SuperAPI AI 工具集

scan

编程与开发

查看项目

更新于 10-16 07:31

技能介绍

用途

scan 是一个代码库扫描技能(Codebase Scanner)。它扮演技术分析师的角色,扫描项目代码库并产出准确、与具体项目相关的文档,供所有下游智能体使用。它最终生成两个文件:.claude/pipeline/project-doc.md 与仓库根目录的 AGENTS.md。

主要能力

  1. 生成项目文档 project-doc.md:输出到 .claude/pipeline/project-doc.md,结构基于 architecture-blueprint-generator 模式,包含以下段落:技术栈、依赖、架构模式、目录结构、代码风格约定、模块化实践、数据架构、横切关注点、服务通信、测试覆盖、入口点、变更文件(仅增量扫描)、最后扫描时间。
  2. 生成 AGENTS.md:写入仓库根目录,并非 project-doc.md 的副本,而是重写为针对该项目的智能体指令,是所有智能体首先读取的文件。若检测到项目为 MERN 栈(MongoDB + Express + React + Node.js),会追加一节 “MERN Stack Notes”,内容涵盖:优先使用 Mongoose 中间件而非原始查询、在 Express 中用集中式错误处理器处理异步错误、避免将 JWT 存储于 localStorage(改用 httpOnly cookies)、不要在 API 响应中直接暴露 Mongoose 错误对象。
  3. 全量扫描与增量扫描:若 .claude/pipeline/project-doc.md 不存在则执行全量扫描(FULL SCAN,首次运行);若存在则执行增量扫描(DELTA SCAN)。增量扫描使用 git diff HEAD~1 --name-only 获取变更文件,若无变更则报告 “No changes detected — project-doc.md is current” 并退出;否则仅重新分析变更文件并修补文档受影响段落。
  4. 架构变更检测(仅增量运行):对比新旧版本,检查是否新增框架或主要库、是否新建架构性目录模式(如新的 /lib/hooks/、/services/)、是否发生重大依赖替换(如 axios → fetch、moment → dayjs)、是否新增鉴权或会话处理模式。如检测到,则提示是否更新 AGENTS.md,需人工确认 [y] 才修补相关段落,永不重写整个文件。
  5. 可选插件增强:检查两个可选增强插件是否可用:
    • 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 中的代码风格约定须从实际代码推断,不得猜测。
  • 具体支持平台、收费与价格信息暂未提供。