痛点：手动维护会死人
当你的设计系统有 31 个组件协议、21 个 Section 协议、还有 Direction 和 Page 层的结构——"保持一致性"就不再是一个可以靠自觉的事情。
具体来说：
- 新建一个组件要创建 3 个文件（协议/实现/注册），漏一个就不完整
- 注册表里有 31 个条目，每个要和磁盘上的协议文件对应
- 协议文件有 JSON Schema 约束，手写很容易犯格式错误
- 组件协议引用了不存在的 token？没有校验就等着运行时炸
这些问题用 human review 是扛不住的。 一旦协议数量超过 15 个，你就需要工具化治理。
ds-cli 是什么
ds-cli 是我为这套设计系统写的专用命令行工具。它做三类事：
核心命令速览
| 命令 | 做什么 | 典型场景 |
|---|---|---|
ds init [name] | 初始化新设计系统项目 | 第一次搭建 |
ds add component <name> | 创建组件（协议+实现+注册） | 新增 button/input/modal |
ds add section <name> | 创建 Section（组合组件） | 新增 FormFooter/HeroCard |
ds add direction <name> | 创建 Direction（页面布局模式） | 新增 sidebar/wizard 布局 |
ds validate | 协议 Schema 校验 + 类型检查 | CI 集成 / 提交前检查 |
ds audit | 一致性审计（孤儿/幽灵/缺口） | 定期健康检查 |
ds list [type] | 列出所有设计对象 | 快速了解全貌 |
ds info <name> | 查看单个对象详情 | 开发前了解协议 |
ds schema <type> | 输出 JSON Schema 定义 | AI 生成协议时参考 |
ds workflow [type] | 展示规范工作流 | 新人 onboard |
实战：从零添加一个组件
假设你要新增一个 tag 组件：
ds add component tag --level L1 --category display它会做 5 件事：
- 生成协议文件
protocols/components/tag.protocol.json（含默认结构） - 生成实现骨架
src/components/tag/Tag.vue - 在
manifest/component-registry.json中注册 - 校验协议符合 JSON Schema
- 输出创建报告
关键设计: --dry-run 参数让你先看会生成什么、再决定是否执行。这对 AI 协作尤其重要——AI 生成前先 dry-run 确认路径正确。
验证：防止协议腐坏
ds validate 是最关键的命令。它做三层检查：
Layer 1: Protocol Schema 校验
每个 .protocol.json 必须符合对应的 JSON Schema。检查：
- 必填字段是否存在
- 字段类型是否正确
- 枚举值是否在允许范围内
Layer 2: 类型检查
TypeScript 编译通过——确保协议和实现代码的类型一致。
Layer 3: 构建检查
Vite 构建通过——确保不会有运行时问题。
# CI 中的典型用法
ds validate --scope all --json
# 输出结构化结果，非零退出码表示失败Audit：一致性的终极卫士
ds audit 是我最喜欢的命令。它检查三类不一致：
| 检查类型 | 含义 | 严重程度 |
|---|---|---|
| Orphan（孤儿） | 有实现代码但没有协议文件 | 🔴 高 |
| Ghost（幽灵） | 有协议文件但没有实现代码 | 👻 中 |
| Registry Gap（缺口） | 注册表和实际文件不匹配 | 📋 中（可自动修复） |
--fix 参数可以自动修复 Registry Gap——把注册表和实际文件同步。但 Orphan 和 Ghost 需要人工判断（是漏了协议？还是漏了实现？）。
为什么不用 Storybook CLI？
| 对比 | Storybook CLI | ds-cli |
|---|---|---|
| 目标 | 生成展示 story | 治理协议一致性 |
| 校验 | 无 Schema 校验 | JSON Schema + TypeScript + Build |
| 审计 | 无 | 孤儿/幽灵/缺口检测 |
| 工作流 | 没有 | 内置 canonical workflow |
| AI 友好 | story 是自由文本 | --json 输出结构化数据 |
| 注册表管理 | 无 | 自动同步 |
核心区别: Storybook 管展示，ds-cli 管治理。一个组件是否"合规"——协议完整、Schema 通过、注册到位——这是 ds-cli 的职责。
AI 集成：为什么 --json 参数这么重要
ds-cli 的每个命令都支持 --json 参数，输出结构化数据。这是 AI 协作的关键：
# AI 先查看规范
ds schema component --json
# → 输出 JSON Schema，AI 据此生成协议
# AI 检查现有组件（避免命名冲突）
ds list components --json
# → 输出所有组件列表
# AI 生成后验证
ds validate --json
# → 结构化报告，AI 可解析错误并修复这形成了一个闭环: AI 查规范 → 生成 → 验证 → 修复 → 再验证。ds-cli 是这个闭环的基础设施。
设计哲学
几个影响 ds-cli 设计的关键信念：
- 约定优于配置 — 目录结构固定，不给选项。减少认知负担。
- 协议是真理 — 协议文件是 SoT，实现和注册都从协议派生。
- 失败要响 — validate 失败退出码非零，CI 会拦住。不是"提示一下"，是"不让过"。
- AI 是一等公民 — 每个命令都有
--json，每个工作流都有ds workflow输出标准步骤。
总结：设计系统的复杂度不在单个组件——在组件之间的关系和一致性。当你有 30+ 组件，手动维护一致性是人力灾难。ds-cli 把"保持一致"从人脑转移到工具——它不聪明，但它不会忘。