DeepWiki：从代码到可对话的架构文档

已知（配置可证明）

• 为“每个仓库”提供最新文档（up-to-date documentation）。
• 文档是可对话的（you can talk to）。
• 并以MCP Server 形式对外提供（SSE 入口）。

常见能力（需要你在官网/笔记里验证）

• 架构视图：模块划分、依赖关系、关键入口/运行路径。
• 定位能力：“这个 feature 在哪/从哪进/谁调用谁”。
• 产出页面：项目概览、模块说明、关键流程、配置与部署说明。
• 证据链：回答时引用文件路径/函数名/行号/commit（否则很难信任）。

Web 试用（建议先做）

1. 打开：deepwiki.com
2. 输入一个你熟悉的公开仓库（便于校验准确性）。
3. 先问三问：入口在哪里？模块怎么分？跑起来需要什么？
4. 再问两类：“路径型”问题（从 A 到 B 怎么走）与 “边界型”问题（谁负责什么）。

关键：把它当“地图生成器”，不要把第一句话当结论；要求它引用具体文件/符号。

MCP 接入（面向工作流/Agent）

1. 在你使用的 MCP 客户端里新增一个 Server（类型：SSE）。
2. URL：https://mcp.deepwiki.com/sse
3. 按当前配置线索：无需 API Key（但以官网为准）。
4. 连接后先做一次“列工具/列能力”（不同客户端会显示 tools 列表）。

工程要点（决定体验）

• 引用：回答必须能回链到文件/符号（否则无法信任）。
• 分层：文件级、模块级、系统级摘要要分开生成并缓存。
• 增量：只对 diff 影响的模块重建，才能“up-to-date”。
• 多语言：用 tree-sitter/LSP 统一抽象，逐步扩展语言覆盖。

风险要点（决定能否落地）

• 幻觉：LLM 会“编造代码逻辑”；强制引用/校验可缓解。
• 隐私：私有仓库是否上传第三方？需要明确 policy/自建方案。
• 注入：代码注释/README 可做 prompt injection；要做隔离与安全提示。
• 成本：索引与摘要是持续成本，必须有缓存与淘汰策略。

Simon Brown · C4 Model（paraphrase）

• Thesis：“可维护的架构文档”比“漂亮的架构文档”更重要；文档必须围绕不同受众分层。
• Arguments：用结构图（System/Container/Component）把复杂度切开；让图/页面与代码索引绑定，减少过期。
• Limits：如果缺少“证据链”，对话式总结会变成“故事”，无法用于工程决策。

Beyang Liu · Sourcegraph（paraphrase）

• Thesis：真正的“理解代码库”来自符号级索引与跨文件引用，而不是全文搜索。
• Arguments：统一抽象（symbols, definitions, references）+ 增量索引，才能规模化覆盖多语言与大仓库。
• Limits：调用图/运行路径很难 100% 静态得出，需要“近似 + 指向入口代码”并提示不确定性。

Simon Willison · LLM Systems（paraphrase）

• Thesis：把 LLM 当“自然语言 UI”，而不是“真理引擎”；必须让它展示检索依据。
• Arguments：RAG 的关键是数据管道与评估：能否稳定召回正确片段、回答是否可复现。
• Limits：没有基准问题集与回归测试，任何“看起来很好”的回答都可能在关键处翻车。

MVP（1–2 周，能用就行）

1. 输入：Git URL + branch/commit。
2. 输出：静态站点（HTML/Markdown）+ 3 页：Overview / Architecture / Getting Started。
3. 索引：tree-sitter/ctags 抽 symbols + imports，生成“模块依赖表”。
4. 对话：提供一个 API：问题 → 检索（代码片段+页面）→ 回答（必须引用）。
5. 评估：为 1 个熟悉仓库写 20 道问题做回归（每次改动跑一遍）。

V1（4–8 周，开始像产品）

1. 增量更新：按 commit diff 只重建受影响模块。
2. 缓存：摘要/向量/页面全缓存，支持淘汰策略（LRU/按热度）。
3. 权限：私有仓库（GitHub App/OAuth）与本地自托管模式。
4. 可追溯：每页标注 commit hash + 生成时间 + 数据来源清单。
5. UI：页面树 + 搜索 + “复制引用”按钮（把路径/符号一键贴到 PR/Issue）。

代码解析 / 索引

• tree-sitter/tree-sitter：多语言 AST（适合做符号/结构抽取）。
• universal-ctags/ctags：符号标签（快速生成“函数/类列表”）。
• oracle/opengrok：代码搜索 + 交叉引用（xref）系统。
• sourcegraph/sourcegraph：大规模代码搜索/索引（思路参考价值很高）。

文档站点 / 图 / RAG

• mkdocs/mkdocs：用 Markdown 生成文档站。
• facebook/docusaurus：现代化文档站框架。
• mermaid-js/mermaid：用文本生成架构/流程图。
• langchain-ai/langchain：RAG/Agent 工具链。
• run-llama/llama_index：RAG/索引与数据连接器。