前言¶

DeepSeek Harness（DSH）里的 Agent 通常只在本会话工作区内行动。若你同时在用 OpenAI Codex（桌面版或 CLI），线程、goal、转录和写者锁都在本机 CODEX_HOME 里，DSH 默认碰不到这些数据，也无法把任务无头投递进某个 Codex 线程。

已有做法往往是人工切换 Codex 桌面版、自己翻 rollout，或在脚本里裸调 codex exec。dsh-codex-bridge 是维护者 Dax233 发布的工作流类插件（社区目录分类：工作流），把「列线程、读尾部对话、派发 turn、走官方 queue、查 run、读 goal、做活性快照」收成一组 DSH 工具，经 Harness 的 subprocess seam 驱动本机 Codex CLI，且不写 CODEX_HOME。

这是什么¶

插件包名 @local/dsh-codex-bridge，当前版本 0.2.3（见仓库 package.json），许可证 MIT。一句话：Codex bridge for DeepSeek Harness——列出本机 Codex 线程，无头派发 turn，读取转录，监控 goal 状态与活性（liveness）。

前提：本机已安装 Codex（桌面版自带 CLI 或 npm i -g @openai/codex），并已登录（CODEX_HOME 下的 auth.json）。Node 引擎要求 >=22。

核心功能¶

下面按 README 中的工具表说明能力边界。

看与读¶

• codex_threads：线程清单，支持 query、limit、activeWithinMinutes。
• codex_read：读某线程最近条目，参数含 thread、limit、kinds、maxChars、tailBytes；有界读尾部，避免加载数百 MB 的 rollout。默认 kinds 含 developer；若只看对话，传 kinds: ['user', 'assistant', 'turn-end']。

派与查¶

• codex_send：向指定线程投递消息，或省略 thread 开新线程；可选 waitMs、cwd、model、approvalPolicy、sandboxMode。默认立刻返回 runId，长任务用 codex_run 轮询，不阻塞 DSH 对话。
• codex_queue：当线程被其他写者占用（例如 Codex 桌面版持有 writer，codex_send 因 active writer 被拒）时，走官方 codex queue 通道；可选 waitMs，在本地 rollout 里观察该 turn 完成后返回最终消息。
• codex_run：无 runId 时列表；有则查看派发 turn 的状态与最终消息。

goal 与活性¶

• codex_goals：读官方 goal 行，参数 thread、status、limit。
• codex_liveness：活性快照，参数 threads、idleMs、nudge。默认 allowNudge: false；仅在配置 allowNudge: true 时，codex_liveness({ nudge: true }) 才会真向线程补发「继续」类消息。不会代做 blocked goal 恢复，也不会对 paused goal 发 nudge。

插件对 Codex home 只读（转录、goal 数据库、写者锁、automation 等）；驱动每次 codex exec / codex exec resume 起一个子进程，凭据类环境变量不继承。无头执行默认 approval_policy=never。同一线程若已有本插件进行中的 turn，codex_send 会拒绝第二个写者。

配置要点¶

插件不内置本机路径。Codex home 依次取 config.codexHome → CODEX_HOME → ~/.codex；可执行文件依次取 config.executable → CODEX_BIN → 桌面版 CLI 标准位置 → PATH → 常见包管理器目录。

在 profile 的 cordis.patch.yml 里覆盖 codex-bridge 行时，config 是整块替换，需写全需要的字段。示例（摘自 README）：

- id: codex-bridge
  name: '@local/dsh-codex-bridge'
  config:
    codexHome: ''
    executable: ''
    defaultCwd: ''
    approvalPolicy: never
    sandboxMode: ''
    defaultWaitMs: 0
    queueTimeoutMs: 30000
    queuePollMs: 1200
    disposeGraceMs: 5000
    allowNudge: false
    liveness:
      idleMs: 1800000
      lockFreshMs: 120000
      threads: []
    env: {}

codex_send 省略 cwd 时，新线程用 config.defaultCwd，否则退化为调用它的 DSH 会话工作区；resume 优先用线程自己的 cwd。README 注明当前主要在 Windows 上实测；其他平台依赖 PATH 中的 CLI。goal 读取依赖 node:sqlite，缺失时 goal 相关能力会优雅降级，其余工具不受影响。

安装与启用¶

README 给出的安装方式如下，不要用未在资料中出现的 dsh plugin add github:... 拼接命令。

# 本仓库目录安装为当前 profile 的 bundle

在 DSH 中用插件管理器安装本目录（绝对路径），或在 profile 的 package.json 里通过 link: 加入 dsh.profile.bundles。

本地开发可先做语法检查：

node --check index.js
node --check lib/catalog.mjs

验证：

npm test        # 78 个离线测试
npm run smoke   # 只读冒烟，需要本机 Codex home

典型用法¶

工具调用顺序¶

1、用 codex_threads 找到目标线程名或 ID。
2、用 codex_read 看最近上下文（按需收窄 kinds）。
3、用 codex_send 投递任务；若遇 active writer，改用 codex_queue。
4、用 codex_run 轮询 runId 直到有最终消息。
5、需要盯 goal 或是否停滞时，用 codex_goals 与 codex_liveness。

监控与定时介入（watch）¶

插件本身没有后台定时器，也不会唤醒 DSH 会话。若要在「异常时才介入」，README 建议两层：DSH 的 schedule_create 定时把 prompt 投回本会话；配合仓库内 node scripts/watch.mjs --json 读 ${CODEX_HOME} 只输出告警（退出码 0 无告警，10 有告警，2 检查失败）。脚本必须提供 thread（--thread 或 watch.config.json），否则退出码 2。

唤醒层示例（在 relay 会话里创建，约每 30 分钟一轮）：

schedule_create prompt = "运行 node <本仓库>/scripts/watch.mjs --json。
退出码 0 就静默结束；退出码 10 时用一句话汇报告警 code 与 thread，其它不要做。"

适用场景与注意¶

适合：已在 DSH 里编排 Agent，又需要统一查看本机 Codex 线程、无头投递任务、读转录尾部、配合 goal/liveness 做工作流衔接的开发者。

务必注意：插件以当前 DSH 进程权限运行，子进程环境按白名单透传；安装前应阅读源码与 MIT 许可证，确认 CODEX_HOME 只读边界与无头审批策略符合你的安全要求。运行中的 turn 不能通过工具取消；无流式，长任务请 waitMs: 0 + codex_run。社区目录站点与 DeepSeek / 幻方无官方从属关系，本文仅介绍社区插件本身。

结尾¶

dsh-codex-bridge 把本机 Codex 的线程视图、有界读转录、派发与 queue、run 查询、goal 与 liveness 接到 DSH 工具面，便于在同一 Harness 会话里编排 Codex 与 DSH Agent。目录页：https://www.skillhub.cn/plugins/Dax233/dsh-codex-bridge；源码与完整行为边界：https://github.com/Dax233/dsh-codex-bridge。