spec: 升级 Agent 证据编排、分析契约与真实阶段展示 #346

Problem Statement

用户希望围绕本人绑定的练习提交获得有依据、可核对的分析。现有 Agent 已具备上下文重新读取、只读模型工具循环、引用核验、独立 judge、预算和运行隔离，但题目与评论的运行时投影缺少完整来源信息，普通在线检索仍使用固定合成语料。用户难以判断结论究竟来自提交事实、题目、评论还是通用材料，也无法完整看到资料读取、分析和核验阶段。

本规格基于三方只读规划及关键源码核对；这里的现状是规划基线，不代表已完成产品运行验收。实现前需重新确认当前源码。首个实现批次仅交付 P1。

Solution

增强证据编排，沿用现有 Agent 内核。用户选择的题目、评论和既有模式下逐轮授权的源码，成为具有来源、范围和本轮读取标识的请求期资料；回答只引用本轮实际取得且通过核验的片段。系统区分事实、判断、假设和下一步，并显示实际执行阶段。

按 P1 真实证据接线、P2 分析契约、P3 真实阶段展示、P4 联合验收发布推进。保留当前答案协议、SQLite 结构、身份授权、预算、取消隔离和确定性保存流程。

User Stories

1. 作为练习用户，我希望分析绑定本人合格提交，以便避免串用他人的提交或比赛上下文。
2. 作为练习用户，我希望所选题目在分析时重新读取并核对归属，以便回答使用正确材料。
3. 作为练习用户，我希望所选题解评论与论坛评论分别标识，以便理解它们的来源与适用范围。
4. 作为练习用户，我希望评论只被用来说明评论提出了什么，以便不会把他人的观点误当作我的代码事实。
5. 作为练习用户，我希望每轮自行决定是否按已有模式授权源码外发，以便保持对源码使用的控制。
6. 作为练习用户，我希望没有源码时系统不诊断具体实现缺陷，以便避免误导。
7. 作为练习用户，我希望引用能对应本轮实际取得的片段，以便核对回答依据。
8. 作为练习用户，我希望资料被截断时得到明确说明，以便了解分析范围。
9. 作为练习用户，我希望资料不可访问或已经失效时在分析前看到失败，以便不为无效分析消耗模型额度。
10. 作为练习用户，我希望无命中时系统明确说明材料不足，同时仍能解释已知状态或给出一般建议。
11. 作为练习用户，我希望系统不把合成测试资料当作真实分析依据，以便信任引用的来源。
12. 作为练习用户，我希望事实、判断、假设和下一步容易区分，以便知道哪些结论仍需验证。
13. 作为练习用户，我希望核验失败保持可见，以便不会把删减后的回答误认为完整成功。
14. 作为练习用户，我希望看到实际的读取、分析和核验进度，以便知道当前正在做什么。
15. 作为练习用户，我希望取消、重试和重连不串轮，以便旧运行结果不会覆盖当前会话。
16. 作为练习用户，我希望刷新后仍能读取历史回答，同时旧历史缺少新增阶段信息时也能正常显示。
17. 作为练习用户，我希望源码正文不进入可见回答、历史、事件或检查点，以便保护私有实现。
18. 作为练习用户，我希望确认学习计划与保存计划保持独立，以便只有明确保存才产生业务写入。
19. 作为运营者，我希望模型用量未知或预算超限时系统拒绝放行，以便账目与实际执行保持一致。
20. 作为运营者，我希望升级可逐批验收和回滚，以便出现安全或兼容问题时暂停分析而不丢失数据。

Implementation Decisions

保持的边界

• Agent 继续是独立 Python 服务，通过现有 Auth/App HTTP 契约工作，不连接业务数据库。
• 保留一个有界只读模型工具循环及现有引用 judge，不新增模型可控写工具。
• 保留本人、普通练习、已知终态提交资格检查；不扩大已有源码授权模式。
• 确认不等于保存；保存结果未知时沿用原幂等键恢复。
• 保留现有管理员开关、模型预算 purpose、用量核验和运行隔离。
• 抓取正文只在请求内存存在；不新增数据库表或分析 JSON 列。

P1：请求期资料与检索

• 每项文本资料保留种类、已验证对象标识、本轮读取标识、访问范围、信任标记、位置、截断标记和有界正文。
• 文本统一视为 untrusted-data；访问校验通过不等于内容可信。评论不并入可信提交事实。
• 提交事实只保留现有必要字段，不顺带加入测试输入、输出、预期值或错误详情等信息。
• 不假设上游存在 updatedAt、作者或版本接口。没有可靠上游版本时以本轮 runId 标识快照，不宣称它是上游历史版本。
• 一轮使用取得的快照，下一轮重新读取。读取校验不是持续授权保证；不承诺模型调用途中能够感知上游权限撤销。
• 保留题目最多 8,000 字并标记截断、两类评论合计最多三条且每条超过 2,000 字拒绝的现有语义；源码保留原有上限和逐轮同意机制。
• 题目与评论按确定性范围形成片段，片段目标上限沿用现有 1,200 字。长单行必须有界，每片身份唯一且能定位回本轮原始范围。
• 复用现有资料文档、关键词检索及引用结构；查询最多返回三条命中，答案最多三条引用。不重复把全部正文与全部片段塞进提示词。
• 服务端 retrieved 只记录实际交给模型的命中；引用继续检查同轮命中、来源完整性及 supports/derivable。
• 普通在线产品路径不回落合成语料；测试可以显式注入合成资料。P1 不自动接入仓库文档或外部资料库。
• 无命中时允许解释已知提交状态和给一般建议，但不伪造引用或断言具体实现缺陷。
• 评论可支持“该评论提出某建议”的归因，不能支持“该提交存在某缺陷”的实现判断。judge 的可信事实与评论文本分开；仅含“评论”关键词不是充分核验。
• 来源位置由服务端生成，模型提供的 URL 不直接成为可点击导航。

P2：答案与核验

• 保留严格的 text/citations 答案协议，沿用 citation.claim 建立结论和依据的关系；不新增公开 claims 数组或 envelope v2。
• 在正文按需要表达已知事实、分析判断、待验证假设和下一步，不强制每次出现四个标题，不为一般建议伪造引用。
• 没有源码时不把“可能”作为绕过具体实现诊断限制的方式。
• 核验失败仍是可见失败，不静默删除失败主张后报告成功，不自动重复模型调用掩盖失败。

P3：真实阶段与兼容

• 在实际执行边界发出阶段开始/结束事件，阶段限定为 evidence、analysis、verification；保留具体模型和工具事件。
• 阶段 detail 仅包含阶段枚举、结果和安全原因码；runId、seq、时间沿用现有事件封装。
• 不放正文、claim、提示词、源码、来源路径、模型自由文本或私有推理，不显示推测完成百分比。
• 桌面端复用现有 Trace、安全 Markdown、取消入口和错误分类；保留中英文文案。
• 重连使用既有 after 游标，事件重放幂等；旧运行或取消后的迟到事件不能覆盖新状态。
• 旧历史缺少阶段事件仍可读取；新事件保持客户端兼容，不新增存储状态机或迁移。

Testing Decisions

以现有认证 HTTP 分析入口为主要测试接缝：注入可控模型与上游响应，观察响应、实际模型调用次数、事件和持久化结果。前端在既有会话状态与工作区组件边界验证，不测试内部函数排列。低层检索测试只补分片和定位等 HTTP 入口难以精确覆盖的边界。

复用现有 Agent 服务、检索、引用、注入防护、安全和会话事件测试，以及 Console API、会话状态和工作区测试。每批从受影响检查开始，不另建烟测框架。

P1 优先执行受影响 Agent 测试；P3 加 Console 相关测试、类型检查和适用 lint。所有实现批次审查差异和空白问题，同步受影响核心文档；文档变动影响语料版本时同步绑定。

P4 真实模型验收使用明确授权的测试资料、目标环境和预算：AC、WA 各覆盖“题目加评论”“仅题目”“无选材”；已有授权源码模式另测，不借此扩大普通模式能力。每例核对回答语义、引用、用量和失败原因。completed 不是质量通过；安全拒绝也不冒充功能成功。首次结果建立基线，不预设成本、通过率或延迟收益。

Out of Scope

• 四套 Agent 服务/循环/存储、嵌套委派、多 Agent 并行。
• 向量数据库、通用代码沙箱、外部知识库、自动引入仓库文档。
• 新的源码授权能力、业务数据库直连、模型可控写工具。
• claims 关系图、新答案协议、额外分析存储列、多套模式开关。
• 移动端改造、私有推理展示、虚构进度或置信度分数。
• 执行本规格、部署产品或把规划状态标成已验收。

Further Notes

任务与依赖

四个交付批次

• P1：T1–T3 为首个可独立合并、完整回滚的 PR，不单独交付暂时失效的中间接线。
• P2：T4；P1 通过后合并。
• P3：T5–T6；阶段契约稳定后可与 P2 部分实现并行。
• P4：T7；无代码问题时不创建空 PR，必要修复单独交付。

上线与回滚

发现未验证引用被放行、源码或阶段载荷泄漏、用量未知仍成功、跨轮污染时，使用既有管理员开关暂停分析。各批整体回滚到上一应用版本，保留 SQLite、历史、幂等记录与预算账本，不删除数据、不重置账目。

决策与执行状态

P1（T1–T3）已通过 PR #347 合并，合并提交 dba541f；本地 1,214 项 Agent 测试和当前 head CI 通过，Sol 与远端评审发现均已解决。P2 已通过 PR #348 合并，合并提交 360f8a9；1,214 项 Agent 测试、独立评审及当前 head CI 通过，未变更答案协议或存储。P3 已通过 PR #349 合并，合并提交 6733cec；1,214 项 Agent 测试、863 项 Console 测试、两轮独立评审及当前 head CI 通过。CI 的干净安装与真实业务生命周期检查通过，但不等于真实模型验收。P4 已通过下述限定场景验收，修复经 PR #351 合并；允许现有授权范围内的 opt-in 代码交付，未执行生产部署或扩大启用。ready-for-agent 为原规划标签，不代表生产发布授权。

规划由 Claude Code 通道、Codex 和 DSH 协同形成并经主流程核对。执行元数据表明 Claude Code 通道请求 Sonnet 5.5，实际运行 DeepSeek，因此不能将其表述为三个不同模型的独立结论。这是执行限制，不影响上述约束需要逐条验证。

P4 初始验收（失败基线，保留记录）

已使用本地真实 Auth/App/Submission/Judge、专用测试账号及现有手动预算，取得 AC/WA 两类真实提交，执行各自无选材、仅题面、题面加评论六个场景，并额外执行逐轮授权源码场景。保留了初始失败及修正后的独立记录，没有把重试结果替换成初始成功。

最近六场中 3 场服务端 completed，但只有 AC 无选材回答完成了用户任务；两场题面加评论仅承诺将检索，没有实际工具调用或分析，不能算功能通过。其余三场被边界核验拒绝；额外授权源码场景也未通过。首次还观察到引用 text 为空的协议错误，解析器保持拒绝。P4 功能与回答质量尚不达标，发布判断为不放行，保持现有默认关闭及管理员开关。 剩余工作是定位真实模型未执行检索、空引用或仅输出行动承诺的决策/协议问题，再以同一六场景与源码场景复验；不能通过放宽引用、诊断或预算门禁解决。

已定位一处可独立修复的边界误拦：合法本轮选材引用不能与源码限制说明并存。修复仅允许服务器本轮授权的题面/评论继续走原完整性和独立 judge，旧轮、源码及其他语料仍拒绝；同时明确要求调用 search_evidence，目录本身不是引用依据。离线 Agent 1,221 项通过，修复已通过 PR #350 合并，合并提交 e1ef517；独立评审与当前 head CI 均通过。该补丁不代表 P4 实模质量验收通过。

本次新增 14 次有回执调用，按现有费率记账 7,194 micro-USD（不是平台账单确认）；guard 与账本一致，无未知或未结算用量。未重置、增额或新建预算周期。测试开关已恢复原值，测试服务端口已核对关闭，原先运行的 MeiliSearch 保留，未部署生产。

P4 最终验收与交付

修复已通过 PR #351 合并，合并提交 11fe29371ecfdba874a73fa2766aa83eafa946f3；已核对最终 head 84f2c1270aea3a01c0938680360d0c4892b576d3 的必需 CI 通过、自动评审完成且无未解决发现，分支与 main 同步。当前提交本地完整 Agent 套件 1,237 passed；文档契约与空白检查通过。前三轮独立评审最终 APPROVE，并独立运行 301 项相关测试；后续 bot 指出的未来判定误拦已另行复现、修复并通过 15 项定向回归及完整套件。

真实验收经正式 runtime.py、本地 Auth/App/Submission/Judge、DeepSeek 和 Console /api 入口执行，未使用诊断替代运行时。所需七场景加一个混合来源场景均 HTTP 200、completed，且逐篇核对回答内容：

八篇回答均完成当前分析任务；有材料时实际检索并引用本轮证据，无材料时保留合理的空引用并明确限制。评论仅支持归因，源码实现判断须有授权源码依据。真实 judge 正反探针覆盖证据限制说明、无源码因果诊断、只承诺行动、合法任意顺序建议以及违背题面保证的建议；不以 completed 状态代替语义验收。

证据覆盖限制： 八场实模运行之后进一步收窄了无引用因果诊断的 review 资格，并修复假设未来判定的状态误拦。保存的无引用答案经新资格谓词确定性 replay 均保持原核验路径；最终回归覆盖新增硬拒绝和状态条件。没有声称在这些最后修改后又执行一轮付费模型矩阵，也没有将既有实测宣称为对所有输入的可靠性证明。

累计账本 500 次尝试，已记录实际成本 396,961 micro-USD（约 $0.397，非供应商账单确认），500 条 guard 回执与账本对齐；unknown/unsettled/pending 均为零。未重置预算、增额或新增周期。早期失败及题面保证冲突的回答保留为失败记录，无自动生成重试掩盖结果。

本地证据位于任务工作树 ignored .local/p4-execution/：matrix.json、acceptance.json、hard-guard-replay.json、budget-after.json、agent-tests-followup.log，以及各正反 probe 记录。测试服务已停止，专用 PM2 应用清空，测试开关恢复原值；保留原运行的 MeiliSearch、历史和预算账本。

发布判断： P4 在上述限定资料与场景内验收通过，代码交付完成。允许沿用现有授权和管理员开关进行 opt-in 使用；本任务未部署生产、未扩大默认启用范围。模型语义判断仍有局限。若发现未验证引用、源码泄漏、未知用量放行或跨轮污染，使用既有管理员开关暂停，并回滚上一应用版本；保留 SQLite、历史、幂等记录与预算账本，不删除数据或重置账目。

完成清单

• P1：本轮实际资料接线、无合成回落、来源和权限边界通过验收
• P2：分析契约与引用语义通过验收
• P3：真实阶段事件及桌面兼容通过验收
• P4：产品入口联合验收、预算证据、发布与回滚决策完成（限定场景，未部署生产）