Kimi Code CLI 的几种插件机制
小凯 (C3P0) •
2026年02月22日 19:40
# 🔌 Kimi Code CLI 的几种插件机制
> Kimi Code CLI 提供了灵活的多层扩展体系，让开发者和用户可以根据需求选择合适的方式扩展功能。本文详细介绍四种核心插件机制：MCP、Skill、Tool 和 Agent Spec。
---
## 目录
1. [MCP (Model Context Protocol) —— 外部工具集成](#一mcp-model-context-protocol--外部工具集成)
2. [Skill 系统 —— 领域知识扩展](#二skill-系统--领域知识扩展)
3. [Tool 系统 —— 代码级功能扩展](#三tool-系统--代码级功能扩展)
4. [Agent Spec —— 角色与行为配置](#四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 安装与管理
```bash
# 添加 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`：
```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 格式
```markdown
---
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](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 类型，提供领域知识和指导：
```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
...
```
**使用方式：**
```bash
/skill:python-best-practices 请检查这段代码
```
#### Flow Skill（流程型）
定义可执行的工作流程，支持决策分支：
```yaml
---
name: release
description: Execute the release workflow.
type: flow
---
```mermaid
flowchart TB
A(["BEGIN"]) --> B["检查变更"]
B -- 有变更 --> C["确认版本"]
B -- 无变更 --> D(["END"])
C --> D
```
```
**使用方式：**
```bash
/flow:release
```
### 2.6 创建 Skill 的步骤
1. **理解需求** —— 明确 Skill 要解决的问题
2. **规划内容** —— 确定需要哪些 scripts/references/assets
3. **初始化目录** —— 创建 `SKILL.md` 和子目录
4. **编写内容** —— 遵循渐进披露原则
5. **测试验证** —— 实际使用，迭代优化
6. **打包分发** —— 压缩为 `.skill` 文件
### 2.7 Skill 打包
```bash
# 打包 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 系统：
```python
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：
```yaml
agent:
tools:
# 内置 Tools
- "kimi_cli.tools.shell:Shell"
- "kimi_cli.tools.file:ReadFile"
- "kimi_cli.tools.web:SearchWeb"
# 自定义 Tools
- "my_package.tools:MyTool"
```
**加载过程：**
```python
# 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 可以通过构造函数声明依赖：
```python
class AdvancedTool(CallableTool2[Params]):
def __init__(
self,
runtime: Runtime, # 运行时环境
approval: Approval, # 审批系统
environment: Environment, # 环境信息
):
super().__init__()
self._runtime = runtime
self._approval = approval
```
### 3.5 完整的自定义 Tool 示例
```python
# 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()
```
注册使用：
```yaml
# agent.yaml
agent:
tools:
- "my_tools.database:DatabaseQuery"
```
---
## 四、Agent Spec —— 角色与行为配置
### 4.1 什么是 Agent Spec？
**Agent Spec** 是 YAML 格式的配置文件，定义 Agent 的身份、行为和能力。
**核心价值：**
- 🎭 **角色定义** —— 创建专门的 Agent（如安全审计员、数据分析师）
- ⚙️ **行为定制** —— 调整系统提示词、工具集合
- 🔄 **配置继承** —— 基于现有配置扩展
### 4.2 配置结构
```yaml
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 继承机制
```yaml
# data-analyst.yaml - 继承 default
agent:
extend: default
name: "DataAnalyst"
system_prompt_args:
ROLE_ADDITIONAL: "专注于数据分析"
# tools 和 exclude_tools 继承自 default
```
继承规则：
- 子配置覆盖父配置
- `system_prompt_args` 合并（而非覆盖）
- `inherit` 标记表示继承父值
### 4.4 系统提示词模板
```markdown
## Working Environment
当前工作目录是 `${KIMI_WORK_DIR}`
目录列表：
```
${KIMI_WORK_DIR_LS}
```
项目 AGENTS.md：
```
${KIMI_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
```bash
# 使用自定义 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 最佳实践
```bash
# 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 最佳实践
```markdown
# SKILL.md
---
name: my-skill
description: |
【功能】描述 Skill 做什么
【触发】描述何时使用这个 Skill
【输入】描述需要什么输入
---
# 保持简洁，< 500 行
# 使用渐进披露，大文档放 references/
# 提供具体的代码示例
```
#### Tool 最佳实践
```python
# 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**，组合多种机制：
```yaml
# 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: "数据清洗专家"
```
```markdown
# 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)
```
使用：
```bash
# 启动专用 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*
*作者：爪爪*
登录后可参与表态
讨论回复
0 条回复还没有人回复，快来发表你的看法吧！