@sakki_chin/dsh-codex-orchestrate

把 Codex 任务按 YAML schema 编排成 DAG 工作流的 DSH 插件。每个节点是一个独立的 codex session，下游首轮会自动拿到直接依赖节点的终态结果；进度在 DSH 右侧边栏以原生 React tab 呈现（DAG 连线 + 逐轮 conversation）。

• 派发方式：DSH agent 调用 codex_orchestrate tool（异步 + 可查进度），或直接调 HTTP API
• 每个节点独立 codex session，终态后可在工作台里继续对话（resumeThread，不重跑下游）
• 运行中也能改 DAG：kind: nodePatch 原子化新增 / 修改 / 删除尚未执行的节点
• 工作流状态 append-only 落盘，进程重启后历史仍可查

环境要求

项	要求
DSH	Desktop 或 dsh CLI
codex CLI	已安装并 codex login（订阅登录）或设置 OPENAI_API_KEY
Node	≥ 20

插件完全复用本机 codex 登录态（~/.codex/auth.json）：不代管、不刷新、不转发 token。派发前会做一次只读探测，没有登录态就直接报错，不会烧掉一个必然失败的 turn。

安装

dsh plugin add --profile web @sakki_chin/dsh-codex-orchestrate

--profile 换成你的 profile 名（真源：~/Library/Application Support/DSH Desktop/profile-selection/state.json，一般是 web）。

安装后需要完全重启 DSH：包元数据（含"是不是客户端包"的判定）按 Loader specifier 缓存到进程重启，刷新页面不够。

从本地目录安装（开发用）

cd <插件源码目录>
npm install
npm run build:client
dsh plugin add --profile web "$PWD"

pnpm 会写成 link: 软链，所以之后改源码 → npm run build:client → 宿主 HMR（约 500ms 轮询）会原地重挂载，无需重启或刷新。

打开工作台

右侧边栏 → 点标签条的 **+（「新标签页」）**打开引导页 → 选「Codex Orchestrate」。

也可以右键任意 tab，从 tab 菜单里进入。

使用

由 DSH agent 派发

codex_orchestrate(yaml: "...")

• kind: workflow 创建
• kind: workflowQuery 查询（省略 workflowId 返回清单）
• kind: nodePatch 对尚未执行的节点做原子化增删改

tool 立即返回 { workflowId, nodes, progress, progressUrl, instance }。

用 progressUrl（绝对地址，可直接 GET），不要用 progress（相对路径，需你自己知道 host:port——曾因此把跨实例查询误判成「workflow 不存在」）。instance.instanceId 用于确认「我查的是不是派发我的那个实例」。

YAML schema 见包内 schema/workflow.schema.md（规范说明 + 回传契约），校验真源是 schema/workflow.schema.json。

调度语义

• 节点按 dependsOn 调度，无依赖（或依赖已满足）的节点并发执行，受 concurrency 上限约束（默认 3）
• 下游节点首轮 prompt 自动注入所有直接依赖节点的终态结果
• 节点未显式写 cwd 时，继承发起 DSH 会话的工作目录
• 单节点 timeoutS 默认 600；onFailure: fail（默认）阻塞下游，continue 照常调度

直接 HTTP

POST /codex-orchestrate/api/dispatch   { "yaml": "..." }
GET  /codex-orchestrate/api/workflows
GET  /codex-orchestrate/api/state?workflowId=wf_xxx
POST /codex-orchestrate/api/message    { workflowId, nodeId, text, clientMessageId }
POST /codex-orchestrate/api/cancel     { workflowId, nodeId }
GET  /codex-orchestrate/api/events?workflowId=wf_xxx    # SSE

状态持久化

workflow 状态 append-only 落盘到 $DSH_HOME/workflows.jsonl。

• 进程重启后历史仍可查：/api/state 未命中内存时自动从磁盘回读
• 重启前处于 running/queued 的节点会被照实标成 cancelled，而不是永远停在 running 骗查询方
• 文件尾部半行 / 损坏行会被跳过，不影响其余历史
• 落盘失败（磁盘满 / 权限）只记一条警告，不打断正在跑的工作流

配置

环境变量	作用
DSH_CODEX_MODEL	节点缺省模型（默认 gpt-5.6-sol）
DSH_CODEX_CLI	指定 codex CLI 可执行文件路径
DSH_CODEX_MODULES	额外的 node_modules 目录（用于找 @openai/codex-sdk、YAML 解析器）
DSH_CODEX_STATE_DIR	覆盖状态落盘目录
DSH_CODEX_DEBUG_EVENTS	打印原始 codex 事件流
CODEX_HOME	codex 登录态目录（默认 ~/.codex）

也可在节点上写 model: 覆盖全局缺省。不要用 gpt-5-codex——该 slug 在 ChatGPT 订阅登录下会被服务端拒绝（not supported when using Codex with a ChatGPT account）；订阅可用 gpt-5.6-sol / gpt-5.6-terra / gpt-5.6-luna / gpt-5.5。

排查

http://127.0.0.1:43120 返回 403 —— 这是 DSH Desktop 的 Electron 门禁，对所有非渲染器请求一律拒绝，不是插件故障。无头脚本穿不透它。

节点报「未找到 @openai/codex-sdk」 —— 设置 DSH_CODEX_MODULES 指向含该包的 node_modules；或在本插件目录执行 npm install。

Tab 菜单里没有「Codex Orchestrate」 —— 依次确认：右侧边栏已展开；包已装进 profile（dsh plugin ls --profile web）；DSH 已完全重启。若右栏当前是引导页且尚无扩展条目，右键不会弹菜单，点 + 打开引导页即可看到入口。

开发

npm install
npm run build:client     # 产出 lib/client.js（lazy-CJS 包装，宿主冻结模块全部 external）
npm run verify:edges     # DAG 连线几何自证：采样每条路径，逐点判定是否覆盖节点卡片
node server/orchestrator.test.cjs
node server/plugin.test.cjs

npm publish 会通过 prepublishOnly 自动构建并跑一遍几何自证。

边界

• 运行句柄在内存中：进程重启时未完成的节点/轮次标为 cancelled，已完成历史从 JSONL 恢复
• 只呈现当前进程派发的工作流
• file_change 事件只有路径与 add/delete/update，无 diff 正文（SDK 限制）

License

MIT