222 lines
13 KiB
Markdown
222 lines
13 KiB
Markdown
---
|
|
name: paper
|
|
description: 撰写学术期刊投稿论文(中文核心 / 英文 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**`/列表/表格/`` 居中插图 + 图题自增
|
|
- `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`,后续才能读:
|
|
|
|
```bash
|
|
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 条要点(论点 / 图表 / 引文)
|
|
- 提问:"本段可以了吗?下一段要点改/加/删什么?"
|
|
7. ⛔ **BLOCKING:等用户明确反馈**("OK"/"下一段"/"继续")才动笔。沉默/"看着不错"不算确认;**篇幅或 redlines 异常**时必须主动追问
|
|
8. 用户确认**实质改动**(改机理解释 / 换核心数据图 / 调结论 / 增删引文 / 改创新点表述)后,追加一行到 `<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 的引文不得带进最终稿(核实 / 删论断 / 用户拍板,三选一)。
|
|
|
|
## 阶段六:验收 + 渲染 + 投稿件
|
|
|
|
```bash
|
|
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 / 声明)
|