v0.20 alpha skill-driven python core

PLAN.md

@@ -1,8 +1,8 @@
-# Deep Research 系统方案（OpenCode 实现）
+# Deep Research 系统方案（Python Core + 多平台 Adapter）
 
 > 本文件是整套方案的**单一真实源**，中断后续接时从此文件恢复上下文。
-> 最后更新：2026-04-24
-> 实施阶段：v0.10 — Codex native adapter（独立于 OpenCode）建设中
+> 最后更新：2026-05-05
+> 实施阶段：v0.20 — Skill-driven Python core 重构
 
 ---
 
@@ -33,7 +33,7 @@
 | DOCX 方案 | **Pandoc + reference-doc** |
 | 字数落实 | 框架阶段分配配额 + 终稿校验双保险 |
 | 交互节奏 | Phase 1 末、Phase 3 末强制确认 |
-| 并发 subagent | 3-4 个（稳，避免 API 限流） |
+| 并发执行 | Python task-card worker pool（平台 subagent 仅作可选表层能力） |
 | 中文字体 | **思源宋体 + 思源黑体 + 霞鹜文楷**，通过 `download-fonts.sh` 自动拉取 |
 
 ---
@@ -63,6 +63,22 @@
 
 ## 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 入口)                                                 │
@@ -599,3 +615,74 @@ OpenCode 的坑：如果只是在主会话里装样子地写"让 X agent 做"，
     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 作为默认路径。
+  - 质量测试必须能让“泛泛咨询腔但有引用”的章节失败，让“具体审计发现+法规条款+整改动作+待补证据”的章节通过。