argo-search 1.0.1 → 2.9.7

package/docs/ADDING_NEW_ENGINE.md

@@ -0,0 +1,184 @@
+# 接入新搜索引擎（标准化流程）
+
+目标：在现有 Argo 上**自由增减、组合**搜索 API，走统一配置与准入，而不是每次改一堆散落文件。
+
+## 引擎三档
+
+| 档 | 何时用 | 你要交付什么 | 改 Python？ |
+|----|--------|--------------|-------------|
+| **L1 声明式 HTTP** | 标准 REST JSON 搜索 | `engines/specs/<id>.yaml` + 环境变量 | 否 |
+| **L2 增强声明式** | 特殊 header/body/output_map | 同上，补全 `output_map` / `required_env` | 通常否 |
+| **CLI 桥接** | 本机已装 CLI 输出 YAML/JSON（结构化） | `engines/specs/<id>.yaml`，`type: cli` + `cmd`/`search_args`/`output_format`/`filter_args` | 否 |
+| **L3 插件** | 多端点、HTML、会话、非标协议 | `engines/plugins/<id>.py` + spec `type` | 是 |
+
+模板：
+
+- L1/L2：`engines/_template_http.yaml`
+- CLI 桥接：`engines/_template_cli.yaml`（参考实现 `engines/specs/realtime_index.yaml`）
+- L3：`engines/plugins/_template_plugin.py`
+
+CLI 桥接关键字段：
+
+- `cmd` / `search_args`：命令与参数模板，支持 `{query}` / `{n}` 占位符；裸命令（PATH 中）与绝对路径均可。
+- `output_format: yaml`：走通用 YAML 解析，支持 `results`/`items`/`data` 或顶层 list，字段别名 `title|name`、`url|link`、`snippet|description|content`，并保留 `published_at` 发布时间维度。
+- `filter_args`：条件参数表。查询带 `--since`/`--until`（如 `7d` / `2026-08-01`）时自动追加对应 CLI 参数；未携带则不追加。缓存按时间窗隔离，不会串结果。
+
+## 可选结果字段（图源 / 全文源必看）
+
+结果 dict 只要求 `title` / `url`，其余字段原样透传到融合、精排与 JSON 输出
+（无字段白名单，`rrf_merge` 与 `local_five_dim_rerank` 都不会裁字段）。三个
+**可选**字段有下游消费者，写对了才有价值：
+
+| 字段 | 语义 | 谁在用 |
+|------|------|--------|
+| `image_url` | 可直接打开的图片地址 | 结果展示；判断「这是图源」的唯一依据 |
+| `image_license` | 该图的授权/权利状态 | 合规展示（如 `CC0`、`公有领域（NASA）`） |
+| `full_text_url` | **可确定性取到正文**的端点 | `evidence_loop.gate_results` 的取数建议优先用它，见下 |
+
+> **字段落点**：这些字段进的是 `results`（以及归档用的 `candidates` 视图），
+> **不进** `sources`。`build_sources` 是「底部相关链接」形态的**稳定 5 字段投影**
+> （`ref/title/url/engine/score/snippet`），有意裁剪，别往里加字段。消费方要拿
+> 图片/正文端点请读 `results`。
+
+### `image_url` 的三条硬约束
+
+1. **不对就不写**：上游没给图（或 Met 这类对非公版件不给链接）时**不要**填空串或详情页 URL——宁缺勿假，下游据此判断「有无图」。
+2. **路径必须指向字符串**：声明式 `output_map` 里写 `item_image: links.0.href`。NASA 的 `links.0` 是 `{href, rel, render, …}`，写成 `links.0` 会被 `_coerce_field` 当 dict 丢成空串。
+3. **图床可能有额外要求**：AIC 的 IIIF 要求 `AIC-User-Agent` 头才放行（否则 403），复用该 URL 抓图时要带上。
+
+声明式源可在 spec 顶层写 `image_license: "…"` 作为常量（授权不随条目变化时用，
+如 NASA 公版）。
+
+### `full_text_url` 什么时候该写
+
+当**给人看的页面拿不到正文**、而该源另有确定性正文端点时写它。两个实测例子：
+
+- `gutenberg`：`/ebooks/{id}` 是下载门户页（去标签首段全是 noprint 脚本），gutendex 在 `formats` 里已给纯文本 URL；
+- `egov_law`：`/law/{id}` 是 JS 空壳页（去标签后只剩「e-Gov 法令検索」），`/api/1/lawdata/{id}` 才是官方全文 XML。
+
+写它的收益是让取数建议走直连，省掉「门户页找下载链」或浏览器渲染那几级；
+**如果人类页面本身就能取到正文，不要写**（那是无消费方的装饰字段）。
+
+回归门禁：`tests/test_image_sources.py`、`tests/test_full_text_sources.py`。
+
+## 环境变量规范
+
+```bash
+# 推荐（新）
+export ARGO_TAVILY_API_KEY=...
+export ARGO_EXA_API_KEY=...
+export ARGO_MYENGINE_API_KEY=...
+
+# 兼容（旧名仍可用）
+export TAVILY_API_KEY=...
+export EXA_API_KEY=...
+
+# 可选：白名单 / 黑名单（逗号分隔）
+export ARGO_ENABLE_ENGINES="hackernews,duckduckgo,eastmoney,tavily"
+export ARGO_DISABLE_ENGINES="brave,felo"
+```
+
+策略类配置（路由权重、TTL、RRF）仍在 `config.yaml`，与密钥分离。
+
+## 生命周期
+
+```
+注册声明 → 配置注入 → 标准化验证 → 生产准入
+   YAML        env         validate        admission
+```
+
+### 1. 注册声明（L1 示例）
+
+```bash
+cp engines/_template_http.yaml engines/specs/myengine.yaml
+# 编辑 engine_id / url / headers / body / output_map / required_env
+```
+
+启动时 `config.py` 自动 merge `engines/*.yaml` 与 `engines/specs/*.yaml`（`_` 前缀跳过）。
+
+也可继续写在主 `config.yaml` 的 `engines:` 段（存量方式）。
+
+### 2. 配置注入
+
+```bash
+export ARGO_MYENGINE_API_KEY="..."
+# 可选：仅启用子集做试验
+export ARGO_ENABLE_ENGINES="myengine,hackernews,duckduckgo"
+```
+
+缺 Key 的引擎：
+
+- **自动路由**：跳过
+- **强制** `--engine myengine`：仍可调用（通常返回 `[]`）
+
+### 3. 标准化验证
+
+```bash
+cd ~/.workbuddy/skills/argo   # 或你的安装路径
+
+# 连通性 + schema
+python3 scripts/engine_validate.py --engine myengine --stage health
+
+# 质量基准（固定 query 集）
+python3 scripts/engine_validate.py --engine myengine --stage quality
+
+# 全量 + 写入准入 + 生成文档
+python3 scripts/engine_validate.py --engine myengine --stage all --admit --write-doc
+
+# 批量：所有 free 且 env 就绪
+python3 scripts/engine_validate.py --all-free --stage health --admit
+```
+
+通过 health 且 `--admit` → `~/.cache/unified-search/admission/<id>.json` 中 `blocked: false`。
+
+### 4. 生产准入与观测
+
+```bash
+# 表格式状态
+python3 scripts/search.py --list-engines --detail
+
+# 仅可自动路由
+python3 scripts/search.py --list-engines --detail --routable-only
+
+# JSON
+python3 scripts/search.py --list-engines --detail --json
+
+# 单引擎状态
+python3 scripts/engine_status.py --engine myengine --json
+```
+
+手动熔断：
+
+```python
+from engine_admission import set_blocked
+set_blocked("myengine", True, reason="quota_exhausted")
+```
+
+## 组合与优化
+
+- **减少**：`enabled: false` 或 `ARGO_DISABLE_ENGINES`
+- **增加**：丢 YAML / 插件 → validate → admit
+- **组合**：改 `config.yaml` 的 `domains[].engines_combo`，或 TF-IDF `domain_profiles`
+- **预算**：`--mode fast|auto|deep|budget` 继续按 cost_tier 过滤
+
+## 目录真源
+
+| 路径 | 职责 |
+|------|------|
+| `config.yaml` | 主配置、域规则、cost_tiers、存量引擎 |
+| `engines/specs/*.yaml` | 外置引擎声明（推荐新引擎落点） |
+| `engines/plugins/*.py` | L3 自定义 builder |
+| `scripts/engine_env.py` | Key 别名与 ENABLE/DISABLE |
+| `scripts/engine_admission.py` | 准入状态 |
+| `scripts/engine_validate.py` | 验证 CLI |
+| `backends/engine_registry.yaml` | 元数据/观测目录（非运行时唯一真源） |
+
+运行时引擎列表以 **merge 后的 config engines** 为准。
+
+## 验收清单
+
+- [ ] `engine_validate --stage health` 为 `pass` 或合理 `skipped`（缺 Key）
+- [ ] `--list-engines --detail` 中 `routable=True`（需要进自动路由时）
+- [ ] `search.py "查询" --engine <id>` 有结构化结果
+- [ ] 无 Key 时自动路由不含该引擎
+- [ ] `blocked=true` 后自动路由剔除

package/docs/ARGO_INTRO.md

@@ -0,0 +1,124 @@
+# Argo 阿尔戈 — 统一搜索与证据核验
+
+> 一个开源的「搜索 + 证据核验」工具，给 AI Agent 和终端使用。把 218 个搜索源、多语言路由、深度研究与证据判定整合在一个命令行 / MCP 里，让「搜」和「核」变成一件事。
+
+---
+
+## 安装方式
+
+> **唯一真实源是 GitHub。** 请用下面任一方式，勿用 `npm install argo-search`（npm registry 上那份是**非官方陈旧版 v1.0.1**，不随本项目更新）。
+
+### 方式一：一键脚本（推荐本机长期用）
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh | bash
+```
+
+### 方式二：npx（不加装，即用即走）
+
+```bash
+npx -y github:taxueseek/argo
+```
+
+### 方式三：给 Agent 挂 MCP
+
+Claude / Codex / Kimi 等支持 MCP 的客户端，直接挂：
+
+```json
+{
+  "mcpServers": {
+    "argo": { "command": "npx", "args": ["-y", "github:taxueseek/argo"] }
+  }
+}
+```
+
+挂上后获得 19 个工具（与 CLI 能力面对齐）：`argo_search`、`argo_local_search`、`argo_local_read`、`argo_recompute`、`argo_research`、`argo_evidence`、`argo_clarify`、`argo_crawl`、`argo_fetch`、`argo_screenshot`、`argo_pdf`、`argo_social_search`、`argo_article`（公众号文章全文）、`argo_job`（招聘多平台聚合）、`argo_extract`（结构化提取）、`argo_preflight`（URL 批量预检）、`argo_answer`（直答）、`argo_watch`（网页变化监控）、`argo_cite`（DOI 引用条目）。
+
+### 依赖
+
+- **必需**：Python 3.9+、`pip install pyyaml`
+  - 下限由语法决定，与 `bin/argo` 的 `MIN_PYTHON` / `scripts/install.sh` 保持一致（改一处就要改另外两处）。唯一越界过的 `job.py` 用了 3.12+ 的 PEP 701 f-string 写法，已按 3.9 改写，此后由跨解释器解析检查兜住。
+- **可选**：`curl_cffi`（TLS 指纹，反爬站抓取更稳）、Chrome（截图）
+- 只有 npx 入口才需 Node.js 18+
+
+---
+
+## 使用示例
+
+### 1. 搜索
+
+```bash
+argo search "Rust async runtime tokio 性能"
+argo search "python asyncio error handling"  # 编程问答域 → StackOverflow 官方 API
+argo search "미국 연준 금리 인하 전망"      # 多语言，返回韩语结果
+```
+
+### 2. 证据核验（高后果问题）
+
+金融 / 医疗 / 法律 / 事实核查类查询，搜索结果自带证据门控：高后果问题标 `fetch_required`，每条结果标 `fetch_suggested`、`has_fetched_evidence`。
+
+```bash
+# 对 top-3 核验正文，回填「核实后证据分」
+argo search "某公司财报" --verify 3
+```
+
+### 3. 深度研究（多子查询取证）
+
+复杂问题用 `argo research`，产出 **dossier**（来源 / 覆盖 / 缺口 / 可判定检查），判断稿交给 Agent 写（事实 / 推断 / 建议 / 未知 分开）。
+
+```bash
+argo research "半导体行业 2026 供需格局"
+argo research "iPhone 16 用户口碑" --mode social-sentiment
+```
+
+### 4. 抓取与结构化
+
+```bash
+argo fetch "https://example.com" --focus "关键词"   # 自动降级抓取
+argo pdf "https://example.com/paper.pdf" --pages "1-5"
+```
+
+### 5. 单代理里直接用
+
+```python
+from scripts.search import search          # 或走 MCP 工具
+results = search("查一下")
+```
+
+---
+
+## 为什么是现在（2026 检索趋势）
+
+- **Agent 检索进入证据管线时代**：交付物从链接清单变成可排序、可复核、不撑爆上下文的结构化证据
+- **上下文经济**：token 是第一成本，Agent 档（约 3.7KB/次）与字节预算检查让检索不烧窗口
+- **AI 友好内容标准铺开**：llms.txt 与 `.md` 直出在头部文档站普及，为 Agent 备料的网站越来越多
+- **免费开放生态成熟**：政府/学术/标准/安全机构的开放 API + 免 key 引擎覆盖大多数领域
+- **质量可度量**：排序金标（MRR/nDCG）、融合增益消融、路由负向控制——检索质量有数字可查
+
+Argo v2.8.8 把这五条全部落在代码里：220 源 / 89 域 / 185 免配置。更详细的场景对照与重点源清单见 [为什么选择 Argo](为什么选择argo.md)。
+
+---
+
+## 能力边界（诚实说明）
+
+**能力强项**
+
+- **多语言**：中 / 英 / 日 / 韩 / 欧语（德法西意）/ 西里尔等路由，多数查询返回对应目标语言（ja/ko 已大幅修复）
+- **218 搜索源、89 业务域**（184 个免配置开箱）+ TF-IDF 语义路由 + RRF 融合（weighted，弱源自动降权）
+- **三条拿正文直出通道**：站点根 llms.txt 与页面 `.md` 探测（命中跳过反爬链）+ r.jina.ai 阅读器级保底
+- **垂直官方 API 新成员**：StackExchange（180+ 问答站）、DOI 元数据（CSL JSON）、endoflife、NVD、法律法规库
+- **垂直域**：金融行情、宏观数据、化学、学术、本地、社交、模态卡（火车票/油价/万年历等）
+- **证据完整链路**：`fetch_required` / `--verify` / 证据分回填，适合高后果问题
+- **兼容开源生态**：可直接挂 MCP / DSH 插件（`wide_research` 并行研究调度）
+
+**已知限制**
+
+- 部分高质量源（`exa`、`bocha` 等）需 API Key；无 Key 自动走免费引擎 + 本地引擎，质量略有折损
+- 日 / 韩等技术类专业查询的分源质量仍有提升空间（宏观/日常已明显改善，但非完美）
+- 网络不稳定时（SSL 波动）个别源会暂时失败，会熔断降级自动切备选（证据分能提示是否可下结论）
+- **安装请用 GitHub 来源**；npm registry 上的 `argo-search` 是陈旧的 v1.0.1，功能残缺
+- 判断稿、结论始终由 Agent 负责；`argo` 负责「取证 + 给可判定检查」，不替你下结论
+
+---
+
+**License**：MIT · 仓库：https://github.com/taxueseek/argo

package/docs/DATA_SOURCE_GAPS.md

@@ -0,0 +1,81 @@
+# 数据源缺口评估与归档（2026-08-02）
+
+本文件归档数据源缺口分析结论，供后续按投入产出比分批吸纳。已接入的源不重复列出，
+只记录「缺口 → 候选 → 结论」以及中文垂直源的特殊情况。
+
+## 一、缺口领域与候选数据源总表
+
+| 缺口领域 | 推荐数据源 | 接入成本 | 备注 |
+|---------|-----------|---------|------|
+| 化学/药学结构检索 | PubChem PUG REST、ChEMBL | 零 cost，JSON 原生 | 化学结构检索是通用搜索死角 |
+| 蛋白质/基因组 | UniProt、RCSB PDB | 零 cost | 23 万实验结构 + 100 万 AlphaFold 模型 |
+| 医学术语统一 | UMLS/UTS | 需账号 | 200+ 术语表统一到 CUI |
+| 法律判例 | CourtListener | 免费但 2026-05 后限额骤降 | 5 次/分、125 次/天；美国判例全文唯一免费路径 |
+| 欧盟法律 | EUR-Lex CELLAR | 零 cost | 270 万文档 RDF |
+| 专利全文/权利要求 | Espacenet OPS、Lens、USPTO PatentsView | OPS 需免费 key | Lens 1.4 亿专利 |
+| 经济时间序列 | FRED、World Bank | 已接入（fred/worldbank） | FRED 正吞并 Fed 官方 DDP，是美国数据唯一 API 出口 |
+| 地球科学/遥感 | NASA CMR、USGS、NOAA/NWS | 零 cost | 地震/水文/高程/天气 |
+| 社科微观数据 | ICPSR | 部分受限 | 25 万+ 文件、1.6 万研究 |
+| 政府开放数据 | data.gov、data.europa.eu | 零 cost | 37 万+/200 万+ 数据集 |
+| 公版书籍语料 | Project Gutenberg、Internet Archive Wayback CDX | 零 cost | 7.5 万+ 公版书；CDX 可检索已删除内容 |
+| 全网正文语料 | Common Crawl | 零 cost 但量大 | 单月 27 亿页/377 TiB |
+| 中文社科全文 | NSSD | 无正式公开 API | 2000+ 期刊、930 万+ 篇 |
+| 中文统计数据 | 国家统计局 data.stats.gov.cn | 无正式公开 API | easyquery POST 为社区方案，稳定性待验证 |
+| 地理实体解析 | GeoNames | 零 cost | 1100 万+ 地名 |
+| 音乐元数据 | MusicBrainz | 已在 Argo | 仅作搜索源，未做实体消歧层 |
+| 通用知识图谱 | Wikidata SPARQL | 已在 Argo | 未做图查询增强 |
+
+## 二、优先补齐 Top 5（按投入产出比）
+
+1. **PubChem PUG REST + ChEMBL** —— 零 cost、JSON 原生、化学结构检索是通用搜索死角，5 分钟可集成。
+2. **ClinicalTrials.gov v2** —— 已在引擎列表（clinicaltrials），未在 SKILL.md 垂直分类中显式标注为医疗入口，建议在路由规则中强化。
+3. **FRED + World Bank** —— 经济事实核查黄金组合，已接入；FRED 正在吞并 Fed 官方 DDP。
+4. **Common Crawl + Wayback CDX** —— 全网语料与已删除内容检索，回报率最高的「搜索增强」投资。
+5. **CourtListener** —— 注意 2026-05 限额骤降（5 次/分、125 次/天），仍是美国判例全文检索唯一免费路径。
+
+## 三、中文垂直源现实情况
+
+中文区没有「小而美、免费、有正式 API」的垂直源。两个最可行入口：
+
+- **NSSD**（社科全文）：无正式公开 API 文档，接入需逆向或爬取，风险与维护成本高。
+- **国家统计局 easyquery**（宏观数据）：社区广泛使用但未文档化的 POST 接口，稳定性需自行验证。
+
+结论：两源暂不接入，归档待定。优先把已有源的查询质量做扎实（如 worldbank 国家词分流），
+而非堆砌不稳定的中文源。
+
+## 四、已实施改动
+
+- **worldbank 国家词分流**（ddf60f1 后续提交）：`is_foreign_macro_query` 识别非美国国家词，
+  fred 引擎对「中国GDP」「日本通胀」类查询返回空，route 层将 worldbank 前置，
+  杜绝「搜中国给出来美国数据」的错误（此前 fred 按关键词匹配 series_id 直接返回美国序列，
+  且 fast 模式 early-stop 会短路 worldbank 出场机会）。
+- 修复文件：`scripts/engines_builders_data.py`、`scripts/route.py`。
+
+## 五、未接入源待办（按优先级）
+
+- [x] PubChem PUG REST（chem 域，30d21da 后接入）
+- [x] ChEMBL 活性数据（chem 域，并入 pubchem 引擎兜底）
+- [x] Eurostat SDMX（macro_data 域，EU 国家 GDP/人均GDP/失业率/人口）
+- [x] GBIF 物种检索（species 域，学名/英文俗名）
+- [x] RFC Editor / IETF Datatracker（rfc_search 域）
+- [ ] GDELT 2.0（news 域）—— 持续 429 限流（本机 IP 两次实测均被拒），暂缓
+- [ ] Common Crawl 索引 + Wayback CDX（通用增强）
+- [ ] CourtListener（legal 域，注意配额）
+- [ ] GeoNames 地理消歧（geo 层增强）
+- [ ] MusicBrainz 实体消歧层（music 域）
+- [ ] Wikidata SPARQL 图查询增强
+- [ ] ClinicalTrials.gov 路由强化（medical 域）
+
+## 六、新增引擎实测结论（2026-08-02）
+
+- **PubChem**：名称查询走 `compound/name/{q}/cids` + `property`（分子式/分子量/IUPAC/SMILES）；
+  `compound/formula` 端点是异步等待模式（返回 Waiting + ListKey），不做轮询，分子式查询由
+  ChEMBL 兜底（C9H8O4 → ASPIRIN/CAFFEIC ACID）。ChEMBL 需 `search.json` 后缀或
+  `Accept: application/json`，否则返回 XML。
+- **Eurostat**：SDMX 2.1 免认证；已验证维度 GDP(nama_10_gdp/B1GQ/CP_MEUR)、
+  人均GDP(nama_10_pc/CP_EUR_HAB)、失业率(une_rt_a/Y15-74/PC_ACT)、人口(demo_pjan/age=TOTAL)。
+  HICP 数据集（prc_hicp_manr）400 未用，通胀由 worldbank 覆盖。unit 维度 label 的 key 是编码非索引。
+- **GBIF**：`/v1/species/search?q=` 对拉丁学名准确，对中文俗名返回无关属种
+  （「大熊猫」→ 植物属 Panda 等），引擎加 ASCII 守卫：纯中文查询直接放弃，交给百科类引擎。
+- **RFC**：datatracker `name__icontains` 只匹配文档名（rfc9000 名里无 quic），
+  必须用 `title__icontains` + `type__slug=rfc`；`type=rfc` 直接过滤无效（type 是 URI）。

package/docs/DESIGN_LOCAL_DATA_FUSION.md

@@ -0,0 +1,90 @@
+# 设计：本地数据与网络数据的分层融合（深度研究 L1）
+
+> 状态：P0-1 已实施（2026-08-25）。决策点：常规层 `--include-local` 默认关闭；recompute 执行器用本机受限子进程 + 审批。
+> 目标：常规查询保持轻量双通道；深度研究才启用「本地数据入账 + 可复算 + 攻击验证 + 任务板」完整栈。
+
+## 1. 问题重定义
+
+上一轮审查发现 argo 深度研究只能吃 URL/文本，用户本地一手数据（CSV/XLSX/文献 PDF）无法入账，也无代码执行语义。经讨论确认：**这个缺口只属于深度研究层，常规层不需要**。
+
+- 常规查询验收标准：快 + 来源对得上。本地检索（local-seek）与联网检索（argo_search）独立并列即可，交叉验证成本只在结论承重时值得付。
+- 深度研究验收标准：结论可核查。本地一手数据与网络公开证据需要血缘合并、相互印证、数值重算。
+
+## 2. 分层架构
+
+| 层 | 通道 | 本地+网络关系 | 新增组件 |
+|---|---|---|---|
+| L0 常规 | argo_search + argo_local_search | 独立并列，Agent 自选；可选 `--include-local`（默认关） | `search.py` 一个参数 + seek 结果并尾 |
+| L1 深度 | argo_research / wide_research | 血缘合并 + 可复算 + 攻击验证 | 账本扩展 / recompute 执行器 / claim 验证 / 任务板 |
+
+分流规则（写进 SKILL.md）：
+- 单跳、来源明确 → 两个常规工具任选或都用
+- 多跳、结论承重、涉本地数据文件 → argo_research + 工作包（file_inputs / recompute）
+- 中间地带（如「我的笔记怎么说 + 网上怎么说」单跳对照）→ `--include-local`（默认关）
+
+## 3. P0-1 本地数据入账（file:// 通道）
+
+现状：来源账本只认 http(s) URL（wide_research 防本地注入）。
+
+- 账本条目：`{type: file, path, sha256, mtime, role}`；工作包增 `file_inputs: [{path, kind, role}]`（kind: csv|xlsx|pdf|json|md；role: 定义|基线|数据）
+- 白名单制：仅工作包显式声明的文件可入账（`--forensics-dir` 或 `file_inputs`），其余 fail-closed 拒绝
+- 隐私：内容不入账，只存哈希、摘要字段与引用行号；dossier 输出 `local_sources` 章节
+- 门禁挂钩：`no_primary_sources` 把本地一手文件计入一手命中（防「有原始数据却判 no sources」假阴性）
+
+## 4. P0-2 recompute 可复算契约
+
+工作包可选字段：
+
+```json
+{
+  "id": "wp-rev",
+  "question": "公司 2025 年度营收同比增速是多少",
+  "query": "公司名 2025 年报 营收 同比",
+  "file_inputs": [{"path": "~/data/company_2025.xlsx", "role": "原始年报数据"}],
+  "recompute": {
+    "script": "读取 xlsx 营收列，计算 (2025-2024)/2024",
+    "expect": "0.23 左右",
+    "budget": {"timeout_s": 30, "max_mem_mb": 512}
+  }
+}
+```
+
+执行器 `scripts/recompute.py`（新组件）：
+- 只读挂载 file_inputs → 本机受限子进程（决策确认：非 Docker）
+- Fail-closed：默认禁运行，需 `--allow-exec` 或 MCP 参数显式放行；输入只读、断网（网络命名空间/权限不可用则跳过联网工具）、超时硬杀、无写目录
+- 输出 `{exit_code, stdout, stderr, elapsed_ms}`；改产物进 dossier `recomputed_values`
+- 闭环：检索数字与重算结果对照——对齐标 `recomputed=true`；冲突命中 `fact_conflicts` 门禁（结论上限 medium）
+- 安全：审批制（变异操作须显式确认）；执行记录进 trace
+
+## 5. P0-3 claim 级攻击验证（非对称验证）
+
+- 从 dossier key_findings 提取 load-bearing claims（含数字/判断）
+- 每个 claim 生成攻击子任务：验证器只见「主张 + 证据 + 交付约束」，不见生成全轨迹（防同源锚定）；任务 = 独立源类三角 + 数字/日期/公式原子核验 + 反例搜索
+- 输出 `claim_audit: [{claim, verdict: confirmed|contested|rejected, basis, repair_hint}]`
+- contested/rejected → conclusion_cap 降级；repair_hint 直接生成下一轮工作包
+- 复用现有 verify/evidence 抓取能力，新增验证提示词模板 + 调度
+
+## 6. P2 任务板 + 介入（协调层）
+
+- wide_research 轨道状态机显式化：`board: [{id, objective, state: pending|active|completed|blocked|cancelled, depends_on, returned}]`，输出进 dossier
+- 失败只失效后代：轨道失败 → 依赖轨道 `blocked`，已完成的独立进展保留
+- 介入：研究会话执行中侧信道输入（MCP `intervene` / `--intervene-file` 指令文件，下一轮次边界注入）；支持暂停/取消单轨道、补充 file_inputs、改优先级
+- 预算可见：有界并发预算按轨道分配到板
+
+## 7. L0 常规层明确不做
+
+不融合重排、不加 checkpoint/resume/回放、不加 recompute、不加任务板。
+
+可选开关 `--include-local`（默认关）：`argo_search` 把 seek 结果并入输出尾部（source=local_files），不做交叉评分，零成本扩展口。
+
+## 8. 实施顺序与验收
+
+| 步 | 内容 | 验收 |
+|---|---|---|
+| 1 ✅ | P0-1 账本扩展 + work_packages schema | dossier 含 local_sources；白名单外文件拒绝；`no_primary_sources` 计入（已实施） |
+| 2 ✅ | P0-2 recompute 执行器 + 门禁闭环 | 只读/断网/超时/审批四组测试；recompute_skipped / recompute_conflict 门禁触发测试（已实施） |
+| 3 | P0-3 claim 验证模板 + 调度 | claim_audit 三态判定测试 |
+| 4 | P2 任务板 + intervene | 轨道状态机测试；失败仅后代 blocked |
+| 5 | --include-local（默认关） | 开关默认不改变现有输出 |
+
+与「深度研究不写判断稿」一致：recompute 只产数值事实，判断仍归 Agent。