dsh-zotero 0.2.0 → 0.2.1
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.
- package/README.en.md +16 -15
- package/README.md +16 -15
- package/lib/ask.js +2 -2
- package/lib/ask.js.map +1 -1
- package/package.json +1 -1
package/README.en.md
CHANGED
|
@@ -1,9 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">dsh-zotero</h1>
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
4
|
<b>English</b> · <a href="README.md"><b>中文</b></a>
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
|
+
<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">
|
|
12
|
+
</p>
|
|
13
|
+
|
|
7
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.
|
|
8
15
|
|
|
9
16
|
Describe what you need in a session and the Agent calls the tools below as needed. The only manual command is `/zotero status`.
|
|
@@ -44,20 +51,6 @@ The Agent moves down the ladder as a request deepens. A typical conversation:
|
|
|
44
51
|
|
|
45
52
|
`/zotero status` reports connectivity, API/schema versions, and the database identity (Server ID, Zotero 10+). This is the only health check. Ordinary calls fail with typed domain errors.
|
|
46
53
|
|
|
47
|
-
## On-demand work and connectivity-failure interaction
|
|
48
|
-
|
|
49
|
-
- The plugin is resident but strictly request-driven: loading, idling, and unloading never issue a request (no probes, no polling, no background work). Only two entry points touch Zotero: the five tools, invoked when the user explicitly asks about their library, and the explicitly invoked `/zotero status` command.
|
|
50
|
-
- When a tool call fails with a connectivity error (`ZOTERO_NOT_RUNNING` not running / `ZOTERO_API_DISABLED` local API disabled / `ZOTERO_API_VERSION` unsupported version / `ZOTERO_TIMEOUT` timed out), the plugin asks the user how to proceed through an interactive question card: the first option is the recommended action marked `(Recommended)` (e.g. "I started Zotero, retry (Recommended)"); choosing it re-runs the same request once, and a second failure or the "Abort this query" choice surfaces the original typed error — never a second question.
|
|
51
|
-
- Without an interactive provider (headless compositions), the ask is skipped and the typed error is returned as-is; a failing question mechanism never masks the original connectivity error.
|
|
52
|
-
|
|
53
|
-
## Limits
|
|
54
|
-
|
|
55
|
-
- Read-only library: no path modifies items, notes, tags, or collections.
|
|
56
|
-
- Full-text evidence depends on Zotero's index: `everything` search and `retrieve` full-text passages both require indexing.
|
|
57
|
-
- 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.
|
|
58
|
-
- Attachment depth depends on the harness composition: `zotero_attachment` returns the file location; reading that PDF further needs a matching file/PDF capability.
|
|
59
|
-
- Evidence ranking is term-based relevance, not embedding or semantic search.
|
|
60
|
-
|
|
61
54
|
## Requirements
|
|
62
55
|
|
|
63
56
|
- Zotero desktop with the local API enabled: **Settings → Advanced → "Allow other applications on this computer to communicate with Zotero"**.
|
|
@@ -136,6 +129,14 @@ The plugin registers a "Zotero" card in dsh web's **Settings → Plugins → Plu
|
|
|
136
129
|
- External edits to the settings document (e.g. editing `settings.yaml` directly) hot-apply too.
|
|
137
130
|
- Compositions without a settings service (pure headless) never register the namespace, and the plugin behaves exactly as if unconfigured.
|
|
138
131
|
|
|
132
|
+
## Limits
|
|
133
|
+
|
|
134
|
+
- Read-only library: no path modifies items, notes, tags, or collections.
|
|
135
|
+
- Full-text evidence depends on Zotero's index: `everything` search and `retrieve` full-text passages both require indexing.
|
|
136
|
+
- 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.
|
|
137
|
+
- Attachment depth depends on the harness composition: `zotero_attachment` returns the file location; reading that PDF further needs a matching file/PDF capability.
|
|
138
|
+
- Evidence ranking is term-based relevance, not embedding or semantic search.
|
|
139
|
+
|
|
139
140
|
## Development
|
|
140
141
|
|
|
141
142
|
### Commands
|
package/README.md
CHANGED
|
@@ -1,9 +1,16 @@
|
|
|
1
|
-
|
|
1
|
+
<h1 align="center">dsh-zotero</h1>
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
4
|
<a href="README.en.md"><b>English</b></a> · <b>中文</b>
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
|
+
<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">
|
|
12
|
+
</p>
|
|
13
|
+
|
|
7
14
|
让 Agents 搜索、阅读并引用你的本地 [Zotero](https://www.zotero.org) 文献库：找文献、查看笔记与批注、按问题取证、打开原文、生成引用。
|
|
8
15
|
|
|
9
16
|
在会话里用自然语言描述需求，Agent 自动按需调用下面的工具；唯一的手动命令是 `/zotero status`。
|
|
@@ -44,20 +51,6 @@ Agent 按需求逐层深入，一段典型对话：
|
|
|
44
51
|
|
|
45
52
|
`/zotero status` 报告连通性、API/schema 版本和数据库身份标识（Server ID，Zotero 10+）。这是唯一的健康检查。普通调用失败时返回带类型的领域错误。
|
|
46
53
|
|
|
47
|
-
## 按需工作与连接失败交互
|
|
48
|
-
|
|
49
|
-
- 插件常驻但完全请求驱动：加载、闲置、卸载都不会发起任何请求（无探测、无轮询、无后台任务）。只有两种入口会触达 Zotero：Agent 在用户明确要求时调用五个工具，或用户手动执行 `/zotero status`。
|
|
50
|
-
- 工具调用遇到连接类失败（`ZOTERO_NOT_RUNNING` 未运行 / `ZOTERO_API_DISABLED` 本地 API 被禁用 / `ZOTERO_API_VERSION` 版本过旧 / `ZOTERO_TIMEOUT` 超时）时，会通过交互式问题卡片询问用户怎么处理：第一个选项是带 `(Recommended)` 的推荐操作（英文文案，与错误消息一致，如 "I started Zotero, retry (Recommended)"），选择后插件按原参数重试一次；再失败或选择 "Abort this query" 时返回原类型化错误，绝不反复询问。
|
|
51
|
-
- 无交互能力的环境（headless 组合、无 UI provider）自动降级：不询问，直接返回类型化错误。询问机制自身故障也绝不掩盖原始连接错误。
|
|
52
|
-
|
|
53
|
-
## 限制
|
|
54
|
-
|
|
55
|
-
- 对文献库只读：没有任何修改条目、笔记、标签、分类等文献库数据的路径。
|
|
56
|
-
- 全文证据依赖 Zotero 的全文索引：`everything` 搜索和 `retrieve` 的全文片段都以索引为前提。
|
|
57
|
-
- 笔记正文搜索是插件侧补扫：仅库/分类范围、仅结果首页、受 `maxNoteScanRecords` 上限约束，超出上限的笔记不参与匹配。
|
|
58
|
-
- 附件深度分析取决于当前 Harness 配置：`zotero_attachment` 返回文件位置，能否继续读取该 PDF 由 composition 里是否有相应文件/PDF 能力决定。
|
|
59
|
-
- 证据排序是词项相关度检索，不是 embedding 或语义搜索。
|
|
60
|
-
|
|
61
54
|
## 环境要求
|
|
62
55
|
|
|
63
56
|
- 已安装 Zotero 桌面版，并启用本地 API：**设置 → 高级 → “Allow other applications on this computer to communicate with Zotero”**。
|
|
@@ -136,6 +129,14 @@ allowBuilds:
|
|
|
136
129
|
- 设置文档被外部编辑（如直接改 `settings.yaml`）时同样会热生效。
|
|
137
130
|
- 无 settings 服务的组合（纯 headless）不注册命名空间，插件行为与未配置时完全一致。
|
|
138
131
|
|
|
132
|
+
## 限制
|
|
133
|
+
|
|
134
|
+
- 对文献库只读：没有任何修改条目、笔记、标签、分类等文献库数据的路径。
|
|
135
|
+
- 全文证据依赖 Zotero 的全文索引：`everything` 搜索和 `retrieve` 的全文片段都以索引为前提。
|
|
136
|
+
- 笔记正文搜索是插件侧补扫：仅库/分类范围、仅结果首页、受 `maxNoteScanRecords` 上限约束，超出上限的笔记不参与匹配。
|
|
137
|
+
- 附件深度分析取决于当前 Harness 配置：`zotero_attachment` 返回文件位置，能否继续读取该 PDF 由 composition 里是否有相应文件/PDF 能力决定。
|
|
138
|
+
- 证据排序是词项相关度检索，不是 embedding 或语义搜索。
|
|
139
|
+
|
|
139
140
|
## 开发
|
|
140
141
|
|
|
141
142
|
### 命令
|
package/lib/ask.js
CHANGED
|
@@ -30,7 +30,7 @@ const FAILURE_SPECS = {
|
|
|
30
30
|
[ZOTERO_NOT_RUNNING]: {
|
|
31
31
|
header: 'Zotero is not running',
|
|
32
32
|
question: 'Zotero is not running, so I cannot read your library. What should I do?',
|
|
33
|
-
detail: 'Start Zotero
|
|
33
|
+
detail: 'Start Zotero, then in Settings → Advanced check "Allow other applications on this computer to communicate with Zotero".',
|
|
34
34
|
retryLabel: 'I started Zotero, retry (Recommended)',
|
|
35
35
|
retryDescription: RETRY_DESCRIPTION,
|
|
36
36
|
abortLabel: ABORT_LABEL,
|
|
@@ -39,7 +39,7 @@ const FAILURE_SPECS = {
|
|
|
39
39
|
[ZOTERO_API_DISABLED]: {
|
|
40
40
|
header: 'Zotero local API is disabled',
|
|
41
41
|
question: 'Zotero is running but rejected the local API request (403).',
|
|
42
|
-
detail: '
|
|
42
|
+
detail: 'In Zotero Settings → Advanced, check "Allow other applications on this computer to communicate with Zotero".',
|
|
43
43
|
retryLabel: 'I enabled the local API, retry (Recommended)',
|
|
44
44
|
retryDescription: RETRY_DESCRIPTION,
|
|
45
45
|
abortLabel: ABORT_LABEL,
|
package/lib/ask.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ask.js","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAuB,MAAM,wBAAwB,CAAA;AAO1E,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAA;AAEpB,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,kBAAkB;IAClB,mBAAmB;IACnB,kBAAkB;IAClB,cAAc;CACN,CAAA;AAkBV,MAAM,WAAW,GAAG,kBAAkB,CAAA;AACtC,MAAM,iBAAiB,GAAG,kEAAkE,CAAA;AAC5F,MAAM,iBAAiB,GAAG,gDAAgD,CAAA;AAE1E,MAAM,aAAa,GAAuC;IACxD,CAAC,kBAAkB,CAAC,EAAE;QACpB,MAAM,EAAE,uBAAuB;QAC/B,QAAQ,EAAE,yEAAyE;QACnF,MAAM,EACJ,
|
|
1
|
+
{"version":3,"file":"ask.js","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-zotero",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Let agents search, read, and cite your local Zotero library: find papers, browse notes and annotations, pull evidence by question, open the source document, generate citations.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"zotero",
|