Recall pitfall experience on evidence-backed runtime triggers

docs/experience.md

@@ -19,9 +19,13 @@
 
 ## 什么时候读
 
-准备阶段校验路径并读取一次库，固定任务视图。完成原始 Issue 分析后，按 Issue 与 target_modules 匹配经验：标签命中和摘要关键词命中计分，同分按 ID 排序，零分不返回。英文按词匹配，中文使用相邻双字。
+准备阶段校验路径并读取一次库，固定任务视图。完成原始 Issue 分析后，无结构化触发条件的卡按 Issue 与 target_modules 匹配：标签命中和摘要关键词命中计分，同分按 ID 排序，零分不返回。英文按词匹配，中文使用相邻双字。有 triggers 的过程卡不参与这一检索，不因为工具可用就提前加载。
 
-首轮探索最多展示 3 条 id/summary；Agent 通过 AgentScope 只读工具 `read_experience` 按需读取一条详情。整个任务只能成功读一次，契约修订和候选重试不重新加载。摘要列表与详情的 UTF-8 JSON 合计最多 2048 字节；容量不足时拒绝详情或减少摘要，不截断正文，不挤掉原始 Issue/契约。分析和 Verifier 不直接加载经验，经验引用不能申请当前原版契约修订。
+探索中，真实工具错误、最终权限拒绝或协议纠错触发从同一冻结库按需检索；条件 kind/tool/code 全部一致才匹配。摘要在下一次已有模型调用前作为历史建议送入，原始工具结果保持完整。初版支持 revise_contract 的 SOURCE_RANGE_NOT_DISPLAYED/SOURCE_HASH_MISMATCH，六工具的 DENIED，Read/Grep/Glob 的 RESERVED_FOR_PUBLISHING，以及 MULTIPLE_TOOL_CALLS/UNKNOWN_TOOL/INVALID_TOOL_INPUT。未知错误文本不猜测为上述条件。
+
+首轮及探索中累计最多展示 3 条独立 id/summary；Agent 通过 AgentScope 只读工具 `read_experience` 按需读取一条详情。整个任务只能成功读一次，契约修订和候选重试不重读库、不重置配额、不重复展示已注入卡。累计摘要列表与已读详情的 UTF-8 JSON 合计最多 2048 字节；容量不足跳过经验，不截断正文、不挤掉原始 Issue/契约/工具结果。动态摘要实际进入上下文后才开放对应详情；上下文容量按完整 SDK 消息投影加新消息核对。分析和 Verifier 不直接加载经验，经验引用不能申请当前原版契约修订。
+
+events.jsonl 和 trace 的 experience.triggered/retrieved/injected/omitted 分别说明实际情境、候选及匹配结果、实际加入上下文和省略原因。context_capacity 表示消息字节空间不足，context_threshold 表示加入后会越过 SDK token 阈值；这两种情况都省略经验。阈值通过 SDK 本地 count_tokens 估算并计入工具 schema，不调用 provider。trace 只增加受控 experience_trigger/experience_ids 元数据；不增加模型调用。整个功能不依赖 trace 开关。
 
 ## 什么时候写，谁写
 
@@ -43,7 +47,9 @@
 
 每卡最多 5 个短标签，每标签最多 64 个 Unicode 字符。重叠时优先选择具体框架约束，再选择生成错误模式，其余归工作流程。
 
-单个 JSON 库根字段为 schema_version=1 和 items；每卡包含 id、category、tags、summary、detail、source_task_id、evidence_refs，最终 UTF-8 JSON 最多 2048 字节，全库最多 1 MiB。ID 来自规范化 category/tags/summary 的 SHA256；同 ID 跳过，旧 detail 不覆盖。
+单个 JSON 库根字段为 schema_version=1 和 items；每卡包含 id、category、tags、summary、detail、source_task_id、evidence_refs，可选 triggers 为最多 3 个受控 kind/tool/code 条件。最终 UTF-8 JSON 最多 2048 字节，全库最多 1 MiB。旧卡缺 triggers 按空列表读取，空条件 ID 算法保持规范化 category/tags/summary 的 SHA256；非空条件也参与 ID，避免不同适用情境被误去重。同 ID 跳过，旧 detail 不覆盖。读取不改写旧库、不自动给旧卡补造条件。
+
+写入和检索共用同一套受控事件定义。模型仍只输出五字段，summary/detail 写明适用条件、实际观察和条件建议。程序核对所引用 EID 的冻结原子，从这些原子中的实际错误 metadata 或小型受控事件提取 triggers；不从摘要猜条件，不扫描本次所有工具，也不因任务 EXHAUSTED 就声称某个建议已有效。tool:/error: 标签由程序生成，模型的同名命名空间标签被去除，其余名额保留描述标签，总数仍最多 5 个。这只验证条件的事实来源，不证明建议语义或效果。
 
 写入时用稳定旁路文件做非阻塞系统锁，锁内重新读取、校验、去重和测量，再原子替换。竞争返回 busy；损坏或容量已满返回 store_error；旧库保留。MVP 只追加和精确去重，不自动合并、衰减、删卡、更新旧卡或扩容。
 
@@ -101,7 +107,7 @@ HTTP/token/费用总计已经包含真实学习尝试一次，learning 分项只
 
 离线测试验证真实 SDK + MockTransport + pytest 的调用、时序、引用和交付。提高复现率的结论必须来自固定模型/预算/环境、学习集与评测集分离、冻结库的关闭/开启对照；当前未执行真实模型 A/B。
 
-A/B 的有效性不能只看库的 ready/count：必须检查开启臂实际模型请求包含非空 experience_summaries，关闭臂未注入经验，并核对每次运行前后冻结库哈希不变。experience.matched 表示选中，不保证随后通过上下文容量检查而进入模型；read_experience 则表示是否进一步读详情。同用例生成的卡也可能因关键词零分而未匹配，不能强行注入后还称为当前匹配策略的自然效果。每臂至少两次只能作为小样本试验；同一 Issue 的学习后重跑衡量重复任务帮助，不能证明跨 Issue 泛化。
+A/B 的有效性不能只看库的 ready/count：必须检查开启臂实际模型请求包含非空 experience_summaries，关闭臂未注入经验，并核对每次运行前后冻结库哈希不变。experience.matched/experience.retrieved 表示选中，不保证随后通过上下文容量检查而进入模型；experience.injected 表示运行时实际加入，wire request 才是最终核对依据；read_experience 表示是否进一步读详情。有条件卡首轮零匹配不意味着后来无法检索，需要等对应真实事件发生后判断。若完整任务没有实际注入，停止把后续结果当作卡片效果，不强行补条件。每臂至少两次只能作为小样本试验；同一 Issue 的学习后重跑不能证明跨 Issue 泛化。
 
 开启经验功能，即使匹配结果为空，也可能增加 read_experience 工具。因此零命中不能推出两个运行的全部输入相同。若要测卡片内容的作用，可让控制臂读取有效空库、两臂都禁止写回并保留相同工具表；另外检查实际 wire request 的工具集一致。完全禁用经验与开启经验的对照则衡量整个功能开关，不能把差异单独归因于卡片内容。
 

docs/reviews/2026-10-12-experience-trigger-retrieval-acceptance.md

@@ -0,0 +1,62 @@
+# 经验写入与情境检索验收
+
+状态：实现、独立审查修复和最终完整回归完成。没有真实 provider 请求、没有解密密钥、没有 Astra 验收。
+
+基线 da7ac47，隔离分支 codex/experience-triggers。设计和计划分别为 docs/superpowers/specs/2026-10-12-experience-trigger-retrieval-design.md 与 docs/superpowers/plans/2026-10-12-experience-trigger-retrieval.md。
+
+## 已实现
+
+- 学习模型保持五字段契约；提示词写明条件、事实、建议和不确定性。程序验证 EID/哈希后，从所引冻结受控事实提取 kind/tool/code，生成规范 tool:/error: 标签，保存可选 triggers。没有全程工具列表的泛匹配，没有从错误文本猜条件。
+- 同一冻结库支持首轮问题召回和探索中实际事件召回。过程卡不能因 Issue 词碰巧重合而提前注入。原位库变更不影响当前视图。
+- AgentScope 公共 on_acting/on_check_permission 及原有协议纠错路径通知真实事件。下一次已有模型请求之前补充有界 advisory UserMsg；不重跑工具、不增加模型请求或步数。
+- 累计最多 3 条摘要，共享 2048 B（含唯一一次成功详情）；跨阶段不重置。容量不足卡、上下文未加入的卡不能读取；取消/结束阶段不注入。
+- 新增 experience.triggered/retrieved/injected/omitted 事件及两项受控 trace 属性。学习同时保留小型受控错误事实，完整参数超限时仍可引用这种事实，但不假装完整经过已保留。
+
+## 证据
+
+| 验收 | 结果 |
+| --- | --- |
+| 基线 | 19 passed |
+| 写入 RED | 5 failed / 1 passed，缺 triggers 和同情境去重错误已复现 |
+| 写入 GREEN | 81 passed / 1 skipped，53.33s |
+| 视图 RED / GREEN | 7 failed -> 13 passed |
+| SDK 动态注入 RED | 4 failed / 2 passed，真实 SDK/mock HTTP 确认缺失路径 |
+| SDK/工具/权限回归 | 66 passed，20.86s |
+| 额外事实/trace/材料/采集检查 | 48 passed，33.15s |
+| Viewer | 8 passed |
+| 审查修复/旧库/SDK/launcher | 74 passed / 1 skipped，12.11s |
+| wheel 安装与资源预检 | 3 passed，33.64s |
+| 仓库外 SWT 对照/来源复核 | 17 passed，30.23s |
+| 最终完整 pytest（f828a79，仓库外 basetemp） | 827 passed / 5 skipped，690.76s，exit 0 |
+
+两项边界先 RED 再 GREEN：空白标签不能冒充保留检索命名空间；上下文 append 失败不能提前开放详情。trace 白名单缺失及小型受控事实保留也分别复现后修复。
+
+## 独立审查与修复
+
+GPT-6.1-sol 新上下文只读审查 da7ac47..9b4216d，发现三项 Important，均独立复现 RED 后修复：
+
+1. 旧卡恰好 2048B 加空 triggers 后误关整库：空条件持久化不写可选字段，按 _card_record 的实际字节计量；原始 2048B 记录可读且追加后保持同形内容。
+2. exploration.tool_error 的诊断 I/O 失败会丢 SDK 终态：隔离新增可选事件写入，原始工具响应保持交付，不重跑工具。
+3. 大消息上限下摘要可绕过 SDK 压缩阈值：异步注入前用 SDK 本地 count_tokens（包含工具 schema）测量候选完整输入，超阈值省略历史建议；无额外 provider 调用。
+
+审查还复现独立 ExperienceView API 的 pending-summary -> detail-read -> admission 超额。正常 SDK 原路径没有这种交错；本轮把它作为类的预算不变量修复，详情计入待注入摘要，admission 再核对总量。相关测试分别先 RED 后 GREEN。
+
+审查未判断真实复现收益（留待授权 A/B）、旧 reader 接收新卡（不承诺反向兼容）；两项边界明确保留。没有再次派发审查，按要求用覆盖测试和最终完整回归确认修复。
+
+初次完整验收在源修复前停止；其中六项 launcher 失败是新工作区缺 .venv，已建立私有 Python 并复用既有本地依赖，无下载。后续 launcher 和 wheel 预检通过，不将环境缺失计为产品修复。
+
+修复后首次完整运行因把 basetemp 放在 E:/ReproAgent 内，得到 8 failed / 819 passed / 5 skipped（767.82s）。七项 SWT 对照临时项目继承外层 pytest 配置，节点 ID 多出仓库路径前缀；一项来源测试继承外层 Git。实际 buggy/fixed 调用结果正确，不修改产品来适配测试目录。改用 C:/Users/Dell/AppData/Local/Temp/reproagent-experience-triggers-verification/swt 后，相关 17 项全部通过。完整回归使用该仓库外目录下独立 full 子目录；原失败记录保留，不当作通过证据。
+
+真实 SDK 离线闭环：实际 revise_contract 失败 -> ToolResponse metadata -> capture_exploration -> 冻结证据 EID -> 五字段提案程序校验 -> 追加经验库 -> 新任务加载同卡 -> 对应真实拒绝 -> 下一 wire 请求含摘要。前一请求没有过程摘要，原始 tool result 完整保留；库字节不变。
+
+## 限制和后续评测
+
+旧卡按原关键词方式可读，未凭空补造 triggers；新版 reader 能读旧卡，旧程序不保证能读新增元数据。历史 ab2 那张卡没有结构化错误 metadata，不能声称它已经因本改动自动变成可触发卡。真实新学习要使用本分支代码生成新库。
+
+程序验证了触发条件的事实来源，没有验证自然语言建议的全部语义或因果效果。支持的受控错误是有限集合；未覆盖的错误继续使用既有路径。零命中和容量不足在观测中有原因。
+
+A/B 必须保持相同工具表、模型/环境/预算及冻结库。过程卡允许首轮零匹配，在对应事件后核对实际 wire 注入；整个任务没有注入时不宣称卡片效果。不要继续使用只在首轮 zero_natural_matches 就停止的旧运行器验证过程卡。每臂两次仅小样本，不能证明稳定收益或泛化。
+
+完整验证日志位于 E:/ReproAgent/.local/experience-triggers/；最终日志 full-outside.log，退出码 full-outside.exit=0。计划执行账本和审查包备份在该目录的 execution-ledger.md、review-da7ac47..9b4216d.diff。当前分支 codex/experience-triggers 保留，未 push 或合并到 main。
+
+收尾决策：用户已要求直接执行，本计划明确保留分支且不 push/合并，因此按该已定范围完成，没有再次要求选择集成方式。测试代码及运行源码在最终完整回归期间保持 f828a79；后续仅更新计划和验收文档。没有遗留 Minor 修复项；真实模型收益和旧 reader 读取新卡仍属于上述边界。