@shirayner/ace 0.1.0-snapshot.1

package/templates/skills/coding/references/code-smells.md

@@ -0,0 +1,201 @@
+# 代码坏味道详细清单
+
+本文档作为 code-review skill 的参考材料，提供具体的坏味道检查清单。
+
+## Bug风险类
+
+### 空指针/空引用
+- 未判空的变量直接调用方法
+- 集合操作前未检查null或空
+- 链式调用中可能的中断点（`a.b.c.d`）
+- 自动解装箱导致的NPE（`Integer` vs `int`）
+
+### 资源泄漏
+- 文件流未关闭（未使用try-with-resources）
+- 数据库连接未释放
+- 网络连接未正确关闭
+- 锁未释放（ReentrantLock的lock/unlock不匹配）
+
+### 并发问题
+- 共享变量缺少同步
+- 竞态条件（检查-执行模式）
+- 线程不安全类的共享使用（SimpleDateFormat、HashMap在并发环境）
+- 死锁风险
+
+### 异常处理
+- 空catch块（吞异常）
+- 捕获Exception/Throwable过于宽泛
+- 异常被吞掉或只打印日志未处理
+- 在finally中抛出异常覆盖原始异常
+
+### 边界条件
+- 数组/集合越界（索引从0开始还是1开始）
+- 除零风险
+- 整数溢出
+- 字符串截断导致乱码
+- 时间边界（跨天、跨月、跨年）
+
+### 逻辑错误
+- `==` vs `equals`（引用相等 vs 值相等）
+- 短路逻辑误用（`&&` vs `&`）
+- 运算符优先级错误
+- 死代码（不可能到达的条件）
+- 赋值误用为比较（`=` vs `==`）
+
+## 代码坏味道类
+
+### 过长方法 (Long Method)
+- 方法超过50行
+- 方法做了多件事情（多种职责）
+- 需要注释来解释代码块的功能
+
+### 过大类 (Large Class)
+- 类字段/方法数量过多
+- 类承担了过多职责
+- 导入过多（import地狱）
+
+### 重复代码 (Duplicated Code)
+- copy-paste的代码块
+- 相似的逻辑未抽取（仅变量名不同）
+- 结构重复（if/else中的重复代码）
+
+### 过长参数列表 (Long Parameter List)
+- 超过4个参数
+- 参数经常一起出现（应考虑封装为对象）
+- 布尔标志参数（表示方法做多件事）
+
+### 数据泥团 (Data Clumps)
+- 总是一起出现的数据字段
+- 总是一起传递的参数组
+- 总是一起使用的变量
+
+### Switch语句 / 多态滥用
+- 大量switch/if-else判断类型
+- 违反开闭原则（新增类型需要修改多处）
+- 可以用多态替代的类型判断
+
+### 临时字段 (Temporary Field)
+- 仅在特定条件下使用的字段
+- 对象生命周期中大部分时间该字段为null
+- 字段含义随场景变化
+
+### 消息链 (Message Chains)
+- `a.b.c.d.doSomething()`
+- 过度导航（违反得墨忒耳定律）
+- 紧耦合的实现细节暴露
+
+### 过度使用null (Null Checks)
+- 大量的null检查散落在各处
+- null表示多种不同含义
+- 可以考虑Null Object模式或Optional
+
+### 魔法数字/字符串 (Magic Numbers/Strings)
+- 硬编码的数值（如 86400、1024）
+- 未命名的布尔值（`true`/`false` 参数）
+- 重复出现的字符串常量
+
+### 注释掉的代码
+- 版本控制中遗留的注释代码块
+- 无用的TODO标记
+- 过时的注释与代码不符
+
+### 命名问题
+- 模糊命名（data、temp、obj）
+- 不一致命名风格（camelCase vs snake_case）
+- 误导性命名（名不副实）
+- 缩写不清晰（除非是通用缩写）
+
+## 设计问题类
+
+### SOLID原则违反
+
+**单一职责原则 (SRP)**
+- 一个类/方法改变有多个原因
+- 不同客户端依赖类的不同部分
+- 高内聚的破坏信号
+
+**开闭原则 (OCP)**
+- 新增功能需要修改现有代码
+- 大量的if/else或switch
+- 抽象不足导致扩展困难
+
+**里氏替换原则 (LSP)**
+- 子类违反父类契约
+- 子类抛出父类未声明的异常
+- 子类强化前置条件或弱化后置条件
+
+**接口隔离原则 (ISP)**
+- 接口臃肿（客户被迫依赖不需要的方法）
+- 胖接口（God Interface）
+
+**依赖倒置原则 (DIP)**
+- 高层模块依赖低层模块的具体实现
+- 抽象依赖具体（而非具体依赖抽象）
+
+### 高耦合/低内聚
+- 修改一个类需要修改很多其他类
+- 类之间依赖关系过于复杂（蜘蛛网）
+- 一个类知道太多其他类的内部细节
+
+### 设计模式误用
+
+**继承滥用**
+- "是一个"关系不成立却使用继承
+- 子类仅复用代码而非扩展行为
+- 可以用组合却用了继承
+
+**过度工程（过早抽象）**
+- 为不存在的需求设计
+- 过度使用设计模式
+- 简单问题复杂化
+
+**贫血模型**
+- 只有getter/setter的类
+- 业务逻辑全部在Service中
+- 缺乏封装（直接暴露内部状态）
+
+### API设计问题
+- 方法命名不清晰（动词使用不当）
+- 参数顺序不符合直觉
+- 返回值设计不合理（如用null表示空集合）
+- 副作用不明显（方法做了命名之外的事）
+
+### 可见性问题
+- 过度使用public（所有字段方法都公开）
+- 应该private的字段暴露出去
+- 包可见性使用不当
+
+## 语言特定坏味道
+
+### Java/Kotlin
+- 原始类型偏执（过度使用int/long而非封装类型）
+- 集合的原始类型使用（`List` vs `List<String>`）
+- 不必要的装箱/拆箱
+- Stream API误用（过度复杂或性能差）
+- Optional作为字段或方法参数（应作为返回类型）
+
+### Python
+- 使用list作为默认参数（可变默认参数陷阱）
+- 捕获所有异常过于宽泛（`except:`）
+- 循环中修改被迭代的列表
+- 不使用上下文管理器（`with`）管理资源
+
+### JavaScript/TypeScript
+- 隐式类型转换（`==` vs `===`）
+- 回调地狱（未使用Promise/async-await）
+- var的滥用（应使用let/const）
+- this绑定问题
+- any类型的滥用（TypeScript）
+
+### Go
+- 错误检查被忽视（`_ = doSomething()`）
+- 不必要的接口（仅有一个实现）
+- 过早抽象（接口由消费者定义）
+- goroutine泄漏（未正确关闭channel或wait）
+
+### C/C++
+- 内存泄漏（new/malloc未对应delete/free）
+- 野指针（使用已释放内存）
+- 缓冲区溢出（数组越界写入）
+- 整数溢出
+- 未定义行为（UB）

package/templates/skills/coding/references/implement-guide.md

@@ -0,0 +1,123 @@
+# 实现意图深度参考
+
+> 当 coding skill 路由到"实现"意图时按需加载。
+
+---
+
+## Sub-agent 使用原则
+
+### 何时委托给 sub-agent
+
+| 场景 | 委托方式 | 期望回传 |
+|------|---------|---------|
+| 不确定改动影响哪些文件 | Agent(subagent_type: "Explore") | 影响文件列表 + 风险点 |
+| 需要理解调用链 | Agent(subagent_type: "Explore") | 调用者/被调用者 + 数据流 |
+| 搜索项目中的已有模式 | Agent(subagent_type: "Explore") | 相似实现 + 可复用工具方法 |
+| 分析模块架构 | Agent(subagent_type: "Explore") | 关键组件 + 交互关系图 |
+
+### 如何写好 sub-agent prompt
+
+**原则**：告诉 sub-agent 你需要什么结论，不要规定搜索步骤。
+
+**好**：
+```
+分析 OrderService.createOrder() 的完整调用链。
+我需要知道：
+1. 哪些类直接调用了这个方法
+2. 这个方法内部依赖了哪些外部服务
+3. 修改它的返回值类型会影响哪些下游
+```
+
+**差**：
+```
+先 grep OrderService，再读每个文件，然后...
+```
+
+### 何时不用 sub-agent
+
+- 精确知道要读哪个文件 → 直接 Read
+- 搜索一个已知符号 → 直接 Grep
+- 改动位置已确定 → 直接 Edit
+
+---
+
+## Plan Mode 使用要点
+
+### 进入 Plan Mode 的信号
+
+- 变更涉及 3+ 文件
+- 需要用户确认方案（多种可行路径）
+- 涉及接口变更或公共 API
+- 不确定变更边界
+
+### Plan 应包含
+
+1. **变更目标**：一句话说清楚要达成什么
+2. **影响文件清单**：列出每个需要改动的文件及改动原因
+3. **实施步骤**：带验证点的步骤序列
+4. **风险与回退**：识别主要风险点，说明回退方案
+
+### Plan 不应包含
+
+- 冗余的背景分析（用户已经知道）
+- 过度详细的代码片段（执行时再写）
+- 风险清单和 RACI 表（除非用户要求）
+
+---
+
+## 状态文件使用要点
+
+仅深度任务需要状态文件。参见 SKILL.md 第 4 节"外化"部分的模板。
+
+### 何时创建
+
+- 预计修改 10+ 文件
+- 需要分多个阶段完成
+- 可能跨会话
+
+### 何时不创建
+
+- 能在一轮 Plan Mode 循环内完成的任务
+- 轻量任务
+
+### Phase 划分原则
+
+- 每个 Phase 有独立的验证点（编译/测试可通过）
+- 先核心后周边：Phase 1 先让主路径跑通
+- Phase 之间松耦合：某个 Phase 失败不阻塞其他
+
+---
+
+## 验证策略
+
+### 编译验证
+
+改完就编译，不攒到最后：
+```bash
+# Java/Maven
+mvn compile -pl <module> -DskipTests
+
+# Node
+npm run build
+
+# Go
+go build ./...
+```
+
+### 测试验证
+
+运行变更相关的测试：
+```bash
+# 指定测试类
+mvn test -Dtest=<TestClass> -pl <module>
+
+# 指定测试文件
+npm test -- --grep "<pattern>"
+```
+
+### 回归检查
+
+高风险变更（公共接口/核心逻辑）运行完整测试套件：
+```bash
+mvn test -pl <module>
+```

package/templates/skills/coding/references/unit-test-guide.md

@@ -0,0 +1,211 @@
+# 单元测试意图深度参考
+
+> 当 coding skill 路由到"测试"意图时按需加载。
+> 浓缩自实战经验，每条规则背后都有踩坑记录。
+
+---
+
+## 执行策略
+
+**批量生成 + 统一编译 + 错误修复**，不要逐个测试方法编写验证。
+
+1. 分析被测类 → 2. 一次性生成完整测试类 → 3. 编译验证 → 4. 运行修复 → 5. 覆盖率检查
+
+---
+
+## 框架检测与适配
+
+读取 pom.xml / build.gradle 确定框架组合：
+
+| 框架组合 | 类注解 | Mock 注入 | 注意事项 |
+|---------|--------|----------|---------|
+| JUnit 5 + Mockito | `@ExtendWith(MockitoExtension.class)` | `@InjectMocks` 自动注入 | 推荐方案 |
+| JUnit 4 + Mockito | `@RunWith(MockitoJUnitRunner.class)` | `@InjectMocks` 自动注入 | |
+| JUnit 4 + PowerMock | `@RunWith(PowerMockRunner.class)` | **必须手动注入 @Autowired 字段** | 见下方陷阱 #1 |
+
+---
+
+## Mock 陷阱（必读）
+
+### 陷阱 1: PowerMock + @Autowired 手动注入
+
+PowerMock 的 `@InjectMocks` 不能处理 `@Autowired` 字段，必须反射注入：
+
+```java
+@Before
+public void setUp() throws Exception {
+    MockitoAnnotations.initMocks(this);
+    injectField("repository", repository);
+    injectField("externalService", externalService);
+}
+
+private void injectField(String name, Object value) throws Exception {
+    Field field = ServiceUnderTest.class.getDeclaredField(name);
+    field.setAccessible(true);
+    field.set(serviceUnderTest, value);
+}
+```
+
+### 陷阱 2: thenReturn 中调用 mock 方法
+
+```java
+// WRONG — 触发 UnfinishedStubbingException
+when(service.getData()).thenReturn(buildData(mockObj));
+
+// RIGHT — 使用固定值
+when(service.getData()).thenReturn(buildData(1, 2, 3));
+// 或使用 thenAnswer
+when(service.getData()).thenAnswer(inv -> buildData(mockObj.getId()));
+```
+
+### 陷阱 3: stream/lambda 中的隐藏依赖
+
+被测代码中 stream 操作内的方法调用容易遗漏：
+```java
+rights.stream().map(rightV2 -> {
+    RightKey key = rightV2.rightKey();           // 需要 mock
+    Integer times = rightV2.getTimes(cmd);        // 需要 mock
+    Long count = rightV2.activityAllCount();      // 需要 mock
+});
+```
+**必须**完整阅读方法体，为每个 mock 对象列出"方法调用清单"。
+
+### 陷阱 4: 实体类实例化方式
+
+| 类型 | 实例化方式 | 原因 |
+|------|----------|------|
+| 项目内部 DTO/VO/Entity | `new` + setter | 有完整 setter |
+| 接口、抽象类 | `mock()` | 无法实例化 |
+| 外部 SDK 实体类 | `mock()` + `when().thenReturn()` | 通常无 public setter |
+
+```java
+// WRONG — 外部 SDK 类没有 setter
+AccountRealName account = new AccountRealName();
+account.setEnFirstName("John"); // 编译错误
+
+// RIGHT
+AccountRealName account = mock(AccountRealName.class);
+when(account.getEnFirstName()).thenReturn("John");
+```
+
+**不确定时**：先查看已有测试代码或源代码确认。
+
+### 陷阱 5: 父类已有 mock
+
+检查测试父类是否已定义 mock 字段，子类不要重复定义：
+```java
+// 父类已有
+@Mock protected DTOMapper dtoMapper;
+// 子类中 —— 不要再写 @Mock DTOMapper dtoMapper!
+```
+
+---
+
+## 测试设计
+
+### 命名规范
+
+`test{MethodName}_{Scenario}_{ExpectedResult}`
+
+### Given-When-Then 结构
+
+```java
+@Test
+void testCreateOrder_WithValidRequest_ShouldReturnCreatedOrder() {
+    // Given — 准备数据和 mock
+    CreateOrderRequest request = buildValidRequest();
+    given(inventoryClient.checkStock(any(), anyInt())).willReturn(true);
+
+    // When — 执行被测方法
+    Order result = orderService.createOrder(request);
+
+    // Then — 验证结果和行为
+    assertThat(result.getStatus()).isEqualTo(OrderStatus.CREATED);
+    verify(orderRepository).save(any(Order.class));
+}
+```
+
+### 每个方法的测试用例矩阵
+
+| 类型 | 数量 | 目的 |
+|------|------|------|
+| 正常流程 | 1+ | 核心路径验证 |
+| null/空参数 | 每参数 1 | 防御性检查 |
+| 边界值 | 每参数 1-2 | 极值探测 |
+| 异常流程 | 每异常 1 | 错误处理验证 |
+| 负面验证 | 1-2 | 确认不该发生的事没发生 |
+
+### 行为测试优先
+
+测试"做了什么"而非"怎么做的"：
+```java
+// GOOD — 验证业务行为
+verify(inventoryClient).decreaseStock("product_123", 9);
+
+// BAD — 验证实现细节
+verify(inventoryDao).update(eq("product_123"), eq(9));
+```
+
+---
+
+## 覆盖率目标
+
+| 指标 | 目标 |
+|------|------|
+| 行覆盖率 | >= 80% |
+| 分支覆盖率 | >= 70% |
+| 核心类行覆盖率 | >= 90% |
+
+```bash
+mvn test jacoco:report -pl <module>
+```
+
+---
+
+## 常见编译/运行错误速查
+
+| 错误 | 根因 | 修复 |
+|------|------|------|
+| NPE: mock 对象为 null | 未调用 initMocks / PowerMock 未手动注入 | 检查 setUp 方法 |
+| NPE: mock 方法返回 null | 未 stub 某个方法调用 | 补充 when().thenReturn()，集合返回 emptyList |
+| UnfinishedStubbingException | thenReturn 中调用了 mock | 改用固定值或 thenAnswer |
+| Wanted but not invoked | verify 的方法没被实际调用 | 检查代码路径，确认方法确实被调用 |
+| 编译错误：找不到 setter | 对外部 SDK 类用了 new + setter | 改用 mock |
+| 类型不匹配 | 参数类型错误 | 检查 setter/构造函数期望的类型 |
+
+---
+
+## 静态方法 Mock
+
+**JUnit 5 + Mockito-inline**：
+```java
+try (MockedStatic<StaticClass> mocked = mockStatic(StaticClass.class)) {
+    mocked.when(StaticClass::staticMethod).thenReturn(result);
+    // test code
+}
+```
+
+**PowerMockito**：
+```java
+@RunWith(PowerMockRunner.class)
+@PrepareForTest({StaticClass.class})
+public class MyTest {
+    @Before
+    public void setUp() {
+        PowerMockito.mockStatic(StaticClass.class);
+        when(StaticClass.staticMethod()).thenReturn(result);
+    }
+}
+```
+
+---
+
+## 生成前检查清单
+
+- [ ] 完整阅读被测类方法体（包括私有方法、stream/lambda）
+- [ ] 检查测试父类已有 mock 定义
+- [ ] 为每个 mock 对象列出方法调用清单
+- [ ] 确认实体类实例化方式（mock vs new+setter）
+- [ ] 确认 setter 参数类型正确
+- [ ] 集合类返回 emptyList 而非 null
+- [ ] 不在 thenReturn 中调用 mock 方法