HelloThisWorld/open-mind

[](https://github.com/HelloThisWorld/open-mind/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) [](#use-it-from-an-agent-mcp) [](#verification-first-design) [](#measured-skill-verification) [](#local-first-boundary) [](https://github.com/HelloThisWorld/agent-skill-verification-template) Open Mind 的构建围绕着一个实用的 agent 工程问题： 与其要求模型从零开始“理解”一个代码库，Open Mind 从代码本身构建持久化的 artifact。模型、编辑器或 agent 然后 查询这些 artifact。如果代码库不支持某个声明，Open Mind 更倾向于精确的“未找到”，而不是看似合理的幻觉。 相关项目： - [Open Mind](https://github.com/HelloThisWorld/open-mind)：生成可溯源的代码库 artifact - [open-mind-mcp-server](https://github.com/HelloThisWorld/open-mind-mcp-server)：将这些 artifact 作为 MCP 工具暴露给 agent - [agent-skill-verification-template](https://github.com/HelloThisWorld/agent-skill-verification-template)：使用评估、指标、追踪和重放 artifact 测试 agent 技能/工具 ## 实际项目演示 下面的截图来自运行中的 Open Mind UI，针对的是已索引的 ZooKeeper 代码库。它们展示了已实现的产品界面：基于源码的 词汇表条目和基于结构衍生出的图导航。 | 带有溯源信息的原样词汇表 | 基于源码的图节点详情 | |---|---| |  |  | ## 为什么选择 Open Mind 大型代码库对于人类来说很难学习，而对于 LLM 来说却很容易 误报。一个编码助手可能会自信地编造一个缩写展开， 画出不存在的架构边界，或者基于一个仅仅是作为子字符串匹配到的 符号推荐修改。 Open Mind 采取了相反的方法： - **证据优于流畅度** - 重要的回答基于源文件、 行号、行范围或明确的“未找到”响应。 - **生成前先确定** - 词汇表提取、结构映射、 token 匹配、路由默认值和图投影都是确定性的。 - **将 agent 上下文作为基础设施** - 代码库成为 AI agent、Claude Skills 风格的工作流、编辑器和 更安全的 AI 辅助开发的可查询知识层。 - **有用的省略优于幻觉** - 不支持的术语和未解析的 图边不会被模型填充。 这就是项目的论点： ## 它构建了什么 将 Open Mind 指向本地代码库，它会构建持久化的 artifact： | Artifact | 已实现的行为 | |---|---| | **可溯源的知识索引** | 存储 repo 相对路径、内容哈希、源码位置、文件元数据和搜索块。 | | **原样词汇表** | 从定义表、定义行、缩写展开和代码注释中提取术语/缩写；定义原样复制，并携带 `source_file`、`line_number` 和 `content_hash`。交互式学习路径会扫描代码/配置源；`.openmind` 导出过程还会扫描 README/docs/GLOSSARY 文件（主要的定义来源）。 | | **结构和图映射** | 构建模块树、文件级定义索引、import/dependency 图、入口点以及基于名称的调用/使用图。有歧义的调用边会被标记出来，而不是靠猜。 | | **精确 token + 混合搜索** | 裸标识符使用 token 边界匹配；自然语言查询使用向量 + 词法检索。 | | **有据可查的提问 (Ask) 上下文** | 从词汇表命中、检索到的代码、已解决的案例、先前的对话上下文和用户附件中组装带编号的来源，供本地模型回答。 | | **已保存的解决案例** | 让有用的提问交流成为可搜索的案例；被引用的文件稍后会进行哈希检查，如果代码更改，则标记为过期。 | | **Agent 工具接口** | 通过 MCP stdio server 暴露核心查询、路由、案例和受限修复工具。 | | **可移植的 artifact 导出** | 导出带有版本的 `.openmind` 目录（manifest + glossary, architecture, flows, source index — 都带有 `file:line` 证据），作为外部消费者（例如配套的 MCP server）的稳定契约。 | | **模板配置** | 声明式的 YAML/JSON “透镜”文件，用于描述技术栈（内置的 `generic`, `spring-boot`, `rails`, `django`, `express-nestjs` 位于 `openmind/templates/` 中；将你自己的配置放入 `/templates/` — 相同的 schema，用户文件按名称优先）。一个 schema gate 会列出无效文件及其错误；确定性的技术栈检测会在学习时对配置进行评分，并记录每个项目的获胜者及其匹配的证据（`GET /templates`, `GET/POST /projects/{id}/template`）。解析后的配置随后将文件分类为逻辑 **角色**（controller/service/repository/…），并捕获 **切面** — 原样正则表达式事实，例如 HTTP 路由路径或 Kafka topic 文本，每个都带有 `file:line:snippet` 证据 — 在学习时持久化，通过 `/structure`（层摘要）和 `/graph`（每个节点的角色 + 事实）呈现，并投影到 `.openmind` 导出中。没有解析到模板 -> 行为和输出保持不变。 | | **模板学习指南** | 在每次学习后将解析后的配置的 `guide` 大纲渲染成 markdown 页面（`GET /docs`, `GET /docs/{page}`, MCP `get_doc`；通过 `POST /gendocs` 重新生成）。每个部分都是对已学习映射的一个确定性查询（概述 / 层 / 入口点 / 流 / 切面 / 词汇表 / 模块）；每个事实都引用了 `file:line`，空部分会如实说明，重新生成是字节相同的，并且每页的 `OPENMIND:NOTES` 块在重建过程中保留人类注释。没有指南 -> 文档界面保持为一个诚实的空壳。 | | **测试门控的代码修改路径** | 提供了一个狭窄的原样查找/替换路径：预览 diff，要求绿色的基准测试，应用，重新运行测试，并在测试失败时回滚。 | 这**不是**什么：一个完整的编译器、类型检查器、IDE 扩展或自由形式的 自主编码 agent。它是此类 agent 可以调用的基于源码的上下文和验证层。 ## 为 AI Agent 工作流而生 Open Mind 被设计为实用 AI agent 和工具 集成的基础设施： - **代码库上手** - 快速检查词汇表术语、模块、入口 点、依赖项、调用者和被调用者。 - **上下文工程** - 为 agent 提供持久的代码库上下文，而不是 依赖冗长的 prompt。 - **代码库 Q&A 溯源** - 为本地 LLM 组装带有源码编号的上下文， 词汇表问题首先通过确定性查找进行路由。 - **架构发现** - 检查从结构衍生出的模块、依赖项、 调用和入口点，无需模型推断的架构图。 - **变更影响探索** - 在编辑之前检查基于名称的调用者/被调用者邻域 以及相关的词汇表术语。 - **工具使用验证** - 使用受限的 MCP 工具，如 `propose_fix` 和 `apply_fix`，由测试决定是否保留更改。 - **更安全的 AI 辅助开发** - 优先考虑源码证据、明确的 不确定性，以及可重复的 artifact，而不是一次性的生成摘要。 这与 AI Agent、Claude Skills、工具集成、 上下文工程、验证 pipeline、系统设计以及可靠的 软件开发直接相关。 ## 验证优先设计 Open Mind 将歧义视为风险信号： - **词汇表定义是原样的。** 它们永远不会被模型总结或重写。 如果某个术语不存在，查找将返回 `found: false`。 - **源码位置是一等公民。** 词汇表条目带有 `file:line`； 搜索块带有行范围；图节点细节暴露了源文件、 定义、调用者、被调用者和相关术语。 - **图是由源码衍生而来的。** 依赖和调用/使用图来自于 确定性的静态分析。调用图是基于名称的，因此有歧义的 符号目标会被标记为 `ambiguous`。 - **精确的 token 保持精确。** `ack` 不匹配 `acked`；`user` 不 匹配 `userId`；`service1` 不匹配 `service10`。 - **路由具有确定性的基础。** 可选的本地模型可以细化 能力选择，但前提是它必须返回有效的能力。否则，将采用 确定性的路由器。 - **代码编写是门控的。** codemod 路径是单文件原样的查找/替换， 带有 diff 预览和测试门控的应用/回滚行为。 本地模型很有用，但它不被信任为事实来源。源码 artifact 才是事实来源。 ## 实际运行 ### 原样词汇表查找 一个明确的缩写问题会路由到词汇表映射，而不是相似性搜索： ``` query: "what does ISR mean?" { "found": true, "term": "ISR", "definition": "In-Sync Replicas", "source_file": "server/src/main/java/org/apache/kafka/server/partition/PartitionState.java", "line_number": 24, "source_kind": "acronym", "content_hash": "29122a12..." } ``` 不支持的术语是一个诚实的未命中： ``` query: "what does ZKQ mean?" { "found": false, "term": "ZKQ", "message": "no authoritative definition found for 'ZKQ' in the indexed project" } ``` ### 源码衍生出的图 图视图是结构 artifact 的投影，而不是模型生成的 架构猜测。下面的例子展示了模块聚合的输出形状； 边权重是从索引检出中恢复的引用计数， 而不是基准测试声明： ``` 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 ``` 在 UI 中，单击图节点会打开源码位置、定义、 调用者/被调用者以及交叉链接的词汇表术语。 ### 精确 token 搜索 裸标识符作为完整的 token 进行匹配： ``` search "ApiKeys" -> enum/class/interface chunks containing token ApiKeys search "user" -> token user, not userId unless subword mode is enabled search "service1" -> token service1, not service10 ``` ### Agent 消费 Agent 可以通过 MCP 调用 Open Mind 并接收结构化的、基于源码的 结果： ``` tool: get_glossary args: { "scope": "kafka", "term": "ISR" } result: found: true definition: "In-Sync Replicas" source_file: "..." line_number: 24 ``` 该输出可以直接在编码 agent prompt、审计跟踪或 验证 pipeline 中使用。 ## 这与通用 RAG 有何不同 通用的代码 RAG 通常这样做： 1. 对代码库进行分块。 2. 对这些块进行嵌入 (embed)。 3. 检索相似的文本。 4. 要求模型合成答案。 Open Mind 仍然使用本地嵌入进行概念检索，但在模型介入之前，它会做更多的工作： - 为术语/缩写查找构建确定性的词汇表 artifact； - 为模块、定义、import、 调用和入口点构建确定性的结构 artifact； - 在针对标识符查询的向量相似度之前，应用精确的 token 规则； - 暴露具有确定性兜底的能力路由； - 保持源码路径可移植且可追溯； - 提供 agent 可以安全调用的受限工具 API。 目标不是“与代码库聊天”。目标是提供可靠的代码库上下文，让 AI agent 能够对其进行检查、引用和采取行动。 ## 快速开始 **前提条件：** 在 Windows、macOS 或 Linux 上安装 Python 3.12+。 ``` git clone https://github.com/HelloThisWorld/open-mind.git cd open-mind pip install -r requirements.txt ``` Open Mind 是一个**无头运行时，包含多个前端**。CLI、MCP server 和 FastAPI 应用程序都驱动相同的代码 — Web UI 只是运行时之上的一个适配器， 而不是定义行为的地方，并且它完全是可选的。 ### 工具优先（无 UI） ``` # 检查 runtime：data dir、database、schema version、backends python -m openmind.cli doctor # 基于本地 repository 创建 workspace python -m openmind.cli init --name demo --path ./fixtures/sample-repo # 学习它（增量式；未更改的文件会通过 content hash 跳过） python -m openmind.cli ingest --workspace --wait # 它知道什么？ python -m openmind.cli status --workspace # 通过 MCP 将 knowledge layer 暴露给 editor 或 agent python -m openmind.cli mcp serve # ...或者启动可选的 web UI python -m openmind.cli serve ``` 每个命令都接受 `--json`，以便在 stdout 上输出一个机器可读的对象，在 stderr 上输出诊断信息以及 [稳定的退出代码](docs/cli.md#exit-codes)，因此运行时脚本可以顺畅执行： ``` WS=$(python -m openmind.cli init --name demo --path ./src --json | jq -r .workspace_id) python -m openmind.cli ingest --workspace "$WS" --wait --json | jq '.progress' python -m openmind.cli status --workspace "$WS" --json | jq '.counts' ``` 完整契约：**[docs/cli.md](docs/cli.md)**。 ### Web UI ``` ./run.ps1 # Windows ``` ``` python -m openmind.cli serve # cross-platform python -m uvicorn openmind.main:app --host 127.0.0.1 --port 8077 # equivalent ``` 然后打开 `http://127.0.0.1:8077`，创建一个项目，选择一个本地代码库， 然后开始学习。确定性的词汇表、图和精确 token 搜索 功能不需要 LLM。提问/Q&A 使用可选的本地兼容 OpenAI 的 `llama-server`。 默认情况下，server 绑定到 loopback，并拒绝非 loopback 绑定，除非 你显式传递 `--allow-non-loopback`。 ### 值得了解的事项 * **UI 是可选的。 CLI 或 MCP 路径中的任何操作都不需要它运行。 * **一个运行时，一个引导程序。** CLI、MCP 和 FastAPI 共享相同的 配置、数据库连接、迁移和服务，因此在其中一个创建的工作区 会立即可见于其他工作区。 * **`--workspace` 就是项目 ID。** 存储的实体仍然是一个 *project*， 并且 REST API 仍然显示 `/projects`；“workspace” 是内部词汇， 后续阶段将在此基础上进行构建。存储的形状没有任何改变。 * **artifact schema 是稳定的。** `.openmind` 导出保持在 schema **1.x**； 外部消费者将继续工作。导出是独立的 — 它不需要数据库、 向量存储或模型，并且仅使用标准库运行。 * **schema 变更是通过迁移实现的。** 数据库带有版本并会 自动升级；现有的项目数据库会被设定基准，从不重建。参见 [docs/database-migrations.md](docs/database-migrations.md)。 * 企业 Asset 和 Knowledge Graph 模型是**未来的 v2 工作**，尚未 实现 — 参见 [路线图](#roadmap)。 ## 从 Agent (MCP) 中使用它 Open Mind 附带了一个 MCP stdio server。任一命令都会启动相同的 server — 它们共享一个实现，而不是工具的两个副本： ``` python -m openmind.mcp_server python -m openmind.cli mcp serve ``` 客户端注册示例： ``` { "mcpServers": { "open-mind": { "command": "python", "args": ["-m", "openmind.mcp_server"] } } } ``` 已实现的 MCP 工具： | 工具 | 用途 | |---|---| | `search` | 混合代码搜索，对裸标识符采用精确 token 行为。 | | `get_glossary` | 确定性的术语/缩写查找或完整术语列表。 | | `route` | 具有确定性兜底的能力路由。 | | `dispatch` | 路由查询并调用选定的能力。 | | `find_similar_cases` | 搜索已保存的解决案例，带有过期标志。 | | `save_case` | 将问题/解决方法保存为可重用的案例。 | | `get_doc` | 生成的学习指南页面（模板 `guide` 部分；确定性的，引用了 `file:line`），或者在没有模板指南适用时如实返回未命中。 | | `propose_fix` | 以 unified diff 形式预览原样查找/替换。 | | `apply_fix` | 仅在测试套件保持通过时应用原样替换。 | ## 与兼容 MCP 的 Agent 一起使用 Open Mind Open Mind 是独立的：上述所有内容都不需要任何其他项目即可运行。对于 agent 集成，另外还有一个**稳定的 artifact 契约** — Open Mind 将其知识导出为带有版本的 `.openmind` 目录，并且 配套的 [open-mind-mcp-server](https://github.com/HelloThisWorld/open-mind-mcp-server) 加载该目录并将其作为 MCP 工具暴露出来（搜索、符号证据、 架构说明、声明验证）： ``` Source Code Repository -> Open Mind (this repo; analysis, standalone) -> .openmind artifacts (manifest.json + schema 1.1.0) -> open-mind-mcp-server (optional integration layer) -> Claude / Cursor / AI agents (MCP tools, structured JSON, file:line evidence) ``` 集成边界被故意缩小了：**`manifest.json` 加上带有版本的 artifact schema**。Open Mind 永远不会 import 或启动 MCP server； MCP server 永远不会 import Open Mind 的内部结构或重新运行其分析。 任何一个项目都可以独立于另一个工作 — MCP server 提供了示例 artifact，而 Open Mind 的 artifact 是任何消费者都可以读取的纯 JSON。 生成 artifact（确定性的、离线的、无需 LLM 且没有额外的依赖项 — 导出路径在裸 Python 安装上运行；PyYAML 是可选的，并且只 用于控制 YAML 模板配置，如果没有它会降级为“未应用模板”）： ``` python -m openmind.artifacts --repo ./fixtures/sample-repo --output ./.openmind # 或者通过 npm task-runner shim，等效地： npm run analyze -- --repo ./fixtures/sample-repo --output ./.openmind ``` 然后将它们暴露给 agent： ``` cd ../open-mind-mcp-server npm install npm run demo -- --artifacts ../open-mind/.openmind ``` `.openmind` 目录包含 `manifest.json`、`metadata.json`、 `glossary.json`、`architecture.json`、`flows.json` 和 `source-index.json`。 每个条目都带有 repo 相对路径的 `{file, line, snippet}` 证据 以及 `high`/`medium`/`low` 置信度；原样词汇表提取为 `high`，启发式投影（目录模块、基于名称的调用流）为 `medium` 或更低。将 `--repo` 指向任何本地代码库以为你自己的代码库导出 artifact。该契约由 `python tests/verify_artifacts.py`（schema、针对被分析 repo 的证据有效性 以及字节相同的确定性）验证。 schema 1.1.0 是附加的：当应用模板配置时（确定性自动选择， 或 `--template NAME`；`--no-template` 完全退出）， `metadata.template` 会记录它，`architecture.json` 将获得按角色分类的 `layers`（带证据）和每个组件的 `roles` 计数，并且流程将根据 原样切面捕获进行命名（例如 `HTTP route: Post /orders`）。如果没有 模板，额外的 key 将不存在，输出保持 1.0.0 形状 — 接受 `1.x` 的消费者无论哪种情况都能继续工作。 ## 作为技能的能力 被追踪的代码库将核心能力记录为 `SKILL.md` 契约： | 技能契约 | 涵盖内容 | 状态 | |---|---|---| | [`glossary`](skills/glossary/SKILL.md) | 原样术语/缩写提取和精确查找。 | 已实现 · 验证 90/90 次运行 | | [`code-graphs`](skills/code-graphs/SKILL.md) | 结构、依赖、调用和入口点流映射。 | 已实现 · 验证 80/80 次运行 | | [`capability-router`](skills/capability-router/SKILL.md) | 具有确定性兜底的 agent 风格路由。 | 已实现 · 验证 80/80 次运行 | 这些是 Claude Skills 风格的能力规范：小型的、明确的、 可审计的、具有确定性契约的单元。每个技能都与 [Agent Skill Verification Template](https://github.com/HelloThisWorld/agent-skill-verification-template) 配对 — 这是一个配套项目，它将 agent 技能视为生产组件，将 模型无关的契约与离线评估工具、基于源码的 验证器、可重放的运行 artifact 以及发布门控配对在一起。上面“已验证”的数字 是经过测量的，而不是断言的 — 有关方法论、最新结果以及如何重现这些结果，请参见 [测量的技能验证](#measured-skill-verification)。将技能打包为可安装的 Claude Skills 已列在路线图中；当前的 repo 已经通过 REST 和 MCP 暴露了核心工具接口。 ## 测量的技能验证 这三个能力技能使用 [Agent Skill Verification Template](https://github.com/HelloThisWorld/agent-skill-verification-template) 作为**独立工具**进行端到端评估。该模板并没有重新实现 Open Mind：它 通过 [`openmind/skill_bridge.py`](openmind/skill_bridge.py) 驱动真正的 Python 实现（`openmind/glossary.py`、 `openmind/structure.py`、`openmind/router.py`），这是一个 JSON-lines stdin/stdout 桥梁，为 fixture 语料库构建词汇表和结构 artifact， 并从中回答查找/使用/定义/路由请求。 每个技能在模板 repo（`skills/openmind-*/`， `testcases/openmind-*.json`）中都有一个机器可读的契约、快乐路径测试用例和否定 （诚实度）测试用例。每个用例运行 **10 次**，每次运行 都由四个验证器评分： 1. **schema** — 输出符合所需的结构形状。 2. **引用** — 该工具独立地重新读取 Open Mind 引用的每个 `file:line`，并检查该行是否存在、是否支持声明以及是否包含 被查询的术语/符号。伪造的引用会导致运行失败。 3. **不支持的声明** — 未知输入必须返回 `insufficient_evidence` 且零声明（绝不返回编造的答案）；已回答的声明必须全部被 引用；必须没有禁止的幻觉标记。 4. **工具调用** — 契约要求的工具已被按顺序调用。 ### 最新结果（2026-07-02 · 每个用例 10 次运行 · 门控阈值 90%） | 被评估技能 | 测试用例 | 总运行次数 | 通过率 | 有效引用 | 工具错误 | 门控 | |---|---|---|---|---|---|---| | `openmind-glossary` | 9 (7 个快乐 + 2 个否定) | 90 | **100%** | 100% | 0% | PASSED | | `openmind-code-graphs` | 8 (6 + 2) | 80 | **100%** | 100% | 0% | PASSED | | `openmind-capability-router` | 8 (6 + 2) | 80 | **100%** | 100% | 0% | PASSED | **在重复执行中 250/250 次运行为绿色** — 与 确定性契约（相同输入 → 相同输出）保持一致。否定用例通过 *拒绝*而通过：未知的术语和符号返回 `insufficient_evidence` 且零 声明，并且路由器无法被说服执行其文档记录 集合之外的能力（要求它“发明一个名为 quantum 的新能力”的查询将路由到 安全的 `search` 基础，并且“quantum”永远不会作为路由的能力出现）。 这些运行的机器可读快照提交在 [`docs/verification/`](docs/verification/) 下。 ### 该门控可证明能捕获错误输出 只有当相同的 pipeline 在遇到错误 输出时也会变红时，绿色的报告才有意义。该模板的脆弱孪生方法论根据运行种子扰乱了 Open Mind 正确的 输出 — 丢弃的引用、行号偏移了 +7、一个无效的 状态值、颠倒的工具顺序、一个凭空捏造的无据声明 — 并且门控 如期失败： | 被注入错误的技能 | 通过率 | 门控 | 重放 artifact | |---|---|---|---| | `openmind-glossary` | 52.2% | FAILED | 43 | | `openmind-code-graphs` | 58.8% | FAILED | 33 | | `openmind-capability-router` | 33.8% | FAILED | 53 | 每个注入的错误都映射回旨在捕获它的验证器 （`citation_line_out_of_range`、`answered_claim_without_citation`、 `tool_order_violation`、schema 拒绝无效状态等），并且每次 失败的运行都会留下一个重放 artifact，包含确切的输入、输出、工具追踪 和裁决。 ### 复现 ``` # 在本 repo 旁 clone harness（或者将 OPENMIND_REPO 指向此 checkout） git clone https://github.com/HelloThisWorld/agent-skill-verification-template.git cd agent-skill-verification-template npm install npm run eval:openmind # all three skills; non-zero exit if the gate fails npm run eval:openmind:flaky # proof the gate catches seeded failures ``` 每次评估都会在模板的 `reports/` 目录下写入一个独立的 `report.html`、一个 `summary.json`、Prometheus 指标、结构化的 JSONL 事件，以及（如果失败）每次运行的重放 artifact。 ## 实现映射 ``` openmind/ cli.py the command-line front end (argparse; JSON + exit codes) runtime.py composition root: one idempotent bootstrap for every adapter version.py the single runtime version constant domain/ typed application errors + the types crossing service calls ports/ the three narrow boundaries services depend on services/ use-case orchestration shared by CLI, MCP and FastAPI (workspace, ingest, job, export, health + the container) migrations/ versioned, checksummed SQLite schema migrations walker.py selection-aware walk, .gitignore handling, hashing detect.py manifest/language detection and stack cues langspec.py declarative language registry templates.py declarative template profiles: schema gate + deterministic stack-match auto-selection facets.py template facet extraction: role classification + verbatim capture facts, all with file:line evidence docs.py template-driven learning guide: guide sections -> cited, deterministic markdown pages (notes preserved across rebuilds) structure.py deterministic modules, definitions, imports, calls, entries diagrams.py Mermaid/DOT/interactive graph projections glossary.py verbatim glossary extraction and lookup tokenmatch.py exact identifier/literal boundary matching rag.py code chunking, local embedding, hybrid retrieval embeddings.py fastembed/ONNX backend with deterministic hashing fallback vectorstore.py Chroma persistence with numpy fallback ask.py source-numbered grounded prompt assembly conversation.py bounded retained Ask history cases.py saved solved cases and staleness checks router.py deterministic capability routing plus optional model refine codemod.py preview/apply literal edits with test gating artifacts.py .openmind artifact export (the stable integration contract) mcp_server.py MCP stdio server skill_bridge.py JSON-lines bridge exposing the skills to the eval harness main.py FastAPI REST/SSE API and single-page UI (one adapter) netguard.py audited outbound HTTP guard for app-controlled egress machine.py machine-local source roots and GitHub source links jobs.py resumable background jobs for ingest, Ask, enrichment ``` 语言支持定义在 `openmind/langspec.py` 中，目前在行级 结构层涵盖了 Python、JavaScript、TypeScript、Java、Kotlin、Scala、Go、Rust、C#、Ruby、PHP、C 和 C++。当可用时，Java 还具有 tree-sitter 语义 分块功能，可提供更丰富的 RAG 块。 ## 本地优先边界 Open Mind 是本地优先的： - 索引的项目内容是从本地磁盘读取的； - 持久化的 artifact 尽可能存储 repo 相对路径； - 本地模型调用通过 `netguard` 固定到 loopback； - Wikipedia 词汇表丰富化和 GitHub 源码链接获取是独立的、 经过审计的出口路径，可以禁用； - 嵌入在模型权重可用后在进程内运行。 一个重要的精度：`fastembed` 可能会在 首次使用时下载嵌入模型权重。设置 `OPENMIND_EMBED_OFFLINE=1` 以强制使用确定性哈希 嵌入器，并阻止该模型下载路径。 ## 配置 所有功能都使用默认值即可工作。有用的环境变量： | 变量 | 默认值 | 用途 | |---|---|---| | `OPENMIND_DATA_DIR` | `./data` | SQLite、Chroma、映射、日志和已学习的 artifact。 | | `OPENMIND_MACHINE_DIR` | `~/.openmind` | 机器本地的源码根目录和 GitHub 源码链接，保存在可移植数据之外。 | | `OPENMIND_EMBED_DEVICE` | `smart` | 用于 ONNX 执行提供程序的 `cpu`、`smart`、`auto` 或 `gpu`。 | | `OPENMIND_INGEST_FREE_GPU` | `1` | 在有用时暂时停止 Open Mind 管理的模型 server 以进行批量嵌入。 | | `OPENMIND_EMBED_OFFLINE` | `0` | `1` 强制使用哈希嵌入并阻止嵌入模型下载。 | | `OPENMIND_ENRICH_EGRESS` | `1` | `0` 禁用 Wikipedia 丰富化查找。 | | `OPENMIND_SOURCELINK_EGRESS` | `1` | `0` 禁用为链接源获取 GitHub 原始文件。 | | `OPENMIND_MODELS_FOLDER` | `~/models` 回退 | 本地 `.gguf`模型选择的默认文件夹。 | | `OPENMIND_MODEL_PATH` | 空 | 默认本地模型路径。 | | `OPENMIND_LLAMA_SERVER` | `llama-server` | 本地兼容 OpenAI 的模型 server 二进制文件。 | 可选的 GPU 嵌入包： ``` # Windows AMD/Intel pip uninstall onnxruntime pip install onnxruntime-directml # NVIDIA pip install onnxruntime-gpu ``` ## 测试 两层检查支持本 README 中的声明。 **技能级评估工具** — 这三个能力技能使用 [Agent Skill Verification Template](https://github.com/HelloThisWorld/agent-skill-verification-template) 进行验证（每个测试用例运行 10 次，四个验证器，发布门控）；有关最新的 结果和重现步骤，请参见 [测量的技能验证](#measured-skill-verification)。 **专注的验收脚本** — 涵盖此构建中实现的验证 契约的小型检查。一个命令即可运行支持的套件： ``` python scripts/run_acceptance.py # the CI gate (core tier) python scripts/run_acceptance.py --all # every tier, including local-only python scripts/run_acceptance.py --list # what is in the suite, and why python scripts/run_acceptance.py --only verify_migrations ``` 运行器为每个脚本提供自己独立的 `OPENMIND_DATA_DIR` 和 `OPENMIND_MACHINE_DIR`，强制离线嵌入并禁用所有出口，并且 在任何失败时返回非零值。有两个属性是经过深思熟虑的：**被跳过的 核心脚本会被计为失败**，永远不会算作通过，并且 **磁盘上的每个 `tests/verify_*.py` 都必须注册在运行器的清单中** — 因此在套件仍然报告绿色的同时，新测试不能悄无声息地不被运行。 各个脚本，每个都映射到一个具体的可靠性声明： ``` python tests/verify_artifacts.py # .openmind artifact contract: schema, evidence, determinism python tests/verify_glossary.py # verbatim extraction, provenance, honest miss python tests/verify_structure.py # detection, structure map, incremental reuse python tests/verify_diagrams.py # Mermaid/DOT projections and honest empty graphs python tests/verify_router.py # deterministic routing and model fallback validation python tests/verify_source_link.py # source-link parsing and audited egress policy python tests/verify_resources.py # ingest RAM guard behavior python tests/verify_templates.py # template profiles: schema gate, deterministic selection python tests/verify_facets.py # template facets: roles, captures, projections, honest empties python tests/verify_guide.py # learning guide: cited pages, notes preservation, honest reset python tests/verify_grounding.py # glossary-first Ask routing, honest miss/empty sources python tests/verify.py # 12 cross-cutting design invariants end to end python tests/verify_migrations.py # schema ledger: empty, legacy baseline, checksum, rollback python tests/verify_runtime.py # runtime bootstrap idempotency, worker opt-in, one version python tests/verify_services.py # application services and their typed errors python tests/verify_cli.py # CLI contract: JSON output, exit codes, every command python tests/verify_adapters.py # REST route, MCP tool and skill-bridge compatibility ``` 其余的 `tests/verify_*.py` 文件是回归套件（Ask 流程、模型 server、异步删除、特定的修复批次）。一个脚本， `verify_delete_responsive.py`，被排除在 CI 门控之外，并在 清单中标记为 `local`，原因是：它断言在执行删除操作排空时 API 延迟低于 2 秒，而共享 CI 运行器的调度抖动 会使这一点变得不稳定。在发布对删除路径的更改之前，请在本地运行它。 在运行器的设置下，整个 `tests/` 目录在全新克隆上针对 `fixtures/` 中的中立 fixture 代码库可以通过测试。 ## 路线图 以下内容在当前构建中并未声称已完成： **v2 企业知识层** — 其中任何一个都未实现。阶段 1 （已发布）是 [docs/v2/phase-1-core-foundation.md](docs/v2/phase-1-core-foundation.md) 中描述的以工具为先的运行时基础；它 故意为以下项目创建了扩展点，而不是构建 它们： - 企业 Asset、Revision、Claim 和 Relation 模型； - 工程 Knowledge Graph； - PDF、DOCX 和 XLSX 解析；支持 COBOL 和 JCL； - 云模型提供商（OpenAI、Anthropic、Bedrock、Azure、Vertex） — 运行时保持本地优先，没有云凭证； - 需求到代码的可追溯性、冲突检测和分支覆盖； - webhook 集成和 Bundle 2.0 artifact schema（导出保持在 schema 1.x）； - 类型化的 worker 池或作业 DAG，以取代当前的单 worker 引擎。 **其他尚未完成的工作：** - 为被追踪的能力契约提供可安装的 Claude Skill 打包； - 超出基于名称的调用者/被调用者邻域的更深入的变更影响分析； - IDE 扩展集成； - 在本 repo 自己的 CI 中运行技能评估门控（幻觉抵抗力和源码引用 质量已由配套工具测量）； - 用于模型答案的输出引用验证器； - 超出 Java 的更广泛的 tree-sitter 解析器； - 用于节点扩展和图导航的特定于图的 MCP 工具； - 超出保留的提问历史和已保存的解决案例的一流代码库 记忆层； - `.openmind` 导出中的指南 artifact（学习指南页面目前 仅在应用端生成）； - 图 UI 中的可视层分组（每个节点的 `role` 数据已经 由 API 暴露）。 ## 设计原则 - **证据优于流畅度。** 一个正确的“未找到”比一个自信但 无根据的答案更好。 - **可追溯性优于模糊的摘要。** 有用的事实应该指向源码 路径、行、行范围或显式的提取 artifact。 - **确定性优于聪明的猜测。** 系统的默认行为应该在没有模型的情况下 可重复。 - **歧义即是数据。** 如果静态边是模棱两可的，就标记它；不要假装 系统知道的比它实际知道的更多。 - **Agent 可靠性优于演示吸引力。** 工具 API、路由、本地优先 边界和测试门控比花哨的聊天界面更重要。 ## 贡献 欢迎提交 issue 和 pull request。一个好的更改应保持核心契约 不变： - 为新事实添加源码证据； - 优先选择确定性提取而不是模型生成； - 添加或更新专注的 `tests/verify_*.py` 验收检查； - 通过经过审计的防护来路由新的出站网络路径； - 明确区分未来功能与已实现的行为。 ## 许可证 基于 [MIT 许可证](LICENSE) 发布。

标签：AI智能体, MCP, SOC Prime, 代码理解, 代码索引, 开发工具, 逆向工具