aodw-skill 0.7.3

package/.aodw/02-workflow/aodw-development-stages.md

@@ -0,0 +1,235 @@
+# AODW 开发阶段分析
+
+## 阶段总览
+
+AODW 将开发过程分为 7 个主要阶段，对应 RT 状态机：created → intaking → decided → in-progress → reviewing → done
+
+---
+
+## 阶段 1: Intake（立项）
+
+**状态转换**: created → intaking → decided
+
+**主要任务**:
+- 生成 RT-ID（RT-{seq}）
+- 创建 RT 目录结构（RT/RT-XXX/）
+- 通过交互式提问收集需求信息
+- 记录原始描述、问题与答案
+- 初步判断需求类型（Feature/Bug/Enhancement/Refactor/Research）
+
+**阶段目标**: 明确需求范围、风险等级、影响模块估计，为 Profile 决策做准备
+
+**输出物**:
+- `RT/RT-XXX/meta.yaml`（RT 元数据）
+- `RT/RT-XXX/intake.md`（立项记录）
+- `RT/index.yaml`（全局索引更新）
+
+**协作方式**:
+- AI: 主动提出澄清问题，每个问题提供 2-5 个选项，给出推荐选项和理由
+- 用户: 选择推荐项或提供简短自定义答案（≤5 词），回答业务相关问题
+
+---
+
+## 阶段 2: Decision（决策）
+
+**状态转换**: intaking → decided
+
+**主要任务**:
+- 根据 Intake 信息判断复杂度
+- 选择 Spec-Full 或 Spec-Lite profile
+- 创建 feature 分支（feature/RT-XXX-{short-name}）
+- 切换到 feature 分支并验证
+
+**阶段目标**: 确定开发模式，创建并切换到正确的 feature 分支
+
+**输出物**:
+- `RT/RT-XXX/decision.md`（决策记录，包含选择理由）
+- feature 分支（已创建并切换）
+
+**协作方式**:
+- AI: 分析复杂度，推荐 Profile（Full/Lite），解释推荐理由，创建分支
+- 用户: 确认推荐方案或显式切换 Profile，确认分支名
+
+**关键检查点**: 必须验证当前在 feature 分支上，严禁在 main/master 分支修改代码
+
+**CSF 审查（推荐）**: Decision 阶段完成后，建议执行 CSF 审查，验证 Profile 选择是否合理，目标与复杂度是否匹配。详见 `.aodw/01-core/csf-thinking-framework.md`
+
+---
+
+## 阶段 3: Analysis（分析）
+
+**状态转换**: decided → in-progress
+
+**主要任务**:
+- 影响分析：识别直接/间接影响的模块、文件、功能
+- 不变量检查：列出必须保持不变的行为、接口、约束
+- 风险评估：数据损坏、安全、性能、用户体验风险
+
+**阶段目标**: 明确变更边界和约束条件，避免破坏现有功能
+
+**输出物**:
+- `RT/RT-XXX/impact.md`（影响分析）
+- `RT/RT-XXX/invariants.md`（不变量清单）
+
+**协作方式**:
+- AI: 主导分析，自动识别影响范围，列出不变量
+- 用户: 确认关键约束，补充业务层面的不变量
+
+**触发条件**: 在修改代码前必须完成此阶段
+
+---
+
+## 阶段 4: Spec/Plan（规格/计划）
+
+**状态**: in-progress
+
+**主要任务**:
+
+**Spec-Full**:
+- 编写完整需求说明（spec.md）：背景、目标、用户故事、功能/非功能需求、成功标准
+- 编写技术实现方案（plan.md）：技术背景、方案概览、组件变更、代码结构与分层设计、数据流、风险缓解、分阶段计划
+- 编写数据模型文档（data-model.md，如涉及）
+- 编写契约文档（contracts/，如涉及）
+- 编写任务清单（tasks.md，按 User Story 和 Phase 拆分）
+- 编写质量检查清单（checklists/）
+
+**Spec-Lite**:
+- 编写精简需求说明（spec-lite.md）：背景、目标、当前/期望行为、影响范围
+- 编写精简技术方案（plan-lite.md）：修改点、方案描述、代码结构与分层设计、风险注意事项
+
+**阶段目标**: 明确"做什么"和"怎么做"，确保方案符合编码规范
+
+**输出物**:
+- Spec-Full: `spec.md`, `plan.md`, `data-model.md`, `contracts/`, `tasks.md`, `checklists/`
+- Spec-Lite: `spec-lite.md`, `plan-lite.md`
+
+**协作方式**:
+- AI: 基于 Intake 信息自动生成文档，确保符合编码规范（前端/后端）
+- 用户: 审阅 spec/plan，从业务视角确认方案合理性，批准执行计划
+
+**关键检查点**: Plan 完成后必须暂停，展示摘要，询问"计划已就绪，是否批准执行？"，严禁未获批准前开始修改代码
+
+**CSF 审查（必须）**: Plan 完成后，在进入"计划批准"节点前，**必须**执行 CSF 审查。审查重点：验证方案是否直接贡献于目标、分解是否 MECE、识别 CSF、检查端到端关键路径、评估技术方案合理性。详见 `.aodw/01-core/csf-thinking-framework.md`
+
+---
+
+## 阶段 5: Implementation（实现）
+
+**状态**: in-progress
+
+**主要任务**:
+- 开发准备（Dev Ready）：
+  - 检查工具已初始化（.aodw/tools-status.yaml）
+  - 加载编码规范（前端/后端/通用）
+- 在 feature 分支上实现代码修改：
+  - 遵守项目编码规范
+  - 通过工具自动检查（ESLint/Ruff/Black）
+  - 符合 plan.md 中设计的代码结构与分层
+- 开发结束前自检：
+  - 运行 Lint 检查
+  - 运行格式化检查
+  - 验证文件大小和复杂度符合规范
+- 编写/更新测试文档（tests.md）
+- 更新变更日志（changelog.md）
+- 更新模块文档（如涉及）
+
+**阶段目标**: 实现功能，确保代码质量和规范符合性
+
+**输出物**:
+- 代码修改（在 feature 分支上）
+- `RT/RT-XXX/tests.md`（测试用例列表）
+- `RT/RT-XXX/changelog.md`（变更总结）
+- 模块 README 更新（如涉及）
+
+**协作方式**:
+- AI: 主导代码实现，自动运行检查工具，更新文档，维护 task.md（如需要）
+- 用户: 确认关键实现决策，验证功能是否符合预期
+
+**关键检查点**: 
+- 每次写代码前必须验证当前在 feature 分支
+- 提交代码前必须展示 git status 和关键 diff，询问"修改已完成，是否提交？"
+
+---
+
+## 阶段 6: Verification（验证）
+
+**状态转换**: in-progress → reviewing
+
+**主要任务**:
+- 文档一致性检查：
+  - spec/plan 是否完整记录了问题→方案→实现过程
+  - impact/invariants/tests/changelog 是否完整
+  - 数据模型/接口变更是否已更新相关文档
+  - 模块文档是否已更新
+- RT 完整性检查：
+  - 核心文档是否齐全
+  - 过程文档是否在正确位置（RT/RT-XXX/docs/）
+  - meta.yaml 与 index.yaml 是否一致
+
+**阶段目标**: 确保 RT 文档完整、一致，符合 AODW 规范
+
+**输出物**:
+- 验证结果报告
+- 修正后的文档（如发现不一致）
+
+**协作方式**:
+- AI: 自动执行一致性检查，发现不一致时主动修正或提示
+- 用户: 确认验证结果，必要时补充信息
+
+**CSF 审查（推荐）**: Verification 阶段应执行 CSF 审查，不仅检查文档一致性，还要检查目标达成度、验证端到端关键路径、评估多维决策合理性。详见 `.aodw/01-core/csf-thinking-framework.md`
+
+---
+
+## 阶段 7: Completion（完成）
+
+**状态转换**: reviewing → done
+
+**主要任务**:
+- 知识蒸馏（Knowledge Distillation）：
+  - 读取 modules-index.yaml，找到受影响的模块
+  - 更新对应的模块文档（docs/modules/*.md）
+  - 确认文档与代码一致
+- 提供完成脚本（AI 不得自动执行）：
+  - 确认在 feature 分支
+  - 确认所有改动已提交
+  - 切换到主分支并拉取最新代码
+  - 合并 feature 分支（--no-ff）
+  - 打标签（done-RT-XXX）
+  - 推送代码和标签
+  - 删除本地 feature 分支
+  - 更新 RT 状态为 done
+
+**阶段目标**: 完成代码合并，更新全局状态，确保知识库同步
+
+**输出物**:
+- 合并后的代码（在主分支）
+- `done-RT-XXX` 标签
+- 更新的模块文档
+- `RT/RT-XXX/meta.yaml`（status: done, closed_at）
+- `RT/index.yaml`（状态更新）
+
+**协作方式**:
+- AI: 执行知识蒸馏，提供完整的手动命令脚本，更新 RT 状态
+- 用户: 验证代码质量，验证文档更新，手动执行合并和推送脚本，验证推送结果
+
+**关键规则**: AI 禁止自动执行合并、推送、删除分支操作，必须提供脚本由用户手动执行
+
+---
+
+## 状态机总览
+
+```
+created → intaking → decided → in-progress → reviewing → done
+  ↓         ↓          ↓           ↓            ↓         ↓
+Intake   Intake    Decision   Analysis/    Verification Completion
+                        Spec/Plan/
+                    Implementation
+```
+
+## 关键原则
+
+1. **分支管理**: 所有代码修改必须在 feature 分支上进行，严禁在 main/master 分支直接修改
+2. **文档同步**: 文档必须与代码保持同步，文档与代码不一致视为 Bug
+3. **选项化提问**: AI 所有关键问题应提供选项和推荐，用户只需选择
+4. **主动推进**: AI 应主动推进流程，不等待具体命令
+5. **工具无关**: 行为通过仓库文档约束，不依赖特定工具配置

package/.aodw/02-workflow/rt-id-generation-rules.md

@@ -0,0 +1,267 @@
+# RT-ID 获取规则（强制要求）
+
+⚠️ **关键规则**：AI 在创建新 RT 时，**必须**先检查 `.aodw/config.yaml` 确定开发模式，然后按照相应规则获取 RT-ID。
+
+本文件定义了 AODW 中 RT-ID（Request Ticket ID）的获取规则，确保团队协作时 ID 的唯一性和一致性。
+
+---
+
+## 1. 配置文件检查流程
+
+**强制检查步骤**（AI 必须按顺序执行）：
+
+1. **读取配置文件**
+   - 路径：`.aodw/config.yaml`
+   - 必须读取 `mode` 和 `server_url` 字段
+
+2. **确定开发模式**
+   - 如果 `mode === 'collaborative'`：协作模式（从远程服务器获取）
+   - 如果 `mode === 'independent'` 或未设置：独立模式（本地生成）
+   - 如果 `mode` 字段不存在：默认为独立模式
+
+3. **执行相应获取逻辑**
+   - 根据模式执行对应的 RT-ID 获取流程（见第 2 节和第 3 节）
+
+---
+
+## 2. 协作模式（Collaborative Mode）
+
+**适用场景**：团队协作开发，需要统一的 RT-ID 分配，避免 ID 冲突。
+
+**配置要求**：
+```yaml
+# .aodw/config.yaml
+mode: collaborative
+server_url: http://114.67.218.31:2005  # 或团队自定义服务器地址
+```
+
+**RT-ID 获取流程**：
+
+1. **验证配置**
+   - ✅ 检查 `mode === 'collaborative'`
+   - ✅ 检查 `server_url` 是否存在且非空
+   - ❌ 如果 `server_url` 为空：**立即报错**，提示用户配置服务器地址
+
+2. **调用远程 API**
+   - 端点：`{server_url}/api/next-id?project={project_name}`
+   - 方法：`GET`
+   - 默认服务器：`http://114.67.218.31:2005`
+   - ⚠️ **强制要求**：**必须**带上 `project` 参数，否则服务器无法正确分配 ID
+   - 项目名获取优先级：
+     1. 命令行参数 `--project <name>`
+     2. `.aodw/project.yaml` 的 `project_name` 字段
+     3. `package.json` 的 `name` 字段
+     4. 当前目录名（fallback）
+
+3. **处理响应**
+   - 成功：使用返回的 `id` 字段（格式：`RT-XXX`）
+   - 失败：提示错误信息，询问是否降级到本地生成（**不推荐**，可能导致冲突）
+
+4. **本地 vs 服务器 ID 冲突处理**（⚠️ 重要）
+   
+   **问题场景**：服务器返回的 ID 可能小于本地已有的最大 ID（例如离线创建或服务器数据不同步）。
+   
+   **强制规则**：
+   - 获取服务器 ID 后，必须与本地最大 ID 比较
+   - 如果 `服务器 ID ≤ 本地最大 ID`，则使用 `本地最大 ID + 1`
+   - 同时调用服务器 API 更新服务器端的计数器
+   
+   **比较逻辑**：
+   ```
+   serverSeq = 从服务器 ID 提取序号（如 RT-015 → 15）
+   localMaxSeq = 本地 RT/ 目录下最大序号（如已有 RT-016 → 16）
+   
+   if (serverSeq <= localMaxSeq) {
+       finalSeq = localMaxSeq + 1
+       finalId = `RT-${padStart(finalSeq, 3, '0')}`
+       // 调用服务器 API 更新计数器
+       syncIdToServer(serverUrl, project, finalSeq)
+   } else {
+       finalId = 服务器返回的 ID
+   }
+   ```
+   
+   **服务器同步 API**：
+   - 端点：`{server_url}/api/sync-id?project={project_name}&seq={finalSeq}`
+   - 方法：`POST`
+   - 作用：将服务器计数器更新为 `finalSeq`，确保下次获取的 ID 正确
+
+5. **错误处理**
+   - 网络错误：提示检查网络连接和服务器状态
+   - 服务器错误：提示联系管理员或检查服务器配置
+   - 超时：提示重试或检查服务器状态
+   - 同步失败：记录警告，但不阻塞 RT 创建
+
+**示例代码逻辑**：
+```javascript
+if (userConfig.mode === 'collaborative') {
+    if (!serverUrl || serverUrl.trim() === '') {
+        // 必须报错，不能静默降级
+        throw new Error('Collaborative mode requires server_url');
+    }
+    
+    // ⚠️ 必须带上项目标识
+    // 项目名获取优先级：命令行参数 > .aodw/project.yaml > package.json > 目录名
+    const project = getProjectName(); // 必须获取项目标识
+    
+    // 调用远程 API（必须带上 project 参数）
+    let serverId = await fetchIdFromServer(serverUrl, project);
+    let serverSeq = parseInt(serverId.replace('RT-', ''), 10);
+    
+    // 获取本地最大 ID
+    let localMaxSeq = getLocalMaxSeq();
+    
+    // 比较并选择
+    if (serverSeq <= localMaxSeq) {
+        let finalSeq = localMaxSeq + 1;
+        id = `RT-${String(finalSeq).padStart(3, '0')}`;
+        console.warn(`服务器 ID (${serverId}) ≤ 本地最大 ID (RT-${localMaxSeq})，使用本地 ID: ${id}`);
+        
+        // 同步到服务器（必须带上 project 参数）
+        await syncIdToServer(serverUrl, project, finalSeq);
+    } else {
+        id = serverId;
+    }
+} else {
+    // 独立模式：强制本地生成，忽略 server_url
+    id = getLocalNextId();
+    // 即使配置了 server_url，也不会联网
+}
+```
+
+
+---
+
+## 3. 独立模式（Independent Mode）
+
+**适用场景**：个人开发或小团队，不需要统一的 ID 分配。
+
+**配置要求**：
+```yaml
+# .aodw/config.yaml
+mode: independent
+# server_url 即使配置也会被忽略，不会联网
+```
+
+**RT-ID 获取流程**：
+
+1. **强制本地生成**
+   - ⚠️ **关键规则**：独立模式下**必须**使用本地生成，**禁止**联网获取
+   - 即使配置了 `server_url`，也会被忽略，不会发起任何网络请求
+   - 这是为了确保用户选择独立模式后，完全离线工作
+
+2. **本地生成逻辑**
+   - 扫描 `RT/` 目录下所有 `RT-XXX` 格式的目录
+   - 找到最大序号 `N`
+   - 生成新 ID：`RT-{N+1}`（补零到 3 位，如 `RT-001`, `RT-002`）
+
+3. **冲突检查**
+   - 如果生成的 ID 对应的目录已存在：递增序号直到找到可用 ID
+
+---
+
+## 4. 决策树（Decision Tree）
+
+AI 在创建 RT 时必须遵循以下决策树：
+
+```
+开始创建 RT
+    ↓
+读取 .aodw/config.yaml
+    ↓
+mode 字段存在？
+    ├─ 是 → mode === 'collaborative'?
+    │          ├─ 是 → 检查 server_url
+    │          │          ├─ 存在且非空 → 调用远程 API 获取 RT-ID
+    │          │          └─ 不存在或为空 → ❌ 报错，提示配置服务器
+    │          └─ 否 → 独立模式
+    │                  └─ 本地生成 RT-ID（忽略 server_url）
+    └─ 否 → 独立模式（默认）
+            └─ 本地生成 RT-ID
+```
+
+---
+
+## 5. 强制检查清单
+
+AI 在获取 RT-ID 前必须完成以下检查：
+
+- [ ] ✅ 已读取 `.aodw/config.yaml` 文件
+- [ ] ✅ 已确定 `mode` 字段的值
+- [ ] ✅ 如果是协作模式，已验证 `server_url` 存在且非空
+- [ ] ✅ 已确定项目名称（从 `.aodw/project.yaml` 或目录名获取）
+- [ ] ✅ 已按照决策树执行相应的获取流程
+- [ ] ✅ 已验证获取到的 RT-ID 格式正确（`RT-XXX`）
+- [ ] ✅ 已检查 RT-ID 对应的目录不存在（避免冲突）
+
+---
+
+## 6. 常见错误与处理
+
+| 错误情况          | 原因                   | 处理方式                                    |
+| ----------------- | ---------------------- | ------------------------------------------- |
+| `server_url` 为空 | 协作模式下未配置服务器 | ❌ **必须报错**，提示运行 `aodw config` 配置 |
+| 网络连接失败      | 无法访问远程服务器     | 提示检查网络，询问是否降级（警告风险）      |
+| 服务器返回错误    | 服务器端问题           | 提示联系管理员，记录错误信息                |
+| 本地目录冲突      | 生成的 ID 已存在       | 自动递增序号，直到找到可用 ID               |
+
+---
+
+## 7. 配置示例
+
+**协作模式配置**（推荐团队使用）：
+```yaml
+# .aodw/config.yaml
+mode: collaborative
+server_url: http://114.67.218.31:2005
+```
+
+**独立模式配置**（个人开发）：
+```yaml
+# .aodw/config.yaml
+mode: independent
+```
+
+**独立模式配置说明**：
+```yaml
+# .aodw/config.yaml
+mode: independent
+# server_url 即使配置也会被忽略，不会联网
+```
+
+---
+
+## 8. 执行规范
+
+**AI 必须遵守的规则**：
+
+1. **禁止静默降级**：协作模式下如果 `server_url` 为空，**必须报错**，不能自动降级到本地生成
+2. **必须检查配置**：创建 RT 前必须先读取 `.aodw/config.yaml`
+3. **必须验证模式**：根据 `mode` 字段执行对应的获取逻辑
+4. **独立模式禁止联网**：独立模式下**必须**使用本地生成，**禁止**联网，即使配置了 `server_url` 也要忽略
+5. **必须带上项目标识**：协作模式下调用服务器 API 时，**必须**带上 `project` 参数，否则服务器无法正确分配 ID
+6. **必须处理错误**：网络错误或服务器错误时，必须明确提示用户
+7. **必须验证 ID**：获取到 RT-ID 后，必须验证格式和唯一性
+
+**违反规则的后果**：
+- 如果 AI 在协作模式下静默使用本地生成，可能导致团队内 ID 冲突
+- 如果 AI 未检查配置就生成 ID，可能使用错误的模式
+
+---
+
+## 9. 相关文档
+
+- `.aodw/02-workflow/rt-manager.md` - RT-Manager 完整规范
+- `.aodw/01-core/aodw-constitution.md` - AODW 宪法（包含 RT-Manager 概述）
+- `cli/bin/commands/new.js` - RT 创建命令实现
+
+---
+
+## 10. 服务器部署
+
+如需部署自己的 RT-ID 服务器，请参考：
+- `cli/DEPLOY.md` - 服务器部署指南
+- `cli/test-server.js` - 服务器测试脚本
+- `cli/TEST-SERVER.md` - 测试文档
+
+默认服务器地址：`http://114.67.218.31:2005`

package/.aodw/02-workflow/rt-manager-summary.md

@@ -0,0 +1,15 @@
+# RT-Manager Summary
+
+## 主要职责
+- RT 编号、目录、分支管理
+- Intake 流程与 Spec-Full/Spec-Lite 分流
+- 状态机维护：created → intakeing → decided → in-progress → reviewing → done
+
+## 强制前置检查
+- 必须在 feature 分支上工作
+- 未切分支不得修改业务代码
+
+## 核心门禁
+- decided → in-progress 前必须具备 spec/plan
+- Plan 完成后必须等待用户确认
+- 提交前必须展示 diff 与 status