PaperSpine README

The project's README from github.com/WUBING2023/PaperSpine. As one markdown file: README.md.

PaperSpine 山脊印章标志

PaperSpine

English | 中文

PaperSpine 使用讲解视频(Bilibili)

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

🌍 社区 Stargazer 星图 · 公开 GitHub 社区信号

PaperSpine5 发布候选版

PaperSpine5 0.3.0-rc.1 在保留本仓库 V4 安装与更新身份的基础上,增加五阶段本地科研生产工作区。请从中文发布页开始:先把完整的零起点安装指令交给 AI,也可以按宿主选择 Codex、Claude Code 或 DSH 插件包。GitHub prerelease提供四个原样 ZIP、SHA-256、manifest 与验证证据。

V5 当前是显式选择的 RC,不会替换 V4 的 dist/paperspine_version.json 更新源。更新检查默认关闭;发布软件也不代表授权任何论文外部投稿。精确范围、限制与回滚方式见 RELEASE-NOTES-v0.3.0-rc.1.md 和 ROLLBACK.md。

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、数据摘要、部分初稿和实验描述。

支持四类目标场景:

研究深度:

输出语言为 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 新能力

本地参考文献读取

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

本地参考路径会写入 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、局限性、应用背景等位置提供可选择的候选引用。

默认行为:

检查引用库:

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

⚠️ 从 3.x 升级到 4.0 请手动重装,自更新不适用。 4.0 把原来的 12 个子技能收敛成单一 paper-spine orchestrator,3.x 的更新器会把新包判为「缺 11 个 skill」而中止。跑一次安装脚本,务必带 --clean-legacy(否则旧的 worker skill 会残留,cc switch 里会新旧混杂):

  • Windows:powershell -File install.ps1 -CleanLegacy
  • macOS/Linux:bash install.sh --clean-legacy

装完 --check-only 会显示 already latest: 4.0.0,之后自更新恢复正常。4.0 起的更新器已前向容错,不会再因文档改名等原因中止。

第一次安装之后,如果想检查或更新本地安装,可以在宿主里让 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

仍报 "incomplete"? 任何旧版本自更新到新版报 Downloaded PaperSpine package is incomplete,都是旧版校验器拒收新版包导致的(升级跑的是本地旧校验器,issue #13)。按上面的手动重装即可打通;也可直接从 main 复制 dist/claude/skills/* 与 dist/claude/commands/paperspine.md 到 ~/.claude/skills/、~/.claude/commands/。4.0.0 起的更新器对可选文件(README / 安装脚本)只告警不中止,此问题不再复发。

PaperSpine 试图避免的问题

License

MIT License. See LICENSE.

贡献者

PaperSpine (WUBING2023/PaperSpine)

Searching Database…

What is this?PaperSpine is a local-first academic writing system that orchestrates research, citation sourcing, drafting, review and delivery of papers, enforcing that every claim is backed by confirmed contributions and evidence before a manuscript can be called submittable.
Is this a standalone app or something I install into my AI coding agent?It is not a standalone app; it is an orchestration 'skill' that gets installed into an existing AI coding agent host. A single paper-spine skill routes all 12 writing stages internally rather than shipping as 12 separate tools.
Which coding agents does it need?You need one of four supported hosts already set up: Claude Code, Codex, OpenClaw, or Hermes CLI. The skill installs into each host's own skills folder and is invoked from inside that host, so no separate API key is required by PaperSpine itself.
Does it just start writing once I give it materials?No — writing is hard-blocked behind a Contribution-First gate: no substantive drafting can start until confirmedcontribution.md exists, and the Motivation Confirmation stage stops and waits for explicit user approval instead of auto-selecting a motivation.
Who is this built for?Researchers and students writing journal papers, conference papers, course or technical reports, literature reviews, or competition papers where matching the target format and venue matters.
What final outputs does a full run produce?Beyond the paper itself, PaperSpine generates LaTeX source, a compiled PDF, a Word document, a writingrationalematrix.md explaining every section's reasoning, and a citationsupportbank.md binding each cited claim to evidence.
Does it write in English and Chinese?Yes, output language is English or Chinese; if you choose English, you can request translationpackage=zh to also generate a Chinese translation package and a final Chinese Word document.
How do I upgrade from an older version?Upgrading from 3.x requires a manual reinstall with --clean-legacy since the old 12-skill layout is incompatible with V4's single orchestrator; from 4.0 onward the built-in updater (via /paperspine update) checks and applies new versions automatically.
Creator
WUBING2023
Size
93.4 MB
Stars
6K
Updated
CommitOct 14
Age
5mo
Commits · 90 Days