@dtt_siye/atool 1.1.0

package/skills/project-analyze/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: project-analyze
+description: "Deep project analysis v5.0 — 7-phase pipeline with five-dimensional analysis framework, 14 node types, 24 edge types, 5-level granularity zooming, interactive visualization (Cytoscape.js), and query system. 5 depth levels (L1-L5): Discovery → Pre-Scan → Inventory → Deep Analysis → Knowledge Graph → Multi-Dimensional Analysis → Code Quality → Document Synthesis → Validation. Checkpoint/resume, incremental docs, large-module decomposition. Zero-KT standard, Chinese output. 触发：分析项目/生成文档/analyze project/generate docs/project analysis"
+version: 5.0.0
+---
+
+# Project Analyzer v5.0
+
+11 阶段流水线深度分析项目，通过知识图谱驱动生成完整文档。支持 16 种技术栈，5 级分析深度（L1-L5），断点续传，超大模块自动拆分。
+
+## 核心原则：Zero-KT（零知识传递）
+
+所有文档满足「Zero-KT」标准：**新人仅凭文档即可独立完成任务，无需向任何人提问**：
+1. **理解项目**：为什么架构是这样设计的，每个模块为什么存在
+2. **添加功能**：知道在哪个文件、哪个层、按照什么模式添加
+3. **修复缺陷**：知道错误可能在哪个模块、如何调试、如何验证
+4. **理解业务**：知道核心业务术语、业务规则、数据含义
+
+**三人测试**：文档必须通过——(1) 新入职开发者能理解 (2) 不看源码能操作 (3) 遇到问题有排查指引。**所有 sub-agent prompt 必须包含此原则作为质量评判标准。**
+
+## 触发条件
+
+- 用户说「分析项目」「生成文档」「项目分析」「文档生成」「分析代码」「帮我分析这个项目」
+- 用户说 "analyze project", "analyze codebase", "generate docs", "project analysis", "understand this codebase"
+- 老项目接入 aTool 需要建立文档基线
+
+## 全局输出语言约束（硬性）
+
+所有文档**必须中文**（README.md、COMPONENT.md、UI_STYLE.md、CODE_REVIEW.md、docs/、MODULE-DOC.md、ASCII 图标注）。
+**例外（保持英文）**：代码块、文件路径、技术标识符（变量/函数/类名）、API 路径、包名、Git 分支名。
+**每个 sub-agent prompt 的第一条指令即为此约束，不可遗漏。**
+
+## 分析深度等级
+
+| 等级 | 说明 | 适合场景 |
+|------|------|----------|
+| L1 | 结构扫描：目录树 + 依赖表 + 技术栈识别 | 快速概览、>500 文件项目 |
+| L2 | 架构分析：L1 + 架构图 + 数据流 + 模块文档 + docs/ + 代码质量（**默认**） | 大多数场景 |
+| L3 | 深度实现：L2 + 核心函数签名 + 接口定义 + 关键实现细节 + 代码示例 + 设计决策记录 | 关键模块、交接文档 |
+| L4 | 函数级分析：L3 + 逐函数调用链追踪 + 性能热点识别 + 安全审计点 + 数据流路径 | 质量审查、性能优化 |
+| L5 | 跨模块行为推断：L4 + 时序图 + 状态机 + 异常路径追踪 + 数据血缘 | 架构重构、完整技术文档 |
+
+**选择规则**：用户未指定 → 默认 L2；<50 文件 → 建议提升到 L3；L3/L4/L5 对所有项目规模可用（通过多批次执行）。**L1 特殊**：Phase 0.5 完全替代 Phase 1（0 AI agents，纯 bash 提取）。
+
+---
+
+## Pipeline Controller
+
+### Execution Flow
+
+1. **Detect IDE** → set execution_mode (parallel/sequential/compressed)
+2. **Read `analysis-state.json`** (if exists) → determine resume point (see `phases/phase0-discovery.md` 0.5a)
+3. **Execute Phase 0**: Read `phases/phase0-discovery.md` → detect stack, evaluate scale, compute importance, get user confirmation → write `analysis-state.json`
+4. **Execute Phase 0.5 (Pre-Scan)**: Run `source lib/pre-scan.sh && pre_scan_project "$PROJECT_ROOT" "$PRESCAN_DIR"` → pure bash structural extraction → output `.atool-docs/pre-scan/{module-slug}.json` + `manifest.json` → write checkpoint `phase0_5_prescan = "completed"`
+5. Based on Phase 0 + Phase 0.5 pre-scan data → set depth, scale, module list
+6. **For each phase in pipeline order**:
+   - Check preconditions in `analysis-state.json`
+   - If not completed:
+     - **Read `phases/phase{N}-{name}.md`** for detailed instructions
+     - Execute phase → write checkpoint to `analysis-state.json`
+6. **Phase 6**: Read `phases/phase6-validation.md` → validate all outputs → write summary
+
+### Pipeline Order
+
+```
+Phase 0  → phases/phase0-discovery.md       (always)
+Phase 0.5→ phases/phase0.5-prescan.md       (always, pure bash, no AI)
+Phase 1  → phases/phase1-inventory.md       (always; L1 depth: skip, use Phase 0.5 data)
+Phase 2  → phases/phase2-deep-analysis.md   (skip if Kiro)
+Phase 2a → phases/phase2a-l4-analysis.md    (only if depth >= L4, skip if Kiro)
+Phase 2b → phases/phase2b-l5-analysis.md    (only if depth >= L5, skip if Kiro)
+Phase 3  → phases/phase3-knowledge-graph.md (always, main agent only)
+Phase 3a → phases/phase3a-multi-dimensional.md (always, Kiro: structure only)
+Phase 4  → phases/phase4-code-quality.md    (skip if Kiro)
+Phase 5  → phases/phase5-synthesis.md       (always)
+Phase 6  → phases/phase6-validation.md      (always)
+```
+
+### IMPORTANT RULE
+
+**Before executing ANY phase, you MUST read the corresponding phase file from `phases/phase{N}-{name}.md`. Do not execute from memory. Each phase file contains critical details not duplicated here.**
+
+### Phase 0.5: Pre-Scan (纯 Bash，无 AI)
+
+**目标**：使用 grep/awk/jq 秒级提取所有语法元数据，消除 AI 重复读取。
+
+**执行**：
+1. 读取 `analysis-state.json` 获取模块列表和技术栈
+2. 执行 `source lib/pre-scan.sh && pre_scan_project "$PROJECT_ROOT" "$PRESCAN_DIR"`
+3. 输出 `.atool-docs/pre-scan/{module-slug}.json` + `manifest.json`
+4. 写入检查点 `phase0_5_prescan = "completed"`
+
+**支持语言**：Python, Java/Kotlin, TypeScript/JavaScript/Vue/Svelte, Go, Rust, 通用 fallback
+
+**性能目标**：152 文件/10 模块 < 10 秒（vs AI Phase 1 的 2-4 分钟）
+
+**增量扫描**：比对文件 MD5 hash，仅重新扫描变更文件。
+
+**降级**：pre-scan 失败时，Phase 1 自动回退到全量 AI 提取（v5.0 行为）。
+
+详细指令：`phases/phase0.5-prescan.md`
+
+### Sub-Agent Prompts
+
+When dispatching sub-agents for phases 1, 2, 2a, 4:
+- Read the prompt template from `prompts/{name}-agent.md`
+- Fill in module-specific variables (module name, inventory data, rules content, etc.)
+- Dispatch with the filled prompt
+
+| Phase | Prompt Template | Variables to Fill |
+|-------|----------------|-------------------|
+| Phase 1 | `prompts/inventory-agent.md` | file_list, module-slug |
+| Phase 2 | `prompts/deep-analysis-agent.md` | module_name, inventory_json_content, rules_content, stack, project_name, module_list, depth_specific_instructions |
+| Phase 2a | `prompts/l4-analysis-agent.md` | module_name, analysis_json_content, inventory_json_content, file_list |
+| Phase 4 | `prompts/code-review-agent.md` | module_name, inventory_json, relevant_graph_subtree, multi_dimensional_context, file_list |
+
+### Batch Dispatch Rule (Hard Limit)
+
+**Maximum 5 concurrent sub-agents at all times.** When modules > 5, dispatch in batches of 5 by importance descending order. Wait for all agents in current batch to complete before dispatching next batch.
+
+---
+
+## Cross-IDE Adaptation
+
+### IDE Detection
+
+```
+if "Agent" tool available (sub-agent dispatch):
+  IDE = "claude"    → full parallel mode
+elif Cursor environment detected (CURSOR_* env vars):
+  IDE = "cursor"    → sequential mode
+elif Kiro environment detected:
+  IDE = "kiro"      → compressed mode
+else:
+  IDE = "claude"    → default full parallel
+```
+
+### Phase Availability Matrix
+
+| Phase | Claude | Cursor | Kiro | Notes |
+|-------|--------|--------|------|-------|
+| Phase 0 | full | full | full | All IDEs |
+| Phase 0.5 | full (bash) | full (bash) | full (bash) | Pure shell, no AI |
+| Phase 1 | parallel | sequential | compressed (file counts only) | |
+| Phase 2 | parallel | sequential | **skip** | Kiro uses inventory directly |
+| Phase 2a | parallel | sequential | **skip** | L4 function-level |
+| Phase 2b | parallel+aggregate | sequential | **skip** | L5 cross-module |
+| Phase 3 | main agent | main agent | main agent | No sub-agents |
+| Phase 3a | 5 dimensions | 5 dimensions | structure only | v5.0 |
+| Phase 4 | parallel | sequential | **skip** | |
+| Phase 5 | full | full | L1 quality from inventory | |
+| Phase 6 | full | full | full | All IDEs |
+
+### Kiro Compressed Mode
+Phase 0.5: full pre-scan (bash, same as all IDEs). Phase 1: file counts + import/export counts only (no signatures). Phase 5: L1 quality docs from pre-scan inventory. No CODE_REVIEW.md.
+
+### Cursor Sequential Mode
+Modules processed in importance order, one at a time. Progress line per module. Phase 3 and 6 execute normally.
+
+---
+
+## State Management & Checkpoint/Resume
+
+### Checkpoint Write Timing
+After each sub-agent completes a module analysis, immediately write checkpoint to `analysis-state.json`:
+```
+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
+```
+
+### Resume Flow
+1. Read `.atool-docs/analysis-state.json`
+2. If no state file → full analysis
+3. If `phase0_5_prescan != "completed"` → execute Phase 0.5
+4. Detect stale modules (file hash mismatch) → mark for re-analysis
+5. Determine resume point from checkpoint
+6. Execute pending phases, skip completed, rerun stale
+7. Update final state
+
+Detailed resume logic: see `phases/phase0-discovery.md` section 0.5a.
+
+### Incremental Document Recovery
+When resuming Phase 5, incrementally update already-generated documents using `<!-- aTool-module-start:{slug} -->` markers. Only regenerate changed modules.
+
+---
+
+## Output File Summary
+
+### Final Deliverables (project directory)
+
+| File | Condition |
+|------|-----------|
+| `README.md` | always |
+| `COMPONENT.md` | always |
+| `CODE_REVIEW.md` | L2/L3/L4/L5 |
+| `UI_STYLE.md` | UI projects only |
+| `CLAUDE.md` | append project rules |
+| `.cursor/rules/atool-conventions.mdc` | always |
+| `.kiro/steering/atool-conventions.md` | always |
+| `docs/` (~15 files) | L2/L3/L4/L5 |
+
+### Intermediate Artifacts (.atool-docs/)
+
+| File | Phase |
+|------|-------|
+| `analysis-state.json` | Phase 0 |
+| `pre-scan/{module-slug}.json` | Phase 0.5 |
+| `pre-scan/manifest.json` | Phase 0.5 |
+| `inventory/{module-slug}.json` | Phase 1 |
+| `modules/{module-slug}/MODULE-DOC.md` | Phase 2 |
+| `modules/{module-slug}/analysis.json` | Phase 2 |
+| `modules/{module-slug}/references.json` | Phase 2 |
+| `modules/{module-slug}/l4-analysis.json` | Phase 2a (L4+) |
+| `modules/{module-slug}/l5-analysis.json` | Phase 2b (L5) |
+| `cross-module-behavior.json` | Phase 2b (L5) |
+| `knowledge-graph.json` | Phase 3 |
+| `multi-dimensional-analysis.json` | Phase 3a |
+| `query-index.json` | Phase 3a |
+| `visualization/index.html` | Phase 3a |
+| `code-review/{module-slug}.json` | Phase 4 |
+
+### Multi-Project Extra Outputs
+
+| File | Description |
+|------|-------------|
+| `.atool-docs/discovery.json` | Project discovery record |
+| `.atool-docs/summaries/{name}/summary.md` | Sub-project summary |
+| `.atool-docs/cross-project-analysis.md` | Cross-project relations |
+
+---
+
+## Error Handling
+
+- Analysis state file corrupted → warn user, offer fresh start or manual recovery
+- Pre-scan failure → graceful degradation: skip Phase 0.5, Phase 1 falls back to full AI extraction (v5.0 behavior)
+- Sub-agent fails mid-analysis → mark module as "failed" in state, continue with next module, report in Phase 6
+- Source file read error → skip file, mark in inventory as "unreadable", continue
+- Disk space insufficient → warn immediately, offer partial save
+- Resume with changed state version → auto-migrate v3.0/v4.0 → v5.0 (add missing fields with defaults)
+
+---
+
+## Important Notes
+
+- Always check `.atool-docs/` before starting; offer incremental update if exists
+- Never overwrite user-edited content — only fill sections marked as auto-generated
+- Projects >500 files: warn about potential long runtime
+- Output summary report upon completion (modules, files, deliverables)
+- Each module document must be immediately readable (Zero-KT standard)
+- Existing CLAUDE.md: only append project rules section
+- docs/: only update aTool-numbered files (101, 201-801), never modify user-created docs
+- All inferred content marked `[推断]`
+- UI wireframes: UI projects only (web/mobile)
+- **Never fabricate**: only record what is visible in code
+
+---
+
+## Skill Collaboration
+
+| Collaborating Skill | Trigger Condition | Interaction |
+|---------------------|-------------------|-------------|
+| code-review | Phase 4 eight-dimension review | References rules/ files |
+| software-architecture | Phase 3a structural layer violation rate >30% | Suggest running |
+| {stack}-conventions | Phase 2 deep analysis | Load stack-level conventions |
+| doc-standards-enforcer | Phase 5 document generation | Validate frontmatter format |
+| smart-dispatch | LARGE/XLARGE projects | Batch parallel by module |
+| project-query | Need to query analysis results | User manually invokes /project-query |
+| clarify-before-build | Before Phase 0 user confirmation | Requirement clarification (auto-injected) |

package/skills/project-analyze/phases/phase0-discovery.md

@@ -0,0 +1,278 @@
+# Phase 0: Discovery & Planning
+
+**目标**：检测技术栈、评估规模、制定策略、获得用户确认。
+
+## 前置条件
+
+- 无前置阶段（首个阶段）
+- 如存在 `.atool-docs/analysis-state.json`，先执行 Resume 检测（见 0.5a）
+
+## 详细步骤
+
+### 0.1 技术栈检测
+
+复用 `lib/detect-stack.sh` 逻辑：
+
+1. 检查信号文件（package.json, pom.xml, Cargo.toml, go.mod 等）
+2. 确定具体技术栈（如 `java-spring`, `web-react`, `mobile-swift`）
+3. Monorepo：检查各子目录信号文件，按栈分组
+
+### 0.2 规模评估与策略选择
+
+统计源文件数（排除 node_modules, build, .git, vendor, target, dist），按规模选择策略：
+
+| 规模 | 文件数 | 建议深度 | 覆盖率 | 最大 Agent | 多批次 | 说明 |
+|------|--------|---------|--------|-----------|--------|------|
+| TINY | 1-50 | L3 | 100% | 5 | 否 | 小项目全量深度分析 |
+| SMALL | 51-200 | L2 | 100% | 5 | L3+ 自动分批 | 中小项目，L3+ 按模块分批 |
+| MEDIUM | 201-500 | L2 | 100% | 5 | L3+ 自动分批 | 中型项目，每批 5 模块 |
+| LARGE | 501-1500 | L2 | Top 80% | 5 | L3+ 自动分批 | 非核心模块 L2，核心 L3+ |
+| XLARGE | 1501-5000 | L2 | Top 50% | 5 | L3+ 始终分批 | 核心 L3+，重要 L2，其余 L1 |
+| MEGA | 5001+ | L2 | 用户选择 | 5 | Wave 策略 | 多波策略，Wave 深度递增 |
+
+**深度覆盖规则**：建议深度为推荐值，用户可在 Phase 0.6 覆盖为任意深度。LARGE/XLARGE 的覆盖率仅影响 L4/L5 深度的模块范围，所有模块至少 L2。
+
+### 0.2a 批量派发规则（硬性限制）
+
+**无论项目规模如何，同时运行的 sub-agent 上限为 5 个。** 这是防止 LLM 并发限制和 API 限流的硬性要求。
+
+当模块数量超过 5 时，按以下规则分批派发：
+1. 将所有模块按 importance 评分**降序排列**（高重要性模块优先）
+2. 派发第一批 5 个 agent（Top 5 重要性模块）
+3. **等待当前批次所有 agent 完成**后再派发下一批
+4. 重复直到所有模块分析完毕
+
+此规则适用于 Phase 1（Inventory）、Phase 2（Deep Analysis）和 Phase 4（Code Quality）。
+
+### 0.3 重要性评分 (v5.0: 8 因子)
+
+调用 `lib/compute-importance.sh` 计算模块重要性，v5.0 新增 3 个因子：
+
+| 因子 | 权重 | 说明 |
+|------|------|------|
+| centrality | 0.20 | 有多少模块 import 此模块 |
+| size | 0.15 | log(file_count+1)/log(max+1) |
+| entry_point | 0.15 | 包含 router/main/controller 文件 |
+| business_critical | 0.15 | 路径包含业务关键词 |
+| recency | 0.10 | 近 30 天 git 提交活跃度 |
+| **layer_core** | **0.10** | **是否在 service/domain 核心业务层** |
+| **api_surface** | **0.10** | **暴露的 API 端点数量** |
+| **data_ownership** | **0.05** | **拥有的数据实体数量** |
+
+总分 0.0-1.0，分三档：deep(>=0.6), catalog(>=0.3), skip(<0.3)。
+
+模块按 importance 降序排列，LARGE/XLARGE 取 Top N。
+
+#### 0.3a 架构层检测 (v5.0 NEW)
+
+调用 `lib/knowledge-graph.sh` 的 `detect_architectural_layers()` 进行启发式层检测。
+
+检测 8 种架构层：
+| 层类型 | 匹配模式 |
+|--------|---------|
+| presentation | controller, api, route, view, page, screen, handler, endpoint |
+| service | service, usecase, application, facade, manager, logic |
+| repository | repository, dao, mapper, gateway, persistence, store |
+| domain | domain, model, entity, aggregate, valueobject |
+| infrastructure | config, util, helper, common, shared, infra, middleware |
+| ui | component, widget, layout, template |
+| test | test, spec, mock, fixture, __tests__ |
+| data | schema, migration, seed, database |
+
+检测结果写入 `analysis-state.json` 的 `layers.detected` 和 `layers.assignments`。
+Phase 2 中 sub-agent 会验证和修正这些分配。
+
+### 0.4 MEGA Wave 策略
+
+5001+ 文件项目使用分波分析：
+
+```
+Wave 1 (L1 Quick Scan): 所有模块 → 产出 inventory.json（轻量）
+Wave 2 (L2 Deep): 用户从 Wave 1 结果中选择核心模块（≤20）→ 深度分析
+Wave 3 (L2 Selective): 根据知识图谱发现的关键依赖模块（≤15）→ 补充分析
+Wave 4 (L3/L4/L5 Focused): 用户指定的特定模块（≤5）→ 最深度分析（可选 L3/L4/L5）
+```
+
+每波结束后向用户展示发现摘要，由用户决定是否继续下一波。
+
+### 0.5 初始化状态文件
+
+写入 `.atool-docs/analysis-state.json`（v5.0 schema）：
+
+```json
+{
+  "version": "5.0",
+  "pipeline": "6-phase",
+  "status": "planning",
+  "created_at": "2024-01-01T00:00:00Z",
+  "updated_at": "2024-01-01T00:00:00Z",
+  "stack": "web-react",
+  "template": "web",
+  "depth": "L4",
+  "scale": "MEDIUM",
+  "total_files": 342,
+  "total_modules": 28,
+  "ide": "claude",
+  "checkpoint": {
+    "last_completed_phase": "phase2",
+    "last_completed_module": "user-management",
+    "next_pending_module": "order-management",
+    "batch_index": 2,
+    "total_batches": 6,
+    "timestamp": "2024-01-01T00:05:00Z"
+  },
+  "phases": {
+    "phase0_discovery": { "status": "completed", "at": "..." },
+    "phase0_5_prescan": "pending",
+    "phase1_inventory": { "status": "pending" },
+    "phase2_deep_analysis": { "status": "pending" },
+    "phase2a_l4_analysis": { "status": "pending" },
+    "phase2b_l5_analysis": { "status": "pending" },
+    "phase3_knowledge_graph": { "status": "pending" },
+    "phase3a_multi_dimensional": { "status": "pending" },
+    "phase4_code_quality": { "status": "pending" },
+    "phase5_synthesis": { "status": "pending" },
+    "phase6_validation": { "status": "pending" }
+  },
+  "layers": {
+    "detected": ["presentation", "service", "repository", "domain", "infrastructure"],
+    "assignments": {
+      "user-management": "presentation",
+      "auth-service": "service",
+      "user-repository": "repository"
+    },
+    "method": "heuristic"
+  },
+  "multi_dimensional": {
+    "structural": { "status": "pending" },
+    "behavioral": { "status": "pending" },
+    "data": { "status": "pending" },
+    "quality": { "status": "pending" },
+    "semantic": { "status": "pending" }
+  },
+  "modules": {
+    "user-management": {
+      "path": "src/views/user/",
+      "importance": 0.87,
+      "file_count": 15,
+      "file_hashes": { "src/views/user/UserList.vue": "abc123" },
+      "phase1_status": "pending",
+      "phase2_status": "pending",
+      "phase2a_status": "pending",
+      "phase2b_status": "pending",
+      "phase4_status": "pending",
+      "phase5_docs_generated": false,
+      "depth_override": null
+    }
+  },
+  "batches": {
+    "phase2": {
+      "total_batches": 6,
+      "current_batch": 0,
+      "batch_plan": [
+        { "batch": 1, "modules": ["auth", "user-management", "dashboard", "api-core", "store"], "status": "pending" }
+      ]
+    }
+  },
+  "depth_plan": {
+    "requested_depth": "L4",
+    "module_depth_overrides": {},
+    "estimated_batches": { "phase2": 6, "phase2a": 6, "phase2b": 4 }
+  },
+  "strategy": {
+    "max_agents": 5,
+    "coverage": "100%",
+    "sampling": "none"
+  }
+}
+```
+
+**向后兼容**：读取 v3.0/v4.0 文件时，`phase3a_multi_dimensional` 默认 "pending"，`layers` 和 `multi_dimensional` 默认空，`checkpoint` 默认 null，`depth` 保持原值。
+
+### 0.5a Resume 检测（Phase 0 前置）
+
+执行 Phase 0 之前，检查是否存在可恢复的分析：
+
+```
+state_file = .atool-docs/analysis-state.json
+
+if not exists(state_file):
+    → 全新分析，执行 Phase 0
+
+state = read(state_file)
+
+if state.status == "completed":
+    → 展示「检测到已完成的分析（技术栈、深度、日期）」
+    → 选项: [r=重新分析 / i=增量更新 / n=跳过]
+
+else (中断的分析):
+    checkpoint = state.checkpoint
+    completed_phases = [p for p in state.phases if status == "completed"]
+    completed_modules = count modules with phase2_status == "completed"
+    stale_modules = modules where file_hashes mismatch
+
+    → 展示：
+      技术栈: {stack}
+      深度: {depth}
+      已完成阶段: {completed_phases}
+      已完成模块: {completed_modules}/{total_modules}
+      文件变更模块: {stale_modules}（需重新分析）
+      断点: Phase {checkpoint.last_completed_phase}, 模块 {checkpoint.last_completed_module}
+    → 选项:
+      [c] 从断点恢复（推荐）
+      [r] 全部重新分析
+      [d] 删除分析数据并退出
+```
+
+### 0.6 用户确认（必须）
+
+向用户展示分析计划并获得确认：
+
+```
+📋 分析计划
+技术栈: web-react (React 18 + TypeScript)
+项目规模: MEDIUM (342 文件, 28 模块)
+
+推荐深度: L2 (架构分析)
+可用深度:
+  L1  结构扫描          ~5分钟    ~10K tokens
+  L2  架构分析（推荐）    ~15分钟   ~50K tokens
+  L3  深度实现           ~30分钟   ~100K tokens   [分6批]
+  L4  函数级分析         ~60分钟   ~200K tokens   [分6批]
+  L5  跨模块行为推断      ~90分钟   ~350K tokens   [分6+4批]
+
+策略: 全量深度分析, 最多 5 并行 Agent（按 importance 分批）
+预估产出: README.md + COMPONENT.md + CODE_REVIEW.md + docs/ 知识库(~15 文件) + IDE 规则
+
+请确认: [回车=推荐深度] / [L1-L5] / [m=混合模块深度] / [n=取消]
+```
+
+#### 0.6a 混合深度配置
+
+如果用户选择 `m`，进入交互式模块深度配置：
+
+```
+模块深度配置（共 28 模块）:
+默认深度: L2
+
+Top 10 模块（按 importance）:
+  1. auth            (0.95)  → L2
+  2. user-management (0.87)  → L2
+  3. api-core        (0.82)  → L2
+  ...
+
+输入模块编号和深度（如 "1 L4, 2 L5"）或直接回车确认全部使用默认深度:
+```
+
+混合深度写入 `depth_plan.module_depth_overrides` 字段。
+
+## 输出
+
+- `.atool-docs/analysis-state.json` — 初始化的完整状态文件
+- 控制台展示分析计划并获得用户确认
+
+> **注意**：Phase 0 完成后，自动进入 Phase 0.5 Pre-Scan（纯 bash 执行，无 AI 介入）
+
+## IDE 适配
+
+所有 IDE 均执行 Phase 0（无差异）。

package/skills/project-analyze/phases/phase0.5-prescan.md

@@ -0,0 +1,139 @@
+# Phase 0.5: Pre-Scan
+
+**目标**：快速结构化元数据提取 — 使用 grep/awk/jq 扫描源码，无需 AI 介入。
+
+## 前置条件
+
+- Phase 0 已完成（`analysis-state.json` 包含模块列表和技术栈）
+
+## 详细步骤
+
+### 0.5.1 执行方式
+
+纯 bash 执行，不涉及 AI agent：
+
+```bash
+source lib/pre-scan.sh
+pre_scan_project "$PROJECT_ROOT" "$OUTPUT_DIR"
+```
+
+- `OUTPUT_DIR` 默认为 `.atool-docs/pre-scan/`
+- 内部调用 `detect_stack()` 确定主语言，仅调用相关语言提取器
+- 支持的语言：Python, Java/Kotlin, TypeScript/JavaScript/Vue/Svelte, Go, Rust, 通用 fallback
+
+### 0.5.2 语言提取器
+
+每种语言提取器基于 grep+awk 提取以下结构信息：
+
+| 字段 | 提取方式 | 说明 |
+|------|----------|------|
+| imports | `grep -E '^(from \|import )'` | 含 from/import 源、本地/外部标记 |
+| exports | 从 classes + functions 推导 | 非方法函数 + 公开类 |
+| classes | `grep -E '^class '` | 含继承关系 |
+| functions | `grep -E '^def '` | 含参数签名、是否为方法 |
+| decorators | `grep -E '^@'` | 含路由装饰器标记 |
+| api_endpoints | 路由模式匹配 | HTTP 方法 + 路径 |
+| data_models | 基类模式匹配 | ORM/Pydantic/Schema 类型 |
+
+### 0.5.3 增量检测
+
+- 每次扫描记录文件 MD5 hash
+- 再次扫描时比对 hash，仅重新扫描变更文件
+- 模块级：如果所有文件 hash 未变，跳过整个模块
+
+### 0.5.4 输出格式
+
+**模块级** (`.atool-docs/pre-scan/{module-slug}.json`)：
+
+```json
+{
+  "module": "auth",
+  "scan_metadata": { "scan_timestamp": "...", "extraction_method": "grep+awk+jq" },
+  "files": [
+    {
+      "path": "auth/service.py",
+      "hash": "md5",
+      "lines": 245,
+      "language": "python",
+      "imports": [{"from": "fastapi", "import": "Depends", "line": 3, "is_local": false}],
+      "exports": [{"name": "AuthService", "type": "class", "line": 15}],
+      "classes": [{"name": "AuthService", "bases": ["BaseService"], "line": 15}],
+      "functions": [{"name": "authenticate_user", "params": "username,password", "line": 88, "is_method": false}],
+      "decorators": [{"name": "router.post(/auth/login)", "line": 87, "is_route": true}],
+      "api_endpoints": [{"method": "POST", "path": "/auth/login", "line": 87}],
+      "data_models": [],
+      "extraction_confidence": "high"
+    }
+  ],
+  "module_summary": {
+    "total_files": 5,
+    "total_imports": 23,
+    "total_exports": 8,
+    "total_classes": 3,
+    "total_functions": 12,
+    "total_api_endpoints": 4,
+    "total_data_models": 1,
+    "external_deps": [{"package": "fastapi", "count": 5}]
+  }
+}
+```
+
+**项目级** (`.atool-docs/pre-scan/manifest.json`)：
+
+```json
+{
+  "version": "1.0",
+  "generated_at": "2026-01-01T00:00:00Z",
+  "total_modules": 10,
+  "scan_duration_seconds": 5,
+  "modules": [{"total_files": 37, "total_classes": 23, ...}]
+}
+```
+
+### 0.5.5 错误处理
+
+- 单文件提取失败时跳过（不影响其他文件）
+- 模块目录不存在时标记 warning 并跳过
+- `extraction_confidence: "low"` 标记通用提取器的结果（AI agent 需验证）
+- 整体失败时优雅降级：Phase 1 回退到全量 AI 提取
+
+## 性能目标
+
+| 项目规模 | 目标时间 | 对比 Phase 1 AI |
+|----------|----------|----------------|
+| 50 文件 | <2 秒 | ~30 秒 |
+| 150 文件 | <5 秒 | ~2-4 分钟 |
+| 500 文件 | <15 秒 | ~10+ 分钟 |
+
+## IDE 适配
+
+| IDE | 执行方式 |
+|-----|----------|
+| Claude | 纯 bash 执行 |
+| Cursor | 纯 bash 执行 |
+| Kiro | 纯 bash 执行 |
+
+所有 IDE 行为完全一致 — 纯 shell 命令，不涉及 AI。
+
+## 检查点
+
+写入 `analysis-state.json`：
+```json
+{
+  "phases": {
+    "phase0_5_prescan": "completed"
+  }
+}
+```
+
+恢复时检查：如果 `phase0_5_prescan != "completed"`，重新执行。
+
+## 与后续阶段的协作
+
+| 后续阶段 | 使用方式 |
+|----------|----------|
+| Phase 1 Inventory | 接收 pre-scan JSON，验证 confidence:low 文件，添加语义注释 |
+| Phase 2 Deep Analysis | 接收 pre-scan 摘要，跳过结构提取，专注深度分析 |
+| Phase 2a L4 Analysis | 使用函数行范围定向读取，使用 caller/callee 关系 |
+| Phase 4 Code Review | 使用 pre-computed 基线指标（长函数、嵌套深度等） |
+| L1 深度 | Phase 0.5 完全替代 Phase 1（0 AI agent） |