Kimi CLI 自定义命令实战【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli重复劳动是 CLI 里最常见的消耗。以扫一遍仓库统计各目录 Python 代码行数为例手动要拼好find加wc还得自己汇总结果。Kimi CLI 自定义命令的价值正在于此把这类重复操作写成一个可被模型直接调用的工具之后一句话就能触发。读完这篇你会拿到一个能跑的最小命令骨架、输入输出与报错的写法以及注册和联动的完整路径。示例在examples/custom-tools先把它跑起来git clone https://gitcode.com/GitHub_Trending/ki/kimi-cli cd kimi-cli/examples/custom-tools uv sync --reinstallpyproject.toml只声明了kimi-cli和kosong两个依赖并用tool.uv.sources把kimi-cli指向仓库根目录的本地源码所以必须在仓库内同步。一个自定义命令由三层组成工具层只有一个约定继承kosong.tooling.CallableTool2它是个泛型抽象类你只需填三个空位——name模型调用时用的命令名、description告诉模型什么时候该用它、params入参的 Pydantic 模型。下面这个统计指定目录下 Python 文件总行数的命令就是全部骨架from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue from pydantic import BaseModel, Field class Params(BaseModel): root: str Field(description要统计的目录路径, default.) class CountPyLines(CallableTool2): name: str CountPyLines description: str Count total lines across all .py files under a directory. params: type[Params] Params async def __call__(self, params: Params) - ToolReturnValue: ...三层各管一件事类是命令本体Params定义它吃什么__call__定义它怎么干活。官方示例里的Ls命令也是同一套结构见 custom-tools 示例适合对照着改。输入与输出怎么写入参用 Pydantic 模型声明框架负责把模型产出的 JSON 反序列化成对象。两个细节值得留意Field(description...)里写的文字就是模型看到的参数说明等于契约的一部分别写含糊。default让某个参数可以省略模型在没提及时会直接用默认值。输出不需要再声明一个输出模型。__call__的返回注解固定为ToolReturnValue实际只取两种值ToolOk(output...)表示成功并把output文本回给模型ToolError表示失败。完整实现async def __call__(self, params: Params) - ToolReturnValue: import pathlib root pathlib.Path(params.root) if not root.is_dir(): return ToolError( output, messagef{root} is not a directory, brieftarget missing, ) total 0 for py_file in sorted(root.rglob(*.py)): with open(py_file, encodingutf-8) as fh: total sum(1 for _ in fh) return ToolOk(outputf{total} lines in {len(list(root.rglob(*.py)))} .py files)注意成功路径返回ToolOk失败路径返回ToolError二者互斥这是模型区分结果和报错的唯一依据。框架还有一道保险SimpleToolset在工具入册时会检查返回注解声明不对会直接抛TypeError不用等运行期才发现写错了。把命令注册进 agent写完类只是半成品模型必须认识它才算数。注册发生在 agent spec 文件里myagent.yaml 的写法是version: 1 agent: extend: default tools: - kimi_cli.tools.file:ReadFile - kimi_cli.tools.shell:Shell - my_tools.count_py:CountPyLines三个要点。extend: default表示以默认 agent 为基底tools列表是整体替换而不是追加所以你想保留的内置工具都要列出来。每一项都是模块路径:类名的字符串冒号右边必须和类名完全一致。你的命令所在包要能被导入示例工程用uv在当前目录跑天然满足这一点。入口脚本 展示了一次性调用的完整链路main.py的核心部分session await Session.create(KaosPath.cwd()) instance await KimiCLI.create(session, agent_filemyagent) await instance.run_print( input_formattext, output_formattext, commandWhat tools do you have?, )先问你有哪些工具确认新命令出现在列表里再让它实际跑一次比如统计 examples 目录的 Python 行数两步就能验证注册是否生效。踩坑提示与下一步几个容易翻车的地方返回注解写错或缺失工具入册时就被TypeError拦下报的是Expected tool to return ToolReturnValue照着把注解补齐即可。参数描述太笼统。只写路径不写目录路径还是文件路径模型可能传错东西参数说明就是给模型看的把约束写进description。多个命令想联动别在单个工具里塞流程。把Glob、Grep和你自己的命令并列写进tools列表让模型先定位文件再调统计命令流程编排是模型的事工具只负责一步。想封装外部脚本或命令行程序走的是插件机制plugin.json声明和这里进程内的 Python 工具是两条路别混用。下一步可以试个小挑战把示例里的Ls抄一份改成按后缀统计某目录的文件数量只动Params和__call__三处注册行改成你的新类名。能跑通这套机制你就完全掌握了。扩展方向可继续看 skills 文档它和工具互补工具提供能力skills 提供规范。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考