把 AI 装进
你的终端

Kimchi 是一款基于 pi-mono SDK 的 AI 编程智能体 CLI —— 多模型编排、LSP、Ferment、远程沙箱，开箱即用。

kimchi — zsh — 120×40

multi-model

# 一次性配置
$ kimchi setup
✔ API 密钥已保存
✔ RTK 已自动安装
✔ 14 个 superpowers skills 就绪

# 启动智能体
$ kimchi
kimchi › 重构 auth 模块，添加 JWT 校验中间件

↳ explore  · 定位 4 个相关文件
↳ plan     · 设计中间件接口与测试
↳ build    · orchestrator → kimi-k2.6
↳ review   · builder → minimax-m3
✔ tests: 12 passed · types: clean

kimchi › ▊

为这些 AI 编程工具注入开源模型

Claude Code OpenCode Codex CLI Cursor Windsurf Zed Cline OpenClaw

6 角色

orchestrator / planner / builder / reviewer / explorer / researcher

14 skills

内置 obra/superpowers 方法论

60–90%

RTK 压缩命令输出，节省 LLM 上下文

∞ 会话

Ferment 跨会话持久化，永不丢失进度

Quick Start · 01

一行命令，
即刻拥有 AI 同事

macOS / Linux

Homebrew

macOS 与 Linux 用户的推荐方式。

$ brew install getkimchi/tap/kimchi

一键安装脚本

下载并安装 CLI，自动启动 setup 向导。

$ curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | bash

各平台

手动下载

从 GitHub Releases 下载二进制。

• kimchi_darwin_amd64.tar.gz
• kimchi_darwin_arm64.tar.gz
• kimchi_linux_amd64.tar.gz
• kimchi_linux_arm64.tar.gz

$ tar xzf kimchi_linux_amd64.tar.gz
$ sudo mv kimchi /usr/local/bin/

Step 02

配置 API 密钥 & 启动

只需运行一次 kimchi setup，按交互提示填入 API 密钥即可完成全部初始化。

$ kimchi setup     # 一次性交互式配置
$ kimchi           # 启动编程智能体

kimchi --help 查看所有可用的子命令和参数。

常用启动选项

kimchi --plan计划模式（只读探索）
kimchi --ferment "构建 X"跨会话项目
kimchi --teleport远程沙箱多路复用
kimchi --name "任务名"设置会话名
kimchi --debug启用调试输出
--enable-experimental-features启用实验功能

Features · 02

不只是聊天框
是一个真正能干活的智能体

Core

多模型编排

每个任务交给最合适的模型。编排器自动按复杂度挑选轻量或重量模型，复杂任务自动升级。

当前会话 · multi-model

Ctrl + P

kimi-k2.6 orchestrator

260K · heavy

minimax-m3 builder

200K · standard

nemotron-3-ultra-fp4 explorer

128K · light

Ferment 持久化

会话崩溃、终端关闭都不怕 —— 下次启动从确切状态恢复。

draft → running → complete

类型感知 LSP

TypeScript / Go 等内置语言服务器，提供定义跳转、引用查找、原子重命名。

TypeScript JavaScript Go

RTK Token 压缩

命令输出压缩 60–90%，大幅减少 LLM 上下文用量。

远程 Teleport

本地 TUI 是大本营，远端沙箱可派生、分离、再连接。

14+ Superpowers Skills

TDD、系统调试、并行委派 —— 内置完整方法论库。

Models · 03

三个模型，
各有专长

无需 Anthropic / OpenAI 的 API 密钥，只要你的 Kimchi API 密钥即可使用以下开源模型。

Default · Orchestrator

kimi-k2.6

heavy

Agentic coding、图像分析（最新）。编排、规划、研究默认模型。

260K

Context

32K

Output

Builder · Reviewer

minimax-m3

standard

代码生成、调试。复杂的代码任务可升级到 Claude。

200K

Context

32K

Output

Explorer

nemotron-3

light

快速推理、低成本任务。代码库扫描首选。

128K

Context

32K

Output

角色与默认模型

编辑 ~/.config/kimchi/harness/settings.json 即可覆盖，或用 /multi-model 交互调整。

角色	默认
orchestrator	`kimi-k2.6`
planner	`kimi-k2.6`
builder	`kimi-k2.6`, `minimax-m3`
reviewer	`kimi-k2.6`, `minimax-m3`
explorer	`nemotron-3-ultra-fp4`
researcher	`kimi-k2.6`

自定义元数据

为外部模型提供 tier / description / vision 信息以改善路由。

{
  "modelRoles": {
    "builder": ["kimchi-dev/minimax-m3",
              "anthropic/claude-sonnet-4-5"],
    "reviewer": "anthropic/claude-sonnet-4-5"
  },
  "modelMetadata": {
    "anthropic/claude-sonnet-4-5": {
      "tier": "heavy",
      "description": "强大的通用模型",
      "vision": true
    }
  }
}

Ferment · 04

跨会话项目
永不丢失进度

渐进细化的项目模式。把目标、阶段、步骤以 JSON 状态文件持久化，崩溃、关机、第二天打开 —— 接着上次继续。

1 draft

创建

通过 /ferment new 创建，智能体对话式收集目标与阶段。

2 planned

规划

设置目标、标准、约束、阶段拆分。

3 running

执行

激活阶段，智能体按步骤执行，每步带验证。

4 paused

暂停

用户介入或 /ferment pause，状态完整保留。

5 complete

完成

所有阶段终态，统计可导出为 JSON。

会话中断可恢复

# Day 1
$ kimchi --ferment "Build Tetris"
# ... 智能体工作中，崩溃，终端关闭 ...

# Day 2
$ kimchi --ferment "Build Tetris"
# -> 恢复状态，精准地从上次中断的 Phase 2 继续

状态存放位置

.kimchi/
  ferments/
    <uuid>.json
    <uuid>.events.jsonl
  sessions/
    <ts>.jsonl

每次变更附状态哈希，完全可审计。

Auto Policy · 05

自动延续策略 /ferment auto

/ferment auto 是 Kimchi Ferment 的自动延续模式：智能体在完成当前阶段后自动推进至下一阶段，无需逐一手动确认。遇到阻塞、需要用户输入或执行异常时自动暂停，待问题解决后继续执行，保持推进直到项目完成。

manual vs auto 对比

行为	命令	何时使用	用户介入点
manual	`/ferment manual`	需要逐阶段审查、高危操作	每阶段结束需手动确认
auto	`/ferment auto`	已知任务、信任智能体自动推进	仅在异常或需用户输入时暂停

Auto 模式状态机

   +--------+   用户介入 / pause   +--------+
   |        | -------------------->|        |
   |running |                     |paused  |
   |        |<--------------------|        |
   +--------+   /ferment resume    +--------+
        |                              ^
        | 所有阶段完成                 | 需用户输入
        v                              |（auto 自动响应）
   +--------+                         +
   |complete|
   +--------+

auto 模式下，智能体自动持续运行，仅在遇到阻塞或需要用户确认时暂停。

命令速查

$ /ferment auto       # 切换至自动延续模式
$ /ferment manual     # 切换至手动确认模式
$ /ferment pause      # 暂停当前 Ferment 运行
$ /ferment resume     # 恢复已暂停的 Ferment
$ /ferment exit       # 退出 Ferment 不丢失状态

Auto 模式示例会话

kimchi — zsh — 120×40

auto-mode

$ kimchi --ferment "构建用户认证系统"
kimchi › /ferment auto

↳ Phase 1 · setup      · 初始化项目结构
  ✔ 创建 src/auth/ 目录
  ✔ 安装依赖 express, jsonwebtoken
  ✔ Phase 1 完成，自动进入 Phase 2

↳ Phase 2 · implement  · 实现 JWT 中间件
  ✔ 编写 token 签发逻辑
  ✔ 编写校验中间件
  → 需要确认：是否引入 lodash 辅助解析？
? 需要用户确认：是否引入 lodash？[y/N] y

  ✔ 用户确认通过，继续执行
  ✔ Phase 2 完成，自动进入 Phase 3

Workflow · 05

工具无缝接管，
模型智能路由

你的 AI 工具

Cursor · Claude · Zed

Kimchi CLI

统一 provider 配置

kimi-k2.6

260K · heavy

Agentic · 图像分析

minimax-m3

200K · standard

代码生成 · 调试

nemotron-3

128K · light

快速推理 · 低成本

所有请求经统一端点 https://llm.kimchi.dev

LSP 集成

内置类型感知代码智能，默认加载，零配置。

TS / JS	`typescript-language-server`
Go	`gopls`

远程 Teleport

本地大本营 + 远端沙箱可派生、分离、再连接。

$ kimchi --teleport

/teleport [name]
/detach
/attach <id>
/sessions

标签与阶段

每个请求自动打 phase:{name} + model:{id} 标签。

explore plan build review research

Superpowers · 06

内置 14 个方法论
让智能体自己会干活

首次启动自动下载并提取 obra/superpowers 到 ~/.config/kimchi/vendor/superpowers/。

★ using-superpowers

入口 —— 如何发现和调用 skills

brainstorming

结构化构思与方案评估

writing-plans

将任务拆解为可执行的实施计划

executing-plans

带检查点的逐步执行

test-driven-development

先写失败的测试，再实现

systematic-debugging

方法论式根因分析

subagent-driven-development

把子任务委派给并行智能体

dispatching-parallel-agents

并发运行多个智能体

writing-skills

创建可复用的 skill 定义

requesting-code-review

为审查准备代码

receiving-code-review

处理与应用审查反馈

verification-before-completion

完成前的最终验证

finishing-a-development-branch

清理分支并准备合并

using-git-worktrees

同时跨多分支工作

Configure · 07

配置完全可控

API 密钥解析顺序

KIMCHI_API_KEY 环境变量（优先）
~/.config/kimchi/config.json 中的 api_key 字段

运行 kimchi setup 进行交互式首次配置。

登录方式（会话内 `/login`）

Kimchi 账号 —— 浏览器登录，自动保存密钥
Kimchi API 密钥 —— 输入密钥与端点（默认 https://llm.kimchi.dev）
订阅 —— 跳转上游 OAuth 提供方

全局配置

~/.config/kimchi/config.json
~/.config/kimchi/harness/

项目级

mkdir -p .kimchi
cat > .kimchi/config.json <<'EOF'
{
  "apiKey": "project-specific-key",
  "llmEndpoint": "https://custom-endpoint.example.com",
  "skillPaths": ["/project/skills"],
  "mcpSearch": { "strategy": "bm25" }
}
EOF

Global · 全局

~/.config/kimchi/harness/AGENTS.md

在任何项目级文件之前加载。

Project · 项目级

AGENTS.md
CLAUDE.md

AGENTS.md 优先于 CLAUDE.md。.local.md 变体附加到主文件后。

包管理

$ kimchi resources disable extensions.pi-package-lookup
$ kimchi update                   # 更新包，然后 Kimchi 本身
$ kimchi update --extensions      # 仅更新已安装包
$ kimchi update self              # 仅更新 Kimchi 本身

RTK · Token 压缩

命令输出压缩 60–90%。每次 bash 工具前调用 rtk rewrite。

$ brew install rtk

控制开关

$ kimchi resources disable hooks.rtk-rewrite
$ kimchi resources enable  hooks.rtk-rewrite
$ KIMCHI_RTK=0 kimchi

Bash 钩子

全局：~/.config/kimchi/harness/hooks/bash/
项目：.kimchi/hooks/bash/

Claude Code 适配

$ kimchi resources enable extensions.claude-code-hook-adapter

Migration

从其它智能体迁移

首次运行时自动检测 Claude Code / OpenCode / Cursor，提供一次性 MCP 服务器迁移。

+ Claude Code + OpenCode + Cursor found
|
|  MCP servers: filesystem, github, ripgrep
|  Claude Code skills: 4
|  OpenCode skills: 2
|  Cursor skills: 3
|
* Migrate MCP servers to Kimchi?
|  * Migrate now
|  * Skip this time
|  * Never ask again

命名冲突时 Claude Code > OpenCode > Cursor；已有 Kimchi 条目始终优先。

Resources

资源管理

集中管理钩子、工具、扩展与插件的开关状态。

$ kimchi resources list
$ kimchi resources enable  <id>
$ kimchi resources disable <id>
$ kimchi resources reset   <id>

# 会话内
/resources
/resources list
/hooks
/plugins

Development · 08

为开发者
而生的工具链

环境要求

Node.js 22 (LTS)
Bun · 二进制编译
corepack 已启用
pnpm（自动安装）

快速设置

$ ./scripts/dev-startup.sh

检查并安装 node/pnpm/bun → pnpm install → 启动 harness。

手动设置

$ git clone git@github.com:getkimchi/kimchi.git
$ cd kimchi
$ corepack enable
$ pnpm install

常用命令

`pnpm run build`	编译到 `dist/`
`pnpm run dev`	本地运行 CLI
`pnpm run check`	lint + type check
`pnpm run lint`	Biome lint
`pnpm run test`	vitest 测试
`pnpm run test:smoke`	端到端冒烟测试

项目结构

src/
  entry.ts              # 入口
  cli.ts                # CLI 逻辑与 harness
  models.ts             # 模型元数据
  commands/             # 子命令
  extensions/           # 智能体扩展
    agents/             # 子智能体系统
    orchestration/      # 任务分类与委派
    ferment/            # Ferment 生命周期
  modes/
    interactive/        # TUI harness
    acp/                # JSON-RPC over stdio
    teleport/           # 远端多路复用

FAQ · 09

常见问题

会破坏我现有的配置吗？

不会。CLI 保留你现有的工具配置，仅添加 provider 设置。在 models.json 中添加的自定义 provider（Ollama、vLLM、LM Studio 等）也会跨重启保留。

WSL 或 headless Linux 上剪贴板图片粘贴不工作？

这些环境通常没有显示服务器，因此 Kimchi 默认禁用剪贴板图片粘贴以避免启动崩溃。如果你已在 WSL 中运行 X server（如 VcXsrv、X410），可通过环境变量重新启用：

$ export KIMCHI_CLIPBOARD_FORCE=1
$ kimchi

能切回原来的工具吗？

可以。从工具的配置文件中移除 kimchi provider，或重新运行工具原版的 setup 即可。

API 密钥存储在哪里？

全局：~/.config/kimchi/config.json（权限 600）
项目：.kimchi/config.json
环境变量：KIMCHI_API_KEY

支持哪些平台？

macOS（amd64、arm64）与 Linux（amd64、arm64）。通过 bun build --compile 编译的独立二进制无需运行时。命名约定 kimchi_{os}_{arch}.tar.gz，附 checksums.txt（SHA256）。

把 AI 装进 你的终端

一行命令， 即刻拥有 AI 同事

Homebrew

一键安装脚本

手动下载

配置 API 密钥 & 启动

不只是 聊天框 是一个真正能干活的智能体

多模型编排

Ferment 持久化

类型感知 LSP

RTK Token 压缩

远程 Teleport

14+ Superpowers Skills

三个模型， 各有专长

kimi-k2.6

minimax-m3

nemotron-3

角色与默认模型

自定义元数据

跨会话项目 永不丢失进度

创建

规划

执行

暂停

完成

会话中断可恢复

状态存放位置

自动延续策略 /ferment auto

manual vs auto 对比

Auto 模式状态机

命令速查

Auto 模式示例会话

工具无缝接管， 模型智能路由

LSP 集成

远程 Teleport

标签与阶段

内置 14 个方法论 让智能体自己会干活

配置 完全可控

API 密钥解析顺序

登录方式（会话内 /login）

全局配置

项目级

Global · 全局

Project · 项目级

包管理

RTK · Token 压缩

控制开关

Bash 钩子

Claude Code 适配

从其它智能体迁移

资源管理

为 开发者 而生的工具链

环境要求

快速设置

手动设置

常用命令

项目结构

常见问题

让代码 自己写起来

把 AI 装进
你的终端

一行命令，
即刻拥有 AI 同事

不只是聊天框
是一个真正能干活的智能体

三个模型，
各有专长

跨会话项目
永不丢失进度

工具无缝接管，
模型智能路由

内置 14 个方法论
让智能体自己会干活

配置完全可控

登录方式（会话内 `/login`）

为开发者
而生的工具链

让代码
自己写起来