@dtt_siye/atool 1.4.0 → 1.5.0

package/skills/ai-project-architecture/rules/testing.md

@@ -0,0 +1,249 @@
+# Testing - 测试策略
+
+## 测试原则
+
+### 1. TDD 必需性
+**test-driven-development 技能是必需的**
+- 写任何新代码前（Red-Green-Refactor）
+- 重构迁移的代码前
+- 为迁移的代码写测试时
+
+### 2. 测试覆盖率目标
+```python
+# 目标：100% 覆盖迁移的代码
+# 最小：80% 覆盖率
+# 优先级：
+# 1. 公共接口（100%）
+# 2. 业务逻辑（100%）
+# 3. 工具函数（80%+）
+# 4. 辅助函数（60%+）
+```
+
+## 测试阶段
+
+### Phase 1: 迁移前测试
+```python
+# 1. 记录现有测试结果
+old_test_results = run_existing_tests()
+
+# 2. 基准性能
+old_performance = benchmark_performance()
+
+# 3. 验证现有功能
+test_existing_features()
+```
+
+### Phase 2: 迁移中测试
+每个迁移批次后：
+```python
+# 1. 语法检查
+python -m py_compile new_file.py
+
+# 2. 基本导入测试
+python -c "from apps.module import function"
+
+# 3. 现有测试通过
+pytest tests/
+```
+
+### Phase 3: 迁移后测试
+```python
+# 1. 完整测试套件
+pytest tests/ --cov=.
+
+# 2. 对比迁移前结果
+compare_test_results(old_test_results, current_test_results)
+
+# 3. 性能回归测试
+compare_performance(old_performance, current_performance)
+```
+
+## 测试类型
+
+### 1. 单元测试
+```python
+# agents/user_agent/services.py
+def test_user_service():
+    # Arrange
+    user_service = UserService()
+
+    # Act
+    result = user_service.create_user("test@example.com")
+
+    # Assert
+    assert result.id is not None
+    assert result.email == "test@example.com"
+```
+
+### 2. 集成测试
+```python
+# 测试代理间协作
+def test_user_order_integration():
+    # 用户代理创建用户
+    user = user_agent.create_user("test@example.com")
+
+    # 订单代理为用户创建订单
+    order = order_agent.create_order(user.id, "product")
+
+    # 验证关联
+    assert order.user_id == user.id
+```
+
+### 3. 端到端测试
+```python
+def test_complete_user_flow():
+    # 模拟用户注册到订单完成
+    user = api_client.post("/users", {"email": "test@example.com"})
+    order = api_client.post("/orders", {"user_id": user.id})
+
+    # 验证整个流程
+    assert order.status == "completed"
+```
+
+## 测试工具配置
+
+### 1. pytest 配置
+```python
+# pytest.ini
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*
+addopts = -v --tb=short --strict-markers
+
+markers =
+    unit: unit tests
+    integration: integration tests
+    e2e: end-to-end tests
+```
+
+### 2. Coverage 配置
+```python
+# .coveragerc
+[run]
+source = apps,core,agents
+omit =
+    */tests/*
+    */migrations/*
+    */__pycache__/*
+
+[report]
+exclude_lines =
+    pragma: no cover
+    def __repr__
+    raise AssertionError
+    raise NotImplementedError
+```
+
+## 测试数据管理
+
+### 1. 固定装置（Fixtures）
+```python
+# conftest.py
+import pytest
+from tests.factories import UserFactory, OrderFactory
+
+@pytest.fixture
+def user():
+    return UserFactory()
+
+@pytest.fixture
+def order(user):
+    return OrderFactory(user=user)
+```
+
+### 2. Factories
+```python
+# tests/factories.py
+class UserFactory:
+    @staticmethod
+    def create(**kwargs):
+        defaults = {
+            "email": "test@example.com",
+            "name": "Test User"
+        }
+        return User.objects.create(**{**defaults, **kwargs})
+```
+
+## 测试问题处理
+
+### 1. 测试失败时的处理流程
+```python
+def handle_test_failure(test_name, error):
+    # 1. 隔离问题
+    isolate_issue(test_name)
+
+    # 2. 确定原因
+    cause = determine_cause(error)
+
+    if cause == "IMPORT_ERROR":
+        fix_imports()
+    elif cause == "LOGIC_ERROR":
+        fix_logic()
+    elif cause == "REGRESSION":
+        # 回滚迁移
+        rollback_migration()
+
+    # 3. 重新运行测试
+    rerun_tests()
+```
+
+### 2. 常见问题及解决方案
+
+| 问题 | 原因 | 解决方案 |
+|------|------|---------|
+| ImportError | 导入路径错误 | 检查 new_ 前缀 |
+| AttributeError | 属性不存在 | 检查类/函数名 |
+| AssertionError | 逻辑改变 | 对比迁移前后代码 |
+| KeyError | 配置缺失 | 检查配置文件 |
+
+## 测试报告模板
+
+```markdown
+# 测试报告: [项目名] 迁移
+
+## 概览
+- 总测试数: 150
+- 通过: 145 (96.7%)
+- 失败: 5 (3.3%)
+- 跳过: 0
+
+## 失败测试详情
+
+### 1. test_user_creation
+**原因**: UserService.create_user() 返回值格式改变
+**状态**: 已修复
+**行动**: 更新断言逻辑
+
+### 2. test_payment_processing
+**原因**: PaymentService 类名改变
+**状态**: 已修复
+**行动**: 更新导入语句
+
+## 覆盖率分析
+- 总覆盖率: 87%
+- 目标覆盖率: 80%
+- 覆盖率变化: +2%
+
+## 性能测试
+- 平均响应时间: 120ms (迁移前: 115ms)
+- 回归: 4.3% (在可接受范围内)
+
+## 建议下一步
+1. 修复剩余 5 个测试
+2. 增加边缘情况测试
+3. 考虑性能优化
+```
+
+## 质量关卡
+
+### 测试必需调用
+1. **迁移前**: 记录基准
+2. **迁移中**: 每个批次后
+3. **迁移后**: 全面测试
+
+### 通过标准
+- 所有现有测试通过
+- 无性能回归（<5%变化）
+- 覆盖率 ≥ 80%
+- 新增测试覆盖所有公共接口

package/skills/ai-project-architecture/rules/verification.md

@@ -0,0 +1,111 @@
+# Code Verification - 代码验证
+
+## 执行步骤
+
+### 1. 全面代码审查
+- 审查每个迁移的文件
+- 验证无行为变更
+- 检查意外修改
+- 验证所有导入正确
+
+### 2. 验证所有导入解析
+```bash
+# 检查每个导入
+python -c "from agents.x.y import z"
+
+# 检查循环依赖
+python -c "
+import agents.agent1
+import agents.agent2
+# 无报错表示无循环依赖"
+```
+
+### 3. 检查所有交叉引用更新
+- 配置文件
+- 文档
+- 测试文件
+- 脚本和工具
+
+### 4. 验证无行为变更
+- 逐行比较功能
+- 运行现有测试并验证相同结果
+- 手动测试关键功能
+- 性能比较（应该相同）
+
+### 5. 生成验证报告
+- 列出所有审查的文件
+- 列出所有验证的导入
+- 列出所有更新的引用
+- 记录发现的任何差异（并修复）
+
+## 验证检查清单
+
+### 文件级检查
+- [ ] 所有迁移文件已审查
+- [ ] 文件内容无意外修改
+- [ ] 函数/类签名无变化
+- [ ] 注释和文档无丢失
+
+### 导入检查
+- [ ] 所有导入语句正确
+- [ ] 无循环依赖
+- [ ] 相对 vs 绝对导入正确
+- [ ] 导入链完整
+
+### 功能检查
+- [ ] 所有公共接口行为一致
+- [ ] 错误处理逻辑相同
+- [ ] 返回值格式一致
+- [ ] 性能特征相同
+
+### 测试验证
+- [ ] 现有测试通过
+- [ ] 测试结果与迁移前相同
+- [ ] 覆盖率无下降
+- [ ] 新增测试（如需要）
+
+## 必需技能调用
+
+### systematic-debugging（必需）
+- 调用时机：验证完成后
+- 传递内容：所有代码变更、测试结果、遇到的问题
+- 预期输出：根因分析、变更正确性验证
+
+### software-architecture
+- 调用时机：最终架构验证
+- 传递内容：最终结构、命名、关注点分离
+- 预期输出：架构合规性确认
+
+## 问题修复模板
+
+```markdown
+## 发现的问题
+
+### 问题描述
+[具体描述发现的问题]
+
+### 根因分析
+[为什么会出现这个问题]
+
+### 修复方案
+[如何修复]
+
+### 验证方法
+[如何验证修复正确]
+
+### 修复结果
+[修复后的验证结果]
+```
+
+## 通过标准
+
+1. **systematic-debugging** 审查通过
+2. 所有验证检查通过
+3. 无行为变更
+4. 所有交叉引用更新
+5. 无未解决问题
+
+## 不通过处理
+- 任何检查失败 → 必须修复才能继续
+- systematic-debugging 发现问题 → 必须解决
+- 行为变更 → 必须回滚并重新迁移

package/skills/atool-init/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: atool-init
-description: "Initialize a project with aTool - one-step setup: auto-detect global install status, run global install if needed, then generate project-level CLAUDE.md, Cursor rules, Kiro steering. Use when user says /atool-init, initialize project, setup aTool. 触发：初始化项目/配置aTool/init project"
-version: 1.0.0
+description: "Initialize a project with aTool - one-step setup: auto-detect global install status, run global install if needed, then generate project-level CLAUDE.md, Cursor rules, Kiro steering. Use when user says /atool-init, initialize project, setup aTool, or wants to use CLI equivalent 'atool init'. 触发：初始化项目/配置aTool/init project/atool init"
+version: 1.1.0
 ---
 
 # aTool Project Initialization (One-Step)
@@ -11,9 +11,10 @@ One-step project initialization: automatically checks global install status, per
 ## When to Use
 - User starts a new project and wants AI IDE configuration
 - User asks to set up or configure aTool for their project
-- User says "/atool-init", "initialize project", "setup atool", "init project"
-- User says "初始化项目", "配置aTool", "初始化aTool"
+- User says "/atool-init", "initialize project", "setup atool", "init project", "atool init"
+- User says "初始化项目", "配置aTool", "初始化aTool", "atool 初始化"
 - User wants to generate CLAUDE.md, Cursor rules, or Kiro steering
+- User wants to use the CLI equivalent `atool init` command
 
 ## Steps
 
@@ -139,3 +140,22 @@ Stack detection signal files:
 - If no stack is detected, a generic template is used
 - Global install is only run once (detected by checking staging directories)
 - The install.sh location varies by how aTool was installed (git clone, manual copy, etc.)
+
+## CLI Equivalents
+
+| Use Case | Command in AI IDE | CLI Command |
+|----------|-------------------|-------------|
+| Initialize current directory | `/atool-init` | `atool init` |
+| Initialize specific directory | `/atool-init for ./my-app` | `atool init ./my-app` |
+| Initialize with specific stack | `/atool-init with React stack` | `atool init --stack react` |
+| Check aTool installation | (Not applicable) | `atool version` |
+| Update aTool | (Not applicable) | `atool update` |
+
+## Skill 协作
+
+| 协作 Skill | 触发条件 | 交互方式 |
+|-----------|---------|---------|
+| software-architecture | 项目初始化完成后 | 建议运行架构设计指导 |
+| project-analyze | 初始化的项目 | 可运行深度项目分析 |
+| code-review | 项目有代码后 | 可运行代码质量审查 |
+| java-conventions/web-conventions | 对应技术栈项目 | 自动加载对应编码规范 |

package/skills/project-analyze/SKILL.md

@@ -78,10 +78,23 @@ Pipeline 中 AI 与 bash 工具的分工遵循核心原则：**确定性操作
 ### 6-Phase 架构
 
 ```
-Phase 1: SETUP      → phases/phase1-setup.md        (bash only, no AI, ~30秒)
-Phase 2: UNDERSTAND → phases/phase2-understand.md   (AI sub-agents ≤5并行)
+Phase 1: SETUP      → phases/phase1-setup.md        (bash + AI模块聚合, ~30秒)
+  ├─ 技术栈检测 (bash)
+  ├─ Pre-scan 语法提取 (bash)
+  ├─ 模块发现 + 聚合 (AI, rules/{STACK}.md 聚合规则)
+  └─ 用户确认分析参数
+
+Phase 2: UNDERSTAND → phases/phase2-understand.md   (AI sub-agents ≤5并行, 两阶段执行)
+  ├─ Stage 1: data.json + README.md (结构化提取)
+  ├─ Stage 1 验证 (bash, data.json 合法性 + README 行数)
+  ├─ Stage 2: api.md + data-model.md + dev-guide.md + prd.md + test-cases.md
+  └─ Stage 2 验证 (bash, 核心文档存在性)
+  注: 每个 sub-agent 内部 Stage 1→2 串行, checkpoint 仅在两阶段都验证通过后写入
+
 Phase 2.5: REFINE   → phases/phase2.5-refine.md     (AI sub-agents ≤5并行，串联 requirements-writer + software-architecture Refine Mode)
 Phase 3: GRAPH      → phases/phase3-graph.md        (bash only, no AI, ~30秒)
+  └─ 前置检查: data.json 存在性硬验证, VALID_COUNT=0 时 BLOCKED
+
 Phase 4: SYNTHESIZE → phases/phase4-synthesize.md   (main agent, 聚合模式)
 Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文件)
 ```
@@ -143,7 +156,7 @@ Phase 5: EXPORT     → phases/phase5-export.md       (bash + AI, export 单文
 }
 ```
 
-status 枚举值：`"pending"` | `"in_progress"` | `"completed"` | `"failed"` | `"skipped"`
+status 枚举值：`"pending"` | `"in_progress"` | `"completed"` | `"failed"` | `"skipped"` | `"blocked"`
 
 ### HARD GATE — bash Phase 执行验证
 
@@ -190,12 +203,19 @@ Modules processed in importance order, one at a time. Progress line per module.
 ## State Management & Checkpoint/Resume
 
 ### Checkpoint Write Timing
-After each sub-agent completes a module analysis, immediately write checkpoint to `analysis-state.json`:
+Phase 2 checkpoint **仅在 Stage 1 + Stage 2 都验证通过后**写入（详见 phase2-understand.md §2.5）。
+Phase 3 checkpoint 在 data.json 前置检查通过且 knowledge-graph.json 生成后写入。
+其他 Phase 完成后立即写入 checkpoint。
+
 ```
-state.modules[module_slug].{phase}_status = "completed"
-state.modules[module_slug].{phase}_completed_at = now()
-state.checkpoint = { last_completed_phase, last_completed_module, next_pending_module, batch_index, total_batches, timestamp }
-write analysis-state.json
+Phase 2 每模块:
+  Stage 1 完成 → 验证 data.json → 通过 → Stage 2
+  Stage 2 完成 → 验证 5 个核心文档 → 通过 → 写入 checkpoint
+  任一阶段失败 → 不写 checkpoint, 标记为 "failed"
+
+Phase 3:
+  data.json 前置检查失败 → 标记 "blocked", 不继续
+  knowledge-graph.json 生成成功 → 标记 "completed"
 ```
 
 ### Resume Flow（断点恢复决策树）
@@ -223,6 +243,7 @@ write analysis-state.json
    │  │
    │  ├─ 检查 phase3_graph 状态
    │  │  ├─ "pending" → 执行 Phase 3（知识图谱生成）
+   │  │  ├─ "blocked" → data.json 缺失, 需回到 Phase 2 重新执行
    │  │  ├─ "in_progress" / "failed" → 重新执行 Phase 3
    │  │  └─ "completed" → 进入 Phase 4
    │  │

package/skills/project-analyze/phases/phase1-setup.md

@@ -80,7 +80,51 @@
 > fi
 > ```
 
-### 1.4a 扫描已有文档（用户已有的 PRD/README 等）
+### 1.4a 模块聚合（关键步骤 — 必须执行）
+
+> **背景**：原始发现的模块数量可能过多（如 Maven 多模块项目可能有 50-70 个子模块），需要按 `rules/{STACK}.md` 的聚合规则将子模块聚合为有业务含义的分析单元。
+
+**执行方式**：此步骤由 AI 执行（非 bash），因为需要理解模块的业务含义。
+
+**聚合流程**：
+
+1. 读取 `rules/{STACK}.md` 的「聚合规则」章节
+2. 对 `manifest.json` 中的每个模块，按聚合决策树分类：
+   - **业务模块**：保持独立
+   - **框架/基础设施模块**：聚合为单个 `framework` 模块
+   - **依赖管理模块**（无源码）：标记 `skip`
+   - **脚手架/模板模块**：标记 `skip`
+3. 生成聚合后的模块列表，每个模块包含：
+   - `slug`：模块标识（如 `dtt-module-mall`）
+   - `name`：显示名称（如 `商城模块`）
+   - `path`：模块根路径
+   - `type`：`business` | `framework` | `skip`
+   - `sub_modules`：聚合的子模块列表（仅 framework 类型）
+   - `importance`：`high` | `medium` | `low`
+4. **写入聚合后的模块列表**到 `analysis-state.json` 的 `modules` 字段
+
+> **执行命令（必须通过 Bash 工具）** — 写入聚合结果：
+> ```bash
+> DOCS_DIR="$(pwd)/.atool-docs"
+> # 聚合后的模块列表（AI 生成后通过 jq 写入）
+> # 注意：AGGREGATED_MODULES 变量由 AI 基于聚合规则生成
+> AGGREGATED_MODULES='[
+>   {"slug":"dtt-gateway","name":"API网关","path":"dtt-gateway","type":"business","sub_modules":[],"importance":"high"},
+>   {"slug":"dtt-framework","name":"框架层","path":"dtt-framework","type":"framework","sub_modules":["dtt-common","dtt-spring-boot-starter-mybatis","dtt-spring-boot-starter-redis"],"importance":"high"},
+>   {"slug":"dtt-module-system","name":"系统管理","path":"dtt-module-system","type":"business","sub_modules":[],"importance":"high"}
+> ]'
+> # 上面的 JSON 是示例，实际内容由 AI 根据聚合规则生成
+> # 写入到 manifest.json 的 aggregated_modules 字段
+> jq --argjson modules "$AGGREGATED_MODULES" \
+>   '.aggregated_modules = $modules | .aggregated_count = ($modules | length)' \
+>   "$DOCS_DIR/pre-scan/manifest.json" > "$DOCS_DIR/pre-scan/manifest.json.tmp" \
+>   && mv "$DOCS_DIR/pre-scan/manifest.json.tmp" "$DOCS_DIR/pre-scan/manifest.json"
+> echo "Aggregated: $(jq '.aggregated_count' "$DOCS_DIR/pre-scan/manifest.json") analysis modules (from $(jq '.total_modules' "$DOCS_DIR/pre-scan/manifest.json") raw modules)"
+> ```
+
+**聚合结果必须向用户展示并确认**（纳入 §1.5 的预览中）。
+
+### 1.4b 扫描已有文档（用户已有的 PRD/README 等）
 
 > **执行命令（必须通过 Bash 工具）：**
 > ```bash
@@ -125,7 +169,20 @@
 技术栈：{STACK}
 文件数：{FILE_COUNT}（已排除 node_modules/build/.git 等）
 规模等级：{SCALE}
-识别模块：{MODULE_LIST}
+原始模块：{RAW_MODULE_COUNT} 个子模块
+聚合后分析模块：{AGGREGATED_COUNT} 个
+
+业务模块：
+  ✅ {slug} — {name} ({file_count} 文件)
+  ...
+
+框架模块：
+  📦 {slug} — {name}（聚合 {sub_count} 个子模块）
+  ...
+
+已跳过：
+  ⏭️ {slug} — {reason}
+  ...
 
 分析深度选项：
   L1  结构扫描    ~5分钟   ~10K tokens   目录树+技术栈识别
@@ -147,8 +204,8 @@
 > STACK="${STACK:-unknown}"
 > SCALE="${SCALE:-MEDIUM}"
 >
-> # 从 manifest 提取模块列表，fallback 为空数组
-> MODULES_JSON=$(jq -c '[.modules[].slug]' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null || echo '[]')
+> # 优先使用聚合后的模块列表，fallback 为原始模块
+> MODULES_JSON=$(jq -c 'if .aggregated_modules then [.aggregated_modules[] | .slug] else [.modules[].slug] end' "$DOCS_DIR/pre-scan/manifest.json" 2>/dev/null || echo '[]')
 >
 > # 构建 module_status 初始值
 > MODULE_STATUS=$(echo "$MODULES_JSON" | jq -c '[.[] | {key: ., value: {phase2: "pending"}}] | from_entries' 2>/dev/null || echo '{}')