@dtt_siye/atool 1.1.0

package/skills/project-analyze/rules/devops.md

@@ -0,0 +1,443 @@
+# DevOps / Infrastructure 项目分析规则
+
+## 分析粒度
+
+按服务、环境和基础设施组件进行分析。
+
+```
+Infrastructure as Code (IaC)
+    ├── Docker（容器化）
+    │   ├── Dockerfile（镜像构建）
+    │   ├── docker-compose.yml（多服务编排）
+    │   └── .dockerignore（构建排除）
+    ├── Kubernetes（容器编排）
+    │   ├── Deployment / StatefulSet / DaemonSet
+    │   ├── Service / Ingress / Gateway
+    │   ├── ConfigMap / Secret / PVC
+    │   ├── Helm Chart（模板化部署）
+    │   └── Kustomize（overlay 变体）
+    ├── Terraform / OpenTofu（基础设施）
+    │   ├── resource / data / module
+    │   ├── provider / backend
+    │   └── variable / output / locals
+    └── CI/CD（自动化流水线）
+        ├── GitHub Actions / GitLab CI / Jenkins
+        ├── ArgoCD / Flux（GitOps）
+        └── Makefile / Taskfile（任务编排）
+```
+
+## 目录扫描策略
+
+### 1. 识别基础设施类型
+
+**信号文件检测：**
+
+| 类型 | 信号文件 | 说明 |
+|------|----------|------|
+| Docker | `Dockerfile`, `Dockerfile.*`, `docker-compose.yml`, `docker-compose.yaml`, `.dockerignore` | 容器化配置 |
+| Kubernetes | `k8s/`, `kubernetes/`, `manifests/`, `deploy/`, `kustomization.yaml`, `Chart.yaml`, `values.yaml` | K8s 部署配置 |
+| Terraform | `*.tf`, `*.tfvars`, `terraform.tfstate`, `.terraform.lock.hcl` | IaC 配置 |
+| Ansible | `playbook.yml`, `ansible.cfg`, `inventory/`, `roles/` | 配置管理 |
+| CI/CD | `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/`, `tekton/`, `.argo/` | 流水线配置 |
+| 监控 | `prometheus/`, `grafana/`, `alertmanager/`, `dashboards/`, `rules/*.yml` | 可观测性配置 |
+| 安全 | `vault/`, `policy/`, `cert-manager/`, `istio/` | 安全策略配置 |
+
+### 2. Docker 分析
+
+**扫描文件**: `Dockerfile`, `Dockerfile.*`, `docker-compose.yml`, `docker-compose.yaml`, `.dockerignore`
+
+**提取内容**:
+- 基础镜像及版本（FROM 行）
+- 多阶段构建结构（每个 FROM 为一个阶段）
+- 暴露端口（EXPOSE）
+- 环境变量（ENV）
+- 卷挂载（VOLUME）
+- 入口点（ENTRYPOINT / CMD）
+- 构建参数（ARG）
+- 健康检查（HEALTHCHECK）
+- 用户/权限（USER, RUN chown）
+- `.dockerignore` 排除规则
+
+**输出示例**:
+```
+### api-gateway（Dockerfile）
+- **路径**: `services/api-gateway/Dockerfile`
+- **基础镜像**: `node:20-alpine AS builder` → `nginx:alpine AS production`
+- **多阶段构建**:
+  | 阶段 | 基础镜像 | 用途 |
+  |------|----------|------|
+  | builder | node:20-alpine | 依赖安装 + 构建 |
+  | production | nginx:alpine | 运行时（Nginx 静态服务） |
+- **暴露端口**: 8080
+- **环境变量**: NODE_ENV=production, API_BASE_URL
+- **健康检查**: `curl -f http://localhost:8080/health || exit 1`
+```
+
+### 3. Docker Compose 分析
+
+**扫描文件**: `docker-compose.yml`, `docker-compose.yaml`, `docker-compose.*.yml`
+
+**提取内容**:
+- 服务列表（名称 + 镜像 + 构建上下文）
+- 服务间依赖（depends_on）
+- 网络配置（networks）
+- 卷挂载（volumes）
+- 环境变量（environment / env_file）
+- 端口映射（ports）
+- 健康检查（healthcheck）
+- 扩展策略（deploy.replicas / scale）
+- Compose 文件版本和 overlay 结构
+
+**输出示例**:
+```
+### Docker Compose 服务编排
+- **文件**: `docker-compose.yml` (version: '3.8')
+- **服务列表**:
+  | 服务名 | 镜像 | 端口 | 依赖 | 说明 |
+  |--------|------|------|------|------|
+  | api | node:20-alpine (build) | 3000:3000 | postgres, redis | API 服务 |
+  | worker | node:20-alpine (build) | - | postgres, redis | 后台任务处理 |
+  | postgres | postgres:16-alpine | 5432:5432 | - | 数据库 |
+  | redis | redis:7-alpine | 6379:6379 | - | 缓存 |
+- **网络**: app-network (bridge)
+- **卷**: postgres-data, redis-data
+```
+
+### 4. Kubernetes 分析
+
+**扫描文件**: `k8s/**/*.yaml`, `manifests/**/*.yaml`, `deploy/**/*.yaml`, `Chart.yaml`, `values.yaml`, `templates/**/*.yaml`
+
+**提取内容**:
+- 资源类型和数量（Deployment, Service, Ingress, ConfigMap, Secret, PVC, CronJob, Job, HPA）
+- 每个 Deployment 的镜像、副本数、资源限制、探针配置
+- Service 类型和端口映射（ClusterIP, NodePort, LoadBalancer）
+- Ingress 规则（主机、路径、TLS）
+- ConfigMap / Secret 数据结构（键名，不记录敏感值）
+- PVC 存储类和大小
+- Helm Chart 元数据（name, version, appVersion, dependencies）
+- Helm values 结构（关键配置项及默认值）
+- Kustomize overlay 结构（base + overlays/）
+
+**输出示例**:
+```
+### Kubernetes 部署配置
+#### Deployments
+| 名称 | 命名空间 | 镜像 | 副本 | 资源限制 |
+|------|----------|------|------|----------|
+| api-server | production | myapp/api:v1.2.3 | 3 | cpu: 500m, mem: 512Mi |
+| worker | production | myapp/worker:v1.2.3 | 2 | cpu: 250m, mem: 256Mi |
+
+#### Services
+| 名称 | 类型 | 端口 | 选择器 |
+|------|------|------|--------|
+| api-server-svc | ClusterIP | 8080:8080 | app=api-server |
+| api-server-ingress | LoadBalancer | 80:80, 443:443 | app=api-server |
+
+#### Ingress
+| 主机 | 路径 | 后端 | TLS |
+|------|------|------|-----|
+| api.example.com | / | api-server-svc:8080 | api-tls |
+
+#### ConfigMaps
+| 名称 | 键 |
+|------|-----|
+| api-config | DATABASE_URL, REDIS_URL, LOG_LEVEL |
+
+#### Helm Chart
+- **名称**: myapp-chart
+- **版本**: 0.3.0
+- **AppVersion**: 1.2.3
+- **依赖**: postgresql, redis
+```
+
+### 5. Terraform 分析
+
+**扫描文件**: `*.tf`, `*.tfvars`, `*.tf.json`
+
+**提取内容**:
+- Provider 列表及版本（aws, azurerm, google, kubernetes, helm 等）
+- Backend 配置（s3, gcs, http 等）
+- Resource 列表（类型 + 名称 + 关键参数）
+- Data source 列表（类型 + 名称）
+- Module 调用（源 + 版本 + 输入变量）
+- Variable 定义（名称 + 类型 + 默认值 + 描述）
+- Output 定义（名称 + 值 + 描述）
+- Locals 定义（名称 + 值）
+- 状态文件引用（remote state data source）
+
+**输出示例**:
+```
+### Terraform 基础设施
+#### Providers
+| Provider | 版本 | 源 |
+|----------|------|-----|
+| aws | ~> 5.0 | hashicorp/aws |
+| kubernetes | ~> 2.23 | hashicorp/kubernetes |
+
+#### Resources（按类型分组）
+**EC2**:
+| 名称 | 实例类型 | 关键参数 |
+|------|----------|----------|
+| aws_instance.api | t3.medium | ami, vpc_security_group_ids, subnet_id |
+
+**RDS**:
+| 名称 | 引擎 | 存储大小 |
+|------|------|----------|
+| aws_db_instance.main | postgres 16 | 100 GB |
+
+#### Modules
+| 名称 | 源 | 版本 | 说明 |
+|------|-----|------|------|
+| vpc | terraform-aws-modules/vpc/aws | 5.1.0 | VPC 网络配置 |
+| eks | terraform-aws-modules/eks/aws | 19.15.0 | EKS 集群 |
+
+#### Variables
+| 名称 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| environment | string | "production" | 部署环境 |
+| instance_type | string | "t3.medium" | EC2 实例类型 |
+```
+
+### 6. CI/CD 流水线分析
+
+**扫描文件**: `.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/config.yml`, `tekton/*.yaml`
+
+**GitHub Actions 提取内容**:
+- Workflow 名称和触发条件（push, pull_request, schedule, workflow_dispatch）
+- 环境矩阵（matrix: os / node-version / etc.）
+- Job 列表（名称 + 运行器 + 依赖关系）
+- 每个 Job 的 Steps（动作名称 + 版本 + 关键参数）
+- Secret 使用列表（名称，不记录值）
+- Artifact 上传/下载
+- 缓存策略（actions/cache）
+- 环境部署（environment: production / staging）
+
+**GitLab CI 提取内容**:
+- Stage 列表和顺序
+- Job 列表（stage + image + script + rules/only/except）
+- 变量定义（variables）
+- 缓存配置（cache）
+- Artifact 定义
+- 触发规则（rules / only / except）
+
+**输出示例**:
+```
+### GitHub Actions CI/CD
+#### Workflow: ci.yml
+- **触发条件**: push (main, develop), pull_request
+- **Jobs**:
+  | Job | 运行器 | 依赖 | 超时 | 说明 |
+  |-----|--------|------|------|------|
+  | lint | ubuntu-latest | - | 10m | 代码风格检查 |
+  | test | ubuntu-latest | lint | 20m | 单元测试 + 覆盖率 |
+  | build | ubuntu-latest | test | 15m | Docker 镜像构建 |
+  | deploy-staging | ubuntu-latest | build | 10m | 部署到 staging |
+
+#### Workflow: deploy.yml
+- **触发条件**: workflow_dispatch (inputs: environment)
+- **环境**: production (需要审批), staging
+- **Secrets**: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, KUBECONFIG
+```
+
+### 7. 监控与可观测性分析
+
+**扫描文件**: `prometheus/*.yml`, `grafana/**/*.json`, `alertmanager/*.yml`, `dashboards/**/*.json`
+
+**提取内容**:
+- Prometheus scrape 配置（targets, interval, labels）
+- 自定义指标规则（recording rules）
+- 告警规则（alert name, expr, severity, annotations）
+- Grafana Dashboard 列表（标题 + 数据源 + 面板数）
+- Alertmanager 路由配置（receiver, group_by, inhibit_rules）
+- 日志聚合配置（如 ELK / Loki 的相关配置文件）
+
+**输出示例**:
+```
+### 监控配置
+#### Prometheus
+- **Scrape 配置**:
+  | Job | Target | 间隔 | 标签 |
+  |-----|--------|------|------|
+  | api-server | http://api:8080/metrics | 15s | app=api, env=prod |
+
+#### 告警规则
+| 告警名 | 表达式 | 严重级别 | 说明 |
+|--------|--------|----------|------|
+| HighErrorRate | rate(http_errors_total[5m]) > 0.05 | warning | 错误率 > 5% |
+| PodCrashLooping | kube_pod_container_status_restarts_total > 5 | critical | Pod 重启循环 |
+
+#### Grafana Dashboards
+| 名称 | 数据源 | 面板数 |
+|------|--------|--------|
+| API Overview | Prometheus | 12 |
+| System Resources | Prometheus | 8 |
+```
+
+## 模块发现规则
+
+- **Docker**: 每个 `Dockerfile` 或 `Dockerfile.*` 为一个分析单元
+- **Compose**: 每个 compose 文件为一个分析单元，按 services 拆分子任务
+- **Kubernetes**: 按 namespace / application 分组，每组内的资源类型为一个子任务
+- **Helm**: Chart 为一个分析单元，`values.yaml` 和 `templates/` 分别分析
+- **Terraform**: 每个 `*.tf` 文件为一个分析单元，按 resource type 分组
+- **Ansible**: 每个 playbook 为一个分析单元
+- **CI/CD**: 每个 workflow/job 文件为一个分析单元
+- **监控**: 按工具（Prometheus / Grafana / Alertmanager）分组
+
+## 依赖分析
+
+从配置文件提取：
+- Docker 基础镜像及版本（FROM 行，含 digest）
+- K8s 部署的镜像标签（image: registry/...:tag）
+- Terraform provider 及版本约束
+- Terraform module 源和版本
+- CI/CD 使用的 action / plugin 及版本
+- Helm Chart 依赖（Chart.yaml dependencies）
+- 服务间依赖（compose depends_on, K8s init containers, ArgoCD sync waves）
+- Makefile / Taskfile 中的 target 依赖关系
+
+## 环境管理分析
+
+**扫描文件**: `envs/`, `environments/`, `*.env.example`, `terraform.tfvars`, `values-*.yaml`, `overlays/*/`
+
+**提取内容**:
+- 环境列表（development, staging, production）
+- 每个环境的差异配置（副本数、资源限制、域名、数据库实例等）
+- 环境变量管理方式（ConfigMap / Secret / .env / Vault）
+- 配置覆盖策略（Kustomize overlay / Helm values / Terraform workspaces）
+
+## 安全配置分析
+
+**扫描文件**: `network-policy*.yaml`, `rbac*.yaml`, `pod-security*.yaml`, `vault/*.hcl`, `cert-manager/*.yaml`
+
+**提取内容**:
+- RBAC 角色（Role / ClusterRole + 绑定关系）
+- Network Policy（入站/出站规则）
+- Pod 安全标准（PSS / PSP）
+- Secret 管理方式（K8s Secret / Vault / External Secrets Operator）
+- TLS 配置（证书来源、过期策略）
+
+## 输出模板
+
+### README.md
+
+```markdown
+# {项目名称}
+
+## 项目概述
+基础设施项目描述、管理范围、覆盖的环境
+
+## 架构总览
+### 基础设施拓扑图（ASCII art）
+展示 VPC → K8s Cluster → Services → Pods 的完整拓扑
+
+### 环境架构图
+development / staging / production 三环境的差异
+
+## 目录结构
+带注释的目录树
+
+## 服务清单
+| 服务名 | 类型 | 端口 | 健康检查 | 说明 |
+|--------|------|------|----------|------|
+
+## 环境变量
+| 变量名 | 说明 | 示例值 | 必需 |
+|--------|------|--------|------|
+
+## 部署流程
+从代码提交到生产部署的完整流程图
+
+## 监控与告警
+告警规则摘要 + Dashboard 链接
+
+## 常用运维命令
+部署、回滚、扩缩容、日志查看等命令
+```
+
+### COMPONENT.md
+
+```markdown
+# 基础设施组件文档
+
+## Docker 服务
+### {服务名}
+- **镜像**: ...
+- **端口映射**: ...
+- **环境变量**: ...
+- **健康检查**: ...
+- **构建参数**: ...
+
+## Kubernetes 资源
+### Deployments
+### Services
+### Ingress
+### ConfigMaps / Secrets
+
+## Terraform 资源
+### {资源类型}
+| 名称 | 关键参数 | 依赖 |
+|------|----------|------|
+
+## CI/CD Pipelines
+### {流水线名}
+- **触发条件**: ...
+- **阶段**: ...
+- **Secret 使用**: ...
+
+## 监控配置
+### Prometheus
+### 告警规则
+### Grafana Dashboards
+```
+
+### UI_STYLE.md
+
+对于 DevOps 项目，此文件记录运维可视化规范：
+
+```markdown
+# 运维可视化规范
+
+## 监控 Dashboard 规范
+- 图表类型选择标准
+- 颜色编码（健康/警告/危险）
+- 时间范围选择器默认值
+
+## 告警通知规范
+- 告警级别与通知渠道映射
+- 告警消息格式模板
+- 告警分组和抑制规则
+
+## 日志规范
+- 日志级别使用标准
+- 结构化日志格式
+- 日志保留策略
+```
+
+## 模块边界识别
+
+以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
+
+| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
+|----|----------|-------------|---------------------|
+| Manifests 层 | `manifests/` | 每个子目录 | 目录名 kebab-case |
+| Terraform 模块 | `terraform/modules/` | 每个子目录 | 目录名 kebab-case |
+| CI/CD 层 | `.github/workflows/` | 每个文件 | 文件名去后缀 kebab-case |
+| Helm Charts | `helm/` | 每个 chart | chart 名 kebab-case |
+| 脚本层 | `scripts/` | 每个子目录或文件 | 名称 kebab-case |
+
+**不视为独立模块的情况**：
+- 单文件入口（如 `Makefile`, `docker-compose.yml`）
+- 纯配置文件（`.env.example`, `*.tfvars.example`）
+- Secret 文件（只记录键名，不记录值）
+- `.tf.json` 与 `*.tf` 合并分析
+
+## Token 管理
+
+- 大型 YAML 文件（K8s manifest、Helm values）单独分析
+- 每个子任务分析 <=10 个文件
+- `values.yaml`（Helm）和 `*.tfvars`（Terraform）单独作为一个子任务
+- 生成的清单文件（`helm template` 输出、`terraform plan` 输出）跳过
+- `terraform.tfstate` 不分析（含敏感信息，仅记录 backend 类型）
+- Secret 文件只记录键名，不记录值
+- `.tf.json` 与 `*.tf` 合并分析

package/skills/project-analyze/rules/generic.md

@@ -0,0 +1,243 @@
+# 通用项目分析规则
+
+当无法识别具体技术栈或项目结构不遵循常见框架模式时使用此规则。作为所有规则文件的兜底。
+
+## 分析粒度
+
+按目录结构、文件类型和模块边界进行通用分析。
+
+```
+项目根目录
+    ├── 配置文件（package.json, Makefile, Cargo.toml 等）
+    ├── src/ 或 lib/（源码目录）
+    │   ├── 模块 A
+    │   ├── 模块 B
+    │   └── 公共代码
+    ├── tests/ 或 test/（测试目录）
+    ├── docs/（文档目录）
+    └── scripts/（脚本目录）
+```
+
+## 目录扫描策略
+
+### 1. 识别项目类型
+
+**信号文件检测（按优先级）：**
+- `package.json` → Node.js / JavaScript 项目
+- `pyproject.toml` / `requirements.txt` → Python 项目
+- `go.mod` → Go 项目
+- `Cargo.toml` → Rust 项目
+- `pom.xml` / `build.gradle` → Java 项目
+- `Gemfile` → Ruby 项目
+- `composer.json` → PHP 项目
+- `Makefile` / `CMakeLists.txt` → C/C++ 项目
+- `build.gradle.kts` → Kotlin 项目
+- `pubspec.yaml` → Dart/Flutter 项目
+- 无信号文件 → 按目录结构推断
+
+### 2. 排除非源码目录
+
+```
+node_modules/     vendor/       build/        dist/
+.git/             __pycache__/  .cache/        target/
+.idea/            .vscode/      .settings/    .DS_Store
+.venv/            venv/         env/           oh_modules/
+*.egg-info/       .eggs/        coverage/      .next/
+out/              bin/          obj/           .gradle/
+```
+
+### 3. 按层扫描路径
+
+- **入口**: `src/main.*`, `src/index.*`, `index.*`, `main.*`, `app.*`
+- **公共代码**: `src/common/`, `src/shared/`, `src/core/`, `src/base/`
+- **业务模块**: `src/modules/`, `src/features/`, `src/domain/`
+- **工具**: `src/utils/`, `src/helpers/`, `src/lib/`, `src/internal/`
+- **类型**: `src/types/`, `src/interfaces/`, `src/schemas/`
+- **配置**: `src/config/`, `config/`, `conf/`
+- **测试**: `tests/`, `test/`, `__tests__/`, `src/test/`
+
+## 各层提取规则
+
+### 层 1: 入口分析
+
+**扫描文件**: 项目根目录下的入口文件
+
+**提取内容**:
+- 入口文件路径和语言
+- 导入的模块列表
+- 初始化逻辑摘要
+- 暴露的公开 API
+
+**输出示例**:
+```
+### 入口文件
+- **文件**: `src/index.ts`
+- **语言**: TypeScript
+- **导入模块**: ./config, ./core/App, ./routes
+- **公开 API**:
+  | 名称 | 类型 | 说明 |
+  |------|------|------|
+  | createApp | (config: AppConfig) => App | 创建应用实例 |
+  | version | string | 版本号 |
+```
+
+### 层 2: 模块发现
+
+**扫描规则**:
+- 递归扫描源码目录（最大深度 3 层）
+- 每个包含 3+ 源码文件的目录视为一个功能模块
+- `src/` 下的每个一级子目录为一个模块
+- 单文件项目作为一个整体模块
+
+**输出示例**:
+```
+### 模块列表
+| 模块 | 路径 | 文件数 | 主要语言 | 职责描述 |
+|------|------|--------|----------|----------|
+| core | src/core/ | 12 | TypeScript | 核心逻辑和框架 |
+| utils | src/utils/ | 8 | TypeScript | 工具函数集合 |
+| api | src/api/ | 6 | TypeScript | 外部 API 封装 |
+| models | src/models/ | 4 | TypeScript | 数据模型定义 |
+```
+
+### 层 3: 核心类/函数分析
+
+**扫描文件**: 每个模块内的主要源码文件
+
+**提取内容**:
+- 类/函数/接口名称
+- 签名（参数 + 返回类型）
+- 职责描述
+- 依赖的其他模块
+
+**输出示例**:
+```
+### 核心导出
+- **文件**: `src/core/engine.ts`
+- **导出**:
+  | 名称 | 类型 | 签名 | 说明 |
+  |------|------|------|------|
+  | Engine | Class | constructor(config: Config) | 核心引擎类 |
+  | process | Method | (input: Data): Promise<Result> | 处理数据 |
+  | validate | Function | (data: unknown): data is ValidData | 数据校验 |
+- **依赖**: `src/config`, `src/utils/logger`, `src/models`
+```
+
+### 层 4: 依赖分析
+
+**扫描文件**: 各种包管理器的依赖文件
+
+**提取内容**:
+- 依赖管理器类型和版本
+- 运行时依赖列表（名称 + 版本）
+- 开发依赖列表
+- 对等依赖（peerDependencies）
+
+**输出示例**:
+```
+### 依赖信息
+- **管理器**: npm (package.json)
+- **运行时依赖**:
+  | 包名 | 版本 | 用途 |
+  |------|------|------|
+  | express | 4.18.2 | Web 框架 |
+  | zod | 3.22.4 | 数据验证 |
+  | dayjs | 1.11.9 | 日期处理 |
+```
+
+### 层 5: 构建与配置分析
+
+**扫描文件**: 配置文件、构建脚本
+
+**提取内容**:
+- 构建命令（build、test、lint、dev）
+- 环境变量配置
+- 关键配置项
+
+**输出示例**:
+```
+### 构建配置
+- **构建工具**: TypeScript + tsx
+- **脚本命令**:
+  | 命令 | 执行内容 | 说明 |
+  |------|----------|------|
+  | npm run dev | tsx watch src/index.ts | 开发模式 |
+  | npm run build | tsc && node build.js | 生产构建 |
+  | npm run test | vitest run | 运行测试 |
+  | npm run lint | eslint src/ --ext .ts | 代码检查 |
+```
+
+## 输出模板
+
+### README.md 章节结构
+
+```markdown
+# {项目名}
+
+## 项目概述
+项目功能描述（从 README 或配置文件 description 提取）
+
+## 技术栈
+| 技术 | 版本 | 用途 |
+|------|------|------|
+
+## 架构设计
+### 架构图（ASCII）
+展示模块关系的 ASCII 图
+
+### 目录结构
+带注释的文件树
+
+## 模块说明
+每个模块的职责、核心 API、依赖关系
+
+## 构建 & 运行
+构建命令、环境变量、运行方式
+
+## 开发指南
+如何修改/扩展项目
+```
+
+### COMPONENT.md 章节结构
+
+```markdown
+# 模块文档
+
+## 模块索引
+按功能分组的模块列表
+
+## 各模块详情
+### {模块名}
+- 路径 + 语言
+- 公开 API 表格
+- 依赖关系
+- 使用示例
+```
+
+## 模块边界识别
+
+以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
+
+| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
+|----|----------|-------------|---------------------|
+| 源码层 | `src/` 一级子目录 | 3+ 文件的子目录 | 目录名 kebab-case |
+| API/服务层 | `src/api/`, `src/services/` | 每个子目录 | 目录名 kebab-case |
+| 状态管理层 | `src/store/`, `src/state/` | 每个子目录 | 目录名 kebab-case |
+| 组件层 | `src/components/` | 3+ 文件的子目录 | 目录名 kebab-case |
+| 自动推断 | 其他目录 | 3+ 源码文件 | 目录名 kebab-case |
+
+**不视为独立模块的情况**：
+- 单文件入口（如 `main.ts`, `index.js`, `app.py`）
+- 纯导出桶文件（仅有 re-export）
+- 工具函数目录（`utils/`, `helpers/`, `lib/`）— 合并为一个模块
+- 生成文件（`*.generated.*`, `*.min.*`）跳过
+
+## Token 管理
+
+- 大目录（>20 文件）拆分为子任务
+- 每个子任务分析 ≤10 文件
+- 二进制文件、图片、压缩包跳过
+- 超大文件（>100KB）跳过内容分析，只记录文件名和大小
+- 生成文件（`*.generated.*`, `*.min.*`）跳过
+- 测试文件单独分组分析
+- 配置文件（JSON/YAML/TOML）单独分析