@modus-ai/modus 0.1.0

package/templates/skills/modus-harness-agents/02-dev/SKILL.md

@@ -0,0 +1,102 @@
+# modus-harness-02-dev（代码开发 SubAgent）
+
+**调用方：** Harness Orchestrator  
+**输入：** `01-analysis.md` + 相关业务 Skill  
+**产出物：** `modus/plans/active/{story-id}/02-sprint-contract.md` + 实际代码变更
+
+## 职责
+
+核心代码生成者。按照需求分析报告中的 Sprint 计划，逐层实现代码，每个 Sprint 完成后验证可构建，遵循项目已有的架构规范和编码风格。
+
+---
+
+## 执行流程
+
+### Step 1：读取上下文
+
+1. 读取 `01-analysis.md`，理解 Sprint 计划和技术影响范围
+2. 读取相关业务 Skill，了解项目规范（层次结构、命名约定、技术约束）
+3. 读取 `modus/config.yaml`，获取项目技术栈信息
+
+### Step 2：逐 Sprint 实现
+
+按 Sprint 计划顺序实现，每个 Sprint 遵循以下步骤：
+
+**2a. 分析现有代码**
+- 找到需要修改/新增的文件
+- 理解现有代码风格和命名规范
+- 识别可复用的工具类、基类、常量
+
+**2b. 实现代码**
+遵循的通用原则：
+- 命名遵循项目现有风格（从 Skill 或现有代码中获取规范）
+- 新增文件放置到正确的包/目录层次
+- 事务注解使用项目规范方式（避免同类内部调用失效）
+- 分布式锁按项目已有模式使用
+- 参数校验在接口层完成，服务层做业务校验
+- 所有数据库操作必须在正确的事务边界内
+- 金额字段使用 BigDecimal，避免浮点精度问题
+
+**2c. Sprint 验证**
+每个 Sprint 完成后记录：
+- 新增/修改的文件列表
+- 关键实现决策（与 `01-analysis.md` 中建议有出入时说明原因）
+
+### Step 3：生成 Sprint Contract
+
+所有 Sprint 完成后，生成 `02-sprint-contract.md`。
+
+---
+
+## 产出物格式（02-sprint-contract.md）
+
+```markdown
+# Sprint Contract
+
+## 执行摘要
+- 完成 Sprint: {N} 个
+- 新增文件: {N} 个
+- 修改文件: {N} 个
+- 实现时间: {YYYY-MM-DD HH:mm}
+
+## Sprint 执行记录
+
+### Sprint 1：{名称}
+**状态：** ✅ 完成
+
+**文件变更：**
+- 新增: `{文件路径}` — {说明}
+- 修改: `{文件路径}` — {变更内容}
+
+**关键实现决策：**
+- {决策说明}
+
+### Sprint 2：{名称}
+...
+
+## 已知风险/遗留问题
+- {问题描述：如某个边界情况暂未处理}
+
+## 待 SubAgent 03/04/05 重点关注
+- {代码评审重点关注点}
+- {性能风险点提示}
+- {安全风险点提示}
+```
+
+---
+
+## 编码规范
+
+遵循业务 Skill 中记录的项目规范。如果 Skill 中没有明确说明，参考以下通用原则：
+
+- **分层架构：** Controller/Facade → Service/Manager → Mapper/DAO，跨层只能向下调用
+- **事务：** `@Transactional` 只在最外层 Service/Manager 方法上，避免同类内部调用失效
+- **异常处理：** 业务异常抛出项目统一的业务异常类，不吞掉异常
+- **日志：** 关键业务入口和异常分支必须有日志，不打印敏感信息
+- **注释：** 复杂逻辑和非直觉的业务规则需要注释说明
+
+## 禁止行为
+
+- 不修改已有测试用例（留给 SubAgent 03）
+- 不直接修改生产配置文件（留给 SubAgent 07）
+- 发现可能有性能问题但超出当前 Sprint 范围时，在产出物中标注，不擅自重构

package/templates/skills/modus-harness-agents/03-test/SKILL.md

@@ -0,0 +1,84 @@
+# modus-harness-03-test（代码测试 SubAgent）
+
+**调用方：** Harness Orchestrator（与 04/05 并行启动）  
+**输入：** `02-sprint-contract.md` + 代码变更  
+**产出物：** `modus/plans/active/{story-id}/03-test-report.md` + 单元测试代码
+
+## 职责
+
+为本次代码变更生成单元测试，验证核心业务逻辑有测试覆盖，输出测试报告。
+
+---
+
+## 执行流程
+
+### Step 1：分析代码变更
+
+读取 `02-sprint-contract.md`，识别需要测试的关键方法：
+- Service/Manager 层的核心业务方法
+- 有复杂条件分支的逻辑
+- `01-analysis.md` 中标注的验收标准对应的逻辑
+
+### Step 2：生成测试用例
+
+按照 **Happy Path → 边界条件 → 异常路径** 三段式结构设计测试：
+
+**Happy Path（正常流程）**
+- 主流程成功执行
+- 返回值正确
+
+**边界条件（Boundary）**
+- null / 空值 / 空集合 / 零值
+- 最小值 / 最大值
+- 单条记录 / 批量记录
+
+**异常路径（Exception）**
+- 依赖服务调用失败
+- 数据不存在
+- 业务规则校验失败（如余额不足、状态不合法）
+- 并发场景（如分布式锁被占用）
+
+### Step 3：编写测试代码
+
+遵循项目测试规范（从业务 Skill 或现有测试文件中提取），通用原则：
+- 使用 Mock 隔离外部依赖（DB、RPC、MQ 等）
+- 每个测试方法只测一个场景
+- 测试方法命名清晰表达场景：`test_{methodName}_{scenario}_{expectedResult}`
+- 断言明确，不只断言 "no exception"
+
+### Step 4：运行测试（如可执行环境允许）
+
+如果有可用的测试执行环境：
+- 执行新增的测试用例
+- 记录通过/失败状态
+
+---
+
+## 产出物格式（03-test-report.md）
+
+```markdown
+# 测试报告
+
+## 测试覆盖摘要
+- 新增测试用例: {N} 个
+- 覆盖方法: {N} 个
+- 通过: {N} | 失败: {N} | 跳过: {N}
+
+## 测试用例列表
+
+### {ClassName}Test
+| 测试方法 | 场景 | 状态 |
+|----------|------|------|
+| test_createOrder_success | 正常创建订单 | ✅ |
+| test_createOrder_insufficientBalance | 余额不足 | ✅ |
+| test_createOrder_concurrentLock | 并发锁冲突 | ✅ |
+
+## 覆盖率分析
+- 核心业务逻辑：{N}% 覆盖
+- 未覆盖的分支：{描述原因}
+
+## 验收标准覆盖
+| 验收场景 | 对应测试 | 状态 |
+|----------|----------|------|
+| {从 01-analysis.md 提取} | {测试方法名} | ✅/❌ |
+```

package/templates/skills/modus-harness-agents/04-perf/SKILL.md

@@ -0,0 +1,109 @@
+# modus-harness-04-perf（性能审计 SubAgent）
+
+**调用方：** Harness Orchestrator（与 03/05 并行启动）  
+**输入：** `02-sprint-contract.md` + 代码变更  
+**产出物：** `modus/plans/active/{story-id}/04-perf-report.md`
+
+## 职责
+
+对代码变更进行静态性能审计，识别 N+1 查询、缺少批量操作、大数据量风险等，量化每个风险的影响，按高/中/低分级输出报告。
+
+---
+
+## 审计重点
+
+### 1. N+1 查询（高优先级）
+
+**检测模式：**
+- 循环体内包含 DB 查询调用（`for/while` 内调用 `mapper.select*`）
+- 循环内调用 RPC/HTTP 接口
+
+**量化影响：**
+- 指出循环的数据量（N 条记录 → N 次 SQL）
+- 估算最坏情况下的查询次数
+
+**修复建议：**
+- 将循环内查询提取为批量查询（IN 查询 / 批量 RPC）
+- 先查全量，再在内存中分组/关联
+
+---
+
+### 2. 缺少批量操作（中优先级）
+
+**检测模式：**
+- 循环内调用单条 insert/update
+- 应使用 `insertBatch` 但使用了逐条 `insert`
+
+**修复建议：**
+- 使用 `insertBatchSomeColumn` 或自定义批量 insert XML
+- 大批量操作分批提交（每批 500-1000 条），避免超大事务
+
+---
+
+### 3. 大数据量无保护（高优先级）
+
+**检测模式：**
+- 查询无 LIMIT 限制
+- 分页查询缺少总数上限保护
+- 深分页（`OFFSET` 过大）
+- 全表扫描风险（无索引条件）
+
+**修复建议：**
+- 对列表查询强制设置最大返回条数
+- 深分页改用游标分页（基于最后一条记录的 ID）
+
+---
+
+### 4. 搜索引擎查询（如适用）
+
+**检测模式：**
+- ES 查询缺少 `fetchSource`（返回不必要的字段）
+- 缺少 `trackTotalHits: false`（数据量大时计算总数代价高）
+- 聚合查询无 `size: 0`（无需 hits 时）
+
+---
+
+### 5. 事务范围过大（中优先级）
+
+**检测模式：**
+- `@Transactional` 方法内包含远程调用（RPC/HTTP）
+- 事务内包含大量数据查询或处理逻辑
+
+**修复建议：**
+- 将远程调用移到事务外
+- 大事务拆分为多个小事务
+
+---
+
+## 产出物格式（04-perf-report.md）
+
+```markdown
+# 性能审计报告
+
+## 审计摘要
+- 审计文件数: {N}
+- 高风险: {N} 个 | 中风险: {N} 个 | 低风险: {N} 个
+
+## 高风险问题
+
+### [HIGH-01] N+1 查询
+- **位置：** `{文件名}.java:{行号}`
+- **问题：** `for` 循环中对每条订单调用 `orderMapper.selectById()`，N 条数据产生 N 次 SQL
+- **影响：** 订单列表 100 条 → 100 次 SELECT，响应时间线性增长
+- **修复方案：**
+  ```java
+  // 改为批量查询
+  List<Long> ids = orders.stream().map(Order::getId).collect(toList());
+  Map<Long, Order> orderMap = orderMapper.selectBatchIds(ids)
+      .stream().collect(toMap(Order::getId, o -> o));
+  ```
+
+## 中风险问题
+...
+
+## 低风险问题
+...
+
+## 无性能问题确认
+{如无问题，明确说明已检查的内容，不要留空}
+```

package/templates/skills/modus-harness-agents/05-security/SKILL.md

@@ -0,0 +1,116 @@
+# modus-harness-05-security（安全审计 SubAgent）
+
+**调用方：** Harness Orchestrator（与 03/04 并行启动）  
+**输入：** `02-sprint-contract.md` + 代码变更  
+**产出物：** `modus/plans/active/{story-id}/05-security-report.md`
+
+## 职责
+
+对代码变更进行安全审计，重点检测多租户数据隔离漏洞、权限校验缺失、敏感信息泄露、SQL 注入等风险，按严重/高/低分级输出报告。
+
+---
+
+## 审计重点
+
+### 1. 多租户数据隔离（严重）
+
+**检测模式：**
+- DB 查询/更新缺少 `tenantId` 条件
+- `tenantId` 来自 request 参数（可被篡改），而不是从用户会话/上下文中获取
+- 数据归属校验：操作前是否验证当前用户有权操作该条记录
+
+**修复建议：**
+- `tenantId` 始终从服务端 UserContext/Session 中获取，不信任客户端传入
+- 关键查询增加 `AND tenant_id = #{tenantId}` 条件
+- 修改操作前查询数据归属，确认归属于当前租户
+
+---
+
+### 2. 接口权限校验（高风险）
+
+**检测模式：**
+- 对外暴露的接口（Controller/Facade）缺少权限校验注解
+- 管理员操作接口未校验当前用户是否为管理员角色
+- 查询接口未过滤当前用户无权访问的数据
+
+**修复建议：**
+- 接口层添加权限校验注解或调用权限校验方法
+- 结合项目的权限框架（RBAC/自定义注解）进行检查
+
+---
+
+### 3. 敏感信息泄露（高风险）
+
+**检测模式：**
+- 日志中打印手机号、身份证号、银行卡号、密码等
+- 接口响应中返回不必要的敏感字段
+- 异常信息中暴露内部实现细节（SQL 语句、堆栈等）
+
+**修复建议：**
+- 日志脱敏：手机号保留前 3 后 4，身份证保留前 3 后 4
+- 响应对象中敏感字段加脱敏注解或做 mask 处理
+- 生产环境不返回原始异常信息
+
+---
+
+### 4. SQL 注入风险（严重）
+
+**检测模式：**
+- MyBatis XML 中使用 `${}` 拼接用户输入（应使用 `#{}`）
+- 动态表名/列名未做白名单校验
+- 排序字段直接拼接到 SQL（`ORDER BY ${sortField}`）
+
+**修复建议：**
+- 用户输入一律使用 `#{}` 参数化
+- 动态排序字段做枚举白名单校验
+
+---
+
+### 5. 越权操作（高风险）
+
+**检测模式：**
+- 通过 ID 查询/修改数据，未校验该数据是否属于当前用户/租户
+- 批量操作接口未限制操作范围（如用户传入他人的 ID 列表）
+
+---
+
+## 产出物格式（05-security-report.md）
+
+```markdown
+# 安全审计报告
+
+## 审计摘要
+- 严重: {N} 个 | 高风险: {N} 个 | 低风险: {N} 个
+
+## 严重问题
+
+### [SEC-CRITICAL-01] 多租户隔离缺失
+- **位置：** `{文件名}.java:{行号}`
+- **问题：** `tenantId` 从 request 参数获取，攻击者可篡改访问他人数据
+- **修复：**
+  ```java
+  // 错误
+  Long tenantId = request.getTenantId();
+  // 正确
+  Long tenantId = UserContext.getCurrentTenantId();
+  ```
+
+## 高风险问题
+...
+
+## 低风险问题
+...
+
+## 无安全问题确认
+{如无问题，明确说明已检查的内容}
+```
+
+---
+
+## 评级标准
+
+| 级别 | 说明 | 处理要求 |
+|------|------|----------|
+| 严重 | 可直接导致数据泄露或越权 | 必须在合入前修复，触发 Loop 2 重入 |
+| 高风险 | 有潜在安全风险，影响范围较大 | 必须在合入前修复，触发 Loop 2 重入 |
+| 低风险 | 安全最佳实践问题，影响范围有限 | 建议修复，不阻塞合入 |

package/templates/skills/modus-harness-agents/06-review/SKILL.md

@@ -0,0 +1,123 @@
+# modus-harness-06-review（代码评审 SubAgent）
+
+**调用方：** Harness Orchestrator（Gate B 通过后触发）  
+**输入：** 全部产出物（01-analysis.md 至 05-security-report.md）+ 代码变更  
+**产出物：** `modus/plans/active/{story-id}/cr-report.md`
+
+## 职责
+
+作为独立评审者，综合所有产出物进行代码质量评估。是 Harness 的核心质量守门员。P1/P2 问题会触发 Loop 2 重入，P3 问题建议修复但不阻塞。
+
+---
+
+## 评审维度
+
+### 维度 1：需求符合性
+
+对照 `01-analysis.md` 中的验收标准，检查代码实现是否完整覆盖所有需求：
+- 所有 Sprint 任务是否已实现
+- 验收场景是否有代码覆盖
+- 是否存在遗漏的边界情况
+
+### 维度 2：代码质量
+
+**命名规范：**
+- 类名、方法名、变量名是否语义清晰
+- 是否遵循项目已有命名约定（从业务 Skill 中获取）
+
+**架构规范：**
+- 文件放置位置是否正确（包结构/目录）
+- 层次调用是否正确（不能跨层调用）
+- 职责分离是否清晰（业务逻辑不在 Controller 层）
+
+**事务与并发：**
+- `@Transactional` 是否在正确位置（避免同类内部调用失效）
+- 是否存在事务嵌套问题
+- 分布式锁使用是否正确（加锁范围、锁粒度、释放时机）
+
+**防御性编程：**
+- 关键参数是否有非空校验
+- 数据库结果是否处理了 null/empty 情况
+- 集合操作前是否判空
+
+**异常处理：**
+- 是否使用项目统一的异常类
+- 是否有不当的异常吞咽（`catch (Exception e) {}`）
+- 日志是否完整（入参、出参、异常信息）
+
+**金额处理：**
+- 金额字段是否使用 BigDecimal
+- 运算是否使用 BigDecimal API（避免 `+`/`*` 运算）
+
+### 维度 3：测试覆盖（参考 03-test-report.md）
+
+- 核心业务逻辑是否有测试
+- 测试是否覆盖了重要异常路径
+
+### 维度 4：性能与安全（参考 04/05 报告）
+
+- 04 报告中的高风险问题是否已在代码中修复
+- 05 报告中的严重/高风险问题是否已修复
+
+---
+
+## 问题分级
+
+| 级别 | 定义 | 处理 |
+|------|------|------|
+| **P1（严重）** | 功能缺失、数据安全漏洞、会导致生产故障的 Bug | 必须修复，触发 Loop 2 重入 |
+| **P2（高风险）** | 架构规范违反、事务/并发问题、安全隐患 | 必须修复，触发 Loop 2 重入 |
+| **P3（建议）** | 代码质量改进、命名优化、日志完善 | 建议修复，不阻塞合入 |
+
+---
+
+## 产出物格式（cr-report.md）
+
+```markdown
+# 代码评审报告
+
+## 评审摘要
+- 评审时间: {YYYY-MM-DD HH:mm}
+- P1 问题: {N} 个 | P2 问题: {N} 个 | P3 建议: {N} 个
+- **合入结论: {✅ 可合入 / ❌ 需修复后重审}**
+
+## P1 问题（必须修复）
+
+### [P1-01] {问题标题}
+- **位置：** `{文件名}.java:{行号}`
+- **问题描述：** {详细说明问题是什么，为什么有问题}
+- **代码片段：**
+  ```java
+  // 有问题的代码
+  ```
+- **修复方案：**
+  ```java
+  // 正确的代码
+  ```
+
+## P2 问题（必须修复）
+...
+
+## P3 建议（建议修复）
+...
+
+## 正向确认
+- ✅ {正确的做法，鼓励 SubAgent 02 延续的好实践}
+
+## 下一步
+{如有 P1/P2 → "触发 Loop 2，SubAgent 02 需修复以下 Sprint: Sprint {N}"}
+{如无 P1/P2 → "通过评审，可进入 Final Review"}
+```
+
+---
+
+## 创建 Bug 单（可选）
+
+如果项目配置了 `tapdProjectId`（来自 `modus/config.yaml`），对于 P1/P2 问题可以选择自动创建 TAPD Bug 单：
+
+- Bug 标题：`[Modus CR] {问题标题}`
+- 关联 Story ID：`{当前 story-id}`
+- 描述：包含代码位置、问题代码片段、修复方案
+- 严重程度：P1 → 严重，P2 → 一般
+
+创建完成后将 Bug ID 写入 cr-report.md 末尾。

package/templates/skills/modus-harness-agents/07-deploy/SKILL.md

@@ -0,0 +1,101 @@
+# modus-harness-07-deploy（部署发布 SubAgent）
+
+**调用方：** Harness Orchestrator（Gate C 通过后触发）  
+**输入：** `cr-report.md`（无 P1/P2）+ `02-sprint-contract.md`  
+**产出物：** `modus/plans/active/{story-id}/07-deploy-status.md`
+
+## 职责
+
+代码合入后的灰度部署验证。监控 CI/CD 流水线，验证各灰度环境服务健康状态，对关键接口执行冒烟测试，监控上线后错误日志变化。
+
+---
+
+## 执行流程
+
+### Step 1：确认部署前提
+
+1. 确认 `cr-report.md` 结论为「可合入」（无 P1/P2）
+2. 读取 `modus/config.yaml` 中的部署相关配置（如 CI 地址、环境列表）
+3. 提示用户确认已触发 CI/CD 流水线
+
+### Step 2：CI 流水线状态监控
+
+定期询问或读取 CI 状态：
+- 构建是否通过
+- 单元测试是否通过
+- 代码扫描是否通过
+
+若 CI 失败，输出失败原因并停止。
+
+### Step 3：灰度环境验证
+
+按 `dev → test → pre（预发）` 顺序验证（不自动部署 prd，prd 需人工确认）：
+
+对每个环境：
+1. 检查服务健康状态（health check 接口）
+2. 执行 P0 冒烟测试（来自 `01-analysis.md` 的验收 Scenario）
+3. 查询近 15 分钟 ERROR 日志数量，与上线前基线对比
+
+### Step 4：生成部署报告
+
+---
+
+## 产出物格式（07-deploy-status.md）
+
+```markdown
+# 部署状态报告
+
+## 基本信息
+- Story ID: {id}
+- 部署时间: {YYYY-MM-DD HH:mm}
+- 代码分支: {branch}
+
+## CI 流水线
+| 阶段 | 状态 | 耗时 |
+|------|------|------|
+| 构建 | ✅ | {N}s |
+| 单元测试 | ✅ | {N}s |
+| 代码扫描 | ✅ | {N}s |
+
+## 灰度环境验证
+
+### dev 环境
+- 服务状态: ✅ 健康
+- 冒烟测试: {N}/{N} 通过
+- ERROR 日志: 上线前 {N}/h → 上线后 {N}/h（{变化}）
+
+### test 环境
+- 服务状态: ✅ 健康
+- 冒烟测试: {N}/{N} 通过
+
+### pre（预发）环境
+- 服务状态: ✅ 健康
+- 冒烟测试: {N}/{N} 通过
+- ERROR 日志: 上线前 {N}/h → 上线后 {N}/h
+
+## prd 环境
+⏸️ 等待人工确认部署
+
+**部署确认单：**
+- [ ] pre 环境验证通过
+- [ ] 业务方确认冒烟通过
+- [ ] 运维确认资源充足
+
+## 冒烟测试详情
+| 场景 | 接口 | 状态 |
+|------|------|------|
+| {验收场景1} | POST /api/v1/{path} | ✅ |
+| {验收场景2} | GET /api/v1/{path} | ✅ |
+
+## 结论
+{✅ 灰度验证通过，可推进 prd 部署}
+{❌ 灰度验证失败: {失败原因}}
+```
+
+---
+
+## 注意事项
+
+- prd 环境不自动部署，必须等待人工确认
+- 若任意灰度环境冒烟失败，立即停止并上报给 Orchestrator
+- ERROR 日志增量超过基线 2 倍时，触发告警提示