clay-good/OpenLore

# openlore **为 AI 编程代理提供持久的架构记忆和结构化认知。** openlore 将任何不断演进的代码库转化为可导航的知识图谱，并由 [OpenSpec](https://github.com/Fission-AI/OpenSpec) 的活跃规范提供支持。它跨代理会话维护持久的架构上下文：图谱结构、规范、决策、漂移状态和语义检索——因此代理在开始每项任务时已经明确了方向，无需再通过读取文件来重新探索系统。 ## 为什么需要它 AI 代理虽然强大，但患有“健忘症”。在处理每个新任务时： - 它们会重新读取相同的源文件以理解结构 - 它们会忘记两个会话前做出的架构决策 - 它们的规范与代码之间没有联系——漂移是无形的 - 基于文件的导航通常在一次定位过程中就会消耗 **15,000–50,000 个 token**，而这还是在编写一行有用代码之前 openlore 闭合了这个循环。运行一次完整分析，然后随着代码库的演进保持图谱增量更新。即使是从零开始的项目，在经历几次代理会话后也会在认知上变成“成熟项目”——架构上下文变得碎片化、决策消失，代理不得不反复从零开始重构相同的理解。 openlore 持续地持久化这些上下文：结构、规范、决策、漂移状态和图谱关系在跨会话中始终保持可查询状态。 ## 工作原理 三层架构，每层均可独立使用： | 层级 | 功能 | 需要 API key? | |-------|-------------|----------| | **1. 静态分析** | 调用图、集群、McCabe CC、外部依赖 → `CODEBASE.md` 摘要 | 否 | | **2. 规范层** | LLM 生成的活跃规范、ADR、漂移检测、决策门 | 生成时需要 | | **3. 代理运行时** | 45 个 MCP 工具 —— `orient()`、语义搜索、图谱扩展 | 否 | 你可以仅使用第 1 层来为代理提供结构化上下文。添加第 2 层可通过兼容 OpenSpec 的活跃规范提供语义意图和架构治理。一旦运行 `openlore mcp`，第 3 层即可通过原生图谱 MCP 工具保持该上下文持续可访问。 ## openlore 与其他替代方案对比 | | Cursor / Claude Code | Sourcegraph | openlore | |---|---|---|---| | 图感知 MCP 上下文 | ❌ 基于文件读取 | 部分支持 | ✓ 调用图 + 集群 | | 规范漂移检测 | ❌ | ❌ | ✓ 毫秒级，无需 API | | 架构决策门 | ❌ | ❌ | ✓ pre-commit 钩子 | | 离线结构分析 | ❌ | ❌ | ✓ | | 高效 token 的 orient() | ❌ | ❌ | ✓ 约 1–3k vs 15–50k tokens | | 活跃规范生成 | ❌ | ❌ | ✓ | | 跨会话持久架构记忆 | ❌ | 部分支持 | ✓ | 传统编程代理在每次会话中都会通过重复读取文件来重构架构。openlore 则将其持久化为可查询的图谱。 ## 5 分钟快速入门 ``` npm install -g openlore cd /path/to/your-project openlore analyze # build call graph, clusters, CODEBASE.md openlore mcp # start MCP server ``` 然后向你的代理发出指令：**`orient("add a new payment method")`** 仅此一次调用就会返回相关的函数、它们的调用邻居、匹配的规范部分以及插入点候选——在跨会话中保持架构连贯性，而不是强迫代理从原始文件读取中反复重构上下文。在实践中，这通常会将定位开销从约 30,000 个探索性 token 减少到约 1,000 个针对性 token。 **完整流程**（规范 + 决策 —— 可选且为增量式）： ``` openlore generate # generate living specs (requires API key) openlore drift # detect spec/code drift openlore decisions # manage architectural decisions ```

从源码安装

``` git clone https://github.com/clay-good/openlore cd openlore npm install && npm run build && npm link ```

Nix / NixOS

``` nix run github:clay-good/openlore -- analyze nix shell github:clay-good/openlore ``` 系统 flake： ``` environment.systemPackages = [ openlore.packages.x86_64-linux.default ]; ```

## 实战演示

示例: orient("add a payment method")

``` { "functions": [ { "name": "processPayment", "file": "src/payments/processor.ts", "risk": "medium", "fanIn": 4, "callers": ["handleCheckout", "retryFailedCharge"], "callType": "direct" }, { "name": "validateCard", "file": "src/payments/validator.ts", "risk": "low", "fanIn": 1, "testedBy": [{ "name": "validateCard.test.ts", "confidence": "called" }] } ], "specDomains": ["payments — §CardValidation, §PaymentFlow"], "insertionPoints": [ "src/payments/processor.ts:87 — after existing charge logic" ], "callPath": "POST /charge → handleCheckout → processPayment → validateCard → stripeClient.charge" } ``` 一次图谱查询替代了大部分探索性的文件读取。代理确切地知道在哪里查找以及需要考虑哪些风险。

## 核心特性 **Analyze** (无需 API key) 使用纯静态分析持续维护代码库的结构化表示。构建完整的调用图并持久化至 SQLite，运行标签传播社区检测以聚类紧密耦合的函数，计算每个函数的 McCabe 圈复杂度，并提取 DB 模式、HTTP 路由、UI 组件、中间件链和环境变量。输出 `.openlore/analysis/CODEBASE.md`——一个约 600 个 token 的结构化摘要，将相当于数万个探索性 token 的内容压缩为一个小巧且可查询的总结。 使用 `--watch-auto` 时，调用图会在每次文件保存时增量更新：重新解析更改的文件及其直接调用者，并自动替换图。在完整的 analyze 运行之间，Orient 和 BFS 查询可保持实时生效。 **Generate** (需要 API key) 将分析结果分 6 个结构化阶段发送给 LLM：项目调查 → 实体提取 → 服务分析 → API 提取 → 架构综合 → ADR 丰富化。以 RFC 2119 格式生成 `openspec/specs/` 活跃规范，包含 Given/When/Then 场景。 **Drift** (无需 API key) 在毫秒级时间内比较 git 更改与规范映射。检测：Gap（代码更改，规范未更新）、Uncovered（新文件，无规范）、Stale（规范引用了已删除的文件）、ADR gap（代码在 ADR 引用的域中发生了更改）。可作为 pre-commit 钩子安装。 **MCP** (无需 API key) 通过 stdio 暴露 45 个原生图谱工具。它们共同构成了编码代理的持久架构运行时：定位、图遍历、语义检索、漂移感知、决策上下文和结构性风险分析。 `orient()` 是主要的入口点——一次调用即可替代 10 次以上的文件读取。`detect_changes` 使用调用图中心度 × 变更类型乘数对更改的函数进行风险评分。参见 [docs/mcp-tools.md](docs/mcp-tools.md)。 `orient()` 在一个 15k 节点（TypeScript 编译器，约 79k 条边）的代码库上运行 **p50 耗时约 430µs**。完整基准测试结果：[scripts/BENCHMARKS.md](scripts/BENCHMARKS.md)。 **Decisions** (整合时需要 API key) 代理在编写代码前调用 `record_decision`。整合会在后台立即运行。在提交时，pre-commit 钩子会阻止提交，直到所有经过验证的决策都被审查并作为需求回写到 `spec.md` 文件中。决策按范围（`local / component / cross-domain / system`）分类；只有 `cross-domain` 和 `system` 决策会生成 ADR 文件，从而保持决策日志的高信噪比。 ## 架构 OpenSpec 提供语义意图和工作流结构。openlore 将不断演进的实现维护为供代理使用的、持续可查询的架构图。 ``` Codebase │ ▼ openlore analyze ──► SQLite graph store (.openlore/analysis/call-graph.db) │ │ │ MCP tools (orient, BFS, search…) │ │ Artifact Generator Agent │ ┌─────┴──────┐ ▼ ▼ CODEBASE.md (optional) openlore generate ──► openspec/specs/*.md openlore drift ──► drift report openlore decisions ► ADR gates ``` 图谱与 OpenSpec 规范层是同等的：图谱使定位变得快速，规范使其具备语义基础。漂移检测和决策门将两者连接起来。完整流程图请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 文档 | 主题 | 文档 | |-------|-----| | MCP 工具参考（45 个工具 + 参数） | [docs/mcp-tools.md](docs/mcp-tools.md) | | 代理设置 (Claude Code, Cline, OpenCode, Vibe…) | [docs/agent-setup.md](docs/agent-setup.md) | | LLM 提供商 + embedding 配置 | [docs/providers.md](docs/providers.md) | | 深入了解漂移检测 | [docs/drift-detection.md](docs/drift-detection.md) | | 规范驱动测试 + 规范摘要 | [docs/spec-tests.md](docs/spec-tests.md) | | CI/CD 集成 | [docs/ci-cd.md](docs/ci-cd.md) | | CLI 命令参考 | [docs/cli-reference.md](docs/cli-reference.md) | | 交互式图谱查看器 | [docs/viewer.md](docs/viewer.md) | | 分析输出文件 | [docs/output.md](docs/output.md) | | 配置参考 | [docs/configuration.md](docs/configuration.md) | | 编程式 API | [docs/api.md](docs/api.md) | | Pipeline 架构 | [docs/pipeline.md](docs/pipeline.md) | | 内部设计 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | | 算法 | [docs/ALGORITHMS.md](docs/ALGORITHMS.md) | | 代理工作流 (BMAD, Vibe, GSD, spec-kit) | [docs/agentic-workflows.md](docs/agentic-workflows.md) | | 故障排除 | [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | | 理念 | [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md) | ## 已知限制 - **增量调用图更新仅为深度 1**：`--watch-auto` 在保存时仅重新索引更改文件及其直接调用者的签名和边。传递调用者（A→B→C，C 发生更改，A 保持陈旧）只能在下一次 `analyze --force` 时刷新。对于具有 100 个以上 callerFiles 的核心文件，重新解析可能需要几秒钟。 - **仅支持静态分析**：动态分发、运行时元编程和基于 `eval` 的模式不会被捕获在调用图中。 - **LLM 规范质量参差不齐**：生成的规范反映了模型的理解。在将涵盖复杂业务逻辑的部分视为权威之前，请先进行审查。 - **Embedding 是可选的**：如果没有 embedding 端点，`orient` 和 `search_code` 将回退到 BM25 关键字搜索（仍然有用，但对语义查询的准确性较低）。 - **大型单体仓库**：在大型代码库上运行 `openlore analyze` 可能需要几分钟。图谱存储本身没有实际限制——瓶颈在于流水线（AST 解析、符号提取）。 - **Node 22 上的 `node:sqlite` 实验性警告**：Node.js 22 会向 stderr 打印 `ExperimentalWarning: SQLite is an experimental feature`。此警告在 Node 24+ 上已消失。在 Node 22 上可使用 `NODE_NO_WARNINGS=1 openlore analyze` 抑制。 ## 环境要求 - Node.js 22.5+ - `generate`、`verify` 和 `drift --use-llm` 需要 API key： export ANTHROPIC_API_KEY=sk-ant-... # 默认提供商 export OPENAI_API_KEY=sk-... # OpenAI export GEMINI_API_KEY=... # Google Gemini 或使用基于 CLI 的提供商（`claude-code`、`gemini-cli`、`mistral-vibe`、`cursor-agent`）——不需要 API key，只需 CLI 在你的 PATH 中。 - `analyze`、`drift`、`mcp` 和 `init` 不需要 API key **支持的语言**：TypeScript · JavaScript · Python · Go · Rust · Ruby · Java · C++ · Swift ## 开发 ``` npm install npm run build npm test # 2660+ unit tests npm run typecheck ``` ## 链接 - [OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规范驱动开发框架 - [AGENTS.md](AGENTS.md) — 用于直接 LLM 提示的系统提示词 - [示例](examples/) — BMAD, Vibe, GSD, drift-demo, spec-kit 集成

标签：ADR, AI编程助手, DLL 劫持, LLM, MCP工具, MITM代理, OpenSpec, Unmanaged PE, 上下文管理, 业务逻辑提取, 云安全监控, 云资产清单, 代码分析, 代码图谱, 代码导航, 代码库管理, 代码理解, 企业架构, 凭证管理, 大语言模型, 威胁情报, 开发者工具, 开源, 开源框架, 技术债务, 持续集成, 数据管道, 文档自动化, 架构决策记录, 架构治理, 活文档, 漂移检测, 系统认知, 网络调试, 自动化, 自动化攻击, 规范生成, 语义搜索, 软件工程, 软件架构, 逆向工程, 静态分析