前言¶
在 DSH（DeepSeek Harness）里跑智能体时，常见做法是换模型、接 MCP，或自己写子进程通道。若你已经在 macOS 上用 ZCode 桌面 app 做项目级编码，又希望 DSH 里的模型能把整段任务交给 ZCode、等它做完再把答案取回，就需要一条不依赖 ZCode CLI 或 stdio 的桥。社区插件 dsh-zcode-native（维护者 ORIOW）走 ZCode 的 CDP 调试端口读写界面 DOM，同时提供本机状态看板与原生子代理工具 subagent_zcode，把「派活—等待—取答」收成闭环。下面介绍它是什么、怎么装、怎么用，以及使用时的硬约束。
这是什么¶
dsh-zcode-native 是 DSH 的原生插件，分类为工作流。一句话定位：把 ZCode 桌面 app 变成 DSH 的子代理后端 / 派活通道——宿主里的模型可以把完整任务派给 ZCode，完成后取回答案。实现上不依赖 ZCode 的 CLI、stdio 或其他通道；只要桌面上开着带 CDP 端口的 ZCode 即可。
插件在架构上拆成两个半身：
- host 半身（
lib/index.js等，跑在 DSH 宿主 Node 进程）：HTTP 路由（仅 loopback）、CDP 客户端连127.0.0.1:<debugPort>、只读状态采集、派活状态机、原生子代理 provider（注册名zcode）。 - client 半身（
lib/client.js，注入 DSH Web 界面）：右侧边栏「ZCode 看板」tab、设置卡里控制看板开关的选项。client 只通过同源 HTTP 读 host 路由，不直连 CDP。
目录页：skillhub.cn/plugins/ORIOW/dsh-zcode-native。源码与说明：github.com/ORIOW/dsh-zcode-native（当前发布版本 v0.1.0，许可证 MIT）。社区插件目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
本机 HTTP 接口（host，仅 loopback）¶
GET /plugins/dsh-zcode-native/status：只读快照，含账号摘要（不暴露 token 正文）、客户端可达性与版本、套餐、catalog 模板等；在cacheMs内返回缓存。POST /plugins/dsh-zcode-native/ask：派活。请求体{"prompt": "..."}（上限 64 KiB），写入 ZCode 输入框并取回答案；多请求在插件内串行排队，生成中会返回busy。
工具 subagent_zcode¶
把 ZCode 注册为 DSH 原生子代理后端。模型可见参数只有：
description（必填）：任务简短描述（3–5 个词）；prompt（必填）：完整自包含的任务文本（ZCode 看不到当前 DSH 对话）。
取消或超时会尝试点击 ZCode 的「停止生成」，避免空转生成阻塞后续派活。派活前会记录标题栏项目名；中途切换会话会以 session-changed 失败，不会误用其他项目的回答。
侧边栏 ZCode 看板¶
DSH 右侧边栏出现「ZCode」tab：账号、套餐到期、余额接口可达性（插件实测余额 API 常报参数错误，看板如实显示不可用、不猜测数值）、客户端版本、catalog 模板数等；约每 60 秒自动刷新，也可手动刷新。可在设置卡关闭（偏好存 localStorage，key dsh-zcode-native:sidebar，默认开启）。
配置项¶
可在 profile 的 cordis.patch.yml insert 块里覆盖（定义于 lib/index.js 的 Config）：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
debugPort |
number | 9222 |
ZCode 的 CDP 调试端口 |
cacheMs |
number | 15000 |
/status 快照缓存有效期（毫秒） |
askTimeoutMs |
number | 600000 |
派活等待答案超时（毫秒） |
前置条件与安装¶
环境¶
- macOS（Windows / Linux 未验证）；DSH Desktop 与 ZCode 3.17.1。
- ZCode 必须用 CDP 端口启动，且需先完全退出（Cmd+Q）再从终端启动，否则 Electron 单实例会拒绝
--remote-debugging-port：
/Applications/ZCode.app/Contents/MacOS/ZCode --remote-debugging-port=9222
仓库也提供 scripts/zcode-debug.sh（默认 9222，会先退旧实例再启动）。
安装与启用¶
在 DSH 里装最省事：设置 → 插件 → 安装插件，粘贴：
github:ORIOW/dsh-zcode-native#v0.1.0
等价 CLI（只装依赖，装完还须在插件页勾选启用 dsh-zcode-native）：
dsh plugin --profile web add "github:ORIOW/dsh-zcode-native#v0.1.0"
装完重启 DSH Desktop（host 半身不热重载）。开发时可本地 link: 挂载或 .tgz/绝对路径安装，详见 README 的 B、C 两节。
安装前建议自行浏览源码与 MIT 许可证；插件以当前 DSH 进程权限运行，会读取 ~/.zcode/v2/credentials.json 并按 ZCode 同源算法解密信封，token 仅用于本机请求 https://zcode.z.ai 的套餐相关接口，不回显、不进 HTTP 响应。
典型用法¶
装好后在 DSH 里正常对话即可，模型可调用 subagent_zcode，也可直接 POST /plugins/dsh-zcode-native/ask。README 中的示例意图如下：
用 ZCode 查一下
~/Projects/foo里pnpm test为什么在第 3 个用例挂掉，把根因和改法带回来。把这个仓库的
lib/ask.js通读一遍，列出所有会抛错的分支和它们的错误码。
三条硬规则（ZCode 看不到 DSH 对话）：
- prompt 必须自包含：路径、验收标准写全，不要用「上面那个文件」。
- 派活前让 ZCode 停在目标项目会话：composer 只属于当前可见会话；切走会
session-changed失败。 - 一次一件活：串行队列，忙时新任务为
busy。
默认最多等 10 分钟（askTimeoutMs 可调）。派活日志在 ~/Library/Logs/DSH Desktop/harness.log，关键字 [zcode-native]；prompt 与答案正文不进日志，只记长度。
适用场景与注意¶
适合：已在 macOS 上用 ZCode 3.17.1 做项目编码，希望在 DSH 工作流里把独立子任务（读仓、跑测、通读文件等）交给 ZCode，并在界面侧边栏一眼看到账号与套餐状态。
注意：
- 插件不会替你启动 ZCode 或切换项目；CDP 端口、目标会话都需你手动准备好。
- 一次只服务一个 ZCode 会话，派活串行；界面 DOM 随 ZCode 版本变化可能导致选择器失效（当前按 3.17.1 校准）。
- 所有 HTTP 路由仅接受 loopback，非本机来源 403。
结尾¶
dsh-zcode-native 把 ZCode 桌面端接成 DSH 的状态看板、CDP 派活闭环与原生子代理后端，适合「DSH 编排 + ZCode 动手」的分工。进一步了解可打开 目录页 与 GitHub 仓库。
