Craft Agents 深度链接完整指南：用 craftagents:// 协议让外部应用一键直达指定会话-平芜编程栈

Craft Agents 深度链接完整指南：用 craftagents:// 协议让外部应用一键直达指定会话

【免费下载链接】craft-agents-oss项目地址: https://gitcode.com/GitHub_Trending/cr/craft-agents-oss

Craft Agents 是一款开源的 Agent 原生桌面应用，让你高效管理与多路 AI 会话并行协作。而Craft Agents 深度链接（Deep Link）功能正是它的隐藏利器：通过craftagents://自定义协议，任何外部应用、网页链接或命令行脚本都能一键唤起 Craft Agents 并直达指定会话——无论是打开某条聊天记录、新建一个带提示词的聊天，还是跳转到设置页与数据源页面，全部一条链接搞定。

为什么需要深度链接？

日常使用中我们常遇到这样的场景：在 Slack、脚本或 CI 流水线里看到"去 Craft Agents 查看这个任务"，结果还要手动切窗口、翻找会话列表。深度链接把这一切压缩成一次点击：

外部应用直达会话：链接携带会话 ID，打开即定位；
自动化创建任务：不仅跳转，还能直接创建新聊天并自动发送提示词；
多工作区精准路由：可以明确指定目标工作区，不怕开错窗口。

核心实现位于主进程的协议解析模块 deep-link.ts，它在应用启动时通过 index.ts 中的setAsDefaultProtocolClient注册为craftagents://的默认协议客户端，系统层点击链接时即被唤醒处理。

深度链接 URL 格式速查

协议设计采用"主机段即路由前缀"的风格，格式直观、易记。以下是全部支持的路由：

导航类链接：跳转到指定页面或会话

链接格式	作用
`craftagents://allSessions`	打开全部会话列表
`craftagents://allSessions/session/abc123`	直达指定会话（最常用）
`craftagents://flagged/session/abc123`	在"已标记"筛选下定位会话
`craftagents://state/done/session/abc123`	按状态筛选后定位会话
`craftagents://sources/source/github`	打开某个数据源（Source）详情页
`craftagents://settings`	打开设置页
`craftagents://settings/shortcuts`	直达设置子页（如快捷键）

动作类链接：不只是跳转，还能执行操作

action路由让深度链接具备"执行力"，这是自动化场景的核心：

链接格式	作用
`craftagents://action/new-chat`	新建一个聊天
`craftagents://action/new-chat?input=hello&name=任务A&send=true`	新建聊天并自动发送提示词
`craftagents://action/resume-sdk-session/{sdkId}`	通过 SDK 会话 ID 恢复 Claude Code 会话
`craftagents://action/flag-session/{id}`/`unflag-session/{id}`	标记 / 取消标记会话
`craftagents://action/delete-session/{id}`	删除会话

指定工作区与窗口行为

若链接未指定工作区，默认作用于当前聚焦窗口；也可显式指定：

craftagents://workspace/ws123/allSessions/session/abc123 craftagents://workspace/ws123/action/new-chat?input=hi&send=true

两个实用查询参数：

?window=focused：在新窗口中打开并聚焦（应用内部"新窗口打开"菜单即基于它，见 SidebarMenu.tsx）；
?sidebar=files/path/to/file：打开右侧边栏并定位到指定文件或历史记录。

如何触发深度链接？

无需编写代码，三种最常见方式：

命令行（macOS / Linux）：open "craftagents://allSessions/session/abc123"或xdg-open "craftagents://..."Windows 下双击一个包含该链接的.url文件即可。
网页超链接：把链接写成<a>或 Markdown 链接，点击后系统会询问是否用 Craft Agents 打开。
自动化脚本 / 消息推送：在 CI、Slack 机器人、个人脚本里生成带会话 ID 的链接，实现"消息里的按钮 → 直接跳到会话"。

一个值得注意的细节：如果链接到达时应用尚未完全启动（冷启动），主进程会把链接暂存为pendingDeepLink并在就绪后自动补发，不会丢失。

开发者须知：多实例调试

开发模式下同时运行多个 Craft Agents 实例时，可通过环境变量CRAFT_DEEPLINK_SCHEME将协议替换为craftagents1、craftagents2等，避免互相抢占（见 index.ts）。协议解析的单元测试位于 deep-link-routing.test.ts，可参考其中"按客户端 → 按工作区"的路由回退逻辑。