dsh-cite 0.3.0 → 0.3.2

package/README.en.md

@@ -1,8 +1,10 @@
 # dsh-cite
 
+![npm](https://img.shields.io/npm/v/dsh-cite) ![downloads](https://img.shields.io/npm/dm/dsh-cite) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-cite) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-cite?style=social)
+
 > Give it a DOI, get a proper citation — GB/T 7714 / APA / MLA / Chicago / BibTeX.
 
-A DeepSeek Harness plugin for bibliographic references: query Crossref and format citations. Four tools, zero runtime dependencies.
+A DeepSeek Harness plugin for bibliographic references: query Crossref and format citations. Five tools (including the `cite_health` self-check), zero runtime dependencies.
 
 ## Tools
 
@@ -12,10 +14,11 @@ A DeepSeek Harness plugin for bibliographic references: query Crossref and forma
 | `cite_format` | Generate a formatted citation | `doi`; `style`: gb-t-7714 / apa / mla / chicago |
 | `cite_bibtex` | Generate a BibTeX entry | `doi`; `key` optional |
 | `cite_check` | Extract DOIs from text and validate them | `text`; `maxChecks` 1-50, default 10 |
+| `cite_health` | Self-check: probe Crossref connectivity and report latency | none |
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified against `@deepseek-ai/dsh@0.1.2-alpha.2` on 2026-08-31. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Install
 
@@ -23,8 +26,6 @@ Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cord
 dsh plugin --profile web add dsh-cite
 ```
 
-MIT
-
 ## Uninstall
 
 ```bash

package/README.md

@@ -1,8 +1,10 @@
 # dsh-cite
 
+![npm](https://img.shields.io/npm/v/dsh-cite) ![downloads](https://img.shields.io/npm/dm/dsh-cite) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-cite) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-cite?style=social)
+
 > 给一个 DOI，还你规范参考文献——GB/T 7714 / APA / MLA / Chicago / BibTeX。
 
-DeepSeek Harness 参考文献工具插件：通过 Crossref API 查询文献元数据并格式化引用。四个工具、零运行时依赖、全平台通用。
+DeepSeek Harness 参考文献工具插件：通过 Crossref API 查询文献元数据并格式化引用。五个工具（含 `cite_health` 自检）、零运行时依赖、全平台通用。
 
 ## 工具
 
@@ -12,10 +14,11 @@ DeepSeek Harness 参考文献工具插件：通过 Crossref API 查询文献元
 | `cite_format` | 生成规范引文 | `doi` 必填；`style`：gb-t-7714 / apa / mla / chicago |
 | `cite_bibtex` | 生成 BibTeX 条目 | `doi` 必填；`key` 可选 |
 | `cite_check` | 从文本提取 DOI 并并发校验是否存在（并发 3，保持输入顺序） | `text` 必填；`maxChecks` 1-50 默认 10 |
+| `cite_health` | 自检：探测 Crossref 连通性并报告延迟 | 无 |
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+在 `@deepseek-ai/dsh@0.1.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 

package/lib/config.d.ts

@@ -11,6 +11,7 @@ export interface ResolvedCiteConfig {
     timeoutMs: number;
     userAgent: string;
 }
+export declare const DEFAULT_USER_AGENT = "dsh-cite/0.3.2 (DeepSeek Harness citation plugin; mailto:STARDUSTLC666@users.noreply.github.com)";
 export declare const CITE_TIMEOUT_ENV = "DSH_CITE_TIMEOUT_MS";
 export declare const CITE_USER_AGENT_ENV = "DSH_CITE_USER_AGENT";
 export declare function resolveConfig(config: CiteConfig | undefined | null, env?: NodeJS.ProcessEnv): ResolvedCiteConfig;

package/lib/config.js

@@ -4,7 +4,7 @@
  * @module dsh-cite/config
  */
 const DEFAULT_TIMEOUT_MS = 15000;
-const DEFAULT_USER_AGENT = 'dsh-cite/0.2.0 (DeepSeek Harness citation plugin; mailto:STARDUSTLC666@users.noreply.github.com)';
+export const DEFAULT_USER_AGENT = 'dsh-cite/0.3.2 (DeepSeek Harness citation plugin; mailto:STARDUSTLC666@users.noreply.github.com)';
 export const CITE_TIMEOUT_ENV = 'DSH_CITE_TIMEOUT_MS';
 export const CITE_USER_AGENT_ENV = 'DSH_CITE_USER_AGENT';
 export function resolveConfig(config, env = process.env) {

package/lib/crossref.d.ts

@@ -30,8 +30,8 @@ export type FetchLike = (url: string, init?: {
 }) => Promise<Response>;
 export declare function assertDoi(value: string): string;
 /** 按 DOI 查询 Crossref 并归一化。 */
-export declare function lookupDoi(doi: string, cfg: ResolvedCiteConfig, fetchImpl?: FetchLike): Promise<Work>;
+export declare function lookupDoi(doi: string, cfg: ResolvedCiteConfig, fetchImpl?: FetchLike, signal?: AbortSignal): Promise<Work>;
 /** 按题录文本检索 Crossref，返回归一化结果。 */
-export declare function searchWorks(query: string, limit: number, cfg: ResolvedCiteConfig, fetchImpl?: FetchLike): Promise<Work[]>;
+export declare function searchWorks(query: string, limit: number, cfg: ResolvedCiteConfig, fetchImpl?: FetchLike, signal?: AbortSignal): Promise<Work[]>;
 /** 从任意文本里提取 DOI。 */
 export declare function extractDois(text: string): string[];

package/lib/crossref.js

@@ -6,7 +6,7 @@
 const CROSSREF_API = 'https://api.crossref.org/works/';
 const DOI_PATTERN = /^10\.\d{4,9}\/[-._;()/:A-Za-z0-9]+$/i;
 export function assertDoi(value) {
-    const doi = value.trim().replace(/^https?:\/\/doi\.org\//i, '').replace(/^doi:\s*/i, '');
+    const doi = value.trim().replace(/^https?:\/\/(dx\.)?doi\.org\//i, '').replace(/^doi:\s*/i, '');
     if (!DOI_PATTERN.test(doi))
         throw new Error('DOI 格式不正确：' + value + '（示例：10.1038/nature12345）。');
     return doi;
@@ -63,18 +63,23 @@ function normalizeWork(raw) {
 function makeHeaders(cfg) {
     return { 'user-agent': cfg.userAgent, accept: 'application/json' };
 }
+function requestSignal(timeoutMs, signal) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    return signal === undefined ? timeoutSignal : AbortSignal.any([signal, timeoutSignal]);
+}
 /** 按 DOI 查询 Crossref 并归一化。 */
-export async function lookupDoi(doi, cfg, fetchImpl) {
+export async function lookupDoi(doi, cfg, fetchImpl, signal) {
     const clean = assertDoi(doi);
     const fetcher = fetchImpl ?? globalThis.fetch;
     let response;
     try {
         response = await fetcher(CROSSREF_API + encodeURIComponent(clean), {
             headers: makeHeaders(cfg),
-            signal: AbortSignal.timeout(cfg.timeoutMs),
+            signal: requestSignal(cfg.timeoutMs, signal),
         });
     }
     catch (error) {
+        signal?.throwIfAborted();
         throw new Error('Crossref 请求失败：' + (error instanceof Error ? error.message : String(error)));
     }
     if (!response.ok) {
@@ -98,7 +103,7 @@ export async function lookupDoi(doi, cfg, fetchImpl) {
     return work;
 }
 /** 按题录文本检索 Crossref，返回归一化结果。 */
-export async function searchWorks(query, limit, cfg, fetchImpl) {
+export async function searchWorks(query, limit, cfg, fetchImpl, signal) {
     const q = query.trim();
     if (q === '')
         throw new Error('检索词不能为空。');
@@ -108,10 +113,11 @@ export async function searchWorks(query, limit, cfg, fetchImpl) {
     try {
         response = await fetcher(url, {
             headers: makeHeaders(cfg),
-            signal: AbortSignal.timeout(cfg.timeoutMs),
+            signal: requestSignal(cfg.timeoutMs, signal),
         });
     }
     catch (error) {
+        signal?.throwIfAborted();
         throw new Error('Crossref 检索失败：' + (error instanceof Error ? error.message : String(error)));
     }
     if (!response.ok)

package/lib/format.js

@@ -146,14 +146,15 @@ function buildApa(work) {
             text += '(' + work.issue + ')';
         if (work.page !== '')
             text += ', ' + work.page;
-        text += '. ';
-        text += work.doi !== '' ? 'https://doi.org/' + work.doi : work.url;
-        return text;
+        const tail = work.doi !== '' ? 'https://doi.org/' + work.doi : work.url;
+        if (tail !== '')
+            return text + '. ' + tail;
+        return text + '.';
     }
     if (work.type === 'book' || work.type === 'monograph' || work.type === 'edited-book') {
-        return authors + ' (' + year + '). ' + title + '. ' + (work.publisher !== '' ? work.publisher + '.' : '');
+        return authors + ' (' + year + '). ' + title + '.' + (work.publisher !== '' ? ' ' + work.publisher + '.' : '');
     }
-    return authors + ' (' + year + '). ' + title + '. ' + (work.url !== '' ? work.url : '');
+    return authors + ' (' + year + '). ' + title + '.' + (work.url !== '' ? ' ' + work.url : '');
 }
 /** 生成 MLA 9 参考文献条目。 */
 function buildMla(work) {
@@ -241,7 +242,7 @@ function bibtexType(work) {
 export function buildBibtex(work, key) {
     const first = work.authors[0];
     const firstWord = titleOf(work).split(/[^\p{L}\p{N}]+/u).find((part) => part !== '') ?? 'work';
-    const baseKey = key !== undefined && key.trim() !== '' ? sanitizeBibtexKey(key.trim()) : ((first?.family ?? first?.name ?? 'author') + yearText(work) + firstWord).toLowerCase();
+    const baseKey = key !== undefined && key.trim() !== '' ? sanitizeBibtexKey(key.trim()) : sanitizeBibtexKey(((first?.family || first?.name || 'author') + yearText(work) + firstWord).toLowerCase());
     const type = bibtexType(work);
     const fields = [];
     const authors = work.authors.map((author) => fullName(author)).join(' and ');

package/lib/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * dsh-cite —— 参考文献工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册四个面向模型的工具（cite_lookup / cite_format /
- * cite_bibtex / cite_check），通过 Crossref API 查询元数据并生成 GB/T 7714 / APA /
- * MLA / Chicago 引文。零运行时依赖。
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（cite_lookup / cite_format /
+ * cite_bibtex / cite_check / cite_health），通过 Crossref API 查询元数据并生成
+ * GB/T 7714 / APA / MLA / Chicago 引文。零运行时依赖。
  *
  * @module dsh-cite
  */
@@ -14,9 +14,7 @@ export declare const name = "cite";
 export declare const inject: string[];
 export interface CitePluginContext {
     tools: {
-        register(definition: CiteToolDefinition, options?: {
-            prepend?: boolean;
-        }): () => void;
+        register(definition: CiteToolDefinition): () => void;
     };
     on?(event: string, listener: () => void): () => void;
 }

package/lib/index.js

@@ -1,9 +1,9 @@
 /**
  * dsh-cite —— 参考文献工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册四个面向模型的工具（cite_lookup / cite_format /
- * cite_bibtex / cite_check），通过 Crossref API 查询元数据并生成 GB/T 7714 / APA /
- * MLA / Chicago 引文。零运行时依赖。
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（cite_lookup / cite_format /
+ * cite_bibtex / cite_check / cite_health），通过 Crossref API 查询元数据并生成
+ * GB/T 7714 / APA / MLA / Chicago 引文。零运行时依赖。
  *
  * @module dsh-cite
  */
@@ -23,7 +23,7 @@ export function apply(ctx, config) {
     }
     const disposers = [];
     for (const definition of buildCiteTools(cfg)) {
-        disposers.push(ctx.tools.register(definition, { prepend: true }));
+        disposers.push(ctx.tools.register(definition));
     }
     if (typeof ctx.on === 'function') {
         ctx.on('dispose', () => {

package/lib/tools.js

@@ -74,11 +74,12 @@ const checkSchema = {
     additionalProperties: true,
 };
 /** 以固定并发度执行异步任务并保持原顺序。 */
-async function mapWithConcurrency(items, concurrency, fn) {
+async function mapWithConcurrency(items, concurrency, fn, signal) {
     const results = new Array(items.length);
     let next = 0;
     const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
         while (true) {
+            signal?.throwIfAborted();
             const index = next;
             next += 1;
             if (index >= items.length)
@@ -89,6 +90,14 @@ async function mapWithConcurrency(items, concurrency, fn) {
     await Promise.all(workers);
     return results;
 }
+function executionSignal(exec) {
+    if (typeof exec !== 'object' || exec === null)
+        return undefined;
+    const signal = exec.signal;
+    return signal instanceof AbortSignal ? signal : undefined;
+}
+const CHECK_CONCURRENCY = 3;
+const MAX_CHECKS = 50;
 function workLabel(work) {
     const title = work.title !== '' ? work.title : '(无标题)';
     return title + '（' + (work.year > 0 ? work.year + ', ' : '') + (work.containerTitle !== '' ? work.containerTitle : work.publisher) + '）';
@@ -107,23 +116,23 @@ export function buildCiteTools(cfg, fetchImpl) {
                 const works = Array.isArray(rec.works) ? rec.works : [];
                 return [{ type: 'text', text: works.map((work, index) => (index + 1) + '. ' + workLabel(work)).join('\n') }];
             } },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = (rawArgs ?? {});
             const doi = optionalString(args, 'doi');
             const query = optionalString(args, 'query');
             if (doi === undefined && query === undefined)
                 throw new Error('cite_lookup 需要 doi 或 query 参数（至少一个）。');
             if (doi !== undefined) {
-                const work = await lookupDoi(doi, cfg, fetchImpl);
+                const work = await lookupDoi(doi, cfg, fetchImpl, executionSignal(exec));
                 return { count: 1, works: [work] };
             }
             const queryDoi = extractDois(query)[0];
             if (queryDoi !== undefined) {
-                const work = await lookupDoi(queryDoi, cfg, fetchImpl);
+                const work = await lookupDoi(queryDoi, cfg, fetchImpl, executionSignal(exec));
                 return { count: 1, works: [work], matchedDoi: queryDoi };
             }
             const limit = optionalInteger(args, 'limit', '返回条数', 1, 10, 5);
-            const works = await searchWorks(query, limit, cfg, fetchImpl);
+            const works = await searchWorks(query, limit, cfg, fetchImpl, executionSignal(exec));
             if (works.length === 0)
                 throw new Error('Crossref 没有找到匹配文献，请尝试更精确的标题/作者。');
             return { count: works.length, works };
@@ -142,12 +151,12 @@ export function buildCiteTools(cfg, fetchImpl) {
                 const rec = (value ?? {});
                 return [{ type: 'text', text: typeof rec.citation === 'string' ? rec.citation : '' }];
             } },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = (rawArgs ?? {});
             const doi = requiredString(args, 'doi', 'DOI');
             const style = readStyle(args.style);
             const lang = args.lang === 'en' ? 'en' : 'zh';
-            const work = await lookupDoi(doi, cfg, fetchImpl);
+            const work = await lookupDoi(doi, cfg, fetchImpl, executionSignal(exec));
             const citation = buildCitation(work, style, lang);
             return { doi: work.doi || doi, style, citation, work };
         },
@@ -164,13 +173,13 @@ export function buildCiteTools(cfg, fetchImpl) {
                 const rec = (value ?? {});
                 return [{ type: 'text', text: typeof rec.bibtex === 'string' ? rec.bibtex : '' }];
             } },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = (rawArgs ?? {});
             const doi = requiredString(args, 'doi', 'DOI');
             const key = optionalString(args, 'key');
-            const work = await lookupDoi(doi, cfg, fetchImpl);
+            const work = await lookupDoi(doi, cfg, fetchImpl, executionSignal(exec));
             const bibtex = buildBibtex(work, key);
-            return { doi: work.doi || doi, key, bibtex };
+            return { doi: work.doi || doi, ...(key !== undefined ? { key } : {}), bibtex };
         },
         timeoutMs: cfg.timeoutMs + 2000,
     };
@@ -189,23 +198,25 @@ export function buildCiteTools(cfg, fetchImpl) {
                             return (row.ok === true ? '✅' : '❌') + ' ' + row.doi + (typeof row.title === 'string' && row.title !== '' ? ' — ' + row.title : '');
                         }).join('\n') }];
             } },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = (rawArgs ?? {});
             const text = requiredString(args, 'text', '待检查文本');
             const maxChecks = optionalInteger(args, 'maxChecks', '校验数量', 1, 50, 10);
             const dois = extractDois(text).slice(0, maxChecks);
-            const results = await mapWithConcurrency(dois, 3, async (doi) => {
+            const signal = executionSignal(exec);
+            const results = await mapWithConcurrency(dois, CHECK_CONCURRENCY, async (doi) => {
                 try {
-                    const work = await lookupDoi(doi, cfg, fetchImpl);
+                    const work = await lookupDoi(doi, cfg, fetchImpl, signal);
                     return { doi, ok: true, title: work.title, url: work.url };
                 }
                 catch (error) {
+                    signal?.throwIfAborted();
                     return { doi, ok: false, title: '', url: '', error: error instanceof Error ? error.message : String(error) };
                 }
-            });
+            }, signal);
             return { count: results.length, results };
         },
-        timeoutMs: cfg.timeoutMs * 3 + 5000,
+        timeoutMs: cfg.timeoutMs * Math.ceil(MAX_CHECKS / CHECK_CONCURRENCY) + 5000,
     };
     const citeHealth = {
         name: 'cite_health',
@@ -224,16 +235,20 @@ export function buildCiteTools(cfg, fetchImpl) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute() {
+        async execute(_rawArgs, exec) {
             const checks = [];
             let ok = true;
             const startedAt = Date.now();
+            const signal = executionSignal(exec);
             try {
                 const fetcher = fetchImpl ?? globalThis.fetch;
                 const response = await fetcher('https://api.crossref.org/works?rows=1&select=DOI', {
                     headers: { 'user-agent': cfg.userAgent },
-                    signal: AbortSignal.timeout(Math.min(cfg.timeoutMs, 15000)),
+                    signal: signal === undefined
+                        ? AbortSignal.timeout(Math.min(cfg.timeoutMs, 15000))
+                        : AbortSignal.any([signal, AbortSignal.timeout(Math.min(cfg.timeoutMs, 15000))]),
                 });
+                signal?.throwIfAborted();
                 if (response.ok) {
                     checks.push({ name: 'Crossref API', ok: true, detail: 'HTTP ' + response.status + '，' + (Date.now() - startedAt) + 'ms' });
                 }
@@ -243,6 +258,7 @@ export function buildCiteTools(cfg, fetchImpl) {
                 }
             }
             catch (error) {
+                signal?.throwIfAborted();
                 ok = false;
                 checks.push({ name: 'Crossref API', ok: false, detail: (error instanceof Error ? error.message : String(error)) + '（网络需要特殊代理时请配置系统代理后重启）' });
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-cite",
-  "version": "0.3.0",
-  "description": "DSH 参考文献工具插件：cite_lookup/cite_format/cite_bibtex/cite_check 四工具，Crossref 元数据查询（含 DOI 精确解析与并发校验），GB/T 7714 / APA / MLA / Chicago 格式化，零运行时依赖。",
+  "version": "0.3.2",
+  "description": "DSH 参考文献工具插件：cite_lookup/cite_format/cite_bibtex/cite_check/cite_health 五工具（含自检），Crossref 元数据查询（含 DOI 精确解析与并发校验），GB/T 7714 / APA / MLA / Chicago 格式化，零运行时依赖。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",