@allbluecn/web-app 0.19.2 → 0.19.4

package/src/server/bug-report/report-handler.ts

@@ -31,6 +31,14 @@ import { resolveSeverity } from "./severity-rules";
 import { hashToken, isValidTokenFormat } from "./tokens";
 import { fireBugWebhook } from "./webhook-out";
 import { checkRateLimit } from "@/server/lib/rate-limit";
+import {
+  allocateBugSequence,
+  buildBugPrefix,
+  isBugFingerprintConflict,
+} from "@/server/lib/bug-sequence";
+import { withSequenceNumberRetry } from "@/server/lib/sequence-number-retry";
+import { truncateNullable, toJsonValue } from "@/server/lib/text-truncate";
+import { detectImageMime } from "@/server/lib/image-magic";
 
 // ── 协议常量（§8.2 约束）──
 export const MAX_BODY_BYTES = 256 * 1024; // body ≤ 256KB，超限 413
@@ -47,7 +55,6 @@ const TITLE_MESSAGE_SLICE = 80;
 const URL_UA_MAX = 2048;
 const STACK_SUMMARY_MAX = 64 * 1024;
 const EVENT_PAYLOAD_MAX = 64 * 1024;
-const IDENTIFIER_MAX_RETRIES = 5;
 
 // chrome_ext 截图（任务 25，§12）：PNG dataURL → Blob，≤5MB 沿用 collect 截图
 // 语义（collect-handler MAX_SCREENSHOT_BYTES 同值）；超限/非法跳过该图不失败。
@@ -95,8 +102,7 @@ const json = (
     headers: { "Content-Type": "application/json", ...headers },
   });
 
-const truncate = (value: string | null | undefined, max: number) =>
-  typeof value === "string" ? value.slice(0, max) : null;
+const truncate = truncateNullable;
 
 /** source 映射（§8.3）：扩展上报归 chrome_ext，其余（js_error/node_error/custom）归 sdk_auto */
 function mapReportSource(type: string | undefined): "sdk_auto" | "chrome_ext" {
@@ -108,11 +114,7 @@ function mapReportSource(type: string | undefined): "sdk_auto" | "chrome_ext" {
  * 超限依次丢弃 stack → breadcrumbs/extra（堆栈与面包屑是体积大头），
  * 兜底保证 JSON 完整可解析。
  */
-/** JSON 字段落库类型收敛：unknown 深度结构经 JSON round-trip 保证可序列化（Prisma InputJsonValue） */
-function toJsonValue(value: unknown): Prisma.InputJsonValue {
-  return JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue;
-}
-
+// toJsonValue 复用 server/lib/text-truncate 单源实现（审计 🔵 收敛）
 function buildEventPayload(
   event: ReportEvent,
   sdkVersion: string | undefined,
@@ -155,9 +157,17 @@ function buildEventPayload(
  */
 export async function handleBugReport(request: Request): Promise<Response> {
   // ── 载荷体积防线（先于鉴权：拒绝 oversized body 不消耗 DB/限流资源）──
-  const contentLength = Number(request.headers.get("content-length") ?? "0");
-  if (contentLength > MAX_BODY_BYTES) {
-    return json({ error: "payload_too_large" }, 413);
+  // content-length 头非法（非数字 → NaN、负数）直接 400：NaN 比较恒 false
+  // 会绕过前置防线，超大 body 全量进内存才被第二道兜底拦下（审计 🟡）
+  const rawContentLength = request.headers.get("content-length");
+  if (rawContentLength !== null) {
+    const contentLength = Number(rawContentLength);
+    if (!Number.isFinite(contentLength) || contentLength < 0) {
+      return json({ error: "invalid_content_length" }, 400);
+    }
+    if (contentLength > MAX_BODY_BYTES) {
+      return json({ error: "payload_too_large" }, 413);
+    }
   }
   const rawText = await request.text();
   if (Buffer.byteLength(rawText) > MAX_BODY_BYTES) {
@@ -328,126 +338,119 @@ async function createBugFromEvent(
   const rawPayload = buildEventPayload(event, ctx.sdkVersion, ctx.type, screenshot);
   const severity = resolveSeverity({ errorName: event.errorName, type: ctx.type });
 
-  for (let attempt = 0; attempt < IDENTIFIER_MAX_RETRIES; attempt++) {
-    try {
-      const created = await prisma.$transaction(async (tx) => {
-        const project = await tx.project.findUnique({
-          where: { id: ctx.projectId },
-          select: { id: true, ownerId: true, displayId: true, name: true },
-        });
-        if (!project) throw new Error("token 指向的项目不存在");
+  // 发号/重试语义单源（审计 🔵）：withSequenceNumberRetry 承担 identifier/scope
+  // P2002 重试；指纹 P2002 在此降级为 null（调用方重查后走计数分支），不重试。
+  try {
+    const created = await withSequenceNumberRetry(
+      () =>
+        prisma.$transaction(async (tx): Promise<CreatedBugForWebhook> => {
+          const project = await tx.project.findUnique({
+            where: { id: ctx.projectId },
+            select: { id: true, ownerId: true, displayId: true, name: true },
+          });
+          if (!project) throw new Error("token 指向的项目不存在");
+
+          const { seq, identifier } = await allocateBugSequence(
+            tx,
+            ctx.projectId,
+            buildBugPrefix(project.displayId, project.name),
+          );
+
+          // SDK 无登录用户，Bug.createdById 必填 FK 落项目 owner
+          //（同 collect 匿名提交先例，活动流以 actorType=sdk 区分）
+          const bug = await tx.bug.create({
+            data: {
+              sequenceId: seq,
+              identifier,
+              projectId: ctx.projectId,
+              title,
+              state: "open",
+              severity,
+              source: mapReportSource(ctx.type),
+              fingerprint,
+              env,
+              url,
+              userAgent,
+              stackSummary,
+              createdById: project.ownerId,
+            },
+            select: { id: true },
+          });
 
-        // Bug 发号 scope 带 bug: 前缀，与 Story 序列隔离（照 bug-crud.ts）
-        const counter = await tx.sequenceCounter.upsert({
-          where: { scope: `bug:${ctx.projectId}` },
-          create: { scope: `bug:${ctx.projectId}`, seq: 1 },
-          update: { seq: { increment: 1 } },
-        });
-        const prefix =
-          (project.displayId ?? project.name ?? "")
-            .replace(/[^a-zA-Z0-9]/g, "")
-            .toUpperCase() || "PRJ";
-
-        // SDK 无登录用户，Bug.createdById 必填 FK 落项目 owner
-        //（同 collect 匿名提交先例，活动流以 actorType=sdk 区分）
-        const bug = await tx.bug.create({
-          data: {
-            sequenceId: counter.seq,
-            identifier: `${prefix}-B${counter.seq}`,
+          await tx.bugEvent.create({
+            data: { bugId: bug.id, rawPayload, userAgent },
+          });
+          await tx.bugActivity.create({
+            data: {
+              bugId: bug.id,
+              userId: null,
+              actorType: "sdk",
+              action: "sdk_reported",
+            },
+          });
+          await tx.projectActivity.create({
+            data: {
+              projectId: ctx.projectId,
+              userId: project.ownerId,
+              action: "created",
+              targetType: "bug",
+              targetId: bug.id,
+            },
+          });
+
+          // P4 任务 22：autoFixEnabled=true 时新指纹自动入队 AI 修复（§10.3，trigger=auto）。
+          // 事务边界：run 创建在事务内——与 BUG 建单原子（防「有 BUG 无 run」半态）；
+          // webhook（fix.requested）在事务提交成功后 fire-and-forget——回滚不外发通知。
+          // 去重命中的更新分支（dedupeExistingBug）不触发，避免错误风暴。
+          let autoFixRunId: string | null = null;
+          if (ctx.settings.autoFixEnabled) {
+            const pendingCount = await tx.bugFixRun.count({
+              where: { status: "pending", bug: { projectId: ctx.projectId } },
+            });
+            if (pendingCount < AUTO_FIX_QUEUE_LIMIT) {
+              const fixRun = await tx.bugFixRun.create({
+                data: { bugId: bug.id, status: "pending", triggerType: "auto" },
+                select: { id: true },
+              });
+              autoFixRunId = fixRun.id;
+            } else {
+              // 风暴上限跳过留痕：不建 run、不发 webhook，仅活动注明队列已满
+              await tx.bugActivity.create({
+                data: {
+                  bugId: bug.id,
+                  userId: null,
+                  actorType: "sdk",
+                  action: "fix_queue_full",
+                  newValue: String(AUTO_FIX_QUEUE_LIMIT),
+                },
+              });
+            }
+          }
+
+          // P4 任务 23 接入点：bug.created webhook 在事务提交后 fire（见下方 fireCreationWebhooks）。
+
+          return {
+            id: bug.id,
             projectId: ctx.projectId,
+            identifier,
             title,
-            state: "open",
             severity,
-            source: mapReportSource(ctx.type),
-            fingerprint,
-            env,
             url,
-            userAgent,
             stackSummary,
-            createdById: project.ownerId,
-          },
-          select: { id: true },
-        });
-
-        await tx.bugEvent.create({
-          data: { bugId: bug.id, rawPayload, userAgent },
-        });
-        await tx.bugActivity.create({
-          data: {
-            bugId: bug.id,
-            userId: null,
-            actorType: "sdk",
-            action: "sdk_reported",
-          },
-        });
-        await tx.projectActivity.create({
-          data: {
-            projectId: ctx.projectId,
-            userId: project.ownerId,
-            action: "created",
-            targetType: "bug",
-            targetId: bug.id,
-          },
-        });
-
-        // P4 任务 22：autoFixEnabled=true 时新指纹自动入队 AI 修复（§10.3，trigger=auto）。
-        // 事务边界：run 创建在事务内——与 BUG 建单原子（防「有 BUG 无 run」半态）；
-        // webhook（fix.requested）在事务提交成功后 fire-and-forget——回滚不外发通知。
-        // 去重命中的更新分支（dedupeExistingBug）不触发，避免错误风暴。
-        let autoFixRunId: string | null = null;
-        if (ctx.settings.autoFixEnabled) {
-          const pendingCount = await tx.bugFixRun.count({
-            where: { status: "pending", bug: { projectId: ctx.projectId } },
-          });
-          if (pendingCount < AUTO_FIX_QUEUE_LIMIT) {
-            const fixRun = await tx.bugFixRun.create({
-              data: { bugId: bug.id, status: "pending", triggerType: "auto" },
-              select: { id: true },
-            });
-            autoFixRunId = fixRun.id;
-          } else {
-            // 风暴上限跳过留痕：不建 run、不发 webhook，仅活动注明队列已满
-            await tx.bugActivity.create({
-              data: {
-                bugId: bug.id,
-                userId: null,
-                actorType: "sdk",
-                action: "fix_queue_full",
-                newValue: String(AUTO_FIX_QUEUE_LIMIT),
-              },
-            });
-          }
-        }
-
-        // P4 任务 23 接入点：bug.created webhook 在事务提交后 fire（见下方 fireCreationWebhooks）。
-
-        return {
-          id: bug.id,
-          projectId: ctx.projectId,
-          identifier: `${prefix}-B${counter.seq}`,
-          title,
-          severity,
-          url,
-          stackSummary,
-          autoFixRunId,
-        };
-      });
-      // 事务已提交：仅提交成功才外发通知（回滚路径到不了这里）
-      fireCreationWebhooks(created);
-      return created;
-    } catch (e: unknown) {
-      const code = (e as { code?: string }).code;
-      const target = (e as { meta?: { target?: string[] } }).meta?.target;
-      if (code === "P2002" && target?.includes("identifier") && attempt < IDENTIFIER_MAX_RETRIES - 1) {
-        continue; // 并发发号撞 identifier，重试取新 seq
-      }
-      if (code === "P2002") {
-        return null; // 指纹 unique 冲突：并发同指纹，调用方降级计数
-      }
-      throw e;
-    }
+            autoFixRunId,
+          };
+        }),
+      { exhaustedMessage: "创建 BUG 失败：编号冲突，请重试" },
+    );
+    // 事务已提交：仅提交成功才外发通知（回滚路径到不了这里）
+    fireCreationWebhooks(created);
+    return created;
+  } catch (e: unknown) {
+    // 指纹 unique 冲突：并发同指纹，调用方降级计数（发号冲突已由
+    // withSequenceNumberRetry 消化，走到这里只剩指纹撞号）
+    if (isBugFingerprintConflict(e)) return null;
+    throw e;
   }
-  throw new Error("创建 BUG 失败：编号冲突，请重试");
 }
 
 /** 新建 BUG 事务返回值：含 webhook body 所需的 bug 摘要字段（§3.8） */
@@ -602,7 +605,9 @@ export type ParsedScreenshot =
   | { kind: "ok"; mimeType: string; bytes: Uint8Array<ArrayBuffer>; size: number }
   | { kind: "skip"; reason: "invalid" | "too_large" };
 
-/** 解析 extra.imageData（PNG dataURL → 字节）；缺失返回 null，非法/超限返回 skip */
+/** 解析 extra.imageData（PNG dataURL → 字节）；缺失返回 null，非法/超限返回 skip。
+ * 魔数复检（审计 🟡）：base64 前缀声明之外按字节校验 PNG 魔数，任意字节流
+ * 借 image/png 身份入库被拒（skip=invalid，事件本身不失败）。 */
 export function parseScreenshotImageData(
   extra: Record<string, unknown> | undefined,
 ): ParsedScreenshot | null {
@@ -614,6 +619,7 @@ export function parseScreenshotImageData(
   const bytes = Buffer.from(raw.slice(IMAGE_DATAURL_PREFIX.length), "base64");
   if (bytes.byteLength === 0) return { kind: "skip", reason: "invalid" };
   if (bytes.byteLength > MAX_SCREENSHOT_BYTES) return { kind: "skip", reason: "too_large" };
+  if (detectImageMime(bytes) !== "image/png") return { kind: "skip", reason: "invalid" };
   return {
     kind: "ok",
     mimeType: "image/png",

package/src/server/bug-report/repro-runner.ts

@@ -21,12 +21,16 @@
 // requireAuth + assertBugProjectMember 薄壳，组装/超时/校验/落库全部收在这里。
 // 预算（§11）：堆栈截断 8KB、事件样本仅最近 2 条、面包屑全局最近 20 条——
 // 防止长堆栈撑爆上下文。
-import type { Prisma } from "@allbluecn/database";
 import type { SchemaInput } from "@tanstack/ai";
 import { z } from "zod";
 import { getPrisma } from "@allbluecn/database/get-prisma";
 import { hasAiKey, runChatAsAgent } from "@/server/ai-gateway";
 import { fenceLlmData } from "@/server/ai-gateway/llm-fence";
+import { toJsonValue, truncateUtf8Bytes } from "@/server/lib/text-truncate";
+
+// 截断/JSON 收敛工具已抽到 server/lib/text-truncate（审计 🔵 单源）；
+// 再导出维持既有测试 import 路径稳定
+export { toJsonValue, truncateUtf8Bytes };
 
 // ── token 预算常量（§11）──
 export const REPRO_STACK_MAX_BYTES = 8 * 1024;
@@ -81,16 +85,6 @@ export interface ReproRunOutcome {
 
 // ── 输入组装 ──
 
-/** UTF-8 字节级截断（8KB 预算按字节算而非字符数；尾部分割多字节字符产生的
- * U+FFFD 替换符修剪掉） */
-export function truncateUtf8Bytes(value: string, maxBytes: number): string {
-  if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
-  return Buffer.from(value, "utf8")
-    .subarray(0, maxBytes)
-    .toString("utf8")
-    .replace(/\uFFFD+$/g, "");
-}
-
 /** Bug.description（TipTap JSON）→ markdown（照 bug-story-utils 兼容口径：
  * JSON 时取 markdown 字段；裸 HTML/markdown 历史数据按原文读） */
 function extractDescriptionMarkdown(desc: string | null): string {
@@ -270,10 +264,6 @@ function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
-function toJsonValue(value: unknown): Prisma.InputJsonValue {
-  return JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue;
-}
-
 /**
  * AI 复现执行链：hasAiKey 预检（未配置抛错，不产生孤儿 run）→ 建
  * BugReproRun(running) → runChatAsAgent（outputSchema 强约束 + 55s 超时）→

package/src/server/bug-report/webhook-out.ts

@@ -26,6 +26,7 @@ import { createHmac } from "node:crypto";
 import { getPrisma } from "@allbluecn/database/get-prisma";
 import { assertFetchableUrl } from "@/server/fetch-guard";
 import { BUG_WEBHOOK_EVENTS, type BugWebhookEvent } from "@/shared/bug/constants";
+import { decryptWebhookSecret, isEncryptedWebhookSecret, selfHealWebhookSecret } from "@/server/lib/webhook-secret";
 
 // 事件名规范（规格 §3.8）唯一定义在客户端安全的 @/shared/bug/constants
 // （设置页勾选列表与 serverFn 校验共用），此处 re-export 供 server 侧消费。
@@ -112,7 +113,18 @@ async function deliverToTarget(
     const targetUrl = assertFetchableUrl(target.url);
     // 秒级 Unix 时间戳（GitHub webhook 同款惯例），随 X-Allblue-Timestamp 头外发供接收方验签
     const timestamp = Math.floor(Date.now() / 1000).toString();
-    const signature = createHmac("sha256", target.secret)
+    // 密钥静态加密（审计 A4x-3）：存量明文行由 decrypt 原样返回兼容；
+    // 解密失败（密钥轮换/密文损坏）跳过该端点，避免用错误密钥签名造成接收方静默拒收
+    const secret = decryptWebhookSecret(target.secret);
+    if (!secret) {
+      console.warn("[webhook-out] 端点密钥解密失败，跳过投递", { webhookId: target.id });
+      return;
+    }
+    if (!isEncryptedWebhookSecret(target.secret)) {
+      // 存量明文自愈：投递一次即加密回写（失败不影响本次投递）
+      void selfHealWebhookSecret(target.id, target.secret);
+    }
+    const signature = createHmac("sha256", secret)
       .update(`${timestamp}.${body}`)
       .digest("hex");
     // redirect:error 防 302 跳私网（webhook 接收端正常不重定向）

package/src/server/bug-screenshot/screenshot-handler.ts

@@ -108,9 +108,13 @@ export async function handleBugScreenshot(request: Request): Promise<Response> {
     });
   } catch (error) {
     // requireAuth 抛 UnauthorizedError（message=UNAUTHORIZED）→ 401，其余 500
-    // （与 /api/blob/$id 同口径）
+    // 统一固定文案（审计修复：异常原文可能携带 Prisma 表名/查询细节，仅入日志）
     const message = error instanceof Error ? error.message : "读取失败";
-    const status = message === "UNAUTHORIZED" ? 401 : 500;
-    return new Response(message, { status });
+    if (message !== "UNAUTHORIZED") {
+      console.error("[bug-screenshot] 读取失败:", message);
+    }
+    return new Response(message === "UNAUTHORIZED" ? "Unauthorized" : "Internal error", {
+      status: message === "UNAUTHORIZED" ? 401 : 500,
+    });
   }
 }

package/src/server/builtin-project.ts

@@ -16,6 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { prisma } from "@allbluecn/database"
+import type { Prisma } from "@allbluecn/database"
 import {
   BUILTIN_INDEPENDENT_DISPLAY_ID,
   BUILTIN_INDEPENDENT_NAME,
@@ -101,33 +102,32 @@ export async function resolveStoryScopeProjectIds(
 }
 
 // 将一批需求迁移到用户的「独立需求」内置项目，重新分配 sequenceId/identifier；
-// identifier 唯一冲突（P2002）时整批重试（与 sequenceCounter 自增的并发竞争对应）
+// identifier 唯一冲突（P2002）时整批重试（与 sequenceCounter 自增的并发竞争对应）。
+// ⚠ 调用方契约：storyIds 必须来自服务端按授权范围派生的查询（deleteProjectFn /
+// deleteWorkspaceFn 先 requireOwner 后查库取 id），禁止直传客户端任意 id——
+// 本函数按 id 直更，无逐条属主谓词（加谓词会误伤 workspace 清理跨 owner 项目
+// 的合法迁移）。
+// tx 可选传入外部交互式事务客户端（审计 🟡 2026-10-25：deleteProjectFn 需要
+// 「迁移 + 删项目」原子化——传入 tx 时发号+搬迁直接在外层事务内执行，不再自建
+// 事务与重试，P2002 交由外层统一失败回滚）。
 export async function migrateStoriesToIndependentProject(
   userId: string,
-  storyIds: string[]
+  storyIds: string[],
+  tx?: Prisma.TransactionClient
 ): Promise<void> {
   if (storyIds.length === 0) return
   const independentId = await ensureBuiltinIndependentProject(userId)
 
+  if (tx) {
+    await allocateAndMoveStories(tx, independentId, storyIds)
+    return
+  }
+
   const MAX_RETRIES = 5
   for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
     try {
-      await prisma.$transaction(async (tx) => {
-        for (const id of storyIds) {
-          const counter = await tx.sequenceCounter.upsert({
-            where: { scope: independentId },
-            create: { scope: independentId, seq: 1 },
-            update: { seq: { increment: 1 } },
-          })
-          await tx.story.update({
-            where: { id },
-            data: {
-              projectId: independentId,
-              sequenceId: counter.seq,
-              identifier: `STORY-${counter.seq}`,
-            },
-          })
-        }
+      await prisma.$transaction(async (inner) => {
+        await allocateAndMoveStories(inner, independentId, storyIds)
       })
       break
     } catch (e: unknown) {
@@ -142,3 +142,28 @@ export async function migrateStoriesToIndependentProject(
     }
   }
 }
+
+// 发号 + 搬迁主体（自建事务与外部事务共用；批量单次 upsert 增量 N 后内存分配
+// 连续序号，避免逐条 upsert 的 N+1 事务往返）
+async function allocateAndMoveStories(
+  tx: Prisma.TransactionClient,
+  independentId: string,
+  storyIds: string[]
+): Promise<void> {
+  const counter = await tx.sequenceCounter.upsert({
+    where: { scope: independentId },
+    create: { scope: independentId, seq: storyIds.length },
+    update: { seq: { increment: storyIds.length } },
+  })
+  const baseSeq = counter.seq - storyIds.length + 1
+  for (const [i, id] of storyIds.entries()) {
+    await tx.story.update({
+      where: { id },
+      data: {
+        projectId: independentId,
+        sequenceId: baseSeq + i,
+        identifier: `STORY-${baseSeq + i}`,
+      },
+    })
+  }
+}

package/src/server/collab/reindex-endpoint.ts

@@ -39,12 +39,32 @@ import { indexDocumentById } from "@/server/knowledge/knowledge-index-utils";
 /** 签名请求头名（信封模块常量的再导出，调用方免再 import） */
 export const REINDEX_SIGNATURE_HEADER = INTERNAL_SIGNATURE_HEADER;
 
+/** body 上限（审计 🟡：验签前无界 request.text() 的内存放大面；docId 通知
+ * 载荷实际 <1KB，64KB 已远超合理余量） */
+export const MAX_REINDEX_BODY_BYTES = 64 * 1024;
+
 export async function handleCollabReindex(request: Request): Promise<Response> {
   const secret = process.env.COLLAB_SECRET;
   if (!secret) {
     return Response.json({ error: "internal channel unavailable" }, { status: 503 });
   }
+  // 未认证请求不先读 body：content-length 超限/非法直接 413/400（对比
+  // report-handler 双重检查口径；无 content-length 头（chunked）时落第二道
+  // 字节级兜底）
+  const rawLength = request.headers.get("content-length");
+  if (rawLength !== null) {
+    const n = Number(rawLength);
+    if (!Number.isFinite(n) || n < 0) {
+      return Response.json({ error: "invalid content-length" }, { status: 400 });
+    }
+    if (n > MAX_REINDEX_BODY_BYTES) {
+      return Response.json({ error: "payload too large" }, { status: 413 });
+    }
+  }
   const raw = await request.text();
+  if (Buffer.byteLength(raw) > MAX_REINDEX_BODY_BYTES) {
+    return Response.json({ error: "payload too large" }, { status: 413 });
+  }
   const verified = verifyInternalRequest({
     secret,
     domain: INTERNAL_DOMAIN_REINDEX,

package/src/server/collab/seed.ts

@@ -103,12 +103,24 @@ async function ensureServerDom(): Promise<void> {
   }
 }
 
+/** HTML 实体转义（审计 🟡）：text 兜底路径把用户文本包进 `<p>` 前先转义，
+ * 防含标签的文本以标记身份进入 TipTap 解析管线（是否成 XSS 取决于扩展
+ * schema 白名单，转义后不依赖下游过滤）。 */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
 /**
  * 解析 KnowledgeDocument.content（Json 列）为可种子化的 HTML。
  * 与 NotionDocEditor getInitialContent 读取口径同构：
  * - { html, markdown } 双轨（编辑器 onChange/updateDocumentFn 存储形态）→ html
- * - { text } → 包裹为单段落（同编辑器兜底）
- * - string → 包裹为单段落（历史数据兜底）
+ * - { text } → 转义后包裹为单段落（text 契约是纯文本，同编辑器兜底）
+ * - string → 转义后包裹为单段落（历史数据兜底）
  * 返回 null 表示「业务列无内容」（空对象 / 空串 / 编辑器空文档产物
  * `<p></p>`、`<p><br></p>`）——此时无需种子化，客户端直接建空 Y.Doc。
  */
@@ -119,10 +131,10 @@ export function extractKnowledgeDocHtml(content: unknown): string | null {
     if ("html" in record && typeof record.html === "string") {
       html = record.html;
     } else if ("text" in record && typeof record.text === "string") {
-      html = `<p>${record.text}</p>`;
+      html = `<p>${escapeHtml(record.text)}</p>`;
     }
   } else if (typeof content === "string") {
-    html = `<p>${content}</p>`;
+    html = `<p>${escapeHtml(content)}</p>`;
   }
   if (!html) return null;
   const trimmed = html.trim();
@@ -228,6 +240,10 @@ export function extractStoryDescriptionHtml(
         html = parsed.html;
       }
     } catch {
+      // 历史 bare-string 兜底按整串 HTML 交给 TipTap schema 解析（与客户端
+      // parseStoryDescription 镜像口径一致）：裸串可能是合法历史 HTML，转义
+      // 会破坏存量渲染；XSS 面由 schema parseRules 白名单兜底（script/事件
+      // 属性剥离），此处不做转义
       html = description;
     }
   }

package/src/server/collab/write-guard.ts

@@ -229,6 +229,11 @@ export async function withCollabGuard(opts: WithCollabGuardOptions): Promise<Col
   let attempt = 0;
   // ⑤ 内存排队重试（请求内同步）：失败即重试直至 TTL 耗尽——调用方在本
   // 请求内拿到最终裁决，绝不出现「已降级直写、后台又迟到应用」的互吞。
+  // ⚠ 已知取舍（2026-10 审计 ⚪）：TTL 判定在请求之后，最后一次挂满
+  // requestTimeoutMs 的请求可令实际降级延迟 ≈ ttlMs + requestTimeoutMs
+  // （3s + 2s）。预判「剩余预算 < requestTimeoutMs 即提前降级」会破坏既有
+  // 测试对「短 TTL 下至少两次尝试」的契约（ttlMs < requestTimeoutMs 的
+  // 场景首轮后即降级），且单请求最多多挂一个超时窗，维持现状。
   while (true) {
     attempt += 1;
     try {

package/src/server/csv.ts

@@ -42,10 +42,13 @@ const CSV_INJECTION_PREFIXES = new Set(["=", "+", "-", "@", "\t"]);
 /** CSV 单元格值（服务端行数据允许原始类型；日期等由调用方先转 ISO 字符串） */
 export type CsvCell = string | number | null | undefined;
 
-/** 单格编码：注入防护 → 含分隔符则包裹引号 */
+/** 单格编码：注入防护（仅字符串格——数值格不构成公式注入，负数/差值列
+ * 前置 ' 会破坏「DB 原值机器可读」承诺，审计 🟡 修正）→ 含分隔符则包裹引号 */
 function encodeCell(value: CsvCell): string {
-  let s = value === null || value === undefined ? "" : String(value);
-  if (s.length > 0 && CSV_INJECTION_PREFIXES.has(s[0]!)) {
+  if (value === null || value === undefined) return "";
+  const isStringCell = typeof value === "string";
+  let s = String(value);
+  if (isStringCell && s.length > 0 && CSV_INJECTION_PREFIXES.has(s[0]!)) {
     s = `'${s}`;
   }
   if (/[",\n\r]/.test(s)) {