# Spark Design Agent Usage Guide

> 给 AI agent / coding agent 的执行指南。目标不是介绍组件库是什么，而是约束“在项目里该怎么正确使用它”。

## 1. 默认决策

### 1.1 优先级

默认优先使用 **CLI 按需引入**：

```bash
npx sparkdesign@latest add button
```

只有在以下场景才优先考虑整包安装：

- 用户明确要求 `npm install sparkdesign`
- 目标是快速原型，而不是复制源码后再改
- 运行环境不方便把组件源码拷入项目

### 1.2 两条使用路径

| 路径 | 适用场景 | Agent 默认行为 |
|------|----------|----------------|
| **CLI 按需引入** | 业务项目、需要修改组件源码、希望长期维护本地副本 | **默认优先** |
| **整包安装** | Showcase、快速试用、低定制场景、只想直接 import | 仅在用户明确要求或项目已采用整包模式时使用 |

## 2. CLI 路径怎么用

### 2.1 常用命令

```bash
npx sparkdesign@latest init
npx sparkdesign@latest add button
npx sparkdesign@latest add response
npx sparkdesign@latest list
npx sparkdesign@latest diff button
```

### 2.2 生成后的默认路径

默认组件会写到：

```text
src/components/ui/basic/<name>.tsx
src/components/ui/chat/<name>.tsx
src/components/ui/chat/<name>/index.tsx
```

如果项目里已有 `components.json`，以 `aliases.ui` 为准，不要硬猜路径。

### 2.3 CLI 路径下的 import 规则

默认按以下方式导入：

```tsx
import { Button } from '@/components/ui/basic/button'
import { Response } from '@/components/ui/chat/response'
```

不要在 CLI 路径下再写：

```tsx
import { Button } from 'sparkdesign'
```

这会把“复制到本地的源码”与“整包运行时”混在一起。

## 3. 整包路径怎么用

### 3.1 安装与导入

```bash
npm install sparkdesign
```

```tsx
import 'sparkdesign/style'
import { Button, Response } from 'sparkdesign'
```

### 3.2 整包路径下的样式规则

默认优先：

```tsx
import 'sparkdesign/style'
```

只有在消费者自己维护 Tailwind 4 样式管线时，才改用：

```tsx
import 'sparkdesign/theme.css'
import 'sparkdesign/scale.css'
```

## 4. 主题与 Token 硬规则

### 4.1 一律使用 design tokens

选择 token 前，agent 应优先读取：

```tsx
import ontology from 'sparkdesign/token-ontology.json'
```

仓库内源文件为：

```text
registry/tokens/ontology.json
```

允许：

```tsx
className="bg-primary text-text rounded-md"
className="px-[var(--spacing-3)]"
```

不允许：

```tsx
className="bg-[#1890FF] text-[#333] rounded-[10px]"
```

### 4.2 根节点主题

优先在根节点或大容器设置：

```tsx
<div data-theme="light" data-style="neutral" />
```

可选值：

- `data-theme`: `light` | `dark` | 自定义主题名
- `data-style`: `neutral` | `compact` | `soft` | `sharp` | `dense`

### 4.3 Portal / 浮层组件

Tooltip、DropdownMenu、Toast 这类浮层要考虑 theme/style 继承。若项目已用整包并提供 `ThemeStyleProvider`，优先沿用；不要通过强制 remount 的方式“刷新主题”。

## 5. 组件选择规则

### 5.0 先读 Agent Manifest

设计 / coding agent 在选择组件前，优先读取：

```tsx
import manifest from 'sparkdesign/agent-manifest.json'
```

仓库内源文件为：

```text
registry/agent-manifest.json
```

该 manifest 提供组件 `intent`、`slots`、`states`、`a11y`、`composition`、`antiPatterns` 和常见 `recipes`。选择组件时先按 `intent` 和 `recipes` 匹配，再读源码；不要仅凭组件名相似度决定。

### 5.1 Basic vs Chat

- `basic/*`: 原子 UI，适合表单、控制、布局、通用信息展示
- `chat/*`: 对话流组件，适合消息、响应、任务、推理步骤、附件、代码块等

### 5.2 不要重复造轮子

若以下组件已存在，优先复用：

- 通用按钮：`button` / `icon-button`
- 浮层：`tooltip` / `dropdown-menu` / `alert-dialog`
- 对话输入：`chat-input`
- AI 响应：`response`
- 推理步骤：`reasoning-step`
- 代码卡片：`code-block-part` / `terminal-code-block-part`
- 任务与计划：`task-part` / `plan-part`

## 6. 改组件时的约束

### 6.1 Registry 是 CLI 模板真相

若改动会影响 `npx sparkdesign add ...` 的结果，优先检查：

- `registry/`
- `registry/meta.json`
- `cli/registry/` 是否已由同步脚本刷新

### 6.2 根包是唯一发布入口

不要从 `cli/` 目录单独发布。

正式发布只从仓库根目录执行：

```bash
npm publish
```

根包会同时带上：

- 运行时导出（整包）
- `bin.sparkdesign -> ./cli/dist/index.js`（CLI）

## 7. 给 Agent 的执行清单

开始工作前，优先回答这 5 个问题：

1. 当前项目是在用 **CLI 本地源码**，还是在用 **整包 import**？
2. 目标组件属于 `basic` 还是 `chat`？
3. 是否已经有可复用组件，而不是新建一个相似组件？
4. 样式是否完全基于 token，而不是硬编码？
5. 如果会影响 CLI，是否同步检查了 `registry/meta.json` 与发布链路？

如果这 5 个问题里有任何一个答不上来，先不要写代码，先补上下文。