ClarkCant
ENGitHub

CLI

Lệnh clarkcant

Hỏi Clark, đọc và tạo cuộc trò chuyện, dừng việc đang chạy hoặc gọi bất kỳ route nào, từ terminal hay từ script.

Chạy từ bản checkout

CLI là workspace package @clarkcant/cli trong apps/cli. Nó chưa được phát hành lên npm, nên hãy chạy từ một bản checkout của ClarkCant:

# The CLI is the workspace package @clarkcant/cli (apps/cli). It is not on npm yet.
git clone https://github.com/digitopvn/clarkcant.git
cd clarkcant
corepack enable && pnpm install

node apps/cli/src/main.ts ask "hello"
pnpm clarkcant ask "hello"

# Optional: a shell alias so the examples below work as written
alias clarkcant="node $PWD/apps/cli/src/main.ts"

Phát triển widget

Lệnh tác giả package clark hỗ trợ toàn bộ vòng đời widget từ một bản checkout. Không cần tài khoản runtime hay provider:

node packages/widget-cli/src/cli.ts widget init ./my-widget --template form
node packages/widget-cli/src/cli.ts widget dev ./my-widget
node packages/widget-cli/src/cli.ts widget test ./my-widget
node packages/widget-cli/src/cli.ts widget pack ./my-widget

Đây là clark widget init/dev/test/pack khi workspace bin có trong PATH. Dev chạy widget trong browser host cô lập, chỉ lắng nghe loopback. Bảng dịch vụ mô phỏng từng capability đã khai báo ở trạng thái loading, ready, blocked hoặc unhealthy; bạn có thể thử offline, degraded và phục hồi sau khi khởi động lại bằng fixture của package. Công cụ không chạy dịch vụ thật hay gọi provider.

Binding tới một capability chạy dưới dạng job của package dùng fixture job trong fixtures/dev-host-services.json thay cho outcome: các bước tiến độ, output khi hoàn tất và lỗi khi thất bại. Khi đó một lần bấm khởi động một job mô phỏng, và danh sách Simulated jobs cho phép đi từng bước bằng Next step, Complete hoặc Fail; lệnh huỷ của chính widget cũng hoạt động. Mọi kết thúc đều ghi “(simulated by clark widget dev)”, không có gì được ghi xuống đĩa, và clark widget test kiểm tra rằng chỉ đúng các capability job mới có fixture job.

Bảng ngữ nghĩa hiển thị đề xuất đã chuẩn hoá mà runtime lưu, phần bị cắt hoặc loại bỏ, delta, ghi chú ngữ cảnh và kết quả inspect_ui. Bảng composition gửi các event đã khai báo qua cùng bộ kiểm tra hợp đồng và ghi lại event do widget phát ra. Event sai hoặc chưa khai báo sẽ bị từ chối; mô phỏng chỉ chạy cục bộ và không thể gọi capability. clark widget test kiểm tra giới hạn semantic của fixture và schema event đã khai báo trước khi pack tạo artifact cùng digest.

Hiện tại --template nhận blank, form, dashboard, pure-ui, ai-generator, ui-with-service, media-tool và connected-app. pure-ui sao chép trình soạn thảo văn bản mẫu, mang id, facet id và tên riêng của package mới, không kèm các kiểm thử của trình soạn thảo, nên bạn bắt đầu từ một ứng dụng chạy được và qua được clark widget test. ai-generator và ui-with-service sao chép trình tạo ảnh mẫu theo cách tương tự: ai-generator giữ provider, với origin giữ chỗ https://images.example.com cần thay, còn ui-with-service có một service tự vẽ ảnh, không khai báo provider và chỉ đọc. media-tool sao chép công cụ dựng media mẫu, gồm một widget và một service, mang id riêng của package mới, không kèm các kiểm thử của công cụ. connected-app sao chép ứng dụng kết nối tài khoản mẫu, mang các id và tên riêng của package mới: một widget, một service có các capability nêu scope chúng cần trên một kết nối tài khoản đã khai báo, các skill, fake connector dùng để kiểm thử nó, và tệp kiểm thử di động dev/service.test.mjs của service. Hãy thay provider, client id, scope và endpoint bằng của provider của bạn trước khi phát hành. Template editor, media và MCP App adapter chưa được triển khai.

node packages/widget-cli/src/cli.ts widget init ./my-editor --template pure-ui

Đóng gói và phát hành widget lên npm

Khi package có package.json, clark widget pack build archive npm của nó bằng pnpm pack vào dist/<name>-<version>.tgz. Sau đó lệnh giải nén archive bằng đúng bộ đọc mà node của bạn dùng khi cài đặt, và từ chối archive nếu nó không tự qua được bộ kiểm tra tuân thủ, không giữ cùng clarkcant.json, hoặc chứa thứ có dạng thông tin xác thực như .npmrc, tệp .env, .git-credentials, khóa riêng, node_modules hay .git. Một danh sách files bỏ sót thứ widget cần sẽ bị phát hiện ở đây, chứ không phải trên máy người khác. clark widget init ghi package.json cho mọi template. Package không có tệp này vẫn là package local hoặc git, và pack không build archive.

Pack từ chối package.json vi phạm các quy tắc sau, và nêu tên từng quy tắc:

package.json được tạo mang tên theo phần cuối của package id, và tên đó có thể đã có người dùng trên npm. Hãy đổi tên, hoặc dùng scope của bạn như @you/my-widget, trước khi phát hành. Pack cần pnpm (corepack enable pnpm). Thêm package.json vào một package đã pack sẽ đổi author digest của nó, nên hãy tăng version khi thêm.

dist/artifact.json ghi ba digest, mỗi digest trả lời một câu hỏi:

clark widget publish chuẩn bị directory entry và không upload gì. Entry nêu đúng version npm và content digest của archive. Lệnh in riêng ba kết quả (prepared: yes; published to npm: no; Marketplace submission: no) và lệnh phát hành đúng archive đã được kiểm tra:

node packages/widget-cli/src/cli.ts widget pack ./my-widget
node packages/widget-cli/src/cli.ts widget publish ./my-widget
npm publish ./my-widget/dist/my-widget-0.1.0.tgz

Hãy phát hành tệp đó thay vì chạy npm publish trong thư mục package, để registry phục vụ đúng các byte mà entry nêu. Sau đó Marketplace liệt kê các package npm mang keyword clarkcant. --source local chuẩn bị entry cho chính thư mục của package, không cần tài khoản npm.

Ứng dụng mẫu: trình soạn thảo văn bản

examples/reference-apps/text-editor là một widget hoàn chỉnh chỉ dựng trên các hợp đồng widget công khai: một facet UI cách ly, không có service, không xin quyền nào và không yêu cầu capability nào. Bạn mở một tệp văn bản, sửa, lưu và nhờ Clark viết lại một đoạn đang chọn, còn widget không bao giờ biết tệp nằm ở đâu.

Trong một bản cài thật, Clark gắn nút viết lại khi đặt trình soạn thảo kèm nút đó, qua tool place_widget của nó; không có binding thì nút vẫn bị tắt và hiện lý do. Trình soạn thảo còn cung cấp cho Clark hành động replaceSelection (hành động Clark nhờ một widget thực hiện), nên một yêu cầu gõ trong ô soạn tin, chẳng hạn “rút ngắn dòng thứ hai”, có thể thay đoạn đang chọn qua chính sách thực thi của bạn. Trình soạn thảo từ chối khi đoạn chọn không còn đúng đoạn Clark đã đọc. Thay đổi là một chỉnh sửa chưa lưu, và việc lưu vẫn do bạn làm. Nói nhãn của hành động khi trình soạn thảo đang được chọn sẽ chạy hành động đó qua cùng đường và cùng chính sách thực thi như khi nhờ Clark trong ô soạn tin, trên một trang tới được frame của trình soạn thảo (digitopvn/clarkcant#444). Khi chính sách của bạn yêu cầu hỏi trước, thẻ duyệt hiện trong cuộc trò chuyện và bạn có thể trả lời bằng cách bấm hoặc nói. Câu nói chỉ quyết định khi mọi từ đều là từ đồng ý, như “yes”, “ok” hay “đồng ý”, hoặc mọi từ đều là từ từ chối, như “no”, “cancel” hay “không”, ngoài các từ đệm như “please” hay “nhé”. Một câu hỏi, một câu lẫn lộn hay bất cứ câu nào khác, như “not ok” hay “chưa được”, sẽ được hỏi lại. Sau đó giọng nói cho biết việc đã diễn ra thế nào, và câu trả lời của widget được đọc như lời của chính widget. Một câu ngụ ý hành động mà không nói nhãn của nó, như “rút ngắn đoạn này”, thì giọng nói chưa khớp được; hãy nhờ Clark thay vào đó.

Kiểm tra ứng dụng mẫu từ một bản checkout:

node packages/widget-cli/src/cli.ts widget test examples/reference-apps/text-editor
node packages/widget-cli/src/cli.ts widget pack examples/reference-apps/text-editor

Ứng dụng mẫu: bảng tính

examples/reference-apps/spreadsheet là widget hoàn chỉnh thứ hai chỉ dựng trên các hợp đồng widget công khai: một facet UI cách ly và không có service. Nó làm việc với một tệp, giữ một bảng lớn trong giới hạn, tự mô tả cho Clark và áp dụng một thay đổi do Clark chọn.

Trong một bản cài thật, tool place_widget của Clark đặt bảng tính và gắn cả hành động format mà bảng tính cung cấp lẫn, khi được yêu cầu, nút định dạng. Bảng tính cung cấp cho Clark hành động format ({ format: percent | number | plain, range? }, xem hành động Clark nhờ một widget thực hiện), nên một yêu cầu gõ trong ô soạn tin, chẳng hạn “định dạng chỗ này thành phần trăm”, sẽ định dạng vùng được nêu, hoặc vùng đang chọn khi không nêu vùng nào, qua chính sách thực thi của bạn. Bảng tính từ chối khi đang bận hoặc chỉ đọc, khi định dạng không xác định, và khi vùng không đọc được hoặc vượt quá giới hạn của bảng. “Hoàn tác định dạng” lùi lại định dạng của Clark như mọi định dạng khác.

Kiểm tra ứng dụng mẫu từ một bản checkout:

node packages/widget-cli/src/cli.ts widget test examples/reference-apps/spreadsheet
node packages/widget-cli/src/cli.ts widget pack examples/reference-apps/spreadsheet

Ứng dụng mẫu: trình tạo ảnh

examples/reference-apps/image-generator là một package có một facet UI cách ly và một facet service. Widget khởi động một việc kéo dài trên service của nó, theo dõi việc đó như một job và nhận lại một ảnh dưới dạng tệp, trong khi service tới provider bằng một khoá mà nó không bao giờ giữ.

Clark đặt trình tạo ảnh kèm nút Tạo ảnh qua tool place_widget, tool này gắn nút với capability image.generate của chính package (digitopvn/clarkcant#445). Một nút chỉ được gắn với capability do chính package chứa widget cung cấp, và chỉ gửi những đầu vào mà capability đó khai báo. Cho tới khi khoá của provider được lưu, nút bị tắt kèm lý do của node. Chưa có provider ảnh thật nào được nối vào; đó là digitopvn/clarkcant#321. Thẻ của ảnh đã đính kèm ghi untitled.png, vì tệp kết quả của job không mang tên.

Kiểm tra ứng dụng mẫu từ một bản checkout, hoặc bắt đầu ứng dụng của riêng bạn từ nó:

node packages/widget-cli/src/cli.ts widget test examples/reference-apps/image-generator
node packages/widget-cli/src/cli.ts widget pack examples/reference-apps/image-generator
node packages/widget-cli/src/cli.ts widget init ./my-generator --template ai-generator

Ứng dụng mẫu: công cụ dựng media

examples/reference-apps/media-render là một package có một facet UI cách ly và một facet service. Nó dựng một đoạn WAV bạn chọn, với thay đổi độ lợi và cắt bớt, dưới dạng một job mà widget theo dõi và bạn có thể dừng. Service đọc đoạn âm thanh từ node của bạn theo từng phần và không bao giờ nhận đường dẫn hay handle tới nó (tệp mà một service đọc).

Chỉ WAV PCM 16-bit, mono hoặc stereo, được dựng; không có codec nào khác. Clark đặt widget kèm nút Dựng qua place_widget, gắn với capability dựng của chính package (digitopvn/clarkcant#445). Các kiểm thử trình duyệt của nó cần một container engine chạy được container Linux.

Kiểm tra ứng dụng mẫu từ một bản checkout, hoặc bắt đầu ứng dụng của riêng bạn từ nó:

node packages/widget-cli/src/cli.ts widget test examples/reference-apps/media-render
node packages/widget-cli/src/cli.ts widget pack examples/reference-apps/media-render
node packages/widget-cli/src/cli.ts widget init ./my-render --template media-tool

Ứng dụng mẫu: ứng dụng kết nối tài khoản

examples/reference-apps/connected-app là một package làm việc trên tài khoản của bạn ở một provider mà không bao giờ giữ tài khoản đó: một widget liệt kê công việc và đổi tên một công việc, một service gọi provider, và các skill hướng dẫn Clark cách dùng. Node của bạn kết nối tài khoản và ký các yêu cầu của service; widget chỉ thấy trạng thái (kết nối một tài khoản).

Chưa có provider thật nào; việc này được theo dõi ở digitopvn/clarkcant#333. Ứng dụng desktop chỉ mở địa chỉ HTTPS trong trình duyệt hệ thống, nên bạn kết nối fake connector chạy trên loopback từ trình duyệt; provider thật dùng HTTPS. Clark đặt widget kèm nút liệt kê và nút đổi tên qua place_widget, gắn với các capability của chính package (digitopvn/clarkcant#445).

Kiểm tra ứng dụng mẫu từ một bản checkout, thử nó với fake connector, hoặc bắt đầu ứng dụng của riêng bạn từ nó:

node packages/widget-cli/src/cli.ts widget test examples/reference-apps/connected-app
node packages/widget-cli/src/cli.ts widget pack examples/reference-apps/connected-app
node --test examples/reference-apps/connected-app/dev/service.test.mjs
node examples/reference-apps/connected-app/dev/fake-connector.mjs
node packages/widget-cli/src/cli.ts widget init ./my-tasks --template connected-app

Tạo một chủ đề

Lệnh tác giả package clark cũng hỗ trợ facet chủ đề chỉ chứa dữ liệu. Chạy từ checkout; không cần tài khoản runtime hay provider:

node packages/widget-cli/src/cli.ts theme init ./my-theme
node packages/widget-cli/src/cli.ts theme dev ./my-theme
node packages/widget-cli/src/cli.ts theme test ./my-theme
node packages/widget-cli/src/cli.ts theme pack ./my-theme

Đây là clark theme init/dev/test/pack khi workspace bin có trong PATH. Init tạo manifest package tổng quát và chủ đề JSON hợp lệ. Dev lắng nghe tại 127.0.0.1:4319 (đổi bằng --port) và nạp lại dữ liệu khi sửa, giữ draft xem trước. Dừng bằng Ctrl-C. Theme Lab dùng component sản phẩm cho ví dụ hội thoại, composer, widget, nút/ô nhập, Cài đặt, modal, phê duyệt, lỗi, trạng thái và Orb; thao tác ví dụ không vận hành runtime. Chuyển sáng/tối, kích thước thường/điện thoại/gọn và giảm chuyển động; xem token và recipe đã biên dịch.

Test kiểm tra tài liệu chủ đề bất kỳ ở cả hai chế độ: tương phản chữ/focus, trạng thái được bảo vệ và đường viền, typography có giới hạn, giảm chuyển động, asset là tệp thường trong gói, manifest và không thực thi mã. Chủ đề không nhận CSS, HTML, script, tài nguyên bên ngoài hay URL font. Symlink trong gói bị từ chối. Kiểm tra bố cục browser và bàn phím vẫn ghi rõ requires-dev-host; kiểm tra token không chứng nhận hành trình browser. Pack dùng định dạng artifact bất biến hiện có, chứa digest tài liệu chủ đề, ghi các kiểm tra chưa thực hiện và từ chối thay đổi nội dung cùng phiên bản. Tăng phiên bản trước khi pack bản sửa.

Kết nối

CờBiến môi trườngMặc định
--urlCLARKCANT_URLhttp://127.0.0.1:8765
--tokenCLARKCANT_TOKENĐọc từ identity.json trong thư mục dữ liệu, chỉ khi node ở trên máy này (localhost, 127.x, ::1); --url trỏ tới máy khác cần --token, nên token cục bộ không bao giờ rời khỏi máy
--data-dirCLARKCANT_DATA_DIR~/.clarkcant
--json–In JSON thô

Trên chính máy chạy node, với thư mục dữ liệu mặc định, không cần cờ nào. Với node ở nơi khác, đặt URL và token:

export CLARKCANT_URL="https://clark.example.com"
export CLARKCANT_TOKEN="<token>"
clarkcant status

Các lệnh

LệnhChức năng
clarkcant ask "<text>" [-c <conversationId>]Stream câu trả lời của Clark ra stdout. Không có -c thì tạo cuộc trò chuyện mới và in id của nó ra stderr. Khi tin nhắn được nhập (steer) vào câu trả lời Clark đang viết (resolution: "steered"), lệnh báo điều đó ra stderr và thoát với mã 0; hãy đọc cuộc trò chuyện để xem câu trả lời.
clarkcant statusTình trạng node.
clarkcant conversationsLiệt kê cuộc trò chuyện.
clarkcant new [title]Tạo cuộc trò chuyện.
clarkcant read <conversationId>In cuộc trò chuyện.
clarkcant stopDừng khẩn cấp.
clarkcant api <METHOD> <path> [jsonBody]Gọi thô tới bất kỳ route REST nào, trừ các quyết định của con người (phê duyệt hành động cần kiểm soát, quyết định năng lực của package, xác nhận ý định với ứng dụng, báo cáo ứng dụng đã làm gì với một hành động agent yêu cầu, tin cậy một peer đã ghép cặp hoặc cấp quyền, cài bản cập nhật mà một thông báo nêu) hoặc việc xuất CSV của một bảng, trả về 403 PERSON_ONLY.
clarkcant mcpMCP server qua stdio, nối tới /mcp của node (xem MCP).
clarkcant discoverIn /.well-known/clarkcant.json.
clarkcant instructions check [file|folder]Kiểm tra một tệp hướng dẫn dự án theo contract dùng chung. Đây là lệnh duy nhất chạy ngoại tuyến, không cần node.

Ví dụ

clarkcant status
clarkcant discover

clarkcant ask "how do I connect Cursor to you?"      # new conversation; its id is printed on stderr
clarkcant ask "and Claude Desktop?" -c <conversationId>

clarkcant conversations
clarkcant new "Release notes"
clarkcant read <conversationId>

clarkcant api GET /node
clarkcant api POST /conversations '{ "title": "From the CLI" }'

clarkcant stop

Vì câu trả lời ra stdout còn id cuộc trò chuyện mới ra stderr, ask kết hợp được với pipe và file như mọi lệnh khác.