anytype-llm-wiki

# anytype-llm-wiki <p align="center"> <a href="https://pypi.org/project/anytype-llm-wiki/"><img src="https://img.shields.io/pypi/v/anytype-llm-wiki?color=2b6fb6" alt="PyPI 版本"></a> <a href="https://pypi.org/project/anytype-llm-wiki/"><img src="https://img.shields.io/pypi/pyversions/anytype-llm-wiki" alt="Python 版本"></a> <a href="LICENSE"><img src="https://img.shields.io/pypi/l/anytype-llm-wiki" alt="许可证"></a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/Aldeia-IT/anytype-llm-wiki/main/docs/images/hero.jpg" alt="anytype-llm-wiki — 本地优先、类型化的第二大脑，适用于 Anytype" width="100%"> </p> **本地优先、类型化的 “[第二大脑](https://zh.wikipedia.org/wiki/%E7%AC%AC%E4%BA%8C%E5%A4%A7%E8%82%BD)”，适用于 [Anytype](https://anytype.io) — 面向人类和 AI 代理。** 它借鉴了 Andrej Karpathy 的 *LLM-wiki* 想法 — 让 LLM 编译您的资料来源，创建一个精选的、相互关联的知识库，您可以查询这个知识库 — 并在 Anytype 的原生 **对象、类型和关系** 上构建，而不是扁平的 Markdown 文件。所有内容都通过 [模型上下文协议](https://modelcontextprotocol.io)公开，因此 Claude Code、Cursor、任何 MCP 客户端 — 或您的自主代理 — 都可以读取和写入它。它完全在您的机器上运行。 ## 为什么选择类型化的图谱而不是扁平的笔记或普通的 RAG？ - **类型化的对象和双向关系 — 而不是文件。** 知识以 `实体`、`概念` 和 `来源` 对象形式存在，它们通过真实的、可遍历的关系链接在一个可查询的数据库中。Markdown 维基（Obsidian、Logseq）为您提供文本文件的反向链接；Anytype 为您提供类型化的知识图谱。 - **它检测矛盾。** 当新吸收的事实与已经链接的实体发生冲突时，**两个位置都被保留并相互链接** (`wiki_contradictions`)，并标记为审查 — 永远不会被静默覆盖。您的知识库会在内部存在分歧时通知您。扁平的维基和向量存储无法做到这一点。 - **引用的综合，而不是简单的搜索。** `wiki_query` 返回一个仅从您的维基中提取的答案，并引用它使用的确切对象 — 并且可以存档答案，以便维基每次被使用时变得更好。 - **本地优先。** Anytype + Ollama（嵌入和提取）+ Qdrant（向量），所有都在 `localhost` 上运行。默认情况下，您的机器上没有任何数据离开。 ## 用例 ### 1. 研究/知识维基（适用于您） 将来源（维基百科文章、论文、内部文档、您自己的笔记）指向它，它会将它们编译成类型化、相互链接的实体和概念 *以及出处*，在编译过程中进行重复数据删除和合并。然后用自然语言提问，获取仅从您的维基中综合的答案，每个答案都引用了它所引用的对象。这是 Karpathy 的 LLM-wiki 模式在一个真实的数据库上：图谱可以在 Anytype 中浏览，每个事实都可以追溯到来源。 → 路径：`wiki_bootstrap` → `wiki_ingest` → `wiki_query`（[演练](#5分钟体验））。 ### 2. 面向 AI 代理群的第二大脑 为自主代理提供一个**持久的、类型化的记忆，可以在会话之间存续**，并在项目之间共享。代理会叙述它们所学到的内容（`wiki_remember`）— 决策、持久的事实以及事物之间的关系 — 并在开始新工作之前通过引用（`wiki_query`）读取它。整合使得重复写入是安全的（它去重、取代、**标记矛盾而不是覆盖**），而定期的 `wiki_lint` 会显示矛盾和过时内容以供审查。一个大脑，一个矛盾感知的大脑，随着舰队的运行而不断完善。 → 路径：注册为 MCP 服务器，然后 `wiki_remember` / `wiki_query`。 > 这正是我们在 [Aldeia IT](https://github.com/Aldeia-IT) 中如何使用它的：作为自主 SDLC 代理群的共享长期记忆。 ### 3. 研究缓冲区，减少重复的网络搜索 研究一个主题，跨多个会话意味着反复从网络上重新获取相同的事实。将发现内容一次性吸收，维基就变成了**本地的、引用的缓存**：未来的问题首先从累积的知识中得到答案，实时网络搜索仅用于真正的空白 — 更少的令牌，更快的答案，以及一个出处轨迹。 → 具体示例：一个 **卡波耶拉谱系** 研究项目将其用作这种缓冲区 — 缓存谱系和历史研究，以便避免重复的 LLM 网络搜索。 ## 工作原理 所有内容都**本地运行** — 没有机器外部的数据输出。MCP 客户端调用 `anytype-llm-wiki` 服务器，它协调三个本地后端：**Anytype** （类型化知识图谱）、**Ollama** （提取/推理 LLM + 嵌入）和 **Qdrant** （向量）。  问题仅从您的维基中回答 **，并附有引用** — 并且 Q&A 可以被**存档**，以便未来的问题可以从中检索。维基变得越多越有用，您使用它的次数越多：  > 📊 **[完整视觉指南 →](docs/diagrams.md)** — 编写管道、类型化对象模型和自我审计健康检查。 对象在其 **属性** 中承载知识（`wiki_facts`、`wiki_definition` 等），而不是在对象正文中 — 因此导出的对象在 Anytype 客户端中显示为空正文，这是设计使然；内容被完全索引和可检索。 ## 快速入门 ### 先决条件 - [Anytype](https://anytype.io) 桌面版（端口 31012 上的 REST API） - [Ollama](https://ollama.ai) 带有嵌入模型：`ollama pull bge-m3`（提取还使用一个小型本地生成模型，例如 `ollama pull qwen2.5:7b`） - [Qdrant](https://qdrant.tech)：`docker run -p 6333:6333 qdrant/qdrant` ### 安装 从 [PyPI](https://pypi.org/project/anytype-llm-wiki/) — 这会在您的 PATH 上安装一个 `anytype-llm-wiki` 命令： ```bash uv tool install anytype-llm-wiki # 或：pipx install anytype-llm-wiki ``` <details> <summary>或从源代码运行（用于开发）</summary> ```bash git clone https://github.com/Aldeia-IT/anytype-llm-wiki.git cd anytype-llm-wiki uv sync ``` 然后在下面的命令前加上 `uv run`（例如 `uv run anytype-llm-wiki doctor`）。 </details> 运行 `anytype-llm-wiki` **不带子命令** 启动通过 stdio 的 MCP 服务器。 ### 配置 创建一个 `.env` 文件（仅 `ANYTYPE_API_KEY` 是必需的）： ```bash ANYTYPE_API_KEY=您的-anytype-api-key # Anytype → 设置 → API # 可选（显示默认值）： ANYTYPE_API_URL=http://127.0.0.1:31012 QDRANT_URL=http://127.0.0.1:6333 OLLAMA_URL=http://127.0.0.1:11434 EMBED_MODEL=bge-m3 ``` ### 验证和配置 ```bash anytype-llm-wiki doctor # 只读预检查（Anytype、Qdrant、Ollama） anytype-llm-wiki wiki-bootstrap --space-id <id> # 幂等地创建类型化的维基模式 ``` `wiki-bootstrap` 可以安全地重新运行 — 它会将空间与预期的模式相协调，而不会创建重复项。在更改模式的升级后重新运行它（CHANGELOG 会标记那些更改）。 ### 注册为 MCP 服务器 **Claude Code:** ```bash claude mcp add anytype-llm-wiki -e ANYTYPE_API_KEY=您的密钥 -- anytype-llm-wiki ``` **Claude Desktop / Cursor / 其他客户端** — 将其添加到您的 MCP 配置： ```json { "anytype-llm-wiki": { "command": "anytype-llm-wiki", "env": { "ANYTYPE_API_KEY": "您的密钥" } } } ``` > 无需安装？`uvx anytype-llm-wiki` 直接从 PyPI 运行最新版本 — 在 JSON 配置中使用 `"command": "uvx", "args": ["anytype-llm-wiki"]`。 ### 5 分钟体验 **构建研究维基并查询它**（从空空间）： ```bash # 1. 配置类型化的模式。 anytype-llm-wiki wiki-bootstrap --space-id <id> # 2. 编译来源为类型化、相互链接的对象（自动重新索引）。 anytype-llm-wiki wiki-ingest --space-id <id> \ --source https://en.wikipedia.org/wiki/Retrieval-augmented_generation # 3. 提问 — 仅从您的维基中回答，并附有引用。 # --file-back 存储 Q&A，以便未来查询可以检索它。 anytype-llm-wiki wiki-query --space-id <id> \ --question "什么是检索增强生成？" --file-back ``` **给予代理记忆** — 一旦通过 MCP 注册，您的代理就可以： ``` wiki_remember(space_id, "Qdrant 1.12 通过有效载荷分区添加了原生多租户支持。", subject_hint="Qdrant") wiki_query(space_id, "我们对 Qdrant 多租户了解什么？") ``` ## MCP 工具 | 工具 | 功能 | |------|--------------| | `semantic_search` | 按含义搜索保险库。`query`、`space_id?`、`types?`、`ingested_after?`、`ingested_before?`、`source_type?`、`domain_tags?`、`limit?` （默认结果不包括 `wiki_source` 摘录，除非给定 `types=["wiki_source"]` 或 `source_type`） | | `reindex_anytype` | 触发增量重新索引。`space_id?` | | `wiki_bootstrap` | 在空间中配置类型化的维基模式。`space_id`、`domain_tags?` | | `wiki_ingest` | 将来源（URL 或文件）编译为精选的、相互链接的对象，并具有出处；自动重新索引。`source`、`space_id`、`domain_hint?` | | `wiki_remember` | 将代理的自然语言叙述整合为类型化的对象（LLM 合并/重复数据删除/冲突标记）。舰队安全的 **队列提交**：并发写入者永远不会阻塞或丢失写入（无读后写）。`space_id`、`knowledge`、`subject_hint?`、`kind?`、`relations?`、`domain_tags?`、`source?` | | `wiki_query` | 查询维基以获取综合的、来源引用的答案（分层检索 + 本地综合）；可选地存档答案。`question`、`space_id`、`file_back?`、`types?`、`ingested_after?`、`ingested_before?`、`source_type?` （无操作 — 接受 API 对称性）、`domain_tags?` | | `wiki_lint` | 只读结构健康检查（矛盾、孤立、陈旧、非对称关系 ...），按严重性排序。`space_id`、`severity_threshold?`、`include_duplicates?` | 提取和综合默认在本地 Ollama 上运行（`WIKI_EXTRACT_MODEL`，默认为 `qwen2.5:7b`）；将 `WIKI_EXTRACT_ENDPOINT` 指向托管的 API 会将此处理移出机器，并在一次性同意门后进行 — 请参阅 [安全性和数据流](docs/security-and-data-flow.md)。 ## 值得了解的关键行为 - **矛盾检测是自动的，但有范围。** 在摄入时，当更新的 **实体或概念** 的新事实/定义与其已链接的对等体发生冲突时，两个位置都会被交叉链接到 `wiki_contradictions` 并标记为审查 — 永远不会被静默覆盖。检测仅限于 **已链接的对等体** — 如果对象与未链接的内容发生冲突，则不会立即显示发现。实体和概念矛盾现在都由 `wiki_lint` （严重性 `critical`）标记，并通过在对象上设置 `wiki_last_reviewed` 来解决。它们也被记录在 `wiki_contradictions` 中，并在 Anytype 中可浏览。不要过度信任干净的矛盾列。 - **引用的综合 + 复合循环。** `wiki_query` 仅从检索到的对象中回答，并引用它们在 `sources_consulted` 中 — 包括实际提供答案的 1 跳邻居，而不仅仅是 top-k 种子，因此引用列表诚实地反映了答案从哪些对象中得出（邻居扩展由 `WIKI_QUERY_MAX_NEIGHBORS` 限制，默认为 16，并确定性地排序）。存档仍然只记录种子对象，因此 `wiki_drew_from` 保持种子范围。干净的答案如果满足存档门槛（≥ 3 个引用的来源 **和** ≥ 100 个单词，或 `file_back=True`），则存储为类型化的查询对象；下一次重新索引后，它本身就变得可检索 — 因此维基随着使用而改进。对引用标题和深链接视为不受信任的数据 — 显示它们，但不要自动跟随深链接为受信任。 （存档的答案仅在重新索引后显示 — 请参阅 [已知限制](docs/known-limitations.md)。） - **安全的重复写入（`wiki_remember`）。** 重述的重复数据会被合并，新的事实会被追加，取代的事实会替换（先前的文本被记录在 WikiLog 中并可恢复），矛盾会被标记而不是覆盖，并且重新断言相同的知识会收敛到无操作。 - **舰队安全的并发写入（无读后写）。** 独立代理在单独的 PID/终端上可以同时 `wiki_remember` 相同的空间：每个代理都持久地将其主题排队（一个无锁追加到工作日志），而持有空间锁的进程会排空它们 — 没有人会阻塞，没有人的学习会被丢弃。提交可能会在主题应用之前返回，因此之后的 `wiki_query` 可能还看不到它们（维基是为下一个代理，而不是提交者自己的下一行准备的）。仅限于同一主机 — 请参阅 [已知限制](docs/known-limitations.md)。`wiki-drain` CLI 在需要时强制同步排空。 - **分层检索。** 在 `WIKI_INDEX_THRESHOLD`（默认 200）以下，`wiki_query` 直接读取整个维基（详尽且快速）；在它之上，它使用向量搜索和 1 跳邻居扩展。 - **增量、可调度的索引。** 只有更改的对象会被重新嵌入。对于连续索引，请在计划（cron/launchd — 样本 launchd plist 位于 [`docs/samples/com.aldeia.anytype-llm-wiki-reindex.plist`](docs/samples/com.aldeia.anytype-llm-wiki-reindex.plist)）上运行 `reindex_anytype`。对于高代理写入率，请设置 `WIKI_AUTO_REINDEX=false` 并批量调度重索引，因为重索引成本随总空间大小而缩放。 ## 性能 在 Mac Mini（Apple Silicon）上基准测试： | 操作 | 时间 | |-----------|------| | 单次搜索查询 | **0.22s** | | 索引 50 个块 | 0.73s | | 完整重索引（500 个块） | ~7s | ## 配置 `ANYTYPE_API_KEY` 是唯一必需的变量；合理的默认值涵盖了其他变量。 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `ANYTYPE_API_URL` | `http://127.0.0.1:31012` | Anytype REST API 端点 | | `QDRANT_URL` | `http://127.0.0.1:6333` | Qdrant 端点 | | `OLLAMA_URL` | `http://127.0.0.1:11434` | Ollama 端点 | | `EMBED_MODEL` / `EMBED_DIMS` | `bge-m3` / `1024` | 嵌入模型及其向量维度（必须匹配） | | `WIKI_EXTRACT_MODEL` | `qwen2.5:7b` | 用于提取/综合/整合的本地模型 | | `WIKI_ALIAS_ADJUDICATION` | `off` | **⚠️ 实验性 — 请自担风险启用。** 实体解析中的 LLM 别名合并（步骤 3）。默认关闭。仅在已验证的模型上运行；**启用它将使 MCP 服务器拒绝启动**（大声的 `[CONFIG ERROR]`）。有关警告，请参阅下文。 | | `WIKI_ALIAS_VETTED_MODELS` | _(空)_ | 用于别名裁决的额外提取模型前缀的逗号分隔列表，与内置的 `qwen3.5-mlx` 联合。添加您的模型在这里是覆盖项（没有强制标志）。 | > **⚠️ `WIKI_ALIAS_ADJUDICATION` 是实验性的 — 请勿启用，除非您接受风险。** > *它做什么：* 在写入时，当精确和模糊标题匹配找不到现有对象时，它会询问本地 LLM，判断新实体是否与词汇相似的现有实体是**同一实体**（别名/缩写/重命名），如果是，则**合并**到它，而不是创建重复项 — 自动捕获 `k8s` → `Kubernetes` 之类的重复项。 > *风险：* 判断是**破坏性和不可逆转**的（永远不会创建新对象），即使是验证过的模型，**过度合并不同的实体**在真实、凌乱的数据上（在 ~7-10% 的真实图谱中观察到 — 例如，将人合并到同名的项目中，将测试网合并到其主网，或将集合合并到其成员之一）。它故意保守并在默认关闭标志 + 验证模型启动检查后面，但**它仍然可以破坏您的图谱**。对于管理，我们建议**非破坏性**路径：`wiki_lint --include-duplicates`，它只会**显示** `potential_duplicate` 建议供人类审查和合并。 | `WIKI_EXTRACT_ENDPOINT` | *(未设置 → 本地 Ollama)* | 托管的 LLM 端点用于提取（机器外部；有同意门控） | | `WIKI_INDEX_THRESHOLD` | `200` | `wiki_query` 从第 1 层切换到第 2 层的位置 | | `WIKI_QUERY_MAX_NEIGHBORS` | `16` | `wiki_query` 可以扩展和引用每个查询的不同 1 跳邻居的最大数量 | | `WIKI_AUTO_REINDEX` | `true` | 每次写入后自动重索引（设置为 `false` 以通过计划的重索引进行批处理） | | `WIKI_LOCK_DIR` / `WIKI_WORKLOG_DIR` | `~/.local/share/anytype-llm-wiki/{locks,worklog}` | 主机本地锁定 + 持久主题工作日志。共享同一保险库的同一主机代理群**必须共享两者**（请参阅 [已知限制 §10](docs/known-limitations.md)）；工作日志暂时保存叙述内容 — 视为敏感（[数据流](docs/security-and-data-flow.md)）。 | 附加的 `WIKI_SYNTH_*` 和 `WIKI_LINT_*` 调整旋钮存在具有合理的默认值 — 通常您不需要它们。 ## 架构 - **Anytype 客户端** — 通过 REST API 读取/写入对象；处理分页和身份验证。 - **分块器** — 按标题分割 markdown，默认为段落；每个块都带有对象/空间/类型/标题元数据。 - **嵌入器/索引器** — Ollama `/api/embed`；增量式，按 `last_modified_date` 索引，仅更改的对象重新嵌入，删除的对象清理向量。 - **维基管道** — LLM 提取 → 实体/概念解析 → 类型化对象与双向关系 → 矛盾检测 → 引用的综合。 - **MCP 服务器** — FastMCP 通过 stdio，公开上述七种工具。 - **doctor** — 只读预检查（Anytype、Qdrant、Ollama、嵌入模型）。 📊 **[架构 — 视觉指南](docs/diagrams.md)** — 组件图、读写管道、类型化对象模型和健康检查。 有关内部工作原理 — 编写管道、一致性如何纠正现实、实体解析和重复数据删除、并发模型和无丢弃主题工作日志 — 请参阅 [**架构和内部工作原理**](docs/architecture.md)。 ## 供应链状况 依赖项被锁定在两层：**`uv.lock`** 将所有直接和传递依赖项锁定到确切的、基于内容哈希的版本（CI 运行 `uv lock --check`），而 **`pyproject.toml`** 则声明了与下一主要版本的兼容范围上限，以防止传递解析时静默跨越主要版本。发布工件在无缓存的情况下构建，并使用 [SLSA 构建溯源证明](https://docs.github.com/actions/security-guides/using-artifact-attestations) 进行签名；一旦轮子发布完成，您将能够针对此仓库使用 `gh attestation verify` 进行验证。 ## 路线图 - 混合搜索 — 元数据过滤（对象类型 + 日期范围）现已推出；关键词/稀疏融合仍在路线图中 (#327)；标签/来源过滤在 #336 中跟踪 - 超出链接对等体的矛盾检测（语义预过滤） - 跨空间联合身份验证和访问控制 - 当 Anytype 添加 webhook 支持时，基于 webhook 的索引 查看 [GitHub Releases](https://github.com/Aldeia-IT/anytype-llm-wiki/releases) 和 [CHANGELOG](CHANGELOG.md) 以了解已发布的更新。 ## 比较 | | anytype-llm-wiki | 基于文件的 wiki（Obsidian / Logseq） | 普通向量 RAG | |--|------------------|-----------------------------------|------------------| | 存储 | 类型化的 Anytype 对象 + 关系 | Markdown 文件 + 反向链接 | 向量数据库中的块 | | 知识模型 | 查询图中的实体/概念 | 您手动组织的文档 | 不透明的块 | | 矛盾处理 | **检测并交叉链接以供审查** | 无 | 无 | | 答案 | **合成，具有对象引用** | 您阅读并连接 | 检索到的片段 | | 代理读取 **和** 写入 | **是（MCP）** | 手动 | 主要是读取 | | 本地优先 | 是（Ollama + Qdrant） | 是 | 取决于具体实现 | 它还与像 [`anyproto/anytype-mcp`](https://github.com/anyproto/anytype-mcp)（对象 CRUD，无语义/向量搜索）和 [`wethegreenpeople/anytype-mcp`](https://github.com/wethegreenpeople/anytype-mcp)（ChromaDB，启动时完全重新嵌入）这样的 API 访问 MCP 不同：嵌入式语义检索 **加** 类型化的 wiki 流水线是核心差异化因素。 ## 贡献 由 [Aldeia IT](https://github.com/Aldeia-IT) 维护，供我们自己使用并公开发布。我们 **目前不积极征求贡献**，可能对问题和 PR 的回复较慢 — 但您可以 fork 它。**安全问题：** 请使用 [私募报告](SECURITY.md)，而不是公开问题。开发设置和期望在 [CONTRIBUTING.md](CONTRIBUTING.md) 中；请友善（[行为准则](CODE_OF_CONDUCT.md)）。 ## 许可证 MIT。有关贡献许可（入站 = 出站）的详细信息，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 商标 Anytype 是 Any Association 的商标。本项目与 Any Association 或 Anytype 项目无关联、未获得赞助或认可；本项目仅使用该名称来标识此软件所集成的平台。