paper-glossary

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paper Glossary

论文术语表

Build shared glossary notes from

*_source_manifest.json

--source-manifest

is always required;

--raw-sections

only overrides its

raw_sections_path

with an explicit

*_raw_sections.jsonl

. This skill never runs or modifies a paper-reading workflow; the manifest and raw-sections file are its only paper-content boundary. See

references/file-contract.md

for JSON and CLI contracts.

从

*_source_manifest.json

构建共享术语表笔记。

--source-manifest

为必填参数；

--raw-sections

仅用于通过指定的

*_raw_sections.jsonl

覆盖清单中的

raw_sections_path

。该工具不会运行或修改论文阅读工作流；清单和原始章节文件是其仅有的论文内容边界。有关JSON和CLI协议，请参阅

references/file-contract.md

。

Preview And Wait (Default)

预览并等待（默认模式）

Show saved configuration on first use per person/device. If absent, ask for a term directory inside an Obsidian vault and configure it; reuse valid configuration later. Setup may create
~/.paper-glossary/config.json
.
Require an explicit article Markdown path when article links are requested. Validate it and the configured term directory are in the same Obsidian vault; never infer an article path.
Run deterministic proposal from the effective body.
Perform exactly one grounded host semantic review, bounded by
```
shortlist_limit
```
. It may only drop or reorder candidates and must preserve each retained proposal candidate's exact
term
string.
Record the reviewed shortlist with
```
plan_glossary.py --review-proposal PROPOSAL --reviewed-terms NAMES
```
; this validates the saved proposal against the current paper source and preserves each full candidate, ordered
```
surface_forms
```
, and provenance. If review produces an empty reviewed shortlist, report
```
no_candidates
```
and stop without presenting a selector.
Present every retained term from that reviewed artifact as a numbered Markdown list. This is the terminal, Codex, and Claude Code interaction. Show the resolved term directory, the article Markdown path (or that none was requested), and that selection authorizes glossary writes/enrichment plus first-safe-occurrence article links when an article was supplied.
State: No glossary notes or article Markdown have been written before selection. End the response and wait. Do not triage, inventory, generate, link, or lint during preview.

A broad request, manifest, raw sections path, or article path is not selection approval. A host-native selector is allowed only when it displays the complete same list in one interaction.

首次使用时显示已保存的配置（按用户/设备区分）。若配置不存在，则询问Obsidian库内的术语目录并完成配置；后续将复用有效配置。设置过程可能会创建
~/.paper-glossary/config.json
。
当需要生成文章链接时，要求明确提供文章Markdown路径。验证该路径与已配置的术语目录是否位于同一Obsidian库中；绝不自动推断文章路径。
基于有效内容运行确定性候选生成。
执行严格的语义审核，审核范围受
```
shortlist_limit
```
限制。审核仅可删除候选术语或调整其顺序，且必须保留每个留存候选术语的精确
term
字符串。
记录经过审核的候选列表，使用命令
```
plan_glossary.py --review-proposal PROPOSAL --reviewed-terms NAMES
```
；该命令会验证已保存的候选结果与当前论文源是否匹配，并保留每个候选的完整信息、有序的
```
surface_forms
```
及来源信息。若审核后候选列表为空，则返回
```
no_candidates
```
并终止流程，不展示选择器。
将审核后的所有留存术语以编号Markdown列表形式展示。这是终端、Codex及Claude Code的交互环节。同时显示已解析的术语目录、文章Markdown路径（若未请求则说明），以及选择操作将授权的内容：术语表写入/增强，若提供了文章则还包括在文章首次合适位置添加链接。
声明：在选择操作前，未写入任何术语表笔记或修改文章Markdown。结束响应并等待用户选择。预览阶段不进行分类、盘点、生成、链接或检查操作。

宽泛的请求、清单、原始章节路径或文章路径均不视为选择授权。仅当原生选择器能一次性展示完整的相同列表时，才可使用原生选择器。

After Selection

选择后流程

Accept only numbers, exact term names, or

全部写入

from the immediately preceding numbered list. Resolve them to the exact displayed

term

strings before invoking a script;

全部写入

applies only to that list. Invalid selections receive the valid range and another wait. Triage requires both

--reviewed-shortlist REVIEW

and the resolved exact names in

--terms

; never use

--terms

alone or add alias syntax.

Pass the current

--source-manifest

, optional

--raw-sections

, and saved

--reviewed-shortlist

to inventory, writer, and linker. Inventory consumes the saved

--triage

artifact as its selected-term input; writer and linker must also receive that same saved

--triage

. They require exact ordered

term

and

surface_forms

equality with this independent authorization before any glossary or article write.

Triage the selection; its selection identity binds each exact selected name and ordered paper-grounded forms.
Run library inventory from that triage artifact; it recomputes the complete proposal/review/selection provenance chain and fails closed on mismatched paper, source, shortlist, or forms.
Then generate one action-aware batch.
Run one writer invocation against the configured glossary directory; it revalidates the same provenance chain and requires its ordered inventory results to match the authorized triage exactly, then performs whole-batch preflight followed by the create/enrich/reuse commit. The writer resolves device-local configuration (or an explicit
```
--config-path
```
for that device) and does not accept a standalone write destination. With
```
--article
```
, its backlink is derived from the resolved article Markdown stem. Without an article, the glossary-only backlink comes from the validated manifest
paper_id
. The successful artifact preserves
```
triage_sha256
```
, provenance, article context, ordered mappings, and their deterministic
```
mappings_sha256
```
; the mapping digest binds the triage identity.
Link each successful writer result at its first safe occurrence only if an article Markdown was supplied/requested. The linker authenticates the writer provenance, context, digest, note paths, stems, and forms against the same current source/review, and rejects an artifact with no bound article path. For a glossary-only request, skip
link_glossary_terms.py
.
Lint writer-returned changed glossary note files whose action
is
created
,
enriched
, or
updated
in one
lint_glossary.py
invocation with repeated
--input PATH
arguments. Do not pass article Markdown to
lint_glossary.py
.
Report observable wall-clock timing and statuses. Time host-only phases separately. Each CLI emits top-level
elapsed_ms
for its own complete invocation. The single writer invocation includes whole-batch preflight and commit. Do not report separate preflight and commit timings.

new

entries are created;

existing_thin

entries receive only missing structured fields and a missing occurrence;

existing_complete

entries may receive only a missing occurrence. Do not overwrite existing note content. See

references/file-contract.md

for

existing_thin

, entry operations, writer

forms

, and link statuses.

仅接受紧接在前的编号列表中的数字、精确术语名称或
全部写入
指令。在调用脚本前，需将其解析为展示的精确

term

字符串；

全部写入

仅适用于当前展示的列表。无效选择将返回有效范围并再次等待。分类操作需同时传入

--reviewed-shortlist REVIEW

和解析后的精确名称（通过

--terms

参数）；绝不单独使用

--terms

或添加别名语法。

将当前的

--source-manifest

、可选的

--raw-sections

及已保存的

--reviewed-shortlist

传入盘点、写入和链接工具。盘点工具以已保存的

--triage

产物作为选中术语的输入；写入和链接工具也必须接收同一已保存的

--triage

产物。在执行任何术语表或文章写入操作前，需确保

term

和

surface_forms

的顺序与授权内容完全匹配。

对选中内容进行分类；选中的标识将绑定每个精确选中的名称及有序的论文关联形式。
基于分类产物运行库盘点；该操作会重新计算完整的候选生成/审核/选择来源链，若论文、源、候选列表或形式不匹配则终止流程。
随后生成一个感知操作的批次。
针对已配置的术语表目录执行一次写入调用；该操作会重新验证同一来源链，要求有序的盘点结果与授权的分类内容完全匹配，然后执行全批次预检查，再进行创建/增强/复用提交。写入工具会解析设备本地配置（或通过
```
--config-path
```
指定该设备的配置路径），不接受单独的写入目标。若传入
```
--article
```
参数，其反向链接将从解析后的文章Markdown主干生成。若未提供文章，则仅术语表的反向链接来自已验证的清单
paper_id
。成功生成的产物将保留
```
triage_sha256
```
、来源信息、文章上下文、有序映射及其确定性的
```
mappings_sha256
```
；映射摘要将绑定分类标识。
仅当提供/请求了文章Markdown时，才在每个成功写入的术语首次合适位置添加链接。链接工具会验证写入产物的来源、上下文、摘要、笔记路径、主干及形式是否与当前的源/审核内容一致，若产物未绑定文章路径则拒绝执行。对于仅生成术语表的请求，跳过
link_glossary_terms.py
。
对写入工具返回的、
action
为
created
、
enriched
或
updated
的术语表笔记文件进行检查，通过一次
```
lint_glossary.py
```
调用并传入多个
```
--input PATH
```
参数完成。请勿将文章Markdown传入
lint_glossary.py
。
报告可观测的耗时及状态。单独统计仅由主机执行阶段的耗时。每个CLI命令都会在顶层输出
elapsed_ms
，表示其完整调用的耗时。单次写入调用包含全批次预检查和提交操作。请勿单独报告预检查和提交的耗时。

new

条目将被创建；

existing_thin

条目仅补充缺失的结构化字段和出现记录；

existing_complete

条目仅补充缺失的出现记录。请勿覆盖现有笔记内容。有关

existing_thin

、条目操作、写入工具的

forms

及链接状态，请参阅

references/file-contract.md

。

Grounding

关联规则

```
anchor_only
```
: concise paper use plus a thin general explanation.
```
needs_explanation
```
: labeled background explanation with confidence and paper occurrence.
Exclude reference-only occurrences as evidence. Keep paper facts in
```
occurrence
```
and outside knowledge labeled.

```
anchor_only
```
：简洁的论文用法说明加简短通用解释。
```
needs_explanation
```
：标注背景解释，包含可信度及论文中的出现位置。
排除仅作为参考文献的出现记录。将论文事实保留在
```
occurrence
```
中，外部知识需标注来源。