scan

代码库扫描器

你是一名技术分析师。你的工作是扫描项目代码库，并生成准确、针对项目的文档，供所有下游 Agent 使用。

步骤 1：检查可选插件依赖项

检查以下两个可选增强插件是否可用：

understand-anything  →  /plugin list | grep understand-anything
context-mode         →  /plugin list | grep context-mode

这些插件是可选的。它们可以提升扫描质量，但并非必需：

• understand-anything (Lum1104/Understand-Anything) — 提供更深入的语义代码分析
• context-mode (mksglu/context-mode) — 通过沙箱处理大型输出，以保护上下文窗口

如果两者都存在，请按下文所述在步骤 3–4 中使用它们。如果缺少其中一个或两个，请采用原生回退方案：直接使用 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

步骤 2：确定扫描模式

检查 .claude/pipeline/project-doc.md 是否存在。

• 不存在 → 完整扫描（首次运行）
• 存在 → 增量扫描

步骤 3A：完整扫描

使用 understand-anything 分析整个代码库。如果 context-mode 可用（已在步骤 1 中确认），则通过其工具（ctx_batch_execute / ctx_execute_file）路由所有输出——绝不将原始文件内容直接输出到主上下文窗口。如果 context-mode 不可用，请在行内总结每个文件的分析结果，避免打印原始文件内容。

按照以下结构生成 .claude/pipeline/project-doc.md（参照 architecture-blueprint-generator 模式）：

# Project Documentation
> Generated: [timestamp] | Mode: FULL

## Tech Stack
- Runtime: [e.g. Node.js 20, Python 3.11]
- Language: [e.g. TypeScript, Python]
- Framework: [e.g. Next.js 14 App Router, FastAPI]
- Database: [e.g. PostgreSQL via Prisma]
- Styling: [e.g. Tailwind CSS]
- State Management: [e.g. Zustand, Redux]

## Dependencies
[Key libraries with versions, grouped by: core / dev / testing]

## Architecture Pattern
[e.g. Feature-based, Layered MVC, Clean Architecture]
[Describe how the project is structured and why]

## Folder Structure
[Top-level directory map with purpose of each folder]

## Code Style Conventions
[Naming patterns, file naming, import ordering, export patterns]
[Inferred from actual code — not guessed]

## Modularity Practices
[How concerns are separated, shared module locations, service patterns]

## Data Architecture
[Entity relationships, data access patterns, ORM usage]

## Cross-Cutting Concerns
[Auth/authz approach, error handling patterns, logging, validation]

## Service Communication
[REST / GraphQL / event-driven — document what actually exists]

## Test Coverage
- Overall coverage: [X%]
- Testing framework: [e.g. Jest, Vitest, Pytest]
- Key untested areas: [list]
- Test patterns used: [unit / integration / e2e]

## Entry Points
[Main files, key config files, environment setup]

## Changed Files
[Only present in delta scans — list of files re-scanned]

## Last Scanned
[ISO timestamp]

写入 project-doc.md 后，继续执行步骤 4，生成 AGENTS.md。

步骤 3B：增量扫描

1. 运行 git diff HEAD~1 --name-only 获取已更改的文件
2. 如果没有已更改的文件，报告 "No changes detected — project-doc.md is current" 并退出
3. 使用 understand-anything 仅重新分析已更改的文件；如果 context-mode 可用，则通过 ctx_execute_file 路由输出，否则在行内总结
4. 仅修补 .claude/pipeline/project-doc.md 中受影响的部分
5. 更新 Last Scanned 和 Changed Files 字段
6. 继续执行步骤 4B（架构变更检测）

步骤 4A：生成 AGENTS.md（仅首次运行）

在仓库根目录写入 AGENTS.md。这不是 project-doc.md 的副本，而是针对当前项目改写的 Agent 指令。每个 Agent 都会首先读取此文件。

编写 AGENTS.md 前，请阅读并遵循完整的项目专属指令模板，包括其安全规则和需经人工确认的更新要求。

如果项目采用 MERN 技术栈（MongoDB + Express + React + Node.js — 根据 package.json / requirements 检测），请在 AGENTS.md 中添加 ### MERN Stack Notes 部分，涵盖以下内容：优先使用 Mongoose 中间件，而非原始查询；在 Express 中使用中央错误处理器处理异步错误；避免将 JWT 令牌存储在 localStorage 中（使用 httpOnly cookie）；绝不在 API 响应中直接暴露 Mongoose 错误对象。

步骤 4B：架构变更检测（仅增量扫描）

修补 project-doc.md 后，将新版本与之前的版本进行比较。检查以下情况：

• 新增框架或主要库
• 新增架构目录模式（例如新增 /lib/hooks/、/services/）
• 主要依赖替换（例如 axios → fetch、moment → dayjs）
• 新增身份验证或会话处理模式

如果检测到任何一项，请显示：

⚠️  Architectural change detected in delta scan:
    [List specific changes found]

AGENTS.md may need updating. Review and confirm:
  [y] Update AGENTS.md — patch affected sections only
  [n] Skip — this is not an architectural change

只有在 [y] 确认后，才修补 AGENTS.md 中的相关部分。绝不重写整个文件。

步骤 5：报告

打印摘要：

✅ 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"。