@orbit-work/ui 0.1.0

package/src/screens/_skillsCatalog.tsx

@@ -0,0 +1,372 @@
+import type { ReactNode } from "react"
+import { CatalogEmptyState } from "../components/composite/CatalogStates"
+import type { StatusTagPreset } from "../components/composite/StatusTag"
+import { DesktopAgentCardView, DesktopConnectorCardView } from "../components/domain/desktop/DesktopCatalogView"
+import { DesktopSidebarView } from "../components/domain/desktop/DesktopSidebarView"
+import { DesktopSkillsPageView } from "../components/domain/desktop/DesktopSkillsPageView"
+import type { DesktopSkillsCategory, DesktopSkillsSection } from "../components/domain/desktop/DesktopSkillsPageView"
+import { DesktopWorkbenchShell } from "../components/domain/desktop/DesktopWorkbenchShell"
+import { SkillAvatarView } from "../components/domain/skills/SkillAvatarView"
+import { SkillCardView } from "../components/domain/skills/SkillCardView"
+import { DesktopScreenFrame, noop, screenSidebarProps } from "./_screen"
+
+/**
+ * 插件屏（三页签）的共享底屏 —— Screens/Skills 与 Screens/McpManager 同吃一份。
+ *
+ * 为什么单独一个文件：`Screens/McpManager` 演的是「点连接器卡打开的 MCP 服务管理弹窗」，
+ * 它的底屏就该是连接器页签本身；两个 stories 文件各抄一份 seed 会立刻走形（R1 就是这么
+ * 走形成「MCP 面板铺在连接器页签下」的）。CSF 文件里导出非 story 会被 Storybook 当成
+ * story 收走，所以底屏与 seed 落在这个非 stories 模块里。
+ *
+ * seed 逐条照原型 `template.dc.html`：分类表 3475–3477（`SKILL_CATS / AGENT_CATS / CONN_CATS`）、
+ * 专家 3487–3504（`AGENTS`）、连接器 3505–3514（`CONNS`）、已装集 3525（`SEED_INSTALLED`）、
+ * 状态签 4562–4570（`statusOf`）、卡脚 4581–4592（`metaOf`）、动作 4593–4599（`actOf`）。
+ */
+
+export type SkillsCatalogSection = DesktopSkillsSection
+
+/** 原型 SKILL_CATS(3475) —— 技能页签分类。 */
+export const SKILL_CATS: DesktopSkillsCategory[] = [
+  { id: null, label: "全部" },
+  { id: "office", label: "办公" },
+  { id: "dev", label: "研发" },
+  { id: "content", label: "内容" },
+  { id: "data", label: "数据" },
+]
+
+/** 原型 AGENT_CATS(3476) —— 专家页签分类。 */
+export const AGENT_CATS: DesktopSkillsCategory[] = [
+  { id: null, label: "全部" },
+  { id: "dev", label: "研发" },
+  { id: "research", label: "研究" },
+]
+
+/** 原型 CONN_CATS(3477) —— 连接器页签分类。 */
+export const CONN_CATS: DesktopSkillsCategory[] = [
+  { id: null, label: "全部" },
+  { id: "official", label: "官方" },
+  { id: "dev", label: "研发" },
+  { id: "office", label: "办公" },
+]
+
+export type SkillSeed = {
+  id: string
+  name: string
+  desc: string
+  glyph: string
+  installed: boolean
+  outdated?: boolean
+  installing?: boolean
+  mine?: boolean
+  version?: string
+  /** 卡脚 mono 带的第二段（原型 metaOf：`v1.4.2 · 3 天前`）。 */
+  updated?: string
+}
+
+export const SKILLS: SkillSeed[] = [
+  {
+    id: "code-review",
+    name: "代码审查",
+    desc: "读 diff，指出会出事的地方，顺手给一版改法。",
+    glyph: "审",
+    installed: true,
+    version: "1.4.0",
+    updated: "3 天前",
+  },
+  {
+    id: "weekly",
+    name: "周报整理",
+    desc: "把一周的提交、会议和待办压成一段能直接发的周报。",
+    glyph: "周",
+    installed: true,
+    outdated: true,
+    version: "1.0.0",
+    updated: "2 周前",
+  },
+  {
+    id: "sheet",
+    name: "表格清洗",
+    desc: "统一口径、去重、补空值，输出一张能直接用的表。",
+    glyph: "表",
+    installed: false,
+    version: "2.1.0",
+    updated: "上周",
+  },
+  {
+    id: "meeting",
+    name: "会议纪要",
+    desc: "转录、分发言人、挑决策点，落成结构化纪要。",
+    glyph: "纪",
+    installed: false,
+    installing: true,
+    version: "0.9.2",
+    updated: "4 天前",
+  },
+  {
+    id: "design-lint",
+    name: "设计走查",
+    desc: "照设计系统的 token 与状态清单过一遍界面。",
+    glyph: "查",
+    installed: false,
+    version: "0.4.0",
+    updated: "上个月",
+  },
+  {
+    id: "release",
+    name: "发布说明",
+    desc: "把合并记录翻成人话，按面向用户的改动分组。",
+    glyph: "发",
+    installed: true,
+    version: "3.0.1",
+    updated: "今天",
+  },
+]
+
+type AgentSeed = {
+  id: string
+  name: string
+  desc: string
+  glyph: string
+  team?: boolean
+  mine?: boolean
+  status?: StatusTagPreset
+  actionLabel: string
+  meta: string[]
+}
+
+/** 原型 AGENTS(3487–3504) ＋ SEED_INSTALLED(3525) 推出的四张卡态。 */
+export const AGENTS: AgentSeed[] = [
+  {
+    id: "eng-guard",
+    name: "工程保障团队",
+    desc: "协作完成改动评审、回归验证与发布把关。",
+    glyph: "工",
+    team: true,
+    status: "installed",
+    actionLabel: "使用团队",
+    meta: ["3 成员", "3 技能", "2 连接器", "2 命令"],
+  },
+  {
+    id: "codex",
+    name: "Codex",
+    desc: "软件开发与代码任务，擅长跨文件重构。",
+    glyph: "C",
+    status: "update",
+    actionLabel: "更新",
+    meta: ["5 技能", "1 连接器", "1 命令"],
+  },
+  {
+    id: "radar",
+    name: "行业雷达",
+    desc: "按订阅源持续跟踪赛道动态并按主题归并。",
+    glyph: "雷",
+    actionLabel: "安装",
+    meta: ["2 技能", "1 命令"],
+  },
+  {
+    id: "my-oncall",
+    name: "值班助手",
+    desc: "值班时替我盯告警、拉上下文、写事故时间线。",
+    glyph: "值",
+    mine: true,
+    status: "installed",
+    actionLabel: "使用",
+    meta: ["1 技能", "1 连接器"],
+  },
+]
+
+type ConnectorSeed = {
+  id: string
+  name: string
+  desc: string
+  glyph: string
+  transport: "stdio" | "http"
+  toolCount: number
+  mine?: boolean
+  status?: StatusTagPreset
+  actionLabel: string
+}
+
+/** 原型 CONNS(3505–3514) ＋ statusOf/actOf 推出的四张卡态。 */
+export const CONNECTORS: ConnectorSeed[] = [
+  {
+    id: "filesystem",
+    name: "Filesystem",
+    desc: "读写本机目录，受授权模式与沙箱范围约束。",
+    glyph: "F",
+    transport: "stdio",
+    toolCount: 4,
+    status: "connected",
+    actionLabel: "使用",
+  },
+  {
+    id: "wecom",
+    name: "企业微信",
+    desc: "接收私聊与群聊消息，并把结果推回会话。",
+    glyph: "企",
+    transport: "http",
+    toolCount: 3,
+    status: "needsAuth",
+    actionLabel: "去授权",
+  },
+  {
+    id: "github",
+    name: "GitHub",
+    desc: "读取仓库、Issue 与 PR，支持按分支比较。",
+    glyph: "G",
+    transport: "http",
+    toolCount: 3,
+    actionLabel: "配置",
+  },
+  {
+    id: "my-jira",
+    name: "内网 Jira",
+    desc: "公司内网的 Jira，读写工单与冲刺。",
+    glyph: "J",
+    transport: "http",
+    toolCount: 3,
+    mine: true,
+    status: "connected",
+    actionLabel: "使用",
+  },
+]
+
+/** 每页签一套「搜索词 / 主钮 / 分类表」——页面壳三页签共用，只有这三项随段换。 */
+const SECTION_CHROME: Record<
+  SkillsCatalogSection,
+  { searchPlaceholder: string; actionLabel: string; categories: DesktopSkillsCategory[]; word: string }
+> = {
+  agents: { searchPlaceholder: "搜索专家", actionLabel: "添加专家", categories: AGENT_CATS, word: "专家" },
+  market: { searchPlaceholder: "搜索技能", actionLabel: "添加技能", categories: SKILL_CATS, word: "技能" },
+  connectors: {
+    searchPlaceholder: "搜索连接器",
+    actionLabel: "添加连接器",
+    categories: CONN_CATS,
+    word: "连接器",
+  },
+}
+
+export interface SkillsCatalogScreenProps {
+  section: SkillsCatalogSection
+  /** 空态：`search` ＝搜不到（带「清空搜索」退路），`section` ＝这一段一条都没有。 */
+  empty?: "search" | "section"
+  loading?: boolean
+  /** 弹窗/浮层槽（Screens/McpManager 用它挂 MCP 服务管理弹窗）。 */
+  overlay?: ReactNode
+}
+
+/** 三页签同一张底屏：页头/页签/筛选行/网格全同形，只有卡的配方按段换。 */
+export function SkillsCatalogScreen({ section, empty, loading, overlay }: SkillsCatalogScreenProps) {
+  const chrome = SECTION_CHROME[section]
+  const count = section === "agents" ? AGENTS.length : section === "connectors" ? CONNECTORS.length : SKILLS.length
+  // 分页与列表同源：空/载时总数就是 0，不能摆着「‹ 1 2 ›」与空态自相矛盾。
+  const totalItems = empty || loading ? 0 : count === 0 ? 0 : 48
+  return (
+    <DesktopScreenFrame>
+      <DesktopWorkbenchShell
+        contained
+        view="skills"
+        sidebar={<DesktopSidebarView {...screenSidebarProps({ activeNav: "skills" })} />}
+        chat={null}
+        sites={null}
+        scheduledTasks={null}
+        workspace={null}
+        skills={
+          <DesktopSkillsPageView
+            section={section}
+            onSectionChange={noop}
+            query=""
+            onQueryChange={noop}
+            searchPlaceholder={chrome.searchPlaceholder}
+            actionLabel={chrome.actionLabel}
+            onAction={noop}
+            categories={chrome.categories}
+            activeCategoryId={null}
+            onCategoryChange={noop}
+            installedOnly={false}
+            onInstalledOnlyChange={noop}
+            currentPage={1}
+            totalItems={totalItems}
+            pageSize={24}
+            onPageChange={noop}
+            loading={loading}
+            emptyState={
+              empty === "search" ? (
+                <CatalogEmptyState
+                  grid
+                  title={`没找到匹配的${chrome.word}`}
+                  hint="换个词，或者把分类切回「全部」再看看。"
+                  onClearSearch={noop}
+                />
+              ) : empty === "section" ? (
+                /* 原型 catEmptyText(4636) 的无搜索词分支：「这一段还没有 X，从上面「添加 X」开始。」 */
+                <CatalogEmptyState
+                  grid
+                  title={`这一段还没有${chrome.word}`}
+                  hint={`从上面「${chrome.actionLabel}」开始。`}
+                />
+              ) : undefined
+            }
+            overlay={overlay}
+          >
+            <div className="plaza__grid">
+              {section === "agents" &&
+                AGENTS.map((agent) => (
+                  <DesktopAgentCardView
+                    key={agent.id}
+                    avatar={<SkillAvatarView glyph={{ label: agent.glyph, id: agent.id }} />}
+                    name={agent.name}
+                    description={agent.desc}
+                    team={agent.team}
+                    mine={agent.mine}
+                    status={agent.status}
+                    metaItems={agent.meta.map((label, index) => ({ key: `m${index}`, label }))}
+                    actionLabel={agent.actionLabel}
+                    actionVariant="secondary"
+                    onOpen={noop}
+                    onAction={noop}
+                  />
+                ))}
+              {section === "market" &&
+                SKILLS.map((skill) => (
+                  <SkillCardView
+                    key={skill.id}
+                    name={skill.name}
+                    desc={skill.desc}
+                    avatar={<SkillAvatarView glyph={{ label: skill.glyph, id: skill.id }} />}
+                    version={skill.version}
+                    showVersion
+                    outdated={skill.outdated}
+                    installed={skill.installed}
+                    installing={skill.installing}
+                    mine={skill.mine}
+                    metaItems={skill.updated ? [{ key: "updated", label: skill.updated }] : undefined}
+                    onOpen={noop}
+                    onAction={noop}
+                  />
+                ))}
+              {section === "connectors" &&
+                CONNECTORS.map((connector) => (
+                  <DesktopConnectorCardView
+                    key={connector.id}
+                    logo={connector.glyph}
+                    name={connector.name}
+                    description={connector.desc}
+                    status={connector.status}
+                    mine={connector.mine}
+                    metaItems={[
+                      { key: "transport", label: connector.transport },
+                      { key: "tools", label: "个工具", count: connector.toolCount },
+                    ]}
+                    actionLabel={connector.actionLabel}
+                    onOpen={noop}
+                    onAction={noop}
+                  />
+                ))}
+            </div>
+          </DesktopSkillsPageView>
+        }
+      />
+    </DesktopScreenFrame>
+  )
+}

package/src/theme/SkinDenylistSyncSource.test.mjs

@@ -0,0 +1,124 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const skin = await readFile(new URL("./core/skin.ts", import.meta.url), "utf8")
+
+/**
+ * check-skin-ds2.mjs 在仓里有**两份**字节相同的副本（.claude 与 .agents 各一，
+ * 都是实体目录不是软链）。R2 之前这份测试只读 .claude 那一份，.agents 的副本
+ * 不在任何守卫视野里——改一份忘另一份不会有人报。现在两份一起读、一起断言。
+ */
+const GUARD_COPIES = [
+  ".claude/skills/ui-theme-skin/scripts/check-skin-ds2.mjs",
+  ".agents/skills/ui-theme-skin/scripts/check-skin-ds2.mjs",
+]
+const guards = await Promise.all(
+  GUARD_COPIES.map(async (rel) => ({
+    rel,
+    source: await readFile(new URL(`../../../../${rel}`, import.meta.url), "utf8"),
+  })),
+)
+
+/** 从两处清单里各抽出条目字符串，忽略注释与排布差异。 */
+function entries(source, marker, pattern = /"(--ow-[^"]+)"/) {
+  const start = source.indexOf(marker)
+  assert.notEqual(start, -1, `找不到 ${marker}`)
+  const end = source.indexOf("]", start)
+  return source
+    .slice(start, end)
+    .split("\n")
+    .map((line) => line.match(pattern)?.[1])
+    .filter(Boolean)
+}
+
+/** 任意字符串字面量条目（属性名/值形态清单用，条目不以 --ow- 开头）。 */
+const ANY_STRING = /"([^"]+)"/
+
+// W5 移交项⑤：--ow-mention-bg/-text 直挂 --ow-info-tint/-on-tint。别名不封，
+// 等于给 L2/L3 皮肤留了一道绕开功能色禁覆盖的后门（§15 皮肤边界）。
+test("--ow-mention* 进禁覆盖清单：功能色别名不留后门", () => {
+  assert.ok(entries(skin, "DS2_SKIN_DENYLIST = [").includes("--ow-mention*"))
+  for (const { rel, source } of guards) {
+    assert.ok(entries(source, "const DENYLIST = [").includes("--ow-mention*"), rel)
+  }
+})
+
+// skin.ts 与 skill 脚本是同一清单的多份副本（脚本无法 import TS 源），必须逐条同步。
+// R2：文件头的同步义务点名了五份常量，原来只有 DENYLIST 一份有守卫，其余四份
+// （含 skin.ts 自己写着「⚠️ 同步义务」的 DS2_SKIN_DENIED_PROPERTIES）全靠人记。
+const MIRRORED_LISTS = [
+  { name: "禁覆盖 token 清单", skin: "DS2_SKIN_DENYLIST = [", guard: "const DENYLIST = [", pattern: undefined },
+  {
+    name: "锁定件选择器清单",
+    skin: "DS2_LOCKED_SLOT_SELECTORS = [",
+    guard: "const LOCKED_SLOT_SELECTORS = [",
+    pattern: ANY_STRING,
+  },
+  {
+    name: "禁覆盖 CSS 属性清单",
+    skin: "DS2_SKIN_DENIED_PROPERTIES = [",
+    guard: "const DENIED_PROPERTIES = [",
+    pattern: ANY_STRING,
+  },
+  {
+    name: "禁覆盖值形态清单",
+    skin: "DS2_SKIN_DENIED_VALUE_PATTERNS = [",
+    guard: "const DENIED_VALUE_PATTERNS = [",
+    pattern: ANY_STRING,
+  },
+  {
+    name: "中性组必填键",
+    skin: "NEUTRAL_REQUIRED_KEYS = [",
+    guard: "const NEUTRAL_REQUIRED_KEYS = [",
+    pattern: ANY_STRING,
+  },
+  {
+    name: "中性组触发键",
+    skin: "NEUTRAL_TRIGGER_KEYS = [",
+    guard: "const NEUTRAL_TRIGGER_KEYS = [",
+    pattern: ANY_STRING,
+  },
+]
+
+for (const list of MIRRORED_LISTS) {
+  test(`skin.ts 与 check-skin-ds2.mjs 的${list.name}逐条一致`, () => {
+    const expected = entries(skin, list.skin, list.pattern)
+    assert.ok(expected.length > 0, `${list.skin} 抽不到条目`)
+    for (const { rel, source } of guards) {
+      assert.deepEqual(entries(source, list.guard, list.pattern), expected, rel)
+    }
+  })
+}
+
+// VAR_MAP（白名单 key → CSS 变量落点）：键集合必须一致，否则皮肤能提交一个
+// 脚本认识、运行时不认识（或反过来）的落点。
+test("skin.ts 与 check-skin-ds2.mjs 的 VAR_MAP 键集合一致", () => {
+  const keysOf = (source, marker) => {
+    const start = source.indexOf(marker)
+    assert.notEqual(start, -1, `找不到 ${marker}`)
+    const end = source.indexOf("\n}", start)
+    return source
+      .slice(start, end)
+      .split("\n")
+      .map((line) => line.match(/^\s*"?([A-Za-z][A-Za-z0-9]*)"?\s*:\s*"--ow-/)?.[1])
+      .filter(Boolean)
+      .sort()
+  }
+  const expected = keysOf(skin, "ORBITWORK_SKIN_CSS_VARIABLES: Readonly<Record<keyof OrbitworkSkinTokens, string>> = {")
+  assert.ok(expected.length > 0)
+  for (const { rel, source } of guards) {
+    assert.deepEqual(keysOf(source, "const VAR_MAP = {"), expected, rel)
+  }
+})
+
+test("check-skin-ds2.mjs 的两份副本字节一致", () => {
+  assert.equal(guards[0].source, guards[1].source)
+})
+
+// 别名的落点本身也不许飘：mention 系必须仍指向 info 族，否则封了别名也白封。
+test("--ow-mention-bg/-text 仍别名到 info tint 族", async () => {
+  const tokens = await readFile(new URL("../../styles/tokens.css", import.meta.url), "utf8")
+  assert.match(tokens, /--ow-mention-bg: var\(--ow-info-tint\);/)
+  assert.match(tokens, /--ow-mention-text: var\(--ow-info-on-tint\);/)
+})

package/src/theme/__tests__/skins.test.mjs

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+/**
+ * R2 接线修：本文件原是 `skins.test.ts`，`import { describe, expect, it } from "vitest"`。
+ * 但 package.json 的 test 脚本用 node --test 只收 .mjs（glob 见 package.json scripts.test），
+ * 而 vitest.config.ts 的 test.projects 里只有一个 storybook 浏览器 project（storybookTest
+ * 只跑 stories）。也就是说：`npm test` 一千余条全绿，其中不含这份文件的任何断言——同一个
+ * 目录里两套测试框架，其中一套根本不接线。改写成 node:test，与同目录另两份
+ * （SkinDenylistSyncSource / skinDs2PropertyGate）同框架、同入口。
+ */
+const { BUILTIN_ORBITWORK_SKINS } = await import("../skins/index.ts")
+
+test("内置皮肤全部导出", () => {
+  assert.ok(BUILTIN_ORBITWORK_SKINS)
+  assert.ok(BUILTIN_ORBITWORK_SKINS.length > 0)
+})
+
+test("每份皮肤结构合法（version/id/name/modes）", () => {
+  for (const skin of BUILTIN_ORBITWORK_SKINS) {
+    assert.equal(skin.version, 1, skin.id)
+    assert.ok(skin.id, "id 不能为空")
+    assert.ok(skin.name, `${skin.id}.name 不能为空`)
+    assert.ok(skin.modes, `${skin.id}.modes 缺失`)
+    assert.ok(skin.modes.light || skin.modes.dark, `${skin.id} 至少要有一档`)
+  }
+})
+
+test("皮肤 id 唯一", () => {
+  const ids = BUILTIN_ORBITWORK_SKINS.map((s) => s.id)
+  assert.equal(new Set(ids).size, ids.length)
+})
+
+/*
+ * ⚠️ 已知宽松（W5 记录，暂不收紧）：
+ * `skin.ts` 的解析契约 `HEX_COLOR` 是 hex-only（#RGB/#RGBA/#RRGGBB/#RRGGBBAA），
+ * 本断言却额外放行 `rgba(...)`。原来收紧不了是因为 `skins/glass.ts` 里有
+ * `rgba(59, 130, 246, 0.9)` 实值；研发 main 已把 cyberpunk/glass 两份整删，
+ * 现存三份（aurora / forest / aurora-pro）全是 hex，收紧已无阻碍——留待 D1
+ * （内置皮肤值定案）一并改成 hex-only 并删掉本注释。
+ */
+test("按钮主色值形态合法", () => {
+  for (const skin of BUILTIN_ORBITWORK_SKINS) {
+    for (const mode of ["light", "dark"]) {
+      const value = skin.modes[mode]?.buttonPrimaryBackground
+      if (!value) continue
+      assert.match(value, /^#[0-9a-fA-F]{6}$|^rgba?\(/, `${skin.id}.${mode}.buttonPrimaryBackground`)
+    }
+  }
+})
+
+test("内置皮肤不携带 DS2 禁覆盖键（COMPONENT-RULES §15）", () => {
+  const deniedKeys = [
+    "primary",
+    "primaryHover",
+    "primaryBackground",
+    "primaryBorder",
+    "link",
+    "switchActive",
+    "info",
+    "success",
+    "warning",
+    "error",
+    "cardRadius",
+    "buttonRadius",
+  ]
+  for (const skin of BUILTIN_ORBITWORK_SKINS) {
+    assert.equal(skin.common, undefined, `${skin.id}.common 应已随皮肤边界取消`)
+    for (const mode of [skin.modes.light, skin.modes.dark]) {
+      if (!mode) continue
+      for (const key of deniedKeys) {
+        assert.ok(!(key in mode), `${skin.id} 的 mode 里仍有禁覆盖键 ${key}`)
+      }
+    }
+  }
+})
+
+test("有 L2/L3 就必须有 registry 登记", () => {
+  for (const skin of BUILTIN_ORBITWORK_SKINS) {
+    if (skin.contributes?.semanticStyles || skin.contributes?.patches) {
+      assert.ok((skin.contributes.registry?.length ?? 0) > 0, `${skin.id} 有 L2/L3 却无 registry`)
+    }
+  }
+})

package/src/theme/core/semanticAdapter.ts

@@ -0,0 +1,116 @@
+/**
+ * 语义属性适配器 — 为关键组件自动添加 data-ow-* 属性
+ *
+ * 目的：让皮肤作者能用契约化选择器（data-ow-surface/part）精准定制样式，
+ * 而不依赖易变的 className 或 DOM 结构。
+ *
+ * 实施策略：
+ * - 运行时扫描现有组件的标识属性（data-chat-container 等）
+ * - 自动添加对应的语义属性（data-ow-surface="chat" 等）
+ * - 逐步迁移到组件内声明（在组件代码里直接写语义属性）
+ */
+
+type SemanticRule = {
+  selector: string
+  surface?: string
+  part?: string
+  role?: string
+}
+
+/**
+ * 语义规则表：从现有组件标识映射到语义属性
+ *
+ * 判定标准：有专属皮肤 token 的组件域（见 skin.ts 的 OrbitworkSkinTokens）
+ */
+const SEMANTIC_RULES: readonly SemanticRule[] = [
+  // Chat 域（chatBackground*, userBubble*）
+  { selector: "[data-chat-container]", surface: "chat" },
+  { selector: "[data-message-bubble]", part: "message-bubble" },
+  { selector: "[data-message-avatar]", part: "avatar" },
+
+  // Composer 域（composerBackground, composerBorder）
+  { selector: "[data-composer]", surface: "composer" },
+  { selector: "[data-composer-input]", part: "input" },
+  { selector: "[data-composer-toolbar]", part: "toolbar" },
+
+  // Sidebar 域（sidebarBackground, sidebarSelectedBackground）
+  { selector: "[data-sidebar]", surface: "sidebar" },
+  { selector: "[data-sidebar-item]", part: "sidebar-item" },
+
+  // File 域（file-icon-*）
+  { selector: "[data-file-icon]", part: "file-icon" },
+
+  // Browser 域（未来扩展）
+  { selector: "[data-browser-preview]", surface: "browser" },
+
+  // Workbench 域（未来扩展）
+  { selector: "[data-workbench]", surface: "workbench" },
+] as const
+
+/**
+ * 创建语义属性适配器
+ *
+ * @returns 适配器实例，调用 .disconnect() 停止
+ */
+export function createSemanticAdapter(): MutationObserver {
+  const applySemanticAttributes = () => {
+    for (const rule of SEMANTIC_RULES) {
+      const elements = document.querySelectorAll(rule.selector)
+      for (const el of elements) {
+        // 只添加缺失的属性，避免覆盖组件内声明的值
+        if (rule.surface && !el.hasAttribute("data-ow-surface")) {
+          el.setAttribute("data-ow-surface", rule.surface)
+        }
+        if (rule.part && !el.hasAttribute("data-ow-part")) {
+          el.setAttribute("data-ow-part", rule.part)
+        }
+        if (rule.role && !el.hasAttribute("data-ow-role")) {
+          el.setAttribute("data-ow-role", rule.role)
+        }
+      }
+    }
+  }
+
+  // 初始应用
+  applySemanticAttributes()
+
+  // 监听 DOM 变化
+  const observer = new MutationObserver(() => {
+    applySemanticAttributes()
+  })
+
+  observer.observe(document.body, {
+    childList: true,
+    subtree: true,
+  })
+
+  return observer
+}
+
+/**
+ * 检查元素是否有语义属性
+ */
+export function hasSemanticAttributes(element: Element): boolean {
+  return (
+    element.hasAttribute("data-ow-surface") ||
+    element.hasAttribute("data-ow-part") ||
+    element.hasAttribute("data-ow-role")
+  )
+}
+
+/**
+ * 获取元素的语义属性
+ */
+export function getSemanticAttributes(element: Element): {
+  surface?: string
+  part?: string
+  role?: string
+  state?: string
+} {
+  return {
+    surface: element.getAttribute("data-ow-surface") || undefined,
+    part: element.getAttribute("data-ow-part") || undefined,
+    role: element.getAttribute("data-ow-role") || undefined,
+    state: element.getAttribute("data-ow-state") || undefined,
+  }
+}