codebase-parse: 全项目代码深度解析

职责:把当前仓库(或用户指定目录)转成代码说明书,回答:

• 技术栈:框架、语言、状态、UI、请求、样式、动效、测试——哪些是声明的、哪些是源码里真实在用的?
• 项目逻辑:入口、路由、鉴权、全局状态、配置、Electron 主进程 / IPC(若有)
• 接口逻辑:请求封装、模块划分、端点、鉴权、错误处理、主要调用方
• 页面逻辑:全量页面索引 + 核心页逐页深解(组件树、数据流、用户流程)
• 动效逻辑:Transition / CSS / 动画库 / 路由过渡 / 小程序 animation 等实现与触发条件

核心纪律:只读解析,不擅自改代码。 用户说「按这个分析去改」「开始实现某需求」后,改代码走对应实现 skill;评单条需求改动走 req-analyze。

与相邻 skill 的分工

启动

用户已指定范围

• 子目录(如 packages/web、apps/desktop):只解析该范围,报告开头注明 monorepo 根路径与 package 名。
• 指定页面 / 路由 / 模块(如「深解订单模块」):索引仍做全量(若路由表可读),深解只做指定范围。
• 指定框架关注点(如「只看 Electron 主进程」):其他轴写「未展开」。

用户只说「解析这个项目 / 解析代码」

直接开始,不要连问偏好。默认策略:全量索引 + 核心页深解(见下文)。

可选加速

项目较大时,先跑索引脚本再深读:

bash ~/.cursor/skills/codebase-parse/scripts/scan-index.sh [项目根目录,默认 .]

脚本输出路由/API/动效命中清单;不能替代读源码下结论,只用于缩小搜索范围。

默认深度:索引 + 核心页深解

未指定深度时,固定采用此策略:

核心页选取顺序(按优先级取,凑满 10 个或项目页数不足则停):

1. 用户指定的页面 / 路由 / 模块
2. 路由表里的首页 / 默认 redirect 目标
3. 登录 / 注册 / 鉴权相关页
4. tabBar / 主导航 / 侧边栏入口页
5. 业务上主流程闭环页(列表 → 详情 → 提交/支付等,从路由 meta、菜单配置、命名推断,证据不足标 待确认)
6. Electron:主窗口 / 首屏 renderer 对应路由或 loadURL 目标

索引表里其余页面:一行摘要(职责 + 主要 API + 有无动效),不展开组件树。

用户要求「全部页面深解」时:按模块分批输出,每批 ≤10 页,避免单轮过长。

解析流程(三轮)

能并行读的并行读。每轮结束先在心里核对:证据够不够、有没有和上一轮矛盾。

第一轮:扫描索引

1. 身份识别
   • package.json(含 workspaces)、lockfile 类型、engines
   • 构建配置:nuxt.config.* / vite.config.* / next.config.* / electron.vite.config.* / electron-builder.yml / pages.json + manifest.json
   • 判断项目类型标签(可多选):Vue SPA / Nuxt / uni-app / React SPA / Next.js / Electron / monorepo
2. 运行命令
   • 从 scripts 提取 dev / build / test / lint / typecheck,原样列出,找不到标 待确认
3. 目录地图
   • 列出页面、组件、API、store、composables、router、config、types、styles、electron-main、preload、renderer 等实际存在的路径
4. 路由全量索引
   • Vue/React Router 配置文件、Nuxt pages/ 文件路由、Next app/ 或 pages/、uni-app pages.json
   • Electron:主进程 BrowserWindow + loadURL / loadFile 与 renderer 路由的对应关系
5. 动效关键词扫描
   • 见「动效探测规则」节,产出命中文件列表
6. API 文件清单
   • api/、services/、hooks/use*Api、lib/request 等

第二轮:全局逻辑

1. 应用入口链
   • Web:main.tsx|ts / main.js → App → router / layout
   • Nuxt:app.vue + plugins/
   • Next:app/layout.tsx + middleware
   • Electron:electron-main 入口 → 窗口创建 → preload → renderer 入口
2. 路由体系
   • 全量 path / name / component / meta(权限、keepAlive、title、layout)
3. 鉴权与守卫
   • beforeEach、Next middleware、Nuxt route middleware、uni 登录拦截、Electron 是否单实例
4. 全局状态
   • Pinia / Redux / Zustand / Jotai / MobX / Vuex:每个 store 的文件、职责、主要 action/getter
5. 请求封装
   • baseURL 来源、拦截器、token 注入、错误码、401 处理、域名/环境切换
6. 项目约定(只写本仓库特有的)
   • 路径别名、自动导入、UI 按需、设计稿适配、env 变量命名、lint 配置路径
7. Electron 专块(若存在)
   • 主进程职责、窗口类型(透明/托盘)、IPC channel 清单(preload 暴露的 API)、主↔渲染数据流

第三轮:接口 + 核心页深解 + 动效

1. 读请求封装与每个 API 模块,填端点总表
2. 对核心页逐个读完整 SFC/TSX,填页面详解模板
3. 汇总动效清单,核心页的动效写入对应页面节

项目类型探测要点

Vue / Nuxt / uni-app

React / Next.js

Electron

monorepo

• 先读 workspace 根 package.json 与各 package 职责
• 默认解析用户 cwd 所在 package;用户指定根目录则按指定范围
• 跨 package 依赖在「项目逻辑」里单独说明

技术栈:声明 vs 实际使用

package.json dependencies 里有的不等于项目在用。规则:

• 已使用:源码中出现 import / require / 配置显式启用(如 tailwind.config plugins)
• 仅声明:dependencies 有但源码无引用 → 标「依赖已装未检出使用」
• 版本:写 package.json 中的范围,不猜 lock 精确版本除非读过 lockfile

输出分表:

接口逻辑解析

分四层,禁止只列 URL 字符串:

1. 封装层

• 文件路径、baseURL 来源、请求实例创建
• 请求/响应拦截:token、错误码、重试、取消
• 401 / 403 / 业务码处理与跳转

2. 模块清单

| 模块 | 文件 | 职责 |

3. 端点总表(全量索引)

调用方至少列 页面或顶层组件;找不到标 待确认。请求体/响应字段:只写源码里读到的类型或 JSDoc,不编。

4. 鉴权与环境

• token 存储位置与 header 名
• 环境变量与域名切换逻辑(config/env、import.meta.env、process.env)

页面逻辑:索引表 vs 详解

全量页面索引(每路由一行)

「深解」列:✅ 表示本轮展开,— 表示仅索引。

核心页详解(固定模板)

每个核心页一节,字段不可省略:

### 页面: `/path` → `path/to/Page.vue|tsx`

**职责**:一句话

**组件树**(2~3 层)
- `Page`
  - `ChildA` (`components/...`)
  - `ChildB` (…)

**数据流**
- 进入: route params / searchParams / props 来源
- 请求: `fn()` @ `api/xxx.ts:line` → 写入 store / setState
- 子组件: props down / events up / context

**本地状态**
- ref / useState / reactive 关键字段与用途

**用户流程**(来自 template 真实事件)
1. …
2. …

**依赖接口**
- 方法 路径 — 用途

**关联页面**
- 入口从哪来、跳去哪

**动效**(若有)
- 类型 / 实现 / 触发 — 证据 `file:line`

React 函数组件、Next Server/Client Component 同样适用;Server Component 数据流注明 fetch / cache / props from layout。

动效探测规则

全项目 grep 或跑 scan-index.sh,按类型归类:

动效清单(全量索引)

区分:页面级(路由切换、首屏)组件级(hover、列表)全局(平滑滚动、根 Transition)。

输出格式

固定章节,某节无内容写「未发现」,不要省略标题。

# 代码解析报告

## 0. 解析范围与信心
- 根目录 / 子包 / 用户指定范围
- 项目类型标签
- 信心:高 / 中 / 低(低信心列缺什么)

## 1. 技术栈总览
(声明 vs 实际使用表)

## 2. 怎么跑
| 用途 | 命令 | 依据 |

## 3. 项目逻辑
### 入口与插件
### 路由体系(全量)
### 鉴权 / 守卫
### 全局状态
### 项目约定
### Electron 主进程与 IPC(若有)

## 4. 接口逻辑
### 封装层
### 模块清单
### 端点总表
### 鉴权与环境

## 5. 页面索引(全量)
(索引表)

## 6. 核心页逻辑详解
(逐页模板)

## 7. 动效与交互实现
(动效清单 + 与核心页交叉引用)

## 8. 待确认项

## 9. 后续建议
- 评具体需求 → req-analyze
- 生成 Vue 组件 → vue-component-gen

规模分档

不确定性处理

• 页面职责靠命名推断:标「推断」,写依据(路由名、菜单文案、注释)
• 找不到路由配置:列 pages/ 文件路由猜测,标 待确认
• API 路径在运行时拼接:写拼接逻辑位置,不猜最终字符串
• 多种实现并存(两套请求封装):全部列出,标「并存」,写各自主要使用方
• 分析中发现 dead code:在「待确认项」提及,不擅自删

禁止

• 禁止在解析阶段编辑文件
• 禁止不读代码就输出技术栈或页面清单
• 禁止把「需求改动评估」写进本报告(那是 req-analyze)
• 禁止无证据的「可能用了 xxx」
• 禁止对小项目编造全量 encyclopedia 式废话
• 禁止在报告 / 中文回复中使用斜体;强调用粗体,路径 / 行号 / 字段 / 命令用反引号