DeepSeek Harness 子代理排查：codex 只报 product-error、条目删不掉与结算崩溃

DeepSeek Harness（DSH）的子代理在「好用的时候很省事、坏起来很难查」之间有明显的落差，本批讨论里有四种典型形态：失败只给一句 Product subagent failure (product: Codex; stage: turn; category: product-error) 而没有任何底层细节；同一个任务用 Codex CLI 能完成、用 subagent_codex 却失败（内置 Codex 版本比用户的配置旧）；删掉子代理的会话目录之后界面条目清不掉；以及最严重的一种——continuable 子代理在结算阶段读收件箱抛异常，把整个进程带成致命退出（exit 1），十几分钟必现。 前三种是「能查但有门槛」，最后一种是「稳定性问题」，处理优先级最高（#9640、#9346、#9552、#8849）。 另外，如果子代理的症状是控制类工具像被换了一套、按 id 寻址失败，那属于「工具被 Team 版替换」的另一族问题，见 DeepSeek Harness Agent Teams 冲突：list_agents 同名与子代理停不掉。

DeepSeek Harness 只报 product-error：细节在投影阶段被折叠掉了

一句话结论：适配器把几种不同的底层错误一并折叠成 product-error，真实的错误标识在这一步就被丢掉；而诊断渲染又只输出固定字段——完整原因虽然还留在失败实例上，却没有任何地方去读它。 于是你拿到的永远是一句没有信息量的类别名（#9640）。

DeepSeek Harness 四步把细节捞出来

1. 先确认「同任务换个入口能成」：如果同样的任务用 Codex CLI 直接跑能完成，说明问题在适配层的通信/分类，而不是任务本身（#9640）。
2. 抓 app-server 通信。社区插件 @argszero/dsh-codex-wire-capture 会把 app-server 的 stdout 分流保存，从而拿到被折叠掉的 codexErrorInfo（#9640）：

npm i @argszero/dsh-codex-wire-capture

3. 按拿到的错误标识查含义，再决定是模型不支持、参数不合法，还是上游回滚引起的失败（#9640）。
4. 判读 stage: turn 的边界：它只能告诉你「失败在本轮执行阶段」，不能替代具体错误；看到它不要就此停手（#9640）。

DeepSeek Harness 版本错配：内置 Codex 比你的配置旧

一句话结论：subagent_codex 会沿用本机 Codex 的配置文件（例如默认模型名），而宿主内置的 Codex 二进制可能是较旧版本，读不懂这个模型，于是启动或首轮就失败——同任务用 CLI 能成，正是因为它用的是你本地那个更新的版本。（#9346） 这类「子代理跑的模型或版本和你以为的不一样」的错配（包括模型继承与推理档不传导），在 DSH plugin 子代理用错模型？subagent 模型继承与排查方法 里有更完整的梳理。

DeepSeek Harness 诊断四件套（对齐这四项，问题通常立刻现形）

1. 解析出的可执行路径：确认子代理实际调用的是哪个 Codex，而不是你以为的那个。
2. 它的版本号：直接执行 codex --version 对照宿主内置版本。
3. 生效的 CODEX_HOME：确认读的是哪一份配置（同一台机器上可能存在多份）。
4. 解析后的模型名：把配置文件里声明的默认模型与「该版本支持的模型」对照（#9346）。

DeepSeek Harness 三条处置

1. 让子代理只用内置版本支持的模型（临时可用，改动最小）（#9346）。
2. 改用较新的 Codex 可执行文件：讨论中给出的、已在 Windows 上验证过的规避是备份并改写插件里构造 Codex 启动参数的函数，让它指向较新的 Codex（属于本机改写，升级插件时会被覆盖）（#9346）。
3. 验证：重跑同一任务，预期子代理能正常启动并完成；若仍失败，回到四件套继续对齐（#9346）。

DeepSeek Harness 删了会话目录，界面条目还在

一句话结论：子代理记录已经改成「写在父会话日志里的目录事件 + 一个投影」，而事件、投影、查询与工具四层都没有移除路径**——记录是只追加的，所以删磁盘目录不会让界面条目消失。** 讨论中做了对照：8 月这样做是有效的、10 月（0.2.0-rc.2）起无效，同一个 UUID 对比（#9552）。

DeepSeek Harness 处置

1. 确认判据：删除子代理的会话目录后，刷新与重启都不再清除该条目；而工作区列表与会话文件本身正常（#9552）。
2. 目前没有用户侧规避：讨论明确说明插件也做不到——折叠逻辑会忽略其它事件类型，客户端插件最多只能做显示层隐藏（#9552）。
3. 可接受的替代做法：把不再需要的子代理会话归档或重命名，用「过滤/排序」减少干扰，而不是试图删除记录。
4. 诉求方向（供反馈上游）：新增 subagent/retire 这类事件 + 折叠时过滤 + 查询与工具跟随（#9552）。

DeepSeek Harness 结算期异常把整个进程带崩

一句话结论：continuable 子代理结算阶段读收件箱时，读取函数在状态取不到值的情况下直接抛出**，而调用它的结算逻辑是一个没有捕获的异步立即执行函数——异常逃逸成未处理拒绝，整个进程致命退出。** 特征是时间上十几分钟必现、崩溃栈能映射到收件箱读取与结算激活两处源码（#8849）。

DeepSeek Harness 四步处置（按优先级）

1. 确认判据：宿主运行十几分钟后无预警退出，退出码为 1；日志里能看到未处理拒绝，栈指向收件箱读取与结算激活（#8849）。
2. 规避（当前唯一有效）：回退到不启用 continuation / activation 机制的旧版本——问题就在这条结算链路上（#8849）。
3. 无法回退时：用外部守护进程自动拉起，把「不可用」降级成「可恢复」；但要注意这会中断所有进行中的会话（#8849）。
4. 记住两层缺陷：一是读取路径不该在「状态未定义」时抛；二是顶层异步立即执行函数必须有兜底。讨论里还指出——「缺日志」本身也是缺陷，因为崩溃前没有任何可用线索（#8849）。

DSH插件 排查注意事项

子代理问题的排查顺序建议：先排除「进程级稳定性」（会不会自己退出），再看「版本错配」，最后才是「诊断信息不足」。 八条要点：

1. 十几分钟必现的退出优先按致命退出处理，别先花时间查诊断文案（#8849）。
2. product-error 的语义是「分类失败」，不等于「产品缺陷」（#9640）。
3. stage: turn 只缩小范围，不定位原因（#9640）。
4. 「CLI 能成、子代理不成」是版本错配的指纹（#9346）。
5. 诊断四件套要一起看：可执行路径、版本、CODEX_HOME、模型名，缺一项都容易误判（#9346）。
6. 本机改写插件文件会被升级覆盖，要记进自己的变更清单（#9346）。
7. 子代理记录是只追加的：删目录 ≠ 删记录，别再指望重启能清掉界面条目（#9552）。
8. 修复状态如实：四条在讨论所指版本（0.2.0-rc.2）里都未修；社区插件能补诊断（抓 wire），但版本错配、条目退役、结算崩溃都需要核心侧改动。

子代理这类问题经常和「装了什么、什么版本」直接相关，尤其版本错配那条。与其在各处手敲命令比对版本，不如用 DSH Plugin Hub 这类可视化插件市场：已安装列表带版本号与来源标记、装卸历史与系统日志集中在一个面板里，先确认「环境里各组件都是什么版本」。

来源：Discussion #9640、Discussion #9346、Discussion #9552、Discussion #8849。