轻量编码代理 Sikao-Engine/KimiX

Kimi-CLI-X

中文文档

安装

python install.py

install.py 负责整套安装流程：同步依赖、下载原生运行时、注册工具。

注意： 本仓库不只支持 KIMI LLM，也支持各种 API key！比如 OpenAI、Anthropic 等。默认配置模板放在 docs/ 下；安装完成后用 kimix --config=xx.json 启动。

teasor

为什么选 Kimi-CLI-X？

Kimi-CLI-X 在原版 Kimi-CLI 基础上做了深度优化，重点放在提示词效率、工具可靠性和可扩展性上，另外还加了几个面向真实开发场景的新工具。

优化点

1. 精简系统提示词 —— 把初始提示词和工具描述压缩到约 2000 token，同时覆盖几乎所有内置工具。
2. 加固权限与校验 —— 正确处理 Shell、Glob 等工具的校验，减少失败引发的重试循环。
3. 改进子进程输出 —— 大输出重定向到临时文件，过滤冗余日志，方便后端取回。
4. 简化并发 —— 重新设计子进程、子代理和后台任务，结构更清爽。
5. 可编程提示词 —— 允许在上层注入自定义系统提示词，灵活适配各种场景。
6. 显式会话管理 —— 多任务编排和状态跟踪更清晰。
7. 写入即校验 —— 对严格配置文件自动做格式检查和告警，防止模型幻觉出错。
8. 多 API 支持 —— 导入自定义配置，兼容 OpenAI、Anthropic 等。
9. 后端已验证 —— 已针对 kimi、xai、anthropic、openai_legacy、openai_responses、google_genai/gemini、vertexai/vertex 测试，另加 25+ 个从 Hermes 移植的服务商（deepseek、openrouter、xiaomi、zai、minimax、bedrock……）。详见 kimi-cli/tests/core/test_create_llm.py 和支持的服务商列表。

新增能力

| 能力 | 说明 |
| 交互式 shell 工具 | 通过 task_id 启动并继续 Bash/Powershell/Run 会话，可选 wait_for_pattern。 |
| Docx / PDF 转换 | 内置文档转换，不依赖外部组件。 |
| Python 脚本执行 | 智能体可以直接运行 Python 脚本。 |
| 错误日志 | 记录工具调用错误，供模型回溯和改进。 |
| 脚本系统 | 把提示词和 Python 逻辑组合起来，编排复杂任务。 |
| 增强网页抓取（fetch_url） | 基于无头浏览器输出 Markdown（不是纯文本），支持 output_path，超长内容自动截断；零外部服务依赖。 |
| Best-of-N 采样（AgentSwarm parallel_sample） | 在隔离工作区（git worktree / 临时副本）里把同一任务跑 N 次，用 self_eval 或 majority 选出胜者，再应用并验证胜出的 diff —— 绝不静默接受。 |

可脚本化工作流（核心优势）

不同于传统 CLI 交互中逐条输入命令的方式，Kimi-CLI-X 让你用 Python 脚本编排整个工作流。你可以把提示词、循环、条件判断和工具调用组合成完全自动化、可复现的任务流水线：

from kimix import *
from pathlib import Path

clear_default_context()

for i in Path('docs').glob('*.md'):
prompt(f'''According to the new git commits, update document {i}''')

好处：

- 批量自动化：用原生 Python 语法（for 循环、文件通配）一次性对多个文件发起任务。
- 复杂编排：自由组合模式切换、工具调用和逻辑判断，搭出多阶段、多分支的工作流。
- 可复现、易维护：工作流以脚本形式纳入版本控制，而不是散落在聊天记录里。

上下文记忆架构

Kimi-CLI-X 在 KimiSoul 核心循环里内置了自动上下文记忆系统，让长对话保持连贯，无需人工干预。三层机制协同工作：

1. 对话历史索引（HistoryIndex）

每条用户/助手消息在追加时都会自动建立 BM25 倒排索引（N-gram，n=2），持久化到 <session>/history_index/<id>.json，进程重启后依然存在。上限 500 轮，超出后自动淘汰最旧的记录。

2. 自动上下文压缩（SimpleCompaction）

当上下文 token 占比达到 compaction_trigger_ratio，或剩余空间低于 reserved_context_size 时触发：

- 保留策略：最近 N 轮原样保留（深度由 adaptive_preserve_depth 自适应调整——遇到错误、思考、多文件编辑等情况会加深）；首条消息始终保留（首因效应）。
- LLM 摘要：旧消息通过一次轻量 LLM 调用压缩成结构化摘要；思考块丢弃。
- 级联处理：已压缩的内容再次被压缩时（深度 ≥3），切换到 COMPACT_CASCADE 提示词，防止信息衰减。
- 压缩完成后，所有轮次在 HistoryIndex 中标记为 is_compacted，供后续检索使用。

智能体 Harness：自我调节与提醒

KimiSoul 核心循环会主动让长时间运行保持在正轨上——不用你盯着。CLI、服务器和子代理会话中都一样生效。

- 验证关卡——待办未完成，或编辑了文件却没跑任何检查，这一轮就不能结束。检查失败会反馈给智能体去修复。
- 防循环检测——捕捉跨不同工具对同一文件的重复编辑，以及同一错误反复出现却没有根治；提示智能体换策略。
- 待办提醒——未完成的待办会定期在上下文末尾重新浮现，目标不会淡出注意力。
- 预算提醒（可选开启）——每轮步数/时间预算快用完时给出收尾警告，让智能体从容收尾，而不是被硬切断。
- 决策感知压缩 — 压缩摘要会保留 Decisions & Conclusions 和 Verification Status 两个小节，早期决策和已验证的工作不会丢失。
- 上下文修剪 — 过期工具输出、思考块和近似重复内容会自动省略，回收上下文空间。

todo_list

todo_list 工具跟踪多步计划 — 一个工具，一种条目结构：
- 读取（省略 todos）、upsert（mode='merge'，默认）、整树写入（mode='replace'）、mode='clear'，支持逐条备注。
- 通过 parent=/scope= 嵌套子待办；complete=true 一次调用完成整棵子树，rename_to 原地重命名。
- 重新声明已有标题时，若编号、标点、大小写或词序不同，直接拒绝，不会重复创建（用 on_conflict='reuse'|'append' 关闭该行为）。

Best-of-N Sampling

AgentSwarm 的 parallel_sample 模式在隔离工作区（git worktree / 临时副本）里把同一任务跑 N 次，由模型自评或多数投票选出胜者，再应用并验证胜出的 diff。失败会显式报错 — 绝不静默接受。

文档索引

教程

| 文档 | 说明 |
| docs/tutorials/1_quick_start_en.md | 快速开始指南：一条命令安装、命令行参数、交互式命令。 |
| docs/tutorials/2_long_task_en.md | KimiX 中的长任务策略。 |
| docs/tutorials/3_builtin_tools_en.md | 内置工具完整指南：文件 I/O、搜索、代码执行、进程管理、文档转换、计划模式、子代理，以及提示词策略和最佳实践。 |
| docs/tutorials/4_skills_en.md | 自定义技能编写：设计原则、目录结构、SKILL.md 规范、资源组织、测试、打包和安装。 |
| docs/tutorials/5_server_en.md | HTTP 服务器教程：FastAPI + SSE、兼容 OpenCode 的 REST API、会话管理、事件流、SSE 命令行调试器、dummy 模式、客户端实现。 |
| docs/tutorials/6_multi_provider_en.md | 多服务商配置：用带角色标签的 sub_providers 把子代理和规划器路由到不同 LLM 服务商。 |
| docs/tutorials/7_builtin_tool_injection_en.md | 内置工具注入：在 .kimix/config.json 中声明按会话生效的 JSON-RPC 服务器，扩展 read/write/edit，参考实现见 tools/kimix_lsp.py。 |

配置参考

| 文件 | 说明 |
| docs/config.json | 示例模型配置，含 model、url、api_key、capabilities 等。 |
| docs/sub_provider_link.json | 示例配置：通过 {"role": "sub_agent", "json": "subagent.json"} 从另一个 JSON 文件注册子服务商（会沿父目录逐级向上查找）。 |
| docs/subagent.json | docs/sub_provider_link.json 引用的子服务商配置。 |
| .kimix/config.json | 工作区行为配置：protected_write_paths、protected_read_paths、forbidden_commands 等。 |
| .kimix/skill.json | 工作区技能目录配置：skill_dir 字段（字符串或数组），用于指定额外的技能目录，路径相对工作区解析。 |