Codebase Parse

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

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

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

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

---

与相邻 skill 的分工

| 场景 | 用哪个 | |------|--------| | 解析整个项目代码 / 梳理页面·接口·动效 | codebase-parse | | 有具体需求,评估改哪些文件 | req-analyze | | 某段代码 bug / 性能 / 内存 | vue-fe-review | | 提 PR 前安全与测试 | pre-pr-review | | 生成 Vue 组件骨架 | vue-component-gen |

---

启动

用户已指定范围

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

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

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

可选加速

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

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

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

---

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

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

| 产出块 | 深度 | |--------|------| | 技术栈总览 | 全量 | | 项目逻辑(入口/路由/守卫/全局状态/配置/Electron 主进程) | 全量 | | 接口逻辑(封装层 + 模块清单 + 端点总表) | 全量索引;封装与鉴权深读 | | 页面索引表 | 全量(每个路由一行摘要) | | 页面逻辑详解 | 核心页深解,默认最多 10 页 | | 动效清单 | 全量索引(按页面/组件列);核心页动效写入详解 |

核心页选取顺序(按优先级取,凑满 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

1. 运行命令

• 从 scripts 提取 dev / build / test / lint / typecheck,原样列出,找不到标 待确认

1. 目录地图

• 列出页面、组件、API、store、composables、router、config、types、styles、electron-main、preload、renderer 等实际存在的路径

1. 路由全量索引

• Vue/React Router 配置文件、Nuxt pages/ 文件路由、Next app/ 或 pages/、uni-app pages.json
• Electron:主进程 BrowserWindow + loadURL / loadFile 与 renderer 路由的对应关系

1. 动效关键词扫描

• 见「动效探测规则」节,产出命中文件列表

1. 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 入口

1. 路由体系

• 全量 path / name / component / meta(权限、keepAlive、title、layout)

1. 鉴权与守卫

• beforeEach、Next middleware、Nuxt route middleware、uni 登录拦截、Electron 是否单实例

1. 全局状态

• Pinia / Redux / Zustand / Jotai / MobX / Vuex:每个 store 的文件、职责、主要 action/getter

1. 请求封装

• baseURL 来源、拦截器、token 注入、错误码、401 处理、域名/环境切换

1. 项目约定(只写本仓库特有的)

• 路径别名、自动导入、UI 按需、设计稿适配、env 变量命名、lint 配置路径

1. Electron 专块(若存在)

• 主进程职责、窗口类型(透明/托盘)、IPC channel 清单(preload 暴露的 API)、主↔渲染数据流

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

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

---

项目类型探测要点

Vue / Nuxt / uni-app

| 检查项 | 位置 | |--------|------| | 版本与模式 | package.json, nuxt.config | | 页面 | pages/、views/、src/pages/ | | 路由 | router/index.ts 或 Nuxt 文件路由 | | 状态 | stores/、pinia | | 小程序 | pages.json tabBar、subpackage |

React / Next.js

| 检查项 | 位置 | |--------|------| | 路由模式 | React Router 配置 / Next app/(App Router) / pages/(Pages Router) | | 数据获取 | loader、getServerSideProps、use server、RTK Query、SWR、React Query | | 状态 | store/、features/、zustand useXxxStore | | 布局 | layout.tsx、_app.tsx |

Electron

| 检查项 | 位置 | |--------|------| | 主进程 | electron-main/、main/、src/main/ | | 预加载 | preload.ts, contextBridge.exposeInMainWorld | | 渲染进程 | 内嵌 Web 栈,按 Vue 或 React 规则继续解析 | | 打包 | electron-builder.yml、forge.config.js | | 窗口/托盘 | BrowserWindow 选项、Tray、透明与穿透相关 API |

monorepo

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

---

技术栈:声明 vs 实际使用

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

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

输出分表:

| 类别 | 声明 | 实际使用证据 | |------|------|--------------| | 框架 | … | src/main.ts:3 import vue | | 状态 | … | stores/user.ts | | UI 库 | … | 组件 import 路径 | | 请求 | … | 封装文件路径 | | 动效 | … | grep 命中 | | 测试 | … | vitest/jest/playwright 配置 |

---

接口逻辑解析

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

1. 封装层

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

2. 模块清单

| 模块 | 文件 | 职责 |

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

| 方法 | 路径 | 封装函数 | 定义位置 | 主要调用方 | |------|------|----------|----------|------------|

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

4. 鉴权与环境

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

---

页面逻辑:索引表 vs 详解

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

| 路由/path | 组件文件 | 职责摘要 | 主要 API | 动效(有/无) | 深解 | |-----------|----------|----------|----------|-------------|------|

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

核心页详解(固定模板)

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

### 页面: `/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,按类型归类:

| 类型 | 关键词 / 特征 | |------|----------------| | Vue 过渡 | `80 | 索引 + 核心页深解(≤10);其余页仅索引;建议用户指定下一批深解模块 |

---

不确定性处理

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

---

禁止

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SirGuanZz
• Source: SirGuanZz/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.