From da19c87213fc5b68e257f0899176f76128ed8738 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=82=9F=E6=89=AC?= Date: Tue, 17 Nov 2026 20:17:07 +0800 Subject: [PATCH 1/3] =?UTF-8?q?feat(skills):=20=E6=94=AF=E6=8C=81=E7=BB=84?= =?UTF-8?q?=E4=BB=B6=E3=80=81=E7=A4=BA=E4=BE=8B=E5=92=8C=20SDK=20=E6=BA=90?= =?UTF-8?q?=E7=A0=81=E5=A4=8D=E5=88=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- apps/storybook/content/docs/skill/index.mdx | 11 +- apps/storybook/content/docs/skill/install.mdx | 30 ++- assets/skills/kit-chat-provider/SKILL.md | 8 +- .../kit-chat-provider/references/api.md | 1 + .../kit-chat-provider/references/copy-in.md | 87 ++++++++ .../kit-chat-provider/references/examples.md | 2 +- .../kit-chat-provider/scripts/copy-in.mjs | 37 ++++ .../kit-chat-provider/scripts/install.mjs | 186 ++++++++++++++++++ assets/skills/kit-components/SKILL.md | 7 +- .../skills/kit-components/references/api.md | 1 + .../kit-components/references/copy-in.md | 87 ++++++++ .../kit-components/references/examples.md | 2 +- .../skills/kit-components/references/setup.md | 37 +--- .../skills/kit-components/scripts/copy-in.mjs | 37 ++++ .../skills/kit-components/scripts/install.mjs | 186 ++++++++++++++++++ assets/skills/use-kit-chat/SKILL.md | 15 +- assets/skills/use-kit-chat/references/api.md | 1 + .../skills/use-kit-chat/references/copy-in.md | 87 ++++++++ .../use-kit-chat/references/examples.md | 2 +- .../skills/use-kit-chat/scripts/copy-in.mjs | 37 ++++ .../skills/use-kit-chat/scripts/install.mjs | 186 ++++++++++++++++++ ...0027-skills-source-and-generated-output.md | 7 + docs/repository-layout.md | 7 +- docs/validation.md | 2 +- packages/chat-ui/registry.json | 6 +- scripts/kit/copy-in.mjs | 4 + scripts/kit/skill-install.mjs | 186 ++++++++++++++++++ scripts/skills/AGENTS.md | 10 +- scripts/skills/README.md | 12 +- scripts/skills/copy-in-assets.mjs | 167 ++++++++++++++++ scripts/skills/copy-in.md | 87 ++++++++ scripts/skills/generate.mjs | 12 +- scripts/skills/pack.mjs | 44 +++-- scripts/skills/src/kit-chat-provider/skill.md | 8 +- .../src/kit-components/references/setup.md | 37 +--- scripts/skills/src/kit-components/skill.md | 7 +- scripts/skills/src/use-kit-chat/skill.md | 15 +- scripts/skills/tests/copy-in.test.mjs | 126 ++++++++++++ 39 files changed, 1664 insertions(+), 122 deletions(-) create mode 100644 assets/skills/kit-chat-provider/references/copy-in.md create mode 100644 assets/skills/kit-chat-provider/scripts/copy-in.mjs create mode 100644 assets/skills/kit-chat-provider/scripts/install.mjs create mode 100644 assets/skills/kit-components/references/copy-in.md create mode 100644 assets/skills/kit-components/scripts/copy-in.mjs create mode 100644 assets/skills/kit-components/scripts/install.mjs create mode 100644 assets/skills/use-kit-chat/references/copy-in.md create mode 100644 assets/skills/use-kit-chat/scripts/copy-in.mjs create mode 100644 assets/skills/use-kit-chat/scripts/install.mjs create mode 100644 scripts/kit/skill-install.mjs create mode 100644 scripts/skills/copy-in-assets.mjs create mode 100644 scripts/skills/copy-in.md create mode 100644 scripts/skills/tests/copy-in.test.mjs diff --git a/README.md b/README.md index 7cab455..1e6a3c0 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ | UI 组件 `@openagentpack/kit-chat-ui` | Chat、Message、Sender、Attachments、FileCard、ToolApprovalCard 等 | 组合对话、输入、附件、文件和审批界面;支持将组件及声明依赖复制到业务项目中修改 | | 会话运行时 `@openagentpack/kit-sdk` 的功能入口 | 流解析、请求、后端适配、消息状态、重连与会话动作 | 接入既有后端,管理流式数据与会话交互;非 React 应用可直接订阅会话状态 | | React hooks `@openagentpack/kit-sdk/<功能>/hooks` | `useChat`、`useSessions`、`useAgentCatalog` 等 | 将连接、消息、发送、停止与审批绑定到 React 页面 | -| 开发 Skill | `kit-components`、`use-kit-chat`、`kit-chat-provider` | 指导 coding agent 选组件、组合交互并适配后端,配有 API 参考与可编译示例 | +| 开发 Skill | `kit-components`、`use-kit-chat`、`kit-chat-provider` | 指导 coding agent 选组件、组合交互并适配后端。离线包可将组件和 Kit SDK 源码复制到业务项目 | SDK 按功能导入,例如 `@openagentpack/kit-sdk/chat`、`@openagentpack/kit-sdk/chat/hooks` 与 `@openagentpack/kit-sdk/sessions/hooks`,不提供根聚合入口。 diff --git a/apps/storybook/content/docs/skill/index.mdx b/apps/storybook/content/docs/skill/index.mdx index 0ff88fa..5455430 100644 --- a/apps/storybook/content/docs/skill/index.mdx +++ b/apps/storybook/content/docs/skill/index.mdx @@ -6,7 +6,8 @@ description: 用三个中文 Skill 指导 coding agent 组合 Kit 组件、管 import { Cards, Card } from "fumadocs-ui/components/card"; Kit 提供三个面向 coding agent 的中文 Skill,分别指导组件选择、聊天状态与后端接入。 -每个 Skill 都包含工作步骤、API 参考和经过类型检查的示例,可以独立复制使用。 +每个 Skill 都包含工作步骤、API 参考和经过类型检查的示例。完整离线包还包含在业务项目中 +按需复制组件和 Kit SDK 的脚本与资产。 Skill 是写代码时读取的指南,不是运行时插件,也不会替应用创建会话或调用百炼。 页面的实际行为仍由 `kit-chat-ui`、Kit SDK 各功能入口及其 `/hooks` 和业务后端完成。 @@ -31,12 +32,12 @@ Skill 是写代码时读取的指南,不是运行时插件,也不会替应 ## 获取与阅读 先阅读[安装与更新](/docs/skill/install),再将 Skill 目录复制到 coding agent 支持的目录。 -也可以直接下载[三个 Skill 的离线包](/skills/kit-skills.tgz)并阅读其中的 `SKILL.md`。 -每个包都带有所需的 `references/` 和 `examples/`,不要只复制入口文件。 +可以直接下载[三个 Skill 的离线包](/skills/kit-skills.tgz)并阅读其中的 `SKILL.md`。 +复制整个 Skill 目录,以保留参考、示例、复制脚本和本地 Kit 资产。 Skill 源文件位于 `scripts/skills/src/`,最终目录生成到 `assets/skills//`,离线压缩包 -由 `pnpm pack:skills` 生成到 `assets/skills/dist/`。没有安装器 CLI,也没有发布 npm 包。 -下载的 Skill 包含中文正文、API 说明、示例注释和界面文案。 +由 `pnpm pack:skills` 生成到 `assets/skills/dist/`。离线包内的 `scripts/install.mjs` +可将所需组件、示例和 SDK 源码复制到应用,组件和示例通过相对路径导入 `src/sdk/` 的公开入口。 ## API 与示例如何保持一致 diff --git a/apps/storybook/content/docs/skill/install.mdx b/apps/storybook/content/docs/skill/install.mdx index d06116d..4c0c782 100644 --- a/apps/storybook/content/docs/skill/install.mdx +++ b/apps/storybook/content/docs/skill/install.mdx @@ -5,6 +5,7 @@ description: 从仓库或离线包获取中文 Skill,并在更新时保留本 Skill 通过完整目录交付。每个目录中的 `SKILL.md` 是入口,`references/` 提供按需阅读的 API 和行为说明,`examples/` 提供可复用的 TypeScript 示例。 +`scripts/` 和 `assets/kit/` 提供 copy-in 脚本、组件源码、主题和 Kit SDK。 ## 获取离线包 @@ -27,18 +28,38 @@ Skill 目录。单个压缩包的顶层目录就是 Skill 名称;全部压缩 SKILL.md references/ examples/ + scripts/ + assets/ use-kit-chat/ SKILL.md references/ examples/ + scripts/ + assets/ kit-chat-provider/ SKILL.md references/ examples/ + scripts/ + assets/ ``` -不要只复制 `SKILL.md`:入口中的相对链接需要同目录下的参考与示例。 -三个 Skill 可以独立安装;跨 Skill 的建议不会替代各自必需的参考内容。 +请保留离线包中每个 Skill 的完整目录和 assets。三个 Skill 可以独立安装。 + +## 接入业务项目 + +在目标项目使用 Skill 时,让 coding agent 阅读其中的 `references/copy-in.md`。 +从解压的 Skill 目录运行脚本,传入应用目录和所需组件: + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" chat +``` + +所选组件、传递依赖和主题会放入应用的 `src/components/kit/`。省略组件名和示例时只复制 Kit SDK。 +SDK 源码会放入 `src/sdk/`,复制后的组件通过相对路径导入它的公开入口。 +复制示例时,使用 `--example <文件名>`,例如在 `use-kit-chat` 的脚本中传入 +`--example experience.tsx`。脚本会带上所需组件和随附文件,示例落在 +`src/kit-examples/use-kit-chat/`。应用统一构建这些源码,并用自己的包管理器安装第三方依赖。 ## 从仓库生成 @@ -51,14 +72,13 @@ pnpm pack:skills ``` 源文件位于 `scripts/skills/src//`;最终目录生成到 `assets/skills//`, -离线包写入 `assets/skills/dist/`。`assets/skills//` 是生成物,不要直接手改。 +包含组件和 SDK 资产的完整离线包写入 `assets/skills/dist/`。生成物由上述命令维护。 文档站构建会校验同步结果并准备下载文件,不会替开发者自动改写已跟踪的源或示例。 压缩包保留打包时源文件的实际修改时间(精确到秒),解压后可直接查看。该时间来自当前 工作目录的文件,不代表 Git 最后提交时间;内容或修改时间变化都会改变压缩包。 -Skill 不再作为独立 workspace 包存在,也不需要加入应用的运行时依赖。当前没有安装器命令 -或 npm 发布流程。 +Skill 安装在 coding agent 的工具目录。应用运行时使用复制后的组件源码和本地 SDK。 ## 更新已有 Skill diff --git a/assets/skills/kit-chat-provider/SKILL.md b/assets/skills/kit-chat-provider/SKILL.md index 8d1348d..23492b6 100644 --- a/assets/skills/kit-chat-provider/SKILL.md +++ b/assets/skills/kit-chat-provider/SKILL.md @@ -8,13 +8,17 @@ description: "通过公开的 Request 和 createSessionEventChatProvider 配置 使用本 Skill 在已有业务后端与 Kit 对话控制器之间编写前端适配。上游仍是百炼托管 Agent。 适配层的职责限于连接现有后端、映射响应及订阅生命周期。 +按[复制组件和 Kit SDK](references/copy-in.md)接入应用内的 SDK 源码。用 `--example` +复制适配器示例时,脚本会生成指向本地 SDK 源码的相对导入。多 Agent 示例还会复制 `Chat` 及其依赖, +使用时导入本地主题。 + ## 选择接入方式 | 现有后端 | 实现 | | --- | --- | | 返回标准 SDK `SessionEvent` 快照和控制帧,例如 Kit Server | 配置 `createSessionEventChatProvider`,参考[标准事件接入](references/normalized-events.md) | | 返回标准快照,但采用其他传输方式 | 实现 `ChatProvider` 的五个方法并映射生命周期回调 | -| 转发百炼原始 SSE | 使用 `@openagentpack/kit-sdk/providers/bailian` 的 `createBailianChatProvider`,参考[原始 SSE 接入](references/raw-sse.md) | +| 转发百炼原始 SSE | 使用本地 `src/sdk/providers/bailian/index.ts` 的 `createBailianChatProvider`,参考[原始 SSE 接入](references/raw-sse.md) | Web 应用与自建后端共用同一套公开配置。已有 KitClient 的应用可以继续通过 Context 接入, 也可以使用[兼容封装](examples/kit-client-provider.ts)。 @@ -57,4 +61,4 @@ Stream 将帧数据保留为文本。Request 可解析 JSON 语法,业务 Sche 提供 `SessionEvent` 和 `createBailianSessionEventNormalizer`。 服务端入口提供 `listSessionThreads` 和 `listSessionThreadEvents`。 升级依赖时,检查解析到的公开导出并运行相关合同测试和浏览器打包测试。 -真实后端和 Cloud 接入需独立验收。集成现有后端时沿用已发布的 SDK 与默认配置。 +真实后端和 Cloud 接入需独立验收。 diff --git a/assets/skills/kit-chat-provider/references/api.md b/assets/skills/kit-chat-provider/references/api.md index a1834b1..bc25f75 100644 --- a/assets/skills/kit-chat-provider/references/api.md +++ b/assets/skills/kit-chat-provider/references/api.md @@ -3,6 +3,7 @@ 本页由 `pnpm gen:skills` 生成。更新公开 TypeScript 声明或中文 catalog 后重新生成。 字段类型和必填性来自公开 API,行为说明依据所列文档整理。 组件表格列出 Kit 自有属性。组件按声明继承标准的 React/DOM 属性。 +参考中的包名用于仓库内导入。业务项目按[复制组件和 Kit SDK](copy-in.md)改用本地源码入口。 ## 目录 diff --git a/assets/skills/kit-chat-provider/references/copy-in.md b/assets/skills/kit-chat-provider/references/copy-in.md new file mode 100644 index 0000000..dbbc585 --- /dev/null +++ b/assets/skills/kit-chat-provider/references/copy-in.md @@ -0,0 +1,87 @@ +# 将组件和 Kit SDK 复制进项目 + +使用完整的 Skill 离线包。其 `assets/kit/` 带有匹配示例版本的组件源码、registry 和 Kit SDK。 +也可以在 Kit 仓库运行 `pnpm pack:skills`,从 `assets/skills/dist/` 解压对应的离线包。 +Copy-in 脚本可以用 Node.js 直接运行。 + +## 复制到应用 + +1. 找到待接入应用的 `package.json`。在 monorepo 中选择实际消费 Kit 的成员包。 +2. 用 `--example` 选择当前 Skill 的示例文件,或传入页面需要的组件条目名。组件清单位于 + `assets/kit/chat-ui/registry.json`。脚本会复制选中示例的随附文件、组件及其传递依赖和主题。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" chat +``` + +只使用 SDK 数据入口、hooks 或后端适配时,可以省略组件名和示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" +``` + +SDK 源码位于应用的 `src/sdk/`。组件复制到 `src/components/kit/`, +通过 `--example` 复制的示例位于 `src/kit-examples//`。脚本已为这些文件生成 +相对导入路径。参考中的原始示例保留仓库的包导入,接入应用时先使用脚本生成可直接引用的源码。 + +业务代码也可按文件位置导入 SDK 的公开源码入口。例如在 `src/App.tsx` 中导入 `useChat`。 + +```tsx +import { useChat } from "./sdk/chat/hooks/index.ts"; +``` + +按功能入口导入 SDK,例如消息类型位于 `src/sdk/messages/index.ts`。由宿主应用的工具链统一编译这些源码。 + +脚本会在应用的 `package.json` 中补上缺少的 SDK 和组件依赖,例如上游 `@openagentpack/sdk` +和 `zod`。用应用现有的包管理器执行安装并更新锁文件。应用已有同名依赖时,核对实际解析版本是否与 +Skill 的 `assets/kit/sdk/copy-in.json` 兼容。React 页面使用宿主的 React 和同主版本的 React DOM。 + +将 `src/sdk/` 随应用提交。SDK 使用 `findLast` 和 `toReversed` 等 +ES2023 API,应用的 TypeScript `lib` 应包含 `ES2023` 或更新版本,Web 项目继续保留 DOM 类型。 +Node.js 宿主可以用已有的 TypeScript 运行器,例如安装 `tsx` 后运行 `node --import tsx src/main.ts`, +或通过应用的打包器一起编译。 +仅用数据入口时,如果 `tsconfig.json` 会扫描整个 `src/`,可将 `src/sdk` 加入 `exclude`。 +TypeScript 仍会检查应用实际导入的 SDK 模块。 + +## 使用复制后的 UI + +脚本已改写复制后示例的组件导入。自己编写的页面可从 `src/components/kit/` 按文件位置导入。 +组件文件的层级与 registry 中 `src/components/` 后面的路径一致。例如在应用的 `src/App.tsx` 中: + +```tsx +import { Chat } from "./components/kit/chat/index.tsx"; +import { SessionSidebar } from "./components/kit/session-sidebar/index.tsx"; +``` + +复制的源码保留 `.ts` 和 `.tsx` 导入后缀。由打包器输出 JavaScript 的 TypeScript 项目可用 +`noEmit` 和 `allowImportingTsExtensions` 检查这些文件。 + +在 Tailwind v4 的应用样式入口导入本地主题并确保扫描本地组件源码。Vite 项目初次接入时, +安装 `tailwindcss` 与 `@tailwindcss/vite` 并在 Vite 配置中注册 `tailwindcss()` 插件。 +应用样式文件位于 `src/` 时,可以这样引入: + +```css +@import "tailwindcss"; +@import "./components/kit/theme.css"; +@source "./components/kit"; +``` + +遇到内容不同的本地组件、SDK 源码或示例时,脚本会在写入前报告冲突。先核对差异, +保留需要的定制。相同版本的未修改文件可重复运行脚本。 + +从旧版迁移时,先把已有的 SDK 源码和许可证合并到 `src/sdk/`。按文件所在位置,将业务代码及 +先前复制的组件和示例中的旧 SDK 导入改为指向公开源码的相对路径。核对代码已使用新路径后, +可清理前版的 `#kit-sdk/` 映射或旧的 `@openagentpack/kit-sdk` 本地包依赖。 + +接入完成后,在应用中运行类型检查和构建。需要真实对话时,另外验证应用自己的后端和网络配置。 + +## 接入三栏会话页 + +使用 `use-kit-chat` Skill 时,用下面的命令复制完整三栏示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" --example experience.tsx +``` + +从 `src/kit-examples/use-kit-chat/experience.tsx` 导入 `Experience`。该命令还会复制同目录的 +资源面板和审批列表,以及它们所用的组件。为页面提供稳定的 Client、Provider 和应用回调,并导入本地主题。 diff --git a/assets/skills/kit-chat-provider/references/examples.md b/assets/skills/kit-chat-provider/references/examples.md index 6464715..ac52d60 100644 --- a/assets/skills/kit-chat-provider/references/examples.md +++ b/assets/skills/kit-chat-provider/references/examples.md @@ -1,6 +1,6 @@ # 可编译示例 -本页由随附的示例源文件生成。请按应用需求调整回调和运行时配置。 +本页展示仓库中的示例源文件。按[复制组件和 Kit SDK](copy-in.md)用 `--example` 接入应用,脚本会生成相对导入路径。 ## backend-data.ts diff --git a/assets/skills/kit-chat-provider/scripts/copy-in.mjs b/assets/skills/kit-chat-provider/scripts/copy-in.mjs new file mode 100644 index 0000000..beab29b --- /dev/null +++ b/assets/skills/kit-chat-provider/scripts/copy-in.mjs @@ -0,0 +1,37 @@ +import { cpSync, mkdirSync, readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; + +export const sdkTarget = "src/sdk"; +export const componentTarget = "src/components/kit"; +export const exampleTarget = (skill) => `src/kit-examples/${skill}`; + +export function readRegistry(elementsRoot) { + return JSON.parse(readFileSync(join(elementsRoot, "registry.json"), "utf8")); +} + +/** 解析组件及其传递依赖的闭包;未知组件返回 null。 */ +export function resolveComponentClosure(registry, name) { + const wanted = [name]; + const seen = new Set(); + while (wanted.length) { + const current = wanted.pop(); + if (seen.has(current)) continue; + seen.add(current); + const entry = registry.components[current]; + if (!entry) return null; + wanted.push(...entry.deps); + } + return seen; +} + +/** 落点保留 src/components/ 下的子目录层级:组件间的相对导入依赖它。 */ +export function componentDestPath(entryFile) { + return entryFile.replace(/^src\/components\//, ""); +} + +export function copyComponentSource(elementsRoot, entryFile, targetDir) { + const to = join(targetDir, componentDestPath(entryFile)); + mkdirSync(dirname(to), { recursive: true }); + cpSync(join(elementsRoot, entryFile), to); + return to; +} diff --git a/assets/skills/kit-chat-provider/scripts/install.mjs b/assets/skills/kit-chat-provider/scripts/install.mjs new file mode 100644 index 0000000..19f6640 --- /dev/null +++ b/assets/skills/kit-chat-provider/scripts/install.mjs @@ -0,0 +1,186 @@ +import { + lstatSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + realpathSync, + renameSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { dirname, join, relative, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; +import { parseArgs } from "node:util"; +import { + componentDestPath, + componentTarget, + exampleTarget, + readRegistry, + resolveComponentClosure, + sdkTarget, +} from "./copy-in.mjs"; + +const sdkName = "@openagentpack/kit-sdk"; +const assetRoot = fileURLToPath(new URL("../assets/kit/", import.meta.url)); +const usage = "用法:node /scripts/install.mjs --dir <项目目录> [--example <文件> ...] [组件名 ...]"; + +function addTree(plan, source, target) { + for (const entry of readdirSync(source, { withFileTypes: true })) { + const input = join(source, entry.name); + const output = join(target, entry.name); + if (entry.isDirectory()) addTree(plan, input, output); + else if (entry.isFile()) plan.set(output, readFileSync(input)); + else throw new Error(`无效的 Skill 资产:${entry.name}`); + } +} + +function planExamples(plan, selected, project) { + if (!selected.length) return { components: [] }; + const source = join(assetRoot, "examples"); + const { skill, examples } = JSON.parse(readFileSync(join(source, "copy-in.json"), "utf8")); + const directory = exampleTarget(skill); + const pending = [...selected]; + const visited = new Set(); + const components = new Set(); + while (pending.length) { + const file = pending.pop(); + if (visited.has(file)) continue; + visited.add(file); + if (!Object.hasOwn(examples, file)) throw new Error(`未知示例 ${file},可选:${Object.keys(examples).join("、")}`); + const example = examples[file]; + plan.set(join(project, directory, file), readFileSync(join(source, file))); + pending.push(...example.companions); + for (const component of example.components) components.add(component); + } + return { components: [...components], directory }; +} + +function planComponents(plan, selected, project) { + if (!selected.length) return {}; + const source = join(assetRoot, "chat-ui"); + const registry = readRegistry(source); + const versions = JSON.parse(readFileSync(join(source, "dependencies.json"), "utf8")); + const components = new Set(); + for (const name of selected) { + const closure = Object.hasOwn(registry.components, name) && resolveComponentClosure(registry, name); + if (!closure) throw new Error(`未知组件 ${name},可选:${Object.keys(registry.components).join("、")}`); + for (const component of closure) components.add(component); + } + const target = join(project, componentTarget); + const entries = [...components].map((component) => registry.components[component]); + for (const { file } of entries) plan.set(join(target, componentDestPath(file)), readFileSync(join(source, file))); + const dependencies = {}; + for (const name of new Set(entries.flatMap((entry) => entry.npmDependencies ?? []))) { + if (name === sdkName) continue; + if (!versions[name]) throw new Error(`组件清单缺少依赖 ${name} 的版本。`); + dependencies[name] = versions[name]; + } + plan.set(join(target, "theme.css"), readFileSync(join(source, registry.theme))); + plan.set(join(target, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + return dependencies; +} + +function mergeDependencies(manifest, dependencies) { + const groups = [ + manifest.dependencies, + manifest.devDependencies, + manifest.optionalDependencies, + manifest.peerDependencies, + ]; + if (groups.some((group) => group && Object.hasOwn(group, sdkName))) { + throw new Error(`项目已声明 ${sdkName} 包依赖。切换源码接入时,请按 Skill 指引迁移导入并移除此依赖。`); + } + const additions = Object.fromEntries( + Object.entries(dependencies).filter(([name]) => !groups.some((group) => group && Object.hasOwn(group, name))), + ); + return { ...manifest, dependencies: { ...manifest.dependencies, ...additions } }; +} + +function checkDestinations(project, plan) { + const pending = new Map(); + const conflicts = []; + for (const [file, content] of plan) { + const path = relative(project, file); + const segments = path.split(sep); + if (segments[0] === "..") throw new Error(`目标文件越出项目目录:${path}`); + let parent = project; + for (const segment of segments.slice(0, -1)) { + parent = join(parent, segment); + const stat = lstatSync(parent, { throwIfNoEntry: false }); + if (stat && !stat.isDirectory()) throw new Error(`目标目录不可用:${relative(project, parent)}`); + } + const stat = lstatSync(file, { throwIfNoEntry: false }); + if (!stat) pending.set(file, content); + else if (!stat.isFile() || !readFileSync(file).equals(content)) conflicts.push(path); + } + if (conflicts.length) + throw new Error(`以下文件与 Skill 资产有差异,请先合并或保留现有版本:\n${conflicts.join("\n")}`); + return pending; +} + +function updateManifest(file, previous, manifest) { + if (JSON.stringify(JSON.parse(previous)) === JSON.stringify(manifest)) return; + const indent = previous.match(/^([\t ]+)"/m)?.[1] ?? " "; + const lineEnding = previous.includes("\r\n") ? "\r\n" : "\n"; + const next = `${JSON.stringify(manifest, null, indent)}\n`.replaceAll("\n", lineEnding); + const directory = mkdtempSync(join(dirname(file), ".kit-copy-in-")); + try { + const staging = join(directory, "package.json"); + writeFileSync(staging, next, { mode: lstatSync(file).mode }); + if (readFileSync(file, "utf8") !== previous) throw new Error("并行修改了 package.json,请检查后重试。"); + renameSync(staging, file); + } finally { + rmSync(directory, { recursive: true, force: true }); + } +} + +function install(directory, components, examples) { + const project = realpathSync(resolve(directory)); + const packagePath = join(project, "package.json"); + if (!lstatSync(packagePath, { throwIfNoEntry: false })?.isFile()) { + throw new Error("--dir 必须指向包含 package.json 的应用目录。"); + } + const previous = readFileSync(packagePath, "utf8"); + const manifest = JSON.parse(previous); + const sdk = join(assetRoot, "sdk"); + const sdkMetadata = join(sdk, "copy-in.json"); + if (!lstatSync(sdkMetadata, { throwIfNoEntry: false })?.isFile()) { + throw new Error("缺少 Kit SDK 资产。请解压完整的 Skill 离线包并使用其中的目录。"); + } + const { dependencies } = JSON.parse(readFileSync(sdkMetadata, "utf8")); + const plan = new Map(); + addTree(plan, join(sdk, "src"), join(project, sdkTarget)); + plan.set(join(project, sdkTarget, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + const examplePlan = planExamples(plan, examples, project); + const selected = [...components, ...examplePlan.components]; + const nextManifest = mergeDependencies(manifest, { + ...dependencies, + ...planComponents(plan, selected, project), + }); + const pending = checkDestinations(project, plan); + for (const [file, content] of pending) { + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, content, { flag: "wx" }); + } + updateManifest(packagePath, previous, nextManifest); + process.stdout.write(`已就绪:${sdkTarget}。\n`); + if (selected.length) process.stdout.write(`已就绪:${componentTarget},包括组件依赖和 theme.css。\n`); + if (examplePlan.directory) process.stdout.write(`已就绪:${examplePlan.directory},包括示例依赖。\n`); + process.stdout.write("请使用目标项目的包管理器安装依赖并更新锁文件。\n"); +} + +try { + const { values, positionals } = parseArgs({ + options: { dir: { type: "string" }, example: { type: "string", multiple: true }, help: { type: "boolean" } }, + allowPositionals: true, + }); + if (values.help) process.stdout.write(`${usage}\n`); + else { + if (!values.dir) throw new Error(usage); + install(values.dir, positionals, values.example ?? []); + } +} catch (error) { + process.stderr.write(`${error.message}\n`); + process.exitCode = 1; +} diff --git a/assets/skills/kit-components/SKILL.md b/assets/skills/kit-components/SKILL.md index ea436ab..5cc1cc3 100644 --- a/assets/skills/kit-components/SKILL.md +++ b/assets/skills/kit-components/SKILL.md @@ -5,8 +5,8 @@ description: "用 OpenAgentPack Kit 的 React 组件搭建对话界面,包括 # Kit 对话组件 -用 `@openagentpack/kit-chat-ui` 的公开组件搭建所需界面。示例使用包导入。 -通过 copy-in 引入的项目应改为从本地组件路径导入。 +用 Kit 的公开组件搭建所需界面。先按[复制组件和 Kit SDK](references/copy-in.md)将所需组件、 +主题和 SDK 源码复制进应用。用 `--example` 复制示例时,脚本会生成组件和 SDK 的相对导入路径。 ## 选择页面组合 @@ -40,8 +40,7 @@ description: "用 OpenAgentPack Kit 的 React 组件搭建对话界面,包括 文件上传成功后仍需显式挂载到会话。 5. 工具审批与破坏性操作都需显式确认。`ToolApprovalCard` 提交一次经审阅的决定,并等待服务端权威状态。 破坏性操作由应用获取计划和确认令牌。 -6. 使用 Tailwind 工具类和已有 `--kit-*` token。即使组件位于 workspace 或链接包中, - 也要确保 Tailwind 能扫描组件源码。 +6. 使用 Tailwind 工具类和已有 `--kit-*` token,确保 Tailwind 能扫描复制后的组件源码。 ## 示例 diff --git a/assets/skills/kit-components/references/api.md b/assets/skills/kit-components/references/api.md index 4989e5b..c40083d 100644 --- a/assets/skills/kit-components/references/api.md +++ b/assets/skills/kit-components/references/api.md @@ -3,6 +3,7 @@ 本页由 `pnpm gen:skills` 生成。更新公开 TypeScript 声明或中文 catalog 后重新生成。 字段类型和必填性来自公开 API,行为说明依据所列文档整理。 组件表格列出 Kit 自有属性。组件按声明继承标准的 React/DOM 属性。 +参考中的包名用于仓库内导入。业务项目按[复制组件和 Kit SDK](copy-in.md)改用本地源码入口。 ## 目录 diff --git a/assets/skills/kit-components/references/copy-in.md b/assets/skills/kit-components/references/copy-in.md new file mode 100644 index 0000000..dbbc585 --- /dev/null +++ b/assets/skills/kit-components/references/copy-in.md @@ -0,0 +1,87 @@ +# 将组件和 Kit SDK 复制进项目 + +使用完整的 Skill 离线包。其 `assets/kit/` 带有匹配示例版本的组件源码、registry 和 Kit SDK。 +也可以在 Kit 仓库运行 `pnpm pack:skills`,从 `assets/skills/dist/` 解压对应的离线包。 +Copy-in 脚本可以用 Node.js 直接运行。 + +## 复制到应用 + +1. 找到待接入应用的 `package.json`。在 monorepo 中选择实际消费 Kit 的成员包。 +2. 用 `--example` 选择当前 Skill 的示例文件,或传入页面需要的组件条目名。组件清单位于 + `assets/kit/chat-ui/registry.json`。脚本会复制选中示例的随附文件、组件及其传递依赖和主题。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" chat +``` + +只使用 SDK 数据入口、hooks 或后端适配时,可以省略组件名和示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" +``` + +SDK 源码位于应用的 `src/sdk/`。组件复制到 `src/components/kit/`, +通过 `--example` 复制的示例位于 `src/kit-examples//`。脚本已为这些文件生成 +相对导入路径。参考中的原始示例保留仓库的包导入,接入应用时先使用脚本生成可直接引用的源码。 + +业务代码也可按文件位置导入 SDK 的公开源码入口。例如在 `src/App.tsx` 中导入 `useChat`。 + +```tsx +import { useChat } from "./sdk/chat/hooks/index.ts"; +``` + +按功能入口导入 SDK,例如消息类型位于 `src/sdk/messages/index.ts`。由宿主应用的工具链统一编译这些源码。 + +脚本会在应用的 `package.json` 中补上缺少的 SDK 和组件依赖,例如上游 `@openagentpack/sdk` +和 `zod`。用应用现有的包管理器执行安装并更新锁文件。应用已有同名依赖时,核对实际解析版本是否与 +Skill 的 `assets/kit/sdk/copy-in.json` 兼容。React 页面使用宿主的 React 和同主版本的 React DOM。 + +将 `src/sdk/` 随应用提交。SDK 使用 `findLast` 和 `toReversed` 等 +ES2023 API,应用的 TypeScript `lib` 应包含 `ES2023` 或更新版本,Web 项目继续保留 DOM 类型。 +Node.js 宿主可以用已有的 TypeScript 运行器,例如安装 `tsx` 后运行 `node --import tsx src/main.ts`, +或通过应用的打包器一起编译。 +仅用数据入口时,如果 `tsconfig.json` 会扫描整个 `src/`,可将 `src/sdk` 加入 `exclude`。 +TypeScript 仍会检查应用实际导入的 SDK 模块。 + +## 使用复制后的 UI + +脚本已改写复制后示例的组件导入。自己编写的页面可从 `src/components/kit/` 按文件位置导入。 +组件文件的层级与 registry 中 `src/components/` 后面的路径一致。例如在应用的 `src/App.tsx` 中: + +```tsx +import { Chat } from "./components/kit/chat/index.tsx"; +import { SessionSidebar } from "./components/kit/session-sidebar/index.tsx"; +``` + +复制的源码保留 `.ts` 和 `.tsx` 导入后缀。由打包器输出 JavaScript 的 TypeScript 项目可用 +`noEmit` 和 `allowImportingTsExtensions` 检查这些文件。 + +在 Tailwind v4 的应用样式入口导入本地主题并确保扫描本地组件源码。Vite 项目初次接入时, +安装 `tailwindcss` 与 `@tailwindcss/vite` 并在 Vite 配置中注册 `tailwindcss()` 插件。 +应用样式文件位于 `src/` 时,可以这样引入: + +```css +@import "tailwindcss"; +@import "./components/kit/theme.css"; +@source "./components/kit"; +``` + +遇到内容不同的本地组件、SDK 源码或示例时,脚本会在写入前报告冲突。先核对差异, +保留需要的定制。相同版本的未修改文件可重复运行脚本。 + +从旧版迁移时,先把已有的 SDK 源码和许可证合并到 `src/sdk/`。按文件所在位置,将业务代码及 +先前复制的组件和示例中的旧 SDK 导入改为指向公开源码的相对路径。核对代码已使用新路径后, +可清理前版的 `#kit-sdk/` 映射或旧的 `@openagentpack/kit-sdk` 本地包依赖。 + +接入完成后,在应用中运行类型检查和构建。需要真实对话时,另外验证应用自己的后端和网络配置。 + +## 接入三栏会话页 + +使用 `use-kit-chat` Skill 时,用下面的命令复制完整三栏示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" --example experience.tsx +``` + +从 `src/kit-examples/use-kit-chat/experience.tsx` 导入 `Experience`。该命令还会复制同目录的 +资源面板和审批列表,以及它们所用的组件。为页面提供稳定的 Client、Provider 和应用回调,并导入本地主题。 diff --git a/assets/skills/kit-components/references/examples.md b/assets/skills/kit-components/references/examples.md index 77b03c3..2256ab0 100644 --- a/assets/skills/kit-components/references/examples.md +++ b/assets/skills/kit-components/references/examples.md @@ -1,6 +1,6 @@ # 可编译示例 -本页由随附的示例源文件生成。请按应用需求调整回调和运行时配置。 +本页展示仓库中的示例源文件。按[复制组件和 Kit SDK](copy-in.md)用 `--example` 接入应用,脚本会生成相对导入路径。 ## agent-icon.tsx diff --git a/assets/skills/kit-components/references/setup.md b/assets/skills/kit-components/references/setup.md index b8638f0..7e4076d 100644 --- a/assets/skills/kit-components/references/setup.md +++ b/assets/skills/kit-components/references/setup.md @@ -1,27 +1,10 @@ # 安装与源码归属 -## 从包导入 +## 接入组件和主题 -示例从 `@openagentpack/kit-chat-ui` 导入公开 API,并从 `@openagentpack/kit-sdk/messages` -及 `@openagentpack/kit-sdk/protocol` 导入类型。使用示例的 workspace 需要能访问这些包, -并提供兼容的 React 和 React DOM。当前仓库的 Kit 包为私有 workspace 包,以实际发布情况为准。 - -在已有 Tailwind v4 样式入口导入主题。 - -```css -@import "tailwindcss"; -@import "@openagentpack/kit-chat-ui/theme.css"; -``` - -为组件实际源码位置添加 Tailwind `@source`。自动扫描跳过 `node_modules`,也可能漏掉 -workspace 符号链接。仓库的 `apps/web/src/styles.css` 使用以下路径。 - -```css -@source "../../../packages/chat-ui/src/**/*.{ts,tsx}"; -``` - -该路径相对于样式表。copy-in 项目应改为扫描本地组件目录。 -在生成的 CSS 中检查响应式工具类和主题工具类。 +按[复制组件和 Kit SDK](copy-in.md)接入私有 Kit 依赖。复制的组件通过应用内源码路径导入, +类型通过 `src/sdk/messages/index.ts` 与 `src/sdk/protocol/index.ts` 读取。 +在已有 Tailwind v4 样式入口导入本地主题,检查生成的 CSS 包含所需的响应式工具类和主题工具类。 主题默认浅色,在主题作用域上设置 `data-kit-theme="dark"` 切换为深色。 员工端配色显式设置 `data-kit-appearance="workspace"`,支持的组件用 `variant="workspace"` @@ -30,9 +13,8 @@ workspace 符号链接。仓库的 `apps/web/src/styles.css` 使用以下路径 ## 复制组件源码 -从 Kit 仓库运行 `pnpm kit:add --dir `,将组件源码及登记的依赖复制到现有项目。 -也可以在目标项目通过绝对路径运行 `scripts/kit/add-component.mjs`。 -Registry 按源码文件分组,完整的公开组件名单见 [API 参考](api.md)。 +将下表的 registry 条目名传给 Skill 的复制脚本。Registry 按源码文件分组, +完整的公开组件名单见 [API 参考](api.md)。 | Registry 条目 | 可用组件 | | --- | --- | @@ -58,11 +40,8 @@ Registry 按源码文件分组,完整的公开组件名单见 [API 参考](api | `mermaid` | `Mermaid`、Actions 和 CodeHighlighter | | `tool-approval` | `ToolApprovalCard` 和 `ToolApprovalGroup` | -使用 copy-in 时在目标项目另行安装 npm 依赖。Markdown 使用 `react-markdown`、`remark-gfm`、 -`rehype-sanitize`、`lowlight` 和 `mermaid`。工具审批与确认使用 `@radix-ui/react-alert-dialog`。 -Layout 使用 `@radix-ui/react-dialog` 和 `@openagentpack/kit-sdk/hooks`。 -版本以目标项目与组件 registry、包清单共同支持的范围为准。更新已复制的组件前先查看源码差异, -合并需要保留的本地修改。 +组件所需的 npm 依赖随 registry 选择。Layout 还通过本地 SDK 的 `src/sdk/hooks/index.ts` +获取屏幕尺寸;确认弹窗通过 `@radix-ui/react-alert-dialog` 管理显式确认。 ## 运行时边界 diff --git a/assets/skills/kit-components/scripts/copy-in.mjs b/assets/skills/kit-components/scripts/copy-in.mjs new file mode 100644 index 0000000..beab29b --- /dev/null +++ b/assets/skills/kit-components/scripts/copy-in.mjs @@ -0,0 +1,37 @@ +import { cpSync, mkdirSync, readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; + +export const sdkTarget = "src/sdk"; +export const componentTarget = "src/components/kit"; +export const exampleTarget = (skill) => `src/kit-examples/${skill}`; + +export function readRegistry(elementsRoot) { + return JSON.parse(readFileSync(join(elementsRoot, "registry.json"), "utf8")); +} + +/** 解析组件及其传递依赖的闭包;未知组件返回 null。 */ +export function resolveComponentClosure(registry, name) { + const wanted = [name]; + const seen = new Set(); + while (wanted.length) { + const current = wanted.pop(); + if (seen.has(current)) continue; + seen.add(current); + const entry = registry.components[current]; + if (!entry) return null; + wanted.push(...entry.deps); + } + return seen; +} + +/** 落点保留 src/components/ 下的子目录层级:组件间的相对导入依赖它。 */ +export function componentDestPath(entryFile) { + return entryFile.replace(/^src\/components\//, ""); +} + +export function copyComponentSource(elementsRoot, entryFile, targetDir) { + const to = join(targetDir, componentDestPath(entryFile)); + mkdirSync(dirname(to), { recursive: true }); + cpSync(join(elementsRoot, entryFile), to); + return to; +} diff --git a/assets/skills/kit-components/scripts/install.mjs b/assets/skills/kit-components/scripts/install.mjs new file mode 100644 index 0000000..19f6640 --- /dev/null +++ b/assets/skills/kit-components/scripts/install.mjs @@ -0,0 +1,186 @@ +import { + lstatSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + realpathSync, + renameSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { dirname, join, relative, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; +import { parseArgs } from "node:util"; +import { + componentDestPath, + componentTarget, + exampleTarget, + readRegistry, + resolveComponentClosure, + sdkTarget, +} from "./copy-in.mjs"; + +const sdkName = "@openagentpack/kit-sdk"; +const assetRoot = fileURLToPath(new URL("../assets/kit/", import.meta.url)); +const usage = "用法:node /scripts/install.mjs --dir <项目目录> [--example <文件> ...] [组件名 ...]"; + +function addTree(plan, source, target) { + for (const entry of readdirSync(source, { withFileTypes: true })) { + const input = join(source, entry.name); + const output = join(target, entry.name); + if (entry.isDirectory()) addTree(plan, input, output); + else if (entry.isFile()) plan.set(output, readFileSync(input)); + else throw new Error(`无效的 Skill 资产:${entry.name}`); + } +} + +function planExamples(plan, selected, project) { + if (!selected.length) return { components: [] }; + const source = join(assetRoot, "examples"); + const { skill, examples } = JSON.parse(readFileSync(join(source, "copy-in.json"), "utf8")); + const directory = exampleTarget(skill); + const pending = [...selected]; + const visited = new Set(); + const components = new Set(); + while (pending.length) { + const file = pending.pop(); + if (visited.has(file)) continue; + visited.add(file); + if (!Object.hasOwn(examples, file)) throw new Error(`未知示例 ${file},可选:${Object.keys(examples).join("、")}`); + const example = examples[file]; + plan.set(join(project, directory, file), readFileSync(join(source, file))); + pending.push(...example.companions); + for (const component of example.components) components.add(component); + } + return { components: [...components], directory }; +} + +function planComponents(plan, selected, project) { + if (!selected.length) return {}; + const source = join(assetRoot, "chat-ui"); + const registry = readRegistry(source); + const versions = JSON.parse(readFileSync(join(source, "dependencies.json"), "utf8")); + const components = new Set(); + for (const name of selected) { + const closure = Object.hasOwn(registry.components, name) && resolveComponentClosure(registry, name); + if (!closure) throw new Error(`未知组件 ${name},可选:${Object.keys(registry.components).join("、")}`); + for (const component of closure) components.add(component); + } + const target = join(project, componentTarget); + const entries = [...components].map((component) => registry.components[component]); + for (const { file } of entries) plan.set(join(target, componentDestPath(file)), readFileSync(join(source, file))); + const dependencies = {}; + for (const name of new Set(entries.flatMap((entry) => entry.npmDependencies ?? []))) { + if (name === sdkName) continue; + if (!versions[name]) throw new Error(`组件清单缺少依赖 ${name} 的版本。`); + dependencies[name] = versions[name]; + } + plan.set(join(target, "theme.css"), readFileSync(join(source, registry.theme))); + plan.set(join(target, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + return dependencies; +} + +function mergeDependencies(manifest, dependencies) { + const groups = [ + manifest.dependencies, + manifest.devDependencies, + manifest.optionalDependencies, + manifest.peerDependencies, + ]; + if (groups.some((group) => group && Object.hasOwn(group, sdkName))) { + throw new Error(`项目已声明 ${sdkName} 包依赖。切换源码接入时,请按 Skill 指引迁移导入并移除此依赖。`); + } + const additions = Object.fromEntries( + Object.entries(dependencies).filter(([name]) => !groups.some((group) => group && Object.hasOwn(group, name))), + ); + return { ...manifest, dependencies: { ...manifest.dependencies, ...additions } }; +} + +function checkDestinations(project, plan) { + const pending = new Map(); + const conflicts = []; + for (const [file, content] of plan) { + const path = relative(project, file); + const segments = path.split(sep); + if (segments[0] === "..") throw new Error(`目标文件越出项目目录:${path}`); + let parent = project; + for (const segment of segments.slice(0, -1)) { + parent = join(parent, segment); + const stat = lstatSync(parent, { throwIfNoEntry: false }); + if (stat && !stat.isDirectory()) throw new Error(`目标目录不可用:${relative(project, parent)}`); + } + const stat = lstatSync(file, { throwIfNoEntry: false }); + if (!stat) pending.set(file, content); + else if (!stat.isFile() || !readFileSync(file).equals(content)) conflicts.push(path); + } + if (conflicts.length) + throw new Error(`以下文件与 Skill 资产有差异,请先合并或保留现有版本:\n${conflicts.join("\n")}`); + return pending; +} + +function updateManifest(file, previous, manifest) { + if (JSON.stringify(JSON.parse(previous)) === JSON.stringify(manifest)) return; + const indent = previous.match(/^([\t ]+)"/m)?.[1] ?? " "; + const lineEnding = previous.includes("\r\n") ? "\r\n" : "\n"; + const next = `${JSON.stringify(manifest, null, indent)}\n`.replaceAll("\n", lineEnding); + const directory = mkdtempSync(join(dirname(file), ".kit-copy-in-")); + try { + const staging = join(directory, "package.json"); + writeFileSync(staging, next, { mode: lstatSync(file).mode }); + if (readFileSync(file, "utf8") !== previous) throw new Error("并行修改了 package.json,请检查后重试。"); + renameSync(staging, file); + } finally { + rmSync(directory, { recursive: true, force: true }); + } +} + +function install(directory, components, examples) { + const project = realpathSync(resolve(directory)); + const packagePath = join(project, "package.json"); + if (!lstatSync(packagePath, { throwIfNoEntry: false })?.isFile()) { + throw new Error("--dir 必须指向包含 package.json 的应用目录。"); + } + const previous = readFileSync(packagePath, "utf8"); + const manifest = JSON.parse(previous); + const sdk = join(assetRoot, "sdk"); + const sdkMetadata = join(sdk, "copy-in.json"); + if (!lstatSync(sdkMetadata, { throwIfNoEntry: false })?.isFile()) { + throw new Error("缺少 Kit SDK 资产。请解压完整的 Skill 离线包并使用其中的目录。"); + } + const { dependencies } = JSON.parse(readFileSync(sdkMetadata, "utf8")); + const plan = new Map(); + addTree(plan, join(sdk, "src"), join(project, sdkTarget)); + plan.set(join(project, sdkTarget, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + const examplePlan = planExamples(plan, examples, project); + const selected = [...components, ...examplePlan.components]; + const nextManifest = mergeDependencies(manifest, { + ...dependencies, + ...planComponents(plan, selected, project), + }); + const pending = checkDestinations(project, plan); + for (const [file, content] of pending) { + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, content, { flag: "wx" }); + } + updateManifest(packagePath, previous, nextManifest); + process.stdout.write(`已就绪:${sdkTarget}。\n`); + if (selected.length) process.stdout.write(`已就绪:${componentTarget},包括组件依赖和 theme.css。\n`); + if (examplePlan.directory) process.stdout.write(`已就绪:${examplePlan.directory},包括示例依赖。\n`); + process.stdout.write("请使用目标项目的包管理器安装依赖并更新锁文件。\n"); +} + +try { + const { values, positionals } = parseArgs({ + options: { dir: { type: "string" }, example: { type: "string", multiple: true }, help: { type: "boolean" } }, + allowPositionals: true, + }); + if (values.help) process.stdout.write(`${usage}\n`); + else { + if (!values.dir) throw new Error(usage); + install(values.dir, positionals, values.example ?? []); + } +} catch (error) { + process.stderr.write(`${error.message}\n`); + process.exitCode = 1; +} diff --git a/assets/skills/use-kit-chat/SKILL.md b/assets/skills/use-kit-chat/SKILL.md index 4d08818..55df1b2 100644 --- a/assets/skills/use-kit-chat/SKILL.md +++ b/assets/skills/use-kit-chat/SKILL.md @@ -8,12 +8,16 @@ description: "将 React 对话页面接入 OpenAgentPack Kit 的 useChat,串 让一个 `useChat` 实例持有一个会话,再将状态传给页面的消息、输入和审批组件。 `ChatProvider` 连接业务后端,React 的 `KitProvider` 为应用提供默认 KitClient Context。 +按[复制组件和 Kit SDK](references/copy-in.md)用 `--example` 接入所选示例。脚本会连同 +SDK、所需组件和随附示例一起复制,并生成相对导入路径。 + ## 选择接入入口 - **完整会话页或工作台**可从[三栏会话页](examples/experience.tsx)开始。左侧 `SessionSidebar`、 中间 `Chat` 和右侧 [Agent 资源面板](examples/agent-resources-panel.tsx)共享同一套 Agent 和会话选择。 - 一并复制面板和[审批列表](examples/approval-list.tsx),提供稳定的 Client、ChatProvider 和产物操作宿主。 - 导入 `@openagentpack/kit-chat-ui/theme.css`,并把示例及组件源码纳入 Tailwind v4 的扫描范围。 + 用[三栏示例复制命令](references/copy-in.md#接入三栏会话页)一并接入面板和[审批列表](examples/approval-list.tsx), + 提供稳定的 Client、ChatProvider 和产物操作宿主。导入本地主题, + 并把示例及组件源码纳入 Tailwind v4 的扫描范围。 - **Kit Server 和自建后端**使用 `useChat({ sessionId, provider })`。标准事件后端可配置 `createSessionEventChatProvider`,Web 应用走相同入口,见[自建后端示例](examples/custom-chat.tsx)。 - **已有 KitClient 的应用**可继续在 `KitProvider` 内使用 `useChat(sessionId)`, @@ -25,7 +29,7 @@ description: "将 React 对话页面接入 OpenAgentPack Kit 的 useChat,串 让显式 Provider 复用相同的固定身份与取消边界,再将 `auth.chatProvider` 传给 `useChat`。 - **已有自定义后端适配器**可直接使用 `useChat({ sessionId, provider })`, 无需 `KitProvider`,见[自建后端示例](examples/custom-chat.tsx)。 -- **非 React 宿主**从 `@openagentpack/kit-sdk/chat` 导入 `createChatController`, +- **非 React 宿主**从应用的 `src/sdk/chat/index.ts` 导入 `createChatController`, 显式订阅及销毁,见[控制器示例](examples/controller.ts)。 - 拿到真实会话 ID 前传入 `null`。创建和列出会话通过独立接口完成。 - **Kit Server 的发现和用量**在 `KitProvider` 中使用 `usePlaza`、`useQuota` 和 `useQuotaRequests`, @@ -54,8 +58,9 @@ description: "将 React 对话页面接入 OpenAgentPack Kit 的 useChat,串 按 `useChat` 的公开接口接入。禁止自行添加 `setMessages`、消息编辑、重新生成或请求队列, 也禁止自动重发失败的写请求。数据 Hook 接受显式 `client`,`useKitClient` 保留 Context 兼容入口。 -自定义 ChatProvider 接管对话传输。数据操作单独通过 `createKitClient({ request, operations })` 配置, -见[三栏会话页](examples/experience.tsx)。额度增加申请属于独立业务,由用户显式触发后调用 +自定义 ChatProvider 接管对话传输。数据操作通过本地 `src/sdk/providers/kit/index.ts` 的 +`createKitClient({ request, operations })` 配置。宿主创建稳定的 Client 和 Provider 并将其传给 +[三栏会话页](examples/experience.tsx)。额度增加申请属于独立业务,由用户显式触发后调用 `useCreateQuotaRequest().submit`,然后刷新用量及申请历史。 复用 `useAttachments` 和 `useArtifactActions` 管理上传与下载。文件选择、预览窗口和保存由宿主负责。 diff --git a/assets/skills/use-kit-chat/references/api.md b/assets/skills/use-kit-chat/references/api.md index 3b40d4e..8ef974e 100644 --- a/assets/skills/use-kit-chat/references/api.md +++ b/assets/skills/use-kit-chat/references/api.md @@ -3,6 +3,7 @@ 本页由 `pnpm gen:skills` 生成。更新公开 TypeScript 声明或中文 catalog 后重新生成。 字段类型和必填性来自公开 API,行为说明依据所列文档整理。 组件表格列出 Kit 自有属性。组件按声明继承标准的 React/DOM 属性。 +参考中的包名用于仓库内导入。业务项目按[复制组件和 Kit SDK](copy-in.md)改用本地源码入口。 ## 目录 diff --git a/assets/skills/use-kit-chat/references/copy-in.md b/assets/skills/use-kit-chat/references/copy-in.md new file mode 100644 index 0000000..dbbc585 --- /dev/null +++ b/assets/skills/use-kit-chat/references/copy-in.md @@ -0,0 +1,87 @@ +# 将组件和 Kit SDK 复制进项目 + +使用完整的 Skill 离线包。其 `assets/kit/` 带有匹配示例版本的组件源码、registry 和 Kit SDK。 +也可以在 Kit 仓库运行 `pnpm pack:skills`,从 `assets/skills/dist/` 解压对应的离线包。 +Copy-in 脚本可以用 Node.js 直接运行。 + +## 复制到应用 + +1. 找到待接入应用的 `package.json`。在 monorepo 中选择实际消费 Kit 的成员包。 +2. 用 `--example` 选择当前 Skill 的示例文件,或传入页面需要的组件条目名。组件清单位于 + `assets/kit/chat-ui/registry.json`。脚本会复制选中示例的随附文件、组件及其传递依赖和主题。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" chat +``` + +只使用 SDK 数据入口、hooks 或后端适配时,可以省略组件名和示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" +``` + +SDK 源码位于应用的 `src/sdk/`。组件复制到 `src/components/kit/`, +通过 `--example` 复制的示例位于 `src/kit-examples//`。脚本已为这些文件生成 +相对导入路径。参考中的原始示例保留仓库的包导入,接入应用时先使用脚本生成可直接引用的源码。 + +业务代码也可按文件位置导入 SDK 的公开源码入口。例如在 `src/App.tsx` 中导入 `useChat`。 + +```tsx +import { useChat } from "./sdk/chat/hooks/index.ts"; +``` + +按功能入口导入 SDK,例如消息类型位于 `src/sdk/messages/index.ts`。由宿主应用的工具链统一编译这些源码。 + +脚本会在应用的 `package.json` 中补上缺少的 SDK 和组件依赖,例如上游 `@openagentpack/sdk` +和 `zod`。用应用现有的包管理器执行安装并更新锁文件。应用已有同名依赖时,核对实际解析版本是否与 +Skill 的 `assets/kit/sdk/copy-in.json` 兼容。React 页面使用宿主的 React 和同主版本的 React DOM。 + +将 `src/sdk/` 随应用提交。SDK 使用 `findLast` 和 `toReversed` 等 +ES2023 API,应用的 TypeScript `lib` 应包含 `ES2023` 或更新版本,Web 项目继续保留 DOM 类型。 +Node.js 宿主可以用已有的 TypeScript 运行器,例如安装 `tsx` 后运行 `node --import tsx src/main.ts`, +或通过应用的打包器一起编译。 +仅用数据入口时,如果 `tsconfig.json` 会扫描整个 `src/`,可将 `src/sdk` 加入 `exclude`。 +TypeScript 仍会检查应用实际导入的 SDK 模块。 + +## 使用复制后的 UI + +脚本已改写复制后示例的组件导入。自己编写的页面可从 `src/components/kit/` 按文件位置导入。 +组件文件的层级与 registry 中 `src/components/` 后面的路径一致。例如在应用的 `src/App.tsx` 中: + +```tsx +import { Chat } from "./components/kit/chat/index.tsx"; +import { SessionSidebar } from "./components/kit/session-sidebar/index.tsx"; +``` + +复制的源码保留 `.ts` 和 `.tsx` 导入后缀。由打包器输出 JavaScript 的 TypeScript 项目可用 +`noEmit` 和 `allowImportingTsExtensions` 检查这些文件。 + +在 Tailwind v4 的应用样式入口导入本地主题并确保扫描本地组件源码。Vite 项目初次接入时, +安装 `tailwindcss` 与 `@tailwindcss/vite` 并在 Vite 配置中注册 `tailwindcss()` 插件。 +应用样式文件位于 `src/` 时,可以这样引入: + +```css +@import "tailwindcss"; +@import "./components/kit/theme.css"; +@source "./components/kit"; +``` + +遇到内容不同的本地组件、SDK 源码或示例时,脚本会在写入前报告冲突。先核对差异, +保留需要的定制。相同版本的未修改文件可重复运行脚本。 + +从旧版迁移时,先把已有的 SDK 源码和许可证合并到 `src/sdk/`。按文件所在位置,将业务代码及 +先前复制的组件和示例中的旧 SDK 导入改为指向公开源码的相对路径。核对代码已使用新路径后, +可清理前版的 `#kit-sdk/` 映射或旧的 `@openagentpack/kit-sdk` 本地包依赖。 + +接入完成后,在应用中运行类型检查和构建。需要真实对话时,另外验证应用自己的后端和网络配置。 + +## 接入三栏会话页 + +使用 `use-kit-chat` Skill 时,用下面的命令复制完整三栏示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" --example experience.tsx +``` + +从 `src/kit-examples/use-kit-chat/experience.tsx` 导入 `Experience`。该命令还会复制同目录的 +资源面板和审批列表,以及它们所用的组件。为页面提供稳定的 Client、Provider 和应用回调,并导入本地主题。 diff --git a/assets/skills/use-kit-chat/references/examples.md b/assets/skills/use-kit-chat/references/examples.md index 5cbce5f..8f96dd2 100644 --- a/assets/skills/use-kit-chat/references/examples.md +++ b/assets/skills/use-kit-chat/references/examples.md @@ -1,6 +1,6 @@ # 可编译示例 -本页由随附的示例源文件生成。请按应用需求调整回调和运行时配置。 +本页展示仓库中的示例源文件。按[复制组件和 Kit SDK](copy-in.md)用 `--example` 接入应用,脚本会生成相对导入路径。 ## agent-resources-panel.tsx diff --git a/assets/skills/use-kit-chat/scripts/copy-in.mjs b/assets/skills/use-kit-chat/scripts/copy-in.mjs new file mode 100644 index 0000000..beab29b --- /dev/null +++ b/assets/skills/use-kit-chat/scripts/copy-in.mjs @@ -0,0 +1,37 @@ +import { cpSync, mkdirSync, readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; + +export const sdkTarget = "src/sdk"; +export const componentTarget = "src/components/kit"; +export const exampleTarget = (skill) => `src/kit-examples/${skill}`; + +export function readRegistry(elementsRoot) { + return JSON.parse(readFileSync(join(elementsRoot, "registry.json"), "utf8")); +} + +/** 解析组件及其传递依赖的闭包;未知组件返回 null。 */ +export function resolveComponentClosure(registry, name) { + const wanted = [name]; + const seen = new Set(); + while (wanted.length) { + const current = wanted.pop(); + if (seen.has(current)) continue; + seen.add(current); + const entry = registry.components[current]; + if (!entry) return null; + wanted.push(...entry.deps); + } + return seen; +} + +/** 落点保留 src/components/ 下的子目录层级:组件间的相对导入依赖它。 */ +export function componentDestPath(entryFile) { + return entryFile.replace(/^src\/components\//, ""); +} + +export function copyComponentSource(elementsRoot, entryFile, targetDir) { + const to = join(targetDir, componentDestPath(entryFile)); + mkdirSync(dirname(to), { recursive: true }); + cpSync(join(elementsRoot, entryFile), to); + return to; +} diff --git a/assets/skills/use-kit-chat/scripts/install.mjs b/assets/skills/use-kit-chat/scripts/install.mjs new file mode 100644 index 0000000..19f6640 --- /dev/null +++ b/assets/skills/use-kit-chat/scripts/install.mjs @@ -0,0 +1,186 @@ +import { + lstatSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + realpathSync, + renameSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { dirname, join, relative, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; +import { parseArgs } from "node:util"; +import { + componentDestPath, + componentTarget, + exampleTarget, + readRegistry, + resolveComponentClosure, + sdkTarget, +} from "./copy-in.mjs"; + +const sdkName = "@openagentpack/kit-sdk"; +const assetRoot = fileURLToPath(new URL("../assets/kit/", import.meta.url)); +const usage = "用法:node /scripts/install.mjs --dir <项目目录> [--example <文件> ...] [组件名 ...]"; + +function addTree(plan, source, target) { + for (const entry of readdirSync(source, { withFileTypes: true })) { + const input = join(source, entry.name); + const output = join(target, entry.name); + if (entry.isDirectory()) addTree(plan, input, output); + else if (entry.isFile()) plan.set(output, readFileSync(input)); + else throw new Error(`无效的 Skill 资产:${entry.name}`); + } +} + +function planExamples(plan, selected, project) { + if (!selected.length) return { components: [] }; + const source = join(assetRoot, "examples"); + const { skill, examples } = JSON.parse(readFileSync(join(source, "copy-in.json"), "utf8")); + const directory = exampleTarget(skill); + const pending = [...selected]; + const visited = new Set(); + const components = new Set(); + while (pending.length) { + const file = pending.pop(); + if (visited.has(file)) continue; + visited.add(file); + if (!Object.hasOwn(examples, file)) throw new Error(`未知示例 ${file},可选:${Object.keys(examples).join("、")}`); + const example = examples[file]; + plan.set(join(project, directory, file), readFileSync(join(source, file))); + pending.push(...example.companions); + for (const component of example.components) components.add(component); + } + return { components: [...components], directory }; +} + +function planComponents(plan, selected, project) { + if (!selected.length) return {}; + const source = join(assetRoot, "chat-ui"); + const registry = readRegistry(source); + const versions = JSON.parse(readFileSync(join(source, "dependencies.json"), "utf8")); + const components = new Set(); + for (const name of selected) { + const closure = Object.hasOwn(registry.components, name) && resolveComponentClosure(registry, name); + if (!closure) throw new Error(`未知组件 ${name},可选:${Object.keys(registry.components).join("、")}`); + for (const component of closure) components.add(component); + } + const target = join(project, componentTarget); + const entries = [...components].map((component) => registry.components[component]); + for (const { file } of entries) plan.set(join(target, componentDestPath(file)), readFileSync(join(source, file))); + const dependencies = {}; + for (const name of new Set(entries.flatMap((entry) => entry.npmDependencies ?? []))) { + if (name === sdkName) continue; + if (!versions[name]) throw new Error(`组件清单缺少依赖 ${name} 的版本。`); + dependencies[name] = versions[name]; + } + plan.set(join(target, "theme.css"), readFileSync(join(source, registry.theme))); + plan.set(join(target, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + return dependencies; +} + +function mergeDependencies(manifest, dependencies) { + const groups = [ + manifest.dependencies, + manifest.devDependencies, + manifest.optionalDependencies, + manifest.peerDependencies, + ]; + if (groups.some((group) => group && Object.hasOwn(group, sdkName))) { + throw new Error(`项目已声明 ${sdkName} 包依赖。切换源码接入时,请按 Skill 指引迁移导入并移除此依赖。`); + } + const additions = Object.fromEntries( + Object.entries(dependencies).filter(([name]) => !groups.some((group) => group && Object.hasOwn(group, name))), + ); + return { ...manifest, dependencies: { ...manifest.dependencies, ...additions } }; +} + +function checkDestinations(project, plan) { + const pending = new Map(); + const conflicts = []; + for (const [file, content] of plan) { + const path = relative(project, file); + const segments = path.split(sep); + if (segments[0] === "..") throw new Error(`目标文件越出项目目录:${path}`); + let parent = project; + for (const segment of segments.slice(0, -1)) { + parent = join(parent, segment); + const stat = lstatSync(parent, { throwIfNoEntry: false }); + if (stat && !stat.isDirectory()) throw new Error(`目标目录不可用:${relative(project, parent)}`); + } + const stat = lstatSync(file, { throwIfNoEntry: false }); + if (!stat) pending.set(file, content); + else if (!stat.isFile() || !readFileSync(file).equals(content)) conflicts.push(path); + } + if (conflicts.length) + throw new Error(`以下文件与 Skill 资产有差异,请先合并或保留现有版本:\n${conflicts.join("\n")}`); + return pending; +} + +function updateManifest(file, previous, manifest) { + if (JSON.stringify(JSON.parse(previous)) === JSON.stringify(manifest)) return; + const indent = previous.match(/^([\t ]+)"/m)?.[1] ?? " "; + const lineEnding = previous.includes("\r\n") ? "\r\n" : "\n"; + const next = `${JSON.stringify(manifest, null, indent)}\n`.replaceAll("\n", lineEnding); + const directory = mkdtempSync(join(dirname(file), ".kit-copy-in-")); + try { + const staging = join(directory, "package.json"); + writeFileSync(staging, next, { mode: lstatSync(file).mode }); + if (readFileSync(file, "utf8") !== previous) throw new Error("并行修改了 package.json,请检查后重试。"); + renameSync(staging, file); + } finally { + rmSync(directory, { recursive: true, force: true }); + } +} + +function install(directory, components, examples) { + const project = realpathSync(resolve(directory)); + const packagePath = join(project, "package.json"); + if (!lstatSync(packagePath, { throwIfNoEntry: false })?.isFile()) { + throw new Error("--dir 必须指向包含 package.json 的应用目录。"); + } + const previous = readFileSync(packagePath, "utf8"); + const manifest = JSON.parse(previous); + const sdk = join(assetRoot, "sdk"); + const sdkMetadata = join(sdk, "copy-in.json"); + if (!lstatSync(sdkMetadata, { throwIfNoEntry: false })?.isFile()) { + throw new Error("缺少 Kit SDK 资产。请解压完整的 Skill 离线包并使用其中的目录。"); + } + const { dependencies } = JSON.parse(readFileSync(sdkMetadata, "utf8")); + const plan = new Map(); + addTree(plan, join(sdk, "src"), join(project, sdkTarget)); + plan.set(join(project, sdkTarget, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + const examplePlan = planExamples(plan, examples, project); + const selected = [...components, ...examplePlan.components]; + const nextManifest = mergeDependencies(manifest, { + ...dependencies, + ...planComponents(plan, selected, project), + }); + const pending = checkDestinations(project, plan); + for (const [file, content] of pending) { + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, content, { flag: "wx" }); + } + updateManifest(packagePath, previous, nextManifest); + process.stdout.write(`已就绪:${sdkTarget}。\n`); + if (selected.length) process.stdout.write(`已就绪:${componentTarget},包括组件依赖和 theme.css。\n`); + if (examplePlan.directory) process.stdout.write(`已就绪:${examplePlan.directory},包括示例依赖。\n`); + process.stdout.write("请使用目标项目的包管理器安装依赖并更新锁文件。\n"); +} + +try { + const { values, positionals } = parseArgs({ + options: { dir: { type: "string" }, example: { type: "string", multiple: true }, help: { type: "boolean" } }, + allowPositionals: true, + }); + if (values.help) process.stdout.write(`${usage}\n`); + else { + if (!values.dir) throw new Error(usage); + install(values.dir, positionals, values.example ?? []); + } +} catch (error) { + process.stderr.write(`${error.message}\n`); + process.exitCode = 1; +} diff --git a/docs/adr/0027-skills-source-and-generated-output.md b/docs/adr/0027-skills-source-and-generated-output.md index f626f8b..b9f2889 100644 --- a/docs/adr/0027-skills-source-and-generated-output.md +++ b/docs/adr/0027-skills-source-and-generated-output.md @@ -7,6 +7,13 @@ 生成链路校验入口正文、元数据文案、catalog 说明和手写 Markdown 参考是否包含中文, 并校验链接、API 覆盖、示例和漂移。打包测试验证中文内容原样分发。 +完整离线包为每个 Skill 附上 copy-in 脚本与当前版本的组件、示例和 Kit SDK 源码。 +脚本复用 UI registry 选择组件,复制选中的示例和它们的依赖。生成的组件和示例使用相对路径 +导入 `src/sdk/` 下的公开源码入口,由目标应用统一构建。 +Copy-in 资产从各自的拥有包和示例源生成,仅附于压缩包和文档站下载目录。 +被跟踪的 Skill 目录用于浏览和校验说明、示例、脚本,完整独立接入使用离线包。 +此状态更新不改变 Skill 的非运行时形态,也不增加 workspace 包或发布 CLI。 + ## 背景 `packages/skills` 同时承担两种职责:保存英文 Skill 内容,以及提供生成、校验和打包工具。 diff --git a/docs/repository-layout.md b/docs/repository-layout.md index 8e69af3..5bd5f62 100644 --- a/docs/repository-layout.md +++ b/docs/repository-layout.md @@ -236,8 +236,11 @@ assets/skills/ 三者共用现有公开类型,不复制协议实现、不引入第二套事件模型。 - Skill 正文、参考、元数据、示例注释与示例界面文案使用中文;Skill ID、文件名、API 标识符和协议值沿用公开合同。 -- `pnpm gen:skills` 从 `scripts/skills/src/` 生成 `assets/skills/`、API 参考与 MDX 示例; - `pnpm check:skills` 只检查,`pnpm pack:skills` 生成离线包。生成区不手改。 +- `pnpm gen:skills` 从 `scripts/skills/src/` 及共享 copy-in 脚本和说明生成 `assets/skills/`、 + API 参考与 MDX 示例;`pnpm check:skills` 只检查。生成区不手改。 +- `pnpm pack:skills` 给每个离线包附上 UI registry、组件源码、主题、SDK 源码和可复制的示例。 + 脚本按需复制组件及示例,生成指向 `src/sdk/` 公开入口的相对路径,交给目标应用构建。 + 源码资产只进入离线包和文档站下载目录,在各自的包内维护。 - `pnpm typecheck:skills` 编译示例,`pnpm test:skills` 检查生成漂移、链接、 独立离线包和浏览器依赖边界。语义说明与 API 结构分别维护并共同校验。 - 文档站入口为 `apps/storybook/content/docs/skill/index.mdx`,保留 `/docs/skill/` URL。 diff --git a/docs/validation.md b/docs/validation.md index 26fa14a..7e58113 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -15,7 +15,7 @@ | Console | `pnpm --filter console test` | 管理客户端、导航、草稿所有权、资源表单与恢复 | | Web | `pnpm --filter web test` | 配置、身份隔离、宿主适配及页面纯逻辑 | | 文档站 | `pnpm --filter storybook test` | 接口文档与 Skill 链接;页面内容/预览另由静态构建及浏览器验证 | -| 开发 Skill | `pnpm check:skills` / `pnpm typecheck:skills` / `pnpm test:skills` | 公开 API、生成漂移、示例编译、离线包及浏览器边界 | +| 开发 Skill | `pnpm check:skills` / `pnpm typecheck:skills` / `pnpm test:skills` | 公开 API、生成漂移、示例编译、离线包、项目 copy-in 及浏览器边界 | | web / console E2E | `pnpm e2e` | 对话、重连、归档/删除、附件、管理端 plan → 确认 → 执行 | > Provider HTTP/SSE 合同由 gateway 层 fixture 保护;上层 hooks 测试不重复断言同一份映射。 diff --git a/packages/chat-ui/registry.json b/packages/chat-ui/registry.json index 8898322..321c775 100644 --- a/packages/chat-ui/registry.json +++ b/packages/chat-ui/registry.json @@ -21,11 +21,11 @@ "tool-call-card": { "file": "src/components/process/tool-call-card/index.tsx", "deps": ["process-step", "tool-summary", "markdown", "code-highlighter"] }, "reasoning-block": { "file": "src/components/process/reasoning-block/index.tsx", "deps": ["process-step"] }, "tool-summary": { "file": "src/components/process/tool-summary/index.ts", "deps": [] }, - "markdown": { "file": "src/components/markdown/index.tsx", "deps": ["code-highlighter", "mermaid"] }, + "markdown": { "file": "src/components/markdown/index.tsx", "deps": ["code-highlighter", "mermaid"], "npmDependencies": ["react-markdown", "rehype-sanitize", "remark-gfm"] }, "actions": { "file": "src/components/actions/index.tsx", "deps": [] }, "file-card": { "file": "src/components/file-card/index.tsx", "deps": [] }, - "code-highlighter": { "file": "src/components/code-highlighter/index.tsx", "deps": ["actions"] }, - "mermaid": { "file": "src/components/mermaid/index.tsx", "deps": ["actions", "code-highlighter"] }, + "code-highlighter": { "file": "src/components/code-highlighter/index.tsx", "deps": ["actions"], "npmDependencies": ["lowlight"] }, + "mermaid": { "file": "src/components/mermaid/index.tsx", "deps": ["actions", "code-highlighter"], "npmDependencies": ["mermaid"] }, "agent-header": { "file": "src/components/agent-header/index.tsx", "deps": [] }, "session-list": { "file": "src/components/session-list/index.tsx", "deps": ["tooltip", "process-step"] }, "session-sidebar": { "file": "src/components/session-sidebar/index.tsx", "deps": ["session-list", "states"] }, diff --git a/scripts/kit/copy-in.mjs b/scripts/kit/copy-in.mjs index 7dedf6f..beab29b 100644 --- a/scripts/kit/copy-in.mjs +++ b/scripts/kit/copy-in.mjs @@ -1,6 +1,10 @@ import { cpSync, mkdirSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; +export const sdkTarget = "src/sdk"; +export const componentTarget = "src/components/kit"; +export const exampleTarget = (skill) => `src/kit-examples/${skill}`; + export function readRegistry(elementsRoot) { return JSON.parse(readFileSync(join(elementsRoot, "registry.json"), "utf8")); } diff --git a/scripts/kit/skill-install.mjs b/scripts/kit/skill-install.mjs new file mode 100644 index 0000000..19f6640 --- /dev/null +++ b/scripts/kit/skill-install.mjs @@ -0,0 +1,186 @@ +import { + lstatSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + realpathSync, + renameSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { dirname, join, relative, resolve, sep } from "node:path"; +import { fileURLToPath } from "node:url"; +import { parseArgs } from "node:util"; +import { + componentDestPath, + componentTarget, + exampleTarget, + readRegistry, + resolveComponentClosure, + sdkTarget, +} from "./copy-in.mjs"; + +const sdkName = "@openagentpack/kit-sdk"; +const assetRoot = fileURLToPath(new URL("../assets/kit/", import.meta.url)); +const usage = "用法:node /scripts/install.mjs --dir <项目目录> [--example <文件> ...] [组件名 ...]"; + +function addTree(plan, source, target) { + for (const entry of readdirSync(source, { withFileTypes: true })) { + const input = join(source, entry.name); + const output = join(target, entry.name); + if (entry.isDirectory()) addTree(plan, input, output); + else if (entry.isFile()) plan.set(output, readFileSync(input)); + else throw new Error(`无效的 Skill 资产:${entry.name}`); + } +} + +function planExamples(plan, selected, project) { + if (!selected.length) return { components: [] }; + const source = join(assetRoot, "examples"); + const { skill, examples } = JSON.parse(readFileSync(join(source, "copy-in.json"), "utf8")); + const directory = exampleTarget(skill); + const pending = [...selected]; + const visited = new Set(); + const components = new Set(); + while (pending.length) { + const file = pending.pop(); + if (visited.has(file)) continue; + visited.add(file); + if (!Object.hasOwn(examples, file)) throw new Error(`未知示例 ${file},可选:${Object.keys(examples).join("、")}`); + const example = examples[file]; + plan.set(join(project, directory, file), readFileSync(join(source, file))); + pending.push(...example.companions); + for (const component of example.components) components.add(component); + } + return { components: [...components], directory }; +} + +function planComponents(plan, selected, project) { + if (!selected.length) return {}; + const source = join(assetRoot, "chat-ui"); + const registry = readRegistry(source); + const versions = JSON.parse(readFileSync(join(source, "dependencies.json"), "utf8")); + const components = new Set(); + for (const name of selected) { + const closure = Object.hasOwn(registry.components, name) && resolveComponentClosure(registry, name); + if (!closure) throw new Error(`未知组件 ${name},可选:${Object.keys(registry.components).join("、")}`); + for (const component of closure) components.add(component); + } + const target = join(project, componentTarget); + const entries = [...components].map((component) => registry.components[component]); + for (const { file } of entries) plan.set(join(target, componentDestPath(file)), readFileSync(join(source, file))); + const dependencies = {}; + for (const name of new Set(entries.flatMap((entry) => entry.npmDependencies ?? []))) { + if (name === sdkName) continue; + if (!versions[name]) throw new Error(`组件清单缺少依赖 ${name} 的版本。`); + dependencies[name] = versions[name]; + } + plan.set(join(target, "theme.css"), readFileSync(join(source, registry.theme))); + plan.set(join(target, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + return dependencies; +} + +function mergeDependencies(manifest, dependencies) { + const groups = [ + manifest.dependencies, + manifest.devDependencies, + manifest.optionalDependencies, + manifest.peerDependencies, + ]; + if (groups.some((group) => group && Object.hasOwn(group, sdkName))) { + throw new Error(`项目已声明 ${sdkName} 包依赖。切换源码接入时,请按 Skill 指引迁移导入并移除此依赖。`); + } + const additions = Object.fromEntries( + Object.entries(dependencies).filter(([name]) => !groups.some((group) => group && Object.hasOwn(group, name))), + ); + return { ...manifest, dependencies: { ...manifest.dependencies, ...additions } }; +} + +function checkDestinations(project, plan) { + const pending = new Map(); + const conflicts = []; + for (const [file, content] of plan) { + const path = relative(project, file); + const segments = path.split(sep); + if (segments[0] === "..") throw new Error(`目标文件越出项目目录:${path}`); + let parent = project; + for (const segment of segments.slice(0, -1)) { + parent = join(parent, segment); + const stat = lstatSync(parent, { throwIfNoEntry: false }); + if (stat && !stat.isDirectory()) throw new Error(`目标目录不可用:${relative(project, parent)}`); + } + const stat = lstatSync(file, { throwIfNoEntry: false }); + if (!stat) pending.set(file, content); + else if (!stat.isFile() || !readFileSync(file).equals(content)) conflicts.push(path); + } + if (conflicts.length) + throw new Error(`以下文件与 Skill 资产有差异,请先合并或保留现有版本:\n${conflicts.join("\n")}`); + return pending; +} + +function updateManifest(file, previous, manifest) { + if (JSON.stringify(JSON.parse(previous)) === JSON.stringify(manifest)) return; + const indent = previous.match(/^([\t ]+)"/m)?.[1] ?? " "; + const lineEnding = previous.includes("\r\n") ? "\r\n" : "\n"; + const next = `${JSON.stringify(manifest, null, indent)}\n`.replaceAll("\n", lineEnding); + const directory = mkdtempSync(join(dirname(file), ".kit-copy-in-")); + try { + const staging = join(directory, "package.json"); + writeFileSync(staging, next, { mode: lstatSync(file).mode }); + if (readFileSync(file, "utf8") !== previous) throw new Error("并行修改了 package.json,请检查后重试。"); + renameSync(staging, file); + } finally { + rmSync(directory, { recursive: true, force: true }); + } +} + +function install(directory, components, examples) { + const project = realpathSync(resolve(directory)); + const packagePath = join(project, "package.json"); + if (!lstatSync(packagePath, { throwIfNoEntry: false })?.isFile()) { + throw new Error("--dir 必须指向包含 package.json 的应用目录。"); + } + const previous = readFileSync(packagePath, "utf8"); + const manifest = JSON.parse(previous); + const sdk = join(assetRoot, "sdk"); + const sdkMetadata = join(sdk, "copy-in.json"); + if (!lstatSync(sdkMetadata, { throwIfNoEntry: false })?.isFile()) { + throw new Error("缺少 Kit SDK 资产。请解压完整的 Skill 离线包并使用其中的目录。"); + } + const { dependencies } = JSON.parse(readFileSync(sdkMetadata, "utf8")); + const plan = new Map(); + addTree(plan, join(sdk, "src"), join(project, sdkTarget)); + plan.set(join(project, sdkTarget, "LICENSE"), readFileSync(join(assetRoot, "LICENSE"))); + const examplePlan = planExamples(plan, examples, project); + const selected = [...components, ...examplePlan.components]; + const nextManifest = mergeDependencies(manifest, { + ...dependencies, + ...planComponents(plan, selected, project), + }); + const pending = checkDestinations(project, plan); + for (const [file, content] of pending) { + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, content, { flag: "wx" }); + } + updateManifest(packagePath, previous, nextManifest); + process.stdout.write(`已就绪:${sdkTarget}。\n`); + if (selected.length) process.stdout.write(`已就绪:${componentTarget},包括组件依赖和 theme.css。\n`); + if (examplePlan.directory) process.stdout.write(`已就绪:${examplePlan.directory},包括示例依赖。\n`); + process.stdout.write("请使用目标项目的包管理器安装依赖并更新锁文件。\n"); +} + +try { + const { values, positionals } = parseArgs({ + options: { dir: { type: "string" }, example: { type: "string", multiple: true }, help: { type: "boolean" } }, + allowPositionals: true, + }); + if (values.help) process.stdout.write(`${usage}\n`); + else { + if (!values.dir) throw new Error(usage); + install(values.dir, positionals, values.example ?? []); + } +} catch (error) { + process.stderr.write(`${error.message}\n`); + process.exitCode = 1; +} diff --git a/scripts/skills/AGENTS.md b/scripts/skills/AGENTS.md index 73b21e1..1ed2100 100644 --- a/scripts/skills/AGENTS.md +++ b/scripts/skills/AGENTS.md @@ -9,7 +9,8 @@ - `src//metadata.json`、`skill.md`、`catalog.json`、 `references/`、`examples/`:唯一人工编辑源。 - `generate.mjs`、`api-model.mjs`、`validate.mjs`:抽取公开 API、生成与漂移/内容校验。 -- `pack.mjs`、`archive.mjs`:离线包与文档站下载准备;`tests/`:生成链路合同。 +- `pack.mjs`、`archive.mjs` 和 `copy-in-assets.mjs`:离线包与文档站下载准备; + `copy-in.md` 与 `../kit/skill-install.mjs` 是各 Skill 共用的复制说明与脚本。 - `assets/skills//`:被跟踪的最终生成目录;`assets/skills/dist/` 为忽略的离线包。 `apps/storybook/public/skills/` 是构建下载资产,不是第二份人工源。 @@ -18,7 +19,8 @@ 1. Skill 的入口、参考、元数据、示例注释与界面文案使用中文,保留 Skill ID、文件名、API 标识符和协议值。 2. 最终目录由根命令生成,不手改 `SKILL.md`、OpenAI metadata、API/示例参考、 示例副本或 MDX 的 `skill-example` 标记区。 -3. 每个 Skill 可独立复制;内部相对链接不能越出目录,文件键使用可移植的 `/`。 +3. 每个离线 Skill 可独立复制到目标环境;内部相对链接不能越出目录,文件键使用可移植的 `/`。 + Copy-in 资产来自组件 registry 及 SDK 公开包,随离线包和文档站下载分发。 离线包保持确定性,构建不修补被跟踪的源文件。 4. `kit-components` 覆盖公开组件、静态子组件和 helper,不以 registry 分组代替 API。 示例必须实际调用对应组件或函数,类型和必填项来自公开声明。 @@ -26,7 +28,9 @@ `use-kit-chat` 负责 Controller 与功能 hooks。模块表、catalog 和实际公开入口同步, 同一类型经多入口导出时去重,不暴露私有工具。 6. 示例遵循 SDK / UI 边界,不导入上游 SDK 主入口运行时或 internal,不复制状态机或转换器; - 未发布依赖必须明确前提,不能把离线示例描述为真实 Cloud 验证。 + 组件和示例通过相对路径使用 `src/sdk/` 的公开源码入口,由应用工具链编译。 + 复制脚本保留目标项目的 `package.json#imports` 设置。 + 不能把离线示例描述为真实 Cloud 验证。 ## 修改步骤 diff --git a/scripts/skills/README.md b/scripts/skills/README.md index 2503d4d..582770a 100644 --- a/scripts/skills/README.md +++ b/scripts/skills/README.md @@ -7,7 +7,7 @@ ## 源与生成物 -只编辑 `src/`: +编辑各 Skill 的 `src/`,共用的复制说明在 `copy-in.md`,脚本来自 `../kit/`: ```text scripts/skills/src// @@ -28,9 +28,12 @@ assets/skills// references/examples.md references/... 从 src 复制 examples/ 从 src 复制 + scripts/ 共享的 copy-in 脚本 ``` -`assets/skills/dist/` 是离线包产物,已 gitignore。 +`assets/skills/dist/` 是离线包产物,已 gitignore。打包时在各离线包中加入 +`assets/kit/`,包含组件 registry、组件源码、主题、本地 Kit SDK 以及用相对路径导入的示例。 +安装脚本的 `--example` 参数会复制示例及其随附文件和组件。 ## 常用命令 @@ -39,11 +42,12 @@ pnpm gen:skills # 生成 assets/skills、API 参考和文档示例 pnpm check:skills # 检查中文说明和产物漂移,不写文件 pnpm typecheck:skills # 编译示例与公开 API fixture pnpm test:skills # 生成、链接、打包和浏览器依赖边界 -pnpm pack:skills # 生成 assets/skills/dist/*.tgz +pnpm pack:skills # 生成带组件和 SDK 源码的离线包 ``` 文档站的 `skill-example` 代码块与 Skill 示例来自同一份源文件;改示例后必须重新生成。 -发布或复制 Skill 时,使用 `assets/skills//` 或 `assets/skills/dist/.tgz`。 +从仓库浏览 Skill 时使用 `assets/skills//`;分发给目标项目时使用 +`assets/skills/dist/.tgz` 的完整目录。 ## 新增或修改内容 diff --git a/scripts/skills/copy-in-assets.mjs b/scripts/skills/copy-in-assets.mjs new file mode 100644 index 0000000..a434597 --- /dev/null +++ b/scripts/skills/copy-in-assets.mjs @@ -0,0 +1,167 @@ +import { readFileSync, statSync } from "node:fs"; +import { dirname, posix, relative, resolve } from "node:path"; +import ts from "typescript"; +import { componentDestPath, componentTarget, exampleTarget, readRegistry, sdkTarget } from "../kit/copy-in.mjs"; +import { modules } from "./api-model.mjs"; +import { filesUnder, portablePath } from "./validate.mjs"; + +const sdkName = "@openagentpack/kit-sdk"; +const uiName = modules["chat-ui"].name; + +function sourceFile(file, path) { + return { path: `assets/kit/${path}`, content: readFileSync(file), mtimeMs: statSync(file).mtimeMs }; +} + +function jsonFile(path, value, mtimeMs) { + return { path: `assets/kit/${path}`, content: `${JSON.stringify(value, null, 2)}\n`, mtimeMs }; +} + +function sdkSourceAssets(root) { + const directory = resolve(root, "packages/sdk"); + const sourceDirectory = resolve(directory, "src"); + const manifestPath = resolve(directory, "package.json"); + const sdk = JSON.parse(readFileSync(manifestPath, "utf8")); + const source = filesUnder(sourceDirectory).filter( + (file) => /\.tsx?$/.test(file) && !/\.(?:test|spec)\.tsx?$/.test(file), + ); + const paths = new Set(source); + const modulePaths = new Map(Object.values(modules).map(({ name, path }) => [name, resolve(root, path)])); + const publicEntries = new Map( + Object.keys(sdk.exports).map((key) => { + const specifier = `${sdkName}${key.slice(1)}`; + const file = modulePaths.get(specifier); + if (!file || !paths.has(file)) throw new Error(`SDK 公开入口 ${key} 缺少可复制的源码。`); + return [specifier, `${sdkTarget}/${portablePath(relative(sourceDirectory, file))}`]; + }), + ); + return { + publicEntries, + files: [ + jsonFile("sdk/copy-in.json", { dependencies: sdk.dependencies }, statSync(manifestPath).mtimeMs), + ...source.map((file) => sourceFile(file, `sdk/src/${portablePath(relative(sourceDirectory, file))}`)), + ], + }; +} + +function relativeImport(from, to) { + const path = posix.relative(posix.dirname(from), to); + return path.startsWith("../") ? path : `./${path}`; +} + +function rewriteSdkImports(content, target, publicEntries) { + const references = ts.preProcessFile(content, true, true).importedFiles; + for (const { fileName, pos, end } of references.reverse()) { + if (fileName !== sdkName && !fileName.startsWith(`${sdkName}/`)) continue; + const entry = publicEntries.get(fileName); + if (!entry) throw new Error(`${target} 导入了未公开的 Kit SDK 入口 ${fileName}。`); + if (content.slice(pos + 1, end + 1) !== fileName) throw new Error(`无法转换 ${target} 的 SDK 导入 ${fileName}。`); + content = `${content.slice(0, pos + 1)}${relativeImport(target, entry)}${content.slice(end + 1)}`; + } + return content; +} + +function uiExports(root, directory, registry) { + const barrel = resolve(root, modules["chat-ui"].path); + const source = ts.createSourceFile(barrel, readFileSync(barrel, "utf8"), ts.ScriptTarget.Latest, true); + const components = new Map( + Object.entries(registry.components).map(([name, { file }]) => [ + resolve(directory, file), + { name, target: `${componentTarget}/${componentDestPath(file)}` }, + ]), + ); + const exports = new Map(); + for (const statement of source.statements) { + if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier) continue; + const component = components.get(resolve(dirname(barrel), statement.moduleSpecifier.text)); + const { exportClause } = statement; + if (!component || !exportClause || !ts.isNamedExports(exportClause)) { + throw new Error(`组件公开入口缺少对应的 registry 条目:${statement.getText(source)}`); + } + for (const { name, propertyName } of exportClause.elements) { + exports.set(name.text, { ...component, exportName: (propertyName ?? name).text }); + } + } + return exports; +} + +function formatUiImports(clause, target, publicUi, components) { + if (clause?.name || !clause?.namedBindings || !ts.isNamedImports(clause.namedBindings)) { + throw new Error(`${target} 必须以具名方式导入 Kit 组件。`); + } + const imports = new Map(); + for (const binding of clause.namedBindings.elements) { + const name = (binding.propertyName ?? binding.name).text; + const entry = publicUi.get(name); + if (!entry) throw new Error(`${target} 导入的组件 ${name} 缺少可复制的公开入口。`); + components.add(entry.name); + const local = binding.name.text; + const specifier = entry.exportName === local ? local : `${entry.exportName} as ${local}`; + const specifiers = imports.get(entry.target) ?? []; + specifiers.push(clause.isTypeOnly || binding.isTypeOnly ? `type ${specifier}` : specifier); + imports.set(entry.target, specifiers); + } + return [...imports] + .map(([file, names]) => `import { ${names.join(", ")} } from ${JSON.stringify(relativeImport(target, file))};`) + .join("\n"); +} + +function rewriteExampleUiImports(content, target, publicUi) { + const source = ts.createSourceFile(target, content, ts.ScriptTarget.Latest, true); + const components = new Set(); + for (const statement of [...source.statements].reverse()) { + if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== uiName) continue; + const imports = formatUiImports(statement.importClause, target, publicUi, components); + content = `${content.slice(0, statement.getStart(source))}${imports}${content.slice(statement.end)}`; + } + return { content, components: [...components] }; +} + +function buildExampleAssets(skill, source, sdkEntries, publicUi) { + const sources = filesUnder(source).filter((file) => /\.tsx?$/.test(file)); + const paths = new Set(sources); + const options = { module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler }; + const examples = {}; + const assets = sources.map((file) => { + const name = portablePath(relative(source, file)); + const asset = sourceFile(file, `examples/${name}`); + const target = `${exampleTarget(skill)}/${name}`; + const withSdk = rewriteSdkImports(asset.content.toString("utf8"), target, sdkEntries); + const { content, components } = rewriteExampleUiImports(withSdk, target, publicUi); + const companions = new Set(); + for (const { fileName } of ts.preProcessFile(asset.content.toString("utf8"), true, true).importedFiles) { + if (!fileName.startsWith("./") && !fileName.startsWith("../")) continue; + const resolved = ts.resolveModuleName(fileName, file, options, ts.sys).resolvedModule?.resolvedFileName; + if (!paths.has(resolved)) throw new Error(`示例 ${name} 缺少随附文件 ${fileName}。`); + companions.add(portablePath(relative(source, resolved))); + } + examples[name] = { companions: [...companions], components }; + return { ...asset, content }; + }); + const modificationTime = Math.max(...assets.map(({ mtimeMs }) => mtimeMs), 0); + return [jsonFile("examples/copy-in.json", { skill, examples }, modificationTime), ...assets]; +} + +export function buildCopyInAssets(root) { + const directory = resolve(root, "packages/chat-ui"); + const registry = readRegistry(directory); + const manifestPath = resolve(directory, "package.json"); + const { dependencies } = JSON.parse(readFileSync(manifestPath, "utf8")); + const sdk = sdkSourceAssets(root); + const components = new Set(Object.values(registry.components).map(({ file }) => file)); + const publicUi = uiExports(root, directory, registry); + return { + shared: [ + ...sdk.files, + sourceFile(resolve(root, "LICENSE"), "LICENSE"), + jsonFile("chat-ui/dependencies.json", dependencies, statSync(manifestPath).mtimeMs), + ...["registry.json", registry.theme].map((path) => sourceFile(resolve(directory, path), `chat-ui/${path}`)), + ...[...components].map((path) => { + const asset = sourceFile(resolve(directory, path), `chat-ui/${path}`); + const target = `${componentTarget}/${componentDestPath(path)}`; + const content = rewriteSdkImports(asset.content.toString("utf8"), target, sdk.publicEntries); + return { ...asset, content }; + }), + ], + examples: (skill, directory) => buildExampleAssets(skill, directory, sdk.publicEntries, publicUi), + }; +} diff --git a/scripts/skills/copy-in.md b/scripts/skills/copy-in.md new file mode 100644 index 0000000..dbbc585 --- /dev/null +++ b/scripts/skills/copy-in.md @@ -0,0 +1,87 @@ +# 将组件和 Kit SDK 复制进项目 + +使用完整的 Skill 离线包。其 `assets/kit/` 带有匹配示例版本的组件源码、registry 和 Kit SDK。 +也可以在 Kit 仓库运行 `pnpm pack:skills`,从 `assets/skills/dist/` 解压对应的离线包。 +Copy-in 脚本可以用 Node.js 直接运行。 + +## 复制到应用 + +1. 找到待接入应用的 `package.json`。在 monorepo 中选择实际消费 Kit 的成员包。 +2. 用 `--example` 选择当前 Skill 的示例文件,或传入页面需要的组件条目名。组件清单位于 + `assets/kit/chat-ui/registry.json`。脚本会复制选中示例的随附文件、组件及其传递依赖和主题。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" chat +``` + +只使用 SDK 数据入口、hooks 或后端适配时,可以省略组件名和示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" +``` + +SDK 源码位于应用的 `src/sdk/`。组件复制到 `src/components/kit/`, +通过 `--example` 复制的示例位于 `src/kit-examples//`。脚本已为这些文件生成 +相对导入路径。参考中的原始示例保留仓库的包导入,接入应用时先使用脚本生成可直接引用的源码。 + +业务代码也可按文件位置导入 SDK 的公开源码入口。例如在 `src/App.tsx` 中导入 `useChat`。 + +```tsx +import { useChat } from "./sdk/chat/hooks/index.ts"; +``` + +按功能入口导入 SDK,例如消息类型位于 `src/sdk/messages/index.ts`。由宿主应用的工具链统一编译这些源码。 + +脚本会在应用的 `package.json` 中补上缺少的 SDK 和组件依赖,例如上游 `@openagentpack/sdk` +和 `zod`。用应用现有的包管理器执行安装并更新锁文件。应用已有同名依赖时,核对实际解析版本是否与 +Skill 的 `assets/kit/sdk/copy-in.json` 兼容。React 页面使用宿主的 React 和同主版本的 React DOM。 + +将 `src/sdk/` 随应用提交。SDK 使用 `findLast` 和 `toReversed` 等 +ES2023 API,应用的 TypeScript `lib` 应包含 `ES2023` 或更新版本,Web 项目继续保留 DOM 类型。 +Node.js 宿主可以用已有的 TypeScript 运行器,例如安装 `tsx` 后运行 `node --import tsx src/main.ts`, +或通过应用的打包器一起编译。 +仅用数据入口时,如果 `tsconfig.json` 会扫描整个 `src/`,可将 `src/sdk` 加入 `exclude`。 +TypeScript 仍会检查应用实际导入的 SDK 模块。 + +## 使用复制后的 UI + +脚本已改写复制后示例的组件导入。自己编写的页面可从 `src/components/kit/` 按文件位置导入。 +组件文件的层级与 registry 中 `src/components/` 后面的路径一致。例如在应用的 `src/App.tsx` 中: + +```tsx +import { Chat } from "./components/kit/chat/index.tsx"; +import { SessionSidebar } from "./components/kit/session-sidebar/index.tsx"; +``` + +复制的源码保留 `.ts` 和 `.tsx` 导入后缀。由打包器输出 JavaScript 的 TypeScript 项目可用 +`noEmit` 和 `allowImportingTsExtensions` 检查这些文件。 + +在 Tailwind v4 的应用样式入口导入本地主题并确保扫描本地组件源码。Vite 项目初次接入时, +安装 `tailwindcss` 与 `@tailwindcss/vite` 并在 Vite 配置中注册 `tailwindcss()` 插件。 +应用样式文件位于 `src/` 时,可以这样引入: + +```css +@import "tailwindcss"; +@import "./components/kit/theme.css"; +@source "./components/kit"; +``` + +遇到内容不同的本地组件、SDK 源码或示例时,脚本会在写入前报告冲突。先核对差异, +保留需要的定制。相同版本的未修改文件可重复运行脚本。 + +从旧版迁移时,先把已有的 SDK 源码和许可证合并到 `src/sdk/`。按文件所在位置,将业务代码及 +先前复制的组件和示例中的旧 SDK 导入改为指向公开源码的相对路径。核对代码已使用新路径后, +可清理前版的 `#kit-sdk/` 映射或旧的 `@openagentpack/kit-sdk` 本地包依赖。 + +接入完成后,在应用中运行类型检查和构建。需要真实对话时,另外验证应用自己的后端和网络配置。 + +## 接入三栏会话页 + +使用 `use-kit-chat` Skill 时,用下面的命令复制完整三栏示例。 + +```bash +node "/scripts/install.mjs" --dir "<应用目录>" --example experience.tsx +``` + +从 `src/kit-examples/use-kit-chat/experience.tsx` 导入 `Experience`。该命令还会复制同目录的 +资源面板和审批列表,以及它们所用的组件。为页面提供稳定的 Client、Provider 和应用回调,并导入本地主题。 diff --git a/scripts/skills/generate.mjs b/scripts/skills/generate.mjs index cbaa49d..5130a85 100644 --- a/scripts/skills/generate.mjs +++ b/scripts/skills/generate.mjs @@ -71,6 +71,7 @@ function renderApi(name, entries, model, root, renderedDocs) { "本页由 `pnpm gen:skills` 生成。更新公开 TypeScript 声明或中文 catalog 后重新生成。", "字段类型和必填性来自公开 API,行为说明依据所列文档整理。", "组件表格列出 Kit 自有属性。组件按声明继承标准的 React/DOM 属性。", + "参考中的包名用于仓库内导入。业务项目按[复制组件和 Kit SDK](copy-in.md)改用本地源码入口。", "", "## 目录", "", @@ -110,7 +111,7 @@ function renderExamples(root, name) { return [ "# 可编译示例", "", - "本页由随附的示例源文件生成。请按应用需求调整回调和运行时配置。", + "本页展示仓库中的示例源文件。按[复制组件和 Kit SDK](copy-in.md)用 `--example` 接入应用,脚本会生成相对导入路径。", "", ...examples.flatMap((file) => [ `## ${portablePath(relative(resolve(directory, "examples"), file))}`, @@ -207,6 +208,15 @@ function buildSkillOutputs(root, name, model, renderedDocs) { skillFiles.set("agents/openai.yaml", renderOpenAi(metadata)); skillFiles.set("references/api.md", renderApi(name, entries, model, root, renderedDocs)); skillFiles.set("references/examples.md", renderExamples(root, name)); + for (const [file, source] of [ + ["references/copy-in.md", "./copy-in.md"], + ["scripts/install.mjs", "../kit/skill-install.mjs"], + ["scripts/copy-in.mjs", "../kit/copy-in.mjs"], + ]) { + const text = readFileSync(new URL(source, import.meta.url), "utf8"); + if (file.endsWith(".md")) validateChineseMarkdown(text, source); + skillFiles.set(file, text); + } for (const file of filesUnder(resolve(source, "references"))) { const text = readFileSync(file, "utf8"); if (file.endsWith(".md")) validateChineseMarkdown(text, portablePath(relative(root, file))); diff --git a/scripts/skills/pack.mjs b/scripts/skills/pack.mjs index 633e7ff..51ee9b9 100644 --- a/scripts/skills/pack.mjs +++ b/scripts/skills/pack.mjs @@ -1,21 +1,30 @@ -import { cpSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"; -import { relative, resolve } from "node:path"; +import { cpSync, mkdirSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs"; +import { dirname, relative, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { createArchive } from "./archive.mjs"; +import { buildCopyInAssets } from "./copy-in-assets.mjs"; import { filesUnder, repositoryRoot, skillNames, skillOutputRoot, syncSkills } from "./generate.mjs"; +import { portablePath } from "./validate.mjs"; export function packSkills({ root = repositoryRoot, output = resolve(root, "assets/skills/dist"), docs = false } = {}) { syncSkills({ root }); + const copyInAssets = buildCopyInAssets(root); mkdirSync(output, { recursive: true }); - const names = skillNames(root); - const allFiles = []; - for (const name of names) { + const distributions = skillNames(root).map((name) => { const directory = skillOutputRoot(root, name); - const files = filesUnder(directory).map((file) => ({ - path: `${name}/${relative(directory, file)}`, - content: readFileSync(file), - mtimeMs: statSync(file).mtimeMs, - })); + const assets = [...copyInAssets.shared, ...copyInAssets.examples(name, resolve(directory, "examples"))]; + return { name, directory, assets }; + }); + const allFiles = []; + for (const { name, directory, assets } of distributions) { + const files = [ + ...filesUnder(directory).map((file) => ({ + path: `${name}/${portablePath(relative(directory, file))}`, + content: readFileSync(file), + mtimeMs: statSync(file).mtimeMs, + })), + ...assets.map((file) => ({ ...file, path: `${name}/${file.path}` })), + ]; allFiles.push(...files); writeFileSync(resolve(output, `${name}.tgz`), createArchive(files)); } @@ -24,15 +33,22 @@ export function packSkills({ root = repositoryRoot, output = resolve(root, "asse const publicDirectory = resolve(root, "apps/storybook/public/skills"); rmSync(publicDirectory, { recursive: true, force: true }); mkdirSync(publicDirectory, { recursive: true }); - for (const name of names) - cpSync(skillOutputRoot(root, name), resolve(publicDirectory, name), { + for (const { name, directory, assets } of distributions) { + cpSync(directory, resolve(publicDirectory, name), { recursive: true, preserveTimestamps: true, }); - for (const name of [...names, "kit-skills"]) + for (const asset of assets) { + const file = resolve(publicDirectory, name, asset.path); + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, asset.content); + utimesSync(file, asset.mtimeMs / 1000, asset.mtimeMs / 1000); + } + } + for (const name of [...distributions.map(({ name }) => name), "kit-skills"]) cpSync(resolve(output, `${name}.tgz`), resolve(publicDirectory, `${name}.tgz`)); } - return { skills: names.length, output }; + return { skills: distributions.length, output }; } if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { diff --git a/scripts/skills/src/kit-chat-provider/skill.md b/scripts/skills/src/kit-chat-provider/skill.md index ae27817..9bdc3ab 100644 --- a/scripts/skills/src/kit-chat-provider/skill.md +++ b/scripts/skills/src/kit-chat-provider/skill.md @@ -3,13 +3,17 @@ 使用本 Skill 在已有业务后端与 Kit 对话控制器之间编写前端适配。上游仍是百炼托管 Agent。 适配层的职责限于连接现有后端、映射响应及订阅生命周期。 +按[复制组件和 Kit SDK](references/copy-in.md)接入应用内的 SDK 源码。用 `--example` +复制适配器示例时,脚本会生成指向本地 SDK 源码的相对导入。多 Agent 示例还会复制 `Chat` 及其依赖, +使用时导入本地主题。 + ## 选择接入方式 | 现有后端 | 实现 | | --- | --- | | 返回标准 SDK `SessionEvent` 快照和控制帧,例如 Kit Server | 配置 `createSessionEventChatProvider`,参考[标准事件接入](references/normalized-events.md) | | 返回标准快照,但采用其他传输方式 | 实现 `ChatProvider` 的五个方法并映射生命周期回调 | -| 转发百炼原始 SSE | 使用 `@openagentpack/kit-sdk/providers/bailian` 的 `createBailianChatProvider`,参考[原始 SSE 接入](references/raw-sse.md) | +| 转发百炼原始 SSE | 使用本地 `src/sdk/providers/bailian/index.ts` 的 `createBailianChatProvider`,参考[原始 SSE 接入](references/raw-sse.md) | Web 应用与自建后端共用同一套公开配置。已有 KitClient 的应用可以继续通过 Context 接入, 也可以使用[兼容封装](examples/kit-client-provider.ts)。 @@ -52,4 +56,4 @@ Stream 将帧数据保留为文本。Request 可解析 JSON 语法,业务 Sche 提供 `SessionEvent` 和 `createBailianSessionEventNormalizer`。 服务端入口提供 `listSessionThreads` 和 `listSessionThreadEvents`。 升级依赖时,检查解析到的公开导出并运行相关合同测试和浏览器打包测试。 -真实后端和 Cloud 接入需独立验收。集成现有后端时沿用已发布的 SDK 与默认配置。 +真实后端和 Cloud 接入需独立验收。 diff --git a/scripts/skills/src/kit-components/references/setup.md b/scripts/skills/src/kit-components/references/setup.md index b8638f0..7e4076d 100644 --- a/scripts/skills/src/kit-components/references/setup.md +++ b/scripts/skills/src/kit-components/references/setup.md @@ -1,27 +1,10 @@ # 安装与源码归属 -## 从包导入 +## 接入组件和主题 -示例从 `@openagentpack/kit-chat-ui` 导入公开 API,并从 `@openagentpack/kit-sdk/messages` -及 `@openagentpack/kit-sdk/protocol` 导入类型。使用示例的 workspace 需要能访问这些包, -并提供兼容的 React 和 React DOM。当前仓库的 Kit 包为私有 workspace 包,以实际发布情况为准。 - -在已有 Tailwind v4 样式入口导入主题。 - -```css -@import "tailwindcss"; -@import "@openagentpack/kit-chat-ui/theme.css"; -``` - -为组件实际源码位置添加 Tailwind `@source`。自动扫描跳过 `node_modules`,也可能漏掉 -workspace 符号链接。仓库的 `apps/web/src/styles.css` 使用以下路径。 - -```css -@source "../../../packages/chat-ui/src/**/*.{ts,tsx}"; -``` - -该路径相对于样式表。copy-in 项目应改为扫描本地组件目录。 -在生成的 CSS 中检查响应式工具类和主题工具类。 +按[复制组件和 Kit SDK](copy-in.md)接入私有 Kit 依赖。复制的组件通过应用内源码路径导入, +类型通过 `src/sdk/messages/index.ts` 与 `src/sdk/protocol/index.ts` 读取。 +在已有 Tailwind v4 样式入口导入本地主题,检查生成的 CSS 包含所需的响应式工具类和主题工具类。 主题默认浅色,在主题作用域上设置 `data-kit-theme="dark"` 切换为深色。 员工端配色显式设置 `data-kit-appearance="workspace"`,支持的组件用 `variant="workspace"` @@ -30,9 +13,8 @@ workspace 符号链接。仓库的 `apps/web/src/styles.css` 使用以下路径 ## 复制组件源码 -从 Kit 仓库运行 `pnpm kit:add --dir `,将组件源码及登记的依赖复制到现有项目。 -也可以在目标项目通过绝对路径运行 `scripts/kit/add-component.mjs`。 -Registry 按源码文件分组,完整的公开组件名单见 [API 参考](api.md)。 +将下表的 registry 条目名传给 Skill 的复制脚本。Registry 按源码文件分组, +完整的公开组件名单见 [API 参考](api.md)。 | Registry 条目 | 可用组件 | | --- | --- | @@ -58,11 +40,8 @@ Registry 按源码文件分组,完整的公开组件名单见 [API 参考](api | `mermaid` | `Mermaid`、Actions 和 CodeHighlighter | | `tool-approval` | `ToolApprovalCard` 和 `ToolApprovalGroup` | -使用 copy-in 时在目标项目另行安装 npm 依赖。Markdown 使用 `react-markdown`、`remark-gfm`、 -`rehype-sanitize`、`lowlight` 和 `mermaid`。工具审批与确认使用 `@radix-ui/react-alert-dialog`。 -Layout 使用 `@radix-ui/react-dialog` 和 `@openagentpack/kit-sdk/hooks`。 -版本以目标项目与组件 registry、包清单共同支持的范围为准。更新已复制的组件前先查看源码差异, -合并需要保留的本地修改。 +组件所需的 npm 依赖随 registry 选择。Layout 还通过本地 SDK 的 `src/sdk/hooks/index.ts` +获取屏幕尺寸;确认弹窗通过 `@radix-ui/react-alert-dialog` 管理显式确认。 ## 运行时边界 diff --git a/scripts/skills/src/kit-components/skill.md b/scripts/skills/src/kit-components/skill.md index 61140dd..690fc81 100644 --- a/scripts/skills/src/kit-components/skill.md +++ b/scripts/skills/src/kit-components/skill.md @@ -1,7 +1,7 @@ # Kit 对话组件 -用 `@openagentpack/kit-chat-ui` 的公开组件搭建所需界面。示例使用包导入。 -通过 copy-in 引入的项目应改为从本地组件路径导入。 +用 Kit 的公开组件搭建所需界面。先按[复制组件和 Kit SDK](references/copy-in.md)将所需组件、 +主题和 SDK 源码复制进应用。用 `--example` 复制示例时,脚本会生成组件和 SDK 的相对导入路径。 ## 选择页面组合 @@ -35,8 +35,7 @@ 文件上传成功后仍需显式挂载到会话。 5. 工具审批与破坏性操作都需显式确认。`ToolApprovalCard` 提交一次经审阅的决定,并等待服务端权威状态。 破坏性操作由应用获取计划和确认令牌。 -6. 使用 Tailwind 工具类和已有 `--kit-*` token。即使组件位于 workspace 或链接包中, - 也要确保 Tailwind 能扫描组件源码。 +6. 使用 Tailwind 工具类和已有 `--kit-*` token,确保 Tailwind 能扫描复制后的组件源码。 ## 示例 diff --git a/scripts/skills/src/use-kit-chat/skill.md b/scripts/skills/src/use-kit-chat/skill.md index 71545fc..cdd1dfa 100644 --- a/scripts/skills/src/use-kit-chat/skill.md +++ b/scripts/skills/src/use-kit-chat/skill.md @@ -3,12 +3,16 @@ 让一个 `useChat` 实例持有一个会话,再将状态传给页面的消息、输入和审批组件。 `ChatProvider` 连接业务后端,React 的 `KitProvider` 为应用提供默认 KitClient Context。 +按[复制组件和 Kit SDK](references/copy-in.md)用 `--example` 接入所选示例。脚本会连同 +SDK、所需组件和随附示例一起复制,并生成相对导入路径。 + ## 选择接入入口 - **完整会话页或工作台**可从[三栏会话页](examples/experience.tsx)开始。左侧 `SessionSidebar`、 中间 `Chat` 和右侧 [Agent 资源面板](examples/agent-resources-panel.tsx)共享同一套 Agent 和会话选择。 - 一并复制面板和[审批列表](examples/approval-list.tsx),提供稳定的 Client、ChatProvider 和产物操作宿主。 - 导入 `@openagentpack/kit-chat-ui/theme.css`,并把示例及组件源码纳入 Tailwind v4 的扫描范围。 + 用[三栏示例复制命令](references/copy-in.md#接入三栏会话页)一并接入面板和[审批列表](examples/approval-list.tsx), + 提供稳定的 Client、ChatProvider 和产物操作宿主。导入本地主题, + 并把示例及组件源码纳入 Tailwind v4 的扫描范围。 - **Kit Server 和自建后端**使用 `useChat({ sessionId, provider })`。标准事件后端可配置 `createSessionEventChatProvider`,Web 应用走相同入口,见[自建后端示例](examples/custom-chat.tsx)。 - **已有 KitClient 的应用**可继续在 `KitProvider` 内使用 `useChat(sessionId)`, @@ -20,7 +24,7 @@ 让显式 Provider 复用相同的固定身份与取消边界,再将 `auth.chatProvider` 传给 `useChat`。 - **已有自定义后端适配器**可直接使用 `useChat({ sessionId, provider })`, 无需 `KitProvider`,见[自建后端示例](examples/custom-chat.tsx)。 -- **非 React 宿主**从 `@openagentpack/kit-sdk/chat` 导入 `createChatController`, +- **非 React 宿主**从应用的 `src/sdk/chat/index.ts` 导入 `createChatController`, 显式订阅及销毁,见[控制器示例](examples/controller.ts)。 - 拿到真实会话 ID 前传入 `null`。创建和列出会话通过独立接口完成。 - **Kit Server 的发现和用量**在 `KitProvider` 中使用 `usePlaza`、`useQuota` 和 `useQuotaRequests`, @@ -49,8 +53,9 @@ 按 `useChat` 的公开接口接入。禁止自行添加 `setMessages`、消息编辑、重新生成或请求队列, 也禁止自动重发失败的写请求。数据 Hook 接受显式 `client`,`useKitClient` 保留 Context 兼容入口。 -自定义 ChatProvider 接管对话传输。数据操作单独通过 `createKitClient({ request, operations })` 配置, -见[三栏会话页](examples/experience.tsx)。额度增加申请属于独立业务,由用户显式触发后调用 +自定义 ChatProvider 接管对话传输。数据操作通过本地 `src/sdk/providers/kit/index.ts` 的 +`createKitClient({ request, operations })` 配置。宿主创建稳定的 Client 和 Provider 并将其传给 +[三栏会话页](examples/experience.tsx)。额度增加申请属于独立业务,由用户显式触发后调用 `useCreateQuotaRequest().submit`,然后刷新用量及申请历史。 复用 `useAttachments` 和 `useArtifactActions` 管理上传与下载。文件选择、预览窗口和保存由宿主负责。 diff --git a/scripts/skills/tests/copy-in.test.mjs b/scripts/skills/tests/copy-in.test.mjs new file mode 100644 index 0000000..a4b3a4d --- /dev/null +++ b/scripts/skills/tests/copy-in.test.mjs @@ -0,0 +1,126 @@ +import assert from "node:assert/strict"; +import { execFileSync, spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, resolve } from "node:path"; +import { test } from "node:test"; +import { build } from "esbuild"; +import { repositoryRoot } from "../generate.mjs"; +import { packSkills } from "../pack.mjs"; + +function linkDependency(project, name, source) { + const link = resolve(project, "node_modules", name); + mkdirSync(dirname(link), { recursive: true }); + symlinkSync(source, link, "junction"); +} + +test("a standalone Skill copies local SDK entries and the selected UI closure into a project", async (t) => { + const directory = mkdtempSync(resolve(tmpdir(), "kit-skill-copy-in-")); + t.after(() => rmSync(directory, { recursive: true, force: true })); + packSkills({ output: directory }); + execFileSync("tar", ["-xzf", resolve(directory, "use-kit-chat.tgz"), "-C", directory]); + const installer = resolve(directory, "use-kit-chat/scripts/install.mjs"); + const project = resolve(directory, "external app"); + const packagePath = resolve(project, "package.json"); + const copy = (...components) => execFileSync(process.execPath, [installer, "--dir", project, ...components]); + mkdirSync(project); + writeFileSync( + packagePath, + JSON.stringify({ + name: "external-app", + private: true, + dependencies: { react: "^19", lowlight: "3.3.0" }, + }), + ); + + copy(); + const sdkPath = resolve(project, "src/sdk"); + const uiPath = resolve(project, "src/components/kit"); + const manifest = () => JSON.parse(readFileSync(packagePath, "utf8")); + assert.ok(!Object.hasOwn(manifest(), "imports")); + assert.ok(!manifest().dependencies["@openagentpack/kit-sdk"]); + assert.ok(manifest().dependencies["@openagentpack/sdk"]); + assert.ok(manifest().dependencies.zod); + assert.ok(!existsSync(resolve(sdkPath, "lib")), "source copy-in must be usable without a prebuilt SDK"); + assert.ok(!existsSync(resolve(project, "vendor")), "SDK sources must be copied into the application's src directory"); + assert.ok(!existsSync(uiPath), "SDK-only use should leave the app's UI untouched"); + + // Reuse the installed public dependencies to run without a registry, then edit the + // app's copy to show that a Node consumer sees it on the next application build. + for (const name of ["@openagentpack/sdk", "zod"]) { + linkDependency(project, name, resolve(repositoryRoot, "packages/sdk/node_modules", name)); + } + const requestSource = resolve(sdkPath, "request/index.ts"); + const originalRequest = readFileSync(requestSource, "utf8"); + writeFileSync(requestSource, `${originalRequest}\nexport const localEdit = "copied SDK source";\n`); + const nodeBundle = await build({ + absWorkingDir: project, + stdin: { + contents: + 'import { createRequest, localEdit } from "./src/sdk/request/index.ts"; console.log(typeof createRequest, localEdit);', + resolveDir: project, + }, + bundle: true, + packages: "external", + platform: "node", + format: "esm", + write: false, + logLevel: "silent", + }); + const entry = resolve(project, "request-consumer.mjs"); + writeFileSync(entry, nodeBundle.outputFiles[0].text); + assert.equal(execFileSync(process.execPath, [entry], { encoding: "utf8" }).trim(), "function copied SDK source"); + writeFileSync(requestSource, originalRequest); + + const unrelatedImports = { "#app-settings": "./src/settings.ts" }; + writeFileSync(packagePath, JSON.stringify({ ...manifest(), imports: unrelatedImports })); + copy("--example", "experience.tsx"); + assert.equal(manifest().dependencies.lowlight, "3.3.0", "preserve the application's existing version"); + assert.deepEqual(manifest().imports, unrelatedImports); + for (const name of ["react-markdown", "mermaid", "@radix-ui/react-dialog"]) { + assert.ok(manifest().dependencies[name], `missing runtime dependency ${name}`); + } + for (const file of ["chat/index.tsx", "message-list/index.tsx", "process/sub-agent-card/index.tsx", "theme.css"]) { + assert.ok(existsSync(resolve(uiPath, file)), `missing copied file ${file}`); + } + assert.ok(!existsSync(resolve(uiPath, "menu")), "an unrelated component should be absent"); + const examples = resolve(project, "src/kit-examples/use-kit-chat"); + for (const file of ["experience.tsx", "agent-resources-panel.tsx", "approval-list.tsx"]) { + const code = readFileSync(resolve(examples, file), "utf8"); + assert.match(code, /from "\.\.\/\.\.\/sdk\//); + assert.doesNotMatch(code, /#kit-sdk\/|@openagentpack\/kit-/); + } + const component = readFileSync(resolve(uiPath, "chat/index.tsx"), "utf8"); + assert.match(component, /from "\.\.\/\.\.\/\.\.\/sdk\//); + + for (const name of ["react-dom", ...Object.keys(manifest().dependencies)]) { + if (!existsSync(resolve(project, "node_modules", name))) + linkDependency(project, name, resolve(repositoryRoot, "packages/chat-ui/node_modules", name)); + } + const bundled = await build({ + absWorkingDir: project, + entryPoints: [resolve(examples, "experience.tsx")], + bundle: true, + jsx: "automatic", + platform: "browser", + write: false, + metafile: true, + logLevel: "silent", + }); + assert.ok( + Object.keys(bundled.metafile.inputs).some((file) => file.endsWith("src/sdk/chat/hooks/index.ts")), + "the browser build must use the copied SDK", + ); + + const before = readFileSync(packagePath, "utf8"); + copy("--example", "experience.tsx"); + assert.equal(readFileSync(packagePath, "utf8"), before, "reapplying the same selection is safe"); + const chatPath = resolve(uiPath, "chat/index.tsx"); + writeFileSync(chatPath, "// 目标项目自定义的组件\n"); + const conflict = spawnSync(process.execPath, [installer, "--dir", project, "chat", "menu"], { encoding: "utf8" }); + assert.equal(conflict.status, 1); + assert.match(conflict.stderr, /chat[/\\]index\.tsx/); + assert.equal(readFileSync(chatPath, "utf8"), "// 目标项目自定义的组件\n"); + assert.equal(readFileSync(packagePath, "utf8"), before); + assert.ok(!existsSync(resolve(uiPath, "menu")), "check conflicts before writing unrelated files"); +}); From 574fde3e070c9251ec87d3c7c163f924e835ea4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=82=9F=E6=89=AC?= Date: Wed, 18 Nov 2026 15:33:33 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs(storybook):=20=E9=87=8D=E7=BB=84?= =?UTF-8?q?=E7=BB=84=E4=BB=B6=E6=96=87=E6=A1=A3=E4=B8=8E=E6=9C=80=E4=BD=B3?= =?UTF-8?q?=E5=AE=9E=E8=B7=B5=E6=BC=94=E7=A4=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../docs/components/express/sender/page.tsx | 10 + .../components/demos/chrome-demo.tsx | 36 +-- .../components/demos/general-demo.tsx | 94 ++++--- .../storybook/components/demos/plaza-demo.tsx | 183 ++++++++++++++ .../components/demos/resource-panel-demo.tsx | 231 ++++++++++++++++++ .../components/demos/tool-approval-demo.tsx | 11 +- apps/storybook/components/showcase.tsx | 113 ++++++--- .../components/{chat.mdx => chat/index.mdx} | 24 +- .../content/docs/components/chat/meta.json | 4 + .../components/{express => chat}/sender.mdx | 5 +- .../content/docs/components/chrome.mdx | 152 ++++++------ .../content/docs/components/express/meta.json | 2 +- .../docs/components/feedback/actions.mdx | 2 +- .../components/feedback/artifact-card.mdx | 45 ++++ .../components/feedback/code-highlighter.mdx | 4 +- .../docs/components/feedback/markdown.mdx | 48 ++++ .../docs/components/feedback/mermaid.mdx | 2 +- .../docs/components/feedback/meta.json | 12 +- .../components/feedback/reasoning-block.mdx | 75 ++++++ .../components/feedback/tool-approval.mdx | 2 +- .../components/feedback/tool-call-card.mdx | 49 ++++ .../docs/components/general/message.mdx | 11 +- .../docs/components/general/session-list.mdx | 4 +- .../components/general/sub-agent-panel.mdx | 11 +- .../content/docs/components/index.mdx | 50 +++- .../{layout.mdx => layout/index.mdx} | 58 +++-- .../content/docs/components/layout/meta.json | 4 + .../content/docs/components/message.mdx | 151 ------------ .../content/docs/components/meta.json | 5 +- .../content/docs/components/plaza.mdx | 70 ------ .../components/plaza/activity-heatmap.mdx | 53 ++++ .../docs/components/plaza/category-tabs.mdx | 58 +++++ .../content/docs/components/plaza/meta.json | 4 + .../docs/components/plaza/meter-bar.mdx | 55 +++++ .../docs/components/plaza/plaza-card.mdx | 68 ++++++ apps/storybook/content/docs/concepts.mdx | 2 +- apps/storybook/content/docs/sdk/client.mdx | 2 +- .../content/docs/sdk/discovery-usage.mdx | 2 +- apps/storybook/e2e/chat-previews.spec.ts | 2 +- apps/storybook/e2e/message-previews.spec.ts | 6 +- .../e2e/tool-approval-preview.spec.ts | 22 ++ apps/storybook/lib/showcase-names.ts | 6 +- .../kit-chat-provider/references/api.md | 12 +- .../skills/kit-components/references/api.md | 98 ++++---- assets/skills/use-kit-chat/references/api.md | 28 +-- docs/protocol.md | 5 +- .../src/components/activity-heatmap/README.md | 2 +- .../src/components/artifact-card/README.md | 2 +- .../src/components/category-tabs/README.md | 2 +- .../chat-ui/src/components/chat/README.md | 2 +- .../chat-ui/src/components/chrome/README.md | 2 +- .../src/components/confirm-dialog/README.md | 2 +- .../src/components/empty-state/README.md | 2 +- .../src/components/error-state/README.md | 2 +- .../chat-ui/src/components/layout/README.md | 2 +- .../chat-ui/src/components/markdown/README.md | 2 +- .../src/components/meter-bar/README.md | 2 +- .../src/components/plaza-card/README.md | 2 +- .../chat-ui/src/components/plaza/README.md | 2 +- .../process/execution-group/README.md | 2 +- .../process/reasoning-block/README.md | 2 +- .../src/components/process/step/README.md | 2 +- .../process/tool-call-card/README.md | 2 +- .../components/process/tool-summary/README.md | 2 +- .../chat-ui/src/components/sender/README.md | 2 +- .../chat-ui/src/components/states/README.md | 2 +- .../src/components/status-indicator/README.md | 12 +- .../src/components/thread-panel/README.md | 2 +- .../skills/src/kit-components/catalog.json | 38 +-- scripts/skills/tests/generate.test.mjs | 4 +- 70 files changed, 1393 insertions(+), 594 deletions(-) create mode 100644 apps/storybook/app/docs/components/express/sender/page.tsx create mode 100644 apps/storybook/components/demos/plaza-demo.tsx create mode 100644 apps/storybook/components/demos/resource-panel-demo.tsx rename apps/storybook/content/docs/components/{chat.mdx => chat/index.mdx} (86%) create mode 100644 apps/storybook/content/docs/components/chat/meta.json rename apps/storybook/content/docs/components/{express => chat}/sender.mdx (96%) create mode 100644 apps/storybook/content/docs/components/feedback/artifact-card.mdx create mode 100644 apps/storybook/content/docs/components/feedback/markdown.mdx create mode 100644 apps/storybook/content/docs/components/feedback/reasoning-block.mdx create mode 100644 apps/storybook/content/docs/components/feedback/tool-call-card.mdx rename apps/storybook/content/docs/components/{layout.mdx => layout/index.mdx} (82%) create mode 100644 apps/storybook/content/docs/components/layout/meta.json delete mode 100644 apps/storybook/content/docs/components/message.mdx delete mode 100644 apps/storybook/content/docs/components/plaza.mdx create mode 100644 apps/storybook/content/docs/components/plaza/activity-heatmap.mdx create mode 100644 apps/storybook/content/docs/components/plaza/category-tabs.mdx create mode 100644 apps/storybook/content/docs/components/plaza/meta.json create mode 100644 apps/storybook/content/docs/components/plaza/meter-bar.mdx create mode 100644 apps/storybook/content/docs/components/plaza/plaza-card.mdx create mode 100644 apps/storybook/e2e/tool-approval-preview.spec.ts diff --git a/apps/storybook/app/docs/components/express/sender/page.tsx b/apps/storybook/app/docs/components/express/sender/page.tsx new file mode 100644 index 0000000..e780cb0 --- /dev/null +++ b/apps/storybook/app/docs/components/express/sender/page.tsx @@ -0,0 +1,10 @@ +const senderDocsPath = "/docs/components/chat/sender/"; + +export default function SenderDocsRedirect() { + return ( +
+ + 打开 Sender 输入框文档 +
+ ); +} diff --git a/apps/storybook/components/demos/chrome-demo.tsx b/apps/storybook/components/demos/chrome-demo.tsx index 617fe5c..a79034a 100644 --- a/apps/storybook/components/demos/chrome-demo.tsx +++ b/apps/storybook/components/demos/chrome-demo.tsx @@ -1,28 +1,6 @@ "use client"; -import { EmptyState, ErrorState, StatusIndicator, ThreadPanel } from "@openagentpack/kit-chat-ui"; -import type { ChatMessage } from "@openagentpack/kit-sdk/messages"; - -const THREADS: Record = { - th_subagent_billing: [ - { - id: "t1", - role: "user", - parts: [{ type: "text", text: "查一下这个月的发票状态" }], - status: "done", - createdAt: "2026-11-09T02:00:00Z", - threadId: "th_subagent_billing", - }, - { - id: "t2", - role: "assistant", - parts: [{ type: "text", text: "已提交,预计 2 个工作日内开出。" }], - status: "done", - createdAt: "2026-11-09T02:00:04Z", - threadId: "th_subagent_billing", - }, - ], -}; +import { EmptyState, ErrorState, StatusIndicator } from "@openagentpack/kit-chat-ui"; /** 状态由连接状态和 Turn 阶段共同决定。 */ export function StatusDemo() { @@ -47,18 +25,6 @@ export function StatusDemo() { ); } -/** 兼容旧的 threads 分组;新接入使用 Chat.multiAgent。 */ -export function ThreadDemo() { - return ( -
-

- 兼容旧版 ThreadPanel;原生主子 Agent 交互请查看 Chat 的 multiAgent 预览。 -

- -
- ); -} - /** 空态与错误态:目录为空、请求失败时的两种占位。 */ export function StatesDemo() { return ( diff --git a/apps/storybook/components/demos/general-demo.tsx b/apps/storybook/components/demos/general-demo.tsx index 23d042d..441c509 100644 --- a/apps/storybook/components/demos/general-demo.tsx +++ b/apps/storybook/components/demos/general-demo.tsx @@ -3,6 +3,7 @@ import { AgentHeader, EmptyState, + Layout, Menu, MenuContent, MenuItem, @@ -16,7 +17,7 @@ import { import type { ChatAgentThread, ChatMultiAgent } from "@openagentpack/kit-sdk/chat"; import type { ChatMessage } from "@openagentpack/kit-sdk/messages"; import type { SessionSummary } from "@openagentpack/kit-sdk/protocol"; -import { useRef, useState } from "react"; +import { type ReactNode, useRef, useState } from "react"; import { LogoMark, MessageSquare, SignalBars } from "../icons.tsx"; import { AGENT, AGENTS, SESSIONS } from "./layout-demo.tsx"; import { MESSAGES } from "./message-demo.tsx"; @@ -495,7 +496,7 @@ export function AgentHeaderActionsDemo() { ); } -/** 演示线程基座:loaded 即无加载态,mock 的 loadThreadEvents 保持空实现,时间线直接展示 messages。 */ +/** 演示线程默认已加载,历史预览可覆盖初始状态。 */ function panelThread(id: string, overrides: Partial): ChatAgentThread { return { id, @@ -560,28 +561,66 @@ const SUB_AGENT_MULTI: ChatMultiAgent = { loadThreadEvents: async () => undefined, }; -/** 分区概览:research 按展示名分组计数,行内区分运行中/完成/失败;勾选后线程清空,分区整体不渲染。 */ -export function SubAgentPanelDemo() { - const [empty, setEmpty] = useState(false); +function SubAgentResourcePreview({ multiAgent, children }: { multiAgent: ChatMultiAgent; children?: ReactNode }) { + const [asideOpen, setAsideOpen] = useState(true); return ( -
( + setAsideOpen((open) => !open)} + > + 资源 + + } + /> + )} + asideOpen={asideOpen} + onAsideOpenChange={setAsideOpen} + aside={({ closeButton }) => ( +
+ {closeButton ? ( +
+ 资源 + {closeButton} +
+ ) : null} +
+ +
+
+ )} > + {children} + + ); +} + +/** 分区概览:research 按展示名分组计数,清空线程后分区整体不渲染。 */ +export function SubAgentPanelDemo() { + const [empty, setEmpty] = useState(false); + return ( +
-
- -
-
+ ); } -/** 翻页演示:mock 400ms 拉取更早事件后清除 nextPageToken;期间按钮禁用并显示加载文案。 */ +/** 历史分页示例中追加到前面的较早事件。 */ const SUB_AGENT_OLDER_MESSAGES: ChatMessage[] = [ { id: "sub-agent-demo-0", @@ -605,8 +644,7 @@ const SUB_AGENT_HISTORY_THREADS: ChatAgentThread[] = [ task: "对比三家云厂商的 API 定价与配额,输出对比表", createdAt: "2026-11-10T01:30:00.000Z", endedAt: "2026-11-10T01:30:48.000Z", - messages: SUB_AGENT_MESSAGES, - nextPageToken: "page-2", + loaded: false, }), panelThread("sthr-slide", { name: "slide-maker", @@ -615,6 +653,14 @@ const SUB_AGENT_HISTORY_THREADS: ChatAgentThread[] = [ createdAt: "2026-11-10T02:00:00.000Z", endedAt: "2026-11-10T02:00:31.000Z", historyAvailable: false, + messages: [ + { + id: "sub-agent-slide-demo", + role: "assistant", + status: "done", + parts: [{ type: "text", id: "sub-agent-slide-demo:text", text: "已整理季度汇报的结构与逐页标题。" }], + }, + ], }), ]; @@ -629,7 +675,7 @@ export function SubAgentPanelHistoryDemo() { selectThread: () => undefined, refreshThreads: async () => undefined, loadThreadEvents: async (id, options) => { - if (!options?.more) return; + const more = options?.more === true; setThreads((current) => current.map((thread) => (thread.id === id ? { ...thread, loading: true } : thread))); await new Promise((resolve) => setTimeout(resolve, 400)); setThreads((current) => @@ -638,22 +684,14 @@ export function SubAgentPanelHistoryDemo() { ? { ...thread, loading: false, - nextPageToken: null, - messages: [...SUB_AGENT_OLDER_MESSAGES, ...thread.messages], + loaded: true, + nextPageToken: more ? null : "page-2", + messages: more ? [...SUB_AGENT_OLDER_MESSAGES, ...thread.messages] : SUB_AGENT_MESSAGES, } : thread, ), ); }, }; - return ( -
-
- -
-
- ); + return ; } diff --git a/apps/storybook/components/demos/plaza-demo.tsx b/apps/storybook/components/demos/plaza-demo.tsx new file mode 100644 index 0000000..2ae2531 --- /dev/null +++ b/apps/storybook/components/demos/plaza-demo.tsx @@ -0,0 +1,183 @@ +"use client"; + +import { ActivityHeatmap, CategoryTabs, MeterBar, PlazaCard, type PlazaTabId } from "@openagentpack/kit-chat-ui"; +import type { PlazaEntry, PlazaView } from "@openagentpack/kit-sdk/protocol"; +import { useState } from "react"; + +const exampleAgent: PlazaEntry = { + slug: "weekly-writer", + display_name: "周报助手", + icon: "📝", + category: "writing", + featured: true, + description: "把会议纪要和任务记录整理成可以直接发送的周报。", + suggested_prompts: ["把这些任务记录整理成一份周报"], + capabilities: { streaming: true, fileUpload: true, artifacts: true, threads: false, reasoning: false }, + stats: { turns_30d: 28, mine: true }, +}; + +const categories: PlazaView["categories"] = [ + { id: "writing", name: "写作", count: 1 }, + { id: "coding", name: "编程", count: 1 }, + { id: "data", name: "数据分析", count: 1 }, +]; + +const exampleAgents = [ + exampleAgent, + { slug: "code-reviewer", display_name: "代码审阅助手", category: "coding", featured: false }, + { slug: "table-analyst", display_name: "表格分析助手", category: "data", featured: true }, +]; + +const activity = [0, 1, 4, 0, 6, 2, 0, 3, 0, 8, 1, 4, 0, 2, 0, 6, 9, 4, 0, 1, 0, 3, 5, 0, 7, 3, 0, 1, 2, 0].map( + (turns, index) => ({ day: `2026-10-${String(index + 1).padStart(2, "0")}`, turns }), +); + +export function PlazaCardDemo() { + const [selected, setSelected] = useState(""); + return ( +
+ +

+ {selected && `已选中 ${selected}`} +

+
+ ); +} + +export function CategoryTabsDemo() { + const [active, setActive] = useState("featured"); + const visibleAgents = exampleAgents.filter((agent) => + active === "featured" ? agent.featured : agent.category === active, + ); + return ( +
+ +
    + {visibleAgents.map((agent) => ( +
  • + {agent.display_name} +
  • + ))} +
+
+ ); +} + +export function MeterBarDemo() { + const [used, setUsed] = useState(60); + const [unlimited, setUnlimited] = useState(false); + const limit = 100; + return ( +
+
+ 当月额度 + + {unlimited ? `已用 ${used},不限量` : `已用 ${used} / ${limit}`} + +
+ + + +
+ ); +} + +export function ActivityHeatmapDemo() { + const [zeroTurns, setZeroTurns] = useState(false); + const days = zeroTurns ? activity.map(({ day }) => ({ day, turns: 0 })) : activity; + return ( +
+ + +
+ ); +} + +export const PLAZA_CARD_CODE = `import { PlazaCard } from "@openagentpack/kit-chat-ui"; +import type { PlazaEntry } from "@openagentpack/kit-sdk/protocol"; + +export function AgentCard({ + entry, + openAgent, +}: { + entry: PlazaEntry; + openAgent: (slug: string) => void; +}) { + return ; +}`; + +export const CATEGORY_TABS_CODE = `import { CategoryTabs, type PlazaTabId } from "@openagentpack/kit-chat-ui"; +import type { PlazaView } from "@openagentpack/kit-sdk/protocol"; +import { useState } from "react"; + +export function AgentCategories({ view }: { view: PlazaView }) { + const [active, setActive] = useState("featured"); + const agents = view.agents.filter((agent) => + active === "featured" ? view.featured.includes(agent.slug) : agent.category === active + ); + + return ( + <> + +
    + {agents.map((agent) =>
  • {agent.display_name}
  • )} +
+ + ); +}`; + +export const METER_BAR_CODE = `import { MeterBar } from "@openagentpack/kit-chat-ui"; + +export function UsageProgress({ + used, + limit, + unlimited, +}: { + used: number; + limit: number; + unlimited?: boolean; +}) { + return ( + <> +

已用 {used} / {unlimited ? "不限量" : limit}

+ + + ); +}`; + +export const ACTIVITY_HEATMAP_CODE = `import { ActivityHeatmap } from "@openagentpack/kit-chat-ui"; +import { useQuota } from "@openagentpack/kit-sdk/usage/hooks"; + +export function RecentActivity() { + const { quota } = useQuota(); + return quota ? : null; +}`; diff --git a/apps/storybook/components/demos/resource-panel-demo.tsx b/apps/storybook/components/demos/resource-panel-demo.tsx new file mode 100644 index 0000000..79c8b03 --- /dev/null +++ b/apps/storybook/components/demos/resource-panel-demo.tsx @@ -0,0 +1,231 @@ +"use client"; + +import { AgentHeader, Chat, FileCard, Layout, StatusIndicator, SubAgentPanel } from "@openagentpack/kit-chat-ui"; +import type { ChatMultiAgent } from "@openagentpack/kit-sdk/chat"; +import type { ChatMessage } from "@openagentpack/kit-sdk/messages"; +import { type ReactNode, useRef, useState } from "react"; +import { ArrowRight, Book, Database, Terminal } from "../icons.tsx"; +import { CONTROL_CLASS } from "./general-demo.tsx"; +import { AGENT } from "./layout-demo.tsx"; + +const agent = { ...AGENT, display_name: "方案助手", description: "检索参考资料,整理方案与评审建议。" }; +const artifact = { name: "方案评审.md", type: "text/markdown" }; +const multiAgent: ChatMultiAgent = { + selectedThreadId: null, + threads: [ + { + id: "sthr_resource_research", + name: "资料研究员", + task: "整理方案的参考资料", + status: "idle", + createdAt: "2026-11-18T01:00:00.000Z", + endedAt: "2026-11-18T01:00:36.000Z", + messages: [ + { + id: "resource-research-answer", + role: "assistant", + status: "done", + parts: [ + { + id: "resource-research-answer:text", + type: "text", + text: "已整理三项参考依据,并补充方案的风险与验收条件。", + }, + ], + }, + ], + loading: false, + error: null, + nextPageToken: null, + historyAvailable: true, + loaded: true, + }, + ], + loading: false, + error: null, + selectThread: () => undefined, + refreshThreads: async () => undefined, + loadThreadEvents: async () => undefined, +}; + +function ResourceSection({ title, children }: { title: string; children: ReactNode }) { + return ( +
+ + {title} + + +
{children}
+
+ ); +} + +/** Layout 管理右栏与移动覆盖层,各业务分区通过公开组件组合。 */ +export function ResourcePanelDemo() { + const [asideOpen, setAsideOpen] = useState(true); + const [note, setNote] = useState(""); + const [messages, setMessages] = useState([ + { + id: "resource-main-answer", + role: "assistant", + status: "done", + parts: [{ id: "resource-main-answer:text", type: "text", text: "资料整理完成,已生成方案评审.md。" }], + }, + ]); + const sequence = useRef(0); + return ( + ( + + + + + } + /> + )} + asideOpen={asideOpen} + onAsideOpenChange={setAsideOpen} + aside={({ closeButton }) => ( +
+ {closeButton ? ( +
+ 资源 + {closeButton} +
+ ) : null} +
+ +

{agent.display_name}

+

{agent.description}

+
+ +
+ +
    +
  • + + 资料整理 +
  • +
  • + + 文档检索服务 +
  • +
+
+ +
+ + write_file + + 每次询问 + +
+
+ +

团队知识

+

+ 产品术语与评审规范 +

+
+ + setNote("已触发预览回调,方案评审.md(本地演示)")} + onDownload={() => setNote("已触发下载回调,方案评审.md(本地演示)")} + /> +

+ {note} +

+
+
+
+
+ )} + > + { + sequence.current += 1; + const id = `resource-message-${sequence.current}`; + setMessages((current) => [ + ...current, + { id, role: "user", status: "done", parts: [{ id: `${id}:text`, type: "text", text }] }, + ]); + }} + /> +
+ ); +} + +export const RESOURCE_PANEL_CODE = `import { AgentHeader, Chat, FileCard, Layout, StatusIndicator, SubAgentPanel } from "@openagentpack/kit-chat-ui"; +import { useState } from "react"; + +const [resourcesOpen, setResourcesOpen] = useState(true); + + ( + + + + + )} + /> + )} + asideOpen={resourcesOpen} + onAsideOpenChange={setResourcesOpen} + aside={({ closeButton }) => ( +
+ {closeButton ? ( +
+ 资源{closeButton} +
+ ) : null} +
+
+ Agent 信息 +

{agent.display_name}

+

{agent.description}

+
+ + {resourceSections} + {chat.artifacts.map((file) => ( + openArtifact(file.file_id, file.content_type)} + onDownload={() => downloadArtifact(file.file_id)} /> + ))} +
+
+ )} +> + chat.send(text, { skills })} onStop={chat.stop} /> +
+// resourceSections 由业务页面渲染技能、MCP、工具和记忆库。 +// openArtifact 与 downloadArtifact 由调用方接入文件预览和下载。`; diff --git a/apps/storybook/components/demos/tool-approval-demo.tsx b/apps/storybook/components/demos/tool-approval-demo.tsx index 9a10125..a84eaa2 100644 --- a/apps/storybook/components/demos/tool-approval-demo.tsx +++ b/apps/storybook/components/demos/tool-approval-demo.tsx @@ -40,7 +40,7 @@ const GROUP_REQUESTS: ChatToolApproval[] = [ }, ]; -/** 允许与拒绝一步直提:完整参数已可见,提交中按钮进入 busy,成功后卡片只显示状态。 */ +/** 单项审批允许或拒绝后,展示提交的决定。 */ export function ToolApprovalDemo() { const [approval, setApproval] = useState(REQUEST); return ( @@ -49,11 +49,16 @@ export function ToolApprovalDemo() { className="flex min-w-0 flex-1 flex-col bg-[var(--kit-bg)] text-[var(--kit-fg)]" >
- - 当前状态:{approval.status} + {approval.result && (approval.result === "allow" ? "已提交「允许」" : "已提交「拒绝」")}
import("./demos/layout-demo.tsx").then((module) loading: () =>

正在加载布局预览…

, }); +const ResourcePanelDemo = dynamic( + () => import("./demos/resource-panel-demo.tsx").then((module) => module.ResourcePanelDemo), + { + ssr: false, + loading: () =>

正在加载资源面板预览…

, + }, +); + interface ShowcaseEntry { title: string; /** copy-in 命令:必须是 packages/chat-ui/registry.json 里真实存在的组件名;SDK API 演示可省略 */ @@ -235,18 +254,30 @@ const AGENT_HEADER_ACTIONS_CODE = `import { AgentHeader, StatusIndicator } from // 显式传 actions(含 null)时替代默认新会话按钮;省略 actions 保留 onNewSession 的兼容按钮。`; -const SUB_AGENT_PANEL_CODE = `import { SubAgentPanel } from "@openagentpack/kit-chat-ui"; - -// 资源面板(右栏)分区:multiAgent 直接来自 useChat() 快照 - -// 子 Agent 按展示名去重分组;会话内尚无线程时分区不渲染`; +const SUB_AGENT_PANEL_CODE = `import { Layout, SubAgentPanel } from "@openagentpack/kit-chat-ui"; + +// resourcesOpen 由页头的资源按钮控制,multiAgent 来自 useChat()。 + ( +
+ {closeButton ? ( +
资源{closeButton}
+ ) : null} +
+ +
+
+ )} +> + {conversation} +
`; -const SUB_AGENT_PANEL_HISTORY_CODE = `import { SubAgentPanel } from "@openagentpack/kit-chat-ui"; +const SUB_AGENT_PANEL_HISTORY_CODE = `${SUB_AGENT_PANEL_CODE} -// 点任务行打开该次派发的执行记录弹窗:主 Agent 指令 + 子线程自身事件时间线 - -// 时间线读子线程事件(loadThreadEvents),不依赖主消息流加载; -// nextPageToken 非空时展示「加载更早消息」(more: true)翻页,historyAvailable 为 false 时提示仅显示本次连接收到的消息`; +// 打开任务记录时按需读取该线程的历史。 +// nextPageToken 非空时可加载更早消息。历史不可用时保留本次连接收到的消息。`; const SESSION_SIDEBAR_CODE = `import { SessionSidebar } from "@openagentpack/kit-chat-ui"; @@ -938,18 +969,17 @@ const chat = useChat(sessionId); onStop={chat.stop} /> -// 主 Agent 可发送;子 Agent 只读,支持历史分页与失败重试。 -// 子 Agent 在主消息流中展开只读历史,主输入草稿保持;不再另接 ThreadPanel。 -// 在线预览使用本地 ChatMultiAgent 数据;真实应用由 useChat / Provider 查询。`; +// 子 Agent 卡片可展开查看历史、翻页和重试。开合卡片时保留主输入草稿。`; -const APPROVAL_CODE = `import { ToolApprovalGroup } from "@openagentpack/kit-chat-ui"; +const APPROVAL_CODE = `import { ToolApprovalCard } from "@openagentpack/kit-chat-ui"; import { useChat } from "@openagentpack/kit-sdk/chat/hooks"; const chat = useChat(sessionId); +const approval = chat.approvals[0]; -{chat.approvals.length > 0 ? ( - `; -const THREAD_CODE = `import { ThreadPanel } from "@openagentpack/kit-chat-ui"; - -// 仅用于兼容旧版分组视图;新接入使用 Chat multiAgent={chat.multiAgent}。 -{Object.keys(chat.threads).length > 0 ? : null}`; - const STATES_CODE = `import { EmptyState, ErrorState } from "@openagentpack/kit-chat-ui"; {loading ? null : error ? : null} @@ -1559,13 +1584,13 @@ const SHOWCASES: Record = { }, "sub-agent-panel": { title: "SubAgentPanel(分区概览与空态)", - command: "pnpm kit:add sub-agent-panel", + command: "pnpm kit:add sub-agent-panel && pnpm kit:add layout", code: SUB_AGENT_PANEL_CODE, Demo: SubAgentPanelDemo, }, "sub-agent-panel-history": { title: "SubAgentPanel(执行记录弹窗与历史加载)", - command: "pnpm kit:add sub-agent-panel", + command: "pnpm kit:add sub-agent-panel && pnpm kit:add layout", code: SUB_AGENT_PANEL_HISTORY_CODE, Demo: SubAgentPanelHistoryDemo, }, @@ -1799,7 +1824,8 @@ const SHOWCASES: Record = { }, chrome: { title: "Layout / AgentHeader / ConfirmDialog", - command: "pnpm kit:add layout && pnpm kit:add chrome && pnpm kit:add chat", + command: + "pnpm kit:add layout && pnpm kit:add chrome && pnpm kit:add chat && pnpm kit:add session-sidebar && pnpm kit:add menu", code: LAYOUT_CODE, Demo: LayoutDemo, }, @@ -1809,13 +1835,38 @@ const SHOWCASES: Record = { code: STATUS_CODE, Demo: StatusDemo, }, - threads: { - title: "ThreadPanel(旧版分组兼容)", - command: "pnpm kit:add chrome", - code: THREAD_CODE, - Demo: ThreadDemo, + "resource-panel": { + title: "Layout.aside(信息栏)", + command: + "pnpm kit:add layout && pnpm kit:add agent-header && pnpm kit:add status-indicator && pnpm kit:add chat && pnpm kit:add sub-agent-panel && pnpm kit:add file-card", + code: RESOURCE_PANEL_CODE, + Demo: ResourcePanelDemo, }, states: { title: "EmptyState / ErrorState", command: "pnpm kit:add chrome", code: STATES_CODE, Demo: StatesDemo }, + "plaza-card": { + title: "PlazaCard(智能体卡片)", + command: "pnpm kit:add plaza-card", + code: PLAZA_CARD_CODE, + Demo: PlazaCardDemo, + }, + "category-tabs": { + title: "CategoryTabs(广场分类)", + command: "pnpm kit:add category-tabs", + code: CATEGORY_TABS_CODE, + Demo: CategoryTabsDemo, + }, + "meter-bar": { + title: "MeterBar(用量条)", + command: "pnpm kit:add meter-bar", + code: METER_BAR_CODE, + Demo: MeterBarDemo, + }, + "activity-heatmap": { + title: "ActivityHeatmap(活跃热力图)", + command: "pnpm kit:add activity-heatmap", + code: ACTIVITY_HEATMAP_CODE, + Demo: ActivityHeatmapDemo, + }, "sse-stream": { title: "createSseStream(解码、分帧与取消)", code: SSE_STREAM_CODE, diff --git a/apps/storybook/content/docs/components/chat.mdx b/apps/storybook/content/docs/components/chat/index.mdx similarity index 86% rename from apps/storybook/content/docs/components/chat.mdx rename to apps/storybook/content/docs/components/chat/index.mdx index 0a3264b..6815dce 100644 --- a/apps/storybook/content/docs/components/chat.mdx +++ b/apps/storybook/content/docs/components/chat/index.mdx @@ -1,10 +1,10 @@ --- -title: Chat 与 Sender 组合 -description: 消息列表、流式中间态与输入框的在线预览 +title: Chat 对话区 +description: 组合消息列表、欢迎态、流式状态和默认输入框 --- -`Chat` 组合 [MessageList](/docs/components/general/message-list) 与 -[Sender](/docs/components/express/sender),只认 props,不 fetch、不依赖 server。 +`Chat` 将 [MessageList](/docs/components/general/message-list) 和默认的 +[Sender](/docs/components/chat/sender) 组装成对话区。调用方传入消息和生成状态,通过回调接入发送与停止操作。 ```tsx import { Chat } from "@openagentpack/kit-chat-ui"; @@ -23,7 +23,7 @@ pnpm kit:add chat - 需要「消息列表 + 输入框」标准组合:流式中间态、审批嵌入、欢迎态与滚动跟随一次到位。 - 只要列表或只要输入框时,分别用 [MessageList](/docs/components/general/message-list) 与 - [Sender](/docs/components/express/sender)。 + [Sender](/docs/components/chat/sender)。 ## 代码演示 @@ -37,7 +37,8 @@ pnpm kit:add chat ### 多 Agent 对话 -子 Agent 卡片、只读历史、分页与重试可操作;先输入草稿再开合卡片,观察草稿不变。 +子 Agent 卡片出现在主消息流的派发位置。展开卡片可查看只读历史、加载更早消息和重试。 +先输入草稿再开合卡片,可以观察主输入框里的草稿。 @@ -115,13 +116,14 @@ export function SessionChat({ sessionId, skills }: { sessionId: string | null; s 传入 `multiAgent={chat.multiAgent}`,契约见 [`ChatMultiAgent`](/docs/components/general/sub-agent-panel#chatmultiagent)。执行中的子 Agent 自动展开、完成后收起,也可手动开合;历史经 `loadThreadEvents(id, { more })` 翻页、 -`{ retry: true }` 重试,无历史查询能力时明确提示。子 Agent 无独立输入与审批入口,主输入区的 -停止按钮停止整个主会话。资源面板可另接 [SubAgentPanel](/docs/components/general/sub-agent-panel)。 +`{ retry: true }` 重试,无历史查询能力时明确提示。主输入区的停止按钮停止整个主会话。 +右侧资源面板的 `SubAgentPanel` 从同一个 `multiAgent` 快照读取派发记录。 +[资源面板执行记录演示](/docs/components/general/sub-agent-panel#执行记录弹窗与历史加载) ## 自定义输入区 附件、快捷指令或自定义提交策略通过 `sender` 插槽接入,完整组合见 -[Sender 附件示例](/docs/components/express/sender) 与 [Suggestion](/docs/components/express/suggestion)。 +[Sender 附件示例](/docs/components/chat/sender#组合附件与上传) 与 [Suggestion](/docs/components/express/suggestion)。 自定义 Sender 传 `variant="workspace"`,并连接 `value`、`onChange`、`onSubmit`、 `loading={chat.turnRunning}`、`submitDisabled={!chat.canSend}` 与 `onCancel={chat.stop}`; 此时 Chat 不再接管输入区,但仍需传 `turnRunning` 供等待首帧指示。 @@ -136,7 +138,7 @@ export function SessionChat({ sessionId, skills }: { sessionId: string | null; s | `sending` | `boolean` | `false` | 发送请求在途(含新建会话):乐观气泡出现前列表尾显示「发送中…」指示,回合开始后归「生成中…」 | | `canSend` | `boolean` | `true` | 是否允许提交;设 false 仍可编辑草稿 | | `composerDisabled` | `boolean` | `false` | 禁用默认输入区,例如配额耗尽;已有生成仍可停止。自定义 sender 需自行传入 disabled | -| `approvals` | `ReactNode` | — | 主 Agent 当前待办审批卡,内嵌到消息流末尾;输入区上方只留精简等待提示 | +| `approvals` | `ReactNode` | — | 当前会话的待办审批卡,内嵌到主消息流末尾。输入区上方显示等待提示 | | `onSend` | `(text: string, skills?: string[]) => void \| Promise` | — | 默认 Sender 提交文本和派生技能名;成功后清理未被改写的草稿 | | `onStop` | `() => void \| Promise` | — | 默认 Sender 的停止回调 | | `onArtifactDownload` | `(fileId: string) => void` | — | 文件下载回调 | @@ -167,5 +169,5 @@ export function SessionChat({ sessionId, skills }: { sessionId: string | null; s 「等待审批」提示走 `--kit-text-label` 文字档位;输入区底部留白用 `--kit-space-3` / `--kit-space-6` 与移动端安全区取较大值。消息与输入区本体(气泡、分片、 工具卡、附件、技能 chip)的 token 分别见 [MessageList](/docs/components/general/message-list)、 -[Message](/docs/components/message) 与 [Sender](/docs/components/express/sender);更多主题配置见 +[Message](/docs/components/general/message) 与 [Sender](/docs/components/chat/sender);更多主题配置见 [组件总览](/docs/components#主题)。 diff --git a/apps/storybook/content/docs/components/chat/meta.json b/apps/storybook/content/docs/components/chat/meta.json new file mode 100644 index 0000000..27a3dd6 --- /dev/null +++ b/apps/storybook/content/docs/components/chat/meta.json @@ -0,0 +1,4 @@ +{ + "title": "对话", + "pages": ["index", "sender"] +} diff --git a/apps/storybook/content/docs/components/express/sender.mdx b/apps/storybook/content/docs/components/chat/sender.mdx similarity index 96% rename from apps/storybook/content/docs/components/express/sender.mdx rename to apps/storybook/content/docs/components/chat/sender.mdx index b6ca35c..e9f0bf7 100644 --- a/apps/storybook/content/docs/components/express/sender.mdx +++ b/apps/storybook/content/docs/components/chat/sender.mdx @@ -3,8 +3,9 @@ title: Sender 输入框 description: 受控输入、提交、停止生成与头尾插槽 --- -`Sender` 渲染对话输入框:受控草稿、回车/按钮提交与生成中停止,头尾插槽挂附件或技能。 -它只管理输入交互,不发送请求;与 [Chat](/docs/components/chat) 组合时由 Chat 接线会话状态。 +`Sender` 是可单独使用的对话输入框,支持草稿编辑、回车或按钮提交,以及生成中停止。 +调用方通过 `onSubmit` 和 `onCancel` 接入发送与停止。也可通过 [Chat](/docs/components/chat) 的 +`sender` 插槽替换默认输入框,在头尾插槽中加入附件或技能入口。 ```tsx import { Sender } from "@openagentpack/kit-chat-ui"; diff --git a/apps/storybook/content/docs/components/chrome.mdx b/apps/storybook/content/docs/components/chrome.mdx index 3ae2c6b..20446e8 100644 --- a/apps/storybook/content/docs/components/chrome.mdx +++ b/apps/storybook/content/docs/components/chrome.mdx @@ -1,123 +1,121 @@ --- -title: 页面组合与辅助交互 -description: 侧栏与页头组合、状态灯、子线程、空错态与确认弹窗 +title: 最佳实践 +description: 对话页布局、信息栏、会话操作确认、工具审批、状态提示与错误重试 --- -`pnpm kit:add chrome` 复制页面组合与辅助交互组件,并带出所依赖的 -[AgentHeader](/docs/components/general/agent-header)、[Message](/docs/components/general/message) -与 EmptyState / ErrorState;会话目录 [SessionSidebar](/docs/components/general/session-sidebar) 按独立条目复制。 -完整骨架还组合 Layout 与 Chat,示例问题使用 [Prompts](/docs/components/wake/prompts): +用 `Layout` 组织会话侧栏、移动端抽屉和页头,用 `Chat` 承载消息与输入区。在此基础上接入 +信息栏、会话操作确认、工具审批、连接状态、欢迎态和失败重试。 + +```tsx +import { + AgentHeader, Chat, ConfirmDialog, FileCard, Layout, SessionSidebar, StatusIndicator, SubAgentPanel, ToolApprovalCard, +} from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径): ```bash pnpm kit:add layout pnpm kit:add chrome pnpm kit:add chat +pnpm kit:add session-sidebar +pnpm kit:add menu pnpm kit:add prompts +pnpm kit:add tool-approval +pnpm kit:add sub-agent-panel +pnpm kit:add file-card +pnpm add @radix-ui/react-dialog @radix-ui/react-alert-dialog @radix-ui/react-dropdown-menu ``` +`chrome` 批量复制页头、状态灯、确认弹窗、空态、错误态和子线程兼容面板。 +渲染依赖见 [Markdown 接入](/docs/components/feedback/markdown#接入),主题配置见 [组件总览](/docs/components#主题)。 +交给 coding agent 接入时使用 [kit-components Skill](/docs/skill/kit-components)。 + ## 何时使用 -- 按 antdx 骨架组装完整页面:会话目录、紧凑页头与聊天区一次到位。 -- 页面里有删除 / 归档等破坏性动作,需要确认弹窗与服务端一次性确认令牌。 -- 空目录、请求失败等占位态需要统一视觉,不散写占位文案。 +- 将会话目录、页头和聊天区组合为桌面与手机共用的对话页。 +- 在归档或删除会话前展示操作影响,并取得用户确认。 +- 展示欢迎、加载、重连与错误重试状态。 ## 代码演示 +预览使用本地数据。演示面板内可切换设备视口、查看源码和复制接入命令。 + ### 页面骨架(含破坏性动作确认) -选中会话、新建会话,经行尾「更多操作」菜单触发归档 / 删除确认弹窗。 +可新建或切换会话,从行尾「更多操作」打开归档或删除确认。切换到手机视口后,从页头打开会话抽屉。 -两条硬约束: +### 信息栏 -1. 破坏性动作必须 `ConfirmDialog`(`role="alertdialog"`)语义,服务端再校验一次性确认令牌 - (`POST .../plan` → 带 `confirm_token` 执行,缺令牌 400 / 重放 428)。 -2. 行内操作**不能按钮嵌按钮**:真实点击归最外层元素,内层按钮点不动(合成 `el.click()` 能触发, - 只有真机抓得到);`SessionList` 行容器是 `div`,标题按钮与 `menu` 触发器是并列 `button`, - 动作在 [Menu](/docs/components/basic/menu) 弹层内。 +信息栏通过 `Layout.aside` 展示 Agent 信息、子 Agent、技能与 MCP、工具、记忆库和产物。 +点击页头「资源」可展开或收起面板。各分区支持折叠,子 Agent 的任务行可打开执行记录。 +切换到手机视口后,点击「资源」打开全屏面板。 -### 状态灯 + -`phase` 与 `connection` 组合区分已连接、生成中、等待审批、正在停止、已中断、重连中与错误。 +`Layout` 提供响应式外壳,`SubAgentPanel` 展示子 Agent 分区,`FileCard` 绑定产物的预览与下载。 +预览中的文件操作显示本地回调结果。完整资源分区由业务页面组合,体验页实现位于 +`apps/web/src/features/chat/aside-panel.tsx` 的 `AsidePanelSections`。 +[Layout 右栏接口](/docs/components/layout#api) - +### 工具审批 -新接入传 `phase={chat.phase}`、`connection={chat.connection}`、`error={chat.streamError}`; -`variant="badge"` 适合页头,长错误截断显示,完整内容保留在 `role="status"` 文本中。 +点击「查看参数」核对文件写入路径和内容,再选择「允许」或「拒绝」。示例会显示提交的决定, +点击「重置示例」可以试另一种结果。 -### 子线程兼容面板 + -面向既有 [`threads: Record`](/docs/components/general/message#chatmessage) -投影的只读兼容组件。 +在对话页中,通过 `Chat.approvals` 展示审批卡,将 `chat.canSend` 传给 `Chat`。 +等待审批时仍可编辑草稿,发送暂时禁用。 [工具审批接入](/docs/sdk/tool-approvals) - +### 状态灯 -复用 Message 渲染各分片,可传 `onArtifactDownload` / `onCopy`;不发现 Agent、不查历史、不分页。 -新对话页用 [Chat 的 multiAgent](/docs/components/chat#多-agent-对话),不要塞进审批插槽。 +`phase` 与 `connection` 组合区分已连接、生成中、等待审批、正在停止、已中断、重连中与错误。 -### 欢迎、加载与错误态 + -目录为空、请求失败、agent 未上架都走这两个组件。 +将 `chat.phase`、`chat.connection` 和 `chat.streamError` 分别传给 `phase`、`connection` 和 `error`。 +页头可使用紧凑的 `variant="badge"`,长错误截断显示,完整内容保留在 `role="status"` 文本中。 - +### 子 Agent 执行过程 -聊天欢迎态把 `EmptyState` 与 [Prompts](/docs/components/wake/prompts) 放同一容器整体居中, -输入框保持挂载;`ErrorState` 传 `onRetry` 显示重试按钮。 +将 `useChat().multiAgent` 传给 `Chat`,子 Agent 的任务会在主消息流中显示为可展开的卡片。 +点开卡片后可以查看只读历史、加载更早消息,并重试失败的历史请求。 -## API + -### StatusIndicator +体验页的信息栏也展示子 Agent 的派发记录。按名称展开后,点击任务可打开执行记录弹窗。 +[SubAgentPanel 资源面板示例](/docs/components/general/sub-agent-panel#执行记录弹窗与历史加载) -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `connected` | 是否已建立连接;旧接入 props,新接入改传 `connection` | `boolean` | — | -| `turnRunning` | 当前 Turn 是否在生成;与 `phase` 并存的旧 props | `boolean` | — | -| `phase` | Turn 阶段,优先于由 `turnRunning` 推导 | `"idle" \| "running" \| "requires_action" \| "stopping" \| "failed" \| "interrupted"` | — | -| `connection` | 连接状态;`connecting` / `reconnecting` 提示覆盖暂存错误 | `"disconnected" \| "connecting" \| "connected" \| "reconnecting"` | — | -| `error` | 流错误,与[错误模型](/docs/server-api)同一套 code | `{ code: string; message: string } \| null` | — | -| `variant` | `badge` 在保留状态文本的同时提供紧凑徽标,适合空间受限的页头 | `"default" \| "badge"` | `"default"` | +### 欢迎、加载与错误态 -状态优先级:`phase`(缺省时由 `turnRunning` 推导)决定基础状态;`connecting` / -`reconnecting` 覆盖显示重连提示;其余错误在非重连时优先显示。 +`EmptyState` 展示欢迎、空目录和加载态,`ErrorState` 展示请求失败或 Agent 不可用等状态。 -### ThreadPanel + -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `threads` | 线程 id 到消息数组的映射;空记录整体不渲染 | `Record` | — | -| `onArtifactDownload` | 透传给 Message 的产物下载回调 | `(fileId: string) => void` | — | -| `onCopy` | 透传给 Message 的复制回调 | `(text: string) => void \| Promise` | — | +欢迎态可将 `EmptyState` 和 `Prompts` 放进 `Chat.empty` 的同一容器,输入框保持挂载。 +`ErrorState` 传入 `onRetry` 后显示重试按钮。示例问题的配置见 [Prompts](/docs/components/wake/prompts)。 -### ConfirmDialog +## 接入 -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `title` | 操作标题 | `string` | — | -| `body` | 弹窗正文,通常放真实 plan diff | `string` | — | -| `confirmLabel` | 确认按钮文案 | `string` | `"确认"` | -| `cancelLabel` | 取消按钮文案 | `string` | `"取消"` | -| `danger` | 危险语义的确认按钮 | `boolean` | `true` | -| `busy` | 执行中禁用确认、取消和 Escape | `boolean` | `false` | -| `onConfirm` | 实际执行;成功后由调用方关闭弹窗 | `() => void` | — | -| `onCancel` | 取消回调 | `() => void` | — | +属性类型、必填项和回调见 [组件 API 参考](/skills/kit-components/references/api.md)。 -移动抽屉内发起的确认经 [Layout 的 dialogs 插槽](/docs/components/layout) 渲染,待确认状态归调用方所有。 +### 组合对话页 -### EmptyState +给 `Layout` 的外层容器明确高度,例如 `h-dvh`。将 `SessionSidebar` 放入 `sidebar`,将页头放入 +`header`,再把 `menuToggle` 传给 `AgentHeader.leading`。切换会话后调用 `closeSidebar()` 收起移动抽屉, +用 `Chat` 展示选中会话的消息与输入框。完整的数据绑定见 [三栏对话页示例](/docs/sdk/experience#组件绑定示例)。 -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `title` | 状态标题或开场文案 | `string` | — | -| `hint` | 补充说明 | `string` | — | -| `loading` | 显示低强调进度标记,并用 `role="status"` 表达加载状态 | `boolean` | `false` | +### 会话操作确认 -### ErrorState +归档或删除会话前先向服务端请求计划,在具有 `role="alertdialog"` 语义的 `ConfirmDialog` 中展示返回的 +`diff`。用户显式确认后,携带 `plan_id` 和一次性 `confirm_token` 执行操作。空或畸形令牌返回 +`400 invalid_request`,重放已消费的令牌返回 `428 confirmation_required`。 [会话操作计划](/docs/api/kit/sessions/sessionid/plan/post) -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `message` | 完整错误说明,支持换行 | `string` | — | -| `onRetry` | 由调用方重新加载或恢复 | `() => void` | — | +通过 `Layout.dialogs` 渲染确认弹窗。待确认状态由调用方保存,移动抽屉打开时也能将焦点交给弹窗。 +`SessionList` 的会话标题按钮与行尾菜单触发器并列,具体操作由 `menu` 插槽放进弹层。 [Menu 接入](/docs/components/basic/menu) ## 主题变量(Design Token) @@ -131,8 +129,8 @@ pnpm kit:add prompts | `--kit-accent-fg` / `--kit-danger-fg` | 确认按钮文字 | `#ffffff` | `#ffffff` | | `--kit-warning-fg` | 等待审批状态色 | `#b45309` | `#805917` | | `--kit-fg-muted` | 空闲与停止状态色;说明文字与弹窗正文 | `#5b6478` | `#737373` | -| `--kit-bg-subtle` | badge 与 ThreadPanel 底色;EmptyState 加载标记底 | `#f6f7fb` | `#f7f7f7` | -| `--kit-border` | ThreadPanel 与弹窗描边;取消按钮描边 | `#e3e6ef` | `#e5e5e5` | +| `--kit-bg-subtle` | 状态徽标和空态加载标记底色 | `#f6f7fb` | `#f7f7f7` | +| `--kit-border` | 弹窗与取消按钮描边 | `#e3e6ef` | `#e5e5e5` | | `--kit-border-subtle` | badge 描边;ErrorState 描边;默认主题下等于 `--kit-border` | `#e3e6ef` | `#ececec` | | `--kit-surface` | 弹窗与重试按钮底色 | `#ffffff` | `#ffffff` | | `--kit-overlay` | 弹窗遮罩 | `rgb(0 0 0 / 40%)` | `rgb(23 23 23 / 32%)` | @@ -140,6 +138,6 @@ pnpm kit:add prompts badge 圆点闪动消费 Tailwind 内建 `motion-safe:animate-pulse`,遵循系统减少动画偏好; 焦点环走 `--kit-focus`(默认等于 `--kit-accent`);标题与说明使用 `--kit-text-title` / -`--kit-text-heading` / `--kit-text-label` / `--kit-text-caption` 文字档位,弹窗与 -ThreadPanel 圆角为 `--kit-radius` / `--kit-radius-sm`。更多主题配置见 +`--kit-text-heading` / `--kit-text-label` / `--kit-text-caption` 文字档位。弹窗圆角使用 +`--kit-radius`,按钮圆角使用 `--kit-radius-sm`。更多主题配置见 [组件总览](/docs/components#主题)。 diff --git a/apps/storybook/content/docs/components/express/meta.json b/apps/storybook/content/docs/components/express/meta.json index 38864a5..7b5df79 100644 --- a/apps/storybook/content/docs/components/express/meta.json +++ b/apps/storybook/content/docs/components/express/meta.json @@ -1,4 +1,4 @@ { "title": "表达", - "pages": ["sender", "attachments", "suggestion"] + "pages": ["attachments", "suggestion"] } diff --git a/apps/storybook/content/docs/components/feedback/actions.mdx b/apps/storybook/content/docs/components/feedback/actions.mdx index 425b660..93016d0 100644 --- a/apps/storybook/content/docs/components/feedback/actions.mdx +++ b/apps/storybook/content/docs/components/feedback/actions.mdx @@ -4,7 +4,7 @@ description: 回答下方的操作行:按钮与子菜单、复制与受控赞 --- `Actions` 把回答下方的操作组织成一行:用 `items` 配置按钮与子菜单,或组合 `Actions.Copy` 与 -`Actions.Feedback`。[Message](/docs/components/message) 已为完成的回答内置复制入口, +`Actions.Feedback`。[Message](/docs/components/general/message) 已为完成的回答内置复制入口, 用户消息悬停显示 `iconOnly` 形态。 ```tsx diff --git a/apps/storybook/content/docs/components/feedback/artifact-card.mdx b/apps/storybook/content/docs/components/feedback/artifact-card.mdx new file mode 100644 index 0000000..d6f6d83 --- /dev/null +++ b/apps/storybook/content/docs/components/feedback/artifact-card.mdx @@ -0,0 +1,45 @@ +--- +title: ArtifactCard 产物卡片 +description: 展示 Agent 交付的文件,提供独立的预览与下载入口 +--- + +`ArtifactCard` 用 [FileCard](/docs/components/feedback/file-card) 展示 Agent 交付的文件。 +调用方提供文件名和类型,并通过回调接入预览与下载。 + +```tsx +import { ArtifactCard } from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径): + +```bash +pnpm kit:add artifact-card +``` + +## 何时使用 + +- 在产物列表或详情面板中独立展示交付文件。 +- 在 `Message`、`MessageList` 或 `Chat` 中展示消息产物时,接入消息级 `onArtifactOpen(fileId, contentType?)` 和 + `onArtifactDownload(fileId)`。 + +## 代码演示 + +点击交付文件名称触发预览,独立按钮触发下载。仅提供下载回调时,点击名称触发下载。 +通过演示中的回调提示可区分两种操作。 + + + +## API + +### ArtifactCard + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `filename` | 必填,文件名 | `string` | — | +| `contentType` | MIME 类型,决定图标 | `string` | — | +| `onOpen` | 点击文件名打开预览的回调 | `() => void` | — | +| `onDownload` | 下载回调 | `() => void` | — | + +## 主题变量(Design Token) + +卡片复用 [FileCard 的主题变量](/docs/components/feedback/file-card#主题变量design-token)。 diff --git a/apps/storybook/content/docs/components/feedback/code-highlighter.mdx b/apps/storybook/content/docs/components/feedback/code-highlighter.mdx index 67734b1..6bb7b2d 100644 --- a/apps/storybook/content/docs/components/feedback/code-highlighter.mdx +++ b/apps/storybook/content/docs/components/feedback/code-highlighter.mdx @@ -3,7 +3,7 @@ title: CodeHighlighter 代码高亮 description: 语法高亮代码块:语言、行号、自定义标题与完整复制 --- -`CodeHighlighter` 渲染可复制的语法高亮代码块,[Markdown](/docs/components/message#markdown) 的代码围栏 +`CodeHighlighter` 渲染可复制的语法高亮代码块,[Markdown](/docs/components/feedback/markdown) 的代码围栏 与工具 JSON 输出已自动接入。未知语言按纯文本展示,复制始终是传入的原始代码。 ```tsx @@ -22,7 +22,7 @@ pnpm add lowlight@^3.3.0 ## 何时使用 -- 展示工具输出、错误堆栈等独立代码块:`lang` 高亮加行号加复制;工具 JSON 输出的接线见 [Message](/docs/components/message)。 +- 使用 `lang` 为工具输出和错误堆栈等独立代码块高亮,并提供行号和复制。工具的 JSON 输出见 [ToolCallCard](/docs/components/feedback/tool-call-card)。 - 需要文件名或自定义标题:`header` 传 ReactNode,`false` 隐藏整个工具栏。 - 接 Markdown 正文时无需自行处理围栏:普通围栏由 Markdown 交给本组件,mermaid 围栏由 [Mermaid](/docs/components/feedback/mermaid) 渲染。 diff --git a/apps/storybook/content/docs/components/feedback/markdown.mdx b/apps/storybook/content/docs/components/feedback/markdown.mdx new file mode 100644 index 0000000..83b8811 --- /dev/null +++ b/apps/storybook/content/docs/components/feedback/markdown.mdx @@ -0,0 +1,48 @@ +--- +title: Markdown 富文本 +description: 经过净化的 GFM 正文,支持语法高亮和 Mermaid 图表 +--- + +`Markdown` 将 Markdown 字符串渲染为富文本,支持 GFM 表格、代码围栏和 Mermaid 图表。 +宽表格在自身区域内横向滚动。 + +```tsx +import { Markdown } from "@openagentpack/kit-chat-ui"; +``` + +## 接入 + +copy-in 后将 import 改为项目内路径,并安装渲染依赖: + +```bash +pnpm kit:add markdown +pnpm add react-markdown@^10.1.0 rehype-sanitize@^6.0.0 remark-gfm@^4.0.1 lowlight@^3.3.0 mermaid@^11.12.0 +``` + +`Message`、`Chat` 和 `ToolCallCard` 使用同一套 Markdown 渲染依赖。主题接入见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 在消息或详情面板中渲染 Markdown 文本。 +- 只渲染一段代码或单张图表时,可分别使用 [CodeHighlighter](/docs/components/feedback/code-highlighter) 和 [Mermaid](/docs/components/feedback/mermaid)。 + +## 代码演示 + +代码围栏交给 `CodeHighlighter`,完整的 `mermaid` 围栏交给 `Mermaid`。流式生成中未闭合的 Mermaid 围栏先以源码显示。 + + + +Provider 正文和工具输出属于不可信输入。自定义渲染时须保留 `rehype-sanitize`。 + +## API + +### Markdown + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `children` | 必填,Markdown 原文 | `string` | — | + +## 主题变量(Design Token) + +`--kit-code-keyword`、`--kit-code-string` 和 `--kit-code-number` 随亮暗主题切换。 +色值见 [CodeHighlighter](/docs/components/feedback/code-highlighter#主题变量design-token)。 diff --git a/apps/storybook/content/docs/components/feedback/mermaid.mdx b/apps/storybook/content/docs/components/feedback/mermaid.mdx index 5733561..baf9c14 100644 --- a/apps/storybook/content/docs/components/feedback/mermaid.mdx +++ b/apps/storybook/content/docs/components/feedback/mermaid.mdx @@ -22,7 +22,7 @@ pnpm add mermaid@^11.12.0 lowlight@^3.3.0 ## 何时使用 -- 消息流内的 mermaid 围栏:[Markdown](/docs/components/message#markdown) 把 `mermaid` 代码块路由到本组件, +- 消息流内的 mermaid 围栏:[Markdown](/docs/components/feedback/markdown) 把 `mermaid` 代码块路由到本组件, 业务无需单独接入;Markdown 内追加消息或正文增长时保留用户选择的视图与图表实例。 - 自定义渲染器或独立图表展示:直接传源码字符串,`streaming` 接 Turn 进行中状态。 diff --git a/apps/storybook/content/docs/components/feedback/meta.json b/apps/storybook/content/docs/components/feedback/meta.json index 5881d51..52c6dec 100644 --- a/apps/storybook/content/docs/components/feedback/meta.json +++ b/apps/storybook/content/docs/components/feedback/meta.json @@ -1,4 +1,14 @@ { "title": "反馈", - "pages": ["actions", "tool-approval", "file-card", "code-highlighter", "mermaid"] + "pages": [ + "actions", + "reasoning-block", + "tool-call-card", + "tool-approval", + "file-card", + "artifact-card", + "markdown", + "code-highlighter", + "mermaid" + ] } diff --git a/apps/storybook/content/docs/components/feedback/reasoning-block.mdx b/apps/storybook/content/docs/components/feedback/reasoning-block.mdx new file mode 100644 index 0000000..355d189 --- /dev/null +++ b/apps/storybook/content/docs/components/feedback/reasoning-block.mdx @@ -0,0 +1,75 @@ +--- +title: ReasoningBlock 思考块 +description: 折叠展示思考摘要、完整文本与生命周期状态 +--- + +`ReasoningBlock` 展示单个思考分片,以首个非空行作为摘要,展开后可阅读完整文本。 +内容和状态更新时保留用户的手动开合选择。 + +```tsx +import { ReasoningBlock } from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径): + +```bash +pnpm kit:add reasoning-block +``` + +主题与渲染依赖见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 独立展示思考分片的摘要与全文,通过 `status` 标记流式更新、完成、失败或中断。 +- 在一条消息里展示连续的思考和工具步骤时,交给 [Message](/docs/components/general/message#富内容与执行过程) 组合执行过程。 + +## 代码演示 + +思考块初始收起,状态取自 `reasoning` 分片的 `status`。缺省时摘要显示「思考过程」。 +在 [工具调用演示](/docs/components/feedback/tool-call-card#工具卡三态) 中可以切换思考状态并追加文本。 + +{/* skill-example: kit-components/examples/reasoning.tsx */} + +```tsx +import { ReasoningBlock } from "@openagentpack/kit-chat-ui"; +import { useState } from "react"; + +// 实际对话中,每个推理分片的状态来自 Provider。 +// 下列操作在同一个组件实例上演示各阶段切换。 +export function ReasoningLifecycle() { + const [status, setStatus] = useState<"streaming" | "done" | "failed" | "interrupted">("done"); + return ( +
+
+ 推理阶段操作 + + + + +
+ +
+ ); +} +``` + +{/* /skill-example */} + +## API + +### ReasoningBlock + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `text` | 必填,思考原文,摘要取首个非空行 | `string` | — | +| `status` | 思考分片的当前状态 | `"streaming" \| "done" \| "failed" \| "interrupted"` | — | +| `className` | 追加到根 `details` 的工具类 | `string` | — | +| `contentMaxHeight` | 替换展开内容的限高,`max-h-none` 可取消限高 | `string` | `"max-h-80"` | diff --git a/apps/storybook/content/docs/components/feedback/tool-approval.mdx b/apps/storybook/content/docs/components/feedback/tool-approval.mdx index b4a9e76..6de369f 100644 --- a/apps/storybook/content/docs/components/feedback/tool-approval.mdx +++ b/apps/storybook/content/docs/components/feedback/tool-approval.mdx @@ -33,7 +33,7 @@ copy-in 只复制组件源码,本组件没有额外 npm 依赖。交给 coding ### 基本用法 -允许与拒绝一步直提,不弹确认窗(完整参数已可见);提交中按钮进入 busy,成功后卡片只显示状态。 +点击「查看参数」核对完整参数,再选择「允许」或「拒绝」。提交后可查看本次决定,点击「重置示例」可以再试一次。 diff --git a/apps/storybook/content/docs/components/feedback/tool-call-card.mdx b/apps/storybook/content/docs/components/feedback/tool-call-card.mdx new file mode 100644 index 0000000..4c35863 --- /dev/null +++ b/apps/storybook/content/docs/components/feedback/tool-call-card.mdx @@ -0,0 +1,49 @@ +--- +title: ToolCallCard 工具调用卡 +description: 展示工具调用的运行、完成和失败状态,以及输入参数和执行结果 +--- + +`ToolCallCard` 展示单个工具调用的摘要与状态,展开后可查看输入参数和结果。 +工具执行与审批由业务方接入。 + +```tsx +import { ToolCallCard } from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径): + +```bash +pnpm kit:add tool-call-card +``` + +渲染依赖见 [Markdown 接入](/docs/components/feedback/markdown#接入),主题接入见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 在消息或执行记录里单独展示工具调用。 +- 需要用户查看参数并作出批准或拒绝时,使用 [ToolApprovalCard](/docs/components/feedback/tool-approval)。 + +## 代码演示 + +### 工具卡三态 + +状态取 `running`、`done` 或 `error`。SDK 按调用 ID 匹配后到的输出,更新原来的工具卡。 +JSON 对象及数组使用代码高亮,其余输出按等宽文本展示。缺少参数和结果时显示「暂无调用详情」。 + + + +演示也可切换思考状态并追加内容。摘要随状态更新,同一分片的手动开合选择会保留。 + +## API + +### ToolCallCard + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `part` | 必填,`tool` 类型的 [MessagePart](/docs/components/general/message#messagepart) | `ToolPart` | — | +| `className` | 追加到根 `details` 的工具类 | `string` | — | +| `contentMaxHeight` | 替换展开内容的限高,`max-h-none` 可取消限高 | `string` | `"max-h-80"` | + +## 主题变量(Design Token) + +结构化输出的高亮样式见 [CodeHighlighter](/docs/components/feedback/code-highlighter#主题变量design-token)。 diff --git a/apps/storybook/content/docs/components/general/message.mdx b/apps/storybook/content/docs/components/general/message.mdx index 070a165..e2d83bb 100644 --- a/apps/storybook/content/docs/components/general/message.mdx +++ b/apps/storybook/content/docs/components/general/message.mdx @@ -17,7 +17,7 @@ pnpm kit:add message ``` 该命令复制源码及依赖组件,不自动安装 npm 包;渲染依赖的安装见 -[Markdown 接入](/docs/components/message#markdown),主题接入见[组件总览](/docs/components#主题)。 +[Markdown 接入](/docs/components/feedback/markdown#接入),主题接入见[组件总览](/docs/components#主题)。 以下示例使用 workspace 包导入;copy-in 后改为项目中的组件路径。 ## 何时使用 @@ -68,15 +68,18 @@ pnpm kit:add message 运行中的执行组保持展开,正文到达或消息完成后收起;组内思考与工具步骤默认收起,可手动展开。 +组头显示阶段、总步数与耗时,耗时来自分片时间戳。思考与工具步骤的摘要显示动作和内容预览。 相同分片的内容更新保留用户手动开合。思考状态来自分片自己的 `status`,不由整条消息状态推断。 未知内容保留为可展开的安全文本。 -更多工具状态、Markdown、代码和图表用法见[富内容分片](/docs/components/message)。 +单独接入见 [ReasoningBlock](/docs/components/feedback/reasoning-block)、 +[ToolCallCard](/docs/components/feedback/tool-call-card) 和 [Markdown](/docs/components/feedback/markdown)。 子 Agent 的内嵌卡片通过 `multiAgent` 接入,见 [Chat 多 Agent 对话](/docs/components/chat#多-agent-对话)。 ### 文件与操作回调 -用户上传的 `attachment` 与 Agent 交付的 `artifact` 都复用 [FileCard](/docs/components/feedback/file-card)。 +用户上传的 `attachment` 使用 [FileCard](/docs/components/feedback/file-card),Agent 交付的 +`artifact` 使用 [ArtifactCard](/docs/components/feedback/artifact-card)。 工作区布局将用户附件独立放在正文气泡上方;上传附件只展示文件信息。 @@ -94,7 +97,7 @@ pnpm kit:add message `Message` 只还原消息展示,不执行技能。输入框的选择与提交见 -[Sender](/docs/components/express/sender) 和 [Chat](/docs/components/chat)。 +[Sender](/docs/components/chat/sender) 和 [Chat](/docs/components/chat)。 ## API diff --git a/apps/storybook/content/docs/components/general/session-list.mdx b/apps/storybook/content/docs/components/general/session-list.mdx index e5d5883..dc2e56a 100644 --- a/apps/storybook/content/docs/components/general/session-list.mdx +++ b/apps/storybook/content/docs/components/general/session-list.mdx @@ -25,9 +25,7 @@ pnpm kit:add session-list 与搜索组成的完整目录区用 [SessionSidebar](/docs/components/general/session-sidebar)。 - 会话行需要重命名、归档、删除等操作时,用 `menu` 传入自己的行尾菜单:`menu(session)` 返回的元素在 会话作用域里构造,菜单项 `onClick` 直接取该行 `session` 数据,重命名项改 `editingId` 进入行内编辑。 - 归档与删除是破坏性操作, - 菜单或确认弹窗(AlertDialog)里先展示影响再发起请求,见 - [页面组合与辅助交互](/docs/components/chrome)。 + 归档与删除先请求计划,在确认弹窗展示影响,用户确认后再执行。 [会话操作确认](/docs/components/chrome#会话操作确认) ## 代码演示 diff --git a/apps/storybook/content/docs/components/general/sub-agent-panel.mdx b/apps/storybook/content/docs/components/general/sub-agent-panel.mdx index 8649186..ca55b0d 100644 --- a/apps/storybook/content/docs/components/general/sub-agent-panel.mdx +++ b/apps/storybook/content/docs/components/general/sub-agent-panel.mdx @@ -11,10 +11,11 @@ description: 资源面板中按名归并子 Agent 派发,点击任务行打开 import { SubAgentPanel } from "@openagentpack/kit-chat-ui"; ``` -copy-in 接入(复制后 import 改为项目内路径): +copy-in 接入(复制后 import 改为项目内路径,组合演示使用 `Layout`): ```bash pnpm kit:add sub-agent-panel +pnpm kit:add layout ``` 交给 coding agent 接入时使用 [kit-components Skill](/docs/skill/kit-components);主题与渲染依赖见 @@ -30,17 +31,19 @@ pnpm kit:add sub-agent-panel ## 代码演示 -预览使用本地线程数据;演示面板内可查看源码与接入命令。 +演示通过 `Layout.aside` 展示桌面右栏和手机覆盖层。手机视口先从页头打开「资源」。 +演示使用本地线程数据,面板内可查看源码和接入命令。 ### 基本用法 -research 按展示名分组计数,行内区分运行中 / 已完成 / 出错;勾选清空线程后分区整体不渲染。 +展开 research 查看各次派发及运行中、已完成和出错状态。勾选「清空线程」可查看分区消失后的右栏。 ### 执行记录弹窗与历史加载 -点任务行打开弹窗:research 演示「加载更早消息」翻页(`options.more`),slide-maker 无可回放历史,只显示本次连接收到的消息。 +展开 research,点击任务打开弹窗并加载历史。再点「加载更早消息」可继续翻页。 +slide-maker 展示当前连接收到的消息。 diff --git a/apps/storybook/content/docs/components/index.mdx b/apps/storybook/content/docs/components/index.mdx index b96d300..7b24e12 100644 --- a/apps/storybook/content/docs/components/index.mdx +++ b/apps/storybook/content/docs/components/index.mdx @@ -81,36 +81,57 @@ pnpm kit:add plaza # 广场卡片、分类与用量展示 ## 表达 -表达类组件覆盖输入、附件和快捷指令,调用方负责把交互接到 hooks 与 client。 +表达类组件为对话输入提供附件和快捷指令。 - ## 反馈 -反馈类组件帮助用户阅读和处理 Agent 的回答:复制或评价回答、查看文件、阅读代码和图表。 +反馈类组件帮助用户阅读 Agent 的回答、查看执行步骤和产物,以及评价或复制内容。 操作结果与业务请求由调用方管理。 + + + + + - -## 组合与富内容 +## 布局 - - + + +## 对话 + + + + + + +## 组合示例 + + - - + + + +## 广场与用量 + + + + + + ## 组件清单 @@ -137,11 +158,14 @@ pnpm kit:add plaza # 广场卡片、分类与用量展示 | `SubAgentPanel` | `sub-agent-panel` | 资源面板中的子 Agent 概览与任务执行记录 | | `Layout` | `layout` | 整页布局与移动抽屉;侧栏、页头、弹窗和内容均由插槽注入 | | `Chat` | `chat` | 组合消息与输入;`multiAgent` 支持主子 Agent、只读历史、分页和重试 | -| `ToolCallCard` | `message` | 工具调用卡(running / done / error + input/output) | -| `ArtifactCard` | `message` | 交付文件卡(点击走 server 代理下载,屏蔽预签名 URL 过期) | -| `ReasoningBlock` | `message` | 默认收起,摘要行露出思考预览;支持手动查看 | +| `ToolCallCard` | `tool-call-card` | 工具调用的运行状态、输入参数和执行结果 | +| `ArtifactCard` | `artifact-card` | 交付文件的展示、预览与下载回调 | +| `ReasoningBlock` | `reasoning-block` | 可展开的思考摘要、全文与生命周期状态 | | `Markdown` | `markdown` | GFM 与 sanitize;代码块使用 `CodeHighlighter`,Mermaid 围栏使用 `Mermaid` | -| `PlazaCard` / `CategoryTabs` / `MeterBar` / `ActivityHeatmap` | `plaza` | Agent 发现、分类选择、配额进度与每日活动 | +| `PlazaCard` | `plaza-card` | Agent 卡片与开始体验入口 | +| `CategoryTabs` | `category-tabs` | 精选和分类选择 | +| `MeterBar` | `meter-bar` | 配额使用进度 | +| `ActivityHeatmap` | `activity-heatmap` | 每日对话回合数 | | `StatusIndicator` / `EmptyState` / `ErrorState` / `ConfirmDialog` / `ThreadPanel` | `chrome` | 状态与辅助交互;`chrome` 也包含 `AgentHeader`(`EmptyState` / `ErrorState` 有独立 `states` 条目) | ## 主题 diff --git a/apps/storybook/content/docs/components/layout.mdx b/apps/storybook/content/docs/components/layout/index.mdx similarity index 82% rename from apps/storybook/content/docs/components/layout.mdx rename to apps/storybook/content/docs/components/layout/index.mdx index 470c744..cefef9c 100644 --- a/apps/storybook/content/docs/components/layout.mdx +++ b/apps/storybook/content/docs/components/layout/index.mdx @@ -3,26 +3,46 @@ title: Layout 整页布局 description: 可复用的桌面侧栏、移动抽屉、页头、资源面板与内容区 --- -`Layout` 负责整页结构与响应式交互:桌面常驻侧栏,小于 768px 时改为模态抽屉,右侧可挂资源面板。 -组件不请求数据、不处理认证或路由,也不创建 Session。 +`Layout` 提供桌面侧栏、页头、主内容区与可选的右侧资源面板。小于 768px 时,侧栏切换为模态抽屉, +资源面板切换为全屏覆盖层。路由、身份和会话状态由调用方管理。 ```tsx import { Layout } from "@openagentpack/kit-chat-ui"; ``` -copy-in 接入(组合示例还需 `session-sidebar` / `agent-header`;不自动安装 npm 依赖,需自装 -`@openagentpack/kit-sdk/hooks`、`@radix-ui/react-dialog`,导入共享 `theme.css`,外层给明确高度如 `h-dvh`, -员工端外观经 `data-kit-appearance="workspace"` 启用): +copy-in 接入(复制后 import 改为项目内路径): ```bash pnpm kit:add layout -pnpm kit:add session-sidebar -pnpm kit:add agent-header +pnpm add @radix-ui/react-dialog ``` -交给 coding agent 接入时使用 [kit-components Skill](/docs/skill/kit-components)。下方示例把会话目录、对话内容和 Agent 信息放入三个区域, -并用同一个开关控制桌面右栏和移动端资源面板。主题与渲染依赖见 [组件总览](/docs/components#主题)。 -完整数据接入见 [三栏对话页示例](/docs/sdk/experience#组件绑定示例),路由、身份和会话状态由调用方持有。 +`Layout` 通过 `@openagentpack/kit-sdk/hooks` 判断移动端断点。交给 coding agent 接入时使用 +[kit-components Skill](/docs/skill/kit-components)。主题与渲染依赖见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 广场、用量和聊天页共用一套页头与侧栏。 +- 移动端导航需要抽屉焦点管理、Escape 关闭和软键盘视口适配。 +- Agent 资源需要在桌面停靠右侧,在手机上全屏打开。 + +## 代码演示 + +预览使用本地数据。演示面板内可查看源码与接入命令。 + +### 整页骨架 + +选择「手机」后可从页头打开导航抽屉,体验会话切换、归档或删除确认与用量页入口。 +侧栏开合时正文保留草稿。通过 `dialogs` 传入的确认弹窗在抽屉打开时也能获得焦点。 + + + +## 接入 + +将布局放进高度明确的容器(如 `h-dvh`),通过 `data-kit-appearance="workspace"` 启用工作区外观。 +三栏示例需要 [SessionSidebar](/docs/components/general/session-sidebar)、[AgentHeader](/docs/components/general/agent-header) +和 [Chat](/docs/components/chat),分别填入侧栏、页头和主内容区。`asideOpen` 控制桌面右栏和移动端资源面板的开合。 +会话加载、发送和资源查询见 [三栏对话页示例](/docs/sdk/experience#组件绑定示例)。 {/* skill-example: kit-components/examples/layout.tsx */} @@ -160,22 +180,6 @@ export function WorkspaceLayout(props: WorkspaceLayoutProps) { {/* /skill-example */} -## 何时使用 - -- 员工端整页骨架:广场、用量、聊天页共用同一外壳与断点行为。 -- 需要移动抽屉的模态焦点、Escape 关闭与可视视口适配,不想自写。 -- 右侧资源面板:桌面停靠右列、移动全屏覆盖层,同一插槽两种形态。 - -## 代码演示 - -### 整页骨架 - -桌面常驻侧栏;手机预览经页头入口打开抽屉,可试会话导航、归档 / 删除确认与用量页。 - - - -侧栏开合不重建正文,输入草稿保持;确认弹窗经 `dialogs` 插槽渲染,抽屉打开时也在其焦点范围内。 - ## API ### Layout @@ -217,5 +221,5 @@ render props 控件:`sidebar` 拿到 `closeSidebar()`(选择会话 / 新建 断点 768px 冻结在 `useIsMobile`;面板开合与入场消费 `--kit-duration-base` / `--kit-ease-out` / `--kit-animate-panel-in`;`fitViewport` 运行时注入 `--kit-viewport-height`(缺省 `100dvh`), -[Sender](/docs/components/express/sender) 等组件消费同一变量。宿主可在自己的层级覆盖 +[Sender](/docs/components/chat/sender) 等组件消费同一变量。宿主可在自己的层级覆盖 `--kit-aside-width`。更多主题配置见 [组件总览](/docs/components#主题)。 diff --git a/apps/storybook/content/docs/components/layout/meta.json b/apps/storybook/content/docs/components/layout/meta.json new file mode 100644 index 0000000..9c02e62 --- /dev/null +++ b/apps/storybook/content/docs/components/layout/meta.json @@ -0,0 +1,4 @@ +{ + "title": "布局", + "pages": ["index"] +} diff --git a/apps/storybook/content/docs/components/message.mdx b/apps/storybook/content/docs/components/message.mdx deleted file mode 100644 index e207e45..0000000 --- a/apps/storybook/content/docs/components/message.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: 富内容分片 -description: 思考过程、工具卡、交付文件与 Markdown 在消息中的组合预览 ---- - -一条 Agent 消息由 `MessagePart` 分片组成:思考与工具折成可折叠的执行过程,交付文件渲染为 -文件卡,正文按 Markdown 排版。分片模型与整条消息的接口见 -[Message](/docs/components/general/message#chatmessage)。 - -```tsx -import { Message } from "@openagentpack/kit-chat-ui"; -``` - -使用 copy-in 接入时执行: - -```bash -pnpm kit:add message -pnpm add react-markdown@^10.1.0 rehype-sanitize@^6.0.0 remark-gfm@^4.0.1 lowlight@^3.3.0 mermaid@^11.12.0 -``` - -复制源码不自动安装 npm 包;`markdown` 与 `chat` 共用这条 Markdown 依赖链。主题接入见 -[组件总览](/docs/components#主题)。 - -## 何时使用 - -- 单独复用工具卡、思考块或 Markdown,或确认执行过程的折叠、耗时等展示合同。 -- 需要用户确认的工具走 [ToolApprovalCard](/docs/components/feedback/tool-approval), - 交付文件的展示与下载见 [FileCard](/docs/components/feedback/file-card), - 完成回答的复制与赞踩见 [Actions](/docs/components/feedback/actions)。 - -## 代码演示 - -预览使用本地数据;演示面板内可查看源码与接入命令。 - -### 组合消息 - - - -预览使用 `variant="workspace"` 阅读布局,组件默认值仍是 `"default"`,差异见 -[Message 工作区样式](/docs/components/general/message#工作区样式)。 - -- 连续的思考与工具分片折成「执行过程」,正文、文件与状态打断分组;运行中保持展开, - 正文到达或消息完成后自动收起,之后保留手动开合。 -- 组头显示阶段、总步数与耗时;耗时来自分片时间戳,缺时间戳的历史数据不显示、不估算。 -- 思考与工具步骤默认收起,摘要行为动词 + 内容预览(如「读取文件 data.csv」),可展开 - 查看思考原文、输入参数与执行结果。 - -### 工具卡三态 - - - -`tool.status` 取 `running / done / error`,core 按 call_id 匹配、后到的 output 更新原卡片; -输出为 JSON 对象/数组时用代码高亮,其余保留等宽原文,未提供参数和结果时显示「暂无调用详情」。 -演示同时可切换思考状态并追加内容:摘要行随状态变化,手动展开在累计快照间保留。 - -### 思考生命周期 - -状态来自 `reasoning` 分片自己的 `status`,不由整条消息推断;未提供 `status` 时初始收起且 -不标记完成。单独复用时: - -{/* skill-example: kit-components/examples/reasoning.tsx */} - -```tsx -import { ReasoningBlock } from "@openagentpack/kit-chat-ui"; -import { useState } from "react"; - -// 实际对话中,每个推理分片的状态来自 Provider。 -// 下列操作在同一个组件实例上演示各阶段切换。 -export function ReasoningLifecycle() { - const [status, setStatus] = useState<"streaming" | "done" | "failed" | "interrupted">("done"); - return ( -
-
- 推理阶段操作 - - - - -
- -
- ); -} -``` - -{/* /skill-example */} - -### Markdown - -```bash -pnpm kit:add markdown -``` - - - -`children` 为 Markdown 原文,代码围栏交给 -[CodeHighlighter](/docs/components/feedback/code-highlighter)、`mermaid` 围栏交给 -[Mermaid](/docs/components/feedback/mermaid),两者也可独立接入。**rehype-sanitize 是硬要求**: -事件正文来自 Provider 与工具输出,属于不可信输入。宽表格在区域内部横向滚动,不会撑宽页面。 - -## API - -### ReasoningBlock - -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `text` | 必填,思考原文;摘要行取首个非空行 | `string` | — | -| `status` | 思考状态;缺省不标记完成 | `"streaming" \| "done" \| "failed" \| "interrupted"` | — | -| `className` | 追加到根 `details` 的工具类 | `string` | — | -| `contentMaxHeight` | 展开内容限高工具类,整体替换默认值;`max-h-none` 取消限高 | `string` | `"max-h-80"` | - -### ToolCallCard - -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `part` | 必填,工具分片;字段见 [MessagePart](/docs/components/general/message#messagepart) | `ToolPart` | — | -| `className` | 同 ReasoningBlock | `string` | — | -| `contentMaxHeight` | 同 ReasoningBlock | `string` | `"max-h-80"` | - -### Markdown - -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `children` | Markdown 原文 | `string` | — | - -### ArtifactCard - -| 属性 | 说明 | 类型 | 默认值 | -| --- | --- | --- | --- | -| `filename` | 必填,文件名 | `string` | — | -| `contentType` | MIME 类型,决定图标 | `string` | — | -| `onOpen` | 点击文件名打开预览 | `() => void` | — | -| `onDownload` | 下载 | `() => void` | — | - -在 Message / MessageList / Chat 中使用时,改用消息级 `onArtifactOpen(fileId, contentType?)` 与 -`onArtifactDownload(fileId)` 接线;卡片展示复用 [FileCard](/docs/components/feedback/file-card)。 - -## 主题变量(Design Token) - -本页组件复用各内容组件的 token:气泡与正文见 [Message](/docs/components/general/message)、 -代码高亮三色见 [CodeHighlighter](/docs/components/feedback/code-highlighter)、文件卡见 -[FileCard](/docs/components/feedback/file-card)。其中 `--kit-code-keyword` / `--kit-code-string` / -`--kit-code-number` 只随亮暗主题变化,不随工作区外观变灰。 diff --git a/apps/storybook/content/docs/components/meta.json b/apps/storybook/content/docs/components/meta.json index 1892771..842630d 100644 --- a/apps/storybook/content/docs/components/meta.json +++ b/apps/storybook/content/docs/components/meta.json @@ -9,8 +9,7 @@ "feedback", "layout", "chat", - "message", - "chrome", - "plaza" + "plaza", + "chrome" ] } diff --git a/apps/storybook/content/docs/components/plaza.mdx b/apps/storybook/content/docs/components/plaza.mdx deleted file mode 100644 index 7091ced..0000000 --- a/apps/storybook/content/docs/components/plaza.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: 广场与用量 -description: PlazaCard、CategoryTabs、MeterBar 和 ActivityHeatmap 的 Props 与调用方责任 ---- - -这四个组件用于体验页的 Agent 广场、个人用量页与管理端配额视图。 -组件只展示调用方提供的数据,不读取接口、不决定跳转或执行配额审批。 - -```bash -pnpm kit:add plaza -``` - -## PlazaCard - -展示一个 `PlazaEntry` 的图标、名称、描述、分类、精选与「我的」徽标,以及近 30 天 Turn 数。 -图标支持图片地址与 emoji,点击「开始体验」只调用 `onOpen(entry.slug)`。 - -卡片将图标、标题与分类置于顶部,说明最多展示两行,用量和独立操作按钮置于底部。 -长标题省略显示,标题和说明通过 `title` 保留完整内容;窄屏下徽标和底部操作可以换行。 -卡片不是嵌套按钮,键盘聚焦“开始体验”时显示焦点轮廓。 - -| 属性 | 类型 | 说明 | -| --- | --- | --- | -| `entry` | `PlazaEntry` | 必填,来自 `@openagentpack/kit-sdk/protocol`,包括 Agent 展示信息和 stats | -| `onOpen` | `(slug: string) => void` | 必填,由调用方更新路由、选中 Agent 与会话状态 | - -## CategoryTabs - -受控分类选择器,在调用方传入的分类前追加 `featured`(精选)入口。 -当前只展示分类名称,`count` 暂不展示。 - -分类条使用 `tablist` / `tab` 语义,当前项是 Tab 键的进入位置。左右方向键以及 Home / End -移动焦点并触发 `onChange`,Tab 离开分类条;分类过多时只在分类条内横滚,不拖动整个页面。 - -| 属性 | 类型 | 说明 | -| --- | --- | --- | -| `categories` | `{ id: PlazaCategory; name: string; count: number }[]` | 必填,分类列表 | -| `active` | `PlazaTabId` | 必填,分类枚举或 `featured` | -| `onChange` | `(next: PlazaTabId) => void` | 必填,由调用方筛选数据或重新查询 | - -## MeterBar - -用量进度条。填充比例限制在 0–100%;`unlimited=true` 或 `max <= 0` 时没有填充。 -限额计算、月度加油包叠加与发送拦截由服务端和调用方负责,组件不决定是否允许发送。 - -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| `value` | `number` | 必填 | 当前已用量 | -| `max` | `number` | 必填 | 生效上限,调用方计入当月加油包 | -| `unlimited` | `boolean` | `false` | 不限量时只显示轨道 | -| `className` | `string` | `""` | 附加 Tailwind 类 | - -## ActivityHeatmap - -| 属性 | 类型 | 说明 | -| --- | --- | --- | -| `days` | `{ day: string; turns: number }[]` | 必填,按展示顺序排列,day 必须唯一 | - -按数据中的最大 Turn 数分出三档活跃度,零值显示为空闲色。 -组件不排序、不补齐缺失日期;默认 `useQuota()` 返回的数据已按 UTC 日键排序并补齐近 30 天。 - -## 组合与数据来源 - -体验页将广场搜索、分类与内容卡片放在同一响应式页面中,热门、我的 Agent 与主列表保持各自 -分区。加载与无结果区域复用 [EmptyState](/docs/components/chrome),请求失败复用 -`ErrorState`;这套卡片、按钮与焦点样式也用于个人用量和成员登录页,亮暗配色由页面主题控制。 - -广场数据用 `usePlaza()`,配额与每日活动用 `useQuota()`。这些默认 Hooks 在 -`KitProvider` 内运行,接入说明见 [广场与配额 Hooks](/docs/sdk/discovery-usage)。 -可编译的组合示例见 [kit-components Skill](/docs/skill/kit-components)。 diff --git a/apps/storybook/content/docs/components/plaza/activity-heatmap.mdx b/apps/storybook/content/docs/components/plaza/activity-heatmap.mdx new file mode 100644 index 0000000..29f5c4e --- /dev/null +++ b/apps/storybook/content/docs/components/plaza/activity-heatmap.mdx @@ -0,0 +1,53 @@ +--- +title: ActivityHeatmap 活跃热力图 +description: 用日期格和色阶展示每日对话回合数 +--- + +`ActivityHeatmap` 把每日回合数按每列七格排列。同一份数据中,回合数越多的日期颜色越深。 + +```tsx +import { ActivityHeatmap } from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径) + +```bash +pnpm kit:add activity-heatmap +``` + +主题与渲染依赖见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 在个人用量页展示近期哪些日期有对话活动,以及相对活跃程度。 +- 同时展示额度消耗比例时,可搭配 `MeterBar`。 [MeterBar 用量条](/docs/components/plaza/meter-bar) + +## 代码演示 + +将鼠标悬停在格子上查看日期和回合数。勾选「全部日期为 0 回合」可查看零用量色阶。 + + + +## 接入 + +`useQuota().quota.daily` 已按 UTC 日期从早到晚提供近 30 天的记录,可直接传给 `days`。 +使用其他数据源时,由调用方按展示顺序排列日期,并为缺失的日期补一条 `turns: 0` 的记录。 [广场与配额 Hooks](/docs/sdk/discovery-usage) + +## API + +### ActivityHeatmap + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `days` | 必填,`day` 为唯一的日期键,`turns` 为当日回合数 | `{ day: string; turns: number }[]` | — | + +组件按输入顺序渲染。色阶以本组数据的最大回合数为基准,正数分三档,0 回合显示底色。空数组显示「暂无活跃记录」的无障碍标签。 + +## 主题变量(Design Token) + +| Token | 用途 | 默认主题 | 工作区主题 | +| --- | --- | --- | --- | +| `--kit-border` | 0 回合的格子底色 | `#e3e6ef` | `#e5e5e5` | +| `--kit-heat` | 活跃格子,按档位使用 30%、60% 或 100% 的不透明度 | `#2563eb` | `#2563eb` | + +格子圆角使用 `--kit-radius-xs`。 diff --git a/apps/storybook/content/docs/components/plaza/category-tabs.mdx b/apps/storybook/content/docs/components/plaza/category-tabs.mdx new file mode 100644 index 0000000..c4b0c19 --- /dev/null +++ b/apps/storybook/content/docs/components/plaza/category-tabs.mdx @@ -0,0 +1,58 @@ +--- +title: CategoryTabs 广场分类 +description: 受控的广场分类标签,支持精选、键盘切换和窄屏横向滚动 +--- + +`CategoryTabs` 让用户在「精选」和各个 Agent 分类间切换。调用方控制当前选中项,并根据回调更新列表。 + +```tsx +import { CategoryTabs, type PlazaTabId } from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径) + +```bash +pnpm kit:add category-tabs +``` + +主题与渲染依赖见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 在 Agent 广场用一行标签切换精选、写作、编程等分类。 +- 将分类和搜索条件一起保存在页面状态里,按选中项展示相应的 Agent 列表。 [PlazaCard 智能体卡片](/docs/components/plaza/plaza-card) + +## 代码演示 + +点击分类或聚焦后按左右方向键切换,观察下方列表。按 Home 跳到首项,按 End 跳到末项。 + + + +## 接入 + +传入 `usePlaza().view.categories`,用 `active` 保存选中项。选择普通分类时可将分类 ID 传给 `usePlaza({ category })`。 +选择 `featured` 时省略查询的 `category`,按结果的 `featured` 列表选择卡片。 [广场与配额 Hooks](/docs/sdk/discovery-usage#广场与配额查询) + +标签条采用 `tablist` 和 `tab` 语义。Tab 键进入当前选中项或离开分类条。窄屏时分类条可横向滚动。 + +## API + +### CategoryTabs + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `categories` | 必填,分类标签。组件在列表首位添加「精选」,分类标签显示 `name` | `{ id: PlazaCategory; name: string; count: number }[]` | — | +| `active` | 必填,当前选中项 | `PlazaTabId` | — | +| `onChange` | 必填,用户切换分类时回传新的选中项 | `(next: PlazaTabId) => void` | — | + +`PlazaTabId` 为 `PlazaCategory | "featured"`。`PlazaCategory` 从 `@openagentpack/kit-sdk/protocol` 导入。 + +## 主题变量(Design Token) + +| Token | 用途 | 默认主题 | 工作区主题 | +| --- | --- | --- | --- | +| `--kit-nav-active` | 选中标签底色 | `#eef0ff` | `#ececec` | +| `--kit-bg-subtle` | 标签悬停底色 | `#f6f7fb` | `#f7f7f7` | +| `--kit-focus` | 键盘焦点环 | `#4f46e5` | `#737373` | + +标签圆角使用 `--kit-radius-sm`。 diff --git a/apps/storybook/content/docs/components/plaza/meta.json b/apps/storybook/content/docs/components/plaza/meta.json new file mode 100644 index 0000000..43196ad --- /dev/null +++ b/apps/storybook/content/docs/components/plaza/meta.json @@ -0,0 +1,4 @@ +{ + "title": "广场与用量", + "pages": ["plaza-card", "category-tabs", "meter-bar", "activity-heatmap"] +} diff --git a/apps/storybook/content/docs/components/plaza/meter-bar.mdx b/apps/storybook/content/docs/components/plaza/meter-bar.mdx new file mode 100644 index 0000000..0a3080e --- /dev/null +++ b/apps/storybook/content/docs/components/plaza/meter-bar.mdx @@ -0,0 +1,55 @@ +--- +title: MeterBar 用量条 +description: 将当前用量和生效上限呈现为进度条,支持不限量状态 +--- + +`MeterBar` 将已用量和生效上限显示为进度条。填充比例限制在 0% 到 100%,不限量时显示轨道。 + +```tsx +import { MeterBar } from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径) + +```bash +pnpm kit:add meter-bar +``` + +主题与渲染依赖见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 在个人用量或管理端配额卡片中展示已用量占上限的比例。 +- 同时展示逐日用量时,在进度条旁使用 `ActivityHeatmap`。 [ActivityHeatmap 活跃热力图](/docs/components/plaza/activity-heatmap) + +## 代码演示 + +拖动滑块调整已用额度。勾选「不限量」可查看无固定上限时的轨道。 + + + +## 接入 + +传入单位一致的 `value` 和 `max`。使用 `useQuota()` 时,将 `quota.unlimited` 传给 `unlimited`。 +有上限时,用 `quota.limit` 加上当月所有 `packs` 的 `credits` 得到 `max`。 +Kit 本地成员限额可直接使用限额查询返回的生效上限。页面负责展示具体数值和单位。 [广场与配额 Hooks](/docs/sdk/discovery-usage#配额与显式申请) + +## API + +### MeterBar + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `value` | 必填,当前已用量 | `number` | — | +| `max` | 必填,生效上限。为 0 或负数时显示空轨道 | `number` | — | +| `unlimited` | 为 true 时显示不限量轨道 | `boolean` | `false` | +| `className` | 追加到轨道的 Tailwind 工具类,可调整高度 | `string` | `""` | + +## 主题变量(Design Token) + +| Token | 用途 | 默认主题 | 工作区主题 | +| --- | --- | --- | --- | +| `--kit-bg-subtle` | 轨道底色 | `#f6f7fb` | `#f7f7f7` | +| `--kit-accent` | 已用额度的填充色 | `#4f46e5` | `#171717` | + +填充宽度的过渡遵循 `prefers-reduced-motion`。 diff --git a/apps/storybook/content/docs/components/plaza/plaza-card.mdx b/apps/storybook/content/docs/components/plaza/plaza-card.mdx new file mode 100644 index 0000000..74588a7 --- /dev/null +++ b/apps/storybook/content/docs/components/plaza/plaza-card.mdx @@ -0,0 +1,68 @@ +--- +title: PlazaCard 智能体卡片 +description: 展示 Agent 的分类、能力与近期回合数,提供开始体验入口 +--- + +`PlazaCard` 展示一个 Agent 的图标、名称、分类、描述、能力和近期回合数。点击「开始体验」时,组件将 Agent 的 `slug` 传给调用方。 + +```tsx +import { PlazaCard } from "@openagentpack/kit-chat-ui"; +``` + +copy-in 接入(复制后 import 改为项目内路径) + +```bash +pnpm kit:add plaza-card +``` + +主题与渲染依赖见 [组件总览](/docs/components#主题)。 + +## 何时使用 + +- 在 Agent 广场的精选、热门或搜索结果中展示条目,并提供进入对话的入口。 +- 同时展示多个分类时,用 `CategoryTabs` 切换列表。 [CategoryTabs 广场分类](/docs/components/plaza/category-tabs) + +## 代码演示 + +点击「开始体验」,观察卡片回传的 Agent 标识。演示使用本地条目。 + + + +## 接入 + +将 `usePlaza().view.agents` 中的条目传给 `entry`,用 `onOpen` 切换当前 Agent 和会话。 +描述缺省时使用 Agent 的开场白。提供 `suggested_prompts` 时,卡片展示第一条示例问题。 +长标题和描述截断显示,鼠标悬停可查看完整文字。 [广场与配额 Hooks](/docs/sdk/discovery-usage#广场与配额查询) + +## API + +### PlazaCard + +| 属性 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| `entry` | 必填,含展示信息和用量统计的 Agent 条目 | [`PlazaEntry`](#plazaentry) | — | +| `onOpen` | 必填,点击「开始体验」时回传 Agent 标识 | `(slug: string) => void` | — | + +### PlazaEntry + +从 `@openagentpack/kit-sdk/protocol` 导入。在 `AgentSummary` 基础上增加 `stats`,用于展示近 30 天回合数、当前用户是否用过和最近使用日期。 [AgentSummary](/docs/components/general/agent-header#agentsummary) + +| 属性 | 说明 | 类型 | +| --- | --- | --- | +| `category` | 卡片分类 | `PlazaCategory` | +| `featured` | 为 true 时显示「精选」 | `boolean` | +| `capabilities` | 显示启用的能力,如流式输出、文件上传和产物 | `AgentCapabilities` | +| `stats.turns_30d` | 近 30 天的全局回合数 | `number` | +| `stats.mine` | 当前用户用过时显示「我的」 | `boolean` | +| `stats.last_used_at` | 可选,最近使用时间,按本地日历显示相对日期 | `string` | + +## 主题变量(Design Token) + +| Token | 用途 | 默认主题 | 工作区主题 | +| --- | --- | --- | --- | +| `--kit-surface` | 卡片底色 | `#ffffff` | `#ffffff` | +| `--kit-border` | 卡片边框 | `#e3e6ef` | `#e5e5e5` | +| `--kit-bg-subtle` | 分类标签和示例问题底色 | `#f6f7fb` | `#f7f7f7` | +| `--kit-accent` / `--kit-accent-fg` | 行动按钮的底色和文字 | `#4f46e5` / `#ffffff` | `#171717` / `#ffffff` | + +卡片使用 `--kit-radius`,行动按钮的焦点环使用 `--kit-focus`。 diff --git a/apps/storybook/content/docs/concepts.mdx b/apps/storybook/content/docs/concepts.mdx index d0db8eb..8e9804e 100644 --- a/apps/storybook/content/docs/concepts.mdx +++ b/apps/storybook/content/docs/concepts.mdx @@ -34,7 +34,7 @@ Kit 提供管理端和体验页:管理员配置智能体、准备运行资源 失败时保留会话供重试。已保存的累计用量继续保留。 桌面和 H5 使用同一套对话流程。操作示例见[成员对话](/docs/local-demo/#从广场完成第一轮对话), -界面组合见 [Chat 与 Sender](/docs/components/chat)。 +界面组件见 [Chat 对话区](/docs/components/chat) 和 [Sender 输入框](/docs/components/chat/sender)。 ## 工具审批与子 Agent diff --git a/apps/storybook/content/docs/sdk/client.mdx b/apps/storybook/content/docs/sdk/client.mdx index b5ac6d7..f71efda 100644 --- a/apps/storybook/content/docs/sdk/client.mdx +++ b/apps/storybook/content/docs/sdk/client.mdx @@ -274,7 +274,7 @@ export function KitRoot({ client, children }: { client: KitClient; children: Rea 见[组件交互与后端调用](/docs/sdk/experience#组件绑定示例)。 文件选择、粘贴、移除和上传状态由调用方组合 -[Sender 与 Attachments](/docs/components/express/sender) 管理。 +[Sender 与 Attachments](/docs/components/chat/sender) 管理。 使用 `await client.downloadFile(fileId, { sessionId })` 下载 Artifact,再由宿主保存 Response 中的字节;本人上传文件可以省略 sessionId。服务端检查文件归属,只允许挂载本人上传。 旧数据库升级时,会从历史会话挂载索引补齐唯一原身份的文件归属;存在跨身份歧义或没有 diff --git a/apps/storybook/content/docs/sdk/discovery-usage.mdx b/apps/storybook/content/docs/sdk/discovery-usage.mdx index 7c62b40..4ebe258 100644 --- a/apps/storybook/content/docs/sdk/discovery-usage.mdx +++ b/apps/storybook/content/docs/sdk/discovery-usage.mdx @@ -176,7 +176,7 @@ export function DiscoveryAndUsage() { {/* /skill-example */} -展示组件见 [广场与用量](/docs/components/plaza)。Client 也可独立于 React 调用 +展示组件见 [广场与用量](/docs/components#广场与用量)。Client 也可独立于 React 调用 `plaza()`、`quota()`、`quotaRequests()` 与 `createQuotaRequest()`。 ## API diff --git a/apps/storybook/e2e/chat-previews.spec.ts b/apps/storybook/e2e/chat-previews.spec.ts index 76029b0..242965c 100644 --- a/apps/storybook/e2e/chat-previews.spec.ts +++ b/apps/storybook/e2e/chat-previews.spec.ts @@ -77,7 +77,7 @@ test("思考状态预览:追加内容保留手动开合,四种状态可真 // 子 Agent 以流内嵌卡呈现;展开即拉取消息,失败可在卡内重试,主输入草稿始终保留。 test("Multi-Agent 预览:卡片展开加载与失败重试保留消息,主输入草稿保留", async ({ page }) => { await page.goto("/previews/multi-agent/"); - const input = page.getByRole("textbox", { name: "消息输入", exact: true }); + const input = page.getByLabel("消息输入", { exact: true }); await input.fill("切换协作 Agent 后继续发送的草稿"); const research = page.locator('details[aria-label="子 Agent 资料研究员"]'); await expect(research).toContainText("整理资料并交叉验证来源"); diff --git a/apps/storybook/e2e/message-previews.spec.ts b/apps/storybook/e2e/message-previews.spec.ts index eb2824b..422e22f 100644 --- a/apps/storybook/e2e/message-previews.spec.ts +++ b/apps/storybook/e2e/message-previews.spec.ts @@ -64,7 +64,11 @@ test("Message 内容演示:展开执行详情,区分文件预览、下载和 await expect(page.getByRole("status").filter({ hasText: "打开文件:file-report(text/markdown)" })).toBeVisible(); await page.getByRole("button", { name: "下载 weekly-report.md", exact: true }).click(); await expect(page.getByRole("status").filter({ hasText: "下载文件:file-report" })).toBeVisible(); - await page.getByRole("button", { name: "复制", exact: true }).click(); + await page + .getByRole("group", { name: "消息操作", exact: true }) + .getByRole("button", { name: "复制", exact: true }) + .filter({ hasText: "复制" }) + .click(); await expect(page.getByRole("status").filter({ hasText: "复制原文:" })).toHaveText( "复制原文:周报已生成。\n\n**要点**:本周会话量增长 12%。", ); diff --git a/apps/storybook/e2e/tool-approval-preview.spec.ts b/apps/storybook/e2e/tool-approval-preview.spec.ts new file mode 100644 index 0000000..135e5b1 --- /dev/null +++ b/apps/storybook/e2e/tool-approval-preview.spec.ts @@ -0,0 +1,22 @@ +import { expect, test } from "./fixtures.ts"; + +test("最佳实践的工具审批演示:查看完整参数并分别提交允许和拒绝", async ({ page }) => { + await page.goto("/docs/components/chrome/"); + await expect(page.getByRole("heading", { name: /^工具审批/, level: 3 })).toBeVisible(); + const iframe = page.locator('iframe[src="/previews/tool-approval/"]'); + await page.locator(".kit-preview", { has: iframe }).getByRole("button", { name: "手机", exact: true }).click(); + const preview = iframe.contentFrame(); + const approval = preview.getByRole("region", { name: "工具审批 write_file", exact: true }); + const reset = preview.getByRole("button", { name: "重置示例", exact: true }); + await approval.getByText("查看参数", { exact: true }).click(); + await expect(approval.locator("pre").filter({ hasText: "/mnt/session/report.md" })).toBeVisible(); + + for (const action of ["允许", "拒绝"]) { + await approval.getByRole("button", { name: action, exact: true }).click(); + const outcome = preview.getByText(`已提交「${action}」`, { exact: true }); + await expect(outcome).toBeVisible(); + await expect(approval.getByRole("button", { name: /^(允许|拒绝)$/ })).toHaveCount(0); + await reset.click(); + await expect(outcome).toHaveCount(0); + } +}); diff --git a/apps/storybook/lib/showcase-names.ts b/apps/storybook/lib/showcase-names.ts index f6cdec3..2ce138b 100644 --- a/apps/storybook/lib/showcase-names.ts +++ b/apps/storybook/lib/showcase-names.ts @@ -58,9 +58,13 @@ export const SHOWCASE_NAMES = [ "markdown", "layout", "chrome", + "resource-panel", "status", - "threads", "states", + "plaza-card", + "category-tabs", + "meter-bar", + "activity-heatmap", "sse-stream", "sse-parser", "kit-stream", diff --git a/assets/skills/kit-chat-provider/references/api.md b/assets/skills/kit-chat-provider/references/api.md index bc25f75..e0bc244 100644 --- a/assets/skills/kit-chat-provider/references/api.md +++ b/assets/skills/kit-chat-provider/references/api.md @@ -810,7 +810,7 @@ export type SendMessageRequest = { text: string; skills?: string[] | undefined; | `attachments` | 否 | `{ file_id: string; filename?: string \| undefined; mount_path?: string \| undefined; size?: number \| undefined; }[] \| undefined` | | `client_message_id` | 否 | `string \| undefined` | - + ## SendMessageResponse @@ -1138,7 +1138,7 @@ export type ClientOperations = { agent?: BackendOperation<[slug: string, signal? | `auth.me` | 否 | `any` | | `auth.logout` | 否 | `any` | - + ## ClientOperation @@ -1155,7 +1155,7 @@ export type ClientOperation = "agent" | "sendMessage" | "interrupt" | "toolAppro ``` - + ## ExplicitKitClientOptions @@ -1177,7 +1177,7 @@ import type { ExplicitKitClientOptions } from "@openagentpack/kit-sdk/providers/ | `operations` | 是 | `ClientOperations` | | `chatProvider` | 否 | `ChatProvider \| undefined` | - + ## createMemberSessionStorage @@ -1194,7 +1194,7 @@ export function createMemberSessionStorage(baseUrl: string, getStorage: () => { ``` - + ## normalizeMemberApiBaseUrl @@ -1211,7 +1211,7 @@ export function normalizeMemberApiBaseUrl(value: string, origin: string): string ``` - + ## streamProtocolFrames diff --git a/assets/skills/kit-components/references/api.md b/assets/skills/kit-components/references/api.md index c40083d..39b8265 100644 --- a/assets/skills/kit-components/references/api.md +++ b/assets/skills/kit-components/references/api.md @@ -82,7 +82,7 @@ export function Actions({ items, onClick, children, variant, className, "aria-la | `className` | 否 | `string \| undefined` | | `aria-label` | 否 | `string \| undefined` | - + ## ActionsCopy @@ -111,7 +111,7 @@ export function ActionsCopy({ text, onCopy, disabled, label, iconOnly, variant, | `variant` | 否 | `ActionsVariant \| undefined` | | `className` | 否 | `string \| undefined` | - + ## ActionsFeedback @@ -138,7 +138,7 @@ export function ActionsFeedback({ value, onChange, disabled, variant, className, | `variant` | 否 | `ActionsVariant \| undefined` | | `className` | 否 | `string \| undefined` | - + ## Actions.Copy @@ -167,7 +167,7 @@ export function ActionsFeedback({ value, onChange, disabled, variant, className, | `variant` | 否 | `ActionsVariant \| undefined` | | `className` | 否 | `string \| undefined` | - + ## Actions.Feedback @@ -194,7 +194,7 @@ export function ActionsFeedback({ value, onChange, disabled, variant, className, | `variant` | 否 | `ActionsVariant \| undefined` | | `className` | 否 | `string \| undefined` | - + ## AttachmentFileCard @@ -289,7 +289,7 @@ export function Attachments(props: AttachmentsProps & RefAttributes + ## Chat @@ -325,7 +325,7 @@ export function Layout({ sidebar, header, mobileTitle, sidebarLabel, dialogs, as 从 `@openagentpack/kit-chat-ui` 导入 `Chat`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/chat/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/chat.mdx`。 +说明来自 `apps/storybook/content/docs/components/chat/index.mdx`。 [可编译示例](../examples/chat-runtime.tsx) - 默认 variant=default、turnRunning=false、canSend=true。员工端布局需显式使用 workspace。 @@ -364,7 +364,7 @@ export function Chat({ messages, variant, turnRunning, sending, canSend, compose | `anchorRail` | 否 | `boolean \| undefined` | | `virtualize` | 否 | `boolean \| undefined` | - + ## AgentHeader @@ -422,7 +422,7 @@ export function isIconImageSource(icon: string | undefined): boolean; 从 `@openagentpack/kit-chat-ui` 导入 `ConfirmDialog`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/confirm-dialog/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/chrome.mdx`。 +说明来自 `packages/chat-ui/src/components/confirm-dialog/README.md`。 [可编译示例](../examples/general.tsx) - danger 默认 true,由调用方按条件挂载。 @@ -444,7 +444,7 @@ export function ConfirmDialog({ title, body, confirmLabel, cancelLabel, danger, | `onConfirm` | 是 | `() => void` | | `onCancel` | 是 | `() => void` | - + ## EmptyState @@ -452,7 +452,7 @@ export function ConfirmDialog({ title, body, confirmLabel, cancelLabel, danger, 从 `@openagentpack/kit-chat-ui` 导入 `EmptyState`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/empty-state/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/chrome.mdx`。 +说明来自 `packages/chat-ui/src/components/empty-state/README.md`。 [可编译示例](../examples/general.tsx) @@ -466,7 +466,7 @@ export function EmptyState({ title, hint, loading, }: { title: string; hint?: st | `hint` | 否 | `string \| undefined` | | `loading` | 否 | `boolean \| undefined` | - + ## ErrorState @@ -474,7 +474,7 @@ export function EmptyState({ title, hint, loading, }: { title: string; hint?: st 从 `@openagentpack/kit-chat-ui` 导入 `ErrorState`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/error-state/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/chrome.mdx`。 +说明来自 `packages/chat-ui/src/components/error-state/README.md`。 [可编译示例](../examples/general.tsx) - 提供 onRetry 时才显示重试按钮,由调用方定义重试行为。 @@ -488,7 +488,7 @@ export function ErrorState({ message, onRetry }: { message: string; onRetry?: () | `message` | 是 | `string` | | `onRetry` | 否 | `(() => void) \| undefined` | - + ## SessionSidebar @@ -543,7 +543,7 @@ export function SessionSidebar({ groups, recent, loading, error, onReload, activ 从 `@openagentpack/kit-chat-ui` 导入 `StatusIndicator`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/status-indicator/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/chrome.mdx`。 +说明来自 `packages/chat-ui/src/components/status-indicator/README.md`。 [可编译示例](../examples/general.tsx) - 兼容用的必填 Props 为 connected 和 turnRunning。 @@ -562,7 +562,7 @@ export function StatusIndicator({ connected, turnRunning, phase, connection, err | `error` | 否 | `{ code: string; message: string; } \| null \| undefined` | | `variant` | 否 | `"default" \| "badge" \| undefined` | - + ## SubAgentPanel @@ -585,7 +585,7 @@ export function SubAgentPanel({ multiAgent, className }: { multiAgent?: ChatMult | `multiAgent` | 否 | `ChatMultiAgent \| undefined` | | `className` | 否 | `string \| undefined` | - + ## ThreadPanel @@ -593,7 +593,7 @@ export function SubAgentPanel({ multiAgent, className }: { multiAgent?: ChatMult 从 `@openagentpack/kit-chat-ui` 导入 `ThreadPanel`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/thread-panel/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/chrome.mdx`。 +说明来自 `packages/chat-ui/src/components/thread-panel/README.md`。 [可编译示例](../examples/general.tsx) - threads 为空时不渲染。 @@ -610,7 +610,7 @@ export function ThreadPanel({ threads, onArtifactDownload, onCopy, }: { threads: | `onArtifactDownload` | 否 | `((fileId: string) => void) \| undefined` | | `onCopy` | 否 | `((text: string) => void \| Promise) \| undefined` | - + ## CodeHighlighter @@ -638,7 +638,7 @@ export function CodeHighlighter({ children, lang, header, copyable, showLineNumb | `showLineNumbers` | 否 | `boolean \| undefined` | | `className` | 否 | `string \| undefined` | - + ## FileCard @@ -677,7 +677,7 @@ export function FileCard({ name, type, src, description, loading, disabled, onCl 从 `@openagentpack/kit-chat-ui` 导入 `Markdown`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/markdown/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/message.mdx`。 +说明来自 `apps/storybook/content/docs/components/feedback/markdown.mdx`。 [可编译示例](../examples/content.tsx) - children 须为字符串。 @@ -692,7 +692,7 @@ export function Markdown({ children }: { children: string; }): JSX.Element; | --- | --- | --- | | `children` | 是 | `string` | - + ## Mermaid @@ -721,7 +721,7 @@ export function Mermaid({ children, header, className, defaultRenderType, copyab | `streaming` | 否 | `boolean \| undefined` | | `onRenderTypeChange` | 否 | `((value: "image" \| "code") => void) \| undefined` | - + ## ArtifactCard @@ -729,7 +729,7 @@ export function Mermaid({ children, header, className, defaultRenderType, copyab 从 `@openagentpack/kit-chat-ui` 导入 `ArtifactCard`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/artifact-card/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/message.mdx`。 +说明来自 `apps/storybook/content/docs/components/feedback/artifact-card.mdx`。 [可编译示例](../examples/content.tsx) - 用于输出产物,输入文件使用附件组件。 @@ -746,7 +746,7 @@ export function ArtifactCard({ filename, contentType, onOpen, onDownload, }: { f | `onOpen` | 否 | `(() => void) \| undefined` | | `onDownload` | 否 | `(() => void) \| undefined` | - + ## Message @@ -775,7 +775,7 @@ export function Message({ message, variant, onArtifactDownload, onArtifactOpen, | `multiAgent` | 否 | `ChatMultiAgent \| undefined` | | `skills` | 否 | `string[] \| undefined` | - + ## MessageList @@ -870,7 +870,7 @@ export function MessageListSkeleton({ className }: { className?: string; }): JSX 从 `@openagentpack/kit-chat-ui` 导入 `ReasoningBlock`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/process/reasoning-block/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/message.mdx`。 +说明来自 `apps/storybook/content/docs/components/feedback/reasoning-block.mdx`。 [可编译示例](../examples/reasoning.tsx) - 初始折叠,流式期间也如此。内容或状态更新时保留用户的手动展开选择。 @@ -888,7 +888,7 @@ export function ReasoningBlock({ text, status, className, contentMaxHeight, }: { | `className` | 否 | `string \| undefined` | | `contentMaxHeight` | 否 | `string \| undefined` | - + ## ToolCallCard @@ -896,7 +896,7 @@ export function ReasoningBlock({ text, status, className, contentMaxHeight, }: { 从 `@openagentpack/kit-chat-ui` 导入 `ToolCallCard`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/process/tool-call-card/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/message.mdx`。 +说明来自 `apps/storybook/content/docs/components/feedback/tool-call-card.mdx`。 [可编译示例](../examples/content.tsx) - part 必须是 MessagePart 的 tool 分支。 @@ -912,7 +912,7 @@ export function ToolCallCard({ part, className, contentMaxHeight, }: { part: Too | `className` | 否 | `string \| undefined` | | `contentMaxHeight` | 否 | `string \| undefined` | - + ## Prompts @@ -950,7 +950,7 @@ export function Prompts({ items, title, onItemClick, vertical, wrap, fadeIn, fad 从 `@openagentpack/kit-chat-ui` 导入 `Sender`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/sender/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/express/sender.mdx`。 +说明来自 `apps/storybook/content/docs/components/chat/sender.mdx`。 [可编译示例](../examples/attachment-sender.tsx) - 默认 defaultValue=""、submitType="enter"、loading=false、submitDisabled=false、disabled=false、readOnly=false。 @@ -991,7 +991,7 @@ export function Sender(props: SenderProps & RefAttributes): ReactNode | `className` | 否 | `string \| undefined` | | `classNames` | 否 | `Partial> \| undefined` | - + ## SenderHeader @@ -999,7 +999,7 @@ export function Sender(props: SenderProps & RefAttributes): ReactNode 从 `@openagentpack/kit-chat-ui` 导入 `SenderHeader`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/sender/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/express/sender.mdx`。 +说明来自 `apps/storybook/content/docs/components/chat/sender.mdx`。 [可编译示例](../examples/content.tsx) - 与 Sender.Header 是同一组件,默认 open=false、closable=true。 @@ -1017,7 +1017,7 @@ export function SenderHeader({ title, open, onOpenChange, closable, children, cl | `children` | 否 | `ReactNode` | | `className` | 否 | `string \| undefined` | - + ## Sender.Header @@ -1025,7 +1025,7 @@ export function SenderHeader({ title, open, onOpenChange, closable, children, cl 从 `@openagentpack/kit-chat-ui` 导入 `Sender`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/sender/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/express/sender.mdx`。 +说明来自 `apps/storybook/content/docs/components/chat/sender.mdx`。 [可编译示例](../examples/attachment-sender.tsx) - 默认 open=false、closable=true。 @@ -1045,7 +1045,7 @@ export function SenderHeader({ title, open, onOpenChange, closable, children, cl | `children` | 否 | `ReactNode` | | `className` | 否 | `string \| undefined` | - + ## SessionList @@ -1079,7 +1079,7 @@ export function SessionList({ sessions, activeId, activeStatus, onSelect, menu, | `ariaLabel` | 否 | `string \| undefined` | | `className` | 否 | `string \| undefined` | - + ## Tooltip @@ -1240,7 +1240,7 @@ export function ToolApprovalCard({ approval, onDecision, onRefresh, onStop }: To | `onRefresh` | 是 | `() => Promise` | | `onStop` | 否 | `(() => void) \| undefined` | - + ## ToolApprovalGroup @@ -1266,7 +1266,7 @@ export function ToolApprovalGroup({ approvals, onDecision, onRefresh, onStop, }: | `onRefresh` | 是 | `() => Promise` | | `onStop` | 否 | `(() => void) \| undefined` | - + ## PlazaCard @@ -1274,7 +1274,7 @@ export function ToolApprovalGroup({ approvals, onDecision, onRefresh, onStop, }: 从 `@openagentpack/kit-chat-ui` 导入 `PlazaCard`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/plaza-card/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/plaza.mdx`。 +说明来自 `apps/storybook/content/docs/components/plaza/plaza-card.mdx`。 [可编译示例](../examples/discovery-usage.tsx) - onOpen 接收条目 slug,导航及会话选择由调用方负责。 @@ -1288,15 +1288,15 @@ export function PlazaCard({ entry, onOpen }: { entry: PlazaEntry; onOpen: (slug: | `entry` | 是 | `{ slug: string; display_name: string; suggested_prompts: string[]; capabilities: { streaming: boolean; fileUpload: boolean; artifacts: boolean; threads: boolean; reasoning: boolean; }; category: "data" \| "general" \| "writing" \| "coding" \| "other"; featured: boolean; stats: { mine: boolean; turns_30d: number; last_used_at?: string \| undefined; }; description?: string \| undefined; icon?: string \| undefined; opening_remarks?: string \| undefined; theme?: { accent?: string \| undefined; iconBackground?: string \| undefined; } \| undefined; }` | | `onOpen` | 是 | `(slug: string) => void` | - + ## CategoryTabs -受控选择广场分类或推荐标签页。 +受控选择广场分类或精选标签页。 从 `@openagentpack/kit-chat-ui` 导入 `CategoryTabs`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/category-tabs/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/plaza.mdx`。 +说明来自 `apps/storybook/content/docs/components/plaza/category-tabs.mdx`。 [可编译示例](../examples/discovery-usage.tsx) - 在传入分类的开头插入 featured。 @@ -1312,7 +1312,7 @@ export function CategoryTabs({ categories, active, onChange, }: { categories: { | `active` | 是 | `PlazaTabId` | | `onChange` | 是 | `(next: PlazaTabId) => void` | - + ## MeterBar @@ -1320,7 +1320,7 @@ export function CategoryTabs({ categories, active, onChange, }: { categories: { 从 `@openagentpack/kit-chat-ui` 导入 `MeterBar`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/meter-bar/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/plaza.mdx`。 +说明来自 `apps/storybook/content/docs/components/plaza/meter-bar.mdx`。 [可编译示例](../examples/discovery-usage.tsx) - 默认 unlimited=false、className=""。 @@ -1337,7 +1337,7 @@ export function MeterBar({ value, max, unlimited, className, }: { value: number; | `unlimited` | 否 | `boolean \| undefined` | | `className` | 否 | `string \| undefined` | - + ## ActivityHeatmap @@ -1345,7 +1345,7 @@ export function MeterBar({ value, max, unlimited, className, }: { value: number; 从 `@openagentpack/kit-chat-ui` 导入 `ActivityHeatmap`。 公开入口为 `packages/chat-ui/src/index.ts`,声明位于 `packages/chat-ui/src/components/activity-heatmap/index.tsx`。 -说明来自 `apps/storybook/content/docs/components/plaza.mdx`。 +说明来自 `apps/storybook/content/docs/components/plaza/activity-heatmap.mdx`。 [可编译示例](../examples/discovery-usage.tsx) - 保留输入顺序,日期字符串须唯一。 @@ -1359,7 +1359,7 @@ export function ActivityHeatmap({ days }: { days: { day: string; turns: number; | --- | --- | --- | | `days` | 是 | `{ day: string; turns: number; }[]` | - + ## SkillGlyph diff --git a/assets/skills/use-kit-chat/references/api.md b/assets/skills/use-kit-chat/references/api.md index 8ef974e..22aa3d3 100644 --- a/assets/skills/use-kit-chat/references/api.md +++ b/assets/skills/use-kit-chat/references/api.md @@ -81,7 +81,7 @@ export function useAgentResources(slug: string | null, options?: { client?: KitC ``` - + ## useUsageLimits @@ -99,7 +99,7 @@ export function useUsageLimits(options?: { client?: KitClient; enabled?: boolean ``` - + ## createChatController @@ -371,7 +371,7 @@ export function KitProvider({ client, children }: { client: KitClient; children: ``` - + ## createKitClient @@ -390,7 +390,7 @@ export function createKitClient(options: KitClientOptions): KitClient; ``` - + ## ChatProvider @@ -495,7 +495,7 @@ export function usePlaza(options?: { client?: KitClient; category?: PlazaCategor ``` - + ## useQuota @@ -514,7 +514,7 @@ export function useQuota(options?: { client?: KitClient; days?: number; }): { qu ``` - + ## useQuotaRequests @@ -533,7 +533,7 @@ export function useQuotaRequests(options?: { client?: KitClient; }): { requests: ``` - + ## createMemberAuthController @@ -550,7 +550,7 @@ export function createMemberAuthController(options: MemberAuthOptions): { getSna ``` - + ## MemberAuthController @@ -576,7 +576,7 @@ export type MemberAuthController = { getSnapshot: () => MemberAuthSnapshot; subs | `retry` | 是 | `() => Promise` | | `dispose` | 是 | `() => void` | - + ## MemberAuthOptions @@ -601,7 +601,7 @@ import type { MemberAuthOptions } from "@openagentpack/kit-sdk/auth"; | `createChatProvider` | 否 | `((request: RequestClient) => ChatProvider) \| undefined` | | `createClient` | 否 | `((request: RequestClient) => KitClient) \| undefined` | - + ## MemberAuthSnapshot @@ -627,7 +627,7 @@ import type { MemberAuthSnapshot } from "@openagentpack/kit-sdk/auth"; | `error` | 是 | `string \| null` | | `pending` | 是 | `boolean` | - + ## MemberSessionStorage @@ -648,7 +648,7 @@ import type { MemberSessionStorage } from "@openagentpack/kit-sdk/auth"; | `load` | 是 | `() => StoredMemberSession \| null` | | `save` | 是 | `(session: StoredMemberSession \| null) => void` | - + ## StoredMemberSession @@ -669,7 +669,7 @@ import type { StoredMemberSession } from "@openagentpack/kit-sdk/auth"; | `access_token` | 是 | `string` | | `expires_at` | 是 | `string` | - + ## useMemberAuth @@ -686,7 +686,7 @@ export function useMemberAuth(controller: MemberAuthController): { login: (input ``` - + ## ChatMultiAgent diff --git a/docs/protocol.md b/docs/protocol.md index ff9aa0a..102cba5 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -130,8 +130,9 @@ Kit Server 是标准事件示例后端。订阅采用本文相同的控制帧: 不回退。历史加载不调用主 Store 的 `applyEvent`,不改变乐观消息或审批覆盖状态。 - Session/Provider 切换与卸载取消查询,代次检查丢弃迟到结果;Session SSE reset 使补充 历史失效并在 ready 后重新加载,防止已撤回事件复活。切换线程不重新建立 Session SSE。 -- `useChat().multiAgent` 是共享展示与动作合同;`Chat` 原生呈现页签与只读子 Agent 历史。 - 主输入、草稿、附件及审批保留,子页仍提供返回主 Agent 和停止整轮执行的入口。 +- `useChat().multiAgent` 提供共享的展示数据与动作。`Chat` 在主消息流的派发位置展示子 Agent 卡片, + 展开后可查看只读历史。`SubAgentPanel` 使用同一快照在资源面板展示派发记录和执行详情。 + 展开子线程时保留主输入区、草稿、附件和审批,主输入区可停止整轮执行。 Provider 还可提供 `transformMessage({ messages, event, identity })`,返回 `{ messages, artifacts? }`。这是浏览器内的展示转换策略,不是新增后端操作或 SSE 字段。 diff --git a/packages/chat-ui/src/components/activity-heatmap/README.md b/packages/chat-ui/src/components/activity-heatmap/README.md index 1ef234e..97eb580 100644 --- a/packages/chat-ui/src/components/activity-heatmap/README.md +++ b/packages/chat-ui/src/components/activity-heatmap/README.md @@ -29,4 +29,4 @@ pnpm kit:add activity-heatmap 源码入口为 [index.tsx](index.tsx)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/plaza.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[活跃热力图文档](../../../../../apps/storybook/content/docs/components/plaza/activity-heatmap.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/artifact-card/README.md b/packages/chat-ui/src/components/artifact-card/README.md index 25dd9fe..503e7d4 100644 --- a/packages/chat-ui/src/components/artifact-card/README.md +++ b/packages/chat-ui/src/components/artifact-card/README.md @@ -34,4 +34,4 @@ pnpm kit:add artifact-card 组件依赖:[file-card](../file-card/README.md)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/message.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/feedback/artifact-card.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/category-tabs/README.md b/packages/chat-ui/src/components/category-tabs/README.md index 724fc70..54a32bb 100644 --- a/packages/chat-ui/src/components/category-tabs/README.md +++ b/packages/chat-ui/src/components/category-tabs/README.md @@ -31,4 +31,4 @@ pnpm kit:add category-tabs 源码入口为 [index.tsx](index.tsx)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/plaza.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[广场分类文档](../../../../../apps/storybook/content/docs/components/plaza/category-tabs.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/chat/README.md b/packages/chat-ui/src/components/chat/README.md index 431096a..77cda95 100644 --- a/packages/chat-ui/src/components/chat/README.md +++ b/packages/chat-ui/src/components/chat/README.md @@ -51,4 +51,4 @@ pnpm kit:add chat 同目录测试:[chat.test.tsx](chat.test.tsx)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chat.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chat/index.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/chrome/README.md b/packages/chat-ui/src/components/chrome/README.md index cef7ef8..0c3782e 100644 --- a/packages/chat-ui/src/components/chrome/README.md +++ b/packages/chat-ui/src/components/chrome/README.md @@ -30,4 +30,4 @@ pnpm kit:add chrome 组件依赖:[agent-header](../agent-header/README.md)、[confirm-dialog](../confirm-dialog/README.md)、[status-indicator](../status-indicator/README.md)、[thread-panel](../thread-panel/README.md)、[states](../states/README.md)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chrome.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +页面组合见[最佳实践](../../../../../apps/storybook/content/docs/components/chrome.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/confirm-dialog/README.md b/packages/chat-ui/src/components/confirm-dialog/README.md index f565405..28a64b0 100644 --- a/packages/chat-ui/src/components/confirm-dialog/README.md +++ b/packages/chat-ui/src/components/confirm-dialog/README.md @@ -37,4 +37,4 @@ pnpm kit:add confirm-dialog 源码入口为 [index.tsx](index.tsx)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chrome.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +组合用法见[会话操作确认](../../../../../apps/storybook/content/docs/components/chrome.mdx#会话操作确认)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/empty-state/README.md b/packages/chat-ui/src/components/empty-state/README.md index 68115c6..a8da6fd 100644 --- a/packages/chat-ui/src/components/empty-state/README.md +++ b/packages/chat-ui/src/components/empty-state/README.md @@ -31,4 +31,4 @@ pnpm kit:add empty-state 源码入口为 [index.tsx](index.tsx)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chrome.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +组合用法见[欢迎、加载与错误态](../../../../../apps/storybook/content/docs/components/chrome.mdx#欢迎加载与错误态)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/error-state/README.md b/packages/chat-ui/src/components/error-state/README.md index a7ac43f..443cdad 100644 --- a/packages/chat-ui/src/components/error-state/README.md +++ b/packages/chat-ui/src/components/error-state/README.md @@ -30,4 +30,4 @@ pnpm kit:add error-state 源码入口为 [index.tsx](index.tsx)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chrome.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +组合用法见[欢迎、加载与错误态](../../../../../apps/storybook/content/docs/components/chrome.mdx#欢迎加载与错误态)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/layout/README.md b/packages/chat-ui/src/components/layout/README.md index bf3caad..b792041 100644 --- a/packages/chat-ui/src/components/layout/README.md +++ b/packages/chat-ui/src/components/layout/README.md @@ -44,4 +44,4 @@ pnpm kit:add layout 同目录测试:[layout.test.tsx](layout.test.tsx)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/layout.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/layout/index.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/markdown/README.md b/packages/chat-ui/src/components/markdown/README.md index 637a75f..28b6a44 100644 --- a/packages/chat-ui/src/components/markdown/README.md +++ b/packages/chat-ui/src/components/markdown/README.md @@ -33,4 +33,4 @@ pnpm kit:add markdown 同目录测试:[markdown.test.tsx](markdown.test.tsx)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/message.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/feedback/markdown.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/meter-bar/README.md b/packages/chat-ui/src/components/meter-bar/README.md index 9b6f3eb..7bc308e 100644 --- a/packages/chat-ui/src/components/meter-bar/README.md +++ b/packages/chat-ui/src/components/meter-bar/README.md @@ -32,4 +32,4 @@ pnpm kit:add meter-bar 源码入口为 [index.tsx](index.tsx)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/plaza.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[用量条文档](../../../../../apps/storybook/content/docs/components/plaza/meter-bar.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/plaza-card/README.md b/packages/chat-ui/src/components/plaza-card/README.md index e5ed7bf..6d647d6 100644 --- a/packages/chat-ui/src/components/plaza-card/README.md +++ b/packages/chat-ui/src/components/plaza-card/README.md @@ -34,4 +34,4 @@ pnpm kit:add plaza-card 同目录测试:[plaza.test.tsx](plaza.test.tsx)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/plaza.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[智能体卡片文档](../../../../../apps/storybook/content/docs/components/plaza/plaza-card.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/plaza/README.md b/packages/chat-ui/src/components/plaza/README.md index 62b1464..675f0c7 100644 --- a/packages/chat-ui/src/components/plaza/README.md +++ b/packages/chat-ui/src/components/plaza/README.md @@ -27,4 +27,4 @@ pnpm kit:add plaza 组件依赖:[activity-heatmap](../activity-heatmap/README.md)、[category-tabs](../category-tabs/README.md)、[meter-bar](../meter-bar/README.md)、[plaza-card](../plaza-card/README.md)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/plaza.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +各组件文档入口见[组件总览中的广场与用量](../../../../../apps/storybook/content/docs/components/index.mdx#广场与用量)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/process/execution-group/README.md b/packages/chat-ui/src/components/process/execution-group/README.md index ecfab87..aaa366c 100644 --- a/packages/chat-ui/src/components/process/execution-group/README.md +++ b/packages/chat-ui/src/components/process/execution-group/README.md @@ -32,4 +32,4 @@ pnpm kit:add execution-group 组件依赖:[reasoning-block](../reasoning-block/README.md)、[tool-call-card](../tool-call-card/README.md)。 -完整用法与参数见[文档站对应页面](../../../../../../apps/storybook/content/docs/components/message.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +执行过程的组合展示见 [Message 文档](../../../../../../apps/storybook/content/docs/components/general/message.mdx#富内容与执行过程)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/process/reasoning-block/README.md b/packages/chat-ui/src/components/process/reasoning-block/README.md index a11c10e..b13096b 100644 --- a/packages/chat-ui/src/components/process/reasoning-block/README.md +++ b/packages/chat-ui/src/components/process/reasoning-block/README.md @@ -34,4 +34,4 @@ pnpm kit:add reasoning-block 组件依赖:[process-step](../step/README.md)。 -完整用法与参数见[文档站对应页面](../../../../../../apps/storybook/content/docs/components/message.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[文档站对应页面](../../../../../../apps/storybook/content/docs/components/feedback/reasoning-block.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/process/step/README.md b/packages/chat-ui/src/components/process/step/README.md index f6b25e1..b3f3b99 100644 --- a/packages/chat-ui/src/components/process/step/README.md +++ b/packages/chat-ui/src/components/process/step/README.md @@ -60,4 +60,4 @@ pnpm kit:add process-step 源码入口为 [index.tsx](index.tsx)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../../apps/storybook/content/docs/components/message.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +思考和工具步骤的组合展示见 [Message 文档](../../../../../../apps/storybook/content/docs/components/general/message.mdx#富内容与执行过程)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/process/tool-call-card/README.md b/packages/chat-ui/src/components/process/tool-call-card/README.md index 6ef727e..558bcaf 100644 --- a/packages/chat-ui/src/components/process/tool-call-card/README.md +++ b/packages/chat-ui/src/components/process/tool-call-card/README.md @@ -35,4 +35,4 @@ pnpm kit:add tool-call-card 同目录测试:[tool-call-card.test.tsx](tool-call-card.test.tsx)。 -完整用法与参数见[文档站对应页面](../../../../../../apps/storybook/content/docs/components/message.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[文档站对应页面](../../../../../../apps/storybook/content/docs/components/feedback/tool-call-card.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/process/tool-summary/README.md b/packages/chat-ui/src/components/process/tool-summary/README.md index d01c13f..c78f88e 100644 --- a/packages/chat-ui/src/components/process/tool-summary/README.md +++ b/packages/chat-ui/src/components/process/tool-summary/README.md @@ -34,4 +34,4 @@ pnpm kit:add tool-summary 源码入口为 [index.ts](index.ts)。copy-in 会保留目录层级并带入 registry 声明的依赖;主题接入见文档站。 -完整用法与参数见[文档站对应页面](../../../../../../apps/storybook/content/docs/components/message.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +工具步骤的摘要展示见[工具调用卡文档](../../../../../../apps/storybook/content/docs/components/feedback/tool-call-card.mdx)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/sender/README.md b/packages/chat-ui/src/components/sender/README.md index 6611f9c..0ecef41 100644 --- a/packages/chat-ui/src/components/sender/README.md +++ b/packages/chat-ui/src/components/sender/README.md @@ -72,4 +72,4 @@ pnpm kit:add sender 同目录测试:[sender.test.tsx](sender.test.tsx)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/express/sender.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chat/sender.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/states/README.md b/packages/chat-ui/src/components/states/README.md index 5fcf3f1..8a3046c 100644 --- a/packages/chat-ui/src/components/states/README.md +++ b/packages/chat-ui/src/components/states/README.md @@ -25,4 +25,4 @@ pnpm kit:add states 组件依赖:[empty-state](../empty-state/README.md)、[error-state](../error-state/README.md)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chrome.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +组合用法见[欢迎、加载与错误态](../../../../../apps/storybook/content/docs/components/chrome.mdx#欢迎加载与错误态)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/status-indicator/README.md b/packages/chat-ui/src/components/status-indicator/README.md index de094aa..9e9bda6 100644 --- a/packages/chat-ui/src/components/status-indicator/README.md +++ b/packages/chat-ui/src/components/status-indicator/README.md @@ -2,8 +2,8 @@ 将执行阶段、连接状态和错误组合为文本或紧凑徽标。 -- `connected` / `turnRunning` 是基础状态,`phase` / `connection` 提供精确状态。 -- 重连中的错误仍展示重连状态,其他错误显示文案;组件不启动连接或重试。 +- `connected` 和 `turnRunning` 为必填项,`phase` 提供时作为执行阶段。 +- `connection` 为 `connecting` 或 `reconnecting` 时覆盖基础状态。有错误时,重连中保留重连提示,其余状态展示错误。 ## Props @@ -11,10 +11,10 @@ | 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | -| `connected` | `boolean` | 是 | — | 是否已建立连接;旧接入 props,新接入改传 `connection` | -| `turnRunning` | `boolean` | 是 | — | 当前 Turn 是否在生成;与 `phase` 并存的旧 props | +| `connected` | `boolean` | 是 | — | 是否已建立连接,可传 `chat.connection === "connected"` | +| `turnRunning` | `boolean` | 是 | — | 当前回合是否在生成,可传 `chat.turnRunning` | | `phase` | `"running" \| "failed" \| "idle" \| "requires_action" \| "stopping" \| "interrupted"` | 否 | — | Turn 阶段,优先于由 `turnRunning` 推导 | -| `connection` | `ConnectionState` | 否 | — | 连接状态;`connecting` / `reconnecting` 提示覆盖暂存错误 | +| `connection` | `ConnectionState` | 否 | — | 连接状态,取值为 `disconnected`、`connecting`、`connected` 或 `reconnecting` | | `error` | `{ code: string; message: string; } \| null` | 否 | — | 流错误,与错误模型同一套 code | | `variant` | `"default" \| "badge"` | 否 | `"default"` | `badge` 在保留状态文本的同时提供紧凑徽标,适合空间受限的页头 | @@ -36,4 +36,4 @@ pnpm kit:add status-indicator 同目录测试:[status-indicator.test.tsx](status-indicator.test.tsx)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chrome.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +组合用法见[状态灯演示](../../../../../apps/storybook/content/docs/components/chrome.mdx#状态灯)。全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/packages/chat-ui/src/components/thread-panel/README.md b/packages/chat-ui/src/components/thread-panel/README.md index 45f2a2f..a3c698b 100644 --- a/packages/chat-ui/src/components/thread-panel/README.md +++ b/packages/chat-ui/src/components/thread-panel/README.md @@ -33,4 +33,4 @@ pnpm kit:add thread-panel 组件依赖:[message](../message/README.md)。 -完整用法与参数见[文档站对应页面](../../../../../apps/storybook/content/docs/components/chrome.mdx);全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 +全部组件回归运行 `pnpm --filter @openagentpack/kit-chat-ui test`。 diff --git a/scripts/skills/src/kit-components/catalog.json b/scripts/skills/src/kit-components/catalog.json index ab35ef3..13b9429 100644 --- a/scripts/skills/src/kit-components/catalog.json +++ b/scripts/skills/src/kit-components/catalog.json @@ -98,7 +98,7 @@ "name": "Layout", "export": "Layout", "description": "组合会话导航、页头、限高聊天区和响应式 Agent 资源面板。", - "doc": "apps/storybook/content/docs/components/layout.mdx", + "doc": "apps/storybook/content/docs/components/layout/index.mdx", "example": "examples/layout.tsx", "notes": [ "sidebar 接受内容或获得 closeSidebar、closeButton 的渲染回调。侧栏尺寸、边框和移动端显示由调用方配置。", @@ -113,7 +113,7 @@ "name": "Chat", "export": "Chat", "description": "组合消息列表、内联子 Agent 卡片、默认 Sender 和主 Agent 审批。", - "doc": "apps/storybook/content/docs/components/chat.mdx", + "doc": "apps/storybook/content/docs/components/chat/index.mdx", "example": "examples/chat-runtime.tsx", "notes": [ "默认 variant=default、turnRunning=false、canSend=true。员工端布局需显式使用 workspace。", @@ -157,7 +157,7 @@ "name": "ConfirmDialog", "export": "ConfirmDialog", "description": "展示显式确认和取消选项。", - "doc": "apps/storybook/content/docs/components/chrome.mdx", + "doc": "packages/chat-ui/src/components/confirm-dialog/README.md", "example": "examples/general.tsx", "notes": [ "danger 默认 true,由调用方按条件挂载。", @@ -169,14 +169,14 @@ "name": "EmptyState", "export": "EmptyState", "description": "显示带标题和可选提示的空态。", - "doc": "apps/storybook/content/docs/components/chrome.mdx", + "doc": "packages/chat-ui/src/components/empty-state/README.md", "example": "examples/general.tsx" }, { "name": "ErrorState", "export": "ErrorState", "description": "展示可访问的错误消息及可选重试操作。", - "doc": "apps/storybook/content/docs/components/chrome.mdx", + "doc": "packages/chat-ui/src/components/error-state/README.md", "example": "examples/general.tsx", "notes": [ "提供 onRetry 时才显示重试按钮,由调用方定义重试行为。" @@ -201,7 +201,7 @@ "name": "StatusIndicator", "export": "StatusIndicator", "description": "分别显示传输连接与执行阶段。", - "doc": "apps/storybook/content/docs/components/chrome.mdx", + "doc": "packages/chat-ui/src/components/status-indicator/README.md", "example": "examples/general.tsx", "notes": [ "兼容用的必填 Props 为 connected 和 turnRunning。", @@ -223,7 +223,7 @@ "name": "ThreadPanel", "export": "ThreadPanel", "description": "展示投影后的子线程消息,共用复制和下载回调。", - "doc": "apps/storybook/content/docs/components/chrome.mdx", + "doc": "packages/chat-ui/src/components/thread-panel/README.md", "example": "examples/general.tsx", "notes": [ "threads 为空时不渲染。", @@ -259,7 +259,7 @@ "name": "Markdown", "export": "Markdown", "description": "渲染经净化的 GFM 文本、代码块和完整 Mermaid 围栏。", - "doc": "apps/storybook/content/docs/components/message.mdx", + "doc": "apps/storybook/content/docs/components/feedback/markdown.mdx", "example": "examples/content.tsx", "notes": [ "children 须为字符串。", @@ -283,7 +283,7 @@ "name": "ArtifactCard", "export": "ArtifactCard", "description": "将输出产物元数据适配到 FileCard,并注入预览与下载操作。", - "doc": "apps/storybook/content/docs/components/message.mdx", + "doc": "apps/storybook/content/docs/components/feedback/artifact-card.mdx", "example": "examples/content.tsx", "notes": [ "用于输出产物,输入文件使用附件组件。", @@ -340,7 +340,7 @@ "name": "ReasoningBlock", "export": "ReasoningBlock", "description": "显示可折叠的推理文本和生命周期状态。", - "doc": "apps/storybook/content/docs/components/message.mdx", + "doc": "apps/storybook/content/docs/components/feedback/reasoning-block.mdx", "example": "examples/reasoning.tsx", "notes": [ "初始折叠,流式期间也如此。内容或状态更新时保留用户的手动展开选择。", @@ -352,7 +352,7 @@ "name": "ToolCallCard", "export": "ToolCallCard", "description": "展示已投影的工具调用、结构化参数、输出和状态。", - "doc": "apps/storybook/content/docs/components/message.mdx", + "doc": "apps/storybook/content/docs/components/feedback/tool-call-card.mdx", "example": "examples/content.tsx", "notes": [ "part 必须是 MessagePart 的 tool 分支。", @@ -375,7 +375,7 @@ "name": "Sender", "export": "Sender", "description": "编辑、提交或停止消息,并接入调用方管理的附件与建议。", - "doc": "apps/storybook/content/docs/components/express/sender.mdx", + "doc": "apps/storybook/content/docs/components/chat/sender.mdx", "example": "examples/attachment-sender.tsx", "notes": [ "默认 defaultValue=\"\"、submitType=\"enter\"、loading=false、submitDisabled=false、disabled=false、readOnly=false。", @@ -390,7 +390,7 @@ "name": "SenderHeader", "export": "SenderHeader", "description": "可选 Sender 顶部面板的独立导出。", - "doc": "apps/storybook/content/docs/components/express/sender.mdx", + "doc": "apps/storybook/content/docs/components/chat/sender.mdx", "example": "examples/content.tsx", "notes": [ "与 Sender.Header 是同一组件,默认 open=false、closable=true。" @@ -401,7 +401,7 @@ "export": "Sender", "member": "Header", "description": "在文本输入框上方显示受控的可展开面板。", - "doc": "apps/storybook/content/docs/components/express/sender.mdx", + "doc": "apps/storybook/content/docs/components/chat/sender.mdx", "example": "examples/attachment-sender.tsx", "notes": [ "默认 open=false、closable=true。", @@ -515,7 +515,7 @@ "name": "PlazaCard", "export": "PlazaCard", "description": "展示一个广场条目,在打开 Agent 时通知调用方。", - "doc": "apps/storybook/content/docs/components/plaza.mdx", + "doc": "apps/storybook/content/docs/components/plaza/plaza-card.mdx", "example": "examples/discovery-usage.tsx", "notes": [ "onOpen 接收条目 slug,导航及会话选择由调用方负责。" @@ -524,8 +524,8 @@ { "name": "CategoryTabs", "export": "CategoryTabs", - "description": "受控选择广场分类或推荐标签页。", - "doc": "apps/storybook/content/docs/components/plaza.mdx", + "description": "受控选择广场分类或精选标签页。", + "doc": "apps/storybook/content/docs/components/plaza/category-tabs.mdx", "example": "examples/discovery-usage.tsx", "notes": [ "在传入分类的开头插入 featured。", @@ -536,7 +536,7 @@ "name": "MeterBar", "export": "MeterBar", "description": "将额度用量展示为有界进度或不限量轨道。", - "doc": "apps/storybook/content/docs/components/plaza.mdx", + "doc": "apps/storybook/content/docs/components/plaza/meter-bar.mdx", "example": "examples/discovery-usage.tsx", "notes": [ "默认 unlimited=false、className=\"\"。", @@ -547,7 +547,7 @@ "name": "ActivityHeatmap", "export": "ActivityHeatmap", "description": "展示调用方提供的每日活动及相对强度。", - "doc": "apps/storybook/content/docs/components/plaza.mdx", + "doc": "apps/storybook/content/docs/components/plaza/activity-heatmap.mdx", "example": "examples/discovery-usage.tsx", "notes": [ "保留输入顺序,日期字符串须唯一。", diff --git a/scripts/skills/tests/generate.test.mjs b/scripts/skills/tests/generate.test.mjs index badf49a..88b60e3 100644 --- a/scripts/skills/tests/generate.test.mjs +++ b/scripts/skills/tests/generate.test.mjs @@ -209,12 +209,12 @@ test("stale generated output fails read-only checking and can be regenerated det test("one generation synchronizes SDK and component examples with their source files", () => { const directory = mkdtempSync(resolve(tmpdir(), "kit-skills-sdk-docs-")); try { - for (const path of ["scripts/skills/src", "apps/storybook/content"]) { + for (const path of ["scripts/skills/src", "apps/storybook/content", "packages/chat-ui/src/components"]) { cpSync(resolve(repositoryRoot, path), resolve(directory, path), { recursive: true }); } const examples = [ ["kit-chat-provider", "request.ts", "sdk/request.mdx"], - ["kit-components", "layout.tsx", "components/layout.mdx"], + ["kit-components", "layout.tsx", "components/layout/index.mdx"], ]; for (const [skill, example] of examples) { const source = resolve(skillSourceRoot(directory, skill), "examples", example); From eb42903f40eae1ad2ac3991ef5dd8ecc91e3aca0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=82=9F=E6=89=AC?= Date: Fri, 20 Nov 2026 10:33:37 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(repo):=20=E7=A7=BB=E9=99=A4=20README?= =?UTF-8?q?=20=E4=B8=AD=E9=87=8D=E5=A4=8D=E7=9A=84=E6=8F=90=E4=BA=A4?= =?UTF-8?q?=E6=A0=BC=E5=BC=8F=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 1e6a3c0..2f07859 100644 --- a/README.md +++ b/README.md @@ -298,7 +298,6 @@ pnpm gate # typecheck + lint + test + build + 架构检查 + 文档检查 pnpm verify:push # pre-push hook 跑的就是这套 ``` -提交信息使用简体中文 Conventional Commits,例如 `fix(server): 修复会话恢复`。 Issue 与反馈:https://github.com/modelstudioai/OpenAgentPack-Kit/issues ## License