证据尽调背调MaxHou-infinity/dsh-scout

dsh-scout · 司察（Scout）

ci
license MIT
node >=22.19
dsh-tools 0.1.2-rc.1
tests 34 passing
English README

司察（Scout） —— 面向 DeepSeek Harness 的证据驱动型公司与岗位尽调 / 背调插件。

一句话说清楚：它让 AI 帮你回答——"这家公司和这个岗位，值得进入下一轮吗？面试中还有哪些事项必须核验？" 并且，每一个结论都挂靠真实的来源，绝不把"公司自述"或"融资新闻"当成已经核实的事实。

为什么需要它？（它解决什么痛点）

假设你收到一个面试邀约或 Offer：

- 招聘 JD 说公司"全球第一、估值百亿"——这是公司的宣传口径，不是事实；
- 媒体报道说"融资 20 亿美元"——可能只是媒体转述，甚至已被公司否认；
- 你需要在面试前判断：公司主体真实吗？岗位的汇报线、授权、薪资靠谱吗？该问哪些问题？

司察（dsh-scout）把这件事做成一条可复现的工作流：收集来源 → 登记证据 → 添加结论 → 核验主体 → 生成带证据边界的尽调报告。报告明确区分「已核验」「待核验」「未知」，并直接给出面试行动清单。

它的心智模型：证据等级（核心概念）

所有结论（claim）都受证据等级约束，等级上限由它所引用的来源决定：

| 等级 | 含义 | 例子 |
|---|---|---|
| E0 | 无来源 / 模型推断 | 没有来源支撑的猜测，只能标 unknown 或 needs_verification |
| E1 | 用户提供 | 你自己从内部渠道拿到的信息 |
| E2 | 权威第三方 | 独立媒体、招聘平台（BOSS/猎聘）、工商聚合库（天眼查/爱企查）、维基百科 |
| E3 | 官方一手 | 国家企业信用信息公示系统（gsxt.gov.cn）、监管公告、官方备案 |

四条纪律（插件强制，不可绕过）：

1. 一条主张的 evidenceLevel 不能超过它引用的最强来源（E1 来源撑不起 E3 结论）；
2. 没有来源的高影响结论，只能标记为 unknown 或 needs_verification；
3. 主体核验（scout_verify_identity）必须挂接 E3 官方登记来源，否则拒绝执行；
4. 决策默认保守：只要主体未核验、或有阻断级结论未核实，就保持 VERIFY，不会假装"已通过"。

这保证了：证据不足时，报告会诚实地告诉你"还没核实"，而不是给你一个夸大的结论。

一个案例（case）的生命周期

scout_start          创建案例（默认决策 VERIFY）
│
scout_search         调用 Web Provider 搜索，结果自动登记为来源
│
scout_ingest         批量登记采集结果（可随来源自动登记主张）
│
scout_add_source     登记来源（sourceType + evidenceLevel）
│
scout_add_claim      添加结论（受证据边界约束）
│
scout_verify_identity 用 E3 官方源核验公司主体（可选但强烈建议）
│
scout_verify_claim   用更强证据把结论提升为 verified（保留历史）
│
scout_report / scout_questions  生成报告 / 派生面试问题
│
scout_compare        多个案例并排对比（决策/主体/风险/问题）
│
scout_export / scout_import  落盘持久化（五文件），换会话可恢复

快速上手（一段完整示例）

以"判断某公司 HR 岗位是否值得推进"为例，Agent 会这样工作：

① scout_start(caseId=acme-hr, companyName=某科技公司, roleTitle=HRBP, location=深圳)
② 搜索公司工商信息 → scout_add_source(sourceId=s1, sourceType=company_registry/…, evidenceLevel=E2)
③ 抓取官方招聘 JD → scout_add_source(sourceId=s2, sourceType=company_official, evidenceLevel=E2)
④ 提炼职责/资格/薪资 → scout_add_claim(claimId=c1, status=verified, evidenceLevel=E2, …)
没有来源支撑的高影响项（如"汇报线"）→ status=unknown / needs_verification
⑤ 尝试 gsxt 官方核验 → scout_verify_identity(…)
⑥ scout_report → 生成报告

生成的报告包含：

- 判断：PROCEED / VERIFY / STOP（附理由）
- Key supporting evidence：最有力的已核验结论
- Blocking or unresolved risks：阻断推进的风险与未知项
- Verification checklist：所有待核验的阻断/重要事项 + 各自的下一步动作（直接当面试行动清单用）
- Claim ledger：全部结论台账（状态/证据等级/影响/来源/置信说明）
- Sources：带 URL 的来源清单（可点击回溯）
- Interview questions：建议的面试反问

工具清单

| 工具 | 作用 |
|---|---|
| scout_start | 创建尽调案例 |
| scout_add_source | 登记信息来源（含证据等级） |
| scout_ingest | 批量登记采集结果（自动推断来源类型/证据等级，可随来源一键登记主张草稿） |
| scout_search | 调用 DSH Web Provider 搜索并自动登记结果来源（type/evidence 按 URL 推断） |
| scout_add_claim | 添加证据受限的主张 |
| scout_verify_identity | 用 E3 官方源核验法定主体 |
| scout_verify_claim | 用更强证据提升主张为 verified |
| scout_report | 渲染当前 Markdown 报告 |
| scout_questions | 从案例派生去重、按优先级排序的面试问题清单（上限 12 条） |
| scout_compare | 2–5 个案例的并排对比报告（决策/主体/关键结论/风险/面试问题） |
| scout_export | 持久化五文件导出（case/sources/claims/events/report） |
| scout_import | 从导出目录恢复案例并重算决策 |

安装到 DSH Profile

dsh plugin --profile scout-demo add github:MaxHou-infinity/dsh-scout#
dsh --profile scout-demo --dump-config   # 验证工具挂载

要求：Node ≥ 22.19；面向 DeepSeek Harness 0.1.2-rc.1、@deepseek-ai/dsh-tools 0.1.2-rc.1 与 @deepseek-ai/cordis 4.0.2+。Git 安装会运行 prepare，pnpm 可能需要为 dsh-scout 显式添加 allowBuilds（只放行你审查过的固定版本）。

配置（可选）

在 DSH profile 的 cordis.patch.yml 中为 dsh-scout 配置：

- id: dsh-scout
config:
scoutDir: /path/to/scout-cases   # 默认导出目录；case 落在 //
autoPersist: true                # 每次变更后自动写五文件（默认 false）

- scoutDir 未配置时，scout_export 省略 targetDir 会写到 ./dsh-scout//；
- autoPersist: true 时，每次 scout_start / scout_add_source / scout_ingest / scout_search / scout_add_claim / scout_verify_* 后自动落盘；写失败不影响主流程。

数据持久化（v0.2 / v0.3）

案例默认在内存中、按会话隔离；scout_export 把案例写为五个文件：

case.json      案例主体（含决策状态）
sources.json   来源清单
claims.json    结论台账
events.jsonl   可回放事件流（case_started / claim_added / …）
report.md      当前报告快照

scout_import 可从导出目录恢复案例并重新计算决策——换会话、换机器都能接着尽调。

何时不要用（设计边界）

- 它内置的 scout_search 仅做搜索到来源的登记；不替代专用浏览器或 MCP Provider 的深度抓取；
- 它不会替你把融资信息、公司自述或招聘启事当成已核实的事实；
- 它不构成法律、投资或医疗建议；
- 主体核验依赖 E3 官方源，若 gsxt 等无法访问，报告会如实标记"待核验"。

完整 MVP 边界与验收标准见产品契约；首个示例案例见 Snapmaker HR Head。

开发与测试

pnpm install
pnpm test        # 34 个测试：决策默认值/证据约束/主体核验/会话隔离/报告渲染/导出导入往返/自动持久化/面试问题/采集→主张流转
pnpm run check:release

路线图

- ✅ v0.1：证据纪律、三态决策、结构化报告、会话隔离
- ✅ v0.2：五文件持久化导出 + 事件流 + 导入恢复
- ✅ v0.3：可配置存储（scoutDir / autoPersist）+ 面试问题生成（scout_questions）
- ✅ v0.4：信息采集登记（scout_ingest：批量登记搜索结果/抓取页面，自动推断来源类型与证据等级）
- ✅ v0.5：公司/岗位对比（scout_compare：多案例并排对比报告，合并面试问题）
- ✅ v0.6：采集→主张流转（scout_ingest 支持 claim 草稿：登记来源的同时自动添加主张）
- ✅ v0.7：Provider 深度集成（scout_search：DSH Web Provider 搜索，结果自动登记为来源）

社区

面向 DeepSeek Harness 的独立社区插件（Topic：dsh-plugin、deepseek-harness、due-diligence、company-research、job-research、hr-tech、evidence-based）。欢迎 Issues / PR。