# Lynn Scenario Contract 规划

## 背景

Lynn 现在已经能覆盖搜索、行情、文件、桌面任务、多媒体和长报告，但问题开始从“有没有入口”变成“每类任务怎样才算真正完成”。继续按单点修补会导致每个概念股、每个金价源、每种文件都要发一次包，体验会越来越碎。

Scenario Contract 的目标是给每类任务统一定义：

- 触发条件：用户怎么问时进入这个场景。
- 必需证据：回答前必须拿到什么。
- 直答模板：第一屏要给什么结果。
- 失败兜底：主源失败时怎么换源，仍失败时怎么说。
- 回归测试：以后每次发版都用同一组题目验收。

## 七类场景

### 1. 实时数据类

范围：金价、原油、汇率、天气、航班、体育比分、股价。

完成标准：

- 必须给数字、时间戳、来源。
- 主源拿不到就换源，不能输出“建议你去看某平台”来代替结果。
- 多口径问题要先给最常用口径，再说明差异，例如国际金价、上金所、品牌金饰、回收价。

失败兜底：

- 说明已尝试的来源和失败原因。
- 给用户一个最小补充项，例如截图、具体代码、城市或口径。

优先迁移点：

- 金价、布伦特、天气、股价已经有样板。
- 下一步统一为 `realtime_data` contract，要求所有工具输出 `value/source/timestamp`。

### 2. 行情/研究类

范围：股票、概念股、行业板块、深度报告、房地产。

完成标准：

- 先建候选池，例如港股科技股、美股七姐妹、A 股太空光伏、DeepSeek 概念股。
- 再批量拉数据，例如报价、涨跌幅、成交额、基本面、公告、资金面。
- 最后输出结论排序，不能只有标题和“点击查看完整报告”。

失败兜底：

- 候选池不足时先交付已验证标的，不伪造完整榜单。
- 数据源不足时明确缺少哪类证据，例如成交、财报、公告、房价、容积率。

优先迁移点：

- 股票/概念股走通用候选池，不再为每个概念单独发版。
- 房地产沿用同一模式：基准项目池、候选项目池、批量指标、匹配度排序。

### 3. 新闻/事实类

范围：最新新闻、政策、公司动态、国际事件。

完成标准：

- 按时间排序。
- 交叉验证关键事实。
- 区分“发生了什么”和“市场/舆论解读”。

失败兜底：

- 没有可靠来源时直接说未核验。
- 不把旧闻、传闻、搜索摘要当成事实。

### 4. 文档/文件类

范围：PDF、Word、Excel、合同、桌面文件、合并报表。

完成标准：

- 必须真实读取文件。
- 列出读到的文件名、页数、表名、段落或行数。
- 没读到不能假装分析。

失败兜底：

- 明确是路径不对、权限不足、格式不支持，还是文件内容为空。
- 给用户一个可恢复动作，例如重新拖入文件或提供路径。

### 5. 本地任务/自动化类

范围：整理桌面、定时提醒、批量改名、生成 HTML/Markdown/PPT。

完成标准：

- 执行前有状态快照。
- 执行中有真实动作。
- 执行后有结果和可恢复信息。
- 用户不要留痕时，不写巡检报告，不制造用户噪音。

失败兜底：

- 不做危险写入。
- 失败时保留原文件和可恢复路径。

### 6. 多媒体类

范围：图片识别、TTS、ASR、图片生成。

完成标准：

- 附件必须可靠进入模型。
- TTS/ASR 先做服务健康检查。
- fallback 要明确，例如 CosyVoice 不可用才转 macOS say，且 UI 要告诉用户。

失败兜底：

- 没拿到图片或音频时直接提示重新上传或提供路径。
- 不假装看过图片、听过音频。

### 7. 长任务/Agent 类

范围：深度研究、项目代码分析、复杂报告、连续多步任务。

完成标准：

- 拆任务。
- 拿证据。
- 必要时运行脚本。
- 生成中间产物。
- 最后交付完整结果。
- 不允许“伪深度”或空壳报告。

失败兜底：

- 超时或资料不足时交付当前进度、证据清单和下一步。
- 不输出只有目录、没有内容的报告。

## 推进节奏

### Phase 0：契约层

- 新增 `shared/scenario-contracts.js`。
- 为七类场景补分类和 hint。
- 加单测，保证每类典型用户问题会进入正确 contract。

### Phase 1：接入高频链路

- 在本地 session prompt 中注入场景契约。
- 优先覆盖实时数据、文档读取、深度报告、本地自动化。
- 对“拿不到证据还长篇解释”的场景加直答失败模板。

### Phase 2：统一证据对象

- 工具输出统一增加 `evidence` 字段：`value/source/timestamp/confidence`。
- 行情/研究类增加候选池对象：`candidates/quotes/sources/gaps`。
- 文档类增加读取证明：`files/pages/sheets/sections`。

### Phase 3：回归矩阵

- 建立七类场景 smoke tests。
- 发版前固定跑：金价、天气、布伦特、港股科技股、概念股、PDF/Word、图片、TTS/ASR、深度报告。

## 原则

- 用户要什么就研究什么，不固化单只股票或单个概念。
- 先证据，后结论。
- 有结果先直答，再补解释。
- 没证据就换源，仍失败才问用户。
- 发包跟着能力层走，不跟着每个概念走。
