From 8d7cc1febb8a1667bfb1380a23c3536d21c6766b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=82=9F=E6=89=AC?= Date: Fri, 20 Nov 2026 10:50:48 +0800 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=E6=96=B0=E5=A2=9E=E6=95=B0?= =?UTF-8?q?=E6=8D=AE=E5=BA=93=E6=8E=A5=E5=85=A5=20Skill=20=E5=B9=B6?= =?UTF-8?q?=E7=A7=BB=E9=99=A4=E5=AE=A2=E6=88=B7=E7=AB=AF=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 提供 SQLite、MySQL 和 PostgreSQL 的接入说明,同步 AGENTS.md 和文档入口。生成与打包统一使用通用 Skill 文件。 --- AGENTS.md | 1 + README.md | 2 +- apps/server/AGENTS.md | 3 + apps/server/README.md | 2 + apps/storybook/content/docs/skill/index.mdx | 14 ++-- apps/storybook/content/docs/skill/install.mdx | 18 +++-- .../content/docs/skill/kit-database.mdx | 16 +++++ apps/storybook/content/docs/skill/meta.json | 2 +- .../kit-chat-provider/agents/openai.yaml | 4 -- .../skills/kit-components/agents/openai.yaml | 4 -- assets/skills/kit-database/SKILL.md | 69 +++++++++++++++++++ assets/skills/use-kit-chat/agents/openai.yaml | 4 -- ...0027-skills-source-and-generated-output.md | 4 ++ docs/repository-layout.md | 11 +-- scripts/skills/AGENTS.md | 8 ++- scripts/skills/README.md | 13 ++-- scripts/skills/generate.mjs | 43 +++++------- scripts/skills/pack.mjs | 34 +++++---- .../src/kit-chat-provider/metadata.json | 5 +- .../skills/src/kit-components/metadata.json | 5 +- scripts/skills/src/kit-database/metadata.json | 4 ++ scripts/skills/src/kit-database/skill.md | 64 +++++++++++++++++ scripts/skills/src/use-kit-chat/metadata.json | 5 +- scripts/skills/tests/generate.test.mjs | 27 +++++--- 24 files changed, 261 insertions(+), 101 deletions(-) create mode 100644 apps/storybook/content/docs/skill/kit-database.mdx delete mode 100644 assets/skills/kit-chat-provider/agents/openai.yaml delete mode 100644 assets/skills/kit-components/agents/openai.yaml create mode 100644 assets/skills/kit-database/SKILL.md delete mode 100644 assets/skills/use-kit-chat/agents/openai.yaml create mode 100644 scripts/skills/src/kit-database/metadata.json create mode 100644 scripts/skills/src/kit-database/skill.md diff --git a/AGENTS.md b/AGENTS.md index e4e8a3a..1029819 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,7 @@ - 完整 SDK 公开入口以 `packages/sdk/package.json` 为准;目录映射见目录规则。 - 工作区只包含 `apps/*` 与 `packages/*`;目录与命令是否可用以当前清单为准, 不按历史 ADR 的旧名称恢复已退役的包、原生壳、项目生成器或目录 Project API。 +- 配置 Kit Server 的 SQLite、MySQL 或 PostgreSQL 时,使用仓库内的 [kit-database](assets/skills/kit-database/SKILL.md)。 ## 执行红线 diff --git a/README.md b/README.md index b2c5200..63f50dd 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ | UI 组件 `@openagentpack/kit-chat-ui` | Chat、Message、Sender、Attachments、FileCard、ToolApprovalCard 等 | 组合对话、输入、附件、文件和审批界面;支持将组件及声明依赖复制到业务项目中修改 | | 会话运行时 `@openagentkit/sdk` 的功能入口 | 流解析、请求、后端适配、消息状态、重连与会话动作 | 接入既有后端,管理流式数据与会话交互;非 React 应用可直接订阅会话状态 | | React hooks `@openagentkit/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`、`kit-database` | 指导 coding agent 组合组件、管理会话、接入对话后端和配置服务端数据库 | SDK 按功能导入,例如 `@openagentkit/sdk/chat`、`@openagentkit/sdk/chat/hooks` 与 `@openagentkit/sdk/sessions/hooks`,不提供根聚合入口。 diff --git a/apps/server/AGENTS.md b/apps/server/AGENTS.md index 8669ea9..a909f7c 100644 --- a/apps/server/AGENTS.md +++ b/apps/server/AGENTS.md @@ -54,6 +54,9 @@ ## 修改步骤 +接入或切换数据库时,按 [kit-database](../../assets/skills/kit-database/SKILL.md) 核对现有配置和目标库。 +启动后通过日志中的 `db=` 和 `/healthz` 确认后端与服务状态。需要核对迁移时,读取目标库的 `_kit_migrations`。 + 1. 在 `docs/interfaces.md` 核对或登记 op,确认身份、Schema、错误与恢复语义。 2. 路由只负责边界;服务组织业务,gateway 处理 Provider 合同,store 处理事务与迁移。 3. 改后端接口运行 `pnpm gen:openapi`,检查服务端 spec 与 SDK 生成类型。 diff --git a/apps/server/README.md b/apps/server/README.md index ade5bce..812bd5a 100644 --- a/apps/server/README.md +++ b/apps/server/README.md @@ -67,6 +67,8 @@ node apps/server/dist/bin.js ### 选择数据库 +也可以用 `$kit-database` 让 coding agent 按项目配置接入数据库并核对启动结果。[数据库接入 Skill](../../assets/skills/kit-database/SKILL.md) + 默认启动使用 `KIT_DATA_DIR/kit.sqlite`。如需外部数据库,先创建 Kit 专用库,并授予连接账户 在该库中建表和读写的权限。在根 `.env` 或服务端进程环境中设置以下一组变量,重启后会在所选库中初始化表结构。 diff --git a/apps/storybook/content/docs/skill/index.mdx b/apps/storybook/content/docs/skill/index.mdx index 0ff88fa..d40374c 100644 --- a/apps/storybook/content/docs/skill/index.mdx +++ b/apps/storybook/content/docs/skill/index.mdx @@ -1,12 +1,12 @@ --- title: Skill -description: 用三个中文 Skill 指导 coding agent 组合 Kit 组件、管理会话与接入自建百炼后端 +description: 用中文 Skill 组合 Kit 组件、管理会话、接入对话后端和配置服务端数据库 --- import { Cards, Card } from "fumadocs-ui/components/card"; -Kit 提供三个面向 coding agent 的中文 Skill,分别指导组件选择、聊天状态与后端接入。 -每个 Skill 都包含工作步骤、API 参考和经过类型检查的示例,可以独立复制使用。 +Kit 的中文 Skill 指导 coding agent 选择组件、管理聊天状态、接入对话后端和配置服务端数据库。 +每个 Skill 都可以独立复制使用,涉及公开 API 的 Skill 附有接口参考和可编译示例。 Skill 是写代码时读取的指南,不是运行时插件,也不会替应用创建会话或调用百炼。 页面的实际行为仍由 `kit-chat-ui`、Kit SDK 各功能入口及其 `/hooks` 和业务后端完成。 @@ -17,6 +17,7 @@ Skill 是写代码时读取的指南,不是运行时插件,也不会替应 + | 想完成的工作 | 从哪个 Skill 开始 | @@ -24,15 +25,16 @@ Skill 是写代码时读取的指南,不是运行时插件,也不会替应 | 选择消息、输入、附件、反馈和页面辅助组件 | `kit-components` | | 把已有后端连接到页面,管理发送与会话状态 | `use-kit-chat` | | 自己有百炼后端,需要适配请求和流数据合同 | `kit-chat-provider` | +| 为 Kit Server 选择数据库并验证启动 | `kit-database` | -完整对话页面通常会同时使用三个 Skill。只有 UI 组合需求时,可以单独使用 +完整对话页面通常会同时使用对话相关的三个 Skill。只有 UI 组合需求时,可以单独使用 `kit-components`;已有稳定 Provider 时,不需要重复实现后端适配。 ## 获取与阅读 先阅读[安装与更新](/docs/skill/install),再将 Skill 目录复制到 coding agent 支持的目录。 -也可以直接下载[三个 Skill 的离线包](/skills/kit-skills.tgz)并阅读其中的 `SKILL.md`。 -每个包都带有所需的 `references/` 和 `examples/`,不要只复制入口文件。 +也可以直接下载[全部 Skill 的离线包](/skills/kit-skills.tgz)并阅读其中的 `SKILL.md`。 +复制完整目录即可保留每个 Skill 的元数据和随附资源。 Skill 源文件位于 `scripts/skills/src/`,最终目录生成到 `assets/skills//`,离线压缩包 由 `pnpm pack:skills` 生成到 `assets/skills/dist/`。没有安装器 CLI,也没有发布 npm 包。 diff --git a/apps/storybook/content/docs/skill/install.mdx b/apps/storybook/content/docs/skill/install.mdx index d06116d..034acb2 100644 --- a/apps/storybook/content/docs/skill/install.mdx +++ b/apps/storybook/content/docs/skill/install.mdx @@ -3,20 +3,21 @@ title: 安装与更新 description: 从仓库或离线包获取中文 Skill,并在更新时保留本地修改 --- -Skill 通过完整目录交付。每个目录中的 `SKILL.md` 是入口,`references/` 提供按需阅读的 -API 和行为说明,`examples/` 提供可复用的 TypeScript 示例。 +Skill 通过完整目录交付。每个目录中的 `SKILL.md` 是入口。按需随附 `references/` 中的 +API 和行为说明,以及 `examples/` 中的 TypeScript 示例。 ## 获取离线包 | 内容 | 下载 | | --- | --- | -| 全部三个 Skill | [kit-skills.tgz](/skills/kit-skills.tgz) | +| 全部 Skill | [kit-skills.tgz](/skills/kit-skills.tgz) | | 组件组合 | [kit-components.tgz](/skills/kit-components.tgz) | | 会话状态与交互 | [use-kit-chat.tgz](/skills/use-kit-chat.tgz) | | 默认与自建后端接入 | [kit-chat-provider.tgz](/skills/kit-chat-provider.tgz) | +| SQLite、MySQL 和 PostgreSQL 接入 | [kit-database.tgz](/skills/kit-database.tgz) | 将压缩包解压到临时目录,确认顶层 Skill 目录及其内容,再复制到当前 coding agent 支持的 -Skill 目录。单个压缩包的顶层目录就是 Skill 名称;全部压缩包包含三个同级目录。 +Skill 目录。单个压缩包的顶层目录就是 Skill 名称;合并包包含所有 Skill 的同级目录。 支持项目级 Skill 的工具应优先按项目安装,具体发现路径以所用工具的文档为准。 例如,工具使用项目级 `.agents/skills/` 时,安装后的结构为: @@ -35,10 +36,11 @@ Skill 目录。单个压缩包的顶层目录就是 Skill 名称;全部压缩 SKILL.md references/ examples/ + kit-database/ + SKILL.md ``` -不要只复制 `SKILL.md`:入口中的相对链接需要同目录下的参考与示例。 -三个 Skill 可以独立安装;跨 Skill 的建议不会替代各自必需的参考内容。 +每个 Skill 都可独立安装。复制完整目录可保留元数据和入口引用的全部资源。 ## 从仓库生成 @@ -89,5 +91,9 @@ Skill 随当前仓库 API 更新。旧版本 Kit 或已修改的 copy-in 组件 编写适配器前先核对上游就绪和完整历史回放的接口合同。 ``` +```text +用 $kit-database 把这个项目接到我已有的 PostgreSQL,验证启动和迁移记录。 +``` + 浏览器中的应用登录令牌与百炼 Provider 凭据不同。自建后端接入始终把百炼 API Key 留在 服务端;下载 Skill 不需要提供凭据。 diff --git a/apps/storybook/content/docs/skill/kit-database.mdx b/apps/storybook/content/docs/skill/kit-database.mdx new file mode 100644 index 0000000..66a915f --- /dev/null +++ b/apps/storybook/content/docs/skill/kit-database.mdx @@ -0,0 +1,16 @@ +--- +title: kit-database +description: 配置 Kit Server 的 SQLite、MySQL 或 PostgreSQL,核对启动迁移与目标库 +--- + +`kit-database` 指导 coding agent 配置 Kit Server 的存储后端。可以直接使用默认 SQLite, +也可以接入已有的 MySQL 或 PostgreSQL。Skill 给出了连接环境变量、目标库权限和启动验证步骤。 + +[下载 Skill](/skills/kit-database.tgz) · [阅读 SKILL.md](/skills/kit-database/SKILL.md) + +按[安装与更新](/docs/skill/install)复制完整目录。使用时告诉 coding agent 选择的数据库 +和希望验证的结果,连接凭据通过项目的本地配置或部署环境提供。 + +```text +用 $kit-database 将 Kit Server 接入我的 MySQL,复用现有配置并核对目标库的迁移记录。 +``` diff --git a/apps/storybook/content/docs/skill/meta.json b/apps/storybook/content/docs/skill/meta.json index 513392b..0c5bffe 100644 --- a/apps/storybook/content/docs/skill/meta.json +++ b/apps/storybook/content/docs/skill/meta.json @@ -1,4 +1,4 @@ { "title": "Skill", - "pages": ["index", "install", "kit-components", "use-kit-chat", "kit-chat-provider"] + "pages": ["index", "install", "kit-components", "use-kit-chat", "kit-chat-provider", "kit-database"] } diff --git a/assets/skills/kit-chat-provider/agents/openai.yaml b/assets/skills/kit-chat-provider/agents/openai.yaml deleted file mode 100644 index fd0d484..0000000 --- a/assets/skills/kit-chat-provider/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Kit 对话后端接入" - short_description: "将 Kit Server 或自建百炼后端接入 Kit 对话,处理历史、订阅和审批" - default_prompt: "用 $kit-chat-provider 将我的百炼后端及原始 SSE 订阅接入 Kit 的 useChat。" diff --git a/assets/skills/kit-components/agents/openai.yaml b/assets/skills/kit-components/agents/openai.yaml deleted file mode 100644 index 62923cb..0000000 --- a/assets/skills/kit-components/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Kit 对话组件" - short_description: "用 Kit 组件搭建会话导航、聊天区与资源侧栏,组合附件和审批界面" - default_prompt: "用 $kit-components 搭建一个会话工作台,包含会话导航、聊天区和 Agent 资源侧栏。" diff --git a/assets/skills/kit-database/SKILL.md b/assets/skills/kit-database/SKILL.md new file mode 100644 index 0000000..8a0b49f --- /dev/null +++ b/assets/skills/kit-database/SKILL.md @@ -0,0 +1,69 @@ +--- +name: kit-database +description: "为 OpenAgentKit 的 Kit Server 选择或配置 SQLite、MySQL 与 PostgreSQL。适用于设置 KIT_DB_DRIVER 和 KIT_DATABASE_URL、初始化目标库、验证启动迁移和排查数据库连接问题。" +--- + +# 接入 Kit Server 数据库 + +Kit Server 每次启动选择一种存储后端。本地开发默认使用 SQLite。已有专用 MySQL 或 +PostgreSQL 实例时,通过服务端配置接入该库。 + +先核对当前项目的 `apps/server/README.md` 和服务进程的配置来源。使用仓库启动命令时, +配置在仓库根目录的 `.env`。部署时可由进程环境提供相同变量。已有配置满足目标时直接复用。 +用户要求切库时,只调整与所选数据库有关的配置项;其余配置照常使用。连接凭据通过本地配置或 +部署环境注入,输出中用占位符表示。 + +## SQLite + +Node.js 24 提供内置的 `node:sqlite`。未配置驱动时自动使用 SQLite。下面是显式配置。 + +```dotenv +KIT_DB_DRIVER=sqlite +KIT_DATA_DIR=.data +``` + +库文件为 `KIT_DATA_DIR/kit.sqlite`,相对数据目录以**服务进程的工作目录**为基准。 +接续已有 SQLite 时,指向现有 `kit.sqlite` 所在目录,确认启动方式变化后仍解析到同一路径。 + +## MySQL + +使用 MySQL 8.4 和 InnoDB。预先准备 Kit 专用数据库与应用账号,确保账号可以在目标库中 +执行建表、建索引、迁移变更和日常读写。 + +```dotenv +KIT_DB_DRIVER=mysql +KIT_DATABASE_URL=mysql://kit_user:password@127.0.0.1:3306/kit +``` + +## PostgreSQL + +预先准备 Kit 专用数据库与应用账号,确保账号可以在连接使用的 schema 中执行建表、 +建索引、迁移变更和日常读写。`pg` 是 `KIT_DB_DRIVER=postgres` 的别名。 + +```dotenv +KIT_DB_DRIVER=postgres +KIT_DATABASE_URL=postgresql://kit_user:password@127.0.0.1:5432/kit +``` + +MySQL 和 PostgreSQL 示例的用户名、密码、地址、端口和库名均按实际配置替换。 +用户名或密码中的 URL 保留字符需要百分号编码。连接 URL 支持 `?ssl=true` 开启 TLS 并 +校验服务端证书。 + +## 启动与验证 + +1. 确认目标库。启动会在空库初始化表结构,在已有库按各自的 `_kit_migrations` 记录补齐待执行迁移。 + 切换后端后,服务使用目标库自己的数据。需要搬迁已有记录时,单独确认源库、目标库和迁移方式。 +2. 从仓库根目录运行 `pnpm start server`。首次运行先执行 `pnpm install`。已有配置的开发启动 + 也可用 `pnpm dev server`。启动时沿用用户当前选择的 Provider 模式。 +3. 从启动日志确认 `db=sqlite`、`db=mysql` 或 `db=postgres`,并使用实际监听端口检查 + 健康接口。默认端口的检查命令如下。 + + ```bash + curl -fsS http://127.0.0.1:8787/healthz + ``` + +4. 需要核对迁移时,在目标库读取 `_kit_migrations`,用完整迁移 ID 核对已应用版本。 + 需要验证业务读写时,通过正常的 Kit 接口在专用测试库写入一条测试数据并读回。 + +启动失败时,按报错核对连接 URL、网络连通性、目标库权限或 TLS 证书。迁移失败时,保留 +目标库和迁移记录,报告失败版本及结构差异,便于后续核对和恢复。 diff --git a/assets/skills/use-kit-chat/agents/openai.yaml b/assets/skills/use-kit-chat/agents/openai.yaml deleted file mode 100644 index 123bf70..0000000 --- a/assets/skills/use-kit-chat/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "接入 Kit 对话" - short_description: "把 React 对话页面接入 Kit,管理会话、消息、附件和工具审批" - default_prompt: "用 $use-kit-chat 将三栏会话页接入我已有的 Provider,串起会话导航、聊天区和 Agent 资源。" diff --git a/docs/adr/0027-skills-source-and-generated-output.md b/docs/adr/0027-skills-source-and-generated-output.md index f626f8b..69cdd76 100644 --- a/docs/adr/0027-skills-source-and-generated-output.md +++ b/docs/adr/0027-skills-source-and-generated-output.md @@ -7,6 +7,10 @@ 生成链路校验入口正文、元数据文案、catalog 说明和手写 Markdown 参考是否包含中文, 并校验链接、API 覆盖、示例和漂移。打包测试验证中文内容原样分发。 +配置类 Skill 可用正文和元数据独立生成。生成器根据实际的 catalog 与示例源生成相应参考。 +Skill 使用通用的 `SKILL.md` 作为入口。生成和打包省略客户端专用的 `agents/openai.yaml`, +取代下文关于生成该文件的约定。 + ## 背景 `packages/skills` 同时承担两种职责:保存英文 Skill 内容,以及提供生成、校验和打包工具。 diff --git a/docs/repository-layout.md b/docs/repository-layout.md index a76ef33..8e036e6 100644 --- a/docs/repository-layout.md +++ b/docs/repository-layout.md @@ -215,18 +215,18 @@ Skill 不是 workspace 包,也不参与应用运行时依赖。人工源与生 ``` scripts/skills/ src// - metadata.json name / description / displayName / shortDescription / defaultPrompt + metadata.json name / description skill.md SKILL.md 正文 - catalog.json 公开 API 到中文用途、文档与示例的映射 - references/ 中文行为说明 - examples/ TS/TSX 示例,含中文注释和文案,参与类型检查并同步到文档站 + catalog.json API Skill 的公开接口索引 + references/ 按需提供中文行为说明 + examples/ 按需提供 TS/TSX 示例,参与类型检查并同步到文档站 generate.mjs 生成、校验与 API 模型入口 pack.mjs 确定性离线打包 tests/ 生成、链接、打包与浏览器边界测试 tsconfig.json 示例类型检查 assets/skills/ - / 生成的最终 Skill:SKILL.md、agents/、references/、examples/ + / 生成的最终 Skill,包含 SKILL.md 和按需生成的 references/、examples/ dist/ 离线 tgz 产物(gitignore) ``` @@ -234,6 +234,7 @@ assets/skills/ 为范围依据,不能只检查 registry 顶层项。内部实现组件不进入公开 API。 - `use-kit-chat` 指导 Hook 与生命周期;`kit-chat-provider` 指导默认及自建百炼后端合同。 三者共用现有公开类型,不复制协议实现、不引入第二套事件模型。 +- `kit-database` 指导 Kit Server 接入 SQLite、MySQL 和 PostgreSQL,依据服务端配置与迁移合同。 - Skill 正文、参考、元数据、示例注释与示例界面文案使用中文;Skill ID、文件名、API 标识符和协议值沿用公开合同。 - `pnpm gen:skills` 从 `scripts/skills/src/` 生成 `assets/skills/`、API 参考与 MDX 示例; diff --git a/scripts/skills/AGENTS.md b/scripts/skills/AGENTS.md index 73b21e1..536a508 100644 --- a/scripts/skills/AGENTS.md +++ b/scripts/skills/AGENTS.md @@ -7,7 +7,7 @@ ## 职责与入口 - `src//metadata.json`、`skill.md`、`catalog.json`、 - `references/`、`examples/`:唯一人工编辑源。 + `references/`、`examples/`:唯一人工编辑源。配置类 Skill 可从正文、元数据和所需参考生成。 - `generate.mjs`、`api-model.mjs`、`validate.mjs`:抽取公开 API、生成与漂移/内容校验。 - `pack.mjs`、`archive.mjs`:离线包与文档站下载准备;`tests/`:生成链路合同。 - `assets/skills//`:被跟踪的最终生成目录;`assets/skills/dist/` 为忽略的离线包。 @@ -16,9 +16,10 @@ ## 不变量 1. Skill 的入口、参考、元数据、示例注释与界面文案使用中文,保留 Skill ID、文件名、API 标识符和协议值。 -2. 最终目录由根命令生成,不手改 `SKILL.md`、OpenAI metadata、API/示例参考、 +2. 最终目录由根命令生成,不手改 `SKILL.md`、API/示例参考、 示例副本或 MDX 的 `skill-example` 标记区。 3. 每个 Skill 可独立复制;内部相对链接不能越出目录,文件键使用可移植的 `/`。 + 离线包和文档站下载共用同一份文件清单,省略客户端专用的 `agents/openai.yaml`。 离线包保持确定性,构建不修补被跟踪的源文件。 4. `kit-components` 覆盖公开组件、静态子组件和 helper,不以 registry 分组代替 API。 示例必须实际调用对应组件或函数,类型和必填项来自公开声明。 @@ -27,10 +28,11 @@ 同一类型经多入口导出时去重,不暴露私有工具。 6. 示例遵循 SDK / UI 边界,不导入上游 SDK 主入口运行时或 internal,不复制状态机或转换器; 未发布依赖必须明确前提,不能把离线示例描述为真实 Cloud 验证。 +7. `kit-database` 指导 Kit Server 选择存储驱动、配置连接和验证启动。配置字段以服务端合同为准。 ## 修改步骤 -1. 先改所属公开 API 或 `src//` 的内容,新增能力同步 catalog 与编译示例。 +1. 先改所属公开 API、配置合同或 `src//` 的内容。新增公开 API 同步 catalog 与编译示例。 2. 运行 `pnpm gen:skills`,检查最终目录及 MDX 示例变更,禁止直接修补产物。 3. 新增复杂流程在隔离临时目录前向试用;按适用协作规则使用独立 agent, 以试用结果改进说明,不引入产品运行时依赖。 diff --git a/scripts/skills/README.md b/scripts/skills/README.md index 2503d4d..8d40405 100644 --- a/scripts/skills/README.md +++ b/scripts/skills/README.md @@ -1,7 +1,8 @@ # scripts/skills — Coding Agent Skill 源与生成器 -这里维护三个面向 coding agent 的中文 Skill:`kit-components`、`use-kit-chat` 和 -`kit-chat-provider`。Skill 不参与应用运行时,也不是 npm 包。 +这里维护面向 coding agent 的中文 Skill。`kit-components`、`use-kit-chat` 和 +`kit-chat-provider` 指导对话集成,`kit-database` 指导 Kit Server 数据库接入。 +Skill 不参与应用运行时,也不是 npm 包。 本文件面向人类读者;维护不变量见 [AGENTS.md](./AGENTS.md)。 @@ -11,7 +12,7 @@ ```text scripts/skills/src// - metadata.json name、description、displayName、shortDescription、defaultPrompt + metadata.json name、description skill.md SKILL.md 正文 catalog.json 公开 API 到中文用途、文档与示例的映射 references/ 人工维护的行为说明 @@ -23,7 +24,6 @@ scripts/skills/src// ```text assets/skills// SKILL.md - agents/openai.yaml references/api.md references/examples.md references/... 从 src 复制 @@ -31,6 +31,7 @@ assets/skills// ``` `assets/skills/dist/` 是离线包产物,已 gitignore。 +离线包与文档站下载使用同一份发布文件清单。生成和打包均省略客户端专用的 `agents/openai.yaml`。 ## 常用命令 @@ -50,8 +51,8 @@ pnpm pack:skills # 生成 assets/skills/dist/*.tgz - 新增公开组件、子组件或 SDK 入口时,先更新 `catalog.json`,再补示例并运行 `pnpm gen:skills`。 - 修改行为说明时,编辑 `src//references/`;生成器只复制,不覆盖人工正文。 -- 新增 Skill 时,在 `src/` 下建立完整目录并补齐 metadata、catalog、references 和 examples; - 生成器和文档站会按目录自动发现。 +- 新增 Skill 时在 `src/` 下提供 metadata 和正文。涉及公开 API 时补齐 catalog 与编译示例, + 按需添加参考内容。生成器按目录发现 Skill,文档站导航由 `content/docs/skill/meta.json` 维护。 - 生成、检查和打包都会校验元数据文案、catalog 用途和备注、入口正文以及手写 Markdown 参考是否包含中文。 示例注释与界面文案在 TS/TSX 源文件中维护。 - API 签名、Props 和类型以公开 TypeScript 导出为准;中文用途与约束以 catalog 和 diff --git a/scripts/skills/generate.mjs b/scripts/skills/generate.mjs index cbaa49d..0c0a35d 100644 --- a/scripts/skills/generate.mjs +++ b/scripts/skills/generate.mjs @@ -104,9 +104,7 @@ function renderApi(name, entries, model, root, renderedDocs) { return `${lines.join("\n").trim()}\n`; } -function renderExamples(root, name) { - const directory = skillSourceRoot(root, name); - const examples = filesUnder(resolve(directory, "examples")).filter((file) => /\.tsx?$/.test(file)); +function renderExamples(directory, examples) { return [ "# 可编译示例", "", @@ -128,16 +126,6 @@ function renderSkill(metadata, body) { return `---\nname: ${metadata.name}\ndescription: ${JSON.stringify(description)}\n---\n\n${body.trim()}\n`; } -function renderOpenAi(metadata) { - return [ - "interface:", - ` display_name: ${JSON.stringify(metadata.displayName)}`, - ` short_description: ${JSON.stringify(metadata.shortDescription)}`, - ` default_prompt: ${JSON.stringify(metadata.defaultPrompt)}`, - "", - ].join("\n"); -} - const exampleMarker = /\{\/\* skill-example: ([\w./-]+) \*\/\}[\s\S]*?\{\/\* \/skill-example \*\/\}/g; export function renderDocsExamples(text, root) { @@ -154,7 +142,7 @@ export function renderDocsExamples(text, root) { export function readMetadata(root, name) { const path = resolve(skillSourceRoot(root, name), "metadata.json"); const metadata = JSON.parse(readFileSync(path, "utf8")); - for (const key of ["name", "description", "displayName", "shortDescription", "defaultPrompt"]) { + for (const key of ["name", "description"]) { if (typeof metadata[key] !== "string" || !metadata[key].trim()) throw new Error(`Missing metadata.${key} for ${name}`); if (key !== "name") validateChineseText(metadata[key], `${portablePath(relative(root, path))}#${key}`); @@ -194,9 +182,6 @@ function buildDocsOutputs(root) { function buildSkillOutputs(root, name, model, renderedDocs) { const source = skillSourceRoot(root, name); const metadata = readMetadata(root, name); - const entries = readCatalog(root, name); - if (name === "kit-components") assertChatUiCoverage(model.chatUiCallableNames(), entries); - for (const entry of entries) validateEntry(root, name, entry); const bodyPath = resolve(source, "skill.md"); const body = readFileSync(bodyPath, "utf8"); @@ -204,19 +189,25 @@ function buildSkillOutputs(root, name, model, renderedDocs) { const skillFiles = new Map(); skillFiles.set("SKILL.md", renderSkill(metadata, body)); - 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 of filesUnder(resolve(source, "references"))) { + if (name === "kit-components" || existsSync(resolve(source, "catalog.json"))) { + const entries = readCatalog(root, name); + if (name === "kit-components") assertChatUiCoverage(model.chatUiCallableNames(), entries); + for (const entry of entries) validateEntry(root, name, entry); + skillFiles.set("references/api.md", renderApi(name, entries, model, root, renderedDocs)); + } + const references = resolve(source, "references"); + const examples = resolve(source, "examples"); + const exampleFiles = existsSync(examples) ? filesUnder(examples) : []; + const typedExamples = exampleFiles.filter((file) => /\.tsx?$/.test(file)); + if (typedExamples.length) { + skillFiles.set("references/examples.md", renderExamples(source, typedExamples)); + } + for (const file of existsSync(references) ? filesUnder(references) : []) { const text = readFileSync(file, "utf8"); if (file.endsWith(".md")) validateChineseMarkdown(text, portablePath(relative(root, file))); skillFiles.set(portablePath(relative(source, file)), text); } - for (const file of filesUnder(resolve(skillSourceRoot(root, name), "examples"))) - skillFiles.set( - `examples/${portablePath(relative(resolve(skillSourceRoot(root, name), "examples"), file))}`, - readFileSync(file, "utf8"), - ); + for (const file of exampleFiles) skillFiles.set(portablePath(relative(source, file)), readFileSync(file, "utf8")); validateSkillMap(name, skillFiles); return skillFiles; diff --git a/scripts/skills/pack.mjs b/scripts/skills/pack.mjs index 633e7ff..c659406 100644 --- a/scripts/skills/pack.mjs +++ b/scripts/skills/pack.mjs @@ -1,22 +1,26 @@ import { cpSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"; -import { relative, resolve } from "node:path"; +import { dirname, relative, resolve } from "node:path"; import { fileURLToPath } from "node:url"; import { createArchive } from "./archive.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 }); - mkdirSync(output, { recursive: true }); const names = skillNames(root); - const allFiles = []; - for (const name of names) { + const bundles = names.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, - })); - allFiles.push(...files); + const files = filesUnder(directory).map((source) => { + const path = portablePath(relative(directory, source)); + if (/^agents\/openai\.ya?ml$/i.test(path)) + throw new Error(`Skill ${name} 包含客户端专用文件 ${path},无法打包。`); + return { path: `${name}/${path}`, source, content: readFileSync(source), mtimeMs: statSync(source).mtimeMs }; + }); + return { name, files }; + }); + const allFiles = bundles.flatMap(({ files }) => files); + mkdirSync(output, { recursive: true }); + for (const { name, files } of bundles) { writeFileSync(resolve(output, `${name}.tgz`), createArchive(files)); } writeFileSync(resolve(output, "kit-skills.tgz"), createArchive(allFiles)); @@ -24,11 +28,11 @@ 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), { - recursive: true, - preserveTimestamps: true, - }); + for (const { path, source } of allFiles) { + const target = resolve(publicDirectory, path); + mkdirSync(dirname(target), { recursive: true }); + cpSync(source, target, { preserveTimestamps: true }); + } for (const name of [...names, "kit-skills"]) cpSync(resolve(output, `${name}.tgz`), resolve(publicDirectory, `${name}.tgz`)); } diff --git a/scripts/skills/src/kit-chat-provider/metadata.json b/scripts/skills/src/kit-chat-provider/metadata.json index 8b64b8e..8363693 100644 --- a/scripts/skills/src/kit-chat-provider/metadata.json +++ b/scripts/skills/src/kit-chat-provider/metadata.json @@ -1,7 +1,4 @@ { "name": "kit-chat-provider", - "description": "通过公开的 Request 和 createSessionEventChatProvider 配置接入 Kit Server 或自建百炼后端,也可以用 createBailianChatProvider 接入百炼原始 SSE。适用于处理订阅就绪、历史回放、取消请求和工具审批。", - "displayName": "Kit 对话后端接入", - "shortDescription": "将 Kit Server 或自建百炼后端接入 Kit 对话,处理历史、订阅和审批", - "defaultPrompt": "用 $kit-chat-provider 将我的百炼后端及原始 SSE 订阅接入 Kit 的 useChat。" + "description": "通过公开的 Request 和 createSessionEventChatProvider 配置接入 Kit Server 或自建百炼后端,也可以用 createBailianChatProvider 接入百炼原始 SSE。适用于处理订阅就绪、历史回放、取消请求和工具审批。" } diff --git a/scripts/skills/src/kit-components/metadata.json b/scripts/skills/src/kit-components/metadata.json index 3c61a86..f2820ca 100644 --- a/scripts/skills/src/kit-components/metadata.json +++ b/scripts/skills/src/kit-components/metadata.json @@ -1,7 +1,4 @@ { "name": "kit-components", - "description": "用 OpenAgentKit 的 React 组件搭建对话界面,包括带会话导航、聊天区和 Agent 资源的完整页面。适用于组件选型、布局、消息渲染、附件输入和工具审批界面。", - "displayName": "Kit 对话组件", - "shortDescription": "用 Kit 组件搭建会话导航、聊天区与资源侧栏,组合附件和审批界面", - "defaultPrompt": "用 $kit-components 搭建一个会话工作台,包含会话导航、聊天区和 Agent 资源侧栏。" + "description": "用 OpenAgentKit 的 React 组件搭建对话界面,包括带会话导航、聊天区和 Agent 资源的完整页面。适用于组件选型、布局、消息渲染、附件输入和工具审批界面。" } diff --git a/scripts/skills/src/kit-database/metadata.json b/scripts/skills/src/kit-database/metadata.json new file mode 100644 index 0000000..f67cced --- /dev/null +++ b/scripts/skills/src/kit-database/metadata.json @@ -0,0 +1,4 @@ +{ + "name": "kit-database", + "description": "为 OpenAgentKit 的 Kit Server 选择或配置 SQLite、MySQL 与 PostgreSQL。适用于设置 KIT_DB_DRIVER 和 KIT_DATABASE_URL、初始化目标库、验证启动迁移和排查数据库连接问题。" +} diff --git a/scripts/skills/src/kit-database/skill.md b/scripts/skills/src/kit-database/skill.md new file mode 100644 index 0000000..37a72f9 --- /dev/null +++ b/scripts/skills/src/kit-database/skill.md @@ -0,0 +1,64 @@ +# 接入 Kit Server 数据库 + +Kit Server 每次启动选择一种存储后端。本地开发默认使用 SQLite。已有专用 MySQL 或 +PostgreSQL 实例时,通过服务端配置接入该库。 + +先核对当前项目的 `apps/server/README.md` 和服务进程的配置来源。使用仓库启动命令时, +配置在仓库根目录的 `.env`。部署时可由进程环境提供相同变量。已有配置满足目标时直接复用。 +用户要求切库时,只调整与所选数据库有关的配置项;其余配置照常使用。连接凭据通过本地配置或 +部署环境注入,输出中用占位符表示。 + +## SQLite + +Node.js 24 提供内置的 `node:sqlite`。未配置驱动时自动使用 SQLite。下面是显式配置。 + +```dotenv +KIT_DB_DRIVER=sqlite +KIT_DATA_DIR=.data +``` + +库文件为 `KIT_DATA_DIR/kit.sqlite`,相对数据目录以**服务进程的工作目录**为基准。 +接续已有 SQLite 时,指向现有 `kit.sqlite` 所在目录,确认启动方式变化后仍解析到同一路径。 + +## MySQL + +使用 MySQL 8.4 和 InnoDB。预先准备 Kit 专用数据库与应用账号,确保账号可以在目标库中 +执行建表、建索引、迁移变更和日常读写。 + +```dotenv +KIT_DB_DRIVER=mysql +KIT_DATABASE_URL=mysql://kit_user:password@127.0.0.1:3306/kit +``` + +## PostgreSQL + +预先准备 Kit 专用数据库与应用账号,确保账号可以在连接使用的 schema 中执行建表、 +建索引、迁移变更和日常读写。`pg` 是 `KIT_DB_DRIVER=postgres` 的别名。 + +```dotenv +KIT_DB_DRIVER=postgres +KIT_DATABASE_URL=postgresql://kit_user:password@127.0.0.1:5432/kit +``` + +MySQL 和 PostgreSQL 示例的用户名、密码、地址、端口和库名均按实际配置替换。 +用户名或密码中的 URL 保留字符需要百分号编码。连接 URL 支持 `?ssl=true` 开启 TLS 并 +校验服务端证书。 + +## 启动与验证 + +1. 确认目标库。启动会在空库初始化表结构,在已有库按各自的 `_kit_migrations` 记录补齐待执行迁移。 + 切换后端后,服务使用目标库自己的数据。需要搬迁已有记录时,单独确认源库、目标库和迁移方式。 +2. 从仓库根目录运行 `pnpm start server`。首次运行先执行 `pnpm install`。已有配置的开发启动 + 也可用 `pnpm dev server`。启动时沿用用户当前选择的 Provider 模式。 +3. 从启动日志确认 `db=sqlite`、`db=mysql` 或 `db=postgres`,并使用实际监听端口检查 + 健康接口。默认端口的检查命令如下。 + + ```bash + curl -fsS http://127.0.0.1:8787/healthz + ``` + +4. 需要核对迁移时,在目标库读取 `_kit_migrations`,用完整迁移 ID 核对已应用版本。 + 需要验证业务读写时,通过正常的 Kit 接口在专用测试库写入一条测试数据并读回。 + +启动失败时,按报错核对连接 URL、网络连通性、目标库权限或 TLS 证书。迁移失败时,保留 +目标库和迁移记录,报告失败版本及结构差异,便于后续核对和恢复。 diff --git a/scripts/skills/src/use-kit-chat/metadata.json b/scripts/skills/src/use-kit-chat/metadata.json index 1abdc08..e83ee89 100644 --- a/scripts/skills/src/use-kit-chat/metadata.json +++ b/scripts/skills/src/use-kit-chat/metadata.json @@ -1,7 +1,4 @@ { "name": "use-kit-chat", - "description": "将 React 对话页面接入 OpenAgentKit 的 useChat,串起会话目录、消息与输入框、Agent 资源和产物交互。适用于 Kit Server 或已有的自定义 ChatProvider。", - "displayName": "接入 Kit 对话", - "shortDescription": "把 React 对话页面接入 Kit,管理会话、消息、附件和工具审批", - "defaultPrompt": "用 $use-kit-chat 将三栏会话页接入我已有的 Provider,串起会话导航、聊天区和 Agent 资源。" + "description": "将 React 对话页面接入 OpenAgentKit 的 useChat,串起会话目录、消息与输入框、Agent 资源和产物交互。适用于 Kit Server 或已有的自定义 ChatProvider。" } diff --git a/scripts/skills/tests/generate.test.mjs b/scripts/skills/tests/generate.test.mjs index 3f0cdd0..ce2ba67 100644 --- a/scripts/skills/tests/generate.test.mjs +++ b/scripts/skills/tests/generate.test.mjs @@ -27,6 +27,7 @@ function writeSkill(root, name, body = "# 接入示例\n\n使用公开 API。\n" JSON.stringify({ name, description: "公开 API 接入示例", + // 旧版客户端字段用于验证通用 Skill 的生成。 displayName: "接入示例", shortDescription: "通过公开 API 将会话页面接入后端,并处理历史加载和工具审批", defaultPrompt: `使用 $${name} 接入示例。`, @@ -127,6 +128,7 @@ test("packed Skills are reproducible and preserve source modification times", () for (const name of [...names, "kit-skills"]) { const archive = resolve(first, `${name}.tgz`); assert.deepEqual(readFileSync(archive), readFileSync(resolve(second, `${name}.tgz`))); + assert.doesNotMatch(execFileSync("tar", ["-tzf", archive], { encoding: "utf8" }), /\/agents\/openai\.ya?ml$/im); const extracted = resolve(directory, name); mkdirSync(extracted); execFileSync("tar", ["-xzf", archive, "-C", extracted]); @@ -233,21 +235,30 @@ test("one generation synchronizes SDK and component examples with their source f } }); -test("fixture repository generates a complete final Skill directory", () => { +test("fixture repository generates API Skills and a configuration-only Skill", () => { const directory = mkdtempSync(resolve(tmpdir(), "kit-skills-minimal-")); try { - for (const name of ["use-kit-chat", "kit-chat-provider"]) writeSkill(directory, name); + const apiSkills = ["use-kit-chat", "kit-chat-provider"]; + for (const name of apiSkills) writeSkill(directory, name); + cpSync(skillSourceRoot(repositoryRoot, "kit-database"), skillSourceRoot(directory, "kit-database"), { + recursive: true, + }); mkdirSync(resolve(directory, "apps/storybook/content/docs/skill"), { recursive: true }); mkdirSync(resolve(directory, "apps/storybook/content/docs/sdk"), { recursive: true }); mkdirSync(resolve(directory, "apps/storybook/content/docs/components"), { recursive: true }); const outputs = buildOutputs(directory, createApiModel(repositoryRoot)); - for (const name of skillNames(directory)) { + for (const name of apiSkills) { const root = skillOutputRoot(directory, name); assert.match(outputs.get(resolve(root, "SKILL.md")), /公开 API 接入示例/); - assert.match(outputs.get(resolve(root, "agents/openai.yaml")), /display_name: "接入示例"/); + assert.equal(outputs.has(resolve(root, "agents/openai.yaml")), false); assert.match(outputs.get(resolve(root, "references/api.md")), /^# API 参考\n/); assert.match(outputs.get(resolve(root, "references/examples.md")), /\[源文件\]\(\.\.\/examples\/fixture\.ts\)/); } + const database = skillOutputRoot(directory, "kit-database"); + assert.match(outputs.get(resolve(database, "SKILL.md")), /^---\nname: kit-database\n/); + assert.equal(outputs.has(resolve(database, "agents/openai.yaml")), false); + assert.equal(outputs.has(resolve(database, "references/api.md")), false); + assert.equal(outputs.has(resolve(database, "references/examples.md")), false); } finally { rmSync(directory, { recursive: true, force: true }); } @@ -279,11 +290,11 @@ test("generation rejects untranslated authored prose before it can reach generat assert.doesNotThrow(() => buildOutputs(directory, model)); const failures = [ - ...["description", "displayName", "shortDescription", "defaultPrompt"].map((key) => [ + [ "metadata.json", - JSON.stringify({ ...metadata, [key]: "Integration example" }), - `metadata.json#${key}`, - ]), + JSON.stringify({ ...metadata, description: "Integration example" }), + "metadata.json#description", + ], [ "skill.md", '# Getting started\r\n\r\nUse `中文` in the request.\r\n\r\n~~~ts\r\nconst label = "中文";\r\n~~~\r\n',