验收

禁止

• 不改前端页面样式(CLAUDE.md 规则 7)。本轮唯一的前端改动是 askErrorText 增两条分档与 AskError 多一个 code 字段 —— 纯接线,不动样式、布局、className、token、动画。
• 不加设计稿没有的功能(规则 8)。工具组与限额是 docs/security.md 的既定约束,不是新功能;三个工具名以 ROUNDS.md R7 为准。
• 不实现任何执行类工具。bash / write / 任意代码执行永久禁止进 in-process 进程(规则 9)。
• 不碰 R8 的 metrics / About。

与计划的偏离(两处,均已同步 ROUNDS.md 与 docs/security.md)

1. agent_ro 用 SET LOCAL ROLE,不用 AGENT_RO_DATABASE_URL(所有者裁定 2026-09-01)

ROUNDS.md 原文是「连接串用 AGENT_RO_DATABASE_URL」。落地时发现那条路要多带三样东西:一个 pg 驱动依赖、一份 agent_ro 的登录口令(.env / initdb / secret 各一处)、一个 Encore 管不到的第二连接池。

决定性的不是这三样,是验收能不能自动跑:本机 encore 的库由 CLI 托管,agent_ro 的登录口令进不到那套托管配置里,于是「以 agent_ro 连接尝试写库必须失败」这条验收本地跑不了,只能推到 R9 在 130 上人工核验 —— 而 M2 的止损写的正是「R7 沙箱验收不过 → 不得进入任何公网部署轮」。把验收推进部署轮,等于把止损点也推掉了。

改法:角色仍是真的 Postgres 角色、权限仍由库强制,只是建成 NOLOGIN,由应用连接在事务里 SET LOCAL ROLE agent_ro 临时降权。语义与独立连接等价(降权后 current_user 就是 agent_ro,写库一样 permission denied),而 SET LOCAL 随事务结束复位,连接池复用不会把降权状态泄漏给下一个请求。

代价与连带:

• ROUNDS.md R9 的「docker-entrypoint-initdb.d 建角色」一项取消(角色由迁移 006 建)。
• 多一条隐含前提:deploy/migrate.sh 必须在起 api 之前跑完 —— 那本来就是既定顺序,已在 compose 注释里写明。

2. 只用 defineTool 的类型,不用它的运行时导出

defineTool() 是恒等函数,唯一作用是在用 TypeBox 的 Type.Object() 时保住泛型推断。本轮的 schema 是普通 JSON Schema 对象(pi 的 validateToolArguments 对没有 TypeBox.Kind 符号的 schema 走 JSON Schema 分支,已实测 required / additionalProperties / minLength 全部生效),没有泛型可推;而静态 import 它会把整个 pi 包在 API 启动时拉进来,破坏 runtime.ts 刻意做的惰性加载。

顺带避免了给 apps/api 加一个 typebox 直接依赖(它现在只作为 pi 的 shrinkwrap 内部依赖存在)。

3. notes_list_series 多一个 series 参数(不是偏离,是补位)

ROUNDS.md 把工具组钉成三个名字,而模型要读一章必须先拿到章节 slug —— 这个「目录」能力总得有落点。放进 notes_list_series(给了 series 就往下一层走)比新开第四个工具更省,也不越过「三个工具」的边界。

prompt injection 自测清单(验收 11)

用 faux provider 直接扮演被劫持的模型:不是让真模型去"尝试"越权,而是让它必然发出越权的 tool call,看闸门拦不拦得住。这比对真模型写诱导 prompt 强 —— 后者只能证明"这次没成功"。

没有覆盖到的:真模型在长对话里被逐步诱导的行为面(需要真实 LLM key 与人工判读)。本轮的闸门都在模型之外,与模型是否被说服无关,所以这块不影响上面 8 条的结论。

代码审查

审查方式:codex /codex:review --background(全量 branch diff against main;CLAUDE.md「审查范围」前两轮全量)。

第 1 轮:4 条 findings,全部采纳整改

四条都是最小改动(改判断 / 加一个 SQL FILTER / 多取一列 / 换一个存在性检查),没有新增机制。

第 2 轮(复审,仍是全量范围):2 条 findings,全部采纳整改

关于第 2 条的可观测性,要说清楚:本机 encore 集群里所有登录角色(encore-read / write / service / admin / migrator / postgres)对 sessions 都有 SELECT(实测),所以新旧两版在这个集群上选出的是同一批角色,收紧不可观测。判据不是空转的反例是 agent_ro 自己:has_table_privilege('agent_ro','sessions','SELECT') = false。生产 compose 只有 app 一个角色,两版行为也相同。这条整改防的是「同集群里存在只有 CONNECT、没有表权限的角色」那种环境 —— 正是 finding 描述的场景,而本机恰好不具备。

验证:encore db reset agent 后重跑全套 —— 迁移干净应用(role_table_grants 里 agent_ro 恰好 3 条,即 notes 三张表),9 文件 139 用例全过。

第 3 轮(复审,范围收窄到整改 diff --base 2a17687)

零 findings。 原文:"The changes correctly preserve sanitized tool errors while routing them through pi's error path, and the migration narrows role membership without breaking the documented runtime roles. No actionable regression was found in the reviewed diff."

范围按 CLAUDE.md「审查范围」:前两轮全量 branch diff against main,第 3 轮起只审上一轮整改后的 diff。

结论:整改后 PASS。三轮共 6 条 findings(1×P1 · 4×P2 · 1×P3),全部采纳整改,末轮零 findings,缺陷门禁通过。没有一条被以「概率低」「后面会换掉」为由跳过,也没有一条进 BACKLOG。

失败处理

同一验收项针对性整改后连续 2 次验证仍不过 → 写 rounds/round-07/BLOCKED.md,停下呼人。禁止放宽验收标准自我通过。

本轮实测

踩到的坑

1. 与 R8 撞了迁移号,而 git 不会告诉你。 合并 main 时才发现 R8 已经占了 004(metrics) 与 005(about showcase),本轮也叫 004 —— 两个文件名不同,git 自动合并零冲突, 但 deploy/migrate.sh 对同号迁移是硬失败(发现重复的迁移版本号 v4,R-BUN 那轮 codex 复审专门加的守卫),而在没有这道守卫的路径上后果更糟:「version > current」 会让第二份被静默跳过,库里永久缺一份变更。本轮迁移改号 006,同时改掉 7 处引用 (代码注释 / docs/security.md / compose 注释 / ROUNDS.md / 任务卡 / 测试)。 教训:并行开轮次时,迁移号冲突是 git 看不见的一类冲突,合并后必须 ls migrations/ 看一眼、并把本地库 encore db reset 后重跑一次 —— 改号之后本地 schema_migrations 停在旧号上,不 reset 的话新号之前的迁移会被跳过。

2. GRANT agent_ro TO CURRENT_USER 在本机跑不通。 encore 的本地集群按职责分了多个登录角色,迁移与业务查询不是同一个:迁移跑在 encore-migrator 上,请求跑在 encore-write / encore-service 上。只授给 CURRENT_USER 的表现是迁移成功、运行期 permission denied to set role "agent_ro"。生产 compose 只有 app 一个角色,两者同名,所以这个坑只在本机暴露 —— 而本机正是验收要跑的地方。改成遍历「能连本库的登录角色」逐个授。授得宽是安全的:membership 给的是「降到 agent_ro 的能力」,agent_ro 的权限集是这些角色的真子集。

3. CREATE ROLE 是集群级的,迁移是库级的。 本机 encore 把所有本地 app 的库放在同一个 postgres 容器里,换一个 worktree 就是另一个 app、另一个库、但还是同一个集群。裸 CREATE ROLE 会在第二个 worktree 上直接 role "agent_ro" already exists 把迁移打断。必须 IF NOT EXISTS 守卫。

4. recordUsage 的日界不能走模板插值。 (now() AT TIME ZONE 'Asia/Shanghai')::date 是一段 SQL 表达式,用 Encore 的模板字符串写会被当参数绑定,变成把字符串塞进 day 列。读写两侧都得用 rawExec/rawQuery 把它拼进 SQL。

5. 一轮有多条助手消息,usage 必须逐条累加。 开了工具之后「助手 → 工具 → 助手」是常态。实测一次工具轮的两条助手消息各带 usage(totalTokens 1330 / 1054),只取最后一条会漏掉一半的计费。

6. pi 的 faux provider 是现成的闭环验证器。 它在 @earendil-works/pi-ai/providers/faux(pi 的 shrinkwrap 内部依赖,apps/api 解析不到,只能走深路径),配合 ModelRuntime.registerNativeProvider() 可以脚本化"模型说什么"。本轮用它跑通了工具闭环与四条注入用例,全程不需要 LLM key。这个探针没有提交:深路径穿过另一个包的私有 node_modules,pi 升级时会以"整个测试文件 import 失败"的方式炸掉整个套件。要复现按下面的方法重建。

闭环验证怎么复现

在 apps/api/agent/ 下临时建一个 *.test.ts(跑完删掉),要点:

其余按 createRuntimeSession 的参数照搬(noTools:"all" + customTools + tools),session.prompt(...) 即可。 跑法:encore test --reporter=verbose <文件名>(默认 reporter 不打 stdout)。

本轮实测数字

• dev.ps1 test:9 文件 139 用例全过(R7 新增 27 个,约 +2s);encore db reset agent 后从零重跑同样全过
• faux 闭环单次约 2.2s;工具查询在本机 Postgres 上单次 < 10ms
• 到达观测者的扩展事件(单次工具轮,去重后 19 种):含 tool_call / tool_execution_start / tool_execution_end / tool_result 四种工具事件 —— 轨迹面板拿得到工具轨迹