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

6.0 KiB
Raw Permalink Blame History

Physical Byte Agent — AGENTS.md

基于 pi 二开的嵌入式开发 Agent,模型 glm-5.2。

架构铁律

  1. 单一 barrel 装配:src/extensions/index.ts 是 pi 唯一加载的扩展入口(package.json "pi":{extensions:["src/extensions/index.ts"]})。它依次装配 21 个域扩展工厂。pi 加载一个扩展 = 装配整个 Agent。
  2. 逻辑内联 + 命名导出:每个 src/extensions/<domain>.ts 既 export default function(pi)(pi glue:registerTool/on/registerProvider/appendEntry/events),又 export 纯逻辑函数。tests import 命名导出单测,无需 pi 运行时、无需真实硬件(注入 mock ExecFn)。
  3. fail-closed:所有硬件判据(safety-gate 破坏性命令、flash 三段式烧录、hardware-verify 物理信号、loop-orchestrator checkpoint)默认拒绝/失败,不放过。
  4. 命门根治:
    • 命门一(thinking 黑洞零输出)= glm-provider.ts buildGlmModelConfig()(thinkingFormat:qwen + maxTokens:8192 + thinkingLevelMap 全 null)+ detectEmptyOutput() 兜底
    • 命门二(hex 强转砖板)= glm-provider.ts normalizeHexArg() / makeHexNormalizingPrepareArguments() 工厂(接入结构化工具的 prepareArguments)
  5. 密钥铁律:网关 key 只走 ${DROBOTICS_LLM_KEY} 环境占位,绝不硬编码、不入库。grep -rn sk-nAm src/ 必须为 0。
  6. 真 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 编译(源码+契约已就绪)。