| name | flow-intel-scan |
| description | Brownfield 项目入场扫描器。自动探测项目技术栈、框架、既有抽象、命名约定和数据库 schema，生成/更新 `.specs/CONTEXT.md` 作为后续所有 change 的共享上下文。优先使用 GitNexus MCP 进行语义级扫描（执行流、模块社区、符号关系），GitNexus 不可用时回退到 grep/find。Use when 用户说"扫描代码/scan/intel/入场扫描/给项目体检"，或新项目首次使用 flow-x 且没有 AI 上下文文档时。 |
| paradigm | scout |
flow-intel-scan — 入场扫描
Goal
在已存在的项目（brownfield）里第一次用 flow-x 时，自动扫描代码库 → 自动填 CONTEXT.md → 后续所有 change 都受益。
不是周期命令，跑过一次就行；项目结构有大变化（重构 / 框架升级 / 新增模块）时再跑。
GitNexus MCP 集成策略
优先级：GitNexus MCP（语义级） > grep/find（字面级）
| 扫描目标 | GitNexus MCP 工具 | 回退 grep 命令 |
|---|
| 模块/功能分区 | cypher（Community 节点 + heuristicLabel） | ls src/ + find src -type d |
| 执行流/业务流程 | query（搜索关键概念） | grep -rn "^import" |
| 既有抽象层 | query（搜索 HTTP client / DAO / 状态管理等） | grep -rn "axios|fetch|Repository" |
| API 路由 | route_map（完整路由映射） | grep -rn "@Route|@Controller" |
| 符号关系 | context（360度视图） | grep -rn "class.*extends" |
| 依赖方向 | impact（upstream blast radius） | grep -rn "^import" |
可用性检测（步骤 0 之后必跑）：
- 调用
gitnexus_impact 传一个已知符号（如项目入口类），如果返回有效结果 → GitNexus 可用
- 如果返回错误"index not found"或空结果 → GitNexus 不可用，全部回退到 grep
- 如果返回"index stale"警告 → 提示用户：
npx gitnexus analyze 刷新索引后再继续，或选择回退模式
GitNexus 可用时：步骤 1 全部用 GitNexus MCP 工具，grep 仅做补充验证。
GitNexus 不可用时：步骤 1 全部用原 grep/find 路径（已在步骤 1.1~1.6 中标注）。
Workflow
0. 既有文档探测（必跑 · 在任何扫描前）
目的：很多项目已经有 AI 可读的开发约定文档。不要直接覆盖或忽略，先问用户。
探测下面这些标准文档（按优先级）：
CONTEXT.md（仓库根 / .specs/）— flow-xAGENTS.md（仓库根）— OpenAI CodexCLAUDE.md（仓库根 / .claude/）— Anthropic.cursor/rules/*.md — Cursor.windsurf/rules/*.md — Windsurf.github/copilot-instructions.md — Copilot.clinerules — ClineARCHITECTURE.md（仓库根 / docs/）— 项目自定义CONTRIBUTING.md（仓库根）— 项目自定义README.md（仓库根）— 通用保底
三种分支：
分支 A · 找到至少一个标准 AI 上下文文档 → 反问用户：
-
- 综合+扫描（推荐）：读所有现有文档 + 跑入场扫描，合并生成 CONTEXT.md
-
- 以现有文档为准：选定一个作为基础 → 提取关键信息到 CONTEXT.md
-
- 忽略现有文档，重新扫描生成（警告：可能与现有约定冲突）
-
- 不生成
.specs/CONTEXT.md，改用指定文档作为 AI 遵守依据
分支 B · 找到非标准但项目级文档（README / ARCHITECTURE / CONTRIBUTING）→ 反问用户：
-
- 把它们当作扫描补充输入，生成完整 CONTEXT.md（推荐）
-
- 跳过这些，仅按代码扫描
-
- 用户指定其中一个作为开发遵守依据
分支 C · 一个文档都没有 → 反问用户（必须确认）：
-
- 现在跑入场扫描，纯从代码生成 CONTEXT.md（~15-30k tokens，仅首次）
-
- 手动指定项目里某个文档作为开发遵守依据
-
- 跳过 intel-scan，直接进 0-change（不推荐 · AI 会"盲飞"）
无论选哪个分支，扫描总结里必须贴出：
- 探测命中文档列表
- 用户选择（选项编号 + 简述）
- 决策（生成 CONTEXT.md / 以现有为准 / 跳过）
- 引用源（如有）
0.5. GitNexus MCP 可用性检测（必跑 · 在步骤 1 前）
尝试调用 gitnexus_impact（target 取项目入口文件名或主类名，direction="upstream"）：
在扫描总结里声明 GitNexus 使用状态。
1. 探测项目元信息
按下面顺序探测，记录每条发现（找不到也要记"未发现"）。
GitNexus 可用时，优先使用 MCP 工具；不可用时使用 grep 命令。
1.1 包管理与运行时
| 信号文件 | 提取信息 |
|---|
package.json | name / engines / 主要依赖 / scripts |
pyproject.toml / requirements.txt / Pipfile | Python 版本 / 主要依赖 |
Cargo.toml | Rust edition / 依赖 |
go.mod | Go 版本 / 主要依赖 |
pom.xml / build.gradle | Java 版本 / Spring / Maven |
composer.json | PHP 版本 / Laravel / Symfony |
Gemfile | Ruby / Rails 版本 |
1.2 框架检测
GitNexus 路径：调用 gitnexus_query 搜索框架关键词（如 "Spring Boot controller"、"React component"），从返回的 process_symbols 中提取框架特征。
grep 回退：探测 React / Vue / Svelte / Next / Nuxt / NestJS / FastAPI / Django / Spring Boot / Express 等。
1.3 关键约定
- 命名约定：
ls src/ 看目录命名风格
- import 风格：
grep "^import" 看 alias 用法
- 测试框架：jest / vitest / pytest 等
- Lint / Format：eslint / prettier / ruff 等
- CI 平台：GitHub Actions / GitLab CI 等
1.4 既有抽象层（关键 · 防重复实现）
GitNexus 路径（优先）：
对每类公共工具，调用 gitnexus_query 搜索对应概念：
- HTTP client：
gitnexus_query(query="HTTP request client", goal="find existing HTTP abstraction")
- 数据库访问：
gitnexus_query(query="database access repository DAO", goal="find existing data layer abstraction")
- 状态管理：
gitnexus_query(query="state management store", goal="find existing state abstraction")
- 错误处理：
gitnexus_query(query="error handling exception", goal="find existing error abstraction")
返回结果含 process_symbols（文件位置 + 模块归属），直接写入 CONTEXT.md「既有抽象索引」段。
grep 回退：
- HTTP client：
grep -rn "axios\|fetch\|httpClient\|apiClient" src/
- 数据库访问：
grep -rn "Repository\|DAO\|prisma\|sequelize" src/
- 状态管理：
grep -rn "createStore\|useStore\|atom" src/
- 工具函数：
find src -path '*utils*' -o -path '*helpers*'
- 自定义 hooks（前端）：
find src -name 'use*.ts*'
- 中间件：
find src -path '*middleware*'
- 错误处理：
grep -rn "class.*Error\|errorHandler\|ErrorBoundary" src/
1.5 数据库 schema
探测 Prisma / Alembic / Knex / Flyway / Liquibase / 裸 SQL 等工具及迁移目录。
1.6 API 路由映射
GitNexus 路径（优先）：调用 gitnexus_route_map 获取完整路由映射（含 handler 文件、middleware wrapper 链、消费者）。输出直接写入 CONTEXT.md「跨模块契约」段。
grep 回退：grep -rn "@Route\|@Controller\|@GetMapping\|@PostMapping" src/
1.7 模块/功能分区
GitNexus 路径（优先）：调用 gitnexus_cypher 查询社区/模块：
MATCH (c:Community) RETURN c.heuristicLabel, c.symbolCount, c.keywords, c.description
每个 Community 即一个功能分区，直接写入 CONTEXT.md「模块清单」段。
grep 回退：ls src/ + find src -type d -maxdepth 3
2. 生成 CONTEXT.md
用 references/CONTEXT.md 模板，填入第 1 步的发现。每个字段都要有具体证据（文件路径 + 行号）。
GitNexus 来源的证据格式：gitnexus://<tool>/<query> → <symbol>@<file>:<line>
grep 来源的证据格式：<file>:<line>
禁止填空话："使用了一些工具" / "标准结构"——都要换成具体的证据级引用。
3. 写 STATE.md
last_intel_scan: <YYYY-MM-DD>
context_file: .specs/CONTEXT.md
detected_stack: <主要技术栈一句话总结>
gitnexus_available: <true/false>
gitnexus_last_index: <日期，如可用>
4. 给用户一份扫描总结
## 入场扫描完成
**项目类型**：<前端 / 后端 / 全栈>
**主要技术栈**：<Next.js 14 + Prisma + Postgres>
**GitNexus MCP**：<可用 / 不可用 · 回退到 grep>
**关键发现**：
- HTTP 客户端：`src/lib/api-client.ts:1`（统一封装 axios）
- 工具函数：`src/utils/`（date / string / number 已有）
- 自定义 hooks：`src/hooks/`（22 个）
- Schema 工具：未检测到（裸 SQL 或还没用迁移工具）
- 测试覆盖：仅 `auth/` 目录有测试，其他模块裸奔
- 模块分区：<GitNexus Community 列表 / grep 目录列表>
**对后续 change 的影响**：
- 4-dev 阶段必须沿用既有 ApiClient（不要直接 fetch）
- 涉及 schema 改动 → 建议引入 Prisma 或 Knex（4-dev 1.7 会拦）
- 新增模块的 hooks 命名要参考现有 22 个的风格
- **GitNexus 可用时**：后续 flow-dev / flow-architect / flow-review 将自动使用 GitNexus MCP
`.specs/CONTEXT.md` 已生成。后续运行 0-change 时 AI 会自动加载。
Constraints
- 不动业务代码：本工作流仅写
.specs/ 内文件，禁动 src/
- 未经用户同意没自动开始扫描：分支 C 必须等用户回复 1/2/3
- 每个字段都要有证据：禁止"使用了一些工具"这类空话
- CONTEXT.md 长度建议 ≤ 300 行：超出时把陈旧条目归档到
.specs/archive/CONTEXT-history.md
- GitNexus 优先但非强制：GitNexus 可用时优先使用，不可用时回退到 grep。禁止在 GitNexus 不可用时阻塞扫描
- GitNexus 索引过期必须提示：不允许用过期索引产出结果而不告知用户
Validation
Resources
references/CONTEXT.md — 产出模板（项目共享上下文标准格式）- GitNexus MCP 工具：
gitnexus_query / gitnexus_impact / gitnexus_context / gitnexus_cypher / gitnexus_route_map
