🔌 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 支持的传输方式
| 传输方式 | 适用场景 | 示例 |
|---|---|---|
| stdio | 本地命令行工具 | npx chrome-devtools-mcp |
| HTTP | 远程服务 | Context7、Linear API |
| Streamable HTTP | 实时流服务 | 需要持续连接的 AI 服务 |
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 服务器
| 名称 | 功能 | 安装命令 |
|---|---|---|
| context7 | 文档查询 | kimi mcp add --transport http context7 https://mcp.context7.com/mcp -H "CONTEXT7_API_KEY:xxx" |
| chrome-devtools | 浏览器控制 | kimi mcp add --transport stdio chrome-devtools -- npx chrome-devtools-mcp@latest |
| linear | 项目管理 | kimi mcp add --transport http --auth oauth linear https://mcp.linear.app/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:
## Advanced Features
- **Form filling**: See [FORMS.md](references/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 类型，提供领域知识和指导：
---
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}`
目录列表：
项目 AGENTS.md：
${ROLE_ADDITIONAL}
内置变量：
| 变量 | 说明 |
|---|---|
${KIMI_NOW} | 当前时间 |
${KIMI_WORK_DIR} | 工作目录 |
${KIMI_WORK_DIR_LS} | 目录列表 |
${KIMI_AGENTS_MD} | AGENTS.md 内容 |
${KIMI_SKILLS} | 可用 Skills |
${ROLE_ADDITIONAL} | 额外角色说明 |
4.5 使用自定义 Agent
# 使用自定义 Agent
kimi --agent ./data-analyst.yaml
# 在代码中使用
kimi_cli.create(
agent_file=Path("./data-analyst.yaml"),
...
)
---
五、选择指南与最佳实践
5.1 机制对比
| 维度 | MCP | Skill | Tool | Agent Spec |
|---|---|---|---|---|
| 类型 | 外部工具 | 知识/流程 | 代码功能 | 角色配置 |
| 难度 | ⭐ 简单 | ⭐⭐ 中等 | ⭐⭐⭐ 复杂 | ⭐⭐ 中等 |
| 生态 | 丰富 | 自定义 | 自定义 | - |
| 复用性 | 高 | 中 | 低 | 中 |
| 运行时 | 独立进程 | 提示词 | 同进程 | 配置加载 |
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 提供了四层插件机制，满足不同场景的扩展需求：
| 机制 | 一句话概括 | 入门推荐度 |
|---|---|---|
| MCP | 集成外部工具服务 | ⭐⭐⭐⭐⭐ |
| Skill | 添加领域知识流程 | ⭐⭐⭐⭐⭐ |
| Tool | 开发自定义功能 | ⭐⭐⭐ |
| Agent Spec | 定义专用 Agent | ⭐⭐⭐⭐ |
- 🔌 即插即用 —— 安装简单，自动发现
- 🧩 可组合 —— 多种机制可以叠加使用
- 🛡️ 安全可控 —— 审批机制、路径验证
- 📦 可分发 —— 支持打包分享
*文章完成时间：2026-02-23* *作者：爪爪*