dsh-cite 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,6 +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.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
 
@@ -19,4 +26,14 @@ A DeepSeek Harness plugin for bibliographic references: query Crossref and forma
 dsh plugin --profile web add dsh-cite
 ```
 
-MIT
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-cite
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+## License
+
+MIT (see [LICENSE](LICENSE))

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,6 +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.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -19,6 +26,15 @@ DeepSeek Harness 参考文献工具插件：通过 Crossref API 查询文献元
 dsh plugin --profile web add dsh-cite
 ```
 
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-cite
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+
+
 ## 示例
 
 ```text
@@ -56,3 +72,6 @@ pnpm test       # 构建 + 18 个测试
 ```
 
 MIT
+## License
+
+MIT（见 [LICENSE](LICENSE)）

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.1 (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.1 (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.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;
@@ -135,7 +135,7 @@ export function extractDois(text) {
     const seen = new Set();
     const result = [];
     for (const match of text.match(pattern) ?? []) {
-        const clean = match.replace(/[.,;]+$/, '').trim();
+        const clean = match.replace(/[.,;:)\]}'">]+$/, '').trim();
         if (seen.has(clean.toLowerCase()))
             continue;
         seen.add(clean.toLowerCase());

package/lib/format.js

@@ -26,7 +26,7 @@ function initials(given) {
 }
 function apaName(author) {
     const family = author.family !== '' ? author.family : (author.name !== '' ? author.name : author.given);
-    const initialsText = author.given !== '' ? initials(author.given) : (author.name !== '' ? initials(author.name.split(/[\s-]+/)[0] ?? '') : '');
+    const initialsText = author.given !== '' ? initials(author.given) : '';
     return initialsText !== '' ? family + ', ' + initialsText : family;
 }
 function mlaName(author, first) {
@@ -52,7 +52,9 @@ function apaAuthors(authors) {
         return names[0];
     if (names.length === 2)
         return names[0] + ', & ' + names[1];
-    return names.slice(0, 19).join(', ') + ', ...';
+    if (names.length <= 20)
+        return names.slice(0, -1).join(', ') + ', & ' + names[names.length - 1];
+    return names.slice(0, 19).join(', ') + ', ... ' + names[names.length - 1];
 }
 function mlaAuthors(authors) {
     if (authors.length === 0)
@@ -144,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) {
@@ -201,7 +204,21 @@ export function buildCitation(work, style, lang = 'zh') {
     }
 }
 function escapeLatex(value) {
-    return value.replace(/([{}])/g, '\\$1').replace(/&/g, '\\&').replace(/%/g, '\\%').replace(/\$/g, '\\$');
+    return value.replace(/[\\{}&%$#_~^]/g, (ch) => {
+        switch (ch) {
+            case '\\': return '\\textbackslash{}';
+            case '{': return '\\{';
+            case '}': return '\\}';
+            case '&': return '\\&';
+            case '%': return '\\%';
+            case '$': return '\\$';
+            case '#': return '\\#';
+            case '_': return '\\_';
+            case '~': return '\\textasciitilde{}';
+            case '^': return '\\textasciicircum{}';
+            default: return ch;
+        }
+    });
 }
 /** BibTeX 引用键只允许安全字符，空格/逗号/花括号等替换为下划线。 */
 function sanitizeBibtexKey(value) {
@@ -225,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,15 +1,16 @@
 /**
  * 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
  */
 import { type CiteConfig } from './config.js';
 import { type CiteToolDefinition } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools。 */
+export declare const name = "cite";
 export declare const inject: string[];
 export interface CitePluginContext {
     tools: {

package/lib/index.js

@@ -1,15 +1,16 @@
 /**
  * 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
  */
 import { resolveConfig } from './config.js';
 import { buildCiteTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools。 */
+export const name = 'cite';
 export const inject = ['tools'];
 export function apply(ctx, config) {
     let cfg;

package/lib/tools.js

@@ -207,5 +207,49 @@ export function buildCiteTools(cfg, fetchImpl) {
         },
         timeoutMs: cfg.timeoutMs * 3 + 5000,
     };
-    return [citeLookup, citeFormat, citeBibtex, citeCheck];
+    const citeHealth = {
+        name: 'cite_health',
+        description: 'dsh-cite 自检：向 Crossref API 发一个最小请求验证连通性（rows=1），报告延迟。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => {
+                const rec = (value ?? {});
+                const rawChecks = Array.isArray(rec.checks) ? rec.checks : [];
+                const checks = rawChecks.map((item) => (item ?? {}));
+                const lines = ['dsh-cite 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
+                for (const c of checks) {
+                    lines.push('- ' + c.name + '：' + (c.ok === true ? '✅' : '❌ ' + String(c.detail ?? '')));
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute() {
+            const checks = [];
+            let ok = true;
+            const startedAt = Date.now();
+            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)),
+                });
+                if (response.ok) {
+                    checks.push({ name: 'Crossref API', ok: true, detail: 'HTTP ' + response.status + '，' + (Date.now() - startedAt) + 'ms' });
+                }
+                else {
+                    ok = false;
+                    checks.push({ name: 'Crossref API', ok: false, detail: 'HTTP ' + response.status });
+                }
+            }
+            catch (error) {
+                ok = false;
+                checks.push({ name: 'Crossref API', ok: false, detail: (error instanceof Error ? error.message : String(error)) + '（网络需要特殊代理时请配置系统代理后重启）' });
+            }
+            checks.push({ name: '请求配置', ok: true, detail: 'timeoutMs=' + cfg.timeoutMs + '，UA 已配置' });
+            return { ok, plugin: 'dsh-cite', checks };
+        },
+        timeoutMs: Math.min(cfg.timeoutMs + 5000, 30000),
+    };
+    return [citeLookup, citeFormat, citeBibtex, citeCheck, citeHealth];
 }

package/package.json

@@ -1,64 +1,63 @@
-{
-  "name": "dsh-cite",
-  "version": "0.2.0",
-  "description": "DSH 参考文献工具插件：cite_lookup/cite_format/cite_bibtex/cite_check 四工具，Crossref 元数据查询（含 DOI 精确解析与并发校验），GB/T 7714 / APA / MLA / Chicago 格式化，零运行时依赖。",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md",
-    "README.en.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepare": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
-    "prepublishOnly": "pnpm run build"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "citation",
-    "crossref",
-    "gb-t-7714",
-    "apa",
-    "mla",
-    "chicago",
-    "dsh-plugin"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=22.13"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.6.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/STARDUSTLC666/dsh-cite.git"
-  },
-  "bugs": {
-    "url": "https://github.com/STARDUSTLC666/dsh-cite/issues"
-  },
-  "homepage": "https://github.com/STARDUSTLC666/dsh-cite#readme",
-  "author": "stardustlc",
-  "packageManager": "pnpm@11.7.0"
-}
+{
+  "name": "dsh-cite",
+  "version": "0.3.1",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "citation",
+    "crossref",
+    "gb-t-7714",
+    "apa",
+    "mla",
+    "chicago",
+    "dsh-plugin"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STARDUSTLC666/dsh-cite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-cite/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-cite#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}