在终端用 21st CLI 发布和管理 21st.dev…

需要把 React 组件发布到 21st.dev 或团队库、维护主题/模板列表、编辑/下架已有条目，或更新 21st.dev 个人主页时使用。

适用场景

解决思路

1. 运行 `21st login` 或提供 `21st_sk_…` API key 来认证组件发布、库存、checkout、元数据编辑和取消发布；主题/模板命令仍要求从 https://21st.dev/settings/api-keys 获取真实 API key，并通过 `--api-key`、`TWENTYFIRST_TOKEN` 或 `API_KEY_21ST` 传入。
2. 使用统一 CLI `@21st-dev/cli`（bin 为 `21st`），不要另造发布工具。
3. 发布前运行 `21st search "<query>"` 搜索，避免向库中加入重复项。
4. 当用户要延续或编辑旧组件工作时，先运行 `21st components`，或用 `21st components --status draft --scope personal --json` 过滤，或用 `21st open component:123`、`21st open draft:<uuid> --no-open` 打开。
5. `21st components` 默认清空两个独立分页集合，所以无过滤运行会返回所有可访问的个人或 Team 组件以及拥有的草稿；用 `--status all|draft|published|private` 或 `--scope all|personal|team:<uuid>` 缩小范围。
6. 保留返回的稳定引用 `component:<id>` 或 `draft:<uuid>`，不要用 slug 替代。
7. 运行 `21st open draft:<uuid>` 恢复可编辑 Studio 草稿。
8. 运行 `21st open component:<id>` 基于保留的已发布组件代码和 demo 创建或恢复服务端 CLI Review revision；在该 revision 发布前，线上组件保持不变。
9. 运行 `21st open component:<id> --no-open` 或 `21st open draft:<uuid> --no-open` 创建或恢复工作区并打印 URL，但不启动浏览器。
10. 如果源码已在本地修改，运行 `21st publish ./Component.tsx --component component:123 --description "What changed"`。
11. 不要用同 slug 猜测替换稳定 ref；只有原始组件作者能 checkout 代码；Team 管理者仍可通过稳定 ref 编辑或下架队友组件元数据。
12. 当保留源码、依赖、样式、支持文件或默认 demo 无法安全复现时，checkout 会 fail closed；此时改用本地源发布命令，不要削弱检查或声称有代码访问权限。
13. 登录会话可盘点个人作品和用户可管理的 Teams；个人 key 仅限个人；Team key 仅限该 Team；新 CLI Review 草稿持久化其认证的个人或 Team/library 范围；旧的 proof-backed CLI 草稿恢复到匹配认证范围；旧的无签名草稿若范围无法证明，可能需要重建。
14. 用位置文件路径触发自动检测：从导出组件取名称、从文件名取 slug、从 import 取 tags，并自动查找或合成 demo。
15. 对新 slug 或拥有的 revision，命令会验证依赖、安装并构建组件、创建 Studio 草稿、打开专用 CLI Review 并等待；review sidebar 显示确切的 Demos (N) 数量，并保持选中 demo 与实时预览并排。
16. 运行 `21st publish ./path/to/Component.tsx --to default --description "1-2 sentences: what it does and when to use it"`。
17. Studio 先生成必需 cover，再后台尝试可选 video；拥有的 revision 在完成同一 CLI Review 并发布前保持 pending。
18. 决定访问权限：未限定的 publish/share 链接请求默认 published，不加 flag；要提交目录或争取 featured，先 publish，再运行 `21st submit <slug>`；限制到团队库或内部使用，加 `--private`。
19. 发布只控制访问；目录 featured 始终是独立的 review 动作，发布不会静默提交组件。
20. `--description "…"`：必需，至少 10 字符，说明组件做什么和何时用；不要捏造，读代码或问用户。
21. `--name`、`--slug`、`--tags a,b`：覆盖自动检测的名称、URL slug、1-5 个 tags。
22. `--demo <file>`：指定 demo 文件；自动查找 `{Comp}.demo.tsx`、`demos/{slug}.tsx`、`demos/default.tsx`，或合成一个简单 demo；真实 demo 能得到更好的预览。
23. `--preview <img>`：暂存初始 cover 图片；它替换生成的 cover，但不绕过 Studio review 或 required-cover gate。
24. `--no-open`：打印 Studio 草稿 URL 而不打开；草稿仍可用于之后 review。
25. `--registry ui|hooks|blocks|icons`：选择目标子注册表，默认 `ui`。
26. `--to <library-slug>`：指定目标团队库，例如 `--to default`；省略则用团队默认库。
27. `--registry-dep <ref>`：CLI Review 尚不支持；创建新组件或 owned revision 前移除它。
28. `--visibility published|private`：访问权限，默认 `published`。
29. 对新 slug 或 owned revision，命令先打印 Studio 草稿 URL，仅在 Studio 发布后才报告组件 URL 和 install line；按 Ctrl+C 可停止 CLI 等待但保留草稿。
30. 在 demo 代码中声明一个模块级 `settings` 对象，并让 default export 接受 props，发布管道会据此生成 live controls 面板；没有 flag 可启用。
31. 访客移动 knob 后点击 Copy code，会把他们的值写回 `settings` 字面量；对有可调值的 demo（粒子数、速度、颜色、尺寸、标签、feature flags）都这样做。
32. `settings` 和 props 两半都必须存在：只有 settings 没 props，或只有 props 没 settings，都不会生成面板。
33. 值映射：number 生成 slider（整数为 `0..3x`，`0..1` float 为 ratio slider）。
34. 值映射：boolean 生成 switch。
35. 值映射：CSS 颜色字符串（如 `#7dd3fc`、`oklch(...)`）生成 color picker。
36. 值映射：颜色字符串数组（<= 12）生成可编辑 palette。
37. 值映射：其他字符串且 <= 120 字符生成 text field。
38. 值映射：嵌套对象、混合数组、长字符串不生成控件；应把它们扁平化成顶层键。
39. 写 `settings` 对象前注意：最多 24 个 controls；键必须是普通标识符，且不能是 `key`、`ref`、`constructor`、`prototype`、`__proto__`；值必须是管道可读的字面量，不能是 imported constants、computed expressions 或 spreads；Expo/native demos 完全没有面板。
40. 推断的 labels 和 ranges 只是猜测，应在 CLI Review 的 Controls 块检查，并重命名 labels、收紧 min/max/step；编辑它们不会改变值，值始终从实际发布的代码重新读取。
41. 在最终发布前让组件和 demo 自包含：在最近的 `package.json` 声明所有导入的 npm 包；不要留下未解析的本地或 alias imports；继续前确认 CLI build 成功。
42. 当前 CLI 命令只发送一个组件文件和一个 demo；额外的本地文件和 `21st.json` 尚不接受。
43. 使用可移植 Tailwind 语义 token，如 `bg-primary`、`text-primary-foreground`、`bg-background`、`border-border`；在自定义 CSS 或 arbitrary properties 中，使用 Tailwind v4 theme variables，如 `var(--color-primary)`、`var(--color-muted-foreground)`。
44. 不要写 `oklch(var(--primary))`、`hsl(var(--primary))`，也不要假设 `--primary` 等原始变量的存储格式；透明度使用 `bg-primary/20` 之类的工具类，或 `color-mix()` 与 `var(--color-primary)`。
45. Studio 打开后使用专用 CLI Review；确认 Demos (N) 数量，选择每个 demo，检查右侧 live preview；演练每个有意义状态，并验证 light/dark 主题，包括语义 primary 颜色正确解析。
46. 如果 demo 声明 `settings`，也要操作 Controls panel：每个 knob 必须明显改变预览，且 label 和 range 合理。
47. 如果预览空白、抛错、有未解析依赖或颜色错误，修复源码并重新运行 `21st publish`；不要为了通过预览硬编码源项目的品牌色。
48. 最终发布前等待自动生成的 Cover；cover 生成有第一优先级且是硬发布 gate；可选 video 是后台 best-effort，发布从不等待它，只在 ready 时包含。
49. 如果生成的封面或视频不具代表性，手动替换任一资产；生成媒体不能替代审查 live component。
50. 更新前先盘点。用 `21st open component:<id>` 从保留的已发布代码和 demos 创建或恢复已审查 revision。
51. 如果源码已本地改变，运行 `21st publish <file> --component component:<id>`；当前线上版本在该 revision 完成 CLI Review 并发布前不变。
52. 如果用户想创建新组件但 slug 冲突，先确认再继续，并建议不同的 `--slug`。
53. 永不捏造 description，也不发布包含 API keys、secrets 或未保存编辑的文件。
54. 对已有作品先盘点并使用其稳定 ref；不要从 slug 猜测。
55. 始终先搜索；发布有用 demo（有可调值时通过 `settings` 可控）；验证 build 和 dependencies；完成 live-preview 与 theme-token review；最终发布前等待必需 cover。
56. 发布主题时，主题是 CSS 文件，必须同时定义 `:root` 和 `.dark` 的 token 值，并作为 public 社区主题发布：`21st publish-theme ./my-theme.css --name "Midnight" [--tags dark,minimal]`。
57. 若要从当前项目的 design tokens 生成主题 CSS，使用 `21st-design-sync` skill。
58. 发布模板时，模板是元数据 listing（URLs，不是文件），会进入 `draft` 等待审核：`21st publish-template "SaaS Starter" --site https://demo.example.com --preview https://example.com/thumb.png [--description "…"] [--price 49] [--buy-url https://…] [--video https://…] [--tags 1,2]`。
59. 更新精确组件：`21st edit component:<id> --type component --visibility published|private [--description "…"] [--tags a,b]`；Team 管理者可管理元数据。
60. 更新主题：`21st edit <theme-id> --type theme [--visibility public|private] [--name "New Name"] [--tags a,b]`。
61. 更新模板：`21st edit <template-id> --type template [--name N] [--description D] [--tags 1,2]`。
62. 删除总是需要 `--yes`，且语义不同：组件 -> 取消发布（visibility 设为 private，可通过 edit/re-publish 恢复）；主题 -> 取消发布（从 marketplace 移除，可恢复）；模板 -> 永久硬删除。
63. 运行 `21st delete component:<id> --type component --yes` 或 `21st delete <id> --type theme|template --yes`。
64. 目录审核独立于 Published/Private 访问：`21st submit <slug>`、`21st withdraw <slug>`、`21st resubmit <slug>`、`21st remove-from-catalog <slug>`。
65. 注意：模板 visibility 由审核控制，`--visibility` 对模板会被忽略；主题通过 `--name` 重命名且仅支持 `public|private`；组件 edit/delete 接受登录会话或 API key，主题/模板管理仍要求 API key。
66. 浏览器编辑时先盘点，再运行 `21st open <stable-ref>`；如果保留组件源码不能安全 checkout，改用 `21st publish <file> --component component:<id>` 创建已审查代码 revision。
67. 公开 profile `21st.dev/@you` 可显示 bento 风格 blocks；`set` 是 FULL REPLACE（类似 `edit` 的 `--tags`），如果想保留现有内容先读当前 board。
68. 读取当前 board：`21st profile get [--json]`。
69. 替换 board：`21st profile set --file board.json`（JSON 数组，也可通过 stdin 管道传入）。
70. 恢复 classic profile：`21st profile set --clear`。
71. 上传图片：`21st profile upload ./cover.png`，支持 png/jpg/gif/webp 并打印 url。
72. `board.json` 是从上到下的 blocks 数组，例如 `[{"type":"component","demoId":143},{"type":"library","refId":"<personal-or-team-library-id>"},{"type":"social","url":"https://x.com/you"},{"type":"note","text":"Building UI for 21st.dev"},{"type":"hire","headline":"Work with me","url":"https://cal.com/you"},{"type":"divider"},{"type":"image","mediaUrl":"<url from profile upload>"}]`。
73. Block 类型包括：`component`（自己的 demoId，来自 `21st search --mine` 或 `21st get`）、`social`（链接卡片，图标从域名自动识别）、`note`（文本）、`hire`/`pro`/`support`（headline/body/url/email/cta）、`library`（通过 `refId` 指向公开个人或团队库）、`image`（`mediaUrl` 来自 `profile upload`；外部 url 会被丢弃，不报错）、`divider`（把 board 分成新区段）。
74. 每个 block 都接受可选 `w`/`h`（grid 单位，宽 1-3、高 1-2）来设置尺寸。
75. 重排序就是按想要顺序重新提交 blocks 数组；board 按数组顺序从上到下、从左到右排列。
76. 管理 Teams：运行 `21st teams` 查看 teams，`21st team <teamId>` 查看团队 libraries，`21st team-lists <teamId>` 查看团队共享 bookmark lists，`21st team-components <teamId> [--library <id>]` 查看团队组件。
77. 写入 MCP config：运行 `21st init --client cursor|claude|codex|vscode|devin [--write]`。

适用边界 · 注意事项

• 仅需要查找和安装已有 21st.dev 条目时，不适用本技能，应使用 `21st-cli-use`。
• 需要把项目 design tokens 转成主题时，不适用本技能，应使用 `21st-design-sync`。
• 没有 21st.dev 账号、API key，或无法安装/使用 `@21st-dev/cli` 时，不适用。