伴航 zoe1nan/dsh-convoy

伴航 Convoy

伴航 Convoy 封面

▶ 60 秒演示视频 · 三场景 + 实时监督 + 设置页 + 回执面板 + 复盘，全程零点击。

for DeepSeek Harness · 给每个 AI 会话配一个不干活的「找茬同事」——它不抢活干，只在 agent 快要犯错时直接出手收掉，然后留一张回执。

状态：v0.5.0 · M1 达成（2026-10-22）：T1.1–T1.7 全部完成，真机四轮复验零误报；L2 模型复核已接入宿主 llm 服务（路由跟随会话，可开关）；npm test 99/99、npm run replay 3/3。
日期：2026-10-22 · zoe1 / 小蓝鲸

这是什么

DSH 插件方向：AI 监督 AI。

现有 doctor/guard 类插件管的是「安装前检查、崩溃后修复」，teammate 管的是「分工干活」，没有人管运行过程中的语义级风险：危险命令、范围漂移、幻觉引用、假完成、验证缺失。

伴航旁路监听 DSH 会话事件，用「确定性规则 + 小模型 Reviewer」在关键节点判断，然后默认自动纠偏：安全改写命令、阻断高危操作、回滚范围外改动、补跑验证、循环降频、敏感信息脱敏。处理完只在界面上留一张回执——不弹确认、不等人点、不打断自动流程。

一句话差异：别人管「安装、启动、权限、事后」，伴航管「过程」；别人把用户叫回来，伴航直接把事办了。

目录

dsh-convoy/
├─ README.md # 本文件 ├─ package.json # DSH 插件清单（dsh.bundle.patch + dsh.client） ├─ cordis.patch.yml # bundle patch：把宿主半插入 composition ├─ index.js # 宿主半：/convoy/ 面板页 + /convoy/api/* 实时接口 + 监听 session/event ├─ client.js # 客户端半：右下角回执胶囊/面板 + 设置页 + 侧边栏 + 主面板 ├─ install.mjs / install.cmd # 安装/卸载脚本（全部可回滚） ├─ src/ │ ├─ events/ # 事件层：多帧 zstd 解码、归一化、JSONL/总线双事件源 │ ├─ rules/ # L1 规则：W1 破坏性 / W2 路径越界 / W3 范围漂移 / W5 假完成 │ ├─ score/ # 信任分 │ ├─ receipts/ # 回执存储 + 复盘 markdown │ ├─ reviewer/ # L2 Reviewer（schema / 预算 / 触发 / 降级 / live-model） │ ├─ actions/ # AutoActionExecutor（nudge / git 回滚 / 重跑验证 / 脱敏） │ ├─ host/ # 实时状态中枢 ConvoyHub + /convoy/api 路由 │ └─ pipeline.mjs # 回放/宿主共用的串联管线 ├─ scripts/ # replay 回放器、真机会话探针、夹具生成 ├─ fixtures/ # 三个真实形状事件流（删库 / 范围漂移 / 假完成） ├─ test/ # node:test（99 项） ├─ docs/ │ ├─ PRD.md # 产品需求（v0.5） │ ├─ 工作计划表.md # 23 项任务 / 里程碑 / 风险 │ ├─ M0-技术设计.md # 事件模型 / 规则接口 / 自动动作 / 存储 │ └─ T1.7-冒烟记录.md # 真机冒烟四轮记录（误报证据 + 修复后复验） ├─ out/reviews/ # 三场景复盘样张（s1/s2/s3） └─ demo/ └─ index.html # 单文件交互 Demo（浅色 · 无依赖 · 面板内打开）

安装 / 卸载（全部可回滚）

安装（本机已完成过一次，重装/换机器用）：

1. 双击 install.cmd（或在任意终端运行 node install.mjs）。脚本会：
- 备份 profile 的 package.json（package.json.bak-convoy-<时间戳>）
- 写入 "dsh-convoy": "link:<本目录绝对路径>" 与 dsh.profile.bundles 条目
- 用 DSH 自带 pnpm 安装并校验 node_modules/dsh-convoy
- 任一步失败自动还原 package.json / pnpm-lock.yaml，不会把 DSH 弄坏
2. 完全退出 DSH（托盘图标 → 退出），再重新启动。
3. 右下角出现回执胶囊；侧边栏出现「伴航 Convoy」面板；/convoy/ 由插件自己提供。

卸载 / 回滚：

node install.mjs --uninstall # 移除依赖与 bundles 条目，再跑一次 pnpm install
完全退出 DSH 再启动 → 胶囊、面板、路由全部消失

- 卸载同样先备份 package.json，失败会还原；重复执行是幂等的（输出 profile already up to date）。
- 应急手回滚：把最近的 package.json.bak-convoy-* 覆盖回 package.json，再 pnpm install。
- 演示（不落盘）：node install.mjs --dry-run / node install.mjs --uninstall --dry-run。

安装/卸载演练已做：在临时 profile 上 install → uninstall → 二次 uninstall 幂等 → 清理，全程未触碰真实 profile。本机注记见 docs/T1.7-冒烟记录.md。

实时版怎么用

右下角 伴航回执胶囊（蓝色小标 + 信任分 + 状态点）：

1. 不用点任何东西。正常和 DSH 对话，伴航在后台监听本机所有会话，命中 W1/W2/W3/W5 时自动生成回执并扣信任分。
2. 点胶囊展开面板：最近回执（哨点、原因、证据片段、自动动作）、会话数、红/黄计数、本轮状态；「下载复盘」导出当前会话 markdown。
3. 设置 → 伴航 Convoy：
- 自动纠偏（auto，默认） / 仅记录（record，观察期推荐） / 需要时提问（ask，M0 默认关）
- 自动动作计划开关（M0 只生成计划，不落盘执行）
- L2 状态（默认启用：复用 DSH 宿主 llm 服务，路由跟随会话 request/header；无服务/无路由时显式待命）
4. 数据只在本机：配置 ~/.dsh/convoy/config.json，回执按天追加 ~/.dsh/convoy/receipts/YYYY-MM-DD.jsonl，不上传任何会话内容。

接口（都过 GUI 登录校验，浏览器直连返回 401 属预期）：

| 路由 | 说明 |
| GET /convoy/api/health | 存活 + 版本 + mode:"live" + L2 状态（enabled / standby-no-route / no-llm-service） |
| POST /convoy/api/review/run | 立刻对指定会话跑一次 L2（调试/验证用） |
| GET /convoy/api/state | 会话、信任分、回执统计、模式 |
| GET /convoy/api/stream | SSE 推送，面板实时刷新用 |
| GET /convoy/api/receipts?session=<id>&limit= | 回执列表 |
| GET /convoy/api/review?session=<id>[&download=1] | 复盘 markdown |
| GET\|POST /convoy/api/config | 读取/修改监督模式与自动动作开关 |
| POST /convoy/api/undo | 撤销（M0 诚实返回 not-executed：只生成了计划，未真实执行） |

怎么看 Demo

入口：DSH 侧边栏「伴航 Convoy」（面板内 iframe）或浏览器直开 demo/index.html，内容一致。

1. 打开即见品牌区：DeepSeek 官方 logo + 伴航 Convoy + for DeepSeek Harness；浅色背景，主色 #4D6BFE。
2. 选场景 → 点「▶ 播放」，然后什么都不用点：
- A · 删库前 3 秒：Remove-Item -Recurse -Force $HOME 在执行前被改写成只删 ./tmp、./logs。
- B · 顺手改了支付模块：只让改设置页，agent 顺手改 src/payment.ts；伴航自动回滚该文件，保留设置页改动。
- C · 「测试全部通过」：测试仍 failed 却声称通过；伴航自动重跑测试、贴出真实结果、把结论退回。
3. 每个风险点出现一张内联回执：风险级别、命中哨点、可展开证据、「✓ 已自动处理 · 零点击」；会话在回执后自动继续。
4. 右侧面板实时看：信任分、自动纠偏 / 人工介入（0）/ 避免事故、处理流水；顶部切「自动纠偏 / 仅记录」做对照；结束可下载复盘 .md。

Demo 是纯前端模拟，不操作真实文件；它演示 M1 目标形态（执行前改写/阻断）。真实会话的监督结果看右下角胶囊——M0 自动动作只生成可撤销计划，不落盘执行（见 PRD 5.1）。

PRD 核心（详见 docs/PRD.md）

- 三层机制：看见（事件流旁听）→ 判断（L1 确定性规则 + L2 语义 Reviewer）→ 处理（默认自动动作；仅记录 / 询问为备选）
- 交互原则：工作流是自动跑的，监督也必须自动跑——零点击优先、可逆优先、回执代替弹窗、升级是例外（默认关闭）
- 10 个哨点 + 默认自动动作：破坏性操作（改写/阻断）、路径越界（改写）、范围漂移（回滚）、幻觉引用（注入纠正）、假完成（重跑验证并退回结论）、验证缺失（补跑）、循环空转（中断/降频）、成本异常（降频/断点）、敏感信息（脱敏/阻断）、未兑现承诺（记录）
- 回执四要素：发现 / 证据（eventId + 片段）/ 自动动作 / 可撤销
- 信任分：自动处理红 -8、黄 -5；仅记录模式放行红 -30 / 黄 -15；撤销自动动作 -5
- M0（已完成）：规则引擎 + Reviewer + 自动动作子集 + 回执 + 信任分 + 单会话复盘
- M1：真拦截/改写 hook、自定义自动动作、会话内纠正、报告导出
- M2：哨规/动作市场、跨会话模式、公开评测基准

开发与验证

node --test test/events.test.mjs test/rules.test.mjs test/score.test.mjs \
test/reviewer.test.mjs test/actions.test.mjs test/host.test.mjs # 99/99
node scripts/replay.mjs # 3/3 CHECK PASS（含信任分与复盘生成）
node scripts/replay.mjs --json # 机器可读：checks / decisions / score / plans
node scripts/probe-events.mjs # 解析本机最新真机会话：帧数/行数/事件直方图
node scripts/build-fixtures.mjs # 重新生成三份夹具

Node 24 下 node --test test/ 不支持目录，需显式列文件；定时器均已 unref()，测试不会挂住进程。

技术形态

已实现（T1.1–T1.7，M1）
- 事件层：真机会话 = 多帧 zstd 拼接的 session.v4.jsonl.zstd；按 magic 切帧逐帧解码（Node 单次 zstdDecompressSync 只出第一帧）。SessionNormalizer 做 seq 去重、缺口检测、工具归因；双事件源：总线（ctx.on('session/event') + snapshotEvents 补历史）与 JSONL tail（偏移量、半帧重试、轮转重置）。
- 规则/评分/回执：W1 破坏性命令（命令位置判定，忽略文档/heredoc 里的示例文本）、W2 路径越界、W3 范围漂移（只判源码文件，docs/日志不误报）、W5 假完成；信任分三模式；回执四要素；复盘 markdown。
- L2 Reviewer：严格 JSON schema + 证据门槛（引用不存在 eventId 直接丢弃）+ token 预算（会话 8%）+ 降采样 + 无模型路由时显式降级、绝不阻塞。AutoActionExecutor：nudge / git 回滚（先备份可 undo）/ 测试命令独立重跑 / 脱敏，全部有安全闸（workdir 内、拒敏感目录、不删文件、默认 dry-run）。
- 宿主实时链路：index.js 监听 session/event → ConvoyHub → L1 → 回执/信任分 → /convoy/api/state|stream|receipts|review|config|undo；会话暖启动 hydrate（静默，不重复生成回执）；配置原子落 ~/.dsh/convoy/config.json。
- 客户端：shell.overlay 右下角回执胶囊 + 展开面板（信任分/回执/证据/下载复盘，SSE 实时 + 轮询兜底）；settings.section 模式与开关；保留侧边栏 + main Demo 面板。
- 验证：npm test → 99/99；npm run replay → 3/3；真机四轮冒烟，最终零误报（docs/T1.7-冒烟记录.md）。

M0 边界 / M1 待做

- [ ] 真实执行接线（apply=true + undo 真回滚；M0 只生成可撤销计划）
- [x] L2 模型路由接入（复用宿主 llm 服务，跟随会话路由；每次复核只读、严格 JSON、证据门槛）
- [x] L2 真机接入（每回合只读复核一次；设置页可开关；无路由/无服务显式待命）
- [ ] 执行前「可暂停/可改写」hook 调研（决定 M1 真拦截）
- [ ] 用户误报/干扰接受度与自动动作正确率基线（T2.1 试用）

品牌与视觉

- 产品名固定写作 伴航 Convoy，副标 for DeepSeek Harness；插件 id / npm 包名 dsh-convoy。
- 图标使用 DeepSeek 官方 logo（引用，不重绘、不拉伸、不改色），仅作为生态标识；侧边栏另用自家「伴航」小标（蓝底 + 监视弧线），避免与官方图标混淆。
- 主色 DeepSeek 原生蓝 #4D6BFE；浅色主题：白底 + 浅灰面板 + 少量语义色（红 #E5484D / 黄 #C77F00）。
- 默认字体系统 UI + 中文回退；界面整洁留白，不用深色赛车风。

下一步

1. L2 真机验证：重启 DSH 后跑一个回合，看面板 L2 状态变为「已接入 · 路由」并产出回执
2. T2.1 试用观察（用户日常使用 3–5 天，盯误报；record 模式可先观察）
3. M2 发布：npm + dshbase / awesome-dsh-plugin PR（演示视频：out/video/convoy-60s.mp4，不入库）

旧版本（v0.2「暗哨 watchpost」深色 Demo）保留在 C:\work\dsh-watchpost\ 作为存档；本目录为 v0.3→v0.5「伴航 Convoy」。