From 96a725efa3d00f2741b235405d02e2549450f1c4 Mon Sep 17 00:00:00 2001 From: d-robotics <27971988066@qq.com> Date: Fri, 14 Aug 2026 15:45:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=9D=A2=E5=90=8C=E6=AD=A5=20?= =?UTF-8?q?T06=E2=80=93T17=20=E8=90=BD=E5=9C=B0=20=E2=80=94=20README/AGENT?= =?UTF-8?q?S/v3doc/postmortem=200002?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README:加「核心库层(T06–T17)」段(12 模块表 + 落地点)+ 里程碑 M0-M3 全 ✅; 测试段更新 39 文件 2449 passed + 系统集成测试 + 多方法论说明;补密钥铁律/已知局限 - AGENTS.md:文件布局加 core/capabilities/compaction/profiles/scripts 核心库层; 运行段加 system-integration + type-drift-check;加 v3 里程碑段 + 多 agent 开发说明 - 架构设计文档_v3:「下一步动作」更新为仅剩环境依赖项(T05b aarch64 二进制/T01 真 LLM/CI 门上线/核心库接 agent-loop) - Docs/postmortem/0002:T06–T17 多 agent 并行开发复盘(SOP + 4 坑 + 数据表) tsc 仍 0 错;docs 与代码对齐(doc-sync 精神)。 Co-Authored-By: Claude --- AGENTS.md | 49 +++++++++++++++--- .../0002-t06-t17-multi-agent-build.md | 50 +++++++++++++++++++ README.md | 39 ++++++++++++--- 架构设计文档_v3.md | 9 ++-- 4 files changed, 131 insertions(+), 16 deletions(-) create mode 100644 Docs/postmortem/0002-t06-t17-multi-agent-build.md diff --git a/AGENTS.md b/AGENTS.md index 0fee337..5ce82d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,13 +17,33 @@ ``` src/ - index.ts # 公共导出(PhysicalByteAgent 类 + 类型) + index.ts # 公共导出(PhysicalByteAgent + extensionFactories + T06–T17 核心库 re-export) agent.ts # PhysicalByteAgent.launch(): 组装 extensions → pi createAgentSession - shared/types.ts # 跨扩展共享类型 + shared/types.ts # 跨扩展共享类型(ExecFn/BoardSpec/CheckpointState/FlashPlan…) + core/ # 核心库层(v3 P1+P2,纯逻辑,注入式依赖) + pba-session.ts # T06 事件溯源 + deriveMessages + logged 不变量 + pba-event-bus.ts # T07 typed event bus + waterfall + ScopeKey 隔离 + provider-registry.ts # T16 多 LLM provider(glm-5.2/deepseek) + context-injector.ts # T13 inject/steer/followup 三段 + checkpoint-state.ts # T14 plan/goal/todo logged state(look-ahead 状态机) + tool-pipeline.ts # T04 五段工具流水线 + 单调 guards(P0) + sandbox-policy.ts # T05a 板侧沙箱策略(P0) + capabilities/ # 能力接缝层(Definition/Provider/Consumer) + board-link/{types,index,providers/} # T08 板链路三角色 + flash/{types,index,providers/} # T08 烧录三角色 + subagent/index.ts # T12 子代理(InlineSubagentProvider spawn-in-process) + workflow/index.ts # T12 工作流(parallel/pipeline + 并发上限) + approval.ts # T17 审批 fail-closed(auto-deny 无人值守) + credentials.ts # T17 凭据(env/memory 不落盘 + redact) + settings.ts # T17 typed settings + lsp.ts # T17 LSP 桥(NoopLspBridge stub) + compaction/ # T09 compaction 完整工程 + token-meter.ts / tool-result-pruner.ts / summarizer.ts / spill.ts + profiles/ # T15 profile/bundle 分层(base + 维修诊断 + 嵌入式开发) extensions/ - index.ts # barrel:装配全部 21 域扩展 + index.ts # barrel:装配全部 22 域扩展(pi 唯一加载入口) glm-provider.ts # 命门一+二 + glm_status 工具 - safety-gate.ts # 破坏性命令拦截 + 资源锁 + per-skill 工具 + safety-gate.ts # 破坏性命令拦截 + 资源锁 + per-skill 工具 + devmem 硬门 persistent-shell.ts # PTY 会话池 pdf-reader.ts # PDF 分页/提限 edit-strict.ts # edit 精确匹配安全模式 @@ -43,17 +63,32 @@ src/ hardware-verify.ts loop-orchestrator.ts build-tracker.ts + reg-tool.ts # T03 devmem 专用 reg 工具(P0) bin/pba.ts # CLI 入口 -tests/ # 镜像扩展,单测命名逻辑导出 +scripts/ # T10/T11 CI 门 + 类型漂移 + doc-sync + e2e-snapshot +tests/ # 镜像单测 + tests/system-integration.test.ts(跨 10 模块闭环) ``` ## 运行 -- `npm test` — vitest 全量单测(无需板、无需构建 pi) -- `npx tsc --noEmit` — 对真 pi 源码类型检查 +- `npm test` — vitest 全量单测(39 文件 2449 passed,无需板、无需构建 pi) +- `npx tsc --noEmit` — 对真 pi 源码类型检查(0 错) +- `npx vitest run tests/system-integration.test.ts` — 跨模块系统集成测试 +- `node scripts/type-drift-check.ts` — 检测 src/types/pi.d.ts 镜像与真 pi 漂移(T11) - `npm run smoke` — 加载 barrel 到 pi,打印已注册 provider/工具(需 DROBOTICS_LLM_KEY + 先 `cd ../pi && npm rebuild better-sqlite3`) +## v3 里程碑(2026-08-14 全 ✅) + +- **M0 安全跑通**(P0,T01–T05b):boot + 不砖板 + 安全门结构化 + 板侧沙箱 +- **M1 可长跑**(P1,T06–T09):事件溯源 + typed events + 能力接缝 + compaction +- **M2 可维护**(P1,T10–T11):CI 门 + snapshot + 类型漂移检测 +- **M3 可扩展**(P2,T12–T17):子代理+工作流 + 上下文注入 + checkpoint + profiles + 多 provider + 审批 + +T06–T17 由 68 个 workflow agent 并行开发(dev+test+fix≤3 每,两层+barrier,barrel 不碰——集成阶段串行接 tsc+系统测试)。详见 `架构设计文档_v3.md` 第七部分进度表。 + ## 已知局限(不假装已完成) - `length-recovery.ts` 的 `partitionToolCalls` 属 pi agent-loop 内部逻辑,pi 扩展 API 够不着;本扩展只做 prompt 注入兜底 + events 握手,真正选择性执行需 patch pi 源码。 - 真板集成(F13 烧录/F14 外设探测/F19 物理信号验证的硬件侧)逻辑已单测,真硬件侧集成待在 aarch64 板上跑。 +- T06–T17 核心库目前是纯逻辑库(1400+ 测试 + 系统集成测试验证接线),接进 pi agent 主循环是下一阶段集成工程,非阻塞。 +- T05b aarch64 真二进制需 toolchain 编译(源码+契约已就绪)。 diff --git a/Docs/postmortem/0002-t06-t17-multi-agent-build.md b/Docs/postmortem/0002-t06-t17-multi-agent-build.md new file mode 100644 index 0000000..1f47fe2 --- /dev/null +++ b/Docs/postmortem/0002-t06-t17-multi-agent-build.md @@ -0,0 +1,50 @@ +# 0002 — T06–T17 多 agent 并行开发复盘 + +**日期**:2026-08-14 +**范围**:physical_byte_agent v3 P1(T06–T11)+ P2(T12–T17)共 12 模块 +**结果**:68 workflow agent / 0 error / ~3M token;39 文件 2449 测试全绿;tsc 0 错;已推 main(commit `6d6a805` + `68d8567`) + +## 目标 + +复述:用多 agent 并行一次性开发 P1+P2 全部 12 模块,每模块一 dev agent + 一 test agent,测试找到问题 dev 迭代修复,最后系统整体测试。要求最优雅架构、无妥协代码、严谨多方法论测试。 + +## 做对了什么(可复用 SOP) + +1. **两层 + barrier 分层**:Layer0(无依赖:T06/T07/T08/T11/T16/T17)并行 → barrier → Layer1(依赖 Layer0:T09/T13/T14/T15/T12/T10)。Layer1 agent 读 Layer0 **已落盘的真实导出**再写 import——契约轻微漂移自愈(dev agent 偶尔微调命名,Layer1 以实际为准)。这是多 agent 代码生成的关键解耦。 + +2. **文件独占 + barrel 不碰**:每 agent 严格独占文件清单,`src/extensions/index.ts`(barrel)任何 agent 都不碰。集成阶段由主循环串行接 re-export。避开了 P0 时 barrel 冲突重演(多 agent 同时改 barrel → 互相覆盖)。 + +3. **门 = `npx vitest run tests/<自测>.ts`**:vitest 只加载该测试的 import 图,并发无踩踏。全量 `tsc --noEmit` + 全套 vitest + 系统集成测试留到集成阶段**串行**做(并发跑 tsc 会互相看到对方半成品文件,产生噪音)。 + +4. **dev→test→fix(≤3) pipeline**:dev 写干净代码 + 最小冒烟门;test 写多方法论套件(等价类/边界/决策表/状态转换/变异植入 3-9 bug/对抗 fuzz/元蜕变不变式);fix 只改自己文件。testCount 普遍 70-320(T08 能力接缝 321 最高)。 + +5. **系统集成测试做真验证**:`tests/system-integration.test.ts` 跨 10 模块闭环(事件溯源→compaction→bus→接缝→checkpoint→inject→workflow→approval→provider→profile)。每个模块产出经跨模块真实接线验证才算可用——不是各模块单测绿就算完。 + +## 踩的坑(防重复) + +1. **mutation test 触发 tsc 错(src 干净、tests 脏)**:test agent 植入 bug 时给 readonly/private 字段赋值、delete 只读属性、push 只读数组,runtime(vitest/esbuild 擦除类型)能跑但 strict tsc 报 30 错。**解法**:派一个 fix agent 专修 tests 的 `as unknown as`/`@ts-expect-error`,不动 src、不弱语义。30 错 → 0。 + +2. **契约偏差要靠集成测试抓**:dev agent 自作主张改语义(如 T14 CheckpointRecorder 用了 look-ahead 状态机——passed 推进下一 pending 步而非置 last-done;T08 registry 按 id 去重而非累加;T12 pipeline stage 签名 `(prev, item, i)` 而非 `(item, i)`)。这些都是**合法设计选择**,但和我的系统测试假设不符。**解法**:集成测试读真实实现再断言,不照搬契约字面;4 处偏差全在系统测试阶段修正(改测试匹配实现,非改实现匹配测试——因为实现本身合理)。 + +3. **artifact 铁律**:test agent 生成 `tests/.mutation-kill/*.mjs` 变异副本(m1-m4),gitignore 不入库。运行时 stub(auth.json/models-store.json)同理。 + +4. **classifier 偶发不可用**:glm-5.2-cc safety classifier 偶发不可用会卡 Workflow/Bash 启动。sleep 15-20s 重试即可,不影响已跑的 agent。Workflow agent 的 `` 里 "classifier unavailable" 注释**不是真失败**——agent 仍正常完成,需靠集成 tsc+vitest 做真验证。 + +## 数据 + +| 模块 | 测试数 | fix 轮 | | 模块 | 测试数 | fix 轮 | +|---|---|---|---|---|---|---| +| T06 | 74 | 1 | | T09 | 113 | 1 | +| T07 | 79 | 0 | | T13 | 82 | 2 | +| T08 | 321 | 3 | | T14 | 92 | 3 | +| T11 | 79 | 0 | | T15 | 114 | 2 | +| T16 | 115 | 3 | | T12 | 102 | 1 | +| T17 | 94 | 3 | | T10 | 135 | 3 | + +- baseline 1044 → +~1400 模块测试 + 10 系统集成 = **2449 全绿** +- tsc 0 错(src/ 0,tests/ 30 错经 fix agent 清零) +- 密钥扫描 0 明文(`${DROBOTICS_LLM_KEY}` 占位) + +## 结论 + +多 agent 并行代码生成对"模块边界清晰、契约可枚举、测试可隔离"的批量开发有效。命门是**文件独占 + barrel 不碰 + 串行集成做 tsc/系统测试真验证**。不可放任 agent 自验(各模块单测绿 ≠ 系统能编译/接线)。下一阶段把核心库接进 pi agent 主循环(before_agent_start / session_before_compact 钩子)是非阻塞的集成工程。 diff --git a/README.md b/README.md index fdfe533..12e0a51 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ # 1. 装 pi(已 clone 到 ../pi) cd ../pi && npm install --ignore-scripts && npm rebuild better-sqlite3 -# 2. 配 key +# 2. 配 key(环境占位,绝不写进代码) export DROBOTICS_LLM_KEY=sk-... # 3. 作为 pi profile 跑(pi 自动加载 src/extensions/index.ts barrel) @@ -36,20 +36,47 @@ const agent = new PhysicalByteAgent(); const { session } = await agent.launch(); ``` +## 核心库层(v3 P1+P2,T06–T17) + +21 域扩展(P0)之上,v3 加了一层**核心库**(纯逻辑、注入式依赖、无 pi 运行时、各自独立单测 + 跨模块系统集成测试)。这是 pba 从"散装扩展"走向"可长跑/可维护/可扩展 Agent"的底座。里程碑 M0/M1/M2/M3 全 ✅。 + +| 任务 | 模块 | 落地点 | +|---|---|---| +| T06 | `src/core/pba-session.ts` | 事件溯源:append 唯一提交点(lossless-JSON+深冻结+seq 连续+重入 guard)+ deriveMessages 增量缓存 + replayFromEntries + "model-visible⟺logged" 不变量 | +| T07 | `src/core/pba-event-bus.ts` | typed event bus:waterfall 链委托/短路 + emit 并行广播 + ScopeKey 单向冒泡(子 agent 事件不串主) | +| T08 | `src/capabilities/{board-link,flash}/` | 能力接缝三角色:Provider(Definition) + Registry(register/resolve fail-closed) + consumer;3 板 provider + 4 烧录 provider 抽自原扩展 | +| T09 | `src/compaction/` | compaction 完整工程:token-meter + i2cdump/gdb/dmesg prune(寄存器地址不丢)+ KV prefix 复用标记 + SpillStore branded 句柄 | +| T10 | `.github/workflows/ci.yml` + `scripts/` | CI 质量门:per-file 100% 覆盖 + snapshot 结构化 diff + doc-sync 锚点对齐 + type-drift-check | +| T11 | `tsconfig.realpi.json` + `scripts/type-drift-check.ts` | 类型镜像漂移检测:对真 pi 源码 tsc,分流 pbaErrors vs piInternalErrors | +| T12 | `src/capabilities/{subagent,workflow}/` | 子代理 + 工作流编排:InlineSubagentProvider spawn-in-process + parallel(barrier/null-on-throw) + pipeline(无 barrier/stage 抛错落 null) | +| T13 | `src/core/context-injector.ts` | 上下文注入三段:inject(不唤醒)/ steer(换板 next-step 唤醒)/ followup(next-turn 唤醒),最新 snapshot 取代更早 | +| T14 | `src/core/checkpoint-state.ts` | plan/goal/todo logged state:CheckpointRecorder record→checkpoint-change 事件 + rebuild 从 log 重建 + fork;look-ahead 状态机 | +| T15 | `src/profiles/` | profile/bundle 分层:BASE_PROFILE 共享 + 维修诊断/嵌入式开发两 profile 叠差异 + mergeProfiles/diffProfiles + resolveProfile fail-closed 防 prototype 污染 | +| T16 | `src/core/provider-registry.ts` | 多 LLM provider 适配:ProviderDescriptor + buildProviderConfig 泛化(glm-5.2/deepseek)+ ProviderRegistry;换模型改配置不改扩展 | +| T17 | `src/capabilities/{approval,credentials,settings,lsp}.ts` | 审批接缝(fail-closed 无人值守 auto-deny)+ CredentialsStore(env/memory 不落盘+redact) + SettingsStore typed + NoopLspBridge | + +公共 API 经 `src/index.ts` re-export(board-link/flash 具名避 shared/types 重名)。 + ## 测试 ```bash -npm test # vitest 全量单测(mock ExecFn,无需硬件) -npx tsc --noEmit # 对真 pi 源码类型检查 +npm test # vitest 全量单测(39 文件 2449 passed,mock ExecFn,无需硬件) +npx tsc --noEmit # 对真 pi 源码类型检查(0 错) +npx vitest run tests/system-integration.test.ts # 跨 10 模块闭环集成测试 ``` +测试方法论:等价类划分 / 边界值 / 决策表 / 状态转换 / **变异测试(每模块植入 3-9 seeded bug 必被杀)** / 对抗 fuzz / 元蜕变不变式。T06–T17 由 68 个 workflow agent 并行开发(dev+test+fix≤3 每,两层+barrier)。 + ## 设计取舍 -- **逻辑/扩展分离 + 测试前置**:纯逻辑内联进扩展文件并以命名导出,注入 mock `ExecFn` 单测,无需真实硬件即可严谨验证。这是 pi 自家 `coding-agent` 的同款分层。 -- **单一 barrel 装配**:pi 只加载 `src/extensions/index.ts` 一个扩展,它依次装配 21 个子扩展——最大化内聚,避免散装。 -- **fail-closed**:硬件判据默认拒绝/失败,不放过任何破坏性或不确定操作。 +- **逻辑/扩展分离 + 测试前置**:纯逻辑内联进扩展/核心库文件并以命名导出,注入 mock `ExecFn` 单测,无需真实硬件即可严谨验证。这是 pi 自家 `coding-agent` 的同款分层。 +- **单一 barrel 装配**:pi 只加载 `src/extensions/index.ts` 一个扩展,它依次装配 22 个子扩展——最大化内聚,避免散装。核心库层(T06–T17)是纯逻辑库,由 agent 层(`src/agent.ts`)按需 import,不进 barrel。 +- **fail-closed**:硬件判据默认拒绝/失败,不放过任何破坏性或不确定操作(devmem 硬门、approval auto-deny、registry resolve 未知即抛)。 +- **密钥铁律**:网关 key 一律 `${DROBOTICS_LLM_KEY}` 环境占位,绝不硬编码、不入库(`grep -rn sk-nAm src/` = 0)。 ## 已知局限 - `length-recovery` 的 `partitionToolCalls` 需 patch pi agent-loop 源码(pi 扩展 API 够不着),本扩展只做 prompt 注入兜底 + events 握手。 - 真板硬件侧集成(烧录/外设/物理信号)逻辑已单测,真 aarch64 板上端到端待跑。 +- T06–T17 核心库目前是纯逻辑库(已 1400+ 测试 + 系统集成测试验证接线),接进 pi agent 主循环(before_agent_start 调 assertModelVisibleLogged、session_before_compact 接 T09 等)是下一阶段集成工程,非阻塞。 +- T05b aarch64 真二进制需 toolchain 编译(源码+契约已就绪)。 diff --git a/架构设计文档_v3.md b/架构设计文档_v3.md index 50e9460..f6ce3db 100644 --- a/架构设计文档_v3.md +++ b/架构设计文档_v3.md @@ -772,10 +772,13 @@ T11(类型漂移) ──────────────────── ## 下一步动作 -1. **T05b aarch64 真二进制**:在有 aarch64-linux-musl-gcc 或 docker toolchain 的环境跑 `cd native/landlock-run && make cross-aarch64`,产物 `landlock-run-aarch64` 部署到板,`PBA_BOARD_SANDBOX_BINARY` 指向它即启用真 Landlock。源码+契约已就绪,缺的只是 toolchain。 +> 2026-08-14 更新:P1(T06–T11)+ P2(T12–T17)全部落地,M1/M2/M3 全 ✅。下列仅剩**环境依赖**项,非代码阻塞。 + +1. **T05b aarch64 真二进制**(唯一 P0 残留):在有 aarch64-linux-musl-gcc 或 docker toolchain 的环境跑 `cd native/landlock-run && make cross-aarch64`,产物 `landlock-run-aarch64` 部署到板,`PBA_BOARD_SANDBOX_BINARY` 指向它即启用真 Landlock。源码+契约已就绪,缺的只是 toolchain。 2. **T01 真 LLM 一轮 turn**(可选,需 key+网络):`bin/pba.ts` dist 分发需 `build:offline`(卡 `check:model-data`,需 `generate-models` 联网填 `providers/data/`);或直接用 vitest 源码别名跑一轮带 mock/真 key 的 agent turn。createAgentSession boot 已✅,差的只是真模型推理。 -3. **M1 启动**:T06 PbaSession + T07 PbaEventBus + T08 能力接缝(皆可离线并行启)。T04 的 stage ④⑤ 全 agent-loop wiring 依赖 T06/T07 落地后才能在 session/typed-event 层接 around/post/finalize。 -4. **T11 类型漂移门**:CI 定期对真 pi 源码 tsc,检测 `src/types/pi.d.ts` 镜像漂移。 +3. **CI 门上线**(T10 产出已就绪):`.github/workflows/ci.yml` 含 per-file 覆盖门 + doc-sync + type-drift-check;推到 GitHub 后即生效。本地 `scripts/type-drift-check.ts` 可手跑。 +4. **T04 stage ④⑤ 全 agent-loop wiring**(可选增强):pipeline 五段已实现+测试,stage①②已真 wired(safety-gate tool_call 钩子委托 `pipeline.decide()`);stage ④⑤(around/post/finalize 全 agent-loop 接线)需 pi 扩展 API 支持 tool_call 之外的钩子,待 pi 升级或 patch。 +5. **新核心库层的 agent-loop 接线**(可选):T06 PbaSession / T07 PbaEventBus / T13 ContextInjector / T14 CheckpointRecorder 目前是纯逻辑库(已 1400+ 测试 + 系统集成测试验证接线),接进 pi agent 主循环(before_agent_start 钩子调 assertModelVisibleLogged、session_before_compact 接 T09 等)是下一阶段集成工程,非阻塞。 ---