🔌 Kimi Code CLI 的几种插件机制

Kimi Code CLI 提供了灵活的多层扩展体系，让开发者和用户可以根据需求选择合适的方式扩展功能。本文详细介绍四种核心插件机制：MCP、Skill、Tool 和 Agent Spec。

目录

1. MCP (Model Context Protocol) —— 外部工具集成
2. Skill 系统 —— 领域知识扩展
3. Tool 系统 —— 代码级功能扩展
4. Agent Spec —— 角色与行为配置
5. 选择指南与最佳实践

一、MCP (Model Context Protocol) —— 外部工具集成

1.1 什么是 MCP？

MCP 是由 Anthropic 推出的开放协议，定义了 AI 模型与外部工具通信的标准方式。Kimi Code CLI 完整支持 MCP，可以无缝集成任何兼容 MCP 的服务器。

核心优势：

• 🌐 标准化 —— 通用协议，生态丰富
• 🔌 即插即用 —— 自动发现工具，无需代码修改
• 🔒 安全可靠 —— 支持 OAuth 认证和权限控制

1.2 支持的传输方式

1.3 安装与管理

# 添加 HTTP 类型的 MCP 服务器
kimi mcp add --transport http context7 https://mcp.context7.com/mcp \
  --header "CONTEXT7_API_KEY: ctx7sk-your-key"

# 添加 stdio 类型的 MCP 服务器
kimi mcp add --transport stdio chrome-devtools -- npx chrome-devtools-mcp@latest

# 添加需要 OAuth 认证的服务器
kimi mcp add --transport http --auth oauth linear https://mcp.linear.app/mcp

# 列出所有 MCP 服务器
kimi mcp list

# 测试连接
kimi mcp test context7

# 授权（OAuth 类型）
kimi mcp auth linear

# 删除 MCP 服务器
kimi mcp remove chrome-devtools

1.4 配置文件

MCP 配置存储在 ~/.kimi/mcp.json：

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "your-key"
      }
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

1.5 工作原理

Kimi Code CLI          MCP Client          MCP Server
     │                      │                    │
     │─── 1. 列出工具 ─────▶│                    │
     │                      │─── 2. 发现工具 ────▶│
     │◀── 3. 工具列表 ──────│◀── 4. 返回工具 ────│
     │                      │                    │
     │─── 5. 调用工具 ─────▶│                    │
     │                      │─── 6. 执行操作 ────▶│
     │◀── 7. 返回结果 ──────│◀── 8. 返回结果 ────│

1.6 推荐 MCP 服务器

二、Skill 系统 —— 领域知识扩展

2.1 什么是 Skill？

Skill 是 Kimi Code CLI 的知识型插件，为 Agent 提供特定领域的专业知识、工作流程和最佳实践。

核心理念：

• 📚 知识封装 —— 将领域知识打包成可复用单元
• 🎯 按需触发 —— 通过 /skill:name 或自动触发
• 🧩 渐进披露 —— 分层加载，节省上下文空间

2.2 Skill 目录结构

skill-name/                    # Skill 目录（小写+连字符）
├── SKILL.md                   # 【必需】主文件
│   ├── YAML Frontmatter       # 元数据（name, description）
│   └── Markdown Body          # 具体内容
├── scripts/                   # 【可选】可执行脚本
│   ├── rotate_pdf.py
│   └── merge_csv.py
├── references/                # 【可选】参考文档
│   ├── schema.md
│   └── api_docs.md
└── assets/                    # 【可选】资源文件
    ├── logo.png
    └── template.docx

2.3 SKILL.md 格式

---
name: pdf-processor                      # Skill 标识符
description: |                          # 触发条件说明
  Comprehensive PDF processing including
  text extraction, form filling, and rotation.
  Use when user needs to work with PDF files.
type: standard                          # 或 flow（流程型）
---

# PDF Processing Guide

## Quick Start

Extract text from PDF:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = "\\n".join(page.extract_text() for page in pdf.pages)

Advanced Features

• Form filling: See FORMS.md
• PDF rotation: Use scripts/rotate_pdf.py

### 2.4 Skill 发现路径

Kimi Code CLI 按优先级从多个位置加载 Skill：

1. 内置 Skills (src/kimi_cli/skills/)
2. 用户级 Skills:
   • ~/.config/agents/skills/ ← 推荐
   • ~/.agents/skills/
   • ~/.kimi/skills/
   • ~/.claude/skills/ ← 兼容
   • ~/.codex/skills/ ← 兼容
3. 项目级 Skills:
   • ./.agents/skills/
   • ./.kimi/skills/

### 2.5 Skill 类型

#### Standard Skill（标准型）

最常见的 Skill 类型，提供领域知识和指导：

```yaml
---
name: python-best-practices
description: Guidelines for writing clean, Pythonic code.
---

# Python Best Practices

## Code Style
- Follow PEP 8
- Use type hints
- Prefer list comprehensions over map/filter
...

使用方式：

/skill:python-best-practices 请检查这段代码

Flow Skill（流程型）

定义可执行的工作流程，支持决策分支：

---
name: release
description: Execute the release workflow.
type: flow
---

使用方式：

/flow:release

2.6 创建 Skill 的步骤

1. 理解需求 —— 明确 Skill 要解决的问题
2. 规划内容 —— 确定需要哪些 scripts/references/assets
3. 初始化目录 —— 创建 SKILL.md 和子目录
4. 编写内容 —— 遵循渐进披露原则
5. 测试验证 —— 实际使用，迭代优化
6. 打包分发 —— 压缩为 .skill 文件

2.7 Skill 打包

# 打包 Skill
cd ~/.config/agents/skills/
zip -r my-skill.skill my-skill

# 安装 Skill（解压到 skill 目录）
unzip my-skill.skill -d ~/.config/agents/skills/

三、Tool 系统 —— 代码级功能扩展

3.1 什么是 Tool？

Tool 是 Kimi Code CLI 的功能型插件，通过编写 Python 代码实现自定义功能。

适用场景：

• 需要自定义逻辑的功能
• 与外部系统深度集成
• 性能敏感的计算任务

3.2 Tool 基类

Kimi Code CLI 使用 kosong 框架的 Tool 系统：

from pydantic import BaseModel, Field
from kosong.tooling import CallableTool2, ToolOk, ToolError, ToolReturnValue

class Params(BaseModel):
    """Tool 参数定义"""
    arg1: str = Field(description="参数说明")
    arg2: int = Field(default=10, ge=1, description="带约束的参数")

class MyTool(CallableTool2[Params]):
    """Tool 实现"""
    name: str = "MyTool"           # Tool 名称
    params: type[Params] = Params  # 参数模型
    
    def __init__(self, runtime: Runtime):
        """构造函数，支持依赖注入"""
        super().__init__(description="Tool 描述")
        self._runtime = runtime
    
    async def __call__(self, params: Params) -> ToolReturnValue:
        """Tool 逻辑"""
        try:
            result = await self.do_something(params)
            return ToolOk(output=result, message="成功消息")
        except Exception as e:
            return ToolError(message=f"错误: {e}", brief="简短错误")

3.3 Tool 加载机制

在 agent.yaml 中注册 Tool：

agent:
  tools:
    # 内置 Tools
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
    - "kimi_cli.tools.web:SearchWeb"
    # 自定义 Tools
    - "my_package.tools:MyTool"

加载过程：

# 1. 解析路径 "module.path:ClassName"
module_name, class_name = tool_path.rsplit(":", 1)

# 2. 动态导入模块
module = importlib.import_module(module_name)
tool_cls = getattr(module, class_name)

# 3. 依赖注入
# 根据 __init__ 参数类型自动注入依赖
for param in inspect.signature(tool_cls).parameters.values():
    if param.annotation in dependencies:
        args.append(dependencies[param.annotation])

# 4. 实例化
tool = tool_cls(*args)

3.4 依赖注入

Tool 可以通过构造函数声明依赖：

class AdvancedTool(CallableTool2[Params]):
    def __init__(
        self,
        runtime: Runtime,           # 运行时环境
        approval: Approval,          # 审批系统
        environment: Environment,    # 环境信息
    ):
        super().__init__()
        self._runtime = runtime
        self._approval = approval

3.5 完整的自定义 Tool 示例

# my_tools/database.py
from pathlib import Path
from typing import override
from pydantic import BaseModel, Field
from kosong.tooling import CallableTool2, ToolOk, ToolError, ToolReturnValue
from kimi_cli.soul.agent import Runtime

class QueryParams(BaseModel):
    sql: str = Field(description="SQL query to execute")
    db_path: str = Field(description="Path to SQLite database file")

class DatabaseQuery(CallableTool2[QueryParams]):
    """Execute SQL queries on a SQLite database."""
    
    name: str = "DatabaseQuery"
    params: type[QueryParams] = QueryParams
    
    def __init__(self, runtime: Runtime) -> None:
        super().__init__(
            description="Execute SQL queries on SQLite databases."
        )
        self._runtime = runtime
        self._work_dir = runtime.builtin_args.KIMI_WORK_DIR
    
    @override
    async def __call__(self, params: QueryParams) -> ToolReturnValue:
        import sqlite3
        import json
        
        try:
            # 验证路径安全
            db_path = Path(params.db_path)
            if not db_path.is_absolute():
                db_path = self._work_dir / db_path
            
            # 执行查询
            conn = sqlite3.connect(str(db_path))
            conn.row_factory = sqlite3.Row
            cursor = conn.cursor()
            cursor.execute(params.sql)
            
            # 获取结果
            if params.sql.strip().upper().startswith("SELECT"):
                rows = cursor.fetchall()
                result = [dict(row) for row in rows]
                return ToolOk(
                    output=json.dumps(result, indent=2, ensure_ascii=False),
                    message=f"Query returned {len(rows)} rows."
                )
            else:
                conn.commit()
                return ToolOk(
                    output="",
                    message=f"Query executed successfully. Rows affected: {cursor.rowcount}"
                )
                
        except sqlite3.Error as e:
            return ToolError(
                message=f"Database error: {e}",
                brief="Query failed"
            )
        finally:
            if 'conn' in locals():
                conn.close()

注册使用：

# agent.yaml
agent:
  tools:
    - "my_tools.database:DatabaseQuery"

四、Agent Spec —— 角色与行为配置

4.1 什么是 Agent Spec？

Agent Spec 是 YAML 格式的配置文件，定义 Agent 的身份、行为和能力。

核心价值：

• 🎭 角色定义 —— 创建专门的 Agent（如安全审计员、数据分析师）
• ⚙️ 行为定制 —— 调整系统提示词、工具集合
• 🔄 配置继承 —— 基于现有配置扩展

4.2 配置结构

version: 1
agent:
  name: "DataAnalyst"                    # Agent 名称
  extend: default                        # 继承基础配置
  system_prompt_path: ./system.md        # 系统提示词文件
  system_prompt_args:                    # 提示词变量
    EXPERTISE: "pandas, numpy, matplotlib"
    ROLE_ADDITIONAL: |
      You are a data analysis expert.
      Always provide data-backed insights.
  tools:                                 # 工具列表
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
  exclude_tools:                         # 排除的工具
    - "kimi_cli.tools.file:WriteFile"
  subagents:                             # 子 Agent 定义
    data-cleaner:
      path: ./sub.yaml
      description: "Specializes in data cleaning tasks."

4.3 继承机制

# data-analyst.yaml - 继承 default
agent:
  extend: default
  name: "DataAnalyst"
  system_prompt_args:
    ROLE_ADDITIONAL: "专注于数据分析"
  # tools 和 exclude_tools 继承自 default

继承规则：

• 子配置覆盖父配置
• system_prompt_args 合并（而非覆盖）
• inherit 标记表示继承父值

4.4 系统提示词模板

## Working Environment

当前工作目录是 `\({KIMI_WORK_DIR}`

目录列表：
```\){KIMI_WORK_DIR_LS}

项目 AGENTS.md：

\({KIMI_AGENTS_MD}
```\){ROLE_ADDITIONAL}

内置变量：

4.5 使用自定义 Agent

# 使用自定义 Agent
kimi --agent ./data-analyst.yaml

# 在代码中使用
kimi_cli.create(
    agent_file=Path("./data-analyst.yaml"),
    ...
)

五、选择指南与最佳实践

5.1 机制对比

5.2 选择决策树

想扩展什么？
│
├─► 外部服务/工具（如数据库、API）
│   └─► 是否有 MCP 服务器？
│       ├─► 是 → 使用 MCP
│       └─► 否 → 考虑自己开发 MCP 服务器或 Tool
│
├─► 领域知识/工作流程（如公司规范、最佳实践）
│   └─► 使用 Skill
│
├─► 自定义功能逻辑（如特定算法、复杂计算）
│   └─► 使用 Tool
│
└─► 专门的 Agent 角色（如安全审计员、代码审查员）
    └─► 使用 Agent Spec

5.3 最佳实践

MCP 最佳实践

# 1. 为 MCP 服务器使用描述性名称
kimi mcp add --transport http mycompany-api https://api.mycompany.com/mcp

# 2. 使用配置文件批量管理
# mcp.json
{
  "mcpServers": {
    "staging-api": { "url": "https://staging.api.com/mcp" },
    "prod-api": { "url": "https://prod.api.com/mcp" }
  }
}

# 3. 测试后再使用
kimi mcp test mycompany-api

Skill 最佳实践

# SKILL.md
---
name: my-skill
description: |
  【功能】描述 Skill 做什么
  【触发】描述何时使用这个 Skill
  【输入】描述需要什么输入
---

# 保持简洁，< 500 行
# 使用渐进披露，大文档放 references/
# 提供具体的代码示例

Tool 最佳实践

# 1. 完善的参数验证
class Params(BaseModel):
    path: str = Field(description="文件路径")
    timeout: int = Field(default=30, ge=1, le=300, description="超时时间")

# 2. 清晰的错误信息
return ToolError(
    message=f"详细错误: {e}",
    brief="简短提示"  # 显示给用户
)

# 3. 使用依赖注入获取 Runtime
 def __init__(self, runtime: Runtime):
     self._work_dir = runtime.builtin_args.KIMI_WORK_DIR

5.4 组合使用示例

创建一个数据分析专用 Agent，组合多种机制：

# data-analysis-agent.yaml
agent:
  name: "DataAnalysisAgent"
  extend: default
  system_prompt_path: ./data_prompt.md
  system_prompt_args:
    TOOLS: "pandas, numpy, matplotlib, seaborn"
  
  # 内置工具 + 自定义工具
  tools:
    - "kimi_cli.tools.shell:Shell"
    - "kimi_cli.tools.file:ReadFile"
    - "my_tools.data_viz:DataVisualizer"  # 自定义 Tool
  
  exclude_tools:
    - "kimi_cli.tools.file:WriteFile"  # 只读分析
  
  subagents:
    data-cleaner:
      path: ./cleaner.yaml
      description: "数据清洗专家"

# data-pipeline.skill/SKILL.md
---
name: data-pipeline
description: |
  数据管道处理流程，包括：
  1. 数据提取（支持 CSV, JSON, SQL）
  2. 数据清洗（缺失值、异常值处理）
  3. 数据转换（格式转换、特征工程）
  4. 数据加载（目标数据库/文件）
  
  Use when user needs to build ETL pipelines.
---

## Data Pipeline Guide

### Step 1: Extraction
See [EXTRACTION.md](references/EXTRACTION.md) for data source specifics.

### Step 2: Cleaning
Use `scripts/clean_data.py` for automated cleaning.

### Step 3: Transformation
Common transformations: [TRANSFORMS.md](references/TRANSFORMS.md)

### Step 4: Loading
Database loading: [LOADING.md](references/LOADING.md)

使用：

# 启动专用 Agent
kimi --agent ./data-analysis-agent.yaml

# 在 Agent 中使用 Skill
/skill:data-pipeline 帮我构建一个从 MySQL 到 CSV 的数据管道

六、总结

Kimi Code CLI 提供了四层插件机制，满足不同场景的扩展需求：

核心设计理念：

• 🔌 即插即用 —— 安装简单，自动发现
• 🧩 可组合 —— 多种机制可以叠加使用
• 🛡️ 安全可控 —— 审批机制、路径验证
• 📦 可分发 —— 支持打包分享

文章完成时间：2026-02-23 作者：爪爪