v0.20 alpha skill-driven python core

README.md

@@ -1,8 +1,8 @@
 # Deep Research 系统
 
-> 生物医药行业的 AI 驱动深度研究流水线。基于 OpenCode 多 agent 协作，以麦肯锡/德勤式方法论产出专业级研究报告（PDF + DOCX）。
+> 生物医药行业的 AI 驱动深度研究流水线。v0.20 起以项目自有 Python core + skills + model profiles 为核心，以麦肯锡/德勤式方法论产出专业级研究报告（PDF + DOCX）。
 
-**当前状态**：v0.13 迭代完成。新增 Quarto/xelatex PDF 引擎（`--engine quarto`），解决 ReportLab 超宽表格渲染 bug；ReportLab 引擎保留为默认后备。Quarto 依赖独立安装，不影响现有环境。
+**当前状态**：v0.20 重构启动。核心编排从平台 prompt 迁移到项目自有 Python runtime：模型选择、skills、任务卡并发、中文原生成稿都由 `scripts/dr.py` 与 `configs/models.yaml` 驱动；OpenCode/Codex/Claude Code/Antigravity/Gemini CLI 只作为表层入口。
 详见 `PLAN.md` 了解完整方案、版本记录与迭代路径。
 
 ---
@@ -95,17 +95,23 @@ uv run python scripts/build_report.py <slug> --engine quarto    # Quarto/xelatex
 
 ### 多平台兼容
 
-- OpenCode：主适配器，使用 `.opencode/agents` 与 `.opencode/commands`。
-- Codex：native adapter，使用 `.codex/config.toml`、`.codex/agents`、`.codex/commands`、`.agents/skills` 与 `scripts/dr.py` 独立运行；主入口是 `dr-run`，由 Codex 主线程承担 PM 调度并主动 spawn subagents，详见 `docs/codex-usage.md`。
-- Gemini CLI / Claude Code：暂不做强适配，后续以同一套脚本与配置为基础扩展。
+v0.20 后，所有平台都是 surface adapter，核心调度只在 Python core 中执行。详细调用方式见 `docs/platform-adapters.md`。
 
-安装 Codex adapter：
+- OpenCode：使用 `.opencode/commands/*.md` 薄封装 Python CLI。
+- Codex：使用 `AGENTS.md` + 部署到 `$CODEX_HOME` 的 adapter 文件，优先用 GPT 系列做代码/测试/审阅。
+- Claude Code：使用 `.claude/skills/*/SKILL.md`，优先用 Opus/Sonnet 做访谈、结构讨论和中文风格审阅。
+- Gemini CLI：使用 `GEMINI.md` 与 `.gemini/commands/dr/*.toml`，优先用 Gemini 做长上下文、多模态和替代框架审阅。
+- Antigravity：作为 Agent Manager 打开仓库，要求 agent 在终端运行 `uv run python scripts/dr.py ...`。
+
+部署 Codex adapter（不在仓库内创建 `.codex`）：
 
 ```bash
-uv run python scripts/install_codex_adapter.py --force
+uv run python scripts/deploy_adapters.py codex --force
 ```
 
-Codex adapter 默认面向自动化研究：workspace 可写、命令不逐次审批、实时 web search 与脚本网络访问开启；Tavily / Brave / Exa MCP 会默认启用但不设为必需服务。
+Codex adapter 会写到 `$CODEX_HOME` 或 `~/.codex`；已有文件会在 `--force` 覆盖前生成 `.bak` 备份。adapter 默认面向自动化研究：workspace 可写、命令不逐次审批、实时 web search 与脚本网络访问开启；Tavily / Brave / Exa MCP 会默认启用但不设为必需服务。
+
+安全默认：部署脚本不会复制 `config.toml`，避免覆盖用户级 Codex 配置。只有明确需要安装本项目 bundled profile 时，才使用 `--include-config`。
 
 部署到新环境后自检：
 
@@ -114,12 +120,23 @@ uv run python scripts/deploy_check.py
 uv run python scripts/deploy_check.py --repair --force
 ```
 
-运行 Codex 总调度：
+运行平台无关 Python core：
 
 ```bash
-codex exec "$(uv run python scripts/dr.py prompt dr-run <slug-or-topic>)"
+uv run python scripts/dr.py init "研究主题" --slug <slug> --method mckinsey_market
+uv run python scripts/dr.py frame <slug>
+uv run python scripts/dr.py run <slug-or-topic> --method gmp_gap_assessment
+uv run python scripts/dr.py research <slug> --workers 6
+uv run python scripts/dr.py research <slug> --workers 6 --execute-packets
+uv run python scripts/dr.py research <slug> --workers 6 --execute-packets --allow-search-fallback
+uv run python scripts/dr.py research <slug> --workers 6 --build-briefs
+uv run python scripts/dr.py research <slug> --workers 6 --assemble-chapters
+uv run python scripts/dr.py review <slug>
+uv run python scripts/dr.py finalize <slug>
 ```
 
+OpenCode/Codex/Claude Code/Antigravity/Gemini CLI adapter 只包装这些 CLI，不再承担核心调度或模型选择。
+
 模型与搜索 API 选择见：
 - `docs/model-playbook.md`
 - `docs/search-playbook.md`
@@ -127,7 +144,7 @@ codex exec "$(uv run python scripts/dr.py prompt dr-run <slug-or-topic>)"
 模型预设配置文件：
 - `configs/models.yaml`（统一预设，支持 `simple / medium / premium / cn_heavy / codex_native`）
 
-推荐时机：在 `/dr-init` 访谈阶段就确定 `model_profile`，并立即执行 `apply-models`，保证 plan→pm→analyst→verifier→editor→polisher 的全流程策略一致。
+推荐时机：在 `/dr-init` 访谈阶段就确定 `model_profile`。v0.20 后模型选择优先在 Python runtime 中解析，adapter agent 文件只是兼容层。
 
 命令行查看解析后的模型映射：
 
@@ -136,6 +153,10 @@ uv run python scripts/dr.py models
 uv run python scripts/dr.py models --list
 uv run python scripts/dr.py models --profile premium
 uv run python scripts/dr.py models --profile medium --model-override dr_verifier=zenmux/openai/gpt-5.4
+uv run python scripts/dr.py skills validate
+uv run python scripts/dr.py skills sync
+uv run python scripts/dr.py methods list
+uv run python scripts/dr.py methods show gmp_gap_assessment
 
 # apply profile to agent files
 uv run python scripts/dr.py apply-models --profile medium --target both --dry-run
@@ -201,15 +222,9 @@ deep_research/
 
 ## 关键设计要点
 
-### 1. 防止"多 agent 变单模型跑"
+### 1. Python core 防止上下文污染
 
-OpenCode 的常见陷阱：AI 在主会话里装样子地"委派"子 agent，实际还是主模型在跑。本项目通过 3 道保险避免：
-
-1. **命令 `subtask: true`** — 强制走 Task 工具起子会话
-2. **Agent 强绑 `model`** — 每个 subagent 锁死具体模型
-3. **`permission.task` 白名单** — 精确限定调用关系
-
-验证方法：TUI 里 `<Leader>+Right` 切入子会话，能看到真实在跑的模型名。
+OpenCode/Codex/Claude Code/Antigravity/Gemini CLI 的 subagent 或 agent thread 都可能把大上下文带入子会话。v0.20 起，默认并发由 Python runtime 的任务卡执行层控制：先生成 `phase2/task_cards.json`，再按任务卡产出 `phase2/packets/*.json`，最后组装中文章节。平台 agent 只负责调用 CLI 和展示状态。
 
 ### 2. 信源分级（Tier 1-4 + 黑名单）
 
@@ -309,9 +324,9 @@ Opus 4.7 cache 读取价格 0.5 USD/M tokens（对比输入 25 USD/M，节省 98
 
 **验证 cache 是否生效**：
 1. 在 https://zenmux.ai/settings/logs 打开 API Call Logging
-2. 运行 `/dr-frame` 让 dr-plan 连续调用 2 次
+2. 运行一个真实 Claude/ZenMux 调用链路，例如 `uv run python scripts/dr.py research <slug> --execute-packets`
 3. 第 2 次的 `cache_read_input_tokens` 字段应 > 0
-4. 若始终为 0，检查 agent 的 `model:` 是否以 `zenmux-anthropic/` 开头（详见 `AGENTS.md` §6.5）
+4. 若始终为 0，检查 `configs/models.yaml` 中对应 role 是否走 `zenmux-anthropic/...`
 
 ---
 
@@ -324,11 +339,12 @@ Opus 4.7 cache 读取价格 0.5 USD/M tokens（对比输入 25 USD/M，节省 98
 4. [ ] 用一个小主题（如"5000 字 PD-1 综述"）跑通 MVP 流水线
 
 ### 系统侧（下一阶段）
-- [ ] dr-chief-editor / dr-searcher / dr-analyst / dr-verifier / dr-polisher / dr-reporter 6 个 subagent
-- [ ] `/dr-research` `/dr-review` `/dr-finalize` `/dr-status` 4 个命令
-- [ ] 生物医药专业信源 skill：PubMed / ClinicalTrials / openFDA / 专利 / 金融
-- [ ] citation-manager / evidence-table / mckinsey-method / docx-pandoc / report-template 5 个辅助 skill
-- [ ] Pandoc reference-doc 模板（中文 DOCX）
+- [x] Python core `init/frame/research/review/finalize/status` 骨架
+- [x] OpenCode/Codex/Claude Code/Gemini CLI wrapper
+- [ ] Antigravity 专用工作流模板（等待官方本地配置格式稳定）
+- [x] 用户资料导入基础能力：PDF 文本抽取 + FireRed OCR 扫描件识别 + phase0 落盘
+- [ ] 用户资料导入增强：DOCX / PPTX / 表格抽取 / 版面结构化
+- [ ] PDF reporting 包继续拆分：字体、宽表、引用、渲染验证
 
 ---
 
@@ -351,11 +367,15 @@ which npx
 npx -y tavily-mcp@latest
 ```
 
-### subagent 没被真正调度
-1. 检查 agent frontmatter 的 `mode` 字段是否为 `subagent`
-2. 检查命令 frontmatter 是否有 `subtask: true`
-3. 检查主 agent 的 `permission.task` 是否允许目标 subagent
-4. 在 TUI 用 `<Leader>+Right` 看是否有独立子会话
+### 平台 agent 看起来没有真正并发
+v0.20 不再用平台 subagent 作为默认并发机制。请检查 Python core 产物：
+
+```bash
+uv run python scripts/dr.py status <slug>
+ls projects/<slug>/phase2/task_cards.json
+ls projects/<slug>/phase2/packets
+ls projects/<slug>/phase2/chapter_briefs
+```
 
 ### ReportLab PDF 中文乱码
 ```bash
@@ -457,6 +477,7 @@ direnv allow
 
 - OpenCode 文档：https://opencode.ai/docs
 - Agent 配置：https://opencode.ai/docs/agents
+- 跨平台调用：`docs/platform-adapters.md`
 - Skill 配置：https://opencode.ai/docs/skills
 - MCP Servers：https://opencode.ai/docs/mcp-servers
 - ReportLab 文档：https://docs.reportlab.com
@@ -474,5 +495,6 @@ direnv allow
 - **v0.2** (2026-04-20) — 双 provider 架构（zenmux-anthropic + zenmux），解决 Claude prompt cache 生效问题
 - **v0.3** (2026-04-20) — 修正 v0.2 模型名（回到 Opus 4.7 / Sonnet 4.6 / Gemini 3.1 Pro / GPT-5.4 Pro 等真实 slug）；改 venv + requirements.txt 跨平台方案（macOS + Debian）；新增 `scripts/setup.sh`、`scripts/activate.sh`
 - **v0.13** (2026-05-02) — `build_report.py` 新增 `--engine quarto` 选项：Quarto 1.9 + xelatex 引擎，解决 ReportLab 超宽表格渲染 bug（`negative availWidth`/`NoneType` 问题）；`report-template.py` 同步修复（`render_table_blocks` 分块 + 等宽列强制分配）；README 补充双引擎安装指南与排错
+- **v0.20** (2026-05-05) — Skill-driven Python core 重构启动：新增 `scripts/runtime/*`、`scripts/dr.py init/frame/run/research/review/skills`、task-type 模型映射、中文原生 finalize 默认路径和 `scripts/reporting/*` 报告模块；OpenCode/Codex/Claude Code/Gemini CLI 命令降级为 Python CLI wrapper。
 
 见 `PLAN.md` §12 了解完整变更历史。