@allbluecn/web-app 0.12.0 → 0.12.2

package/src/server/ai-gateway/sandbox/provider.ts

@@ -0,0 +1,128 @@
+import type { SandboxProvider } from "@tanstack/ai-sandbox"
+
+export type SandboxProviderKind = "local-process" | "vercel" | "daytona"
+
+export interface ResolvedSandboxProvider {
+  kind: SandboxProviderKind
+  provider: SandboxProvider
+}
+
+const CLOUD_KINDS: ReadonlySet<string> = new Set(["vercel", "daytona"])
+
+/**
+ * DEPLOY_TARGET + env 分派（ADR 5 provider 矩阵）：
+ * - desktop                → localProcessSandbox（本机，用户自担；任务 3 自研实现）
+ * - AI_SANDBOX_PROVIDER=…  → 显式指定 vercel|daytona，缺对应凭据即 fail-closed
+ * - vercel（自托管云端）   → VERCEL_TOKEN → vercelSandbox；缺 token 降级 daytonaSandbox
+ * - web/cloudflare（自托管）→ DAYTONA_API_KEY → daytona；其次 VERCEL_TOKEN → vercel
+ *
+ * fail-closed：无可用配置时抛错并给出 env 清单，绝不静默返回 null。
+ *
+ * 无 docker provider（2026-09-16 移除）：@tanstack/ai-sandbox-docker 的依赖链
+ * dockerode → docker-modem → ssh2 → cpu-features 含原生绑定，本机未编译时会让
+ * Vite 8 的 client optimizer 在启动期直接崩掉（rolldown UNRESOLVED_IMPORT），
+ * dev server 完全起不来。部署形态是整体打成镜像，运行环境不需要宿主 Docker
+ * daemon，因此不保留这条路径；误配 docker 会得到明确的「已移除」报错而非静默降级。
+ */
+export async function resolveSandboxProvider(): Promise<ResolvedSandboxProvider> {
+  const target = (process.env.DEPLOY_TARGET ?? "web").trim()
+  const explicit = process.env.AI_SANDBOX_PROVIDER?.trim() || undefined
+
+  if (target === "desktop" || explicit === "local-process") {
+    const localRoot = process.env.AI_SANDBOX_LOCAL_ROOT?.trim()
+    if (!localRoot) {
+      throw new Error(
+        "DEPLOY_TARGET=desktop / AI_SANDBOX_PROVIDER=local-process 需要 AI_SANDBOX_LOCAL_ROOT 指定工作区根目录" +
+          "（不默认 /tmp，避免多用户共享同一沙箱目录）",
+      )
+    }
+    const { localProcessSandbox } = await import("./local-process")
+    return { kind: "local-process", provider: localProcessSandbox({ root: localRoot }) }
+  }
+
+  if (explicit && !CLOUD_KINDS.has(explicit)) {
+    throw new Error(
+      `AI_SANDBOX_PROVIDER 取值非法：${explicit}（仅支持 vercel|daytona|local-process` +
+        (explicit === "docker"
+          ? "；docker provider 已移除——运行环境不需要宿主 Docker daemon"
+          : "") +
+        "）",
+    )
+  }
+
+  if (explicit === "vercel") {
+    return {
+      kind: "vercel",
+      provider: await createVercelSandbox(requireEnv("VERCEL_TOKEN", "vercel")),
+    }
+  }
+  if (explicit === "daytona") {
+    return {
+      kind: "daytona",
+      provider: await createDaytonaSandbox(requireEnv("DAYTONA_API_KEY", "daytona")),
+    }
+  }
+
+  if (target === "vercel") {
+    if (process.env.VERCEL_TOKEN) {
+      return { kind: "vercel", provider: await createVercelSandbox() }
+    }
+    if (process.env.DAYTONA_API_KEY) {
+      return { kind: "daytona", provider: await createDaytonaSandbox() }
+    }
+    throw new Error(
+      "DEPLOY_TARGET=vercel 未配置 VERCEL_TOKEN；如需降级请设置 DAYTONA_API_KEY（Daytona 云沙箱）",
+    )
+  }
+
+  if (process.env.DAYTONA_API_KEY) {
+    return { kind: "daytona", provider: await createDaytonaSandbox() }
+  }
+  if (process.env.VERCEL_TOKEN) {
+    return { kind: "vercel", provider: await createVercelSandbox() }
+  }
+
+  throw new Error(
+    "未配置沙箱 provider：请设置 VERCEL_TOKEN（Vercel 云沙箱）/ DAYTONA_API_KEY（Daytona 云沙箱）/ " +
+      "DEPLOY_TARGET=desktop 或 AI_SANDBOX_PROVIDER=local-process（本机沙箱）",
+  )
+}
+
+function requireEnv(name: string, kind: string): string {
+  const value = process.env[name]?.trim()
+  if (!value) {
+    throw new Error(`AI_SANDBOX_PROVIDER=${kind} 需要 ${name} 环境变量（未设置或为空）`)
+  }
+  return value
+}
+
+function optionalEnv(name: string): string | undefined {
+  const value = process.env[name]?.trim()
+  return value || undefined
+}
+
+async function createVercelSandbox(
+  token: string | undefined = optionalEnv("VERCEL_TOKEN"),
+): Promise<SandboxProvider> {
+  const { vercelSandbox } = await import("@tanstack/ai-sandbox-vercel")
+  return vercelSandbox({
+    token,
+    teamId: optionalEnv("VERCEL_TEAM_ID"),
+    projectId: optionalEnv("VERCEL_PROJECT_ID"),
+    runtime: optionalEnv("AI_SANDBOX_RUNTIME") ?? "node24",
+    // durable runs 的持久化开关：false（默认）时沙箱 stop 后 resume 返回 null。
+    persistent: process.env.AI_SANDBOX_PERSISTENT === "true",
+  })
+}
+
+async function createDaytonaSandbox(
+  apiKey: string | undefined = optionalEnv("DAYTONA_API_KEY"),
+): Promise<SandboxProvider> {
+  const { daytonaSandbox } = await import("@tanstack/ai-sandbox-daytona")
+  return daytonaSandbox({
+    apiKey,
+    apiUrl: optionalEnv("DAYTONA_API_URL"),
+    snapshot: optionalEnv("AI_SANDBOX_SNAPSHOT"),
+    ephemeral: process.env.AI_SANDBOX_EPHEMERAL === "true",
+  })
+}

package/src/server/ai-gateway/sandbox/tool-bridge.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { TOOL_RISK } from "../tools/select"
+
+/** 只需 name 的结构：与 TanStack AI 的具体 tool 类型解耦，便于单测注入桩数据。 */
+export interface SandboxToolLike {
+  readonly name: string
+}
+
+export class SandboxToolLeakError extends Error {
+  constructor(readonly leakedTools: readonly string[]) {
+    super(
+      `[sandbox-tool-bridge] destructive 工具泄漏进沙箱工具面：${leakedTools.join(", ")}`,
+    )
+    this.name = "SandboxToolLeakError"
+  }
+}
+
+/**
+ * 沙箱 agent 工具池（P3 §9.3-1 最关键防线）。
+ *
+ * 语义：write / destructive 级工具**完全不进**工具列表——不是标 needsApproval
+ * 等审批，而是让模型在工具面里根本看不到，无从调用。
+ *
+ * 不复用 selectTools()：它的白名单过滤对 delete_project 无条件放行
+ * （select.ts 的 DELETE_PROJECT_KEY 特判），该硬规则服务于普通对话链的
+ * destructive 审批流；对沙箱工具桥语义恰好相反——destructive 必须不在沙箱
+ * 工具面内。因此这里直接按 TOOL_RISK 过滤。
+ *
+ * fail-closed 两条：
+ * - TOOL_RISK 未收录的工具视为不可信 → 排除（新增工具漏配风险等级时不会
+ *   意外获得沙箱执行权）；
+ * - 结果中出现 destructive 级即 throw（防回归哨兵，安全矩阵 ⑪ 的实现级前置）。
+ *
+ * 用户显式开启某 write 工具（UserAgent.allowedTools ∩ write 级）时才注入；
+ * 逐次审批由各工具定义层已声明的 needsApproval 承担。
+ *
+ * 消费方：任务 11 的委派子 agent（delegate_task 工具面 = sandboxToolPool ∩
+ * agent.allowedTools，设计 §10.6-2）。本任务只交付桥本身与单测，未接入
+ * chat-stream-builder——沙箱开启时普通 app 工具仍走既有 needsApproval 审批流。
+ */
+export function sandboxToolPool<TTool extends SandboxToolLike>(
+  allTools: readonly TTool[],
+  allowedTools?: readonly string[],
+): readonly TTool[] {
+  const explicitWrite = new Set(
+    (allowedTools ?? []).filter((name) => TOOL_RISK[name] === "write"),
+  )
+
+  const pool = allTools.filter((tool) => {
+    const risk = TOOL_RISK[tool.name]
+    if (risk === "read") return true
+    if (risk === "write") return explicitWrite.has(tool.name)
+    return false
+  })
+
+  const leaked = pool.filter((tool) => TOOL_RISK[tool.name] === "destructive")
+  if (leaked.length > 0) {
+    throw new SandboxToolLeakError(leaked.map((tool) => tool.name))
+  }
+
+  return pool
+}

package/src/server/ai-gateway/skills/builtin/competitive-analysis/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: competitive-analysis
+description: 用统一框架做竞品对比——市场定位、功能矩阵、差异化优势与潜在威胁，产出可直接用于决策的结论
+---
+
+# 竞品分析
+
+按以下四个维度展开，每个维度都要落到具体证据，避免「对方体验更好」这类无据判断。
+
+## 1. 市场定位
+
+- 目标客户与客群规模（谁在付钱、决策链是谁）
+- 商业模式与定价结构（席位制、用量制、订阅分层）
+- 增长阶段判断：早期获客 / 规模化 / 存量运营
+- 一句话定位，与我们的定位差异是否清晰
+
+## 2. 功能矩阵
+
+- 按能力域分组，逐项标注「有 / 部分有 / 无」，不确定的标「未验证」
+- 每个「无」要判断：是能力缺失，还是产品策略性不做
+- 找出对方刻意留白的区域——那往往是我们的切入点
+- 详细矩阵模板见 `references/matrix-template.md`，需要时用 `read_skill_resource` 读取
+
+## 3. 差异化
+
+- 我们的独有优势（数据、场景、集成、工作流深度）
+- 对方的独有优势（生态、品牌、客户存量、价格）
+- 双方共同空白点（可抢占的新机会）
+
+## 4. 威胁与应对
+
+- 列出 Top 3 具体威胁，说明触发条件（什么情况下会真的伤害我们）
+- 每个威胁给出应对策略：跟随、差异化、或明确不跟进的理由
+- 标注信息时效性：结论基于的观察日期与信息来源
+
+## 输出要求
+
+- 结论先行：先给「我们的相对位置」判断，再展开论据
+- 区分事实与推测，推测必须显式标注
+- 不做技术优劣的绝对判断，只判断在目标客户场景下的相对价值

package/src/server/ai-gateway/skills/builtin/competitive-analysis/references/matrix-template.md

@@ -0,0 +1,37 @@
+# 竞品功能矩阵模板
+
+使用时把每个「未验证」在拿到证据后改为确定结论；拿不到证据的能力域要写明信息缺口。
+
+## 图例
+
+- ✅ 完整支持，有公开文档或可复现的实测
+- 🟡 部分支持，能力存在但有限制（数量、权限、套餐）
+- ❌ 明确不支持
+- ❓ 未验证（无公开信息或无法访问）
+
+## 矩阵结构
+
+| 能力域 | 能力项 | 我方 | 竞品 A | 竞品 B | 备注 |
+| --- | --- | --- | --- | --- | --- |
+| 核心工作流 | 创建与编辑 | | | | |
+| 核心工作流 | 批量操作 | | | | |
+| 核心工作流 | 版本与回滚 | | | | |
+| 协作 | 多人实时编辑 | | | | |
+| 协作 | 权限粒度 | | | | |
+| 集成 | 第三方接入 | | | | |
+| 智能能力 | AI 辅助 | | | | |
+| 商业化 | 免费额度 | | | | |
+| 商业化 | 企业版能力 | | | | |
+
+## 每个能力域补充三问
+
+1. 这项能力对目标客户的实际价值是什么？（低价值项不必追赶）
+2. 差距是可短期补齐的，还是需要长期投入的基础能力？
+3. 客户会在选型时主动问这一项吗？（决定是否需要进对位话术）
+
+## 结论提炼格式
+
+- **我方优势项**：列 3 项以内，每项一句话说明护城河
+- **可补齐项**：列差距与预估投入量级（人日 / 人月）
+- **战略性不做**：列出并写清不做理由，防止后续被反复提出
+- **信息缺口**：列出仍未验证的能力项与建议验证方式

package/src/server/ai-gateway/skills/builtin/naming-advisor/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: naming-advisor
+description: 为产品、功能或概念提供命名建议，兼顾可记性、可检索性与品牌一致性
+---
+
+# 命名建议
+
+按以下步骤给出命名方案，不要只甩一堆候选词。
+
+## 1. 先澄清
+
+在提方案前确认以下信息（缺则先问，不要直接猜）：
+
+- 命名的对象是什么（产品 / 功能模块 / 内部代号 / 对外术语）
+- 使用场景与受众（对外品牌、内部沟通、开发者文档）
+- 语言要求（纯中文 / 纯英文 / 中英混用）
+- 必须包含或必须避免的语义与词根
+
+## 2. 生成候选
+
+- 每轮给 5 个候选，覆盖三种风格：直白描述型、隐喻联想型、造词缩写型
+- 每个候选附一句「选它的理由」与一句「它的风险」
+- 明确标注哪些是行业通用词（搜索会与竞品混在一起）
+
+## 3. 评估维度
+
+- **可记性**：音节数 ≤ 3 为佳；避免辅音簇与生僻字
+- **可检索性**：拼音或英文是否易输入；是否与高频竞品词碰撞
+- **可发音性**：跨语言能否读出来（对外产品尤其重要）
+- **可延展性**：能否衍生子功能名、文档标签、API 前缀
+- **品牌一致性**：是否与现有产品线词汇体系协调
+- **风险**：商标近似、负面谐音、文化歧义、缩写歧义
+
+## 4. 收敛
+
+- 给出 1 个主推方案 + 2 个备选，并说明取舍逻辑
+- 说明放弃其他候选的原因，避免后续反复讨论
+- 如名称会被写入 API 或代码，提示需要保持的大小写与连字符规范
+
+## 边界
+
+- 不承诺商标可注册性——涉及商标注册时提示需法务检索
+- 不做纯粹的字面联想，必须回到使用场景判断

package/src/server/ai-gateway/skills/builtin/prd-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: prd-review
+description: 逐节审查产品需求文档的完整性、可执行性与验收标准，产出可直接回填文档的审查清单
+---
+
+# PRD 审查
+
+对用户提供的需求文档做一次结构化审查。逐节给出判定，不做泛泛而谈的整体评价。
+
+## 审查顺序
+
+1. **背景与目标** —— 业务问题是否讲清（谁、在什么场景、遇到什么障碍）；目标能否度量；非目标（Out of Scope）是否显式列出。
+2. **用户与场景** —— 目标用户是否有真实依据（调研、数据、访谈）；核心路径是否覆盖主要场景与角色。
+3. **功能范围** —— 每个功能点是否有明确的行为定义与边界；是否把实现方案混进了需求描述。
+4. **交互与流程** —— 主流程与异常流是否成对出现；状态迁移是否闭环；空态、加载态、失败态是否覆盖。
+5. **数据与依赖** —— 关键实体与字段是否定义；上游依赖、接口契约、降级方案是否说明。
+6. **验收标准** —— 是否可测试（有明确的前置条件与期望结果）；是否覆盖边界与异常；是否与目标指标挂钩。
+
+## 输出格式
+
+- 逐节给出「通过 / 需补充 / 需重写」判定，每条附具体理由。
+- 每条问题给出可直接回填的修改建议——写完整句子，不写「建议补充说明」这类空话。
+- 结尾按严重程度排序，列出 Top 3 阻塞项。
+
+## 边界
+
+- 只审查文档本身，不评价业务方向是否值得做。
+- 文档信息不足时明确写「信息缺失」，不要替用户脑补。
+- 需要更细的检查项时，先用 `read_skill_resource` 读取 `references/review-checklist.md` 再开始。

package/src/server/ai-gateway/skills/builtin/prd-review/references/review-checklist.md

@@ -0,0 +1,46 @@
+# PRD 审查细化清单
+
+逐项核对，每一项都能在文档中定位到具体位置时才算通过。
+
+## 背景与目标
+
+- [ ] 现状问题有可量化的描述（受影响人数、频次、损失）
+- [ ] 目标有明确的成功指标与目标值，且可在上线后测量
+- [ ] 护栏指标已声明（不能恶化的指标，如延迟、退订率）
+- [ ] 非目标显式列出，避免评审时被拉入范围蔓延
+- [ ] 假设与风险单独成段，而非散落在正文
+
+## 用户与场景
+
+- [ ] 用户画像区分了「主要用户」与「次要用户」
+- [ ] 每个核心场景包含触发条件、操作步骤、预期结果
+- [ ] 异常流与主流程一一对应，不是「正常情况外均报错」
+- [ ] 无「用户会理解」「用户能看懂」这类未验证的假设
+
+## 功能范围
+
+- [ ] 功能点有唯一标识，可被引用与追踪
+- [ ] 每个功能点标注了优先级（P0/P1/P2）
+- [ ] 边界条件明确（输入范围、上限、权限）
+- [ ] 未把技术方案（用哪个表、哪个算法）写进需求
+
+## 交互与流程
+
+- [ ] 状态机闭环：每个状态都有明确的进入与退出条件
+- [ ] 空态、加载态、失败态、部分成功态均已定义
+- [ ] 关键操作有确认与撤销路径
+- [ ] 错误文案对用户可操作（告知原因与下一步），不是「操作失败」
+
+## 数据与依赖
+
+- [ ] 新增/变更的实体与字段有类型、约束、默认值
+- [ ] 对外依赖列明了接口契约、SLA、降级行为
+- [ ] 数据迁移与兼容策略已说明
+- [ ] 权限模型明确（谁能看、谁能改、谁能删）
+
+## 验收标准
+
+- [ ] 每条验收标准可被测试人员独立执行，不依赖作者口头解释
+- [ ] 覆盖正常路径、边界值、异常输入、权限不足四类
+- [ ] 与目标指标有关联（哪条验收标准证明目标达成）
+- [ ] 性能与容量类需求给出可测量的阈值

package/src/server/ai-gateway/skills/builtin-source.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import {
+  aggregate,
+  inlineSkill,
+  parseSkill,
+  type SkillSource,
+} from "@tanstack/ai-skills"
+import prdReview from "./builtin/prd-review/SKILL.md?raw"
+import prdReviewChecklist from "./builtin/prd-review/references/review-checklist.md?raw"
+import competitiveAnalysis from "./builtin/competitive-analysis/SKILL.md?raw"
+import competitiveMatrix from "./builtin/competitive-analysis/references/matrix-template.md?raw"
+import namingAdvisor from "./builtin/naming-advisor/SKILL.md?raw"
+
+export type WarnFn = (message: unknown, ...rest: Array<unknown>) => void
+
+export interface MarkdownSkillEntry {
+  raw: string
+  resources: Record<string, string>
+}
+
+export interface BuiltSkill {
+  source: SkillSource
+  metadata: { name: string; description: string }
+}
+
+/**
+ * SKILL.md 文本 → SkillSource。解析失败（缺 frontmatter / 缺 description）
+ * 与元数据校验失败（name 不匹配 [a-z0-9-]、超长）一律跳过并 warn，
+ * 绝不抛出：单个内置技能写错不应中断整条对话链路。
+ */
+export function buildSkillsFromMarkdown(
+  entries: Array<MarkdownSkillEntry>,
+  warn: WarnFn = console.warn,
+): Array<BuiltSkill> {
+  const built: Array<BuiltSkill> = []
+  for (const entry of entries) {
+    try {
+      const parsed = parseSkill(entry.raw)
+      if (parsed.warnings.length > 0) {
+        for (const w of parsed.warnings) warn(`[ai-skills] 技能解析警告: ${w.message}`, w.code)
+      }
+      const source = inlineSkill({
+        name: parsed.metadata.name,
+        description: parsed.metadata.description,
+        instructions: parsed.body,
+        resources: entry.resources,
+        ...(parsed.metadata.compatibility
+          ? { compatibility: parsed.metadata.compatibility }
+          : {}),
+      })
+      built.push({
+        source,
+        metadata: {
+          name: parsed.metadata.name,
+          description: parsed.metadata.description,
+        },
+      })
+    } catch (e) {
+      warn(`[ai-skills] 技能加载失败，已跳过:`, e instanceof Error ? e.message : String(e))
+    }
+  }
+  return built
+}
+
+const BUILTIN_ENTRIES: Array<MarkdownSkillEntry> = [
+  {
+    raw: prdReview,
+    resources: { "references/review-checklist.md": prdReviewChecklist },
+  },
+  {
+    raw: competitiveAnalysis,
+    resources: { "references/matrix-template.md": competitiveMatrix },
+  },
+  { raw: namingAdvisor, resources: {} },
+]
+
+// 内置技能是静态文件，模块加载期解析一次即可，避免每次 chat() 重复 parse。
+// inlineSkill 的 revision() 已内建 stableHash，withSkills 侧无需再缓存。
+const builtinMemo = (() => {
+  const built = buildSkillsFromMarkdown(BUILTIN_ENTRIES)
+  return {
+    sources: built.map((b) => b.source),
+    catalog: built.map((b) => b.metadata),
+  }
+})();
+
+export function getBuiltinSkillSources(): Array<SkillSource> {
+  return builtinMemo.sources
+}
+
+export function getBuiltinSkillCatalog(): Array<{ name: string; description: string }> {
+  return builtinMemo.catalog
+}
+
+// 资源读取走单一聚合源：aggregate 的 readResource 按 skill name 路由到
+// 拥有者，因此用户技能未来接入资源列后也会被同一工具覆盖。
+export function getBuiltinResourceSource(): SkillSource {
+  return aggregate(builtinMemo.sources)
+}

package/src/server/ai-gateway/skills/governance.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import {
+  modelFamilyOf,
+  renderCatalog,
+  sortSkills,
+  type SkillMetadata,
+} from "@tanstack/ai-skills"
+
+// tier-1 目录只承载 name + description（description 上限 1024 字符），
+// 单条实际约 40~120 tokens。1600 tokens ≈ 6400 字符，可容纳 40+ 条技能，
+// 远高于任何真实用户的技能数量（付费档 skillQuota=3），因此它是失控兜底
+// 而非节流阀；同时把最坏情况的提示词膨胀压到 24k 上下文窗口的约 7%。
+export const MAX_CATALOG_TOKENS = 1600
+
+// 与 @tanstack/ai-skills 内部 estimateTokens 一致的换算口径。
+const TOKEN_CHARS = 4
+
+// modelFamilyOf 只识别 anthropic/openai/gemini 三大族，其余归 'other'。
+// 下列 adapterKind 虽归 'other'，但其 adapter 确实透传 systemPrompts，
+// 目录可以安全放在系统提示词里；未列出的未知 adapterKind 一律降级为
+// tool-description（目录并入 load_skill 工具描述），保证新增服务商时
+// 技能目录不会静默丢失。
+const SYSTEM_PROMPT_CAPABLE_KINDS = new Set([
+  "openai",
+  "anthropic",
+  "gemini",
+  "openrouter",
+  "groq",
+  "grok",
+  "ollama",
+  "openai-compatible",
+])
+
+export type CatalogPlacement = "system" | "tool-description"
+
+export function resolveCatalogPlacement(adapterKind?: string): CatalogPlacement {
+  if (!adapterKind) return "tool-description"
+  if (modelFamilyOf(adapterKind) !== "other") return "system"
+  return SYSTEM_PROMPT_CAPABLE_KINDS.has(adapterKind) ? "system" : "tool-description"
+}
+
+/**
+ * 估算目录 token 占用。用 anthropic 族的 XML 渲染结果做上限估计——它是
+ * 三种渲染格式里最长的，对 openai/gemini/other 族的 markdown 渲染是
+ * 保守上界，避免裁剪后仍被 withSkills 判定超限而抛 SkillLimitError。
+ */
+export function estimateCatalogTokens(skills: Array<SkillMetadata>): number {
+  return Math.ceil(renderCatalog(sortSkills(skills), "anthropic").length / TOKEN_CHARS)
+}
+
+/**
+ * onLimitExceeded 裁剪器：按稳定排序（sortSkills 按 name 字典序）保留前缀，
+ * 保证同一批技能每次裁剪结果一致——目录内容稳定才能命中模型侧的
+ * 提示词缓存前缀。永不返回空数组（空数组会让 withSkills 抛 SkillLimitError
+ * 并中断整条对话）。
+ */
+export function trimSkillsToBudget(
+  skills: Array<SkillMetadata>,
+  limit: number,
+): Array<SkillMetadata> {
+  const sorted = sortSkills(skills)
+  const kept: Array<SkillMetadata> = []
+  for (const skill of sorted) {
+    if (kept.length === 0) {
+      kept.push(skill)
+      continue
+    }
+    if (estimateCatalogTokens([...kept, skill]) <= limit) kept.push(skill)
+  }
+  return kept
+}