grounded-knowledge-engine

# 知识引擎 **本地优先、提供者中立的 AI 代理项目记忆库。** 知识引擎（GKE）将 Markdown 和实际文档转换为可搜索的知识库，根据证据提供答案，并将有用的学习内容捕获回纯文本文件中，在 Claude Code、Codex、Gemini CLI 和其他 MCP 客户端之间恢复结构化的项目上下文。 您的文件仍然是事实来源。检索索引是可丢弃的，MCP 服务器在本地运行，可选的操作员驾驶舱预览了代理消耗的相同项目状态。公共驾驶舱预览计划在 [dimouzunov.com](https://dimouzunov.com) 上提供，仅限于经过净化的演示工作区。 > **状态：** 已实现基于证据的检索、捕获、文档摄入、提供者中立的 MCP 服务器、项目上下文和 React 驾驶舱。GKE 不是托管的 SaaS；托管的驾驶舱是静态的公共预览，仅限于演示内容，而不是托管的知识引擎。 ## 已实现功能 | 功能 | 当前行为 | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **基于证据的检索** | 使用 BM25 或 SQLite FTS5 在本地 Markdown 上进行搜索，并提供文件和行引用。 | | **持久捕获** | 有用的答案变成 Markdown 笔记；未解决的问题可以记录，而不是被猜测。 | | **文档摄入** | PDF、DOCX、XLSX、Markdown 和文本在本地提取、清理、规范化、捕获和索引。 | | **项目恢复** | `kb.resume_project` 返回当前焦点、最近更改、决策、阻塞/问题、下三个操作、关键文档和引用。 | | **一个 MCP 服务器** | Claude Code、Codex 和 Gemini CLI 使用相同的本地 `kb` 服务器和知识库。 | | **操作员驾驶舱** | React 预览提供了知识库、项目面板、结构化的项目详情、移交复制和上下文图。公共预览仅使用净化的演示内容。 | | **有限的协议表面** | 默认 MCP 配置文件包含四个语义工具，带有输出模式、安全注释和 CI 强制执行的模式预算。 | ## 复合循环 <!-- 现实命令的静态渲染；通过脚本/record-loop.sh重新生成。 -->  ```mermaid flowchart LR F[Markdown · PDF · DOCX · XLSX] -->|ingest| K[Markdown 事实来源] K -->|derive| I[(BM25 · SQLite)] A[Claude · Codex · Gemini] --> M[本地 MCP 服务器] M -->|search / answer / capture| I M -->|write useful learning| K P[规范的项目记录] --> R[kb.resume_project] M --> R R --> C[项目胶囊 + 引用移交] K --> O[操作员驾驶舱] C --> O ``` 该存储库证明了两个循环的端到端： 1. 摄入或索引本地内容。 2. 根据检索的证据提供答案，并附上引用。 3. 将有用的学习内容捕获回 Markdown。 4. 从捕获的笔记中重新回答一个新的查询。 5. 在不混淆类似命名的情况下，从另一个项目恢复明确标识的项目上下文。 6. 在本地驾驶舱中渲染相同的项目事实，并复制技术移交。  ## 快速入门 需要 **Node ≥ 22.5** 以使用内置的 `node:sqlite`；推荐 Node 24。 ```bash npm install # 搜索演示知识库 npm run search -- --query "MCP 工具是模型控制还是应用程序控制" \ --mode generic --limit 5 --context 1 --refresh # 验证 MCP 发现、资源、基础、捕获、重用和项目恢复 npm run smoke:mcp # 运行完整的引擎套件 npm run test:gke ``` 演示语料库位于 [`demo-kb`](demo-kb)。规范的项目上下文示例是 [`demo-kb/projects/router-rollout/project.md`](demo-kb/projects/router-rollout/project.md)，具有明确链接的证据位于 [`demo-kb/sources/router-rollout`](demo-kb/sources/router-rollout)。 ## 连接 Claude Code、Codex 或 Gemini CLI 在所有三个客户端上注册相同的本地 `kb` MCP 服务器： ```bash npm run setup:mcp ``` 生成的适配器使用绝对的可执行文件和服务器路径，并指向 [`tools/kb-mcp-server/server.ts`](tools/kb-mcp-server/server.ts)： - Claude Code：`.mcp.json` 加本地批准。 - Codex：`.codex/config.toml`。 - Gemini CLI：`.gemini/settings.json`。 配置一个客户端或更改目录策略： ```bash npm run setup:mcp -- --client codex npm run setup:mcp -- --profile full npm run setup:mcp -- --no-writes npm run setup:mcp -- --skip-smoke ``` 该命令是幂等的。生成的机器特定配置被 Git 忽略。在设置完成后，从此存储库重新启动配置的客户端。 ### 默认 MCP 表面 故意小的 `core` 配置文件公开： - `kb.search` — 具有引用的排名本地证据。 - `kb.get_record` — 按路径、标题、slug 或文件名索引的记录。 - `kb.answer_and_capture` — 基于证据的答案和捕获策略。 - `kb.resume_project` — 一个紧凑的、引用的项目胶囊。 `full` 配置文件添加了高级检索、刷新、显式写入工具和兼容性别名。除非启用写入，否则写入工具不会被发现。 MCP 资源公开可寻址的上下文，而不膨胀工具列表： - `gke://workspace/info` - `gke://record/{path}` - `gke://project/{projectId}/context` 每个广告工具都有一个正式的输出模式和 MCP 安全注释。目录字符和工具数量预算由 `npm run test:mcp:catalog` 强制执行。 ### 薄代理技能 提供者中立的 [`grounded-knowledge-workflow`](skills/grounded-knowledge-workflow/SKILL.md) 技能教导代理何时搜索本地证据、恢复项目、保留持久知识或使用确定性的项目 CLI。它只包含策略；所有检索、引用、范围和写入仍保留在共享引擎中。 支持代理技能布局的代理可以直接加载文件夹。对于个人 Codex 安装，请将其复制到本地技能目录： ```bash cp -R skills/grounded-knowledge-workflow ~/.codex/skills/ ``` > 本地服务器通过标准输入/输出发出换行分隔的 JSON。它不是远程 HTTP 服务。传输还接受旧的 `Content-Length` 输入帧以实现兼容性，但生成的客户端适配器使用换行分隔的 JSON。 ## 结构化项目上下文 规范的项目使用一个明确的记录： ```text kb/ ├── projects/ │ └── router-rollout/ │ └── project.md └── sources/ └── router-rollout/ └── evidence.md ``` `project.md` 使用 `record_type: project` 和 `project_id` 标识项目。项目成员资格通过 `project_id`、`source_roots`、规范的项目文件夹或链接文档显式表示。仅语义相似性从不使文档成为项目的一部分。 `kb.resume_project` 仅解析请求的 ID，对于未知项目则放弃。其输出包括： - 这里开始的简介； - 当前焦点和最近的变更； - 活跃的决策； - 阻塞和开放问题； - 最多三个操作（已完成的项目没有）； - 关键文档和行引用。 共享解析器和移交格式化程序位于 [`tools/projects`](tools/projects)。驾驶舱使用相同的模型，而不是维护项目 Markdown 的单独解释。旧项目笔记为兼容性而保留。 **今天实现：** 规范的项目记录、共享解析器/标准化器、项目范围的 `kb.resume_project`、驾驶舱渲染和 `gke project` CLI（`create`、`list`、`show`、`validate`、`update`、`link`）。 **计划（目标架构，尚未实现）：** 自动或 CLI 检查点创建、多工作区保险库、决策重放记录和远程 MCP 网关。这些出现在 [`docs/workspace-data-architecture.md`](docs/workspace-data-architecture.md) 中，作为规范的目标模型；每个记录类型都带有其自己的**实现状态**标签，以便当前表面永远不会与计划的表面混淆。 ### 创建和验证项目 项目可以直接作为 Markdown 编写，也可以通過确定性的项目 CLI 创建。MCP 不需要进行项目管理。 ```bash # 创建规范的记录和默认源文件夹 npm run project -- create customer-pilot \ --title "客户试点" \ --owner "工作区所有者" \ --track "产品" \ --status active \ --tag pilot \ --tag customer # 检查和验证项目 npm run project -- list npm run project -- show customer-pilot npm run project -- validate customer-pilot npm run project -- validate # 验证每个项目 # 更新已知字段或部分，而不替换整个 Markdown 文件 npm run project -- update customer-pilot \ --current-focus "验证试点工作流程" \ --next-action "运行验收测试" \ --next-action "记录结果" # 将现有工作区文件添加到关键文档和项目范围 npm run project -- link customer-pilot notes/pilot-evidence.md \ --label "试点证据" # 预览生成的 Markdown 而不写入 npm run project -- create another-pilot --title "另一个试点" --dry-run npm run project -- update customer-pilot --owner "新所有者" --dry-run ``` 在 `npm run build` 之后，使用 `npm link` 将编译的 CLI 公开为 `gke`: ```bash npm link gke create customer-pilot --title "客户试点" ``` 可重用的 TypeScript 服务从 [`tools/projects`](tools/projects) 导出 `createProject`、`getProject`、`listProjects`、`updateProject`、`linkProjectSource`、`validateProject` 和 `validateAllProjects`。创建使用工作区相对路径和原子写入。验证是只读的，并检查规范的元数据、日期、必填部分、重复 ID、生命周期值、源根和本地链接。受控更新保留未知的前面和正文部分。 直接编辑仍然受支持。手动创建的规范记录位于 `kb/projects/<project-id>/project.md` 下，被 CLI、驾驶舱和 `kb.resume_project` 以与生成记录相同的方式发现。 要通过相同的 CLI 将存储库的演示重现为独立的、可移植的工作区： ```bash npm run export:demo-projects npm run project -- validate --repo-root examples/demo-project-workspace ``` 生成的 [`examples/demo-project-workspace`](examples/demo-project-workspace) 在不复制主工作区中的 ID 的情况下使用 `kb/projects`、`kb/sources` 和 `kb/topics`。 ## 操作员驾驶舱 公共前端预览版将在 [`dimouzunov.com`](https://dimouzunov.com) 上提供。它是 `apps/cockpit` 的静态 Vercel 构建，位于存储库的净化演示知识库之上；它不公开本地 MCP 服务器、索引、写入工具或私有工作区文件。 运行本地预览版： ```bash cd apps/cockpit npm install npm run dev ``` 驾驶舱读取 `demo-kb` 和 `kb`，将两者映射到一个逻辑知识命名空间，并提供： - 任务控制和快速搜索； - Markdown 知识库； - 项目面板； - 结构化的项目详情，包括焦点、变更、决策、问题、阻塞、操作和链接资源； - **复制移交**，包括对限制浏览器外壳的回退； - 上下文图。 参见 [`apps/cockpit/README.md`](apps/cockpit/README.md) 以获取路由和开发详情。 ## 摄入真实文档 馈送一个包含 PDF、DOCX、XLSX、Markdown 或文本文件的文件夹： ```bash npm run ingest -- ./inbox npm run ingest -- ./inbox --dry-run npm run ingest -- ./inbox --module general --no-scrub ``` 完全本地的管道是： ```text detect → extract → normalize → scrub → capture → index ``` 每个源都接收到一个确定性的路径，使得重新摄入是幂等的，并防止同名文件发生冲突。默认情况下，类似机密的值会被清理。仅限图像的 PDF 被检测并跳过，因为 OCR 不在此范围内。 代理还可以通过连接的 MCP 服务器捕获附件文档；参见 [`docs/ingest-recipe.md`](docs/ingest-recipe.md)。开发人员详细信息位于 [`tools/ingest/README.md`](tools/ingest/README.md)。 ## 架构 | 层 | 责任 | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | [`tools/grounding`](tools/grounding) | 确定性索引、检索、基于证据的合成和评估。 | | [`tools/projects`](tools/projects) | 规范的项目解析、严格的范围解析、恢复胶囊、引用和移交格式化。 | | [`tools/kb-mcp-server`](tools/kb-mcp-server) | 提供者中立的 stdio 传输、MCP 目录、处理程序、资源、配置文件和安全合约。 | | [`tools/ingest`](tools/ingest) | 本地文档提取和捕获适配器。 | | [`apps/cockpit`](apps/cockpit) | 相同 Markdown 和共享项目模型的 React 预览；作为静态演示托管在 `dimouzunov.com` 上。 | | `demo-kb/` 和 `kb/` | 规范的纯文件知识和项目状态。 | 参见 [`docs/architecture.md`](docs/architecture.md) 以获取引擎图和 [`docs/workspace-data-architecture.md`](docs/workspace-data-architecture.md) 以获取更广泛的项目/工作区数据模型和计划的顾问功能。 ## 验证 ```bash # 引擎 npm run typecheck npm run build npm run test:gke npm run scrub # 驾驶舱 cd apps/cockpit npm run typecheck npm run test npm run build ``` CI 验证类型安全、构建、检索质量、MCP 设置和合约、项目上下文隔离、捕获/重用循环、 二进制文档摄入、驾驶舱和机密/文件名净化。 ## 边界 - GKE 是本地优先的：文件和 MCP 进程保留在您的机器上。 - 公共前端预览是静态的，仅用于演示；它不托管用户工作区或 MCP 进程。 - Markdown 文件是规范的；索引和预览内容是派生的。 - 项目范围是显式和确定性的。 - GKE 不是托管的 SaaS、Jira 替代品或通用文档管理平台。 - 企业代理的临时远程网关是一个计划中的、按需的集成 — 不是当前核心的一部分。 ## 演示源和许可证 演示知识库包含来自 MIT 许可的 [Model Context Protocol 文档](https://github.com/modelcontextprotocol/docs) 的转述笔记，以及用于测试隔离和移交行为的原始综合项目记录。属性在 [`docs/demo-sources.md`](docs/demo-sources.md) 中记录。 [MIT](LICENSE)