验收

禁止

• 不改前端页面样式(规则 7;next.config.ts rewrites 属接线,不属样式)。
• 不加设计稿没有的功能(规则 8;spike 端点是验证脚手架,不是产品功能,R3/R4 正式实现后移除)。
• 不把 pi 内置工具打开(noTools:'all' 起步,规则 9);不声明任何 defineTool 工具(R6 的事)。
• 不建库表、不写迁移(R2 的事);会话仅内存态。
• key 明文不进代码、日志、任务卡、SSE。

代码审查

• 审查方式:codex /codex:review --background(thread 01a04741-7d31-7de3-9cc6-45282bfb7d75)
• findings 处理:
  • [P1] SSE 事件脱敏应为白名单而非黑名单(events.ts)——采纳。docs/security.md §2 是强约束,不应推迟到 R4:已改为逐事件顶层字段白名单(EVENT_FIELD_WHITELIST,未列字段一律丢弃;payload/headers/完整 message 等富对象永不放行,以派生摘要替代),值层保留截断 + 凭据键黑名单(DROP_KEY,并扩充 credential/cookie/access_token 形态)作纵深防御。整改后回归:provider 事件仅剩 {type}/{type,status},泄漏扫描 0 命中。
  • [P2] project_trust handler 必须返回 {trusted}(runtime.ts)——采纳。SDK emitProjectTrustEvent 直接读 handlerResult.trusted,返回 undefined 会 TypeError;观测者对该事件改返回 { trusted: "undecided" }(不做裁决),其余事件仍返回 undefined。
  • 审查推理中另涉及的 spike 端点无认证/无限额/会话上限竞态等——不整改,属已知 spike 范围:限额是 R6、后台认证是 R7 的交付,spike 端点仅本机开发环境存在且 R3/R4 落正式实现后移除(任务卡「禁止」段已声明)。
• 结论:整改后 PASS
• 复审(所有者问询后补做,codex /codex:adversarial-review --background,thread 01a0474f-52e5-7892-805f-336398ff0ef5,针对 P1/P2 整改本身):
  • P2 结论:{trusted:"undecided"} 与 0.84.3 SDK 契约一致,其余 33 事件返回 undefined 不改写流程——通过,无需再改。
  • [high] 白名单富字段(args/result/input/content/partialResult)仍经 sanitizeValue 递归复制未知嵌套结构;DROP_KEY 漏 access_token/client_secret/password/private_key 等变体;字符串值内凭据不检测——采纳:工具入参/出参不再复制结构,派生为 previewText 单条截断文本(序列化 replacer 层凭据键置 [redacted] + 字符串值过 sk-/Bearer 模式清洗);message_update.assistantMessageEvent 改固定投影 {type, contentIndex, delta};DROP_KEY 放宽为子串匹配并补齐变体。
  • [medium] 无单事件总量上限,大对象可放大 SSE/内存——采纳:sanitizeValue 增加对象键数上限(30);sanitizeEvent 出口加 MAX_EVENT_BYTES=8192 总量断言,超限降级 {type, oversized}(内存队列与 SSE 共用该出口)。
  • 按复审建议新增脱敏自测 fixtures(凭据键变体/深层嵌套/字符串值 Bearer·sk-/headers/未知字段/超大对象 6 组),挂 /spike/events/audit 的 sanitizeSelfTests 字段,整改后 6/6 PASS;转正式 encore test 已记入 rounds/BACKLOG.md(R2 测试基建落地后做)。
  • 复审整改后回归:tsc 干净;真实对话 + 轨迹流正常;SSE 采样泄漏扫描(含 access_token/client_secret 形态)0 命中。
• 复审结论:整改后 PASS

失败处理

同一验收项针对性整改后连续 2 次验证仍不过 → 写 rounds/round-01/BLOCKED.md,停下呼人(重点预案:sidecar 形态重评估)。

本轮实测

验收逐项(2026-08-28,本机 Windows,encore v1.57.13,node v24.11.1):

1. 钉版本 ✅ @earendil-works/pi-coding-agent@0.84.3(exact)入 apps/api/package.json + lockfile;CLAUDE.md 新增「钉版本」段。SDK 即 CLI 本体包,无独立 SDK 包;createAgentSession/defineTool/扩展系统均在其中。
2. 真实 LLM 对话 ✅ DeepSeek 官方 https://api.deepseek.com(内置 provider),模型 deepseek-v4-flash,thinkingLevel low。Encore 请求 handler 内 createAgentSession({noTools:'all'}) → prompt() 全程跑通,中文/英文各一轮 + 同 session 续问(?sessionId=)均正常;done 事件带 messageCount/capturedEvents。
3. 34 事件订阅 ✅ 每个会话 pi.on 订阅 34/34 成功、0 错误(/spike/events/audit)。纯对话(noTools)场景实际触发 16 种:session_start、resources_discover、input、before_agent_start、agent_start、turn_start、context、before_provider_headers、before_provider_request、after_provider_response、message_start、message_update、message_end、turn_end、agent_end、agent_settled。未触发的 18 种需对应场景(tool_* 要工具、session_before_*/compact/tree 要相应操作、user_bash/model_select 等),R4+ 按场景补测。
4. 模式计数核对 ✅ 实测 notify 19 / veto 6 / chain 7 / takeover 2 = 34;docs/architecture.md 旧记 notify 18(合计 33)为笔误,已回改并附逐事件清单指针(apps/api/spike/events.ts)。划分依据:handler result 语义(veto=可取消/拦截,chain=结果沿链传递,takeover=可完全接管,notify=纯通知)。
5. SSE 直连 ✅ curl -N 带毫秒时间戳逐行采样:对话流 delta 在 ~7s(短答)/~18s(长答)内持续逐字到达,非一次性;trace 流对话中实时出事件(先回放缓冲再 live tail,并发第二轮对话事件即时到达)。
6. SSE 经 Next dev proxy ✅ localhost:3000/api/spike/*(rewrites → :4000,与 Caddy strip_prefix 同语义)对话流 18s 逐字到达、done 正常收尾;trace 流回放 + 长连接心跳(15s : hb)不断流。
7. 内存基线(process.memoryUsage,无法强制 GC——encore 运行时未开 --expose-gc,gcForced=false,数字为自然回收口径):
   • 进程基线(pi 未加载):RSS 64.5MB / heap 5.4MB
   • import 增量:RSS +96.3MB / heap +62.4MB(动态 import 一次性成本,约 16s)
   • 单活跃(空闲)会话增量:RSS ~0.4MB / heap ~0.1MB(3 并发均摊)
   • dispose 回收:3 会话 dispose 后 RSS 回到创建前 ±0.1MB;10 轮 create/dispose 循环残留 RSS +0.6~0.9MB,无单调增长
   • 部署含义:pi in-process 固定成本 ~100MB,会话边际成本极小;compose mem_limit 512MB 起步即可,重点盯长对话历史与事件缓冲(每会话 capped 2000 条)
8. 凭据不泄漏 ✅ 6 份 SSE 原始采样 grep -iE "authorization|x-api-key|bearer|sk-|cookie|access_token" 全 0 命中;脱敏为逐事件字段白名单(codex review P1 整改,docs/security.md §2):payload/headers/完整 message 永不放行,provider 事件透出仅 {type}/{type,status};值层另有截断 + 凭据键黑名单兜底。key 走 .secrets.local.cue(已入 .gitignore,同时补了 .secrets.*.cue 规则),仓库无 key 片段。
9. 编译 ✅ dev.ps1 check 通过;npx tsc --noEmit(补 @types/node devDep)干净。

踩坑与实测发现:

• encore secret set 需要 app link,未 link 的本地 app 用 apps/api/.secrets.local.cue 提供 secret(官方本地覆盖机制)。
• bare createAgentSession() 不向扩展广播 session_start/resources_discover——它们由 run 模式层的 session.bindExtensions() 触发。spike 在创建后补 bindExtensions({ mode: "print" })(headless,hasUI=false)后两事件正常到达;已写入 docs/architecture.md,R3 沿用。
• pi 资源发现指向 tmpdir 下空隔离目录(agent-xray-spike-pi),ModelRuntime 的 auth/models/models-store 路径同样隔离——in-process 进程不加载本机 ~/.pi 的任何用户扩展/凭据;key 仅经 setRuntimeApiKey 运行时注入,不落盘。
• DeepSeek deepseek-v4-flash 的 thinkingLevelMap 不支持 medium(SDK 会 clamp),spike 显式用 low。
• Encore 检测到新版 v1.58.4,按钉版本原则不升级(v1.57.13 继续)。

与计划的偏离:

• ROUNDS.md 原文「经海外中转端点」→ 按所有者指示改用 DeepSeek 官方 API 境内直连(见「前置」)。
• 新增 apps/api/spike/sse.ts(SSE 写出小工具)与 @types/node devDep,交付物清单外的必要小件。