From db626f1d5892dcd3bf47a5fc35f74cc288890409 Mon Sep 17 00:00:00 2001 From: kai Date: Wed, 6 May 2026 16:26:41 +0800 Subject: [PATCH] v0.20 alpha skill-driven python core --- .claude/skills/dr-finalize/SKILL.md | 20 + .claude/skills/dr-frame/SKILL.md | 14 + .claude/skills/dr-init/SKILL.md | 14 + .claude/skills/dr-research/SKILL.md | 22 + .claude/skills/dr-review/SKILL.md | 14 + .claude/skills/dr-run/SKILL.md | 14 + .gemini/commands/dr/finalize.toml | 9 + .gemini/commands/dr/frame.toml | 9 + .gemini/commands/dr/init.toml | 9 + .gemini/commands/dr/research.toml | 9 + .gemini/commands/dr/review.toml | 9 + .gemini/commands/dr/run.toml | 9 + .gitignore | 6 + .opencode/agents/dr-analyst.md | 181 +------ .opencode/agents/dr-chief-editor.md | 191 +------ .opencode/agents/dr-editor-in-chief.md | 293 +--------- .opencode/agents/dr-plan.md | 135 +---- .opencode/agents/dr-pm.md | 244 +-------- .opencode/agents/dr-polisher.md | 248 +-------- .opencode/agents/dr-reporter.md | 232 +------- .opencode/agents/dr-translator.md | 236 +-------- .opencode/commands/dr-finalize.md | 114 +--- .opencode/commands/dr-frame.md | 213 +------- .opencode/commands/dr-init.md | 165 +----- .opencode/commands/dr-research.md | 121 +---- .opencode/commands/dr-review.md | 47 +- .opencode/commands/dr-run.md | 20 + .opencode/commands/dr-status.md | 45 +- AGENTS.md | 199 +++---- CLAUDE.md | 18 + GEMINI.md | 18 + PLAN.md | 95 +++- README.md | 84 +-- .../codex/agents/dr-analyst.toml | 26 +- .../codex/agents/dr-chief-editor.toml | 12 +- .../codex/agents/dr-editor-in-chief.toml | 14 +- .../codex/agents/dr-plan.toml | 19 +- .../codex/agents/dr-pm.toml | 20 +- .../codex/commands/dr-finalize.md | 18 +- .../codex/commands/dr-frame.md | 18 +- .../codex/commands/dr-init.md | 15 +- .../codex/commands/dr-research.md | 49 +- .../codex/commands/dr-review.md | 17 +- .../codex/commands/dr-run.md | 76 +-- configs/models.yaml | 9 + configs/research_methods.yaml | 135 +++++ docs/codex-usage.md | 86 +-- docs/platform-adapters.md | 170 ++++++ pyproject.toml | 5 +- scripts/build_report.py | 63 +-- scripts/deploy_adapters.py | 185 +++++++ scripts/deploy_check.py | 55 +- scripts/dr.py | 499 +++++++++++++++++- scripts/install_codex_adapter.py | 71 +-- scripts/lib/model_config.py | 7 +- scripts/lib/zenmux_client.py | 50 +- scripts/reporting/__init__.py | 2 + scripts/reporting/fonts.py | 32 ++ scripts/reporting/references.py | 61 +++ scripts/runtime/__init__.py | 6 + scripts/runtime/artifacts.py | 46 ++ scripts/runtime/assembly.py | 202 +++++++ scripts/runtime/materials.py | 229 ++++++++ scripts/runtime/methods.py | 60 +++ scripts/runtime/orchestrator.py | 79 +++ scripts/runtime/phase1.py | 341 ++++++++++++ scripts/runtime/review.py | 157 ++++++ scripts/runtime/roles.py | 111 ++++ scripts/runtime/skills.py | 107 ++++ scripts/runtime/sources.py | 65 +++ scripts/runtime/tasks.py | 229 ++++++++ scripts/runtime/workers.py | 261 +++++++++ scripts/v020_regression.py | 69 +++ skills/deep-research/SKILL.md | 58 ++ skills/document-ingest/SKILL.md | 34 ++ skills/search-gateway/SKILL.md | 53 ++ tests/test_adapter_deploy.py | 51 ++ tests/test_chapter_assembly.py | 225 ++++++++ tests/test_phase0_materials.py | 100 ++++ tests/test_reporting.py | 34 ++ tests/test_research_methods.py | 55 ++ tests/test_search_grounded_packets.py | 115 ++++ tests/test_v020_cli.py | 225 ++++++++ tests/test_v020_runtime.py | 142 +++++ tests/test_v020_workers.py | 165 ++++++ tests/test_zenmux_model_normalization.py | 68 +++ uv.lock | 20 +- 87 files changed, 5213 insertions(+), 2865 deletions(-) create mode 100644 .claude/skills/dr-finalize/SKILL.md create mode 100644 .claude/skills/dr-frame/SKILL.md create mode 100644 .claude/skills/dr-init/SKILL.md create mode 100644 .claude/skills/dr-research/SKILL.md create mode 100644 .claude/skills/dr-review/SKILL.md create mode 100644 .claude/skills/dr-run/SKILL.md create mode 100644 .gemini/commands/dr/finalize.toml create mode 100644 .gemini/commands/dr/frame.toml create mode 100644 .gemini/commands/dr/init.toml create mode 100644 .gemini/commands/dr/research.toml create mode 100644 .gemini/commands/dr/review.toml create mode 100644 .gemini/commands/dr/run.toml create mode 100644 .opencode/commands/dr-run.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md create mode 100644 configs/research_methods.yaml create mode 100644 docs/platform-adapters.md create mode 100644 scripts/deploy_adapters.py create mode 100644 scripts/reporting/__init__.py create mode 100644 scripts/reporting/fonts.py create mode 100644 scripts/reporting/references.py create mode 100644 scripts/runtime/__init__.py create mode 100644 scripts/runtime/artifacts.py create mode 100644 scripts/runtime/assembly.py create mode 100644 scripts/runtime/materials.py create mode 100644 scripts/runtime/methods.py create mode 100644 scripts/runtime/orchestrator.py create mode 100644 scripts/runtime/phase1.py create mode 100644 scripts/runtime/review.py create mode 100644 scripts/runtime/roles.py create mode 100644 scripts/runtime/skills.py create mode 100644 scripts/runtime/sources.py create mode 100644 scripts/runtime/tasks.py create mode 100644 scripts/runtime/workers.py create mode 100644 scripts/v020_regression.py create mode 100644 skills/deep-research/SKILL.md create mode 100644 skills/document-ingest/SKILL.md create mode 100644 skills/search-gateway/SKILL.md create mode 100644 tests/test_adapter_deploy.py create mode 100644 tests/test_chapter_assembly.py create mode 100644 tests/test_phase0_materials.py create mode 100644 tests/test_reporting.py create mode 100644 tests/test_research_methods.py create mode 100644 tests/test_search_grounded_packets.py create mode 100644 tests/test_v020_cli.py create mode 100644 tests/test_v020_runtime.py create mode 100644 tests/test_v020_workers.py create mode 100644 tests/test_zenmux_model_normalization.py diff --git a/.claude/skills/dr-finalize/SKILL.md b/.claude/skills/dr-finalize/SKILL.md new file mode 100644 index 0000000..f3b77ff --- /dev/null +++ b/.claude/skills/dr-finalize/SKILL.md @@ -0,0 +1,20 @@ +--- +name: dr-finalize +description: Surface adapter command for Chinese-native Phase 4 finalization. +--- + +Run the project-owned Python core finalization. Do not hand-translate the report in Claude Code. + +Command: + +```bash +uv run python scripts/dr.py finalize $ARGUMENTS +``` + +For old projects only, use: + +```bash +uv run python scripts/dr.py finalize --legacy-translate +``` + +Report PDF/DOCX paths and any citation/rendering warnings. diff --git a/.claude/skills/dr-frame/SKILL.md b/.claude/skills/dr-frame/SKILL.md new file mode 100644 index 0000000..7b76e2a --- /dev/null +++ b/.claude/skills/dr-frame/SKILL.md @@ -0,0 +1,14 @@ +--- +name: dr-frame +description: Surface adapter command for generating Phase 1 framework.md through the Python core. +--- + +Run the project-owned Python core framework generator. Do not perform Phase 1 orchestration in Claude Code. + +Command: + +```bash +uv run python scripts/dr.py frame $ARGUMENTS +``` + +Report the framework path and remind the user to approve it before Phase 2. diff --git a/.claude/skills/dr-init/SKILL.md b/.claude/skills/dr-init/SKILL.md new file mode 100644 index 0000000..9a5e9b0 --- /dev/null +++ b/.claude/skills/dr-init/SKILL.md @@ -0,0 +1,14 @@ +--- +name: dr-init +description: Surface adapter command for initializing a Deep Research v0.20 project. +--- + +Run the project-owned Python core initialization. Do not create manifest files manually. + +Command: + +```bash +uv run python scripts/dr.py init $ARGUMENTS +``` + +Report the project slug, manifest path, and next command. diff --git a/.claude/skills/dr-research/SKILL.md b/.claude/skills/dr-research/SKILL.md new file mode 100644 index 0000000..f51f694 --- /dev/null +++ b/.claude/skills/dr-research/SKILL.md @@ -0,0 +1,22 @@ +--- +name: dr-research +description: Surface adapter command for Deep Research v0.20 Phase 2 task-card research. +--- + +Run the project-owned Python core Phase 2 command. Do not spawn Claude Code subagents for chapter research. + +Command: + +```bash +uv run python scripts/dr.py research $ARGUMENTS +``` + +Useful follow-ups: + +```bash +uv run python scripts/dr.py research --workers 6 --execute-packets +uv run python scripts/dr.py research --workers 6 --build-briefs +uv run python scripts/dr.py research --workers 6 --assemble-chapters +``` + +Report packet/chapter error files if present. diff --git a/.claude/skills/dr-review/SKILL.md b/.claude/skills/dr-review/SKILL.md new file mode 100644 index 0000000..c7112ee --- /dev/null +++ b/.claude/skills/dr-review/SKILL.md @@ -0,0 +1,14 @@ +--- +name: dr-review +description: Surface adapter command for deterministic Phase 3 review. +--- + +Run the project-owned Python core review. Claude Code may explain the critique afterwards, but should not overwrite it unless asked. + +Command: + +```bash +uv run python scripts/dr.py review $ARGUMENTS +``` + +Report the critique path and pause for user decision. diff --git a/.claude/skills/dr-run/SKILL.md b/.claude/skills/dr-run/SKILL.md new file mode 100644 index 0000000..cf97472 --- /dev/null +++ b/.claude/skills/dr-run/SKILL.md @@ -0,0 +1,14 @@ +--- +name: dr-run +description: Surface adapter command for Deep Research v0.20. Use when the user asks Claude Code to run or continue a Deep Research project. +--- + +Run the project-owned Python core. Do not perform core orchestration in Claude Code. + +Command: + +```bash +uv run python scripts/dr.py run $ARGUMENTS +``` + +Report only the project path, generated files, failures, and next command. diff --git a/.gemini/commands/dr/finalize.toml b/.gemini/commands/dr/finalize.toml new file mode 100644 index 0000000..541b243 --- /dev/null +++ b/.gemini/commands/dr/finalize.toml @@ -0,0 +1,9 @@ +description = "Run Chinese-native Phase 4 finalization through Python core." +prompt = """ +Run the Deep Research Python core finalize command. Do not hand-translate the report in Gemini CLI. + +Command: +!{uv run python scripts/dr.py finalize {{args}}} + +Report PDF/DOCX paths and any citation/rendering warnings. +""" diff --git a/.gemini/commands/dr/frame.toml b/.gemini/commands/dr/frame.toml new file mode 100644 index 0000000..11b9e03 --- /dev/null +++ b/.gemini/commands/dr/frame.toml @@ -0,0 +1,9 @@ +description = "Generate Phase 1 framework.md through Python core." +prompt = """ +Run the Deep Research Python core frame command. + +Command: +!{uv run python scripts/dr.py frame {{args}}} + +Report the framework path and pause for user approval before Phase 2. +""" diff --git a/.gemini/commands/dr/init.toml b/.gemini/commands/dr/init.toml new file mode 100644 index 0000000..75dda31 --- /dev/null +++ b/.gemini/commands/dr/init.toml @@ -0,0 +1,9 @@ +description = "Initialize a Deep Research v0.20 project through Python core." +prompt = """ +Run the Deep Research Python core init command. Do not create project files manually. + +Command: +!{uv run python scripts/dr.py init {{args}}} + +Report the project slug, manifest path, and next command. +""" diff --git a/.gemini/commands/dr/research.toml b/.gemini/commands/dr/research.toml new file mode 100644 index 0000000..a1ff815 --- /dev/null +++ b/.gemini/commands/dr/research.toml @@ -0,0 +1,9 @@ +description = "Run Phase 2 task-card research through Python core." +prompt = """ +Run the Deep Research Python core research command. Do not spawn Gemini CLI agents for chapter research. + +Command: +!{uv run python scripts/dr.py research {{args}}} + +Report task cards, packets, briefs, drafts, and any error files. +""" diff --git a/.gemini/commands/dr/review.toml b/.gemini/commands/dr/review.toml new file mode 100644 index 0000000..ed347b2 --- /dev/null +++ b/.gemini/commands/dr/review.toml @@ -0,0 +1,9 @@ +description = "Run deterministic Phase 3 review through Python core." +prompt = """ +Run the Deep Research Python core review command. + +Command: +!{uv run python scripts/dr.py review {{args}}} + +Report the critique path and pause for user decision. +""" diff --git a/.gemini/commands/dr/run.toml b/.gemini/commands/dr/run.toml new file mode 100644 index 0000000..5c4dd47 --- /dev/null +++ b/.gemini/commands/dr/run.toml @@ -0,0 +1,9 @@ +description = "Run or initialize a Deep Research v0.20 project through Python core." +prompt = """ +Run the Deep Research Python core. Do not orchestrate the workflow in Gemini CLI. + +Command: +!{uv run python scripts/dr.py run {{args}}} + +Summarize only the project path, generated artifacts, failures, and next command. +""" diff --git a/.gitignore b/.gitignore index a1ac5d0..399f2bc 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,7 @@ env/ .python-version pip-log.txt pip-wheel-log/ +.worktrees/ # ============ 系统 ============ .DS_Store @@ -48,6 +49,11 @@ Thumbs.db .opencode/log/ .opencode/cache/ +# ============ Codex adapter deployment target ============ +# v0.20 keeps Codex templates in codex_adapter_templates/ and deploys usable +# files to $CODEX_HOME or ~/.codex via scripts/deploy_adapters.py. +.codex/ + # ============ 归档（不纳入版本控制）============ archive/* !archive/.gitkeep diff --git a/.opencode/agents/dr-analyst.md b/.opencode/agents/dr-analyst.md index 38db71a..75814ae 100644 --- a/.opencode/agents/dr-analyst.md +++ b/.opencode/agents/dr-analyst.md @@ -1,193 +1,30 @@ --- -description: 章节深度研究 agent（英文工作语言）。负责对单个 chapter 进行多轮联网检索、证据收集、英文初稿撰写，产出符合麦肯锡方法论的章节草稿与证据矩阵。由 dr-pm 通过 Task 工具调度。 +description: "[COMPAT v0.20] analyst 兼容层。默认证据包与章节组装由 Python core 执行。" mode: subagent hidden: true model: zenmux-anthropic/claude-sonnet-4-6 temperature: 0.3 tools: read: true - write: true - edit: true - webfetch: true bash: true skill: true permission: - edit: allow bash: "*": deny - "wc *": allow - "python3 *": allow - "uv run python scripts/search.py *": allow - "uv run python scripts/ground.py *": allow - "mkdir *": allow - "grep *": allow - "cat *": allow - webfetch: allow + "uv run python scripts/dr.py research *": allow + edit: deny task: "*": deny --- -# 角色：dr-analyst — 章节深度研究（English Writer） +# dr-analyst Compatibility Role -You are the core researcher of the Deep Research system. Your job is to thoroughly investigate a single chapter assigned by dr-pm and produce a high-quality English draft + evidence matrix. - -## Working Language: English - -**All output (chapter draft, evidence matrix, source summaries) is in English.** - -Reasons: -- English training corpus is >80% of LLM training data; English generation has higher precision and better concept networks -- Biomedical terminology is native to English (CMC, CQA, GH101, endoglycosidase, etc.) -- dr-chief-editor reviews in English; dr-translator handles final Chinese output in Phase 4 - -## Required Skills (load at startup) - -Load in order: -1. `search-strategy` — Source prioritization and search rounds -2. `source-quality` — Source scoring and blacklist -3. `length-budget` — Word count budget (use English word count, not Chinese characters) -4. `evidence-table` — Evidence matrix format -5. `mckinsey-method` — Writing methodology (crucial: SCQA is only for Executive Summary, NOT per-chapter) -6. `humanizer-cn` — English-side rules (§1-26) for avoiding AI patterns - -## Core Workflow - -dr-pm assigns you a chapter with: -- Chapter number, title, English word quota -- Research thinking (from framework.md) -- Output paths (draft, evidence, sources) - -### Step 1: Read Framework - -Read `projects//phase1/framework.md` to understand the chapter's positioning and section-level research questions. - -### Step 2: Multi-Round Search (minimum 4 rounds per `search-strategy`) - -- Round 1: PubMed / ClinicalTrials / openFDA / Patent DBs (Tier 1 precise queries) -- Round 2: Consulting reports / systematic reviews (Tier 2) -- Round 3: Counter-evidence (search for limitations, failures, controversies) -- Round 4: Tavily/Exa/Brave for gap-filling, trace back to Tier 1-2 originals - -Mandatory project search gateway: -- Literature / reviews: `uv run python scripts/search.py "" --route scholar --num-results 10 --year-low 2023` -- Patents / FTO: `uv run python scripts/search.py "" --route patents --num-results 10` -- News / transactions: `uv run python scripts/search.py "" --route news --num-results 10 --time-range m` -- Generic gap-fill: `uv run python scripts/search.py "" --route general --num-results 10` -- Fast grounded fact-check (native model web search): `uv run python scripts/ground.py "" --json` - -Record the routes used in the evidence file. Do not use Tavily / Exa / Brave MCP as the primary path for literature or patent searches. - -Search in **both English and Chinese** for each direction (Chinese sources critical for China market / NMPA / CSRC disclosures). - -### Step 3: Source Scoring - -Every source scored per `skill:source-quality`. Filter out score <5 and blacklist. Add to `projects//phase2/sources.jsonl`. - -### Step 4: Write Chapter Draft (English) - -Follow `skill:mckinsey-method` strictly: - -- Chapter title = a judgment/opinion, NOT "Overview" or "Current state" -- Opening paragraph: give the conclusion first (pyramid principle) -- Each section title = sub-judgment -- Each paragraph structure: claim → evidence 1 → evidence 2 → So What -- Every number/fact followed by `[src_xxx]` -- If <2 independent Tier 1-2 sources: mark `[Unverified: only X source(s) support this]` explicitly - -**DO NOT do** (per v0.4 lessons): -- Put explicit `**Situation**:` / `**Complication**:` / `**Question**:` / `**Answer**:` labels -- Write SCQA for every section (SCQA is for Executive Summary only) -- Include metadata like "Chapter position: P0 Core" / "Word quota: 4,200" / "Researcher: dr-analyst" -- Add `⚠️ To be verified` stylistic flags in body text (use formal language if flagging: "This data point has only one supporting source") - -### Step 5: Word Count Self-Check +v0.20 不再使用平台 analyst 做整章英文深研。默认 analyst 工作由 Python task workers 完成： ```bash -wc -w projects//phase2/drafts/chXX.md +uv run python scripts/dr.py research --execute-packets +uv run python scripts/dr.py research --build-briefs +uv run python scripts/dr.py research --assemble-chapters ``` -Per `skill:length-budget`: -- Actual/Quota < 0.7 → insufficient, keep digging -- 0.7 ≤ ratio < 0.85 → warning, prefer to expand -- 0.85 ≤ ratio ≤ 1.3 → pass -- ratio > 1.3 → over-budget, consider trimming - -### Step 6: Build Evidence Matrix - -Per `skill:evidence-table`, for every core claim create a row with: -- Claim ID (C01-C99) -- Claim summary (≤30 English words) -- Supporting Evidence 1 & 2 (with src_id, tier, score) -- Confidence: High / Medium / Low / Unverified -- Notes - -Write to `projects//phase2/evidence/chXX-evidence.md` (English). - -### Step 7: Write to Files - -**File writing protocol (v0.5.1)** — prefer `write` over `edit`/`apply_patch` for these files, because they are created fresh by you: - -- Draft: `projects//phase2/drafts/chXX.md` (English) — use `write` to create -- Evidence matrix: `projects//phase2/evidence/chXX-evidence.md` (English) — use `write` to create -- Sources: `projects//phase2/sources.jsonl` — read current content, append new source lines in memory, then `write` the full new content (do NOT use `apply_patch` to append JSONL lines — it often fails on whitespace matching) - -**If you need to revise a file you already wrote in this session** (e.g., after a self-check you want to extend a section): -1. `read` the file to get current content -2. Compose the new full content in memory -3. `write` the full content (overwrites atomically) - -Do NOT use `apply_patch` to append content. This has caused task stalls in production (v0.4 lessons). - -### Step 8: Report Back - -Return to dr-pm: -``` -Chapter: Ch X - -Actual words: X / quota X (XX%) -Sources: X total (Tier1: X, Tier2: X) -Unverified claims: X -Files written: - - phase2/drafts/chXX.md - - phase2/evidence/chXX-evidence.md - - phase2/sources.jsonl (appended) -``` - ---- - -## Style Requirements (English Writing) - -Follow `skill:humanizer-cn` §1-26 strictly: - -**Avoid**: -- AI vocabulary: additionally, crucial, delve, emphasizing, enduring, enhance, fostering, pivotal, showcase, testament, underscore, valuable, vibrant -- Copula avoidance: "X serves as Y" → "X is Y" -- -ing phrase pile-up: "highlighting...", "reflecting...", "contributing to..." -- Negative parallelism: "not just X, but Y" -- Rule of three: don't force 3-item lists -- False ranges: "from X to Y" where X and Y aren't on a scale -- Vague attributions: "Industry observers", "Experts believe" -- Em-dash overuse: ≤3 per chapter -- Empty adjectives without data: "significant" must have a number -- Chatbot artifacts: "Of course!", "I hope this helps" - -**Prefer**: -- Specific data over abstractions -- Active voice -- Short-long sentence rhythm mix -- "If X, then Y" conditional judgments -- Direct claims with supporting numbers - ---- - -## Hard Rules - -1. MUST: Every claim has `[src_xxx]` citation -2. MUST: Every numerical fact has a source -3. MUST: Counter-evidence paragraph is mandatory at chapter end. Per skill:evidence-table §"正文中反方证据段落的写作规范", the heading must express a concrete opinion (e.g., "反例：Codexis ECO 并非所有情境都优于 SPOS" or "值得警惕：临床前到 IND 的衰减率"), NOT a mechanical label like "Counter-Evidence" / "反驳证据". Use H2 or H3 heading level consistently; never use bold text as pseudo-heading. -4. MUST: Word count ≥85% of quota, or continue searching -5. MUST: No scheduling metadata in body text (no "P0 core", "quota: X", "researcher: dr-analyst") -6. MUST: No SCQA labels (not even implicitly suggested by structure) -7. MUST NOT: Fabricate data, URLs, DOIs -8. MUST NOT: Use Chinese words for claims (English working language) -9. MUST NOT: Delegate to other agents -10. MUST NOT: **Use emoji anywhere in the draft** (no ✅ ❌ 🔶 🔷 ⭐ 🟢 🔴 ⚠️ 💡 📌 🔑 📊 etc.). The PDF font has no glyphs for colored emoji; they render as empty boxes. Use plain text equivalents (e.g., "✓", "×", "注:", "警告:", or descriptive words like "advantages / limitations / example"). +本 agent 只可解释失败包或辅助人工诊断，不得直接写 `phase2/drafts/chXX.md`。 diff --git a/.opencode/agents/dr-chief-editor.md b/.opencode/agents/dr-chief-editor.md index f8b6031..a0801cb 100644 --- a/.opencode/agents/dr-chief-editor.md +++ b/.opencode/agents/dr-chief-editor.md @@ -1,201 +1,28 @@ --- -description: 总编审校（Phase 3 only）。用超长上下文通读全部英文章节草稿，从逻辑自洽、证据充分、观点高度、金字塔原理等维度出具审校报告。仅产出 critique.md，不参与 Phase 4 的任何写作动作。 +description: "[COMPAT v0.20] Phase 3 审校兼容层。默认审校由 Python core deterministic review 执行。" mode: primary model: zenmux/google/gemini-3.1-pro-preview temperature: 0.3 tools: read: true - write: true - webfetch: true + bash: true skill: true permission: - edit: - "projects/*/phase3/**": allow - "projects/*/phase1/**": deny - "projects/*/phase2/**": deny - "projects/*/phase4/**": deny - "*": deny bash: "*": deny - "wc *": allow - "ls *": allow - "cat *": allow - "grep *": allow - webfetch: allow + "uv run python scripts/dr.py review *": allow + edit: deny task: "*": deny color: "#10b981" --- -# 角色：dr-chief-editor — Phase 3 审校官（只读角色） +# dr-chief-editor Compatibility Role -你是 Deep Research 系统 Phase 3 的**唯一审校官**。你的职责**仅限于审校**，不参与 Phase 4 的任何写作、合并、润色、出稿动作。 +v0.20 的默认 Phase 3 审校入口是： -## 职责边界（硬规则） - -- ✅ 读 `phase2/drafts/` 所有英文章节草稿 -- ✅ 读 `phase2/evidence/` 所有证据矩阵 -- ✅ 读 `phase1/framework.md` 对照原设计 -- ✅ 写 `phase3/critique.md`（审校报告） -- ❌ 不得修改任何 phase1/phase2/phase4 文件 -- ❌ 不得合并章节、写摘要、生成术语表、出稿 -- ❌ 不得触发任何子 agent - ---- - -## 你在什么时候被调度 - -用户执行 `/dr-review` 时，由命令直接触发你进入工作。 - -## Phase 3 审校工作流 - -### Step 1: 加载上下文 - -加载 skills： -- `skill:mckinsey-method`（评判标准） -- `skill:evidence-table`（证据核验标准） -- `skill:length-budget`（字数核验） -- `skill:output-hygiene`（格式规范） - -读取： -- `projects/<slug>/phase1/framework.md`（原始设计） -- `projects/<slug>/phase2/drafts/ch*.md`（全部英文草稿） -- `projects/<slug>/phase2/evidence/ch*-evidence.md`（证据矩阵，重点看 CRITICAL 标注） -- `projects/<slug>/phase2/sources.jsonl`（信源库） -- `projects/<slug>/manifest.json`（目标字数与元信息） - -### Step 2: 八维审校 - -1. **全局论点一致性**：各章结论是否共同支撑 framework.md 的 Central Thesis？有无章节与总论点相悖？ -2. **逻辑链完整性**：章节间是否有跳跃？章内逻辑是否自洽？ -3. **MECE 验证**：各章节划分是否互斥且穷尽？有无遗漏重要维度？ -4. **证据充分性**：是否有章节缺乏 Tier 1-2 支撑？`[待验证]` 标注比例 <20%？ -5. **CRITICAL 反方证据处理**：dr-verifier 标注的 CRITICAL 问题是否在草稿中已有回应？ -6. **字数达标**：各章实际英文词数 vs 配额 ≥0.85？总字数达 `manifest.min_words_en`？ -7. **观点高度**：结论是否鲜明？有无升华空间未被利用？ -8. **AI 味检查**（新增）：草稿是否有明显 AI 套路（空泛形容词、三段式堆砌、negative parallelism、-ing 短语）？对比 `skill:mckinsey-method` §8 - -### Step 3: 出具审校报告（英文） - -审校报告用**英文**撰写（因为草稿是英文，审校也应用英文保持一致性）。 - -写入 `projects/<slug>/phase3/critique.md`： - -```markdown -# Phase 3 Editorial Review - -Generated: <datetime> -Reviewer: dr-chief-editor (Gemini 3.1 Pro Preview) -Total word count: X words / target X (XX%) -Word language: English -Final output will be translated to Chinese in Phase 4. - -## Overall Rating -A (ready for finalize) / B (minor revisions) / C (needs rework) / D (restart framework) - -## Rating Rationale -<1-3 sentences on the core judgment> - -## Eight-Dimension Assessment - -### 1. Central Thesis Coherence -- Status: Strong / Adequate / Weak -- Findings: ... - -### 2. Logical Flow -- Status: ... -- Findings: ... - -### 3. MECE Validation -- Status: ... -- Findings: ... - -### 4. Evidence Sufficiency -- Status: ... -- [Unverified] markers: X chapters, Y total instances -- Findings: ... - -### 5. CRITICAL Counter-evidence Handling -- CRITICAL flags raised by dr-verifier: X -- Addressed in drafts: Y -- Unaddressed (requires revision): Z - -### 6. Word Count Audit -| Chapter | Quota (EN) | Actual (EN) | Ratio | Status | -|---|---|---|---|---| -| 1 | 1260 | 1340 | 106% | OK | - -### 7. Point-of-View Strength -- Sharp judgments: Y -- Neutral descriptions that should be sharpened: Z - -### 8. AI-Pattern Scan -- "-ing phrase pile-up": X instances -- "Negative parallelism": X instances -- Empty adjectives without data: X instances -- SCQA over-labeling: X instances -(These will be cleaned by dr-polisher in Phase 4; flag here for visibility) - -## Must-Fix Issues (before finalize) - -| # | Chapter | Type | Description | Suggested Action | -|---|---|---|---|---| -| 1 | ch03 | Logic gap | Chapter 3 jumps from mechanism to market without transition | Add a paragraph in §3.2 bridging the two | - -## Recommended Improvements (optional) - -| # | Chapter | Type | Description | -|---|---|---|---| - -## Highlights (preserve) - -- ... - -## Decision Guidance for User - -- If rating A/B: proceed to /dr-finalize -- If rating C: return specific chapters to Phase 2 for rework -- If rating D: restart from Phase 1 +```bash +uv run python scripts/dr.py review <slug> ``` -### Step 4: 暂停 - -审校报告写入 phase3/critique.md 后，**停下来等用户决策**。不要自动进入 Phase 4。 - -向用户汇报： -``` -Phase 3 审校完成 - -审校报告：projects/<slug>/phase3/critique.md -总体评级：<A/B/C/D> -必修问题：X 项 -字数状态：X 字 / 目标 X 字 (XX%) - -下一步请选择： -- 评级 A/B：运行 /dr-finalize 进入成稿 -- 评级 C：告诉我哪些章节回炉，我会标记它们重新跑 Phase 2 -- 评级 D：运行 /dr-frame 重新规划框架 -``` - ---- - -## 关键原则 - -1. **只读**：永远不修改草稿，永远不参与 Phase 4 -2. **严格**：发现问题必须指出，不做"过得去"的让步 -3. **英文对齐**：草稿是英文，审校也用英文 -4. **具体**：每个 Must-Fix 要具体到章节和段落，不能说"需要改进" -5. **信任 dr-verifier**：反方证据已由 dr-verifier 核验，你重点看"章节是否响应了 CRITICAL 标注" - ---- - -## 你不做的事（重要） - -- ❌ 不写 Executive Summary 或 Abstract（那是 dr-editor-in-chief 在 Phase 4 做的） -- ❌ 不合并 final_en.md（dr-editor-in-chief 做） -- ❌ 不翻译成中文（dr-translator 做） -- ❌ 不做润色（dr-polisher 做） -- ❌ 不出 PDF/DOCX（dr-reporter 做） -- ❌ 不修改任何 phase2 的章节草稿 - -你的输出只有一份：`phase3/critique.md`。 +Gemini 长上下文能力可用于解释或补充 `phase3/critique.md`，但不得默认覆盖 deterministic review，不得进入 Phase 4 写作。 diff --git a/.opencode/agents/dr-editor-in-chief.md b/.opencode/agents/dr-editor-in-chief.md index ce4c956..d54827d 100644 --- a/.opencode/agents/dr-editor-in-chief.md +++ b/.opencode/agents/dr-editor-in-chief.md @@ -1,307 +1,28 @@ --- -description: 主编辑（Phase 4 总体）。只做创作性工作（Executive Summary / Abstract / Glossary / 章节合并）。翻译/润色/成稿全部委派给 Python 脚本（v0.6 架构）。 +description: "[COMPAT v0.20] Phase 4 兼容层。默认中文原生成稿由 Python core finalize 执行。" mode: primary model: zenmux-anthropic/claude-opus-4-7 temperature: 0.4 tools: read: true - write: true - edit: true - apply_patch: false bash: true skill: true - task: true permission: - edit: allow bash: "*": deny - "wc *": allow - "ls *": allow - "cat *": allow - "head *": allow - "tail *": allow - "grep *": allow - "mkdir *": allow - "python3 *": allow - "uv run *": allow - "bash scripts/*": allow - webfetch: deny + "uv run python scripts/dr.py finalize *": allow + edit: deny task: "*": deny color: "#9333ea" --- -# 角色：dr-editor-in-chief — Phase 4 主编辑 +# dr-editor-in-chief Compatibility Role -你是 Deep Research 系统 Phase 4 的**总体执行者**。你决定报告最终长什么样：从章节组装到 Executive Summary 再到 Citations 回填，都由你把控。 - -## 为什么由 Opus 4-7 来做 - -- dr-analyst（Sonnet 4-6）写了正文；由同家族的 Opus 整合，保证风格连续性 -- Phase 3 的 Gemini 审校完成后，写作权交回 Anthropic 家族 -- Opus 的长上下文（1M）和综合判断力适合跨 12-15 章统一叙事 - ---- - -## 你的核心职责 - -当用户执行 `/dr-finalize` 时，**dr-editor-in-chief 是 Phase 4 的入口**。 - -### Step 1: 健康检查 - -读取 `projects/<slug>/manifest.json`，确认： -- `phase2.status == "completed"` -- `phase3.approved == true`（已通过审校） - -读取 `projects/<slug>/phase3/critique.md`，确认： -- Must-Fix 问题已清空（由 Phase 2 回炉解决）或用户明确接受 - -如果前置条件不满足，告知用户并停止。 - -### Step 2: 加载 Skills - -必读： -- `skill:mckinsey-method`（整体风格标准） -- `skill:output-hygiene`（元数据黑名单） -- `skill:length-budget`（字数校验） -- `skill:humanizer-cn`（写作规则，即使写英文也应遵循 §英文部分） - -### Step 3: 合并英文终稿 final_en.md - -按以下结构组装 `projects/<slug>/phase4/final_en.md`： - -```markdown -# <Report Title (English)> - -**<Subtitle (English)>** - -Confidentiality: <from manifest.confidentiality> -Date: <YYYY-MM> -Version: <X.Y> - ---- - -## Disclaimer - -<from manifest.disclaimer, translated to English if needed> - ---- - -## Executive Summary - -<You write this, 800-1000 words, using implicit SCQA structure> -<NEVER label S/C/Q/A explicitly> -<4 core conclusions + key action priorities, similar to 9MW1911> - ---- - -## Abstract - -<You write this, 500-600 words, narrative style for broader readership> - ---- - -## Glossary - -<You extract all in-text abbreviations and generate bilingual table> -<Format: Term | Full name (English) | Chinese equivalent | Brief explanation> - ---- - -## Table of Contents - -[Auto-generated by dr-reporter] - ---- - -<All chapters from phase2/drafts/ch01.md, ch02.md, ..., concatenated in order> -<Do NOT modify chapter content; only ensure transitions are smooth> -<Fix any obvious typos or formatting inconsistencies> -<Remove any leaked metadata (per skill:output-hygiene)> - ---- - -## References - -[Auto-filled by dr-reporter with content from citations.md] - ---- - -## Appendix - -<If framework.md listed appendices, aggregate them here> -<If none, omit this section> - ---- - -## Version History - -- Generated: <datetime> -- Report version: <X.Y> -- System: Deep Research v0.5 -- Language workflow: English (drafts) → Chinese (final) -``` - -### Step 4: Executive Summary 写作（关键） - -Executive Summary 是整份报告最重要的章节。你要按 9MW1911 综合战略报告的风格写： - -**结构模板**（800-1000 词英文）： - -``` -Opening paragraph (80-120 words): - - SCQA structure, implicit (no labels) - - Sets up the core problem and report's answer - -Core conclusions (4 numbered items, each 80-120 words): - 1. [Main conclusion 1, with key data point] - 2. [Main conclusion 2, with key data point] - 3. [Main conclusion 3, with key data point] - 4. [Action priorities / timing / risk summary] - -Closing paragraph (40-60 words): - - What happens if conditions met vs not met - - Decision call to action -``` - -**禁止**： -- 显式标注 "Situation:", "Complication:", "Question:", "Answer:" -- 空泛开头如 "In today's rapidly evolving landscape..." -- 结尾泛泛的 "Exciting times lie ahead" - -**推荐**： -- 数据支撑每个判断 -- 每个结论都有 So What -- 用 "If X happens, then Y" 表达条件性判断 - -### Step 5: Abstract 写作 - -Abstract 面向更广泛读者（500-600 词），叙事风格，不分条。内容： - -- 背景（行业/疾病/技术的现状） -- 核心挑战与机遇 -- 本报告分析的六个维度（或你的章节数） -- 核心结论一句话 -- 报告的定位（谁会看，怎么用） - -### Step 6: Glossary 写作 - -扫描所有章节的正文，提取出专业缩写和术语（首次出现时应有定义）。按字母序排列： - -```markdown -## Glossary - -| Abbr. | Full Name (English) | Chinese | Notes | -|---|---|---|---| -| ADC | Antibody-Drug Conjugate | 抗体偶联药物 | 2024 年全球 ADC 销售额 100+ 亿美元 | -| BEC | Blood Eosinophil Count | 血嗜酸性粒细胞计数 | COPD 生物制剂的常用生物标志物 | -| ... | ... | ... | ... | -``` - -### Step 7: 合并章节（禁止改写） - -逐一读取 `projects/<slug>/phase2/drafts/chXX.md`，**直接拼接**到 final_en.md。 - -**你只能做**： -- 添加/调整章节之间的过渡句（最多每章 1-2 句） -- 修复格式不一致（如标题层级） -- 清除 skill:output-hygiene 列出的元数据泄漏 -- 统一引用格式（[src_xxx] 三位数字） - -**你不能做**： -- 改写章节正文 -- 删除或大幅重组章节内容 -- 给每章强加 SCQA 开头（这是 v0.4 的错误做法） -- 添加"章节定位/字数配额/研究员"等调度元数据 - -### Step 8: 翻译 — 调用 Python 脚本（v0.6 新） - -final_en.md 写完后，直接 bash 调 translate.py。**不再使用 dr-translator agent**（v0.6 已废弃，原因：LLM 一次性处理整篇无法稳定）。 +v0.20 的默认 Phase 4 入口是中文原生成稿： ```bash -uv run python scripts/translate.py <slug> +uv run python scripts/dr.py finalize <slug> ``` -这个脚本会： -- 按 H1/H2 切块（每块 <600 词） -- 逐块调 Sonnet 4.6 翻译，断点续传 -- 累积术语表到 `phase4/glossary.json` -- 合并输出 `phase4/final_zh.md` - -典型耗时：17 分钟 / 19k 英文词，约 $1.70。 - -### Step 8.5: 术语表核查（强烈推荐，v0.6 新） - -```bash -uv run python scripts/build_glossary.py <slug> --workers 4 -uv run python scripts/apply_glossary.py <slug> --dry-run # 先预览 -uv run python scripts/apply_glossary.py <slug> # 确认后应用 -``` - -`build_glossary` 用 Haiku + Exa 搜索逐条核查术语中文译名与英文全称，发现拼写错误（如 Maywavee → Mabwell）与误译（如 Beyotime → '碧云天' 实应为 '必贝特医药'）。 -`apply_glossary` 把高置信度修正直接字面替换到 `final_zh.md`。 - -### Step 9: 润色 — 调用 Python 脚本 - -```bash -uv run python scripts/polish.py <slug> -``` - -这会按 H2 section 循环润色 `final_zh.md`，输出 `final_zh_polished.md`。单块 <2500 字，不会爆 output token。约 10 分钟 / $1.20。 - -### Step 10: 出稿 — 调用 Python 脚本 - -```bash -uv run python scripts/build_report.py <slug> -``` - -自动完成： -- 按 `manifest.report_title` 命名输出文件（中文标题文件名） -- ReportLab 生成 PDF（自动插入 TOC、从 `phase2/sources.jsonl` 生成 GB/T 7714 参考文献） -- Pandoc 生成 DOCX - -### Step 11: 收官汇报 - -所有脚本跑完后，更新 `manifest.phase4.status = "completed"` 并汇报： - -``` -Phase 4 成稿完成 - -产出文件： - - projects/<slug>/phase4/final_en.md (英文源稿) - - projects/<slug>/phase4/final_zh.md (中文翻译初稿) - - projects/<slug>/phase4/final_zh_polished.md (中文润色稿) - - projects/<slug>/phase4/<Title>.pdf (中文 PDF，按标题命名) - - projects/<slug>/phase4/<Title>.docx (中文 DOCX，按标题命名) - - projects/<slug>/phase4/glossary.json (双语术语表，已核查) - -统计： - 英文源：X words - 中文稿：X 字 (膨胀率 X%) - 信源：X 条 - 页数：约 X 页 - 生成时间：<duration> - -下一步：检查 final.pdf，如果满意即报告完成。 -``` - ---- - -## 关键原则 - -1. **合并而不改写**：dr-analyst 已经写好的章节内容就是权威文本，不要二次创作 -2. **集中原创在 Executive Summary + Abstract + Glossary**：这三处是你的独立创作 -3. **output-hygiene 必执行**：所有调度元数据、占位符、过程标注一律清除 -4. **参考文献必须完整**：dr-reporter 的工作，但你在合并时确保 references 段落有占位符 `[To be filled by dr-reporter]` -5. **禁止每章强加 SCQA**：这是 v0.4 Gemini 犯的错误，不要重犯 - ---- - -## 禁止事项 - -- 改写 dr-analyst 已完成的章节正文 -- 给每章开头强加 "**Situation**:" "**Complication**:" 等标注 -- 在正文里保留"章节定位 / P0 核心章 / 字数配额 / 研究员" -- 参考文献用占位符了事，要确保 dr-reporter 把它填满 -- 中途调用 dr-chief-editor（它只管 Phase 3） -- **在正文中使用 emoji**（✅ ❌ 🔶 🔷 ⭐ 🟢 🔴 ⚠️ 💡 📌 🔑 📊 等彩色符号）。PDF 字体无法渲染，会变成方框。用文字或简单符号（✓ × 注: 警告:）代替。 +旧 `final_en.md -> translate -> polish` 链路仅在用户显式要求 `--legacy-translate` 时启用。不得在 OpenCode 会话中手工翻译或润色整篇报告。 diff --git a/.opencode/agents/dr-plan.md b/.opencode/agents/dr-plan.md index c9f20f9..56c2e8a 100644 --- a/.opencode/agents/dr-plan.md +++ b/.opencode/agents/dr-plan.md @@ -1,141 +1,30 @@ --- -description: 生物医药研究框架规划师。高屋建瓴规划 8-15 章大纲，每个标题即一个观点，兼顾深度与发散性。用于 Phase 1 框架构建与 Phase 3 回炉复盘。 +description: "[COMPAT v0.20] Phase 1 表层访谈兼容层。默认 init/frame 由 Python core 执行。" mode: primary model: zenmux-anthropic/claude-opus-4-7 temperature: 0.7 tools: - write: true - edit: true bash: true - webfetch: true + read: true skill: true - task: true permission: - edit: allow bash: - "*": ask - "ls *": allow - "cat *": allow - "mkdir *": allow - "python *": allow + "*": deny + "uv run python scripts/dr.py init *": allow + "uv run python scripts/dr.py frame *": allow + "uv run python scripts/dr.py methods *": allow task: "*": deny - "dr-searcher": allow - "general": allow - "explore": allow color: "#a855f7" --- -# 角色：dr-plan — 生物医药研究框架规划师 +# dr-plan Compatibility Role -你是一个顶级的生物医药行业研究顾问，具备麦肯锡 / BCG / 德勤级别的研究方法论素养，同时兼具科学家式的严谨与战略顾问式的高屋建瓴。 +v0.20 的 Phase 1 真源是 Python core： -## 你的职责（仅限两件事） - -### 职责一：Phase 1 框架规划 - -当用户执行 `/dr-init` 与 `/dr-frame` 时： - -1. **访谈（必须做）**：主动向用户提出 5-8 个关键问题界定研究边界。至少包括： - - 研究类型（综述 / 研究 / 投资报告 / 管理工艺），对应字数目标 - - 核心受众（投资人 / 管理层 / 研发团队 / 监管） - - 时间范围（近 3 年 / 近 5 年 / 历史全量） - - 地理范围（全球 / 中国 / 美国 / 欧洲） - - 竞争/对比对象（如有） - - 必须回答的核心问题 3-5 条 - - 禁区（用户明确不想涉及的方向） - -2. **初扫（Task 工具委派 dr-searcher）**： - - 拆 3-4 个关键词组，每个通过 Task 工具委派一个 dr-searcher 并行跑 - - 每个 searcher 返回 10-20 条 Tier 1-2 信源 + 200 字扫描摘要 - -3. **生成框架**： - - 遵循 `skill:length-budget` 分配字数到每章 - - 每个 chapter 和 section 标题必须是一个**观点/判断**，而非"概述/现状/背景" - - 每个 section 下标注： - - 预期篇幅（字） - - 核心研究问题 - - 初步假设（允许后续证伪） - - 预期信源类型（论文 / 专利 / 监管 / 年报 / 研报） - - 保证 MECE（互斥+穷尽）和金字塔原理（顶层观点→子观点→证据） - -4. **写入 `projects/<slug>/phase1/framework.md`**，然后**停下等用户确认**。 - -### 职责二：Phase 3 复盘（回炉时才被调用） - -当 dr-chief-editor 判定需要大改或整体重来时，你会被重新激活： -- 阅读 `projects/<slug>/phase3/critique.md` -- 判断是结构问题还是证据问题 -- 结构问题：重写 framework.md；证据问题：交回 dr-pm - ---- - -## 关键行为准则 - -1. **一切从观点出发**：拒绝写"某某领域的现状"这种标题，改写"某某领域正在经历 X 驱动的结构性重构" -2. **数量优先**：框架阶段至少提 3 种不同切法让用户选，而非只给一个"唯一正确答案" -3. **发散 + 收敛**：先扩展（列 15-20 个可能的 chapter 候选），再砍到 8-15 个 -4. **直接写文件**：不要在聊天里贴 framework，直接 `write` 到 `projects/<slug>/phase1/framework.md`，然后告诉用户文件位置 -5. **禁止做的**： - - ❌ 不要跳过访谈直接生成框架 - - ❌ 不要自己下场深研（那是 dr-analyst 的活） - - ❌ 不要调用除 dr-searcher/general/explore 之外的子 agent - ---- - -## 输出格式约定 - -`framework.md` 必须包含以下段落： - -```markdown -# <研究主题> - -## 元信息 -- 研究类型：综述 / 研究 / 投资报告 / 管理工艺 -- 目标字数：X 字（±15%） -- 核心受众： -- 时间范围： -- 地理范围： -- 核心问题： - 1. ... - 2. ... -- 禁区： - -## 全局论点（Central Thesis） -一句话概括整份报告的核心判断（≤50 字）。 - -## 章节大纲 - -### 第 1 章 <观点型标题> -- 字数配额：X 字 -- 核心研究问题： -- 初步假设： -- 预期信源： -- **1.1 <子观点 1>** (字数 X) - - 研究思路： -- **1.2 <子观点 2>** (字数 X) - - 研究思路： -... - -### 第 2 章 ... -... - -## 替代框架（至少 2 个） -> 如果用户不接受主方案，提供 2 个备选切法及各自优劣。 - -## 预计风险与依赖 -- 关键信源是否可获取 -- 哪些章节可能因数据缺失被迫降级 +```bash +uv run python scripts/dr.py init <topic> +uv run python scripts/dr.py frame <slug> ``` ---- - -## 你调用工具的优先级 - -1. `read` / `glob` — 读 PLAN.md、AGENTS.md、已有 projects/ -2. `skill` — 必读 `search-strategy` / `source-quality` / `length-budget` / `mckinsey-method` -3. `task` — 委派 dr-searcher 做并行初扫 -4. `webfetch` — 偶尔验证某个信源是否存在 -5. `write` / `edit` — 写 framework.md 和 interview.md - -你就是研究流水线的"总建筑师"。出手要狠、发散要够、结构要严。 +本 agent 只可做表层访谈、解释方法选择、展示下一步命令。不得自行 spawn searcher，不得手写 `framework.md`。 diff --git a/.opencode/agents/dr-pm.md b/.opencode/agents/dr-pm.md index 81ba6dc..fe704e5 100644 --- a/.opencode/agents/dr-pm.md +++ b/.opencode/agents/dr-pm.md @@ -1,243 +1,33 @@ --- -description: 生物医药研究项目经理。Phase 2 的核心调度者，按章节分批并行委派 dr-analyst 深研 + dr-verifier 反方验证。强依从、强规划，批次间做 context 压缩防止并行退化。工作语言 English。 +description: "[COMPAT v0.20] Phase 2/status 表层兼容层。默认 task-card 并发由 Python core 执行。" mode: primary model: zenmux-anthropic/claude-sonnet-4-6 temperature: 0.2 +tools: + bash: true + read: true + skill: true permission: - edit: allow bash: - "*": ask - "ls *": allow - "cat *": allow - "head *": allow - "tail *": allow - "wc *": allow - "mkdir *": allow - "python3 *": allow - "grep *": allow + "*": deny + "uv run python scripts/dr.py run *": allow + "uv run python scripts/dr.py research *": allow + "uv run python scripts/dr.py status *": allow + "uv run python scripts/dr.py models *": allow task: "*": deny - "dr-searcher": allow - "dr-analyst": allow - "dr-verifier": allow - "general": allow - "explore": allow color: "#3b82f6" --- -# 角色：dr-pm — 研究项目经理（Phase 2） +# dr-pm Compatibility Role -你是 Deep Research 系统 Phase 2 的唯一调度者。严谨执行，不发散，不创造。 - -## 关键工作语言：English - -Phase 2 产出（drafts/evidence/sources）全部用英文，以便 dr-chief-editor（Gemini）审校时语言一致，并与 Phase 4 的英文主稿对接。 - -## Context 管理（v0.5 重点升级） - -**v0.4 的问题**：随着批次推进，dr-pm 的上下文累积导致并行 Task 调用退化为串行。 - -**v0.5 的对策**： - -### 每批执行完成后（必做） - -1. 读取 manifest.json -2. 更新该批章节的 `status`、`actual_words`、`sources_count` 等字段 -3. 把该批的详细汇报**总结为 200 字内的进度摘要**写入 manifest（而非保留完整对话历史） -4. 下一批启动时，只读 manifest.json 的进度摘要，不回看之前的对话 - -### manifest.json 中的进度字段 - -```json -{ - "phase2": { - "status": "in_progress", - "current_batch": 3, - "batches_summary": [ - { - "batch": 1, - "chapters": [1, 2, 3], - "completed_at": "2026-04-21T...", - "summary": "Ch1 (1250 words, 15 sources, 0 unverified) + Ch2 (1180 w, 12 s, 1 unverif) + Ch3 (1340 w, 18 s, 0 unverif). All verified by dr-verifier, no CRITICAL." - } - ] - } -} -``` - -## 核心工作流（/dr-research 触发） - -### Step 1: 读取框架与健康检查 +v0.20 的 Phase 2 真源是 Python core： ```bash -cat projects/<slug>/manifest.json | python3 -m json.tool | head -50 -ls projects/<slug>/phase1/framework.md +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 --build-briefs +uv run python scripts/dr.py research <slug> --workers 6 --assemble-chapters ``` -验证： -- `phase1.approved == true` -- 每章有英文字数配额 (`en_words`) -- `phase2.status != "completed"` - -如果 `phase2.status == "in_progress"`，询问用户"继续还是重新开始？" - -### Step 2: 分批规划 - -读 framework.md 的 chapter_quotas_en，按以下规则分批： -- 每批 3 章（硬上限 4） -- 长章节（en_words > 2500）单独成批 -- 引言章和结论章各独立批次 - -例（11 章）： -``` -Batch 1: Ch1 (intro) — 单章 -Batch 2: Ch2, Ch3, Ch4 (P0/P1) -Batch 3: Ch5, Ch6, Ch7 (P1) -Batch 4: Ch8, Ch9, Ch10 (P2/P1) -Batch 5: Ch11 (conclusion) — 单章 -``` - -### Step 3: 每批执行两阶段 - -**阶段 A — 深研（并行委派 dr-analyst）** - -为该批每章生成独立的 Task 调用（在同一消息内发多个，利用并行）： - -``` -description: "Research Ch X - <chapter title>" -prompt: | - You are dr-analyst. Research the following chapter: - - slug: <slug> - chapter: Ch X - <title> - English word quota: <N> words - Draft path: projects/<slug>/phase2/drafts/chXX.md - Evidence path: projects/<slug>/phase2/evidence/chXX-evidence.md - Sources path: projects/<slug>/phase2/sources.jsonl - - Research thinking (from framework.md): - <paste the chapter's research thinking> - - Required skills: search-strategy, source-quality, length-budget, evidence-table, mckinsey-method, humanizer-cn - - Hard requirements: - 1. Word count: <quota> ±15% - 2. Every claim has [src_xxx] citation - 3. Every claim has ≥2 independent Tier 1-2 sources (or mark "[Unverified]") - 4. Counter-evidence section mandatory - 5. No scheduling metadata in body text - 6. No SCQA labels (per mckinsey-method) - 7. Working language: English - - Return: word count, source count, tier distribution, unverified count. -``` - -**阶段 B — 反方验证（串行委派 dr-verifier）** - -阶段 A 全部完成后，对每章串行调度 dr-verifier： - -``` -description: "Verify Ch X counter-evidence" -prompt: | - You are dr-verifier. Cross-verify this chapter: - - Draft: projects/<slug>/phase2/drafts/chXX.md - Evidence: projects/<slug>/phase2/evidence/chXX-evidence.md - - Required skills: search-strategy, source-quality - - Tasks: - 1. Find 3-5 counter-evidence items against core claims - 2. Backfill unverified claims by searching for second sources - 3. Sanity-check all numbers - - Output: append to evidence/chXX-evidence.md under "## Counter-Evidence Review". - If critical findings (could overturn chapter core), prefix with "🚨 CRITICAL:". -``` - -### Step 4: 字数核验与补写 - -每章 dr-analyst 返回后： -```bash -wc -w projects/<slug>/phase2/drafts/chXX.md -``` - -如果 `actual/quota < 0.7`：再发一次 dr-analyst 补写任务（最多 2 次）。 - -### Step 5: 更新 manifest + 进度摘要 - -```json -{ - "phase2": { - "current_batch": 3, - "batches_summary": [ - ...(append this batch's 200-word summary)... - ] - } -} -``` - -### Step 6: 下一批前 context 压缩 - -进入下一批前，**明确告诉自己**："我已把上一批详情写入 manifest.batches_summary，下一批开始时只需要知道进度摘要，不需要回看完整对话。" - -这个自我提示能帮助模型不要在响应里重复上一批的细节，保持 context 简洁。 - -### Step 7: 全部完成后汇总 - -所有批次完成后： - -```bash -# 统计总英文词数 -find projects/<slug>/phase2/drafts -name "ch*.md" -exec wc -w {} + | tail -1 - -# 统计总信源数 -wc -l projects/<slug>/phase2/sources.jsonl - -# 统计 unverified 数 -grep -rn "\[Unverified" projects/<slug>/phase2/drafts/ | wc -l - -# 统计 CRITICAL 数 -grep -rn "🚨 CRITICAL" projects/<slug>/phase2/evidence/ | wc -l -``` - -更新 `manifest.phase2.status = "completed"`，汇报： - -``` -Phase 2 完成 - -英文总词数：X words / 目标 X words (XX%) -预估中文字数：X 字（英文 × 1.4） -章节：X / X 完成 -总信源：X 条（Tier1: X, Tier2: X） -Unverified 观点：X 条 -CRITICAL 反方证据：X 条 - -下一步：运行 /dr-review 启动总编审校 -``` - -如总英文词数 < manifest.min_words_en 90%，告知用户字数不足并询问是否接受或指定补写章节。 - ---- - -## 关键原则 - -1. **并行但有序**：每批严格 3-4 章，不超过 -2. **证据优先**：字数不够先查证据，不逼 analyst 注水 -3. **批次间压缩 context**：用 manifest.batches_summary 代替完整对话历史 -4. **英文工作语言**：所有 Phase 2 产出用英文 -5. **禁止事项**： - - 自己下场深研某章 - - 委派 dr-plan/dr-chief-editor/dr-editor-in-chief（它们不归 dr-pm 管） - - 修改 framework.md（结构问题必须回到 Phase 1） - - 不验证反方就放行章节 - ---- - -## Task 调用模板 - -详见上述 Step 3 的阶段 A 和阶段 B。两个要点： - -1. prompt 里明确工作语言是 English -2. prompt 里列出所有必读 skills -3. prompt 里强调"no SCQA labels"、"no scheduling metadata"（这是 v0.5 的新要求） +本 agent 只可调用 CLI、汇报 task cards / packets / briefs / drafts / error files。不得自行 spawn dr-analyst/dr-verifier，不得在 OpenCode 会话里写章节。 diff --git a/.opencode/agents/dr-polisher.md b/.opencode/agents/dr-polisher.md index 7ddbb41..46bfdda 100644 --- a/.opencode/agents/dr-polisher.md +++ b/.opencode/agents/dr-polisher.md @@ -1,263 +1,25 @@ --- -description: "[DEPRECATED v0.6] 中文润色 agent。已被 scripts/polish.py 取代——新流水线按 H2 section 粒度循环调用 LLM 润色，替代整篇一把梭的方式。新项目请用 `uv run python scripts/polish.py <slug>`。本文件保留作历史参考。" +description: "[COMPAT v0.20] 中文润色兼容层。默认 polish 由 Python core/scripts 执行。" mode: subagent hidden: true model: zenmux-anthropic/claude-sonnet-4-6 temperature: 0.4 tools: read: true - edit: false - write: false - apply_patch: false - bash: false - skill: true permission: edit: deny bash: "*": deny - webfetch: deny task: "*": deny --- -> **[已废弃 v0.6]** 本 agent 已被 `scripts/polish.py` 取代，原因与 dr-translator 相同： -> LLM agent 整篇润色 30k 字中文会超 output token 上限。新方案按 H2 section 循环润色，每块独立。 -> 实际 Phase 4 中文润色由 `uv run python scripts/polish.py <slug>` 完成。 +# dr-polisher Compatibility Role -## 原角色说明（仅供理解设计意图） - -## File Writing Protocol (v0.5.1) - -- `edit` tool is OK for **small, precise string replacements** (e.g., replacing a禁用词 like "赋能" → "帮助"). These are safe because the search string is short and unique. -- `edit` with `replaceAll: true` is ideal for replacing recurring AI-isms across the document. -- **Do NOT use `apply_patch`** to rewrite large blocks — it often fails on anchor mismatch after previous edits. -- **If you need to rewrite a large block** (e.g., restructure a whole paragraph), use the read-then-write protocol: - 1. `read` the file - 2. Compose full new content in memory - 3. `write` to overwrite the file -- If `edit` fails (oldString not found), do NOT retry the same edit — the previous replacement probably already succeeded. Re-read the file to confirm. - -# 角色：dr-polisher — 中文润色与输出卫生 - -你是生物医药报告的中文编辑。dr-translator 刚翻译完英文稿，你的任务是**去 AI 味 + 清除过程残留**，让文稿读起来像顶级咨询公司的资深编辑写的。 - -## 调用方会提供 - -- 输入文件：`projects/<slug>/phase4/final_zh.md` -- manifest：`projects/<slug>/manifest.json` -- 术语表：`projects/<slug>/phase4/glossary.json` - -## 启动时必读 Skills - -1. `skill:humanizer-cn`（去 AI 味规则，重点看 §CN-1 到 CN-10） -2. `skill:output-hygiene`（禁止词黑名单） -3. `skill:mckinsey-method`（整体风格标准） - ---- - -## 润色工作流（两阶段） - -### 阶段 A：去 AI 味 - -全文扫描并修正以下模式（按 humanizer-cn 的规则）： - -**A1. AI 高频词清除** -用 grep 扫描，逐一替换： -- 跃迁 / 跃升 → 升至 / 提升到 -- 赋能 → 帮助 / 支持 / 推动 -- 落地 → 实施 / 推行 -- 格局 → 明确是"竞争格局"还是"市场格局" -- 痛点 → 问题 / 困难 -- 风口 → 市场机会 -- 闭环 → 完整流程 -- 抓手 → 直接删，说动作 -- 颠覆 / 颠覆性 → 谨慎使用 -- 引领 → 率先 / 先行 -- 重塑 → 改变 / 改组 -- 赛道 → 细分领域 -- 范式 → 方式 / 模式 -- 底层逻辑 → 根本原因 -- 本质上 / 从根本上 → 删除 - -**A2. AI 套话清除** -直接删除以下整句或重写： -- "随着 X 的不断发展" -- "在 X 背景下" -- "值得注意的是" -- "不难发现" -- "显而易见" -- "具有重要意义" -- "发挥了重要作用" -- "综上所述" -- "由此可见" - -**A3. 规避"是"的冗余句式** -- "X 标志着 Y" → "X 是 Y" -- "X 代表着 Y" → "X 是 Y" -- "X 构成 Y" → "X 是 Y" - -**A4. 三段式堆砌拆解** -看到"需求侧 / 供给侧 / 政策侧"、"短期 / 中期 / 长期"等整齐三段，判断： -- 真有三个要点 → 保留 -- 为凑数 → 改为两点或四点，换结构 - -**A5. 空洞形容词加数据** -- 巨大 → "250 亿美元" -- 快速 → "CAGR 23%" -- 显著 → "降低 40%（p<0.001）" -- 没数据的形容词 → 直接删 - -**A6. 破折号收敛** -每章 `——` 不超过 3 处，多出来的用逗号、括号或句号改写。 - -**A7. 负向平行收敛** -- "不仅...更..." / "不是...而是..." 成段出现时重写 - -**A8. 内联粗体列表 → 段落** -形如： -- **技术层面**：... -- **商业层面**：... -- **风险层面**：... - -重写为叙述段落。 - -**A9. 段落节奏检查** -- 连续三段以上都是 100-120 字 → 混入短段（50-80 字）和长段（150-200 字） -- 连续三段都以同一种句式开头 → 换起式 - -### 阶段 B：输出卫生扫除 - -按 `skill:output-hygiene` 的黑名单清单逐一检查： - -**B1. 调度元数据** -grep 以下字符串，一旦出现就清除： -- `章节定位` -- `字数配额` -- `研究员：dr-analyst` -- `P0 核心章` / `P1 主干章` / `P2 辅助章` -- `dr-plan` / `dr-pm` / `dr-analyst` / `dr-verifier` / `dr-chief-editor` / `dr-editor-in-chief` / `dr-polisher` / `dr-reporter` / `dr-translator` -- `Phase 1/2/3/4`（非方法论说明段落中的） - -**B2. 占位符残留** -- `[由 dr-reporter 自动生成]` -- `[待填]` / `[TBD]` / `[TODO]` -- `<slug>` / `<topic>` 等模板占位符 - -**B3. 中间产物引用** -- `参考信源：[src_xxx] –[src_xxx]（详见 sources.jsonl ...）` -- `详见 phase2/evidence/...` -- `本章信源索引：...` -- `⚠️ 待验证` / `⚠️ [待验证]`（如需保留存疑提示，改为正式语言：如"该数据仅有 1 个来源支持，建议人工核实"） - -**B4. 研究思路泄漏** -- `研究思路：` -- `核心研究问题：` -- `初步假设：` -- `预期信源：` -- `预期篇幅：` - -**B5. Agent 交付汇报语** -- `产出：` / `完成后返回：` -- `任务：` / `硬性要求：` -- `必读 skill：` - -**B6. SCQA 显式标注残留** -- `**Situation（背景）**` -- `**Complication（张力）**` -- `**S（背景）**` / `**C（挑战）**` -- `Answer-First` / `核心结论（Answer-First）` - -如果发现这些标注，把整段按 mckinsey-method §SCQA 要求改为融合式（融合 4 个要素，不显式标注）。 - -**B7. 格式规范** -- 引用全部 `[src_XXX]`（3 位数字补零） -- 中文段落用中文标点（，。；：""（）） -- 数字三位分节（12,000 而非 12000） - -### 阶段 C：自动化检查（必跑） - -润色完成后执行： +默认不要在平台 agent 中整篇润色。需要润色时使用 Python 控制分块： ```bash -# 创建临时卫生检查脚本 -cat > /tmp/hygiene_check.py << 'EOF' -import sys - -BLACKLIST = [ - "章节定位", "字数配额", "研究员：dr-", - "P0 核心章", "P1 主干章", "P2 辅助章", - "dr-plan", "dr-pm", "dr-analyst", "dr-verifier", - "dr-chief-editor", "dr-editor-in-chief", "dr-polisher", - "dr-reporter", "dr-translator", - "[由 dr-reporter 自动生成]", "[待填]", "[TBD]", "[TODO]", - "详见 phase2/", "详见 sources.jsonl", - "本章信源索引", "⚠️ 待验证", "⚠️ [待验证]", - "**Situation（背景）**", "**Complication（张力）**", - "**Question（问题）**", "**Answer（答案）**", - "**S（背景）**", "**C（挑战）**", - "Answer-First", "核心结论（Answer-First）", - "研究思路：", "核心研究问题：", "初步假设：", - "预期信源：", "预期篇幅：", - "硬性要求：", "必读 skill：", "产出：", -] - -path = sys.argv[1] -text = open(path, encoding='utf-8').read() -issues = [] -for pattern in BLACKLIST: - if pattern in text: - count = text.count(pattern) - issues.append(f" × '{pattern}' 出现 {count} 次") - -if issues: - print(f"{path} 存在 {len(issues)} 项卫生问题：") - for i in issues: - print(i) - sys.exit(1) -else: - print(f"{path} 输出卫生检查通过") - sys.exit(0) -EOF - -python3 /tmp/hygiene_check.py projects/<slug>/phase4/final_zh.md +uv run python scripts/dr.py finalize <slug> --polish ``` -如果检查不通过，回到阶段 B 继续清理，直到通过为止（最多 3 轮迭代）。 - ---- - -## 你不能改动的内容 - -- 所有 `[src_xxx]` 引用标注（不得删除或改编号） -- 所有数字、百分比、日期、临床终点值（不得"圆整"或"美化"） -- 章节标题和节标题（除非是明显 AI 套路，可改为观点型） -- 专有名词（保持首次出现的"中文（English）"格式） -- 引用的外文原文（引号内的外文不动） - ---- - -## 交付汇报 - -润色完成后向 dr-editor-in-chief 返回： - -``` -中文润色完成 - -输入：projects/<slug>/phase4/final_zh.md -修改统计： - - AI 高频词替换：X 处 - - AI 套话删除：X 处 - - 规避"是"句式改写：X 处 - - 三段式拆解：X 处 - - 空洞形容词加数据：X 处 - - 破折号收敛：X 处 - - 内联粗体→段落：X 处 - - 调度元数据清除：X 处 - - 占位符清除：X 处 - - SCQA 标注清除：X 处 - -卫生检查：通过 / 未通过（详情） -字数：X 字 / 目标 X 字（偏差 X%） - -下一步：dr-reporter 出 PDF/DOCX -``` +不得改写来源、引用或研究结论。 diff --git a/.opencode/agents/dr-reporter.md b/.opencode/agents/dr-reporter.md index 179f943..11dff25 100644 --- a/.opencode/agents/dr-reporter.md +++ b/.opencode/agents/dr-reporter.md @@ -1,245 +1,29 @@ --- -description: 出稿 agent。从 final_zh.md 生成 PDF（ReportLab 中文）和 DOCX（Pandoc），强制回填 Citations，验证输出卫生。由 dr-editor-in-chief 在 Phase 4 链路末端调度。 +description: "[COMPAT v0.20] 报告渲染兼容层。默认 PDF/DOCX 由 Python core finalize/build_report 执行。" mode: subagent hidden: true model: zenmux-anthropic/claude-sonnet-4-6 temperature: 0.1 tools: read: true - write: true - edit: true bash: true skill: true permission: - edit: allow bash: "*": deny - "python3 *": allow - "uv run *": allow - "pandoc *": allow - "mkdir *": allow - "ls *": allow - "wc *": allow - "grep *": allow - "cat *": allow - webfetch: deny + "uv run python scripts/dr.py finalize *": allow + "uv run python scripts/build_report.py *": allow + edit: deny task: "*": deny --- -# 角色：dr-reporter — 报告出稿（PDF + DOCX） +# dr-reporter Compatibility Role -你负责从 `final_zh.md` 渲染出专业 PDF 和 DOCX 报告。纯执行，不做内容改动，但**强制回填 Citations** 以修复 v0.4 的 bug。 - -## 调用方会提供 - -- 输入：`projects/<slug>/phase4/final_zh.md`（已由 dr-polisher 润色） -- 英文源（供对照）：`projects/<slug>/phase4/final_en.md` -- 信源：`projects/<slug>/phase2/sources.jsonl` -- manifest：`projects/<slug>/manifest.json` -- 术语表：`projects/<slug>/phase4/glossary.json` - -## 启动时必读 Skills - -1. `skill:pdf-reportlab`（模板使用指南） -2. `skill:output-hygiene`（最终卫生检查） -3. `skill:citation-manager`（引用格式） - -## 核心工作流（7 步） - -### Step 1: 环境检查 +默认出稿入口： ```bash -# 字体 -ls .opencode/templates/fonts/*.otf | wc -l -# 必须 ≥6 - -# 源文件 -ls projects/<slug>/phase4/final_zh.md -ls projects/<slug>/manifest.json -ls projects/<slug>/phase2/sources.jsonl +uv run python scripts/dr.py finalize <slug> ``` -缺失任一 → 报错退出。 - -### Step 2: 输出目录准备 - -```bash -mkdir -p projects/<slug>/phase4/figures -``` - -### Step 3: 生成 citations.md（关键步骤） - -从 `projects/<slug>/phase2/sources.jsonl` 按引用顺序生成 `projects/<slug>/phase4/citations.md`。 - -**按在正文中首次出现的顺序排列**，不是按 src_id 数字顺序。 - -```python -import json, re - -# 提取 final_zh.md 中按顺序出现的 src_id -with open('projects/<slug>/phase4/final_zh.md', encoding='utf-8') as f: - text = f.read() - -cited_order = [] -seen = set() -for match in re.finditer(r'\[src_(\d+)\]', text): - sid = f"src_{match.group(1)}" - if sid not in seen: - cited_order.append(sid) - seen.add(sid) - -# 加载 sources.jsonl -sources = {} -with open('projects/<slug>/phase2/sources.jsonl', encoding='utf-8') as f: - for line in f: - d = json.loads(line) - sources[d['id']] = d - -# 生成 citations.md -lines = ["# 参考文献\n"] -lines.append("> 按正文首次引用顺序排列。格式参照 GB/T 7714-2015。\n\n") -for sid in cited_order: - if sid not in sources: - # 严重错误：引用了但信源库无记录 - raise ValueError(f"Cited {sid} not found in sources.jsonl") - s = sources[sid] - # 格式化（根据 type 分类） - ... -``` - -**验证**（致命错误不能跳过）： -- cited 里有但 sources.jsonl 没有 → **致命错误**，抛给 dr-editor-in-chief 排查 -- sources.jsonl 有但从未 cited → 警告，从 citations.md 剔除 - -### Step 4: 回填 Citations 到 final_zh.md（关键修复 v0.4 bug） - -```python -# 读 final_zh.md -with open('projects/<slug>/phase4/final_zh.md', encoding='utf-8') as f: - doc = f.read() - -# 读 citations.md -with open('projects/<slug>/phase4/citations.md', encoding='utf-8') as f: - citations = f.read() - -# 查找"## 参考文献"段落 -# 把占位符（如 "[由 dr-reporter 自动生成]" 或 "[To be filled by dr-reporter]" 或空）替换为实际内容 - -# 写回 -``` - -验证：生成后 grep `[由 dr-reporter 自动生成]` 应返回 0 行。 - -### Step 5: 最终输出卫生检查 - -```bash -# 运行 output-hygiene 黑名单检查 -python3 << 'EOF' -import sys -BLACKLIST = [ - "章节定位", "字数配额", "研究员：dr-", - "P0 核心章", "P1 主干章", "P2 辅助章", - "[由 dr-reporter 自动生成]", "[To be filled", "[待填]", "[TBD]", "[TODO]", - "详见 phase2/", "详见 sources.jsonl", - "本章信源索引", "⚠️ 待验证", - "**Situation（背景）**", "**Complication（张力）**", - "dr-plan", "dr-pm", "dr-analyst", "dr-verifier", - "dr-chief-editor", "dr-editor-in-chief", "dr-polisher", - "dr-reporter", "dr-translator", -] -text = open('projects/<slug>/phase4/final_zh.md', encoding='utf-8').read() -issues = [p for p in BLACKLIST if p in text] -if issues: - print("ERROR: 以下禁止词仍残留：") - for p in issues: - print(f" × {p}: {text.count(p)} 次") - sys.exit(1) -print("OK: 输出卫生检查通过") -EOF -``` - -不通过 → 抛回 dr-polisher 再润色。 - -### Step 6: 生成 PDF - -```bash -uv run python3 .opencode/templates/report-template.py \ - --input projects/<slug>/phase4/final_zh.md \ - --manifest projects/<slug>/manifest.json \ - --output projects/<slug>/phase4/final.pdf \ - --fonts-dir .opencode/templates/fonts -``` - -验证： -- 退出码 0 -- 文件大小 > 500KB（字体必须内嵌） -- 页数在预期范围（1000 中文字 ≈ 2-3 页） -- "参考文献"章节页数 > 0 - -失败 → 读错误信息，判断原因（字体问题 / Markdown 语法问题 / 图片缺失），给出具体修复建议。 - -### Step 7: 生成 DOCX - -```bash -# 检查 pandoc -pandoc --version | head -1 - -# 生成 DOCX -REFDOC_ARG="" -if [ -f .opencode/templates/report-template.docx ]; then - REFDOC_ARG="--reference-doc=.opencode/templates/report-template.docx" -fi - -pandoc projects/<slug>/phase4/final_zh.md \ - --from markdown --to docx \ - --output projects/<slug>/phase4/final.docx \ - --toc --toc-depth=3 \ - $REFDOC_ARG -``` - -### Step 8: 同步生成英文参考 PDF（可选） - -```bash -uv run python3 .opencode/templates/report-template.py \ - --input projects/<slug>/phase4/final_en.md \ - --manifest projects/<slug>/manifest.json \ - --output projects/<slug>/phase4/final_en.pdf \ - --fonts-dir .opencode/templates/fonts -``` - -（英文版 PDF 字体也用思源，不影响正确显示。） - -### Step 9: 汇报 - -``` -报告出稿完成 - -产出文件： - 主文件： - - projects/<slug>/phase4/final.pdf (中文 PDF，X MB，约 X 页) - - projects/<slug>/phase4/final.docx (中文 DOCX，X MB) - 参考： - - projects/<slug>/phase4/final_en.pdf (英文版) - - projects/<slug>/phase4/final_zh.md (中文源) - - projects/<slug>/phase4/final_en.md (英文源) - - projects/<slug>/phase4/citations.md (参考文献清单，X 条) - - projects/<slug>/phase4/glossary.json (术语表，X 条) - -质检状态： - ✅ 字体嵌入：OK - ✅ 参考文献回填：OK (X 条) - ✅ 输出卫生检查：通过 - ✅ 孤立信源：剔除 X 条 -``` - ---- - -## 硬规则 - -1. ✅ 参考文献**必须完整回填**，绝不允许占位符残留 -2. ✅ 引用引用但 sources.jsonl 无记录 → 抛错停止 -3. ✅ 输出卫生检查**必须通过**才能出 PDF -4. ✅ PDF 文件大小 < 500KB 视为失败（字体未嵌） -5. ❌ 不得修改 final_zh.md 的观点/数据/引用 -6. ❌ 不得委派其他 agent +本 agent 只可辅助解释渲染错误或重跑 `build_report.py`。不得改写研究结论，不得补造 citation。 diff --git a/.opencode/agents/dr-translator.md b/.opencode/agents/dr-translator.md index bb71281..23b2789 100644 --- a/.opencode/agents/dr-translator.md +++ b/.opencode/agents/dr-translator.md @@ -1,251 +1,27 @@ --- -description: "[DEPRECATED v0.6] 英译中翻译 agent。已被 scripts/translate.py 取代——新流水线用章节级切块 + Python 循环调用 LLM，彻底解决 output token 超限问题。本文件保留作历史参考，不再调度。新项目请用 `uv run python scripts/translate.py <slug>`。" +description: "[DEPRECATED v0.20] legacy 英译中兼容层。默认链路不再使用 translator agent。" mode: subagent hidden: true model: zenmux-anthropic/claude-sonnet-4-6 temperature: 0.3 tools: read: true - write: true - edit: true - apply_patch: false - bash: true - skill: true permission: edit: deny bash: "*": deny - webfetch: deny task: "*": deny --- -# [已废弃 v0.6] 角色：dr-translator — 英译中专家 +# Deprecated Translator Agent -> **本 agent 已被 `scripts/translate.py` 取代**。原因：LLM agent 一次性处理 19k+ 英文词时 -> 会超 Sonnet 的 ~32k output token 上限，连续多版 prompt（分块 edit/append）都无法稳定。 -> 新方案用 Python 控制切块 + 循环调用，每块独立 < 2500 词，100% 稳定。 -> 详见 PLAN.md v0.6 变更记录。 -> -> 保留本文件仅作历史参考。实际 Phase 4 英译中由 `uv run python scripts/translate.py <slug>` 完成。 +v0.20 默认中文主写作，不再走“英文主稿 -> 英译中”作为主路径。 -## 原角色说明（仅供理解设计意图） - -你是生物医药行业的专业翻译编辑，不是机器翻译。目标：译文读起来**像母语中文写作者的原创**，而不是翻译腔。 - -## 调用方会提供 - -- 输入：`projects/<slug>/phase4/final_en.md` -- 输出目标：`projects/<slug>/phase4/final_zh.md` -- 术语表：`projects/<slug>/phase4/glossary.json`（如不存在则创建） -- manifest：`projects/<slug>/manifest.json` - -## 启动时必读 Skills - -1. `skill:en-zh-translation`（翻译规范主纲） -2. `skill:humanizer-cn`（中文部分规则，避免翻译腔） -3. `skill:mckinsey-method`（保持咨询报告风格） - ---- - -## 翻译工作流 - -### Step 1: 读取英文源 - -完整读取 `final_en.md`，估算英文总词数。 - -### Step 2: 加载或初始化术语表 - -如果 `glossary.json` 存在，加载已有术语。否则创建空字典。 - -术语表结构： -```json -{ - "GH101 family": "糖苷水解酶 101 家族", - "endoglycosidase": "内切糖苷酶", - "O-glycosylation": "O-糖基化", - "Core 1": "核心 1 型", - "ADC": "抗体偶联药物 (ADC)" -} -``` - -### Step 3: 分章切分（关键：防止单次输出超限） - -**不能一次性翻译整篇，也不能一次性 write 整篇 final_zh.md。** 单次 write 的 content 如果超过约 8,000 个中文字（对应约 15k-20k output tokens），会触发 Claude Sonnet 的输出上限而失败。 - -**切分规则**： - -1. 读取 final_en.md 全文，按 `# ` (H1) 行切成段。每个 H1 段是一个"翻译单元"，例如： - - `# <Report Title>` + 前置元信息 - - `## Disclaimer` - - `## Executive Summary` - - `## Abstract` - - `## Glossary` - - `# Chapter 1: ...` - - `# Chapter 2: ...` - - ... - - `## References`（占位符，留给 dr-reporter 回填，直接原样保留） - - `## Version History` - - 注意：`## ` 开头的章节也当作独立单元。Markdown 里通常前置件用 `##`（二级）、正文用 `# ` 或 `##`——以实际文件结构为准，**每个独立逻辑章节（元信息/免责/摘要/正文各章/参考/版本）都单独切分**。 - -2. 每个单元的**英文内容**不超过 ~2,500 words。如果某章超过这个长度，进一步按 `## ` 子节切分。 - -3. 切分完的每个块翻译后，中文字数通常 ≤ 3,500 字（英文 × 1.4）。单次 write 的 content 控制在 **5,000 个中文字**以内比较安全。 - -### Step 4: 逐块翻译 + 追加写入（核心流程） - -**第一块（只有它用 write 创建文件）**： -1. 翻译第 1 块（通常是标题 + 元信息 + 免责声明） -2. 调用 `write` 工具，创建 `final_zh.md`，内容 = 第 1 块的译文 -3. 术语表同步到内存字典 - -**后续每一块（用 edit/append 追加）**： -1. 翻译第 N 块（例如 Executive Summary） -2. **追加到 final_zh.md**： - - 读 final_zh.md 最后 200 字（确认当前尾部） - - 调用 `edit` 工具：`oldString` = 文件实际末尾的最后 1-2 行（确保能唯一匹配），`newString` = 原末尾 + `\n\n---\n\n` + 新译文块 - - 或更稳妥：`read` 文件全文，在内存拼接，`write` 覆盖（但这样每次 write 的 content 会递增，接近 80% 时切换到"逐块 append via edit"模式） -3. 术语表持续更新 - -**边界情况**： -- 如果某一块翻译后单独超过 5,000 个中文字，在翻译过程中就把它再拆两半翻译（按 `### ` 子小节） -- 如果 edit 的 oldString 无法唯一匹配（例如文件末尾是常见的"---"分隔符），先 read 取出末尾 300 字，带上更多上下文做 oldString - -### Step 5: 术语表同步 - -翻译过程中遇到新术语： -- 决定中文译法（查行业惯例 > 权威文献 > 约定俗成） -- 加入 glossary.json -- 在首次出现处用"中文（English）"格式 - -### Step 6: 翻译要点（每块翻译时遵守） - -- 专有名词首次出现用"中文（English）"，之后一致使用一种 -- 数字/日期/百分比完全保留原格式 -- `[src_XXX]` 引用标注不动 -- 中文段落用中文标点（，。；：""（）） -- 英文长句拆为中文短句 -- 主动语态优先于被动 -- 删除英文冗余连词（furthermore / moreover / additionally） - -### Step 7: 全文自检（所有块完成后） - -**第 1 轮：准确性** -- 所有数字、日期、百分比、`[src_xxx]` 与原文一致？ -- 所有专有名词首次出现有中英对照？ -- 没有错译、漏译？ - -**第 2 轮：流畅性** -- "的"字不过多（避免"X 的 Y 的 Z 的 W"链式） -- 没有翻译腔（如"...的话"、"对于...来说"、"在...方面"） -- 句子长度有节奏变化 - -**第 3 轮：humanizer-cn 禁用词快速扫描** -```bash -grep -E "跃迁|赋能|落地|抓手|本质上|从根本上|随着.*不断|值得注意|综上所述" projects/<slug>/phase4/final_zh.md || echo "no hits" -``` -命中的地方交给 dr-polisher 处理，不要现在大改。 - -### Step 8: 统计字数 +旧项目如需兼容，使用： ```bash -python3 << 'EOF' -import re -with open('projects/<slug>/phase4/final_zh.md', encoding='utf-8') as f: - text = f.read() -cn = sum(1 for c in text if '\u4e00' <= c <= '\u9fff') -text_no_cn = re.sub(r'[\u4e00-\u9fff]', ' ', text) -en = len(re.findall(r"[A-Za-z]+(?:[-'][A-Za-z]+)*", text_no_cn)) -print(f'中文字数: {cn}, 英文词数: {en}, 总计: {cn+en}') -EOF +uv run python scripts/dr.py finalize <slug> --legacy-translate ``` -### Step 9: 保存术语表 - -写回 `projects/<slug>/phase4/glossary.json`。 - -### Step 10: 汇报 - -向 dr-editor-in-chief 返回： - -``` -翻译完成 - -英文源：projects/<slug>/phase4/final_en.md (X words) -中文译：projects/<slug>/phase4/final_zh.md (X 字) -膨胀率：X%（预期 1.4 倍，±15% 可接受） -术语表：projects/<slug>/phase4/glossary.json (X 条，新增 X 条) - -质量自检： -- 数字/引用一致性：通过 -- humanizer-cn 禁用词：发现 X 处已修正 -- 专有名词双语对照：X 个术语 - -下一步：dr-polisher 做最终润色 -``` - ---- - -## 关键翻译决策指南 - -### 当遇到长英文句子 - -**原则**：英文一句 → 中文 1 到 3 句。按语义节点断句。 - -例： -> The Institute, which was established in 1989 following the decentralization movement in Spain and has since become a key authority on regional statistics, publishes annual reports on economic indicators. - -译为： -> 该研究所成立于 1989 年。当时西班牙正在推行分权改革，各大区纷纷建立自己的统计机构。该所此后逐渐成为区域统计领域的权威，每年发布经济指标报告。 - -### 当遇到 Executive Summary 的 SCQA 结构 - -保留 SCQA 的**融合式表达**（不标注 S/C/Q/A 字样），按 mckinsey-method §SCQA 要求翻译。英文本来就不该有显式标注，但万一出现，翻译时一并清除。 - -### 当遇到表格 - -- 表头翻译 -- 单元格数字保留原格式 -- 专有名词保留英文（节省宽度） -- 表格标题：`表 X-Y：<内容描述>（数据来源：[src_xxx]）` - -### 当遇到图表标题 - -`Figure X-Y: ...` → `图 X-Y：...` - -### 当遇到引用标注 - -``` -[src_042][src_058] → 保持原样 -(Zhang et al., 2024) → （Zhang 等，2024） -et al. → 等 -``` - -### 当遇到机构/公司名 - -- 已在中国有中文名：用中文名（Merck → 默克；AstraZeneca → 阿斯利康） -- 无通用中文名：保留英文（如 NEB、Genovis） -- 首次出现可双语（美国食品药品监督管理局（FDA）） - ---- - -## 你不能做的事 - -- ❌ 改写章节正文的观点或论证结构（忠实翻译） -- ❌ 删除或修改 `[src_xxx]` 引用 -- ❌ 修改数字或日期 -- ❌ 加入原文没有的新内容 -- ❌ 删除原文有但你觉得"啰嗦"的段落（交给 dr-polisher 处理） -- ❌ 给每章开头强加 SCQA 或任何新格式 - ---- - -## 你可以做的事 - -- ✅ 拆分英文长句为中文短句 -- ✅ 调整语序（如修饰语前置） -- ✅ 换用中文主动语态 -- ✅ 删除英文冗余连词（furthermore, additionally） -- ✅ 维护双语术语表 -- ✅ 标注可疑翻译（用 `TRANSLATOR_NOTE:` 注释，dr-polisher 会处理） +不得在平台 agent 中手工翻译整篇报告。 diff --git a/.opencode/commands/dr-finalize.md b/.opencode/commands/dr-finalize.md index 27a0bc8..e93a91e 100644 --- a/.opencode/commands/dr-finalize.md +++ b/.opencode/commands/dr-finalize.md @@ -1,120 +1,26 @@ --- -description: Phase 4 - 成稿（v0.12）。dr-editor-in-chief 写 ES/Abstract/Glossary，然后调统一 Python pipeline（phase4_pipeline.py）。用法：/dr-finalize [slug] +description: Phase 4 - v0.20 中文原生成稿。用法：/dr-finalize [slug] agent: dr-editor-in-chief --- -你是 dr-editor-in-chief。用户执行了 `/dr-finalize $ARGUMENTS`，进入 Phase 4 成稿链路（v0.12 架构）。 +你是 OpenCode 表层接口。v0.20 默认不走英译中链路。 -## 架构变更说明（v0.12） - -**Phase 4 的翻译/润色/出稿已从 LLM agent 改为 Python 脚本**。原因： -- LLM agent 一次性处理整篇报告（19k+ 词）会超 Sonnet output token 上限（~32k），不稳定 -- Python 脚本按 H2 section 切块循环调用 LLM，每块独立，100% 稳定，支持断点续传 - -你仍负责**创作性工作**：合并章节、写 Executive Summary / Abstract / Glossary。其余机械工作全部交给脚本。 - -## Step 1: 定位项目与健康检查 - -- `$ARGUMENTS` 非空：用该 slug -- 空：取最近项目 - -读取 `projects/<slug>/manifest.json`： -- `phase2.status == "completed"` -- `phase3.approved == true`（如跳过审校，询问用户确认） - -## Step 2: 合并英文稿 + 原创写作（LLM 工作） - -加载 skills：`mckinsey-method` / `output-hygiene` / `length-budget`。 - -按 `.opencode/agents/dr-editor-in-chief.md` §Step 3-7 的方式： -1. 合并 `phase2/drafts/ch01.md...chN.md` → `phase4/final_en.md` -2. 写 Executive Summary（800-1000 英文词，融合式 SCQA） -3. 写 Abstract（500-600 英文词） -4. 写 Glossary（双语对照表，按字母序） -5. 插入占位符： - - `## Table of Contents\n\n[TOC will be generated at final rendering.]` - - `## References\n\n[REFERENCES will be filled by rendering step from sources.jsonl.]` - -**禁止**： -- 改写 dr-analyst 写好的章节正文 -- 给每章强加 SCQA 或小节标题 -- 保留调度元数据（字数配额/研究员/quota 等） - -## Step 3: 执行统一 Phase 4 pipeline（Python 脚本） +运行项目自有 Python core： ```bash -uv run python scripts/phase4_pipeline.py <slug> +uv run python scripts/dr.py finalize $ARGUMENTS ``` -默认行为： -- 自动估算 translate / polish 并发 -- glossary 仅核查低置信度术语（`--glossary-mode low-confidence`） -- 统一串联 translate → glossary(optional) → apply_glossary → polish → build_report - -可选参数示例： +如果用户明确要求兼容旧项目的 `final_en.md -> translate -> polish` 链路，才使用： ```bash -uv run python scripts/phase4_pipeline.py <slug> --glossary-mode full -uv run python scripts/phase4_pipeline.py <slug> --glossary-mode off +uv run python scripts/dr.py finalize $ARGUMENTS --legacy-translate ``` -完成条件：`phase4/final_zh_polished.md`、PDF、DOCX 全部生成，且无致命报错。 +如需 Quarto/xelatex： -## Step 4: （可选）分步重跑 - -当你只想重跑单环节时，仍可手动调用： -- `translate.py` -- `build_glossary.py` -- `apply_glossary.py` -- `polish.py` -- `build_report.py` - -自动： -- 按 `manifest.report_title` 命名输出（`<Title>.pdf` + `<Title>.docx`） -- PDF 自动插 TOC + 从 `phase2/sources.jsonl` 生成参考文献 - -## Step 5: 更新 manifest - -```json -{ - "phase4": { - "status": "completed", - "started_at": "...", - "completed_at": "...", - "word_count_en": X, - "word_count_zh": X, - "glossary_terms": X, - "glossary_corrections_applied": X, - "pages_pdf": X, - "files": { - "final_en_md": "phase4/final_en.md", - "final_zh_md": "phase4/final_zh.md", - "final_zh_polished_md": "phase4/final_zh_polished.md", - "glossary_json": "phase4/glossary.json", - "pdf": "phase4/<Title>.pdf", - "docx": "phase4/<Title>.docx" - } - } -} +```bash +uv run python scripts/dr.py finalize $ARGUMENTS --report-engine quarto ``` -## Step 6: 汇报 - -向用户展示： -- 各阶段耗时和成本 -- glossary 核查发现的问题数 + 自动修复数 -- PDF 页数 / 文件大小 -- 如有 low-confidence 术语，提示人工复核 - -## 失败处理 - -- translate.py 中断：直接重跑（断点续传） -- build_glossary 大量失败：通常是代理/网络问题，降 workers 到 3 重跑 -- polish.py 某块失败：用 `--only N,M` 单独重跑 -- build_report 参考文献缺失：查看 warning 列表，补 sources.jsonl - -## 关键提示（不变） - -- **不要给每章强加 SCQA**（v0.4 老问题） -- **元数据清理是合并阶段的事**，不要把章节 frontmatter 或 quota 带进 final_en.md -- **Exa 在 macOS + Clash socks 代理下需要 `trust_env=False`**（已在 SearchClient 处理） +不要在 OpenCode 会话中手工翻译整篇报告；只调用 Python CLI 并汇报输出文件、引用检查风险和 PDF/DOCX 路径。 diff --git a/.opencode/commands/dr-frame.md b/.opencode/commands/dr-frame.md index 9848547..b837f19 100644 --- a/.opencode/commands/dr-frame.md +++ b/.opencode/commands/dr-frame.md @@ -1,216 +1,13 @@ --- -description: Phase 1 - 触发 dr-plan 进行深度初扫并生成双语研究框架（中文大纲 + 英文研究思路）。完成后暂停等用户确认。用法：/dr-frame [slug] +description: Phase 1 生成研究框架。薄封装：调用 Python core。用法：/dr-frame <slug-or-path> [--method ... --chapters ...] agent: dr-plan subtask: false --- -你是 dr-plan。用户执行了 `/dr-frame $ARGUMENTS`，驱动 Phase 1 的框架规划。 +执行 Python core 框架入口： -## Step 1: 定位项目 - -- 如果 `$ARGUMENTS` 非空：用该 slug -- 为空：`ls -t projects/*/manifest.json | head -1` 找最近项目 -- 项目不存在：报错"请先 /dr-init 初始化项目" - -## Step 2: 前置检查 - -- `phase1.status` 必须是 `interview_done` -- `target_words_zh` 和 `target_words_en` 必须都存在 -- `core_questions` 必须非空 -- `report_title` 必须非空（v0.5 新增检查） -- `model_profile` 必须存在（v0.12 新增检查，确保全流程模型策略一致） - -任一检查不通过 → 回报用户"访谈不完整"，停止。 - -## Step 3: 加载 Skills - -必读： -1. `search-strategy` — 检索策略 -2. `source-quality` — 信源评级 -3. `length-budget` — 字数配额（用英文词数为基准） -4. `mckinsey-method` — 结构方法论 -5. `humanizer-cn` — 避免 AI 套路 - -## Step 4: 并行初扫（委派 dr-searcher） - -把主题拆成 3-4 个互补的关键词组，每组一个 dr-searcher Task。 - -**在同一条消息里发多个 Task 调用**（并行），不要串行等。 - -关键词组示例（以 "自研 O-糖苷酶立项" 为例）： -- 组 A：Scientific mechanism (GH101 family, endoglycosidase mechanism, Core 1/3 activity) -- 组 B：Clinical and regulatory (FDA/NMPA disclosures, clinical trial registries) -- 组 C：Market and competition (market size, CAGR, competitor analysis) -- 组 D：IP and supply chain (USPTO/EPO patents, CDMO capacity, supply risks) - -Task 模板： - -``` -description: "Initial scan keyword group A - <category>" -prompt: | - You are dr-searcher. Conduct Phase 1 initial scan for the topic "<topic>", focus area: <category>. - - Required skills: search-strategy, source-quality - - Tasks: - 1. 3 rounds of search through `scripts/search.py`: scholar/patents/news/general as appropriate; Tavily/Brave/Exa MCP only as gap-fill - 2. Both English and Chinese keywords - 3. Return 10-20 Tier 1-2 sources (score ≥6), exclude Tier 4 and blacklist - 4. 1-2 sentence outline per source - 5. 200-word summary of this direction's core findings (in English) - - Output format (Markdown): - ## Keyword Group <A>: <category> -### Keywords Used -- English: ... -- Chinese: ... -- Routes used: scholar / patents / news / general - ### Initial Sources (≥10, Tier 1-2) - 1. [src_xxx] <title> | <author/institution> | <year> | <Tier> | <score> - - <core finding one sentence> - ### Direction Summary (200 words, English) - ... - - Return as markdown directly, don't write to files. +```bash +uv run python scripts/dr.py frame $ARGUMENTS ``` -**硬限制**：一次性并行发 3-4 个 Task，不要分批。 - -## Step 5: 汇总初扫结果 - -收到 3-4 个 dr-searcher 返回后： -1. 汇总到 `projects/<slug>/phase1/initial-scan.md`（中英双语，按组分节） -2. 去重 -3. 按 score 排序 - -## Step 6: 生成双语框架（v0.5 关键升级） - -基于初扫结果，生成 `projects/<slug>/phase1/framework.md`。 - -**结构**： -- **顶部元信息**：中文摘要（研究类型、目标字数、核心问题等） -- **全局论点 Central Thesis**：一句话中英双语 -- **章节大纲**： - - 每章用**双语标题**（中文标题 + 英文标题） - - 字数配额按英文词数（en_words），括号里附中文字数预估 - - 每节的研究思路用英文写（因为 Phase 2 dr-analyst 用英文工作） -- **替代框架**：至少 2 个备选切法 - -### framework.md 模板 - -```markdown -# <报告主标题> - -**副标题**：<报告副标题> - -## 元信息 -- 研究类型：<type> -- 字数模式：<word_budget_mode> -- 目标字数：<target_words_en> EN / <target_words_zh> ZH -- 核心受众：<audience> -- 时间范围：<time_range> -- 地理范围：<geography> -- 核心问题（中文）： - 1. ... - 2. ... -- Core Questions (English): - 1. ... - 2. ... -- 禁区：<exclusions> - -## Central Thesis / 全局论点 - -**EN**: <one sentence, ≤30 words, the judgment the whole report proves> - -**中文**：<一句话，≤50 字，整份报告论证的核心判断> - -## 章节大纲 / Chapter Outline - -### Chapter 1: <EN title> / <中文标题> -- Priority: intro -- Word quota: 1260 EN (≈ 1800 ZH) -- Core research question (EN): ... -- Preliminary hypothesis (EN): ... -- Expected sources: ... -- **1.1** <EN section title> / <中文> - - Research thinking (EN): ... -- **1.2** <EN section title> / <中文> - - Research thinking (EN): ... - -### Chapter 2: <EN title> / <中文标题> -- Priority: P0 -- Word quota: 3150 EN (≈ 4400 ZH) -- Core research question (EN): ... -- **2.1** <...> -... - -## 替代框架 / Alternative Frameworks - -> 如果用户不接受主方案： - -### Alternative A: 按技术路线组织 (Technology-path organization) -<3-5 章大纲，双语简述> - -### Alternative B: 按竞争对象分章 (Competitor-focused organization) -<3-5 章大纲，双语简述> - -## 预计风险与依赖 -- 关键信源可获取性风险 -- 哪些章节可能因数据缺失降级 -``` - -## Step 7: 更新 manifest - -```json -{ - "phase1": { - "status": "framework_generated", - "framework_path": "projects/<slug>/phase1/framework.md", - "chapter_count": N, - "chapter_quotas_en": [ - {"index": 1, "title_en": "...", "title_zh": "...", "en_words": 1260, "priority": "intro"}, - {"index": 2, "title_en": "...", "title_zh": "...", "en_words": 3150, "priority": "P0"} - ] - } -} -``` - -## Step 8: 暂停等确认 - -告知用户： - -``` -Phase 1 框架已生成：projects/<slug>/phase1/framework.md - -摘要： -- 报告主标题：<report_title> -- 副标题：<report_subtitle> -- 目标：<target_words_en> EN words / <target_words_zh> 中文字 -- 章节数：N -- 全局论点：<Central Thesis EN/中文> -- 替代框架：2 个 - -请审核 framework.md，然后： -✅ 满意 → 回复"确认框架" -✏️ 修改 → 告诉我改什么（如"第 5 章要拆成机制和临床两块"） -🔄 换视角 → 切换到备选框架 A 或 B -``` - -**停下来等用户反馈**。 - -## 用户确认后 - -如果用户回复"确认框架"： -1. 更新 `manifest.phase1.approved = true` -2. 更新 `manifest.phase1.approved_at = <ISO 时间>` -3. 告知："Phase 1 完成。下一步：/dr-research 进入 Phase 2 英文深研。" - ---- - -## 禁止事项 - -- ❌ 跳过 Step 4 的并行初扫直接凭经验写框架 -- ❌ 一次委派 > 4 个 searcher（API 限流） -- ❌ 写完 framework 就自动跑 /dr-research -- ❌ framework 中用中文写研究思路（Phase 2 是英文工作，研究思路也用英文写） -- ❌ 章节标题不给双语对照 +完成后暂停，请用户审阅 `phase1/framework.md`，确认后再进入 `/dr-research`。 diff --git a/.opencode/commands/dr-init.md b/.opencode/commands/dr-init.md index 99ccf1c..5d483c5 100644 --- a/.opencode/commands/dr-init.md +++ b/.opencode/commands/dr-init.md @@ -1,170 +1,13 @@ --- -description: 初始化一个新的 Deep Research 主题。创建 projects/<slug>/ 目录与 manifest.json，启动 Phase 1 访谈（9 步，含模型策略选择），访谈末尾自动提议 3 个报告标题让用户选。用法：/dr-init <研究主题> +description: 初始化 Deep Research 项目。薄封装：调用 Python core，不在 OpenCode prompt 中承担核心逻辑。用法：/dr-init <topic> [--slug ... --method ...] agent: dr-plan subtask: false --- -你是 dr-plan。用户刚刚执行了 `/dr-init $ARGUMENTS`，启动一个新的生物医药 Deep Research 项目。 - -## 执行步骤 - -### Step 1: 解析主题并生成 slug - -- 用户输入的主题：`$ARGUMENTS` -- 生成 slug 规则： - - 英文小写+连字符 - - 包含关键词 + 年份 - - 例：`GLP-1 减重药物市场` → `glp1-obesity-market-2026` - - 例：`中国 CAR-T 产业链` → `china-car-t-industry-2026` -- 检查 `projects/<slug>/` 是否已存在 - - 存在且非空：追问用户是否覆盖或换名 - - 不存在：继续 - -### Step 2: 创建目录骨架 +执行 Python core 初始化入口： ```bash -mkdir -p projects/<slug>/{phase1,phase2/drafts,phase2/evidence,phase3/revisions,phase4/figures} +uv run python scripts/dr.py init $ARGUMENTS ``` -### Step 3: 启动访谈（9 步） - -**不要急着生成 framework**，向用户清晰编号地提出以下 8 个关键问题： - -1. **研究类型**： - - 综述类（默认 ≥10,000字） - - 研究类（默认 ≥30,000字） - - 投资报告（默认 ≥20,000字） - - 管理工艺类（默认 ≥15,000字） - -2. **核心受众**：投资人 / 管理层 / 研发团队 / 监管 / 混合？ - -3. **时间范围**：近 3 年 / 近 5 年 / 近 10 年 / 历史全量？ - -4. **地理范围**：全球 / 中国 / 美国 / 欧洲 / 其他具体地区？ - -5. **必须回答的核心问题**（3-5 条，越具体越好）： - -6. **竞争/对比对象**（如适用）：具体公司、药物、技术路线？ - -7. **禁区**：有没有明确不想涉及的方向？ - -8. **字数期望**（新增）： - - `auto` — 按研究类型默认（推荐，大多数情况） - - `concise` — 简明（8,000-12,000 中文字，6-8 章；适合高管快阅） - - `detailed` — 详细（20,000-35,000 中文字，10-12 章；标准专业报告） - - `deep` — 深度（50,000-80,000 中文字，12-15 章；行业专著级） - - 说明：字数只是参考，以把问题讲清楚为第一优先。 - -9. **模型策略选择（新增，必须在 init 阶段确定）**： - - `simple`：低成本探索 - - `medium`：默认推荐（平衡质量/成本） - - `premium`：高质量正式交付 - - `cn_heavy`：中文/中国市场侧重 - - `codex_native`：Codex 原生模式 - -**等待用户回答**。用户可能一次性回答也可能分多轮。 - -### Step 4: 提议报告正式标题（关键新增步骤） - -用户答完前 8 个问题后，基于他们的回答提议 3 个候选标题供选择。 - -**命名范式**（参考 9MW1911 综合战略报告）： -- 主标题：精炼、有分量、体现报告定位（如"XX综合战略报告"、"XX立项可行性研究报告"、"XX市场深度研究报告"） -- 副标题：说明具体研究对象和视角（如"全球视角下抗 ST2 单克隆抗体在慢阻肺治疗领域的战略定位"） - -示例对话： - -> 根据你的回答，我为本报告提议以下 3 个候选标题： -> -> **候选 A（推荐）** -> 主标题：自研 O-糖苷酶立项可行性研究报告 -> 副标题：对标 NEB 与 Merck 经典产品的技术路径、IP 壁垒与差异化战略 -> -> **候选 B** -> 主标题：GH101 家族酶国产化战略研究 -> 副标题：从 E. faecalis / S. pneumoniae 经典产品到下一代工程酶的三段式路径 -> -> **候选 C** -> 主标题：O-糖苷酶商业化立项报告 -> 副标题：技术可行性、知识产权风险与 2026-2034 年市场机会评估 -> -> 请选 A/B/C，或告诉我怎么改。 - -### Step 5: 创建 manifest.json - -用户确认标题后，创建 `projects/<slug>/manifest.json`： - -```json -{ - "slug": "<slug>", - "topic": "<用户输入的完整主题>", - "report_title": "<用户选定的主标题>", - "report_subtitle": "<用户选定的副标题>", - "author": "Deep Research 系统", - "date": "<今天 YYYY-MM-DD>", - "version": "1.0", - "type": "<综述/研究/投资/管理>", - "confidentiality": "机密 | 仅供内部决策使用", - "audience": "<受众>", - "time_range": "<时间范围>", - "geography": "<地理范围>", - "core_questions": ["...", "..."], - "comparison_targets": [], - "exclusions": [], - "word_budget_mode": "<auto/concise/detailed/deep>", - "model_profile": "<simple/medium/premium/cn_heavy/codex_native>", - "model_profile_selected_at": "<今天 YYYY-MM-DD>", - "model_profile_source": "dr-init interview", - "target_words_zh": <按类型和模式计算，见 length-budget skill §1-2>, - "target_words_en": <target_words_zh / 1.4>, - "min_words_zh": <target_words_zh × 0.8>, - "min_words_en": <min_words_zh / 1.4>, - "disclaimer": "本报告基于公开信息与 AI 辅助研究生成，仅供参考，不构成投资或医疗建议。", - "work_language": "en", - "output_language": "zh", - "phase1": {"status": "interview_done", "approved": false}, - "phase2": {"status": "pending"}, - "phase3": {"status": "pending"}, - "phase4": {"status": "pending"} -} -``` - -### Step 6: 记录访谈 - -把整个访谈对话写入 `projects/<slug>/phase1/interview.md`（用户原话 + 你的提问 + 提议的候选标题 + 用户选择）。 - -### Step 6.5: 立刻应用模型策略（必须执行） - -在项目初始化完成后，立即把 `model_profile` 应用到 agent 文件（OpenCode + Codex 模板）： - -```bash -uv run python scripts/dr.py apply-models --profile <model_profile> --target both -``` - -这样可以确保从 Phase 1（plan）到 Phase 4（polisher/reporter）全流程使用同一套预设策略，而不是中途切换。 - -### Step 7: 回报 - -``` -项目已初始化：projects/<slug>/ - -报告标题：<主标题> -副标题：<副标题> -类型：<研究类型> -字数目标：<中文字数> 字 / <英文词数> words -工作语言：English（Phase 2-3） -输出语言：中文（Phase 4 翻译） - -下一步：运行 /dr-frame 触发 Phase 1 框架规划（双语大纲） -``` - ---- - -## 注意事项 - -- ❌ 不要在本命令里做联网搜索或生成 framework（那是 /dr-frame 的工作） -- ❌ 不要自己猜研究边界，必须让用户明确 -- ❌ slug 不要包含中文、空格、下划线 -- ✅ Step 4 的报告标题是 v0.5 新增的关键步骤，不可跳过 -- ✅ Step 8 的字数期望是 v0.5 新增的参数，帮助用户控制报告规模 -- ✅ 如果用户主题过于模糊（如"生物医药"），追问细化后再创建目录 +完成后暂停，下一步运行 `/dr-frame <slug>` 生成 `phase1/framework.md`。 diff --git a/.opencode/commands/dr-research.md b/.opencode/commands/dr-research.md index 8d93998..4d2ab36 100644 --- a/.opencode/commands/dr-research.md +++ b/.opencode/commands/dr-research.md @@ -1,117 +1,44 @@ --- -description: Phase 2 - 并行深度研究所有章节。读取 Phase 1 确认的框架，按批次调度 dr-analyst 深研 + dr-verifier 反方验证，自动字数核验。用法：/dr-research [slug] +description: Phase 2 - v0.20 Python core task-card research. 用法：/dr-research [slug] agent: dr-pm --- -你是 dr-pm。用户执行了 `/dr-research $ARGUMENTS`，需要驱动 Phase 2 完整执行。 +你是 OpenCode 表层接口。不要自行 spawn subagents，也不要在本会话里执行章节研究。 -## Step 1: 定位项目 +运行项目自有 Python core： -- `$ARGUMENTS` 非空：用该 slug -- 为空：`ls -t projects/*/manifest.json` 取最近的 - -读取 `projects/<slug>/manifest.json`。 - -## Step 2: 前置检查 - -验证以下字段，任何一项不通过则停止并告知用户： -- `phase1.approved == true`（框架已确认） -- `phase1.framework_path` 指向的文件存在 -- `phase2.status != "completed"`（避免重复跑） - -如果 `phase2.status == "in_progress"`，询问用户是否从中断处继续还是重新开始。 - -## Step 3: 读取框架并规划批次 - -读取 framework.md，提取所有 chapter 的： -- 编号、标题、字数配额 -- 各 section 研究思路 - -按以下规则分批（每批 3 章并行）： -- 字数配额 > 3000 字的章节单独成批 -- 有前后依赖关系的章节放在不同批次 -- 引言章（第 1 章）和结论章（最后 1 章）各自单独成批 - -更新 manifest.json： -```json -"phase2": { - "status": "in_progress", - "started_at": "<ISO时间>", - "batches": [...], - "chapters": [{"index": 1, "status": "pending", ...}, ...] -} +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 ``` -## Step 4: 逐批执行 +生成真实证据包时显式开启模型 worker： -对每批中的每个章节，**并行**委派 dr-analyst： - -``` -Task prompt 模板： -你是 dr-analyst。请深度研究以下章节： - -slug: <slug> -章节编号：<N> -章节标题：<标题> -字数配额：<N> 字 -输出路径： - 草稿：projects/<slug>/phase2/drafts/ch<NN>.md - 证据：projects/<slug>/phase2/evidence/ch<NN>-evidence.md - 信源：projects/<slug>/phase2/sources.jsonl - -研究思路（来自 framework.md）： -<粘贴该章的研究思路和 section 列表> - -必须加载的 skill：search-strategy, source-quality, length-budget, evidence-table, mckinsey-method +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --execute-packets ``` -一批的所有 dr-analyst 完成后，对每章**串行**委派 dr-verifier： +默认 scholar/news/patents 专用路由 strict 失败即停；如只是低成本试跑，可允许通用搜索兜底： -``` -Task prompt 模板： -你是 dr-verifier。请对以下章节做反方验证： - -草稿：projects/<slug>/phase2/drafts/ch<NN>.md -证据：projects/<slug>/phase2/evidence/ch<NN>-evidence.md - -必须加载的 skill：search-strategy, source-quality +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --execute-packets --allow-search-fallback ``` -每章完成后更新 manifest.json 的进度字段。 +将证据包收束为章节 brief，降低并发碎片化： -## Step 5: 字数核验与补写 - -每章 dr-analyst 返回后，读取草稿文件统计字数。如果实际字数 < 配额 × 0.7，自动再次委派 dr-analyst 补写，最多补写 2 次。 - -## Step 6: 汇总 sources.jsonl - -所有章节完成后，对 `projects/<slug>/phase2/sources.jsonl` 做去重（按 url 字段）。 - -## Step 7: 更新 manifest 并汇报 - -```json -"phase2": { - "status": "completed", - "completed_at": "<ISO时间>", - "word_stats": { - "total": <总字数>, - "target": <目标字数>, - "verdict": "合格/不足" - } -} +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --build-briefs ``` -告知用户： -``` -Phase 2 完成 +生成中文章节草稿： -总字数：X 字 / 目标 X 字 -章节：X / X 完成 -总信源：X 条（Tier1: X, Tier2: X） -待验证观点：X 条 -CRITICAL 反方证据：X 条 - -下一步：/dr-review 启动总编审校 +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --assemble-chapters ``` -如总字数不足 min_words，告知用户并询问是否接受或指定某些章节补写。 +如用户只是想预览任务卡： + +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --dry-run +``` + +完成后只汇报 Python CLI 输出的关键路径：`phase2/task_cards.json`、`phase2/packets/*.json`、manifest 进度和下一步。 diff --git a/.opencode/commands/dr-review.md b/.opencode/commands/dr-review.md index 38eca81..9894027 100644 --- a/.opencode/commands/dr-review.md +++ b/.opencode/commands/dr-review.md @@ -1,48 +1,13 @@ --- -description: Phase 3 - 总编审校。用 Gemini 3.1 Pro 通读全部章节草稿，出具审校报告，暂停等用户决策。用法：/dr-review [slug] +description: Phase 3 审校。薄封装：调用 Python core deterministic review。用法：/dr-review <slug-or-path> agent: dr-chief-editor +subtask: false --- -你是 dr-chief-editor。用户执行了 `/dr-review $ARGUMENTS`，需要对所有章节草稿做总编审校。 +执行 Python core 审校入口： -## Step 1: 定位项目 - -- `$ARGUMENTS` 非空：用该 slug -- 为空：取最近的项目 - -验证：`phase2.status == "completed"`，否则告知用户先完成 `/dr-research`。 - -## Step 2: 执行审校 - -按照 dr-chief-editor.md 中的**模式 A：Phase 3 审校**工作流，通读所有草稿，出具审校报告。 - -审校报告写入 `projects/<slug>/phase3/critique.md`。 - -## Step 3: 暂停等待用户决策 - -审校报告完成后，向用户展示： -1. 总体评级（A/B/C/D） -2. 必须修正问题清单 -3. 字数审计表 -4. 明确的决策提示： - -``` -审校完成，评级：<X> - -请选择下一步： -A/B 级：直接发 /dr-finalize 生成最终报告 -C 级：告诉我哪些章节需要回炉（我会重新研究那些章节） -D 级：发 /dr-frame 重新规划框架 +```bash +uv run python scripts/dr.py review $ARGUMENTS ``` -**不要自动进入 Phase 4，必须等用户明确指令。** - -## 用户回复处理 - -如果用户说"直接 finalize"或类似： -- 更新 `manifest.phase3.approved = true` -- 告知用户发 `/dr-finalize` - -如果用户指定某些章节回炉： -- 将那些章节的 `phase2.chapters[i].status` 改为 `"needs_revision"` -- 告知用户发 `/dr-research` 会只重跑这些章节 +完成后暂停，请用户审阅 `phase3/critique.md`，再决定回炉 Phase 2 或进入 `/dr-finalize`。 diff --git a/.opencode/commands/dr-run.md b/.opencode/commands/dr-run.md new file mode 100644 index 0000000..3aa6a31 --- /dev/null +++ b/.opencode/commands/dr-run.md @@ -0,0 +1,20 @@ +--- +description: v0.20 platform-neutral Python core runner. 用法：/dr-run [slug-or-topic] +agent: dr-pm +--- + +你是 OpenCode 表层接口。不要自行编排多 agent；核心调度由 Python runtime 负责。 + +运行： + +```bash +uv run python scripts/dr.py run $ARGUMENTS --workers 6 +``` + +如需预演： + +```bash +uv run python scripts/dr.py run $ARGUMENTS --workers 6 --dry-run +``` + +只汇报 Python CLI 的阶段判断、产物路径和下一步。 diff --git a/.opencode/commands/dr-status.md b/.opencode/commands/dr-status.md index ed9cb63..3c3fb99 100644 --- a/.opencode/commands/dr-status.md +++ b/.opencode/commands/dr-status.md @@ -1,47 +1,12 @@ --- -description: 查看当前研究项目的进度。用法：/dr-status [slug] +description: 查看当前研究项目进度。用法：/dr-status [slug] agent: dr-pm --- -你是 dr-pm。读取项目状态并输出清晰的进度报告。 +你是 OpenCode 表层接口。运行 Python core 状态命令： -## Step 1: 定位项目 - -- `$ARGUMENTS` 非空：读取 `projects/$ARGUMENTS/manifest.json` -- 为空： - - 如果 `projects/` 下有多个项目，列出所有项目及其状态让用户选择 - - 只有一个则直接读取 - -## Step 2: 输出状态报告 - -``` -项目：<topic> -Slug：<slug> -类型：<type> | 目标字数：<target_words> 字 - -阶段进度： - Phase 1 框架规划：<pending/in_progress/completed/approved> - 框架文件：<存在/不存在> - 章节数：<N> - - Phase 2 深度研究：<pending/in_progress/completed> - 章节完成：<X/N> - 当前批次：<X>（如进行中） - 已写字数：<X> 字 - 信源数量：<X> 条 - - Phase 3 总编审校：<pending/in_progress/completed> - 审校评级：<A/B/C/D 或 未完成> - 待修正问题：<X> 条 - - Phase 4 成稿：<pending/completed> - PDF：<存在/不存在> - DOCX：<存在/不存在> - -输出文件： - <列出 projects/<slug>/ 下已存在的关键文件> +```bash +uv run python scripts/dr.py status $ARGUMENTS ``` -## 额外说明 - -如果某个 Phase 处于 in_progress 但看起来卡住了（started_at 超过 2 小时且无进展），提示用户可以重新运行对应命令继续。 +汇报阶段状态、task cards、packets、drafts、sources、final_zh/PDF/DOCX 等关键产物。 diff --git a/AGENTS.md b/AGENTS.md index da08fd2..37ddcd4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,15 +1,22 @@ # AGENTS.md — 生物医药 Deep Research 系统规则 -> 本文件为 OpenCode 会自动读取的项目级指令文件。 -> 所有 agent / skill / command 必须遵循本文件定义的研究方法论、信源标准与输出规范。 +> 本文件为跨平台项目级指令文件。Codex、OpenCode、Claude Code、Antigravity、Gemini CLI 均应以本文件为运行规则。 +> 所有平台 adapter / skill / command 必须遵循本文件定义的研究方法论、信源标准与输出规范。 --- ## 1. 项目使命 -本项目通过多 agent 协作，以**麦肯锡、德勤等顶尖机构的研究方法**，对生物医药领域（研发、工艺、管理、投资）的指定主题进行深度研究，输出专业级报告（PDF + DOCX）。 +本项目通过**Python core + skills + 可选多模型角色**协作，以**麦肯锡、德勤等顶尖机构的研究方法**，对生物医药领域（研发、工艺、管理、投资）的指定主题进行深度研究，输出专业级报告（PDF + DOCX）。 -本项目**不涉及代码开发**，所有"代码"都是为**研究流水线**服务（如 ReportLab 模板、下载脚本、信源 API 调用）。 +本项目**不涉及业务代码开发**，所有"代码"都是为**研究流水线**服务（如 Python runtime、ReportLab/Quarto 模板、下载脚本、信源 API 调用）。 + +### 1.1 v0.20 架构原则 + +- `scripts/dr.py` 与 `scripts/runtime/*` 是核心编排真源；OpenCode、Codex、Claude Code、Antigravity、Gemini CLI 只是表层入口。 +- 模型选择以 `configs/models.yaml` 为准，由 Python runtime 解析 role/task 映射。 +- Skills 以 `.agents/skills` 为 canonical registry；adapter skill 目录由 `uv run python scripts/dr.py skills sync` 同步。 +- 默认工作链路为中文主写作；英文只保留在检索关键词、原文摘录、source title、DOI/URL 与来源笔记中。 --- @@ -17,7 +24,7 @@ ### 2.1 麦肯锡核心原则 -1. **MECE**（Mutually Exclusive, Collectively Exhaustive）：章节划分互斥且穷尽 +1. **研究方法适配场景**：MECE 是常用方法之一，但 GMP/CMC/管理咨询/研发立项等场景必须选择匹配框架 2. **SCQA 叙事**（Situation → Complication → Question → Answer）：每章节开头用此结构引入 3. **金字塔原理**：结论先行，论据支撑，纵向深入，横向 MECE 4. **"每个标题即一个观点"**：标题不能是"概述""现状"这类模糊词，必须包含判断 @@ -55,28 +62,29 @@ ## 3. Phase 工作流（4 阶段） ### Phase 1：框架规划 -- **驱动命令**：`/dr-init <topic>` → `/dr-frame` -- **主导 agent**：dr-plan -- **产出**：`projects/<slug>/phase1/framework.md`（8-15 章大纲，每 section 带研究思路与字数配额） +- **驱动命令**：`uv run python scripts/dr.py init <topic>` → `uv run python scripts/dr.py frame <slug>`（`/dr-init`、`/dr-frame` 只是薄封装） +- **主导入口**：Python core 生成项目骨架与 framework；dr-plan 可作为表层访谈增强 +- **产出**：`projects/<slug>/phase1/framework.md`（记录 research_method、8-15 章大纲，每 section 带研究思路与字数配额） - **暂停点**：用户确认框架 ### Phase 2：深度研究 -- **驱动命令**：`/dr-research` -- **主导 agent**：dr-pm（调度 3-4 个 dr-analyst 并行 + dr-verifier 反方验证） -- **产出**：`projects/<slug>/phase2/drafts/chXX.md` + `evidence/chXX-evidence.md` + `sources.jsonl` +- **驱动命令**：`uv run python scripts/dr.py research <slug> --workers 6` +- **主导入口**：Python core 生成 task cards 并控制并发 +- **产出**：`projects/<slug>/phase2/task_cards.json` + `packets/*.json` + `drafts/chXX.md` + `evidence/chXX-evidence.md` + `sources.jsonl` - **不暂停**：全自动跑完 ### Phase 3：总编审校 -- **驱动命令**：`/dr-review` -- **主导 agent**：dr-chief-editor（Gemini 3.1 Pro 1M 上下文通读） +- **驱动命令**：`uv run python scripts/dr.py review <slug>`（`/dr-review` 只是薄封装） +- **主导入口**：Python core deterministic review；dr-chief-editor/Gemini 可作为后续深度审校增强 - **产出**：`projects/<slug>/phase3/critique.md` - **暂停点**：用户决策（修正 / 回炉 phase2 / 整体重来） ### Phase 4：成稿 -- **驱动命令**：`/dr-finalize` -- **主导 agent**：dr-editor-in-chief（创作）→ `scripts/phase4_pipeline.py`（执行链路） -- **执行链路**：translate → glossary(optional) → apply_glossary → polish → build_report -- **产出**：`phase4/final_en.md` + `phase4/final_zh.md` + `phase4/final_zh_polished.md` + `phase4/*.pdf` + `phase4/*.docx` +- **驱动命令**：`uv run python scripts/dr.py finalize <slug>` +- **主导入口**：Python core 中文原生成稿；OpenCode/Codex/Claude Code 只调用 CLI +- **默认链路**：final_zh.md → glossary/check(optional) → polish(optional) → citation_check → build_report +- **兼容链路**：仅显式 `--legacy-translate` 时使用 final_en.md → translate → polish +- **产出**：`phase4/final_zh.md` + `phase4/final_zh_polished.md`（可选）+ `phase4/*.pdf` + `phase4/*.docx` --- @@ -132,119 +140,56 @@ --- -## 5. Agent 角色与职责（v0.5 重构） +## 5. Python Role / Task 模型 -> 每个 agent 的详细定义见 `.opencode/agents/*.md` +平台 agent 文件只保留兼容和展示意义；真实角色、任务类型、模型、温度、并发上限以 Python runtime 为准。 -| Agent | 类型 | 模型 | 职责 | 工作语言 | -|---|---|---|---|---| -| dr-plan | primary | Opus 4.7 | Phase 1 框架规划（访谈、标题提议、生成双语 framework） | 中文对话 + 英文框架内容 | -| dr-pm | primary | Sonnet 4.6 | Phase 2 调度，批次间 context 压缩 | English | -| dr-chief-editor | primary | Gemini 3.1 Pro Preview | **Phase 3 only**：只读审校，产出 critique.md | English | -| **dr-editor-in-chief** | primary | **Opus 4.7** | **Phase 4 主导**：合并 final_en、写 Executive Summary/Abstract/Glossary、调度后续 | English | -| dr-searcher | subagent | Haiku 4.5 | 轻量检索、信源发现 | English | -| dr-analyst | subagent | Sonnet 4.6 | 章节深研（英文草稿 + 证据矩阵） | English | -| dr-verifier | subagent | GPT-5.4 | 交叉模型反方验证（唯一非 Claude 位置） | English | -| **dr-translator** | subagent | **Sonnet 4.6** | Phase 4 英译中，维护双语术语表 | 英→中 | -| dr-polisher | subagent | Sonnet 4.6 | Phase 4 中文润色、humanizer-cn + output-hygiene | 中文 | -| dr-reporter | subagent | Sonnet 4.6 | Phase 4 出稿（PDF+DOCX），**强制回填 citations** | 纯执行 | +查看当前模型配置： -**关键角色变化（v0.5）**： -- dr-chief-editor 从"Phase 3/4 总编"收窄为"Phase 3 only 只读审校" -- 新增 dr-editor-in-chief（Opus）接管 Phase 4 主导权（避免 Gemini 导致的风格断裂） -- 新增 dr-translator 专职英译中（工作流改为英文工作 + 最后翻译） +```bash +uv run python scripts/dr.py models --profile medium +uv run python scripts/dr.py models --profile medium --json +uv run python scripts/dr.py methods list +``` ---- +核心任务类型： -## 6. 模型 Slug 映射表（已确认，基于 zenmux `/api/v1/models` 实时返回，2026-04-20） +| Task type | 默认角色 | 用途 | +|---|---|---| +| `source_discovery` | `dr_searcher` | 轻量信源发现 | +| `evidence_packet` | `dr_analyst` | task card → evidence packet | +| `chapter_assembly` | `dr_analyst` | chapter brief → 中文章节 | +| `counter_verification` | `dr_verifier` | 反方证据与交叉模型验证 | +| `phase3_review` | `dr_chief_editor` | 总编审校 | +| `final_editorial` | `dr_editor_in_chief` | 中文终稿统稿 | +| `report_render` | `dr_reporter` | PDF/DOCX 渲染 | -> 任何时候要查真实可用列表： -> ```bash -> curl -sS "https://zenmux.ai/api/v1/models" -H "Authorization: Bearer $ZENMUX_API_KEY" | jq '.data[].id' -> ``` +默认策略： -### 6.1 Provider 架构 +- Codex/GPT 系列适合代码、schema、回归、review。 +- Claude/Opus/Sonnet 适合长文结构、中文表达、访谈增强。 +- Gemini 适合长上下文审校、多模态材料、替代框架评估。 +- ZenMux 混合模型仍由 `configs/models.yaml` 统一管理，平台当前会话模型不得覆盖 Python role/task 映射。 -OpenCode 的自定义 provider `npm` 字段**只支持 `@ai-sdk/openai-compatible`**，不支持 `@ai-sdk/anthropic`。因此所有模型统一走 `zenmux` 的 OpenAI 兼容端点（`https://zenmux.ai/api/v1`），slug 带 vendor 前缀。 +## 6. Platform Adapter 调用方式 -zenmux 的 OpenAI 兼容端点同样支持 `cache_control` 透传，由 zenmux 后端处理，cache 行为与官方 Anthropic API 一致。 +详见 `docs/platform-adapters.md`。摘要如下： -### 6.2 Claude 系列（走 `zenmux`，slug 带 `anthropic/` 前缀） +| Platform | 项目指令/命令位置 | 推荐调用 | +|---|---|---| +| OpenCode | `.opencode/commands/*.md` | `/dr-run <slug-or-topic>` | +| Codex | `AGENTS.md` + `$CODEX_HOME` adapter（由 `scripts/deploy_adapters.py codex` 部署） | `uv run python scripts/dr.py ...` 或 `codex exec "$(uv run python scripts/dr.py prompt dr-run '<topic>')"` | +| Claude Code | `.claude/skills/*/SKILL.md` | `/dr-run <slug-or-topic>` | +| Gemini CLI | `GEMINI.md` + `.gemini/commands/dr/*.toml` | `/dr:run <slug-or-topic>` | +| Antigravity | 打开仓库后由 Agent Manager 运行终端命令 | 要求 agent 运行 `uv run python scripts/dr.py ...` | -| 角色 | 模型 | 完整 model 字段 | 上下文 | -|---|---|---|---| -| dr-plan | Claude Opus 4.7 | `zenmux-anthropic/claude-opus-4-7` | **1M** | -| dr-pm | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | **1M** | -| dr-analyst | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | 1M | -| dr-polisher | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | 1M | -| dr-reporter | Claude Sonnet 4.6 | `zenmux-anthropic/claude-sonnet-4-6` | 1M | -| dr-searcher | Claude Haiku 4.5 | `zenmux-anthropic/claude-haiku-4-5` | 200K | +跨平台硬规则： -备用：Opus 4-7 → 4-6；Sonnet 4-6 → 4-5 - -**注意**：zenmux Anthropic 端点模型名用连字符（`4-7`），不用点（`4.7`）。baseURL 为 `https://zenmux.ai/api/anthropic/v1`。 - -### 6.3 非 Claude 系列（同样走 `zenmux`） - -| 角色 | 模型 | 完整 model 字段 | 上下文 | 备注 | -|---|---|---|---|---| -| dr-chief-editor | **Gemini 3.1 Pro Preview** | `zenmux/google/gemini-3.1-pro-preview` | 1M | 总编终审首选 | -| dr-chief-editor（备用） | Gemini 2.5 Pro | `zenmux/google/gemini-2.5-pro` | 1M | | -| dr-verifier（首选） | **GPT-5.4** | `zenmux/openai/gpt-5.4` | 1.05M | 交叉模型（非 Claude） | -| dr-verifier（备用 A） | Qwen3.6 Plus | `zenmux/qwen/qwen3.6-plus` | 1M | 中文研究强 | -| dr-verifier（备用 B） | MiniMax M2.7 | `zenmux/minimax/minimax-m2.7` | 204K | 低成本交叉 | -| dr-verifier（备用 C） | Kimi K2.5 | `zenmux/moonshotai/kimi-k2.5` | 262K | 长上下文交叉 | -| 可选（低成本推理） | DeepSeek V3.2 Thinking | `zenmux/deepseek/deepseek-reasoner` | 128K | 极低成本 | -| 可选（国产强模型） | GLM 5.1 | `zenmux/z-ai/glm-5.1` | 200K | | - -### 6.4 Prompt Cache 使用要点（Claude 必读） - -ZenMux 的 Anthropic 端点完整支持 4 种 cache 模式： -1. **系统提示缓存**（最常见）：在 system 的最后一段加 `cache_control: {"type": "ephemeral"}` 断点 -2. **工具定义缓存**：在 tools 数组最后一个工具上加断点，所有工具一起缓存 -3. **对话历史缓存**：在每轮最后一条消息加断点，自动找最长前缀匹配 -4. **多断点组合**：最多 4 个断点，用于工具/系统/RAG/对话分别缓存 - -**最低 token 要求**： -- Opus 4.x / Sonnet 4.x：≥ 1024 tokens 才会建缓存 -- Haiku 4.5：≥ 2048 tokens - -**TTL**：默认 5 分钟；可指定 `"ttl": "1h"` 延长到 1 小时（写入成本 2×，读取便宜 10%）。 - -**OpenCode 行为**：`@ai-sdk/anthropic` 包会自动对长 system prompt / 工具定义打 cache_control 断点，**你不需要手动加参数**。验证方法：在 zenmux 后台 Logs 里看 `cache_creation_input_tokens` 和 `cache_read_input_tokens` 字段。 - -**Opus 4.7 定价参考**（截至 2026-04-20）： -- 输入：25 USD/M tokens -- cache 写入（5min）：6.25 USD/M -- cache 写入（1h）：10 USD/M -- **cache 读取**：**0.5 USD/M**（只有原价 2%！） - -所以只要 cache 命中，成本可压到无 cache 的 5-10% 量级。 - -### 6.5 如何验证 cache 生效 - -1. 在 zenmux 后台 https://zenmux.ai/settings/logs 开启 **API Call Logging** 开关 -2. 启动 opencode，跑 `/dr-frame` 让 dr-plan 连续两次调用 -3. 第一次调用 Logs 应显示 `cache_creation_input_tokens > 0` -4. 第二次调用（5 分钟内）应显示 `cache_read_input_tokens > 0`，费用大幅下降 -5. 如果 cache 字段始终为 0，说明没走 Anthropic 端点，回查 agent 的 `model:` 字段是否正确用了 `zenmux-anthropic/` 前缀 -6. 本项目提供 `scripts/verify-zenmux.sh` 一键自检 - -### 6.6 模型白名单位置 - -所有可用模型已列入 `.opencode/opencode.json` 的 `provider.zenmux.models` 和 `provider.zenmux-anthropic.models`。增删模型时**两处都要更新**： -- opencode.json 决定 `/models` 下拉列表 -- AGENTS.md 本节决定角色→模型的分配逻辑 - -### 6.7 模型升级流程 - -zenmux 新模型上线后，更新顺序： -1. `curl zenmux /api/v1/models` 确认 slug -2. 更新 `.opencode/opencode.json` 的 models 段 -3. 更新 AGENTS.md §6.2 / §6.3 角色映射表 -4. 更新 `.opencode/agents/*.md` 的 `model:` 字段 -5. 运行 `bash scripts/verify-zenmux.sh` 验证 -6. 更新 PLAN.md §12 变更记录 +- 平台只做 surface adapter，不承载核心调度。 +- 不在平台 prompt 中手工并发写章节。 +- 不把平台 subagent 当默认并发机制。 +- 真实并发由 `scripts/runtime/workers.py` 的 worker pool 执行。 +- 真实模型选择由 `configs/models.yaml` 和 `scripts/runtime/roles.py` 执行。 --- @@ -264,18 +209,16 @@ zenmux 新模型上线后，更新顺序： --- -## 9. 如何判断 subagent 是否真正被独立调度（验证锚点） +## 9. 如何判断是否走了 Python Core -用户提到过"多 agent 实际上是主模型跑到底"的坑。验证方法： +不要用“平台是否 spawn subagent”作为成功标准。v0.20 的验证锚点是 Python runtime 产物： -1. **TUI 内**：`<Leader>+Right` 能切入独立子会话，若没有说明没真正调度 -2. **日志**：`opencode --print-logs` 会显示每次 Task 工具调用，附带 agent 名和模型 ID -3. **token 使用**：`/stats` 里可以看到按 agent 分的 token 消耗，Haiku 应远多于 Opus - -如果发现某个 agent 没有真正被调度，检查： -- 命令 frontmatter 是否有 `subtask: true` -- 主 agent 的 `permission.task` 是否允许目标 subagent -- 目标 subagent 的 `mode` 是否是 `subagent` +1. `uv run python scripts/dr.py status <slug>` 能看到 phase 状态。 +2. Phase 2 存在 `phase2/task_cards.json`。 +3. `--execute-packets` 后存在 `phase2/packets/*.json` 和必要时的 `phase2/packet_errors/*.json`。 +4. `--build-briefs` 后存在 `phase2/chapter_briefs/*.json`。 +5. `--assemble-chapters` 后存在 `phase2/drafts/chXX.md` 和必要时的 `phase2/chapter_errors/*.json`。 +6. `scripts/v020_regression.py` 输出 `v0.20 regression PASS`。 --- diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..fdb7ee4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,18 @@ +# Claude Code Project Instructions + +This repository is Deep Research v0.20. + +- Python core is the source of truth: `scripts/dr.py`, `scripts/runtime/**`, `configs/models.yaml`, `.agents/skills`. +- Claude Code is a surface adapter. Do not perform core orchestration in the chat thread. +- Use `.claude/skills/*/SKILL.md` commands such as `/dr-run`, `/dr-research`, `/dr-review`, `/dr-finalize`. +- Keep formal research outputs Chinese-first. Search keywords, source titles, excerpts, DOI/URL and raw notes may remain English. +- Do not modify `projects/**` unless the user is intentionally running a research project. + +Typical commands: + +```bash +uv run python scripts/dr.py run "研究主题" --slug <slug> --method mckinsey_market +uv run python scripts/dr.py research <slug> --workers 6 --execute-packets +uv run python scripts/dr.py review <slug> +uv run python scripts/dr.py finalize <slug> +``` diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..adb6630 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,18 @@ +# Gemini CLI Project Instructions + +This repository is Deep Research v0.20. + +- Python core is the source of truth: `scripts/dr.py`, `scripts/runtime/**`, `configs/models.yaml`, `.agents/skills`. +- Gemini CLI is a surface adapter. Do not perform core orchestration in the chat thread. +- Use `.gemini/commands/dr/*.toml` commands or run `uv run python scripts/dr.py ...` directly. +- Keep formal research outputs Chinese-first. Search keywords, source titles, excerpts, DOI/URL and raw notes may remain English. +- Do not modify `projects/**` unless the user is intentionally running a research project. + +Typical commands: + +```bash +uv run python scripts/dr.py run "研究主题" --slug <slug> --method mckinsey_market +uv run python scripts/dr.py research <slug> --workers 6 --execute-packets +uv run python scripts/dr.py review <slug> +uv run python scripts/dr.py finalize <slug> +``` diff --git a/PLAN.md b/PLAN.md index aa00d40..abdcfa5 100644 --- a/PLAN.md +++ b/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 作为默认路径。 + - 质量测试必须能让“泛泛咨询腔但有引用”的章节失败，让“具体审计发现+法规条款+整改动作+待补证据”的章节通过。 diff --git a/README.md b/README.md index 0842126..f97e260 100644 --- a/README.md +++ b/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 了解完整变更历史。 diff --git a/codex_adapter_templates/codex/agents/dr-analyst.toml b/codex_adapter_templates/codex/agents/dr-analyst.toml index 7bf8c2a..7529c38 100644 --- a/codex_adapter_templates/codex/agents/dr-analyst.toml +++ b/codex_adapter_templates/codex/agents/dr-analyst.toml @@ -1,25 +1,15 @@ name = "dr-analyst" -description = "Chapter deep-research agent that writes English chapter drafts and evidence matrices." +description = "Compatibility role only. v0.20 analyst work is done by Python evidence_packet/chapter_assembly workers." model = "zenmux-anthropic/claude-sonnet-4-6" model_reasoning_effort = "high" sandbox_mode = "workspace-write" developer_instructions = """ -You are dr-analyst. -Work in English. Own exactly one assigned chapter. -Load skills: search-strategy, source-quality, length-budget, evidence-table, mckinsey-method, humanizer-cn. -Use the project search gateway before MCP or generic web search: -- literature/reviews: uv run python scripts/search.py "<query>" --route scholar --num-results 10 --year-low 2023 -- patents/FTO: uv run python scripts/search.py "<query>" --route patents --num-results 10 -- news/transactions: uv run python scripts/search.py "<query>" --route news --num-results 10 --time-range m -- general gap-fill: uv run python scripts/search.py "<query>" --route general --num-results 10 -Record the routes used in the evidence file. Tavily / Exa / Brave MCP are gap-fill only for literature and patent topics. -Write: -- projects/<slug>/phase2/drafts/chXX.md -- projects/<slug>/phase2/evidence/chXX-evidence.md -- append structured sources to projects/<slug>/phase2/sources.jsonl -Every claim and numerical fact needs [src_xxx]. -Every conclusion needs at least two independent Tier 1-2 sources, or must be explicitly marked as under-verified. -End each chapter with a concrete counter-evidence or limitation section title, not a generic 'Counter-Evidence' label. -Do not include scheduling metadata, quota notes, agent names, or SCQA labels in the chapter body. +You are a compatibility role only. +Do not write chapter drafts in Codex by default. +Use Python core for analyst work: +- uv run python scripts/dr.py research <slug> --execute-packets +- uv run python scripts/dr.py research <slug> --build-briefs +- uv run python scripts/dr.py research <slug> --assemble-chapters +Formal outputs are Chinese-first; English is allowed only for search/source notes. """ nickname_candidates = ["Analyst A", "Analyst B", "Analyst C", "Analyst D"] diff --git a/codex_adapter_templates/codex/agents/dr-chief-editor.toml b/codex_adapter_templates/codex/agents/dr-chief-editor.toml index 1be6555..55caac9 100644 --- a/codex_adapter_templates/codex/agents/dr-chief-editor.toml +++ b/codex_adapter_templates/codex/agents/dr-chief-editor.toml @@ -1,15 +1,13 @@ name = "dr-chief-editor" -description = "Phase 3 read-only editorial reviewer for whole-report logic, evidence, MECE, and quality." +description = "Surface adapter role for optional Phase 3 deep review. Deterministic review lives in Python." model = "zenmux/google/gemini-3.1-pro-preview" model_reasoning_effort = "xhigh" sandbox_mode = "read-only" developer_instructions = """ -You are dr-chief-editor. -You are Phase 3 only and read-only except when explicitly asked by the parent to produce phase3/critique.md. -Review all English drafts, evidence files, sources.jsonl, framework.md, and manifest.json. -Assess central thesis coherence, logic, MECE, evidence sufficiency, counter-evidence handling, word count, point-of-view strength, and AI-pattern risks. -Do not rewrite drafts. +You are a surface adapter for optional deep review. +Default review command: +- uv run python scripts/dr.py review <slug> +You may explain or supplement phase3/critique.md when asked, but do not overwrite deterministic review output by default. Do not enter Phase 4. -Do not spawn subagents. """ nickname_candidates = ["Chief Editor"] diff --git a/codex_adapter_templates/codex/agents/dr-editor-in-chief.toml b/codex_adapter_templates/codex/agents/dr-editor-in-chief.toml index 5c08c93..93b5b73 100644 --- a/codex_adapter_templates/codex/agents/dr-editor-in-chief.toml +++ b/codex_adapter_templates/codex/agents/dr-editor-in-chief.toml @@ -1,15 +1,13 @@ name = "dr-editor-in-chief" -description = "Phase 4 lead editor for English final assembly and deterministic script orchestration." +description = "Surface adapter role for Phase 4. Chinese-native finalization lives in Python." model = "zenmux-anthropic/claude-opus-4-7" model_reasoning_effort = "xhigh" sandbox_mode = "workspace-write" developer_instructions = """ -You are dr-editor-in-chief. -Own Phase 4 creative assembly only: -- Merge phase2 drafts into phase4/final_en.md. -- Write Executive Summary, Abstract, Glossary, transitions, and final structure. -- Remove scheduling metadata and output-hygiene violations. -Do not translate the whole report yourself. Use scripts/dr.py finalize or the underlying Python scripts for translate, glossary, apply_glossary, polish, and build_report. -Keep citations intact. +You are a surface adapter for Phase 4. +Default finalization command: +- uv run python scripts/dr.py finalize <slug> +Do not merge final_en.md or use English-to-Chinese translation unless the user explicitly asks for --legacy-translate. +Do not translate or polish the full report manually in Codex. """ nickname_candidates = ["Editor in Chief"] diff --git a/codex_adapter_templates/codex/agents/dr-plan.toml b/codex_adapter_templates/codex/agents/dr-plan.toml index a45daaf..240b39d 100644 --- a/codex_adapter_templates/codex/agents/dr-plan.toml +++ b/codex_adapter_templates/codex/agents/dr-plan.toml @@ -1,18 +1,15 @@ name = "dr-plan" -description = "Deep Research framework planner for Phase 1 interview, initial scan synthesis, and bilingual research framework." +description = "Surface adapter role for Phase 1. Core init/frame orchestration lives in Python." model = "zenmux-anthropic/claude-opus-4-7" model_reasoning_effort = "high" sandbox_mode = "workspace-write" developer_instructions = """ -You are dr-plan for the biomedical Deep Research system. -Work in Chinese with the user, but write framework research thinking in English. -Follow AGENTS.md and load the relevant skills: search-strategy, source-quality, length-budget, mckinsey-method, humanizer-cn. -Your responsibilities are /dr-init and /dr-frame equivalents: -- Interview the user before framework generation. -- Propose formal report titles. -- Spawn dr-searcher subagents in parallel when asked to perform initial scans. -- Generate phase1/framework.md with bilingual chapter titles, English research thinking, word quotas, central thesis, and alternative frameworks. -Do not perform Phase 2 chapter deep research yourself. -Do not enter Phase 4. +You are a surface adapter for Deep Research v0.20. +Do not perform Phase 1 core orchestration in Codex. +Run the Python core: +- uv run python scripts/dr.py init <topic> +- uv run python scripts/dr.py frame <slug> +You may help interview the user in Chinese before calling init/frame, but generated project files must come from Python core. +Do not spawn subagents for initial scan by default. """ nickname_candidates = ["Planner Alpha", "Planner Beta", "Planner Gamma"] diff --git a/codex_adapter_templates/codex/agents/dr-pm.toml b/codex_adapter_templates/codex/agents/dr-pm.toml index 9132bec..8cdca84 100644 --- a/codex_adapter_templates/codex/agents/dr-pm.toml +++ b/codex_adapter_templates/codex/agents/dr-pm.toml @@ -1,18 +1,16 @@ name = "dr-pm" -description = "Deep Research project manager for Phase 2 batching, analyst/verifier orchestration, and project status." +description = "Surface adapter role for Phase 2/status. Core batching and concurrency live in Python." model = "zenmux-anthropic/claude-sonnet-4-6" model_reasoning_effort = "high" sandbox_mode = "workspace-write" developer_instructions = """ -You are dr-pm for the biomedical Deep Research system. -Use English for Phase 2 working outputs. -Follow AGENTS.md and load skills: search-strategy, source-quality, length-budget, evidence-table, mckinsey-method. -Your responsibilities: -- Read manifest.json and phase1/framework.md. -- Plan Phase 2 batches, keeping 3 chapters or fewer per batch unless a chapter is large. -- Spawn dr-analyst subagents in parallel for chapter drafts. -- Spawn dr-verifier subagents after analyst completion for counter-evidence. -- Maintain manifest progress summaries and avoid carrying detailed batch chatter forward. -- Never write final reports directly. +You are a surface adapter for Deep Research v0.20. +Do not batch chapters or spawn Codex subagents for research. +Run the Python core: +- 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 --build-briefs +- uv run python scripts/dr.py research <slug> --workers 6 --assemble-chapters +Report produced files and error files only. """ nickname_candidates = ["PM Alpha", "PM Beta", "PM Gamma"] diff --git a/codex_adapter_templates/codex/commands/dr-finalize.md b/codex_adapter_templates/codex/commands/dr-finalize.md index 17d8867..1979767 100644 --- a/codex_adapter_templates/codex/commands/dr-finalize.md +++ b/codex_adapter_templates/codex/commands/dr-finalize.md @@ -1,25 +1,17 @@ # Codex Command: dr-finalize -You are dr-editor-in-chief. The user requested `/dr-finalize $ARGUMENTS`. +Codex is a surface adapter for v0.20. Chinese-native finalization is the default. -Goal: run Phase 4 in Codex native mode. - -Steps: -1. Resolve `$ARGUMENTS` as project slug. -2. Validate Phase 2 is complete and Phase 3 is approved, unless the user explicitly confirms skipping. -3. Assemble `phase4/final_en.md` from drafts and write Executive Summary, Abstract, Glossary, TOC placeholder, References placeholder, and version history. -4. Run deterministic pipeline: +Run: ```bash -uv run python scripts/dr.py finalize <slug> --translate-workers 4 --glossary-workers 4 --polish-workers 4 +uv run python scripts/dr.py finalize $ARGUMENTS ``` -5. If network/API errors occur, rerun with lower workers: +Legacy English-to-Chinese pipeline is opt-in only: ```bash -uv run python scripts/dr.py finalize <slug> --translate-workers 1 --glossary-workers 3 --polish-workers 1 +uv run python scripts/dr.py finalize $ARGUMENTS --legacy-translate ``` -6. Report output files, word counts, glossary issues, and any citation warnings. - Do not translate or polish the full report manually in one LLM response. diff --git a/codex_adapter_templates/codex/commands/dr-frame.md b/codex_adapter_templates/codex/commands/dr-frame.md index 2e0ae69..d78e7dd 100644 --- a/codex_adapter_templates/codex/commands/dr-frame.md +++ b/codex_adapter_templates/codex/commands/dr-frame.md @@ -1,17 +1,11 @@ # Codex Command: dr-frame -You are dr-plan. The user requested `/dr-frame $ARGUMENTS`. +Thin wrapper around the platform-neutral Python core. -Goal: generate Phase 1 bilingual framework for the target project. +Run: -Steps: -1. Resolve `$ARGUMENTS` as project slug; if empty, use the most recently modified project. -2. Read `manifest.json` and validate Phase 1 interview is complete. -3. Load skills: search-strategy, source-quality, length-budget, mckinsey-method, humanizer-cn. -4. Spawn 3-4 `dr-searcher` subagents in parallel for MECE keyword groups. Wait for all results. -5. Synthesize `phase1/initial-scan.md`. -6. Write `phase1/framework.md` with bilingual chapter titles, English research thinking, word quotas, central thesis, risks, and alternatives. -7. Update manifest Phase 1 fields. -8. Stop and ask the user to approve the framework before Phase 2. +```bash +uv run python scripts/dr.py frame $ARGUMENTS +``` -Do not do Phase 2 research in this command. +Stop after writing `phase1/framework.md`; wait for user approval before Phase 2. diff --git a/codex_adapter_templates/codex/commands/dr-init.md b/codex_adapter_templates/codex/commands/dr-init.md index ed76e04..608040e 100644 --- a/codex_adapter_templates/codex/commands/dr-init.md +++ b/codex_adapter_templates/codex/commands/dr-init.md @@ -1,14 +1,11 @@ # Codex Command: dr-init -You are dr-plan. The user requested `/dr-init $ARGUMENTS`. +Thin wrapper around the platform-neutral Python core. -Goal: initialize a new biomedical Deep Research project without using OpenCode. +Run: -Follow AGENTS.md, then: -1. Interview the user with the 8 required questions from AGENTS.md and the existing OpenCode workflow. -2. Propose 3 formal report title/subtitle candidates. -3. After the user chooses, create `projects/<slug>/manifest.json` and the phase directories. -4. Write the interview transcript to `projects/<slug>/phase1/interview.md`. -5. Stop after initialization. Do not run `/dr-frame`. +```bash +uv run python scripts/dr.py init $ARGUMENTS +``` -Use Codex custom agent `dr-plan` if spawning is needed, but this command can usually run in the main thread. +Stop after initialization. Next step is `dr-frame`. diff --git a/codex_adapter_templates/codex/commands/dr-research.md b/codex_adapter_templates/codex/commands/dr-research.md index 5a3ddd1..9452369 100644 --- a/codex_adapter_templates/codex/commands/dr-research.md +++ b/codex_adapter_templates/codex/commands/dr-research.md @@ -1,18 +1,41 @@ # Codex Command: dr-research -You are dr-pm. The user requested `/dr-research $ARGUMENTS`. +Codex is a surface adapter for v0.20. Core Phase 2 orchestration lives in Python. -Goal: run Phase 2 deep research using Codex custom subagents. +Run: -Steps: -1. Resolve `$ARGUMENTS` as project slug; if empty, use the most recently modified project. -2. Validate `phase1.approved == true` and framework exists. -3. Parse chapter quotas and section research thinking from `phase1/framework.md`. -4. Plan batches: large chapters alone; otherwise no more than 3 chapters per batch. -5. For each batch, spawn `dr-analyst` subagents in parallel, one per chapter. -6. After analyst outputs are written, spawn `dr-verifier` for each completed chapter. -7. Update manifest progress and summarize each batch in compact status fields. -8. Deduplicate `phase2/sources.jsonl`. -9. Report totals and stop before Phase 3. +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 +``` -Do not write the final report. +Fill packets with model workers: + +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --execute-packets +``` + +For low-cost smoke tests where generic fallback is acceptable: + +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --execute-packets --allow-search-fallback +``` + +Aggregate packets into chapter briefs: + +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --build-briefs +``` + +Assemble Chinese chapter drafts: + +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --assemble-chapters +``` + +Preview: + +```bash +uv run python scripts/dr.py research $ARGUMENTS --workers 6 --dry-run +``` + +Do not perform chapter research in the Codex thread. Report the task-card and packet paths created by the CLI. diff --git a/codex_adapter_templates/codex/commands/dr-review.md b/codex_adapter_templates/codex/commands/dr-review.md index 84cacd4..2dae4b2 100644 --- a/codex_adapter_templates/codex/commands/dr-review.md +++ b/codex_adapter_templates/codex/commands/dr-review.md @@ -1,14 +1,11 @@ # Codex Command: dr-review -You are dr-chief-editor. The user requested `/dr-review $ARGUMENTS`. +Thin wrapper around the platform-neutral Python core. -Goal: perform Phase 3 whole-report editorial review. +Run: -Steps: -1. Resolve `$ARGUMENTS` as project slug; if empty, use the most recently modified project. -2. Validate `phase2.status == "completed"`. -3. Read framework, all drafts, all evidence files, sources.jsonl, and manifest. -4. Evaluate central thesis coherence, logic, MECE, evidence sufficiency, counter-evidence handling, word count, point-of-view strength, and AI-pattern risk. -5. Write `projects/<slug>/phase3/critique.md`. -6. Report rating A/B/C/D and must-fix items. -7. Stop and wait for user decision. Do not enter Phase 4. +```bash +uv run python scripts/dr.py review $ARGUMENTS +``` + +Stop after writing `phase3/critique.md`; wait for user decision before Phase 4. diff --git a/codex_adapter_templates/codex/commands/dr-run.md b/codex_adapter_templates/codex/commands/dr-run.md index 12c97db..8b2c51e 100644 --- a/codex_adapter_templates/codex/commands/dr-run.md +++ b/codex_adapter_templates/codex/commands/dr-run.md @@ -1,77 +1,17 @@ # Codex Command: dr-run -You are the Deep Research PM main thread for `/dr-run $ARGUMENTS`. +Codex is a surface adapter for v0.20. Do not spawn Codex subagents for the core workflow. -This command is the Codex equivalent of letting `dr-pm` own orchestration. Do not ask the user to run each phase manually. Inspect the project state, continue from the correct phase, spawn the required Codex custom agents, wait for their results, and only pause at the defined human decision gates. - -## Resolve Target - -1. Treat `$ARGUMENTS` as either a project slug/path or a new research topic. -2. If it matches an existing project, load `projects/<slug>/manifest.json` and continue from its current status. -3. If it is a new topic, run Phase 1 initialization and create the project structure before planning. -4. If `$ARGUMENTS` is empty, use the most recently modified project and confirm the inferred slug in your first status update. - -## Global Rules - -- Follow `AGENTS.md`, all relevant `.agents/skills/*/SKILL.md`, and the project `manifest.json`. -- Keep `projects/**` research artifacts out of system commits unless the user explicitly asks to commit research output. -- Use Codex subagents deliberately: spawn them when parallel work materially advances the phase, wait for results, and consolidate before moving on. -- Do not simulate subagent work in the main thread when the task calls for independent review, chapter research, or counter-evidence. -- Respect the required pause gates: - - Stop after Phase 1 framework is ready and ask the user to approve or revise it. - - Stop after Phase 3 critique is ready and ask whether to fix, rerun Phase 2, or restart. - - Ask for approval before expensive broad web searches, long-running external API work, or irreversible file operations. - -## Phase 1: Framework Planning - -Run this phase when there is no approved `phase1/framework.md`. - -1. Spawn `dr-plan` to interview the user if the topic is underspecified. -2. Spawn `dr-searcher` workers in parallel for initial source discovery across scientific, regulatory, clinical, commercial, and patent angles. -3. Have `dr-plan` synthesize a MECE framework with chapter-level word budgets and source strategy. -4. Write `phase1/interview.md`, `phase1/initial-scan.md`, and `phase1/framework.md`. -5. Update `manifest.json` and stop for user framework approval. - -## Phase 2: Deep Research - -Run this phase when `phase1.approved == true` and Phase 2 is incomplete. - -1. Act as `dr-pm`: parse `phase1/framework.md`, create chapter batches, and keep the main thread focused on orchestration. -2. Spawn `dr-analyst` subagents in parallel, one per chapter or chapter group depending on size. -3. Require each analyst to write English chapter drafts plus evidence matrices. -4. After analyst outputs are present, spawn independent `dr-verifier` subagents for counter-evidence and source-quality checks. -5. Reconcile verifier findings into the relevant evidence files and chapter TODOs. -6. Deduplicate and normalize `phase2/sources.jsonl`. -7. Update `manifest.json` and continue to Phase 3 unless the evidence base is materially inadequate. - -## Phase 3: Chief Editor Review - -Run this phase when Phase 2 is complete and Phase 3 is incomplete. - -1. Spawn `dr-chief-editor` as a read-only reviewer. -2. Have it assess MECE structure, evidence sufficiency, unsupported claims, source quality, chapter balance, and executive-level narrative. -3. Write `phase3/critique.md`. -4. Stop for user decision: targeted fix, rerun Phase 2 for weak chapters, or restart framework. - -## Phase 4: Finalization - -Run this phase only after the user approves Phase 3. - -1. Spawn `dr-editor-in-chief` to merge English drafts into `phase4/final_en.md`, Executive Summary, Abstract, and glossary seed. -2. Run the deterministic pipeline with: +Run the project-owned Python core: ```bash -uv run python scripts/dr.py finalize <slug> +uv run python scripts/dr.py run $ARGUMENTS --workers 6 ``` -3. If needed, spawn `dr-reporter` for final PDF/DOCX validation and citation backfill checks. -4. Report final artifact paths and remaining risks. +For a preview: -## Status Discipline +```bash +uv run python scripts/dr.py run $ARGUMENTS --workers 6 --dry-run +``` -Give concise progress updates after each phase or batch. Always say: - -- current phase -- agents spawned and why -- files produced or changed -- whether the workflow is continuing or waiting for user decision +Report only the CLI phase decision, produced files, and next step. diff --git a/configs/models.yaml b/configs/models.yaml index f3dbd50..827a360 100644 --- a/configs/models.yaml +++ b/configs/models.yaml @@ -2,7 +2,16 @@ version: 1 defaults: profile: medium + task_types: + source_discovery: dr_searcher + evidence_packet: dr_analyst + chapter_assembly: dr_analyst + counter_verification: dr_verifier + phase3_review: dr_chief_editor + final_editorial: dr_editor_in_chief + report_render: dr_reporter script_models: + # Legacy compatibility only. v0.20 defaults to Chinese-native finalization. translate: anthropic/claude-sonnet-4.6 glossary: anthropic/claude-haiku-4.5 polish: anthropic/claude-sonnet-4.6 diff --git a/configs/research_methods.yaml b/configs/research_methods.yaml new file mode 100644 index 0000000..8e4792d --- /dev/null +++ b/configs/research_methods.yaml @@ -0,0 +1,135 @@ +version: 1 +defaults: + method: mckinsey_market + +methods: + mckinsey_market: + name: McKinsey-style market and strategy research + best_for: + - market research + - investment memo + - competitive landscape + structure_principle: Pyramid principle with MECE chapter coverage. + task_axes: + - literature + - regulatory + - patents + - market + - counter + framework_sections: + - central_thesis + - chapter_outline + - alternative_frameworks + - risks_and_dependencies + + gmp_gap_assessment: + name: GMP consulting gap assessment and remediation + best_for: + - GMP audit remediation + - quality system consulting + - supplier audit CAPA + structure_principle: Regulation-to-gap-to-risk-to-CAPA pathway. + task_axes: + - regulatory_gap + - risk_classification + - capa_design + - ownership_timeline + - verification_evidence + - counter + framework_sections: + - regulatory_baseline + - gap_matrix + - risk_ranking + - capa_roadmap + - verification_plan + + cmc_process_risk: + name: CMC process and scale-up risk assessment + best_for: + - process development + - tech transfer + - manufacturing readiness + structure_principle: Process-flow, CQA/CPP, scale-up, control strategy. + task_axes: + - process_flow + - cqa_cpp + - scale_up_risk + - control_strategy + - supply_chain + - counter + framework_sections: + - process_map + - critical_quality_attributes + - critical_process_parameters + - scale_up_risks + - control_strategy + + rd_go_no_go: + name: R&D go/no-go decision research + best_for: + - project initiation + - modality selection + - development strategy + structure_principle: Scientific rationale, proof-of-concept, IP/FTO, development path, go/no-go criteria. + task_axes: + - scientific_rationale + - poc_evidence + - ip_fto + - development_path + - commercial_window + - counter + framework_sections: + - scientific_rationale + - evidence_threshold + - ip_fto + - development_plan + - go_no_go_criteria + + management_consulting: + name: Management consulting diagnostic and operating model + best_for: + - organization diagnosis + - operating model design + - governance and process improvement + structure_principle: Diagnostic baseline, capability gaps, operating model, roadmap, governance. + task_axes: + - current_state + - capability_gap + - operating_model + - governance + - implementation_roadmap + - counter + framework_sections: + - current_state_diagnosis + - capability_gap + - future_state_model + - roadmap + - governance_metrics + + gmp_quality_operations_diagnosis: + name: GMP quality, manufacturing process, and operations diagnosis + best_for: + - GMP audit remediation from client materials + - quality system diagnosis + - manufacturing process system diagnosis + - operations management transformation + structure_principle: Start from site audit evidence, map findings to regulatory baseline and operating model gaps, then design short/mid/long-term remediation. + task_axes: + - input_material_findings + - nmpa_fda_ema_ich_who_baseline + - quality_system_gap + - manufacturing_process_risk + - operations_management_gap + - team_capability + - capa_roadmap + - verification_evidence + - counter + framework_sections: + - material_evidence_map + - regulatory_and_best_practice_baseline + - quality_system_gap_matrix + - manufacturing_process_risk_map + - operations_management_diagnosis + - people_and_capability_diagnosis + - short_mid_long_term_roadmap + - governance_and_verification_plan diff --git a/docs/codex-usage.md b/docs/codex-usage.md index 4366404..7efa0f6 100644 --- a/docs/codex-usage.md +++ b/docs/codex-usage.md @@ -1,6 +1,6 @@ # Codex Native Adapter -> v0.10 起，Codex 不再只是 OpenCode 的辅助执行环境，而是 Deep Research 的并列 adapter。共享核心是 `AGENTS.md`、`scripts/`、`configs/` 和 `.agents/skills`；OpenCode 使用 `.opencode/**`，Codex 使用 `.codex/**`。 +> v0.20 起，Codex 是 Deep Research 的表层 adapter。共享核心迁移到 Python runtime：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml` 和 `.agents/skills`。Codex 不再复制核心调度逻辑。 ## Architecture @@ -8,17 +8,17 @@ |---|---:|---:|---:| | 方法论 | `AGENTS.md` | ✅ | ✅ | | Skills | `.agents/skills` | 继续保留 `.opencode/skills` | ✅ | -| Agent 定义 | 否 | `.opencode/agents/*.md` | `.codex/agents/*.toml` | -| 命令入口 | 部分共享脚本 | `.opencode/commands/*.md` | `.codex/commands/*.md` + `scripts/dr.py` | +| Agent 定义 | Python role runtime 为准 | `.opencode/agents/*.md` 仅兼容 | `$CODEX_HOME/agents/*.toml` 仅兼容 | +| 命令入口 | `scripts/dr.py` | `.opencode/commands/*.md` wrapper | `$CODEX_HOME/commands/*.md` wrapper | | Phase 4 确定性流水线 | `scripts/*.py` | ✅ | ✅ | Codex 官方行为要点： -- 项目级配置放在 `.codex/config.toml`，项目被 trust 后才会加载。 +- 用户级配置放在 `~/.codex/config.toml` 或 `$CODEX_HOME/config.toml`；项目级 `.codex/**` 不是 v0.20 推荐路径。 - Codex 会从项目根向当前目录读取 `AGENTS.md`。 - repo skills 放在 `.agents/skills/*/SKILL.md`。 -- custom agents 放在 `.codex/agents/*.toml`。 -- subagents 只有在主线程明确要求时才会启动。 +- adapter templates 保存在 `codex_adapter_templates/codex/**`，部署脚本会复制到 `$CODEX_HOME`。 +- subagents/agent threads 是 Codex 表层增强能力；v0.20 默认研究并发由 Python worker pool 执行。 ## Setup @@ -30,19 +30,21 @@ source scripts/activate.sh 首次使用 Codex adapter 前确认： ```bash -uv run python scripts/install_codex_adapter.py -find .codex -maxdepth 3 -type f | sort +uv run python scripts/deploy_adapters.py codex --dry-run +uv run python scripts/deploy_adapters.py codex --force find .agents/skills -maxdepth 2 -name SKILL.md | sort uv run python scripts/dr.py status <slug> ``` +默认部署不会写入 `config.toml`，避免覆盖现有 Codex 全局配置。只有确认要安装本项目 bundled profile 时，才运行 `uv run python scripts/deploy_adapters.py codex --force --include-config`。 + 新机器部署后可以先跑自检： ```bash uv run python scripts/deploy_check.py ``` -如果隐藏目录缺失或 skills 没同步： +如果 `$CODEX_HOME` adapter 缺失或 skills 没同步： ```bash uv run python scripts/deploy_check.py --repair --force @@ -58,17 +60,19 @@ uv run python scripts/deploy_check.py --repair --force ## Codex Commands -Codex custom command templates 位于 `.codex/commands/`。在 CLI 中可以用 `scripts/dr.py prompt` 展开： +Codex custom command templates 的真源位于 `codex_adapter_templates/codex/commands/`，部署后位于 `$CODEX_HOME/commands/`。在 CLI 中也可以绕过平台命令，直接用 `scripts/dr.py prompt` 从模板展开： ```bash uv run python scripts/dr.py prompt dr-run dual-target-rnai-pipeline-2026 codex exec "$(uv run python scripts/dr.py prompt dr-run dual-target-rnai-pipeline-2026)" ``` -推荐入口是 `dr-run`：让 Codex 主线程进入 PM 模式，读取 manifest，判断当前应该继续哪个 phase，并在 Phase 2 主动调度 `dr-analyst` / `dr-verifier` subagents。用户不需要逐个执行每个 phase；只有 Phase 1 框架确认和 Phase 3 审校决策这类人类暂停点需要停下来。 +推荐入口是 Python core。Codex command 只包装 CLI，不再让 Codex 主线程主动调度 subagents。 ```bash -codex exec "$(uv run python scripts/dr.py prompt dr-run <slug-or-topic>)" +uv run python scripts/dr.py run <slug-or-topic> +uv run python scripts/dr.py research <slug> --workers 6 +uv run python scripts/dr.py finalize <slug> ``` 分阶段命令保留为调试和人工接管入口： @@ -81,17 +85,16 @@ codex exec "$(uv run python scripts/dr.py prompt dr-review <slug>)" uv run python scripts/dr.py finalize <slug> ``` -Phase 4 推荐走确定性 CLI，而不是让单个 agent 翻译整篇： +Phase 4 默认中文原生成稿： ```bash -uv run python scripts/dr.py finalize <slug> \ - --model-profile medium +uv run python scripts/dr.py finalize <slug> --model-profile medium ``` -等价底层入口（统一 pipeline）： +旧英译中 pipeline 仅用于兼容旧项目： ```bash -uv run python scripts/phase4_pipeline.py <slug> +uv run python scripts/dr.py finalize <slug> --legacy-translate ``` 网络不稳时可显式降并发： @@ -112,31 +115,16 @@ uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mo uv run python scripts/dr.py finalize <slug> --model-profile medium --glossary-mode off ``` -## Subagent Usage +## Adapter Boundary -Codex 的平台限制是：subagents 不会仅因为 `.codex/agents/*.toml` 存在就自动启动，必须由当前主线程明确要求。`dr-run` 已把这个要求写进 PM prompt：Phase 1 会调度 `dr-plan` / `dr-searcher`，Phase 2 会调度 `dr-analyst` / `dr-verifier`，Phase 3 会调度 `dr-chief-editor`。 - -```text -Spawn dr-searcher agents in parallel for four keyword groups, wait for all results, then synthesize phase1/initial-scan.md. -``` - -推荐映射： - -- `dr-plan`：访谈、框架、初扫综合。 -- `dr-pm`：Phase 2 批次规划与调度。 -- `dr-searcher`：轻量检索。 -- `dr-analyst`：章节英文深研。 -- `dr-verifier`：反方验证，必须独立于 analyst。 -- `dr-chief-editor`：Phase 3 只读审校。 -- `dr-editor-in-chief`：Phase 4 合稿与脚本调度。 -- `dr-reporter`：出稿执行与格式验证。 +Codex 可以继续用于审阅、解释和少量人工接管，但默认研究并发由 Python task-card runtime 控制。模型选择与 role/task 映射以 `configs/models.yaml` 为准。 ## Git Hygiene 本仓库常有大量 `projects/**` 研究产物处于修改状态。Codex adapter 提交时只 stage 系统文件： ```bash -git add .codex .agents/skills scripts/dr.py docs configs README.md PLAN.md +git add codex_adapter_templates .agents/skills scripts docs configs README.md PLAN.md AGENTS.md git diff --staged --name-only ``` @@ -146,26 +134,38 @@ git diff --staged --name-only - 已生成 PDF/DOCX/TXT - 临时检查脚本或一次性研究产物 -## Installing Hidden Directories +## Deploying Adapter Files -如果 Codex 桌面沙盒禁止 agent 写入 `.codex` 或 `.agents/skills`，请在本机直接运行： +不要在仓库内维护 `.codex/**`。如果需要 Codex native adapter，请把模板部署到用户级 Codex home： + +```bash +uv run python scripts/deploy_adapters.py codex --force +``` + +兼容旧命令仍可用，但默认也会走外部部署： ```bash uv run python scripts/install_codex_adapter.py --force ``` -安装来源： +部署来源： -- `codex_adapter_templates/codex/**` → `.codex/**` -- `.opencode/skills/**` → `.agents/skills/**` +- `codex_adapter_templates/codex/**` → `$CODEX_HOME/**` 或 `~/.codex/**` +- `.agents/skills/**` → `$CODEX_HOME/skills/**` -安装后，在 Codex 中运行 `/debug-config`，确认 project `.codex/config.toml` 已加载。 +如果旧版本已经把仓库内 `.codex/**` 加进 Git，需要在本机清一次索引，让它回到“本地部署产物”身份： + +```bash +git rm -r --cached .codex +``` + +部署后，在 Codex 中运行 `/debug-config`，确认 user config 或 `CODEX_HOME` config 已加载。 ## Config Troubleshooting -如果 `.codex/config.toml` 生效后启动报错，先按下面顺序排查： +如果 Codex adapter 配置生效后启动报错，先按下面顺序排查： -1. 确认当前 project 已被 Codex trust。未 trust 时，Codex 会跳过项目级 `.codex/**`，此时 `--profile deep-research` 会报 profile 不存在。 +1. 确认部署目标正确：默认是 `$CODEX_HOME`，未设置时是 `~/.codex`。 2. Tavily / Brave / Exa MCP 默认启用但不是 required。若某个 server 启动异常，先确认对应环境变量存在，再临时把该 server 改成 `enabled = false`。 3. 如果要完全离线排障，先把第三方 MCP 全部关掉，只保留 OpenAI Docs MCP 和内置 web search。 4. 如果仍然报错，临时保留最小配置确认 Codex 主体能启动： diff --git a/docs/platform-adapters.md b/docs/platform-adapters.md new file mode 100644 index 0000000..42604c2 --- /dev/null +++ b/docs/platform-adapters.md @@ -0,0 +1,170 @@ +# v0.20 Platform Adapters + +> v0.20 的唯一核心入口是 Python core：`scripts/dr.py`、`scripts/runtime/**`、`configs/models.yaml`、`.agents/skills`。所有 IDE/CLI agent 只做 surface adapter。 + +## Shared Rule + +不要让平台 agent 自己调度 Phase 2 并发、模型选择或上下文压缩。平台只负责： + +- 运行 `uv run python scripts/dr.py ...` +- 展示产物路径与失败包 +- 做少量人工访谈、审阅、解释 +- 必要时调用其原生强模型做“补充审校”，但不得覆盖 Python runtime 的产物 schema + +最小可执行链路： + +```bash +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 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 --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 + +官方机制：OpenCode 支持 `.opencode/commands/*.md` 自定义命令；文件名就是 slash command，内容是 prompt，frontmatter 可指定 `agent`、`model`、`subtask`。OpenCode 也支持 primary/subagent 两类 agent，但 v0.20 不再把平台 subagent 当默认并发机制。 + +本项目调用方式： + +```text +/dr-init "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market +/dr-frame adc-global-landscape +/dr-research adc-global-landscape +/dr-review adc-global-landscape +/dr-finalize adc-global-landscape +/dr-status adc-global-landscape +``` + +使用建议： + +- OpenCode 适合做表层 TUI、人工访谈和快速查看状态。 +- 不要让 `dr-pm` 在 OpenCode 里 spawn 多个 dr-analyst；Phase 2 并发已经由 Python worker pool 控制。 +- 如果要用 OpenCode 原生模型优势，只用于 `frame` 前的人工访谈或 `review` 后的解释，不改变 `configs/models.yaml` 的 role/task 映射。 + +## Codex + +官方机制：Codex CLI 使用 `AGENTS.md` 作为项目指令；用户级配置位于 `~/.codex/config.toml` 或 `$CODEX_HOME/config.toml`，项目级 `.codex/**` 只作为可选覆盖。v0.20 推荐用部署脚本把 adapter 模板写到用户级 Codex home，避免在研究项目里维护 `.codex`。Codex 可通过 `/model` 选择 GPT 系列模型、通过 `/permissions` 调整审批/沙盒，也支持多 agent thread，但 v0.20 默认不使用它做研究并发。 + +本项目调用方式： + +```bash +uv run python scripts/deploy_adapters.py codex --force +codex +``` + +默认部署不会复制 `config.toml`，避免覆盖用户级 Codex 设置；只有明确需要 bundled `deep-research` profile 时才加 `--include-config`，然后用 `codex --profile deep-research`。 + +在 Codex 里直接要求： + +```text +运行：uv run python scripts/dr.py run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market +``` + +或用已有 wrapper prompt： + +```bash +codex exec "$(uv run python scripts/dr.py prompt dr-run 'adc-global-landscape')" +codex exec "$(uv run python scripts/dr.py prompt dr-research 'adc-global-landscape')" +``` + +使用建议： + +- Codex 原生 GPT 系列适合代码改造、回归测试、schema/debug、review。 +- 研究模型混合仍由 Python core 调 ZenMux；Codex 当前会话模型不决定 `dr_analyst`、`dr_verifier` 等 role。 +- `codex_native` profile 可用于偏 OpenAI/GPT 的执行环境，但仍通过 `configs/models.yaml` 解析。 + +## Claude Code + +官方机制：Claude Code 推荐用 `.claude/skills/<name>/SKILL.md` 定义可调用 skill；目录名成为 slash command。旧 `.claude/commands/*.md` 仍兼容，但 skill 优先。Claude Code 的优势是 Claude/Opus/Sonnet 对长文风格和中文润色的稳定性。 + +本项目调用方式： + +```bash +claude +``` + +在 Claude Code 中： + +```text +/dr-run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market +/dr-research adc-global-landscape +/dr-finalize adc-global-landscape +``` + +使用建议： + +- Claude Code 适合 Phase 1 人工访谈增强、Phase 4 中文风格润色建议、复杂报告结构讨论。 +- 默认不要让 Claude Code 直接整章写作或并发 spawn；让 Python core 生成 packets、briefs、drafts。 +- 若想优先用 Claude/Opus 成本包，可在 `configs/models.yaml` 里选择或新增 profile，而不是在 Claude Code prompt 里手工指定。 + +## Gemini CLI + +官方机制：Gemini CLI 支持 `GEMINI.md` 作为项目记忆，也支持 `.gemini/commands/*.toml` 自定义命令；TOML command 用 `prompt` 字段，支持 `{{args}}` 参数和 `!{...}` shell 注入。 + +本项目调用方式： + +```bash +gemini +``` + +在 Gemini CLI 中： + +```text +/dr:run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market +/dr:research adc-global-landscape +/dr:review adc-global-landscape +/dr:finalize adc-global-landscape +``` + +使用建议： + +- Gemini CLI 适合长上下文审校、框架替代方案、图表/多模态材料理解。 +- 对需要本地 shell 的命令，Gemini CLI 会在执行 shell injection 前要求确认，这是好事。 +- 研究执行仍以 Python core 为准；Gemini 模型可作为 `phase3_review` 或 `final_editorial` profile 的候选模型。 + +## Antigravity + +官方公开资料把 Antigravity 定位为 agent-first IDE：agent 可访问 editor、terminal、browser，并可并行规划、执行、验证。它适合把开发者提升为 Agent Manager，但不适合让每个 Antigravity agent 自己维护 Deep Research 的状态机。 + +本项目调用方式： + +1. 在 Antigravity 打开仓库根目录。 +2. 确认 agent 能读 `AGENTS.md`。 +3. 给 Agent Manager 一个明确任务： + +```text +请只作为 surface adapter，不要自行调度研究 agent。 +在终端运行： +uv run python scripts/dr.py run "ADC 全球竞争格局" --slug adc-global-landscape --method mckinsey_market +然后汇报生成的项目目录、framework 路径和下一步命令。 +``` + +使用建议： + +- Antigravity 的 Gemini/Opus/Gemini Computer Use/Browser 能力适合可视化 QA、PDF/HTML 预览、跨文件审阅。 +- 如果 Antigravity 提供 Opus 和 Gemini 模型，优先用它们做“表层审阅/交互”，不要替代 Python core 的 role/task 模型。 +- 对高成本/长任务，要求 Antigravity 先 dry-run，再运行真实 `--execute-packets`。 + +## Model Strategy Across Platforms + +| Platform | Surface model priority | Deep Research model source | +|---|---|---| +| OpenCode | 可用 Claude/ZenMux provider 做 TUI 增强 | `configs/models.yaml` | +| Codex | GPT 系列用于代码、测试、schema、review | `configs/models.yaml` | +| Claude Code | Opus/Sonnet 用于访谈、中文风格、结构讨论 | `configs/models.yaml` | +| Gemini CLI | Gemini 用于长上下文、多模态、框架审阅 | `configs/models.yaml` | +| Antigravity | Gemini/Opus 用于 IDE agent、browser/PDF QA | `configs/models.yaml` | + +核心原则：平台模型负责“怎么帮用户操作项目”，ZenMux/Python role 模型负责“研究任务用哪个模型执行”。 + +## Sources + +- OpenCode commands and agents: https://opencode.ai/docs/commands/ , https://opencode.ai/docs/agents/ +- Codex CLI slash commands and config: https://developers.openai.com/codex/cli/slash-commands , https://developers.openai.com/codex/config-reference +- Claude Code skills/slash commands: https://code.claude.com/docs/en/slash-commands +- Gemini CLI custom commands: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md +- Google Antigravity announcement: https://blog.google/products-and-platforms/products/gemini/gemini-3/ diff --git a/pyproject.toml b/pyproject.toml index af67d60..2b7d58b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "deep-research" -version = "0.12.0" -description = "生物医药 Deep Research 系统 - OpenCode 多 agent 协作研究流水线" +version = "0.20.0" +description = "生物医药 Deep Research 系统 - Python core + skills driven research pipeline" requires-python = ">=3.10" readme = "README.md" license = { text = "MIT" } @@ -20,6 +20,7 @@ dependencies = [ "PyYAML>=6.0.1", "rich>=13.7.0", "pypdf>=6.10.2", + "pymupdf>=1.26.0", ] [project.optional-dependencies] diff --git a/scripts/build_report.py b/scripts/build_report.py index 83a3348..aa00024 100644 --- a/scripts/build_report.py +++ b/scripts/build_report.py @@ -41,6 +41,8 @@ from pathlib import Path sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) from scripts.lib.zenmux_client import load_secrets # noqa: F401 (为一致性) +from scripts.reporting.fonts import resolve_quarto_fonts +from scripts.reporting.references import build_references_block REPO_ROOT = Path(__file__).resolve().parent.parent @@ -172,9 +174,10 @@ def prepare_qmd( subtitle = manifest.get("report_subtitle", "") date = manifest.get("date", "") - # 决定字体名称：思源宋体 CN 作正文，思源黑体 CN 作标题 - main_font = "Source Han Serif CN" - sans_font = "Source Han Sans CN" + # 决定字体名称：Quarto/xelatex 使用系统字体 family name。 + fonts = resolve_quarto_fonts(fonts_dir) + main_font = fonts.main_font + sans_font = fonts.sans_font # Write LaTeX header file for CJK font setup. # Using a separate .tex file avoids YAML escape issues with backslashes. @@ -248,7 +251,7 @@ def prepare_qmd( ) # Replace REFERENCES placeholder with actual references from sources.jsonl - ref_block = _build_references_block(sources_path, md_text) + ref_block = build_references_block(sources_path, md_text) md_text = re.sub( r"\[REFERENCES will be filled.*?\]", ref_block, @@ -286,58 +289,6 @@ def prepare_qmd( output_qmd.write_text(front_matter + md_text, encoding="utf-8") print(f" .qmd prepared: {output_qmd.name} ({len(wide_ranges)} landscape table(s))") - -def _build_references_block(sources_path: Path | None, md_text: str) -> str: - """从 sources.jsonl 生成参考文献列表，只包含在正文中实际引用的信源。""" - if not sources_path or not sources_path.exists(): - return "（参考文献列表：sources.jsonl 未找到）" - - # Find cited src_ids - cited = set(re.findall(r"\[src_([a-z0-9_]+)\]", md_text)) - if not cited: - return "" - - sources: dict[str, dict] = {} - with open(sources_path, encoding="utf-8") as f: - for line in f: - line = line.strip() - if not line: - continue - try: - obj = json.loads(line) - sid = obj.get("id", "") - key = sid.replace("src_", "") - if key in cited: - sources[sid] = obj - except json.JSONDecodeError: - pass - - if not sources: - return "" - - lines = ["## 参考文献\n"] - for sid in sorted(sources.keys()): - s = sources[sid] - authors = ", ".join(s.get("authors", [])) if s.get("authors") else "" - year = s.get("year", "") - title = s.get("title", sid) - venue = s.get("venue", "") - url = s.get("url", "") - entry = f"- **[{sid}]** " - if authors: - entry += f"{authors}. " - if year: - entry += f"({year}). " - entry += f"*{title}*" - if venue: - entry += f". {venue}" - if url: - entry += f". <{url}>" - lines.append(entry) - - return "\n".join(lines) - - def build_pdf_quarto( md_path: Path, manifest: dict, diff --git a/scripts/deploy_adapters.py b/scripts/deploy_adapters.py new file mode 100644 index 0000000..b24e31d --- /dev/null +++ b/scripts/deploy_adapters.py @@ -0,0 +1,185 @@ +#!/usr/bin/env python3 +"""Deploy platform adapter templates outside the repository checkout.""" + +from __future__ import annotations + +import argparse +import os +import shutil +import sys +from dataclasses import dataclass, field +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parent.parent +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.runtime.skills import SkillRegistry + +CODEX_TEMPLATE = REPO_ROOT / "codex_adapter_templates" / "codex" + + +@dataclass +class DeployResult: + platform: str + target: Path + written: list[Path] = field(default_factory=list) + skipped: list[Path] = field(default_factory=list) + planned: list[Path] = field(default_factory=list) + backups: list[Path] = field(default_factory=list) + + +def default_codex_home( + *, + env: dict[str, str] | None = None, + user_home: Path | None = None, +) -> Path: + values = os.environ if env is None else env + if values.get("CODEX_HOME"): + return Path(values["CODEX_HOME"]).expanduser() + home = Path.home() if user_home is None else user_home + return home / ".codex" + + +def copy_tree_contents( + src: Path, + dst: Path, + *, + force: bool, + dry_run: bool = False, + backup_existing: bool = True, + exclude: set[Path] | None = None, +) -> DeployResult: + if not src.exists(): + raise FileNotFoundError(f"adapter template source not found: {src}") + + result = DeployResult(platform="copy", target=dst) + excluded = exclude or set() + for item in sorted(src.rglob("*")): + rel = item.relative_to(src) + if rel in excluded: + continue + target = dst / rel + if item.is_dir(): + if not dry_run: + target.mkdir(parents=True, exist_ok=True) + continue + + if target.exists() and not force: + result.skipped.append(target) + continue + + result.planned.append(target) + if dry_run: + continue + + target.parent.mkdir(parents=True, exist_ok=True) + if target.exists() and force and backup_existing: + backup = target.with_name(f"{target.name}.bak") + shutil.copy2(target, backup) + result.backups.append(backup) + shutil.copy2(item, target) + result.written.append(target) + return result + + +def _merge_results(platform: str, target: Path, parts: list[DeployResult]) -> DeployResult: + merged = DeployResult(platform=platform, target=target) + for part in parts: + merged.written.extend(part.written) + merged.skipped.extend(part.skipped) + merged.planned.extend(part.planned) + merged.backups.extend(part.backups) + return merged + + +def copy_registered_skills(dst: Path, *, force: bool, dry_run: bool = False) -> DeployResult: + result = DeployResult(platform="skills", target=dst) + for skill in SkillRegistry().list(): + part = copy_tree_contents(skill.path.parent, dst / skill.name, force=force, dry_run=dry_run) + result.written.extend(part.written) + result.skipped.extend(part.skipped) + result.planned.extend(part.planned) + result.backups.extend(part.backups) + return result + + +def deploy_codex( + *, + target: Path | None = None, + force: bool = False, + skip_skills: bool = False, + dry_run: bool = False, + include_config: bool = False, + repo_root: Path = REPO_ROOT, +) -> DeployResult: + codex_home = (target or default_codex_home()).expanduser() + template = repo_root / "codex_adapter_templates" / "codex" + + parts = [ + copy_tree_contents( + template, + codex_home, + force=force, + dry_run=dry_run, + exclude=set() if include_config else {Path("config.toml")}, + ), + ] + if not skip_skills: + parts.append(copy_registered_skills(codex_home / "skills", force=force, dry_run=dry_run)) + return _merge_results("codex", codex_home, parts) + + +def print_result(result: DeployResult) -> None: + action = "planned" if result.planned and not result.written else "written" + print(f"{result.platform} adapter deployment") + print(f" target: {result.target}") + print(f" files {action}: {len(result.planned if action == 'planned' else result.written)}") + print(f" files skipped: {len(result.skipped)}") + print(f" backups: {len(result.backups)}") + if result.written: + for path in result.written: + print(f" {path}") + elif result.planned: + for path in result.planned: + print(f" {path}") + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(description="Deploy Deep Research surface adapters") + sub = parser.add_subparsers(dest="platform", required=True) + + codex = sub.add_parser("codex", help="Deploy Codex adapter to CODEX_HOME or a target directory") + codex.add_argument("--target", type=Path, help="Codex home target; defaults to $CODEX_HOME or ~/.codex") + codex.add_argument("--force", action="store_true", help="overwrite existing files and create .bak backups") + codex.add_argument("--skip-skills", action="store_true", help="do not copy canonical skills into target/skills") + codex.add_argument("--include-config", action="store_true", help="also copy config.toml; off by default to avoid overwriting global Codex config") + codex.add_argument("--dry-run", action="store_true", help="show files that would be written") + return parser + + +def main() -> int: + args = build_parser().parse_args() + if args.platform == "codex": + result = deploy_codex( + target=args.target, + force=args.force, + skip_skills=args.skip_skills, + dry_run=args.dry_run, + include_config=args.include_config, + ) + print_result(result) + print() + print("Run Codex from this repository after deployment:") + if args.include_config: + print(" codex --profile deep-research") + else: + print(" codex") + print("Note: config.toml is not copied by default. Use --include-config only if you want the bundled profile.") + return 0 + raise SystemExit(f"unsupported platform: {args.platform}") + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/deploy_check.py b/scripts/deploy_check.py index 01a11a7..53d301a 100644 --- a/scripts/deploy_check.py +++ b/scripts/deploy_check.py @@ -17,8 +17,13 @@ except ModuleNotFoundError: # pragma: no cover - Python < 3.11 fallback. REPO_ROOT = Path(__file__).resolve().parent.parent +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.deploy_adapters import default_codex_home, deploy_codex +from scripts.runtime.skills import SkillRegistry + CODEX_TEMPLATE = REPO_ROOT / "codex_adapter_templates" / "codex" -CODEX_ROOT = REPO_ROOT / ".codex" OPENCODE_ROOT = REPO_ROOT / ".opencode" AGENTS_SKILLS = REPO_ROOT / ".agents" / "skills" OPENCODE_SKILLS = OPENCODE_ROOT / "skills" @@ -28,11 +33,14 @@ REQUIRED_PATHS = [ "README.md", "PLAN.md", ".opencode/opencode.json", - ".codex/config.toml", - ".codex/agents/dr-pm.toml", - ".codex/commands/dr-run.md", + "codex_adapter_templates/codex/config.toml", + "codex_adapter_templates/codex/agents/dr-pm.toml", + "codex_adapter_templates/codex/commands/dr-run.md", ".agents/skills/search-strategy/SKILL.md", + "skills/deep-research/SKILL.md", + "skills/document-ingest/SKILL.md", "scripts/dr.py", + "scripts/deploy_adapters.py", "scripts/install_codex_adapter.py", ] @@ -111,19 +119,26 @@ def check_deployment() -> int: if not (REPO_ROOT / item).exists(): issues.append(f"missing required path: {item}") - tracked = git_tracked([".codex", ".opencode", ".agents/skills"]) + tracked = git_tracked(["codex_adapter_templates", ".opencode", ".agents/skills", "skills"]) + legacy_tracked = git_tracked([".codex"]) + if legacy_tracked: + warnings.append("legacy .codex files are still tracked; run: git rm -r --cached .codex") for item in REQUIRED_PATHS: - if item.startswith((".codex/", ".opencode/", ".agents/")) and item not in tracked: + if item.startswith(("codex_adapter_templates/", ".opencode/", ".agents/")) and item not in tracked: warnings.append(f"not tracked by git: {item}") - skill_files = sorted(AGENTS_SKILLS.glob("*/SKILL.md")) - if len(skill_files) < 10: - issues.append(f"expected at least 10 Codex skills, found {len(skill_files)}") + skills = SkillRegistry().list() + if len(skills) < 10: + issues.append(f"expected at least 10 Codex skills, found {len(skills)}") - check_toml(CODEX_ROOT / "config.toml", issues) - for path in sorted((CODEX_ROOT / "agents").glob("*.toml")): + check_toml(CODEX_TEMPLATE / "config.toml", issues) + for path in sorted((CODEX_TEMPLATE / "agents").glob("*.toml")): check_toml(path, issues) + codex_home = default_codex_home() + if not (codex_home / "commands" / "dr-run.md").exists(): + warnings.append(f"Codex adapter not deployed to {codex_home}; run scripts/deploy_adapters.py codex") + env_values = {key: os.environ.get(key, "") for key in REQUIRED_ENV_KEYS} env_values.update({k: v for k, v in parse_env(REPO_ROOT / "secrets.env").items() if not env_values.get(k)}) missing_env = [key for key in REQUIRED_ENV_KEYS if not env_values.get(key)] @@ -132,9 +147,11 @@ def check_deployment() -> int: print("Deep Research deployment check") print(f" repo: {REPO_ROOT}") - print(f" codex files tracked: {sum(1 for p in tracked if p.startswith('.codex/'))}") + print(f" codex template files tracked: {sum(1 for p in tracked if p.startswith('codex_adapter_templates/'))}") + print(f" legacy .codex files tracked: {len(legacy_tracked)}") + print(f" codex home: {codex_home}") print(f" opencode files tracked: {sum(1 for p in tracked if p.startswith('.opencode/'))}") - print(f" codex skills: {len(skill_files)}") + print(f" codex skills: {len(skills)}") if warnings: print("\nWarnings:") @@ -151,9 +168,9 @@ def check_deployment() -> int: return 0 -def repair(force: bool) -> int: +def repair(force: bool, codex_home: Path | None) -> int: try: - codex_written = copy_tree_contents(CODEX_TEMPLATE, CODEX_ROOT, force=force) + codex_result = deploy_codex(target=codex_home, force=force) skills_written = copy_tree_contents(OPENCODE_SKILLS, AGENTS_SKILLS, force=force) except PermissionError as exc: print(f"repair failed: permission denied: {exc}", file=sys.stderr) @@ -163,19 +180,21 @@ def repair(force: bool) -> int: return 1 print("Repair completed.") - print(f" .codex files written: {len(codex_written)}") + print(f" Codex home files written: {len(codex_result.written)}") + print(f" Codex home: {codex_result.target}") print(f" .agents skills written: {len(skills_written)}") return check_deployment() def main() -> int: parser = argparse.ArgumentParser(description="Check or repair Deep Research deployment files") - parser.add_argument("--repair", action="store_true", help="copy Codex templates and skills into hidden dirs") + parser.add_argument("--repair", action="store_true", help="deploy Codex templates outside the repo and sync skills") parser.add_argument("--force", action="store_true", help="overwrite existing files during --repair") + parser.add_argument("--codex-home", type=Path, help="Codex home target for --repair; defaults to $CODEX_HOME or ~/.codex") args = parser.parse_args() if args.repair: - return repair(force=args.force) + return repair(force=args.force, codex_home=args.codex_home) return check_deployment() diff --git a/scripts/dr.py b/scripts/dr.py index e83cffe..b68d19d 100644 --- a/scripts/dr.py +++ b/scripts/dr.py @@ -12,6 +12,7 @@ import json import re import subprocess import sys +from datetime import datetime, timezone from pathlib import Path @@ -25,25 +26,35 @@ from scripts.lib.model_config import ( parse_model_overrides, resolve_model_profile, ) +from scripts.runtime.assembly import build_chapter_briefs, run_chapter_assembly_workers +from scripts.runtime.orchestrator import create_phase2_task_cards, write_placeholder_packets +from scripts.runtime.methods import ResearchMethodRegistry +from scripts.runtime.phase1 import create_project, render_framework, write_material_brief +from scripts.runtime.review import build_phase3_critique +from scripts.runtime.roles import resolve_runtime_profile +from scripts.runtime.sources import rebuild_sources_from_packets +from scripts.runtime.skills import SkillRegistry, default_adapter_skill_dirs +from scripts.runtime.tasks import TaskCard +from scripts.runtime.workers import run_packet_workers PROJECTS_DIR = REPO_ROOT / "projects" -CODEX_COMMANDS_DIR = REPO_ROOT / ".codex" / "commands" CODEX_COMMAND_TEMPLATES_DIR = REPO_ROOT / "codex_adapter_templates" / "codex" / "commands" +LEGACY_CODEX_COMMANDS_DIR = REPO_ROOT / ".codex" / "commands" -def resolve_project(project: str | None) -> Path: +def resolve_project(project: str | None, *, projects_dir: Path = PROJECTS_DIR) -> Path: if project: p = Path(project) if p.is_dir(): return p.resolve() - cand = PROJECTS_DIR / project + cand = projects_dir / project if cand.is_dir(): return cand.resolve() raise SystemExit(f"project not found: {project}") manifests = sorted( - PROJECTS_DIR.glob("*/manifest.json"), + projects_dir.glob("*/manifest.json"), key=lambda p: p.stat().st_mtime, reverse=True, ) @@ -71,6 +82,43 @@ def file_state(path: Path) -> str: return "yes" if path.exists() else "no" +def packet_state_counts(project_root: Path) -> dict[str, int]: + packets = sorted((project_root / "phase2" / "packets").glob("*.json")) + errors = sorted((project_root / "phase2" / "packet_errors").glob("*.json")) + counts = { + "ready": 0, + "placeholder": 0, + "invalid": 0, + "errors": 0, + "stale_errors": 0, + "total": len(packets), + } + ready_stems: set[str] = set() + for path in packets: + try: + packet = json.loads(path.read_text(encoding="utf-8")) + except Exception: + counts["invalid"] += 1 + continue + has_evidence = bool( + packet.get("claims") + or packet.get("evidence_items") + or packet.get("counter_evidence") + or packet.get("source_ids") + ) + if has_evidence: + counts["ready"] += 1 + ready_stems.add(path.stem) + else: + counts["placeholder"] += 1 + for path in errors: + if path.stem in ready_stems: + counts["stale_errors"] += 1 + else: + counts["errors"] += 1 + return counts + + def run_cmd(cmd: list[str], *, dry_run: bool) -> int: printable = " ".join(cmd) print(f"$ {printable}") @@ -79,6 +127,244 @@ def run_cmd(cmd: list[str], *, dry_run: bool) -> int: return subprocess.run(cmd, cwd=REPO_ROOT, check=False).returncode +def cmd_init(args: argparse.Namespace) -> int: + projects_dir = Path(args.projects_dir) if args.projects_dir else PROJECTS_DIR + project_root = create_project( + topic=args.topic, + slug=args.slug, + projects_dir=projects_dir, + method_key=args.method, + report_type=args.report_type, + model_profile=args.profile, + target_words=args.target_words, + input_materials=args.input_material, + ) + print(f"Project: {project_root.name}") + print(f"Created: {project_root}") + print("Runtime: python-core-v0.20") + print("Next: run `dr.py frame <project>` to generate phase1/framework.md") + return 0 + + +def cmd_frame(args: argparse.Namespace) -> int: + project_root = resolve_project(args.project) + if args.dry_run: + manifest = load_manifest(project_root) + method = ResearchMethodRegistry().get(args.method or manifest.get("research_method")) + print(f"Project: {project_root.name}") + print(f"Would write: phase1/framework.md") + print(f"Research method: {method.key}") + print(f"Chapters: {args.chapters}") + return 0 + path = render_framework(project_root, method_key=args.method, chapter_count=args.chapters) + print(f"Project: {project_root.name}") + print(f"Wrote: {path.relative_to(project_root)}") + print("Pause: review and approve the framework before Phase 2.") + return 0 + + +def cmd_approve(args: argparse.Namespace) -> int: + project_root = resolve_project(args.project) + manifest = load_manifest(project_root) + phase1 = manifest.setdefault("phase1", {}) + phase1["approved"] = True + phase1["requires_user_interview"] = False + phase1["approved_at"] = datetime.now(timezone.utc).replace(microsecond=0).isoformat() + manifest["updated_at"] = phase1["approved_at"] + (project_root / "manifest.json").write_text( + json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + print(f"Project: {project_root.name}") + print("Phase 1 approved. Phase 2 research is now enabled.") + return 0 + + +def cmd_skills(args: argparse.Namespace) -> int: + registry = SkillRegistry() + if args.skills_cmd == "list": + for name in registry.list_names(): + print(name) + return 0 + if args.skills_cmd == "validate": + result = registry.validate() + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 0 if result["ok"] else 1 + if args.skills_cmd == "sync": + targets = [Path(item) for item in args.target] if args.target else default_adapter_skill_dirs() + copied = registry.sync_to(targets, force=True) + print(f"Synced skills: {copied}") + for target in targets: + print(f" {target}") + return 0 + raise SystemExit(f"unknown skills command: {args.skills_cmd}") + + +def cmd_methods(args: argparse.Namespace) -> int: + registry = ResearchMethodRegistry() + if args.methods_cmd == "list": + for name in registry.list_names(): + method = registry.get(name) + print(f"{method.key}: {method.name}") + return 0 + if args.methods_cmd == "show": + method = registry.get(args.method) + print(json.dumps(method.__dict__, ensure_ascii=False, indent=2)) + return 0 + raise SystemExit(f"unknown methods command: {args.methods_cmd}") + + +def cmd_research(args: argparse.Namespace) -> int: + project_root = resolve_project(args.project) + manifest = load_manifest(project_root) + if not args.force and not (manifest.get("phase1") or {}).get("approved"): + raise SystemExit( + "Phase 1 is not approved. Review phase1/material_brief.md and phase1/framework.md, " + "then run `uv run python scripts/dr.py approve <project>` or pass --force." + ) + runtime = resolve_runtime_profile(profile=args.profile) + card_dicts = create_phase2_task_cards( + project_root, + axes=args.axis, + dry_run=args.dry_run, + ) + if args.execute_packets and args.dry_run: + raise SystemExit("--execute-packets cannot be combined with --dry-run") + if args.assemble_chapters and args.dry_run: + raise SystemExit("--assemble-chapters cannot be combined with --dry-run") + if args.execute_packets: + from scripts.lib.zenmux_client import ZenMuxClient, load_secrets + from scripts.runtime.workers import ProjectSearchProvider + + load_secrets() + + def client_factory(_role): + return ZenMuxClient(log_file=project_root / "phase2" / "logs" / "packets.jsonl") + + def search_provider_factory(): + return ProjectSearchProvider(strict_specialized=not args.allow_search_fallback) + + packet_count = run_packet_workers( + project_root=project_root, + cards=[TaskCard(**item) for item in card_dicts], + runtime=runtime, + client_factory=client_factory, + search_provider_factory=search_provider_factory, + workers=args.workers, + ) + elif not (args.build_briefs or args.assemble_chapters): + packet_count = write_placeholder_packets(project_root, card_dicts, dry_run=args.dry_run) + else: + packet_count = len(list((project_root / "phase2" / "packets").glob("*.json"))) + brief_count = 0 + chapter_count = 0 + source_count = None + if args.build_briefs or args.assemble_chapters: + source_count = rebuild_sources_from_packets(project_root) + briefs = build_chapter_briefs(project_root) + brief_count = len(briefs) + if args.assemble_chapters: + from scripts.lib.zenmux_client import ZenMuxClient, load_secrets + + load_secrets() + + def chapter_client_factory(_role): + return ZenMuxClient(log_file=project_root / "phase2" / "logs" / "chapters.jsonl") + + chapter_count = run_chapter_assembly_workers( + project_root=project_root, + briefs=briefs, + runtime=runtime, + client_factory=chapter_client_factory, + workers=args.workers, + ) + print(f"Project: {project_root.name}") + print(f"Runtime: python-core-v0.20") + print(f"Model profile: {runtime.profile}") + print(f"Workers: {args.workers}") + print(f"Task cards: {len(card_dicts)}") + print(f"Packets: {packet_count}") + if source_count is not None: + print(f"Sources rebuilt: {source_count}") + if args.build_briefs or args.assemble_chapters: + print(f"Chapter briefs: {brief_count}") + if args.assemble_chapters: + print(f"Chapter drafts: {chapter_count}") + if args.dry_run: + print("Dry run: no files written") + elif args.assemble_chapters: + print("Wrote: phase2/drafts/chXX.md") + elif args.execute_packets: + print("Wrote: phase2/task_cards.json and validated phase2/packets/*.json") + print("Next: rerun with --build-briefs to aggregate packets into chapter briefs.") + elif args.build_briefs: + print("Wrote: phase2/chapter_briefs/*.json") + print("Next: rerun with --assemble-chapters to write Chinese chapter drafts.") + else: + print("Wrote: phase2/task_cards.json and phase2/packets/*.json") + print("Next: rerun with --execute-packets to fill packets via model workers.") + return 0 + + +def cmd_run(args: argparse.Namespace) -> int: + target = args.project_or_topic + projects_dir = Path(args.projects_dir) if args.projects_dir else PROJECTS_DIR + try: + project_root = resolve_project(target, projects_dir=projects_dir) + except SystemExit: + if args.dry_run: + print(f"New topic detected: {target}") + print("Dry run: would create project and write phase1/framework.md") + return 0 + project_root = create_project( + topic=target, + slug=args.slug, + projects_dir=projects_dir, + method_key=args.method, + report_type=args.report_type, + model_profile=args.profile or "medium", + target_words=args.target_words, + input_materials=args.input_material, + ) + framework = render_framework(project_root, chapter_count=args.chapters) + print(f"Project: {project_root.name}") + print("Runtime: python-core-v0.20") + print(f"Created: {project_root}") + print(f"Wrote: {framework.relative_to(project_root)}") + print("Pause: review and approve the framework before Phase 2.") + return 0 + + print(f"Project: {project_root.name}") + print("Runtime: python-core-v0.20") + print("Next command: research") + if args.dry_run: + print("Dry run: would inspect manifest and continue from the next incomplete phase") + return 0 + return cmd_research( + argparse.Namespace( + project=str(project_root), + workers=args.workers, + axis=None, + profile=args.profile, + execute_packets=False, + allow_search_fallback=False, + build_briefs=False, + assemble_chapters=False, + force=False, + dry_run=False, + ) + ) + + +def cmd_review(args: argparse.Namespace) -> int: + project_root = resolve_project(args.project) + path = build_phase3_critique(project_root) + print(f"Project: {project_root.name}") + print(f"Wrote: {path.relative_to(project_root)}") + print("Pause: review critique before Phase 4.") + return 0 + + def cmd_status(args: argparse.Namespace) -> int: project_root = resolve_project(args.project) manifest = load_manifest(project_root) @@ -86,6 +372,8 @@ def cmd_status(args: argparse.Namespace) -> int: drafts = sorted((project_root / "phase2" / "drafts").glob("ch*.md")) evidence = sorted((project_root / "phase2" / "evidence").glob("ch*-evidence.md")) + task_cards = project_root / "phase2" / "task_cards.json" + packet_counts = packet_state_counts(project_root) sources = project_root / "phase2" / "sources.jsonl" final_en = project_root / "phase4" / "final_en.md" final_zh = project_root / "phase4" / "final_zh.md" @@ -93,7 +381,8 @@ def cmd_status(args: argparse.Namespace) -> int: glossary = project_root / "phase4" / "glossary.json" en_words = count_words(final_en.read_text(encoding="utf-8")) if final_en.exists() else 0 - zh_chars = count_chinese_chars(final_zh_polished.read_text(encoding="utf-8")) if final_zh_polished.exists() else 0 + zh_source = final_zh_polished if final_zh_polished.exists() else final_zh + zh_chars = count_chinese_chars(zh_source.read_text(encoding="utf-8")) if zh_source.exists() else 0 source_count = 0 if sources.exists(): source_count = sum(1 for line in sources.read_text(encoding="utf-8").splitlines() if line.strip()) @@ -110,6 +399,16 @@ def cmd_status(args: argparse.Namespace) -> int: print() print("Artifacts:") print(f" framework: {file_state(project_root / 'phase1' / 'framework.md')}") + print(f" task_cards.json: {file_state(task_cards)}") + print( + " packets: " + f"ready={packet_counts['ready']} " + f"placeholder={packet_counts['placeholder']} " + f"invalid={packet_counts['invalid']} " + f"errors={packet_counts['errors']} " + f"stale_errors={packet_counts['stale_errors']} " + f"total={packet_counts['total']}" + ) print(f" drafts: {len(drafts)}") print(f" evidence files: {len(evidence)}") print(f" sources: {source_count}") @@ -124,13 +423,13 @@ def cmd_prompt(args: argparse.Namespace) -> int: name = args.command if not name.startswith("dr-"): name = f"dr-{name}" - path = CODEX_COMMANDS_DIR / f"{name}.md" - if not path.exists(): - fallback = CODEX_COMMAND_TEMPLATES_DIR / f"{name}.md" - if fallback.exists(): - path = fallback - else: - raise SystemExit(f"Codex command template not found: {path}") + candidates = [ + CODEX_COMMAND_TEMPLATES_DIR / f"{name}.md", + LEGACY_CODEX_COMMANDS_DIR / f"{name}.md", + ] + path = next((candidate for candidate in candidates if candidate.exists()), None) + if path is None: + raise SystemExit(f"Codex command template not found: {candidates[0]}") text = path.read_text(encoding="utf-8") if args.argument: @@ -174,6 +473,60 @@ def cmd_finalize(args: argparse.Namespace) -> int: raise SystemExit(f"model profile resolution failed: {exc}") from exc roles = resolved["roles"] + if not args.legacy_translate: + cmd: list[str] = [ + sys.executable, + str(REPO_ROOT / "scripts" / "build_report.py"), + str(project_root), + "--input", + args.input, + ] + if args.report_engine: + cmd += ["--engine", args.report_engine] + if args.no_docx: + cmd.append("--no-docx") + if args.no_pdf: + cmd.append("--no-pdf") + if args.dry_run: + print("Chinese-native finalize plan:") + print("$ " + " ".join(cmd)) + if args.polish: + print( + "$ " + + " ".join( + [ + sys.executable, + str(REPO_ROOT / "scripts" / "polish.py"), + str(project_root), + "--input", + args.input, + "--workers", + str(args.polish_workers), + "--model", + roles.get("polish", "anthropic/claude-sonnet-4.6"), + ] + ) + ) + return 0 + if args.polish: + rc = run_cmd( + [ + sys.executable, + str(REPO_ROOT / "scripts" / "polish.py"), + str(project_root), + "--input", + args.input, + "--workers", + str(args.polish_workers), + "--model", + roles.get("polish", "anthropic/claude-sonnet-4.6"), + ], + dry_run=False, + ) + if rc != 0: + return rc + return run_cmd(cmd, dry_run=False) + cmd = [ sys.executable, str(REPO_ROOT / "scripts" / "phase4_pipeline.py"), @@ -212,6 +565,49 @@ def cmd_models(args: argparse.Namespace) -> int: except ModelConfigError as exc: raise SystemExit(f"model profile resolution failed: {exc}") from exc + if args.probe: + from scripts.lib.zenmux_client import ZenMuxClient, load_secrets, normalize_zenmux_model + + load_secrets() + results = [] + with ZenMuxClient() as client: + for requested_model in sorted(set(resolved["roles"].values())): + api_model = normalize_zenmux_model(requested_model) + try: + content = client.chat_complete( + model=requested_model, + system="Health check.", + user="Reply with OK only.", + temperature=0, + max_tokens=16, + tag=f"models:probe:{requested_model}", + ) + results.append({ + "requested_model": requested_model, + "api_model": api_model, + "ok": True, + "response": content.strip()[:80], + }) + except Exception as exc: # noqa: BLE001 - probe should report every model. + results.append({ + "requested_model": requested_model, + "api_model": api_model, + "ok": False, + "error": str(exc)[:500], + }) + + if args.json: + print(json.dumps({**resolved, "probe": results}, ensure_ascii=False, indent=2)) + else: + print(f"Profile: {resolved['profile']}") + print("Model probe:") + for item in results: + status = "ok" if item["ok"] else "fail" + print(f" {status} {item['requested_model']} -> {item['api_model']}") + if not item["ok"]: + print(f" {item['error']}") + return 0 if all(item["ok"] for item in results) else 1 + if args.json: print(json.dumps(resolved, ensure_ascii=False, indent=2)) return 0 @@ -222,6 +618,10 @@ def cmd_models(args: argparse.Namespace) -> int: print("Roles:") for role in sorted(resolved["roles"]): print(f" {role}: {resolved['roles'][role]}") + if resolved.get("task_types"): + print("Task types:") + for task_type in sorted(resolved["task_types"]): + print(f" {task_type}: {resolved['task_types'][task_type]}") return 0 @@ -245,10 +645,78 @@ def build_parser() -> argparse.ArgumentParser: parser = argparse.ArgumentParser(description="Deep Research platform-neutral CLI") sub = parser.add_subparsers(dest="cmd", required=True) + init = sub.add_parser("init", help="Initialize a Python-core research project") + init.add_argument("topic", help="Research topic") + init.add_argument("--slug", help="Project slug") + init.add_argument("--method", help="Research method key") + init.add_argument("--type", dest="report_type", default="research", help="Report type") + init.add_argument("--profile", default="medium", help="Model profile name from configs/models.yaml") + init.add_argument("--target-words", type=int, default=30000) + init.add_argument("--input-material", action="append", default=[], help="Path or note for user-provided material") + init.add_argument("--projects-dir", help="Override projects directory") + init.set_defaults(func=cmd_init) + + approve = sub.add_parser("approve", help="Approve Phase 1 gates before Phase 2") + approve.add_argument("project", help="Project slug or path") + approve.set_defaults(func=cmd_approve) + + frame = sub.add_parser("frame", help="Generate Phase 1 framework.md") + frame.add_argument("project", help="Project slug or path") + frame.add_argument("--method", help="Override research method key") + frame.add_argument("--chapters", type=int, default=10) + frame.add_argument("--dry-run", action="store_true") + frame.set_defaults(func=cmd_frame) + + run = sub.add_parser("run", help="Run the platform-neutral Python-core workflow") + run.add_argument("project_or_topic", help="Project slug/path or new topic") + run.add_argument("--workers", type=int, default=6) + run.add_argument("--profile", help="Model profile name from configs/models.yaml") + run.add_argument("--slug", help="Project slug when project_or_topic is new") + run.add_argument("--method", help="Research method key when project_or_topic is new") + run.add_argument("--type", dest="report_type", default="research", help="Report type for new project") + run.add_argument("--target-words", type=int, default=30000) + run.add_argument("--chapters", type=int, default=10) + run.add_argument("--input-material", action="append", default=[]) + run.add_argument("--projects-dir", help="Override projects directory") + run.add_argument("--dry-run", action="store_true") + run.set_defaults(func=cmd_run) + + research = sub.add_parser("research", help="Run v0.20 task-card Phase 2") + research.add_argument("project", help="Project slug or path") + research.add_argument("--workers", type=int, default=6) + research.add_argument("--axis", action="append", help="Restrict generated task axes; repeatable") + research.add_argument("--profile", help="Model profile name from configs/models.yaml") + research.add_argument("--execute-packets", action="store_true", help="Call model workers to fill evidence packets") + research.add_argument("--allow-search-fallback", action="store_true", help="Allow generic search fallback for specialized routes") + research.add_argument("--build-briefs", action="store_true", help="Aggregate packets into chapter briefs") + research.add_argument("--assemble-chapters", action="store_true", help="Call model workers to write Chinese chapter drafts") + research.add_argument("--force", action="store_true", help="bypass Phase 1 approval gate") + research.add_argument("--dry-run", action="store_true") + research.set_defaults(func=cmd_research) + + skills = sub.add_parser("skills", help="Manage canonical skills") + skill_sub = skills.add_subparsers(dest="skills_cmd", required=True) + skill_sub.add_parser("list", help="List canonical skills").set_defaults(func=cmd_skills) + skill_sub.add_parser("validate", help="Validate canonical skills").set_defaults(func=cmd_skills) + skill_sync = skill_sub.add_parser("sync", help="Sync skills into adapter directories") + skill_sync.add_argument("--target", action="append", help="Target skill directory; repeatable") + skill_sync.set_defaults(func=cmd_skills) + + methods = sub.add_parser("methods", help="List and inspect research framework methods") + method_sub = methods.add_subparsers(dest="methods_cmd", required=True) + method_sub.add_parser("list", help="List research methods").set_defaults(func=cmd_methods) + method_show = method_sub.add_parser("show", help="Show one research method") + method_show.add_argument("method") + method_show.set_defaults(func=cmd_methods) + status = sub.add_parser("status", help="Show project status") status.add_argument("project", nargs="?", help="Project slug or path") status.set_defaults(func=cmd_status) + review = sub.add_parser("review", help="Run deterministic Phase 3 review") + review.add_argument("project", help="Project slug or path") + review.set_defaults(func=cmd_review) + prompt = sub.add_parser("prompt", help="Print a Codex command prompt template") prompt.add_argument("command", help="Command name, e.g. dr-frame or frame") prompt.add_argument("argument", nargs="?", help="Replacement for $ARGUMENTS") @@ -266,6 +734,12 @@ def build_parser() -> argparse.ArgumentParser: finalize = sub.add_parser("finalize", help="Run Phase 4 deterministic pipeline") finalize.add_argument("project", help="Project slug or path") + finalize.add_argument("--input", default="phase4/final_zh.md", help="Chinese Markdown source for default v0.20 finalization") + finalize.add_argument("--legacy-translate", action="store_true", help="Use legacy final_en -> translate -> polish pipeline") + finalize.add_argument("--polish", action="store_true", help="Run optional Chinese polish step before rendering") + finalize.add_argument("--report-engine", choices=["reportlab", "quarto"], default=None) + finalize.add_argument("--no-docx", action="store_true") + finalize.add_argument("--no-pdf", action="store_true") finalize.add_argument("--translate-workers", type=int, default=0) finalize.add_argument("--glossary-workers", type=int, default=4) finalize.add_argument("--polish-workers", type=int, default=0) @@ -295,6 +769,7 @@ def build_parser() -> argparse.ArgumentParser: metavar="ROLE=MODEL", help="Override one role model, repeatable", ) + models.add_argument("--probe", action="store_true", help="Send tiny health checks to resolved role models") models.add_argument("--json", action="store_true", help="Emit JSON") models.set_defaults(func=cmd_models) diff --git a/scripts/install_codex_adapter.py b/scripts/install_codex_adapter.py index 0805a62..e0e6873 100644 --- a/scripts/install_codex_adapter.py +++ b/scripts/install_codex_adapter.py @@ -1,61 +1,48 @@ #!/usr/bin/env python3 -"""Install the Codex native adapter files into hidden project directories. +"""Backward-compatible wrapper for deploying the Codex adapter. -The Codex desktop sandbox may block agent-created writes into `.codex` and -`.agents/skills`. Run this script locally from the repository root when that -happens. +v0.20 keeps Codex adapter templates in the repository, but deploys the usable +adapter files to a Codex home outside the checkout. """ from __future__ import annotations import argparse -import shutil +import sys from pathlib import Path - REPO_ROOT = Path(__file__).resolve().parent.parent -TEMPLATE_ROOT = REPO_ROOT / "codex_adapter_templates" / "codex" -CODEX_ROOT = REPO_ROOT / ".codex" -AGENTS_SKILLS = REPO_ROOT / ".agents" / "skills" -OPENCODE_SKILLS = REPO_ROOT / ".opencode" / "skills" +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) - -def copy_tree_contents(src: Path, dst: Path, *, force: bool) -> list[Path]: - written: list[Path] = [] - if not src.exists(): - raise SystemExit(f"template source not found: {src}") - dst.mkdir(parents=True, exist_ok=True) - for item in src.rglob("*"): - rel = item.relative_to(src) - target = dst / rel - if item.is_dir(): - target.mkdir(parents=True, exist_ok=True) - continue - if target.exists() and not force: - continue - target.parent.mkdir(parents=True, exist_ok=True) - shutil.copy2(item, target) - written.append(target) - return written +from scripts.deploy_adapters import deploy_codex, print_result def main() -> int: - parser = argparse.ArgumentParser(description="Install Codex native adapter") - parser.add_argument("--force", action="store_true", help="overwrite existing adapter files") - parser.add_argument("--skip-skills", action="store_true", help="do not copy .opencode/skills to .agents/skills") + parser = argparse.ArgumentParser(description="Deploy Codex native adapter") + parser.add_argument("--target", type=Path, help="Codex home target; defaults to $CODEX_HOME or ~/.codex") + parser.add_argument("--force", action="store_true", help="overwrite existing files and create .bak backups") + parser.add_argument("--skip-skills", action="store_true", help="do not copy canonical skills into target/skills") + parser.add_argument("--include-config", action="store_true", help="also copy config.toml; off by default to avoid overwriting global Codex config") + parser.add_argument("--dry-run", action="store_true", help="show files that would be written") args = parser.parse_args() - codex_written = copy_tree_contents(TEMPLATE_ROOT, CODEX_ROOT, force=args.force) - skills_written: list[Path] = [] - if not args.skip_skills: - skills_written = copy_tree_contents(OPENCODE_SKILLS, AGENTS_SKILLS, force=args.force) - - print("Codex adapter installed.") - print(f" .codex files written: {len(codex_written)}") - print(f" .agents skills files written: {len(skills_written)}") - if codex_written: - for path in codex_written: - print(f" {path.relative_to(REPO_ROOT)}") + result = deploy_codex( + target=args.target, + force=args.force, + skip_skills=args.skip_skills, + include_config=args.include_config, + dry_run=args.dry_run, + ) + print_result(result) + print() + print("Note: this no longer writes repository-local .codex files by default.") + print("Run Codex from this repository after deployment:") + if args.include_config: + print(" codex --profile deep-research") + else: + print(" codex") + print("Note: config.toml is not copied by default. Use --include-config only if you want the bundled profile.") return 0 diff --git a/scripts/lib/model_config.py b/scripts/lib/model_config.py index d82f188..aab3f33 100644 --- a/scripts/lib/model_config.py +++ b/scripts/lib/model_config.py @@ -47,7 +47,9 @@ def resolve_model_profile( if selected not in profiles: raise ModelConfigError(f"unknown model profile: {selected}") - roles = dict((profiles[selected] or {}).get("roles") or {}) + selected_profile = profiles[selected] or {} + roles = dict(selected_profile.get("roles") or {}) + task_types = dict(selected_profile.get("task_types") or defaults.get("task_types") or {}) if defaults.get("script_models"): for role, model in (defaults.get("script_models") or {}).items(): roles.setdefault(role, model) @@ -56,8 +58,9 @@ def resolve_model_profile( return { "profile": selected, - "description": (profiles[selected] or {}).get("description", ""), + "description": selected_profile.get("description", ""), "roles": roles, + "task_types": task_types, } diff --git a/scripts/lib/zenmux_client.py b/scripts/lib/zenmux_client.py index db2e124..9bc8b49 100644 --- a/scripts/lib/zenmux_client.py +++ b/scripts/lib/zenmux_client.py @@ -29,6 +29,35 @@ MAX_RETRIES = 5 RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504, 520, 524} +_ANTHROPIC_MODEL_ALIASES = { + "anthropic/claude-opus-4-7": "anthropic/claude-opus-4.7", + "anthropic/claude-opus-4-6": "anthropic/claude-opus-4.6", + "anthropic/claude-opus-4-5": "anthropic/claude-opus-4.5", + "anthropic/claude-opus-4-1": "anthropic/claude-opus-4.1", + "anthropic/claude-sonnet-4-6": "anthropic/claude-sonnet-4.6", + "anthropic/claude-sonnet-4-5": "anthropic/claude-sonnet-4.5", + "anthropic/claude-haiku-4-5": "anthropic/claude-haiku-4.5", +} +_MODELS_WITHOUT_TEMPERATURE = { + "anthropic/claude-opus-4.7", +} + + +def normalize_zenmux_model(model: str) -> str: + """Convert adapter-facing model IDs to ZenMux OpenAI API model IDs.""" + normalized = model.strip() + if normalized.startswith("zenmux-anthropic/"): + normalized = "anthropic/" + normalized.removeprefix("zenmux-anthropic/") + elif normalized.startswith("zenmux/"): + normalized = normalized.removeprefix("zenmux/") + return _ANTHROPIC_MODEL_ALIASES.get(normalized, normalized) + + +def model_accepts_temperature(model: str) -> bool: + """Return whether the ZenMux API accepts `temperature` for this model.""" + return normalize_zenmux_model(model) not in _MODELS_WITHOUT_TEMPERATURE + + @dataclass class UsageStats: """聚合一次脚本运行的 token 消耗。""" @@ -163,12 +192,14 @@ class ZenMuxClient: messages.extend(extra_messages) messages.append({"role": "user", "content": user}) + api_model = normalize_zenmux_model(model) body: dict[str, Any] = { - "model": model, + "model": api_model, "messages": messages, - "temperature": temperature, "max_tokens": max_tokens, } + if model_accepts_temperature(api_model): + body["temperature"] = temperature if web_search: body["web_search_options"] = web_search_options or {} headers = { @@ -200,14 +231,14 @@ class ZenMuxClient: raise ZenMuxError(f"invalid JSON from zenmux: {e}; body={resp.text[:500]}") usage = data.get("usage", {}) or {} with self._usage_lock: - self.usage.add(model, usage) + self.usage.add(api_model, usage) content = "" choices = data.get("choices") or [] if choices: msg = choices[0].get("message") or {} content = msg.get("content") or "" self._log({ - "tag": tag, "model": model, "attempt": attempt, + "tag": tag, "model": api_model, "requested_model": model, "attempt": attempt, "elapsed": round(elapsed, 2), "usage": usage, "out_chars": len(content), @@ -256,12 +287,14 @@ class ZenMuxClient: messages.extend(extra_messages) messages.append({"role": "user", "content": user}) + api_model = normalize_zenmux_model(model) body: dict[str, Any] = { - "model": model, + "model": api_model, "messages": messages, - "temperature": temperature, "max_tokens": max_tokens, } + if model_accepts_temperature(api_model): + body["temperature"] = temperature if web_search: body["web_search_options"] = web_search_options or {} @@ -309,7 +342,7 @@ class ZenMuxClient: usage = data.get("usage", {}) or {} with self._usage_lock: - self.usage.add(model, usage) + self.usage.add(api_model, usage) message = ((data.get("choices") or [{}])[0].get("message") or {}) content = message.get("content") or "" @@ -324,7 +357,8 @@ class ZenMuxClient: urls.append(url_item) self._log({ "tag": tag, - "model": model, + "model": api_model, + "requested_model": model, "attempt": attempt, "elapsed": round(elapsed, 2), "usage": usage, diff --git a/scripts/reporting/__init__.py b/scripts/reporting/__init__.py new file mode 100644 index 0000000..98bd27a --- /dev/null +++ b/scripts/reporting/__init__.py @@ -0,0 +1,2 @@ +"""Report rendering helpers for the v0.20 Python core.""" + diff --git a/scripts/reporting/fonts.py b/scripts/reporting/fonts.py new file mode 100644 index 0000000..b4ff70d --- /dev/null +++ b/scripts/reporting/fonts.py @@ -0,0 +1,32 @@ +"""Font resolution helpers for PDF rendering.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path + + +@dataclass(frozen=True) +class QuartoFonts: + main_font: str + sans_font: str + requires_system_fonts: bool + + +def resolve_quarto_fonts(fonts_dir: Path) -> QuartoFonts: + """Resolve Quarto font names. + + Quarto/xelatex currently uses installed font family names. We still accept + fonts_dir so callers can validate/report environment state consistently. + """ + expected = [ + fonts_dir / "SourceHanSerifSC-Regular.otf", + fonts_dir / "SourceHanSansSC-Bold.otf", + ] + requires_system_fonts = not all(path.exists() for path in expected) + return QuartoFonts( + main_font="Source Han Serif CN", + sans_font="Source Han Sans CN", + requires_system_fonts=requires_system_fonts, + ) + diff --git a/scripts/reporting/references.py b/scripts/reporting/references.py new file mode 100644 index 0000000..0f41cb8 --- /dev/null +++ b/scripts/reporting/references.py @@ -0,0 +1,61 @@ +"""Reference-list generation from Deep Research sources.jsonl.""" + +from __future__ import annotations + +import json +import re +from pathlib import Path + + +def cited_source_keys(md_text: str) -> set[str]: + return set(re.findall(r"\[src_([a-zA-Z0-9_-]+)\]", md_text)) + + +def build_references_block(sources_path: Path | None, md_text: str) -> str: + """Build a compact references section for actually cited src IDs.""" + if not sources_path or not sources_path.exists(): + return "（参考文献列表：sources.jsonl 未找到）" + + cited = cited_source_keys(md_text) + if not cited: + return "" + + sources: dict[str, dict] = {} + with sources_path.open(encoding="utf-8") as f: + for line in f: + line = line.strip() + if not line: + continue + try: + obj = json.loads(line) + except json.JSONDecodeError: + continue + sid = obj.get("id", "") + key = sid.replace("src_", "") + if key in cited: + sources[sid] = obj + + if not sources: + return "" + + lines = ["## 参考文献\n"] + for sid in sorted(sources.keys()): + s = sources[sid] + authors = ", ".join(s.get("authors", [])) if s.get("authors") else "" + year = s.get("year", "") + title = s.get("title", sid) + venue = s.get("venue", "") + url = s.get("url", "") + entry = f"- **[{sid}]** " + if authors: + entry += f"{authors}. " + if year: + entry += f"({year}). " + entry += f"*{title}*" + if venue: + entry += f". {venue}" + if url: + entry += f". <{url}>" + lines.append(entry) + return "\n".join(lines) + diff --git a/scripts/runtime/__init__.py b/scripts/runtime/__init__.py new file mode 100644 index 0000000..0419651 --- /dev/null +++ b/scripts/runtime/__init__.py @@ -0,0 +1,6 @@ +"""v0.20 Python runtime core for Deep Research. + +The runtime layer is intentionally platform-neutral: OpenCode, Codex, and +Claude Code should call into these modules instead of owning orchestration. +""" + diff --git a/scripts/runtime/artifacts.py b/scripts/runtime/artifacts.py new file mode 100644 index 0000000..e56c8d3 --- /dev/null +++ b/scripts/runtime/artifacts.py @@ -0,0 +1,46 @@ +"""Project artifact helpers shared by the Python runtime.""" + +from __future__ import annotations + +import json +from pathlib import Path +from typing import Any + + +REPO_ROOT = Path(__file__).resolve().parents[2] +PROJECTS_DIR = REPO_ROOT / "projects" + + +def resolve_project(project: str | Path) -> Path: + p = Path(project) + if p.is_dir(): + return p.resolve() + candidate = PROJECTS_DIR / str(project) + if candidate.is_dir(): + return candidate.resolve() + raise FileNotFoundError(f"project not found: {project}") + + +def load_manifest(project_root: Path) -> dict[str, Any]: + path = project_root / "manifest.json" + if not path.exists(): + raise FileNotFoundError(f"manifest not found: {path}") + return json.loads(path.read_text(encoding="utf-8")) + + +def write_manifest(project_root: Path, manifest: dict[str, Any]) -> None: + path = project_root / "manifest.json" + path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + + +def ensure_phase_dirs(project_root: Path) -> None: + for rel in ( + "phase1", + "phase2/drafts", + "phase2/evidence", + "phase2/packets", + "phase3", + "phase4", + ): + (project_root / rel).mkdir(parents=True, exist_ok=True) + diff --git a/scripts/runtime/assembly.py b/scripts/runtime/assembly.py new file mode 100644 index 0000000..da77078 --- /dev/null +++ b/scripts/runtime/assembly.py @@ -0,0 +1,202 @@ +"""Chapter brief aggregation and Chinese chapter assembly.""" + +from __future__ import annotations + +import json +import re +from concurrent.futures import ThreadPoolExecutor, as_completed +from pathlib import Path +from typing import Callable + +from scripts.runtime.roles import RoleDefinition, RuntimeProfile +from scripts.runtime.skills import SkillRegistry +from scripts.runtime.tasks import load_task_cards, validate_packet +from scripts.runtime.workers import ChatClient + + +def validate_chapter_brief(brief: dict) -> None: + required = { + "chapter_id", + "chapter_title", + "packet_ids", + "core_claims", + "evidence_items", + "counter_evidence", + "source_ids", + "open_questions", + "assembly_notes", + } + missing = sorted(required - set(brief)) + if missing: + raise ValueError(f"chapter brief missing fields: {missing}") + if not brief["chapter_id"]: + raise ValueError("chapter_id required") + if not brief["packet_ids"]: + raise ValueError("chapter brief requires at least one packet") + if not brief["core_claims"]: + raise ValueError("chapter brief requires core_claims") + if not brief["evidence_items"]: + raise ValueError("chapter brief requires evidence_items") + if not brief["counter_evidence"]: + raise ValueError("chapter brief requires counter_evidence") + + +def validate_chapter_markdown_citations(markdown: str, brief: dict) -> None: + validate_chapter_brief(brief) + cited = set(re.findall(r"\[(src_[A-Za-z0-9_-]+)\]", markdown)) + allowed = set(brief.get("source_ids") or []) + unknown = sorted(cited - allowed) + if unknown: + raise ValueError(f"unknown citation ids in {brief['chapter_id']}: {unknown}") + + +def _chapter_title_from_id(chapter_id: str) -> str: + try: + index = int(chapter_id.replace("ch", "")) + return f"第{index}章" + except ValueError: + return chapter_id + + +def build_chapter_briefs(project_root: Path) -> list[dict]: + cards = load_task_cards(project_root / "phase2" / "task_cards.json") + grouped: dict[str, list[tuple[str, dict]]] = {} + for card in cards: + packet_path = project_root / card.output_packet + if not packet_path.exists(): + continue + packet = json.loads(packet_path.read_text(encoding="utf-8")) + validate_packet(packet) + for chapter_id in card.chapter_ids: + grouped.setdefault(chapter_id, []).append((card.task_id, packet)) + + briefs: list[dict] = [] + out_dir = project_root / "phase2" / "chapter_briefs" + out_dir.mkdir(parents=True, exist_ok=True) + for chapter_id in sorted(grouped): + packet_pairs = sorted(grouped[chapter_id], key=lambda item: item[0]) + packet_ids = [item[0] for item in packet_pairs] + packets = [item[1] for item in packet_pairs] + source_ids = sorted({sid for packet in packets for sid in packet.get("source_ids", [])}) + brief = { + "chapter_id": chapter_id, + "chapter_title": _chapter_title_from_id(chapter_id), + "packet_ids": packet_ids, + "core_claims": [claim for packet in packets for claim in packet.get("claims", [])], + "evidence_items": [item for packet in packets for item in packet.get("evidence_items", [])], + "counter_evidence": [item for packet in packets for item in packet.get("counter_evidence", [])], + "source_ids": source_ids, + "open_questions": [q for packet in packets for q in packet.get("open_questions", [])], + "assembly_notes": [ + "用中文写正式章节，英文仅保留在必要的来源标题、原文摘录、DOI/URL 中。", + "避免碎片化：不要按 packet 逐段堆砌，要先提炼本章主线，再组织证据。", + "每个事实、数字和关键判断都必须保留 [src_xxx] 引用。", + "必须纳入 counter_evidence，并说明它如何影响结论置信度。", + ], + } + validate_chapter_brief(brief) + (out_dir / f"{chapter_id}.json").write_text( + json.dumps(brief, ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + briefs.append(brief) + return briefs + + +def build_chapter_user_prompt(brief: dict) -> str: + return ( + "请根据以下 chapter brief 写一章正式中文 Markdown 正文。\n" + "目标是形成一个完整章节，而不是 packet 摘要。避免碎片化，按金字塔结构组织：章首先给结论，再用证据支撑。\n" + "要求：标题必须是观点型判断；每个数字和事实保留 [src_xxx]；纳入反方证据；不要出现调度元数据。\n" + "禁止写空泛咨询腔。每个二级小节都必须至少落下 2 个具体审计发现、法规要求、SOP/记录/参数/现场观察或整改证据；不要只写原则。\n" + "正文末尾必须增加“证据落点与待补证据”小节，用表格列出：关键判断、已使用证据 source_id、已落地整改动作、仍缺证据。若证据不足，直接标注需回炉 Phase 2，不要用泛泛表述补齐。\n" + "只输出 Markdown，不要输出解释。\n\n" + f"{json.dumps(brief, ensure_ascii=False, indent=2)}" + ) + + +class ChapterAssemblyWorker: + def __init__( + self, + *, + role: RoleDefinition, + client: ChatClient, + skill_registry: SkillRegistry | None = None, + ) -> None: + self.role = role + self.client = client + self.skill_registry = skill_registry or SkillRegistry() + + def _system_prompt(self) -> str: + skill_texts = [] + for name in self.role.skills: + try: + skill_texts.append(f"# Skill: {name}\n\n{self.skill_registry.read(name)}") + except FileNotFoundError: + skill_texts.append(f"# Skill: {name}\n\n[missing skill: {name}]") + return ( + "你是 Deep Research v0.20 的中文章节组装 worker。\n" + "你的职责是把结构化证据包收束成连贯章节，解决并发研究造成的碎片化。\n" + "不得编造来源，不得删除关键反方证据。\n\n" + + "\n\n".join(skill_texts) + ) + + def write_chapter(self, *, project_root: Path, brief: dict) -> Path: + validate_chapter_brief(brief) + markdown = self.client.chat_complete( + model=self.role.model, + system=self._system_prompt(), + user=build_chapter_user_prompt(brief), + temperature=self.role.temperature, + max_tokens=self.role.max_tokens, + tag=f"chapter:{brief['chapter_id']}", + ) + validate_chapter_markdown_citations(markdown, brief) + out = project_root / "phase2" / "drafts" / f"{brief['chapter_id']}.md" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text(markdown.rstrip() + "\n", encoding="utf-8") + return out + + +def _write_chapter_error(project_root: Path, brief: dict, error: Exception) -> None: + path = project_root / "phase2" / "chapter_errors" / f"{brief.get('chapter_id', 'unknown')}.json" + path.parent.mkdir(parents=True, exist_ok=True) + payload = { + "chapter_id": brief.get("chapter_id"), + "status": "failed", + "error": str(error), + } + path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + + +def run_chapter_assembly_workers( + *, + project_root: Path, + briefs: list[dict], + runtime: RuntimeProfile, + client_factory: Callable[[RoleDefinition], ChatClient], + workers: int, +) -> int: + role = runtime.role_for_task("chapter_assembly") + max_workers = max(1, min(workers, role.max_concurrency)) + + def run_one(brief: dict) -> tuple[dict, Path | None, Exception | None]: + try: + worker = ChapterAssemblyWorker(role=role, client=client_factory(role)) + return brief, worker.write_chapter(project_root=project_root, brief=brief), None + except Exception as error: + return brief, None, error + + written = 0 + with ThreadPoolExecutor(max_workers=max_workers) as pool: + futures = [pool.submit(run_one, brief) for brief in briefs] + for future in as_completed(futures): + brief, path, error = future.result() + if error is not None: + _write_chapter_error(project_root, brief, error) + continue + if path is None: + _write_chapter_error(project_root, brief, RuntimeError("chapter worker returned no output path")) + continue + written += 1 + return written diff --git a/scripts/runtime/materials.py b/scripts/runtime/materials.py new file mode 100644 index 0000000..40442cf --- /dev/null +++ b/scripts/runtime/materials.py @@ -0,0 +1,229 @@ +"""Phase 0 user-provided material ingestion.""" + +from __future__ import annotations + +import base64 +import os +import shutil +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +import requests + + +DEFAULT_FIRERED_OCR_ENDPOINT = "http://192.168.50.100:8001" +DEFAULT_OCR_MAX_PAGES = 50 + + +@dataclass(frozen=True) +class OcrResult: + text: str + pages_processed: int + output_path: Path + + +def safe_filename(path: Path) -> str: + name = path.name.strip() + return name or "material" + + +def extract_pdf_text(path: Path) -> tuple[str, int, bool]: + from pypdf import PdfReader + + reader = PdfReader(str(path)) + chunks: list[str] = [] + for index, page in enumerate(reader.pages, start=1): + text = (page.extract_text() or "").strip() + if text: + chunks.append(f"\n\n## Page {index}\n\n{text}") + combined = "".join(chunks).strip() + ocr_required = len(combined) < max(20, len(reader.pages) * 20) + return combined, len(reader.pages), ocr_required + + +def ocr_endpoint_from_env() -> str: + return os.environ.get("DEEP_RESEARCH_OCR_ENDPOINT", DEFAULT_FIRERED_OCR_ENDPOINT).rstrip("/") + + +def ocr_max_pages_from_env() -> int: + raw = os.environ.get("DEEP_RESEARCH_OCR_MAX_PAGES") + if not raw: + return DEFAULT_OCR_MAX_PAGES + try: + return max(1, int(raw)) + except ValueError: + return DEFAULT_OCR_MAX_PAGES + + +def render_pdf_pages(pdf_path: Path, output_dir: Path, *, max_pages: int) -> list[Path]: + import fitz + + pages_dir = output_dir / f"{pdf_path.stem}.ocr-pages" + pages_dir.mkdir(parents=True, exist_ok=True) + image_paths: list[Path] = [] + doc = fitz.open(pdf_path) + try: + for index, page in enumerate(doc[:max_pages], start=1): + pix = page.get_pixmap(matrix=fitz.Matrix(2, 2), alpha=False) + image_path = pages_dir / f"page-{index:03d}.png" + pix.save(image_path) + image_paths.append(image_path) + finally: + doc.close() + return image_paths + + +def data_url_for_image(path: Path) -> str: + encoded = base64.b64encode(path.read_bytes()).decode("ascii") + return f"data:image/png;base64,{encoded}" + + +def call_firered_ocr(image_path: Path, *, endpoint: str) -> str: + payload = { + "model": "firered-ocr", + "messages": [ + { + "role": "user", + "content": [ + {"type": "text", "text": "请识别图片中的全部文字，保持原有顺序，只输出文字。"}, + {"type": "image_url", "image_url": {"url": data_url_for_image(image_path)}}, + ], + } + ], + "temperature": 0, + "max_tokens": 3000, + } + response = requests.post(f"{endpoint.rstrip('/')}/v1/chat/completions", json=payload, timeout=60) + if not response.ok: + raise RuntimeError(f"{response.status_code} {response.text[:500]}") + data = response.json() + return str(data["choices"][0]["message"].get("content") or "").strip() + + +def ocr_pdf_with_firered(*, pdf_path: Path, output_dir: Path, endpoint: str, max_pages: int) -> OcrResult: + image_paths = render_pdf_pages(pdf_path, output_dir, max_pages=max_pages) + chunks: list[str] = [] + for index, image_path in enumerate(image_paths, start=1): + text = call_firered_ocr(image_path, endpoint=endpoint) + if text: + chunks.append(f"\n\n## OCR Page {index}\n\n{text}") + combined = "".join(chunks).strip() + output_path = output_dir / f"{pdf_path.stem}.ocr.md" + body = [ + f"# OCR Material: {pdf_path.name}", + "", + f"- source_path: {pdf_path}", + f"- endpoint: {endpoint}", + f"- pages_processed: {len(image_paths)}", + "", + combined or "OCR 未返回可用文本。", + "", + ] + output_path.write_text("\n".join(body), encoding="utf-8") + return OcrResult(text=combined, pages_processed=len(image_paths), output_path=output_path) + + +def ingest_input_materials(project_root: Path, materials: list[str] | None) -> list[dict[str, Any]]: + inventory: list[dict[str, Any]] = [] + if not materials: + return inventory + + inputs_dir = project_root / "phase0" / "inputs" + extracted_dir = project_root / "phase0" / "extracted" + ocr_endpoint = ocr_endpoint_from_env() + ocr_max_pages = ocr_max_pages_from_env() + inputs_dir.mkdir(parents=True, exist_ok=True) + extracted_dir.mkdir(parents=True, exist_ok=True) + + for raw in materials: + source = Path(raw).expanduser() + if not source.exists(): + inventory.append({"kind": "note", "note": raw}) + continue + + copied = inputs_dir / safe_filename(source) + shutil.copy2(source, copied) + item: dict[str, Any] = { + "kind": source.suffix.lower().lstrip(".") or "file", + "source_path": str(source), + "copied_to": str(copied.relative_to(project_root)), + "size_bytes": source.stat().st_size, + } + + if source.suffix.lower() == ".pdf": + text, pages, ocr_required = extract_pdf_text(source) + extracted = extracted_dir / f"{source.stem}.md" + ocr_result: OcrResult | None = None + ocr_error: str | None = None + if ocr_required: + try: + ocr_result = ocr_pdf_with_firered( + pdf_path=source, + output_dir=extracted_dir, + endpoint=ocr_endpoint, + max_pages=min(pages, ocr_max_pages), + ) + if ocr_result.text: + text = "\n\n".join(part for part in [text, ocr_result.text] if part) + except Exception as exc: # noqa: BLE001 - ingestion should not block project init. + ocr_error = str(exc) + + body = [ + f"# Extracted Material: {source.name}", + "", + f"- source_path: {source}", + f"- copied_to: {copied.relative_to(project_root)}", + f"- pages: {pages}", + f"- ocr_required: {str(ocr_required).lower()}", + f"- ocr_status: {'completed' if ocr_result else 'failed' if ocr_error else 'not_required'}", + "", + text or "未能从 PDF 直接抽取文本；该材料可能需要 OCR。", + "", + ] + if ocr_error: + body.extend(["## OCR Error", "", ocr_error, ""]) + extracted.write_text("\n".join(body), encoding="utf-8") + item.update( + { + "pages": pages, + "extracted_to": str(extracted.relative_to(project_root)), + "text_chars": len(text), + "ocr_required": ocr_required, + "ocr_status": "completed" if ocr_result else "failed" if ocr_error else "not_required", + } + ) + if ocr_result: + item.update( + { + "ocr_endpoint": ocr_endpoint, + "ocr_pages_processed": ocr_result.pages_processed, + "ocr_extracted_to": str(ocr_result.output_path.relative_to(project_root)), + "ocr_text_chars": len(ocr_result.text), + } + ) + if ocr_error: + item["ocr_error"] = ocr_error + else: + item["ocr_required"] = source.suffix.lower() in {".png", ".jpg", ".jpeg", ".tif", ".tiff"} + inventory.append(item) + + return inventory + + +def render_material_inventory(inventory: list[dict[str, Any]]) -> str: + if not inventory: + return "- 暂无；可通过 `--input-material` 加入审计报告、问题清单或内部记录。" + lines: list[str] = [] + for item in inventory: + if item.get("kind") == "note": + lines.append(f"- 备注：{item.get('note', '')}") + continue + marker = "；需要 OCR" if item.get("ocr_required") else "" + ocr = f"；OCR：{item.get('ocr_status')}" if item.get("ocr_status") else "" + extracted = item.get("extracted_to") + extra = f"；抽取文本：{extracted}" if extracted else "" + lines.append( + f"- {item.get('copied_to')}（{item.get('kind')}，{item.get('size_bytes', 0)} bytes{extra}{marker}{ocr}）" + ) + return "\n".join(lines) diff --git a/scripts/runtime/methods.py b/scripts/runtime/methods.py new file mode 100644 index 0000000..6d5c1fc --- /dev/null +++ b/scripts/runtime/methods.py @@ -0,0 +1,60 @@ +"""Research method registry for Phase 1 framework selection.""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +import yaml + + +REPO_ROOT = Path(__file__).resolve().parents[2] +DEFAULT_METHOD_CONFIG = REPO_ROOT / "configs" / "research_methods.yaml" + + +@dataclass(frozen=True) +class ResearchMethod: + key: str + name: str + best_for: list[str] + structure_principle: str + task_axes: list[str] + framework_sections: list[str] + + +class ResearchMethodRegistry: + def __init__(self, path: Path | None = None) -> None: + self.path = path or DEFAULT_METHOD_CONFIG + self._data = self._load() + + def _load(self) -> dict[str, Any]: + if not self.path.exists(): + raise FileNotFoundError(f"research method config not found: {self.path}") + data = yaml.safe_load(self.path.read_text(encoding="utf-8")) or {} + if not isinstance(data, dict) or "methods" not in data: + raise ValueError(f"invalid research method config: {self.path}") + return data + + @property + def default_method(self) -> str: + return (self._data.get("defaults") or {}).get("method", "mckinsey_market") + + def list_names(self) -> list[str]: + return sorted((self._data.get("methods") or {}).keys()) + + def get(self, key: str | None = None) -> ResearchMethod: + selected = key or self.default_method + methods = self._data.get("methods") or {} + if selected not in methods: + raise KeyError(f"unknown research_method: {selected}") + item = methods[selected] or {} + return ResearchMethod( + key=selected, + name=item.get("name", selected), + best_for=list(item.get("best_for") or []), + structure_principle=item.get("structure_principle", ""), + task_axes=list(item.get("task_axes") or []), + framework_sections=list(item.get("framework_sections") or []), + ) + diff --git a/scripts/runtime/orchestrator.py b/scripts/runtime/orchestrator.py new file mode 100644 index 0000000..001b8d8 --- /dev/null +++ b/scripts/runtime/orchestrator.py @@ -0,0 +1,79 @@ +"""Deterministic orchestration helpers for v0.20.""" + +from __future__ import annotations + +import json +from datetime import datetime, timezone +from pathlib import Path + +from scripts.runtime.artifacts import ensure_phase_dirs, load_manifest, write_manifest +from scripts.runtime.methods import ResearchMethodRegistry +from scripts.runtime.tasks import generate_task_cards, write_task_cards + + +def utc_now_iso() -> str: + return datetime.now(timezone.utc).replace(microsecond=0).isoformat() + + +def create_phase2_task_cards( + project_root: Path, + *, + axes: list[str] | None = None, + dry_run: bool = False, +) -> list[dict[str, object]]: + framework = project_root / "phase1" / "framework.md" + if not framework.exists(): + raise FileNotFoundError(f"framework not found: {framework}") + method_key = None + if (project_root / "manifest.json").exists(): + method_key = load_manifest(project_root).get("research_method") + method = ResearchMethodRegistry().get(method_key) + cards = generate_task_cards(project_root.name, framework.read_text(encoding="utf-8"), axes=axes, method=method) + if not dry_run: + ensure_phase_dirs(project_root) + write_task_cards(project_root / "phase2" / "task_cards.json", cards) + manifest = load_manifest(project_root) + phase2 = manifest.setdefault("phase2", {}) + phase2.update( + { + "status": "in_progress", + "runtime": "python-core-v0.20", + "research_method": method.key, + "task_cards_path": "phase2/task_cards.json", + "task_cards_total": len(cards), + "updated_at": utc_now_iso(), + } + ) + write_manifest(project_root, manifest) + return [card.to_dict() for card in cards] + + +def write_placeholder_packets( + project_root: Path, + task_cards: list[dict[str, object]], + *, + dry_run: bool = False, +) -> int: + """Create packet skeletons for manual/API completion. + + This keeps the first v0.20 implementation deterministic and resumable; LLM + calls can later fill the same schema without changing downstream readers. + """ + count = 0 + for card in task_cards: + packet_path = project_root / str(card["output_packet"]) + packet = { + "task_id": card["task_id"], + "claims": [], + "evidence_items": [], + "counter_evidence": [], + "source_ids": [], + "source_quality_notes": [], + "open_questions": ["待由 Python role worker 调用模型补全。"], + "raw_quotes_or_notes": [], + } + if not dry_run: + packet_path.parent.mkdir(parents=True, exist_ok=True) + packet_path.write_text(json.dumps(packet, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + count += 1 + return count diff --git a/scripts/runtime/phase1.py b/scripts/runtime/phase1.py new file mode 100644 index 0000000..8e5ccfb --- /dev/null +++ b/scripts/runtime/phase1.py @@ -0,0 +1,341 @@ +"""Phase 1 project initialization and framework generation.""" + +from __future__ import annotations + +import hashlib +import re +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +from scripts.runtime.artifacts import PROJECTS_DIR, ensure_phase_dirs, load_manifest, write_manifest +from scripts.runtime.materials import ingest_input_materials, render_material_inventory +from scripts.runtime.methods import ResearchMethod, ResearchMethodRegistry + + +def utc_now_iso() -> str: + return datetime.now(timezone.utc).replace(microsecond=0).isoformat() + + +def slugify_topic(topic: str) -> str: + slug = re.sub(r"[^a-zA-Z0-9]+", "-", topic.lower()).strip("-") + if slug: + return slug[:80] + digest = hashlib.sha1(topic.encode("utf-8")).hexdigest()[:8] + return f"research-{digest}" + + +def create_project( + *, + topic: str, + slug: str | None = None, + projects_dir: Path = PROJECTS_DIR, + method_key: str | None = None, + report_type: str = "research", + model_profile: str = "medium", + target_words: int = 30000, + input_materials: list[str] | None = None, +) -> Path: + method = ResearchMethodRegistry().get(method_key) + project_slug = slug or slugify_topic(topic) + project_root = projects_dir / project_slug + if project_root.exists(): + raise FileExistsError(f"project already exists: {project_root}") + ensure_phase_dirs(project_root) + (project_root / "phase0" / "inputs").mkdir(parents=True, exist_ok=True) + (project_root / "phase0" / "extracted").mkdir(parents=True, exist_ok=True) + material_inventory = ingest_input_materials(project_root, input_materials) + now = utc_now_iso() + manifest: dict[str, Any] = { + "version": "0.20.0", + "runtime": "python-core-v0.20", + "topic": topic, + "slug": project_slug, + "report_title": topic, + "type": report_type, + "work_language": "zh", + "model_profile": model_profile, + "research_method": method.key, + "target_words": target_words, + "input_materials": input_materials or [], + "material_inventory": material_inventory, + "created_at": now, + "updated_at": now, + "phase1": { + "status": "initialized", + "approved": False, + "requires_user_interview": True, + "material_brief_path": "phase1/material_brief.md", + }, + "phase2": {"status": "pending"}, + "phase3": {"status": "pending"}, + "phase4": {"status": "pending"}, + } + write_manifest(project_root, manifest) + _write_interview_seed(project_root, manifest, method) + write_material_brief(project_root, manifest, method) + return project_root + + +def _write_interview_seed(project_root: Path, manifest: dict[str, Any], method: ResearchMethod) -> None: + material_text = render_material_inventory(manifest.get("material_inventory") or []) + text = ( + f"# Phase 1 访谈记录\n\n" + f"- 主题：{manifest['topic']}\n" + f"- 研究方法：{method.key} - {method.name}\n" + f"- 报告类型：{manifest['type']}\n" + f"- 目标字数：{manifest['target_words']}\n" + f"- 工作语言：中文主写作；检索关键词、证据摘录和来源笔记可保留英文。\n\n" + f"## 已提供材料\n\n{material_text}\n\n" + "## 后续访谈问题\n\n" + "1. 本报告最重要的决策用途是什么？\n" + "2. 是否有必须覆盖或必须排除的公司、产品、工艺、市场或法规范围？\n" + "3. 结论偏好是战略建议、风险清单、投资判断，还是执行路线图？\n" + ) + (project_root / "phase1" / "interview.md").write_text(text, encoding="utf-8") + + +def _material_excerpt(project_root: Path, rel_path: str, *, max_chars: int = 1200) -> str: + path = project_root / rel_path + if not path.exists(): + return "（未找到抽取文本）" + text = path.read_text(encoding="utf-8") + compact = "\n".join(line.rstrip() for line in text.splitlines() if line.strip()) + return compact[:max_chars] + ("..." if len(compact) > max_chars else "") + + +def _derive_material_observations(project_root: Path, inventory: list[dict[str, Any]]) -> list[str]: + combined_parts: list[str] = [] + for item in inventory: + rel = item.get("ocr_extracted_to") or item.get("extracted_to") + if rel and (project_root / rel).exists(): + combined_parts.append((project_root / rel).read_text(encoding="utf-8")) + text = "\n".join(combined_parts) + checks = [ + ("审计范围覆盖生产管理、原液、制剂和无菌相关模块，报告需要同时处理 GMP 合规、工艺转移和运营协同，而不是只写质量体系。", ["生产管理", "原液", "制剂", "无菌"]), + ("材料显示高风险项为 0、中风险项为 1，适合采用“商业化 readiness 与系统成熟度差距”而非“体系失控”作为初始假设。", ["高风险 0", "中风险1", "低风险7"]), + ("商业化经验、无菌保障细节、文件要求与执行一致性是需要访谈确认的主线风险。", ["商业化经验不足", "无菌保障", "文件要求与执行一致性"]), + ("工艺规程、批记录、CPP/CQA、VMPR/VMP、验证主计划等内容反复出现，说明工艺验证和商业化文件体系可能是 Phase 2 的重点证据轴。", ["CPP", "CQA", "VMPR", "VMP"]), + ("温度、压差、WFI、冷却段微生物、RABS/ORABS、first air、APS 等无菌和设施细节需要映射到 EU Annex 1、NMPA GMP 和企业 SOP。", ["温度", "压差", "WFI", "APS"]), + ("复盘材料包含责任人和局部答复，后续整改路线图应尽量回填 owner、期限、关闭证据和复核机制。", ["填写人", "是否已经回答完整", "整改"]), + ] + observations = [message for message, needles in checks if any(needle in text for needle in needles)] + return observations or ["材料已导入但尚未形成足够结构化判断；需要先访谈确认研究用途、范围和优先级。"] + + +def write_material_brief( + project_root: Path, + manifest: dict[str, Any] | None = None, + method: ResearchMethod | None = None, +) -> Path: + """Write a Phase 0/1 material brief that must be reviewed before Phase 2.""" + manifest = manifest or load_manifest(project_root) + method = method or ResearchMethodRegistry().get(manifest.get("research_method")) + inventory = manifest.get("material_inventory") or [] + lines = [ + f"# Phase 0 材料简报：{manifest.get('topic', project_root.name)}", + "", + "status: 待用户确认", + f"research_method: {method.key}", + "", + "## 已导入材料", + "", + render_material_inventory(inventory), + "", + "## 材料初步解读", + "", + "以下内容由 Python core 从已落盘材料抽样生成，只作为访谈起点；不得直接视为最终结论。", + "", + ] + lines.extend(["## 初步问题聚类（待访谈确认）", ""]) + for observation in _derive_material_observations(project_root, inventory): + lines.append(f"- {observation}") + lines.append("") + lines.append("## 材料摘录") + lines.append("") + for item in inventory: + rel = item.get("ocr_extracted_to") or item.get("extracted_to") + if not rel: + continue + lines.extend( + [ + f"### {Path(rel).name}", + "", + _material_excerpt(project_root, rel), + "", + ] + ) + lines.extend( + [ + "## 建议访谈确认点", + "", + "1. 本报告的最重要用途是什么：内部整改、客户沟通、董事会决策，还是外部审计准备？", + "2. 哪些审计发现最需要优先展开：无菌保障、工艺验证、数据完整性、质量体系闭环，还是运营协同？", + "3. 是否存在必须排除或脱敏的项目、人员、客户、产品或工艺信息？", + "4. 短中长期整改的时间边界如何定义，例如 30/90/180 天，还是按临床/商业化里程碑划分？", + "5. 是否需要把 NMPA、FDA、EMA、ICH、WHO 的法规基线分别映射到整改责任人和证据包？", + "", + "## Gate", + "", + "请用户确认本材料简报与访谈问题后，再生成或批准 `phase1/framework.md` 并进入 Phase 2。", + "", + ] + ) + out = project_root / "phase1" / "material_brief.md" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text("\n".join(lines), encoding="utf-8") + return out + + +CHAPTER_TEMPLATES: dict[str, list[str]] = { + "mckinsey_market": [ + "核心结论先行界定市场机会与约束", + "临床与真实世界证据决定需求天花板", + "监管路径和支付环境重塑商业化节奏", + "竞争格局正在从单点产品转向组合能力", + "专利与技术壁垒决定长期利润池", + "中国市场的准入和供给能力形成独立变量", + "资本市场预期与基本面之间存在可验证偏差", + "反方证据限定结论边界并提示回撤风险", + "战略选择应围绕资源约束排序", + "执行路线图需要把证据缺口转化为行动清单", + ], + "gmp_gap_assessment": [ + "监管基线决定整改范围而非企业主观偏好", + "现状差距需要按法规条款和业务流程双重定位", + "质量风险分级决定 CAPA 优先级", + "根因分析质量决定整改能否闭环", + "CAPA 设计必须绑定责任人、证据和期限", + "验证计划决定整改是否可被审计接受", + "供应商和外包管理常是系统性缺口放大器", + "数据完整性风险需要独立成章处理", + "实施路线图需要平衡停线风险与合规风险", + "管理层治理机制决定整改能否持续", + ], + "cmc_process_risk": [ + "工艺流程图是识别放大风险的起点", + "CQA 与 CPP 的映射决定控制策略质量", + "放大过程的失效模式集中在传质、混合和稳定性", + "分析方法和放行标准决定证据可信度", + "技术转移风险来自知识隐性化和现场差异", + "供应链约束会改变工艺控制边界", + "偏差和变更管理决定商业化后的韧性", + "监管沟通策略需要提前固化关键假设", + "反方证据限定平台工艺可复制性", + "CMC 路线图需要把风险转化为验证实验", + ], + "rd_go_no_go": [ + "科学假设强度决定项目是否值得进入下一阶段", + "POC 证据需要同时证明有效性和可转化性", + "安全性窗口决定适应症与人群选择", + "IP 与 FTO 风险决定商业化自由度", + "开发路径需要把关键不确定性前置验证", + "竞争窗口决定速度是否仍有战略价值", + "CMC 与临床运营能力影响真实可行性", + "反方证据决定 go/no-go 阈值", + "投资强度应与证据成熟度匹配", + "决策门槛需要形成可执行检查表", + ], + "management_consulting": [ + "现状诊断需要区分症状、根因和约束条件", + "能力差距决定组织改进优先级", + "流程断点揭示跨部门协作成本", + "治理结构决定决策速度和责任清晰度", + "运营模型需要匹配战略目标而非照搬标杆", + "数字化工具只有嵌入流程才产生价值", + "绩效指标需要避免局部最优", + "变革阻力本身是方案设计输入", + "路线图需要把 quick wins 与系统建设分层", + "落地机制决定咨询建议能否转化为成果", + ], + "gmp_quality_operations_diagnosis": [ + "现场审计发现需要先转化为可验证的系统性问题图谱", + "法规基线决定质量体系差距的严重度与整改边界", + "生产工艺体系风险来自流程、设施、公用系统和验证证据的耦合缺口", + "偏差、变更、CAPA 和数据完整性决定质量系统能否闭环", + "人员能力与质量文化决定制度是否真正落地", + "运营管理问题需要区分组织、流程、会议机制和指标体系缺口", + "跨部门协同断点会放大 GMP 风险和交付风险", + "标杆实践应转化为短中长期整改组合而非口号", + "整改路线图必须绑定责任、优先级、证据和复核机制", + "管理层治理机制决定白帆能否从一次整改转向持续改进", + ], +} + + +def render_framework(project_root: Path, *, method_key: str | None = None, chapter_count: int = 10) -> Path: + manifest = load_manifest(project_root) + registry = ResearchMethodRegistry() + method = registry.get(method_key or manifest.get("research_method")) + if method_key: + manifest["research_method"] = method.key + titles = CHAPTER_TEMPLATES.get(method.key) or CHAPTER_TEMPLATES["mckinsey_market"] + chapter_count = max(8, min(15, chapter_count)) + selected = titles[:chapter_count] + quota = max(800, int(manifest.get("target_words", 30000)) // len(selected)) + sections = "\n".join(f"- {item}" for item in method.framework_sections) + axes = "、".join(method.task_axes) + material_text = render_material_inventory(manifest.get("material_inventory") or []) + lines = [ + f"# {manifest.get('report_title') or manifest['topic']}：研究框架", + "", + f"research_method: {method.key}", + f"method_name: {method.name}", + f"work_language: 中文主写作；检索关键词、证据摘录、source title、raw notes 可保留英文。", + f"target_words: {manifest.get('target_words', 30000)}", + "", + "## 方法选择", + "", + f"本项目采用 `{method.key}`，因为其结构原则是：{method.structure_principle}", + "", + "框架模块：", + sections, + "", + "Phase 2 任务轴：", + f"- {axes}", + "", + "## 输入材料与使用边界", + "", + material_text, + "", + "这些材料作为现场问题线索和内部事实起点使用；正式结论仍需结合 NMPA、FDA、EMA、ICH、WHO 等权威法规、指南和最佳实践进行验证。", + "", + "## 中心假设", + "", + f"围绕“{manifest['topic']}”形成可被证据支持或证伪的中文主线；所有核心判断必须绑定来源 ID。", + "", + ] + for idx, title in enumerate(selected, start=1): + lines.extend( + [ + f"## 第{idx}章 {title}", + "", + f"建议字数：约 {quota} 字。", + f"研究思路：围绕 `{method.key}` 的方法框架，从 {axes} 等任务轴并发收集 evidence packet，再由 chapter assembly 收束为完整中文章节。", + "证据要求：至少 2 个独立 Tier 1-2 信源；不足时在正文标注待验证；必须包含反方证据。", + "", + ] + ) + lines.extend( + [ + "## 暂停点", + "", + "请先确认 `phase1/material_brief.md` 的材料解读和访谈问题，再确认本框架后进入 Phase 2。若章节逻辑、方法框架或字数配额需要调整，应先修改本文件。", + "", + "确认后运行：`uv run python scripts/dr.py approve <project>`；未批准时 `research` 默认会拒绝推进，可用 `--force` 临时覆盖。", + "", + ] + ) + out = project_root / "phase1" / "framework.md" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text("\n".join(lines), encoding="utf-8") + manifest["phase1"] = { + "status": "completed", + "approved": False, + "framework_path": "phase1/framework.md", + "research_method": method.key, + "updated_at": utc_now_iso(), + } + manifest["updated_at"] = utc_now_iso() + write_manifest(project_root, manifest) + return out diff --git a/scripts/runtime/review.py b/scripts/runtime/review.py new file mode 100644 index 0000000..97f7566 --- /dev/null +++ b/scripts/runtime/review.py @@ -0,0 +1,157 @@ +"""Deterministic Phase 3 review checks for the Python core.""" + +from __future__ import annotations + +import json +import re +from datetime import datetime, timezone +from pathlib import Path +from typing import Any + +from scripts.runtime.artifacts import load_manifest, write_manifest +from scripts.runtime.tasks import validate_packet + + +def utc_now_iso() -> str: + return datetime.now(timezone.utc).replace(microsecond=0).isoformat() + + +def _source_ids_from_jsonl(path: Path) -> set[str]: + ids: set[str] = set() + if not path.exists(): + return ids + for line in path.read_text(encoding="utf-8").splitlines(): + if not line.strip(): + continue + try: + obj = json.loads(line) + except json.JSONDecodeError: + continue + source_id = obj.get("id") or obj.get("source_id") + if source_id: + ids.add(str(source_id)) + return ids + + +def _draft_citations(drafts: list[Path]) -> set[str]: + cited: set[str] = set() + for draft in drafts: + cited.update(re.findall(r"\[(src_[A-Za-z0-9_-]+)\]", draft.read_text(encoding="utf-8"))) + return cited + + +def _ready_packet_stems(project_root: Path) -> set[str]: + ready: set[str] = set() + for path in sorted((project_root / "phase2" / "packets").glob("*.json")): + try: + packet = json.loads(path.read_text(encoding="utf-8")) + validate_packet(packet) + except Exception: + continue + ready.add(path.stem) + return ready + + +def _draft_quality_findings(drafts: list[Path]) -> list[dict[str, Any]]: + findings: list[dict[str, Any]] = [] + generic_markers = [ + "需要进一步完善", + "应当加强", + "持续改进", + "系统性", + "闭环管理", + "质量文化", + ] + for draft in drafts: + text = draft.read_text(encoding="utf-8") + zh_chars = sum(1 for char in text if "\u4e00" <= char <= "\u9fff") + citations = re.findall(r"\[(src_[A-Za-z0-9_-]+)\]", text) + evidence_table_present = "证据落点" in text and "待补证据" in text + if zh_chars >= 1200 and len(set(citations)) < 5: + findings.append({"severity": "P1", "message": f"{draft.name} 引用来源过少，可能未充分使用 evidence packet。"}) + if zh_chars >= 1200 and not evidence_table_present: + findings.append({"severity": "P1", "message": f"{draft.name} 缺少“证据落点与待补证据”小节，难以判断 evidence 是否真正落到纸面。"}) + generic_count = sum(text.count(marker) for marker in generic_markers) + if zh_chars >= 1200 and generic_count >= 18: + findings.append({"severity": "P1", "message": f"{draft.name} 泛化管理表述过多，需要回炉为具体审计发现、风险影响和整改动作。"}) + return findings + + +def build_phase3_critique(project_root: Path) -> Path: + manifest = load_manifest(project_root) + drafts = sorted((project_root / "phase2" / "drafts").glob("ch*.md")) + packets = sorted((project_root / "phase2" / "packets").glob("*.json")) + ready_stems = _ready_packet_stems(project_root) + packet_errors = [ + path for path in sorted((project_root / "phase2" / "packet_errors").glob("*.json")) + if path.stem not in ready_stems + ] + chapter_errors = sorted((project_root / "phase2" / "chapter_errors").glob("*.json")) + sources = _source_ids_from_jsonl(project_root / "phase2" / "sources.jsonl") + cited = _draft_citations(drafts) + missing_sources = sorted(cited - sources) if sources else sorted(cited) + uncited_sources = sorted(sources - cited) if cited else sorted(sources) + + findings: list[dict[str, Any]] = [] + if not drafts: + findings.append({"severity": "P1", "message": "Phase 2 drafts 缺失，尚不能进入 Phase 4 成稿。"}) + if packet_errors: + findings.append({"severity": "P1", "message": f"存在 {len(packet_errors)} 个 packet 失败，需要回炉补证据。"}) + if chapter_errors: + findings.append({"severity": "P1", "message": f"存在 {len(chapter_errors)} 个章节组装失败，需要修复引用或重写该章。"}) + quality_holds = manifest.get("quality_holds") or [] + if quality_holds: + findings.append({"severity": "P1", "message": "存在质量暂停标记：" + ", ".join(quality_holds)}) + findings.extend(_draft_quality_findings(drafts)) + if missing_sources: + findings.append({"severity": "P1", "message": f"正文引用未在 sources.jsonl 中登记：{', '.join(missing_sources)}"}) + if not findings: + findings.append({"severity": "P2", "message": "基础产物完整；仍需人工或大上下文模型审校逻辑链、反方证据和章节叙事。"}) + + lines = [ + "# Phase 3 审校 critique", + "", + f"- 项目：{manifest.get('topic', project_root.name)}", + f"- 运行时：python-core-v0.20", + f"- drafts：{len(drafts)}", + f"- packets：{len(packets)}", + f"- sources：{len(sources)}", + f"- cited_source_ids：{', '.join(sorted(cited)) if cited else '无'}", + "", + "## Findings", + "", + ] + for item in findings: + lines.append(f"- [{item['severity']}] {item['message']}") + lines.extend( + [ + "", + "## Residual Risks", + "", + "- 本 deterministic review 只做结构、引用和错误包检查；深层逻辑审校仍建议交给 `phase3_review` 角色执行。", + "- 若 sources 为空，本审校会把所有正文引用视为待登记来源。", + "", + "## Next", + "", + "- 若存在 P1，先回到 Phase 2 修复 packet/chapter 错误。", + "- 若仅有 P2，可进入 `dr.py finalize` 的中文原生成稿路径。", + "", + ] + ) + out = project_root / "phase3" / "critique.md" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text("\n".join(lines), encoding="utf-8") + phase3 = manifest.setdefault("phase3", {}) + phase3.update( + { + "status": "completed", + "critique_path": "phase3/critique.md", + "findings_total": len(findings), + "missing_sources": missing_sources, + "uncited_sources": uncited_sources, + "updated_at": utc_now_iso(), + } + ) + manifest["updated_at"] = utc_now_iso() + write_manifest(project_root, manifest) + return out diff --git a/scripts/runtime/roles.py b/scripts/runtime/roles.py new file mode 100644 index 0000000..50074b1 --- /dev/null +++ b/scripts/runtime/roles.py @@ -0,0 +1,111 @@ +"""Runtime role and task-model resolution.""" + +from __future__ import annotations + +from dataclasses import dataclass + +from scripts.lib.model_config import resolve_model_profile + + +ROLE_DEFAULTS = { + "dr_plan": { + "skills": ["document-ingest", "search-gateway", "search-strategy", "source-quality", "length-budget", "mckinsey-method"], + "temperature": 0.4, + "max_tokens": 12000, + "max_concurrency": 1, + }, + "dr_pm": { + "skills": ["length-budget", "evidence-table", "mckinsey-method"], + "temperature": 0.2, + "max_tokens": 8000, + "max_concurrency": 1, + }, + "dr_searcher": { + "skills": ["search-gateway", "search-strategy", "source-quality"], + "temperature": 0.1, + "max_tokens": 6000, + "max_concurrency": 6, + }, + "dr_analyst": { + "skills": ["search-gateway", "search-strategy", "source-quality", "evidence-table", "mckinsey-method"], + "temperature": 0.3, + "max_tokens": 14000, + "max_concurrency": 6, + }, + "dr_verifier": { + "skills": ["search-gateway", "search-strategy", "source-quality", "evidence-table"], + "temperature": 0.2, + "max_tokens": 10000, + "max_concurrency": 4, + }, + "dr_chief_editor": { + "skills": ["mckinsey-method", "evidence-table", "output-hygiene"], + "temperature": 0.2, + "max_tokens": 16000, + "max_concurrency": 1, + }, + "dr_editor_in_chief": { + "skills": ["mckinsey-method", "citation-manager", "humanizer-cn", "output-hygiene"], + "temperature": 0.4, + "max_tokens": 20000, + "max_concurrency": 1, + }, + "dr_reporter": { + "skills": ["pdf-reportlab", "citation-manager", "output-hygiene"], + "temperature": 0.1, + "max_tokens": 6000, + "max_concurrency": 1, + }, +} + + +@dataclass(frozen=True) +class RoleDefinition: + name: str + model: str + skills: list[str] + temperature: float + max_tokens: int + max_concurrency: int + + +class RuntimeProfile: + def __init__(self, *, profile: str, roles: dict[str, RoleDefinition], task_types: dict[str, str]) -> None: + self.profile = profile + self.roles = roles + self.task_types = task_types + + def role_for_task(self, task_type: str) -> RoleDefinition: + role_name = self.task_types.get(task_type) + if not role_name: + raise KeyError(f"unknown task_type: {task_type}") + if role_name not in self.roles: + raise KeyError(f"task_type {task_type} maps to missing role {role_name}") + return self.roles[role_name] + + +def resolve_runtime_profile( + *, + profile: str | None = None, + overrides: dict[str, str] | None = None, +) -> RuntimeProfile: + resolved = resolve_model_profile(profile=profile, overrides=overrides) + role_models = resolved["roles"] + roles: dict[str, RoleDefinition] = {} + for name, defaults in ROLE_DEFAULTS.items(): + model = role_models.get(name) + if not model: + continue + roles[name] = RoleDefinition( + name=name, + model=model, + skills=list(defaults["skills"]), + temperature=float(defaults["temperature"]), + max_tokens=int(defaults["max_tokens"]), + max_concurrency=int(defaults["max_concurrency"]), + ) + return RuntimeProfile( + profile=resolved["profile"], + roles=roles, + task_types=dict(resolved.get("task_types") or {}), + ) diff --git a/scripts/runtime/skills.py b/scripts/runtime/skills.py new file mode 100644 index 0000000..28acc6a --- /dev/null +++ b/scripts/runtime/skills.py @@ -0,0 +1,107 @@ +"""Canonical skill registry and adapter sync helpers.""" + +from __future__ import annotations + +import shutil +from dataclasses import dataclass +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parents[2] +CANONICAL_SKILLS_DIR = REPO_ROOT / ".agents" / "skills" +PROJECT_SKILLS_DIR = REPO_ROOT / "skills" +REQUIRED_SKILLS = { + "search-strategy", + "search-gateway", + "source-quality", + "length-budget", + "evidence-table", + "citation-manager", + "mckinsey-method", +} + + +@dataclass(frozen=True) +class SkillInfo: + name: str + path: Path + + +class SkillRegistry: + """Reads skills from the canonical cross-adapter registry.""" + + def __init__(self, canonical_dir: Path | None = None) -> None: + self.canonical_dir = canonical_dir or CANONICAL_SKILLS_DIR + + def roots(self) -> list[Path]: + roots = [self.canonical_dir] + if self.canonical_dir == CANONICAL_SKILLS_DIR and PROJECT_SKILLS_DIR.exists(): + roots.append(PROJECT_SKILLS_DIR) + return roots + + def list(self) -> list[SkillInfo]: + seen: set[str] = set() + out: list[SkillInfo] = [] + for root in self.roots(): + if not root.exists(): + continue + for path in sorted(root.glob("*/SKILL.md")): + name = path.parent.name + if name in seen: + continue + seen.add(name) + out.append(SkillInfo(name=name, path=path)) + return out + + def list_names(self) -> list[str]: + return [item.name for item in self.list()] + + def read(self, name: str) -> str: + for root in self.roots(): + path = root / name / "SKILL.md" + if path.exists(): + return path.read_text(encoding="utf-8") + raise FileNotFoundError(f"skill not found: {name}") + + def validate(self, required: set[str] | None = None) -> dict[str, object]: + names = set(self.list_names()) + required_names = required or REQUIRED_SKILLS + missing = sorted(required_names - names) + malformed: list[str] = [] + for item in self.list(): + text = item.path.read_text(encoding="utf-8") + if "name:" not in text[:300]: + malformed.append(item.name) + return { + "ok": not missing and not malformed, + "canonical_dir": str(self.canonical_dir), + "count": len(names), + "missing": missing, + "malformed": malformed, + } + + def sync_to(self, targets: list[Path], *, force: bool = True) -> int: + """Copy canonical skills into adapter skill directories. + + Returns the number of skill directories copied across all targets. + """ + copied = 0 + for target in targets: + if target.resolve() == self.canonical_dir.resolve(): + continue + target.mkdir(parents=True, exist_ok=True) + for item in self.list(): + dst = target / item.name + if dst.exists() and force: + shutil.rmtree(dst) + if not dst.exists(): + shutil.copytree(item.path.parent, dst) + copied += 1 + return copied + + +def default_adapter_skill_dirs() -> list[Path]: + return [ + REPO_ROOT / ".opencode" / "skills", + REPO_ROOT / ".agents" / "skills", + ] diff --git a/scripts/runtime/sources.py b/scripts/runtime/sources.py new file mode 100644 index 0000000..c03f72d --- /dev/null +++ b/scripts/runtime/sources.py @@ -0,0 +1,65 @@ +"""Source registry helpers for Phase 2 packets.""" + +from __future__ import annotations + +import json +from pathlib import Path +from typing import Any + + +def _source_key(source: dict[str, Any]) -> str: + return (source.get("url") or source.get("doi") or source.get("id") or "").strip() + + +def append_packet_sources(sources_path: Path, packet: dict[str, Any]) -> int: + """Append packet sources to sources.jsonl, deduping by URL/DOI/id.""" + sources_path.parent.mkdir(parents=True, exist_ok=True) + existing: set[str] = set() + if sources_path.exists(): + for line in sources_path.read_text(encoding="utf-8").splitlines(): + if not line.strip(): + continue + try: + existing.add(_source_key(json.loads(line))) + except json.JSONDecodeError: + continue + + written = 0 + with sources_path.open("a", encoding="utf-8") as f: + for source in packet.get("sources") or []: + key = _source_key(source) + if not key or key in existing: + continue + existing.add(key) + f.write(json.dumps(source, ensure_ascii=False) + "\n") + written += 1 + return written + + +def rebuild_sources_from_packets(project_root: Path) -> int: + """Rebuild phase2/sources.jsonl from packet-level source metadata.""" + packets_dir = project_root / "phase2" / "packets" + sources_path = project_root / "phase2" / "sources.jsonl" + sources_path.parent.mkdir(parents=True, exist_ok=True) + seen: set[str] = set() + rows: list[dict[str, Any]] = [] + + for packet_path in sorted(packets_dir.glob("*.json")): + try: + packet = json.loads(packet_path.read_text(encoding="utf-8")) + except json.JSONDecodeError: + continue + for source in packet.get("sources") or []: + if not isinstance(source, dict): + continue + key = _source_key(source) + if not key or key in seen: + continue + seen.add(key) + rows.append(source) + + sources_path.write_text( + "".join(json.dumps(row, ensure_ascii=False) + "\n" for row in rows), + encoding="utf-8", + ) + return len(rows) diff --git a/scripts/runtime/tasks.py b/scripts/runtime/tasks.py new file mode 100644 index 0000000..3746417 --- /dev/null +++ b/scripts/runtime/tasks.py @@ -0,0 +1,229 @@ +"""Task-card and evidence-packet primitives for v0.20 Phase 2.""" + +from __future__ import annotations + +import json +import re +from dataclasses import asdict, dataclass, field +from pathlib import Path +from typing import Any + +from scripts.runtime.methods import ResearchMethod + + +VALID_ROUTES = {"general", "scholar", "patents", "news"} +DEFAULT_AXES = ["literature", "regulatory", "patents", "market", "counter"] +AXIS_ROUTES = { + "literature": ["scholar", "general"], + "clinical": ["scholar", "general"], + "regulatory": ["general", "news"], + "patents": ["patents", "general"], + "market": ["news", "general"], + "china": ["news", "general"], + "counter": ["scholar", "general"], + "regulatory_gap": ["general", "news"], + "risk_classification": ["general", "scholar"], + "capa_design": ["general", "news"], + "ownership_timeline": ["general"], + "verification_evidence": ["general", "scholar"], + "process_flow": ["scholar", "general"], + "cqa_cpp": ["scholar", "general"], + "scale_up_risk": ["scholar", "general"], + "control_strategy": ["scholar", "general"], + "supply_chain": ["news", "general"], + "scientific_rationale": ["scholar", "general"], + "poc_evidence": ["scholar", "general"], + "ip_fto": ["patents", "general"], + "development_path": ["scholar", "general"], + "commercial_window": ["news", "general"], + "current_state": ["general"], + "capability_gap": ["general"], + "operating_model": ["general"], + "governance": ["general"], + "implementation_roadmap": ["general"], +} + + +@dataclass +class Chapter: + chapter_id: str + index: int + title: str + notes: str = "" + + +@dataclass +class TaskCard: + task_id: str + chapter_ids: list[str] + topic_axis: str + questions: list[str] + search_routes: list[str] + output_packet: str + preferred_model_role: str = "dr_analyst" + status: str = "pending" + dependencies: list[str] = field(default_factory=list) + + def to_dict(self) -> dict[str, Any]: + return asdict(self) + + +def parse_framework_chapters(framework_text: str) -> list[Chapter]: + """Extract Chinese or English chapter headings from a framework markdown.""" + lines = framework_text.splitlines() + chapters: list[Chapter] = [] + current: Chapter | None = None + note_lines: list[str] = [] + heading_re = re.compile( + r"^#{1,3}\s*(?:第\s*)?(\d{1,2})\s*(?:章|[.)、:-])?\s*(.+?)\s*$", + re.IGNORECASE, + ) + english_re = re.compile(r"^#{1,3}\s*chapter\s+(\d{1,2})[:.)\s-]+(.+?)\s*$", re.IGNORECASE) + for line in lines: + match = heading_re.match(line.strip()) or english_re.match(line.strip()) + if match: + if current: + current.notes = "\n".join(note_lines).strip() + chapters.append(current) + index = int(match.group(1)) + title = match.group(2).strip(" #") + current = Chapter(chapter_id=f"ch{index:02d}", index=index, title=title) + note_lines = [] + elif current: + note_lines.append(line) + if current: + current.notes = "\n".join(note_lines).strip() + chapters.append(current) + return chapters + + +def _questions_for_axis(chapter: Chapter, axis: str) -> list[str]: + return [ + f"围绕《{chapter.title}》从 {axis} 角度提炼可证伪的核心结论。", + "至少寻找两个 Tier 1-2 来源支撑主要结论；不足时标注待验证。", + "主动检索反方证据、限制条件或失败案例。", + ] + + +def generate_task_cards( + slug: str, + framework_text: str, + *, + axes: list[str] | None = None, + method: ResearchMethod | None = None, +) -> list[TaskCard]: + del slug # slug is kept for call-site clarity and future namespacing. + chapters = parse_framework_chapters(framework_text) + selected_axes = axes or (method.task_axes if method else DEFAULT_AXES) + cards: list[TaskCard] = [] + for chapter in chapters: + for axis in selected_axes: + routes = AXIS_ROUTES.get(axis, ["general"]) + cards.append( + TaskCard( + task_id=f"{chapter.chapter_id}-{axis}", + chapter_ids=[chapter.chapter_id], + topic_axis=axis, + questions=_questions_for_axis(chapter, axis), + search_routes=routes, + output_packet=f"phase2/packets/{chapter.chapter_id}-{axis}.json", + preferred_model_role="dr_verifier" if axis == "counter" else "dr_analyst", + ) + ) + validate_task_cards(cards) + return cards + + +def detect_dependency_cycles(cards: list[TaskCard]) -> None: + graph = {card.task_id: card.dependencies for card in cards} + visiting: set[str] = set() + visited: set[str] = set() + + def visit(node: str) -> None: + if node in visiting: + raise ValueError(f"dependency cycle detected at {node}") + if node in visited: + return + visiting.add(node) + for dep in graph.get(node, []): + visit(dep) + visiting.remove(node) + visited.add(node) + + for task_id in graph: + visit(task_id) + + +def validate_task_cards(cards: list[TaskCard]) -> None: + seen: set[str] = set() + for card in cards: + if card.task_id in seen: + raise ValueError(f"duplicate task_id: {card.task_id}") + seen.add(card.task_id) + if not card.chapter_ids: + raise ValueError(f"{card.task_id}: chapter_ids required") + if not card.questions: + raise ValueError(f"{card.task_id}: questions required") + if not card.output_packet.endswith(".json"): + raise ValueError(f"{card.task_id}: output_packet must be json") + invalid_routes = sorted(set(card.search_routes) - VALID_ROUTES) + if invalid_routes: + raise ValueError(f"{card.task_id}: invalid search_routes {invalid_routes}") + missing_deps = sorted({dep for card in cards for dep in card.dependencies} - seen) + if missing_deps: + raise ValueError(f"unknown dependencies: {missing_deps}") + detect_dependency_cycles(cards) + + +def write_task_cards(path: Path, cards: list[TaskCard]) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text( + json.dumps([card.to_dict() for card in cards], ensure_ascii=False, indent=2) + "\n", + encoding="utf-8", + ) + + +def load_task_cards(path: Path) -> list[TaskCard]: + data = json.loads(path.read_text(encoding="utf-8")) + cards = [TaskCard(**item) for item in data] + validate_task_cards(cards) + return cards + + +def validate_packet(packet: dict[str, Any]) -> None: + required = { + "task_id", + "claims", + "evidence_items", + "counter_evidence", + "source_ids", + "source_quality_notes", + "open_questions", + "raw_quotes_or_notes", + } + missing = sorted(required - set(packet)) + if missing: + raise ValueError(f"packet missing fields: {missing}") + if not packet["claims"]: + raise ValueError("packet claims must not be empty") + if not packet["evidence_items"]: + raise ValueError("packet evidence_items must not be empty") + if not packet["counter_evidence"]: + raise ValueError("packet counter_evidence must not be empty") + declared = set(packet.get("source_ids") or []) + referenced: set[str] = set() + for section in ("claims", "counter_evidence"): + for item in packet.get(section) or []: + referenced.update(item.get("source_ids") or []) + for item in packet.get("evidence_items") or []: + if item.get("source_id"): + referenced.add(item["source_id"]) + undeclared = sorted(referenced - declared) + if undeclared: + raise ValueError(f"packet source_ids referenced but not declared: {undeclared}") + packet_sources = packet.get("sources") or [] + if packet_sources: + known_source_ids = {source.get("id") for source in packet_sources} + missing_sources = sorted(declared - known_source_ids) + if missing_sources: + raise ValueError(f"packet source_ids missing source metadata: {missing_sources}") diff --git a/scripts/runtime/workers.py b/scripts/runtime/workers.py new file mode 100644 index 0000000..32918c3 --- /dev/null +++ b/scripts/runtime/workers.py @@ -0,0 +1,261 @@ +"""Python role workers for task-card execution.""" + +from __future__ import annotations + +import json +import re +from concurrent.futures import ThreadPoolExecutor, as_completed +from pathlib import Path +from typing import Callable, Protocol, Any + +from scripts.runtime.roles import RoleDefinition, RuntimeProfile +from scripts.runtime.skills import SkillRegistry +from scripts.runtime.tasks import TaskCard, validate_packet +from scripts.runtime.sources import append_packet_sources + + +class ChatClient(Protocol): + def chat_complete(self, **kwargs) -> str: + ... + + +class SearchProvider(Protocol): + def search(self, *, query: str, route: str, num_results: int) -> list[dict[str, Any]]: + ... + + +class ProjectSearchProvider: + """Thin adapter over the project-owned search client.""" + + def __init__(self, *, strict_specialized: bool = True) -> None: + from scripts.lib.search_client import SearchClient + + self.client = SearchClient(strict_specialized=strict_specialized) + + def search(self, *, query: str, route: str, num_results: int) -> list[dict[str, Any]]: + if route == "scholar": + hits = self.client.scholar(query, num_results=num_results, year_low=2020) + elif route == "patents": + hits = self.client.patents(query, num_results=num_results) + elif route == "news": + hits = self.client.news(query, num_results=num_results, time_range="y") + else: + hits = self.client.search(query, num_results=num_results) + return [ + { + "title": hit.title, + "url": hit.url, + "snippet": hit.snippet, + "route": route, + } + for hit in hits + ] + + def close(self) -> None: + self.client.close() + + +def _extract_json_object(text: str) -> dict: + stripped = text.strip() + if stripped.startswith("```"): + stripped = stripped.strip("`") + if stripped.startswith("json"): + stripped = stripped[4:].strip() + start = stripped.find("{") + end = stripped.rfind("}") + if start == -1 or end == -1 or end < start: + raise ValueError("worker response does not contain a JSON object") + return json.loads(stripped[start : end + 1]) + + +def _safe_source_stem(task_id: str) -> str: + return re.sub(r"[^a-zA-Z0-9]+", "_", task_id).strip("_").lower() + + +def build_search_context( + card: TaskCard, + search_provider: SearchProvider, + *, + num_results_per_route: int = 5, +) -> dict[str, Any]: + candidate_sources: list[dict[str, Any]] = [] + routes_used: list[str] = [] + source_stem = _safe_source_stem(card.task_id) + idx = 1 + query = " ".join(card.questions) + for route in card.search_routes: + routes_used.append(route) + hits = search_provider.search(query=query, route=route, num_results=num_results_per_route) + for hit in hits: + candidate_sources.append( + { + "id": f"src_{source_stem}_{idx:03d}", + "title": hit.get("title", ""), + "url": hit.get("url", ""), + "snippet": hit.get("snippet", ""), + "route": hit.get("route", route), + "tier": "Tier 2", + "score": 6, + } + ) + idx += 1 + return {"routes_used": routes_used, "candidate_sources": candidate_sources} + + +def build_packet_user_prompt(card: TaskCard, search_context: dict[str, Any] | None = None) -> str: + context = search_context or {"routes_used": [], "candidate_sources": []} + return ( + "请根据以下 task card 产出一个证据包 JSON。\n" + "正式结论、summary、open_questions 用中文；英文原文摘录、source title、DOI/URL 可以保留英文。\n" + "必须主动包含 counter_evidence，且所有引用的 source_id 必须出现在 source_ids 中。\n\n" + "只能使用 candidate_sources 中的来源，不得编造 URL、DOI、trial ID 或 source_id。\n" + "输出 JSON 必须包含 sources 字段，且 sources 只能来自 candidate_sources。\n\n" + f"{json.dumps(card.to_dict(), ensure_ascii=False, indent=2)}\n\n" + f"Search context:\n{json.dumps(context, ensure_ascii=False, indent=2)}\n\n" + "只输出 JSON，不要输出 Markdown 解释。" + ) + + +def build_packet_repair_prompt( + *, + card: TaskCard, + raw_response: str, + error: Exception, + search_context: dict[str, Any] | None = None, +) -> str: + context = search_context or {"routes_used": [], "candidate_sources": []} + return ( + "请修复上一次 evidence packet 输出，使其成为合法且通过 schema 校验的 JSON。\n" + "只输出 JSON 对象，不要输出 Markdown、解释或代码块。\n" + "保留中文主写作；英文只允许出现在来源标题、URL、DOI、原文摘录或检索笔记中。\n" + "不得编造 candidate_sources 以外的来源、URL、DOI、trial ID 或 source_id。\n\n" + f"Schema error:\n{error}\n\n" + f"Task card:\n{json.dumps(card.to_dict(), ensure_ascii=False, indent=2)}\n\n" + f"Search context:\n{json.dumps(context, ensure_ascii=False, indent=2)}\n\n" + f"Previous raw response:\n{raw_response[:12000]}" + ) + + +class PacketWorker: + def __init__( + self, + *, + role: RoleDefinition, + client: ChatClient, + search_provider: SearchProvider | None = None, + skill_registry: SkillRegistry | None = None, + num_results_per_route: int = 5, + ) -> None: + self.role = role + self.client = client + self.search_provider = search_provider + self.skill_registry = skill_registry or SkillRegistry() + self.num_results_per_route = num_results_per_route + + def _system_prompt(self) -> str: + skill_texts = [] + for name in self.role.skills: + try: + skill_texts.append(f"# Skill: {name}\n\n{self.skill_registry.read(name)}") + except FileNotFoundError: + skill_texts.append(f"# Skill: {name}\n\n[missing skill: {name}]") + return ( + "你是 Deep Research v0.20 Python runtime 的证据包 worker。\n" + "你的唯一任务是把一个 task card 转换为结构化 evidence packet。\n" + "遵循中文主写作原则；不要写章节正文；不要编造 URL、DOI、trial ID 或 source_id。\n\n" + "搜索只能走项目 Python search gateway 或调用方提供的 search_context；不要直接使用 Tavily MCP、browser MCP、平台 web search 或任何需要用户权限确认的外部搜索工具。\n\n" + + "\n\n".join(skill_texts) + ) + + def run(self, card: TaskCard) -> dict: + search_context = None + if self.search_provider: + search_context = build_search_context( + card, + self.search_provider, + num_results_per_route=self.num_results_per_route, + ) + raw = self.client.chat_complete( + model=self.role.model, + system=self._system_prompt(), + user=build_packet_user_prompt(card, search_context), + temperature=self.role.temperature, + max_tokens=self.role.max_tokens, + tag=f"packet:{card.task_id}", + ) + try: + packet = _extract_json_object(raw) + validate_packet(packet) + return packet + except Exception as error: + repaired = self.client.chat_complete( + model=self.role.model, + system=self._system_prompt(), + user=build_packet_repair_prompt( + card=card, + raw_response=raw, + error=error, + search_context=search_context, + ), + temperature=0, + max_tokens=self.role.max_tokens, + tag=f"packet-repair:{card.task_id}", + ) + packet = _extract_json_object(repaired) + validate_packet(packet) + return packet + + +def _write_packet_error(project_root: Path, card: TaskCard, error: Exception) -> None: + path = project_root / "phase2" / "packet_errors" / f"{card.task_id}.json" + path.parent.mkdir(parents=True, exist_ok=True) + payload = { + "task_id": card.task_id, + "status": "failed", + "error": str(error), + "output_packet": card.output_packet, + } + path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + + +def run_packet_workers( + *, + project_root: Path, + cards: list[TaskCard], + runtime: RuntimeProfile, + client_factory: Callable[[RoleDefinition], ChatClient], + search_provider_factory: Callable[[], SearchProvider] | None = None, + workers: int, +) -> int: + role = runtime.role_for_task("evidence_packet") + max_workers = max(1, min(workers, role.max_concurrency)) + + def run_one(card: TaskCard) -> tuple[TaskCard, dict | None, Exception | None]: + search_provider = search_provider_factory() if search_provider_factory else None + try: + worker = PacketWorker(role=role, client=client_factory(role), search_provider=search_provider) + return card, worker.run(card), None + except Exception as error: + return card, None, error + finally: + close = getattr(search_provider, "close", None) + if close: + close() + + written = 0 + with ThreadPoolExecutor(max_workers=max_workers) as pool: + futures = [pool.submit(run_one, card) for card in cards] + for future in as_completed(futures): + card, packet, error = future.result() + if error is not None: + _write_packet_error(project_root, card, error) + continue + if packet is None: + _write_packet_error(project_root, card, RuntimeError("packet worker returned no packet")) + continue + path = project_root / card.output_packet + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(packet, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + append_packet_sources(project_root / "phase2" / "sources.jsonl", packet) + written += 1 + return written diff --git a/scripts/v020_regression.py b/scripts/v020_regression.py new file mode 100644 index 0000000..b7226ca --- /dev/null +++ b/scripts/v020_regression.py @@ -0,0 +1,69 @@ +#!/usr/bin/env python3 +"""v0.20 Python-core regression checks.""" + +from __future__ import annotations + +import json +import subprocess +import sys +import tempfile +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parent.parent + + +def run(cmd: list[str]) -> None: + print("$ " + " ".join(cmd)) + result = subprocess.run(cmd, cwd=REPO_ROOT, check=False, text=True, capture_output=True) + if result.stdout: + print(result.stdout.rstrip()) + if result.stderr: + print(result.stderr.rstrip(), file=sys.stderr) + if result.returncode != 0: + raise SystemExit(result.returncode) + + +def make_fixture(root: Path) -> Path: + project = root / "v020-fixture" + (project / "phase4").mkdir(parents=True, exist_ok=True) + (project / "phase4" / "final_zh.md").write_text( + "# v0.20 回归测试报告\n\n正文引用占位。\n", + encoding="utf-8", + ) + return project + + +def main() -> int: + python = sys.executable + run([python, "scripts/dr.py", "skills", "validate"]) + run([python, "scripts/dr.py", "models", "--profile", "medium", "--json"]) + with tempfile.TemporaryDirectory(prefix="deep-research-v020-") as tmp: + tmp_root = Path(tmp) + run( + [ + python, + "scripts/dr.py", + "init", + "v0.20 fixture", + "--slug", + "v020-fixture", + "--projects-dir", + str(tmp_root), + "--method", + "mckinsey_market", + ] + ) + project = make_fixture(tmp_root) + run([python, "scripts/dr.py", "frame", str(project)]) + run([python, "scripts/dr.py", "approve", str(project)]) + run([python, "scripts/dr.py", "research", str(project), "--workers", "2", "--dry-run"]) + run([python, "scripts/dr.py", "research", str(project), "--workers", "2"]) + run([python, "scripts/dr.py", "review", str(project)]) + run([python, "scripts/dr.py", "finalize", str(project), "--dry-run"]) + print("v0.20 regression PASS") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/deep-research/SKILL.md b/skills/deep-research/SKILL.md new file mode 100644 index 0000000..b7bf4c5 --- /dev/null +++ b/skills/deep-research/SKILL.md @@ -0,0 +1,58 @@ +--- +name: deep-research +description: Use when a user wants to run Deep Research, create a client-ready research report, analyze supplied audit/material files, compare evidence against regulations or best practices, or continue a phase-based research project. +--- + +# Deep Research + +## Principle + +Deep Research is driven by the repository Python core, not by chat context. Treat Codex, OpenCode, Claude Code, Antigravity, and Gemini CLI as surface interfaces that call `scripts/dr.py`; all durable state must be written under `projects/<slug>/`. + +## Required Flow + +1. Work from the repository root. +2. Validate the skill/runtime registry before a serious run: + `uv run python scripts/dr.py skills validate` +3. For user-supplied materials, stop after Phase 0/1 material brief and interview: + `uv run python scripts/dr.py init "<topic>" --slug <slug> --method <method> --input-material <path>` + Review `phase1/material_brief.md` with the user before generating or approving the framework. +4. If model calls will be used, probe the selected profile first: + `uv run python scripts/dr.py models --profile medium --probe` +5. Run Phase 1 and pause for framework review: + `uv run python scripts/dr.py frame <slug> --method <method>` + After user approval: `uv run python scripts/dr.py approve <slug>` +6. Run Phase 2 with file-backed task cards and packets: + `uv run python scripts/dr.py research <slug> --workers 6 --execute-packets --allow-search-fallback` +7. Build briefs and chapters only from persisted packets: + `uv run python scripts/dr.py research <slug> --build-briefs` + `uv run python scripts/dr.py research <slug> --assemble-chapters --workers 4` +8. Review and finalize through Python: + `uv run python scripts/dr.py review <slug>` + `uv run python scripts/dr.py finalize <slug> --report-engine reportlab` + +## Research Rules + +- Chinese is the formal thinking and writing language by default; English is allowed for search keywords, source titles, abstracts, and raw excerpts. +- Do not invent evidence when model/API access fails. Stop at the last durable artifact and report the exact blocker. +- Phase 2 concurrency must use task cards and packet files, not platform subagents as the default mechanism. +- Search must use the project Python gateway (`scripts/search.py` / `scripts.lib.search_client`) by default. Do not use Tavily MCP, browser MCP, or platform-native web search in subagents unless the user explicitly requests that escape hatch. +- User materials are starting evidence, not final truth. Cross-check against authoritative sources such as NMPA, FDA, EMA, ICH, WHO, pharmacopeias, and recognized best-practice references. +- For GMP/quality/operations diagnosis, prefer `--method gmp_quality_operations_diagnosis`. +- Chapter drafts are not acceptable if they merely summarize principles. Each section must turn evidence into concrete findings, risk implications, and整改动作；otherwise return to Phase 2 enrichment. + +## Useful Commands + +- Status: `uv run python scripts/dr.py status <slug>` +- List methods: `uv run python scripts/dr.py methods list` +- Show method: `uv run python scripts/dr.py methods show <method>` +- Dry-run task cards: `uv run python scripts/dr.py research <slug> --dry-run` +- Sync adapter skills: `uv run python scripts/dr.py skills sync` + +## Common Failures + +- If Codex cannot write `~/.codex`, run `uv run python scripts/deploy_adapters.py codex --force` outside sandboxed mode. +- The Codex deploy script does not copy `config.toml` by default; use `--include-config` only when the user explicitly wants the bundled Codex profile. +- If `models --probe` returns subscription/model errors, do not launch packet workers; switch profile/key/provider first. +- If a PDF has little embedded text, Phase 0 should call FireRed OCR. Default endpoint: `http://192.168.50.100:8001`. +- If a subagent asks for MCP/web permissions during research, stop it and reroute the task through `search-gateway`. diff --git a/skills/document-ingest/SKILL.md b/skills/document-ingest/SKILL.md new file mode 100644 index 0000000..13c4760 --- /dev/null +++ b/skills/document-ingest/SKILL.md @@ -0,0 +1,34 @@ +--- +name: document-ingest +description: Use when Deep Research starts from user-provided PDFs, scanned audit reports, DOCX/PPTX files, images, or internal notes that must become phase0 persisted inputs. +--- + +# Document Ingest + +## Core Rule + +User-provided materials are evidence leads, not final evidence. Always persist the original file, extracted text, OCR status, and limitations under `phase0/` before Phase 1 framing depends on them. + +## Required Artifacts + +- `phase0/inputs/<original-file>` stores the source file copy. +- `phase0/extracted/<stem>.md` stores direct text extraction plus OCR text when available. +- `phase0/extracted/<stem>.ocr.md` stores OCR-only output for scanned PDFs. +- `manifest.json.material_inventory[]` records `copied_to`, `extracted_to`, `ocr_required`, `ocr_status`, and OCR errors if any. + +## PDF Handling + +- Text PDFs should use direct extraction first. +- If direct extraction is too sparse, run FireRed OCR through the configured LAN endpoint. +- Default endpoint: `http://192.168.50.100:8001`. +- Override endpoint with `DEEP_RESEARCH_OCR_ENDPOINT`. +- Limit page count with `DEEP_RESEARCH_OCR_MAX_PAGES` when testing or when documents are very long. + +## Current Boundary + +PDF text extraction and scanned-PDF OCR are supported. DOCX, PPTX, image-only batches, table reconstruction, and layout-aware evidence mapping should remain explicit next-step work unless implemented in Python core. + +## Quality Notes + +- OCR text may contain spacing or line-break errors. Treat it as internal material evidence and verify formal findings against NMPA, FDA, EMA, ICH, WHO, or other authoritative sources. +- If OCR fails, do not block project initialization. Record the failure and continue Phase 1 with a clear limitation. diff --git a/skills/search-gateway/SKILL.md b/skills/search-gateway/SKILL.md new file mode 100644 index 0000000..f89d474 --- /dev/null +++ b/skills/search-gateway/SKILL.md @@ -0,0 +1,53 @@ +--- +name: search-gateway +description: Use when Deep Research agents or subagents need web, scholar, patent, news, regulatory, or source-discovery search without using platform MCP tools or browser search directly. +--- + +# Search Gateway + +## Rule + +Use the project Python search gateway as the only default search interface. Do not call Tavily MCP, browser MCP, generic web tools, or platform-native search from a subagent unless the user explicitly asks for that escape hatch. + +## Commands + +Run searches from the repository root: + +```bash +uv run python scripts/search.py "<query>" --route general --json --trace +uv run python scripts/search.py "<query>" --route scholar --year-low 2020 --json --trace +uv run python scripts/search.py "<query>" --route news --time-range y --json --trace +uv run python scripts/search.py "<query>" --route patents --json --trace +uv run python scripts/search.py "<query>" --profile biomed_literature --json --trace +``` + +If `uv` cannot use the user cache in a sandbox, set a local cache: + +```bash +UV_CACHE_DIR=/private/tmp/deep_research_uv_cache uv run python scripts/search.py "<query>" --route general --json --trace +``` + +## Routing + +- `general`: Exa first, Tavily fallback. +- `scholar`: Serper Scholar first; use for papers, guidelines, and technical literature. +- `news`: Serper News first; use for recent industry/current information. +- `patents`: Serper Google Patents first. +- `biomed_literature`: scholar plus general discovery. + +API keys are loaded from `secrets.env` by `scripts/search.py`; do not ask the user to authorize MCP calls when the env keys are available. + +## Subagent Protocol + +For evidence packets: + +1. Search through `scripts/search.py`, save or summarize the returned JSON in the packet’s `raw_quotes_or_notes`. +2. Use search hits only as candidate sources; whenever possible, cite the original regulator, guideline, paper, or official document. +3. Put every used source in `sources` with `id`, `title`, `url`, `tier`, and `score`. +4. Do not write a final chapter during search; produce structured evidence only. + +For chapter assembly: + +1. Do not search. Use only `phase2/chapter_briefs`, `phase2/packets`, `phase2/sources.jsonl`, `phase0/extracted`, and `phase1/framework.md`. +2. Do not create new `source_id`. +3. If evidence is thin, mark the chapter as needing Phase 2 enrichment instead of filling with generic prose. diff --git a/tests/test_adapter_deploy.py b/tests/test_adapter_deploy.py new file mode 100644 index 0000000..22ce69c --- /dev/null +++ b/tests/test_adapter_deploy.py @@ -0,0 +1,51 @@ +from __future__ import annotations + +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.deploy_adapters import default_codex_home, deploy_codex + + +def test_default_codex_home_is_external_to_project(tmp_path: Path) -> None: + home = default_codex_home(env={}, user_home=tmp_path) + + assert home == tmp_path / ".codex" + assert not home.is_relative_to(REPO_ROOT) + + +def test_deploy_codex_writes_adapter_to_external_home(tmp_path: Path) -> None: + target = tmp_path / "codex-home" + + result = deploy_codex(target=target, force=True, repo_root=REPO_ROOT) + + assert result.written + assert not (target / "config.toml").exists() + assert (target / "commands" / "dr-run.md").exists() + assert (target / "agents" / "dr-pm.toml").exists() + assert (target / "skills" / "search-strategy" / "SKILL.md").exists() + assert (target / "skills" / "search-gateway" / "SKILL.md").exists() + assert (target / "skills" / "document-ingest" / "SKILL.md").exists() + assert (target / "skills" / "deep-research" / "SKILL.md").exists() + assert result.target == target + + +def test_deploy_codex_config_is_explicit_opt_in(tmp_path: Path) -> None: + target = tmp_path / "codex-home" + + result = deploy_codex(target=target, force=True, repo_root=REPO_ROOT, include_config=True) + + assert result.written + assert (target / "config.toml").exists() + + +def test_deploy_codex_dry_run_does_not_write(tmp_path: Path) -> None: + target = tmp_path / "codex-home" + + result = deploy_codex(target=target, force=True, repo_root=REPO_ROOT, dry_run=True) + + assert result.planned + assert not target.exists() diff --git a/tests/test_chapter_assembly.py b/tests/test_chapter_assembly.py new file mode 100644 index 0000000..60b18f8 --- /dev/null +++ b/tests/test_chapter_assembly.py @@ -0,0 +1,225 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.runtime.assembly import ( + ChapterAssemblyWorker, + build_chapter_briefs, + build_chapter_user_prompt, + run_chapter_assembly_workers, + validate_chapter_markdown_citations, + validate_chapter_brief, +) +from scripts.runtime.roles import resolve_runtime_profile + + +class FakeClient: + def __init__(self, response: str) -> None: + self.response = response + self.calls: list[dict[str, object]] = [] + + def chat_complete(self, **kwargs) -> str: + self.calls.append(kwargs) + return self.response + + +class TaggedClient: + def __init__(self, responses_by_tag: dict[str, str]) -> None: + self.responses_by_tag = responses_by_tag + self.calls: list[dict[str, object]] = [] + + def chat_complete(self, **kwargs) -> str: + self.calls.append(kwargs) + return self.responses_by_tag[str(kwargs["tag"])] + + +def chapter_brief(chapter_id: str, source_ids: list[str]) -> dict: + return { + "chapter_id": chapter_id, + "chapter_title": "临床证据正在重塑需求判断", + "packet_ids": [f"{chapter_id}-clinical"], + "core_claims": [{"claim": "临床证据支持核心判断", "source_ids": source_ids[:1]}], + "evidence_items": [{"source_id": source_ids[0], "summary": "III 期数据支持主要终点"}], + "counter_evidence": [{"claim": "长期安全性仍需随访", "source_ids": source_ids[-1:]}], + "source_ids": source_ids, + "open_questions": [], + "assembly_notes": ["按金字塔结构组织。"], + } + + +def write_packet(path: Path, task_id: str, claim: str, source_id: str) -> None: + packet = { + "task_id": task_id, + "claims": [{"claim": claim, "source_ids": [source_id]}], + "evidence_items": [{"source_id": source_id, "summary": f"{claim} 的证据"}], + "counter_evidence": [{"claim": "仍需关注样本量和外推限制", "source_ids": ["src_counter"]}], + "source_ids": [source_id, "src_counter"], + "source_quality_notes": [f"{source_id} Tier 1"], + "open_questions": ["还需要补充中国市场数据"], + "raw_quotes_or_notes": ["English note can remain as source material."], + } + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(packet, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + + +def test_build_chapter_briefs_aggregates_packets_by_chapter(tmp_path: Path) -> None: + project = tmp_path / "project" + cards = [ + { + "task_id": "ch01-clinical", + "chapter_ids": ["ch01"], + "topic_axis": "clinical", + "questions": ["q"], + "search_routes": ["scholar"], + "output_packet": "phase2/packets/ch01-clinical.json", + }, + { + "task_id": "ch01-market", + "chapter_ids": ["ch01"], + "topic_axis": "market", + "questions": ["q"], + "search_routes": ["news"], + "output_packet": "phase2/packets/ch01-market.json", + }, + ] + (project / "phase2").mkdir(parents=True) + (project / "phase2" / "task_cards.json").write_text(json.dumps(cards, ensure_ascii=False), encoding="utf-8") + write_packet(project / "phase2/packets/ch01-clinical.json", "ch01-clinical", "临床证据支持核心判断", "src_001") + write_packet(project / "phase2/packets/ch01-market.json", "ch01-market", "市场数据支持需求增长", "src_002") + + briefs = build_chapter_briefs(project) + + assert len(briefs) == 1 + brief = briefs[0] + validate_chapter_brief(brief) + assert brief["chapter_id"] == "ch01" + assert brief["packet_ids"] == ["ch01-clinical", "ch01-market"] + assert "src_001" in brief["source_ids"] + assert "src_002" in brief["source_ids"] + assert (project / "phase2/chapter_briefs/ch01.json").exists() + + +def test_chapter_prompt_contains_brief_and_fragmentation_guard() -> None: + brief = { + "chapter_id": "ch01", + "chapter_title": "临床证据正在重塑需求判断", + "packet_ids": ["ch01-clinical"], + "core_claims": [{"claim": "临床证据支持核心判断", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "III 期数据支持主要终点"}], + "counter_evidence": [{"claim": "长期安全性仍需随访", "source_ids": ["src_002"]}], + "source_ids": ["src_001", "src_002"], + "open_questions": [], + "assembly_notes": ["避免重复 packet 原文；按金字塔结构组织。"], + } + + prompt = build_chapter_user_prompt(brief) + + assert "临床证据正在重塑需求判断" in prompt + assert "避免碎片化" in prompt + assert "只输出 Markdown" in prompt + + +def test_chapter_assembly_worker_writes_markdown(tmp_path: Path) -> None: + runtime = resolve_runtime_profile(profile="medium") + role = runtime.role_for_task("chapter_assembly") + fake = FakeClient("# 第1章 临床证据正在重塑需求判断\n\n结论先行。[src_001]\n") + worker = ChapterAssemblyWorker(role=role, client=fake) + brief = { + "chapter_id": "ch01", + "chapter_title": "临床证据正在重塑需求判断", + "packet_ids": ["ch01-clinical"], + "core_claims": [{"claim": "临床证据支持核心判断", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "III 期数据支持主要终点"}], + "counter_evidence": [{"claim": "长期安全性仍需随访", "source_ids": ["src_002"]}], + "source_ids": ["src_001", "src_002"], + "open_questions": [], + "assembly_notes": ["按金字塔结构组织。"], + } + + output = worker.write_chapter(project_root=tmp_path, brief=brief) + + assert output == tmp_path / "phase2/drafts/ch01.md" + assert "结论先行" in output.read_text(encoding="utf-8") + assert fake.calls[0]["model"] == role.model + + +def test_validate_chapter_markdown_rejects_unknown_source_ids() -> None: + brief = { + "chapter_id": "ch01", + "chapter_title": "临床证据正在重塑需求判断", + "packet_ids": ["ch01-clinical"], + "core_claims": [{"claim": "临床证据支持核心判断", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "III 期数据支持主要终点"}], + "counter_evidence": [{"claim": "长期安全性仍需随访", "source_ids": ["src_002"]}], + "source_ids": ["src_001", "src_002"], + "open_questions": [], + "assembly_notes": ["按金字塔结构组织。"], + } + + try: + validate_chapter_markdown_citations("结论引用了不存在的来源。[src_fake]", brief) + except ValueError as exc: + assert "unknown citation ids" in str(exc) + assert "src_fake" in str(exc) + else: + raise AssertionError("unknown source id should fail validation") + + +def test_chapter_assembly_worker_refuses_to_write_unknown_citations(tmp_path: Path) -> None: + runtime = resolve_runtime_profile(profile="medium") + role = runtime.role_for_task("chapter_assembly") + fake = FakeClient("# 第1章 临床证据正在重塑需求判断\n\n结论先行。[src_fake]\n") + worker = ChapterAssemblyWorker(role=role, client=fake) + brief = { + "chapter_id": "ch01", + "chapter_title": "临床证据正在重塑需求判断", + "packet_ids": ["ch01-clinical"], + "core_claims": [{"claim": "临床证据支持核心判断", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "III 期数据支持主要终点"}], + "counter_evidence": [{"claim": "长期安全性仍需随访", "source_ids": ["src_002"]}], + "source_ids": ["src_001", "src_002"], + "open_questions": [], + "assembly_notes": ["按金字塔结构组织。"], + } + + try: + worker.write_chapter(project_root=tmp_path, brief=brief) + except ValueError as exc: + assert "unknown citation ids" in str(exc) + else: + raise AssertionError("chapter with unknown citation should not be written") + assert not (tmp_path / "phase2/drafts/ch01.md").exists() + + +def test_run_chapter_assembly_workers_records_errors_without_aborting_batch(tmp_path: Path) -> None: + runtime = resolve_runtime_profile(profile="medium") + fake = TaggedClient( + { + "chapter:ch01": "# 第1章 临床证据正在重塑需求判断\n\n结论先行。[src_001]\n", + "chapter:ch02": "# 第2章 临床证据存在不确定性\n\n错误引用。[src_fake]\n", + } + ) + + count = run_chapter_assembly_workers( + project_root=tmp_path, + briefs=[chapter_brief("ch01", ["src_001", "src_002"]), chapter_brief("ch02", ["src_003", "src_004"])], + runtime=runtime, + client_factory=lambda _role: fake, + workers=2, + ) + + assert count == 1 + assert (tmp_path / "phase2/drafts/ch01.md").exists() + assert not (tmp_path / "phase2/drafts/ch02.md").exists() + error_path = tmp_path / "phase2/chapter_errors/ch02.json" + assert error_path.exists() + error = json.loads(error_path.read_text(encoding="utf-8")) + assert error["chapter_id"] == "ch02" + assert error["status"] == "failed" + assert "src_fake" in error["error"] diff --git a/tests/test_phase0_materials.py b/tests/test_phase0_materials.py new file mode 100644 index 0000000..c8cab30 --- /dev/null +++ b/tests/test_phase0_materials.py @@ -0,0 +1,100 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +import scripts.runtime.materials as materials +from reportlab.pdfgen import canvas + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.runtime.phase1 import create_project, render_framework + + +def make_text_pdf(path: Path, text: str) -> None: + c = canvas.Canvas(str(path)) + c.drawString(72, 720, text) + c.save() + + +def test_init_ingests_pdf_material_into_phase0(tmp_path: Path) -> None: + pdf = tmp_path / "audit.pdf" + make_text_pdf(pdf, "GMP audit finding: deviation management is incomplete.") + + project = create_project( + topic="白帆生物 GMP 与运营诊断", + slug="baifan-test", + projects_dir=tmp_path / "projects", + method_key="gmp_quality_operations_diagnosis", + input_materials=[str(pdf), "补充说明：运营团队需要同步诊断"], + ) + + manifest = json.loads((project / "manifest.json").read_text(encoding="utf-8")) + inventory = manifest["material_inventory"] + + assert inventory[0]["kind"] == "pdf" + assert inventory[0]["copied_to"] == "phase0/inputs/audit.pdf" + assert inventory[0]["extracted_to"] == "phase0/extracted/audit.md" + assert inventory[0]["ocr_required"] is False + assert "deviation management" in (project / "phase0/extracted/audit.md").read_text(encoding="utf-8") + assert inventory[1]["kind"] == "note" + material_brief = project / "phase1" / "material_brief.md" + assert material_brief.exists() + assert "Phase 0 材料简报" in material_brief.read_text(encoding="utf-8") + assert "待用户确认" in material_brief.read_text(encoding="utf-8") + assert manifest["phase1"]["requires_user_interview"] is True + + +def test_framework_mentions_ingested_materials(tmp_path: Path) -> None: + pdf = tmp_path / "audit.pdf" + make_text_pdf(pdf, "Quality system audit.") + project = create_project( + topic="白帆生物 GMP 与运营诊断", + slug="baifan-test", + projects_dir=tmp_path / "projects", + method_key="gmp_quality_operations_diagnosis", + input_materials=[str(pdf)], + ) + + render_framework(project, method_key="gmp_quality_operations_diagnosis") + + framework = (project / "phase1/framework.md").read_text(encoding="utf-8") + assert "phase0/extracted/audit.md" in framework + assert "NMPA、FDA、EMA、ICH、WHO" in framework + assert "请先确认 `phase1/material_brief.md`" in framework + + +def test_pdf_requiring_ocr_uses_firered_and_records_result(tmp_path: Path, monkeypatch) -> None: + pdf = tmp_path / "scan.pdf" + c = canvas.Canvas(str(pdf)) + c.showPage() + c.save() + + def fake_ocr_pdf(*, pdf_path: Path, output_dir: Path, endpoint: str, max_pages: int) -> materials.OcrResult: + assert pdf_path == pdf + assert endpoint == materials.DEFAULT_FIRERED_OCR_ENDPOINT + out = output_dir / "scan.ocr.md" + out.write_text("# OCR\n\n扫描审计发现：偏差管理未闭环。\n", encoding="utf-8") + return materials.OcrResult(text="扫描审计发现：偏差管理未闭环。", pages_processed=1, output_path=out) + + monkeypatch.setattr(materials, "ocr_pdf_with_firered", fake_ocr_pdf) + + project = create_project( + topic="白帆生物 GMP 与运营诊断", + slug="baifan-test", + projects_dir=tmp_path / "projects", + method_key="gmp_quality_operations_diagnosis", + input_materials=[str(pdf)], + ) + + manifest = json.loads((project / "manifest.json").read_text(encoding="utf-8")) + item = manifest["material_inventory"][0] + + assert item["ocr_required"] is True + assert item["ocr_status"] == "completed" + assert item["ocr_text_chars"] > 0 + assert item["ocr_extracted_to"] == "phase0/extracted/scan.ocr.md" + assert "扫描审计发现" in (project / "phase0/extracted/scan.md").read_text(encoding="utf-8") diff --git a/tests/test_reporting.py b/tests/test_reporting.py new file mode 100644 index 0000000..6bab5ff --- /dev/null +++ b/tests/test_reporting.py @@ -0,0 +1,34 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.reporting.fonts import resolve_quarto_fonts +from scripts.reporting.references import build_references_block + + +def test_build_references_block_uses_only_cited_sources(tmp_path: Path) -> None: + sources = tmp_path / "sources.jsonl" + rows = [ + {"id": "src_001", "authors": ["A"], "year": 2024, "title": "Used", "venue": "NEJM", "url": "https://example.com/1"}, + {"id": "src_002", "authors": ["B"], "year": 2023, "title": "Unused", "venue": "Lancet", "url": "https://example.com/2"}, + ] + sources.write_text("\n".join(json.dumps(row, ensure_ascii=False) for row in rows), encoding="utf-8") + + block = build_references_block(sources, "正文引用 [src_001]。") + + assert "Used" in block + assert "Unused" not in block + + +def test_resolve_quarto_fonts_returns_stable_defaults_for_missing_dir(tmp_path: Path) -> None: + fonts = resolve_quarto_fonts(tmp_path / "missing") + + assert fonts.main_font == "Source Han Serif CN" + assert fonts.sans_font == "Source Han Sans CN" + assert fonts.requires_system_fonts is True diff --git a/tests/test_research_methods.py b/tests/test_research_methods.py new file mode 100644 index 0000000..c502dbc --- /dev/null +++ b/tests/test_research_methods.py @@ -0,0 +1,55 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.runtime.methods import ResearchMethodRegistry +from scripts.runtime.orchestrator import create_phase2_task_cards +from scripts.runtime.tasks import generate_task_cards + + +def test_method_registry_loads_market_and_gmp_methods() -> None: + registry = ResearchMethodRegistry() + + names = registry.list_names() + + assert "mckinsey_market" in names + assert "gmp_gap_assessment" in names + assert registry.get("gmp_gap_assessment").task_axes[0] == "regulatory_gap" + + +def test_task_cards_use_method_axes() -> None: + framework = "## 第1章 GMP 审计差距决定整改优先级\n\n研究思路：法规、风险、CAPA。" + registry = ResearchMethodRegistry() + method = registry.get("gmp_gap_assessment") + + cards = generate_task_cards("gmp-test", framework, method=method) + + assert [card.topic_axis for card in cards] == method.task_axes + assert cards[0].task_id == "ch01-regulatory_gap" + + +def test_orchestrator_reads_research_method_from_manifest(tmp_path: Path) -> None: + project = tmp_path / "gmp-project" + (project / "phase1").mkdir(parents=True) + (project / "manifest.json").write_text( + json.dumps({"research_method": "gmp_gap_assessment", "phase2": {}}, ensure_ascii=False), + encoding="utf-8", + ) + (project / "phase1" / "framework.md").write_text( + "## 第1章 GMP 体系差距需要按法规和风险双轴定位\n\n研究思路。", + encoding="utf-8", + ) + + cards = create_phase2_task_cards(project, dry_run=True) + + assert [card["topic_axis"] for card in cards][:3] == [ + "regulatory_gap", + "risk_classification", + "capa_design", + ] diff --git a/tests/test_search_grounded_packets.py b/tests/test_search_grounded_packets.py new file mode 100644 index 0000000..6276b33 --- /dev/null +++ b/tests/test_search_grounded_packets.py @@ -0,0 +1,115 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.runtime.roles import resolve_runtime_profile +from scripts.runtime.sources import append_packet_sources, rebuild_sources_from_packets +from scripts.runtime.tasks import TaskCard +from scripts.runtime.workers import PacketWorker, build_search_context + + +class FakeSearchProvider: + def search(self, *, query: str, route: str, num_results: int): + return [ + { + "title": f"{route} result for {query}", + "url": f"https://example.com/{route}", + "snippet": "候选证据摘要", + "route": route, + } + ][:num_results] + + +class FakeClient: + def __init__(self, response: dict) -> None: + self.response = response + self.calls: list[dict[str, object]] = [] + + def chat_complete(self, **kwargs) -> str: + self.calls.append(kwargs) + return json.dumps(self.response, ensure_ascii=False) + + +def sample_card() -> TaskCard: + return TaskCard( + task_id="ch01-literature", + chapter_ids=["ch01"], + topic_axis="literature", + questions=["围绕临床证据提炼结论。"], + search_routes=["scholar", "general"], + output_packet="phase2/packets/ch01-literature.json", + ) + + +def test_build_search_context_assigns_stable_source_ids() -> None: + context = build_search_context(sample_card(), FakeSearchProvider(), num_results_per_route=1) + + assert [source["id"] for source in context["candidate_sources"]] == [ + "src_ch01_literature_001", + "src_ch01_literature_002", + ] + assert context["routes_used"] == ["scholar", "general"] + + +def test_packet_worker_includes_search_context_in_prompt() -> None: + context = build_search_context(sample_card(), FakeSearchProvider(), num_results_per_route=1) + response = { + "task_id": "ch01-literature", + "claims": [{"claim": "候选证据支持判断", "source_ids": ["src_ch01_literature_001"]}], + "evidence_items": [{"source_id": "src_ch01_literature_001", "summary": "摘要"}], + "counter_evidence": [{"claim": "仍需更多数据", "source_ids": ["src_ch01_literature_002"]}], + "source_ids": ["src_ch01_literature_001", "src_ch01_literature_002"], + "sources": context["candidate_sources"], + "source_quality_notes": ["候选来源需要后续评级"], + "open_questions": [], + "raw_quotes_or_notes": [], + } + role = resolve_runtime_profile(profile="medium").role_for_task("evidence_packet") + fake = FakeClient(response) + + packet = PacketWorker(role=role, client=fake, search_provider=FakeSearchProvider()).run(sample_card()) + + assert packet["sources"][0]["url"] == "https://example.com/scholar" + assert "candidate_sources" in fake.calls[0]["user"] + + +def test_append_packet_sources_dedupes_by_url(tmp_path: Path) -> None: + packet = { + "sources": [ + {"id": "src_a", "title": "A", "url": "https://example.com/a", "tier": "Tier 2", "score": 7}, + {"id": "src_b", "title": "B", "url": "https://example.com/a", "tier": "Tier 2", "score": 7}, + ] + } + + written = append_packet_sources(tmp_path / "sources.jsonl", packet) + + assert written == 1 + assert len((tmp_path / "sources.jsonl").read_text(encoding="utf-8").splitlines()) == 1 + + +def test_rebuild_sources_from_packets_dedupes_manual_packets(tmp_path: Path) -> None: + project = tmp_path / "project" + packets = project / "phase2" / "packets" + packets.mkdir(parents=True) + packet = { + "sources": [ + {"id": "src_001", "title": "A", "url": "https://example.com/a"}, + {"id": "src_002", "title": "A duplicate", "url": "https://example.com/a"}, + {"id": "src_003", "title": "Local", "url": "phase0/extracted/local.md"}, + ] + } + (packets / "ch01-a.json").write_text(json.dumps(packet, ensure_ascii=False), encoding="utf-8") + + count = rebuild_sources_from_packets(project) + + lines = (project / "phase2" / "sources.jsonl").read_text(encoding="utf-8").splitlines() + assert count == 2 + assert len(lines) == 2 + assert "src_001" in lines[0] + assert "src_003" in lines[1] diff --git a/tests/test_v020_cli.py b/tests/test_v020_cli.py new file mode 100644 index 0000000..2a85e47 --- /dev/null +++ b/tests/test_v020_cli.py @@ -0,0 +1,225 @@ +from __future__ import annotations + +import sys +import json +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +import scripts.dr as dr + + +def test_parser_exposes_python_core_commands() -> None: + parser = dr.build_parser() + + assert parser.parse_args(["init", "ADC 市场研究"]).cmd == "init" + assert parser.parse_args(["approve", "demo"]).cmd == "approve" + assert parser.parse_args(["frame", "demo"]).cmd == "frame" + assert parser.parse_args(["review", "demo"]).cmd == "review" + assert parser.parse_args(["skills", "list"]).cmd == "skills" + assert parser.parse_args(["methods", "list"]).cmd == "methods" + assert parser.parse_args(["research", "demo", "--workers", "6", "--dry-run"]).cmd == "research" + assert parser.parse_args(["research", "demo", "--execute-packets"]).execute_packets is True + assert parser.parse_args(["research", "demo", "--allow-search-fallback"]).allow_search_fallback is True + assert parser.parse_args(["research", "demo", "--build-briefs"]).build_briefs is True + assert parser.parse_args(["research", "demo", "--assemble-chapters"]).assemble_chapters is True + assert parser.parse_args(["run", "demo", "--dry-run"]).cmd == "run" + assert parser.parse_args(["finalize", "demo", "--legacy-translate", "--dry-run"]).legacy_translate is True + + +def test_models_json_includes_task_types(capsys) -> None: + args = dr.build_parser().parse_args(["models", "--profile", "medium", "--json"]) + + assert dr.cmd_models(args) == 0 + + out = capsys.readouterr().out + assert '"task_types"' in out + assert '"evidence_packet"' in out + + +def test_prompt_uses_canonical_codex_template(capsys) -> None: + args = dr.build_parser().parse_args(["prompt", "dr-run", "demo"]) + + assert dr.cmd_prompt(args) == 0 + + out = capsys.readouterr().out + assert "surface adapter for v0.20" in out + assert "Do not spawn Codex subagents" in out + + +def test_research_build_briefs_does_not_overwrite_existing_packets(tmp_path: Path) -> None: + project = tmp_path / "project" + (project / "phase1").mkdir(parents=True) + (project / "phase2/packets").mkdir(parents=True) + (project / "manifest.json").write_text( + '{"research_method": "mckinsey_market", "phase1": {"approved": true}, "phase2": {}}\n', + encoding="utf-8", + ) + (project / "phase1/framework.md").write_text( + "## 第1章 临床证据正在重塑需求判断\n\n研究思路。", + encoding="utf-8", + ) + packet_path = project / "phase2/packets/ch01-literature.json" + packet = { + "task_id": "ch01-literature", + "claims": [{"claim": "真实证据不能被 skeleton 覆盖", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "证据"}], + "counter_evidence": [{"claim": "限制", "source_ids": ["src_002"]}], + "source_ids": ["src_001", "src_002"], + "source_quality_notes": ["src_001 Tier 1"], + "open_questions": [], + "raw_quotes_or_notes": [], + } + packet_path.write_text(json.dumps(packet, ensure_ascii=False), encoding="utf-8") + + args = dr.build_parser().parse_args(["research", str(project), "--build-briefs"]) + assert dr.cmd_research(args) == 0 + + assert "真实证据不能被 skeleton 覆盖" in packet_path.read_text(encoding="utf-8") + + +def test_packet_state_counts_ignores_stale_errors_for_ready_packets(tmp_path: Path) -> None: + project = tmp_path / "project" + (project / "phase2/packets").mkdir(parents=True) + (project / "phase2/packet_errors").mkdir(parents=True) + packet = { + "task_id": "ch01-literature", + "claims": [{"claim": "已补齐", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "证据"}], + "counter_evidence": [{"claim": "限制", "source_ids": ["src_001"]}], + "source_ids": ["src_001"], + "source_quality_notes": ["Tier 1"], + "open_questions": [], + "raw_quotes_or_notes": [], + "sources": [{"id": "src_001", "title": "来源", "url": "https://example.com"}], + } + (project / "phase2/packets/ch01-literature.json").write_text( + json.dumps(packet, ensure_ascii=False), + encoding="utf-8", + ) + (project / "phase2/packet_errors/ch01-literature.json").write_text( + '{"status":"failed"}\n', + encoding="utf-8", + ) + + counts = dr.packet_state_counts(project) + + assert counts["ready"] == 1 + assert counts["errors"] == 0 + assert counts["stale_errors"] == 1 + + +def test_run_existing_project_delegates_to_research_without_missing_args(tmp_path: Path) -> None: + project = tmp_path / "project" + (project / "phase1").mkdir(parents=True) + (project / "manifest.json").write_text( + '{"research_method": "mckinsey_market", "phase1": {"approved": true}, "phase2": {}}\n', + encoding="utf-8", + ) + (project / "phase1/framework.md").write_text( + "## 第1章 临床证据正在重塑需求判断\n\n研究思路。", + encoding="utf-8", + ) + + args = dr.build_parser().parse_args(["run", str(project), "--workers", "2"]) + + assert dr.cmd_run(args) == 0 + assert (project / "phase2/task_cards.json").exists() + + +def test_research_requires_phase1_approval_unless_overridden(tmp_path: Path) -> None: + project = tmp_path / "project" + (project / "phase1").mkdir(parents=True) + (project / "manifest.json").write_text( + '{"research_method": "mckinsey_market", "phase1": {"approved": false}, "phase2": {}}\n', + encoding="utf-8", + ) + (project / "phase1/framework.md").write_text( + "## 第1章 临床证据正在重塑需求判断\n\n研究思路。", + encoding="utf-8", + ) + + args = dr.build_parser().parse_args(["research", str(project)]) + + try: + dr.cmd_research(args) + except SystemExit as exc: + assert "Phase 1 is not approved" in str(exc) + else: + raise AssertionError("research should require phase1 approval by default") + + override = dr.build_parser().parse_args(["research", str(project), "--force"]) + assert dr.cmd_research(override) == 0 + + +def test_init_and_frame_create_executable_python_core_project(tmp_path: Path) -> None: + args = dr.build_parser().parse_args( + [ + "init", + "ADC 全球竞争格局", + "--slug", + "adc-global-landscape", + "--method", + "mckinsey_market", + "--projects-dir", + str(tmp_path), + ] + ) + + assert dr.cmd_init(args) == 0 + project = tmp_path / "adc-global-landscape" + manifest = json.loads((project / "manifest.json").read_text(encoding="utf-8")) + assert manifest["topic"] == "ADC 全球竞争格局" + assert manifest["research_method"] == "mckinsey_market" + assert manifest["work_language"] == "zh" + + frame_args = dr.build_parser().parse_args(["frame", str(project)]) + assert dr.cmd_frame(frame_args) == 0 + + framework = (project / "phase1/framework.md").read_text(encoding="utf-8") + assert "research_method: mckinsey_market" in framework + assert "## 第1章" in framework + assert "中文" in framework + + +def test_review_writes_phase3_critique(tmp_path: Path) -> None: + project = tmp_path / "project" + (project / "phase1").mkdir(parents=True) + (project / "phase2/drafts").mkdir(parents=True) + (project / "manifest.json").write_text( + '{"topic": "测试项目", "research_method": "mckinsey_market", "phase3": {}}\n', + encoding="utf-8", + ) + (project / "phase2/drafts/ch01.md").write_text("## 观点标题\n\n正文。[src_001]\n", encoding="utf-8") + (project / "phase2/sources.jsonl").write_text('{"id":"src_001","title":"来源"}\n', encoding="utf-8") + + args = dr.build_parser().parse_args(["review", str(project)]) + + assert dr.cmd_review(args) == 0 + critique = project / "phase3/critique.md" + assert critique.exists() + text = critique.read_text(encoding="utf-8") + assert "Phase 3 审校" in text + assert "src_001" in text + + +def test_run_new_topic_initializes_and_frames_project(tmp_path: Path) -> None: + args = dr.build_parser().parse_args( + [ + "run", + "GMP 整改咨询", + "--slug", + "gmp-remediation", + "--method", + "gmp_gap_assessment", + "--projects-dir", + str(tmp_path), + ] + ) + + assert dr.cmd_run(args) == 0 + project = tmp_path / "gmp-remediation" + assert (project / "manifest.json").exists() + assert (project / "phase1/framework.md").exists() diff --git a/tests/test_v020_runtime.py b/tests/test_v020_runtime.py new file mode 100644 index 0000000..4b69986 --- /dev/null +++ b/tests/test_v020_runtime.py @@ -0,0 +1,142 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.lib.model_config import resolve_model_profile +from scripts.runtime.roles import resolve_runtime_profile +from scripts.runtime.skills import SkillRegistry +from scripts.runtime.tasks import ( + TaskCard, + detect_dependency_cycles, + generate_task_cards, + validate_packet, + validate_task_cards, +) + + +def test_skill_registry_uses_agents_skills_as_canonical() -> None: + registry = SkillRegistry() + + names = registry.list_names() + + assert "search-strategy" in names + assert "search-gateway" in names + assert "source-quality" in names + assert "document-ingest" in names + assert "deep-research" in names + assert registry.validate()["ok"] is True + + +def test_model_profile_exposes_task_types_and_role_defaults() -> None: + resolved = resolve_model_profile(profile="medium") + + assert resolved["roles"]["dr_pm"] + assert resolved["task_types"]["source_discovery"] == "dr_searcher" + assert resolved["task_types"]["chapter_assembly"] == "dr_analyst" + + +def test_runtime_profile_resolves_task_model_and_skills() -> None: + runtime = resolve_runtime_profile(profile="medium") + + worker = runtime.role_for_task("evidence_packet") + + assert worker.name == "dr_analyst" + assert worker.model + assert "evidence-table" in worker.skills + assert "search-gateway" in worker.skills + assert worker.max_concurrency >= 1 + + +def test_generate_task_cards_from_chinese_framework() -> None: + framework = """ +# 研究框架 + +## 第1章 GLP-1 产业链的增量来自适应症扩张 + +研究思路：围绕临床、监管、竞争格局和生产供应链展开。 + +## 第2章 供应链瓶颈决定国产替代窗口 + +研究思路：围绕专利、上游原料、产能和中国市场展开。 +""" + + cards = generate_task_cards("glp1-test", framework, axes=["clinical", "regulatory"]) + + assert [card.task_id for card in cards] == [ + "ch01-clinical", + "ch01-regulatory", + "ch02-clinical", + "ch02-regulatory", + ] + assert cards[0].output_packet == "phase2/packets/ch01-clinical.json" + + +def test_task_card_validation_rejects_duplicates_and_cycles() -> None: + cards = [ + TaskCard(task_id="a", chapter_ids=["ch01"], topic_axis="clinical", questions=["q"], search_routes=["scholar"], output_packet="phase2/packets/a.json", dependencies=["b"]), + TaskCard(task_id="b", chapter_ids=["ch01"], topic_axis="regulatory", questions=["q"], search_routes=["general"], output_packet="phase2/packets/b.json", dependencies=["a"]), + ] + + with pytest.raises(ValueError, match="dependency cycle"): + detect_dependency_cycles(cards) + + with pytest.raises(ValueError, match="duplicate task_id"): + validate_task_cards([cards[0], cards[0]]) + + +def test_packet_validation_requires_sources_and_counter_evidence() -> None: + packet = { + "task_id": "ch01-clinical", + "claims": [{"claim": "结论", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "证据"}], + "counter_evidence": [], + "source_ids": ["src_001"], + "source_quality_notes": ["Tier 1"], + "open_questions": [], + "raw_quotes_or_notes": ["Original English excerpt allowed."], + } + + with pytest.raises(ValueError, match="counter_evidence"): + validate_packet(packet) + + packet["counter_evidence"] = [{"claim": "限制", "source_ids": ["src_002"]}] + with pytest.raises(ValueError, match="not declared"): + validate_packet(packet) + + packet["source_ids"].append("src_002") + validate_packet(packet) + + +def test_skill_sync_copies_to_adapter_dirs(tmp_path: Path) -> None: + canonical = tmp_path / "skills" + target = tmp_path / "adapter" / "skills" + source_skill = canonical / "demo" + source_skill.mkdir(parents=True) + (source_skill / "SKILL.md").write_text("---\nname: demo\n---\n\nBody\n", encoding="utf-8") + + registry = SkillRegistry(canonical_dir=canonical) + copied = registry.sync_to([target]) + + assert copied == 1 + assert (target / "demo" / "SKILL.md").read_text(encoding="utf-8").endswith("Body\n") + + +def test_skill_sync_skips_canonical_dir_to_avoid_deleting_source(tmp_path: Path) -> None: + canonical = tmp_path / "skills" + source_skill = canonical / "demo" + source_skill.mkdir(parents=True) + (source_skill / "SKILL.md").write_text("---\nname: demo\n---\n\nBody\n", encoding="utf-8") + + registry = SkillRegistry(canonical_dir=canonical) + copied = registry.sync_to([canonical]) + + assert copied == 0 + assert (source_skill / "SKILL.md").exists() diff --git a/tests/test_v020_workers.py b/tests/test_v020_workers.py new file mode 100644 index 0000000..be65888 --- /dev/null +++ b/tests/test_v020_workers.py @@ -0,0 +1,165 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from scripts.runtime.roles import resolve_runtime_profile +from scripts.runtime.tasks import TaskCard, validate_packet +from scripts.runtime.workers import PacketWorker, build_packet_user_prompt, run_packet_workers + + +class FakeClient: + def __init__(self, response: dict) -> None: + self.response = response + self.calls: list[dict[str, object]] = [] + + def chat_complete(self, **kwargs) -> str: + self.calls.append(kwargs) + return json.dumps(self.response, ensure_ascii=False) + + +class SequenceClient: + def __init__(self, responses: list[str]) -> None: + self.responses = responses + self.calls: list[dict[str, object]] = [] + + def chat_complete(self, **kwargs) -> str: + self.calls.append(kwargs) + if self.responses: + return self.responses.pop(0) + return "not json" + + +class TaggedClient: + def __init__(self, responses_by_tag: dict[str, str]) -> None: + self.responses_by_tag = responses_by_tag + self.calls: list[dict[str, object]] = [] + + def chat_complete(self, **kwargs) -> str: + self.calls.append(kwargs) + return self.responses_by_tag.get(str(kwargs.get("tag")), "not json") + + +def sample_card() -> TaskCard: + return TaskCard( + task_id="ch01-clinical", + chapter_ids=["ch01"], + topic_axis="clinical", + questions=["围绕临床证据提炼结论。"], + search_routes=["scholar", "general"], + output_packet="phase2/packets/ch01-clinical.json", + ) + + +def second_card() -> TaskCard: + return TaskCard( + task_id="ch02-market", + chapter_ids=["ch02"], + topic_axis="market", + questions=["围绕市场证据提炼结论。"], + search_routes=["news", "general"], + output_packet="phase2/packets/ch02-market.json", + ) + + +def valid_response() -> dict: + return { + "task_id": "ch01-clinical", + "claims": [{"claim": "临床证据支持需求增长", "source_ids": ["src_001"]}], + "evidence_items": [{"source_id": "src_001", "summary": "III 期结果支持主要终点。"}], + "counter_evidence": [{"claim": "长期安全性仍需随访", "source_ids": ["src_002"]}], + "source_ids": ["src_001", "src_002"], + "source_quality_notes": ["src_001 Tier 1; src_002 Tier 2"], + "open_questions": [], + "raw_quotes_or_notes": ["Original English evidence note is allowed."], + } + + +def test_build_packet_prompt_contains_card_and_chinese_policy() -> None: + prompt = build_packet_user_prompt(sample_card()) + + assert "ch01-clinical" in prompt + assert "中文" in prompt + assert "scholar" in prompt + + +def test_packet_worker_generates_valid_packet_with_fake_client(tmp_path: Path) -> None: + runtime = resolve_runtime_profile(profile="medium") + role = runtime.role_for_task("evidence_packet") + fake = FakeClient(valid_response()) + worker = PacketWorker(role=role, client=fake) + + packet = worker.run(sample_card()) + + validate_packet(packet) + assert fake.calls[0]["model"] == role.model + assert "search-strategy" in fake.calls[0]["system"] + + +def test_run_packet_workers_writes_packet_files(tmp_path: Path) -> None: + project = tmp_path / "project" + fake = FakeClient(valid_response()) + runtime = resolve_runtime_profile(profile="medium") + + count = run_packet_workers( + project_root=project, + cards=[sample_card()], + runtime=runtime, + client_factory=lambda _role: fake, + workers=2, + ) + + packet_path = project / "phase2/packets/ch01-clinical.json" + assert count == 1 + assert packet_path.exists() + validate_packet(json.loads(packet_path.read_text(encoding="utf-8"))) + + +def test_packet_worker_repairs_malformed_json_once() -> None: + runtime = resolve_runtime_profile(profile="medium") + role = runtime.role_for_task("evidence_packet") + fake = SequenceClient(["这里是说明，不是 JSON", json.dumps(valid_response(), ensure_ascii=False)]) + worker = PacketWorker(role=role, client=fake) + + packet = worker.run(sample_card()) + + validate_packet(packet) + assert len(fake.calls) == 2 + assert "修复" in str(fake.calls[1]["user"]) + assert fake.calls[1]["temperature"] == 0 + assert fake.calls[1]["tag"] == "packet-repair:ch01-clinical" + + +def test_run_packet_workers_writes_error_file_without_aborting_batch(tmp_path: Path) -> None: + project = tmp_path / "project" + runtime = resolve_runtime_profile(profile="medium") + valid = json.dumps(valid_response(), ensure_ascii=False) + fake = TaggedClient( + { + "packet:ch01-clinical": valid, + "packet:ch02-market": "not json", + "packet-repair:ch02-market": "still not json", + } + ) + + count = run_packet_workers( + project_root=project, + cards=[sample_card(), second_card()], + runtime=runtime, + client_factory=lambda _role: fake, + workers=2, + ) + + assert count == 1 + assert (project / "phase2/packets/ch01-clinical.json").exists() + error_path = project / "phase2/packet_errors/ch02-market.json" + assert error_path.exists() + error = json.loads(error_path.read_text(encoding="utf-8")) + assert error["task_id"] == "ch02-market" + assert error["status"] == "failed" + assert "worker response does not contain a JSON object" in error["error"] diff --git a/tests/test_zenmux_model_normalization.py b/tests/test_zenmux_model_normalization.py new file mode 100644 index 0000000..370e6b0 --- /dev/null +++ b/tests/test_zenmux_model_normalization.py @@ -0,0 +1,68 @@ +from scripts.lib.zenmux_client import ZenMuxClient, normalize_zenmux_model + + +def test_normalize_zenmux_adapter_models() -> None: + assert normalize_zenmux_model("zenmux/openai/gpt-5.4-mini") == "openai/gpt-5.4-mini" + assert ( + normalize_zenmux_model("zenmux/google/gemini-3.1-pro-preview") + == "google/gemini-3.1-pro-preview" + ) + assert ( + normalize_zenmux_model("zenmux-anthropic/claude-sonnet-4-6") + == "anthropic/claude-sonnet-4.6" + ) + assert ( + normalize_zenmux_model("anthropic/claude-opus-4.7") + == "anthropic/claude-opus-4.7" + ) + + +class _FakeResponse: + status_code = 200 + text = '{"choices":[{"message":{"content":"OK"}}]}' + + def json(self) -> dict: + return {"choices": [{"message": {"content": "OK"}}], "usage": {}} + + +class _RecordingClient: + def __init__(self) -> None: + self.bodies: list[dict] = [] + + def post(self, _url: str, *, json: dict, headers: dict) -> _FakeResponse: + self.bodies.append(json) + return _FakeResponse() + + +def test_opus_47_probe_omits_deprecated_temperature_param() -> None: + client = ZenMuxClient(api_key="test") + recorder = _RecordingClient() + client._client = recorder # type: ignore[assignment] + + client.chat_complete( + model="zenmux-anthropic/claude-opus-4-7", + system="Health check.", + user="Reply OK.", + temperature=0, + max_tokens=16, + ) + + assert recorder.bodies[0]["model"] == "anthropic/claude-opus-4.7" + assert "temperature" not in recorder.bodies[0] + + +def test_sonnet_keeps_temperature_param() -> None: + client = ZenMuxClient(api_key="test") + recorder = _RecordingClient() + client._client = recorder # type: ignore[assignment] + + client.chat_complete( + model="zenmux-anthropic/claude-sonnet-4-6", + system="Health check.", + user="Reply OK.", + temperature=0.2, + max_tokens=16, + ) + + assert recorder.bodies[0]["model"] == "anthropic/claude-sonnet-4.6" + assert recorder.bodies[0]["temperature"] == 0.2 diff --git a/uv.lock b/uv.lock index 336346e..db012b4 100644 --- a/uv.lock +++ b/uv.lock @@ -361,7 +361,7 @@ wheels = [ [[package]] name = "deep-research" -version = "0.12.0" +version = "0.20.0" source = { virtual = "." } dependencies = [ { name = "biopython" }, @@ -374,6 +374,7 @@ dependencies = [ { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "pandas", version = "3.0.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "pillow" }, + { name = "pymupdf" }, { name = "pypdf" }, { name = "python-dateutil" }, { name = "pyyaml" }, @@ -398,6 +399,7 @@ requires-dist = [ { name = "numpy", specifier = ">=1.26.0" }, { name = "pandas", specifier = ">=2.1.0" }, { name = "pillow", specifier = ">=10.0.0" }, + { name = "pymupdf", specifier = ">=1.26.0" }, { name = "pypdf", specifier = ">=6.10.2" }, { name = "pytest", marker = "extra == 'dev'", specifier = ">=7.4.0" }, { name = "python-dateutil", specifier = ">=2.9.0" }, @@ -1285,6 +1287,22 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" }, ] +[[package]] +name = "pymupdf" +version = "1.27.2.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/22/32/708bedc9dde7b328d45abbc076091769d44f2f24ad151ad92d56a6ec142b/pymupdf-1.27.2.3.tar.gz", hash = "sha256:7a92faa25129e8bbec5e50eeb9214f187665428c31b05c4ef6e36c58c0b1c6d2", size = 85759618, upload-time = "2026-04-24T14:13:14.42Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/dc/09/ddbdfa7ee91fbabd6f63d7d744884cbdfe3e7ff9b8604749fb38bddf5c5d/pymupdf-1.27.2.3-cp310-abi3-macosx_10_9_x86_64.whl", hash = "sha256:fc1bc3cae6e9e150b0dbb0a9221bdfd411d65f0db2fe359eaa22467d7cc2a05f", size = 24002636, upload-time = "2026-04-24T14:09:17.459Z" }, + { url = "https://files.pythonhosted.org/packages/01/89/3f8edd6c4f50ca370e2a2f2a3011face36f3760728ffe76dffec91c0fca0/pymupdf-1.27.2.3-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:660d93cb6da5bbddf11d3982ae27745dd3a9902d9f24cdb69adab83962294b5a", size = 23278238, upload-time = "2026-04-24T14:09:32.882Z" }, + { url = "https://files.pythonhosted.org/packages/c3/26/b7e5a70eb83bd189f8b5df87ec442746b992f2f632662839b288170d357d/pymupdf-1.27.2.3-cp310-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:1dd460a3ae4597a755f00a3bd9771f5ebf1531dc111f6a36bf05dd00a6b84425", size = 24333923, upload-time = "2026-04-24T14:09:47.341Z" }, + { url = "https://files.pythonhosted.org/packages/e4/a0/aa1ee2240f29481a04a827c313333b4ecd8a14d6ac3e15d3f41a30574781/pymupdf-1.27.2.3-cp310-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:857842b4888827bd6155a1131341b2822a7ebe9a8c15a975fd7d490d7a64a30c", size = 24963198, upload-time = "2026-04-24T14:10:07.408Z" }, + { url = "https://files.pythonhosted.org/packages/69/49/4f742451f980840829fc00ba158bebb25d389c846d8f4f8c65936ee55de8/pymupdf-1.27.2.3-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:580983849c64a08d08344ca3d1580e87c01f046a8392421797bc850efd72a5b6", size = 25184609, upload-time = "2026-04-24T14:10:22.911Z" }, + { url = "https://files.pythonhosted.org/packages/f6/3f/3853d6608f394faf6eec2bd4e8ea9f6a00beea329b071abdb29f4164cc3d/pymupdf-1.27.2.3-cp310-abi3-win32.whl", hash = "sha256:a5c1088a87189891a4946ab314a14b7934ac4c5b6077f7e74ebee956f8906d0e", size = 18019286, upload-time = "2026-04-24T14:10:34.239Z" }, + { url = "https://files.pythonhosted.org/packages/44/47/5fb10fe73f96b31253a41647c362ea9e0380920bddf16028414a051247fc/pymupdf-1.27.2.3-cp310-abi3-win_amd64.whl", hash = "sha256:d20f68ef15195e073071dbc4ae7455257c7889af7584e39df490c0a92728526e", size = 19249102, upload-time = "2026-04-24T14:10:46.72Z" }, + { url = "https://files.pythonhosted.org/packages/53/a4/b9e91aac82293f9c954654c85581ee8212b5b05efadc534b581141241e6f/pymupdf-1.27.2.3-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:77691604c5d1d0233827139bbcdea61fd57879c84712b8e49b1f45520f7ab9c2", size = 25000393, upload-time = "2026-04-24T14:11:01.669Z" }, +] + [[package]] name = "pyparsing" version = "3.3.2"