为什么 wiki.json 会缩减你的 DeepWiki
首先来看看这个文件的作用。“如果在 wiki 生成期间在仓库的根目录中找到了 .devin/wiki.json 文件，我们将使用提供的 repo_notes and pages 来引导 wiki 生成。这两个字段都是必需的，且 pages 必须至少列出一个页面。”
这两个字段承担不同的工作。Cognition 用一句话总结道：“Notes 引导每个页面如何编写；pages 决定创建哪些页面。”Notes 是上下文。Pages 是大纲。
而这个大纲是字面意义上的。配置参考中提到，pages “被视为明确的指令：只有你在 JSON 中定义的页面才会被生成，不多不少。”排错部分又两次强调了这一点，这充分说明了人们有多容易掉进这个坑里。“Wiki 仅生成你列出的页面，因此任何没有对应页面的文件夹都不会出现。”以及：“请记住：DeepWiki 将仅生成此数组中包含的页面，因此请确保所有页面都存在，而不仅仅是缺失的页面。”
所以，最自然的操作——“wiki 漏掉了我们的 testing/ 文件夹，我们加个配置提到它吧”——会用一个完全只包含你写下的页面的 wiki，去替换掉自动规划的 wiki。
此外还有一些硬性限制需要规划：“最多 30 页（企业版为 80 页）”，“仓库和页面 notes 总计最多 100 个”，以及“每个 note 最多 10,000 个字符”。页面标题“必须唯一且非空”。没有 pages 的文件也不会悄悄回退到自动规划：一个“省略了 pages（或将其留空）”的 wiki.json “会被拒绝”。
还有两个细节决定了 wiki 反映的内容。分支：“Devin 会索引每个仓库的默认分支”，Cognition 的建议是“索引你团队正在积极开发的分支”。Effort（投入度）：wiki 生成运行在三个 effort 级别之一，并且“企业组织始终以低 effort 运行；该设置对他们不可配置”。
然后是受众。DeepWiki 不仅仅是供人浏览的。“Ask Devin 将使用 Wiki 中的信息来更好地理解并在你的代码库中寻找相关的上下文。”通过 DeepWiki MCP 服务端，外部 Agent 可以使用名为 read_wiki_structure、read_wiki_contents 和 ask_question 的工具来读取它。一个没有生成的页面，就是所有这些工具都无法读取的页面。
人们尝试的其他替代方案
添加一个仅包含缺失页面的 wiki.json。 这就是上面提到的陷阱。你得到了想要的页面，却丢失了所有未列出的页面。
使用 repo_notes 来请求覆盖。 Notes 决定页面的编写方式，而不是存在哪些页面。一条写着“记录 scripts 文件夹”的 note 毫无用处，除非 pages 中有该页面的配置。
让自动生成的 wiki 保持原样，并寄希望于 Agent 去搜索其余的代码。 Agent 确实可以搜索代码，但文件夹的生成文档与通过名称查找文件是两码事。Agent 实际加载的内容比大多数团队设想的要窄得多，这一模式在编程 Agent 实际读取的内容中有所提及。
将 MCP 服务端指向 DeepWiki 并假设私有仓库已被覆盖。 公共 MCP 服务端被描述为“一个免费、远程、无需身份验证的服务，提供对公共仓库的访问”。对于私有代码，Cognition 指向带有 Devin API 密钥的 Devin MCP 服务端。
将一个客户端的 MCP 配置复制到另一个客户端。 Cognition 明确指出了这一点：“Devin Desktop 使用 serverUrl，而大多数其他客户端使用标准的 url 字段。使用错误的字段名称会导致 MCP 服务端被静默忽略。”
解决方案：记录现有的 wiki，然后用完整的页面列表进行引导
目标是让 wiki 覆盖你关心的文件夹，保留自动规划已经生成的有用内容，并触及每一个依赖它的 Agent。
步骤 1：在添加配置之前记录当前的 wiki 结构
在动任何东西之前，写下当前自动生成的 wiki 包含哪些内容。在 Devin 或 deepwiki.com 上打开 wiki 并复制页面树：每个顶级页面和每个子页面。
如果你使用 MCP 客户端，可以要求它为仓库调用 read_wiki_structure，Cognition 将其描述为“获取 GitHub 仓库的文档主题列表”的方法。将结果保存到一个文件中，以便稍后进行对比。
然后用三个标签之一标记每个页面：保留（keep）、合并（merge）或丢弃（drop）。保留人和 Agent 使用的页面。合并覆盖相邻代码的单薄页面。丢弃记录了没人需要解释的生成代码或第三方（vendored）代码的页面。
最后，列出缺失的内容：自动规划跳过的文件夹、它从未创建的交叉主题（服务之间如何通信、部署如何工作），以及生成的摘要过于浅显而无用的区域。
步骤 2：编写包含你想要的每个页面的 wiki.json，并将优先级放入 repo_notes
现在根据你的列表（而不仅仅是缺失的部分）来构建文件。
将每个“保留”页面和每个缺失的页面放入 pages 中，每个页面都有唯一的 title 和特定的 purpose。Cognition 的指导是“提及要关注的特定目录、文件或概念”并“提供足够的细节以便系统理解你的意图”。使用 parent 重建层级结构，从“高级概述页面”开始。
在提交之前计算数量。如果你的列表超出了页面限制，请合并相关页面直到符合要求，保留 Agent 和新团队成员最常打开的页面。
使用 repo_notes 来强调重点和关系。Cognition 建议使用 notes 来指出“代码库的哪些部分最重要”并“解释系统不同部分之间的关系”。即使你没有什么要添加的，也要保留 repo_notes 键；参考文档指出要“使用空数组（[]）”。对于仅适用于单个页面的指导，请使用 page_notes。
然后按照文档记录的顺序操作：“提交文件并重新生成你的 wiki。”
步骤 3：重新生成、对比并检查 Agent 是否接收到
将重新生成的 wiki 与你在步骤 1 中保存的树进行对比。每个“保留”页面应该仍然存在，合并的页面应该读起来连贯，缺失的文件夹现在应该有了对应的页面。如果有什么东西消失了，说明它被遗漏在 pages 之外了。
检查分支。如果 wiki 描述的是默认分支，但你的团队在另一个分支上工作，请按照 Cognition 的建议，将该分支添加到索引中。
然后检查 Agent。在团队使用的每个 MCP 客户端中，确认服务端条目使用了该客户端期望的字段——Devin Desktop 使用 serverUrl，大多数其他客户端使用 url——并且它指向推荐的端点；Cognition 指出“推荐使用 /mcp 端点，因为 SSE 正在被弃用”。向每个客户端提出一个答案位于新页面上的问题。如果客户端从 wiki 中给出了回答，说明引导已经传达到了你的 Agent。
当代码库结构发生变化时，重新审视该文件。新服务或废弃的模块意味着页面列表需要编辑，因为 wiki 将生成文件所写的内容，不多也不少。
在 MemoryLake 中进行设置
引导后的 DeepWiki 解释了代码是什么以及它们是如何组合在一起的。它是从仓库生成的，因此它描述的是结构而不是历史：为什么拆分某个模块、尝试并放弃了哪种方法、团队对 API 达成了什么共识。这些上下文存在于人们的脑海和零散的讨论中。MemoryLake 是一个可以将这些内容与 wiki 放在一起保存的地方，这样 Agent 既能获得地图，也能了解背后的原因。
你可以用自己的语言亲自编写这些条目。不会从你的 DeepWiki、你的 wiki.json、你的仓库或任何服务商的存储中读取、写入或删除任何内容。
步骤 1：创建 API 密钥
登录并在控制面板中生成一个密钥。该密钥可以让你的编程 Agent 在它们运行的任何客户端中读取你编写的条目。
步骤 2：上传你的第一批记忆
从步骤 1 中显现但任何生成的页面都无法容纳的内容开始：结构背后的决策、已知的坑，以及代码中不明显的约定。每个条目记录一个决策，并附带原因。
步骤 3：连接你的 AI 和 Agent
连接你团队使用的编程 Agent。这样，在每个会话中，决策就会与 wiki 并排存在，包括通过 MCP 读取 DeepWiki 的 Agent。
这在实践中改变了什么
第一个区别是引导不再具有风险。一旦你记录了现有的树并据此构建了页面列表，添加 wiki.json 就会扩大覆盖范围，而不是替换它。
第二个区别是 repo notes 能够各司其职。当覆盖范围由 pages 负责时，notes 就可以自由地去做 Cognition设计它们时的本职工作：解释优先级和关系，从而改善每个页面，而不是去请求新页面。
第三个区别是 Agent 不再根据残缺的地图工作。同一个 wiki 会提供给 Ask Devin 和每个 MCP 客户端，因此完整的页面列表可以同时改善所有地方的回答。当 Agent 否则需要在每个会话中重新读取代码库来重建认知时，这一点尤为重要。
第四个区别是生成的文档和团队知识不再混淆。从代码重新生成的 wiki 回答了“这是什么”。而决策回答了“为什么是这样”。对生成的页面进行检索固然有用，但正如为什么 RAG 不是记忆所解释的，这与记住团队的决定是两码事。
引导 DeepWiki 的最佳实践
在添加配置之前保存当前的页面树。 这是了解 wiki.json 删除了什么的唯一方法。
列出你想要的每一个页面，而不仅仅是缺失的页面。 Wiki 会精确生成 pages 数组中定义的内容。
使用 repo_notes 强调重点，使用 pages 确保覆盖。 Notes 引导页面的编写方式；pages 决定存在哪些页面。
保持在限制范围内。 合并页面，而不是超出页面数量限制。
索引你团队开发的分支。 除非你添加其他分支，否则 Devin 只会索引默认分支。
使 MCP 字段与客户端匹配。 错误的字段名称会导致服务端被静默忽略。
将原因留在 wiki 之外，保存在持久的地方。 Devin 自身的 Knowledge 条目有其自己的检索规则，而 Devin 遗忘任务上下文是与文档覆盖率不同的另一个问题。对于操作流程，将记忆移动到技能中是另一种途径。
结论
.devin/wiki.json 是当 DeepWiki 的自动规划遗漏了大型仓库的重要部分时的正确工具。它也是完全字面化的。正如 Cognition 所说，“只有你在 JSON 中定义的页面才会被生成，不多不少。”
在引导之前，先记录你现有的 wiki。根据该记录加上缺失的部分构建页面列表，使用 repo notes 强调重点，保持在限制范围内，然后重新生成。接着检查分支是否正确，以及每个 MCP 客户端是否配置了它期望的字段，以便读取 wiki 的 Agent 能够获得你预期的版本。
将代码背后的原因保留在它们自己的层中，因为生成的 wiki 描述的是结构，而背后的决策来自你的团队。关于 MCP 连接在会话之间传输和不传输什么的更广泛问题，请参阅 MCP 中缺失的记忆层。