@blueking/chat-x 0.0.45-beta.2 → 0.0.45-beta.4

package/dist/mcp/generated/docs/markdown-content.md

@@ -182,6 +182,7 @@ props.content → completeMarkdownSyntax → md.parse → groupTokens → groupe
 
 | 插件                        | 语法                | 功能                 |
 | --------------------------- | ------------------- | -------------------- |
+| `markdownItBkInlineStyle`   | 见下文「蓝鲸行内样式」 | 安全行内颜色/字号/粗斜体（非 HTML） |
 | `markdown-it-footnote`      | `[^1]`              | 脚注                 |
 | `markdown-it-ins`           | `++text++`          | 下划线               |
 | `markdown-it-mark`          | `==text==`          | 高亮                 |
@@ -192,8 +193,30 @@ props.content → completeMarkdownSyntax → md.parse → groupTokens → groupe
 | `markdownItLatex`           | `$...$` / `$$...$$` | KaTeX 数学公式 token |
 | `markdownItContainer`       | `::: hljs-left` 等  | 自定义对齐容器（class 与 highlight.js 命名对齐） |
 
+### 蓝鲸行内样式（`markdownItBkInlineStyle`）
+
+不开启 `html: true`，由专用语法生成带白名单 `style` 的 `<span class="bk-md-inline-style">`。
+
+**语法**：`::bk{` *属性* `}` *正文* `:/bk::`
+
+- 属性写在 `{}` 内，使用 `;` 分隔；每项为 `键=值` 或 `键:值`。
+- 正文支持行内 Markdown（如 `**粗体**`）。
+- 结束标记必须为字面量 `:/bk::`，请勿在正文中出现该序列。
+
+**支持的键**：`color` / `c`、`background-color`、`font-size`、`bold`、`italic`（详见 `plugins/markdown-bk-inline-style.ts` 内注释）。
+
+**示例**：
+
+```markdown
+::bk{color:#c00;font-size:18px}**重要**:/bk::
+::bk{background-color:yellow}高亮:/bk::
+::bk{bold;italic}强调:/bk::
+```
+
 ### 安全性
 
+`MarkdownIt` **不**开启 `html: true`，用户无法插入任意 HTML 标签；行内彩色/字号等请使用上文「蓝鲸行内样式」扩展。
+
 `VNodeRenderer` 渲染的 HTML 统一经过 DOMPurify 过滤，并额外允许 KaTeX 所需标签：
 
 ```typescript

package/dist/mcp/generated/docs/message-container.md

@@ -502,7 +502,7 @@ AI 回复状态为 `error` 时，消息以错误样式展示：
 | messageGroups            | `MessageGroup[]`                                                                             | —       | 预计算的消息分组；传入时跳过内部分组逻辑，由 `ChatContainer` 通过 `useMessageGroup` 提供                                                 |
 | messageStatus            | `MessageStatus`                                                                              | —       | 当前整体消息状态，控制底部「停止生成」按钮显示；`ChatContainer` 会结合末尾 Loading 占位推导 `fetching` 等再传入                                                                                                   |
 | messageToolsStatus       | `MessageToolsStatus`                                                                         | —       | 工具栏状态，透传给 `MessageTools` 和 `MessageRender`                                                                                     |
-| messageToolsTippyOptions | `AITippyProps`                                                                               | —       | 透传给 `MessageTools` 和 `MessageRender`（进而透传给 `UserMessage` 的工具栏）的 Tippy 配置，用于自定义 tooltip 挂载点（如 `appendTo`）等 |
+| messageToolsTippyOptions | `AITippyProps`                                                                               | —       | 透传给 `MessageTools` 和 `MessageRender`（进而透传给 `UserMessage` 的工具栏）的 Tippy 配置，用于自定义 tooltip 挂载点、位置等（如 `appendTo`、`placement`、`zIndex`） |
 | enableSelection          | `boolean`                                                                                    | `false` | 是否启用多选模式                                                                                                                         |
 | onAgentAction            | `(tool: IToolBtn, messages: Message[]) => Promise<string[] \| void>`                         | —       | AI 消息工具操作回调；`copy` 操作由内部处理，`like/unlike` 应返回反馈原因字符串数组                                                       |
 | onAgentFeedback          | `(tool: IToolBtn, messages: Message[], reasonList: string[], otherReason: string) => void`   | —       | AI 消息反馈提交回调（点赞/踩选完原因后触发）                                                                                             |

package/dist/mcp/generated/docs/message-render.md

@@ -39,7 +39,7 @@ MessageRender
 │     ├── 'info'       → InfoMessage（转发 message）
 │     ├── 'reasoning'  → ReasoningMessage（转发 message）
 │     ├── 'tool'       → ToolMessage（转发 message）
-│     ├── 'activity'   → ActivityMessage（转发 message）
+│     ├── 'activity'   → ActivityMessage（转发 message + onInterruptResume）
 │     ├── 'loading'    → LoadingMessage（转发 message）
 │     ├── 'interrupt'  → InterruptMessageRender（转发 message + onInterruptResume）
 │     │
@@ -274,7 +274,7 @@ slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<Assista
 | messageToolsStatus | `MessageToolsStatus`                                                       | —      | 工具按钮状态；**仅转发给 `UserMessage`**          |
 | onAction           | `(tool: IToolBtn) => Promise<string[] \| void>`                            | —      | 工具操作回调；**仅转发给 `UserMessage`**          |
 | onInputConfirm     | `(content: UserMessage['content'], docSchema: TagSchema) => Promise<void>` | —      | 用户编辑确认回调；**仅转发给 `UserMessage`**      |
-| onInterruptResume  | `(payload: InterruptResume, interrupt: Interrupt) => Promise<void>`        | —      | 中断响应回调；**仅转发给 `InterruptMessageRender`**     |
+| onInterruptResume  | `(payload: InterruptResume, interrupt?: Interrupt) => Promise<void>`         | —      | 中断 / FlowAgent 节点操作回调；转发给 `InterruptMessageRender` 与 `ActivityMessage`（后者仅 `flow_agent` 子组件消费） |
 | onShortcutConfirm  | `(formModel: Record<string, unknown>) => Promise<void>`                    | —      | 用户快捷指令提交回调；**仅转发给 `UserMessage`**  |
 | tippyOptions       | `Partial<Omit<TippyOptions, 'getReferenceClientRect' \| 'triggerTarget'>>` | —      | 自定义 Tippy 配置；**仅转发给 `UserMessage`**     |
 
@@ -295,7 +295,7 @@ slot 参数类型与 `AssistantMessage` 的 slot 保持一致（`Partial<Assista
 | `info`        | `InfoMessage`      | `message`                                                                                               | 系统信息 / 会话分隔符 |
 | `reasoning`   | `ReasoningMessage` | `message`                                                                                               | AI 思考过程（可折叠） |
 | `tool`        | `ToolMessage`      | `message`                                                                                               | 工具调用返回结果      |
-| `activity`    | `ActivityMessage`  | `message`                                                                                               | 知识检索 / 引用文档   |
+| `activity`    | `ActivityMessage`  | `message` + `onInterruptResume`                                                                         | 知识检索 / 引用文档 / FlowAgent 执行（节点重试 / 跳过） |
 | `loading`     | `LoadingMessage`   | `message`（字段被忽略，组件无 Props）                                                                   | 等待响应的加载占位    |
 | `interrupt`   | `InterruptMessageRender` | `message` + `onInterruptResume`                                                                         | human-in-the-loop 中断 |
 | 其他 / 未知   | —                  | —                                                                                                       | 返回 `null`，不渲染   |

package/dist/mcp/generated/docs/message-tools.md

@@ -363,9 +363,9 @@ const CONST_UPDATE_TOOLS = [
 import { MessageToolsStatus, type IToolBtn } from '@blueking/chat-x';
 
 interface IToolBtn {
-  id: string; // 工具唯一标识；与 ToolIconsMap 匹配时显示内置图标，否则显示 name 文本
-  name: string; // 工具名称，无对应图标时显示；也用作 tooltip fallback
-  description: string; // tooltip 文本
+  id?: keyof typeof ToolIconsMap; // 工具唯一标识；与 ToolIconsMap 匹配时显示内置图标，否则显示 name 文本
+  name?: string; // 工具名称，无对应图标时显示；也用作 tooltip fallback
+  description?: string; // tooltip 文本
 }
 
 enum MessageToolsStatus {

package/dist/mcp/generated/docs/shortcut-render.md

@@ -349,7 +349,7 @@ const components: ShortcutComponent[] = [
 | ------------- | ------------------------------------ | ---- | ------------------------------------------------------------------------------------------ |
 | type          | 见[表单类型](#表单组件类型)          | ✓    | 控件类型；未知类型返回 `null`，不渲染                                                      |
 | key           | `string`                             | ✓    | 表单字段名；`submit` 事件返回对象以此为 key；同时作为校验 property                         |
-| name          | `string`                             | —    | 表单项标签（`Form.FormItem` 的 `label`）                                                   |
+| name          | `string`                             | —    | 表单项标签；优先于 `formItemProps.label`，通过 `#label` 插槽渲染为 `.shortcut-render-form-label` |
 | default       | `string`                             | —    | 字段初始值；优先于 `formModel`，在 `watchEffect` 中覆盖写入                                |
 | fillBack      | `boolean`                            | —    | `true` 时映射为 `required: true`（必填校验），同时标记回填语义                             |
 | placeholder   | `string`                             | —    | 占位文本（`input` / `textarea` / `number` 可用）                                           |
@@ -416,6 +416,10 @@ interface BaseShortcutComponent {
 }
 ```
 
+## 样式说明
+
+表单项与控件会附加类型化 class，便于样式覆盖：`shortcut-render-form-item_{type}`（如 `_radio`、`_checkbox`），单选/多选项子项为 `shortcut-render-form-item_radio` / `shortcut-render-form-item_checkbox`。表单项标签使用 BEM 风格类名 `shortcut-render-form-label`。
+
 ## 关联组件
 
 - [ShortcutBtn](/components/input/shortcut-btn) — 与 Shortcut 数据模型一致的入口按钮

package/dist/mcp/generated/docs/theme.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-说明通过 SCSS 变量（尺寸、颜色、z-index）与 CSS 类覆盖（chat-input、用户/助手消息、shortcut-btns、ai-markdown-body、tool-btn 等）自定义主题。 含渐变边框 mixin、ai-markdown-fade-in 与弹窗过渡。暗色示例通过根 class 切换。组件随包引入样式，业务侧按需覆写。
+说明通过 SCSS 变量（尺寸、颜色、z-index）、字号主题 CSS 变量（data-ai-size 切换 small/normal）与 CSS 类覆盖自定义主题。 ChatContainer.size 控制根节点 data-ai-size；浮层同步 document.body.dataset.aiSize。含渐变边框 mixin、骨架屏类 ai-skeleton-element 等。
 
 ### 关联组件
 - **chat-container** — 整体布局与侧栏
@@ -26,6 +26,51 @@
 import { ChatInput, MessageContainer } from '@blueking/chat-x';
 ```
 
+## 字号主题
+
+组件库通过根节点 `[data-ai-size]` 切换两档字号主题，内部组件统一引用 CSS 变量（均带兜底值，无 provider 时退回 `small`）。
+
+### 切换方式
+
+| 方式 | 说明 |
+| ---- | ---- |
+| `ChatContainer` 的 `size` prop | 推荐。根节点 `.ai-chat-container` 设置 `data-ai-size`；同时通过 `useGlobalConfig` 注入 `size` 供逻辑层读取 |
+| 手动设置 `data-ai-size` | 在任意祖先元素上设置 `data-ai-size="small"` 或 `data-ai-size="normal"`，后代继承 CSS 变量 |
+| `document.body.dataset.aiSize` | `ChatContainer` 会自动同步，供 Tippy / Teleport 等挂载到 `body` 的浮层继承字号变量；容器卸载时清理 |
+
+```vue
+<template>
+  <ChatContainer v-model="input" :messages="messages" size="normal" />
+</template>
+```
+
+### CSS 变量
+
+定义于 `src/styles/size-theme.scss`，随 `global.scss` 自动引入：
+
+| 变量名 | `small`（默认） | `normal` | 说明 |
+| ------ | --------------- | -------- | ---- |
+| `--ai-font-size` | `12px` | `14px` | 基准字号 |
+| `--ai-line-height` | `20px` | `24px` | 标准行高 |
+| `--ai-line-height-compact` | `20px` | `22px` | 紧凑行高 |
+| `--ai-spacing-comfortable` | `8px` | `12px` | 舒适间距（如消息气泡水平内边距） |
+| `--ai-icon-size` | `16px` | `20px` | 标准图标尺寸 |
+| `--ai-icon-size-sm` | `16px` | `18px` | 小号图标尺寸 |
+
+组件样式中统一使用 `var(--ai-font-size, 12px)` 等形式引用，保证无 `data-ai-size` 时仍退回 small 档位。
+
+```scss
+// 示例：在自定义样式中复用字号主题变量
+.my-custom-panel {
+  font-size: var(--ai-font-size, 12px);
+  line-height: var(--ai-line-height, 20px);
+}
+```
+
+### 骨架屏
+
+全局类 `.ai-skeleton-element` 用于加载占位（如 FlowAgent 节点详情、UserFeedback 原因列表）。可通过 `.skeleton-element-lg` 修饰尺寸。详见各业务组件文档中的加载态说明。
+
 ## SCSS 变量
 
 组件库使用以下 SCSS 变量，可以在项目中覆盖：
@@ -383,6 +428,7 @@ $selection-z-index: $shortcut-menu-z-index + 1;
 
 ## 关联组件
 
-- [ChatContainer](../components/setup/chat-container) — 布局与主题根节点
+- [ChatContainer](../components/setup/chat-container) — 布局与字号主题根节点（`size` prop）
+- [useGlobalConfig](../composables/use-global-config) — 注入 `size` 供后代读取
 - [ChatInput](../components/input/chat-input) — 输入区变量与类名
 - [MessageContainer](../components/setup/message-container) — 消息列表区域

package/dist/mcp/generated/docs/tool-approval-card.md

@@ -129,11 +129,11 @@ ToolApprovalCard
 | 属性名            | 类型                         | 默认值 | 说明                                         |
 | ----------------- | ---------------------------- | ------ | -------------------------------------------- |
 | interrupt         | `AIDevToolApprovalInterrupt` | —      | **必填**，含 `metadata.ticket`               |
-| onInterruptResume | `OnInterruptResume`          | —      | 取消审批时触发，签名为 `(payload, interrupt)`，payload 为 `{ action: 'cancel' }` |
+| onInterruptResume | `OnInterruptResume`          | —      | 取消审批时触发，签名为 `(payload, interrupt)`，payload 为 `{ operation: InterruptResumeOperation.ApprovalCancel, payload: { interrupt_id } }` |
 
 ### Events / Slots / Expose
 
-无。打开链接、复制剪贴板在组件内部完成；取消审批通过 `onInterruptResume({ action: 'cancel' }, interrupt)` 通知业务侧处理。
+无。打开链接、复制剪贴板在组件内部完成；取消审批通过 `onInterruptResume({ operation: InterruptResumeOperation.ApprovalCancel, payload: { interrupt_id: interrupt.id } }, interrupt)` 通知业务侧处理。
 
 ## 依赖
 

package/dist/mcp/generated/docs/tool-btn.md

@@ -30,8 +30,9 @@ div.ai-tool-btn（v-tippy，flex，min-width: 20px，height: 20px，border-radiu
   disabled=true → .is-disabled（color: #979ba5; cursor: not-allowed）
   :not(.is-disabled):hover → color: #4d4f56; background: #eaebf0
   │
-  ├── [id in ToolIconsMap] → <component :is="ToolIconsMap[id]" />（SVG 图标，font-size: 16px 控制大小）
-  └── [id not in ToolIconsMap] → <div>{{ name }}</div>（文本回退，XSS 安全）
+  └── <slot>（默认内容，可完全自定义）
+        ├── [id && id in ToolIconsMap] → <component :is="ToolIconsMap[id]" />（SVG 图标）
+        └── [其他] → <div>{{ name }}</div>（文本回退，XSS 安全）
 
 Tippy：content=description, theme='ai-chat-box', disabled=true 时 onShow 返回 false 不显示
 click 事件：disabled=true 时被 JS 拦截，不触发 emit
@@ -56,7 +57,7 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 | `activeLike`   | 点赞（实心）   | 激活态填充图标           |
 | `activeUnLike` | 不满意（实心） | 激活态填充图标           |
 
-> `id` 不在上表时，组件渲染 `<div>{{ name }}</div>` 作为文本回退。此时 `id` 的 TypeScript 类型会报错（`keyof typeof ToolIconsMap`），建议优先使用预置 ID。
+> 未传入 `id`、或 `id` 不在上表时，组件渲染 `<div>{{ name }}</div>` 作为文本回退。也可通过默认插槽完全自定义按钮内容（如全屏图标），此时可不传 `id`。
 
 ## 基础用法
 
@@ -192,7 +193,31 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 
 ## 未知 ID 的文本回退
 
-`id` 不在 `ToolIconsMap` 时渲染 `name` 文本，适用于自定义扩展场景（注意 TypeScript 会报类型错误）：
+`id` 不在 `ToolIconsMap` 时渲染 `name` 文本，适用于自定义扩展场景：
+
+## 自定义插槽内容
+
+通过默认插槽可完全替换内置图标/文本，适用于预置 `ToolIconsMap` 未覆盖的图标场景（如侧栏全屏按钮）：
+
+```vue
+<template>
+  <ToolBtn
+    description="全屏"
+    :tippy-options="{ content: '全屏' }"
+    @click="handleFullScreen"
+  >
+    <FullScreenIcon />
+  </ToolBtn>
+</template>
+
+<script setup lang="ts">
+  import { ToolBtn, FullScreenIcon } from '@blueking/chat-x';
+
+  const handleFullScreen = () => {
+    // 进入全屏逻辑
+  };
+</script>
+```
 
 ## API
 
@@ -200,7 +225,7 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 
 | 属性名       | 类型                                                                       | 必填 | 默认值 | 说明                                                                                                               |
 | ------------ | -------------------------------------------------------------------------- | ---- | ------ | ------------------------------------------------------------------------------------------------------------------ |
-| id           | `keyof typeof ToolIconsMap`                                                | 是   | —      | 按钮标识；在 `ToolIconsMap` 中时渲染对应 SVG 图标，否则渲染 `name` 文本                                            |
+| id           | `keyof typeof ToolIconsMap`                                                | 否   | —      | 按钮标识；在 `ToolIconsMap` 中时渲染对应 SVG 图标，否则渲染 `name` 文本；使用插槽自定义内容时可省略                  |
 | name         | `string`                                                                   | 否   | —      | 按钮名称；`id` 无对应图标时作为文本内容渲染                                                                        |
 | description  | `string`                                                                   | 否   | —      | Tippy tooltip 内容；`disabled=true` 时不显示 tooltip                                                               |
 | active       | `boolean`                                                                  | 否   | —      | 激活态；`true` 时追加 `.is-active`（字色由 `id` 决定：`like`/`activeLike` 为蓝色 `#3a84ff`，其他为红色 `#E71818`） |
@@ -213,12 +238,18 @@ click 事件：disabled=true 时被 JS 拦截，不触发 emit
 | ------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | click  | `(data: IToolBtn & { active?: boolean; disabled?: boolean }, event: MouseEvent)` | 点击时触发；`data` 为组件当前全量 props（含 `active`/`disabled`）；`disabled=true` 时不触发 |
 
+### Slots
+
+| 插槽名  | 说明                                                                                       |
+| ------- | ------------------------------------------------------------------------------------------ |
+| default | 按钮内容；传入时替换默认的图标/文本渲染逻辑，常用于自定义 SVG 图标（如全屏、退出全屏按钮） |
+
 ## 类型定义
 
 ```typescript
 // 来自 @blueking/chat-x 导出
 interface IToolBtn {
-  id: keyof typeof ToolIconsMap; // 限定为预置 ID
+  id?: keyof typeof ToolIconsMap; // 预置 ID；省略时走 name 文本或插槽
   name?: string;
   description?: string;
 }

package/dist/mcp/generated/docs/use-flow-node-actions.md

@@ -0,0 +1,124 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useFlowNodeActions 接收 onInterruptResume 与 openNodeDetail，返回 getNodeActions(task, node)。 失败节点按 retryable/skippable 展示重试/跳过，详情恒在末尾；点击 resume 时不传 interrupt。
+
+### 关联组件
+- **flow-agent-content** — FlowAgentContent 内部消费，驱动节点行尾按钮组渲染
+
+---
+<!-- FULL DOC -->
+
+# useFlowNodeActions 节点行尾操作
+
+> **分类**：composable
+
+将 FlowAgent 节点行尾的「详情（打开侧栏）」与「重试 / 跳过（回传 Agent resume）」聚合为统一的声明式操作列表。`FlowAgentContent` 只需遍历 `getNodeActions` 返回值渲染按钮，显隐与点击行为均收敛于此 composable。
+
+源码：`src/components/chat-content/flow-agent-content/use-flow-node-actions.ts`
+
+## 函数签名
+
+```typescript
+function useFlowNodeActions(options: {
+  /** resume 回调（与第三方审批取消同一回调，按 payload.operation 分流） */
+  onInterruptResume: Ref<OnInterruptResume | undefined>;
+  /** 打开节点详情侧栏（复用 useFlowTab 的能力） */
+  openNodeDetail: (task: BkFlowTask, node: BkFlowNode) => void;
+}): {
+  getNodeActions: (task: FlowTaskVM, node: FlowNodeVM) => FlowNodeActionVM[];
+};
+```
+
+## 返回值：FlowNodeActionVM
+
+```typescript
+type FlowNodeActionId =
+  | 'detail'
+  | InterruptResumeOperation.FlowNodeRetry
+  | InterruptResumeOperation.FlowNodeSkip;
+
+interface FlowNodeActionVM {
+  icon: Component;
+  id: FlowNodeActionId;
+  label: string;
+  run: () => void;
+}
+```
+
+| 字段    | 说明                           |
+| ------- | ------------------------------ |
+| `icon`  | 按钮图标组件                   |
+| `id`    | 唯一标识，用于 `v-for` key     |
+| `label` | 国际化文案                     |
+| `run`   | 点击执行（详情或 resume）      |
+
+## 操作显隐规则
+
+| 操作 | `id`               | 显隐条件                                   | 点击行为                                      |
+| ---- | ------------------ | ------------------------------------------ | --------------------------------------------- |
+| 重试 | `flow_node_retry`  | `convergedState === 'failed'` 且 `retryable` | 调用 `onInterruptResume`，**不传** `interrupt` |
+| 跳过 | `flow_node_skip`   | `convergedState === 'failed'` 且 `skippable` | 同上                                          |
+| 详情 | `detail`           | 始终（Share 模式由上层组件隐藏整组）       | 调用 `openNodeDetail(task.raw, node.raw)`     |
+
+展示顺序：重试 → 跳过 → 详情。
+
+## resume 负载格式
+
+```typescript
+// 重试
+onInterruptResume?.({
+  operation: InterruptResumeOperation.FlowNodeRetry,
+  payload: { node_id: node.id, task_id: task.task_id },
+});
+
+// 跳过
+onInterruptResume?.({
+  operation: InterruptResumeOperation.FlowNodeSkip,
+  payload: { node_id: node.id, task_id: task.task_id },
+});
+```
+
+## 使用示例
+
+`FlowAgentContent` 内部用法（业务侧通常通过 `MessageRender` 传入 `onInterruptResume`，无需直接调用本 composable）：
+
+```typescript
+import { toRef } from 'vue';
+import { useFlowNodeActions } from '@blueking/chat-x';
+// 或相对路径：'./use-flow-node-actions'
+
+const { getNodeActions } = useFlowNodeActions({
+  onInterruptResume: toRef(props, 'onInterruptResume'),
+  openNodeDetail,
+});
+
+// 模板中
+// v-for="action in getNodeActions(task, node)" :key="action.id"
+// @click.stop="action.run()"
+```
+
+## 扩展新操作
+
+在 `RESUME_ACTION_DEFS` 注册表中追加一项即可，需声明 `visible` 与 `operation` 枚举：
+
+```typescript
+const RESUME_ACTION_DEFS: FlowNodeResumeActionDef[] = [
+  // 现有：重试、跳过
+  {
+    icon: MyIcon,
+    id: InterruptResumeOperation.MyNewOp, // 需先在 InterruptResumeOperation 扩展
+    label: () => t('新操作'),
+    visible: node => /* 自定义显隐 */,
+  },
+];
+```
+
+同时在 `interrupt.ts` 扩展 `InterruptResumeOperation` 与 `FlowNodeResume` 联合类型。
+
+## 关联文档
+
+- [FlowAgentContent 执行内容](/components/agent/flow-agent-content) — 消费方组件
+- [中断类型 Interrupt](/types/interrupt) — `InterruptResumeOperation`、`FlowNodeResume`、`OnInterruptResume`
+- [ActivityMessage 活动消息](/components/message/activity-message) — `onInterruptResume` 透传链路
+- [MessageRender 消息渲染器](/components/message/message-render) — 顶层透传入口

package/dist/mcp/generated/docs/use-full-screen.md

@@ -0,0 +1,114 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+useFullScreen 将目标元素（或 document.documentElement）以浏览器原生全屏展示。 模块加载时一次性嗅探 requestFullscreen / webkitRequestFullscreen，返回 isSupported、只读 isFullScreen 与 enter/exit/toggle。 监听 fullscreenchange 同步 ESC 等外部退出；ChatContainer 侧栏全屏按钮使用此 composable。
+
+### 关联组件
+- **chat-container** — 侧栏 .ai-full-screen-wrapper 全屏切换
+- **tool-btn** — 全屏按钮通过插槽渲染 FullScreenIcon
+
+---
+<!-- FULL DOC -->
+
+# useFullScreen 全屏控制
+
+> **分类**：composable
+
+基于浏览器原生 Fullscreen API 的全屏控制组合式函数。模块加载时一次性嗅探标准 API 与 `webkit` 前缀（兼容旧版 Safari），在组件作用域销毁时自动移除事件监听。
+
+## 工作原理
+
+```
+useFullScreen(target?)
+  │
+  ├── resolveFullscreenApi()（模块级，仅执行一次）
+  │     requestFullscreen / webkitRequestFullscreen
+  │
+  ├── isSupported = !!fullscreenApi
+  ├── isFullScreen（readonly shallowRef，与浏览器真实状态同步）
+  │
+  ├── enter()  → target.requestFullscreen()
+  ├── exit()   → document.exitFullscreen()
+  ├── toggle() → isFullScreen ? exit() : enter()
+  │
+  └── document.addEventListener(fullscreenchange, syncState)
+        syncState：指定 target 时，仅当 fullscreenElement === target 视为全屏
+        onScopeDispose 时移除监听
+```
+
+> **注意**：`enter()` 可能因缺少用户手势等原因被浏览器拒绝，内部会静默捕获异常，避免未处理的 Promise rejection。
+
+## 基础用法
+
+```vue
+<template>
+  <div>
+    <div ref="panelRef" class="demo-panel">
+      <p>可全屏展示的面板内容</p>
+    </div>
+    <button :disabled="!isSupported" @click="enter">进入全屏</button>
+    <button :disabled="!isFullScreen" @click="exit">退出全屏</button>
+    <span>当前状态：{{ isFullScreen ? '全屏' : '窗口' }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+  import { useTemplateRef } from 'vue';
+  import { useFullScreen } from '@blueking/chat-x';
+
+  const panelRef = useTemplateRef<HTMLElement>('panelRef');
+  const { isSupported, isFullScreen, enter, exit } = useFullScreen(panelRef);
+</script>
+```
+
+## 在 ChatContainer 中的使用
+
+`ChatContainer` 将侧栏包裹在 `.ai-full-screen-wrapper` 中，通过 `useFullScreen(fullScreenRef)` 控制侧栏全屏；Tab 栏 `#setting` 插槽内的 `ToolBtn` 使用自定义插槽渲染 `FullScreenIcon` / `UnFullScreenIcon`。
+
+详见 [ChatContainer 侧栏全屏](../components/setup/chat-container.md#侧栏全屏)。
+
+## API
+
+### 参数
+
+| 参数名 | 类型 | 默认值 | 说明 |
+| ------ | ---- | ------ | ---- |
+| target | `MaybeRef<HTMLElement \| null>` | — | 需要全屏的目标元素；省略时回退到 `document.documentElement` |
+
+### 返回值
+
+| 属性名 | 类型 | 说明 |
+| ------ | ---- | ---- |
+| isSupported | `boolean` | 当前环境是否支持 Fullscreen API（SSR 或不支持时为 `false`） |
+| isFullScreen | `Readonly<ShallowRef<boolean>>` | 只读响应式全屏状态；与浏览器真实状态同步（含 ESC 退出） |
+| enter | `() => Promise<void>` | 进入全屏；已全屏或不受支持时无操作 |
+| exit | `() => Promise<void>` | 退出全屏；当前无全屏元素时无操作 |
+| toggle | `() => void` | 切换全屏状态 |
+
+## 类型定义
+
+```typescript
+import { useFullScreen } from '@blueking/chat-x';
+import type { MaybeRef, Readonly, ShallowRef } from 'vue';
+
+type UseFullScreenReturn = {
+  isSupported: boolean;
+  isFullScreen: Readonly<ShallowRef<boolean>>;
+  enter: () => Promise<void>;
+  exit: () => Promise<void>;
+  toggle: () => void;
+};
+
+// 调用签名
+declare function useFullScreen(target?: MaybeRef<HTMLElement | null>): UseFullScreenReturn;
+```
+
+## 使用场景
+
+- `ChatContainer` 侧栏执行情况 / 自定义 Tab 区域全屏查看
+- 任意需要将局部 DOM 区域以浏览器原生全屏展示的交互面板
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container.md) — 内置侧栏全屏按钮
+- [ToolBtn](../components/feedback/tool-btn.md) — 全屏按钮自定义插槽

package/dist/mcp/generated/docs/use-global-config.md

@@ -1,7 +1,7 @@
 <!-- AI SUMMARY -->
 ## 快速了解
 
-useGlobalConfig 接收 GlobalConfig（含 supportUpload: ComputedRef<boolean>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig； UserMessage 等通过 injectGlobalConfig 读取 supportUpload。
+useGlobalConfig 接收 GlobalConfig（含 size?: ComputedRef<AiSizeMode>、supportUpload: ComputedRef<boolean>），以 GLOBAL_CONFIG_TOKEN provide 给后代； injectGlobalConfig 在子组件中取出配置，无 Provider 时返回 undefined。ChatContainer 在 setup 中调用 useGlobalConfig 注入 size 与 supportUpload； 后代组件可通过 injectGlobalConfig 读取配置；字号主题主要通过根节点 data-ai-size 与 CSS 变量生效。
 
 ### 关联组件
 - **chat-container** — 根容器调用 useGlobalConfig 注入 supportUpload
@@ -13,14 +13,20 @@ useGlobalConfig 接收 GlobalConfig（含 supportUpload: ComputedRef<boolean>）
 
 > **分类**：composable
 
-在聊天容器根组件与子组件之间通过 Vue `provide` / `inject` 共享**全局展示相关配置**（当前主要为是否支持上传 `supportUpload`）。与 Teleport 插槽 ID 无关。
+在聊天容器根组件与子组件之间通过 Vue `provide` / `inject` 共享**全局展示相关配置**（当前包括字号主题档位 `size`、是否支持上传 `supportUpload`）。与 Teleport 插槽 ID 无关。
+
+> 字号主题主要通过 `ChatContainer` 根节点的 `data-ai-size` 与 CSS 变量（`--ai-font-size` 等）生效；`GlobalConfig.size` 供后代在逻辑层读取当前档位，样式层无需逐组件传参。
 
 ## 工作原理
 
 ```
 ChatContainer（根）
-  ├── useGlobalConfig({ supportUpload: computed(() => props.supportUpload ?? false) })
-  │     └── provide(GLOBAL_CONFIG_TOKEN, { supportUpload })
+  ├── :data-ai-size="size"（CSS 变量作用域）
+  ├── useGlobalConfig({
+  │     size: computed(() => props.size ?? 'small'),
+  │     supportUpload: computed(() => props.supportUpload ?? false),
+  │   })
+  │     └── provide(GLOBAL_CONFIG_TOKEN, { size, supportUpload })
   │
   └── MessageContainer → … → UserMessage 等
 
@@ -43,10 +49,12 @@ UserMessage（后代）
   import { useGlobalConfig } from '@blueking/chat-x';
 
   const props = defineProps<{
+    size?: 'normal' | 'small';
     supportUpload?: boolean;
   }>();
 
   useGlobalConfig({
+    size: computed(() => props.size ?? 'small'),
     supportUpload: computed(() => props.supportUpload ?? false),
   });
 </script>
@@ -75,11 +83,15 @@ import type { ComputedRef } from 'vue';
 
 export const GLOBAL_CONFIG_TOKEN: unique symbol;
 
+export type AiSizeMode = 'normal' | 'small';
+
 export type GlobalConfig = {
+  size?: ComputedRef<AiSizeMode>;
   supportUpload: ComputedRef<boolean>;
 };
 
 export function useGlobalConfig(options: GlobalConfig): {
+  size?: ComputedRef<AiSizeMode>;
   supportUpload: ComputedRef<boolean>;
 };
 
@@ -96,12 +108,14 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 
 | 字段            | 说明                                                                     |
 | --------------- | ------------------------------------------------------------------------ |
+| `size`          | 可选。字号主题档位 `normal`（14px）/ `small`（12px），与 `ChatContainer.size` 对齐 |
 | `supportUpload` | 是否支持上传，与根容器 `ChatContainer` 的 `supportUpload` 等展示策略对齐 |
 
 ### `useGlobalConfig(options)`
 
 | 参数                    | 说明                                                                                  |
 | ----------------------- | ------------------------------------------------------------------------------------- |
+| `options.size`          | 可选。字号主题档位，建议使用 `computed(() => props.size ?? 'small')` 与根 props 同步 |
 | `options.supportUpload` | 是否支持上传，建议使用 `computed(() => props.supportUpload ?? false)` 与根 props 同步 |
 
 - 调用后立即 `provide(GLOBAL_CONFIG_TOKEN, options)`。
@@ -122,4 +136,5 @@ export function injectGlobalConfig(): GlobalConfig | undefined;
 
 ## 关联组件
 
-- [ChatContainer](../components/setup/chat-container) — 调用 `useGlobalConfig` 注入 `supportUpload`
+- [ChatContainer](../components/setup/chat-container) — 调用 `useGlobalConfig` 注入 `size` 与 `supportUpload`
+- [主题配置](../theme/theme) — `data-ai-size` 与 CSS 变量说明