命令行与工作区管理

命令行入口与适用范围#

当前运行时保留两种不同入口的名称。craft-agent 是工作区配置工具的兼容包装器和随包文档入口；craft-cli 是源码 apps/cli 中通过 WebSocket 连接服务器的 RPC 客户端。两者的命令与返回格式不同。

当前源码基线里的 craft-agent 包装器依赖另外的命令包入口，不能仅凭包装器存在就认为普通终端已经安装可用工具。ZeroWorks 尚未提供经过验收的独立 CLI 安装分发；本页的命令参考不代表已经发布。

• 上述语法对应配置工具：--help 查看帮助，--discover 列出对象，--json 或 --stdin 提交结构化参数。先确认所在运行环境实际提供命令。
• 源码开发者可在 works-agent 中运行 bun run apps/cli/src/index.ts --help 查看 RPC 客户端用法；连接已经运行的服务器时使用 --url、--token 与可选的 --workspace。
• RPC 连接变量是 CRAFT_SERVER_URL、CRAFT_SERVER_TOKEN 与可选的 CRAFT_TLS_CA。token 只填入自己的终端环境或专用字段，不写进聊天与反馈。

常用命令#

随包配置工具文档按对象列出以下命令。它们需要可用的 craft-agent 命令包；具体动作以该环境的 --help 为准，各对象不保证提供同一套 CRUD 动作。

远程工作区#

跨设备使用桌面端的服务器模式：客户端通过 URL 和 token 连接运行 ZeroWorks 的主机，再选择该服务器上的工作区。会话和文件留在服务器环境里，命令也在服务器上执行。

当前没有账号驱动的工作区云同步；登录 ZeroWorks 官网或控制台不会自动找回桌面会话，也不会把两台独立安装的工作区合并。

1. 在主机的“设置 → 服务端”启用服务器模式，保存配置，并按界面提示重启；复制可达的 ws:// 或 wss:// URL 和 token。
2. 在另一台桌面客户端中选择“添加工作区 → 连接远程”，填入 URL 与 token，运行 Test Connection。
3. 选择测试返回的已有工作区，点击 Connect，再核对已有会话与服务器工作目录。需要新内容空间时才创建新工作区。

无头模式部署#

把工作台作为无头服务单独部署在服务器上，并对外发布可下载的服务端安装包，目前不在 ZeroWorks 的范围内。本节因此不提供部署步骤、服务端安装包地址或容器编排示例。

当前可行的做法是用桌面端配合自动化任务，并在桌面端或直接连接同一服务器的客户端中查看结果。自动化任务的运行依赖本机进程保持开启。

• 定时自动化：按 cron 计划触发，命中后新建一个会话并执行提示。
• 事件触发：在指定事件发生时执行预设动作。
• 命令行：把重复的配置维护动作写成脚本，交给命令行工具执行。

会话在工作区之间转移#

“发送到工作区”把会话导出并导入目标工作区，创建独立副本，包含对话消息、可迁移的会话元数据与上下文摘要。原会话保留在原工作区。

目标来自客户端可访问的本地工作区或已连接的远程服务器。它不是账号云同步；复制会话不会把原项目的整个文件目录同步到目标。

1. 打开会话的更多菜单，选择“发送到工作区”。
2. 选择本地工作区或已连接远程服务器上的目标工作区，确认发送并等待完成。
3. 在目标工作区打开新会话，核对消息、摘要和权限模式。
4. 继续处理文件前，确认项目材料已在目标运行环境中可访问，并核对实际工作目录。

连接状态#

先在工作台设置与来源详情中确认状态。下面的命令需要可用的配置工具；源码 RPC 客户端则用 ping、health、workspaces、sources 检查已经连接的服务器。

• 工作区：命令行执行 craft-agent source list，确认来源是否仍然存在并处于启用状态。
• 来源：执行 craft-agent source validate <slug> 与 source test <slug>，检查配置与连通性。
• 权限：执行 craft-agent permission validate，确认各层级的权限规则是否合法。
• 凭据：在设置里打开对应连接的“配置访问”，检查状态并重新填写过期凭据。

排障#

命令行的问题大多集中在三处：环境没配好、参数用法不对、配置本身不合法。按下面的对照表逐项确认。