子代理委派桥 Kevin-Y572/zcode-dsh-bridge

dsh-bridge

把 ZCode 子代理的活委派给 DeepSeek Harness（dsh）在 deepseek-v4-flash 上的一次性 headless 运行——主模型只为分发和验收付费。

ZCode 插件：把子代理任务委派给 DeepSeek Harness（dsh）的一次性 headless 运行，重活交给 deepseek-v4-flash，主模型只承担「分发 + 验收」的成本。

工作原理

ZCode 主智能体（贵模型） └─ /dsh 或 dsh-dispatch skill └─ dsh --profile headless "<自包含任务>" ← V4 Flash 在这里做完全部多轮工作 └─ stdout 返回最终总结（做了什么 / 文件清单 / 验证方法） └─ 主智能体核对磁盘改动，提炼摘要给用户

- dsh headless 每次调用都是独立进程：启动 → 执行 → 打印最后一条回复 → 退出。无常驻服务、无监听端口、无需为 dsh 安装任何额外插件（headless profile 随发行版自带）。
- 多个任务可并行分发，各自一个 dsh 进程（前提：任务之间改动的文件不相交）。

安装

1. dsh 侧（一次性）

1. 安装 Node.js（18+），然后全局安装 dsh：

npm install -g @deepseek-ai/dsh
dsh --version

不建议依赖 npx：在 Windows + Git Bash 下 npx 生成的命令 shim 实测无法启动 dsh （报 "'dsh' 不是内部或外部命令"）。全局安装后 dsh 直接可用。

2. 首次配置凭据与模型（用 Web UI 配一次即可，headless 读取同一份配置）：

dsh web

打开 http://127.0.0.1:3080 → Settings → Models：
- 在 DeepSeek 卡片填入 API key（存储于 ~/.dsh/.credentials.yaml）；
- 在模型选择器里选中 deepseek-v4-flash —— 选中的模型即成为新会话的默认模型，headless 会使用它。

配置完成后可以关掉 Web UI。等效的手工方式是在 ~/.dsh/settings.yaml 写入：

agent-default-model:
provider: deepseek-official
model: deepseek-v4-flash

默认模型是全局唯一的，没有按 profile 或按调用覆盖的机制（settings.yaml 里的 agent-default-model 优先级最高，profile 补丁也无法越过它）。把它设为 flash 意味着 web 端新建会话也默认 flash；在 web 里手动选回 v4-pro 会把默认值一并改回——两者共享这一个旋钮，按需权衡。

3. 验证：

dsh --profile headless "reply with: ok"

stdout 输出 ok 即打通。

若启动时报 ERR_MODULE_NOT_FOUND（例如找不到某个 UI 皮肤插件）：~/.dsh/cordis.patch.yml 全局用户层对所有 profile 生效，其中声明的插件必须装进对应 profile。修复：

dsh plugin --profile headless add <报错的包名>

2. ZCode 侧

本仓库自身就是一个 ZCode marketplace（仓库根的 .zcode-plugin/marketplace.json 列出了 dsh-bridge），从 GitHub 安装：

1. ZCode → Settings → Plugin Management → Discover → +，添加 GitHub 仓库地址： https://github.com/Kevin-Y572/zcode-dsh-bridge

2. 在 Discover 中找到 dsh-bridge，安装并启用。
3. 重启会话后即可使用：
- 输入 /dsh <任务描述> 显式委派；
- 或在对话中说"用 dsh / 委派给 V4 Flash 干这个"，dsh-dispatch skill 会被自动触发。

也可以不经 GitHub，把本仓库的本地目录直接添加为 marketplace（ clone 后选其上级目录），适合开发调试。

权限模式说明

skill 默认以 DSH_PERMISSION_MODE=danger-full-access 调用 dsh：沙箱全开、审批自动放行，保证无人值守跑完。这意味着 V4 Flash 智能体拥有与你本机相同的权限——与任何本地编码智能体一致，但请知悉。更保守的替代是默认的 workspace-write（写操作限制在工作区内），代价是超范围的工具请求会被自动拒绝（不会挂起），部分任务会失败收场。

成本与限制

- 主模型 token 节省：中间所有迭代（读文件、工具调用、试错）都记在 V4 Flash 账上；主模型只消费任务描述和最终摘要。子代理分发形态下，dsh 的完整 stdout 由子代理消化，主对话上下文只进提炼后的摘要。
- 单次时长上限：ZCode 的 Bash 工具最长 10 分钟，任务需按此粒度拆分。
- 只有最终回复：headless 不暴露中间过程，因此 skill 强制要求 dsh 输出结构化总结（含文件清单），且改动核心文件后必须验证（读 diff / 跑测试）。完整过程并非丢失：每次调用都会在 dsh 侧留下持久化会话记录（~/.dsh/sessions/，JSONL 事件日志，含全部工具调用与中间消息），可在 dsh web 的会话列表中打开查看，或用 tui 的 --resume <会话ID> 继续。
- 会话记录累积：每次 headless 调用产生一个新会话，append-only、无自动清理，高频使用会让 ~/.dsh/sessions 持续增长，需定期手动清理。
- 冷启动：每次调用有数秒的进程启动开销，高频微任务不划算（直接做更便宜）。

目录结构

zcode-dsh-bridge/
├── .claude-plugin/
│ ├── marketplace.json # marketplace 清单（ZCode 第一探测路径 = Claude Code 期望路径，双工具通吃） │ └── plugin.json # Claude Code 兼容镜像（与 .zcode-plugin/plugin.json 同内容） ├── .zcode-plugin/ │ └── plugin.json # 插件清单（ZCode 优先位置，skills + commands） ├── skills/dsh-dispatch/SKILL.md # 分发流程（核心） ├── commands/dsh.md # /dsh 显式入口 ├── CHANGELOG.md ├── LICENSE # MIT └── README.md

English Quick Start

1. dsh side (one-time): npm install -g @deepseek-ai/dsh, run dsh web, add your DeepSeek API key in Settings → Models, and select deepseek-v4-flash as the default model. Verify with dsh --profile headless "reply with: ok".
2. ZCode side: Settings → Plugin Management → Discover → + → add https://github.com/Kevin-Y572/zcode-dsh-bridge, install dsh-bridge, restart the session.
3. Use: type /dsh <task> in any conversation, or just mention dsh / DeepSeek / V4 Flash / delegation. Bulky, well-scoped implementation or exploration tasks may trigger it automatically.

License

MIT