@allbluecn/shared 0.2.0

package/src/i18n/locales/zh/tags.json

@@ -0,0 +1,42 @@
+{
+  "title": "标签",
+  "description": "标签管理正在开发中，敬请期待",
+  "detail": {
+    "title": "标签详情",
+    "description": "标签详情页正在开发中"
+  },
+  "settings": {
+    "title": "标签设置",
+    "description": "管理你的标签：增删改色、拖拽排序"
+  },
+  "emptyTitle": "暂无标签",
+  "emptyDesc": "创建你的第一个标签来组织 PRD",
+  "createTag": "新建标签",
+  "editTag": "编辑标签",
+  "nameLabel": "名称",
+  "colorLabel": "颜色",
+  "nameRequired": "请输入名称",
+  "nameConflict": "该名称已存在",
+  "saveFailed": "保存失败",
+  "saving": "保存中...",
+  "save": "保存",
+  "cancel": "取消",
+  "delete": "删除",
+  "deleted": "已删除",
+  "deleteFailed": "删除失败",
+  "updated": "已更新",
+  "created": "已创建",
+  "sortFailed": "排序失败",
+  "confirmDeleteTitle": "删除标签「{{name}}」？",
+  "confirmDeleteDesc": "已关联的 PRD 仍会保留此标签，恢复后自动重新可见。",
+  "selector": {
+    "placeholder": "选择标签",
+    "searchPlaceholder": "搜索或创建...",
+    "createTag": "创建「{{name}}」"
+  },
+  "colorPicker": {
+    "selectColor": "选择颜色 {{color}}"
+  },
+  "edit": "编辑",
+  "removeTag": "移除 {{name}}"
+}

package/src/i18n/locales/zh/workspace.json

@@ -0,0 +1,90 @@
+{
+  "title": "工作台",
+  "list": {
+    "title": "工作空间",
+    "subtitle": "管理你的项目、团队协作与需求",
+    "create": "新建工作空间",
+    "emptyTitle": "暂无工作空间",
+    "emptyDescription": "创建第一个工作空间，开始团队协作",
+    "noDescription": "暂无介绍",
+    "projects": "项目",
+    "members": "成员"
+  },
+  "createWorkspace": {
+    "title": "新建工作空间",
+    "description": "创建一个工作空间，管理项目、需求和团队成员",
+    "nameLabel": "工作空间名称 *",
+    "namePlaceholder": "输入工作空间名称",
+    "nameRequired": "请输入工作空间名称",
+    "descriptionLabel": "介绍",
+    "descriptionPlaceholder": "简短介绍（可选）",
+    "cancel": "取消",
+    "creating": "创建中...",
+    "create": "创建",
+    "createFailed": "创建失败",
+    "upgradeTitle": "已达工作区上限",
+    "upgradeDescription": "Free 账号最多创建 1 个工作区。升级 Pro 后不限数量，并可解锁全部高级功能。",
+    "upgradeAction": "升级 Pro"
+  },
+  "detail": {
+    "noDescription": "暂无介绍",
+    "projects": "项目",
+    "members": "成员",
+    "createProject": "新建项目",
+    "emptyProjectsTitle": "暂无项目",
+    "emptyProjectsDescription": "在此工作空间创建第一个项目"
+  },
+  "settings": {
+    "back": "返回工作空间",
+    "title": "工作空间设置",
+    "basicInfo": "基本信息",
+    "icon": "工作空间图标",
+    "nameLabel": "工作空间名称 *",
+    "nameRequired": "请输入工作空间名称",
+    "descriptionLabel": "介绍",
+    "descriptionPlaceholder": "简短介绍工作空间目标与范围",
+    "saveChanges": "保存修改",
+    "updateSuccess": "工作空间已更新",
+    "saveFailed": "保存失败",
+    "members": "成员管理",
+    "inviteEmailPlaceholder": "输入成员邮箱",
+    "inviteEmailRequired": "请输入邮箱",
+    "inviteSuccess": "邀请已发送",
+    "inviteFailed": "邀请失败",
+    "inviteLoading": "邀请中...",
+    "invite": "邀请",
+    "seatsExceeded": "Pro 计划最多 {{max}} 位成员（当前 {{current}}/{{max}}）。请联系工作空间所有者升级 Enterprise。",
+    "memberRemoved": "成员已移除",
+    "removeFailed": "移除失败",
+    "roleUpdated": "角色已更新",
+    "operationFailed": "操作失败",
+    "workspaceDeleted": "工作空间已删除",
+    "deleteFailed": "删除失败",
+    "roles": {
+      "owner": "所有者",
+      "admin": "管理员",
+      "member": "成员",
+      "viewer": "访客"
+    },
+    "unknownUser": "未知用户",
+    "self": "（你）",
+    "pending": "待接受",
+    "dangerZone": "危险操作",
+    "deleteDescription": "删除工作空间将永久移除工作空间及其所有成员关系，此操作不可恢复。",
+    "hasProjects": "此工作空间还有 {{count}} 个项目，请先选择处理方式",
+    "deleteClear": "清空项目并删除工作空间",
+    "deleteTransfer": "转移项目后删除工作空间",
+    "deleteWorkspace": "删除工作空间",
+    "confirmDelete": "确认删除",
+    "confirmDeleteDescription": "此操作将永久删除「{{name}}」及其所有关联数据，无法恢复。",
+    "projectHandling": "处理项目方式",
+    "clearProjects": "清空项目（不可恢复）",
+    "clearProjectsDesc": "工作空间下所有项目将被永久删除。",
+    "transferProjects": "转移到其他工作空间",
+    "transferProjectsDesc": "选择目标工作空间，保留项目数据。",
+    "confirmRemoveMember": "确认移除成员",
+    "confirmRemoveMemberDesc": "确定要移除该成员吗？该成员将立即失去工作空间访问权限。",
+    "cancel": "取消",
+    "confirmRemove": "确认移除"
+  }
+}

package/src/i18n/server.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import i18next from 'i18next'
+import { initReactI18next } from 'react-i18next'
+import { resources, fallbackLng, defaultNs, type AppLocale } from './config'
+
+export function createServerI18n(locale: AppLocale) {
+  const i18n = i18next.createInstance()
+  i18n.use(initReactI18next)
+  i18n.init({
+    lng: locale,
+    fallbackLng,
+    defaultNS: defaultNs,
+    resources,
+    interpolation: { escapeValue: false },
+    react: { useSuspense: false },
+  })
+  return i18n
+}

package/src/i18n/types.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import type { i18n as I18nInstance } from 'i18next'
+import type { AppLocale, NamespaceKey } from './config'
+
+export type { AppLocale, NamespaceKey, I18nInstance }

package/src/index.ts

@@ -0,0 +1,90 @@
+// 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/>.
+
+export { moduleRegistry } from "./modules/registry"
+export { registerDefaultModules } from "./modules/register-defaults"
+
+// 全站虚拟化/分页门槛常量（web / admin / desktop 统一）
+export * from "./constants/perf"
+
+// AI 服务商元数据（类型、常量、种子数据）
+export * from "./modules/ai-providers"
+
+// 第三方依赖版本管理（类型、常量、种子数据）
+export * from "./modules/dependencies"
+
+export {
+  resolveIpLocation,
+  getClientIp,
+} from "./infrastructure/ip-location"
+export {
+  parseUserAgent,
+  formatParsedUA,
+  type ParsedUA,
+} from "./infrastructure/ua-parser"
+
+export type {
+  AllBlueModule,
+  EntityDef,
+  AICommandDef,
+  AICommandContext,
+  AICommandResult,
+  AICommandHandler,
+  ReferenceDisplayFn,
+} from "./interfaces/module"
+
+export type {
+  Reference,
+  ResolvedRef,
+  RefDisplay,
+  SearchResult,
+} from "./interfaces/references"
+
+export type {
+  AiAdapter,
+  CLIAgentInfo,
+} from "./interfaces/ai"
+
+export type {
+  EntityUpdateEvent,
+  RealtimeTransport,
+} from "./interfaces/transport"
+
+export {
+  FeatureRegistry,
+  FEATURE_KEYS,
+  OSS_BASE_FEATURES,
+  isOssFeature,
+} from "./modules/billing/feature-registry"
+export type { FeatureMeta, FeatureKey } from "./modules/billing/feature-registry"
+
+export { PlanFeaturesSchema } from "./modules/billing/plan-features-schema"
+export type { PlanFeatures } from "./modules/billing/plan-features-schema"
+
+export {
+  RESOURCE_KEYS,
+  ResourceRegistry,
+  isResourceDefined,
+} from "./modules/billing/resource-registry"
+export type {
+  ResourceKey,
+  ResourceMeta,
+  ResourceSnapshot,
+  ResourceSnapshots,
+} from "./modules/billing/resource-registry"
+
+export type { AvatarPart, AvatarConfig, ShapeType } from "./interfaces/avatar"

package/src/infrastructure/ai/adapter.ts

@@ -0,0 +1,59 @@
+// 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 { AICommandContext } from "../../interfaces/module"
+import type { CLIAgentInfo } from "../../interfaces/ai"
+
+let activeAgentId: string | null = null
+
+export function getActiveAgent(): string | null {
+  return activeAgentId
+}
+
+export function switchAgent(agentId: string): void {
+  activeAgentId = agentId
+}
+
+export async function executeViaAgent(
+  agent: CLIAgentInfo,
+  prompt: string,
+  _ctx: AICommandContext
+): Promise<string> {
+  if (agent.id === "openai-api") {
+    const response = await fetch(`${process.env.AI_BASE_URL || "https://api.openai.com/v1"}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
+      },
+      body: JSON.stringify({
+        model: process.env.AI_MODEL || "gpt-4o-mini",
+        messages: [{ role: "user", content: prompt }],
+        temperature: 0.7,
+      }),
+    })
+    const data = await response.json() as { choices: { message: { content: string } }[] }
+    return data.choices[0]?.message?.content || ""
+  }
+
+  const { execSync } = await import("child_process")
+  const result = execSync(`${agent.binary} -p "${prompt.replace(/"/g, '\\"')}"`, {
+    timeout: 60000,
+    encoding: "utf-8",
+  })
+  return result.trim()
+}

package/src/infrastructure/ai/cli-detector.ts

@@ -0,0 +1,64 @@
+// 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 { CLIAgentInfo } from "../../interfaces/ai"
+
+const KNOWN_AGENTS: { id: string; name: string; binary: string }[] = [
+  { id: "claude-code",    name: "Claude Code",        binary: "claude" },
+  { id: "claude-cli",     name: "Claude CLI",         binary: "claude" },
+  { id: "copilot-cli",    name: "GitHub Copilot CLI", binary: "github-copilot-cli" },
+  { id: "ollama",         name: "Ollama",             binary: "ollama" },
+  { id: "llama-cpp",      name: "llama.cpp",          binary: "llama-cli" },
+  { id: "open-interpreter", name: "Open Interpreter", binary: "interpreter" },
+  { id: "aider",          name: "Aider",              binary: "aider" },
+  { id: "continue",       name: "Continue",           binary: "continue" },
+  { id: "codex-cli",      name: "Codex CLI",          binary: "codex" },
+  { id: "swe-agent",      name: "SWE-agent",          binary: "sweagent" },
+  { id: "openhands",      name: "OpenHands",          binary: "openhands" },
+  { id: "taskmaster",     name: "TaskMaster",         binary: "taskmaster" },
+  { id: "gpt-engineer",   name: "GPT Engineer",       binary: "gptengineer" },
+  { id: "mentat",         name: "Mentat",             binary: "mentat" },
+  { id: "sweep",          name: "Sweep",              binary: "sweep" },
+  { id: "mcp-cli",        name: "MCP CLI",            binary: "mcp" },
+]
+
+export async function detectAgents(): Promise<CLIAgentInfo[]> {
+  const { execSync } = await import("child_process")
+  return KNOWN_AGENTS.map(({ id, name, binary }) => {
+    try {
+      const version = execSync(`${binary} --version 2>/dev/null || ${binary} version 2>/dev/null`, {
+        timeout: 3000,
+        encoding: "utf-8",
+      }).trim().slice(0, 50)
+      return { id, name, binary, version, available: true }
+    } catch {
+      return { id, name, binary, version: "", available: false }
+    }
+  })
+}
+
+export function getApiAgent(): CLIAgentInfo | undefined {
+  const key = process.env.OPENAI_API_KEY
+  if (!key || key === "sk-your-api-key-here") return undefined
+  return {
+    id: "openai-api",
+    name: `OpenAI (${process.env.AI_MODEL || "gpt-4o-mini"})`,
+    binary: "api",
+    version: "v1",
+    available: true,
+  }
+}

package/src/infrastructure/ip-location.ts

@@ -0,0 +1,76 @@
+// 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/>.
+
+/**
+ * IP 地理位置查询工具（服务端专用）
+ *
+ * - 开发环境 / 内网 IP：返回「本地」
+ * - 生产环境：使用 ip-api.com 免费查询（中文，每分钟 45 请求限制）
+ *   失败时返回「未知」，不阻塞登录流程
+ */
+
+const PRIVATE_IP_PATTERNS =
+  /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|::1$|fc00:|fd00:|fe80:|169\.254\.|localhost)/i
+
+export async function resolveIpLocation(
+  ip: string | null | undefined,
+): Promise<string> {
+  if (!ip) return "Unknown"
+
+  // 开发环境 / 内网 IP
+  if (PRIVATE_IP_PATTERNS.test(ip)) return "Local"
+
+  // 生产环境：ip-api.com 免费查询
+  try {
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 3000)
+    const res = await fetch(
+      `http://ip-api.com/json/${encodeURIComponent(ip)}?fields=status,country,regionName,city&lang=zh-CN`,
+      { signal: controller.signal },
+    )
+    clearTimeout(timeout)
+    if (!res.ok) return "Unknown"
+    const data = (await res.json()) as {
+      status: string
+      country?: string
+      regionName?: string
+      city?: string
+    }
+    if (data.status !== "success") return "Unknown"
+    const parts = [data.city, data.regionName, data.country].filter(Boolean)
+    return parts.length > 0 ? parts.join(", ") : "Unknown"
+  } catch {
+    return "Unknown"
+  }
+}
+
+/**
+ * 从 Request 中提取客户端真实 IP
+ * 优先级：X-Forwarded-For > X-Real-IP > CF-Connecting-IP
+ */
+export function getClientIp(request: Request): string | null {
+  const xff = request.headers.get("x-forwarded-for")
+  if (xff) {
+    const first = xff.split(",")[0]?.trim()
+    if (first) return first
+  }
+  const xri = request.headers.get("x-real-ip")
+  if (xri) return xri.trim()
+  const cfip = request.headers.get("cf-connecting-ip")
+  if (cfip) return cfip.trim()
+  return null
+}

package/src/infrastructure/references/engine.ts

@@ -0,0 +1,104 @@
+// 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 { getPrismaSeam } from "../../server-seam"
+import type { Reference, ResolvedRef, RefDisplay, SearchResult } from "../../interfaces/references"
+import { moduleRegistry } from "../../modules/registry"
+
+async function resolveDisplay(
+  targetModule: string,
+  targetEntityId: string,
+  entityType?: string
+): Promise<RefDisplay> {
+  const mod = moduleRegistry.getModule(targetModule)
+  if (!mod) return { title: `[${targetModule}:${targetEntityId}]` }
+
+  const entity = entityType
+    ? mod.entities.find(e => e.type === entityType)
+    : mod.entities[0]
+  if (!entity) return { title: `[${targetModule}:${targetEntityId}]` }
+
+  try {
+    const fields = [...entity.displayFields, "id"].join(", ")
+    const rows = await getPrismaSeam().$queryRawUnsafe<Record<string, unknown>>(
+      `SELECT ${fields} FROM \`${entity.table}\` WHERE id = ?`,
+      targetEntityId
+    )
+    if (!rows.length) return { title: `Deleted ${entity.type}`, status: "deleted" }
+    return mod.referenceDisplay(entity.type, rows[0])
+  } catch {
+    return { title: `[${targetEntityId}]` }
+  }
+}
+
+export async function createReference(ref: Omit<Reference, "id">): Promise<Reference> {
+  const seam = getPrismaSeam()
+  return seam.reference.create({ data: ref }) as unknown as Reference
+}
+
+export async function resolveReferences(
+  sourceModule: string,
+  sourceEntityId: string
+): Promise<ResolvedRef[]> {
+  const seam = getPrismaSeam()
+  const refs = await seam.reference.findMany({
+    where: { sourceModule, sourceEntityId },
+  }) as unknown as Reference[]
+
+  return Promise.all(
+    refs.map(async (ref) => {
+      const display = await resolveDisplay(ref.targetModule, ref.targetEntityId)
+      return { ...ref, display }
+    })
+  )
+}
+
+export async function searchReferences(
+  query: string,
+  types?: string[]
+): Promise<SearchResult[]> {
+  const searchConfigs = moduleRegistry.getSearchFields()
+  const filtered = types
+    ? searchConfigs.filter(c => types.includes(c.module) || types.includes(c.type))
+    : searchConfigs
+
+  const results: SearchResult[] = []
+  for (const config of filtered) {
+    const mod = moduleRegistry.getModule(config.module)
+    if (!mod) continue
+    const searchField = config.fields[0]
+    const seam = getPrismaSeam()
+    try {
+      const rows = await seam.$queryRawUnsafe<Record<string, unknown>>(
+        `SELECT id, ${config.fields.join(", ")} FROM \`${mod.entities[0].table}\` WHERE \`${searchField}\` LIKE ? LIMIT 20`,
+        `%${query}%`
+      )
+      for (const row of rows) {
+        const display = mod.referenceDisplay(config.type, row)
+        results.push({
+          id: row.id as string,
+          module: config.module,
+          type: config.type,
+          title: display.title,
+          status: display.status,
+          url: display.url,
+        })
+      }
+    } catch { /* skip tables that don't exist yet */ }
+  }
+  return results
+}

package/src/infrastructure/ua-parser.ts

@@ -0,0 +1,107 @@
+// 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/>.
+
+/**
+ * User-Agent 解析工具（轻量无依赖实现）
+ * 从 UA 字符串提取浏览器、操作系统、设备类型
+ */
+
+export interface ParsedUA {
+  /** 浏览器名称 + 主版本号，如 "Chrome 120"、"Edge 119" */
+  browser: string
+  /** 操作系统 + 主版本号，如 "Windows 10/11"、"macOS 14"、"iOS 17" */
+  os: string
+  /** 设备类型：桌面 / iPhone / iPad / Android 手机 / Android 平板 */
+  device: string
+}
+
+export function parseUserAgent(ua: string | null | undefined): ParsedUA {
+  if (!ua) {
+    return { browser: "Unknown", os: "Unknown", device: "Unknown" }
+  }
+
+  // ===== 浏览器解析（注意优先级：Edge/Opera 等基于 Chromium 的 UA 也含 Chrome）=====
+  let browser = "Unknown"
+  if (ua.includes("Edg/")) {
+    const m = ua.match(/Edg\/(\d+)/)
+    browser = `Edge${m ? " " + m[1] : ""}`
+  } else if (ua.includes("OPR/") || ua.includes("Opera")) {
+    const m = ua.match(/(?:OPR|Opera)\/(\d+)/)
+    browser = `Opera${m ? " " + m[1] : ""}`
+  } else if (ua.includes("Firefox/")) {
+    const m = ua.match(/Firefox\/(\d+)/)
+    browser = `Firefox${m ? " " + m[1] : ""}`
+  } else if (ua.includes("Chrome/")) {
+    // Chrome / Chromium / Brave / Vivaldi 等，统一显示为 Chrome
+    const m = ua.match(/Chrome\/(\d+)/)
+    browser = `Chrome${m ? " " + m[1] : ""}`
+  } else if (ua.includes("Safari/") && !ua.includes("Chrome")) {
+    const m = ua.match(/Version\/(\d+)/)
+    browser = `Safari${m ? " " + m[1] : ""}`
+  }
+
+  // ===== 操作系统解析 =====
+  let os = "Unknown"
+  if (ua.includes("Windows NT 10")) os = "Windows 10/11"
+  else if (ua.includes("Windows NT 6.3")) os = "Windows 8.1"
+  else if (ua.includes("Windows NT 6.2")) os = "Windows 8"
+  else if (ua.includes("Windows NT 6.1")) os = "Windows 7"
+  else if (ua.includes("Windows")) os = "Windows"
+  else if (ua.includes("Mac OS X") || ua.includes("Macintosh")) {
+    // 苹果从 macOS 11 Big Sur 起冻结 UA 为 10_15_7（包括最新的 macOS 26），
+    // UA 无法区分真实版本，统一显示 "macOS"；仅 10_14 及以下是真实旧版本
+    const frozen = /Mac OS X 10_15/.test(ua)
+    if (frozen) {
+      os = "macOS"
+    } else {
+      const m = ua.match(/Mac OS X (\d+)(?:[_.](\d+))?/)
+      if (m) {
+        const major = parseInt(m[1], 10)
+        os = major >= 11 ? `macOS ${major}` : `Mac OS X ${m[1]}.${m[2] ?? "0"}`
+      } else {
+        os = "macOS"
+      }
+    }
+  } else if (ua.includes("Android")) {
+    const m = ua.match(/Android ([\d.]+)/)
+    os = `Android${m ? " " + m[1] : ""}`
+  } else if (/iPhone|iPad|iPod/.test(ua)) {
+    const m = ua.match(/OS (\d+)[_ ](?:\d+)?/)
+    os = `iOS${m ? " " + m[1] : ""}`
+  } else if (ua.includes("Linux")) {
+    os = "Linux"
+  }
+
+  // ===== 设备类型解析 =====
+  let device = "Desktop"
+  if (ua.includes("iPad")) device = "iPad"
+  else if (ua.includes("iPhone")) device = "iPhone"
+  else if (ua.includes("Android") && ua.includes("Mobile"))
+    device = "Android Phone"
+  else if (ua.includes("Android")) device = "Android Tablet"
+
+  return { browser, os, device }
+}
+
+/**
+ * 将 ParsedUA 拼接为可读字符串，如 "Chrome 120 / Windows 10/11 / 桌面"
+ */
+export function formatParsedUA(parsed: ParsedUA): string {
+  return [parsed.browser, parsed.os, parsed.device]
+    .filter((s) => s && s !== "Unknown")
+    .join(" / ")
+}