ethan-skill 1.10.4 → 1.11.0

package/rules/cursor/.cursorrules

@@ -1,7 +1,7 @@
-# Ethan v1.8.0
+# Ethan v1.11.0
 
 > 自动生成 - 请勿手动修改，源文件：src/skills/
-> Generated at: 2026-03-31T16:55:43.257Z
+> Generated at: 2026-04-06T14:12:22.298Z
 
 ## 重要：Skill 激活规则
 
@@ -35,6 +35,8 @@
 - 代码重构：代码重构、refactoring、refactor
 - 可观测性：可观测性、observability、监控
 - 设计模式：设计模式、design pattern、design patterns
+- Spec Proposal：spec proposal、openspec proposal、生成提案
+- Spec Review（意图审查）：spec review、intent review、意图审查
 
 ---
 
@@ -3782,4 +3784,243 @@ export const db = createDbPool(); // 模块级单例，足够用
 
 ---
 
+## Skill 25：Spec Proposal
+
+**触发词**：`spec proposal`、`openspec proposal`、`生成提案`、`变更提案`、`spec 提案`、`写 proposal`、`@ethan spec proposal`、`/spec-proposal`
+
+**描述**：遵循 OpenSpec 规范，在编码前生成完整变更提案包（proposal + design + tasks + spec delta）
+
+### 1. 扫描现有 Spec 上下文
+
+查阅 openspec/specs/ 目录，了解已有规范：
+
+- 列出所有 capability 目录及其 spec.md 摘要
+- 识别本次变更涉及的 capability（可能跨多个）
+- 了解现有需求（Requirements）和场景（Scenarios）边界
+
+**如无 openspec 目录**：询问用户需要创建哪些 capability 的 spec，用 `ethan spec init [capability]` 初始化。
+
+**输出**：涉及的 spec 文件列表 + 关键现有需求摘要
+
+### 2. 生成 proposal.md（变更提案）
+
+生成 openspec/changes/[change-id]/proposal.md：
+
+```markdown
+# Change Proposal: [变更标题]
+
+> Change ID: [yyyymmdd-xxxx]
+
+## 变更描述
+[1-3 句话说明这个变更要做什么]
+
+## 动机与背景
+[为什么需要这个变更，解决什么业务问题]
+
+## 影响范围
+- 涉及的 Capability：[列表]
+- 影响的用户角色：[列表]
+- 影响的现有功能：[列表]
+
+## 非功能性考量
+- 性能影响：[说明或无]
+- 安全考量：[说明或无]
+- 向后兼容性：[说明]
+```
+
+### 3. 生成 design.md（技术方案）
+
+生成 openspec/changes/[change-id]/design.md：
+
+```markdown
+# Technical Design: [变更标题]
+
+## 架构决策
+[关键架构选择及原因，如技术选型、模式选择]
+
+## 接口变更
+[新增/修改的 API 端点、组件 Props、函数签名]
+
+## 数据模型变更
+[新增/修改的数据库表、数据结构]
+
+## 实现方案
+[核心实现思路，关键算法或流程]
+
+## 风险与缓解措施
+[技术风险点 → 对应缓解策略]
+```
+
+### 4. 生成 tasks.md（实现任务）
+
+生成 openspec/changes/[change-id]/tasks.md，按阶段拆分原子任务：
+
+```markdown
+# Implementation Tasks: [变更标题]
+
+## Phase 1: 基础准备
+- [ ] Task 1.1: [任务描述] | 估算：S/M/L
+
+## Phase 2: 核心实现
+- [ ] Task 2.1: [任务描述] | 估算：S/M/L
+
+## Phase 3: 测试与验收
+- [ ] Task 3.1: 编写单元测试，覆盖所有场景 AC
+- [ ] Task 3.2: Spec Review — 验证代码与 spec delta 对齐
+
+## 总估算
+S: [n] | M: [n] | L: [n]
+```
+
+每个任务应足够原子，可独立完成和验证。
+
+### 5. 生成 Spec Delta（需求变更）
+
+为每个涉及的 capability 生成需求变更文件（openspec/changes/[id]/specs/[capability].md）：
+
+```markdown
+# Spec Delta: [capability]
+
+> 变更描述：[本次变更对此 capability 的影响]
+
+## 新增需求
+
+### REQ-XXX: [新需求名称]
+[需求描述]
+
+## 修改需求
+
+**变更前：**
+[原需求内容]
+
+**变更后：**
+[新需求内容]
+
+## 新增场景
+
+GIVEN [前置条件]
+WHEN [用户操作]
+THEN [预期结果]
+```
+
+**原则**：Spec delta 只记录"变化"，不重复现有 spec 的未变更内容。
+
+**输出格式**：OpenSpec 变更提案包（保存到 openspec/changes/[change-id]/）：
+- proposal.md（变更提案）
+- design.md（技术方案）
+- tasks.md（分阶段任务）
+- specs/[capability].md（spec delta，每个涉及的 capability 一个文件）
+
+**注意事项**：
+- 提案应在编写任何代码之前生成，让团队先对变更意图达成共识
+- Spec delta 只记录"变化"，不重复现有 spec 内容
+- tasks.md 的每个任务应足够原子，可独立完成和验证
+- 如项目尚无 openspec 目录，先运行 ethan spec init [capability] 初始化
+
+---
+
+## Skill 26：Spec Review（意图审查）
+
+**触发词**：`spec review`、`intent review`、`意图审查`、`openspec review`、`spec 审查`、`需求对齐检查`、`@ethan spec review`、`/spec-review`
+
+**描述**：基于 OpenSpec，对比 spec delta 与代码实现，执行意图级 Review（而非逐行代码审查）
+
+### 1. 加载 Spec 上下文
+
+读取本次变更相关的 OpenSpec 文档：
+
+1. 定位 openspec/changes/[change-id]/ 目录（取最新的或由用户指定）
+2. 读取 proposal.md（了解变更目标和意图）
+3. 读取 specs/[capability].md（逐个 spec delta）
+4. 读取代码 diff（git diff HEAD 或 PR diff）
+
+**目标**：建立"期望变更"（spec delta）和"实际变更"（代码）的对照关系。
+
+如无 change proposal，说明本次改动未经过 spec 规范流程，建议先运行 `ethan spec proposal`。
+
+### 2. 意图对齐检查
+
+逐条检查每个 spec delta 条目是否在代码中得到正确实现：
+
+**对齐矩阵模板**
+
+| Spec 需求/场景 | 对应代码位置 | 对齐状态 | 说明 |
+|--------------|------------|---------|------|
+| REQ-XXX: [需求名] | [文件:行号] | ✅ | 完全实现 |
+| Scenario: [场景名] | [文件:行号] | ⚠️ | 边界条件缺失 |
+| REQ-YYY: [需求名] | — | ❌ | 未找到实现 |
+| [代码功能] | [文件:行号] | 🔄 | 超出 spec 范围 |
+
+**状态说明**
+- ✅ 完全实现：代码与 spec 意图一致，GIVEN/WHEN/THEN 均覆盖
+- ⚠️ 部分实现：核心逻辑存在但细节缺失（如缺少异常处理）
+- ❌ 未实现：spec 要求的功能在代码中找不到
+- 🔄 超范围：代码实现了 spec 未定义的内容
+
+### 3. 偏差识别与分级
+
+识别三类关键偏差：
+
+**🔴 意图偏差（Critical）—— 必须修复才能合并**
+代码实现与 spec 意图相反或严重不符，例如：
+- 场景要求"3次失败后锁定账号"，实际实现了"无限重试"
+- 权限检查逻辑与 GIVEN/WHEN/THEN 定义的场景不匹配
+- 数据模型与 spec delta 中定义的结构不一致
+
+**🟡 遗漏需求（Warning）—— 强烈建议补充**
+spec 中定义的场景或需求在代码中未体现：
+- 异常流程未处理（spec 中有 THEN [错误情况] 但代码未实现）
+- 边界条件未覆盖（如空值、超长输入、并发）
+- 非功能性需求未落实（如性能、安全要求）
+
+**💡 超范围实现（Info）—— 确认并按需更新 spec**
+代码实现了 spec 没有定义的功能：
+- 可能是合理的技术实现细节（不需要更新 spec）
+- 也可能是功能范围蔓延（需补充 spec delta 或回退）
+
+### 4. 输出 Spec Review 报告
+
+生成结构化的意图审查报告：
+
+```markdown
+# Spec Review Report
+
+## 变更提案摘要
+- Change ID: [id]
+- 变更目标：[proposal.md 核心摘要]
+- 涉及 Capability：[列表]
+
+## 意图对齐矩阵
+[对照表格]
+
+## 关键发现
+
+### 🔴 意图偏差（[n] 项）
+1. **[偏差描述]**
+   - Spec 要求：[spec 原文]
+   - 实际实现：[代码位置] [实际行为]
+   - 建议：[修复方向]
+
+### 🟡 遗漏需求（[n] 项）
+[列表]
+
+### 💡 超范围实现（[n] 项）
+[列表]
+
+## 审查结论
+- [ ] 意图完全对齐，可以合并
+- [ ] 需要修复意图偏差后重新审查
+- [ ] 需要更新 spec（超范围实现合理）
+```
+
+**输出格式**：Spec Review 报告：意图对齐矩阵 + 三级偏差列表（🔴意图偏差 / 🟡遗漏需求 / 💡超范围）+ 审查结论
+
+**注意事项**：
+- Spec Review 不替代 Code Review，两者互补：Spec Review 审意图，Code Review 审实现质量
+- 如果没有对应的 spec delta，说明该改动未经过规范的 spec 流程，需补充
+- 超范围实现不一定是问题，但必须显式确认并按需更新 spec
+- GIVEN/WHEN/THEN 场景是最好的对齐锚点，每个场景都应在代码中有对应的实现
+
+---
+
 *Ethan - Your AI Workflow Assistant | 让每一步都有据可依*

package/rules/cursor/smart-flow.mdc

@@ -4,10 +4,10 @@ globs:
 alwaysApply: true
 ---
 
-# Ethan v1.8.0
+# Ethan v1.11.0
 
 > 自动生成 - 请勿手动修改，源文件：src/skills/
-> Generated at: 2026-03-31T16:55:43.257Z
+> Generated at: 2026-04-06T14:12:22.298Z
 
 ## 重要：Skill 激活规则
 
@@ -47,6 +47,8 @@ alwaysApply: true
 | 代码重构 | `代码重构` |
 | 可观测性 | `可观测性` |
 | 设计模式 | `设计模式` |
+| Spec Proposal | `spec proposal` |
+| Spec Review（意图审查） | `spec review` |
 
 ---
 
@@ -3794,4 +3796,243 @@ export const db = createDbPool(); // 模块级单例，足够用
 
 ---
 
+## Skill 25：Spec Proposal
+
+**触发词**：`spec proposal`、`openspec proposal`、`生成提案`、`变更提案`、`spec 提案`、`写 proposal`、`@ethan spec proposal`、`/spec-proposal`
+
+**描述**：遵循 OpenSpec 规范，在编码前生成完整变更提案包（proposal + design + tasks + spec delta）
+
+### 1. 扫描现有 Spec 上下文
+
+查阅 openspec/specs/ 目录，了解已有规范：
+
+- 列出所有 capability 目录及其 spec.md 摘要
+- 识别本次变更涉及的 capability（可能跨多个）
+- 了解现有需求（Requirements）和场景（Scenarios）边界
+
+**如无 openspec 目录**：询问用户需要创建哪些 capability 的 spec，用 `ethan spec init [capability]` 初始化。
+
+**输出**：涉及的 spec 文件列表 + 关键现有需求摘要
+
+### 2. 生成 proposal.md（变更提案）
+
+生成 openspec/changes/[change-id]/proposal.md：
+
+```markdown
+# Change Proposal: [变更标题]
+
+> Change ID: [yyyymmdd-xxxx]
+
+## 变更描述
+[1-3 句话说明这个变更要做什么]
+
+## 动机与背景
+[为什么需要这个变更，解决什么业务问题]
+
+## 影响范围
+- 涉及的 Capability：[列表]
+- 影响的用户角色：[列表]
+- 影响的现有功能：[列表]
+
+## 非功能性考量
+- 性能影响：[说明或无]
+- 安全考量：[说明或无]
+- 向后兼容性：[说明]
+```
+
+### 3. 生成 design.md（技术方案）
+
+生成 openspec/changes/[change-id]/design.md：
+
+```markdown
+# Technical Design: [变更标题]
+
+## 架构决策
+[关键架构选择及原因，如技术选型、模式选择]
+
+## 接口变更
+[新增/修改的 API 端点、组件 Props、函数签名]
+
+## 数据模型变更
+[新增/修改的数据库表、数据结构]
+
+## 实现方案
+[核心实现思路，关键算法或流程]
+
+## 风险与缓解措施
+[技术风险点 → 对应缓解策略]
+```
+
+### 4. 生成 tasks.md（实现任务）
+
+生成 openspec/changes/[change-id]/tasks.md，按阶段拆分原子任务：
+
+```markdown
+# Implementation Tasks: [变更标题]
+
+## Phase 1: 基础准备
+- [ ] Task 1.1: [任务描述] | 估算：S/M/L
+
+## Phase 2: 核心实现
+- [ ] Task 2.1: [任务描述] | 估算：S/M/L
+
+## Phase 3: 测试与验收
+- [ ] Task 3.1: 编写单元测试，覆盖所有场景 AC
+- [ ] Task 3.2: Spec Review — 验证代码与 spec delta 对齐
+
+## 总估算
+S: [n] | M: [n] | L: [n]
+```
+
+每个任务应足够原子，可独立完成和验证。
+
+### 5. 生成 Spec Delta（需求变更）
+
+为每个涉及的 capability 生成需求变更文件（openspec/changes/[id]/specs/[capability].md）：
+
+```markdown
+# Spec Delta: [capability]
+
+> 变更描述：[本次变更对此 capability 的影响]
+
+## 新增需求
+
+### REQ-XXX: [新需求名称]
+[需求描述]
+
+## 修改需求
+
+**变更前：**
+[原需求内容]
+
+**变更后：**
+[新需求内容]
+
+## 新增场景
+
+GIVEN [前置条件]
+WHEN [用户操作]
+THEN [预期结果]
+```
+
+**原则**：Spec delta 只记录"变化"，不重复现有 spec 的未变更内容。
+
+**输出格式**：OpenSpec 变更提案包（保存到 openspec/changes/[change-id]/）：
+- proposal.md（变更提案）
+- design.md（技术方案）
+- tasks.md（分阶段任务）
+- specs/[capability].md（spec delta，每个涉及的 capability 一个文件）
+
+**注意事项**：
+- 提案应在编写任何代码之前生成，让团队先对变更意图达成共识
+- Spec delta 只记录"变化"，不重复现有 spec 内容
+- tasks.md 的每个任务应足够原子，可独立完成和验证
+- 如项目尚无 openspec 目录，先运行 ethan spec init [capability] 初始化
+
+---
+
+## Skill 26：Spec Review（意图审查）
+
+**触发词**：`spec review`、`intent review`、`意图审查`、`openspec review`、`spec 审查`、`需求对齐检查`、`@ethan spec review`、`/spec-review`
+
+**描述**：基于 OpenSpec，对比 spec delta 与代码实现，执行意图级 Review（而非逐行代码审查）
+
+### 1. 加载 Spec 上下文
+
+读取本次变更相关的 OpenSpec 文档：
+
+1. 定位 openspec/changes/[change-id]/ 目录（取最新的或由用户指定）
+2. 读取 proposal.md（了解变更目标和意图）
+3. 读取 specs/[capability].md（逐个 spec delta）
+4. 读取代码 diff（git diff HEAD 或 PR diff）
+
+**目标**：建立"期望变更"（spec delta）和"实际变更"（代码）的对照关系。
+
+如无 change proposal，说明本次改动未经过 spec 规范流程，建议先运行 `ethan spec proposal`。
+
+### 2. 意图对齐检查
+
+逐条检查每个 spec delta 条目是否在代码中得到正确实现：
+
+**对齐矩阵模板**
+
+| Spec 需求/场景 | 对应代码位置 | 对齐状态 | 说明 |
+|--------------|------------|---------|------|
+| REQ-XXX: [需求名] | [文件:行号] | ✅ | 完全实现 |
+| Scenario: [场景名] | [文件:行号] | ⚠️ | 边界条件缺失 |
+| REQ-YYY: [需求名] | — | ❌ | 未找到实现 |
+| [代码功能] | [文件:行号] | 🔄 | 超出 spec 范围 |
+
+**状态说明**
+- ✅ 完全实现：代码与 spec 意图一致，GIVEN/WHEN/THEN 均覆盖
+- ⚠️ 部分实现：核心逻辑存在但细节缺失（如缺少异常处理）
+- ❌ 未实现：spec 要求的功能在代码中找不到
+- 🔄 超范围：代码实现了 spec 未定义的内容
+
+### 3. 偏差识别与分级
+
+识别三类关键偏差：
+
+**🔴 意图偏差（Critical）—— 必须修复才能合并**
+代码实现与 spec 意图相反或严重不符，例如：
+- 场景要求"3次失败后锁定账号"，实际实现了"无限重试"
+- 权限检查逻辑与 GIVEN/WHEN/THEN 定义的场景不匹配
+- 数据模型与 spec delta 中定义的结构不一致
+
+**🟡 遗漏需求（Warning）—— 强烈建议补充**
+spec 中定义的场景或需求在代码中未体现：
+- 异常流程未处理（spec 中有 THEN [错误情况] 但代码未实现）
+- 边界条件未覆盖（如空值、超长输入、并发）
+- 非功能性需求未落实（如性能、安全要求）
+
+**💡 超范围实现（Info）—— 确认并按需更新 spec**
+代码实现了 spec 没有定义的功能：
+- 可能是合理的技术实现细节（不需要更新 spec）
+- 也可能是功能范围蔓延（需补充 spec delta 或回退）
+
+### 4. 输出 Spec Review 报告
+
+生成结构化的意图审查报告：
+
+```markdown
+# Spec Review Report
+
+## 变更提案摘要
+- Change ID: [id]
+- 变更目标：[proposal.md 核心摘要]
+- 涉及 Capability：[列表]
+
+## 意图对齐矩阵
+[对照表格]
+
+## 关键发现
+
+### 🔴 意图偏差（[n] 项）
+1. **[偏差描述]**
+   - Spec 要求：[spec 原文]
+   - 实际实现：[代码位置] [实际行为]
+   - 建议：[修复方向]
+
+### 🟡 遗漏需求（[n] 项）
+[列表]
+
+### 💡 超范围实现（[n] 项）
+[列表]
+
+## 审查结论
+- [ ] 意图完全对齐，可以合并
+- [ ] 需要修复意图偏差后重新审查
+- [ ] 需要更新 spec（超范围实现合理）
+```
+
+**输出格式**：Spec Review 报告：意图对齐矩阵 + 三级偏差列表（🔴意图偏差 / 🟡遗漏需求 / 💡超范围）+ 审查结论
+
+**注意事项**：
+- Spec Review 不替代 Code Review，两者互补：Spec Review 审意图，Code Review 审实现质量
+- 如果没有对应的 spec delta，说明该改动未经过规范的 spec 流程，需补充
+- 超范围实现不一定是问题，但必须显式确认并按需更新 spec
+- GIVEN/WHEN/THEN 场景是最好的对齐锚点，每个场景都应在代码中有对应的实现
+
+---
+
 *Ethan - Your AI Workflow Assistant | 让每一步都有据可依*