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. 工具抽象

每个功能都是实现标准接口的工具：

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 驱动的开发助手提供了强大、可扩展的基础，同时将安全性、性能和用户体验作为主要关注点。