# 让 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 里不写死数量（本文档除外）。