# Wiki

> 项目知识库。按角色分顶层目录、目录内扁平。
>
> **设计哲学**：详见 [`framework-redesign.md`](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md) / [vision.md](vision.md)。
>
> 注：framework-redesign.md 是 koala 框架的设计文档，托管在 koala-agent/koala 仓库；新项目可参考但不必复制。

## 入口

- [Vision](vision.md) — 我们在造什么、5 年方向
- [Roadmap](roadmap.md) — 季度节奏与里程碑
- [Architecture](architecture.md) — 当前系统结构
- [Features](features/_index.md) — 特性总览（CI 自动生成）
- [Decisions / ADRs](decisions/_index.md) — 架构决策日志
- [Health](health.md) — 实时健康指标（CI 自动写）
- [Runbook](runbook.md) — 安装、命令、故障排除
- [Testing](testing.md) — 测试策略与工具链
- [Tech Debt](tech-debt.md) — 技术债清单（链 issue）

## 目录结构

```
wiki/
├── README.md            ← 你在这里
│
├── vision.md            Tier 3 (人写)
├── roadmap.md           Tier 3
├── architecture.md      Tier 2 (LLM 起草 + 人审)
├── runbook.md           Tier 2
├── testing.md           Tier 3
├── tech-debt.md         Tier 1 (CI 部分自动)
├── health.md            Tier 1 (CI 全自动)
│
├── features/            一文件一特性，平铺
│   ├── _template.md     复制粘贴用模板
│   ├── _index.md        Tier 1 自动生成
│   └── <feature>.md     ...
│
├── decisions/           一文件一 ADR，编号顺序，永不删
│   ├── _index.md        Tier 1 自动生成
│   └── NNNN-<title>.md  ...
│
├── specs/               叙事性设计文档（多章节，narrative）
│   └── README.md        约定说明
│
├── rfcs/                RFC 提案（讨论中，未成 ADR）
│   └── README.md        约定说明
│
├── migrations/          大版本迁移指南
│   └── README.md        约定说明
│
├── post-mortems/        事故复盘（按时间戳命名，永不删）
│   └── README.md        约定说明
│
└── _tags/               Tier 1 自动生成的 tag 索引
    └── <tag>.md         ...
```

## 知识归属：判断口诀

| 性质 | 位置 |
|---|---|
| 当前态参考（"现在长什么样"） | wiki 顶层 |
| 单个决策 ADR | `decisions/NNNN-*.md` |
| 叙事性设计 / 多章节论证 | `specs/` |
| RFC（讨论中的提案） | `rfcs/` |
| 大版本迁移指南 | `migrations/` |
| 事故复盘 | `post-mortems/` |

## 三层分类（Tier）

| Tier | 谁写 | 自动化程度 | 例子 |
|---|---|---|---|
| Tier 1 | CI | 完全自动，人不准编辑 | `health.md` / `_index.md` / `_tags/` |
| Tier 2 | LLM 起草 + 人审 | 季度刷新 PR | `architecture.md` / `runbook.md` |
| Tier 3 | 纯人工 | 永不自动 | `vision.md` / `decisions/*.md` |

详见 [`framework-redesign.md` §3.4](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md)。

## 怎么用

### 我是新人，第一次看这个项目

1. 读 [vision.md](vision.md)（5 分钟）
2. 读 [architecture.md](architecture.md)（15 分钟）
3. 浏览 [features/_index.md](features/_index.md)（5 分钟）
4. 跑 [runbook.md](runbook.md) 安装段把项目跑起来（5 分钟）

总计 30 分钟可以开始动手。卡住的地方记下来反馈给团队。

### 我要加新功能

参考 [`framework-redesign.md` §3.6 体量自适应流程](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md)：

- 小改（< 20 行 / 不跨模块）：直接 PR + smoke test
- 中改（< 200 行）：PR 同步更新对应 `features/X.md`
- 大改（跨模块 / 新功能）：先写 ADR + 改 `architecture.md`，开 wiki-only PR 让人类批准设计，再写代码

### 我要查一个决策为什么这么做

```bash
# 在 decisions/ 里 grep
grep -r "<keyword>" wiki/decisions/

# 或者 koala-core adr 命令
koala-core adr list --tag <topic>
koala-core adr show <NNNN>
```

### 我要改 wiki 内容

| 想改什么 | 怎么改 |
|---|---|
| 修 Tier 1 文件（`health` / `_index` / `_tags`） | **不要直接改**，改源（代码 / frontmatter）后跑 `koala-core wiki gen` |
| 加新 feature | `cp features/_template.md features/<name>.md`，编辑 frontmatter 与正文 |
| 改 `architecture.md` | 先开 ADR（这是大改）→ 人审 → 再改 |
| 加新 ADR | `koala-core adr new "<标题>"` → 编辑 → commit |
| 推翻一个 ADR | 写新 ADR + `koala-core adr supersede <old> <new>` |

## 写作规范

每种文件都有写作铁律：

- **Feature**：[`features/_template.md`](features/_template.md)
- **ADR**：[`framework-redesign.md` §3.3](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md)
- **架构 / runbook**：Tier 2，LLM 起草后人审

通用原则：

- 写代码自证不了的东西（why、tradeoff、context、history）
- 不写代码已经能说的东西（what、how、列表式 API）
- 用户视角的 behavior（"用户跑 X 看到 Y"）
- 不写开发者视角的 behavior（"调用 fn 返回 Result"）

## CI 强制（违反 = PR 拒）

| 检查项 | 工具 |
|---|---|
| Wiki ↔ code drift | `koala-core drift` |
| ADR 引用悬空 | `koala-core adr validate` |
| Acceptance criteria 链向真实 test | `koala-core drift` |
| Runbook 命令可跑 | doctest |
| Tier 1 文件被手编 | `koala-core wiki check` |

---

> 此文件由 `koala-core init` 创建。可按项目实际调整入口列表与目录结构，但保留三层 Tier 分类与 CI 强制段。
