Zotero 10 插件 · v1.0.9 · English below

Zest 记录你读了多久、真的看过哪些页，把阅读状态、评级、期刊分区、被引数、标注分布直接��在条目列表里， 并配上图谱、阅读统计和标注矩阵三个视图。

1. 从 最新 Release 下载 zest.xpi。
2. Zotero →工具 ▸ 插件→ 右上角齿轮 →Install Plugin From File…→ 选中该 .xpi。
3. 按提示重启 Zotero。

装好后，条目工具栏上会出现一个 Z 按钮（线条风格，和 Zotero 自带图标同一套），点它 →套用 Zest 推荐列布局。

这一步会把标题、简记、年份、作者、阅读、状态、评级、期刊、期刊标签、影响因子、被引数、添加日期、附件排成一行，并按添加日期倒序。 不喜欢可以立刻还原：工具 ▸ Zest ▸ 撤销上一次布局切换。你也可以自己右键列标题勾选想要的列——Zest 的列 和 Zotero 原生列一样，可以随意拖动、调宽、排序。

Zest 的列默认大多是关的（每一列都要按行算东西）。第一次套用推荐布局时，它会把自己需要的那几列 一并打开；此后再套用就只排布局，不再动你的开关——你在设置 ▸ Zest 里关掉的列不会被翻回来。

阅读——阅读总时长，底下是每页热力条（4 级台阶，颜色越深看得越久）。计时只在阅读器窗口处于活动状态时 走，无输入 120 秒自动停表，朗读时不停。

状态——不用你动手也有答���：没设置过状态的条目，Zest 按阅读记录自动判定——有 PDF 但从没打开过是 未读，读过（本机记录 ≥ 30 秒，或 Zotero 自己记下的「最近阅读」/ 阅读位置，在别的设备上翻过也算）是 在读，页数与时长都达标（默认 90% 页 + 5 分钟）是已读。自动判定画成空心圈、灰字，手动设置的 是实心点；手动永远优先。要改：点圆点弹出菜单，直接选（选中多行时对整批生效）；也可以在条目右键 ▸ Zest ▸ 阅读状态、或右侧 Zest 面板的状态按钮里改（阅读器标签页右侧的上下文面板里也有这一栏）。 手动值写在条目 Extra 的 Read_Status 行，与 Reading List 插件同键；「设置 ▸ 阅读记录」里还可以让达标 时顺手把在读 / 已读写进 Extra（同步到其它设备）。

评级——点第几颗星就是几分；再点当前最高那颗降一分，点第一颗清零。存 Extra。符号和颜色可改 （设置里能换成 ♥ 或任意字符）。

标签 / #标签——#标签 列把符合规则的标签显示成文字徽章。规则语法：# 表示以 # 开头的标签、 ~~X 表示不以 X 开头、/正则/ 用正则（有捕获组就只显示捕获的部分）。「标签」列把彩色与 emoji 标签 单独成列、可排序——Zotero 本身已在标题里画这些色点，所以这一列默认关，配合「隐藏标题列里的标签色点」用。

作者 / 第一作者 / 末位作者——Zotero 自带的「创建者」列只显示「第一作者 et al.」，这三列是它的扩展： 显示方式（全部 / 前 N 位 + et al. / 前 N 位 … 末位 / 仅第一 / 仅末位 / 导师）、显示几位、姓名顺序（自动按 文字系统 / 名前 / 姓前）、名的写法（全名 / 首字母 / 不显示）、分隔符（留空 = 王小明、李雷 / Ada Lovelace, Alan Turing 自动）、「等」文案（留空 = Zotero 自身语言）、省略标记、末位作者标记（标记不进排序键）都可以 自己定；把自己的名字填进「我的名字」，你自己的署名会被高亮。装过 better-authors 的，工具 ▸ Zest ▸ 导入其设置。

期刊标签 / 影响因子 / 期刊——分区徽章与影响因子；「期刊」列把期刊名 / 会议名 / 书名 / 出版者按条目 类型合成一列（Zotero 自带的「出版物」列只有期刊名，混合文库要开三列）。影响因子默认画成数字底下一��热力色块：IF 越高颜色 越深，分四档（刻度上限的 1/15、1/5、1/2、上限，上限默认 15，设置里可改；也可以换回进度条或只显示数字）。 数据来源依次是：你导入的本地数据集 → easyScholar（填了密钥才用）→ OpenAlex（免密钥）。默认不联网， 所以刚装好时这两列是空的：从 Z 按钮 ▸ 联网获取期刊数据（等同于设置里的「自动获取」）打开，或右键条目 ▸ Zest ▸ 更新期刊分区。空单元格的悬停提示会告诉你是哪种情况。查询按期刊（不是按条目）进行，只发送期刊名、 ISSN 或 DOI，结果按期刊缓存 30 天。中科院分区、北大核心等中文体系只有 easyScholar 有，需要在设置里填密钥。 英文界面使用默认字段时按 JCR → 中科院 → IF 显示，中科院标签会写成 CAS Z1 · Med. 等英文短名， 悬停可看完整英文说明；中文界面保留原始中文和原顺序。你手动设置过的 Fields 顺序始终优先。

被引数——右键条目 ▸ Zest ▸ 更新被引数（可批量、可随时取消）。数值写进 Extra 的 Citations: 12 (Crossref) [2026-08-18]，来源依次 Crossref → OpenAlex →（可选）Semantic Scholar。 别的插件写的 GSCC:、ZSCC:、openalex.cit_count: 会被读取但绝不删除。

标注——这条文献你划了多少：稀疏柱状图显示标注在全文中的分布，或按高亮颜色分段。

简记——一行备注，双击单元格就能改，存在 Extra。

Zest——为了一眼了解这篇文献：标题（有译文时译文在上、原文在下）、全部作者一行列出（按作者列 的姓名规则，自己的名字高亮、末位标记；Zotero 信息栏一行一个、超过五个就折叠）、期刊与分区徽章、被引数 （带刷新按钮）、阅读时长 + 可点击的每页热力条（点哪一段就跳到那一页）、状态 / 评级 / 简记直接编辑、 一排外部链接（DOI、PubMed——有 PMID 直达，没有就按标题搜、arXiv、Google Scholar、Semantic Scholar、 OpenAlex、Connected Papers），以及摘要：装了 zotero-pdf-translate 并翻译过的，先显示译文（多段完整 显示），原文折叠在下面；没翻译的只显示原文（默认折叠）。译文读的是翻译插件写进 Extra 的 titleTranslation / abstractTranslation，Zest 自己不翻译、不改写这两行。Zotero 在阅读器右侧的上下文面板里也会��示这一栏。

Annotation Finder——这条文献的全部标注，按标签树里选中的标签过滤，双击直接跳进阅读器里那条标注。

如果你用 #文献密码/研究方法/统计 这种层级标签，在设置 ▸ Zest ▸ 标签里打开嵌套标签树：它会挂在 Zotero 原生标签选择器的位置，把标签展开成树。点父节点 = 按该分支下的所有标签筛选（Zotero 原生标签筛选 只能对精确标签做「且」）。支持搜索、排序、折叠、整枝重命名（会提示有多少标签会被合并）、给标签配颜色和 emoji（不占 Zotero 那 9 个颜色位）。全程可用键盘：方向键移动、←/→ 折叠展开、Enter/空格选中。

默认是关的，随时可以切回 Zotero 原生标签选择器。

把当前的列组合存成一个命名视图（比如「筛文献」「写作」「投标书」），之后从列标题右键菜单一键切换， Alt+, / Alt+. 在视图间前后切换，切错了还能撤销上一次。视图写的是 Zotero 自己的列配置文件， 所以关掉插件后你的列也还在。

• 阅读数据导入导出：设置 ▸ Zest ▸ 阅读数据 → JSON / CSV，换机器直接搬。
• 整套配置导入导出：设置 ▸ Zest ▸ 配置 → 一个 JSON 文件（刻意不含任何密钥）。
• 所有密钥都是可选的：不填 easyScholar 也有 OpenAlex 的期刊指标，被引数用 Crossref 就够。只有你主动 触发（或打开自动获取）时才会联网。

• 垂直标签页（默认关）：把 Zotero 的标签页竖着排在侧边，支持分组（跨重启保留）、保存会话、搜索、拖拽 排序。若 Zotero 改动了标签页内部实现，这块会自动停用而不是崩掉。
• 阅读器：Zest 不往阅读器里加东西；背景主题与高亮颜色请用 Zotero 自带的「外观」菜单和颜色下拉。
• 分类计数（默认关）：分类名旁显示条目数，可选「本分类 / 含子分类 / 两者都显示」。
• 外观：一个主色贯穿全部界面，设置 ▸ Zest ▸ 外观里有取色器和 5 个预设，可一并套用到热力图与徽章。 默认避开蓝色——Zotero 选中行用的就是系统选区蓝。

Zest 把它算出来的东西挂在 Zotero.Zest.api 上，供 Better Notes 模板、Actions & Tags 脚本、 以及 工具 ▸ 开发者 ▸ 运行 JavaScript 调用。全部只读，任何一个都不会抛异常——取不到就返回 空值，模板不会因为某一格没数据而整个中断。传条目对象或条目 ID 都行，传附件会自动上溯到父条目。

const zest = Zotero.Zest.api;

zest.readingTime(item); // "1.5 h"      阅读列显示的那个值
zest.readingSeconds(item); // 5400         总秒数
zest.pagesRead(item); // 23           停留超过 5 秒的页数
zest.pagesTotal(item); // 31
zest.readingProgress(item); // 74           百分比
zest.firstRead(item); // "2026-03-04"
zest.lastRead(item); // "2026-08-19"
zest.readingByDay(item); // { "2026-08-19": 930, … }   每天的秒数
zest.readingByPage(item); // { 0: 120, 1: 45, … }       每页的秒数

zest.readStatus(item); // "In Progress"  状态列显示的那个值（手动或自动判定）
zest.readStatusSource(item); // "manual" | "auto" | "none"
zest.rating(item); // 4
zest.ratingStars(item); // "★★★★☆"

zest.citations(item); // 42
zest.citationInfo(item); // { count: 42, source: "Crossref", date: "2026-08-20" }

zest.journalRank(item); // "综合性期刊1区 · Q1"
zest.journalRanks(item); // [{ field, value, source }, …]  按你配置的字段顺序
zest.impactFactor(item); // 56.1
zest.journalName(item); // "Nature"

zest.annotationCount(item); // 18
zest.annotationChars(item); // 4210
zest.annotationColors(item); // [{ color: "#ffd400", count: 12 }, …]
zest.textTags(item); // [{ tag: "#Method/Cohort", text: "Method/Cohort", color }]

在 Better Notes 模板里直接插值即可：

读了 ${Zotero.Zest.api.readingTime(topItem)}，看到第 ${Zotero.Zest.api.pagesRead(topItem)} 页
评分 ${Zotero.Zest.api.ratingStars(topItem)}
${Zotero.Zest.api.journalRank(topItem)}

Zotero 10.x。不支持 Zotero 7 / 8。

npm install
npm start      # 启动隔离的开发 profile 并加载插件
npm run build  # 生成 .scaffold/build/zest.xpi

Zest records how long you read something and which pages you actually looked at, and puts read status, rating, journal rank, citation counts and annotation spread straight into the item list — with a graph, a reading-statistics window and an annotation matrix on top.

Download zest.xpi from the latest release, then Zotero → Tools ▸ Plugins → gear icon → Install Plugin From File… → restart when prompted.

A Z button appears in the item toolbar, drawn in Zotero's own line-icon style. Click it → Apply the Zest column layout: title, remark, year, authors, reading, status, rating, journal, journal tags, IF, citations, date added and attachments, sorted by date added (newest first). Don't like it? Tools ▸ Zest ▸ Undo layout change. Most Zest columns ship off, so the first apply also turns on the ones the layout needs. Every apply after that only arranges columns — a column you switch off in Settings ▸ Zest stays off.

The same button opens the graph, the reading statistics window, the annotation matrix and the settings. The graph's author mode disambiguates names: same-surname authors cluster by full given name (Wang Lei ≠ Wang Li, an ambiguous "Wang L." stays its own node), cached OpenAlex author IDs merge spelling variants, and hovering a node shows the institution when known.

• Reading — total time plus a per-page heat strip (4 steps). The clock only runs while the reader window is active, stops after 120 s without input, and keeps running during Read Aloud.
• Status — answered without your help: an item with no status set is read off the reading record — a PDF nobody has opened is New, one you have read (≥ 30 s here, or Zotero's own last-read stamp / resume position, so a page turned on another device counts) is In Progress, and enough pages plus minutes (90 % + 5 min by default) is Read. Automatic statuses are drawn as a ring with a grey label, set ones as a filled dot; a set status always wins. To set one: click the dot and pick from the menu (applies to the whole selection when the row is part of it), or use the item context menu ▸ Zest ▸ Read Status or the status button in the Zest pane (which Zotero also shows in a reader tab's context pane). Set values go to Extra as Read_Status, the key Reading List uses; Settings ▸ Reading Tracker can also write In Progress / Read into Extra when the thresholds are crossed (so they sync).
• Rating — click star k to rate; click the current top star to lower it. Stored in Extra; symbol and colour are configurable.
• Tags / #Tags — rule-matched tags as text badges (# prefix, ~~X = everything NOT starting with X, /regex/ with optional capture group). The Tags column puts the coloured and emoji tags in a sortable column of their own; Zotero already paints those swatches in the Title cell, so it ships off and pairs with "Hide tag swatches in the Title column".
• Authors / First author / Last author — Zotero's own Creator column shows "First et al." and nothing else; these three extend it: preset (all / first N + et al. / first N … last / first only / last only / advisor), how many, name order (per script / given first / family first), given names (full / initials / hidden), separator (empty = 王小明、李雷 / Ada Lovelace, Alan Turing by script), "et al." text (empty = Zotero's own), gap marker, last-author mark that never enters the sort key, and your own name highlighted. better-authors users: Tools ▸ Zest ▸ import its settings.
• Publication Tags / IF / Venue — rank badges and impact factor from your own dataset → easyScholar (only with a key) → OpenAlex (no key). The IF sits on a heat wash: darker for higher, four steps on a log-ish ladder (1/15, 1/5, 1/2 and the top of the scale, 15 by default — or switch to a bar / plain number in Settings). Offline by default, so both columns start empty: switch lookups on from Z button ▸ Look journal data up online (the same pref as auto-fetch in Settings), or use the item context menu. Hovering an empty cell tells you which case you are in. Lookups are per journal, send only the name, ISSN or DOI, and are cached for 30 days. The Chinese ranking systems exist only in easyScholar and need a key. With the shipped fields, an English UI shows JCR → CAS → IF and renders CAS labels as compact English badges such as CAS Z1 · Med., with the full wording on hover. A Chinese UI keeps the source wording and order; any Fields order you set yourself always wins. Venue merges publication title, proceedings, book title and publisher into one column by item type — Zotero's own Publication column is journal titles only.
• Citations — right-click ▸ Zest ▸ update (batchable, cancellable). Written to Extra as Citations: 12 (Crossref) [2026-08-18], sourced Crossref → OpenAlex → optional Semantic Scholar. Other plugins' records (GSCC:, ZSCC:, openalex.cit_count:) are read but never deleted.
• Annotations — where your highlights sit in the document, or one bar split by highlight colour.
• Remark — a one-line note, double-click to edit, stored in Extra.

Zest — the paper at a glance: the title (translation above the original when there is one), every author on one line (the Authors column's name rules, your own name highlighted, the last-author mark; Zotero's Info box folds after five), venue and rank badges, citations with a refresh button, reading time and a clickable per-page heat strip (click a segment, land on that page), status / rating / remark inline, one row of links out (DOI, PubMed — by PMID, else a title search —, arXiv, Google Scholar, Semantic Scholar, OpenAlex, Connected Papers), and the abstract: zotero-pdf-translate's translation first (every paragraph) with the original folded underneath, or the original alone (folded) when nothing was translated. The translations are read from the titleTranslation / abstractTranslation lines that plugin writes into Extra; Zest neither translates nor rewrites them. Zotero shows the same section in a reader tab's context pane.

Annotation Finder — every annotation of the item, filtered by whatever you selected in the tag tree; double-click jumps into the reader at that annotation.

For hierarchical tags (#Method/Statistics/Survival), turn on the nested tag tree in Settings ▸ Zest ▸ Tags. Clicking a branch filters by everything under it — Zotero's own tag filter can only AND exact names. Search, sort, collapse, rename a whole branch (with a merge warning), and colour/emoji rules beyond Zotero's nine colour slots. Fully keyboard operable. Off by default, and one click back to Zotero's own selector.

Save the current column arrangement under a name ("Screening", "Writing", "Grant"), switch from the column-header context menu, Alt+, / Alt+. to cycle, one level of undo. Views are written to Zotero's own column settings, so your columns stay put if you disable the plugin.

Reading data exports and re-imports as JSON or CSV; the whole configuration exports as one JSON file that deliberately contains no secrets. No key is required — journal ranks work from OpenAlex or your own dataset, citations from Crossref. Nothing is fetched unless you ask for it.

Vertical tab sidebar with persistent groups and saved sessions (off by default), optional collection counts, and one accent colour driving every Zest surface (picker plus five presets in Settings ▸ Zest ▸ Appearance). Zest adds nothing to the reader; backgrounds and highlight colours are Zotero 10's own (Appearance menu, colour dropdown).

Everything Zest computes is published on Zotero.Zest.api, for Better Notes templates, Actions & Tags scripts and Tools ▸ Developer ▸ Run JavaScript. It is read-only and nothing throws — a missing record answers with an empty value rather than aborting the caller's template. Pass an item or an item id; an attachment resolves to its parent.

const zest = Zotero.Zest.api;

zest.readingTime(item); // "1.5 h"      what the Reading column shows
zest.readingSeconds(item); // 5400
zest.pagesRead(item); // 23           pages that got more than 5 seconds
zest.pagesTotal(item); // 31
zest.readingProgress(item); // 74           percent
zest.firstRead(item); // "2026-03-04"
zest.lastRead(item); // "2026-08-19"
zest.readingByDay(item); // { "2026-08-19": 930, … }   seconds per day
zest.readingByPage(item); // { 0: 120, 1: 45, … }       seconds per page

zest.readStatus(item); // "In Progress"  what the Status column shows (set or automatic)
zest.readStatusSource(item); // "manual" | "auto" | "none"
zest.rating(item); // 4
zest.ratingStars(item); // "★★★★☆"

zest.citations(item); // 42
zest.citationInfo(item); // { count: 42, source: "Crossref", date: "2026-08-20" }

zest.journalRank(item); // "综合性期刊1区 · Q1"
zest.journalRanks(item); // [{ field, value, source }, …]  in your configured order
zest.impactFactor(item); // 56.1
zest.journalName(item); // "Nature"

zest.annotationCount(item); // 18
zest.annotationChars(item); // 4210
zest.annotationColors(item); // [{ color: "#ffd400", count: 12 }, …]
zest.textTags(item); // [{ tag: "#Method/Cohort", text: "Method/Cohort", color }]

Zotero 10.x. Zotero 7 and 8 are not supported.

npm install
npm start      # isolated dev profile with the plugin loaded
npm run build  # .scaffold/build/zest.xpi

Copyright © 2026 the Zest authors.

Zest is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details: LICENSE · https://www.gnu.org/licenses/agpl-3.0.html

本项目为自由软件，依据 GNU Affero 通用公共许可证（AGPL）第 3 版或任何更新版本发布，不附带任何担保。