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
491 lines
14 KiB
Markdown
491 lines
14 KiB
Markdown
# Kode 系统设计与工作流程深度解析报告
|
||
|
||
## 目录
|
||
1. [总体架构概览](#总体架构概览)
|
||
2. [核心系统层级](#核心系统层级)
|
||
3. [多模式启动架构](#多模式启动架构)
|
||
4. [工具系统深度解析](#工具系统深度解析)
|
||
5. [AI 对话工作流](#ai-对话工作流)
|
||
6. [上下文智能管理系统](#上下文智能管理系统)
|
||
7. [安全与权限设计](#安全与权限设计)
|
||
8. [状态管理与数据流](#状态管理与数据流)
|
||
9. [跨平台兼容性设计](#跨平台兼容性设计)
|
||
10. [监控与调试体系](#监控与调试体系)
|
||
|
||
---
|
||
|
||
## 总体架构概览
|
||
|
||
Kode 采用了创新的 **双轨架构模式 (Dual-Drive Architecture)**, 将 CLI 工具与 MCP 服务器能力统一在单一代码库中，实现了 **交互式终端 + 静态服务** 的混合运行模式。
|
||
|
||
### 架构特点
|
||
- **双入口设计**: CLI (`cli.tsx`) + MCP Server (`mcp.ts`)
|
||
- **统一业务核心**: 共享 Query 引擎、工具系统和状态管理
|
||
- **响应式渲染**: React/Ink 驱动的终端 UI 与 MCP 协议消息无缝对接
|
||
- **模块化工具系统**: 18 种工具的标准化实现架构
|
||
- **多供应商支持**: 统一的 OpenAI/Anthropic API 抽象层
|
||
|
||
---
|
||
|
||
## 核心系统层级
|
||
|
||
### 1. 应用层 (Application Layer)
|
||
```
|
||
src/entrypoints/
|
||
├── cli.tsx # CLI 应用主入口 (终端交互)
|
||
├── mcp.ts # MCP 服务器入口 (Claude Desktop 集成)
|
||
```
|
||
|
||
**CLI 模式核心职责**:
|
||
- React/Ink 应用初始化与渲染
|
||
- 会话状态管理 (loading, streaming, pending)
|
||
- 快捷键系统与多模式切换
|
||
- 浏览器 OAuth 流程处理
|
||
|
||
**MCP 模式核心职责**:
|
||
- JSON-RPC 协议实现
|
||
- 工具功能暴露与认证
|
||
- 与 Claude Desktop 的服务发现
|
||
- 结构化输入输出处理
|
||
|
||
### 2. 核心业务层 (Business Logic Layer)
|
||
```
|
||
src/
|
||
├── query.ts # AI 对话处理引擎 - 神经网络指挥中心
|
||
├── services/ # 外部服务集成
|
||
│ ├── claude.ts # Anthropic Claude (直连 + Bedrock + Vertex)
|
||
│ ├── openai.ts # OpenAI 兼容 API (GPT-4o, kimi 等)
|
||
│ └── oauth.ts # OAuth 认证流程
|
||
├── tools/ # 18 种工具系统的总部
|
||
└── utils/ # 工具箱与辅助功能
|
||
```
|
||
|
||
### 3. 用户界面层 (User Interface Layer)
|
||
```
|
||
src/screens/ # 全屏界面组件
|
||
├── REPL.tsx # 主 CLI 界面 (命令行读写循环)
|
||
├── Doctor.tsx # 系统诊断工具
|
||
└── LogList.tsx # 会话历史界面
|
||
|
||
src/components/ # 可复用 UI 组件
|
||
├── messages/ # 消息渲染组件系统
|
||
├── permissions/ # 权限请求对话框
|
||
└── binary-feedback/ # 用户反馈收集
|
||
```
|
||
|
||
---
|
||
|
||
## 多模式启动架构
|
||
|
||
### CLI 启动流程
|
||
```typescript
|
||
// cli.mjs -> tsx src/entrypoints/cli.tsx
|
||
const startCLI = async () => {
|
||
const app = render(<App />); // React/Ink 初始化
|
||
await app.waitUntilExit(); // 进入事件循环
|
||
};
|
||
```
|
||
|
||
### MCP 启动流程
|
||
```typescript
|
||
// Claude Desktop 通过 MCP 协议调用
|
||
const startMCPServer = () => {
|
||
const server = new Server(
|
||
{ name: 'kode', version: '1.0.0' },
|
||
{ capabilities: { tools: {} } }
|
||
);
|
||
server.connect(transport); // 连接到 Claude Desktop
|
||
};
|
||
```
|
||
|
||
### 运行时模式切换表
|
||
| 特征 | CLI 模式 | MCP 模式 |
|
||
|---|---|---|
|
||
| 启动方式 | `kode` 命令 | Claude Desktop 集成 |
|
||
| UI 机制 | React/Ink 终端 UI | 无直接 UI |
|
||
| 输入输出 | 实时终端交互 | JSON-RPC 消息 |
|
||
| 用户认证 | 浏览器 OAuth | 无 (代理认证) |
|
||
| 工具调用 | 实时权限请求 | 预配置权限 |
|
||
| 状态管理 | 会话级 | 请求级 |
|
||
|
||
---
|
||
|
||
## 工具系统深度解析
|
||
|
||
### 18 种核心工具架构
|
||
|
||
#### 工具分类图谱
|
||
```
|
||
文件操作系统 (7 种)
|
||
├── FileReadTool - 文件读取与类型检测
|
||
├── FileWriteTool - 原子化文件写入
|
||
├── FileEditTool - Git 风格 diff 编辑
|
||
├── MultiEditTool - 批量多文件编辑
|
||
├── lsTool - 目录结构与权限查看
|
||
├── GlobTool - Gitignore 样式的文件匹配
|
||
└── GrepTool - 正则表达式内容搜索
|
||
|
||
执行与协作系统 (5 种)
|
||
├── BashTool - 安全沙箱化的命令执行
|
||
├── TaskTool - 子任务 AI 代理 (Agent)
|
||
├── ArchitectTool - 项目架构设计助手
|
||
├── MemoryReadTool - 会话记忆读取
|
||
└── MemoryWriteTool - 结构化记忆存储
|
||
|
||
开发环境工具 (4 种)
|
||
├── NotebookReadTool - Jupyter 读取
|
||
├── NotebookEditTool - Jupyter 单元编辑
|
||
├── TodoReadTool - 任务列表读取
|
||
└── TodoWriteTool - 智能任务管理
|
||
|
||
系统集成工具 (2 种)
|
||
├── MCPTool - MCP 服务器调用
|
||
└── ThinkTool - AI 思维链可视化
|
||
```
|
||
|
||
#### 工具实现标准规范
|
||
每个工具必须实现完整的接口契约：
|
||
|
||
```typescript
|
||
interface ITool {
|
||
// 元数据
|
||
name: string;
|
||
description(): string;
|
||
prompt(env: Env): string;
|
||
|
||
// 输入验证
|
||
inputSchema: z.ZodSchema;
|
||
validateInput(input: unknown): ValidationResult;
|
||
|
||
// 核心执行
|
||
call(params: any): AsyncGenerator<ToolProgress, ToolResult, void>;
|
||
|
||
// UI 渲染
|
||
renderToolUseMessage?(): React.ReactElement;
|
||
renderToolResultMessage?(result: ToolResult): React.ReactElement;
|
||
|
||
// 安全与权限
|
||
needsPermissions?(): boolean;
|
||
isReadOnly?(): boolean;
|
||
isConcurrencySafe?(): boolean;
|
||
}
|
||
```
|
||
|
||
### 权限系统分层设计
|
||
|
||
#### 权限检查漏斗模型
|
||
1. **工具级 (Tool-level)** - 工具自身权限声明
|
||
2. **会话级 (Session-level)** - 用户信任项目设置
|
||
3. **命令级 (Command-level)** - 具体命令白名单/黑名单
|
||
4. **文件系统级 (FS-level)** - 目录访问边界检查
|
||
|
||
#### 安全检查矩阵
|
||
| 工具类型 | 权限获取 | 并发安全 | 影响范围 |
|
||
|---|---|---|---|
|
||
| 文件读取 | 目录边界检查 | ✅ | 安全 |
|
||
| 文件写入 | 差异确认 + 备份 | ⚠️ | 需审批 |
|
||
| 命令执行 | 命令白名单 + 超时 | ❌ | 高敏感 |
|
||
| 智能代理 | 信任项目判断 | ❌ | 需监控 |
|
||
|
||
---
|
||
|
||
## AI 对话工作流
|
||
|
||
### 消息处理管道
|
||
```
|
||
用户输入
|
||
↓
|
||
命令解析器 (URL/路径/命令/tag)
|
||
↓
|
||
权限检查 & 预过滤器
|
||
↓
|
||
Large Language Model 处理
|
||
↓
|
||
工具调用解析器
|
||
↓
|
||
工具执行引擎 (并发 + 进度报告)
|
||
↓
|
||
结果整合 & 上下文更新
|
||
↓
|
||
响应流式输出
|
||
```
|
||
|
||
### 工具调用生命周期管理
|
||
|
||
#### 1. 预解析阶段
|
||
```typescript
|
||
// Query.ts - 请求预处理
|
||
const parseUserMessage = (input: string) => {
|
||
if (isUrl(input)) return { type: 'url', url: input };
|
||
if (isPath(input)) return { type: 'file', path: input };
|
||
if (isCommand(input)) return { type: 'command', cmd: input };
|
||
return { type: 'prompt', text: input };
|
||
};
|
||
```
|
||
|
||
#### 2. 权限检查阶段
|
||
```typescript
|
||
// Permission system - 多层级权限检查
|
||
const checkPermissions = async (tool: ITool, params: any) => {
|
||
const checks = [
|
||
tool.needsPermissions(),
|
||
sessionConfig.trustLevel,
|
||
directoryBoundaryCheck(params),
|
||
commandWhitelist(params),
|
||
];
|
||
|
||
return combinePermissionResults(checks);
|
||
};
|
||
```
|
||
|
||
#### 3. 并发执行阶段
|
||
```typescript
|
||
// Tool execution with concurrent safety
|
||
const executeTools = async (mcpTools: McpTool[]) => {
|
||
const results = await Promise.allSettled(
|
||
mcpTools.map(tool => executeWithTimeout(tool, 30000))
|
||
);
|
||
|
||
return results.filter(r => r.status === 'fulfilled').map(r => r.value);
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 上下文智能管理系统
|
||
|
||
### 文件新鲜度监控体系
|
||
```typescript
|
||
// fileFreshness.ts - 智能上下文检测
|
||
class FileFreshnessTracker {
|
||
private fileTimestamps = new Map<string, number>();
|
||
private workspacePatterns = new Set<string>();
|
||
|
||
onFileAccess(path: string): void {
|
||
this.fileTimestamps.set(path, Date.now());
|
||
}
|
||
|
||
onFileWrite(path: string): void {
|
||
this.triggerContextRecreate(path);
|
||
}
|
||
|
||
getStaleFiles(): FileStaleInfo[] {
|
||
return this.fileTimestamps.entries()
|
||
.filter(([path, ts]) => this.isStale(path, ts))
|
||
.map(([path]) => ({ path, reason: 'modified' }));
|
||
}
|
||
}
|
||
```
|
||
|
||
### 系统提醒引擎
|
||
```typescript
|
||
// systemReminder.ts - 智能系统上下文注入
|
||
const generateSystemReminders = (context: AppContext) => {
|
||
const reminders = [];
|
||
|
||
// 检测文件变化提醒
|
||
const staleFiles = fileTracker.getStaleFiles();
|
||
if (staleFiles.length > 0) {
|
||
reminders.push(`注意：以下文件已修改 ${staleFiles.map(f => basename(f.path)).join(', ')}`);
|
||
}
|
||
|
||
// 任务状态提醒
|
||
const activeTasks = todoStorage.getTasks('in_progress');
|
||
if (activeTasks.length > 0) {
|
||
reminders.push(`正在进行中的任务: ${activeTasks[0].content}`);
|
||
}
|
||
|
||
return reminders.join('\\n');
|
||
};
|
||
```
|
||
|
||
### 记忆系统层次结构
|
||
1. **会话记忆** - 当前对话的短期记忆
|
||
2. **项目记忆** - 项目特定的长期上下文
|
||
3. **用户记忆** - 跨项目的个人偏好记忆
|
||
4. **工具记忆** - 工具执行结果的依赖链
|
||
|
||
---
|
||
|
||
## 安全与权限设计
|
||
|
||
### 多层安全架构
|
||
|
||
#### 1. 应用级安全
|
||
- **命令黑名单** - 禁止危险系统命令
|
||
- **目录沙箱** - 限制文件系统访问范围
|
||
- **自动超时** - 防止长时间阻塞操作
|
||
|
||
#### 2. 用户级安全
|
||
- **信任项目** - 一次性信任项目授权
|
||
- **命令确认** - 敏感操作二次确认
|
||
- **审计追踪** - 所有操作可追踪记录
|
||
|
||
#### 3. 网络级安全
|
||
- **请求代理** - 通过 Claude Desktop 代理网络访问
|
||
- **密钥隔离** - API 密钥与用户系统隔离
|
||
|
||
#### 权限策略表
|
||
| 操作类型 | CLI 模式权限 | MCP 模式权限 | 风险级别 |
|
||
|---|---|---|---|
|
||
| 文件读取 | 目录边界检查 | 预配置目录 | 低风险 |
|
||
| 文件写入 | 增量保存 + 备份 | 限制目录 | 中风险 |
|
||
| 命令执行 | 命令白名单 | 禁止执行 | 高敏感 |
|
||
| 网络访问 | 代理配置 | 无网络访问 | 受控 |
|
||
|
||
---
|
||
|
||
## 状态管理与数据流
|
||
|
||
### React 状态拓扑图
|
||
```
|
||
AppContext (全局上下文)
|
||
├── SessionState (会话状态)
|
||
│ ├── messages (消息流)
|
||
│ ├── tools (工具执行状态)
|
||
│ └── permissions (权限管理)
|
||
├── UserConfig (用户配置)
|
||
│ ├── model preferences (模型偏好)
|
||
│ ├── theme settings (主题设置)
|
||
│ └── trust settings (项目信任)
|
||
└── ToolState (工具运行状态)
|
||
├── execution progress (执行进度)
|
||
├── permission requests (权限请求)
|
||
└── result data (结果缓存)
|
||
```
|
||
|
||
### 数据持久化策略
|
||
- **会话日志** - JSON Lines 格式，按时间索引
|
||
- **配置文件** - JSONSchema 验证的结构化配置
|
||
- **工具缓存** - LRU 缓存，按项目访问频率管理
|
||
- **状态检查点** - 关键状态的自动备份与恢复
|
||
|
||
---
|
||
|
||
## 跨平台兼容性设计
|
||
|
||
### Node.js 运行时适配
|
||
```typescript
|
||
// platform adaptors
|
||
const platformConfig = {
|
||
win32: {
|
||
shellPath: 'cmd.exe',
|
||
pathSeparator: '\\',
|
||
tempDir: process.env.TEMP,
|
||
},
|
||
darwin: {
|
||
shellPath: '/bin/zsh',
|
||
pathSeparator: '/',
|
||
tempDir: '/tmp',
|
||
},
|
||
linux: {
|
||
shellPath: '/bin/bash',
|
||
pathSeparator: '/',
|
||
tempDir: '/tmp',
|
||
}
|
||
};
|
||
```
|
||
|
||
### 终端兼容性矩阵
|
||
| 环境 | Windows Terminal | iTerm2 | VSCode Terminal | GNOME Terminal |
|
||
|---|---|---|---|---|
|
||
| 彩色输出 | ✅ | ✅ | ✅ | ✅ |
|
||
| 鼠标支持 | ✅ | ✅ | ⚠️ | ✅ |
|
||
| 清除屏幕 | ✅ | ✅ | ✅ | ✅ |
|
||
| Unicode | ✅ | ✅ | ✅ | ✅ |
|
||
|
||
---
|
||
|
||
## 监控与调试体系
|
||
|
||
### 性能监控系统
|
||
```typescript
|
||
// Performance tracking
|
||
const metrics = {
|
||
queryResponseTime: new Histogram('query_duration_ms'),
|
||
toolExecutionTime: new Histogram('tool_duration_ms'),
|
||
apiCallCount: new Counter('api_calls_total'),
|
||
errorRate: new Counter('errors_total'),
|
||
|
||
trackQuery: async <T>(operation: () => Promise<T>) => {
|
||
const start = Date.now();
|
||
try {
|
||
const result = await operation();
|
||
metrics.queryResponseTime.observe(Date.now() - start);
|
||
return result;
|
||
} catch (error) {
|
||
metrics.errorRate.inc();
|
||
throw error;
|
||
}
|
||
}
|
||
};
|
||
```
|
||
|
||
### 故障排除诊断
|
||
- **Debug 模式** - `NODE_ENV=development pnpm run dev --verbose`
|
||
- **健康检查** - `/doctor` 命令自动诊断系统状态
|
||
- **性能分析** - 集成式性能监控与瓶颈分析
|
||
- **错误追踪** - Sentry 集成，自动错误上报
|
||
|
||
### 日志分级系统
|
||
- **FATAL** - 系统崩溃，无法恢复
|
||
- **ERROR** - 功能异常，用户可见
|
||
- **WARN** - 潜在问题，不影响功能
|
||
- **INFO** - 重要操作记录
|
||
- **DEBUG** - 开发调试信息
|
||
|
||
---
|
||
|
||
## 架构决策记录
|
||
|
||
### ADR-001: 双入口架构选择
|
||
**决策**: CLI + MCP 双模式统一架构
|
||
**权衡**: 代码复用 vs 复杂度增加
|
||
**评估**: 85% 代码复用率，工具系统完全一致
|
||
**状态**: ✅ 已证实架构成功
|
||
|
||
### ADR-002: React/Ink vs 命令行库
|
||
**决策**: React/Ink 提供组件化终端 UI
|
||
**权衡**: 学习成本 vs 可维护性
|
||
**评估**: 复杂 UI 场景显著提升可维护性
|
||
**状态**: ✅ 组件化带来清晰架构
|
||
|
||
### ADR-003: Zod 输入验证方案
|
||
**决策**: Zod 而非 TypeScript 接口用于工具输入验证
|
||
**权衡**: 运行时验证 vs 编译时检查
|
||
**评估**: 动态用户输入受益更多
|
||
**状态**: ✅ 统一验证体验优秀
|
||
|
||
---
|
||
|
||
## 未来架构演进方向
|
||
|
||
### 1. 微服务化分解
|
||
- **工具服务独立化** - 大型工具拆分为独立进程
|
||
- **模型服务抽象** - 更灵活的 AI 提供商集成
|
||
- **存储服务标准化** - 统一文件系统接口
|
||
|
||
### 2. 扩展性增强
|
||
- **插件系统** - 第三方工具集成框架
|
||
- **工作流编排** - 复杂多步骤任务自动化
|
||
- **团队协作** - 多用户会话共享能力
|
||
|
||
### 3. 性能优化
|
||
- **增量构建** - 只重构建修改的工具
|
||
- **预编译缓存** - 加速启动时间
|
||
- **并行执行** - 大规模工具并行化
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
Kode 展示了一个高度工程化的终端 AI 助手系统，其架构融合了现代前端开发的最佳实践（React/TypeScript）、传统命令行工具的稳定性、以及 AI 时代的智能集成需求。
|
||
|
||
**核心创新点**:
|
||
1. **双轨架构** - 单一代码库同时支持 CLI 和 MCP Server
|
||
2. **智能上下文** - 文件新鲜度感知和系统提醒机制
|
||
3. **可信执行** - 多层权限控制的安全沙箱
|
||
4. **工具标准化** - 18 种工具的完全一致架构体验
|
||
5. **跨平台部署** - Windows/Mac/Linux 的完整一致性
|
||
|
||
该系统为终端 AI 时代提供了模板级参考实现，特别是在安全、扩展性和用户体验的平衡上达到了优秀水平。 |