跳转至

Pi 1.3.0 产品与扩展章节作者记录

状态：六章已完整重写，可交独立复审；本记录是作者核查，不是独立 PASS。 作者范围：仅 docs/03-usage.md、docs/source/08-tools-extensions.md、docs/source/09-mcp-codemode.md、docs/source/10-interfaces.md、docs/labs/12-customize.md、docs/labs/15-production.md，以及本 research 目录作者证据。未修改 examples 或构建脚本。 固定源码：pi-1.3.0 / 71023aec1546d6d677a65669c5665c0927ce0dd0。未把 upstream main 机制写进 release 教程。

初审发现

旧03仍安装1.0.1，未覆盖1.3恢复active tools与相对选择语义。旧08以注册与旧版renderer补丁为主，缺少最终malformed arguments与1.2 custom-run启动临界区。旧09不能继续把worker结果/close与实际退出合并，也缺少1.2 portable/remote和MCP dispatch取消边界。旧10的大段pi-protocol/client/server、CBOR/attachment与Chord集成说明已不属于1.3产品架构。旧12/15需要把这些变化落实为自建研究Agent的工具范围、状态归属与故障演练，而非只更新版本号。

已先通读旧六章，读coding-agent、codemode、mcp changelog的1.1/1.2/1.3段，并直接比较1.0.1→1.3.0 codemode/runtime/host.ts、ai/utils/json-parse.ts。其中host从内置完整execution重构为launcher+base runtime；最终参数增加argumentsError，流式partial不再用于执行。

逐章修改

  • 03：重建离线→真实CLI→工具选择→会话→自动化→迁移/分享→排错路线。明确普通allowlist对MCP的例外、relative modifiers作用于恢复集、print text截断退出1、auto分享仅凭据不可用时fallback。
  • 08：以search预览/read收据/submit验收串起schema、授权、业务校验；增加最终JSON与流式预览分流图、结果消费者、same-file queue边界、trust bootstrap及调用权限图、custom-run生命周期、exposure/reachesTools。
  • 09：重新解释MCP与CodeMode分层；OAuth整个流程取消、issuer缺metadata拒绝、refresh后dispatch检查与close最后token；首行options、structured失败值；1.3 live worker两阶段状态图和集成层限额2；inline/remote/start重放边界、store非事务。
  • 10：删除现行架构中的实验server/client/protocol与Chord依赖，重建runtime/session/TUI/print/RPC。给出disposition等待时序、LF-only framing、EOF shutdown和产品业务终态，不把settled当accepted。
  • 12：完整个人研究包加载、安装、移除与迁移练习，解释每条规则落在template/skill/extension/submit哪一层；新增messageType guard、branch状态与reload生命周期、配置范围。
  • 15：围绕accepted artifact定义生产设计；租户身份注入、状态所有权、幂等与事务、三层取消、actual exit容量、分层预算/重试、配置迁移、分享与观测、线上评测、四个故障演练。

实际读源范围

product-readers.json列出33份阅读器文件及具体范围。关键读源包括：

  • Core：agent-loop prepare/validate/hooks/execute/result；ai json-parse完整文件关键分支及validation尾部；tool result structuredContent删除规则。
  • Coding-agent：sdk工具选择段；agent-session restored tools与_startRun；runtime接口及所有权；resource-loader trust bootstrap；project-trust完整决策；settings-manager migrate/load/reload及迁移入口；extensions types、runner nested context、wrapper；edit schema/兼容层、file queue完整文件、truncate常量。
  • CodeMode：host完整launcher、source完整parser、execute限额/结果映射/store提交、inline/remote边界与VM interrupt轮询定位；worker-admission测试完整阅读，source/portable等测试只定位而未作为已运行证据。
  • MCP：flow issuer/signal/refresh/native注册；streamable-http send/close/dispatch；extension session signal、reachesTools等待；OAuth与HTTP测试的取消/issuer/关闭段。
  • 接口：print完整函数、RPC prompt/extension UI/输入/EOF段、jsonl完整文件、runtime当前session所有权、TUI Component；share完整文件以及测试定位。
  • 测试：rpc-prompt-response-semantics主要场景完整阅读，print fixture/shutdown段，settings测试定位。课程package/codemode/evidence/edge-cases/v130-boundaries相关实现与测试阅读。

作者实际验证

2026-10-18，在 examples 执行：

node --test --test-reporter spec test/package.test.ts test/codemode.test.ts test/v130-boundaries.test.ts
10 tests / 10 pass / 0 fail / duration 3746.367301 ms

覆盖真实QuickJS无Node/fetch、输出cap、store成功/失败、副作用不回滚、nested授权hook、真实包发现与edit拦截、malformed JSON不可执行、cross-model thinking、abort/timeout实际worker退出但宿主副作用仍可迟到。

六章55处固定40位SHA源码行锚已按本地文件校验存在和行数，修正越界末行；Markdown fence成对。作者检查结果保存 product-author-check.json。链接21/22等待root创建对应章节后由全站构建校验。

未测与剩余限制

未执行真实provider调用、真实MCP OAuth、远端MCP server部署、Radius/gist上传。没有运行上游vitest整套，也没有把读过的上游测试记为本机PASS。课程实际worker测试在Node执行，不能声称已实测Bun非可中断built-in；上游mock terminate admission测试是阅读证据。未单独进行六章Mermaid浏览器渲染，待全站构建与独立复审。

公开源码快照的coding-agent package.json generate:schemas仍引用已删除experimental/source-resolver；正文没有教授执行这个脚本。本文的配置Schema说明来自release变更与运行时读取机制，不将该命令描述成已验证入口。

后续独立审阅应重点检查：active-tools与MCP allowlist例外；tool_call改参不重验；print text与JSON退出码区别；share auto失败不fallback；CodeMode逻辑settle与actual exit；read收据与语义评测的边界。作者可修正反馈，但不签发独立PASS。

交叉复审后的作者修正

  • 修正 08/10 到 docs 根目录 21/22 的相对链接。

  • labs 独立审发现 08.2 图将 argumentsError 直接送 validation，遗漏 prepareArguments。按 agent-loop.ts:727–729 改为 error → prepare → validation，正文补充兼容层须纯转换；保留错误标记阻止 execute。本条为作者修正，不计独立 PASS。

  • 第四独立源码审查指出15.5取消图先worker终止后外部取消不符源码。作者回读runtime/execution.ts410–447与runtime/host.ts后修正为待处理宿主调用controller.abort→channel.stop→逻辑settle；图限定已建立channel且worker未退出，以并行分支区分实际exit，工具signal不等于远端取消。新增固定execution源码锚。待core/labs/第四独立者复验；不改作者自身独立PASS范围。