论文工作流引擎 gqallen931/paper-gogo-plugin

dsh-paper-gogo-plugin

把 Paper-gogo（审稿人倒推、证据优先的学术论文工作流）开发为 DeepSeek Harness 插件：工作流的 18 个 Phase、7 道质量门禁、四态证据标签与命令系统，全部变成模型可直接调用的原生工具。

插件是自包含的 —— 它自带完整的 Paper-gogo 工作流正文与 57 个技能，安装即可使用，不需要另外安装 Paper-gogo 包。

- 纯 ESM，运行时零依赖，无需构建步骤
- 针对本机安装的 DSH 版本校验通过（见 兼容性）
- 97 项自动检查全部通过：67 项单元/行为 + 19 项真实 ToolRuntime 端到端 + 11 项自包含

1. 它解决什么问题

Paper-gogo 原本是一份技能包（Markdown），要单独安装才能用，而且门禁与证据状态只存在于自然语言里——模型可以口头说「门禁通过了」，却没有任何东西能拦住它。

这个插件把它变成可执行的能力，并且把内容一起打包：

| 原来的问题 | 插件之后 |
| 还要单独装一份 Paper-gogo 包，版本容易错配 | 插件自带工作流与技能，dsh plugin add 一步到位 |
| 工作流是 45 KB 的文档，模型要么全读要么不读 | paper_manifest 按需返回结构化清单，单 Phase 细节一次到位 |
| 门禁 G0-G6 只是约定 | paper_gate 归一化门禁输入、拒绝在 FAIL 时推进 |
| 四态证据标签容易被忽略 | paper_evidence 统计、阻断 MISSING、把未标注项标为 UNLABELED 而不是默认通过 |
| 命令系统要人工对照 | paper_route 把中文/英文意图映射到命令，并给出该命令的精确执行要求 |
| 「每 Phase 必须写工作记录」靠自觉 | paper_phase_log 强制写出 Phase{N}_{name}.md |

2. 自带内容

插件在 workflow/ 目录内自带全部内容，共 57 个技能（完整清单见 workflow/SKILLS_INDEX.md，由脚本生成，不会与实际内容脱节）：

| 位置 | 内容 | 技能数 |
| workflow/ | SKILL.md、paper-workflow-v6.md（18 Phase 正文）、paper-workflow-v5.md、references/（命令系统、执行路由、审稿检查表） | — |
| workflow/skills/nature-skills/ | 检索、阅读、写作、润色、引用、数据、图表、PPT、审稿回复 | 9 |
| workflow/skills/code-understanding/ | 代码理解、差异分析、故障诊断 | 9 |
| workflow/skills/architecture-engineering/ | 领域建模、模块设计、TDD | 8 |
| workflow/skills/world-model-method/ | 复杂方案比较与审查 | 1 |
| workflow/skills/paper-framework-figure-studio-pro/ | 严格逐回合 S0-S7 论文框架图 | 1 |
| workflow/skills/karpathy-guidelines/ | 编码护栏 | 1 |
| workflow/skills/python-expert/ | Python 实验实现 | 1 |
| workflow/code_assets/ | 可复用实验与项目模板 | — |
| workflow/extras/ | 附加第三方合集：academic-research-skills(4)、claude-scholar(19)、paper-craft-skills(3)、scipilot-figure-skill(1) | 27 |

许可证注意：workflow/extras/academic-research-skills/ 是 CC BY-NC 4.0（禁止商业使用），与插件本身的 MIT 不同。详见 workflow/extras/THIRD_PARTY_NOTICES.extras.md。

为控制体积剥离的内容：所有内置副本中的图片/PDF 等媒体资产（原 37 MB）已移除；依赖内置图片的技能（如 paper-comic、paper-deck）保真度会下降，全部指令、参考与脚本均保留。

3. 提供的工具

| 工具 | 作用 |
| paper_manifest | 返回 4 个阶段、18 个 Phase、7 道门禁 G0-G6、四态证据词表、执行标记与指令优先级。传 phase 得单个 Phase 的完整定义（产出、门禁、回退、阶段记录路径、子阶段优先级表） |
| paper_doc | 读取自带文档（SKILL.md、工作流、命令系统、执行路由、检查表、SKILLS_INDEX.md、许可证等），支持 outline 先看标题、section 只取匹配章节 |
| paper_gate | 评估门禁并判定能否推进。接受宽松输入（布尔 / "pass" / {result} / 中文），未提供的门禁报告为 NOT EVALUATED 而非默认通过，任一 FAIL 即阻断 |
| paper_evidence | 审计主张的证据状态。接受 Markdown 表格或 主张 :: 状态 行，统计四态、阻断 MISSING、把无标注项标为 UNLABELED |
| paper_route | 把自由文本意图路由到正确的斜杠命令，返回该命令的精确执行要求、所属 Phase、主技能群与固定五段输出契约 |
| paper_phase_log | 写出强制的 Phase 工作记录到 docs/项目工作阶段记录/Phase{N}_{name}.md，拒绝写到工作流根之外 |
| paper_doctor | 诊断安装：解析到哪个工作流根、内容是否来自自带副本、文件是否齐全、以及修复方法 |

调用示例

paper_manifest({ phase: 7 })
→ Phase 7 实验执行：9 个子阶段与 P0/P1 优先级、产出路径、真实性门禁（stub 必须标 NON_EVALUABLE）、回溯决策、G4 归属

paper_gate({ phase: 8, gates: { G4: "FAIL" }, next: true })
→ recommendation: BLOCKED
"失败门禁必须给出修复路径，不能靠润色覆盖。"

paper_evidence({ claims: "| 主张 | 状态 |\n|---|---|\n| A | SUPPORTED |\n| B | MISSING |" })
→ verdict: BLOCKED，counts.MISSING = 1

paper_route({ intent: "帮我看看创新点够不够" })
→ /检查创新 · Phase 4 · world-model-method

paper_doc({ doc: "workflow", section: "全局规则" })
→ 只返回 7 条全局规则，而不是 45 KB 全文

paper_doctor({})
→ usable: true，内容来源：插件自带（无需外部 Paper-gogo 包）

4. 安装

方式 A：作为组合包安装进 profile（推荐）

本目录是一个合法的 DSH 组合包：package.json 声明了 dsh.bundle，cordis.patch.yml 是它贡献的配置层。

dsh plugin --profile desktop add D:\Skills\paper-gogo-plugin
dsh --profile desktop --dump-config # 应能看到 "# == dsh-paper-gogo-plugin" 层

也可以先打包再安装，避免任何构建授权：

dsh plugin --profile desktop add .\dsh-paper-gogo-plugin-0.1.0.tgz

移除：

dsh plugin --profile desktop remove dsh-paper-gogo-plugin

方式 B：用 --patch overlay 本地加载（改代码即生效）

pnpm dsh web --patch D:\Skills\paper-gogo-plugin\examples\paper-gogo.patch.yml

overlay 只贡献配置，不改变 loader 解析模块路径时使用的 profile 目录，因此这种方式最适合开发调试。

安装后自检

在会话里让模型调用一次 paper_doctor。它应当报告 usable: true、内容来源：插件自带。若为 false，按它输出的修复方法处理。

⚠️ Windows 用户：先开长路径支持

从 GitHub 克隆本插件时，默认的 Windows 路径长度限制（260 字符）会导致检出失败。内置的框架图技能里有很长的文件名，例如：

workflow/skills/paper-framework-figure-studio-pro/assets/vector-library/iclr_reference_library/paper_derived_icon_refinement/cut_svg/paper.derived.architecture.privacy.secure.aggregation.paper_derived_outline.v1.svg

该相对路径本身就有 215 字符，一旦克隆到稍深的目录就会超过上限。症状是仓库克隆成功但检出失败，报 Filename too long，并且插件目录里缺少文件。

三种解决办法，任选其一：

1) 单次克隆时开启（最快）
git -c core.longpaths=true clone https://github.com/gqallen931/paper-gogo-plugin.git

2) 永久为本机 git 开启
git config --global core.longpaths true

3) 系统级开启（需管理员 PowerShell，一次即可，随后所有程序都受益） New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name LongPathsEnabled -Value 1 -PropertyType DWORD -Force

说明：core.longpaths 是本地配置，在克隆过程中尚未生效，因此 git config --global core.longpaths true 必须在克隆之前执行；否则请用第 1 种的一次性写法。安装本插件（dsh plugin add）走的是 pnpm 链接或本地目录，不经 git clone，不受此影响。

同样的限制也适用于 Paper-gogo 包中 paper-framework-figure-studio-pro/assets/ 下的全部资源。

5. 配置

插件开箱即用，无需任何配置。以下项仅在需要覆盖默认行为时才设置，写在 profile 的 cordis.patch.yml 中：

- id: paper-gogo
name: dsh-paper-gogo-plugin
config:
preferBundled: true # 默认 true：使用插件自带的工作流副本 root: null # 仅当 preferBundled 为 false 时使用
searchRoots: []
journalDir: docs/项目工作阶段记录 # 阶段记录目录

| 配置项 | 默认值 | 说明 |
| preferBundled | true | 使用插件自带的内容；设为 false 则优先使用外部 Paper-gogo 包 |
| root | null | 外部工作流包的绝对路径（仅 preferBundled: false 时生效） |
| searchRoots | [] | 外部包的兜底候选路径 |
| journalDir | docs/项目工作阶段记录 | paper_phase_log 的写入目录 |

工作流根如何解析

preferBundled 为 true（默认）时，直接用插件自带的 workflow/。

设为 false 时按以下顺序：配置 root → 环境变量 DSH_PAPER_GOGO_ROOT → 从会话工作目录向上搜索 → searchRoots。

一个目录被认定为工作流根，必须同时存在 SKILL.md、paper-workflow-v6.md 与 references/。

6. 项目结构

paper-gogo-plugin/
├── package.json # 组合包 manifest（dsh.bundle）+ devDependencies ├── cordis.patch.yml # 安装为组合包时贡献的配置层 ├── examples/ │ └── paper-gogo.patch.yml # 本地 --patch overlay ├── src/ │ ├── plugin.js # 插件入口：apply() 注册 7 个工具 │ ├── data/ │ │ ├── phases.js # 18 Phase / 4 阶段 / 7 门禁 / 证据词表 / 执行标记 │ │ └── commands.js # 命令目录 + 意图关键词 │ └── lib/ │ ├── root.js # 工作流根解析（自带优先）与巡检 │ ├── routing.js # 意图 → 命令 → Phase → 技能 路由 │ ├── gates.js # 门禁归一化/评估、证据审计、Phase 排序 │ └── render.js # 规范值 → Markdown 渲染器 ├── workflow/ # 自带的工作流与技能（57 个技能） │ ├── SKILL.md # 工作流入口 │ ├── paper-workflow-v6.md # 18 Phase 正文 │ ├── references/ # 命令系统、执行路由、审稿检查表 │ ├── skills/ # 7 个技能组 │ ├── extras/ # 附加第三方合集（许可证不同） │ └── SKILLS_INDEX.md # 自动生成的技能清单 ├── scripts/ │ └── build-skills-index.mjs # 重新生成 SKILLS_INDEX.md └── test/ ├── run-tests.mjs # 67 项单元与行为测试 ├── verify-against-dsh-tools.mjs # 19 项真实 ToolRuntime 端到端验证 └── check-bundle.mjs # 11 项自包含检查

模块契约

- 规范值（canonical value） 是纯 JSON，传给 output.schema 校验；渲染器（render） 是纯函数，把规范值转成模型可见的 Markdown 文本块。两者分离，UI 卡片与程序化调用都能复用规范值。
- src/lib/ 除 root.js 的读取函数外全部是无副作用纯函数，因此可以直接单元测试。

7. 开发与测试

cd D:\Skills\paper-gogo-plugin
pnpm install # 只装 devDependencies（cordis + dsh-tools + yaml）
npm test # 67 项单元与行为测试
npm run verify # 19 项真实 ToolRuntime 端到端验证
npm run check:bundle # 11 项自包含检查（模拟无外部包的机器）
npm run build:index # 重新生成 workflow/SKILLS_INDEX.md

verify 会实例化真实的 Cordis Context 与真实的 ToolRuntime，把插件加载进去，然后通过真实注册表流水线派发调用，覆盖：参数校验 → execute() → 规范值校验 → render() → 内容块，以及 UNKNOWN_TOOL、参数类型错误、缺必填参数、枚举非法、业务校验失败等错误路径。

check:bundle 会把工作目录切到一个空临时目录、清空所有环境变量，验证插件仍然解析到自带内容并且每个工具都返回真实结果——这就是「无需外部 Paper-gogo 包」的证据。

已验证的 DSH 行为（写代码时的坑）

这几条是实测出来的，不是文档写的：

1. schema 不支持数组形式的 type。 写 { type: ['integer', 'null'] } 会让注册表把该 schema 视为不支持，规范值被拒为 "value" must be a lossless JSON value。可空类型必须用 oneOf: [spec, { type: 'null' }]。
2. 显式对象节点必须声明 additionalProperties。 省略会让意图变得含糊，DSH 要求显式 true | false。
3. SKILL.md 的 description 常用 YAML 块标量（>-）。 解析 frontmatter 时必须处理续行，否则会得到 >- 这样的字面值。

三条都已固化为测试，防止回归。

8. 兼容性

| 项 | 值 |
| 目标 DSH | 0.2.0-rc.2（本机 dsh --version）；同时兼容 0.1.0-rc.5 起的所有 0.1.x / 0.2.x 发布 |
| @deepseek-ai/dsh-tools peer | >=0.0.1-rc.1 <0.1.0 \|\| >=0.1.0-rc.1 <0.2.0-0 \|\| >=0.1.1-rc.1 <0.2.0-0 \|\| >=0.2.0-rc.1 <0.3.0-0 |
| @deepseek-ai/cordis peer | ^4.0.1 |
| Node | ≥ 20（宿主内置 24.21.0） |
| 运行时依赖 | 无（自带内容 + 纯 ESM） |
| 插件体积 | 约 29.4 MB（含 57 个技能与工作流正文；已剥离 37 MB 媒体资产） |
| 插件形态 | 函数式 apply(ctx, config)，inject = ['tools'] |

插件只使用 ctx.tools.register(definition) 一个 API，不导入任何 @deepseek-ai/ 包，因此宿主升级时通常无需改动。devDependencies 仅用于类型与测试校验。

⚠️ 为什么 peer 范围写成这样（装不上时先看这里）

DSH 会在安装后校验插件的 peer 声明。写死一个精确版本会让每一次 harness 升级都变成安装失败：

// ❌ 只在 0.1.7-alpha.2 上通过；harness 升到 0.2.0-rc.2 后安装被拒 "@deepseek-ai/dsh-tools": "0.1.7-alpha.2"

// ✅ 显式列出预发布分支，覆盖 0.1.x 与 0.2.x
"@deepseek-ai/dsh-tools": ">=0.0.1-rc.1 <0.1.0 || >=0.1.0-rc.1 <0.2.0-0 || >=0.1.1-rc.1 <0.2.0-0 || >=0.2.0-rc.1 <0.3.0-0"

根因是 node-semver 的预发布规则：只有当范围内某个比较符与该版本的 major.minor.patch 元组完全一致、且自身带预发布标签时，预发布版本才会被放行。所以看起来「很宽」的 >=0.0.1-rc.1 <0.2.0 实际匹配不到 0.2.0-rc.2——0.2.0 这个元组上没有带预发布标签的比较符，它被静默排除。

用 semver 实测上面的范围：

| harness 版本 | 是否满足 |
| 0.1.0-rc.5 | ✅ |
| 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.0 | ✅ |
| 0.3.0-rc.1 | ❌（尚未支持，需显式加分支） |

安装时若看到 installation rejected: ... incompatible with dsh <version>，先确认插件版本 ≥ 0.1.1；若仍是旧版说明拿到的是缓存，重装即可。

临时绕过（不推荐）：dsh plugin allow-version 可对某个确切版本授予豁免。但正确做法是升级插件，而不是长期豁免版本兼容性检查。

9. 许可证

插件代码本身为 MIT。

自带内容沿用各自上游许可证：Paper-gogo 工作流与其 7 个技能组（其中 world-model-method 与 karpathy-guidelines 为 MIT，其余待核实，见 workflow/THIRD_PARTY_NOTICES.md）；workflow/extras/ 下的 4 个附加合集许可证各不相同，其中 academic-research-skills 为 CC BY-NC 4.0，禁止商业使用，详见 workflow/extras/THIRD_PARTY_NOTICES.extras.md。