让 AI 正确使用 / 扩展这套组件库

结论先说：需要 skill，但 skill 只做「入口 + 护栏 + 验证循环」，规则仍然只写在文档里。 否则规则会两处维护，迟早漂移。

1. 三件东西各管什么

文件	给谁	作用
`skills/stash-ui/SKILL.md`	支持 skill 的 agent（DSH 等）	任务分流（用 / 改 / 加）、硬约束、验证命令、已知坑
`AGENTS.md`	任意 AI 编码工具（Codex、Claude Code、Cursor…）	进仓库先读到「去哪里看」
`DESIGN.md` / `docs/COMPONENTS.md` / `docs/ADDING-A-COMPONENT.md`	人与 AI	唯一事实来源（规则、契约、流程）

skill 的内容刻意很短（约 80 行），因为它解决的是入口问题： AI 不需要每次都把 5 份文档读一遍，而是先被路由到正确的文档和验收命令。

2. 三种接入方式

2.1 直接读文件（最通用，零配置）

任何能读仓库的 AI 都可以从 skills/stash-ui/SKILL.md 开始：

读 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/）：

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 名）：

- 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 关键字段：

{
  "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 用这套库时的三条铁律

先查再用：COMPONENTS.md §2 有「用哪个」决策表；能组合就不新增组件。
令牌唯一：颜色 / 间距 / 字号 / 圆角只走 --su-*；直接写 --su-gray-* 会在深色下串色。
改 props = 改契约：组件、展示页、COMPONENTS.md + README 三处必须同时更新。

4. 验证循环（AI 必须自己跑）

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

4.4 KiB Raw Permalink Blame History Unescape Escape