aodw-skill 0.7.3

package/.aodw/01-core/ai-interaction-rules.md

@@ -0,0 +1,218 @@
+0. UI 任务判断（前置检查）
+
+在执行任何任务之前，AI 必须首先进行 **任务类型判断**，识别是否为 UI 相关任务。
+
+### 0.1 UI 相关任务判定条件
+
+以下任意条件满足，即视为 **UI 相关任务**：
+- ✅ 涉及页面、界面、布局、组件、表单、Dashboard
+- ✅ 涉及用户操作流程、交互体验、可视化
+- ✅ 涉及前端 UI、样式、视觉呈现
+- ✅ 用户明确提到"界面 / UI / 好看 / 丑 / 设计"
+- ✅ 涉及 UI 改造、UI 新建、UI 优化
+
+### 0.2 判断时机
+
+- **RT 创建阶段**：在 `intake.md` 生成时进行判断
+- **任务执行阶段**：在执行任何代码修改前进行判断
+- **需求变更阶段**：当用户提出新需求时重新判断
+
+### 0.3 判断结果处理
+
+- **非 UI 相关任务**：按正常 AODW 流程执行
+- **UI 相关任务**：**必须进入 UI 专用流程**
+
+> **详细规则**：请参考 `.aodw/02-workflow/ui-workflow-rules.md`
+
+---
+
+1. 问题类型（两大类）
+AI 所提出的所有问题必须明确属于：
+	1.	决策型（Decision Question）
+	•	必须提供选项
+	•	必须明确推荐项
+	•	必须给出推荐理由
+	•	必须支持 "custom: …"（≤ 5 个词）
+	2.	信息型（Information Question）
+	•	用于收集信息
+	•	必须提供示例答案
+	•	必须限制用户输入不超过 10 个词
+	•	必须保证问题可被快速回答
+
+⸻
+
+2. 问题的格式规范
+所有问题必须遵守格式（AI 必须严格采用）：
+Q1. <问题内容>
+
+A. <选项1>
+B. <选项2>
+C. <选项3>
+D. <选项4>
+
+Recommended: B（理由：……）
+
+请回复：A/B/C/D 或 custom:<你的答案>
+
+信息型问题格式：
+Q2. <要确认的信息>
+
+示例答案：
+- "订单服务"
+- "支付模块"
+- "只影响前端"
+
+请给我一个 ≤10个词的回答。
+
+3. 每轮最多提出的问题数量
+	•	🚫 单轮禁止提出超过 5 个问题
+	•	建议每轮 3 个 以内
+	•	超过 3 个必须提示用户原因（例如：需求范围大，需要更多澄清）
+
+⸻
+
+4. AI 问题的节奏（Flow Control）
+AI 必须遵守：
+	•	不得一次性问一大堆问题
+	•	必须逐步推进（Ask → Wait → Respond → Continue）
+	•	每轮问题结束后必须总结本轮收集到的信息
+	•	不能在用户未回答的情况下继续提出下一组问题
+
+⸻
+
+5. 用户中断与暂停机制
+AI 必须支持以下命令：
+	•	"先暂停 AODW"
+	•	"等一下，不继续流程"
+	•	"跳过这一步"
+
+AI 必须立即：
+	•	停止流程推进
+	•	切换到「普通代码助手模式」
+	•	并要求用户说"继续 AODW"才能回到流程
+
+⸻
+
+5.5. UI 流程主动触发机制
+
+用户可以在任何时候主动触发 UI 相关流程，AI 必须识别并执行以下命令：
+
+### 5.5.1 UI 流程触发命令识别
+
+AI 必须识别以下用户指令（支持多种表达方式）：
+
+| 触发类型 | 触发词示例 | 执行动作 |
+|---------|-----------|---------|
+| **UI 设计** | "请 AODW 规范，帮我就当前这个 RT 任务的界面进行设计"<br>"按 AODW 规范设计界面"<br>"设计 UI"<br>"生成界面原型" | 执行 UI 设计流程（规则文件读取 → UI 结构与设计说明 → 静态 HTML 原型生成 → 用户确认） |
+| **UI 审计/审查** | "请 AODW 规范，帮我就当前这个 RT 任务的界面进行审计"<br>"审计界面"<br>"审查 UI"<br>"检查界面" | 执行 UI Critic 审查流程（切换到 UI Critic 角色，按 `.aodw/03-standards/ui-kit/ui-kit.md` 第 4 节标准审查） |
+| **UI 挑毛病** | "请 AODW 规范，帮我就当前这个 RT 任务的界面挑毛病"<br>"挑 UI 毛病"<br>"找界面问题"<br>"UI 有什么问题" | 执行 UI Critic 审查流程（严格审查，指出所有问题） |
+
+### 5.5.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（根据第 0 节判断），提示用户："检测到当前 RT 可能涉及 UI，是否执行 UI 流程？"
+   - 如果完全不涉及 UI，提示用户："当前 RT 不涉及 UI，是否仍要执行 UI 审查？"
+
+3. **执行对应的 UI 流程**
+   - **UI 设计**：按照 `.aodw/02-workflow/ui-workflow-rules.md` 第 2 节执行
+   - **UI 审计/审查/挑毛病**：按照 `.aodw/02-workflow/ui-workflow-rules.md` 第 3 节执行
+
+### 5.5.3 执行响应模板
+
+当用户触发 UI 流程时，AI 应回复：
+
+```
+✅ **UI 流程已触发**
+- 当前 RT：[RT-XXX]
+- 触发类型：[设计 / 审计 / 挑毛病]
+- 执行动作：[具体要执行的内容]
+- 参考规范：[.aodw/03-standards/ui-kit/ui-kit.md]
+```
+
+### 5.5.4 执行优先级
+
+- **用户主动触发** > **自动流程触发**
+- 如果用户主动触发 UI 流程，即使当前不在 UI 相关阶段，也应立即执行
+- 执行完成后，询问用户是否继续原流程
+
+⸻
+
+6. 错误恢复机制
+如果用户回答不清晰或违背格式，AI 必须：
+	•	或再次提出简化问题
+	•	并提供新的建议选项
+
+⸻
+
+7. 透明度与确认机制
+
+AI 必须主动维护流程的透明度：
+- **复杂任务追踪**：当任务步骤超过 3 步时，必须创建 `task.md` 并实时更新。
+  - **任务追踪检查**：
+    - 在执行复杂任务时，AI 应在每个阶段结束后主动检查 task.md 是否需要更新
+    - 如果发现 task.md 已过时，必须立即更新并告知用户
+    - 在每次提交代码前，AI 必须检查 task.md 是否已更新到最新状态
+- **关键节点确认**：
+  - Plan 完成后，必须暂停并请求批准。
+  - 代码提交前，必须暂停并请求确认。
+
+⸻
+
+8. 门禁检查点与用户确认
+
+> **重要**：详细的门禁检查点定义见 `aodw-constitution.md` 第 4.5 节。
+
+### 8.1 确认词汇表
+
+AI 必须识别以下用户确认指令：
+
+| 确认类型     | 触发词                           | 范围                             |
+| ------------ | -------------------------------- | -------------------------------- |
+| **单步确认** | "继续"、"下一步"、"好"、"ok"     | 只批准当前 Gate，进入下一阶段    |
+| **批准执行** | "批准"、"执行"、"approved"、"go" | 批准 Plan，允许开始编码          |
+| **跳过确认** | "跳过"、"skip"                   | 跳过当前检查点（需二次确认风险） |
+| **暂停流程** | "暂停"、"pause"、"等等"、"停"    | 暂停 AODW 流程，切换到普通模式   |
+| **启动审计** | "审计"、"audit"                  | 启动对应阶段的审计               |
+
+### 8.2 确认边界
+
+**关键规则**：
+- ⚠️ 用户说"继续"只意味着"通过当前 Gate"，**不是"执行到底"**
+- ⚠️ AI 必须在下一个 Gate 再次等待确认
+- ⚠️ 默认模式下，每个 Gate 只能通过一个确认
+
+### 8.3 确认后响应模板
+
+当用户确认后，AI 应回复：
+
+```
+✅ **确认收到**
+- 当前操作：[刚才批准的内容]
+- 正在执行：[即将做的事情]
+- 下一检查点：[下一个 Gate 的位置]
+```
+
+⸻
+
+9. 分支验证前置
+
+AI 在执行任何代码修改操作（`write_to_file`、`replace_file_content`）前，必须：
+
+1. 运行 `git branch --show-current`
+2. 检查结果：
+   - ✅ 如果显示 `feature/RT-XXX-xxx`：继续执行
+   - ❌ 如果显示 `main` 或 `master`：**立即停止**
+3. 如果在 main/master 分支：
+   - 提示用户当前在主分支
+   - 询问是否创建 feature 分支
+   - 创建并切换到分支后才能继续
+
+**违规处理**：如果 AI 在 main/master 分支上修改了业务代码，必须立即回滚。

package/.aodw/01-core/ai-knowledge-rules.md

@@ -0,0 +1,302 @@
+# AI Knowledge Maintenance Rules  
+AI 必须确保文档始终与代码一致。
+
+本文件定义“何时更新哪些文档”，以及文档与代码之间的映射方式。
+
+---
+
+## 1. 总原则
+
+1. 文档是系统的一等公民，必须与代码一起演化；
+2. 任何重要改动都必须在相关文档中有所体现；
+3. AI 在执行任何非琐碎修改后，应主动检查并更新相关文档；
+4. 如果文档与代码不一致，AI 应优先尝试修正不一致，而不是忽略。
+
+---
+
+## 2. 文档类别
+
+### 2.1 全局文档（Global）
+
+位于 `.aodw/` 或 `docs/` 下，用于整个系统：
+
+- `.aodw/01-core/aodw-constitution.md`  
+- `.aodw/06-project/ai-overview.md`  
+- `.aodw/03-standards/ai-coding-rules.md`  
+- `.aodw/01-core/ai-knowledge-rules.md`  
+- 模块 README（如 `docs/modules/users.md`、`docs/modules/orders.md` 等）  
+- 数据与合约文档（如 `data-model.md`、`contracts/*.md` / `contracts/*.yaml`）
+
+**当发生以下情况时，AI 必须更新相关全局文档：**
+
+- 整体架构变化（例如引入新子系统、拆分服务、替换核心中间件）；
+- 模块职责变化（例如将一部分业务从 A 模块迁移到 B 模块）；
+- 数据模型变化（增加 / 删除 / 修改实体或字段含义）；
+- 对外接口或协议变化（API、消息格式等）；
+- AODW 流程规则本身发生修改。
+
+---
+
+### 2.2 RT 专属文档（Local per RT）
+
+每个 RT 都有自己的知识库目录，包括核心文档和过程文档。
+
+**目录结构**：详见 `.aodw/02-workflow/rt-manager.md` 第 2 节"目录与分支创建"。
+
+**核心文档**：位于 RT 目录根目录，记录 RT 全生命周期信息（intake、decision、spec、plan、impact、invariants、tests、changelog 等）。
+
+**过程文档**：位于 `RT/RT-XXX/docs/` 目录，记录执行过程中的分析、调研、决策。详细规则见第 7 节。
+
+---
+
+## 3. 何时更新哪些文档
+
+### 3.1 Intake 阶段后
+
+在 RT-Manager 完成本 RT 的 Intake（立项）后：
+
+- 必须创建 / 更新：
+  - `RT/RT-XXX/intake.md`
+  - `RT/RT-XXX/decision.md`
+
+`intake.md` 应包含：
+
+- 原始用户描述；
+- AI 提出的问题与用户回答的简要记录；
+- 对需求 / 问题的归类（Feature / Bug / Enhancement / Refactor / Research 等）；
+- 初步范围与风险评估。
+
+`decision.md` 应包含：
+
+- 为何选择 Spec-Full 或 Spec-Lite；
+- 若存在备选流程（如纯 Research），记录为何未采用；
+- 如用户强行指定流程，记录 AI 的原始建议与用户的选择。
+
+---
+
+### 3.2 Spec 阶段后（Spec-Full / Spec-Lite）
+
+**Spec-Full：**
+
+- AI 必须创建 / 更新：
+  - `RT/RT-XXX/spec.md`
+  - `RT/RT-XXX/clarifications`（可在 spec 中以章节形式存在）
+
+Spec 内容应包括：
+
+- 背景与目标；
+- 用户故事 / 功能需求；
+- 非功能需求（性能、安全、可用性等）；
+- 成功标准；
+- 需要澄清的历史问题记录（Q&A）。
+
+**Spec-Lite：**
+
+- AI 必须创建 / 更新：
+  - `RT/RT-XXX/spec-lite.md`
+
+Spec-Lite 内容应精简，至少包含：
+
+- 当前问题描述；
+- 目标行为（修复后 / 改进后的预期效果）；
+- 影响范围的文字说明。
+
+---
+
+### 3.3 Plan 阶段后
+
+**Spec-Full：**
+
+- AI 必须创建 / 更新：
+  - `RT/RT-XXX/plan.md`
+  - `RT/RT-XXX/data-model.md`（如涉及数据模型变更）
+  - `RT/RT-XXX/contracts/`（如涉及对外接口变更）
+  - `RT/RT-XXX/research.md`（如有前期调研与决策）
+
+**Spec-Lite：**
+
+- AI 必须创建 / 更新：
+  - `RT/RT-XXX/plan-lite.md`
+
+Plan-Lite 内容应包含：
+
+- 预期修改的代码位置（文件路径 / 模块）；
+- 简单的技术方案；
+- 潜在风险与注意事项。
+
+---
+
+### 3.4 修改代码前
+
+在实现前，AI 必须创建 / 更新：
+
+- `RT/RT-XXX/impact.md`  
+  - 当前问题是如何触发的；
+  - 哪些模块 / 功能直接受到影响；
+  - 哪些模块可能被间接影响；
+- `RT/RT-XXX/invariants.md`  
+  - 在本次改动中必须保持不变的行为；
+  - 不允许被破坏的数据与接口约束。
+
+这些文档是 **变更的约束条件**。如之后发现方案与 invariants 冲突，AI 应向用户明确指出，并建议走 Spec-Full 或修订 invariants。
+
+---
+
+### 3.5 修改代码后
+
+在实现完成后，AI 必须：
+
+1. **更新 tests.md**
+
+   - 列出新增的测试用例及其覆盖的场景；
+   - 列出建议回归的关键用例；
+   - 如存在未自动化但应进行手动验证的场景，也应列出。
+
+2. **更新 changelog.md**
+
+   - 以简洁的方式概述本次 RT 对系统行为的改动；
+   - 如有潜在影响范围（例如“可能对历史数据产生影响”），加以说明；
+   - 标注与其他 RT 或模块的依赖关系。
+
+3. 如涉及数据模型或对外接口更改，必须更新：
+
+   - `data-model.md`；
+   - `contracts/` 中的相关说明；
+   - 相关模块 README；
+   - 必要时更新 `ai-overview.md`（例如新增了新的核心模块）。
+
+---
+
+## 4. 文档与代码的映射（Frontmatter Mapping）
+
+为了帮助 AI 找到与某段代码相关的文档，建议在文档顶部使用 Frontmatter：
+
+```yaml
+---
+rt: RT-001
+related_files:
+  - apps/api/src/orders/**
+  - apps/api/src/orders/order_service.ts
+  - apps/web/src/features/orders/**
+---
+```
+
+或在模块 README 中：
+
+```yaml
+---
+module: orders
+files:
+  - apps/api/src/orders/**
+  - apps/web/src/features/orders/**
+---
+```
+
+AI 在进行修改时，必须执行 **Mapping Check**：
+
+1.  **查索引**：读取 `.aodw/06-project/modules-index.yaml`，获取所有模块的 `root` 路径。
+2.  **匹配路径**：检查本次修改的文件路径是否落在某个模块的 `root` 下。
+3.  **定位文档**：如果匹配，读取对应的 `path`（即模块 README）。
+4.  **验证 Frontmatter**：进一步检查模块 README 中的 `files` 字段是否包含该文件。
+5.  **更新文档**：确认匹配后，必须审查该文档，并将本次 RT 的变更同步更新进去。
+
+**如果找不到匹配的模块**：
+- 考虑是否需要创建一个新模块？
+- 或者该文件属于公共基础设施（需更新全局文档）？
+
+---
+
+## 5. 文档一致性检查
+
+在 RT 实现流程的最后（合并 / 完成之前），AI 应进行一次快速一致性检查：
+
+**核心文档检查**：
+- 当前改动是否改变了数据模型？如果是，`data-model.md` 是否反映了这一点？
+- 当前改动是否改变了对外接口？如果是，`contracts/` 是否已更新？
+- 当前改动是否改变了模块职责？如果是，相关 README 是否已更新？
+- 当前 RT 的：
+  - `spec` / `spec-lite`
+  - `plan` / `plan-lite`
+  - `impact`
+  - `invariants`
+  - `tests`
+  - `changelog`
+
+  是否完整地记录了从"问题 → 方案 → 实现 → 测试 → 结果"的过程？
+
+**目录结构检查**：
+- 检查过程文档是否在正确位置（应在 `RT/RT-XXX/docs/` 目录下，详见第 7 节）
+- 检查核心文档是否完整（meta.yaml、intake.md、decision.md、spec/plan、impact、invariants、tests、changelog）
+
+如发现明显不一致，AI 应主动修订文档或提示用户。
+
+---
+
+## 6. 版本控制与标签
+
+所有文档都应纳入 Git 版本控制。
+
+当一个 RT 完成时，推荐在：
+
+- 代码分支合并后打上 tag（例如 `done-RT-XXX`）；
+- 在 RT 的 `changelog.md` 中记录最终状态；
+- 如果本次 RT 涉及 AODW 制度本身的更新（例如修改了 `aodw-constitution.md`），应特别标注。
+
+---
+
+## 7. 过程文档管理规则
+
+过程文档是指在 RT 执行过程中产生的、用于记录分析、调研、决策等过程的文档。
+
+**存储位置**：必须存放在 `RT/RT-XXX/docs/` 目录下，禁止与核心文档混放在根目录。
+
+**命名规范**：使用小写字母和连字符（如 `dependency-installation-strategy.md`），避免使用序号前缀。
+
+**何时创建**：进行策略分析、技术调研、设计决策、问题诊断、修复总结时。
+
+**与核心文档的关系**：过程文档是对核心文档的补充和细化，不应替代核心文档。
+
+---
+
+## 8. 当信息缺失或不确定时
+
+如果 AI 判断文档中存在以下情况：
+
+- 信息缺失；
+- 描述明显过时；
+- 与代码行为明显矛盾；
+
+则 AI 应：
+
+1. 在当前 RT 中开辟一小节（可放在 `changelog.md` 或 `docs/` 目录下的单独文档中）记录发现的问题；
+2. 尝试基于当前代码自动修正文档；
+3. 在不确定时向用户提出明确问题，获取确认后再更新文档。
+
+AI 不应在发现明显不一致时保持沉默。
+
+---
+---
+
+## 9. RT 元数据与索引维护规则
+
+**元数据优先级**：`RT/RT-XXX/meta.yaml` 是权威来源，`RT/index.yaml` 是全局汇总。如不一致，以 meta.yaml 为准。
+
+**何时更新 meta.yaml**：RT 创建、类型/Profile/状态/模块/工具/负责人变更、RT 结束时。
+
+**何时更新 index.yaml**：新建 RT、meta.yaml 发生变更时同步更新。详细操作规范见 `.aodw/02-workflow/rt-manager.md` 第 9 节。
+
+**一致性检查**：RT 进入 `done` 状态前，检查 meta.yaml 与 index.yaml 是否一致。
+
+---
+
+## 9.5 时间字段获取规则
+
+⚠️ **重要**：所有时间字段必须使用系统真实时间，严禁 AI 自行推断或使用假时间。
+
+**详细规则**：请参考 `.aodw/02-workflow/rt-manager.md` 第 10 节"时间字段获取规则（强制要求）"。
+
+**关键要求**：
+- 必须通过系统命令或 API 获取真实时间
+- 禁止使用 AI 训练数据、对话上下文或自行推断的时间
+- 时间格式：ISO8601（如 `2025-11-28T11:54:45Z`）
+- 适用范围：`meta.yaml`、`RT/index.yaml`、`AODW_Governance/version.md` 等所有时间字段