deep_research/PLAN.md

# Deep Research 系统方案（OpenCode 实现）

> 本文件是整套方案的**单一真实源**，中断后续接时从此文件恢复上下文。
> 最后更新：2026-04-20
> 实施阶段：路径 2 — 最小可用先行（MVP）

---

## 0. 背景与目标

### 0.1 用户画像
- 主业：生物医药行业的研发、工艺、管理、投资研究（非 coding）
- 痛点：此前在 OpenClaw / Hermes 做 Deep Research 时 token 消耗大但效果差
- 预期：以麦肯锡、德勤等顶尖机构的方法论输出专业报告

### 0.2 质量标准（硬性）
- **字数**：综述类 ≥ 10,000 字；研究类 ≥ 30,000 字
- **证据**：每条结论至少 2 个独立 Tier 1-2 信源佐证，否则标注"观点待验证"
- **结构**：8-15 章，每章下分 section / sub-section；每个标题即一个观点
- **信源**：优先论文、专利、权威研究报告；排除劣质纯新闻、自媒体
- **交付**：PDF（ReportLab）+ DOCX（Pandoc），格式专业、中文排版规范

---

## 1. 关键决策（已与用户确认）

| 维度 | 决策 |
|---|---|
| LLM 接入 | **zenmux 中转**（多模型混合） |
| 项目位置 | **仅项目级** `.opencode/`，项目根目录为 `deep_research/` |
| 搜索 API | **Tavily / Brave / Exa 走 MCP Server**；生物医药专业信源走 skill+bash |
| PDF 方案 | **ReportLab**（中文字体一次注册，样式集中 StyleSheet） |
| DOCX 方案 | **Pandoc + reference-doc** |
| 字数落实 | 框架阶段分配配额 + 终稿校验双保险 |
| 交互节奏 | Phase 1 末、Phase 3 末强制确认 |
| 并发 subagent | 3-4 个（稳，避免 API 限流） |
| 中文字体 | **思源宋体 + 思源黑体 + 霞鹜文楷**，通过 `download-fonts.sh` 自动拉取 |

---

## 2. 模型分配（zenmux 双 provider 架构）

详细 slug、cache 机制、升级流程见 `AGENTS.md` §6。关键要点：

- **Claude 系列走 `zenmux-anthropic/...`（无 `anthropic/` 前缀的裸 slug）**，以便 prompt cache 原生生效
- 其他模型走 `zenmux/<vendor>/<slug>`，隐式缓存自动生效
- 真实可用模型清单通过 `curl zenmux /api/v1/models` 随时查询；不要依赖 zenmux 文档里的过期示例

| 角色 | 模型 | 完整 model 字段 | 上下文 | 温度 | top_p |
|---|---|---|---|---|---|
| dr-plan（框架规划） | Claude Opus 4.7 | `zenmux-anthropic/claude-opus-4.7` | 1M | **0.7** | **0.9** |
| dr-pm（项目经理/调度） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.2 | 默认 |
| dr-chief-editor（总编/终审） | Gemini 3.1 Pro Preview | `zenmux/google/gemini-3.1-pro-preview` | 1M | 0.3 | 默认 |
| dr-searcher（轻量检索） | Claude Haiku 4.5 | `zenmux-anthropic/claude-haiku-4.5` | 200K | 0.1 | 默认 |
| dr-analyst（章节深研） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.3 | 默认 |
| dr-verifier（反方验证） | GPT-5.4 Pro（首选）/ Qwen3.6-Plus / MiniMax M2.7 | `zenmux/openai/gpt-5.4-pro` 等 | 1.05M | 0.2 | 默认 |
| dr-polisher（去AI味+润色） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.4 | 默认 |
| dr-reporter（出稿） | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4.6` | 1M | 0.1 | 默认 |

**Cache 行为**：Claude 走 `@ai-sdk/anthropic` 会自动打 `cache_control` 断点，zenmux 的 Anthropic 端点完整支持 4 种 cache 模式。Opus 4.7 cache read 价格仅 0.5 USD/M tokens（对比输入价 25 USD/M，节省 98%）。验证方法见 `AGENTS.md` §6.5。

---

## 3. 完整架构

```
┌─────────────────────────────────────────────────────────────────┐
│  用户 (TUI 入口)                                                 │
└─────────────────────┬───────────────────────────────────────────┘
                      │ Tab 切换主 agent
          ┌───────────┼────────────┐
          ▼           ▼            ▼
      ┌───────┐  ┌───────┐   ┌──────────┐
      │ dr-   │  │ dr-   │   │ dr-chief │  (Primary)
      │ plan  │  │ pm    │   │ -editor  │
      │ (Opus)│  │(Sonnet)│  │ (Gemini) │
      └───┬───┘  └───┬────┘  └─────┬────┘
          │          │ Task 工具委派│
          │          ▼             │
          │    ┌─────────────┐    │
          │    │ Subagents   │    │ (并行 3-4 个)
          │    ├─────────────┤    │
          │    │ dr-searcher │    │ Haiku 轻检索
          │    │ dr-analyst  │    │ Sonnet 深研
          │    │ dr-verifier │    │ GPT-5/Qwen 交叉
          │    │ dr-polisher │    │ Sonnet 润色
          │    │ dr-reporter │    │ Sonnet 出稿
          │    └─────────────┘    │
          │                       │
    调用 Skills ───────────────────┘
    调用 MCP Servers
```

---

## 4. 目录结构

```
deep_research/
├── PLAN.md                           # 本文件 — 方案真实源
├── AGENTS.md                         # 研究方法论与规则（OpenCode 自动读）
├── README.md                         # 使用指南
├── .gitignore
├── secrets.env.example               # 密钥模板
├── secrets.env                       # 实际密钥（不入 git）
│
├── .opencode/
│   ├── opencode.json                 # MCP + 权限 + 默认模型
│   ├── agents/
│   │   ├── dr-plan.md                # [MVP] Primary：框架规划 Opus temp 0.7
│   │   ├── dr-pm.md                  # [MVP] Primary：PM/调度 Sonnet temp 0.2
│   │   ├── dr-chief-editor.md        # [待补] Primary：总编 Gemini
│   │   ├── dr-searcher.md            # [待补] Subagent：轻检索 Haiku
│   │   ├── dr-analyst.md             # [待补] Subagent：深研 Sonnet
│   │   ├── dr-verifier.md            # [待补] Subagent：交叉验证 GPT-5/Qwen
│   │   ├── dr-polisher.md            # [待补] Subagent：润色 Sonnet
│   │   └── dr-reporter.md            # [待补] Subagent：出稿 Sonnet
│   ├── skills/
│   │   ├── search-strategy/SKILL.md          # [MVP] 检索策略总纲
│   │   ├── source-quality/SKILL.md           # [MVP] 信源评级与黑名单
│   │   ├── length-budget/SKILL.md            # [MVP] 字数预算
│   │   ├── pdf-reportlab/SKILL.md            # [MVP] ReportLab 中文模板
│   │   ├── biomed-pubmed/SKILL.md            # [待补]
│   │   ├── biomed-clinicaltrials/SKILL.md    # [待补]
│   │   ├── biomed-openfda/SKILL.md           # [待补]
│   │   ├── biomed-patents/SKILL.md           # [待补]
│   │   ├── biomed-finance/SKILL.md           # [待补]
│   │   ├── docx-pandoc/SKILL.md              # [待补]
│   │   ├── citation-manager/SKILL.md         # [待补]
│   │   ├── evidence-table/SKILL.md           # [待补]
│   │   ├── mckinsey-method/SKILL.md          # [待补]
│   │   └── report-template/SKILL.md          # [待补]
│   ├── commands/
│   │   ├── dr-init.md                # [MVP] /dr-init <topic>
│   │   ├── dr-frame.md               # [MVP] /dr-frame
│   │   ├── dr-research.md            # [待补] /dr-research
│   │   ├── dr-review.md              # [待补] /dr-review
│   │   ├── dr-finalize.md            # [待补] /dr-finalize
│   │   └── dr-status.md              # [待补] /dr-status
│   └── templates/
│       ├── report-template.py        # [MVP] ReportLab PDF 模板
│       ├── report-template.docx      # [待补] Pandoc reference-doc
│       ├── report-template.md        # [待补] Markdown 骨架
│       └── fonts/
│           ├── download-fonts.sh     # [MVP] 字体自动下载
│           ├── README.md             # 字体来源说明
│           ├── SourceHanSerifSC-Regular.otf     (git 忽略)
│           ├── SourceHanSerifSC-Bold.otf        (git 忽略)
│           ├── SourceHanSansSC-Light.otf        (git 忽略)
│           ├── SourceHanSansSC-Medium.otf       (git 忽略)
│           ├── SourceHanSansSC-Bold.otf         (git 忽略)
│           ├── SourceHanSansSC-Heavy.otf        (git 忽略)
│           └── LXGWWenKai-Regular.ttf           (git 忽略)
│
├── projects/                          # 每个研究主题一个子目录
│   └── <topic-slug>/
│       ├── manifest.json              # 元信息
│       ├── phase1/
│       │   ├── initial-scan.md
│       │   ├── framework.md
│       │   └── interview.md
│       ├── phase2/
│       │   ├── evidence/
│       │   ├── sources.jsonl
│       │   └── drafts/
│       ├── phase3/
│       │   ├── critique.md
│       │   └── revisions/
│       └── phase4/
│           ├── final.md
│           ├── final.pdf
│           ├── final.docx
│           └── citations.bib
│
└── archive/                           # 历史研究归档
```

---

## 5. 字体方案（方案 A：思源 + 霞鹜文楷）

| 用途 | 字体 | 字号 | 行高 |
|---|---|---|---|
| 正文 | 思源宋体 Regular | 10.5pt | 16pt |
| 正文粗体/术语 | 思源宋体 Bold | 10.5pt | 16pt |
| 一级标题（章） | 思源黑体 Bold | 18pt | 28pt |
| 二级标题（section） | 思源黑体 Bold | 14pt | 22pt |
| 三级标题（subsection） | 思源黑体 Medium | 12pt | 18pt |
| 摘要/引文/批注 | 霞鹜文楷 Regular | 10.5pt | 16pt |
| 图表标题 | 思源黑体 Medium | 9pt | 13pt |
| 脚注/参考文献 | 思源宋体 Regular | 9pt | 13pt |
| 页眉页脚 | 思源黑体 Light | 8pt | 12pt |
| 封面主标题 | 思源黑体 Heavy | 32pt | 42pt |

所有字体均为 **SIL OFL** 许可，可自由商用、嵌入 PDF 分发。

**字体下载来源（download-fonts.sh）**：
- 思源宋体：`https://github.com/adobe-fonts/source-han-serif/releases`
- 思源黑体：`https://github.com/adobe-fonts/source-han-sans/releases`
- 霞鹜文楷：`https://github.com/lxgw/LxgwWenKai/releases`

---

## 6. 工作流（四阶段）

### Phase 1：框架规划（dr-plan 主导）
1. `/dr-init <topic>` 创建项目目录 + manifest.json，进行初轮对话访谈
2. `/dr-frame` 触发：
   - dr-plan 用 `skill:search-strategy` 指挥 3 个 dr-searcher 并行初扫
   - 生成 8-15 章大纲 + 每章研究思路 + 字数配额（依据 `skill:length-budget`）
   - **【停】等用户确认** — 可迭代

### Phase 2：深度研究（dr-pm 主导）
1. `/dr-research` 触发：
   - dr-pm 按章节分批并行调度 dr-analyst
   - 每章完成后自动调度 dr-verifier 做反方验证
   - 每条结论自动填入 `evidence/chXX-evidence.md` 的"观点-证据-来源-置信度"表
   - `skill:length-budget` 自检，不足则继续挖掘

### Phase 3：总编审校（dr-chief-editor 主导）
1. `/dr-review` 触发：
   - Gemini 3.1 Pro 通读全部 drafts
   - 产出 `critique.md`：逻辑漏洞、证据不足、观点雷同、金字塔违反
   - **【停】等用户决策**：
     - a) 直接修正 → 进入 finalize
     - b) 特定章节回炉 phase2
     - c) 整体重来 → 回 phase1

### Phase 4：成稿（dr-chief-editor 调度）
1. `/dr-finalize` 触发：
   - dr-polisher 去 AI 味、中文表达、术语统一
   - dr-reporter 执行：
     - `python .opencode/templates/report-template.py final.md → final.pdf`
     - `pandoc final.md --reference-doc=... → final.docx`

---

## 7. 如何避免"多 agent 实际是一个主模型跑到底"

OpenCode 的坑：如果只是在主会话里装样子地写"让 X agent 做"，实际还是主模型在跑，token 花了但没分工。

**三道保险**：
1. **命令级强制**：所有命令 frontmatter 设 `subtask: true`，强制走 Task 工具，真起子会话
2. **Agent 强绑模型**：每个 subagent 的 `model` 字段写死到具体模型，OpenCode 会真正起独立会话用那个模型
3. **任务权限白名单**：dr-pm 的 `permission.task` 精确限定只能调用 subagent，不能跨级调度
4. **可验证**：TUI 里 `<Leader>+Right` 切入子会话，能看到真实在跑的模型名

---

## 8. 完整实施清单（v0.4 全部完成）

### 基础设施
- [x] 目录结构
- [x] PLAN.md / AGENTS.md / README.md / .gitignore
- [x] .opencode/opencode.json（双 provider + MCP + 权限）
- [x] secrets.env.example
- [x] scripts/setup.sh / activate.sh / verify-zenmux.sh
- [x] requirements.txt / pyproject.toml（uv）

### Agents（8 个）
- [x] dr-plan（Opus 4-7，temp 0.7）
- [x] dr-pm（Sonnet 4-6，temp 0.2）
- [x] dr-searcher（Haiku 4-5，temp 0.1）
- [x] dr-analyst（Sonnet 4-6，temp 0.3）
- [x] dr-verifier（GPT-5.4-pro，temp 0.2）
- [x] dr-chief-editor（Gemini 3.1 Pro Preview，temp 0.3）
- [x] dr-polisher（Sonnet 4-6，temp 0.4）
- [x] dr-reporter（Sonnet 4-6，temp 0.1）

### Commands（6 个）
- [x] /dr-init
- [x] /dr-frame
- [x] /dr-research
- [x] /dr-review
- [x] /dr-finalize
- [x] /dr-status

### Skills（7 个）
- [x] search-strategy
- [x] source-quality
- [x] length-budget
- [x] pdf-reportlab
- [x] evidence-table
- [x] citation-manager
- [x] mckinsey-method

### 报告模板
- [x] report-template.py（ReportLab PDF）
- [x] fonts/download-fonts.sh

### 待补（后续优化）
- [ ] docx-pandoc skill（Pandoc reference-doc 模板）
- [ ] 生物医药专业信源 skill（PubMed / ClinicalTrials / openFDA / 专利 / 金融）
- [ ] dr-reporter 的 DOCX 样式优化

---

## 9. 后续路径

### 优化项（实施阶段 5）

### 优化项（实施阶段 4）
- 把稳定的 bash skill 封装成 MCP server
- 引入 Exa /neural search 提升专业文献召回
- 支持图表自动生成（matplotlib 模板库）

---

## 10. 用户待办

1. [x] ~~模型 slug 映射~~（v0.3 已完成，基于 zenmux `/api/v1/models` 实时数据）
2. [ ] 准备 API keys（`secrets.env` 填写）：
   - ZENMUX_API_KEY（必填，格式 `sk-ai-v1-xxx`）
   - TAVILY_API_KEY / EXA_API_KEY / BRAVE_API_KEY
   - NCBI_API_KEY（可选，高频查 PubMed 时需要）
3. [ ] 环境初始化（跨 macOS/Debian，用 uv）：
   ```bash
   bash scripts/setup.sh
   ```
   会自动：装 uv（如缺失）→ `uv sync` 建 `.venv/` + 装依赖 → 检查系统二进制。
4. [ ] 系统二进制（setup.sh 会检测但不自动装）：
   - `pandoc`（DOCX 出稿阶段必须）
   - `opencode`（TUI 主程序）
5. [ ] 首次使用前：
   ```bash
   source scripts/activate.sh                           # 激活 venv + 载入 secrets
   bash .opencode/templates/fonts/download-fonts.sh     # 下载字体
   bash scripts/verify-zenmux.sh                        # 验证端点与 cache
   ```
6. [ ] 用一个小主题跑通 MVP 流水线，验证：
   - subagent 是否真正被独立调度（TUI 可见子会话）
   - 字数配额是否正确落到 framework.md
   - 信源过滤是否生效（Tier 4 不会进 sources.jsonl）
   - zenmux 后台 Logs 能看到 `cache_read_input_tokens > 0`

---

## 11. 风险与缓解

| 风险 | 缓解 |
|---|---|
| zenmux 模型 slug 命名变动 | AGENTS.md §6 单点维护映射表，全部 agent 引用此表 |
| Claude prompt cache 未生效 → 成本暴涨 | Claude 系列强制走 `zenmux-anthropic`（`@ai-sdk/anthropic` 通道），zenmux 后台 Logs 验证 `cache_creation_input_tokens` 字段 |
| MCP server 首次启动慢 | 用 `opencode serve` 常驻；subagent 设合理 timeout |
| 搜索 API 限流 | search-strategy 里规定每批 ≤3 个 searcher；失败重试 3 次带退避 |
| Opus 成本高 | dr-plan 用 steps 限制迭代次数（见 length-budget） |
| ReportLab 中文渲染慢 | matplotlib 预渲染 PNG，StyleSheet 缓存 |
| 中断恢复 | 所有状态写 manifest.json + phase 文件，本 PLAN.md 是元控制文件 |

---

## 12. 变更记录

- 2026-04-20 v0.1：初版方案确定，MVP 路径 2 开始实施
- 2026-04-20 v0.2：**双 provider 架构**上线，解决 zenmux Claude prompt cache 问题
  - 新增 `zenmux-anthropic` 自定义 provider（`@ai-sdk/anthropic` + `https://zenmux.ai/api/anthropic`）
  - Claude 系列迁移到裸 slug
  - 非 Claude 系列保留 `zenmux/<vendor>/<slug>` 走 OpenAI 兼容端点
  - AGENTS.md §6 重写：cache 机制、验证锚点、最低 token、升级流程

- 2026-04-20 v0.3：**修正 v0.2 错误 + 切换到 uv**
  - **模型修正**：v0.2 用了 zenmux 文档里过期的模型列表（被用户指正），重新通过 `curl zenmux /api/v1/models` 拉真实清单
    - Claude 恢复实际最新版：Opus **4.7** / Sonnet **4.6** / Haiku 4.5（Opus/Sonnet 都是 1M 上下文）
    - dr-chief-editor 升级为 Gemini **3.1 Pro Preview**（1M）
    - dr-verifier 恢复 GPT-5.4 Pro（1.05M）/ Qwen 3.6 Plus / MiniMax M2.7 / Kimi K2.5
  - 新增 AGENTS.md §6.7 "模型升级流程"，**原则：模型 slug 以 zenmux `/api/v1/models` 实时返回为准**
  - **Python 环境切换到 uv**（v0.2 是 pip+venv，跨平台体验差）
    - 新增 `pyproject.toml` 作为依赖真源
    - `scripts/setup.sh` 改为调 `uv sync`（自动装 uv、装 Python、建 venv、装依赖）
    - `scripts/activate.sh` 激活时自动找 uv 路径
    - `requirements.txt` 降级为备用清单（无 uv 的沙盒环境兜底）

- 2026-04-20 v0.4：**全流程完成**
  - 修复 zenmux-anthropic baseURL 缺 `/v1` 导致返回 HTML 页面的问题
  - 修复 Anthropic 端点模型名用点号（`4.7`）应改为连字符（`4-7`）
  - 新增全部 subagent：dr-searcher / dr-analyst / dr-verifier / dr-chief-editor / dr-polisher / dr-reporter
  - 新增 Phase 2-4 命令：/dr-research / /dr-review / /dr-finalize / /dr-status
  - 新增 skills：evidence-table / citation-manager / mckinsey-method
  - Phase 1 已成功跑通（O-糖苷酶立项报告测试主题）

- 2026-04-21 v0.5：**深度质量改造**（P0+P1+P2 一次到位）

  **根因诊断**：v0.4 跑通后发现 6 类质量问题：
  1. 并行派发退化（Batch 3 后只派 1 个 subagent）
  2. 全文 AI 味重（humanizer 能识别的 28 种 AI 模式大量出现）
  3. Phase 2 草稿（Sonnet）与 Final.md（Gemini 重写）风格断裂
  4. 标题用了用户原始问题而非正式报告命名
  5. 每章首节都强制套 SCQA 显式标注（机械套路）
  6. 正文混入"章节定位/字数配额/研究员 dr-analyst/生成时间"等调度元数据
  7. PDF 分页散乱，标题孤行
  8. 参考文献只留占位符 `[由 dr-reporter 自动生成]`

  **工作流重构**：切换为"英文工作 + 最终翻译"：
  - Phase 1：中文访谈 + 双语 framework（中文大纲 + 英文研究思路）
  - Phase 2：dr-analyst/dr-verifier 全英文产出
  - Phase 3：dr-chief-editor（Gemini）英文只读审校
  - Phase 4：全新链路 dr-editor-in-chief → dr-translator → dr-polisher → dr-reporter

  **Agent 调整**：
  - dr-chief-editor（Gemini 3.1 Pro）：收窄为 Phase 3 只读审校，不参与 Phase 4 写作
  - **新增** dr-editor-in-chief（Opus 4-7）：Phase 4 主体，负责合并英文稿、写 Executive Summary / Abstract / Glossary
  - **新增** dr-translator（Sonnet 4-6）：英译中专家
  - dr-polisher（Sonnet 4-6）：强化加载 humanizer-cn + output-hygiene
  - dr-reporter（Sonnet 4-6）：强制回填 citations + 卫生检查
  - dr-analyst / dr-verifier / dr-pm：切换为英文工作语言
  - dr-pm：批次间 context 压缩（通过 manifest.batches_summary）

  **Skills 新增/升级**：
  - `mckinsey-method` 重写：SCQA 仅限 Executive Summary + 各章引入段，禁止显式标注 S/C/Q/A；金字塔原理优先
  - `length-budget` 升级：4 种字数模式（auto/concise/detailed/deep）+ 英中换算率 1:1.4
  - **新增** `humanizer-cn`：基于 blader/humanizer + 中文特化（CN-1 到 CN-10）
  - **新增** `output-hygiene`：禁止词黑名单（章节定位/P0/研究员/占位符/SCQA 标注等 50+ 项）
  - **新增** `en-zh-translation`：生物医药英译中规范
  - `pdf-reportlab` 升级：widows/orphans/keepWithNext/splitByRow 分页规则，3 级颜色层次，封面保密标识

  **Commands 升级**：
  - `/dr-init`：访谈增至 8 步，末尾由 dr-plan 提议 3 个报告标题让用户选
  - `/dr-frame`：生成双语 framework（章节标题中英对照，研究思路英文为主）
  - `/dr-finalize`：新链路 dr-editor-in-chief 入口，4 步串行调度

  **模板升级**：
  - `report-template.py` 重写：颜色层次（h1 深蓝 / h2 蓝 / h3 深灰）、封面保密标识红色、widows=2 orphans=2、表格 splitByRow、禁止孤行寡行

  **manifest.json 新字段**：
  - `report_title` / `report_subtitle`：与 `topic` 分离，由用户在 /dr-init 选定
  - `confidentiality`：封面保密标识
  - `word_budget_mode`：auto/concise/detailed/deep
  - `target_words_en` / `min_words_en`：英文词数目标
  - `work_language` / `output_language`：工作和输出语言
  - `phase2.batches_summary`：批次间 context 压缩的进度摘要

  **v0.4 的"/dr-status" 命令保持**（未改动）

  备份：v0.4 状态打 tag `v0.4-final`；v0.4 的 project 产物归档到 `archive/o-glycosidase-feasibility-2026-v0.4/`

- 2026-04-22 v0.6：**Phase 4 Python 化 + 术语事实核查**

  **根因**：v0.5.2 的 dr-translator 反复在 output token 超限处卡死。本质原因：单 agent 处理 19k+ 词整文超 Sonnet 4.6 的 ~32k output token 上限，任何 prompt 级的分块追加协议都依赖 LLM 遵从性，实测不稳。

  **决策**：把 Phase 4 的翻译/润色/出稿从 LLM agent 降级为 **Python 脚本 + LLM 调用**。Python 负责"做多少"（切块、循环、重试、断点），LLM 只负责"做什么"（翻译/润色这一小段）。

  **新增 Python 基础设施**（全部独立于 opencode）：

  - `scripts/lib/zenmux_client.py` — HTTP 客户端，指数退避重试、token 统计、JSONL 日志、secrets.env 自动加载
  - `scripts/lib/markdown_chunker.py` — 按 H1/H2 切块，稳定 anchor ID（order + title sha1），合并工具
  - `scripts/lib/search_client.py` — 通用搜索门面（Exa > Tavily），`trust_env=False` 关键修复系统 socks 代理 TLS EOF 问题
  - `scripts/prompts/{translate,polish,glossary}_system.txt` — 三个核心 prompt，用自定义 `<<<TAG>>>` 分隔符格式（规避 Markdown-in-JSON 的引号/换行转义问题）

  **新增 Python 脚本**：

  - `scripts/translate.py` — 章节级切块循环翻译 + 术语表累积
  - `scripts/polish.py` — 按 H2 section 循环润色，记模型自标异常到 polish_notes.jsonl
  - `scripts/build_glossary.py` — **术语表事实核查**：用 Haiku + Exa 并发验证每个术语的中文译名和英文拼写，发现拼写错误与误译
  - `scripts/apply_glossary.py` — 把 glossary 发现的明确错误直接字面替换进 final_zh.md；保守策略（只改公司/机构/产品类专有名词，不碰 PDE/ASGPR 等有歧义的缩写）
  - `scripts/build_report.py` — 统一出稿入口，按 manifest.report_title 命名 PDF/DOCX，自动发现 sources.jsonl

  **report-template.py 深度修复**：

  - 字体注册支持 `fonts/ttf/` 子目录（OTF 的 PostScript outlines 与 ReportLab 不兼容）
  - 删除 build_disclaimer 的 manifest 重复调用（免责声明从 Markdown 读，不再重复）
  - 自动跳过正文首个 H1 + 封面元信息段（与封面避免重复）
  - 识别"目录将在最终渲染时自动生成"占位符 → 自动生成 TOC
  - 识别"完整编号参考文献列表…"占位符 → 从 `phase2/sources.jsonl` 生成 GB/T 7714 格式引文
  - src 上标正则扩展：支持 src_A14 / src_B-18 等字母+数字组合（原只支持 src_\\d+）
  - Unicode 上/下标转 `<super>/<sub>` 标签（思源字体子集不含上标字形，否则渲染方框）
  - 中英/数字混排自动加半角空格（CJK ↔ ASCII 边界）
  - 表格样式重做：table-header 水平居中、短 cell 居中、长 cell 左对齐、所有 cell 垂直居中、长文字 CJK 自动换行
  - TOC 末尾 PageBreak（目录独占整页）

  **Agent 调整**：

  - dr-translator / dr-polisher 标记 `[DEPRECATED v0.6]`，权限全部 deny，保留文件仅供历史参考
  - dr-editor-in-chief 重构为"只做创作 + bash 调脚本"模式，新增 `uv run *` / `bash scripts/*` 权限
  - `/dr-finalize` command 重写为 9 步流程：合并英文 → translate.py → build_glossary → apply_glossary → polish → build_report

  **实测结果（dual-target-rnai-pipeline-2026 项目）**：
  - translate.py：63 块全成功，17 分钟，$1.70，33,441 中文字（膨胀 1.89×）
  - polish.py：60 块全成功，10.7 分钟，$1.20，字数 -0.2%
  - build_glossary：201/310 术语核查成功（失败 106 条是代理 TLS EOF，降并发后可补齐），发现关键事实错误：
    - Maywavee 实为 **Mabwell（迈威生物）** 的拼写错误
    - Beyotime 中文误译为 '碧云天'，实应为 '必贝特医药'
    - Aurigene 误译 '天津奥利法'，应为 '天津奥瑞芙生物医药'
  - apply_glossary：自动修正 3 处关键错误
  - build_report：生成《双靶点 RNAi 药物工艺图谱与上游供应链机会研究.pdf》55 页 + 同名 DOCX

  **已知限制**：
  - dr-analyst 在 Phase 2 可能编造信源 ID（本次正文 101 个 src_id vs sources.jsonl 只 44 条），build_references 会列出缺失项供人工核对
  - build_glossary 对"通用缩写"判定仍依赖 LLM，存在歧义风险（已加 _AMBIGUOUS_ABBREVS 黑名单防止误伤）
  - 反方证据段落格式不统一（小节标题/加粗段混用）仍未解决，需改 skill:evidence-table 或 mckinsey-method

  **尚未处理的用户反馈（留待 v0.6.1）**：
  - 反驳证据段标题规范化（建议从"反方证据/Counter-Evidence"改为观点化标题如"另一种声音"）
  - build_glossary 默认放到 Phase 2 阶段运行，在源头拦截错误
  - 提示 dr-analyst 加强对公司名/机构名的搜索验证流程