---
name: grounded-knowledge-prepare
description: "知识准备：确保目标项目的 .deepwiki/ 知识库就绪，为其他 grounded_workflows skill 提供知识基础。"
---

# 知识准备 Skill

本 Skill 是 **grounded_workflows** 体系中的**知识门禁**：在依赖项目内嵌知识（架构说明、模块边界、关键路径等）的其他 Skill 执行之前，必须先确认目标仓库根目录下的 `.deepwiki/` 知识库存在、结构可用，并在可接受的时间窗口内与源码保持相对一致。若知识缺失或陈旧，应明确阻断「盲目推理」，改为引导用户先补齐知识产物。

**适用场景**：任何需要以 `.deepwiki/` 为事实来源的后续工作流（规划、评审、落地实现前的上下文构建等）。

**不适用场景**：用户明确仅需一次性问答且不要求持久化 wiki 产物；或目标并非本地代码仓库。

---

## Checklist

执行本 Skill 时，**必须按顺序完成**以下步骤，不得跳过；任一步无法完成时，在报告中说明阻塞原因与下一步。

### 步骤 1：识别目标项目路径

1. 若用户在指令中已给出绝对路径或相对路径，将其规范化为**项目根目录**（含 `README`、清单文件或 `src/` 等典型根标识的目录）。
2. 若未给出路径，则以**当前 Cursor 工作区根目录**作为默认目标；若工作区为多根，列出候选根目录并请用户**明确选定一个**作为 `PROJECT_ROOT`。
3. 将最终确定的 `PROJECT_ROOT` 写入后续步骤的上下文（所有路径均相对于该根，除非使用绝对路径）。

### 步骤 2：检查 `.deepwiki/` 是否存在

1. 在 `PROJECT_ROOT` 下检查是否存在目录 `.deepwiki/`（注意前导点号，区分大小写）。
2. 若不存在，**不进入**大纲与新鲜度细节校验，直接跳转至**步骤 3**。
3. 若存在，继续**步骤 4**。

### 步骤 3（`.deepwiki/` 不存在时）：引导生成知识库

向用户输出清晰引导，说明必须先通过本项目内置的 **grounded-deepwiki** skill 的 **generate-wiki** 模式生成标准目录结构（含 `_outline.md`、`pages/`、`README.md` 等）。

**须包含的要点**：

- 说明产物位置：`PROJECT_ROOT/.deepwiki/`。
- 说明推荐模式：`generate-wiki`（触发语示例：「为该项目生成 wiki / 生成知识库 / 创建文档」）。
- **引导方式**：读取并执行本 grounded_workflows 内置的 grounded-deepwiki skill：
  - Skill 路径：`skills/grounded-deepwiki/SKILL.md`（相对于 grounded_workflows 根目录）
  - 示例指令：「请使用 grounded-deepwiki skill 的 generate-wiki 模式，对 `{PROJECT_ROOT}` 生成知识库」
  - grounded-deepwiki skill 会将输出写入 `PROJECT_ROOT/.deepwiki/`，包含 `_outline.md`、`pages/*.md`、`README.md` 等标准结构（详见 `skills/grounded-deepwiki/reference/output-spec.md`）

完成后请用户重新触发本 **grounded-knowledge-prepare** Skill。此情况下最终报告状态应为 **NOT_READY**。

### 步骤 4（`.deepwiki/` 存在时）：读取并校验 `_outline.md`

1. 使用 Read 工具读取 `PROJECT_ROOT/.deepwiki/_outline.md`。
2. **结构完整性**最低标准（须全部满足，否则视为不完整）：
   - 文件非空，且为有效 Markdown 文本。
   - 文档中能够识别**明确的页面列表**（例如有序/无序列表项、表格行，或带编号的章节与页面标题对应关系），且每项能映射到预期 wiki 页面主题（标题或 slug 均可）。
   - **页面数量合理**：与 DeepWiki 约定一致，通常为 **4～12** 个规划页面（若为大仓「精简模式」则不少于 **4**）；若明显少于 4 或列表项与 `pages/` 下实际文件严重不一致（见步骤 5 交叉核对），则判定为不完整。
3. 若 `_outline.md` 缺失、无法读取或上述校验失败，视为 **NOT_READY**（结构不完整），在报告中列出具体缺失项；可建议用户重新运行 **generate-wiki** 或修复大纲后重试。

### 步骤 5：核对页面数量并列出覆盖主题

1. 列出 `PROJECT_ROOT/.deepwiki/pages/` 下符合命名约定的页面文件（如 `NN-kebab-title.md`），统计数量 **N_pages**。
2. 将 `_outline.md` 中解析出的主题与 `pages/` 文件名/标题做对照；记录**覆盖主题列表**（使用人类可读的中文或原文标题，按大纲顺序或编号排序）。
3. 若 `pages/` 为空或与大纲严重不符，将状态倾向 **NOT_READY**，并在报告中说明偏差。

### 步骤 6：新鲜度检查

1. **知识库一侧**：取得 `.deepwiki/` 目录内（含子目录）**最近一次内容修改时间**（建议使用 `find` + `stat` 或等价方式取最大 `mtime`），记为 **T_wiki**。
2. **源码一侧**：在 `PROJECT_ROOT` 下对典型源码与配置扩展名采样扫描最近修改时间（例如 `*.ts`、`*.tsx`、`*.js`、`*.py`、`*.go`、`*.rs`、`*.java`、`*.kt`、`*.swift`、`*.rb`、`*.vue`、`*.json`、`*.toml`、`*.yaml`、`*.yml` 等，**排除** `node_modules/`、`.git/`、`dist/`、`build/`、`target/`、`.venv/`、`__pycache__/` 等构建与依赖目录），取得**最大** `mtime`，记为 **T_src**。
3. **对比规则**：
   - 计算 **T_wiki** 距**当前日期**的天数差 **D_age**（可按日历日或 24 小时倍数一致化，并在报告中说明取值方式）。**D_age** 用于下节 **READY / STALE** 的主判定。
   - 若 **T_src** 晚于 **T_wiki** 超过 **24 小时**，在报告中单独增加**提示项**「源码较知识库新」，供用户判断是否需要提前刷新 wiki；**不单独**因此将 **READY** 改为 **STALE**（**STALE** 仅由「超过 7 天未更新」触发，见下节）。

> **macOS / BSD 提示**：可使用 `stat -f '%m %N'` 等格式；**Linux** 使用 `stat -c '%Y %n'`。跨平台脚本应以当前 OS 选择合适 `stat` 参数。

### 步骤 7：输出知识就绪报告

严格使用以下 Markdown 模板输出（字段值按实际检查结果填写；列表使用项目符号）：

```markdown
## 知识就绪报告
- **状态**: READY / NOT_READY / STALE
- **页面数**: N
- **覆盖主题**: [列表]
- **最后更新**: [日期]
- **建议**: 继续 / 更新知识库 / 生成知识库
```

- **最后更新**：使用 **T_wiki** 对应的 UTC 或本地日期（与命令输出一致即可），并注明时区或「本地时间」。
- **建议** 与 **状态** 对齐：**READY** →「继续」；**STALE** →「更新知识库」；**NOT_READY** →「生成知识库」或「修复后重新生成」。若报告含「源码较知识库新」而状态仍为 **READY**，可将 **建议** 写为「继续（建议择机更新知识库）」。

---

## 工具映射

| 步骤 | 工具 | 用途 |
|------|------|------|
| 检测目录 | Shell（`ls`、`test -d`） | 判断 `PROJECT_ROOT/.deepwiki/` 是否存在；必要时列出 `pages/` |
| 读取大纲 | Read | 读取 `.deepwiki/_outline.md` 全文以做结构与主题解析 |
| 新鲜度检查 | Shell（`stat`、`find`） | 聚合 `.deepwiki/` 与源码树最近修改时间并比较 |
| 生成报告 | 直接输出 | 向用户展示「知识就绪报告」模板及解释性说明 |

---

## 状态判定规则

按优先级从高到低判定（**NOT_READY** 优先于 **STALE**，**STALE** 优先于 **READY**）：

| 状态 | 条件 |
|------|------|
| **NOT_READY** | `.deepwiki/` **不存在**；或 **结构不完整**（`_outline.md` 缺失/不可读、无法解析出合理页面列表、`pages/` 与大纲严重不一致、页面数明显不在合理区间等任一失败）。 |
| **STALE** | `.deepwiki/` **存在**且**结构完整**（步骤 4、5 全部通过），但自 **T_wiki** 起已超过 **7 天**未更新（**D_age > 7**）。 |
| **READY** | `.deepwiki/` **存在**且**结构完整**，且 **D_age ≤ 7**（在 7 天内有过以 `.deepwiki/` 为准的更新）。 |

**执行策略**：

- **READY**：可告知用户后续 grounded_workflows Skill 可将 `.deepwiki/` 作为主要 grounded 知识源。
- **STALE**：必须在报告中说明「知识库已超过 7 天未更新」；默认 **建议** 为「更新知识库」。是否允许继续下游 Skill 由具体工作流策略决定，但须在报告中披露风险。
- **NOT_READY**：**不得**将缺失或结构无效的 wiki 当作事实来源推进关键决策；必须先完成生成或修复。

---

## 与其他 Skill 的协作

- **上游**：依赖用户或工作区提供正确的 `PROJECT_ROOT`；依赖内置的 **grounded-deepwiki** skill（`skills/grounded-deepwiki/SKILL.md`）生成 `.deepwiki/`。
- **下游**：其他需要「先读后写」或架构级推理的 grounded_workflows Skill 应在入口处声明：**若未通过 grounded-knowledge-prepare，则须先执行本 Skill 或等价检查**。

---

## 质量与边界

- 所有结论须基于工具实际输出，避免臆测目录存在或页面数量。
- 若项目极大导致 `find` 耗时过长，可先限制深度或对 `src/`、`lib/` 等主要源码目录扫描，并在报告中注明采样范围（**T_src** 仅作提示，不影响 **STALE** 的 7 日定义）。
- 本 Skill **不**负责编写 wiki 正文；仅负责**就绪判定**与**用户引导**。