前言¶
在 DSH 里做复杂任务时，主智能体往往要兼顾对话、工具调用和较长链路的工作。若把整块编码、审查或探索丢给单一模型，上下文和权限边界都难控；若手工切换多个 CLI，又很难把进度、用量和结果统一回主会话。
dsh-maestro-codex 面向上述场景：在宿主 DSH 进程内注册派发工具，由主代理按任务类型与难度门槛，把子任务交给 headless 的 Codex CLI、Claude Code CLI 或 Grok CLI 执行，并把结果自动回填。路由、CLI 安装、模型注入、技能桥接与监视界面集中在插件配置页完成。
这是什么¶
dsh-maestro-codex 是 DSH 的 CLI 子代理编排插件（npm 包名 dsh-maestro-codex，当前发布版本 v0.1.15，MIT 许可证）。维护者为 GaoHu1997（仓库与 SkillHub 目录页 一致）。
一句话定位：把会话中的任务按类型派发给 codex cli、claude cli 或 grok cli 执行，取回结果回填主会话；并在配置页管理路由表、各 CLI 的权限与模型，以及 CLI 本身的安装与卸载。
核心功能¶
下面按主流程概括 README 已说明的能力，不涉及未在文档中出现的行为。
派发与难度门槛¶
主会话注册 dispatch_cli_task 工具。派发前主代理先判断是否需要子代理；不需要则自行完成。需要时再评估难度并给出理由：达到为对应 CLI 配置的门槛才启动外部 CLI，未达门槛则改用 DSH 内置子代理（subagent / subagent_fork），不拉起 CLI。
Claude、Codex、Grok 各自独立的最低难度（低 / 中 / 高 / 极高，默认中）在「CLI 管理」中配置，互不影响。调用时传 task_difficulty（low / medium / high / extreme）与 difficulty_reason；显式指定 cli 也不能绕过门槛。
任务类型路由¶
配置页以卡片为 13 个内置四字任务类型指定执行器。默认分工在 README 中写明：例如 Claude 侧偏仓库探索、影响分析、模块重构等；Codex 侧偏功能开发、缺陷修复、测试验证等。旧类型名会映射到新名称并保留关键词兼容。
CLI 与 SDK 管理¶
配置页检测版本，并可通过 npm 全局安装或卸载：
@anthropic-ai/claude-code@openai/codex@xai-official/grok
支持自定义 npm registry；「SDK 管理」区负责 Claude Code SDK / Codex SDK 的检测与装卸。Claude / Grok 权限策略、Codex 沙箱档位（read-only / workspace-write / danger-full-access）与并发上限均在配置页设置；连续无输出超时为各 CLI 共用一项，放在「调度设置」。
模型与思考等级¶
模型下拉直接读取 DSH 已配置的供应商与模型（llm-pi-ai 设置与 credentials）。选中后插件在 spawn 前注入端点、密钥与协议方言，并做 1-token 级模型预检；两端点都不可用则任务直接失败并列原因，不会静默回落到 CLI 自有配置文件中的模型（Codex 派发时使用 --ignore-user-config）。
思考等级来自所选 DSH 模型条目的 reasoningEfforts 档位，不写死枚举。
技能与宿主工具桥接¶
派发时通过随包的 dsh_bridge stdio MCP 服务器，把 DSH 技能目录（两段式按需加载）与宿主工具桥接给子代理。Claude 可选原生模式（claudeSkillsMode: native），将技能暂存为 .claude/skills 树；失败时回退桥模式。桥接策略含 bridgeTools: off / auto / custom。
监视、看板与会话续接¶
- 任务监视：记录
dispatch_cli_task派发的子任务，展示进度事件、取消、超时与并发。 - 任务看板：安装 dsh-better-sidebar 后，右侧栏增加「任务看板」tab，以分层树状图查看主智能体与各子智能体阶段与耗时。
- CLI 会话页：回放任务与结果，统计 Token；底部输入框可续发消息（
POST /task/reply，底层走各 CLI 的 resume 语义）。
用量与可靠性¶
用量写入 $DSH_HOME/maestro/usage-journal；任务结果落盘至 $DSH_HOME/maestro/tasks/<taskId>.json，重启后恢复最近 40 条。提供 GET /health、GET /status 等接口；同一父会话 + CLI + 任务名 + cwd 在 10 分钟内重复派发可由幂等键挡下。进程被杀遗留的任务在下次启动标记为 已中断（interrupted）。
安装与启用¶
安装插件本体¶
README 写明：
安装到 dsh：在 dsh 插件市场或插件管理器安装本包；
cordis.patch.yml会把dsh-maestro-codex条目插入 profile。
SkillHub 上条目为 GaoHu1997/dsh-maestro-codex，可与目录页「发送给 DeepSeek Harness 安装」的说明对照。文档未给出固定的 dsh plugin add … 命令行，请以上述市场或管理器路径为准，不要凭仓库名自行拼接安装命令。
安装包运行要求 Node >=22.19（内置 fetch）。
安装并配置 CLI¶
- 在 DSH 中打开本插件「配置页 · CLI 管理」。
- 按需为 Claude / Codex / Grok 检测版本并执行全局 npm 安装（或使用「SDK 管理」安装对应 SDK）。
- 为各执行器勾选任务类型、最低难度，并在「dsh 模型」下拉选择可用供应商与模型。
- 在「调度设置」中设置连续无输出超时与并发上限。
启用后，主会话即可使用 dispatch_cli_task；补丁会自动把插件条目写入 profile。
典型用法¶
主会话内派发¶
典型流程不由单独脚本驱动，而是由主智能体在对话中调用 dispatch_cli_task：
- 主代理判断任务是否值得开子代理。
- 若需要，评估
task_difficulty与difficulty_reason，由路由表选择 CLI。 - 未达该 CLI 门槛时，回落 DSH 内置子代理，不启动外部 CLI。
- 子任务结束后，结果与用量投影回主会话；可在会话内任务列表与 CLI 子会话页查看。
工具参数可显式指定 cli 或 provider::model；后者锁定 DSH 供应商，且仍须通过预检与门槛校验。
配置页日常运维¶
- 在「CLI 管理」调整某类任务改派执行器，或临时关闭某一 CLI。
- 在 CLI 会话页对已完成任务 续发消息，沿用原难度门槛与路由，并继承上一轮 DSH 模型配置（服务端按协议过滤可选模型）。
命令行查看状态快照¶
README 提供运维脚本（需在实际插件安装目录下执行，或使用脚本绝对路径）：
node scripts/maestro-status.mjs --json
该脚本依赖与插件相同的 Node 版本，用于读取 GET /status 一类信息的命令行快照；亦可结合 GET /health 做健康检查。
适用场景与注意¶
适合谁：已在 DSH 中集中配置多供应商模型，并希望把「大块编码 / 审查 / 探索」交给专业 CLI、同时保留主会话编排与可观测性的开发者。
生态说明：DSH 奉行「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无文档所载的官方从属关系。
安全与权限：插件在 当前 DSH 进程权限 下运行，会 spawn 外部 CLI 并可能桥接宿主工具。安装前应阅读 GitHub 源码 与许可证，并查阅仓库内 CLI 安全说明。Codex 沙箱与 Claude 权限模式务必按环境审慎选择；danger-full-access 等高档位仅应在可信环境中启用。
依赖与可选组件：任务看板完整体验依赖 dsh-better-sidebar；未安装时仍可使用任务监视与会话内列表。Grok 执行器默认关闭，需在配置页显式启用。
结尾¶
dsh-maestro-codex 把多 CLI 子代理纳入同一套 DSH 配置、路由与账本：主会话只做该不该派、派给谁，执行与回放留在插件提供的监视界面里。若要进一步核对行为边界与恢复流程，请直接阅读仓库 README 与 docs/ 下的可靠性、任务板说明。
