dsh-plugin-litsearch 0.3.5 → 0.4.0

package/lib/host/tools.js

@@ -9,14 +9,22 @@
  * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读与分组，
  *   做新老对比与统计。
  * - `literature_export`：把任务（按筛选）导出为 CSV / RIS / BibTeX / Markdown 并落盘。
+ * - `literature_download`：把自然语言下载请求解析成已校验的 paperId 清单，
+ *   通过事件下发给右侧栏，由右侧栏复用批量下载弹窗执行并逐篇展示。
+ * - `literature_zotero`：与下载共用范围解析，改为让右侧栏复用 Zotero 同步
+ *   弹窗；对话里点名目录且匹配成功才自动开跑，否则由用户选目录。
  *
  * 参数在边界做一次校验（模型输出不可信），服务层仍会再兜底。
  */
-import { MAX_LIMIT } from '../search/config.js';
+import { randomUUID } from 'node:crypto';
+import { MAX_LIMIT, getSettings } from '../search/config.js';
 import { SearchError } from '../search/errors.js';
 import { asRecord } from '../search/normalize.js';
 import { PROVIDER_INFOS } from '../search/providers/index.js';
-import { SOURCE_IDS, TASK_LANGUAGES } from '../search/types.js';
+import { RESULT_PAGE_SIZE, SOURCE_IDS, TASK_LANGUAGES } from '../search/types.js';
+import { describePages, mergeDownloadFilter, resolveDownloadScope, toPaperFilter, } from './tasks/download.js';
+import { filterPapers, pdfStatusOf, sortPapers } from './tasks/filter.js';
+import { describeZoteroTargets, matchZoteroTarget } from './zotero/match.js';
 import { resolveSessionWorkspace } from './workspace.js';
 /** 模型侧最多等多久；超时后任务继续跑，只返回当前进度与已有结果。 */
 const MODEL_WAIT_MS = 25_000;
@@ -28,6 +36,28 @@ const SORT_MODES = ['relevance', 'citations', 'year'];
 const LANGUAGES = TASK_LANGUAGES;
 const SCREENINGS = ['unread', 'read', 'included', 'excluded'];
 const EXPORT_FORMATS = ['csv', 'ris', 'bibtex', 'md'];
+const DOWNLOAD_SCOPES = [
+    'ids',
+    'currentPage',
+    'pages',
+    'currentView',
+    'all',
+    'group',
+    'filters',
+];
+const PAGE_BASES = ['view', 'filtered'];
+/** `fields=ids` 时一次最多回多少条 id（与 `literature_task` 的 limit 上限一致）。 */
+const IDS_LIMIT = 200;
+const PDF_STATUSES = [
+    'unknown',
+    'available',
+    'downloaded',
+    'missing',
+    'html-only',
+    'paywalled',
+    'blocked',
+    'failed',
+];
 const TASK_ACTIONS = [
     'current',
     'list',
@@ -154,6 +184,25 @@ const TASK_PARAMETERS = {
         groupId: { type: 'string', description: '按任务内分组过滤。' },
         queryId: { type: 'string', description: '按检索式 id 过滤命中文献。' },
         q: { type: 'string', description: '标题/摘要关键词。' },
+        hasPdf: {
+            type: 'boolean',
+            description: 'get 时只看有 PDF 直链或已下载的文献；引用「有 PDF 的那批」前先用它核对。',
+        },
+        missingFullText: { type: 'boolean', description: 'get 时只看尚无可用全文的文献。' },
+        pdfStatus: { type: 'string', enum: [...PDF_STATUSES], description: '按全文状态精确过滤。' },
+        yearFrom: { type: 'integer', minimum: 1, maximum: 3000, description: '起始年份。' },
+        yearTo: { type: 'integer', minimum: 1, maximum: 3000, description: '截止年份。' },
+        source: { type: 'string', enum: [...SOURCE_IDS], description: '只看该数据源命中的文献。' },
+        type: { type: 'string', description: '文献类型（精确匹配）。' },
+        language: { type: 'string', enum: [...TASK_LANGUAGES], description: '语言码。' },
+        venue: { type: 'string', description: '期刊/出处（精确匹配）。' },
+        author: { type: 'string', description: '作者全名（精确匹配）。' },
+        newOnly: { type: 'boolean', description: '只看相对基准任务新增的文献。' },
+        fields: {
+            type: 'string',
+            enum: ['full', 'ids'],
+            description: 'get 的返回格式。full（默认）= 条件 + 摘要 + paperId，适合阅读；ids = 每条只回「paperId｜标题｜是否有 PDF」，一次最多 200 条，适合列出清单或核对范围（配 offset 翻页）。',
+        },
         scope: {
             type: 'string',
             enum: ['task', 'filtered'],
@@ -239,6 +288,136 @@ const EXPORT_PARAMETERS = {
     required: ['taskId', 'format'],
     additionalProperties: false,
 };
+/**
+ * 下载范围参数的字段名一律沿用 `ResultsQuery` / `PaperFilter`，让模型下载与
+ * 界面筛选共用同一套口径；这里不引入任何新的条件表达式。
+ */
+const DOWNLOAD_PARAMETERS = {
+    type: 'object',
+    properties: {
+        taskId: { type: 'string', description: '要下载的任务 id；省略则用当前任务。' },
+        scope: {
+            type: 'string',
+            enum: [...DOWNLOAD_SCOPES],
+            description: '下载范围，按用户话术选择：ids = 用户点名了具体文献且你已从工具结果看到确切 paperId；currentPage = 「当前页/这一页」；pages = 用户给了明确页码（「第 2 页」「第 4–5 页」），必须同时给 pages；currentView = 「当前全部/当前筛选下全部」（含跨页，默认，不等于整个任务）；all = 用户明确说「整个任务/所有文献/不管筛选」；group = 「xx 分组」（必须同时给 groupId）；filters = 用户给了年份、开放获取、关键词、来源、筛读状态等条件。',
+        },
+        pages: {
+            type: 'array',
+            maxItems: 20,
+            items: { type: 'integer', minimum: 1, maximum: 500 },
+            description: 'scope=pages 时的页码，1-based，指用户在右侧栏看到的那一页（每页 20 条，按当前排序与筛选），不是任务条件的「每源条数」。例：「第二页」→ [2]；「第 4–5 页」→ [4,5]。页码由宿主按面板上报的视图快照换算成 paperId，你不要自己算 offset 或搬 id。',
+        },
+        pageBase: {
+            type: 'string',
+            enum: [...PAGE_BASES],
+            description: '页码的基准，默认 view。view = 先按面板当前筛选/排序切页，再在页内套 hasPdf 等附加条件（「第二页里有 PDF 的文献」用这个）；filtered = 先把附加条件合并进筛选再切页（「有 PDF 的文献的第 2 页」用这个）。',
+        },
+        reason: {
+            type: 'string',
+            description: '一句话复述用户要下载的范围（会显示在右侧批量下载框里），必填。',
+        },
+        paperIds: {
+            type: 'array',
+            maxItems: 1500,
+            items: { type: 'string' },
+            description: 'scope=ids 时的确切 paperId 列表。只能填你在工具返回的「paperId:」行里看到的 id，禁止编造或猜测；其余 id 会被忽略。',
+        },
+        q: { type: 'string', description: '标题/摘要关键词，用于「下载关于 xx 的文献」。' },
+        groupId: { type: 'string', description: '任务内分组 id；scope=group 时必填。' },
+        queryId: { type: 'string', description: '只下某条检索式命中的文献。' },
+        source: { type: 'string', enum: [...SOURCE_IDS], description: '只下该数据源命中的文献。' },
+        yearFrom: { type: 'integer', minimum: 1, maximum: 3000, description: '起始年份。' },
+        yearTo: { type: 'integer', minimum: 1, maximum: 3000, description: '截止年份。' },
+        openAccessOnly: {
+            type: 'boolean',
+            description: '仅上游标记为开放获取的文献；与 hasPdf 不等价，不要同时默认开启。',
+        },
+        hasPdf: {
+            type: 'boolean',
+            description: '仅有 PDF 直链或已下载的文献。「下载当前页的所有 pdf 文献」用这个；付费墙文献会被跳过。',
+        },
+        missingFullText: { type: 'boolean', description: '只下尚无可用全文的文献。' },
+        pdfStatus: {
+            type: 'string',
+            enum: [...PDF_STATUSES],
+            description: '按全文状态精确筛选（如只要 missing 或 failed 的重试）。',
+        },
+        screening: { type: 'string', enum: [...SCREENINGS], description: '按筛读状态过滤。' },
+        type: { type: 'string', description: '文献类型（精确匹配）。' },
+        language: { type: 'string', enum: [...TASK_LANGUAGES], description: '语言码。' },
+        venue: { type: 'string', description: '期刊/出处（精确匹配）。' },
+        author: { type: 'string', description: '作者全名（精确匹配）。' },
+    },
+    required: ['scope', 'reason'],
+    additionalProperties: false,
+};
+/**
+ * Zotero 同步的范围字段与下载**完全一致**（同一个 schema 展开），只把文案
+ * 换成同步语境；额外多一个 `collection`。这样两个工具不会各自演化出一套
+ * 筛选口径，模型学到的字段也能直接迁移。
+ */
+const ZOTERO_PARAMETERS = {
+    ...DOWNLOAD_PARAMETERS,
+    properties: {
+        ...DOWNLOAD_PARAMETERS.properties,
+        taskId: { type: 'string', description: '要同步的任务 id；省略则用当前任务。' },
+        scope: {
+            type: 'string',
+            enum: [...DOWNLOAD_SCOPES],
+            description: '同步范围，按用户话术选择：ids = 用户点名了具体文献且你已从工具结果看到确切 paperId；currentPage = 「当前页/这一页」；pages = 用户给了明确页码（「第 2 页」「第 4–5 页」），必须同时给 pages；currentView = 「当前全部/当前筛选下全部」（含跨页，默认，不等于整个任务）；all = 用户明确说「整个任务/所有文献/不管筛选」；group = 「xx 分组」（必须同时给 groupId）；filters = 用户给了年份、开放获取、关键词、来源、筛读状态等条件。',
+        },
+        pages: {
+            type: 'array',
+            maxItems: 20,
+            items: { type: 'integer', minimum: 1, maximum: 500 },
+            description: 'scope=pages 时的页码，1-based，指用户在右侧栏看到的那一页（每页 20 条，按当前排序与筛选），不是任务条件的「每源条数」。例：「第二页」→ [2]；「第 4–5 页」→ [4,5]。页码由宿主按面板上报的视图快照换算成 paperId，你不要自己算 offset 或搬 id。',
+        },
+        pageBase: {
+            type: 'string',
+            enum: [...PAGE_BASES],
+            description: '页码的基准，默认 view。view = 先按面板当前筛选/排序切页，再在页内套 hasPdf 等附加条件（「第二页里有 PDF 的文献」用这个）；filtered = 先把附加条件合并进筛选再切页（「有 PDF 的文献的第 2 页」用这个）。',
+        },
+        reason: {
+            type: 'string',
+            description: '一句话复述用户要同步的范围（会显示在右侧同步弹窗里），必填。',
+        },
+        paperIds: {
+            type: 'array',
+            maxItems: 1500,
+            items: { type: 'string' },
+            description: 'scope=ids 时的确切 paperId 列表。只能填你在工具返回的「paperId:」行里看到的 id，禁止编造或猜测；其余 id 会被忽略。',
+        },
+        collection: {
+            type: 'string',
+            description: '用户点名的 Zotero 目标目录（名称或 id，如「综述」「C15」）。省略时右侧栏会弹出同步框、加载好文献，由用户自己选目录再点「同步」；填了则宿主按名称/ id 精确匹配，唯一命中时自动选中并立即开始，找不到或有歧义时本工具不下发指令并返回可用目录清单，让你在对话里向用户确认。不确定目录名就不要猜，直接省略本字段。',
+        },
+        q: { type: 'string', description: '标题/摘要关键词，用于「同步关于 xx 的文献」。' },
+        queryId: { type: 'string', description: '只同步某条检索式命中的文献。' },
+        source: { type: 'string', enum: [...SOURCE_IDS], description: '只同步该数据源命中的文献。' },
+        hasPdf: {
+            type: 'boolean',
+            description: '仅有 PDF 直链或已下载的文献（这类才会带 PDF 附件）。',
+        },
+        missingFullText: { type: 'boolean', description: '只同步尚无可用全文的文献。' },
+    },
+    required: ['scope', 'reason'],
+    additionalProperties: false,
+};
+/**
+ * `literature_scope` 的参数：与下载 / 同步的范围字段**完全同构**，只把 reason
+ * 设为可选（预览不产生指令，不需要复述）。同构是有意的：模型核对过一次范围后，
+ * 直接把这套参数搬给 literature_download / literature_zotero 即可，不会再出现
+ * 「预览的口径」和「执行的口径」两套。
+ */
+const SCOPE_PARAMETERS = {
+    ...DOWNLOAD_PARAMETERS,
+    properties: {
+        ...DOWNLOAD_PARAMETERS.properties,
+        reason: { type: 'string', description: '可选：一句话复述当前范围，仅用于回显。' },
+    },
+    required: ['scope'],
+    additionalProperties: false,
+};
 /** 构造本插件注册的全部工具（每次注册都新造定义，便于整体替换）。 */
 export function literatureTools(service) {
     return [
@@ -328,8 +507,9 @@ export function literatureTools(service) {
         },
         {
             name: 'literature_task',
-            description: '读取与推进已保存的检索任务。current 读「当前任务」（推荐在执行任何检索/任务操作前先调用，确认这个对话正在用哪个任务；无需 id）；list 列出任务；get 读条件、分组、笔记与结果（可按筛读/分组/检索式/关键词过滤）；update 改标题、条件、任务笔记与分组；rounds 读该任务的检索轮次历史（每轮时间、条件、发起方、命中数与状态）；annotate 批量写入筛读状态与分组；compare 与旧任务按论文身份对比新增/缺失；stats 读语料统计（年份、来源、期刊、作者、类型、语言）。' +
-                '注意：一个对话只保留一个任务 tab，切换任务由用户在任务列表里完成；run 会在指定任务内开新一轮检索（并把它设为当前任务），与 literature_search 一样受「用户查看结果并明确要求后才能进入下一轮」约束，不能用它绕过该约束自行加搜；也不要用 update 改完条件就立刻 run。适合在检索之后做筛选、整理与汇报。',
+            description: '读取与推进已保存的检索任务。current 读「当前任务」（推荐在执行任何检索/任务操作前先调用，确认这个对话正在用哪个任务；无需 id）；list 列出任务；get 读条件、分组、笔记与结果（可按筛读/分组/检索式/关键词/年份/来源/类型/语言/全文状态/是否有 PDF 过滤；fields=ids 时每条只回「paperId｜标题｜有无 PDF」，一次最多 200 条，适合列清单或核对范围）；update 改标题、条件、任务笔记与分组；rounds 读该任务的检索轮次历史（每轮时间、条件、发起方、命中数与状态）；annotate 批量写入筛读状态与分组；compare 与旧任务按论文身份对比新增/缺失；stats 读语料统计（年份、来源、期刊、作者、类型、语言）。' +
+                'current / get 会回显「面板视图：第 x/y 页｜每页 20 条｜筛选…」，这是判断用户所说「第几页」的唯一依据；含页码的下载/同步请直接用 literature_download 的 scope=pages，不要靠 get 的 offset 自己拼页码。' +
+                '注意：一个对话只保留一个任务 tab，切换任务由用户在任务列表里完成；run 会在指定任务内开新一轮检索（并把它设为当前任务），与 literature_search 一样受「用户查看结果并明确要求后才能进入下一轮」约束，不能用它绕过该约束自行加搜；也不要用 update 改完条件就立刻 run。适合在检索之后做筛选、整理与汇报。用户要求批量下载 PDF 时改用 literature_download，要求批量存入 Zotero 时改用 literature_zotero。',
             parameters: TASK_PARAMETERS,
             output: TEXT_OUTPUT,
             async execute(args, exec) {
@@ -347,6 +527,44 @@ export function literatureTools(service) {
                 return { text: await runExport(service, readExportArgs(args)) };
             },
         },
+        {
+            name: 'literature_scope',
+            description: '只读的「范围预演」：把用户的说法（当前页 / 第 2 页 / 第 4–5 页 / 当前筛选全部 / 全部 / 分组 / 条件）算成一份 paperId 清单并回显，**不下载、不同步、不修改任何数据**。' +
+                '返回：范围说明、命中篇数、按面板每页 20 条算出的总页数与本次页窗口、面板当前视图（第 x/y 页、筛选条件）、清单前 10 篇（paperId + 是否有 PDF）。' +
+                '适合两种情况：(1) 用户提到了页码或范围较模糊，先预演一次确认「第 2 页」到底是哪 20 篇；(2) 执行前核对命中篇数，避免下错范围。参数与 literature_download / literature_zotero 完全一致（scope + pages + pageBase + 筛选字段），核对无误后把它们原样传给下载 / 同步工具即可，不需要搬 paperId。' +
+                '注意：页码只能用 scope=pages + pages 表达（1-based，宿主按视图快照换算）；不要自己用 offset 推算页码，也不要把 ids 当页码范围。',
+            parameters: SCOPE_PARAMETERS,
+            output: TEXT_OUTPUT,
+            async execute(args, exec) {
+                return {
+                    text: await runScopePreview(service, readScopeArgs(args, false), exec.agent?.id),
+                };
+            },
+        },
+        {
+            name: 'literature_download',
+            description: '在用户要求「帮我下载 XX 文献 / 下载当前页的所有 pdf 文献 / 下载 xx 分组下的文献 / 下载 xx 条件的文献 / 帮我下载当前全部文献」时调用：把范围算成一份已校验的 paperId 清单，下发给右侧栏，右侧栏会自动弹出批量下载框并立即逐篇下载，用户能看到每篇标题、来源与实时状态，也能点「取消下载」中止。' +
+                '【范围怎么选】用户点名具体文献且你已在工具结果的「paperId:」行看到确切 id → scope=ids 并给 paperIds；「当前页/这一页」→ scope=currentPage；「第 2 页」「第 4–5 页」→ scope=pages 并给 pages（1-based，页码指面板上那一页，宿主换算，不要自己算 offset）；「当前全部/当前筛选下全部」→ scope=currentView（含跨页，不等于整个任务）；明确说「整个任务/所有文献/不管筛选」→ scope=all；「xx 分组」→ scope=group + groupId；给了年份、OA、关键词、来源、筛读状态等条件 → scope=filters 并填对应字段。pages 与 hasPdf 同时给时，默认先按面板切页、再在页内留下有 PDF 的（「第二页里有 PDF 的文献」）；要「有 PDF 的文献的第 2 页」则传 pageBase=filtered。' +
+                '【重要】你看不到右侧栏界面，「当前页」「第 N 页」「当前筛选全部」由宿主用面板上报的视图快照 + 服务端筛选精确计算，不要自己猜页码或编造 paperId；页码不等于任务条件的「每源条数」（面板每页恒为 20 条）。范围不确定时先调 literature_scope 预演，再执行。scope=ids 时只能使用工具结果里出现过的 paperId，无效 id 会被忽略。hasPdf 表示「有 PDF 直链或已下载」，openAccessOnly 表示上游标记为开放获取，两者不等价，不要同时默认开启。' +
+                '本工具只下发指令、不等待下载完成，也不要重复调用同一条指令或臆测下载结果；若范围为空会返回原因而不下发。需要检索后再下载时，先按检索工具的轮次约束完成检索，再由用户明确提出下载。用户要求把文献「存入 Zotero / 同步到文献库」时改用 literature_zotero，不要用本工具。',
+            parameters: DOWNLOAD_PARAMETERS,
+            output: TEXT_OUTPUT,
+            async execute(args, exec) {
+                return { text: await runDownload(service, readScopeArgs(args), exec.agent?.id) };
+            },
+        },
+        {
+            name: 'literature_zotero',
+            description: '在用户要求「把这批文献存入 Zotero / 存到『综述』目录 / 把当前页的文献同步到 Zotero / 把 xx 分组的文献存进 Zotero」时调用：把范围算成一份已校验的 paperId 清单，下发给右侧栏，右侧栏复用「存入 Zotero」弹窗逐篇同步，用户能看到每篇标题、来源与实时状态，也能中途取消。' +
+                '【目录怎么选】用户点名了目标目录（如「综述」「C15」）→ 填 collection，宿主会在本机 Zotero 目录列表里精确匹配，唯一命中时弹窗自动选中该目录并立即开始同步；没点名 → 省略 collection，弹窗加载好文献和目录后由用户自己选目录再点「同步」（与手动操作完全一致）；匹配失败或有歧义、Zotero 没开、同步在设置里关闭时，本工具不下发指令并返回原因与可用目录清单，此时请在对话里向用户确认目录或请其检查 Zotero，绝不猜一个目录就写入。也可以先主动问一句「要存到哪个目录」，但不要把它当成必经步骤。' +
+                '【范围怎么选】与 literature_download 完全相同的 7 种 scope 和筛选字段：用户点名具体文献且你已在工具结果的「paperId:」行看到确切 id → scope=ids + paperIds；「当前页」→ currentPage；「第 2 页 / 第 4–5 页」→ scope=pages + pages（1-based，面板上那一页）；「当前全部」→ currentView（含跨页，不等于整个任务）；「整个任务」→ all；「xx 分组」→ scope=group + groupId；给了年份、OA、关键词、筛读状态等条件 → scope=filters 并填对应字段。你看不到右侧栏界面，「当前页 / 第 N 页 / 当前筛选全部」由宿主用面板上报的视图快照 + 服务端筛选精确计算，不要自己猜页码或编造 paperId；面板每页恒为 20 条，与任务条件的「每源条数」不是一回事。范围不确定时先调 literature_scope 预演，再同步。' +
+                '同步会在 Zotero 里新建条目、不会覆盖已有条目，也不要跳过「已同步」的文献；目录只读时只存条目、不带 PDF 附件。本工具只下发指令、不等同步完成，也不要重复调用同一条指令或臆测同步结果；范围为空会返回原因而不下发。需要检索后再同步时，先按检索工具的轮次约束完成检索，再由用户明确提出同步。',
+            parameters: ZOTERO_PARAMETERS,
+            output: TEXT_OUTPUT,
+            async execute(args, exec) {
+                return { text: await runZotero(service, readZoteroArgs(args), exec.agent?.id) };
+            },
+        },
     ];
 }
 /** 把模型给的参数收窄成建任务输入；非法输入抛错给模型看。 */
@@ -560,6 +778,36 @@ function readTaskArgs(args) {
     const q = readText(record['q'], 'q');
     if (q !== undefined)
         input.q = q;
+    // get 的筛选字段与下载工具同口径，复用同一个校验函数，避免两套白名单。
+    const filter = readScopeFilter(record);
+    if (filter.hasPdf === true)
+        input.hasPdf = true;
+    if (filter.missingFullText === true)
+        input.missingFullText = true;
+    if (filter.pdfStatus !== undefined)
+        input.pdfStatus = filter.pdfStatus;
+    if (filter.yearFrom !== undefined)
+        input.yearFrom = filter.yearFrom;
+    if (filter.yearTo !== undefined)
+        input.yearTo = filter.yearTo;
+    if (filter.source !== undefined)
+        input.source = filter.source;
+    if (filter.type !== undefined)
+        input.type = filter.type;
+    if (filter.language !== undefined)
+        input.language = filter.language;
+    if (filter.venue !== undefined)
+        input.venue = filter.venue;
+    if (filter.author !== undefined)
+        input.author = filter.author;
+    if (filter.newOnly === true)
+        input.newOnly = true;
+    const fields = record['fields'];
+    if (fields !== undefined) {
+        if (fields !== 'full' && fields !== 'ids')
+            throw new Error('fields 只能是 full / ids');
+        input.fields = fields;
+    }
     const scope = record['scope'];
     if (scope !== undefined) {
         if (scope !== 'task' && scope !== 'filtered') {
@@ -728,11 +976,168 @@ function readExportArgs(args) {
         input.queryId = queryId;
     return input;
 }
+/**
+ * 模型范围参数边界校验：枚举白名单、严格布尔、paperIds 去空去重且保序。
+ * 下载 / Zotero 同步 / 范围预演共用；`reason` 只有真正下发指令时才必填。
+ */
+function readScopeArgs(args, requireReason = true) {
+    const record = asRecord(args);
+    const scope = record['scope'];
+    if (typeof scope !== 'string' || !DOWNLOAD_SCOPES.includes(scope)) {
+        throw new Error(`scope 只能是 ${DOWNLOAD_SCOPES.join(' / ')}`);
+    }
+    const reason = readText(record['reason'], 'reason');
+    if (requireReason && reason === undefined) {
+        throw new Error('缺少 reason：请用一句话复述用户要处理的范围');
+    }
+    const input = {
+        scope: scope,
+        reason: (reason ?? '').slice(0, 200),
+        filter: {},
+    };
+    const taskId = readText(record['taskId'], 'taskId');
+    if (taskId !== undefined)
+        input.taskId = taskId;
+    if (record['paperIds'] !== undefined) {
+        const papers = record['paperIds'];
+        if (!Array.isArray(papers) || !papers.every((item) => typeof item === 'string')) {
+            throw new Error('paperIds 必须是字符串数组');
+        }
+        if (papers.length > 1500)
+            throw new Error('paperIds 最多 1500 条');
+        input.paperIds = [
+            ...new Set(papers.map((id) => id.trim()).filter((id) => id !== '')),
+        ];
+    }
+    if (input.scope === 'ids' && (input.paperIds ?? []).length === 0) {
+        throw new Error('scope=ids 必须给出 paperIds，且只能使用工具结果里出现过的 paperId');
+    }
+    if (record['pages'] !== undefined) {
+        const pages = record['pages'];
+        if (!Array.isArray(pages) || pages.length === 0) {
+            throw new Error('pages 必须是非空的页码数组，例如 [2] 或 [4,5]');
+        }
+        if (pages.length > 20)
+            throw new Error('pages 最多 20 个页码');
+        const parsed = [];
+        for (const value of pages) {
+            if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 500) {
+                throw new Error('pages 里只能是 1–500 的整数页码');
+            }
+            parsed.push(value);
+        }
+        input.pages = [...new Set(parsed)].sort((a, b) => a - b);
+    }
+    if (input.scope === 'pages' && (input.pages ?? []).length === 0) {
+        throw new Error('scope=pages 必须给出 pages（1-based 页码，如 [2] 或 [4,5]）');
+    }
+    if (input.scope !== 'pages' && input.pages !== undefined) {
+        throw new Error('pages 只能与 scope=pages 一起使用；「当前页」请用 scope=currentPage');
+    }
+    const pageBase = record['pageBase'];
+    if (pageBase !== undefined) {
+        if (typeof pageBase !== 'string' || !PAGE_BASES.includes(pageBase)) {
+            throw new Error(`pageBase 只能是 ${PAGE_BASES.join(' / ')}`);
+        }
+        input.pageBase = pageBase;
+    }
+    const filter = readScopeFilter(record);
+    if (input.scope === 'group' && filter.groupId === undefined) {
+        throw new Error('scope=group 必须给出 groupId');
+    }
+    input.filter = filter;
+    return input;
+}
+/**
+ * 把 `ResultsQuery` / `PaperFilter` 同名键收窄成 `PaperFilter`。
+ *
+ * `literature_task get` 与下载工具共用这一份白名单：任何键只在这里识别一次，
+ * 模型在「读」和「下」两侧看到的筛选口径就不会分叉。
+ */
+function readScopeFilter(record) {
+    const filter = {};
+    const q = readText(record['q'], 'q');
+    if (q !== undefined)
+        filter.q = q.slice(0, 200);
+    const groupId = readText(record['groupId'], 'groupId');
+    if (groupId !== undefined)
+        filter.groupId = groupId;
+    const queryId = readText(record['queryId'], 'queryId');
+    if (queryId !== undefined)
+        filter.queryId = queryId;
+    const type = readText(record['type'], 'type');
+    if (type !== undefined)
+        filter.type = type.slice(0, 100);
+    const venue = readText(record['venue'], 'venue');
+    if (venue !== undefined)
+        filter.venue = venue.slice(0, 200);
+    const author = readText(record['author'], 'author');
+    if (author !== undefined)
+        filter.author = author.slice(0, 200);
+    const yearFrom = readInteger(record['yearFrom'], 'yearFrom', 3000);
+    if (yearFrom !== undefined)
+        filter.yearFrom = yearFrom;
+    const yearTo = readInteger(record['yearTo'], 'yearTo', 3000);
+    if (yearTo !== undefined)
+        filter.yearTo = yearTo;
+    if (yearFrom !== undefined && yearTo !== undefined && yearFrom > yearTo) {
+        throw new Error('yearFrom 不能大于 yearTo');
+    }
+    for (const key of ['openAccessOnly', 'hasPdf', 'missingFullText', 'newOnly']) {
+        const value = record[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'boolean')
+            throw new Error(`${key} 必须是布尔值`);
+        if (value)
+            filter[key] = true;
+    }
+    const source = record['source'];
+    if (source !== undefined) {
+        if (typeof source !== 'string' || !SOURCE_IDS.includes(source)) {
+            throw new Error(`source 只能是 ${SOURCE_IDS.join(' / ')}`);
+        }
+        filter.source = source;
+    }
+    const language = record['language'];
+    if (language !== undefined) {
+        if (typeof language !== 'string' || !LANGUAGES.includes(language)) {
+            throw new Error('language 不是支持的语言码');
+        }
+        filter.language = language;
+    }
+    const screening = record['screening'];
+    if (screening !== undefined) {
+        if (typeof screening !== 'string' || !SCREENINGS.includes(screening)) {
+            throw new Error(`screening 只能是 ${SCREENINGS.join(' / ')}`);
+        }
+        filter.screening = screening;
+    }
+    const pdfStatus = record['pdfStatus'];
+    if (pdfStatus !== undefined) {
+        if (typeof pdfStatus !== 'string' || !PDF_STATUSES.includes(pdfStatus)) {
+            throw new Error(`pdfStatus 只能是 ${PDF_STATUSES.join(' / ')}`);
+        }
+        filter.pdfStatus = pdfStatus;
+    }
+    return filter;
+}
+/** Zotero 额外接受一个自由文本的目录名 / id；空串当作没指定。 */
+function readZoteroArgs(args) {
+    const base = readScopeArgs(args);
+    const collection = readText(asRecord(args)['collection'], 'collection');
+    if (collection === undefined)
+        return base;
+    return { ...base, collection: collection.slice(0, 120) };
+}
 async function runTaskAction(service, args, signal, sessionId) {
     switch (args.action) {
         case 'current': {
             const task = await service.currentTask();
-            return formatCurrentTask(task);
+            if (task === undefined)
+                return formatCurrentTask(undefined);
+            const snapshot = await service.getViewSnapshot(sessionId, task.id);
+            return formatCurrentTask(task, describeView(snapshot, snapshot?.total ?? task.result.papers.length));
         }
         case 'list': {
             const tasks = await service.list();
@@ -744,10 +1149,14 @@ async function runTaskAction(service, args, signal, sessionId) {
             const detail = await service.getDetail(id);
             const page = await service.results(id, {
                 ...readFilterArgs(args),
-                limit: args.limit ?? 30,
+                limit: args.fields === 'ids' ? Math.min(args.limit ?? IDS_LIMIT, IDS_LIMIT) : (args.limit ?? 30),
                 offset: args.offset ?? 0,
             });
-            return formatTaskDetail(detail, page, task.states, task.groups);
+            const snapshot = await service.getViewSnapshot(sessionId, id);
+            const view = describeView(snapshot, page.total);
+            if (args.fields === 'ids')
+                return formatPaperIds(task, page, view);
+            return formatTaskDetail(detail, page, task.states, task.groups, undefined, view);
         }
         case 'update': {
             const task = await service.update(requireId(args), args.patch ?? {});
@@ -810,6 +1219,346 @@ async function runExport(service, args) {
         preview,
     ].join('\n');
 }
+/** 按界面排序原地排好并返回同一数组，便于内联到 `filterPapers` 的结果上。 */
+function sortPapersInPlace(papers, sort) {
+    sortPapers(papers, sort);
+    return papers;
+}
+async function resolveModelScope(service, args, sessionId, verb) {
+    const task = args.taskId !== undefined ? await service.get(args.taskId) : await service.currentTask();
+    if (task === undefined) {
+        return {
+            ok: false,
+            text: `当前没有检索任务：请先检索文献，或让用户从右侧栏打开一个任务，再让我${verb}。`,
+        };
+    }
+    const snapshot = await service.getViewSnapshot(sessionId, task.id);
+    const needsView = args.scope === 'currentPage' || args.scope === 'currentView' || args.scope === 'pages';
+    if (needsView && snapshot === undefined) {
+        return {
+            ok: false,
+            text: [
+                `任务「${task.title}」（id: ${task.id}）暂时读不到右侧栏的当前视图，无法准确判断「当前页 / 第 N 页 / 当前全部」。`,
+                args.scope === 'pages'
+                    ? '页码是按面板的筛选、排序与每页 20 条切出来的，缺视图快照就无法换算成同一批文献。'
+                    : '',
+                '请让用户先在右侧栏打开该任务的结果页、翻到要看的那一页，再重复这条指令；也可以改用 scope=all 处理整个任务、用 filters 给明确条件、用 ids 指定文献。',
+                `本次没有下发任何${verb}指令。`,
+            ]
+                .filter((line) => line !== '')
+                .join('\n'),
+        };
+    }
+    // 「当前页 / 第 N 页 / 当前全部」以界面筛选打底；其余范围忽略界面筛选，避免
+    // 用户说「把全部文献存进去」时却只处理了筛出来的那批。
+    const viewFilter = needsView ? toPaperFilter(snapshot?.filters ?? {}) : {};
+    const filter = await service.resolveDownloadFilter(task.id, mergeDownloadFilter(viewFilter, args.filter));
+    // 页码切片的基准必须与界面完全一致：排序取快照（缺省回落任务排序），
+    // 且由这一层先排好再交给纯函数切页 —— 下载解析层不引运行时依赖。
+    const sort = snapshot?.sort ?? task.conditions.sort;
+    const viewMatched = args.scope === 'pages' && (args.pageBase ?? 'view') === 'view'
+        ? sortPapersInPlace(filterPapers(task, await service.resolveDownloadFilter(task.id, viewFilter)), sort)
+        : undefined;
+    // 当前页优先用面板直接上报的顺序；缺 paperIds 时按视图筛选与排序重算这一页。
+    let pagePaperIds;
+    if (args.scope === 'currentPage' && snapshot !== undefined) {
+        if (snapshot.pagePaperIds.length > 0) {
+            pagePaperIds = snapshot.pagePaperIds;
+        }
+        else {
+            const page = await service.results(task.id, {
+                ...viewFilter,
+                ...(snapshot.sort === undefined ? {} : { sort: snapshot.sort }),
+                offset: snapshot.pageIndex * snapshot.pageSize,
+                limit: snapshot.pageSize,
+            });
+            pagePaperIds = page.papers.map((paper) => paper.paperId);
+        }
+    }
+    const groupName = args.scope === 'group' && args.filter.groupId !== undefined
+        ? task.groups.find((group) => group.id === args.filter.groupId)?.name
+        : undefined;
+    const matched = args.scope === 'pages'
+        ? sortPapersInPlace(filterPapers(task, filter), sort)
+        : filterPapers(task, filter);
+    const resolved = resolveDownloadScope(task, {
+        scope: args.scope,
+        filter,
+        matched,
+        ...(args.paperIds === undefined ? {} : { explicitIds: args.paperIds }),
+        ...(args.pages === undefined ? {} : { pages: args.pages }),
+        ...(args.pageBase === undefined ? {} : { pageBase: args.pageBase }),
+        ...(snapshot === undefined ? {} : { snapshot }),
+        ...(snapshot === undefined ? {} : { pageSize: snapshot.pageSize }),
+        ...(viewMatched === undefined ? {} : { viewMatched }),
+        ...(pagePaperIds === undefined ? {} : { pagePaperIds }),
+        ...(groupName === undefined ? {} : { groupName }),
+    });
+    if (resolved.outOfRange !== undefined && resolved.outOfRange.length > 0) {
+        const size = snapshot?.pageSize ?? RESULT_PAGE_SIZE;
+        return {
+            ok: false,
+            text: [
+                `第 ${describePages(resolved.outOfRange)} 页超出范围：该任务在当前筛选与排序下共 ${resolved.pageCount} 页（每页 ${size} 条）。`,
+                '请让用户确认页码，或先用 literature_scope 预演一次看清单前几篇；不要自行改动页码后重复下发。',
+                `本次没有下发任何${verb}指令。`,
+            ].join('\n'),
+        };
+    }
+    if (resolved.paperIds.length === 0) {
+        return {
+            ok: false,
+            text: [
+                `没有匹配到可${verb}的文献（${resolved.scopeLabel}）。`,
+                `任务「${task.title}」共 ${task.result.papers.length} 篇；本次没有下发任何${verb}指令。`,
+                '请放宽条件、确认页码/分组/年份是否正确，或改用 scope=all；不要重复下发同一条指令。',
+            ].join('\n'),
+        };
+    }
+    return {
+        ok: true,
+        task,
+        resolved,
+        matchedTotal: matched.length,
+        ...(snapshot === undefined ? {} : { snapshot }),
+    };
+}
+/** 面板筛选的键名 → 中文短标签；键名沿用 `ResultsQuery`。 */
+const SNAPSHOT_FILTER_LABELS = {
+    q: '关键词',
+    source: '来源',
+    queryId: '检索式',
+    type: '类型',
+    venue: '出处',
+    author: '作者',
+    openAccessOnly: '仅开放获取',
+    hasPdf: '仅含 PDF',
+    missingFullText: '缺全文',
+    newOnly: '仅新增',
+    screening: '筛读',
+    language: '语言',
+    pdfStatus: '全文状态',
+    groupId: '分组',
+    sort: '排序',
+};
+function describeSnapshotFilters(filters) {
+    const parts = [];
+    if (filters['yearFrom'] !== undefined || filters['yearTo'] !== undefined) {
+        parts.push(`${filters['yearFrom'] ?? '不限'}–${filters['yearTo'] ?? '不限'} 年`);
+    }
+    for (const [key, value] of Object.entries(filters)) {
+        if (key === 'yearFrom' || key === 'yearTo')
+            continue;
+        const label = SNAPSHOT_FILTER_LABELS[key];
+        if (label === undefined)
+            continue;
+        parts.push(`${label} ${String(value)}`);
+    }
+    return parts.join('、');
+}
+/**
+ * 「你现在看到的是哪一页」——模型判断页码的唯一依据。
+ *
+ * 面板每页条数、排序、筛选都由视图快照决定；没有快照就不猜，直接不输出，
+ * 让 `scope=pages` 走失败分支而不是悄悄按错误的基准切页。
+ */
+function describeView(snapshot, total) {
+    if (snapshot === undefined)
+        return [];
+    const size = Math.max(1, snapshot.pageSize);
+    const count = total ?? snapshot.total;
+    const pageCount = count === undefined ? undefined : Math.max(1, Math.ceil(count / size));
+    const parts = [
+        `第 ${snapshot.pageIndex + 1}${pageCount === undefined ? '' : `/${pageCount}`} 页`,
+        `每页 ${size} 条`,
+    ];
+    if (count !== undefined)
+        parts.push(`共 ${count} 篇`);
+    const filters = describeSnapshotFilters(snapshot.filters);
+    if (filters !== '')
+        parts.push(`筛选：${filters}`);
+    return [`面板视图：${parts.join('｜')}`];
+}
+/**
+ * 只读预演：把范围算一遍给模型看，**不下发任何指令**。
+ *
+ * 存在的意义是替掉「模型自己翻页 / 自己搬 paperId」：页码换算、页内再筛、
+ * 越界判断都在这里一次算清，模型只需要核对命中数与标题，再把同一套参数
+ * 原样交给下载 / 同步工具。
+ */
+async function runScopePreview(service, args, sessionId) {
+    const scope = await resolveModelScope(service, args, sessionId, '处理');
+    if (!scope.ok)
+        return scope.text;
+    const { task, resolved, matchedTotal, snapshot } = scope;
+    const size = Math.max(1, snapshot?.pageSize ?? RESULT_PAGE_SIZE);
+    const pageCount = resolved.pageCount ?? Math.max(1, Math.ceil(matchedTotal / size));
+    const byId = new Map(task.result.papers.map((paper) => [paper.paperId, paper]));
+    const preview = resolved.paperIds.slice(0, 10);
+    // 页窗口按视图切页时，总篇数用面板上报的视图总数；否则用本次筛选命中的篇数。
+    const pageMode = args.scope === 'pages';
+    const totalHint = pageMode && (args.pageBase ?? 'view') === 'view' ? undefined : matchedTotal;
+    const lines = [
+        '范围预演（只读，未下发任何指令）：',
+        `任务：${task.title}（id: ${task.id}）`,
+        `范围：${resolved.scopeLabel}`,
+        ...describeView(snapshot, totalHint),
+        pageMode
+            ? `页窗口：第 ${describePages(args.pages ?? [])} 页（每页 ${size} 条，共 ${pageCount} 页）→ 与附加条件取交集后 ${resolved.paperIds.length} 篇；附加条件在全任务命中 ${matchedTotal} 篇。`
+            : `命中：该条件下共 ${matchedTotal} 篇（每页 ${size} 条 ≈ ${pageCount} 页）→ 本次范围 ${resolved.paperIds.length} 篇。`,
+        '',
+        `清单前 ${preview.length} 篇：`,
+    ];
+    preview.forEach((paperId, index) => {
+        const paper = byId.get(paperId);
+        const pdf = paper !== undefined && (paper.pdfUrl !== '' || pdfStatusOf(task, paper) === 'downloaded');
+        lines.push(`${index + 1}. ${paper?.title ?? paperId}｜paperId: ${paperId}｜${pdf ? '有 PDF' : '无 PDF 直链'}`);
+    });
+    if (resolved.paperIds.length > preview.length) {
+        lines.push(`… 还有 ${resolved.paperIds.length - preview.length} 篇，执行时会按同一范围一起处理。`);
+    }
+    lines.push('', '确认无误后，把同一套参数（scope / pages / pageBase / 筛选字段）原样传给 literature_download 或 literature_zotero 即可；不要改用 ids 把 paperId 抄一遍，也不要自己按 offset 推算页码。');
+    return lines.join('\n');
+}
+/** 清单前几篇的预览，供模型核对范围有没有选错。 */
+function previewItems(resolved) {
+    return resolved.items
+        .slice(0, 5)
+        .map((item, index) => `${index + 1}. ${item.title}（${item.source}）`)
+        .join('\n');
+}
+/**
+ * 「少掉的那些」怎么解释。
+ *
+ * `scope=pages` 的差额是页内不满足附加条件的文献（例如第 2 页 20 条里只有
+ * 10 条有 PDF），属于预期行为，不能写成「id 被忽略」——否则模型会以为页码
+ * 或 id 填错了。
+ */
+function ignoredNote(resolved, scope) {
+    if (resolved.ignored <= 0)
+        return '';
+    return scope === 'pages'
+        ? `，页内另有 ${resolved.ignored} 篇不满足附加条件已跳过`
+        : `，另有 ${resolved.ignored} 个 id 被忽略（不属于该任务或不满足条件）`;
+}
+/**
+ * 把自然语言下载请求算成已校验清单并下发指令。
+ *
+ * 只等服务端把范围算完（毫秒级），不等右侧栏下载完成：下载由 Client 复用
+ * 现有批量下载弹窗执行，模型拿到的只是「已受理」的说明。
+ */
+async function runDownload(service, args, sessionId) {
+    const scope = await resolveModelScope(service, args, sessionId, '下载');
+    if (!scope.ok)
+        return scope.text;
+    const { task, resolved } = scope;
+    const command = {
+        commandId: randomUUID(),
+        taskId: task.id,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        at: Date.now(),
+        origin: 'model',
+        reason: args.reason,
+        scopeLabel: resolved.scopeLabel,
+        paperIds: resolved.paperIds,
+        items: resolved.items,
+    };
+    // 先请求打开任务 tab，再下发指令；两者在同一次 /events 增量里送到客户端，
+    // 面板即使原本没挂载也能被拉起后再消费指令。
+    service.focusTask(task.id, task.title, sessionId);
+    service.publishDownloadCommand(command);
+    const lines = [
+        `已向右侧栏下发批量下载指令：${resolved.scopeLabel}。`,
+        `任务「${task.title}」（id: ${task.id}）；范围：${args.reason}`,
+        `清单已逐个校验：${resolved.paperIds.length} 篇属于该任务且满足条件${ignoredNote(resolved, args.scope)}。`,
+        '',
+        '清单前几篇：',
+        previewItems(resolved),
+        '',
+        '右侧栏会自动弹出批量下载框并立即开始，用户能看到每篇标题、来源与实时状态，也可点「取消下载」中止。本工具只下发指令、不等待下载完成；请勿重复调用，也不要替用户臆测下载结果。',
+    ];
+    if (resolved.paperIds.length > 200) {
+        lines.push('', `注意：本次 ${resolved.paperIds.length} 篇数量较大，可能耗时较长并触发上游限流；已下载的会跳过，建议提示用户必要时收窄范围。`);
+    }
+    return lines.join('\n');
+}
+/**
+ * 与下载共用范围解析，改由右侧栏复用 Zotero 同步弹窗执行。
+ *
+ * 唯一多出来的一步是目录：点名了目录就先在本机 Zotero 目录列表里精确匹配，
+ * 只有唯一命中才带上 `autoStart` 自动开跑；匹配失败 / 歧义 / Zotero 不可用
+ * 一律不下发，避免往错误的分类里写入数据。
+ */
+async function runZotero(service, args, sessionId) {
+    if (!getSettings().zoteroEnabled) {
+        return [
+            'Zotero 同步已在设置中关闭：请让用户先在插件设置里开启「Zotero 同步」再试。',
+            '本次没有下发任何同步指令。',
+        ].join('\n');
+    }
+    const scope = await resolveModelScope(service, args, sessionId, '同步');
+    if (!scope.ok)
+        return scope.text;
+    const { task, resolved } = scope;
+    const targetsResult = await service.zoteroTargets();
+    if (!targetsResult.ok || targetsResult.targets.length === 0) {
+        return [
+            `读取本机 Zotero 目录失败：${targetsResult.error ?? 'Zotero 里没有可用目录'}`,
+            '请让用户启动 Zotero 桌面端、确认允许其他应用与本机通信，并在 Zotero 里准备好可写入的分类后重试。',
+            '本次没有下发任何同步指令（不会在未经确认的情况下写入「我的文库」）。',
+        ].join('\n');
+    }
+    let target;
+    if (args.collection !== undefined) {
+        const match = matchZoteroTarget(targetsResult.targets, args.collection);
+        if (match.kind !== 'matched') {
+            const head = match.kind === 'ambiguous'
+                ? `「${args.collection}」在 Zotero 里匹配到多个目录，无法确定目标：`
+                : `在 Zotero 里没有找到目录「${args.collection}」。可用目录：`;
+            return [
+                head,
+                describeZoteroTargets(match.candidates),
+                '',
+                '请在对话里让用户确认要存到哪个目录，再重新调用本工具并填 collection；也可以不填 collection，让用户直接在右侧同步弹窗里选目录。',
+                '本次没有下发任何同步指令。',
+            ].join('\n');
+        }
+        target = match.target;
+    }
+    const command = {
+        commandId: randomUUID(),
+        taskId: task.id,
+        ...(sessionId === undefined ? {} : { sessionId }),
+        at: Date.now(),
+        origin: 'model',
+        reason: args.reason,
+        scopeLabel: resolved.scopeLabel,
+        paperIds: resolved.paperIds,
+        items: resolved.items,
+        ...(target === undefined ? {} : { target }),
+        autoStart: target !== undefined,
+    };
+    service.focusTask(task.id, task.title, sessionId);
+    service.publishZoteroCommand(command);
+    const targetLine = target === undefined
+        ? '未在指令里指定目录：右侧栏会弹出「存入 Zotero」框并加载好文献与目录，请用户自己选目录再点「同步」。'
+        : `已按指令选中目录「${target.name}」（id: ${target.id}）${target.filesEditable === false ? '，该目录不可写附件，只会保存条目' : ''}：右侧栏会自动预选并立即开始同步。`;
+    const lines = [
+        `已向右侧栏下发批量存入 Zotero 指令：${resolved.scopeLabel}。`,
+        `任务「${task.title}」（id: ${task.id}）；范围：${args.reason}`,
+        `清单已逐个校验：${resolved.paperIds.length} 篇属于该任务且满足条件${ignoredNote(resolved, args.scope)}。`,
+        '',
+        '清单前几篇：',
+        previewItems(resolved),
+        '',
+        targetLine,
+        '用户能在弹窗里看到每篇标题、来源与实时状态，也可中途取消；重新同步会在 Zotero 里新建条目，不会覆盖已有条目。本工具只下发指令、不等同步完成；请勿重复调用，也不要替用户臆测同步结果。',
+    ];
+    if (resolved.paperIds.length > 200) {
+        lines.push('', `注意：本次 ${resolved.paperIds.length} 篇数量较大，可能耗时较长；建议提示用户必要时收窄范围。`);
+    }
+    return lines.join('\n');
+}
 function readFilterArgs(args) {
     const filter = {};
     if (args.screening !== undefined)
@@ -820,6 +1569,28 @@ function readFilterArgs(args) {
         filter.queryId = args.queryId;
     if (args.q !== undefined && args.q.trim() !== '')
         filter.q = args.q.trim();
+    if (args.hasPdf === true)
+        filter.hasPdf = true;
+    if (args.missingFullText === true)
+        filter.missingFullText = true;
+    if (args.pdfStatus !== undefined)
+        filter.pdfStatus = args.pdfStatus;
+    if (args.yearFrom !== undefined)
+        filter.yearFrom = args.yearFrom;
+    if (args.yearTo !== undefined)
+        filter.yearTo = args.yearTo;
+    if (args.source !== undefined)
+        filter.source = args.source;
+    if (args.type !== undefined)
+        filter.type = args.type;
+    if (args.language !== undefined)
+        filter.language = args.language;
+    if (args.venue !== undefined)
+        filter.venue = args.venue;
+    if (args.author !== undefined)
+        filter.author = args.author;
+    if (args.newOnly === true)
+        filter.newOnly = true;
     return filter;
 }
 function requireId(args) {
@@ -837,7 +1608,7 @@ function readText(value, name, allowEmpty = false) {
     return allowEmpty ? value : value.trim();
 }
 /** 「当前任务」的轻量快照：模型在执行检索/任务操作前先确认这个对话正在用哪个任务。 */
-function formatCurrentTask(task) {
+function formatCurrentTask(task, view = []) {
     if (task === undefined) {
         return [
             '当前没有任务：这个对话还没有任何检索任务。',
@@ -851,6 +1622,7 @@ function formatCurrentTask(task) {
     const lines = [
         `当前任务：${task.title}（id: ${task.id}）`,
         `状态：${statusLabel(task.status)}${task.error === undefined ? '' : `（${task.error}）`}`,
+        ...view,
         `检索轮次：共 ${task.rounds.length} 轮${last === undefined
             ? ''
             : `｜最近一轮 ${last.createdAt.slice(0, 19).replace('T', ' ')}（${last.origin === 'model' ? '模型' : '面板'}）`}`,
@@ -872,7 +1644,7 @@ function formatTaskList(tasks, limit) {
     }
     return lines.join('\n');
 }
-function formatTaskDetail(detail, page, states, groups, outcome) {
+function formatTaskDetail(detail, page, states, groups, outcome, view = []) {
     const lines = [`任务：${detail.title}（id: ${detail.id}，rev=${detail.rev}）`];
     lines.push(outcome === 'timeout'
         ? '状态：仍在检索中，已先返回当前结果；任务会继续在右侧栏完成。'
@@ -887,6 +1659,8 @@ function formatTaskDetail(detail, page, states, groups, outcome) {
     }
     const screening = detail.stats.screening;
     lines.push(`漏斗：原始 ${detail.stats.rawHits}｜去重 ${detail.stats.deduped}｜已加载 ${detail.result.totalLoaded}｜纳入 ${screening.included}、排除 ${screening.excluded}、待读 ${screening.unread}、已读 ${screening.read}`);
+    if (view.length > 0)
+        lines.push(...view);
     if (groups.length > 0) {
         const usage = new Map();
         for (const state of Object.values(states)) {
@@ -915,6 +1689,8 @@ function formatTaskDetail(detail, page, states, groups, outcome) {
             paper.citedBy === null ? '' : `被引 ${paper.citedBy}`,
         ].filter((part) => part !== '');
         lines.push(`${page.offset + index + 1}. [${marks.join('|')}] ${paper.title}`);
+        // 供 literature_download 的 scope=ids 引用；模型不得编造这个 id。
+        lines.push(`   paperId: ${paper.paperId}`);
         if (meta.length > 0)
             lines.push(`   ${meta.join(' | ')}`);
         if (paper.abstract !== '')
@@ -925,6 +1701,27 @@ function formatTaskDetail(detail, page, states, groups, outcome) {
     }
     return lines.join('\n');
 }
+/**
+ * `fields=ids`：一行一篇的紧凑清单。
+ *
+ * 只给「序号｜paperId｜标题｜有无 PDF」，方便模型核对范围或向用户复述篇数；
+ * 需要摘要时用默认的 full 模式。一次最多 `IDS_LIMIT` 条，超出用 offset 续读。
+ */
+function formatPaperIds(task, page, view) {
+    const lines = [
+        `结果清单（ids 模式）：筛选后共 ${page.total} 篇，以下第 ${page.offset + 1}–${page.offset + page.papers.length} 篇`,
+        ...view,
+        '',
+    ];
+    page.papers.forEach((paper, index) => {
+        const pdf = paper.pdfUrl !== '' || pdfStatusOf(task, paper) === 'downloaded';
+        lines.push(`${page.offset + index + 1}. ${paper.paperId}｜${truncate(paper.title, 120)}｜${pdf ? '有PDF' : '无PDF'}`);
+    });
+    if (page.total > page.offset + page.papers.length) {
+        lines.push('', `还有 ${page.total - page.offset - page.papers.length} 篇；用 offset 继续读，或直接用 scope=pages 让宿主按页取（不必搬 id）。`);
+    }
+    return lines.join('\n');
+}
 function formatCompare(report) {
     const { counts } = report;
     const lines = [
@@ -1048,6 +1845,8 @@ function formatTaskResult(detail, page, outcome, reused) {
     page.papers.forEach((paper, index) => {
         lines.push('');
         lines.push(`${index + 1}. ${paper.title}`);
+        // 供 literature_download 的 scope=ids 引用；模型不得编造这个 id。
+        lines.push(`   paperId: ${paper.paperId}`);
         const meta = [
             paper.authors.slice(0, 6).join(', '),
             paper.year === null ? '' : String(paper.year),