定义：Semibot 的知识库基于 Karpathy LLM Wiki 协议构建：原始素材存储在 raw/ 目录中，Agent 在 wiki/ 目录中维护有组织的主题文章。这不是一次性的「生成一份报告」工作流——而是持续的知识维护。Agent 可以摄入新材料、更新现有文章、保留修订日志，用户全程可以看到知识成形的过程。知识不是被一次性生产出来的，而是在持续使用中不断生长和修正的。
一个工作区中的三种模式
知识库在同一个工作区中提供三种能力，每一种对应不同的使用场景：
- 浏览：真实的文件夹树，支持文件预览。保留用户对目录和文件的心智模型。你可以像操作普通文件管理器一样展开目录、点击文件、查看内容。这种设计的好处是直觉——不需要学习新的界面范式。
- 搜索：跨单个或所有工作区的混合语义搜索。从原始素材和 Wiki 文章中找到相关内容。搜索既理解关键词精确匹配，也理解语义相似——即使你用不同的措辞描述同一件事，搜索也能找到相关材料。
- Wiki：由 Agent 通过 Ingest/Query/Lint 生命周期维护的、持续组织的、可溯源来源的主题文章。这是知识库的核心能力——不是简单的文档存储，而是有生命力的知识组织。
raw/wiki 协议
协议的结构很简单，但每个部分都有明确的职责：
- raw/：技能抓取并保存的原始素材，按主题组织。这些是未经加工的来源材料——网页快照、PDF 提取、API 返回的结构化数据等。原始素材保持原貌，不被修改或美化。
- wiki/：技能维护的知识文章。每篇文章围绕一个主题，内容经过组织和归纳，附带来源链接。文章会随着新素材的摄入而持续更新。
- wiki/index.md：人类可读的全局索引。列出所有文章的标题和摘要，方便快速浏览整个知识库的结构。
- wiki/log.md：技能的维护历史和断点笔记。记录每次 ingest、lint 和编辑操作，以及遇到的问题和处理方式。这是知识库的审计日志。
知识库的生命周期由五个操作组成。Ingest 抓取新材料并放入 raw/ 目录。Triage 决定新材料的去向——是创建新文章、合并到现有文章、还是标记为待处理。Compile 生成或更新文章。Query 通过引用 Wiki 内容来回答问题。Lint 检查和修复现有文章——修正过时信息、补充缺失来源、解决文章之间的矛盾。技能直接在这些目录上操作——没有暂存区、没有生成流水线、没有自动回滚。每一步操作都立即反映在文件系统中，用户随时可以看到当前状态。
用户心智模型：看着知识成形
在 Wiki 更新过程中，用户可能会短暂看到半成品状态——一篇正在被编辑的文章、一个尚未完成的索引条目、一段临时的占位文本。这是有意为之的：它反映了知识维护的真实工作状态。
替代方案——隐藏所有中间工作、只展示完成的文章——会产生「生成后遗忘」的循环。在那种模式下，用户看到的永远是成品，无法理解知识库的结构和演化过程。这导致两个问题：第一，用户不知道知识库里有什么、缺什么，无法有效地引导 Agent 补充缺失的知识；第二，用户无法验证文章的质量，因为看不到推理过程和来源链路。
「看着知识成形」的心智模型让用户成为知识维护的参与者而不仅仅是消费者。你可以中途介入、修正方向、补充素材，而不是等成品出来后再质疑。这种透明性是 Wiki 模式和传统报告生成模式的根本区别。
搜索投影
搜索索引是一个派生投影：它可以随时从 raw/ 和 wiki/ 中重建。这意味着搜索索引是二等公民——它的存在是为了加速查询，但它不是知识的权威来源。raw/ 和 wiki/ 中的文件才是。
如果搜索投影更新失败，Wiki 更新不受影响。这种分离意味着知识维护和搜索索引可以独立失败，而不会互相破坏。搜索索引坏了，知识还在；Wiki 更新卡住了，搜索还能用旧索引工作。这种容错设计确保了知识库在部分组件出问题时仍然可用。
本地优先的知识
Wiki 位于工作区的 .semibot/knowledge/ 目录中。Agent 的工作目录固定在此位置。原始素材、文章、索引和日志都是本地文件，用普通的 Markdown 格式存储。如果用户之后切换到其他工具，原始文件仍然在本机上——它们不是某种私有格式，任何文本编辑器都能打开。
本地优先的含义不只是「数据在本机」。它意味着知识库的读写不依赖网络、不依赖云端服务、不依赖特定厂商的服务器。即使你断网了，你仍然可以浏览和编辑知识库。即使 Semibot 停止运营，你的知识文件仍然完好无损地在你的磁盘上。这是本地优先设计的核心承诺：你的知识属于你，不被锁定在任何平台上。
局限性
- Wiki 的质量取决于模型组织和归纳总结的能力。素材质量差或过于稀疏，产出的文章就会粗糙。Agent 不会凭空编造内容来填补素材的空白。
- 没有人工编辑界面。Agent 自主维护文章。用户可以手动用文本编辑器打开 Markdown 文件进行编辑，Agent 在下一个 ingest 周期会看到修改，但没有实时协作编辑、冲突合并或修订追踪的界面。
- 「没有素材」是一个有效的结果——技能不会凭空强行创建文章。如果素材不足，技能会如实记录而不是编造内容。
- 修订历史基于日志文件（log.md），而非 Git 风格的版本控制。没有 diff 视图、分支合并或一键回滚界面。要恢复到某个历史状态，需要手动操作。
直接维护模型与真源分离
Semibot 知识库 Wiki 的核心架构决策是「直接维护」：原始材料（raw/）与知识文章（wiki/）是唯一真实状态，没有暂存区、没有生成后发布、没有自动回滚。整理过程对用户实时可见，更新中途出现半完成状态被视为 Wiki 的真实工作状态而非缺陷；运行中断时保留已完成的部分，下一次从原地继续。这套设计的赌注是透明大于整洁——用户看见的正是系统正在做的。
组织契约借自 Karpathy 的 LLM Wiki 实践：全局索引与维护日志两个锚点文件，材料经过「获取 → 分诊 → 按需编译」进入知识文章，每篇文章维护来源引用与交叉链接；对每份材料只有四种合法结论——新知识、更新、有争议、无实质（最后一种是合法结果，不是失败）。溯源在界面上一等呈现：文章显示来源与更新时间，点击来源直接打开原始文档。
两个实现细节值得单独记录。其一，SQLite 只保存运行状态与已处理来源的版本游标，搜索索引与向量是可随时从文件重建的派生投影——真源永远是 Markdown 文件。其二，增量更新为每个来源建立独立的处理会话，提示里只含变化类型与相对路径、不内嵌正文：这是对「把大量文件名塞进一个提示导致整体假处理」这一失败模式的直接防御。检索侧，Wiki 文章作为受信系统来源与原始资料一同进入混合检索（语义检索加关键词检索，重排序融合），Wiki 不替代原文——两种召回并存，结论可溯源到其中之一。
FAQ
这和 RAG 系统一样吗？
不完全一样。RAG（检索增强生成）做的是检索相关片段并将上下文传递给模型来生成回答。Wiki 模式维护的是作为持久知识结构的有组织文章——它们不是临时拼接的上下文，而是可以独立阅读、持续更新的文档。两者可以协同工作：Wiki 提供结构化的主题知识，RAG 提供原始素材的语义搜索。
我能编辑 Wiki 文章吗？
可以。它们是磁盘上的普通 Markdown 文件，用任何文本编辑器都能打开和修改。Agent 会在下一个 ingest 周期看到你的编辑，并在后续维护中考虑你的修改。你甚至可以直接创建新文章——Agent 会在下一次 lint 中发现它们并纳入维护范围。
当新信息到来时，旧文章会怎样？
Lint 周期会用新来源检查现有文章，可以更新过时的内容、扩展不完整的章节、或标记与其他来源的矛盾之处。文章不是冻结的——它们会随着新信息的到来而演化。如果一篇文章和新素材产生冲突，Agent 会在文章中标记矛盾并注明来源，而不是简单地用新内容覆盖旧内容。
Wiki 会保持在本地吗？
是的。Wiki 在工作区本地的 .semibot/knowledge/ 目录中，全部是普通文件。只有模型 API 调用（如果使用云端模型）涉及网络传输——知识文件本身始终在你的磁盘上。如果你接入的是本地模型服务，整个知识库的工作流可以完全在本地完成。
多个工作区的知识能互通吗？
每个工作区有自己独立的知识库目录。搜索功能支持跨工作区查询，可以在多个知识库中找到相关内容。但文章的维护是按工作区独立进行的——一个工作区的 Agent 不会自动修改另一个工作区的文章。这种隔离确保了不同项目之间的知识不会意外混在一起。