# 产品目标与用户故事

## 1. 产品定义

Finding Ledger 是一个面向 Agent 的持久化工程发现账本。它记录开发者与 Agent 在实验、调试、代码阅读和方案决策过程中产生的可复用结论，并保留其证据、适用范围、状态变化和关联历史。

它不是完整的会话记忆系统，也不是文档检索系统。产品目标是减少重复排查与错误知识复用，让 Agent 在跨会话工作时继承“当前仍值得相信的结论”，而非只恢复一段摘要。

## 2. 目标用户与高频任务

主要用户是使用 Agent 进行持续工程工作的开发者、研究人员和技术负责人，典型任务包括：
- 多轮实验和根因定位；
- 跨会话修改复杂代码库；
- 上下文压缩后继续排查；
- 对已排除路径避免重复消耗算力；
- 在修改代码、配置或依赖后判断旧结论是否仍适用。

非目标用户场景包括一般聊天偏好记忆、通用个人知识库、自动索引全部文件，以及替代项目设计文档或任务管理系统。

## 3. 核心用户故事

### US-01：压缩后继续排查
作为工程开发者，我希望上下文压缩后能恢复当前任务相关的关键发现，以便继续从已有进展工作，而不是重新执行相同探针。

验收：
- 恢复内容来自当前项目，且经过 scope 检查；
- 支持结论、已排除路径与用户约束在呈现上明确区分；
- 每条注入记录有 finding ID 和证据摘要；
- 注入受 token 预算约束，不复制整个历史记录。

### US-02：保存有证据的发现
作为实验执行者，我希望能保存一条短结论并关联日志、实验、代码位置或用户陈述，以便之后验证和追溯。

验收：
- statement 可独立理解，不依赖原会话的代词或上下文；
- 来源类型、精确定位符和证据作用分别保存；
- 缺乏证据的主张不能仅凭措辞自动升级为 supported；
- 一个证据来源可被多个 findings 复用。

### US-03：跨会话查找既有结论
作为长期任务的负责人，我希望新会话能按项目与任务检索已有发现，以便会话切换不导致工程知识断层。

验收：
- 项目 identity 不只依赖当前 cwd 字符串；
- 支持关键词、标签、状态和 scope 过滤；
- 支持从简短结果按 ID 取得完整证据；
- 默认查询不混入其他项目的发现。

### US-04：反证或取代错误结论
作为发现先前判断有误的开发者，我希望能反证旧结论并保存纠正依据，以便 Agent 不再重复引用错误判断，同时保留排查历史。

验收：
- 反证不会删除 finding；
- 反证必须保存理由，并优先关联反证证据；
- 新结论取代旧结论时，关联关系与生命周期状态在同一事务中更新；
- 历史记录可追溯，但不会默认作为当前事实重复注入。

### US-05：判断结论的适用性
作为切换分支、模型、配置或运行环境的开发者，我希望系统区分历史结果与当前可用结论，以便旧实验不会被不加判断地套用到新环境。

验收：
- 适用条件可以包含任务、commit、依赖、后端、dtype 和配置等信息；
- 区分硬性匹配条件与仅用于追溯的上下文；
- 条件不明时降级为“待核验/历史参考”，而非无条件复用；
- 关键环境变化可触发重新验证提示。

### US-06：沉淀可复用的项目规则
作为项目维护者，我希望把稳定发现提议为 AGENTS.md 规则，以便常见约束进入日常工作流程。

验收：
- 转换为规则前展示来源与理由；
- 用户批准与写入完成是两个不同状态；
- 规则文档与 ledger 保留互相引用；
- 默认不自动将任意 finding 写入项目规则。

## 4. 产品成功指标

第一阶段只需评估下列指标，不将数据库记录总量或自动写入数量作为成功标准：

| 指标 | 定义 |
|---|---|
| 重复探针率 | 上下文压缩或换会话后重复执行已记录探针的比例 |
| 关键结论召回率 | 后续任务需要的有效结论中，被正确检索到的比例 |
| 错误复用率 | 已反证、已取代或 scope 不匹配的结论被当作当前事实使用的比例 |
| 过期注入率 | 环境变化后仍被直接注入为当前适用结论的比例 |
| 上下文成本 | 每次恢复注入的 token 数及其带来的任务收益 |
| 证据可追溯率 | 注入的结论中，可以追溯到有效来源的比例 |

## 5. 产品原则

- **准确性高于自动化率：** 状态不确定时保留不确定性。
- **可追溯高于摘要美观：** 结论必须能回到证据。
- **适用性高于历史强度：** 旧结论不因过去被验证过就自动适用于新条件。
- **最小上下文：** 注入结论与必要条件，细节通过查询按需加载。
- **用户保有纠错权：** 对外部副作用、规则沉淀和敏感信息保留明确控制。