- 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>
62 KiB
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-gatepi.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。 - 单
boardSandboxPolicyhome: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 结果替成
SpillLocatorbranded 句柄 + 检索提示,模型按需取回。
验收
- 压力触发后 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/**/*.tsper-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:coverageper-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】
- 执行:
cd /Users/d-robotics/Desktop/pi && npm run build(需联网 generate-models)。cd /Users/d-robotics/Desktop/physical_byte_agent && DROBOTICS_LLM_KEY=<env> npx tsx bin/pba.ts。- 断言:①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】
- 执行:
src/extensions/safety-gate.ts的evaluateSafety(:98)在过正则前,先调normalizeHexArg(glm-provider.ts:166)归一命令里的十进制地址。- 新增测试:
devmem 1073872896 write→ 归一为devmem 0x40020000 write→ 命中devmem-write正则(:57)→ block。 - 新增测试:
devmem 0x40020000 write(已 hex)→ 原样命中 → block。 - 新增测试:
baudrate 115200→ 不被误归一(denylist,normalizeHexArg已支持)→ 放行。
- 验收:3 条测试全绿,
devmem十进制绕过漏洞堵死。 - 状态:未开始。
T03 devmem 专用 reg 工具 + datasheet 地址校验【P0,前置 T02,G5】
- 执行:
- 新建
src/extensions/reg-tool.ts(或迁capabilities/):reg read/write工具,参数{address, value?, datasheetRef?}。 - write 前校验
address在 datasheet 已知寄存器表内(datasheet-rag 联动),未校验即 block。 - safety-gate 新增规则:裸
devmem走 bash → block,建议改用reg工具。 reg工具走prepareArgumentshex 归一(makeHexNormalizingPrepareArguments)。
- 新建
- 验收:
devmem ... w走 bash 被 block;reg write带 datasheet 校验通过;未知地址 block。 - 状态:未开始。
T04 五段工具流水线(pre-execute waterfall + monotonic guards + finalizeContent)【P0,前置 T07,G4】
- 执行:
src/core/tool-pipeline.ts:实现ToolPipeline调度器(嫁接 dshToolRuntimeScheduler,packages/core/tools/src/index.ts:451)。- safety-gate
pi.on("tool_call")升级为pre-executewaterfall(allow/deny/ask)。 - 注册 monotonic guards:破坏性命令 / 资源锁 / 阻值门(T03)/ datasheet 地址(T03),任一 deny 不可覆盖。
tools/executearound:通用 timeout/retry 容器。tools/post-execute:accept/block/replace/add context。- flash 工具加
finalizeContent(verify 结果 content-only 不变量)。
- 验收:五段挂 listener;任一 guard deny 不可 force-allow(单调测试);flash verify 经 finalizeContent。
- 状态:未开始。
T05 board-side landlock/seccomp 沙箱【P0,前置 T08,G5】
- 执行:
src/core/sandbox-policy.ts:单boardSandboxPolicyhome(嫁接 dshsandbox-policy)。- board-link
boardlink:exec在板侧包 argv:landlock(内核 5.13+grantArgs)或 seccomp。 - fail-closed probe:板侧 runner 不可用报
unusable,命令不跑。 - 板侧 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】
- 执行:
src/core/pba-session.ts:PbaSession类包装 piappendEntry,定义PbaSessionEventMap(turn/step/user-message/assistant-message/tool-call/tool-result/hw:state/flash-log/verify-record/checkpoint-change)。append唯一提交点:lossless-JSON 快照 + 深冻结 +seq连续性。deriveMessages:从有序 surface 投影模型历史,增量缓存。replayFromEntries推广到全量事件(从 hardware-state:134抽公共)。- "model-visible⟺logged" 断言:
before_agent_start钩子校验。
- 验收:append 重入 guard;deriveMessages 从 log 投影;compaction replace 重建;伪造"未 log 喂模型"断言抛错。
- 状态:未开始。
T07 PbaEventBus + ScopeKey 隔离【P1,前置无,G3】
- 执行:
src/core/pba-event-bus.ts:PbaEventBus薄封装pi.events,加emit/waterfall/serial/on+ScopeKey标签过滤。waterfall实现:listener 收(...args, next),调next()委托。- scope:无标签全局 + 匹配键/祖先键(注册向下继承、事件向上扩展)。
- 迁移:21 域现有
pi.events.on/emit改 typed 版本(verify:passed/build:done/boardlink:*/glm:*/xcompile:*/pdf-reader:*/debugger:*/length-recovery:*)。
- 验收:waterfall 链委托生效;scope agent 隔离;21 域迁移后 tsc 编译期检查签名。
- 状态:未开始。
T08 能力接缝三角色(board-link + flash)【P1,前置无,G6】
- 执行:
src/capabilities/board-link/types.ts:BoardLinkProvider接口(Definition)。src/capabilities/board-link/index.ts:BoardLinkRegistry(接缝,register返回 disposer)。src/capabilities/board-link/providers/:从board-link.ts抽rdk-x5-ssh/rdk-s100-serial/local三 provider。src/capabilities/board-link/tool-board-link.ts:consumer(原 tool 逻辑)。- flash 同理:
FlashProvider(dd/fastboot/dfu/openocd)+ 各 provider + tool consumer。 - BoardSpec(
shared/types.ts:98)做 provider 配置。
- 验收:加
RdkS100Provider后 tool-board-link 无改动可用 S100;registerdisposer 后 tool 不见该板。 - 状态:未开始。
T09 compaction 完整工程【P1,前置 T06,G8】
- 执行:
src/compaction/token-meter.ts:量 context 用量(嫁接 dshtoken-meter)。src/compaction/tool-result-pruner.ts:i2cdump/gdb/dmesg 大输出 model-free 压缩成摘要。src/compaction/summarizer.ts:重放前缀 + append 压缩指令,复用 pi-ai KV prefix cache。- surface replace:
user/message带surfaceOp:{op:'replace',start,end}(接 T06 PbaSession)。 src/compaction/spill.ts:SpillStore+SpillLocatorbranded 句柄,datasheet 大结果 spill。
- 验收:压力触发 summarize KV cache 复用;i2cdump prune 寄存器地址不丢;datasheet spill 句柄可取回。
- 状态:未开始。
T10 CI 质量门 + snapshot + doc-sync【P1,前置 T01,G12】
- 执行:
.github/workflows/ci.yml:test:coverageper-file 100% 门(v8/istanbul)。scripts/e2e-snapshot.ts:联网 key 跑最小闭环,输出 snapshot,回归对比。scripts/doc-sync.ts:校验架构文档锚点 file:line 与代码对齐。scripts/type-drift-check.ts:CI 定期对真 pi 源码 tsc,检测镜像漂移。docs/postmortem/:编号事后复盘模板。
- 验收:CI per-file 100% 门红即挡;snapshot 漂移红;doc-sync 锚点不一致红;类型漂移红。
- 状态:未开始(依赖 T01 联网)。
T11 类型镜像漂移检测【P1,前置无,G13】
- 执行:
tsconfig.realpi.json:paths 指真 pi 源码(../pi/packages/*/src/index.ts),临时用。scripts/type-drift-check.ts:跑tsc -p tsconfig.realpi.json,过滤 pi 自家内部错(已知packages/agent/src/*报错是 pi build 产物问题,非 pba),只看src/**/*.ts是否 0 错。- CI 定期跑(周)。
- 验收:pi 升版后若 pba
src/types/pi.d.ts镜像与真 pi 不符,CI 红。 - 状态:未开始(已实测:当前我文件对真 pi 源码 0 错,报错全在 pi 自家)。
6.3 P2 任务(改进,工程效率/通用性)
T12 子代理 + 工作流编排【P2,前置 T07/T08,G7】
- 执行:
- 评估 pi subagent 机制;不足则自建
src/capabilities/subagent/(spawn-in-process provider)。 - loop-orchestrator 上层加
src/capabilities/workflow/:parallel(编译+探板+datasheet)/ pipeline(edit→compile→flash→verify)。 - 工作流脚本能 fan out 子 agent,带上限。
- 评估 pi subagent 机制;不足则自建
- 验收: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 全 ✅。下列仅剩环境依赖项,非代码阻塞。
- 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。 - T01 真 LLM 一轮 turn(可选,需 key+网络):
bin/pba.tsdist 分发需build:offline(卡check:model-data,需generate-models联网填providers/data/);或直接用 vitest 源码别名跑一轮带 mock/真 key 的 agent turn。createAgentSession boot 已✅,差的只是真模型推理。 - CI 门上线(T10 产出已就绪):
.github/workflows/ci.yml含 per-file 覆盖门 + doc-sync + type-drift-check;推到 GitHub 后即生效。本地scripts/type-drift-check.ts可手跑。 - 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。 - 新核心库层的 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 + 测试证据。