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',