dsh-kenari-plugin 0.1.1

package/lib/llm/recovery.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Kenari 路由的模型失败恢复：重试用尽后换模型，再不行回退默认 provider。
+ *
+ * 分工：5s × 5 的重试交给 dsh 自带的 `dsh-llm-retry`（声明式策略，见 `./retry.ts`），
+ * 本模块只负责它放弃之后的升级 —— 因为在同一个 step 内改 provider/model 是 dsh 没提供的缝。
+ *
+ * 两个监听器的注册顺序是设计的一部分，不是随手写的：
+ * 1. `agent/request` 用 `prepend` 挂在**最外层**。瀑布里外层拿最终决定权，而
+ *    `installModelSelection` 会用「本 step 组装时捕获的」原模型回写 —— 排在内层会被它改回去
+ *    （`packages/core/agent/src/model-selection.ts:88-105`）。
+ * 2. `agent/request-error` 用默认顺序，也就是内层：`dsh-llm-retry` 决定重试时不会 `next()`，
+ *    所以我们只在它放弃（码不可重试或次数用尽）之后才被调用。
+ * @module dsh-kenari-plugin/llm/recovery
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import type { ModelCandidates } from './candidates.js';
+/** 一次替换的目标路由。档位用 dsh 的 brand 类型，直接喂回 `agent/request` 才合法。 */
+export interface Target {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+}
+/** 恢复机制的可调输入与依赖。 */
+export interface ModelRecoveryDeps {
+    /** 总开关。false 时一个监听器都不装。 */
+    enabled: boolean;
+    /** 参与恢复的 provider 路由；范围外的失败原样交给下一个监听者。 */
+    providers: readonly string[];
+    /** 是否允许换模型；false 时只依赖 dsh 的重试，用尽后该轮以 error 结束。 */
+    switchEnabled: boolean;
+    /** 换模型/回退前的等待毫秒数。 */
+    switchDelayMs: number;
+    /** 跳过「同 provider 换模型」、直接回退 provider 的失败码。 */
+    skipCodes: readonly string[];
+    /** 是否注入模型切换通知。 */
+    noticeEnabled: boolean;
+    candidates: ModelCandidates;
+    /** dsh 默认 provider/model；服务缺失时返回 undefined，回退阶段自动退化为放弃。 */
+    defaultSelection: () => Target | undefined;
+    logger?: {
+        warn(msg: string): void;
+        info(msg: string): void;
+    };
+}
+/** 装上恢复机制。调用方负责只在 llm seam 存在时调用（`ctx.inject(['llm'], …)`）。 */
+export declare function installModelRecovery(ctx: Context, deps: ModelRecoveryDeps): void;
+//# sourceMappingURL=recovery.d.ts.map

package/lib/llm/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/llm/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAK7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAKtD,6DAA6D;AAC7D,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,CAAC,EAAE,iBAAiB,CAAA;CACpC;AAUD,oBAAoB;AACpB,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,OAAO,EAAE,OAAO,CAAA;IAChB,0CAA0C;IAC1C,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,kDAAkD;IAClD,aAAa,EAAE,OAAO,CAAA;IACtB,qBAAqB;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,kBAAkB;IAClB,aAAa,EAAE,OAAO,CAAA;IACtB,UAAU,EAAE,eAAe,CAAA;IAC3B,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC1C,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAC9D;AAUD,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CA8FhF"}

package/lib/llm/recovery.js

@@ -0,0 +1,118 @@
+/**
+ * Kenari 路由的模型失败恢复：重试用尽后换模型，再不行回退默认 provider。
+ *
+ * 分工：5s × 5 的重试交给 dsh 自带的 `dsh-llm-retry`（声明式策略，见 `./retry.ts`），
+ * 本模块只负责它放弃之后的升级 —— 因为在同一个 step 内改 provider/model 是 dsh 没提供的缝。
+ *
+ * 两个监听器的注册顺序是设计的一部分，不是随手写的：
+ * 1. `agent/request` 用 `prepend` 挂在**最外层**。瀑布里外层拿最终决定权，而
+ *    `installModelSelection` 会用「本 step 组装时捕获的」原模型回写 —— 排在内层会被它改回去
+ *    （`packages/core/agent/src/model-selection.ts:88-105`）。
+ * 2. `agent/request-error` 用默认顺序，也就是内层：`dsh-llm-retry` 决定重试时不会 `next()`，
+ *    所以我们只在它放弃（码不可重试或次数用尽）之后才被调用。
+ * @module dsh-kenari-plugin/llm/recovery
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { isRecoveryProvider, sleepUnlessAborted } from './retry.js';
+/** 决定本次失败后进入哪个阶段；undefined 表示放弃。 */
+function planStage(stage, code, deps) {
+    if (!deps.switchEnabled)
+        return undefined;
+    if (stage === 0)
+        return deps.skipCodes.includes(code) ? 2 : 1;
+    if (stage === 1)
+        return 2;
+    return undefined;
+}
+/** 装上恢复机制。调用方负责只在 llm seam 存在时调用（`ctx.inject(['llm'], …)`）。 */
+export function installModelRecovery(ctx, deps) {
+    if (!deps.enabled)
+        return;
+    const states = new WeakMap();
+    // 最外层：先拿到全链结果再覆盖，才能盖过 installModelSelection 用组装快照做的回写
+    ctx.on('agent/request', async ({ agent }, next) => {
+        const resolved = await next();
+        const target = states.get(agent.session)?.target;
+        if (target === undefined)
+            return resolved;
+        // 档位是 adapter-owned、按模型定义的：把上一个模型的档位搬给新模型可能直接非法，所以丢掉
+        const { reasoningEffort: _dropped, ...rest } = resolved;
+        return {
+            ...rest,
+            provider: target.provider,
+            model: target.model,
+            ...(target.reasoningEffort === undefined ? {} : { reasoningEffort: target.reasoningEffort }),
+        };
+    }, { prepend: true });
+    ctx.on('agent/request-error', async ({ agent, turn, step, provider, failure, signal }) => {
+        if (!isRecoveryProvider(provider, deps.providers))
+            return undefined;
+        if (signal.aborted)
+            return undefined;
+        const session = agent.session;
+        const current = session.requestContext();
+        const currentModel = current?.model;
+        if (currentModel === undefined)
+            return undefined;
+        const stepKey = `${turn}:${step}`;
+        const previous = states.get(session);
+        const state = previous?.stepKey === stepKey ? previous : { stepKey, stage: 0 };
+        states.set(session, state);
+        const planned = planStage(state.stage, failure.code, deps);
+        if (planned === undefined) {
+            states.delete(session);
+            return undefined;
+        }
+        let target;
+        let entered = 2;
+        if (planned === 1) {
+            const candidate = await deps.candidates.pick({
+                provider,
+                model: currentModel,
+                ...(current?.contextWindow === undefined ? {} : { contextWindow: current.contextWindow }),
+                signal,
+            });
+            if (candidate !== undefined) {
+                target = { provider: candidate.provider, model: candidate.model };
+                entered = 1;
+            }
+        }
+        if (target === undefined) {
+            const fallback = deps.defaultSelection();
+            // 已经处于默认路由时「回退」是空操作；重试同一个组合没有意义
+            if (fallback === undefined || (fallback.provider === provider && fallback.model === currentModel)) {
+                states.delete(session);
+                return undefined;
+            }
+            target = { ...fallback };
+        }
+        state.stage = entered;
+        state.target = target;
+        const from = `${provider}/${currentModel}`;
+        const to = `${target.provider}/${target.model}`;
+        deps.logger?.warn(`kenari: ${from} 失败（${failure.code}），${entered === 1 ? '换模型' : '回退默认 provider'}为 ${to}`);
+        if (deps.noticeEnabled) {
+            // 换模型对用户是可见的行为变化（风格与能力都会变），静默切换会让人困惑。
+            // 形态照抄 dsh 自己的 modelSwitchNotice，走 inject 排到下一个 step 的 pre-step。
+            agent.inject(createUserMessage({
+                content: [{ type: 'text', text: `[kenari: ${from} 连续失败（${failure.code}），已切换到 ${to}]` }],
+                source: { kind: 'plugin', plugin: 'kenari', form: 'notice', summary: `${from} → ${to}` },
+            }));
+        }
+        const waited = await sleepUnlessAborted(deps.switchDelayMs, signal);
+        if (!waited) {
+            states.delete(session);
+            return undefined;
+        }
+        return { kind: 'retry' };
+    });
+    // 用户显式选模型（会话日志追加 model/selection）时让人的选择优先。
+    // 只有 /model 命令会追加该事件，所以不会误清我们的 override。
+    ctx.on('session/event', (session, event) => {
+        // `model/selection` 的事件类型由 `@deepseek-ai/dsh-session-controller` 声明合并而来。
+        // 为了一个字符串比对上整个 session-controller 依赖不划算，所以按形状读。
+        if (event.type === 'model/selection')
+            states.delete(session);
+    });
+}
+//# sourceMappingURL=recovery.js.map

package/lib/llm/recovery.js.map

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

package/lib/llm/retry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 模型失败恢复的共享件：路由判定、重试策略装配、可取消延时。
+ *
+ * 为什么策略在这里拼：`LlmAdapter.providerRetryPolicy()` 只在适配器注册那一刻被调用一次，
+ * 返回值随即被 dsh 冻结进注册记录（`packages/llm/llm/src/index.ts:436-442`）。所以这里产出的
+ * 是「注册时的配置快照」—— 改 `modelRetryMaxRetries` 要重启 dsh 才生效，与 plugin-rules #10
+ * 对结构性字段的说明一致。
+ * @module dsh-kenari-plugin/llm/retry
+ */
+import type { ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm';
+/** 判定一个 provider 路由是否参与模型失败恢复。路由 id 是精确匹配，不做大小写归一。 */
+export declare function isRecoveryProvider(provider: string, configured: readonly string[]): boolean;
+/** 重试策略的可调输入，取自插件 Config。 */
+export interface KenariRetryInput {
+    /** 首次请求之后的额外重试次数。 */
+    maxRetries?: number;
+    /** 每次重试前的固定等待毫秒数。 */
+    delayMs?: number;
+    /** 允许重试的失败码；省略则用 dsh 默认集，但显式传空数组会被拒绝。 */
+    retryableCodes?: readonly string[];
+}
+/**
+ * 拼出 Kenari 路由的重试策略：固定间隔、无抖动。
+ *
+ * dsh 的退避是 `initialDelayMs * 2^n` 用 `maxDelayMs` 封顶，所以把两者设成同一个值、
+ * 关掉抖动，就得到「每次都等同样久」。「5s 后重试」只有这样才表达得准确。
+ */
+export declare function kenariRetryPolicy(input: KenariRetryInput): ResolvedRetryPolicy;
+/**
+ * 可取消的等待。返回 false 表示等待期间被取消，调用方应当放弃本次恢复而不是继续重试。
+ *
+ * 用 AbortSignal 而不是裸 setTimeout：用户在等待期间点了停止，不该再打一次模型请求。
+ */
+export declare function sleepUnlessAborted(ms: number, signal: AbortSignal): Promise<boolean>;
+//# sourceMappingURL=retry.d.ts.map

package/lib/llm/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/llm/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAqB,MAAM,sBAAsB,CAAA;AAElF,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE3F;AAED,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,mBAAmB,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAapF"}

package/lib/llm/retry.js

@@ -0,0 +1,53 @@
+/**
+ * 模型失败恢复的共享件：路由判定、重试策略装配、可取消延时。
+ *
+ * 为什么策略在这里拼：`LlmAdapter.providerRetryPolicy()` 只在适配器注册那一刻被调用一次，
+ * 返回值随即被 dsh 冻结进注册记录（`packages/llm/llm/src/index.ts:436-442`）。所以这里产出的
+ * 是「注册时的配置快照」—— 改 `modelRetryMaxRetries` 要重启 dsh 才生效，与 plugin-rules #10
+ * 对结构性字段的说明一致。
+ * @module dsh-kenari-plugin/llm/retry
+ */
+import { resolveRetryPolicy } from '@deepseek-ai/dsh-llm';
+/** 判定一个 provider 路由是否参与模型失败恢复。路由 id 是精确匹配，不做大小写归一。 */
+export function isRecoveryProvider(provider, configured) {
+    return configured.includes(provider);
+}
+/**
+ * 拼出 Kenari 路由的重试策略：固定间隔、无抖动。
+ *
+ * dsh 的退避是 `initialDelayMs * 2^n` 用 `maxDelayMs` 封顶，所以把两者设成同一个值、
+ * 关掉抖动，就得到「每次都等同样久」。「5s 后重试」只有这样才表达得准确。
+ */
+export function kenariRetryPolicy(input) {
+    const delayMs = input.delayMs ?? 5_000;
+    const config = {
+        mode: 'normal',
+        maxRetries: input.maxRetries ?? 5,
+        ...(input.retryableCodes === undefined ? {} : { retryableCodes: [...input.retryableCodes] }),
+        backoff: { initialDelayMs: delayMs, maxDelayMs: delayMs, jitterRatio: 0 },
+    };
+    // resolveRetryPolicy 顺带做校验：maxRetries 非负、retryableCodes 非空
+    return resolveRetryPolicy(config, 'kenari.modelRecovery.retryPolicy');
+}
+/**
+ * 可取消的等待。返回 false 表示等待期间被取消，调用方应当放弃本次恢复而不是继续重试。
+ *
+ * 用 AbortSignal 而不是裸 setTimeout：用户在等待期间点了停止，不该再打一次模型请求。
+ */
+export function sleepUnlessAborted(ms, signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        let timer;
+        const settle = (waited) => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            resolve(waited);
+        };
+        const onAbort = () => settle(false);
+        timer = setTimeout(() => settle(true), ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=retry.js.map

package/lib/llm/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/llm/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAGzD,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,UAA6B;IAChF,OAAO,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAA;AACtC,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAuB;IACvD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAA;IACtC,MAAM,MAAM,GAAsB;QAChC,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,CAAC;QACjC,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;QAC5F,OAAO,EAAE,EAAE,cAAc,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE;KAC1E,CAAA;IACD,2DAA2D;IAC3D,OAAO,kBAAkB,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAA;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,EAAU,EAAE,MAAmB;IAChE,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACjD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,KAAgD,CAAA;QACpD,MAAM,MAAM,GAAG,CAAC,MAAe,EAAQ,EAAE;YACvC,IAAI,KAAK,KAAK,SAAS;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAA;YAC5C,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YAC5C,OAAO,CAAC,MAAM,CAAC,CAAA;QACjB,CAAC,CAAA;QACD,MAAM,OAAO,GAAG,GAAS,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACzC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;QAC1C,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/lib/plans.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Kenari 套餐表：`GET /api/plans` 同步 + TTL 缓存 + 模型覆盖索引。
+ *
+ * 这是**站点**端点（不在 `/v1` 下、不需要 key），官网的「Langganan」页就是读它渲染的；
+ * 每个套餐给一份 `scope_models`——请求命中覆盖列表里的模型才从套餐额度扣，
+ * 否则直接走预付余额。所以「这个模型哪些套餐能用」只有一个事实来源，就是这里。
+ *
+ * 形状比 API 线宽松：字段缺失、整体 404、官网改版都按"套餐数据不可用"处理，
+ * 需要它的界面降级为只显示能力标签，而不是把插件判为故障。
+ * @module dsh-kenari-plugin/plans
+ */
+import type { KenariHttpDeps } from './http.js';
+/** 一个订阅套餐：价格与它覆盖的模型列表。 */
+export interface KenariPlan {
+    id: string;
+    name: string;
+    /** 价格（IDR）；0 表示免费档。目录未公布时为 undefined。 */
+    priceIdr?: number;
+    /** 覆盖的模型 id（裸 id，不带 `:free` 后缀）。 */
+    scopeModels: string[];
+    /** 该套餐下缓存读取不计额度的模型 id。 */
+    freeCacheModels: string[];
+}
+/** 模型 id 的套餐归属：套餐名列表（含免费缓存标记）。 */
+export interface PlanCoverage {
+    /** 覆盖该模型的套餐名，按套餐表顺序。 */
+    plans: string[];
+    /** 其中对该模型免缓存读额度的套餐名。 */
+    freeCachePlans: string[];
+}
+/**
+ * 套餐表客户端：进程内 TTL 缓存（复用 `catalogCacheTtlMs`——两者都是"Kenari 的目录类事实"）。
+ * 并发请求合并到同一次抓取。
+ */
+export declare class KenariPlans {
+    private readonly deps;
+    private cache;
+    private inflight;
+    constructor(deps: KenariHttpDeps);
+    /** 缓存有效期取自实时配置：设置页改完下一次读取即生效。 */
+    private get ttlMs();
+    /**
+     * 抓取套餐表（公开端点，无需 key）。
+     * 失败上抛：调用方按"套餐数据缺失"降级，不要让它挡住模型目录。
+     */
+    list(signal?: AbortSignal): Promise<KenariPlan[]>;
+    /**
+     * 模型 id → 套餐归属索引。
+     *
+     * 索引键同时收裸 id 与 `:free` 形式：套餐表写 `hy3`，目录里 `hy3` 与 `hy3:free`
+     * 都可能是可路由的模型，两者都该算被覆盖。
+     */
+    coverage(signal?: AbortSignal): Promise<Map<string, PlanCoverage>>;
+    /** 清空缓存（测试与强制刷新用）。 */
+    invalidate(): void;
+}
+/** 覆盖查询：先按原 id，再按裸 id（目录带 `:free`、套餐表不带的场景）。 */
+export declare function coverageOf(index: Map<string, PlanCoverage>, modelId: string): PlanCoverage;
+//# sourceMappingURL=plans.d.ts.map

package/lib/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../src/plans.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAK/C,0BAA0B;AAC1B,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oCAAoC;IACpC,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,0BAA0B;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,wBAAwB;IACxB,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AA0BD;;;GAGG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,KAAK,CAAwD;IACrE,OAAO,CAAC,QAAQ,CAAmC;gBAEtB,IAAI,EAAE,cAAc;IAEjD,iCAAiC;IACjC,OAAO,KAAK,KAAK,GAEhB;IAED;;;OAGG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAyBvD;;;;;OAKG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAkBxE,sBAAsB;IACtB,UAAU,IAAI,IAAI;CAGnB;AAED,gDAAgD;AAChD,wBAAgB,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAE1F"}

package/lib/plans.js

@@ -0,0 +1,118 @@
+/**
+ * Kenari 套餐表：`GET /api/plans` 同步 + TTL 缓存 + 模型覆盖索引。
+ *
+ * 这是**站点**端点（不在 `/v1` 下、不需要 key），官网的「Langganan」页就是读它渲染的；
+ * 每个套餐给一份 `scope_models`——请求命中覆盖列表里的模型才从套餐额度扣，
+ * 否则直接走预付余额。所以「这个模型哪些套餐能用」只有一个事实来源，就是这里。
+ *
+ * 形状比 API 线宽松：字段缺失、整体 404、官网改版都按"套餐数据不可用"处理，
+ * 需要它的界面降级为只显示能力标签，而不是把插件判为故障。
+ * @module dsh-kenari-plugin/plans
+ */
+import { kenariPublicGet, siteEndpoint } from './http.js';
+/** 套餐端点路径（相对裸域）。 */
+const PLANS_PATH = '/api/plans';
+/** 去掉 `:free` 后缀：套餐表用裸 id，目录用带后缀的 id，join 前必须归一。 */
+function bareId(id) {
+    return id.endsWith(':free') ? id.slice(0, -5) : id;
+}
+/** 宽松解析一行套餐；缺 id/name 的行直接丢弃（不猜）。 */
+function parsePlan(row) {
+    if (typeof row !== 'object' || row === null)
+        return undefined;
+    const record = row;
+    const id = record.id;
+    const name = record.name;
+    if (typeof id !== 'string' || id.length === 0)
+        return undefined;
+    if (typeof name !== 'string' || name.length === 0)
+        return undefined;
+    const strings = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+    return {
+        id,
+        name,
+        ...(typeof record.price_idr === 'number' ? { priceIdr: record.price_idr } : {}),
+        scopeModels: strings(record.scope_models),
+        freeCacheModels: strings(record.free_cache_models),
+    };
+}
+/**
+ * 套餐表客户端：进程内 TTL 缓存（复用 `catalogCacheTtlMs`——两者都是"Kenari 的目录类事实"）。
+ * 并发请求合并到同一次抓取。
+ */
+export class KenariPlans {
+    deps;
+    cache;
+    inflight;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** 缓存有效期取自实时配置：设置页改完下一次读取即生效。 */
+    get ttlMs() {
+        return this.deps.config.catalogCacheTtlMs ?? 3_600_000;
+    }
+    /**
+     * 抓取套餐表（公开端点，无需 key）。
+     * 失败上抛：调用方按"套餐数据缺失"降级，不要让它挡住模型目录。
+     */
+    async list(signal) {
+        const cached = this.cache;
+        const ttlMs = this.ttlMs;
+        if (ttlMs > 0 && cached !== undefined && Date.now() - cached.fetchedAt < ttlMs) {
+            return cached.plans;
+        }
+        if (this.inflight !== undefined)
+            return this.inflight;
+        const request = kenariPublicGet(this.deps, siteEndpoint(this.deps.config.baseURL, PLANS_PATH), signal, { retries: 1 })
+            .then((payload) => {
+            const rows = Array.isArray(payload)
+                ? payload
+                : (typeof payload === 'object' && payload !== null && Array.isArray(payload.data)
+                    ? payload.data
+                    : []);
+            const plans = rows.map(parsePlan).filter((plan) => plan !== undefined);
+            this.cache = { plans, fetchedAt: Date.now() };
+            return plans;
+        })
+            .finally(() => {
+            this.inflight = undefined;
+        });
+        this.inflight = request;
+        return request;
+    }
+    /**
+     * 模型 id → 套餐归属索引。
+     *
+     * 索引键同时收裸 id 与 `:free` 形式：套餐表写 `hy3`，目录里 `hy3` 与 `hy3:free`
+     * 都可能是可路由的模型，两者都该算被覆盖。
+     */
+    async coverage(signal) {
+        const plans = await this.list(signal);
+        const index = new Map();
+        const record = (id, planName, freeCache) => {
+            for (const candidate of id.endsWith(':free') ? [id] : [id, `${id}:free`]) {
+                const entry = index.get(candidate) ?? { plans: [], freeCachePlans: [] };
+                const bucket = freeCache ? entry.freeCachePlans : entry.plans;
+                if (!bucket.includes(planName))
+                    bucket.push(planName);
+                index.set(candidate, entry);
+            }
+        };
+        for (const plan of plans) {
+            for (const id of plan.scopeModels)
+                record(id, plan.name, false);
+            for (const id of plan.freeCacheModels)
+                record(id, plan.name, true);
+        }
+        return index;
+    }
+    /** 清空缓存（测试与强制刷新用）。 */
+    invalidate() {
+        this.cache = undefined;
+    }
+}
+/** 覆盖查询：先按原 id，再按裸 id（目录带 `:free`、套餐表不带的场景）。 */
+export function coverageOf(index, modelId) {
+    return index.get(modelId) ?? index.get(bareId(modelId)) ?? { plans: [], freeCachePlans: [] };
+}
+//# sourceMappingURL=plans.js.map

package/lib/plans.js.map

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

package/lib/session-title.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 会话标题前缀：`yyyyMMddHHmmss-`（模板可自定义，可开关）。
+ *
+ * dsh 的标题是 log-only 的 `session/title` 事件，事件数据固定为
+ * `{ title, messageSeqs, source }` —— 没有独立的前缀字段，前缀只能是 title
+ * 字符串的一部分。所以本模块在服务端事件层统一改写：剥掉旧前缀、按本会话的
+ * 开始时间（本机时区）重算，再 append 一条同源事件；标题取最后一条，因此 Web、
+ * TUI、headless 读到的是同一个字符串。
+ *
+ * 开始时间取「本会话第一条人类 `user/message` 的时间」，而不是
+ * `session.header.createdAt`：dsh 的 Web 侧会**复用空白会话**，记录可能在工作区
+ * 打开时就建好，比真正开口说话早几个小时，用 createdAt 会写出对不上的时间。
+ * 没有任何人类消息时（例如对空会话手动改名）才退回 `header.createdAt`；fork
+ * 子会话跳过 seed 继承的事件，所以拿到的是子会话自己的第一条消息。
+ *
+ * 不注册 provider、不改 dsh 行：监听器挂在 bundle 插件 ctx 上（未打 scope 标签的
+ * 上下文全局收得到会话事件），只在标题事件与 fork 创建时动手。自动标题
+ * （provider / fallback）与手动 rename 一视同仁 —— 浏览器 fork 之后会用一次
+ * `source.kind === 'user'` 的 rename 把父标题带进子会话，按 source 区分会在 fork
+ * 上漏改前缀。
+ *
+ * @module dsh-kenari-plugin/session-title
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 前缀的可调配置。全部用 thunk 读，改动在下一次标题事件即生效。 */
+export interface SessionTitlePrefixOptions {
+    /** 是否在生成标题时写入前缀。 */
+    readonly enabled: () => boolean;
+    /** 前缀模板：token `yyyy/MM/dd/HH/mm/ss`（本机时区），其余字符原样。 */
+    readonly template: () => string;
+    /** 前缀 + 正文的 UTF-8 总字节预算。 */
+    readonly maxBytes: () => number;
+}
+/**
+ * 按会话创建时间渲染前缀模板。
+ * @param template - 前缀模板。
+ * @param createdAt - 会话创建时刻（epoch 毫秒）。
+ * @returns 渲染后的前缀；不含 token 的模板即模板本身。
+ */
+export declare function renderTitlePrefix(template: string, createdAt: number): string;
+/**
+ * 写入设置页时的本地校验：schema 表达不了的约束在这里拦下。
+ * @param options - 当前配置值。
+ * @throws 模板为空/渲染为空/含控制字符/过长，或字节预算容不下前缀加最短正文时。
+ */
+export declare function validateSessionTitlePrefix(options: {
+    enabled: boolean;
+    template: string;
+    maxBytes: number;
+}): void;
+/**
+ * 在服务端标题事件上维护前缀。
+ *
+ * 每次标题事件与每次 fork 创建后：剥掉标题开头的一个已知前缀（本会话上次写入的、
+ * 父会话的、以及历史版本按记录创建时间写下的），开关开启时再拼上按本会话开始时间
+ * 渲染的前缀，然后 append 一条同源事件。同一标题重复触发时结果与当前一致，不会
+ * 追加事件。
+ *
+ * @param ctx - bundle 插件上下文；监听器随 fiber 卸载自动回收。
+ * @param options - 前缀开关、模板与字节预算。
+ */
+export declare function installSessionTitlePrefix(ctx: Context, options: SessionTitlePrefixOptions): void;
+//# sourceMappingURL=session-title.d.ts.map

package/lib/session-title.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-title.d.ts","sourceRoot":"","sources":["../src/session-title.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AA0ClD,yCAAyC;AACzC,MAAM,WAAW,yBAAyB;IACxC,oBAAoB;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAA;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAA;IAC/B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAA;CAChC;AAUD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAc7E;AA4ED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IAClD,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,IAAI,CAsBP;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAsGhG"}