内容
# LLM Wiki 服务端
[](https://github.com/knowledge-bridge-labs/llmwiki-serve/actions/workflows/ci.yml)
[](./LICENSE)
[](https://www.python.org/)
`llmwiki-serve` 是 LLMWiki 工具链的只读知识源服务器。将其指向现有的 Markdown、Obsidian 风格或 LLMWiki 文件夹，它会公开与 CLI 命令、HTTP 端点、MCP 风格的 JSON-RPC 工具、MCP 流式 HTTP 端点和可选的 A2A 风格兼容性端点相同的本地投影。
在以下情况下使用：
- 您想要来自您已经拥有的文件的本地的、代理可读的上下文。
- 编码代理、IDE 代理、脚本或工作台可以检索引用的证据并进行自己的规划或答案合成。
- 您需要 `llmwiki-agent-bridge` 和 `llmwiki-chat` 可以调用的源层。
在工具链中，`llmwiki-serve` 是第一层：它读取您的 wiki 并提供证据。`llmwiki-agent-bridge` 是可选的答案合成升级层，而 `llmwiki-chat` 是用于源、图、运行时和跟踪检查的浏览器工作台。
它不是一个全栈 RAG 应用：它不爬取网络、构建托管的向量存储、运行模型、合成最终答案或修改您的 wiki。
[示例](examples/README.md)
| [架构](docs/architecture.md)
| [OpenAPI 合同](docs/openapi.json)
| [发布检查清单](docs/release.md)
| [文档门户](https://knowledge-bridge-labs.github.io/llmwiki-docs/)
| [发布状态](https://knowledge-bridge-labs.github.io/llmwiki-docs/status)
| [贡献](CONTRIBUTING.md)
| [安全](SECURITY.md)
| [支持](SUPPORT.md)
| [变更日志](CHANGELOG.md)
> 公共预览说明：源代码 checkout 使用是支持的首选路径。
> 包安装命令在发布第一个 PyPI 版本后生效。
## 演示
[观看文档演示](https://knowledge-bridge-labs.github.io/llmwiki-docs/demo)
以查看 `llmwiki-serve` 项目现有的 LLMWiki、Markdown 或 Obsidian 风格文件夹作为只读知识源。
[](https://knowledge-bridge-labs.github.io/llmwiki-docs/demo)
## 10 分钟快速入门
安装 `uv` 并使用 Python 3.11 或更高版本：
```bash
uv --version
uv python install 3.11
```
从源代码 checkout 运行捆绑的示例 wiki：
```bash
git clone https://github.com/knowledge-bridge-labs/llmwiki-serve.git
cd llmwiki-serve
uv sync --extra dev
uv run llmwiki-serve manifest ./examples/sample-wiki
uv run llmwiki-serve query ./examples/sample-wiki "release readiness"
uv run llmwiki-serve serve ./examples/sample-wiki --host 127.0.0.1 --port 8765
```
在另一个终端，查询本地服务器：
```bash
curl -s http://127.0.0.1:8765/manifest
curl -s http://127.0.0.1:8765/query \
-H 'content-type: application/json' \
-d '{"query":"release readiness","limit":4}'
```
在 Windows PowerShell 上，显式使用 `curl.exe` 或使用 PowerShell 对象正文的 `Invoke-RestMethod`。
您成功时，`manifest` 返回页面/源元数据，`query` 返回带有引用的上下文包，来自 `examples/sample-wiki`。指向您自己的 Markdown 文件夹时：
```bash
uv run llmwiki-serve query /path/to/wiki-folder "what should an agent know?"
uv run llmwiki-serve serve /path/to/wiki-folder --host 127.0.0.1 --port 8765
```
在发布第一个包后，通过以下方式安装 CLI：
```bash
uv tool install llmwiki-serve
# 或
pipx install llmwiki-serve
```
## 它提供什么
`llmwiki-serve` 是本地知识文件夹上的协议层。它从 Markdown 页面、链接、标题、标签、前端事项、源引用和可选的侧车图事实中构建只读投影。
| 需要 | `llmwiki-serve` 提供 |
| --- | --- |
| 给代理提供基础上下文 | 查询排名的上下文包，带有定位页面、引用证据、限制和图提示。 |
| 检查 wiki 而不更改它 | 清单、搜索、读取和图投影，从磁盘上的文件重新构建。 |
| 在工具中使用一个源 | CLI 命令、HTTP 端点、MCP 风格的 JSON-RPC 工具、MCP 流式 HTTP 工具和可选的 A2A 风格兼容性端点，适用于同一服务模型。 |
| 将草稿排除在代理上下文之外 | 默认情况下，草稿和未发布的页面不会被包含在上下文、搜索、读取和图响应中。 |
| 优先考虑本地 | 默认情况下，本地 CORS、网络清单路径删除和无需托管存储。 |
适用于 Obsidian、Logseq、Foam、Dendron、Quartz、原生 LLMWiki 文件夹和生成的 Markdown 知识库，这些知识库符合文档化的文件夹合同。
不适用于 wiki 编译器、爬虫、创作工具、托管 RAG 应用、向量数据库、模型运行时、答案合成器或认证的 MCP/A2A 实现。
## 它如何适配
```mermaid
flowchart LR
wiki["现有 Markdown 或 LLMWiki 文件夹"]
serve["llmwiki-serve<br/>只读知识源"]
direct["Codex / Claude Code / Copilot<br/>直接上下文使用"]
bridge["llmwiki-agent-bridge<br/>运行时合成升级"]
chat["llmwiki-chat<br/>图和跟踪工作台"]
wiki --> serve
serve --> direct
serve --> bridge
serve --> chat
```
| 路径 | 最佳时机 | 关系 |
| --- | --- | --- |
| 直接代理使用 | Codex、Claude Code、Copilot、IDE 代理或脚本需要本地 wiki 上下文时。 | 从这里开始。代理调用 `llmwiki-serve` 获取证据，并控制规划、编辑或响应。 |
| `llmwiki-agent-bridge` | 运行时需要一个汇总源证据并返回模型支持的引用答案的单一端点。 | 从直接上下文调用升级，当答案合成属于桥接服务时。 |
| `llmwiki-chat` | 人类需要一个用于连接源、图上下文、运行时选择和跟踪的浏览器工作台。 | 从服务器 API 升级，当检查、路由和审查需要 UI 时。 |
| `llmwiki-docs` | 您需要跨仓库的快速入门、协议映射、部署姿势和兼容性说明。 | 为公共预览准备了文档门户。 |
## 直接代理技能
编码代理可以直接使用 `llmwiki-serve`，前提是可信的本地服务器已经运行。 在项目说明或本地环境中设置服务器 URL：
```bash
export LLMWIKI_SERVE_URL=http://127.0.0.1:8765
```
然后指示 Codex、Claude Code、Copilot 或另一个本地客户端：
1. 调用 `POST /query` 获取任务特定的上下文包。
2. 仅使用 `/search`、`/read/{page_id}`、`/graph`、`/mcp` 或 `/mcp/stream` 进行后续检查。
3. 将返回的页面视为源证据，而不是生成的最终答案。
不要在提交的代理说明中硬编码私有主机、端口、凭证或承载令牌。可重用的 Codex、Claude Code 和 Copilot 直接客户端示例位于 `llmwiki-agent-bridge` 存储库下的 `integrations/` 目录中；公共传输后，从 `https://github.com/knowledge-bridge-labs/llmwiki-agent-bridge/tree/main/integrations` 开始。在本地 sibling checkouts 中，使用 `../llmwiki-agent-bridge/integrations/README.md`。
当代理应调用单个模型支持的答案端点而不是自己管理源检索时，升级到 `llmwiki-agent-bridge`。当人类需要交互式地检查图上下文、运行时选择、跟踪和引用答案时，升级到 `llmwiki-chat`。
## 服务表面
所有入口点都使用相同的只读服务行为。
| 表面 | 形状 |
| --- | --- |
| CLI | `manifest`、`query`、`source-refs`、`source-bundle` 和 `serve`。 |
| HTTP | `GET /health`、`GET /manifest`、`GET /source-bundle`、`GET /source-refs`、`POST /query`、`POST /search`、`GET /read/{page_id}`、`GET /graph`。 |
| MCP 风格 JSON-RPC | `POST /mcp`，带有 `tools/list` 和 `tools/call`，适用于 `llmwiki_context`、`llmwiki_search`、`llmwiki_read`、`llmwiki_graph`、`llmwiki_source_refs` 和 `llmwiki_source_bundle`。 |
| MCP 流式 HTTP | `POST /mcp/stream`，使用官方 MCP Python SDK FastMCP 流式 HTTP 传输，适用于相同的六种工具。 |
| A2A 风格兼容性 | 默认关闭。启用 `GET /.well-known/agent-card.json` 和 `POST /message:send`，使用 `llmwiki-serve serve --enable-a2a-compat` 或 `create_app(..., enable_a2a_compat=True)`。 |
代理应首先调用 `llmwiki_context` 获取单个基础问题。协调主机拥有的 RAG 或多源编排的代理还应检查 `llmwiki_source_bundle` 以发现稳定的源标识、投影签名、原始元数据和不透明的源引用。搜索、读取、图和源引用工具是用于聚焦检查的后续工具。
生成的 FastAPI OpenAPI 合同提交在 [docs/openapi.json](docs/openapi.json) 中。它涵盖了默认的 HTTP 和 MCP 风格 JSON-RPC 兼容性表面；挂载的 MCP 流式 HTTP ASGI 应用在运行时提供，A2A 风格的模式仅在启用 A2A 兼容性的情况下可用。
## 它读取什么
- 具有 `hot.md`、`index.md`、`overview.md` 和主题页面的通用 Markdown wiki。
- Obsidian 风格的 wiki 链接，例如 `[[Process Page]]` 和指向其他 `.md` 页面的 Markdown 链接。
- YAML 前端事项字段，例如 `id`、`title`、`status`、`review_state`、`source_refs`、`tags` 和 `updated_at`。
- 来自页面、标题、链接、标签和源引用的文件夹级图结构。
- 来自 `graph/graph.json` 的可选侧车图事实。
- 源包元数据，标识一个服务的知识源，其当前投影签名、可见源引用和原始元数据提示。原始文件由操作员或主机 RAG 层保留；`llmwiki-serve` 不读取或公开任意二进制源内容。
命名生产者仓库在架构指南中是兼容的 Markdown 输出目标，而不是推荐的集成或每个版本的支持声明。`llmwiki-serve` 读取它们生成的或存储的 Markdown，当它匹配原生文件夹合同或支持的适配器形状时。
## 比较
| 比较对象 | 差异 |
| --- | --- |
| 全栈 RAG 应用 | `llmwiki-serve` 不拥有摄入作业、嵌入、模型调用、聊天 UX、身份验证或托管。它提供本地文件作为上下文和协议形状的 API。 |
| 向量数据库 | 不需要嵌入索引或远程存储。排名基于当前的只读 Markdown 投影。 |
| Wiki 编译器或爬虫 | 它不生成、爬取、规范化、迁移或重写源 Markdown。 |
| MCP/A2A 实现 | 它公开官方 SDK 的 MCP 流式 HTTP 端点以及兼容性测试的 JSON-RPC 和可选的 A2A 风格表面，但不声明 A2A 认证或详尽的运行时功能完整性。 |
| `llmwiki-agent-bridge` | 桥接层是模型/运行时升级层。`llmwiki-serve` 仍然是其下的源投影层。 |
| `llmwiki-chat` | 聊天是浏览器工作台。`llmwiki-serve` 是其可以检查或调用的本地 API 表面。 |
## Python API
记录的 Python 导入表面是：
```python
from llmwiki_serve import LlmWikiService, create_app
```
`LlmWikiService` 拥有清单、源包、源引用、上下文、搜索、读取、图和刷新行为。`create_app` 为嵌入 HTTP、MCP 风格 JSON-RPC、MCP 流式 HTTP 和可选的 A2A 风格兼容性表面构建 FastAPI 应用。其他包模块是实现细节，除非此处记录。
## 安全默认值
- 选定的源文件夹是不可变的输入。不会通过服务器重写、规范化、迁移、注释或上传源 Markdown。
- CLI `manifest` 和 `query` 为每个进程构建新的投影。
长运行的 `serve` 实例缓存内存中的投影，并在 Markdown、Org、适配器标记/配置或 `graph/graph.json` 源文件更改时刷新它。
- 草稿和未发布的页面默认情况下不会被包含在读取、搜索、上下文和图响应中。可见性块显式非服务标记：`draft: true`、`published: false`、`publish: false`、`draft/proposed/needs_review` `review_state` 值和 `status` 值，如 `draft`、`proposed`、`needs_review`、`blocked`、`unpublished`、`private`、`hidden`、`embargoed`、`confidential`、`internal` 或 `withheld`。其他生命周期或成熟度 `status` 值默认情况下提供。HTTP 和 MCP 工具 `include_drafts=true` 仅在 `--allow-drafts` 或 `create_app(..., allow_drafts=True)` 使用时被尊重。 A2A 风格兼容性端点默认情况下禁用；启用时，`message:send` 始终构建仅限审批的上下文。
- 网络清单响应省略本地 wiki 根路径。CLI 清单是本地操作员输出，包括根路径。
- 默认 HTTP CORS 策略允许 `localhost`、`127.0.0.1` 和 IPv6 localhost `[::1]` 上的本地浏览器源；它不是通配符。显式 `--cors-origin` 值替换默认的本地允许列表。
- 默认情况下，符号链接的 Markdown/Org 源文件、符号链接的适配器标记/配置文件和符号链接的 `graph/graph.json` 侧车被忽略，因此提供的源树在选定的 wiki 根目录内。
在公开 wiki 超出受信任的本地环境之前，请查看 [SECURITY.md](SECURITY.md)。使用 [SUPPORT.md](SUPPORT.md) 进行问题路由和兼容性报告期望。
## 存储库结构
| 路径 | 目的 |
| --- | --- |
| `src/llmwiki_serve/` | 服务、解析器、投影、API 和 CLI 实现。 |
| `examples/` | 公共示例 wiki 和示例用法说明。 |
| `docs/` | 架构、OpenAPI 合同和发布指南，供源代码 checkout 用户使用。 |
| `scripts/` | 发布烟雾和候选样本辅助脚本。 |
| `tests/` | 单元测试、适配器夹具和兼容性烟雾覆盖。 |
| `pyproject.toml`、`uv.lock` | Python 包元数据和锁定开发环境。 |
## 项目姿态
`llmwiki-serve` 是独立的社区工具，用于 LLMWiki 风格的 Markdown 知识文件夹。它是 Apache-2.0 许可的，并且不是 Andrej Karpathy 或兼容性示例中提到的任何上游生产者的官方项目。
该存储库处于公共源代码 checkout 预览阶段。源代码 checkout 使用是今日的支持路径。包安装命令在发布第一个 PyPI 版本后生效。使用托管的文档和发布状态和兼容性矩阵获取当前的包和协议姿态。
当前的协议表面是 HTTP 加上 MCP 风格的 JSON-RPC、MCP 流式 HTTP 和可选的 A2A 风格的消息形状。流式 HTTP 端点使用官方 MCP Python SDK FastMCP 传输；兼容性端点是本地代理和 harness 表面，而不是 A2A 认证、详尽的运行时功能完整性或上游生产者认证。
## 验证
快速源代码 checkout 烟雾测试：
```bash
uv run python scripts/check_third_party_notices.py
uv run python scripts/export_openapi.py --check
uv run python scripts/release_smoke.py
```
发布导向的本地门户：
```bash
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -q
uv build
uv run python scripts/release_smoke.py --wheel dist/*.whl --sdist dist/*.tar.gz
```
发布烟雾测试检查捆绑的示例 wiki，通过 CLI、HTTP、MCP 风格的 JSON-RPC、MCP 流式 HTTP 和可选的 A2A 风格的消息形状，包括草稿过滤、本地 CORS、MCP 错误减少、源不变性、源分发内容、OpenAPI 合同新鲜度和打包的轮子 CLI 安装。
可选验证路径在 [docs/release.md](docs/release.md) 中记录：实际本地服务器 curl 检查、公共上游样本快照烟雾和生成的候选样本工件。这些是兼容性探针，用于当前的服务合同。它们不认证上游生产者版本、全面的 MCP/A2A 协议支持或私有 wiki 安全、实时网络部署、身份验证、TLS 或每个应用程序特定的 Obsidian/Logseq/Foam/Dendron/Quartz 功能。
## 项目文档
- [文档门户](https://knowledge-bridge-labs.github.io/llmwiki-docs/)
- [发布状态和兼容性](https://knowledge-bridge-labs.github.io/llmwiki-docs/status)
- [架构](docs/architecture.md)
- [示例](examples/README.md)
- [发布检查清单](docs/release.md)
- [贡献](CONTRIBUTING.md)
- [安全](SECURITY.md)
- [支持](SUPPORT.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [变更日志](CHANGELOG.md)
## 许可
Apache-2.0。参见 [LICENSE](LICENSE)。
