agentworkshop 0.7.34 → 0.7.37

package/docs/full-test-plan.md

@@ -0,0 +1,174 @@
+# AgentWorkShop 全功能测试流程 Plan
+
+> 版本无关的常备测试手册（撰写时基线 v0.7.36）。用途：后续直接指令 agent
+> 「按 docs/full-test-plan.md 执行 Phase 0–N」即可完成全功能测试。
+> 断言数为历史全绿基线（2026-09 上旬各轮验收），以脚本实际输出为准；括号内数字仅用于识别明显回退。
+> 最后核对：2026-09-12（脚本清单逐一经 `scripts/` 实存核对）。
+
+---
+
+## 0. 总则
+
+**通过标准**：本 plan 内列出的脚本全部全绿（0 failed）+ 服务日志无新增未解释 error + 关键页面目视无破版。任何红项：先定位修复，再复跑该阶段全量确认。
+
+**执行纪律（每轮必守）**：
+- 本机 7890 代理会拦截 localhost：所有对 127.0.0.1 的 curl/node 调用带 `NO_PROXY='127.0.0.1,localhost'`（或 `NO_PROXY='*'`）。
+- 探针避开 3000/3001 冲突：dev=3000、生产 `aw start`=3001、隔离实例=3021。
+- `.ts` 脚本必须 `npx tsx --tsconfig .nuxt/tsconfig.server.json`（先 build 过一次）。
+- 测试账号（勿改动）：admin@awshop.local / admin123（生产零种子 admin）；perf-runner@awshop.io（admin）；read-verify@awshop.io（plain）。老脚本默认 `E2E_USER ?? 'zhangwei@awshop.io'`，对生产须显式传 env。
+- 凭据纪律：脚本从 env / `/api/system/settings` 运行时读取，不写可用凭据字面量。
+- Bash 写源码/配置会被 Mimosa hook 拒绝 → 用 Write/Edit 工具；git add 源码路径同样被拒。
+- commitlint：subject 首字符不得大写（中文开头最稳），body 每行 ≤100 字符。本仓库有并行会话共享 git index：commit 必须 pathspec 限定，提交后 `git log` 核对没被卷走。
+- 共享实例有累积脏数据（数百产线/未结批次）：判断「数采没采」前先确认产线批次门控（见 §8 排障表）。
+
+**报告产物**：`docs/test-report-<版本>.md`，逐阶段列脚本 → 断言数 → 结果 → 失败详情与处置。
+
+**两档执行模式**：
+| 档位 | 范围 | 约耗时 |
+|---|---|---|
+| 冒烟（quick） | P0 + P1 + P2核心(api-live/perms/config-groups) + P3(protocol-matrix) + P4(agent-team) + P6(aw-start-smoke) + P7 抽查 | ~40 min |
+| 全量（full） | P0–P7 全部 | ~2.5–3.5 h（4 引擎真实 LLM 占 ~40 min） |
+
+---
+
+## Phase 0 环境准备（全部后续阶段的前置）
+
+| # | 动作 | 命令/检查点 |
+|---|---|---|
+| 0.1 | 生产实例 :3001 | `cd D:/codes/ABO/AgentWorkShop && NO_PROXY='127.0.0.1,localhost' node bin/aw.mjs start`（后台）；健康门 `curl --noproxy '*' -s http://127.0.0.1:3001/api/health` 返回 ok |
+| 0.2 | dev 实例 :3000（仅 P4 部分/TUI 需要时再起） | `npm run dev`；健康门同上换 3000 |
+| 0.3 | 协议模拟器五件套 | `node scripts/dev-protocol-simulators.mjs`（MQTT:1883 / HTTP:1889 / ModbusTCP:1502 / ModbusRTU:15030 / OPC UA:4840）+ `node scripts/dev-plc-simulator.mjs`（PLC 涂布线 :15040，PV 40001 / 可写 SP 40021） |
+| 0.4 | PLC 节点模拟器（独立项目，挤出流延） | PLC 项目目录启动（API :4010 + Modbus TCP :16040，40001=熔体温度/40021=加热区1SP，float32 big-endian）；`curl --noproxy '*' http://127.0.0.1:4010/health` |
+| 0.5 | rag-knowledge | KB 后端 :8770（e2e-plc-plugin-closedloop 缺省 8771，见各脚本 KB_BASE）；健康门含 `vector.ready=true`、`embedding_available=true`；挂死（/health 30s+ 超时）→ 在 rag 项目根 `node command/ragctl.js restart backend`；检索 0 命中且 hnsw 报 "Nothing found on disk" → reindex（force 重建） |
+| 0.6 | 工业深度诊断 | API :3210 + RAG 引擎 :8764（降级容忍但须存活）；`curl http://127.0.0.1:8764/health` → status healthy |
+| 0.7 | admin token | 浏览器或 REST 登录 admin@awshop.local 取 token → `export AW_E2E_TOKEN=<token>`（多数 3001 脚本依赖） |
+| 0.8 | 快速健康门 | `node bin/aw.mjs doctor` / `node bin/aw.mjs status`；插件清单 `node bin/aw.mjs plugin list`（rag-bridge、diag-bridge 为 enabled） |
+
+⚠️ 0.3–0.6 任一不可用：对应依赖它的 Phase 3/5 项标记 SKIP 并在报告注明原因，不得静默当绿。
+
+---
+
+## Phase 1 服务层静态回归（无需任何服务在跑）
+
+| 脚本 | 覆盖 | 基线 |
+|---|---|---|
+| `node scripts/test-data-root.mjs` | 单一数据根 `.AgentWorkShop/data` +「最新者胜」迁移 | 52 |
+| `node scripts/test-rollback-index.mjs` | DCW 回滚账本索引化：结果一致 + 热路径更快 | 19 |
+| `node scripts/_dbg-configroot-audit.mjs` | 配置根解析：`./.AgentWorkShop` 优先 / `~` 兜底，start/dev-guard/直跑 .output 三路一致 | 18 |
+| `npm run test:plugin-lifecycle` | 插件生命周期 | 全绿 |
+| `npm run test:sdk-surface` | SDK 面 | 全绿 |
+
+---
+
+## Phase 2 生产实例 API/UI 回归（对 :3001）
+
+前置：0.1 + 0.7。
+
+| 脚本 | 覆盖 | 基线 |
+|---|---|---|
+| `AW_E2E_TOKEN=… NO_PROXY='127.0.0.1,localhost' node scripts/api-live-e2e.mjs` | 持久化恢复/模板/频道/任务三模式/agent-tools | 64 |
+| `NO_PROXY='127.0.0.1,localhost' node scripts/_dbg-perms-e2e.mjs http://127.0.0.1:3001 admin123` | 产线权限矩阵（默认无权→readonly/operate 授权逐项） | 20 |
+| `NO_PROXY='127.0.0.1,localhost' node scripts/_dbg-audit-neg-e2e.mjs` | 越权负向（start/stop/samples/WS 无鉴权） | 9 |
+| `NO_PROXY='127.0.0.1,localhost' node scripts/_dbg-render-regression.mjs http://127.0.0.1:3001 admin@awshop.local admin123` | 关键页渲染回归 | 29 |
+| `AW_E2E_TOKEN=… NO_PROXY='127.0.0.1,localhost' node scripts/e2e-config-groups.mjs` | 配置分组系统 + 两桥接插件正确/错误 token·URL 实测 | 58 |
+| `E2E_USER=admin@awshop.local E2E_PASS=admin123 NO_PROXY='127.0.0.1,localhost' node scripts/_dbg-groups-ui-verify.mjs` | 设置页分组 UI（浏览器实测） | 16 |
+| `node scripts/_dbg-daq-rowstyle-verify.mjs` | 数采行样式 + 设置页三节拍 | 10+6 |
+| `node scripts/_dbg-daq-intervals-func.mjs` | 三节拍（采集/WS下发/趋势刷新）独立热生效 + 下限钳制 + 详情页按节拍实测重拉 | 13 |
+| `node scripts/_dbg-town-smoke.mjs` | 数字孪生画布/场景钩子/帧推进 | 5 |
+
+---
+
+## Phase 3 协议与数采/数控全栈（真实模拟工况，对 :3001）
+
+前置：0.1 + 0.3 + 0.4 + 0.5 + 0.6 + 0.7。
+
+| 脚本 | 覆盖 | 基线 |
+|---|---|---|
+| `NO_PROXY='*' node scripts/_dbg-protocol-matrix.mjs` | 5 协议 DAQ 读取 + 4 路 DCW 读/写闭环（modbus-tcp SP→PV 真收敛） | 全绿 |
+| `NO_PROXY='127.0.0.1,localhost' node scripts/_dbg-live-line-e2e.mjs http://127.0.0.1:3001` | S1 夹具→S2 协议连通→S3 数采落库→S4 五路数控→S5 Agent 闭环(CLOSEDLOOP-OK)→S6 HITL 真实写入 | 37 |
+| `AW_E2E_TOKEN=… NO_PROXY='127.0.0.1,localhost' node scripts/e2e-plc-plugin-closedloop.mjs` | A 插件健康 / B 产线供给 / C 数采交叉核对 / D 真实诊断 / E 知识闭环 / F 参数逐键热生效 / G Channel 级开关 | 71 |
+| `AW_E2E_TOKEN=… NO_PROXY='127.0.0.1,localhost' node scripts/production-closed-loop-e2e.mjs` | 生产闭环增强：事件自动诊断(source=auto)→kb_search→dcw_control(HITL)→回写 | 23 |
+| `AW_E2E_TOKEN=… NO_PROXY='127.0.0.1,localhost' node scripts/three-system-e2e.mjs`（可选 `--full` 走 omp 真实诊断） | AW × 深度诊断 × rag-knowledge 三系统；插件启停热重载 | 52 |
+
+---
+
+## Phase 4 Agent / Harness 多引擎（真实 LLM，最耗时）
+
+前置：0.1 + 0.7；zhipu 配额 429 时当日 12:45 重置后重跑。
+
+| 脚本 | 覆盖 | 基线 |
+|---|---|---|
+| `NO_PROXY='127.0.0.1,localhost' node scripts/e2e-agent-team.mjs --base http://127.0.0.1:3001` | 团队 CRUD/批量部署/lead 分发/worker 真实执行/409 冲突 | 25 |
+| `KEEP=1 node scripts/_dbg-opslog-agent-e2e.mjs`（自起隔离实例 :3021；占用则先清理） | Agent 归属(actor=Channel/成员) + ops_log/recipe_log 工具注入 + **四引擎真实 LLM**（omp/codex/dsh/opencode 全 COMPLETED） | 39；耗时 ~11 min |
+| `NO_PROXY='127.0.0.1,localhost' node scripts/_dbg-multiharness-live-e2e.mjs` | 四引擎并行真实 Modbus：OMP-CLOSEDLOOP-OK / CODEX-WRITE-OK / DSH-DAQ-OK / OC-RECIPE-OK + PLC 回读断言 | 四标记全出现 |
+| `NO_PROXY='127.0.0.1,localhost' node scripts/e2e-hitl-live.mjs` | HITL 实时审批链 | 全绿 |
+
+**验收要点**：所有任务终态必须 COMPLETED。出现 CANCELED/FAILED 即回归（历史根因：codex 无 host 工具面+600s 停滞误杀；dsh 无 MCP client 靠交付兜底收口——已修，勿再引入）。交付物必须含各场景 OK 标记。`KEEP=1` 保留现场便于查证，查完清理。
+
+---
+
+## Phase 5 子系统专项
+
+| 脚本 | 前置 | 覆盖 | 基线 |
+|---|---|---|---|
+| `npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/e2e-aml.ts`（真实链路加 `--real`，首次数分钟） | 0.1 + 0.7 | AML：数据集→隔离拒绝→训练→门禁→排行榜→晋升/预测守卫→审计 | 全绿 |
+| `AW_E2E_TOKEN=… node scripts/aml-ui-smoke.mjs` | 0.1 | AML UI 冒烟 | 全绿 |
+| `NO_PROXY='127.0.0.1,localhost' node scripts/_dbg-recipe-e2e.mjs`（自起隔离实例 :3021） | 0.1 | Recipe 版本流/归因/Agent 更新与回滚/line_context | 24 |
+| `SIM_BASE=http://127.0.0.1:4010 NO_PROXY='127.0.0.1,localhost' node scripts/experiment-castfilm-closedloop.mjs` | 0.4 | 挤出流延孪生闭环优化实验 | 收敛达标(J≈96%) |
+| rag 专项（手工三项） | 0.5 | ① `/health` vector.ready=true；② kb_search 用语料词法重叠词命中>0（无重叠 0 命中是设计）；③ kb_store 后可检索回 | 三项过 |
+
+---
+
+## Phase 6 TUI / CLI / 打包链路
+
+| # | 动作 | 命令/基线 |
+|---|---|---|
+| 6.1 | TUI 无头 e2e（dev :3000） | `node scripts/tui-smoke.mjs --base http://127.0.0.1:3000`（生产时 `AW_TUI_EMAIL=admin@awshop.local AW_TUI_PASSWORD=admin123`） |
+| 6.2 | 全局 `aw tui` 真实路径 | 全局包已装时：`node scripts/e2e-aw-tui-global.mjs --base http://127.0.0.1:3001` |
+| 6.3 | CLI 面 | `aw doctor` / `aw status` / `aw config get <key>` 输出与文档一致；`aw plugin disable rag-bridge` → 1s 内路由+工具消失 → `enable` 恢复（热生效实测） |
+| 6.4 | aw start 打包冒烟 | `AW_E2E_TOKEN=… NO_PROXY='127.0.0.1,localhost' node scripts/aw-start-smoke.mjs`（前置 0.1 + dev-plc-simulator :15040）基线 26 |
+
+---
+
+## Phase 7 浏览器目视验收（Puppeteer 截图逐页过目）
+
+覆盖页：登录/仪表盘/产线管理/数采列表+详情（趋势图在动）/数控/数字孪生（帧推进+无黑屏）/设置（分组渲染+折叠+来源徽标）/插件/运维日志 /logs/AML/AgentTeam。
+工具：`scripts/ui-screenshot.mjs`、`scripts/_dbg-audit-all-pages.mjs`（全页 console error 扫描=0）。截图存 `.e2e-shots/` 逐张目视；破版/白屏/控制台报错即红项。
+
+---
+
+## Phase 8 发布链路（仅当次有版本变更时执行）
+
+1. `npm run build` 通过；2. commit（pathspec 限定）+ push（`git -c http.proxy= push`）；3. `npm publish --no-proxy --https-proxy=null --proxy=null`（本地 7890 会拦 PUT；CDN 传播 5–7 min，期间安装 404 属正常）；4. `npm i -g agentworkshop@latest --no-proxy`；5. 全局 `aw start`（home 模式）健康门 + 抽样回归（P2 的 api-live + P3 的 protocol-matrix）；6. 复核 npm 页面版本与 tarball 内容（`files` 白名单）。
+
+---
+
+## §8 排障速查（历史实锤，先查这里再动手）
+
+| 症状 | 真相与处置 |
+|---|---|
+| 产线报「运行中」但数采不采、start 返回 CONFLICT | 重启后旧批次 LineRun 丢失不自动恢复采样（设计现状）→ 该产线 **stop→start** |
+| produced 恒 0 | 数采受批次门控：无活动批次不采样是设计，非故障 |
+| 部分节点 value=null 且 lastError 为空（静默不采） | 曾是网关 sweep 额度饿死（已修 isDue+游标+并发64）；复现先看节点在表的位置与并发额度 |
+| rag /health 超时 30s+，连带闭环 Stage E 全线超时 | rag 后端挂死 → rag 项目根 `node command/ragctl.js restart backend`；恢复后 ~170ms |
+| kb_search 0 命中但系统正常 | 两阶段检索 stage1=BM25 词法；查询与语料无词法重叠时**有意** 0 结果；换语料词重试 |
+| hnsw "Nothing found on disk" | 进程被杀时 embeddings_queue 未落盘（数据丢失）→ reindex force 重建；健康面应显示 vector.ready=false 预警 |
+| LLM 任务 FAILED with 429 | zhipu 配额限流，当日 12:45 重置后重跑；勿改代码 |
+| codex/dsh 终态 CANCELED 但交付物完整 | 已根修（codex 无条件 CODEX_HOME 种子+停滞 1800s；dsh 交付兜底收口）。复现即回归，查是否有新提交动过 agents/runtime |
+| 工具调用报「未知工具」集中在插件重载窗口 | 插件热重载空窗（已修：注销延后）；复现即回归 |
+| agent-tools/invoke 404 或参数不识别 | body 键是 **args**（非 arguments）；agentId 用 channel 成员**实例 id**（非模板 id） |
+| `aw-start-smoke` 报「Agent dcw_control 下发 178」FAIL、文本是「工具桥不支持该协作工具: dcw_control」 | 该成员用的是**无自有工具面的 harness**（mock 等），REST 直调只会落到协作工具族，够不到工业工具族。`invokeHostTool` 的回退链是 `impl.dispatchHostTool` → `invokeAgentWorkspaceTool`，缺 `host-tool-bridge.dispatchHostTool` 这一跳（见 `manager.ts:2810` 附近）。真实引擎成员自带工具面，不受影响；要补需给回退链加 workspace 上下文，并统一 manual 模式的 HITL 语义 —— 未修，勿当回归 |
+| api-live 持久化段被清 | 脚本预清理吞 `api-e2e-*` 前缀频道；夹具勿用该前缀 |
+| 双绑定 15030 竞态 / 3002 全局包陷阱 / mini-slave 须回显事务 id | 协议模拟器纪律，见协议驱动记忆 |
+| npm publish/install 被 7890 拦 | `--no-proxy --https-proxy=null --proxy=null`；git push 用 `-c http.proxy=` |
+| dev 起服务 500 找不到 `D:\shared\*.mjs` | nitro 相对导入打包坑：须 `@/` 别名（勿用裸相对路径） |
+| tsx 报类型/import 错 | 必须带 `--tsconfig .nuxt/tsconfig.server.json` |
+
+---
+
+## 执行指令模板（给 agent 下达时用）
+
+- 全量：「按 docs/full-test-plan.md 执行 Phase 0–7 全量测试，产出 docs/test-report-<版本>.md」
+- 冒烟：「按 docs/full-test-plan.md 执行冒烟档（§0 两档执行模式）」
+- 单阶段：「按 docs/full-test-plan.md 只跑 Phase 4」
+- 失败处置约定：阻断性失败（服务起不来/P0 环境缺）→ 停下修复后再继续；单脚本红 → 先按 §8 排障表定位，能修则修复并复跑该脚本+相邻脚本；不能修 → 报告标注 FAIL+根因假设，继续后续阶段。

package/docs/multi-harness-architecture.md

@@ -0,0 +1,248 @@
+# 多 Harness 适配架构指南（可移植版）
+
+> 生成日期：2026-09-10 · 基准版本：AgentWorkShop 0.7.27（14 引擎全绿）
+> 用途：供其他项目参照本文档实现「多 Agent Harness（执行引擎）适配」。只讲**架构思想**与**每个引擎的库依赖/集成方式**，不绑定本仓库业务。
+
+---
+
+## 0. 问题域与总原则
+
+**问题域**：平台要把 N 个异构 AI Agent 执行引擎（CLI 工具 / SDK）当作可互换的「Agent 大脑」：同一套上层编排（任务分发、消息、调度、审批、记忆）驱动任意引擎，新增引擎时上层与前端零改动。
+
+**七条核心原则**（全部是本系统实战沉淀，移植时建议原样保留）：
+
+1. **单一契约**：所有引擎实现同一个接口 `AgentInterface`（run/supervise/steer/HITL/进程治理等）。上层（runtime/scheduler/API/前端）只依赖契约，永远不出现 `if (harness === 'codex')`。
+2. **单一事实源注册表**：一个 `HARNESS_REGISTRY` 常量表声明每个引擎的 id/label/描述/主页/**能力面**/工厂函数/**可用性探测声明**。前端下拉、可用性面板、执行前校验、模型目录全部从此派生，禁止第七处硬编码白名单。新增引擎 = 注册表加一项 + 实现一个类。
+3. **两种进程模型，两个基座**：
+   - **常驻会话型**（omp/codex/dsh/opencode/qwen/hermes/claude）：每 Agent 一个长活子进程（或进程内 SDK 会话），lazy 启动、跨消息复用、dispose 时销毁；
+   - **一次性回合型**（gemini/copilot/cursor/crush/goose/pi）：每回合 spawn 一个子进程，进程退出即回合结束，会话延续靠引擎自身的 session id + resume 参数。
+   两个模型各有共享基类（`BaseAgentImpl` → 协议无关平台语义；`OneShotCliAgentImpl` → 一次性 CLI 家族），引擎差异全部收敛为子类/引擎 spec 的一张「映射表」。
+4. **能力如实声明，降级策略显式化**：注册表 `capabilities` 六元组（steer 同轮注入 / supervise lead 调度 / hitl 程序化审批 / terminal 终端镜像 / contextStats 上下文统计 / compact 主动压缩）必须反映引擎真实能力，**不虚报**。引擎不支持的，必须有明确的降级语义（如 steer 恒 `'deferred'` 走信箱；无 HITL 的走预授权白名单），不允许静默缺失。
+5. **工具注入统一化 + 环境变量携带身份**：平台侧的全部协作工具（任务/消息/记忆）与业务工具，通过统一的 host-tool 分发桥暴露给引擎。CLI 引擎的注入主路径是 **stdio MCP server 桥**：桥脚本被引擎当作本地 MCP server 拉起，工具调用经 HTTP 回程落到平台 API（agent token 鉴权）。关键设计：`AW_BASE_URL / AW_AGENT_ID / AW_AGENT_TOKEN` 注入**引擎进程的环境变量**，引擎拉起的 MCP 子进程自动继承 → **配置文件可全局共享，无需每 Agent 一份 HOME**。
+6. **错误即事件 / steer 诚实语义**：spawn 失败、非 0 退出、超时、协议错误都必须产出 `{kind:'error'}` 事件（错误码形如 `CODEX_EXIT_1` + stderr 尾部），绝不静默吞掉。`steer()` 只有真的注入了流式会话才返回 `'steer'`，否则返回 `'deferred'`（消息保持 pending，下一回合携带），保证消息不丢。
+7. **探测与拉起同源**：「引擎是否可用」的 PATH 探测和「真实 spawn」走同一个命令解析函数；执行前在所有入口（模板增改/克隆/实例换引擎/任务直发/lead 派发等，本系统共七处）统一强校验，未知引擎 400、未安装 409，任务不进「起跑后失败」路径。
+
+---
+
+## 1. 分层架构与模块地图
+
+```
+                        上层（harness 无关）
+   runtime(每 Agent 生命周期) · scheduler(lead 调度循环) · HITL API · 前端下拉/徽标
+                                   │ 只依赖
+                            AgentInterface（统一契约）
+                                   │ 由
+                HARNESS_REGISTRY（单一事实源：capabilities/probe/create）
+                                   │ 装配
+   ┌──────────────────────────────┴───────────────────────────────┐
+   │ BaseAgentImpl（平台语义基类）                                  │
+   │  · run() 消息分流：metadata['x-aw-task-kind']='assign'→workerTurn│
+   │    否则有来源→peerTurn                                          │
+   │  · supervise() 模板方法：快照→prompt→collectTurnEvents→JSON 解析 │
+   │  · contextPrefix（场景×身份×手册×名册）/ dispatchHostTool 直调面 │
+   └──────────────┬───────────────────────────────┬───────────────┘
+                  │                               │
+     常驻会话型子类                     OneShotCliAgentImpl（一次性 CLI 基座）
+   omp(RPC) codex(JSON-RPC)          引擎差异=一份 OneShotEngineSpec：
+   dsh/hermes(ACP) opencode(HTTP/SSE)  resolveCommand/buildArgs/promptDelivery
+   qwen(旧版ACP) claude(SDK进程内)      /engineEnv/mapLine/prepare/plainTextStdout…
+
+   ── 共享基础设施（全部引擎复用）──
+   line-spawn        受控子进程拉起：拒绝 shell 元字符；Windows .cmd shim 走
+                     字面量 'cmd.exe /d /s /c' 包装+逐参数校验；PATH+PATHEXT 解析
+   stdio-jsonrpc     NDJSON JSON-RPC 2.0 客户端（响应/通知/服务端请求三分）
+   harness-process   子进程登记/强杀（win32 taskkill /T /F）/OS 存活校准
+   harness-env       MCP 桥环境计算：AW_BASE_URL/AW_AGENT_ID/AW_AGENT_TOKEN
+   aw-mcp-bridge.mjs 零依赖 stdio MCP server → HTTP 回程（agent token 鉴权）
+   host-tool-bridge  全引擎唯一工具分发入口（协作工具族按角色过滤+插件工具）
+   prompt-builder    共享 prompt 组装（worker/peer/supervise/系统手册/JSON 提取）
+   hitl-registry     HITL 中枢（globalThis 单例；kind 枚举=各引擎审批请求类型）
+   harness-availability  可用性探测（与拉起同源；30s 缓存；assertHarnessUsable）
+   harness-models    各引擎 provider/model 目录发现（5min 缓存）
+```
+
+**host tools 工具面**（MCP 桥暴露给引擎的内容）：AgentWorkspace 协作方法族（任务分发/上报/完成、信箱收发、记忆检索/沉淀、名册/队列观察、成员管理等 ~25 个）+ 业务/工业工具族 + 插件注册工具，按角色（lead/worker）过滤。引擎用原生工具调用方式消费，**平台不做任何文本解析**。
+
+**HITL 链路**（引擎审批请求 → 人 → 回答）：引擎侧审批请求（如 codex `requestApproval`、dsh/hermes `session/request_permission`、claude `canUseTool`、qwen `requestToolCallConfirmation`）→ 登记 hitl-registry（kind 枚举：`codex-approval / opencode-permission / dsh-permission / claude-permission / qwen-permission / hermes-permission / omp-dialog / dcw-approval`）→ 前端铃标 → 人经 API 应答 → respondHitl 传导回引擎 → 回合继续。**超时/取消一律 fail-closed（拒绝）**。
+
+---
+
+## 2. 十四个引擎一览
+
+| id | 引擎 | 官方文档 | 集成面 | 进程模型 | 库依赖 |
+|---|---|---|---|---|---|
+| mock | 进程内模拟引擎 | —（内部） | 剧本驱动，无 LLM，联调/CI 用 | 进程内 | 无 |
+| omp | oh-my-pi | https://github.com/acidsugarx/oh-my-pi | `omp --mode rpc` 自定义 RPC 协议 | 常驻子进程 | 全局 CLI `omp` |
+| opencode | OpenCode | https://opencode.ai （server：https://opencode.ai/docs/server ） | `opencode serve --port` + HTTP API + 全局 SSE `/event` | 常驻子进程 | 全局 CLI `opencode` |
+| codex | OpenAI Codex CLI | https://github.com/openai/codex （app-server 协议：`codex-rs/app-server/README.md`） | `codex app-server` NDJSON JSON-RPC v2（thread/start + turn/start） | 常驻子进程 | 全局 CLI `codex` |
+| dsh | DeepSeek Harness | https://github.com/deepseek-ai/DeepSeek-Harness （ACP：`packages/acp/acp/README.md`） | `dsh --profile acp` 标准 ACP v1（session/new + session/prompt 单飞） | 常驻子进程 | 全局 CLI `dsh` |
+| claude | Claude Agent SDK | https://code.claude.com/docs/en/agent-sdk/typescript | 进程内 SDK：`query()` + AsyncIterable 流式输入 | **进程内 SDK**（SDK 自管 claude 二进制） | **npm：`@anthropic-ai/claude-agent-sdk`**（动态 import，缺失时报 HARNESS_NOT_CONFIGURED 而非崩溃） |
+| gemini | Gemini CLI | https://github.com/google-gemini/gemini-cli （headless：`docs/cli/headless.md`） | `gemini -p --output-format stream-json`（JSONL 帧 init/message/tool_use/result） | 一次性回合 | 全局 CLI `gemini` |
+| copilot | GitHub Copilot CLI | https://docs.github.com/en/copilot/how-tos/copilot-cli （编程式：`automate-copilot-cli/run-cli-programmatically`） | `copilot -p --output-format json`（JSONL） | 一次性回合 | 全局 CLI `copilot` |
+| cursor | Cursor CLI | https://cursor.com/docs/cli/headless | `cursor-agent -p --output-format stream-json --stream-partial-output`（帧与 Claude Code 同构） | 一次性回合 | 原生 CLI `cursor-agent` |
+| crush | Charm Crush | https://github.com/charmbracelet/crush | `crush run -q`（v0.92 起无 JSON 格式 → 纯文本 stdout 一次性） | 一次性回合 | CLI `crush`（npm shim 可能损坏，可指包内 bin 直启） |
+| goose | Block Goose | https://blockgoose.io （源码：https://github.com/aaif-goose/goose ，headless 教程在仓库 docs） | `goose run -t --output-format stream-json --name aw-<agentId> [--resume]` | 一次性回合 | 原生 CLI `goose` |
+| qwen | Qwen Code | https://github.com/QwenLM/qwen-code （docs：https://qwenlm-qwen-code.mintlify.app/cli/overview ） | `qwen --experimental-acp`（**旧版 Zed ACP**：camelCase 方法、无 sessionId、单隐式会话） | 常驻子进程 | 全局 CLI `qwen` |
+| pi | pi coding agent | https://github.com/badlogic/pi-mono | `pi -p --mode json`（JSONL：session/message_end/message_update/turn_end）；prompt 经 **@临时文件** 投递（绕 Windows ~8K 命令行上限） | 一次性回合 | CLI `pi`（@mariozechner/pi-coding-agent） |
+| hermes | Hermes Agent | https://github.com/NousResearch/hermes-agent | `hermes acp` 标准 ACP v1（与 dsh 同型，方法名集中一处便于版本漂移修改） | 常驻子进程 | CLI `hermes` |
+
+通用协议参考：**MCP** https://modelcontextprotocol.io · **ACP（Agent Client Protocol）** https://agentclientprotocol.com
+
+> 选型口径（可复用）：候选引擎必须满足「无头模式 + 结构化输出（JSON 事件流）+ MCP 客户端」三要素；能力覆盖密度（七能力面占几项）≥ 5/7 才值得接入。无结构化输出的引擎（如 Amazon Q CLI）宁可进观察名单也不做纯文本抓取——违背「错误即事件/usage 透出」底线。
+
+---
+
+## 3. 每引擎集成卡片（鉴权 · 工具注入 · 审批 · steer）
+
+### omp（默认推荐引擎）
+- 协议：omp 自有 RPC（`--mode rpc`），每 Agent 一个子进程 lazy 启动；事件 `AgentSessionEvent → AgentEvent` 映射。
+- 工具：平台工具经 `set_host_tools` **进程内直调**（不回程），是最早的直连模型。
+- 审批：extension_ui 对话框 → HITL；steer：✅ 原生同轮注入；上下文：被动跟踪 + 平台 70% 阈值主动压缩（引擎原生 auto-compaction 摘要经 harvest 桥落库）。
+- 鉴权：`omp models` 提供 provider 分组目录；自定义网关可用。
+
+### codex
+- 协议：`codex app-server`（stdio NDJSON JSON-RPC v2）。`thread/start` 建会话、`turn/start` 驱动回合、`turn/steer` 同轮注入、`thread/compact/start` 主动压缩、`model/list` 拉模型目录。
+- 工具：impl 装配 `config.toml` 的 `[mcp_servers.aw]` 指向 stdio 桥。
+- 审批：`item/commandExecution|fileChange` 的 `requestApproval`（服务端→客户端请求）→ HITL（decision: accept/decline/cancel）；审批策略 `approvalPolicy: untrusted|on-request|never`，默认 on-request。
+- 鉴权/provider：config.toml 网关配置；`CODEX_HOME` 环境变量可隔离配置目录。
+
+### dsh
+- 协议：标准 ACP v1（JSON-RPC over stdio）：`initialize / session/new / session/prompt / session/cancel`；`session/prompt` 单飞（响应在回合终点返回 stopReason）。方法名集中在一个常量表，pre-1.0 协议漂移时只改一处。
+- 工具：`session/new` 的 `mcpServers` 参数挂 stdio 桥（引擎给工具加 `mcp__aw__` 前缀）。
+- 审批：`session/request_permission` → HITL（allow/reject/cancel，fail-closed）；steer：❌ 恒 deferred。
+- 鉴权/provider：`DEEPSEEK_BASE_URL` 等网关 env；模型目录=内置官方表 + 用户 settings.yaml 自定义网关轻解析。
+
+### opencode
+- 协议：`opencode serve --port <空闲>` 子进程 + 官方 HTTP API（`prompt_async / abort / permissions / summarize`）+ 全局 SSE `/event`。port 用本地 net 探测空闲。
+- 工具：运行时 `POST /mcp` 注册 stdio 桥。
+- 审批：`permission.asked / question.asked` 事件 → HITL（once|always|reject）；steer：✅ 回合运行中再投 prompt（引擎 queue admission），内容不丢。
+- 上下文：`message.tokens` 被动跟踪，越阈值 `POST /session/{id}/summarize`；provider 目录走 `opencode models`（models.dev 生态，任意 OpenAI 兼容网关）。
+
+### claude（SDK 特例）
+- 集成：npm 依赖 `@anthropic-ai/claude-agent-sdk`，**动态 import**（依赖缺失→回合报 HARNESS_NOT_CONFIGURED，注册表仍可列出）。每 Agent 一个常驻 SDK 会话，`query({ prompt: AsyncIterable, options })` 流式输入。
+- steer：✅ 向流式生成器再 `yield` 一条 user 消息（七引擎中与 omp 并列的原生 steer）。
+- 审批：`canUseTool(tool, input) => PermissionResult` → HITL（allow→`{behavior:'allow',updatedInput}`；deny→`{behavior:'deny',message}`）；AW 桥工具经 `allowedTools: ['mcp__aw']` 预授权不走审批。
+- 工具：`mcpServers.aw` = stdio 桥（工具清单动态 tools/list，插件热更自动传导）；SDK 也支持进程内 SDK MCP server（`createSdkMcpServer`，零回程直调）作替代通道。
+- 上下文：SDK 原生 auto-compact（观测 `compact_boundary`）；usage 从 result（`total_cost_usd/usage/num_turns`）透出。
+- 鉴权/provider：`config.apiKey → ANTHROPIC_AUTH_TOKEN`、`config.providerBaseUrl → ANTHROPIC_BASE_URL`（任意 Anthropic 兼容网关实测可用）。
+
+### gemini
+- 进程：每回合 `gemini -p --output-format stream-json`；init 帧捕获 session_id → 下回合 `--resume <sid>`。
+- 工具：**merge-only** 写 `<workspace>/.gemini/settings.json` 的 `mcpServers.aw`（trust=true，不动用户已有配置）+ `--allowed-mcp-server-names aw` 白名单；native 工具保持 `--approval-mode default`（无头下需确认的操作被引擎拒绝，fail-safe）。
+- 坑：headless 需 `GEMINI_CLI_TRUST_WORKSPACE=true`；鉴权锁定 Google 面（GEMINI_API_KEY/OAuth），**无自定义网关 provider 面**。
+
+### copilot
+- 进程：每回合 `copilot -p --output-format json`（prompt 经 stdin 管道）。
+- 配置隔离：官方 `COPILOT_HOME` 指向 `.AgentWorkShop/harness-config/copilot/<agentId>/`（内种子 mcp-config.json 挂桥）——**唯一用官方 per-agent 目录隔离的引擎**。
+- 授权：`--allow-tool aw` 白名单制（仅授权 AW 桥），native shell/write 默认不授权；`--no-ask-user` 默认开。
+- 鉴权：token 链 `COPILOT_GITHUB_TOKEN > GH_TOKEN > GITHUB_TOKEN`（服务端可直接用 PAT）；GitHub 账号锁定，无自定义网关。
+
+### cursor
+- 进程：每回合 `cursor-agent -p --output-format stream-json --stream-partial-output`；帧与 Claude Code 同构（system/init、assistant、tool_call、result）。
+- 安全档：**默认不带 `--force`** → 文件变更只提案不落地（与平台写控制哲学一致）；per-agent 显式配置才放开。
+- 工具：`--mcp-config` 指向共享 aw-mcp.json（无 agent 段：身份走 env 继承）。已知边界：print 模式 MCP 偶发不触发（版本相关）。鉴权 `CURSOR_API_KEY`，账号锁定。
+
+### crush
+- 进程：每回合 `crush run`；**v0.92 移除了 `--format json`**（相对文档回归）→ 走基座 `plainTextStdout` 模式（stdout 纯文本按增量聚合）。
+- 配置：`./.crushrc`（bash 方言）。文件缺失时整份生成（`mcp add aw` 桥 + `provider add zhipu --type openai-compat` + `model add`），**api_key 引用 `${AW_CRUSH_API_KEY}` 环境变量，凭据不落盘**；已有用户配置则不动。
+- 鉴权：config.apiKey → 进程 env `AW_CRUSH_API_KEY`。run 模式无程序化审批。
+
+### goose
+- 进程：每回合 `goose run --output-format stream-json -t <prompt> --name aw-<agentId> [--resume]`（prompt 必须 `-t`，位置参数被拒 exit 2）。
+- 无头姿势 env：`GOOSE_MODE=auto`、`GOOSE_CONTEXT_STRATEGY=summarize`（引擎原生上下文自动摘要）、`GOOSE_MAX_TURNS`、`GOOSE_DISABLE_SESSION_NAMING=true`。
+- 工具：aw 桥经 `--with-extension "<node> <bridge>"` 临时挂载（身份 env 随进程继承）。
+- 鉴权/provider：`OPENAI_API_KEY` + `GOOSE_PROVIDER` + `OPENAI_HOST`（带 scheme）/`OPENAI_BASE_PATH` 拼接（OpenAI 兼容网关实测可用）。
+
+### qwen
+- 协议：`qwen --experimental-acp`——内嵌**最老版 Zed ACP**（camelCase 方法名、无 sessionId、单隐式会话）：`initialize / sendUserMessage{content[]} / cancelSendMessage`；`streamAssistantMessageChunk` 增量、`requestToolCallConfirmation` → HITL（`qwen-permission`）。`sendUserMessage` 的 JSON-RPC 响应在回合终点返回（与 dsh 单飞同型）。
+- 工具：`~/.qwen/settings.json` merge-only 写 `mcpServers.aw`（trust=true）。
+- 鉴权/provider：`selectedAuthType=openai` + `OPENAI_API_KEY / OPENAI_BASE_URL` 网关；**模型经 `OPENAI_MODEL` env**（acp 路径 `-m` 不生效）。教训：同族引擎（gemini fork）也要逐项探针，不能假设协议一致。
+
+### pi
+- 进程：每回合 `pi -p --mode json`；**promptDelivery='argFile'**——prompt 写临时文件后以 `@<path>` 位置参数投递，规避 Windows cmd ~8K 命令行上限。
+- 工具：pi 无内建 MCP → 零依赖扩展 `pi-aw-tools.mjs` 经 `-e` 加载；工具清单由回合前置钩子从 hostToolsForRole 写临时文件（`AW_PI_TOOLS_FILE` env 指路）；工具 execute 走平台 HTTP 回程（身份 env 由 pi 进程继承到扩展）。**MCP 之外的第三种工具注入形态：引擎原生扩展机制。**
+- 鉴权/provider：`--provider/--model` + `~/.pi/agent/models.json` 自定义 provider（anthropic-messages 网关实测可用）；`config.apiKey → --api-key` 透传。
+
+### hermes
+- 协议：`hermes acp` 标准 ACP v1，与 dsh 同型实现（session/new + session/prompt 单飞）。
+- 审批：`session/request_permission` → HITL（`hermes-permission`，fail-closed）。
+- 工具：hermes 自身 MCP 体系（`hermes mcp add aw ...` 用户级配置一次）。
+- 鉴权/provider：模型面来自 hermes 自身 config.yaml（`hermes model` 交互配置）；`config.apiKey → GLM_API_KEY` env（zai provider 接 GLM）、`config.provider/model → HERMES_PROVIDER/HERMES_MODEL` env。
+
+### mock
+- 进程内剧本引擎：无 LLM、恒可用（`probe: {inprocess:true}`）、steer=true 其余能力按需。用途：联调/CI/e2e 在无任何外部 CLI 与凭据的机器上全链路跑通平台语义。**移植时强烈建议先做 mock 再接真引擎。**
+
+---
+
+## 4. 能力矩阵（注册表 capabilities 实际声明值）
+
+| 引擎 | steer 同轮 | supervise 调度 | hitl 审批 | terminal | contextStats | compact |
+|---|---|---|---|---|---|---|
+| mock | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| omp | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| opencode | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| codex | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| dsh | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ |
+| claude | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| gemini | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ |
+| copilot | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| cursor | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| crush | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ |
+| goose | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ |
+| qwen | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| pi | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ |
+| hermes | ❌ | ✅ | ✅ | ❌ | ✅ | ❌ |
+
+- `supervise`（lead 调度回合）是平台侧 prompt 驱动的，所有引擎都能做——所以全 ✅；它不属于引擎原生能力。
+- **无 HITL 引擎的安全姿态**（重要设计）：AW 桥工具是平台可信面、显式白名单放行；引擎 native 写/执行工具保持各引擎**最保守档**（gemini `--approval-mode default`、copilot 仅 `--allow-tool aw`、cursor 默认无 `--force`、goose headless fail-safe）。高危操作在这些引擎上**默认不发生**，而不是静默放行。
+
+---
+
+## 5. 新增一个引擎的接入清单（Step-by-step）
+
+1. **调研探针先行**：写一次性探针脚本（spawn → 首个结构化事件 → 退出码语义），确认：无头参数、JSONL 帧形、会话延续标志、MCP 配置定位、鉴权 env 面、provider 网关面、审批事件存在性。**产出差异表后再写 impl**（勿信文档，文档会回归——crush 删 JSON 格式是实例）。
+2. **注册表条目**：`HARNESS_REGISTRY` 加一项——id/label/description/homepage/**capabilities（如实初稿，探针后修正）**/`create`（工厂：new Impl({...config, agentId, name, role, channelId, token})）/**probe**（进程内引擎 `{inprocess:true}`；进程型 `{command: c => 覆盖链}`，与真实 spawn 同源）。
+3. **选择基座**：常驻会话型 → 继承 `BaseAgentImpl`，实现 `workerTurn/peerTurn/collectTurnEvents`（+ steer/getContextStats/respondHitl 按能力覆盖）；一次性 CLI 型 → 在 `OneShotCliAgentImpl` 上写一份 `OneShotEngineSpec`（resolveCommand/buildArgs/promptDelivery/engineEnv/mapLine/prepare/…），通常 80~250 行。
+   ⚠️ 基类构造参数必须显式 `super(config, spec)` 透传（空子类隐式构造器会丢 spec → 静默失败）。
+4. **工具注入**：优先 stdio MCP 桥（merge-only 写引擎配置 or `--mcp-config` 旗标 or 运行时注册 API）；引擎无 MCP → 仿 pi 用引擎原生扩展机制；SDK 型 → SDK MCP server。**身份 env（AW_AGENT_ID/AW_AGENT_TOKEN/AW_BASE_URL）必须注入引擎进程**，让桥子进程继承。
+5. **审批接入**（若有）：引擎审批请求 → hitl-registry 注册（新增 kind 进枚举）→ 实现 `respondHitl`（outcome 映射回引擎协议；超时/取消 fail-closed）。
+6. **平台面派生项**：运行时设置加 `harness.<id>_command`（命令覆盖链最后一环）；模型目录（静态表 or 引擎子进程发现）；i18n 词条（引擎名/未安装态，双语）；文档页（安装/鉴权/能力矩阵/已知限制四节）。
+7. **测试验收**：
+   - 单测：假 CLI（node -e 输出预制 JSONL）断言事件映射/退出码→错误事件/abort 杀树/会话 id 捕获/resume 参数/HITL 超时 deny；
+   - 引擎 e2e 双场景：A=工具闭环（引擎经桥调 report_progress→complete_task→落库）；B=HITL（注册→铃标→respond→回合继续至 done）；真实子进程+真实 LLM，**凭据缺失自动 SKIP（有因跳过≠失败）**；
+   - 可用性三态断言（未知 400 / 未装 409 / 装了 resolvedPath）；
+   - 前端：下拉出现新引擎、未安装灰化、设置页命令项探测联动；
+   - 回归门：既有引擎 e2e + runtime/liveness 单测全绿。
+
+---
+
+## 6. 工程纪律与已知坑（移植时省命）
+
+- **Windows**：npm 全局 CLI 是 `.cmd` shim，CreateProcess 不能直启 → 固定 `cmd.exe /d /s /c` 包装 + 逐参数严格校验（拒绝引号/控制字符），参数面保持结构化。包装器必须是字面量，绝不由环境变量决定。npm shim 本身可能损坏（crush 实例）→ 命令设置可指向包内真实 bin。
+- **命令行长度**：Windows cmd ~8K 上限 → 长 prompt 用 stdin 投递（默认）或 argFile（`@file`，pi 模式）。
+- **stdin EOF**：`promptDelivery=arg` 时基座仍须关闭 stdin，否则等 stdin 的引擎挂起（crush 实例）。
+- **同族≠同协议**：gemini/qwen 同 fork 但事件协议完全不同（stream-json vs 旧版 zed ACP）；每个引擎独立探针。
+- **配置文件写入一律 merge-only**：只增不改，用户已有配置解析失败时**保留原文件不动**并告警；凭据永远走 env 引用不落盘。
+- **多 Agent 并发**：环境变量携带身份使引擎配置可全局共享；per-agent 会话隔离各用引擎机制（goose `--name`、copilot `COPILOT_HOME`、codex `CODEX_HOME`、dsh/omp 进程独占）；同一 Agent 同时只允许一个回合（回合互斥位）。
+- **进程治理**：所有子进程登记注册表；abort = 杀进程树（win32 `taskkill /T /F`）；OS 存活周期校准（休眠/强杀后 exit 事件可能不达父进程）。
+- **schema 漂移防护**：解析器对未知事件/未知 type **忽略并计数上报**（不崩）；错误消息附 stderr 尾部；引擎版本 pin 建议。
+- **不许静默**：能力缺失有显式降级语义；执行前强校验给「人话」报错；错误即事件。
+
+---
+
+## 7. 本仓库对应文件索引（供交叉查阅）
+
+| 职责 | 文件 |
+|---|---|
+| 注册表 + capabilities | `server/services/workshop/agents/registry.ts` |
+| 统一契约 | `server/services/workshop/agents/agent-interface.ts` |
+| 平台语义基类 | `server/services/workshop/agents/base-agent.ts` |
+| 一次性 CLI 基座 | `server/services/workshop/agents/adapters/one-shot-cli-agent.ts` |
+| 受控 spawn | `server/services/workshop/agents/adapters/line-spawn.ts` |
+| JSON-RPC 基座 | `server/services/workshop/agents/adapters/stdio-jsonrpc.ts` |
+| 各引擎 impl | 同目录 `{omp,codex,dsh,opencode,claude,gemini,qwen,copilot,cursor,crush,goose,pi,hermes,mock}-agent.ts` |
+| MCP 回程桥 | `server/harness/aw-mcp-bridge.mjs`（零依赖）· pi 扩展 `server/harness/pi-aw-tools.mjs` |
+| 工具分发/权限/审批 | `host-tool-bridge.ts` · `tool-approvals.ts` · `hitl-registry.ts` |
+| 环境注入/进程治理/探测/模型目录 | `harness-env.ts` · `harness-process.ts` · `harness-availability.ts` · `harness-models.ts` |
+| prompt 组装 | `prompt-builder.ts` |
+| e2e | `scripts/e2e-multi-harness.ts [engine]`（双场景，401 自动 SKIP） |