@dtt_siye/atool 1.1.0

package/skills/clarify-before-build/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: clarify-before-build
+description: 在动手写代码前，先分级评估任务复杂度，通过上下文感知提问澄清需求，避免幻觉和偏差
+version: 1.0.0
+---
+
+# Clarify Before Build
+
+在任何功能实现之前，先评估任务复杂度并澄清需求。这是减少 AI 幻觉和需求偏差的核心机制。
+
+## 任务复杂度分级
+
+在收到用户的实现请求时，先判断复杂度等级：
+
+| 级别 | 名称 | 判断标准 | 行为 |
+|------|------|----------|------|
+| **Tier 0** | 无需提问 | 单值修改、typo、格式调整、明确的单行改动 | 直接执行 |
+| **Tier 1** | 快速确认 | 小改动但有 1-2 个模糊点（如"加个 loading"） | 问 1-2 个关键问题 |
+| **Tier 2** | 结构化澄清 | 新功能、中等复杂度（如"加搜索功能"、"做个设置页"） | 问 3-5 个上下文相关问题 |
+| **Tier 3** | 完整设计 | 新平台、架构级、需求模糊（如"做一个天气 App"） | 委托给 `/brainstorming` |
+
+### 判断 Checklist
+
+对每个实现请求，快速过以下问题：
+
+1. **需求是否完全明确？** — 用户是否已给出所有必要细节（文件位置、具体行为、边界条件）？
+2. **是否存在多种合理实现方式？** — 如果是，需要确认偏好
+3. **改动范围是否可控？** — 是否只涉及 1-3 个文件？
+4. **是否需要引入新依赖/新模式？** — 如果是，需要确认
+
+如果以上任一回答为"不确定"，则至少升一级。
+
+### 退出机制
+
+当用户发出以下信号时，立即按 Tier 0 处理，不再提问：
+
+- "别问了"、"不要问"、"别再问了"
+- "直接做"、"直接实现"、"直接开始"
+- "just do it"、"go ahead"、"stop asking"
+- "不用确认"、"跳过提问"、"不要确认"
+
+## 上下文感知提问原则
+
+### 先读后问
+
+提问前必须先了解项目现状，不问项目中已有明确答案的问题：
+
+1. 读 `CLAUDE.md` / `COMPONENT.md` — 了解项目结构和规范
+2. 读 `package.json` / `pom.xml` / `Cargo.toml` 等依赖文件 — 了解技术栈
+3. 扫描相关源码文件 — 了解现有模式和代码风格
+
+### 好的提问 vs 坏的提问
+
+**坏**（浪费用户时间，答案已在项目中）：
+- "你用什么前端框架？" — package.json 已有答案
+- "项目用什么状态管理？" — 源码已明确
+
+**好**（基于上下文的精确提问）：
+- "我看到你用 Zustand 管理状态，新的搜索功能的状态也用这个模式？还是需要独立的 store？"
+- "现有 API 都用 REST，新的实时通知功能你倾向于 WebSocket 还是 SSE？"
+
+### 反幻觉规则
+
+1. **不假设已安装的库** — 使用前先检查 `package.json` / `pom.xml` 等依赖文件
+2. **不假设现有模式** — 先读相关源码确认实际使用的模式，不凭经验猜测
+3. **不假设用户偏好** — 多种合理方案时，列出选项让用户选择
+4. **不假设项目约定** — 先读项目配置和规范文件
+
+## 按场景的问题模板
+
+### 新功能
+
+- 这个功能的主要使用场景是什么？面向哪类用户？
+- 优先级最高的核心功能是哪个？哪些可以后续迭代？
+- 是否需要与现有功能（如登录、权限）集成？
+- 对性能/可访问性/移动端适配有什么要求？
+
+### Bug 修复
+
+- 能描述一下复现步骤和预期行为吗？
+- 这个 bug 是在特定条件下才出现，还是普遍存在？
+- 是否有相关的错误日志或截图？
+
+### 重构
+
+- 重构的动机是什么？性能、可读性、还是为后续功能做准备？
+- 有哪些行为必须保持不变（即回归风险点）？
+- 是否有测试覆盖需要重构的区域？
+
+### UI 开发
+
+- 有设计稿或 Figma 链接吗？
+- 需要支持的屏幕尺寸/断点有哪些？
+- 动画和交互细节有什么要求？
+
+### 后端/API
+
+- API 的认证方式是什么？
+- 预期的并发量和数据量级？
+- 是否需要分页/缓存/限流？
+
+## 与其他 Skill 的协作
+
+- **Tier 3** → 委托给 `/brainstorming` 进行完整的设计探索
+- **新功能 + 有测试要求** → `/test-driven-development`
+- **重构 + 有回归风险** → `/systematic-debugging`
+- **完成后** → 检查文档是否需要更新（`/doc-coauthoring`）

package/skills/code-review/SKILL.md

@@ -0,0 +1,406 @@
+---
+name: code-review
+description: "AI-driven code quality analysis across 8 dimensions (quality, dead-code, duplication, error-security, architecture, maintainability, coupling-cohesion, deprecation-debt) with scoring, fix suggestions, and refactoring plans. Use independently via /code-review or auto-triggered by project-analyze v5.0 Phase 4."
+version: 0.3.0
+---
+
+# Code Review Skill (aTool v3.0)
+
+AI 主导的代码质量分析，覆盖 8 个维度（含架构合规、可维护性、耦合内聚、技术债务），生成评分报告、修复建议和重构方案。
+
+## 触发方式
+
+| 方式 | 说明 |
+|------|------|
+| `/code-review` | 分析当前项目 |
+| `/code-review src/auth/` | 分析指定目录 |
+| project-analyze v5.0 Phase 4 | 自动触发 |
+| verification-before-completion | 轻量级检查（仅修改文件） |
+
+## 分析步骤
+
+### Step 1: 确定分析范围
+
+- 用户指定目录 → 分析该目录下所有源文件
+- 无指定 → 分析项目根目录下所有源文件
+- 轻量模式（SDD） → 仅分析当前任务修改的文件
+- **知识图谱模式** → 如果 `.atool-docs/knowledge-graph.json` 存在，利用图谱数据进行耦合分析
+
+排除规则（与 project-analyze 一致）：
+- `node_modules/`, `vendor/`, `.git/`, `dist/`, `build/`, `target/`
+- 锁文件、生成文件、第三方代码
+- 测试文件（`*_test.*`, `*.spec.*`, `test_*`）
+
+### Step 2: 加载分析规则
+
+从 `skills/code-review/rules/` 加载 **8 个维度**规则：
+
+| # | 维度 | 文件 | 权重 | 说明 |
+|---|------|------|------|------|
+| 1 | 代码质量 | `rules/quality.md` | 0.15 | 圈复杂度、函数长度、嵌套深度、注释率、参数数量、Halstead Volume |
+| 2 | 死代码检测 | `rules/dead-code.md` | 0.10 | 未使用函数/import、不可达代码、被注释代码块 |
+| 3 | 重复代码 | `rules/duplication.md` | 0.10 | 相似代码块、函数体、抽象不足 |
+| 4 | 错误处理与安全 | `rules/error-security.md` | 0.20 | 空catch、SQL注入、硬编码凭证、未验证输入 |
+| 5 | 架构合规 | `rules/architecture.md` | 0.15 | 分层违反、DDD合规、微服务适应性、包结构 |
+| 6 | 可维护性 | `rules/maintainability.md` | 0.10 | SQALE修复工作量、MI指数、代码异味 |
+| 7 | 耦合与内聚 | `rules/coupling-cohesion.md` | 0.10 | Ca/Ce/Instability、循环依赖、CK Metrics、DSM |
+| 8 | 废弃与债务 | `rules/deprecation-debt.md` | 0.10 | 已废弃API、TODO老化、过时模式、废弃代码段 |
+
+**权重之和验证：** 0.15 + 0.10 + 0.10 + 0.20 + 0.15 + 0.10 + 0.10 + 0.10 = **1.00** ✓
+
+**维度 6/7 加载条件：**
+- 维度 7（耦合与内聚）需要 `.atool-docs/knowledge-graph.json`，不存在时跳过（标记 "skipped (no graph data)"）
+- 维度 6（可维护性）始终加载，MI 计算需要维度 1 的 Halstead Volume 数据
+
+如果项目有技术栈对应规则（如 `rules/rust.md`），额外加载。
+
+### Step 3: 文件扫描
+
+使用 project-analyze 的扫描模式识别源文件：
+- 按文件扩展名过滤（排除 .md, .json, .yaml, .css 等非源文件）
+- 按模块/目录分组（每组最多 **8 个文件**，为规则内容留更多空间）
+- 跳过超大文件（>100KB，只提取签名）
+
+### Step 4: 多 Agent 并行分析
+
+为每个模块/文件组启动 sub-agent：
+- 每个 sub-agent 读取该模块所有源文件
+- 按 8 个维度规则逐项检查
+- 输出：问题列表（severity + file + line + issue + suggestion）
+
+**Agent Dispatch Control（硬性限制）：** 最多 5 个并行 sub-agent。当模块/文件组超过 5 个时：
+1. 按模块重要性评分（如可获取）或文件数降序排列
+2. 派发第一批 5 个 agent
+3. 等待当前批次所有 agent 完成后再派发下一批
+4. 重复直到所有组分析完毕
+这是防止 LLM 并发限制和 API 限流的硬性要求。
+
+**Sub-agent prompt 必须包含：**
+1. 分析范围（文件列表）
+2. **适用的维度规则**的完整内容（不是引用路径）
+   - 维度 1-5, 6, 8：始终注入
+   - 维度 7（耦合与内聚）：仅当知识图谱存在时注入图谱摘要
+3. 输出格式要求（Markdown 表格）
+4. 语言约束（中文输出）
+5. 项目技术栈信息（用于架构合规维度判断）
+6. **知识图谱上下文**（如存在）：当前模块的 Ca/Ce 值、循环依赖状态、依赖模块列表
+
+### Step 5: 评分聚合
+
+```
+# 维度评分（0-100，越高越差）
+dimension_score = min(issues_weighted_sum / normalization_factor * 100, 100)
+
+# 文件级评分（8 维度加权）
+file_score = sum(dimension_score * dimension_weight)
+  where weights: quality=0.15, dead-code=0.10, duplication=0.10,
+                 error-security=0.20, architecture=0.15, maintainability=0.10,
+                 coupling-cohesion=0.10, deprecation-debt=0.10
+
+# 跳过的维度权重重分配
+if coupling-cohesion skipped:
+    redistribute 0.10 proportionally to remaining dimensions
+
+# 项目级评分（按文件大小加权）
+project_score = sum(file_score * file_line_count) / sum(file_line_count)
+```
+
+### Step 6: 生成报告
+
+输出 `CODE_REVIEW.md` 到项目根目录（同时写入 `.atool-docs/code-review/summary.json`）。
+
+## 健康等级
+
+| 分数 | 等级 | 描述 |
+|------|------|------|
+| 0-20 | 健康 | 代码质量良好，可放心维护 |
+| 20-40 | 一般 | 有改进空间但不影响开发效率 |
+| 40-60 | 需关注 | 存在明显问题，建议优先修复 |
+| 60-80 | 较差 | 代码质量较差，维护成本高 |
+| 80-100 | 严重 | 严重技术债务，需系统性重构 |
+
+## 输出模板
+
+```markdown
+# 代码质量报告
+
+**生成时间：** {date}
+**分析范围：** {scope} ({file_count} 文件, {line_count} 行)
+**技术栈：** {stack}
+**分析版本：** v3.0 (8-dimension)
+
+## 综合评分：{score}/100 — {health_level}
+
+| 维度 | 评分 | 权重 | 问题数 | 状态 |
+|------|------|------|--------|------|
+| 代码质量 | {score}/100 | 0.15 | {count} | ✅ |
+| 死代码检测 | {score}/100 | 0.10 | {count} | ✅ |
+| 重复代码 | {score}/100 | 0.10 | {count} | ✅ |
+| 错误处理与安全 | {score}/100 | 0.20 | {count} | ✅ |
+| 架构合规 | {score}/100 | 0.15 | {count} | ✅ |
+| 可维护性 | {score}/100 | 0.10 | {count} | ✅ |
+| 耦合与内聚 | {score}/100 | 0.10 | {count} | ✅/⏭️ |
+| 废弃与债务 | {score}/100 | 0.10 | {count} | ✅ |
+
+## 汇总
+
+- Critical: {n} | Warning: {n} | Info: {n}
+- 死代码估计：约 {lines} 行（{percentage}%）
+- 技术债务比率：{ratio}（{level}）
+- 估算修复工作量：{hours} 人时
+- 循环依赖：{cycle_count} 个
+
+## 代码质量
+
+| Severity | File | Line | Issue | Suggestion |
+|----------|------|------|-------|------------|
+| ... | ... | ... | ... | ... |
+
+## 死代码检测
+
+| Severity | File | Line | Issue |
+|----------|------|------|-------|
+| ... | ... | ... | ... |
+
+## 重复代码
+
+| Severity | Files | Lines | Issue |
+|----------|-------|-------|-------|
+| ... | ... | ... | ... |
+
+## 错误处理与安全
+
+| Severity | File | Line | Issue |
+|----------|------|------|-------|
+| ... | ... | ... | ... |
+
+## 架构合规评估
+
+### 分层违反
+
+| Severity | File | Layer | Violation | Suggestion |
+|----------|------|-------|-----------|------------|
+| ... | ... | ... | ... | ... |
+
+### 微服务适应性（如适用）
+
+| 检测项 | 状态 | 详情 | 建议 |
+|--------|------|------|------|
+| ... | ... | ... | ... |
+
+### 包结构
+
+| 检测项 | 状态 | 详情 |
+|--------|------|------|
+| ... | ... | ... |
+
+## 可维护性评估
+
+**技术债务比率：** {ratio} — {level}
+**MI 均值：** {mi_value}
+**估算修复工作量：** {hours} 人时
+
+| 异味类型 | 数量 | 总修复时间 |
+|----------|------|-----------|
+| ... | ... | ... |
+
+### 高风险文件
+
+| 文件 | MI | CC | 最大函数长度 | 风险因素 |
+|------|-----|-----|------------|---------|
+| ... | ... | ... | ... | ... |
+
+## 耦合与内聚（知识图谱驱动）
+
+**平均耦合度:** Ca={avg_ca}, Ce={avg_ce}
+**循环依赖:** {cycle_count} 个
+
+### 模块耦合矩阵
+
+{DSM matrix}
+
+### 循环依赖
+
+| 循环路径 | 涉及模块数 | 破坏建议 |
+|----------|-----------|---------|
+| ... | ... | ... |
+
+### CK Metrics 告警（OO 项目）
+
+| 类 | WMC | CBO | LCOM | 问题 |
+|----|-----|-----|------|------|
+| ... | ... | ... | ... | ... |
+
+## 废弃与债务
+
+**已废弃 API：** {count} 处
+**TODO/FIXME 积压：** {count} 个（其中严重老化 {n} 个）
+**过时模式：** {count} 处
+
+### 已废弃 API 使用
+
+| 严重度 | 文件 | 行 | 废弃 API | 替代方案 |
+|--------|------|-----|---------|---------|
+| ... | ... | ... | ... | ... |
+
+### TODO 老化分析
+
+| 严重度 | 文件 | 行 | 标记 | 内容 | 年龄 |
+|--------|------|-----|------|------|------|
+| ... | ... | ... | ... | ... | ... |
+
+## 模块级架构健康度
+
+| 模块 | 分层合规 | 耦合 | 内聚 | 债务 | 综合 | 严重问题数 |
+|------|----------|------|------|------|------|-----------|
+| ... | ... | ... | ... | ... | ... | ... |
+
+## 重构建议
+
+### 高优先级重构（影响架构健康）
+
+1. **{重构名称}**
+   - 当前状态：{描述}
+   - 目标状态：{描述}
+   - 影响范围：{文件列表}
+   - 步骤：
+     1. {step 1}
+     2. {step 2}
+     3. {step 3}
+   - 预计工作量：{S/M/L}
+
+## 优先修复清单（Top 10）
+
+1. [{severity}] {file}:{line} — {issue} → {fix_suggestion}
+2. ...
+```
+
+## 轻量级模式（SDD 集成）
+
+用于 `verification-before-completion` 和 `writing-plans` 中的代码质量检查。
+
+**与完整分析的区别：**
+
+| 特性 | 轻量级 | 完整分析 |
+|------|--------|----------|
+| 范围 | 当前修改的文件 | 全项目或指定目录 |
+| 维度 | 仅 Critical 级别检查 | 全部 8 维度 |
+| 输出 | 内联反馈，无文件 | CODE_REVIEW.md |
+| 评分 | 不评分 | 完整评分 |
+| 耗时 | <1 分钟 | 5-15 分钟 |
+
+**轻量级检查项（仅 Critical）：**
+- 硬编码凭证/密钥
+- SQL 注入风险
+- 空 catch/except 块
+- 不可达代码
+- 函数圈复杂度 >15
+- 函数长度 >120 行
+- 分层违反（Controller 直接调用 Repository/DAO）
+- **已废弃 Critical API 使用**（React 废弃生命周期、Vue 2 废弃 API、eval/exec）
+
+## Phase 4 集成（project-analyze v5.0）
+
+在 project-analyze v5.0 的 Phase 4 中自动调用：
+- Phase 0-1: 不执行代码审查
+- Phase 2 (L2+): 执行完整 8 维度代码审查，生成 CODE_REVIEW.md
+- Phase 2 (L3): 执行完整代码审查 + 每个问题的修复代码建议 + 重构方案
+
+## Skill 协作
+
+### 与 software-architecture 的协作
+
+- 当 Dimension 5（架构合规）发现**重度架构违反**时（如：分层大面积违反、循环依赖 >3 个、微服务边界严重不合理），在报告末尾追加：
+  > ⚠️ 检测到重大架构合规问题。建议运行 `/software-architecture` skill 进行系统级架构评审，确定根因和改进方案。
+- 架构合规评分 < 40 的模块自动标记为「需架构评审」
+
+### 与 conventions skills 的协作
+
+- 8 个维度规则提供通用检查标准；**如需更详细的栈级规范**（如 Java 命名约定、React 组件规范、Go 错误处理模式），参考对应的 `{stack}-conventions` skill
+- 架构合规维度中的分层检查应与对应 conventions skill 的分层规则保持一致
+- 支持的 conventions skills：`java-conventions`、`web-conventions`、`go-conventions`、`python-conventions`、`rust-conventions`、`swift-conventions`、`flutter-conventions`、`react-native-conventions`、`android-conventions`、`harmony-conventions`、`devops-conventions`
+
+### 与 project-query 的协作
+
+- 需要查询分析结果的详细数据时，建议运行 `/project-query`
+- 可查询 CODE_REVIEW.md 的评分明细、特定维度问题列表、模块级健康度等结构化数据
+
+### 与 doc-standards-enforcer 的协作
+
+- 生成的 `CODE_REVIEW.md` 和 `.atool-docs/` 下的报告文件应遵循 `doc-standards-enforcer` 的格式规范
+- 独立运行的 `/code-review` 不强制执行文档标准验证，但建议用户在文档正式交付前使用 `doc-standards-enforcer` 检查
+
+**知识图谱集成：**
+- Phase 3 完成后，`.atool-docs/knowledge-graph.json` 可用于维度 7 的耦合分析
+- 如果 Phase 4 在 Phase 3 之前运行（如独立调用 `/code-review`），维度 7 跳过
+- 独立调用时建议先运行 `/project-analyze --phase 0-3` 生成知识图谱
+- 知识图谱格式兼容 v5.0（14 node types, 24 edge types），自动适配新旧版本
+
+MODULE-DOC.md 新增以下章节：
+- `## 已知问题` — 该模块的代码质量问题摘要
+- `## 架构合规评估` — 分层合规表格 + 包结构分析 + 依赖方向
+- `## 耦合分析` — Ca/Ce/Instability + 循环依赖 + CK Metrics
+- `## 技术债务` — MI 指数 + 废弃 API + TODO 老化
+
+## 跨 IDE 适配
+
+### IDE 检测逻辑
+
+```
+if "Agent" tool available (sub-agent dispatch):
+  IDE = "claude"    → 并行 sub-agent 模式
+elif Cursor environment detected (CURSOR_* env vars):
+  IDE = "cursor"    → 顺序分析模式
+elif Kiro environment detected:
+  IDE = "kiro"      → 轻量级模式
+else:
+  IDE = "claude"    → 默认并行
+```
+
+### 执行模式矩阵
+
+| 模式 | 适用 IDE | 分析方式 | 维度 | 输出 |
+|------|----------|----------|------|------|
+| 完整并行 | Claude Code | 多 sub-agent 并行 | 全部 8 维度 | CODE_REVIEW.md + summary.json |
+| 顺序分析 | Cursor | 逐模块顺序分析 | 全部 8 维度 | CODE_REVIEW.md + summary.json |
+| 轻量级 | Kiro | 仅 Critical 检查，无 sub-agent | 仅 Critical 级 | 内联反馈，无文件输出 |
+
+### Cursor 顺序模式
+
+- 模块按 importance 排序，逐个分析
+- 每完成一个模块输出进度行：`[Code Review] ✓ module-name (12 issues found)`
+- 所有 8 个维度规则正常加载执行
+- 评分聚合、CODE_REVIEW.md 生成与 Claude 模式一致
+
+### Kiro 轻量级模式
+
+- **不启动 sub-agent**，由主 agent 直接执行
+- 仅执行「轻量级检查项」（见上方轻量级模式章节）
+- 维度 7（耦合与内聚）需要知识图谱，不存在时跳过
+- **不生成 CODE_REVIEW.md 和 summary.json**
+- 输出格式：内联 Markdown 反馈，列出发现的 Critical 问题
+
+---
+
+## 质量检查清单
+
+- [ ] 8 个维度规则全部加载并执行（维度 7 可选）
+- [ ] 评分计算正确（权重之和 = 1.00）
+- [ ] 跳过的维度权重已重分配
+- [ ] 问题按严重度正确分类（Critical/Warning/Info）
+- [ ] 修复建议具体可执行（不是"改进代码"等空话）
+- [ ] 死代码估算行数合理
+- [ ] 安全问题无假阳性（环境变量引用不算硬编码）
+- [ ] 重复代码相似度判断合理（排除样板代码）
+- [ ] 架构合规维度已加载并执行（第 5 维度）
+- [ ] 分层违反已检测（import 分析，白名单排除已应用）
+- [ ] 微服务适应性已评估（如适用）
+- [ ] **可维护性维度已执行**（SQALE 修复工作量、MI 指数、代码异味）
+- [ ] **耦合与内聚维度已执行或标记跳过**（Ca/Ce、循环依赖、CK Metrics）
+- [ ] **废弃与债务维度已执行**（已废弃 API、TODO 老化、过时模式、废弃代码段）
+- [ ] 重构建议包含具体步骤和预计工作量
+- [ ] 模块级架构健康度表格已生成（含 8 维度评分）
+- [ ] CODE_REVIEW.md 格式符合模板
+- [ ] 健康等级与评分匹配
+- [ ] 优先修复清单按严重度×影响范围排序
+- [ ] `.atool-docs/code-review/summary.json` 已写入