# 安全、评测与实施路线图

## 1. 风险模型

Finding Ledger 会将工程判断持久化，并在之后再次呈现给 Agent。主要风险来自错误结论的长期传播、适用范围误判、敏感数据保留和注入内容失控。

| 风险 | 可能后果 | 缓解措施 |
|---|---|---|
| 无证据的猜测被提升为事实 | 后续推理持续建立在错误前提上 | 默认 unassessed/provisional；supported 必须通过证据校验 |
| Scope 过宽 | 将其他版本或任务中的发现错误复用 | match/context 分开；未知条件不默认匹配 |
| 证据源发生变化 | 引用指向不同内容，原判断失去依据 | 记录 revision/content_hash；来源变化时提示核验 |
| 反证丢失或被覆盖 | Agent 重走已排除路径 | 保留反证状态、证据和事件，不用静默覆盖纠错 |
| 注入内容过多 | 上下文被历史记录占满 | 确定性检索、token 预算、短摘要和按需展开 |
| 不可信文本进入 evidence | 外部网页或日志中的指令被误当成系统指令 | 证据是数据，不作为指令执行；限制摘要和外链加载 |
| 项目之间泄漏 | 一个项目的约束或结论出现在另一个项目 | 稳定 project identity；跨项目共享默认关闭 |
| 敏感数据被保存 | 凭据、个人信息或客户数据长期留存 | 写入前脱敏、限制 excerpt、提供受控清理流程 |

## 2. 安全和隐私要求

- **本地优先：** 数据库默认保存在用户控制的位置；没有明确需求时，不上传完整日志或证据内容。
- **最小留存：** 保存定位符和必要摘要，原始日志尽量留在原系统。
- **秘密信息过滤：** 对 API key、凭据、cookie、私密路径和客户数据进行脱敏或拒绝持久化。
- **来源视为不可信数据：** finding/evidence 可能来自外部网页、日志或用户粘贴内容，其中的指令不能直接执行。
- **项目隔离：** 查询先确定项目身份；跨项目检索必须明确启用。
- **副作用审批：** 修改 AGENTS.md 或其他项目文件前，需要明确授权与审阅。
- **可纠错与清理：** 提供撤回、归档、按项目导出和受控删除能力。

## 3. 测试策略

### 单元测试
- claim_kind、epistemic_state、lifecycle_state 的枚举及组合；
- evidence relation 与 finding relation 的语义区分；
- scope_json 校验和 unknown/incompatible 判定；
- 状态转换规则与非法转换拒绝；
- supersedes 自指、取代环和目标不存在；
- 关键字段变更是否生成事件；
- project identity 规范化。

### 存储和事务测试
- 数据库连接启用外键约束；
- refute_finding 的证据、状态和事件写入全成或全败；
- supersede_finding 的创建、关系、生命周期和事件写入全成或全败；
- 幂等请求不会产生不受控的重复记录；
- 并发状态更新可检测冲突；
- schema_migrations 能阻止同一 schema 版本脚本被重复应用。

### 检索与注入测试
- supported 且 applicable 的关键 finding 能被找回；
- refuted 项以已排除路径呈现，不会被当成支持性结论；
- scope 不兼容的记录不会作为当前事实注入；
- superseded 项默认只以必要的历史关系摘要出现；
- scope unknown 的记录带警告或进入核验流程；
- token 预算不足时仍保留状态、ID 和硬性适用条件；
- 数据库或宿主事件失败时有明确回退，不阻塞主要任务。

### 回归测试案例
1. 同一项目、同一版本的重复调试；
2. 代码变更后查询历史发现；
3. 同一结论在不同配置下有不同结果；
4. 结论被反证；
5. 新结论取代旧结论；
6. 用户约束与实验事实混合；
7. 两条结论互相冲突但适用范围不同；
8. 引用路径不可访问或内容哈希变化。

## 4. 评测方案

将 ledger 检索与无 ledger、全部历史注入等基线对比，至少测量：

- **重复排查率：** 已记录且适用的探针被重复执行的比例；
- **关键结论召回率：** 后续任务需要的有效 finding 被找回的比例；
- **错误复用率：** 已反证、被取代或 scope 不匹配的记录被当成当前事实使用的比例；
- **过期注入率：** 环境变化后仍被直接呈现为当前适用结论的比例；
- **证据追溯率：** 注入结论中可以定位原始来源的比例；
- **token 效率：** 每千 token 带来的重复步骤减少量或任务成功率变化；
- **延迟：** 新会话初始化与压缩后恢复的检索耗时。

评测不能只看召回率。若记忆提高召回，却增加过期知识误用，整体收益可能为负。每项指标都应有可重复的测试集和计算定义。

## 5. 实施路线图

### P0：可信数据闭环
- 实现核心 schema 与 schema version tracking；
- 实现 log_finding、query_findings、get_finding、add_evidence；
- 实现状态变更、refute_finding 和 supersede_finding；
- 保证事务一致性并记录关键事件；
- 完成单元测试与集成测试。

完成标准：未经证据校验的主张不能被直接标为 supported；反证与取代操作全成或全败；结论演化可追溯。

### P1：项目与 Scope 可靠性
- 实现稳定 project identity；
- 实现 scope match/context/revalidate_on 解析器；
- 实现项目隔离、适用性提示和 needs_revalidation 行为；
- 实现证据来源可访问性与内容变化检查。

完成标准：明确不适用的 finding 不会作为当前事实注入；条件未知时不默认适用。

### P2：宿主集成与预算化注入
- 验证实际 harness 事件与 prompt assembly 接口；
- 支持新会话和 compaction 后检索；
- 实现状态感知的提示词格式化；
- 实现 token budget、错误回退和注入日志。

完成标准：压缩恢复稳定，注入内容可追溯且有上限，数据库故障不阻塞用户的主要任务。

### P3：评测驱动优化
- 建立有人工标注的回归案例集；
- 评估标签、关键词和结构化条件检索的召回；
- 只有在基准测试证明必要时再引入 embedding/reranker；
- 评估候选发现、去重与冲突提示；
- 检验用户审批下的规则沉淀流程。

完成标准：以可重复指标证明重复排查或错误复用下降，且 token 与延迟成本可接受。

## 6. 首期明确不做的能力

- 未经校准的 0–1 confidence 字段；
- 根据措辞或模型自评自动提升证据状态；
- 在缺乏评测依据时引入向量数据库或远程存储；
- 自动把所有会话结论写入账本；
- 仅按记录年龄判定结论过期；
- 未经用户批准修改项目规则；
- 将 Finding Ledger 扩展为完整会话存档或文档平台。