项目简介与目标定位

OpenDeepWiki 是一款面向开发团队的开源代码知识库生成平台，核心目标是将任意 Git 仓库（包括 GitHub、GitLab、Gitee、Forgejo 等自托管实例以及 ZIP 上传包）转化为可检索、可交互的结构化 Wiki 文档，并通过 AI 提供基于代码上下文的对话问答能力。仓库内 README.md 与中文版 README.zh-CN.md 同时存在，明确将项目定位为"AI 驱动的代码文档生成与对话平台"。

平台面向三类典型用户：(1) 希望自动化产出项目说明文档的开源维护者；(2) 需要在内部大量代码仓库上落地知识库的研发团队；(3) 通过自托管（self-hosted）部署，将 Forgejo、MCP、OAuth 等能力回馈上游的二次开发者。这一反馈路径可见于社区讨论（issue #371），其中自托管 fork 已领先 main 分支约 60 个提交。最新发布版本为 v2.0.3，包含 MCP Server、Slack 通知、可折叠侧边栏等新增模块。

技术栈与代码组织

OpenDeepWiki 采用 .NET 9 后端 + Next.js 15 前端的典型分层结构，仓库根目录的 OpenDeepWiki.sln 解决方案整合了后端服务、AI 处理、数据库实体等多个子项目。

后端主要项目包括：

• src/OpenDeepWiki/：主 Web API 入口，使用 Program.cs 作为启动引导，通过 GlobalUsing.cs 集中声明全局命名空间以减少冗余 using；appsettings.json 中可配置 CHAT_MODEL、ANALYSIS_MODEL、ENDPOINT、DB_TYPE、DB_CONNECTION_STRING、LANGUAGE 等关键运行参数。
• src/OpenDeepWiki.Entities/：实体层项目，OpenDeepWiki.Entities.csproj 定义了与数据库映射的数据模型。
• src/KoalaWiki/：AI 文档生成与对话处理的核心引擎（早期名称为 KoalaWiki），KoalaWiki.csproj 集成大模型调用、文件分析、Mermaid 修复等能力。
• src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs：Wiki 文档生成的主要编排器，内部 ExecuteAgentWithRetryAsync 方法承担智能体循环调用与重试职责。

前端位于 web/，采用 Next.js App Router（web/app/layout.tsx 为根布局，web/package.json 声明依赖）。社区曾反馈 start-frontend.bat 启动后页面异常（issue #157），主要与 Next.js 15 standalone 模式构建产物相关。

核心功能模块

平台能力在源码层面拆分为若干高内聚模块：

仓库接入与管理：通过 Controllers/RepositoryController.cs 暴露 Repository/RepositoryList、ImportRepository 等接口，支持 Git URL 拉取与 ZIP 上传两种方式。社区反馈指出 ZIP 上传后默认不解析分支信息，导致页面提示仓库不存在，需手动补齐 Warehouses.Branch 字段（issue #301）。

Wiki 文档生成：Services/Wiki/WikiGenerator.cs 负责整体编排，先扫描仓库文件结构，再由 AI 分析生成多级目录树与正文文档，最后持久化到数据库。生成的目录若包含子标题，部分父目录点击后会显示文档不存在（issue #354）；导出压缩包按钮亦曾出现打不开的故障（issue #355）。

智能对话与模型适配：聊天与分析流程解耦，可分别为 CHAT_MODEL 和 ANALYSIS_MODEL 指定不同模型。当使用本地 LLM（如 Ollama）时，曾出现 bad_response_status_code: Can only get item pairs from a mapping 的 500 错误（issue #307）；切换为 DeepSeek-V1 时则会出现大批空文档（issue #275）。

消息通知与扩展集成：v2.0.3 引入 Slack 通知 Provider（PR #324），并通过 MCP Server + OAuth 2.1 提供对外智能体协议能力（PR #325）。

管理后台：仓库删除、目录状态切换等管理操作通过独立后台页面提供，社区反馈删除生成的仓库 Wiki 时存在失败现象（issue #362）。

系统架构与数据流

整体架构可概括为「接入层 → 调度层 → AI 处理层 → 持久化层 → 表现层」五段式：

flowchart LR
    A[Git/ZIP 接入] --> B[仓库目录与分支解析]
    B --> C[WikiGenerator 调度]
    C --> D[AI 分析模型]
    C --> E[AI 聊天模型]
    D --> F[Mermaid 修复与文档合成]
    F --> G[(DB: SQLite/PG)]
    E --> G
    G --> H[Next.js 前端 Wiki]
    H --> I[对话与导出]
    I --> J[Slack/MCP 通知]

调度层核心循环：WikiGenerator.ExecuteAgentWithRetryAsync（位于 WikiGenerator.cs:1127-1265）以 MaxRetryAttempts × TimeoutSeconds 控制重试预算。社区指出该方法缺少最大工具调用次数守卫，在模型陷入工具循环时会产生成倍计费的 LLM 请求（issue #374）。

持久化策略：默认支持 SQLite 与 PostgreSQL，通过 DB_TYPE + DB_CONNECTION_STRING 切换。SQLite 模式下偶发出现"生成的文档未保存到数据库"的现象（issue #279），根因通常为事务边界或空内容短路逻辑（如 PR #290 在 DocumentPendingService 中加入"文件内容为空则不再继续"的防御）。

国际化与多分支：LANGUAGE 环境变量控制输出语言，目前以英文与中文为主，社区已提出增加越南语等语言支持（issue #370）。同一仓库多次导入不同分支时存在状态错乱（issue #353），需在 Warehouses 表上以 (Name, OrganizationName, Branch) 做联合约束以彻底规避。

概述

OpenDeepWiki 的 Wiki 生成流水线是一套将 Git 仓库源码转化为结构化文档的端到端流程，核心由 WikiGenerator 服务承担。IWikiGenerator 接口对外暴露生成、目录管理、增量化更新等能力，WikiGenerator 是其默认实现，组合了目录存储、提示词缓存键构建器以及底层 LLM 客户端，形成"扫描 → 分析 → 目录规划 → 文档生成 → 持久化"的完整链路。资料来源：src/OpenDeepWiki/Services/Wiki/IWikiGenerator.cs:1-40、src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:1-50。

仓库侧的处理入口是 RepositoryProcessingWorker，它通过 Channel 化的消息队列接收任务（自 v2.0.1 引入），并把生成请求委派给 WikiGenerator。这种"后台 Worker + 通道队列"的解耦设计让 HTTP API 与 AI 生成节奏分离，避免大模型调用阻塞请求线程。资料来源：src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs:1-80。

流水线阶段

流水线大致分为四个阶段，每一阶段都对应 WikiGenerator 中的具体方法：

1. 仓库预处理与扫描：识别分支、压缩包结构（社区反馈 #301 指出压缩包上传时未解析 Branch，导致文档虽生成但页面找不到仓库）。资料来源：src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs:80-160。
2. 目录（Catalog）规划与持久化：CatalogStorage 负责将多层级目录写入存储，子目录与父目录的关联在此阶段建立（社区 #354 反馈父目录点击后无文档，疑似与目录节点的关联写入有关）。资料来源：src/OpenDeepWiki/Services/Wiki/CatalogStorage.cs:1-120。
3. AI 文档生成：WikiGenerator 调用 LLM，针对目录节点逐个生成文档，并使用 WikiPromptCacheKeyBuilder 构建可复用的提示词缓存键以减少重复消耗。资料来源：src/OpenDeepWiki/Services/Wiki/WikiPromptCacheKeyBuilder.cs:1-60、src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:200-400。
4. 结果回写：生成的 Markdown 文档经清洗（含 REPAIR_MERMAID 修复）后写入数据库，并刷新目录状态。资料来源：src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:400-700。

flowchart LR
  A[仓库上传/导入] --> B[RepositoryProcessingWorker]
  B --> C[WikiGenerator 预处理]
  C --> D[CatalogStorage 目录规划]
  D --> E[LLM 文档生成 + 提示词缓存]
  E --> F[Mermaid/格式修复]
  F --> G[持久化到数据库]
  G --> H[前端 Wiki 展示]

AI 集成与重试机制

WikiGenerator 通过 WikiGeneratorOptions 注入关键参数：MaxRetryAttempts、TimeoutSeconds、CHAT_MODEL、ANALYSIS_MODEL 等，由此支持在同一实例上分别为"聊天"与"分析"配置不同模型（例如 CHAT_MODEL=glm-4.6 与 ANALYSIS_MODEL=glm-4.6，与社区 #279 中的部署示例一致）。资料来源：src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs:1-80。

核心调用封装在 WikiGenerator.ExecuteAgentWithRetryAsync（位于 src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs#L1127-L1265）。该方法对单次 AI 调用按 TimeoutSeconds 超时，并按 MaxRetryAttempts 重试。社区 #374 指出其"缺乏最大工具调用次数守卫"——若模型陷入循环，单次 Wiki 生成可能消耗 MaxRetryAttempts × (TimeoutSeconds / per-call) 次付费 LLM 调用，是当前的成本与稳定性风险点。资料来源：src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:1127-1265。

社区 #275 报告"生成的文档很多都为空"，通常与所选模型（如 deepseek-v1）对话稳定性或响应截断相关，需要结合 WikiGeneratorOptions 的超时与重试参数协同调优。社区 #307 反馈本地 LLM（如通过 8088 端口代理）返回 bad_response_status_code: 500 / Can only get item pairs from a mapping，属于上游响应格式与 OpenAI 兼容协议的解析失败，发生在 ExecuteAgentWithRetryAsync 的响应反序列化阶段。资料来源：src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:1100-1130。

已知问题与扩展点

• 多分支与目录显示：#353 反映同一仓库导入不同分支冲突，#354 反映父目录点击无文档，两者均与 CatalogStorage 的节点写入/查询策略相关。资料来源：src/OpenDeepWiki/Services/Wiki/CatalogStorage.cs:120-220。
• 导出压缩包：#355 报告 v2.0.1 导出按钮生成的压缩包无法打开，建议升级到 v2.0.3（该版本合并了多项修复）后再验证。资料来源：src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:700-900。
• 国际化（i18n）：#370 提议增加越南语支持；#371 提议将自托管分支中的通用特性（Forgejo、MCP auth、i18n、OAuth）回馈上游。提示词与目录节点结构中均需为多语言预留位置。资料来源：src/OpenDeepWiki/Services/Wiki/IWikiGenerator.cs:40-80。
• 管理员后台：#362 反映"管理后台删除仓库 wiki 失败"，涉及生成记录的级联删除逻辑，需要排查 WikiGenerator 与持久化层之间的状态机。资料来源：src/OpenDeepWiki/Services/Wiki/WikiGenerator.cs:900-1127。

配置与最佳实践

最小可用配置（参考 #279 用户实测）应至少包含：CHAT_MODEL、ANALYSIS_MODEL、CHAT_API_KEY、ENDPOINT、LANGUAGE、DB_TYPE/DB_CONNECTION_STRING、REPAIR_MERMAID=1。当切换到非标准 OpenAI 兼容端点时，建议先通过 v2.0.0 引入的"AI API 连接测试端点"验证连通性，再触发 Wiki 生成，以减少在 ExecuteAgentWithRetryAsync 中的失败重试。资料来源：src/OpenDeepWiki/Services/Wiki/WikiGeneratorOptions.cs:80-140。

对运维而言，应在 Worker 侧为 RepositoryProcessingWorker 设置合理的并发上限与 Channel 容量，避免突发导入把 LLM 配额与数据库写入同时打满。资料来源：src/OpenDeepWiki/Services/Repositories/RepositoryProcessingWorker.cs:160-260。

模块定位与作用

OpenDeepWiki 的"仓库导入、分支与多语言管理"子系统负责将外部代码仓库接入系统，并在仓库之上管理分支、增量更新与多语言文档生成。该子系统由两套端点组成：面向普通用户的 RepositoryUploadEndpoints（压缩包上传）和 GitHubImportEndpoints（GitHub 仓库直接导入），以及面向管理员的 AdminRepositoryEndpoints 与 AdminGitHubImportEndpoints（管理后台导入与删除）。BranchGenerationEndpoints 提供分支维度的文档生成入口，IncrementalUpdateEndpoints 提供基于提交差异的增量更新能力。

资料来源：src/OpenDeepWiki/Endpoints/RepositoryUploadEndpoints.cs:1-1、src/OpenDeepWiki/Endpoints/GitHubImportEndpoints.cs:1-1、src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs:1-1、src/OpenDeepWiki/Endpoints/Admin/AdminGitHubImportEndpoints.cs:1-1、src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs:1-1、src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs:1-1

仓库导入流程

仓库导入支持两种主要方式：

用户上传压缩包时，系统将其解压到本地仓库目录（KOALAWIKI_REPOSITORIES）并入库。社区反馈显示，压缩包形式不会解析 git 分支信息，需要管理员手动在数据库中补充 Branch 字段，否则前端会提示"仓库不存在"。资料来源：src/OpenDeepWiki/Endpoints/RepositoryUploadEndpoints.cs:1-1、社区 Issue #301

flowchart LR
  A[用户/管理员] --> B{选择导入方式}
  B -->|压缩包| C[RepositoryUploadEndpoints]
  B -->|GitHub| D[GitHubImportEndpoints]
  B -->|后台批量| E[AdminGitHubImportEndpoints]
  C --> F[(Warehouse 表)]
  D --> F
  E --> F
  F --> G[分支/多语言生成]

分支管理与多分支冲突

每个仓库在 Warehouse 表中以 (OrganizationName, Name) 唯一标识，分支作为其下属维度。BranchGenerationEndpoints 允许针对同一仓库的不同分支分别触发文档生成任务，从而实现多分支并行 wiki 化。

社区存在一个典型缺陷：当用户已导入 master 分支后，再尝试导入同一仓库的 revert-20-master 等其他分支会被识别为"已存在仓库"而被拒绝，导致无法为同一仓库维护多套文档。资料来源：src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs:1-1、社区 Issue #353

AdminRepositoryEndpoints 提供删除入口，但删除失败时仅返回通用错误，需要管理员结合 Warehouse.Status（取值范围 0-4 表示待处理/处理中/已完成/失败/已删除）和数据库手动排查。资料来源：src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs:1-1、社区 Issue #362

增量更新与生成任务

IncrementalUpdateEndpoints 接收 WebHook 或定时调度（UPDATE_INTERVAL）推送的提交事件，比对本地最新 commit 与远端 HEAD，仅对差异文件重新走"分析→生成"流水线。增量任务与全量 BranchGeneration 共享同一个任务队列（Channel 化的消息处理，自 v2.0.1 引入），因此同时受到 TASK_MAX_SIZE_PER_USER 并发限制。资料来源：src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs:1-1、社区 Issue #279

增量更新会复用已有文档目录树与多语言翻译缓存，因此分支切换时仅重生成 LANGUAGE 指定的语言文件；如需多语言，需要在 .env 中调整 LANGUAGE 变量或在请求中显式传入目标语言列表。

多语言支持现状

LANGUAGE 环境变量（如 LANGUAGE=中文）控制生成阶段调用的提示词与最终文档语种。社区已请求增加越南语等更多语言（Issue #370），同时有自托管分支提议将 i18n、OAuth 等通用特性回馈上游（Issue #371）。

目前多语言覆盖范围由各 Endpoints 中的提示词模板与前端 i18n 字典共同决定；当模型不支持目标语言、或 LLM 返回空内容时，会出现"生成文档为空"的现象（Issue #275）。运营侧建议：为不同分支配置独立 CHAT_MODEL / ANALYSIS_MODEL，并避免在压缩包导入路径上依赖自动分支探测。资料来源：src/OpenDeepWiki/Endpoints/BranchGenerationEndpoints.cs:1-1、src/OpenDeepWiki/Endpoints/IncrementalUpdateEndpoints.cs:1-1

已知问题与运维建议

• 分支无法重复导入：导入 master 后再导入其他分支会失败，需管理员介入调整唯一性约束。资料来源：Issue #353
• 压缩包缺分支信息：需手动写 Branch 字段，否则页面报"仓库不存在"。资料来源：Issue #301
• 删除失败：管理后台删除仓库返回失败，但任务可能仍在运行。资料来源：Issue #362
• 多语言空白文档：在 DeepSeek v1 等模型上易触发，需切换至榜单推荐模型（Claude Sonnet 4/3.7 等）。资料来源：Issue #275、Issue #141
• 导出压缩包异常：在 v2.0.1 之前浏览器侧下载按钮可点击但产物不可解压，已在 v2.0.3 修复。资料来源：Issue #355、Release v2.0.3

运维实践：定期清理 Status=Failed 的 Warehouse 记录；为 GitHub 导入配置专用令牌；在 KOALAWIKI_REPOSITORIES 之外保留冷备的 zip 源文件以应对增量任务回溯。资料来源：src/OpenDeepWiki/Endpoints/Admin/AdminRepositoryEndpoints.cs:1-1、src/OpenDeepWiki/Endpoints/Admin/AdminGitHubImportEndpoints.cs:1-1

1. 部署形态与启动方式

OpenDeepWiki 提供两种 Compose 部署模板，分别面向 SQLite 轻量部署与 PostgreSQL 生产部署，并通过 Makefile 统一管理构建与编排命令。

• compose.yaml：默认编排文件，使用内嵌 SQLite 数据库，适合本地体验与小规模自托管。资料来源：compose.yaml:1-40
• compose.pgsql.yaml：面向生产环境的 PostgreSQL 部署模板，需配合 DB_TYPE=postgres 使用。资料来源：compose.pgsql.yaml:1-40
• Makefile：将 docker compose 命令包装为 build、up、down 等可复用目标。资料来源：Makefile:1-60

Windows 用户可使用 build.ps1 触发等价流程；Linux/macOS 推荐使用 start.sh 一键启动并自动完成依赖拉起。资料来源：build.ps1:1-40、资料来源：start.sh:1-40

注意：start-frontend.bat 在 Windows 上启动前端后曾出现端口冲突导致页面不可用（#157），建议在执行前确认 3000 端口未被占用，并检查 .next/standalone 产物是否由同一次 build 生成。

2. 关键环境变量与配置

完整变量清单见 .env.example，以下为运维侧最常被调整的几项：

资料来源：.env.example:1-80

3. 常见故障排查

3.1 LLM 调用链路异常

• 现象：日志出现 bad_response_status_code: Can only get item pairs from a mapping（#307）。
• 定位：通常是上游网关返回了非 JSON 字典结构（如错误页 HTML），导致 SDK 反序列化失败。
• 处置：核对 ENDPOINT 是否指向 .../v1 之类的 OpenAI 兼容路径，并在 /api/AI/Test 接口中先验证连通性。

3.2 文档生成失败

• 空文档（#275）：多为模型在 ANALYSIS_MODEL 路径下输出被截断，建议提高 MaxRetryAttempts 与超时，或切换更强模型。
• 文档未入库（#279）：检查 SQLite 写权限与 KOALAWIKI_REPOSITORIES 挂载；DocumentPendingService 已对空文件做了前置拦截（v2.0.0，#290）。

3.3 仓库导入与分支冲突

• 同一仓库不同分支会触发唯一性冲突（#353）：目前需在管理后台为不同分支创建独立记录，或在数据库调整 Warehouses 表的命名规则。
• 压缩包导入缺少分支信息（#301）：上传 zip 不会自动推断 Branch，需手动补齐，否则前端会提示"仓库不存在"。

3.4 WikiGenerator 资源耗尽

WikiGenerator.ExecuteAgentWithRetryAsync 在模型卡死时会持续重试，消耗 MaxRetryAttempts × (TimeoutSeconds / per-call) 次计费调用（#374）。建议在网关侧为 /v1/chat/completions 启用工具调用次数与 token 双重限流。

3.5 前端导出与目录交互

• 导出压缩包打不开（#355）：检查后端流式响应头 Content-Disposition 与 Content-Type，确认 zip 头 PK\x03\x04 完整。
• 目录滚动卡死（#356）：v2.0.3 前版本存在 overlay 捕获滚动事件的问题，建议升级到最新发布版本。

4. 运维建议

• 将 compose.pgsql.yaml 与数据卷分离托管，使用只读反向代理对外暴露 /api/Repository/RepositoryList 等接口。
• 启用 v2.0.1 引入的 Channel 化消息处理后，注意为 Channel 消费者配置 MaxRetryAttempts（v2.0.1 #315），避免单条任务拖垮队列。
• 对接自托管 Git 平台时，可参考社区提案 #371（Forgejo、MCP auth、OAuth、i18n）准备前置能力。
• 升级到 v2.0.3 后，可使用新增的 MCP Server（OAuth 2.1）与 Slack 消息通道作为运维通知出口。

资料来源：Makefile:1-60、资料来源：compose.pgsql.yaml:1-40、资料来源：.env.example:1-80

flowchart LR
  A[Git/Zip 导入] --> B[任务队列<br/>Channel]
  B --> C[WikiGenerator]
  C --> D[LLM 端点<br/>CHAT/ANALYSIS]
  C --> E[(DB<br/>SQLite/Postgres)]
  C --> F[/repositories 目录]
  D -- bad response --> G[网关/SDK 异常]
  C -- 工具调用失控 --> H[限流与重试]
  E --> I[管理后台]
  F --> I
  I --> J[Wiki 前端<br/>导出/浏览]

Pitfall Log / 踩坑日志

项目：AIDotNet/OpenDeepWiki

摘要：发现 21 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：配置坑 - 来源证据：Please add support for the Vietnamese language.。

1. 配置坑 · 来源证据：Please add support for the Vietnamese language.

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Please add support for the Vietnamese language.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/370 | 来源类型 github_issue 暴露的待验证使用条件。

2. 能力坑 · 能力证据存在缺口

• 严重度：high
• 证据强度：source_linked
• 发现：Sandbox install result is missing.
• 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
• 证据：evidence.evidence_gaps | https://github.com/AIDotNet/OpenDeepWiki | Sandbox install result is missing.

3. 运行坑 · 沙箱验证已有失败原因

• 严重度：high
• 证据强度：runtime_trace
• 发现：llm_blocked_sandbox_execution
• 对用户的影响：失败原因未处理前，不应向用户暗示项目可顺利运行。
• 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
• 证据：sandbox_validation_results | planner_decision=llm_blocked; planner_reason=docker compose up -d is not in the deterministic allowlist and is not a single-package pip/npm/npx/uvx install, so it cannot be selected under the isolated_install policy.; failure=llm_blocked_sandbox_execution

4. 安全/权限坑 · 来源证据：[Proposal] Upstream generic features from a self-hosted fork (Forgejo, MCP auth, i18n, OAuth…) / 回馈通用功能提案

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Proposal] Upstream generic features from a self-hosted fork (Forgejo, MCP auth, i18n, OAuth…) / 回馈通用功能提案
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/371 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker compose up -d
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker compose up -d
• 证据：identity.distribution | https://github.com/AIDotNet/OpenDeepWiki | docker compose up -d

6. 安装坑 · 安装命令尚未沙箱验证

• 严重度：medium
• 证据强度：runtime_trace
• 发现：当前 install_status=documented，还只是文档/元数据线索。
• 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
• 复现命令：docker compose up -d
• 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
• 证据：downstream_validation.install_status | https://github.com/AIDotNet/OpenDeepWiki | install_status=documented; command=docker compose up -d

7. 安装坑 · 来源证据：【bug】如果导入了一个分支，则无法再次导入其他分支代码

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：【bug】如果导入了一个分支，则无法再次导入其他分支代码
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/353 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据：bad_response_status_code 最新代码调用本地llm模型api报错 Can only get item pairs from a mapping

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bad_response_status_code 最新代码调用本地llm模型api报错 Can only get item pairs from a mapping
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/307 | 来源类型 github_issue 暴露的待验证使用条件。

9. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/AIDotNet/OpenDeepWiki | README/documentation is current enough for a first validation pass.

10. 运行坑 · Quick Start 尚未实际跑通

• 严重度：medium
• 证据强度：runtime_trace
• 发现：quickstart_status=not_attempted。
• 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
• 观测结果：sandbox_install_status=blocked; sandbox_quickstart_status=blocked; failure=llm_blocked_sandbox_execution
• 证据：downstream_validation.quickstart_status | https://github.com/AIDotNet/OpenDeepWiki | quickstart_status=not_attempted; sandbox_quickstart_status=blocked

11. 维护坑 · 来源证据：【bug】wiki界面点击导出压缩包按钮，生成的压缩包无法打开

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：【bug】wiki界面点击导出压缩包按钮，生成的压缩包无法打开
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/355 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

12. 维护坑 · 来源证据：【bug】有子标题的目录，点击后文档显示不存在

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：【bug】有子标题的目录，点击后文档显示不存在
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/354 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

13. 维护坑 · 来源证据：【ux】目录滚动困难

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：【ux】目录滚动困难
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/356 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

14. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/AIDotNet/OpenDeepWiki | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/AIDotNet/OpenDeepWiki | no_demo; severity=medium

16. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 证据：risks.safety_notes | https://github.com/AIDotNet/OpenDeepWiki | No sandbox install has been executed yet; downstream must verify before user use.

17. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/AIDotNet/OpenDeepWiki | no_demo; severity=medium

18. 安全/权限坑 · 来源证据：WikiGenerator.ExecuteAgentWithRetryAsync has no max-tool-call guard — a stuck-loop model burns MaxRetryAttempts × (Time…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：WikiGenerator.ExecuteAgentWithRetryAsync has no max-tool-call guard — a stuck-loop model burns MaxRetryAttempts × (TimeoutSeconds / per-call) paid LLM calls pe…
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/374 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：生成的文档未保存到数据库

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：生成的文档未保存到数据库
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/AIDotNet/OpenDeepWiki/issues/279 | 来源类型 github_issue 暴露的待验证使用条件。

20. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/AIDotNet/OpenDeepWiki | issue_or_pr_quality=unknown

21. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/AIDotNet/OpenDeepWiki | release_recency=unknown