内容
OKF
一个遵循 [开放（OKF）v0.1 规范](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.mdLLM管理的知识库 —— 一组带有YAML前置信息的普通，可由人类阅读，在git中可差异化，由代理管理。
方式，一个代理：**
- **MCP服务器** — 通过stdio或可流式传输的HTTP提供 `memory_query` / `memory_add` / `memory_update` / `memory_status` / `memory_maintain` 工具。每次调用都驱动一个带有OKF规范的内部LLM代理。
- **网页界面** — 浏览捆绑包（树、概念查看器、更新日志、一致性徽章），将内存视为类似Obsidian的**力导向图**（可拖拽/平移/缩放，按类型着色，按连接大小立节点红色环绕，点击打开），并与同一个代理聊天以。工具调用内联渲染，以便您可以观察其工作过程。
命令行界面** — `pnpm agent:query "..."` / `pnpm agent:mutate "..."` 烟雾测试条目。
**设计规则：一致性在代码中强制执行，而不是在提示中。** 确定性捆绑层验证前置信息（需要 `type`），重新生成 `index.md` 文件，追加 `log.md` 条最新的在前，规范§7），并将所有路径沙盒化到捆绑包根目录。LLM决定*更改内容*；代码保证结果是一个一致的捆绑包。
## 技术栈
pnpm monorepo：
| 包 | 描述 |
|---|---|
| `packages/core` | OKF捆绑层（零）+ 代理（Vercel AI SDK工具循环：搜索/读取/列出/写入/修补/删除）+ 提供者注册表 |
| `packages/server` | Fastify：MCP可流式HTTP在 `/mcp`，stdio二进制文件，REST浏览API在 `/api/*`，流式聊天在 `/api/chat`构建 |
| `packages/web` | Vite + React + Tail捆绑浏览器 + 代理`useChat`） |
提供环境选择，每个聊天可替换）：**Anthropic** （**OpenRouter**，**pp** （llamallama-server` / llama-swap — 模型从 `//models` 自动发现加载模型），**local** （任何其他OpenAI兼容端点）。
### llama.cpp
```bash
# 在推理盒上 — --jinja 启用OpenAI样式的工具调用
llama-server -m model.gguf --jinja --host 0.0.0.0 --port 8080
# 这里 — 不需要模型ID，它被发现
_PROVIDER=llamacppACPP_BASE_URL=http://inference-box:8080UNDLE_ROOT=./sample-bundle node packages/server/dist/index```
也适用于llama-swap：发现优先使用**已加载**模型，因此查询多分钟的模型交换。使用M_MODEL=` 固定。
## 快速开始
pnpm install
pnpm build
cp .env.example # 添加您的API密钥UNDLE_ROOT=./sample-bundle ANTHROPIC_API_KEY=sk-... node packages/server/dist/index.js
# → http://localhost:3800 (网页界面 + /api + /mcp)
```
开发模式（服务器在:3800，Vite HMR在:5180，带代理）：
```bash
BUNDLE_ROOT=./sample-bundle pnpm --filter @okf-agent/server dev
pnpm --filter @okf-agent/web dev
```
## MCP注册（Claude Code / Desktop）
```bash
claude mcp add okf-kb \
-e BUNDLE_ROOT=/path/to/your/bundle \
-e ANTHROPIC_API_KEY=sk-... \
-- node /path/to/okf-agent/packages/server/dist/mcp/stdio.js
```
或将HTTP MCP客户端指向 `http://host:3800/mcp`。
### 种子内存
客户端LLM仅看到四个裸工具名称，从未获得检查内存的直觉。因此，在**会话开始**时，服务器通过两个通道将知识库内容的紧凑概述注入到模型中：
1. MCP初始化 **`instructions`** 字段（Claude将其放入系统），以及
2. **`memory_query` 工具描述** — 每个工具调用客户端加载的通用备用。
种子为每个新会话重新生成。在长期（stdio）会话中进行 `memory_add` / `memory_update` 后，工具描述通过 `tools/list_changed` 刷新，以便会话查看其自身写入。带（手动编辑，其他客户端）被拾取到下一个会话 图表健康与维护
内存是一张图，而不是一堆笔记，图会腐烂：概念变得**孤立**（无链接到它们），链接变得**断裂**。两种机制保持：
- **写入时链接** — 新知识要么所属的概念（现有实体的属性被修补，而不是单独归要么当它是独立，创建 *且*概念反向链接。矛盾在原地被取代，从不并存。
- **`memory_maintain`** — 确定性 lint（孤立 + 断裂链接，在 `memory_status` 下的 `graph` 中显示）驱动内部代理将孤立节点连接到相关概念并修复悬空链接。定期运行以对抗漂移；当图已经健康时，它是一个空操作。
该设计镜像了Karpathy的 [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)（index.md + log.md，创建-vs-lint for orphans）。从该模式中延期，直到规模需要：显式页面类型模式，和混合FTS5 + 嵌入式搜索（``中的简单扫描对于低千计的概念来说足够）。
## Docker
```bash
docker compose up --build
# 捆绑包是一个卷挂载 — 将 ./sample-bundle 指向任何OKF捆绑```
## 测试
```bash
pnpm test # 核心：15个测试（规范§5/§6/§§9，沙盒，搜索，并发）
pnpm --filter @okf-agent/server exec tsx scripts/mcp-smoke # MCP stdio 往返（需要 SMOKE_BUNDLE + API密钥）
```
## 环境
参见 [.env.example](.env.example)。`BUNDLE_ROOT` 是必需的；`GIT_AUTOCOMMIT=true` 提交每次变更。
