{
  "markdown": "<p align=\"center\">\n  <img src=\"website/assets/brand/paperspine-mark.svg\" width=\"112\" alt=\"PaperSpine 山脊印章标志\">\n</p>\n\n# PaperSpine\n\n[English](README.en.md) | [中文](README.md)\n\n[**PaperSpine 使用讲解视频（Bilibili）**](https://www.bilibili.com/video/BV1rjVa6ZEYu)\n\n配音贡献：[https://github.com/YiShanZheng](https://github.com/YiShanZheng)\n\n[**🌍 社区 Stargazer 星图 · 公开 GitHub 社区信号**](https://wubing2023.github.io/PaperSpine/)\n\n## PaperSpine5 发布候选版\n\nPaperSpine5 `0.3.0-rc.1` 在保留本仓库 V4 安装与更新身份的基础上，增加五阶段本地科研生产工作区。请从[中文发布页](https://wubing2023.github.io/PaperSpine/v5/)开始：先把完整的零起点安装指令交给 AI，也可以按宿主选择 Codex、Claude Code 或 DSH 插件包。[GitHub prerelease](https://github.com/WUBING2023/PaperSpine/releases/tag/v0.3.0-rc.1)提供四个原样 ZIP、SHA-256、manifest 与验证证据。\n\nV5 当前是显式选择的 RC，不会替换 V4 的 `dist/paperspine_version.json` 更新源。更新检查默认关闭；发布软件也不代表授权任何论文外部投稿。精确范围、限制与回滚方式见 [`RELEASE-NOTES-v0.3.0-rc.1.md`](RELEASE-NOTES-v0.3.0-rc.1.md) 和 [`ROLLBACK.md`](ROLLBACK.md)。\n\n\n> PaperSpine 是一个以「贡献为先、面向审稿人」为核心的学术写作系统，支持 Claude Code、Codex、OpenClaw 和 Hermes CLI 四个宿主。\n\n它适合目标格式很重要的写作任务：期刊论文、会议论文、课程或技术报告、综述、竞赛论文。PaperSpine 要求 agent 先学习目标场景和优秀样例，先和用户确认论文的「贡献」，再逐单元设计文章，最后才写作或重建稿件，并输出 LaTeX / PDF / Word。\n\nV4 不再是 12 个扁平 worker skill 的套件，而是 **一个** 名为 `paper-spine` 的编排 skill：12 个阶段的路由都在 `SKILL.md` 内完成，每个阶段读取 `references/` 下对应的 playbook，角色信息放在 `agents/` 中。\n\n## 仓库结构\n\n```text\nPaperSpine/\n  src/                          # 唯一真源\n    skill/\n      SKILL.md                  # 单一 paper-spine 编排 skill（含 12 阶段路由）\n      references/               # 各阶段 playbook（40+ 篇）\n      agents/                   # 角色卡（研究、审稿人等）\n    scripts/                    # 确定性辅助与关卡脚本\n    adapters/                   # 各宿主适配（claude / codex / hermes）\n  dist/                         # 由 sync 从 src/ 生成（不要手改）\n    claude/skills/paper-spine/  # Claude Code 单 skill\n    claude/commands/paperspine.md\n    codex/skills/paper-spine/   # Codex 单 skill\n    codex/prompts/paperspine.md\n    openclaw/skills/paper-spine/ # OpenClaw 单 skill\n    hermes/skills/academic-writing/paper-spine/  # Hermes CLI 单 skill\n    paperspine_version.json     # 版本元数据（4.0.0）\n  .claude-plugin/               # Claude Code 插件元数据\n  install.ps1                   # Windows 安装器（薄包装）\n  install.sh                    # macOS / Linux 安装器（薄包装）\n  README.md\n  README.en.md\n```\n\n`src/` 是唯一真源，`dist/` 完全由同步脚本 `src/scripts/sync_local_installs.py` 从 `src/skill` + `src/scripts` + `src/adapters` 生成。不要直接编辑 `dist/`。\n\n## 快速安装\n\nWindows PowerShell：\n\n```powershell\ngit clone https://github.com/WUBING2023/PaperSpine.git\ncd PaperSpine\n.\\install.ps1\n```\n\nmacOS / Linux：\n\n```bash\ngit clone https://github.com/WUBING2023/PaperSpine.git\ncd PaperSpine\nbash install.sh\n```\n\n`install.ps1` 和 `install.sh` 都是薄包装，统一委托给 `src/scripts/sync_local_installs.py`：脚本会先从 `src/` 生成 `dist/`，再把同一个 `paper-spine` skill 安装到四个宿主。它对 PowerShell 5.1 友好，并且 **永不写入 settings.json**（修复了 issue #3 中旧安装器抹掉 settings.json 的问题）。\n\n清理旧版残留：\n\n```powershell\n.\\install.ps1 -CleanLegacy\n```\n\n```bash\nbash install.sh --clean-legacy\n```\n\n`-CleanLegacy` / `--clean-legacy` 会清理旧 PaperSpine 目录和遗留的 `paper-spine-*` worker 副本，避免重复发现或找不到 skill。安装器会把当前版本写入 `~/.paperspine/install_state.json`，并保留 `~/.paperspine/config.json`（含 UI 语言等全局配置）。\n\n## 四个宿主\n\n同一个 `paper-spine` skill 被安装到四个宿主，互不混用：\n\n| 宿主 | 安装位置 | 常用入口 |\n| --- | --- | --- |\n| Claude Code | `~/.claude/skills/paper-spine` + `~/.claude/commands/paperspine.md` | `/paperspine` 命令 |\n| Codex | `~/.codex/skills/paper-spine` + `~/.codex/prompts/paperspine.md` | `/paperspine` prompt |\n| OpenClaw | `~/.openclaw/skills/paper-spine` | `paper-spine` |\n| Hermes CLI | `~/AppData/Local/hermes/skills/academic-writing/paper-spine` | `paper-spine` |\n\n对应的 `dist/` 来源分别是 `dist/claude/skills`、`dist/claude/commands`、`dist/codex/skills`、`dist/openclaw/skills` 和 `dist/hermes/skills/academic-writing`。安装后请重启或 reload 对应宿主。不要把整个仓库直接复制进 `skills` 文件夹——那是重复或缺失 skill 的主要原因。\n\n## /paperspine 入口\n\n在 Claude Code 和 Codex 中，推荐统一用：\n\n```text\n/paperspine\n```\n\n当 `paper_rewriting_output/paper_spine_config.json` 缺失时，这个入口会自动启动外部终端 intake UI 来收集配置，而不是让用户手写 JSON。兜底方式是 Python wizard：\n\n```powershell\npython src/scripts/intake_wizard.py\n```\n\n配置完成后会生成：\n\n```text\npaper_rewriting_output/paper_spine_config.json\npaper_rewriting_output/paper_spine_config.md\n```\n\nOpenClaw 和 Hermes CLI 没有 slash 入口，直接调用 `paper-spine` skill 即可，缺配置时同样会引导走 intake。\n\n## Claude Code 插件安装\n\nClaude Code 也可以用 `.claude-plugin` 中的插件元数据：\n\n```text\n/plugin marketplace add https://github.com/WUBING2023/PaperSpine\n/plugin install paper-spine\n/reload-plugins\n```\n\n插件 manifest 指向 `dist/claude/skills` 下的单一 `paper-spine` skill。\n\n## 主工作流\n\nPaperSpine 有两条平级主流程：\n\n1. **Rewrite Existing**：改进已有论文或报告，但不把任务降级成简单润色。\n2. **Build From Materials**：从素材文件夹构筑论文或报告，素材可以包括说明文档、图片、PDF、数据摘要、部分初稿和实验描述。\n\n支持四类目标场景：\n\n- `journal`：期刊论文\n- `conference`：会议论文\n- `report_review`：课程报告、技术报告或综述\n- `competition`：竞赛论文或竞赛报告\n\n研究深度：\n\n- `flash`：3 篇目标场景样例、3 篇近期/高质量同领域论文和官方要求。\n- `pro`：6 篇目标场景样例、6 篇近期/高质量同领域论文和官方要求。\n\n输出语言为 `en` 或 `zh`。选择英文输出时，可通过 `translation_package=zh` 额外生成中文翻译包，并产出最终中文 Word 文档。\n\n## 方法论升级（V4）\n\nV4 在原有的 motivation 主线之上，引入三条由关卡强制执行的核心规则。motivation 仍然必需（`confirmed_motivation.md`），但它现在服务于「贡献」，而不再是顶层组织单元。\n\n1. **Contribution-First（贡献为先）**：稿件最高优先级的组织单元是已确认的贡献。在 `confirmed_contribution.md` 存在之前不得开始实质写作。关卡：`contribution_check.py`。\n2. **Results-as-Validation（结果即验证）**：每个主要 Results 子节都必须验证至少一条贡献承诺，只有指标、没有映射到贡献的单元视为失败，记录于 `results_validation.md`。关卡：`results_validation_check.py`。\n3. **Reviewer-Aware（面向审稿人）**：在声称「可投稿」之前，必须基于三个审稿人角色生成 `reviewer_audit.md`（审稿人价值图 + 异议登记 + 期刊匹配）。关卡：`reviewer_audit_check.py`。\n\n第 12 阶段的最终审计硬关卡会一次性运行这三个检查，任一失败都不得宣布完成。\n\n## 12 阶段编排\n\n`paper-spine` 编排 skill 不直接修句子，而是逐阶段路由，每个阶段读取 `references/` 下的 playbook：\n\n1. **Intake**：校验 `paper_spine_config.json`。\n2. **Research**：学习目标场景、本地/指定参考资料和优秀样例。\n3. **Citation**：构建 claim 级别的引用支持库。\n4. **Motivation Confirmation**：停下等用户确认控制性 motivation（BLOCKED，不自动选择）。\n5. **Humanize**（按需）：按 tier 应用去 AI 痕迹约束。\n6. **Writing / Drafting**：rewrite 或 build，先产出蓝图与写作思路矩阵。\n7. **Integrity Audit**：LaTeX 组装前的完整性审计。\n8. **LaTeX / PDF / Word**：生成并检查 LaTeX、可用时编译 PDF，并产出 Word。\n9. **Submission Package**（按需）：highlights、cover letter 等投稿材料。\n10. **Translation Package**（按需）：英文输出时产出 `translation_zh/` 翻译包及最终中文 Word。\n11. **Review Response**（按需）：生成审稿意见回复。\n12. **Final Audit**：完成度硬关卡，所有检查通过才算完成。\n\n每个阶段都是一道关卡，由 `progress_check.py --gate <stage>` 把守；关卡失败就路由回该阶段，不允许跳过或手写缺失产物。历史上的 `paper-spine-research` 等 worker 名称只是遗留别名，不再是用户入口。\n\n## V4 新能力\n\n- **阶段关卡 + 断点续跑**：`progress_check.py` 提供逐阶段 gate，并支持从第一个未完成阶段 `resume` 续跑，不必从头重来。\n- **投稿材料包**：`submission_check.py` 校验 highlights、cover letter 等投稿材料。\n- **审稿意见回复**：`respond_check.py` 协助生成结构化的 review response。\n- **英文引用核验**：`citation_verification_en.py` 对英文稿件中的引用进行核验。\n- **更深的去 AI 痕迹（humanize）**：`humanize_check.py` 按 `light` / `medium` / `heavy` 分级，输出 D1–D5 五个维度的可测量指标，区分必过项与建议项。\n\n## 本地参考文献读取\n\n参考材料获取不再只依赖网络。配置字段 `reference_mode` 控制 PaperSpine 如何开始文献和样例读取：\n\n- `local_first`：默认。先索引当前工作文件夹中的参考材料，再按需进行网络补充。\n- `specified_paths`：只索引 `reference_paths` 中指定的文件夹或文件，再按任务需要补充。\n- `web`：用户没有本地参考材料时使用网络收集。\n\n本地参考路径会写入 `paper_rewriting_output/reference_materials/source_index.md`。辅助脚本：\n\n```powershell\npython src/scripts/reference_inventory.py . --output-dir paper_rewriting_output --mode local_first\n```\n\nPaperSpine 可以读取用户提供的 PDF、下载论文、BibTeX/RIS、模板、笔记、学校或竞赛文档。它不能绕过付费墙或私有数据库权限。\n\n## 引用支持库\n\nCitation 阶段会生成 `paper_rewriting_output/citation_support_bank.md`。它和优秀论文学习是两件事：样例论文用于学习结构和写法；引用支持库用于为 Introduction、Related Work、Discussion、局限性、应用背景等位置提供可选择的候选引用。\n\n默认行为：\n\n- `citation_target_count`：`20`\n- 候选池：`citation_target_count * 3`，默认 `60`\n- 近期论文目标：约 `80%` 候选来自近三年（2026 年的简单阈值是 2023 年及以后）\n- 每一行候选都必须包含参考文献/BibTeX 风格信息、年份、来源，以及一两句可以支撑正文论述的句子\n\n检查引用库：\n\n```powershell\npython src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md --target-count 20 --markdown\n```\n\n## 关键产物\n\n一次完整运行不应该只有最终论文，而应留下完整可审计的写作轨迹：\n\n```text\npaper_rewriting_output/\n  paper_spine_config.json\n  paper_spine_config.md\n  reference_materials/source_index.md\n  research_dossier.md\n  exemplar_learning_dossier.md\n  style_profile.md\n  sota_gap_map.md\n  motivation_options_after_research.md\n  citation_support_bank.md\n  confirmed_motivation.md\n  confirmed_contribution.md       # V4 贡献为先\n  results_validation.md           # V4 结果即验证\n  reviewer_audit.md               # V4 面向审稿人\n  section_blueprints.md\n  writing_rationale_matrix.md\n  latex_report.md\n  final_artifact_manifest.md\n  final_paper/\n    main.tex\n    references.bib\n    figures/\n    paper.pdf                     # 本机有 LaTeX 编译器时生成\n    paper.docx                    # 英文 Word 输出\n    paper.zh.docx                 # output_language=zh 或翻译包时生成\n  submission_package/             # 请求投稿材料时\n  review_response/                # 请求审稿回复时\n  translation_zh/                 # translation_package=zh 时\n```\n\n最核心产物是 `writing_rationale_matrix.md`。它必须按真实论文或报告结构逐单元解释：该单元承担什么功能、如何服务确认后的贡献与 motivation、学习了哪些 SOTA 或目标场景样例、使用了哪些证据、最终文本应通过什么检查。`citation_support_bank.md` 是第二个重要推理产物，它让每个候选引用在进入正文前先绑定到一个具体句子级 claim。\n\n## 检查命令\n\n检查产物完整性：\n\n```powershell\npython src/scripts/artifact_check.py paper_rewriting_output --markdown --write\n```\n\n各阶段关卡与方法论硬关卡：\n\n```powershell\npython src/scripts/progress_check.py paper_rewriting_output --gate final_audit\npython src/scripts/contribution_check.py paper_rewriting_output --markdown --write\npython src/scripts/results_validation_check.py paper_rewriting_output --markdown --write\npython src/scripts/reviewer_audit_check.py paper_rewriting_output --markdown --write\npython src/scripts/integrity_audit.py paper_rewriting_output --markdown --write\n```\n\n检查 LaTeX 与 Word：\n\n```powershell\npython src/scripts/latex_guard.py paper_rewriting_output/final_paper/main.tex --markdown\npython src/scripts/word_guard.py paper_rewriting_output/final_paper/paper.docx --markdown\n```\n\n检查本地参考索引与引用候选覆盖：\n\n```powershell\npython src/scripts/reference_inventory.py . --output-dir paper_rewriting_output --mode local_first\npython src/scripts/citation_bank_check.py paper_rewriting_output/citation_support_bank.md --target-count 20 --markdown\n```\n\n运行项目测试：\n\n```powershell\npython -m pytest tests -q\n```\n\n## 更新 PaperSpine\n\n> ⚠️ **从 3.x 升级到 4.0 请手动重装，自更新不适用。** 4.0 把原来的 12 个子技能收敛成单一 `paper-spine` orchestrator，3.x 的更新器会把新包判为「缺 11 个 skill」而中止。**跑一次安装脚本，务必带 `--clean-legacy`**（否则旧的 worker skill 会残留，cc switch 里会新旧混杂）：\n>\n> - Windows：`powershell -File install.ps1 -CleanLegacy`\n> - macOS/Linux：`bash install.sh --clean-legacy`\n>\n> 装完 `--check-only` 会显示 `already latest: 4.0.0`，之后自更新恢复正常。4.0 起的更新器已前向容错，不会再因文档改名等原因中止。\n\n第一次安装之后，如果想检查或更新本地安装，可以在宿主里让 `paper-spine` 走 update 路由（`/paperspine update`），它会运行：\n\n```powershell\npython src/scripts/paperspine_update.py --yes\n```\n\n它会把 `~/.paperspine/install_state.json` 中记录的版本和 GitHub `main` 上的 `dist/paperspine_version.json` 进行比较。已是最新版会直接提示；发现新版本时会下载 GitHub 压缩包、校验 PaperSpine 目录结构，然后同步更新四个宿主的 `paper-spine` skill，并保留 `~/.paperspine/config.json`。只想检查而不修改本地安装：\n\n```powershell\npython src/scripts/paperspine_update.py --check-only\n```\n\n**仍报 \"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 / 安装脚本）只告警不中止，此问题不再复发。\n\n## PaperSpine 试图避免的问题\n\n- 只改句子，不改论文逻辑或贡献。\n- 没确认贡献和 motivation 就开始写。\n- Results 只堆指标，却不验证任何一条贡献承诺。\n- 在没做面向审稿人审计的情况下声称「可投稿」。\n- 添加没有证据支撑的 claim。\n- 只输出 `main.tex`，但不解释为什么这样设计文章，也不产出 Word。\n- 用户要求翻译包时，只翻译一部分中间产物。\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n\n## 贡献者\n\n- [Wubin2023](https://github.com/WUBING2023) — PaperSpine 发起者、V1–V4 核心贡献者与维护者，主导项目的设计、开发与持续迭代。\n- [ZHOUYUNCHEN](https://github.com/ZHOUYUNCHEN) — V4 早期协作者。\n",
  "bytes": 11523,
  "sha": "9e5e1afa7140b1ac002ddae37841cde3061731c3651de45531c5cf65a5b8e725",
  "repo_slug": "wubing2023/paperspine",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_wubing2023_paperspine_paper_spine_4d0ccc2e/readme"
}