REST & SSE

HTTP API

HTTP và JSON thuần, mô tả bằng OpenAPI 3.1. Câu trả lời có thể chờ trọn vẹn hoặc stream bằng Server-Sent Events.

Kết nối

export CLARKCANT_URL="http://127.0.0.1:8765"
export CLARKCANT_TOKEN="<token>"   # localToken from <data-dir>/identity.json

Route công khai (không cần token)

RouteTrả về
GET /healthTình trạng sống, nền tảng runtime, giao thức đã thương lượng. Không kèm danh tính node.
GET /.well-known/clarkcant.jsonTài liệu khám phá, liệt kê mọi giao diện (api, mcp, websocket, cli) và endpoint của chúng.
GET /openapi.jsonMô tả OpenAPI 3.1 của phần REST ổn định.
GET /connections/callback/{packageId}Nơi provider đưa trình duyệt của bạn quay về sau khi bạn kết nối tài khoản của một gói. state dùng một lần do node của bạn cấp xác thực route này. Trả về một trang ngắn không bao giờ lặp lại mã hay state.

Các route (bề mặt v1 ổn định)

MethodPathBodyGhi chú
GET/node–Id node, nhãn, fingerprint, model đã cấu hình (model là null khi chưa đặt) và clarkVersion, phiên bản Clark node đang chạy ("unknown" khi bản build không đọc được hồ sơ của chính nó; xem bên dưới).
GET/changelog?since=–Phiên bản Clark này đã thay đổi những gì. Xem bên dưới.
GET/conversations–Danh sách cuộc trò chuyện.
POST/conversations{ title? }201 { conversationId, homeNodeId }
POST/conversations/{id}/messages{ text, attachmentIds?, references? }Chờ câu trả lời; trả về { resolution, taskId, messageIds, timeline }, hoặc 202 khi việc tiếp tục chạy nền (đọc timeline sau).
POST/conversations/{id}/messages/stream{ text, attachmentIds?, references? }Stream câu trả lời bằng Server-Sent Events (xem bên dưới).
POST/conversations/{id}/stop{ source? }Chỉ dừng câu trả lời mà cuộc trò chuyện này đang viết. Phần đã viết được giữ lại, gắn nhãn đã dừng. Trả về { stopped }, là false khi không có câu trả lời nào đang chạy. Mỗi lần dừng được ghi audit kèm nguồn (chat, voice, hoặc api khi bỏ trống).
GET/conversations/{id}/timeline?after=N · ?before=N · ?window=latest, mỗi cách kèm &limit=–Một trang tin nhắn (các block: text/markdown, hoạt động của tool, suy luận, widget…), mục đã ghim, các instance widget. Xem đọc một hội thoại dài.
POST/conversations/{id}/questions/{questionId}/answer{ text?, optionIds?, confirmed? }Trả lời một ask_user_question; bắt đầu một lượt mới.
POST/conversations/{id}/questions/{questionId}/cancel–Huỷ câu hỏi.
POST/conversations/{id}/widgets/{instanceId}/export{ sort?, query?, filters?, columns? }Tải một widget bảng xuống thành file CSV (text/csv, tên file nằm trong Content-Disposition). Các dòng lấy từ chính dataset của bảng: cách sắp xếp, từ khoá tìm và bộ lọc bạn gửi chọn dòng dựa trên mọi cột mà bảng hiển thị, giống hệt trên màn hình, còn columns chỉ quyết định file chứa những cột nào trong số đó. Request không thể mang dòng dữ liệu. Ô nào mà bảng tính sẽ chạy như công thức đều được thêm tiền tố '. Chỉ chủ của bảng mới xuất được, và relay WebSocket, MCP cùng clarkcant api từ chối nó với 403 PERSON_ONLY.
POST/conversations/{id}/widgets/{instanceId}/actions{ actionBindingId, expectedRevision, expectedBindingDigest, input, invocationId, variant?, sequence? }Bấm một hành động đã gắn trên widget, giống hệt khi bấm chuột hay nói yêu cầu. 200 là outcome: "done"; 202 là "approval-required" hoặc "background". Khi bị từ chối, body mang code và message (tiếng Anh, dành cho log và agent), và khi liên quan có thêm outcome (uncertain, partial, refused), mayHaveRun, recorded, readOnly, taskId, retryAfterMs, limit và báo cáo workflow cho từng bước. Widget không nằm trong cuộc trò chuyện được nêu thì nhận 404 INSTANCE_UNKNOWN; vượt giới hạn mỗi phút của binding thì nhận 429 RATE_LIMITED. Cuộc gọi có thể thay đổi dữ liệu được ghi vào sổ effect trước khi gửi; nếu không ghi được, lần bấm nhận 503 LEDGER_UNAVAILABLE và không có gì được gửi. Cuộc gọi đã gửi mà không nhận được câu trả lời đáng tin (504 SERVICE_TIMED_OUT, 409 SERVICE_CANCELLED, 504 SERVICE_UNREACHABLE, 502 SERVICE_TOOL_FAILED) trả về outcome: "uncertain" với mayHaveRun: true, trở thành effect chưa rõ, và hộp thư chỉ hỏi về nó, kèm taskId, khi recorded là true. Một lần read chưa xong thì không thay đổi gì và mang readOnly: true. Cùng một invocationId không bao giờ được gửi hai lần: lần lặp lại nhận câu trả lời đã lưu, kể cả sau khi khởi động lại, và lần bấm bị việc khởi động lại cắt ngang thì nhận ACTION_INTERRUPTED. contextRefs của hành động agent do node đọc và chỉ đến model như dữ liệu, không bao giờ như chỉ dẫn; yêu cầu không mang chữ nào của riêng nó. variant: "view-state" là lần ghi chỉ trạng thái cho trạng thái phát của một trình phát do host giữ (canvas.video@1, canvas.audio@1) và cần một sequence, số nguyên dương tăng dần theo mỗi lần ghi; giá trị vượt đồng hồ của node hơn một ngày nhận 400 INVALID_INPUT. Nó qua cùng các bước kiểm tra chủ sở hữu, binding, revision, digest và input, rồi trả về 200 { variant, duplicate, instanceId, revision, stateRevision, state } mà không có timeline và không làm revision của instance tăng lên. Lần ghi có sequence không mới hơn lần cuối được nhận thì không ghi gì và, trước các bước kiểm tra revision và digest, được trả về duplicate: true cùng trạng thái node đang giữ; lần thử lại với đúng invocationId của lần ghi mới nhất được trả về đúng như vậy, còn mọi lần ghi khác thuộc loại này mang thêm stale: true. invocationId bắt đầu bằng view-state: được dành riêng cho bản ghi của chính node và nhận 400 INVALID_SCHEMA, giống như sequence không kèm variant, variant không kèm sequence, hay bất kỳ giá trị variant nào khác; variant trên một binding khác thì nhận 400 UNSUPPORTED_ACTION. Một lần bấm gọi tới capability của service cũng có thể mang structuredContent (kết quả có cấu trúc).
GET/composer/suggestions?trigger=/|@&q=&conversationId=–Những gì nên gợi ý sau / (lệnh gạch chéo, rồi đến kỹ năng) hoặc @ (dự án, tệp, thư mục, dịch vụ, cuộc trò chuyện, việc nền). Tối đa 8 dòng; khi chưa gõ gì, mỗi loại có phần dòng của mình, và phần một loại không dùng hết thì nhường cho các loại khác. Mỗi dòng mang ref để gửi đi, hoặc disabledReason. Dòng lệnh mang command và không có ref: lệnh được viết vào tin nhắn, không đính kèm theo nó. Xem bên dưới.
GET/POST/providers/…–Đăng nhập và đăng xuất AI provider. Xem bên dưới.
POST/stop–Dừng khẩn cấp: huỷ các lệnh đang chạy, ngắt lượt trả lời, dừng việc chạy nền.

Đọc câu trả lời của node

Ứng dụng desktop và một node trên máy khác được cập nhật riêng. Vì vậy ứng dụng đọc khoan dung một câu trả lời mà cấp trên cùng không ràng buộc điều gì: một trường ở cấp trên cùng mới hơn ứng dụng bị bỏ qua và không bao giờ được chuyển tiếp, và ở những chỗ cần thiết ứng dụng nói rằng node mới hơn và một số điều node gửi không được hiển thị. Các trường ứng dụng biết vẫn giữ giới hạn của chúng, và các đối tượng nằm trong chúng vẫn được đọc chặt. Cách đọc này áp dụng cho hộp thư và từng thông báo, các con số của hộp thư, kết quả của một hành động trên thông báo và của một lần đối chiếu, danh sách bộ nhớ và từng mục, các gợi ý, bộ chọn của ô soạn tin, các job và tệp đính kèm của một widget, và view của một phiên phát triển widget.

Câu trả lời mang một phê duyệt, một quyết định hay điều Clark còn truy cập được thì vẫn chặt: xoá một hội thoại, quyết định của một ý định ứng dụng và câu trả lời khi bỏ chọn một thư mục. Kết quả của một hành động trên thông báo được đọc khoan dung dù có thể nêu một phê duyệt (approvalId, cùng số capability đang chờ hay bị từ chối): không có gì được phê duyệt từ kết quả này, vì nó chỉ trỏ tới một mục đang chờ, và bạn quyết định trên mục đó, mục mà hộp thư đọc chặt. Trong hộp thư, từng mục đang chờ, cùng các hành động và phạm vi truy cập của một thông báo, cũng vẫn chặt; mục nào không đọc được thì bị bỏ ra và được đếm. Một giá trị ứng dụng không biết trong một trường nó biết, chẳng hạn một trạng thái hay kết quả mới, làm câu trả lời bị từ chối; không trường enum đã biết nào chuyển sang giá trị "không rõ". Các yêu cầu ứng dụng gửi vẫn chặt.

GET /node trả về clarkVersion. Khi không đọc được một câu trả lời, ứng dụng so phiên bản đó với phiên bản của chính nó; một lần hỏi thất bại không được giữ lại, và một phiên bản dài hơn 64 ký tự được coi là không rõ. Nếu node chạy Clark mới hơn, ứng dụng nêu cả hai phiên bản và đề nghị bạn cập nhật ứng dụng. Nếu không, ứng dụng nói rằng nó không bị cũ và đề nghị thử lại. Nếu không biết một trong hai phiên bản, ứng dụng nói rằng có lẽ node mới hơn. Lời báo cũng nói điều gì được giữ nguyên: một lần đọc không thay đổi gì; với một hành động trên thông báo, node đã trả lời nhưng ứng dụng không đọc được node đã làm gì (với một bản cập nhật, hãy xem hộp thư để biết bản cập nhật đã được cài hay đang chờ bạn phê duyệt); một lần đối chiếu đã được ghi nhận; bỏ chọn một thư mục chỉ nói rằng node đã trả lời, không nói thư mục đã được bỏ chọn hay Clark còn truy cập được ở đâu; một lần bắt đầu /develop đã bắt đầu phiên; hoặc với Tạo issue, node đã trả lời nhưng ứng dụng không đọc được báo cáo đã được gửi lên hay chưa, nên thẻ không nói là thất bại mà đề nghị Kiểm tra lại.

Nếu bạn xây dựng dựa trên các câu trả lời này, đừng bao giờ thêm một phê duyệt, một quyền được cấp, một phạm vi truy cập hay một lần kích hoạt thành một trường mới ở cấp trên cùng: một ứng dụng cũ hơn sẽ bỏ qua nó. Hãy đặt nó trong một đối tượng đọc chặt. Bảng đầy đủ nằm trong docs/open-interfaces.vi.md của kho mã.

Phiên bản này có gì mới

GET /changelog trả về cùng nội dung với /changelog và Cài đặt: { installed, since?, notesCover?, releases, source }. Nó đọc ghi chú phát hành nhúng trong bản build nên dùng được khi không có mạng, và chỉ để đọc: không có trạng thái cập nhật hay lựa chọn kênh. installed mang phiên bản và kênh (stable, beta, hoặc source với bản checkout), còn releases liệt kê các bản ghi phát hành, mới nhất trước. since chỉ giữ các bản phát hành sau một phiên bản như 1.4. Bản chạy từ mã nguồn có thêm notesCover, commit và ngày mà ghi chú của nó đạt tới; thay đổi sau commit đó không được liệt kê.

curl -s "$CLARKCANT_URL/changelog?since=1.4" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"

Tạo cuộc trò chuyện

curl -s -X POST "$CLARKCANT_URL/conversations" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "From my app" }'
# 201 → { "conversationId": "…", "homeNodeId": "…" }

Gửi tin nhắn và chờ trả lời

curl -s -X POST "$CLARKCANT_URL/conversations/<conversationId>/messages" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Summarise the notes in my Documents folder" }'
# → { "resolution": …, "taskId": "…", "messageIds": […], "timeline": … }

Một câu gõ như “open settings” được host hiểu là ý định với ứng dụng (appIntent trong response) thay vì gửi tới model.

Gõ /settings mở cùng hộp thoại Cài đặt mà nút bánh răng trên thanh đầu trang mở, và /settings <tab> mở nó ở tab đó. Gọi tab bằng id của nó (experience, ai, control, extensions, devices, memory, developer), bằng nhãn của nó đúng như Cài đặt hiển thị bằng tiếng Anh hoặc tiếng Việt, cả nhãn hay từng phần hai bên dấu “&” (Bộ nhớ, giọng nói, AI & Routing, routing), hoặc bằng những từ khác mà câu “mở cài đặt” chấp nhận, như model hay tab ai. Response mang quyết định settings.open hoặc settings.tab của chính host trong appIntent (trong frame done trên /messages/stream), được đưa ra và ghi thành cùng sự kiện kiểm toán app.intent như câu gõ “mở cài đặt”. Gửi trong lúc câu trả lời còn đang được viết, POST /app-intents với cùng text trả lời /settings, /settings <tab> và /new ngay. /new không dừng câu trả lời đó: nó tiếp tục được viết trong cuộc trò chuyện vừa rời đi, mở lại được bằng /sessions, và readBack của quyết định nói rõ điều này. Mọi lệnh gạch chéo khác được trả lời none ở đó, vì nó phải chờ câu trả lời xong. Ứng dụng mở đúng hộp thoại đó, không bao giờ mở hộp thoại thứ hai chồng lên hộp thoại khác, giữ nguyên cuộc trò chuyện và các tệp trong ô soạn thảo, và trả focus về ô soạn thảo khi bạn đóng nó. Một tab không tồn tại thì không mở gì cả, và câu trả lời liệt kê các tab theo nhãn trong ngôn ngữ của bạn. Không model nào được hỏi.

Khi bạn gửi một tin nhắn kèm tệp, Clark đọc các tệp đó cùng tin nhắn của bạn. Nếu Clark vẫn đang trả lời, tin nhắn của bạn sẽ được trả lời thành một lượt riêng sau khi câu trả lời hiện tại xong. Các lệnh như /new, 'mở cài đặt' hay 'dừng lại' vẫn hoạt động khi đang có tệp đính kèm, nhưng các tệp đó không được gửi kèm lệnh. Chúng được giữ lại trong ô soạn thảo cho tin nhắn tiếp theo, kèm một ghi chú ngắn rằng lệnh không mang theo tệp. Một lệnh mà Clark chưa thể làm lúc này cũng vậy, như xoá cuộc trò chuyện khi Clark đang trả lời: bạn nhận được lý do, câu trả lời đang viết vẫn tiếp tục, và các tệp của bạn vẫn nằm trong ô soạn thảo. Khi bắt đầu một cuộc trò chuyện mới, bằng /new hay nút bắt đầu lại, các tệp đó được bỏ lại, nên không bao giờ theo bạn sang cuộc trò chuyện khác. Ngoại lệ duy nhất là /background kèm một yêu cầu: khi có tệp đính kèm, nó được trả lời như một tin nhắn bình thường để tệp được đọc. Riêng /background không kèm yêu cầu sẽ hiện hướng dẫn cách dùng. Một yêu cầu nghe giống lệnh nhưng không phải lệnh, như 'chuyển sang tiếng Anh' kèm một tài liệu, cũng được trả lời như một tin nhắn bình thường. Tệp không còn dùng được sẽ bị từ chối ngay, và câu trả lời đang viết không bị ngắt.

Trên cả /messages và /messages/stream, attachmentIds được kiểm tra trước khi bất cứ thứ gì khác xử lý tin nhắn. Tệp không còn dùng được, hoặc attachmentIds không phải là một danh sách id, bị từ chối với 400 ATTACHMENT_NOT_AVAILABLE trên mọi nhánh (lệnh gạch chéo, lệnh ứng dụng gõ bằng chữ, hoặc trên /messages là tin nhắn gửi khi có lượt đang trả lời), và lượt đang chạy được giữ nguyên. Một lệnh của host, dù là lệnh gạch chéo (/new, /thinking) hay lệnh gõ bằng chữ (như “mở cài đặt” hay “dừng lại”), là về ứng dụng, không phải về tệp, nên host vẫn trả lời nó kể cả khi tin nhắn có tệp đính kèm, và các tệp đó không được gắn vào tin nhắn nào. Điều này gồm cả một lệnh mà host nhận ra rồi từ chối, như xoá cuộc trò chuyện khi đang có câu trả lời chạy: lời từ chối là câu trả lời, và lượt đang chạy được giữ nguyên. Ngoại lệ duy nhất là /background có yêu cầu và có tệp đính kèm: yêu cầu của nó có thể nói về các tệp đó và lần chạy nền chỉ mang lời, nên tin nhắn được lưu cùng các tệp của nó và được trả lời thành một lượt, với nội dung đúng như đã gõ. Một /background không kèm yêu cầu luôn nhận hướng dẫn cách dùng. Một câu trông giống lệnh nhưng không khớp lệnh nào được trả lời là “không hiểu” khi không có tệp đính kèm; khi có tệp đính kèm, nó được lưu cùng các tệp đó và được trả lời thành một lượt. Client phân biệt hai trường hợp qua frame done của luồng: resolution: "app-intent" nghĩa là host đã trả lời một lệnh và không tệp nào được gắn; mọi giá trị khác nghĩa là tin nhắn đã được lưu cùng các tệp.

Trong ô soạn tin, tệp đã chọn vẫn nằm cùng draft khi đang kiểm tra tải lên. Nút Gửi bị vô hiệu trong lúc đó; nhấn Enter không gửi hay xoá nội dung và tệp. Khi tải lên xong, hãy gửi tin nhắn như bình thường. Tệp tải lỗi vẫn giữ lý do đã nêu và không được gửi cùng tin nhắn.

Ô soạn tin đánh dấu Markdown cơ bản ngay khi bạn gõ: chữ đậm, chữ nghiêng, gạch ngang, code trong dòng, liên kết, tiêu đề, trích dẫn, danh sách và khối code có rào. Ô nhập vẫn là văn bản thuần, nên gõ, chọn, hoàn tác, kiểm tra chính tả và bộ gõ vẫn hoạt động như trước. Các ký tự Markdown vẫn hiện, và tin nhắn được gửi đúng như bạn đã gõ.

Dòng dưới ô soạn tin bắt đầu bằng model mà tin nhắn tiếp theo sẽ chạy và mức thinking của nó (thinking: tự động khi node không đặt mức nào, tức là model dùng mức mặc định của nó), sau đó là độ đầy của ngữ cảnh, tỉ lệ cache, tốc độ viết và chi phí của lượt gần nhất. Model được đọc từ GET /node, nơi model phản ánh model đã chọn trong Cài đặt kể từ khi node khởi động, và dòng này cập nhật ngay khi bạn chọn model khác. Mỗi lượt trả lời dừng sau 5 phút theo mặc định (CC_MODEL_MAX_WALL_CLOCK_MS); việc dài hơn nên chạy nền.

Việc phê duyệt do con người quyết định trên giao diện của chính họ. Route đó nằm ngoài mô tả ổn định và cố ý không có tool MCP.

Tin nhắn gửi khi Clark đang trả lời

Một tin nhắn ngắn bạn gõ khi Clark vẫn đang trả lời sẽ được nhập (steer) vào câu trả lời đó. Tin nhắn có tệp, tham chiếu hoặc phê duyệt, tin nhắn nói, hoặc tin nhắn từ script hay ứng dụng khác sẽ chờ và được trả lời riêng. Stop cũng huỷ các tin nhắn còn đang chờ.

Trên route /messages thường, một tin nhắn tới khi có lượt đang trả lời được quyết định ngay tại đó: nhập (steer) vào lượt đang chạy, ngắt lượt đó, hoặc chạy nền. Một tin nhắn có nguồn gốc khác với lượt đang chạy, một tin nhắn gõ trong lúc đang có lượt nói bằng giọng, hoặc một tin nhắn có tệp đính kèm, không bao giờ được nhập (steer) vào lượt đó, và tin nhắn có tệp đính kèm không bao giờ chạy nền. Khi steer được chọn cho một tin nhắn như vậy, hoặc chạy nền được chọn cho một tin nhắn có tệp đính kèm, nó cũng không ngắt lượt đang chạy: nó chờ và được trả lời thành một lượt riêng với nguồn gốc và tệp của chính nó. Lượt đang chạy chỉ bị ngắt khi bộ quyết định chọn ngắt, khi tin nhắn mới có tham chiếu, hoặc khi chạy nền mà không có worker nào nhận.

Mọi cách khác để bắt đầu một lượt (route stream, phần tiếp theo sau một phê duyệt, một câu hỏi đã được trả lời, giọng nói) không bao giờ gửi prompt thứ hai cho lượt đang chạy. Chữ thuần cùng nguồn gốc và cùng kênh, không có tệp đính kèm, tham chiếu, chỉ dẫn hay dữ liệu, được nhập (steer) vào lượt trong lúc câu trả lời của lượt đó đang được viết. Câu trả lời đó trả lời luôn tin nhắn này, và response cùng sự kiện done của stream báo resolution: "steered" không kèm id tin nhắn. Chữ gõ không bao giờ nhập vào một lượt nói, và tin nhắn có tệp đính kèm chờ tới lượt riêng của nó. Mọi tin nhắn khác chờ lượt đang chạy kết thúc rồi thành một lượt riêng, đọc tệp đính kèm và tham chiếu của chính nó; request (hoặc stream) của nó vẫn mở cho tới khi lượt đó trả lời xong.

Một lượt chỉ đang được chuẩn bị (session của nó còn đang được tạo, hoặc việc đổi model còn đang chờ) thì chưa trả lời: tin nhắn mới không bao giờ dừng nó và được trả lời sau nó. Stop, nút dừng khẩn cấp hoặc việc node tắt sẽ huỷ mọi tin nhắn còn đang chờ, nên không tin nhắn nào trong số đó bắt đầu; thẻ trả lời của nó cho biết nó đã được dừng trước khi bắt đầu, và tin nhắn vẫn được lưu.

Chỉ tới một kỹ năng, một dự án hay một tệp

Ngoài phần chữ, một tin nhắn có thể mang tối đa 8 tham chiếu có kiểu: một kỹ năng, một dự án, một tệp hay thư mục trong dự án đã được lập chỉ mục, một dịch vụ MCP, một cuộc trò chuyện khác hoặc một việc nền. Hãy lấy chúng từ GET /composer/suggestions thay vì tự dựng, rồi gửi ref của từng dòng bạn chọn. Hộp thư của ứng dụng cũng gửi theo cách đó một loại nữa, là thông báo, khi bạn dùng Hỏi Clark hoặc Thêm vào ngữ cảnh trên nó.

Tin nhắn bắt đầu bằng một lệnh gạch chéo, như /new, được trả lời như lệnh đó. Vì vậy hãy viết kỹ năng trong phần chữ thành /<tên>, hoặc thành /skill:<tên> khi tên của nó trùng với một lệnh: kỹ năng tên new được gửi thành /skill:new và được gọi, còn /new thì mở một cuộc trò chuyện mới. Gõ skill: sau dấu gạch chéo (trigger=/&q=skill:ne) thì chỉ liệt kê kỹ năng.

curl -s "$CLARKCANT_URL/composer/suggestions?trigger=@&q=myapp/src/" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"
# → { "trigger": "@", "query": "myapp/src/", "suggestions": [ { "kind": "file", "label": "myapp/src/app.ts", "ref": { … } } ] }

curl -s -X POST "$CLARKCANT_URL/conversations/<conversationId>/messages" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Xem giúp @myapp/src/app.ts", "references": { "version": 1, "items": [ <ref đó> ] } }'

Tham chiếu là con trỏ, không phải quyền. Node kiểm lại từng tham chiếu khi tin nhắn tới: kỹ năng đã bị sửa hay gỡ, tệp không còn, dự án nằm ngoài các thư mục được phép, cuộc trò chuyện không còn tồn tại, hay thông báo không còn trong hộp thư đều khiến cả tin nhắn bị từ chối với 400 REFERENCE_NOT_AVAILABLE, có nêu tên tham chiếu, và không có gì được lưu. Tham chiếu được chấp nhận sẽ được lưu trên tin nhắn thành block reference, và lượt trả lời được báo về nó bằng đường dẫn tương đối với thư mục được phép, không bao giờ bằng đường dẫn tuyệt đối; nội dung của một thông báo được trích lại dưới dạng dữ liệu, không bao giờ như chỉ dẫn. Muốn đọc, chạy hay thay đổi thứ nó chỉ tới thì vẫn đi qua công cụ và chính sách như thường lệ.

Đăng nhập AI provider

Các route phía sau /login và /logout. Mọi route trừ danh sách đều chỉ dành cho người dùng: MCP client, widget hay node đã ghép cặp đều bị từ chối, vì đăng nhập là quyết định của người dùng.

Node không có runtime model trả 503 PROVIDER_AUTH_UNAVAILABLE. Lần đăng nhập đã kết thúc bị quên sau 10 phút.

Stream câu trả lời (SSE)

curl -N -X POST "$CLARKCANT_URL/conversations/<conversationId>/messages/stream" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "text": "What changed in my project today?" }'
Sự kiệnÝ nghĩa
deltaThêm một đoạn trả lời: { text }.
reasoningPhần suy luận của model, tách khỏi những gì nó nói với người dùng.
tool-start, tool-endMột lần gọi tool bắt đầu hoặc kết thúc.
host-controlAgent yêu cầu ứng dụng thay đổi một thứ gì đó: mở Settings ở một tab, đổi model, mở hoặc kết thúc chế độ giọng nói, quay lại cuộc trò chuyện. Xem bên dưới.
errorLượt trả lời gặp lỗi.
doneSự kiện cuối: { resolution, taskId, messageIds, timeline }.

Từ JavaScript:

// EventSource cannot POST or send headers, so read the stream with fetch.
const res = await fetch(`${url}/conversations/${conversationId}/messages/stream`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
  body: JSON.stringify({ text: "hello" }),
});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log(value); // raw Server-Sent Events: delta, tool-start, …, done
}

Khi agent thay đổi ứng dụng

Sự kiện host-control do agent yêu cầu mang một controlId. Ứng dụng thực hiện hành động, rồi trả lời bằng POST /app-intents/host-control/<controlId> { "ran": true|false, "say": "…" }. Agent nhận đúng câu trả lời đó, nên Clark chỉ nói ứng dụng đã thay đổi khi ứng dụng báo là đã làm, và chuyển lại lý do của ứng dụng khi không làm được. Nếu không có câu trả lời trong vài giây, agent được báo là hành động chưa được xác nhận. Mỗi controlId chỉ được trả lời một lần, và route chờ câu trả lời (/messages) không bao giờ chờ nó. Việc trả lời thuộc bề mặt của con người: relay WebSocket, MCP và clarkcant api từ chối nó với 403 PERSON_ONLY.

Trong bản ghi audit, một hành động agent yêu cầu khi đang trả lời điều bạn nói được đánh dấu voice-agent, tách biệt với lệnh do chính bạn nói (voice).

Đọc một cuộc trò chuyện

curl -s "$CLARKCANT_URL/conversations/<conversationId>/timeline?after=0" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"

Timeline trả về mọi bước đúng như đã lưu. Khi ứng dụng hiển thị một câu trả lời, từ ba bước làm việc liên tiếp trở lên (lệnh gọi tool, suy luận và các bước kiểm tra đi kèm) được gộp thành một dòng, “Đã làm N bước”, bấm vào để mở ra mọi bước theo đúng thứ tự. Nếu có bước lỗi, dòng đó thêm “· N bước lỗi” màu đỏ, và bên trong, bước lỗi mở sẵn ở lý do của nó. Khi câu trả lời còn đang được viết, bước mới nhất của nó nằm ngoài phần gộp.

Sau khi bạn duyệt một lệnh trên thẻ, Clark bắt đầu một lượt mới để đọc kết quả của lệnh và làm tiếp. Không ai gõ tin nhắn người dùng mà lượt đó trả lời, nên tin nhắn ấy mang hostWritten: { "kind": "host-continuation", "version": 1 }. Hãy hiển thị tin nhắn như vậy thành một dòng của ClarkCant ("Đã duyệt — Clark tiếp tục"), không phải lời người dùng đã viết, và làm y như vậy với mọi kind hoặc version bạn không nhận ra. Nội dung của nó là thứ model đã đọc. Nó không xuất hiện trong kết quả tìm kiếm, và clarkcant read in nó thành (approved, Clark carries on).

Mỗi lượt của model kết thúc bằng một khối system-card có subject là "connection": ghi chú model, cho biết model nào đã trả lời. Các fields của nó là những dòng để đọc, được viết bằng ngôn ngữ của chủ node ngay lúc viết. Cùng các thông tin đó cũng nằm trên khối dưới dạng dữ liệu, nên client không bao giờ phải đọc nhãn của một dòng: modelNote: { "version": 1, "elapsedMs": <số nguyên ≥ 0>, "fallback"?: { "from": "<provider/model>" } }. elapsedMs là thời gian model đã dùng, đúng con số mà dòng thời lượng hiển thị. fallback chỉ có khi một model dự phòng trả lời thay cho model người dùng đã chọn, và from ghi tên model đã chọn. Thẻ được viết trước khi có trường này thì không có modelNote. Client gặp một thẻ không có trường này, có version mà nó không biết, hoặc có ghi chú mà nó không đọc được, sẽ quay về đọc các dòng.

Đọc một hội thoại dài

Route timeline trả về một trang tin nhắn của hội thoại, cũ nhất trước, chọn theo số thứ tự tin nhắn (sequence): thứ tự mà node của bạn lưu các tin nhắn của một hội thoại.

QueryTrang
không có, hoặc after=NCác tin nhắn ngay sau sequence N. Không có tham số là after=0, trang mà route này luôn trả về, nên các client hiện có không bị ảnh hưởng.
before=NCác tin nhắn ngay trước sequence N, để cuộn ngược lại.
window=latestCác tin nhắn mới nhất, là thứ hiện ra khi mở lại một hội thoại.

Chỉ dùng tối đa một trong ba. limit đặt cỡ trang: 1 tới 500, mặc định 200. Mọi giá trị khác là 400 INVALID_SCHEMA. Mọi timeline, từ route này hay đi kèm trong một phản hồi khác, đều có window:

{ "version": 1, "fromSequence": 1901, "toSequence": 2100, "hasOlder": true, "hasNewer": false, "sequences": [1901, 1902, "..."] }

Trang chứa mọi tin nhắn đã lưu có fromSequence <= sequence <= toSequence, và không có tin nào khác. sequences cho sequence của từng tin nhắn theo thứ tự trong messages. hasOlder nghĩa là before=<fromSequence> đọc được trang tiếp giáp với trang này, và hasNewer nghĩa là after=<toSequence> cũng vậy. Hai trang có khoảng chạm nhau hoặc chồng lên nhau gộp thành một khoảng, không tin nào lặp lại và không có chỗ hở; trong khoảng của chính nó, trang mới hơn là đúng, nên tin nhắn đã bị xoá sẽ biến mất. Các trang không chạm nhau thì không ghép được, và các con số cho bạn biết điều đó.

curl -s "$CLARKCANT_URL/conversations/<conversationId>/timeline?window=latest&limit=200" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"

# Then, for the page before it
curl -s "$CLARKCANT_URL/conversations/<conversationId>/timeline?before=<fromSequence>" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"

Hai con số khác nhau. cursor sự kiện mà timeline cũng mang cho biết người đọc đã thấy những sự kiện nào, không phải đang giữ những tin nhắn nào. Nó không bao giờ là con trỏ trang: chỉ phân trang bằng sequence của tin nhắn.

Mọi phản hồi mang theo hội thoại đều trả về trang mới nhất của nó: gửi tin nhắn, sự kiện SSE done, hành động widget, ghim, câu hỏi và thẻ đã trả lời, và phê duyệt. Phản hồi của hành động widget còn mang instance mà nó tác động, và mọi timeline đều mang các instance của những mục đã ghim trong hội thoại, dù tin nhắn của chúng ở đâu. Người đọc đang giữ lịch sử cũ hơn gộp trang đó vào những gì mình đang giữ thay vì bắt đầu lại.

Trả lời câu hỏi của Clark

Khi cần bạn quyết định điều gì, Clark hỏi bằng ask_user_question rồi kết thúc lượt. Câu trả lời của bạn mở một lượt mới. Gửi text, optionIds hoặc confirmed tuỳ theo câu hỏi, hoặc huỷ bằng …/cancel.

curl -s -X POST "$CLARKCANT_URL/conversations/<conversationId>/questions/<questionId>/answer" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "optionIds": ["<optionId>"] }'

Yêu cầu duyệt do task đang chạy tạo ra

GET /inbox có các yêu cầu duyệt đang chờ do task đang chạy tạo ra. Quyết định bằng POST /tasks/{taskId}/approvals/{approvalId}/decide với { "decision": "granted" | "denied", "digest": "<operationDigest shown in the inbox>" }, dùng đúng digest đã hiện trong hộp thư. Duyệt cho phép task chạy lại; redispatched cho biết node đã nhận lượt chạy đó hay chưa. Nếu chưa nhận, chưa có gì chạy và bạn có thể yêu cầu lại. Từ chối hoặc hết hạn sẽ kết thúc task. Đây là quyết định chỉ bạn được thực hiện: MCP, relay yêu cầu qua WebSocket và clarkcant api từ chối route bằng 403 PERSON_ONLY, để AI client không tự duyệt thao tác của nó.

Ai đã yêu cầu: nguồn gốc của một lượt

Mỗi lượt ghi lại ai đã bắt đầu nó, thành origin của tin nhắn người dùng: person (trang của chính bạn, một tin nhắn nói, hoặc một thẻ bạn trả lời hoặc một hành động widget bạn bấm trong trang), mcp (MCP ask_clark), relay (relay WebSocket), cli-api (clarkcant api, một script hoặc mọi người giữ token khác), automation (một tự động hoá đã lên lịch hoặc thường trực) hoặc peer (tác vụ một node khác uỷ cho). Node đọc giá trị này từ những gì gateway đã biết, không bao giờ từ thân request, và ghi nó trên thẻ duyệt mà lượt đó tạo ra, trên dòng của lượt trong GET /activity và trong nhật ký kiểm toán.

Mặc định chính sách đối xử với mọi nguồn gốc như với chính bạn: một lượt do ứng dụng AI bắt đầu qua MCP được quyết định y như tin nhắn của bạn. Để các chương trình phải hỏi trước, hãy bật tuỳ chọn trong Cài đặt → Điều khiển → Yêu cầu từ chương trình khác, tức đặt preference execution.machineTurns thành "ask". Khi đó một bước rủi ro (external-write, destructive, financial, communication, media-capture) trong lượt bắt đầu từ mcp, relay hoặc cli-api sẽ hỏi trước, ở chỗ chính sách lẽ ra đã cho chạy. Quy tắc từ chối hoặc lệnh cấm vẫn thắng.

Duyệt một bước không có nghĩa là duyệt phần còn lại: sau khi bạn duyệt một thẻ do chương trình tạo ra, bước rủi ro tiếp theo của nó vẫn được hỏi lại. Lưu ý: chương trình nào giữ token của node này vẫn có thể đổi cài đặt này, hoặc gọi thẳng HTTP API mà xưng là bạn.

channel được dành cho tin nhắn từ một ứng dụng nhắn tin bên ngoài (Telegram, Discord, WhatsApp và tương tự) đã gắn với một cuộc trò chuyện. Hiện chưa kết nối được ứng dụng nhắn tin nào: node đã có phần nền, nhưng bản build này chưa kèm nhà cung cấp kênh nào và chưa có route nào nhận tin nhắn từ kênh, nên hôm nay chưa có lượt nào mang nguồn gốc này. Khi có, việc lượt đó được làm gì tùy vào người gửi là ai, được quyết định từ tài khoản mà họ được ánh xạ tới, không bao giờ từ tên hiển thị hay nội dung tin nhắn:

Tin nhắn người dùng đến từ kênh còn mang authorPrincipalId (người gửi được ánh xạ tới ai, để bản ghi phân biệt được nhiều người nói) và, khi nó trả lời một tin nhắn của cuộc trò chuyện này, inReplyToMessageId. Cả hai đều không bắt buộc, chỉ node đặt, và không có trên mọi tin nhắn khác.

Xử lý một thông báo

GET /inbox liệt kê các thông báo của bạn, và mỗi thông báo mang theo các actions hợp với điều nó nói tới ngay lúc này. Node tính lại chúng mỗi lần đọc, nên một thao tác không còn làm được vẫn được liệt kê, kèm lý do unavailable (conversation-gone, work-gone, package-gone hoặc already-current), thay vì thành một nút bấm vào thì lỗi. Mỗi thao tác đi tới một route riêng:

Thao tácRouteTác dụng
Chạy lạiPOST /work/{id}/retryViệc nền bị lỗi, bị dừng hoặc bị cắt ngang do khởi động lại sẽ chạy lại với đúng yêu cầu cũ, trong cùng hội thoại, thành một việc mới có id riêng. Mỗi lần chạy chỉ chạy lại được một lần: bấm lần thứ hai trả về 409 ALREADY_RETRIED. Việc đã xong hoặc còn đang chạy trả về 409 WORK_NOT_RETRYABLE, còn node đang bận trả về 429 BACKGROUND_BUSY và để lần chạy đó vẫn chạy lại được sau.
Hỏi lạiPOST /conversations/{id}/questions/{questionId}/ask-againMột câu hỏi đã hết hạn mà chưa ai trả lời quay lại thành câu hỏi mới với cùng lời và cùng lựa chọn, và thẻ cũ ghi rằng nó đã được hỏi lại. Câu hỏi còn đang chờ trả về 409 QUESTION_OPEN, câu đã được trả lời hoặc đã huỷ trả về 409 QUESTION_CLOSED, và câu đã được hỏi lại trả về 409 ALREADY_ASKED_AGAIN.
Cập nhậtPOST /packages/installLần cài đặt bình thường với phiên bản thông báo nêu, nên mọi bước kiểm tra khi cài vẫn áp dụng. Nếu bị từ chối, bản bạn đang cài vẫn giữ nguyên.
Bỏ qua bản nàyPOST /inbox/notices/{id}/skip-versionNgừng báo phiên bản đó của một gói, cùng các bản cũ hơn; bản mới hơn vẫn được báo. Phiên bản được đọc từ thông báo, không từ yêu cầu gửi lên. …/unskip-version hoàn tác việc này. Thông báo không phải về bản cập nhật trả về 409 NOT_AN_UPDATE.

Thông báo rằng bộ máy của Clark (Pi SDK) có bản mới không cần bạn làm gì: bản mới sẽ có trong bản ClarkCant tiếp theo. Tiêu đề gọi theo bộ máy của Clark, phần nội dung vẫn ghi tên Pi SDK và các phiên bản, và nút đầu tiên là Bỏ, cạnh đó là Bỏ qua phiên bản này, không có nút Hỏi Clark.

Các phiên bản bạn đã bỏ qua nằm trong skippedVersions của GET /inbox, mới nhất trước. DELETE /inbox/skipped-versions/{kind}/{name}/{version} lấy lại một bản kể cả khi thông báo của nó đã không còn, với kind là package hoặc pi và mỗi phần được mã hoá URL, nên @scope/name vẫn dùng được.

curl -s -X DELETE "$CLARKCANT_URL/inbox/skipped-versions/package/%40scope%2Fname/1.4.0" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"

Một route cho mọi thao tác của một thông báo

POST /inbox/notices/{id}/actions/{action} thực hiện bất kỳ thao tác nào ở trên theo tên. Đây là route mà các nút trong hộp thư của ứng dụng, một yêu cầu gõ hoặc nói, các agent của chính Clark, MCP tool act_on_notice và clarkcant api đều dùng. Thao tác là một trong mark-read, mark-unread, dismiss, restore (hoàn tác việc bỏ trong năm phút), snooze, unsnooze, suppress, unsuppress, retry, update, skip-version hoặc ask-again. Body là {}; snooze cần { "until": "<ISO instant>" }, tối đa 30 ngày sau.

curl -s -X POST "$CLARKCANT_URL/inbox/notices/<noticeId>/actions/dismiss" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Node đối chiếu thao tác với những gì thông báo đưa ra ngay lúc đó, và không đổi gì khi từ chối:

Khi làm được, câu trả lời là { "noticeId", "action", "outcome": "done" }, cùng những gì thao tác tạo ra: snoozedUntil, workId mới, version hoặc questionId mới. Một bản cập nhật đã cài còn cho biết bao nhiêu quyền nó yêu cầu đang chờ bạn duyệt (pendingCapabilities) và bao nhiêu bị chế độ thực thi của bạn từ chối (deniedCapabilities). update trả nguyên mọi lời từ chối của bước cài đặt. Nếu chế độ thực thi của bạn yêu cầu hỏi trước khi cài, nó trả 202 với "outcome": "approval-required" và không cài gì; yêu cầu lại cùng phiên bản sẽ dùng lại yêu cầu duyệt vẫn đang chờ. Mỗi lần gọi mà route này xử lý được ghi vào nhật ký của node kèm bề mặt nó đến từ đó. Các route trong bảng vẫn dùng được như trước.

Các route hộp thư dùng cùng token nhưng chưa có trong /openapi.json và có thể thay đổi.

Cho biết một hành động đã có hiệu lực hay chưa

Khi một lệnh tác động ra ngoài máy của bạn, chẳng hạn một lần push, hết thời gian hoặc bị dừng trước khi báo kết quả, không ai biết nó đã được thực hiện hay chưa. Tác vụ chờ ở trạng thái chưa rõ, không tự làm lại hành động đó, và hộp thư của bạn nhận một thông báo về nó với hai nút: “Đã có hiệu lực” và “Chưa có hiệu lực”. Câu trả lời được ghi lại cùng người trả lời và thời điểm, không thể đổi về sau, và quyết định kết cục của tác vụ: tác vụ chỉ thành công khi hành động đã có hiệu lực và lần chạy đã kiểm tra kết quả của nó.

curl -s -X POST "$CLARKCANT_URL/effects/<effectId>/reconcile" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "confirmed" }'
# outcome: "confirmed" (đã có hiệu lực) hoặc "failed" (chưa có hiệu lực)

source (click, chat hoặc voice) là nhãn tuỳ chọn cho biết câu trả lời được đưa ra ở đâu; nhãn được lưu đúng như gửi và không chứng minh điều gì. Một hành động thuộc tác vụ của người khác, của node khác, hoặc không tồn tại trả về 404 RESOURCE_NOT_FOUND; một hành động không còn ở trạng thái chưa rõ trả về 409 EFFECT_NOT_UNKNOWN. Route này ghi lại quyết định của một người, nên relay WebSocket, MCP và clarkcant api từ chối nó với 403 PERSON_ONLY: một AI client tự nói được rằng lần push của nó đã thành công thì cũng tự báo được thành công của chính nó.

Một tác vụ website chạy nền ghi các lần gửi biểu mẫu và những cú nhấp khác có thể làm thay đổi điều gì đó vào cùng sổ này. Khi một biểu mẫu đã được gửi đi mà không nhận được trả lời, kết quả là chưa rõ, biểu mẫu không bị gửi lại, và nó dẫn tới đây.

Chọn chủ đề

Chủ đề quy định màu sắc và độ bo góc của Clark, và từ appearance API 2 là cả phần còn lại của diện mạo (xem bên dưới). Nó tách biệt với chế độ màu (sáng, tối hoặc theo hệ thống), vốn vẫn áp dụng bên trong mọi chủ đề. Clark Default có sẵn, và các chủ đề khác đến từ những gói đã cài có khai báo facet themes. Chủ đề chỉ là dữ liệu: nó không chạy được mã, không thêm được style toàn cục, không với ra ngoài gói của nó và không tải được gì. Mọi chủ đề đều phải qua cùng phép kiểm tra độ tương phản như Clark Default và một phép kiểm tra giữ các trạng thái được bảo vệ tách biệt nhau, và chủ đề trượt một trong hai sẽ không được đưa ra để chọn. Các route này dùng cùng token nhưng chưa có trong /openapi.json và có thể thay đổi.

MethodĐường dẫnBodyGhi chú
GET/themes–{ themes, problems, unchecked }. Clark Default đứng đầu, sau đó là từng chủ đề của gói kèm themeRef (package:<package id>#<theme id>) và nơi cung cấp: package id, phiên bản, digest, làn tin cậy và nguồn. problems nêu từng chủ đề không thể đưa ra và lý do; chủ đề trượt kiểm tra độ tương phản có kèm danh sách contrast các cặp màu không đạt. unchecked nêu từng gói mà node này không đọc được tệp.
GET/appearance–{ selectedRef, appliedRef, theme, provider, fallback }: điều bạn đã chọn và điều đang được vẽ. Khi lựa chọn không vẽ được, Clark Default được vẽ thay, lựa chọn của bạn vẫn được giữ, và fallback cho biết lý do bằng THEME_NOT_INSTALLED, THEME_INVALID, THEME_LOW_CONTRAST, THEME_PROTECTED, THEME_UNAVAILABLE hoặc THEME_UNKNOWN. Cài lại gói, hoặc lùi bản cập nhật đã làm hỏng nó, sẽ đưa chủ đề trở lại mà không cần chọn lại.
PUT/preferences/experience.themeRef{ value }Chọn một chủ đề: builtin:clark, hoặc một themeRef từ /themes. Tham chiếu mà node này không vẽ được sẽ bị từ chối với 409 cùng mã và lý do tương ứng, và không có gì được lưu. Giá trị hoàn toàn không phải là tham chiếu trả về 400 PREFERENCE_INVALID.

Các trường message bằng tiếng Anh, dành cho log. Hãy hiển thị lỗi từ code và contrast bằng ngôn ngữ của người đọc, như ứng dụng vẫn làm. Không có gì được đẩy xuống khi một gói thay đổi, nên client đọc lại /appearance sau khi nó thay đổi một gói và khi cửa sổ của nó được mở lại. Trang đổi giao diện tại chỗ, không tải lại, và giữ nguyên cuộc trò chuyện, tin nhắn đang soạn và các khung đã ghim.

curl -s -X PUT "$CLARKCANT_URL/preferences/experience.themeRef" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "package:com.example.theme-dusk#dusk" }'

Gói chủ đề tham chiếu

Pixel Arcade và Neo Brutalism là ví dụ chỉ chứa dữ liệu trong checkout ClarkCant. Cài qua vòng đời package hiện có, rồi chọn trong Cài đặt → Trải nghiệm hoặc xem trước trong Theme Lab. Tham chiếu của chúng là package:org.clarkcant.pixel-arcade#pixel-arcade và package:org.clarkcant.neo-brutalism#neo-brutalism. Đây là gói trong checkout; xuất bản trên marketplace vẫn là bước riêng.

Pixel Arcade có khung vuông, nút vát cạnh, bóng cứng, đường quét có giới hạn, chuyển động theo bước và Orb Plasma mặc định. Neo Brutalism có viền dày, bóng lệch, tiêu đề đậm, nút nổi và Orb Glass mặc định. Cả hai thích ứng qua cùng đường diện mạo của host, widget built-in/khai báo, snapshot widget cách ly và cửa sổ tách rời. Lựa chọn Orb riêng thắng các mặc định này; giảm chuyển động luôn thắng. Clark Default giữ nguyên.

Mỗi gói ghi giấy phép Apache-2.0 và nguồn. Phông là profile do host sở hữu với fallback hệ thống: Pixel Arcade dùng mono cho tiêu đề, typewriter cho mã và system dễ đọc cho nội dung; Neo Brutalism dùng system cho nội dung/tiêu đề và stack mono của host. Các gói không đóng gói và không tải tệp phông nào. Phông lấy từ stack hệ thống có thể khác nhau giữa hệ điều hành.

Xem trước và tùy chỉnh

Mở Cài đặt → Trải nghiệm → Duyệt chủ đề để vào Theme Lab. Nó dùng component sản phẩm thật với các ví dụ cục bộ được ghi rõ. Xem trước chủ đề đã cài giữ hội thoại, draft và focus; chỉ Dùng chủ đề này mới lưu lựa chọn. Chủ đề dùng gần đây do cùng bộ ghi preference lưu lại (tối đa sáu tham chiếu khác nhau); tham chiếu không còn trên node này không hiện thành nút gần đây.

GET /appearance?themeRef=<tham chiếu đã encode> phân giải chủ đề đã cài và kiểm tra để xem trước, không đổi preference. Tham chiếu sai hình dạng trả 400; chủ đề không có trả fallback Clark Default thông thường. Diện mạo cá nhân trả thêm customization: { accent, density, font, codeFont } khi có. Accent là null để dùng màu của chủ đề hoặc { dark: "#7AA2F7", light: "#2453A8" }; density là comfortable hoặc compact. font là phông giao diện cho tin nhắn, tiêu đề và mọi nút bấm, một trong các profile body bên dưới; codeFont là phông cho khối code, code trong dòng, đường dẫn và số liệu căn cột, một trong các profile mono. null giữ phông của chủ đề. Ghi qua PUT /preferences/experience.accent, experience.density, experience.font và experience.codeFont với { value }. Trong Cài đặt → Trải nghiệm, mỗi lựa chọn phông được vẽ bằng chính phông đó, nên bạn chọn bằng mắt. Mỗi màu nhấn hiện thành một ô màu cạnh mã hex, và bấm vào ô màu sẽ mở bảng chọn màu của hệ điều hành, nên bạn chọn được màu mà không cần biết mã của nó. Màu nhấn khó đọc hoặc che trạng thái được bảo vệ trả 409 trước khi đổi preference. Compiler chọn màu chữ dễ đọc trên nút nhấn; mật độ gọn giữ nguyên typography và giới hạn bố cục tối thiểu. Cả hai lựa chọn tới widget và cửa sổ detached qua cùng snapshot appearance.

Nếu bản cập nhật package khiến màu nhấn đã lưu không đạt kiểm tra, màu của chủ đề được vẽ và customizationFallback giải thích lý do; preference đã lưu vẫn được giữ. Đặt lại tùy chỉnh chủ đề đưa màu nhấn, mật độ, phông chữ, chuyển động và cá nhân hóa Orb về mặc định, giữ chủ đề đã chọn, chế độ sáng/tối và ngôn ngữ. Lựa chọn giảm chuyển động của hệ điều hành luôn thắng. Xem tạo chủ đề cho init, dev, test và pack.

Phần còn lại của diện mạo (appearance API 2)

Từ appearance API 2 ("appearanceApi": { "min": 2, "max": 2 }), chủ đề có thể đặt toàn bộ diện mạo chứ không chỉ màu sắc. Mỗi thiết lập là một cái tên hoặc một con số có giới hạn, và ClarkCant tự viết CSS:

Chủ đề không được chứa CSS, selector, URL, tệp font hay ảnh, và trường, recipe hay hiệu ứng lạ, hoặc giá trị ngoài giới hạn, đều bị từ chối. Chủ đề phải qua hai phép kiểm tra ở cả chế độ sáng và tối: kiểm tra độ tương phản và kiểm tra trạng thái được bảo vệ. Phép kiểm tra trạng thái được bảo vệ yêu cầu:

Chủ đề không đạt sẽ không được đưa ra để chọn. /themes liệt kê nó trong problems kèm từng mục không đạt, và chọn nó sẽ nhận 409 với THEME_LOW_CONTRAST (kèm danh sách contrast) hoặc THEME_PROTECTED (kèm danh sách protected gồm { scheme, check, first, second, value, minimum }). check là status-distinct, status-vs-text, focus-vs-border, disabled-distinct, edge-visible, surface-readable hoặc orb-visible, và first là "orb" với orb-visible. THEME_PROTECTED cũng có thể là mã fallback của /appearance. Hãy diễn đạt từng mã bằng ngôn ngữ của người đọc, và diễn đạt một mã bạn không biết bằng một câu chung.

Dù chủ đề nói gì, có những thứ luôn do ClarkCant kiểm soát:

Đổi diện mạo bằng cách yêu cầu

Bạn cũng đổi được diện mạo bằng cách nói với Clark, bằng giọng nói, hoặc qua POST /app-intents với appearance.set-theme (themeRef), appearance.set-color-scheme (colorScheme: light, dark hoặc system), appearance.reset (Clark Default, theo hệ thống) hoặc appearance.open-theme-gallery. Mỗi yêu cầu lưu lựa chọn giống như bộ chọn trong Cài đặt, và không yêu cầu nào hỏi xác nhận. Chủ đề được đối chiếu với các chủ đề của node này và bị từ chối bằng một câu nói rõ khi không vẽ được. Một yêu cầu làm việc, như "make a dark theme", được chuyển cho Clark thay vì đổi chế độ màu. Các câu có sẵn ("switch to dark mode", "chuyển giao diện sang tối") giữ nguyên nghĩa kể cả khi có chủ đề đã cài tên "Dark"; chủ đề như vậy được chọn từ bộ chọn hoặc qua agent.

Diện mạo cho tác giả widget

Widget built-in và Mini App khai báo theo chủ đề hiện tại bằng token semantic. Widget cách ly nhận cùng AppearanceSnapshot công khai đã kiểm tra, với chế độ sáng/tối đã phân giải, token có giới hạn, giảm chuyển động và revision. Nó không nhận tệp theme thô, thông tin xác thực hay quyền truy cập host.

api.appearance.current() trả về snapshot đóng băng sâu, hoặc undefined khi host cũ không cung cấp extension. api.appearance.subscribe(handler) nhận revision thay đổi và trả về hàm huỷ đăng ký. Snapshot ban đầu đến trước khi mount; đổi chủ đề giữ nguyên iframe, props và state, không ghi semantic hay tạo lượt model. Nội dung lịch sử, props/state đã lưu, nguồn gốc và văn bản dự phòng giữ nguyên.

import { bindAppearance } from "@clarkcant/widget-sdk/dom";

const unbind = bindAppearance(document.documentElement, api.appearance);
api.lifecycle.onDispose(unbind);

SDK core độc lập với DOM. Adapter tuỳ chọn chỉ ghi biến --cc-* chuẩn và thuộc tính diện mạo trên phần tử được truyền vào, giữ nguyên biến riêng của tác giả. Runtime /widget-runtime.js do host phục vụ cũng export bindAppearance và applyAppearanceToElement.

Bridge phiên bản 2 mang appearance tuỳ chọn trong init kèm appearance@1, rồi gửi { kind: "appearance.changed", nonce, revision, appearance } với revision trùng khớp và kiểm tra source/nonce hiện có. SDK mới nhận host phiên bản 1 không có diện mạo. SDK cũ phiên bản 1 đóng gói trong widget phải được nâng cấp để chạy với host phiên bản 2; hãy dùng runtime do host cung cấp hoặc build lại bằng SDK hiện tại. Composition tách cửa sổ nhận cùng revision đã phân giải qua relay chỉ đọc của desktop, không truy vấn theme hay nhận thông tin xác thực.

Định nghĩa widget mặc định dùng appearanceMode: "adaptive"; widget có thể khai báo "fixed" cho hệ thống giao diện riêng. Lab và thẻ chi tiết ghi rõ widget fixed. Directory có thể cung cấp widgetAppearance: [{ id, mode }] để hiển thị trên marketplace, nhưng định nghĩa đã cài và kiểm tra digest vẫn là nguồn quyết định. Widget fixed vẫn nhận diện mạo và phải tôn trọng giảm chuyển động; cả hai chế độ đều không thể đổi giao diện của host.

Ô bản đồ

Bản đồ vẽ một bản đồ nền ngoại tuyến và không yêu cầu ô bản đồ nào cho tới khi một nhà cung cấp được nêu tên trong preference maps.tilePolicy, vốn mặc định là null (xem Bản đồ). Bạn đặt nó trong Cài đặt → Tiện ích → Ô bản đồ, hoặc Clark đặt nó qua công cụ của mình theo execution policy của bạn. Việc ghi hoặc hoàn tác trực tiếp chính sách, cũng như nhập hoặc xóa khóa, là quyết định của riêng bạn: MCP, relay WebSocket và clarkcant api từ chối các route đó với 403 PERSON_ONLY. Các route ô bản đồ có trong /openapi.json.

MethodĐường dẫnBodyGhi chú
PUT/preferences/maps.tilePolicy{ value }Đặt chính sách thành một nhà cung cấp, hoặc thành null để tắt ô bản đồ. origin đúng dạng scheme://host[:port], dùng https, hoặc http chỉ với địa chỉ loopback. template là một đường dẫn trên origin đó chứa {z}, {x} và {y}, mỗi cái đúng một lần. attribution là một dòng dài tối đa 200 ký tự, và maxZoom là số nguyên tối đa 19. template dài tối đa 300 ký tự, bắt đầu bằng / và chỉ dùng chữ cái, chữ số, / . _ ~ - = & ? cùng các ký hiệu giữ chỗ. Trong phần truy vấn của template, tên tham số nào chứa key, token, secret, sig, auth, pass, credential hoặc session đều bị từ chối: khóa thuộc về credential. credential tùy chọn là { secret: "maps:tiles" } kèm đúng một trong hai trường header hoặc query; chính sách nêu tên bất kỳ secret nào khác đều bị từ chối. Giá trị không hợp lệ trả về 400 PREFERENCE_INVALID, và không có gì được lưu. Chỉ dành cho người dùng: 403 PERSON_ONLY trên giao diện máy.
POST/preferences/maps.tilePolicy/undo–Hoàn tác lần ghi cuối và trở về giá trị mà nó đã thay: { undone, preference }. undone: false, kèm reason, nghĩa là không có gì để hoàn tác. Chỉ dành cho người dùng: 403 PERSON_ONLY trên giao diện máy.
GET/map-tiles–{ provider: { origin, attribution, maxZoom } | null, offline? }. Khi provider là null, offline cho biết lý do: no-provider (mặc định), key-unavailable (chính sách cần khóa nhưng chưa lưu khóa dùng được) hoặc key-origin-mismatch (khóa đã lưu được nhập cho origin khác, nên node không gửi nó tới origin này). Không bao giờ trả về mẫu đường dẫn hay bất cứ phần nào của khóa.
GET/map-tiles/key–{ key: { origin? } | null }: đã lưu khóa hay chưa, và origin duy nhất mà khóa được gửi tới. Không bao giờ trả về giá trị.
PUT/map-tiles/key{ origin, value }Lưu khóa thành secret maps:tiles của node, gắn với origin; node chỉ gửi khóa tới đó. Nhập lại khóa cho origin khác sẽ chuyển ràng buộc, và không gì khác chuyển được. Trả về { key: { origin } }, không bao giờ trả về giá trị. Chỉ dành cho người dùng: 403 PERSON_ONLY trên giao diện máy.
DELETE/map-tiles/key–Xóa khóa: { removed }. Chỉ dành cho người dùng: 403 PERSON_ONLY trên giao diện máy.
GET/map-tiles/{z}/{x}/{y}–Một ô bản đồ từ nhà cung cấp của chính sách, do node tải về: image/png hoặc image/webp, được kiểm tra bằng loại nội dung của nhà cung cấp và chính các byte, tối đa 512 KiB, kèm nosniff. Chuyển hướng không được đi theo. Các lỗi từ chối: 404 MAP_TILES_OFF khi không có chính sách, 400 MAP_TILE_OUT_OF_BOUNDS khi zoom vượt maxZoom hoặc x và y nằm ngoài lưới của mức zoom đó, 429 MAP_TILES_RATE_LIMITED khi vượt 12 yêu cầu mỗi giây với đợt dồn 48, 404 MAP_TILE_MISSING khi nhà cung cấp không có ô nào ở địa chỉ đó, 502 MAP_TILE_FAILED hoặc MAP_TILE_REFUSED, và 503 MAP_TILE_KEY_UNAVAILABLE khi không dùng được khóa, thường kèm cùng lý do offline (trừ khi chính secret broker từ chối khóa). Tối đa 256 ô hoặc 24 MiB được lưu đệm trong một giờ.

Khóa luôn là secret riêng của node, maps:tiles, với consumer duy nhất là maps:tiles@<origin>, tức origin mà khóa được nhập cho. Node thêm khóa, thông qua secret broker, dưới dạng header hoặc tham số truy vấn mà chính sách nêu tên, và chỉ vào các yêu cầu tới origin đó. Clark có thể nêu tên một nhà cung cấp nhưng không chuyển được khóa, và biểu mẫu credential chung (POST /credentials) từ chối tên maps:tiles cùng mọi consumer maps:tiles. Khóa không bao giờ tới trang, props, trạng thái widget, log, khóa bộ đệm, thông báo lỗi hay mô hình.

Ví dụ dưới đây gọi node qua HTTP trực tiếp bằng token của chính node. clarkcant api, MCP và relay WebSocket từ chối cùng lệnh gọi đó với 403 PERSON_ONLY.

curl -s -X PUT "$CLARKCANT_URL/preferences/maps.tilePolicy" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": { "origin": "https://tiles.example.com", "template": "/styles/basic/{z}/{x}/{y}.png", "attribution": "© Example contributors", "maxZoom": 17, "credential": { "secret": "maps:tiles", "header": "x-api-key" } } }'

Chính sách nội dung media

Trình phát âm thanh có thể phát một tệp từ web, nhưng trang không bao giờ tự tải nó: node của bạn tải nó, một lần, khi trình phát được đặt (xem Trình phát âm thanh và xem trước tài liệu). Không có route HTTP nào cho việc này; chính sách là thiết lập khởi động CC_MEDIA_ORIGINS của node, một danh sách các origin https trần phân tách bằng dấu phẩy, tối đa 32 mục, mặc định để trống. Một danh sách có bất kỳ mục nào không đúng dạng đó sẽ bị bỏ qua toàn bộ, node không cho phép gì, và nói lý do một lần khi khởi động.

CC_MEDIA_ORIGINS=https://media.example.com,https://cdn.example.org

Mỗi lần từ chối kết thúc bằng (media policy rule: <rule>) trong thông báo mà mô hình đọc:

Quy tắcĐiều bị từ chối
origin-not-allowedMột origin không có trong CC_MEDIA_ORIGINS.
https-onlyBất kỳ scheme nào ngoài https, trong URL hoặc trong một lần chuyển hướng.
credentials-in-urlTên người dùng hoặc mật khẩu trong URL hoặc trong một lần chuyển hướng.
private-addressMột tên phân giải ra địa chỉ loopback, riêng tư, link-local hoặc địa chỉ dành riêng khác, được kiểm tra trên đúng địa chỉ thực sự được kết nối. Một origin được viết dưới dạng địa chỉ hoặc localhost chỉ đúng địa chỉ đó và được cho phép.
redirect-off-origin, too-many-redirectsChuyển hướng sang origin khác, hoặc quá 3 lần.
type-not-allowedLoại khai báo không phải audio/mpeg, audio/ogg, audio/wav hay audio/webm.
type-mismatchCác byte không đúng loại đã khai báo, được kiểm tra bằng cách nhận dạng định dạng chứa, hoặc truyền tải có nén.
too-largeLớn hơn 25 MiB, dựa trên độ dài khai báo hoặc ngay khi phần thân vượt quá mức đó.
too-long, duration-unknownDài hơn một giờ, hoặc định dạng chứa không nêu độ dài của nó.
timeout, not-found, fetch-failedLần tải lâu hơn 30 giây, tệp không tồn tại, hoặc không kết nối được.
sourceKhông có đúng một nguồn, hoặc một ID mà node không cấp.

Yêu cầu không mang cookie, thông tin xác thực hay referrer và dùng một kết nối mới. Tệp vượt qua kiểm tra được lưu thành artifact của cuộc hội thoại, tính vào hạn mức lưu trữ của bạn, và trang phát nó từ node; chính sách nội dung của trang vẫn là media-src 'self' blob:. Các bước kiểm tra loại tệp, kích thước và độ dài cũng áp dụng cho tệp âm thanh mà người dùng đã có sẵn.

Danh sách gói đến từ đâu

Thư mục gói mà node của bạn tìm kiếm và cài đặt được ghép từ nhiều nguồn, theo thứ tự ưu tiên sau:

  1. tệp chỉ mục JSON do CC_DIRECTORY_INDEX chỉ định;
  2. từng feed marketplace hoặc catalog trong CC_DIRECTORY_MARKETPLACES, theo thứ tự đã ghi: các URL https ngăn cách bằng dấu phẩy hoặc khoảng trắng, chỉ cho phép http thường tới loopback của chính máy này;
  3. feed của ClarkCant Marketplace chính thức, https://marketplace.clarkcant.cc/api/v1/directory, bật sẵn theo mặc định. Khởi động node với CC_OFFICIAL_MARKETPLACE=off để tắt nó.

Feed chính thức còn mới. Feed đã phản hồi, nhưng chỉ liệt kê những gói mà Marketplace đã lập chỉ mục kèm ID gói ClarkCant, nên hiện có thể chỉ có vài gói hoặc chưa có gói nào. Tệp chỉ mục hay catalog của riêng bạn vẫn hoạt động mà không cần nó.

Một ID gói thuộc về nguồn đầu tiên liệt kê nó. Listing của nguồn sau cho cùng ID đó bị bỏ ra và được đếm là bị che (shadowed), nên một marketplace không thể thêm phiên bản, hay bản cập nhật, cho gói mà chỉ mục hoặc catalog của bạn đã nêu. Mọi nguồn đều không được tin cậy: listing chỉ là một con trỏ, không thứ gì nó mang theo cấp quyền, và cài nó đi qua cùng quy trình cài đặt, với các bước kiểm tra phiên bản chính xác và digest, như một listing trong tệp của bạn.

Một nguồn từ xa chỉ được tải khi có việc cần đến: một lần tìm kiếm, khi bản sao đã cũ hơn 15 phút; một lần cài listing chưa có trong bản sao, khi bản sao cũ hơn một phút; và lần kiểm tra cập nhật, vốn chỉ làm mới những nguồn node đã từng tải. Bản sao tốt gần nhất được giữ trong <dataDir>/directory-cache/ kèm thời điểm tải. Một nguồn không phản hồi đầy đủ không bao giờ hiện thành danh sách rỗng như thể “không tìm thấy gì”; nó được báo kèm trạng thái:

Trạng tháiÝ nghĩa
staleLần làm mới thất bại. Bản sao tốt gần nhất vẫn được liệt kê, kèm lý do.
not-fetchedNguồn chưa từng được tải.
unreachableKhông kết nối được tới nguồn và chưa có bản sao nào trước đó.
unsupportedĐịa chỉ trả về 404, 405 hoặc 501.
unreadableNguồn không phải là một thư mục gói hợp lệ.

Nguồn không đọc được vẫn giữ các gói của nó

Thứ tự ưu tiên chỉ đứng vững khi các nguồn trước đọc được, nên một nguồn không đọc được không bao giờ nhường ID gói của nó cho nguồn sau:

Mỗi hàng của thẻ marketplace-results mang sourceId (local, official hoặc custom-<hash>), và nút Cài gửi lại giá trị này. Khi thẻ chứa nhiều nguồn, mỗi hàng còn mang origin: { kind, label }, trong đó kind là local-file, custom-marketplace hoặc official-marketplace. Thẻ liệt kê từng nguồn không phản hồi đầy đủ trong sources: [{ kind, label, state, fetchedAt?, reason? }]. Tool search_directory của Clark nhận packageId tùy chọn và khi đó liệt kê mọi phiên bản của gói đó kèm chi tiết.

Một feed chỉ được gọi tên bằng host và đường dẫn của nó. Với địa chỉ không phân tích được, mọi thứ từ dấu ? hoặc # đầu tiên và mọi thứ trước dấu @ đều bị cắt bỏ, nên token trong địa chỉ feed không bao giờ xuất hiện trong nhãn, thông báo lỗi, thẻ tìm kiếm hay GET /packages.

Cài từ một nguồn, và bản cập nhật đến từ đâu

POST /packages/install nhận sourceId tùy chọn: nguồn bạn đã chọn khi bấm Cài trên một hàng. Khi listing chưa có trong bản sao của node, nó làm mới nguồn từ xa một lần. Thư mục gói bổ sung các lần từ chối sau:

Phản hồiKhi nào
404 NOT_IN_DIRECTORYKhông nguồn nào liệt kê gói và phiên bản đó. Thông báo nêu tên mọi nguồn đã không phản hồi.
409 DIRECTORY_UNREADABLEKhông nguồn nào đọc được, hoặc tệp chỉ mục bị hỏng.
409 DIRECTORY_SOURCE_UNREADGửi không kèm sourceId, và một nguồn đứng trước không đọc được. Thông báo nêu tên cả hai nguồn.
409 DIRECTORY_SOURCE_CHANGEDGửi không kèm sourceId, và gói đang được cài từ một nguồn khác; hoặc gửi kèm, nhưng giờ một nguồn khác đang sở hữu listing đó.

Node ghi nguồn lên generation đã cài (directorySource). Lần kiểm tra cập nhật chỉ đề xuất phiên bản mới hơn từ chính nguồn đó, và thông báo cập nhật nêu tên nguồn. Muốn chuyển một gói sang nguồn khác, bạn bấm Cài trên hàng của nguồn đó. Gói được cài trước khi nguồn được ghi lại là gói đến từ tệp chỉ mục của bạn, nguồn duy nhất lúc đó: nó chỉ nhận cập nhật từ tệp, không có thông báo cập nhật khi tệp không liệt kê nó, và chỉ chuyển sang nguồn khác khi bạn bấm Cài trên hàng của nguồn đó.

Một lần cài mà chế độ thực thi hỏi bạn sẽ giữ nguồn đang sở hữu listing tại lúc hỏi. Nếu tới lúc bạn duyệt mà một nguồn khác đã sở hữu nó, kể cả với các byte giống hệt, lần duyệt trả về 409 DIRECTORY_SOURCE_CHANGED, không cài gì và câu hỏi rời khỏi hộp thư. Cài lại sẽ hỏi về nguồn mới.

Cài một gói

POST /packages/install cài gói mà bạn đã chọn. Chỉ ứng dụng của chính bạn gọi được route này: MCP, relay WebSocket và clarkcant api nhận 403 PERSON_ONLY, và không agent hay tool nào của mô hình cài được gói từ một thư mục gói. Tool agent duy nhất đi tới đường cài đặt là develop_widget (phiên phát triển widget), chỉ trong lượt do bạn gửi, và policy quyết định các lần cài của nó như đề xuất của chính Clark.

Với một gói được liệt kê bằng đường dẫn trên máy này, node của bạn tự tính digest các tệp của nó; bạn không cần gửi digest. Listing trên marketplace mang contentDigest, digest của các tệp đó lúc danh sách được tạo, và nút Cài gửi lại nó. Nếu các tệp đã đổi từ đó, lần cài bị từ chối với 409 DIGEST_MISMATCH, không có gì được cài hay được hỏi, và ứng dụng mời tìm lại thay vì cùng nút Cài. Lần cài sao chép các tệp vào bộ nhớ đệm gói của node và gói chạy từ bản sao đó, nên những chỉnh sửa sau này với các tệp của nó không thay đổi gì cho tới khi bạn cài lại, và lần cài lại kiểm tra chúng từ đầu. Trong lúc bạn đang làm một gói, clark widget dev hoặc một phiên phát triển widget là vòng chỉnh sửa trực tiếp. Nếu listing thay đổi dưới một gói đã cài (cùng phiên bản được liệt kê với digest khác, hoặc một phiên bản khác), các tệp, frame và lượt đọc widget của nó trả về 409 NOT_INSTALLED cho tới khi bạn cài lại, và các widget của nó giữ nguyên trạng thái. Một đường dẫn không sao chép được các tệp (không đọc được, chứa liên kết tượng trưng hay liên kết cứng, hoặc hơn 5.000 tệp, 5.000 thư mục, thư mục lồng sâu 64 cấp hay 64 MiB) bị từ chối với 400 LOCAL_SOURCE_UNREADABLE, còn các tệp thay đổi trong lúc đang được sao chép thì nhận 409 DIGEST_MISMATCH, nên bản sao không bao giờ là sự pha trộn của hai phiên bản. Một bản sao mà node không ghi được vào bộ nhớ đệm của chính nó (ví dụ khi ổ đĩa đầy) bị từ chối với 503 PACKAGE_CACHE_UNAVAILABLE; các tệp của bạn không bị thay đổi, và bạn có thể thử lại. Các kiểm tra này chạy trước khi chế độ thực thi của bạn quyết định. Client nào gửi localDigest vẫn hoạt động như trước.

Khi chế độ thực thi của bạn yêu cầu hỏi trước khi cài, node của bạn không cài gì và trả 202 kèm { "code": "APPROVAL_REQUIRED", "message", "approvalId" }. Lần cài đó chờ bạn trong hộp thư: GET /inbox liệt kê nó trong waiting với kind: "install-approval", kèm gói, phiên bản, những quyền gói xin, mức rủi ro, operationDigest, requestedAt và expiresAt. Mục này chỉ được liệt kê khi thư mục gói vẫn còn công bố đúng gói, đúng phiên bản và đúng digest đó.

Bạn quyết định bằng POST /packages/approvals/{approvalId}/decision với { "decision": "granted" | "denied", "digest" }, gửi đúng digest mà mục đã hiện. Đây cũng là route chỉ bạn dùng được để duyệt quyền của gói.

Một quyết định duyệt vẫn có thể bị từ chối:

Lần cài không ai quyết định sẽ hết hạn sau mười phút. Không cài gì, và một thông báo nói rõ điều đó. Mọi kết quả (đã hỏi, đã cài, đã từ chối, hết hạn, bị từ chối, thất bại) được ghi vào luồng sự kiện package.install-approval. Nút Cập nhật trên thông báo và nút Cài trong marketplace đều dẫn tới mục chờ này và nói nơi để quyết định.

Trước khi bạn cài, thẻ thư mục gói và câu hỏi cài đặt liệt kê những gì gói chạm tới bên ngoài vùng cách ly (xem những gì một gói chạm tới). Một artifact có manifest khai báo phạm vi khác với những gì trang gói đã hiện sẽ bị từ chối với 409 DECLARED_REACH_MISMATCH trước khi có bất cứ điều gì được ghi lại.

Phiên phát triển widget

Một phiên soạn trực tiếp cho một gói widget trong một thư mục trên node của bạn: thư mục được theo dõi, mỗi thay đổi đọc được như một gói trở thành một thế hệ bất biến, và thế hệ đó được cài qua đường cài đặt ở trên rồi hiện trong hội thoại trong khung widget thật. Xem phát triển widget ngay trong hội thoại.

MethodPathBodyGhi chú
POST/widget-dev/sessions{ root, conversationId?, widgetId? }Bắt đầu theo dõi root, một đường dẫn tuyệt đối trên node. 201 kèm phiên khi bản dựng đầu tiên đã chạy và đã được kích hoạt trong phạm vi policy cho phép. Có conversationId thì widget được đặt vào đó, ghim mở, khi có một thế hệ chạy. Bắt đầu một thư mục đã có phiên bị dừng thì phiên đó được tiếp tục. Chỉ người dùng.
GET/widget-dev/sessions–{ sessions: [...] }
GET/widget-dev/sessions/{id}–Một phiên: latest (bản dựng tốt mới nhất), running, activation (active, awaiting-approval kèm approvalId, refused kèm code và message, hoặc none), lastBuild (kèm diagnostics khi lỗi), showingLastKnownGood, placed, và với phiên đã dừng là stopReason (requested, watch-failed, folder-gone, capacity hoặc root-refused). root-refused nghĩa là khi node khởi động lại, thư mục không qua được bước kiểm mà một lần bắt đầu thực hiện; những gì phiên đã chạy vẫn tiếp tục chạy, và stopCode cho biết bước kiểm nào. ROOT_NOT_OWNED: Clark không còn được phép tự theo dõi thư mục, chẳng hạn một phiên do Clark bắt đầu trong một thư mục đã chọn bị xoá rồi tạo lại trong lúc node dừng; chính lần bắt đầu của người dùng (Phát triển lại trên thẻ /develop) chọn lại thư mục. ROOT_NOT_LOCAL hoặc ROOT_IN_DATA_FOLDER: thư mục giờ dẫn tới một ổ mạng chia sẻ hay đường dẫn thiết bị, hoặc vào thư mục dữ liệu của node (hay chứa thư mục đó), nên chọn lại nó cũng bị từ chối và thẻ không có nút Phát triển lại; hãy chép dự án vào không gian làm widget hoặc một thư mục dự án khác trên máy. stopCode là trường bổ sung và không bắt buộc: một phiên do phiên bản trước dừng thì không có nó, và một mã client không biết chỉ được nói bằng lý do. Ứng dụng đọc view của phiên một cách khoan dung: một trường ở cấp trên cùng mới hơn ứng dụng bị bỏ qua, còn dòng trạng thái và thẻ /develop nói rằng node mới hơn và một số điều node gửi không được hiển thị. Các trường đã biết vẫn giữ giới hạn của chúng, nên một giá trị ứng dụng không biết trong một trường nó biết (một stopReason, status hay trạng thái kích hoạt mới) vẫn làm view bị từ chối. Một trường mới hơn nằm trong activation, latest hoặc running (trạng thái kích hoạt, phê duyệt và phạm vi truy cập) hay trong lastBuild hoặc placed (trạng thái bản dựng và vị trí đặt widget) cũng vẫn làm view bị từ chối, và trạng thái phê duyệt hay phạm vi truy cập không bao giờ được thêm thành một trường mới ở cấp trên cùng, vì ứng dụng cũ hơn sẽ bỏ qua nó. Một ứng dụng dựng trước cách đọc khoan dung này, bao gồm mọi ứng dụng cũ hơn stopCode, sẽ từ chối cả view. Trong mọi trường hợp đó, ứng dụng nói mỗi bên đang chạy Clark phiên bản nào và, khi node mới hơn, đề nghị bạn cập nhật ứng dụng (xem Đọc câu trả lời của node); hãy giữ ứng dụng desktop ở cùng bản dựng với node mà nó kết nối tới, kể cả một node trên máy khác. Các yêu cầu và các phiên node lưu vẫn chặt. Một bản dựng cũ hơn đọc sessions.json có stopCode hay chosenFolderId sẽ chuyển cả tệp sang một bên và khởi động không có phiên nào; hãy chuyển nó về khi một bản dựng mới hơn chạy lại. Việc đọc không thay đổi gì.
DELETE/widget-dev/sessions/{id}–Ngừng theo dõi. Thế hệ đang chạy vẫn được cài và tiếp tục hiển thị ở nơi nó đã được đặt.
POST/widget-dev/sessions/{id}/rebuild–Dựng thư mục ngay khi không còn lần dựng nào khác đang chạy; nếu thư mục đang được tạo lại, lần dựng sẽ chờ thư mục xuất hiện trở lại. 409 SESSION_STOPPED với phiên đã dừng. Chỉ người dùng.
POST/widget-dev/sessions/{id}/place{ conversationId, widgetId? }Đặt widget đang chạy vào một hội thoại. Chỉ người dùng.
POST/widget-dev/chosen-folders/forget{ root }Thu hồi lựa chọn một thư mục của bạn: lựa chọn đó không còn cho Clark bắt đầu phiên trong thư mục đó, hay trong các thư mục bên trong nó, nữa. Trả { root, forgotten, stillCoveredBy? }; forgotten là false khi thư mục chưa được chọn, nên bấm lần hai cũng không sao. stillCoveredBy nêu một thư mục Clark vẫn được phát triển và chứa thư mục này (một thư mục khác bạn đã chọn, hoặc một giá trị workspace.roots bạn đã ghi), nên Clark vẫn có quyền ở đó cho tới khi thư mục đó cũng bị thu hồi. Các phiên đang chạy vẫn giữ nguyên. Chỉ người dùng.

Bắt đầu, dựng lại và đặt widget đều cài mã, nên relay WebSocket, clarkcant api và MCP từ chối chúng bằng 403 PERSON_ONLY. Thu hồi một thư mục đã chọn cũng bị từ chối như vậy: rút lại lựa chọn là việc của bạn, giống như chọn. Đọc và dừng một phiên vẫn dùng được ở mọi nơi. Trong hội thoại, tool develop_widget của Clark (start, choose, folders, status, rebuild, place, stop) điều khiển cùng các phiên đó; nó chỉ bắt đầu, dựng lại hay đặt widget trong lượt do người dùng gửi, không bao giờ trong lượt do một giao diện máy, một automation hay một node đã ghép cặp gửi. choose và folders chỉ cho bạn thấy thẻ develop (một thư mục để chọn, hoặc các thư mục bạn đã chọn, mỗi thư mục có nút Thu hồi); cả hai đều không bắt đầu hay thu hồi gì. choose đưa ra một lựa chọn lâu dài nên cũng chỉ chạy trong lượt do bạn gửi; folders chỉ thu hẹp quyền và chạy được trong mọi lượt.

Dừng mọi thứ

curl -s -X POST "$CLARKCANT_URL/stop" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"

Xoá hội thoại

Gõ “xoá hội thoại này”, hoặc yêu cầu bằng giọng nói. Clark dùng policy thực thi hiện tại của bạn: thực hiện yêu cầu rõ ràng, hỏi trước hoặc từ chối. Khi policy yêu cầu xác nhận, hội thoại hiện Giữ hội thoại và Xoá hội thoại. Không giữ bản sao để Hoàn tác vì mục tiêu là giải phóng tệp và hạn mức.

POST /conversations/{id}/delete nhận {} trên node gốc của hội thoại. Đây là hành động của người dùng: MCP, relay WebSocket và clarkcant api từ chối route này cùng route xác nhận bằng 403 PERSON_ONLY; app intent do agent yêu cầu cũng không được xoá.

  1. 202 trả về { deleted: false, decision: { kind: "needs-confirmation", intent, readBack, confirmationToken } } khi policy hỏi. Chưa xoá gì.
  2. Trả lời bằng POST /app-intents/confirm và { confirmationToken, decision: "granted" | "denied" }. Từ chối giữ nguyên mọi thứ. Duyệt trả về decision có intent.deletionPermit.
  3. Gửi { deletionPermit } tới route xoá ban đầu. Quyền này thuộc đúng người và hội thoại, hết hạn sau hai phút và chỉ dùng một lần. Policy và hoạt động được kiểm tra lại; từ chối mới luôn thắng quyền đã duyệt.

200 trả về { deleted: true, conversationId, attachments, artifacts, pendingFiles, readBack }. Các row của hội thoại, tệp đính kèm, tệp widget (kể cả tệp đã hoàn tất nhưng chưa đính kèm), grant và hàng đợi dọn tệp commit cùng nhau, với foreign key vẫn bật. Tệp vật lý bị xoá sau commit; byte còn dùng ở nơi khác được giữ. Tệp đang khoá chờ lần khởi động hoặc lượt dọn định kỳ tiếp theo; pendingFiles báo số tệp còn chờ.

409 trả về { deleted: false, decision: { kind: "refused", say } }, giải thích cái gì được giữ và bước tiếp theo. Task chưa kết thúc, đang tạm dừng hoặc chưa rõ kết quả, lượt trả lời, công việc nền và thao tác widget còn đang xử lý kết quả đều chặn việc xoá. Hãy hoàn tất, huỷ hoặc đối soát công việc đó rồi thử lại.

Bộ nhớ đã lưu, tài nguyên độc lập, nhật ký phiên và lịch sử kiểm toán/đồng bộ chỉ ghi thêm được giữ lại. Sau khi xác nhận thành công, ứng dụng bắt đầu hội thoại mới. Nếu mất phản hồi mạng thì chưa rõ kết quả: tải lại trước khi thử lại.

Báo lỗi hoặc đề xuất tính năng

Các route phía sau /report. Báo cáo chỉ tới repo chuẩn digitopvn/clarkcant: đích đến lấy từ cấu hình tin cậy của node, và không trường nào trong yêu cầu đổi được nó.

MethodPathBodyPhản hồi
POST/feedback/reports{ request, conversationId? }201 { draft, diagnostics }. Chuẩn bị và lưu bản nháp; chưa gửi gì.
GET/feedback/reports/{reportId}–{ draft, status, publication? }
POST/feedback/reports/{reportId}/publish{ conversationId, intent?: "send" | "check" | "send-anyway", answers? }{ publication, eligibility?, messageId, timeline }, kèm thẻ kết quả ghi vào cuộc trò chuyện. Chỉ người dùng.

request là { kind: "bug" | "feature", description, source, includeDiagnostics?, title?, subsystem?, bug?, feature?, evidence?, error?, philosophy? }, trong đó source là slash, chat, voice hoặc composer. Phần nào không ai nói tới thì bị bỏ khỏi issue. Đề xuất tính năng kèm mức phù hợp triết lý (aligned, aligned-with-constraints hoặc material-conflict); yêu cầu xung đột vẫn được gửi đúng như đã nói.

Gửi báo cáo là cú bấm của chính người dùng, nên relay WebSocket, MCP và clarkcant api từ chối bằng 403 PERSON_ONLY. Lần ghi là một hiệu ứng external-write và policy thực thi áp dụng cho nó. intent mặc định là send; answers nêu thẻ mà cú bấm nằm trên, để từ đó thẻ ấy hiện là đã dùng.

Tệp mà một widget giữ

Widget không bao giờ nhận được đường dẫn. Nó giữ một tệp dưới dạng artifactRef, { v, artifactId, kind, mimeType, sizeBytes, name, digest? }, và máy của bạn kiểm lại quyền của widget mỗi lần ref được dùng, nên một ref bị chép sang chỗ khác không mở được gì. Một quyền kéo dài 24 giờ kể từ lúc chọn tệp hoặc lần ghi gần nhất của widget. Sau đó, widget vẫn đọc được tệp do chính nó tạo và đã hoàn tất, còn tệp người dùng đã chọn thì phải được chọn lại. Một tệp còn đang ghi dở bị xoá 24 giờ sau lần ghi gần nhất. Mỗi tệp tối đa 25 MiB, và mỗi widget giữ tối đa 128 MiB trong 1 GiB của bạn. Phần đó tính các tệp widget đã tạo và những gì nó đính kèm từ các tệp ấy, nhưng không tính các tệp bạn đã chọn cho nó. Widget chỉ bỏ được tệp do chính nó tạo. Mọi câu trả lời là một ref, các byte, hoặc một lời từ chối có mã nói rõ điều gì sai. Tên tệp được gửi đi dưới cả hai dạng filename và filename* (RFC 6266), nên một tên có dấu được tải xuống đúng như khi viết.

Xoá hội thoại giải phóng tệp widget và grant của nó, kể cả tệp đã hoàn tất nhưng chưa đính kèm. Byte dùng chung được giữ; việc dọn tệp vật lý chờ database commit.

Các route của widget bắt đầu bằng /conversations/{id}/widgets/{instanceId}/artifacts, viết tắt là … ở bảng dưới.

MethodPathBodyGhi chú
GET/artifacts/{artifactId}–Artifact, kèm artifactRef của nó. Artifact của người khác trả về 404 ARTIFACT_NOT_FOUND.
GET/artifacts/{artifactId}/content–Các byte của một tệp đã hoàn tất. 409 ARTIFACT_NOT_FINALIZED khi tệp vẫn đang được ghi.
POST/artifacts/{artifactId}/export{ suggestedName? }Lưu thành: các byte được tải xuống dưới một tên tệp, không bao giờ là một đường dẫn. Tên giữ phần mở rộng theo kiểu của tệp. Relay WebSocket, MCP và clarkcant api từ chối nó với 403 PERSON_ONLY.
POST…{ mimeType, name? }Một tệp mới mà widget này được ghi. 201 { artifactRef }.
POST…/pick{ name, mimeType, contentBase64, accept? }Một tệp người dùng đã chọn, trao cho widget này. Bị các relay đó từ chối với 403 PERSON_ONLY.
GET…/{artifactId}/content?offset=&length=–{ artifactRef, offset, eof, contentBase64 }, tối đa 262.144 byte mỗi lần đọc.
POST…/{artifactId}/chunks{ offset, contentBase64 }Tối đa 262.144 byte, bắt đầu từ chỗ tệp đang kết thúc. 409 ARTIFACT_INSTANCE_QUOTA_EXCEEDED khi widget đã giữ 128 MiB.
POST…/{artifactId}/finalize–Chốt các byte sau khi kiểm chúng với kiểu đã khai báo.
POST…/{artifactId}/attach{ name? }201 { artifactRef, attachmentRef }. Tệp chờ trong ô soạn tin; người dùng gửi nó cùng tin nhắn tiếp theo. name đề xuất tên tệp cho tệp đính kèm. Node làm sạch tên đó, và cả tên riêng của artifact khi không có name: node bỏ phần đường dẫn cùng các ký tự không an toàn hoặc vô hình, giới hạn độ dài, và đặt phần mở rộng theo kiểu của tệp. Khi không còn gì dùng được, node dùng tên mặc định như untitled.png. Lần đính kèm đầu tiên quyết định tên: đính kèm lại cùng một tệp sẽ trả về đúng tệp đính kèm đó.
DELETE…/{artifactId}–Bỏ một tệp do widget này tạo: { discarded: true, artifactId }. Các byte của nó bị xoá khi không còn gì dùng tới. Tệp của widget khác, hoặc tệp người dùng đã chọn, trả về 403 ARTIFACT_NOT_CREATOR.

Các route này có trong /openapi.json. Chọn một tệp và Lưu thành là hành động của chính người dùng, nên widget phải nhờ host làm và không tự làm được. Thay tệp mà widget đã mở chỉ có trong ứng dụng desktop, chỉ bằng một tệp cùng kiểu, và nút này nêu tên cả hai tệp. Trên trình duyệt, Lưu thành là một lượt tải xuống, nên ứng dụng báo “Đã bắt đầu tải xuống” chứ không nói tệp đã được lưu.

Thao tác ghi tệp của widget từ bề mặt máy

Trên bề mặt máy (MCP, relay WebSocket, clarkcant api), năm thao tác ghi tệp của widget (tạo, ghi chunk, chốt, đính kèm, bỏ) đi qua chính sách thực thi của người dùng, và mọi lần đều được ghi nhật ký kiểm toán, không kèm byte. Mỗi lần là một hiệu ứng local-write. Ngoại lệ là bỏ một tệp không phải tệp đang ghi dở do chính bên yêu cầu đó bắt đầu: việc này có thể xoá bản duy nhất của người dùng, nên nó là destructive và được hỏi ở cả chế độ Có rào lẫn chế độ Tự chủ. Chính sách hoặc cho chạy, hoặc từ chối với 403 POLICY_REFUSED, hoặc hỏi. Khi người dùng đã chọn được hỏi về các lượt từ bề mặt máy (machineTurns: "ask"), mỗi lần ghi được quyết định như một lượt do bề mặt đó yêu cầu: khi đó một lần bỏ tệp destructive vẫn được hỏi kể cả khi có quy tắc cho chạy hiệu ứng destructive, và thẻ nói rõ ai đã yêu cầu.

Khi hỏi, một thẻ phê duyệt do host sở hữu xuất hiện trong hội thoại, bằng ngôn ngữ của người dùng, và bên gọi nhận 202 { outcome: "approval-required", approvalRequired: { approvalId } }. Chỉ người dùng quyết định được thẻ đó. Hỏi lại đúng việc đó sẽ nhận lại thẻ đang chờ. Quá 8 thẻ đang chờ từ một bề mặt trong một hội thoại, câu trả lời là 429 APPROVALS_PENDING. Số đếm này nằm trong bộ nhớ, nên khởi động lại sẽ đặt lại nó. Mỗi thẻ là cho một tệp, không bao giờ cho từng chunk, và không bao giờ chứa byte.

Duyệt một lệnh tạo, hoặc quyền ghi vào một tệp đang ghi dở, sẽ cấp quyền ghi 15 phút trên đúng tệp đó: các chunk và lệnh chốt chạy mà không cần thẻ khác. Quyền kết thúc khi tệp được chốt, bị bỏ hoặc hết hạn. Qua relay WebSocket, chỉ đúng kết nối đã yêu cầu giữ quyền này. Lời gọi MCP và các lần chạy clarkcant api không có danh tính riêng của từng client, nên ở đó mọi client của bề mặt đó đều giữ quyền, không chỉ client đã yêu cầu. Thẻ và biên nhận nói rõ điều này.

Job chạy lâu của package

Một capability của package có công việc kéo dài hơn một lần bấm khai báo "execution": { "kind": "job", "version": 1 } trong tools facet. Một lần bấm vào nó không chờ service: api.actions.invoke trả về một JobRef, là một id job_… không mang nghĩa, và máy của bạn chạy lời gọi ở nền tối đa 30 phút. Widget giữ JobRef trong state của nó, nên vẫn theo dõi được đúng job đó sau khi được mở lại.

const jobId = await api.actions.invoke("binding_notes_export", { steps: 12, stepMs: 1500 }, invocationId);
await api.state.update((state) => ({ ...state, exportJob: jobId }), { exportJob: jobId });
const stop = api.jobs.subscribe(jobId, (job) => render(job));

api.jobs.get(ref) đọc trạng thái của job (queued, running, waiting, completed, failed hoặc cancelled), tiến độ, output, lỗi và các tệp kết quả. api.jobs.subscribe(ref, handler) kiểm tra mỗi giây, chỉ chuyển đi những thay đổi, và tự dừng khi job kết thúc. api.jobs.cancel(ref) dừng job. Tiến độ chỉ là những gì chính service đã báo, và tệp kết quả đến dưới dạng artifactRef, không bao giờ là đường dẫn.

Liệt kê các job của widget (jobs.list@1). api.jobs.list() trả về các job do chính các nút của widget này khởi động, mới nhất trước và tối đa 20, kể cả các job Clark hay giọng nói khởi động qua cùng nút đó, nên widget có thể hiện công việc không bắt đầu từ một cú bấm. Việc liệt kê ra đời sau jobs@1 và được cung cấp như một extension riêng, jobs.list@1, bên cạnh nó; api.jobs.canList() cho biết ứng dụng có cung cấp hay không, và api.jobs.list() từ chối mà không gửi gì khi ứng dụng không cung cấp. Widget có liệt kê thì kiểm tra trước: không có danh sách, nó hiện các job được khởi động trong lúc nó đang mở và nói rõ rằng các job trước đó không được hiện. Một job trong danh sách có cùng các trường như job đọc bằng api.jobs.get.

Một job thất bại có thể mang chính lời của service. Khi service báo lỗi, error của job trích lời đó bên trong câu của chính node: The package service reported an error: “…”. Its effect may have happened; review before retrying. Phần trong ngoặc kép là của service, và có thể là của provider mà service gọi: các ký tự điều khiển và ký tự định dạng vô hình (kể cả ký tự đảo chiều bidi) bị loại bỏ và phần đó bị cắt ở 400 ký tự, nhưng ngoài ra không có gì bảo đảm cho nó. Hãy hiển thị nó như lời service đã nói, bên trong một câu của riêng bạn. Khoá provider mà provider gửi lại đã được thay bằng [redacted] ở đó (cách một service tới provider của nó).

JobRef là con trỏ, không phải quyền. Máy của bạn chỉ trả lời widget có chính nút bấm đã khởi động job, trong cùng hội thoại, với cùng phiên bản package và capability; mọi trường hợp khác, kể cả một ref bị chép sang widget khác, đều là 404 JOB_NOT_FOUND, giống hệt một job chưa từng tồn tại. Nếu chế độ thực thi của bạn cần hỏi trước khi capability chạy, lần bấm sẽ hiện thẻ phê duyệt của ứng dụng trước, và job chỉ bắt đầu sau khi bạn phê duyệt ở đó.

Một job chạy tối đa 30 phút; quá thời hạn đó nó kết thúc ở trạng thái thất bại. Trong lúc chạy, nó nằm trong danh sách công việc đang chạy của node (GET /work), và việc dừng nó ở đó (POST /work/{id}/cancel), Dừng khẩn cấp và việc tắt node đều huỷ nó. Nút Dừng của hội thoại kết thúc câu trả lời, không kết thúc một job đã chạy, giống như các công việc nền khác. Vì service có thể đã làm xong việc trước khi nhận được lệnh huỷ, job sẽ báo rằng nó “có thể đã hoàn tất tác động” thay vì khẳng định không có gì xảy ra. Job vẫn đang chạy khi node khởi động lại được đánh dấu thất bại và không bao giờ tự chạy lại. Khi job kết thúc, hội thoại và hộp thư đều báo, nêu tối đa ba tệp kết quả. Hội thoại còn job đang chạy thì không xoá được cho tới khi job kết thúc hoặc bị huỷ.

MethodPathBodyGhi chú
GET/conversations/{id}/widgets/{instanceId}/jobs–{ jobs: [...] }, mới nhất trước và tối đa 20: các job do chính các nút của widget này khởi động. Mỗi mục có cùng các trường như job của route một job và qua cùng bước kiểm tra chủ sở hữu. Instance không thuộc hội thoại là 404 INSTANCE_UNKNOWN. Trong widget, đây là api.jobs.list().
GET/conversations/{id}/widgets/{instanceId}/jobs/{jobId}–{ job: { jobId, status, progress?, resultRefs, output?, error?, createdAt, startedAt?, endedAt? } }.
POST/conversations/{id}/widgets/{instanceId}/jobs/{jobId}–Huỷ job: 202 { accepted, jobId }. Job đã kết thúc trả về 409 JOB_NOT_RUNNING và vẫn đọc được.

Các route này có trong /openapi.json. Node không chạy được job trả về 503 JOB_UNAVAILABLE. POST /stop đếm các job đã huỷ trong stopped.jobs. Theo thiết kế, các route này, kể cả route liệt kê, mở cho client máy như client MCP hay relay, không chỉ cho màn hình của chính bạn: một client máy có thể liệt kê các job của một instance, output của chúng và các artifactRef mà không cần biết trước JobRef nào. Nó không biết thêm gì mà nó không đọc được từng job một, và không đọc được byte của tệp qua các route này.

Lần bấm đọc điều widget đang hiển thị

Một widget cách ly mô tả điều nó đang hiển thị bằng api.semantic.publish(summary, selectedIds, values?). Ứng dụng gửi lần publish cuối của một loạt sau 250 ms, và gửi các lần publish lần lượt từng cái, đúng thứ tự. Một binding agent có thể đọc mô tả đó khi được bấm, qua contextRefs của nó (selection, widget), nên một lần bấm ngay sau một lần publish không được chạy dựa trên mô tả trước đó.

Trước khi chạy lần bấm như vậy, ứng dụng gửi lần publish còn đang chờ ổn định và chờ đến khi máy của bạn đã giữ mô tả được publish trước lần bấm, hoặc một mô tả mới hơn. Các lần publish sau lần bấm vẫn được gửi như thường nhưng không được chờ, nên một widget publish liên tục không thể giữ lần bấm lại. Các lần bấm khác chỉ chờ lần publish còn đang chờ ổn định, hoặc lần mà máy của bạn vừa từ chối.

Thời gian chờ có giới hạn: mỗi lần gửi bị bỏ sau 5 giây và toàn bộ việc chờ sau 8 giây. Mô tả bị máy của bạn từ chối được gửi lại một lần. Nếu vẫn hỏng, hoặc hết thời gian chờ, api.actions.invoke bị từ chối kèm câu của ứng dụng (“Chưa gửi kịp cho Clark điều widget đang hiển thị, nên hành động này chưa chạy…”) và lần bấm không chạy. Không có gì trong widget bị thay đổi, và người dùng có thể bấm lại. Hãy hiện lời từ chối đó ở chỗ người dùng đã bấm. Trình soạn thảo văn bản mẫu làm đúng như vậy cho nút viết lại của nó.

Hành động Clark nhờ một widget thực hiện

Một widget cách ly có thể cung cấp cho Clark những hành động do chính nó thực hiện, chẳng hạn định dạng các ô đang chọn: widget khai báo chúng trong offeredActions và xử lý từng hành động bằng api.actions.offer(name, handler) (actions.perform@1). Khi đó Clark có thể nhờ một widget đang hiện trên màn hình thực hiện một trong các hành động đó, qua chính sách thực thi của bạn, và chỉ màn hình đang hiện widget mới thực hiện nó. Clark không bao giờ tự ghi vào widget và không bao giờ tự duyệt hành động. Khi widget đang mở trong cửa sổ desktop riêng, ứng dụng desktop chuyển yêu cầu của Clark tới cửa sổ đó và báo lại câu trả lời của widget, nên hành động vẫn chạy ở đó, dù bạn nhờ bằng chữ hay bằng giọng nói. Cửa sổ không giữ thông tin xác thực nào: chính ứng dụng desktop gửi câu trả lời. Ứng dụng desktop cũ hơn thì từ chối yêu cầu mà không có gì được gửi tới widget, và Clark được báo là cần gắn widget lại trước.

Khi chính sách thực thi muốn hỏi trước, Clark đặt một thẻ phê duyệt vào cuộc trò chuyện, và không có gì được gửi cho widget cho tới khi bạn phê duyệt. Thẻ hiện toàn bộ dữ liệu widget sẽ nhận; một hành động có dữ liệu quá dài để hiện đầy đủ (hơn 1.200 ký tự) bị từ chối thay vì chỉ hiện một phần. Nếu Clark yêu cầu lại cùng hành động với cùng dữ liệu trong lúc thẻ của nó còn chờ, bạn nhận lại đúng thẻ đó, không có thẻ thứ hai, và một cuộc trò chuyện giữ tối đa 8 thẻ hành động đang chờ, dù có bao nhiêu bề mặt đã yêu cầu. Phê duyệt sẽ hỏi widget trên màn hình bạn phê duyệt; phê duyệt từ hộp thư, hoặc từ một trang không hiện widget, được ghi là “đã duyệt nhưng không thực hiện”, và không có gì được gửi. Thực hiện một hành động được cung cấp là thao tác ghi cục bộ, nên riêng lựa chọn được hỏi về lượt của chương trình không làm nó bị hỏi; một quy tắc hoặc chế độ có hỏi thì sẽ hỏi. Ai đã yêu cầu được ghi trên thẻ phê duyệt và trong nhật ký kiểm toán, kể cả sau khi bạn duyệt.

Dành cho tác giả widget. Để từ chối một hành động được cung cấp, hãy throw api.actions.refuse("CODE", "lý do") trước khi thay đổi bất cứ điều gì. Mọi lỗi khác, kể cả lời từ chối của chính SDK, nghĩa là widget có thể đã thay đổi điều gì đó: Clark nói rằng không biết hành động đã có hiệu lực hay chưa và không thử lại.

Kết quả có cấu trúc từ một service

Tool của một service trong gói có thể liệt kê outputSchema và trả structuredContent bên cạnh phần chữ, như MCP 2025-06-18 mô tả. Node của bạn giữ schema đó trên capability khi nó là một JSON schema object có type: "object", dài tối đa 16.384 ký tự, không chứa pattern nào bị node từ chối vì việc kiểm tra nó có thể kéo dài không giới hạn; schema khác bị bỏ, log của node ghi lý do, và tool vẫn được nạp. title, _meta và các gợi ý annotation ngoài những gợi ý Clark đọc được chấp nhận rồi bỏ qua. Không điều gì service liệt kê, kể cả schema, mô tả, title hay annotation, hạ được điều chính sách thực thi của bạn quyết định: effect category của capability là loại mà manifest khai báo, và những gì service liệt kê chỉ có thể nâng nó lên.

structuredContent của một kết quả chỉ được giữ, dưới dạng bản sao, khi nó là object JSON thuần sâu tối đa 32 tầng, có tối đa 16.384 giá trị, không có khoá __proto__, constructor hay prototype, JSON của nó dài tối đa 65.536 ký tự, và nó khớp outputSchema mà tool khai báo. Nếu không, nó bị bỏ, phần chữ của service được giữ, và phần chữ ghi lý do. Model vẫn đọc phần chữ của service; service không trả phần chữ thì JSON của giá trị là phần chữ.

Một lần bấm binding invoke của widget mà gọi tới capability của service trả 200 { outcome: "done", output, structuredContent? } cùng các trường thường có. output là phần chữ service trả về, như trước, còn structuredContent là giá trị được giữ. Một invocationId lặp lại được trả lại đúng giá trị đó, và client bỏ qua trường này thấy đúng phản hồi như trước. Tool invoke_capability của Clark và lệnh nói đi tới cùng lời gọi capability và nhận cùng giá trị. invoke_capability mang nó trong một kết quả có dạng CallToolResult của MCP, cho chương trình gọi tool; ClarkCant chưa chạy chương trình như vậy, nên hiện chưa có model hay script nào đọc nó ở đó.

Giá trị này được phân loại cùng phần chữ, ở dạng JSON và theo từng chuỗi, và bị giữ lại không cho model thấy cùng phần chữ (xem khi một tin nhắn không được gửi). Nó là dữ liệu của service: không bao giờ thành chỉ dẫn, thẻ phê duyệt hay widget. Tệp vẫn được trả về dưới dạng resource và lưu thành tệp của cuộc trò chuyện, không đặt trong structuredContent.

Tài nguyên mà một gói được chạy cùng

Các service của một gói chạy trong một container trên máy của bạn. Gói xin kích thước cho container đó bằng cách nêu tên một resource profile trong manifest, không bao giờ bằng con số:

"resources": { "version": 1, "profile": "interactive-heavy" }

Node của bạn giữ bảng profile và quyết định cấp gì. Gói không nêu profile nào chạy với interactive-light, đúng giới hạn mà mọi service đã chạy trước khi có profile, từng giá trị một, nên một gói có sẵn vẫn chạy y như trước.

ProfileBộ nhớ / CPU / tiến trình / /tmpMỗi lệnh gọiMỗi jobSố job cùng lúcKhi ra khỏi màn hình
interactive-light (mặc định)256 MiB / 1 / 128 / 16 MiB60 giây30 phút4Bị gỡ khỏi màn hình
interactive-heavy1 GiB / 2 / 256 / 64 MiB120 giây30 phút2Bị gỡ khỏi màn hình
media-workstation4 GiB / 4 / 512 / 512 MiB300 giây2 giờ1Có thể tiếp tục phát
background-compute2 GiB / 2 / 256 / 256 MiB60 giây4 giờ2Bị gỡ khỏi màn hình

Mọi profile đều chạy không có mạng (--network none) và với /tmp ở chế độ noexec. Profile đặt bộ nhớ, số CPU, giới hạn tiến trình và kích thước /tmp của container, thời hạn của lệnh gọi và của job, và số job chạy cùng lúc. Service và job vẫn chạy dù widget của chúng có đang hiện trên màn hình hay không. Tệp lớn nhất mà một service trả về vẫn bằng giới hạn tệp đính kèm, nên luôn đính kèm được vào hội thoại.

Node của bạn quyết định theo thứ tự sau:

  1. Không bao giờ cấp GPU: node không chuyển GPU vào container.
  2. interactive-light luôn được cấp.
  3. Lời từ chối của policy thực thi luôn thắng.
  4. Một profile không được cấp khi nó cần nhiều CPU hơn số container engine báo, hoặc hơn một nửa bộ nhớ của engine. Với Docker Desktop, đó là dung lượng của máy ảo Linux của nó.

Một profile không cấp được thì không bao giờ bị đổi sang profile nhỏ hơn. Thay vào đó gói ở trạng thái suy giảm: các service của nó không khởi động, và mỗi capability hiện lý do. Cài đặt → Tiện ích hiện profile bên cạnh mỗi gói đã cài: các giới hạn khi được cấp, hoặc “Đã xin … nhưng không được cấp: …” khi không.

Podman rootless không được uỷ quyền các controller cgroup v2 chấp nhận giới hạn bộ nhớ và CPU nhưng không áp dụng chúng. Node của bạn vẫn cấp profile ở đó, và chi tiết gói ghi rằng container engine ở đây không áp giới hạn bộ nhớ và CPU, thay vì khẳng định có giới hạn.

Một widget bị gỡ khỏi màn hình khi nó cuộn ra ngoài vùng nhìn thấy. Chỉ widget có gói được cấp media-workstation mới có nút bật “Tiếp tục phát khi cuộn đi” trong khung do chính ứng dụng vẽ. Khi bật, widget vẫn được giữ lại và ứng dụng báo “tên widget vẫn đang chạy ngoài màn hình”. Nút này tắt với mỗi lần widget được gắn mới, widget không tự bật được, và nút Dừng vẫn kết thúc nó.

Cách một service gọi tới provider của nó

Container của service vẫn ở --network none, và service không bao giờ giữ khoá của provider. Tools facet của gói khai báo các khoá nó cần và các origin nó được gọi tới, mỗi thứ kèm mục đích:

"egress": {
  "version": 1,
  "secrets": [{ "name": "LOOKUP_API_KEY", "purpose": "Signs the lookups in with the provider." }],
  "origins": [{
    "origin": "https://api.example.com",
    "purpose": "Looks up the words you ask about.",
    "credential": { "secret": "LOOKUP_API_KEY", "header": "authorization", "scheme": "bearer" }
  }]
}

Node của bạn là MCP client của từng service của gói, qua stdio. Với service có khai báo egress, lệnh initialize của node đề nghị capabilities.experimental["clarkcant/egress"] với version: 1. Khi đó service gửi cho node request clarkcant/egress.fetch với { version: 1, url, method?, headers?, body? } trên cùng kết nối, và chính node thực hiện request HTTP:

Lời từ chối là lỗi JSON-RPC từ -32010 tới -32018: origin chưa khai báo, không có lệnh gọi đang chạy, khoá không dùng được, quá lớn, không kết nối được provider, đã dừng, phương thức không được các lệnh gọi đang chạy cho phép, quá nhiều request, và origin mà node này không gọi tới. -32019 là request bị từ chối vì một lệnh gọi đang chạy giữ một tệp bạn đã chọn (tệp mà một service đọc). Mỗi request được ghi kiểm toán là egress với gói, phương thức, origin, tên khoá, trạng thái và kết quả, không bao giờ ghi đường dẫn, body hay giá trị. Phương thức này chỉ nằm giữa node và các service của chính nó; nó không có trên POST /mcp.

Cho tới khi khoá đã khai báo được lưu, các capability của gói được xem là chưa đăng nhập (authenticated: false) kèm lý do, ví dụ “the secret LOOKUP_API_KEY has not been provided on this node”. Một lần bấm, agent và giọng nói đều bị từ chối với 409 CAPABILITY_NOT_AUTHENTICATED. Đây là trạng thái “cần đăng nhập” của một service; trạng thái vòng đời widget needs_auth không được đặt cho nó. Lưu khoá cho package:<id> bằng POST /credentials sẽ đăng nhập service mà không cần khởi động lại, và xoá khoá sẽ đăng xuất nó. Cả hai đều chỉ dành cho người dùng: 403 PERSON_ONLY trên bề mặt máy, nên bạn tự lưu khoá trong Cài đặt hoặc bằng token của chính bạn. Khoá lưu cho consumer command: không được dùng cho egress, nên hãy lưu một khoá riêng cho gói.

Chưa có mạng qua proxy cho service cần socket thô. Cho container một mạng sẽ làm yếu một mặc định cách ly.

Tệp mà một service đọc

Một service có thể làm việc trên tệp mà một widget giữ mà không bao giờ nhận đường dẫn hay handle tới tệp đó. Một capability nêu các trường đối số mang id artifact trong facet tools của nó:

{ "tool": "render_audio", "ref": "com.example.media.render@1", "effectCategory": "read",
  "execution": { "kind": "job", "version": 1 },
  "inputArtifacts": { "version": 1, "fields": ["source"] } }

Một lệnh gọi nêu tệp ở một trong các trường đó chỉ có thể đến từ nút của chính instance widget đang giữ tệp. Cùng lệnh gọi đó từ Clark, giọng nói, MCP hay CLI bị từ chối với 403 ARTIFACT_INPUT_REFUSED, vì không ai trong số đó giữ quyền của widget. Trước khi gửi lệnh gọi, node của bạn kiểm tra từng tệp được nêu:

Lệnh gọi bị từ chối không gửi gì tới service. Khi chính sách thực thi của bạn hỏi trước một lệnh gọi như vậy, thẻ phê duyệt nêu widget và nút mà lần bấm đến từ đó, và điều bạn phê duyệt bao gồm cả hai. Phê duyệt sẽ chạy lệnh gọi như chính lần bấm đó: node kiểm tra lại rằng hội thoại vẫn giữ widget và nút vẫn gọi capability này, rồi thực hiện mọi bước kiểm tra ở trên. Thẻ có widget đã mất bị từ chối với APPROVAL_STALE.

Các giới hạn đến từ profile đã được cấp, không bao giờ từ manifest. Manifest nêu trường, không nêu kích thước, nên không thể nâng giới hạn nào:

ProfileTệp đầu vàoĐộ dài media
interactive-light8 MiB2 phút
interactive-heavy16 MiB10 phút
media-workstation25 MiB2 giờ
background-compute25 MiB1 giờ

Node của bạn cung cấp việc đọc tệp trong initialize của MCP dưới dạng capabilities.experimental["clarkcant/artifacts"]: { version: 1, methods: ["clarkcant/artifacts.read"], chunkBytes: 262144, maxInputBytes, maxMediaSeconds, maxResultBytes }. Trong lúc lệnh gọi diễn ra, và chỉ khi đó, service gửi clarkcant/artifacts.read với { version: 1, artifactId, offset, length } và nhận lại { artifactId, offset, bytes, eof, sizeBytes, mimeType }, với byte ở dạng base64:

Công cụ dựng media mẫu được xây trên cơ chế này: widget của nó chọn một đoạn WAV, và service của nó đọc đoạn đó theo từng phần dưới profile background-compute.

Kết nối một tài khoản

Một service làm việc trên tài khoản của bạn ở một provider, chẳng hạn danh sách công việc hay lịch của bạn, khai báo một connection trên facet tools của nó. Node của bạn làm mọi việc chạm tới thông tin xác thực của tài khoản: service thấy câu trả lời của provider và widget thấy trạng thái. Không bên nào giữ access token, refresh token hay mã ủy quyền, và trang web hay container của service cũng vậy.

"connection": {
  "version": 1,
  "provider": "fake.tasks",
  "displayName": "Fake Tasks (test fixture)",
  "flow": "oauth-pkce",
  "authorization": {
    "authorizationEndpoint": "http://127.0.0.1:8880/oauth/authorize",
    "tokenEndpoint": "http://127.0.0.1:8880/oauth/token",
    "revocationEndpoint": "http://127.0.0.1:8880/oauth/revoke",
    "clientId": "connected-app-dev"
  },
  "scopes": [
    { "scope": "tasks.read", "purpose": "Lists your tasks." },
    { "scope": "tasks.write", "purpose": "Renames a task when you ask." }
  ],
  "endpoints": ["http://127.0.0.1:8880"],
  "probe": { "url": "http://127.0.0.1:8880/api/me" }
}

Luồng duy nhất là authorization code với PKCE, nên một package không bao giờ mang client secret, và client id là công khai. Mọi URL phải là HTTPS, trừ địa chỉ loopback. Probe phải nằm trên một endpoint đã khai báo. Một package khai báo tối đa một kết nối, và một endpoint không thể đồng thời là một origin egress, nên mỗi origin chỉ có một thông tin xác thực. Mỗi capability nêu các scope nó cần trong requiredScopes, và mỗi scope đó phải là scope mà kết nối xin.

Trong Cài đặt. Cài đặt → Tiện ích hiện tài khoản của từng package: trạng thái, các scope đã cấp và lý do nó chưa dùng được đầy đủ. Nút Kết nối hiện khi chưa kết nối, còn lại là Kết nối lại, và Thu hồi hiện khi đã kết nối hoặc kết nối một phần. Trong lúc bạn đăng nhập ở provider, Cài đặt báo đang chờ và đọc lại trạng thái mỗi 1,5 giây, tối đa năm phút.

Một capability, một nhật ký kiểm toán. Kết nối không thay đổi cách một capability chạy. Nút của widget, invoke_capability của Clark và một câu lệnh nói vẫn tới cùng capability, cùng chính sách thực thi của bạn, cùng thẻ phê duyệt của chính ứng dụng và cùng nhật ký kiểm toán. Một lần ghi không nhận được câu trả lời trước hạn chót được ghi là chưa rõ kết quả và không được thử lại.

MethodĐường dẫnTrả vềTừ chối
GET/packages/{id}/connection200 { connection }: trạng thái ở trên, không bao giờ có token.404 NOT_INSTALLED, 404 NO_CONNECTION, 409 MANIFEST_UNREADABLE, 503 CONNECTIONS_UNAVAILABLE
POST/packages/{id}/connection200 { authorizationUrl }. Chỉ người dùng.Các mã ở trên, cộng thêm 403 PERSON_ONLY, 409 CONNECT_ON_THIS_MACHINE, và 409 ENDPOINT_REFUSED cho địa chỉ provider loopback hoặc mạng riêng trên một node khởi động không có CC_EGRESS_ALLOW_PRIVATE_NETWORK=1
POST/packages/{id}/connection/revoke200 { connection }, đã ở trạng thái revoked.Như với GET
GET/connections/callback/{packageId}Công khai. 200 “Connected to …”, hoặc 400 “Not connected” kèm điều gì thất bại và rằng chưa có gì được kết nối.503 khi node không kết nối tài khoản

GET /packages cũng mang trạng thái connection của từng package đã cài. Thu hồi không giới hạn cho người dùng: bất kỳ giao diện nào giữ token của node bạn đều có thể thu hồi, một cách có chủ ý, vì thu hồi chỉ thu hẹp quyền truy cập.

Ứng dụng kết nối tài khoản mẫu chứng minh điều này với fake connector của nó, một fixture kiểm thử và phát triển, không phải provider thật. Chưa có provider thật nào (digitopvn/clarkcant#333). Ứng dụng desktop chỉ mở địa chỉ HTTPS trong trình duyệt hệ thống, nên một provider trên địa chỉ http loopback, như fake connector, được kết nối từ trình duyệt. Chỉ luồng authorization code với PKCE được xây dựng; nhiều tài khoản cho một package, hay một kết nối dùng chung giữa các package, thì chưa. Cài lại một package sau khi gỡ hiện để service của nó ở trạng thái không hoạt động, còn khôi phục thì vẫn được (digitopvn/clarkcant#400).

Token trình duyệt cho widget (tokens@1)

Một số SDK của nhà cung cấp chỉ chạy được với token trong trình duyệt. UI facet của gói có thể khai báo các provider mà widget cần token, tối đa 8 provider, mỗi provider 16 scope:

"browserTokens": {
  "version": 1,
  "providers": [{ "provider": "example.maps", "scopes": ["tiles:read"], "purpose": "Draws the map tiles." }]
}

Chỉ widget có gói đã khai báo token trình duyệt mới được đề nghị tokens@1 trong init.extensions:

if (api.tokens.available()) {
  const token = await api.tokens.request({ provider: "example.maps", scopes: ["tiles:read"], ttlSeconds: 300 });
  sdk.setAccessToken(token.value); // { provider, value, scopes, expiresAt }
}

Token gắn với một instance widget và một phiên. Mỗi lần widget được gắn là một phiên riêng, một id ngẫu nhiên do ứng dụng giữ, và token bị thu hồi khi lần gắn đó kết thúc, khi gói bị gỡ, quay về bản cũ hoặc cập nhật sang mã mới, và khi node dừng, ở nơi provider hỗ trợ thu hồi. Token chỉ được cấp khi provider và mọi scope đều đã khai báo, node của bạn có adapter cho provider đó có thể tạo token giới hạn theo đúng các scope ấy, và thời hạn nằm trong 30–3600 giây và trong mức tối đa của chính provider (900 giây khi không xin thời hạn). Request bị từ chối chứ không bao giờ bị thu hẹp. Mỗi phiên giữ tối đa 8 token; token thứ chín thu hồi token cũ nhất.

Node của bạn chỉ giữ id token của provider, và ghi kiểm toán provider, instance và kết quả là browser-token, không bao giờ ghi giá trị. SDK và ứng dụng đều từ chối, với TOKEN_NOT_ALLOWED, một lần cập nhật state, semantic publish, action, ghi tệp hoặc liên kết ngoài có chứa token đúng như khi được cấp. Lớp bảo vệ này chỉ cố gắng hết mức: mã của widget giữ giá trị token, nên điều giới hạn rò rỉ là token có scope hẹp, thời hạn ngắn và bị thu hồi khi widget đóng.

MethodPathBodyGhi chú
POST/conversations/{id}/widgets/{instanceId}/browser-tokens{ session, request: { provider, scopes, ttlSeconds? } }{ token: { provider, token, scopes, expiresAt } }. Chỉ người dùng: ứng dụng xin thay cho widget mà nó đã gắn.
DELETE/conversations/{id}/widgets/{instanceId}/browser-tokens/{session}–{ ended: true, revoked }. Request sau đó cho phiên này là 409 TOKEN_SESSION_ENDED.

Các route này có trong /openapi.json. Lời từ chối: 403 TOKEN_PROVIDER_NOT_DECLARED hoặc TOKEN_SCOPE_NOT_DECLARED, 409 TOKEN_PACKAGE_NOT_ACTIVE hoặc TOKEN_SESSION_ENDED, 422 TOKEN_PROVIDER_UNSCOPED, TOKEN_SCOPE_NOT_SUPPORTED hoặc TOKEN_TTL_TOO_LONG, 502 TOKEN_ISSUE_FAILED và 503 TOKEN_PROVIDER_UNAVAILABLE. ClarkCant chưa kèm adapter provider nào, nên hiện mọi request đều là 503 TOKEN_PROVIDER_UNAVAILABLE.

Những gì một gói chạm tới, hiện trước khi cài

Một mục trong thư mục gói nêu phạm vi của gói trong declaredReach, { origins, secrets, browserTokens, connections }; trang gói không có trường này nghĩa là gói không chạm tới gì. Trước khi cấp bất cứ quyền gì, thẻ thư mục gói trong hội thoại, câu hỏi cài đặt trong hộp thư và chi tiết gói trong Cài đặt → Tiện ích liệt kê từng origin kèm mục đích, từng khoá theo tên kèm mục đích (không bao giờ hiện giá trị), từng provider token trình duyệt kèm scope và mục đích, và từng kết nối tài khoản kèm provider, scope và endpoint.

Node đọc một mục trong thư mục gói có những trường nó không biết bằng cách bỏ qua các trường đó thay vì từ chối cả mục. Thẻ thư mục gói khi đó cho biết có bao nhiêu thông tin mà phiên bản Clark này không đọc được, và nêu tên những trường có tên là định danh thuần; một bản Clark mới hơn sẽ hiển thị chúng.

Một artifact có manifest khai báo phạm vi khác với những gì trang gói đã hiện sẽ bị từ chối với 409 DECLARED_REACH_MISMATCH trước khi có bất cứ điều gì được ghi lại, nên những gì bạn đồng ý đúng là những gì bạn nhận. Resource profile được hiện trong chi tiết gói sau khi gói đã cài.

Những gì một bản cập nhật cho thấy. Thông báo cập nhật gói, và câu hỏi cài đặt mà một bản cập nhật đưa ra khi chế độ thực thi hỏi trước, so sánh trang gói của phiên bản mới với manifest của phiên bản đang cài và mang reachChange: từng origin, khoá, scope token trình duyệt, scope tài khoản và endpoint tài khoản mà phiên bản mới thêm vào hay bỏ đi; từng origin mà một khoá giờ được gửi tới hoặc không còn được gửi tới; một yêu cầu GPU, thứ node này không bao giờ cấp; từng giới hạn tài nguyên bị thay đổi, kèm cả hai giá trị; và cách gói hoạt động khi khuất màn hình nếu cách đó thay đổi. Kết luận là wider khi có thứ được thêm vào, có giới hạn tăng lên hoặc cách hoạt động khi khuất màn hình chuyển từ suspend sang authorized-playback, narrower khi chỉ có thứ bị bỏ đi hoặc hạ xuống, và unchanged trong các trường hợp còn lại. Nó không có mặt khi gói chưa được cài, và là { verdict: "unknown" }, hiện thành lời báo không so sánh được với bản đang cài, khi không đọc được manifest đang cài hoặc trang gói mới. Mỗi danh sách giữ tối đa 32 mục và đếm phần còn lại. Nó chỉ giúp bạn quyết định chứ không quyết định gì: một bản cập nhật vẫn do chính sách thực thi quyết định như mọi lần cài.

Các node đã ghép cặp

Hai node ClarkCant có thể được ghép cặp với nhau, ví dụ laptop của bạn và một máy chủ. Một node đã ghép cặp có thể báo cho node kia biết chuyện gì đã xảy ra, đặt một thông báo vào hộp thư của chủ node kia, và giao cho nó một việc, mỗi thứ chỉ trong phạm vi mà chủ của node nhận cho phép.

Các route này dùng cùng token nhưng chưa có trong /openapi.json và có thể thay đổi. Xác nhận một peer và viết một grant là quyết định của chủ node: relay WebSocket, MCP và clarkcant api từ chối chúng với 403 PERSON_ONLY. Hiện nay các node nói chuyện với gateway của nhau bằng HTTP thuần, nên một node phải truy cập được qua HTTP mới ghép cặp được, và con người kiểm khoá của node kia bằng cách so fingerprint.

Ghép cặp hai node

Một node mời, node kia nhận lời mời, rồi một người xác nhận trên cả hai node. Khi cả hai chưa cùng xác nhận, peer vẫn đang chờ: không có gì được gửi tới nó và tin nhắn của nó bị từ chối.

MethodPathBodyGhi chú
POST/peers/invites{ endpoint }Trên node mời, kèm địa chỉ mà node kia sẽ dùng để gọi tới. 201 { invite } gồm inviteId, issuerNodeId, endpoint, fingerprint và expiresAt. Chỉ dùng một lần, có hiệu lực 10 phút.
POST/peers/claim{ inviteId, node }Node nhận lời mời gọi route này trên node mời, không cần token của node đó. node là { nodeId, label, endpoint, publicKey, fingerprint, tokenHash } của node nhận lời mời. 200 { issuer, tokenHash }, và node nhận lời mời được ghi lại ở trạng thái chờ. 404 INVITE_UNKNOWN; 409 INVITE_EXPIRED hoặc INVITE_ALREADY_CLAIMED; 400 FINGERPRINT_MISMATCH khi fingerprint không khớp với khoá được đưa ra.
POST/peers/record{ node }Trên node nhận lời mời: issuer trong câu trả lời của lượt nhận lời mời, kèm endpoint bạn đã dùng để gọi tới nó và tokenHash trong câu trả lời. 201 { nodeId, trustedAt }, vẫn đang chờ (trustedAt là null).
GET/peers–nodeId, endpoint, fingerprint, pairedAt, trustedAt và revokedAt của từng peer.
POST/peers/{nodeId}/confirm–Quyết định của một người, sau khi so fingerprint: lời mời mang fingerprint của node mời, còn GET /node cho thấy fingerprint của chính từng máy. 200 { nodeId, trusted: true }; 404 PEER_UNKNOWN.
POST/peers/{nodeId}/revoke–Kết thúc việc ghép cặp trên node này: node không nhận thêm tin nhắn nào từ peer đó và không gửi gì cho nó nữa. 200 { nodeId, revoked: true }; 404 PEER_UNKNOWN.

Không có token nào đi qua mạng khi ghép cặp. Mỗi node đưa cho peer một token dẫn xuất từ localToken của chính nó (HMAC-SHA256 dạng base64url của peer:<peerNodeId>, với khoá là localToken), còn tokenHash là SHA-256 dạng hex của token đó. Chỉ có hash được lưu lại.

curl -s -X POST "$CLARKCANT_URL/peers/invites" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "endpoint": "http://laptop.local:8765" }'
# 201 → { "invite": { "inviteId": "…", "fingerprint": "…", "expiresAt": "…", … } }

# Sau khi node kia đã nhận lời mời và bạn đã so fingerprint:
curl -s -X POST "$CLARKCANT_URL/peers/<nodeId>/confirm" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN"

Viết một grant

POST /grants nhận một grant: { grantId, ownerPrincipalId, senderNodeId, receiverNodeId, capabilityRefs, resources, allowedDataClasses, expiresAt, budget?, maxDelegationDepth, allowedEffectCategories? }. Grant ghi node này là bên gửi, chủ của node này (ownerPrincipalId trong identity.json) là chủ, và một peer đã xác nhận là bên nhận. Grant được lưu và xếp hàng gửi tới peer trong cùng một lần ghi, và từ đó peer nhận những việc node này giao cho nó theo grant đó, cho tới khi grant hết hạn hoặc bị thu hồi. Peer vẫn chỉ chạy những gì chủ của nó cho phép: nó lấy giao của grant với mức cho phép của chính nó, nên một grant có thể thu hẹp những gì chạy ở đó nhưng không bao giờ mở rộng.

Hiếm khi bạn phải tự viết grant. Khi bạn thiết lập trong cuộc trò chuyện một tự động hoá chạy trên node đã ghép cặp, grant được viết cho đúng các thư mục, repository và tác động của nó, và việc tạm dừng hay xoá tự động hoá đó thu hồi grant trên cả hai node.

Trước khi giao việc, bạn có thể xem node kia sẽ chạy được gì cho bạn. Hãy nhờ Clark liệt kê các node đã ghép cặp (list_peers): với mỗi node, Clark cho biết chủ của node đó có cho phép node của bạn điều gì không, và trong những năng lực được cho phép, năng lực nào node đó chạy được ngay lúc này. Node của bạn chỉ biết đến vậy: các thư mục và mọi thứ khác mà quyền cho phép bao gồm vẫn ở lại node kia. Khi bạn thiết lập một tự động hoá chạy ở đó, Clark cảnh báo nhưng không từ chối nếu node đó chưa cho phép node của bạn, không cho phép điều tác vụ cần, hoặc chưa chạy được nó. Một node không hỏi được, vì đang chạy ClarkCant cũ hơn hoặc không trả lời trong 5 giây, được báo là chưa rõ. Lần kiểm tra khi tác vụ tới nơi vẫn là bên quyết định.

Một tác vụ tới nơi trước khi node đó chạy được điều nó cần, chẳng hạn khi một gói còn đang nạp, sẽ chờ ở đó thay vì bị từ chối, và cả hai chủ node đều được báo nó đang chờ năng lực nào. Việc chờ không có giới hạn thời gian: tác vụ tự bắt đầu khi năng lực đó sẵn sàng, và dừng nó ở nơi bạn thiết lập sẽ kết thúc nó ngay. Với cặp ghép được tạo trước tính năng này, cho tới khi mỗi node đã gửi được gì đó cho node kia, tác vụ như vậy vẫn bị từ chối ngay, và lời cảnh báo nói rõ điều đó.

Một tác vụ giao cho node đã ghép cặp có thể mang về các tệp mà lần chạy đã ghi, nhưng chỉ khi cả hai chủ node cho phép. Về phía bạn, hãy đặt cho tự động hoá một hạn mức byte bằng maxArtifactBytes trong create_automation, tối đa 16 MiB. Về phía bên kia, chủ của node đó cho node của bạn một hạn mức bằng maxArtifactBytes trong allow_peer_tasks. Thiếu một trong hai thì tệp ở lại node kia, và kết quả sẽ nói rõ điều đó. Tệp được mang về trong phạm vi hạn mức nhỏ hơn, tối đa 8 tệp và 4 MiB mỗi tệp. Chỉ các tệp được ghi bằng công cụ ghi tệp dự án bên trong các thư mục của tác vụ mới được gửi, không bao giờ có HTML, SVG hay script. Node của bạn kiểm tra từng tệp theo chính grant của bạn cho tác vụ đó, tải về một lần và kiểm tra digest trước khi giữ lại. Tệp được mang về hiển thị cùng kết quả trong cùng cuộc trò chuyện, và tệp nào bị bỏ ra hoặc bị từ chối đều được liệt kê kèm lý do.

Báo cho node đã ghép cặp biết chuyện gì đã xảy ra

POST /peers/{nodeId}/signals { id, topic, payload?, subject?, occurredAt? }, gửi tới chính node của bạn bằng token của nó. id là tên bạn đặt cho sự kiện. Signal được xếp hàng trước khi gửi, nên không bị mất khi peer đang ngoại tuyến, và peer chỉ ghi nhận nó một lần dù được gửi lại bao nhiêu lần.

Peer ghi nhận nó thành peer.<topic> từ node mà kênh đã xác thực chỉ ra, nên nó không thể giả làm một lần gửi từ GitHub, một webhook có chữ ký hay một bộ hẹn giờ. Signal là một sự việc, không phải mệnh lệnh: nó không cần grant và không đòi hỏi gì, và chỉ những yêu cầu thường trực mà chủ của peer đã thiết lập ở đó mới quyết định nó khởi động việc gì, nếu có.

curl -s -X POST "$CLARKCANT_URL/peers/<nodeId>/signals" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "build-812", "topic": "build.finished", "payload": { "status": "failed" } }'
# 202 → { "messageId": "…", "queued": true }

Đặt thông báo vào hộp thư của chủ node kia

POST /peers/{nodeId}/notices { id, title, body?, category?, severity? }, gửi tới chính node của bạn bằng token của nó. id là tên bạn đặt cho sự kiện. category là result, update, message (mặc định) hoặc alert; severity là info (mặc định), success, warning hoặc error. Hiện chưa có gì trên node tự gửi thông báo, nên route này là cách một script, CLI, một client MCP hay một tự động hoá báo cho một Clark đã ghép cặp.

Thông báo chỉ là chữ, không hơn: id tối đa 160 ký tự, tiêu đề tối đa 120 và nội dung tối đa 500, không có hành động, liên kết hay chủ thể. Node hiển thị nó quyết định có thể làm gì với nó, và xem nội dung của nó là dữ liệu. Nó được ghi nhận là của node bạn, mỗi id một lần, nên gửi lại hay phát lại cũng chỉ hiện một lần. Mỗi peer giữ tối đa 20 thông báo đang chờ ở đó, cái cũ nhất bị bỏ trước, mà không đẩy ra thông báo của chính node đó hay của peer khác.

Node nhận chỉ nhận thông báo theo quyết định của chính chủ nó là làm việc với node của bạn: một grant còn hiệu lực mà chủ đó đã viết cho node của bạn, hoặc việc họ cho phép node của bạn chạy việc ở đó. Grant do node của bạn viết không tính, và chỉ ghép cặp thôi cũng không đủ. Nó cũng chỉ nhận tối đa 30 thông báo mỗi phút từ một peer. Lời từ chối là quyết định cuối cùng, không phải lần gửi thất bại: node của bạn không gửi lại thông báo đó, và báo cho bạn trong hộp thư của chính bạn, mỗi peer và mỗi lý do một lần, thông báo nào không tới, vì sao, và điều gì sẽ thay đổi được việc đó.

curl -s -X POST "$CLARKCANT_URL/peers/<nodeId>/notices" \
  -H "Authorization: Bearer $CLARKCANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "id": "backup-2026-09-30", "title": "Sao lưu đêm qua thất bại", "severity": "error" }'
# 202 → { "messageId": "…", "queued": true }

Trong hộp thư

Sinh client

Phần ổn định được mô tả bằng OpenAPI 3.1, nên công cụ OpenAPI 3.1 nào cũng sinh được client có kiểu từ đó:

curl -s "$CLARKCANT_URL/openapi.json" -o clarkcant-openapi.json

File đính kèm và ảnh là dữ liệu nhị phân: gửi chúng qua HTTP. Các route này cũng gọi được qua WebSocket, MCP và CLI.