@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/composables/use-command-selection.md

@@ -0,0 +1,150 @@
+# useCommandSelection
+
+> 导入：`import { useCommandSelection } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useCommandSelection 无参数，返回 commandSelection、docSnapshot、GetCursorPosition、GetDocSnapshot。 GetCursorPosition 写入光标行列；GetDocSnapshot 将当前文档快照写入 docSnapshot，供外部 modelValue 与编辑器比对同步。 仅在 AiSlashInput（@ 菜单插入与 modelValue 同步）内部使用。
+
+**关联**：chat-input（AiSlashInput 内部使用）
+
+---
+
+# useCommandSelection 光标位置追踪
+
+> **分类**：composable
+
+为 `edix` 富文本编辑器提供光标位置追踪能力的组合式函数。内部封装一个 `EditorCommand`，由编辑器调用后将光标的行列信息存入响应式变量，供后续编辑命令（如插入 tag、删除关键词）精确定位。
+
+> 该 composable 仅在 `AiSlashInput` 内部使用，属于编辑器底层基础设施，**通常无需直接调用**。
+
+## 实现原理
+
+```
+editor.command(GetCursorPosition)
+  │  edix 编辑器将 (doc, selection) 注入 EditorCommand
+  │
+  └── GetCursorPosition(doc, selection)
+        const [, focus] = selection   // selection = [anchor, focus]
+        const [line, column] = focus  // focus = [lineIndex, columnIndex]
+        commandSelection.value = { column, line }
+                                 ↓
+               commandSelection（shallowRef，初始值 { column: 0, line: 0 }）
+
+editor.command(GetDocSnapshot)
+  └── GetDocSnapshot(doc)
+        docSnapshot.value = doc   // 当前文档快照，用于与 props.modelValue 比对
+```
+
+**使用时机**：
+
+- 在 `@` 资源插入流程中，先执行 `GetCursorPosition` 快照当前光标，再据此计算删除范围和插入位置。
+- 在外部 `modelValue` 变化时，先执行 `GetDocSnapshot` 取得编辑器当前文档，与 `docToString(modelValue)` 比对，决定是否 `ReplaceAll` 同步。
+
+## 概念演示
+
+`commandSelection` 追踪编辑器光标的 `{ line, column }` 位置（行从 0 开始，column 为字符偏移量）。以下用原生 textarea 模拟等价的位置信息：
+
+> 实际使用时，由 `editor.command(GetCursorPosition)` 触发写入，而非手动计算。
+
+## 在 AiSlashInput 中的实际用法
+
+```typescript
+import { watch } from 'vue';
+
+const { commandSelection, GetCursorPosition, GetDocSnapshot, docSnapshot } = useCommandSelection();
+
+// 用户从 @xxx 菜单中选择资源时：
+const insertTagAtCursor = (tag: IInputMenuItem) => {
+  editor.command(GetCursorPosition);
+  const { column, line } = commandSelection.value;
+  editor.command(DeleteTag, [line, column - keyword.value.length - 1], [line, column]);
+  editor.command(InsertTag, [line, column], tag);
+};
+
+// 外部 modelValue 变化时，与编辑器文档对齐（简化示意；需已存在 editor、props、text、docToString）
+watch(
+  () => props.modelValue,
+  () => {
+    editor.command(GetDocSnapshot);
+    if (docToString(docSnapshot.value || []) !== docToString(text.value || [])) {
+      editor.command(ReplaceAll, docToString(text.value || []) as unknown as string);
+    }
+  },
+  { deep: false },
+);
+```
+
+## API
+
+### 参数
+
+无。`useCommandSelection()` 不接受任何参数。
+
+### 返回值
+
+| 属性名              | 类型                                           | 初始值                   | 说明                                                                                       |
+| ------------------- | ---------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
+| `commandSelection`  | `ShallowRef<{ column: number; line: number }>` | `{ column: 0, line: 0 }` | 存储最近一次执行 `GetCursorPosition` 时的光标行列位置                                      |
+| `docSnapshot`       | `ShallowRef<DocFragment>`                      | `[]`                     | 存储最近一次执行 `GetDocSnapshot` 时的文档快照                                             |
+| `GetCursorPosition` | `EditorCommand<[]>`                            | —                        | 编辑器命令，由 `editor.command(GetCursorPosition)` 触发，将当前光标写入 `commandSelection` |
+| `GetDocSnapshot`    | `EditorCommand<[]>`                            | —                        | 编辑器命令，由 `editor.command(GetDocSnapshot)` 触发，将当前文档写入 `docSnapshot`       |
+
+## 类型说明
+
+```typescript
+// EditorCommand：edix 编辑器的命令签名
+type EditorCommand<A extends unknown[]> = (
+  doc: DocFragment,
+  selection: SelectionSnapshot, // [[anchorLine, anchorColumn], [focusLine, focusColumn]]
+  ...args: A
+) => Transaction | void;
+
+// useCommandSelection 返回值
+interface UseCommandSelectionReturn {
+  commandSelection: ShallowRef<{ column: number; line: number }>;
+  docSnapshot: ShallowRef<DocFragment>;
+  GetCursorPosition: EditorCommand<[]>;
+  GetDocSnapshot: EditorCommand<[]>;
+}
+```
+
+## 实现源码
+
+```typescript
+import { shallowRef } from 'vue';
+
+import type { EditorCommand } from '../edix';
+import type { DocFragment } from '../edix/doc/types';
+
+export const useCommandSelection = () => {
+  const commandSelection = shallowRef<{ column: number; line: number }>({ column: 0, line: 0 });
+  const docSnapshot = shallowRef<DocFragment>([]);
+
+  const GetCursorPosition: EditorCommand<[]> = (_doc, selection) => {
+    const [, focus] = selection;
+    const [line, column] = focus;
+    commandSelection.value = { column, line };
+  };
+
+  const GetDocSnapshot: EditorCommand<[]> = doc => {
+    docSnapshot.value = doc;
+  };
+
+  return {
+    commandSelection,
+    docSnapshot,
+    GetCursorPosition,
+    GetDocSnapshot,
+  };
+};
+```
+
+## 注意事项
+
+1. **只读命令**：`GetCursorPosition` 不返回 `Transaction`，不修改编辑器文档内容，仅记录位置
+2. **异步快照**：`commandSelection` 在 `editor.command(GetCursorPosition)` 执行后**同步**更新，下一行代码即可安全读取
+3. **`shallowRef` 而非 `ref`**：对象引用替换触发响应式，内部字段修改不触发（此处每次整体替换，无影响）
+4. **仅适用于 edix 编辑器**：`GetCursorPosition` / `GetDocSnapshot` 依赖 edix 的文档与选区格式，不适用于原生 contenteditable 或其他富文本库
+
+## 关联组件
+
+- [ChatInput](../components/input/chat-input) — AiSlashInput 子模块使用

package/skills/blueking-chat-x/references/composables/use-container-scroll.md

@@ -0,0 +1,57 @@
+# useContainerScroll
+
+> 导入：`import { useContainerScrollConsumer, useContainerScrollProvider } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useContainerScrollProvider 在滚动容器与底部锚点上绑定 IntersectionObserver、scroll、wheel，提供 isScrollBottom、scrollBottomHeight、autoScrollEnabled、jumpToBottom、toScrollBottom/toScrollTop 及防抖「返回底部」按钮状态。 toScrollBottom 缺省按距底部距离自动选择行为：超过 INSTANT_SCROLL_DISTANCE（600px）时瞬时贴底，否则平滑滚动，避免切换会话时出现长距离平滑滚动动画。 useContainerScrollConsumer 通过 inject 在子组件中获取同一套控制，无需 props 透传。 典型用于流式输出时仅在用户位于底部时自动滚底。MessageContainer 与 ScrollBtn 配合使用。
+
+**关联**：message-container（Provider 挂载于消息列表滚动区域）、scroll-btn（使用 debouncedShowScrollBottomBtn 与 toScrollBottom）、chat-container（组合消息区与输入区时的整体布局上下文）
+
+---
+
+# useContainerScroll 容器滚动
+
+> **分类**：composable
+
+为消息容器提供滚动控制的组合式函数对，通过 **Provider/Consumer** 模式在父子组件间共享滚动状态。
+
+- `useContainerScrollProvider`：在容器组件中调用，创建滚动控制并通过 `provide` 向下共享
+- `useContainerScrollConsumer`：在任意后代组件中调用，通过 `inject` 获取滚动控制
+
+## 工作原理
+
+```
+useContainerScrollProvider(containerRef, bottomRef)
+  │
+  ├── IntersectionObserver 监听 bottomRef
+  │     可见 → isScrollBottom=true, scrollBottomHeight=0, autoScrollEnabled=true
+  │     不可见 → isScrollBottom=false, calculateScrollBottom()
+  │
+  ├── scroll 事件（passive）→ calculateScrollBottom()
+  │     scrollBottomHeight = max(0, scrollHeight - scrollTop - clientHeight)
+  │
+  ├── wheel 事件（passive）→ deltaY < 0 时 autoScrollEnabled=false
+  │     （用户向上滚动时暂停自动滚动）
+  │
+  ├── jumpToBottom()   → autoScrollEnabled=true + container.scrollTop = scrollHeight（瞬时）
+  ├── toScrollBottom(behavior?) → autoScrollEnabled=true；
+  │     behavior 缺省时：距底部 > INSTANT_SCROLL_DISTANCE(600) → jumpToBottom()
+  │     否则 / 显式 'smooth' → bottomRef.scrollIntoView({ behavior:'smooth', block:'end' })
+  ├── toScrollTop()    → containerRef.scrollTo({ top:0, behavior:'smooth' })
+  │
+  └── provide(CONTAINER_SCROLL_TOKEN, computed(() => ({
+            autoScrollEnabled: autoScrollEnabled.value,  // 解包为 boolean
+            isScrollBottom,             // ShallowRef<boolean>（保持响应式）
+            scrollBottomHeight,         // ShallowRef<number>（保持响应式）
+            debouncedShowScrollBottomBtn, // customRef，防抖显示返回底部按钮
+            jumpToBottom,
+            toScrollBottom,
+            toScrollTop,
+        })))
+
+useContainerScrollConsumer()
+  └── inject(CONTAINER_SCROLL_TOKEN) → ComputedRef<ContainerScrollData> | undefined
+```
+
+> **注意**：Consumer 获得的 `ComputedRef` 中，`isScrollBottom` 和 `scrollBottomHeight` 是 `ShallowRef` 对象（非解包值），需要通过 `.value` 访问。
+
+## 渲染示例

package/skills/blueking-chat-x/references/composables/use-custom-tab.md

@@ -0,0 +1,158 @@
+# useCustomTab
+
+> 导入：`import { useCustomTabConsumer, useCustomTabProvider } from '@blueking/chat-x'` ｜ since 1.0.0
+
+useCustomTabProvider 返回 tabs、selectedTab、isCollapse 及 add/ensure/remove/selectCustomTab，并通过 provide 共享；可选 onTabChange 在切换时拉取数据、可选 collapsed 注入受控折叠态 ref。 ensureCustomTab 只挂载/合并元信息，不展开侧栏、不主动切换选中；addCustomTab 会展开并选中。 未被主动切换过时，选中态默认跟随 Tab 栏首位（order 最小），如常驻的「文件产物」。 useCustomTabConsumer 在后代注入同一套 API，常用于侧栏动态节点详情等。EXECUTION_TAB_NAME 标识默认「执行情况」Tab。 ChatContainer 侧栏集成 Provider 与 Tab UI。
+
+**关联**：chat-container（Provider 与侧栏 Tab 主场景）
+
+---
+
+# useCustomTab 自定义 Tab 管理
+
+> **分类**：composable
+
+Provider/Consumer 模式的自定义 Tab 管理，用于 `ChatContainer` 侧边栏的 Tab 动态管理。Provider 在 `ChatContainer` 中创建，Consumer 在任意后代组件中注入使用。
+
+## 函数签名
+
+### useCustomTabProvider
+
+```typescript
+function useCustomTabProvider<T extends Record<string, unknown>>(options: {
+  // 侧栏折叠态；由容器传入受控 ref（如 ChatContainer 的 v-model:asideCollapsed），缺省内部自持
+  collapsed?: Ref<boolean>;
+  // 执行情况 Tab 是否展示，缺省 true；传 getter 以保持响应式
+  executionTabVisible?: () => boolean | undefined;
+  onTabChange?: (tab: CustomTab<T>) => void;
+}): {
+  tabs: ShallowRef<CustomTab<T>[]>;
+  displayTabs: ComputedRef<CustomTab<T>[]>;
+  selectedTab: Ref<CustomTab<T>>;
+  isCollapse: Ref<boolean>;
+  addCustomTab: (tab: CustomTab<T>) => void;
+  ensureCustomTab: (tab: CustomTab<T>) => void;
+  removeCustomTab: (tabName: string) => void;
+  selectCustomTab: (tab: CustomTab<T>) => void;
+  resetCustomTab: () => void;
+};
+```
+
+### useCustomTabConsumer
+
+```typescript
+function useCustomTabConsumer<T extends Record<string, unknown>>():
+  | undefined
+  | {
+      tabs: ShallowRef<CustomTab<T>[]>;
+      displayTabs: ComputedRef<CustomTab<T>[]>;
+      selectedTab: ShallowRef<CustomTab<T> | null>;
+      addCustomTab: (tab: CustomTab<T>) => void;
+      ensureCustomTab: (tab: CustomTab<T>) => void;
+      removeCustomTab: (tabName: string) => void;
+      selectCustomTab: (tab: CustomTab<T>) => void;
+      resetCustomTab: () => void;
+    };
+```
+
+## 使用示例
+
+### Provider（容器组件）
+
+```typescript
+import { useCustomTabProvider, EXECUTION_TAB_NAME } from '@blueking/chat-x';
+
+const { tabs, selectedTab, isCollapse, addCustomTab, ensureCustomTab, removeCustomTab, selectCustomTab, resetCustomTab } =
+  useCustomTabProvider({
+  onTabChange: async tab => {
+    // Tab 切换时加载数据
+    const data = await fetchTabData(tab.name);
+    return data;
+  },
+});
+```
+
+### Consumer（后代组件）
+
+```typescript
+import { useCustomTabConsumer } from '@blueking/chat-x';
+
+const tabManager = useCustomTabConsumer();
+
+// 添加一个自定义 Tab（展开侧栏并选中）
+tabManager?.addCustomTab({
+  name: 'node-detail-123',
+  label: '节点详情',
+  data: {
+    component: NodeDetailComponent,
+    props: { nodeId: '123' },
+  },
+});
+
+// 仅确保 Tab 存在（不展开、不切换选中）—— 如常驻挂上文件产物 Tab
+tabManager?.ensureCustomTab({
+  name: 'file-artifact',
+  label: '文件产物',
+  closable: false,
+  order: -1,
+});
+
+// 移除 Tab
+tabManager?.removeCustomTab('node-detail-123');
+```
+
+## 内置常量
+
+| 常量名               | 值            | 说明                                       |
+| -------------------- | ------------- | ------------------------------------------ |
+| `EXECUTION_TAB_NAME` | `'execution'` | 执行情况 Tab 的固定标识                    |
+| `DEFAULT_TAB_ORDER`  | `100`         | Tab 默认排序权重；执行情况固定为 `0`       |
+| `CUSTOM_TAB_TOKEN`   | `Symbol`      | provide/inject 注入 Token                  |
+
+## 返回值说明
+
+| 属性/方法名     | 类型                        | 说明                                              |
+| --------------- | --------------------------- | ------------------------------------------------- |
+| tabs            | `ShallowRef<CustomTab[]>`   | 所有 Tab 列表（含默认的执行情况 Tab，保留隐藏项） |
+| displayTabs     | `ComputedRef<CustomTab[]>`  | Tab 栏实际展示列表：过滤 `visible === false`，按 `order` 升序稳定排序 |
+| selectedTab     | `Ref<CustomTab>`            | 当前选中的 Tab；未被主动切换过时跟随 Tab 栏首位，选中项被隐藏时自动回退到首个可见 Tab |
+| isCollapse      | `Ref<boolean>`              | 侧边栏折叠状态；传入 `collapsed` 时即该受控 ref（读写都作用于外部），否则为内部状态；`addCustomTab` 时自动设为 `false` |
+| addCustomTab    | `(tab: CustomTab) => void`  | 添加/合并 Tab，**展开侧栏并选中**目标 Tab |
+| ensureCustomTab | `(tab: CustomTab) => void`  | 添加/合并 Tab，**不展开、不主动切换选中**；用于常驻挂载（如文件产物） |
+| removeCustomTab | `(tabName: string) => void` | 移除指定 Tab                                      |
+| selectCustomTab | `(tab: CustomTab) => void`  | 切换到指定 Tab，触发 `onTabChange` 回调           |
+| resetCustomTab  | `() => void`                  | 重置为仅保留「执行情况」Tab、折叠侧栏并选中默认 Tab；`ChatContainer` 在卸载时调用，避免残留自定义 Tab |
+
+## 类型定义
+
+```typescript
+interface CustomTab<T = Record<string, unknown>> {
+  label: string;
+  name: string;
+  /** 可与 `component` / `props` 并列；用于侧栏「在对话中定位」与主消息 `message.uid` 对齐 */
+  data?: T & { messageUid?: string };
+  /** 排序权重，升序，越小越靠前；缺省 100，执行情况默认 0 */
+  order?: number;
+  /** 是否在 Tab 栏展示，缺省 true；false 时仍可被程序化选中，但内容不渲染、会自动切到首个可见 Tab */
+  visible?: boolean;
+  /** 是否可关闭，缺省 true；执行情况强制不可关闭 */
+  closable?: boolean;
+}
+```
+
+## 设计特点
+
+- `tabs` 使用 `shallowRef`，`addCustomTab` 通过展开新数组触发更新，避免 `UnwrapRef<T>` 类型问题
+- 默认的「执行情况」Tab 始终存在且不可关闭，`order` 固定 `0`；可通过 `executionTabVisible` 配置显隐
+- `displayTabs` 负责「过滤显隐 + 按 `order` 排序」；原始 `tabs` 仍保留全部 Tab 供程序化选中与查找
+- 排序为稳定排序，`order` 相同的 Tab 保持插入先后顺序
+- 选中的 Tab 被配置隐藏时，内容不再渲染，自动切换到首个可见 Tab
+- `addCustomTab` 同时展开侧边栏（`isCollapse = false`）并在 `nextTick` 后自动选中目标 Tab；同名 Tab 合并更新
+- `ensureCustomTab` 与 `addCustomTab` 共用合并逻辑，但不改 `isCollapse`、自身不切换 `selectedTab`；适合「常驻挂载文件产物 Tab」等场景
+- 默认选中跟随 Tab 栏首位：只要没调用过 `selectCustomTab` / `addCustomTab`，挂上更靠前（`order` 更小）的 Tab 就会成为选中项，因此常驻的「文件产物」（`order: -1`）是侧栏默认面板；一旦主动切换过便不再跟随。`resetCustomTab` 会重置该标记
+- 折叠态支持受控：传入 `collapsed` 后 Provider 不再自持状态，内部展开动作直接写回该 ref，容器即可通过 `v-model` 把状态交给外部判断
+
+## 关联组件
+
+- [ChatContainer](../components/setup/chat-container) — 侧栏 Tab 与自定义面板
+- [useArtifactPreview](./use-artifact-preview) — 文件产物 Tab：初始化 `ensureCustomTab` 常驻挂载，点击卡片时 `addCustomTab`

package/skills/blueking-chat-x/references/composables/use-flow-node-actions.md

@@ -0,0 +1,164 @@
+# useFlowNodeActions
+
+> 未从包入口导出：内部实现 ｜ since 2.0.0
+
+useFlowNodeActions 接收 onInterruptResume 与 openNodeDetail，返回 getNodeActions 与 isNodePending。 失败节点按 retryable/skippable 展示重试/跳过，详情恒在末尾；点击后进入 pending 防重复提交， 以 task_id:node_id:retry 为键自动收敛；点击 resume 时不传 interrupt。 hideResumeActions 为 true 时只返回详情，覆盖 Share 分享态与侧栏「执行情况」面板两类只读场景。
+
+**关联**：flow-agent-content（FlowAgentContent 内部消费，驱动节点行尾按钮组渲染）
+
+---
+
+# 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 操作（分享态、侧栏执行情况面板等只读场景，仅保留「详情」查看入口） */
+  hideResumeActions?: Ref<boolean>;
+  /** resume 回调（与第三方审批取消同一回调，按 payload.operation 分流） */
+  onInterruptResume: Ref<OnInterruptResume | undefined>;
+  /** 打开节点详情侧栏（复用 useFlowTab 的能力） */
+  openNodeDetail: (task: BkFlowTask, node: BkFlowNode) => void;
+}): {
+  getNodeActions: (task: FlowTaskVM, node: FlowNodeVM) => FlowNodeActionVM[];
+  /** 当前节点是否有进行中的 resume 操作（供视图层常驻显示按钮组） */
+  isNodePending: (task: FlowTaskVM, node: FlowNodeVM) => boolean;
+};
+```
+
+## 返回值：FlowNodeActionVM
+
+```typescript
+type FlowNodeActionId =
+  | 'detail'
+  | InterruptResumeOperation.FlowNodeRetry
+  | InterruptResumeOperation.FlowNodeSkip;
+
+interface FlowNodeActionVM {
+  /** 是否禁用点击（任一 resume 操作进行中时，重试 / 跳过均禁用） */
+  disabled: boolean;
+  icon: Component;
+  id: FlowNodeActionId;
+  /** 国际化文案（进行中时切换为「重试中 / 跳过中」） */
+  label: string;
+  /** 是否处于进行中态：图标切换为 loading */
+  loading: boolean;
+  /** 因另一操作进行中而禁用时的 hover 提示 */
+  tooltip?: string;
+  run: () => void;
+}
+```
+
+| 字段       | 说明                                                           |
+| ---------- | -------------------------------------------------------------- |
+| `disabled` | 禁用点击；resume 进行中时重试 / 跳过均为 `true`，详情恒为 `false` |
+| `icon`     | 按钮图标组件（`loading` 时由上层切换为 Loading 组件）          |
+| `id`       | 唯一标识，用于 `v-for` key                                     |
+| `label`    | 国际化文案；进行中为「重试中 / 跳过中」                        |
+| `loading`  | 本操作进行中时为 `true`                                        |
+| `tooltip`  | 被另一操作阻塞时的 hover 提示（如「任务正在重试中，不可跳过」） |
+| `run`      | 点击执行（详情或 resume）；进行中重复调用被内部忽略              |
+
+## 操作显隐规则
+
+| 操作 | `id`               | 显隐条件                                   | 点击行为                                      |
+| ---- | ------------------ | ------------------------------------------ | --------------------------------------------- |
+| 重试 | `flow_node_retry`  | `convergedState === 'failed'` 且 `retryable`，且 `hideResumeActions` 为 `false` | 调用 `onInterruptResume`，**不传** `interrupt` |
+| 跳过 | `flow_node_skip`   | `convergedState === 'failed'` 且 `skippable`，且 `hideResumeActions` 为 `false` | 同上                                          |
+| 详情 | `detail`           | 始终（不受 `hideResumeActions` 影响）        | 调用 `openNodeDetail(task.raw, node.raw)`     |
+
+展示顺序：重试 → 跳过 → 详情。
+
+> **只读场景过滤**：`hideResumeActions` 为 `true` 时，`getNodeActions` 直接过滤掉重试 / 跳过，仅返回「详情」查看入口，用于放开查看、禁止交互的场景。`FlowAgentContent` 目前把两类只读场景并入该入参：
+>
+> - `RenderMode.Share` 分享态
+> - 侧栏「执行情况」面板内（`ExecutionSummary` 通过 `EXECUTION_PANEL_TOKEN` 提供上下文，组件用 `useExecutionPanelInject` 读取）
+
+## pending 态与防重复提交
+
+点击重试或跳过后：
+
+1. 以 `task_id:node_id:retry` 为键写入 `pendingMap`，同一节点仅允许一个进行中的 resume 操作
+2. 进行中按钮：`loading: true`、`disabled: true`、`label` 切换为「重试中 / 跳过中」
+3. 另一 resume 按钮：`disabled: true`，`tooltip` 给出阻塞原因
+4. 详情按钮：不受影响
+5. `isNodePending(task, node)` 返回 `true`，供视图层添加 `is-pending` class 常驻显示按钮组
+6. 后端推送新状态且 `node.retry` 变化时，pending 键自动失效，按钮恢复可用
+
+## 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'
+
+// 是否处于侧栏「执行情况」面板内；缺省 false，即对话流内渲染
+// useExecutionPanelInject 来自内部 src/composables/use-common.ts，未从包入口导出
+const isInExecutionPanel = useExecutionPanelInject();
+
+const { getNodeActions, isNodePending } = useFlowNodeActions({
+  // 分享态与侧栏执行情况面板均只读：过滤重试 / 跳过，仅保留详情
+  hideResumeActions: computed(() => renderMode.value === RenderMode.Share || isInExecutionPanel),
+  onInterruptResume: toRef(props, 'onInterruptResume'),
+  openNodeDetail,
+});
+
+// 模板中
+// :class="{ 'is-pending': isNodePending(task, node) }"
+// v-for="action in getNodeActions(task, node)" :key="action.id"
+// :class="{ 'is-disabled': action.disabled }"
+// v-tippy="action.tooltip ? { content: action.tooltip } : { content: '' }"
+// @click.stop="handleActionClick(action)"  // 禁用态拦截，避免重复提交
+```
+
+## 扩展新操作
+
+在 `RESUME_ACTION_DEFS` 注册表中追加一项即可，需声明 `visible` 与 `operation` 枚举：
+
+```typescript
+const RESUME_ACTION_DEFS: FlowNodeResumeActionDef[] = [
+  // 现有：重试、跳过
+  {
+    blockedTip: () => t('另一操作进行中的提示'),
+    icon: MyIcon,
+    id: InterruptResumeOperation.MyNewOp, // 需先在 InterruptResumeOperation 扩展
+    label: () => t('新操作'),
+    pendingLabel: () => 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/skills/blueking-chat-x/references/composables/use-full-screen.md

@@ -0,0 +1,112 @@
+# useFullScreen
+
+> 导入：`import { useFullScreen } from '@blueking/chat-x'` ｜ since 2.0.0
+
+useFullScreen 将目标元素（或 document.documentElement）以浏览器原生全屏展示。 模块加载时一次性嗅探 requestFullscreen / webkitRequestFullscreen，返回 isSupported、只读 isFullScreen 与 enter/exit/toggle。 监听 fullscreenchange 同步 ESC 等外部退出；ChatContainer 侧栏全屏按钮使用此 composable。
+
+**关联**：chat-container（侧栏 .ai-full-screen-wrapper 全屏切换）、tool-btn（全屏按钮通过插槽渲染 FullScreenIcon）
+
+---
+
+# 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) — 全屏按钮自定义插槽