diff --git a/docs/api.html b/docs/api.html index cc7e2ea..5979e88 100644 --- a/docs/api.html +++ b/docs/api.html @@ -534,11 +534,14 @@
/widget-dev/sessions/{id}/widget-dev/sessions/{id}/rebuild409 SESSION_STOPPED for a stopped session. Person-only./widget-dev/sessions/{id}/place{ conversationId, widgetId? }/widget-dev/chosen-folders/forget{ root }{ root, forgotten, stillCoveredBy? }; forgotten is false when the folder was not chosen, so a second press is harmless. stillCoveredBy names a folder Clark may still develop in that holds this one (another folder you chose, or a workspace.roots value you recorded), so Clark keeps access there until that one goes too. Running sessions stay as they are. Person-only.Starting, rebuilding and placing install code, so the WebSocket relay, clarkcant api and MCP refuse them with 403 PERSON_ONLY. Reading and stopping a session stay reachable everywhere. In the conversation, Clark's develop_widget tool (start, status, rebuild, place, stop) drives the same sessions; it starts, rebuilds or places only in a turn the person sent, never in one a machine surface, an automation or a paired node sent.
Starting, rebuilding and placing install code, so the WebSocket relay, clarkcant api and MCP refuse them with 403 PERSON_ONLY. Forgetting a chosen folder is refused the same way: taking a choice back is yours, as making it is. Reading and stopping a session stay reachable everywhere. In the conversation, Clark's develop_widget tool (start, choose, folders, status, rebuild, place, stop) drives the same sessions; it starts, rebuilds or places only in a turn the person sent, never in one a machine surface, an automation or a paired node sent. choose and folders only show you the develop card (a folder to choose, or the folders you chose, each with Forget); neither starts nor forgets anything. choose offers a lasting choice, so it too runs only in a turn you sent; folders only narrows access and runs in any turn.
root is resolved to its real path first. 400 ROOT_NOT_LOCAL refuses a Windows network share or device path; 400 ROOT_IN_DATA_FOLDER refuses the node's data folder, a folder inside it or one that holds it, except Clark's widget workspace <dataDir>/widget-workspace. A session Clark starts may watch only that workspace; any other folder is 403 ROOT_NOT_OWNED.root is resolved to its real path first. 400 ROOT_NOT_LOCAL refuses a Windows network share or device path; 400 ROOT_IN_DATA_FOLDER refuses the node's data folder, a folder inside it or one that holds it, except Clark's widget workspace <dataDir>/widget-workspace. A session you start on the route marks its folder as one you chose (chosenByPerson in the session view), but only when the path you gave is the folder itself as it resolves at that moment: a path through a link or junction starts the session it leads to without marking anything, so a link swapped in after the card was drawn grants nothing. The choice covers every folder inside it. A whole drive or your home folder itself is never marked: a session may run there, but Clark keeps no access. A chosen folder is kept as the real path it had when you started it, so if that path later leads somewhere else (the folder was replaced by a link or junction, moved or removed) the choice no longer counts; it is still listed, as not found, so you can forget it. A session Clark starts may watch that workspace, a folder you chose (or one inside it), or a folder inside a workspace.roots preference you recorded yourself; any other folder is 403 ROOT_NOT_OWNED, nothing starts, and Clark's answer carries a host-drawn develop card offering the folder to you./develop and /develop <folder> (or asking Clark, which uses develop_widget choose) answer with the same develop command card. It names the folder the path resolves to when the card is drawn, and shows the path given when that differs; a press sends that canonical path, which is kept as your choice only if it is still the folder itself when pressed. A path that is not found, not absolute, or a network share or device gets no button, only a note saying why. Each row's action is { "kind": "develop-folder", "root"? }, and the card starts nothing itself: a press in your own app calls POST /widget-dev/sessions as you, so no agent, widget or machine surface chooses a folder for itself. Without a root the desktop app opens the system folder dialog; where it cannot (a browser, a node on another machine, a dialog that does not open) the row asks for the path./develop forget (or asking Clark which folders it may use) lists the folders you chose, each with a Forget button whose action is { "kind": "develop-folder-forget", "root" }. A press calls POST /widget-dev/chosen-folders/forget as you. Forgetting does not stop a running session, and a folder inside another folder you chose stays reachable through that one; the answer says so.isolated-ui and declarative facets run. A package with a service, tools or native facet fails to build with FACET_LANE_UNSUPPORTED. A package id that belongs to something else on the node is refused as activation.state: "refused" with PACKAGE_LISTED, PACKAGE_IN_OTHER_SESSION or PACKAGE_INSTALLED_OTHERWISE.lastBuild.ok is false with up to 32 diagnostics, the running generation keeps running, and showingLastKnownGood is true. A folder over 5,000 files or 64 MiB fails with FILES_TOO_LARGE, a link out of it with FILES_LINK_REFUSED, and files that could not be read with FILES_UNREADABLE.GET /inbox carries that scope as its operationDigest and is decided on POST /packages/approvals/{approvalId}/decision. A later build with the same scope installs on that approval; a build whose scope changed is a new question, and the generation before it keeps running meanwhile.clark widget dev simulates a node. To see the widget on your node itself, ask Clark to develop one (“build me a timer widget”), or start a session on the widget dev session routes. Your node watches the folder with the same build engine the dev host uses. Every change that reads as a package becomes a new build, named by the digest of its files, copied into the node's package cache and listed for this node alone, then installed through the ordinary install path. Nothing goes through npm, the Marketplace or a directory index, and nothing is published. A node_modules folder at the top is left out of each build; built output such as dist is kept.
The widget appears in the conversation in the real widget frame, with the real sandbox, bridge, state and migrations. A new build reloads only the frame: the widget keeps its state, which goes through the package's own migrations when the version changes. Beside the frame, your node says which build is on screen and, when it is not the newest, why: the new build failed (with its problems listed), it waits for your answer in the inbox, or the policy refused it. “Showing the last successful build” appears exactly when that is what you see.
<dataDir>/widget-workspace, where it scaffolds a new one. To have Clark work on a widget project you already have, copy its folder there. Pointing Clark at another project folder is not available yet (#538). A session you start yourself on the route may watch any other local folder, but never the node's own data folder or a network share.<dataDir>/widget-workspace, where it scaffolds a new one. To have Clark work on a widget project you already have, choose its folder yourself: type /develop (or /develop <folder>, or ask Clark) and press Choose folder… in the card that answers. The desktop app opens your system's folder dialog; a browser, or a desktop app connected to a node on another machine, asks for the folder's full path on the node's machine and says why. If Clark wants to develop a folder you have not chosen, nothing starts, and the same card offers it to you with Develop this folder. The card names the folder the path really leads to, and says so when that differs from the path you gave; a path that is not found gets no button. A press keeps the folder as your choice only if the path is still that folder itself when you press, so a link put in its place meanwhile gains nothing. Only a message you sent can make Clark show a folder to choose. Once you start a folder, Clark may work in it, and in every folder inside it, without asking again, until you take that back: type /develop forget (or ask Clark which folders it may use) and press Forget beside the folder. Forgetting does not stop a running session, and a folder inside another folder you chose stays reachable through that one (the answer says so). A chosen folder that is moved away is listed as not found, so you can still forget it. A whole drive or your home folder can be developed for one session, but Clark never keeps access to it. A session you start yourself may watch any local folder, but never the node's own data folder or a network share.isolated-ui and declarative facets). A package with a service, tools or a native part is refused with a problem saying so; install it the ordinary way./thinking chooses how hard the next turns think, from a list, or directly: /thinking high, /thinking default. It is the same setting as Settings → AI & Routing → Thinking level./background <request> runs the request as background work beside the conversation and reports back in it./report reports a bug or asks for a feature in ClarkCant itself. See below./develop chooses a folder to develop a widget from, live in the conversation; /develop <folder> offers that folder, and /develop forget lists the folders you chose so you can take one back. See developing a widget in the conversation.A command typed in the middle of a sentence is just text. Commands are not sent to the model. See provider sign-in routes.
diff --git a/vi/docs/api.html b/vi/docs/api.html index e481575..77b0e80 100644 --- a/vi/docs/api.html +++ b/vi/docs/api.html @@ -534,11 +534,14 @@/widget-dev/sessions/{id}/widget-dev/sessions/{id}/rebuild409 SESSION_STOPPED với phiên đã dừng. Chỉ người dùng./widget-dev/sessions/{id}/place{ conversationId, widgetId? }/widget-dev/chosen-folders/forget{ root }{ 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. Đọ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, 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.
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.
root được quy về đường dẫn thật trước. 400 ROOT_NOT_LOCAL từ chối ổ mạng chia sẻ hay đường dẫn thiết bị của Windows; 400 ROOT_IN_DATA_FOLDER từ chối thư mục dữ liệu của node, thư mục nằm trong nó hay thư mục chứa nó, trừ không gian làm widget của Clark <dataDir>/widget-workspace. Phiên do Clark bắt đầu chỉ được theo dõi không gian đó; thư mục khác nhận 403 ROOT_NOT_OWNED.root được quy về đường dẫn thật trước. 400 ROOT_NOT_LOCAL từ chối ổ mạng chia sẻ hay đường dẫn thiết bị của Windows; 400 ROOT_IN_DATA_FOLDER từ chối thư mục dữ liệu của node, thư mục nằm trong nó hay thư mục chứa nó, trừ không gian làm widget của Clark <dataDir>/widget-workspace. Phiên do bạn bắt đầu qua route đánh dấu thư mục của nó là thư mục bạn đã chọn (chosenByPerson trong view của phiên), nhưng chỉ khi đường dẫn bạn đưa ra chính là thư mục đó như nó được phân giải lúc ấy: một đường dẫn qua liên kết hoặc junction vẫn bắt đầu phiên ở nơi nó dẫn tới nhưng không đánh dấu gì, nên một liên kết bị tráo sau khi thẻ được vẽ không cấp quyền gì. Lựa chọn đó gồm mọi thư mục bên trong nó. Cả một ổ đĩa hay chính thư mục home của bạn không bao giờ được đánh dấu: một phiên vẫn chạy được ở đó, nhưng Clark không giữ quyền. Thư mục đã chọn được giữ dưới đường dẫn thật nó có lúc bạn bắt đầu, nên nếu về sau đường dẫn đó dẫn tới nơi khác (thư mục bị thay bằng một liên kết hoặc junction, bị chuyển đi hoặc bị xoá) thì lựa chọn không còn được tính; nó vẫn được liệt kê, với trạng thái không tìm thấy, để bạn thu hồi. Phiên do Clark bắt đầu được theo dõi không gian đó, một thư mục bạn đã chọn (hoặc thư mục nằm trong nó), hoặc một thư mục nằm trong tùy chọn workspace.roots do chính bạn ghi; thư mục khác nhận 403 ROOT_NOT_OWNED, không có gì được bắt đầu, và câu trả lời của Clark mang một thẻ develop do host vẽ, mời bạn phát triển thư mục đó./develop và /develop <thư mục> (hoặc nhờ Clark, khi đó Clark dùng choose của develop_widget) trả về cùng thẻ lệnh develop. Thẻ nêu thư mục mà đường dẫn dẫn tới lúc thẻ được vẽ, và cho thấy đường dẫn được đưa ra khi hai cái khác nhau; lần bấm gửi đường dẫn chuẩn đó, và nó chỉ được giữ làm lựa chọn của bạn nếu lúc bấm nó vẫn chính là thư mục đó. Đường dẫn không tìm thấy, không đầy đủ, hoặc trỏ tới thư mục chia sẻ qua mạng hay thiết bị thì không có nút, chỉ có một ghi chú nói lý do. Thao tác của mỗi dòng là { "kind": "develop-folder", "root"? }, và thẻ tự nó không bắt đầu gì: một lần bấm trong chính ứng dụng của bạn gọi POST /widget-dev/sessions với tư cách bạn, nên không agent, widget hay giao diện máy nào tự chọn được thư mục cho mình. Khi không có root, ứng dụng desktop mở hộp chọn thư mục của hệ thống; ở nơi không mở được (trình duyệt, node trên máy khác, hộp chọn không mở) dòng đó hỏi đường dẫn./develop forget (hoặc hỏi Clark những thư mục nó được dùng) liệt kê các thư mục bạn đã chọn, mỗi thư mục có nút Thu hồi với thao tác { "kind": "develop-folder-forget", "root" }. Lần bấm gọi POST /widget-dev/chosen-folders/forget với tư cách bạn. Thu hồi không dừng phiên đang chạy, và một thư mục nằm trong một thư mục khác bạn đã chọn vẫn được dùng qua thư mục đó; câu trả lời nói rõ điều này.isolated-ui và declarative được chạy. Gói có facet service, tool hay native dựng thất bại với FACET_LANE_UNSUPPORTED. Id gói thuộc về thứ khác trên node bị từ chối thành activation.state: "refused" với PACKAGE_LISTED, PACKAGE_IN_OTHER_SESSION hoặc PACKAGE_INSTALLED_OTHERWISE.lastBuild.ok là false kèm tối đa 32 diagnostics, thế hệ đang chạy vẫn chạy, và showingLastKnownGood là true. Thư mục quá 5.000 tệp hoặc 64 MiB thất bại với FILES_TOO_LARGE, liên kết trỏ ra ngoài với FILES_LINK_REFUSED, và tệp không đọc được với FILES_UNREADABLE.GET /inbox mang phạm vi đó làm operationDigest và được quyết định trên POST /packages/approvals/{approvalId}/decision. Bản dựng sau có cùng phạm vi được cài theo lần chấp thuận đó; bản dựng có phạm vi thay đổi là một câu hỏi mới, và thế hệ trước đó vẫn chạy trong lúc chờ.clark widget dev mô phỏng một node. Để xem widget trên chính node của bạn, hãy nhờ Clark phát triển một widget (“làm cho tôi một widget hẹn giờ”), hoặc bắt đầu một phiên qua các route phiên phát triển widget. Node của bạn theo dõi thư mục bằng cùng bộ dựng mà dev host dùng. Mỗi thay đổi đọc được như một gói trở thành một bản dựng mới, đặt tên theo digest các tệp của nó, được sao chép vào bộ nhớ đệm gói của node và chỉ liệt kê cho riêng node này, rồi được cài qua đường cài đặt thông thường. Không có gì đi qua npm, Marketplace hay một chỉ mục thư mục, và không có gì được phát hành. Thư mục node_modules ở cấp trên cùng được bỏ ra khỏi mỗi bản dựng; đầu ra đã dựng như dist vẫn được giữ.
Widget xuất hiện trong hội thoại trong khung widget thật, với sandbox, bridge, trạng thái và migration thật. Bản dựng mới chỉ tải lại khung: widget giữ trạng thái của nó, và trạng thái đi qua các migration của chính gói khi phiên bản thay đổi. Bên cạnh khung, node của bạn cho biết bản dựng nào đang hiển thị và, khi đó không phải bản mới nhất, lý do: bản dựng mới bị lỗi (kèm danh sách vấn đề), nó đang chờ bạn trả lời trong hộp thư, hoặc policy đã từ chối nó. “Đang hiện bản dựng thành công gần nhất” chỉ xuất hiện đúng khi đó là thứ bạn đang thấy.
<dataDir>/widget-workspace, nơi nó dựng khung cho widget mới. Để Clark làm việc với một dự án widget bạn đã có, hãy chép thư mục của nó vào đó. Chỉ cho Clark một thư mục dự án khác hiện chưa có (#538). Phiên do chính bạn bắt đầu qua route có thể theo dõi bất kỳ thư mục cục bộ nào khác, nhưng không bao giờ là thư mục dữ liệu của chính node hay một ổ mạng chia sẻ.<dataDir>/widget-workspace, nơi nó dựng khung cho widget mới. Để Clark làm việc với một dự án widget bạn đã có, hãy tự chọn thư mục của nó: gõ /develop (hoặc /develop <thư mục>, hoặc nhờ Clark) rồi bấm Chọn thư mục… trên thẻ trả lời. Ứng dụng desktop mở hộp chọn thư mục của hệ thống; trình duyệt, hoặc ứng dụng desktop nối với một node trên máy khác, sẽ hỏi đường dẫn đầy đủ của thư mục trên máy chạy node và nói rõ lý do. Nếu Clark muốn phát triển một thư mục bạn chưa chọn, không có gì được bắt đầu, và chính thẻ đó mời bạn với nút Phát triển thư mục này. Thẻ nêu thư mục mà đường dẫn thật sự dẫn tới, và nói rõ khi nó khác đường dẫn bạn đưa ra; đường dẫn không tìm thấy thì không có nút. Lần bấm chỉ giữ thư mục làm lựa chọn của bạn nếu lúc bấm đường dẫn vẫn chính là thư mục đó, nên một liên kết được đặt vào chỗ nó trong lúc chờ không được gì. Chỉ tin nhắn do bạn gửi mới khiến Clark đưa ra một thư mục để chọn. Khi bạn đã bắt đầu một thư mục, Clark được làm việc trong đó, và trong mọi thư mục nằm bên trong nó, mà không cần hỏi lại, cho tới khi bạn thu hồi: gõ /develop forget (hoặc hỏi Clark những thư mục nó được dùng) rồi bấm Thu hồi cạnh thư mục đó. Thu hồi không dừng phiên đang chạy, và một thư mục nằm trong một thư mục khác bạn đã chọn vẫn được dùng qua thư mục đó (câu trả lời nói rõ điều này). Một thư mục đã chọn bị chuyển đi được liệt kê là không tìm thấy, để bạn vẫn thu hồi được. Cả một ổ đĩa hay thư mục home của bạn có thể được phát triển trong một phiên, nhưng Clark không bao giờ giữ quyền với nó. Phiên do chính bạn bắt đầu có thể theo dõi bất kỳ thư mục cục bộ nào, nhưng không bao giờ là thư mục dữ liệu của chính node hay một ổ mạng chia sẻ.isolated-ui và declarative). Gói có service, tool hay phần native bị từ chối kèm một vấn đề nói rõ điều đó; hãy cài gói đó theo cách thông thường./thinking chọn mức suy nghĩ cho các lượt sau, từ danh sách, hoặc gõ trực tiếp: /thinking high, /thinking default. Đây cũng là thiết lập Cài đặt → AI & Định tuyến → Mức suy nghĩ./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 đó./report báo lỗi hoặc đề xuất tính năng cho chính ClarkCant. Xem bên dưới./develop chọ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 forget liệ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.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.