前言¶
在 DSH 里编排智能体时，常见做法是让插件去 spawn claude CLI，拿结构化 JSON 结果、还能 resume 会话——例如同生态里的 dsh-claude-pilot。另一类需求是：任务要在 Claude 桌面应用里跑，用图形界面看 Claude Code、Cowork，或把 CLI 里已经开好的会话交回桌面端继续。
Claude 桌面端对外没有本地 RPC 端口，也不能用 CDP 遥控 Chromium。维护者 Dobo233 的 dsh-claude-desktop（GitHub：Dobo233/dsh-claude-desktop，社区目录：skillhub 插件页）走的是应用自带的 claude:// 深链：投递 prompt、目录和文件，必要时代按发送键，再从本地会话文件读回回答。插件把「能做什么、不能做什么」写进 README，并给出实测依据；分类为 工作流。
下面介绍它的定位、工具、安装与典型用法。
这是什么¶
dsh-claude-desktop 是 DSH 插件（Cordis bundle，当前 package 版本 0.1.2，MIT 许可证）。一句话：让 DSH 通过 claude:// 把活交给 Claude 桌面端，并支持从本地 jsonl 读回对话——不是远程遥控已打开窗口里的输入框，也不是 CDP 驱动。
与 dsh-claude-pilot 的分工：
| 方向 | dsh-claude-pilot | dsh-claude-desktop |
|---|---|---|
| 调用方式 | spawn claude CLI |
调桌面应用深链 |
| 结果形态 | JSON（cost / turns / session_id 等） | 读本地 jsonl + 应用侧会话索引 |
| 典型场景 | 要在 DSH 里干净拿 CLI 结果 | 要在桌面端 UI 里跑、或 CLI 会话交回桌面 |
桥的能力可以概括成：投递 + 交接 + 读回，不是往已开对话里插话，也不能 --remote-debugging-port。
能力边界¶
以下结论来自 README 中的能力表与实测说明。
能做的：
- 投递任务到桌面端：例如
claude://code/new?q=…&folder=…，应用日志会出现工作区信任等记录。 - 投递 Cowork 任务（带文件）：
claude://cowork/new，参数q/folder/file转发到/task/new。 - 把 CLI 会话交回桌面端：
claude://code/continue?session=last或 UUID，Resume 分支会importCliSession。 - 读回桌面端的回答：桌面端 Claude Code 内部跑真 Claude Code，正文在
~/.claude/projects/<cwd-slug>/<cliSessionId>.jsonl；应用索引在%LOCALAPPDATA%/Claude-Data/claude_<pkg>/claude-code-sessions/...里对照sessionId与cliSessionId。
不能做的：
- 往已打开的对话里插话：没有 queue 式 IPC。
- CDP / 远程调试驱动：
--remote-debugging-port在应用 Chromium 开关黑名单里。
另外需要理解 投递 ≠ 发送：深链里的 q 只会 预填输入框，不会自动发出消息；实测里草稿写在 composer-draft，Ctrl+Enter 才会触发 [CCD] session spawn 等日志并真正开跑。Enter 在 Claude Code 输入框里是换行。插件在 submit=true 时会尽力 SendKeys('^{ENTER}')，失败会返回 ok:false 并说明原因。
深链契约（摘要）¶
插件行为与桌面端 claudeURLHandler 对齐，常用入口如下：
| 用途 | URL | 主要参数 |
|---|---|---|
| 新 Claude Code 会话 | claude://code/new |
q（或 prompt）、folder（可重复）、file（可重复） |
| 继续会话 | claude://code/continue |
session=last 或 UUID |
| 等你处理的会话 | claude://code/needs-input |
session |
| Cowork 任务 | claude://cowork/new |
q、folder、file |
| 新聊天 | claude://claude.ai/new |
surface=chat |
协议名默认 claude，由桌面端注册；应用内可用 disableDeepLinkRegistration 关闭注册。
核心工具¶
DSH 侧通过下列工具与桌面端协作（参数以 README 为准）：
| 工具 | 作用 |
|---|---|
desktop_send |
投递任务；可选 folder、files[]、surface（code / cowork / claude.ai）、submit、wait |
desktop_continue |
CLI 会话交回桌面；session=last 或 UUID |
desktop_open |
打开面板或任意深链（entry 或完整 claude://…） |
desktop_sessions |
列出最近会话（local_<uuid>、cliSessionId、cwd 等） |
desktop_read |
读某会话最后 N 轮正文 |
desktop_wait |
等会话跑完一轮并读回 |
desktop_probe |
体检：版本、进程、协议注册、配置路径、能力边界 |
读回不依赖应用进程常驻：jsonl 已在磁盘上，desktop_read(session="last") 即使应用关闭也可读（读的是本地文件，不额外联网；额度以桌面端实际跑的那一轮为准）。
安装与配置¶
安装¶
在 PowerShell 中从 GitHub 安装（README 原文命令）：
dsh plugin --profile web add github:Dobo233/dsh-claude-desktop
本地开发时可把 <repo-path> 传给同一子命令。插件要求 Node ^22.19.0 || >=24.0.0，peer 依赖 @deepseek-ai/dsh-tools（见 package.json）。
DSH 生态是「一切皆插件」；skillhub.cn 上的社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系。安装前请自行查看仓库源码与 MIT 许可证；插件以当前 DSH 进程权限运行，投递会在用户桌面端开启真实会话并可能消耗用户额度。
配置项¶
在 ~/.dsh/profiles/<profile>/cordis.patch.yml 的 config 段或插件项中可调整：
| 键 | 默认 | 说明 |
|---|---|---|
dryRun |
false |
true 只返回拼好的 URL，不拉起应用 |
maxPromptChars |
6000 |
prompt 截断长度 |
protocol |
"claude" |
协议名，一般不改 |
appPackageId |
"Claude_pzs8sxrjxfjjc" |
定位 Claude-Data\<pkg> |
submit |
false |
是否在投递后自动 Ctrl+Enter |
submitKeys |
"^{ENTER}" |
SendKeys 组合（勿改成仅 {ENTER}） |
focusDelayMs |
1200 |
投递后等待再抢前台 |
waitTimeoutMs |
180000 |
wait 最长等待 |
pollMs |
2000 |
轮询会话索引间隔 |
安全方面：仅允许 claude:// 前缀 URL；Windows 上通过 rundll32.exe url.dll,FileProtocolHandler 拉起，不经 shell 二次解析；prompt 中控制字符会被清理，超长会截断并在返回值提示。
典型用法¶
下面示例来自 README，可直接在 DSH 工具调用里复现思路：
desktop_send(prompt="把 README 的第一段改短一点", folder="E:\\path\\to\\repo")
desktop_send(prompt="只回复一行 OK", submit=true)
desktop_send(prompt="跑一下 unit test", folder="E:\\repo", submit=true, wait=true)
desktop_read(session="last", turns=2)
desktop_sessions(limit=5)
desktop_continue(session="6bede325-c04e-405a-8681-85a1e060931d")
desktop_open(entry="needs-input")
desktop_probe()
若要在 DSH 里拿到与 CLI 一致的干净 JSON（cost、turns、session_id），README 建议改用 dsh-claude-pilot 的 claude_run；本插件侧重桌面端交接与读本地 transcript。
适用场景与排错¶
适合谁：
- 工作流里要把一步明确交给 Claude 桌面端（Claude Code / Cowork / 新聊天），并在 DSH 里读回最后几轮回答。
- 需要把 CLI 会话 UUID 推回桌面端继续，而不是只在终端里 resume。
注意：
- 首次向某目录投递时，桌面端会要求 工作区信任（日志：
Saved workspace trust for <dir>）。 submit=true依赖窗口前台与 SendKeys，不稳定时可手动 Ctrl+Enter；带wait=true时插件会自动重按发送键（最多 4 轮）。- 排错时先跑
desktop_probe：例如claude://未注册需启动过桌面端；找不到 MSIX 包需确认安装的是 Claude 桌面版（包名Claude_pzs8sxrjxfjjc）；输入框有字但未发送是预期——需submit=true或手动 Ctrl+Enter。
结尾¶
dsh-claude-desktop 用官方 claude:// 深链在 DSH 与 Claude 桌面端之间做 投递、会话交接与本地读回，并把不能插话、不能 CDP 的边界写清楚。进一步了解请查看 GitHub 仓库 与 skillhub 目录页。
