mjylfz/dsh-subagent-codex

让 DeepSeek Harness 里的 agent，把活儿丢给真正的 OpenAI Codex 去干。

English | 中文

---

一句话说清楚

这是一个 DSH 插件。装上它，你的 DSH 会话里会多一个 subagent_codex 工具——你（或你的主 agent）把任务扔给它，它就在你本机的 Codex CLI 里独立跑一遍，再把结果拿回来。任务在 Codex 自己的环境里执行，用的是 Codex 的模型和工具链，跟 DSH 主对话完全隔离。

简单说：DSH 负责统筹，Codex 负责干活。

什么时候用它？

举几个真实场景（都是有点分量的活儿，Codex 很擅长）：

• 职场：竞品调研 —— 让 codex 帮我做一份竞品分析：把市面上 3 款主流笔记软件的定价、功能、优缺点都对比一遍，再结合我的使用场景给出选型建议，最后整理成一份能直接发给老板的汇报材料 —— Codex 自己上网查、横向对比、按你的需求给结论，回来就是一份能直接用的成品。
• 学习：把一个陌生领域彻底搞懂 —— 让 codex 帮我彻底搞懂"什么是区块链"：它会把这个问题拆成 5 个递进的小问题（是什么、怎么运作、解决了什么问题、和传统方案差在哪、有哪些争议），每个问题查多个来源交叉验证，用生活类比 + 图解 + 术语对照表讲清楚，最后输出一份带 FAQ 的完整学习文档 —— 这不再是"查个资料写篇文"：Codex 会像做研究一样系统地拆解、验证、组织，一次交付一份结构完整的深度学习材料。
• 创作：内容策划 —— 让 codex 帮我策划一篇小红书爆款笔记：给出 3 个选题方向，每个配上标题、开头钩子和正文大纲，再帮我搜集 5 条支撑素材 —— 一次调用给你整套创作方案，从选题到素材一步到位。
• 开发：跨模块改造 —— 让 codex 把用户认证从 JWT 迁移到 OAuth2：改鉴权中间件、补数据库迁移脚本、写单元测试和集成测试，全部跑通后整理成一份提交说明 —— 一整条开发流水线：动手改代码、补测试、跑通、总结，交付整套改动，你只负责 review。

什么时候不适合用它：任务需要在 DSH 内部完成时（比如要调用 DSH 的记忆、会话历史、其他 DSH 工具）——那种活儿留给普通 subagent。

快速开始

1. 前提

• 已安装 Codex CLI 并登录（~/.codex/auth.json 存在）。
• 已安装 DeepSeek Harness。

2. 安装

# 通过 dsh 插件命令安装（dsh.bundle 声明会自动把插件加进 bundle 栈）
dsh plugin --profile web add dsh-subagent-codex
# 或本地 tgz 安装
dsh plugin --profile web add file:/path/to/dsh-subagent-codex-0.1.1.tgz

3. 重启，开聊

重启 DSH 后新开一个会话，直接说：

让 codex 调研一下大语言模型推理加速的最新论文进展，整理成一篇带对比的综述
让 codex 子 agent 做 XX

工具名是 subagent_codex，每次调用 = 启动一次独立的 Codex CLI 任务。

配置

插件在配置树里注册两行：

id	作用
subagent-codex	codex provider 插件行
tool-subagent-codex-enabled	subagent_codex 工具行（one-shot）

provider 行支持的配置项：

- id: subagent-codex
  name: 'dsh-subagent-codex'
  config:
    command: codex            # codex CLI 可执行文件（PATH 名或绝对路径）
    cwd: /path/to/workdir     # 可选，子任务工作目录（缺省继承父会话 workspace）
    model: o3                 # 可选，指定模型（codex exec -m）
    sandbox: workspace-write  # 可选：read-only | workspace-write | danger-full-access
    timeoutMs: 600000         # 单次任务超时（毫秒）
    maxOutputChars: 40000     # 返回给委派方的输出上限

工作原理（技术细节）

• 插件实现 DSH 的 SubagentProvider 接口（@deepseek-ai/dsh-subagent 的 out-of-process 契约），注册名为 codex 的 provider。
• 因为是外部进程，provider 不声明任何 start 能力（NO_START_CAPABILITIES）：外部 CLI 无法强制执行 outputSchema / maxDepth / toolFilter / persona。
• 每次委派 spawn 一次 codex exec --json --skip-git-repo-check <prompt>，解析 JSONL 事件流，取最后一条 agent_message 文本作为最终输出。
• 支持取消（AbortSignal → SIGKILL）、超时、输出截断。结果永远 resolve（正常 / 中止 / 失败都解析为终态），不会把异常抛给主对话。

可追溯性：每次运行都有完整记录

插件不带 --ephemeral，所以每次调用 Codex 都会把完整会话写到磁盘：

~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<session-id>.jsonl

这个文件里是这次任务的完整对话（输入、Codex 的中间过程、最终输出）。你可以：

• 用 codex resume 找回这个会话继续聊；
• 需要长期归档时执行 codex archive <session-id>，会移入 ~/.codex/archived_sessions/。

常见问题

Q: 为什么 DSH 侧边栏看不到 codex 子 agent 的运行记录？ A: 设计如此。DSH 的侧边栏子 agent 树只显示 DSH 内部子 agent（有 DSH 会话）。Codex 是外部进程 provider，运行时不创建 DSH 会话，所以 GUI 里不显示。想看运行过程，去上面说的 ~/.codex/sessions/ 目录。

Q: 需要装 Codex 的桌面 app 吗？ A: 不需要。插件直接调用 codex CLI。桌面 app 装不装都不影响。

Q: 报错说找不到 codex 命令（spawn … ENOENT）怎么办？ A: 插件在你本机的 PATH 里找 codex 可执行文件。如果找不到，先确认 Codex CLI 已安装：codex --version。如果已安装但不在 PATH（比如装在非默认位置），在配置里把 command 指向它的绝对路径：command: /path/to/codex。

Q: 会消耗我的 OpenAI 额度吗？ A: 会。每次调用都用你 ~/.codex 登录的账号跑 Codex，消耗的是 Codex 的 token 额度。

License

MIT