dsh-router-core 0.4.6 → 0.4.7

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

@@ -0,0 +1,92 @@
+/**
+ * 流的协议转码 —— 把「一种协议的 SSE 字节流」翻译成「另一种协议的 SSE 字节流」。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么拆成 transform + state 两层
+ * ════════════════════════════════════════════════════════════════════
+ * 逐帧翻译需要一个**有状态**的累加器（usage 分散在多帧、工具名要先于参数、
+ * 收尾帧要在流末补），直接写成一个 200 行的 async generator 会把「状态」和
+ * 「翻译」搅在一起。所以：
+ *   - `StreamState`：一次流的有状态累加（纯内存，可单测，无 IO）。
+ *   - `translateStream`：把它接到字节流上（只管分帧/拼帧/生命周期）。
+ *
+ * 同一条流里**同时只有一个转码器**（上游协议固定），但出站协议由客户端决定 ——
+ * 所以是「一个 decode + 一个 encode」，而不是各自独立的两趟。
+ *
+ * ⚠️ **不缓冲、不聚合**：每个事件到立刻吐对应帧。首字节延迟与上游一致，
+ * 不会因为转码多等一个 chunk（Gemini 的工具调用除外：它的参数是一次性整块，
+ * 天然没有增量可言）。
+ */
+import type { ProtocolId } from './types.ts';
+/** 一次流式转码的有状态累加。 */
+export declare class StreamState {
+    /** 上游协议（解码用）。 */
+    readonly from: ProtocolId;
+    /** 客户端协议（编码用）。 */
+    readonly to: ProtocolId;
+    /** 上游 usage（跨帧合并，字段级 max —— 见 mergeUsage 的注释）。 */
+    private usage;
+    /** 已经吐过起始帧没有（起始帧只能在流最前发一次）。 */
+    private started;
+    /** 收尾原因（用于补 endFrames；缺省 stop）。 */
+    private finish;
+    /** 模型名（回显进 startFrames/endFrames，如 Anthropic 的 message_start）。 */
+    private model;
+    /**
+     * 解码侧会话与编码侧会话，各一份。
+     *
+     * **必须每帧复用同一个**：Gemini 的工具名↔index 映射就存在这里；每帧新建
+     * 会让 `tool-args` 找不到 `tool-start` 给的名字（参数被丢），而放模块级会
+     * 跨请求串名。会话在 `StreamState` 构造时建、随流结束丢弃 —— 生命周期与
+     * 「一条流」严格对齐。
+     */
+    private readonly decodeSession;
+    private readonly encodeSession;
+    constructor(from: ProtocolId, to: ProtocolId, model?: string);
+    /** 当前累计的用量。 */
+    currentUsage(): {
+        promptTokens: number;
+        completionTokens: number;
+        cachedTokens: number;
+    };
+    /** 把上游一帧原文（`data:` 载荷）翻成出站帧原文列表。 */
+    translateFrame(frame: string, event?: string): string[];
+    /**
+     * 上游流结束：补发收尾帧。
+     *
+     * **顺序固定**：finish → usage → endFrames。各协议的收尾帧都要求这个次序
+     * （Anthropic 的 message_delta 必须在 message_stop 前，Responses 的
+     * `response.completed` 是最后一件且自带 usage）。
+     *
+     * `endFrames` 拿得到 finish 与 usage —— 有的协议（Responses）只有收尾帧
+     * 里才有地方放 usage 与「是否被截断」。
+     */
+    finishStream(): string[];
+    /**
+     * 带当前用量派生的编码会话。
+     *
+     * 不能只在 `encodeSession` 存在时才派生：`createSession` 是**可选**的
+     * （只有 Gemini 这类有跨帧映射的协议实现它），Anthropic 没有 —— 按
+     * `encodeSession === undefined` 就返回 undefined 会让 usage 永远送不进去
+     * （2026-10-21 实测：output_tokens 恒为 0）。所以无论如何都造一个，
+     * 有 state 就带上。
+     */
+    private finishSessionWithUsage;
+    /**
+     * usage 合并：字段级 max。
+     *
+     * 与 `router/usage-tokens.ts` 的 `mergeUsage` 同规则（那里照 9router）：
+     * Claude 把输入用量放 `message_start`、输出放 `message_delta`，两帧都给
+     * `usage` 字段，**覆盖**会让后一帧把前面的输入清零。
+     */
+    private mergeUsage;
+}
+/**
+ * 把上游 SSE 字节流转成客户端协议的 SSE 字节流。
+ *
+ * 生命周期：上游正常读完 / 上游 error / 消费方取消，三条路径都要**释放上游
+ * reader** 并把取消传下去 —— 否则上游 fetch body 永不 cancel，长跑会漏连接
+ * （`router/index.ts` 的 `normalizeSSEStream` 里同一个坑，判据在
+ * `router/disconnect-leak.test.ts`）。
+ */
+export declare function translateStream(upstream: ReadableStream<Uint8Array>, state: StreamState): ReadableStream<Uint8Array>;

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

@@ -0,0 +1,224 @@
+/**
+ * 协议矩阵的**规范形态**（canonical form）与编解码契约。
+ *
+ * ════════════════════════════════════════════════════════════════════
+ * 为什么内部只留一种形态
+ * ════════════════════════════════════════════════════════════════════
+ * 四种协议两两互转是 4×3 = 12 条路径，逐条实现必然长出一打互相不一致的
+ * 实现。收敛成「全部先转成同一个规范形态、再从规范形态转出去」之后：
+ *
+ *     外来请求 ──decode──┐                ┌──encode── 外来响应
+ *                        ├─ 规范形态 ────┤
+ *     供应商请求 ◀─encode─┘                └─decode──▶ 供应商响应
+ *
+ * 只需要 N 个协议模块（N=4），而不是 N² 条翻译路径；新增第五种协议只是再加
+ * 一个模块，已有路径一行不改。
+ *
+ * 规范形态选 **OpenAI Chat Completions**（请求体）与**一组扁平事件**（响应流），
+ * 不是随便挑的：供应商契约（`suppliers/contract.ts` 的 `chatOnce`）今天就是
+ * 「吃 Chat Completions 请求体、吐 OpenAI SSE」，选别的形态等于把每个已装
+ * 供应商插件都改一遍。
+ *
+ * 天花板：规范形态只覆盖**能表达的部分**。各家私有的、没有对应概念的东西
+ * （Anthropic 的 `cache_control`、Responses 的 `previous_response_id`、
+ * Gemini 的 `safetySettings`）在跨协议时会被**丢掉**，不是被翻译。每条丢弃
+ * 在对应模块的注释里点名。
+ */
+/** 四种协议。`chat` 是规范形态本身，因此它的编解码是恒等变换。 */
+export type ProtocolId = 'chat' | 'anthropic' | 'responses' | 'gemini';
+/** 所有协议 id（顺序 = 文档与面板展示顺序）。 */
+export declare const PROTOCOL_IDS: readonly ProtocolId[];
+/** 宽松 JSON 对象（外来请求体一律不可信，逐字段校验）。 */
+export type JsonObject = Record<string, unknown>;
+/** 编解码时需要知道的上下文。 */
+export interface CodecContext {
+    /**
+     * 请求里声明的模型名（已剥掉本插件的 `alias/` 前缀）。
+     *
+     * 有些协议把模型名放在 URL 路径里（Gemini 的
+     * `/v1beta/models/<model>:generateContent`），有些放在请求体里；模块统一从
+     * 这里取，不各自去猜。
+     */
+    model: string;
+    /** 客户端是否要流式。 */
+    stream: boolean;
+    /**
+     * 收尾原因（仅 `endFrames` 会读）。
+     *
+     * 有些协议的收尾帧要**同时**带状态与用量（Responses 的 `response.completed`
+     * 里 `status: 'completed' | 'incomplete'` 决定 Codex 是否认为被截断），
+     * 而 `finish` 事件本身在这些协议里没有独立帧可发 —— 于是原因必须通过
+     * 上下文传进 `endFrames`，不能只靠「收到过 finish 事件」这个事实。
+     */
+    finish?: FinishReason;
+    /** 累计用量（仅 `endFrames` 会读，同上：Responses 只在收尾帧给 usage）。 */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        cachedTokens: number;
+    };
+}
+/**
+ * 规范形态的**流式事件**。
+ *
+ * 刻意做得很小：只要四家能无损落进来的都在这，落不进来的都不在。工具调用用
+ * `tool-start` + `tool-args` 两段表达（各家都是「先给名字、再给参数增量」，
+ * 只有 Gemini 把参数整块给一次 —— 它在 decode 时拆成一段即可）。
+ */
+export type ChatEvent = 
+/** 可见文本增量。 */
+{
+    type: 'text';
+    text: string;
+}
+/** 推理过程增量（`reasoning_content` / `thinking` / `thought`）。 */
+ | {
+    type: 'reasoning';
+    text: string;
+}
+/** 一个工具调用的开始（名字先到，参数随后）。同一 index 只发一次。 */
+ | {
+    type: 'tool-start';
+    index: number;
+    id?: string;
+    name?: string;
+}
+/** 工具调用的参数**增量**（JSON 片段，逐段拼接后才是完整参数）。 */
+ | {
+    type: 'tool-args';
+    index: number;
+    delta: string;
+}
+/** 收尾原因。一条流最多一个，且必须是最后一个内容事件。 */
+ | {
+    type: 'finish';
+    reason: FinishReason;
+}
+/** 用量。多数上游在最后一帧才给。 */
+ | {
+    type: 'usage';
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens: number;
+}
+/** 上游在流内报的错（HTTP 200 + 流内 error 是真实存在的形态）。 */
+ | {
+    type: 'error';
+    message: string;
+};
+/** 收尾原因（规范形态）。 */
+export type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error';
+/**
+ * 一条流里的编解码会话状态。
+ *
+ * 刻意做成**不透明的空接口 + 可选**：绝大多数协议（chat / Anthropic /
+ * Responses）逐帧无状态，不需要它；只有 Gemini 这类「用名字而非 index 指代
+ * 工具」的协议需要跨帧记住名字↔index。让它可选，是为了不给无状态协议强加
+ * 一个空对象参数。
+ */
+export interface CodecSession {
+    /** 会话内的临时槽位（各协议自己的形状，核心不解读）。 */
+    readonly state?: unknown;
+    /**
+     * 本流已累计的用量。
+     *
+     * 为什么编码器需要它：有的协议把「收尾原因」与「输出用量」绑在**同一帧**
+     * （Anthropic 的 `message_delta`），而 finish 事件本身不带 usage。不给这个
+     * 槽位，收尾帧只能写 `output_tokens: 0` 或者再多发一帧 —— 后者会让客户端
+     * 取到第一个（占位）值，把用量读成 0（2026-10-21 在 3080 实测到）。
+     */
+    readonly usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        cachedTokens: number;
+    };
+}
+/**
+ * 一个协议的编解码器。
+ *
+ * 四个方法分成两组，两组都必须实现 —— 少了任何一组就只能单向，而「双向互转」
+ * 正是这个模块存在的理由：
+ *   - `toChat*`：**入站**用。客户端说这个协议，我们得听懂它、并用它回答。
+ *   - `fromChat*`：**出站**用。供应商说这个协议，我们得用它的语言请求、并把
+ *     它的回答翻回规范形态。
+ */
+export interface ProtocolCodec {
+    readonly id: ProtocolId;
+    /**
+     * 一条流的编解码会话。
+     *
+     * 部分协议是**有状态**的：Gemini 的 `functionCall` 靠工具名认，而规范形态
+     * 靠 index，跨帧必须有映射；映射若放模块级就会串请求（并发两条流各自的
+     * `ls` 抢同一个 index，或上一条流的残留映射漏到下一条）。
+     *
+     * 所以状态由调用方在**请求边界**建一次、在整条流里传给每一帧：
+     *   - `translateStream` / `StreamState` 在一次转码里建一个；
+     *   - 单帧转换（测试、非流式一次性）可以不传，此时每帧各建一份 —— 结果
+     *     等价于无状态，代价只有一次 Map 分配。
+     */
+    createSession?(): CodecSession;
+    /** 外来请求体 → 规范请求体。`chat` 是恒等。 */
+    toChat(body: JsonObject, ctx: CodecContext): JsonObject;
+    /** 规范请求体 → 外来请求体。`chat` 是恒等。 */
+    fromChat(body: JsonObject, ctx: CodecContext): JsonObject;
+    /**
+     * 外来响应流的**单帧**解码：一帧 SSE 载荷（已剥掉 `data:` 前缀）→ 0..n 个
+     * 规范事件。`[DONE]` 与无法识别的帧返回空数组，**不抛**：一条坏帧不该让
+     * 整轮响应作废（上游发半截 JSON 是常态，见 `llm/adapter.ts` 的同类处理）。
+     *
+     * @param frame SSE 的 `data:` 载荷原文；`[DONE]` 由调用方过滤，不会传进来。
+     * @param event 该帧的 `event:` 名（Anthropic 用它区分事件类型；其余协议为空）。
+     */
+    decodeFrame(frame: string, event?: string, session?: CodecSession): ChatEvent[];
+    /**
+     * 规范事件 → 0..n 个外来 SSE 帧。
+     *
+     * 返回的是**完整帧**（含 `event:`/`data:` 行与结尾空行），调用方只管拼字节。
+     * 做成整帧而不是载荷，是因为 Anthropic 这类协议每个事件都要带 `event:` 行，
+     * 让编码器自己拼比让调用方猜事件名干净。
+     */
+    encodeFrame(event: ChatEvent, session?: CodecSession): string[];
+    /**
+     * 非流式响应体的解码：整个 JSON body → 规范事件列表。
+     *
+     * 与 `decodeFrame` 同构（同样返回事件列表），区别只在输入是**一个完整的
+     * 响应对象**而不是一帧增量。两种都必须实现：客户端可能发 `stream:false`，
+     * 供应商也可能只给 JSON（有些上游对短请求直接回非流式）。
+     */
+    decodeJson(body: JsonObject): ChatEvent[];
+    /**
+     * 规范事件 → 非流式响应体。
+     *
+     * 与 `encodeFrame` 同构：把攒起来的事件折成一个完整响应对象。
+     * `events` 里最多一个 `finish`、一个 `usage`，其余是内容。
+     */
+    encodeJson(events: ChatEvent[], ctx: CodecContext): JsonObject;
+    /**
+     * 流开始时的一次性帧（Anthropic 的 `message_start`、Responses 的
+     * `response.created`）。恒等协议返回空数组。
+     */
+    startFrames(ctx: CodecContext): string[];
+    /**
+     * 流结束时的一次性帧（`message_stop`、`response.completed`、`[DONE]`）。
+     * 与 `startFrames` 对称；`finish` 事件本身走 `encodeFrame`。
+     *
+     * 带上 `session` 是因为有的协议**必须**在流末才发得出东西：Gemini 的
+     * `functionCall` 是「名字+完整参数」一个 part，而上游逐帧发参数增量，
+     * 只能攒到流末（见 gemini.ts 的 endFrames）。
+     */
+    endFrames(ctx: CodecContext, session?: CodecSession): string[];
+}
+/** 是否为已知协议 id。 */
+export declare function isProtocolId(v: unknown): v is ProtocolId;
+/** 取对象字段（不是对象则 undefined）。 */
+export declare function obj(v: unknown): JsonObject | undefined;
+/** 取数组字段（不是数组则 undefined）。 */
+export declare function arr(v: unknown): unknown[] | undefined;
+/** 取非空字符串字段。 */
+export declare function str(v: unknown): string | undefined;
+/** 取有限数字字段。 */
+export declare function num(v: unknown): number | undefined;
+/** 取布尔字段。 */
+export declare function bool(v: unknown): boolean | undefined;
+/** 把 `finish` 原因在各协议间对齐（各家词汇不同，这里是唯一的对照表）。 */
+export declare function finishOf(v: unknown): FinishReason;

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

@@ -12,6 +12,31 @@ import { UsageStore } from './usage-store.ts';
  * 谁也没法再改结果）。核心也是所有供应商唯一的收口点，套一次全都受益。
  */
 export declare function withFirstByteDeadline(stream: ReadableStream<Uint8Array>, ms: number): ReadableStream<Uint8Array>;
+/** 丢弃响应的假 ServerResponse（测试模型用：记录状态+内容，用于判定成败）。 */
+/**
+ * 响应收集器：把 Router 本来要写给 `res` 的东西收进来，让调用方翻译后自己写。
+ *
+ * 只给**非 chat 协议**用（`/v1/messages`、`/v1/responses`、Gemini）：Router 只会
+ * 写 OpenAI 形态，而客户端要的是别的协议，中间必须插一层翻译。插入点在
+ * `chatCompletions` 的入口 —— 那里是唯一能同时看到「响应还没开始写」与
+ * 「协议是什么」的地方。
+ *
+ * 三条路径都要接住，漏一条就是那个协议下的一种故障：
+ *   - `head(status, headers)` —— 非流式的状态行（503 也走这里）
+ *   - `write(bytes)` —— 流式的 SSE 字节（可能是多段）
+ *   - `end()` —— 流结束
+ *
+ * 流式的 `writeHead` 是**延迟到第一个字节**才发生的（见 writeChatResult），
+ * 所以 `head` 在流式下可能一次都不来；调用方不能假设它来过。
+ */
+export interface ResponseSink {
+    /** 状态行 + 响应头（流式下可能不来；来了就一次）。 */
+    head?: (status: number, headers: Record<string, string>) => void;
+    /** 一段响应体字节。 */
+    write: (bytes: Uint8Array) => void;
+    /** 响应体结束。 */
+    end: () => void;
+}
 /** 路由器。 */
 export declare class Router {
     /**
@@ -108,6 +133,13 @@ export declare class Router {
      * pi-ai 等 DSH provider 通过它发现 Router 的模型目录。
      */
     listModels(): Promise<ModelInfo[]>;
+    /**
+     * 该供应商的 `chatOnce`，已按它声明的 wire 包好协议翻译。
+     *
+     * 每次调用都现取（而不是构造时缓存）：供应商会被开关/热重载替换，
+     * 缓存会把旧实例的翻译绑在新实例上。
+     */
+    private wireOf;
     /** 组合列表（面板用）：用户自定义组合。 */
     combos(): Promise<Combo[]>;
     /**
@@ -196,7 +228,16 @@ export declare class Router {
      * - model 命中组合名 → 在组合模型里按策略选一个，交给供应商；失败按回退顺序尝试剩余模型。
      * - 否则 → 依次尝试供应商，直到某个返回 true（已写响应）或全部返回 false。
      */
-    chatCompletions(req: ChatRequest, res: ServerResponse): Promise<void>;
+    /**
+     * 规范请求入口。
+     *
+     * @param res 真实的客户端响应。协议非 chat 时**不直接用它**，而是经
+     *   `sink` 先收集再翻译（见 `protocol/entry.ts`）—— 因为 Router 只知道
+     *   怎么写 OpenAI 形态，而客户端说的可能是 Anthropic/Gemini。
+     * @param sink 可选的响应收集器：给了就把「写给 res 的东西」改成写给 sink，
+     *   由调用方翻译后自己写真正的 res。只给非 chat 协议用。
+     */
+    chatCompletions(req: ChatRequest, res: ServerResponse, sink?: ResponseSink): Promise<void>;
     /** 调指定供应商。
      *  模型名**原样**传给插件（不在这剥 alias/）——插件自己认得自己的别名
      *  （如 traework 会剥第一段）。核心在这剥就会剥两次，把模型 id 里的

package/lib/types/router/types.d.ts

@@ -5,6 +5,7 @@
  */
 import type { AccountState, ChatOnceResult, SupplierAccountNow } from '../suppliers/contract.ts';
 import type { AccountPool } from './account-pool.ts';
+import type { ProtocolId } from '../protocol/types.ts';
 /** 面板展示的账号状态（脱敏）。 */
 export interface SupplierAccount {
     uid: string;
@@ -64,6 +65,15 @@ export interface ChatRequest {
      * 能反查是哪个客户端在打）。缺省 = 匿名外部客户端。
      */
     session?: string;
+    /**
+     * 客户端说的协议（入站）。
+     *
+     * 缺省 `'chat'`（今天所有入口的现状）。四种协议（chat / anthropic /
+     * responses / gemini）在入站路由上就被翻成规范形态，所以**核心与供应商
+     * 只认 chat**；这个字段存在的理由是让用量记录与日志能说出「客户端原本
+     * 说的哪种协议」，排查「Claude Code 打过来为什么不通」时省一次猜。
+     */
+    protocol?: ProtocolId;
 }
 /**
  * 供应商接口。核心负责账号池（选号/冷却/禁用/错误累计/遍历回退），
@@ -90,6 +100,15 @@ export interface Supplier {
     accounts(): SupplierAccountNow[];
     /** 对单个账号调一次上游。不遍历账号、不管冷却、不写 res。 */
     chatOnce(uid: string, lv: string, req: ChatRequest): Promise<ChatOnceResult>;
+    /**
+     * 上游说哪种协议（缺省 `'chat'`）。
+     *
+     * 声明成别种时，核心在 `chatOnce` 前后各做一次翻译：请求体翻成该协议、
+     * 响应流翻回 OpenAI SSE。于是**插件实现里永远只看见 OpenAI 形态**，
+     * 契约不变 —— 一个只会说 Anthropic 的上游可以接一个只写了几行 fetch 的
+     * 插件，路由/选号/冷却/用量全都照旧。
+     */
+    readonly wire?: ProtocolId;
     /** 删除链接（清理凭证；内部能力，js 契约不要求实现）。 */
     removeLink?(uid: string): Promise<boolean>;
     dispose(): void;

package/lib/types/shared.d.ts

@@ -185,6 +185,17 @@ export interface ExtControlItem {
     body?: string;
     /** 文本可编辑（缺省 = 只读；见 `ExtControl.editable`）。 */
     editable?: boolean;
+    /**
+     * 分组名（可选；缺省 = 无组）—— 详情页按它分节渲染，组间插组标题行；
+     * 无组照旧平铺（见 `ExtControl.group`）。
+     */
+    group?: string;
+    /**
+     * 参与拖动排序（可选；缺省 = 参与）—— `false` 的条目不给拖把手
+     * （见 `ExtControl.sortable`）。⚠️ 服务端**带值透传**，`false` 也会收到；
+     * 判断必须写 `sortable !== false`，`!sortable` 会把缺省（参与）当不参与。
+     */
+    sortable?: boolean;
     /**
      * 自建条目（可删）还是内置（不可删、只有开关与还原）。
      *

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

@@ -13,6 +13,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { ChatRequest, ModelInfo, SupplierAccount } from '../router/types.ts';
 import type { SupplierConfigStore } from '../supplier-config.ts';
 import type { CredentialStore } from '../credential-store.ts';
+import type { ProtocolId } from '../protocol/types.ts';
 /** 供应商配置：loader 注入的运行时环境。 */
 export interface SupplierEnv {
     /** 数据目录（state.json / keys.json 所在目录）。 */
@@ -45,9 +46,16 @@ export interface SupplierEnv {
  * `source` 是**可选标签**，声明这个供应商是从哪儿来的。核心用它把 `/health` 的
  * `source` 报准（面板按它分「内置 / 插件」两组，面板和插件页都看这个值）。
  * 不声明 = `external`（独立安装的供应商插件的现状，一个字段都不用改）。
+ *
+ * `wire` 是**协议标签**（可选）：这个供应商的上游说哪种协议。缺省
+ * `'chat'`（= OpenAI Chat Completions，今天所有供应商的现状，一个都不用改）。
+ * 声明成别种时，核心在把 `req` 交给插件前把规范请求体翻成它的协议，
+ * 并把它的响应流翻回规范形态 —— 插件看到的仍是「OpenAI SSE」，
+ * 于是**契约不变、已有插件全都不动**。详见 `protocol/`。
  */
 export type SupplierFactory = ((env: SupplierEnv) => SupplierModule) & {
     source?: 'builtin';
+    wire?: ProtocolId;
 };
 /**
  * 账户此刻的状态 —— 插件**解读**上游信号后的语义状态。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-router-core",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "DSH plugin: a simplified 9router (AI routing gateway). Adds a 路由系统 (Routing System) sidebar entry beside 记忆系统; the panel shows suppliers, account pool, combos, and endpoint/API keys.",
   "type": "module",
   "repository": {
@@ -105,7 +105,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.4"
+    "@deepseek-ai/schemastery": "^3.18.5"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.4",
@@ -113,8 +113,8 @@
     "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
     "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
     "cordis": "^4.0.0-rc.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
@@ -134,13 +134,13 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^26.6.2",
+    "@types/node": "^26.6.5",
     "@types/react": "~19.3.0",
     "@types/react-dom": "~19.3.0",
     "cordis": "4.0.0-rc.10",
-    "react": "^19.3.0",
+    "react": "^19.3.1",
     "react-dom": "19.3.0",
-    "tsdown": "^0.23.0",
+    "tsdown": "^0.23.1",
     "typescript": "^7.0.2",
     "vite": "8.3.0",
     "vite-plugin-css-injected-by-js": "^5.0.2"

package/src/client/ExtDetail.tsx

@@ -16,10 +16,11 @@
  * 名称/副行，下面跟扩展说明卡与未就绪横幅。有 `api()` 支持的自定义扩展可在未来
  * 按需加独立面板，此处不内置任何具体扩展的专属视图。
  */
-import { useEffect, useState } from 'react'
+import { Fragment, useEffect, useState } from 'react'
 import { Switch } from '@deepseek-ai/dsh-client-ui-primitives'
 import { ROUTER_API_BASE, type ExtControlItem, type RouterExtItem, type RouterExtResponse } from '../shared.ts'
 import { extPanel } from './ext-panels.ts'
+import { groupControlRows } from './group-controls.ts'
 import { Modal } from './Modal.tsx'
 
 /**
@@ -436,14 +437,30 @@ function ExtControls({ item }: { item: RouterExtItem }): JSX.Element {
             它只剩两个字，却仍占一行 —— 页面进来第一眼是「子开关」这三个字而不是
             那些规则本身。列表自带每条的标题与开关，不需要再套一层说明。 */}
         <ul className="dshr-compRows">
-          {controls.map((c, index) => (
+          {/* 分组渲染（`ExtControl.group`）：无组节（准则分类）平铺在前 ——
+              没用 group 的扩展拿到的就是原来的平铺列表，行为不变；有组的
+              条目（宿主段落）每组前插一行组标题。组的先后与组内顺序都来自
+              服务端 `rows`（= prompt 序），这里不重排。 */}
+          {groupControlRows(controls).map((g) => (
+            <Fragment key={g.label ?? '__plain__'}>
+              {g.label !== undefined && (
+                <li className="dshr-extGroupTitle">{g.label}</li>
+              )}
+              {g.items.map((c) => {
+                // 下标永远对 `controls`（= 服务端 rows）取：分组只影响**渲染
+                // 顺序**，拖动落盘的 ids 必须基于原列表 —— 段落行不可拖（见下），
+                // 可拖的准则全在无组节，原下标与视图位置天然一致。
+                const index = controls.indexOf(c)
+                const sortable = c.sortable !== false
+                return (
             <li
               key={c.id}
               className={`dshr-compRow${dragIndex === index ? ' dshr-linkRowDragging' : ''}`}
-              draggable
-              onDragStart={(e) => { setDragIndex(index); e.dataTransfer.effectAllowed = 'move' }}
-              onDragOver={(e) => { e.preventDefault(); e.dataTransfer.dropEffect = 'move' }}
+              draggable={sortable}
+              onDragStart={(e) => { if (!sortable) return; setDragIndex(index); e.dataTransfer.effectAllowed = 'move' }}
+              onDragOver={(e) => { if (!sortable) return; e.preventDefault(); e.dataTransfer.dropEffect = 'move' }}
               onDrop={(e) => {
+                if (!sortable) { setDragIndex(null); return }
                 e.preventDefault()
                 if (dragIndex === null || dragIndex === index) { setDragIndex(null); return }
                 const next = [...controls]
@@ -511,6 +528,9 @@ function ExtControls({ item }: { item: RouterExtItem }): JSX.Element {
                 onChange={(next) => { void toggle(c.id, next) }}
               />
             </li>
+                )
+              })}
+            </Fragment>
           ))}
         </ul>
         {withBody.length === 0 && (

package/src/client/group-controls.test.ts

@@ -0,0 +1,53 @@
+/**
+ * 详情页 controls 分组的判据（`group-controls.ts`）。
+ *
+ * 关键是**向后兼容不可退**：没用 `group` 字段的扩展（ext-test 等）必须
+ * 拿到"一个无组节、顺序不变"的结果 —— 分组是新能力的**叠加**，不是重排。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { groupControlRows } from './group-controls.ts'
+import type { ExtControlItem } from '../shared.ts'
+
+function row(id: string, extra: Partial<ExtControlItem> = {}): ExtControlItem {
+  return { id, title: id, on: true, custom: false, overridden: false, ...extra }
+}
+
+test('★ 全部无组 ⇒ 单一个无组节（旧扩展的面板展示与改动前一致）', () => {
+  const groups = groupControlRows([row('a'), row('b')])
+  assert.equal(groups.length, 1)
+  assert.equal(groups[0]!.label, undefined)
+  assert.deepEqual(groups[0]!.items.map((i) => i.id), ['a', 'b'], '无组条目顺序被改了')
+})
+
+test('★ 无组节恒排最前，且不产出空的无组节', () => {
+  const groups = groupControlRows([row('a'), row('t1', { group: '工具说明' })])
+  assert.deepEqual(groups.map((g) => g.label), [undefined, '工具说明'])
+  const onlyGrouped = groupControlRows([row('t1', { group: '工具说明' })])
+  assert.deepEqual(onlyGrouped.map((g) => g.label), ['工具说明'], '只有分组条目时不该冒出一个空的无组节')
+})
+
+test('组的先后 = 首次出现序（不按字母重排）', () => {
+  const groups = groupControlRows([
+    row('h', { group: '开场身份' }),
+    row('w', { group: '工具说明' }),
+    row('e', { group: '工具说明' }),
+    row('p', { group: '计划模式' }),
+  ])
+  assert.deepEqual(groups.map((g) => g.label), ['开场身份', '工具说明', '计划模式'])
+  assert.deepEqual(groups[1]!.items.map((i) => i.id), ['w', 'e'], '组内顺序被重排 ⇒ 面板序与 prompt 序脱钩')
+})
+
+test('同名组跨位置仍归一组（不因中间夹了别的组而拆开）', () => {
+  const groups = groupControlRows([
+    row('w1', { group: '工具说明' }),
+    row('h', { group: '开场身份' }),
+    row('w2', { group: '工具说明' }),
+  ])
+  const tool = groups.find((g) => g.label === '工具说明')!
+  assert.deepEqual(tool.items.map((i) => i.id), ['w1', 'w2'])
+})
+
+test('空输入 ⇒ 空数组', () => {
+  assert.deepEqual(groupControlRows([]), [])
+})

package/src/client/group-controls.ts

@@ -0,0 +1,43 @@
+/**
+ * 扩展详情页 controls 的**分组**纯逻辑（客户端，可单测）。
+ *
+ * 分组是**归属信息**，不是样式：一条扩展同时管两类东西时（分层提示词 =
+ * 准则分类 + 宿主系统提示词段落），平铺成一长列无从分辨哪条是谁的。
+ *
+ * 两条规则：
+ *   ① **无组节恒排最前** —— 没用 `group` 字段的扩展（ext-test 等）拿到的
+ *      分组结果就是原来的平铺列表（一个无名节），面板行为一个像素不变；
+ *   ② 组的先后 = 组名在 `rows` 里的**首次出现序**，组内保持原顺序 ——
+ *      不按字母重排：`rows` 的顺序来自服务端（段落按 prompt 序），重排
+ *      就会把"面板顺序 ≈ 模型看到的顺序"这条对应关系打断。
+ */
+import type { ExtControlItem } from '../shared.ts'
+
+/** 一个分组：`label === undefined` 表示"无组节"（平铺条目）。 */
+export interface ControlGroup {
+  label?: string
+  items: ExtControlItem[]
+}
+
+/** 按 `group` 分组；空输入返回空数组（不产出空的无组节）。 */
+export function groupControlRows(rows: readonly ExtControlItem[]): ControlGroup[] {
+  const plain: ExtControlItem[] = []
+  const groups: ControlGroup[] = []
+  const byLabel = new Map<string, ExtControlItem[]>()
+  for (const c of rows) {
+    if (c.group === undefined) {
+      plain.push(c)
+      continue
+    }
+    let items = byLabel.get(c.group)
+    if (!items) {
+      items = []
+      byLabel.set(c.group, items)
+      groups.push({ label: c.group, items })
+    }
+    items.push(c)
+  }
+  const out: ControlGroup[] = []
+  if (plain.length > 0) out.push({ items: plain })
+  return [...out, ...groups]
+}