diff --git a/.agents/agents.md b/.agents/agents.md index 0c4c61f..d5d0f7b 100644 --- a/.agents/agents.md +++ b/.agents/agents.md @@ -1,64 +1,88 @@ # Deep Research Agent Team -This file defines Antigravity roles. Do not put detailed skills or long process rules here; use `.agents/skills/` and `.agents/workflows/` for those. +This file defines Antigravity roles only. Put persistent constraints in `.agents/rules/`, reusable capabilities in `.agents/skills/`, and phase sequencing in `.agents/workflows/`. ## Research Manager Primary model: Gemini 3 Flash. -Responsibilities: +Purpose: -- Keep the phase task list current. +- Manage the task list, phase transitions, model switches, and approval gates. - Load the relevant rules, skills, and workflow. -- Ask the user to switch models before heavyweight phase work. -- Ensure artifacts are written under `projects//`. -- Stop at Phase 1 and Phase 3 approval gates. +- Keep all artifacts under `projects//`. Must not: -- Invent sources or claim searches without receipts. +- Perform deep reasoning that belongs to a phase specialist. +- Claim that search or verification happened without receipts. - Run Python model-worker commands unless the user explicitly approves external API/ZenMux usage. -- Hide uncertainty or missing evidence. ## Phase 0-1 Strategist Primary model: Claude Opus 4.6 (Thinking). -Responsibilities: +Purpose: -- Interpret user materials and intended audience. -- Select the research method and success criteria. -- Build the chapter architecture, hypotheses, and validation plan. -- Produce `phase1/material_brief.md`, `framework.md`, `research_brief.md/json`, and search logs. +- Interpret materials, audience, and decision purpose. +- Select the most appropriate research method or method mix. +- Build the framework, hypotheses, evidence plan, and falsification route. + +Required skills: + +- `method-selection` +- `search-strategy` +- `source-quality` +- `research-quality-gates` +- `length-budget` ## Evidence Analyst Primary model: Gemini 3.1 Pro (Low). -Responsibilities: +Purpose: - Execute task-card research. -- Use approved search tools and maintain `phase2/search_log.jsonl`. -- Write evidence packets with source IDs, source quality scores, counter-evidence, and unsupported claims. -- Draft chapters only from approved chapter briefs and compressed findings. +- Maintain search logs and source ledgers. +- Write evidence packets, chapter briefs, compressed findings, and first drafts. + +Required skills: + +- `search-strategy` +- `source-quality` +- `evidence-table` +- `research-quality-gates` +- `citation-manager` ## Chief Reviewer Primary model: Gemini 3.1 Pro (High). -Responsibilities: +Purpose: -- Audit logic, MECE structure, source quality, unsupported claims, and counter-evidence. -- Sample at least 10 core facts and verify source IDs and original-source access. -- Produce `phase3/critique.md` with a `go`, `rework`, or `fail` decision. +- Audit method fit, logic, structure, evidence quality, counter-evidence, and unsupported claims. +- Produce a clear go / rework / fail decision. + +Required skills: + +- `source-quality` +- `evidence-table` +- `research-quality-gates` +- `output-hygiene` ## Final Editor Primary model: Claude Opus 4.6 (Thinking). -Responsibilities: +Purpose: -- Assemble the final Chinese report from approved drafts and sources. +- Produce the final Chinese report from approved drafts and verified sources. - Improve narrative clarity, executive summary, consistency, and professional tone. -- Produce `phase4/final_zh.md`, `editorial_notes.md`, and `final_fact_check.md`. -- Avoid adding new facts unless sources and search logs are added first. +- Preserve source traceability and downgrade unsupported claims. + +Required skills: + +- `citation-manager` +- `research-quality-gates` +- `humanizer-cn` +- `output-hygiene` diff --git a/.agents/rules/deep-research-antigravity.md b/.agents/rules/deep-research-antigravity.md index d680369..ad7c31e 100644 --- a/.agents/rules/deep-research-antigravity.md +++ b/.agents/rules/deep-research-antigravity.md @@ -14,11 +14,13 @@ When operating this repository from Google Antigravity, use Antigravity as the p ## Anti-Hallucination Contract - No tool receipt, no search claim. The agent may not write that it has searched, checked, verified, or confirmed anything unless a search/browser/terminal/MCP tool call actually happened and the result is logged. -- No source ID, no factual claim. Every concrete fact in drafts must map to a `source_id` in `sources.jsonl` or the current phase ledger. +- No source ID, no factual claim. Every concrete fact in drafts must map to a `source_id` in `sources.jsonl` and a row in `claims_ledger.jsonl`, or be visibly marked as unverified. - No snippet laundering. Search result snippets, AI summaries, and memory are only leads; they cannot support final claims. - Failed access must be explicit. If a page, PDF, registry, patent, or filing cannot be opened, mark it as inaccessible and do not quote exact values from it. - Each phase must maintain `phaseX/search_log.md` or `phaseX/search_log.jsonl`. -- Each evidence packet must include `search_receipts`, `sources`, `counter_evidence`, and `unsupported_claims`. +- Each evidence packet must include `search_receipts`, `sources`, `evidence_spans`, `counter_evidence`, and `unsupported_claims`. +- Phase 2 must maintain `claims_ledger.jsonl`, `coverage_matrix.md`, and `rejected_sources.jsonl`. +- Before resuming or handing off work, update `continuation_state.json`. - When evidence is thin, write "该观点证据不足，待进一步验证" rather than smoothing over the gap. ## Quota Discipline diff --git a/.agents/skills/antigravity-surface-adapter/SKILL.md b/.agents/skills/antigravity-surface-adapter/SKILL.md index 08ddb9e..d3935b5 100644 --- a/.agents/skills/antigravity-surface-adapter/SKILL.md +++ b/.agents/skills/antigravity-surface-adapter/SKILL.md @@ -16,19 +16,20 @@ The Deep Research method still comes from this repo: - Follow `AGENTS.md` for evidence, source tiers, word budgets, pause points, and output hygiene. - Load project skills from `.agents/skills/*` as needed. - Write all artifacts under `projects//`. -- Keep claims traceable to source IDs in `sources.jsonl`. +- Keep claims traceable through search receipts, source IDs, and `claims_ledger.jsonl`. ## Anti-Hallucination Contract This project treats Gemini-family research as high risk for false confidence. Follow these rules mechanically: 1. No tool receipt, no search claim. Do not write "I searched", "confirmed", "official data shows", or similar unless the tool call happened and is recorded. -2. No source ID, no factual claim. Every concrete fact needs a `source_id`. +2. No source ID, no factual claim. Every concrete fact needs a `source_id` and claim-ledger entry. 3. Search snippets are leads, not evidence. Open the original paper, filing, registry, patent, guideline, or company disclosure before citing. 4. Failed access is a finding. Write that the source could not be opened; do not infer exact numbers from inaccessible pages. 5. Log all searches in `phaseX/search_log.md` or `phaseX/search_log.jsonl`. 6. Keep an `unsupported_claims` list. It is better to expose uncertainty than to make the report look complete. -7. Before finishing each phase, sample at least 10 factual claims and verify that each has a source ID and opened source. +7. Keep `continuation_state.json` current so a resumed Antigravity session can continue from artifacts, not chat memory. +8. Before finishing each phase, sample at least 10 factual claims and verify that each has a source ID, opened source, evidence locator, and claim-ledger record. ## Antigravity Model Plan @@ -64,32 +65,39 @@ uv run python scripts/dr.py finalize --no-pdf --no-docx ## Native Runbook 1. Open the repository root in Antigravity. -2. Start with Gemini 3 Flash as Research Manager. Load `.agents/agents.md`, this skill, `AGENTS.md`, `mckinsey-method`, `search-strategy`, `source-quality`, `evidence-table`, `citation-manager`, `length-budget`, and `output-hygiene`. +2. Start with Gemini 3 Flash as Research Manager. Load `.agents/agents.md`, this skill, `AGENTS.md`, `method-selection`, `search-strategy`, `source-quality`, `evidence-table`, `research-quality-gates`, `citation-manager`, `length-budget`, and `output-hygiene`. 3. Create or confirm `projects//` and the phase folders. Use Python `init` only for scaffolding if helpful. 4. Phase 0-1: ask the user to switch to Claude Opus 4.6 (Thinking). Produce: - `phase1/material_brief.md` - `phase1/framework.md` +- `phase1/method_decision.md` - `phase1/research_brief.md` - `phase1/research_brief.json` - `phase1/search_log.md` +- `phase1/assumptions.md` - `phase1/unsupported_claims.md` 5. Pause for user confirmation. 6. Phase 2: ask the user to switch to Gemini 3.1 Pro (Low). Build evidence packets and chapter drafts without Python model workers: - `phase2/task_cards.json` -- `phase2/packets/*.json` +- `phase2/search_log.jsonl` - `phase2/sources.jsonl` +- `phase2/rejected_sources.jsonl` +- `phase2/claims_ledger.jsonl` +- `phase2/coverage_matrix.md` +- `phase2/packets/*.json` - `phase2/chapter_briefs/*.json` - `phase2/compressed_findings/*.json` - `phase2/drafts/chXX.md` -- `phase2/search_log.jsonl` - `phase2/unsupported_claims.md` -7. Phase 3: ask the user to switch to Gemini 3.1 Pro (High). Produce `phase3/critique.md`, with explicit go/rework/fail decision and a source-audit table for at least 10 core facts. +If a claim lacks support, use delta retrieval: write the gap, run targeted searches, update sources and the claim ledger, then either verify or visibly caveat the claim. + +7. Phase 3: ask the user to switch to Gemini 3.1 Pro (High). Produce `phase3/critique.md`, with explicit go/rework/fail decision, claim-ledger audit, contradiction audit, and a source-audit table for at least 10 core facts. 8. Pause for user decision. -9. Phase 4: ask the user to switch to Claude Opus 4.6 (Thinking). Produce `phase4/final_zh.md`, `phase4/editorial_notes.md`, and `phase4/final_fact_check.md`. Use deterministic renderers afterward for PDF/DOCX. +9. Phase 4: ask the user to switch to Claude Opus 4.6 (Thinking). Produce `phase4/final_zh.md`, `phase4/editorial_notes.md`, and `phase4/final_fact_check.md`. New facts require new receipts and claim-ledger rows. Use deterministic renderers afterward for PDF/DOCX. ## Search Strategy diff --git a/.agents/skills/evidence-table/SKILL.md b/.agents/skills/evidence-table/SKILL.md index 9661ed9..6e0024e 100644 --- a/.agents/skills/evidence-table/SKILL.md +++ b/.agents/skills/evidence-table/SKILL.md @@ -9,6 +9,51 @@ description: 证据矩阵规范。规定每条核心结论必须有对应的证 **每条结论必须可追溯**。报告中每一个有 [src_xxx] 标注的观点，都必须在对应章节的 evidence 文件中有一行记录。 +Antigravity native 模式下，证据不能只停留在模型上下文或章节草稿里。除章节 evidence markdown 外，还必须维护机器可审计的 claim ledger，让 Phase 3/4 可以逐条核验。 + +--- + +## Antigravity Native 证据落盘 + +Phase 2 必须至少维护以下文件： + +- `projects//phase2/search_log.jsonl`：检索、打开、抽取的回执 +- `projects//phase2/sources.jsonl`：稳定 source registry +- `projects//phase2/claims_ledger.jsonl`：原子 claim 台账 +- `projects//phase2/coverage_matrix.md`：章节/任务覆盖矩阵 +- `projects//phase2/unsupported_claims.md`：未证实或仅弱证据支持的观点 + +`claims_ledger.jsonl` 每行必须是一个原子事实或判断，字段至少包括： + +```json +{ + "claim_id": "ch03_C012", + "chapter": "ch03", + "claim_type": "fact|trend|comparison|causal|forecast|recommendation", + "claim": "...", + "supporting_source_ids": ["src_042", "src_087"], + "counter_source_ids": ["src_103"], + "evidence_spans": [ + { + "source_id": "src_042", + "locator": "Table 2", + "summary": "..." + } + ], + "confidence": "high|medium|low|unsupported", + "verification_status": "verified|partially_verified|conflicted|unsupported", + "needs_delta_retrieve": false, + "visible_caveat_required": false +} +``` + +正文、章节 evidence markdown、`claims_ledger.jsonl` 三者必须能互相对上： + +- 正文的 `Cxx/Fxx/Txx` ID 必须在 evidence markdown 和 `claims_ledger.jsonl` 中存在； +- `claims_ledger.jsonl` 中 `verification_status=unsupported` 的 claim 必须进入 `unsupported_claims.md`； +- `needs_delta_retrieve=true` 的 claim 必须补做定向检索，或在正文显式降级； +- Phase 4 不得新增未进入 claim ledger 的事实。 + --- ## 证据矩阵文件格式 diff --git a/.agents/skills/method-selection/SKILL.md b/.agents/skills/method-selection/SKILL.md new file mode 100644 index 0000000..d4e368a --- /dev/null +++ b/.agents/skills/method-selection/SKILL.md @@ -0,0 +1,157 @@ +--- +name: method-selection +description: Selects the appropriate research framework and analytical tools for biomedical, market, investment, CMC/GMP, clinical, R&D, BD, and management consulting topics instead of defaulting to MECE or McKinsey-style framing. +--- + +# Method Selection + +Use this skill before Phase 0-1 framing and whenever the user changes the report purpose. + +## Principle + +Do not default to McKinsey/MECE. MECE, SCQA, and pyramid writing are useful communication tools, not universal research methods. + +Select the method based on: + +- report purpose +- audience +- decision to support +- available materials +- evidence type +- regulatory or scientific risk +- output format + +## Method Router + +### Market, investment, or commercial strategy + +Use when the user asks about market opportunity, competition, investment thesis, BD opportunity, pricing, or commercialization. + +Methods and tools: + +- market sizing: TAM/SAM/SOM, bottom-up demand model, volume-price bridge +- competitive landscape: segmentation, product differentiation, launch timing, share shifts +- value chain: upstream supply, manufacturing bottlenecks, channel economics +- investment: thesis tree, scenario analysis, sensitivity analysis, risk-adjusted NPV where feasible +- transaction/BD: deal comps, licensing terms, patent cliff, strategic fit + +Outputs: + +- market map +- competitor table +- assumptions ledger +- upside/base/downside scenarios + +### Clinical, translational, or evidence review + +Use when the topic is efficacy, safety, trial design, disease area, standard of care, biomarker, or clinical development. + +Methods and tools: + +- PICO or PICOTS framing +- evidence hierarchy +- endpoint and comparator analysis +- trial design critique +- TPP and go/no-go criteria +- benefit-risk assessment + +Outputs: + +- clinical evidence matrix +- trial landscape +- endpoint comparability table +- evidence gaps and patient-selection risks + +### CMC, GMP, quality, or manufacturing operations + +Use when the topic involves process development, tech transfer, validation, inspection readiness, deviations, CAPA, sterility assurance, supply chain, or manufacturing risk. + +Methods and tools: + +- ICH / FDA / EMA / NMPA regulatory baseline mapping +- gap assessment +- FMEA or risk matrix +- process validation lifecycle +- control strategy mapping +- deviation/CAPA effectiveness review +- data integrity assessment + +Outputs: + +- gap register +- risk heatmap +- CAPA prioritization +- control strategy map +- readiness scorecard + +### R&D feasibility or technology assessment + +Use when the topic asks whether a technology, target, modality, platform, assay, or process is feasible. + +Methods and tools: + +- technology readiness level +- critical path analysis +- mechanism and modality fit +- experiment roadmap +- scale-up risk assessment +- IP and freedom-to-operate screening + +Outputs: + +- feasibility scorecard +- key experiments +- kill criteria +- technical risk register + +### Management, organization, or operating model + +Use when the topic involves organization, governance, operating cadence, capability building, performance management, or transformation. + +Methods and tools: + +- issue tree +- operating model design +- RACI / decision rights +- KPI tree +- process maturity assessment +- change management roadmap + +Outputs: + +- operating model options +- capability gap assessment +- implementation roadmap +- KPI and governance model + +### Policy, regulation, or access environment + +Use when the topic asks about policy, reimbursement, regulatory pathways, pricing access, or regional rules. + +Methods and tools: + +- policy timeline +- stakeholder map +- regulatory pathway comparison +- access and reimbursement framework +- scenario analysis by jurisdiction + +Outputs: + +- jurisdiction comparison +- policy impact map +- regulatory milestone table +- access risks + +## Phase 0-1 Output Requirements + +Write a method decision note in `phase1/research_brief.md`: + +- selected method +- why it fits +- methods rejected and why +- evidence types needed +- search routes +- expected output artifacts + +If the topic spans multiple scenarios, combine methods explicitly and define which chapters use which method. diff --git a/.agents/skills/research-quality-gates/SKILL.md b/.agents/skills/research-quality-gates/SKILL.md new file mode 100644 index 0000000..adadd6a --- /dev/null +++ b/.agents/skills/research-quality-gates/SKILL.md @@ -0,0 +1,212 @@ +--- +name: research-quality-gates +description: Applies stage gates for Antigravity-native Deep Research: search receipts, source access, claims ledger, triangulation, contradiction search, continuation state, and final assembly checks. +--- + +# Research Quality Gates + +Use this skill after every phase boundary and before any user-facing "done" claim. It is designed for Antigravity-native runs where model work happens inside Antigravity, while this repository provides the evidence discipline. + +## Core Principle + +Evidence must persist outside the model context. A claim is not verified because the model remembers it, summarized it, or saw it in a search snippet. It is verified only when the artifact trail contains: + +1. a search receipt, +2. an opened original source or explicit access failure, +3. a registered `source_id`, +4. an evidence span or data locator, +5. a claim-ledger record linking the claim to supporting and counter evidence. + +## Required Artifacts + +Create these files when the relevant phase begins. Empty files are acceptable at creation time, but they must be populated before the phase gate passes. + +| Phase | Artifact | Purpose | +|---|---|---| +| Phase 1 | `phase1/method_decision.md` | Selected method, rejected methods, evidence types, and search routes. | +| Phase 1 | `phase1/assumptions.md` | Material assumptions and scope assumptions that need validation. | +| Phase 2 | `phase2/search_log.jsonl` | One row per search/open/extract action. | +| Phase 2 | `phase2/sources.jsonl` | Stable source registry with scores and tiers. | +| Phase 2 | `phase2/rejected_sources.jsonl` | Rejected or low-quality sources with reasons. | +| Phase 2 | `phase2/claims_ledger.jsonl` | Atomic factual and analytical claims with verification status. | +| Phase 2 | `phase2/coverage_matrix.md` | Coverage of questions, chapters, methods, and evidence gaps. | +| Phase 2 | `phase2/unsupported_claims.md` | Claims that could not be verified or need user-visible caveats. | +| All phases | `continuation_state.json` | Current phase, completed sections, artifact paths, open gaps, and next actions. | +| Phase 4 | `phase4/final_fact_check.md` | Final audit showing each core fact exists in the verified claim ledger. | + +## Search Receipt Gate + +Every search or retrieval action must write a row to `search_log.jsonl`. + +Required fields: + +```json +{ + "receipt_id": "srch_0001", + "timestamp": "YYYY-MM-DDTHH:MM:SSZ", + "tool": "search-cli|browser|project-search|other", + "mode": "academic|scholar|patents|news|extract|general|deep", + "query_or_url": "...", + "purpose": "which task/card/chapter this supports", + "result_count": 10, + "opened_urls": ["https://..."], + "status": "ok|partial|failed", + "failure_reason": null +} +``` + +Gate fails if a model says it searched, confirmed, checked, extracted, opened, or verified a fact without a corresponding receipt. + +## Source Access Gate + +For any source used as evidence, `sources.jsonl` must record access status. + +Required additional fields: + +```json +{ + "id": "src_042", + "search_receipt_ids": ["srch_0001"], + "raw_url": "https://...", + "canonical_url": "https://...", + "title": "...", + "publication_date": "YYYY-MM-DD", + "source_type": "paper|regulator|trial_registry|patent|filing|database|consulting|media|other", + "tier": 1, + "score": 8.6, + "access_status": "opened_original|opened_abstract|paywalled|failed|snippet_only", + "evidence_locator": "page/table/section/trial id/patent claim", + "independence_cluster": "cluster_...", + "notes": "..." +} +``` + +`snippet_only` sources cannot support final claims. Paywalled or abstract-only sources can be used only with a visible caveat or a second opened source that carries the same fact. + +## Claim Ledger Gate + +Each chapter draft must be backed by `claims_ledger.jsonl`. Store atomic claims, not paragraphs. + +Required fields: + +```json +{ + "claim_id": "ch03_C012", + "chapter": "ch03", + "claim_type": "fact|trend|comparison|causal|forecast|recommendation", + "claim": "...", + "supporting_source_ids": ["src_042", "src_087"], + "counter_source_ids": ["src_103"], + "evidence_spans": [ + { + "source_id": "src_042", + "locator": "Table 2", + "summary": "..." + } + ], + "independence_clusters": ["cluster_a", "cluster_b"], + "confidence": "high|medium|low|unsupported", + "verification_status": "verified|partially_verified|conflicted|unsupported", + "needs_delta_retrieve": false, + "visible_caveat_required": false +} +``` + +Gate fails if: + +- a core claim has fewer than 2 independent Tier 1-2 supporting sources; +- a claim has source IDs but no evidence locator; +- supporting sources all come from the same independence cluster; +- a conflicted or unsupported claim is written as a settled conclusion. + +## Triangulation Gate + +Counting URLs is not enough. Sources are independent only when they do not trace back to the same press release, same trial registry entry, same company deck, same sell-side note, or same syndicated article. + +For core conclusions, require at least two of these source families where available: + +- regulator / official registry, +- peer-reviewed paper or systematic review, +- company filing / annual report / exchange disclosure, +- patent or legal record, +- independent database, +- reputable industry or consulting report, +- independent expert or professional media analysis. + +If a field has only one source family available, mark the limitation explicitly in `unsupported_claims.md` and in the report limitations section. + +## Contradiction Gate + +Every chapter requires at least one deliberate counter-search or falsification pass. Record it in `search_log.jsonl` and summarize it in the chapter brief. + +Minimum counter-evidence record: + +```json +{ + "claim_id": "ch03_C012", + "counter_query": "...", + "counter_source_ids": ["src_103"], + "result": "none_found|weak_counter|material_counter", + "impact": "keep|qualify|rewrite|delete" +} +``` + +Gate fails if the chapter contains no counter-evidence section, no counter-search receipt, or no decision about how contradictions affected the draft. + +## Coverage Gate + +Before drafting, create `phase2/coverage_matrix.md` with one row per chapter/task axis: + +| Chapter | Method | Core Question | Required Evidence | Found Evidence | Gaps | Decision | +|---|---|---|---|---|---|---| + +Gate fails if a chapter is drafted while its method, required evidence, or gaps are blank. + +## Delta-Retrieve Protocol + +When a gap appears, do not patch it from memory. Create a targeted delta task: + +1. write the gap in `coverage_matrix.md` or `claims_ledger.jsonl`; +2. run 1-3 targeted searches with explicit query purpose; +3. register any usable sources; +4. update the relevant claim record; +5. if still unsupported, keep the caveat visible. + +Delta retrieval is mandatory when Phase 3 finds a critical evidence gap. + +## Continuation Protocol + +For long reports or interrupted runs, keep `projects//continuation_state.json` current. + +Minimum fields: + +```json +{ + "version": "0.20", + "slug": "...", + "current_phase": "phase2", + "active_model": "Gemini 3.1 Pro (Low)", + "completed_artifacts": ["phase2/task_cards.json"], + "open_gates": ["claim_ledger_gate"], + "artifact_paths": { + "sources": "phase2/sources.jsonl", + "claims": "phase2/claims_ledger.jsonl", + "search_log": "phase2/search_log.jsonl" + }, + "open_questions": [], + "next_actions": [] +} +``` + +Before resuming a project, read this state and the latest artifacts. Do not rely on chat history alone. + +## Final Assembly Gate + +Phase 4 must prove that final facts are a subset of verified claims: + +- Sample at least 20 high-impact facts or all core claims, whichever is smaller. +- For each sampled fact, record `claim_id`, `source_ids`, verification status, and final wording decision in `phase4/final_fact_check.md`. +- New facts introduced during editing require new search receipts and claim-ledger records. +- Delete or caveat any unsupported factual claim before rendering PDF/DOCX. + +Do not render final deliverables until the final assembly gate passes. diff --git a/.agents/skills/source-quality/SKILL.md b/.agents/skills/source-quality/SKILL.md index e96b8f3..9b930b4 100644 --- a/.agents/skills/source-quality/SKILL.md +++ b/.agents/skills/source-quality/SKILL.md @@ -78,7 +78,52 @@ description: 信源质量评分系统（0-10 分制）与黑名单机制。规 --- -## 三、黑名单（直接拒绝入库） +## 三、检索回执与原文访问 + +Gemini / Antigravity 模式下，信源质量评分必须和检索回执绑定。任何来源进入 `sources.jsonl` 前，必须能追溯到 `search_log.jsonl` 中的至少一条记录。 + +### search_log.jsonl 最低字段 + +```json +{ + "receipt_id": "srch_0001", + "timestamp": "YYYY-MM-DDTHH:MM:SSZ", + "tool": "search-cli|browser|project-search|other", + "mode": "academic|scholar|patents|news|extract|general|deep", + "query_or_url": "...", + "purpose": "which task/card/chapter this supports", + "result_count": 10, + "opened_urls": ["https://..."], + "status": "ok|partial|failed", + "failure_reason": null +} +``` + +### sources.jsonl 追加字段 + +```json +{ + "id": "src_042", + "search_receipt_ids": ["srch_0001"], + "raw_url": "https://...", + "canonical_url": "https://...", + "source_type": "paper|regulator|trial_registry|patent|filing|database|consulting|media|other", + "access_status": "opened_original|opened_abstract|paywalled|failed|snippet_only", + "evidence_locator": "page/table/section/trial id/patent claim", + "independence_cluster": "cluster_..." +} +``` + +硬规则： + +- `snippet_only` 只能作为发现线索，不能支撑正文事实。 +- `failed` 必须保留失败原因，不能根据标题或搜索摘要推断具体数据。 +- `paywalled` / `opened_abstract` 可以用于发现方向，但核心结论还需要至少一个可打开原文或官方记录支撑。 +- 同一公司新闻稿、同一试验登记、同一专利族、同一券商报告转载链，必须归入同一个 `independence_cluster`。 + +--- + +## 四、黑名单（直接拒绝入库） 以下信源**无论评分多少都禁用**： @@ -112,7 +157,7 @@ description: 信源质量评分系统（0-10 分制）与黑名单机制。规 --- -## 四、利益冲突检测要点 +## 五、利益冲突检测要点 ### 常见利益冲突场景 - 药企赞助的 RCT 对自家产品评价极高 → 查对比剂、盲法、样本量 @@ -130,7 +175,7 @@ description: 信源质量评分系统（0-10 分制）与黑名单机制。规 --- -## 五、评分执行流程（伪代码） +## 六、评分执行流程（伪代码） ``` for each candidate_source in search_results: @@ -162,7 +207,7 @@ for each candidate_source in search_results: --- -## 六、输出字段（写入 sources.jsonl） +## 七、输出字段（写入 sources.jsonl） ```jsonl { @@ -177,12 +222,16 @@ for each candidate_source in search_results: "conflict_of_interest": null, "blacklist_checked": true, "retraction_checked": true, + "search_receipt_ids": ["srch_0001"], + "access_status": "opened_original", + "evidence_locator": "Table 2", + "independence_cluster": "cluster_trial_001", "notes": "NEJM 2025 原文，RCT 独立研究" } ``` --- -## 七、审计留痕 +## 八、审计留痕 -所有被**拒绝**的信源，也要写入 `projects//phase2/rejected-sources.jsonl`（注明原因）。这是事后复盘的关键，不要静默丢弃。 +所有被**拒绝**的信源，也要写入 `projects//phase2/rejected_sources.jsonl`（注明原因、对应 `receipt_id`、拒绝规则）。这是事后复盘的关键，不要静默丢弃。 diff --git a/.agents/workflows/deep-research-native.md b/.agents/workflows/deep-research-native.md index 45f7cf1..ac6d8c9 100644 --- a/.agents/workflows/deep-research-native.md +++ b/.agents/workflows/deep-research-native.md @@ -1,56 +1,154 @@ +--- +description: Run native biomedical Deep Research in Antigravity using roles, rules, skills, workflows, source receipts, and explicit approval gates. +--- + # Deep Research Native Workflow -Description: Run a biomedical Deep Research project in Antigravity using Antigravity model quota, with explicit anti-hallucination gates and source receipts. +Invoke as `/deep-research-native `. -## Step 0: Load Context +## Step 0: Load Operating Context - Load `AGENTS.md`. +- Load `GEMINI.md`. - Load `.agents/agents.md`. - Load `.agents/rules/deep-research-antigravity.md`. - Load `.agents/skills/antigravity-surface-adapter/SKILL.md`. -- Load skills: `mckinsey-method`, `search-strategy`, `source-quality`, `evidence-table`, `citation-manager`, `length-budget`, `output-hygiene`. -- Confirm topic, slug, report type, target audience, method, output length, and allowed search tools. +- Load `.agents/skills/method-selection/SKILL.md`. +- Load relevant quality skills: `search-strategy`, `source-quality`, `evidence-table`, `research-quality-gates`, `citation-manager`, `length-budget`, `output-hygiene`. -Gate: do not proceed if the topic, slug, and report purpose are unclear. +Gate: if the active model has not loaded the above files, stop and ask the user to restart or explicitly mention them. -## Step 1: Phase 0-1 With Opus +## Step 1: Define The Research Problem -- Ask the user to switch the conversation model to Claude Opus 4.6 (Thinking). -- Create project folders under `projects//`. -- Read user materials and write `phase1/material_brief.md`. -- Run real searches and log them in `phase1/search_log.md`. -- Write `phase1/framework.md`, `phase1/research_brief.md`, and `phase1/research_brief.json`. -- Write `phase1/unsupported_claims.md` for hypotheses not yet evidenced. +Act as Research Manager with Gemini 3 Flash. -Gate: pause for user confirmation. Do not enter Phase 2 before approval. +Confirm: -## Step 2: Phase 2 With Gemini 3.1 Pro Low +- topic and slug +- report purpose +- target reader +- decision the report supports +- report type and expected length +- available input materials +- allowed search tools +- whether Python model-worker commands are forbidden or allowed -- Ask the user to switch the conversation model to Gemini 3.1 Pro (Low). -- Build `phase2/task_cards.json`. -- For each task card, run real searches and append `phase2/search_log.jsonl`. -- Write `phase2/packets/*.json`; every packet must contain `search_receipts`, `sources`, `counter_evidence`, and `unsupported_claims`. -- Build `phase2/chapter_briefs/*.json` and `phase2/compressed_findings/*.json`. -- Write `phase2/drafts/chXX.md` only from chapter briefs and compressed findings. +Create or confirm `projects//` and phase folders. Create or update `projects//continuation_state.json`. Use Python only for scaffolding if helpful. -Gate: do not draft a chapter from memory or snippets. Every concrete claim needs a source ID. +Gate: do not continue if purpose, audience, and decision use are unclear. -## Step 3: Phase 3 With Gemini 3.1 Pro High +## Step 2: Select Method -- Ask the user to switch the conversation model to Gemini 3.1 Pro (High). -- Review framework, packets, sources, chapter briefs, and drafts. -- Write `phase3/critique.md`. -- Include a source-audit table for at least 10 core facts. -- Mark decision as `go`, `rework`, or `fail`. +Ask the user to switch to Claude Opus 4.6 (Thinking). + +Act as Phase 0-1 Strategist. Use `method-selection`. + +Write a method decision note covering: + +- selected method or method mix +- why it fits the scenario +- rejected methods and why +- evidence types required +- search routes by chapter or task axis +- expected artifacts + +Save it as `phase1/method_decision.md` or embed the same content in `phase1/research_brief.md` with a clear heading. + +Gate: do not default to McKinsey, MECE, or SCQA. Use them only when they fit the decision problem. + +## Step 3: Phase 0-1 Framing + +Still using Claude Opus 4.6 (Thinking), produce: + +- `phase1/material_brief.md` +- `phase1/search_log.md` +- `phase1/method_decision.md` +- `phase1/assumptions.md` +- `phase1/framework.md` +- `phase1/research_brief.md` +- `phase1/research_brief.json` +- `phase1/unsupported_claims.md` + +Rules: + +- Hypotheses without evidence must be labeled as hypotheses. +- Every searched claim must have a search receipt. +- Each chapter must state method, core question, likely evidence, and falsification route. + +Gate: pause for user approval before Phase 2. + +## Step 4: Phase 2 Evidence And Drafting + +Ask the user to switch to Gemini 3.1 Pro (Low). + +Act as Evidence Analyst. + +Produce: + +- `phase2/task_cards.json` +- `phase2/search_log.jsonl` +- `phase2/sources.jsonl` +- `phase2/rejected_sources.jsonl` +- `phase2/claims_ledger.jsonl` +- `phase2/coverage_matrix.md` +- `phase2/packets/*.json` +- `phase2/chapter_briefs/*.json` +- `phase2/compressed_findings/*.json` +- `phase2/drafts/chXX.md` +- `phase2/unsupported_claims.md` + +Rules: + +- No tool receipt, no search claim. +- No source ID, no factual claim. +- Search snippets and AI summaries are leads only. +- Every packet must include `search_receipts`, `sources`, `evidence_spans`, `counter_evidence`, and `unsupported_claims`. +- Every core claim must be represented in `claims_ledger.jsonl`. +- Every chapter must pass a counter-search or falsification pass. +- Evidence gaps trigger delta retrieval before drafting or visible caveats if still unresolved. +- Draft chapters only from approved chapter briefs and compressed findings. + +Gate: run `research-quality-gates`. Do not move to Phase 3 if packet evidence is missing, claim-ledger records are incomplete, unsupported claims are hidden, source independence is not tracked, or counter-evidence is absent. + +## Step 5: Phase 3 Review + +Ask the user to switch to Gemini 3.1 Pro (High). + +Act as Chief Reviewer. + +Produce `phase3/critique.md` with: + +- go / rework / fail decision +- structural critique +- method fit critique +- evidence gap list +- counter-evidence critique +- claim-ledger audit +- coverage matrix audit +- source-audit table for at least 10 core facts +- rework task list if needed + +If the critique finds a critical evidence gap, create delta-retrieve tasks instead of asking Phase 4 to paper over the gap. Gate: pause for user decision after critique. -## Step 4: Phase 4 With Opus +## Step 6: Phase 4 Finalization -- Ask the user to switch the conversation model to Claude Opus 4.6 (Thinking). -- Write `phase4/final_zh.md` from approved drafts and sources only. -- Write `phase4/editorial_notes.md`. -- Write `phase4/final_fact_check.md`, listing any unresolved or downgraded claims. -- Use deterministic renderer tools afterward for PDF/DOCX. +Ask the user to switch to Claude Opus 4.6 (Thinking). -Gate: final output cannot introduce new facts without adding sources and search logs first. +Act as Final Editor. + +Produce: + +- `phase4/final_zh.md` +- `phase4/editorial_notes.md` +- `phase4/final_fact_check.md` + +Rules: + +- Do not introduce new facts unless new sources and search logs are added first. +- Final facts must be a subset of verified or explicitly caveated `claims_ledger.jsonl` rows. +- Downgrade or mark claims that remain unsupported. +- Use deterministic rendering tools afterward for PDF/DOCX. + +Gate: final output must pass citation and unsupported-claim review before rendering. diff --git a/AGENTS.md b/AGENTS.md index 3248ea5..dd09c93 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,252 +1,91 @@ -# AGENTS.md — 生物医药 Deep Research 系统规则 +# AGENTS.md — Deep Research Cross-Tool Rules -> 本文件为跨平台项目级指令文件。Codex、OpenCode、Claude Code、Antigravity、Gemini CLI 均应以本文件为运行规则。 -> 所有平台 adapter / skill / command 必须遵循本文件定义的研究方法论、信源标准与输出规范。 +This file is the shared, cross-tool instruction layer for Codex, OpenCode, Claude Code, Gemini CLI, and Antigravity. ---- +Keep this file short. Do not put Antigravity roles, detailed workflows, or long skill manuals here. -## 1. 项目使命 +## Project -本项目通过**Python core + skills + 可选多模型角色**协作，以**麦肯锡、德勤等顶尖机构的研究方法**，对生物医药领域（研发、工艺、管理、投资）的指定主题进行深度研究，输出专业级报告（PDF + DOCX）。 +Deep Research produces professional biomedical research reports for R&D, CMC/GMP, management, market, and investment topics. -本项目**不涉及业务代码开发**，所有"代码"都是为**研究流水线**服务（如 Python runtime、ReportLab/Quarto 模板、下载脚本、信源 API 调用）。 +This repository is not an application codebase. Its code supports the research pipeline: Python runtime, search utilities, evidence schemas, citation checks, and PDF/DOCX rendering. -### 1.1 v0.20 架构原则 +## Instruction Layers -- `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 与来源笔记中。 +- Cross-tool baseline: `AGENTS.md` +- Gemini / Antigravity override: `GEMINI.md` +- Antigravity roles: `.agents/agents.md` +- Antigravity strong rules: `.agents/rules/` +- Reusable skills: `.agents/skills/` +- Antigravity workflows: `.agents/workflows/` +- Implementation plan and changelog: `PLAN.md` -## 2. 研究方法论（所有 agent 必须遵循） +If instructions conflict, use the more specific layer. For Antigravity, `GEMINI.md` and `.agents/rules/` override this file. -### 2.1 麦肯锡核心原则 +## Operating Modes -1. **研究方法适配场景**：MECE 是常用方法之一，但 GMP/CMC/管理咨询/研发立项等场景必须选择匹配框架 -2. **SCQA 叙事**（Situation → Complication → Question → Answer）：每章节开头用此结构引入 -3. **金字塔原理**：结论先行，论据支撑，纵向深入，横向 MECE -4. **"每个标题即一个观点"**：标题不能是"概述""现状"这类模糊词，必须包含判断 -5. **So What? 自检**：每写完一段问自己"所以呢？"，若无则删 +Python-core mode: -### 2.2 证据铁律 +- Use `scripts/dr.py`, `scripts/runtime/**`, `configs/models.yaml`, and `.agents/skills`. +- Platform agents should call the Python CLI rather than reimplement worker orchestration. +- Model routing is resolved by the Python runtime. -- **每条结论至少 2 个独立 Tier 1-2 信源**佐证（见 §4 信源分级） -- 达不到则**必须在正文注明**"该观点仅有 X 个来源支持，待进一步验证" -- **反方证据优先**：每个 chapter 的研究必须主动搜索证伪性论点，不能只找支持证据 -- **数据可追溯**：所有数字、百分比、日期必须有来源 ID（如 `[src_042]`） +Antigravity native mode: -### 2.3 字数配额（硬要求） +- Use `.agents/agents.md`, `.agents/rules/`, `.agents/skills/`, and `.agents/workflows/`. +- Antigravity uses its own model quota for research execution. +- Python scripts are auxiliary for scaffolding, local material processing, deterministic checks, citation/report rendering, and status. +- Do not run Python model-worker commands such as `dr.py run`, `research --execute-packets`, or `research --assemble-chapters` unless the user explicitly approves external API/ZenMux usage. -| 报告类型 | 最小字数 | 建议章节数 | -|---|---|---| -| 综述类 | 10,000 字 | 8-10 章 | -| 研究类 | 30,000 字 | 10-12 章 | -| 投资报告 | 20,000 字 | 10-12 章 | -| 管理/工艺类 | 15,000-25,000 字 | 9-11 章 | - -**字数分配原则**： -- 每章字数差距不超过 ±30%（避免头重脚轻） -- 每 section 最少 800 字（不够则合并） -- 结论章不少于全文 10% - -### 2.4 报告不能只谈结论 - -- 每个观点后必须紧跟**数据/事实/案例**佐证 -- 禁止空洞形容词（"巨大""快速""显著"）不带数据 -- 趋势判断必须给**量化依据**（年复合增长率、市场规模、成功率等） - ---- - -## 3. Phase 工作流（4 阶段） - -### Phase 1：框架规划 -- **驱动命令**：`uv run python scripts/dr.py init ` → `uv run python scripts/dr.py frame `（`/dr-init`、`/dr-frame` 只是薄封装） -- **主导入口**：Python core 生成项目骨架与 framework；dr-plan 可作为表层访谈增强 -- **产出**：`phase1/material_brief.md` + `phase1/framework.md` + `phase1/research_brief.md/json` -- **暂停点**：用户确认材料解读、研究方法、任务切分、检索策略和章节框架 -- **硬规则**：clarification 不只是问范围；必须固化报告用途、基调、成功标准、任务拆分、每个任务轴的 prompt/skills/search route，让低成本 worker 也能独立执行 - -### Phase 2：深度研究 -- **驱动命令**：`uv run python scripts/dr.py research --workers 6` -- **主导入口**：Python core 生成 task cards 并控制并发 -- **产出**：`phase2/task_cards.json` + `packets/*.json` + `sources.jsonl` + `chapter_briefs/*.json` + `compressed_findings/*.json` + `drafts/chXX.md` -- **不暂停**：全自动跑完 -- **防碎片化规则**：并发 worker 只写 evidence packet；`--build-briefs` 必须先收束为 chapter brief 和 compressed finding；章节正文必须从 compressed finding 写，不得把 packet 按顺序拼贴成报告 - -### Phase 3：总编审校 -- **驱动命令**：`uv run python scripts/dr.py review `（`/dr-review` 只是薄封装） -- **主导入口**：Python core deterministic review；dr-chief-editor/Gemini 可作为后续深度审校增强 -- **产出**：`projects//phase3/critique.md` -- **暂停点**：用户决策（修正 / 回炉 phase2 / 整体重来） - -### Phase 4：成稿 -- **驱动命令**：`uv run python scripts/dr.py finalize ` -- **主导入口**：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` - ---- - -## 4. 信源分级（Tier 系统） - -### Tier 1 — 一级信源（优先使用，评分权重 × 1.2） - -- **一手学术文献**：PubMed、Cochrane、顶刊原文（NEJM / Lancet / Nature / Science / Cell / JAMA） -- **监管机构公告**：FDA、EMA、NMPA、PMDA 官网及 openFDA -- **临床试验注册**：ClinicalTrials.gov、ChiCTR -- **专利原文**：USPTO、EPO、CNIPA、Google Patents -- **上市公司披露**：SEC 10-K/10-Q、招股书、交易所年报 - -### Tier 2 — 二级信源（可用，标准权重） - -- **权威咨询报告**：麦肯锡、BCG、德勤、IQVIA、EvaluatePharma、弗若斯特沙利文 -- **学术综述**：系统综述（Systematic Review）、Meta 分析 -- **行业协会**：PhRMA、BIO、中国医药工业协会 -- **专业数据库**：Wind、东方财富、同花顺（金融侧） -- **专业媒体**：BioSpace、Endpoints News、FiercePharma、医药魔方、Insight 数据库 - -### Tier 3 — 三级信源（辅助，不得作为唯一支撑） - -- **预印本**：bioRxiv、medRxiv（需标注"未经同行评审"） -- **券商研报**：中金、中信、高盛生物医药团队（需注意利益冲突） -- **会议摘要**：AACR、ASCO、ASH 会议摘要（数据可能未完整发表） -- **企业白皮书**（注明来源，降权使用） - -### Tier 4 — 四级信源（仅做发现入口） - -- Tavily / Brave / Exa 通用搜索返回的**普通网页** -- 一般新闻报道 -- Wikipedia（**只做术语理解入口，结论不得引用**） - -### 黑名单（禁用） - -- 纯新闻聚合站（百家号、头条号、部分自媒体公众号） -- 未署名作者的行业博客 -- 被 Retraction Watch 标记为撤稿的论文 -- 明显软文/PR 稿（如"某某 CEO 表示..."而无实质数据） -- 超过 5 年的综述（除机制类研究可放宽） - -### 信源评分（0-10） - -每个进入 `sources.jsonl` 的信源必须打分，维度： -- 权威性（期刊 IF、机构排名）0-3 -- 时效性（≤3 年满分，每老 1 年 -0.5） 0-2 -- 一手性（一手 > 综述 > 二次解读） 0-2 -- 可验证性（有 DOI / URL / 原始数据） 0-2 -- 利益冲突（厂商自发 -1） 0-1 - -**硬规则**：评分 < 5 的信源不得作为结论唯一支撑。 - ---- - -## 5. Python Role / Task 模型 - -平台 agent 文件只保留兼容和展示意义；真实角色、任务类型、模型、温度、并发上限以 Python runtime 为准。 - -查看当前模型配置： +## Core Commands ```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 +uv run python scripts/dr.py init "研究主题" --slug --method +uv run python scripts/dr.py frame +uv run python scripts/dr.py research --workers 6 --execute-packets +uv run python scripts/dr.py review +uv run python scripts/dr.py finalize +uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace --dry-run ``` -核心任务类型： +## Research Integrity -| 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 渲染 | +- No fabricated data, URLs, DOIs, clinical results, regulatory status, patents, or market figures. +- No factual claim without a source ID or a clearly marked "to verify" status. +- No claim that a search or verification was performed unless there is a real tool receipt or search log. +- Search snippets, AI summaries, and model memory are discovery leads, not final evidence. +- Every major conclusion needs at least two independent Tier 1-2 sources. If not available, downgrade and mark uncertainty. +- Counter-evidence is mandatory. Do not collect only supporting evidence. +- Wikipedia is allowed for orientation only and must not support final conclusions. +- Use Chinese for formal report writing. English may remain in search keywords, titles, DOI/URL, original excerpts, and raw notes. -默认策略： +## Method Selection -- Codex/GPT 系列适合代码、schema、回归、review。 -- Claude/Opus/Sonnet 适合长文结构、中文表达、访谈增强。 -- Gemini 适合长上下文审校、多模态材料、替代框架评估。 -- ZenMux 混合模型仍由 `configs/models.yaml` 统一管理，平台当前会话模型不得覆盖 Python role/task 映射。 +Do not default to McKinsey/MECE for every topic. -## 6. Platform Adapter 调用方式 +Choose the research method and tools based on the user's scenario. Use `.agents/skills/method-selection/SKILL.md` for Antigravity native work and `configs/research_methods.yaml` for Python-core mode. -详见 `docs/platform-adapters.md`。摘要如下： +## Source Quality -| Platform | 项目指令/命令位置 | 推荐调用 | -|---|---|---| -| OpenCode | `.opencode/commands/*.md` | `/dr-run ` | -| 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 '')"` | -| Claude Code | `.claude/skills/*/SKILL.md` | `/dr-run ` | -| Gemini CLI | `GEMINI.md` + `.gemini/commands/dr/*.toml` | `/dr:run ` | -| Antigravity | `.agents/agents.md` + `.agents/rules` + `.agents/skills` + `.agents/workflows` | 角色定义在 agents，强约束在 rules，技能在 skills，流程在 workflows | +Detailed scoring belongs in `.agents/skills/source-quality/SKILL.md`. -跨平台硬规则： +Baseline tiers: -- 除 Antigravity native 模式外，平台只做 surface adapter，不承载核心调度。 -- Antigravity 的角色定义放在 `.agents/agents.md`；不要把角色、技能和流程继续堆进本文件。 -- 不在平台 prompt 中手工并发写章节。 -- 不把平台 subagent 当默认并发机制。 -- 真实并发由 `scripts/runtime/workers.py` 的 worker pool 执行。 -- 真实模型选择由 `configs/models.yaml` 和 `scripts/runtime/roles.py` 执行。 -- 信息检索默认走 `scripts/search.py` / `SearchClient` / `search-gateway` skill；不得把 Tavily MCP、browser MCP 或平台 web search 作为默认路径，除非用户明确授权。 -- 搜索路由必须按任务类型选择：`evidence`=Exa highlights 受控证据发现，`fda/scholar/patents/news`=专用信源路径，`general`=宽泛发现和兜底；Tavily Research 只能作为阶段性 scan/enrichment/rework 输入，不能直接替代 evidence packet 或章节正文。 +- Tier 1: original academic papers, systematic reviews where appropriate, regulator documents, clinical trial registries, patents, company filings. +- Tier 2: authoritative consulting/industry reports, industry associations, reputable professional media and databases. +- Tier 3: preprints, conference abstracts, brokerage research, company white papers. Use with caution. +- Tier 4: general web pages, ordinary news, Wikipedia. Discovery only. ---- +## Safety -## 7. 目录约定 +- Keep API keys only in `secrets.env`; never hardcode or commit secrets. +- Do not read or expose secrets unless the user explicitly asks. +- Do not overwrite user settings or existing workspace rule/skill/workflow files unless the user asks for `--force`. +- Do not run destructive git commands such as `git reset --hard`, `git clean`, or broad file deletion without explicit approval. +- Do not write outside the current workspace unless the user explicitly approves. -- 每个研究主题放在 `projects//`，slug 用小写+连字符，如 `glp1-r-agonist-market-2026` -- 所有中间产物（drafts、evidence、sources.jsonl）均为 Markdown 或 JSONL，便于 diff 与版本控制 -- `archive/` 存放已完成或废弃的研究，不再主动维护 +## Change Management ---- - -## 8. 安全与权限 - -- API 密钥**只存** `secrets.env`（已入 gitignore），禁止硬编码到任何 agent/skill/command -- 字体文件（~140MB）不入 git，通过 `download-fonts.sh` 获取 -- `bash` 权限默认 `ask`，仅允许 `python *` / `pandoc *` / `ls *` / `cat *` / `curl *` 自动执行 - ---- - -## 9. 如何判断是否走了 Python Core - -不要用“平台是否 spawn subagent”作为成功标准。Python-core 模式的验证锚点是 Python runtime 产物： - -1. `uv run python scripts/dr.py status ` 能看到 phase 状态。 -2. Phase 2 存在 `phase2/task_cards.json`。 -3. Phase 1 存在 `phase1/research_brief.md` 和 `phase1/research_brief.json`。 -4. `--execute-packets` 后存在 `phase2/packets/*.json` 和必要时的 `phase2/packet_errors/*.json`。 -5. `--build-briefs` 后存在 `phase2/chapter_briefs/*.json` 与 `phase2/compressed_findings/*.json`。 -6. `--assemble-chapters` 后存在 `phase2/drafts/chXX.md` 和必要时的 `phase2/chapter_errors/*.json`。 -7. `scripts/v020_regression.py` 输出 `v0.20 regression PASS`。 - -Antigravity native 模式的验收锚点由 `.agents/workflows/deep-research-native.md` 定义。 - ---- - -## 10. 禁止事项（negative instructions） - -所有 agent 均禁止： - -1. ❌ 引用 Wikipedia 作为结论支撑（仅做术语理解） -2. ❌ 在缺乏 2 个独立信源时仍给出绝对化结论 -3. ❌ 使用"据报道""有专家认为"等未指明来源的表述 -4. ❌ 编造或虚构数据、URL、DOI -5. ❌ 声称"已搜索/已验证/官网显示"但没有工具回执和检索记录 -6. ❌ 用搜索摘要、AI summary、snippet 冒充原文证据 -7. ❌ 写空洞的套话（"随着科技的发展""在大数据时代"） -8. ❌ 忽略反方观点，只收集支持证据 -9. ❌ 对输出字数"打折"（综述 <10000 字、研究 <30000 字必须返工） -10. ❌ 在正文中使用未在术语表中定义的专业缩写（首次出现需全称+缩写） - ---- - -## 11. 变更管理 - -- 本文件与 `PLAN.md` 是**双核**：PLAN.md 管实施进度与架构，AGENTS.md 管运行时规则 -- 修改本文件需同步更新 PLAN.md 的"变更记录"段 -- 所有 agent/skill 新增或重大调整必须在 PLAN.md §8 清单中标记完成状态 +- Treat `AGENTS.md`, `GEMINI.md`, `.agents/**`, and `PLAN.md` as production configuration. +- Keep root rules short. Move roles to `.agents/agents.md`, constraints to `.agents/rules`, capabilities to `.agents/skills`, and phase sequencing to `.agents/workflows`. +- When changing runtime rules or adapter behavior, update `PLAN.md` changelog. diff --git a/GEMINI.md b/GEMINI.md index 5fb836e..ec62f70 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,34 +1,34 @@ -# Gemini CLI Project Instructions +# GEMINI.md — Gemini / Antigravity Overrides -This repository is Deep Research v0.20. Gemini must assume it is high-risk for hallucination and false confirmation in research tasks. +This file has higher priority than `AGENTS.md` for Gemini CLI and Antigravity. -## Load Order +## Load The Right Layer -- Treat `AGENTS.md` as the cross-platform rule source. -- For Antigravity-native work, also follow `.agents/rules/deep-research-antigravity.md` and `.agents/skills/antigravity-surface-adapter/SKILL.md`. -- Use `/memory show` or equivalent context inspection when behavior seems inconsistent. +- Shared baseline: `AGENTS.md` +- Antigravity roles: `.agents/agents.md` +- Strong research rules: `.agents/rules/` +- Skills: `.agents/skills/` +- Workflows: `.agents/workflows/` -## Non-Negotiable Research Integrity +For Antigravity native research, load `.agents/agents.md`, `.agents/rules/deep-research-antigravity.md`, `.agents/skills/antigravity-surface-adapter/SKILL.md`, `.agents/skills/method-selection/SKILL.md`, `.agents/skills/research-quality-gates/SKILL.md`, and `.agents/workflows/deep-research-native.md`. -- Never claim "searched", "verified", "confirmed", "officially shows", or "according to source" unless a tool was actually executed in this session or current phase and the result is logged. -- Every factual claim with a number, date, company, product, clinical phase, regulatory status, market size, patent status, or quote needs a `source_id`. -- Search snippets, AI summaries, and model memory are discovery aids only. They are not evidence. -- If you cannot open the original source, write "未能访问原文，仅作为发现线索" and do not extract exact values from it. -- Maintain a phase search log: query, tool, timestamp, URL/title, selected/rejected status, and reason. -- Prefer saying "未找到足够证据" over filling gaps. +Use `/memory show` or `/memory refresh` in Gemini CLI when the loaded context may be stale. -## Platform Mode +## Gemini Failure Modes -- Gemini CLI is normally a Python-core surface adapter. Use `.gemini/commands/dr/*.toml` or run `uv run python scripts/dr.py ...`. -- Antigravity is the exception: it should use its own model quota and skills to execute research natively; Python scripts are auxiliary unless the user explicitly approves model-worker/API usage. -- 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. +Treat Gemini-family models as high risk for false certainty in research. -## Typical Python-Core Commands +- Never say "searched", "verified", "confirmed", "officially shows", or "according to source" unless a real tool call happened in this session or phase and the result is logged. +- Do not use model memory, snippets, or AI summaries as evidence. +- Every concrete fact needs a `source_id`, claim-ledger row, or a clear "to verify" label. +- If the original source cannot be opened, write "未能访问原文，仅作为发现线索" and do not extract exact values from it. +- Keep `search_log.jsonl`, `claims_ledger.jsonl`, and `continuation_state.json` current in Antigravity native runs. +- Prefer "未找到足够证据" over filling gaps. -```bash -uv run python scripts/dr.py run "研究主题" --slug --method mckinsey_market -uv run python scripts/dr.py research --workers 6 --execute-packets -uv run python scripts/dr.py review -uv run python scripts/dr.py finalize -``` +## Platform Boundary + +Gemini CLI normally uses Python-core mode through `.gemini/commands/dr/*.toml` or `uv run python scripts/dr.py ...`. + +Antigravity is different: use native mode and its model quota for research execution. Python scripts are auxiliary unless the user explicitly approves Python model-worker/API usage. + +Do not modify `projects/**` unless the user is intentionally running a research project. diff --git a/PLAN.md b/PLAN.md index b5308cb..fda946f 100644 --- a/PLAN.md +++ b/PLAN.md @@ -754,7 +754,7 @@ OpenCode 的坑：如果只是在主会话里装样子地写"让 X agent 做"， - Claude/Claude Code 最佳实践可借鉴：根指令要短、具体、可执行，长流程拆到 rules/skills/workflows，避免巨型上下文降低遵从性。 **已落地**： - - `AGENTS.md` 新增 Antigravity native 例外、检索回执、source_id、search_log、unsupported_claims 等反幻觉硬规则。 + - 初版曾在 `AGENTS.md` 中加入 Antigravity native 例外、检索回执、source_id、search_log、unsupported_claims 等反幻觉硬规则；v0.20.3/v0.20.4 已将这些内容迁入 `.agents/rules`、`.agents/skills` 与 `.agents/workflows`。 - `GEMINI.md` 重写为短约束：禁止假搜索、禁止无 source_id 事实、要求 search log，并区分 Gemini CLI 与 Antigravity native。 - `.agents/rules/deep-research-antigravity.md` 加入 Anti-Hallucination Contract。 - `.agents/skills/antigravity-surface-adapter/SKILL.md` 加入 phase artifacts、fact-audit、权限建议和检索日志要求。 @@ -773,3 +773,20 @@ OpenCode 的坑：如果只是在主会话里装样子地写"让 X agent 做"， - 瘦身 `AGENTS.md`，只保留跨平台研究底线与分层指引。 - `antigravity-surface-adapter` skill 和 `deep-research-native` workflow 改为引用 `.agents/agents.md`。 - `scripts/deploy_adapters.py antigravity` 同步部署 `.agents/agents.md`，默认跳过已有文件，`--force` 才备份覆盖。 + +- 2026-05-07 v0.20.4 AGENTS/GEMINI slimdown + method selection：**根规则瘦身，研究方法按场景选择** + + **设计结论**： + - 根 `AGENTS.md` 只保留跨工具底线、命令入口、安全边界和分层索引；Phase 0-4 工作流、Antigravity 角色、长规则和技能细则全部迁出。 + - `GEMINI.md` 只做 Gemini/Antigravity 高优先级覆盖，强调上下文加载和反假搜索。 + - 麦肯锡/MECE/SCQA 只是候选表达和咨询工具，不再作为默认研究方法；不同研究场景必须选择匹配的分析框架。 + + **已落地**： + - 重写 `AGENTS.md`，缩短为跨工具规则和索引。 + - 重写 `GEMINI.md`，保留 Gemini 反幻觉、平台边界和 context 加载指引。 + - 新增 `.agents/skills/method-selection/SKILL.md`，覆盖市场/投资、临床、CMC/GMP、R&D、管理、政策等方法路由。 + - 参考 `199-biotechnologies/claude-deep-research-skill` 的证据持久化、claim-level verification、delta retrieve、continuation state 和 final assembly gate 设计，新增 `.agents/skills/research-quality-gates/SKILL.md`。 + - 强化 `source-quality` 与 `evidence-table`：要求 search receipt、原文访问状态、独立性 cluster、`claims_ledger.jsonl`、`coverage_matrix.md` 和不可证实 claim 显式落盘。 + - 重写 `.agents/agents.md`，只保留角色定义和 required skills。 + - 重写 `.agents/workflows/deep-research-native.md`，把方法选择设为独立 gate，加入 claim ledger、delta retrieve、coverage audit 和 continuation state gate。 + - 文档与测试同步更新。 diff --git a/README.md b/README.md index f014013..3ab1028 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ v0.20 后，OpenCode/Codex/Claude Code/Gemini CLI 都是 Python core 的 surface - 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 打开仓库，使用 `.agents/rules` + `.agents/skills` 指导其用 Antigravity 模型配额原生执行 Deep Research；Python core 只做脚手架、校验、引用和出稿辅助。 +- Antigravity：作为 Agent Manager 打开仓库，使用 `.agents/rules` + `.agents/skills` 指导其用 Antigravity 模型配额原生执行 Deep Research；Python core 只做脚手架、校验、引用和出稿辅助；质量门由 `method-selection`、`research-quality-gates`、`source-quality`、`evidence-table` 共同约束。 部署 Codex adapter（不在仓库内创建 `.codex`）： @@ -120,7 +120,7 @@ uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace ``` -Antigravity 部署不会修改全局设置。若目标工作区已有同名 agents/rule/skill/workflow 文件，默认跳过；只有显式加 `--force` 时才会先生成 `.bak` 备份再覆盖。 +Antigravity 部署不会修改全局设置。若目标工作区已有同名 agents/rule/skill/workflow 文件，默认跳过；只有显式加 `--force` 时才会先生成 `.bak` 备份再覆盖。Antigravity 分层为：`.agents/agents.md` 定义角色，`.agents/rules` 放强约束，`.agents/skills` 放能力，`.agents/workflows` 放流程。关键 artifact 包括 `search_log.jsonl`、`sources.jsonl`、`claims_ledger.jsonl`、`coverage_matrix.md` 和 `continuation_state.json`。 部署到新环境后自检： diff --git a/docs/platform-adapters.md b/docs/platform-adapters.md index 41e2425..3b4bf68 100644 --- a/docs/platform-adapters.md +++ b/docs/platform-adapters.md @@ -136,6 +136,8 @@ gemini - `.agents/agents.md`：Antigravity 角色定义，只定义 Research Manager / Strategist / Analyst / Reviewer / Final Editor 等角色。 - `.agents/skills/antigravity-surface-adapter/SKILL.md`：Antigravity 专用执行说明。 +- `.agents/skills/method-selection/SKILL.md`：按场景选择研究方法，避免默认套用麦肯锡/MECE。 +- `.agents/skills/research-quality-gates/SKILL.md`：把 search receipt、source access、claims ledger、delta retrieve、continuation state 和 final fact check 做成阶段质量门。 - `.agents/rules/deep-research-antigravity.md`：workspace rule，约束其优先使用 Antigravity 模型配额，避免主流程落回 ZenMux。 - `.agents/workflows/deep-research-native.md`：可按 slash workflow 执行的四阶段研究流程与反幻觉 gate。 - `.agents/skills/*`：Antigravity 官方默认 skill 目录，直接复用本项目 canonical skill registry。 @@ -166,7 +168,7 @@ uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace 4. 给 Agent Manager 一个明确任务： ```text -请加载 .agents/agents.md、.agents/rules/deep-research-antigravity.md、.agents/skills/antigravity-surface-adapter/SKILL.md 和 AGENTS.md。 +请加载 .agents/agents.md、.agents/rules/deep-research-antigravity.md、.agents/skills/antigravity-surface-adapter/SKILL.md、.agents/skills/research-quality-gates/SKILL.md 和 AGENTS.md。 用 Gemini 3 Flash 做流程管理，按 skill 要求在需要时提示我切换模型。 研究主题："ADC 全球竞争格局"，slug: adc-global-landscape，method: mckinsey_market。 请先创建/确认项目目录，然后进入 Phase 0-1，并在生成 phase1/framework.md 和 research_brief 后暂停。 @@ -179,6 +181,7 @@ uv run python scripts/deploy_adapters.py antigravity --target /path/to/workspace - 不要默认运行 `dr.py run`、`research --execute-packets`、`research --assemble-chapters`，这些会把主流程重新导向 Python/ZenMux。 - Python core 可用于 `init/status/skills validate/finalize/render` 等辅助动作。 - 若本机安装了 `paperfoot/search-cli` 的 `search` 命令，Antigravity Phase 0-2 可优先用 `search agent-info`、`search ... --json` 做统一检索入口。 +- Phase 2 不只产出章节草稿；必须维护 `search_log.jsonl`、`sources.jsonl`、`claims_ledger.jsonl`、`coverage_matrix.md` 和 `unsupported_claims.md`，否则 Phase 3/4 不得声称已验证。 - 不建议依赖 SOUL.md：它不是 Antigravity 官方 Deep Research 约束入口。本项目用 `AGENTS.md`、`.agents/agents.md`、`.agents/rules`、`.agents/skills` 和 `.agents/workflows` 分层约束。 ## Model Strategy Across Platforms diff --git a/tests/test_v020_runtime.py b/tests/test_v020_runtime.py index 5029eae..89213d2 100644 --- a/tests/test_v020_runtime.py +++ b/tests/test_v020_runtime.py @@ -36,6 +36,8 @@ def test_skill_registry_uses_agents_skills_as_canonical() -> None: assert "document-ingest" in names assert "deep-research" in names assert "antigravity-surface-adapter" in names + assert "method-selection" in names + assert "research-quality-gates" in names assert registry.validate()["ok"] is True