7a3c4a7baa
- Update project branding from claude-cli to Kode - Reorganize documentation with new development guides - Add CONTRIBUTING.md and Chinese README - Remove worktree_merge command and relocate system-design.md - Update dependencies and package configuration - Improve custom commands service with better error handling - Clean up storage utilities and debug logging
178 lines
6.3 KiB
Markdown
178 lines
6.3 KiB
Markdown
# Kode 系统概述
|
||
|
||
## 介绍
|
||
|
||
Kode 是一个 AI 驱动的终端助手，它将 Claude 和其他语言模型的强大功能直接带到您的命令行。它被设计为一个复杂的开发工具，能够理解您的代码库、执行命令，并通过自然语言交互处理复杂的工作流程。
|
||
|
||
## 核心设计理念
|
||
|
||
### 1. **工具优先架构**
|
||
Kode 中的所有内容都被抽象为"工具" - 一个自包含的功能单元，具有标准化的接口：
|
||
- 通过 Zod 模式进行输入验证
|
||
- 权限检查和安全性
|
||
- 带进度报告的异步执行
|
||
- 为 AI 和人类消费格式化结果
|
||
|
||
这种设计允许无限的可扩展性，同时保持一致性和安全性。
|
||
|
||
### 2. **终端原生体验**
|
||
与基于 Web 的 AI 助手不同，Kode 专为终端工作流程而构建：
|
||
- React 组件使用 Ink 直接渲染到终端
|
||
- 为高级用户提供键盘快捷键和类 vim 绑定
|
||
- 带实时进度指示器的流式响应
|
||
- 终端中的语法高亮和差异可视化
|
||
|
||
### 3. **上下文感知智能**
|
||
AI 自动通过以下方式理解您的项目：
|
||
- Git 状态和最近的提交
|
||
- 目录结构分析
|
||
- KODE.md 和 CLAUDE.md 项目文档
|
||
- .claude/commands/ 和 .kode/commands/ 中的自定义命令定义
|
||
- 先前的对话历史和分叉对话
|
||
|
||
### 4. **通过权限实现安全**
|
||
平衡安全性和可用性的双层安全模型：
|
||
- **宽松模式**（默认）：简化的工作流程，最少的中断
|
||
- **安全模式**（--safe 标志）：每个操作的细粒度权限请求
|
||
|
||
### 5. **提供商无关**
|
||
通过统一接口支持多个 AI 提供商：
|
||
- Anthropic Claude（主要）
|
||
- OpenAI 和兼容的 API
|
||
- 自定义端点和本地模型
|
||
- 基于上下文大小的自动模型切换
|
||
|
||
### 6. **通过 MCP 实现可扩展性**
|
||
模型上下文协议（MCP）集成支持：
|
||
- 第三方工具集成
|
||
- 自定义服务器连接（stdio/SSE）
|
||
- 从 Claude Desktop 配置导入
|
||
- 项目范围的服务器管理
|
||
|
||
## 技术栈
|
||
|
||
### 核心技术
|
||
- **语言**：TypeScript，采用宽松严格模式进行实用开发
|
||
- **运行时**：Node.js 18+，使用 Bun 进行开发，TSX 用于生产
|
||
- **UI 框架**：React + Ink 用于终端渲染
|
||
- **CLI 框架**：Commander.js 用于参数解析
|
||
- **验证**：Zod 用于运行时类型检查
|
||
|
||
### AI 集成
|
||
- **Anthropic SDK**：与 Claude 模型的原生集成
|
||
- **OpenAI SDK**：支持 GPT 模型和兼容的 API
|
||
- **流式传输**：服务器发送事件用于实时响应
|
||
- **上下文管理**：智能令牌计数和压缩
|
||
|
||
### 开发工具
|
||
- **构建系统**：基于 Bun 的自定义构建脚本
|
||
- **测试**：Bun 测试运行器，支持模拟
|
||
- **格式化**：Prettier，保持一致的代码风格
|
||
- **错误跟踪**：Sentry 集成用于生产监控
|
||
- **分析**：Statsig 用于功能标志和使用指标
|
||
|
||
## 系统架构层
|
||
|
||
### 1. 表示层
|
||
React 组件渲染到终端，提供：
|
||
- 交互式提示和选择
|
||
- 语法高亮的代码显示
|
||
- 进度指示器和加载动画
|
||
- 支持 markdown 的消息格式化
|
||
|
||
### 2. 命令与控制层
|
||
通过以下方式编排用户交互：
|
||
- 用于快速操作的斜杠命令系统
|
||
- 用于 AI 对话的自然语言处理
|
||
- 工具选择和执行管道
|
||
- 上下文注入和管理
|
||
|
||
### 3. 工具执行层
|
||
标准化的工具接口支持：
|
||
- 文件操作（读取、写入、编辑）
|
||
- Shell 命令执行
|
||
- 代码搜索和分析
|
||
- 任务管理和规划
|
||
- 通过 MCP 的外部工具集成
|
||
|
||
### 4. 服务集成层
|
||
连接到外部服务：
|
||
- AI 模型提供商（Anthropic、OpenAI）
|
||
- 用于扩展功能的 MCP 服务器
|
||
- 用于版本控制集成的 Git
|
||
- 用于项目分析的文件系统
|
||
|
||
### 5. 基础设施层
|
||
基础服务包括：
|
||
- 配置管理（全局/项目）
|
||
- 权限系统和安全性
|
||
- 日志记录和错误处理
|
||
- 会话和历史管理
|
||
- 成本跟踪和分析
|
||
|
||
## 关键设计模式
|
||
|
||
### 用于流式传输的异步生成器
|
||
工具使用异步生成器来产生进度更新，在长操作期间启用实时反馈，同时保持取消支持。
|
||
|
||
### 基于组件的 UI 架构
|
||
每个 UI 元素都是一个 React 组件，从简单的文本显示到复杂的交互式对话框，确保一致性和可重用性。
|
||
|
||
### 配置级联
|
||
设置从全局 → 项目 → 运行时流动，每个级别都有验证，允许灵活的自定义而不复杂。
|
||
|
||
### 错误边界
|
||
全面的错误处理确保优雅降级，提供用户友好的消息和自动错误报告。
|
||
|
||
### 上下文注入
|
||
相关的项目上下文会自动注入到 AI 对话中，无需手动指定即可提高响应质量。
|
||
|
||
## 开发原则
|
||
|
||
### 1. **用户体验优先**
|
||
每个功能都是为终端工作流程效率而设计的，具有键盘优先的交互和最小的上下文切换。
|
||
|
||
### 2. **渐进式披露**
|
||
复杂的功能隐藏在简单的界面后面，需要时可以使用高级选项。
|
||
|
||
### 3. **优雅失败**
|
||
错误会得到优雅的处理，提供有用的消息、后备选项和恢复建议。
|
||
|
||
### 4. **性能意识**
|
||
缓存、延迟加载和流式传输确保即使在大型代码库中也能进行响应式交互。
|
||
|
||
### 5. **默认安全**
|
||
对潜在危险的操作进行权限检查是强制性的，具有清晰的用户同意流程。
|
||
|
||
## 系统功能
|
||
|
||
### 核心功能
|
||
- **代码理解**：分析项目结构和关系
|
||
- **文件操作**：使用验证读取、写入和编辑文件
|
||
- **命令执行**：运行带输出捕获的 shell 命令
|
||
- **搜索与分析**：查找代码模式和依赖关系
|
||
- **任务管理**：规划和跟踪开发任务
|
||
|
||
### AI 增强功能
|
||
- **自然语言命令**：用简单的英语描述您想要的内容
|
||
- **上下文感知建议**：AI 理解您项目的具体情况
|
||
- **多步骤工作流**：自动分解复杂任务
|
||
- **代码生成**：按照项目模式创建新代码
|
||
- **重构支持**：安全地修改现有代码
|
||
|
||
### 集成功能
|
||
- **MCP 服务器**：连接到外部工具和服务
|
||
- **自定义命令**：定义可重用的基于 markdown 的命令
|
||
- **Git 集成**：理解并使用版本控制
|
||
- **多个 AI 模型**：根据任务在模型之间切换
|
||
|
||
## 未来可扩展性
|
||
|
||
该架构是为未来扩展而设计的：
|
||
- 可以通过实现工具接口添加新工具
|
||
- 可以通过 ModelManager 集成额外的 AI 提供商
|
||
- 自定义命令启用用户定义的工作流
|
||
- MCP 支持允许第三方扩展
|
||
- 可以以最小的更改添加插件系统
|
||
|
||
这种模块化、可扩展的设计确保 Kode 可以随着用户需求的发展而发展，同时保持稳定性和安全性。 |