zcdsj
/
zcbot
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zcbot/skills/paper/SKILL.md

13 KiB
Raw Blame History

name description
paper 撰写学术期刊投稿论文(中文核心 / 英文 SCI;原创研究 original / 综述 review / 快报 letter)。把实验数据、前期报告整理成可投稿的论文 .docx,含 IMRaD 骨架、引文三角核验、投稿件。当用户要写论文、投稿稿、manuscript、写 Introduction/Methods/Results/Discussion、写综述、改投稿稿时使用。

学术论文写作

把实验数据 / 前期素材变成可投稿的论文 .docx。先定类型与语言 → 八条对齐 → 建文献矩阵 → 先定图表 → 逐章一段一卡 → 引文三角核验 → 验收渲染 + 投稿件 —— 不要一口气出全文。

进度展示建议:用 task_progress 标记「摄取素材 / 类型与八条对齐 / 文献矩阵 / 图表定稿 / 逐章起草 / 引文核验 / 验收渲染」等关键阶段;章节内每段确认不必单独更新。

边界(先划清,免得和别的 skill 撞)

与谁区分 边界
vs proposal proposal 写本子/任务书(立项依据骨架);paper 写期刊投稿稿(IMRaD 骨架)。两者各自独立
vs review review 改已有稿;paper 从零起草。paper 阶段六终审调用 review 的协议,不重复造
vs research/documents 它们查文献;paper 是消费方,引文核验(阶段五)接到它们头上
vs patent/standard 写交底书→patent;写标准→standard

何时不用:只改不写→review;写本子→proposal;只查文献→research/documents;只出图→plot_pub。

资源

下面所有路径都相对 <skill_dir> —— load_skill 返回头里的 [skill=paper, dir=<绝对路径>],用这个绝对路径拼脚本/资源,不要假设 cwd。

先读(always):

  • <skill_dir>/references/paper_types.md —— 原创/综述/快报 的 IMRaD 骨架 + 篇幅预算 + 章节命名

按 spec 条件加载(一篇论文只挂一套):

  • 语言=zh → references/cite_gbt7714.md + references/redlines_zh.md
  • 语言=en → references/cite_elsevier.md + references/redlines_en.md

阶段五必读:

  • references/citation_verify.md —— 引文三角核验协议(存在性 / 三角印证 / 支撑度,接 documents/research)

模板:

  • templates/spec.md —— 八条对齐固定字段(复制到 task 级 spec 文件)
  • templates/original_article.md —— IMRaD 章节骨架(type=original)
  • templates/review_article.md —— 主题式章节骨架(type=review)

脚本(.venv/Scripts/python.exe <skill_dir>/scripts/...):

  • scripts/render_diagrams.py —— sections/*.md 的 mermaid 块 → figures/fig_<caption>.png(caption 必填+唯一)
  • scripts/render_docx.py —— md→docx,--lang {zh,en}(图题 图/Fig.),--toc(默认不出目录),自动 **bold**/列表/表格/![](png) 居中插图 + 图题自增
  • scripts/word_count.py —— --type --lang,章节篇幅 vs 预算
  • scripts/quality_check.py —— --type,结构/占位符/过度宣称/插图 + 引文交叉核对(orphan/uncited/编号连续)

阶段零:摄取素材(有实验数据 / 报告 / PDF 时才走)

用户给实验数据 XLSX / 前期报告 DOCX / 相关论文 PDF / 目标期刊 Guide URL → 先转 <task_dir>/source/<name>.md,后续才能读:

markitdown <path>/data.xlsx        -o <task_dir>/source/data.md
markitdown <path>/report.docx      -o <task_dir>/source/report.md
markitdown <path>/ref_paper.pdf    -o <task_dir>/source/ref.md
markitdown https://.../guide       -o <task_dir>/source/guide.md

转完后阶段一直接 read <task_dir>/source/*.md 拿事实,实验数据一律以用户素材为准,不得自造。

阶段一:八条对齐(写 spec)

产物:task 级 spec 文件(论文"宪法",后续每章前都要重读)。命名按 system prompt 的《task 级「宪法」文件命名约定》:

<task_dir>/<today>-<task_short_id>-<task_name>.spec.md

0. 先检测已有 spec(同 working_dir 可能已有别的 task 的 spec):

glob <task_dir>/*-<task_short_id>-*.spec.md → 按文件名字典序排,取最大者作 current
  • 已有当前 task 的 spec → 读出展示,问「沿用进阶段二 / 重定调(以 today 为前缀写新版,旧版留存)」,⛔ BLOCKING
  • 只有别的 task 的 spec → 仅作参考;继续走 1-4
  • 完全没有 → 直接走 1-4
  1. 先读 references/paper_types.md 定论文类型(original/review/letter)
  2. 复制模板 read templates/spec.md → write <task_dir>/<today>-<task_short_id>-<task_name>.spec.md
  3. 按字段填(§1 类型+语言、§2 目标期刊、§3 一句话贡献 是后续所有阶段的锚,务必和用户敲定)
  4. ⛔ BLOCKING:用户确认 spec 后才进阶段二

spec 定下「类型 + 语言」后,按 §资源 条件加载对应的 cite_.md + redlines_.md,后续都遵这一套。

阶段二:文献矩阵(立证据底座)

移植自 ARS,后端用 zcbot 自己的库。Introduction 与 Discussion 靠这份矩阵,不靠记忆。

  1. 据 spec §3/§4 的贡献与 gap,列要查的主题(英文 keyword 优先,见 research/documents 规则)

  2. 用 documents(材料类优先,中英 query 都行)/ research(要 DOI 走这个)检索,建矩阵到 <task_dir>/lit_matrix.md:

    文献(真实条目) DOI 一句话贡献 在本文用在哪(Intro/Methods/Disc)
    <author year> <doi> <gap/方法/对比> Intro 第2段

  3. ⛔ BLOCKING:矩阵给用户过目(查得够不够、方向对不对),确认后进阶段三

  4. 矩阵里的文献是阶段五核验的输入;起草引用先用 [CITE-<keyword>] 占位

阶段三:先定图表(写正文前)

paper-writer 的关键纪律 —— 先把证据骨架(图/表)定下来,再写正文,避免正文写完发现图对不上。

  1. 据 spec §6 图表清单,确认每张图/表要表达的结论与数据来源
  2. 出图:数据图走 plot_pub skill(材料论文配色/字号/矢量规范),流程/机理/装置图走 mermaid 块(caption 必填),实拍/SEM 直接 ![]()
  3. 落到 <task_dir>/figures/;mermaid 块先留在将写的章节里,阶段六统一 render_diagrams.py
  4. ⛔ BLOCKING:图表清单与初版图给用户确认后进阶段四(图错了正文白写)

阶段四:逐章起草(一段一卡)

写作顺序(不是文件顺序):Methods → Results → Introduction → Discussion → Abstract → Title。先写定事实,再写需要全局视野的部分,最后凝练摘要题名。

复制 templates/<original_article|review_article>.md 对应小节到 <task_dir>/sections/NN_xxx.md(命名见 paper_types.md)。

每章两段式:先列要点 → 用户确认 → 再起草 → 用户确认。

A. 起草前列要点(改要点比改正文便宜):

  1. 读 current spec + 加载的 redlines + 本章在 paper_types.md 的篇幅预算与要素
  2. 列 3-6 条要点骨架:本章论点 / 用哪些图表 / 引哪些矩阵里的文献,每条贴预估篇幅
  3. ⛔ BLOCKING:用户确认要点后才动正文

B. 正文起草: 4. 按要点填;引用处放 [CITE-<keyword>] 占位(阶段五再核验编号) 5. 关键章节一段一卡 —— Introduction / Methods / Results / Discussion:写一段 → 报篇幅 + 预告下一段 → 等确认 → 写下一段。短章节(Abstract/Conclusion)一节一卡 6. 报告格式(每次卡点):

  • 本段(节):章节名 / 实际篇幅 / 预算 / 与 redlines 对齐情况(可复现?只陈述?不过度宣称?)
  • 下一段(节)预告:标题 + 3-5 条要点(论点 / 图表 / 引文)
  • 提问:"本段可以了吗?下一段要点改/加/删什么?"
  1. ⛔ BLOCKING:等用户明确反馈("OK"/"下一段"/"继续")才动笔。沉默/"看着不错"不算确认;篇幅或 redlines 异常时必须主动追问
  2. 用户确认实质改动(改机理解释 / 换核心数据图 / 调结论 / 增删引文 / 改创新点表述)后,追加一行到 <task_dir>/REVISIONS.md

两段式 + 段段卡是为了拦早 —— 论文连续生成容易把错方向(尤其机理论述、过度解读)推到底。

例外:用户主动且明确说"别问,直接全做"才一次跑完,跑完必须 quality_check + citation_verify。"太慢/太碎"的抱怨不算例外。

阶段五:引文三角核验(渲染前必跑)

论文最致命的失分是编造引文 / 引而不实。逐条走 references/citation_verify.md 三层:

  1. 存在性:每条引文在 documents/research 查到真实条目,字段以库返回为准;查不到标 [未核实],不编造
  2. 三角印证:关键论断的支撑引文至少两个独立来源一致
  3. 支撑度:抓回 md_content/PDF,定位 ≤25 词锚点原文,判 support/partial/not-support;partial→改论断迁就证据,not-support→删或换
  4. 台账写 <task_dir>/CITATIONS.md;只有 verified 的进编号
  5. 按文中首次出现顺序编 [1][2]...,把占位替换掉,写 sections/<NN>_references.md

⛔ status 非 verified 的引文不得带进最终稿(核实 / 删论断 / 用户拍板,三选一)。

阶段六:验收 + 渲染 + 投稿件

python <skill_dir>/scripts/word_count.py      <task_dir>/sections/ --type original --lang en
python <skill_dir>/scripts/quality_check.py   <task_dir>/sections/ --type original
python <skill_dir>/scripts/render_diagrams.py <task_dir>/sections/          # 有 ```mermaid 块就跑
python <skill_dir>/scripts/render_docx.py     <task_dir>/sections/ --lang en -o <task_dir>/<topic>.docx
  • quality_check 的 orphan/uncited/占位符不通过 → 回头改章节或补阶段五核验,再跑
  • 终审走 review skill 的反谄媚审稿协议(EIC + 审稿人视角,pre-commit 评分防一味说好),别自己说"挺好"就交
  • 投稿件(可选,用户要才出):cover letter(说清贡献与契合度)/ Highlights / AI 使用声明 / 作者贡献(CRediT)/ 利益冲突声明 —— 按目标期刊要求

工作目录

<task_dir> = system prompt 给的绝对路径。所有产物写到 task_dir 下,不要写 cwd / skills/ / repo 根。

<task_dir>/
├── source/                                  # 摄取的素材(实验数据/报告/参考论文)
├── <today>-<task_short_id>-<task_name>.spec.md   # 阶段一定调,论文宪法
├── lit_matrix.md                            # 阶段二文献矩阵
├── figures/                                 # 阶段三图表(plot_pub 出的 png / mermaid 渲染的 png)
├── sections/                                # 阶段四逐章产物(NN_xxx.md)
├── CITATIONS.md                             # 阶段五引文核验台账
├── REVISIONS.md                             # 修订日志:每次卡点用户确认的实质改动
└── <topic>.docx                             # 最终投稿稿(按论文主题命名,不要 output.docx)

修订日志 (REVISIONS.md)

<task_dir>/REVISIONS.md 是产物迭代的紧凑 changelog。spec 是宪法(定调一次),REVISIONS 是实施日志(每次卡点累加)。

情形 记?
用户确认改 机理解释 / 核心数据图 / 结论 / 创新点表述 ✅ 必记
用户确认 增/删/换 引文 / 图表 / 章节 ✅ 必记
阶段五因支撑度不足改写论断 ✅ 必记(注明触发的引文)
章节首次起草(从 0 写出) ❌ 不记
错别字 / 标点 / 排版 ❌ 不记

格式(倒序,最新在上;文件首次创建写一次头注释):

- `<YYYY-MM-DD HH:MM>` | <文件:章节/段> | <一句话改了什么> — <为什么>

操作:edit 在头注释后插入新行;文件不存在就 write 带头注释创建。

硬规则速查(违反审稿扣分)

  • 可复现:Methods 给材料来源/纯度/配比/工艺/仪器型号/标准,不写"按常规方法"
  • 结果只陈述:机理解释留 Discussion;数据带单位 + 误差
  • 不过度宣称:"国际领先/首次/world-first/unprecedented" 等无证据夸张词禁用(quality_check 拦)
  • 引文真实:经 citation_verify 核验;不编造、不凭印象;起草用 [CITE-xx] 占位,渲染前必清空
  • 摘要自含:不出现 [n] 引文与图表号
  • 术语统一:一个概念一个词;缩写首次给全称
  • 图:用 mermaid/matplotlib 出 png,不用 ASCII 字符画(Word 必错位,quality_check 拦);图题自增不手写"图 2-2"
  • 详细规则见加载的 redlines_zh.md / redlines_en.md

反模式

  • 未 spec 就硬写正文 / 一次性出全文 / 跳过"列要点"直接写
  • 跳过文献矩阵与图表定稿,边写正文边凑图凑引文
  • 关键章节(Intro/Methods/Results/Discussion)整章一次出 —— 必须段段卡
  • 自造实验数据 / 指标(不知道就 <TODO 待用户提供>)
  • 编造引文 / 引文凭印象 / 带 [CITE-xx] 占位就渲染 / 跳过阶段五核验
  • 结果章大段解读机理 / 讨论重复结果数字 / 摘要里写 [n]
  • 不跑 quality_check 就交付 / 文件名 output.docx / 论文.docx(按主题命名)

输出

完成后给用户:

  • 文件路径
  • 各章节篇幅 vs 预算
  • 引文核验结论(verified 条数 / 待用户提供条数 / 因支撑度改写的论断)
  • <TODO> 待补项清单
  • 是否需要出投稿件(cover letter / 声明)