kai/deep_research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0644a68ecc135889cd9d404a937eeee7361f0245
deep_research/PLAN.md
T

46 KiB
Raw Blame History

Deep Research 系统方案（Python Core + 多平台 Adapter）

本文件是整套方案的单一真实源，中断后续接时从此文件恢复上下文。 最后更新：2026-05-05 实施阶段：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 自动拉取

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. 完整架构

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；.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。
┌─────────────────────────────────────────────────────────────────┐
│  用户 (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 全部完成）

基础设施

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

Agents（8 个）

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

Commands（6 个）

  • /dr-init
  • /dr-frame
  • /dr-research
  • /dr-review
  • /dr-finalize
  • /dr-status

Skills（7 个）

  • search-strategy
  • source-quality
  • length-budget
  • pdf-reportlab
  • evidence-table
  • citation-manager
  • mckinsey-method

报告模板

  • report-template.py（ReportLab PDF）
  • 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. 模型 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 scripts/setup.sh
    会自动：装 uv（如缺失）→ uv sync 建 .venv/ + 装依赖 → 检查系统二进制。
  4. 系统二进制（setup.sh 会检测但不自动装）：
    • pandoc（DOCX 出稿阶段必须）
    • opencode（TUI 主程序）
  5. 首次使用前： 
    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 仍放入后续资料导入增强。
Reference in New Issue View Git Blame Copy Permalink