name: manuscript-drafter description: > 学术论文初稿自动撰写。触发条件: (1) 用户说"写初稿"/"draft manuscript"/"开始写论文", (2) 统计分析完成后自动触发, (3) 用户说"把结果写成论文"。 核心能力: 基于分析报告、数据字典、人群流程图和目标期刊规范， 自动生成结构完整、数据准确的论文初稿，无需人工逐段指导。 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch

Manuscript Drafter - 论文初稿自动撰写

核心理念

数据驱动写作，不是模板填空。

P-A 论文中稿件撰写是最大的手动步骤——用户需要指导每一段的内容和取舍。 本 Skill 的目标是：给定分析结果 + 期刊规范，直接输出可提交级别的初稿。

传统流程: 分析完 → 用户说"写Introduction" → 写 → 用户说"写Methods" → 写 → ...
本Skill:  分析完 → 自动读取所有输入 → 一次性生成完整初稿

触发条件

1. 用户说"写初稿"/"draft"/"开始写论文"/"把结果写成论文"
2. paper-pipeline 编排器在分析完成后自动调用
3. statistical-analysis 完成并生成 full_analysis_report.md 后

输入

• 必需: 分析报告路径 (full_analysis_report.md)
• 必需: 目标期刊名称
• 推荐: 数据字典 (data_dictionary.md) — 来自 data-profiler
• 推荐: 人群流程图 (flow_diagram.md) — 来自 flow-diagram-generator
• 推荐: 研究计划 (CLAUDE.md) — 包含研究问题和假设
• 可选: 对标报告 (benchmark_report.md) — 来自 journal-benchmarker
• 可选: 关键参考文献列表

输出

• manuscript_draft.md — 完整论文初稿（含结构化摘要、正文、图表说明）
• 初稿自动触发 academic-reference-inserter 和 manuscript-reviewer

撰写流程

Phase 0: 信息收集

目标: 自动读取所有可用输入，建立写作上下文。

自动扫描项目目录:
  outputs/
    ├── full_analysis_report.md     → 统计结果
    ├── data_dictionary.md          → 变量定义
    ├── flow_diagram.md             → 人群流转
    ├── population_registry.md      → 各分析 N
    ├── benchmark_report.md         → 对标数据
    ├── tables/                     → 表格文件
    └── figures/                    → 图表文件
  docs/
    ├── CLAUDE.md                   → 研究计划
    └── 论文产出规划.md              → 论文定位

从这些文件中提取：

1. 研究问题和假设 (CLAUDE.md)
2. 样本量和事件数 (population_registry.md / analysis report)
3. 主要结果 (analysis report: HR, CI, p-values)
4. 敏感性分析结果 (analysis report)
5. 期刊规范 (manuscript-reviewer 的速查表 / WebSearch)
6. 字数预算 (期刊限制 → 各节分配)

Phase 0b: 文献知识地基（由 literature 模块提供）

本步骤已迁移至 reference-manager Skill 的 /ref research 子命令。

执行顺序: statistics → CP-2 通过 → /ref research → manuscript-drafter。 这保证了文献调研基于已验证的统计结果和故事线，一次到位不做第二次（硬约束 O6）。

manuscript-drafter 启动前，literature 模块应已完成以下产出：

• outputs/literature_summary.md — 深度调研报告 + 验证后的文献列表（必引/重要/背景三级，含稿件用途标注）
• outputs/academic_evolution_diagram.png — 学术演进时间线图（可选）

激活条件:

• literature_summary.md 存在且修改时间 < 7 天 → 直接进 Phase 1
• 不存在 → 阻断，提示先运行 /ref research

写稿时引用规则:

• Phase 2（Introduction）优先从 usage=Introduction背景 的文献引用
• Phase 3（Methods）优先从 usage=Methods方法引用 的文献引用
• Phase 5（Discussion）优先从 usage=Discussion对比/Discussion机制 的文献引用
• 所有引用优先用 literature_summary.md 中的真实文献，不足时用 [REF: xxx] 占位符

Phase 1: 字数预算分配

基于期刊限制和对标数据分配字数。

def allocate_words(journal_limit, benchmark=None):
    """字数预算分配"""
    # 默认分配 (基于P-A经验和文献分析)
    default_allocation = {
        'Introduction': 0.16,    # ~560
        'Methods': 0.32,         # ~1120
        'Results': 0.28,         # ~980
        'Discussion': 0.24,      # ~840
    }

    # 如果有对标数据，使用对标中位数
    if benchmark:
        allocation = benchmark['word_allocation']
    else:
        allocation = default_allocation

    budget = {}
    for section, pct in allocation.items():
        budget[section] = int(journal_limit * pct)

    return budget

# EJHF 示例
# budget = allocate_words(3500)
# → Introduction: 560, Methods: 1120, Results: 980, Discussion: 840

Phase 2: Introduction 撰写

结构: 漏斗式 (宽→窄→本研究)

¶1: 疾病负担 (心衰流行病学，1-2个关键数字 + 引用)
    ↓
¶2: 现有知识差距 (分型方法的局限性，2-3个引用)
    ↓
¶3: 研究方法的理论基础 (AI/聚类在心衰中的应用，2-3个引用)
    ↓
¶4: 本研究的目的和假设 (1句话，明确可检验)

规则:

• 每段1-2个引用占位符 [REF: keywords]
• 最后一段必须包含明确的研究目的陈述
• 不要剧透结果
• 控制在 ~500-600 词

Phase 3: Methods 撰写

结构: 按分析流程顺序

§ Study Design and Setting
  - 回顾性队列研究
  - 数据来源（医院、时间范围）
  - 伦理声明 [IRB占位符]

§ Study Population
  - 入选标准
  - 排除标准
  - 引用 Figure 1 (流程图)

§ Data Collection
  - 变量定义（从数据字典提取）
  - 结局变量定义
  - 随访方式

§ TCM Syndrome Assessment (如适用)
  - 证型诊断标准
  - 诊断流程

§ Statistical Analysis
  - 描述性统计方法
  - 主要分析（KM、Cox等）
  - 模型调整策略（Models 1-4）
  - 敏感性分析列表
  - 软件声明 + alpha水平
  - 缺失数据处理声明

关键规则:

• 从 population_registry 获取每个分析的精确 N
• 从 analysis report 获取模型的具体协变量
• Methods 中描述的每个分析，必须在 Results 中有对应结果
• 敏感性分析必须明确列举

Phase 4: Results 撰写

结构: 从描述到推断

§ Study Population
  - 基线特征总结（引用 Table 1）
  - 关键组间差异

§ Primary Outcome
  - 事件率
  - KM 曲线（引用 Figure）
  - Log-rank 检验

§ Multivariable Analysis
  - Cox Models 1-4 结果（引用 Table）
  - 每个 HR 必须附带 95% CI 和 p 值
  - 所有组都要报告（包括非显著的）

§ Secondary Findings
  - 亚组分析
  - AI 聚类结果

§ Sensitivity Analyses
  - 逐项报告
  - 与主分析对比

数据准确性规则:

• 所有数字必须从 analysis report 中复制粘贴，不能手动编辑
• HR 格式: HR X.XX (95% CI X.XX-X.XX, p=0.XXX)
• P < 0.001 时写 p<0.001，不写 p=0.000
• 每个分析段落开头注明 N 和事件数

Phase 4b: Discussion 对比文献全文获取

在写 Discussion 之前，先获取需要对比的文献全文。

目标: 确保 Discussion 中引述其他研究数据时基于原文，不是 AI 记忆。
适用: Discussion 中直接对比数据的文献（通常 5-10 篇）。
不适用: Introduction 背景性引用（摘要足够）。

步骤:

1. 从 Phase 4 Results 提取本研究核心发现（HR/OR/关键指标值）
2. 从 literature_summary.md 筛选出 Discussion 需要对比的文献
3. 分层下载全文 PDF:
   • Layer 1: Unpaywall API（免费 OA 版）
   • Layer 2: PMC OA Service（生物医学论文）
   • Layer 3: PyPaperBot（多源回退含 SciHub）
   • Layer 4: CNKI 代理 + browser-use + Gemini（中文文献 / 上层失败时兜底）
4. 读取全文，为每篇文献提取"对比要点":
   • 研究设计和样本量
   • 关键结果数据（HR/OR/效应量 + CI + p）
   • 与本研究可直接对比的指标
5. 输出 outputs/discussion_references.md

输出格式:

# Discussion 对比文献摘要
## [1] Author et al. (Year) - Title
- 设计: 前瞻性队列, N=1,234
- 关键结果: HR=1.45 (95%CI 1.12-1.88, p=0.005)
- 与本研究对比点: 同样发现 X 与 Y 的独立关联
- 原文来源: discussion_refs/author2024.pdf, Table 3

门控: 如果任何目标文献全文均未获取到（所有 Layer 都失败），标记该文献为"仅摘要引用"，Discussion 中不引述其具体数据，仅做方向性对比。

Phase 5: Discussion 撰写

结构: 镜像式 (结果→解释→比较→限制→结论)

¶1: 主要发现总结 (1段，不超过4句)
    ↓
¶2-3: 核心发现的解释和文献比较
    - 与同类研究的一致/不一致
    - 可能的机制解释
    ↓
¶4: 次要发现讨论
    ↓
¶5: 临床意义 (Clinical Implications)
    ↓
¶6: Limitations
    - 单中心
    - 回顾性设计
    - 缺失数据
    - 无外部验证
    - 样本量（引用对标数据防御）
    ↓
¶7: Conclusion (2-3句)

规则:

• Discussion 不引入新数据
• 不使用因果语言
• Limitations 必须涵盖所有主要弱点
• 每个 limitation 都应有"但是…"的辩护
• Conclusion 不能超出数据支持的范围

Phase 6: 结构化摘要

在正文写完后最后写摘要 — 确保与正文一致。

Aims: 1-2句研究目的
Methods and Results: 设计、N、主要方法、关键结果（HR+CI+p）
Conclusion: 1-2句结论 + 临床意义

摘要字数: ≤250词（ESC系列）

Phase 7: 组装与自检

1. 组装完整稿件（头部元数据 + 摘要 + 正文 + 图表说明 + 参考文献占位）
2. 自检清单:
   • 所有 N 与 population_registry 一致
   • 所有 HR/CI/p 与 analysis report 一致
   • Methods 中每个分析在 Results 中有结果
   • 所有图表在正文中被引用
   • 字数在预算范围内
   • 无因果语言

Phase 7b: 数字对账（自动触发）

Phase 7 自检通过后，自动触发 /qa check（NTC v2 轻量模式）。

触发条件: manuscript_draft.md 写入完成
输入: manuscript_draft.md + 项目 results/ 目录下所有 CSV
输出: 数字对账单（内嵌在终端输出中）

对账单示例:

| 位置 | 稿件值 | CSV值 | 来源 | 判定 |
|------|--------|-------|------|------|
| Abstract N= | 130 | 130 | group.csv:N | ✅ |
| §Results HR= | 1.58 | 1.58 | cox.csv:HR | ✅ |
| Table 2 p= | .003 | .0028 | comparison.csv:p | ✅ 四舍五入 |
| §3.7.1 p= | .56 | .918 | attrition.csv:p | ❌ |

统计: 38项 ✅32 ❌3 📖2 ⚪1

门控规则:

• ❌ = 0 → 自动通过，继续下游（reference-inserter / reviewer）
• ❌ ≥ 1 → 阻断，列出所有不匹配项，要求修正后重新触发
• ⚪ (UNTRACED) → 不阻断，但在对账单中标注"来历不明，请确认"

这是 NTC v2 的 T1 触发点——在写稿当下发现数字错误，修复成本最低。

引用占位符格式

初稿中使用占位符，后续由 academic-reference-inserter 替换:

Heart failure affects approximately 64 million people worldwide [REF: heart failure global prevalence].
Previous studies using latent class analysis identified distinct HF phenotypes [REF: LCA heart failure phenotyping].

与其他 Skill 的协作

• 上游: reference-manager /ref research → literature_summary.md（知识地基，必需）
• 上游: statistical-analysis → 分析报告
• 上游: data-profiler → 数据字典
• 上游: flow-diagram-generator → 人群流程图和登记表
• 上游: journal-benchmarker → 字数分配和对标数据
• 下游（即刻）: 本Skill Phase 7 完成 → 自动触发 quality-gate /qa check 数字对账
• 下游（对账通过后）: 初稿 → reference-manager /ref insert 替换占位符
• 下游（对账通过后）: 初稿 → manuscript-reviewer 6维审查
• 最终: submission-assembler 组装投稿包

更新日志

• v1.4 (2026-03-11): Phase 0b 迁移至 reference-manager /ref research
  • Phase 0b（文献预挖掘）完整逻辑迁移至 reference-manager v4.0 的 /ref research 子命令
  • 本 Skill Phase 0b 简化为依赖声明：要求 literature_summary.md 已存在
  • 上游协作关系更新：reference-manager 成为必需上游
  • 原因：literature 模块应包含完整的知识地基能力（Deep Research + 文献验证），而非散落在 manuscript-drafter 中
• v1.3 (2026-03-11): 新增 Phase 4b Discussion 对比文献全文获取
  • Discussion 写作前自动下载需对比的文献全文（5-10篇）
  • 四层下载回退: Unpaywall → PMC → PyPaperBot → CNKI+browser-use+Gemini
  • 输出 discussion_references.md，确保 Discussion 引述基于原文而非 AI 记忆
  • 全文均获取失败时降级为"仅摘要引用"，不引述具体数据
• v1.2 (2026-03-11): 新增 Phase 7b 数字对账自动触发
  • 写稿完成后自动调用 /qa check（NTC v2 轻量模式），生成数字对账单
  • 对账单有 ❌ 项时阻断下游（reference-inserter / reviewer），要求修正
  • 这是 NTC v2 的 T1 触发点——"写稿当下即校验"
  • 协作关系更新：quality-gate /qa check 成为 manuscript-drafter 的直接下游
• v1.1 (2026-02-27): 新增 Phase 0b 文献预挖掘
  • 嵌入 Semantic Scholar API 检索，替代"盲写 + 后期补引用"模式
  • 输出 literature_summary.md，按主题分组，供 Phase 2-6 直接引用
  • 含缓存跳过（7天内重用）和 WebFetch 降级逻辑，向后兼容
• v1.0 (2026-02-26): 初始版本
  • 7阶段撰写流程：信息收集 → 字数预算 → Intro → Methods → Results → Discussion → 组装自检
  • 引用占位符系统
  • 从 P-A 手动写稿经验中提炼的写作规则和结构模板