dsh-router-core 0.4.6 → 0.4.8

package/src/ext-prompt/sections.ts

@@ -0,0 +1,193 @@
+/**
+ * 系统提示词**段落级**总控的纯逻辑与清单缓存 —— 把整体系统提示词拆成
+ * 每一段（`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 const SECTION_CONTROL_PREFIX = 'sec:'
+
+/**
+ * 自己的准则段：**不进清单、不被过滤**。
+ *
+ * 它已有独立的开关体系（扩展总开关 + 14 个分类开关）——再列一条"段开关"
+ * 就是同一件事的第二个开关，两边状态会漂移；过滤它还会让分类开关看起来
+ * 失效（段没了，分类怎么切都看不到效果）。
+ */
+export const OWN_SECTION_NAME = 'dsh-router-ext-prompt:guideline'
+
+/**
+ * 段名前缀 → 面板分组名。**未知前缀原样当组名**（不硬编全部前缀）：
+ * 宿主还会加新段（`web:`、`structured:`…），映射漏了顶多组名不雅，
+ * 条目照常列出照常开关 —— 映射表漂移不允许变成"段消失"。
+ */
+/**
+ * 段名前缀 → 面板分组名。
+ *
+ * ⚠️ 键是**段名的第一段**（冒号前），不是"看起来像"的前缀。2026-10-21 实测
+ * 真宿主（3081，23 条 controls / 9 段）纠正过两处脑补：
+ *   - `harness:source`（运行时上下文里 Harness 检出的位置）第一段是 `harness`，
+ *     按前缀映射会被并入「开场身份」—— 而它不是身份，是运行环境说明；
+ *   - `app:web-surface`（Web GUI 说明）第一段是 `app`，与"界面与交付"无关。
+ * 所以 `harness` 刻意**不映射**：`harness:identity` 是身份、`harness:source` 不是，
+ * 靠第一段分不开 —— 让它们各自留下真实前缀（`harness` / `app`）比归错组诚实。
+ * `ui:` 才是界面与交付那一组（`ui:deliverable-file-references`）。
+ *
+ * 映射漏了或故意不映射的前缀，组名**原样显示前缀**、条目照常能列能开关 ——
+ * 映射表漂移不允许变成"段消失"。
+ */
+const GROUP_LABELS: Record<string, string> = {
+  deployment: '部署人设',
+  plan: '计划模式',
+  team: '团队',
+  tool: '工具说明',
+  mcp: 'MCP 服务',
+  context: '运行上下文',
+  ui: '界面与交付',
+}
+
+/**
+ * 无冒号段名的映射（宿主有几个段名整名不带冒号）。
+ *
+ * `harness:identity` 才是开场身份，它带冒号走前缀表；这里只收无冒号的整名。
+ */
+const WHOLE_NAME_LABELS: Record<string, string> = {
+  'mcp-resource-servers': 'MCP 资源',
+}
+
+/** 一条已装配的段（面板清单用）。 */
+export interface SectionEntry {
+  /** 段注册名（稳定；也是开关的落盘键）。 */
+  name: string
+  /** 面板副行显示的原文（装配时 provider 现算的结果，**未做 `{{变量}}` 插值**）。 */
+  text: string
+}
+
+/** `controlId`（`sec:…`）→ 段名；非段条目返回 null。 */
+export function sectionNameOf(controlId: string): string | null {
+  return controlId.startsWith(SECTION_CONTROL_PREFIX) ? controlId.slice(SECTION_CONTROL_PREFIX.length) : null
+}
+
+/** 段名 → 面板控制条 id。 */
+export function sectionControlId(name: string): string {
+  return SECTION_CONTROL_PREFIX + name
+}
+
+/**
+ * 段名的分组名。
+ *
+ * 查表顺序：**整名**（无冒号段名，如 `mcp-resource-servers`）→ **第一段前缀**
+ * （`tool:write` → `tool`）。两级都查不到 ⇒ 有冒号时用第一段原样当组名、
+ * 无冒号归「其他」。
+ */
+export function groupLabelOf(name: string): string {
+  const whole = WHOLE_NAME_LABELS[name]
+  if (whole !== undefined) return whole
+  const i = name.indexOf(':')
+  if (i < 0) return '其他'
+  const head = name.slice(0, i)
+  return GROUP_LABELS[head] ?? head
+}
+
+/** 面板条目标题：去掉组前缀的部分（`tool:write` → `write`；无冒号 = 全名）。 */
+export function sectionTitleOf(name: string): string {
+  const i = name.indexOf(':')
+  return i >= 0 ? name.slice(i + 1) : name
+}
+
+/**
+ * 当前被关掉的段名集合。**只认显式 `false`** —— 缺项是"没碰过"（默认开），
+ * 与 `resolveEnabledCategories` 对 `undefined` 的处置同一纪律。
+ */
+export function disabledSectionNames(data: PromptExtData | undefined): Set<string> {
+  const out = new Set<string>()
+  const saved = data?.sections
+  if (!saved) return out
+  for (const [name, on] of Object.entries(saved)) if (on === false) out.add(name)
+  return out
+}
+
+/**
+ * 过滤掉关闭的段（保序）。自己那段**恒放行**（理由见 `OWN_SECTION_NAME`）。
+ *
+ * ⚠️ 名字不在清单里的关闭项静默跳过：宿主段随版本增删，旧数据里的名字
+ * 失效是正常生命周期，报错只会把面板变成红字噪音。
+ */
+export function filterSections<T extends { name: string }>(sections: readonly T[], off: ReadonlySet<string>): T[] {
+  // ⚠️ 条件是 `===` **或** 没被关 —— 我第一版写成 `!== OWN && !off.has(...)`，
+  //   把"是自己的段"当成了排除条件：结果是**准则段每次都被删掉**，而
+  //   tool:write 这些反倒留着。方向写反不会抛错，只会让面板看起来全开、
+  //   prompt 里准则凭空消失（本条判据就是靠两个方向同时断言抓出来的）。
+  return sections.filter((s) => s.name === OWN_SECTION_NAME || !off.has(s.name))
+}
+
+/**
+ * 段清单缓存：waterfall 监听器是**唯一写入者**（装配路径顺路喂），
+ * 面板 controls getter 只读。分组与排序都在读取端做 —— 缓存保持
+ * 装配原序（`assemble` 已按 order/name 排好），组的次序自然等于 prompt 次序。
+ */
+export function createSectionCache(): {
+  /** 用一次装配结果刷新（整表替换；自己的段不进清单）。 */
+  update: (sections: readonly { name: string; text: string }[]) => void
+  /** 当前清单（拷贝，防调用方改缓存内部）。 */
+  list: () => SectionEntry[]
+} {
+  let entries: SectionEntry[] = []
+  return {
+    update(sections) {
+      entries = sections
+        .filter((s) => s.name !== OWN_SECTION_NAME)
+        .map((s) => ({ name: s.name, text: s.text }))
+    },
+    list() {
+      return entries.map((e) => ({ ...e }))
+    },
+  }
+}
+
+/** 一个分组（组名 + 组内条目，组内保持清单序）。 */
+export interface SectionGroup {
+  label: string
+  items: SectionEntry[]
+}
+
+/**
+ * 按段名前缀分组；**组的先后 = 首次出现序**（清单已按 prompt 序 ⇒ 组序即
+ * 段落在 prompt 里的先后）——不按字母重排，面板顺序与模型看到的顺序一致。
+ */
+export function groupSections(list: readonly SectionEntry[]): SectionGroup[] {
+  const out: SectionGroup[] = []
+  const byLabel = new Map<string, SectionGroup>()
+  for (const item of list) {
+    const label = groupLabelOf(item.name)
+    let g = byLabel.get(label)
+    if (!g) {
+      g = { label, items: [] }
+      byLabel.set(label, g)
+      out.push(g)
+    }
+    g.items.push(item)
+  }
+  return out
+}

package/src/ext-route.test.ts

@@ -76,3 +76,19 @@ test('★ src 下不许有备份/临时文件（它们会被 `git add -A` 顺手
     .filter((f) => /\.(bak|orig|rej|tmp|swp)$/.test(f) || /~$/.test(f))
   assert.deepEqual(junk, [], `源码目录里有临时/备份文件：${junk.join(', ')}`)
 })
+
+// ── controls 序列化白名单（2026-10-21 段落总控）──────────────────
+test('★ controls 透传 group / sortable（白名单漏字段 ⇒ 面板分组永远不生效）', () => {
+  // ⚠️ 这里存在一个**只在入口才暴露**的失效：`GET /ext` 用 `.map()` 逐字段
+  //   重建 controls（白名单），扩展在 `controls` 里给了 `group`，但白名单
+  //   不认它 ⇒ 字段被静默丢掉。而单测（直接读扩展对象的 `.controls`）**全绿**：
+  //   扩展那头确实给了。两端都"对"，中间少一环 —— 只能在这里守。
+  //
+  // 判据用源码形状而非启服务器：与本文件既有做法一致（理由见文件头）。
+  const mapLine = src.split('\n').find((l) => l.includes('.map((c) => ({ id: c.id, title: c.title' ))
+  assert.ok(mapLine !== undefined, '找不到 controls 的序列化 map（形状变了 ⇒ 本判据要跟着改）')
+  assert.match(mapLine, /\.\.\.\(c\.group !== undefined \? \{ group: c\.group \}/,
+    'controls 序列化没透传 group ⇒ 段落分组在面板上永远不出现')
+  assert.match(mapLine, /\.\.\.\(c\.sortable !== undefined \? \{ sortable: c\.sortable \}/,
+    'controls 序列化没透传 sortable ⇒ 段落行仍可拖（假交互）')
+})

package/src/index.ts

@@ -47,6 +47,7 @@ import { loopbackBaseURL } from './host-base-url.ts'
 import { detectHostVersion, isHostSupported } from './host-version.ts'
 import { ExtStore } from './ext/store.ts'
 import type { ExtControl, ExtInfo, ExtStoreService, RouterExt, RouterExtService } from './ext/contract.ts'
+import { geminiModelFromPath, geminiStreamFromPath, lvOf, outboundSink, parseInbound } from './protocol/entry.ts'
 
 /**
  * Plugin identity for cordis.yml rows — 必须与 package.json 的 name 一致。
@@ -138,6 +139,24 @@ function writeJson(res: ServerResponse, status: number, body: unknown): void {
   res.end(payload)
 }
 
+/**
+ * 每种协议的 error body 形状。
+ *
+ * 为什么必须有：非 chat 入口的 400/413/501 若照 OpenAI 的
+ * `{error:{message,type,code}}` 写，Claude Code 解析不到 `error.message`
+ * 会显示「未知错误」——用户看到的是一个空错误，而真因（如 body 太大）
+ * 就在手边却送不出去。
+ */
+function errBodyFor(protocol: 'anthropic' | 'responses' | 'gemini', message: string): unknown {
+  if (protocol === 'anthropic') {
+    return { type: 'error', error: { type: 'invalid_request_error', message } }
+  }
+  if (protocol === 'gemini') {
+    return { error: { code: 400, message, status: 'INVALID_ARGUMENT' } }
+  }
+  return { error: { message, type: 'api_error', code: 'invalid_request' } }
+}
+
 function readBody(req: IncomingMessage, limit: number): Promise<string> {
   return new Promise((resolve, reject) => {
     const chunks: Buffer[] = []
@@ -334,6 +353,14 @@ export function apply(rawContext: unknown): void {
   })()
 
   // ---- /v1/* (OpenAI-compatible, Bearer auth via KeysStore) ----
+  //
+  // 四种协议共用同一套路由/账号池/用量统计，差别只在「怎么听懂请求、怎么回答」：
+  //   /v1/chat/completions                      OpenAI Chat Completions
+  //   /v1/messages, /v1/messages/count_tokens   Anthropic Messages
+  //   /v1/responses                             OpenAI Responses
+  //   /v1beta/models/<m>:generateContent        Google Gemini
+  // 入站一律先翻成规范请求（Chat Completions 形状）再进 Router，所以上面这些
+  // 端点**自动**获得组合回退、账号池选号、首字节预算与用量看板。
 
   const withV1Auth = (handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>) => {
     return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
@@ -386,9 +413,90 @@ export function apply(rawContext: unknown): void {
         model: typeof peek.model === 'string' ? peek.model : '',
         lv,
         ...(session === undefined ? {} : { session }),
+        protocol: 'chat',
+      },
+      res,
+    )
+  }))
+
+  /**
+   * Anthropic / Responses / Gemini 三个非 chat 入口的**公共前半段**：
+   * 鉴权 → 读 body → 翻成规范请求 → 交给 Router → 把响应翻回客户端协议。
+   *
+   * 抽出来是因为三者的差别只有「协议 id 是什么、模型名从哪取」，而鉴权/限流/
+   * 归因/错误形状必须完全一致 —— 各写一份就会出现「Anthropic 入口认了
+   * x-dsh-router-session、Gemini 入口不认」这种只能靠实测发现的漂移。
+   */
+  const enterProtocol = (protocol: 'anthropic' | 'responses' | 'gemini') => withV1Auth(async (req, res) => {
+    const parsed = await parseInbound(req, protocol, {
+      limitBytes: 8 << 20,
+      modelFromPath: protocol === 'gemini' ? geminiModelFromPath(req.url ?? '') : undefined,
+      // Gemini 的「流不流式」在 URL 尾部（:streamGenerateContent vs
+      // :generateContent），body 里没有 stream 字段 —— 不认它，流式请求会被
+      // 当成非流式返回一整个 JSON，客户端按 SSE 解析就是空响应。
+      streamFromPath: protocol === 'gemini' ? geminiStreamFromPath(req.url ?? '') : undefined,
+      lvFromBody: (body) => lvOf(body, protocol),
+    })
+    if ('error' in parsed) {
+      writeJson(res, parsed.status, errBodyFor(protocol, parsed.error))
+      return
+    }
+    if (parsed.model === '') {
+      writeJson(res, 400, errBodyFor(protocol, 'missing model'))
+      return
+    }
+    const sessionRaw = req.headers['x-dsh-router-session']
+    const session = (typeof sessionRaw === 'string' && sessionRaw !== '' ? sessionRaw : undefined)
+      ?? clientIdentityOf(parsed.body, req.headers['user-agent'])
+    // 出口：Router 只会写 OpenAI 形态，sink 负责翻成客户端协议再写给 res。
+    // sink 是**透传式中继**，Router 那套「客户端断开就取消上游流」的逻辑
+    // 照旧生效 —— 它监听的是真实 res 的 close，与本层无关。
+    const sink = outboundSink(protocol, parsed.model, res)
+    await router.chatCompletions(
+      {
+        rawBody: JSON.stringify(parsed.body),
+        stream: parsed.stream,
+        model: parsed.model,
+        lv: parsed.lv,
+        ...(session === undefined ? {} : { session }),
+        protocol,
       },
       res,
+      sink,
     )
+  })
+
+  // Anthropic Messages（Claude Code 只说这种协议）。
+  // count_tokens 是「问一句要多少 token」：没有本地 tokenizer 就不能诚实回答，
+  // 而跑一次上游只数 token 是要花钱的假精确 —— 直接 501，别编数字。
+  route('/v1/messages', enterProtocol('anthropic'))
+  route('/v1/messages/count_tokens', withV1Auth(async (_req, res) => {
+    writeJson(res, 501, {
+      type: 'error',
+      error: { type: 'not_supported', message: 'count_tokens is not supported; send the message instead' },
+    })
+  }))
+
+  // OpenAI Responses（Codex 用）。
+  route('/v1/responses', enterProtocol('responses'))
+
+  // Google Gemini。Gemini 的模型名在 **URL 路径**里
+  // （`/v1beta/models/<model>:generateContent`），所以走 prefix 路由自己解析
+  // `req.url`（webServer 的 exact 匹配不吃 `:param` 语法，而模型名本身可含
+  // 斜杠，逐段穷举不现实）。流式/非流式靠路径尾部的
+  // `:streamGenerateContent` / `:generateContent` 区分，已在
+  // `geminiModelFromPath` 与 `parseInbound` 里落到 `stream` 上。
+  //
+  // ⚠️ **prefix 不能带尾斜杠**：宿主 `Table.match()` 的判据是
+  //     `pathname === prefix || pathname.startsWith(prefix + '/')`
+  //   注册 `'/v1beta/models/'` 会让实际请求去比 `'/v1beta/models//'`，
+  //   **永不匹配** → 落到宿主兜底，表现为 GET 404 / POST 405（2026-10-21 实测
+  //   在 3080 上复现）。注册成不带斜杠的 `'/v1beta/models'`，
+  //   `startsWith('/v1beta/models/')` 才成立。
+  disposers.push(ctx.webServer.register({
+    kind: 'prefix',
+    path: '/v1beta/models',
+    handler: enterProtocol('gemini'),
   }))
 
   // ---- /router/api/* (panel, same-origin) ----
@@ -621,7 +729,7 @@ return Object.values(table as RouterExtService)
             controls: e.controls
               .filter((c): c is ExtControl =>
                 !!c && typeof c.id === 'string' && c.id !== '' && typeof c.title === 'string')
-              .map((c) => ({ id: c.id, title: c.title, on: c.on === true, ...(c.detail !== undefined ? { detail: c.detail } : {}), ...(typeof c.body === 'string' ? { body: c.body } : {}), ...(c.editable === true ? { editable: true } : {}), custom: c.custom === true, overridden: c.overridden === true })),
+              .map((c) => ({ id: c.id, title: c.title, on: c.on === true, ...(c.detail !== undefined ? { detail: c.detail } : {}), ...(typeof c.body === 'string' ? { body: c.body } : {}), ...(c.editable === true ? { editable: true } : {}), ...(c.group !== undefined ? { group: c.group } : {}), ...(c.sortable !== undefined ? { sortable: c.sortable } : {}), custom: c.custom === true, overridden: c.overridden === true })),
           }
         : {}),
       ...(st?.detail !== undefined ? { detail: st.detail } : {}),