- 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>
6.0 KiB
6.0 KiB
Physical Byte Agent — AGENTS.md
基于 pi 二开的嵌入式开发 Agent,模型 glm-5.2。
架构铁律
- 单一 barrel 装配:
src/extensions/index.ts是 pi 唯一加载的扩展入口(package.json"pi":{extensions:["src/extensions/index.ts"]})。它依次装配 21 个域扩展工厂。pi 加载一个扩展 = 装配整个 Agent。 - 逻辑内联 + 命名导出:每个
src/extensions/<domain>.ts既export default function(pi)(pi glue:registerTool/on/registerProvider/appendEntry/events),又export纯逻辑函数。tests import 命名导出单测,无需 pi 运行时、无需真实硬件(注入 mock ExecFn)。 - fail-closed:所有硬件判据(safety-gate 破坏性命令、flash 三段式烧录、hardware-verify 物理信号、loop-orchestrator checkpoint)默认拒绝/失败,不放过。
- 命门根治:
- 命门一(thinking 黑洞零输出)=
glm-provider.tsbuildGlmModelConfig()(thinkingFormat:qwen + maxTokens:8192 + thinkingLevelMap 全 null)+detectEmptyOutput()兜底 - 命门二(hex 强转砖板)=
glm-provider.tsnormalizeHexArg()/makeHexNormalizingPrepareArguments()工厂(接入结构化工具的 prepareArguments)
- 命门一(thinking 黑洞零输出)=
- 密钥铁律:网关 key 只走
${DROBOTICS_LLM_KEY}环境占位,绝不硬编码、不入库。grep -rn sk-nAm src/必须为 0。 - 真 pi 类型:tsconfig
paths指向../pi/packages/*/src,对真 pi 源码做 tsc(非 shim)。
文件布局
src/
index.ts # 公共导出(PhysicalByteAgent + extensionFactories + T06–T17 核心库 re-export)
agent.ts # PhysicalByteAgent.launch(): 组装 extensions → pi createAgentSession
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:装配全部 22 域扩展(pi 唯一加载入口)
glm-provider.ts # 命门一+二 + glm_status 工具
safety-gate.ts # 破坏性命令拦截 + 资源锁 + per-skill 工具 + devmem 硬门
persistent-shell.ts # PTY 会话池
pdf-reader.ts # PDF 分页/提限
edit-strict.ts # edit 精确匹配安全模式
length-recovery.ts # stop=length 恢复
subprocess-isolation.ts
env-probe.ts
mcp-bridge.ts
server-runtime.ts
hardware-state.ts
cross-compile.ts
flash.ts
peripheral-probe.ts
jtag-debugger.ts
device-tree.ts
board-link.ts
datasheet-rag.ts
hardware-verify.ts
loop-orchestrator.ts
build-tracker.ts
reg-tool.ts # T03 devmem 专用 reg 工具(P0)
bin/pba.ts # CLI 入口
scripts/ # T10/T11 CI 门 + 类型漂移 + doc-sync + e2e-snapshot
tests/ # 镜像单测 + tests/system-integration.test.ts(跨 10 模块闭环)
运行
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 编译(源码+契约已就绪)。