# Paper To Vault

> 把 Zotero 中提取的论文 .text 文件总结为中文摘要并/或整理成结构化 Markdown，保存到 Obsidian survey-vault 的 pages/ 目录。处理 CR 换行符、frontmatter 规范、表格碎片化、参考文献筛选等已知坑。Use when the user provides a `/Users/zhaoliang/Zotero/storage/<ID>/<n>.text` path along with requests like "总结这篇文章"、"写一千字摘要"、"中文摘要"、"整理成 Markdown"、"全文转 Markdown"、"convert this paper to markdown"、"summarize this paper".

- Skill: `goodluckz/paper-to-vault` (Agent Skill)
- Install (CLI): `npx skillmds@latest add goodluckz/paper-to-vault`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goodluckz/paper-to-vault/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: goodluckz (https://skillmd.com/u/goodluckz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goodluckz/paper-to-vault

---


# Paper → Survey Vault

把 Zotero 提取的论文 `.text` 文件转换为 Obsidian 知识库笔记。支持两种产出模式：

| 模式 | 用途 | 文件名后缀 |
|------|------|------------|
| **快速摘要** (~1000 字) | 知识库索引、回顾入口 | `<Title>.md` |
| **完整 Markdown** | 深入阅读、引用骨架 | `<Title> - Full.md` |

两种模式互补，可以独立调用或顺序进行（先摘要，再追加全文）。

## 触发条件

用户提供 `/Users/zhaoliang/Zotero/storage/<ID>/<n>.text` 路径并要求：

- "总结这篇文章"、"写一千字摘要"、"中文摘要"
- "整理成 Markdown"、"全文转 Markdown"、"convert to markdown"
- "summarize this paper"、"做成 vault 笔记"

如果用户也指出目标目录（例如 `pages/`），按指示走；否则按本 skill 的默认 `pages/` 走。

## Phase 1: 读取与预处理

**已知坑 #1：CR 换行符**。Zotero 的 `.text` 经常用旧 Mac CR 换行符，`wc -l` 会显示 0 行，Read 工具会因 "very long lines" 失败。

```bash
file /Users/zhaoliang/Zotero/storage/<ID>/<n>.text
# 若结果含 "with CR line terminators":
tr '\r' '\n' < /Users/zhaoliang/Zotero/storage/<ID>/<n>.text > /tmp/zotero_lf.txt
wc -l /tmp/zotero_lf.txt
```

之后用 Read 工具按 `offset` / `limit` **分段读** `/tmp/zotero_lf.txt`，每次 ≤200 行（约 25K tokens 上限）。可以并行 Read 多段加速。

## Phase 2: 快速摘要（默认）

### 通读结构

按顺序识别：abstract、sections（编号 `^\d+\s+` 或 `^\d+\.\d+`）、tables / figures（`Table X.` / `Fig. X.`）、references（通常在末尾，`^\[\d+\]` 起头）、conclusion。

### 撰写中文摘要（~1000 字）

固定覆盖：

1. 论文基本信息：标题、作者机构、年份、venue、页数
2. 核心问题与定义（如果作者给出了定义，直接引用）
3. 主要方法 / 分类法 / 贡献（保留分类标签的精确名称，如 "MAESTRO"、"ATFAA"）
4. 关键发现或权衡（用 **加粗** 标出核心术语）
5. 结论与未来研究方向

写作风格：**段落 + 加粗子标题** 而不是大量 bullets，便于回顾时扫读。

**专有名词标注规则**：被翻译成中文的技术术语，在**首次出现时**用全角括号补上英文原文，形如 `中文术语（English Term）`。例如 "双用途困境（dual-use dilemma）"、"四层模型（Four-Layer Model）"、"涌现共谋（emergent collusion）"。

- 后续出现不重复标注
- 已是英文/缩写的不动：LLM、SOC、API、NIST、Agentic AI、框架名 ATFAA/MAESTRO/OWASP 等
- 用全角括号 `（）` 而非半角 `()` 以符合中文排版

### 询问保存方式

用 `AskUserQuestion` 一次性问保存位置 + 标签：

```
Q1: 保存到哪里？
  - pages/<Title>.md (推荐)
  - research/<Title>.md
  - 不保存，仅显示
Q2: 用哪个标签？
  - 从 CLAUDE.md 现有标签列表选一个 (machine-learning / research-note / programming / reference)
  - 新建跨学科标签 (如 ai-cybersecurity)
```

**已知坑 #2：CLAUDE.md 的标签体系是按单一学科分的**（`research-note` 仅指 NDN/ICN/SDN 网络研究）。AI × 安全、ML × 系统等交叉论文不要硬塞进现有标签——直接新建标签更合理。如果新建了，记得保存到项目 memory。

## Phase 3: 写入 Vault

### Frontmatter 规范

参考 `/Users/zhaoliang/LocalDocuments/vaults/survey-vault/CLAUDE.md`：

```yaml
---
aliases: ["<英文长标题>", "<短引用如 Lazer 2026>"]
created: YYYY/MM/DD, HH:MM:SS
modified: YYYY/MM/DD, HH:MM:SS
tags:
  - <分类标签>
title: "<英文长标题或主题>"
---
```

**已知坑 #3**：用户经常在保存后手动调整 frontmatter（改 title 为完整英文长标题、加 aliases）。如果看到 PostToolUse hook 提示文件被修改，**沿用最新版本，不要回滚**。

### 文件命名

按 CLAUDE.md "有明确主题的文件" 规则用描述性英文：

- 好：`Agentic AI Cybersecurity Survey.md`
- 差：`20260516 paper.md`（无主题信息）

### 正文骨架（快速摘要模式）

```markdown
# <Title>

**Authors:** ...
**Year / Venue:** ...
**Source PDF:** [[<PDF wiki-link>]]

> [!abstract]
> <1000 字中文摘要>

## 来源
`/Users/zhaoliang/Zotero/storage/<ID>/<n>.text`
```

## Phase 4: 完整 Markdown 整理（按需）

用户请求 "全部整理"、"全文 Markdown"、"convert full paper" 时进入此阶段。

### 询问三个关键选项

用 `AskUserQuestion` 一次性问：

```
Q1: 保存位置？
  - pages/<Title> - Full.md (推荐，与摘要文件并存)
  - research/
  - 覆盖现有摘要文件
Q2: 参考文献（通常 100-200 条）怎么处理？
  - 全部保留并格式化
  - 只保留正文中高频引用（10-20 条，推荐）
  - 完全去掉
Q3: 表格怎么处理？
  - 重建为 Markdown 表（推荐，但 PDF 提取的表常碎片化）
  - 仅保留表标题与表说明（最稳妥）
  - 仅保留表名
```

### 统计高频引用

正文中的 `[N]` 引用频次能反映核心参考：

```bash
# 假设 references 段从第 530 行开始
awk 'NR<=530' /tmp/zotero_lf.txt \
  | grep -oE '\[[0-9]+(, *[0-9]+)*\]' \
  | tr -d '[]' | tr ',' '\n' | tr -d ' ' \
  | sort | uniq -c | sort -rn | head -20
```

取频次 ≥6 的 ID 作为 selected references（具体阈值按论文调整）。

### 提取对应 References 条目

```bash
awk 'NR>=531' /tmp/zotero_lf.txt \
  | grep -E '^\[(15|23|24|27|37|41|60|61|76|85|97|115|118|122|164|165|187)\]'
```

**已知坑 #4**：有的 `[N]` 条目在前一条的同一行末尾（PDF 排版导致），grep 起点要精确，必要时用 `grep -n '<id>'` 全文反查。

### 结构化 Markdown 模板

```markdown
---
aliases: ["<长标题>", "<短引用 Full>"]
created: <ts>
modified: <ts>
tags: [<标签>]
title: "<长标题>"
---

# <Title>

**Authors:** ...
**Year / Venue:** ...
**Source PDF:** [[<PDF>]]
**Short summary:** [[<短摘要笔记>]]

> [!abstract]
> <原文 abstract 翻译>

---

## 1. Introduction
<原文 Section 1 中文整理，保留 [N] 引用编号>

---

## 2. Related Work
...

> **Table 1.** <表名> — *<表说明，仅保留标题与说明>*

---

## 3. <Section>
### 3.1 <Subsection>
**3.1.1 <Subsub>.** <段落整理>

> **Fig. X.** <图说明>

---

## ... 各章节 ...

### Key Takeaways from Section N
- ...

---

## Selected References

> 仅保留正文中高频引用（按频次排序）。完整 ~N 条参考请见原 PDF。

- **[118]** <Author>. <Year>. *<Title>*. <URL>（引用 15×）
- ...

---

## 来源

- **原始 PDF**：`/Users/zhaoliang/Zotero/storage/<ID>/<n>.text`
- **DOI**: ...
```

### 章节排版细节

- 一级章节用 `## N. Title`
- 子节用 `### N.M Title`
- 子子节用加粗段首 `**N.M.K Topic.**`（沿用论文风格）
- Figure / Table 用 blockquote `> **Fig. X.** ...`
- 对话片段（如红蓝队 Round 1/2）用 blockquote 保持原话
- Key Takeaways 用 bullet list

## Phase 5: 关联与记忆

### 两个文件互链

- 短摘要的 frontmatter 加：`Full version: [[<Title> - Full]]`
- 全文的 frontmatter 加：`Short summary: [[<Title>]]`

### 新标签 / 新约定 → 项目 memory

如果引入了 CLAUDE.md 之外的新标签（如 `ai-cybersecurity`），在
`/Users/zhaoliang/.claude/projects/-Users-zhaoliang-LocalDocuments-vaults-survey-vault/memory/`
写一条 `project` 类型 memory，并在 `MEMORY.md` 索引中加一行。

## 已知坑速查

| # | 问题 | 解决 |
|---|------|------|
| 1 | `.text` 是 CR 换行，Read 失败 | `tr '\r' '\n'` 转换到 `/tmp/zotero_lf.txt` |
| 2 | 跨学科论文不匹配现有标签 | 询问用户后新建标签，保存到 memory |
| 3 | 用户手动调过 frontmatter | PostToolUse hook 提示后沿用最新版，不回滚 |
| 4 | References 条目跨行（`[N]` 在前条尾部） | 用 `grep -n` 全文反查精确行 |
| 5 | PDF 表格被 OCR 切碎 | 默认仅保留标题 + 说明，不要强行重建 |
| 6 | 文件 >25K tokens | 分段 Read（每次 ≤200 行）；可以并行多个 Read |
| 7 | 大段写入会触发 vault formatter (PostToolUse hook) | 正常，写完看新版即可 |

## 触发示例

- 「`/Users/zhaoliang/Zotero/storage/MEGP42RJ/1.text` 总结这篇文章，写一千字中文摘要」→ Phase 1-3
- 「再把刚才那篇全部整理成 Markdown」→ Phase 4-5
- 「这篇论文做成 vault 笔记 + 全文整理」→ Phase 1-5 顺序执行

## 不要做的事

- 不要给空文件或仅含 frontmatter 的笔记加 `Related: [[X]]` 链接
- 不要修改用户调整过的 `aliases` / `title`
- 不要把 PDF 提取错乱的表格"猜着重建"——宁可保留标题与说明
- 不要为了凑字数把摘要写到 2000 字，1000 字左右就是最佳
- 不要默认保存——总是先问保存位置