21st-registry 是 21st.dev 团队组件库的发布与安装技能，核心工具是 @21st-dev/registry CLI。它支持两个方向：把组件发布给团队，以及安装团队已共享的组件。
用途 用于在 21st.dev 的团队库中发布 React 组件，让队友用一条命令安装；也可安装团队或个人已发布的组件。
使用前检查 需要确认认证状态：环境变量 API_KEY_21ST 已设置，或 registry CLI 已保存凭据。若两者都没有，应提示用户运行一次 npx @21st-dev/registry login，不要代为登录。
发布组件 发布前需决定可见性，默认使用 unlisted。用户说“分享给团队”“内部发布”或未明确说明时，使用所选/默认注册表中的 unlisted，无需可见性标志；用户说“通过链接公开分享/在我的个人资料上，但不列入库”时使用 --unlisted；用户说“公开发布”“在 21st 上公开”时使用 --public；用户说“限制在注册表团队”“私有团队草稿”时使用 --private。没有用户明确指示，绝不使用 --public。公开组件会经过管理员审核并出现在 21st 库中；--unlisted 是用户想要可分享 URL 但不想列入库时的安全选项。
标准发布命令：
npx @21st-dev/registry ./path/to/Component.tsx
--to default
--description "1-2 sentences about what it does and when to use it"
CLI 的位置文件路径会触发自动检测：名称来自默认导出，slug 来自文件名，标签来自导入，演示自动查找或合成。
常用标志：--name 覆盖自动检测的名称；--description 必填，至少 10 个字符，需真实描述用途和使用场景，不得编造；--tags 为 1-5 个小写标签，默认从导入检测；--slug 覆盖 URL slug；--demo 指定演示文件，自动检测模式包括 {Component}.demo.tsx、demos/{slug}.tsx、demos/default.tsx，若不存在 CLI 会自动合成一个简单的 <Component /> 演示；--preview 可选静态预览图；--to 指定目标注册表；--public/--unlisted/--private 覆盖可见性。
发布成功后返回类似： ✅ https://21st.dev/community/components/{username}/{slug} Install in another project: npx @21st-dev/registry add @{username}/{slug}
更新已有组件：相同命令、相同 slug 即为 upsert，CLI 会打印“Updated”而非“Published”，无需版本标志，队友始终获取最新版。若用户想要新组件但 slug 冲突，应先确认再覆盖，建议更改 --slug。
安装组件 支持两种地址格式：@team-slug/component-slug（团队注册表，团队共享首选）和 @username/component-slug（用户个人/公开组件）。
npx @21st-dev/registry add @acme/animated-button
或
npx @21st-dev/registry add @serjobas/animated-button
CLI 会获取注册表 JSON 和组件文件，写入项目（默认 components/ui/{slug}.tsx），为 npm 依赖运行 pnpm/npm/yarn/bun add，若依赖其他 21st 组件会打印出来，需单独 add 安装。
对于 shadcn，公开/unlisted 组件可使用普通注册表项 URL：
npx shadcn@latest add "https://21st.dev/r/acme/animated-button"
重复安装或私有组件，可在消费项目的 components.json 中注册 21st 注册表并使用 Bearer token：
{ "registries": { "@YOUR_NAMESPACE": { "url": "https://21st.dev/r/acme/default/{name}.json", "headers": { "Authorization": "Bearer ${API_KEY_21ST}" } } } }
然后用标准 shadcn CLI 安装：
npx shadcn@latest add @YOUR_NAMESPACE/animated-button
@YOUR_NAMESPACE 只是 components.json 中的本地别名，可任选清晰 slug。除非用户明确希望本地文件包含个人密钥，否则不要将真实 API 密钥提交到 components.json。
安装标志：--force 覆盖现有文件；--no-install 跳过 npm 安装步骤；--dir PATH 安装到不同项目目录。
搜索团队库 当用户想要组件但不知道确切名称时：
npx @21st-dev/registry search "<query>"
默认范围是团队库。使用 --scope mine 仅搜索自己的，--scope public 搜索公开库。发布前若可能已有类似组件，应始终先搜索，避免重复。
npx @21st-dev/registry search "button" --scope team
打印列表，含可传给 add 的 @user/slug 引用。
管理团队与注册表 可通过 CLI 查看、创建和编辑团队与注册表（无删除，删除保留在 Web Studio）。每个子命令都接受 --json，需要解析输出时优先使用。团队通过 slug 用 --team <slug> 指定，默认是 API 密钥所属团队。
操作前检查
npx @21st-dev/registry team list --json # 所有团队：slug、角色、默认 npx @21st-dev/registry team info [team] # 成员 + 待处理邀请 npx @21st-dev/registry registry list --team <slug> --json
创建
npx @21st-dev/registry team create "<name>" [--description TEXT] npx @21st-dev/registry registry create "<name>" [--slug SLUG] [--description TEXT] [--team SLUG]
若省略 --slug，注册表 slug 会从名称自动派生
编辑
npx @21st-dev/registry team edit [team] --name TEXT --description TEXT # 仅所有者 npx @21st-dev/registry registry edit <slug> --name TEXT --description TEXT
通过电子邮件邀请协作者
npx @21st-dev/registry team invite <email> [--team SLUG]
发布新组件组前的典型流程：registry list --json 查看现有内容 → 如需要则 registry create "Marketing blocks" → publish --to marketing-blocks。
代理硬性规则 ❌ 没有用户明确“公开发布”指示，绝不使用 --public。 ❌ 绝不编造描述。应询问用户或仔细阅读代码。 ❌ 发布的组件文件中绝不包含 API 密钥、环境变量值或硬编码内部 URL。 ❌ 绝不发布有未保存编辑的文件，先保存。 ✅ 若可能已有类似组件，发布前始终搜索。 ✅ 尽可能添加带真实 props 的有用演示文件；仅在最后手段才回退到自动合成的演示。
常见错误 演示通过错误路径导入组件。CLI 会在上传前自动重写相对导入（如 import X from "../component"）为 @/components/ui/{slug}，因此演示应使用相对导入指向用户源文件，而非别名，CLI 会处理。
多次发布之间 slug 不一致。若用户重命名文件，自动派生的 slug 会变化，导致创建重复项。在稳定名称下重新发布时，应显式传递 --slug。
组件缺少默认导出。会以明确错误失败，需先重构为 export default function ComponentName(...)。