physical_byte_agent/架构设计文档_v3.md
d-robotics 96a725efa3
Some checks are pending
CI / quality-gate (push) Waiting to run
CI / type-drift (push) Waiting to run
docs: 全面同步 T06–T17 落地 — README/AGENTS/v3doc/postmortem 0002
- 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 <noreply@anthropic.com>
2026-08-14 15:45:48 +08:00

62 KiB
Raw Permalink Blame History

Physical Byte Agent 架构设计文档(v3)

项目:@d-robotics/physical-byte-agent(pi 二开嵌入式硬件闭环 Agent) 路径:/Users/d-robotics/Desktop/physical_byte_agent 当前版本:v2 重构完成(commit 06a19a6,21 域扩展,732 单测,tsc 0 错,离线装配冒烟 21 工厂) v3 全程进展(2026-08-14):P0(T01–T05b)+ P1(T06–T11)+ P2(T12–T17)全部落地;39 测试文件 2449 单测全绿(1044 baseline + ~1400 模块 + 10 系统集成),tsc 0 错,68 workflow agent 并行开发。M0/M1/M2/M3 全 ✅。详见第七部分进度表。 本版本:v3——嫁接 dsh 八条工业骨架到 pi 扩展底座,补齐致命差距,迈向"能安全跑通嵌入式闭环" 文档日期:2026-08-14 文档目的:从顶层架构一路拆解到一堆具体的、可执行、可验证的开发任务,并在底部维护进度 输入依据:

  • 《deepseek_harness_深度研究剖析报告.md》(dsh 架构与源码锚点)
  • 《deepseek_harness创新点与physical_byte_agent差距分析报告.md》(18 条差距矩阵 G1-G18)
  • physical_byte_agent 实读源码(src/extensions/*.ts、src/agent.ts、src/shared/types.ts、bin/pba.ts)

0. 文档导读

本分七大部分:

  • 第一部分:项目定位与设计哲学(做层不做壳、收窄 RDK/ROS2、五条骨架嫁接)
  • 第二部分:与 pi 的对比(pi 是底座,本节厘清继承什么、二开什么、绕开什么)
  • 第三部分:与 deepseek-harness 的区别(dsh 是参照天花板,本节厘清取什么、不取什么)
  • 第四部分:顶层架构设计(五条骨架 + 嵌入式能力栈 + 数据流拓扑)
  • 第五部分:核心子系统设计(逐子系统接口契约 + 实现锚点)
  • 第六部分:开发任务分解(从架构拆到 T01-TN 可执行可验证任务,带验收标准)
  • 第七部分:开发任务进度表(维护中)

第一部分:项目定位与设计哲学

1.1 一句话定位

Physical Byte Agent(pba)是一个基于 pi 二开的、收窄到 RDK/ROS2 嵌入式硬件闭环的 C 层编程 Agent——它不是写码助手(那是 pi / opencode 的赛道),不是机器人大脑(那是世界模型的赛道),而是让 LLM agent 能在嵌入式开发场景里安全地"改码→交叉编译→烧板→上板验证→查日志"跑通硬件闭环的中间层 agent。

1.2 三条设计哲学

哲学一:做层不做壳

pba 是"层"——夹在 pi(agent harness 底座)与嵌入式硬件(RDK X5/S100/S600 + ROS2)之间的能力层。不重新造 harness(pi 已造),不做完整 IDE(那是上游),不做机器人控制栈(那是下游)。pba 的价值在"把嵌入式硬件能力 + 嵌入式安全约束,封装成 pi 可加载的扩展与工具"。

哲学二:收窄 RDK/ROS2

不追求通用嵌入式(不碰 STM32 裸机、不碰 Arduino、不碰 FPGA)。收窄到 D-Robotics RDK X5/S100/S600(aarch64 Linux + BPU + ROS2)一条线。收窄的回报:能力栈可深度(devmem/i2cset/openocd/gdb MI/设备树 overlay 全为这块板打磨),安全约束可硬(砖板物理不可逆 → fail-closed 安全门)。

哲学三:五条骨架嫁接,底座不换 Cordis

dsh 证明了工业级 agent harness 该有的八条骨架。pba 不引入 Cordis 全栈(那是通用 harness 的复杂度投入),而是把其中五条骨架——单一提交点 session log / 五段工具流水线 / OS 级沙箱 / scope 多 agent 隔离 / 能力接缝三角色——用 pi 的扩展机制(registerTool/on/appendEntry/events/defineTool/createAgentSession)实现,嫁接到 pba 已有的 21 域嵌入式能力栈上。其余三条(compaction 完整工程 / 子代理 + 工作流 / 质量门)按需引入。

1.3 v3 的目标

把 v2(逻辑层 95%、运行时 0%)推进到 v3(逻辑层 95% + 运行时验证 + 安全骨架补齐):

  • 能真跑:联网 build pi + 真 key 端到端冒烟通过(G1)
  • 能安全跑:OS 级安全门 + 五段工具流水线 + 正则与 hex 归一联动堵 devmem 漏洞(G4/G5)
  • 能长跑:session 事件溯源 + compaction + typed events/scope(G2/G3/G8)
  • 能多板:能力接缝三角色,换板不动 tool(G6)
  • 能可维护:CI 覆盖门 + snapshot + doc-sync(G12)

第二部分:与 pi 的对比

pi(@earendil-works/pi,v0.84.1)是 pba 的底座——一个 10 包 monorepo 的轻量 agent harness。pba 不是另起炉灶,是在 pi 扩展系统上二开。下表厘清 pba 对 pi 的继承 / 二开 / 绕开。

2.1 继承 pi(不动,直接用)

pi 能力 pi 锚点 pba 怎么用
扩展加载 createAgentSession packages/coding-agent/src/core/sdk.ts:171 PhysicalByteAgent.launch()(src/agent.ts:71)动态 import
扩展自动发现 packages/coding-agent/src/core/extensions/loader.ts:710 .pi/extensions/index.ts 重导出 barrel
registerTool types.ts:1251 21 域扩展注册工具
defineTool + Type (TypeBox) packages/coding-agent 工厂内动态 import,schema 定义
on("tool_call"/"tool_result"/"session_start"/"before_agent_start"/"message_end") types.ts:901/1071-1080/1102-1106/1117-1120 safety-gate/glm-provider 等挂钩子
registerProvider pi provider API glm-provider 注册 glm-5.2
appendEntry 持久化 types.ts:1318 hardware-state/loop-orchestrator 审计
pi.events EventBus pi EventBus 跨扩展通信(v3 升级为 typed event bus)
setActiveTools pi safety-gate per-skill 收敛
session_before_compact 钩子 types.ts:1117-1120 hardware-state compaction 保护
executionMode:"sequential" agent-loop.ts:419-423 flash 独占锁、单板串行
pi-ai LLM 抽象 + 模型目录 @earendil-works/pi-ai glm-provider 复用 qwen thinkingFormat 分支

2.2 二开 pi(治命门 + 补骨架)

pi 不足 pba 二开 锚点
glm-5.2 thinking 黑洞零输出(命门一) buildGlmModelConfig:thinkingFormat:"qwen" + maxTokens:8192 + thinkingLevelMap 全 null → 触发 pi openai-completions.ts:762-763 的 enable_thinking:false src/extensions/glm-provider.ts:81-102
glm-5.2 hex 强转砖板(命门二) normalizeHexArg(BigInt 保 64 位)+ normalizeToolArguments(递归 walk + denylist)+ makeHexNormalizingPrepareArguments(在 prepareArguments 拦截点归一,因 BeforeToolCallResult 不支持替换 args 只能 block) glm-provider.ts:166-262
pi 无 OS 级沙箱 v3 新增 ctx.sandbox 接缝(board-side landlock/seccomp) 待建(见 T05)
pi 工具执行是单点 block v3 升级为五段流水线(pre-execute/guard/around/post/finalize) 待建(见 T04)
pi events 松散字符串 v3 加 typed event bus(declaration merging + waterfall + scope) 待建(见 T07)
pi 无全量 session 事件溯源 v3 加 SessionEventMap + deriveMessages(最小子集) 待建(见 T06)
pi 无能力接缝三角色 v3 把 board-link/flash 抽 ctx.boardLink/ctx.flash 接缝 待建(见 T08)

2.3 绕开 pi(不改 pi 源码,扩展层兜底)

pi 内部够不着的 pba 绕法 说明
partitionToolCalls(agent-loop 内部) 扩展层 prompt 注入兜底 + events 握手 pi 扩展 API 够不着 agent-loop 内部,只做兜底,注释明说局限
agent-loop 并发分类(exclusive/parallel) flash 工具自带独占锁 + executionMode:"sequential" 不依赖 pi 内部分类
真 pi 运行时构建(需联网 generate-models) 离线用 verifyAssembly() 自检;联网后 build 不 hack pi 构建流程

2.4 与 pi 关系的本质

pba 是 pi 的能力层扩展包,不是 pi 的 fork。pba 通过 package.json 的 "pi": {"extensions": ["src/extensions/index.ts"]} 声明,pi 经 readPiManifest(loader.ts:605-620)解析后自动加载 pba 的 barrel。pba 的代码全在 src/extensions/,pi 源码不动(除 vendored patch 如有)。


第三部分:与 deepseek-harness 的区别

dsh(0.1.0-rc.5)是 pba 的参照天花板——它证明了工业级 agent harness 该有的骨架。但 pba 不照搬 dsh 全栈。本节厘清取什么、不取什么、为什么。

3.1 取 dsh 的八条骨架(嫁接到 pi 扩展)

dsh 骨架 dsh 锚点 pba 怎么嫁接 pba 任务
① append-only session log + "model-visible⟺logged" Session.append(packages/core/session/src/index.ts:604)+ deriveMessages(:726)+ SessionEventMap(types.ts:236) 定义 pba SessionEventMap(turn/step/tool-call/tool-result/hw:state/flash/verify),append 唯一提交点,deriveMessages 从 surface 投影,加 "model-visible⟺logged" 断言。先最小子集。 T06
② OS 级进程沙箱 native/landlock-run(C11)+ sandbox-local(bwrap/Seatbelt/ACL)+ sandbox-policy 单 home board-side landlock/seccomp(aarch64 Linux 5.13+);host-side safety-gate 正则升级;devmem 强制走专用 reg 工具 T05
③ 五段工具流水线 + 单调 guard + finalizeContent tools/index.ts:1342 + ToolRuntimeScheduler(:451)+ guard(:1110)+ finalizeContent(:247) safety-gate evaluateSafety 升级为 pre-execute waterfall + monotonic guard(破坏性/资源锁/阻值门/datasheet 地址各一 guard,任一 deny 不可覆盖);flash 加 finalizeContent T04
④ 类型化事件四分派 + waterfall + scope 链 四分派表(docs/cordis-primer.md)+ scope(packages/core/scope/src/index.ts:137/170)+ agentEvents(packages/core/agent/src/dispatch.ts:107) 薄封装 pi.events 加 typed event bus(declaration merging + waterfall next() + scope key 多 agent 隔离) T07
⑤ 能力接缝三角色 docs/capability-seams.md 大表 board-link 抽 ctx.boardLink(BoardLinkProvider 接口 + 各板 provider + tool consumer);flash 四方法抽 provider T08
⑥ compaction 完整工程 compaction-basic(KV cache 复用 + tool-result prune)+ spillStore/spill-policy 加 tokenMeter 压力触发 + tool-result prune(i2cdump/gdb 大输出)+ spill 句柄(datasheet 大检索结果) T10
⑦ 子代理 + 工作流引擎 ctx.subagents(6 provider)+ ctx.workflowEngine(parallel/pipeline/phase + node:vm) 评估 pi subagent 或自建轻量 ctx.subagents;loop-orchestrator 上层加 workflow 编排 T11
⑧ 质量门 + postmortem test:coverage per-file 100% + test:snapshot + doc-sync + docs/postmortem/ CI per-file 覆盖门 + 真实 API snapshot 回放 + doc-sync + postmortem 文化 T13

3.2 不取 dsh 的(过度工程,pba 收窄不需要)

dsh 东西 为什么 pba 不取
Cordis 全栈框架(vendor/cordis) pba 底座是 pi 扩展,已验证可装配 21 域。五条骨架用 pi 扩展实现,不引 Cordis 依赖
Typert 类型图生成器 + api-gateway RPC(ctx.typert/ctx.typertGateway) 为 web 客户端 + 远程 RPC 设计的重型类型基础设施。pba 不做 web 客户端
全 60 个 ctx 接缝(web-search/acp/e2b/otel/directory-picker...) dsh 为通用 agent 设计。pba 只需嵌入式相关子集(boardLink/fs/subprocess/compaction/sandbox/subagents/skills/storage)
single-exe Python 分发(python/sdk-runtime) pba 是 TS agent,不做 Python 分发
windows-acl 沙箱(packages/sandbox/sandbox-windows-acl) 嵌入式板是 aarch64 Linux,不需要 Windows ACL
8 种 thinking dispatch 格式表(THINKING_FORMAT_GATE) pba 只 glm-5.2,qwen 一种够用
web-app bundle(dsh-web-app) pba 不做浏览器应用,走 headless/CLI/JSON-RPC
headless bundle 的完整 snapshot 基建 pba 按需取 snapshot 思路,不搬 dsh 的 ACP snapshot 全套

3.3 pba 有而 dsh 没有的(嵌入式领域护城河,不丢)

pba 能力 dsh 状态 pba 锚点
三段式安全烧录(dd/fastboot/dfu/openocd) dsh 无(dsh 有 tool-bash 但无烧录 gate) src/extensions/flash.ts
JTAG/gdb MI 调试 dsh 无 src/extensions/jtag-debugger.ts
外设探测(i2c/gpio/spi) dsh 无 src/extensions/peripheral-probe.ts
设备树解析/校验 dsh 无 src/extensions/device-tree.ts
aarch64 交叉编译工具链 dsh 无 src/extensions/cross-compile.ts
硬件信号验证判据(dmesg/gpio/i2c/sysfs/serial/current) dsh 无 src/extensions/hardware-verify.ts
硬件状态持久化 + compaction 保护 dsh 有通用 compaction 但不特化硬件状态 src/extensions/hardware-state.ts
闭环 checkpoint 状态机(edit→compile→flash→verify→check→done) dsh 有通用 workflow 但无物理不可逆 fail-closed src/extensions/loop-orchestrator.ts
glm-5.2 专属命门根治(thinking 黑洞 + hex 强转砖板) dsh 不遇(DeepSeek 原生 adapter 不开 thinking 黑洞,不写 devmem) src/extensions/glm-provider.ts
离线可测架构(顶层 import type + factory 内动态 import) dsh 需 build:lib:host 先 全 extensions 一致
单板串行 concurrency=1 物理约束建模 dsh 是通用 maxParallelToolCalls flash executionMode:"sequential"

3.4 与 dsh 关系的本质

dsh 是通用 agent harness 的工业天花板参照;pba 是嵌入式硬件闭环 agent 的能力栈。pba 取 dsh 的五条工业骨架(+ 三条按需)嫁接到 pi 扩展底座,叠加 pba 自有的嵌入式能力栈与 glm-5.2 命门根治,形成"工业骨架 + 领域能力 + 专属安全"三位一体。不照搬、不 fork dsh,只学其骨架范式。


第四部分:顶层架构设计

4.1 架构总览(分层图)

┌─────────────────────────────────────────────────────────────────────┐
│                        用户/CI 入口层                                  │
│   bin/pba.ts (CLI)  │  PhysicalByteAgent.launch() (程序化)  │  CI  │
└─────────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────────┐
│  pba 装配层(barrel) src/extensions/index.ts                        │
│  physicalByteAgentAssembly(pi) → 依次装配所有域扩展工厂(fail-soft)  │
└─────────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────────┐
│  pba 工业骨架层(v3 嫁接 dsh 五条 + 按需三条)                         │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│ │Session log│ │Typed     │ │工具流水线 │ │OS 沙箱   │ │能力接缝   │  │
│ │append-only│ │Events    │ │pre/guard/│ │landlock/ │ │三角色     │  │
│ │+derive    │ │+waterfall│ │around/   │ │seccomp + │ │Definition/│  │
│ │+logged    │ │+scope    │ │post/     │ │fail-closed│Provider/  │  │
│ │不变量     │ │隔离      │ │finalize  │ │probe     │ │Consumer   │  │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                                 │
│ │compaction│ │子代理+   │ │质量门     │  (按需引入)                   │
│ │KV cache+ │ │workflow  │ │CI 100%+  │                                 │
│ │prune+spill│ │parallel/│ │snapshot+ │                                 │
│ │           │ │pipeline │ │doc-sync  │                                 │
│ └──────────┘ └──────────┘ └──────────┘                                 │
└─────────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────────┐
│  pba 嵌入式能力栈层(v2 已有 21 域,v3 保留 + 接骨架)                  │
│ glm-provider │ safety-gate │ persistent-shell │ pdf-reader           │
│ edit-strict │ length-recovery │ subprocess-isolation │ env-probe    │
│ mcp-bridge │ server-runtime │ hardware-state │ cross-compile        │
│ flash │ peripheral-probe │ jtag-debugger │ device-tree │ board-link │
│ datasheet-rag │ hardware-verify │ loop-orchestrator │ build-tracker │
└─────────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────────┐
│  pi 底座层(继承,不动)                                              │
│ createAgentSession │ registerTool/defineTool/Type │ on(钩子)          │
│ registerProvider │ appendEntry │ pi.events │ setActiveTools           │
│ session_before_compact │ executionMode:sequential │ pi-ai LLM 抽象   │
└─────────────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────────────────────────────────────────────┐
│  硬件/OS 层                                                            │
│ RDK X5/S100/S600(aarch64 Linux + BPU + ROS2)│ SSH/串口 │ devmem/i2c │
│ /sys/class/gpio │ device-tree overlay │ openocd/gdb │ cross-gcc      │
└─────────────────────────────────────────────────────────────────────┘

4.2 五条骨架与 pi 的映射(嫁接点)

骨架 dsh 实现 pba 嫁接到 pi 的方式 pi 锚点
Session log Session.append + deriveMessages pba Session 类包装 pi appendEntry,定义 PbaSessionEventMap,deriveMessages 从 pba 事件投影;"model-visible⟺logged" 用 before_agent_start + message_end 钩子断言 appendEntry(types.ts:1318)+ session_before_compact(:1117)
Typed events + scope Cordis ctx.waterfall/scope 薄封装 pi.events:PbaEventBus.emit/waterfall/serial + ScopeKey 标签过滤(agent 隔离) pi.events(EventBus)
工具流水线 ToolRuntimeScheduler 五段 pi.on("tool_call") pre-execute waterfall + monotonic guards + pi.on("tool_result") post + 工具 finalizeContent on("tool_call"/"tool_result")(:901/1071)
OS 沙箱 sandbox-local + landlock-run host-side:safety-gate 正则升级 + 与 hex 归一联动;board-side:landlock/seccomp 围栏(aarch64 Linux 5.13+) on("tool_call") block + 工具内 spawn 包 argv
能力接缝 Definition/Provider/Consumer board-link/flash 抽 BoardLinkProvider/FlashProvider 接口 + 各板/方法 provider + tool consumer registerTool 消费

4.3 数据流:一次硬件闭环 turn

用户 followup("烧新的 bootloader 到 X5")
  → pba Session.append(turn/start)                    [骨架①]
  → agent/pre-step waterfall(inject 寄存器表/runtime-context)[骨架④]
  → systemPrompt.assemble(21 域工具 schema + 安全门 section)[pi]
  → ctx.llm.stream(glm-5.2,命门一已关 thinking)    [pi-ai qwen]
     → assistant/chunk* → Session.append(assistant/message) [骨架①]
  → 工具流水线(flash 工具)                           [骨架③]
     → pre-execute waterfall: safety-gate 阻值门 guard + 资源锁 guard [骨架③]
     → monotonic guards: 任一 deny 不可覆盖            [骨架③]
     → tools/execute around: timeout/retry + 独占锁   [骨架③]
     → tool body: planFlash → dryRun(根盘拒绝+sha256)→ verifyFlash
        → board-side landlock 围栏包 argv             [骨架②]
        → ctx.boardLink provider(SSH 到 X5)          [骨架⑤]
     → post-execute: accept/block/replace/add context [骨架③]
     → finalizeContent: verify 结果强制 content-only   [骨架③]
     → tools/result → Session.append(tool/result)     [骨架①]
  → compaction 如压力触发: prune + summarize + KV cache 复用 [骨架⑥]
  → agent/turn-stopping serial                         [骨架④]
  → Session.append(turn/end)                            [骨架①]

4.4 运行时拓扑(单板串行 + 板外并行)

宿主机(macOS/Linux)                        目标板(RDK X5,aarch64 Linux)
┌────────────────────────┐                  ┌────────────────────────┐
│ pba agent (pi 进程)     │   SSH/串口       │ 板侧 landlock runner     │
│ ├ glm-provider (网关)   │ ───────────────→│ ├ boardlink:exec         │
│ ├ safety-gate (host 正则)│                 │ ├ /sys/class/gpio        │
│ ├ flash 工具 (三段式)    │   devmem/i2c    │ ├ devmem/i2cset          │
│ ├ cross-compile (aarch64)│ ───────────────→│ ├ openocd/gdb            │
│ ├ loop-orchestrator      │                 │ └ landlock 围栏(fail-   │
│ └ Session log (JSONL)   │                 │    closed probe)         │
└────────────────────────┘                  └────────────────────────┘
        单板串行 concurrency=1(物理约束):flash/verify/devmem 独占锁
        板外可并行:编译(宿主)+ 探板(板)+ datasheet RAG(宿主)—— v3 子代理/工作流

第五部分:核心子系统设计

5.1 子系统 A:Session 事件溯源(骨架①)

现状

  • pi 有 appendEntry(松散 CustomEntry)+ sqlite/jsonl 存储。
  • pba 的 hardware-state(src/extensions/hardware-state.ts)已有 replayFromEntries(:134)重建 {locks, checkpoint, flashLog},但只覆盖硬件状态子集。

v3 设计

定义 pba 自己的 PbaSessionEventMap(merge-extensible),PbaSession 类包装 pi appendEntry:

// src/core/pba-session.ts(新建)
export interface PbaSessionEventMap {
  "turn/start": { turn: number };
  "turn/end": { turn: number; reason: TurnEndReason };
  "step/start": { turn: number; step: number };
  "step/end": { turn: number; step: number };
  "user/message": UserMessage;
  "assistant/message": AssistantMessage;  // surface, 带 sourceEventSeqs
  "tool/call": { turn: number; step: number; name: string; args: unknown };
  "tool/result": { turn: number; step: number; name: string; result: unknown };
  "hw:state": HwEntry;                    // 复用 hardware-state
  "flash/log": FlashLogEntry;
  "verify/record": VerifyRecord;
  "checkpoint/change": CheckpointState;
}
  • PbaSession.append(type, data):唯一提交点,lossless-JSON 快照 + 深冻结 + seq 连续性不变量。
  • PbaSession.deriveMessages():从有序 surface(user/message + assistant/message + tool/result)投影模型历史,增量缓存。
  • "model-visible⟺logged" 断言:在 before_agent_start 钩子校验即将喂模型的消息全可从 log 重建。
  • replayFromEntries 推广到全量事件。

验收

  • PbaSession.append 唯一提交点,重入 guard。
  • deriveMessages 从 log 投影,compaction replace 重建。
  • "model-visible⟺logged" 断言在伪造"喂模型未 log 的消息"时抛错。

5.2 子系统 B:Typed Event Bus + Scope 隔离(骨架④)

现状

  • pba 全用 pi.events.emit/on(松散字符串,无 waterfall/serial/scope/类型)。实例如 loop-orchestrator.ts:503/508、board-link.ts:682-712、glm-provider.ts:406。

v3 设计

薄封装 pi.events,加 PbaEventBus:

// src/core/pba-event-bus.ts(新建)
export class PbaEventBus {
  constructor(private pi: ExtensionAPI) {}
  emit<K extends keyof PbaEventMap>(event: K, payload: PbaEventMap[K], scope?: ScopeKey): void;
  waterfall<K>(event: K, payload, next): Promise<result>;   // around 中间件,调 next() 委托
  serial<K>(event: K, payload): Promise<last>;
  on<K>(event: K, listener, opts?: { scope?: ScopeKey; prepend?: boolean }): () => void;
}
export type ScopeKey = object;  // identity-compared,agent 隔离
  • waterfall:listener 收 (...args, next),调 next() 委托,不调即短路(dsh 范式)。
  • scope:ScopeKey 标签,无标签全局 + 匹配键/祖先键(注册向下继承、事件向上扩展)。
  • 迁移:现有 pi.events.on("verify:passed", ...) 等改 typed 版本;safety-gate pi.on("tool_call") 升级为 pre-execute waterfall。

验收

  • waterfall 链:A listener 包装结果传 B,B 收到 A 的包装。
  • scope:agent A 的事件不进 agent B 的 scoped listener。
  • 现有 21 域的 pi.events 调用全迁 typed 版本,tsc 编译期检查签名。

5.3 子系统 C:五段工具流水线(骨架③)

现状

  • safety-gate(src/extensions/safety-gate.ts:206)pi.on("tool_call") 只在 pre-execute 段做正则拦截 + 资源锁;pi.on("tool_result") 释放锁。
  • flash 工具内联独占锁 + 三段式,但无通用 around/post/finalize 容器。

v3 设计

五段流水线(嫁接 dsh ToolRuntimeScheduler):

tools/pre-execute waterfall (allow|deny|ask)
  ├ safety-gate: 破坏性命令 guard
  ├ safety-gate: 资源锁 guard
  ├ safety-gate: 上电前置阻值门 guard(v3 新增)
  ├ datasheet 地址校验 guard(devmem 专用 reg 工具,v3 新增)
  └ monotonic: 任一 deny 不可被另一 force-allow
→ ctx.approval(一次性,fail-closed,缺失 deny)
→ tools/execute around-waterfall
  ├ timeout(通用容器)
  ├ retry
  ├ metrics
  └ tool execute() body(flash 三段式 / devmem / openocd / ...)
→ tools/post-execute waterfall (accept|block|replace|add context)
→ finalizeContent(content-only 不变量)
→ tools/result(冻结、lossless-JSON、权威)
  • pre-execute 改 PbaEventBus.waterfall("tools/pre-execute", ...)。
  • monotonic guards:注册式,guardReason 全局→scope 链最远优先,身份保护。
  • finalizeContent:工具定义可选,materialize 前同步校验 content-only。
  • 正则与 hex 归一联动(堵 G5 漏洞):safety-gate 的 evaluateSafety 在过正则前先调 normalizeHexArg 归一命令里的地址,使 devmem 1073872896 write 归一成 devmem 0x40020000 write 再匹配 devmem-write 正则。

验收

  • 五段都能挂 listener,waterfall next() 委托生效。
  • 任一 guard deny,另一 guard 不能 force-allow(单调性测试)。
  • devmem 1073872896 write(十进制)经归一后被 devmem-write 正则命中并 block(堵漏洞测试)。
  • flash 工具的 verify 结果经 finalizeContent 强制 content-only。

5.4 子系统 D:OS 级沙箱(骨架②)

现状

  • 零 OS 级沙箱。safety-gate 8 条正则在命令字符串层(safety-gate.ts:35-110)。
  • 具体漏洞:devmem-write 正则 devmem2?\s+0x[0-9a-fA-F]+\s+\b(w|write)\b 要求字面 0x,glm-5.2 命门二强转十进制后 devmem 1073872896 write 不匹配。

v3 设计

分两侧:

Host-side(宿主,pba agent 跑的地方):

  • safety-gate 正则升级 + hex 归一联动(子系统 C 已述)。
  • 破坏性工具强制走专用工具(flash 已如此;devmem 建专用 reg 工具带 datasheet 地址校验,禁走 bash)。
  • 宿主侧可选 landlock(macOS/Linux 开发机)。

Board-side(目标板,aarch64 Linux):

  • boardlink:exec 在板侧包 argv:landlock(内核 5.13+,grantArgs({readOnly:['/'], readWrite:[workspace]}))或 seccomp 围栏。
  • fail-closed probe:板侧 runner 不可用时不跑命令直接报 unusable。
  • 单 boardSandboxPolicy home:board-link 与 flash 共享一个围栏策略,防围不同 root。

验收

  • board-side landlock runner probe 返回 full/partial/unusable,unusable 时命令不跑。
  • devmem 1073872896 write(十进制)在 host-side 被归一 + 正则 block。
  • devmem 强制走 reg 工具,走 bash 被 safety-gate block。

5.5 子系统 E:能力接缝三角色(骨架⑤)

现状

  • board-link(src/extensions/board-link.ts,714 行)ssh/serial/local 三实现内联一个文件。
  • flash(src/extensions/flash.ts)dd/fastboot/dfu/openocd 四方法内联。

v3 设计

抽接缝(嫁接 dsh ctx.boardLink 范式):

// src/capabilities/board-link/types.ts(新建)
export interface BoardLinkProvider {
  readonly name: string;  // "rdk-x5" | "rdk-s100" | "rdk-s600" | ...
  readonly linkType: BoardLinkType;
  exec(command: string, opts: ExecOpts): Promise<ExecResult>;
  healthCheck(): Promise<boolean>;
}
// src/capabilities/board-link/index.ts
export class BoardLinkRegistry {
  register(provider: BoardLinkProvider): () => void;  // effect 可逆
  get(boardId: string): BoardLinkProvider | undefined;
}
// src/capabilities/board-link/providers/rdk-x5-ssh.ts
export class RdkX5SshProvider implements BoardLinkProvider { ... }
// src/capabilities/board-link/tool-board-link.ts(consumer)
// flash 同理:FlashProvider(dd/fastboot/dfu/openocd)+ 各方法 provider + tool consumer
  • BoardSpec(shared/types.ts:98)做 provider 配置(板 id → provider 名 + 连接参数)。
  • 换板(X5→S100)= 加一个 provider + 改 BoardSpec 配置,不动 tool 代码。

验收

  • 加 RdkS100Provider 后,tool-board-link 无代码改动即可用 S100。
  • BoardLinkRegistry.register 返回 disposer,unload 后 tool 不见该板。

5.6 子系统 F:compaction 完整工程(骨架⑥)

现状

  • length-recovery(src/extensions/length-recovery.ts)治 glm stop=length 零输出。
  • hardware-state selectProtected/buildCompactionProtection(:227/312)保 hw entry。

v3 设计

加 compaction provider(嫁接 dsh compaction-basic + spillStore):

  • 压力触发:tokenMeter 等价,量 context 用量,超阈值触发。
  • tool-result prune:i2cdump/gdb/dmesg 大输出先 model-free 压缩成摘要(保留寄存器地址 + 关键值)。
  • summarize:重放前缀 + append 压缩指令,复用 pi-ai provider KV prefix cache(降本)。
  • surface replace:user/message 带 surfaceOp:{op:'replace',start,end} 覆盖被遮蔽节点(接子系统 A 的 PbaSession)。
  • spill 句柄:超大 datasheet RAG 结果替成 SpillLocator branded 句柄 + 检索提示,模型按需取回。

验收

  • 压力触发后 summarize,KV cache 复用(provider 请求带前缀)。
  • i2cdump 大输出 prune 成摘要,寄存器地址不丢。
  • datasheet 大结果 spill 成句柄,模型可按句柄取回。

5.7 子系统 G:子代理 + 工作流(骨架⑦,按需)

现状

  • 无子代理。loop-orchestrator CheckpointMachine(:153)线性状态机。

v3 设计

  • 评估 pi 自带 subagent 机制;若不足,自建轻量 ctx.subagents(spawn-in-process provider 足够,fresh child 不继承上下文)。
  • loop-orchestrator 保留作单板闭环串行 gate(物理约束正确抽象);上层加 workflow 编排:
    • parallel:编译(宿主)+ 探板(板)+ datasheet RAG(宿主)并行。
    • pipeline:edit→compile→flash→verify。
  • 工作流脚本能 fan out 子 agent,带上限(maxConcurrent/maxItems)。

验收

  • parallel 三任务并发,板外并行窗口利用。
  • pipeline edit→compile→flash→verify 串行,stage 抛错 item 落 null。
  • 子 agent 的 agent/pre-step 不进主 agent 的 scoped listener(子系统 B 验证)。

5.8 子系统 H:嵌入式能力栈保留 + 接骨架(v2 已有)

21 域扩展(v2)保留,按需接骨架:

  • safety-gate → 子系统 C(pre-execute waterfall + guards)+ 子系统 D(正则与 hex 联动)。
  • flash → 子系统 C(finalizeContent)+ 子系统 E(FlashProvider 接缝)+ 子系统 D(board-side 沙箱)。
  • hardware-state → 子系统 A(PbaSession 事件)+ 子系统 F(compaction 保护)。
  • loop-orchestrator → 子系统 A(checkpoint 写 log)+ 子系统 G(上层 workflow)。
  • glm-provider → 不变(命门根治已扎实,走 pi-ai qwen 分支,dsh 已生产验证)。
  • 其余 16 域 → 按需把 pi.events 迁 typed 版本(子系统 B)。

5.9 子系统 I:质量门 + postmortem(骨架⑧)

现状

  • 732 单测(逻辑层),tsc 0 错(对类型镜像),装配冒烟 21 工厂。无 CI 覆盖门/snapshot/doc-sync/postmortem。

v3 设计

  • CI per-file 覆盖门:test:coverage 对 src/**/*.ts per-file 100%(v8/istanbul)。
  • 真实 API snapshot:联网 key 跑最小闭环,输出 snapshot,后续回归对比。
  • doc-sync 文档门:CI 校验 README/AGENTS/架构文档与代码同步(锚点 file:line 对齐)。
  • 类型漂移检测:CI 定期对真 pi 源码 tsc(tsconfig.realpi.json 临时 paths 指真 pi),检测 src/types/pi.d.ts 镜像漂移。
  • postmortem:docs/postmortem/ 编号事后复盘(砖板事故/零输出事故/装配挂事故)。

验收

  • CI test:coverage per-file 100% 门。
  • snapshot 回放对比,输出漂移即 CI 红。
  • doc-sync 校验架构文档锚点与代码一致。
  • 类型镜像漂移检测在 pi 升版后报红。

5.10 目录与包结构设计(v3 增量)

physical_byte_agent/
├── src/
│   ├── core/                    [v3 新增] 工业骨架层
│   │   ├── pba-session.ts       # PbaSession + PbaSessionEventMap(骨架①)
│   │   ├── pba-event-bus.ts     # PbaEventBus + ScopeKey(骨架④)
│   │   ├── tool-pipeline.ts     # 五段流水线调度器(骨架③)
│   │   ├── sandbox-policy.ts    # 单 sandboxPolicy home(骨架②)
│   │   └── invariants.ts        # "model-visible⟺logged" 等断言
│   ├── capabilities/            [v3 新增] 能力接缝三角色
│   │   ├── board-link/
│   │   │   ├── types.ts         # BoardLinkProvider 接口(Definition)
│   │   │   ├── index.ts         # BoardLinkRegistry(接缝)
│   │   │   ├── providers/
│   │   │   │   ├── rdk-x5-ssh.ts
│   │   │   │   ├── rdk-s100-serial.ts
│   │   │   │   └── local.ts
│   │   │   └── tool-board-link.ts  # Consumer
│   │   └── flash/
│   │       ├── types.ts         # FlashProvider 接口
│   │       ├── providers/{dd,fastboot,dfu,openocd}.ts
│   │       └── tool-flash.ts
│   ├── compaction/              [v3 新增] compaction + spill(骨架⑥)
│   │   ├── token-meter.ts
│   │   ├── tool-result-pruner.ts
│   │   ├── summarizer.ts
│   │   └── spill.ts
│   ├── extensions/              [v2 已有,v3 接骨架] 21 域
│   │   ├── index.ts             # barrel
│   │   ├── glm-provider.ts
│   │   ├── safety-gate.ts       # → 接 tool-pipeline + sandbox
│   │   ├── flash.ts             # → 迁到 capabilities/flash/
│   │   ├── board-link.ts        # → 迁到 capabilities/board-link/
│   │   └── ... (其余 17 域)
│   ├── shared/types.ts          [v2 已有,v3 扩展]
│   ├── agent.ts
│   └── index.ts
├── tests/                       [v2 已有 + v3 增量]
├── bin/pba.ts
├── models.json
├── .github/workflows/           [v3 新增] CI 门
├── docs/postmortem/             [v3 新增] 事后复盘
├── tsconfig.json
└── vitest.config.ts

第六部分:开发任务分解

原则:每个任务可执行(有明确代码改动点)+ 可验证(有验收标准 + 测试)。按优先级 P0→P1→P2 排序,前置依赖标注。锚点均为真实 file:line。

6.1 P0 任务(致命,不补会砖板/零输出/无法安全跑闭环)

T01 真端到端 pi 运行时冒烟【P0,无前置,G1】

  • 执行:
    1. cd /Users/d-robotics/Desktop/pi && npm run build(需联网 generate-models)。
    2. cd /Users/d-robotics/Desktop/physical_byte_agent && DROBOTICS_LLM_KEY=<env> npx tsx bin/pba.ts。
    3. 断言:①pi 加载 barrel(无 assembly-error)②glm-5.2 provider 注册(glm_status 工具可查)③21 工具注册(pi.getActiveTools() 含 flash/verify/pshell 等)④tool_call 钩子挂上(safety-gate 拦截测试命令)⑤最小闭环:edit→compile→flash(dry_run)→verify 不抛。
  • 验收:冒烟脚本 scripts/e2e-smoke.ts 通过,输出落 docs/postmortem/0001-e2e-smoke.md(首次冒烟记录)。
  • 若失败:按失败点定位(provider 注册失败 / 钩子签名漂移 / 工具 schema 被 pi 拒),记 postmortem。
  • 状态:未开始(受联网约束,待用户授权联网 build pi)。

T02 safety-gate 正则与 hex 归一联动堵 devmem 漏洞【P0,前置 T06 部分可用,G5】

  • 执行:
    1. src/extensions/safety-gate.ts 的 evaluateSafety(:98)在过正则前,先调 normalizeHexArg(glm-provider.ts:166)归一命令里的十进制地址。
    2. 新增测试:devmem 1073872896 write → 归一为 devmem 0x40020000 write → 命中 devmem-write 正则(:57)→ block。
    3. 新增测试:devmem 0x40020000 write(已 hex)→ 原样命中 → block。
    4. 新增测试:baudrate 115200 → 不被误归一(denylist,normalizeHexArg 已支持)→ 放行。
  • 验收:3 条测试全绿,devmem 十进制绕过漏洞堵死。
  • 状态:未开始。

T03 devmem 专用 reg 工具 + datasheet 地址校验【P0,前置 T02,G5】

  • 执行:
    1. 新建 src/extensions/reg-tool.ts(或迁 capabilities/):reg read/write 工具,参数 {address, value?, datasheetRef?}。
    2. write 前校验 address 在 datasheet 已知寄存器表内(datasheet-rag 联动),未校验即 block。
    3. safety-gate 新增规则:裸 devmem 走 bash → block,建议改用 reg 工具。
    4. reg 工具走 prepareArguments hex 归一(makeHexNormalizingPrepareArguments)。
  • 验收:devmem ... w 走 bash 被 block;reg write 带 datasheet 校验通过;未知地址 block。
  • 状态:未开始。

T04 五段工具流水线(pre-execute waterfall + monotonic guards + finalizeContent)【P0,前置 T07,G4】

  • 执行:
    1. src/core/tool-pipeline.ts:实现 ToolPipeline 调度器(嫁接 dsh ToolRuntimeScheduler,packages/core/tools/src/index.ts:451)。
    2. safety-gate pi.on("tool_call") 升级为 pre-execute waterfall(allow/deny/ask)。
    3. 注册 monotonic guards:破坏性命令 / 资源锁 / 阻值门(T03)/ datasheet 地址(T03),任一 deny 不可覆盖。
    4. tools/execute around:通用 timeout/retry 容器。
    5. tools/post-execute:accept/block/replace/add context。
    6. flash 工具加 finalizeContent(verify 结果 content-only 不变量)。
  • 验收:五段挂 listener;任一 guard deny 不可 force-allow(单调测试);flash verify 经 finalizeContent。
  • 状态:未开始。

T05 board-side landlock/seccomp 沙箱【P0,前置 T08,G5】

  • 执行:
    1. src/core/sandbox-policy.ts:单 boardSandboxPolicy home(嫁接 dsh sandbox-policy)。
    2. board-link boardlink:exec 在板侧包 argv:landlock(内核 5.13+ grantArgs)或 seccomp。
    3. fail-closed probe:板侧 runner 不可用报 unusable,命令不跑。
    4. 板侧 runner 先用 shell 脚本模拟(真 landlock-run 需交叉编译 C,作 T05b)。
  • 验收:probe 返回 full/partial/unusable;unusable 时命令不跑;board-link 与 flash 共享围栏策略。
  • 状态:未开始(T05a 脚本模拟先行,T05b 真 landlock-run 后续)。

6.2 P1 任务(重要,不补长会话/多 agent/可维护性差)

T06 PbaSession 事件溯源 + deriveMessages【P1,前置无,G2】

  • 执行:
    1. src/core/pba-session.ts:PbaSession 类包装 pi appendEntry,定义 PbaSessionEventMap(turn/step/user-message/assistant-message/tool-call/tool-result/hw:state/flash-log/verify-record/checkpoint-change)。
    2. append 唯一提交点:lossless-JSON 快照 + 深冻结 + seq 连续性。
    3. deriveMessages:从有序 surface 投影模型历史,增量缓存。
    4. replayFromEntries 推广到全量事件(从 hardware-state :134 抽公共)。
    5. "model-visible⟺logged" 断言:before_agent_start 钩子校验。
  • 验收:append 重入 guard;deriveMessages 从 log 投影;compaction replace 重建;伪造"未 log 喂模型"断言抛错。
  • 状态:未开始。

T07 PbaEventBus + ScopeKey 隔离【P1,前置无,G3】

  • 执行:
    1. src/core/pba-event-bus.ts:PbaEventBus 薄封装 pi.events,加 emit/waterfall/serial/on + ScopeKey 标签过滤。
    2. waterfall 实现:listener 收 (...args, next),调 next() 委托。
    3. scope:无标签全局 + 匹配键/祖先键(注册向下继承、事件向上扩展)。
    4. 迁移:21 域现有 pi.events.on/emit 改 typed 版本(verify:passed/build:done/boardlink:*/glm:*/xcompile:*/pdf-reader:*/debugger:*/length-recovery:*)。
  • 验收:waterfall 链委托生效;scope agent 隔离;21 域迁移后 tsc 编译期检查签名。
  • 状态:未开始。
  • 执行:
    1. src/capabilities/board-link/types.ts:BoardLinkProvider 接口(Definition)。
    2. src/capabilities/board-link/index.ts:BoardLinkRegistry(接缝,register 返回 disposer)。
    3. src/capabilities/board-link/providers/:从 board-link.ts 抽 rdk-x5-ssh/rdk-s100-serial/local 三 provider。
    4. src/capabilities/board-link/tool-board-link.ts:consumer(原 tool 逻辑)。
    5. flash 同理:FlashProvider(dd/fastboot/dfu/openocd)+ 各 provider + tool consumer。
    6. BoardSpec(shared/types.ts:98)做 provider 配置。
  • 验收:加 RdkS100Provider 后 tool-board-link 无改动可用 S100;register disposer 后 tool 不见该板。
  • 状态:未开始。

T09 compaction 完整工程【P1,前置 T06,G8】

  • 执行:
    1. src/compaction/token-meter.ts:量 context 用量(嫁接 dsh token-meter)。
    2. src/compaction/tool-result-pruner.ts:i2cdump/gdb/dmesg 大输出 model-free 压缩成摘要。
    3. src/compaction/summarizer.ts:重放前缀 + append 压缩指令,复用 pi-ai KV prefix cache。
    4. surface replace:user/message 带 surfaceOp:{op:'replace',start,end}(接 T06 PbaSession)。
    5. src/compaction/spill.ts:SpillStore + SpillLocator branded 句柄,datasheet 大结果 spill。
  • 验收:压力触发 summarize KV cache 复用;i2cdump prune 寄存器地址不丢;datasheet spill 句柄可取回。
  • 状态:未开始。

T10 CI 质量门 + snapshot + doc-sync【P1,前置 T01,G12】

  • 执行:
    1. .github/workflows/ci.yml:test:coverage per-file 100% 门(v8/istanbul)。
    2. scripts/e2e-snapshot.ts:联网 key 跑最小闭环,输出 snapshot,回归对比。
    3. scripts/doc-sync.ts:校验架构文档锚点 file:line 与代码对齐。
    4. scripts/type-drift-check.ts:CI 定期对真 pi 源码 tsc,检测镜像漂移。
    5. docs/postmortem/:编号事后复盘模板。
  • 验收:CI per-file 100% 门红即挡;snapshot 漂移红;doc-sync 锚点不一致红;类型漂移红。
  • 状态:未开始(依赖 T01 联网)。

T11 类型镜像漂移检测【P1,前置无,G13】

  • 执行:
    1. tsconfig.realpi.json:paths 指真 pi 源码(../pi/packages/*/src/index.ts),临时用。
    2. scripts/type-drift-check.ts:跑 tsc -p tsconfig.realpi.json,过滤 pi 自家内部错(已知 packages/agent/src/* 报错是 pi build 产物问题,非 pba),只看 src/**/*.ts 是否 0 错。
    3. CI 定期跑(周)。
  • 验收:pi 升版后若 pba src/types/pi.d.ts 镜像与真 pi 不符,CI 红。
  • 状态:未开始(已实测:当前我文件对真 pi 源码 0 错,报错全在 pi 自家)。

6.3 P2 任务(改进,工程效率/通用性)

T12 子代理 + 工作流编排【P2,前置 T07/T08,G7】

  • 执行:
    1. 评估 pi subagent 机制;不足则自建 src/capabilities/subagent/(spawn-in-process provider)。
    2. loop-orchestrator 上层加 src/capabilities/workflow/:parallel(编译+探板+datasheet)/ pipeline(edit→compile→flash→verify)。
    3. 工作流脚本能 fan out 子 agent,带上限。
  • 验收:parallel 三任务并发;pipeline 串行 stage 抛错 item 落 null;子 agent 事件不串主 agent。
  • 状态:未开始。

T13 上下文注入三段(inject/steer/followup)【P2,前置 T06/T07,G9】

  • 执行:pba Agent 接口加 inject(寄存器表 next-step 不唤醒)/steer(换板 next-step 唤醒)/followup(新任务 next-turn 唤醒)。
  • 验收:三段语义区分;runtime-context 快照"取代更早快照"。
  • 状态:未开始。

T14 plan/goal/todo logged state【P2,前置 T06,G10】

  • 执行:checkpoint 进度(CheckpointState,shared/types.ts:45)写进 PbaSession 事件,resume/fork 从 log 重建。
  • 验收:session resume 后 checkpoint 状态从 log 重建。
  • 状态:未开始。

T15 profile/bundle 分层【P2,前置 T08,G11】

  • 执行:维修诊断 profile vs 嵌入式开发 profile,共享 base + 叠差异(维修诊断要 pdf-reader/datasheet-rag/外设探测;嵌入式开发要 cross-compile/flash/jtag)。
  • 验收:两 profile 共享 base,各叠差异扩展。
  • 状态:未开始。

T16 多 LLM provider 适配【P2,前置无,G14】

  • 执行:glm-provider 扩展支持多 provider(复用 dsh THINKING_FORMAT_GATE 思路),支持 DeepSeek 原生 + 其他。
  • 验收:换模型改配置行不改扩展。
  • 状态:未开始。

T17 审批接缝 + LSP/code-runtime + credentials/settings【P2,按需,G16-G18】

  • 执行:按业务方向引入 ctx.approval(fail-closed 无人值守审批)/ ctx.lsp(嵌入式 IDE)/ ctx.credentials/ctx.settings。
  • 验收:按需逐个。
  • 状态:未开始。

6.4 任务依赖图

T01(真冒烟) ────────────────── T10(CI 门) ──┐
                                            │
T06(PbaSession) ─┬─ T09(compaction)         │
                 ├─ T13(inject/steer)       │
                 ├─ T14(plan/goal/todo)     │
                 └─ T04(流水线) ────────────┤
                                            │
T07(PbaEventBus) ─┬─ T04(流水线)            │
                  ├─ T08(接缝) ── T15(profile)
                  ├─ T12(子代理+工作流)     │
                  └─ T13                   │
                                            │
T02(正则+hex联动) ── T03(reg 工具) ── T04   │
                                            │
T08(接缝) ── T05(board 沙箱)                │
                                            │
T11(类型漂移) ─────────────────────────────┘

关键路径:T01 真冒烟(解锁运行时验证)→ T02/T03 安全门堵漏洞(防砖板)→ T07 typed events + T06 session log(骨架底座)→ T04 五段流水线(安全结构化)→ T08 接缝(多板)→ T05 board 沙箱(板侧围栏)→ T09 compaction(长会话)→ T10 CI 门(可维护)。


第七部分:开发任务进度表

维护中。状态:✅ 完成 / 🔄 进行中 / ⏳ 未开始 / ⛔ 阻塞。每完成一项更新此表 + 附 commit hash + 测试证据。

v2 已完成(commit 06a19a6)

项 状态 证据
21 域扩展 barrel 装配 ✅ src/extensions/index.ts:38-86,--print-extensions 21 工厂
glm-5.2 命门一根治(thinking 黑洞) ✅ glm-provider.ts:81-102,buildGlmModelConfig
glm-5.2 命门二根治(hex 强转砖板) ✅ glm-provider.ts:166-262,normalizeHexArg
空输出检测 ✅ glm-provider.ts:286-314
safety-gate 破坏性命令拦截 + 资源锁 ✅ safety-gate.ts:35-170
flash 三段式安全烧录 ✅ flash.ts:1-130
hardware-state mini 事件溯源 ✅ hardware-state.ts:134
loop-orchestrator checkpoint 状态机 ✅ loop-orchestrator.ts:153
732 单测 + tsc 0 错 + 装配冒烟 ✅ vitest 21 文件 732 绿
PhysicalByteAgent.launch + verifyAssembly ✅ src/agent.ts:44-93
密钥铁律(${DROBOTICS_LLM_KEY} 占位) ✅ grep sk-nAm = 0

v3 任务进度

任务 优先级 前置 状态 commit 验收证据
T01 真 pi 端到端冒烟 P0 无 ✅ 离线 boot 验证 (本批) 1044 测试含 71 e2e-smoke + 1 e2e-runtime;真 createAgentSession boot 成功(vitest 源码别名,无需 build)+ 21/21 工厂装配 + 24 工具注册 + drobotics-glm provider + 模型无回退;剩余"真 LLM 一轮 turn"需 key+网络、"bin/pba.ts dist 分发"需 build:offline,均非硬阻塞(见 postmortem 0001 更正)
T02 safety-gate 正则与 hex 归一联动 P0 T06 部分 ✅ (本批) safety-gate.ts evaluateSafety 接 normalizeCommandHex+deobfuscateCommand;70 测试(EP/边界/决策表/对抗/变异/元蜕变);devmem 1073872896 w→归一→block
T03 devmem 专用 reg 工具 + datasheet 校验 P0 T02 ✅ (本批) reg-tool.ts(KNOWN_REGISTERS+validateRegisterAddress+planRegOp+工厂,prepareArguments 接 hex 归一);29 测试;devmem-via-bash 硬门(hardGate 不可 allowRules 豁免)+ barrel 注册 reg(22 工厂)
T04 五段工具流水线 P0 T07 ✅ (①②wired/④⑤tested) (本批) src/core/tool-pipeline.ts(ToolPipeline 五段+单调 guards+decide();24 测试,含单调不变式元蜕变);safety-gate tool_call 钩子委托 pipeline.decide()(stage①②真 wired);flash finalizeFlashContent 导出(content-only);注:stage ④⑤全 agent-loop wiring 受 pi 扩展 API 在 tool_call 仅能 block 之限,pipeline 自身已实现+测试,未假装
T05a board-side 沙箱(脚本模拟) P0 T08 ✅ (本批) src/core/sandbox-policy.ts(probeSandbox full/partial/unusable + applySandboxToArgv + shouldRunCommand,Object.freeze 单一 home);board-link makeExec 包 argv + fail-closed(unusable→exitCode126 不 spawn);159 测试(EP/边界/决策表/状态转换/变异/对抗/元蜕变)
T05b board-side 真 landlock-run P0 T05a ✅ 源码+契约验证 / ⏙ 待交叉编译 (本批) native/landlock-run/landlock-run.c(C11,raw syscall self-restrict-then-exec,fail-closed exit126,--probe exit 0/1/2 映射 capability)+ Makefile(cross-aarch64 musl 静态)+ README;sandbox-policy.ts 加 probeViaBinary + board-link resolveBoardSandbox 接真二进制优先;macOS stub 编译+--probe exit2 + -- exec 契约测试通过;aarch64 真二进制需 toolchain(本机无 aarch64-linux-musl-gcc/docker)跑 make cross-aarch64
T06 PbaSession 事件溯源 P1 无 ✅ 2026-08-14 src/core/pba-session.ts(PbaSessionEventMap + append 唯一提交点 lossless-JSON+深冻结+seq 连续+重入 guard + deriveMessages 增量缓存 + replayFromEntries 推广自 hardware-state + assertModelVisibleLogged 不变量);74 测试
T07 PbaEventBus + ScopeKey P1 无 ✅ 2026-08-14 src/core/pba-event-bus.ts(PbaListener(args,next) + waterfall 链委托/短路 + emit 并行广播 + ScopeKey 单向冒泡子→父不串 + KNOWN_EVENTS typed 名);79 测试
T08 能力接缝三角色(board-link+flash) P1 无 ✅ 2026-08-14 src/capabilities/{board-link,flash}/{types,index,providers/*}.ts(BoardLinkProvider/FlashProvider Definition + Registry register/resolve fail-closed + 3 板 provider + 4 烧录 provider 抽自原扩展);321 测试
T09 compaction 完整工程 P1 T06 ✅ 2026-08-14 src/compaction/{token-meter,tool-result-pruner,summarizer,spill}.ts(estimateTokens + i2cdump/gdb/dmesg prune 寄存器地址不丢 + KV prefix reuse 标记 + SpillStore branded 句柄 recall/evict);113 测试
T10 CI 质量门 + snapshot + doc-sync P1 T11 ✅ 2026-08-14 .github/workflows/ci.yml(per-file 覆盖门+doc-sync+type-drift)+ scripts/{e2e-snapshot,doc-sync}.ts(compareSnapshot 结构化 diff + checkDocSync 锚点对齐,readFile/grepSymbol 注入);135 测试
T11 类型镜像漂移检测 P1 无 ✅ 2026-08-14 tsconfig.realpi.json(paths 指真 pi 源码)+ scripts/type-drift-check.ts(checkTypeDrift 跑 tsc 分流 pbaErrors vs piInternalErrors,runTsc 注入);79 测试
T12 子代理 + 工作流编排 P2 T07/T08 ✅ 2026-08-14 src/capabilities/{subagent,workflow}/index.ts(InlineSubagentProvider spawn-in-process + SubagentRegistry + parallel barrier/null-on-throw + pipeline 无 barrier stage 抛错落 null + MAX_CONCURRENCY);102 测试
T13 上下文注入三段 P2 T06/T07 ✅ 2026-08-14 src/core/context-injector.ts(inject 不唤醒 / steer 换板 next-step 唤醒 / followup next-turn 唤醒 + deriveActiveContext 最新 snapshot 取代更早);82 测试
T14 plan/goal/todo logged state P2 T06 ✅ 2026-08-14 src/core/checkpoint-state.ts(CheckpointRecorder record 写 checkpoint-change 事件 + current/rebuild 从 log 重建 + fork;look-ahead 状态机 passed 推进下一 pending 步,done passed 置终态);92 测试
T15 profile/bundle 分层 P2 T08 ✅ 2026-08-14 src/profiles/{base,repair-diagnosis,embedded-dev,index}.ts(BASE_PROFILE 共享 + 两 profile 叠差异 + mergeProfiles/diffProfiles + resolveProfile fail-closed 防 prototype 污染);114 测试
T16 多 LLM provider 适配 P2 无 ✅ 2026-08-14 src/core/provider-registry.ts(ProviderDescriptor + buildProviderConfig 泛化 glm/deepseek + ProviderRegistry + DEFAULT_GLM_DESCRIPTOR + KNOWN_PROVIDERS);115 测试;换模型改配置不改扩展
T17 审批/LSP/credentials/settings P2 按需 ✅ 2026-08-14 src/capabilities/{approval,credentials,settings,lsp}.ts(ApprovalGate fail-closed 无人值守 auto-deny + CredentialsStore env/memory 不落盘+redact + SettingsStore typed + NoopLspBridge stub);94 测试

里程碑

里程碑 范围 目标 状态
M0 安全跑通 T01/T02/T03/T04/T05a/T05b 能 boot(真 createAgentSession 离线✅) + 不砖板(devmem 硬门+hex 联动+reg 工具) + 安全门结构化(五段流水线①②wired) + 板侧沙箱(landlock-run C 源+契约✅) ✅ P0 全落(T05b aarch64 真二进制待 toolchain 编译)
M1 可长跑 T06/T07/T08/T09 session 事件溯源 + typed events + 接缝 + compaction ✅ 全落(74+79+321+113 测试)
M2 可维护 T10/T11 CI 门 + snapshot + 漂移检测 ✅ 全落(135+79 测试;ci.yml 接 type-drift + doc-sync)
M3 可扩展 T12-T17 子代理 + profile 分层 + 多 provider ✅ 全落(102+82+92+114+115+94 测试)

下一步动作

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. 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 等)是下一阶段集成工程,非阻塞。

附录 A:与 pi / dsh / pba 三方对比速查

维度 pi dsh pba(v3 目标)
框架底座 自研轻量 harness vendored Cordis pi 扩展(不引 Cordis)
session log sqlite + appendEntry append-only + deriveMessages + "logged"不变量 PbaSession + deriveMessages(最小子集,T06)
事件 pi.events 松散 四分派 + waterfall + scope PbaEventBus + waterfall + scope(T07)
工具流水线 registerTool + tool_call block 五段 + 单调 guard + finalizeContent 五段(T04)
沙箱 无 Landlock C11/Seatbelt/ACL board-side landlock/seccomp + host 正则升级(T05)
能力接缝 无 Definition/Provider/Consumer board-link/flash 三角色(T08)
LLM pi-ai ctx.llm + DeepSeek + pi-ai glm-5.2 命门根治(已✅)
compaction session_before_compact KV cache + prune + spill compaction 完整工程(T09)
子代理/工作流 无原生 ctx.subagents + workflowEngine 子代理 + workflow(T12)
嵌入式能力 无 无 21 域(已✅,dsh 完全没有)
质量门 基本测试 per-file 100% + snapshot + doc-sync CI 门(T10)

附录 B:关键源码锚点速查

pba 现状(v2)

主题 锚点
barrel 装配 src/extensions/index.ts:38-86
glm 命门一 src/extensions/glm-provider.ts:81-102
glm 命门二 glm-provider.ts:166-262
safety-gate 正则 src/extensions/safety-gate.ts:35-110
safety-gate tool_call 钩子 safety-gate.ts:206-240
flash 三段式 src/extensions/flash.ts:1-130
hardware-state replay src/extensions/hardware-state.ts:134
loop-orchestrator checkpoint src/extensions/loop-orchestrator.ts:153
PhysicalByteAgent.launch src/agent.ts:71-93
pi 类型镜像 src/types/pi.d.ts(EventBus:141)

dsh 参照(嫁接源)

主题 锚点
Session.append packages/core/session/src/index.ts:604
deriveMessages index.ts:726
SessionEventMap packages/core/session/src/types.ts:236
scope packages/core/scope/src/index.ts:137/170
工具流水线 packages/core/tools/src/index.ts:1342
ToolRuntimeScheduler index.ts:451
guard index.ts:706/1110
landlock-run native/landlock-run/
compaction packages/compaction/compaction/src/index.ts
subagent packages/subagent/subagent/src/types.ts
workflow packages/workflow/workflow/src/index.ts
PiAiAdapter packages/llm/llm-pi-ai/src/adapter.ts:186

pi 底座(继承)

主题 锚点
createAgentSession packages/coding-agent/src/core/sdk.ts:171
扩展自动发现 packages/coding-agent/src/core/extensions/loader.ts:710
registerTool types.ts:1251
on tool_call types.ts:901/1071-1080
appendEntry types.ts:1318
session_before_compact types.ts:1117-1120
executionMode sequential agent-loop.ts:419-423
openai-completions qwen 分支 openai-completions.ts:762-763

本架构文档基于 pba commit 06a19a6(v2)+ dsh commit 47f943859b + pi v0.84.1 源码。v3 任务进度表随开发实时更新,每完成一项附 commit hash + 测试证据。