@allbluecn/web-app 0.19.2 → 0.19.4

package/src/server/ai-gateway/tools/plugin-lifecycle-server.ts

@@ -19,6 +19,7 @@
 // 客户端 def 见 plugin-lifecycle-defs.ts（零 prisma import）
 
 import { prisma } from "@allbluecn/database";
+import { z } from "zod";
 import { precheckPluginCode } from "@/server/serverFns/plugins/plugin-precheck";
 import type { AppContext } from "../types";
 import {
@@ -29,6 +30,24 @@ import {
   pluginInspectListDef,
 } from "./plugin-lifecycle-defs";
 
+/**
+ * harnessPlugin.tools Json 列的读侧 schema（审计 🟡：此前裸 `as any[]` 消费，
+ * 畸形数据无防御）。写侧经 plugin_define 的 precheck 约束，此处只做形状收窄。
+ */
+const pluginToolColumnSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  inputSchema: z.unknown().optional(),
+});
+
+function parsePluginToolsColumn(raw: unknown): Array<{ name: string; description: string; inputSchema: unknown }> {
+  const parsed = z.array(pluginToolColumnSchema).safeParse(raw);
+  // 显式带 inputSchema 键（z.unknown() 输出类型要求键存在，值可为 undefined）
+  return parsed.success
+    ? parsed.data.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
+    : [];
+}
+
 export const pluginDefineTool = pluginDefineDef.server<AppContext>(
   async ({ name, purpose, codeHost, codeClient }, { context }) => {
     const userId = context.userId;
@@ -79,7 +98,7 @@ export const pluginRunTool = pluginRunDef.server<AppContext>(
 
     return {
       started: true,
-      tools: plugin.tools as any[],
+      tools: parsePluginToolsColumn(plugin.tools),
     };
   }
 );
@@ -118,9 +137,11 @@ export const pluginInspectListTool = pluginInspectListDef.server<AppContext>(
   async (_args, { context }) => {
     const userId = context.userId;
 
+    // 审计 ⚪：列表场景用 select 投影，避免回拉 codeHost/codeClient 大列（单条 64KB）
     const plugins = await prisma.harnessPlugin.findMany({
       where: { userId, isDeleted: false },
       orderBy: { updatedAt: "desc" },
+      select: { id: true, name: true, purpose: true, version: true, status: true, tools: true },
     });
 
     return {
@@ -130,10 +151,10 @@ export const pluginInspectListTool = pluginInspectListDef.server<AppContext>(
         purpose: p.purpose,
         version: p.version,
         status: p.status,
-        tools: (p.tools as any[])?.map((t) => ({
+        tools: parsePluginToolsColumn(p.tools).map((t) => ({
           name: t.name,
           description: t.description,
-        })) ?? [],
+        })),
       })),
     };
   }

package/src/server/ai-gateway/tools/plugin-tools.ts

@@ -27,23 +27,34 @@ import { buildPluginDynamicToolDef } from "@/lib/plugin-runtime/plugin-tool-defs
 export interface PluginToolDef {
   name: string;
   description: string;
-  inputSchema: any;
+  /** DB Json 列；@tanstack/ai 的 SchemaInput 接受裸 JSON Schema（types.d.ts L84/L1187） */
+  inputSchema: unknown;
 }
 
-export async function buildPluginTools(userId: string): Promise<any[]> {
+/** 工具名/插件名护栏：`__` 是三段前缀 plugin__<plugin>__<tool> 的分隔符（审计 ⚪） */
+function isSafeNameSegment(name: string): boolean {
+  return name.length > 0 && !name.includes("__")
+}
+
+type PluginDynamicTool = ReturnType<typeof buildPluginDynamicToolDef>;
+
+export async function buildPluginTools(userId: string): Promise<PluginDynamicTool[]> {
   const plugins = await prisma.harnessPlugin.findMany({
     where: { userId, status: "running", isDeleted: false },
     select: { id: true, name: true, tools: true },
   });
 
-  const tools: any[] = [];
+  const tools: PluginDynamicTool[] = [];
 
   for (const plugin of plugins) {
+    // 插件名含 `__` 会让拼出的工具名歧义/可伪装成其他插件的工具，读侧跳过
+    if (!isSafeNameSegment(plugin.name)) continue;
     const pluginTools = plugin.tools as PluginToolDef[] | null;
     if (!pluginTools || !Array.isArray(pluginTools)) continue;
 
     for (const toolDef of pluginTools) {
-      if (!toolDef.name || !toolDef.description) continue;
+      if (!toolDef?.name || !toolDef?.description) continue;
+      if (!isSafeNameSegment(toolDef.name)) continue;
 
       tools.push(buildPluginDynamicToolDef(plugin.name, toolDef));
     }

package/src/server/ai-gateway/tools/select.ts

@@ -23,7 +23,8 @@
  *                不能豁免审批。此类工具在工具定义上必须 `needsApproval: true`，
  *                selectTools 有防御断言锁定此不变式，避免未来回归。
  *
- * 分级仅覆盖 agent 可见的 8 个工具；web_search 属外部检索只读。
+ * 分级覆盖 agent 可见的全部 15 个工具；web_search / knowledge_search 等
+ * 外部检索类只读。
  * todo_write/plan_submit 归 read——它们只写投影快照（ADR 7 的
  * projection/<threadId> namespace，非用户资产表），不产生业务副作用。
  */
@@ -68,9 +69,12 @@ function normalizeToolName(name: string): string {
 /**
  * 从入池工具集中挑选工具。
  * - `allowedKeys` 为空/未传：返回全集（agent 未启用或平台默认全可见场景）。
- * - `allowedKeys` 非空：白名单过滤，destructive 级工具（当前仅 delete_project）
- *   无论是否在白名单中都会保留——平台硬规则，agent 无权通过白名单隐藏它
- *   （agent 无法控制是否可见，但审批门槛恒定）。
+ * - `allowedKeys` 非空：白名单过滤。destructive 级工具的平台硬规则是
+ *   「必须 needsApproval: true」（下方断言锁定）；在此基础上两种 destructive
+ *   的可见性策略**有意不同**（审计 🟢：原注释「当前仅 delete_project」过时）：
+ *   - delete_project：无论是否在白名单中都强制保留（平台工具面恒可见，审批恒在）；
+ *   - plugin_define：不强制保留——可见性仍由白名单决定，其审批链在 define
+ *     生效时逐次触发（needsApproval 已满足平台硬规则）。
  *
  * 防御断言：destructive 级工具必须显式声明 `needsApproval: true`，否则
  * 抛出运行时错误。此断言是设计 §9.2 的回归哨兵——未来若有人给 delete_project

package/src/server/ai-gateway/tools/server.ts

@@ -23,6 +23,7 @@ import { prisma } from "@allbluecn/database"
 import { constrainKnowledgeBaseId, mergeKnowledgeResults, type KnowledgeSearchInput } from "./knowledge-scope"
 import { todoWriteTool } from "./todo-write"
 import { planSubmitTool } from "./plan-submit"
+import { ToolValidationError, toToolErrorMessage } from "./tool-errors"
 
 /**
  * knowledge_search 的执行逻辑（从 tool 定义中抽出，使返回边界可被直接单测）。
@@ -59,15 +60,26 @@ export async function executeKnowledgeSearch(
 
   let searchKbIds: string[]
   if (knowledgeBaseId && boundKbIds) {
-    const constrained = constrainKnowledgeBaseId(
-      { query, knowledgeBaseId, topK },
-      boundKbIds,
-    )
-    searchKbIds = [constrained.knowledgeBaseId]
+    // 空绑定的语义是「本线程不可检索任何 KB」（fail-closed，审计 2026-10-25 🟠）：
+    // constrainKnowledgeBaseId 对空绑定原样放行，此处显式短路，不得 fail-open。
+    searchKbIds = boundKbIds.length > 0
+      ? [constrainKnowledgeBaseId({ query, knowledgeBaseId, topK }, boundKbIds).knowledgeBaseId]
+      : []
   } else if (boundKbIds && boundKbIds.length > 0) {
     searchKbIds = boundKbIds
+  } else if (knowledgeBaseId) {
+    // 无绑定上下文：模型给的 kbId 必须落在当前用户可读范围（审计 🟠 fail-open 跨用户检索）
+    const readable = await prisma.knowledgeBase.findFirst({
+      where: {
+        id: knowledgeBaseId,
+        isDeleted: false,
+        OR: [{ userId: context.userId }, { visibility: { in: ["team", "general"] } }],
+      },
+      select: { id: true },
+    })
+    searchKbIds = readable ? [knowledgeBaseId] : []
   } else {
-    searchKbIds = knowledgeBaseId ? [knowledgeBaseId] : []
+    searchKbIds = []
   }
 
   if (searchKbIds.length === 0) {
@@ -82,7 +94,7 @@ export async function executeKnowledgeSearch(
         (raw) => raw.map((r: { id: string; content: string; similarity: number }) => ({
           content: r.content,
           documentTitle: r.id,
-          documentId: r.id.split("-")[0],
+          documentId: documentIdFromEmbeddingId(r.id),
           score: r.similarity,
         })),
       ),
@@ -124,13 +136,67 @@ export async function executeKnowledgeSearch(
 
 const knowledgeSearchTool = knowledgeSearchDef.server<AppContext>(executeKnowledgeSearch)
 
+/**
+ * AI 工具的 KB 写权限（审计 2026-10-25 🔴：document_action 裸 id 水平越权）。
+ * 口径对齐人工路径（knowledge.ts update/delete 的 kb: { userId }）：属主专用；
+ * 线程绑定了 KB 时再收紧到绑定范围（收敛提示注入的爆炸半径）。
+ */
+async function assertToolKbWriteAccess(kbId: string, context: AppContext): Promise<void> {
+  const bound = Array.isArray(context.knowledgeBaseIds) ? context.knowledgeBaseIds : undefined
+  if (bound && bound.length > 0 && !bound.includes(kbId)) {
+    throw new ToolValidationError("knowledgeBaseId 不在本线程绑定的知识库范围内")
+  }
+  const kb = await prisma.knowledgeBase.findFirst({
+    where: { id: kbId, userId: context.userId, isDeleted: false },
+    select: { id: true },
+  })
+  if (!kb) throw new ToolValidationError("knowledgeBaseId 不存在或无权限")
+}
+
+/** update/delete：文档必须存在且其 KB 属当前用户；返回行供后续使用 */
+async function assertToolDocAccess(documentId: string, context: AppContext) {
+  const doc = await prisma.knowledgeDocument.findFirst({
+    where: {
+      id: documentId,
+      isDeleted: false,
+      kb: { userId: context.userId, isDeleted: false },
+    },
+    select: { id: true, kbId: true },
+  })
+  if (!doc) throw new ToolValidationError("documentId 不存在或无权限")
+  const bound = Array.isArray(context.knowledgeBaseIds) ? context.knowledgeBaseIds : undefined
+  if (bound && bound.length > 0 && !bound.includes(doc.kbId)) {
+    throw new ToolValidationError("documentId 不在本线程绑定的知识库范围内")
+  }
+  return doc
+}
+
+/**
+ * embedding 行 id 形如 "<docId>-<chunkIndex>"（knowledge-index-utils 插入时拼接）。
+ * 用 lastIndexOf 取分离点：docId 自身含 `-`（如 uuid 形态）时前向 split 会截断错误。
+ */
+function documentIdFromEmbeddingId(embeddingId: string): string {
+  const i = embeddingId.lastIndexOf("-")
+  return i > 0 ? embeddingId.slice(0, i) : embeddingId
+}
+
 const documentCrudTool = documentCrudDef.server<AppContext>(
   async ({ action, knowledgeBaseId, documentId, title, content, parentId }, { context }) => {
     try {
       if (action === "create") {
+        if (!knowledgeBaseId) return { success: false, error: "knowledgeBaseId is required" }
+        await assertToolKbWriteAccess(knowledgeBaseId, context)
+        if (parentId) {
+          // 挂载点必须存在且属于同一 KB（防把文档挂到他人 KB 节点下）
+          const parent = await prisma.knowledgeDocument.findFirst({
+            where: { id: parentId, kbId: knowledgeBaseId, isDeleted: false },
+            select: { id: true },
+          })
+          if (!parent) return { success: false, error: "parentId 不存在或不属于该知识库" }
+        }
         const doc = await prisma.knowledgeDocument.create({
           data: {
-            title: title || "Untitled",
+            title: title || "未命名文档",
             content: content || "",
             kbId: knowledgeBaseId,
             parentId: parentId || null,
@@ -145,7 +211,8 @@ const documentCrudTool = documentCrudDef.server<AppContext>(
         return { success: true, documentId: doc.id }
       }
       if (action === "update" && documentId) {
-        const doc = await prisma.knowledgeDocument.update({
+        const doc = await assertToolDocAccess(documentId, context)
+        const updated = await prisma.knowledgeDocument.update({
           where: { id: documentId },
           data: {
             ...(title !== undefined ? { title } : {}),
@@ -155,26 +222,23 @@ const documentCrudTool = documentCrudDef.server<AppContext>(
         if (content !== undefined) {
           const aiConfig = await getPorts().infra.resolveKnowledgeAiConfig(doc.kbId)
           getPorts().infra.indexDocumentEmbeddings(
-            { id: doc.id, kbId: doc.kbId, title: doc.title, content: doc.content as string },
+            { id: updated.id, kbId: updated.kbId, title: updated.title, content: updated.content as string },
             aiConfig
           ).catch(() => {})
         }
         return { success: true, documentId }
       }
       if (action === "delete" && documentId) {
-        const doc = await prisma.knowledgeDocument.findUnique({
-          where: { id: documentId },
-          select: { id: true },
-        })
+        await assertToolDocAccess(documentId, context)
         await prisma.knowledgeDocument.delete({ where: { id: documentId } })
-        if (doc) {
-          getPorts().infra.deleteEmbeddings("knowledge_embeddings", "documentId", documentId).catch(() => {})
-        }
+        getPorts().infra.deleteEmbeddings("knowledge_embeddings", "documentId", documentId).catch(() => {})
         return { success: true, documentId }
       }
       return { success: false, error: "Invalid action or missing documentId" }
     } catch (e) {
-      return { success: false, error: String(e) }
+      // 审计 ⚪：原始异常串不回传 LLM（可能携带 Prisma/内部细节）；
+      // 主动校验错误（ToolValidationError）原样透传，其余收敛为简短消息。
+      return { success: false, error: toToolErrorMessage(e) }
     }
   },
 )
@@ -215,7 +279,15 @@ export const webSearchTool = webSearchDef.server<AppContext>(
 )
 
 const reindexKnowledgeBaseTool = reindexKnowledgeBaseDef.server<AppContext>(
-  async ({ knowledgeBaseId }) => {
+  async ({ knowledgeBaseId }, { context }) => {
+    // 全量重建清空并重写该 KB 的向量、消耗属主 embedding 配额：仅 KB 属主可触发
+    // （审计 2026-10-25 🟠：裸 kbId 可对任意 KB 触发昂贵重建）
+    const kb = await prisma.knowledgeBase.findFirst({
+      where: { id: knowledgeBaseId, userId: context.userId, isDeleted: false },
+      select: { id: true },
+    })
+    if (!kb) throw new ToolValidationError("knowledgeBaseId 不存在或无权限")
+
     const docs = await prisma.knowledgeDocument.findMany({
       where: { kbId: knowledgeBaseId, isDeleted: false },
       select: { id: true, title: true, content: true, kbId: true },

package/src/server/ai-gateway/tools/todo-write.ts

@@ -28,9 +28,10 @@ export type TodoItem = {
 };
 
 const todoItemSchema = z.object({
-  content: z.string().describe("任务描述"),
+  // 单条长度上限（审计 ⚪）：快照整体写入 chatPersistenceMeta JSON 列
+  content: z.string().max(500).describe("任务描述"),
   status: z.enum(["pending", "in_progress", "completed"]).describe("任务状态"),
-  activeForm: z.string().optional().describe("进行中的动作描述（仅 status='in_progress' 时填写，进行态展示用）"),
+  activeForm: z.string().max(200).optional().describe("进行中的动作描述（仅 status='in_progress' 时填写，进行态展示用）"),
 });
 
 export const todoWriteDef = toolDefinition({
@@ -39,7 +40,7 @@ export const todoWriteDef = toolDefinition({
     "整表替换当前对话的待办清单。每次调用传入完整的最新 todo 列表，禁止增量补丁；" +
     "客户端投影面板以此为准渲染。用于跟踪复杂多步任务的进度。",
   inputSchema: z.object({
-    todos: z.array(todoItemSchema).describe("完整待办列表（整表替换语义）"),
+    todos: z.array(todoItemSchema).max(100).describe("完整待办列表（整表替换语义）"),
   }),
   outputSchema: z.object({
     stored: z.boolean().describe("是否已写入服务端权威快照；false 表示无 threadId 未落库"),

package/src/server/ai-gateway/tools/tool-errors.ts

@@ -0,0 +1,38 @@
+// 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/>.
+
+/**
+ * 工具校验失败标记：message 面向 LLM，可原样回传（审计 ⚪：error 回传需区分
+ * 「有意给出的校验消息」与「未预期异常」——后者可能携带 Prisma/内部细节）。
+ */
+export class ToolValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "ToolValidationError"
+  }
+}
+
+/**
+ * 把工具 catch 到的异常转为回传 LLM 的 error 字符串：
+ * ToolValidationError（本仓工具主动抛的归属/参数校验）原样透传；
+ * 其余异常只给简短可读消息，原始细节留在服务端日志（审计 ⚪）。
+ */
+export function toToolErrorMessage(e: unknown): string {
+  if (e instanceof ToolValidationError) return e.message
+  console.error("[ai-gateway tool] 未预期异常:", e instanceof Error ? e.message : String(e))
+  return "操作失败，请稍后重试"
+}

package/src/server/ai-gateway/unified-router.ts

@@ -56,20 +56,25 @@ export interface UnifiedAiRequest {
   threadId?: string
   runId?: string
   parentRunId?: string
-   resume?: Array<unknown>
-   signal?: AbortSignal
-   request?: Request
-   /** GitHub 代码工作区上下文（harness 路由选中仓库后注入） */
-   workspaceContext?:
-     | { type: "github"; owner: string; repo: string; defaultBranch: string }
-     | { type: "local"; path: string }
-     | { type: "cloud"; workspaceId: string }
-   /** 已解析的模型来源模式（由 chat-handler 从 session 注入，跳过 per-request DB findUnique） */
-   aiSourceMode?: string | null
-  }
+  resume?: Array<unknown>
+  signal?: AbortSignal
+  request?: Request
+  /** GitHub 代码工作区上下文（harness 路由选中仓库后注入） */
+  workspaceContext?:
+    | { type: "github"; owner: string; repo: string; defaultBranch: string }
+    | { type: "local"; path: string }
+    | { type: "cloud"; workspaceId: string }
+  /** 已解析的模型来源模式（由 chat-handler 从 session 注入，跳过 per-request DB findUnique） */
+  aiSourceMode?: string | null
+}
 
 export type UnifiedAiStream = AsyncIterable<StreamChunk>
 
+/** desktop 未配置 DESKTOP_SAAS_URL 时的默认 SaaS 端点（审计 ⚪：提为具名常量） */
+const DEFAULT_DESKTOP_SAAS_URL = 'https://allblue.litsex.cn'
+/** BYOK 命中但无模型名时的兜底模型（审计 ⚪：提为具名常量） */
+const DEFAULT_BYOK_FALLBACK_MODEL = 'gpt-4o-mini'
+
 export type UnifiedAiRoute =
   | { kind: 'local'; stream: UnifiedAiStream }
   | { kind: 'remote'; saasUrl: string; token: string; model?: string }
@@ -96,7 +101,7 @@ async function tryRemoteRoute(req: UnifiedAiRequest): Promise<UnifiedAiRoute | n
   if (!remoteAuth) return null
   return {
     kind: 'remote',
-    saasUrl: process.env.DESKTOP_SAAS_URL || 'https://allblue.litsex.cn',
+    saasUrl: process.env.DESKTOP_SAAS_URL || DEFAULT_DESKTOP_SAAS_URL,
     token: remoteAuth.sessionToken ?? '',
     model: req.model,
   }
@@ -152,6 +157,25 @@ export async function resolveUnifiedAiStream(
   throw new Error('remote route requires chat-handler forwarding')
 }
 
+/**
+ * 本地路由装配收敛点（审计 🔵）：tryByok 四个分支只有「配置来源 → adapter →
+ * 计量维度」不同，装配体完全一致。新增配置来源时只改调用侧。
+ */
+async function buildLocalRoute(
+  adapter: unknown,
+  req: UnifiedAiRequest,
+  usage: { providerConfigKind?: string; usageProvider?: string; usageModel?: string },
+): Promise<UnifiedAiRoute> {
+  return {
+    kind: 'local',
+    stream: await buildChatStreamWithTools({
+      adapter,
+      ...req,
+      ...usage,
+    }),
+  }
+}
+
 async function tryByok(
   req: UnifiedAiRequest,
   request?: Request,
@@ -167,22 +191,17 @@ async function tryByok(
         req.model,
       )
       if (meta) {
-        const byokModel = meta.model ?? req.model ?? 'gpt-4o-mini'
+        const byokModel = meta.model ?? req.model ?? DEFAULT_BYOK_FALLBACK_MODEL
         const adapter = await createProviderAdapter(meta.providerId, {
           model: byokModel,
           apiKey: byokKey,
           baseUrl: meta.baseUrl,
         })
-        return {
-          kind: 'local',
-          stream: await buildChatStreamWithTools({
-            adapter,
-            ...req,
-            providerConfigKind: meta.adapterKind,
-            usageProvider: meta.adapterKind,
-            usageModel: byokModel,
-          }),
-        }
+        return buildLocalRoute(adapter, req, {
+          providerConfigKind: meta.adapterKind,
+          usageProvider: meta.adapterKind,
+          usageModel: byokModel,
+        })
       }
     }
   }
@@ -195,16 +214,11 @@ async function tryByok(
         apiKey: providerConfig.apiKey,
         baseUrl: providerConfig.baseUrl,
       })
-      return {
-        kind: 'local',
-        stream: await buildChatStreamWithTools({
-          adapter,
-          ...req,
-          providerConfigKind: providerConfig.adapterKind,
-          usageProvider: providerConfig.adapterKind,
-          usageModel: providerConfig.model,
-        }),
-      }
+      return buildLocalRoute(adapter, req, {
+        providerConfigKind: providerConfig.adapterKind,
+        usageProvider: providerConfig.adapterKind,
+        usageModel: providerConfig.model,
+      })
     }
   }
   const defaultConfig = await resolveDefaultProviderConfig(req.userId)
@@ -214,30 +228,20 @@ async function tryByok(
       apiKey: defaultConfig.apiKey,
       baseUrl: defaultConfig.baseUrl,
     })
-    return {
-      kind: 'local',
-      stream: await buildChatStreamWithTools({
-        adapter,
-        ...req,
-        providerConfigKind: defaultConfig.adapterKind,
-        usageProvider: defaultConfig.adapterKind,
-        usageModel: defaultConfig.model,
-      }),
-    }
+    return buildLocalRoute(adapter, req, {
+      providerConfigKind: defaultConfig.adapterKind,
+      usageProvider: defaultConfig.adapterKind,
+      usageModel: defaultConfig.model,
+    })
   }
   const fallbackConfig = await resolveAiConfig(req.userId)
   if (!fallbackConfig) return null
   const adapter = createAdapter(fallbackConfig)
-  return {
-    kind: 'local',
-    stream: await buildChatStreamWithTools({
-      adapter,
-      ...req,
-      providerConfigKind: 'openrouter',
-      usageProvider: fallbackConfig.provider,
-      usageModel: fallbackConfig.model,
-    }),
-  }
+  return buildLocalRoute(adapter, req, {
+    providerConfigKind: 'openrouter',
+    usageProvider: fallbackConfig.provider,
+    usageModel: fallbackConfig.model,
+  })
 }
 
 async function tryHosted(req: UnifiedAiRequest, request?: Request): Promise<UnifiedAiRoute | null> {
@@ -246,13 +250,19 @@ async function tryHosted(req: UnifiedAiRequest, request?: Request): Promise<Unif
   try {
     await getPorts().accessPolicy.requireFeature(request, 'hostedAi')
   } catch (err) {
-    console.warn('[tryHosted] 托管 AI 权益检查失败，降级 BYOK:', (err as Error).name)
+    // 审计 ⚪：仅 warn err.name 排查信息不足，补 message
+    console.warn(
+      '[tryHosted] 托管 AI 权益检查失败，降级 BYOK:',
+      err instanceof Error ? `${err.name}: ${err.message}` : String(err),
+    )
     return null
   }
   if (!req.workspaceId) return null
   return {
     kind: 'local',
     stream: hostedAi.chatStream(
+      // ⚠ hosted 侧契约仅声明 string content（审计 ⚪【待决策】：分段 content
+      // （图片 parts 等）是否支持取决于 Pro 侧 chatStream 实现，此处维持原强转）
       {
         workspaceId: req.workspaceId,
         userId: req.userId,

package/src/server/ai-ports.ts

@@ -20,9 +20,13 @@ import { getCurrentSession } from "@/lib/session"
 import { invalidateProfileCache } from "@/lib/auth/auth.config"
 import { readRemoteAuth } from "@/server/remote-auth"
 import { requireFeature } from "@/server/entitlements"
-import { searchWeb } from "@/server/serverFns/web-search"
+import { searchWeb } from "@/server/web-search"
 import { checkAiRateLimit } from "@/server/middlewares/rate-limit-server-fn"
-import { ragSearch } from "@/lib/rag"
+import {
+  checkRateLimit,
+  RateLimitExceededError,
+} from "@/server/lib/rate-limit"
+import { ragSearch } from "@/server/rag"
 import { getVectorStore } from "@/lib/vector-store"
 import {
   indexDocumentEmbeddings as knowledgeIndexDocumentEmbeddings,
@@ -36,6 +40,12 @@ import { DbBlobStore } from "@/server/ai-gateway/storage"
 
 registerProServiceResolver(getProService)
 
+/** 知识库索引/embedding 兜底 chat 模型（审计 🟡：原硬编码，上移为 env 可覆盖） */
+const KNOWLEDGE_FALLBACK_MODEL = process.env.KNOWLEDGE_FALLBACK_MODEL ?? "openai/gpt-4o-mini"
+
+/** 无主 webSearch 调用的共享匿名桶（审计 🟡：userId 缺省时不再零限流） */
+const WEB_SEARCH_ANON_LIMIT = { max: 20, windowMs: 60_000 } as const
+
 registerGatewayPorts({
   keyCipher: {
     decrypt: (encryptedKey: string): string => {
@@ -51,6 +61,13 @@ registerGatewayPorts({
     search: async (query: string, limit: number, userId?: string) => {
       if (userId) {
         await checkAiRateLimit(userId, "webSearch")
+      } else {
+        // 无主调用（端口契约 userId 可选，个别调用点未透传）：回落共享匿名桶，
+        // 不再零限流打 SearXNG。抛 RateLimitExceededError 与 checkAiRateLimit 同口径。
+        const anon = checkRateLimit("websearch:anonymous", WEB_SEARCH_ANON_LIMIT)
+        if (!anon.allowed) {
+          throw new RateLimitExceededError(anon.retryAfterMs, "webSearch")
+        }
       }
       return searchWeb(query, limit)
     },
@@ -68,8 +85,10 @@ registerGatewayPorts({
       return {
         provider: "openrouter",
         apiKey: raw.apiKey,
-        model: "openai/gpt-4o-mini",
+        model: KNOWLEDGE_FALLBACK_MODEL,
         ...(raw.baseUrl ? { baseUrl: raw.baseUrl } : {}),
+        // source 取值为 AiConfig 联合类型既有项："env" 语义是「非用户配置的
+        // 系统级来源」，此处实取知识库（infra）配置，排障时按本注释理解
         source: "env",
       } satisfies AiConfig
     },