807 lines
56 KiB
Markdown
807 lines
56 KiB
Markdown
# Deep Research 系统方案（Python Core + 多平台 Adapter）
|
||
|
||
> 本文件是整套方案的**单一真实源**，中断后续接时从此文件恢复上下文。
|
||
> 最后更新：2026-05-07
|
||
> 实施阶段：v0.20 — Skill-driven Python core 重构
|
||
|
||
---
|
||
|
||
## 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 末强制确认 |
|
||
| 并发执行 | Python task-card worker pool（平台 subagent 仅作可选表层能力） |
|
||
| 中文字体 | **思源宋体 + 思源黑体 + 霞鹜文楷**，通过 `download-fonts.sh` 自动拉取 |
|
||
| Antigravity 适配 | 使用 `.agents/rules` + `.agents/skills` 指导 Antigravity 原生执行 Deep Research；Gemini Flash 管流程，Opus/Gemini Pro 分 phase 执行，Python core 退为辅助工具 |
|
||
|
||
---
|
||
|
||
## 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。
|
||
|
||
### 2.1 Antigravity 原生模型策略
|
||
|
||
Antigravity 当前可选 models 包括 Gemini 3.1 Pro (High/Low)、Gemini 3 Flash、Claude Sonnet 4.6 (Thinking)、Claude Opus 4.6 (Thinking) 与 GPT-OSS 120B。Codex 使用经验显示，若 Antigravity 仍默认调用 Python core model workers，研究主流程容易回到 ZenMux，并且 packet/chapter assembly 有碎片化风险。因此 Antigravity 采用 native 模式：用 skill 指导 Antigravity 自身模型按 phase 写产物，Python core 只负责脚手架、确定性校验、引用和出稿。
|
||
|
||
默认策略：
|
||
|
||
- Surface manager：Gemini 3 Flash，负责读 skill、维护 task list、推进 phase、跑轻量命令和收集 artifact。
|
||
- Phase 0-1：Claude Opus 4.6 (Thinking)，负责材料解读、研究方法选择、大胆假设、章节架构和成功标准。
|
||
- Phase 2：Gemini 3.1 Pro (Low)，负责证据包、反方证据、chapter brief、初稿，优先追求速度和可控成本。
|
||
- Phase 3：Gemini 3.1 Pro (High)，先做总编审校和证伪；若质量不足，再人工决定是否换模型复核。
|
||
- Phase 4：Claude Opus 4.6 (Thinking)，负责最终中文统稿、Executive Summary、表达质量和交付一致性。
|
||
- Python core 禁止默认接管 `run/research --execute-packets/assemble-chapters`；只有用户明确授权外部模型/API 消耗时才运行。
|
||
|
||
---
|
||
|
||
## 3. 完整架构
|
||
|
||
### 3.0 v0.20 Python Core 架构
|
||
|
||
v0.20 后，核心编排从平台 prompt 迁移到项目自有 Python runtime：
|
||
|
||
- `scripts/dr.py` 是稳定入口：`init`、`frame`、`run`、`research`、`review`、`finalize`、`skills`、`models`。
|
||
- `scripts/runtime/*` 负责 role/task 模型解析、skill registry、task cards、packet schema、manifest 更新。
|
||
- `.agents/skills` 是 canonical skill registry，也是 Antigravity 默认 workspace skill 目录；`.opencode/skills` 等 adapter 目录由 `dr.py skills sync` 生成。
|
||
- OpenCode/Codex/Claude Code 只作为 surface adapter，调用 Python CLI，不再承载默认并发调度。
|
||
- Phase 2 默认生成 `phase2/task_cards.json` 与 `phase2/packets/*.json`，减少长上下文传递。
|
||
- Phase 2 在正式写章前生成 `phase2/chapter_briefs/*.json`，先把并发证据收束为章节主线，降低碎片化。
|
||
- Phase 2 packet worker 对模型返回做一次 JSON 修复；仍失败的任务写入 `phase2/packet_errors/*.json`，不阻塞同批其他任务。
|
||
- Phase 2 chapter assembly 会校验正文 `[src_xxx]` 是否来自 chapter brief；失败章写入 `phase2/chapter_errors/*.json`，不阻塞同批其他章节。
|
||
- Phase 4 默认中文原生：`final_zh.md -> build_report`，legacy 英译中链路仅由 `--legacy-translate` 显式启用。
|
||
- Phase 1 必须选择 `research_method`，由 `configs/research_methods.yaml` 决定框架方法和 Phase 2 task axes；MECE 不再是唯一默认。
|
||
- 用户提供资料入口已支持 `input_materials` / `phase0/inputs` / `phase0/extracted`；PDF 文本抽取与 FireRed OCR 扫描件识别已先行落地，DOCX/PPTX/表格结构化继续放入 v0.21。
|
||
- Antigravity 入口已落地：`.agents/rules/deep-research-antigravity.md` 约束其优先使用 Antigravity 模型配额，`.agents/skills/antigravity-surface-adapter` 提供 native runbook、模型切换和搜索策略。
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 用户 (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 加强对公司名/机构名的搜索验证流程
|
||
|
||
- 2026-04-24 v0.9：**Phase 4 并发提速 + 模型/搜索攻略本 + Codex 兼容**
|
||
|
||
**目标**：在不破坏 OpenCode 主流程的前提下，把 v0.6 Python 化 Phase 4 进一步提速，并补齐跨平台使用说明。OpenCode 仍是主适配器；Codex 第一阶段只复用 `AGENTS.md` 与 Python 脚本，不复刻 OpenCode subagent。
|
||
|
||
**Phase 4 并发化**：
|
||
- `scripts/translate.py` 新增 `--workers`，默认 4；设为 1 时回退串行。
|
||
- 翻译阶段改为"稳定术语表快照 + 并发 chunk 翻译 + 事后统一合并 glossary patch"，避免多线程同时写 `glossary.json`。
|
||
- `scripts/polish.py` 新增 `--workers`，默认 4；润色块彼此独立，按完成顺序写 chunk，最终按原始 order 合并。
|
||
- `scripts/lib/zenmux_client.py` 增加日志与 usage 聚合锁，避免并发 JSONL 日志交错或 token 统计竞争。
|
||
|
||
**流程修正**：
|
||
- 修正 `apply_glossary.py` 默认输入，从 `phase4/final_zh_polished.md` 改为 `phase4/final_zh.md`。
|
||
- `/dr-finalize` 明确默认顺序：`translate.py → build_glossary.py → apply_glossary.py --input phase4/final_zh.md → polish.py → build_report.py`。
|
||
- 保留二次修正选项：润色后可手动对 `final_zh_polished.md` 再跑一次 `apply_glossary.py --input phase4/final_zh_polished.md --dry-run`。
|
||
|
||
**模型与搜索攻略本**：
|
||
- 新增 `docs/model-playbook.md`：定义 premium / balanced / budget / cn-heavy / verifier 五套模型策略。
|
||
- 新增 `docs/search-playbook.md`：说明 Tavily / Exa / Brave / Serper / PubMed / ClinicalTrials / FDA/EMA/NMPA / Patents 的使用边界。
|
||
- 新增 `configs/model_profiles.yaml` 与 `configs/search_profiles.yaml`，作为跨平台、人类和 agent 共用的策略配置参考；当前不强制重构 `.opencode/agents` 自动读取。
|
||
|
||
**Codex 兼容**：
|
||
- 新增 `docs/codex-usage.md`，说明 Codex 下如何遵循 `AGENTS.md`、运行 Phase 4 Python 流水线、检查 git staging，避免误提交 `projects/**` 研究产物。
|
||
- Codex v1 定位为"审阅/规划/修补/执行脚本"；确定性编排继续放在 Python 脚本，OpenCode subagent 调度暂不移植。
|
||
|
||
**Git 管理要求**：
|
||
- 本轮迭代应在独立分支推送到 Gitea。
|
||
- 提交范围仅限系统文件和文档：`README.md`、`PLAN.md`、`scripts/**`、`docs/**`、`configs/**`、必要的 `.opencode/commands/**`。
|
||
- 不提交 `projects/**`、生成的 PDF/DOCX/TXT、一次性研究产物或本地临时脚本。
|
||
|
||
- 2026-04-24 v0.10：**Codex native adapter（独立复刻版）**
|
||
|
||
**目标**：把 Codex 从"辅助 OpenCode 跑脚本"升级为并列 adapter。OpenCode 继续使用 `.opencode/**`；Codex 使用 `.codex/config.toml`、`.codex/agents/*.toml`、`.codex/commands/*.md`、`.agents/skills/**` 和共享 `scripts/**`。
|
||
|
||
**已落地的共享层**：
|
||
- 新增 `scripts/dr.py` 平台无关 CLI：支持 `status`、`prompt`、`glossary`、`finalize`。
|
||
- 新增 `scripts/install_codex_adapter.py`：从 `codex_adapter_templates/codex/**` 安装 `.codex/**`，并把 `.opencode/skills/**` 复制到 `.agents/skills/**`。
|
||
- 新增 `scripts/deploy_check.py`：新环境部署自检；必要时用 `--repair --force` 从模板重建 `.codex/**` 并同步 `.agents/skills/**`。
|
||
- 新增 `codex_adapter_templates/codex/**`：包含 Codex 项目配置、8 个 custom agents 和命令模板；`dr-run` 是主入口，用 Codex 主线程承担 PM 调度，阶段命令只作为调试和人工接管入口。
|
||
- `configs/model_profiles.yaml` 新增 `codex_native` profile，使用 OpenAI 原生 `gpt-5.4` / `gpt-5.4-mini` 角色映射。
|
||
- `docs/codex-usage.md` 重写为 Codex native adapter 使用说明。
|
||
|
||
**设计约定**：
|
||
- Codex 默认走 OpenAI 原生模型，不依赖 ZenMux provider。
|
||
- Codex 不会因 custom agent 文件存在而自动启动 subagent；`dr-run` prompt 必须明确要求主线程 spawn / wait / consolidate。
|
||
- Phase 1-3 由 `dr-run` 主线程调度 Codex custom agents 执行；Phase 4 由 `scripts/dr.py finalize` 调确定性 Python 流水线。
|
||
- `.opencode/**` 不改不删，避免破坏 OpenCode 已可用流程。
|
||
- `.opencode/skills` 将复制到 `.agents/skills`，而非软链接，以保证 Git 与跨机器可移植。
|
||
|
||
**安装方式**：
|
||
- 在本机运行 `uv run python scripts/install_codex_adapter.py --force`。
|
||
- 安装后运行 `/debug-config` 确认 `.codex/config.toml` 被 Codex 加载。
|
||
- 自动化研究默认权限：`sandbox_mode = "workspace-write"`、`approval_policy = "never"`、`web_search = "live"`、`sandbox_workspace_write.network_access = true`。
|
||
- Tavily / Brave / Exa MCP server 在模板中默认 `enabled = true` 且 `required = false`；确认本机 key、npm 与网络可用可直接使用，某个服务异常时再单独关闭。
|
||
|
||
- 2026-04-24 v0.11：**项目内搜索网关与 search-strategy 强化**
|
||
|
||
**目标**：把搜索主路径从平台 MCP 收敛到项目内 Python CLI，避免 Codex/OpenCode/Gemini/Claude Code 各自配置差异导致策略漂移。
|
||
|
||
**变更**：
|
||
- 新增 `scripts/search.py`：统一搜索入口，支持 `--route scholar|patents|news|general` 与 `--profile biomed_literature|patent_heavy|china_market|investment`。
|
||
- `scripts/lib/search_client.py` 调整为 Serper / Exa / Tavily 路由：文献走 Serper Scholar，专利走 Serper + Google Patents，新闻走 Serper News，通用搜索走 Exa → Tavily。
|
||
- `search-strategy` 明确 MCP 只做 gap-fill；文献必须优先 `scripts/search.py --route scholar`，专利必须优先 `scripts/search.py --route patents`。
|
||
- OpenCode `dr-searcher` / `dr-analyst` / `dr-verifier` 增加搜索网关调用要求与必要 bash 权限。
|
||
- Codex adapter 模板同步要求 `dr-run`、`dr-searcher`、`dr-analyst`、`dr-verifier` 使用搜索网关。
|
||
|
||
- 2026-04-29 v0.12：**三轨并行改造（搜索稳定性 + 模型配置化 + Phase 4 替代式 pipeline）**
|
||
|
||
**目标**：并行解决三项瓶颈：
|
||
1) 搜索工具遵循不稳定；
|
||
2) 模型选择被硬编码锁定；
|
||
3) Phase 4 串行链路耗时过长。
|
||
|
||
**Track A — 搜索路径可控化（Sprint 1）**：
|
||
- 新增 `scripts/ground.py`，统一封装 ZenMux native grounding（`web_search_options`）并输出引用 URL。
|
||
- `scripts/lib/zenmux_client.py` 增加 `web_search` 参数透传与 `chat_complete_with_meta()`（返回 content/usage/citations/raw）。
|
||
- `scripts/lib/search_client.py` 对 `scholar/patents/news` 默认启用 strict 模式，Serper 异常时显式失败，禁止静默降级。
|
||
- `scripts/search.py` 增加 `--strict-specialized`、`--trace`、`china_market` 查询重写。
|
||
- `.opencode/opencode.json` 关闭 Tavily/Brave/Exa MCP 的默认启用，收敛到项目内搜索网关。
|
||
|
||
**Track B — 模型配置化（Sprint 2-3）**：
|
||
- 新增统一配置 `configs/models.yaml`（`simple/medium/premium/cn_heavy/codex_native`）。
|
||
- 新增 `scripts/lib/model_config.py`，支持 profile 解析、override（`ROLE=MODEL`）与 profile 列表。
|
||
- `scripts/dr.py` 新增 `models`、`apply-models`，并让 `finalize` 支持 `--model-profile` 与 `--model-override`。
|
||
- 新增 `scripts/apply_model_profile.py`，可将 profile 批量回填到 `.opencode/agents/*.md` 与 `codex_adapter_templates/codex/agents/*.toml`。
|
||
- 新增 OpenCode 命令：`/dr-models`、`/dr-apply-models`。
|
||
|
||
**Track C — Phase 4 替代式重构（Sprint 4）**：
|
||
- 新增 `scripts/phase4_pipeline.py` 作为统一编排入口：
|
||
`translate -> glossary(optional) -> apply_glossary -> polish -> build_report`。
|
||
- glossary 核查支持 `off/low-confidence/full`，默认 `low-confidence`；低置信度条目过多时自动回退 `full`，避免超长命令参数。
|
||
- translate/polish workers 支持自动估算（`0 => auto`），降低人工调参成本。
|
||
- `scripts/dr.py finalize` 与 `.opencode/commands/dr-finalize.md` 切换到新 pipeline。
|
||
|
||
**Sprint 5 回归验证**：
|
||
- 新增 `scripts/sprint5_regression.py`，覆盖模型预设解析、搜索网关 dry-run、Phase 4 finalize dry-run 三项关键回归检查。
|
||
- 文档同步：`README.md`、`docs/model-playbook.md`、`docs/search-playbook.md`、`docs/codex-usage.md`。
|
||
|
||
**Sprint 6 收尾验收**：
|
||
- AGENTS.md 的 Phase 4 描述更新为 v0.12 真实链路（`dr-editor-in-chief + scripts/phase4_pipeline.py`）。
|
||
- README 增补一键回归命令：`uv run python scripts/sprint5_regression.py <slug>`。
|
||
- 验收口径固定：
|
||
1) `dr.py models --list` 可列出预设；
|
||
2) `dr.py apply-models` 可 dry-run 与落盘；
|
||
3) `scripts/search.py` 专用路由默认 strict；
|
||
4) `dr.py finalize --model-profile <x>` 走统一 Phase 4 pipeline；
|
||
5) `scripts/sprint5_regression.py` 全部 PASS。
|
||
|
||
- 2026-05-05 v0.20：**Skill-driven Python core 重构启动**
|
||
|
||
**目标**：把 Deep Research 从 OpenCode/Codex/Claude Code prompt 驱动，迁移为项目自有 Python runtime + skills + model profiles 驱动。平台工具只作为表层入口。
|
||
|
||
**已落地**：
|
||
- 新增 `scripts/runtime/`：skills registry、role runtime、task cards、artifact helpers、orchestrator。
|
||
- 新增 `scripts/reporting/`：引用生成与 Quarto 字体解析先行拆分，`build_report.py` 保持兼容入口。
|
||
- 新增 `configs/research_methods.yaml` 与 `scripts/runtime/methods.py`：支持 `mckinsey_market`、`gmp_gap_assessment`、`cmc_process_risk`、`rd_go_no_go`、`management_consulting`。
|
||
- 新增 `scripts/runtime/assembly.py`：把 packets 聚合为 chapter briefs，并通过中文章节组装 worker 生成 `phase2/drafts/chXX.md`。
|
||
- 新增 `scripts/runtime/phase1.py` 与 `scripts/runtime/review.py`：Python core 可直接执行 init、frame、review，不再依赖 OpenCode prompt 完成 Phase 1/3 骨架。
|
||
- `configs/models.yaml` 新增 `defaults.task_types`，模型解析同时返回 roles 与 task_types。
|
||
- `scripts/dr.py` 新增 `init`、`frame`、`run`、`research`、`review`、`skills list|validate|sync`，`finalize` 默认走中文原生路径；legacy 翻译链路改为显式 `--legacy-translate`。
|
||
- OpenCode/Codex 命令模板瘦身为 Python CLI wrapper，不再要求平台自行 spawn subagents 或复刻 Phase 1/3 编排逻辑。
|
||
- 新增 `docs/platform-adapters.md`、`CLAUDE.md`、`GEMINI.md`、`.claude/skills/*`、`.gemini/commands/dr/*.toml`，明确 Codex/OpenCode/Claude Code/Antigravity/Gemini CLI 的调用方式与模型边界。
|
||
- 新增 `scripts/deploy_adapters.py`：Codex adapter 从 `codex_adapter_templates/codex/**` 部署到 `$CODEX_HOME` 或 `~/.codex`，不再要求仓库内维护 `.codex/**`；旧 `scripts/install_codex_adapter.py` 改为兼容 wrapper。
|
||
- 新增 `scripts/runtime/materials.py` 与 `skills/document-ingest/SKILL.md`：Phase 0 可复制用户 PDF、直接抽取文本；扫描型 PDF 自动调用 LAN FireRed OCR（默认 `http://192.168.50.100:8001`），结果写入 `phase0/extracted/*.md` 与 manifest。
|
||
- 新增测试：runtime、CLI、reporting；新增计划中的 `scripts/v020_regression.py` 回归入口。
|
||
|
||
**仍需后续增强**：
|
||
- task-card worker 已支持显式 `--execute-packets` 先检索候选 sources、再调用 ZenMux 并发生成证据包，并自动回填 `phase2/sources.jsonl`；`--build-briefs` 收束为章节 brief；`--assemble-chapters` 生成中文章节草稿。
|
||
- packet worker 已增加一次 JSON 修复调用与失败隔离；单个 packet 失败会落盘到 `phase2/packet_errors/*.json`，不会拖垮整批并发。
|
||
- chapter assembly 已增加引用白名单校验与失败隔离；章节正文不得新增 brief 外的 `[src_xxx]`，失败章落盘到 `phase2/chapter_errors/*.json`。
|
||
- Phase 1 init/frame 已有可执行 Python core 骨架；后续可继续增强为模型辅助访谈与初扫，而不是回到平台 prompt 编排。
|
||
- v0.21 需要继续实现用户资料导入 pipeline：DOCX/PPTX/图片批量 OCR、表格抽取、材料 source registry、问题清单结构化。
|
||
- PDF 模块已开始拆分，但 ReportLab/Quarto 渲染主体仍在 `build_report.py` 与 `.opencode/templates/report-template.py` 中。
|
||
|
||
- 2026-05-06 v0.20-alpha：**Skill-driven Python core Alpha 与白帆案例暴露问题**
|
||
|
||
**Alpha 目标**：先把 Python core、skill registry、Codex adapter 外部部署、Phase0 PDF/OCR、task-card 并发、packet/brief/draft 骨架跑成可执行版本；不声明报告质量达标。
|
||
|
||
**已验证能力**：
|
||
- Codex adapter 可部署到 `$CODEX_HOME`，默认不复制 `config.toml`，避免覆盖用户全局配置；`--include-config` 才安装 bundled profile。
|
||
- `skills/deep-research`、`skills/document-ingest`、`skills/search-gateway` 已纳入 registry 并可同步到 adapter。
|
||
- `scripts/lib/zenmux_client.py` 支持 adapter model id 规范化，并对 Opus 4.7 自动省略已废弃的 `temperature` 参数。
|
||
- Phase0 可导入 PDF；扫描/弱文本 PDF 可走 FireRed OCR；当前白帆案例已生成 `phase0/extracted`。
|
||
- Phase2 可生成 90 个 task cards / packets / chapter briefs；packet validation、source rebuild、stale error 识别均已可执行。
|
||
- Phase3 deterministic review 已能把 citation 通过但 evidence 落纸不足的 draft 标为 P1 回炉。
|
||
|
||
**白帆案例暴露的问题**：
|
||
- Phase0/1 原先没有先读材料形成访谈问题，就直接生成框架并推进 Phase2，用户体验和研究方向控制不足。
|
||
- subagent 在 Codex 中可能绕开项目 Python search gateway，触发 Tavily MCP 权限确认；应禁止平台 MCP 作为默认搜索路径。
|
||
- evidence packet 到 chapter draft 存在信息损耗：引用密度不低，但具体审计发现、法规条款、整改动作和待补证据没有充分落到纸面。
|
||
- 单纯 `validate_packet` / citation whitelist 不足以判断报告质量；需要 evidence utilization、groundedness、specificity、actionability 等更高层质量门槛。
|
||
|
||
- 2026-05-06 v0.21 规划：**Research Brief + Enrichment + Compression + Evaluation**
|
||
|
||
**设计来源**：借鉴 `langchain-ai/open_deep_research` 的 clarification gate、research brief、bounded supervisor/researcher 并发、compression step 和 evaluator rubrics，但保留本项目 file-backed Python core、法规证据矩阵、PDF/DOCX 输出和项目内 search gateway。
|
||
|
||
**Phase0/1 改造**：
|
||
- `init` 后必须生成 `phase1/material_brief.md`：材料清单、初步问题聚类、关键访谈问题、材料使用边界。
|
||
- 新增 `phase1/research_brief.md/json`：把用户访谈、材料简报、研究方法、报告用途、范围排除项、基调和成功标准固化为 Phase2 的唯一输入。
|
||
- `research` 默认要求 `phase1.approved=true`；用户确认后运行 `dr.py approve <slug>`，否则只能显式 `--force`。
|
||
- clarification 不只问范围，还要输出 task 切分原则：哪些问题适合并发，哪些必须串行，弱模型需要哪些 prompt/skill/context。
|
||
|
||
**Phase2 改造**：
|
||
- task card 从 `research_brief` 生成，而不是只从章节标题生成；每张卡必须包含：研究目标、调研方式、推荐 search route、必读 skills、可用材料、期望 evidence schema、停止条件。
|
||
- 新增 `phase2/enrichment_rounds/roundXX/coverage_gap.json`：每轮先评估覆盖缺口，再生成补充 task cards；避免一次性 packet 后直接写章。
|
||
- 新增 `phase2/compressed_findings/chXX.json`：对 packets 进行压缩，但要求保留全部关键事实、原始来源、反方证据、证据落点和待补证据。
|
||
- `search-gateway` 成为信息收集 subagent 必读 skill：默认调用 `scripts/search.py` / `SearchClient`，不得直接用 Tavily MCP、browser MCP 或平台 web search。
|
||
|
||
**Phase3/4 改造**：
|
||
- chapter draft 必须从 `compressed_findings` 写，而不是直接从 packet 拼接；每章必须包含“证据落点与待补证据”表。
|
||
- Phase3 增加 evaluator rubrics：groundedness、completeness、relevance、structure、source quality、evidence utilization、specificity、actionability、writing quality。
|
||
- 任一核心维度低于阈值时禁止 finalize，自动生成回炉建议和补充 task cards。
|
||
- Final assembly 只允许使用通过 Phase3 的章节和 sources，避免把 Alpha 草稿误渲染为正式 PDF/DOCX。
|
||
|
||
**测试计划**：
|
||
- fixture 项目必须覆盖：material brief -> research brief -> task cards -> enrichment round -> compressed findings -> chapter draft -> Phase3 score gate。
|
||
- 搜索测试必须验证 subagent prompt 中包含 `search-gateway`，且不会提及 Tavily MCP 作为默认路径。
|
||
- 质量测试必须能让“泛泛咨询腔但有引用”的章节失败，让“具体审计发现+法规条款+整改动作+待补证据”的章节通过。
|
||
|
||
- 2026-05-06 v0.21-alpha implementation：**Research Brief 与压缩发现先行落地**
|
||
|
||
**已落地**：
|
||
- `scripts/runtime/phase1.py` 新增 `phase1/research_brief.md` 与 `phase1/research_brief.json`，在 `frame` 阶段把材料简报、研究方法、工作语言、写作基调、成功标准、任务切分原则、每个任务轴的 prompt brief / search route / required skills / stop conditions 固化为文件。
|
||
- `scripts/runtime/orchestrator.py` 生成 Phase2 task cards 时优先读取 `research_brief.json`，不再只依赖章节标题和 method axes。
|
||
- `scripts/runtime/tasks.py` 扩展 `TaskCard` schema：`research_goal`、`research_method`、`prompt_brief`、`required_skills`、`allowed_materials`、`expected_evidence`、`stop_conditions`、`model_hint`；旧 task card 会自动补默认字段，保持 fixture 兼容。
|
||
- `scripts/runtime/assembly.py` 新增 `build_compressed_findings()` 与 `validate_compressed_finding()`，`--build-briefs` 会同步写入 `phase2/compressed_findings/chXX.json`。
|
||
- `--assemble-chapters` 改为从 `compressed_findings` 写中文章节，减少并发 packet 直接拼接造成的碎片化。
|
||
- `AGENTS.md` 已同步更新 Phase1/2 真实产物、search-gateway 默认路径、Python core 验证锚点。
|
||
|
||
**仍未完成**：
|
||
- `phase2/enrichment_rounds/roundXX/coverage_gap.json` 还未实现；下一步应先做 deterministic coverage evaluator，再让补充 task cards 从 gap 生成。
|
||
- Phase3 evaluator rubrics 仍是计划项；当前 deterministic review 已能抓部分 draft 质量问题，但还没有分维度评分与 finalize gate。
|
||
- DOCX/PPTX/图片批量 OCR、表格抽取、材料 source registry 仍放入后续资料导入增强。
|
||
|
||
- 2026-05-07 v0.20/v0.21-alpha search routing refinement：**Exa evidence discovery + Tavily Research 边界定锚**
|
||
|
||
**设计结论**：
|
||
- Exa 更适合作为 Phase2 的受控 evidence discovery：优先返回 highlights/text，便于进入 source-quality、evidence-table 和 packet schema。
|
||
- Tavily Research 更适合作为 Phase1 初扫、薄弱章节补证据、Phase3 回炉扫描；其综合报告不得直接替代 evidence packet 或章节正文。
|
||
- Serper 继续承担 Scholar、Google Patents、News 与 Google-specific `site:` 检索；Brave 用于交叉验证和混合语种 fallback。
|
||
|
||
**已落地**：
|
||
- `scripts/search.py` 新增 `--route evidence` 与 `--exa-category`，profile 路由加入 `evidence`。
|
||
- `scripts/lib/search_client.py` 新增 `SearchClient.evidence()`，优先调用 Exa highlights/text，失败后降级 Tavily/Brave。
|
||
- `scripts/runtime/tasks.py` 把 `evidence` 纳入合法 search route，并更新主要 task axes 的默认路由。
|
||
- `scripts/runtime/workers.py` 的 `ProjectSearchProvider` 支持 `evidence` route。
|
||
- `skills/search-gateway`、`skills/search-strategy`、`docs/search-playbook.md`、`README.md`、`AGENTS.md` 同步记录搜索分工，避免后续又回到 Tavily MCP 或中文长句搜索。
|
||
|
||
- 2026-05-07 v0.20.1 Antigravity native adapter：**用 Antigravity 模型配额执行研究**
|
||
|
||
**设计结论**：
|
||
- Antigravity 官方机制以 `.agents/skills`、`.agents/rules`、Rules/Workflows、Task Groups 和 browser subagent 为核心；本项目在 Antigravity 中采用 skill-driven native research，而不是默认调用 Python core model workers。
|
||
- `AGENTS.md` 继续作为跨平台总规则；Antigravity 专项约束放到 workspace rule 和 skill，避免引入非官方 SOUL.md 作为项目真源。
|
||
- Opus 额度有限但大局观强，优先用于 Phase 0-1 和 Phase 4；Gemini 3 Flash 做流程管理，Gemini 3.1 Pro Low/High 分别用于 Phase 2/3。
|
||
- `paperfoot/search-cli` 可作为 Antigravity 原生检索前台：多 provider、14 modes、JSON/exit code 友好；但不得替代本项目 source tier 与 source-quality 评分。
|
||
|
||
**已落地**：
|
||
- 新增 `.agents/skills/antigravity-surface-adapter/SKILL.md`，定义 Antigravity native runbook、pause points、artifact 汇报、模型切换表和 `search-cli` 使用建议。
|
||
- 新增 `.agents/rules/deep-research-antigravity.md`，要求 Antigravity 优先使用自身模型配额，Python core 只做脚手架、确定性校验、引用和出稿。
|
||
- 撤回 `configs/models.yaml` 中 Antigravity 专用 ZenMux profile，避免误导主流程继续走 Python/ZenMux。
|
||
- `docs/platform-adapters.md`、`README.md`、测试用例同步更新。
|
||
|
||
- 2026-05-07 v0.20.2 Antigravity/Gemini research integrity hardening：**反幻觉、反假搜索、workflow gates**
|
||
|
||
**设计结论**：
|
||
- Gemini/Gemini CLI/Antigravity 在 deep research 中必须默认视为高幻觉风险模型；项目规则要把"诚实暴露不确定性"写成硬门槛，而不是依赖模型自觉。
|
||
- `GEMINI.md` 适合放短而硬的项目级行为约束，并通过层级 context 与 imports 承接 `AGENTS.md`。
|
||
- Antigravity `rules` 适合放 Always-On 约束；`workflows` 适合固化 Phase 0-4 执行顺序、人工暂停点和质量 gates。
|
||
- Claude/Claude Code 最佳实践可借鉴：根指令要短、具体、可执行，长流程拆到 rules/skills/workflows，避免巨型上下文降低遵从性。
|
||
|
||
**已落地**：
|
||
- 初版曾在 `AGENTS.md` 中加入 Antigravity native 例外、检索回执、source_id、search_log、unsupported_claims 等反幻觉硬规则；v0.20.3/v0.20.4 已将这些内容迁入 `.agents/rules`、`.agents/skills` 与 `.agents/workflows`。
|
||
- `GEMINI.md` 重写为短约束：禁止假搜索、禁止无 source_id 事实、要求 search log，并区分 Gemini CLI 与 Antigravity native。
|
||
- `.agents/rules/deep-research-antigravity.md` 加入 Anti-Hallucination Contract。
|
||
- `.agents/skills/antigravity-surface-adapter/SKILL.md` 加入 phase artifacts、fact-audit、权限建议和检索日志要求。
|
||
- 新增 `.agents/workflows/deep-research-native.md`，把四阶段 native research 写成可执行 workflow，并在每阶段设 gate。
|
||
- `scripts/deploy_adapters.py antigravity` 同步部署 workflows；已有文件继续默认跳过，`--force` 才备份覆盖。
|
||
|
||
- 2026-05-07 v0.20.3 Antigravity rule/agent/skill separation：**按 Antigravity 最佳实践重新分层**
|
||
|
||
**设计结论**：
|
||
- `AGENTS.md` / `GEMINI.md` 是跨工具/Antigravity 项目规则，不应承担角色定义、技能手册和详细流程。
|
||
- `.agents/agents.md` 用于 Antigravity 角色团队定义；`.agents/rules` 放强约束；`.agents/skills` 放可复用技能；`.agents/workflows` 放 slash workflow 和阶段编排。
|
||
- 继续保留反幻觉约束，但从 `AGENTS.md` 的长段落中移出，由 Antigravity rule/skill/workflow 承载，避免根规则膨胀影响遵从性。
|
||
|
||
**已落地**：
|
||
- 新增 `.agents/agents.md`，定义 Research Manager、Phase 0-1 Strategist、Evidence Analyst、Chief Reviewer、Final Editor。
|
||
- 瘦身 `AGENTS.md`，只保留跨平台研究底线与分层指引。
|
||
- `antigravity-surface-adapter` skill 和 `deep-research-native` workflow 改为引用 `.agents/agents.md`。
|
||
- `scripts/deploy_adapters.py antigravity` 同步部署 `.agents/agents.md`，默认跳过已有文件，`--force` 才备份覆盖。
|
||
|
||
- 2026-05-07 v0.20.4 AGENTS/GEMINI slimdown + method selection：**根规则瘦身，研究方法按场景选择**
|
||
|
||
**设计结论**：
|
||
- 根 `AGENTS.md` 只保留跨工具底线、命令入口、安全边界和分层索引；Phase 0-4 工作流、Antigravity 角色、长规则和技能细则全部迁出。
|
||
- `GEMINI.md` 只做 Gemini/Antigravity 高优先级覆盖，强调上下文加载和反假搜索。
|
||
- 麦肯锡/MECE/SCQA 只是候选表达和咨询工具，不再作为默认研究方法；不同研究场景必须选择匹配的分析框架。
|
||
|
||
**已落地**：
|
||
- 重写 `AGENTS.md`，缩短为跨工具规则和索引。
|
||
- 重写 `GEMINI.md`，保留 Gemini 反幻觉、平台边界和 context 加载指引。
|
||
- 新增 `.agents/skills/method-selection/SKILL.md`，覆盖市场/投资、临床、CMC/GMP、R&D、管理、政策等方法路由。
|
||
- 参考 `199-biotechnologies/claude-deep-research-skill` 的证据持久化、claim-level verification、delta retrieve、continuation state 和 final assembly gate 设计，新增 `.agents/skills/research-quality-gates/SKILL.md`。
|
||
- 强化 `source-quality` 与 `evidence-table`：要求 search receipt、原文访问状态、独立性 cluster、`claims_ledger.jsonl`、`coverage_matrix.md` 和不可证实 claim 显式落盘。
|
||
- 重写 `.agents/agents.md`，只保留角色定义和 required skills。
|
||
- 重写 `.agents/workflows/deep-research-native.md`，把方法选择设为独立 gate，加入 claim ledger、delta retrieve、coverage audit 和 continuation state gate。
|
||
- 文档与测试同步更新。
|
||
|
||
- 2026-05-07 v0.20.5 Antigravity clean workspace：**修正 Antigravity 加载目录与上下文污染**
|
||
|
||
**问题复盘**：
|
||
- Antigravity 实测会被完整仓库里的 `.codex`、`.opencode`、`.claude`、`.gemini` 和旧 `.agents` 提示污染，进而引用过期的 dr-pm/英文 Phase 2/并行管线等约束。
|
||
- Antigravity 当前 workspace 规则/技能/工作流应使用 `.agent/` 单数目录；`.agents/` 复数目录不应作为 native 加载入口。
|
||
|
||
**已落地**：
|
||
- 新增 `.agent/agents.md`、`.agent/rules`、`.agent/skills`、`.agent/workflows` 作为 Antigravity 唯一 native 入口。
|
||
- `AGENTS.md`、`GEMINI.md`、Antigravity rule/skill/workflow 明确要求忽略 `.codex`、`.opencode`、`.claude`、`.gemini` 和 legacy `.agents`。
|
||
- `scripts/deploy_adapters.py antigravity` 改为部署到 `.agent/`。
|
||
- `scripts/runtime/skills.py` canonical skill registry 改为 `.agent/skills`，保留 legacy `.agents/skills` fallback。
|
||
- 新增 `docs/antigravity-clean-workspace.md` 和 `scripts/export_antigravity_workspace.py`，支持 sparse checkout 或从完整仓库导出 clean workspace。
|
||
- `.gitignore` 新增 legacy/generated platform adapter 目录，后续不再把这些目录作为 Antigravity workspace 内容。
|