ethan-skill 1.15.2 → 1.15.3

package/rules/cursor/smart-flow.mdc

@@ -4,10 +4,10 @@ globs:
 alwaysApply: true
 ---
 
-# Ethan v1.15.0
+# Ethan v1.15.2
 
 > 自动生成 - 请勿手动修改，源文件：src/skills/
-> Generated at: 2026-04-11T16:46:27.639Z
+> Generated at: 2026-04-14T03:12:49.305Z
 
 ## 重要：Skill 激活规则
 
@@ -59,6 +59,8 @@ alwaysApply: true
 | 移动端专项审查 | `移动端审查` |
 | 数据管道设计 | `数据管道` |
 | ML 实验管理 | `ml experiment` |
+| 自动修复 | `自动修复` |
+| Agent 记忆 | `agent 记忆` |
 
 ---
 
@@ -6985,4 +6987,402 @@ if drift_detected:
 
 ---
 
+## Skill 37：自动修复
+
+**触发词**：`自动修复`、`auto fix`、`auto-fix`、`CI 失败`、`ci failed`、`测试失败`、`test failed`、`lint 报错`、`lint error`、`修复失败`、`fix failing tests`、`自动迭代修复`、`@ethan fix`、`@ethan auto-fix`、`/auto-fix`
+
+**描述**：读取 CI/测试/Lint 失败信息，自动分析根因、生成修复方案并迭代验证，直到通过（最多 3 轮）
+
+### 1. 收集失败信息
+
+收集所有可用的失败上下文：
+
+**信息来源（优先级从高到低）**
+- CI 流水线日志（完整 stderr/stdout，不截断）
+- 测试框架输出（Jest / Vitest / PyTest / Go test）
+- Lint 报告（ESLint / Prettier / tsc / pylint）
+- 构建错误（webpack / vite / tsc）
+- 运行时异常（stack trace + 上下文代码）
+
+**必须提取的字段**
+```
+失败类型:    [ 测试失败 | Lint | 类型错误 | 构建失败 | 运行时错误 ]
+失败文件:    [文件路径:行号]
+错误信息:    [原始错误文本，保留完整 stack trace]
+触发条件:    [哪个命令/步骤触发]
+上次绿灯:   [最近一次通过的 commit / 时间（如可获取）]
+```
+
+> 如果日志超长，提取前 100 行 + 最后 50 行，优先保留 "FAILED"、"ERROR"、"at " 行。
+
+### 2. 根因分析
+
+对每个失败逐一诊断根因，区分「直接原因」和「根本原因」：
+
+**失败类型与常见根因速查**
+
+| 失败类型 | 直接原因 | 根本原因示例 |
+|---------|---------|------------|
+| 测试断言失败 | 返回值与预期不符 | 业务逻辑变更未同步更新测试 |
+| 测试超时 | 异步未正确 resolve | 缺少 await 或 mock 配置不当 |
+| 类型错误 | interface 不匹配 | API 变更未更新消费方类型 |
+| Lint 报错 | 代码风格违规 | 缺少 import、未使用变量、规则变更 |
+| 构建失败 | 模块未找到 | 路径别名配置、缺少依赖 |
+| 运行时错误 | 空指针/未定义 | 边界条件未处理 |
+
+**输出根因诊断表**
+```
+失败 #1
+  文件:       src/auth/login.test.ts:42
+  错误:       Expected "invalid" but received "error"
+  直接原因:   返回值从 "error" 改为 "invalid"
+  根本原因:   auth.ts 第 89 行修改了错误码但未同步测试
+  修复难度:   🟢 简单（更新测试断言）
+  可自动修复: ✅
+
+失败 #2
+  文件:       src/utils/parser.ts:15
+  错误:       Type 'string | null' is not assignable to 'string'
+  直接原因:   getUser() 返回值新增了 null 类型
+  根本原因:   API 层变更未向下传播 null 处理
+  修复难度:   🟡 中等（需添加 null guard）
+  可自动修复: ✅
+```
+
+### 3. 生成修复方案（Round 1）
+
+针对每个可自动修复的失败，生成最小化修复方案：
+
+**修复原则**
+- 最小改动原则：只修改必须改的代码
+- 不引入新问题：修复后不能导致其他测试失败
+- 保持语义一致：修复逻辑应符合原始意图
+- 优先修代码而非修测试（除非测试本身写错了）
+
+**分优先级处理**
+1. 🔴 **先修 Blocker**：类型错误、构建失败（影响所有后续步骤）
+2. 🟡 **再修测试**：断言失败、Mock 配置（影响覆盖率报告）
+3. 🟢 **最后修 Lint**：风格问题（不影响功能，可批量修复）
+
+**Lint 批量自动修复命令**
+```bash
+npx eslint src --fix
+npx prettier src --write
+```
+
+**输出修复 Diff（每个失败一个代码块）**
+```diff
+// 修复 #1：更新测试断言
+- expect(result).toBe('error');
++ expect(result).toBe('invalid');
+
+// 修复 #2：添加 null guard
+- const name = getUser().name;
++ const user = getUser();
++ const name = user?.name ?? '';
+```
+
+### 4. 应用修复并验证
+
+应用修复方案后立即验证：
+
+**验证步骤（按失败类型）**
+```bash
+# 测试失败
+npx vitest run [changed-test-file]   # 先跑单文件，快速反馈
+npx vitest run                        # 再跑全量，确认无新增失败
+
+# 类型错误
+npx tsc --noEmit                     # 全量类型检查
+
+# Lint 错误
+npx eslint src --max-warnings 0      # 不允许遗留 warning
+
+# 构建失败
+npm run build                        # 完整构建验证
+```
+
+**验证结果记录**
+```
+Round 1 结果：
+  修复前：❌ 3 失败（2 测试 + 1 类型错误）
+  修复后：
+    ✅ 测试失败 #1 — 已修复（断言更新）
+    ✅ 类型错误 #2 — 已修复（null guard）
+    ❌ 测试失败 #3 — 仍失败（需进入 Round 2）
+```
+
+### 5. 迭代修复（Round 2-3）
+
+如果 Round 1 仍有失败，进入迭代模式：
+
+**迭代策略**
+- **Round 2**：针对剩余失败，进行更深入的根因分析（可能是 Round 1 修复引入了副作用）
+- **Round 3**：最终尝试，优先保证 CI 通过（允许临时 skip 不稳定测试，但必须标注 @todo）
+
+**副作用检测**（重要）
+```
+检查 Round 1 修复后的新增失败：
+- 是否有原本通过的测试现在失败了？
+- 如果有，优先回退引入副作用的修改，重新设计方案
+```
+
+**Round 3 后仍失败的处理**
+```markdown
+## ⚠️ 需要人工介入
+
+以下失败无法通过自动修复解决：
+
+### 失败 #X
+- **错误**：[原始错误]
+- **已尝试**：[已尝试的修复方案]
+- **失败原因**：[为什么自动修复不可行]
+- **建议人工处理**：[具体建议步骤]
+- **最低可行方案**：暂时 skip 此测试，添加 TODO 注释：
+  `// TODO(@owner): fix in #issue-number — [简短原因]`
+```
+
+**迭代上限约束**
+- 最多 3 轮迭代，防止无限循环
+- 每轮必须有至少 1 个失败被修复，否则停止并输出人工介入指引
+
+### 6. 输出修复报告
+
+所有轮次完成后，输出结构化修复报告：
+
+```markdown
+## Auto-Fix 修复报告
+
+### 修复概览
+- **总失败数**：X
+- **自动修复**：Y（Y/X）
+- **需人工处理**：Z
+- **迭代轮次**：N 轮
+
+### 修复详情
+
+| # | 文件 | 错误类型 | 修复方式 | 状态 |
+|---|------|---------|---------|------|
+| 1 | src/auth.ts:42 | 断言失败 | 更新期望值 | ✅ Round 1 |
+| 2 | src/utils.ts:15 | 类型错误 | 添加 null guard | ✅ Round 1 |
+| 3 | src/api.ts:88 | 集成测试 | 更新 Mock 配置 | ✅ Round 2 |
+
+### 代码变更摘要
+[修改的文件列表 + 每处修改的简短说明]
+
+### 需要人工介入
+[如有，列出无法自动修复的项目 + 建议]
+
+### 预防建议
+- [导致此次失败的系统性问题]
+- [建议的规范或流程改进]
+```
+
+**输出格式**：Markdown 修复报告：根因诊断表 + 分 Round 修复 Diff + 验证结果 + 人工介入指引（如有）
+
+**注意事项**：
+- 优先修代码而非修测试——除非测试本身写错了
+- 每轮修复后必须验证，确认无副作用后再继续
+- 3 轮迭代上限是硬约束，防止循环修复
+- 临时 skip 测试时必须留下 TODO 注释，不允许无理由 skip
+- Lint 可以批量 --fix，但需检查 fix 后的语义是否正确
+
+---
+
+## Skill 38：Agent 记忆
+
+**触发词**：`agent 记忆`、`agent memory`、`持久化记忆`、`persistent memory`、`记住这个`、`remember this`、`跨会话记忆`、`项目决策记录`、`注入上下文`、`inject context`、`@ethan memory`、`@ethan agent-memory`、`/agent-memory`
+
+**描述**：提取并持久化项目关键决策、架构约束与已解决问题，跨会话注入 Agent 上下文，消除重复探索
+
+### 1. 识别值得记忆的信息
+
+并非所有信息都值得持久化，聚焦以下四类高价值记忆：
+
+**四类核心记忆**
+
+| 类型 | 描述 | 示例 |
+|------|------|------|
+| 🏗️ **架构决策** | 重要的技术选型和设计取舍 | "使用 Zustand 而非 Redux，因为项目规模小、不需要 devtools" |
+| ⚠️ **已知陷阱** | 踩过的坑、避坑经验 | "直接调用 /api/v1/user 会 401，必须先刷新 token" |
+| 📐 **项目约定** | 命名规范、目录结构、代码约束 | "所有异步操作用 useQuery，禁止裸 fetch" |
+| ✅ **已解决问题** | 解决了的复杂 bug 和方案 | "iOS Safari 下 flex gap 不生效，用 margin 替代" |
+
+**识别触发条件**
+- 对话中出现「为什么要这样」「这个项目的约定是」「上次解决这个问题的方法是」
+- 重要的 ADR（架构决策记录）产出
+- 排查超过 30 分钟的 bug 及其解决方案
+- 用户明确说「记住这个」
+
+**不值得记忆的信息**
+- 一次性任务的临时上下文
+- 可以从代码本身读出的信息
+- 过于宽泛的"最佳实践"（已在 CLAUDE.md 中）
+
+### 2. 结构化记忆条目
+
+将识别到的信息格式化为标准记忆条目：
+
+**记忆条目格式（YAML）**
+```yaml
+# .ethan/agent-memory/architecture.yaml
+entries:
+  - id: mem_001
+    type: architecture_decision    # architecture_decision | gotcha | convention | resolved_bug
+    title: 状态管理选型：Zustand over Redux
+    content: |
+      本项目使用 Zustand 进行全局状态管理。
+      原因：组件树层级浅（≤3层），不需要时间旅行调试，Redux 模板代码过多。
+      影响：所有跨组件状态通过 useXxxStore() hook 访问，不使用 Context API。
+    tags: [state-management, zustand, frontend]
+    created_at: 2024-01-15
+    confidence: high               # high | medium | low
+    scope: global                  # global | module:<name> | file:<path>
+```
+
+**文件组织结构**
+```
+.ethan/agent-memory/
+├── architecture.yaml    # 架构决策
+├── gotchas.yaml         # 已知陷阱
+├── conventions.yaml     # 项目约定
+├── resolved-bugs.yaml   # 已解决问题
+└── index.yaml           # 记忆索引（供快速检索）
+```
+
+**记忆条目质量标准**
+- title：一句话，包含关键词（方便检索）
+- content：5-10 行，包含决策背景 + 结论 + 影响范围
+- tags：3-5 个，技术栈 + 模块 + 问题类型
+- confidence：high=已验证可重用，medium=上下文相关，low=存疑待确认
+
+### 3. 写入持久化存储
+
+将格式化的记忆条目追加写入对应文件：
+
+**写入操作**
+```bash
+# 目录不存在时自动创建
+mkdir -p .ethan/agent-memory
+
+# 在 index.yaml 更新记忆摘要（用于快速检索）
+# index.yaml 格式：
+# entries:
+#   - id: mem_001
+#     title: "状态管理选型：Zustand over Redux"
+#     type: architecture_decision
+#     tags: [state-management, zustand]
+#     file: architecture.yaml
+```
+
+**记忆维护规则**
+- 同一主题新记忆覆盖旧记忆（更新 content + updated_at）
+- 标记为 low confidence 的记忆，3 个月未访问则删除
+- 每次成功使用后，将 confidence 升级（low → medium → high）
+- 发现记忆内容已过时时，立即更新或标记 deprecated
+
+**与 .ethan/team-knowledge/ 的区别**
+| | agent-memory | team-knowledge |
+|--|---|---|
+| 写入者 | AI（自动提取） | 人工（ethan knowledge add）|
+| 格式 | 结构化 YAML | 自由文本 Markdown |
+| 粒度 | 单条决策/问题 | 完整知识文档 |
+| 检索 | 按 tags + type 自动匹配 | 按关键词全文搜索 |
+
+### 4. 记忆检索与上下文注入
+
+在新会话开始或 Agent 执行前，检索相关记忆注入上下文：
+
+**检索策略（多维度匹配）**
+```
+1. 任务关键词 ↔ 记忆 tags（精确匹配）
+2. 当前工作文件路径 ↔ 记忆 scope（前缀匹配）
+3. 失败信息中的技术词 ↔ 记忆 title（模糊匹配）
+4. 最近 7 天被访问的记忆（时间权重提升）
+```
+
+**注入格式（添加到系统提示词开头）**
+```markdown
+## 📚 项目记忆上下文（来自 .ethan/agent-memory/）
+
+### 架构决策
+- **状态管理**：使用 Zustand，不用 Redux。所有跨组件状态通过 useXxxStore() 访问。
+- **API 层**：统一使用 React Query，禁止裸 fetch 调用。
+
+### 已知陷阱
+- ⚠️ iOS Safari 下 flex gap 不生效，用 margin-right/bottom 替代
+- ⚠️ /api/v1/user 接口在 token 过期时返回 200 + {error: "token_expired"}，非标准 401
+
+### 项目约定
+- 组件文件统一 PascalCase，工具函数 camelCase
+- 单元测试覆盖率要求 ≥ 80%（核心业务）
+
+> ⓘ 以上记忆来自 .ethan/agent-memory/（共 N 条）。如有不准确，请更新记忆文件。
+```
+
+**记忆命中反馈**
+每次使用记忆后，记录命中情况：
+```yaml
+# .ethan/agent-memory/index.yaml
+  - id: mem_003
+    last_hit: 2024-03-20
+    hit_count: 7
+    confidence: high    # 命中多次后自动升级
+```
+
+### 5. 记忆审计与清理
+
+定期维护记忆库，确保记忆的准确性和有效性：
+
+**审计清单**
+```bash
+# 查看所有记忆
+ethan memory list
+
+# 统计记忆健康度
+ethan memory stats
+# 输出：
+#   总记忆条数：48
+#   高置信度：32 | 中：12 | 低：4
+#   30天未命中：8条（建议清理）
+#   重复/矛盾：2组（需合并）
+```
+
+**记忆衰减策略**
+- 90 天未命中：自动降级 confidence（high → medium → low）
+- 180 天未命中的 low confidence 记忆：标记为 deprecated，下次审计删除
+- 代码库重大重构后：批量检查相关记忆是否仍有效
+
+**记忆冲突处理**
+```
+如发现两条矛盾的记忆：
+1. 保留更新的（created_at 更晚）
+2. 将旧的标记为 deprecated
+3. 在新记忆的 content 中注明「取代了 mem_xxx」
+```
+
+**团队共享记忆**
+```bash
+# 将记忆同步到 git（团队共享）
+ethan sync push --include agent-memory
+
+# 拉取团队记忆
+ethan sync pull
+
+# 记忆文件建议加入 .gitignore 的例外
+# .gitignore:
+# !.ethan/agent-memory/*.yaml
+```
+
+**输出格式**：YAML 记忆条目文件（写入 .ethan/agent-memory/）+ Markdown 注入格式的上下文摘要
+
+**注意事项**：
+- 记忆要精不要多——50 条高质量记忆 > 500 条低质量记忆
+- 每次新会话开始前运行"记忆检索"，将相关记忆注入为背景
+- 记忆不能替代代码本身——代码变更后记忆也要更新
+- 团队共享记忆文件建议提交到 git，个人临时记忆可以 .gitignore
+- 使用 ethan memory search <keyword> 快速检索历史经验
+
+---
+
 *Ethan - Your AI Workflow Assistant | 让每一步都有据可依*