Sikao-Engine/KimiX

Kimi-CLI-X

中文文档

安装

python install.py

install.py 处理整个安装流程：依赖同步、原生运行时下载以及工具注册。

注意： 本仓库不仅支持 KIMI LLM，还支持多种 API 密钥！例如 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 脚本执行 | Agent 可以直接运行 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）自动建立索引，持久化到 /history_index/.json，并在进程重启后依然保留。上限为 500 轮；最旧的记录会被自动淘汰。

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

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

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

3. 自动历史检索 + 按需召回

- 自动检索（_maybe_auto_retrieve_history）：每轮中，如果用户输入 ≥10 个字符，则通过 BM25 在 HistoryIndex 中搜索匹配的已压缩轮次；将超过 auto_retrieve_history_threshold 的匹配项以 [Auto-retrieved from past conversation] 形式注入。
- retrieve 工具：智能体可以通过自然语言查询主动搜索所有归档历史（包括已压缩轮次），返回带相关性评分的逐字摘录（或按 id 获取某一轮）。

┌──────────────┐    append     ┌──────────────┐    overflow    ┌──────────────────┐
│   Context    │ ───────────► │ HistoryIndex │ ────────────► │ SimpleCompaction │
│ (live window)│              │ (BM25 index) │               │ (LLM summary)    │
└──────────────┘              └──────────────┘               └──────────────────┘
▲                            │                               │
│       自动检索        │                               │
└────────────────────────────┘                               │
│              检索（agent主动recall）                       │
└────────────────────────────────────────────────────────────┘

Agent Harness：自我调节与提醒

KimiSoul 核心循环会主动让长时间运行保持在正轨上——无需人工照看。它在 CLI、服务器和子代理会话中同样有效。

- 验证门控 — 当待办事项未完成，或文件被编辑但未运行任何检查时，一个回合无法结束。失败的检查会被反馈给代理以进行修复。
- 防循环检测 — 捕获跨不同工具对同一文件的重复编辑，以及同一错误反复出现却未进行根因修复的情况；提示代理改变策略。
- 待办提醒 — 未完成的待办事项会定期在上下文末尾重新浮现，因此目标永远不会偏离注意力。
- 压缩提醒 — 当上下文填满时（约70%），代理会被提示在强制自动压缩启动之前按自己的方式压缩。
- 预算提醒（可选启用）— 当每回合的步骤/时间预算即将耗尽时发出收尾警告，以便代理优雅地完成，而不是被切断。
- 上下文计量器 — 当上下文使用量发生实质性变化时，代理会被提醒使用 Retrieve 工具召回过去的历史记录。
- 决策感知压缩 — 压缩摘要会保留 Decisions & Conclusions 和 Verification Status 部分，因此早期决策和已验证的工作得以保留。
- 上下文修剪 — 过时的工具输出、思考块和近乎重复的内容会被自动省略，以回收上下文空间。

todo_write
todo_write 工具用于跟踪多步骤计划：
- 通过追加/覆盖模式进行增量更新，支持模糊标题匹配和每个待办事项的备注。
- 通过 todo_write（发送完整树）或 todo_update(parent=...) 创建嵌套子待办事项；todo_update(complete=True) 一次调用即可完成一个子树。

Best-of-N 采样

AgentSwarm 的 parallel_sample 模式在隔离的工作区（git worktree / 临时副本）中将同一任务运行 N 次，通过模型自我评估或多数投票选出获胜者，然后应用并验证获胜的差异。失败是显式错误——绝不会被静默接受。

文档索引

教程

| 文档 | 描述 |
|----------|-------------|
| docs/tutorials/1_quick_start_en.md | 快速入门指南：一键安装、CLI 参数和交互式命令。 |
| 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 CLI 调试器、虚拟模式，以及客户端实现。 |
| docs/tutorials/6_multi_provider_en.md | 多提供商配置：通过带角色标签的 sub_providers 将子代理和规划器路由到不同的 LLM 提供商。 |

配置参考

| 文件 | 描述 |
|------|-------------|
| docs/config.json | 示例模型配置，包含 model、url、api_key、capabilities 等。 |
| .kimix/config.json | 工作区行为配置：protected_write_paths、protected_read_paths、forbidden_commands 等。 |
| .kimix/skill.json | 工作区技能目录配置：skill_dir 字段（字符串或数组），用于指定额外的技能目录，相对于工作区解析。 |