Kode-cli/docs/develop-zh/architecture.md

# 系统架构

## 高层架构

```
┌─────────────────────────────────────────────────────────────┐
│                        用户界面层                             │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  CLI 入口   │  │     REPL     │  │  React/Ink UI    │  │
│  │  (cli.tsx)  │  │  (REPL.tsx)  │  │     组件         │  │
│  └─────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      命令与控制层                             │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │    命令      │  │   查询引擎    │  │    上下文管理     │  │
│  │  (斜杠 /)   │  │              │  │                  │  │
│  └─────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                       工具执行层                              │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  文件工具    │  │   系统工具    │  │    AI 工具       │  │
│  │ (读/写/编辑) │  │ (Bash/Grep)  │  │  (Task/Think)    │  │
│  └─────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                      服务集成层                              │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ AI 提供商   │  │  MCP 服务器   │  │   外部 API       │  │
│  │(Claude/GPT) │  │ (stdio/SSE)  │  │  (Git/Sentry)    │  │
│  └─────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                       基础设施层                              │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  配置管理    │  │   权限系统    │  │   日志与错误      │  │
│  │             │  │              │  │     处理         │  │
│  └─────────────┘  └──────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## 组件关系

### 数据流架构

```
用户输入 → 命令解析器 → 路由决策
                          ↓
                ┌─────────────────────┐
                │    是斜杠命令吗？     │
                └─────────────────────┘
                          ↓
          是 ←────────────┼────────────→ 否
           ↓                              ↓
    ┌──────────────┐              ┌──────────────┐
    │  命令处理器   │              │   AI 查询     │
    └──────────────┘              └──────────────┘
           ↓                              ↓
    ┌──────────────┐              ┌──────────────┐
    │     执行     │              │   工具选择    │
    └──────────────┘              └──────────────┘
           ↓                              ↓
    ┌──────────────┐              ┌──────────────┐
    │   返回结果   │              │   工具执行    │
    └──────────────┘              └──────────────┘
           ↓                              ↓
           └──────────┬──────────────────┘
                      ↓
              ┌──────────────┐
              │   渲染响应    │
              └──────────────┘
```

### 模块依赖图

```
cli.tsx (入口点)
    ├── REPL.tsx (交互模式)
    │   ├── PromptInput.tsx
    │   ├── MessageResponse.tsx
    │   └── query.ts (AI 编排)
    │       ├── tools.ts (工具注册)
    │       │   ├── BashTool
    │       │   ├── FileEditTool
    │       │   ├── GrepTool
    │       │   └── [其他工具]
    │       ├── permissions.ts
    │       └── context.ts
    ├── commands.ts (命令系统)
    │   ├── 内置命令
    │   ├── MCP 命令
    │   └── 自定义命令
    └── services/
        ├── claude.ts
        ├── openai.ts
        ├── mcpClient.ts
        └── statsig.ts
```

## 核心模块交互

### 1. 对话流程

```
用户提示
    ↓
上下文注入 (AGENTS.md, git 状态等)
    ↓
模型选择 (基于上下文大小)
    ↓
带工具的 API 请求
    ↓
流式响应
    ↓
工具使用检测
    ↓
权限检查
    ↓
工具执行
    ↓
结果集成
    ↓
继续或完成
```

### 2. 工具执行管道

```
AI 请求工具使用
    ↓
工具验证 (Zod Schema)
    ↓
权限检查
    ├── 宽松模式 → 自动批准安全操作
    └── 安全模式 → 请求用户权限
    ↓
工具执行 (异步生成器)
    ├── 产生进度更新
    ├── 处理取消
    └── 返回结果
    ↓
为 AI 格式化结果
    ↓
继续对话
```

### 3. 配置级联

```
环境变量
    ↓
全局配置 (~/.claude/config.json)
    ↓
项目配置 (./.claude/config.json)
    ↓
运行时覆盖 (CLI 标志)
    ↓
有效配置
```

### 4. MCP 服务器集成

```
MCP 服务器配置
    ↓
服务器启动 (stdio/SSE)
    ↓
工具发现
    ↓
动态工具注册
    ↓
对话中可用的工具
    ↓
通过 MCP 协议执行工具
    ↓
结果转换
```

## 关键架构决策

### 1. 工具抽象
每个功能都是实现标准接口的工具：
```typescript
interface Tool {
  name: string
  description: string
  inputSchema: ZodSchema
  needsPermissions(): boolean
  call(): AsyncGenerator<ToolCallResult>
  renderResultForAssistant(): string
}
```

### 2. 流式架构
所有长时间运行的操作都使用异步生成器：
- 启用实时进度更新
- 支持任何时候取消
- 允许增量结果显示

### 3. 终端中的 React
使用 React 与 Ink 用于终端 UI：
- 组件可重用性
- 状态管理
- 复杂的交互式 UI
- 一致的样式

### 4. 权限层
多级权限系统：
- **工具级别**：每个工具声明权限需求
- **会话级别**：当前会话的临时权限
- **持久级别**：跨会话保存的权限
- **模式级别**：安全与宽松模式

### 5. 上下文管理
自动上下文注入：
- 项目文件 (AGENTS.md, CLAUDE.md)
- Git 状态和最近的提交
- 目录结构
- 先前的对话历史

## 模块通信模式

### 事件驱动更新
组件通过以下方式通信：
- React props 和回调
- 用于取消的中止信号
- 用于更新的进度生成器
- 用于横切关注点的事件发射器

### 服务集成
通过以下方式访问外部服务：
- 专用服务模块
- 统一错误处理
- 带退避的重试逻辑
- 流式响应处理

### 配置访问
通过以下方式访问配置：
- 单例配置管理器
- 首次访问时延迟加载
- 版本更改时自动迁移
- 加载时验证

## 安全架构

### 权限模型
```
请求 → 权限检查 → 决策
         ↓            ↓
    ┌──────────┐  ┌──────┐
    │ 检查缓存  │  │ 拒绝  │
    └──────────┘  └──────┘
         ↓
    ┌──────────┐
    │ 检查会话  │
    └──────────┘
         ↓
    ┌──────────┐
    │ 询问用户  │
    └──────────┘
         ↓
    ┌──────────┐
    │ 缓存决策  │
    └──────────┘
```

### 文件系统安全
- 基于目录的访问控制
- 路径遍历防护
- 符号链接解析
- 隐藏文件保护

### 命令执行安全
- 命令批准系统
- 环境变量清理
- 工作目录限制
- 输出大小限制

## 性能考虑

### 缓存策略
- 模型响应缓存在内存中
- 带新鲜度检查的文件读取缓存
- 每个会话的配置缓存
- MCP 工具发现缓存

### 延迟加载
- 首次使用时加载命令
- 按需启动 MCP 服务器
- 增量加载上下文
- 需要时加载重型依赖

### 流式优化
- 分块响应处理
- 增量渲染
- 部分结果显示
- 早期终止支持

## 扩展点

### 添加新工具
1. 创建扩展 Tool 的类
2. 实现所需方法
3. 在 tools.ts 中注册
4. 工具自动可用

### 添加 AI 提供商
1. 实现提供商接口
2. 添加到 ModelManager
3. 在模型配置文件中配置
4. 提供商可供使用

### 添加命令
1. 创建命令处理器
2. 在 commands.ts 中注册
3. 通过斜杠可用命令

### 添加 MCP 服务器
1. 配置服务器详细信息
2. 服务器工具自动发现
3. 工具在对话中可用

## 系统边界

### 内部边界
- 清晰的模块接口
- 依赖注入
- 服务抽象
- 工具隔离

### 外部边界
- API 速率限制
- 文件系统访问控制
- 网络请求超时
- 资源消耗限制

## 可扩展性考虑

### 水平可扩展性
- 无状态命令执行
- 独立的工具操作
- 并行工具执行（安全时）
- 分布式 MCP 服务器

### 垂直可扩展性
- 大响应的流式传输
- 分块文件处理
- 增量上下文加载
- 内存高效缓存

这种架构为 AI 驱动的开发助手提供了强大、可扩展的基础，同时将安全性、性能和用户体验作为主要关注点。