103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# 让 AI 正确使用 / 扩展这套组件库
|
||
|
||
结论先说：**需要 skill，但 skill 只做「入口 + 护栏 + 验证循环」，规则仍然只写在文档里。**
|
||
否则规则会两处维护，迟早漂移。
|
||
|
||
## 1. 三件东西各管什么
|
||
|
||
| 文件 | 给谁 | 作用 |
|
||
| --- | --- | --- |
|
||
| [`skills/stash-ui/SKILL.md`](../skills/stash-ui/SKILL.md) | 支持 skill 的 agent（DSH 等） | 任务分流（用 / 改 / 加）、硬约束、验证命令、已知坑 |
|
||
| [`AGENTS.md`](../AGENTS.md) | 任意 AI 编码工具（Codex、Claude Code、Cursor…） | 进仓库先读到「去哪里看」 |
|
||
| [`DESIGN.md`](../DESIGN.md) / [`docs/COMPONENTS.md`](COMPONENTS.md) / [`docs/ADDING-A-COMPONENT.md`](ADDING-A-COMPONENT.md) | 人与 AI | 唯一事实来源（规则、契约、流程） |
|
||
|
||
skill 的内容刻意很短（约 80 行），因为它解决的是**入口问题**：
|
||
AI 不需要每次都把 5 份文档读一遍，而是先被路由到正确的文档和验收命令。
|
||
|
||
## 2. 三种接入方式
|
||
|
||
### 2.1 直接读文件（最通用，零配置）
|
||
|
||
任何能读仓库的 AI 都可以从 `skills/stash-ui/SKILL.md` 开始：
|
||
|
||
```text
|
||
读 skills/stash-ui/SKILL.md，按里面的流程执行。
|
||
```
|
||
|
||
Claude Code / Codex / Cursor 这类工具会自动读仓库根的 `AGENTS.md`（或 `CLAUDE.md`），
|
||
所以把仓库交给它们时，入口是自动的。
|
||
|
||
### 2.2 DeepSeek Harness（技能目录）
|
||
|
||
如果你的 harness 支持扫描技能目录，把 `skills/stash-ui/` 整个复制到技能根目录即可
|
||
（目录名即 skill 名，`SKILL.md` 的 frontmatter 里也有 `name: stash-ui`）。
|
||
|
||
### 2.3 DeepSeek Harness（插件包，官方同款做法）
|
||
|
||
DSH 的 skill 由 `@deepseek-ai/dsh-skill-filesystem` 提供，插件通过 `cordis.patch.yml`
|
||
注册一个 `bundledSkillDir`。最小骨架如下（放在本仓库之外，例如 `stash-ui-dsh-plugin/`）：
|
||
|
||
```text
|
||
stash-ui-dsh-plugin/
|
||
├── package.json # name: @yourscope/stash-ui-dsh，dsh.bundle.patch: ./cordis.patch.yml
|
||
├── cordis.patch.yml
|
||
├── lib/index.js # 导出 resolveStashSkillRoot（可选，便于测试）
|
||
└── skills/stash-ui/SKILL.md
|
||
```
|
||
|
||
`cordis.patch.yml`（把 `<你的包名>` 换成实际 npm 名）：
|
||
|
||
```yaml
|
||
- insert:
|
||
- id: stash-ui-skill-filesystem
|
||
name: '@deepseek-ai/dsh-skill-filesystem'
|
||
config:
|
||
providerName: stash-ui
|
||
includeDefaultRoots: false
|
||
bundledSkillDir: !!js process.getBuiltinModule('node:path').join(
|
||
process.getBuiltinModule('node:path').dirname(
|
||
process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('<你的包名>/package.json')
|
||
),
|
||
'skills'
|
||
)
|
||
```
|
||
|
||
`package.json` 关键字段：
|
||
|
||
```json
|
||
{
|
||
"name": "<你的包名>",
|
||
"type": "module",
|
||
"files": ["lib", "cordis.patch.yml", "skills"],
|
||
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
|
||
}
|
||
```
|
||
|
||
装到 DSH profile 后，`skill` 工具的技能目录里就会出现 `stash-ui`；
|
||
如果没出现，先确认 patch 里的包名能被 profile 的 `createRequire(baseUrl)` 解析到。
|
||
|
||
## 3. AI 用这套库时的三条铁律
|
||
|
||
1. **先查再用**：`COMPONENTS.md §2` 有「用哪个」决策表；能组合就不新增组件。
|
||
2. **令牌唯一**：颜色 / 间距 / 字号 / 圆角只走 `--su-*`；直接写 `--su-gray-*` 会在深色下串色。
|
||
3. **改 props = 改契约**：组件、展示页、`COMPONENTS.md` + README 三处必须同时更新。
|
||
|
||
## 4. 验证循环（AI 必须自己跑）
|
||
|
||
```bash
|
||
npm run typecheck && npm run lint && npm run build && npm run build:site
|
||
node scripts/screenshot.mjs http://127.0.0.1:5199/#<section> shots/<section>.png
|
||
node scripts/screenshot.mjs "http://127.0.0.1:5199/demo.html?scheme=dark" shots/demo-dark.png full
|
||
```
|
||
|
||
- `lint` 要求 **0 warnings**（不是「能过就行」）。
|
||
- 视觉改动要贴图核对；深色必须单独看一遍。
|
||
- 交付时说明改了哪些组件、契约是否同步、截图路径。
|
||
|
||
## 5. 维护 skill 的规则
|
||
|
||
- skill 里**不复制**具体数值、props 表、12 步流程；只写入口、约束、命令、坑。
|
||
- 文档改了影响流程的部分（验收清单、命令、目录结构）时，同步改 skill 那几行。
|
||
- 新增「已知坑」时，先写到 `DESIGN.md §9`，再决定要不要在 skill 里留一句指针。
|
||
- 每次组件数量变化，只改 README / COMPONENTS，skill 里不写死数量（本文档除外）。
|