用途
该技能用于在 Chat SDK 的适配器目录与文档中登记一个第三方适配器(厂商官方或社区)。它不用于构建第一方的 packages/adapter-* 包。
在撰写任何文字之前,必须加载 technical-writer 技能(../technical-writer/SKILL.md):包括文档页、frontmatter 的 tagline 与 description、changeset、提交信息以及 PR 描述,都需遵循其编辑规范,并与下方的来源规则一并遵守。
信息来源:不得编造
需要向用户索取:
- 其适配器的 GitHub 仓库 URL。
- 其文档或 README。
阅读以上两者。写入目录和文档的所有内容都必须直接来自这些来源或用户,不得假设或猜测任何信息:
- packageName:从仓库的 package.json 中原样读取。
- 工厂导出(如 createFooAdapter):从包的导出/源码读取,不要根据显示名称猜测。
- type(platform 或 state)、环境变量、功能矩阵:以代码和 README 实际记录的内容为准。
- 安装与使用片段:取自 README,不要编写适配器可能并不支持的示例代码。
如果仓库或 README 中没有说明清楚,应停下并询问用户,而不是自行填写。存疑时询问。
选择 slug(kebab-case),并用 ls apps/docs/content/adapters/*/ 确认尚未被占用。
层级选择
- community:在文档中列出。在 @chat-adapter/catalog 中使用 CommunityAdapter 条目(仅列表元数据与能力),无 scaffold spec。
- vendor-official:维护/认可状态的适配器。使用完整的 CatalogAdapter 条目,含 setup 元数据(工厂导出、peer 依赖、环境变量),配套的 create-chat-sdk scaffold-spec 条目,以及 changeset。Frontmatter 增加 vendorOfficial: true 和 author。
需要改动的文件
其中 <tier> 为 vendor-official 或 community。
- apps/docs/content/adapters/<tier>/<slug>.mdx:文档页。平台适配器从 assets/adapter.mdx 开始,状态适配器从 assets/adapter-state.mdx 开始,并遵循 references/page-layout.md 中的章节顺序与名称。文件名主干必须等于 frontmatter 的 slug 字段,且页面必须渲染 <FeatureSupport />。
- apps/docs/content/adapters/<tier>/meta.json:把 "<slug>" 加入 pages 数组。
- packages/catalog/src/adapters/<tier>/<slug>.ts:目录条目,包含 name、slug、type、group、description、packageName、author、readme(适配器源码文件夹的 GitHub tree URL,固定到某个 commit 或 tag;文档页会从中获取 README,并以“View source”链接到它)和 features(文档页渲染的能力矩阵)。可复制同文件夹中的相邻文件。然后在 packages/catalog/src/adapters/index.ts 中注册:community 用 COMMUNITY_ADAPTERS,vendor-official 用 ADAPTERS。参见 packages/catalog/AGENTS.md。
vendor-official 还需:
- 目录条目中的 setup 字段:factoryExport、peerDeps、可选的 importPath 和 env。复用 packages/catalog/src/env.ts 中的 env/secretEnv/urlEnv 辅助函数;没有环境变量时使用 env: { notes: "…" }。
- packages/create-chat-sdk/src/catalog/scaffold-spec.ts:添加匹配的 "<slug>": { invocation: … } 条目,参照类似适配器编写。这是必需的注册步骤,而非行为变更:该对象为 satisfies Record<AdapterSlug, …>,因此每个目录 slug 都必须有一个对应条目,否则 create-chat-sdk 无法通过类型检查。
- .changeset/<slug>-adapter.md:"@chat-adapter/catalog": patch 加 "create-chat-sdk": patch,一行说明此次新增。社区列表也会随已发布的 catalog 一同发布,因此也需为其添加 "@chat-adapter/catalog": patch changeset。
测试强制的不变量
- 文档与目录一致:每个适配器 MDX 页面在匹配的 group 中都有目录条目,每个目录条目也都有页面。vendor-official 条目放入 ADAPTERS,community 条目放入 COMMUNITY_ADAPTERS。这是社区适配器跳过第 4、5 步的原因。
- peerDeps 与 PackageInstall 一致:目录条目的 peerDeps(排序后)必须与 MDX 中 <PackageInstall package="…" /> 的额外包完全一致,去除适配器自身的 packageName、chat 以及任何 @chat-adapter/state-* 之后。最简单的做法是 peerDeps: [],在 PackageInstall 中只安装 <packageName> chat(外加一个状态适配器),其他导入放在围栏代码块中。
- 字段一致:packageName、type 以及 author(在 frontmatter 中设置时)必须在 MDX frontmatter 与目录条目之间保持一致。
- 能力保存在目录中:frontmatter 不得声明 features;<FeatureSupport /> 从目录条目读取它们。只允许 PLATFORM_FEATURE_CATEGORIES 或 STATE_FEATURE_CATEGORIES(与适配器 type 匹配)中的键。
- 必需的 frontmatter:title、description、packageName、slug、tagline、type(platform | state)、mdxBody: true、community: true(vendor-official 另加 vendorOfficial: true 和 author)。
验证
pnpm --filter @chat-adapter/catalog build # regenerate the catalog the tests import
pnpm --filter @chat-adapter/catalog test
pnpm --filter @chat-adapter/integration-tests test
pnpm --filter create-chat-sdk typecheck # vendor-official only
pnpm check && pnpm konsistent
资源
- 人工指南(vendor-official):apps/docs/content/docs/contributing/vendor-official.mdx
- 人工指南(社区列表):apps/docs/content/docs/contributing/publishing.mdx
- MDX 模板:assets/adapter.mdx(平台)与 assets/adapter-state.mdx(状态)
- 页面布局与章节名称:references/page-layout.md
- 写作规范(必需):technical-writer 技能(../technical-writer/SKILL.md)
- 目录约定:packages/catalog/AGENTS.md
- 可复制示例:apps/docs/content/adapters/vendor-official/ 与 apps/docs/content/adapters/community/