用途
scan 是一个代码库扫描技能(Codebase Scanner)。它扮演技术分析师的角色,扫描项目代码库并产出准确、与具体项目相关的文档,供所有下游智能体使用。它最终生成两个文件:.claude/pipeline/project-doc.md 与仓库根目录的 AGENTS.md。
主要能力
- 生成项目文档 project-doc.md:输出到
.claude/pipeline/project-doc.md,结构基于 architecture-blueprint-generator 模式,包含以下段落:技术栈、依赖、架构模式、目录结构、代码风格约定、模块化实践、数据架构、横切关注点、服务通信、测试覆盖、入口点、变更文件(仅增量扫描)、最后扫描时间。 - 生成 AGENTS.md:写入仓库根目录,并非 project-doc.md 的副本,而是重写为针对该项目的智能体指令,是所有智能体首先读取的文件。若检测到项目为 MERN 栈(MongoDB + Express + React + Node.js),会追加一节 “MERN Stack Notes”,内容涵盖:优先使用 Mongoose 中间件而非原始查询、在 Express 中用集中式错误处理器处理异步错误、避免将 JWT 存储于 localStorage(改用 httpOnly cookies)、不要在 API 响应中直接暴露 Mongoose 错误对象。
- 全量扫描与增量扫描:若
.claude/pipeline/project-doc.md不存在则执行全量扫描(FULL SCAN,首次运行);若存在则执行增量扫描(DELTA SCAN)。增量扫描使用git diff HEAD~1 --name-only获取变更文件,若无变更则报告 “No changes detected — project-doc.md is current” 并退出;否则仅重新分析变更文件并修补文档受影响段落。 - 架构变更检测(仅增量运行):对比新旧版本,检查是否新增框架或主要库、是否新建架构性目录模式(如新的
/lib/hooks/、/services/)、是否发生重大依赖替换(如 axios → fetch、moment → dayjs)、是否新增鉴权或会话处理模式。如检测到,则提示是否更新 AGENTS.md,需人工确认[y]才修补相关段落,永不重写整个文件。 - 可选插件增强:检查两个可选增强插件是否可用:
- understand-anything(Lum1104/Understand-Anything)— 提供更深入的语义代码分析;
- context-mode(mksglu/context-mode)— 将大输出经由沙盒路由,以保护上下文窗口。
两者均缺失时,使用原生回退方案:直接使用 find、grep、cat 和 git 命令;若 context-mode 可用,则将大输出经
ctx_execute/ctx_execute_file路由,否则内联汇总。
使用方式
可手动安装可选插件:
/plugin marketplace add Lum1104/Understand-Anything && /plugin install understand-anything
/plugin marketplace add mksglu/context-mode && /plugin install context-mode@context-mode
检测插件:/plugin list | grep understand-anything 与 /plugin list | grep context-mode。
流程:步骤 1 检查可选插件依赖 → 步骤 2 判定扫描模式 → 步骤 3A 全量扫描或 3B 增量扫描 → 步骤 4A 生成 AGENTS.md(仅首次运行)或 4B 架构变更检测(增量运行)→ 步骤 5 报告。
写入 project-doc.md 后,若 context-mode 可用,则将全部输出路由经其工具(ctx_batch_execute / ctx_execute_file),绝不可将原始文件内容倾泻进主上下文窗口;若不可用,则逐文件内联汇总并避免打印原始文件内容。
报告中打印摘要形如:
✅ Scan complete ([FULL/DELTA])
project-doc.md → updated
AGENTS.md → [generated / patched / unchanged]
Changed files → [N files re-scanned / N/A for full scan]
Coverage → [X%]
并将状态写入 state.json 的 checkpoints.scan = "completed"。
适用场景
- 引导(bootstrap)新的智能体驱动仓库时;
- 项目文档需要刷新时。
限制
- 两个增强插件为可选,非必需;缺失时以原生命令回退。
- 增量扫描下若 git diff 无变更文件,则直接退出。
- AGENTS.md 的更新需人工确认后才执行,且只修补相关段落,不重写完整文件。
- project-doc.md 中的代码风格约定须从实际代码推断,不得猜测。
- 具体支持平台、收费与价格信息暂未提供。