Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)。

## 执行红线

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,不提供根聚合入口。
Expand Down
3 changes: 3 additions & 0 deletions apps/server/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 生成类型。
Expand Down
2 changes: 2 additions & 0 deletions apps/server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` 或服务端进程环境中设置以下一组变量,重启后会在所选库中初始化表结构。

Expand Down
14 changes: 8 additions & 6 deletions apps/storybook/content/docs/skill/index.mdx
Original file line number Diff line number Diff line change
@@ -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` 和业务后端完成。
Expand All @@ -17,22 +17,24 @@ Skill 是写代码时读取的指南,不是运行时插件,也不会替应
<Card title="kit-components" description="覆盖所有已实现的公开组件、子组件和兼容别名,指导 UI 组合与样式接入。" href="/docs/skill/kit-components" />
<Card title="use-kit-chat" description="接入 useChat,处理连接、发送、停止、会话切换以及工具批准与拒绝。" href="/docs/skill/use-kit-chat" />
<Card title="kit-chat-provider" description="使用默认 Kit Server,或把自建百炼后端的已转换事件、原始 SSE 接入 Provider。" href="/docs/skill/kit-chat-provider" />
<Card title="kit-database" description="配置 Kit Server 的 SQLite、MySQL 或 PostgreSQL,检查连接和启动迁移。" href="/docs/skill/kit-database" />
</Cards>

| 想完成的工作 | 从哪个 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/<name>/`,离线压缩包
由 `pnpm pack:skills` 生成到 `assets/skills/dist/`。没有安装器 CLI,也没有发布 npm 包。
Expand Down
18 changes: 12 additions & 6 deletions apps/storybook/content/docs/skill/install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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/` 时,安装后的结构为:
Expand All @@ -35,10 +36,11 @@ Skill 目录。单个压缩包的顶层目录就是 Skill 名称;全部压缩
SKILL.md
references/
examples/
kit-database/
SKILL.md
```

不要只复制 `SKILL.md`:入口中的相对链接需要同目录下的参考与示例。
三个 Skill 可以独立安装;跨 Skill 的建议不会替代各自必需的参考内容。
每个 Skill 都可独立安装。复制完整目录可保留元数据和入口引用的全部资源。

## 从仓库生成

Expand Down Expand Up @@ -89,5 +91,9 @@ Skill 随当前仓库 API 更新。旧版本 Kit 或已修改的 copy-in 组件
编写适配器前先核对上游就绪和完整历史回放的接口合同。
```

```text
用 $kit-database 把这个项目接到我已有的 PostgreSQL,验证启动和迁移记录。
```

浏览器中的应用登录令牌与百炼 Provider 凭据不同。自建后端接入始终把百炼 API Key 留在
服务端;下载 Skill 不需要提供凭据。
16 changes: 16 additions & 0 deletions apps/storybook/content/docs/skill/kit-database.mdx
Original file line number Diff line number Diff line change
@@ -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,复用现有配置并核对目标库的迁移记录。
```
2 changes: 1 addition & 1 deletion apps/storybook/content/docs/skill/meta.json
Original file line number Diff line number Diff line change
@@ -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"]
}
4 changes: 0 additions & 4 deletions assets/skills/kit-chat-provider/agents/openai.yaml

This file was deleted.

4 changes: 0 additions & 4 deletions assets/skills/kit-components/agents/openai.yaml

This file was deleted.

69 changes: 69 additions & 0 deletions assets/skills/kit-database/SKILL.md
Original file line number Diff line number Diff line change
@@ -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 证书。迁移失败时,保留
目标库和迁移记录,报告失败版本及结构差异,便于后续核对和恢复。
4 changes: 0 additions & 4 deletions assets/skills/use-kit-chat/agents/openai.yaml

This file was deleted.

4 changes: 4 additions & 0 deletions docs/adr/0027-skills-source-and-generated-output.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@
生成链路校验入口正文、元数据文案、catalog 说明和手写 Markdown 参考是否包含中文,
并校验链接、API 覆盖、示例和漂移。打包测试验证中文内容原样分发。

配置类 Skill 可用正文和元数据独立生成。生成器根据实际的 catalog 与示例源生成相应参考。
Skill 使用通用的 `SKILL.md` 作为入口。生成和打包省略客户端专用的 `agents/openai.yaml`,
取代下文关于生成该文件的约定。

## 背景

`packages/skills` 同时承担两种职责:保存英文 Skill 内容,以及提供生成、校验和打包工具。
Expand Down
11 changes: 6 additions & 5 deletions docs/repository-layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,25 +215,26 @@ Skill 不是 workspace 包,也不参与应用运行时依赖。人工源与生
```
scripts/skills/
src/<skill-name>/
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-name>/ 生成的最终 Skill:SKILL.md、agents/、references/、examples/
<skill-name>/ 生成的最终 Skill,包含 SKILL.md 和按需生成的 references/、examples/
dist/ 离线 tgz 产物(gitignore)
```

- `kit-components` 覆盖 `kit-chat-ui` 全部公开组件、静态子组件与兼容别名;以公开 barrel
为范围依据,不能只检查 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 示例;
Expand Down
8 changes: 5 additions & 3 deletions scripts/skills/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
## 职责与入口

- `src/<name>/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/<name>/`:被跟踪的最终生成目录;`assets/skills/dist/` 为忽略的离线包。
Expand All @@ -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。
示例必须实际调用对应组件或函数,类型和必填项来自公开声明。
Expand All @@ -27,10 +28,11 @@
同一类型经多入口导出时去重,不暴露私有工具。
6. 示例遵循 SDK / UI 边界,不导入上游 SDK 主入口运行时或 internal,不复制状态机或转换器;
未发布依赖必须明确前提,不能把离线示例描述为真实 Cloud 验证。
7. `kit-database` 指导 Kit Server 选择存储驱动、配置连接和验证启动。配置字段以服务端合同为准。

## 修改步骤

1. 先改所属公开 API 或 `src/<name>/` 的内容,新增能力同步 catalog 与编译示例。
1. 先改所属公开 API、配置合同或 `src/<name>/` 的内容。新增公开 API 同步 catalog 与编译示例。
2. 运行 `pnpm gen:skills`,检查最终目录及 MDX 示例变更,禁止直接修补产物。
3. 新增复杂流程在隔离临时目录前向试用;按适用协作规则使用独立 agent,
以试用结果改进说明,不引入产品运行时依赖。
Expand Down
Loading