Actually you don't need to read our docs, just ask Clark questions
Thật ra bạn không cần đọc docs đâu, cứ hỏi Clark là được.
Hỏi ngay từ terminal:
clarkcant ask "how do I connect Cursor to you?"
Hiện CLI chạy từ một bản checkout của ClarkCant, nên nếu chưa đặt alias thì câu hỏi trên sẽ là:
# From a ClarkCant checkout (the CLI is not published to npm yet)
node apps/cli/src/main.ts ask "how do I connect Cursor to you?"
Hoặc, từ bất kỳ công cụ AI nào nói được MCP (Claude Desktop, Cursor, …), gọi tool ask_clark:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "ask_clark", "arguments": { "text": "how do I connect Cursor to you?" } } }
Các trang còn lại dành cho lúc bạn cần chính xác route, frame và cờ dòng lệnh.
Xây trên chuẩn mở
ClarkCant là một cuộc trò chuyện với một Clark. Cùng một Clark đó có thể được gọi qua những giao diện mở, phổ biến, nên mọi ứng dụng bên thứ ba, script hay công cụ AI đều điều khiển được mà không cần SDK riêng:
- HTTP/JSON + SSEREST API mô tả bằng OpenAPI 3.1, câu trả lời được stream bằng Server-Sent Events.
- MCPModel Context Protocol qua Streamable HTTP, kèm cầu nối stdio cho các công cụ AI trên máy tính.
- WebSocketMọi lệnh REST dưới dạng frame, chạy song song trên một socket.
- CLI
clarkcant: hỏi, đọc, dừng, hoặc gọi bất kỳ route nào từ terminal.
Một token, một gateway, cùng một ngữ nghĩa ở mọi nơi. Mọi giao diện đều do cùng một runtime node phục vụ, cùng origin, cùng bearer token. Không có tầng xử lý nghiệp vụ thứ hai: một tool MCP, một request WebSocket hay một lệnh CLI đều đi tới cùng một handler của HTTP gateway, nên chúng hoạt động y hệt lệnh REST bên dưới.
Phê duyệt (approval) cố ý không có trên MCP. Quyết định phê duyệt là việc của con người. Một client AI không được phép tự phê duyệt hành động cần kiểm soát của chính nó, nên không có tool MCP nào cho việc này.
Lệnh gạch chéo
Gõ / trong ô soạn tin để xem các lệnh, xếp trước các skill của bạn. Khi chưa gõ gì, lệnh và skill chia nhau danh sách (mỗi loại một nửa khi cả hai đều nhiều), nên skill của bạn luôn có mặt; gõ thêm vài chữ để tìm những mục còn lại. Clark trả lời mỗi lệnh ngay trong cuộc trò chuyện, bằng một tin nhắn kèm thẻ nhỏ để bạn thao tác tại chỗ, nên không lệnh nào mở màn hình riêng, trừ /settings, lệnh mở đúng hộp thoại Cài đặt mà nút bánh răng mở.
/newbắt đầu cuộc trò chuyện mới. Cuộc hiện tại vẫn được giữ, mở lại bằng/sessions. Lệnh này cũng chạy ngay cả khi Clark đang viết câu trả lời: câu trả lời không bị dừng, nó tiếp tục trong cuộc trò chuyện bạn vừa rời đi, và một ghi chú cho bạn biết điều đó./sessionsliệt kê việc nền và các cuộc trò chuyện trước, mỗi mục có nút Mở. Cuộc trò chuyện Clark vẫn đang trả lời được đánh dấu./changelogcho xem phiên bản này có gì mới. Xem bên dưới./loginđăng nhập AI provider ngay trong thẻ, bằng trang tài khoản của provider, mã thiết bị hoặc API key, tuỳ provider hỗ trợ cách nào. Những gì bạn nhập đi thẳng tới runtime của model; nó không bao giờ hiện trong cuộc trò chuyện và không lần đọc nào sau đó trả lại nó. Khi đăng nhập xong, thẻ nêu tên provider và kiểm tra Clark chạy được những model nào của provider đó. Sau đó thẻ đề nghị Chọn model của …, mở bộ chọn/modelcho provider đó ngay trong cùng thẻ, hoặc Giữ model hiện tại. Việc đăng nhập không bao giờ tự đổi model. Nếu provider chưa hiện là đã đăng nhập, hoặc không có model nào, thẻ nói rõ và có nút Kiểm tra lại. Đăng nhập từ Cài đặt → AI & Định tuyến cũng kết thúc bằng đúng bước này./modelchọn model trả lời. Thẻ liệt kê các model node này chạy được, đánh dấu model đang dùng và cho biết từng provider đã đăng nhập chưa. Bạn có thể tìm kiếm, hoặc gõ kèm từ khoá:/model large. Mở thẻ không thay đổi gì. Sau khi bạn chọn một model và xác nhận Đổi model, model đó trả lời từ tin nhắn tiếp theo của bạn. Nếu node này chưa chạy model nào, nó sẽ dùng model đó từ lần khởi động sau. Model của provider chưa đăng nhập vẫn được hiện nhưng chưa chọn được cho tới khi bạn đăng nhập bằng/login. Chính node từ chối model đó, nênPOST /modeltừ API hayclarkcant apicũng nhận cùng câu trả lời:409 CAPABILITY_NOT_AUTHENTICATEDkèm lý do./logoutđăng xuất khỏi provider mà Clark đã lưu khoá. Nếu khoá lấy từ môi trường, như.envhoặc shell, thẻ sẽ nói rõ và bạn gỡ nó ở đó./thinkingchọn mức suy nghĩ cho các lượt sau, từ danh sách, hoặc gõ trực tiếp:/thinking high, hoặc/thinking autođể model tự dùng mức mặc định của nó. Đây cũng là thiết lập Cài đặt → AI & Định tuyến → Mức suy nghĩ./settingsmở Cài đặt, cùng hộp thoại với nút bánh răng trên thanh đầu trang;/settings <tab>mở thẳng tab đó, như/settings ai,/settings memory, hoặc nhãn của tab đúng như Cài đặt hiển thị ở cả hai ngôn ngữ, cả nhãn hay từng phần hai bên dấu “&”, như/settings bộ nhớ,/settings giọng nóihay/settings AI & Định tuyến. Lệnh này dùng được cả khi Clark đang viết câu trả lời. Đóng lại thì bạn trở về cuộc trò chuyện đúng như lúc rời đi. Các lệnh khác ngoài/settingsvà/newgõ trong lúc Clark đang trả lời vẫn nằm trong ô soạn tin, kèm một ghi chú rằng bạn gửi được khi câu trả lời xong./background <yêu cầu>chạy yêu cầu thành việc nền bên cạnh cuộc trò chuyện và báo kết quả trong đó./reportbáo lỗi hoặc đề xuất tính năng cho chính ClarkCant. Xem bên dưới./developchọn một thư mục để phát triển widget ngay trong hội thoại;/develop <thư mục>đề xuất đúng thư mục đó, và/develop forgetliệt kê các thư mục bạn đã chọn để bạn thu hồi. Xem phát triển widget trong hội thoại.
Khi một cú bấm trên thẻ lệnh không tới được node của bạn, hoặc không có câu trả lời kịp thời, thẻ nói rõ điều đó và đặt nút Thử lại bên cạnh để gửi lại đúng cú bấm ấy; điều này áp dụng cho /thinking, /login, /logout, /develop và việc bỏ chọn một thư mục. Một cú bấm bị node từ chối thì nói lý do và không có gì để lặp lại, vì gửi lại cũng chỉ nhận về đúng câu trả lời đó.
Skill trùng tên với một lệnh được liệt kê và ghi thành /skill:<tên>, nên chọn nó là dùng skill đó; tự gõ /new thì vẫn chạy lệnh.
Lệnh gõ ở giữa câu chỉ là chữ thường. Lệnh không được gửi tới model. Xem các route đăng nhập provider.
Báo lỗi hoặc đề xuất tính năng
Gõ /report để nhận một thẻ: chọn Lỗi hay Tính năng, kể chuyện đã xảy ra hoặc điều bạn muốn bằng lời của mình, và mở “Những gì sẽ được chia sẻ” để xem chính xác những gì đi kèm. /report bug … và /report feature … (hoặc lỗi và tính năng), một câu nói với Clark, hay giọng nói đi thêm một bước: Clark chuẩn bị báo cáo và hiện issue đúng như sẽ được gửi. Không cách nào trong số đó gửi đi thứ gì. Chỉ cú bấm Tạo issue của chính bạn mới gửi báo cáo; Clark, công cụ của nó và giọng nói đều không thể. Báo cáo chỉ tới digitopvn/clarkcant, không đi đâu khác.
Policy thực thi của bạn áp dụng cho cú bấm đó. Nếu policy từ chối, báo cáo bị từ chối và không gì được gửi; nếu policy lẽ ra sẽ hỏi trước, chính cú bấm của bạn là câu trả lời. Trước khi gửi, Clark xem các issue đang mở và các issue đóng trong 90 ngày gần nhất; khi một issue đang mở khớp rõ ràng, báo cáo của bạn được thêm vào đó thành bình luận thay vì mở issue mới.
Thẻ kết quả cho biết chuyện diễn ra thế nào: Đã tạo issue hoặc Đã thêm vào issue có sẵn (chỉ sau khi Clark đọc lại được báo cáo từ GitHub), Chưa rõ kết quả, Chưa gửi được, Cần quyền GitHub hoặc Chính sách không cho gửi. Khi không nhận được phản hồi của GitHub, Kiểm tra lại chỉ xem, không bao giờ gửi. Gửi lại chỉ xuất hiện khi GitHub cho thấy không có báo cáo ít nhất hai phút sau lần thử. Nếu Clark không thể biết GitHub đã giữ báo cáo hay chưa, thẻ nói rõ điều đó, dẫn tới các issue bạn đã mở từ lúc ấy và trang tạo issue đã điền sẵn, và có nút Vẫn gửi, có thể gửi hai lần. Clark không bao giờ tự gửi lại: sau khi khởi động lại, các báo cáo chưa ngã ngũ được kiểm tra, không gửi lại, và kết quả được đăng vào cuộc trò chuyện của chúng.
Nếu cú bấm Tạo issue của bạn không tới được node, thẻ đề nghị Thử lại, gửi lại đúng báo cáo đó theo đúng cách cũ. Nếu cú bấm đã đi và thứ quay về không phải là lời từ chối do node quyết định (mất kết nối, hết thời gian chờ, một chặng chuyển tiếp ở giữa bị lỗi, hoặc chính node gặp lỗi), node có thể đã gửi rồi, nên thẻ không bao giờ nói là chưa gửi được: thẻ nói chưa biết kết quả và đề nghị Kiểm tra lại, chỉ hỏi node xem báo cáo đang ở đâu, kèm Thử lại bên cạnh khi gửi lại cú bấm đó có thể đi tới nơi. Một cú bấm tới lúc node vẫn đang gửi báo cáo được báo đúng như vậy, bằng ngôn ngữ của bạn. Node nhận một báo cáo cho một lần gửi trước khi hỏi GitHub bất cứ điều gì, nên một báo cáo node đã gửi hoặc đang gửi chỉ được kiểm tra chứ không bị gửi lại, kể cả khi hai cú bấm chồng lên nhau; thử lại không bao giờ gửi một báo cáo hai lần. Một lần Kiểm tra lại không đi tới nơi vẫn để kết quả ở trạng thái chưa biết. Nếu node đã trả lời nhưng phiên bản ứng dụng này không đọc được câu trả lời, thẻ nói rằng báo cáo có thể đã được gửi lên hoặc chưa, không bao giờ nói là thất bại, và đề nghị Kiểm tra lại. Một lời từ chối do node quyết định không có gì để lặp lại và không gợi ý thử lại. Sau Thử lại hoặc Kiểm tra lại, tiêu điểm bàn phím vẫn ở dòng trạng thái của thẻ.
Việc gửi dùng token GitHub (github_token) bạn đã lưu cho nguồn signal. Chưa có token, thẻ hiện Cần quyền GitHub kèm liên kết tới trang tạo issue của GitHub đã điền sẵn để bạn tự gửi. Repo cũng có mẫu issue Bug report và Feature request để gửi thủ công.
Những gì được chia sẻ, và những gì không bao giờ. Lời của bạn, đã che bí mật, và chẩn đoán an toàn trừ khi bạn tắt: phiên bản ClarkCant, hệ điều hành và kiến trúc, runtime, ngôn ngữ và cách nhập, phần ClarkCant liên quan, provider và model, cùng lỗi dưới dạng trích đoạn ngắn đã che bí mật kèm dấu vân. Không bao giờ gửi: cuộc trò chuyện, prompt hệ thống, tệp, biến môi trường, log thô hay thông tin đăng nhập. Thư mục home được ghi là ~, và các @mention trong lời bạn được vô hiệu hoá để báo cáo không thông báo cho ai.
Giao cho Clark xử lý một issue bạn đã gửi hiện chưa có; thẻ kết quả nói lý do. Xem các route báo cáo.
Đăng nhập nhà cung cấp AI
Mở Cài đặt → AI & Định tuyến để đăng nhập các nhà cung cấp AI mà pi có thể dùng để trả lời, ngay dưới ô chọn nhà cung cấp và model. Mỗi nhà cung cấp chỉ hiện những cách đăng nhập mà pi hỗ trợ cho nó: đăng nhập tài khoản khi nhà cung cấp có, API key khi nhà cung cấp nhận. Quá trình đăng nhập diễn ra ngay trong hàng: mở trang của nhà cung cấp rồi dán mã trang đó hiện ra, hoặc nhập khoá vào ô mật khẩu. Những gì bạn nhập đi thẳng tới pi và không bao giờ hiện lại. Gõ /login hoặc /logout trong cuộc trò chuyện cũng làm được việc này.
Nhà cung cấp đã đăng nhập cho biết thông tin đăng nhập đến từ đâu: do pi lưu, biến môi trường của node (.env hoặc shell), được trao lúc node khởi động, models.json của pi, hoặc khoá pi tự tìm thấy. Chỉ thông tin đăng nhập do pi lưu mới đăng xuất hoặc thay được ở đây. Với các loại khác, hàng đó nói rõ điều này và chỉ chỗ cần gỡ khoá. Sau khi đăng nhập hoặc đăng xuất, danh sách nhà cung cấp và danh sách model được làm mới, nên bạn chọn được ngay model vừa dùng được.
Hộp thư và thông báo
Mở hộp thư từ huy hiệu ở đầu ứng dụng, bằng bàn phím, hoặc yêu cầu Clark bằng chữ hay giọng nói: “mở hộp thư”. Hộp thư tập hợp yêu cầu duyệt lệnh, quyền của gói, yêu cầu duyệt do task đang chạy tạo ra, câu hỏi chưa trả lời và thông báo đã lưu về công việc nền, yêu cầu hết hạn và bản cập nhật. Công cụ control_app của Clark cũng mở cùng hộp thư này.
Duyệt yêu cầu của task đang chạy cho phép node chạy lại task; nếu node chưa nhận được lượt chạy, Clark nói rõ 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. Quyết định đó thuộc về bạn; các giao diện máy từ chối thao tác này. Xem quyết định yêu cầu duyệt của task.
Cài đặt → Điều khiển có thông báo hệ điều hành trên desktop và Web Notifications trên trình duyệt, với công tắc theo nhóm và giờ yên tĩnh. Trình duyệt phải cấp quyền thông báo. Thông báo chỉ hiện khi ứng dụng bị ẩn, mất focus hoặc ở chế độ orb/thu gọn; nội dung đã che dữ liệu nhạy cảm và không bao giờ chứa dòng lệnh. Bấm thông báo sẽ mở đúng mục trong hộp thư; nếu mục đã được xử lý, ứng dụng nói rõ điều đó.
Nếu hệ điều hành từ chối hoặc không hiện được thông báo, trạng thái ngay cạnh công tắc thông báo hệ điều hành giải thích lý do và cho biết mục vẫn còn trong hộp thư. Trạng thái này biến mất khi một thông báo được hiện lại thành công. Kiểm tra cập nhật chỉ đề xuất phiên bản trình cài đặt chấp nhận trên máy của bạn và giữ im lặng khi node ngoại tuyến.
Gói đến từ đâu
Khi bạn nhờ Clark tìm một gói, thẻ kết quả liệt kê gói từ tệp chỉ mục của riêng bạn, từ mọi catalog mà người vận hành đã thêm, và từ ClarkCant Marketplace chính thức, vốn bật sẵn theo mặc định. Mỗi hàng nêu tên nguồn của nó, và nguồn nào không phản hồi thì được nêu tên thay vì hiện thành danh sách rỗng. Marketplace chính thức hiện có thể chỉ có vài gói hoặc chưa có gói nào. Mỗi gói giữ nguồn mà nó được cài từ đó: bản cập nhật chỉ đến từ nguồn ấy, và thông báo cập nhật nêu tên nguồn đó. Cấu hình, thứ tự ưu tiên và các mã lỗi nằm ở danh sách gói đến từ đâu; cách tự lưu trữ catalog nằm ở feed thư mục gói.
Cửa sổ ứng dụng desktop
Ứng dụng desktop mở lại cửa sổ hội thoại đúng nơi bạn để: cùng vị trí và kích thước, phóng to hoặc toàn màn hình nếu lúc đóng nó đang như vậy. Nếu màn hình đó không còn được kết nối, hoặc cửa sổ sẽ mở ra ở chỗ không với tới được, nó mở ở vị trí và kích thước mặc định. Cửa sổ được nhớ từ một màn hình lớn hơn sẽ được thu lại cho vừa.
Điều khiển cửa sổ trên Linux: X11, Wayland và Hyprland
Thanh thu gọn, orb, chế độ mở rộng, toàn màn hình và nút ghim hoạt động như nhau trên macOS, Windows và Linux dưới X11, kể cả phiên Wayland mà ứng dụng chạy qua XWayland (khởi động với --ozone-platform=x11): ứng dụng đặt kích thước, vị trí của cửa sổ và có thể giữ nó nằm trên các cửa sổ khác. Dưới XWayland, compositor của bạn vẫn có thể ghi đè vị trí hoặc thứ tự xếp chồng.
Dưới Wayland gốc, chế độ mà ứng dụng desktop dùng mặc định trong phiên Wayland, compositor quyết định cửa sổ nằm ở đâu, và không có giao thức chuẩn nào cho phép ứng dụng giữ cửa sổ của mình nằm trên các cửa sổ khác. Vì vậy ở đó ứng dụng chỉ yêu cầu kích thước, mà compositor dạng tiling cũng có thể bỏ qua với cửa sổ đang được xếp ô, và ứng dụng không bao giờ giả vờ khác đi: nút ghim không hiện, yêu cầu ghim bị từ chối kèm lý do thay vì được gửi đi, và mọi lần đổi chế độ cửa sổ đều báo vị trí là không được hỗ trợ.
Trên Hyprland, ví dụ Omarchy, bạn có thể chủ động bật backend Hyprland, điều khiển cửa sổ bằng chính các lệnh của Hyprland: chế độ thu gọn và orb cho cửa sổ nổi ở đúng kích thước của chúng, orb còn được ghim lên mọi workspace, chế độ mở rộng phóng to cửa sổ, còn nút ghim cho cửa sổ nổi và ghim nó. Thu nhỏ bị từ chối, vì Hyprland không có trạng thái thu nhỏ. Bật bằng cách khởi động ứng dụng desktop với --window-backend hyprland hoặc biến môi trường CLARKCANT_WINDOW_BACKEND=hyprland. Tuỳ chọn này chỉ có tác dụng khi Hyprland thực sự đang chạy; ở nơi khác ứng dụng giữ hành vi mặc định. Nếu một lần giao tiếp với Hyprland thất bại, cửa sổ quay về hành vi Wayland gốc ở trên cho đến hết phiên.
Chưa được kiểm chứng trên Hyprland thật. Backend Hyprland tắt theo mặc định vì mới chỉ được kiểm thử với một bản giả lập, chưa chạy trên desktop Hyprland hay Omarchy thật, và chưa có gói Omarchy nào được phát hành. Trong các phiên Linux, chỉ X11 có kiểm thử tự động. Các bước tự kiểm tra trên máy của bạn nằm trong hướng dẫn smoke theo nền tảng.
Phiên bản và có gì mới
Hỏi Clark “có gì mới?” hoặc “đây là phiên bản nào?”, gõ /changelog (hoặc /changelog 1.4 để xem những gì có sau 1.4), hoặc mở Cài đặt → Trải nghiệm → Phiên bản & có gì mới. Cách nào cũng hiện cùng một thẻ do node của bạn vẽ: phiên bản và kênh đang dùng, cùng ghi chú phát hành đi kèm bản này, chia thành thay đổi không tương thích, tính năng, sửa lỗi và thay đổi khác. Ghi chú được nhúng trong bản build nên thẻ dùng được cả khi không có mạng. Clark có thể tóm tắt các mục bằng ngôn ngữ của bạn, nhưng không thể thêm mục nào: thẻ thuộc về node của bạn, và các mục là những gì bản phát hành đã ghi lại. Thẻ không có nút Cập nhật, trạng thái cập nhật hay lựa chọn kênh, vì chưa có dịch vụ cập nhật. Xem GET /changelog.
Chạy từ mã nguồn. Một bản checkout mang theo ghi chú phát hành đã được commit cùng nó, và ghi chú đó dừng ở một commit đã ghi lại. Với bản cài từ mã nguồn, thẻ, /changelog và Clark nêu commit đó cùng ngày của nó, và nói rằng bản checkout có thể có thay đổi mới hơn chưa được liệt kê. git pull không thêm chúng vào. Cho tới khi bản phát hành đầu tiên ra mắt, liên kết của thẻ ghi “Toàn bộ lịch sử thay đổi” và mở lịch sử commit tới commit đó.
Để cập nhật bản cài từ mã nguồn, làm theo mục Cập nhật trong hướng dẫn cài đặt: git pull, rồi node tools/setup.mjs. Nếu bạn đã sửa một tệp mà bản cập nhật thay đổi, git pull dừng lại báo lỗi thay vì ghi đè phần bạn sửa; giữ hoặc bỏ thay đổi đó rồi pull lại. Hiện đây là cách cập nhật duy nhất: Clark chưa có trình tự động cập nhật.
Phiên bản và kênh
Số phiên bản được tính từ các commit kể từ bản phát hành trước, viết theo Conventional Commits, và theo quy tắc semantic versioning: thay đổi không tương thích là bản major, feat là bản minor, fix hoặc perf là bản patch. main là kênh ổn định (1.4.0); dev là kênh beta (1.5.0-beta.1, …), và bản beta không bao giờ vào kênh ổn định. Quy tắc đầy đủ, cùng cách chạy kế hoạch phát hành từ một bản checkout, nằm trong tài liệu phát hành; chạy corepack pnpm install ở thư mục gốc của repo trước bước cài riêng của công cụ phát hành, vì trình lập kế hoạch đọc các contract dùng chung của ứng dụng.
Chưa có. Chưa có bản phát hành nào được công bố. Trình cài đặt, bản build có chữ ký, ghi chú phát hành công khai và cập nhật ngay trong Clark sẽ đến sau.
Nhãn theo ngôn ngữ giao diện
Thẻ task ghi trạng thái và bằng chứng bằng ngôn ngữ giao diện, ví dụ “cần bạn quyết định” hay “chưa rõ kết quả”; trạng thái mà phiên bản này chưa biết được hiện đúng như được gửi. Trong thư viện widget, nguồn của mỗi widget (Có sẵn, Gói đã cài, Gói đang phát triển trên máy) và trạng thái (Ổn định, Thử nghiệm) cũng được ghi như vậy. Cài đặt → Tiện ích liệt kê mỗi công cụ theo việc nó làm, kèm tên bên cạnh, dưới “Của node này” và “Của agent (pi)”; chỉ dẫn mà model nhận được cho một công cụ nằm sau “Chỉ dẫn cho model”.
Văn bản do chính node của bạn viết vào cuộc trò chuyện theo ngôn ngữ giao diện bạn chọn trong Cài đặt (Tiếng Việt hoặc English, preference experience.language; tiếng Việt khi chưa đặt). Văn bản được viết bằng ngôn ngữ đó ngay lúc viết, ứng dụng không dịch lại sau, nên những dòng đã có trong cuộc trò chuyện giữ ngôn ngữ lúc chúng được viết. Điều này áp dụng cho thẻ trả lời của Clark và các ghi chú của chúng (model nào đang trả lời, không có model, model lỗi, câu trả lời bị dừng, số liệu của lượt, một khối bị từ chối), các mẫu trên màn hình bắt đầu và nhãn của các bề mặt Clark dựng, báo cáo về việc chạy nền và task (bắt đầu, xong, dừng, lỗi, hàng đợi đầy, thử lại, hạn chót), biên nhận dừng và phê duyệt, khôi phục sau khi khởi động lại, tin nhắn của tự động hoá, nhãn của các dòng cho công cụ do node định nghĩa, dòng câu hỏi và việc chúng hết hạn, cùng trạng thái của việc đã giao cho một node đã ghép đôi và các tệp nó mang về. Điều này cũng áp dụng cho ghi chú model và các thẻ khác do node của bạn viết; các dòng và biên nhận mà một lệnh hay một lời gọi gói đã duyệt để lại, kể cả các ghi chú về những gì lệnh in ra (“Không có output.”, dấu đánh dấu đã cắt bớt); thẻ phê duyệt cho việc cài một gói, cấp quyền cho gói và tải ô bản đồ, cùng lý do một task đang chờ phê duyệt; task đã kết thúc ra sao, khi chính node của bạn viết điều đó (bị từ chối trước khi chạy, một lần chạy không có gì để báo, một lần dừng, và câu trả lời bạn đã ghi cho một thao tác chưa rõ kết quả); thông báo rằng một lần chạy tự động không bắt đầu được; thông báo trong hộp thư, kể cả từ dùng cho một thông báo không có tiêu đề; các gợi ý trên màn hình bắt đầu; nhãn công cụ dưới mục Công cụ trong Cài đặt → Tiện ích; và câu trả lời khi bạn từ chối một câu lệnh nói hay gõ, hoặc khi lời xác nhận của nó đã quá hạn hay đã được dùng.
Giữ nguyên như đã viết. Văn bản đã viết giữ ngôn ngữ của nó khi bạn đổi ngôn ngữ: một thẻ phê duyệt được hỏi trước khi đổi giữ nguyên lời lẽ, và thông báo hết hạn của nó cũng vậy ở chỗ trích lại thẻ đó. Các gợi ý đang có trên màn hình giữ nguyên cho tới lần tải tiếp theo. Nhãn và mô tả do một gói hay extension viết được hiện đúng lời tác giả. Văn bản gửi tới một node đã ghép đôi giữ nguyên, vì node của bạn không biết ngôn ngữ của chủ node đó. Văn bản không do node của bạn viết, như một thông báo lỗi hay điều một lần chạy đã báo, được trích nguyên văn chứ không được viết lại vào câu. Thông điệp được lưu cho một task, và những gì được gửi tới một node đã ghép đôi về task đó, giữ nguyên lời lẽ ban đầu. Những gì model được dặn không được dịch: đó là đầu vào của model, không phải văn bản bạn đọc.
Thuật ngữ lập trình khi bạn nói
Khi bạn nói một câu trộn tiếng Việt với thuật ngữ lập trình tiếng Anh, node của bạn sửa cách các thuật ngữ được nghe trước khi câu được đọc như một tin nhắn, một lệnh hay một câu trả lời: “sửa lỗi stale closer trong use effect” thành “sửa lỗi stale closure trong useEffect”, và “cài core pack rồi bật p and pm” thành “cài Corepack rồi bật pnpm”. Câu đã sửa thay cho dòng đang được viết, nên mỗi điều bạn nói là một dòng, không phải hai.
Cách sửa là các quy tắc cố định, không phải một model: chữ hoa chữ thường, khoảng trắng, các lỗi nghe nhầm đã biết, và một chữ nói trượt trong tên công cụ, provider hay model. Mỗi lần sửa cần có bằng chứng trong câu, và các thuật ngữ lấy từ những gì phiên của bạn biết: các dự án, nhánh đang dùng, các symbol, đường dẫn và issue mà cuộc trò chuyện đã nhắc tới, skill, extension, model hiện tại và một bảng thuật ngữ lập trình có sẵn. Sửa một chữ không bao giờ chạm tới tên symbol, đường dẫn, nhánh hay package, hoặc một từ có chữ số, vì các tên gần nó là những tên có thật khác hoặc một phiên bản khác. Một từ có thật hay tên người không bao giờ bị coi là nghe nhầm, phần của một từ dài hơn đã viết sẵn không bao giờ bị động tới, đoạn có thể là hai thuật ngữ thì được giữ như đã nghe, và câu vốn đã viết đúng thì giữ nguyên. Không model nào viết lại lời bạn nói.
Bộ nhận dạng riêng, nếu người vận hành bật
Mặc định, lời bạn nói lấy từ bản chép lời của chính phiên giọng nói trực tiếp. Người vận hành có thể cho một node dùng bộ nhận dạng riêng bằng cách khởi động nó với CC_VOICE_RECOGNIZER=gemini-transcribe. Bộ này dùng cùng thông tin xác thực Gemini với phiên trực tiếp; phiên trực tiếp vẫn là giọng nói và vẫn nghe khi bạn ngắt lời. Trong lúc bạn nói, bản nghe tạm được hiện rồi thay thế, và chỉ câu đã chốt mới được gửi, một lần. Câu bị cắt ngang bởi giới hạn phiên của provider vẫn là một câu. Nếu bộ nhận dạng không mở được kịp hoặc hỏng giữa chừng, bản chép lời trực tiếp tiếp quản, bắt đầu từ phần bộ nhận dạng chưa giao. Khi bật, phần kỹ thuật chưa rõ trong một câu có thể được nghe lại từ chính âm thanh của câu đó, và một quy tắc cố định chọn giữa các bản nghe. Ứng dụng không có thiết lập nào cho việc này. Giá trị không hợp lệ bị bỏ qua và node báo điều đó trên stderr.
Những gì được gửi tới bộ nhận dạng. Ngoài giọng nói của bạn, vốn phiên trực tiếp cũng nghe, bộ nhận dạng riêng được gửi các thuật ngữ của phiên dưới dạng customVocabulary của Gemini: những tên như identifier, đường dẫn tệp, tên nhánh và số issue lấy từ cuộc trò chuyện. Mọi thuật ngữ đều qua cùng bộ che bí mật, và thuật ngữ nào bị bộ che làm thay đổi thì bị bỏ ra. Các câu trong cuộc trò chuyện chỉ dùng để xếp hạng thuật ngữ; chúng không bao giờ được gửi đi. Khi không bật thiết lập này, các thuật ngữ ở lại trên node của bạn và chỉ dùng để sửa bản chép lời. Xem kiến trúc hệ thống và ADR-003.
Terminal trong hội thoại
Yêu cầu Clark bằng chữ hoặc giọng nói “mở terminal trong thư mục dự án” để mở shell thật ngay trong hội thoại. Các chương trình toàn màn hình như vim và htop hoạt động tại đây. Lệnh Clark đề xuất đi qua chính sách thực thi của bạn; khi cần bạn duyệt, lệnh chỉ được điền sẵn và chạy khi bạn nhấn Enter. Clark không ghi đè dòng bạn đang nhập. Nhấn F6 để chuyển focus ra khỏi terminal.
Gửi vùng chọn, kết quả lệnh đã kết thúc gần nhất hoặc màn hình về hội thoại; nút nói rõ nội dung nào sẽ được gửi, và chuỗi giống thông tin xác thực được che trước khi model nhìn thấy. Mỗi terminal chỉ có một bên điều khiển: thẻ khác theo dõi và có thao tác “Điều khiển tại đây”. Bảng Tiến độ liệt kê terminal khác, lượt chạy lệnh và công việc nền. Thẻ báo đúng trạng thái đang kết nối, mất kết nối kèm kết nối lại, đã kết thúc kèm mã thoát, không còn trên node hoặc không dùng được vì node không có PTY.
Cài đặt → Widget → Duyệt liệt kê Terminal trong Thẻ hệ thống, với mô tả, hình minh họa tĩnh được ghi rõ là minh họa và gợi ý yêu cầu Clark mở. Không có xem trước trực tiếp hay nút mở. Tìm kiếm có hoặc không có dấu tiếng Việt đều được; chọn nhóm khác Tất cả sẽ ẩn Thẻ hệ thống. Socket /terminal thuộc về thẻ này của ứng dụng.
Hội thoại dài
Một hội thoại dài vẫn là một hội thoại. Nó mở ở những tin nhắn mới nhất, và lịch sử cũ hơn được tải khi bạn cuộn lên, không cần bấm nút nào; phần đó được chèn lên trên mà không làm dịch dòng bạn đang đọc. Khi bạn đang ở cao hơn đáy hơn một màn hình và có nội dung mới tới, nút Đến tin mới nhất hiện ở chân hội thoại, và biến mất khi bạn đã ở đáy. Nếu không đọc được lịch sử cũ hơn, hội thoại nói rõ điều đó ngay tại chỗ lẽ ra nó hiện, giữ nguyên mọi thứ trên màn hình, và cho phép Thử lại.
Để luôn nhanh, chỉ những tin nhắn quanh màn hình được giữ trong trang; tin nhắn bạn đang focus, trình phát đang phát, video hay bản đồ nhúng bạn dùng gần nhất, vùng đang chọn và tin nhắn mới nhất luôn được giữ. Một thẻ bạn cuộn đi rồi quay lại vẫn giữ như lúc bạn rời, như một mục đang mở, bản nháp hay ô tìm kiếm, nhưng không bao giờ giữ bí mật đã gõ vào thẻ thông tin đăng nhập. Vì vậy, tính năng tìm trong trang của trình duyệt chỉ thấy mọi tin nhắn trong hội thoại tối đa 60 tin; ở hội thoại dài hơn, nó chỉ tìm thấy các tin nhắn gần màn hình. Tìm kiếm xa hơn về trước hiện chưa có. Xem đọc một hội thoại dài.
Biểu đồ và bảng trong câu trả lời
Khi câu trả lời có cấu trúc, như các con số cần so sánh, một xu hướng hay danh sách lựa chọn, Clark hiển thị nó dưới dạng biểu đồ hoặc bảng ngay trong câu trả lời mà không cần bạn yêu cầu. Chỉ cần hỏi “so sánh benchmark của model A và B”; bạn không phải thêm “dưới dạng biểu đồ”. Clark vẽ đúng những con số đã thu thập được, nói rõ nguồn và không bao giờ bịa giá trị để lấp biểu đồ.
Các con số Clark thu thập cho một câu trả lời được giữ trên node của bạn dưới dạng dữ liệu đã lưu do bạn sở hữu, và biểu đồ ghi rõ đó là dữ liệu đã lưu chứ không phải dữ liệu trực tiếp. Biểu đồ cột có thể đặt nhiều chuỗi cạnh nhau kèm chú giải, để so sánh hai model trên từng benchmark. Các hàng không hợp lệ, như quá nhiều hàng hay một ô quá dài, bị từ chối toàn bộ kèm lý do; không có biểu đồ nào hiện ra dở dang. Hiện tại các hàng này được vẽ trong biểu đồ hoặc bảng hiển thị riêng, chưa vẽ bên trong một bản tổng quan ghép. Xem tiêu chuẩn phát triển widget (§8.6.1).
Bảng Kanban trong hội thoại
Khi câu trả lời có bảng, bạn có thể di chuyển thẻ bằng chuột, cảm ứng hoặc bàn phím. Bảng có sẵn hiển thị công việc Clark đã biết; bản thân nó không kết nối tới dịch vụ quản lý dự án. Nếu bảng được gắn action để đổi dữ liệu ở nơi khác, yêu cầu đó đi qua luồng action và policy thông thường của Clark. Xem tiêu chuẩn phát triển widget (§8.10).
Cây phân cấp
Khi Clark đã có sẵn thông tin phân cấp, thông tin đó có thể hiện thành outline lồng nhau bằng canvas.tree@1. Mỗi mục có id ổn định và nhãn, cùng chữ phụ, icon thuộc một nhóm cố định và các mục con tùy chọn. Đây là cách xem thông tin đã biết, không phải trình duyệt tệp: cây không đọc service, còn việc đổi lựa chọn hay mở nhánh không sửa dữ liệu nguồn. Lựa chọn và các nhánh đang mở được lưu cùng widget và khôi phục theo pin; ID đã lưu nhưng không còn trong cây mới sẽ bị bỏ qua.
Phím mũi tên di chuyển giữa các mục đang hiện và mở hoặc đóng nhánh; Home và End tới hai đầu, gõ chữ để tìm nhãn, Enter hoặc Space để chọn mục. Trình đọc màn hình nhận được cấp, vị trí, số mục trong nhóm, trạng thái chọn và trạng thái mở của mỗi mục. Node kiểm tra giới hạn cây trước khi hiển thị. Xem hợp đồng và giới hạn của cây cùng hướng dẫn phát triển widget nội bộ.
Sơ đồ và đồ thị
Khi Clark có một luồng, một đồ thị phụ thuộc hay một cây nhỏ cần hiển thị, Clark có thể vẽ bằng canvas.diagram@1. Ứng dụng tự dựng SVG và không có gì trong đó được thực thi: nhãn là chữ, hình và đường là các con số từ một bố cục dùng chung, và không có HTML, foreignObject, liên kết, ảnh, style hay handler nào mà một nhãn có thể gọi tới.
Sơ đồ có tối đa 60 node và 120 cạnh. ID node dài tối đa 64 ký tự gồm chữ cái ASCII, chữ số, _ và -. Nhãn là một dòng tối đa 80 ký tự, nhãn cạnh tối đa 40, tên nhóm tối đa 40 và tiêu đề tối đa 200. Hình của node là box, round, diamond hoặc circle. Hướng của cạnh là forward, both hoặc none, và cạnh có thể mang nhãn. Nhóm chỉ có một cấp. Node từ chối ID node bị lặp, cạnh trỏ tới node không tồn tại, cạnh từ một node về chính nó, cùng một cạnh hai lần, quá nhiều node hoặc cạnh, trường lạ và ký tự ẩn, và mỗi lần từ chối đều nói lý do bằng câu của chính host.
layout là layered (mặc định) hoặc tree, còn direction là TB (từ trên xuống) hoặc LR (từ trái sang phải). Bố cục phân lớp phá vòng, chia node thành lớp theo đường dài nhất và bẻ các cạnh dài qua những lớp chúng đi ngang. Bố cục cây đặt node con cân giữa dưới node cha và từ chối đồ thị không phải là rừng. Khoảng trống chứa nhãn cạnh được nới rộng cho vừa nhãn, và các cạnh nối cùng hai node được vẽ tách nhau. Bố cục là tất định: cùng props luôn cho cùng một hình vẽ trên node và trên mọi client, và đồ thị lớn nhất được chấp nhận được dàn trong thời gian có giới hạn.
Lưu đồ Mermaid
Clark cũng có thể đưa cho show_view một lưu đồ Mermaid: { "mermaid": "flowchart LR ...", "title"?, "layout"? }. Node tự đọc một tập con được tài liệu hóa của cú pháp flowchart và chỉ giữ lại mô hình sơ đồ thu được. Node không bao giờ lưu mã nguồn Mermaid và không bao giờ tải renderer của Mermaid. Tập con gồm:
flowcharthoặcgraphvớiTB,TDhoặcLR;- node viết dạng
id,id[box],id(round),id{diamond}vàid((circle)); - liên kết
-->,---,<-->,-->|nhãn|và-- nhãn -->; - một cấp
subgraph, trở thành nhóm của node; node được nêu bên ngoài trước sẽ vào subgraph nêu nó sau đó, còn node được nêu trong hai subgraph bị từ chối; accTitlelàm tiêu đề. Chú thích%%vàaccDescrmột dòng được bỏ qua vì không vẽ gì.
Mã nguồn nêu quá 60 node hoặc 120 liên kết bị từ chối ngay khi vượt giới hạn. Mọi thứ cấu hình hoặc mở rộng renderer của Mermaid đều bị từ chối theo dòng, kèm lý do: click, href, call, style, classDef, class, :::, linkStyle, directive %%{init}%%, front matter, HTML hoặc mã entity trong nhãn, chuỗi Markdown, icon fa:, các hình node khác, các kiểu liên kết khác, chuỗi &, subgraph lồng nhau và các loại sơ đồ khác.
Chọn node và bàn phím
Chọn một node sẽ gửi diagram.select với { selectedId }. Node kiểm tra giá trị này với sơ đồ hiện tại và giữ nó trong trạng thái widget, nên lựa chọn vẫn còn sau khi tải lại; ID đã khôi phục mà sơ đồ không còn chứa sẽ bị bỏ qua.
Mỗi node là một nút, và chỉ một node nằm trong thứ tự tab. Phím theo chiều luồng (Xuống với TB, Phải với LR) đi theo một cạnh về phía trước, còn phím ngược lại đi theo cạnh quay về. Các phím ngang đi trong cùng một lớp, Home và End tới node đầu và node cuối. Enter hoặc Space chọn node đang có tiêu điểm, hoặc bỏ chọn nếu node đó đã được chọn, còn Escape bỏ chọn. Tên truy cập của node nói rõ nhãn, hình và nhóm, cùng các node nó dẫn tới, đến từ và nối với, mỗi node kèm nhãn của cạnh nối chúng (“dẫn tới Ship (yes)”). Node được chọn làm nổi các cạnh và node kề bằng độ dày nét và nét đứt chứ không chỉ bằng màu, và một vùng live thông báo thay đổi. Hình vẽ rộng giữ nguyên kích thước và cuộn bên trong thẻ, nên trang không bao giờ cuộn ngang. Sơ đồ không tự tạo chuyển động và theo cả hai theme.
Tài liệu semantic báo số node và cạnh, bố cục và hướng, cùng node được chọn với các node kề và nhãn cạnh của chúng. Phần thay thế dạng chữ, cũng hiện dưới hình vẽ, liệt kê mọi node cùng các cạnh đi ra của nó. Xem bộ đọc tập con Mermaid và tiêu chuẩn phát triển widget (§8.12).
Giới hạn hiện tại. Khi hai cạnh có nhãn cùng rời một node vào cùng một khoảng trống, các nhãn có thể nằm sát nhau; nhãn luôn tránh xa các node. Giống cây phân cấp, sơ đồ chưa thể được đặt làm một phần của giao diện Clark dựng sẵn.
Bản đồ
Khi Clark có những địa điểm cần cho bạn xem, nó có thể vẽ chúng trên bản đồ bằng canvas.map@1: các điểm có nhãn, các đường như lộ trình, và các vùng. Bản đồ được vẽ trên một bản đồ nền ngoại tuyến đi kèm ứng dụng, nên với thiết lập mặc định, bản đồ không gửi yêu cầu nào ra ngoài node của bạn và không ai biết bạn đang xem phần nào của thế giới.
Bản đồ nền là lớp đất liền tỷ lệ 1:110m của Natural Earth, phiên bản 5.1.2, thuộc phạm vi công cộng. Nó được tạo bởi một script build ghim SHA-256 của tệp nguồn, và bản đồ ghi công Natural Earth dưới mọi hình vẽ.
Bản đồ chứa những gì
Vị trí là [kinh độ, vĩ độ] theo WGS84, trong một tập con chặt của hình học GeoJSON: Point, LineString và Polygon, tức một đường bao với tối đa 15 lỗ, mỗi vòng đều khép kín. Một bản đồ chứa tối đa 200 đối tượng và tổng cộng 5.000 vị trí. ID dài tối đa 120 ký tự, nhãn 120, mô tả 300 và tiêu đề 200. Bản đồ tự khớp với các đối tượng của nó, hoặc một view tùy chọn dạng { center, zoom }, với mức zoom nguyên từ 0 đến 18, sẽ thay cho khung nhìn đã khớp. Mã hóa địa lý, tìm đường, vị trí thiết bị của bạn, vector tile, 3D, gom cụm và chỉnh sửa không thuộc widget này, và bản đồ không bao giờ hỏi vị trí của bạn.
Node từ chối một bản đồ trước khi nó được hiển thị, và nói rõ lý do: tọa độ nằm ngoài địa cầu, loại hình học không xác định, quá nhiều đối tượng hoặc vị trí, văn bản quá dài hoặc lặp lại, ký tự ẩn, và bất kỳ URL nào. Một khóa mang tên đường dẫn (url, href, src, tile, endpoint và những khóa tương tự) hoặc một giá trị là đường dẫn (https://, //, data:, javascript:, blob:) đều bị từ chối, nên props của bản đồ không bao giờ có thể nêu tên một máy chủ. Những địa điểm Clark đặt lên bản đồ là phát biểu của Clark, và bản đồ không mang huy hiệu “trực tiếp” nào.
Ô bản đồ, chỉ khi bạn chọn một nhà cung cấp
Ô bản đồ. Bản đồ luôn có nền ngoại tuyến và hoạt động đầy đủ mà không cần ô bản đồ, vốn tắt theo mặc định. Để thêm ô từ nhà cung cấp, mở Cài đặt → Tiện ích → Ô bản đồ và nhập origin, đường dẫn ô, ghi công và mức phóng to tối đa của nhà cung cấp. Việc này đặt chính sách ô bản đồ của node, tức preference maps.tilePolicy, nêu tên một nhà cung cấp. Nếu nhà cung cấp cần khóa, nhập khóa cùng header hoặc tham số truy vấn chứa nó. Khóa được gắn với origin bạn nhập nó cho: ClarkCant chỉ gửi khóa tới origin đó và không bao giờ hiển thị lại. Bạn cũng có thể nhờ Clark bật hoặc tắt ô bản đồ. Clark làm theo execution policy của bạn: ở chế độ Tự chủ, thay đổi diễn ra ngay và có thể hoàn tác trong Cài đặt; ở chế độ Hỏi mỗi lần, bạn duyệt trên một thẻ. Ở chế độ Có rào, việc đặt nhà cung cấp hỏi bạn trên một thẻ còn việc tắt ô bản đồ diễn ra ngay, và Từ chối tất cả từ chối cả hai. Clark không bao giờ chuyển được khóa của bạn. Nếu Clark đặt một nhà cung cấp cần khóa ở origin khác, bản đồ chỉ dùng nền ngoại tuyến cho tới khi bạn nhập lại khóa cho nhà cung cấp đó. GET /map-tiles cho biết lý do bản đồ chỉ dùng nền ngoại tuyến trong trường offline: no-provider, key-unavailable (chưa lưu khóa dùng được) hoặc key-origin-mismatch (khóa đã lưu thuộc origin khác).
Các AI client qua MCP, relay WebSocket và clarkcant api không thể ghi trực tiếp chính sách hay khóa: các route đó trả về 403 PERSON_ONLY, và client nào muốn đổi ô bản đồ thì nhờ Clark. Các route được liệt kê trong API của node.
- Node của bạn tự tải các ô bản đồ. Trang chỉ hỏi node của bạn và không bao giờ liên hệ nhà cung cấp, nên chính sách nội dung của trang không đổi.
- Chỉ một nhà cung cấp mà chính sách nêu tên được hỏi, ở mức zoom tới mức tối đa của nó (tối đa 19). Chuyển hướng không được đi theo.
- Chỉ ô PNG hoặc WebP được phục vụ, được kiểm tra bằng cả loại nội dung của nhà cung cấp lẫn chính các byte, mỗi ô tối đa 512 KiB.
- Yêu cầu bị giới hạn tốc độ ở 12 yêu cầu mỗi giây với đợt dồn tối đa 48, và tối đa 256 ô hoặc 24 MiB được lưu đệm trong một giờ.
- Khóa là secret riêng của node,
maps:tiles, được gắn với một origin. Node của bạn chỉ thêm nó, dưới dạng header hoặc tham số truy vấn, vào các yêu cầu tới origin đó. Nó không bao giờ tới trang, props hay trạng thái của bản đồ, log, khóa bộ đệm, thông báo lỗi hay mô hình. - Hiển thị ô bản đồ cho nhà cung cấp biết bạn đang xem vùng nào, nên dòng dưới bản đồ nêu tên origin của ô bản đồ và dòng ghi công của nó.
- Đặt chính sách về không có nhà cung cấp sẽ tắt ô bản đồ ngay lập tức: từ lúc đó node của bạn từ chối mọi yêu cầu ô bản đồ và không hỏi ai cả.
Lựa chọn, bàn phím và bảng
Chọn một đối tượng sẽ gửi map.select với { selectedId }, để trống để bỏ chọn, và di chuyển bản đồ sẽ gửi map.view với { center, zoom }. Node kiểm tra cả hai với bản đồ hiện tại và giữ chúng trong trạng thái widget, nên lựa chọn và khung nhìn vẫn còn sau khi tải lại. Một lần kéo được lưu 400 ms sau khi dừng, nên một loạt phím bấm chỉ là một lần ghi. Trong giao diện Clark dựng sẵn, map.select cũng là một sự kiện có trường selectedId mà các phần khác có thể theo.
Bản đồ có thể nhận tiêu điểm và dùng được bằng bàn phím:
- các phím mũi tên kéo bản đồ, và giữ Shift để kéo xa hơn;
- + và - phóng to, thu nhỏ, và 0 đặt lại khung nhìn;
- N và P đi qua lần lượt các đối tượng, còn Escape bỏ chọn.
Kéo bằng con trỏ cũng di chuyển bản đồ. Trên màn hình cảm ứng, vuốt qua một bản đồ bạn chưa chạm vào sẽ cuộn cuộc trò chuyện; khi bạn đã chạm vào bản đồ, kéo sẽ di chuyển nó. Các nút phóng to, thu nhỏ và đặt lại có kích thước 44 px. Một vùng live thông báo khung nhìn khi nó dừng lại, và cả lựa chọn. Bản đồ chỉ trượt khi chuyển động được cho phép; khi giảm chuyển động, khung nhìn đổi ngay lập tức. Bản đồ theo cả hai theme, và bản đồ hẹp chuyển các nút điều khiển xuống dưới hình và vẽ nhãn lớn hơn, không tràn ngang ở 390 px.
Dưới bản đồ, một bảng liệt kê mọi đối tượng cùng loại và vị trí của nó. Nút Chọn của bảng chọn đối tượng trên bản đồ và đưa nó vào khung nhìn, còn chọn trên bản đồ sẽ làm nổi hàng tương ứng. Bảng đó cũng là phần thay thế dạng chữ của bản đồ.
Tài liệu semantic báo số đối tượng và số lượng từng loại, ranh giới và mức zoom đang hiển thị, nhãn và tọa độ của đối tượng được chọn, và ô bản đồ đang ngoại tuyến hay đến từ origin của chính sách. Xem hợp đồng bản đồ và các giới hạn và tiêu chuẩn phát triển widget (§8.13).
Giới hạn hiện tại. Bản đồ là một thế giới duy nhất không lặp lại: khung nhìn dừng ở kinh tuyến đổi ngày, và bản đồ không cuộn vòng qua kinh tuyến 180°. Bản đồ nền, các đối tượng và ô bản đồ đều được vẽ một lần, nên chúng luôn khớp nhau.
Trình phát âm thanh và xem trước tài liệu
Clark có thể phát một âm thanh bằng canvas.audio@1 và hiển thị văn bản của một tệp PDF hoặc tệp văn bản bằng canvas.document@1. Trang không bao giờ tự tải gì cho cả hai widget này. Clark nêu tên một nguồn, còn node của bạn đọc nó, kiểm tra nó theo chính sách nội dung media và chỉ lưu những gì đã được kiểm tra.
Âm thanh đến từ đâu
Clark nêu đúng một nguồn, một tiêu đề và, nếu có, một bản chép lời dài tối đa 4.000 ký tự:
- Một tệp trong cuộc hội thoại này, theo ID artifact hoặc ID tệp đính kèm: một tệp WAV bạn đã gửi (loại tệp đính kèm
audio) hoặc một tệp WAV do service của một gói tạo ra; - Một URL
httpstrên một origin mà chính sách media của node cho phép. Node của bạn tải nó một lần, kiểm tra và giữ nó như một tệp đã niêm phong của cuộc hội thoại, cấp quyền cho trình phát, trong cùng một bước đặt trình phát. Về sau Clark có thể đặt lại tệp đó theo ID của nó, và node của bạn không tải lại.
Node của bạn tự điền tham chiếu mà trang phát, loại tệp, độ dài và kích thước, và với tệp được tải về thì cả origin nguồn. Clark không thể tự cung cấp những giá trị này, nên trình phát không bao giờ khai một loại tệp hay một độ dài mà không ai kiểm tra. Trang chỉ thấy tham chiếu đến một tệp do node của bạn giữ, không bao giờ thấy URL bên ngoài. 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 bạn đã có sẵn.
Phát âm thanh
Trình phát dùng các nút điều khiển sẵn có của trình duyệt, kể cả bàn phím: đưa tiêu điểm vào nó rồi nhấn Space để phát hoặc tạm dừng. Nó không bao giờ tự phát, kể cả khi mới xuất hiện hay khi được khôi phục. Nó giữ lại trạng thái đang phát hay không, vị trí đang nghe và độ dài, được ghi theo cùng cách như video, nên sau khi tải lại trang nó mở ở trạng thái tạm dừng đúng chỗ bạn đã dừng. Bản chép lời, nếu có, là văn bản thuần trong một mục bạn có thể mở bằng bàn phím, và ký tự ẩn trong đó được vẽ thành một dấu hiệu nhìn thấy được. Giọng nói, ghi chú thêm vào lượt hỏi kế tiếp và inspect_ui biết tiêu đề, trạng thái phát, vị trí và độ dài, và có bản chép lời hay không.
Xem trước tài liệu
Clark nêu tên một tệp PDF hoặc tệp văn bản trong cuộc hội thoại này (văn bản thuần, Markdown, CSV, giá trị phân tách bằng tab hoặc JSON), theo ID artifact hoặc ID tệp đính kèm. Node của bạn đọc văn bản của nó, với PDF thì qua bộ đọc riêng của node, và giữ tối đa 20.000 ký tự trong tối đa 10 trang, mỗi trang tối đa 2.000 ký tự, ngắt ở cuối dòng hoặc ở một khoảng trắng. Một thông báo cho biết khi bản xem trước bị cắt bớt và đang hiển thị bao nhiêu. Bản xem trước chỉ là văn bản: hình ảnh và bố cục không được hiển thị, và không gì trong tệp được coi là markup hay được chạy. Ký tự ẩn được vẽ thành dấu hiệu, kèm cảnh báo.
Văn bản của trang nằm trong một vùng mà bàn phím có thể tới. Tab chuyển tới các nút Trước và Sau, còn Enter lật trang. Ở trang đầu hoặc trang cuối, nút vẫn giữ tiêu điểm và được thông báo là không khả dụng, trang mới mở từ đầu, và số trang trên tổng số trang được thông báo một cách nhẹ nhàng. Trang bạn đang xem được lưu cùng widget, nên vẫn mở sau khi tải lại, và giọng nói, ghi chú cho lượt hỏi kế tiếp và inspect_ui đều biết nó. Tệp WAV không phải tài liệu, và bản xem trước từ chối nó.
Cả hai widget theo cả hai theme và vừa khít ở 390 px. Khi giảm chuyển động, chúng không thêm hiệu ứng động hay chuyển tiếp nào. Hiện chưa widget nào có thể được đặt làm một phần của giao diện Clark dựng sẵn: mỗi widget được hiển thị riêng, nơi node của bạn kiểm tra nguồn của nó. Thư viện Widget hiển thị các thẻ mẫu; thẻ âm thanh mẫu nói rằng nó không phát được thay vì giả vờ.
Chính sách nội dung media
Node của bạn chỉ tải âm thanh từ web về từ những origin bạn liệt kê trong CC_MEDIA_ORIGINS, 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. Danh sách này mặc định để trống, nên node của bạn không tải gì cho tới khi bạn nêu tên một origin. Một danh sách có bất kỳ mục nào không phải origin https trần sẽ bị bỏ qua toàn bộ: node của bạn không cho phép gì và nói lý do một lần khi khởi động. Mỗi lần tải tuân theo các quy tắc sau:
- Chỉ
https, không có tên người dùng hay mật khẩu trong URL. - Chuyển hướng chỉ được đi theo trong cùng một origin, tối đa 3 lần.
- Mộ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 bị từ chối, được kiểm tra trên đúng địa chỉ thực sự được kết nối. Một origin bạn viết dưới dạng địa chỉ hoặc
localhostchỉ đúng địa chỉ đó và được cho phép. - Không gửi cookie, thông tin xác thực hay referrer.
- Chỉ âm thanh MP3, Ogg, WAV hoặc WebM, được kiểm tra dựa trên chính các byte; truyền tải có nén bị từ chối.
- Tối đa 25 MiB và dài một giờ. Tệp không nêu độ dài của nó bị từ chối, vì một giới hạn không kiểm tra được thì không phải là giới hạn. Toàn bộ lần tải phải xong trong 30 giây.
Mỗi lần từ chối kết thúc bằng quy tắc bị vi phạm, dạng (media policy rule: <rule>), để Clark có thể nói cho bạn biết cần đổi gì. Tệp vượt qua kiểm tra được tính vào dung lượng lưu trữ của bạn. Chính sách nội dung của trang không đổi. Xem tên các quy tắc, hợp đồng nội dung media và tiêu chuẩn phát triển widget (§8.14 và §14.5).
Giới hạn hiện tại. Khi một cuộc hội thoại được tải, trang đọc toàn bộ tệp của mọi trình phát đã đặt, dù nó không phát gì cho tới khi bạn nhấn phát; việc chỉ đọc khi cần được theo dõi ở #403. Mỗi lần lưu vị trí phát là một lần ghi trọn trạng thái widget, chi phí này được theo dõi ở #380.
Ảnh và video trong hội thoại
Gallery hoặc carousel giữ lại ảnh bạn đã chọn. Lựa chọn được lưu cùng widget, nên vẫn còn sau khi tải lại trang hoặc khôi phục pin. Video cục bộ giữ lại trạng thái đang phát hay không, vị trí đang xem và độ dài. Khi mở lại, video dừng ở đúng vị trí đó và không bao giờ tự phát.
Clark biết bạn đang xem gì. Giọng nói, ghi chú thêm vào lượt hỏi kế tiếp và công cụ inspect_ui của Clark mô tả ảnh đang chọn (ảnh thứ mấy trên tổng số, kèm văn bản thay thế) hoặc trạng thái phát của video. Khi video đang phát, vị trí được lưu tối đa ba giây một lần, và lưu ngay khi bạn tạm dừng, tua hoặc video kết thúc. Việc lưu khi bạn rời trang chỉ là cố gắng tốt nhất, nên trạng thái “đang phát” cũ hơn tám giây được báo là đã dừng tại vị trí lưu gần nhất. Nếu máy của bạn từ chối một lần lưu, widget nói lý do ngay bên cạnh: gallery hoặc carousel hiện lại ảnh đã lưu, còn video giữ nguyên vị trí.
Giao diện Clark dựng cho bạn có thể chứa gallery hoặc carousel gồm chính các ảnh bạn đã nhập, mới nhất trước. Clark chỉ chọn widget và cách nối nó; ảnh Clark tự nêu sẽ bị bỏ qua. Chọn một ảnh sẽ gửi media.select với { selectedIndex }, đếm từ 0, nên phần khác của giao diện nối cùng giá trị đó sẽ đi theo và trạng thái của giao diện báo lại giá trị này.
Chính sách của trang và cửa sổ desktop cho phép media-src 'self' blob:, chỉ để video phát được từ object URL mà ứng dụng tạo ra từ dữ liệu đã tải bằng token của node. Không cho phép nguồn media từ xa và không cho phép media data:.
Giới hạn hiện tại. Node chưa nhập được tệp video, nên video cục bộ chỉ phát từ tham chiếu mà node đã phục vụ sẵn. Gallery hoặc carousel trong giao diện dựng sẵn giữ các ảnh có mặt lúc giao diện được dựng; ảnh nhập sau chỉ xuất hiện trong giao diện dựng mới. Mỗi lần lưu vị trí phát vẫn là một action đầy đủ của widget; việc giảm chi phí này được theo dõi ở #380. Xem tiêu chuẩn phát triển widget (§8.11).
Bắt đầu nhanh
- Chạy một node. Trình cài đặt sẽ dựng sẵn; từ bản checkout thì chạy
node apps/runtime/src/main.ts. Node nghe ởhttp://127.0.0.1:8765, mặc định chỉ trên loopback. - Lấy token: trường
localTokentrong<data-dir>/identity.json. Thư mục dữ liệu mặc định là~/.clarkcant; với Docker thư mục dữ liệu là/data(token trong/data/identity.json). - Kiểm tra node và khám phá các giao diện của nó. Ba route này không cần token:
export CLARKCANT_URL="http://127.0.0.1:8765"
export CLARKCANT_TOKEN="<token>" # localToken from <data-dir>/identity.json
# Public: no token needed
curl -s "$CLARKCANT_URL/health"
curl -s "$CLARKCANT_URL/.well-known/clarkcant.json"
curl -s "$CLARKCANT_URL/openapi.json"
/health báo node còn sống, nền tảng runtime và giao thức đã thương lượng, không kèm danh tính node. /.well-known/clarkcant.json liệt kê mọi giao diện (api, mcp, websocket, cli) và endpoint của chúng. /openapi.json mô tả phần REST ổn định.
Rồi gửi cho Clark tin nhắn đầu tiên:
# 1. Create a conversation → 201 { "conversationId": "…", "homeNodeId": "…" }
curl -s -X POST "$CLARKCANT_URL/conversations" \
-H "Authorization: Bearer $CLARKCANT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "From my app" }'
# 2. Talk to Clark in it
curl -s -X POST "$CLARKCANT_URL/conversations/<conversationId>/messages" \
-H "Authorization: Bearer $CLARKCANT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "text": "What can you do on this machine?" }'
Xác thực và lỗi
- Mọi route, trừ ba route công khai, đều cần
Authorization: Bearer <token>. WebSocket thì gửi token trong frame đầu tiên. - Thiếu token hay sai token đều trả về
401 UNAUTHENTICATED. - Lỗi là JSON kèm mã trạng thái HTTP:
{ "code": "UNAUTHENTICATED", "message": "…" }
Giữ kín token. Token cho toàn quyền với Clark của bạn. Mặc định node chỉ lắng nghe trên loopback; --allow-public-bind mở nó ra ngoài và cần TLS đứng trước. Chưa có đăng nhập OAuth: bearer token là thông tin xác thực duy nhất.
Clark chọn ngữ cảnh thế nào
Các biến môi trường sau trên node chọn ngữ cảnh mà Clark gửi cho model cùng mỗi tin nhắn:
CLARKCANT_CONTEXT_PLANNER(mặc định bật): Khi bật, bản ghi nhớ và phần tóm tắt cho session mới tập trung vào tin đang được trả lời. Các tin cũ hơn trong hội thoại mà khớp sẽ đến với model dưới dạng dữ liệu có ghi rõ ai nói, không bao giờ là chỉ dẫn. Việc chạy nền và task worker do bạn khởi động có thể đọc cùng ngữ cảnh đó khi cần.offtrả lại phần tóm tắt cố định (12 tin mới nhất) và bản ghi nhớ cố định (12 ghi nhớ mới nhất), và thôi đưa ngữ cảnh đã truy xuất cho việc chạy nền và task worker. Hai cải tiến vẫn giữ ở cả hai chế độ: bản ghi nhớ không đọc được thì lượt chạy tiếp mà không có nó thay vì thất bại, và một lượt có thể được dừng trong lúc đang đọc ngữ cảnh. Phần tóm tắt cũng đọc 40 tin mới nhất ở cả hai chế độ. Chỉ việc do một người yêu cầu trong hội thoại mới được nhận ngữ cảnh đã truy xuất; task do node khác uỷ cho, do một tự động hoá khởi chạy hay do chính node tạo ra thì không.CLARKCANT_CONTEXT_DECIDER(mặc địnhrank):jevcho Jev, bộ chọn của node, chỉ chọn trong các lựa chọn node đã cho phép và không bao giờ cấp quyền gì (cách cấu hình), sắp lại 8 kết quả khớp nhất khi thứ hạng sát nhau và câu trả lời có thể đổi điều được gửi đi. Khi đang mở dần tool, Jev còn có thể chọn một nhóm tool cho tin đầu tiên không nhắc nhóm nào. Lỗi hay hết giờ thì giữ thứ tự tất định. Giá trị khác làrank.CLARKCANT_TOOL_DISCLOSURE(mặc địnhall):progressiveđưa các tool lõi cùng các nhóm tool mà tin nhắn nhắc tới, chỉ tăng thêm trong một session. Vẫn tắt vì ước tính offline, trong mẫu, cho thấy tốn hơn khoảng 7% khi tính cả việc ghi lại prompt cache. Giá trị khác làall.
Nội dung gửi tới provider của Jev (chỉ khi CLARKCANT_CONTEXT_DECIDER=jev và chỉ khi Jev được hỏi): tin đang được trả lời, đã che thông tin nhạy cảm, tối đa 300 ký tự (400 ký tự khi chọn nhóm tool), cùng từng ghi nhớ hay tin cũ hơn là ứng viên mà toàn bộ là public hoặc internal, đã che, tối đa 200 ký tự. Không có gì khác rời khỏi node, và Jev không cấp quyền gì.
Chọn provider cho bộ quyết định
Theo mặc định, Jev của TypeSafe trả lời bộ chọn của node bạn. Bộ chọn tách biệt với model hội thoại: nó chỉ trả lời các câu hỏi nhỏ có kiểu mà Clark đặt ra khi dựng câu trả lời. Thay cho Jev, bạn có thể chọn Cloudflare Clef trên Workers AI, hoặc một model quyết định qua decisions API của OpenRouter. Chính sách của Clark (những gì được đưa ra, những gì được che, các ngưỡng, thời gian cho phép và mọi đường quay về) giống nhau dù provider nào trả lời, và mọi provider nhận cùng một yêu cầu đã che; chỉ endpoint, credential và model được ghim là khác. Đổi provider là đổi bên nhận yêu cầu đó, nên đây là quyết định chia sẻ dữ liệu chứ không chỉ là quyết định kỹ thuật. Với OpenRouter có hai bên nhận: OpenRouter, và công ty phục vụ model bạn chọn.
Chọn trong Cài đặt. Mở Cài đặt → AI & Định tuyến → Nhà cung cấp quyết định, cạnh mục Đăng nhập nhà cung cấp và tách biệt với model hội thoại. Mục này cho thấy provider và model đang có hiệu lực, một nhãn cho biết cái gì đã chọn chúng (Cài đặt, môi trường hay mặc định), trạng thái (sẵn sàng, chỉ cục bộ, cấu hình sai, chưa có khoá, hoặc đã tắt) kèm lý do và việc cần làm, cùng lần gọi gần nhất kể từ khi node khởi động. Chọn Theo môi trường, TypeSafe Jev, Cloudflare Clef hoặc OpenRouter. Cloudflare có thêm hai model và một ô account id; OpenRouter có thêm một ô model slug, và chưa có gì được lưu cho tới khi bạn nhập một slug được ghim (các router của chính OpenRouter, như openrouter/auto, bị từ chối). Mỗi provider có một thẻ key cho biết key đến từ đâu (lưu trên thẻ, lưu trong Thông tin xác thực với TypeSafe, môi trường, hoặc chưa có). Thẻ Cloudflare và OpenRouter có nút Lưu và Gỡ; key bạn nhập được xoá khỏi ô sau khi lưu và không bao giờ hiện lại. Key TypeSafe chỉ có một chỗ là danh sách Thông tin xác thực trên cùng tab, nên thẻ TypeSafe không có ô riêng và nút Mở Thông tin xác thực của nó đưa focus vào ô key của dòng đó. Lưu hoặc gỡ key ở đó sẽ cập nhật thẻ ngay, không cần tải lại trang. Một lý do mà ứng dụng chưa biết được hiện thành một thông báo chung bằng ngôn ngữ của bạn. Lựa chọn này thắng các biến môi trường bên dưới, và chọn "theo môi trường" sẽ trả quyền chọn về cho chúng. Thay đổi có hiệu lực từ quyết định kế tiếp; node không khởi động lại. Cùng lựa chọn đó cũng có qua API của node, và chỉ con người mới được thực hiện: một AI client hay một bề mặt máy khác không thể chọn bên thứ ba nào nhận quyết định.
GET /decision-provider: provider và model đang có hiệu lực, cái gì đã chọn chúng, key lấy từ đâu (vault,environmenthoặcnone, không bao giờ là key), lời gọi có được thực hiện không và vì sao không, cùng kết quả của lời gọi gần nhất. Mỗi lý do, ở trạng thái lẫn ở lời gọi gần nhất, đều kèm mộtreasonCodeổn định (ví dụno-credential,budget-exhaustedhoặcprovider-rejected-key) để client diễn đạt bằng ngôn ngữ của người dùng;reasontiếng Anh đi kèm dành cho log. Client gặp một mã không biết nên hiện một thông báo chung.PUT /decision-providervới{"selection": {"provider": "cloudflare", "model": "clef"}},{"selection": {"provider": "openrouter", "model": "cloudflare/clef-flash"}},{"selection": {"provider": "typesafe"}}, hoặc{"selection": null}để theo môi trường.PUT /decision-provider/credentialvới{provider, value}lưu một key, vàDELETE /decision-provider/credential/<provider>xoá nó. Key của Cloudflare và OpenRouter lưu ở đây chỉ được dùng cho quyết định, và biểu mẫu credential chung từ chối tên của chúng.
Chọn trong môi trường. Người vận hành cấu hình node mà không qua Cài đặt dùng các biến sau:
CLARKCANT_DECISION_PROVIDER(mặc địnhtypesafe):typesafe(Jev),cloudflare(Clef) hoặcopenrouter. Giá trị khác làm mọi lời gọi quyết định bị từ chối thay vì quay về TypeSafe.CLARKCANT_DECISION_MODEL: id chính xác của model. Với Cloudflare, biến này bắt buộc và phải làclefhoặcclef-flash. Với OpenRouter, biến này bắt buộc và phải là một slug được ghim nhưcloudflare/clef-flashhaytypesafe/jev-1.13; alias~và các router của chính OpenRouter (openrouter/auto) bị từ chối, vì một router không bao giờ trả lời như một model được ghim. Với TypeSafe, khi được đặt nó thắngCLARKCANT_JEV_MODEL(mặc địnhjev-1.13.0), và một id model của provider khác ở đây bị từ chối trước mọi lời gọi.TYPESAFE_API_KEY: credential của TypeSafe. Key lưu trong Cài đặt (danh sách Thông tin xác thực trong AI & Định tuyến) thắng biến này.CLOUDFLARE_ACCOUNT_ID: chỉ cho Cloudflare, 32 ký tự thập lục phân. Endpoint được dựng từ giá trị này và không ghi đè được. Account id lưu trong Cài đặt thắng biến này.CLOUDFLARE_API_TOKEN: chỉ cho Cloudflare, một token được phép chạy Workers AI. Token lưu trong thẻ Cloudflare của decision provider thắng biến này. Key của TypeSafe không bao giờ được dùng thay, và token được giữ ngoài các lệnh mà model chạy, như các key nhà cung cấp khác.OPENROUTER_API_KEY: chỉ cho OpenRouter. Key lưu trong thẻ OpenRouter của decision provider thắng biến này. Quyết định chỉ dùng nó khi OpenRouter là decision provider được chọn.
CLARKCANT_DECISION_PROVIDER=cloudflare
CLARKCANT_DECISION_MODEL=clef # or clef-flash
CLOUDFLARE_ACCOUNT_ID=<account-id> # 32 hexadecimal characters
CLOUDFLARE_API_TOKEN=<token> # allowed to run Workers AI
# or
CLARKCANT_DECISION_PROVIDER=openrouter
CLARKCANT_DECISION_MODEL=cloudflare/clef-flash # a pinned slug
OPENROUTER_API_KEY=<key>
Thay đổi môi trường, kể cả CLARKCANT_JEV_LOCAL_ONLY và CLARKCANT_JEV_ENABLED, vẫn cần khởi động lại, và không gì trong Cài đặt có thể gỡ chế độ local-only.
Khi provider không dùng được, node của bạn quay về đường tất định và nói rõ điều đó. Thiếu credential, cấu hình sai dạng, CLARKCANT_JEV_LOCAL_ONLY=1 (từ chối mọi provider), một credential còn sót trong yêu cầu, hết giờ, lỗi hay một câu trả lời không đáng tin đều kết thúc giống nhau: lời gọi được báo là không dùng được kèm lý do, không được thử lại, và công việc tiếp tục theo đường tất định. Bề mặt được dựng mà không cần bộ chọn, tìm kiếm xếp hạng bằng BM25 và ngữ cảnh giữ thứ tự đã xếp hạng. Khi khởi động, node in một dòng về bộ chọn, ví dụ selector: clef-flash pinned on cloudflare, 4000 ms per turn hoặc selector: disabled (no credential or local-only); composed surfaces use the deterministic path. Các dòng telemetry và bản ghi quyết định đã lưu chỉ nêu provider khi đó không phải TypeSafe. Xem cấu hình bộ chọn.
Lời gọi quyết định chỉ mang nội dung public và internal. Dù provider nào trả lời, nội dung do người dùng, một tệp hay một bản ghi cung cấp chỉ được thuộc hai class đó, và mọi thứ vượt mức này bị bỏ ra trước khi dựng yêu cầu, không bao giờ gửi đi rồi mới lọc. Một ứng viên đại diện cho dữ liệu của bạn (một kết quả tìm kiếm, một ghi nhớ hay một tin cũ hơn) chỉ được đưa ra khi toàn bộ bản ghi nằm trong giới hạn đó; khi còn lại ít hơn hai kết quả tìm kiếm, thứ hạng được giữ nguyên và không provider nào được hỏi. Văn bản tự do (lời của bạn, tên thư mục, một mô tả, các quy tắc guardrail của chính bạn) được che, cắt rồi kiểm tra lại, và văn bản vẫn vượt internal được gửi đi dưới dạng rỗng. Khi điều đó làm rỗng chính tin nhắn hay truy vấn cần quyết định, không provider nào được hỏi và node của bạn giữ câu trả lời thông thường: thứ hạng của chính nó, mọi nhóm tool, hoặc không thay đổi lượt. Những gì node của bạn tự viết được miễn, vì một model id có ngày tháng trông như số điện thoại: các định danh như id lựa chọn, ref và con số đếm, các chỉ dẫn cố định của node, và các mô tả trong danh mục như alias (provider/modelId) của một tuyến model, nhãn của một template hay mô tả của một nhóm tool. Bước kiểm tra credential vẫn áp dụng cho chúng.
Giới hạn kích thước. Yêu cầu lớn hơn 64 KiB sau khi tuần tự hoá không được gửi. Body lỗi của provider không bao giờ được đọc: nó bị huỷ mà không đọc, và không bao giờ được trả về, ghi log hay lưu lại. Câu trả lời lớn hơn 256 KiB không được đọc quá giới hạn và bị coi là sai dạng, bất kể provider hay transport nào đưa nó về. Mỗi trường hợp đều quay về như mô tả ở trên.
Chuyển về TypeSafe. Chọn TypeSafe (hoặc "theo môi trường") trong Cài đặt, hoặc bỏ CLARKCANT_DECISION_PROVIDER (hoặc đặt thành typesafe) rồi khởi động lại. Một surface do provider khác chọn vẫn được phát lại mà không hỏi provider nào, và bản ghi của nó vẫn nêu provider và model đó. Còn hạ chính node về một bản phát hành cũ hơn thì khác: bản phát hành không biết provider đó sẽ không đọc được surface nó đã chọn, nên phát lại hay làm mới surface đó sẽ thất bại. Hãy chuyển provider về trước, và giữ một bản phát hành đọc được các surface đó chừng nào chúng còn cần.
Đã kiểm tra trực tiếp ngày 2026-10-08, chỉ với yêu cầu tổng hợp. Cloudflare clef và clef-flash trả lời đúng cả khi gọi trực tiếp lẫn qua OpenRouter. Hôm đó TypeSafe Jev không trả lời kịp, cả trực tiếp lẫn qua OpenRouter, nên chưa có kết quả trực tiếp mới cho nó. OpenRouter đánh dấu decisions API của họ là alpha. Các benchmark Clef so với Jev là số liệu của nhà cung cấp trên khối việc của họ, nên TypeSafe vẫn là mặc định.
Model được nhận những gì
Mỗi khối node của bạn thêm vào ngữ cảnh của một model được gắn nhãn public, internal, confidential hoặc secret, chỉ từ chính văn bản của nó và trước khi bất cứ thứ gì được xếp hạng hay gửi đi:
secret: dạng credential, như bearer token, JWT, khoá riêng PEM, AWS access key id, token API của GitHub hoặc Google, mật khẩu trong URL, token có tiền tố phát hành (sk-,ghp_,xoxb-…) hoặc giá trị gán cho một trường mang tên bí mật. Code ở vị trí đó không phải giá trị: lời gọi schema nhưz.string(), một kiểu, một tham chiếu thành viên hoặc placeholder (${…},{{…}},<…>), trong một trường hay một URL.confidential: địa chỉ email, số điện thoại hoặc đường dẫn thư mục home.internal: mọi thứ khác người dùng hoặc Clark viết, kể cả định danh trong code nhưtoken_refresh_worker_2, mã commit và digest. Ghi nhớ được che thông tin nhạy cảm khi ghi nên được đọc làinternal.
Một model profile có thể nêu nó được nhận gì bằng trustClass (local, first-party, approved-third-party hoặc untrusted) và allowedDataClasses. Theo trust class, local được nhận mọi thứ, kể cả secret; first-party và approved-third-party tới confidential; untrusted chỉ public. Có cả hai thì profile chỉ nhận những gì cả hai cho phép. Một danh sách không kèm trust class được lấy đúng như đã viết, nên nó có thể thêm secret cho một profile chưa gắn nhãn. Profile không có cả hai được nhận mọi thứ trừ secret, và một model được nhiều profile nêu chỉ nhận những gì tất cả cho phép.
Khi CLARKCANT_CONTEXT_PLANNER bật, khối vượt trần của model đang trả lời bị bỏ khỏi phần tóm tắt, bản ghi nhớ, các tin cũ hơn, ngữ cảnh mà việc chạy nền hay task worker truy xuất (kể cả các lần đọc read_context), hướng dẫn dự án và kết quả của search_history, mỗi kết quả được xét trên toàn bộ mục đã lưu, không chỉ đoạn trích hiển thị. Mỗi chỗ chỉ báo số khối bị giữ lại, không bao giờ báo nội dung, và phần tóm tắt không chỉ tới công cụ nào để đọc lại chúng. Jev chỉ được đưa ứng viên public và internal.
Việc chạy nền bỏ qua model profile không được nhận mức dữ liệu của công việc (mức của yêu cầu hoặc mục tiêu task), dù planner bật hay tắt. Khi không profile nào đạt, hoặc việc định tuyến thất bại, công việc chỉ quay về model đã cấu hình của node nếu model đó được nhận những gì công việc gửi đi, và ngữ cảnh đã truy xuất được thu hẹp theo model đó trước. Khi chính mức dữ liệu làm mọi profile bị loại, node ghi một dòng JSON trên stderr (model-route, chỉ gồm mức dữ liệu và số đếm); khi chính việc định tuyến thất bại, dòng đó được đánh dấu route-failed và không chứa nội dung lỗi. Khi cả model được định tuyến lẫn model đã cấu hình đều không được nhận công việc, công việc không bắt đầu và không có gì được gửi đi: việc chạy nền thất bại với một câu nêu mức dữ liệu, nói rằng chưa có gì được gửi và bạn có thể thay đổi gì, còn task bị từ chối trước khi worker của nó khởi động, kèm một bản ghi audit chỉ nêu model và mức dữ liệu.
Khi một tin nhắn không được gửi
Trần là giới hạn cứng cho những gì một model được gửi, không phải một ưu tiên định tuyến. Một phép kiểm tra chạy ngay trước mỗi lần gửi, với chính model sắp nhận, dù model đó được chọn theo cách nào. Phép kiểm tra chỉ áp dụng cho confidential và secret: mỗi mức trong hai mức này mà yêu cầu mang theo đều phải được phép với model đó. public và internal định hướng việc định tuyến và ngữ cảnh được thu thập, nhưng không bao giờ chặn một tin nhắn, nên một profile chỉ được nhận public vẫn trò chuyện bình thường được.
Một tin nhắn mang dữ liệu confidential hoặc secret mà model đã chọn không được nhận sẽ không được gửi, và Clark không tự chuyển nó sang model khác thay bạn. Câu trả lời nói mức dữ liệu nào đã chặn nó, rằng chưa có gì được gửi, rằng tin nhắn và lựa chọn model của bạn vẫn được giữ, và bạn có thể thay đổi gì:
- chọn một model được nhận mức đó, chẳng hạn một model chạy trên chính máy này;
- cho phép mức đó với model này trong Cài đặt → AI & Định tuyến;
- hoặc gửi lại tin nhắn mà không có phần đó.
Bằng tiếng Việt, câu đó ví dụ như: “Tin nhắn này có dữ liệu mức confidential, mà {model} không được nhận dữ liệu mức đó, nên không có gì được gửi tới model. Tin nhắn của bạn đã được lưu và model bạn chọn vẫn giữ nguyên. Để tiếp tục, hãy chọn một model được nhận dữ liệu mức confidential (ví dụ một model chạy trên máy này), cho phép mức confidential cho model đó trong Cài đặt → AI & Định tuyến, hoặc gửi lại mà không có phần đó.”
Nếu không đọc được trần của model, câu trả lời nói rõ điều đó thay vì nêu một trần nào; tin nhắn bình thường vẫn được gửi, còn tin nhắn mang dữ liệu confidential hoặc secret thì không. Khi provider từ chối một lượt và Clark chuyển sang model dự phòng, model đó cũng được kiểm tra như vậy; nếu nó không được nhận tin nhắn, bạn đọc được cả lý do model đã chọn không trả lời lẫn lý do model dự phòng không được gửi tin nhắn. Mỗi lần từ chối ghi một dòng trên stderr (model-send-blocked) nêu mức dữ liệu và model, không bao giờ nêu nội dung.
Credential bị từ chối theo mặc định. Profile không có danh sách được nhận mọi thứ trừ secret, nên một chuỗi có dạng credential (API key, mật khẩu, bearer token, thông tin xác thực HTTP Basic, key SendGrid) bị từ chối thay vì được gửi tới model bên thứ ba. Placeholder hiển nhiên như your_api_key, changeme, example hay xxxx không bị coi là credential; một giá trị có chữ số, hoặc bất kỳ giá trị nào khác trông như thật, thì vẫn bị coi là credential. Thông tin xác thực trong một URL như postgres://app:<password>@db.example.com không bị đọc thành địa chỉ email.
Phép kiểm tra bao trùm mọi thứ một lượt gửi đi: lời của bạn (kể cả nội dung của tệp văn bản đính kèm), phần tóm tắt, bản ghi nhớ, tham chiếu, hướng dẫn dự án, các tin cũ hơn và những gì đang hiện trên màn hình, một câu được nhập (steer) vào câu trả lời đang viết, và mọi kết quả công cụ cùng lỗi công cụ được trả lại cho model. Nó cũng bao trùm yêu cầu của việc chạy nền cùng ngữ cảnh việc đó truy xuất, và mục tiêu cùng hướng dẫn dự án của một task trước khi worker của nó khởi động. Ba phần được xử lý mà không chặn tin nhắn:
- Kết quả công cụ. Kết quả công cụ vượt trần của model đang trả lời bị giữ lại không cho model thấy, model chỉ đọc một ghi chú rằng nó bị giữ lại vì mức dữ liệu, và mọi hình ảnh trong đó bị bỏ. Điều này áp dụng cả cho việc đọc tệp trong thư mục dự án đã được cấp quyền: các kết quả đó nêu đường dẫn tuyệt đối đã đọc, nên một tệp trong thư mục home là
confidential. Bạn vẫn thấy kết quả thật trong cuộc trò chuyện. - Hướng dẫn cá nhân của bạn. Nếu chúng mang một mức mà model không được nhận, chúng bị bỏ khỏi tin nhắn đó, và tin nhắn vẫn được gửi.
- Tệp ngữ cảnh của dự án. Một tệp
AGENTS.mdhoặcCLAUDE.md, mộtSYSTEM.md, một kỹ năng hay một prompt template mang mức mà model của session không được nhận sẽ không được nạp cho model đó. Vì vậy một kỹ năng nằm trong thư mục home bị bỏ với model không được nhậnconfidential. Mỗi session một lần, thẻ model của câu trả lời kế tiếp cho bạn biết tệp nào, và hướng dẫn của chính bạn có bị bỏ hay không, chỉ bằng tên tệp và mức dữ liệu.
Phạm vi. Ranh giới này không áp dụng cho nội dung hình ảnh, vốn không được phân loại (hình ảnh chỉ bị bỏ cùng một kết quả bị giữ lại); văn bản agent tự đưa vào system prompt của nó, như thư mục làm việc, đường dẫn của một tệp ngữ cảnh và mô tả công cụ; extension Pi gốc, vốn là code tin cậy trên máy của bạn; hay những gì một session đã giữ từ các lượt trước khi trần của một profile bị thu hẹp trong lúc session đó tiếp tục. CLARKCANT_CONTEXT_PLANNER=off tắt việc giữ lại, kể cả với search_history, nhưng phép kiểm tra vẫn chạy, nên một lượt mà phần tóm tắt, bộ nhớ hay lịch sử mang mức vượt trần của model đang trả lời sẽ bị từ chối thay vì được gửi. Định tuyến theo mức dữ liệu áp dụng dù planner bật hay tắt. Trần quyết định model được gửi những gì, không bao giờ quyết định model được gọi công cụ nào.
Hướng dẫn dự án
Một dự án có thể giữ hướng dẫn chỉ áp dụng cho một phần của nó. Node của bạn chỉ đọc chúng từ một dự án nằm trong thư mục bạn đã cấp quyền: .clarkcant/instructions.json chứa tối đa 32 rule, và mỗi tên được include là tệp .clarkcant/instructions/<name>.md.
{
"version": 1,
"rules": [
{
"when": { "path": "src/payments/**", "operation": "write" },
"include": ["payments"],
"pin": false
}
]
}
whencó thể khớp theopath,operation,capability,role,skillvàproject.operationlàread,write,test,deployhoặccommand.pathlà glob tương đối với dự án.**đứng thành một đoạn thì đi qua nhiều thư mục, và mẫu không có/khớp tên tệp ở bất cứ đâu. Chữ hoa thường được gộp trên Windows và macOS, giữ nguyên trên Linux và mọi nền tảng khác, cả trong glob lẫn khi node tìm thư mục đã cấp quyền chứa một đường dẫn: trên Windows và macOS, một đường dẫn gõ khác chữ hoa thường so với thư mục bạn đã cấp vẫn nhận được hướng dẫn của nó. Việc một đường dẫn có nằm trong một dự án hay không, và đó là dự án nào, được quyết định theo đường dẫn thật trên ổ đĩa, nên trên một ổ phân biệt chữ hoa thường, hai thư mục có tên chỉ khác nhau về chữ hoa thường vẫn là hai dự án. Một glob dài quá 200 ký tự, có hơn 16 ký tự đại diện hoặc hơn 32 đoạn sẽ làm rule của nó bị bỏ, và một rule làm tổng số ký tự glob của tệp vượt 4.000 cũng bị bỏ;clarkcant instructions checkbáo cả hai, cùng với mọi lỗi khác trong tệp. Việc so khớp luôn có giới hạn, dù tệp viết gì: một đường dẫn cần nhiều hơn ngân sách so khớp, hoặc dài quá 4.096 ký tự, không thỏa điều kiệnpathnào, nên hướng dẫn có thể bị thiếu nhưng không bao giờ được nêu cho một đường dẫn mà nó không nói tới. Mỗi lần hỏi chỉ kiểm tra tối đa 96 đường dẫn được chạm: 64 đường dẫn gần nhất của session và tối đa 32 chỗ mà tin nhắn trỏ tới.- Rule áp dụng khi những gì công việc chạm tới khớp với nó: tệp và thư mục tin nhắn tham chiếu (tính là đọc), đường dẫn trong các tool call của hội thoại (đường dẫn của tool tệp, thư mục làm việc của lệnh), và với task là các thư mục nó được cấp, thư mục ghi được tính là ghi.
- Khi một tool call làm rule áp dụng, hướng dẫn được nối vào kết quả của chính call đó; nếu không thì nó vào lượt kế tiếp. Hướng dẫn không ghim được nêu một lần mỗi session. Hướng dẫn ghim (
"pin": true) được nêu lại mỗi lượt nó còn áp dụng, nên nó còn sau một phần tóm tắt hay một lần dựng lại session. Task worker nhận các hướng dẫn ứng với quyền được cấp khi bắt đầu. - Sau khi phân giải liên kết, dự án phải nằm trong thư mục đã cấp, còn tệp rule, thư mục instructions và từng hướng dẫn phải nằm trong dự án. Liên kết dẫn ra ngoài đều bị bỏ qua.
- Tệp là một contract có phiên bản: tệp phải có
"version": 1. Tệp cũ chưa có phiên bản vẫn được đọc như phiên bản 1, và khóa$schemacủa trình soạn thảo được chấp nhận. Tệp có phiên bản mới hơn sẽ không được đọc cho tới khi bạn cập nhật ClarkCant. Mọi khóa lạ khác ở cấp cao nhất khiến tệp không được đọc, còn một khóa lạ bên trong một rule chỉ làm bỏ qua rule đó. clarkcant instructions check [file|folder]kiểm tra một tệp, hoặc tệp.clarkcant/instructions.jsoncủa một thư mục dự án, theo đúng contract mà node của bạn dùng để đọc. Lệnh chạy ngoại tuyến, không cần node, và báo từng lỗi trên một dòng riêng, kể cả khi phiên bản cần một bản ClarkCant mới hơn. Lệnh cũng cảnh báo khi một rule include một tên không có tệp.md; cảnh báo không làm thay đổi mã thoát.
Hướng dẫn đến với model dưới dạng dữ liệu của dự án: một tiêu đề nói rằng chúng đến từ tệp .clarkcant của dự án, không phải lời của bạn hay của node, và không cấp quyền gì. Mỗi hướng dẫn được bọc trong một thẻ mang một mã node của bạn tạo một lần cho mỗi session (session được dựng lại hoặc được bàn giao sẽ có mã mới) và nêu một lần, trong chính lời hướng dẫn của node ở đầu session đó, như mã duy nhất đánh dấu hướng dẫn dự án; brief của task worker tự nêu mã của nó. Một hướng dẫn không thể tự đóng khối của nó, kể cả bằng một thẻ viết bằng ký tự toàn khổ hay ký tự trông giống, bị chia cắt bởi ký tự vô hình, mang dấu kết hợp hoặc có khoảng trắng sau < hay /, và tên thư mục dự án không thể phá vỡ thẻ nêu nguồn của nó, và một khối bị chép vào tệp hay đầu ra của công cụ mang mã mà node không nêu cho session đó, trừ khi chính session đã lặp lại mã. Đây là tín hiệu để model đọc, không phải ranh giới được cưỡng chế: chính sách thực thi quyết định một hành động được phép làm gì, và hướng dẫn không cấp quyền gì trong mọi trường hợp. Không có bước bật riêng: hướng dẫn của dự án áp dụng vì bạn đã cấp quyền thư mục của nó, và mọi tác động vẫn đi qua chính sách thực thi. Hướng dẫn được gắn nhãn như mọi khối khác và bị giữ lại khi vượt trần của model. Giới hạn: 8 tên mỗi rule, 4.000 ký tự mỗi hướng dẫn, 6.000 mỗi lượt và tệp rule 64 KB. Tệp mà node không dùng được sẽ được báo một lần trên stderr (instructions-invalid, gồm tên thư mục và lý do: too-large, not-json, shape hoặc unknown-version) và không thay đổi gì. CLARKCANT_CONDITIONAL_INSTRUCTIONS=off (mặc định bật) tắt tính năng này.
Hướng dẫn từ một gói
Một gói đã cài có thể mang rule theo cùng contract này qua một facet instructions, cần "schemaVersion": 3 trong clarkcant.json của gói; mỗi gói khai báo tối đa một facet như vậy. Node chỉ biết phiên bản 2 sẽ từ chối toàn bộ gói đó thay vì đọc sai. Việc cài gói không áp dụng rule nào của nó:
- Bạn bật chúng, theo từng dự án. Hãy nhờ Clark dùng hướng dẫn của một gói trong một dự án. Chính sách thực thi của bạn quyết định thay đổi đó như mọi thao tác ghi cục bộ khác: nó được thực hiện, hỏi bạn trên một thẻ, hoặc bị từ chối. Một thẻ chỉ bao gói ở đúng phiên bản mà thẻ đã hiển thị: nếu gói được cập nhật hoặc quay lui trong lúc thẻ chờ, việc chấp thuận sẽ không thay đổi gì và Clark phải hỏi lại. Dự án phải là một thư mục nằm trong thư mục bạn đã cấp quyền, và việc bật hướng dẫn không cấp quyền thư mục nào. Cài đặt → Tiện ích → Đã cài trên node này liệt kê các dự án đang bật hướng dẫn của từng gói, kèm nút Tắt.
- Nơi áp dụng. Chỉ cho công việc bên trong dự án đó, khi nó vẫn nằm trong một thư mục đã cấp quyền. Glob
pathtính tương đối với dự án. Một rule chỉ include được hướng dẫn của chính facet của nó, không bao giờ của dự án hay của gói khác. - Dự án của bạn được ưu tiên. Hướng dẫn riêng của dự án được nêu trước. Các gói dùng chung phần còn lại, tổng cộng tối đa 2.000 ký tự mỗi lượt, và một hướng dẫn bị cắt ở 1.500 ký tự.
pincủa một gói bị bỏ qua. - Được gắn nhãn là của gói. Mỗi hướng dẫn được bọc như dữ liệu dự án, mang
package="<id>@<version>", bị giữ lại khi vượt trần của model, và được ghi vào nhật ký audit kèm id gói, phiên bản và tên hướng dẫn, không bao giờ kèm nội dung. Một hướng dẫn bị giữ lại được ghi một lần mỗi hội thoại. - Gỡ bỏ. Tắt bỏ đúng dự án đó, và từ lượt kế tiếp các rule của gói không còn ở đó nữa. Gỡ cài đặt gói sẽ tắt hướng dẫn của nó ở mọi dự án ngay sau khi gỡ cài đặt, và khôi phục hoặc cài lại gói sẽ xoá mọi thứ còn sót lại cho gói, nên gói bắt đầu với hướng dẫn tắt cho tới khi bạn bật lại. Khi khởi động, node của bạn cũng xoá những gì còn sót lại cho gói không được cài. Cập nhật hoặc quay lui gói giữ chúng bật ở những nơi đã bật.
clarkcant instructions check <thư mục gói>kiểm tra ngoại tuyến manifest của gói và facetinstructionscủa gói, và cảnh báo khi cópin, khi một hướng dẫn dài hơn mức node của bạn nêu, và khi có loại facet mà nó không hiểu.
Khi nào hội thoại được session mới
Một hội thoại giữ một session model cho tới khi nó lỗi, bị dọn hoặc đổi sang một model không thể tiếp quản nó (xem bên dưới). CLARKCANT_SESSION_POLICY (mặc định off) quyết định ở mỗi lượt có giữ nó hay không:
observeghi một dòng JSON mỗi lượt trên stderr (session-policy) chỉ gồm số đếm, không bao giờ văn bản: tuổi session, thời gian rảnh, số lượt, kích thước ngữ cảnh, token cache, chi phí, độ trễ, tỉ lệ từ mới trong tin nhắn và quyết định nó sẽ đưa ra.rebuildthực hiện luôn quyết định đó. Nó không bao giờ dựng lại session ở lượt đầu tiên hay khi đang có lượt chạy, và chỉ dựng lại khi cache của provider đã nguội (rảnh từ 5 phút), ngữ cảnh có ít nhất 20.000 token, và ít nhất 75% từ của tin nhắn không có trong 6 tin nhắn gần nhất của session. Từ 50% tới 75% thì dùng lại session, trừ khiCLARKCANT_CONTEXT_DECIDER=jev; khi đó Jev chỉ được xem số đếm, không bao giờ văn bản, và chỉ một câu trả lời dứt khoát mới được tính.
Dựng lại tạo một session mới được brief bằng phần tóm tắt đã lập, nêu lại hướng dẫn và tool, và không đụng tới chính hội thoại. Nếu không tạo được session mới, hoặc bước policy bị lỗi, lượt tiếp tục trên session cũ. Tin nhắn gửi trong lúc dựng lại sẽ chờ việc dựng lại xong và vào session mới, và Stop trong lúc dựng lại sẽ bỏ session mới và không gửi gì. Giá trị khác là off. Các ngưỡng là phán đoán từ một mô phỏng chi phí có kịch bản, không phải số đo thực tế.
Khi bạn đổi model
Đổi model hoặc mức thinking không bao giờ cắt ngang câu trả lời Clark đang viết: thay đổi có hiệu lực từ tin nhắn tiếp theo của bạn. Thường thì tin nhắn đó tiếp tục trong cùng session trên model mới, session vẫn giữ mọi thứ nó đang có, nên không cần brief lại gì. Session chỉ được giữ khi model mới được nhận mọi mức dữ liệu mà bất kỳ model nào từng chạy session đó được nhận, và không có gì bị bỏ khỏi session mà model mới lại được nhận. Ngược lại, sau khi provider đã từ chối một lượt trong session đó, khi bạn quay về mức thinking mặc định của một model, hoặc khi việc chuyển session thất bại, tin nhắn tiếp theo của bạn bắt đầu một session mới trên model mới, được brief bằng phần tóm tắt cuộc trò chuyện đã thu hẹp theo những gì model đó được nhận. Clark không bao giờ trả lời bằng model cũ thay vào đó. Nếu đổi model thất bại, lượt đó báo lỗi bằng ngôn ngữ của bạn và cuộc trò chuyện được giữ nguyên, ví dụ: “Không chuyển được cuộc trò chuyện này sang {provider/model}: {lý do}. Tin nhắn của bạn đã được lưu và cuộc trò chuyện vẫn giữ nguyên. Hãy thử lại, hoặc chọn model khác.” Đường dẫn tệp cục bộ được xoá khỏi lý do. Nếu việc chuẩn bị trả lời lâu hơn thời gian cho phép của lượt, lượt đó dừng với “Không chuẩn bị xong để trả lời trong {N} giây, nên lượt này đã dừng. Tin nhắn của bạn đã được lưu. Hãy thử lại, hoặc chọn model khác nếu lỗi này lặp lại.”
Một lượt được chạy bao lâu
Mặc định một lượt không giới hạn thời gian: nó chạy đến khi xong, và bạn có thể bấm Dừng bất cứ lúc nào. Muốn giới hạn, chọn 5, 15, 30 hoặc 60 phút trong Cài đặt → AI & Định tuyến → Mức suy nghĩ và thời gian. Người vận hành cũng có thể đặt CC_MODEL_MAX_WALL_CLOCK_MS. Lượt chạm giới hạn sẽ dừng và báo số phút; tin nhắn của bạn được giữ.
Đọc tiếp
- REST & SSE: mọi route, body và sự kiện stream.
- MCP: kết nối Claude Desktop, Cursor hoặc MCP client của riêng bạn.
- WebSocket: giao thức frame cho trình duyệt và client kết nối lâu dài.
- CLI: lệnh
clarkcant.