@dtt_siye/atool 1.1.0

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

@@ -0,0 +1,390 @@
+# Web 项目分析规则
+
+通用 Web 项目分析规则，适用于 React、Vue、Next.js、Svelte 等前端框架。如检测到具体框架（Vue 3 / React），会同时加载 `rules/web-vue.md` 或 `rules/web-react.md` 作为补充。
+
+## 分析粒度
+
+按页面、组件目录和功能模块进行分析，分层结构为：
+
+```
+用户界面 (UI)
+    ↓
+页面/路由 (Pages/Router)
+    ↓
+组件 (Components)
+    ↓
+Hooks/Composables (逻辑复用)
+    ↓
+状态管理 (Store/Context)
+    ↓
+服务/API (Services)
+    ↓
+工具/类型 (Utils/Types)
+```
+
+## 目录扫描策略
+
+### 1. 识别框架类型
+
+**信号文件检测：**
+- Next.js: `app/` 或 `pages/` 目录 + `next.config.js` / `next.config.mjs`
+- React SPA: `src/App.tsx` + `react-router` 依赖
+- Vue/Nuxt: `src/views/` + `vue-router` 依赖，或 Nuxt 的 `pages/` 目录
+- SvelteKit: `src/routes/` + `svelte.config.js`
+- Vite 项目: `vite.config.ts` / `vite.config.js`
+
+**微前端检测：**
+- qiankun: `main.js` 中包含 `registerMicroApps`，子应用有 `vue.config.js` 中 `devServer.headers`
+- Module Federation: `webpack.config.js` 中包含 `ModuleFederationPlugin`
+- single-spa: `import-map.json` 或 `single-spa` 依赖
+
+**Monorepo 检测：**
+- `pnpm-workspace.yaml` → pnpm workspace
+- `lerna.json` → Lerna monorepo
+- `nx.json` → Nx monorepo
+- `package.json` 中 `workspaces` 字段
+
+### 2. 依赖提取
+
+从 `package.json` 提取关键依赖并分类：
+
+| 类别 | 依赖示例 |
+|------|----------|
+| 框架 | react, vue, next, nuxt, svelte |
+| UI 库 | element-plus, antd, vuetify, shadcn/ui, tailwindcss |
+| 状态管理 | zustand, redux-toolkit, pinia, vuex, mobx |
+| 路由 | react-router, vue-router, @tanstack/router |
+| 请求库 | axios, fetch, swr, @tanstack/react-query |
+| 构建工具 | vite, webpack, turbopack, rollup |
+| CSS 方案 | tailwindcss, sass, styled-components, css-modules |
+| 测试 | vitest, jest, cypress, playwright |
+| 代码质量 | eslint, prettier, typescript, husky |
+
+### 3. 按层扫描路径
+
+- **页面层**: `src/pages/`, `app/`, `src/views/`, `src/routes/`
+- **组件层**: `src/components/`, `src/ui/`, `src/shared/`
+- **逻辑层**: `src/hooks/`, `src/composables/`, `src/directives/`
+- **状态层**: `src/stores/`, `src/store/`, `src/context/`, `src/redux/`
+- **服务层**: `src/services/`, `src/api/`, `src/request/`, `src/http/`
+- **工具层**: `src/utils/`, `src/lib/`, `src/helpers/`, `src/constants/`
+- **类型层**: `src/types/`, `src/interfaces/`, `src/schemas/`
+- **样式层**: `src/styles/`, `src/assets/css/`, `src/themes/`
+- **国际化**: `src/locales/`, `src/i18n/`, `src/lang/`
+- **权限**: `src/permission/`, `src/auth/`, `src/guards/`
+
+### 4. 模块发现规则
+
+- Next.js App Router: `app/` 下的每个一级目录（排除 `api/`, `layout.tsx`）为一个页面模块
+- Next.js Pages Router: `pages/` 下的每个文件/目录为一个路由模块
+- React SPA: `src/pages/` 下的每个文件为一个路由模块
+- Vue 项目: `src/views/` 下的每个子目录为一个页面模块
+- Feature-based 结构: `src/features/{feature}/` 下的子目录
+- 组件目录按子目录分组（如 `components/ui/`, `components/business/`）
+
+## 各层提取规则
+
+### 层 1: 路由/入口层
+
+**扫描文件**: `src/router/index.ts`, `src/routes.ts`, `app/**/page.tsx`, `app/**/layout.tsx`
+
+**提取内容**:
+- 路由配置（路径 + 对应组件 + 路由 meta）
+- 嵌套路由结构
+- 路由守卫（权限检查、登录拦截）
+- 布局组件层级
+
+**输出示例**:
+```
+### 路由结构
+
+/ (Layout: DefaultLayout)
+├── /login                          → LoginPage         [公开]
+├── /dashboard                      → DashboardPage     [需认证]
+├── /system
+│   ├── /system/user                → UserPage          [admin]
+│   ├── /system/role                → RolePage          [admin]
+│   └── /system/menu                → MenuPage          [admin]
+└── /404                            → NotFoundPage      [公开]
+
+### 路由守卫链路
+router.beforeEach → 检查 token → 无 token → 跳转 /login
+                                  → 有 token → 检查权限 → 放行 / 403
+```
+
+### 层 2: 状态管理层
+
+**扫描文件**: `src/stores/**/*.ts`, `src/store/**/*.ts`, `src/context/**/*.tsx`
+
+**提取内容**:
+- Store ID / 名称
+- State 接口（所有字段的类型和初始值）
+- Getters / 计算属性
+- Actions（参数 + 调用的 API + 修改的 state）
+- 跨 Store 依赖
+- 持久化配置
+
+**输出示例**:
+```
+### useUserStore
+- **文件**: `src/stores/modules/user.ts`
+- **State 接口**:
+  | 字段 | 类型 | 初始值 | 说明 |
+  |------|------|--------|------|
+  | token | string | '' | JWT token |
+  | userInfo | UserInfo \| null | null | 当前用户信息 |
+  | roles | string[] | [] | 角色列表 |
+- **Getters**:
+  | 名称 | 返回类型 | 说明 |
+  |------|----------|------|
+  | isAdmin | boolean | 是否管理员 |
+  | avatar | string | 用户头像 URL |
+- **Actions**:
+  | Action | 参数 | 调用的 API | 说明 |
+  |--------|------|-----------|------|
+  | login | (data: LoginForm) | authApi.login() | 登录并存储 token |
+  | getUserInfo | () | userApi.getInfo() | 获取用户信息 |
+  | logout | () | - | 清空状态并跳转 |
+- **跨 Store 依赖**: usePermissionStore（登录后同步权限）
+- **持久化**: localStorage, key: 'user-store'
+```
+
+### 层 3: 服务/API 层
+
+**扫描文件**: `src/api/**/*.ts`, `src/services/**/*.ts`, `src/request/**/*.ts`
+
+**提取内容**:
+- API 基础配置（baseURL、超时、拦截器）
+- API 函数列表（路径 + 方法 + 参数 + 返回类型）
+- Token 注入方式
+- 错误处理策略
+- 请求/响应拦截器逻辑
+
+**输出示例**:
+```
+### API 基础配置
+- **实例文件**: `src/utils/request.ts`
+- **baseURL**: `/api/v1`
+- **超时**: 15000ms
+- **Token 注入**: 请求拦截器从 localStorage 读取 token，添加 `Authorization: Bearer {token}` header
+- **错误处理**: 401 → 跳转登录；403 → 提示无权限；500 → 提示服务器错误
+
+### 用户模块 API
+| 函数 | 方法 | 路径 | 参数 | 返回类型 |
+|------|------|------|------|----------|
+| getUserPage | GET | /system/user/list | { pageNum, pageSize, ...query } | PageResult<UserVO> |
+| getUserDetail | GET | /system/user/:id | { id: string } | R<UserVO> |
+| createUser | POST | /system/user | CreateUserDTO | R<void> |
+| updateUser | PUT | /system/user | UpdateUserDTO | R<void> |
+| deleteUser | DELETE | /system/user/:id | { id: string } | R<void> |
+```
+
+### 层 4: 组件层
+
+**扫描文件**: `src/components/**/*.vue`, `src/components/**/*.tsx`
+
+**提取内容**:
+- 组件名称 + 路径
+- Props/参数定义（类型 + 是否必填 + 默认值）
+- Events/Emits（事件名 + 载荷类型）
+- Slots（插槽名 + 用途）
+- 依赖的 Store / API / 其他组件
+- 组件分类（基础组件 / 业务组件 / 页面组件）
+
+**输出示例**:
+```
+### UserList（业务组件）
+- **路径**: `src/views/system/user/index.vue`
+- **Props**:
+  | Prop | Type | Required | Default | Description |
+  |------|------|----------|---------|-------------|
+  | loading | boolean | No | false | 加载状态 |
+- **Emits**:
+  | Event | Payload | Description |
+  |-------|---------|-------------|
+  | refresh | () => void | 刷新列表 |
+  | edit | (row: UserVO) => void | 编辑用户 |
+- **使用的 Store**: useUserStore
+- **使用的 API**: getUserPage(), deleteUser()
+- **依赖组件**: UserForm, DictTag, Pagination
+```
+
+### 层 5: Hooks/Composables 层
+
+**扫描文件**: `src/hooks/**/*.ts`, `src/composables/**/*.ts`
+
+**提取内容**:
+- Hook 名称 + 路径
+- 参数签名
+- 返回值签名
+- 内部使用的 API / Store
+- 副作用说明
+
+**输出示例**:
+```
+### useTable
+- **路径**: `src/hooks/useTable.ts`
+- **签名**: `useTable<T>(fetchFn: (params) => Promise<PageResult<T>>, initialParams?)`
+- **返回值**:
+  | 字段 | 类型 | 说明 |
+  |------|------|------|
+  | tableData | Ref<T[]> | 表格数据 |
+  | loading | Ref<boolean> | 加载状态 |
+  | pagination | Reactive<PageParams> | 分页参数 |
+  | search | (params?) => void | 搜索方法 |
+  | refresh | () => void | 刷新当前页 |
+```
+
+### 层 6: 权限/认证层
+
+**扫描文件**: `src/permission/**/*.ts`, `src/auth/**/*.ts`, `src/directives/**/*.ts`
+
+**提取内容**:
+- 认证流程（登录 → token 存储 → token 刷新）
+- 权限模型（RBAC / ABAC）
+- 权限指令（如 `v-permission`）
+- 路由守卫逻辑
+
+**输出示例**:
+```
+### 认证流程
+用户登录 → POST /auth/login → 获取 token + refreshToken
+  → 存储 localStorage → 设置 Axios header
+  → 请求 401 → 使用 refreshToken 刷新 → 刷新失败 → 跳转登录页
+
+### 权限模型
+RBAC（基于角色的访问控制）
+- 用户 → 角色 → 菜单/按钮权限
+- 权限存储在 usePermissionStore.permissions: string[]（如 ['system:user:add']）
+- 指令 v-permission="['system:user:add']" 控制按钮显示
+```
+
+### 层 7: 国际化层
+
+**扫描文件**: `src/locales/**/*.ts`, `src/i18n/**/*.json`
+
+**提取内容**:
+- 支持的语言列表
+- i18n 框架（vue-i18n / react-i18next / next-intl）
+- 语言切换机制
+- 翻译文件结构
+
+### 层 8: 样式/设计系统层
+
+**扫描文件**: `src/styles/**`, `src/assets/css/**`, `tailwind.config.*`, `theme.ts`
+
+**提取内容**:
+- CSS 变量定义（`:root` / `.dark`）
+- SCSS 变量（`$color-primary`）
+- Tailwind 配置（`theme.extend`）
+- UI 库主题定制
+- 暗色模式实现方式
+- 响应式断点
+
+**输出示例**:
+```
+### 颜色系统（从 styles/variables.scss 提取）
+| 变量名 | 值 | 用途 |
+|--------|------|------|
+| --el-color-primary | #00a3e0 | 主色调 |
+| --el-color-primary-light-3 | #33b7e9 | 主色调浅色 |
+| --el-color-success | #67c23a | 成功状态 |
+| --el-color-warning | #e6a23c | 警告状态 |
+| --el-color-danger | #f56c6c | 危险状态 |
+
+### 暗色模式
+通过 html.dark class 切换，CSS 变量在 `styles/dark.scss` 中覆盖
+
+### 响应式断点
+| 名称 | 宽度 | 用途 |
+|------|------|------|
+| sm | ≥640px | 手机横屏 |
+| md | ≥768px | 平板 |
+| lg | ≥1024px | 桌面 |
+| xl | ≥1280px | 大屏 |
+```
+
+## 输出模板
+
+### README.md 章节结构
+
+```markdown
+# {项目名}
+
+## 项目概述
+业务描述 + 项目目标
+
+## 技术栈
+| 技术 | 版本 | 用途 |
+|------|------|------|
+
+## 架构设计
+### 架构图（ASCII）
+### 数据流图
+用户操作 → 事件处理 → Store → API → 响应 → UI 更新
+
+## 目录结构
+带注释的文件树
+
+## 路由结构
+路由树 + 权限标注
+
+## 状态管理
+Store 关系图 + 核心 Store 说明
+
+## API 接口
+按模块分组的 API 端点表
+
+## 认证与权限
+登录流程 + 权限模型
+
+## 构建 & 部署
+构建命令 + 环境变量 + 部署方式
+
+## 开发指南
+新增页面/组件/API 的步骤
+```
+
+### COMPONENT.md 章节结构
+
+```markdown
+# 组件文档
+
+## 基础组件
+项目内封装的通用组件（不含第三方 UI 库）
+
+## 业务组件
+按功能模块分组的业务组件
+
+## Hooks / Composables
+可复用的逻辑 Hook
+
+## 跨模块依赖关系
+模块间调用关系的 ASCII 图
+```
+
+## 模块边界识别
+
+以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
+
+| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
+|----|----------|-------------|---------------------|
+| 页面/视图层 | `src/views/`, `src/pages/` | 每个子目录 | 目录名 kebab-case |
+| API/服务层 | `src/api/`, `src/services/` | 每个子目录 | 目录名 kebab-case |
+| 状态管理层 | `src/store/modules/`, `src/stores/` | 每个子目录 | 目录名 kebab-case |
+| 组件层 | `src/components/{name}/` | 3+ 文件的子目录 | 目录名 kebab-case |
+| Hooks 层 | `src/hooks/` | 每个文件 | 文件名去后缀 kebab-case |
+
+**不视为独立模块的情况**：
+- 单文件入口（如 `main.ts`, `App.vue`, `index.ts`）
+- 纯导出桶文件（`index.ts` 仅有 re-export）
+- 工具函数目录（`utils/`, `helpers/`）— 合并为一个模块
+
+## Token 管理
+
+- 大组件目录（>15 文件）拆分为子任务
+- 每个子任务分析 ≤10 文件
+- `package.json` 分析单独一个子任务
+- 样式相关文件（CSS/Theme）单独一个子任务
+- 微前端项目：每个子应用作为独立分析单元
+- Monorepo 项目：每个 workspace 子包作为独立分析单元

package/skills/project-query/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: project-query
+description: 在需要查询项目分析结果时使用 — 支持节点查找、调用链追踪、影响分析、数据血缘、邻域查询、聚合统计，支持 G1-G5 五级粒度缩放。Use when querying analysis results — supports node lookup, call chain tracing, impact analysis, data lineage, neighborhood queries, aggregate statistics with G1-G5 granularity zooming.
+version: 0.1.0
+category: quality
+---
+
+# Project Query — 项目分析结果查询
+
+## 概述
+
+本 skill 提供对已完成 `project-analyze` 分析的项目进行交互式查询。基于 `.atool-docs/knowledge-graph.json` 和 `.atool-docs/multi-dimensional-analysis.json`，支持 6 类查询和 5 级粒度缩放。
+
+## 前置条件
+
+- 项目已通过 `/project-analyze` 完成分析
+- 存在 `.atool-docs/knowledge-graph.json`（v4.0+ 或 v5.0）
+- 如果需要数据流和调用链查询，需要 L2+ 深度的分析结果
+
+## 查询类别
+
+### 1. 节点查找 (Node Lookup)
+
+查找特定类型的节点。
+
+```
+/find all functions named createUser
+/find all classes in auth module
+/find all API endpoints
+/find modules with highest coupling
+```
+
+**执行步骤**：
+1. 读取 `knowledge-graph.json` 的 `nodes` 数组
+2. 按 `type` 和 `label` 过滤（支持子串匹配）
+3. 输出匹配节点的列表（ID、名称、路径、重要度）
+4. 如果结果 > 20 个，按 importance 降序排列，仅展示 top 20
+
+### 2. 路径查询 (Path Query)
+
+查找两个节点之间的调用路径。
+
+```
+/show call path from UserController.createUser to UserRepository.save
+/show dependency path from module-a to module-b
+```
+
+**执行步骤**：
+1. 在 knowledge-graph 中定位 source 和 target 节点
+2. 根据 edge 类型选择子图：
+   - `call path` → `calls` + `calls_async` 边
+   - `dependency path` → `depends_on` 边
+3. 执行 BFS 从 source 到 target
+4. 输出路径（每步包含：节点名称、边类型、行号）
+5. 生成 Mermaid `graph LR` 图
+6. 如果有多条路径，展示所有（最多 5 条）
+
+### 3. 影响分析 (Impact Analysis)
+
+分析修改某个节点后的影响范围。
+
+```
+/what changes if I modify User entity
+/impact of changing AuthService
+```
+
+**执行步骤**：
+1. 定位目标节点 X
+2. 查找所有反向边（其他节点 → X）：`depends_on`, `calls`, `reads_from`, `reads_state`, `implements`, `extends`
+3. 对每个依赖节点 D，递归查找 D 的依赖者（最多 3 层）
+4. 计算风险评分：
+   - `risk(X) = Σ importance(D) × weight(D→X)` 对所有直接依赖者 D
+   - risk > 0.7 = **HIGH**（红色标记）
+   - 0.3-0.7 = **MEDIUM**（橙色标记）
+   - < 0.3 = **LOW**（绿色标记）
+5. 统计受影响的：模块数、函数数、API 端点数、数据实体数
+6. 生成影响范围 Mermaid 图（G1 视角 = 模块级，G3 视角 = 函数级）
+7. 输出风险摘要 + 建议的测试范围
+
+### 4. 数据血缘 (Data Lineage)
+
+追踪数据的来源和去向。
+
+```
+/trace data lineage of Order entity
+/where does userData come from and where does it flow
+```
+
+**执行步骤**：
+1. 定位数据实体节点 D
+2. **反向追踪**（来源）：沿 `writes_to`, `writes_state`, `transforms` 边反向 BFS
+   - 找到所有写入 D 的函数/服务
+   - 继续追踪这些函数的数据来源
+   - 直到找到外部输入（API、用户输入、定时任务）
+3. **正向追踪**（去向）：沿 `reads_from`, `reads_state`, `transforms`, `persists_to` 边正向 BFS
+   - 找到所有读取 D 的函数/服务
+   - 继续追踪这些函数的输出去向
+   - 直到找到最终汇聚点（数据库、外部 API、日志）
+4. 生成数据血缘图：
+   - Mermaid `graph TD` 图，数据节点高亮
+   - 每步标注操作类型（read/write/transform/persist）
+5. 输出数据流描述文本
+
+### 5. 邻域查询 (Neighborhood)
+
+查看某个节点周围 N 跳的所有关联。
+
+```
+/show everything connected to AuthService within 2 hops
+/neighbors of UserController.createUser
+```
+
+**执行步骤**：
+1. 定位焦点节点 F
+2. 无向 BFS（不区分边的方向）展开 N 跳（默认 2，最大 5）
+3. 按当前粒度级别过滤节点/边类型
+4. 输出：
+   - 邻域图（Mermaid）
+   - 每个邻居节点与焦点的关系说明
+   - 按关系类型分组统计
+
+### 6. 聚合查询 (Aggregate)
+
+按度量值排序和筛选节点。
+
+```
+/which module has highest coupling
+/top 10 most complex functions
+/modules ranked by importance
+/show all nodes with Critical risk level
+```
+
+**支持的度量**：
+- `coupling` → instability (I), efferent coupling (Ce), afferent coupling (Ca)
+- `complexity` → cyclomatic_complexity, halstead_volume
+- `importance` → composite importance score
+- `quality` → maintainability_index, technical_debt_ratio
+- `centrality` → betweenness, in_degree, out_degree
+- `data_flow` → flow_rate, schema_coupling
+
+**执行步骤**：
+1. 解析查询的度量和排序方向
+2. 从 knowledge-graph.json 读取所有节点的 metrics
+3. 按指定度量排序
+4. 输出 top N 结果（默认 10，最大 50）
+5. 生成柱状图 ASCII 或 Mermaid
+
+## 粒度缩放 (Zoom Level)
+
+查询时通过 `zoom` 参数控制结果粒度：
+
+| 缩放级别 | 可见节点类型 | 可见边类型 | 适用场景 |
+|---------|------------|-----------|---------|
+| G1 (System) | module, layer | depends_on | 架构全景 |
+| G2 (Module) | + class, service, store, interface | + implements, extends, belongs_to | 模块内部结构 |
+| G3 (Function) | + function, api, route, hook | + calls, calls_async, returns, sends_http | 调用链追踪 |
+| G4 (Data) | + data_entity | + reads_from, writes_to, transforms, validates, reads_state, writes_state | 数据流分析 |
+| G5 (Cross-cutting) | 所有类型 | 所有边类型 | 全景视图 |
+
+**缩放实现**：
+- 读取 knowledge-graph.json
+- 按级别过滤节点类型 → 按级别过滤边类型
+- 从焦点节点 BFS 展开（如有焦点）
+- 返回过滤后的子图
+
+## 输出格式
+
+每个查询结果包含以下部分：
+
+### 1. 结构化摘要
+```
+## Query Result: Impact Analysis on User entity
+
+**Risk Level**: HIGH (0.82)
+**Affected Modules**: 5
+**Affected Functions**: 23
+**Affected APIs**: 3
+```
+
+### 2. Mermaid 可视化
+根据查询类型生成对应的 Mermaid 图：
+- 路径查询 → `graph LR`（从左到右的有向图）
+- 影响分析 → `graph TD`（从上到下的辐射图）
+- 数据血缘 → `graph TD`（数据流图）
+- 邻域查询 → `graph TD`（星形图）
+- 聚合查询 → 柱状图或表格
+
+### 3. ASCII 视图（终端兼容）
+```
+UserController.create()  --calls-->  UserService.createUser()
+    └── UserService.createUser()  --calls-->  UserRepository.save()
+        └── UserRepository.save()  --persists_to-->  [DB: users]
+```
+
+### 4. 明细表格
+| 节点 | 类型 | 度量 | 关系 |
+|------|------|------|------|
+
+## 多维分析查询
+
+如果 `.atool-docs/multi-dimensional-analysis.json` 存在，还可以查询：
+
+```
+/show structural analysis results
+/show call graph hotspots
+/show data flow hotspots
+/show quality metrics summary
+/show domain vocabulary
+```
+
+## Skill 协作
+
+| 协作 Skill | 触发条件 | 交互方式 |
+|-----------|---------|---------|
+| project-analyze | 需要生成 knowledge-graph.json | 前置依赖 |
+| code-review | 需要更详细的代码质量分析 | 建议运行 |
+| software-architecture | 影响分析显示架构问题 | 建议运行 |
+
+## 错误处理
+
+- 如果 `knowledge-graph.json` 不存在 → 提示用户先运行 `/project-analyze`
+- 如果查询的节点不存在 → 列出最接近的匹配建议（模糊搜索）
+- 如果查询的度量不存在 → 列出可用的度量列表
+- 如果结果为空 → 建议更高的分析深度（L2+ 推荐用于路径查询）