dsh-subagent-cwd
为 DeepSeek Harness（dsh）提供增强版子代理委派工具，
支持按次指定工作目录（cwd）。
包含 dsh-subagent-tools 的全部能力（按次 model / provider /
persona / toolFilter 覆盖、@preset: 引用、provider/model 复合 id）再加按次 cwd 参数——并附带
让 cwd 真正生效所需的两处进程内 provider 补丁。
两个包二选一，不要同时装
| 包 | 按次 model/provider/persona/toolFilter | @preset: |
cwd |
补丁 |
|---|---|---|---|---|
| dsh-subagent-tools | ✅ | ✅ | ❌ | 无（纯 bundle） |
| dsh-subagent-cwd（本包） | ✅ | ✅ | ✅ | 2 处 provider 补丁 |
二选一安装。两者暴露相同的工具面（subagent / subagent_fork），同时装会因工具名冲突互相打架。
为什么 cwd 需要补丁（而其他功能不需要）
SubagentStartRequest 没有 cwd 字段，进程内驱动层构建子代理会话 meta 时只用
childSessionMeta(parent, ...)——按次 cwd 根本不会透传。进程内子代理有两条创建路径，两条都必须
打补丁，否则就会踩到经典陷阱：前台路径认 cwd、后台路径静默忽略：
| 路径 | 要改的包 | 文件 |
|---|---|---|
| 前台（one-shot） | @deepseek-ai/dsh-subagent-in-process-driver |
lib/index.js |
| 后台（continuable） | @deepseek-ai/dsh-subagent |
lib/index.js（bundle！不是 lib/types/continuation.js） |
第二处是 bundle 陷阱：该包 package.json 的 main/exports 指向 lib/index.js（内含 continuation
manager 的内联副本）。改长得像源码的 lib/types/continuation.js 不生效——必须改并验证 bundle。
persona × preset 并存（补丁 v2）
preset 与 persona 同时给出时（例如
subagent(preset: "@preset:router-standard", persona: "@preset:翻译员")），旧补丁会把 per-call
persona 注册成 deployment:persona 段，随后被目标 preset 的 router-bootstrap 类插件按名删除
（applyPersona 会清掉所有名字含 "persona" 的段）——角色 persona 静默丢失。
v2 补丁（install.ps1 的 hunk 3 / hunk 5，三态兼容：原始 / 旧补丁 / 新补丁均可升级）改为：
- preset + persona 同给时跳过 deployment:persona 注册；
- recompose 之后把 per-call persona 注册为 delegation:role（order 1，名字不含
"persona"），router 删不到它，于是 preset 自身的推理 persona 与委派的角色 persona 并存。
只传 persona（无 preset）时行为不变：仍走 deployment:persona 的 shadow 语义。
补丁 v2 的 hunk 3–5 目前仅在 install.ps1（Windows）实现；POSIX 的 install.sh
preset hunks 将在后续补齐。届时在 Linux 上 preset 参数会被接受，但在该补齐落地前不会
真正 recompose。
⚠️ 限制警告：router-style 预设下 persona 失效
即使有补丁 v2，当子代理/成员组合使用 router-style 预设（如 @preset:dsh-router-standard）时，
per-call persona 依然不会进入系统提示。这是 router-style 预设的机制性行为：其
system-prompt/assemble 钩子会删除所有段名含 "persona" 的段，并注入预设自带的动态
persona。因此最终生效的只有预设自带动态 persona，自定义角色文本被静默丢弃。
缓解建议：
- a) 改用非 router-style 预设（如 standard），让 persona 参数正常生效；
- b) 把角色设定通过消息层注入（首轮 prompt 前缀 / 任务消息前缀，如 agent-teams 的
拼接机制），不依赖 cwd；
- c) 或接受 router-style 下 persona 参数失效（预设动态 persona 生效）。
安装
# 1. 安装插件（npm / git / 本地目录）
dsh plugin --profile web add dsh-subagent-cwd
# 2. 应用两处驱动层补丁（cwd 生效必需）
powershell -ExecutionPolicy Bypass -File patches\install.ps1 # Windows
# 或：./patches/install.sh # POSIX
安装后重启 dsh --profile web。
升级 dsh 之后
dsh 升级会重写 node_modules，两处补丁都会丢失。每次升级后：
# 重跑安装脚本（幂等；anchor 不匹配会自动报错）
powershell -ExecutionPolicy Bypass -File patches\install.ps1
若安装脚本报 "anchor not found"，说明目标包结构变了——检查是否有新版本，或提 issue。
卸载
powershell -ExecutionPolicy Bypass -File patches\uninstall.ps1 # Windows
# 或：./patches/uninstall.sh # POSIX
dsh plugin --profile web remove dsh-subagent-cwd
示例
让子代理在不注入项目 AGENTS.md 的目录里干活：
subagent(description="总结这个文件", prompt="...", cwd="D:\\projects\\scratch\\notes")
设计要点
- 工具面是 bundle——官方
tool-subagent/tool-subagent-fork行被禁用并替换，工具面本身不改任何官方文件。 cwd是唯一无法保持 bundle-only 的能力。SubagentStartRequest没有 cwd 字段，按次 cwd 必须由进程内
subagent provider 透传——所以需要patches/里的两处小补丁（各一个 hunk），幂等、首次运行自动备份、
node --check校验。这就是本包与dsh-subagent-tools分开存在的原因。- 版本契约：
peerDependencies锁定公开 dsh 包（0.1.1-rc.1）；补丁针对同一版本。dsh 升级会重写
dsh 安装的node_modules并清掉两处补丁——每次升级后重跑patches/install.ps1/install.sh
（见"升级 dsh 之后"）。bundle 本身装在 profile 自己的node_modules，升级后仍在，但官方 API 一旦变化，
peerDependencies会显式拒绝加载。
已验证
在干净（无本地补丁）的 dsh 0.1.1-rc.1 Windows 环境实测（headless + web）：
dsh-subagent-tools的全部验证项（按次 model/provider/persona/toolFilter、@preset:、presetHints）✅cwd前台路径 ✅ —— 子代理的pwd和沙箱工作区都切到指定目录cwd后台（continuable）路径 ✅ —— 后台子代理同样生效（"前台认、后台静默忽略"的经典陷阱未复现）toolFilter作用域 ✅patches/install.ps1与patches/uninstall.ps1往返 ✅（备份→打补丁→node --check→还原→复验）
限制
- 补丁已适配 rc.1（0.1.1-rc.1）。 两处补丁匹配 rc.1 官方源码的精确锚点；dsh 再次升级后若锚点失效，重跑
patches/install.ps1（报 "anchor not found" 即需适配新版本）。rc.1 官方已原生支持按次persona/toolFilter
（applyChildComposition直接消费request.persona），补丁只补官方仍缺的按次cwd与presetrecompose。 @preset:依赖本地预设布局 —— 与dsh-subagent-tools相同。- Web 会话需要 preset 适配脚本（
install-preset.ps1）——原因同dsh-subagent-tools。
License
MIT
