@orbit-work/ui 0.1.0

package/src/components/domain/skills/McpServerListView/index.tsx

@@ -0,0 +1,250 @@
+"use client"
+
+import { useState } from "react"
+import { ChevRight, Globe, Refresh, Terminal, Trash } from "../../../composite/Icons"
+import { RowOverflowMenu } from "../../../composite/RowOverflowMenu"
+import { Skeleton } from "../../../composite/Skeleton"
+import { Tag } from "../../../composite/Tag"
+import { Button, Chip } from "../../../primitives"
+import type { ChipDotTone } from "../../../primitives/Chip"
+import { EmptyState } from "../../../primitives/EmptyState"
+import { Pagination } from "../../../primitives/Pagination"
+
+const PAGE_SIZE = 8
+
+export type McpServerViewStatus =
+  | "available"
+  | "configured"
+  | "auto_disabled"
+  | "starting"
+  | "restarting"
+  | "degraded"
+  | "error"
+  | "missing"
+  | "sidecar_error"
+  | "unknown"
+
+export interface McpServerViewModel {
+  id: string
+  type: "stdio" | "http"
+  displayName?: string
+  summary: string
+  status: McpServerViewStatus
+  statusText: string
+  toolNames: string[]
+  errorSummary?: string
+}
+
+export interface McpServerListViewProps<T extends McpServerViewModel = McpServerViewModel> {
+  servers: T[]
+  page: number
+  onPageChange: (page: number) => void
+  loading: boolean
+  onRefresh: (server: T) => Promise<void>
+  onCopy: (server: T) => void
+  onRemove: (server: T) => Promise<void>
+}
+
+/**
+ * McpServerListView — 自定义 MCP 服务列表（BLUEPRINT 05 · connectors 域）。
+ *
+ * 行按 DS2 行家族配方组织：左类型图标 → 名称 → 传输 `Tag`（直角 6，纯分类）→
+ * 连接状态 `Chip`（胶囊 999，带状态点）→ 行末 `RowOverflowMenu`（Menu 配方）。
+ * R1 双编码（§4）：连接状态的点色**永远**伴随可读文字（已连接=success / 连接中=warning /
+ * 待命·未知=neutral / 异常=error），颜色只作第二编码；R3 中性件，全行无信标荧黄。
+ * W3-4：传输类型的彩色底章退役——原来 http 走 info 蓝底蓝字、stdio 走中性底，
+ * 「哪种传输」只由底色说，是纯颜色编码。现两型同为中性章（--ow-surface-2 + --ow-text-2），
+ * 类型改由字形（Terminal / Globe）＋ 同行 `Tag` 的 STDIO/HTTP 文字双编码承担。
+ * §6 容器件三态：空态走 `EmptyState` 原语（G5：信标 mono 母题 ＋ 一句 text-2，W3 起
+ * 不再是 52px 图标筐 ＋ 600 标题 ＋ text-3 副行的 connector-empty 老三件）、
+ * 加载走 skeleton 呼吸（禁 shimmer）、错误由展开区人话一句 ＋ mono 摘要 ≤2 行承担。
+ * 读数（命令摘要、工具名）§7 一律 mono＋tabular-nums，样式在 desktop-surfaces.css。
+ */
+export function McpServerListView<T extends McpServerViewModel>({
+  servers,
+  page,
+  onPageChange,
+  loading,
+  onRefresh,
+  onCopy,
+  onRemove,
+}: McpServerListViewProps<T>) {
+  if (loading && servers.length === 0) {
+    return (
+      <div className="mcp-server-list" aria-busy="true" aria-label="正在读取 MCP 配置">
+        {[0, 1, 2].map((index) => (
+          <div className="mcp-server-row" key={index}>
+            <span />
+            <Skeleton variant="block" width={38} height={38} radius="var(--ow-radius-md)" />
+            <div className="mcp-server-row__body">
+              <Skeleton variant="line" width="42%" height={13} />
+              <Skeleton variant="line" width="66%" height={11} />
+            </div>
+            <span />
+          </div>
+        ))}
+      </div>
+    )
+  }
+  if (servers.length === 0) {
+    return (
+      /* A5-B3：整块面板的空态，落 `size="page"` 一级形制——母题 52×32 ＋ 16/500 标题
+         ＋ 14/1.75 副句，版心归原语（56/440/14），`py-16` 这条外挂内距撤掉，
+         否则上留白 64+56 叠成两截。
+         这里**不给 CTA**：同一张卡的卡头右上已经有一枚「添加 MCP」主钮（行动极 ×1，暗档
+         就是那块荧黄），空态再摆一枚就是同屏第二处（§4 全屏一处）；那枚钮就在这块空白
+         正上方 40px，用不着再在正文里指一次路。本件也没有 onAdd 之类的回调，凭空造一个
+         新接口只为渲一枚重复的钮不划算。
+         副句因此只承担「接进来会怎样」这一件事，并收在 440 量度内一行放得下。 */
+      <EmptyState
+        className="connector-empty"
+        size="page"
+        title="还没有自定义 MCP"
+        message="把本机跑着的 MCP 服务接进来，AI 就能用上它带的那些工具。"
+      />
+    )
+  }
+  const totalPages = Math.max(1, Math.ceil(servers.length / PAGE_SIZE))
+  const currentPage = Math.min(page, totalPages)
+  return (
+    <div className="mcp-server-list">
+      {servers.slice((currentPage - 1) * PAGE_SIZE, currentPage * PAGE_SIZE).map((server) => (
+        <McpServerRow key={server.id} server={server} onRefresh={onRefresh} onCopy={onCopy} onRemove={onRemove} />
+      ))}
+      {totalPages > 1 && (
+        <Pagination current={currentPage} total={servers.length} pageSize={PAGE_SIZE} onChange={onPageChange} />
+      )}
+    </div>
+  )
+}
+
+function McpServerRow<T extends McpServerViewModel>({
+  server,
+  onRefresh,
+  onCopy,
+  onRemove,
+}: Omit<McpServerListViewProps<T>, "servers" | "page" | "onPageChange" | "loading"> & { server: T }) {
+  const [expanded, setExpanded] = useState(false)
+  const [reconnecting, setReconnecting] = useState(false)
+  const [removing, setRemoving] = useState(false)
+  const unavailable = server.status !== "available"
+  const hasDetails = Boolean(server.errorSummary || unavailable)
+  const busy = reconnecting || removing
+  const statusTone = reconnecting ? "reconnecting" : statusToneOf(server.status)
+  const statusLabel = reconnecting ? "重连中" : statusLabelOf(server)
+  const reconnect = async () => {
+    setReconnecting(true)
+    try {
+      await onRefresh(server)
+    } finally {
+      setReconnecting(false)
+    }
+  }
+  const remove = async () => {
+    setRemoving(true)
+    try {
+      await onRemove(server)
+    } finally {
+      setRemoving(false)
+    }
+  }
+  return (
+    <div className={`mcp-server-row${expanded ? " is-expanded" : ""}${busy ? " is-busy" : ""}`}>
+      {/* §6 focus-visible：展开钮走 ghost·sm 正规变体（含 2px 环＋2px 缝），
+          不再用 unstyled 手搓——unstyled 不带焦点环。 */}
+      <Button
+        variant="ghost"
+        size="sm"
+        className="mcp-server-row__expand"
+        disabled={!hasDetails}
+        aria-label={expanded ? "收起 MCP 详情" : "展开 MCP 详情"}
+        aria-expanded={hasDetails ? expanded : undefined}
+        onClick={() => setExpanded((value) => !value)}
+      >
+        <ChevRight />
+      </Button>
+      {/* t-stdio / t-http 保留作渲染钩子，但不再挂颜色（W3-4，见 desktop-surfaces.css）。 */}
+      <span className={`mcp-server-row__icon t-${server.type}`}>
+        {server.type === "stdio" ? <Terminal /> : <Globe />}
+      </span>
+      <div className="mcp-server-row__body">
+        <div className="mcp-server-row__title">
+          <b>{server.displayName || server.id}</b>
+          <Tag size="sm" variant="primary" shape="square">
+            {server.type === "stdio" ? "STDIO" : "HTTP"}
+          </Tag>
+          {/* R1 双编码：点色 + 文字同时给出，禁止只靠颜色区分连接状态。
+              空挂钩清除：原来还挂着一个只作定位用的类名，样式表里无任何规则
+              （真正生效的是 .mcp-server-row__title > [data-slot="chip"]）。 */}
+          <Chip dot={chipToneOf(statusTone)} label={statusLabel} description={server.statusText} />
+        </div>
+        {hasDetails && expanded && (
+          <div className="mcp-server-row__details">
+            <div className="mcp-server-row__summary">{server.summary || "-"}</div>
+            {server.toolNames.length > 0 && (
+              <div className="mcp-server-row__tools">{server.toolNames.slice(0, 5).join(" · ")}</div>
+            )}
+            <b>处理建议</b>
+            <p>{server.errorSummary ?? "当前 MCP 暂未返回工具，请刷新状态或在首次使用时再检查。"}</p>
+          </div>
+        )}
+      </div>
+      <div className="mcp-server-row__actions">
+        <RowOverflowMenu
+          disabled={busy}
+          ariaLabel={`「${server.displayName || server.id}」的更多操作`}
+          items={[
+            { key: "reconnect", label: reconnecting ? "重连中…" : "重连", icon: <Refresh /> },
+            ...(hasDetails ? [{ key: "copy", label: "复制错误摘要", icon: <Terminal />, confirmsInPlace: true }] : []),
+            { key: "remove", label: removing ? "删除中…" : "删除", icon: <Trash />, danger: true },
+          ]}
+          onSelect={(key) => {
+            if (key === "reconnect") void reconnect()
+            else if (key === "copy") onCopy(server)
+            else if (key === "remove") void remove()
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+/**
+ * 连接状态 → 语义档。
+ *
+ * `degraded`（部分异常／已降级）原来 fall through 到 "error"，于是「已降级」与
+ * 「启动失败」拿同一枚红点，功能色四档在这一屏塌成两档、肉眼无法区分。
+ * 降级＝还在服务但不完整，正是 warning 的语义档（`chipToneOf` 早已为
+ * reconnecting 留了 warning 出口，degraded 只是没接上）。
+ */
+function statusToneOf(status: McpServerViewStatus): "unavailable" | "error" | "success" | "warning" {
+  if (status === "available") return "success"
+  if (status === "auto_disabled" || status === "starting" || status === "restarting" || status === "unknown")
+    return "unavailable"
+  if (status === "degraded") return "warning"
+  return "error"
+}
+
+/** 连接状态 → Chip 状态点色（§4 R1：点色只是第二编码，文字始终同在）。 */
+function chipToneOf(tone: "unavailable" | "error" | "success" | "warning" | "reconnecting"): ChipDotTone {
+  if (tone === "success") return "success"
+  if (tone === "error") return "error"
+  if (tone === "warning" || tone === "reconnecting") return "warning"
+  return "neutral"
+}
+
+function statusLabelOf(server: McpServerViewModel): string {
+  const labels: Partial<Record<McpServerViewStatus, string>> = {
+    available: "已连接",
+    configured: "暂无可用工具",
+    auto_disabled: "已自动隔离",
+    starting: "连接中",
+    restarting: "重连中",
+    degraded: "部分异常",
+    error: "连接异常",
+    missing: "连接异常",
+    sidecar_error: "状态刷新失败",
+    unknown: "状态未知",
+  }
+  return labels[server.status] || server.statusText || "不可用"
+}

package/src/components/domain/skills/SkillAvatarView/SkillAvatarView.stories.tsx

@@ -0,0 +1,121 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { SkillAvatarView, skillAvatarTone, skillGlyph } from "./index"
+
+/**
+ * SkillAvatarView —— 技能/智能体/连接器头像。
+ *
+ * DS2 §7 身份色：底色只在 `--ow-data-1..6` 六档里按稳定身份键哈希轮转（与 Avatar 同一份
+ * `hashToDataColor`），agent 走墨面档，neutral 是未知身份的无彩档。调用方**只交身份和首字**，
+ * 不再注入 bg/fg —— 那条透传口是 V1 遗留，2.0 已移除。
+ */
+const meta = {
+  title: "Skills/SkillAvatarView",
+  component: SkillAvatarView,
+  parameters: { layout: "centered" },
+  tags: ["autodocs"],
+} satisfies Meta<typeof SkillAvatarView>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const tile =
+  "inline-flex h-9 w-9 items-center justify-center [border-radius:var(--ow-radius-sm)] text-ow-fs-ui font-semibold"
+
+export const Default: Story = {
+  args: { className: tile, glyph: skillGlyph("code-review", "代码走查") },
+}
+
+/** 六档 data 色轮转：同一个 id 永远落同一档，换主题只换色值不换档。 */
+export const DataRotation: Story = {
+  render: () => (
+    <div className="flex flex-wrap items-center gap-3">
+      {["data-1", "data-2", "data-3", "data-4", "data-5", "data-6"].map((tone, index) => (
+        <div key={tone} className="flex flex-col items-center gap-1.5">
+          <SkillAvatarView className={tile} glyph={{ label: String(index + 1), tone: tone as never }} />
+          <span className="font-[family-name:var(--ow-font-mono)] text-ow-fs-caption text-ow-text-3 tabular-nums">
+            {tone}
+          </span>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/** agent＝墨面档（智能体身份）；neutral＝无彩档（占位/未知身份）。 */
+export const AgentAndNeutral: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <SkillAvatarView className={tile} glyph={{ label: "智", tone: "agent" }} />
+      <SkillAvatarView className={tile} glyph={{ label: "?", tone: "neutral" }} />
+    </div>
+  ),
+}
+
+/** 同一 id 反复渲染永远同色——用 skillAvatarTone 可以预读档位。 */
+export const StableByIdentity: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2">
+      {[
+        ["ppt-gen", "PPT 生成"],
+        ["data-analysis", "数据分析"],
+        ["browser-automation", "浏览器自动化"],
+        ["hot-tracking", "热点追踪"],
+        ["social-ops", "社媒运营指南"],
+      ].map(([id, name]) => (
+        <div key={id} className="flex items-center gap-3">
+          <SkillAvatarView className={tile} glyph={skillGlyph(id, name)} />
+          <span className="text-ow-fs-ui text-ow-text">{name}</span>
+          <span className="ml-auto font-[family-name:var(--ow-font-mono)] text-ow-fs-caption text-ow-text-3 tabular-nums">
+            {skillAvatarTone(id)}
+          </span>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/** 有图就用图（object-fit: fill，方形裁切由容器 className 决定）。 */
+export const WithImage: Story = {
+  args: {
+    className: tile,
+    src: "data:image/svg+xml;utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='36' height='36'%3E%3Crect width='36' height='36' fill='%235E9787'/%3E%3C/svg%3E",
+    glyph: skillGlyph("with-image", "带图技能"),
+  },
+}
+
+/** 图挂了就退回字形档——退回后仍是稳定的 data 色，不会闪成另一种颜色。 */
+export const ImageFallback: Story = {
+  render: () => {
+    const [failed, setFailed] = useState(false)
+    return (
+      <div className="flex flex-col items-center gap-2">
+        <SkillAvatarView
+          className={tile}
+          src="https://invalid.example/avatar.png"
+          glyph={skillGlyph("fallback-demo", "回退演示")}
+          failed={failed}
+          onImageError={() => setFailed(true)}
+        />
+        <span className="text-ow-fs-caption text-ow-text-3">{failed ? "已回退到字形档" : "正在尝试加载图片"}</span>
+      </div>
+    )
+  },
+}
+
+/** 尺寸由调用方的 className 决定（卡内 36、详情 Hero 56、菜单行 20）。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-end gap-3">
+      <SkillAvatarView
+        className="inline-flex h-5 w-5 items-center justify-center [border-radius:var(--ow-radius-2xs)] text-ow-fs-caption font-semibold"
+        glyph={skillGlyph("size-sm", "小")}
+      />
+      <SkillAvatarView className={tile} glyph={skillGlyph("size-md", "中")} />
+      <SkillAvatarView
+        className="inline-flex h-14 w-14 items-center justify-center [border-radius:var(--ow-radius-card)] text-ow-fs-subtitle font-semibold"
+        glyph={skillGlyph("size-lg", "大")}
+      />
+    </div>
+  ),
+}

package/src/components/domain/skills/SkillAvatarView/SkillAvatarViewSource.test.mjs

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict"
+import { readFile, readdir } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+
+test("skill avatar rotates over the six data colors instead of taking injected colors", () => {
+  // 色档只来自 --ow-data-1..6 / agent 墨面 / neutral 无彩，全部由 hashToDataColor 决定
+  assert.match(source, /import \{ hashToDataColor \} from "\.\.\/\.\.\/\.\.\/primitives\/Avatar"/)
+  assert.match(source, /export type SkillAvatarTone = `data-\$\{1 \| 2 \| 3 \| 4 \| 5 \| 6\}` \| "agent" \| "neutral"/)
+  // R2·T2：色档解析多了一层「摆放它的那个面说了算」——上下文 > glyph.tone > 身份哈希。
+  // 上下文缺席时仍走 data 轮转（会话菜单 / 命令面板 / 详情面一个字没动）。
+  assert.match(
+    source,
+    /const tone = contextTone \?\? glyph\.tone \?\? hashToDataColor\(glyph\.id \|\| glyph\.label \|\| ""\)/,
+  )
+  // 核对（R2·T2）：useContext 必须排在 `if (src && !failed)` 的 img 早退**之前**——宿主 SkillAvatar.tsx
+  // 图片加载失败时同一实例从 img 分支切到字形分支，hook 排在早退之后会让 React 抛
+  // "Rendered more hooks than during the previous render"。
+  assert.match(
+    source,
+    /const contextTone = useContext\(GlyphToneContext\)[\s\S]*?if \(src && !failed\) \{[\s\S]*?const tone = contextTone \?\?/,
+  )
+  assert.match(source, /background: "var\(--ow-avatar-agent-bg\)", color: "var\(--ow-avatar-agent-text\)"/)
+  assert.match(source, /return \{ background: `var\(--ow-\$\{tone\}\)`, color: "var\(--ow-on-fill\)" \}/)
+})
+
+// 只看代码，不看注释——文档里要点名旧口径（旧调色板与 bg/fg 透传）才说得清收紧了什么。
+const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "")
+
+test("the caller-injected color pass-through is gone", () => {
+  // SkillAvatarGlyph 不再有 bg/fg —— 旧口径是 29 处调用方各自算色的裸色透传口
+  assert.doesNotMatch(code, /\bbg:\s*string/)
+  assert.doesNotMatch(code, /\bfg\?:\s*string/)
+  assert.doesNotMatch(code, /glyph\.bg|glyph\.fg/)
+  // 也不得回退到 V1 的 --ow-glyph-* 旧调色板或任何裸 hex
+  assert.doesNotMatch(code, /--ow-glyph-/)
+  assert.doesNotMatch(code, /#[0-9a-fA-F]{3,8}\b/)
+})
+
+test("字形章色档可由外层容器钉住（R2·T2 GlyphToneProvider）", () => {
+  // 目录卡包 neutral、专家卡包 agent，宿主一行不改就同时拿到「技能/连接器中性、专家藏蓝」。
+  // 不许改本件的默认色档：那会把 20+ 处卡外调用方（ComposerMenu / CommandPalette /
+  // AgentDetailView / PluginMcpManagement / SitesDiscoverPanel…）的身份色一起抹平。
+  assert.match(source, /export function GlyphToneProvider\(/)
+  assert.match(source, /const GlyphToneContext = createContext<SkillAvatarTone \| null>\(null\)/)
+  assert.match(
+    source,
+    /if \(tone === "neutral"\) return \{ background: "var\(--ow-surface-2\)", color: "var\(--ow-text-2\)" \}/,
+  )
+})
+
+test("skillGlyph is the sanctioned construction helper", () => {
+  assert.match(source, /export function skillGlyph\(id: string, label\?: string\): SkillAvatarGlyph/)
+  assert.match(source, /export function skillAvatarTone\(id: string\): SkillAvatarTone/)
+})
+
+test("skills domain views carry no hardcoded beacon yellow (R2/R3)", async () => {
+  const dir = new URL("../", import.meta.url)
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const file = new URL(`${entry.name}/index.tsx`, dir)
+    const text = await readFile(file, "utf8").catch(() => null)
+    if (text === null) continue
+    assert.doesNotMatch(text, /--ow-beacon|--ow-accent-dot|--ow-yellow/, `${entry.name} 引了荧黄/信标 token`)
+  }
+})

package/src/components/domain/skills/SkillAvatarView/index.tsx

@@ -0,0 +1,112 @@
+"use client"
+
+import { type ReactNode, createContext, useContext } from "react"
+import { hashToDataColor } from "../../../primitives/Avatar"
+
+/**
+ * 技能/智能体/连接器头像的色档。
+ *
+ * DS2 §7「数据与身份」：身份色只在 `--ow-data-1..6` 六档里轮转（与 Avatar 同一份
+ * `hashToDataColor`），agent 走墨面档 `--ow-avatar-agent-*`，未知身份走 neutral。
+ * **不再接受调用方注入任意 bg/fg**——旧口径由 29 处调用方各自算色（`glyphColor()`
+ * 的 7 档 `--ow-glyph-*` 旧调色板），是裸色透传口；2.0 收紧后色档只由本组件按
+ * 稳定身份键决定，调用方只交身份和首字。
+ */
+export type SkillAvatarTone = `data-${1 | 2 | 3 | 4 | 5 | 6}` | "agent" | "neutral"
+
+export interface SkillAvatarGlyph {
+  /** 首字/缩写，1-2 字 */
+  label: string
+  /**
+   * 稳定身份键（技能 id / 名字）。不给 tone 时由它哈希决定 data-1..6，
+   * 同一个 id 永远拿到同一档色；两者都不给则退到 label 自身哈希。
+   */
+  id?: string
+  /** 显式色档；agent=墨面档（智能体身份），neutral=无彩中性档（占位/未知身份） */
+  tone?: SkillAvatarTone
+}
+
+export interface SkillAvatarViewProps {
+  src?: string | null
+  glyph: SkillAvatarGlyph
+  className?: string
+  failed?: boolean
+  onImageError?: () => void
+}
+
+/**
+ * 字形章色档上下文（R2·T2）——**卡决定章色，不是章自己决定**。
+ *
+ * 原型（template.dc.html:4569–4570 `glyphOf`）的口径只有两档：专家（含专家详情）走
+ * 墨面 `--ow-avatar-agent-*`，技能/连接器一律中性 `--ow-surface-2` ＋ `--ow-text-2`；
+ * 数据色轮转只留给会话/命令面板那种「一屏里要认出好几个不同身份」的场合。
+ * 章色是**内联样式**（级联压不住，见 brief-exec 铁律 6），所以去彩不能靠改 CSS，
+ * 也不能改本件的默认值——本件有 20+ 处调用方（ComposerMenu / CommandPalette /
+ * AgentDetailView / PluginMcpManagement / SitesDiscoverPanel…），改默认会把会话屏与
+ * 命令面板里的身份色一起抹平。改由**外层容器**声明色档：目录卡包 `neutral`、
+ * 专家卡包 `agent`，不在卡里的菜单/面板一个字都不用改。
+ *
+ * 优先级：**上下文 > `glyph.tone` > 身份哈希**。上下文赢 props 是有意的——同一张
+ * `SkillCardView` 在卡里要中性、在命令面板里要身份色，决定权归摆放它的那个面。
+ */
+const GlyphToneContext = createContext<SkillAvatarTone | null>(null)
+
+/** 给一小片子树钉住字形章色档（目录卡＝neutral，专家卡＝agent）。 */
+export function GlyphToneProvider({
+  value,
+  children,
+}: {
+  value: SkillAvatarTone
+  children: ReactNode
+}): React.ReactElement {
+  return <GlyphToneContext.Provider value={value}>{children}</GlyphToneContext.Provider>
+}
+
+/** 把身份键映射到 data 档；与本组件内部同一份哈希，供调用方预解析或做视觉测试。 */
+export function skillAvatarTone(id: string): SkillAvatarTone {
+  return hashToDataColor(id)
+}
+
+/** 便捷构造：`skillGlyph(skill.id, skill.name)` → 稳定色档 + 首字标签。 */
+export function skillGlyph(id: string, label?: string): SkillAvatarGlyph {
+  const key = (id ?? "").trim()
+  const text = (label ?? key).trim()
+  return { label: text.charAt(0).toUpperCase() || "?", id: key || text }
+}
+
+function toneStyle(tone: SkillAvatarTone): { background: string; color: string } {
+  if (tone === "agent") return { background: "var(--ow-avatar-agent-bg)", color: "var(--ow-avatar-agent-text)" }
+  if (tone === "neutral") return { background: "var(--ow-surface-2)", color: "var(--ow-text-2)" }
+  return { background: `var(--ow-${tone})`, color: "var(--ow-on-fill)" }
+}
+
+export function SkillAvatarView({
+  src,
+  glyph,
+  className,
+  failed,
+  onImageError,
+}: SkillAvatarViewProps): React.ReactElement {
+  // Hook 必须排在 img 早退之前（rules-of-hooks）：宿主 SkillAvatar.tsx:35 在图片加载失败时把
+  // failed 翻成 true，同一实例从 img 分支切到字形分支——hook 数目一变，React 就抛
+  // "Rendered more hooks than during the previous render"，整棵目录随之白屏。
+  const contextTone = useContext(GlyphToneContext)
+  if (src && !failed) {
+    return (
+      <img
+        className={className}
+        src={src}
+        alt=""
+        decoding="async"
+        style={{ objectFit: "fill" }}
+        onError={onImageError}
+      />
+    )
+  }
+  const tone = contextTone ?? glyph.tone ?? hashToDataColor(glyph.id || glyph.label || "")
+  return (
+    <span className={className} style={toneStyle(tone)}>
+      {glyph.label}
+    </span>
+  )
+}