# ICEN UI（@icen.ai/ui）— 全量文档（llms-full.txt）

站点: https://ui.icen.ai · 索引: https://ui.icen.ai/llms.txt · npm: @icen.ai/ui

════════════════════════════════════════════════════════
## AGENTS.md 消费方速查
════════════════════════════════════════════════════════

# 第一段 · 消费方速查（在用户项目里用 @icen.ai/ui）

完整类型签名看包内 `dist/*.d.ts`；交互式文档 <https://ui.icen.ai>；AI 能力规格 `docs/spec/ai-native.md`；文档全文（喂模型）<https://ui.icen.ai/llms-full.txt>。

## 形态约束（先读，避免生成跑不通的代码）

- 零依赖纯 ESM + TypeScript；组件 = CSS + 行为 JS，**不绑定框架**（React/Vue 在 effect/mounted 里调行为函数即可）。
- 先引 tokens 再引组件：`@import '@icen.ai/ui/tokens.css';`（组件 CSS 全部消费 `--token-*` 变量）。
- **Astro 陷阱**：kit 入口的 css import 在页面 `<script>`（client bundle）里会被摇掉——Astro 项目必须在布局 frontmatter 引组件 CSS；Vite SPA / webpack 无此问题。
- 行为函数全部**幂等**且 **SSR 安全**（`window` 未定义静默返回）；渲染只写 `textContent`，绝不 innerHTML。
- 自定义事件统一 `icen:` 前缀（图表 `icen:chart-*`，AI 族 `icen:ai-*`）。明暗 = html `data-theme="dark"`；密度 = 容器 `data-density`。

## 安装颗粒度

```bash
bun add @icen.ai/ui               # 或 npm i
bunx @icen.ai/ui list             # 全部 slug
bunx @icen.ai/ui add btn toast    # 按 slug 打印引入行
```

```css
@import '@icen.ai/ui/tokens.css';
@import '@icen.ai/ui/ui.css';     /* 全量；或单引 @icen.ai/ui/components/btn.css */
```

- **kit 一行入口**（CSS + behavior 一起）：`import '@icen.ai/ui/kit/btn';`
- **只取行为 JS**：`import { renderChart } from '@icen.ai/ui/behaviors/charts';`
- slug 清单机器可读：`@icen.ai/ui/registry.json`。

## 图表通用层（behaviors/charts）— ChartSpec 纯 JSON，天然可被模型调用

```ts
import { renderChart } from '@icen.ai/ui/behaviors/charts';
const c = renderChart(el, {
  type: 'line',                  // line|area|vbar|hbar|stack|donut|radar|heatmap|calendar|sparkline|gauge|scatter
  title: '各版本能力数',
  labels: ['v0.1','v0.2','v0.3'],
  series: [{ name: '组件', values: [31,41,43] }, { name: 'AI 专属', values: [0,0,0] }],
  format: { unit: ' 个', places: 0 },  // 值格式化描述符（chartFormatValue）
});
c.update(newSpec);
c.on('click', (e) => e.detail);   // { index, seriesIndex, seriesName, label, value, pointerX, pointerY }
c.destroy();
```

- 省略 `type` 时 `inferChartType` 自动选型（ISO 日期/年月/周几/版本号 v0.8/纯年份等时序标签 → line）。
- 事件：`icen:chart-{move,out,click,dblclick,contextmenu,legend-toggle}`；内置 tooltip 门户（`tooltip:false` 关闭只派事件）；图表头统一带**图例眼睛**（隐藏/显示全部指标）。
- 底层渲染器（同 chrome，非 AI 场景直用）：`renderVBar/renderHBar/renderStack/renderDonut/renderLine/renderArea/renderRadar/renderHeatmap/renderCalendar/renderSparkline/renderGauge/renderScatter`。

## AI 原生族 — 7 态状态机 + kind 注册表

状态：`pending | running | streaming | approval | done | error | cancelled`。

```ts
import { renderAiMessage, createAiStream } from '@icen.ai/ui/behaviors/ai-chat';
import { renderAiToolCall, renderAiSubagent, initAiTool, initAiSubagent } from '@icen.ai/ui/behaviors/ai-tool';

renderAiMessage(el, {
  role: 'assistant', model: 'kimi-k3',
  content: [                        // 多模态 parts（纯 string 也可）
    { type: 'text', text: '结论如下' },
    { type: 'image', url, alt },    // 另有 audio / video / file{mimeType,filename} / resource_link
  ],
  meta: '刚刚 · 1.1k tok',
});

const t = renderAiToolCall(el, { id, name: 'WebSearch', kind: 'browser', status: 'running', input: { query } });
t.update({ status: 'done', output: '命中 24 条', durationMs: 1800 });
// 审批态：status:'approval' + approval:{reason} → 卡上按钮派 icen:ai-approve / icen:ai-reject
renderAiSubagent(el, { name: 'verify', input: { task }, activities: [/* 同工具卡 */] });
initAiTool(); initAiSubagent();      // 事件委托，页面级一次
```

- 线格式归一 `normalizeContentParts`（OpenAI/Anthropic/MCP 通吃）；取纯文本 `contentToText`；资源 URL `aiContentUrl`。
- kind 可扩展：`registerAiKind({ label, icon, tint, summarize })`；工具卡输入 JSON 默认折叠，`chart`/`error`/`approval`/多模态输出默认展开。
- 推理块 `.ai-reasoning` + `createAiStream(host)` 流入（host 在 `.ai-reasoning` 内时完成自动折叠并回填耗时）。
- 面板：`renderAiTodo/renderAiUsage/renderAiContext/renderAiAudit`（ai-panel）、`parseUnifiedDiff/renderAiDiff`（ai-diff）。

## 输入台 + 零接线绑定

```ts
import { initAiComposer, bindComposer, setComposerTodo, setComposerModels } from '@icen.ai/ui/behaviors/ai-composer';

initAiComposer(el);
setComposerModels(el, listAiProviders(), { provider: 'kimi', model: 'kimi-k3' });
bindComposer(el, { client, messages: chatEl });  // 一行接通发送→流式→停止→排队→错误→用量环
setComposerTodo(el, [                           // 业界模式：plan 是工具调用，实时状态挂输入框
  { content: '搜集资料', status: 'done' },
  { content: '渲染图表', status: 'running', activeForm: '正在渲染图表' },
]);  // chip 显示 x/y；全 done → is-done；有 error/cancelled → is-error；点开弹层看清单
```

## Provider 层（behaviors/ai-provider）

```ts
import { createAiClient, createAiAuditor, estimateCost } from '@icen.ai/ui/behaviors/ai-provider';

const client = createAiClient({ provider: 'kimi', model: 'kimi-k3', apiKey });
await client.chat({ messages });       // 或 client.stream(...)（SSE 逐 chunk）
const auditor = createAiAuditor();     // log() 条目含 cost（定价表估算）与 ttftMs
// 每次请求收尾派 icen:ai-done（detail: status/usage/cost/error/durationMs/ttftMs）
```

- 多模态出线：`toOpenAiContent/toAnthropicBlocks`（含 cache_control 与 tool_result 回传）。
- 用量双口径：`contextEstimate(history)` = 上下文估算（输入框用量环）；计费走 `normalizeUsage` + `estimateCost`（定价表未命中不猜价）。别混用。

## 工具体系（behaviors/ai-tools）— 把 UI 能力注册成模型可调用工具

```ts
import { createAiToolArea, aiToolsToOpenAI, aiToolsToMcp, aiToolsManifest, parseAiToolArgs }
  from '@icen.ai/ui/behaviors/ai-tools';

const area = createAiToolArea(mountEl, {
  tools: ['render_chart', 'chart-*'],  // 白名单支持 glob；缺省 = 全部已注册
  max: 4,                              // 挂载上限，LRU 淘汰
});
area.call('render_chart', { type: 'line', labels, series });  // 宿主手动/模型触发
area.setTools(['render_chart']);  area.setMax(2);  area.onChange(cb);

aiToolsToOpenAI();   // → OpenAI tools 数组
aiToolsToMcp();      // → MCP tools/list 形态
aiToolsManifest();   // → 自描述 manifest
parseAiToolArgs('render_chart', raw);   // 模型回包解析（容错 JSON 字符串/对象）
```

自定义工具：`registerAiTool({ name, description, inputSchema, onCall })`；内置 `render_chart`。挂载区条目可折叠/移除，超限 LRU 自动回收。

## 深挖索引（复杂模块不设单独 AGENTS.md，类型真相在 .d.mts）

每个 behavior 的完整接口/类型/字段约束都随包发布在 `dist/behaviors/<模块>.d.mts`（JSDoc 注释含行为约束，如「el 传容器或内部任意元素，就近解析 `[data-ai-composer]`」）。**不建议也不需要按组件再写深层 AGENTS.md**——复制必漂移；读类型面即读文档：

| 深挖什么 | 去哪读 |
| --- | --- |
| AI 族全部签名与字段约束 | 包内 `dist/behaviors/ai-{core,chat,composer,tool,panel,diff,provider,tools}.d.mts` |
| 图表 ChartSpec 全字段 + 各类型 options | `dist/behaviors/charts.d.mts` |
| 上述类型面 + JSDoc 的纯文本快照 | <https://ui.icen.ai/llms-full.txt>（「API 类型面」节，构建期自动内嵌） |
| 设计动机 / 状态机语义 / 口径取舍 | `docs/spec/ai-native.md`（包内随发） |
| DOM 契约 / CSS 类名 | 各组件文档页 <https://ui.icen.ai/components/<slug>/，kit 入口同款 CSS 头注释 |
| 场景配方（选图决策树 / 聊天五步 / 主题切换） | skill `icen-ui`（skill.icen.ai，`curl -sL https://skill.icen.ai/install/ui.sh \| bash`）——按需触发的流程层，与本手册（事实层）互补 |

---

════════════════════════════════════════════════════════
## ai-native 规格（docs/spec/ai-native.md）
════════════════════════════════════════════════════════

# AI 原生组件族 · 设计规格（v0.6.x 新增）

> 唯一事实源。施工代理按此文件执行，不得偏离契约（类名 / 导出签名 / 事件名）。
> 设计调研依据：AG-UI 协议、Vercel AI SDK UIMessage parts、OpenAI/Anthropic wire 格式、
> MCP tools schema、A2A Task 状态；产品侧 Claude Code / Kimi Code / Cursor / Copilot / Codex 的已标准化模式。

## 0. 设计原则

1. **继承用 CSS 变量级联实现**：`.ai-item` 基元定义 `--ai-item-*` 局部变量，kind/变体只覆盖变量不改结构（btn.css 的 `--btn-*` 模式的推广）。
2. **多态用 kind 注册表**：MCP、skill 不是独立组件，是 tool-call 的 kind。`registerAiKind()` 开放第三方扩展。
3. **组件只消费归一化模型**：业界格式（OpenAI / Anthropic / AI SDK / 素朴）由适配层统一翻译，组件不认识任何 provider。
4. **状态机是唯一语言**：所有 AI 条目共享 7 态，语义色与动画全库一致。
5. 遵守库全部既有纪律：token 消费 / `.is-*` 状态 / aria 等价 / SSR 守卫 / 幂等 init / 禁 innerHTML（SVG 走 `svgIcon()` 消毒解析）/ 事件 `icen:ai-*` 前缀 / 浮层 z 标尺。

## 1. 状态机（一切 AI 条目共享）

```
pending → running → streaming → done
   │          │          │
   └→ approval（待人确认，HITL）   ├→ error
   └→ cancelled ←──────────┘
```

| 状态 | 类 | 视觉 |
|---|---|---|
| 等待 | `.is-pending` | faint 空心点 |
| 执行中 | `.is-running` | accent 脉冲点 |
| 流式中 | `.is-streaming` | 流式光标（▍闪烁，`animate-blink` 复用） |
| 待人确认 | `.is-approval` | warning 色 + 内联 允许/拒绝 按钮 |
| 完成 | `.is-done` | success 对勾 |
| 失败 | `.is-error` | error 色，失败条目**自动展开**（Copilot 模式） |
| 已取消 | `.is-cancelled` | faint + 删除线标题 |

协议映射：AI SDK `input-streaming/input-available`→pending、`approval-requested`→approval、`output-available`→done、`output-error`→error；AG-UI `TOOL_CALL_RESULT`→done、`outcome.interrupt`→approval；A2A `INPUT_REQUIRED/AUTH_REQUIRED`→approval、`WORKING`→running、终态→done/error/cancelled。

## 2. 条目基元 `.ai-item`（CSS 骨架，所有行式条目的"基类"）

```html
<div class="ai-item is-running" style="--ai-item-tint: var(--token-accent)">
  <span class="ai-item-icon"><!-- svg --></span>
  <div class="ai-item-main">
    <div class="ai-item-title">一行摘要</div>
    <div class="ai-item-sub">次要信息（路径/参数）</div>
  </div>
  <div class="ai-item-side">
    <span class="ai-item-status"></span>   <!-- 状态点，纯 CSS 由 .is-* 驱动 -->
    <span class="ai-item-meta">1.2s</span>
  </div>
  <div class="ai-item-detail" hidden>展开详情</div>
</div>
```

局部变量：`--ai-item-tint`（图标/状态点着色槽，默认 accent）。状态点 `.ai-item-status` 是纯 CSS 圆点，由 `.is-*` 决定颜色与动效（running 脉冲用 `--pill-pulse-duration` 同款变量化时长）。

## 3. 文件与 slug 组织

### CSS（4 个文件，MERGED_CSS 登记）

| 文件 | 服务 slug |
|---|---|
| `src/components/ai-chat.css` | `ai-chat` `ai-message` `ai-reasoning` `ai-composer` |
| `src/components/ai-tool.css` | `ai-tool-call` `ai-subagent` |
| `src/components/ai-diff.css` | `ai-diff` `ai-files` |
| `src/components/ai-panel.css` | `ai-todo` `ai-context` `ai-usage` |

### Behaviors（6 个文件，index.ts 全部 `export *`）

| 文件 | 导出 |
|---|---|
| `src/behaviors/ai-core.ts` | 状态机 / 注册表 / 适配器 / 格式化 / svgIcon（见 §6） |
| `src/behaviors/ai-chat.ts` | `initAiChat` `createAiStream` |
| `src/behaviors/ai-composer.ts` | `initAiComposer` |
| `src/behaviors/ai-tool.ts` | `initAiTool` `initAiSubagent` `renderAiToolCall` `renderAiSubagent` |
| `src/behaviors/ai-diff.ts` | `initAiDiff` `renderAiDiff` `parseUnifiedDiff` |
| `src/behaviors/ai-panel.ts` | `initAiTodo` `renderAiTodo` `initAiContext` `renderAiContext` `renderAiUsage` |

### slugs.mjs 登记（S4 执行）

- SLUGS 追加 11 个（新分组「AI」）：`ai-chat, ai-message, ai-reasoning, ai-composer, ai-tool-call, ai-subagent, ai-diff, ai-files, ai-todo, ai-context, ai-usage`
- MERGED_CSS：ai-message/ai-reasoning/ai-composer→`ai-chat.css`；ai-subagent→`ai-tool.css`；ai-files→`ai-diff.css`；ai-todo/ai-context/ai-usage→`ai-panel.css`
- SLUG_INIT：ai-chat→initAiChat, ai-composer→initAiComposer, ai-tool-call→initAiTool, ai-subagent→initAiSubagent, ai-diff→initAiDiff, ai-todo→initAiTodo, ai-context→initAiContext
- SLUG_BEHAVIOR：ai-message→ai-chat, ai-reasoning→ai-chat, ai-files→ai-diff, ai-usage→ai-panel（纯渲染/函数式的挂对应模块）
- SLUG_EXPORTS：ai-message/ai-reasoning→['createAiStream'] 等按实际补；函数式 slug 给渲染函数提示

## 4. 组件契约（类名固定，施工中不得改名）

### 4.1 ai-chat（ai-chat.css + ai-chat.ts）

```html
<div class="ai-chat" data-density="normal">   <!-- verbose|normal|summary 透明度三档 -->
  <div class="ai-chat-scroll">
    <div class="ai-msg ai-msg--user | ai-msg--assistant | ai-msg--system | ai-msg--tool">
      <span class="ai-msg-avatar"></span>
      <div class="ai-msg-body">…内容（消费方可自行渲染 markdown）…</div>
      <div class="ai-msg-actions"><button data-ai-msg-action="copy">…<button data-ai-msg-action="retry">…</div>
      <div class="ai-msg-meta">12:04 · 1.2k tok</div>
    </div>
  </div>
  <button class="ai-chat-jump" hidden>回到底部 · 3 条新消息</button>
</div>
```

- `initAiChat(root?)`：幂等（`__icenAiChatInit`）。滚动钉底：scroll 监听，贴底时自动跟随新内容（监听 scroll 容器尺寸变化用 ResizeObserver）；用户上滚暂停跟随并显示 `.ai-chat-jump`（带未读计数），点击回底恢复。消息动作委托：copy→复制正文+派 `icen:ai-copy`；retry→派 `icen:ai-retry`（detail 含消息元素）。reasoning 折叠委托也在这里（`.ai-reasoning-head` 点击切换）。
- `createAiStream(el)` → `{ append(text), done(), cancel(), fail(message?) }`：textContent 级追加（不解析 HTML），追加期间宿主挂 `.is-streaming`，done/cancel 移除；`fail()` 终止流并给宿主挂 `.is-error`（错误路径，append 之后失效）。Markdown 重渲染是消费方职责（文档里写明）。
- `renderAiMessage(scrollEl, model)` → `{ el, body, setMeta, setError, stream() }`：DOM API 构建整条消息（含多模态部件渲染，见 §10），返回句柄；`stream()` 在正文末尾开 `createAiStream`。model：

```ts
interface AiMessageModel {
  role: 'user' | 'assistant' | 'system' | 'tool';
  content: AiContent;            // string | AiContentPart[]（§10）
  meta?: string;                 // "12:04 · 1.2k tok"
  model?: string;                // assistant 消息的模型名标签
  error?: string;                // → .ai-msg--error + 错误文本行
  streaming?: boolean;           // 初始即流式态
}
```

### 4.2 ai-message / ai-reasoning（ai-chat.css 一族）

```html
<div class="ai-reasoning is-done">
  <button class="ai-reasoning-head" aria-expanded="false">
    <span class="ai-reasoning-label">思考过程</span><span class="ai-reasoning-time">3s</span>
  </button>
  <div class="ai-reasoning-body" hidden>…</div>
</div>
```

流式中 `.is-streaming`：head 显示 shimmer「正在思考…」（动画时长走 `--ai-shimmer-duration` 局部变量）；完成自动折叠并显示耗时。**新 behavior 复用 ai-chat 的委托，不独立 init。**

### 4.3 ai-composer（ai-chat.css + ai-composer.ts）

```html
<div class="ai-composer" data-ai-composer>
  <div class="ai-composer-queue" hidden><!-- 排队消息 chips，可逐个 × --></div>
  <div class="ai-composer-attach" hidden><!-- 附件 chips --></div>
  <div class="ai-composer-box control">
    <textarea class="ai-composer-input" rows="1" placeholder="…"></textarea>
    <div class="ai-composer-actions">
      <button class="ai-composer-btn" data-ai-attach aria-label="附件"></button>
      <button class="ai-composer-send" data-ai-send></button>  <!-- 运行态变 .is-stop 停止钮 -->
    </div>
  </div>
</div>
```

- `initAiComposer(root?)`：autosize（上限 ~8 行后内滚）；Enter 发送 / Shift+Enter 换行 / IME 组合态安全（复用 input.ts 模式）；发送派 `icen:ai-send {text}` 并清空。
- **运行/停止态**：`setComposerRunning(el, bool)` 导出——运行中发送钮变停止钮（点击派 `icen:ai-stop`），此时输入不丢：回车转为入队（queue chip）并派 `icen:ai-queue {text}`；chip × 移除派 `icen:ai-dequeue {index}`。（queue / steer / stop 三动词分化，对齐 Cursor/Copilot 2026 模式）
- 附件钮打开 file input，选中文件生成 chip，派 `icen:ai-attach {files}`。

### 4.4 ai-tool-call（ai-tool.css + ai-tool.ts）

```html
<div class="ai-tool ai-tool--shell is-done">   <!-- kind 修饰类：--shell/--read/--edit/… -->
  <button class="ai-tool-head" aria-expanded="false">
    <span class="ai-item-icon"></span>
    <span class="ai-item-main"><span class="ai-item-title">Read</span>
      <span class="ai-item-sub">src/foo.ts:1-50</span></span>
    <span class="ai-item-status"></span>
    <span class="ai-item-meta">0.4s</span>
  </button>
  <div class="ai-tool-body" hidden>
    <div class="ai-tool-io"><div class="ai-tool-io-label">输入</div><pre class="ai-tool-io-content">…</pre></div>
    <div class="ai-tool-io"><div class="ai-tool-io-label">输出</div><pre class="ai-tool-io-content">…</pre></div>
    <div class="ai-tool-approval">   <!-- 仅 .is-approval 显示 -->
      <button class="btn btn-sm btn-primary" data-ai-approve>允许</button>
      <button class="btn btn-sm" data-ai-reject>拒绝</button>
    </div>
  </div>
</div>
```

- `initAiTool(root?)`：委托展开/折叠（head click + 键盘）；**默认展开集**（spec §4.4.1）首渲染自动展开；approval 按钮派 `icen:ai-approve` / `icen:ai-reject`（detail `{id, kind}`）。
- **默认展开集 §4.4.1（一切 AI 渲染物可折叠，默认态按「是否必须立刻看见」定）**：`chart` kind（数据可视化）/ `error`（Copilot 模式）/ `approval`（待人操作按钮必须可见）/ 多模态回执（output 含 image/video/audio 部件）→ 展开；其余 kind（shell/read/edit/write/rm/grep/glob/mcp/skill/todo/plan/subagent…）→ 折叠只露一行摘要。**用户手动切换后（data-ai-user-toggled）默认策略不再干预**；`update(patch)` 流转中新状态命中展开集仍会展开。
- `renderAiToolCall(el, model: AiToolCallModel)`：DOM API 构建整卡（流式场景用），返回 `{ el, update(patch) }`。
- kind 视觉：`ai-tool--<kind>` 覆盖 `--ai-item-tint` 与图标（注册表驱动）。内置 kinds：`shell read edit write rm grep glob browser search fetch mcp skill todo plan subagent note`。
- 展开动画：grid-template-rows 0fr→1fr 或 max-height 之外，用 `hidden` + 入场 `icen-pop-in`（简单可靠）。

### 4.5 ai-subagent（ai-tool.css + ai-tool.ts）

```html
<div class="ai-subagent is-running">
  <button class="ai-subagent-head" aria-expanded="false">
    <span class="ai-item-icon"></span>
    <span class="ai-item-main"><span class="ai-item-title">explore</span>
      <span class="ai-item-sub">搜索 auth 模块的所有入口</span></span>
    <span class="ai-item-status"></span>
    <span class="ai-item-meta">12.3s · 4 步</span>
  </button>
  <div class="ai-subagent-body" hidden>
    <div class="ai-subagent-stream"><!-- 嵌套 .ai-item / .ai-tool / .ai-reasoning 活动流 --></div>
    <div class="ai-subagent-result">完成回执摘要</div>
  </div>
</div>
```

- 嵌套流用**缩进 + 左侧引导线**表达层级（CSS 伪元素），可再嵌套子代理（递归）。
- `renderAiSubagent(el, model)`：model 含 `activities: AiToolCallModel[]`（复用 renderAiToolCall 渲染嵌套项——递归复用即"继承"）。
- 交互：点击 head 展开看细节（**用户明确要求比 kimi/codex 更优雅**——展开时活动项逐条 `icen-pop-in` 渐入）。

### 4.6 ai-diff（ai-diff.css + ai-diff.ts）

```html
<div class="ai-diff">
  <div class="ai-diff-file is-modified">   <!-- is-added/is-modified/is-deleted/is-renamed -->
    <div class="ai-diff-head">
      <span class="ai-diff-path">src/foo.ts</span>
      <span class="ai-diff-stat"><b class="ai-diff-add">+12</b> <b class="ai-diff-del">−4</b></span>
      <span class="ai-diff-actions">
        <button data-ai-diff-accept>接受</button><button data-ai-diff-reject>拒绝</button>
      </span>
    </div>
    <div class="ai-diff-body" hidden>
      <table class="ai-diff-table">
        <tr class="ai-diff-line--hunk"><td colspan="3">@@ -10,6 +10,8 @@</td></tr>
        <tr class="ai-diff-line--ctx"><td class="ai-diff-ln">10</td><td class="ai-diff-ln">10</td><td class="ai-diff-code">…</td></tr>
        <tr class="ai-diff-line--add">…</tr>
        <tr class="ai-diff-line--del">…</tr>
      </table>
    </div>
  </div>
</div>
```

- `parseUnifiedDiff(text)` → 结构化 hunks（纯函数，SSR 安全）；`renderAiDiff(el, {files})` DOM API 渲染（文本全 textContent）。
- `initAiDiff(root?)`：文件展开/折叠委托；accept/reject 派 `icen:ai-diff-accept` / `icen:ai-diff-reject`（detail `{path}`），点击后该文件标记 `.is-accepted` / `.is-rejected`。
- 长 diff 默认折叠只露 head；`.ai-diff--inline` 变体支持内联并排？——不做并排，保持 unified 单栏（范围控制）。

### 4.7 ai-files（ai-diff.css 一族，纯 CSS）

```html
<div class="ai-files">
  <span class="ai-file-chip is-added"><span class="ai-file-icon"></span>src/foo.ts</span>
</div>
```

chip 态：`is-added/is-modified/is-deleted` + hover 操作（可选）。无 behavior（文档说明）。

### 4.8a 输入框实时待办（setComposerTodo，业界模式）

待办是**工具调用**（对话里只留折叠的 TodoWrite 卡，todo kind summarize 显示 x/y 完成），
**实时状态挂在输入区**而非对话流：`setComposerTodo(el, items | null)` 在工具条渲染
`.ai-composer-todo` chip（清单图标 + x/y；进行中 accent / 全部完成 success / 有失败
warning），点击弹层展示完整清单（popover + renderAiTodo 只读）；传 null 清除。

### 4.8 ai-todo（ai-panel.css + ai-panel.ts）

```html
<div class="ai-todo">
  <div class="ai-todo-head"><span class="ai-todo-progress">2/5</span><div class="ai-todo-bar"><i style="width:40%"></i></div></div>
  <div class="ai-todo-item is-running">
    <span class="ai-item-status"></span>
    <span class="ai-todo-text">实现登录页</span>
    <span class="ai-todo-active">正在实现登录页…</span>  <!-- activeForm：运行中替换文案（Claude Code 模式） -->
  </div>
</div>
```

- `renderAiTodo(el, items)`：`items: {content, status: AiStatus, activeForm?}[]`；`initAiTodo(root?)`：`data-ai-todo-interactive` 时可点击循环状态并派 `icen:ai-todo-toggle {index, status}`；默认只读。
- 进度条用 feedback 的 progress 视觉（token 消费）。

### 4.9 ai-usage（ai-panel.css + ai-panel.ts）

```html
<div class="ai-usage">
  <div class="ai-usage-bar">
    <i class="ai-usage-seg ai-usage-seg--input" style="width:35%"></i>
    <i class="ai-usage-seg ai-usage-seg--cache-read" style="width:20%"></i>
    <i class="ai-usage-seg ai-usage-seg--cache-write" style="width:5%"></i>
    <i class="ai-usage-seg ai-usage-seg--reasoning" style="width:10%"></i>
    <i class="ai-usage-seg ai-usage-seg--output" style="width:12%"></i>
  </div>
  <div class="ai-usage-legend"><!-- 各段色点+数值；缓存分列（计费诚实） --></div>
  <div class="ai-usage-total">82k / 200k · 41%</div>
</div>
```

- `renderAiUsage(el, usage: AiUsage, opts?: { total?: number; cost?: number })`：分段条 + 图例 + 占比；`normalizeUsage` 在 ai-core。
- 配色：input=accent、output=success、cacheRead=info、cacheWrite=warning、reasoning=faint——语义 token。
- **环形形态 `renderAiUsageRing`**（Claude Desktop 式上下文窗口指示器）：紧凑圆环（SVG dasharray，`viewBox 36 / r 15.9155` → 周长恰为 100），中心百分比；点击弹出完整分段分解（弹层为一次性动态 `.popover.ai-usage-popover`，复用 `openPopover`/`closePopover`，anchor 豁免外点关闭，Esc/外点/再点关闭即移除）。状态档：<60% is-ok（accent）/ 60–85% is-warn / >85% is-hot（error + 脉冲）。`--lg` 大号变体。

### 4.10 ai-context（ai-panel.css + ai-panel.ts）—— 右上角资源抽屉

```html
<aside class="ai-context" hidden>
  <div class="ai-context-head"><span>上下文</span><button data-ai-context-close>×</button></div>
  <section class="ai-context-section"><h3>用量</h3><!-- ai-usage --></section>
  <section class="ai-context-section"><h3>文件 (3)</h3><!-- ai-files chips --></section>
  <section class="ai-context-section"><h3>MCP (2)</h3><!-- server 行：名称+状态点+工具数 --></section>
  <section class="ai-context-section"><h3>Skills</h3><!-- skill chip 列表 --></section>
</aside>
```

- `initAiContext(root?)`：触发器 `[data-ai-context-open]` 全局委托开合；抽屉 fixed 右侧滑入（`--z-chrome`），Esc/外点关闭；`.ai-context--inline` 变体为页面流内嵌（不做 fixed）。
- `renderAiContext(el, { usage?, files?, mcpServers?, skills? })`：组合渲染（内部复用 renderAiUsage / ai-files chip / ai-item 行）。
- MCP server 行：`.ai-item` 基元 + `is-done`（已连接）/`is-error`（断开）。

## 5. 事件汇总（全部 bubbles）

| 事件 | detail | 来源 |
|---|---|---|
| `icen:ai-send` | `{text}` | composer 发送 |
| `icen:ai-stop` | `{}` | composer 停止 |
| `icen:ai-queue` / `icen:ai-dequeue` | `{text}` / `{index}` | 排队消息 |
| `icen:ai-attach` | `{files}` | 附件（钮选 / 粘贴 / 拖放共用） |
| `icen:ai-copy` / `icen:ai-retry` | `{el}` | 消息操作 |
| `icen:ai-approve` / `icen:ai-reject` | `{id, kind}` | 工具审批 |
| `icen:ai-diff-accept` / `icen:ai-diff-reject` | `{path}` | diff 审阅 |
| `icen:ai-todo-toggle` | `{index, status}` | 交互 todo |
| `icen:ai-toggle` | `{el, open}` | 通用条目展开/折叠 |
| `icen:ai-model-change` | `{provider, model, label, context}` | 模型切换（§8） |
| `icen:ai-command` | `{name, args}` | 斜杠命令（§8） |
| `icen:ai-ref` | `{action:'add'\|'remove', ref}` | @ 引用（§8） |
| `icen:ai-usage` | `AiUsage`（本次请求归一） | client 每次请求完成（§9） |
| `icen:ai-done` | `{status:'ok'\|'error'\|'cancelled', provider, model, stream, usage?, cost?, error?, durationMs, ttftMs?}` | client 每次请求收尾（chat 与 stream 的 finally；绑定层的驱动事件，§11） |
| `icen:ai-audit-clear` | `{}` | renderAiAudit 清除钮（§12） |

## 6. ai-core.ts 契约（S1 实现，其余 slice 消费）

```ts
export type AiStatus = 'pending'|'running'|'streaming'|'approval'|'done'|'error'|'cancelled';
export interface AiUsage { input?; output?; cacheRead?; cacheWrite?; reasoning?; total?; }
export interface AiKindDef { label: string; icon: string; tint?: 'accent'|'success'|'warning'|'error'|'info'|'muted'; summarize?: (input: unknown) => string; }
export interface AiToolCallModel {
  id: string; name: string; kind: string; status: AiStatus;
  input?: unknown; output?: unknown; errorText?: string;
  approval?: { reason?: string }; durationMs?: number; usage?: AiUsage;
  activities?: AiToolCallModel[];   // subagent 嵌套
}
export function aiStatusLabel(s: AiStatus): string;   // 中文：等待/执行中/流式中/待确认/完成/失败/已取消
export function registerAiKind(name: string, def: AiKindDef): void;
export function getAiKind(name: string): AiKindDef;   // 未注册回退 'note'
export function inferKind(toolName: string): string;  // Bash/Shell→shell, Read→read, mcp__*→mcp, 等
export function normalizeToolCall(raw: unknown): AiToolCallModel;  // OpenAI tool_calls 项 / Anthropic tool_use|tool_result block / AI SDK tool-* part / 素朴
export function normalizeUsage(raw: unknown): AiUsage;             // OpenAI usage / Anthropic usage / Gemini usageMetadata / 素朴
export function formatTokens(n: number): string;    // 1234 → "1.2k"
export function formatDuration(ms: number): string; // 1234 → "1.2s"
export function svgIcon(svg: string): SVGElement | null;  // DOMParser 消毒（剥 on* 属性与 script/foreignObject），SSR 返回 null
```

内置 kind 图标：内联 SVG 字符串常量（lucide 风格 24×24 stroke 图标，手写最简路径；terminal/file/file-pen/file-plus/file-trash/search/folder-search/globe/brain/list/bot 等）。

## 7. 施工分工（文件互斥，严禁越界改别的文件）

- **S1**：`src/behaviors/ai-core.ts` `src/behaviors/ai-chat.ts` `src/behaviors/ai-composer.ts` `src/components/ai-chat.css` `src/index.ts`（追加 6 个 ai 行为导出）
- **S2**：`src/behaviors/ai-tool.ts` `src/components/ai-tool.css`
- **S3**：`src/behaviors/ai-diff.ts` `src/behaviors/ai-panel.ts` `src/components/ai-diff.css` `src/components/ai-panel.css`
- **S4**（S1-S3 完成后）：`scripts/slugs.mjs` `site/src/lib/components.ts`（新分组「AI」+ 11 个交互 demo 条目）`AGENTS.md`（追加 AI 组件族约定）`README.md`（组件统计更新）

验证：各自 `bunx tsc --noEmit`（ui/ 根目录；node 需 `export PATH="/e/Env/Node/fnm/node-versions/v22.22.3/installation:$PATH"`）；不跑 `bun run build`（dist 冲突），统一由主代理构建。

---

## 8. ai-composer v2（输入台重做，2026 业界集大成）

结构（自底向上工具条，业界主流形态）：

```html
<div class="ai-composer" data-ai-composer>
  <div class="ai-composer-queue" hidden></div>   <!-- 排队 chips（v1 已有） -->
  <div class="ai-composer-refs" hidden></div>    <!-- @ 引用 chips（分离渲染：textarea 不嵌 chip） -->
  <div class="ai-composer-attach" hidden></div>  <!-- 附件 chips（v1 已有） -->
  <div class="ai-composer-box control">
    <textarea class="ai-composer-input" rows="1"></textarea>
    <div class="ai-composer-toolbar">
      <button class="ai-composer-model" data-ai-model-open>  <!-- 模型切换：provider 图标 + 模型名 + chevron -->
      <span class="ai-composer-spacer"></span>
      <span class="ai-composer-usage" data-ai-usage></span>   <!-- 上下文环挂载点 -->
      <button class="ai-composer-btn" data-ai-attach></button>
      <button class="ai-composer-send" data-ai-send></button>
    </div>
  </div>
</div>
```

新 API（全部可选配置，向后兼容 v1 契约）：

- `setComposerModels(el, providers: AiProviderOption[], current?: {provider, model})`：
  `AiProviderOption = { id, label, icon?, models: { id, label, context? }[] }`。
  工具条出现模型钮；点击开 `.ai-composer-popup`（portal body，`computePopoverLayout` side:top）——
  按 provider 分组（图标+名）+ 模型行（label + 上下文窗口如 `1M`）+ 搜索过滤 + 当前勾选。
  选择派 `icen:ai-model-change { provider, model, label, context }`；
  **切换时若 cacheRead 占比高则弹层内提示"换模型会使 prompt 缓存失效"**（Kimi Code 细节）。
  选中模型的 `context` 自动作为 `setComposerUsage` 的 total 默认值（闭环）。
- `setComposerCommands(el, commands: { name, description?, argsHint? }[])`：
  输入开头为 `/` 时弹层过滤；↑↓ 导航、Enter/Tab 选中、Esc 关；选中派 `icen:ai-command { name, args }`
  并清空输入（命令被拦截执行、不进消息流——业界共识）。
- `setComposerRefs(el, sources: { kind: 'file'|'folder'|'doc'|'agent', id, label, sub? }[])`：
  任意位置输入 `@` 触发弹层（分组按 kind + 图标）；选中后文本插入 `@label ` 且 refs chip 行 +1，
  派 `icen:ai-ref { action: 'add', ref }`；chip × 移除（同时删文本里首个 `@label`）派 `{ action: 'remove' }`。
- `setComposerUsage(el, usage, opts)`：工具条右侧挂 `renderAiUsageRing`。
- 历史：输入为空时按 `↑` 取回上一条已发送文本（会话内历史数组，每 composer 独立）。
- 运行态（v1 已有 queue/stop）补充：运行中按 `↑` 把最后一条排队消息取回输入框重新编辑（Claude Code 模式）。
- 弹层接管时键盘事件 preventDefault；IME 组合态安全（沿用 v1）。
- 图标对齐修复：工具条按钮统一 28px 方形、svg 14px 居中、gap 走 density token。

事件新增：`icen:ai-model-change` / `icen:ai-command` / `icen:ai-ref`（全 bubbles）。

## 9. ai-provider（provider 适配层：填入 key 即工作）

新文件 `src/behaviors/ai-provider.ts`（index.ts export）。调研依据：五家官方文档 + Vercel AI SDK openai-compatible 架构 + LiteLLM 映射思路。

### 9.1 注册表

```ts
export interface AiProviderModel { id: string; label: string; context?: number; outputLimit?: number; }
export interface AiProviderDef {
  id: string; label: string; icon: string;       // icon: 单色 svg 字母章（svgIcon 消毒）
  baseURL: string;                                // 默认，可覆盖（自定义 BaseURL 是一等公民）
  chatPath: string;                               // /chat/completions | /messages
  wire: 'openai' | 'anthropic';
  auth: 'bearer' | 'x-api-key';
  extraHeaders?: Record<string, string>;          // 如 anthropic-version / dangerous-direct-browser-access
  models: AiProviderModel[];
  /** 浏览器直连 CORS：'yes'（Anthropic 官方支持）/ 'no'（OpenAI 官方禁止）/ 'unknown'（DeepSeek/GLM/Kimi 无承诺，建议代理） */
  browserDirect: 'yes' | 'no' | 'unknown';
}
export function registerAiProvider(def: AiProviderDef): void;   // 第三方/自建网关注册入口
export function getAiProvider(id: string): AiProviderDef | undefined;
export function listAiProviders(): AiProviderDef[];
```

内置五家（2026-10 调研值）：
- openai：`https://api.openai.com/v1`，wire openai，browserDirect 'no'；模型 gpt-5 / gpt-5-mini / gpt-5.1 / gpt-5.5 等
- claude：`https://api.anthropic.com/v1`，wire anthropic，browserDirect 'yes'（自动带 anthropic-version + anthropic-dangerous-direct-browser-access）；claude-opus-5-5 / claude-sonnet-5-5 / claude-fable-5-1 / claude-haiku-4-5
- deepseek：`https://api.deepseek.com/v1`，wire openai，'unknown'；deepseek-flash / deepseek-v4-pro（1M ctx）
- glm：`https://open.bigmodel.cn/api/paas/v4`，wire openai，'unknown'（API key 直接当 Bearer；JWT 可选不做）；glm-5.3 / glm-5.3-flash / glm-5.2 / glm-4.6
- kimi：`https://api.moonshot.cn/v1`，wire openai，'unknown'；kimi-k3（1M）/ kimi-k2.7-code / kimi-k2.6

### 9.2 客户端

```ts
createAiClient({
  provider: string,          // 注册表 id
  apiKey: string,
  baseURL?: string,          // 覆盖默认（自定义网关/代理）
  model?: string,            // 默认取 provider.models[0]
  onAudit?: (entry: AiAuditEntry) => void,
  auditor?: AiAuditor,       // 传实例则每次请求自动 log（entry 含 cost/ttftMs，§12）
  fetch?: typeof fetch,      // mock 注入（AI SDK 同款）
}) → {
  chat(req: AiChatRequest): Promise<AiChatResult>;
  stream(req: AiChatRequest): AiStreamSession;   // AsyncIterable<AiStreamChunk> + cancel() + done
  config: 只读当前配置（provider/baseURL/model）
}

AiChatRequest = { messages: AiChatMessage[], model?, temperature?, maxTokens?, signal? }
AiChatMessage = {
  role: 'system' | 'user' | 'assistant' | 'tool';
  content: string | AiContentPart[];   // §10 标准化内容（多模态）
  toolCallId?: string;                 // role 'tool' 时：openai 族映射 tool_call_id；
                                       //   anthropic 族映射为 user 消息的 tool_result block（真回灌）
  cacheControl?: boolean;              // anthropic 族：该消息末块打 cache_control 断点（prompt 缓存
                                       //   一等公民）；openai 族自动缓存，字段忽略
}
AiChatResult  = { text, usage: AiUsage（normalizeUsage 归一）, cost?: number（定价表命中时）, finishReason?, raw? }
AiStreamChunk = { type:'text', delta } | { type:'done' } | { type:'error', message }
```

**多模态传输映射（parts → wire）**：
- openai 族：text → `{type:'text'}`；image → `{type:'image_url',image_url:{url}}`（data 拼回 data URI）；audio → `{type:'input_audio',input_audio:{data,format: mimeType 后缀}}`；file（url 为 file_id 时）→ `{type:'file',file:{file_id}}`；**video → 诚实抛 `AiProviderError{type:'unsupported'}`**（无主流 API 支持）；resource-link → text 部件降级。
- anthropic 族：text → `{type:'text'}`；image → `{type:'image',source}`（url 或 base64）；audio → `{type:'audio',source:{type:'base64'}}`（仅音频模型，官方口径）；file（pdf 等）→ `{type:'document',source}`；video → unsupported；resource-link → text 降级。
- 响应侧 `chat()` 的 content parts 数组（assistant 回图等）→ `result.parts?: AiContentPart[]`（normalizeContentParts 归一），`text` 仍为拼接文本。

- **两族线协议**：openai 族 POST chat/completions（bearer；`stream_options.include_usage` 自动注入——AI SDK 同款）；anthropic 族 POST /messages（x-api-key + 版本头 + 浏览器直连头；`max_tokens` 必填——缺省 4096；system 顶层参数转换）。
- **SSE 解析器两套**：openai 族按空行分隔的 `data:` 帧 + `[DONE]`；anthropic 族 `event:` 分派（text_delta 出文本；usage 取 message_start 的 input + message_delta 的 output，**不 += 累加**）。缓冲按空行切，不按 read 边界。
- **usage 归一**：走 ai-core `normalizeUsage`（已含 OpenAI/Anthropic/GLM details 路径）；本次给 ai-core 补 DeepSeek 顶层 `prompt_cache_hit_tokens`→cacheRead、Kimi 顶层 `cached_tokens`→cacheRead 与 `prompt_tokens_details.cache_write_tokens`→cacheWrite。
- **错误归一**：OpenAI/DeepSeek 同构 `error.{message,type}`；Kimi 无 param/code 自有枚举；GLM 业务码信封；Anthropic 多一层 `type:"error"` 包装——统一抛 `AiProviderError { provider, status, type, message, raw }`。
- **CORS 诚实**：browserDirect 'no'/'unknown' 的 provider 在浏览器直连失败时，错误信息里建议走代理（文档写明，不静默）。

### 9.3 审计（"完美进入 AI 体系"的闭环）

```ts
createAiAuditor({ persist?: string（localStorage key）, max?: number（默认 100，环形） }) → {
  log(entry): void; list(): AiAuditEntry[]; clear(): void;
  summary(): AiUsage;        // 全量聚合 → 直接喂 renderAiUsage / renderAiUsageRing
  byModel(): Record<string, AiUsage>;
}
AiAuditEntry = { id, ts, provider, model, baseURL, stream, status: 'ok'|'error', durationMs, usage?, error? }
```

client 每次请求自动产审计记录（onAudit 回调 + 若传了 auditor 实例则自动 log）。usage 增量事件派 `icen:ai-usage`（detail AiUsage，bubbles，挂 document）——上下文环/用量面板监听即实时更新。

### 9.4 可测试性（补）

`createAiClient` 接受 `fetch?: typeof fetch` 注入（AI SDK 同款）——单测与文档站 demo 用 mock fetch 返回预制 SSE 流，离线可演示全链路（流式文本 + usage + 审计）。

---

## 10. 标准化内容模型 `AiContent`（v0.7.1 新增，ai-core）

> 调研依据（2026-10）：Vercel AI SDK v5 UIMessage parts（text / reasoning / tool-\<name\> 六态 / file{mediaType,url} / source-url / source-document / data-*）、
> MCP 内容类型（TextContent / ImageContent / AudioContent / ResourceLink / EmbeddedResource + structuredContent，全部带 annotations）、
> OpenAI content parts（text / image_url / input_audio / file）、Anthropic content blocks（text / image / document / audio / tool_use / tool_result）。
> 设计目标：**消费方用一套 parts 表达任意输入；渲染组件、估算器、传输层全部只认这一套。**

### 10.1 类型

```ts
export type AiContent = string | AiContentPart[];

export type AiContentPart =
  | { type: 'text'; text: string; state?: 'streaming' | 'done' }   // AI SDK TextUIPart 对齐
  | { type: 'image'; url?: string; data?: string; mimeType?: string; alt?: string }
  | { type: 'audio'; url?: string; data?: string; mimeType?: string }
  | { type: 'video'; url?: string; data?: string; mimeType?: string }
  | { type: 'file';   url?: string; data?: string; mimeType?: string; filename?: string }
  | { type: 'resource-link'; uri: string; name?: string; mimeType?: string }; // MCP ResourceLink
```

约定：`url` 与 `data` 二选一——`data` 为**无前缀 base64** 且必须伴随 `mimeType`；渲染用 `aiContentUrl(part)` 归一（data → `data:<mime>;base64,<data>`）。
video 当前无主流 chat API 支持，属 UI 前瞻位（渲染与估算齐备，传输层诚实报不支持）。

### 10.2 归一化（业界 wire → parts）

```ts
export function normalizeContentParts(raw: unknown): AiContentPart[];
```

一函数覆盖四族来源（逐项探测，非本届即跳过）：
- **OpenAI**：`{type:'text'}` / `{type:'image_url',image_url:{url}}`（data URI 自动拆 data+mimeType）/ `{type:'input_audio',input_audio:{data,format}}` / `{type:'file',file:{file_id}}`（→ file 部件，url 放 file_id）
- **Anthropic**：`{type:'text'}` / `{type:'image'|'document'|'audio', source:{type:'base64',media_type,data} | {type:'url',url}}`（document → file 部件）
- **MCP**：`{type:'text'}` / `{type:'image'|'audio', data, mimeType}` / `{type:'resource_link', uri, name}` / `{type:'resource', resource:{uri, mimeType, blob|text}}`（blob → 对应媒体部件、text → text 部件）
- **素朴**：已是本类型族的原样通过；字符串 → 单 text 部件；未知 type 剔除

`normalizeMcpContent(raw)` 为 MCP 场景别名（同实现，可发现性）；MCP `structuredContent`（JSON）由消费方自行决定序列化为 text 部件。

### 10.3 工具与文本

```ts
export function isAiContentPartArray(v: unknown): v is AiContentPart[];   // 守卫（tool output 多模态探测）
export function contentToText(content: AiContent): string;                // 拼接全部 text 部件（复制/降级传输用）
export function aiContentUrl(part: AiContentPart): string | undefined;    // url 或 data URI（渲染 src）
```

`AiToolCallModel.output` 保持 `unknown`；`renderAiToolCall` 内部用 `isAiContentPartArray` 探测——数组部件渲染媒体/链接，其余保持 JSON `<pre>`（**MCP 回执的多模态呈现零改动打通**）。

### 10.4 估算器

```ts
export function estimateTokens(content: AiContent | AiUsage): number;
```
- 内容启发式（无依赖，业界粗估惯例）：CJK 字符 ×0.6 + 其余字符 ÷4；文件/图片部件按 mimeType 给经验值（image ≈ 1000、audio ≈ 25/秒无时长信息时 1500、video ≈ 300/秒缺省 6000、file 文本类 ≈ 内容未知给 500）。
- 传 `AiUsage` 时直接返回归一 total。

```ts
export function contextEstimate(usage: AiUsage): number;
```
**下一轮上下文估算**（上下文环的正确口径）：`(input??0)+(cacheRead??0)+(cacheWrite??0)+(output??0)`——本次输出会进入下轮输入；reasoning 已计入 output（OpenAI）或单列（Anthropic 计费口径），单列时也加上。**与 `auditor.summary()`（累计计费口径）语义不同，二者不可混喂同一个环**——绑定层（§11）负责选对口径。

---

## 11. 绑定层 `bindComposer`（v0.7.1 新增，ai-composer.ts）

「零接线全链路」的胶水：**事件驱动、消费方拥有传输会话的所有权不变**。绑定层监听 §5 的 `icen:ai-*` 事件把 composer ↔ 消息区 ↔ client ↔ 用量环接成闭环。

```ts
export interface AiComposerBindOpts {
  client?: AiClient;          // 传入即托管对话：send → 用户消息渲染 + running + client.stream
                              //   → assistant 消息 + createAiStream 逐 chunk 追加 → done 收尾
                              //   （错误 → fail + setError；stop → session.cancel；排队消息在
                              //    每轮完成后自动发送下一条）
  messages?: HTMLElement;     // .ai-chat-scroll 或任意消息容器：renderAiMessage 的挂载点（client 模式必填）
  usage?: { from: 'context' | 'billing' | AiAuditor; total?: number };
                              // 环口径：'context'（默认，icen:ai-done 的 contextEstimate——环语义正确）
                              //   | 'billing'（icen:ai-done 的请求 usage 累加——计费视角）
                              //   | 传 auditor 实例则用其 summary()
  running?: boolean;          // 运行态自动管理（默认 true）：icen:ai-send → running；icen:ai-done → 解除
}
export interface AiComposerBinding { unbind(): void }
export function bindComposer(el: HTMLElement, opts?: AiComposerBindOpts): AiComposerBinding;
```

- **client 模式**下 stop 钮绑定 `session.cancel()`；`icen:ai-done` 的 `cost` 自动进环的 `opts.cost` 累计；assistant 消息 meta 自动填 token 数与模型名。
- 不传 client 时是纯状态绑定（send→running、done→解除、环更新），传输仍归消费方——**渐进采用**。
- composer 同时新增：粘贴文件与拖放文件落附件（`icen:ai-attach` 同事件）；`MODEL_CTX` 在选中模型无 `context` 时显式清除（环回退无上限形态）。

---

## 12. 定价与审计闭环（v0.7.1 新增，ai-provider.ts + ai-panel.ts）

### 12.1 定价表（注册表内联，USD / MTok，2026-10 调研近似值）

```ts
export interface AiPricing { input: number; output: number; cacheRead?: number; cacheWrite?: number }
// AiProviderModel 增：pricing?: AiPricing
export function estimateCost(usage: AiUsage, provider: string, model: string): number | undefined;
```

内置值（锚点：Anthropic Opus 5.5 $4/$20、Sonnet 5 $2/$10、Haiku 4.5 $1/$5、Fable $10/$50、缓存读 ~10% 输入价；
GPT-5 $1.25/$10、mini $0.25/$2；DeepSeek V4 Pro ~$0.55/$1.1（峰谷取中）、Flash ~$0.14/$0.28；
GLM-5.x ~$0.5/$3 档；Kimi K3 $3/$15、缓存读 ~$0.3，K2.6 ~$0.95/$3）。cacheWrite 缺省按 input 的 1.25 倍
（Anthropic 5-minute cache write 口径）。**第三方网关注册时自带来价，estimateCost 未命中定价返回 undefined（不猜价）。**

### 12.2 审计增强

- `AiAuditEntry` 增 `ttftMs?: number`（首 token 延迟——stream 在首个 text chunk 记时）与 `cost?: number`（按定价表算出，未命中缺省）。
- `AiAuditor` 增 `totals(): { usage: AiUsage; cost: number; requests: number; errors: number; avgTtftMs?: number }`
  （`summary()` 保留为 usage-only 别名，喂 renderAiUsage 不变）。
- **`renderAiAudit(elm, source, opts?)`**（ai-panel.ts，source 为 `AiAuditor | AiAuditEntry[]`）：
  totals 行（请求数 ok/error · 累计 tokens · 累计成本 · 平均 TTFT）+ byModel 分组行 + 最近请求列表
  （limit 默认 10：状态点 · provider/model · 时长 · TTFT · tokens · 错误行）。清除钮派 `icen:ai-audit-clear`
  （消费方调 `auditor.clear()` 后重渲染）；`opts.onClear` 可替代事件。
- `AiContextModel` 增 `audit?: AiAuditor | AiAuditEntry[]`：上下文抽屉自动出现「审计」节（复用 renderAiAudit 内部件，无清除钮）。
- localStorage 持久化审计在多 tab 下为 last-write-wins：绑定层不自动同步，文档写明（审计以单 tab 会话为准）。

---

## 13. AI 工具体系（v0.8，`src/behaviors/ai-tools.ts`）

> 任何 UI 能力（图表渲染、未来的 diff 应用 / todo 写入……）注册为 **AiToolDef**，
> 模型侧可调用、宿主侧全控。库内置 `render_chart` 一个工具（吃 ChartSpec 纯 JSON）。

### 13.1 注册表

```ts
export interface AiToolDef<TInput = unknown> {
  name: string;                    // 模型侧 function name（snake_case）
  description: string;             // 给模型看的说明
  inputSchema: Record<string, unknown>;  // OpenAI parameters / MCP inputSchema 兼容
  run: (input: TInput, mount: HTMLElement) => unknown;  // 在挂载点上渲染，返回值即工具结果
  present?: 'mount' | 'data';
}
registerAiTool(def) / unregisterAiTool(name) / getAiTool(name) / listAiTools()
```

### 13.2 挂载区（挂不挂 / 挂哪些 / 挂几个——宿主三层控制）

```ts
createAiToolArea(el, { tools?: string[]; max?: number; itemMinHeight?: number }) → AiToolArea
// tools 白名单支持通配 'chart-*'；max 超出 LRU 淘汰最旧挂载
// AiToolArea: { el, count, call(name, input), can(name), setTools, setMax, clear, onChange(fn) }
```

- 三层控制：① 不 import 本模块 = 生态无工具体系（tree-shake）；② area 白名单 + max；
  ③ 运行时 setTools/setMax/clear + unregisterAiTool 全局下架。
- 挂载项结构：`.ai-tools-mount > .ai-tools-item > head（折叠钮 chevron/工具名/时间/×，button，aria-expanded）+ body（工具自渲染，默认展开，head 点击折叠；× 拦截冒泡只做移除）`。
- 事件（bubbles）：`icen:ai-tool-call {name, input, el}` / `icen:ai-tool-result {name, ok, el, error?, count}`
  / `icen:ai-tool-evict {name, el}`。

### 13.3 模型侧导出（agent loop 直接消费）

```ts
aiToolsToOpenAI(names?)   // → chat.completions tools 参数格式
aiToolsToMcp(names?)      // → MCP tools 格式（name/description/inputSchema）
aiToolsManifest(names?)   // → system prompt 能力清单文本
parseAiToolArgs(raw)      // tool_call 参数容错解析（JSON 字符串/对象/坏 JSON→{}）
```

宿主 agent loop 接线：模型回 `render_chart` tool_call → `area.call('render_chart', parseAiToolArgs(args))`。

### 13.4 图表与 AI 族的接缝

- `render_chart` 工具：inputSchema = ChartSpec JSON Schema；run = renderChart（自动选型 /
  容错归一 / 交互事件族 / 可隐藏图例全数继承）。
- **工具回执内嵌图**：`renderAiToolCall` 的 output 为 `{type:'chart', spec}` 信封或裸
  ChartSpec 时，IO 区直接渲染小图（`chartSpecOf` 探测，`.ai-tool-io-chart` 容器）。
- **kind**：ai-core 内置 `chart` kind（折线图标，info tint，summarize 取 title）；
  `inferKind`：工具名含 chart/plot/visualize → 'chart'。


════════════════════════════════════════════════════════
## API 类型面（复杂模块 .d.mts 原文，含全部 JSDoc 约束注释）
════════════════════════════════════════════════════════

以下为 npm 包内 `dist/behaviors/<模块>.d.mts` 的构建期快照——接口/类型/字段约束的唯一真相，
与包内文件同源生成，永不漂移。其余模块类型面更薄，直接读包内同名 .d.mts。

════════════════════════════════════════════════════════
## 组件全表（desc + usage）
════════════════════════════════════════════════════════

### 基础

#### 按钮（btn）

5 变体（默认 / primary / danger / ghost / link）+ 3 尺寸（sm / 默认 / lg）+ 图标钮 + loading spinner + 错误态 + block 通栏。

```ts
<button class="btn">默认</button>
<button class="btn btn-primary">主要</button>
<button class="btn btn-danger">危险</button>
<button class="btn btn-ghost">幽灵</button>
<button class="btn btn-link">链接</button>

<!-- 尺寸 -->
<button class="btn btn-sm">小号</button>
<button class="btn btn-lg">大号</button>

<!-- 图标 -->
<button class="btn btn-primary">
  <svg class="btn-icon-start">…</svg>
  <span class="btn-text">文本</span>
</button>
<button class="btn btn-icon" aria-label="设置"><svg>…</svg></button>

<!-- loading（加 .is-loading + aria-busy） -->
<button class="btn is-loading" aria-busy="true">加载中</button>
```

#### 面板（panel）

白卡片容器（panel）+ 标题栏（panel-title），用于承载一组相关内容。增强：副标题（panel-subtitle）、可折叠（--collapsible + .is-collapsed）、强调变体（--accent）、平面变体（--flat）。

```ts
<div class="panel [--flush] [--accent] [--flat] [--collapsible] [.is-collapsed]">
  <div class="panel-title">
    <div class="panel-title-text">
      <span>标题</span>
      <span class="panel-subtitle">副标题</span>
    </div>
    <div class="panel-title-actions">…</div>
  </div>
  <div class="panel-body">…内容…</div>
  <div class="panel-foot">…底栏…</div>
</div>
```

#### 徽章（pill）

语义色状态徽章，纪律：仅绿 / 黄 / 红 + 品牌 accent。

```ts
<span class="pill pill--success">运行中</span>
<span class="pill pill--warning">降级</span>
<span class="pill pill--error">已停止</span>
```

#### 标签（tag）

中性展示标签（区别于 pill 的状态语义）：可选关闭按钮、选中态、图标、五档语义色与三档尺寸。

```ts
<span class="tag">默认标签</span>
<span class="tag is-selected">筛选条件</span>
<span class="tag tag--accent">品牌色</span>
<span class="tag">
  <span class="tag-label">可移除</span>
  <button class="tag-close" type="button" aria-label="移除">×</button>
</span>
<!-- 语义色：tag--accent/success/warning/error/info；尺寸：tag--sm/lg -->
```

#### 标签页（tabs）

与 behaviors/tabs 配套的 data 契约分区导航——下面是可点击切换的 live demo。

```ts
import { initTabs } from '@icen.ai/ui/behaviors/tabs';
initTabs(); // 激活态挂 .is-active；切换时容器派发 icen:tab-change（detail { tab, panel, index }）
```

#### 指标卡（stat）

stat-grid 自适应网格 + stat-card；支持趋势 delta、图标、交互 hover。增强：横向布局（dashboard 顶栏）、迷你 sparkline 槽、SVG 进度环、加载骨架态。

```ts
<div class="stat-grid [--2|--3|--4]">
  <div class="stat-card [--interactive] [--horizontal] [--sm] [.is-loading]">
    <div class="stat-head">
      <span class="stat-label">标签</span>
      <span class="stat-icon [.icon--success|.icon--warning|.icon--error|.icon--info]">…svg…</span>
    </div>
    <div class="stat-body">
      <div class="stat-num [.stat-num--accent|.stat-num--warning|.stat-num--error|.stat-num--info]">数字</div>
      <div class="stat-delta [.up|.down|.flat]">趋势</div>
    </div>
    <div class="stat-progress">…SVG ring…</div>
  </div>
</div>
```

#### 轻提示（toast）

与 behaviors/toast 配套（toast.css 提供容器与滑入动画）：toast.ok / err / warn。

```ts
import { toast } from '@icen.ai/ui/behaviors/toast';
toast.ok('已保存');
toast.err('保存失败');
toast.warn('配额将尽');
```

#### 工具条（toolbar）

横向承载按钮 / 控件的容器。与 segmented 区别——toolbar 是宽松容器（可分组、可分隔、可换行），segmented 是紧贴互斥分段选择。

```ts
<div class="toolbar [--sm|--lg|--wrap|--elevated|--borderless]">
  <div class="toolbar-group">
    <button class="btn btn-sm">…</button>
    <button class="btn btn-sm">…</button>
  </div>
  <span class="toolbar-separator"></span>
  <span class="toolbar-spacer"></span>
  <span class="toolbar-label">右侧文字</span>
</div>
<!-- 分组 toolbar-group / 分隔符 toolbar-separator / 弹性占位 toolbar-spacer -->
```

#### 分栏拖拽（split-pane）

与 behaviors/split-pane 配套：可拖拽的分栏容器，支持水平 / 垂直方向，双击分隔条复位 50%，键盘 ←→ ↑↓ 调整。

```ts
import { initSplitPane } from '@icen.ai/ui/behaviors/split-pane';
initSplitPane();

<!-- DOM 契约 -->
<div class="split-pane [--vertical]" data-split-pane style="--split:50%; height:400px">
  <div class="split-pane-first">左侧</div>
  <div class="split-pane-divider" role="separator"></div>
  <div class="split-pane-second">右侧</div>
</div>
<!-- data-split-min/max（默认 10/90）、data-split-step（键盘步长，默认 2） -->
```

### 表单

#### 表单布局（form）

字段结构（form / form-field / form-label / form-hint / form-error）+ 裸 form-input / form-textarea + 页面级 banner-ok / banner-err 横幅。与 input.css 的 wrapper 互补：input 处理"单控件外壳"，form 处理"字段→label→hint 的纵向布局"。

```ts
<form class="form">
  <fieldset class="form-field">
    <label class="form-label" for="x">姓名<span class="req">*</span></label>
    <input class="form-input" id="x" />
    <span class="form-hint">辅助提示</span>
    <span class="form-error">错误信息</span>
  </fieldset>
</form>
<!-- form-input 同时支持原生 :invalid 与 [data-invalid=true] 驱动错误态 -->
```

#### 输入框（input）

wrapper 式输入族：三档尺寸，前后缀、清除钮、密码切换、错误/禁用态，含多行与搜索框。增强：字符计数器（maxlength / data-count）、输入掩码（data-mask）、IME 安全、blur 自动 trim。

```ts
import { initInput } from '@icen.ai/ui/behaviors/input';
initInput(); // 清除钮 / 密码切换 / textarea autosize / OTP / 字符计数 / 输入掩码

<!-- 字符计数 -->
<input class="input" maxlength="20" />

<!-- 输入掩码（# 数字 / A 字母 / * 任意） -->
<input class="input" data-mask="###-####-####" placeholder="手机号" />
<input class="input" data-mask="####-####-####-####" placeholder="信用卡" />

<!-- blur 自动去空白 -->
<input class="input" data-trim />
```

#### 选择器（select）

触发器与 input 同视觉；弹层支持 ↑↓ 移动、Enter 选中、Esc / 外点关闭，选中值同步隐藏 input。增强：data-select-search 可搜索过滤、data-select-multiple 多选（逗号分隔）、data-select-max 上限。

```ts
import { initSelect } from '@icen.ai/ui/behaviors/select';
initSelect();

<!-- 基础单选 -->
<div class="select" data-select>…</div>

<!-- 可搜索（带分组） -->
<div class="select" data-select data-select-search>…</div>

<!-- 多选 + 上限 -->
<div class="select" data-select data-select-multiple data-select-max="3">…</div>
<!-- 多选：trigger 内加 .select-clear 清除全部 -->
```

#### 滑块（slider）

透明原生 range 覆盖层驱动填充与滑块；双滑块带选中段与 lo ≤ hi − step 钳制。

```ts
import { initSlider } from '@icen.ai/ui/behaviors/slider';
initSlider();
```

#### 标签输入（tag-input）

Enter / 逗号提交、重复静默清空、空草稿 Backspace 删尾、blur 提交；达到 data-max 边框转 warning 色并拒加。

```ts
import { initTagInput } from '@icen.ai/ui/behaviors/tag-input';
initTagInput();
```

#### 开关与选择（switch）

纯 CSS 状态组件：开关两档尺寸；勾选框三态（未选 / 已选 / 半选）；单选行组排他。

```ts
<button class="switch" type="button" role="switch" aria-checked="false">
  <span class="switch-thumb"></span>
</button>
<!-- 状态由使用方驱动：点击切换 aria-checked，CSS 负责全部视觉 -->
```

#### 分段选择（segmented）

同族四件：分段控件（两档尺寸）、toggle-group、数字步进器、OTP 单元格（输入跳格 / 粘贴分摊）。

```ts
import { initInput } from '@icen.ai/ui/behaviors/input';
initInput(); // OTP 单元格的输入跳格 / 粘贴分摊由 input behavior 处理
// segmented / toggle-group / stepper 为纯 CSS 契约，选中态由使用方切换
```

#### 上传（upload）

点击 / Enter / Space 打开文件选择；拖入高亮，drop 后文件写入 input.files 并派发 change。增强（data-upload-list）：自动渲染文件列表，图片缩略图、大小格式化、单文件移除、accept/max-size/max-files 校验。

```ts
import { initUpload } from '@icen.ai/ui/behaviors/upload';
initUpload();

<!-- 基础上传（无列表） -->
<div class="upload" role="button" tabindex="0">
  <input type="file" multiple />
  …
</div>

<!-- 增强上传（文件列表 + 校验） -->
<div class="upload" data-upload-list data-max-size="5242880" data-max-files="6"
     role="button" tabindex="0">
  <input type="file" multiple accept="image/*,.pdf" />
  …
</div>
<!-- 事件：icen:upload { files } / icen:upload-error { file, reason } / icen:upload-remove { file } -->
```

#### 日期选择（date-picker）

与 behaviors/date-picker 配套：点击触发器弹出日历面板，支持月份导航 / 今日 / 清除 / min-max 限制 / 周首日配置。纯 JS 渲染，零依赖。

```ts
import { initDatePicker } from '@icen.ai/ui/behaviors/date-picker';
initDatePicker();

<div class="date-picker" data-date-picker>
  <button class="date-picker-trigger" type="button">
    <span class="date-picker-value is-empty"></span>
    <span class="date-picker-icon">…日历 svg…</span>
  </button>
  <input type="hidden" name="date" />
</div>
<!-- 可选 data-date-picker-format/min/max/week-start/placeholder -->
```

### 浮层

#### 对话框（modal）

data-modal 契约 + behaviors/modal：焦点陷阱、滚动锁、Esc/遮罩关闭、焦点还原；Sheet 四向贴边滑入。

```ts
import { initModal, open, close } from '@icen.ai/ui/behaviors/modal';
initModal(); // 事件委托一次绑定，后续 open(id) / close(id) 可编程控制
```

#### 下拉菜单（dropdown）

trigger + [data-dropdown-menu] 模板；面板 fixed 定位在 trigger 下方 4px，视口 12px margin 内 clamp，空间不足翻上。

```ts
import { initDropdown } from '@icen.ai/ui/behaviors/dropdown';
initDropdown();
// 面板由 JS portal 到 body；click / ArrowDown 打开，↑↓ 高亮，Enter 激活，Esc / 外点 / 滚动关闭
```

#### 右键菜单（context-menu）

全局单例：registerContextMenu(id, items) 注册，[data-context-menu="id"] 命中；支持 header / separator / danger / disabled，触屏长按触发。

```ts
import { initContextMenu, registerContextMenu } from '@icen.ai/ui/behaviors/context-menu';

registerContextMenu('demo-file', [
  { type: 'header', label: 'report-2026.qmd', description: '文档 · 2.4 MB' },
  { label: '重命名', shortcut: 'F2', onClick: () => toast.ok('重命名') },
  { label: '复制链接', onClick: () => toast.ok('已复制链接') },
  { type: 'separator' },
  { label: '移到回收站', danger: true, shortcut: '⌫', onClick: () => toast.warn('已移到回收站') },
  { label: '高级操作（不可用）', disabled: true },
]);
initContextMenu();
```

#### 浮层（popover）

computePopoverLayout 纯函数选侧（prefer → 翻对侧 → 取大侧）；openPopover 负责 portal、跟随重算与外点/Esc 关闭。

```ts
import { openPopover, closePopover, computePopoverLayout } from '@icen.ai/ui/behaviors/popover';

openPopover(panel, { anchor: trigger, side: 'bottom', align: 'start' });
// panel 移入 body 定位；resize / 捕获 scroll 重算；外点 / Esc 关闭并还原
```

#### 提示（tooltip）

纯 CSS：data-tooltip 文案 + data-tooltip-side 方向；hover 延迟 400ms，键盘 focus-visible 立即出现。

```ts
<!-- 纯 CSS：hover 延迟 400ms 出现，focus-visible 立即出现 -->
<button class="btn" data-tooltip="文案" data-tooltip-side="top">目标</button>
<!-- data-tooltip-side 可选 top | bottom | left | right -->
```

#### 命令面板（command-palette）

与 behaviors/command-palette 配套：⌘K / Ctrl+K 唤起的命令面板，搜索过滤、↑↓ 导航、Enter 执行、ESC 关闭，常用于编辑器 / 后台快速跳转。

```ts
import { initCommandPalette } from '@icen.ai/ui/behaviors/command-palette';
initCommandPalette(); // 全局 ⌘K / Ctrl+K 自动触发

// 命令项可加 data-command-palette-keyword 补充关键字
// 加 data-command-palette-keep-open 执行后不关闭面板
```

### 数据展示

#### 卡片（card）

四变体（默认 / elevated / outlined / glass）+ interactive 浮起 + is-selected 双圈选中。

```ts
<div class="card">
  <div class="card-head"><h3 class="card-title">标题</h3></div>
  <div class="card-body">内容</div>
  <div class="card-foot"><span class="card-meta">元信息</span></div>
</div>
<!-- 变体：card--elevated / card--outlined / card--glass / card--interactive；选中态 .is-selected -->
```

#### 空状态（empty）

图标 + 标题 + 描述 + 可选动作按钮。类型预设：--error / --404 / --search / --maintenance / --network，自动改图标底色与基调。

```ts
<div class="empty [.empty--sm|.empty--lg]
     [.empty--error|.empty--404|.empty--search|.empty--maintenance|.empty--network]
     [.empty--illustrated]">
  <div class="empty-icon">…svg…</div>
  <p class="empty-title">暂无数据</p>
  <p class="empty-desc">描述文字</p>
  <div class="empty-action"><button class="btn btn-primary btn-sm">动作</button></div>
</div>
```

#### 头像（avatar）

xs 20 / sm 28 / 默认 36 / lg 48；文字兜底或 img 填充（object-fit: cover）。

```ts
<span class="avatar">沈</span>
<span class="avatar avatar--lg"><img src="…" alt="名字" /></span>
```

#### 媒体卡（media-card）

2/3 封面（此处用色块代替图片）；hover 上浮 6px + accent 辉光，底部信息条滑出（延迟 80ms）。

```ts
<div class="media-card" style="width:148px">
  <div class="media-card-cover" style="background:…"></div>
  <div class="media-card-overlay">
    <div>标题</div>
    <div>副标题</div>
  </div>
</div>
```

#### 评分（rating）

is-filled 实星 / is-half 半星（warning 色）；另有 rating--sm / rating--lg 尺寸。

```ts
<div class="rating" role="group" aria-label="评分 3.5 星，满分 5 星">
  <button class="rating-star is-filled" type="button" aria-label="1 星">…星形 svg…</button>
  <button class="rating-star is-half" type="button" aria-label="4 星">…星形 svg…</button>
  <button class="rating-star" type="button" aria-label="5 星">…星形 svg…</button>
</div>
<!-- 填充态由使用方按分数挂 .is-filled / .is-half -->
```

#### 键盘键（kbd）

按键帽（含 kbd--sm）与行内代码片 code-inline。

```ts
<kbd class="kbd">Ctrl</kbd> + <kbd class="kbd kbd--sm">K</kbd>
<code class="code-inline">行内代码</code>
```

#### 列表（list）

行间 1px 分隔线 + hover 底色的分隔列表。

```ts
<ul class="list">
  <li class="list-item">条目一</li>
  <li class="list-item">条目二</li>
</ul>
```

#### 折叠面板（accordion）

与 behaviors/accordion 配套；本例容器带 data-single（展开一项自动收起其余）。

```ts
import { initAccordion } from '@icen.ai/ui/behaviors/accordion';
initAccordion();
// 容器带 data-single 时展开一项会收起其余
```

#### 时间线（timeline）

五档语义色圆点 + 连接线，时间右对齐 tabular-nums。

```ts
<div class="timeline">
  <div class="timeline-item">
    <div class="timeline-dot timeline-dot--success">…svg…</div>
    <div class="timeline-body">
      <div class="timeline-head"><span class="timeline-title">标题</span><span class="timeline-time">10:24</span></div>
      <p class="timeline-desc">描述</p>
    </div>
  </div>
</div>
```

#### 描述列表（desc）

desc--bordered 格线列表（--desc-cols 控制列数，--desc-span 跨列）。

```ts
<div class="desc desc--bordered">
  <p class="desc-title">标题</p>
  <dl class="desc-grid" style="--desc-cols:2">
    <div class="desc-item"><dt>键</dt><dd>值</dd></div>
  </dl>
</div>
```

#### 树形（tree）

与 behaviors/tree 配套：三层可折叠 + 叶子单选 + 禁用节点。

```ts
import { initTree } from '@icen.ai/ui/behaviors/tree';
initTree();
// toggle 折叠/展开子 ul；点击叶子节点单选（.is-selected）
```

#### 轮播（carousel）

与 behaviors/carousel 配套：箭头 / 自动圆点 / 循环切换（三张色块幻灯）。

```ts
import { initCarousel } from '@icen.ai/ui/behaviors/carousel';
initCarousel();
// dots 自动生成；首尾循环；当前 dot 挂 .is-active
```

#### 徽标（badge）

角标式徽标：数字计数 / 纯圆点，挂在外层元素的角上（外层需 position: relative）。区别于 pill（行内状态徽章）。

```ts
<span class="badge-host">
  <button class="btn">消息</button>
  <span class="badge">9</span>
</span>
<!-- 纯圆点：badge--dot；语义色：--success/--warning/--error/--accent/--info -->
<!-- 底部角（头像在线点）：badge--bottom；尺寸：badge--sm/lg -->
```

#### 滚动容器（scroll-area）

显式带视觉边界的滚动区。全局已有细薄滚动条（base.css），本组件用于强调"可滚动"或限定方向的场景。

```ts
<div class="scroll-area scroll-area--inset" style="height:200px">
  超长内容…
</div>
<!-- 变体：--sm/--lg（滚动条宽度）/--x/--y/--both（轴向）/--inset（带边界）/--fade（渐隐遮罩）-->
```

#### 表格（table）

table-wrap 负责窄屏横向滚动；行 hover 高亮，ops 列右对齐放 btn-sm。增强：--zebra 斑马纹、caption 标题、--sticky-col 首列粘滞、行状态色（row-success/warning/error）、展开行（row-expand）。

```ts
<div class="table-wrap [--bordered]">
  <table class="table [--zebra] [--compact|--dense] [--sticky-col]">
    <caption class="table-caption">标题</caption>
    <thead><tr><th>名称</th><th class="ops">操作</th></tr></thead>
    <tbody>
      <tr class="row-link [.is-selected] [.row-success|.row-warning|.row-error]">
        <td>gateway</td>
        <td class="ops"><button class="btn btn-sm">编辑</button></td>
      </tr>
    </tbody>
    <tfoot><tr><td>合计</td></tr></tfoot>
  </table>
</div>
```

#### 数据表格（datatable）

createTable 函数式 API：搜索 / 排序 / 筛选 / 多选（Shift 范围选）/ 分页 / 虚拟滚动（万级行）/ 行展开 / 列宽拖拽 / 列显隐 / 冻结列 / CSV 导出 / 行右键。管线缓存，零依赖。

```ts
import { createTable } from '@icen.ai/ui/kit/datatable';

const table = createTable(el, {
  columns: [
    { key: 'name', title: '名称', sortable: true, width: '160px', frozen: true },
    { key: 'status', title: '状态', filterable: true,
      render: (v) => pillNode(v) },            // 返回 Node = 嵌套任意组件
    { key: 'updated', title: '更新', sortable: true },
    { key: 'ops', title: '操作', render: (_v, row) => actionsNode(row) },
  ],
  data: rows,
  rowKey: 'id',                               // 多选/展开跨页保持的依据
  searchable: true,                           // 内置搜索（160ms 防抖）
  selectable: true,                           // 多选 + 表头三态 + Shift 范围选
  pagination: true, pageSize: 10,             // 分页；或 virtual: true 万级行虚拟滚动
  resizable: true,                            // 列宽拖拽（默认开）
  columnVisibility: true,                     // 工具栏列显隐开关
  exportable: true,                           // 工具栏 CSV 导出按钮
  density: 'compact',                         // 紧凑密度（可选）
  rowClassName: (row) => row.status === '已停止' ? 'row-offline' : '',
  expandable: (row) => detailNode(row),       // 行展开（虚拟模式外可用）
  contextMenu: (row) => [                     // 行右键（复用 context-menu，kit 已带 menu.css）
    { label: '重命名', shortcut: 'F2', onClick: () => toast.ok('重命名') },
    { type: 'separator' },
    { label: '停止服务', danger: true, onClick: () => toast.warn('已停止') },
  ],
  onSelectionChange: (rows) => console.log(rows.length),
  onSortChange: (key, dir) => console.log(key, dir),
});

table.setData(next);      // 换数据
table.getData();          // 取当前管线数据（搜索→筛选→排序后）
table.exportCSV('服务列表.csv'); // 导出
table.showColumn('updated');    // 显示列
table.hideColumn('ops');        // 隐藏列
table.destroy();
```

### 反馈

#### 警示（alert）

info / success / warning / error 四态警示条，带关闭按钮（演示 JS 点击移除）。

```ts
<div class="alert alert--success">
  <span class="alert-icon">…svg…</span>
  <div class="alert-content">
    <p class="alert-title">标题</p>
    <div class="alert-body">正文</div>
  </div>
  <button class="alert-close" type="button" aria-label="关闭">×</button>
</div>
```

#### 结果页（result）

终态展示（success 一例；另有 error / warning / info 变体）。

```ts
<div class="result result--success">
  <div class="result-icon">…svg…</div>
  <h3 class="result-title">标题</h3>
  <p class="result-desc">描述</p>
  <div class="result-extra">…动作按钮…</div>
</div>
```

#### 进度条（progress）

默认 6px 轨道 / progress--sm 4px，右侧 tabular-nums 百分比标签。

```ts
<div class="progress">
  <div class="progress-track"><div class="progress-bar" style="width:64%"></div></div>
  <span class="progress-label">64%</span>
</div>
```

#### 加载指示（spinner）

sm 16px / 默认 20px / lg 32px，1s 线性旋转。

```ts
<div class="spinner"></div>
<div class="spinner spinner--sm"></div>
<div class="spinner spinner--lg"></div>
```

#### 骨架屏（skeleton）

呼吸脉冲占位块；skeleton--circle 为圆形。

```ts
<div class="skeleton" style="height:12px;width:80%"></div>
<div class="skeleton skeleton--circle" style="width:40px;height:40px"></div>
```

#### 复制按钮（copy）

与 behaviors/copy 配套：命中 .copy-btn[data-copy] 写入剪贴板，成功后文本变「已复制」1.4s 还原；图标变体加 data-copy-icon 仅切 .is-done 类。与 toast 的区别——copy 是原地反馈，toast 是全局通知。

```ts
import { initCopy } from '@icen.ai/ui/behaviors/copy';
initCopy(); // 委托监听，自动处理所有 .copy-btn[data-copy]
```

#### 通知栈（notification）

与 behaviors/notification 配套：工程级持久通知栈——进度通知、Promise confirm、多按钮、hover 暂停+倒计时进度、优先级置顶、已读未读、自定义图标/头像、详情链接、localStorage 持久化、多容器。与 toast（瞬时）/ alert（内嵌）正交。

```ts
import { notify, createNotificationCenter } from '@icen.ai/ui/behaviors/notification';

// ── 便捷 API ──
notify.success('已发布', { description: '5 分钟后全量生效' });
notify.warn('配额将尽', { description: '已用 80%', duration: 8000 });  // 8s 自动关闭
notify.error('发布失败', { description: '封面图尺寸不足' });

// ── 进度通知（返回 handle，可动态 setProgress）──
const h = notify.progress('正在导出', { progressLabel: '准备中…' });
let p = 0;
const timer = setInterval(() => {
  p += 0.08;
  if (p >= 1) {
    h.setProgress(1, '完成');
    clearInterval(timer);
    setTimeout(() => h.dismiss(), 1500);
  } else {
    h.setProgress(p, '导出中 ' + Math.round(p * 100) + '%');
  }
}, 300);

// ── Promise confirm（阻塞式确认）──
const ok = await notify.confirm('确认删除该作品？', {
  description: '此操作不可撤销，相关数据将被清除。',
  confirmLabel: '删除',
  cancelLabel: '取消',
});
if (ok) { /* 执行删除 */ }

// ── 多按钮 ──
notify.info('评论了你的作品', {
  description: '「很喜欢这段配乐」—— 沈墨',
  avatar: 'https://example.com/u.jpg',
  actions: [
    { label: '回复', type: 'primary', onClick: () => openReply() },
    { label: '忽略', onClick: () => {} },
  ],
  link: '/works/123',
  linkLabel: '查看作品',
});

// ── 高优先级置顶 + 未读 ──
notify.error('服务中断', {
  description: 'gateway-001 不可达，已自动切换备用节点',
  priority: 'high',
  unread: true,
});

// ── Handle 方法 ──
h.update({ title: '新标题', description: '更新后' });
h.markRead();
h.pause(); h.resume();
h.dismiss();
notify.markRead();        // 全部已读
notify.clear();           // 全清
notify.get(id);           // 读取
notify.getAll();          // 全部

// ── 多容器（独立位置与配置）──
const center = createNotificationCenter(document.body, {
  position: 'bottom-right',
  maxStack: 3,
  persist: 'app:messages',
});
center.push({ title: '新消息', kind: 'info', options: { description: '…' } });
center.markAllRead();
center.clear();

// ── 全局配置 ──
notify.config({ position: 'top-right', maxStack: 5, pauseOnHover: true });
```

### 图表

#### 图表总览（charts）

零依赖纯 SVG/DOM 渲染（无 ECharts）——12 种图表 + 通用层。renderChart 统一入口吃一份纯 JSON 规格（ChartSpec）：type 缺省自动推断、data[] + dims 任意维度透视、内置 tooltip、icen:chart-hover/click/dblclick/contextmenu 交互事件族、图例点击切换系列。下方 demo 可切换图型并实时看事件日志；实际使用请按需安装细分类型（kit/chart-line 等）。

```ts
// ── 通用层（推荐；纯 JSON 规格，AI 调用层同构）──
import { renderChart } from '@icen.ai/ui/behaviors/charts';

const handle = renderChart(el, {
  title: '一周活跃',
  labels: ['周一', '周二', '周三', '周四', '周五', '周六', '周日'],
  series: [
    { name: 'Web', values: [8, 14, 9, 18, 22, 16, 25] },
    { name: 'CLI', values: [3, 5, 4, 8, 6, 11, 9] },
  ],
  format: { notation: 'compact', unit: '次' },
  // type 缺省自动推断（时间序→line / 占比→donut / dates→calendar / points→scatter…）
  // tooltip: false 关闭内置提示；stacked: true 堆叠柱；legend: false 初始隐藏图例
});
handle.on 右侧小眼睛随时切换（icen:chart-legend-visibility）。

handle.on('click', (d) => console.log(d.label, d.value, d.seriesName));
handle.on('contextmenu', (d, e) => openContextMenu(e, d));  // 右键接自家 context-menu
handle.update(nextSpec);   // 原地重渲染（事件委托保留）

// 任意维度原始记录 + 字段映射（pivot 成 类目 × 系列）
renderChart(el, {
  data: [{ 城市: '北京', 渠道: '直营', 销量: 120 }, /* … */],
  dims: { label: '城市', series: '渠道', value: '销量' },
});

// 容错归一（LLM/外部输入友好）：'bar'→vbar、'pie'→donut、字符串数字、JSON 字符串
import { normalizeChartSpec, inferChartType } from '@icen.ai/ui/behaviors/charts';

// ── 底层渲染器（按需安装细分类型 kit/chart-line 等，只引需要的 CSS + JS）──
import { renderHeatmap, renderCalendar, renderScatter } from '@icen.ai/ui/behaviors/charts';
renderHeatmap(el, { values: 近180天数值数组, weeks: 26 });        // 周格热力
renderCalendar(el, { dates: ['2026-07-01', /* … */], values: [5, /* … */] }); // 贡献日历（月份标签）
renderScatter(el, { points: [{ x: 1, y: 2, size: 30, label: 'A' }] }); // 散点/气泡
```

#### 折线图（chart-line）

面积渐变 + 网格 + 数据点的折线趋势图；series 多系列走调色盘 + 可切换图例（点击图例行显隐系列）。独立安装：只引这一份 CSS + renderLine。

```ts
import '@icen.ai/ui/kit/chart-line';
import { renderLine } from '@icen.ai/ui/kit/chart-line';

renderLine(el, { labels: ['周一','周二','周三','周四','周五','周六','周日'], values: [8, 14, 9, 18, 22, 16, 25] });

// 多系列（调色盘自动分配 + 可切换图例）
renderLine(el, {
  labels: ['周一', '周日…'],
  series: [
    { name: 'Web', values: [8, /* … */] },
    { name: 'CLI', values: [3, /* … */] },
  ],
});
```

#### 柱状图（chart-bar）

renderVBar 垂直柱状 + renderHBar 水平条形两种形态，同一 kit 入口。

```ts
import { renderVBar, renderHBar } from '@icen.ai/ui/kit/chart-bar';

renderVBar(el,  { labels: ['一月','二月'], values: [12, 19] });
renderHBar(el,  { labels: ['搜索','直接'], values: [320, 80], tone: 'success' });
```

#### 饼图（chart-pie）

环形分割图（renderDonut）+ 图例百分比。支持多段、自定义色调与格式化。

```ts
import { renderDonut } from '@icen.ai/ui/kit/chart-pie';

renderDonut(el, {
  segments: [
    { label: '研发', value: 48 },
    { label: '设计', value: 32, tone: 'success' },
    { label: '测试', value: 20, tone: 'warning' },
  ],
});
```

#### 雷达图（chart-radar）

N 轴蛛网雷达图（renderRadar），支持多系列叠加对比 + 图例。

```ts
import { renderRadar } from '@icen.ai/ui/kit/chart-radar';

renderRadar(el, {
  axes: ['攻击', '防御', '速度', '技巧', '魔法', '运气'],
  series: [
    { name: '战士', values: [9, 8, 5, 6, 2, 5] },
    { name: '法师', values: [3, 4, 6, 7, 9, 6], tone: 'success' },
  ],
});
```

#### 热力图（chart-heatmap）

GitHub 式贡献图热力格（renderHeatmap）：7 行 × N 周，5 档色阶。支持精确日期或便捷数组。

```ts
import { renderHeatmap } from '@icen.ai/ui/kit/chart-heatmap';

renderHeatmap(el, { values: 近180天数值数组, weeks: 26 });       // 便捷形态
renderHeatmap(el, { data: [{ date: '2026-07-01', value: 5 }] }); // 精确日期形态
```

#### 面积图（chart-area）

以面积填充为主体的趋势图（renderArea），与折线同族但视觉更厚重。

```ts
import { renderArea } from '@icen.ai/ui/kit/chart-area';

renderArea(el, {
  labels: ['Q1', 'Q2', 'Q3', 'Q4'],
  values: [120, 180, 150, 210],
  tone: 'success',
});
```

#### 堆叠条（chart-stack）

100% 堆叠条形图（renderStack），展示各部分占比 + 图例。

```ts
import { renderStack } from '@icen.ai/ui/kit/chart-stack';

renderStack(el, {
  segments: [
    { label: '已完成', value: 45, tone: 'success' },
    { label: '进行中', value: 30 },
    { label: '待处理', value: 25, tone: 'warning' },
  ],
});
```

#### 仪表盘（chart-gauge）

环形单值仪表盘（renderGauge），中心显示百分比，适合 KPI 完成率。

```ts
import { renderGauge } from '@icen.ai/ui/kit/chart-gauge';

renderGauge(el, { value: 64, label: '完成率' });
```

#### 迷你趋势（chart-sparkline）

无轴迷你趋势线（renderSparkline），嵌入指标卡 / 表格单元格的利器。

```ts
import { renderSparkline } from '@icen.ai/ui/kit/chart-sparkline';

renderSparkline(el, { values: [4, 7, 5, 9, 6, 11, 8, 13, 10, 15] });
```

#### 散点气泡（chart-scatter）

散点/气泡图（renderScatter）：坐标域自动 nice 取整 + 边界刻度；points 的 size 为第三维时映射气泡半径 3–10。数据点带交互标记（hover/单击/双击/右键走 renderChart 通用层）。

```ts
import { renderScatter } from '@icen.ai/ui/kit/chart-scatter';

renderScatter(el, {
  points: [
    { x: 3.2, y: 48, size: 12, label: 'web' },
    { x: 5.1, y: 72, size: 30, label: 'cli' },
  ],
  tone: 'accent',
});
// 交互：配 renderChart 走通用层（tooltip + icen:chart-* 事件族）
import { renderChart } from '@icen.ai/ui/behaviors/charts';
renderChart(el, { type: 'scatter', points: [/* 同上 */] }).on('click', (d) => { /* d.label / d.value */ });
```

#### 贡献日历（chart-calendar）

贡献日历（renderCalendar，GitHub 提交图同款）：dates + values 自动按周布局，月份标签 + 星期列 + 5 档色阶图例。周格热力（renderHeatmap）的日历完整形态。

```ts
import { renderCalendar } from '@icen.ai/ui/kit/chart-calendar';

renderCalendar(el, {
  dates: ['2026-06-01', '2026-06-02', /* … */],   // ISO 日期（旧 → 新）
  values: [5, 12, /* … */],                        // 与 dates 配对
});
// 或精确形态 data: [{ date, value }[]]；色阶 tone 可覆盖
// 交互：配 renderChart({ type: 'calendar', dates, values }) 走通用层
```

### 导航

#### 顶栏（nav）

三段式玻璃顶栏（左 / 中 / 右）+ pill 导航钮；data-scroll-reactive 时滚动超过 12px 切 .is-scrolled。

```ts
import { initNav } from '@icen.ai/ui/behaviors/nav';
initNav(); // scrollY > 12 时给 .nav[data-scroll-reactive] 加 .is-scrolled
```

#### 侧栏（sidebar）

分组可折叠（grid 0fr↔1fr 动画，chevron 随开合旋转），条目支持图标与 .is-active。

```ts
import { initSidebar } from '@icen.ai/ui/behaviors/sidebar';
initSidebar(); // 点击 .sidebar-group-title 切父 group 的 .is-open + aria-expanded
```

#### 面包屑（breadcrumb）

分隔符由 .breadcrumb-sep 的 ::after（›）提供；当前页挂 aria-current="page"。

```ts
<nav class="breadcrumb" aria-label="面包屑">
  <ol>
    <li><a class="breadcrumb-link" href="/">首页</a><span class="breadcrumb-sep" aria-hidden="true"></span></li>
    <li><span class="breadcrumb-current" aria-current="page">当前页</span></li>
  </ol>
</nav>
```

#### 分页（pagination）

纯样式契约（翻页逻辑归消费方）：1 … 4 [5] 6 … 12 静态演示，含禁用态与省略号。

```ts
<nav class="pagination" aria-label="分页">
  <button class="page-btn motion is-disabled" aria-label="上一页">‹</button>
  <button class="page-btn motion is-active" aria-current="page">1</button>
  <button class="page-btn motion" aria-label="下一页">›</button>
</nav>
```

#### 步骤条（steps）

三态 finish / process / wait，连接线颜色跟随已完成步骤；横向与垂直共用同一 DOM，仅容器加 .steps--vertical。

```ts
<ol class="steps">
  <li class="step step--finish">
    <span class="step-line"></span>
    <span class="step-dot">✓</span>
    <div class="step-body">
      <div class="step-title">已完成</div>
      <div class="step-desc">描述</div>
    </div>
  </li>
  <li class="step step--process">…</li>
  <li class="step step--wait">…</li>
</ol>
```

#### 回到顶部（back-top）

与 behaviors/back-top 配套：滚动超过阈值（默认 320px）出现的悬浮按钮，点击平滑滚回顶部。支持手写按钮或 autoCreate 全自动。

```ts
import { initBackTop } from '@icen.ai/ui/behaviors/back-top';

// 全自动：portal 一个默认按钮到 body，滚到顶
initBackTop({ autoCreate: true });

// 或手写：
// <button class="back-top" data-back-top type="button" aria-label="回到顶部">…svg…</button>
// initBackTop();
// 可选 data-* 或 opts：threshold（默认 320）/ target（滚动容器）/ offset（滚到多少 px）
```

#### 布局工具（layout）

stack / divider / surface / text / grid / center / container / aspect / visually-hidden 全部工具类，无 JS。

```ts
<div class="stack stack--gap-4">纵向间距栈</div>
<div class="stack stack--row stack--justify-between">横向分布</div>
<div class="grid grid--cols-3 grid--gap-12">三列网格</div>
<div class="surface surface--elevated">浮起表面</div>
<span class="text--sm text--muted">辅助文字</span>
<div class="divider"></div>
```

### AI 原生

#### AI 总览（ai-overview）

一段可播放的完整对话《分析 AI 迭代历史》——把 AI 族全部能力按真实工作流串起来：思考（reasoning 流式+自动折叠）→ 规划（todo activeForm 推进）→ 网络搜索 / 接口调用（工具卡）→ 二次思考 → 正文流式 → render_chart 可视化（默认展开）→ 人工审批（点「允许」继续）→ history.md 差异审阅（accept/reject）→ 文件标签 → 子智能体（嵌套活动流）→ 失败重试（自动展开）→ 多模态回执（架构图）→ 收尾（token/成本、上下文抽屉、审计面板）。输入台 v2（模型切换/命令/@引用/上下文环）全程参与。

```ts
<!-- 本页是「活文档」：全部子组件的独立文档见侧栏 AI 分组各页 -->
```

#### AI 会话（ai-chat）

AI 会话容器（AI 族门面条目）：滚动钉底跟随、上滚暂停跟随并浮出「回到底部 · N 条」浮动钮（缺失自动补建）；消息 copy / retry 操作委托（icen:ai-copy / icen:ai-retry）；reasoning 折叠委托。配套 createAiStream 流式追加（含 fail() 错误路径）与 renderAiMessage 消息渲染原语（多模态部件 + 错误变体）；data-density 三档控制信息密度。下方 demo 是零接线全链路：bindComposer 一行把 composer ↔ 消息区 ↔ createAiClient（mock provider SSE 流式）↔ 上下文环（contextEstimate 正确口径）接成闭环，排队消息自动续发，审计自动累计成本。

```ts
import { initAiChat, createAiStream, renderAiMessage } from '@icen.ai/ui/kit/ai-chat';
initAiChat();   // 钉底跟随 / 上滚暂停 / .ai-chat-jump 缺失自动补建 / copy·retry / reasoning 折叠

// 消息渲染原语（多模态部件 + 错误变体；spec §10 标准化内容）
const msg = renderAiMessage(scrollEl, {
  role: 'user',
  content: [
    { type: 'text', text: '这张图里有什么？' },
    { type: 'image', data: base64, mimeType: 'image/png' },
  ],
  meta: '12:04 · 1.2k tok',
});
msg.stream().append('…');   // 正文末开流式节点（textContent 级，不解析 HTML）
msg.setError('网络中断');    // → .ai-msg--error + 错误文本行

// 零接线全链路（composer ↔ 消息区 ↔ client ↔ 上下文环）：
import { bindComposer } from '@icen.ai/ui/kit/ai-composer';
const binding = bindComposer(composer, {
  client,                        // createAiClient(...)
  messages: scrollEl,            // renderAiMessage 挂载点
  usage: { from: 'context' },    // 环 = contextEstimate（正确口径）；'billing' | AiAuditor 亦可
});
// binding.unbind() 解绑
```

#### AI 消息（ai-message）

消息行基元 .ai-msg：user / assistant / system / tool 四角色（avatar 语义色）+ meta 时间 · token（summary 档隐藏）+ hover / focus-within 浮出 copy · retry 操作钮。renderAiMessage 渲染原语消费标准化内容（spec §10）：字符串或部件数组——文字 / 图片 / 音频 / 视频 / 文件 / 资源链接（MCP ResourceLink）任意组合，另支持错误变体（.ai-msg--error）与流式节点。操作委托由 initAiChat 提供（消息须挂在 .ai-chat 容器内）。

```ts
import { renderAiMessage, initAiChat } from '@icen.ai/ui/kit/ai-message';
initAiChat();   // copy / retry / 折叠委托（消息须挂在 .ai-chat 容器内）

// 纯文本捷径
renderAiMessage(scrollEl, { role: 'user', content: '帮我看看这张图', meta: '12:04 · 21 tok' });

// 多模态部件（spec §10 标准化内容，同一套 parts 直达传输层）
renderAiMessage(scrollEl, {
  role: 'user',
  content: [
    { type: 'text', text: '这张图里有什么？' },
    { type: 'image', data: base64, mimeType: 'image/png', alt: '截图' },
    { type: 'file', url: fileUrl, mimeType: 'application/pdf', filename: 'report.pdf' },
  ],
});

// MCP 回执零改动进消息：normalizeMcpContent 把 tool result 的 content 数组归一成部件
import { normalizeMcpContent } from '@icen.ai/ui';
const parts = normalizeMcpContent(result.content);   // text / image / audio / resource_link / resource
renderAiMessage(scrollEl, { role: 'tool', content: parts, meta: '0.4s' });

// 错误路径：流失败 → fail()；渲染层 → setError
const msg = renderAiMessage(scrollEl, { role: 'assistant', content: '', model: 'kimi-k3' });
const s = msg.stream();
s.append('…');
s.fail();              // 正文节点挂 .is-error，追加终止
msg.setError('网络中断'); // 消息挂 .ai-msg--error + 错误文本行
```

#### AI 推理（ai-reasoning）

推理块 .ai-reasoning：流式中 head 显示 shimmer「正在思考…」（--ai-shimmer-duration 变量化时长）；createAiStream 的 done() 自动折叠并回填耗时；head 点击展开 / 折叠（initAiChat 委托）。summary 密度档默认折叠。

```ts
<div class="ai-reasoning is-done">
  <button class="ai-reasoning-head" aria-expanded="false">
    <span class="ai-reasoning-label">思考过程</span><span class="ai-reasoning-time">3s</span>
  </button>
  <div class="ai-reasoning-body" hidden>…</div>
</div>

<!-- 流式推理：宿主在 .ai-reasoning 内时 done() 自动折叠 + 回填耗时 -->
import { createAiStream, initAiChat } from '@icen.ai/ui/kit/ai-reasoning';
initAiChat();   // head 展开/折叠委托
const s = createAiStream(document.querySelector('.ai-reasoning-body'));
s.append('…');
s.done();   // 或 s.cancel()（取消不折叠、不计耗时）
```

#### AI 输入台（ai-composer）

AI 输入台：autosize（默认 8 行上限后内滚）、Enter 发送 / Shift+Enter 换行、IME 组合态安全、附件 chips（钮选 / 粘贴文件 / 拖放文件三入口共用 icen:ai-attach，拖放时输入框高亮）；setComposerRunning 切换运行态——发送钮变停止钮（icen:ai-stop），运行中回车转为排队 chip（icen:ai-queue / icen:ai-dequeue，可单个 × 移除）。事件 icen:ai-send {text} / icen:ai-attach {files}。bindComposer 绑定层可一行接通全链路（见 ai-chat 页 demo）。

```ts
import { initAiComposer, setComposerRunning, setComposerModels, setComposerCommands, setComposerRefs, setComposerUsage } from '@icen.ai/ui/kit/ai-composer';
initAiComposer();

<div class="ai-composer" data-ai-composer>
  <div class="ai-composer-queue" hidden></div>
  <div class="ai-composer-attach" hidden></div>
  <div class="ai-composer-box control">
    <textarea class="ai-composer-input" rows="1" placeholder="输入消息，/ 命令 · @ 引用 · Enter 发送"></textarea>
    <div class="ai-composer-actions">
      <button class="ai-composer-btn" data-ai-attach aria-label="附件"></button>
      <button class="ai-composer-send" data-ai-send aria-label="发送"></button>
    </div>
  </div>
</div>

// v2：模型切换（多源 × 多模型，弹层分组+搜索+缓存失效提示）
setComposerModels(el, providers, { provider: 'kimi', model: 'kimi-k3' });
// / 斜杠命令（拦截执行不进消息流，icen:ai-command {name, args}）
setComposerCommands(el, [{ name: 'plan', description: '进入计划模式', argsHint: '[任务]' }]);
// @ 引用（file/folder/doc/agent 分组，chip 分离渲染，icen:ai-ref）
setComposerRefs(el, [{ kind: 'file', id: 'f1', label: 'src/app.ts', sub: '2.1k tok' }]);
// 上下文环（模型 context 自动作 total；bindComposer 的 usage.from='context' 自动驱动）
setComposerUsage(el, usage, { cost: 0.3124 });

// 运行态：发送钮 → 停止钮（icen:ai-stop）；运行中回车排队（icen:ai-queue/dequeue）；
// 空输入 ↑ 取回历史；运行中 ↑ 取回排队消息重新编辑
// 附件三入口：钮选 / 在输入框粘贴文件 / 拖放文件到输入框（.is-dragover 高亮）

// 零接线全链路（推荐）：一行绑定 composer ↔ 消息区 ↔ client ↔ 上下文环
import { bindComposer } from '@icen.ai/ui/kit/ai-composer';
const binding = bindComposer(el, {
  client,                          // createAiClient(...)
  messages: scrollEl,              // renderAiMessage 挂载点
  usage: { from: 'context' },      // 环口径：'context'（正确口径）| 'billing' | auditor
});
// binding.unbind() 解绑
```

#### AI 工具调用（ai-tool-call）

工具调用卡 .ai-tool：kind 修饰类（--shell/--read/--edit/--mcp/--rm…，kind 注册表驱动 --ai-item-tint 与图标）+ 7 态状态机（失败条目自动展开）+ 审批内联按钮（icen:ai-approve / icen:ai-reject，detail {id, kind}）。renderAiToolCall(el, model) 动态建卡，返回 { el, update(patch) } 做流式状态流转；输入/输出走注册表 summarize 或压缩 JSON。

```ts
import { initAiTool, renderAiToolCall } from '@icen.ai/ui/kit/ai-tool-call';
initAiTool();   // 展开/折叠 + 审批按钮委托（icen:ai-approve / icen:ai-reject，detail {id, kind}）

<!-- 静态卡：kind 修饰类 + 7 态；失败 is-error 首次渲染自动展开 -->
<div class="ai-tool ai-tool--edit is-approval" data-ai-id="t-1" data-ai-kind="edit">
  <button class="ai-tool-head" aria-expanded="false">…</button>
  <div class="ai-tool-body" hidden>
    <div class="ai-tool-approval">
      <button class="btn btn-sm btn-primary" data-ai-approve>允许</button>
      <button class="btn btn-sm" data-ai-reject>拒绝</button>
    </div>
  </div>
</div>

// 动态建卡（流式场景），update(patch) 做状态流转
const h = renderAiToolCall(el, {
  id: 't-2', name: 'Shell', kind: 'shell', status: 'pending',
  input: { cmd: 'bun run build' },   // 摘要行：注册表 summarize 或压缩 JSON
});
h.update({ status: 'running' });
h.update({ status: 'running' });
h.update({ status: 'done', output: '…', durationMs: 3200 });

// 工具回执内嵌图：output 为 {type:'chart',spec} 或裸 ChartSpec → 展开区直接渲染小图
h.update({ status: 'done', kind: 'chart', output: { type: 'chart', spec: { labels: ['Q1','Q2'], values: [4, 7] } } });

// ── AI 工具体系（ai-tools）：UI 能力注册为模型工具，宿主全控 ──
import { createAiToolArea, registerAiTool, aiToolsToOpenAI, aiToolsManifest } from '@icen.ai/ui';
const area = createAiToolArea(el, { tools: ['render_chart'], max: 4 });  // 白名单 + 上限（LRU）
area.call('render_chart', toolCallArgs);   // 模型 tool_call 的落地入口
registerAiTool({ name: 'highlight_row', description: '…', inputSchema: {/* OpenAI/MCP 兼容 */}, run: (input, mount) => {/*…*/} });
aiToolsToOpenAI();    // → chat.completions tools 参数
aiToolsManifest();    // → system prompt 能力清单
```

#### AI 子智能体（ai-subagent）

子智能体卡 .ai-subagent：activities（AiToolCallModel[]）递归渲染工具卡 / 推理块 / 再嵌套子代理（缩进 + 左侧引导线表达层级）；展开时活动项按 --ai-activity-index 逐条 icen-pop-in 渐入；底部完成回执区。renderAiSubagent(el, model) 返回 update(patch)；第三方 kind 走 ai-core 的 registerAiKind 扩展（demo 里注册了一个 deploy kind）。

```ts
import { initAiSubagent, renderAiSubagent } from '@icen.ai/ui/kit/ai-subagent';
initAiSubagent();   // head 展开/折叠委托（嵌套卡各自独立监听）

// activities 是 AiToolCallModel[]，kind: 'subagent' 的项递归渲染子卡
const h = renderAiSubagent(el, {
  id: 'sa-1', name: 'explore', kind: 'subagent', status: 'running',
  input: { task: '搜索 auth 模块的所有入口' },
  activities: [
    { id: 'a1', name: 'Grep', kind: 'grep', status: 'done', input: { pattern: 'auth' }, output: '6 处命中', durationMs: 900 },
  ],
});
// 活动流按 id 增量 diff：已有的 update、新增的 append（渐入）、消失的移除
h.update({ status: 'done', durationMs: 12400, output: 'auth 模块共 3 个入口' });
// 第三方 kind：registerAiKind('deploy', { label, icon, tint, summarize })
```

#### AI 差异审阅（ai-diff）

差异审阅卡 .ai-diff：parseUnifiedDiff(text) 解析 unified diff（git / 传统头、add/del/rename/binary 均可）→ renderAiDiff(el, {files}) DOM 渲染（行号 + add/del 着色 + hunk 头，全 textContent）；initAiDiff 委托展开 / 接受 / 拒绝——icen:ai-diff-accept / icen:ai-diff-reject（detail {path}），决策后盖状态章并淡化。

```ts
import { initAiDiff, renderAiDiff, parseUnifiedDiff } from '@icen.ai/ui/kit/ai-diff';

// 真实 unified diff → 结构化 files → DOM 渲染（重复调用替换内容）
renderAiDiff(el, { files: parseUnifiedDiff(diffText) });
initAiDiff();   // 展开/折叠 + 接受/拒绝（icen:ai-diff-accept / icen:ai-diff-reject，detail {path}）

// AiDiffFile：{ path, oldPath?, status: added|modified|deleted|renamed, addCount, delCount, hunks }
// hunk：{ oldStart, oldCount, newStart, newCount, header, lines: [{ type: ctx|add|del, oldNo, newNo, text }] }
```

#### AI 文件标签（ai-files）

文件 chips .ai-file-chip（纯 CSS 族，无 behavior）：is-added / is-modified / is-deleted 三态 × 类型修饰类（--ts/--js/--css/--json/--md/--img/--other，图标由消费方注入 svg）；renderAiContext 的文件区复用同款 chips。

```ts
<!-- 纯 CSS 组件，无 behavior；文件图标由消费方注入 svg -->
<div class="ai-files">
  <span class="ai-file-chip is-added ai-file-chip--ts">
    <span class="ai-file-icon">…svg…</span>src/foo.ts
  </span>
</div>
<!-- 类型修饰类：--ts / --js / --css / --json / --md / --img / --other -->
```

#### AI 任务清单（ai-todo）

任务清单 .ai-todo：进度条（feedback progress 视觉）+ N/M 计数 + 7 态条目；running 条目用 activeForm 替换文案（Claude Code 模式）。renderAiTodo(el, items) 渲染；data-ai-todo-interactive 容器可点击循环状态 pending → running → done（icen:ai-todo-toggle {index, status}），默认只读。

```ts
import { renderAiTodo, initAiTodo } from '@icen.ai/ui/kit/ai-todo';

renderAiTodo(el, [
  { content: '搭建 tokens 合并构建', status: 'done' },
  { content: '联调接口', status: 'running', activeForm: '正在联调接口…' },  // Claude Code 模式运行文案
  { content: '写测试', status: 'pending' },
]);
initAiTodo();   // data-ai-todo-interactive 容器可点击循环状态（icen:ai-todo-toggle {index, status}）

<!-- 静态手写等价契约 -->
<div class="ai-todo" data-ai-todo-interactive>
  <div class="ai-todo-head"><span class="ai-todo-progress">2/5</span>
    <div class="ai-todo-bar" role="progressbar"><i style="width:40%"></i></div></div>
  <div class="ai-todo-item is-running">
    <span class="ai-item-status"></span>
    <span class="ai-todo-text">实现登录页</span>
    <span class="ai-todo-active">正在实现登录页…</span>
  </div>
</div>
```

#### AI 用量条（ai-usage）

上下文用量 .ai-usage 双形态：分段条（renderAiUsage）+ 上下文窗口环形指示器（renderAiUsageRing，Claude Desktop 式常驻小环，点击弹出完整分解，弹层复用 popover）。分段条 = 分段条 + 图例 + 占比行；配色契约 input=accent / output=success / cacheRead=info / cacheWrite=warning / reasoning=faint。缓存分列计费诚实：cacheRead ≈ 0.1× 输入价、cacheWrite ≈ 1.25× 输入价（行业惯例，展示与算账口径一致）。配套 renderAiAudit 审计面板：totals（请求数/失败/累计 tokens/累计成本/平均 TTFT）+ byModel 分组 + 最近条目，与 createAiAuditor 的条目（含 cost 定价估算与 ttftMs）闭环。

```ts
import { renderAiUsage, renderAiUsageRing, renderAiAudit } from '@icen.ai/ui/kit/ai-usage';

// 分段条形态
renderAiUsage(el, {
  input: 42000, output: 18000, cacheRead: 96000, cacheWrite: 12000, reasoning: 8000,
}, { total: 200000, cost: 0.3124 });

// 上下文窗口环形指示器（点击弹出完整分解，复用 popover）
renderAiUsageRing(el, { input: 42000, /* … */ }, { total: 200000 });
// 状态档：<60% accent / 60–85% warning / >85% error + 脉冲

// 审计面板：totals + byModel + 最近条目（source 为 auditor 或条目数组，快照渲染）
import { createAiClient, createAiAuditor, estimateCost } from '@icen.ai/ui';
const auditor = createAiAuditor({ persist: 'my-audit', max: 100 });
const client = createAiClient({ provider: 'kimi', apiKey, auditor });
// …每次请求自动 log（含 cost 定价估算 + ttftMs 首 token 延迟）…
renderAiAudit(el, auditor, { limit: 10 });   // 清除钮派 icen:ai-audit-clear，或 opts.onClear

// 手动估一笔（注册表定价；未命中返回 undefined，不猜价）
const cost = estimateCost(usage, 'kimi', 'kimi-k3');
```

#### AI 上下文面板（ai-context）

上下文抽屉 .ai-context：触发器 [data-ai-context-open] 全局委托开合（属性值可为 #id 选择器），fixed 右侧滑入（--z-chrome），Esc / 外点关闭、Tab 焦点圈禁；renderAiContext 组合渲染用量（renderAiUsage）+ 审计节（audit 传 auditor 或条目数组，紧凑形态）+ 文件 chips + MCP server 行（.ai-item：connected→is-done / disconnected→is-error）+ Skills 列表；.ai-context--inline 为页面流内嵌变体（不参与开合）。

```ts
import { initAiContext, renderAiContext } from '@icen.ai/ui/kit/ai-context';

renderAiContext(document.getElementById('ctx'), {
  usage: { input: 42000, cacheRead: 96000, cacheWrite: 12000, output: 18000, reasoning: 8000 },
  usageTotal: 200000,          // 传给 renderAiUsage 的 opts.total
  usageCost: 0.3124,           // 追加 $ 成本行
  audit: auditor,              // auditor 实例或 AiAuditEntry[]：自动出现「审计」节（§12.2 紧凑形态）
  files: [{ path: 'src/foo.ts', status: 'modified' }],
  mcpServers: [{ name: 'github', tools: 24 }],          // connected（默认）→ is-done
  skills: [{ name: 'webbridge', description: '浏览器自动化' }],
});
initAiContext();   // 触发器 [data-ai-context-open] 全局委托；Esc / 外点关闭；焦点圈禁

<!-- 触发器（任意元素；属性值可为 #id 选择器定位指定抽屉） -->
<button data-ai-context-open>上下文</button>
<div id="ctx"></div>
<!-- .ai-context--inline 为页面流内嵌变体：不做 fixed、不参与开合 -->
```