# AI Use Case Daily Scout — Milestone 3 实录

> 完成日期：2026-02-28
> 状态：✅ Deep Dive 技能全栈落地，Claude Code 双 Skill 上线，系统级 CLI 注册完毕

---

## 一、Milestone 2 → 3 解决了什么

Milestone 2 完成时的状态：三数据源打通，每日产出 30-40 条结构化 AI 场景，但消费端仅有被动的 Obsidian 日报，无法对单篇文章进行深度研究。

Milestone 3 目标：**从"雷达扫描"升级为"主动研究"——对任意文章做多角度事实核查，并作为 Claude Code Skill 内联到对话工作流中**。

```
之前（M2）: 每日定时扫描 → 分类存档 → 被动阅读 Obsidian 日报
之后（M3）: 同上 + /deep-dive <URL> → 四步分析管道 → 可信度评分 + 中文报告 → Obsidian
```

---

## 二、Phase 3 新增功能全记录

### 2.1 Deep Dive 四步分析管道

新增 `src/ai_usecases_explorer/deep_dive/` 子包，对任意文章执行端到端深度研究：

```
输入（URL / 文本 / 本地文件）
  ↓ Step 1: StructuralAnalyzer（Claude）
    → 核心主张、子论点、论证方式、关键实体、可核实事实、检索词
  ↓ Step 2: WebResearcher（Exa.ai）
    → 支持性来源、反对性来源、权威观点、事实核查
  ↓ Step 3: MultiPerspectiveEvaluator（Claude）
    → 正方论点、反方论点、中性背景、偏见评估、可信度评分（0–1）、总体结论
  ↓ Step 4: DeepDiveReporter
    → Obsidian Markdown 报告（全中文）
```

**新增文件一览：**

| 文件 | 职责 |
|------|------|
| `deep_dive/models.py` | Pydantic 模型：ArticleContent、StructuralAnalysis、ResearchResults、MultiPerspectiveEvaluation、DeepDiveReport |
| `deep_dive/fetcher.py` | ContentFetcher：httpx 抓取 + Exa.ai 兜底（处理 Cloudflare 403） |
| `deep_dive/analyzer.py` | StructuralAnalyzer：Claude 提取论证结构（中文输出） |
| `deep_dive/researcher.py` | WebResearcher：Exa.ai 四类查询并行检索 + URL 去重 |
| `deep_dive/evaluator.py` | MultiPerspectiveEvaluator：Claude 综合评估 + 评分（中文输出） |
| `deep_dive/reporter.py` | DeepDiveReporter：Markdown 渲染 + 写入 Obsidian `deep-dive/` 子目录 |
| `deep_dive/cli.py` | DeepDiveOrchestrator 编排器 + argparse CLI 入口 |

---

### 2.2 ContentFetcher：双路内容获取

`fetcher.py` 实现了两条获取路径，自动降级：

```python
# 路径一：httpx 直接抓取（大多数网页）
response = httpx.get(url, follow_redirects=True, timeout=15)

# 路径二：Exa.ai get_contents() 兜底（Cloudflare 保护 / 4xx 错误）
if response.status_code in (403, 429, 503):
    exa_result = self._exa_client.get_contents([url], text=True)
    raw_text = exa_result.results[0].text
```

正文提取用 `html.parser` 剥离标签，截断至 **8000 字**（防止 LLM 上下文溢出）。

---

### 2.3 WebResearcher：四类 Exa 检索

`researcher.py` 对 `SearchQueries` 中的四类查询各自独立调用 Exa：

| 查询类型 | 对应字段 | 用途 |
|---------|---------|------|
| `supporting` | 支持性来源 | 印证文章核心论点 |
| `opposing` | 反对性来源 | 暴露反驳声音 |
| `expert` | 权威观点 | 学术/行业专家立场 |
| `fact_checks` | 事实核查 | 验证具体数字和事实 |

**踩坑：Exa `autoprompt` 参数不存在**

调用 `search_and_contents()` 时传入 `autoprompt=True` 会抛 `TypeError`，Exa Python SDK 不支持此参数。修复：直接删除该参数，不传即可。

**设计：Exa 错误不中断管道**

任何单次 Exa 调用失败（网络超时、API 错误）只记录日志，返回空列表，管道继续执行后续步骤。

---

### 2.4 两个 Claude Code Skill

在 `.claude/commands/` 下注册两个 slash 命令，可在 Claude Code 对话中内联调用：

**`/deep-dive`**

```
/deep-dive --url https://example.com/article
/deep-dive --text "粘贴文章内容..."
/deep-dive --file /path/to/article.txt
/deep-dive --url https://... --dry-run
```

执行逻辑（三步）：
1. 调用 `ai-deep-dive $ARGUMENTS`，等待 CLI 输出 `REPORT_PATH:<path>`
2. 用 Read 工具读取报告文件完整内容
3. 提取关键字段向用户展示：标题、核心主张、可信度评分、正/反论点、总体结论

**`/ai-scout`**

```
/ai-scout
/ai-scout --dry-run
/ai-scout --date 2026-02-28
```

执行逻辑：调用 `ai-scout $ARGUMENTS` → 从输出中解析报告路径 → 读取并展示扫描统计 + 新场景列表。

---

### 2.5 系统级 CLI 注册

两个命令注册为系统级可执行文件，**无需激活 venv**：

```bash
# /usr/local/bin/ai-scout    → 封装脚本
# /usr/local/bin/ai-deep-dive → 封装脚本
```

pyproject.toml 同步注册 entry_points：

```toml
[project.scripts]
ai-scout = "ai_usecases_explorer.main:main"
ai-deep-dive = "ai_usecases_explorer.deep_dive.cli:main"
```

---

### 2.6 SKILLS.md 使用文档

新增 `SKILLS.md`，提供双 Skill 的完整中文使用指南：

- `/deep-dive` 四步管道说明、参数表、输出格式、所需配置
- `/ai-scout` 流程图、参数表、场景分类、Cron 配置
- CLI 速查表
- 完整 `.env` 配置参考

---

### 2.7 Settings 扩展

`settings.py` 新增两个配置字段：

| 字段 | 环境变量 | 默认值 |
|------|---------|--------|
| `deep_dive_model` | `DEEP_DIVE_MODEL` | `claude-sonnet-4-6` |
| `deep_dive_report_dir` | `DEEP_DIVE_REPORT_DIR` | `/root/vault/obsidian_vault/obsidian/Documents/obsidian/auto_report/deep-dive/` |

> Deep Dive 默认使用 Sonnet（推理质量要求高），ai-scout 继续使用 Haiku（成本优先）。

---

## 三、架构演进对比

```
Milestone 2:
  HN + Reddit + GitHub ──► 轮询交替 ──► LLM 三步 ──► SQLite ──► Obsidian 日报

Milestone 3:
  同上（每日定时）
  +
  用户发起 /deep-dive --url <URL>
    ↓
  ContentFetcher（httpx + Exa 兜底）
    ↓
  StructuralAnalyzer（Claude Sonnet）
    ↓
  WebResearcher（Exa.ai 四类检索）
    ↓
  MultiPerspectiveEvaluator（Claude Sonnet）
    ↓
  DeepDiveReporter ──► Obsidian deep-dive/ 子目录
    ↓
  Claude Code 读取报告 ──► 在对话中展示结构化摘要
```

---

## 四、首次 Deep Dive 运行效果

对 HackerNews 968pt 文章 `How I use Claude Code: Separation of planning and execution` 运行深度分析：

```
✅ 报告已保存至 Obsidian：/root/vault/obsidian_vault/obsidian/Documents/obsidian/auto_report/deep-dive/2026-02-28-1402-how-i-use-claude-code.md
   可信度评分：0.78 / 1.0
   总体结论：实践性强的经验分享，论证结构清晰，来源为一手经验，整体可信
```

报告内容（全中文）：
- **核心主张**：分离规划与执行是 Claude Code 高效使用的关键工作流
- **正方论点**：降低 AI 幻觉风险、提高迭代效率、更易追踪变更
- **反方质疑**：缺少对照实验支撑、经验具有个人偏向性
- **事实核查**：Claude Code 2025 年发布 — 已验证

---

## 五、测试覆盖

```
139 passed in 5.21s
```

| 模块 | 测试数 | M2 → M3 |
|------|--------|---------|
| models（UseCase） | 18 | 不变 |
| storage | 15 | 不变 |
| collectors | 24 | 不变 |
| processors | 11 | 不变 |
| reporters（Obsidian） | 12 | 不变 |
| main | 6 | 不变 |
| **deep_dive（新增）** | **53** | **+53** |

Deep Dive 测试分布：

| 类 | 测试数 | 关键覆盖 |
|----|--------|---------|
| `TestArticleContent` | 4 | Pydantic 必填字段约束 |
| `TestSearchQueries` | 2 | 列表为空允许 |
| `TestStructuralAnalysis` | 2 | 全字段校验 |
| `TestWebSource` + `TestFactCheck` | 3 | 字段类型和空值 |
| `TestResearchResults` | 1 | 四类列表结构 |
| `TestMultiPerspectiveEvaluation` | 2 | credibility_score 类型 |
| `TestDeepDiveReport` | 2 | report_path 可选 |
| `TestContentFetcher` | 5 | httpx mock，8000 字截断，403 异常 |
| `TestStructuralAnalyzer` | 4 | mock `_call_llm`，解析 sub_claims / search_queries |
| `TestWebResearcher` | 6 | Exa mock，去重，错误容错，字段完整性 |
| `TestMultiPerspectiveEvaluator` | 5 | mock `_call_llm`，pro/con 解析，入参类型 |
| `TestDeepDiveReporter` | 10 | 文件创建、目录自动建立、Markdown 内容、UTF-8 编码 |
| `TestDeepDiveOrchestrator` | 5 | 管道顺序、dry-run、无输入抛异常 |

---

## 六、怎么使用

### 6.1 Deep Dive（Claude Code 中）

```
/deep-dive --url https://example.com/article
/deep-dive --text "粘贴文章内容..."
/deep-dive --url https://... --dry-run
```

### 6.2 Deep Dive（终端）

```bash
ai-deep-dive --url https://example.com/article
ai-deep-dive --file /path/to/article.txt
ai-deep-dive --url https://... --dry-run
```

### 6.3 AI Scout（Claude Code 中）

```
/ai-scout
/ai-scout --dry-run
```

### 6.4 可调参数（.env）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ANTHROPIC_API_KEY` | 必填 | Claude API Key |
| `EXA_API_KEY` | 必填 | Exa.ai Key（Scout + Deep Dive 均需要） |
| `DEEP_DIVE_MODEL` | `claude-sonnet-4-6` | Deep Dive 使用的模型（推荐 Sonnet） |
| `DEEP_DIVE_REPORT_DIR` | `/root/vault/obsidian_vault/obsidian/Documents/obsidian/auto_report/deep-dive/` | 深度报告输出目录 |
| `CLAUDE_MODEL` | `claude-haiku-4-5-20251001` | ai-scout 使用的模型 |
| `ANTHROPIC_BASE_URL` | （空） | 代理地址 |
| `GITHUB_TOKEN` | （空） | GitHub API 限额 60→5000/小时 |
| `MAX_ITEMS_PER_RUN` | `80` | Scout 单次最多处理条数 |

---

## 七、报告输出路径

| 工具 | 路径 |
|------|------|
| ai-scout 日报 | `/root/vault/obsidian_vault/obsidian/Documents/obsidian/auto_report/YYYY-MM-DD.md` |
| deep-dive 报告 | `/root/vault/obsidian_vault/obsidian/Documents/obsidian/auto_report/deep-dive/YYYY-MM-DD-HHMM-slug.md` |

---

## 八、当前已知限制与 Phase 4 候选

| 优先级 | 方向 | 说明 |
|--------|------|------|
| 高 | Deep Dive 批量模式 | 支持一次分析多个 URL（如读取日报中的链接列表） |
| 高 | Scout 与 Deep Dive 联动 | 在日报中对高价值条目一键触发深度分析 |
| 中 | 向量去重优化 | Deduplicator 目前依赖 LLM，可引入嵌入向量加速 |
| 中 | Reddit 内容量 | Exa 对小众子版块 24h 索引条数少，可延长至 48h |
| 低 | Twitter/X 采集 | API 方案待确定 |

---

## 九、技术栈（M3 新增）

| 层次 | M2 | M3 新增 |
|------|-----|---------|
| 深度分析 | 无 | **Deep Dive 四步管道**（StructuralAnalyzer + WebResearcher + MultiPerspectiveEvaluator） |
| 内容获取 | 无 | **ContentFetcher**（httpx + Exa.ai 兜底） |
| 研究检索 | Exa（Scout 用） | **Exa 四类查询**（支持/反对/专家/事实核查） |
| 报告输出 | Obsidian 日报 | + **Deep Dive 子目录报告**（全中文，含事实核查表） |
| Claude Code 集成 | 无 | **双 Skill**（/ai-scout + /deep-dive） |
| CLI | `python -m ...main` | + **系统级 `ai-scout`、`ai-deep-dive`**（/usr/local/bin） |
| 模型策略 | 单一 Haiku | **双模型**（Scout→Haiku，Deep Dive→Sonnet，可配置） |