open-mind

<div align="center"> # 开放思维 **将任何代码库转化为确定性、源可追溯的知识索引**，让你在下午而不是一个月内理解一个陌生的开源项目。 [](https://www.python.org/) [](LICENSE) [](#设计原则) [](#从编辑器或代理使用-MCP) [](#设计原则) </div> 开放思维读取代码仓库并构建持久化的**制品**，包括逐字词典、结构/依赖/调用图和精确令牌代码搜索，**每个事实都链接回其来源的精确`文件:行`**。它不会凭空捏造：未知术语会诚实地返回"未找到"，而不会猜测。相同的代码可以在单个模块库或17,000个文件的多语言大型代码仓库中运行，而无需为某个项目量身定制。 --- ## 目录 - [为什么存在](#为什么存在) - [功能](#功能) - [实际应用](#实际应用) - [项目结构](#项目结构) - [工作原理](#工作原理) - [在真实项目中查看](#在真实项目中查看) - [快速入门](#快速入门) - [从编辑器或代理使用（MCP）](#从编辑器或代理使用-MCP) - [能力，作为技能](#能力作为技能) - [配置](#配置) - [测试](#测试) - [设计原则](#设计原则) - [技术栈](#技术栈) - [路线图](#路线图) - [贡献](#贡献) - [许可证](#许可证) --- ## 为什么存在 开源是现代软件的构建方式，但在一个大型、陌生的代码仓库中提高生产力非常缓慢：你需要grep、猜测、多次阅读同一个文件，直到理解系统。LLM助手承诺提供帮助——而且经常做到——但它们也会**产生幻觉**：它们会自信地描述一个实际上并不存在于代码中的函数、API或缩写词。当你试图学习一个还不熟悉的系统时，一个自信的错误答案比没有答案更糟糕，因为你无法分辨哪个是哪个。 开放思维采取相反的立场。它将判断**从模型中转移到从真实代码构建的确定性制品**，然后让你导航它们： - **什么是"ISR"在这个项目中？** → 定义它的精确句子，带有其`文件:行`。 - **什么调用`SocketServer`，它依赖于什么？** → 真实的调用/依赖图。 - **在哪里处理重试-回退？** → 索引代码的精确令牌搜索。 相同的输入，相同的输出。没有任何内容是从空中产生的，不支持的声明被阻止。结果是一个可靠的、可导航的项目真实结构和词汇的地图——这是在你打开一个从未见过的代码仓库时希望存在的东西。 --- ## 功能 - **确定性词典** —— 术语和缩写定义直接从项目的权威来源中提取，每个定义都有`文件:行`出处、内容哈希和基础用法配置文件（定义位置、哪些文件引用它、相关术语）。 - **源可追溯图** —— 从真实代码中恢复的结构、依赖、调用和入口点流图；模糊的边被标记，而不是捏造；每个节点都链接到源。 - **精确令牌 + 混合搜索** —— 裸露的标识符作为精确令牌匹配（永远不是另一个符号的子字符串）；自然语言查询使用向量 + 词汇混合。 - **跨语言和规模的通用性** —— 检测-然后-适应设计；在Java、Scala、Go、Kotlin、TypeScript、JavaScript和Python上验证，从~1k到~17.5k个文件。 - **本地优先和审计** —— 项目内容永远不会离开机器；每个出站请求都经过策略检查和记录。 - **增量和幂等** —— 每个文件的哈希意味着未更改的文件永远不会被重新扫描或重新嵌入；重新运行在更新的检查点上只会影响更改的内容。 - **便携索引** —— 学习的数据存储只有仓库相对路径，因此可以复制到另一台机器上并仍然打开。 - **MCP原生** —— 每个功能都作为MCP工具暴露给编辑器或代理。 - **可选的本地LLM** —— 词典、图和精确令牌搜索是完全确定性的，不需要模型；本地模型只添加基础的、源引用的答案。 --- ## 实际应用 以下每个示例都是**真实的Apache Kafka源索引输出** —— 没有模拟，每个事实都带有其来源的`文件:行`。 ### 确定性词典，带有出处和用法配置文件 ```text ISR — "In-Sync Replicas" （缩写 · 逐字，不是生成的） 定义于 server/src/main/java/org/apache/kafka/server/partition/PartitionState.java:24 内容哈希 29122a12… （固定确切的源文本） 使用于 core/src/main/scala/kafka/cluster/Partition.scala 模块 core/…/cluster · server/…/partition ``` 定义是源代码中的确切文本；用法配置文件是从结构图中计算得出的。未知术语会诚实地返回**"没有权威定义找到"**，永远不会猜测。 ### 源可追溯代码图 Kafka真实**模块依赖图**的一个片段（边权重 = 恢复的引用数量）。它揭示了代码库的真实事实：线路协议模块`common/requests`是几乎所有内容依赖的中心枢纽。每个节点和边都来自静态分析——没有捏造。GitHub原生渲染它： ```mermaid flowchart LR admin["clients · admin/internals"] -->|1878| req["clients · common/requests"] ctrl["metadata · controller"] -->|1800| req persist["server-common · share/persister"] -->|1241| req group["group-coordinator · group"] -->|862| req consumer["clients · consumer/internals"] -->|745| req style req fill:#e8590c,stroke:#a63a00,color:#fff ``` *（节点标签从完整路径缩短；在应用程序中，点击一个节点会打开其真实源位置、调用者/被调用者和交叉链接的词典术语。）* ### 精确令牌代码搜索 裸露的标识符解析为其真实定义和用法站点——精确到令牌边界，永远不是另一个符号的子字符串： ```text 搜索 "ApiKeys" → clients/…/common/protocol/ApiKeys.java:47 enum ApiKeys 搜索 "ProducerConfig" → clients/…/clients/producer/ProducerConfig.java:54 class ProducerConfig 搜索 "RecordBatch" → clients/…/common/record/internal/RecordBatch.java:34 interface RecordBatch ``` > 想要一个现场演示？参见 [`docs/screenshots/`](docs/screenshots/) 获取如何从运行的应用程序中捕获词典、图和搜索截图的说明。 --- ## 项目结构 代码库组织成具有明确管道的小型、单一责任模块，功能打包为自包含、可调用的**技能**。（行数给出规模感；完整的验收测试位于 `tests/` 中。） ``` openmind/ │ ├─ 提取管道 ── 从任何代码仓库构建确定性索引 │ ├─ walker.py 选择感知文件系统遍历（.gitignore、排除、哈希） │ ├─ detect.py 阶段 1 · 项目检测（原型、语言、入口点） │ ├─ langspec.py 可扩展语言注册表 — “检测-然后-适应”的骨架 │ ├─ javaparse.py 树状分析语义解析（Java） │ ├─ structure.py 阶段 2 · 结构图：模块、定义、导入 + 调用图 │ ├─ glossary.py 确定性、逐字术语/缩写索引，带有出处 │ ├─ diagrams.py 阶段 3 · 结构派生 Mermaid / Graphviz / 心智图投影 │ ├─ rag.py 语义分块 + 混合精确令牌/向量检索 │ ├─ tokenmatch.py 精确令牌边界匹配（永远不是子字符串冲突） │ ├─ embeddings.py 本地嵌入（fastembed/ONNX，CPU 或 GPU）+ 离线哈希回退 │ └─ vectorstore.py Chroma 每个项目集合（+ 纯 numpy 回退） │ ├─ 功能作为技能 ── 可组合、独立调用的单元 │ ├─ router.py 代理式功能路由，带有确定性 if-else 底线 │ ├─ cases.py / 累积的“已解决案例” — 体验层 │ │ memory.py │ └─ wikienrich.py 审计维基百科丰富（外部定义，固定源 + 日期） │ ├─ 接口 ── 从浏览器、编辑器或代理使用 │ ├─ main.py FastAPI REST + SSE + 单页 UI │ ├─ mcp_server.py MCP stdio 服务器（搜索 · get_glossary · 路由 · 调度 · …） │ ├─ ask.py / 基础答案组装 — 严格源引用的，或“不在源中” │ │ conversation.py │ └─ static/index.html 零依赖网页 UI │ ├─ 本地优先和安全 ── 未审计的内容不会离开机器 │ ├─ netguard.py 出口防护 + 审计日志（默认仅环回） │ ├─ model_server.py 本地 llama-server 生命周期（附加或生成、健康、自动恢复） │ ├─ llm_client.py 本地 OpenAI 兼容客户端 │ ├─ resources.py RAM 管理器 — 长时间提取不会使机器冻结 │ └─ codemod.py 唯一写入路径：小型查找/替换，仅在测试保持绿色时保留 │ └─ 持久性和可移植性 ├─ db.py SQLite 注册表 / 作业 / 文件索引 / 案例（WAL，线程安全） ├─ machine.py 机器本地源根侧车 — 将`data/`保持无跟踪且可复制 ├─ jobs.py 可恢复、可重新连接的后台作业引擎 ├─ mapio.py 原子每个项目映射工件 I/O └─ config.py 中央配置 + 系统不变量 技能/ SKILL.md 功能单元（词典 · 代码图 · 功能路由器） .claude/skills/ wikipedia-glossary 技能 （SKILL.md + 脚本） tests/ verify_*.py 验收测试（确定性、反制造、异步删除、…） ``` 两个设计选择决定了其他一切： - **检测-然后-适应，而不是特定于架构。** `detect.py` + `langspec.py` 在导入时识别项目的语言和形状，因此结构图、词典和搜索适用于 Java 单体、Go 服务或 TypeScript 前端 — 无需每个仓库配置。 - **功能是技能。** 每个功能都是一个自包含的单元，记录在标准的 `SKILL.md` 格式下，位于 `skills/`，并作为 **MCP 工具** 暴露，以便在编辑器或代理中直接使用。 --- ## 工作原理 将开放思维指向代码仓库会运行一个可恢复的后台管道： 1. **遍历** — `walker.py` 选择可索引的文件，遵循 `.gitignore`、排除集和内置忽略；每个文件都经过内容哈希（增量键）。 2. **检测** — `detect.py` + `langspec.py` 识别语言、原型和入口点。 3. **结构** — `structure.py` 通过确定性静态分析恢复模块树、每个文件的定义索引和导入 + 调用图（Java 使用 tree-sitter）。 4. **词典** — `glossary.py` 提取带有出处的逐字术语/缩写定义。 5. **图表** — `diagrams.py` 将结构图投影为 Mermaid / DOT / 心智图视图。 6. **索引** — `rag.py` 将代码语义分块并将嵌入存储在 Chroma 中，用于精确令牌 + 混合检索。 7. **丰富（可选，审计）** — `wikienrich.py` 将权威的外部定义附加到已知术语作为单独的、属性字段（源 + 时间戳），永远不会替换项目内的文本。 每个阶段都由每个文件的哈希值索引，因此在更新的检查点上重新运行只会影响实际更改的内容。 --- ## 在真实项目中查看 以下是运行在三个不同大小和语言多样性的开源代码仓库上的相同管道，无需每个项目调整： | 项目 | 语言 | 索引文件 | 定义 | 调用边 | 模块 | |---|---|--:|--:|--:|--:| | **Apache ZooKeeper** | Java, JS, TS, Python | 1,182 | 2,260 | 7,778 | 160 | | **Apache Kafka** | Java, Scala, Python | 6,560 | 14,363 | 164,260 | 767 | | **OpenClaw** | Go, Kotlin, TS, JS, Python | 17,515 | 128,141 | 675,310 | 736 | 最大的代码库是一个 ~17.5k 文件、五语言代码库，拥有 **675,000** 个恢复的调用边，通过与处理 1,182 文件的项目相同的确定性传递构建。 --- ## 快速入门 **先决条件：** Python 3.12+（Windows / macOS / Linux）。无需设置数据库或外部服务 — 存储为本地文件。可选的本地 LLM。 ```powershell git clone <你的分叉网址> open-mind cd open-mind pip install -r requirements.txt # Web UI + REST API on http://127.0.0.1:8077 ./run.ps1 # Windows # 或，跨平台： python -m uvicorn openmind.main:app --host 127.0.0.1 --port 8077 ``` 打开 http://127.0.0.1:8077，将其指向本地代码仓库，让它学习，然后浏览 **词典** 和 **图表** 选项卡以及搜索框。词典、图表和精确令牌搜索是完全确定性的，不需要模型。 > **GPU 嵌入（可选，全部本地）。** 大型代码仓库索引在 GPU 上更快。在 Windows AMD/Intel 上：`pip uninstall onnxruntime && pip install onnxruntime-directml`； 在 NVIDIA 上：`onnxruntime-gpu`。开放思维会自动选择设备，默认情况下会暂时释放其自己的托管模型服务器的 VRAM 以进行嵌入传递，以便两者永远不会竞争（参见 [配置](#配置)）。 --- ## 从编辑器或代理使用（MCP） 开放思维附带一个 MCP stdio 服务器，因此相同的功能可用于任何MCP客户端（编辑器、代理、CLI）： ```bash python -m openmind.mcp_server ``` 注册它（客户端配置可能有所不同）： ```json { "mcpServers": { "open-mind": { "command": "python", "args": ["-m", "openmind.mcp_server"] } } } ``` 暴露的工具：`search`, `get_glossary`, `route`, `dispatch`, `find_similar_cases`, `save_case`, `propose_fix`, `apply_fix`. --- ## 能力，作为技能 每个功能都小巧、独立、可测试，并且有两种调用方式 — 通过 REST（网页 UI）或作为 **MCP 工具** — 遵循一个原则：**确定性、源可追溯、非捏造**。 | 技能 | 功能 | 确定性 | |---|---|---| | [`glossary`](skills/glossary/SKILL.md) | 逐字术语索引 + 基础用法配置文件 | 完全确定性 | | [`code-graphs`](skills/code-graphs/SKILL.md) | 从真实代码中恢复的结构/依赖/调用/流程图 | 完全确定性 | | [`capability-router`](skills/capability-router/SKILL.md) | 将请求路由到正确的能力 | 模型辅助，具有确定性底线 | | [`wikipedia-glossary`](.claude/skills/wikipedia-glossary/SKILL.md) | 权威的外部定义，固定源 + 时间戳 | 确定性写回；出口审计 | **路由器** 显示了模型在整个过程中的使用方式：确定性 if-else 分类器始终首先决定；当本地模型可用时，它可能会完善选择，但其答案必须**验证**以确保与已知功能集一致，并且只有在有效时才接受 — 不可用或规范外的模型会静默降级为确定性规则。模型在可靠的地方提供帮助；行为永远不会**依赖**于它是否正确。 --- ## 配置 一切开箱即用；这些环境变量可以调整它。无需任何变量即可正常工作。 | 变量 | 默认值 | 用途 | |---|---|---| | `OPENMIND_DATA_DIR` | `./data` | 学习索引存储位置（SQLite + Chroma + 地图文件）。 | | `OPENMIND_MACHINE_DIR` | `~/.openmind` | 机器本地侧车，保存每个项目的绝对源根目录（存储在 `data/` 之外，以便索引可移植）。 | | `OPENMIND_EMBED_DEVICE` | `smart` | `cpu` · `smart`（GPU 免费时使用 GPU，否则使用 CPU）· `auto`（如果可用，则始终使用 GPU）· `gpu`。 | | `OPENMIND_INGEST_FREE_GPU` | `1` | 在嵌入传递期间，暂时停止托管模型服务器以释放 VRAM，然后重新启动。 | | `OPENMIND_EMBED_OFFLINE` | `0` | `1` 强制确定性哈希嵌入器（无需模型下载）。 | | `OPENMIND_ENRICH_EGRESS` | `1` | `0` 禁用审计的维基百科丰富查找（完全离线）。 | --- ## 测试 验收测试断言最重要的契约 — 确定性、反造假和并发边缘情况 — 大多数测试无需重依赖项即可运行： ```bash python tests/verify_glossary.py # 逐字定义、出处、诚实的“未找到” python tests/verify_structure.py # 确定性结构图 + 增量维护 python tests/verify_diagrams.py # 图表有效 + 诚实为空 python tests/verify_router.py # 路由底线 + 模型降级 python tests/verify_resources.py # RAM 管理器不会冻结机器 python tests/verify_async_delete.py # 删除即时 + 绝不复活清理过程中的项目 ``` --- ## 设计原则 - **确定性和非捏造。** 定义直接从源代码中提取；图表从真实定义/导入/调用中恢复；模糊性被标记，而不是捏造；缺失的事实返回“未找到”。代码中的防护措施得到强制执行，而不仅仅是断言。 - **本地优先和审计。** 项目内容永远不会离开机器。模型调用仅发送到本地服务器，固定在环回地址；每个出站请求都经过策略检查和记录（`netguard`）。（有一个可选的、审计的例外，获取公共参考定义 — 仅限单个术语，从不项目源代码。） - **先验证再信任。** 单一代码写入路径（`codemod`）仅在项目的自身测试套件保持绿色时应用更改；模型永远不会决定正确性，测试来决定。 - **通用。** 检测-然后-适应（`detect` + `langspec`）— 在不同语言和架构上工作，无需每个仓库配置。 - **可移植。** 学习的数据存储只有仓库相对路径；绝对源根目录存储在 `data/` 之外的机器本地侧车中，因此索引可以复制到另一台机器上并仍然打开。 --- ## 技术栈 Python 3.12 · FastAPI + Uvicorn（REST/SSE）· 零依赖单页 UI · tree-sitter（语义解析）· ChromaDB + fastembed/ONNX（本地嵌入，具有纯 Python 回退）· SQLite（WAL）· 模型上下文协议（MCP）· 可选的本地 `llama-server`。 --- ## 路線圖 开放思维是一个索引优先；长期目标是让任何陌生的代码库感觉**已经理解** — 更丰富的跨项目链接、更深入的流程级视图，以及更多符合相同规则的能力技能，**显示给用户真实的代码，而不是似是而非的虚构**。 --- ## 贡献 欢迎提出问题和拉取请求。一个好的变更保持项目的核心承诺完整： - 新事实必须**可追溯到源**，而非捏造；优先使用确定性提取而不是模型生成。 - 保持功能**自包含且可测试**；添加一个 `verify_*.py` 验收测试。 - 保持**本地优先**：没有新的出站网络路径通过 `netguard`。 --- ## 许可证 在 [MIT 许可证](LICENSE) 下发布。