dsh-cite 0.1.0

package/README.en.md

@@ -0,0 +1,22 @@
+# dsh-cite
+
+> 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.
+
+## Tools
+
+| Tool | Purpose | Key parameters |
+| :-- | :-- | :-- |
+| `cite_lookup` | Look up metadata by DOI or bibliographic query | `doi` or `query`; `limit` 1-10, default 5 |
+| `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 |
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-cite
+```
+
+MIT

package/README.md

@@ -0,0 +1,57 @@
+# dsh-cite
+
+> 给一个 DOI，还你规范参考文献——GB/T 7714 / APA / MLA / Chicago / BibTeX。
+
+DeepSeek Harness 参考文献工具插件：通过 Crossref API 查询文献元数据并格式化引用。四个工具、零运行时依赖、全平台通用。
+
+## 工具
+
+| 工具 | 作用 | 关键参数 |
+| :-- | :-- | :-- |
+| `cite_lookup` | 查文献元数据（DOI 精确查询 / 题录检索） | `doi` 或 `query` 至少一个；`limit` 1-10 默认 5 |
+| `cite_format` | 生成规范引文 | `doi` 必填；`style`：gb-t-7714 / apa / mla / chicago |
+| `cite_bibtex` | 生成 BibTeX 条目 | `doi` 必填；`key` 可选 |
+| `cite_check` | 从文本提取 DOI 并校验是否存在 | `text` 必填；`maxChecks` 1-50 默认 10 |
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-cite
+```
+
+## 示例
+
+```text
+用户：给我 10.1038/nature12345 的 GB/T 7714 引用
+Agent：
+  cite_format { doi: "10.1038/nature12345", style: "gb-t-7714" }
+  → LeCun Y, Bengio Y, Hinton G. Deep learning[J]. Nature, 2015, 521(7553): 436-444.
+
+用户：检查这段参考文献的 DOI 是否有效
+Agent：
+  cite_check { text: "..." }
+```
+
+## 配置
+
+```yaml
+- id: cite
+  name: 'dsh-cite'
+  config:
+    timeoutMs: 15000   # Crossref 请求超时
+    userAgent: ''      # 自定义 UA（建议带上可联系邮箱）
+```
+
+## 说明
+
+- 数据源：Crossref REST API，无需 API key
+- 引文为纯文本输出；格式按常见模板生成，正式投稿前请核对目标期刊的细节要求
+- 不采集、不上传任何本地文献数据
+
+## 开发
+
+```bash
+pnpm test       # 构建 + 14 个测试
+```
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# dsh-cite 组合包补丁：把参考文献工具插件行插入 profile。
+#
+# 示例（用户 profile 的 cordis.patch.yml）：
+#   - id: cite
+#     name: 'dsh-cite'
+#     config:
+#       timeoutMs: 15000     # Crossref 请求超时（默认 15 秒）
+#       userAgent: ''        # 自定义 User-Agent（默认 dsh-cite/0.1.0）
+#
+- insert:
+    - id: cite
+      name: 'dsh-cite'
+      config:
+        timeoutMs: 15000

package/lib/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * dsh-cite 配置解析：Crossref 请求超时与 User-Agent。
+ *
+ * @module dsh-cite/config
+ */
+export interface CiteConfig {
+    timeoutMs?: number;
+    userAgent?: string;
+}
+export interface ResolvedCiteConfig {
+    timeoutMs: number;
+    userAgent: string;
+}
+export declare function resolveConfig(config: CiteConfig | undefined | null): ResolvedCiteConfig;
+export declare function optionalString(args: Record<string, unknown>, key: string): string | undefined;
+export declare function requiredString(args: Record<string, unknown>, key: string, label: string): string;
+export declare function optionalInteger(args: Record<string, unknown>, key: string, label: string, lo: number, hi: number, fallback: number): number;

package/lib/config.js

@@ -0,0 +1,40 @@
+/**
+ * dsh-cite 配置解析：Crossref 请求超时与 User-Agent。
+ *
+ * @module dsh-cite/config
+ */
+const DEFAULT_TIMEOUT_MS = 15000;
+const DEFAULT_USER_AGENT = 'dsh-cite/0.1.0 (DeepSeek Harness citation plugin; mailto:STARDUSTLC666@users.noreply.github.com)';
+export function resolveConfig(config) {
+    const cfg = config ?? {};
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    if (cfg.timeoutMs !== undefined) {
+        if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0) {
+            throw new Error('timeoutMs 必须是大于 0 的数字（毫秒），例如 15000。');
+        }
+        timeoutMs = Math.min(120000, Math.max(2000, Math.round(cfg.timeoutMs)));
+    }
+    const userAgent = typeof cfg.userAgent === 'string' && cfg.userAgent.trim() !== '' ? cfg.userAgent.trim() : DEFAULT_USER_AGENT;
+    return { timeoutMs, userAgent };
+}
+export function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+export function requiredString(args, key, label) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
+    return value;
+}
+export function optionalInteger(args, key, label, lo, hi, fallback) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error(label + '（参数 ' + key + '）必须是数字。');
+    const rounded = Math.round(value);
+    if (rounded < lo || rounded > hi)
+        throw new Error(label + '（参数 ' + key + '）必须在 ' + lo + '-' + hi + ' 之间。');
+    return rounded;
+}

package/lib/crossref.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Crossref REST API 适配：按 DOI 查询 / 题录检索，统一归一化为 Work。
+ *
+ * @module dsh-cite/crossref
+ */
+import { type ResolvedCiteConfig } from './config.js';
+export interface CiteAuthor {
+    given: string;
+    family: string;
+    name: string;
+}
+export interface Work {
+    doi: string;
+    type: string;
+    title: string;
+    authors: CiteAuthor[];
+    containerTitle: string;
+    publisher: string;
+    year: number;
+    volume: string;
+    issue: string;
+    page: string;
+    url: string;
+    isbn: string;
+}
+export type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<Response>;
+export declare function assertDoi(value: string): string;
+/** 按 DOI 查询 Crossref 并归一化。 */
+export declare function lookupDoi(doi: string, cfg: ResolvedCiteConfig, fetchImpl?: FetchLike): Promise<Work>;
+/** 按题录文本检索 Crossref，返回归一化结果。 */
+export declare function searchWorks(query: string, limit: number, cfg: ResolvedCiteConfig, fetchImpl?: FetchLike): Promise<Work[]>;
+/** 从任意文本里提取 DOI。 */
+export declare function extractDois(text: string): string[];

package/lib/crossref.js

@@ -0,0 +1,144 @@
+/**
+ * Crossref REST API 适配：按 DOI 查询 / 题录检索，统一归一化为 Work。
+ *
+ * @module dsh-cite/crossref
+ */
+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, '');
+    if (!DOI_PATTERN.test(doi))
+        throw new Error('DOI 格式不正确：' + value + '（示例：10.1038/nature12345）。');
+    return doi;
+}
+function firstText(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (Array.isArray(value))
+        return firstText(value[0]);
+    return '';
+}
+function firstNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return firstNumber(value[0]);
+    return 0;
+}
+function record(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function normalizeAuthor(raw) {
+    const rec = record(raw);
+    const family = typeof rec.family === 'string' ? rec.family.trim() : '';
+    const given = typeof rec.given === 'string' ? rec.given.trim() : '';
+    const name = typeof rec.name === 'string' ? rec.name.trim() : '';
+    if (family === '' && given === '' && name === '')
+        return null;
+    return { given, family, name };
+}
+function normalizeWork(raw) {
+    const authorsRaw = Array.isArray(raw.author) ? raw.author : [];
+    const authors = authorsRaw.map(normalizeAuthor).filter((item) => item !== null);
+    const issued = record(raw.issued);
+    const dateParts = Array.isArray(issued['date-parts']) ? issued['date-parts'] : [];
+    const year = firstNumber(Array.isArray(dateParts[0]) ? dateParts[0][0] : raw.year);
+    const doi = typeof raw.DOI === 'string' ? raw.DOI.trim() : '';
+    return {
+        doi,
+        type: typeof raw.type === 'string' ? raw.type : 'other',
+        title: firstText(raw.title),
+        authors,
+        containerTitle: firstText(raw['container-title']),
+        publisher: typeof raw.publisher === 'string' ? raw.publisher.trim() : '',
+        year: year || 0,
+        volume: typeof raw.volume === 'string' ? raw.volume.trim() : '',
+        issue: typeof raw.issue === 'string' ? raw.issue.trim() : '',
+        page: typeof raw.page === 'string' ? raw.page.trim() : '',
+        url: typeof raw.URL === 'string' ? raw.URL.trim() : (doi !== '' ? 'https://doi.org/' + doi : ''),
+        isbn: firstText(raw.ISBN),
+    };
+}
+function makeHeaders(cfg) {
+    return { 'user-agent': cfg.userAgent, accept: 'application/json' };
+}
+/** 按 DOI 查询 Crossref 并归一化。 */
+export async function lookupDoi(doi, cfg, fetchImpl) {
+    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),
+        });
+    }
+    catch (error) {
+        throw new Error('Crossref 请求失败：' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (!response.ok) {
+        if (response.status === 404)
+            throw new Error('DOI 在 Crossref 中不存在：' + clean);
+        throw new Error('Crossref 返回 HTTP ' + response.status + '，无法完成查询。');
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new Error('Crossref 响应不是合法 JSON。');
+    }
+    const message = record(payload).message;
+    if (typeof message !== 'object' || message === null)
+        throw new Error('Crossref 响应缺少 message 字段。');
+    const work = normalizeWork(message);
+    if (work.doi === '')
+        work.doi = clean;
+    return work;
+}
+/** 按题录文本检索 Crossref，返回归一化结果。 */
+export async function searchWorks(query, limit, cfg, fetchImpl) {
+    const q = query.trim();
+    if (q === '')
+        throw new Error('检索词不能为空。');
+    const url = CROSSREF_API + '?query.bibliographic=' + encodeURIComponent(q) + '&rows=' + String(limit);
+    const fetcher = fetchImpl ?? globalThis.fetch;
+    let response;
+    try {
+        response = await fetcher(url, {
+            headers: makeHeaders(cfg),
+            signal: AbortSignal.timeout(cfg.timeoutMs),
+        });
+    }
+    catch (error) {
+        throw new Error('Crossref 检索失败：' + (error instanceof Error ? error.message : String(error)));
+    }
+    if (!response.ok)
+        throw new Error('Crossref 返回 HTTP ' + response.status + '，无法完成检索。');
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new Error('Crossref 响应不是合法 JSON。');
+    }
+    const items = record(payload).message;
+    const list = Array.isArray(items) ? items : (typeof items === 'object' && items !== null ? record(items).items : []);
+    if (!Array.isArray(list))
+        return [];
+    return list.map((item) => normalizeWork(record(item)));
+}
+/** 从任意文本里提取 DOI。 */
+export function extractDois(text) {
+    const pattern = /\b10\.\d{4,9}\/[-._;()/:A-Za-z0-9]+/gi;
+    const seen = new Set();
+    const result = [];
+    for (const match of text.match(pattern) ?? []) {
+        const clean = match.replace(/[.,;]+$/, '').trim();
+        if (seen.has(clean.toLowerCase()))
+            continue;
+        seen.add(clean.toLowerCase());
+        result.push(clean);
+    }
+    return result;
+}

package/lib/format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 参考文献格式化：GB/T 7714-2015 / APA 7 / MLA 9 / Chicago note，以及 BibTeX。
+ *
+ * @module dsh-cite/format
+ */
+import type { Work } from './crossref.js';
+export type CiteStyle = 'gb-t-7714' | 'apa' | 'mla' | 'chicago';
+export declare function readStyle(raw: unknown): CiteStyle;
+/** 按样式生成引文。 */
+export declare function buildCitation(work: Work, style: CiteStyle, lang?: string): string;
+/** 生成 BibTeX 条目。 */
+export declare function buildBibtex(work: Work, key?: string): string;

package/lib/format.js

@@ -0,0 +1,247 @@
+/**
+ * 参考文献格式化：GB/T 7714-2015 / APA 7 / MLA 9 / Chicago note，以及 BibTeX。
+ *
+ * @module dsh-cite/format
+ */
+export function readStyle(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return 'gb-t-7714';
+    if (raw === 'gb-t-7714' || raw === 'apa' || raw === 'mla' || raw === 'chicago')
+        return raw;
+    throw new Error('style 只支持 gb-t-7714 / apa / mla / chicago，收到：' + String(raw));
+}
+function fullName(author) {
+    if (author.name !== '')
+        return author.name;
+    if (author.given !== '' && author.family !== '')
+        return author.family + ' ' + author.given;
+    return author.family !== '' ? author.family : author.given;
+}
+function initials(given) {
+    return given
+        .split(/[\s.-]+/)
+        .filter((part) => part !== '')
+        .map((part) => part[0].toUpperCase() + '.')
+        .join(' ');
+}
+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] ?? '') : '');
+    return initialsText !== '' ? family + ', ' + initialsText : family;
+}
+function mlaName(author, first) {
+    const name = fullName(author);
+    const parts = name.trim().split(/\s+/);
+    if (parts.length < 2)
+        return name;
+    if (first)
+        return parts[0] + ', ' + parts.slice(1).join(' ');
+    return parts.slice(1).join(' ') + ' ' + parts[0];
+}
+function gbtAuthors(authors) {
+    if (authors.length === 0)
+        return '佚名';
+    const names = authors.map((author) => fullName(author));
+    return names.length <= 3 ? names.join(', ') : names.slice(0, 3).join(', ') + ', 等';
+}
+function apaAuthors(authors) {
+    if (authors.length === 0)
+        return 'Anonymous';
+    const names = authors.map(apaName);
+    if (names.length === 1)
+        return names[0];
+    if (names.length === 2)
+        return names[0] + ', & ' + names[1];
+    return names.slice(0, 19).join(', ') + ', ...';
+}
+function mlaAuthors(authors) {
+    if (authors.length === 0)
+        return 'Anonymous';
+    if (authors.length === 1)
+        return mlaName(authors[0], true);
+    if (authors.length === 2)
+        return mlaName(authors[0], true) + ', and ' + mlaName(authors[1], false);
+    return mlaName(authors[0], true) + ', et al.';
+}
+function chicagoAuthors(authors) {
+    if (authors.length === 0)
+        return 'Anonymous';
+    if (authors.length <= 3)
+        return authors.map((author) => fullName(author)).join(', ');
+    return fullName(authors[0]) + ', et al.';
+}
+function gbtTypeLabel(type, work) {
+    switch (type) {
+        case 'journal-article': return '[J]';
+        case 'book':
+        case 'monograph':
+        case 'edited-book': return '[M]';
+        case 'proceedings-article':
+        case 'proceedings': return '[C]';
+        case 'dissertation': return '[D]';
+        case 'report': return '[R]';
+        case 'standard': return '[S]';
+        case 'patent': return '[P]';
+        case 'posted-content':
+        case 'dataset':
+        case 'other': return work.url !== '' ? '[EB/OL]' : '[Z]';
+        default: return work.url !== '' ? '[EB/OL]' : '[Z]';
+    }
+}
+function yearText(work) {
+    return work.year > 0 ? String(work.year) : 'n.d.';
+}
+function volumeIssuePages(work) {
+    let text = work.volume;
+    if (work.issue !== '')
+        text += '(' + work.issue + ')';
+    if (work.page !== '')
+        text += (text !== '' ? ': ' : '') + work.page;
+    return text;
+}
+function cleanupTitle(title) {
+    return title.replace(/\s+/g, ' ').trim();
+}
+function titleOf(work) {
+    return cleanupTitle(work.title !== '' ? work.title : '(无标题)');
+}
+/** 生成 GB/T 7714-2015 参考文献条目。 */
+function buildGbt(work, lang) {
+    const authors = gbtAuthors(work.authors);
+    const title = titleOf(work);
+    const label = gbtTypeLabel(work.type, work);
+    if (work.type === 'journal-article' && work.containerTitle !== '') {
+        let tail = work.containerTitle + ', ' + yearText(work);
+        const vip = volumeIssuePages(work);
+        if (vip !== '')
+            tail += ', ' + vip;
+        return authors + '. ' + title + label + '. ' + tail + '.';
+    }
+    if (work.type === 'book' || work.type === 'monograph' || work.type === 'edited-book') {
+        let tail = work.publisher !== '' ? work.publisher + ', ' : '';
+        tail += yearText(work);
+        if (work.isbn !== '')
+            tail += '. ISBN ' + work.isbn;
+        return authors + '. ' + title + '[M]. ' + tail + '.';
+    }
+    if (work.containerTitle !== '' && work.type === 'proceedings-article') {
+        return authors + '. ' + title + '[C]//' + work.containerTitle + '. ' + yearText(work) + '.';
+    }
+    const urlPart = work.url !== '' ? ' ' + work.url + '.' : '';
+    const accessed = new Date().toISOString().slice(0, 10);
+    return authors + '. ' + title + label + '. (' + yearText(work) + ')[' + (lang === 'zh' ? '引用日期 ' : 'cited ') + accessed + '].' + urlPart;
+}
+/** 生成 APA 7 参考文献条目。 */
+function buildApa(work) {
+    const authors = apaAuthors(work.authors);
+    const title = titleOf(work);
+    const year = yearText(work);
+    if (work.type === 'journal-article' && work.containerTitle !== '') {
+        let text = authors + ' (' + year + '). ' + title + '. ' + work.containerTitle;
+        if (work.volume !== '')
+            text += ', ' + work.volume;
+        if (work.issue !== '')
+            text += '(' + work.issue + ')';
+        if (work.page !== '')
+            text += ', ' + work.page;
+        text += '. ';
+        text += work.doi !== '' ? 'https://doi.org/' + work.doi : work.url;
+        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.url !== '' ? work.url : '');
+}
+/** 生成 MLA 9 参考文献条目。 */
+function buildMla(work) {
+    const authors = mlaAuthors(work.authors);
+    const title = titleOf(work);
+    let text = authors + '. "' + title + '." ';
+    if (work.containerTitle !== '')
+        text += work.containerTitle + ', ';
+    if (work.volume !== '')
+        text += 'vol. ' + work.volume + ', ';
+    if (work.issue !== '')
+        text += 'no. ' + work.issue + ', ';
+    text += yearText(work);
+    if (work.page !== '')
+        text += ', pp. ' + work.page;
+    text += '.';
+    if (work.doi !== '')
+        text += ' https://doi.org/' + work.doi;
+    return text;
+}
+/** 生成 Chicago（note 格式）引用。 */
+function buildChicago(work) {
+    const authors = chicagoAuthors(work.authors);
+    const title = titleOf(work);
+    let text = authors + ', "' + title + '"';
+    if (work.containerTitle !== '')
+        text += ', ' + work.containerTitle;
+    if (work.volume !== '')
+        text += ' ' + work.volume;
+    if (work.issue !== '')
+        text += ', no. ' + work.issue;
+    text += ' (' + yearText(work) + ')';
+    if (work.page !== '')
+        text += ': ' + work.page;
+    text += '.';
+    if (work.doi !== '')
+        text += ' https://doi.org/' + work.doi;
+    return text;
+}
+/** 按样式生成引文。 */
+export function buildCitation(work, style, lang = 'zh') {
+    switch (style) {
+        case 'gb-t-7714': return buildGbt(work, lang);
+        case 'apa': return buildApa(work);
+        case 'mla': return buildMla(work);
+        case 'chicago': return buildChicago(work);
+    }
+}
+function escapeLatex(value) {
+    return value.replace(/([{}])/g, '\\$1').replace(/&/g, '\\&').replace(/%/g, '\\%').replace(/\$/g, '\\$');
+}
+function bibtexType(work) {
+    switch (work.type) {
+        case 'journal-article': return 'article';
+        case 'book':
+        case 'monograph':
+        case 'edited-book': return 'book';
+        case 'proceedings-article':
+        case 'proceedings': return 'inproceedings';
+        case 'dissertation': return 'phdthesis';
+        case 'report': return 'techreport';
+        default: return 'misc';
+    }
+}
+/** 生成 BibTeX 条目。 */
+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() !== '' ? key.trim() : ((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 ');
+    if (authors !== '')
+        fields.push('  author={' + escapeLatex(authors) + '}');
+    fields.push('  title={' + escapeLatex(titleOf(work)) + '}');
+    if (work.containerTitle !== '')
+        fields.push(type === 'article' ? '  journal={' + escapeLatex(work.containerTitle) + '}' : '  booktitle={' + escapeLatex(work.containerTitle) + '}');
+    if (work.year > 0)
+        fields.push('  year={' + work.year + '}');
+    if (work.volume !== '')
+        fields.push('  volume={' + work.volume + '}');
+    if (work.issue !== '')
+        fields.push('  number={' + work.issue + '}');
+    if (work.page !== '')
+        fields.push('  pages={' + work.page + '}');
+    if (work.publisher !== '')
+        fields.push('  publisher={' + escapeLatex(work.publisher) + '}');
+    if (work.doi !== '')
+        fields.push('  doi={' + work.doi + '}');
+    if (work.url !== '')
+        fields.push('  url={' + escapeLatex(work.url) + '}');
+    return '@' + type + '{' + baseKey + ',\n' + fields.join(',\n') + '\n}';
+}

package/lib/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 引文。零运行时依赖。
+ *
+ * @module dsh-cite
+ */
+import { type CiteConfig } from './config.js';
+import { type CiteToolDefinition } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.tools。 */
+export declare const inject: string[];
+export interface CitePluginContext {
+    tools: {
+        register(definition: CiteToolDefinition, options?: {
+            prepend?: boolean;
+        }): () => void;
+    };
+    on?(event: string, listener: () => void): () => void;
+}
+export declare function apply(ctx: CitePluginContext, config?: CiteConfig | null): void;
+export * from './config.js';
+export * from './crossref.js';
+export * from './format.js';
+export * from './tools.js';

package/lib/index.js

@@ -0,0 +1,37 @@
+/**
+ * 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 引文。零运行时依赖。
+ *
+ * @module dsh-cite
+ */
+import { resolveConfig } from './config.js';
+import { buildCiteTools } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.tools。 */
+export const inject = ['tools'];
+export function apply(ctx, config) {
+    let cfg;
+    try {
+        cfg = resolveConfig(config);
+    }
+    catch (error) {
+        console.warn('[dsh-cite] ' + (error instanceof Error ? error.message : String(error)));
+        cfg = resolveConfig(null);
+    }
+    const disposers = [];
+    for (const definition of buildCiteTools(cfg)) {
+        disposers.push(ctx.tools.register(definition, { prepend: true }));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+        });
+    }
+}
+export * from './config.js';
+export * from './crossref.js';
+export * from './format.js';
+export * from './tools.js';

package/lib/tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 四个面向模型的参考文献工具：
+ * cite_lookup / cite_format / cite_bibtex / cite_check。
+ *
+ * @module dsh-cite/tools
+ */
+import { type ResolvedCiteConfig } from './config.js';
+import { type FetchLike } from './crossref.js';
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+export interface CiteToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec: unknown): Promise<unknown>;
+    timeoutMs?: number;
+}
+export declare function buildCiteTools(cfg: ResolvedCiteConfig, fetchImpl?: FetchLike): CiteToolDefinition[];

package/lib/tools.js

@@ -0,0 +1,190 @@
+/**
+ * 四个面向模型的参考文献工具：
+ * cite_lookup / cite_format / cite_bibtex / cite_check。
+ *
+ * @module dsh-cite/tools
+ */
+import { optionalInteger, optionalString, requiredString } from './config.js';
+import { extractDois, lookupDoi, searchWorks } from './crossref.js';
+import { buildBibtex, buildCitation, readStyle } from './format.js';
+function compileParameters(spec) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(spec)) {
+        if (prop?.required === true)
+            required.push(key);
+        const node = {};
+        if (typeof prop?.type === 'string')
+            node.type = prop.type;
+        if (typeof prop?.description === 'string')
+            node.description = prop.description;
+        if (prop?.enum !== undefined)
+            node.enum = prop.enum;
+        properties[key] = node;
+    }
+    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
+}
+const authorSchema = {
+    type: 'object',
+    properties: { given: { type: 'string' }, family: { type: 'string' }, name: { type: 'string' } },
+    additionalProperties: true,
+};
+const workSchema = {
+    type: 'object',
+    properties: {
+        doi: { type: 'string' },
+        type: { type: 'string' },
+        title: { type: 'string' },
+        authors: { type: 'array', items: authorSchema },
+        containerTitle: { type: 'string' },
+        publisher: { type: 'string' },
+        year: { type: 'integer' },
+        volume: { type: 'string' },
+        issue: { type: 'string' },
+        page: { type: 'string' },
+        url: { type: 'string' },
+        isbn: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+const lookupSchema = {
+    type: 'object',
+    properties: { count: { type: 'integer' }, works: { type: 'array', items: workSchema } },
+    additionalProperties: true,
+};
+const formatSchema = {
+    type: 'object',
+    properties: { doi: { type: 'string' }, style: { type: 'string' }, citation: { type: 'string' }, work: workSchema },
+    additionalProperties: true,
+};
+const bibtexSchema = {
+    type: 'object',
+    properties: { doi: { type: 'string' }, key: { type: 'string' }, bibtex: { type: 'string' } },
+    additionalProperties: true,
+};
+const checkItemSchema = {
+    type: 'object',
+    properties: { doi: { type: 'string' }, ok: { type: 'boolean' }, title: { type: 'string' }, url: { type: 'string' }, error: { type: 'string' } },
+    additionalProperties: true,
+};
+const checkSchema = {
+    type: 'object',
+    properties: { count: { type: 'integer' }, results: { type: 'array', items: checkItemSchema } },
+    additionalProperties: true,
+};
+function workLabel(work) {
+    const title = work.title !== '' ? work.title : '(无标题)';
+    return title + '（' + (work.year > 0 ? work.year + ', ' : '') + (work.containerTitle !== '' ? work.containerTitle : work.publisher) + '）';
+}
+export function buildCiteTools(cfg, fetchImpl) {
+    const citeLookup = {
+        name: 'cite_lookup',
+        description: '查询文献元数据：给 DOI 精确查询，或给题录文本（标题/作者/刊名）到 Crossref 检索。返回归一化后的作者、标题、期刊、年份、卷期页、DOI 等信息。',
+        parameters: compileParameters({
+            doi: { type: 'string', description: 'DOI（可选；与 query 至少给一个，例如 10.1038/nature12345）。' },
+            query: { type: 'string', description: '题录检索文本（可选；与 doi 至少给一个）。' },
+            limit: { type: 'integer', description: 'query 检索返回条数 1-10（默认 5）。' },
+        }),
+        output: { schema: lookupSchema, render: (_args, value) => {
+                const rec = (value ?? {});
+                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) {
+            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);
+                return { count: 1, works: [work] };
+            }
+            const limit = optionalInteger(args, 'limit', '返回条数', 1, 10, 5);
+            const works = await searchWorks(query, limit, cfg, fetchImpl);
+            if (works.length === 0)
+                throw new Error('Crossref 没有找到匹配文献，请尝试更精确的标题/作者。');
+            return { count: works.length, works };
+        },
+        timeoutMs: cfg.timeoutMs + 2000,
+    };
+    const citeFormat = {
+        name: 'cite_format',
+        description: '按 DOI 生成规范参考文献条目。style 支持 gb-t-7714（默认，中国论文标准）、apa、mla、chicago；lang 为 zh 或 en（影响电子文献引用日期措辞）。',
+        parameters: compileParameters({
+            doi: { type: 'string', required: true, description: '文献 DOI（必填）。' },
+            style: { type: 'string', enum: ['gb-t-7714', 'apa', 'mla', 'chicago'], description: '引用格式（默认 gb-t-7714）。' },
+            lang: { type: 'string', enum: ['zh', 'en'], description: '语言（默认 zh）。' },
+        }),
+        output: { schema: formatSchema, render: (_args, value) => {
+                const rec = (value ?? {});
+                return [{ type: 'text', text: typeof rec.citation === 'string' ? rec.citation : '' }];
+            } },
+        async execute(rawArgs) {
+            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 citation = buildCitation(work, style, lang);
+            return { doi: work.doi || doi, style, citation, work };
+        },
+        timeoutMs: cfg.timeoutMs + 2000,
+    };
+    const citeBibtex = {
+        name: 'cite_bibtex',
+        description: '按 DOI 生成 BibTeX 条目。key 可选，缺省用第一作者 + 年份 + 标题首词生成。',
+        parameters: compileParameters({
+            doi: { type: 'string', required: true, description: '文献 DOI（必填）。' },
+            key: { type: 'string', description: 'BibTeX 引用键（可选）。' },
+        }),
+        output: { schema: bibtexSchema, render: (_args, value) => {
+                const rec = (value ?? {});
+                return [{ type: 'text', text: typeof rec.bibtex === 'string' ? rec.bibtex : '' }];
+            } },
+        async execute(rawArgs) {
+            const args = (rawArgs ?? {});
+            const doi = requiredString(args, 'doi', 'DOI');
+            const key = optionalString(args, 'key');
+            const work = await lookupDoi(doi, cfg, fetchImpl);
+            const bibtex = buildBibtex(work, key);
+            return { doi: work.doi || doi, key, bibtex };
+        },
+        timeoutMs: cfg.timeoutMs + 2000,
+    };
+    const citeCheck = {
+        name: 'cite_check',
+        description: '从一段文本中提取所有 DOI 并逐个到 Crossref 校验是否存在，返回每个 DOI 的状态与标题。用于检查参考文献清单里的 DOI 是否有效。',
+        parameters: compileParameters({
+            text: { type: 'string', required: true, description: '要检查的文本（参考文献列表或任意含 DOI 的文本）。' },
+            maxChecks: { type: 'integer', description: '最多校验多少个 DOI，1-50（默认 10）。' },
+        }),
+        output: { schema: checkSchema, render: (_args, value) => {
+                const rec = (value ?? {});
+                const results = Array.isArray(rec.results) ? rec.results : [];
+                return [{ type: 'text', text: 'DOI 校验：' + results.map((item) => {
+                            const row = (item ?? {});
+                            return (row.ok === true ? '✅' : '❌') + ' ' + row.doi + (typeof row.title === 'string' && row.title !== '' ? ' — ' + row.title : '');
+                        }).join('\n') }];
+            } },
+        async execute(rawArgs) {
+            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 = [];
+            for (const doi of dois) {
+                try {
+                    const work = await lookupDoi(doi, cfg, fetchImpl);
+                    results.push({ doi, ok: true, title: work.title, url: work.url });
+                }
+                catch (error) {
+                    results.push({ doi, ok: false, title: '', url: '', error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            return { count: results.length, results };
+        },
+        timeoutMs: cfg.timeoutMs * 3 + 5000,
+    };
+    return [citeLookup, citeFormat, citeBibtex, citeCheck];
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "dsh-cite",
+  "version": "0.1.0",
+  "description": "DSH 参考文献工具插件：cite_lookup/cite_format/cite_bibtex/cite_check 四工具，Crossref 元数据查询，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"
+  ],
+  "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"
+}