# 01 · 核心理念

> 本文件展开每一个设计决策背后的论证。README 是摘要，这里讲"为什么"。

---

## 1. 设计的事实来源必须是可编辑的文本

### 1.1 对比

| | 用一个像素工具/图片当源头 | 用文本当源头 |
|---|---|---|
| 改一个字 | 要重算周围所有坐标 | 改一行 |
| 评审意见怎么落 | 再画一遍 | 改一行 |
| 能和代码一起 diff 吗 | 不能 | 能 |
| AI 能直接理解和修改吗 | 不能 | 能 |
| 设计会不会"过期" | 一定会（改起来太贵，于是没人改） | 不会（改起来便宜） |

**结论：图片只做交付物，不承担编辑职责。** 任何时候都不要直接在 PNG 上改东西。

### 1.2 对 AI 协作的决定性意义

文本为源不止是"方便"，它是让 AI 参与设计流程的前提：

- AI 生成、修改、检查的都是文本（HTML/CSS/SVG/Markdown），这是它的强项
- 设计评审变成"AI 读文件 → 输出问题清单"，可自动化
- 设计到实现之间没有"有损转换"环节——阶段 8 交接时，设计资产本身就是文本，AI 编码助手直接消费

---

## 2. 载体的分工与边界

| 载体 | 用来做什么 | 为什么 | 边界 |
|---|---|---|---|
| **HTML + CSS** | 界面布局、组件、状态（**主体**） | 盒模型（flex/grid/padding/border-radius）几乎能一对一映射到任何 UI 框架；改文案成本≈0；可写少量 JS 演示交互；能无头截图为 PNG | 不是最终交付物，是"设计源" |
| **SVG** | 图标、需要精确矢量的图元 | 可导入设计工具；图标可以直接转成目标框架的 Path | 图标用现成图标集复制，不自己画 |
| **Mermaid** | 流程图、状态图、时序图 | 自动排版连线，改节点名不用重画 | **只适合"节点+边"**，画不了界面布局 |
| **静态图片** | 交付、评审、存档 | 只读派生物 | 必须由源文件生成，不手改 |
| **Figma 等** | 需要多人协作评审时 | 与流程并存 | **方向不可反**：HTML 定稿 → 导出进 Figma 评审 → 意见回到 HTML 改 |

一句话记忆：**Mermaid 排不了三栏布局，SVG 改不动文案，PNG 改起来如上所述；所以界面主体用 HTML+CSS。**

### 2.1 为什么 Mermaid 的定位是"只能画流程图"

Mermaid 的布局引擎是自动的——它决定节点位置、连线路径。这带来两个后果：

- 优点：改节点名/增删节点不需要重画，流程图永远保持整洁
- 缺点：**布局不可控**。自由布局的架构图、需要精确位置的示意图会很快触顶

因此流程中 Mermaid 只出现在"节点+边"能说清问题的场合：页面流转、状态流转、时序。界面布局永远走 HTML。

---

## 3. 角色分工：工具 / AI / 人

### 3.1 三方职责

| 角色 | 职责 | 不做什么 |
|---|---|---|
| **工具**（InspireDesign） | 信息提供者：声明流程约束、环境要求、通过标准 | 不碰系统环境、不执行操作、不替人做决定 |
| **AI agent** | 执行与引导者：引导对话、检查环境、与用户确认、安装环境、运行脚本、生成产物 | 不被工具强制（工具只给约束，AI 有自己的判断） |
| **人** | 决策者：满意度、安装授权、阶段推进 | 不需要专业经验——每步都有引导 |

### 3.2 为什么"工具不碰系统环境"

MCP 工具在用户的机器上运行。如果工具自己去装环境、修依赖：

- 越权：动用户的系统是重大操作，必须经过用户确认
- 脆弱：工具无法适配所有系统形态，安装逻辑会变成巨大的兼容性包袱
- 错位：工具没有与用户对话的位置——它没法问你"确认要装吗"

而 AI agent 恰好三样都有：终端执行能力、与用户对话的通道、对项目上下文的感知。
所以正确分工是：**工具声明的，AI 落实的，人拍板的。**

### 3.3 为什么把"装环境"设计成流程的一部分

这不只是技术分工，还是方法论的一部分：

- 对使用者：这是"AI 引导、人决策、AI 执行"协作模式的第一次演练——之后每个设计阶段都是同一个模式的重复
- 对流程：环境就绪是"体检出图"阶段的硬前提，把它显式化（而不是藏在某个隐藏步骤里）能避免"工具跑不通才来排查"的混乱

---

## 4. 环境要求是声明式的

### 4.1 数据结构

每条环境要求包含五个要素：

| 要素 | 作用 |
|---|---|
| `name` / `minVersion` | 是什么、最低版本 |
| `why` | 为什么需要——**写给人和 AI 两方看**，让人理解安装的必要性 |
| `check` | 检查命令——AI 执行的探测手段 |
| `install` | 安装命令/地址——AI 在执行安装时的依据 |
| `optional` | 是否可选——可选依赖缺失时只降级部分能力，不阻塞 |

### 4.2 脚本的错误信息写给 AI 看

工具链脚本（check-layout.js / export-png.py）的报错原则：

- 说清"缺什么"：缺 Pillow
- 给出"怎么装"：`pip install pillow`
- 说明"装完怎么办"：重跑本脚本
- **不抛裸堆栈**：堆栈对 AI 是干扰信息，可执行的指令才是有效信息

这是"AI 时代工具设计"的通用原则：**错误信息的读者是 AI（顺便人也能看懂），标准是"可执行"。**

---

## 5. 人说了算

### 5.1 工具不参与满意度判断

完成一个阶段后，判断"这样行不行"的是人，不是工具。工具能判断的只有**形状问题**（溢出、越界、魔法数字、找不到落点），不能判断**意图问题**（这是不是我想要的）。

这个分工的意义：工具保持"客观检查者"的纯粹性，人保持对设计方向的完全掌控。

### 5.2 回退修正是一等公民

文本为源的直接推论：**任何阶段的产物都能回去改。**

- 改了 `tokens.css` → 下游的 `app.css` 和所有 `fig*.html` 需要复查
- 改了页面清单 → 所有下游都受影响

约束包里带"回退影响面"，AI 在用户说"想改 XX"时据此引导排查。**回退不是失败，是流程的正常组成部分。**

### 5.3 每个阶段的暂停点

"每个阶段结束必须停下来等人确认"——这条规则防止了 AI 最常见的失控模式：结构没确认就铺开，四处一起返工。

---

## 6. 粗粒度、无状态

### 6.1 为什么是一个大工具，不是十个小工具

| | 粗粒度（选定） | 细粒度 |
|---|---|---|
| 工具数量 | 1 个核心 + 少量辅助 | 十几个（select_mode / get_stage / advance / …） |
| 调用次数 | 少，一次拿全 | 多，每次拿一点 |
| 状态管理 | 无 | 工具要帮 AI 记住"现在第几步" |
| AI 的负担 | 一次消化完整约束 | 需要维护对流程的"操作感" |

AI 本身有完整的会话记忆和推理能力——它不需要工具帮它"走流程"，只需要工具回答"这个阶段的完整约束是什么"。

### 6.2 无状态 + 依赖提示

工具不记进展，但每次返回都带 `dependencies`（本阶段依赖的前置产物）。

于是 AI 的推理变得简单：拿到约束 → 检查依赖产物是否存在 → 缺则回补、齐则继续。**"进展"由文件系统本身记录**（tokens.css 存在 = 定令牌已完成），不需要工具记。

### 6.3 任意跳转

支持 AI 随时取任意阶段的约束，因为回退修正是常态。工具不做"流程门禁"——门禁在人那里（"你说行就行"），不在工具里。

---

## 7. 面向"非专业者"的降门槛设计

目标用户不是设计师，这套设计对他的保护体现在：

| 困难点 | 保护机制 |
|---|---|
| 不知道从哪开始 | 阶段 0 的功能蓝图：AI 用几个问题把你的想法结构化 |
| 不会描述想要的界面 | 风格探索阶段：丢参考图 + 情绪词，AI 生成多个方向供选择 |
| 不知道怎么说才"专业" | 每个阶段配提示词模板，可复制即用 |
| 不知道做到什么程度算完 | 每个阶段有明确出口条件（很多是机器可检查的） |
| 怕被 AI 带偏 | 每个阶段停下来等人确认；随时可回退 |
| 不懂设计工具 | 全程不需要——载体是 HTML/CSS/SVG/Mermaid，都在文本世界 |

**核心信念：把方法论工程化到足够细，人的专业性和熟练度就不再是瓶颈。**