PaperSpine

English | 中文

PaperSpine 使用讲解视频（Bilibili）

配音贡献：https://github.com/YiShanZheng

🌍 订阅者星图 · 看看哪些高校和城市在用 PaperSpine

PaperSpine 是一个以「贡献为先、面向审稿人」为核心的学术写作系统，支持 Claude Code、Codex、OpenClaw 和 Hermes CLI 四个宿主。

它适合目标格式很重要的写作任务：期刊论文、会议论文、课程或技术报告、综述、竞赛论文。PaperSpine 要求 agent 先学习目标场景和优秀样例，先和用户确认论文的「贡献」，再逐单元设计文章，最后才写作或重建稿件，并输出 LaTeX / PDF / Word。

V4 不再是 12 个扁平 worker skill 的套件，而是 一个 名为 paper-spine 的编排 skill：12 个阶段的路由都在 SKILL.md 内完成，每个阶段读取 references/ 下对应的 playbook，角色信息放在 agents/ 中。

仓库结构

PaperSpine/
  src/                          # 唯一真源
    skill/
      SKILL.md                  # 单一 paper-spine 编排 skill（含 12 阶段路由）
      references/               # 各阶段 playbook（40+ 篇）
      agents/                   # 角色卡（研究、审稿人等）
    scripts/                    # 确定性辅助与关卡脚本
    adapters/                   # 各宿主适配（claude / codex / hermes）
  dist/                         # 由 sync 从 src/ 生成（不要手改）
    claude/skills/paper-spine/  # Claude Code 单 skill
    claude/commands/paperspine.md
    codex/skills/paper-spine/   # Codex 单 skill
    codex/prompts/paperspine.md
    openclaw/skills/paper-spine/ # OpenClaw 单 skill
    hermes/skills/academic-writing/paper-spine/  # Hermes CLI 单 skill
    paperspine_version.json     # 版本元数据（4.0.0）
  .claude-plugin/               # Claude Code 插件元数据
  install.ps1                   # Windows 安装器（薄包装）
  install.sh                    # macOS / Linux 安装器（薄包装）
  README.md
  README.en.md

src/ 是唯一真源，dist/ 完全由同步脚本 src/scripts/sync_local_installs.py 从 src/skill + src/scripts + src/adapters 生成。不要直接编辑 dist/。

快速安装

Windows PowerShell：

git clone https://github.com/WUBING2023/PaperSpine.git
cd PaperSpine
.\install.ps1

macOS / Linux：

git clone https://github.com/WUBING2023/PaperSpine.git
cd PaperSpine
bash install.sh

install.ps1 和 install.sh 都是薄包装，统一委托给 src/scripts/sync_local_installs.py：脚本会先从 src/ 生成 dist/，再把同一个 paper-spine skill 安装到四个宿主。它对 PowerShell 5.1 友好，并且 永不写入 settings.json（修复了 issue #3 中旧安装器抹掉 settings.json 的问题）。

清理旧版残留：

.\install.ps1 -CleanLegacy

bash install.sh --clean-legacy

-CleanLegacy / --clean-legacy 会清理旧 PaperSpine 目录和遗留的 paper-spine-* worker 副本，避免重复发现或找不到 skill。安装器会把当前版本写入 ~/.paperspine/install_state.json，并保留 ~/.paperspine/config.json（含 UI 语言等全局配置）。

四个宿主

同一个 paper-spine skill 被安装到四个宿主，互不混用：

宿主	安装位置	常用入口
Claude Code	~/.claude/skills/paper-spine + ~/.claude/commands/paperspine.md	/paperspine 命令
Codex	~/.codex/skills/paper-spine + ~/.codex/prompts/paperspine.md	/paperspine prompt
OpenClaw	~/.openclaw/skills/paper-spine	paper-spine
Hermes CLI	~/AppData/Local/hermes/skills/academic-writing/paper-spine	paper-spine

对应的 dist/ 来源分别是 dist/claude/skills、dist/claude/commands、dist/codex/skills、dist/openclaw/skills 和 dist/hermes/skills/academic-writing。安装后请重启或 reload 对应宿主。不要把整个仓库直接复制进 skills 文件夹——那是重复或缺失 skill 的主要原因。

/paperspine 入口

在 Claude Code 和 Codex 中，推荐统一用：

/paperspine

当 paper_rewriting_output/paper_spine_config.json 缺失时，这个入口会自动启动外部终端 intake UI 来收集配置，而不是让用户手写 JSON。兜底方式是 Python wizard：

python src/scripts/intake_wizard.py

配置完成后会生成：

paper_rewriting_output/paper_spine_config.json
paper_rewriting_output/paper_spine_config.md

OpenClaw 和 Hermes CLI 没有 slash 入口，直接调用 paper-spine skill 即可，缺配置时同样会引导走 intake。

Claude Code 插件安装

Claude Code 也可以用 .claude-plugin 中的插件元数据：

/plugin marketplace add https://github.com/WUBING2023/PaperSpine
/plugin install paper-spine
/reload-plugins

插件 manifest 指向 dist/claude/skills 下的单一 paper-spine skill。

主工作流

PaperSpine 有两条平级主流程：

1. Rewrite Existing：改进已有论文或报告，但不把任务降级成简单润色。
2. Build From Materials：从素材文件夹构筑论文或报告，素材可以包括说明文档、图片、PDF、数据摘要、部分初稿和实验描述。

支持四类目标场景：

• journal：期刊论文
• conference：会议论文
• report_review：课程报告、技术报告或综述
• competition：竞赛论文或竞赛报告

研究深度：

• flash：3 篇目标场景样例、3 篇近期/高质量同领域论文和官方要求。
• pro：6 篇目标场景样例、6 篇近期/高质量同领域论文和官方要求。

输出语言为 en 或 zh。选择英文输出时，可通过 translation_package=zh 额外生成中文翻译包，并产出最终中文 Word 文档。

方法论升级（V4）

V4 在原有的 motivation 主线之上，引入三条由关卡强制执行的核心规则。motivation 仍然必需（confirmed_motivation.md），但它现在服务于「贡献」，而不再是顶层组织单元。

1. Contribution-First（贡献为先）：稿件最高优先级的组织单元是已确认的贡献。在 confirmed_contribution.md 存在之前不得开始实质写作。关卡：contribution_check.py。
2. Results-as-Validation（结果即验证）：每个主要 Results 子节都必须验证至少一条贡献承诺，只有指标、没有映射到贡献的单元视为失败，记录于 results_validation.md。关卡：results_validation_check.py。
3. Reviewer-Aware（面向审稿人）：在声称「可投稿」之前，必须基于三个审稿人角色生成 reviewer_audit.md（审稿人价值图 + 异议登记 + 期刊匹配）。关卡：reviewer_audit_check.py。

第 12 阶段的最终审计硬关卡会一次性运行这三个检查，任一失败都不得宣布完成。

12 阶段编排

paper-spine 编排 skill 不直接修句子，而是逐阶段路由，每个阶段读取 references/ 下的 playbook：

1. Intake：校验 paper_spine_config.json。
2. Research：学习目标场景、本地/指定参考资料和优秀样例。
3. Citation：构建 claim 级别的引用支持库。
4. Motivation Confirmation：停下等用户确认控制性 motivation（BLOCKED，不自动选择）。
5. Humanize（按需）：按 tier 应用去 AI 痕迹约束。
6. Writing / Drafting：rewrite 或 build，先产出蓝图与写作思路矩阵。
7. Integrity Audit：LaTeX 组装前的完整性审计。
8. LaTeX / PDF / Word：生成并检查 LaTeX、可用时编译 PDF，并产出 Word。
9. Submission Package（按需）：highlights、cover letter 等投稿材料。
10. Translation Package（按需）：英文输出时产出 translation_zh/ 翻译包及最终中文 Word。
11. Review Response（按需）：生成审稿意见回复。
12. Final Audit：完成度硬关卡，所有检查通过才算完成。

每个阶段都是一道关卡，由 progress_check.py --gate <stage> 把守；关卡失败就路由回该阶段，不允许跳过或手写缺失产物。历史上的 paper-spine-research 等 worker 名称只是遗留别名，不再是用户入口。

V4 新能力

• 阶段关卡 + 断点续跑：progress_check.py 提供逐阶段 gate，并支持从第一个未完成阶段 resume 续跑，不必从头重来。
• 投稿材料包：submission_check.py 校验 highlights、cover letter 等投稿材料。
• 审稿意见回复：respond_check.py 协助生成结构化的 review response。
• 英文引用核验：citation_verification_en.py 对英文稿件中的引用进行核验。
• 更深的去 AI 痕迹（humanize）：humanize_check.py 按 light / medium / heavy 分级，输出 D1–D5 五个维度的可测量指标，区分必过项与建议项。

本地参考文献读取

参考材料获取不再只依赖网络。配置字段 reference_mode 控制 PaperSpine 如何开始文献和样例读取：

• local_first：默认。先索引当前工作文件夹中的参考材料，再按需进行网络补充。
• specified_paths：只索引 reference_paths 中指定的文件夹或文件，再按任务需要补充。
• web：用户没有本地参考材料时使用网络收集。

本地参考路径会写入 paper_rewriting_output/reference_materials/source_index.md。辅助脚本：

python src/scripts/reference_inventory.py . --output-dir paper_rewriting_output --mode local_first

PaperSpine 可以读取用户提供的 PDF、下载论文、BibTeX/RIS、模板、笔记、学校或竞赛文档。它不能绕过付费墙或私有数据库权限。

引用支持库

Citation 阶段会生成 paper_rewriting_output/citation_support_bank.md。它和优秀论文学习是两件事：样例论文用于学习结构和写法；引用支持库用于为 Introduction、Related Work、Discussion、局限性、应用背景等位置提供可选择的候选引用。

默认行为：

• citation_target_count：20
• 候选池：citation_target_count * 3，默认 60
• 近期论文目标：约 80% 候选来自近三年（2026 年的简单阈值是 2023 年及以后）
• 每一行候选都必须包含参考文献/BibTeX 风格信息、年份、来源，以及一两句可以支撑正文论述的句子

检查引用库：

python src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md --target-count 20 --markdown

关键产物

一次完整运行不应该只有最终论文，而应留下完整可审计的写作轨迹：

paper_rewriting_output/
  paper_spine_config.json
  paper_spine_config.md
  reference_materials/source_index.md
  research_dossier.md
  exemplar_learning_dossier.md
  style_profile.md
  sota_gap_map.md
  motivation_options_after_research.md
  citation_support_bank.md
  confirmed_motivation.md
  confirmed_contribution.md       # V4 贡献为先
  results_validation.md           # V4 结果即验证
  reviewer_audit.md               # V4 面向审稿人
  section_blueprints.md
  writing_rationale_matrix.md
  latex_report.md
  final_artifact_manifest.md
  final_paper/
    main.tex
    references.bib
    figures/
    paper.pdf                     # 本机有 LaTeX 编译器时生成
    paper.docx                    # 英文 Word 输出
    paper.zh.docx                 # output_language=zh 或翻译包时生成
  submission_package/             # 请求投稿材料时
  review_response/                # 请求审稿回复时
  translation_zh/                 # translation_package=zh 时

最核心产物是 writing_rationale_matrix.md。它必须按真实论文或报告结构逐单元解释：该单元承担什么功能、如何服务确认后的贡献与 motivation、学习了哪些 SOTA 或目标场景样例、使用了哪些证据、最终文本应通过什么检查。citation_support_bank.md 是第二个重要推理产物，它让每个候选引用在进入正文前先绑定到一个具体句子级 claim。

检查命令

检查产物完整性：

python src/scripts/artifact_check.py paper_rewriting_output --markdown --write

各阶段关卡与方法论硬关卡：

python src/scripts/progress_check.py paper_rewriting_output --gate final_audit
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
python src/scripts/integrity_audit.py paper_rewriting_output --markdown --write

检查 LaTeX 与 Word：

python src/scripts/latex_guard.py paper_rewriting_output/final_paper/main.tex --markdown
python src/scripts/word_guard.py paper_rewriting_output/final_paper/paper.docx --markdown

检查本地参考索引与引用候选覆盖：

python src/scripts/reference_inventory.py . --output-dir paper_rewriting_output --mode local_first
python src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md --target-count 20 --markdown

运行项目测试：

python -m pytest tests -q

更新 PaperSpine

第一次安装之后，如果想检查或更新本地安装，可以在宿主里让 paper-spine 走 update 路由（/paperspine update），它会运行：

python src/scripts/paperspine_update.py --yes

它会把 ~/.paperspine/install_state.json 中记录的版本和 GitHub main 上的 dist/paperspine_version.json 进行比较。已是最新版会直接提示；发现新版本时会下载 GitHub 压缩包、校验 PaperSpine 目录结构，然后同步更新四个宿主的 paper-spine skill，并保留 ~/.paperspine/config.json。只想检查而不修改本地安装：

python src/scripts/paperspine_update.py --check-only

PaperSpine 试图避免的问题

• 只改句子，不改论文逻辑或贡献。
• 没确认贡献和 motivation 就开始写。
• Results 只堆指标，却不验证任何一条贡献承诺。
• 在没做面向审稿人审计的情况下声称「可投稿」。
• 添加没有证据支撑的 claim。
• 只输出 main.tex，但不解释为什么这样设计文章，也不产出 Word。
• 用户要求翻译包时，只翻译一部分中间产物。

License

MIT License. See LICENSE.