WUBING2023/PaperSpine · 上手攻略

  • 仓库：WUBING2023/PaperSpine
  • 链接：https://github.com/WUBING2023/PaperSpine
  • 分类：skill（学术写作 / agent）
  • 作者：Tom
  • 更新：2026-07-08

一、是什么

PaperSpine 是一个以"贡献为先、面向审稿人"为核心理念的学术写作系统，支持 Claude Code、Codex、OpenClaw 和 Hermes CLI 四个 AI Agent 宿主。它将学术论文写作拆解为 12 个有序阶段，每阶段有强制关卡（gate），不允许跳步，必须逐关通过才能进入下一阶段。

V4（当前版本 4.0.0）是重大升级：原本 12 个扁平的 worker skill 被收敛为一个名为 paper-spine 的编排 skill，所有路由逻辑集中在 SKILL.md 中，阶段 playbook 放在 references/ 目录，角色卡放在 agents/ 目录，结构清晰很多。

关键词：motivation 驱动、贡献为先、面向审稿人、LaTeX 安全审计、逐阶段关卡。

二、解决什么问题

学术论文写作中常见的坑：

  • 写了半天不知道核心贡献是什么 → PaperSpine 要求在 confirmed_contribution.md 确认之前不许开始实质写作
  • Results 只堆指标，没有验证任何贡献 → results_validation.md 要求每个 Results 子节至少验证一条贡献承诺
  • 写完才发现文章结构混乱、逻辑不自洽 → integrity_audit.py 在 LaTeX 组装前做完整性审计
  • 投稿材料不全或不符合期刊格式 → submission_package 阶段生成 highlights、cover letter 等
  • 审稿意见回复临时抱佛脚 → review_response 阶段协助生成结构化回复
  • AI 写作痕迹太重被审稿人识破 → humanize 阶段按 tier 应用去 AI 痕迹约束，输出 D1–D5 可测量指标

三、快速安装

前置要求

  • Git
  • Python ≥ 3.10
  • 对应宿主的 AI Agent（Claude Code / Codex / OpenClaw / Hermes CLI）

克隆仓库

git clone https://github.com/WUBING2023/PaperSpine.git
cd PaperSpine

安装（自动识别系统）

macOS / Linux：

bash install.sh

Windows PowerShell：

.\install.ps1

安装脚本会： 1. 从 src/ 生成 dist/（src/ 是唯一真源，dist/ 由同步脚本生成，不要手动改） 2. 把 paper-spine skill 安装到四个宿主对应位置 3. 不写入 settings.json（解决了旧版安装器抹掉配置的 issue #3）

清理旧版残留（从 3.x 升级必做）

# macOS / Linux
bash install.sh --clean-legacy

# Windows PowerShell
.\install.ps1 -CleanLegacy

⚠️ 从 3.x 升级到 4.0 必须手动重装并带 --clean-legacy，自动更新不适用（3.x 更新器会把新包判为"缺 11 个 skill"而中止）。

四、核心用法

4.1 启动入口

Claude Code / Codex：

/paperspine

当 paper_rewriting_output/paper_spine_config.json 缺失时，会自动启动 intake UI（外部终端）引导用户填写配置；兜底方案是 Python wizard：

python src/scripts/intake_wizard.py

OpenClaw / Hermes CLI：

直接调用 paper-spine skill 即可，缺配置时同样引导走 intake。

4.2 配置写作任务

配置写入两个文件：

paper_rewriting_output/paper_spine_config.json   # 机器可读配置
paper_rewriting_output/paper_spine_config.md     # 人类可读配置

关键配置字段：

{
  "scenario": "journal",          // journal | conference | report_review | competition
  "depth": "pro",                 // flash(3篇样例) | pro(6篇样例)
  "output_language": "en",        // en | zh
  "translation_package": false,    // true 时额外输出中文 Word
  "reference_mode": "local_first" // local_first | specified_paths | web
}

4.3 两条主流程

Rewrite Existing（改进已有论文）：

intake → research → citation → motivation_confirm → humanize(按需)
→ writing/drafting → integrity_audit → latex → submission_package(按需)
→ translation(按需) → review_response(按需) → final_audit

Build From Materials（从素材构筑论文）：

intake → research(读素材文件夹) → citation → motivation_confirm → ...

4.4 主要阶段速查

阶段 产物 说明
Intake paper_spine_config.json 校验配置，启动写作任务
Research research_dossier.md, sota_gap_map.md 学习目标场景 + 优秀样例 + SOTA
Citation citation_support_bank.md claim 级别引用支持库（默认 20 条，候选池 60 条）
Motivation Confirm confirmed_motivation.md BLOCKED：停下等用户确认 control 性的 motivation
Humanize（按需） 去 AI 痕迹报告 D1–D5 五维度可测量指标
Writing/Drafting section_blueprints.md, writing_rationale_matrix.md 蓝图 + 写作思路矩阵
Integrity Audit 完整性报告 LaTeX 组装前完整性检查
LaTeX / PDF / Word main.tex, paper.pdf, paper.docx 编译产出
Submission Package（按需） highlights, cover letter 投稿材料
Translation（按需） translation_zh/, paper.zh.docx 中文化包
Review Response（按需） review_response/ 审稿意见回复
Final Audit 全部产物 三个方法论硬关卡任一失败不得宣布完成

4.5 核心产物解读

最重要：writing_rationale_matrix.md

每个论文单元（section/subsection）必须解释：该单元承担什么功能、如何服务确认后的贡献与 motivation、学习了哪些 SOTA / 样例、使用了什么证据、最终文本应通过什么检查。

第二重要：citation_support_bank.md

每个候选引用必须包含：参考文献/BibTeX 信息、年份、来源，以及一两句可以支撑正文论述的句子。不是罗列文献，而是绑定到具体 claim 级别。

4.6 检查产物完整性

# 完整度检查
python src/scripts/artifact_check.py paper_rewriting_output --markdown --write

# 逐阶段关卡检查
python src/scripts/progress_check.py paper_rewriting_output --gate final_audit

# 贡献检查（V4 核心）
python src/scripts/contribution_check.py paper_rewriting_output --markdown --write

# 结果验证检查
python src/scripts/results_validation_check.py paper_rewriting_output --markdown --write

# 审稿人审计检查
python src/scripts/reviewer_audit_check.py paper_rewriting_output --markdown --write

# LaTeX 安全审计
python src/scripts/latex_guard.py paper_rewriting_output/final_paper/main.tex --markdown

# Word 产出检查
python src/scripts/word_guard.py paper_rewriting_output/final_paper/paper.docx --markdown

# 引用库检查
python src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md --target-count 20 --markdown

# 运行测试
python -m pytest tests -q

4.7 自更新（4.0+）

# 在宿主中调用 paper-spine update 路由
# /paperspine update

# 或手动
python src/scripts/paperspine_update.py --check-only   # 只检查
python src/scripts/paperspine_update.py --yes           # 检查并更新

五、典型适用场景

  1. 期刊论文（journal） — 英文 SCI/SSCI 期刊投稿
  2. 会议论文（conference） — ACL/NeurIPS/ICML 等会议投稿
  3. 综述 / 课程报告（report_review） — 文献综述、技术报告
  4. 竞赛论文（competition） — Kaggle 报告、各类学术竞赛
  5. 英译中翻译包 — 英文论文产出后额外生成中文 Word

六、坑与注意

坑 说明
3.x → 4.0 必须手动重装 自更新会把新包判为"缺 11 个 skill"而中止；务必跑一次 install.sh --clean-legacy
macOS 上首次运行报 "incomplete" 旧校验器不认识新版 dist 结构；按上面重装方法解决（4.0.0 起修复）
Motivation 必须用户确认才能继续 motivation_confirm 阶段是 BLOCKED 的，Agent 不会自动选择；必须人工介入
LaTeX 编译器非必须但推荐 有编译器才产 paper.pdf；没有的话只输出 main.tex 和 paper.docx
样例论文需要用户提供 reference_mode=local_first 时需在当前目录有参考材料；可配合 reference_inventory.py 建立索引
不要把整个仓库直接复制进 skills 目录 旧版玩家常犯的错误；安装器会自动做结构映射，手动复制会导致 skill 重复或缺失

七、与同类对比

方案 定位 AI 宿主 特点
PaperSpine 学术论文全流程写作 Claude Code / Codex / OpenClaw / Hermes 12 阶段关卡、贡献驱动、去 AI 痕迹
LaTeX-first 工作流 LaTeX 模板填充 任意 LLM 简单但无结构管控
普通润色 Agent 改写句子 任意 LLM 只改语言不改逻辑
Word 模板 + LLM 结构化填充 任意 LLM 格式可控但缺乏写作过程管控

PaperSpine 的核心差异：不只改句子，而是从"贡献确认"开始管论文的逻辑结构和投稿准备度；关卡强制执行，不可跳过。

八、一句话推荐结论

如果你经常需要写或改写英文学术论文（期刊/会议/竞赛），且希望 AI Agent 的帮助从"改句子"升级到"管结构、管贡献、管投稿材料"，PaperSpine V4 的 12 阶段编排和三个方法论硬关卡值得认真用起来；但它学习成本不低，第一次跑通全流程可能需要 1–2 小时配置。

来源：GitHub README（中文版）、repo_cards 卡片（Stars 3,848 / 周增 +189 / 分类 trending / MIT 协议 / Python）