@bitqyh/dsh-codex-bridge

dsh plugin --profile web add @bitqyh/dsh-codex-bridge

@bitqyh/dsh-codex-bridge

Codex ↔ DSH 跨 agent 接力：会话采集、自动存档、中断恢复提示。

一个包，一条命令安装。

只想用中断恢复？ 直接在项目目录跑

dsh-codex-bridge resume --from-agent codex 即可，不需要注册插件、

装 profile 或重启 DSH。

下面「安装」段落装的是事件插件（会话采集/自动存档/中断提示），

那套需要注册与重启；它不是使用 resume 的前置条件。

安装

dsh plugin --profile desktop add @bitqyh/dsh-codex-bridge

然后跑安装命令（不会自动改文件，见下方说明）：

npx @bitqyh/dsh-codex-bridge doctor          # 先只读检查
npx @bitqyh/dsh-codex-bridge setup           # 看计划（不写文件）
npx @bitqyh/dsh-codex-bridge setup --yes     # 真正安装 DSH 侧
npx @bitqyh/dsh-codex-bridge setup-codex --yes   # 安装 Codex 侧

本包的 cordis.patch.yml 已自带 UI 入口（「交接」按钮），dsh plugin add

装完重启 DSH 即可使用，不需要再手动改 profile patch。

只有想额外启用事件扫描插件（中断提示）时才需要下面这一步。

最后（可选，仅事件插件）：

1. 在 ~/.dsh/profiles/desktop/cordis.patch.yml 加：

- insert:
    - id: dsh-codex-bridge-events
      name: '@bitqyh/dsh-codex-bridge'

2. 重启 DSH

3. Codex 里 /hooks 重新信任（改了命令哈希会失效，且静默跳过）

为什么不用 postinstall 自动装

两个原因，都实测过：

1. 技术上跑不起来。 DSH profile 用 pnpm 11，pnpm-workspace.yaml 的

allowBuilds 白名单会拦掉未批准的安装脚本：

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: ...

本机白名单只有 cloudflared，所以 postinstall 根本不会执行。

2. 产品上不该这么做。 安装要往

~/Library/Application Support/ai-memory/hooks/dsh/ 写 13 个文件

（7 个 hook 脚本 + 6 个工具脚本）、覆盖 hooks.json——都在项目目录之外。

装一个 npm 包不预期会改这些。

所以改成显式命令：默认只打印计划，加 --yes 才执行，且改任何文件前先备份。

命令

命令 · 作用

dsh-codex-bridge resume · 构建中断会话的恢复上下文（只读）

dsh-codex-bridge doctor · 只读检查两侧状态

dsh-codex-bridge setup · 安装 DSH 侧（先看计划）

dsh-codex-bridge setup --yes · 真正执行

dsh-codex-bridge setup-codex · 安装 Codex 侧（合并，保留原有其他事件）

dsh-codex-bridge paths · 打印所有相关路径

选项：--server=<url> 覆盖 ai-memory 地址（默认 http://127.0.0.1:49374）。

接续已有聊天

没有「已完成的任务」——只有「本轮已收尾」和「因故中断」，后续都还会有新需求。

所以接续既用于中断恢复，也用于上一轮正常结束之后的后续需求。

三种入口，按顺手程度选：

1. DSH 界面按钮：点输入框下方的「交接」→ 按聊天名称选 → 看预览 →

点「插入当前对话」，内容进草稿，自己确认后再发送。

列表按具体项目分组（组名就是项目名），未归属的合成「非项目会话」放最后；

组顺序按组内最新会话时间倒序。搜索作用于全部会话，展开后行数只增不减。

分组依据与它的边界见下面「项目归属」一节。

只插入草稿，绝不自动发送。 按钮只调 insertText，不碰 setDraft/paste/submit。

2. Codex skill：说「用接续任务接着 DSH 没做完的任务」，或 $resume-task。

3. 命令行（备用入口）：

在同一项目目录运行 dsh-codex-bridge resume --from-agent codex，先核验现场，再继续。

反向（从 DSH 切到 Codex）把参数改成 --from-agent dsh。

候选里每个聊天带一个本轮标识：本轮已收尾 / 因故中断 / 未收尾/需核验。

它说的是这一轮怎么结束的，不是任务完成度。徽标是可接续聊天数。

# 备用 agent 在项目目录里跑；只读，不写 handoff/DB，不调用模型
dsh-codex-bridge resume --from-agent codex

# 两边工作目录不一致时，显式给路径
dsh-codex-bridge resume --from-agent codex --cwd '<实际项目路径>'

# 只有出现多个可接续来源时才需要指定（必须完整 native id，不猜 latest）
dsh-codex-bridge resume --from-agent codex --session <完整native-id>

输出是一份机械提取的恢复上下文：定位信息、任务目标（人类原话）、已确认成功

的操作、失败/未知/待审批、最后一条助手可见输出、接续前必须先核验的清单。

它是证据，不是新授权。 备用 agent 按你当前的指令继续任务时，用的是它自己的

模型和工具；resume 本身只读日志。

退出码：0 ready、2 no-candidate、3 needs-selection、4 incomplete。

incomplete 表示信息不足（缺目标、未知 scope、片段无法排序），不要当通过。

它提供什么

能力 · 说明

会话采集 · prompt、工具调用、轮次边界，上报 ai-memory

自动存档 · 每轮结束刷新可恢复快照（零 token）

中断检测 · 限速扫描磁盘日志，发现额度中断/崩溃的会话并注入提示

手动恢复 · resume 只读解析原生日志，构建中断会话的恢复上下文；可离线、无 DB 降级，不依赖服务运行

「交接」按钮 · 输入框下方按具体项目分组列出可接续的 Codex 聊天，只把恢复内容插入草稿

和已有插件的区别

市场里已有一批「把外部会话带进 DSH」的插件。本插件的定位是

不导入、不切换上下文、不写回——只把会话列清楚，并诚实标注归属判断有多可靠。

与 dsh-codex-history（平铺列表 + 导入）、dsh-assembly.resume（按路径末段命名分组 +

导入会话）、dsh-takeover（新建会话接管）、task-passport（任务状态搬运）的逐条对比

见 [COMPARISON.md](./COMPARISON.md)。

开发与发布

改了代码要发新版本时，完整流程（含 npm scope 组织、token 类型、202 异步落地、

市场 PR 的几个坑）见 [RELEASE.md](./RELEASE.md)。

npm install     # 首次：装 peer 依赖
npm test        # 201 项
npm pack --dry-run   # 发版前看清单

前置条件

运行时依赖一览

这个包不是「一条命令装完就什么都不用管」。 它复用你机器上已有的 python3

读原生日志，装之前先对一下表：

依赖 · 谁需要 · 缺了会怎样

Node.js ≥ 20 · 全部 · 插件不加载

python3 ≥ 3.8 · 「交接」列表、resume、doctor · 列表静默为空，前端显示「读取失败」；CLI 无输出

zstd · 只读 DSH 侧会话时需要 · DSH 侧会话全部读不出，逐个进「已跳过」；Codex 侧不受影响

ai-memory 服务 · 采集 / 自动存档 / 中断提示 · 「交接」列表和 resume 仍可用（它们不依赖服务）

Codex（CLI 或 Desktop） · 读 Codex 会话 · Codex 侧没有可接续聊天

自检：

node -v          # ≥ 20
python3 -V       # ≥ 3.8（只用标准库，不需要 pip 装任何东西）
command -v zstd  # 只读 DSH 侧才需要

python3 只用到标准库（json/sqlite3/subprocess/pathlib 等），

不需要 pip / requirements.txt。已实测 macOS 自带的 /usr/bin/python3（3.9）

可用；5 个工具脚本在 3.9 下全部编译通过。

🪟 Windows 暂未适配。 代码里直接 spawnSync("python3", ...)，而 Windows

上通常只有 python 或 py，没有 python3。没有做 process.platform 分支，

所以 Windows 上「交接」列表会是空的。装之前请确认 python3 在 PATH 里，

否则等后续版本。

⚠️ python3 是硬依赖，而且缺了不会报错。 实测：PATH 里没有 python3 时

CLI 退出码 1、stdout 为空、stderr 也为空，界面只说「读取失败」。

如果你装完发现「交接」列表一直是空的，先 command -v python3。

按你要用的能力分

① 采集 / 自动存档 / 普通 handoff — 需要已安装并运行 ai-memory 服务

（本包不包含）：

launchctl list | grep ai-memory
curl -s http://127.0.0.1:49374/healthz   # → {"status":"ok"}

没装见 https://github.com/akitaonrails/ai-memory

② resume 手动恢复 — 不需要服务运行：

• 直接读本机原生日志（Codex ~/.codex/sessions、DSH sessions 目录）。
• 没有 ai-memory 数据库也能用：正文全部由原生日志构建，恢复内容一个字节都不少。
• 只读 DSH 侧会话时需要 zstd（DSH 日志是 session.v4.jsonl.zstd）。

没有 zstd 时 DSH 侧会话会全部读不出并逐个进「已跳过」统计，Codex 侧不受影响

——因为 Codex 日志是未压缩的 .jsonl。

• 有 DB 时会多做三项一致性核对（这是 DB 唯一的作用，它不是恢复内容的来源）：

1. 日志末尾 vs 钩子最后上报 → 钩子是否在丢事件

2. 日志末尾 vs 存档时间 → 存档是否落后于真实进度（超过 90 秒即报，

额度中断/崩溃时最容易出现）

3. 会话是否在 DB 登记、agent kind 是否一致

缺 DB 时这三项跳过，正文开头标一行「缺 DB 校验」。

• 注意 ended_at 不参与进度新旧判断：它是「钩子捕获到结束的时刻」，

与日志末尾实测可差 ±16 小时且方向不定。

配置

{
  scriptPath: "",         // 留空自动解析（已安装位置 → 包内自带）
  throttleSeconds: 600,   // 扫描限速窗口
  sinceHours: 24,         // 只看最近 N 小时有活动的会话
  maxReported: 3,         // 最多提示几条
  enabled: true,
}

设计要点

为什么挂 UserPromptSubmit 而不是 SessionStart

常驻会话不会重新触发 SessionStart。实测一个长期会话：

钩子 · 触发次数

PreToolUse / PostToolUse · 821 / 821

UserPromptSubmit · 63

SessionStart · 0

用户日常把 agent 挂后台，挂 `Se

…(truncated)