adu3110/flowIndex

# FlowIndex [](https://github.com/adu3110/flowIndex/actions/workflows/ci.yml) [](https://pypi.org/project/flowindex/) [](LICENSE) 为 AI 编码 agent 打造的行为优先代码库索引。 FlowIndex 映射了代码库的行为方式：entrypoint、调用路径、测试、runtime 追踪以及 git 历史记录。它帮助 AI 编码 agent 在修改代码前了解潜在影响。 大多数编码 agent 工具主要索引文件、代码块、符号或 embedding。而 FlowIndex 索引的是行为。 它可以回答如下问题： - 哪段代码路径负责处理这个功能？ - 如果我修改了这个函数，什么会出错？ - 针对这个 patch 应该运行哪些测试？ - 之前的哪些 bug 修复涉及到了这块代码？ - 在进行修改前，agent 应该接收的最小上下文是什么？ ## 为什么行为优先？ 文件树和 embedding 搜索只能告诉你*存在*什么。它们无法告诉你当你修改一个共享模块时，什么会*运行*、什么会*出错*，或者什么*至关重要*。 FlowIndex 构建了一个本地、确定性的行为图谱： - **Entrypoint** — API 路由、webhook、页面、CLI 命令 - **调用路径** — 通过静态分析获取的函数间关系 - **测试** — pytest、Jest/Vitest 检测并与符号关联 - **Git 历史** — 共同变更模式和 bug 修复提交信号 - **影响** — 在修改前提供透明的风险评估 无需向量数据库。无需 LLM 调用。无需 SaaS。使用可检查的 SQLite。 ## 与众不同之处 | 方法 | FlowIndex | |----------|-----------| | 代码库映射 / 文件树 | 包含 entrypoint 和调用边的行为图谱 | | Embedding / RAG | 确定性的词法 + 图谱排序 | | Agent 框架 | 为 agent 提供上下文的开发者工具 | | 通用静态分析 | 面向 agent 的影响分析、测试关联、上下文包 | ## 安装说明 ``` pip install flowindex ``` 支持 Cursor / Claude Code 的 MCP： ``` pip install "flowindex[mcp]" ``` 从源码安装： ``` git clone https://github.com/adu3110/flowIndex.git cd flowIndex pip install -e ".[dev]" ``` ## 快速入门 ``` cd your-project flowindex init # use --here inside nested example dirs flowindex scan flowindex overview flowindex explain "POST /api/payments" flowindex impact src/services/ledger.py flowindex tests-for update_ledger flowindex context "fix duplicate payments when webhook retries" ``` ### 演示 ``` cd examples/python_fastapi_app flowindex init --here flowindex scan flowindex context "fix duplicate payments when webhook retries" ``` ## CLI 示例 ``` # 在当前 repo 中初始化 index flowindex init # 扫描并构建 behavior graph flowindex scan # 解释 entrypoint flow flowindex explain "POST /payments" # 分析变更影响 flowindex impact services/ledger.py # 为变更建议测试 flowindex tests-for services/ledger.py # 生成 agent context pack flowindex context "fix webhook retry duplicate ledger entries" ``` ## MCP 使用方法 (Cursor) 将其添加到 Cursor MCP 设置中（`~/.cursor/mcp.json` 或项目设置）： ``` { "mcpServers": { "flowindex": { "command": "flowindex", "args": ["mcp"], "cwd": "/absolute/path/to/your/repo" } } } ``` 首先在该代码库中运行 `flowindex init && flowindex scan`。 手动启动 server： ``` flowindex mcp ``` 工具：`get_repo_overview`、`explain_entrypoint`、`get_change_impact`、`suggest_tests`、`make_context_pack` 等 — 详见 [docs/mcp.md](docs/mcp.md)。 ## 架构 ``` flowchart LR subgraph ingest [Ingest] Scan[File Scanner] Py[Python Parser] TS[TS/JS Parser] Git[Git Analyzer] end subgraph index [Local Index] DB[(SQLite)] Graph[Behavior Graph] end subgraph out [Outputs] CLI[CLI Commands] MCP[MCP Server] Pack[Context Packs] end Scan --> Py Scan --> TS Py --> Graph TS --> Graph Git --> Graph Graph --> DB DB --> CLI DB --> MCP DB --> Pack ``` ## 上下文包示例 ``` flowindex context "fix duplicate payments when webhook retries" ``` ``` # FlowIndex Context Pack ## 任务 fix duplicate payments when webhook retries ## 可能的 Relevant Entrypoints - POST /payments - POST /stripe/webhook ## 可能的 Relevant Files - main.py - services/ledger.py - services/payments.py ## 高风险 Symbols - update_ledger() - handle_stripe_webhook() ## 要运行的测试 - tests/test_payments.py ## 注意事项 - services/ledger.py has high change risk. - update_ledger() is shared by refunds and payments. ``` ## 路线图 - [ ] 针对 TS/JS 的 Tree-sitter 解析器以及更丰富的调用解析 - [ ] Runtime 追踪摄取（OpenTelemetry、测试覆盖率） - [ ] 跨代码库依赖索引 - [ ] 感知 patch 的增量扫描 - [ ] 语言服务器：Go、Rust、Java ## 研究问题 - 与 embedding 相比，行为图谱能减少多少 agent 的错误？ - 保持 patch 正确性的最小上下文包大小是多少？ - 共同变更图谱是否比仅靠 import 图谱更能准确地预测测试选择？ - 哪些 entrypoint 类别与生产环境故障的相关性最高？ ## 贡献指南 1. Fork 并克隆代码库 2. `pip install -e ".[dev]"` 3. 带着测试进行修改 4. `ruff check . && mypy flowindex && pytest` 5. 发起 pull request 有关概念、CLI 参考和示例，请参阅 [docs/](docs/)。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AI编程助手, MCP, SOC Prime, 上下文管理, 云安全监控, 代码索引, 开发工具, 逆向工具, 静态分析