---
name: grounded-deepwiki
description: "项目知识库生成与分析。扫描本地项目代码，生成结构化 .deepwiki/ 知识库（wiki 文档、架构分析、深度研究），为 grounded_workflows 提供知识源。"
---

# DeepWiki — 项目知识库生成与分析

扫描本地项目代码，生成结构化 wiki 文档、回答代码问题、进行深度研究和架构分析。仅使用 agent 内置工具，无外部依赖、无 API key、无服务端。

## 模式

本 skill 支持四种模式。根据用户意图选择：

| 模式 | 触发关键词 | 输出 |
|------|-----------|------|
| **generate-wiki** | "生成 wiki"、"生成文档"、"创建知识库"、"generate wiki" | `.deepwiki/pages/*.md` + 索引 |
| **ask** | 关于代码的具体问题："X 怎么工作？"、"Y 在哪里？" | 直接在对话中回答 |
| **deep-research** | "深入研究"、"深度分析"、"deep research" | `.deepwiki/research/{topic}.md` |
| **analyze** | "分析架构"、"依赖关系"、"模块图" | `.deepwiki/analysis/*.md` |

意图不明确时，询问用户选择哪种模式。

---

## Phase 1：项目探索（所有模式通用）

所有模式都从这里开始。对于 **ask** 模式，如果对话中已有项目上下文，可以简化（跳过完整目录扫描）。

### Step 1：扫描文件结构

读取 `reference/file-filters.md` 获取排除规则，然后：

1. 列出顶层目录，了解项目布局
2. 递归扫描每个重要目录（跳过 file-filters.md 中的排除目录）
3. 构建紧凑的文件树：显示目录及文件数量，而非每个文件

对于大型项目（1000+ 文件），初始限制为 3 层深度，需要时再展开。

### Step 2：读取关键文件

读取以下文件（如果存在）以理解项目：

**必读：**
- `README.md`（或 `README.rst`、`README`）
- 包清单：`package.json`、`pyproject.toml`、`Cargo.toml`、`go.mod`、`pom.xml`、`build.gradle`、`Gemfile`、`composer.json`、`mix.exs`

**存在时读取（补充上下文）：**
- `Dockerfile`、`docker-compose.yml`
- `.github/workflows/*.yml`（找到的第一个）
- 主入口：在根目录或 `src/` 中查找 `main.*`、`index.*`、`app.*`、`server.*`

### Step 3：构建项目画像

从已读文件中确定：

- **语言**：使用了哪些编程语言（通过文件扩展名和清单文件）
- **框架**：使用了哪些框架（从清单文件的依赖中）
- **项目类型**：库、Web 应用、CLI 工具、API 服务、monorepo 或其他
- **规模**：小型（<50 源文件）、中型（50-200）、大型（200+）

将此画像保留在上下文中，指导后续流程。

---

## 模式：generate-wiki

完整的 wiki 生成。在 `.deepwiki/` 中创建结构化文档集。

### Step 1 — 规划 Wiki 结构

1. 读取 `prompts/wiki-structure.md` 获取模板
2. 读取 `examples/wiki-structure-example.md` 查看预期输出格式
3. 将项目画像（文件树 + README 摘要 + 技术栈）填入模板
4. 根据以下条件选择完整模式（8-12 页）或精简模式（4-6 页）：
   - 用户的明确要求，或
   - 项目规模：大型项目默认完整模式，小型默认精简模式
5. 生成 wiki 大纲，格式为 Markdown 编号列表
6. 将大纲写入 `.deepwiki/_outline.md`

继续之前审查大纲。如果用户在对话中，简要展示大纲并询问是否需要调整。否则直接继续。

### Step 2 — 生成页面

读取 `prompts/page-content.md` 获取生成模板，然后读取 `reference/output-spec.md` 获取格式规则。

按大纲顺序，逐页生成：

1. **收集上下文**：搜索与页面主题相关的代码：
   - 用页面标题和描述做语义搜索
   - Grep 大纲中提到的关键符号（类名、函数名、API 路由）
   - 读取大纲中该页 "Key files" 列出的文件
   - 如果找到少于 5 个相关文件，扩大搜索范围
2. **生成页面**，遵循 page-content.md 中的模板：
   - 以 `<details>` 源文件块开始
   - H1 标题，然后引言
   - 详细章节（H2/H3 标题）
   - Mermaid 图表（每页至少一个）
   - 结构化数据用表格
   - 全文引用源码
3. **写入文件**到 `.deepwiki/pages/{NN}-{slug}.md`

按顺序逐页处理，确保质量。

### Step 3 — 生成索引

所有页面写入后：

1. 创建 `.deepwiki/README.md`：
   - 项目标题和描述
   - 目录，链接到所有页面，按章节组织
2. 创建 `.deepwiki/_sidebar.md`，包含导航链接

详见 `reference/output-spec.md`。

---

## 模式：ask

回答关于代码库的具体问题。

1. 执行 Phase 1（简化版 — 如果上下文已建立则跳过完整扫描）
2. 如果之前 wiki 生成过，读取 `.deepwiki/_outline.md` 获取结构上下文
3. 搜索与问题相关的代码：
   - 用问题文本做语义搜索
   - Grep 提到的特定符号、函数名或模式
4. 读取最相关的文件（最多 10 个文件或文件片段）
5. 直接回答问题，包含：
   - 带文件路径和行号的代码引用
   - 基于实际源码的解释
   - 有助于解释架构或流程的 Mermaid 图表
6. 除非用户明确要求，不写输出文件

---

## 模式：deep-research

对特定代码主题的多轮深入调查。

1. 执行 Phase 1（完整探索）
2. 读取 `prompts/deep-research.md` 获取迭代模板
3. **迭代 1 — 研究计划：**
   - 遵循 deep-research.md 中的「Iteration 1」模板
   - 概述研究方法，识别关键代码区域，提供初步发现
   - 以「下一步」结尾
4. **搜索代码**：读取计划中识别的相关文件
5. **迭代 2-3 — 研究更新：**
   - 遵循「Iterations 2-3」模板
   - 基于前次发现深入，调查缺口
   - 每次迭代间搜索新代码
6. **最终迭代 — 结论：**
   - 遵循「Final Iteration」模板
   - 将所有发现综合为全面结论
7. 将最终报告写入 `.deepwiki/research/{topic-slug}.md`

---

## 模式：analyze

架构与依赖分析，重点输出图表。

1. 执行 Phase 1（完整探索）
2. 读取 `prompts/code-analysis.md` 获取分析模板
3. 确定哪些维度适用于该项目：
   - **架构分析** — 始终适用
   - **依赖分析** — 有包清单时适用
   - **数据流分析** — 有请求/响应模式的应用适用
   - **入口分析** — 应用程序（非库）适用
4. 对每个适用维度：
   - 搜索并读取相关代码（imports、入口、路由、配置）
   - 按模板生成分析
   - 写入 `.deepwiki/analysis/{dimension}.md`
5. 创建 `.deepwiki/analysis/README.md`，链接到所有分析报告

---

## 工具映射

| 操作 | Cursor | Claude Code |
|------|--------|-------------|
| 按语义搜索代码 | SemanticSearch | search |
| 搜索精确文本 | Grep | grep |
| 按名称查找文件 | Glob | glob |
| 读取文件 | Read | read |
| 写入文件 | Write | write |
| 运行 shell 命令 | Shell | bash |
| 列目录内容 | Shell: `ls` | bash: `ls` |

---

## 输出管理

所有输出写入项目根目录的 `.deepwiki/`。详见 `reference/output-spec.md`。

写入任何输出前：
1. 如不存在则创建 `.deepwiki/` 目录
2. 按需创建子目录（`pages/`、`analysis/`、`research/`）

文件命名规范：
- Wiki 页面：`{NN}-{kebab-case-title}.md`（如 `01-overview.md`）
- 分析报告：使用描述性 kebab-case 名称，无编号
- 研究报告：使用研究主题作为 slug（如 `caching-strategy.md`）

---

## 使用建议

- **大型项目**：先用精简模式快速了解，再展开特定章节
- **Monorepo**：一次聚焦一个 package/service，不要一次分析整个仓库
- **不熟悉的代码库**：先运行 `analyze` 模式了解全貌，再 `generate-wiki`
- **具体问题**：用 `ask` 模式 — 比生成完整 wiki 更快
- **复杂问题**：用 `deep-research` 做多轮深入调查