dsh-zotero 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.en.md +50 -38
  2. package/README.md +49 -34
  3. package/lib/client.js +454 -545
  4. package/lib/client.js.map +4 -4
  5. package/lib/config.d.ts +1 -1
  6. package/lib/config.d.ts.map +1 -1
  7. package/lib/config.js +1 -1
  8. package/lib/config.js.map +1 -1
  9. package/lib/constants.d.ts +9 -0
  10. package/lib/constants.d.ts.map +1 -1
  11. package/lib/constants.js +9 -0
  12. package/lib/constants.js.map +1 -1
  13. package/lib/contract.d.ts +7 -45
  14. package/lib/contract.d.ts.map +1 -1
  15. package/lib/contract.js +7 -97
  16. package/lib/contract.js.map +1 -1
  17. package/lib/evidence.d.ts +16 -4
  18. package/lib/evidence.d.ts.map +1 -1
  19. package/lib/evidence.js +87 -14
  20. package/lib/evidence.js.map +1 -1
  21. package/lib/http-client.d.ts.map +1 -1
  22. package/lib/http-client.js +5 -3
  23. package/lib/http-client.js.map +1 -1
  24. package/lib/presentation-meta.d.ts +4 -0
  25. package/lib/presentation-meta.d.ts.map +1 -1
  26. package/lib/presentation-meta.js +1 -0
  27. package/lib/presentation-meta.js.map +1 -1
  28. package/lib/prompt.d.ts +8 -4
  29. package/lib/prompt.d.ts.map +1 -1
  30. package/lib/prompt.js +13 -13
  31. package/lib/prompt.js.map +1 -1
  32. package/lib/provider-local.d.ts +38 -15
  33. package/lib/provider-local.d.ts.map +1 -1
  34. package/lib/provider-local.js +179 -82
  35. package/lib/provider-local.js.map +1 -1
  36. package/lib/remote.d.ts +6 -28
  37. package/lib/remote.d.ts.map +1 -1
  38. package/lib/remote.js +5 -80
  39. package/lib/remote.js.map +1 -1
  40. package/lib/tools/export.d.ts +1 -1
  41. package/lib/tools/export.js +3 -3
  42. package/lib/tools/export.js.map +1 -1
  43. package/lib/tools/retrieve.d.ts.map +1 -1
  44. package/lib/tools/retrieve.js +3 -0
  45. package/lib/tools/retrieve.js.map +1 -1
  46. package/lib/tools/search.d.ts +3 -0
  47. package/lib/tools/search.d.ts.map +1 -1
  48. package/lib/tools/search.js +5 -1
  49. package/lib/tools/search.js.map +1 -1
  50. package/lib/typert.d.ts +5 -6
  51. package/lib/typert.d.ts.map +1 -1
  52. package/lib/typert.js +6 -22
  53. package/lib/typert.js.map +1 -1
  54. package/lib/types.d.ts +10 -1
  55. package/lib/types.d.ts.map +1 -1
  56. package/package.json +28 -26
package/README.en.md CHANGED
@@ -1,19 +1,26 @@
1
- <h1 align="center">dsh-zotero</h1>
1
+ <div align="center">
2
2
 
3
+ # dsh-zotero
4
+
5
+ <img
6
+ src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=18&pause=2000&color=CC2936&center=true&vCenter=true&width=760&lines=%3E+Zotero+as+an+evidence+store+for+agents."
7
+ alt="dsh-zotero"
8
+ />
3
9
  <p align="center">
4
- <b>English</b> · <a href="README.md"><b>中文</b></a>
10
+ <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/v/dsh-zotero" alt="npm version" style="max-width:100%;"></a>
11
+ <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/dm/dsh-zotero" alt="npm downloads" style="max-width:100%;"></a>
12
+ <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/l/dsh-zotero" alt="license" style="max-width:100%;"></a>
13
+ <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
5
14
  </p>
15
+ </div>
6
16
 
7
17
  <p align="center">
8
- <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
9
- <img src="https://img.shields.io/npm/v/dsh-zotero" alt="npm version">
10
- <img src="https://img.shields.io/npm/dm/dsh-zotero" alt="npm downloads">
11
- <img src="https://img.shields.io/npm/l/dsh-zotero" alt="license">
18
+ <a href="README.md"><b>中文</b></a> · <b>English</b>
12
19
  </p>
13
20
 
14
- Let agents search, read, and cite your local [Zotero](https://www.zotero.org) library: find papers, browse notes and annotations, pull evidence by question, open the source document, generate citations.
21
+ Let agents discover sources in your [Zotero](https://www.zotero.org) library, extract the evidence relevant to a question, and always keep the link between evidence and the source document.
15
22
 
16
- Describe what you need in a session and the Agent calls the tools below as needed. The only manual command is `/zotero status`.
23
+ dsh-zotero is built for agent research workflows: from literature search and metadata/note inspection to evidence retrieval, opening the source, and citation generation, the Agent pulls what the current task needs step by step — without reading a whole paper or the whole library up front.
17
24
 
18
25
  ## Tools
19
26
 
@@ -56,6 +63,14 @@ The Agent moves down the ladder as a request deepens. A typical conversation:
56
63
  - Zotero desktop with the local API enabled: **Settings → Advanced → "Allow other applications on this computer to communicate with Zotero"**.
57
64
  - Read access is unauthenticated on `http://127.0.0.1:23119/api`. V1 has no path that modifies library data (items, notes, tags, collections).
58
65
  - Zotero ≥ 7 speaking local API version 3. Upgrade if the status command reports a version mismatch.
66
+ - Node.js ≥ 22.19 (or 24+); the host dsh runtime is the rc.7 line. Runtime peer dependencies are declared in `package.json` `peerDependencies` (`@deepseek-ai/cordis` ≥ 4, `dsh-tools`, `dsh-llm`, `dsh-settings`, `dsh-user-questions`, `dsh-typert-protocol`, `dsh-typert-registry`, `dsh-api-remotes`, `dsh-commands`, `dsh-timeout`), all currently `^0.1.0-rc.7`.
67
+
68
+ ### Capability boundary and side effects
69
+
70
+ - Network: only the loopback-forced `http://127.0.0.1:23119/api` (redirects refused, streaming byte bound); no external network calls.
71
+ - Files: only `existsSync` checks of attachment disk paths — never written, never executed.
72
+ - Process: no shell calls, no native modules, no resident background tasks or timers — every request is driven by a tool call, and loading the plugin never probes Zotero.
73
+ - External side effects: the only persistent write is the settings card saving the `zotero:` section (user layer) of `$DSH_HOME/settings.yaml`; no telemetry.
59
74
 
60
75
  ## Install
61
76
 
@@ -72,7 +87,7 @@ The tarball ships the built `lib/` (the node half plus the browser half `lib/cli
72
87
  ```sh
73
88
  cd dsh-zotero
74
89
  npm pack
75
- dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
90
+ dsh plugin --profile <name> add ./dsh-zotero-0.3.1.tgz
76
91
  ```
77
92
 
78
93
  `npm pack` runs `prepare` first, so the tarball carries a fresh `lib/`. Use this for unpublished or local trial installs.
@@ -98,32 +113,32 @@ The plugin mounts as id `zotero` and takes effect on the next dsh start. After i
98
113
 
99
114
  All values are `Config` fields changeable from the bundle's `config` block (e.g. via `dsh plugin config`). Defaults are shown.
100
115
 
101
- | Field | Default | Meaning |
102
- | ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
103
- | `baseUrl` | `http://127.0.0.1:23119/api` | Local API base URL. Plain loopback HTTP only. |
104
- | `provider` | `local` | Provider id to select. |
105
- | `timeoutMs` | `5000` | Per-request provider deadline. |
106
- | `maxSearchResults` | `20` | Upper bound for `zotero_search` `limit`. |
107
- | `maxNoteScanRecords` | `200` | Upper bound for note records scanned for body matches by `zotero_search`. |
108
- | `maxEvidenceChars` | `6000` | Total character budget for retrieved evidence. |
109
- | `maxEvidencePassages` | `4` | Upper bound for evidence passage counts. |
110
- | `maxDetailChars` | `3000` | Character budget for `zotero_get` abstract previews. |
111
- | `maxNoteBodyChars` | `30000` | Character budget for a note item's own body returned by `zotero_get`. |
112
- | `maxNoteChars` | `2000` | Character budget per note preview in `zotero_get`. |
113
- | `maxNoteRecords` | `50` | Upper bound for note records returned by `zotero_get`. |
114
- | `maxAnnotationRecords` | `100` | Upper bound for annotation records returned by `zotero_get`. |
115
- | `fulltextChunkWords` | `200` | Word count per full-text passage entering evidence ranking. |
116
- | `maxFulltextChars` | `250000` | Full text accepted into evidence ranking. |
117
- | `maxResponseBytes` | `16777216` | Streaming byte bound for every API response. |
118
- | `maxExportChars` | `1000000` | Export output hard limit. Never mid-truncated. |
119
- | `maxExportRefs` | `1000` | Upper bound for refs in one `zotero_export` call; keeps the request line under the server's HTTP header limit. |
120
- | `defaultStyle` | `apa` | CSL style for citation/bibliography formats. |
121
- | `defaultLocale` | `en-US` | CSL locale for citation/bibliography formats. |
122
- | `webEnabled` | `true` | Enables the dedicated Zotero conversation tab; the gate is read once per page load. |
116
+ | Field | Default | Meaning |
117
+ | ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
118
+ | `baseUrl` | `http://127.0.0.1:23119/api` | Local API base URL. Plain loopback HTTP only. |
119
+ | `provider` | `local` | Provider id to select. |
120
+ | `timeoutMs` | `5000` | Per-request provider deadline. |
121
+ | `maxSearchResults` | `20` | Upper bound for `zotero_search` `limit`. |
122
+ | `maxNoteScanRecords` | `200` | Upper bound for note records scanned for body matches by `zotero_search`. |
123
+ | `maxEvidenceChars` | `6000` | Total character budget for retrieved evidence. |
124
+ | `maxEvidencePassages` | `4` | Upper bound for evidence passage counts. |
125
+ | `maxDetailChars` | `3000` | Character budget for `zotero_get` abstract previews. |
126
+ | `maxNoteBodyChars` | `30000` | Character budget for a note item's own body returned by `zotero_get`. |
127
+ | `maxNoteChars` | `2000` | Character budget per note preview in `zotero_get`. |
128
+ | `maxNoteRecords` | `50` | Upper bound for note records returned by `zotero_get`. |
129
+ | `maxAnnotationRecords` | `100` | Upper bound for annotation records returned by `zotero_get`. |
130
+ | `fulltextChunkWords` | `200` | Word count per full-text passage entering evidence ranking. |
131
+ | `maxFulltextChars` | `250000` | Full text accepted into evidence ranking. |
132
+ | `maxResponseBytes` | `16777216` | Streaming byte bound for every API response. |
133
+ | `maxExportChars` | `1000000` | Export output hard limit. Never mid-truncated. |
134
+ | `maxExportRefs` | `50` | Upper bound for refs in one `zotero_export` call; citation batches past the API's 50-key per-request cap. |
135
+ | `defaultStyle` | `apa` | CSL style for citation/bibliography formats. |
136
+ | `defaultLocale` | `en-US` | CSL locale for citation/bibliography formats. |
137
+ | `webEnabled` | `true` | Enables the dedicated Zotero tab at the top of the session; the toggle applies live — turning it off hides the tab right away, no reload needed. |
123
138
 
124
139
  ### Web configuration
125
140
 
126
- The plugin registers a "Zotero" card in dsh web's **Settings → Plugins → Plugin configuration** page listing all 20 fields above. The card binds the `zotero` settings namespace: writes land in the `zotero:` section of `$DSH_HOME/settings.yaml` (layered over the patch entry's `config`, user layer wins), and **saves apply live** — the transport and the provider rebuild on the new values, so the next tool call or `/zotero status` uses them without a dsh restart.
141
+ The plugin registers a "Zotero" card in dsh web's **Settings → Plugins → Plugin configuration** page listing every field in the table above. The card binds the `zotero` settings namespace: writes land in the `zotero:` section of `$DSH_HOME/settings.yaml` (layered over the patch entry's `config`, user layer wins), and **saves apply live** — the transport and the provider rebuild on the new values, so the next tool call or `/zotero status` uses them without a dsh restart.
127
142
 
128
143
  - Invalid values (a non-loopback `baseUrl`, a non-positive limit) are refused before the write; the card reports the failed save and keeps the draft, and the plugin keeps running on the last valid value.
129
144
  - Every field shows its effective value; fields overridden by the settings document carry an "Overridden" badge and offer a one-click reset (clears the user layer, back to the patch entry value).
@@ -136,13 +151,13 @@ The dsh web session view is a tab ring (Chat, Trajectory, …). The plugin regis
136
151
 
137
152
  - A **connection strip** leads the tab: one status probe on mount, another per explicit Refresh (request-driven, no polling timers); it shows the connection state, API/schema versions, Server ID (Zotero 10+), and the last-checked time, with the diagnosis when Zotero is unavailable.
138
153
  - Below it, the session's **Zotero tool activity**: every search, read, retrieve, attachment, and export call renders as a rich card (expandable, copyable refs, evidence passages labeled by source), fully replay-driven from the conversation snapshot — the same transcript renders the same cards, and missing meta degrades to the raw content.
139
- - The **Web → Session tool cards** toggle in the settings page (`webEnabled`, default on) controls the tab's registration; the gate is read once per page load, so a toggle change applies after the page reloads. When off, Zotero calls show as dsh's built-in generic cards in the trajectory.
154
+ - The **Web → Session tool cards** toggle in the settings page (`webEnabled`, default on) controls the tab's registration; the toggle applies live — turning it off hides the tab immediately, no reload needed. When off, Zotero calls show as dsh's built-in generic cards in the trajectory.
140
155
 
141
156
  ## Limits
142
157
 
143
158
  - Read-only library: no path modifies items, notes, tags, or collections.
144
159
  - Full-text evidence depends on Zotero's index: `everything` search and `retrieve` full-text passages both require indexing.
145
- - Note-content search is a client-side scan: library/collection scopes and the first result page only, bounded by `maxNoteScanRecords`; notes beyond the cap never match.
160
+ - Note-content search is a client-side scan: library/collection scopes and the first result page (offset 0) only, bounded by `maxNoteScanRecords`; matches fill the first page up to the limit and are reported in the `noteMatches` field, outside the paged `total`.
146
161
  - Attachment depth depends on the harness composition: `zotero_attachment` returns the file location; reading that PDF further needs a matching file/PDF capability.
147
162
  - Evidence ranking is term-based relevance, not embedding or semantic search.
148
163
 
@@ -187,16 +202,13 @@ pnpm dsh web --patch ./dsh-zotero/dev.cordis.yml
187
202
 
188
203
  This plugin builds in two halves: the **Node side** (`lib/`, emitted by `tsc`, holds the service, tools, provider, and other logic) and the **browser side** (`lib/client.js`, emitted by `esbuild`, holds the dsh web configuration card and the Zotero tab view). The three flows below cover the common cases.
189
204
 
190
- - `npm run build` emits both halves; `npm run build:client` rebuilds only the browser side.
191
- - The rest of this section assumes `npm run build` has been run at least once so `lib/` exists.
192
-
193
205
  **① Resident instance verification (tarball install)**
194
206
 
195
207
  Pack a tarball and install it into a profile. The plugin runs from the tarball's built artifacts; code updates require re-packing and re-installing. Verify with the production-stack smoke after install:
196
208
 
197
209
  ```sh
198
210
  npm pack
199
- dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
211
+ dsh plugin --profile <name> add ./dsh-zotero-0.3.1.tgz
200
212
  cd ~/.dsh/profiles/<name>
201
213
  node --input-type=module < /path/to/dsh-zotero/scripts/smoke.mjs
202
214
  ```
package/README.md CHANGED
@@ -1,19 +1,26 @@
1
- <h1 align="center">dsh-zotero</h1>
1
+ <div align="center">
2
2
 
3
+ # dsh-zotero
4
+
5
+ <img
6
+ src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=500&size=18&pause=2000&color=CC2936&center=true&vCenter=true&width=760&lines=%3E+Zotero+as+an+evidence+store+for+agents."
7
+ alt="dsh-zotero"
8
+ />
3
9
  <p align="center">
4
- <a href="README.en.md"><b>English</b></a> · <b>中文</b>
10
+ <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/v/dsh-zotero" alt="npm version" style="max-width:100%;"></a>
11
+ <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/dm/dsh-zotero" alt="npm downloads" style="max-width:100%;"></a>
12
+ <a href="https://www.npmjs.com/package/dsh-zotero"><img src="https://img.shields.io/npm/l/dsh-zotero" alt="license" style="max-width:100%;"></a>
13
+ <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
5
14
  </p>
15
+ </div>
6
16
 
7
17
  <p align="center">
8
- <a href="https://awesome-dsh-plugin.com"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome DSH Plugin"></a>
9
- <img src="https://img.shields.io/npm/v/dsh-zotero" alt="npm version">
10
- <img src="https://img.shields.io/npm/dm/dsh-zotero" alt="npm downloads">
11
- <img src="https://img.shields.io/npm/l/dsh-zotero" alt="license">
18
+ <a href="README.en.md"><b>English</b></a> · <b>中文</b>
12
19
  </p>
13
20
 
14
- 让 Agents 搜索、阅读并引用你的本地 [Zotero](https://www.zotero.org) 文献库：找文献、查看笔记与批注、按问题取证、打开原文、生成引用。
21
+ 让 Agent 从你的 [Zotero](https://www.zotero.org) 文献库中发现来源、提取与问题相关的证据，并始终保留证据与原始文献之间的联系。
15
22
 
16
- 在会话里用自然语言描述需求，Agent 自动按需调用下面的工具；唯一的手动命令是 `/zotero status`。
23
+ dsh-zotero 面向 Agent 的研究工作流设计：从文献检索、元数据与笔记查看，到证据检索、原文打开和引用生成，Agent 可以根据当前任务逐步获取所需信息，而不必一次读取整篇文献或整个文献库。
17
24
 
18
25
  ## 工具
19
26
 
@@ -56,6 +63,14 @@ Agent 按需求逐层深入，一段典型对话：
56
63
  - 已安装 Zotero 桌面版，并启用本地 API：**设置 → 高级 → “Allow other applications on this computer to communicate with Zotero”**。
57
64
  - 本地 API 为无认证读取，地址为 `http://127.0.0.1:23119/api`。V1 没有任何修改文献库数据（条目、笔记、标签、分类等）的路径。
58
65
  - Zotero ≥ 7，本地 API 版本为 3。如果 status 命令报告版本不匹配，请升级。
66
+ - Node.js ≥ 22.19（或 24+）；宿主 dsh 运行时为 rc.7 系。运行时依赖（peer）见 `package.json` 的 `peerDependencies`（`@deepseek-ai/cordis` ≥ 4、`dsh-tools`、`dsh-llm`、`dsh-settings`、`dsh-user-questions`、`dsh-typert-protocol`、`dsh-typert-registry`、`dsh-api-remotes`、`dsh-commands`、`dsh-timeout`），当前均声明为 `^0.1.0-rc.7`。
67
+
68
+ ### 能力边界与副作用
69
+
70
+ - 网络：只访问强制回环的 `http://127.0.0.1:23119/api`（拒绝重定向、流式字节上限）；没有任何外部网络调用。
71
+ - 文件：仅读取附件磁盘路径的存在性（`existsSync`），不写入、不执行。
72
+ - 进程：无 Shell 调用、无 native 模块、无常驻后台任务或定时器——所有请求都由工具调用驱动，加载插件不会探测 Zotero。
73
+ - 外部副作用：唯一的持久化写入是设置卡片保存时对 `$DSH_HOME/settings.yaml` 中 `zotero:` 小节（用户层）的更新；无遥测、无埋点。
59
74
 
60
75
  ## 安装
61
76
 
@@ -72,7 +87,7 @@ tarball 内含已构建的 `lib/`（node 半与浏览器半 `lib/client.js`）
72
87
  ```sh
73
88
  cd dsh-zotero
74
89
  npm pack
75
- dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
90
+ dsh plugin --profile <name> add ./dsh-zotero-0.3.1.tgz
76
91
  ```
77
92
 
78
93
  `npm pack` 先运行 `prepare` 构建 `lib/`，适合未发布或本地试装。
@@ -98,28 +113,28 @@ allowBuilds:
98
113
 
99
114
  所有值都是 `Config` 字段，可在 bundle 的 `config` 块中修改（例如通过 `dsh plugin config`）。以下为默认值。
100
115
 
101
- | 字段 | 默认值 | 含义 |
102
- | ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------- |
103
- | `baseUrl` | `http://127.0.0.1:23119/api` | 本地 API 基础 URL。仅支持纯回环 HTTP。 |
104
- | `provider` | `local` | 要选择的 provider id。 |
105
- | `timeoutMs` | `5000` | 每个请求的 provider 超时时间。 |
106
- | `maxSearchResults` | `20` | `zotero_search` `limit` 的上限。 |
107
- | `maxNoteScanRecords` | `200` | `zotero_search` 补扫笔记正文的笔记数量上限。 |
108
- | `maxEvidenceChars` | `6000` | 检索证据的总字符预算。 |
109
- | `maxEvidencePassages` | `4` | 证据片段数量的上限。 |
110
- | `maxDetailChars` | `3000` | `zotero_get` 摘要预览的字符预算。 |
111
- | `maxNoteBodyChars` | `30000` | `zotero_get` 返回 note 条目自身正文的字符预算。 |
112
- | `maxNoteChars` | `2000` | `zotero_get` 单条笔记预览的字符预算。 |
113
- | `maxNoteRecords` | `50` | `zotero_get` 返回笔记数量的上限。 |
114
- | `maxAnnotationRecords` | `100` | `zotero_get` 返回批注数量的上限。 |
115
- | `fulltextChunkWords` | `200` | 进入证据排序的全文片段词数。 |
116
- | `maxFulltextChars` | `250000` | 进入证据排序的全文大小上限。 |
117
- | `maxResponseBytes` | `16777216` | 每个 API 响应的流式字节上限。 |
118
- | `maxExportChars` | `1000000` | 导出输出的硬上限。不会中途截断。 |
119
- | `maxExportRefs` | `1000` | 单次 `zotero_export` 的 refs 数量上限，保护请求行不超服务器 HTTP 头限制。 |
120
- | `defaultStyle` | `apa` | 引用/参考文献使用的 CSL 样式。 |
121
- | `defaultLocale` | `en-US` | 引用/参考文献使用的 CSL locale。 |
122
- | `webEnabled` | `true` | 是否在会话顶部显示 Zotero 专属标签页；开关在每次页面加载时读取，切换后需刷新页面生效。 |
116
+ | 字段 | 默认值 | 含义 |
117
+ | ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------ |
118
+ | `baseUrl` | `http://127.0.0.1:23119/api` | 本地 API 基础 URL。仅支持纯回环 HTTP。 |
119
+ | `provider` | `local` | 要选择的 provider id。 |
120
+ | `timeoutMs` | `5000` | 每个请求的 provider 超时时间。 |
121
+ | `maxSearchResults` | `20` | `zotero_search` `limit` 的上限。 |
122
+ | `maxNoteScanRecords` | `200` | `zotero_search` 补扫笔记正文的笔记数量上限。 |
123
+ | `maxEvidenceChars` | `6000` | 检索证据的总字符预算。 |
124
+ | `maxEvidencePassages` | `4` | 证据片段数量的上限。 |
125
+ | `maxDetailChars` | `3000` | `zotero_get` 摘要预览的字符预算。 |
126
+ | `maxNoteBodyChars` | `30000` | `zotero_get` 返回 note 条目自身正文的字符预算。 |
127
+ | `maxNoteChars` | `2000` | `zotero_get` 单条笔记预览的字符预算。 |
128
+ | `maxNoteRecords` | `50` | `zotero_get` 返回笔记数量的上限。 |
129
+ | `maxAnnotationRecords` | `100` | `zotero_get` 返回批注数量的上限。 |
130
+ | `fulltextChunkWords` | `200` | 进入证据排序的全文片段词数。 |
131
+ | `maxFulltextChars` | `250000` | 进入证据排序的全文大小上限。 |
132
+ | `maxResponseBytes` | `16777216` | 每个 API 响应的流式字节上限。 |
133
+ | `maxExportChars` | `1000000` | 导出输出的硬上限。不会中途截断。 |
134
+ | `maxExportRefs` | `50` | 单次 `zotero_export` 的 refs 数量上限；citation 分批到该上限，其余格式单次最多 50。 |
135
+ | `defaultStyle` | `apa` | 引用/参考文献使用的 CSL 样式。 |
136
+ | `defaultLocale` | `en-US` | 引用/参考文献使用的 CSL locale。 |
137
+ | `webEnabled` | `true` | 是否在会话顶部显示 Zotero 专属标签页；开关即时生效，关闭后立即隐藏标签页，无需刷新。 |
123
138
 
124
139
  ### Web 配置
125
140
 
@@ -136,13 +151,13 @@ dsh web 的会话视图是标签页环（Chat、Trajectory、…）。插件注
136
151
 
137
152
  - 标签页顶部是**连接条**：挂载时探测一次、每次手动刷新再探测一次（请求驱动，无轮询定时器）；显示连接状态、API/Schema 版本、Server ID（Zotero 10+）与上次检查时间；Zotero 不可用时显示诊断信息。
138
153
  - 下方是本会话的 **Zotero 工具活动**：每次搜索、精读、取证、附件解析与导出调用都渲染为富卡片（可展开、ref 可复制、证据段落标注来源），完全由会话快照重放驱动——同一段记录永远渲染出同样的卡片，meta 缺失时降级为原始内容。
139
- - 设置页的 **Web → 会话工具卡片** 开关（`webEnabled`，默认开启）控制标签页的注册；开关在每次页面加载时读取一次，切换后需刷新页面生效。关闭后，Zotero 调用在轨迹中显示为 dsh 内置的通用卡片。
154
+ - 设置页的 **Web → 会话工具卡片** 开关（`webEnabled`，默认开启）控制标签页的注册；开关即时生效——打开立即显示、关闭立即隐藏，无需刷新页面。关闭后，Zotero 调用在轨迹中显示为 dsh 内置的通用卡片。
140
155
 
141
156
  ### 限制
142
157
 
143
158
  - 只读文献库：没有任何路径会修改条目、笔记、标签或合集。
144
159
  - 全文证据依赖 Zotero 的索引：`everything` 搜索与 `retrieve` 的全文段落都需要已建立索引。
145
- - 笔记正文搜索是客户端扫描：仅限 library/collection 作用域与第一页结果，受 `maxNoteScanRecords` 限制；超出上限的笔记永远不会命中。
160
+ - 笔记正文搜索是客户端扫描：仅限 library/collection 作用域与第一页结果（offset 0），受 `maxNoteScanRecords` 限制；命中并入第一页直到 `limit`，计数在返回的 `noteMatches` 字段中，不计入分页 `total`。
146
161
  - 附件深度取决于宿主组合：`zotero_attachment` 返回文件位置；继续阅读该 PDF 需要宿主具备对应的文件/PDF 能力。
147
162
  - 证据排序是基于词项的相关性，而非向量或语义检索。
148
163
 
@@ -193,7 +208,7 @@ pnpm dsh web --patch ./dsh-zotero/dev.cordis.yml
193
208
 
194
209
  ```sh
195
210
  npm pack
196
- dsh plugin --profile <name> add ./dsh-zotero-0.1.0.tgz
211
+ dsh plugin --profile <name> add ./dsh-zotero-0.3.1.tgz
197
212
  cd ~/.dsh/profiles/<name>
198
213
  node --input-type=module < /path/to/dsh-zotero/scripts/smoke.mjs
199
214
  ```