Kimi CLI自定义工具开发指南：打造专属AI命令行助手

在日常开发工作中，我们经常需要处理各种重复且繁琐的系统管理任务。当面对"如何让AI代理帮我监控系统进程并自动处理异常"这样的需求时，通用工具往往难以完美适配个性化工作流。Kimi CLI提供的自定义工具机制，正是解决这类问题的理想方案。本文将通过"需求场景→解决方案→实践验证"的三段式框架，带你从零开始构建一个实用的进程管理工具，展示如何将Kimi CLI打造成真正贴合个人工作习惯的AI助手。

需求场景：系统进程管理的痛点分析

场景化需求分析

作为开发者或系统管理员，你是否经常遇到这些问题：需要定期检查特定服务是否正常运行、当进程占用资源过高时希望及时得到提醒、或者在进程意外终止时能自动重启？传统的解决方案要么依赖复杂的shell脚本，要么需要配置专门的监控服务，这两种方式都不够灵活且学习成本较高。

想象这样一个典型工作场景：你需要监控多个应用服务的运行状态，当某个服务的CPU占用持续超过80%时发出警告，并在服务崩溃时自动重启。使用常规方法，你可能需要编写多个脚本并配置定时任务，维护成本很高。而通过Kimi CLI的自定义工具功能，你可以将这些功能集成到AI对话中，只需一句自然语言指令就能完成复杂的系统监控任务。

核心需求提炼

从上述场景中，我们可以提炼出三个核心需求：

1. 进程状态查询：能够查看指定进程的运行状态、资源占用等信息
2. 异常监控：当进程出现异常（如CPU/内存占用过高）时发出提醒
3. 自动恢复：在进程意外终止时自动重启服务

这些需求共同构成了一个完整的进程管理工作流，通过Kimi CLI的自定义工具功能，我们可以将这些功能无缝集成到AI助手的能力体系中。

解决方案：构建进程管理自定义工具

模块化实现方案

Kimi CLI的自定义工具采用模块化设计，主要包含三个核心部分：工具实现代码、元数据配置和代理注册。这种设计的优势在于：保持代码结构清晰、便于维护和扩展，同时使AI能够理解工具的功能和使用方式。

💡 为什么这样设计？ 模块化架构允许工具开发者专注于功能实现，而无需关心AI交互的细节。AI通过解析工具元数据就能理解如何调用工具，这种解耦设计大大降低了开发门槛。

1. 创建工具实现文件

首先，在my_tools目录下创建process_manager.py文件，实现进程管理功能。我们将使用Python的psutil库来获取系统进程信息，这是一个跨平台的进程管理库，能够轻松获取进程ID、名称、CPU占用率等信息。

from typing import List, Optional
from pydantic import BaseModel, Field
from kimi_cli.tools import BaseTool, tool

# 输入模型：定义工具需要的参数
class ProcessMonitorInput(BaseModel):
    process_name: str = Field(description="进程名称或关键词")
    cpu_threshold: Optional[float] = Field(
        default=80.0, 
        description="CPU占用率阈值(%)，超过此值将触发警告"
    )

# 输出模型：定义工具返回的数据结构
class ProcessInfo(BaseModel):
    pid: int = Field(description="进程ID")
    name: str = Field(description="进程名称")
    cpu_percent: float = Field(description="CPU占用率(%)")
    memory_percent: float = Field(description="内存占用率(%)")
    status: str = Field(description="进程状态(running/sleeping等)")

class ProcessMonitorOutput(BaseModel):
    processes: List[ProcessInfo] = Field(description="匹配的进程列表")
    alert: Optional[str] = Field(default=None, description="异常警告信息")

@tool(
    "进程监控工具", 
    input_model=ProcessMonitorInput, 
    output_model=ProcessMonitorOutput,
    require_approval=True,  # 执行前需要用户确认
    description="监控指定进程的运行状态，当CPU占用超过阈值时发出警告"
)
def process_monitor_tool(process_name: str, cpu_threshold: float = 80.0) -> ProcessMonitorOutput:
    """监控指定进程的运行状态并检查资源占用情况"""
    import psutil
    
    # 查找匹配的进程
    matched_processes = []
    for proc in psutil.process_iter(['pid', 'name', 'cpu_percent', 'memory_percent', 'status']):
        try:
            # 进程名称包含关键词则匹配
            if process_name.lower() in proc.info['name'].lower():
                matched_processes.append(proc.info)
        except (psutil.NoSuchProcess, psutil.AccessDenied):
            continue
    
    # 格式化进程信息
    processes = [
        ProcessInfo(
            pid=p['pid'],
            name=p['name'],
            cpu_percent=p['cpu_percent'],
            memory_percent=p['memory_percent'],
            status=p['status']
        ) for p in matched_processes
    ]
    
    # 检查是否有进程CPU占用过高
    alert = None
    high_cpu_processes = [p for p in processes if p.cpu_percent > cpu_threshold]
    if high_cpu_processes:
        alert = f"警告：以下进程CPU占用超过{cpu_threshold}%: {[p.name for p in high_cpu_processes]}"
    
    return ProcessMonitorOutput(processes=processes, alert=alert)

2. 配置工具元数据

在工具包的__init__.py中声明工具入口，让Kimi CLI能够发现并加载这个工具：

# my_tools/__init__.py
from .process_manager import process_monitor_tool

# 工具列表，供代理配置使用
__all__ = ["process_monitor_tool"]

3. 注册工具到代理配置

修改myagent.yaml文件（一种人类可读的数据序列化格式），将自定义工具添加到代理的工具列表中：

version: 1
agent:
  extend: default  # 继承默认代理配置
  tools:
    - "kimi_cli.tools.file:ReadFile"  # 保留默认文件读取工具
    - "my_tools.process_manager:process_monitor_tool"  # 添加自定义进程监控工具
  system_prompt: |
    你是一个系统管理助手，擅长使用进程监控工具帮助用户管理系统进程。
    当用户询问进程相关问题时，自动调用process_monitor_tool获取实时信息。

工具工作流程解析

下面的流程图展示了自定义工具从调用到返回结果的完整流程：

graph TD
    A[用户输入] --> B{AI判断是否需要工具}
    B -->|是| C[调用自定义工具]
    C --> D[工具执行系统查询]
    D --> E[返回结构化结果]
    E --> F[AI解析结果并生成回答]
    F --> G[展示给用户]
    B -->|否| F

这个流程体现了Kimi CLI的核心设计思想：AI负责理解用户意图和生成自然语言回答，而具体的系统操作则由自定义工具完成。这种分工使得AI能够专注于理解和决策，而工具则专注于执行特定任务，两者配合实现强大的功能。

常见问题排查

在开发自定义工具过程中，你可能会遇到以下问题：

1. 工具无法被Kimi CLI识别

   • 检查__init__.py是否正确导出了工具函数
   • 确认myagent.yaml中的工具路径是否正确，格式应为"模块路径:工具名称"
   • 运行uv run main.py --debug查看加载过程日志

2. 工具执行时报错

   • 检查是否安装了所有依赖库（如本示例中的psutil）
   • 确认工具函数的参数与输入模型定义一致
   • 使用try-except捕获可能的异常并返回友好提示

3. AI没有自动调用工具

   • 检查system_prompt是否包含了工具使用的指引
   • 在提问时明确提及相关工具，如"使用进程监控工具检查nginx状态"
   • 确保工具的description字段清晰描述了其功能

实践验证：从开发到部署的完整流程

渐进式验证流程

1. 环境准备

首先，克隆项目仓库并安装必要的依赖：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/ki/kimi-cli
cd kimi-cli/examples/custom-tools

# 安装项目依赖
uv sync --reinstall

# 安装进程管理工具所需的psutil库
uv add psutil

预期输出：

Resolving dependencies...
Downloaded 12 packages in 2.3s
Installed 15 packages.

2. 代码实现与配置

按照前面介绍的步骤，创建my_tools/process_manager.py、配置my_tools/__init__.py并修改myagent.yaml。

3. 本地测试

使用项目提供的测试框架验证工具功能：

# 运行示例工具
uv run main.py

启动后，你将看到Kimi CLI的欢迎界面，提示模型未设置：

输入/setup命令配置AI模型，按照提示选择合适的API平台并完成认证。

配置完成后，你可以直接在对话中使用自然语言调用自定义工具：

请帮我监控nginx进程的运行状态

Kimi CLI将自动调用我们开发的进程监控工具，并返回类似以下的结果：

已找到2个匹配的nginx进程：
1. PID: 1234, 名称: nginx, CPU: 2.3%, 内存: 1.5%, 状态: running
2. PID: 1235, 名称: nginx, CPU: 1.8%, 内存: 1.2%, 状态: running

所有进程CPU占用均低于阈值(80.0%)，系统运行正常。

4. 交互演示

下面的动态图展示了在Kimi CLI中使用自定义进程监控工具的完整交互过程：

在实际使用中，你可以进一步扩展工具功能，如添加进程终止、重启等操作，或者设置定时监控任务。

自定义工具与传统脚本的对比

特性	自定义工具	传统Shell脚本
调用方式	自然语言交互	命令行输入
参数处理	自动类型校验	手动解析
结果展示	AI格式化自然语言	原始文本输出
与AI集成	无缝集成	需要额外配置
权限控制	内置审批机制	需要手动实现
跨平台性	基于Python，跨平台	依赖特定shell环境

扩展学习资源

1. 官方开发文档：docs/zh/customization/skills.md
2. 工具开发示例库：examples/custom-tools/
3. API参考手册：src/kimi_cli/tools/

定制化思路：扩展你的AI助手能力

一旦掌握了自定义工具的开发方法，你可以根据自己的工作需求，进一步扩展Kimi CLI的能力：

1. 服务健康检查工具：扩展进程监控功能，添加HTTP接口检查、数据库连接测试等功能，构建完整的服务健康监控体系。

2. 代码质量分析工具：集成静态代码分析工具（如flake8、pylint），让AI能够在对话中直接分析代码质量问题并提供修复建议。

3. 云资源管理工具：对接云服务提供商API（如AWS、阿里云），实现云资源的查询、创建和管理，通过自然语言指令控制云基础设施。

通过这些定制化扩展，Kimi CLI将不仅仅是一个通用的AI助手，而成为真正贴合你工作流的个性化工具平台。无论是系统管理、开发辅助还是数据分析，自定义工具都能让AI代理更好地理解和满足你的专业需求。

希望本文能够帮助你开启Kimi CLI自定义工具的开发之旅。记住，最好的AI助手不是最强大的，而是最懂你的那一个。通过不断定制和优化，让Kimi CLI成为你工作中不可或缺的得力助手。