dsh-kenari-plugin 0.1.1

package/lib/tools/shared.d.ts

@@ -0,0 +1,89 @@
+/**
+ * REST 工具族共享基建：工具依赖、计费记账、成本回显与通用 render 辅助。
+ * 每个工具文件只声明自己的参数 schema 与端点映射，网络与错误映射集中在 http.ts，
+ * 目录与计价集中在 catalog.ts，账本集中在 billing.ts。
+ * @module dsh-kenari-plugin/tools/shared
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { KenariHttpDeps } from '../http.js';
+import type { Config } from '../index.js';
+import type { KenariCatalog, KenariModel } from '../catalog.js';
+import type { BalanceMonitor, BillingLedger } from '../billing.js';
+export { formatRupiah, GLOBAL_SCOPE } from '../billing.js';
+/** 工具族共享的运行时依赖：传输层 + 目录 + 账本 + 余额监控 + attachment（经 ctx）。 */
+export interface ToolsDeps {
+    readonly http: KenariHttpDeps;
+    readonly ctx: Context;
+    /** 实时配置视图：settings 提交后下一次操作即读到新值。 */
+    readonly config: Config;
+    /** 模型目录（TTL 缓存，公开端点）。 */
+    readonly catalog: KenariCatalog;
+    /** 计费账本（按会话累计）。 */
+    readonly billing: BillingLedger;
+    /** 余额监控（MCP 入口，TTL 缓存）。 */
+    readonly balance: BalanceMonitor;
+}
+/** 单次调用的计费回显行；cost 缺失时不产生误导。 */
+export declare function costLine(microIdr: number | undefined): string;
+/** 会话作用域：优先 dsh 的 SessionId，无 agent 的调用落到 global。 */
+export declare function scopeOf(exec: {
+    agent?: {
+        id: string;
+    };
+} | undefined): string;
+/**
+ * 花费前预检：会话预算已用尽就拒绝（抛 KenariBudgetError）。
+ * 用在每个会产生费用的工具入口。
+ */
+export declare function spendGuard(deps: ToolsDeps, exec: {
+    agent?: {
+        id: string;
+    };
+} | undefined, tool: string): void;
+/** 一次花费的记账输入。 */
+export interface SpendInput {
+    tool: string;
+    model?: string;
+    /** 响应回显的实际扣费（micro-IDR）；有它就以它为准。 */
+    costMicroIdr?: number;
+    /** 目录单价 × 数量推算的预估费用（micro-IDR）。 */
+    estimateMicroIdr?: number;
+    /** 预估口径说明，例如「1 张 × Rp 175」。 */
+    estimateNote?: string;
+    /** 明确的口径补充，例如「复用命中，本次免费」。 */
+    note?: string;
+    /** 该调用是否计费；false 表示免费工具（如目录查询、token 计数）。 */
+    billable?: boolean;
+}
+/**
+ * 记账并生成回显文本。实际值优先于预估值；两者都缺且声明计费时如实说明未计入，
+ * 避免模型把「没写费用」当成「免费」。
+ */
+export declare function billSpend(deps: ToolsDeps, exec: {
+    agent?: {
+        id: string;
+    };
+} | undefined, input: SpendInput): Promise<string>;
+/**
+ * 非 token 单位按整单位上取。
+ *
+ * 实测（2026-09-10，mimo-v2-5-tts）：21 字符的 TTS 输入按 1 个「1k 字符」单位计费
+ * Rp 250，而非 0.021 单位。所以 `image`/`second`/`1k_chars`/`song`/`request`/
+ * `megapixel` 这类按件单位都要向上取整，否则预估会低一到两个数量级。
+ * `token_1m` 是按 token 线性计价，保留小数才是正确口径。
+ */
+export declare function billedUnits(units: number, unit: string | undefined): {
+    units: number;
+    roundedUp: boolean;
+};
+/**
+ * 按目录计价行预估一次调用：`units` 必须以该行的计费单位表达
+ * （图像=张、视频=秒、语音=千字符、token 类=百万 token）。
+ * 找不到模型或该端点单价时返回空预估（不阻断调用）。
+ */
+export declare function estimateByUnit(deps: ToolsDeps, modelId: string, endpoint: string, units: number, variant?: string): Promise<{
+    model?: KenariModel;
+    microIdr?: number;
+    note?: string;
+}>;
+//# sourceMappingURL=shared.d.ts.map

package/lib/tools/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAkB,MAAM,eAAe,CAAA;AAE/E,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAGlE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAY1D,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,qCAAqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,2BAA2B;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CACjC;AAED,gCAAgC;AAChC,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE7D;AAED,qDAAqD;AACrD,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,SAAS,GAAG,MAAM,CAE5E;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE5G;AAED,iBAAiB;AACjB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mCAAmC;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,SAAS,EAC5C,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,MAAM,CAAC,CAuCjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAI1G;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAwBpE"}

package/lib/tools/shared.js

@@ -0,0 +1,128 @@
+/**
+ * REST 工具族共享基建：工具依赖、计费记账、成本回显与通用 render 辅助。
+ * 每个工具文件只声明自己的参数 schema 与端点映射，网络与错误映射集中在 http.ts，
+ * 目录与计价集中在 catalog.ts，账本集中在 billing.ts。
+ * @module dsh-kenari-plugin/tools/shared
+ */
+import { priceLineOf, unitLabel } from '../catalog.js';
+import { GLOBAL_SCOPE, formatRupiah } from '../billing.js';
+export { formatRupiah, GLOBAL_SCOPE } from '../billing.js';
+/** 端点 → 目录 modality：只有专用能力模型不在默认目录里。 */
+function modalityOfEndpoint(endpoint) {
+    switch (endpoint) {
+        case 'embeddings': return 'embedding';
+        case 'rerank': return 'rerank';
+        case 'moderations': return 'moderation';
+        default: return undefined;
+    }
+}
+/** 单次调用的计费回显行；cost 缺失时不产生误导。 */
+export function costLine(microIdr) {
+    return microIdr === undefined ? '' : `\n\n费用：${formatRupiah(microIdr)}（micro_idr ${microIdr}）`;
+}
+/** 会话作用域：优先 dsh 的 SessionId，无 agent 的调用落到 global。 */
+export function scopeOf(exec) {
+    return exec?.agent?.id ?? GLOBAL_SCOPE;
+}
+/**
+ * 花费前预检：会话预算已用尽就拒绝（抛 KenariBudgetError）。
+ * 用在每个会产生费用的工具入口。
+ */
+export function spendGuard(deps, exec, tool) {
+    deps.billing.assertWithinBudget(scopeOf(exec), tool);
+}
+/**
+ * 记账并生成回显文本。实际值优先于预估值；两者都缺且声明计费时如实说明未计入，
+ * 避免模型把「没写费用」当成「免费」。
+ */
+export async function billSpend(deps, exec, input) {
+    const billable = input.billable ?? true;
+    const scope = scopeOf(exec);
+    let head;
+    if (input.costMicroIdr !== undefined) {
+        deps.billing.recordSpend(scope, {
+            tool: input.tool,
+            ...(input.model !== undefined ? { model: input.model } : {}),
+            microIdr: input.costMicroIdr,
+            estimated: false,
+        });
+        head = `费用：${formatRupiah(input.costMicroIdr)}（实际扣费${input.costMicroIdr === 0 ? '，复用命中免费' : ''}）`;
+    }
+    else if (input.estimateMicroIdr !== undefined) {
+        deps.billing.recordSpend(scope, {
+            tool: input.tool,
+            ...(input.model !== undefined ? { model: input.model } : {}),
+            microIdr: input.estimateMicroIdr,
+            estimated: true,
+        });
+        const per = input.estimateNote === undefined ? '' : `（${input.estimateNote}）`;
+        head = `费用：约 ${formatRupiah(input.estimateMicroIdr)}（按目录单价预估${per}，最终以账单为准）`;
+    }
+    else if (billable) {
+        head = '费用：本次调用既无回显也未查到单价，未计入累计';
+    }
+    if (head === undefined)
+        return '';
+    if (input.note !== undefined)
+        head = `${head}；${input.note}`;
+    const totals = deps.billing.spendTotals(scope);
+    const scopeLabel = scope === GLOBAL_SCOPE ? '本进程' : '本会话';
+    const lines = [`${head}｜${scopeLabel}累计：${formatRupiah(totals.microIdr)}（${totals.calls} 次）`];
+    const thresholdRp = deps.config.lowBalanceAlertRp ?? 0;
+    if (thresholdRp > 0) {
+        const alert = await deps.balance.alertIfLow(thresholdRp);
+        if (alert !== undefined)
+            lines.push(alert);
+    }
+    return `\n\n${lines.join('\n')}`;
+}
+/**
+ * 非 token 单位按整单位上取。
+ *
+ * 实测（2026-09-10，mimo-v2-5-tts）：21 字符的 TTS 输入按 1 个「1k 字符」单位计费
+ * Rp 250，而非 0.021 单位。所以 `image`/`second`/`1k_chars`/`song`/`request`/
+ * `megapixel` 这类按件单位都要向上取整，否则预估会低一到两个数量级。
+ * `token_1m` 是按 token 线性计价，保留小数才是正确口径。
+ */
+export function billedUnits(units, unit) {
+    if (unit === 'token_1m')
+        return { units, roundedUp: false };
+    const whole = Math.ceil(units);
+    return { units: whole, roundedUp: whole !== units };
+}
+/**
+ * 按目录计价行预估一次调用：`units` 必须以该行的计费单位表达
+ * （图像=张、视频=秒、语音=千字符、token 类=百万 token）。
+ * 找不到模型或该端点单价时返回空预估（不阻断调用）。
+ */
+export async function estimateByUnit(deps, modelId, endpoint, units, variant) {
+    try {
+        const resolved = await deps.catalog.resolve(modelId, modalityOfEndpoint(endpoint));
+        if (resolved === undefined)
+            return {};
+        const line = priceLineOf(resolved.model, endpoint, variant);
+        if (line?.micro_idr === undefined)
+            return { model: resolved.model };
+        const label = unitLabel(line.unit);
+        const billed = billedUnits(units, line.unit);
+        const unitPrice = line.micro_idr;
+        const parts = [
+            `${Number.isInteger(billed.units) ? billed.units : billed.units.toFixed(6)} ${label}`,
+            `× Rp ${(unitPrice / 1_000_000).toLocaleString('id-ID')}`,
+        ];
+        if (billed.roundedUp)
+            parts.push(`（不足一单位按一单位计，输入量 ${units.toFixed(6)}）`);
+        if (variant !== undefined)
+            parts.push(`@ ${variant}`);
+        return {
+            model: resolved.model,
+            microIdr: Math.round(unitPrice * billed.units),
+            note: parts.join(' '),
+        };
+    }
+    catch {
+        // 目录不可用时预估失效，调用本身继续
+        return {};
+    }
+}
+//# sourceMappingURL=shared.js.map

package/lib/tools/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"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"}

package/lib/tools/x-search.d.ts

@@ -0,0 +1,11 @@
+/**
+ * X（原 Twitter）搜索工具：POST /v1/x/search，过滤参数全量透传。
+ * allowed/excluded handles 互斥且各 ≤20（不含 @）；日期 YYYY-MM-DD。
+ * 按次计费到余额，失败调用不计费。
+ * @module dsh-kenari-plugin/tools/x-search
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import type { ToolsDeps } from './shared.js';
+/** 注册 kenari_x_search。 */
+export declare function registerXSearchTool(deps: ToolsDeps, register: (tool: ReturnType<typeof defineTool>) => void): void;
+//# sourceMappingURL=x-search.d.ts.map

package/lib/tools/x-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x-search.d.ts","sourceRoot":"","sources":["../../src/tools/x-search.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AA4B5C,0BAA0B;AAC1B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,GAAG,IAAI,CA+FlH"}

package/lib/tools/x-search.js

@@ -0,0 +1,129 @@
+/**
+ * X（原 Twitter）搜索工具：POST /v1/x/search，过滤参数全量透传。
+ * allowed/excluded handles 互斥且各 ≤20（不含 @）；日期 YYYY-MM-DD。
+ * 按次计费到余额，失败调用不计费。
+ * @module dsh-kenari-plugin/tools/x-search
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { billSpend, spendGuard } from './shared.js';
+import { kenariPost } from '../http.js';
+/** handle 约束：≤20 个、不含 @（OpenAPI pattern 限字母数字下划线）。 */
+const MAX_HANDLES = 20;
+/** 校验 handle 数组：去 @ 前缀、查数量与字符集；违规抛参数错误。 */
+function normalizeHandles(handles, field) {
+    const stripped = handles.map((handle) => handle.replace(/^@/, ''));
+    if (stripped.length > MAX_HANDLES) {
+        throw new Error(`${field} 最多 ${MAX_HANDLES} 个，收到 ${stripped.length} 个`);
+    }
+    for (const handle of stripped) {
+        if (!/^[A-Za-z0-9_]{1,40}$/.test(handle)) {
+            throw new Error(`${field} 含非法 handle "${handle}"：只允许字母、数字、下划线（不含 @）`);
+        }
+    }
+    return stripped;
+}
+/** 日期形参校验：只验形状（YYYY-MM-DD），语义由 Kenari 侧把关。 */
+function assertDate(value, field) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        throw new Error(`${field} 必须是 YYYY-MM-DD 格式，收到 "${value}"`);
+    }
+}
+/** 注册 kenari_x_search。 */
+export function registerXSearchTool(deps, register) {
+    register(defineTool({
+        name: 'kenari_x_search',
+        description: 'Search X (Twitter) live via Kenari and get a synthesized answer with x.com source links. Billed per search to your Kenari balance. Optional filters: allowed/excluded handles (mutually exclusive, max 20, no @), date range, image/video understanding.',
+        parameters: {
+            query: { type: 'string', required: true, description: 'The X search query. Must be non-empty.' },
+            allowed_x_handles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only include posts from these handles. Cannot be combined with excluded_x_handles. Max 20, without @.',
+            },
+            excluded_x_handles: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Exclude posts from these handles. Cannot be combined with allowed_x_handles. Max 20, without @.',
+            },
+            from_date: { type: 'string', description: 'Start date, YYYY-MM-DD.' },
+            to_date: { type: 'string', description: 'End date, YYYY-MM-DD.' },
+            enable_image_understanding: { type: 'boolean', description: 'Let the backend read images in posts.' },
+            enable_video_understanding: { type: 'boolean', description: 'Let the backend read videos in posts.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    answer: { type: 'string', required: true },
+                    citations: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                url: { type: 'string' },
+                                title: { type: 'string' },
+                            },
+                        },
+                    },
+                    cost_micro_idr: { type: 'integer' },
+                    text: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.text }],
+        },
+        timeoutMs: 60_000,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            spendGuard(deps, exec, 'kenari_x_search');
+            // 互斥与形状约束 schema 表达不了，参数级校验（硬约束：同传报参数错）
+            if (args.allowed_x_handles !== undefined && args.excluded_x_handles !== undefined) {
+                throw new Error('allowed_x_handles 与 excluded_x_handles 不可同时使用');
+            }
+            if (args.query.trim().length === 0) {
+                throw new Error('query 不能为空');
+            }
+            const filter = {};
+            if (args.allowed_x_handles !== undefined) {
+                filter.allowed_x_handles = normalizeHandles(args.allowed_x_handles, 'allowed_x_handles');
+            }
+            if (args.excluded_x_handles !== undefined) {
+                filter.excluded_x_handles = normalizeHandles(args.excluded_x_handles, 'excluded_x_handles');
+            }
+            if (args.from_date !== undefined) {
+                assertDate(args.from_date, 'from_date');
+                filter.from_date = args.from_date;
+            }
+            if (args.to_date !== undefined) {
+                assertDate(args.to_date, 'to_date');
+                filter.to_date = args.to_date;
+            }
+            if (args.enable_image_understanding !== undefined)
+                filter.enable_image_understanding = args.enable_image_understanding;
+            if (args.enable_video_understanding !== undefined)
+                filter.enable_video_understanding = args.enable_video_understanding;
+            const body = { query: args.query };
+            if (Object.keys(filter).length > 0)
+                body.x_search_filter = filter;
+            const result = await kenariPost(deps.http, '/x/search', body);
+            const citations = (result.citations ?? [])
+                .map((c) => `- [${c.title ?? c.url}](${c.url})`)
+                .join('\n');
+            const billed = await billSpend(deps, exec, {
+                tool: 'kenari_x_search',
+                costMicroIdr: result.cost_micro_idr,
+                note: '按次计费',
+            });
+            const text = `${result.answer ?? '(无答案)'}${citations.length > 0 ? `\n\n来源：\n${citations}` : ''}${billed}`;
+            return {
+                answer: result.answer ?? '',
+                citations: result.citations ?? [],
+                ...(result.cost_micro_idr !== undefined ? { cost_micro_idr: result.cost_micro_idr } : {}),
+                text,
+            };
+        },
+    }));
+}
+//# sourceMappingURL=x-search.js.map

package/lib/tools/x-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x-search.js","sourceRoot":"","sources":["../../src/tools/x-search.ts"],"names":[],"mappings":"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"}

package/lib/web/fallback.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 组合 provider：Kenari 优先，调用失败后回退 dsh 默认 provider。
+ * web seam 无回退链（硬约束 6），回退只能在调用失败后发生；
+ * 兜底实例只实例化不注册（硬约束 3）。
+ * @module dsh-kenari-plugin/web/fallback
+ */
+import { DeepSeekSearchProvider } from '@deepseek-ai/dsh-web-search-deepseek';
+import { HttpFetchProvider } from '@deepseek-ai/dsh-web-fetch-http';
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult, WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+/** 回退日志的最小形状（ctx.logger 满足）。 */
+export interface FallbackLogger {
+    warn(msg: string): void;
+    info(msg: string): void;
+}
+/**
+ * Kenari 优先搜索。Kenari available() 恒真（key 缺失在调用时以 WebError 暴露，
+ * 因为 available() 禁止网络请求），所以选择权在 seam，回退在本类内部完成。
+ */
+export declare class KenariFirstSearch implements WebSearchProvider {
+    private readonly kenari;
+    private readonly official;
+    private readonly logger?;
+    readonly id = "kenari-fallback";
+    constructor(kenari: WebSearchProvider, official: DeepSeekSearchProvider, logger?: FallbackLogger | undefined);
+    /** Kenari 或官方任一可用即选择本组合 provider。 */
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+/** Kenari 优先抓取，回退到本地匿名 HTTP provider。 */
+export declare class KenariFirstFetch implements WebFetchProvider {
+    private readonly kenari;
+    private readonly local;
+    private readonly logger?;
+    readonly id = "kenari-fallback";
+    constructor(kenari: WebFetchProvider, local: HttpFetchProvider, logger?: FallbackLogger | undefined);
+    available(): boolean;
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}
+//# sourceMappingURL=fallback.d.ts.map

package/lib/web/fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../src/web/fallback.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAA;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AACnE,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EAChB,MAAM,sBAAsB,CAAA;AAE7B,gCAAgC;AAChC,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAaD;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IAIvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAN1B,QAAQ,CAAC,EAAE,qBAAoB;gBAGZ,MAAM,EAAE,iBAAiB,EAEzB,QAAQ,EAAE,sBAAsB,EAChC,MAAM,CAAC,EAAE,cAAc,YAAA;IAG1C,qCAAqC;IACrC,SAAS,IAAI,OAAO;IAId,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAaxF;AAED,yCAAyC;AACzC,qBAAa,gBAAiB,YAAW,gBAAgB;IAIrD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAN1B,QAAQ,CAAC,EAAE,qBAAoB;gBAGZ,MAAM,EAAE,gBAAgB,EAExB,KAAK,EAAE,iBAAiB,EACxB,MAAM,CAAC,EAAE,cAAc,YAAA;IAG1C,SAAS,IAAI,OAAO;IAKd,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;CAarF"}

package/lib/web/fallback.js

@@ -0,0 +1,79 @@
+/**
+ * 组合 provider：Kenari 优先，调用失败后回退 dsh 默认 provider。
+ * web seam 无回退链（硬约束 6），回退只能在调用失败后发生；
+ * 兜底实例只实例化不注册（硬约束 3）。
+ * @module dsh-kenari-plugin/web/fallback
+ */
+import { DeepSeekSearchProvider } from '@deepseek-ai/dsh-web-search-deepseek';
+import { HttpFetchProvider } from '@deepseek-ai/dsh-web-fetch-http';
+function logFallback(logger, outcome) {
+    logger?.warn(`kenari-fallback: ${outcome.direction} 失败后回退（${outcome.reason}，${outcome.elapsedMs}ms）`);
+}
+/**
+ * Kenari 优先搜索。Kenari available() 恒真（key 缺失在调用时以 WebError 暴露，
+ * 因为 available() 禁止网络请求），所以选择权在 seam，回退在本类内部完成。
+ */
+export class KenariFirstSearch {
+    kenari;
+    official;
+    logger;
+    id = 'kenari-fallback';
+    constructor(kenari, 
+    // 兜底实例：import 自 dsh 包入口，只实例化不注册（id 冲突会抛 WEB_DUPLICATE_PROVIDER）
+    official, logger) {
+        this.kenari = kenari;
+        this.official = official;
+        this.logger = logger;
+    }
+    /** Kenari 或官方任一可用即选择本组合 provider。 */
+    available() {
+        return this.kenari.available() || this.official.available();
+    }
+    async search(request, signal) {
+        const start = Date.now();
+        try {
+            return await this.kenari.search(request, signal);
+        }
+        catch (err) {
+            logFallback(this.logger, {
+                direction: `search "${request.query}"`,
+                reason: String(err),
+                elapsedMs: Date.now() - start,
+            });
+            return this.official.search(request, signal);
+        }
+    }
+}
+/** Kenari 优先抓取，回退到本地匿名 HTTP provider。 */
+export class KenariFirstFetch {
+    kenari;
+    local;
+    logger;
+    id = 'kenari-fallback';
+    constructor(kenari, 
+    // 同上：只实例化不注册
+    local, logger) {
+        this.kenari = kenari;
+        this.local = local;
+        this.logger = logger;
+    }
+    available() {
+        // 本地 fetch provider 无凭据语义，available() 恒真
+        return this.kenari.available() || this.local.available();
+    }
+    async fetch(request, signal) {
+        const start = Date.now();
+        try {
+            return await this.kenari.fetch(request, signal);
+        }
+        catch (err) {
+            logFallback(this.logger, {
+                direction: `fetch "${request.url}"`,
+                reason: String(err),
+                elapsedMs: Date.now() - start,
+            });
+            return this.local.fetch(request, signal);
+        }
+    }
+}
+//# sourceMappingURL=fallback.js.map

package/lib/web/fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../../src/web/fallback.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAA;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA;AAuBnE,SAAS,WAAW,CAAC,MAAkC,EAAE,OAAwB;IAC/E,MAAM,EAAE,IAAI,CAAC,oBAAoB,OAAO,CAAC,SAAS,UAAU,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,KAAK,CAAC,CAAA;AACvG,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IAIT;IAEA;IACA;IANV,EAAE,GAAG,iBAAiB,CAAA;IAE/B,YACmB,MAAyB;IAC1C,gEAAgE;IAC/C,QAAgC,EAChC,MAAuB;QAHvB,WAAM,GAAN,MAAM,CAAmB;QAEzB,aAAQ,GAAR,QAAQ,CAAwB;QAChC,WAAM,GAAN,MAAM,CAAiB;IACvC,CAAC;IAEJ,qCAAqC;IACrC,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAA;IAC7D,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAyB,EAAE,MAAoB;QAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACxB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAClD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE;gBACvB,SAAS,EAAE,WAAW,OAAO,CAAC,KAAK,GAAG;gBACtC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;gBACnB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aAC9B,CAAC,CAAA;YACF,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC;CACF;AAED,yCAAyC;AACzC,MAAM,OAAO,gBAAgB;IAIR;IAEA;IACA;IANV,EAAE,GAAG,iBAAiB,CAAA;IAE/B,YACmB,MAAwB;IACzC,aAAa;IACI,KAAwB,EACxB,MAAuB;QAHvB,WAAM,GAAN,MAAM,CAAkB;QAExB,UAAK,GAAL,KAAK,CAAmB;QACxB,WAAM,GAAN,MAAM,CAAiB;IACvC,CAAC;IAEJ,SAAS;QACP,yCAAyC;QACzC,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAA;IAC1D,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAwB,EAAE,MAAoB;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACxB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QACjD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE;gBACvB,SAAS,EAAE,UAAU,OAAO,CAAC,GAAG,GAAG;gBACnC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;gBACnB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;aAC9B,CAAC,CAAA;YACF,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC;CACF"}

package/lib/web/fetch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Kenari web 抓取 provider：`POST /v1/web/fetch` 映射为 seam 的 WebFetchProvider。
+ * Kenari 返回纯文本正文；seam 的非 2xx 是结果不是错误，这里恒报 200（Kenari 已代抓）。
+ * @module dsh-kenari-plugin/web/fetch
+ */
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@deepseek-ai/dsh-web';
+import type { KenariHttpDeps } from '../http.js';
+import type { RecordWebSpend } from './search.js';
+export declare const KENARI_FETCH_PROVIDER_ID = "kenari-fallback";
+export declare class KenariFetchProvider implements WebFetchProvider {
+    private readonly deps;
+    private readonly recordSpend?;
+    readonly id = "kenari-fallback";
+    constructor(deps: KenariHttpDeps, recordSpend?: RecordWebSpend | undefined);
+    /** key 现场解析，本地判定可用性；不发网络请求。 */
+    available(): boolean;
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}
+//# sourceMappingURL=fetch.d.ts.map

package/lib/web/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/web/fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC7F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD,eAAO,MAAM,wBAAwB,oBAAoB,CAAA;AAKzD,qBAAa,mBAAoB,YAAW,gBAAgB;IAIxD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAJ/B,QAAQ,CAAC,EAAE,qBAA2B;gBAGnB,IAAI,EAAE,cAAc,EACpB,WAAW,CAAC,EAAE,cAAc,YAAA;IAG/C,+BAA+B;IAC/B,SAAS,IAAI,OAAO;IAId,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;CAsBrF"}

package/lib/web/fetch.js

@@ -0,0 +1,41 @@
+/**
+ * Kenari web 抓取 provider：`POST /v1/web/fetch` 映射为 seam 的 WebFetchProvider。
+ * Kenari 返回纯文本正文；seam 的非 2xx 是结果不是错误，这里恒报 200（Kenari 已代抓）。
+ * @module dsh-kenari-plugin/web/fetch
+ */
+import { kenariPost } from '../http.js';
+export const KENARI_FETCH_PROVIDER_ID = 'kenari-fallback';
+/** fetch 正文尾部最多附带的链接数，防 links[] 过长污染上下文。 */
+const MAX_APPENDED_LINKS = 20;
+export class KenariFetchProvider {
+    deps;
+    recordSpend;
+    id = KENARI_FETCH_PROVIDER_ID;
+    constructor(deps, recordSpend) {
+        this.deps = deps;
+        this.recordSpend = recordSpend;
+    }
+    /** key 现场解析，本地判定可用性；不发网络请求。 */
+    available() {
+        return true;
+    }
+    async fetch(request, signal) {
+        const response = await kenariPost(this.deps, '/web/fetch', { url: request.url }, signal);
+        if (typeof response.cost_micro_idr === 'number')
+            this.recordSpend?.(response.cost_micro_idr, 'fetch');
+        const links = response.links ?? [];
+        const bodyParts = [response.content ?? ''];
+        if (links.length > 0) {
+            // links[] 附正文尾部（任务包要求），空行分隔便于 consumer 展示
+            bodyParts.push('', links.slice(0, MAX_APPENDED_LINKS).join('\n'));
+        }
+        return {
+            url: request.url,
+            // Kenari 代抓正文成功即视为 200；目标站错误已在 Kenari 侧消化为正文内容
+            statusCode: 200,
+            body: { kind: 'text', content: bodyParts.join('\n') },
+            truncated: false,
+        };
+    }
+}
+//# sourceMappingURL=fetch.js.map

package/lib/web/fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/web/fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,UAAU,EAA4B,MAAM,YAAY,CAAA;AAGjE,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAA;AAEzD,4CAA4C;AAC5C,MAAM,kBAAkB,GAAG,EAAE,CAAA;AAE7B,MAAM,OAAO,mBAAmB;IAIX;IACA;IAJV,EAAE,GAAG,wBAAwB,CAAA;IAEtC,YACmB,IAAoB,EACpB,WAA4B;QAD5B,SAAI,GAAJ,IAAI,CAAgB;QACpB,gBAAW,GAAX,WAAW,CAAiB;IAC5C,CAAC;IAEJ,+BAA+B;IAC/B,SAAS;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAAwB,EAAE,MAAoB;QACxD,MAAM,QAAQ,GAAG,MAAM,UAAU,CAC/B,IAAI,CAAC,IAAI,EACT,YAAY,EACZ,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EACpB,MAAM,CACP,CAAA;QACD,IAAI,OAAO,QAAQ,CAAC,cAAc,KAAK,QAAQ;YAAE,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,CAAA;QACrG,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAA;QAClC,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;QAC1C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,0CAA0C;YAC1C,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QACnE,CAAC;QACD,OAAO;YACL,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,+CAA+C;YAC/C,UAAU,EAAE,GAAG;YACf,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACrD,SAAS,EAAE,KAAK;SACjB,CAAA;IACH,CAAC;CACF"}

package/lib/web/search.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Kenari web 搜索 provider：`POST /v1/web/search` 映射为 seam 的 WebSearchProvider。
+ * available() 只做本地检查（硬约束 5）；字段映射集中在文件顶部便于跟进 rc 变动。
+ * @module dsh-kenari-plugin/web/search
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@deepseek-ai/dsh-web';
+import type { KenariHttpDeps } from '../http.js';
+/** seam 词汇 → Kenari 请求的映射要点（对照知识库 kenari-api.md）。 */
+export declare const KENARI_SEARCH_PROVIDER_ID = "kenari-fallback";
+/** 计费回调：web 搜索按次扣费，记进共享账本（无会话归属，落 global 作用域）。 */
+export type RecordWebSpend = (microIdr: number, kind: 'search' | 'fetch') => void;
+export declare class KenariSearchProvider implements WebSearchProvider {
+    private readonly deps;
+    private readonly recordSpend?;
+    readonly id = "kenari-fallback";
+    constructor(deps: KenariHttpDeps, recordSpend?: RecordWebSpend | undefined);
+    /** key 现场解析，本地判定可用性；不发网络请求。 */
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+//# sourceMappingURL=search.d.ts.map

package/lib/web/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/web/search.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAmB,MAAM,sBAAsB,CAAA;AACjH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAOhD,qDAAqD;AACrD,eAAO,MAAM,yBAAyB,oBAAoB,CAAA;AAE1D,kDAAkD;AAClD,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,KAAK,IAAI,CAAA;AAEjF,qBAAa,oBAAqB,YAAW,iBAAiB;IAI1D,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAJ/B,QAAQ,CAAC,EAAE,qBAA4B;gBAGpB,IAAI,EAAE,cAAc,EACpB,WAAW,CAAC,EAAE,cAAc,YAAA;IAG/C,+BAA+B;IAC/B,SAAS,IAAI,OAAO;IAId,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAyBxF"}