Kimi CLI 中的 Kimi SDK基于 Kosong 的轻量级 Python Agent 开发套件【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cliKimi SDK仓库路径 sdks/kimi-sdk是 Kimi CLI 项目推出的轻量级 Python SDK为开发者提供访问 Kimi API 并构建 Agent 工作流的一站式入口。本文围绕设计文档 KLIP-7: Kimi SDK (thin wrapper around Kosong) 展开讲解其包结构、公开 API、依赖与版本策略、测试与 CI 设计并结合仓库源码说明generate/step、消息内容分片、工具调用等底层实现原理帮助你快速上手基于 Kimi 的 Agent 开发。背景与设计目标KLIP-7 记录了 kimi-sdk 的设计决策作为 Kosong 之上的一层薄封装thin wrapper在保持低风险、快速交付的前提下提供一个 OpenAI-SDK 风格的统一入口from kimi_sdk import Kimi, generate, step, Message设计目标明确为仅保留 Kimi 能力只导出 Kosong 的 Kimi provider 与 Agent 原语不暴露其他 provider含kosong.contrib零行为改动v1 采用纯 re-export 实现不引入新的 HTTP 层不改变 Kimi 请求/响应语义扁平模块所有公开 API 都位于包顶层kimi_sdk不划分kimi_sdk.*子模块导出完整内容分片支持 Kimi chat provider 的全部内容分片content parts与展示块display blocks。该设计同时明确了非目标不对 Kosong 做拆分或重构文档发布推迟到 v1 之后。这意味着 v1 阶段的 kimi-sdk 更像一个能力子集 统一入口而非独立的实现体系。包结构扁平模块设计根据 KLIP-7 的规划sdks/kimi-sdk的目录结构如下与仓库现状一致sdks/kimi-sdk/ pyproject.toml README.md CHANGELOG.md LICENSE / NOTICE src/kimi_sdk/ __init__.py py.typed模块职责划分kimi_sdk.__init__re-export 全部公开面Kimi、KimiStreamedMessage、generate、step、GenerateResult、Message、SimpleToolset、工具类型、provider 异常、内容分片、展示块并通过显式__all__按类别分组保持面向 Kimi 的清晰界面模块 docstring 内置了一个最小 Agent 循环示例py.typed标记包支持 PEP 561 类型标注配合项目中的 pyright strict 检查。在仓库源码 sdks/kimi-sdk/src/kimi_sdk/init.py 中可以看到所有符号均来自kosong及其子模块的导入例如from kosong.chat_provider.kimi import Kimi, KimiFiles, KimiStreamedMessage、from kosong.tooling.simple import SimpleToolset整个包没有一行业务实现——这正印证了薄封装的定位SDK 的稳定性完全由下游 Kosong 保障。公开 API 全景KLIP-7 规划并在init.py 中实现的__all__按六类组织分类导出的符号providersKimi、KimiFiles、KimiStreamedMessage、StreamedMessagePart、ThinkingEffortprovider errorsAPIConnectionError、APIEmptyResponseError、APIStatusError、APITimeoutError、ChatProviderErrormessages content partsMessage、Role、ContentPart、TextPart、ThinkPart、ImageURLPart、AudioURLPart、VideoURLPart、ToolCall、ToolCallParttoolingTool、CallableTool、CallableTool2、Toolset、SimpleToolset、ToolReturnValue、ToolOk、ToolError、ToolResult、ToolResultFuturedisplay blocksDisplayBlock、BriefDisplayBlock、UnknownDisplayBlockgenerationgenerate、step、GenerateResult、StepResult、TokenUsage其中KimiFiles与VideoURLPart是 0.2.0 版本见 CHANGELOG新增的视频上传能力比 KLIP-7 最初的导出清单更完整体现了 SDK 随版本迭代持续扩展的实践。快速上手安装与第一个对话环境要求与安装Kimi SDK 要求 Python 3.12 或更高版本见 pyproject.toml推荐使用 uv 作为包管理器uv init --python 3.12 # or higher uv add kimi-sdk简单对话补全import asyncio from kimi_sdk import Kimi, Message, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) history [ Message(roleuser, contentWho are you?), ] result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, ) print(result.message) print(result.usage) asyncio.run(main())generate返回的GenerateResult包含message合并完成后的完整Message与usageTokenUsage当 API 返回空响应时抛出APIEmptyResponseError见下文底层原理。流式输出通过on_message_part回调逐片接收流式内容适合实时展示场景import asyncio from kimi_sdk import Kimi, Message, StreamedMessagePart, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) history [ Message(roleuser, contentWho are you?), ] def output(message_part: StreamedMessagePart) - None: print(message_part) result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, on_message_partoutput, ) print(result.message) print(result.usage) asyncio.run(main())视频上传KimiFiles 的多模态能力Kimi SDK 通过Kimi.files暴露文件能力。KimiFiles.upload_video将视频上传到 Kimi files API 并返回一个VideoURLPart内容分片可直接嵌入消息import asyncio from pathlib import Path from kimi_sdk import Kimi, Message, TextPart, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) video_path Path(demo.mp4) video_part await kimi.files.upload_video( datavideo_path.read_bytes(), mime_typevideo/mp4, ) history [ Message( roleuser, content[ TextPart(textPlease describe this video.), video_part, ], ), ] result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, ) print(result.message) print(result.usage) asyncio.run(main())在底层实现 packages/kosong/src/kosong/chat_provider/kimi.py 中upload_video会校验 MIME 类型必须以video/开头否则抛出ChatProviderError随后以purposevideo调用/files接口并将返回的ms://file_idURL 封装为VideoURLPart供模型引用。工具调用用 step 构建单步 Agent 循环step在generate之上叠加了工具调度能力。以下示例定义了一个两整数相加的工具并通过SimpleToolset注册import asyncio from pydantic import BaseModel from kimi_sdk import CallableTool2, Kimi, Message, SimpleToolset, StepResult, ToolOk, ToolReturnValue, step class AddToolParams(BaseModel): a: int b: int class AddTool(CallableTool2[AddToolParams]): name: str add description: str Add two integers. params: type[AddToolParams] AddToolParams async def __call__(self, params: AddToolParams) - ToolReturnValue: return ToolOk(outputstr(params.a params.b)) async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) toolset SimpleToolset() toolset AddTool() history [ Message(roleuser, contentPlease add 2 and 3 with the add tool.), ] result: StepResult await step( chat_providerkimi, system_promptYou are a precise math tutor., toolsettoolset, historyhistory, ) print(result.message) print(await result.tool_results()) asyncio.run(main())要点工具参数用 PydanticBaseModel声明CallableTool2[AddToolParams]提供类型安全的参数绑定step只执行一次模型生成与工具派发返回StepResultawait result.tool_results()聚合该步内所有工具调用的结果ToolResult列表step不会修改传入的history多轮循环需要调用方自行追加消息见下文最小 Agent 循环。最小 Agent 循环模块 docstring 中的完整示例kimi_sdk的模块 docstringinit.py内置了一个可直接运行的最小 Agent 循环读取用户输入、将用户消息追加到history、反复调用step直到模型不再产生工具调用并把ToolResult转换为roletool的消息回填历史import asyncio from kimi_sdk import Kimi, Message, SimpleToolset, StepResult, ToolResult, step def tool_result_to_message(result: ToolResult) - Message: return Message( roletool, tool_call_idresult.tool_call_id, contentresult.return_value.output, ) async def agent_loop() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) toolset SimpleToolset() history: list[Message] [] system_prompt You are a helpful assistant. while True: user_input input(You: ).strip() if not user_input: continue if user_input.lower() in {exit, quit}: break history.append(Message(roleuser, contentuser_input)) while True: result: StepResult await step( chat_providerkimi, system_promptsystem_prompt, toolsettoolset, historyhistory, ) history.append(result.message) tool_results await result.tool_results() for tool_result in tool_results: history.append(tool_result_to_message(tool_result)) if text : result.message.extract_text(): print(Assistant:, text) if not result.tool_calls: break asyncio.run(agent_loop())这个模式与 Kimi CLI 自身的 Agent 工作流同构Kimi CLI 的 soul/agent.py 正是基于消息历史 工具调度 循环收敛的思路驱动交互SDK 将这个循环提炼为可复用的最小范式。环境变量与 Kosong 的 Kimi provider 语义保持一致KLIP-7 明确环境变量保持相同语义KIMI_API_KEYKimi API 密钥KIMI_BASE_URL覆盖 API 基础地址默认https://api.moonshot.ai/v1。在 kimi.py 中api_key与base_url未显式传入时依次回退到环境变量且两者都缺失时会抛出ChatProviderError提示设置api_key参数或KIMI_API_KEY。底层原理generate 与 step 的实现剖析理解 SDK 的行为需要回到其依赖的 Kosong 实现。generate流式分片合并packages/kosong/src/kosong/_generate.py 中的generate函数调用chat_provider.generate(system_prompt, tools, history)获得流逐片消费StreamedMessagePart通过merge_in_place尝试把可合并的分片如连续的文本增量就地合并无法合并的分片如工具调用则按序追加到Message可选地通过on_message_part、on_tool_call、on_trace_id三个回调实时转发原始分片、完整工具调用与请求的x-trace-id响应头对空响应与仅有思考内容、无文本无工具调用的异常终止常见于推理中途流中断或max_tokens耗尽抛出APIEmptyResponseError这是对 Kimi 推理类模型输出的重要防护返回GenerateResult含id、message、usage、trace_id。step工具派发与异步结果packages/kosong/src/kosong/init.py 中的step在generate的on_tool_call回调里同步派发工具toolset.handle(tool_call)若返回ToolResult则包装为已完成的ToolResultFuture否则直接持有异步 Future。StepResult.tool_results()按tool_calls顺序 await 每个 Future 收集结果并在结束或异常时取消所有未完成 Future避免悬挂任务实现见此处。Kimi provider 的适配细节packages/kosong/src/kosong/chat_provider/kimi.py 中值得注意的实现细节思考内容响应中的reasoning_content被转换为ThinkPart流式场景下空字符串的reasoning_content也会保留为ThinkPart以区分已推理但为空与未推理部分后端要求每个 assistant 轮次都携带reasoning_content工具 schema 修补Moonshot API 会拒绝嵌套属性缺少type的参数 schema例如部分 MCP 服务器暴露的 enum-only 属性_convert_tool通过ensure_property_types本地修补 schema 后再发送见此处内置函数以$开头的工具名会被转换为typebuiltin_functionKimi 内置函数无需提供描述与参数Token 用量拆分KimiStreamedMessage.usage会把 Moonshot 的cached_tokens或 OpenAI 兼容的prompt_tokens_details.cached_tokens拆分为input_cache_read其余输入记为input_other见此处生成参数with_generation_kwargs/with_thinking/with_extra_body以不可变复制方式返回新实例支持temperature、max_completion_tokensmax_tokens为弃用别名会自动归一化、reasoning_effort等参数with_extra_body对thinking子键做字段级合并保证先设置thinking.type再追加thinking.keep时不会互相覆盖。依赖策略与 Kosong 的版本协作KLIP-7 提出了分阶段依赖策略仓库现状处于 Phase 1MVP直接依赖 Kosong最初建议的依赖区间为kosong0.37.0,0.38.0通过严格上界保证兼容性实际落地时pyproject.toml 采用kosong0.37.0无上界配套 CHANGELOG 中 0.1.1、0.1.2、0.2.1 等版本陆续放宽对 kosong 0.38.x、0.39.x、0.40.x 的支持——这印证了 KLIP-7 的非锁步理念kimi-sdk独立发版兼容性通过 Kosong 依赖区间而非版本号联动来保障。开发依赖包含httpx、inline-snapshot[black]、pdoc、pyright、ty、pytest、pytest-asyncio、ruff等构建后端为uv_build并启用了 ruffE/F/UP/B/SIM/I 规则集、pyright strict 与 ty 类型检查。版本管理、Tag 与发布工作流KLIP-7 对版本与发布做了明确约定独立 semverkimi-sdk使用自己的语义化版本兼容性由 Kosong 依赖区间约束Tag 前缀新增kimi-sdk-*前缀如kimi-sdk-0.1.0发布工作流计划新增.github/workflows/release-kimi-sdk.yml触发条件为kimi-sdk-*标签依次执行版本校验scripts/check_version_tag.py、构建make build-kimi-sdk、发布pypa/gh-action-pypi-publishv1 阶段不发布文档Makefile 集成仓库根目录 Makefile 中已落地format-kimi-sdk、check-kimi-sdk、test-kimi-sdk、build-kimi-sdk四个目标分别执行 ruff 格式化/检查、pyrightty 类型检查、pytest 测试与uv build --package kimi-sdk构建。测试与 CIKLIP-7 规划的冒烟测试已落地为 sdks/kimi-sdk/tests/test_smoke.py使用httpx.MockTransport拦截POST /v1/chat/completions返回预设的 chat completion JSON构造Kimi(modelkimi-k2-turbo-preview, api_keytest-key, streamFalse, http_clienthttp_client)调用generate后断言result.message.role assistantresult.message.extract_text() Helloresult.usage.input_other 10、result.usage.output 5验证TokenUsage字段解析正确。CI 层面规划了ci-kimi-sdk.yml复用make check-kimi-sdk与make test-kimi-sdk结构镜像ci-kosong.yml保证 SDK 的 lint、类型检查与测试在每次变更中持续生效。从 Kosong 迁移到 kimi-sdkKLIP-7 明确指出从kosong迁移到kimi-sdk只涉及导入路径的变化。以工具调用示例为例对照如下Kosong 写法kimi-sdk 写法from kosong.chat_provider.kimi import Kimifrom kimi_sdk import Kimifrom kosong.message import Messagefrom kimi_sdk import Messagefrom kosong.tooling import CallableTool2, ToolOk, ToolReturnValuefrom kimi_sdk import CallableTool2, ToolOk, ToolReturnValuefrom kosong.tooling.simple import SimpleToolsetfrom kimi_sdk import SimpleToolsetkosong.step(...)/kosong.generate(...)kimi_sdk.step(...)/kimi_sdk.generate(...)唯一的取舍是kimi-sdk刻意不暴露kosong.contrib与其他 provider因此依赖多 provider 能力的代码不适合迁移面向 Kimi 的 Agent 应用则可以获得更简洁、聚焦的导入面。总结Kimi SDK 以薄封装策略在 KLIP-7 的设计约束下快速落地generate负责流式合并与完整消息产出step负责工具派发与异步结果聚合消息分片、工具抽象、错误类型与展示块全部集中在kimi_sdk顶层。对开发者而言这意味着可以用一套 OpenAI-SDK 风格的扁平 API在 20 行左右的代码内搭建起具备多模态输入、工具调用与流式输出的 Kimi Agent 应用而对维护者而言Kosong 依赖区间 独立 semver Makefile/CI 目标构成的发布链路则保证了 SDK 可以持续、低风险地跟进底层能力演进。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kimi CLI 中的 Kimi SDK：基于 Kosong 的轻量级 Python Agent 开发套件
Kimi CLI 中的 Kimi SDK基于 Kosong 的轻量级 Python Agent 开发套件【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cliKimi SDK仓库路径 sdks/kimi-sdk是 Kimi CLI 项目推出的轻量级 Python SDK为开发者提供访问 Kimi API 并构建 Agent 工作流的一站式入口。本文围绕设计文档 KLIP-7: Kimi SDK (thin wrapper around Kosong) 展开讲解其包结构、公开 API、依赖与版本策略、测试与 CI 设计并结合仓库源码说明generate/step、消息内容分片、工具调用等底层实现原理帮助你快速上手基于 Kimi 的 Agent 开发。背景与设计目标KLIP-7 记录了 kimi-sdk 的设计决策作为 Kosong 之上的一层薄封装thin wrapper在保持低风险、快速交付的前提下提供一个 OpenAI-SDK 风格的统一入口from kimi_sdk import Kimi, generate, step, Message设计目标明确为仅保留 Kimi 能力只导出 Kosong 的 Kimi provider 与 Agent 原语不暴露其他 provider含kosong.contrib零行为改动v1 采用纯 re-export 实现不引入新的 HTTP 层不改变 Kimi 请求/响应语义扁平模块所有公开 API 都位于包顶层kimi_sdk不划分kimi_sdk.*子模块导出完整内容分片支持 Kimi chat provider 的全部内容分片content parts与展示块display blocks。该设计同时明确了非目标不对 Kosong 做拆分或重构文档发布推迟到 v1 之后。这意味着 v1 阶段的 kimi-sdk 更像一个能力子集 统一入口而非独立的实现体系。包结构扁平模块设计根据 KLIP-7 的规划sdks/kimi-sdk的目录结构如下与仓库现状一致sdks/kimi-sdk/ pyproject.toml README.md CHANGELOG.md LICENSE / NOTICE src/kimi_sdk/ __init__.py py.typed模块职责划分kimi_sdk.__init__re-export 全部公开面Kimi、KimiStreamedMessage、generate、step、GenerateResult、Message、SimpleToolset、工具类型、provider 异常、内容分片、展示块并通过显式__all__按类别分组保持面向 Kimi 的清晰界面模块 docstring 内置了一个最小 Agent 循环示例py.typed标记包支持 PEP 561 类型标注配合项目中的 pyright strict 检查。在仓库源码 sdks/kimi-sdk/src/kimi_sdk/init.py 中可以看到所有符号均来自kosong及其子模块的导入例如from kosong.chat_provider.kimi import Kimi, KimiFiles, KimiStreamedMessage、from kosong.tooling.simple import SimpleToolset整个包没有一行业务实现——这正印证了薄封装的定位SDK 的稳定性完全由下游 Kosong 保障。公开 API 全景KLIP-7 规划并在init.py 中实现的__all__按六类组织分类导出的符号providersKimi、KimiFiles、KimiStreamedMessage、StreamedMessagePart、ThinkingEffortprovider errorsAPIConnectionError、APIEmptyResponseError、APIStatusError、APITimeoutError、ChatProviderErrormessages content partsMessage、Role、ContentPart、TextPart、ThinkPart、ImageURLPart、AudioURLPart、VideoURLPart、ToolCall、ToolCallParttoolingTool、CallableTool、CallableTool2、Toolset、SimpleToolset、ToolReturnValue、ToolOk、ToolError、ToolResult、ToolResultFuturedisplay blocksDisplayBlock、BriefDisplayBlock、UnknownDisplayBlockgenerationgenerate、step、GenerateResult、StepResult、TokenUsage其中KimiFiles与VideoURLPart是 0.2.0 版本见 CHANGELOG新增的视频上传能力比 KLIP-7 最初的导出清单更完整体现了 SDK 随版本迭代持续扩展的实践。快速上手安装与第一个对话环境要求与安装Kimi SDK 要求 Python 3.12 或更高版本见 pyproject.toml推荐使用 uv 作为包管理器uv init --python 3.12 # or higher uv add kimi-sdk简单对话补全import asyncio from kimi_sdk import Kimi, Message, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) history [ Message(roleuser, contentWho are you?), ] result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, ) print(result.message) print(result.usage) asyncio.run(main())generate返回的GenerateResult包含message合并完成后的完整Message与usageTokenUsage当 API 返回空响应时抛出APIEmptyResponseError见下文底层原理。流式输出通过on_message_part回调逐片接收流式内容适合实时展示场景import asyncio from kimi_sdk import Kimi, Message, StreamedMessagePart, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) history [ Message(roleuser, contentWho are you?), ] def output(message_part: StreamedMessagePart) - None: print(message_part) result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, on_message_partoutput, ) print(result.message) print(result.usage) asyncio.run(main())视频上传KimiFiles 的多模态能力Kimi SDK 通过Kimi.files暴露文件能力。KimiFiles.upload_video将视频上传到 Kimi files API 并返回一个VideoURLPart内容分片可直接嵌入消息import asyncio from pathlib import Path from kimi_sdk import Kimi, Message, TextPart, generate async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) video_path Path(demo.mp4) video_part await kimi.files.upload_video( datavideo_path.read_bytes(), mime_typevideo/mp4, ) history [ Message( roleuser, content[ TextPart(textPlease describe this video.), video_part, ], ), ] result await generate( chat_providerkimi, system_promptYou are a helpful assistant., tools[], historyhistory, ) print(result.message) print(result.usage) asyncio.run(main())在底层实现 packages/kosong/src/kosong/chat_provider/kimi.py 中upload_video会校验 MIME 类型必须以video/开头否则抛出ChatProviderError随后以purposevideo调用/files接口并将返回的ms://file_idURL 封装为VideoURLPart供模型引用。工具调用用 step 构建单步 Agent 循环step在generate之上叠加了工具调度能力。以下示例定义了一个两整数相加的工具并通过SimpleToolset注册import asyncio from pydantic import BaseModel from kimi_sdk import CallableTool2, Kimi, Message, SimpleToolset, StepResult, ToolOk, ToolReturnValue, step class AddToolParams(BaseModel): a: int b: int class AddTool(CallableTool2[AddToolParams]): name: str add description: str Add two integers. params: type[AddToolParams] AddToolParams async def __call__(self, params: AddToolParams) - ToolReturnValue: return ToolOk(outputstr(params.a params.b)) async def main() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) toolset SimpleToolset() toolset AddTool() history [ Message(roleuser, contentPlease add 2 and 3 with the add tool.), ] result: StepResult await step( chat_providerkimi, system_promptYou are a precise math tutor., toolsettoolset, historyhistory, ) print(result.message) print(await result.tool_results()) asyncio.run(main())要点工具参数用 PydanticBaseModel声明CallableTool2[AddToolParams]提供类型安全的参数绑定step只执行一次模型生成与工具派发返回StepResultawait result.tool_results()聚合该步内所有工具调用的结果ToolResult列表step不会修改传入的history多轮循环需要调用方自行追加消息见下文最小 Agent 循环。最小 Agent 循环模块 docstring 中的完整示例kimi_sdk的模块 docstringinit.py内置了一个可直接运行的最小 Agent 循环读取用户输入、将用户消息追加到history、反复调用step直到模型不再产生工具调用并把ToolResult转换为roletool的消息回填历史import asyncio from kimi_sdk import Kimi, Message, SimpleToolset, StepResult, ToolResult, step def tool_result_to_message(result: ToolResult) - Message: return Message( roletool, tool_call_idresult.tool_call_id, contentresult.return_value.output, ) async def agent_loop() - None: kimi Kimi( base_urlhttps://api.moonshot.ai/v1, api_keyyour_kimi_api_key_here, modelkimi-k2-turbo-preview, ) toolset SimpleToolset() history: list[Message] [] system_prompt You are a helpful assistant. while True: user_input input(You: ).strip() if not user_input: continue if user_input.lower() in {exit, quit}: break history.append(Message(roleuser, contentuser_input)) while True: result: StepResult await step( chat_providerkimi, system_promptsystem_prompt, toolsettoolset, historyhistory, ) history.append(result.message) tool_results await result.tool_results() for tool_result in tool_results: history.append(tool_result_to_message(tool_result)) if text : result.message.extract_text(): print(Assistant:, text) if not result.tool_calls: break asyncio.run(agent_loop())这个模式与 Kimi CLI 自身的 Agent 工作流同构Kimi CLI 的 soul/agent.py 正是基于消息历史 工具调度 循环收敛的思路驱动交互SDK 将这个循环提炼为可复用的最小范式。环境变量与 Kosong 的 Kimi provider 语义保持一致KLIP-7 明确环境变量保持相同语义KIMI_API_KEYKimi API 密钥KIMI_BASE_URL覆盖 API 基础地址默认https://api.moonshot.ai/v1。在 kimi.py 中api_key与base_url未显式传入时依次回退到环境变量且两者都缺失时会抛出ChatProviderError提示设置api_key参数或KIMI_API_KEY。底层原理generate 与 step 的实现剖析理解 SDK 的行为需要回到其依赖的 Kosong 实现。generate流式分片合并packages/kosong/src/kosong/_generate.py 中的generate函数调用chat_provider.generate(system_prompt, tools, history)获得流逐片消费StreamedMessagePart通过merge_in_place尝试把可合并的分片如连续的文本增量就地合并无法合并的分片如工具调用则按序追加到Message可选地通过on_message_part、on_tool_call、on_trace_id三个回调实时转发原始分片、完整工具调用与请求的x-trace-id响应头对空响应与仅有思考内容、无文本无工具调用的异常终止常见于推理中途流中断或max_tokens耗尽抛出APIEmptyResponseError这是对 Kimi 推理类模型输出的重要防护返回GenerateResult含id、message、usage、trace_id。step工具派发与异步结果packages/kosong/src/kosong/init.py 中的step在generate的on_tool_call回调里同步派发工具toolset.handle(tool_call)若返回ToolResult则包装为已完成的ToolResultFuture否则直接持有异步 Future。StepResult.tool_results()按tool_calls顺序 await 每个 Future 收集结果并在结束或异常时取消所有未完成 Future避免悬挂任务实现见此处。Kimi provider 的适配细节packages/kosong/src/kosong/chat_provider/kimi.py 中值得注意的实现细节思考内容响应中的reasoning_content被转换为ThinkPart流式场景下空字符串的reasoning_content也会保留为ThinkPart以区分已推理但为空与未推理部分后端要求每个 assistant 轮次都携带reasoning_content工具 schema 修补Moonshot API 会拒绝嵌套属性缺少type的参数 schema例如部分 MCP 服务器暴露的 enum-only 属性_convert_tool通过ensure_property_types本地修补 schema 后再发送见此处内置函数以$开头的工具名会被转换为typebuiltin_functionKimi 内置函数无需提供描述与参数Token 用量拆分KimiStreamedMessage.usage会把 Moonshot 的cached_tokens或 OpenAI 兼容的prompt_tokens_details.cached_tokens拆分为input_cache_read其余输入记为input_other见此处生成参数with_generation_kwargs/with_thinking/with_extra_body以不可变复制方式返回新实例支持temperature、max_completion_tokensmax_tokens为弃用别名会自动归一化、reasoning_effort等参数with_extra_body对thinking子键做字段级合并保证先设置thinking.type再追加thinking.keep时不会互相覆盖。依赖策略与 Kosong 的版本协作KLIP-7 提出了分阶段依赖策略仓库现状处于 Phase 1MVP直接依赖 Kosong最初建议的依赖区间为kosong0.37.0,0.38.0通过严格上界保证兼容性实际落地时pyproject.toml 采用kosong0.37.0无上界配套 CHANGELOG 中 0.1.1、0.1.2、0.2.1 等版本陆续放宽对 kosong 0.38.x、0.39.x、0.40.x 的支持——这印证了 KLIP-7 的非锁步理念kimi-sdk独立发版兼容性通过 Kosong 依赖区间而非版本号联动来保障。开发依赖包含httpx、inline-snapshot[black]、pdoc、pyright、ty、pytest、pytest-asyncio、ruff等构建后端为uv_build并启用了 ruffE/F/UP/B/SIM/I 规则集、pyright strict 与 ty 类型检查。版本管理、Tag 与发布工作流KLIP-7 对版本与发布做了明确约定独立 semverkimi-sdk使用自己的语义化版本兼容性由 Kosong 依赖区间约束Tag 前缀新增kimi-sdk-*前缀如kimi-sdk-0.1.0发布工作流计划新增.github/workflows/release-kimi-sdk.yml触发条件为kimi-sdk-*标签依次执行版本校验scripts/check_version_tag.py、构建make build-kimi-sdk、发布pypa/gh-action-pypi-publishv1 阶段不发布文档Makefile 集成仓库根目录 Makefile 中已落地format-kimi-sdk、check-kimi-sdk、test-kimi-sdk、build-kimi-sdk四个目标分别执行 ruff 格式化/检查、pyrightty 类型检查、pytest 测试与uv build --package kimi-sdk构建。测试与 CIKLIP-7 规划的冒烟测试已落地为 sdks/kimi-sdk/tests/test_smoke.py使用httpx.MockTransport拦截POST /v1/chat/completions返回预设的 chat completion JSON构造Kimi(modelkimi-k2-turbo-preview, api_keytest-key, streamFalse, http_clienthttp_client)调用generate后断言result.message.role assistantresult.message.extract_text() Helloresult.usage.input_other 10、result.usage.output 5验证TokenUsage字段解析正确。CI 层面规划了ci-kimi-sdk.yml复用make check-kimi-sdk与make test-kimi-sdk结构镜像ci-kosong.yml保证 SDK 的 lint、类型检查与测试在每次变更中持续生效。从 Kosong 迁移到 kimi-sdkKLIP-7 明确指出从kosong迁移到kimi-sdk只涉及导入路径的变化。以工具调用示例为例对照如下Kosong 写法kimi-sdk 写法from kosong.chat_provider.kimi import Kimifrom kimi_sdk import Kimifrom kosong.message import Messagefrom kimi_sdk import Messagefrom kosong.tooling import CallableTool2, ToolOk, ToolReturnValuefrom kimi_sdk import CallableTool2, ToolOk, ToolReturnValuefrom kosong.tooling.simple import SimpleToolsetfrom kimi_sdk import SimpleToolsetkosong.step(...)/kosong.generate(...)kimi_sdk.step(...)/kimi_sdk.generate(...)唯一的取舍是kimi-sdk刻意不暴露kosong.contrib与其他 provider因此依赖多 provider 能力的代码不适合迁移面向 Kimi 的 Agent 应用则可以获得更简洁、聚焦的导入面。总结Kimi SDK 以薄封装策略在 KLIP-7 的设计约束下快速落地generate负责流式合并与完整消息产出step负责工具派发与异步结果聚合消息分片、工具抽象、错误类型与展示块全部集中在kimi_sdk顶层。对开发者而言这意味着可以用一套 OpenAI-SDK 风格的扁平 API在 20 行左右的代码内搭建起具备多模态输入、工具调用与流式输出的 Kimi Agent 应用而对维护者而言Kosong 依赖区间 独立 semver Makefile/CI 目标构成的发布链路则保证了 SDK 可以持续、低风险地跟进底层能力演进。【免费下载链接】kimi-cliKimi Code CLI is your next CLI agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kimi-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考