@sakki_chin/dsh-codex-orchestrate 1.0.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@sakki_chin/dsh-codex-orchestrate",
+  "version": "1.0.0",
+  "description": "DSH 插件：把 Codex 任务按 YAML schema 编排成 DAG 工作流，并在 DSH 右侧边栏以原生 React tab 呈现 DAG 进度与逐节点会话。",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "codex",
+    "orchestrate",
+    "workflow",
+    "dag"
+  ],
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "server/plugin.mjs",
+  "exports": {
+    ".": "./server/plugin.mjs",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ]
+    }
+  },
+  "files": [
+    "server",
+    "schema",
+    "lib",
+    "client",
+    "scripts",
+    "cordis.patch.yml",
+    "esbuild.client.mjs"
+  ],
+  "scripts": {
+    "build:client": "node esbuild.client.mjs",
+    "verify:edges": "node scripts/verify-edge-routing.mjs",
+    "prepublishOnly": "npm run build:client && npm run verify:edges"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@openai/codex-sdk": "0.154.0"
+  },
+  "devDependencies": {
+    "@ant-design/x-markdown": "2.9.0",
+    "esbuild": "0.28.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  }
+}

package/schema/workflow.example.yaml

@@ -0,0 +1,32 @@
+apiVersion: codex.dsh/v1
+kind: workflow
+title: 原型仓发布准备
+goal: 校验测试、构建并起草变更说明，产出可发布的工件清单
+concurrency: 3
+nodes:
+  - id: verify
+    title: 跑通测试与 lint
+    prompt: |
+      在仓库根目录运行单元测试与 lint，汇总失败项与修复建议。
+      输出：失败清单（文件:行号:规则）+ 一句话修复建议。
+    model: gpt-5.6-sol
+    sandboxMode: read-only
+    timeoutS: 900
+
+  - id: build
+    title: 构建产物并校验体积
+    prompt: 执行生产构建，报告产物体积与明显的体积回归（阈值 +10%）。
+    dependsOn: [verify]
+    sandboxMode: workspace-write
+
+  - id: docs
+    title: 起草变更说明
+    prompt: 基于 git log 最近 20 条提交起草用户可读的变更说明（中文，分组列出）。
+    dependsOn: [verify]
+    reasoningEffort: low
+
+  - id: release
+    title: 汇总发布清单
+    prompt: 汇总以上产物，输出发布检查单（Markdown 表格）。
+    dependsOn: [build, docs]
+    onFailure: fail

package/schema/workflow.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.local/schemas/codex-orchestrate/workflow.v1.json",
+  "title": "DSH Codex Orchestrate Workflow",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["apiVersion", "kind"],
+  "properties": {
+    "apiVersion": { "const": "codex.dsh/v1" },
+    "kind": { "enum": ["workflow", "nodePatch", "workflowQuery"] },
+    "workflowId": { "type": "string", "pattern": "^wf_[a-z0-9]+$" },
+    "title": { "type": "string", "minLength": 1, "maxLength": 120 },
+    "goal": { "type": "string", "maxLength": 2000 },
+    "concurrency": { "type": "integer", "minimum": 1, "maximum": 16 },
+    "nodes": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "items": { "$ref": "#/$defs/nodeMutation" }
+    },
+    "remove": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/nodeId" }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "kind": { "const": "workflow" } } },
+      "then": {
+        "required": ["title", "nodes"],
+        "properties": {
+          "nodes": { "items": { "$ref": "#/$defs/node" } }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "nodePatch" } } },
+      "then": { "required": ["workflowId"] }
+    }
+  ],
+  "$defs": {
+    "nodeId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$" },
+    "nodeMutation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nodeId" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "prompt": { "type": "string", "minLength": 1, "maxLength": 32000 },
+        "model": { "type": "string", "maxLength": 120 },
+        "cwd": { "type": "string", "pattern": "^/" },
+        "dependsOn": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/nodeId" },
+          "uniqueItems": true,
+          "maxItems": 16
+        },
+        "sandboxMode": { "enum": ["read-only", "workspace-write", "danger-full-access"], "default": "danger-full-access" },
+        "approvalPolicy": { "enum": ["never", "on-request", "on-failure", "untrusted"] },
+        "reasoningEffort": { "enum": ["minimal", "low", "medium", "high"] },
+        "timeoutS": { "type": "integer", "minimum": 30, "maximum": 7200 },
+        "onFailure": { "enum": ["fail", "continue"] }
+      }
+    },
+    "node": {
+      "$ref": "#/$defs/nodeMutation",
+      "required": ["id", "prompt"],
+      "properties": {}
+    }
+  }
+}

package/schema/workflow.schema.md

@@ -0,0 +1,112 @@
+# DSH Codex Orchestrate · Workflow YAML Schema (v1)
+
+`codex_orchestrate` tool 的唯一入参格式。DSH 按此 schema 创建、查询和动态修改 codex 工作流；
+插件负责原子校验、调度依赖、并发执行、持久化与进度回传。
+
+## 设计原则
+
+1. **一份文档一个意图**：`kind: workflow` 创建工作流；`kind: workflowQuery` 查询；
+   `kind: nodePatch` 对已有工作流的未来节点做原子化**新增 / 修改 / 删除**。
+2. **节点 = 一个独立 codex session**：每个节点拥有自己的 Thread、消息历史与产物。
+3. **依赖是声明式的**：`dependsOn` 指向同工作流内节点 id；环依赖、悬空引用在校验期拒绝。
+4. **并发受控**：无依赖（或依赖已满足）的节点并发执行，受顶层 `concurrency` 上限约束。
+
+## 顶层字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `apiVersion` | `codex.dsh/v1` | ✓ | 固定值 |
+| `kind` | `workflow` \| `nodePatch` \| `workflowQuery` | ✓ | 创建、动态修改或查询 |
+| `workflowId` | string | nodePatch 必填 | 目标工作流；query 省略时返回工作流清单 |
+| `title` | string | workflow 必填 | 人可读标题 |
+| `goal` | string | — | 总目标描述（展示用） |
+| `concurrency` | int 1–16 | — | 并发节点上限，默认 3 |
+| `nodes` | Node[] | workflow 必填 | 创建节点；nodePatch 中为新增/局部更新 |
+| `remove` | string[] | — | nodePatch 中真正删除的节点 id |
+
+## Node 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | `[a-z0-9][a-z0-9-]{0,63}` | ✓ | 工作流内唯一 |
+| `title` | string ≤120 | — | 缺省取 id |
+| `prompt` | string 1–32000 | 新增时必填 | 发给 codex 的任务指令；更新已有节点时可省略 |
+| `model` | string | — | 缺省 `gpt-5.6-sol`（可用环境变量 `DSH_CODEX_MODEL` 覆盖）。必须是当前登录方式可用的 slug：`gpt-5-codex` 在 **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` |
+| `cwd` | string | — | codex 工作目录（绝对路径）；省略时继承发起 DSH 会话的工作目录 |
+| `dependsOn` | string[] | — | 前置节点 id；不得自引用；直接依赖的终态结果会自动注入该节点首轮 prompt |
+| `sandboxMode` | `read-only` \| `workspace-write` \| `danger-full-access` | — | 缺省 `danger-full-access`；DSH 可在 YAML 中覆盖 |
+| `approvalPolicy` | `never` \| `on-request` \| `on-failure` \| `untrusted` | — | 缺省 `never`（原型非交互） |
+| `reasoningEffort` | `minimal` \| `low` \| `medium` \| `high` | — | 缺省 `medium` |
+| `timeoutS` | int 30–7200 | — | 单节点超时，缺省 600 |
+| `onFailure` | `fail` \| `continue` | — | `fail`（缺省）：下游阻塞；`continue`：下游照常调度 |
+
+## nodePatch 事务语义
+
+- `nodes` 按 `id` 匹配：不存在则**新增**；存在且未开始则**覆盖传入的可编辑字段**
+  （title/prompt/model/cwd/dependsOn/sandboxMode/approvalPolicy/reasoningEffort/timeoutS/onFailure）。
+- `remove` 真正移除节点；被保留节点仍引用它时，必须在同一补丁中修改 `dependsOn` 完成重连。
+- 只有 `pending` / `blocked` / `queued` 节点可修改或删除；`running`、有活动对话的节点以及
+  `completed` / `failed` / `cancelled` 节点不可变。
+- 整个补丁以最终 DAG 为单位校验：目标状态、悬空依赖、自依赖或环任一失败，整包不提交。
+- 删除会写入 append-only 日志墓碑，进程重启后不会复活。
+
+```yaml
+apiVersion: codex.dsh/v1
+kind: nodePatch
+workflowId: wf_abc123
+title: 调整后的工作流
+remove: [old-review]
+nodes:
+  - id: publish
+    dependsOn: [build] # 局部更新：既有节点不必重复 prompt
+  - id: smoke-test
+    prompt: 执行冒烟测试
+    dependsOn: [build]
+```
+
+## 查询语义
+
+```yaml
+# 查询单个工作流完整快照
+apiVersion: codex.dsh/v1
+kind: workflowQuery
+workflowId: wf_abc123
+```
+
+省略 `workflowId` 时返回工作流清单。查询不会初始化 Codex SDK，也不要求启动新任务。
+
+## 示例
+
+见 `workflow.example.yaml`。规范真源：`workflow.schema.json`（JSON Schema 2020-12）。
+
+## 回传契约（tool 返回）
+
+```json
+{
+  "workflowId": "wf_abc123",
+  "created": ["verify", "build"],
+  "updated": [],
+  "deleted": [],
+  "rejected": [],
+  "nodes": [{ "id": "verify", "status": "queued", "dependsOn": [], "model": "gpt-5.6-sol" }],
+  "defaultModel": "gpt-5.6-sol",
+  "auth": { "mode": "chatgpt-subscription", "authFile": "/Users/me/.codex/auth.json", "present": true },
+  "progress": "/codex-orchestrate/api/state?workflowId=wf_abc123"
+}
+```
+
+进度查询返回各节点状态 + codex session 内 item 快照（形状对齐
+`@openai/codex-sdk` 的 ThreadItem 聚合语义：`item.updated` 为全量快照覆盖）。
+
+## 认证（模型请求为什么会生效 / 不生效）
+
+节点由**本机 codex**执行，认证完全复用 codex 自己的登录态（`~/.codex/auth.json`，
+可用 `CODEX_HOME` 改位置），插件不代管、不刷新、不转发任何 token；
+
+- **ChatGPT 订阅登录**：终端执行 `codex login`（官方 OAuth 流程）写入订阅 token，
+  之后无需 API key；SDK 原样使用该登录态。此路径下 `gpt-5-codex` 不被服务端接受，
+  用订阅可用的 slug（缺省 `gpt-5.6-sol`）。
+- **API key 登录**：设置 `OPENAI_API_KEY`（或 `codex login --api-key`）。
+- 两种登录态都没有时，`createRunner()` 会在派发前直接报错，不会烧掉一个必然失败的 turn。
+- 只读探测结果见 `GET /codex-orchestrate/api/status`（`defaultModel` + `auth.mode`），
+  以及 tool 返回里的 `defaultModel` / `auth` 字段。

package/scripts/verify-edge-routing.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/* 几何自证：证明 workflow DAG 的所有连线都不会覆盖任何一张节点卡片。
+ *
+ * 做法：用 esbuild 把 client/components/WorkflowRail.jsx 转成 CJS（react 置为 external），
+ * 直接调用其中真实的 layoutWorkflow，拿到每条边的路径；再把每条路径按 M/H/V/Q 密集采样，
+ * 逐点与所有卡片矩形做命中判定。
+ *
+ *   node scripts/verify-edge-routing.mjs
+ *
+ * 退出码 0 = 全部通过；1 = 存在压线。
+ */
+import { build } from 'esbuild'
+import { createRequire } from 'node:module'
+import { rmSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+
+/* ---------------- 取真实实现 ---------------- */
+/* 产物必须落在仓库内：这样 bundle 里的 require('react') 才能从本包 node_modules 解析到 */
+const outfile = join(root, '.rail-geom.cjs')
+rmSync(outfile, { force: true })
+await build({
+  entryPoints: [join(root, 'client/components/WorkflowRail.jsx')],
+  outfile,
+  bundle: true,
+  format: 'cjs',
+  platform: 'node',
+  target: ['node20'],
+  external: ['react'],
+  jsx: 'automatic',
+  logLevel: 'error',
+})
+const require_ = createRequire(import.meta.url)
+const { layoutWorkflow } = require_(outfile)
+
+/* ---------------- 路径采样 ---------------- */
+/* 只支持本组件实际会生成的命令：M / H / V / Q。出现别的命令直接报错，
+   避免"采样器不认识所以跳过"这种假通过。 */
+function samplePath(d, step = 0.4) {
+  /* 组件生成的路径里命令字母与数字是相连的（如 "M190 88"），
+     所以按「命令字母」或「数字」逐个切，而不是只按空白切。 */
+  const tokens = d.match(/[MHQV]|-?\d*\.?\d+/g) || []
+  const points = []
+  let x = 0
+  let y = 0
+  let i = 0
+  while (i < tokens.length) {
+    const command = tokens[i++]
+    if (command === 'M') {
+      x = Number(tokens[i++]); y = Number(tokens[i++])
+      points.push([x, y])
+    } else if (command === 'H') {
+      const nx = Number(tokens[i++]); emitLine(points, x, y, nx, y, step); x = nx
+    } else if (command === 'V') {
+      const ny = Number(tokens[i++]); emitLine(points, x, y, x, ny, step); y = ny
+    } else if (command === 'Q') {
+      const qx = Number(tokens[i++]); const qy = Number(tokens[i++])
+      const nx = Number(tokens[i++]); const ny = Number(tokens[i++])
+      const segments = 48
+      for (let k = 0; k <= segments; k++) {
+        const u = k / segments
+        const v = 1 - u
+        points.push([
+          v * v * x + 2 * v * u * qx + u * u * nx,
+          v * v * y + 2 * v * u * qy + u * u * ny,
+        ])
+      }
+      x = nx; y = ny
+    } else {
+      throw new Error(`采样器不认识路径命令 "${command}"（path=${d}）`)
+    }
+  }
+  return points
+}
+
+function emitLine(points, x0, y0, x1, y1, step) {
+  const length = Math.hypot(x1 - x0, y1 - y0)
+  const count = Math.max(1, Math.ceil(length / step))
+  for (let k = 1; k <= count; k++) {
+    points.push([x0 + (x1 - x0) * k / count, y0 + (y1 - y0) * k / count])
+  }
+}
+
+/* ---------------- 判定 ---------------- */
+const INSET = 1              /* 允许贴边（箭头必须停在卡片左边框上），但不允许真正进入卡片内部 */
+const STROKE_HALF = 2        /* 最宽的描边是 3.2px 流动虚线，半宽 1.6px */
+
+function cardRects(layout) {
+  return [...layout.positions.entries()].map(([id, p]) => ({
+    id, x: p.x, y: p.y, w: p.width, h: p.height,
+  }))
+}
+
+function verify(name, nodes) {
+  const layout = layoutWorkflow(nodes)
+  const rects = cardRects(layout)
+  const failures = []
+  const tight = []
+  let sampled = 0
+  let bodyClearance = Infinity
+
+  for (const edge of layout.edges) {
+    const points = samplePath(edge.d)
+    sampled += points.length
+    /* 形状判据（硬约束之外的"不难看"约束）：
+       本组件所有走线都是「右出 → 最多一次竖直转折 → 左进」，
+       所以 x 必须单调不减、y 的方向变化不得超过 1 次。
+       历史 bug：通道方向符号写反时会出现"越过目标再折返"——
+       折返段落在列空隙里，不压卡片，几何判据抓不到，但肉眼一看就是错的。 */
+    for (let i = 1; i < points.length; i++) {
+      if (points[i][0] < points[i - 1][0] - 0.01) {
+        failures.push(`${edge.key}: 第 ${i} 段 x 回退（${points[i - 1][0].toFixed(1)} → ${points[i][0].toFixed(1)}）`)
+        break
+      }
+    }
+    let previousDirection = 0
+    let reversals = 0
+    for (let i = 1; i < points.length; i++) {
+      const delta = points[i][1] - points[i - 1][1]
+      if (Math.abs(delta) < 0.01) continue
+      const direction = delta > 0 ? 1 : -1
+      if (previousDirection !== 0 && direction !== previousDirection) reversals += 1
+      previousDirection = direction
+    }
+    if (reversals > 1) {
+      failures.push(`${edge.key}: y 方向折返 ${reversals} 次（>1，线在通道处越过目标又折回）`)
+    }
+    /* 硬判据：任何采样点都不得进入任何卡片内部（含本条边自己的两端）。
+       间距指标只对「非本条边两端」的卡片计算——线本来就要贴到自己的
+       源/目标卡片边框上，把它们算进来指标会退化成排除阈值，自我满足。 */
+    for (const [px, py] of points) {
+      for (const r of rects) {
+        const insideX = px > r.x + INSET && px < r.x + r.w - INSET
+        const insideY = py > r.y + INSET && py < r.y + r.h - INSET
+        if (insideX && insideY) {
+          failures.push(`${edge.key}: (${px.toFixed(1)}, ${py.toFixed(1)}) 落在卡片 [${r.x},${r.y} ${r.w}x${r.h}] 内部`)
+        }
+        if (r.id === edge.sourceId || r.id === edge.targetId) continue
+        const dx = Math.max(r.x - px, 0, px - (r.x + r.w))
+        const dy = Math.max(r.y - py, 0, py - (r.y + r.h))
+        const clearance = Math.hypot(dx, dy)
+        if (clearance < bodyClearance) bodyClearance = clearance
+        if (clearance < STROKE_HALF) {
+          tight.push(`${edge.key}: (${px.toFixed(1)}, ${py.toFixed(1)}) 距「其它」卡片仅 ${clearance.toFixed(1)}px（线宽包络 ${STROKE_HALF}px）`)
+        }
+      }
+    }
+  }
+
+  const ok = failures.length === 0 && tight.length === 0
+  console.log(
+    `${ok ? '✓' : '✗'} ${name}\n` +
+    `    节点 ${nodes.length}  边 ${layout.edges.length}  行间通道 ${layout.channelCount}  图高 ${layout.height}px  采样点 ${sampled}` +
+    `${Number.isFinite(bodyClearance) ? `  中段最小间距 ${bodyClearance.toFixed(1)}px` : ''}`,
+  )
+  for (const failure of [...failures, ...tight].slice(0, 6)) console.log(`      ! ${failure}`)
+  const extra = failures.length + tight.length - 6
+  if (extra > 0) console.log(`      … 另有 ${extra} 处`)
+  return ok
+}
+
+/* ---------------- 用例 ---------------- */
+const node = (id, dependsOn = [], status = 'completed') => ({
+  id, title: id, prompt: '', status, dependsOn,
+})
+
+/* 真实跑过的工作流 wf_0f3d1ebb：host-contract→port-ui 是跨 2 列的长边 */
+const realOne = [
+  node('host-contract'),
+  node('workbench-inventory'),
+  node('scaffold', ['host-contract']),
+  node('port-ui', ['host-contract', 'workbench-inventory', 'scaffold']),
+  node('verify', ['scaffold', 'port-ui']),
+]
+
+/* 真实跑过的工作流 wf_4254276f */
+const realTwo = [
+  node('shanghai-weather'),
+  node('beijing-weather'),
+  node('typhoon-china'),
+  node('report', ['shanghai-weather', 'beijing-weather', 'typhoon-china']),
+]
+
+/* 压力用例：6 列 x 3 行，大量跨列长边 */
+const stress = [
+  node('a'), node('b'), node('c'),
+  node('d', ['a']), node('e', ['b']), node('f', ['c']),
+  node('g', ['a', 'd']), node('h', ['b', 'e']), node('i', ['c', 'f']),
+  node('j', ['a', 'g']), node('k', ['b', 'h']), node('l', ['c', 'i']),
+  node('m', ['a', 'j']), node('n', ['b', 'k']), node('o', ['c', 'l']),
+  node('p', ['a', 'm']), node('q', ['b', 'n']), node('r', ['c', 'o']),
+]
+
+const cases = [
+  ['真实工作流 wf_0f3d1ebb（含跨 2 列长边）', realOne],
+  ['真实工作流 wf_4254276f（三路汇合）', realTwo],
+  ['单节点（无边）', [node('solo')]],
+  ['相邻两列同排（短边退化直线）', [node('a'), node('b', ['a'])]],
+  ['相邻两列错排（短边 S 形）', [node('a'), node('b'), node('c', ['a'])]],
+  ['压力用例（6 列 x 3 行，大量长边）', stress],
+]
+
+let allOk = true
+for (const [name, nodes] of cases) allOk = verify(name, nodes) && allOk
+
+rmSync(outfile, { force: true })
+
+console.log(allOk
+  ? '\n全部通过：所有连线均未覆盖任何节点卡片。'
+  : '\n存在压线，见上方明细。')
+process.exit(allOk ? 0 : 1)

package/server/codex-runner.js

@@ -0,0 +1,129 @@
+/* ============================================================
+ * codex-runner.js — codex 执行适配器（真实链路）
+ * - @openai/codex-sdk（Codex → startThread → runStreamed）
+ *   ThreadItem 快照直接透传（reasoning / command_execution / file_change /
+ *   agent_message / error / mcp_tool_call / web_search / todo_list）
+ * - 认证：完全复用本机 codex 登录态（~/.codex/auth.json）。订阅登录由
+ *   `codex login` 走官方 OAuth 写入，SDK 原样使用；这里只做只读探测，
+ *   不代管 token、不刷新、不转发。
+ * - 缺省模型来自 defaults.js（gpt-5.6-sol）；订阅登录下服务端拒绝的
+ *   slug 会翻译成可操作的报错，而不是让节点静默 failed。
+ * ============================================================ */
+'use strict';
+
+const { DEFAULT_MODEL, authState, authGuidance } = require('./defaults.js');
+const { createTurnState, reduceEvent, finalizeTurn } = require('./turn-reduce.js');
+const { join, dirname } = require('node:path');
+const { existsSync } = require('node:fs');
+
+/** 把 codex 的原始报错翻译成「下一步做什么」。 */
+function explainFailure(message, model) {
+  const text = String(message || '');
+  if (/not supported when using Codex with a ChatGPT account/i.test(text)) {
+    return `${text}\n模型 "${model}" 与当前 ChatGPT 订阅登录不兼容；`
+      + `改用订阅可用的 slug（缺省 ${DEFAULT_MODEL}），或改用 API key 登录（OPENAI_API_KEY）。`;
+  }
+  if (/\b401\b|unauthorized|invalid_grant|token.*expired/i.test(text)) {
+    return `${text}\ncodex 登录态可能已失效：重新执行 \`codex login\`。`;
+  }
+  return text;
+}
+
+/* 从本文件所在目录逐层上溯，找第一个含 @openai/codex-sdk 的 node_modules。
+ * 不能写死 <插件>/node_modules/…：安装进 DSH profile 后依赖会被 pnpm hoisted
+ * 提升到 profile 根，插件目录下的 node_modules 并不存在，写死就会「装完即坏」。
+ * 包是 ESM-only（exports 只有 import 条件），require.resolve 用不上，所以按已知入口探测。 */
+function findCodexSdk() {
+  const tail = ['@openai', 'codex-sdk', 'dist', 'index.js'];
+  const roots = [];
+  if (process.env.DSH_CODEX_MODULES) roots.push(process.env.DSH_CODEX_MODULES);
+  let dir = __dirname;
+  for (;;) {
+    roots.push(dir);
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const root of roots) {
+    /* 两种布局都要覆盖：
+     *   root 是普通目录   → 包在 <root>/node_modules/…
+     *   root 本身是 node_modules（上溯途中会路过它）→ 包直接在 <root>/… */
+    for (const base of [join(root, 'node_modules'), root]) {
+      const candidate = join(base, ...tail);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+async function createRunner() {
+  const { pathToFileURL } = await import('node:url');
+  const sdkPath = findCodexSdk();
+  if (!sdkPath) {
+    throw new Error('未找到 @openai/codex-sdk：请先安装本插件依赖，或设置 DSH_CODEX_MODULES 指向含该包的 node_modules');
+  }
+  const sdk = await import(pathToFileURL(sdkPath).href);
+  const { Codex } = sdk;
+
+  /* 优先使用 SDK 自带 CLI 二进制；平台包缺失时回退本机 codex CLI（codexPathOverride） */
+  let codex;
+  try {
+    codex = new Codex();
+  } catch {
+    const { access, constants } = await import('node:fs/promises');
+    const localCli = process.env.DSH_CODEX_CLI || '/opt/homebrew/bin/codex';
+    try { await access(localCli, constants.X_OK); } catch {
+      throw new Error('SDK 平台二进制不可用，且未找到可执行的本机 codex CLI（可设置 DSH_CODEX_CLI）');
+    }
+    codex = new Codex({ codexPathOverride: localCli });
+  }
+  /* 派发前预检登录态：没有登录态就不必烧一个必然失败的 turn */
+  const guidance = authGuidance();
+  if (guidance) throw new Error(guidance);
+
+  return {
+    mode: 'real',
+    defaultModel: DEFAULT_MODEL,
+    auth: authState(),
+    async run(def, callbacks, signal, { sessionId = null, prompt = def.prompt } = {}) {
+      const model = def.model || DEFAULT_MODEL;
+      const threadOptions = {
+        model,
+        workingDirectory: def.cwd,
+        sandboxMode: def.sandboxMode,
+        approvalPolicy: def.approvalPolicy,
+        modelReasoningEffort: def.reasoningEffort,
+        skipGitRepoCheck: true,
+      };
+      const thread = sessionId
+        ? codex.resumeThread(sessionId, threadOptions)
+        : codex.startThread(threadOptions);
+      /* 新 thread 的 id 只有 thread.started 之后才存在；resume 的 id 已知。 */
+      if (sessionId) callbacks.onSessionId(sessionId);
+      /* 终局判定在 turn-reduce.js（纯函数，可单测）：已自愈的传输恢复不算失败 */
+      let state = createTurnState();
+      let errorSeq = 0;
+      try {
+        const { events } = await thread.runStreamed(prompt, { signal });
+        for await (const event of events) {
+          if (process.env.DSH_CODEX_DEBUG_EVENTS) {
+            console.error('[codex-event]', JSON.stringify({ type: event.type, item: event.item?.type || null }));
+          }
+          if (event.type === 'thread.started' && event.thread_id) callbacks.onSessionId(event.thread_id);
+          state = reduceEvent(state, event, message => explainFailure(message, model));
+          if ((event.type === 'turn.failed' || event.type === 'error') && state.turnError) {
+            callbacks.onItem({ type: 'error', id: `item_error_${++errorSeq}`, message: state.turnError });
+          } else if (event.item) {
+            callbacks.onItem({ ...event.item, live: event.type !== 'item.completed' });
+          }
+        }
+      } catch (error) {
+        if (signal?.aborted) return { status: 'cancelled', finalMessage: null, usage: null };
+        throw error;
+      }
+      return finalizeTurn(state);
+    },
+  };
+}
+
+module.exports = { createRunner, explainFailure };