fix(narration): 取得判定改为申报加集合校验，叙事被拒改为句级降级 (#512)

[Ximaohu-LMX]

关联 Issue

Refs #512
Closes #520

没有用 Closes：#512 的验收标准第 1 条要求「第 9、第 10 条的判据改为对引擎真值的集合包含判断，校验路径中不再依赖取得类/状态类动词词表」。本 PR 对第 10 条（inventory）做到了，对第 9 条（状态断言）刻意没有做到——理由见下方「偏差说明」。是否更新该条验收口径、还是另开 Issue 处理第 9 条，请评审决定。

主要改动

1. 取得判定：从开集词表改为申报 + 集合校验（#512 的缺陷本体）

ActionPlanNarrationOutput 增加两个申报字段，沿用第 2 关 claimed_evidence_refs 的既有范式：

claimed_inventory_ids: tuple[str, ...] = ()
claimed_state_changes: tuple[NarrationStateClaim, ...] = ()

校验退化为对引擎真值的包含判断，不含任何词表：申报的背包 id 必须在最终 player_view.inventory 中，申报的状态三元组必须来自 committed_results 或可见实体的 observable_state。

词表退为「申报不足」时的守门补丁，按声明强弱分两级：

• 明确入包声明（放进背包 / 收进口袋 / 背包里多了）——目的地本身就是玩家背包这个权威概念，无条件要求正文点名一件确实在最终 inventory 里的物品。
• 无容器的取得类动词（带走 / 取走 / 收好）——只有当动词所在小句里出现权威物品名（场景散落物 ∪ 可见实体 ∪ 最终背包）且该物品不在最终背包时才判定。

动词表里删掉了 拿起 / 拾起 / 捡起，并随之删掉 _TRANSIENT_HANDLING 白名单。

2. 拒绝后的句级降级阶梯

两次校验不过时，先剔除违规小句、复校验剩余正文，通过才发布；剩余为空或仍不合规才交回原有兜底。覆盖背包与状态断言、禁词泄漏、NPC 引语四类可定位的拒绝。

3. 申报字段容错

DeepSeek 一路只用 response_format={"type": "json_object"}，schema 仅作为提示词文字下发、没有任何强制。实测日志出现 reason=outer_schema：八种常见写法里七种（null、裸字符串、单个对象、混用 CommittedResult 键名、value 给成数字……）会让 model_validate 抛错、整段有效正文被丢掉。改为逐条降级——读不懂的丢弃，读得懂的保留。

4. NPC 引语拒绝改为可重试、可剔除

npc_dialogue_embedded_in_text 此前没有专属重试提示，落到通用文案（完全没提引号），模型无从修正、照原样再写一遍再被同一关拒掉。补了说清楚的提示，并把这一关纳入句级降级。

5. @NPC 兜底不再零气泡

「结构化 @NPC 至少产生一条独立气泡」的安全网原先只写在成功路径上，所有兜底路径从 except 直接返回、绕过了它。抽成 helper，四条返回路径共用。

6. 拒绝日志可定位

outer_schema 记失败字段路径，hidden_disclosure 记命中项来源，句级降级记剔除区间。均不落盘任何模型正文与禁词字面值。

7. 提示词改用申报口径

同步说明临时取用不需要申报、也不要为了避险而回避这类动作。

8. 顺带修复 main 的 CI 红灯（#520，与 #512 无关）

app/adapters/host_speech.py 中音色列表查询的 httpx 客户端直接传了标量 timeout，
绕过 #510/#511 引入的 model_http_timeout()，被其源码扫描测试
test_no_production_http_client_passes_a_scalar_timeout 抓住。main 分支自 ef47d7f
起 Backend CI 持续红灯（前一提交 93d0011 尚绿），所有基于 main 的 PR 都继承了这条
失败，CI 结果不再可信。

按维护者要求在本 PR 一并修复。这一项与 #512 无关，评审时可单独看
fix(adapters): 音色列表查询的建连超时与生成预算分开 (#520) 这一个提交，也可单独 revert。

采用该方案的原因

根因不是词表不够长，而是校验器被要求在开集上做语义识别。 中文里「拿起 X 去做 Y」是开集搭配（拨号、抿一口、掂重量、翻到某页……），白名单必然追不上——_TRANSIENT_HANDLING 收了「翻看」「翻阅」，唯独没有「翻到」，这类补丁的速度追不上中文动词的组合速度。

同一个文件里已有正确范式：第 2 关让模型自报 claimed_evidence_refs，校验器只做 issubset，零词表、零歧义。本 PR 把它推广到背包与状态断言。

这不是「信任模型」：撒谎的成本从「绕过一个词表」变成「必须写一个引擎当场查表否掉的 id」。

关于容错（改动 3）：它只可能让正文多受一次守门补丁检查，不可能放过虚假声明——过度申报仍由集合校验当场挡掉，申报不足本就由守门补丁与「前端背包只跟权威 PlayerView 走」两道覆盖。这也是这个文件已经写明的原则：不该因为模型漏填一个记账字段就丢掉本来有效的正文。

关于论元位（改动 1 的第二级）：仅按「物品名 + 动词」收窄不够。线上原句「你拿起电话，拨打了传单上的号码」整句里确实出现了权威物品名「传单」，但它不是该动词的论元——不做小句绑定的话这句仍会被误拒。

前端背包（#512 验收标准第 5 条）

不新增通道，也不改前端。 前端背包由 _broadcast_player_views 投影的权威 PlayerView 驱动。集合校验已保证 claimed_inventory_ids ⊆ 最终 inventory，申报永远不会凭空增加前端看不到的物品；而「正文声称但未申报」时 PlayerView.inventory 无变化，前端也就没有背包变化——落差当场可见。

再开一条申报驱动的 UI 通道会制造第二个真值源，与本仓库「PlayerView 是唯一权威投影」的设计相悖。改为用测试钉住这个不变量。

偏差说明

第 9 关保留了状态动词表

状态断言的闭集锚点是可见实体名，而 visible_entities 并不是「可被合法提及的角色」的全集——persistent_results.py 中已有注释说明随行者、运行时对话人物都可能不在其中。把词表收窄到「必须点名可见实体」会放行「守墓人昏迷了」这类点名场外实体的无证据断言，属于开洞而非修洞。

因此第 9 关的词表保留，但它的误判代价由本 PR 的句级降级阶梯承担——被拒的是一小句，不再是整段正文。narrator 层的既有测试全部保持不变、保持抛错。

第 6 关的下游处理有变化

#512 的「不包含」写明第 1/4/5/6 条合规检查「不得因本次改动被削弱」。第 6 关的判据完全没动，仍然照常拒绝；变化的是拒绝之后：它现在有专属重试提示，并可被句级剔除。这是减轻误判代价，不是放宽判定，但确实改变了行为，请评审确认是否可接受。

测试与验证

• 测试已完成
• 手动验证已完成
• 构建或静态检查已完成

自动化

• agent-collaboration-framework：528 passed
• trpg-backend 相关套件（test_action_plan_turn_recovery / test_openai_models / test_ws / test_chat_ws / test_logging）：全部通过
• trpg-backend 全量：701 passed, 23 skipped, 0 failed
• CI 的四道检查在本地逐一复跑：ruff check ✅ / ruff format --check ✅ / ty check ✅ / pytest ✅

分支上原本继承了 main 的一条失败（test_no_production_http_client_passes_a_scalar_timeout，指向 app/adapters/host_speech.py:213）。已确认那是 main 自身的红灯（见 #520 与 main 上的失败 run），并按维护者要求在本 PR 的改动 8 中一并修复，后端全量因此由 700 passed / 1 failed 变为 701 passed / 0 failed。

#512 的 11 条验收用例：全部符合预期（原为 4/11）

期望	用例	结果
PASS	你拿起电话，拨打了传单上的号码，但电话那头传来的只是一阵持续的忙音，无人接听。	✅
PASS	你拿起听筒贴到耳边，线路那头一片死寂。	✅
PASS	你拿起桌上的照片，指腹擦过詹姆斯的脸。	✅
PASS	你拿起茶杯抿了一口，茶已经凉了。	✅
PASS	你拿起手册翻到第一页。	✅
PASS	莱恩夫人拿起手帕擦了擦眼角。	✅
PASS	你拿起门边的雨伞掂了掂重量。	✅
PASS	你拿起传单，仔细端详上面的图案。	✅
REJECT	你把传单收进外套口袋。	✅
REJECT	你把蛙蛙度假村传单放进背包。	✅
REJECT	你顺手把那张传单带走了。	✅

补充用例「你把传单收进背包。」在传单已进入最终 inventory 时 PASS ✅

Issue 路径 A（确定性复现）：改动后重跑 #512 正文的脚本，由 8 REJECT / 1 PASS 变为 8 PASS / 1 REJECT（只剩真正的取得声明被拒）。

手动端到端：本地部署《幸福蛙蛙村》实跑一局（接受委托 → 查看传单 → 前往度假村 → 进入接待大厅 → 与 NPC 对话 → 强行带走詹姆斯）。日志中不再出现 persistent_claim_without_evidence:inventory_acquisition，并观察到句级降级实际生效：

action=be9cb2d0 attempt=1 reason=outer_schema
action=be9cb2d0 attempt=2 reason=hidden_disclosure
action=be9cb2d0 action_plan_narration_sentence_degraded removed_sentences=1
action=be9cb2d0 attempts=2 path=sentence_degraded

该行动在改动前会整段塌成「这次行动已经按当前可确认的结果完成。」，现在保留了其余三句正常叙事。

风险与回滚

契约变更：ActionPlanNarrationOutput 增加两个字段、ActionPlanNarrationValidationError 增加三个可选参数。新字段均有默认值，旧形状输出照常通过（有测试钉住）；错误的新参数全部可选，既有单参构造点不受影响。

行为变更：拿起 / 拾起 / 捡起 不再被视为取得动词。凭空写「你捡起钥匙」不再被拒——但也不会产生任何背包变化，落差在前端当场可见（前端背包只跟权威 PlayerView 走）。这是本 PR 有意的取舍。

句级降级是静默的：改动前整段塌成状态播报，一眼看得出出事；现在少一小句，玩家侧无痕迹。日志有 action_plan_narration_sentence_degraded（含剔除区间）可追。这是 #512 设计中「误判代价从整段变废话降到少一小句」的固有属性。

回滚：6 个提交互相独立、按主题拆分，可整体 revert，也可只 revert 其中某一项（例如只回滚句级降级、保留取得判定的修复）。无数据库迁移、无配置变更、无依赖变更。

UI 证据

不适用。本 PR 不含前端改动，也不新增任何 UI 通道（前端背包继续由权威 PlayerView 驱动，见「采用该方案的原因」）。

AI 使用情况

本 PR 由 Claude Opus 5 在 Claude Code 中协助完成。关键提示与人工介入点：

• 起点是「修复 issue512」，随后就两处设计分叉做了人工决策：分支基线取 upstream/main；第 9 关范围取「申报 + 降级、保留词表兜底」而非与第 10 关完全对称改造（理由见「偏差说明」）。
• 实现过程中由本地实跑日志驱动了三轮修正：申报字段容错（改动 3）、NPC 引语的重试与降级（改动 4）、@NPC 兜底零气泡（改动 5）——这三项都不在最初计划内，是实跑暴露出来后补的。
• 引语区间的取法经过三次修正：最初按「含引号字符的句子」剔除，会把多句引语的中间部分留下（引号没了、台词被改写成守秘人正文，比落兜底更糟）；改为扩到句末又会把闭引号后的正常叙事连坐；最终定为「仅在引语前紧挨冒号时扩到句首，右边界只到引语结束加紧随的小句标点」。

人工 Review 声明：改动范围、判据取舍与偏差说明均经人工确认；上述 11 条验收用例与端到端实跑由人工执行并核对结果。合并前仍需至少一名维护者 Review。

自检

• 改动范围符合 Issue（偏差已在上方显式说明）
• 无关改动仅有一处且已显式说明：改动 8（[Bug][CI] main 分支 Backend CI 持续红灯：host_speech 新增的 httpx 客户端绕过 model_http_timeout #520 的 CI 修复）经维护者要求纳入，独占一个提交、可单独 revert。本地 pyproject.toml / uv.lock 的代理适配改动保持未提交
• 已包含必要的测试和文档（新增 17 条测试；提示词同步更新）
• 不包含密钥、个人信息或非预期生成物
• 已完成 AI 辅助质量检查和人工 Review

[fennoai]

Reviewed the complete fixed diff for narration validation, declaration schemas, recovery/fallback paths, prompt/schema integration, and the associated tests. No actionable P0–P3 correctness, security, performance, or maintainability findings meet the review threshold.

Verification: python3 -m compileall -q agent-collaboration-framework/collaboration_framework trpg-backend/app and git diff --check pass. Focused pytest execution was unavailable because this environment does not have pytest, uv, or the project dependencies installed.