# dsh-scout 产品契约

状态：Draft 0.1
目标：把公司与岗位尽调收敛为一个可复现、可追溯、能支持下一步行动的 DSH 场景插件。

当前实现进度：首个公开切片已经覆盖 session 隔离的内存 case、封闭来源类型、主体核验、claim 证据历史、保守三态决策、结构化报告、卸载清理和临时 DSH profile 安装门禁；v0.2 已落地持久化五文件导出（`scout_export` / `scout_import`，含可回放事件流 `events.jsonl` 与导入后决策重算）；v0.3 已落地可配置存储（`scoutDir` / `autoPersist` 插件配置）与面试问题生成（`scout_questions`）；v0.4 已落地信息采集登记（`scout_ingest`：批量登记采集结果并按 URL 自动推断来源类型与证据等级）；v0.5 已落地公司/岗位对比（`scout_compare`：2–5 案例并排对比报告与合并面试问题）；v0.6 已落地采集→主张流转（`scout_ingest` 支持 claim 草稿，登记来源同时自动添加主张）；v0.7 已落地 Provider 深度集成（`scout_search`：接入 DSH Web Provider，搜索结果自动登记为来源）。

## 1. 产品承诺

给定一个公司和一个岗位，`dsh-scout` 不承诺“找到所有信息”，而承诺在证据边界内回答：

> 这个机会是否值得进入下一轮？如果值得，面试中必须验证什么？

所有重要结论必须绑定来源、证据等级和下一步动作；无法验证的内容必须保留为 `unknown` 或 `needs_verification`，不能被润色成事实。

## 2. 首个用户流程

输入：

- 公司名称或官网
- 岗位名称或岗位链接
- 用户目标（默认：是否值得进入下一轮）

流程：

1. 确认公司主体：名称、注册主体、品牌名和地域；存在歧义时暂停。
2. 建立九段式调查卡：公司与创始人、产品与技术、市场与竞争、融资与商业化、组织与 HR、风险、岗位匹配、面试反问、待核验事项。
3. 采集并归档来源；保存抓取时间、来源类型和原始链接。
4. 将事实、推断、用户提供信息和未知项分开。
5. 生成三态判断：`PROCEED`、`VERIFY` 或 `STOP`。
6. 输出报告、证据清单、风险清单和面试问题。

## 3. 首版输出物

每个 case 生成一个可复制的目录：

```text
scout-cases/<case-id>/
  case.json
  sources.json
  claims.json
  events.jsonl
  report.md
```

首版不要求精确的总分。报告必须包含：

- 一句话判断和判断状态
- 3 个支持判断的关键证据
- 3 个阻断或待核验风险
- 岗位可能的真实任务与权限假设
- 5-10 个面试反问
- 下一步最小核验动作

## 4. 证据模型

证据等级是来源质量标签，不是事实真伪的自动证明：

| 等级 | 含义 |
| --- | --- |
| `E0` | 未找到证据或仅为模型猜测 |
| `E1` | 用户提供、招聘信息或公司自述 |
| `E2` | 独立媒体、公开数据库或多源交叉信息 |
| `E3` | 工商、监管、官方文件或可直接复核的一手资料 |

每条 claim 至少包含：`claim_id`、`text`、`status`、`evidence_level`、`source_ids`、`confidence_note` 和 `next_action`。

允许的 `status`：`verified`、`reported`、`inferred`、`contradicted`、`unknown`、`needs_verification`。

## 5. DSH 插件边界

首版作为外部 bundle，优先使用现有工具、子 Agent、任务和文件系统能力：

- 工具：启动 case、核验 claim、比较公司、生成面试问题、导出报告。
- 事件观察：记录工具结果和来源归档，不重写 Agent Loop。
- 配置：来源目录、报告目录、并发数、超时和输出语言必须是可配置字段。
- 生命周期：所有 watcher、后台任务、连接和临时文件都必须在卸载时清理。

首版不新增模型可见的持久化事件；如果未来需要让 case 状态进入模型上下文，必须为其设计可回放的 session event。

## 6. 明确非目标

- 不重做通用搜索、浏览器或 MCP provider。
- 不自动发送求职邮件、提交申请或联系第三方。
- 不把公司融资、估值、专利数量或招聘规模直接转化为成功判断。
- 不把个人简历、身份信息或求职意图默认发送给第三方服务。
- 不提供法律、投资或医疗结论。
- 不在首版实现完整 Web UI、实时数据库或公司评分排行榜。

## 7. 首个验收案例

使用 `docs/fixtures/dsh-scout/snapmaker-hr-head.json` 作为离线 fixture，验证：

1. 公司主体存在未确认时，case 不能直接进入 `PROCEED`。
2. 用户历史材料可以作为 `E1/reported`，不能冒充当前独立事实。
3. 至少一个 claim 能从 `needs_verification` 转为 `verified`，并保留来源变化。
4. 报告能生成面试问题，而不是只输出摘要。
5. 没有来源的高影响结论必须显示为未知或待核验。

## 8. 成功标准

首个 MVP 通过的条件：

- 一个真实 case 可以从输入运行到报告导出。
- 每个高影响结论都能追溯到 claim 和 source。
- 同一 fixture 在无网络模式下可重放并得到结构稳定的结果。
- 失败时输出缺失证据和下一步动作，而不是编造补全。
- 插件可以加载、卸载、重载，不遗留 watcher、任务或连接。