这是一份写给 AI 执行的 SOP。目的：把\"每次开发前重读整个代码库\"这个昂贵动作一次性固化成结构化文档缓存，后续开发直接加载文档当上下文。
\n调用格式：/codebase-context <mode> [project-name] [--full]
mode：\nscan → 进入 scan 模式dev → 进入 dev 模式用法: /codebase-context <scan|dev> [project-name] [--full] 并终止-- 开头参数为 project-name：\nbasename \"$PWD\"，取当前工作目录最后一段路径名作为 project-name--full 参数：\nDOC_DIR = {PROJECT_ROOT}/docs/codebase-context/（存于项目工程内,随 git 提交、团队共享、换机不丢）PROJECT_ROOT = 当前工作目录全部存于 DOC_DIR 下，文件名固定，不得增删改名：
| 文件 | \n内容 | \n
|---|---|
| 00-index.md | \n索引与快速导航 | \n
| 01-overview.md | \n项目概述与技术栈 | \n
| 02-directory.md | \n目录结构 | \n
| 03-architecture.md | \n架构设计与模块关系 | \n
| 04-api-routes.md | \nAPI 接口汇总 | \n
| 05-data-models.md | \n数据模型与类型 | \n
| 06-core-modules.md | \n核心模块（组件/Hooks/Store） | \n
| 07-business-logic.md | \n关键业务逻辑 | \n
| 08-conventions.md | \n编码规范与约定 | \n
| 09-changelog.md | \n文档变更记录 | \n
| .scan-meta.json | \n{\"lastScanTime\":\"UTC时间\",\"scanType\":\"full|incremental\",\"projectRoot\":\"绝对路径\"} | \n
*/package.json、*/*/package.json（及 Cargo.toml/go.mod 等）——若当前目录自身不是单一项目根（无 src/），而多个子目录各含项目描述文件 → 列出候选子项目并让用户选定（或用 project-name 参数匹配子目录名）；选定后 PROJECT_ROOT/DOC_DIR 重设为该子项目根。把多个不相干项目扫进一张地图，查重与波及面全部失真——脏地图比没地图更危险（实跑教训：4 项目混装仓库靠人肉 cd 才扫对）--full 参数 → 全量扫描.scan-meta.json 且 无 --full → 增量扫描.scan-meta.json → 全量扫描（元数据缺失视同首扫）mkdir -p {DOC_DIR} 创建目录规模档位（先数源码文件再动手）：≤200 个源文件 → 按下述七轮正常执行；>200 个 → 第 4/5/6 轮不逐个 Read，改用 Grep 收 export 签名清单入表（函数名/类型名/位置），精读仍限抽样 3–5 个最复杂文件；>500 个 → 同上，并提示用户\"项目较大，建议按模块分次 scan（cd 到子模块根分别执行）\"。防止扫到一半上下文耗尽——成本花了、地图没产出是最差结果。
\n第 1 轮 项目元信息：用 Read 读取 package.json、README.md；用 Glob 匹配构建配置 vite.config.*、webpack.config.*、tsconfig.json、next.config.*、.env.example，逐个 Read。提取：项目名/版本/依赖清单/脚本命令/构建工具/环境变量键名。
第 2 轮 目录结构：用 Bash 执行 ls -R（或用 Glob src/*/* 展开 src 两层）。识别 pages/、components/、api/、store/、hooks/、utils/、types/ 等目录及其职责。
第 3 轮 入口与路由：用 Glob 定位 main.*、index.*、App.*、router/、routes/，逐个 Read；用 Grep 搜索全局 store 初始化与全局 service 入口。提取：启动链路、路由表、全局状态挂载点。
第 4 轮 API 接口层：用 Glob 匹配 **/api/** 与 **/services/**，逐个 Read。提取每个接口函数的：函数名 / HTTP 方法 / URL / 参数 / 返回类型 / 定义位置（文件:函数）。
第 5 轮 数据模型与类型：用 Glob 匹配 **/types/**、**/models/**、**/interfaces/**、**/enums/**，逐个 Read。提取：实体 / 枚举 / DTO 及各自定义位置。
第 6 轮 核心模块：用 Glob 展开 components/（区分公共组件 vs 业务组件）、hooks/、store/，逐个 Read 提取签名与职责；再用 Grep 按 import 次数与文件行数抽样精读 3–5 个最复杂的页面/组件（Read 全文），提取其状态、关键流程。
第 7 轮 规范与工具：用 Glob 匹配 **/constants/**、**/config/**、**/utils/** 及 .eslintrc*、.prettierrc*，逐个 Read。提取：常量清单 / 工具函数清单 / 可推断的代码规范。
依据下方【文档模板】，按 00 → 09 顺序逐份用 Write 生成 10 份文档，照模板填空。
\ndate -u +\"%Y-%m-%dT%H:%M:%SZ\" 取 UTC 时间.scan-meta.json：{\"lastScanTime\":\"{UTC}\",\"scanType\":\"full\",\"projectRoot\":\"{PROJECT_ROOT}\"}✅ codebase-context 全量扫描完成 — {project-name}\n\uD83D\uDCC1 文档目录: {DOC_DIR}\n\uD83D\uDCC4 生成文档: 10 份（00-index ~ 09-changelog）\n\uD83D\uDCCA 扫描统计: 接口 {N} 个 | 类型 {N} 个 | 组件 {N} 个 | Hooks {N} 个 | 精读页面 {N} 个\n▶ 开发时执行: /codebase-context dev {project-name}\n.scan-meta.json，取 lastScanTime 与 projectRootfind {projectRoot}/src -type f \\( -name \"*.ts\" -o -name \"*.tsx\" -o -name \"*.js\" -o -name \"*.jsx\" -o -name \"*.vue\" -o -name \"*.json\" \\) -newer {DOC_DIR}/.scan-meta.json\n02-directory.md 记录的文件清单对比，推断新增文件（结果里有、文档里无）与删除文件（文档里有、磁盘上无——用 Bash test -f 验证）按下表将每个变更文件路径映射到扫描轮次，只重跑受影响的轮次：
\n| 文件路径模式 | \n扫描轮次 | \n需更新文档 | \n
|---|---|---|
| package.json / README / vite・webpack・tsconfig・next 配置 / .env.example | \n第 1 轮 | \n01-overview | \n
| 目录新增/删除（任何路径层级变化） | \n第 2 轮 | \n02-directory | \n
| main.* / index.* / App.* / router/ / routes/ / 全局 store・service 入口 | \n第 3 轮 | \n03-architecture | \n
| **/api/** 、 **/services/** | \n第 4 轮 | \n04-api-routes | \n
| **/types/** 、 **/models/** 、 **/interfaces/** 、 **/enums/** | \n第 5 轮 | \n05-data-models | \n
| components/ 、 hooks/ 、 store/ | \n第 6 轮 | \n06-core-modules | \n
| pages/ 下的页面文件 | \n第 6 轮 | \n06-core-modules、07-business-logic | \n
| **/constants/** 、 **/config/** 、 **/utils/** 、 eslint/prettier 配置 | \n第 7 轮 | \n08-conventions | \n
| （任何变更，无条件） | \n— | \n09-changelog、00-index（日期） | \n
00-index.md 的\"最后更新\"日期09-changelog.md 追加本次条目（日期/类型 incremental/变更摘要/涉及文档）.scan-meta.json（scanType: \"incremental\"）；否则保留原元数据，在索引/日志标明本次局部核实范围，不用新时间掩盖未知区域✅ codebase-context 增量扫描完成 — {project-name}\n\uD83D\uDD0D 变更检测: 新增 {N} 个 | 修改 {N} 个 | 删除 {N} 个\n\uD83D\uDCC4 已更新文档: {文档列表，如 04-api-routes、05-data-models、09-changelog、00-index}\nreferences/writeback.md 先查项目指定地图，否则从代码定向建立本次链路；任务目标缺失时先补问目标，不盲扫全仓references/writeback.md 核实地图与当前代码；过期、错误或缺少相关链路时定向补查，确认本次影响范围后才能改业务代码。授权范围内审前回写，不强制全量 scan\uD83D\uDCDA 已加载 {project-name} 参考文档（{实际数量} 份，覆盖 {相关模块}，最后更新 {日期}）\n\uD83D\uDCCC 项目概要: {已核实的一句话或待核实}\n开发过程中强制遵循：
\n08-conventions.md 的规范与约定04-api-routes.md——已有接口直接复用，不重复造05-data-models.md——已有类型直接引用，不重复定义06-core-modules.md——已有组件/Hook 直接复用03-architecture.md 的分层与模块归属开发结束、独立审查前必须按 业务地图增量回写 评估并更新受影响章节；\n无需更新时说明依据。需求开发和缺陷修复复用同一判据，不重复扫描或在批准后回写。
\n生成时照模板填空；某章节在本项目无对应内容时保留标题并填\"本项目未发现此类文件\"。
\n# {project-name} — 代码库参考文档索引\n\n- 最后更新: {YYYY-MM-DD HH:MM UTC}\n- 扫描类型: {full | incremental}\n- 项目根: {projectRoot}\n\n## 文档导航\n\n| 文档 | 内容 | 什么时候看 |\n| ---- | ---- | ---- |\n| 01-overview | 项目概述与技术栈 | 初次接触项目 |\n| 02-directory | 目录结构 | 找文件放哪/在哪 |\n| 03-architecture | 架构与模块关系 | 新代码归属、理解依赖方向 |\n| 04-api-routes | API 接口汇总 | 调接口前查重 |\n| 05-data-models | 数据模型与类型 | 定义类型前查重 |\n| 06-core-modules | 组件/Hooks/Store | 写组件前查复用 |\n| 07-business-logic | 关键业务逻辑 | 改业务流程前看线路 |\n| 08-conventions | 编码规范与约定 | 动手写代码前 |\n| 09-changelog | 文档变更记录 | 追溯文档演进 |\n\n## 快速定位\n\n| 我想找… | 去 |\n| ---- | ---- |\n| 某个接口怎么调 | 04-api-routes |\n| 某个字段的类型定义 | 05-data-models |\n| 有没有现成组件/Hook | 06-core-modules |\n| 某业务流程的完整线路 | 07-business-logic |\n| 命名/风格规矩 | 08-conventions |\n# 项目概述与技术栈\n\n## 项目定位\n\n{一句话说明这个项目是什么、给谁用、解决什么问题}\n\n## 技术栈\n\n| 层 | 技术 | 版本 |\n| ---- | ---- | ---- |\n| 语言 | {TypeScript/…} | {x.y} |\n| 框架 | {React/Vue/…} | {x.y} |\n| 构建 | {Vite/Webpack/…} | {x.y} |\n| 状态管理 | {…} | {x.y} |\n| 其他关键依赖 | {…} | {x.y} |\n\n## 脚本命令\n\n| 命令 | 作用 |\n| ---- | ---- |\n| `npm run dev` | {…} |\n| `npm run build` | {…} |\n| `npm run test` | {…} |\n\n## 环境变量（仅键名与用途，不含值）\n\n| 键 | 用途 | 来源 |\n| ---- | ---- | ---- |\n| {ENV_KEY} | {…} | .env.example |\n# 目录结构\n\n## 目录树（src 两层）\n\n```text\nsrc/\n├── pages/ # {职责}\n├── components/ # {职责}\n├── api/ # {职责}\n├── store/ # {职责}\n├── hooks/ # {职责}\n├── utils/ # {职责}\n└── types/ # {职责}\n```\n\n## 目录职责\n\n| 目录 | 职责 | 典型文件 |\n| ---- | ---- | ---- |\n| {src/pages} | {…} | {…} |\n\n## 文件清单（供增量扫描对比新增/删除）\n\n| 文件 | 所属轮次 |\n| ---- | ---- |\n| {src/api/user.ts} | 4 |\n# 架构设计与模块关系\n\n## 分层结构\n\n```text\n{页面层 pages}\n ↓ 调用\n{逻辑层 hooks / store}\n ↓ 调用\n{服务层 api / services}\n ↓ 请求\n{后端 / 云函数}\n```\n\n## 启动链路\n\n{main.* → App.* → 路由挂载 → 全局 store 初始化，逐步说明，每步带 文件:位置}\n\n## 路由表\n\n| 路径 | 页面 | 定义位置 |\n| ---- | ---- | ---- |\n| {/home} | {pages/home} | {router/index.ts} |\n\n## 模块依赖关系\n\n| 模块 | 依赖谁 | 被谁依赖 |\n| ---- | ---- | ---- |\n| {store/user} | {api/user} | {pages/*, hooks/useAuth} |\n# API 接口汇总\n\n## {模块名，如 user}\n\n| 函数名 | 方法 | URL | 参数 | 返回类型 | 定义位置 |\n| ---- | ---- | ---- | ---- | ---- | ---- |\n| {getUser} | GET | {/api/user/:id} | {id: string} | {User} | {src/api/user.ts} |\n\n（按模块分节重复上表；无 api/ 与 services/ 目录时填\"本项目未发现此类文件\"）\n# 数据模型与类型\n\n## 实体\n\n| 名称 | 字段摘要 | 定义位置 | 主要使用方 |\n| ---- | ---- | ---- | ---- |\n| {User} | {id, name, role…} | {src/types/user.ts} | {api/user, store/user} |\n\n## 枚举\n\n| 名称 | 取值 | 定义位置 |\n| ---- | ---- | ---- |\n| {OrderStatus} | {pending/paid/closed} | {src/types/order.ts} |\n\n## DTO / 请求响应类型\n\n| 名称 | 用于接口 | 定义位置 |\n| ---- | ---- | ---- |\n| {CreateOrderReq} | {POST /api/order} | {src/types/dto.ts} |\n# 核心模块\n\n## 公共组件\n\n| 组件 | Props 摘要 | 定义位置 | 复用场景 |\n| ---- | ---- | ---- | ---- |\n| {Button} | {type, onClick…} | {src/components/common/} | {全局} |\n\n## 业务组件\n\n| 组件 | 职责 | 定义位置 | 所属业务 |\n| ---- | ---- | ---- | ---- |\n\n## Hooks\n\n| 名称 | 输入 | 输出 | 定义位置 |\n| ---- | ---- | ---- | ---- |\n| {useAuth} | {—} | {user, login, logout} | {src/hooks/useAuth.ts} |\n\n## Store\n\n| 模块 | state 摘要 | 主要 actions | 定义位置 |\n| ---- | ---- | ---- | ---- |\n\n## 复杂页面精读（3–5 个）\n\n### {页面名}（{文件路径}）\n\n- 职责: {…}\n- 关键状态: {…}\n- 关键流程: {步骤 1 → 步骤 2 → …，每步带函数名}\n# 关键业务逻辑\n\n## {业务线名，如：下单}\n\n**线路**：{页面 pages/order} → {hook useOrder} → {api createOrder} → {POST /api/order} → {模型 Order}\n（每个环节标注 文件:函数）\n\n**关键规则**：\n\n- {规则 1，如：金额用分存储，展示层才转元 —— src/utils/money.ts}\n- {规则 2}\n\n**边界与注意**：\n\n- {已知坑/特殊分支/兼容逻辑，带位置}\n\n（按业务线重复本节）\n# 编码规范与约定\n\n## 命名\n\n| 对象 | 规则 | 示例 |\n| ---- | ---- | ---- |\n| 组件文件 | {PascalCase} | {UserCard.tsx} |\n| hooks | {use 前缀} | {useAuth} |\n\n## 代码风格（自 ESLint/Prettier 推断）\n\n- {缩进/引号/分号/import 排序 等要点}\n\n## 常量\n\n| 常量 | 值/含义 | 定义位置 |\n| ---- | ---- | ---- |\n\n## 工具函数\n\n| 函数 | 用途 | 定义位置 |\n| ---- | ---- | ---- |\n\n## 其他约定\n\n- {错误处理方式/请求封装规则/目录放置约定}\n# 文档变更记录\n\n| 日期(UTC) | 类型 | 变更摘要 | 涉及文档 |\n| ---- | ---- | ---- | ---- |\n| {2026-07-14T08:00Z} | full | 首次全量扫描 | 全部 10 份 |\n| {…} | incremental | {新增 2 接口/修改 1 类型} | {04、05} |\n| {…} | dev回写 | {开发 xx 功能后回写} | {04、06、07} |\n⚠ 当前目录未发现 package.json，请确认 {PROJECT_ROOT} 是正确的项目目录（回复继续则按非 npm 项目扫描），等用户确认后再继续。api/）：跳过该轮，在对应文档的相应章节标注\"本项目未发现此类文件\"，不报错不中断。(大文件,仅提取签名)。references/writeback.md 定向核实/补齐；证据不足暂停相关修改，不猜测，不强制全量 scan。