# Architecture

> Tier 2 文档（LLM 起草 + 人审）。当前架构。变更需先开 wiki PR + 写新 ADR，详见 [`framework-redesign.md` §3.6](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md)。
>
> 注：framework-redesign.md 是 koala 框架的设计文档，托管在 koala-agent/koala 仓库；新项目可参考但不必复制。

## 系统视角

<一段话描述系统组成与对外接口。说清楚有哪些主要组件、谁是 user-facing、依赖方向。>

```
<系统组成图。建议用 ASCII 模块图，标注依赖方向。例如：

                ┌──────────────┐
                │   <shell>    │   ← user-facing
                └──────┬───────┘
                       │
       ┌──────────┬────┴─────┬──────────┐
       ▼          ▼          ▼          ▼
   ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
   │<mod 1>│ │<mod 2>│ │<mod 3>│ │<mod 4>│
   └───┬───┘ └───┬───┘ └───┬───┘ └───┬───┘
       └─────────┴────┬────┴─────────┘
                      ▼
                 ┌─────────┐
                 │ <core>  │   ← pure logic, no I/O
                 └─────────┘
>
```

## 模块清单

| 模块 | 职责（一句话） | 依赖 |
|---|---|---|
| <module-1> | <职责> | <依赖> |
| <module-2> | <职责> | <依赖> |
| <module-3> | <职责> | <依赖> |

## 数据流

<典型请求 / 任务的端到端路径。建议用编号步骤 + 简图描述一个核心流程，例如"用户操作 → 进入哪个入口 → 经过哪些模块 → 落到哪里"。>

```
<数据流示意，可用编号步骤或 ASCII 流程图>
```

## 设计原则（违反 = CI 红线）

1. **单一职责**：每个模块一句话能说清；说不清 → 拆
2. **显式依赖**：依赖图无环；深度 ≤ 4；方向单向（shell → domain → core，反向禁止）
3. **可独立测**：每个模块脱离其他模块能单测，依赖可 mock
4. **命名可猜**：同一概念全仓同一词；新人看名字能猜对函数行为
5. **抽象有度**：抽象层数 ≤ 3；新增抽象需 ADR
6. **副作用边界**：I/O 集中在外壳，core 是纯逻辑
7. **公开 API 稳定**：breaking change 必须 ADR + major version bump

> 这 7 条由 invariant suite 强制（详见 `.koala/architecture.toml` 与 `.koala/invariants/`）。

## 模块边界

```toml
# .koala/architecture.toml
[layers]
core    = ["<core 模块清单>"]
domain  = ["<domain 模块清单>"]
shell   = ["<shell 模块清单>"]

[forbidden]
core   -> domain    # core 不依赖 domain
core   -> shell     # core 不依赖 shell
domain -> shell     # domain 不依赖 shell
```

## 副作用集中点

所有 I/O（fs / network / process / db）集中在以下位置：

- `<shell 入口路径>` — 用户命令入口、参数解析与 dispatch
- `<shell io 模块路径>` — 文件读写、网络调用、进程调用
- <其他副作用边界，如有>

`core` 与 domain 模块的 lib 路径下**禁止任何 I/O**（CI 用静态分析强制）。

## 配置文件位置

| 文件 | 用途 | 维护 |
|---|---|---|
| `koala.toml`（仓根） | 项目级配置（profile / 阈值） | 人编 |
| `.koala/architecture.toml` | 架构边界规则 | 人编 |
| `.koala/invariants/*.toml` | 自定义 invariant 规则集 | 人编 |
| `.koala/cache/` | 验证缓存（`.gitignore`） | CI 写 |
| `<其他项目特定配置>` | <用途> | <谁编> |

## 状态持久化

**没有自造 store**——git is the database。所有"状态"活在 git / GitHub 中：

| 状态类型 | 存放位置 |
|---|---|
| 工作单元（story） | GitHub Issue |
| 决策记录 | `wiki/decisions/NNNN-*.md` |
| Reviewer 证据 | `.review/round-N/*.md`（git-tracked） |
| 健康指标 | `wiki/health.md`（CI 自动写） |
| <项目特定状态> | <位置> |

## 性能目标

| 操作 | p50 | p99 | 说明 |
|---|---|---|---|
| <core 操作 1> | <值> | <值> | <说明> |
| <core 操作 2> | <值> | <值> | <说明> |

> 性能基线由 `.koala/invariants/perf.toml` 强制。回归 → CI 红线。

## 关键决策（参考 ADR）

| 主题 | ADR |
|---|---|
| <决策主题 1> | [ADR-NNNN](decisions/NNNN-<title>.md) |
| <决策主题 2> | [ADR-NNNN](decisions/NNNN-<title>.md) |

## 测试覆盖矩阵

详见 [testing.md](testing.md)。当前覆盖率（auto-generated to [health.md](health.md)）：

- 单元测试：<%>
- 集成测试：<%>
- E2E：<覆盖范围>

## 演化原则

**架构是给当前规模的**，不为想象中的未来设计。如果需求出现：

- 新增模块：必须 ADR + 证明无法在现有模块内消化
- 拆分模块：必须 invariant 报警（如某模块行数超阈值 / 内聚指标恶化）触发
- 删除模块：在季度 [pruning sprint](https://github.com/koala-agent/koala/blob/main/wiki/specs/framework-redesign.md) 中决定

**架构变更默认阻塞，必须人审。**

---

> 此文件由 `koala-core init` 创建。删除 `<...>` 占位后开始填写。
> 写作约束：< 500 行；季度级更新；改动需 ADR。Tier 2（LLM 起草 + 人审）。
