# Grounded Workflows — 知识驱动的 AI 工作流系统

融合 **DeepWiki 知识源**、**Superpower 工作流模式**和 **Tree of Thoughts 结构化推理**的纯 Markdown skill 系统。所有 AI 推理和输出优先基于项目级 `.deepwiki/` 知识库，通过多路径生成→展开→评估→筛选的 ToT 流程，确保设计决策有据可循、创意探索结构化、输出质量可追溯。

---

## 架构

```mermaid
graph TD
    User[用户调用 skill] --> Router[SKILL.md 入口路由]
    Router --> DWS[deepwiki]
    Router --> KP[knowledge-prepare]
    Router --> BS[brainstorming]
    Router --> PL[planning]
    Router --> CR[critique]

    DWS -->|生成| DW[".deepwiki/ 知识库"]
    KP -->|检查| DW

    BS --> CB[context-building 协议]
    BS --> GR[grounding 协议]
    BS --> ToT[tot-reasoning 协议]

    PL --> CB
    PL --> GR
    PL --> ToT

    CR --> CB
    CR --> GR
    CR --> ToT

    CB --> DW
```

**协议协作关系：**

```
context-building ──→ grounding ──→ tot-reasoning
  (构建知识)        (控制优先级)    (多路径推理)
```

---

## 安装

**方式 1：`npx` 安装（推荐）**

```bash
npx grounded-workflows
```

安装器会优先选择**已存在**的宿主技能目录，并安装到其中的 `grounded-workflows/`：

```bash
~/.agents/skills
~/.cursor/skills
~/.codex/skills
```

如果以上目录都不存在，则回退到：

```bash
~/.agents/skills/grounded-workflows
```

安装器会在完成时打印最终安装路径。

验证安装结果：

```bash
ls ~/.agents/skills/grounded-workflows
```

**指定精确安装目录**

```bash
npx grounded-workflows --target ~/.cursor/skills/grounded-workflows
```

**覆盖已有安装**

默认不会覆盖目标目录；如需替换已有安装，显式传入 `--force`：

```bash
npx grounded-workflows --force
```

**方式 2：手动复制（备用）**

```bash
cp -R grounded_workflows ~/.agents/skills/grounded-workflows
```

---

## 快速开始

| 调用 | 效果 |
|------|------|
| 使用 `grounded-workflows` | 入口路由，自动识别意图 |
| 使用 `grounded-deepwiki` | 扫描项目代码，生成 `.deepwiki/` 知识库 |
| 使用 `grounded-knowledge-prepare` | 检查 `.deepwiki/` 知识源就绪状态 |
| 使用 `grounded-brainstorming` | 知识驱动的头脑风暴 |
| 使用 `grounded-planning` | 知识驱动的实施计划 |
| 使用 `grounded-critique` | 知识驱动的批判性审查 |

**典型工作流：**

1. `grounded-deepwiki` — 为目标项目生成 `.deepwiki/` 知识库
2. `grounded-knowledge-prepare` — 检查知识库就绪状态（存在、结构完整、新鲜度）
3. `grounded-brainstorming` — 从需求到设计方案
4. `grounded-planning` — 从设计方案到实施计划
5. `grounded-critique` — 审查设计或代码

---

## 目录结构

```
grounded_workflows/
├── SKILL.md                          # 入口路由
├── protocols/                        # 可复用协议（被 skill 引用）
│   ├── grounding.md                  # 知识优先级协议
│   ├── context-building.md           # 上下文构建协议
│   └── tot-reasoning.md              # Tree of Thoughts 推理协议
├── skills/                           # 可调用的工作流 skill
│   ├── grounded-deepwiki/             # 知识库生成（内置 DeepWiki）
│   │   ├── SKILL.md                  # 主 skill：4 种模式
│   │   ├── reference/                # 扫描规则、输出规范
│   │   ├── prompts/                  # 生成模板
│   │   └── examples/                 # Wiki 大纲示例
│   ├── grounded-knowledge-prepare/SKILL.md  # 知识准备（就绪检查）
│   ├── grounded-brainstorming/SKILL.md      # 头脑风暴
│   ├── grounded-planning/SKILL.md           # 计划制定
│   └── grounded-critique/SKILL.md           # 批判性审查
├── templates/                        # 输出模板
│   ├── brainstorming-output.md
│   ├── planning-output.md
│   └── critique-output.md
├── examples/                         # 使用示例
│   └── brainstorming-example.md
└── README.md
```

---

## 协议概览

| 协议 | 文件 | 职责 |
|------|------|------|
| 知识优先级 | `protocols/grounding.md` | 控制知识来源优先级 `[DW]` > `[SRC]` > `[EXT]`，确保输出有据可循 |
| 上下文构建 | `protocols/context-building.md` | 从 `.deepwiki/` 按需加载知识，构建任务相关上下文 |
| ToT 推理 | `protocols/tot-reasoning.md` | 多路径生成→展开→评估→筛选，结构化创造性推理 |

## Skill 概览

| Skill | 文件 | 触发场景 |
|-------|------|----------|
| grounded-deepwiki | `skills/grounded-deepwiki/SKILL.md` | 生成 wiki、分析架构、深度研究 |
| grounded-knowledge-prepare | `skills/grounded-knowledge-prepare/SKILL.md` | 首次使用、检查知识源 |
| grounded-brainstorming | `skills/grounded-brainstorming/SKILL.md` | 设计、方案探索、头脑风暴 |
| grounded-planning | `skills/grounded-planning/SKILL.md` | 制定实施计划、任务拆解 |
| grounded-critique | `skills/grounded-critique/SKILL.md` | 审查设计、代码、方案 |

---

## 设计原则

- **知识优先**：所有推理优先引用 `.deepwiki/` 知识，每个结论标注来源
- **协议复用**：三个协议被四个 skill 复用，改一处全局生效
- **结构化推理**：在决策点触发 ToT 多路径分析，避免单一思路偏见
- **可追溯性**：输出包含来源统计，`[EXT]` 超 40% 自动警告