Stigmergy：为团队打造会主动浮现知识的LLM Wiki

如果你最近在关注大模型应用，大概率听过 Andrej Karpathy 多次提到的“LLM wiki”概念：让大模型变成你的私人图书馆管理员，在你写作时实时检索、联想背景、补充材料。这个想法听起来迷人，但它有一个默认前提——这些知识只属于一个人。

那么问题来了：一个团队能不能也拥有这样的 LLM wiki？当知识分散在十个、二十个成员的头脑里，散落在文档、会议记录、代码注释和聊天记录里，大模型还能不能扮演那个“图书馆管理员”？

这就是今天要聊的项目 Stigmergy 正在回答的问题。它是一个面向团队、而非个人的 Karpathy 风格 LLM wiki。项目一发布就登上了 Hacker News 首页，标题里那句 “for a team, not one person” 非常精准地戳中了当前知识管理工具的断层。

我的判断是：Stigmergy 真正有意思的地方，不在于“用 LLM 检索 wiki”这层表面功能，而在于它把生物学里的“间接协同”机制搬到了团队知识库设计里。这篇文章会从概念、架构、实践部署、适用边界四个角度，把它拆开讲清楚。读完你不仅能判断这个项目是否适合你的团队，还能知道如果自己动手做一个团队 LLM wiki，核心设计点应该落在哪里。

1. 这篇文章真正要解决的问题

先说一个很多团队都经历过的痛。

团队 wiki 或知识库，最典型的状态是：创建初期热火朝天，三个月后开始长草，半年后没人看了。不是大家不想写，而是“写文档”这件事在团队协作里有一个根本性矛盾——写的时候没有即时回报，读的时候又找不到想要的答案。你花半小时写的部署文档，可能直到三个月后别人踩坑时才会被翻开；而等你真的需要某条信息时，又不知道该去 wiki 搜索、翻聊天记录，还是直接问同事。

传统方案是流程驱动：强制要求写周报、写文档、定期 review。这套方法能维持知识的“存在”，但维持不了知识的“流动”。知识一旦被写下来就变成静态文件，和人脑里的上下文脱节。

Karpathy 提出的 LLM wiki 范式，本质上是给个人知识库加了一个“实时上下文层”。当你写文章、写代码、做笔记时，LLM 会基于你已有的知识库，主动给你提供相关背景、材料、甚至反驳意见。这个交互是低摩擦的：你不用专门去“检索”什么，知识会在你需要的时候自己浮现。

但这个范式放到团队里，会碰到三个个人场景没有的难题：

第一，知识所有权分散。一个知识点可能散落在 A 的头脑、B 的文档、C 的聊天记录里，没有任何一个人拥有全貌。

第二，写入动力不足。个人笔记是写给未来的自己看，收益明确；团队文档是写给“不确定的读者”看，收益模糊。

第三，上下文是稀疏的。个人知识库可以假设“我自己了解背景”，团队知识库必须考虑“新同事什么都不了解”。

Stigmergy 这个项目的价值，就是尝试回答：如何设计一套激励机制和空间结构，让团队成员在不知不觉中留下知识痕迹，让 LLM 有能力把这些痕迹组织成可用的团队上下文。

这篇文章最该读的读者，是正在搭建团队知识库、内部工具平台，或者对“LLM Agent + 知识管理”方向感兴趣的开发者。如果你只是一个人用，那 Karpathy 原版的个人 wiki 思路可能更合适；但如果你在负责团队的内部知识体系建设，Stigmergy 的很多设计取舍值得你仔细看。

2. Stigmergy 不是什么玄学概念：从蚂蚁、维基到 LLM

很多人第一次看到 Stigmergy 这个单词会以为是个生造词，其实它是一个正经的生物学概念，中文通常翻译为“间接协同”或“斯托墨吉”。

这个概念最早由生物学家 Pierre-Paul Grassé 在 1959 年研究白蚁筑巢行为时提出。他发现白蚁个体之间并没有直接沟通，但每只白蚁在环境中留下的痕迹，会反过来影响其他白蚁的行为。简单说就是：个体通过修改环境来影响同伴，同伴再继续修改环境，形成一个良性循环。

最经典的例子是蚂蚁觅食。蚂蚁在爬行时会分泌信息素，其他蚂蚁会沿着信息素浓度更高的路径前进，走过的蚂蚁又会继续留下信息素。这条路越多人走，信息素越浓，于是更多蚂蚁被吸引过来。整个过程没有“领导指挥”，没有“蚂蚁开会”，但群体却展现出了惊人的协作能力。

把它抽象出来，Stigmergy 有三个关键特征：

• 工作产物即沟通媒介：蚂蚁不用“说话”，留下的痕迹本身就是信息。
• 增量积累：每只蚂蚁都在已有成果上做微小贡献，不需要推倒重来。
• 环境驱动行为：个体看到环境中的痕迹，会自然知道该做什么。

这套机制放到知识管理里是非常有意思的映射：

生物学特征	传统团队 wiki	Stigmergy 式团队 LLM wiki
沟通媒介	聊天、开会、文档	任何人修改过的知识痕迹
增量积累	依赖个人自觉	通过低摩擦写入机制鼓励累积
环境驱动	需要主动搜索	LLM 在写作上下文中唤起相关知识

这也是为什么这个项目要叫 Stigmergy 而不是叫“TeamLLMWiki”。它想表达的是：团队知识库不应该靠“命令”和“流程”来维护，而应该靠让知识痕迹自然沉淀、自然被复用、自然吸引更多人参与。

在这个意义上，wiki 本身就有 Stigmergy 的属性。维基百科的运行机制就是典型的间接协同：每个人编辑一个小段落，链接结构逐渐覆盖全领域，后来者沿着链接继续补充。Stigmergy 做的事情，是用 LLM 把这个“链接图”升级成“语义网络”，让知识的关联和响应可以通过大模型自然浮现，而不需要人类手动去维护目录结构和标签体系。

所以，它并不是一个“用 LLM 套壳的 wiki”那么表面，它是在回答一个更本质的问题：在一个团队里，知识的痕迹应该以什么形式存在，才能最大化被复用？

3. Karpathy 式 LLM wiki：到底在讲什么

要理解 Stigmergy，必须先理解它致敬的“Karpathy 式 LLM wiki”是什么。

Andrej Karpathy 在多个场合表达过一个场景化的设想：如果你有一个长期积累的个人知识库，涵盖了你的笔记、文章、代码、读过的书、过去的想法，LLM 可以在你写作或思考时实时介入。它不只是被动地等你提问，而是主动地“翻看”你的资料库，在你写下一段话时提醒你：“你在三年前写过一篇相关的笔记”“这篇文章的数据和你的旧结论有冲突”“这个方向你过去尝试过但放弃了”。

这里有几个重要的技术前提：

第一，知识库已经存在。LLM 本身没有你的记忆，它必须有一个可以检索的外部存储。这也是个人 wiki 类应用和大模型结合的核心——用向量化和检索把私有知识变成 LLM 的“外挂记忆”。

第二，交互是低摩擦的。Karpathy 强调的不是“你问它答”，而是 LLM 主动提供上下文。这会改变写作体验：你不是面对一张白纸，而是面对一个熟悉你绝大部分思考过程的“合作者”。

第三，价值来源于时间积累。个人笔记用久了才有价值，因为 LLM 需要足够多的素材才能做出有价值的联想。第一天用的时候，它基本帮不上什么忙。

这个设想让“LLM wiki”成为最近 AI 知识管理领域的热词。Obsidian、Notion 等工具纷纷推出 AI 插件，很多开源项目也在做“个人知识库 + LLM Agent”的组合。如果你搜索“LLM wiki Obsidian 插件”，能看到大量把笔记应用和大模型检索结合的项目。

但注意，Karpathy 的这个设想里有一个隐性前提：这个知识库只服务一个人。

个人知识库的检索可以非常激进。因为内容都是自己的，即使 LLM 返回的上下文有点偏差，你也能迅速判断对错。你不用担心隐私边界，不用考虑别人会不会误解你的笔记，也不用担心某个知识点过时了会误导同事。

团队场景完全不同。一个团队 wiki 要同时服务：刚入职的新人、负责不同模块的同事、跨团队协作的伙伴。同一段知识，对不同角色有不同含义。LLM 如果只是机械地把检索结果拼进回答里，非常容易产生“看起来合理、实际误导”的严重后果。

所以，Stigmergy 并不是简单地把个人 LLM wiki 的多用户版做出来，而是要在团队环境下重建“知识痕迹”的流动方式。这也是为什么它的创始人选用了Stigmergy这个生物学概念作为项目名——它暗示了这个项目的核心不是“检索技术”而是“协作机制”。

4. 团队 LLM wiki 的核心架构设计

虽然 Stigmergy 具体的技术栈和目录结构需要以项目 README 为准，但我们可以从它的定位和目标出发，推导出一个团队 LLM wiki 应该具备的核心架构层次。

4.1 知识层：以文本文件为知识的物理载体

团队 wiki 知识层的第一选择，我强烈建议使用 Markdown 纯文本文件，而不是直接使用数据库。

原因有几个：

• 纯文本可读、可 diff、可追踪变更历史。
• Git 天然适合做多人在线编辑、分支、合并。
• 文本是 LLM 最容易处理的格式，不需要额外做格式解析。
• 即使 LLM 中断，知识文件本身仍然可读，不会变成“锁死的数据”。

一个典型的目录结构可以是这样：

team-wiki/ ├── docs/ # 正式文档 │ ├── architecture/ │ │ └── payment-service.md │ ├── runbooks/ │ │ └── db-failover.md │ └── decisions/ │ └── 2025-04-use-postgres.md ├── notes/ # 轻量笔记，允许不完美 │ └── meeting-2025-04-02.md ├── snippets/ # 代码片段和配置片段 │ └── nginx-reload.md └── README.md # 团队知识库入口

这个结构的好处是：正式文档、过程笔记、代码片段之间是弱耦合的，任何人可以在任意层级追加内容。它不要求所有内容“一步到位”，而是允许知识以任何粗糙的形态先沉淀下来。

4.2 索引层：把文档洗成可检索的向量索引

要让 LLM 回答与团队知识相关的问题，最基础的做法是 RAG（检索增强生成）。流程是：

• 将文档按标题、段落切分成块（chunk）。
• 用嵌入模型（embedding model）将文本块向量化。
• 存入向量数据库。
• 用户提问时，先做向量相似度检索，找到最相关的文本块。
• 把文本块作为上下文拼进 prompt，交给 LLM 生成答案。

# 文件路径：scripts/build_index.py # 说明：示意脚本，演示"文档 -> 文本块 -> 向量 -> 向量库"的基本过程 # 实际实现请参考项目的 README 或选择你自己熟悉的技术栈 import os from pathlib import Path def chunk_text(text: str, max_chars: int = 800) -> list[str]: """按最大长度切分文本，优先在换行处分段。""" paragraphs = text.split("\n") chunks = [] current = "" for para in paragraphs: if len(current) + len(para) + 1 > max_chars: if current: chunks.append(current.strip()) current = para else: current = current + "\n" + para if current.strip(): chunks.append(current.strip()) return chunks def load_wiki_docs(root_dir: str) -> list[dict]: """遍历 wiki 目录，加载所有 Markdown 文件。""" docs = [] base = Path(root_dir) for path in base.rglob("*.md"): text = path.read_text(encoding="utf-8") chunks = chunk_text(text) for idx, chunk in enumerate(chunks): docs.append({ "source": str(path.relative_to(base)), "chunk_index": idx, "text": chunk, }) return docs if __name__ == "__main__": # 用法：python scripts/build_index.py /path/to/team-wiki import sys wiki_dir = sys.argv[1] docs = load_wiki_docs(wiki_dir) print(f"共加载 {len(docs)} 个文本块") # 下一步：调用嵌入模型将 docs 写入向量数据库

注意，上面的代码只完成了最基础的切分和加载。真正的系统还要考虑：

• 去重：同一知识被多个人记录时，应通过相似度合并或提醒。
• 增量索引：只更新 Git 中变更过的文件，而不是每次全量重建。
• 权限过滤：某些文档可能只对部分角色可见，这需要在索引构建时就打上权限标签。

4.3 检索层：同时支持相似度搜索和关键词搜索

如果你实际做过 RAG 应用就会发现，纯向量检索有一个常见问题：对精确术语、代码标识符、版本号、人名，向量检索的效果不一定好。

一个稳妥的检索策略是混合检索：向量检索负责语义相关性，BM25 或全文检索负责关键词命中，两者结果合并后重排。重排可以使用 LLM 或者简单的分数加权。

# 文件路径：services/retriever.py # 说明：示意代码，演示把向量检索和关键词检索结果合并 # 这不是 Stigmergy 项目源码，而是实现同类功能时的通用参考 def hybrid_search(query: str, top_k: int = 5): # 向量检索：基于语义 vector_results = vector_store.search(query, top_k=top_k * 2) # 关键词检索：例如通过 SQLite FTS5 或 Elasticsearch keyword_results = keyword_store.search(query, top_k=top_k * 2) # 合并：按分数加权，向量分数和关键词分数需要做归一化 merged = {} for doc_id, score in vector_results: merged[doc_id] = merged.get(doc_id, 0) + 0.6 * score for doc_id, score in keyword_results: merged[doc_id] = merged.get(doc_id, 0) + 0.4 * score ranked = sorted(merged.items(), key=lambda x: x[1], reverse=True) return [doc_id for doc_id, _ in ranked[:top_k]]

混合检索在团队知识库中特别重要，因为团队文档里充满专有名词和内部代号，这些恰恰是纯向量检索不擅长处理的。

4.4 生成层：基于检索结果生成团队上下文

生成层是直接面对用户的部分。团队场景和个人场景的一个关键差异是：回答必须包含可追溯的来源。

个人 LLM wiki 可以只回复结论，因为用户自己能判断对错；团队 wiki 则不行，用户（尤其是新人）很可能会把 LLM 的回答当成团队“官方结论”。因此，回答中必须包含引用的文档路径、相关的时间上下文、以及“该信息可能过期”的风险提示。

一个朴素但有效的 prompt 模板大致如下：

你是团队知识库的助手。请基于以下检索到的文档回答问题。 如果文档中没有足够信息，请明确回答"知识库中没有找到相关记录"， 不要使用你自己的通用知识来猜测。 检索到的资料： {context} 请回答： {question} 要求： 1. 回答末尾列出引用的文档路径。 2. 如果文档中存在冲突信息，请在回答中明确指出。

4.5 交互层：让知识在写作过程中自然浮现

这是 Stigmergy 最有辨识度的地方，也是从“Karpathy 式个人 LLM wiki”继承来的核心交互理念。

传统 wiki 的交互模式是“先有需求，再搜索”。Stigmergy 想要实现的是“写作时自然唤起”。也就是说，当团队成员正在文档编辑器中写一段关于“支付服务重构”的笔记时，LLM 可以自动检索知识库，给出提示：“知识库里有三篇与支付服务重构相关的旧文档，其中一篇提到的方案和你现在写的方案不一致。”

要实现这种交互，前端编辑器需要监听文档内容的变更，将最近的文本片段发送给后端检索服务。考虑到成本和延迟，通常只会触发“节流”逻辑：用户停止输入几秒后，才发起一次检索。这个设计，让“记录”和“复用”不再是两个分离的动作，而是融为一体。

5. 环境准备与技术选型建议

虽然 Stigmergy 的具体安装步骤要以项目 README 为准，但如果你准备在团队里部署一套类似的 LLM wiki 系统，以下环境和技术选型是你绕不开的决策点。

5.1 基础环境

• 操作系统：Linux 服务器或 macOS 开发机均可，Windows 也可以通过 WSL 运行。
• 语言运行时：Python 3.10 以上（主流 LLM 工具链的默认选择）。
• 版本管理：Git，必须，因为知识文件要用 Git 做多人在线协作。
• 向量数据库：根据团队规模选择。小团队可以直接用轻量方案，比如sqlite-vss或chromadb；数据量大了再迁移到qdrant、milvus或pgvector。

5.2 LLM 接入：自托管模型还是 API

团队知识库涉及内部信息，关于 LLM 的接入方式必须非常谨慎。这里有两个方向：

一是商业 API。OpenAI、Anthropic、国内大模型厂商都提供 API。优点是效果稳定、接入快；缺点是企业内部知识会发送给第三方服务，这在很多公司的安全规范里是不被允许的。你要先确认公司对数据出境、第三方处理的合规要求。

二是本地模型。通过llama.cpp、Ollama、vLLM部署开源模型（比如 Qwen、Llama、DeepSeek 等）。优点是数据不会出内网，适合私有化部署；缺点是效果和并发能力取决于你的 GPU 资源。

关于“AI 开发免费的 LLM 模式有哪些”——如果你在开发阶段想跑通流程，可以从几个思路入手：使用本地小模型（参数量小、量化版本）做开发验证；使用云厂商的免费额度；仅把 LLM 用于最终答案生成，检索、分类等环节用规则或传统方法完成。等流程验证完再换更强的模型，能显著降低开发期的成本。

5.3 嵌入模型与向量化

嵌入模型选择上，需要注意：嵌入模型决定了检索的上限。如果文档包含大量中文内容，建议优先选择对中文支持较好的中文嵌入模型；如果团队文档以代码为主，混合代码和自然语言的嵌入模型可能效果更好。

向量化的基础建议：

• 文本块大小建议 500 到 1000 字之间，太小则语义不完整，太大则检索噪音多。
• 每个文本块保留元数据字段：来源文件路径、最后修改时间、作者、权限标签。
• 文档更新后，最好在 CI 里自动触发增量索引任务，避免手动维护。

5.4 团队部署形态

很多团队会纠结一个问题：LLM 服务和团队 wiki 是否必须部署在同一台机器上？比如热词里有人问“ComfyUI 与 LLM 必须在同一台电脑上么”，这个问题本质是问本地 AI 工具与模型服务的耦合方式。

答案通常是否定的。在团队场景里，更合理的结构是：知识库文件仓库是一层，检索服务是一层，LLM 模型服务又是一层，三者可以通过 HTTP 或内部 API 解耦。Wiki 文件可以放在 Git 仓库或 NAS 上，检索服务单独部署，LLM 服务可以独立管理。分层部署的好处是，当模型升级或知识库扩容时，不会互相阻塞。对个人本地工具来说，耦合部署更方便；但团队系统一般优先考虑解耦。

6. 最小落地实践：一个团队知识库原型的部署思路

由于 Stigmergy 目前仍处在早期阶段，且具体的部署命令会随版本更新，我不会在这里列出可能过期的安装命令。更稳妥的方式是：带你走一遍“如何用开源组件搭建一个最小可用的团队 LLM wiki 原型”，这套思路在任何具体框架下都适用。

6.1 第一步：初始化 wiki 仓库

# 创建团队 wiki 目录，并初始化 Git 仓库 mkdir team-wiki && cd team-wiki git init # 创建基础目录 mkdir -p docs/architecture docs/runbooks docs/decisions notes snippets # 添加一个初始 README，让团队的 LLM 有一个入口了解知识库定位 cat > README.md << 'EOF' # Team Wiki 本仓库是团队的知识库，所有内容使用 Markdown 编写。 - docs/architecture: 架构设计文档 - docs/runbooks: 运维手册 - docs/decisions: 技术决策记录 - notes: 会议记录、过程笔记 - snippets: 代码片段、配置片段 写入要求：允许粗糙，鼓励记录。知识只有在被写下来之后才有被复用的可能。 EOF git add . git commit -m "init team wiki"

这一步的关键不是命令本身，而是让团队成员意识到：知识库允许“粗糙的笔记”，不要求一次性写出完美文档。过程笔记的价值，往往比正式文档更高。

6.2 第二步：实现一个最小检索服务

最小原型不需要复杂的 API 服务，你可以先用一个脚本跑通“提问 -> 检索 -> 生成”的闭环。

# 文件路径：scripts/ask.py # 说明：最简 RAG 示例，演示团队 wiki 的提问流程 # 需要先安装依赖：pip install chromadb sentence-transformers openai import sys from pathlib import Path import chromadb from chromadb.utils import embedding_functions def main(): wiki_dir = sys.argv[1] if len(sys.argv) > 1 else "team-wiki" question = sys.argv[2] if len(sys.argv) > 2 else "我们的数据库容灾方案是什么？" # 初始化客户端和嵌入函数 client = chromadb.PersistentClient(path="./vector_store") embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction( model_name="BAAI/bge-small-zh-v1.5" ) collection = client.get_or_create_collection( name="team_wiki", embedding_function=embedding_fn ) # 如果 collection 为空，先构建索引（简化逻辑） if collection.count() == 0: for md_file in Path(wiki_dir).rglob("*.md"): text = md_file.read_text(encoding="utf-8") # 按段粗略切分 chunks = [c.strip() for c in text.split("\n\n") if c.strip()] for idx, chunk in enumerate(chunks[:20]): # 演示时限制块数 collection.add( ids=[f"{md_file.stem}-{idx}"], documents=[chunk[:500]], # 截断避免超长 metadatas=[{"source": str(md_file)}], ) # 检索 results = collection.query(query_texts=[question], n_results=5) print("=== 检索到的相关文档 ===") for source in results["metadatas"][0]: print(f"- {source['source']}") # 简化的回答生成：只返回检索结果，真正的 LLM 调用可以在这个基础上扩展 print("\n=== 下一步 ===") print("将上述检索结果作为 context，拼接 LLM prompt，即可生成带来源的回答。") if __name__ == "__main__": main()

# 运行方式 python scripts/ask.py team-wiki "我们的数据库容灾方案是什么？"

这个脚本展示了 RAG 的最小闭环：文档加载、文本切分、向量化、检索。真实的 LLM 生成环节，只需要把results["documents"][0]拼进 prompt 再调用大模型即可。

6.3 第三步：配置 CI 自动更新索引

团队 wiki 的核心是“持续沉淀”。如果你要求成员手动执行索引构建脚本，这个系统八成会死在运维成本上。正确的做法是把索引更新放进 CI。

# 文件路径：.github/workflows/index-wiki.yml # 说明：当 main 分支有文档变更时，自动重建向量索引 name: Build Wiki Index on: push: branches: [main] paths: ["docs/**", "notes/**", "snippets/**"] jobs: build-index: runs-on: ubuntu-latest steps: - name: Checkout wiki repo uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v5 with: python-version: "3.11" - name: Install dependencies run: pip install chromadb sentence-transformers - name: Build index run: python scripts/build_index.py ./team-wiki

这只是一个可行的思路，具体 CI 配置以你的代码托管平台为准。但有一个原则是通用的：知识库的索引构建，必须全自动，不能依赖人工命令。

6.4 第四步：设计回答的可信度

团队知识库的 LLM 回答，必须有“可信度声明”。建议在回答的结尾强制附带：

以上回答基于以下文档： - docs/runbooks/db-failover.md（最后更新：2025-03-20） - docs/decisions/2025-04-use-postgres.md 注意：知识库内容由团队成员维护，可能存在过期或冲突信息。如有疑问，请查看原始文档。

这个设计不是形式主义，而是在团队环境中建立“LLM 只是检索器，不是权威来源”的心理预期。否则很容易出现：成员把 LLM 编造的答案写进正式系统，导致事故。

7. 运行效果与验证方式

搭建完最小原型后，怎么判断它是否真的对团队有帮助？

7.1 验证指标

不要只看“它能不能搜到内容”。更有意义的验证维度是：

• 已知问题覆盖度：把团队过去三个月在 IM 里反复回答的问题整理成清单，看 LLM wiki 能否直接回答其中 70% 以上。
• 首次回答可引用率：每次回答是否附带了正确的文档引用。
• 误判率：回答中是否出现“知识库之外”的模型编造信息。
• 写入氛围：团队成员是否愿意继续在 wiki 里添加新内容。

7.2 运行与验证

如果使用类似前文的原型脚本，运行后预期输出应该包含：

1. 程序成功完成文档加载和切分。
2. 检索结果能返回至少一条与问题相关的文档路径。
3. 如果有真实 LLM 接入，回答能围绕检索结果生成，并附上引用来源。

# 在 wiki 目录中新增一个测试问题 python scripts/ask.py team-wiki "支付服务的超时重试策略是什么？"

如果输出显示“没有找到相关文档”，先不要急着调模型。优先检查：

1. 是否真的有人在 wiki 里写过这个主题。
2. 文本切分是否把长文档切坏了。
3. 嵌入模型是否适合你的文档语言。

7.3 失败的排查方向

一个常见误区：LLM 回答不好，就马上换更大的模型。实际上，在 RAG 系统里，绝大多数“回答不行”的问题都出在检索环节，而不是生成环节。

如果你发现 LLM 经常“一本正经地胡说八道”，大概率原因是检索到的上下文本身就不相关。这时候应该先看检索到的前几名文档是不是真的与问题相关，而不是盲目更换模型。

8. 常见问题与排查思路

问题现象	可能原因	排查方式	解决方案
团队没人愿意写 wiki	写入摩擦太高，模板要求严格	查看文档写作流程是否复杂	增加 notes 目录，允许“一句话笔记”；降低正式文档要求
LLM 回答经常瞎编	检索结果不相关或为空	检查检索环节的 top_k 结果，看召回文档是否相关	优化切分策略、增加混合检索、在 prompt 中明确限制只能基于检索结果回答
新同事还是习惯直接问人	知识库内容覆盖率不够，或搜索体验差	统计常见问题在知识库中是否有对应文档	优先沉淀反复出现的问题，把问答记录导入 wiki
文档更新后，检索结果还是旧内容	索引没有触发增量更新	检查 CI 任务日志，确认索引构建是否执行	配置 push 事件自动触发索引更新，或增加定时重建任务
向量检索效果差，专有名词匹配不到	嵌入模型对代码和术语不敏感	用几个典型问题测试召回结果	切换为混合检索策略，增加 BM25 关键词检索加权
内部知识发送到外部 API，安全合规不通过	LLM 服务使用了云端 API	检查数据流向和公司安全规范	切换至本地部署的开源模型，或使用私有化 API 网关
wiki 文件多后，索引速度慢	全量重建索引	查看索引构建耗时	改为增量索引，只处理 Git 变更文件

9. 适用团队与使用边界

Stigmergy 的目标场景很明确：它适合小到中型团队，尤其是知识密集型的研发团队。这种团队有一个共同特征——大量知识存在于成员的头脑中，而正式文档永远跟不上变化。

哪些团队应该尝试它？

• 10 到 50 人的技术团队，已经有了明显的“重复回答问题”现象。
• 远程或混合办公团队，同事之间无法随时“站起来问一句”。
• 对数据安全有要求、但允许内网部署 LLM 服务的团队。
• 有 Git 基础，成员不排斥写 Markdown 的团队。

哪些团队不应该硬上？

• 人数很少（比如 2 到 3 人）的团队，直接对话的成本可能低于知识库维护成本。
• 已经重度使用 Notion、Confluence 且有成熟流程的团队，迁移成本可能大于收益。
• 团队文档文化尚未建立，连普通 wiki 都没有维护习惯时，贸然上 LLM wiki 只会让问题更快暴露。

这里需要做一个诚实的判断：LLM 不能解决“团队不想记录”的问题，它只能让“记录过的东西”更容易被复用。如果你所在团队连最基本的 wiki 都维护不起来，Stigmergy 不会带来奇迹。

10. 最佳实践与工程建议

10.1 用“文档即代码”的方式管理团队知识

团队 wiki 应该使用 Git 管理，而不是某个 SaaS 知识库平台的私有格式。这带来的直接好处是：

• 每个改动都有提交记录，可以定位“是谁、在什么时候、基于什么理由”改的。
• 可以像 code review 一样 review 文档改动。
• 可以写脚本做自动检查：比如检查是否有文档把密码、密钥直接写进了正文。

10.2 写作范围优先于格式规范

团队 wiki 最大的敌人不是写得不好，而是“要写得很好才能提交”。建议把目录分为两层：

• formal/：正式文档，需要 review，用于对外说明和高价值沉淀。
• inbox/：过程笔记，允许粗糙，鼓励记录，定期由专人或 LLM 来做整理归类。

这本质上是把 Stigmergy 的“低摩擦写入”原则落到了目录结构上。允许环境的“不完美痕迹”存在，知识才会开始流动。

10.3 安全和权限边界

团队 LLM wiki 涉及数据安全问题，必须重视：

• 最小权限原则：不是所有人都能查看所有文档。涉及密钥、客户敏感信息的文档更应严格限制。
• 检索服务必须集成权限过滤：向量检索的召回结果不能包含用户无权查看的文档。
• 如果使用外部 LLM API，确保发送的内容不包含敏感信息；如果合规不允许，就切换到本地模型。
• 任何生产环境变更，都应该先在测试环境验证。

10.4 成本控制

团队 RAG 系统的成本主要在三个地方：

• LLM 推理费用：频繁调用外部 API 会产生成本。建议增加缓存，相同问题直接返回历史结果。
• 向量化费用：文档越多，每次索引构建的嵌入调用也越多。增量索引可以显著降低成本。
• 存储费用：向量数据库和文件仓库的存储成本相对较低，但要注意备份机制。

10.5 回答质量闭环

在团队 wiki 的回答页面加上“这个回答有用吗”的反馈按钮。把反馈数据收集起来，定期生成“无法回答的问题清单”和“低质量回答清单”，这些清单就是知识库下一步要补充的内容方向。这个闭环，才是团队知识库不断进化的驱动力。

11. 总结与延伸方向

Stigmergy 这个项目，给我最大的启发不是“把 LLM 接进 wiki”这个技术动作，而是它把团队知识库的定位，从“信息存储系统”重新定义为“协作痕迹系统”。

Karpathy 的 LLM wiki 为个人知识管理提供了新的交互范式，而 Stigmergy 试图把这个范式带到团队领域。想清楚什么值得记录、如何让记录被复用、怎么保证回答的可信度，比单纯接入更大的模型更重要。

如果你准备动手实践，建议按这个顺序推进：

1. 先建一个简单的 Git wiki 仓库，鼓励团队把散落在聊天记录和文档里的知识点沉淀成 Markdown 文件。
2. 跑通一个最小 RAG 脚本，让 LLM 能基于这些文件回答问题。
3. 在回答中强制附带文档来源，观察团队的实际使用反馈。
4. 逐渐引入增量索引、混合检索、权限过滤和 CI 自动化。
5. 积累足够数据后，再考虑实现 Stigmergy 中更复杂的“写作时主动唤起”交互。

更深一层的方向，是关注 Agent 与知识库的结合。当 LLM 不再只是“回答问题”，而是能主动发现知识库中的缺口、提醒冲突、联系相关成员时，团队知识管理会真正从“被人搜索的工具”变成“参与协作的基础设施”。Stigmergy 是这条路上的一个早期但有代表性的尝试，值得持续关注。