CrazyBoyM 7a3c4a7baa Refactor project structure and update documentation

- 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

2025-08-11 21:31:18 +08:00

6.3 KiB

Raw Blame History

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 可以随着用户需求的发展而发展，同时保持稳定性和安全性。

6.3 KiB Raw Blame History Unescape Escape