aodw-skill 0.7.3

package/.aodw/02-workflow/ui-workflow-rules.md

@@ -0,0 +1,334 @@
+# UI Workflow Rules
+UI 设计与审查流程规范
+
+## 0. 概述
+
+当 RT 任务涉及 UI/界面/交互相关工作时，必须执行本流程。本流程确保：
+- UI 设计符合项目统一审美标准（非 AI 风格）
+- **在实现前先产出静态 HTML 原型供用户确认**（强制步骤）
+- 通过严格的 UI 审查机制保证质量
+
+### 0.1 核心要求
+
+> ⚠️ **关键规则**：所有 UI 相关任务**必须**在 RT 目录中创建 HTML 版本的界面原型，并**必须**获得用户确认后才能进入实现阶段。
+
+- **HTML 原型文件位置**：`RT/RT-XXX/docs/ui-prototype.html`
+- **用户确认**：是强制门禁，不可跳过
+- **实现代码**：仅在用户确认原型后才能生成
+
+---
+
+## 1. UI 任务识别（Task Type Detection）
+
+在执行任何任务之前，AI 必须首先进行 **任务类型判断**。
+
+### 1.1 UI 相关任务判定条件
+
+以下任意条件满足，即视为 **UI 相关任务**：
+
+- ✅ 涉及页面、界面、布局、组件、表单、Dashboard
+- ✅ 涉及用户操作流程、交互体验、可视化
+- ✅ 涉及前端 UI、样式、视觉呈现
+- ✅ 用户明确提到"界面 / UI / 好看 / 丑 / 设计"
+- ✅ 涉及 UI 改造、UI 新建、UI 优化
+
+### 1.2 判断时机
+
+- **RT 创建阶段**：在 `intake.md` 生成时进行判断
+- **任务执行阶段**：在执行任何代码修改前进行判断
+- **需求变更阶段**：当用户提出新需求时重新判断
+- **用户主动触发**：用户明确要求执行 UI 流程时（见第 1.4 节）
+
+### 1.3 判断结果处理
+
+- **非 UI 相关任务**：按正常 AODW 流程执行
+- **UI 相关任务**：**必须进入 UI 专用流程**（见第 2 节）
+
+### 1.4 用户主动触发 UI 流程
+
+用户可以在任何时候主动触发 UI 相关流程，AI 必须识别并执行。
+
+#### 1.4.1 触发命令识别
+
+AI 必须识别以下用户指令（支持多种表达方式）：
+
+| 触发类型 | 触发词示例 | 执行动作 |
+|---------|-----------|---------|
+| **UI 设计** | "请 AODW 规范，帮我就当前这个 RT 任务的界面进行设计"<br>"按 AODW 规范设计界面"<br>"设计 UI"<br>"生成界面原型" | 执行 UI 设计流程（第 2 节） |
+| **UI 审计/审查** | "请 AODW 规范，帮我就当前这个 RT 任务的界面进行审计"<br>"审计界面"<br>"审查 UI"<br>"检查界面" | 执行 UI Critic 审查流程（第 3 节） |
+| **UI 挑毛病** | "请 AODW 规范，帮我就当前这个 RT 任务的界面挑毛病"<br>"挑 UI 毛病"<br>"找界面问题"<br>"UI 有什么问题" | 执行 UI Critic 审查流程（第 3 节，严格模式） |
+
+> **详细规则**：请参考 `.aodw/01-core/ai-interaction-rules.md` 第 5.5 节
+
+#### 1.4.2 触发条件检查
+
+当用户触发 UI 流程时，AI 必须：
+
+1. **检查当前 RT 上下文**
+   - 确认是否存在当前 RT（检查 `RT/RT-XXX/` 目录）
+   - 如果不存在，提示用户："未找到当前 RT，请先创建或打开一个 RT"
+   - 如果存在，读取 `intake.md` 或 `spec.md` / `spec-lite.md` 了解任务内容
+
+2. **检查是否为 UI 相关任务**
+   - 如果 `intake.md` 中标注了 `ui_related: true`，直接进入 UI 流程
+   - 如果未标注，但任务涉及 UI（根据第 1.1 节判断），提示用户："检测到当前 RT 可能涉及 UI，是否执行 UI 流程？"
+   - 如果完全不涉及 UI，提示用户："当前 RT 不涉及 UI，是否仍要执行 UI 审查？"
+
+3. **执行对应的 UI 流程**
+   - **UI 设计**：按照第 2 节执行
+   - **UI 审计/审查/挑毛病**：按照第 3 节执行
+
+#### 1.4.3 执行优先级
+
+- **用户主动触发** > **自动流程触发**
+- 如果用户主动触发 UI 流程，即使当前不在 UI 相关阶段，也应立即执行
+- 执行完成后，询问用户是否继续原流程
+
+---
+
+## 2. UI 专用流程（强制执行，不可跳过）
+
+当任务被判定为 UI 相关时，AI 必须严格按以下顺序执行：
+
+### 2.1 规则文件读取（强制前置，但按需加载）
+
+> ⚠️ **Token 优化**：UI-Kit 文件应该合并为单个文件（`.aodw/03-standards/ui-kit/ui-kit.md`），以减少加载次数和 token 消耗。
+
+**加载时机**：在生成任何 UI 代码之前，AI **必须**先读取并理解 UI 设计规范文件。
+
+**文件位置**：`.aodw/03-standards/ui-kit/` 目录
+
+**加载方式**：
+- **必须读取**：`.aodw/03-standards/ui-kit/ui-kit.md`（合并后的统一文件，包含所有 UI 设计规范）
+  - 第 1 节：UI 设计系统（统一审美与设计约束）
+  - 第 2 节：UI 生成提示词（所有 UI 生成的"总提示词"）
+  - 第 3 节：禁止的 AI 风格（明确禁止的 AI 审美）
+  - 第 4 节：UI Critic Agent（UI 审查标准）
+
+**关键规则**：
+- ⚠️ 在未确认理解上述规则之前，**不允许生成任何 UI**
+- ⚠️ 在未确认理解上述规则之前，**不允许输出任何代码**
+- ⚠️ **只在 UI 任务时加载**，非 UI 任务不加载 UI-Kit 文件
+- AI 必须明确告知用户："已读取 UI 设计规范，准备开始设计"
+
+### 2.2 UI 生成阶段规则
+
+#### 2.2.1 设计原则
+
+UI 生成必须遵守：
+- ✅ 克制、非 AI 风格
+- ✅ 禁止蓝 / 紫 / 红 AI 默认审美
+- ✅ 更像真实成熟产品（Linear / Notion / Stripe），而非 Demo 或 AI 工具
+- ✅ 严格遵循 `ui-kit.md` 第 1 节（UI 设计系统）中的规范
+
+#### 2.2.2 生成流程（必须顺序执行，不可跳过）
+
+**步骤 A：UI 结构与设计说明**
+- 先输出 UI 结构与设计说明
+- 包括：布局结构、组件层次、交互流程、颜色方案
+- 说明设计理由，解释如何符合设计系统
+
+**步骤 B：静态 HTML 原型生成（强制步骤）**
+
+> ⚠️ **关键规则**：所有 UI 相关任务**必须**在 RT 目录中创建 HTML 版本的界面原型。
+
+- **文件位置**：必须在 `RT/RT-XXX/docs/ui-prototype.html`（如果 `docs/` 目录不存在，必须先创建）
+- **文件命名**：统一使用 `ui-prototype.html`
+- **文件内容要求**：
+  - ✅ 生成**完整的静态 HTML 原型**（使用模拟数据）
+  - ✅ **必须包含所有 UI 元素和交互状态**
+  - ✅ **必须包含完整的样式**（内联 CSS 或 `<style>` 标签）
+  - ✅ **必须包含模拟数据**（不需要任何真实 API 请求）
+  - ✅ 必须能够在浏览器中直接打开查看
+  - ✅ 必须符合 `ui-kit.md` 第 1 节（UI 设计系统）中的设计规范
+- **文件创建**：AI 必须使用 `write` 工具创建此文件，确保文件存在于 RT 目录中
+
+**步骤 C：用户确认（强制门禁，不可跳过）**
+
+> ⚠️ **关键规则**：用户确认是**强制步骤**，未获得确认前**严禁**进入实现阶段。
+
+- **展示 HTML 原型**：
+  - 告知用户文件位置：`RT/RT-XXX/docs/ui-prototype.html`
+  - 提示用户："请在浏览器中打开此文件查看界面原型"
+  - 如果可能，提供文件路径的完整说明
+- **明确询问**：
+  - 必须明确询问："请确认此 UI 原型是否符合预期？"
+  - 必须等待用户明确确认（"确认"、"通过"、"继续"、"批准"等）
+- **确认前禁止**：
+  - ❌ **未获得用户确认前，禁止进入下一步**
+  - ❌ **未获得用户确认前，禁止生成任何实现代码**
+  - ❌ **未获得用户确认前，禁止修改任何业务代码**
+
+**步骤 D：实现代码生成（用户确认后）**
+- **仅在用户明确确认后**，才生成实际实现代码
+- 代码必须与确认的原型保持一致
+- 如果用户要求修改，必须回到步骤 A 重新设计
+
+---
+
+## 3. UI 质量审查（必须执行）
+
+在 UI 初稿生成完成后（无论是 HTML 原型还是实现代码），**必须自动执行 UI 审查流程**。
+
+### 3.1 审查触发时机
+
+- **自动触发**：
+  - HTML 原型生成后（用户确认前）
+  - 实现代码生成后（提交前）
+- **用户主动触发**：
+  - 用户明确要求"审计界面"、"审查 UI"、"检查界面"、"挑 UI 毛病"等
+  - 用户可以在任何时候主动触发 UI 审查，即使不在 UI 相关阶段
+  - 详细触发命令见第 1.4 节
+
+### 3.2 审查执行流程
+
+1. **切换到 UI Critic 角色**
+   - 按照 `.aodw/03-standards/ui-kit/ui-kit.md` 第 4 节（UI Critic Agent）的标准执行审查
+   - 以"挑剔的资深 UI/UX 设计总监"身份进行评判
+
+2. **审查标准**
+   - 是否有 AI 默认审美特征
+   - 是否像真实产品，而不是 Demo
+   - 是否存在颜色、排版、层级滥用
+   - 是否"用力过猛"
+
+3. **审查输出格式**
+   必须包含：
+   - **丑点清单**（明确指出问题）
+   - **为什么丑**（原因分析）
+   - **如何改**（改进建议）
+   - **是否建议整体重做**（是 / 否）
+
+### 3.3 审查结果处理
+
+- **通过审查**：继续下一步流程
+- **未通过审查**：进入重构流程（见第 4 节）
+
+---
+
+## 4. 重构流程（条件触发）
+
+如果 UI Critic 指出存在明显问题，必须执行重构：
+
+### 4.1 重构触发条件
+
+- UI Critic 明确建议"整体重做"
+- 发现 `ui-kit.md` 第 3 节（禁止的 AI 风格）中列出的任何禁止模式
+- 存在明显的颜色、排版、层级问题
+
+### 4.2 重构执行规则
+
+1. **禁止引入禁止模式**
+   - 不得引入 `ui-kit.md` 第 3 节（禁止的 AI 风格）中的任何模式
+   - 不得使用蓝紫渐变、紫色主色、高饱和科技蓝等
+
+2. **重构目标**
+   - 更人类、更克制、更专业
+   - 更接近 Linear / Notion / Stripe 风格
+
+3. **重构后重新审查**
+   - 重构完成后，必须再次执行 UI 审查流程
+   - 直到通过审查或用户明确接受
+
+---
+
+## 5. UI 流程与 RT 流程集成
+
+### 5.1 在 Spec-Lite 中的集成
+
+当 RT 使用 Spec-Lite Profile 且涉及 UI 时：
+
+1. **Intake 阶段**：识别为 UI 任务
+2. **Spec 阶段**：在 `spec-lite.md` 中明确标注 UI 相关
+3. **Plan 阶段**：在 `plan-lite.md` 中必须包含：
+   - UI 原型生成步骤
+   - UI 审查步骤
+   - 用户确认步骤
+4. **实现阶段**：按本流程执行
+
+### 5.2 在 Spec-Full 中的集成
+
+当 RT 使用 Spec-Full Profile 且涉及 UI 时：
+
+1. **Intake 阶段**：识别为 UI 任务
+2. **Spec 阶段**：在 `spec.md` 中详细描述 UI 需求
+3. **Plan 阶段**：在 `plan.md` 中必须包含：
+   - UI 原型设计步骤
+   - UI 审查步骤
+   - 用户确认步骤
+   - UI 实现步骤
+4. **Impact 阶段**：在 `impact.md` 中分析 UI 变更影响
+5. **实现阶段**：按本流程执行
+
+### 5.3 文档记录要求
+
+UI 相关 RT 必须在以下文档中记录：
+
+- **`intake.md`**：标注 `ui_related: true`
+- **`spec.md` 或 `spec-lite.md`**：包含 UI 设计说明
+- **`plan.md` 或 `plan-lite.md`**：包含 UI 流程步骤
+- **`RT/RT-XXX/docs/ui-prototype.html`**：**必须创建** HTML 原型文件（强制要求）
+- **`changelog.md`**：记录 UI 变更历史，包括 HTML 原型的创建和确认时间
+
+---
+
+## 6. 最终原则
+
+### 6.1 质量优先
+
+**UI 的质量优先级高于完成速度。**
+
+如果不确定是否好看，**优先简化，而不是增加设计**。
+
+### 6.2 用户确认优先（强制要求）
+
+**所有 UI 设计必须经过用户确认才能进入实现阶段。**
+
+**强制要求**：
+- ✅ **必须**在 `RT/RT-XXX/docs/ui-prototype.html` 创建 HTML 原型文件
+- ✅ **必须**等待用户在浏览器中查看原型并明确确认
+- ✅ **必须**在用户确认后才允许生成实现代码
+- ❌ **严禁**跳过 HTML 原型直接生成实现代码
+- ❌ **严禁**在未获得用户确认前进入实现阶段
+
+静态 HTML 原型是确认的关键工具，必须包含完整的视觉呈现和所有交互状态。
+
+### 6.3 禁止跳过（强制检查点）
+
+以下步骤**不可跳过**，违反将视为严重违规：
+- ❌ 规则文件读取
+- ❌ UI 结构与设计说明
+- ❌ **静态 HTML 原型生成**（必须在 `RT/RT-XXX/docs/ui-prototype.html` 创建文件）
+- ❌ **用户确认**（强制门禁，未确认前禁止进入实现阶段）
+- ❌ UI 审查
+
+**违规处理**：
+- 如果 AI 跳过 HTML 原型生成或用户确认步骤，必须立即停止，重新执行完整流程
+
+---
+
+## 7. 违规处理
+
+如果 AI 违反本流程：
+
+1. **在未读取规则文件前生成 UI**：必须立即停止，重新读取规则
+2. **未创建 HTML 原型文件**：必须立即停止，创建 `RT/RT-XXX/docs/ui-prototype.html` 文件
+3. **跳过用户确认直接实现**：必须回退，重新生成原型并确认，**严禁**在未确认前生成实现代码
+4. **未执行 UI 审查**：必须补充审查，根据结果决定是否重构
+5. **引入禁止的 AI 风格**：必须立即重构，不得继续
+
+**严重违规**：
+- 如果 AI 跳过 HTML 原型创建或用户确认步骤，视为严重违规
+- 必须立即停止所有工作，重新执行完整的 UI 流程
+- 必须向用户明确说明违规情况并道歉
+
+---
+
+## 8. 参考文件
+
+- `.aodw/03-standards/ui-kit/ui-kit.md` - 统一 UI 设计规范（合并文件，包含所有 UI 设计规范）
+  - 第 1 节：UI 设计系统（统一审美与设计约束）
+  - 第 2 节：UI 生成提示词（所有 UI 生成的"总提示词"）
+  - 第 3 节：禁止的 AI 风格（明确禁止的 AI 审美）
+  - 第 4 节：UI Critic Agent（专门「挑丑」的 AI Agent）
+

package/.aodw/03-standards/ai-coding-rules-common.md

@@ -0,0 +1,89 @@
+# AI Coding Rules - Common Standards
+
+> **注意**：本文件是 `.aodw/03-standards/ai-coding-rules.md` 的子规范文件。  
+> 请先阅读主文件了解通用编码原则，再阅读本文件了解通用编码规范。
+
+**适用场景**：
+- 所有类型的代码开发（前端、后端、脚本等）
+- 文件大小和复杂度控制
+- 代码拆分原则
+- 输出策略
+
+---
+
+## 1. 全局文件长度限制（软上限）
+
+为了防止代码库变得难以维护，AI 必须严格遵守以下文件长度限制。
+
+当文件接近以下限制时，AI **必须** 停止向该文件添加新功能，并考虑拆分。
+
+- **TS/TSX/JS 页面组件 (Page)**：建议 ≤ 250 行（软上限 300 行）
+- **TS/TSX 业务组件 (Business)**：建议 ≤ 200 行
+- **TS/TSX 展示组件 (Display)**：建议 ≤ 150 行
+- **Python 模块**：≤ 300 行（普通业务模块建议 ≤ 250 行）
+- **Shell 脚本**：≤ 150 行
+- **SQL / JSON / YAML / 配置文件**：≤ 200 行（或大小 < 20KB）
+
+---
+
+## 2. 函数 / 方法 / 类限制
+
+- **单个函数/方法**：建议 ≤ 40 行，**最多 ≤ 60 行**。
+  - *Action*：如超过 60 行，必须拆分为多个小函数。
+- **单个类**：建议 ≤ 300 行。
+  - *Action*：如超过需按职责拆类或拆模块。
+- **JSX 结构**：超过 80 行或嵌套过深时，必须拆成子组件。
+
+---
+
+## 3. 拆分原则 (Splitting Principle)
+
+当你（AI）意识到继续实现会导致文件超出上述限制时，必须执行以下 **Stop & Ask** 流程：
+
+1. **立刻停止**继续往这个文件里加内容。
+2. **主动说明**需要新建哪些文件（组件 / hooks / services / 子模块）来分担职责。
+3. **分步实现**：当前对话只实现一个核心文件，其余留待后续迭代。
+
+---
+
+## 4. 输出策略 (Output Strategy)
+
+对于中大型功能（或预计代码量 > 100 行）：
+
+1. **目录结构先行**：
+   - 第一步必须给出 **目录结构 + 文件列表 + 各文件职责说明**（不写具体代码）。
+   - 在得到用户确认前，**不要**直接生成完整实现。
+
+2. **单次单文件**：
+   - 每次对话只生成 **一个文件** 的完整代码。
+   - 必须按如下格式标明路径与职责：
+
+   ```tsx
+   // path: src/pages/ProjectEditorPage/index.tsx
+   // 职责：负责项目编辑页面的整体布局和组件组合，不包含复杂业务逻辑
+   <代码...>
+   ```
+
+---
+
+## 5. 复杂度控制
+
+- **圈复杂度 (Cyclomatic Complexity)**：建议 ≤ 10
+- **认知复杂度 (Cognitive Complexity)**：建议 ≤ 15
+
+如果复杂度超过限制，必须：
+1. 重构代码，降低复杂度
+2. 拆分函数或类
+3. 提取公共逻辑
+
+---
+
+## 6. 代码质量检查
+
+在提交代码前，必须确保：
+
+- [ ] 文件大小符合限制
+- [ ] 函数/方法长度符合限制
+- [ ] 复杂度符合限制
+- [ ] 代码已通过静态检查工具（ESLint、Ruff 等）
+- [ ] 代码已通过格式化工具（Prettier、Black 等）