Kimi-CLI 架构分析报告

概述

本文档提供了 Kimi-CLI 代码库的深度架构分析，涵盖了目录结构、插件系统、MCP 实现、搜索和抓取、提示词系统以及工具注册机制。

文档结构

1. 目录结构分析 - 详细的目录结构说明
2. 插件/扩展系统 - 工具、技能和 MCP 架构
3. MCP 实现详解 - MCP 协议实现细节
4. 搜索和页面抓取 - Web 搜索和内容抓取实现
5. 提示词系统 - 系统提示词和技能提示词
6. 工具注册和调用 - 工具系统的核心机制

核心架构亮点

1. 多语言架构

Kimi-CLI 采用了多语言架构：

• Python (50.4%): 应用逻辑、工具实现、技能系统
• Rust (26.0%): 性能关键路径、LLM 抽象层、文件系统抽象
• TypeScript (21.9%): Web UI、ACP 协议

通过 PyO3 实现 Python-Rust 互操作。

2. 分层设计

┌─────────────────────────────────────────────────┐
│           用户界面层                 │
│  CLI / Web UI / ACP               │
├─────────────────────────────────────────────────┤
│           Soul 层                    │
│  KimiSoul / Agent Runtime          │
├─────────────────────────────────────────────────┤
│           工具层                     │
│  工具注册 / 工具调用 / MCP         │
├─────────────────────────────────────────────────┤
│           抽象层                     │
│  Kaos (文件系统) / Kosong (LLM)    │
├─────────────────────────────────────────────────┤
│           基础设施                   │
│  Rust 运行时 / 异步 I/O            │
└─────────────────────────────────────────────────┘

3. 模块化扩展

三层扩展机制：

1. 工具: 最小功能单元，通过依赖注入加载
2. 技能: 可复用能力组合，支持标准技能和 Flow 技能
3. MCP: 外部工具协议，支持 HTTP、SSE、Stdio 三种传输

4. 异步优先

全面采用异步架构：

• Python: asyncio + aiohttp
• Rust: tokio
• 跨语言: 异步桥接

5. 动态配置

• 工具运行时加载
• 技能动态发现
• MCP 服务器动态连接

关键技术栈

Python 部分

• 框架: 异步应用框架
• LLM: OpenAI 兼容接口
• Web: HTTP 客户端
• 内容提取: 网页内容提取
• 模板引擎: Jinja2
• 数据验证: Pydantic

Rust 部分

• 运行时: Tokio
• 异步桥接: Python 互操作
• 序列化: JSON 处理

TypeScript 部分

• 框架: React UI 框架
• 构建工具: 构建工具
• 协议: ACP 协议实现

核心设计模式

1. 依赖注入

工具通过类型注解自动注入依赖：

tool_deps = {
    Config: runtime.config,
    Runtime: runtime,
    Approval: runtime.approval,
}

toolset.load_tools(tools, tool_deps)

2. 工厂模式

工具通过工厂方法动态创建：

@staticmethod
def _load_tool(tool_path: str, dependencies: dict) -> Tool:
    module = importlib.import_module(module_name)
    tool_cls = getattr(module, class_name)
    return tool_cls(*dependencies)

3. 策略模式

不同的工具实现不同的执行策略：

• 本地工具: 直接调用
• MCP 工具: 通过 MCP 协议调用
• 外部工具: 通过 Wire 协议调用

4. 观察者模式

工具调用通过 Wire 协议广播到 UI：

wire.send(ToolCallRequest(...))
result = await wire.wait()

性能优化

1. 并行执行

支持并行工具调用：

# 并行调用多个文件读取
results = await asyncio.gather([
    ReadFile("file1.txt"),
    ReadFile("file2.txt"),
    ReadFile("file3.txt"),
])

2. 后台加载

MCP 工具在后台异步加载：

if in_background:
    self._mcp_loading_task = asyncio.create_task(_connect())

3. 结果缓存

服务模式的结果由服务端缓存。

安全机制

1. 批准系统

所有工具调用都需要用户批准：

if not await approval.request(tool_name, description):
    return ToolRejectedError()

2. 路径验证

文件操作限制在工作目录内：

def _normalize_path(path: str) -> str:
    cwd = str(KaosPath.cwd().canonical())
    if path.startswith(cwd):
        path = path[len(cwd):].lstrip("/\\")
    return path

3. OAuth 认证

MCP 服务器支持 OAuth 认证：

if not await _check_oauth_tokens(server_url):
    server_info.status = "unauthorized"

可扩展性

1. 自定义工具

开发者可以轻松添加自定义工具：

class MyTool(CallableTool2[Params]):
    name: str = "MyTool"
    async def __call__(self, params: Params) -> ToolReturnValue:
        return ToolOk(output=[TextPart(text="执行成功")])

2. 自定义技能

创建技能目录和 SKILL.md：

~/.config/agents/skills/my-skill/SKILL.md

3. 自定义 MCP 服务器

实现 MCP 协议的服务器可以无缝集成。

关键代码位置

Python 核心代码

Rust 核心代码

TypeScript 核心代码

配置文件

Agent 配置

# src/kimi_cli/agents/default/agent.yaml
version: 1
agent:
  name: "Kimi Code CLI"
  system_prompt_path: ./system.md
  tools:
    - "kimi_cli.tools.file:ReadFile"
    - "kimi_cli.tools.web:SearchWeb"
  subagents:
    coder:
      path: ./sub.yaml
      description: "Software engineering specialist"

用户配置

# ~/.kimi/config.toml
default_model = "kimi-for-coding"

[providers.kimi-for-coding]
type = "kimi"
base_url = "https://api.kimi.com/coding/v1"
api_key = "sk-xxx"

[loop_control]
max_steps_per_turn = 100
max_retries_per_step = 3

[services.moonshot_search]
base_url = "https://api.kimi.com/coding/v1/search"
api_key = "sk-xxx"

[mcp.client]
tool_call_timeout_ms = 60000

测试架构

单元测试

# Python 测试
make test-kimi-cli

# Rust 测试
make test-kosong
make test-pykaos

端到端测试

# E2E 测试
pytest tests_e2e/

AI 测试

# AI 辅助测试
python tests_ai/scripts/run.py

开发工作流

1. 准备环境

git clone https://github.com/MoonshotAI/kimi-cli.git
cd kimi-cli
make prepare

2. 运行开发版本

uv run kimi

3. 代码检查

make format    # 格式化代码
make check     # 运行 linting 和类型检查
make test      # 运行测试

4. 构建

make build        # 构建 Python 包
make build-web    # 构建 Web UI
make build-bin    # 构建独立二进制文件

集成点

1. IDE 集成

通过 ACP 协议集成到 IDE：

{
  "agent_servers": {
    "Kimi Code CLI": {
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

2. Shell 集成

通过 Zsh 插件集成：

git clone https://github.com/MoonshotAI/zsh-kimi-cli.git \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/kimi-cli

3. VS Code 集成

通过 Kimi Code VS Code Extension 集成。

总结

Kimi-CLI 是一个设计精良的 AI 代理系统，具有以下特点：

1. 模块化架构: 清晰的分层设计，易于扩展
2. 多语言实现: Python、Rust、TypeScript 各展所长
3. 异步优先: 全面采用异步编程模型
4. 动态配置: 运行时加载工具和技能
5. 开放协议: 支持 MCP 和 ACP 等开放协议
6. 安全考虑: 批准机制、路径验证、OAuth 认证
7. 性能优化: 并行执行、后台加载、结果缓存

这些设计使 Kimi-CLI 成为一个强大、灵活、安全的 AI 命令行工具。

参考资料

• Kimi-CLI GitHub 仓库
• Kimi-CLI 文档
• MCP 协议
• ACP 协议