add-adapter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add a catalog adapter (vendor-official or community)

添加入目录的适配器（厂商官方或社区版）

Use this to list a third-party adapter in the Chat SDK catalog and docs. It is not for building a first-party

packages/adapter-*

package.

本指南用于在Chat SDK目录和文档中列出第三方适配器，不适用于构建第一方

packages/adapter-*

包。

Gather the source — never invent details

收集源信息——切勿编造细节

Ask the user for:

Their adapter's GitHub repository URL.
Their docs or README.

Read both. Everything you write into the catalog and docs must come directly from those sources or from the user. Do not assume or guess any information:

packageName
— read it from the repo's
```
package.json
```
, verbatim.
Factory export (e.g.
```
createFooAdapter
```
) — read it from the package's exports/source. Do not guess it from the display name.
type
(
```
platform
```
or
```
state
```
), env vars, and the feature matrix — base these on what the code and README actually document.
Install and usage snippets — take them from the README; do not write example code the adapter may not support.

If the repo or README does not make something clear, stop and ask the user rather than filling it in. When in doubt, ask.

Choose the

slug

(kebab-case) and confirm it is not already taken:

ls apps/docs/content/adapters/*/

向用户索要：

其适配器的GitHub仓库URL。
其文档或README。

阅读上述两者。你写入目录和文档的所有内容必须直接来自这些来源或用户提供的信息。不得假设或猜测任何信息：

packageName
— 从仓库的
```
package.json
```
中读取，完全照搬。
工厂导出（例如
```
createFooAdapter
```
）——从包的导出/源码中读取。不要根据显示名称猜测。
type
（
```
platform
```
或
```
state
```
）、环境变量和功能矩阵——基于代码和README实际记录的内容来确定。
安装和使用代码片段——从README中提取；不要编写适配器可能不支持的示例代码。

如果仓库或README中有不明确的地方，停止操作并询问用户，而不是自行填充内容。如有疑问，务必询问。

选择

slug

（短横线命名法，kebab-case）并确认尚未被占用：

ls apps/docs/content/adapters/*/

。

Pick the tier

选择层级

community — listed in the docs only. No
```
chat/adapters
```
catalog entry, no changeset.
vendor-official — a maintained/blessed adapter. Everything community has, plus a
```
chat/adapters
```
catalog entry, a matching
```
create-chat-sdk
```
scaffold-spec entry, and a changeset. Frontmatter adds
```
vendorOfficial: true
```
and
```
author
```
.

community（社区版） — 仅在文档中列出。无需添加
```
chat/adapters
```
目录条目和变更记录。
vendor-official（厂商官方版） — 经过维护/认证的适配器。包含社区版的所有内容，另外还需添加
```
chat/adapters
```
目录条目、匹配的
```
create-chat-sdk
```
脚手架规范条目以及变更记录。页面前置元数据需添加
```
vendorOfficial: true
```
和
```
author
```
字段。

Files to change

需要修改的文件

<tier>

vendor-official

community

apps/docs/content/adapters/<tier>/<slug>.mdx
— the docs page. Start from assets/adapter.mdx. The filename basename must equal the
```
slug
```
frontmatter field, and the page must render
```
<FeatureSupport />
```
.

apps/docs/content/adapters/<tier>/meta.json
— add

"<slug>"

to the

pages

array.

apps/docs/adapters.json
— add a registry entry:

name

slug

type

community: true

description

packageName

author

readme

(the GitHub URL). Add

vendorOfficial: true

for vendor-official.

packages/integration-tests/src/docs-adapters.test.ts
— add

"<slug>"

to the hardcoded expected list for its tier.

packages/integration-tests/src/documentation-test-utils.ts
— add the
```
packageName
```
to
```
VALID_DOC_PACKAGES
```
, plus every import specifier used in the MDX code blocks (subpaths count separately).

Vendor-official also:

packages/chat/src/adapters/index.ts
— add an

ADAPTERS

entry with

group: "vendor-official"

. Reuse the

env

secretEnv

urlEnv

helpers; use

env: { notes: "…" }

when there are no env vars. See

packages/chat/src/adapters/AGENTS.md

packages/create-chat-sdk/src/catalog/scaffold-spec.ts
— add a matching
```
"<slug>": { invocation: … }
```
entry, modeled on a similar adapter. This is a required registration step, not a behavior change: the object is
```
satisfies Record<AdapterSlug, …>
```
, so every catalog slug must have one or
```
create-chat-sdk
```
fails to type-check.

.changeset/<slug>-adapter.md
—

"chat": patch

"create-chat-sdk": patch

, one line describing the addition.

<tier>

为

vendor-official

或

community

。

apps/docs/content/adapters/<tier>/<slug>.mdx
— 文档页面。从assets/adapter.mdx开始创建。文件名的基础名必须与前置元数据中的
```
slug
```
字段一致，且页面必须渲染
```
<FeatureSupport />
```
组件。

apps/docs/content/adapters/<tier>/meta.json
— 在

pages

数组中添加

"<slug>"

。

apps/docs/adapters.json
— 添加一条注册表条目：包含
```
name
```
、
```
slug
```
、
```
type
```
、
```
community: true
```
、
```
description
```
、
```
packageName
```
、
```
author
```
、
```
readme
```
（GitHub URL）。厂商官方版需添加
```
vendorOfficial: true
```
。

packages/integration-tests/src/docs-adapters.test.ts
— 在对应层级的硬编码预期列表中添加

"<slug>"

。

packages/integration-tests/src/documentation-test-utils.ts
— 将
```
packageName
```
添加到
```
VALID_DOC_PACKAGES
```
中，同时添加MDX代码块中使用的所有导入标识符（子路径需单独计数）。

厂商官方版额外步骤：

packages/chat/src/adapters/index.ts
— 添加一条

ADAPTERS

条目，设置

group: "vendor-official"

。复用

env

secretEnv

urlEnv

工具函数；当没有环境变量时，使用

env: { notes: "…" }

。参考

packages/chat/src/adapters/AGENTS.md

。

packages/create-chat-sdk/src/catalog/scaffold-spec.ts
— 添加匹配的
```
"<slug>": { invocation: … }
```
条目，参考同类适配器的写法。这是必填的注册步骤，不属于行为变更：该对象需满足
```
Record<AdapterSlug, …>
```
类型约束，因此每个目录中的slug都必须对应一条条目，否则
```
create-chat-sdk
```
会类型检查失败。

.changeset/<slug>-adapter.md
— 写入

"chat": patch

"create-chat-sdk": patch

，用一行文字描述本次添加操作。

Invariants the tests enforce

测试强制执行的约束

Registry ↔ catalog parity.
```
Object.keys(ADAPTERS)
```
must equal the adapters.json slugs where
```
!community || vendorOfficial
```
. So vendor-official must be in
```
chat/adapters
```
; community-only must not be. This is why community adapters skip steps 6–8.
peerDeps ↔ PackageInstall. The catalog entry's
```
peerDeps
```
(sorted) must exactly equal the extra packages in the MDX
```
<PackageInstall package="…" />
```
, after removing the adapter's own
```
packageName
```
,
```
chat
```
, and any
```
@chat-adapter/state-*
```
. Easiest:
```
peerDeps: []
```
, install only
```
<packageName> chat
```
(plus a state adapter) in
```
PackageInstall
```
, and keep any other imports in fenced code blocks.
Fields match.
```
packageName
```
,
```
type
```
,
```
community
```
, and
```
vendorOfficial
```
must match between the MDX frontmatter and the adapters.json entry.

Required frontmatter:

title

description

packageName

slug

tagline

type

(

platform

state

mdxBody: true

community: true

(plus

vendorOfficial: true

and

author

for vendor-official).

Imports. Every import in an MDX code block must be listed in
```
VALID_DOC_PACKAGES
```
.

注册表与目录一致性。
```
Object.keys(ADAPTERS)
```
必须等于adapters.json中
```
!community || vendorOfficial
```
的slug集合。因此厂商官方版必须加入
```
chat/adapters
```
；仅社区版不得加入。这也是社区版适配器跳过步骤6-8的原因。
peerDeps与PackageInstall一致性。目录条目中的
```
peerDeps
```
（已排序）必须与MDX中
```
<PackageInstall package="…" />
```
里除适配器自身
```
packageName
```
、
```
chat
```
以及任何
```
@chat-adapter/state-*
```
之外的额外包完全一致。最简单的做法是：
```
peerDeps: []
```
，在
```
PackageInstall
```
中仅安装
```
<packageName> chat
```
（加上状态适配器），将其他导入放在代码块中。
字段匹配。
```
packageName
```
、
```
type
```
、
```
community
```
和
```
vendorOfficial
```
必须在MDX前置元数据和adapters.json条目之间保持一致。

必填前置元数据：

title

、

description

、

packageName

、

slug

、

tagline

、

type

（

platform

state

）、

mdxBody: true

、

community: true

（厂商官方版需额外添加

vendorOfficial: true

和

author

）。

导入约束。MDX代码块中的每个导入都必须在
```
VALID_DOC_PACKAGES
```
中列出。

Validate

验证

bash

pnpm --filter chat build            # regenerate the catalog the tests import
pnpm --filter @chat-adapter/integration-tests test
pnpm --filter chat typecheck
pnpm --filter create-chat-sdk typecheck   # vendor-official only
pnpm check && pnpm konsistent

bash

pnpm --filter chat build            # 重新生成测试导入的目录
pnpm --filter @chat-adapter/integration-tests test
pnpm --filter chat typecheck
pnpm --filter create-chat-sdk typecheck   # 仅厂商官方版需要
pnpm check && pnpm konsistent

Resources

参考资源

Human guide (vendor-official):

apps/docs/content/docs/contributing/vendor-official.mdx

Human guide (community listing):

apps/docs/content/docs/contributing/publishing.mdx

MDX template: assets/adapter.mdx
Catalog conventions:
```
packages/chat/src/adapters/AGENTS.md
```

Examples to copy:

apps/docs/content/adapters/vendor-official/

and

apps/docs/content/adapters/community/

人工指南（厂商官方版）：

apps/docs/content/docs/contributing/vendor-official.mdx

人工指南（社区版列表）：

apps/docs/content/docs/contributing/publishing.mdx

MDX模板：assets/adapter.mdx
目录规范：
```
packages/chat/src/adapters/AGENTS.md
```

参考示例：

apps/docs/content/adapters/vendor-official/

和

apps/docs/content/adapters/community/