深链与工作台唤起
用「在 ZeroWorks 中打开」的链接从浏览器或脚本唤起工作台，新建会话、定位工作区并执行会话动作。
用链接新建会话
ZeroWorks 桌面端保留兼容协议 craftagents://。安装并注册该协议后，可从浏览器、文档或系统启动器唤起桌面端；协议名使用这一固定值。
新建动作是 action/new-session，可预填内容与会话名称。默认只填入输入框；只有 send=true 且提供 input 时才会立即发送。
| 参数 | 含义 |
|---|---|
| input | 经过 URL 编码的输入文本 |
| send | 精确值 true 会立即提交 input；省略则仅预填 |
| name | 新会话名称，需 URL 编码 |
| status | 当前工作区已配置的状态 ID |
| label | 当前工作区已配置的单个标签 ID |
| project | 目标工作区的项目 ID |
| mode | explore、ask、guarded 或 execute；guarded 需先启用决策功能 |
| workdir | Agent 主机上的工作目录，需 URL 编码 |
| model | 目标连接中可用的模型 ID |
craftagents://action/new-session?input=Hello%20world&name=Docs%20demo
定位到指定工作区
未指定工作区时使用当前聚焦或最近活动的窗口。要指定工作区，在 craftagents:// 后使用 workspace/{workspaceId}/，然后追加受支持的视图或 action。
workspaceId 是桌面客户端配置中的工作区标识，可在 ~/.zero-works/config.json 的 workspaces 列表中查找；不要把名称、文件夹路径或账号 ID 代替它。
craftagents://workspace/{workspaceId}/action/new-session?input=Check%20dependency%20versions
直接打开某个视图
当前桌面主进程只接受以下六类外部视图前缀：allSessions、flagged、state、sources、skills、settings。内部界面能导航到的页面不一定能通过外部深链打开。
| craftagents:// 后的路径 | 打开的内容 |
|---|---|
| allSessions | 全部会话列表 |
| allSessions/session/{sessionId} | 指定会话 |
| flagged/session/{sessionId} | 标记列表中的指定会话；省略 session 部分则打开列表 |
| state/{statusId}/session/{sessionId} | 状态列表中的会话；可省略 session 部分 |
| sources | 全部来源 |
| sources/api、sources/mcp、sources/local | 按类型筛选来源；实际 URL 中选择其中一条路径 |
| sources/source/{sourceSlug} | 指定来源详情 |
| skills/skill/{skillSlug} | 指定技能；skills 打开技能列表 |
| settings | 设置入口 |
| settings/ai、settings/workspace、settings/shortcuts | 对应的设置子页；实际 URL 中选择其中一条路径 |
craftagents://sources/source/github craftagents://skills/skill/weekly-review craftagents://settings/ai
对会话执行动作
动作路径可以写在 craftagents://action/ 下，也可以加上 workspace/{workspaceId}/。目标会话必须已经存在于客户端可访问的工作区；参数值都要 URL 编码。
| 路径 | 作用 |
|---|---|
| action/rename-session/{sessionId}?name=New%20name | 重命名会话 |
| action/flag-session/{sessionId} | 标记会话 |
| action/unflag-session/{sessionId} | 取消标记 |
| action/delete-session/{sessionId} | 删除会话 |
| action/set-mode/{sessionId}?mode=explore | 改为 Explore 模式；也支持 ask、guarded、execute |
窗口模式
默认情况下链接复用当前窗口。加一个 window 参数，可以让工作台另开一个窗口。
| window 取值 | 行为 |
|---|---|
| focused | 新开聚焦模式窗口 |
| full | 新开完整窗口 |
craftagents://allSessions?window=full
典型用法
- 浏览器书签：把常用的开场提示做成书签，一键发起对应会话。
- 团队文档：在文档里插入链接，读者点击后直接带着问题进入工作台。
- 命令行别名：为常用任务建立 shell 别名，直接把提示词送进工作台。
- 启动器快捷键：在系统启动器或快捷指令工具里配置同样的链接，绑定到快捷键。
alias briefing="open 'craftagents://action/new-session?input=Summarize%20project%20progress'"
使用提示
- 预填文本做 URL 编码：空格为 %20，问号 %3F，与号 %26，换行 %0A；不要把未编码文本直接拼进查询参数。
- 先用仅预填的无害提示测试协议唤起，再加入真实工作区或会话 ID。
- 只有确实需要立即提交时才加 send=true；它仍受所选会话权限约束。
- 链接里的工作区和会话 ID 需要在目标客户端可解析；不会通过登录账号自动映射到另一台独立安装。
- 无法打开时，检查桌面安装的协议注册、craftagents:// 拼写、外部视图前缀和工作区 ID。
open "craftagents://action/new-session?input=Hello%20world"