dsh-router-core 0.4.6 → 0.4.7

package/lib/types/ext/contract.d.ts

@@ -65,7 +65,7 @@ export interface RouterExt {
      * 扩展自带的**子开关**（可选；不声明 = 只有总开关）。
      *
      * 为什么需要：有些扩展的「开/关」不是一件事而是**几件独立的事** —— 例如分层
-     * 提示词有 14 个准则分类，每条都该能单独关。硬塞进一个总开关 = 要么全给、
+     * 提示词的准则分类，每条都该能单独关。硬塞进一个总开关 = 要么全给、
      * 要么全不给。
      *
      * ⚠️ **与总开关的关系**：子开关是**叠加**在总开关之上的，总开关关 ⇒ 全部子开关
@@ -178,6 +178,25 @@ export interface ExtControl {
     readonly custom?: boolean;
     /** 文本被用户改过（决定「还原」按钮是否可点）。 */
     readonly overridden?: boolean;
+    /**
+     * 分组名（可选；缺省 = 无组）—— 面板按它把控制条**分节**渲染，组间插一条
+     * 组标题行，组内顺序照旧。**无组的条目照旧平铺** ⇒ 没用这个字段的扩展
+     * （ext-test 等）面板行为一个像素都不变。
+     *
+     * 为什么要有：一条扩展同时管两类东西时（分层提示词 = 准则分类 + 宿主段落），
+     * 平铺成一长列会让"哪条是准则、哪条是宿主的段"无从分辨 —— 分组是**归属
+     * 信息**，不是样式。
+     */
+    readonly group?: string;
+    /**
+     * 这一条参与拖动排序（可选；缺省 = 参与，保持既有行为）。
+     *
+     * 为什么需要显式关掉：排序落盘只认扩展自己的条目 id（`setControlOrder`
+     * 过滤未知 id）—— 宿主段落的 id 不在其中，拖它只会被静默丢弃 ⇒ 看起来能拖、
+     * 松手弹回，是假交互。**由扩展逐条声明**，与 `editable` 同一理由：能力在
+     * 实现方手里，由它说哪条有。
+     */
+    readonly sortable?: boolean;
 }
 /** 面板/API 用的一条扩展器信息 = 核心存的开关 + 插件报的运行时事实。 */
 export interface ExtInfo {

package/lib/types/ext-prompt/content.d.ts

@@ -20,6 +20,12 @@
  *      —— 它没有终止条件，每次收口都必然能再找出一件存量，等于无限循环。
  *   ② 固化：由"每次用户可见损失都必须固化"降级为"只对数据丢失/安全这类真损失
  *      补检查"，并删掉「不固化的教训等于决定再犯一次」这句无界义务。
+ *
+ * ⚠️ 2026-10-17 用户点名的两处改动：
+ *   ① **删掉「固化」分类**（整条移除，id `hardening` 不复存在）。用户已存的
+ *      `categories`/`text`/`order` 里残留的 `hardening` 键无须迁移 ——
+ *      `resolveCategories` 规则 2 会忽略不认识的 id。
+ *   ② 身份气质：「默认中文」→「回复、思考过程必须使用中文」。
  */
 /** 一个可独立开关的提示词分类。 */
 export interface PromptCategory {
@@ -43,7 +49,7 @@ export declare const PROMPT_CATEGORIES: readonly PromptCategory[];
  *
  * ⚠️ 拆分时差点丢它：原文是 `[…] ·身份气质：…`，标题挂在方括号里、
  *   **不属于任何单条分类**，按分隔符切分时自然被丢掉
- *   （只在 `content.ts` 头注出现过、没进任何 `body`）。⇒ 模型会看到 14 条
+ *   （只在 `content.ts` 头注出现过、没进任何 `body`）。⇒ 模型会看到一堆
  *   **没有名字**的规则，而"这套东西叫什么、为什么存在"恰恰是它需要的上下文。
  *
  * 形状：**不属于任何分类** ⇒ 不可被单条开关关掉（它一关，准则就无名无姓）。

package/lib/types/ext-prompt/mount.d.ts

@@ -23,10 +23,21 @@ export interface SystemPromptFace {
         order: number;
         text: string | (() => string);
     }): () => void;
-    getSectionOrder?(name: string): number;
+    /**
+     * 段落总控用（`index.ts` 的 waterfall 预热）：宿主 `SystemPrompt.assemble()`。
+     * 只声明用得到的最小形状 —— 返回的 `sections` 已按 order/name 排好序。
+     */
+    assemble(context?: Record<string, unknown>): Promise<{
+        sections: {
+            name: string;
+            text: string;
+        }[];
+    }>;
 }
 /** 段落名（**稳定**）：改名会让已注册的作用域 section 与旧名并存。 */
 export declare const PROMPT_SECTION_NAME = "dsh-router-ext-prompt:guideline";
+/** 官方 `SECTION_ORDERS` 里最低的那档（第一方开场白），测试用它当"最前"的判据。 */
+export declare const OFFICIAL_LOWEST_SECTION_ORDER = -1000;
 export interface MountPromptDeps {
     /** 取 `ctx.systemPrompt`（可能尚未就绪 ⇒ undefined）。 */
     getSystemPrompt: () => SystemPromptFace | undefined;

package/lib/types/ext-prompt/plugin.d.ts

@@ -13,6 +13,7 @@
  * 真正的注入在 `mount.ts`。
  */
 import type { ExtStoreService, RouterExt } from '../ext/contract.ts';
+import { type SectionEntry } from './sections.ts';
 /** 扩展开关表里的注册键。 */
 export declare const EXT_PROMPT_ID = "prompt";
 /**
@@ -29,4 +30,13 @@ export declare const EXT_PROMPT_ID = "prompt";
 export declare function createPromptExt(deps: {
     isSystemPromptReady: () => boolean;
     store?: ExtStoreService;
+    /**
+     * 当前已装配的段落清单（最近一次 `assemble` 的快照，来自 waterfall 缓存）。
+     *
+     * ⚠️ **必选，不给缺省**：缺省成 `() => []` 的话，`index.ts` 忘接这个参数
+     * 就是"段清单恒空"的静默失效（面板无段、过滤不生效，但一切照常跑）——
+     * 让类型红比让它静默强。**空清单是合法值**（还没预热完/宿主一段都没有），
+     * 与"没接线"的区分靠这里不给缺省，不靠运行时猜。
+     */
+    getSections: () => SectionEntry[];
 }): RouterExt;

package/lib/types/ext-prompt/render.d.ts

@@ -24,7 +24,7 @@ export interface PromptExtData {
     text?: Record<string, PromptCategoryOverride>;
     /**
      * 用户自建的准则条目。**与内置的 `PROMPT_CATEGORIES` 分开存** ——
-     * 内置那 14 条是**代码常量**（发版即定），混在一起就会出现"代码里有一条、
+     * 内置条目是**代码常量**（发版即定），混在一起就会出现"代码里有一条、
      * 落盘里又有一条"的归属问题：升级时新加的内置条目会和用户的旧数据打架。
      *
      * 存的是**完整条目**（不是覆盖值）：自建的东西没有"内置版本"可回退。
@@ -33,12 +33,23 @@ export interface PromptExtData {
     /**
      * 展示顺序：`[id, …]`，含内置与自建。
      *
-     * ⚠️ **只存 id 顺序，不重排内置数组本身**：内置 14 条的次序是 `content.ts`
+     * ⚠️ **只存 id 顺序，不重排内置数组本身**：内置条目的次序是 `content.ts`
      *   里的代码顺序，它同时是"准则作为一份文档的阅读顺序"；让用户拖动去改它，
      *   等于让代码顺序随某个用户的操作漂移 —— 别人拿到新版本看到的次序就变了。
      *   落盘只记"这次会话里按什么顺序显示"，代码顺序永远是兜底。
      */
     order?: string[];
+    /**
+     * 段落级开关：`{ [sectionName]: boolean }`，**只存关闭项**（`false` = 关）。
+     *
+     * 缺项 = 开（默认全开）——与 `text` 的"只存覆盖值"同一纪律：宿主的段落随
+     * 宿主/别的插件增删，存全文表就得在升级后逐条对账；只记"用户主动关了谁"
+     * 让新增段落自然落回默认（开），用户的选择不会被静默迁移。
+     *
+     * key 是**段的注册名**（如 `tool:write`），不是控制条 id（`sec:` 前缀是
+     * 传输层编码，落盘用裸名，见 sections.ts）。
+     */
+    sections?: Record<string, boolean>;
 }
 /** 一条分类上用户改过的字段（只记改了的那些）。 */
 export interface PromptCategoryOverride {
@@ -69,7 +80,7 @@ export declare function resolveEnabledCategories(masterOn: boolean, data: Prompt
  * 渲染成**一个**段落文本（多分类拼一起）。
  *
  * 为什么要拼成一段而不是一段一个：面板开关是"分类"粒度，而 prompt 读起来
- * 是一段连续的准则 —— 分成 14 个 section 会让 KV cache 每个分类各占一段、
+ * 是一段连续的准则 —— 分成多个 section 会让 KV cache 每个分类各占一段、
  * 增删任意一个分类都让其后全部位移。这里**注册一个 section，文本由开关拼装**。
  *
  * @returns 关闭的分类不进结果；全关 ⇒ 空串（上游 `renderPrompt` 会丢弃空段）。

package/lib/types/ext-prompt/sections.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 系统提示词**段落级**总控的纯逻辑与清单缓存 —— 把整体系统提示词拆成
+ * 每一段（`harness:identity`、`tool:write`、`plan:policy` …），面板分组列出、
+ * 逐段开关，关掉的段在装配时被过滤掉（`index.ts` 的 waterfall）。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 清单从哪来：`assemble()` 的真实产物，不写死宿主段名表
+ * ════════════════════════════════════════════════════════════════════
+ * 段名只有个别是宿主导出常量（`harness:identity`、`deployment:persona-*`），
+ * 其余（`tool:*`、`mcp:*`、第三方插件段）都埋在各自插件里 —— 写死清单必然漂移。
+ * 装配 waterfall（`system-prompt/assemble`）每轮都携带**全量已排序段落**，
+ * 顺路缓存一份就是面板的事实源；apply 时预热一次 assemble，没开始对话也有清单。
+ *
+ * ⚠️ 清单是**最近一次装配的快照**（近似）：`assemble()` 不带 scope 时只含
+ * global 段，真实对话是 agent scope；且多会话并发时缓存归"最后一次装配"。
+ * 面板展示可接受，**开关判定不受影响** —— 过滤按段名，名字缺席时无害跳过。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 开关的生效面：waterfall 删段，不碰别人的注册
+ * ════════════════════════════════════════════════════════════════════
+ * 宿主没有"禁用别人的段"的 API。两条路里选了 waterfall：`assemble()` 的
+ * 监听器返回值是权威结果（宿主源码 `return transformed`，complete 段除外），
+ * 删掉的段不会被恢复。同名覆盖（scoped section 返回 `''`）只适合"顶掉某一个
+ * 已知名字"，对同层自己注册的段还会 throw —— 删段才是对全部段通用的开关。
+ */
+import type { PromptExtData } from './render.ts';
+/** 面板控制条 id 的段前缀（**传输层编码**；落盘用裸段名，不带前缀）。 */
+export declare const SECTION_CONTROL_PREFIX = "sec:";
+/**
+ * 自己的准则段：**不进清单、不被过滤**。
+ *
+ * 它已有独立的开关体系（扩展总开关 + 14 个分类开关）——再列一条"段开关"
+ * 就是同一件事的第二个开关，两边状态会漂移；过滤它还会让分类开关看起来
+ * 失效（段没了，分类怎么切都看不到效果）。
+ */
+export declare const OWN_SECTION_NAME = "dsh-router-ext-prompt:guideline";
+/** 一条已装配的段（面板清单用）。 */
+export interface SectionEntry {
+    /** 段注册名（稳定；也是开关的落盘键）。 */
+    name: string;
+    /** 面板副行显示的原文（装配时 provider 现算的结果，**未做 `{{变量}}` 插值**）。 */
+    text: string;
+}
+/** `controlId`（`sec:…`）→ 段名；非段条目返回 null。 */
+export declare function sectionNameOf(controlId: string): string | null;
+/** 段名 → 面板控制条 id。 */
+export declare function sectionControlId(name: string): string;
+/**
+ * 段名的分组名。
+ *
+ * 查表顺序：**整名**（无冒号段名，如 `mcp-resource-servers`）→ **第一段前缀**
+ * （`tool:write` → `tool`）。两级都查不到 ⇒ 有冒号时用第一段原样当组名、
+ * 无冒号归「其他」。
+ */
+export declare function groupLabelOf(name: string): string;
+/** 面板条目标题：去掉组前缀的部分（`tool:write` → `write`；无冒号 = 全名）。 */
+export declare function sectionTitleOf(name: string): string;
+/**
+ * 当前被关掉的段名集合。**只认显式 `false`** —— 缺项是"没碰过"（默认开），
+ * 与 `resolveEnabledCategories` 对 `undefined` 的处置同一纪律。
+ */
+export declare function disabledSectionNames(data: PromptExtData | undefined): Set<string>;
+/**
+ * 过滤掉关闭的段（保序）。自己那段**恒放行**（理由见 `OWN_SECTION_NAME`）。
+ *
+ * ⚠️ 名字不在清单里的关闭项静默跳过：宿主段随版本增删，旧数据里的名字
+ * 失效是正常生命周期，报错只会把面板变成红字噪音。
+ */
+export declare function filterSections<T extends {
+    name: string;
+}>(sections: readonly T[], off: ReadonlySet<string>): T[];
+/**
+ * 段清单缓存：waterfall 监听器是**唯一写入者**（装配路径顺路喂），
+ * 面板 controls getter 只读。分组与排序都在读取端做 —— 缓存保持
+ * 装配原序（`assemble` 已按 order/name 排好），组的次序自然等于 prompt 次序。
+ */
+export declare function createSectionCache(): {
+    /** 用一次装配结果刷新（整表替换；自己的段不进清单）。 */
+    update: (sections: readonly {
+        name: string;
+        text: string;
+    }[]) => void;
+    /** 当前清单（拷贝，防调用方改缓存内部）。 */
+    list: () => SectionEntry[];
+};
+/** 一个分组（组名 + 组内条目，组内保持清单序）。 */
+export interface SectionGroup {
+    label: string;
+    items: SectionEntry[];
+}
+/**
+ * 按段名前缀分组；**组的先后 = 首次出现序**（清单已按 prompt 序 ⇒ 组序即
+ * 段落在 prompt 里的先后）——不按字母重排，面板顺序与模型看到的顺序一致。
+ */
+export declare function groupSections(list: readonly SectionEntry[]): SectionGroup[];

package/lib/types/protocol/anthropic.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Anthropic Messages 协议。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么第一个做它
+ * ════════════════════════════════════════════════════════════════════
+ * Claude Code 只会说这一种协议，而它对 `ANTHROPIC_BASE_URL` 的支持是现成的：
+ * 把它指到我们的端点，就**直接**能用上账号池/组合/用量看板。其余三种协议
+ * （Responses/Gemini）没有这样的「一个客户端在等」的理由。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 翻译表（唯一的事实来源）
+ * ════════════════════════════════════════════════════════════════════
+ *  请求  system            → messages[0] 的 system-role 消息（字符串或块数组都要吃）
+ *        tools[].input_schema → tools[].function.parameters
+ *        tool_use / tool_result 块 → assistant.tool_calls / role:"tool"
+ *        max_tokens / temperature / stop_sequences → 同名（下划线差异两处）
+ *  响应  message_start     → usage（input_tokens 在这帧）
+ *        content_block_start(text)     → text 增量开始
+ *        content_block_delta(text_delta) → text 增量
+ *        content_block_delta(input_json_delta) → tool-args 增量
+ *        content_block_delta(thinking_delta) → reasoning 增量
+ *        content_block_stop  → 该 index 结束（无对应规范事件，吃掉）
+ *        message_delta      → usage + finish_reason
+ *        message_stop       → 无对应事件（finish 已由 message_delta 给）
+ *
+ * 丢弃（明确不做翻译，见下）：
+ *   - `cache_control`：Anthropic 的提示缓存标记。跨到 Chat 后失去意义
+ *     （Chat 的缓存是上游自动的），硬造一个 `prompt_cache_key` 反而是猜。
+ *   - `thinking.budget_tokens`：只在响应侧保留为 reasoning 增量。
+ *   - `mcp_servers` / `container` / `context_management`：客户端侧特性，
+ *     转发到只懂 Chat 的上游只会得到 400。
+ */
+import { type ProtocolCodec } from './types.ts';
+export declare const anthropicCodec: ProtocolCodec;

package/lib/types/protocol/chat.d.ts

@@ -0,0 +1,25 @@
+/**
+ * OpenAI Chat Completions 协议 —— **规范形态本身**，所以编解码是恒等变换。
+ *
+ * 这个文件承担两件别处不做的事：
+ *
+ * 1. **请求侧恒等**：`toChat`/`fromChat` 原样返回。供应商契约
+ *    （`suppliers/contract.ts` 的 `chatOnce`）吃的就是 Chat Completions 请求体，
+ *    多一层拷贝只会让「哪一层改的」变难查。
+ *
+ * 2. **响应侧的规范事件翻译**：OpenAI SSE → `ChatEvent`，以及反向。这是**所有
+ *    协议共用的脊柱** —— Anthropic/Gemini 的 `decodeFrame` 拿到自己的帧后，
+ *    也要靠这里的逻辑把内容映射成同一组事件，才能让「Anthropic 客户端问、
+ *    Gemini 供应商答」这条路只有两个模块参与，而不是 12 条路径。
+ *
+ * ⚠️ 这里的映射规则与 `llm/adapter.ts` 的 `translateSse` 是**同一套语义的两种
+ *    落点**：那边翻译成 DSH 的 `StreamChunk`（给宿主 agent loop 用），这边翻译
+ *    成 `ChatEvent`（给协议矩阵用）。两处都留着，因为消费方不同、且
+ *    `translateSse` 里那些踩过坑的处理（残缺 tool_call 收尾、空串 name 剥除）
+ *    只对 DSH 有意义；但**改任何一处规则都必须看另一处**，否则同一个上游在
+ *    两个入口表现不一致。
+ */
+import { type ProtocolCodec, finishOf } from './types.ts';
+export declare const chatCodec: ProtocolCodec;
+/** 收尾原因 → 规范形态（在各协议模块里共用，从这再导出省一次 import）。 */
+export { finishOf };

package/lib/types/protocol/entry.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 入站协议的四个入口 —— 把四种协议的请求翻成规范请求、交给 Router，
+ * 再把 Router 的响应翻回客户端说的协议。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么 Router 不认识协议，翻译却全在这
+ * ════════════════════════════════════════════════════════════════════
+ * Router 的核心职责是「选号/冷却/回退/记账」，它不该知道世界上有几种协议。
+ * 所以这里只做三件与协议有关的事：认路径、翻请求体、翻响应体。剩下全部
+ * 委托给 `Router.chatCompletions` —— 于是四种协议**自动**获得账号池、
+ * 组合回退、首字节预算、断流补帧、用量统计，一个都不用重写。
+ *
+ * 挂载点见 `src/index.ts` 的 `route(...)` 调用处；新增第五种协议只改
+ * 这里 + `protocol/` 下加一个模块，`src/index.ts` 只多一行 route。
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { StreamState } from './stream.ts';
+import type { JsonObject, ProtocolId } from './types.ts';
+/** 一次入站请求解析后的结果。 */
+export interface InboundRequest {
+    /** 规范请求体（Chat Completions 形状）。 */
+    body: JsonObject;
+    /** 客户端要的流式。 */
+    stream: boolean;
+    /** 模型名（已从路径或请求体取出）。 */
+    model: string;
+    /** 推理等级；缺省 'auto'。 */
+    lv: string;
+    /** 客户端协议。 */
+    protocol: ProtocolId;
+}
+/**
+ * 读请求体 + 按协议翻成规范请求。
+ *
+ * 模型名从哪来因协议而异：Chat/Anthropic/Responses 在 body 的 `model`，
+ * Gemini 在 URL 路径（`:generateContent` 之前那段）—— 由 `modelFromPath`
+ * 调用方先解析好传进来。
+ */
+export declare function parseInbound(req: IncomingMessage, protocol: ProtocolId, opts: {
+    limitBytes: number;
+    modelFromPath?: string;
+    lvFromBody?: (body: JsonObject) => string;
+    /**
+     * 路径里已声明的流式意图。
+     *
+     * Gemini 是唯一把「流不流式」放在 **URL 路径**（`:streamGenerateContent`
+     * vs `:generateContent`）而不是 body 里的协议。不认它，Gemini 的流式请求
+     * 会被当成非流式处理 —— 客户端拿到一整个 JSON，而它按 SSE 解析 ⇒ 空响应
+     * （2026-10-21 在 3080 实测）。
+     *
+     * `undefined` = 路径没说，看 body；`true/false` = 路径已明确，body 不算数。
+     */
+    streamFromPath?: boolean;
+}): Promise<InboundRequest | {
+    error: string;
+    status: number;
+}>;
+/**
+ * 给 Router 的**非 chat 出口**：收集 OpenAI 形态的响应，翻译成客户端协议。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 两条路径分开处理，因为时序完全不同
+ * ════════════════════════════════════════════════════════════════════
+ *  非流式：Router 一次 `head(200) + end(json)`。整份 JSON 已在手里，
+ *          `decodeJson` → `encodeJson` 一个来回就完。
+ *  流式：  Router 分很多次 `write(bytes)`，且**第一个字节前可能失败换号**。
+ *          不能等收齐再翻（那就没有流式了）；每收到一段就翻一段。
+ *
+ * 流式那条为什么插一层 sink 而不是让 Router 直接写翻译后的字节：Router 的
+ * `writeChatResult` 里有一整套「客户端断开就取消上游流」「断流补 `[DONE]`」
+ * 的逻辑，那些必须继续对真实的 `res` 生效。sink 只是**转发的中继**：
+ * 它翻译字节、写给真正的 res；断开时调用方取消本层（见 index.ts 挂载处），
+ * Router 那侧的取消链路原样传到上游。
+ */
+export declare function outboundSink(protocol: ProtocolId, model: string, res: ServerResponse): ResponseSinkLike;
+/** Router 的 ResponseSink 形状（本地声明，避免 protocol → router 的循环依赖）。 */
+export interface ResponseSinkLike {
+    head?: (status: number, headers: Record<string, string>) => void;
+    write: (bytes: Uint8Array) => void;
+    end: () => void;
+}
+/**
+ * 一段上游 OpenAI SSE 文本的转码器 —— **有状态**。
+ *
+ * 上游一帧被拆在两个 TCP 段里是常态（Router 按拿到的字节原样转交），所以
+ * 分帧缓冲必须跨 `write()` 调用存活。这里用 `sse.ts` 的 `SseSplitter`（它内部
+ * 留着半个帧）而不是每次现切 —— 早先每次现切会把不完整帧当完整帧解析，
+ * 表现是「文本丢一半、工具参数截断」，而 HTTP 200，客户端看不到任何错误。
+ *
+ * 生命周期与 sink 一致：一个请求一个实例。
+ */
+export declare class ChunkTranslator {
+    private readonly splitter;
+    private readonly state;
+    constructor(state: StreamState);
+    /** 喂一段文本，返回可写给客户端的帧。 */
+    push(text: string): string[];
+    /** 流结束：冲刷残留帧（上游不发尾空行是有的），返回收尾帧。 */
+    end(): string[];
+    private emit;
+}
+/**
+ * 单次调用版：把一段**完整**的 SSE 文本转成客户端帧。
+ *
+ * 只适合「手里已经有一整段完整数据」的场合（测试、非流式上游误发了 SSE）。
+ * 真正的流式路径必须用 `ChunkTranslator` 保持跨段状态。
+ */
+export declare function translateChunk(state: StreamState, text: string): string[];
+/**
+ * 从 Gemini 的 URL 路径里取模型名。
+ *
+ * 形如 `/v1beta/models/<model>:generateContent`（或 `:streamGenerateContent`），
+ * `<model>` 本身可以含斜杠，所以取 `models/` 之后到最后一个 `:` 之前那段。
+ *
+ * **必须先切掉 query**：Gemini CLI 默认带 `?alt=sse`，不切的话 `$` 锚点匹配
+ * 不上，模型名变空 —— 表现为「404 model not found」而不是参数错误，很难查。
+ * 顺便支持 `/v1beta/models/<model>` 这种带版本号但无方法的形态（走 GET 列表时
+ * 会撞上，这里取不到 `/` 就是取不到，返回 undefined 让上层报 400）。
+ */
+export declare function geminiModelFromPath(pathname: string): string | undefined;
+/**
+ * Gemini 的流式意图在**路径尾部**：`:streamGenerateContent` 是流式、
+ * `:generateContent` 是非流式。返回 `undefined` 表示路径没表态（不是 Gemini
+ * 形态，或路径不可识别），交给 body 的 `stream` 决定。
+ *
+ * 为什么不能只看 body：Gemini 的请求体里**没有** `stream` 字段 —— 它的官方
+ * 契约就是靠 URL 区分两种方法。不认这个，流式请求会被当成非流式，客户端按
+ * SSE 解析一整个 JSON ⇒ 空响应（2026-10-21 在 3080 实测到）。
+ */
+export declare function geminiStreamFromPath(pathname: string): boolean | undefined;
+/**
+ * 从请求体取推理等级（各协议字段名不同）。
+ *
+ * 只认「明确说了要多少思考」的形态，其余一律 'auto'：把「有这个字段」当成
+ * 「要高档推理」会让所有带 thinking 块的请求都按 high 走，费用与延迟都变。
+ */
+export declare function lvOf(body: JsonObject, protocol: ProtocolId): string;

package/lib/types/protocol/gemini.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Google Gemini 协议（`generateContent` / `streamGenerateContent`）。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 与其他三种的差异
+ * ════════════════════════════════════════════════════════════════════
+ *  1. **模型名在 URL 路径里**：`/v1beta/models/<model>:generateContent`，
+ *     请求体里没有 `model` 字段。
+ *  2. **角色名不同**：`user` / `model`（不是 assistant）。
+ *  3. **内容是 parts**：`{parts:[{text}]}`，不是字符串。
+ *  4. **工具调用是整块**：`functionCall` part 一次给全 `{name,args}`，
+ *     没有增量形态 —— 故 decode 时拆成 tool-start + tool-args 一段。
+ *  5. **鉴权走 query 参数 `?key=`** 或 `x-goog-api-key` 头（不是 Bearer）。
+ *  6. **流式响应是 JSON 数组分片**（`[{...},{...}]`），不是 SSE ——
+ *     `streamGenerateContent?alt=sse` 才给 SSE。我们只支持 `alt=sse`，
+ *     非 SSE 形态明确不支持（见文件尾 `geminiStreamSse` 的说明）。
+ *
+ * 丢弃：`safetySettings` / `tools[].googleSearch` / `cachedContent` /
+ *      `systemInstruction` 之外的 `generationConfig` 大部分字段（只留
+ *      temperature / maxOutputTokens / stopSequences）。
+ */
+import { type JsonObject, type ProtocolCodec } from './types.ts';
+export declare const geminiCodec: ProtocolCodec;
+/**
+ * 工具名 ↔ index 的映射，**每个请求一份**。
+ *
+ * Gemini 没有 index 概念（工具调用靠 name 认），而规范事件用 index —— 所以
+ * 跨帧必须有映射，而跨**请求**必须没有。模块级 Map 会串名（并发两条流各自
+ * 的 `ls` 抢同一个 index，或者上一条流的映射残留到下一条），所以这里做成
+ * 每个编解码会话一个实例，由 `StreamState` / `entry.ts` 在请求边界创建。
+ *
+ * 谁在用：`decodeFrameInto` / `encodeFrameWith` 拿到同一个 `GeminiToolMap`；
+ * 单次调用（测试、非流式一次性转换）走 `geminiBodyEvents` 的默认实例。
+ */
+export interface GeminiToolMap {
+    /** 工具名 → 规范 index（同名复用同一个 index）。 */
+    indexOf(name: string): number;
+    /** 规范 index → 工具名（未知返回 ''）。 */
+    nameOf(index: number): string;
+    /** 记下「规范 index → 工具名」（`tool-start` 带上游 index 时用）。 */
+    remember(index: number, name: string): void;
+    /**
+     * 把一段参数增量累到该 index 上，返回**截至目前**的完整 JSON。
+     *
+     * Gemini 的 `functionCall.args` 是整块对象，没有增量形态；而上游（OpenAI
+     * 系）会把一次调用拆成很多 `arguments` 增量帧。逐帧发 `functionCall` 会让
+     * 客户端看到 N 次调用、且前 N-1 次 args 是空对象或半截 JSON
+     * （2026-10-21 在 3080 实测：5 个 `args:{}`）。所以只能攒。
+     */
+    appendArgs(index: number, delta: string): string;
+    /** 该 index 上是否有**完整可解析**的参数（流末判定用）。 */
+    completeArgs(index: number): JsonObject | undefined;
+    /** 攒过参数的所有 index（流末按序发出）。 */
+    pendingIndexes(): number[];
+}
+/** 新建一份空的工具名映射。 */
+export declare function newGeminiToolMap(): GeminiToolMap;

package/lib/types/protocol/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 协议注册表 —— 按 id 取编解码器。
+ *
+ * 刻意保持成一张**静态表**而不是注册机制：四种协议是编译期就知道的集合，
+ * 加第五种就是改这个文件 + 加一个模块，不需要运行时发现。做成可注册会让
+ * 「谁在什么时候注册了什么」变成运行时事实，而这里没有任何插件需要插进来
+ * （供应商 wire 是另一回事，见 `suppliers/contract.ts` 的 `wire`）。
+ */
+import type { ProtocolCodec, ProtocolId } from './types.ts';
+/** 取编解码器。id 已由 `isProtocolId` 校验过，这里不再兜底。 */
+export declare function codecOf(id: ProtocolId): ProtocolCodec;
+/** 全部编解码器（文档与测试用）。 */
+export declare function allCodecs(): ProtocolCodec[];

package/lib/types/protocol/responses.d.ts

@@ -0,0 +1,41 @@
+/**
+ * OpenAI Responses 协议（Codex 用的是它）。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 与 Chat Completions 的关键差异
+ * ════════════════════════════════════════════════════════════════════
+ *  请求  `input` 是**消息数组**（与 messages 同构）而不是 messages 本身
+ *        `instructions` 替代 `system` 消息
+ *        `max_output_tokens` 替代 `max_tokens`
+ *        `tools` 项是扁平的 `{type:'function', name, parameters}`，
+ *        没有 `function` 这一层包装
+ *  响应  事件名带语义：`response.output_text.delta` / `response.function_call_arguments.delta`
+ *        / `response.reasoning_summary_text.delta`，全部带 `sequence_number`
+ *        收尾是 `response.completed`（带完整 response 对象），不是 finish_reason
+ *
+ * 丢弃（明确不做）：
+ *   - `previous_response_id` / `store`：服务端会话态。我们的供应商契约是
+ *     无状态的（`chatOnce` 一次一请求），转发过去只会拿到错误。
+ *   - `reasoning.effort` 之外的 `reasoning.summary`：摘要粒度由上游定，
+ *     我们只透传 reasoning 增量。
+ *   - `include` / `text.format`（结构化输出）：跨协议没有对应物。
+ */
+import { type ChatEvent, type ProtocolCodec } from './types.ts';
+export declare const responsesCodec: ProtocolCodec;
+/**
+ * 拼 `response.completed` 帧（收尾时由调用方带用量与收尾原因调）。
+ *
+ * `output` 里要写一条 `function_call` 占位项（当 finish 是 tool-calls 时）——
+ * Responses 没有 finish_reason 字段，客户端（以及我们自己的 `completedEvents`）
+ * 只能靠 `output` 里有没有 function_call 判断「这轮是调工具还是说完」。
+ * 少了这条，工具轮在往返后会被认成普通结束。
+ */
+export declare function completedFrame(model: string, usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens?: number;
+}, finish?: string): string;
+/** Responses 的 usage 帧（若调用方要单独发）。 */
+export declare function usageFrame(event: Extract<ChatEvent, {
+    type: 'usage';
+}>): string;

package/lib/types/protocol/sse.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SSE 帧的编解码小工具 —— 四种协议共用。
+ *
+ * 只做三件事：把字节流按 SSE 规则切成「一帧」、把一帧拆成 `event:`/`data:`
+ * 两部分、把若干帧拼回字节流。**不**知道任何协议语义 —— 那在各协议的
+ * `ProtocolCodec` 里。
+ *
+ * 为什么不用现成库：宿主没有 SSE 依赖，而我们要的能力只有「分帧」这一件，
+ * 引入一个包换三十行代码不值；且分帧必须跨 chunk 边界缓冲（上游一帧被拆在
+ * 两个 TCP 段里是常态），现成库普遍假设整帧到达。
+ */
+/** 一帧 SSE。 */
+export interface SseFrame {
+    /** `event:` 行的值（没有该行时为空串）。 */
+    event: string;
+    /** `data:` 各行的拼接（多行 `data:` 用 `\n` 连接，SSE 规范如此）。 */
+    data: string;
+}
+/**
+ * 增量分帧器：喂字节进去，吐出完整帧。
+ *
+ * 用类而不是纯函数，是因为「半个帧」必须留在实例里 —— 每次调用都是无状态的
+ * 函数做不到这件事，而每个流都要一个独立缓冲。
+ */
+export declare class SseSplitter {
+    private buf;
+    /** 喂入一块字节，返回其中包含的完整帧（可能 0..n 个）。 */
+    push(bytes: Uint8Array): SseFrame[];
+    /** 流结束时冲刷：把残留的、不以空行结尾的尾帧也吐出来（上游不发尾空行是有的）。 */
+    end(): SseFrame[];
+    /** 把已缓冲的完整帧全部切出来。 */
+    private drain;
+}
+/** 把一帧原文拆成 `event` + `data`。空 data 的帧（注释/keep-alive）返回空 data。 */
+export declare function parseFrame(raw: string): SseFrame;
+/** 拼一帧字节（`data:` 帧；不带 `event:`）。 */
+export declare function dataFrame(data: string): string;
+/** 拼一帧字节（带 `event:`）。 */
+export declare function eventFrame(event: string, data: string): string;
+/** 把若干帧原文拼成字节。 */
+export declare function framesToBytes(frames: string[]): Uint8Array;