Kimi-CLI 架构深度分析

分析概览

本文档集提供了对 Moonshot AI 的 Kimi-CLI 项目进行的深度架构分析。Kimi-CLI 是一个多语言、模块化的 AI 代理系统，能够在终端中帮助用户完成软件开发任务和终端操作。

文档目录

1. 目录结构分析

详细分析了 Kimi-CLI 的完整目录结构

关键内容:

• 总体架构概览
• Python 核心模块 (src/kimi_cli/)
• Rust 核心模块 (rust/)
• Python 包 (packages/)
• Web UI (web/)
• 关键设计模式
• 分层架构详解

重要发现:

• 采用 Python (50.4%)、Rust (26.0%)、TypeScript (21.9%) 多语言架构
• 清晰的分层设计：Soul 层、Agent 层、Tool 层、Kaos 层、Kosong 层
• 完整的模块化设计，支持动态加载和扩展

2. 插件/扩展系统架构

深入分析了 Kimi-CLI 的三层扩展机制

关键内容:

• 工具系统定义和实现
• 工具加载机制和依赖注入
• 技能系统（标准技能和 Flow 技能）
• MCP (Model Context Protocol) 工具集成
• 扩展性设计和自定义扩展方法

重要发现:

• 工具是最小功能单元，通过 CallableTool2 基类实现
• 依赖注入系统自动注入运行时依赖
• 技能分为标准技能和基于流程图的 Flow 技能
• MCP 工具作为外部工具协议无缝集成
• 支持自定义工具、技能和 MCP 服务器

关键代码片段:

# 工具定义
class SearchWeb(CallableTool2[Params]):
    name: str = "SearchWeb"
    description: str = "搜索互联网获取最新信息"
    
    async def __call__(self, params: Params) -> ToolReturnValue:
        # 实现逻辑
        pass

# 依赖注入
tool_deps = {
    Config: runtime.config,
    Runtime: runtime,
    Approval: runtime.approval,
}
toolset.load_tools(tools, tool_deps)

3. MCP 工具实现详解

全面分析了 MCP (Model Context Protocol) 的实现细节

关键内容:

• MCP 架构和核心组件
• MCP 工具加载流程
• MCP 工具调用机制
• 三种 MCP 服务器类型（HTTP、SSE、Stdio）
• OAuth 认证集成
• MCP 配置和管理
• 错误处理和性能优化

重要发现:

• Kimi-CLI 完整实现了 MCP 客户端功能
• 支持三种传输协议：HTTP、SSE、Stdio
• MCP 工具与内置工具统一管理在 KimiToolset 中
• 支持 OAuth 认证，提供细粒度权限控制
• MCP 工具调用需要用户批准，确保安全性

关键代码片段:

# MCP 工具包装
class MCPTool(CallableTool):
    def __init__(self, server_name: str, mcp_tool: mcp.Tool, client, *, runtime: Runtime):
        super().__init__(
            name=mcp_tool.name,
            description=f"This is an MCP tool from MCP server `{server_name}`",
            parameters=mcp_tool.inputSchema,
        )
        self._client = client
    
    async def __call__(self, **kwargs) -> ToolReturnValue:
        # 请求批准
        if not await self._runtime.approval.request(self.name, description):
            return ToolRejectedError()
        
        # 调用 MCP 工具
        async with self._client as client:
            result = await client.call_tool(
                self._mcp_tool.name,
                kwargs,
                timeout=self._timeout,
            )
            return convert_mcp_tool_result(result)

4. 搜索和页面内容抓取

详细分析了 Web 搜索和内容抓取的实现

关键内容:

• SearchWeb 工具的实现
• FetchURL 工具的双模式架构（服务模式 + 本地模式）
• API 调用和响应处理
• 内容提取（使用 trafilatura）
• 配置和 OAuth 集成
• 错误处理和性能优化

重要发现:

• SearchWeb 和 FetchURL 都支持服务模式和本地模式
• 服务模式通过 Moonshot API 获取优化后的结果
• 本地模式使用 aiohttp + trafilatura 进行 HTTP 请求和内容提取
• 服务失败时自动回退到本地模式
• 支持 OAuth 认证和自定义 HTTP 头

关键代码片段:

# SearchWeb 工具
class SearchWeb(CallableTool2[Params]):
    async def __call__(self, params: Params) -> ToolReturnValue:
        # 调用搜索 API
        async with session.post(
            self._base_url,
            headers={
                "Authorization": f"Bearer {api_key}",
                "X-Msh-Tool-Call-Id": tool_call.id,
            },
            json={
                "text_query": params.query,
                "limit": params.limit,
                "enable_page_crawling": params.include_content,
            }
        ) as response:
            results = Response(**await response.json()).search_results
            
        # 格式化输出
        for result in results:
            builder.write(
                f"Title: {result.title}\n"
                f"URL: {result.url}\n"
                f"Summary: {result.snippet}\n\n"
            )

# FetchURL 双模式
async def __call__(self, params: Params) -> ToolReturnValue:
    if self._service_config:
        ret = await self._fetch_with_service(params)
        if not ret.is_error:
            return ret
        # 回退到本地模式
    return await self.fetch_with_http_get(params)

5. 提示词系统

深入分析了提示词的定义位置和组织方式

关键内容:

• 系统提示词的定义和结构
• Jinja2 模板引擎的使用
• 内置提示词参数
• 技能提示词的组织
• 子 Agent 提示词
• 提示词动态渲染机制
• 上下文压缩提示词

重要发现:

• 系统提示词使用 Jinja2 模板语法，支持动态变量替换
• 内置参数包括：KIMI_NOW、KIMI_WORK_DIR、KIMI_WORK_DIR_LS、KIMI_AGENTS_MD、KIMI_SKILLS
• 技能信息动态注入到系统提示词中
• 支持子 Agent，每个子 Agent 有自己的提示词
• 提示词按功能分段，清晰易维护

关键代码片段:

# 提示词模板渲染
def _load_system_prompt(
    path: Path, 
    args: dict[str, str], 
    builtin_args: BuiltinSystemPromptArgs
) -> str:
    system_prompt = path.read_text(encoding="utf-8").strip()
    
    # 创建 Jinja2 环境
    env = JinjaEnvironment(
        variable_start_string="${",
        variable_end_string="}",
        undefined=StrictUndefined,
    )
    
    template = env.from_string(system_prompt)
    # 合并内置参数和规范参数
    return template.render(asdict(builtin_args), **args)

# 内置参数
@dataclass
class BuiltinSystemPromptArgs:
    KIMI_NOW: str
    KIMI_WORK_DIR: KaosPath
    KIMI_WORK_DIR_LS: str
    KIMI_AGENTS_MD: str
    KIMI_SKILLS: str

6. 工具注册和调用机制

全面分析了工具的注册、发现和调用机制

关键内容:

• 工具定义和基类
• 工具注册机制
• 依赖注入系统
• 工具调用流程（Kosong Step 函数）
• Toolset Handle 方法
• 工具执行和结果处理
• 特殊工具（SkipThisTool、外部工具）
• 工具链和工具流控制
• 工具监控和调试

重要发现:

• 工具通过路径字符串（module.path:ClassName）加载
• 依赖注入通过类型注解自动实现
• 工具调用分为同步和异步两种
• 支持并行工具调用，提高效率
• 所有工具调用都需要用户批准
• 通过 Wire 协议支持外部工具

关键代码片段:

# 工具加载
def _load_tool(tool_path: str, dependencies: dict) -> Tool:
    module_name, class_name = tool_path.rsplit(":", 1)
    module = importlib.import_module(module_name)
    tool_cls = getattr(module, class_name)
    
    # 依赖注入
    args = []
    for param in inspect.signature(tool_cls).parameters.values():
        if param.kind == inspect.Parameter.KEYWORD_ONLY:
            break
        if param.annotation not in dependencies:
            raise ValueError(f"Tool dependency not found: {param.annotation}")
        args.append(dependencies[param.annotation])
    
    return tool_cls(*args)

# 工具调用处理
def handle(self, tool_call: ToolCall) -> HandleResult:
    tool = self._tool_dict[tool_call.function.name]
    arguments = json.loads(tool_call.function.arguments or "{}")
    
    async def _call():
        ret = await tool.call(arguments)
        return ToolResult(tool_call_id=tool_call.id, return_value=ret)
    
    return asyncio.create_task(_call())

核心架构亮点

1. 多语言架构

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

2. 分层设计

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

3. 模块化扩展

• 工具: 最小功能单元，依赖注入加载
• 技能: 可复用能力组合（标准技能 + Flow 技能）
• MCP: 外部工具协议（HTTP/SSE/Stdio）

4. 异步优先

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

5. 动态配置

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

6. 安全机制

• 批准系统（用户确认）
• 路径验证（限制工作目录）
• OAuth 认证（细粒度权限）

关键技术栈

Python 部分

• 异步: asyncio + aiohttp
• LLM: kosong (OpenAI 兼容)
• Web: SearchWeb / FetchURL
• 内容提取: trafilatura
• 模板引擎: Jinja2
• 数据验证: Pydantic

Rust 部分

• 运行时: tokio
• 异步桥接: PyO3
• 序列化: serde_json

TypeScript 部分

• UI: React + Vite
• 协议: ACP 实现

配置文件位置

关键文件路径总结

扩展开发指南

添加自定义工具

1. 创建工具类，继承 CallableTool2
2. 定义参数模型（Pydantic BaseModel）
3. 实现 __call__ 异步方法
4. 在 agent.yaml 中注册

添加自定义技能

1. 创建技能目录和 SKILL.md
2. 编写技能说明
3. 放到 ~/.config/agents/skills/ 或项目 .agents/skills/

添加 MCP 服务器

1. 实现 MCP 协议
2. 使用 kimi mcp add 添加
3. 配置认证（如果需要）

总结

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

✅ 模块化架构: 清晰的分层设计，易于扩展和维护 ✅ 多语言实现: Python、Rust、TypeScript 各展所长 ✅ 异步优先: 全面采用异步编程模型，性能优异 ✅ 动态配置: 运行时加载工具和技能，灵活性强 ✅ 开放协议: 支持 MCP 和 ACP 等开放协议 ✅ 安全考虑: 批准机制、路径验证、OAuth 认证 ✅ 性能优化: 并行执行、后台加载、结果缓存 ✅ 用户友好: 清晰的错误提示、详细的配置说明

这些设计使 Kimi-CLI 成为一个强大、灵活、安全的 AI 命令行工具，能够帮助开发者高效完成软件开发任务。

参考资料

• Kimi-CLI GitHub 仓库
• Kimi-CLI 官方文档
• MCP 协议规范
• ACP 协议规范

分析完成日期: 2026-02-06
Kimi-CLI 版本: 1.3
分析深度: Very Thorough