@allbluecn/web-app 0.19.2 → 0.19.4

package/src/lib/deploy-region.ts

@@ -1,10 +1,15 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+// 本模块被 billing/harness/testcase 等客户端组件在渲染路径消费——浏览器 bundle
+// 无 process 全局，读 process.env 在客户端渲染/水合即抛 ReferenceError（同
+// edition-desktop.ts 的结论）。统一经 vite.shared.ts 的 define 读
+// import.meta.env（SSR 与客户端由 Vite 静态替换，输出一致，无 hydration 分叉）。
+
 export type DeployRegion = 'overseas' | 'china' | 'desktop'
 
 export function getDeployRegion(): DeployRegion {
-  if (process.env.DEPLOY_TARGET === 'desktop') return 'desktop'
-  const region = process.env.DEPLOY_REGION ?? 'overseas'
+  if (import.meta.env.VITE_DEPLOY_TARGET === 'desktop') return 'desktop'
+  const region = import.meta.env.VITE_DEPLOY_REGION ?? 'overseas'
   return region === 'china' ? 'china' : 'overseas'
 }
 
@@ -18,4 +23,8 @@ export function isChina(): boolean {
 
 export function isDesktop(): boolean {
   return getDeployRegion() === 'desktop'
-}
+}
+// 命名注记：本文件 isDesktop() 判定「构建目标=desktop」（构建期常量）；
+// desktop-detect.ts 的 isDesktop() 是 Tauri 运行时探测；edition-desktop.ts
+// 的 isDesktopEdition() 是同构建目标的另一封装——三者语义不同勿混用
+// （收敛为单一判定模块属跨文件重构，暂记待决策）。

package/src/lib/design-tree-utils.ts

@@ -44,6 +44,24 @@ export function buildTree(pages: DesignPage[]): TreeNode[] {
     }
   }
 
+  // 环检测（开发态告警）：成环的节点互为父子、谁都不进 roots，数据仍在
+  // 但从树中不可达（用户感知为数据丢失）——历史脏数据无从发现，console.warn 暴露
+  if (process.env.NODE_ENV !== "production") {
+    const reachable = new Set<string>();
+    const walk = (nodes: TreeNode[]) => {
+      for (const n of nodes) {
+        reachable.add(n.id);
+        walk(n.children);
+      }
+    };
+    walk(roots);
+    for (const p of pages) {
+      if (!reachable.has(p.id)) {
+        console.warn(`[design-tree] 节点 ${p.id}（${p.name}）不在树中：parentId 链疑似成环或悬空`);
+      }
+    }
+  }
+
   const sortNodes = (nodes: TreeNode[]) => nodes.sort((a, b) => a.order - b.order);
   sortNodes(roots);
   for (const node of map.values()) sortNodes(node.children);
@@ -73,6 +91,18 @@ export function canMove(node: TreeNode, targetParentId: string | null, allPages:
   if (targetParentId === node.id) return false;
   const targetPage = allPages.find(p => p.id === targetParentId);
   if (targetPage?.type === "folder") return false;
+  // 后代检测：targetParentId 位于 node 的子孙链上时，移动会成环（A.parent=B
+  // 且 B.parent=A），buildTree 后环上节点谁都不进 roots，整分支从树里静默消失
+  if (targetParentId !== null) {
+    const pageById = new Map(allPages.map(p => [p.id, p]));
+    let cursor: DesignPage | undefined = pageById.get(targetParentId);
+    const visited = new Set<string>();
+    while (cursor && !visited.has(cursor.id)) {
+      if (cursor.id === node.id) return false;
+      visited.add(cursor.id);
+      cursor = cursor.parentId ? pageById.get(cursor.parentId) : undefined;
+    }
+  }
   return true;
 }
 

package/src/lib/form/standard-schema-validator.ts

@@ -0,0 +1,44 @@
+// 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 type {
+  FormValidatorContext,
+  ParseFormIssuesFn,
+  StandardSchemaV1,
+} from "@tanstack/react-form";
+
+/**
+ * 把 Standard Schema（zod schema）适配为 TanStack Form v2 表单级 `run` 校验函数。
+ *
+ * 审计修复：多处 `validators: [{ run: schema as any }]` 用 as any 掩盖
+ * 「schema input 类型（含 .default() 的可选字段）≠ 表单值类型」的不匹配。
+ * 本适配器把 input 类型显式分离为 TInput，issues 经框架的 `parseIssues`
+ * 路由到 form/field 错误位，全程无 as any。
+ *
+ * 用法：`validators: [{ run: standardSchemaValidator(myZodSchema), triggers: ['change'] }]`
+ */
+export function standardSchemaValidator<TValues, TInput>(
+  schema: StandardSchemaV1<TInput, unknown>,
+): (
+  ctx: FormValidatorContext<TValues>,
+) => Promise<ReturnType<ParseFormIssuesFn<TValues>> | undefined> {
+  return async ({ value, parseIssues }) => {
+    const result = schema["~standard"].validate(value)
+    const resolved = result instanceof Promise ? await result : result
+    return resolved.issues ? parseIssues(resolved.issues) : undefined
+  }
+}

package/src/lib/fsap.ts

@@ -43,19 +43,27 @@ export async function listDirEntries(
   )
 }
 
-/** 按需读取文件内容为文本（@ 引用时流式进上下文） */
+/** 按需读取文件内容为文本（@ 引用时流式进上下文）。
+ *  路径不存在/句柄失效/空路径一律返回 null（签名契约 string | null，
+ *  NotFoundError 等异常不外泄——调用方按「读不到」分支处理） */
 export async function readFileText(
   dirHandle: FileSystemDirectoryHandle,
   relPath: string,
 ): Promise<string | null> {
   const parts = relPath.split("/").filter(Boolean)
-  let current: FileSystemHandle = dirHandle
-  for (let i = 0; i < parts.length - 1; i++) {
+  if (parts.length === 0) return null
+  try {
+    let current: FileSystemHandle = dirHandle
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (current.kind !== "directory") return null
+      current = await (current as FileSystemDirectoryHandle).getDirectoryHandle(parts[i])
+    }
     if (current.kind !== "directory") return null
-    current = await (current as FileSystemDirectoryHandle).getDirectoryHandle(parts[i])
+    const fileHandle = await (current as FileSystemDirectoryHandle).getFileHandle(parts[parts.length - 1])
+    const file = await fileHandle.getFile()
+    return await file.text()
+  } catch {
+    // NotFoundError（路径拼写错误/文件被删）等：契约化返回 null
+    return null
   }
-  if (current.kind !== "directory") return null
-  const fileHandle = await (current as FileSystemDirectoryHandle).getFileHandle(parts[parts.length - 1])
-  const file = await fileHandle.getFile()
-  return file.text()
 }

package/src/lib/github.ts

@@ -83,10 +83,14 @@ const LANGUAGE_COLORS: Record<string, string> = {
   MDX: "#fcb32c",
 }
 
+const GITHUB_SEGMENT = /^(?!\.{1,2}$)[A-Za-z0-9_.-]+$/;
+
 export function parseGithubUrl(url: string): { owner: string; repo: string } | null {
   const clean = url.replace("https://github.com/", "").split("/tree/")[0].replace(".git", "");
   const [owner, repo] = clean.split("/");
   if (!owner || !repo) return null;
+  // owner/repo 会拼进 API 路径，拒绝 `?` `#` `..` 等可改写请求路径的字符
+  if (!GITHUB_SEGMENT.test(owner) || !GITHUB_SEGMENT.test(repo)) return null;
   return { owner, repo };
 }
 
@@ -97,12 +101,31 @@ export function getLanguageColor(language: string): string {
   return LANGUAGE_COLORS[language] ?? "#8b8b8b"
 }
 
+const GITHUB_API_ORIGIN = "https://api.github.com";
+
+/** 直连优先，国内网络回落到公共代理。 */
+const GITHUB_API_ENDPOINTS = [GITHUB_API_ORIGIN, `https://ghproxy.com/${GITHUB_API_ORIGIN}`];
+
+const GITHUB_FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * 只对 api.github.com 直连携带 GITHUB_TOKEN。此前同一 headers 对象在回落到 ghproxy.com
+ * 时原样发出 Authorization，等于把 token 交给不受控的第三方代理（审计 2026-10-25）。
+ */
+function githubHeaders(endpoint: string): Record<string, string> {
+  const headers: Record<string, string> = { Accept: "application/vnd.github.v3+json" };
+  if (endpoint === GITHUB_API_ORIGIN && process.env.GITHUB_TOKEN) {
+    headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  }
+  return headers;
+}
+
 /**
  * Fetch extended metadata for a GitHub repository.
  *
  * - Uses the public GitHub REST API — no API key required.
- * - Optionally authenticates with `process.env.GITHUB_TOKEN`.
- * - Caches the result for 1 hour.
+ * - Optionally authenticates with `process.env.GITHUB_TOKEN` (direct endpoint only).
+ * - No caching here; callers decide their own caching policy.
  *
  * Returns `null` if the request fails or the repo doesn't exist.
  */
@@ -110,21 +133,12 @@ export async function fetchGitHubRepoData(
   owner: string,
   repo: string
 ): Promise<GitHubRepoData | null> {
-  const endpoints = [
-    "https://api.github.com",
-    "https://ghproxy.com/https://api.github.com",
-  ];
-
-  for (const endpoint of endpoints) {
+  for (const endpoint of GITHUB_API_ENDPOINTS) {
     try {
       const url = `${endpoint}/repos/${owner}/${repo}`;
       const response = await fetch(url, {
-        headers: {
-          Accept: "application/vnd.github.v3+json",
-          ...(process.env.GITHUB_TOKEN
-            ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` }
-            : {}),
-        },
+        headers: githubHeaders(endpoint),
+        signal: AbortSignal.timeout(GITHUB_FETCH_TIMEOUT_MS),
       });
 
       if (!response.ok) continue;
@@ -164,21 +178,12 @@ export async function fetchLatestRelease(
   owner: string,
   repo: string
 ): Promise<{ tag: string; publishedAt: string } | null> {
-  const endpoints = [
-    "https://api.github.com",
-    "https://ghproxy.com/https://api.github.com",
-  ];
-
-  for (const endpoint of endpoints) {
+  for (const endpoint of GITHUB_API_ENDPOINTS) {
     try {
       const url = `${endpoint}/repos/${owner}/${repo}/releases/latest`;
       const response = await fetch(url, {
-        headers: {
-          Accept: "application/vnd.github.v3+json",
-          ...(process.env.GITHUB_TOKEN
-            ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` }
-            : {}),
-        },
+        headers: githubHeaders(endpoint),
+        signal: AbortSignal.timeout(GITHUB_FETCH_TIMEOUT_MS),
       });
       if (!response.ok) continue;
       const data = await response.json();
@@ -193,36 +198,5 @@ export async function fetchLatestRelease(
 
   return null;
 }
-
-/**
- * Format a number for compact display.
- */
-export function formatCount(count: number): string {
-  if (count >= 1_000_000) {
-    const value = count / 1_000_000
-    return `${value % 1 === 0 ? value.toFixed(0) : value.toFixed(1)}m`
-  }
-  if (count >= 1_000) {
-    const value = count / 1_000
-    return `${value % 1 === 0 ? value.toFixed(0) : value.toFixed(1)}k`
-  }
-  return count.toLocaleString("en-US")
-}
-
-/**
- * Format a relative time from an ISO date string.
- */
-export function formatRelativeDate(iso: string): string {
-  const date = new Date(iso)
-  const now = new Date()
-  const diffMs = now.getTime() - date.getTime()
-  const diffDays = Math.floor(diffMs / 86_400_000)
-
-  if (diffDays === 0) return "today"
-  if (diffDays === 1) return "yesterday"
-  if (diffDays < 30) return `${diffDays}d ago`
-  const months = Math.floor(diffDays / 30)
-  if (months < 12) return `${months}mo ago`
-  const years = Math.floor(diffDays / 365)
-  return `${years}y ago`
-}
+// formatCount / formatRelativeDate 已删除：全仓零引用（含 Pro 镜像）的死导出，
+// 且其英文相对时间文案无法过 i18n 关卡（审计 🟡 条目的收敛处置）。

package/src/lib/hooks/use-story-panel-open.ts

@@ -17,7 +17,13 @@
 
 // 需求详情各子面板折叠状态持久化（localStorage，按 storyId 分桶）。
 // peek 面板与详情路由共享同一状态（同一 story 打开处即可见上次折叠态）。
-import { useEffect, useState, type Dispatch, type SetStateAction } from "react";
+//
+// ⚠ storyId 变化防御（审计 🟠）：TanStack Router 同一路由模式（$id）导航会
+// 复用组件实例，useState 惰性初始化只在首挂载读值——storyId A→B 时旧面板
+// 的 open/collapsed/filters 会以旧值写入 B 的桶（串号 + 持久化被覆盖）。
+// 三个 hook 均内置「scope 变化 → 重读新桶 + 首次写回跳过」守卫
+// （per-effect skipWriteRef，SSR localStorage 恢复约定同款，见 AGENTS）。
+import { useEffect, useRef, useState, type Dispatch, type SetStateAction } from "react";
 
 const storageKey = (storyId: string) => `allblue.story-panels.${storyId}`;
 
@@ -32,6 +38,19 @@ function readState(storyId: string): PanelState {
   }
 }
 
+/** 读取某 story 的整桶状态（含 groups/filters 命名空间） */
+function readBucket(storyId: string): {
+  groups?: Record<string, Record<string, boolean>>;
+  filters?: Record<string, Record<string, unknown>>;
+} & PanelState {
+  try {
+    const raw = window.localStorage.getItem(storageKey(storyId));
+    return raw ? (JSON.parse(raw) as ReturnType<typeof readBucket>) : {};
+  } catch {
+    return {};
+  }
+}
+
 export function useStoryPanelOpen(storyId: string, panelKey: string, defaultOpen = true) {
   const [open, setOpen] = useState(() => {
     try {
@@ -41,7 +60,28 @@ export function useStoryPanelOpen(storyId: string, panelKey: string, defaultOpen
     }
   });
 
+  // scope（storyId:panelKey）变化：重读新桶值 + 跳过紧接着的一次写回
+  //（旧 scope 的 open 值不得写入新 scope 的存储桶）
+  const scopeRef = useRef(`${storyId}:${panelKey}`);
+  const skipWriteRef = useRef(false);
   useEffect(() => {
+    const scope = `${storyId}:${panelKey}`;
+    if (scopeRef.current === scope) return;
+    scopeRef.current = scope;
+    try {
+      setOpen(readState(storyId)[panelKey] ?? defaultOpen);
+    } catch {
+      setOpen(defaultOpen);
+    }
+    skipWriteRef.current = true;
+    // defaultOpen 为调用方字面量，变化场景视为重置
+  }, [storyId, panelKey, defaultOpen]);
+
+  useEffect(() => {
+    if (skipWriteRef.current) {
+      skipWriteRef.current = false;
+      return;
+    }
     try {
       const state = readState(storyId);
       if (state[panelKey] === open) return;
@@ -55,19 +95,6 @@ export function useStoryPanelOpen(storyId: string, panelKey: string, defaultOpen
   return [open, setOpen] as const;
 }
 
-/** 读取某 story 的整桶状态（含 groups/filters 命名空间） */
-function readBucket(storyId: string): {
-  groups?: Record<string, Record<string, boolean>>;
-  filters?: Record<string, Record<string, unknown>>;
-} & PanelState {
-  try {
-    const raw = window.localStorage.getItem(storageKey(storyId));
-    return raw ? (JSON.parse(raw) as ReturnType<typeof readBucket>) : {};
-  } catch {
-    return {};
-  }
-}
-
 /**
  * 列表内分组标题行的折叠状态持久化（同桶 groups.{panelKey} 命名空间）。
  * 键为分组 key（含子分组复合键），维度切换后遗留键自然失效。
@@ -81,7 +108,25 @@ export function useStoryPanelGroupCollapsed(storyId: string, panelKey: string) {
     }
   });
 
+  const scopeRef = useRef(`${storyId}:${panelKey}`);
+  const skipWriteRef = useRef(false);
   useEffect(() => {
+    const scope = `${storyId}:${panelKey}`;
+    if (scopeRef.current === scope) return;
+    scopeRef.current = scope;
+    try {
+      setCollapsed(readBucket(storyId).groups?.[panelKey] ?? {});
+    } catch {
+      setCollapsed({});
+    }
+    skipWriteRef.current = true;
+  }, [storyId, panelKey]);
+
+  useEffect(() => {
+    if (skipWriteRef.current) {
+      skipWriteRef.current = false;
+      return;
+    }
     try {
       const bucket = readBucket(storyId);
       const groups = bucket.groups ?? {};
@@ -116,7 +161,27 @@ export function useStoryPanelFilters<T extends object>(
     }
   });
 
+  const scopeRef = useRef(`${storyId}:${panelKey}`);
+  const skipWriteRef = useRef(false);
   useEffect(() => {
+    const scope = `${storyId}:${panelKey}`;
+    if (scopeRef.current === scope) return;
+    scopeRef.current = scope;
+    try {
+      const stored = readBucket(storyId).filters?.[panelKey] as Partial<T> | undefined;
+      setFilters(stored ? { ...defaults, ...stored } : defaults);
+    } catch {
+      setFilters(defaults);
+    }
+    skipWriteRef.current = true;
+    // defaults 为调用方字面量对象，引用变化不触发重置（仅 scope 变化触发）
+  }, [storyId, panelKey]);
+
+  useEffect(() => {
+    if (skipWriteRef.current) {
+      skipWriteRef.current = false;
+      return;
+    }
     try {
       const bucket = readBucket(storyId);
       const stored = bucket.filters?.[panelKey];

package/src/lib/hotkeys/registry.ts

@@ -22,85 +22,94 @@ export const HOTKEY_REGISTRY: HotkeyDefinition[] = [
     id: "shortcuts-panel",
     keys: "Mod+/",
     scope: "global",
-    description: "打开快捷键面板",
+    descriptionKey: "common_hotkey_desc_shortcutsPanel",
     category: "导航",
   },
   {
     id: "toggle-sidebar",
     keys: "Mod+B",
     scope: "global",
-    description: "切换侧边栏",
+    descriptionKey: "common_hotkey_desc_toggleSidebar",
     category: "导航",
   },
   {
     id: "save",
     keys: "Mod+S",
     scope: "app",
-    description: "保存当前编辑内容",
+    descriptionKey: "common_hotkey_desc_save",
     category: "编辑",
   },
   {
     id: "close-panel",
     keys: "Escape",
     scope: "modal",
-    description: "关闭当前弹窗或面板",
+    descriptionKey: "common_hotkey_desc_closePanel",
     category: "导航",
   },
   {
     id: "copy-message",
     keys: "Mod+C",
     scope: "modal",
-    description: "复制消息内容",
+    descriptionKey: "common_hotkey_desc_copyMessage",
     category: "聊天",
   },
   {
     id: "chat-prev",
     keys: "ArrowUp",
     scope: "chat-history",
-    description: "切换到上一条对话",
+    descriptionKey: "common_hotkey_desc_chatPrev",
     category: "聊天",
   },
   {
     id: "chat-next",
     keys: "ArrowDown",
     scope: "chat-history",
-    description: "切换到下一条对话",
+    descriptionKey: "common_hotkey_desc_chatNext",
     category: "聊天",
   },
   {
     id: "command-palette",
     keys: "Mod+K",
     scope: "global",
-    description: "打开命令面板",
+    descriptionKey: "common_hotkey_desc_commandPalette",
     category: "导航",
   },
   {
     id: "toggle-theme",
     keys: "Mod+Shift+L",
     scope: "global",
-    description: "切换明暗主题",
+    descriptionKey: "common_hotkey_desc_toggleTheme",
     category: "视图",
   },
-  { id: "goto-dashboard", keys: "G D", scope: "global", description: "前往工作台", category: "导航" },
-  { id: "goto-chat", keys: "G C", scope: "global", description: "前往对话", category: "导航" },
-  { id: "goto-agents", keys: "G A", scope: "global", description: "前往智能体", category: "导航" },
-  { id: "goto-inspiration", keys: "G I", scope: "global", description: "前往灵感", category: "导航" },
-  { id: "goto-stories", keys: "G S", scope: "global", description: "前往需求", category: "导航" },
-  { id: "goto-prd", keys: "G P", scope: "global", description: "前往 PRD", category: "导航" },
-  { id: "goto-design", keys: "G E", scope: "global", description: "前往设计", category: "导航" },
-  { id: "goto-test-cases", keys: "G T", scope: "global", description: "前往测试用例", category: "导航" },
-  { id: "goto-bugs", keys: "G B", scope: "global", description: "前往缺陷", category: "导航" },
-  { id: "goto-knowledge", keys: "G K", scope: "global", description: "前往知识库", category: "导航" },
-  { id: "goto-anyhub", keys: "G H", scope: "global", description: "前往应用中心", category: "导航" },
-  { id: "goto-workspaces", keys: "G W", scope: "global", description: "前往工作空间", category: "导航" },
-  { id: "goto-settings", keys: "G M", scope: "global", description: "前往设置", category: "导航" },
-  { id: "create-prd-hk", keys: "N P", scope: "global", description: "新建 PRD", category: "操作" },
-  { id: "create-conversation-hk", keys: "N C", scope: "global", description: "新建对话", category: "操作" },
-  { id: "create-story-hk", keys: "N S", scope: "global", description: "新建需求", category: "操作" },
+  { id: "goto-dashboard", keys: "G D", scope: "global", descriptionKey: "common_hotkey_desc_gotoDashboard", category: "导航" },
+  { id: "goto-chat", keys: "G C", scope: "global", descriptionKey: "common_hotkey_desc_gotoChat", category: "导航" },
+  { id: "goto-agents", keys: "G A", scope: "global", descriptionKey: "common_hotkey_desc_gotoAgents", category: "导航" },
+  { id: "goto-inspiration", keys: "G I", scope: "global", descriptionKey: "common_hotkey_desc_gotoInspiration", category: "导航" },
+  { id: "goto-stories", keys: "G S", scope: "global", descriptionKey: "common_hotkey_desc_gotoStories", category: "导航" },
+  { id: "goto-prd", keys: "G P", scope: "global", descriptionKey: "common_hotkey_desc_gotoPrd", category: "导航" },
+  { id: "goto-design", keys: "G E", scope: "global", descriptionKey: "common_hotkey_desc_gotoDesign", category: "导航" },
+  { id: "goto-test-cases", keys: "G T", scope: "global", descriptionKey: "common_hotkey_desc_gotoTestCases", category: "导航" },
+  { id: "goto-bugs", keys: "G B", scope: "global", descriptionKey: "common_hotkey_desc_gotoBugs", category: "导航" },
+  { id: "goto-knowledge", keys: "G K", scope: "global", descriptionKey: "common_hotkey_desc_gotoKnowledge", category: "导航" },
+  { id: "goto-anyhub", keys: "G H", scope: "global", descriptionKey: "common_hotkey_desc_gotoAnyhub", category: "导航" },
+  { id: "goto-workspaces", keys: "G W", scope: "global", descriptionKey: "common_hotkey_desc_gotoWorkspaces", category: "导航" },
+  { id: "goto-settings", keys: "G M", scope: "global", descriptionKey: "common_hotkey_desc_gotoSettings", category: "导航" },
+  { id: "create-prd-hk", keys: "N P", scope: "global", descriptionKey: "common_hotkey_desc_createPrdHk", category: "操作" },
+  { id: "create-conversation-hk", keys: "N C", scope: "global", descriptionKey: "common_hotkey_desc_createConversationHk", category: "操作" },
+  { id: "create-story-hk", keys: "N S", scope: "global", descriptionKey: "common_hotkey_desc_createStoryHk", category: "操作" },
 ] as const
 
 export function getHotkeysByCategory(category: HotkeyCategory): HotkeyDefinition[] {
   return HOTKEY_REGISTRY.filter((h) => h.category === category)
 }
 
-export const CATEGORY_ORDER: HotkeyCategory[] = ["导航", "视图", "编辑", "需求", "聊天", "操作"]
+export const CATEGORY_ORDER: HotkeyCategory[] = ["导航", "视图", "编辑", "聊天", "操作"]
+
+/** 分类 → i18n key（面板分组标题渲染经 t() 解析） */
+export const HOTKEY_CATEGORY_LABEL_KEYS: Record<HotkeyCategory, string> = {
+  导航: "common_hotkey_cat_navigation",
+  视图: "common_hotkey_cat_view",
+  编辑: "common_hotkey_cat_edit",
+  聊天: "common_hotkey_cat_chat",
+  操作: "common_hotkey_cat_action",
+}

package/src/lib/hotkeys/types.ts

@@ -17,13 +17,15 @@
 
 export type HotkeyScope = "global" | "app" | "modal" | "chat-history"
 
-export type HotkeyCategory = "导航" | "编辑" | "视图" | "需求" | "聊天" | "操作"
+// 「需求」分类在注册表中无条目（审计 🟢），已移除
+export type HotkeyCategory = "导航" | "编辑" | "视图" | "聊天" | "操作"
 
 export interface HotkeyDefinition {
   id: string
   keys: string
   /** @deprecated API 不支持 scope，保留字段供未来扩展 */
   scope: HotkeyScope
-  description: string
+  /** i18n message key（flat JSON），渲染层经 t() 解析——描述直接展示给用户 */
+  descriptionKey: string
   category: HotkeyCategory
 }

package/src/{server/serverFns/iteration/__tests__/burndown-core.test.ts → lib/iteration/__tests__/burndown.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { computeBurndown } from "../burndown-core";
+import { computeBurndown } from "../burndown";
 
 // 输入构造器：迭代 09-01~09-05（5 天），时区 Asia/Shanghai
 const base = {

package/src/{server/serverFns/iteration/burndown-core.ts → lib/iteration/burndown.ts}

@@ -17,6 +17,11 @@
 
 import { formatInTimeZone } from "date-fns-tz";
 
+// 燃尽回放纯函数（客户端安全：零 prisma，date-fns-tz 同构；audit 2026-10-25 🟡
+// 自 serverFns/iteration/burndown-core.ts 迁出，满足 serverFn 目录纯净性且
+// components/iteration/burndown-chart.tsx 的类型导入不再指向 serverFns 树）。
+// 日期序列以「日期字符串 + UTC 零点平移」步进（addDay），不涉墙钟，DST 切换日不跳日/重复。
+
 export interface BurndownStory { id: string; addedAt: string }
 export interface StateEvent { storyId: string; at: string; to: string }
 export interface BurndownPoint { date: string; scope: number; pending: number; ideal: number }

package/src/lib/knowledge/share-result-message.ts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+import { m } from "@/paraglide/messages.js";
+
+/** 与 server/knowledge/public/share-merge.ts 的 ShareResult.action 同构（客户端不跨边界引服务器模块） */
+export type ShareResultAction = "created" | "appended" | "already";
+
+/**
+ * 公共库分享结果 → 用户可见文案（客户端渲染）。
+ * 服务端只回机器可读 action（审计 A2x-4/A2x-5 待决策：原先服务端持有中文文案，
+ * 英文界面同样显示中文）。bookmarks/dictionary/compliance/legal 四域共用。
+ */
+export function shareResultMessage(action: ShareResultAction): string {
+  switch (action) {
+    case "created":
+      return m.knowledge_shareResult_created();
+    case "appended":
+      return m.knowledge_shareResult_appended();
+    case "already":
+      return m.knowledge_shareResult_already();
+    default:
+      return m.knowledge_shareResult_already();
+  }
+}

package/src/lib/layout.shared.tsx

@@ -27,14 +27,26 @@ export const translations = fumadocsI18n
 export function baseOptions(lang: DocsLang): BaseLayoutProps {
   return {
     nav: {
-      title: lang === 'en' ? 'AllBlue Docs' : 'AllBlue 使用文档',
+      title: docsText(lang).siteTitle,
       url: `/${lang}/docs`,
     },
     links: [
       {
-        text: lang === 'en' ? 'Back to App' : '返回应用',
+        text: docsText(lang).backToApp,
         url: '/dashboard',
       },
     ],
   }
 }
+
+/**
+ * docs 域文案单源（审计 A5x-1：route.lazy 与 baseOptions 各写一份同文案三元）。
+ * 注意：docs 语言由 URL `$lang` 决定，与 paraglide 全局 locale（cookie）解耦，
+ * 故走 lang 参数化而非 m.xxx()，避免 /en/docs 在 cookie lng=zh 时渲染中文。
+ */
+export function docsText(lang: DocsLang): { siteTitle: string; backToApp: string } {
+  return {
+    siteTitle: lang === 'en' ? 'AllBlue Docs' : 'AllBlue 使用文档',
+    backToApp: lang === 'en' ? 'Back to App' : '返回应用',
+  }
+}