{"owner":"MoonshotAI","repo":"kimi-cli","hasSkills":true,"totalSkillsCount":23,"totalTokensCount":24542,"categories":["anthropic-skill","root-instruction","plugin-manifest","subagent-persona"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/codex-worker/SKILL.md",".agents/skills/feature-smoke-test/SKILL.md",".agents/skills/feature-smoke-test/references/prompt-patterns.md",".agents/skills/gen-changelog/SKILL.md",".agents/skills/gen-docs/SKILL.md",".agents/skills/gen-rust/SKILL.md",".agents/skills/pull-request/SKILL.md",".agents/skills/release/SKILL.md",".agents/skills/translate-docs/SKILL.md",".agents/skills/worktree-status/SKILL.md","AGENTS.md","docs/AGENTS.md","examples/custom-tools/README.md","examples/sample-plugin/SKILL.md","examples/sample-plugin/plugin.json","packages/kaos/README.md","packages/kimi-code/README.md","packages/kosong/README.md","src/kimi_cli/agents/default/system.md","src/kimi_cli/skills/kimi-cli-help/SKILL.md","src/kimi_cli/skills/skill-creator/SKILL.md","src/kimi_cli/tools/AGENTS.md","tests_e2e/AGENTS.md"],"skills":{".agents/skills/codex-worker/SKILL.md":"---\nname: codex-worker\ndescription: Spawn and manage multiple Codex CLI agents via tmux to work on tasks in parallel. Use whenever a task can be decomposed into independent subtasks (e.g. batch triage, parallel fixes, multi-file refactors). When codex and tmux are available, prefer this over the built-in Task tool for parallelism.\n---\n\n# codex-worker\n\nOrchestrate multiple Codex CLI (`codex`) agents running in parallel, each in its\nown git worktree and tmux session.\n\n**When to use:** Whenever you identify that a task can be split into independent\nsubtasks — don't wait for the user to ask for parallelism. Examples:\n- User says \"triage all open issues updated in the last 7 days\" → fetch the\n issue list, then spawn one codex worker per issue.\n- User says \"refactor these 5 modules\" → one worker per module.\n- User says \"fix lint errors across packages\" → one worker per package.\n\n**Replaces Task tool:** When `codex` and `tmux` are available in the\nenvironment, use codex workers instead of the built-in Task (subagent) tool.\nCodex workers are full-featured agents with their own file system access, shell,\nand isolated worktree — far more capable than subagents.\n\n## Preflight check\n\n```bash\ncommand -v codex && codex login status && command -v tmux\n```\n\nAll three must succeed. The project must be a git repository.\n\n## Naming convention\n\nGit branch and worktree directory share a **task name**:\n\n```\n--\n```\n\nThe tmux session adds a `codex-worker-` prefix so workers are easy to filter:\n\n| | Format | Example |\n|---|---|---|\n| Task name | `--` | `issue-836-prompt-dollar-sign` |\n| Git branch | same as task name | `issue-836-prompt-dollar-sign` |\n| Worktree dir | `.worktrees/` | `kimi-cli.worktrees/issue-836-prompt-dollar-sign` |\n| tmux session | `codex-worker-` | `codex-worker-issue-836-prompt-dollar-sign` |\n\nMore examples:\n- `issue-518-mcp-config-isolation`\n- `fix-share-dir-skills-path`\n- `feat-ask-user-tool`\n- `refactor-jinja-templates`\n\nList only codex workers: `tmux ls | grep ^codex-worker-`\n\n## Usage\n\nPrefer tmux + interactive codex for all tasks. It supports multi-turn dialogue,\nthe user can `tmux attach` to inspect or intervene, and you can send follow-up\nprompts from outside.\n\n### Spawn a worker\n\n```bash\nNAME=\"issue-836-prompt-dollar-sign\" # task name\nSESSION=\"codex-worker-$NAME\" # tmux session name\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\n# 1. Create worktree (skip if exists)\ngit worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n\n# 2. Launch interactive codex inside tmux\ntmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n```\n\n### Send a prompt\n\nThe Codex TUI needs time to initialize before it accepts input.\nAfter launching a session, **wait at least 5 seconds** before sending\na prompt. Then send the text followed by `Enter`. If the prompt stays\nin the input field without being submitted, send an additional `Enter`.\n\n```bash\nsleep 5 # wait for Codex TUI to initialize\ntmux send-keys -t \"$SESSION\" \"Your prompt here\" Enter\n# If it doesn't submit, send another Enter:\n# tmux send-keys -t \"$SESSION\" Enter\n```\n\n### Peek at output\n\n```bash\ntmux capture-pane -t \"$SESSION\" -p | tail -30\n```\n\n### Attach for hands-on interaction\n\n```bash\ntmux attach -t \"$SESSION\"\n```\n\n### Parallel fan-out\n\n```bash\nTASKS=(\n \"issue-518-mcp-config-isolation|Triage #518: MCP config 被子 agent 继承的隔离问题。分析根因，给出修复方案。\"\n \"issue-836-prompt-dollar-sign|Triage #836: prompt 包含 $ 时启动静默失败。分析根因，给出修复方案。\"\n)\n\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\nfor entry in \"${TASKS[@]}\"; do\n NAME=\"${entry%%|*}\"\n PROMPT=\"${entry#*|}\"\n SESSION=\"codex-worker-$NAME\"\n git worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n tmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n sleep 5 # wait for Codex TUI to fully initialize\n tmux send-keys -t \"$SESSION\" \"$PROMPT\" Enter\ndone\n```\n\n### Fallback: `codex exec`\n\nOnly use `codex exec` when you explicitly don't need follow-up (e.g. CI, pure\nanalysis with `-o` output). It does not support multi-turn dialogue.\n\n```bash\ncodex exec --dangerously-bypass-approvals-and-sandbox \\\n -o \"/tmp/$NAME-result.md\" \\\n \"Your prompt here\"\n```\n\n## Lifecycle management\n\nList active workers:\n\n```bash\ntmux ls | grep ^codex-worker-\n```\n\nKill a finished worker:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\"\n```\n\nClean up worktree after merging:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\" 2>/dev/null\ngit worktree remove \"$WORKTREE_DIR/$NAME\"\ngit branch -d \"$NAME\"\n```\n\nBatch cleanup of dead sessions:\n\n```bash\ntmux list-sessions -F '#{session_name}:#{pane_dead}' \\\n | grep ':1$' \\\n | cut -d: -f1 \\\n | xargs -I{} tmux kill-session -t {}\n```\n",".agents/skills/feature-smoke-test/SKILL.md":"---\nname: feature-smoke-test\ndescription: 针对 Kimi Code CLI 的新增或变更功能，规划并执行可重复的端到端冒烟测试。从 git diff 推断功能边界，读取相关文档和代码，设计测试 prompt，以 --print 非交互模式运行本地 CLI，检查进程退出码和 session 产物，总结预期与实际行为之间的差异。发现问题时自动启动多路并行探查以定位根因。\n---\n\n冒烟测试是运行时验证，不是写完 prompt 或读完代码就结束。必须实际执行、实际检查产物。\n\n## 确定测试范围\n\n动手之前，先从代码变更推断功能边界：\n\n```sh\ngit diff main --name-only\ngit diff main --stat\n```\n\n根据变更文件集合，明确写下：\n\n- 被测的功能边界\n- 用户可感知的行为变化\n- 运行前的准备工作和运行后的清理工作\n- 能够证明成功或失败的证据\n\n如果功能涉及状态、异步、审批流或时序敏感逻辑，默认认为单条 prompt 不够。\n\n## 先读事实来源\n\n读取定义该功能真实行为的最小文件集合：\n\n- 面向用户的文档、changelog 或设计笔记\n- 暴露该功能的 agent prompt 或 tool prompt\n- 实现层入口\n- 已有测试——当测试比文档更准确地描述行为时优先看测试\n\n不要信任过时的 prompt 示例。先从代码或当前文档重建真实的工具接口。\n\n## 制定最小测试计划\n\n默认覆盖三个场景：\n\n1. 正常路径\n2. 边界条件、非法输入或容量极限\n3. 中断、重试、清理或恢复\n\n每个场景记录：\n\n- `目标`\n- `前置准备`\n- `prompt 策略`\n- `成功信号`\n- `失败信号`\n- `需要检查的产物`\n\n如果功能存在竞态条件，必须显式标注时序。用长时间运行的命令或刻意的等待来制造时序窗口，不要用\"快速再跑一个\"这种模糊说法。\n\n## 优先使用多轮 prompt\n\n默认采用多轮流程：\n\n1. 探索轮：让 agent 在阅读事实来源后复述当前真实接口\n2. 执行轮：只执行一个场景\n3. 观察轮：只读取输出、工具状态和产物文件，不扩大范围\n4. 清理轮：停止、回滚或关闭有状态资源\n\n仅对无状态的简单功能使用单轮 prompt。\n\n多轮测试时，每一轮单独调用 CLI，在两轮之间检查上一轮的输出和产物，再决定下一轮的 prompt。不要把多轮 prompt 一次性塞进 stdin——那是盲写，无法根据上一轮结果调整。\n\n测试时，显式要求 agent 先列举当前可用的工具，不要臆造历史工具名。可复用的 prompt 模板见 `references/prompt-patterns.md`。\n\n## 以非交互模式隔离运行 CLI\n\n使用 `/tmp` 下的一次性目录作为 `--work-dir`，实现 session 隔离。CLI 的 session 路径由 `~/.kimi/sessions//` 决定，不同的 work-dir 自动产生独立的 session 命名空间，不会污染正常项目的 session。认证状态保留在 `~/.kimi` 下，无需额外配置。\n\n### 环境准备\n\n```sh\nSMOKE_DIR=\"$(mktemp -d /tmp/kimi-smoke-XXXXXX)\"\n```\n\n如果功能需要仓库上下文（读取代码、git 信息等），把仓库文件复制或软链到 `SMOKE_DIR`。如果功能会编辑文件，绝不要用活跃仓库作为 work-dir。\n\n### 默认执行方式\n\n绝大多数场景使用这个模式：\n\n```sh\nuv run python -m kimi_cli.cli \\\n --print \\\n --prompt \"你的测试 prompt\" \\\n --work-dir \"$SMOKE_DIR\"\necho \"exit_code=$?\"\n```\n\n`--print` 会自动启用 `--yolo`（自动批准所有操作），适合无人值守的冒烟测试。\n\n执行后**必须先检查退出码**：非零表示 CLI 本身崩溃或超时，应优先排查进程级错误，再看 session 产物。\n\n### 备选执行模式\n\n当默认方式不满足需求时，按需选用：\n\n- **长 prompt**：通过 stdin 传入——`cat <<'PROMPT' | uv run python -m kimi_cli.cli --print --input-format text --work-dir \"$SMOKE_DIR\"`\n- **结构化输出**：加 `--output-format stream-json`，输出逐行 JSON，便于程序化解析\n- **只看最终结果**：用 `--quiet`，等价于 `--print --output-format text --final-message-only`\n\n### 注意事项\n\n- 运行过程中记录这些路径：`SMOKE_DIR`、最终 session 目录（可通过 `inspect_session.py` 定位）、功能特定的输出文件。\n\n## 刻意执行\n\n执行过程中维护一份简短的运行日志：\n\n- 使用的完整 prompt\n- 关键的工具调用或命令\n- 功能产生的 task id、输出路径或审批 id\n- 时序敏感时记录时间戳\n\n不要仅凭 assistant 的最终文本推断正确性。运行时文件和工具结果才是事实来源。\n\n## 检查 session 产物\n\n首先检查：\n\n- `~/.kimi/sessions/.../context.jsonl`\n- `~/.kimi/sessions/.../wire.jsonl`\n- 功能创建的 session 级文件\n\n使用 `scripts/inspect_session.py` 查找并汇总最新 session：\n\n```sh\nuv run python .agents/skills/feature-smoke-test/scripts/inspect_session.py --share-dir ~/.kimi\n```\n\n脚本退出码含义：0 = 正常汇总，1 = session 目录缺失或无法解析。\n\n如果功能会创建后台任务、通知或附属文件，直接检查这些文件，不要只依赖模型摘要。\n\n## 汇报结论\n\n将结果分为三类：\n\n- **已确认**的行为\n- **与预期不符**的行为\n- **仍有歧义**、需要更确定性复现的行为\n\n对于每个 bug 或回归，记录：\n\n- 触发它的 prompt\n- 精确的 session 路径\n- 证明它的产物路径\n- 能推导出的最小复现步骤\n\n## 问题探查\n\n当发现与预期不符的行为时，不要停在报告层面。启动并行探查流程定位根因：\n\n### 探查策略\n\n针对每个发现的问题，**同时启动多个独立的探查方向**（使用 Agent 工具并行执行）。根据问题的具体表现自行判断最有价值的探查角度，常见方向包括但不限于：\n\n- 从触发问题的入口沿调用链追踪实际执行路径\n- 检查输入数据经过各处理阶段后的变化\n- 检查持久化状态（session 文件、后台任务、通知记录等）是否一致\n- 运行相关单元测试和集成测试，确认测试是否覆盖了出问题的路径\n\n不必机械地覆盖所有方向。根据 session 产物中的具体异常信号，选择最可能命中根因的 2-3 个方向并行展开。\n\n### 探查输出\n\n每条探查方向独立汇报：\n\n- 探查的具体方向和范围\n- 发现的事实（附文件路径和行号）\n- 该方向的结论：已定位根因 / 已排除 / 需要进一步调查\n\n### 综合定位\n\n汇总所有探查结果后，输出：\n\n- **根因**：一句话总结问题的本质原因\n- **证据链**：从触发 prompt → 代码路径 → 出错点 → 产物表现的完整链路\n- **修复建议**：最小改动方案，附具体文件和行号\n- **回归风险**：修复后需要额外验证的相关功能\n",".agents/skills/feature-smoke-test/references/prompt-patterns.md":"# Prompt 模板\n\n以下模板作为脚手架使用。运行前替换占位符。\n\n## 单轮还是多轮\n\n满足以下任一条件时使用多轮：\n\n- 功能有状态\n- 功能依赖时序或并发\n- 功能需要审批、清理或恢复\n- session 产物本身是证据的一部分\n- 工具接口可能近期发生过变化\n\n仅对无状态的窄范围检查使用单轮。\n\n## 变量\n\n起草 prompt 前填写以下字段：\n\n- `` — 被测功能名称\n- `` — 当前场景的目标\n- `` — 需要阅读的源码路径\n- `` — 执行约束\n- `` — 成功信号\n- `` — 失败信号\n- `` — 需要检查的产物路径\n- `` — session 目录路径\n\n## 探索 prompt\n\n```text\n我要验证 。\n\n先阅读这些文件并只总结当前真实对外接口，不要假设旧文档、旧 prompt 或旧 tool 名称仍然正确：\n\n\n然后给我一个最小 smoke test 计划，只包含：\n1. happy path\n2. 一个边界/异常场景\n3. 一个清理、恢复或中断场景\n\n每个场景都写清楚目标、预期信号和要检查的产物。\n```\n\n## 执行 prompt\n\n```text\n在当前 session 里只执行这个场景：\n\n约束：\n\n\n执行前先复述你将使用的工具或命令。执行时记录关键 task id、输出片段、文件路径和任何需要后续复盘的标识符。不要扩展到其他场景。\n```\n\n## 观察 prompt\n\n```text\n现在不要继续跑新的测试。\n\n只读取并总结这次运行已经产生的状态和文件：\n\n\n请明确指出哪些证据支持了预期，哪些证据反驳了预期，哪些地方仍然不确定。\n```\n\n## 复盘 prompt\n\n```text\n请根据这个 session 目录复盘整个 smoke test：\n\n\n重点阅读 context.jsonl、wire.jsonl 和相关运行产物。输出：\n1. 实际执行流程\n2. 关键 tool 调用与结果\n3. 与预期不一致的点\n4. 最小复现步骤\n```\n\n## 兼容性校验 prompt\n\n```text\n在运行 smoke test 之前，先从提供的文档或代码中复述当前真实可用的工具及其准确名称。不要臆造旧版工具名。如果任务涉及状态或时序，将工作拆分为多轮而非一次性长回复。\n```\n",".agents/skills/gen-changelog/SKILL.md":"---\nname: gen-changelog\ndescription: Generate changelog entries for code changes.\n---\n\nGenerate changelog entries for changes on the current branch relative to `main`, then sync to the docs site.\n\n## Steps\n\n1. **Inspect**: `git log main..HEAD --oneline` + `git diff main..HEAD --stat`.\n2. **Edit root CHANGELOG**: add bullets under `## Unreleased` in `CHANGELOG.md` using the prefix table below. For changes scoped to a subpackage under `packages/` or `sdks/`, **also** update that subpackage's `CHANGELOG.md` — subpackage CHANGELOGs follow their own prefix conventions (e.g. `packages/kosong/CHANGELOG.md` uses provider prefixes like `Kimi:` / `Anthropic:`); only the root CHANGELOG follows the table below.\n3. **Sync English docs**: `node docs/scripts/sync-changelog.mjs`.\n4. **Translate to Chinese**: hand-write equivalents under `## 未发布` in `docs/zh/release-notes/changelog.md`. Use the full-width colon `：`. Follow `docs/AGENTS.md` terminology.\n5. **Breaking changes**: if any, add a section under `## Unreleased` in `docs/en/release-notes/breaking-changes.md` with **Affected** + **Migration** subsections, and under `## 未发布` in `docs/zh/release-notes/breaking-changes.md` with **受影响** + **迁移** subsections.\n\n## Entry format\n\n```\n- : — \n```\n\n- **First sentence stands alone** — readers should know after one sentence whether the bullet matters to them.\n- **One change per bullet.** No `; also`, `; and`, or nested em-dashes. Two changes = two bullets.\n- **Verb-led**: `Fix …` / `Add …` / `Switch …` / `Bump …`.\n- **User-meaningful only.** No internal refactors, test churn, or CI tweaks — except `Lib:` for SDK-facing changes.\n\n## Prefixes — pick from this list, do not invent new ones\n\n| Prefix | Scope |\n|---|---|\n| `Shell` | Interactive TUI: keys, status bar, slash commands, terminal rendering |\n| `Web` | `kimi web` |\n| `Vis` | `kimi vis` tracing visualizer |\n| `CLI` | Top-level flags, subcommands, `--print` / `--yolo` / `--afk` |\n| `ACP` | Zed / JetBrains and other ACP integrations |\n| `Core` | Agent runtime, step loop, approval, quota, turns, background tasks |\n| `Tool` | Any built-in tool; name the specific tool in the body (ReadFile, Grep, Todo, Plan, …) |\n| `Skill` | Skill discovery/loading, Flow, Loop (always singular — not `Skills:`) |\n| `MCP` | MCP server integration |\n| `Plugin` | Plugin system, `kimi plugin` subcommands |\n| `LLM` | Provider-agnostic or cross-provider; name the provider in the body (Kimi / Anthropic / OpenAI / DeepSeek …). **Do not** create per-provider prefixes |\n| `Kosong` | Changes to the `kosong` LLM abstraction layer surfaced in the root CHANGELOG (the subpackage's own CHANGELOG uses provider prefixes) |\n| `Wire` | Wire protocol events, version |\n| `Auth` | OAuth, token refresh, `/login` |\n| `Config` | Config schema, env vars |\n| `Lib` | SDK-facing API changes |\n| `Build` | Nix / Rust / Python / packaging |\n\nWhen unsure, match an existing entry of the same kind. Prefer this list; if you genuinely need a new prefix, raise it with maintainers and update this table in the same PR so the convention stays single-sourced.\n\n**Ordering**: within each version, group bullets by prefix in the order of the table above. Order within a prefix is free — keep the development order.\n\n## Highlights\n\nStarting from the next release, add `**Highlights**: …` under each version header (1–3 items most users will notice); mirror it as `**亮点**：…` in Chinese. Skip on releases that are only internal or `Lib:`. Highlights summarize — every highlighted item still needs its full bullet below. **Do not backfill historical versions.**\n",".agents/skills/gen-docs/SKILL.md":"---\nname: gen-docs\ndescription: Update Kimi Code CLI user documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n我们现在对代码库有了一些修改，请你参考最近的 git commit、staged changes、changelog.md 等的内容，根据 AGENTS.md 中的信息，必要时找到实际的代码全文，确保理解了所有变更对产品用户体验的真实改变，然后逐页、逐段地检查和更新文档内容。\n\n你应该首先确保英文 changelog 使用 `node docs/scripts/sync-changelog.mjs` 进行了同步，然后确保中文文档符合最新代码的行为，最后，使用 translate-docs skill 进行双语同步。\n",".agents/skills/gen-rust/SKILL.md":"---\nname: gen-rust\ndescription: Sync Rust implementation with Python changes (exclude UI/login) by reviewing recent changes, mapping modules, porting logic, and updating tests.\n---\n\n# gen-rust\n\nUse this skill when the user wants Rust (kagent/kosong/kaos) to stay logically identical to Python (kimi_cli/kosong/kaos), excluding UI and login/auth. This includes code and tests: Rust behavior and tests must be fully synchronized with Python changes.\n\nNote: The Rust binary is named `kagent`. User-facing CLI/output text in Rust must use `kagent`\ninstead of `kimi` to match the Rust command name.\n\n## Quick workflow\n\n1) **Build a complete change inventory**\n\nReview recent changes to understand what needs syncing:\n\n```sh\n# Check staged changes\ngit diff --cached --name-only\ngit diff --cached -- src packages\n\n# Check recent commits\ngit log --oneline -20 -- src packages\ngit diff HEAD~20..HEAD -- src packages\n\n# Review CHANGELOG.md for context\nhead -50 CHANGELOG.md\n```\n\n2) **Classify changes**\n\n- Exclude UI and login/auth changes (Shell/Print/ACP UI, login/logout commands).\n- Everything else must be mirrored in Rust.\n- Keep a small checklist: file -> change summary -> Rust target -> status.\n\n3) **Map Python -> Rust**\n\nCommon mappings:\n- `src/kimi_cli/llm.py` -> `rust/kagent/src/llm.rs`\n- `src/kimi_cli/soul/*` -> `rust/kagent/src/soul/*`\n- `src/kimi_cli/tools/*` -> `rust/kagent/src/tools/*`\n- `src/kimi_cli/utils/*` -> `rust/kagent/src/utils/*`\n- `src/kimi_cli/wire/*` -> `rust/kagent/src/wire/*`\n- `packages/kosong/*` -> `rust/kosong/*`\n- `packages/kaos/*` -> `rust/kaos/*`\n\n4) **Port logic carefully**\n\n- Match error messages and tool output text exactly (tests often assert strings).\n- Preserve output types (text vs parts) and ordering.\n- For media/tool outputs, verify ContentPart wrapping and serialization.\n- If Python adds new helper modules, mirror minimal Rust utilities.\n- Use `rg` to find existing analogs and references.\n\n5) **Update tests**\n\n- Update Rust tests that assert content/strings/parts.\n- Mirror Python unit and integration tests when they exist; add missing Rust tests so coverage matches intent.\n- Ensure E2E parity: use the existing Python E2E suite against the Rust binary by setting\n `KIMI_E2E_WIRE_CMD` (do not rewrite E2E in Rust). All E2E cases must pass or the gap must be documented.\n- Prefer targeted tests first (`cargo test -p kagent --test `), then full suite if asked.\n\n6) **Verification is mandatory**\n\n- Run the full Rust test suite and ensure all Rust tests pass.\n- Run E2E tests with the wire command swapped to Rust (set `KIMI_E2E_WIRE_CMD`), and ensure they pass.\n\n7) **Final report**\n\n- List synced files and logic.\n- Call out intentionally skipped UI/login changes.\n- List tests run and results (must include full Rust tests and Rust E2E with wire command override).\n\n## Pitfalls to avoid\n\n- Skipping `llm.py`: it often changes model capability logic.\n- Using commit message filtering instead of full diff.\n- Forgetting to update Rust tests when output text/parts change.\n- Mixing UI/login changes into core sync.\n- Leaving test parity ambiguous; always state unit/integration/E2E status.\n\n## Minimal diff checklist (template)\n\n- [ ] Recent changes reviewed (staged, commits, changelog)\n- [ ] Python diffs inspected for core logic\n- [ ] Rust mappings applied\n- [ ] Tests updated\n- [ ] Targeted tests run\n- [ ] Full Rust test suite passed\n- [ ] Rust E2E passed with `KIMI_E2E_WIRE_CMD`\n",".agents/skills/pull-request/SKILL.md":"---\nname: pull-request\ndescription: Create and submit a GitHub Pull Request.\ntype: flow\n---\n\n```mermaid\nflowchart TB\n A([\"BEGIN\"]) --> B[\"当前分支有没有 dirty change？\"]\n B -- 有 --> D([\"END\"])\n B -- 没有 --> n1[\"确保当前分支是一个不同于 main 的独立分支\"]\n n1 --> n2[\"根据当前分支相对于 main 分支的修改，push 并提交一个 PR（利用 gh 命令），用英文编写 PR 标题和 description，描述所做的更改。PR title 要符合先前的 commit message 规范（PR title 就是 squash merge 之后的 commit message）。\"]\n n2 --> D\n```\n",".agents/skills/release/SKILL.md":"---\nname: release\ndescription: Execute the release workflow for Kimi Code CLI packages.\n---\n\nRelease process for Kimi Code CLI packages. Tags are pushed without a `v` prefix and follow one of these patterns (matched by `.github/workflows/release-*.yml`):\n\n| Tag pattern | Releases |\n|---|---|\n| `1.42.0` (numeric) | `kimi-cli` (root) + `kimi-code` wrapper, released together — versions must stay aligned |\n| `kosong-0.53.0` | `packages/kosong` |\n| `pykaos-0.9.0` | `packages/kaos` (PyPI name `pykaos`) |\n| `kimi-sdk-0.3.0` | `sdks/kimi-sdk` |\n\nThe Rust implementation (`kagent`) lives in a separate repository and is **not** released from here.\n\n## Steps\n\n1. **Understand the automation.** Read `AGENTS.md` and `.github/workflows/release*.yml` so you know what each release workflow expects before changing any versions.\n\n2. **Detect changed packages.** Check each release unit under `packages/`, `sdks/`, and the repo root for changes since its last release tag. Use path-scoped diffs for subpackages so unrelated repo changes do not trigger a package release, e.g. `git diff kosong-0.53.0..HEAD -- packages/kosong`, `git diff pykaos-0.9.0..HEAD -- packages/kaos`, and `git diff kimi-sdk-0.2.1..HEAD -- sdks/kimi-sdk`. If nothing changed anywhere, stop and report that there is nothing to release. Note: `packages/kimi-code` is a thin wrapper and must stay version-synced with `kimi-cli`, so treat it as changed whenever the root package changes.\n\n3. **Confirm new versions with the user.** For each changed package, propose a new version and confirm before editing. Versioning policy:\n - Patch is always `0`.\n - Bump the minor version for any change.\n - Major only changes by explicit manual decision from the user.\n\n4. **Create the release branch.** Name it `bump--`. If multiple packages are being bumped together, use a single branch with a descriptive name.\n\n5. **Update version metadata and changelogs.** For each changed package:\n - Update its `pyproject.toml`.\n - Update `CHANGELOG.md`, keeping the `## Unreleased` header empty in place (do **not** rename it — add a new dated `## (YYYY-MM-DD)` section below it).\n - Update `breaking-changes.md` in both languages if there are breaking changes.\n - If bumping `packages/kosong` or `packages/kaos`, also update the root `pyproject.toml` pinned dependency (`kosong[contrib]==` or `pykaos==`) so root validation keeps passing.\n\n6. **Sync the `kimi-code` wrapper when the root version changes.** Bump `packages/kimi-code/pyproject.toml` `version` to match the new root version. It is a legacy stub with no dependencies — do not add a `kimi-cli` pin back.\n\n7. **Run `uv sync`** to refresh the lockfile.\n\n8. **Update docs.** Follow the `gen-docs` skill to make sure docs reflect the release.\n\n9. **Confirm with the user before opening the PR.** Summarize the staged changes and ask the user to explicitly confirm:\n - **Version numbers** — every updated `pyproject.toml` (changed package + `packages/kimi-code` if the root moved) reflects the version agreed in step 3.\n - **Dependency pins** — the root `pyproject.toml` pins (`kosong[contrib]==`, `pykaos==`) match the bumped versions.\n - **Documentation** — CHANGELOG entries are added below `## Unreleased` (Unreleased still present and empty), `breaking-changes.md` is updated in both languages if applicable, and `gen-docs` left no inconsistencies.\n\n Wait for explicit user approval before proceeding. If the user flags anything, fix it and re-confirm — do not push.\n\n10. **Open the PR.** Commit all changes, push, and open a PR with `gh`. The PR description must follow this structure (see https://github.com/MoonshotAI/kimi-cli/pull/2225 for reference):\n\n ```markdown\n ## Summary\n - Bump to \n - Move the current release notes under \n - (If applicable) Move breaking-change entries under \n - (If applicable) Any additional noteworthy changes (dependency pin updates, etc.)\n\n ## Validation\n - uv run python scripts/check_version_tag.py --pyproject --expected-version \n - (For root releases) uv run python scripts/check_version_tag.py --pyproject packages/kimi-code/pyproject.toml --expected-version \n - uv run python scripts/check_kimi_dependency_versions.py --root-pyproject pyproject.toml --kosong-pyproject packages/kosong/pyproject.toml --pykaos-pyproject packages/kaos/pyproject.toml\n - make check\n\n ## Post-merge\n After this PR lands, create and push the release tag:\n\n ```sh\n git tag \n git push origin \n ```\n ```\n\n11. **Hand off the tag step.** After merge, switch to `main`, pull latest, and tell the user the exact `git tag` command for the final release tag (pick the right tag pattern from the table above — e.g. `git tag 1.43.0` for a root release, `git tag kosong-0.54.0` for a kosong release). The user will run the tag and push tags themselves.\n\n## Stop conditions\n\nFail fast — never paper over an error to keep the release moving. Stop and report back to the user when any of these happen:\n\n- Nothing changed since the last tag → there is nothing to release.\n- `uv sync` fails or produces unexpected `uv.lock` churn beyond the version bump.\n- `gen-docs` reports a doc inconsistency you cannot resolve.\n- PR checks go red after push — investigate, do **not** `--no-verify` or force-merge.\n- The release workflow fails after tag push — read the workflow logs and surface the failure, do not retag silently.\n",".agents/skills/translate-docs/SKILL.md":"---\nname: translate-docs\ndescription: Translate and sync bilingual documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n中文文档和英文 changelog 已经确保是正确符合预期的，现在请你逐页、逐段地翻译文档内容，确保中英双语保持同步。\n\n## 翻译方向\n\n- **Changelog**: 以英文为准，翻译到中文\n- **其他所有页面**: 以中文为准，翻译到英文\n\n## 注意事项\n\n- 必要时可以参考代码文件以确保翻译的准确性\n- 要保证不同语言的表达风格、结构标记等保持一致\n- 但需要遵守两者可能不同的用词和排版偏好（主要是 sentence case、翻译对照之类的）\n",".agents/skills/worktree-status/SKILL.md":"---\nname: worktree-status\ndescription: Audit all git worktrees in the current project. Use when the user asks about worktree status, which branches are merged, which have uncommitted changes, or which worktrees can be safely cleaned up.\n---\n\n# worktree-status\n\nReport the status of every git worktree for the current project, covering\ndirty state and merge status.\n\n## When to use\n\n- User asks \"which worktrees can I clean up?\"\n- User asks \"what's the status of my worktrees / branches?\"\n- Before batch-cleaning worktrees, to avoid losing uncommitted work\n\n## Procedure\n\n### 1. Pull latest main (MANDATORY)\n\nYou MUST pull latest main before any status checks. Without this, merge\ndetection (both ancestry and content diff) will produce stale results and\nyou may mistakenly conclude a branch is not merged.\n\n```bash\ncd \"$(git rev-parse --show-toplevel)\" && git pull origin main\n```\n\n### 2. Collect worktree info\n\n```bash\nPROJECT_DIR=\"$(git rev-parse --show-toplevel)\"\n\nfor wt in $(git worktree list --porcelain | grep \"^worktree \" | sed 's/^worktree //' | grep -v \"$PROJECT_DIR$\"); do\n branch=$(git -C \"$wt\" branch --show-current 2>/dev/null)\n [ -z \"$branch\" ] && branch=\"(detached)\"\n name=$(basename \"$wt\")\n\n # dirty?\n if [ -z \"$(git -C \"$wt\" status --short 2>/dev/null)\" ]; then\n dirty=\"clean\"\n else\n dirty=\"DIRTY\"\n fi\n\n # merged into origin/main?\n # NOTE: This project uses squash merges exclusively. `git merge-base\n # --is-ancestor` does NOT detect squash-merged branches. Always follow\n # up with a content diff (step 3) for branches that appear \"not merged\".\n if [ \"$branch\" != \"(detached)\" ]; then\n if git merge-base --is-ancestor \"$branch\" origin/main 2>/dev/null; then\n merged=\"merged\"\n else\n merged=\"not merged (verify with content diff)\"\n fi\n else\n merged=\"n/a\"\n fi\n\n echo \"\"\n echo \"[$name] branch=$branch $dirty $merged\"\n if [ \"$dirty\" = \"DIRTY\" ]; then\n git -C \"$wt\" status --short 2>/dev/null | sed 's/^/ /'\n fi\ndone\n```\n\n### 3. Detect squash-merged branches (content diff)\n\nFor any branch that shows \"not merged\", check whether the branch's\nchanges are already in main. The correct method is:\n\n1. Find the files the branch actually changed (relative to merge-base).\n2. For each changed file, compare the branch version with main.\n If all files are identical, the branch was squash-merged.\n\n**⚠️ Do NOT use `git diff origin/main `** — that compares the\ntwo tips directly, so commits added to main *after* the branch diverged\nwill show up as false differences.\n\n```bash\nBRANCH=\"\"\nBASE=$(git merge-base origin/main \"$BRANCH\")\n\n# List files the branch touched\nFILES=$(git diff --name-only \"$BASE\" \"$BRANCH\")\n\n# Compare each file between branch and current main\nfor f in $FILES; do\n d=$(git diff \"$BRANCH\" origin/main -- \"$f\" | wc -l)\n if [ \"$d\" != \"0\" ]; then\n echo \"❌ $f — differs\"\n else\n echo \"✅ $f — identical in main\"\n fi\ndone\n# All ✅ = squash-merged\n```\n\n### 4. (Optional) Check for associated tmux sessions\n\nOnly run this if `tmux` is available and relevant (e.g. worktrees were\ncreated by codex-worker or similar tooling). Skip if not applicable.\n\n```bash\ntmux ls 2>/dev/null | grep -E 'codex-worker|' || true\n```\n\n### 5. Present results\n\n**Always present results as a Markdown table.** Every worktree must appear\nas a row. Never use abbreviated or prose-only summaries.\n\n| Worktree | Branch | Dirty | Merged | Can clean? |\n|---|---|---|---|---|\n| `example-wt` | `feat-foo` | ✅ clean | ✅ squash-merged | ✅ |\n| `another-wt` | `fix-bar` | ⚠️ 3 files | ❌ not merged | ❌ dirty + not merged |\n| `detached-wt` | (detached) | ⚠️ 14 files | n/a | ❌ has uncommitted changes |\n\nColumn definitions:\n\n- **Dirty**: `✅ clean` or `⚠️ N files`\n- **Merged**: `✅ merged` / `✅ squash-merged` (confirmed via content diff) / `❌ not merged` / `n/a`\n- **Can clean?**: `✅` only when merged (or squash-merged) AND clean\n\nAdd extra columns (e.g. tmux session, notes) only when relevant.\n\n### 6. Cleanup (only when asked)\n\nOnly clean worktrees the user explicitly approves. For each:\n\n```bash\nNAME=\"\"\ngit worktree remove \"/path/to/$NAME\"\ngit branch -D \"\" # only if the branch is no longer needed\n```\n","AGENTS.md":"# Kimi Code CLI\n\n## Quick commands (use uv)\n\n- `make prepare` (sync deps for all workspace packages and install git hooks)\n- `make format`\n- `make check`\n- `make test`\n- `make ai-test`\n- `make build` / `make build-bin`\n\nIf running tools directly, use `uv run ...`.\n\n## Project overview\n\nKimi Code CLI is a Python CLI agent for software engineering workflows. It supports an interactive\nshell UI, ACP server mode for IDE integrations, and MCP tool loading.\n\n## Tech stack\n\n- Python 3.12+ (tooling configured for 3.14)\n- CLI framework: Typer\n- Async runtime: asyncio\n- LLM framework: kosong\n- MCP integration: fastmcp\n- Logging: loguru\n- Package management/build: uv + uv_build; PyInstaller for binaries\n- Tests: pytest + pytest-asyncio; lint/format: ruff; types: pyright + ty\n\n## Architecture overview\n\n- **CLI entry**: `src/kimi_cli/cli/__init__.py` (Typer) parses flags (UI mode, agent spec, config, MCP)\n and routes into `KimiCLI` in `src/kimi_cli/app.py`.\n- **App/runtime setup**: `KimiCLI.create` loads config (`src/kimi_cli/config.py`), chooses a\n model/provider (`src/kimi_cli/llm.py`), builds a `Runtime` (`src/kimi_cli/soul/agent.py`),\n loads an agent spec, restores `Context`, then constructs `KimiSoul`.\n- **Agent specs**: YAML under `src/kimi_cli/agents/` loaded by `src/kimi_cli/agentspec.py`.\n Specs can `extend` base agents, select tools by import path, and register builtin subagent\n types via the `subagents` field. Subagent instances are persisted separately under the session\n directory and can be resumed by `agent_id`. System prompts live alongside specs; builtin args\n include `KIMI_NOW`, `KIMI_WORK_DIR`, `KIMI_WORK_DIR_LS`, `KIMI_AGENTS_MD`, `KIMI_SKILLS`, `KIMI_OS`, `KIMI_SHELL`\n (this file is injected via `KIMI_AGENTS_MD`).\n- **Tooling**: `src/kimi_cli/soul/toolset.py` loads tools by import path, injects dependencies,\n and runs tool calls. Built-in tools live in `src/kimi_cli/tools/` (agent, shell, file, web,\n todo, background, dmail, think, plan). MCP tools are loaded via `fastmcp`; CLI management is\n in `src/kimi_cli/mcp.py` and stored in the share dir.\n- **Subagents**: `LaborMarket` in `src/kimi_cli/soul/agent.py` registers builtin subagent types.\n The `Agent` tool (`src/kimi_cli/tools/agent/`) creates or resumes subagent instances, while\n `SubagentStore` persists instance metadata, prompts, wire logs, and context under\n `session/subagents//`.\n- **Core loop**: `src/kimi_cli/soul/kimisoul.py` is the main agent loop. It accepts user input,\n handles slash commands (`src/kimi_cli/soul/slash.py`), appends to `Context`\n (`src/kimi_cli/soul/context.py`), calls the LLM (kosong), runs tools, and performs compaction\n (`src/kimi_cli/soul/compaction.py`) when needed.\n- **Approvals**: `src/kimi_cli/soul/approval.py` is the tool-facing facade. `ApprovalRuntime`\n in `src/kimi_cli/approval_runtime/` is the session-level source of truth for pending approvals,\n and approval requests are projected onto the root wire stream for Shell/Web style UIs.\n- **UI/Wire**: `src/kimi_cli/soul/run_soul` connects `KimiSoul` to a `Wire`\n (`src/kimi_cli/wire/`) so UI loops can stream events. UIs live in `src/kimi_cli/ui/`\n (shell/print/acp/wire).\n- **Shell UI**: `src/kimi_cli/ui/shell/` handles interactive TUI input, shell command mode,\n and slash command autocomplete; it is the default interactive experience.\n- **Slash commands**: Soul-level commands live in `src/kimi_cli/soul/slash.py`; shell-level\n commands live in `src/kimi_cli/ui/shell/slash.py`. The shell UI exposes both and dispatches\n based on the registry. Standard skills register `/skill:` and load `SKILL.md`\n as a user prompt; flow skills register `/flow:` and execute the embedded flow.\n\n## Major modules and interfaces\n\n- `src/kimi_cli/app.py`: `KimiCLI.create(...)` and `KimiCLI.run(...)` are the main programmatic\n entrypoints; this is what UI layers use.\n- `src/kimi_cli/soul/agent.py`: `Runtime` (config, session, builtins), `Agent` (system prompt +\n toolset), and `LaborMarket` (builtin subagent type registry).\n- `src/kimi_cli/soul/kimisoul.py`: `KimiSoul.run(...)` is the loop boundary; it emits Wire\n messages and executes tools via `KimiToolset`.\n- `src/kimi_cli/soul/context.py`: conversation history + checkpoints; used by DMail for\n checkpointed replies.\n- `src/kimi_cli/soul/toolset.py`: load tools, run tool calls, bridge to MCP tools.\n- `src/kimi_cli/ui/*`: shell/print/acp frontends; they consume `Wire` messages.\n- `src/kimi_cli/wire/*`: event types and transport used between soul and UI.\n\n## Repo map\n\n- `src/kimi_cli/agents/`: built-in agent YAML specs and prompts\n- `src/kimi_cli/prompts/`: shared prompt templates\n- `src/kimi_cli/soul/`: core runtime/loop, context, compaction, approvals\n- `src/kimi_cli/tools/`: built-in tools\n- `src/kimi_cli/ui/`: UI frontends (shell/print/acp/wire)\n- `src/kimi_cli/acp/`: ACP server components\n- `packages/kosong/`, `packages/kaos/`: workspace deps\n + Kosong is an LLM abstraction layer designed for modern AI agent applications.\n It unifies message structures, asynchronous tool orchestration, and pluggable\n chat providers so you can build agents with ease and avoid vendor lock-in.\n + PyKAOS is a lightweight Python library providing an abstraction layer for agents\n to interact with operating systems. File operations and command executions via KAOS\n can be easily switched between local environment and remote systems over SSH.\n- `tests/`, `tests_ai/`: test suites\n- `klips`: Kimi Code CLI Improvement Proposals\n\n## Conventions and quality\n\n- Python >=3.12 (ty config uses 3.14); line length 100.\n- Ruff handles lint + format (rules: E, F, UP, B, SIM, I); pyright + ty for type checks.\n- Tests use pytest + pytest-asyncio; files are `tests/test_*.py`.\n- CLI entry points: `kimi` / `kimi-cli` -> `src/kimi_cli/__main__.py` (routes to `src/kimi_cli/cli/__init__.py`).\n- User config: `~/.kimi/config.toml`; logs, sessions, and MCP config live in `~/.kimi/`.\n\n## Git commit messages\n\nConventional Commits format:\n\n```\n(): \n```\n\nAllowed types:\n`feat`, `fix`, `test`, `refactor`, `chore`, `style`, `docs`, `perf`, `build`, `ci`, `revert`.\n\n## Versioning\n\nThe project follows a **minor-bump-only** versioning scheme (`MAJOR.MINOR.PATCH`):\n\n- **Patch** version is always `0`. Never bump it.\n- **Minor** version is bumped for any change: new features, improvements, bug fixes, etc.\n- **Major** version is only changed by explicit manual decision; it stays unchanged during\n normal development.\n\nExamples: `0.68.0` → `0.69.0` → `0.70.0`; never `0.68.1`.\n\nThis rule applies to all packages in the repo (root, `packages/*`, `sdks/*`) as well as release\nand skill workflows.\n\n## Release workflow\n\nFor the full procedure, follow the `release` skill (`.agents/skills/release/SKILL.md`). The summary:\n\n1. Ensure `main` is up to date (pull latest).\n2. Create a release branch, e.g. `bump-0.68` or `bump-pykaos-0.5.3`.\n3. Update `CHANGELOG.md`: add a new `## 0.68 (YYYY-MM-DD)` section below `## Unreleased` (do not rename `## Unreleased`).\n4. Update `pyproject.toml` version.\n5. Run `uv sync` to align `uv.lock`.\n6. Commit the branch and open a PR.\n7. Merge the PR, then switch back to `main` and pull latest.\n8. Tag and push:\n - `git tag 0.68` or `git tag pykaos-0.5.3`\n - `git push --tags`\n9. GitHub Actions handles the release after tags are pushed.\n","docs/AGENTS.md":"# Documentation Agent Guide\n\nThis repository uses VitePress for the documentation site. The current docs are structural scaffolds only; everything beyond the headings is placeholder guidance. The `Reference Code` blocks are there to guide future writing and should be removed once the docs are complete.\n\n## Structure\n\n- Locales live under `docs/en/` and `docs/zh/` with mirrored paths and filenames.\n- Main sections (nav + sidebar) are:\n - Guides: getting-started, use-cases, interaction, sessions, ides, integrations\n - Customization: mcp, skills, agents, print-mode, wire-mode\n - Configuration: config-files, providers, overrides, env-vars, data-locations\n - Reference: kimi-command, kimi-acp, kimi-mcp, slash-commands, keyboard, tools, exit-codes\n - FAQ: setup, interaction, acp, mcp, print-wire, updates\n - Release notes: changelog, breaking-changes\n- Navigation and sidebar are defined in `docs/.vitepress/config.ts`. Any new or renamed page must be wired there for both locales.\n\n## Source of truth\n\n- **Changelog page**: The English version (`docs/en/release-notes/changelog.md`) is the source of truth. It is auto-synced from the root `CHANGELOG.md` via script. The Chinese changelog should be translated from the English version.\n- **All other pages**: The Chinese version (`docs/zh/`) is the source of truth. English translations should be based on the Chinese docs.\n\nOnly the Chinese documentation and the English changelog are manually reviewed. Other translations (e.g., English versions of non-changelog pages) may be auto-generated by AI agents.\n\n## Authoring workflow\n\n- Each page is a scaffold: expand the bullets into prose while keeping the section ordering, and keep the `::: info Reference Code` blocks aligned with the relevant section.\n- For changelog: edit the root `CHANGELOG.md`, then run `npm run sync` to update the English docs.\n- For other pages: edit the Chinese version first, then translate to English.\n\n## Naming conventions\n\n- Filenames are kebab-case and mirror across locales (same slug in `docs/en/` and `docs/zh/`).\n- Use consistent section labels that match the sidebar titles.\n- Use backticks for flags, commands, subcommands, command arguments, file paths, code identifiers, type names, field names, field values, and keyboard shortcuts.\n\n## Wording conventions\n\n- Do not change H1 titles or nav/sidebar labels.\n- English H2+ headings use sentence case (only the first word capitalized unless it is a proper noun). Treat \"Wire\" as a proper noun; do not treat \"agent\", \"shell mode\", or \"print mode\" as proper nouns.\n- Chinese H2+ headings keep English words in sentence case; preserve proper nouns listed in the term table below.\n- Use `API key` in English and `API 密钥` in Chinese; keep `JSON`, `JSONL`, `OAuth`, `macOS`, and `uv` as-is.\n- Use straight double quotes with spaces for quoted content: `\"被引内容\"` (not curly quotes). Add a space before and after the quoted text when adjacent to CJK characters. Use corner brackets `「」` for special terms (e.g., `「工具」`, `「会话」`).\n- Prefer \"终端\" over \"命令行\" in Chinese when both are applicable (e.g., \"运行在终端中\", \"终端界面\", \"终端操作\").\n- Use \"工具调用\" / \"tool call\", not \"工具使用\" / \"tool use\".\n- Use inline code for tool names (e.g., `Task`, `ReadFile`, `Shell`).\n\nTerm mapping (Chinese <-> English, and proper noun handling):\n\n| Chinese | English | Proper noun (zh) | Proper noun (en) |\n| --- | --- | --- | --- |\n| Agent | agent | yes | no |\n| Shell | shell | yes | no |\n| Shell 模式 | shell mode | yes | no |\n| Print 模式 | print mode | yes | no |\n| Wire 模式 | Wire mode | yes | yes (Wire) |\n| Thinking 模式 | thinking mode | yes | no |\n| MCP | MCP | yes | yes |\n| ACP | ACP | yes | yes |\n| Kimi Code CLI | Kimi Code CLI | yes | yes |\n| Agent Skills | Agent Skills | yes | yes |\n| Skill | skill | yes | no |\n| 系统提示词 | system prompt | no | no |\n| 提示词 | prompt | no | no |\n| 会话 | session | no | no |\n| 上下文 | context | no | no |\n| 子 Agent | subagent | yes (Agent) | no |\n| API 密钥 | API key | yes | no |\n| JSON | JSON | yes | yes |\n| JSONL | JSONL | yes | yes |\n| OAuth | OAuth | yes | yes |\n| macOS | macOS | yes | yes |\n| uv | uv | yes | yes |\n| 审批请求 | approval request | no | no |\n| 斜杠命令 | slash command | no | no |\n| 工具调用 | tool call | no | no |\n| Frontmatter | frontmatter | yes | no |\n| User 消息 | user message | yes (User) | no |\n| Assistant 消息 | assistant message | yes (Assistant) | no |\n| Tool 消息 | tool message | yes (Tool) | no |\n| 轮次 | turn | no | no |\n| 供应商 | provider | no | no |\n| Prompt Flow | Prompt Flow | yes | yes |\n| Ralph 循环 | Ralph Loop | yes | yes |\n| Diff | diff | yes | no |\n\nJetBrains IDE terminology (Chinese UI translations):\n\n| English | Chinese |\n| --- | --- |\n| AI Chat | AI 聊天 |\n| Registry | 注册表 |\n| Configure ACP agents | (未翻译) |\n\n## Typography\n\n- **Spacing around mixed content**: Add a space between Chinese characters and English words, numbers, inline code, or links. Exception: no space before full-width punctuation.\n - ✓ 在 Python 中使用 \\`class\\` 关键字\n - ✗ 在Python中使用\\`class\\`关键字\n - ✓ 详见 \\[配置文件\\](./config.md)。\n - ✗ 详见\\[配置文件\\](./config.md)。\n- **Full-width punctuation**: Use full-width punctuation in Chinese text: `，。；：？！（）` not `, . ; : ? ! ( )`.\n- **Code block language**: Always specify language for fenced code blocks (e.g., ` ```sh `, ` ```toml `, ` ```json `). Exception: natural language examples (user prompts) may omit the language.\n- **Callout titles**: Use short category titles for callout blocks (`::: tip`, `::: warning`, `::: info`, `::: danger`). Put the detailed description in the block content, not the title.\n - Chinese: use `提示` for tip, `注意` for warning, `说明` for info, `警告` for danger.\n - English: use no title or short words like `Note` for warning.\n - ✓ `::: tip 提示` + content starting with the key point\n - ✓ `::: warning 注意` + content `\\`KIMI_SHARE_DIR\\` 不影响 Skills 的搜索路径。...`\n - ✗ `::: warning 不影响 Skills` (title too long, should be in content)\n - ✗ `::: tip Skills 路径独立于 KIMI_SHARE_DIR` (title too long)\n- **Version info blocks**: For version change callouts, use `::: info` with a category title (Added/Changed/Removed in English; 新增/变更/移除 in Chinese). The content should be a complete sentence.\n - ✓ `::: info 新增` + content `新增于 Wire 1.2。`\n - ✗ `::: info 新增于 Wire 1.2` (title too long)\n - ✓ `::: info Changed` + content `Renamed in Wire 1.1. ...`\n - ✗ `::: info Renamed in Wire 1.1` (title too long)\n\n## Writing style\n\n- **Natural narrative**: Organize content like writing an article, guiding readers smoothly through the material.\n- **Avoid fragmentation**: Don't turn every point into a subheading; use paragraph transitions instead.\n- **Global perspective**: \"Getting Started\" introduces core concepts only; detailed usage belongs in later pages.\n- **Progressive depth**: Guides → Customization → Configuration → Reference, information deepens gradually.\n- **No \"next steps\"**: VitePress already provides prev/next navigation; don't add manual `::: tip 接下来` blocks at page end.\n\n### Example: good vs bad\n\nOutline prompt:\n\n```\n* Install and upgrade\n * System requirements: Python 3.12+, recommend uv\n * Install, upgrade, uninstall steps\n```\n\n**Bad** (mechanical conversion to headings):\n\n```markdown\n## Install and upgrade\n\n### System requirements\n\n- Python 3.12+\n- Recommend uv\n\n### Install\n\n...\n\n### Upgrade\n\n...\n```\n\n**Good** (natural narrative):\n\n```markdown\n## Install and upgrade\n\nKimi Code CLI requires Python 3.12+. We recommend using uv for installation and management.\n\nIf you haven't installed uv yet, please refer to the uv installation docs first. Install Kimi Code CLI:\n\n(code block)\n\nVerify the installation:\n\n(code block)\n\nUpgrade to the latest version:\n\n(code block)\n```\n\n## Build and preview\n\n- Docs are built with VitePress from `docs/`.\n- Common commands (run inside `docs/`):\n - `npm install` (or `bun install` if you use bun)\n - `npm run dev`\n - `npm run build`\n - `npm run preview`\n- The build output is `docs/.vitepress/dist`.\n\n## Changelog syncing\n\nThe English changelog (`docs/en/release-notes/changelog.md`) is auto-generated from the root `CHANGELOG.md`. Do not edit it manually.\n\n- The sync script is `docs/scripts/sync-changelog.mjs`.\n- It runs automatically before `npm run dev` and `npm run build`.\n- To run manually: `npm run sync` (from the `docs/` directory).\n- The script converts title format (`## [0.69] - 2025-12-29` → `## 0.69 (2025-12-29)`) and removes HTML comments.\n","examples/custom-tools/README.md":"# Example: Custom Tools\n\nThis example demonstrates how to write custom tools for Kimi Code CLI and add them to your agent spec file.\n\n```sh\ncd examples/custom-tools\nuv sync --reinstall\nuv run main.py\n```\n","examples/sample-plugin/SKILL.md":"---\nname: sample-plugin\ndescription: |\n Sample plugin demonstrating the Skills + Tools model.\n Includes a Python tool (greeting) and a TypeScript tool (calculator).\n---\n\n# Sample Plugin\n\nA demo plugin with two tools in different languages, showing that plugin tools are language-agnostic.\n\n## Tools\n\n| Tool | Language | Description |\n|------|----------|-------------|\n| `py_greet` | Python | Generate a greeting in en/zh/ja |\n| `ts_calc` | TypeScript | Evaluate a math expression |\n\n## Usage\n\n- \"greet Alice in Chinese\" -> use `py_greet` with name=\"Alice\", lang=\"zh\"\n- \"what is 42 * 17 + 3\" -> use `ts_calc` with expression=\"42 * 17 + 3\"\n","examples/sample-plugin/plugin.json":"{\n \"name\": \"sample-plugin\",\n \"version\": \"1.0.0\",\n \"description\": \"Sample plugin demonstrating Skills + Tools with both Python and TypeScript tools\",\n \"tools\": [\n {\n \"name\": \"py_greet\",\n \"description\": \"Generate a greeting message (Python tool)\",\n \"command\": [\"python3\", \"scripts/greet.py\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Name to greet\"\n },\n \"lang\": {\n \"type\": \"string\",\n \"enum\": [\"en\", \"zh\", \"ja\"],\n \"description\": \"Language: en=English, zh=Chinese, ja=Japanese\"\n }\n },\n \"required\": [\"name\"]\n }\n },\n {\n \"name\": \"ts_calc\",\n \"description\": \"Evaluate a math expression and return the result (TypeScript tool)\",\n \"command\": [\"npx\", \"tsx\", \"scripts/calc.ts\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"expression\": {\n \"type\": \"string\",\n \"description\": \"Math expression to evaluate, e.g. '2 + 3 * 4'\"\n }\n },\n \"required\": [\"expression\"]\n }\n }\n ]\n}\n","packages/kaos/README.md":"# PyKAOS\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nPyKAOS is a lightweight Python library providing an abstraction layer for agents to interact with operating systems. File operations and command executions via KAOS can be easily switched between local environment and remote systems over SSH.\n","packages/kimi-code/README.md":"# kimi-code (PyPI): legacy package, archived\n\n> [!CAUTION]\n> **This PyPI package is NOT the new Kimi Code CLI.** It is a legacy alias of the archived Python [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) and is no longer maintained.\n>\n> PyPI 上的 `kimi-code` 是已归档的旧版 Python Kimi CLI 的别名包，**不是**新版 Kimi Code CLI。\n\n## Install the new Kimi Code CLI\n\n```sh\n# macOS / Linux\ncurl -fsSL https://code.kimi.com/kimi-code/install.sh | bash\n```\n\n```powershell\n# Windows (PowerShell)\nirm https://code.kimi.com/kimi-code/install.ps1 | iex\n```\n\nAlso available via Homebrew (`brew install kimi-code`) and npm (`npm install -g @moonshot-ai/kimi-code`).\n\nThen uninstall this package: `uv tool uninstall kimi-code` (or `pip uninstall kimi-code kimi-cli`, since pip does not remove the legacy `kimi-cli` dependency automatically).\n\nMigration guide: [English](https://moonshotai.github.io/kimi-code/en/guides/migration) | [中文](https://moonshotai.github.io/kimi-code/zh/guides/migration)\n\n## Note for existing users\n\nStarting from 1.51.0, running `kimi-code` from this package only prints the instructions above. The legacy CLI it used to install is no longer supported and will stop working, so please migrate to Kimi Code CLI.\n","packages/kosong/README.md":"# Kosong\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nKosong is an LLM abstraction layer designed for modern AI agent applications. It unifies message structures, asynchronous tool orchestration, and pluggable chat providers so you can build agents with ease and avoid vendor lock-in.\n\n> Kosong means \"empty\" in Malay and Indonesian.\n\n## Installation\n\nKosong requires Python 3.12 or higher. We recommend using uv as the package manager.\n\nInit your project with:\n\n```bash\nuv init --python 3.12 # or higher\n```\n\nThen add Kosong as a dependency:\n\n```bash\nuv add kosong\n```\n\nTo enable chat providers other than Kimi (e.g. Anthropic and Google Gemini), install the optional extra:\n\n```bash\nuv add 'kosong[contrib]'\n```\n\n## Examples\n\n### Simple chat completion\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Streaming output\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider import StreamedMessagePart\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n def output(message_part: StreamedMessagePart):\n print(message_part)\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n on_message_part=output,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Tool calling with `kosong.step`\n\n```python\nimport asyncio\n\nfrom pydantic import BaseModel\n\nimport kosong\nfrom kosong import StepResult\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\nfrom kosong.tooling import CallableTool2, ToolOk, ToolReturnValue\nfrom kosong.tooling.simple import SimpleToolset\n\n\nclass AddToolParams(BaseModel):\n a: int\n b: int\n\n\nclass AddTool(CallableTool2[AddToolParams]):\n name: str = \"add\"\n description: str = \"Add two integers.\"\n params: type[AddToolParams] = AddToolParams\n\n async def __call__(self, params: AddToolParams) -> ToolReturnValue:\n return ToolOk(output=str(params.a + params.b))\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n toolset = SimpleToolset()\n toolset += AddTool()\n\n history = [\n Message(role=\"user\", content=\"Please add 2 and 3 with the add tool.\"),\n ]\n\n result: StepResult = await kosong.step(\n chat_provider=kimi,\n system_prompt=\"You are a precise math tutor.\",\n toolset=toolset,\n history=history,\n )\n print(result.message)\n print(await result.tool_results())\n\n\nasyncio.run(main())\n```\n\n## Builtin Demo\n\nKosong comes with a builtin demo agent that you can run locally. To start the demo, run:\n\n```sh\nexport KIMI_BASE_URL=\"https://api.moonshot.ai/v1\"\nexport KIMI_API_KEY=\"your_kimi_api_key\"\n\nuv run python -m kosong kimi --with-bash\n```\n\n## Development\n\nTo set up a development environment, clone the repository and install the dependencies:\n\n```bash\ngit clone https://github.com/MoonshotAI/kosong.git\ncd kosong\nuv sync --all-extras\n\nmake check # run lint and type checks\nmake test # run tests\nmake format # format code\n```\n","src/kimi_cli/agents/default/system.md":"You are Kimi Code CLI, an interactive general AI agent running on a user's computer.\n\nYour primary goal is to help users with software engineering tasks by taking action — use the tools available to you to make real changes on the user's system. You should also answer questions when asked. Always adhere strictly to the following system instructions and the user's requirements.\n\n${ROLE_ADDITIONAL}\n\n# Prompt and Tool Use\n\nThe user's messages may contain questions and/or task descriptions in natural language, code snippets, logs, file paths, or other forms of information. Read them, understand them and do what the user requested. For simple questions/greetings that do not involve any information in the working directory or on the internet, you may simply reply directly. For anything else, default to taking action with tools. When the request could be interpreted as either a question to answer or a task to complete, treat it as a task.\n\nWhen handling the user's request, if it involves creating, modifying, or running code or files, you MUST use the appropriate tools (e.g., `WriteFile`, `Shell`) to make actual changes — do not just describe the solution in text. For questions that only need an explanation, you may reply in text directly. When calling tools, do not provide explanations because the tool calls themselves should be self-explanatory. You MUST follow the description of each tool and its parameters when calling tools.\n\nIf the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. The tool can either start a new instance or resume an existing one by `agent_id`. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context because a newly created subagent instance does not automatically see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it instead of creating a new instance. Default to foreground subagents. Use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes, and you do not need the result immediately to decide your next step.\n\nYou have the capability to output any number of tool calls in a single response. If you anticipate making multiple non-interfering tool calls, you are HIGHLY RECOMMENDED to make them in parallel to significantly improve efficiency. This is very important to your performance.\n\nThe results of the tool calls will be returned to you in a tool message. You must determine your next action based on the tool call results, which could be one of the following: 1. Continue working on the task, 2. Inform the user that the task is completed or has failed, or 3. Ask the user for more information.\n\nThe system may insert information wrapped in `` tags within user or tool messages. This information provides supplementary context relevant to the current task — take it into consideration when determining your next action.\n\nTool results and user messages may also include `` tags. Unlike `` tags, these are **authoritative system directives** that you MUST follow. They bear no direct relation to the specific tool results or user messages in which they appear. Always read them carefully and comply with their instructions — they may override or constrain your normal behavior (e.g., restricting you to read-only actions during plan mode).\n\nIf the `Shell`, `TaskList`, `TaskOutput`, and `TaskStop` tools are available and you are the root agent, you can use Background Bash for long-running shell commands. Launch it via `Shell` with `run_in_background=true` and a short `description`. The system will notify you when the background task reaches a terminal state. Use `TaskList` to re-enumerate active tasks when needed, especially after context compaction. Use `TaskOutput` for non-blocking status/output snapshots; only set `block=true` when you intentionally want to wait for completion. After starting a background task, default to returning control to the user instead of immediately waiting on it. Use `TaskStop` only when you need to cancel the task. For human users in the interactive shell, the only task-management slash command is `/task`. Do not tell users to run `/task list`, `/task output`, `/task stop`, `/tasks`, or any other invented slash subcommands. If you are a subagent or these tools are not available, do not assume you can create or control background tasks.\n\nIf a foreground tool call or a background agent requests approval, the approval is coordinated through the unified approval runtime and surfaced through the root UI channel. Do not assume approvals are local to a single subagent turn.\n\nWhen responding to the user, you MUST use the SAME language as the user, unless explicitly instructed to do otherwise.\n\n# General Guidelines for Coding\n\nWhen building something from scratch, you should:\n\n- Understand the user's requirements.\n- Ask the user for clarification if there is anything unclear.\n- Design the architecture and make a plan for the implementation.\n- Write the code in a modular and maintainable way.\n\nAlways use tools to implement your code changes:\n\n- Use `WriteFile` to create or overwrite source files. Code that only appears in your text response is NOT saved to the file system and will not take effect.\n- Use `Shell` to run and test your code after writing it.\n- Iterate: if tests fail, read the error, fix the code with `WriteFile` or `StrReplaceFile`, and re-test with `Shell`.\n\nWhen working on an existing codebase, you should:\n\n- Understand the codebase by reading it with tools (`ReadFile`, `Glob`, `Grep`) before making changes. Identify the ultimate goal and the most important criteria to achieve the goal.\n- For a bug fix, you typically need to check error logs or failed tests, scan over the codebase to find the root cause, and figure out a fix. If user mentioned any failed tests, you should make sure they pass after the changes.\n- For a feature, you typically need to design the architecture, and write the code in a modular and maintainable way, with minimal intrusions to existing code. Add new tests if the project already has tests.\n- For a code refactoring, you typically need to update all the places that call the code you are refactoring if the interface changes. DO NOT change any existing logic especially in tests, focus only on fixing any errors caused by the interface changes.\n- Make MINIMAL changes to achieve the goal. This is very important to your performance.\n- Follow the coding style of existing code in the project.\n- For broader codebase exploration and deep research, use the `Agent` tool with `subagent_type=\"explore\"`. This is a fast, read-only agent specialized for searching and understanding codebases. Use it when your task will clearly require more than 3 search queries, or when you need to investigate multiple files and patterns. You can launch multiple explore agents concurrently to investigate independent questions in parallel.\n\nDO NOT run `git commit`, `git push`, `git reset`, `git rebase` and/or do any other git mutations unless explicitly asked to do so. Ask for confirmation each time when you need to do git mutations, even if the user has confirmed in earlier conversations.\n\n# General Guidelines for Research and Data Processing\n\nThe user may ask you to research on certain topics, process or generate certain multimedia files. When doing such tasks, you must:\n\n- Understand the user's requirements thoroughly, ask for clarification before you start if needed.\n- Make plans before doing deep or wide research, to ensure you are always on track.\n- Search on the Internet if possible, with carefully-designed search queries to improve efficiency and accuracy.\n- Use proper tools or shell commands or Python packages to process or generate images, videos, PDFs, docs, spreadsheets, presentations, or other multimedia files. Detect if there are already such tools in the environment. If you have to install third-party tools/packages, you MUST ensure that they are installed in a virtual/isolated environment.\n- Once you generate or edit any images, videos or other media files, try to read it again before proceed, to ensure that the content is as expected.\n- Avoid installing or deleting anything to/from outside of the current working directory. If you have to do so, ask the user for confirmation.\n\n# Working Environment\n\n## Operating System\n\nYou are running on **${KIMI_OS}**. The Shell tool executes commands using **${KIMI_SHELL}**.{% if KIMI_OS == \"Windows\" %} Use Unix shell syntax inside Shell commands — `/dev/null` not `NUL`, forward slashes in paths (backslashes are escape characters in bash).{% endif +%}\n\nThe operating environment is not in a sandbox. Any actions you do will immediately affect the user's system. So you MUST be extremely cautious. Unless being explicitly instructed to do so, you should never access (read/write/execute) files outside of the working directory.\n\n## Date and Time\n\nThe current date and time in ISO format is `${KIMI_NOW}`. This is only a reference for you when searching the web, or checking file modification time, etc. If you need the exact time, use Shell tool with proper command.\n\n## Working Directory\n\nThe current working directory is `${KIMI_WORK_DIR}`. This should be considered as the project root if you are instructed to perform tasks on the project. Every file system operation will be relative to the working directory if you do not explicitly specify the absolute path. Tools may require absolute paths for some parameters, IF SO, YOU MUST use absolute paths for these parameters.\n\nThe directory listing of current working directory is:\n\n```\n${KIMI_WORK_DIR_LS}\n```\n\nUse this as your basic understanding of the project structure. The tree only shows the first two levels; entries marked \"... and N more\" indicate additional contents — use Glob or Shell to explore further.\n{% if KIMI_ADDITIONAL_DIRS_INFO %}\n\n## Additional Directories\n\nThe following directories have been added to the workspace. You can read, write, search, and glob files in these directories as part of your workspace scope.\n\n${KIMI_ADDITIONAL_DIRS_INFO}\n{% endif %}\n\n# Project Information\n\nMarkdown files named `AGENTS.md` usually contain the background, structure, coding styles, user preferences and other relevant information about the project. You should use this information to understand the project and the user's preferences. `AGENTS.md` files may exist at different locations in the project, but typically there is one in the project root.\n\n> Why `AGENTS.md`?\n>\n> `README.md` files are for humans: quick starts, project descriptions, and contribution guidelines. `AGENTS.md` complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.\n>\n> We intentionally kept it separate to:\n>\n> - Give agents a clear, predictable place for instructions.\n> - Keep `README`s concise and focused on human contributors.\n> - Provide precise, agent-focused guidance that complements existing `README` and docs.\n\nThe `AGENTS.md` instructions (merged from all applicable directories):\n\n`````````\n${KIMI_AGENTS_MD}\n`````````\n\n`AGENTS.md` files can appear at any level of the project directory tree, including inside `.kimi/` directories. Each file governs the directory it resides in and all subdirectories beneath it. When multiple `AGENTS.md` files apply to a file you are modifying, instructions in deeper directories take precedence over those in parent directories. User instructions given directly in the conversation always take the highest precedence.\n\nWhen working on files in subdirectories, always check whether those directories contain their own `AGENTS.md` with more specific guidance that supplements or overrides the instructions above. You may also check `README`/`README.md` files for more information about the project.\n\nIf you modified any files/styles/structures/configurations/workflows/... mentioned in `AGENTS.md` files, you MUST update the corresponding `AGENTS.md` files to keep them up-to-date.\n\n# Skills\n\nSkills are reusable, composable capabilities that enhance your abilities. Each skill is a self-contained directory with a `SKILL.md` file that contains instructions, examples, and/or reference material.\n\n## What are skills?\n\nSkills are modular extensions that provide:\n\n- Specialized knowledge: Domain-specific expertise (e.g., PDF processing, data analysis)\n- Workflow patterns: Best practices for common tasks\n- Tool integrations: Pre-configured tool chains for specific operations\n- Reference material: Documentation, templates, and examples\n\n## Available skills\n\nSkills are grouped by scope (`Project`, `User`, `Extra`, `Built-in`) so you can tell where each came from. When the user refers to \"the skill in this project\" or \"the user-scope skill\", use the scope heading to disambiguate. When multiple scopes define a skill with the same name, the more specific scope takes precedence: **Project overrides User overrides Extra overrides Built-in**.\n\n${KIMI_SKILLS}\n\n## How to use skills\n\nIdentify the skills that are likely to be useful for the tasks you are currently working on, read the `SKILL.md` file for detailed instructions, guidelines, scripts and more.\n\nOnly read skill details when needed to conserve the context window.\n\n# Ultimate Reminders\n\nAt any time, you should be HELPFUL, CONCISE, and ACCURATE. Be thorough in your actions — test what you build, verify what you change — not in your explanations.\n\n- Never diverge from the requirements and the goals of the task you work on. Stay on track.\n- Never give the user more than what they want.\n- Try your best to avoid any hallucination. Do fact checking before providing any factual information.\n- Think about the best approach, then take action decisively.\n- Do not give up too early.\n- ALWAYS, keep it stupidly simple. Do not overcomplicate things.\n- When the task requires creating or modifying files, always use tools to do so. Never treat displaying code in your response as a substitute for actually writing it to the file system.\n","src/kimi_cli/skills/kimi-cli-help/SKILL.md":"---\nname: kimi-cli-help\ndescription: Answer Kimi Code CLI usage, configuration, and troubleshooting questions. Use when user asks about Kimi Code CLI installation, setup, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, how something works internally, or any questions about Kimi Code CLI itself.\n---\n\n# Kimi Code CLI Help\n\nHelp users with Kimi Code CLI questions by consulting documentation and source code.\n\n## Strategy\n\n1. **Prefer official documentation** for most questions\n2. **Read local source** when in kimi-cli project itself, or when user is developing with kimi-cli as a library (e.g., importing from `kimi_cli` in their code)\n3. **Clone and explore source** for complex internals not covered in docs - **ask user for confirmation first**\n\n## Documentation\n\nBase URL: `https://moonshotai.github.io/kimi-cli/`\n\nFetch documentation index to find relevant pages:\n\n```\nhttps://moonshotai.github.io/kimi-cli/llms.txt\n```\n\n### Page URL Pattern\n\n- English: `https://moonshotai.github.io/kimi-cli/en/...`\n- Chinese: `https://moonshotai.github.io/kimi-cli/zh/...`\n\n### Topic Mapping\n\n| Topic | Page |\n|-------|------|\n| Installation, first run | `/en/guides/getting-started.md` |\n| Config files | `/en/configuration/config-files.md` |\n| Providers, models | `/en/configuration/providers.md` |\n| Environment variables | `/en/configuration/env-vars.md` |\n| Slash commands | `/en/reference/slash-commands.md` |\n| CLI flags | `/en/reference/kimi-command.md` |\n| Keyboard shortcuts | `/en/reference/keyboard.md` |\n| MCP | `/en/customization/mcp.md` |\n| Agents | `/en/customization/agents.md` |\n| Skills | `/en/customization/skills.md` |\n| FAQ | `/en/faq.md` |\n\n## Source Code\n\nRepository: `https://github.com/MoonshotAI/kimi-cli`\n\nWhen to read source:\n\n- In kimi-cli project directory (check `pyproject.toml` for `name = \"kimi-cli\"`)\n- User is importing `kimi_cli` as a library in their project\n- Question about internals not covered in docs (ask user before cloning)\n","src/kimi_cli/skills/skill-creator/SKILL.md":"---\nname: skill-creator\ndescription: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Kimi's capabilities with specialized knowledge, workflows, or tool integrations.\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Kimi's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Kimi from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n## Core Principles\n\n### Concise is Key\n\nThe context window is a public good. Skills share the context window with everything else Kimi needs: system prompt, conversation history, other Skills' metadata, and the actual user request.\n\n**Default assumption: Kimi is already very smart.** Only add context Kimi doesn't already have. Challenge each piece of information: \"Does Kimi really need this explanation?\" and \"Does this paragraph justify its token cost?\"\n\nPrefer concise examples over verbose explanations.\n\n### Set Appropriate Degrees of Freedom\n\nMatch the level of specificity to the task's fragility and variability:\n\n**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.\n\n**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.\n\n**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.\n\nThink of Kimi as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\nEvery SKILL.md consists of:\n\n- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Kimi reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.\n- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Kimi for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Kimi's process and thinking.\n\n- **When to include**: For documentation that Kimi should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Kimi determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Kimi produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Kimi to use files without loading them into context\n\n#### What to Not Include in a Skill\n\nA skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:\n\n- README.md\n- INSTALLATION_GUIDE.md\n- QUICK_REFERENCE.md\n- CHANGELOG.md\n- etc.\n\nThe skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Kimi (Unlimited because scripts can be executed without reading into context window)\n\n#### Progressive Disclosure Patterns\n\nKeep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.\n\n**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.\n\n**Pattern 1: High-level guide with references**\n\n```markdown\n# PDF Processing\n\n## Quick start\n\nExtract text with pdfplumber:\n[code example]\n\n## Advanced features\n\n- **Form filling**: See [FORMS.md](FORMS.md) for complete guide\n- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods\n- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns\n```\n\nKimi loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.\n\n**Pattern 2: Domain-specific organization**\n\nFor Skills with multiple domains, organize content by domain to avoid loading irrelevant context:\n\n```\nbigquery-skill/\n├── SKILL.md (overview and navigation)\n└── reference/\n ├── finance.md (revenue, billing metrics)\n ├── sales.md (opportunities, pipeline)\n ├── product.md (API usage, features)\n └── marketing.md (campaigns, attribution)\n```\n\nWhen a user asks about sales metrics, Kimi only reads sales.md.\n\nSimilarly, for skills supporting multiple frameworks or variants, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + provider selection)\n└── references/\n ├── aws.md (AWS deployment patterns)\n ├── gcp.md (GCP deployment patterns)\n └── azure.md (Azure deployment patterns)\n```\n\nWhen the user chooses AWS, Kimi only reads aws.md.\n\n**Pattern 3: Conditional details**\n\nShow basic content, link to advanced content:\n\n```markdown\n# DOCX Processing\n\n## Creating documents\n\nUse docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).\n\n## Editing documents\n\nFor simple edits, modify the XML directly.\n\n**For tracked changes**: See [REDLINING.md](REDLINING.md)\n**For OOXML details**: See [OOXML.md](OOXML.md)\n```\n\nKimi reads REDLINING.md or OOXML.md only when the user needs those features.\n\n**Important guidelines:**\n\n- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.\n- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Kimi can see the full scope when previewing.\n\n## Skill Locations and Discovery\n\nKimi Code CLI loads skills in layers (built-in -> user -> project). Within each layer, it uses the\nfirst existing directory in priority order. Built-in skills only load for LocalKaos or ACPKaos.\n\n**User level** (by priority):\n- `~/.config/agents/skills/` (recommended)\n- `~/.kimi/skills/`\n- `~/.claude/skills/`\n\n**Project level**:\n- `.agents/skills/`\n\n`--skills-dir` overrides discovery and loads only that directory (built-ins still load when\nsupported).\n\n## Skill Creation Process\n\nSkill creation involves these steps:\n\n1. Understand the skill with concrete examples\n2. Plan reusable skill contents (scripts, references, assets)\n3. Initialize the skill (run init_skill.py)\n4. Edit the skill (implement resources and write SKILL.md)\n5. Package the skill (run package_skill.py)\n6. Iterate based on real usage\n\nFollow these steps in order, skipping only if there is a clear reason why they are not applicable.\n\n### Skill Naming\n\n- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., \"Plan Mode\" -> `plan-mode`).\n- When generating names, generate a name under 64 characters (letters, digits, hyphens).\n- Prefer short, verb-led phrases that describe the action.\n- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).\n- Name the skill folder exactly after the skill name.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, create a new skill directory with a required `SKILL.md`\nfile and any optional resource directories that the skill needs (`scripts/`, `references/`,\n`assets/`). Create only the directories you intend to populate.\n\nAfter initialization, customize the SKILL.md and add resources as needed.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Kimi to use. Include information that would be beneficial and non-obvious to Kimi. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Kimi instance execute these tasks more effectively.\n\n#### Learn Proven Design Patterns\n\nCapture proven design patterns directly in this SKILL.md:\n\n- **Multi-step processes**: Clearly describe sequential workflows and conditional branches, including triggers, decision points, and expected outputs at each step.\n- **Specific output formats or quality standards**: Document required output shapes, templates, and examples directly in this SKILL.md so they are easy to follow.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAdded scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.\n\nDelete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.\n\n#### Update SKILL.md\n\n**Writing Guidelines:** Always use imperative/infinitive form.\n\n##### Frontmatter\n\nWrite the YAML frontmatter with `name` and `description`:\n\n- `name`: The skill name\n- `description`: This is the primary triggering mechanism for your skill, and helps Kimi understand when to use the skill.\n - Include both what the Skill does and specific triggers/contexts for when to use it.\n - Include all \"when to use\" information here - Not in the body. The body is only loaded after triggering, so \"When to Use This Skill\" sections in the body are not helpful to Kimi.\n - Example description for a `docx` skill: \"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Kimi needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks\"\n\nDo not include any other fields in YAML frontmatter.\n\n##### Body\n\nWrite instructions for using the skill and its bundled resources.\n\n### Step 5: Packaging a Skill\n\nOnce development of the skill is complete, package it into a distributable `.skill` file (a zip\narchive). Before packaging, validate that the skill meets all requirements:\n\n1. **Validate** the skill, checking:\n\n - YAML frontmatter format and required fields\n - Skill naming conventions and directory structure\n - Description completeness and quality\n - File organization and resource references\n\n2. **Package** the skill if validation passes:\n\n - Create an archive of the skill's root folder (the folder containing `SKILL.md` and all related files).\n - Ensure the archive preserves the internal directory structure.\n - Name the archive `.skill` (for example, `my-skill.skill`). The `.skill` file is a zip file with a `.skill` extension.\n\nExample packaging command:\n\n```bash\ncd \nzip -r my-skill.skill my-skill\n```\n\nIf validation fails (for example, due to malformed frontmatter, missing files, or an incomplete\ndescription), fix the issues and repackage the skill.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n","src/kimi_cli/tools/AGENTS.md":"# Kimi Code CLI Tools\n\n## Guidelines\n\n- Tools should not refer to types in `kimi_cli/wire/` unless they are explicitly implementing a UI / runtime bridge. When importing things like `ToolReturnValue` or `DisplayBlock`, prefer `kosong.tooling`.\n","tests_e2e/AGENTS.md":"# tests_e2e Wire E2E Guide\n\n## Goals and Scope\n- Test only `kimi --wire` JSON-RPC + wire messages; no Shell UI/Print/ACP/Term/shortcuts.\n- Do not test `--agent okabe`.\n- Do not test: W-23, W-26, W-29, W-27 (env overrides).\n\n## Execution Rules\n- Tests run via `uv run kimi` by default; set `KIMI_E2E_WIRE_CMD` to override the base command\n (e.g. `../kimi-agent-rs/target/debug/kimi-agent` or `kimi-agent` on PATH). `--wire` is appended if missing.\n- Always isolate `HOME`, `USERPROFILE`, and `KIMI_SHARE_DIR`, and use a temporary `--work-dir` to\n avoid touching real `~/.kimi`.\n- Use `inline_snapshot` for snapshot testing; snapshots can start empty and be updated later.\n- Wire traffic is line-delimited JSON; `event`/`request`/responses may interleave.\n\n## Test Matrix\n**Startup and Protocol**\n- W-01 Handshake: `initialize` returns `protocol_version=1.1`, `server`, and non-empty\n `slash_commands`.\n- W-02 External tool registration and call: register `external_tools`, trigger a\n `ToolCallRequest`, return `ToolResult`, turn finishes.\n- W-03 External tool conflict: registering a tool name that conflicts with a built-in is\n rejected with a reason.\n- W-04 Prompt without handshake: send `prompt` without `initialize`, turn still completes.\n- W-05 LLM not set: missing config yields `-32001` (LLM is not set).\n- W-06 Max steps: set a tiny `--max-steps-per-turn`, response is `status=max_steps_reached`.\n\n**Prompt and Event Stream**\n- W-07 Basic turn: `TurnBegin`/`StepBegin`/`ContentPart(text)`/`StatusUpdate` flow.\n- W-08 Multiline input: `TurnBegin.user_input` preserves newlines.\n- W-09 Content parts input: `user_input` as `ContentPart[]` (text/image/audio/video) with\n capabilities enabled.\n- W-10 Thinking toggle: `--thinking` emits `ContentPart(type=think)`, `--no-thinking` does not\n (real LLM).\n- W-11 Concurrent prompt: second `prompt` returns `-32000` (turn already in progress).\n- W-12 Cancel turn: `cancel` returns `{}`, original `prompt` becomes `status=cancelled`\n (may emit `StepInterrupted`, real LLM).\n\n**Tools and Approvals**\n- W-13 Shell approval: `Shell` triggers `ApprovalRequest`, `approve` yields `ToolResult`.\n- W-14 Approval reject: `reject` ends turn; tool does not run.\n- W-15 Session approval: `approve_for_session` removes subsequent blocking approvals.\n- W-16 YOLO: `--yolo` skips blocking approvals.\n- W-17 DisplayBlock coverage: `Shell`/`WriteFile`/`StrReplaceFile`/`SetTodoList` emit expected\n display types.\n- W-18 Tool args streaming: `ToolCallPart.arguments_part` can be stitched into full args.\n\n**Sessions and Context**\n- W-19 Session files: `--session ` writes `context.jsonl` and `wire.jsonl`.\n- W-20 Continue session: `--continue` appends to the same session files.\n- W-21 Clear context: `/clear` ensures the next `prompt` does not rely on prior context.\n- W-22 Manual compaction: `/compact` triggers `CompactionBegin/CompactionEnd`.\n- W-24 Status stats: `StatusUpdate.context_usage/token_usage` types are valid and change over time.\n\n**Config and Runtime Flags**\n- W-25 `--config` inline: JSON/TOML string config works.\n- W-28 CLI override: `--model` overrides `default_model`.\n- W-30 Work dir: `prompt` asks \"where is the current directory\", verify `--work-dir` (real LLM).\n\n**Extensions (Agents/Skills/MCP)**\n- W-31 Built-in agent boundary: `default` calling `SendDMail` fails or is rejected.\n- W-32 Custom agent: `--agent-file` excludes tool and calls are rejected.\n- W-33 Subagents: prompt \"parallel call two task tools, each runs shell sleep 0.5 and 1 second\";\n verify Task/SubagentEvent streaming/ToolResult/multiple approvals (real LLM).\n- W-34 Skill call: create a test skill, `/skill:test` injects `SKILL.md` (wire has no `/help`).\n- W-35 Flow skill: `/flow:` runs the flow until `END`.\n- W-36 MCP: use a Python fastmcp test server, load via `--mcp-config-file`, verify tool works.\n\n**Resilience and Errors**\n- W-37 Invalid JSON: malformed JSON line returns `-32700`.\n- W-38 Invalid request: missing fields returns `-32600`.\n- W-39 Unknown method: returns `-32601`.\n- W-40 Invalid params: bad structure returns `-32602`.\n- W-41 Cancel without active turn: returns `-32000`.\n- W-42 LLM errors: unsupported model `-32002` and service error `-32003`.\n\n## Real LLM Placeholders\n- W-10/W-12/W-30/W-33 require a real provider; everything else uses `_scripted_echo`.\n"},"files":{".agents/skills/codex-worker/SKILL.md":"---\nname: codex-worker\ndescription: Spawn and manage multiple Codex CLI agents via tmux to work on tasks in parallel. Use whenever a task can be decomposed into independent subtasks (e.g. batch triage, parallel fixes, multi-file refactors). When codex and tmux are available, prefer this over the built-in Task tool for parallelism.\n---\n\n# codex-worker\n\nOrchestrate multiple Codex CLI (`codex`) agents running in parallel, each in its\nown git worktree and tmux session.\n\n**When to use:** Whenever you identify that a task can be split into independent\nsubtasks — don't wait for the user to ask for parallelism. Examples:\n- User says \"triage all open issues updated in the last 7 days\" → fetch the\n issue list, then spawn one codex worker per issue.\n- User says \"refactor these 5 modules\" → one worker per module.\n- User says \"fix lint errors across packages\" → one worker per package.\n\n**Replaces Task tool:** When `codex` and `tmux` are available in the\nenvironment, use codex workers instead of the built-in Task (subagent) tool.\nCodex workers are full-featured agents with their own file system access, shell,\nand isolated worktree — far more capable than subagents.\n\n## Preflight check\n\n```bash\ncommand -v codex && codex login status && command -v tmux\n```\n\nAll three must succeed. The project must be a git repository.\n\n## Naming convention\n\nGit branch and worktree directory share a **task name**:\n\n```\n--\n```\n\nThe tmux session adds a `codex-worker-` prefix so workers are easy to filter:\n\n| | Format | Example |\n|---|---|---|\n| Task name | `--` | `issue-836-prompt-dollar-sign` |\n| Git branch | same as task name | `issue-836-prompt-dollar-sign` |\n| Worktree dir | `.worktrees/` | `kimi-cli.worktrees/issue-836-prompt-dollar-sign` |\n| tmux session | `codex-worker-` | `codex-worker-issue-836-prompt-dollar-sign` |\n\nMore examples:\n- `issue-518-mcp-config-isolation`\n- `fix-share-dir-skills-path`\n- `feat-ask-user-tool`\n- `refactor-jinja-templates`\n\nList only codex workers: `tmux ls | grep ^codex-worker-`\n\n## Usage\n\nPrefer tmux + interactive codex for all tasks. It supports multi-turn dialogue,\nthe user can `tmux attach` to inspect or intervene, and you can send follow-up\nprompts from outside.\n\n### Spawn a worker\n\n```bash\nNAME=\"issue-836-prompt-dollar-sign\" # task name\nSESSION=\"codex-worker-$NAME\" # tmux session name\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\n# 1. Create worktree (skip if exists)\ngit worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n\n# 2. Launch interactive codex inside tmux\ntmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n```\n\n### Send a prompt\n\nThe Codex TUI needs time to initialize before it accepts input.\nAfter launching a session, **wait at least 5 seconds** before sending\na prompt. Then send the text followed by `Enter`. If the prompt stays\nin the input field without being submitted, send an additional `Enter`.\n\n```bash\nsleep 5 # wait for Codex TUI to initialize\ntmux send-keys -t \"$SESSION\" \"Your prompt here\" Enter\n# If it doesn't submit, send another Enter:\n# tmux send-keys -t \"$SESSION\" Enter\n```\n\n### Peek at output\n\n```bash\ntmux capture-pane -t \"$SESSION\" -p | tail -30\n```\n\n### Attach for hands-on interaction\n\n```bash\ntmux attach -t \"$SESSION\"\n```\n\n### Parallel fan-out\n\n```bash\nTASKS=(\n \"issue-518-mcp-config-isolation|Triage #518: MCP config 被子 agent 继承的隔离问题。分析根因，给出修复方案。\"\n \"issue-836-prompt-dollar-sign|Triage #836: prompt 包含 $ 时启动静默失败。分析根因，给出修复方案。\"\n)\n\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\nfor entry in \"${TASKS[@]}\"; do\n NAME=\"${entry%%|*}\"\n PROMPT=\"${entry#*|}\"\n SESSION=\"codex-worker-$NAME\"\n git worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n tmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n sleep 5 # wait for Codex TUI to fully initialize\n tmux send-keys -t \"$SESSION\" \"$PROMPT\" Enter\ndone\n```\n\n### Fallback: `codex exec`\n\nOnly use `codex exec` when you explicitly don't need follow-up (e.g. CI, pure\nanalysis with `-o` output). It does not support multi-turn dialogue.\n\n```bash\ncodex exec --dangerously-bypass-approvals-and-sandbox \\\n -o \"/tmp/$NAME-result.md\" \\\n \"Your prompt here\"\n```\n\n## Lifecycle management\n\nList active workers:\n\n```bash\ntmux ls | grep ^codex-worker-\n```\n\nKill a finished worker:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\"\n```\n\nClean up worktree after merging:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\" 2>/dev/null\ngit worktree remove \"$WORKTREE_DIR/$NAME\"\ngit branch -d \"$NAME\"\n```\n\nBatch cleanup of dead sessions:\n\n```bash\ntmux list-sessions -F '#{session_name}:#{pane_dead}' \\\n | grep ':1$' \\\n | cut -d: -f1 \\\n | xargs -I{} tmux kill-session -t {}\n```\n",".agents/skills/feature-smoke-test/SKILL.md":"---\nname: feature-smoke-test\ndescription: 针对 Kimi Code CLI 的新增或变更功能，规划并执行可重复的端到端冒烟测试。从 git diff 推断功能边界，读取相关文档和代码，设计测试 prompt，以 --print 非交互模式运行本地 CLI，检查进程退出码和 session 产物，总结预期与实际行为之间的差异。发现问题时自动启动多路并行探查以定位根因。\n---\n\n冒烟测试是运行时验证，不是写完 prompt 或读完代码就结束。必须实际执行、实际检查产物。\n\n## 确定测试范围\n\n动手之前，先从代码变更推断功能边界：\n\n```sh\ngit diff main --name-only\ngit diff main --stat\n```\n\n根据变更文件集合，明确写下：\n\n- 被测的功能边界\n- 用户可感知的行为变化\n- 运行前的准备工作和运行后的清理工作\n- 能够证明成功或失败的证据\n\n如果功能涉及状态、异步、审批流或时序敏感逻辑，默认认为单条 prompt 不够。\n\n## 先读事实来源\n\n读取定义该功能真实行为的最小文件集合：\n\n- 面向用户的文档、changelog 或设计笔记\n- 暴露该功能的 agent prompt 或 tool prompt\n- 实现层入口\n- 已有测试——当测试比文档更准确地描述行为时优先看测试\n\n不要信任过时的 prompt 示例。先从代码或当前文档重建真实的工具接口。\n\n## 制定最小测试计划\n\n默认覆盖三个场景：\n\n1. 正常路径\n2. 边界条件、非法输入或容量极限\n3. 中断、重试、清理或恢复\n\n每个场景记录：\n\n- `目标`\n- `前置准备`\n- `prompt 策略`\n- `成功信号`\n- `失败信号`\n- `需要检查的产物`\n\n如果功能存在竞态条件，必须显式标注时序。用长时间运行的命令或刻意的等待来制造时序窗口，不要用\"快速再跑一个\"这种模糊说法。\n\n## 优先使用多轮 prompt\n\n默认采用多轮流程：\n\n1. 探索轮：让 agent 在阅读事实来源后复述当前真实接口\n2. 执行轮：只执行一个场景\n3. 观察轮：只读取输出、工具状态和产物文件，不扩大范围\n4. 清理轮：停止、回滚或关闭有状态资源\n\n仅对无状态的简单功能使用单轮 prompt。\n\n多轮测试时，每一轮单独调用 CLI，在两轮之间检查上一轮的输出和产物，再决定下一轮的 prompt。不要把多轮 prompt 一次性塞进 stdin——那是盲写，无法根据上一轮结果调整。\n\n测试时，显式要求 agent 先列举当前可用的工具，不要臆造历史工具名。可复用的 prompt 模板见 `references/prompt-patterns.md`。\n\n## 以非交互模式隔离运行 CLI\n\n使用 `/tmp` 下的一次性目录作为 `--work-dir`，实现 session 隔离。CLI 的 session 路径由 `~/.kimi/sessions//` 决定，不同的 work-dir 自动产生独立的 session 命名空间，不会污染正常项目的 session。认证状态保留在 `~/.kimi` 下，无需额外配置。\n\n### 环境准备\n\n```sh\nSMOKE_DIR=\"$(mktemp -d /tmp/kimi-smoke-XXXXXX)\"\n```\n\n如果功能需要仓库上下文（读取代码、git 信息等），把仓库文件复制或软链到 `SMOKE_DIR`。如果功能会编辑文件，绝不要用活跃仓库作为 work-dir。\n\n### 默认执行方式\n\n绝大多数场景使用这个模式：\n\n```sh\nuv run python -m kimi_cli.cli \\\n --print \\\n --prompt \"你的测试 prompt\" \\\n --work-dir \"$SMOKE_DIR\"\necho \"exit_code=$?\"\n```\n\n`--print` 会自动启用 `--yolo`（自动批准所有操作），适合无人值守的冒烟测试。\n\n执行后**必须先检查退出码**：非零表示 CLI 本身崩溃或超时，应优先排查进程级错误，再看 session 产物。\n\n### 备选执行模式\n\n当默认方式不满足需求时，按需选用：\n\n- **长 prompt**：通过 stdin 传入——`cat <<'PROMPT' | uv run python -m kimi_cli.cli --print --input-format text --work-dir \"$SMOKE_DIR\"`\n- **结构化输出**：加 `--output-format stream-json`，输出逐行 JSON，便于程序化解析\n- **只看最终结果**：用 `--quiet`，等价于 `--print --output-format text --final-message-only`\n\n### 注意事项\n\n- 运行过程中记录这些路径：`SMOKE_DIR`、最终 session 目录（可通过 `inspect_session.py` 定位）、功能特定的输出文件。\n\n## 刻意执行\n\n执行过程中维护一份简短的运行日志：\n\n- 使用的完整 prompt\n- 关键的工具调用或命令\n- 功能产生的 task id、输出路径或审批 id\n- 时序敏感时记录时间戳\n\n不要仅凭 assistant 的最终文本推断正确性。运行时文件和工具结果才是事实来源。\n\n## 检查 session 产物\n\n首先检查：\n\n- `~/.kimi/sessions/.../context.jsonl`\n- `~/.kimi/sessions/.../wire.jsonl`\n- 功能创建的 session 级文件\n\n使用 `scripts/inspect_session.py` 查找并汇总最新 session：\n\n```sh\nuv run python .agents/skills/feature-smoke-test/scripts/inspect_session.py --share-dir ~/.kimi\n```\n\n脚本退出码含义：0 = 正常汇总，1 = session 目录缺失或无法解析。\n\n如果功能会创建后台任务、通知或附属文件，直接检查这些文件，不要只依赖模型摘要。\n\n## 汇报结论\n\n将结果分为三类：\n\n- **已确认**的行为\n- **与预期不符**的行为\n- **仍有歧义**、需要更确定性复现的行为\n\n对于每个 bug 或回归，记录：\n\n- 触发它的 prompt\n- 精确的 session 路径\n- 证明它的产物路径\n- 能推导出的最小复现步骤\n\n## 问题探查\n\n当发现与预期不符的行为时，不要停在报告层面。启动并行探查流程定位根因：\n\n### 探查策略\n\n针对每个发现的问题，**同时启动多个独立的探查方向**（使用 Agent 工具并行执行）。根据问题的具体表现自行判断最有价值的探查角度，常见方向包括但不限于：\n\n- 从触发问题的入口沿调用链追踪实际执行路径\n- 检查输入数据经过各处理阶段后的变化\n- 检查持久化状态（session 文件、后台任务、通知记录等）是否一致\n- 运行相关单元测试和集成测试，确认测试是否覆盖了出问题的路径\n\n不必机械地覆盖所有方向。根据 session 产物中的具体异常信号，选择最可能命中根因的 2-3 个方向并行展开。\n\n### 探查输出\n\n每条探查方向独立汇报：\n\n- 探查的具体方向和范围\n- 发现的事实（附文件路径和行号）\n- 该方向的结论：已定位根因 / 已排除 / 需要进一步调查\n\n### 综合定位\n\n汇总所有探查结果后，输出：\n\n- **根因**：一句话总结问题的本质原因\n- **证据链**：从触发 prompt → 代码路径 → 出错点 → 产物表现的完整链路\n- **修复建议**：最小改动方案，附具体文件和行号\n- **回归风险**：修复后需要额外验证的相关功能\n",".agents/skills/feature-smoke-test/references/prompt-patterns.md":"# Prompt 模板\n\n以下模板作为脚手架使用。运行前替换占位符。\n\n## 单轮还是多轮\n\n满足以下任一条件时使用多轮：\n\n- 功能有状态\n- 功能依赖时序或并发\n- 功能需要审批、清理或恢复\n- session 产物本身是证据的一部分\n- 工具接口可能近期发生过变化\n\n仅对无状态的窄范围检查使用单轮。\n\n## 变量\n\n起草 prompt 前填写以下字段：\n\n- `` — 被测功能名称\n- `` — 当前场景的目标\n- `` — 需要阅读的源码路径\n- `` — 执行约束\n- `` — 成功信号\n- `` — 失败信号\n- `` — 需要检查的产物路径\n- `` — session 目录路径\n\n## 探索 prompt\n\n```text\n我要验证 。\n\n先阅读这些文件并只总结当前真实对外接口，不要假设旧文档、旧 prompt 或旧 tool 名称仍然正确：\n\n\n然后给我一个最小 smoke test 计划，只包含：\n1. happy path\n2. 一个边界/异常场景\n3. 一个清理、恢复或中断场景\n\n每个场景都写清楚目标、预期信号和要检查的产物。\n```\n\n## 执行 prompt\n\n```text\n在当前 session 里只执行这个场景：\n\n约束：\n\n\n执行前先复述你将使用的工具或命令。执行时记录关键 task id、输出片段、文件路径和任何需要后续复盘的标识符。不要扩展到其他场景。\n```\n\n## 观察 prompt\n\n```text\n现在不要继续跑新的测试。\n\n只读取并总结这次运行已经产生的状态和文件：\n\n\n请明确指出哪些证据支持了预期，哪些证据反驳了预期，哪些地方仍然不确定。\n```\n\n## 复盘 prompt\n\n```text\n请根据这个 session 目录复盘整个 smoke test：\n\n\n重点阅读 context.jsonl、wire.jsonl 和相关运行产物。输出：\n1. 实际执行流程\n2. 关键 tool 调用与结果\n3. 与预期不一致的点\n4. 最小复现步骤\n```\n\n## 兼容性校验 prompt\n\n```text\n在运行 smoke test 之前，先从提供的文档或代码中复述当前真实可用的工具及其准确名称。不要臆造旧版工具名。如果任务涉及状态或时序，将工作拆分为多轮而非一次性长回复。\n```\n",".agents/skills/gen-changelog/SKILL.md":"---\nname: gen-changelog\ndescription: Generate changelog entries for code changes.\n---\n\nGenerate changelog entries for changes on the current branch relative to `main`, then sync to the docs site.\n\n## Steps\n\n1. **Inspect**: `git log main..HEAD --oneline` + `git diff main..HEAD --stat`.\n2. **Edit root CHANGELOG**: add bullets under `## Unreleased` in `CHANGELOG.md` using the prefix table below. For changes scoped to a subpackage under `packages/` or `sdks/`, **also** update that subpackage's `CHANGELOG.md` — subpackage CHANGELOGs follow their own prefix conventions (e.g. `packages/kosong/CHANGELOG.md` uses provider prefixes like `Kimi:` / `Anthropic:`); only the root CHANGELOG follows the table below.\n3. **Sync English docs**: `node docs/scripts/sync-changelog.mjs`.\n4. **Translate to Chinese**: hand-write equivalents under `## 未发布` in `docs/zh/release-notes/changelog.md`. Use the full-width colon `：`. Follow `docs/AGENTS.md` terminology.\n5. **Breaking changes**: if any, add a section under `## Unreleased` in `docs/en/release-notes/breaking-changes.md` with **Affected** + **Migration** subsections, and under `## 未发布` in `docs/zh/release-notes/breaking-changes.md` with **受影响** + **迁移** subsections.\n\n## Entry format\n\n```\n- : — \n```\n\n- **First sentence stands alone** — readers should know after one sentence whether the bullet matters to them.\n- **One change per bullet.** No `; also`, `; and`, or nested em-dashes. Two changes = two bullets.\n- **Verb-led**: `Fix …` / `Add …` / `Switch …` / `Bump …`.\n- **User-meaningful only.** No internal refactors, test churn, or CI tweaks — except `Lib:` for SDK-facing changes.\n\n## Prefixes — pick from this list, do not invent new ones\n\n| Prefix | Scope |\n|---|---|\n| `Shell` | Interactive TUI: keys, status bar, slash commands, terminal rendering |\n| `Web` | `kimi web` |\n| `Vis` | `kimi vis` tracing visualizer |\n| `CLI` | Top-level flags, subcommands, `--print` / `--yolo` / `--afk` |\n| `ACP` | Zed / JetBrains and other ACP integrations |\n| `Core` | Agent runtime, step loop, approval, quota, turns, background tasks |\n| `Tool` | Any built-in tool; name the specific tool in the body (ReadFile, Grep, Todo, Plan, …) |\n| `Skill` | Skill discovery/loading, Flow, Loop (always singular — not `Skills:`) |\n| `MCP` | MCP server integration |\n| `Plugin` | Plugin system, `kimi plugin` subcommands |\n| `LLM` | Provider-agnostic or cross-provider; name the provider in the body (Kimi / Anthropic / OpenAI / DeepSeek …). **Do not** create per-provider prefixes |\n| `Kosong` | Changes to the `kosong` LLM abstraction layer surfaced in the root CHANGELOG (the subpackage's own CHANGELOG uses provider prefixes) |\n| `Wire` | Wire protocol events, version |\n| `Auth` | OAuth, token refresh, `/login` |\n| `Config` | Config schema, env vars |\n| `Lib` | SDK-facing API changes |\n| `Build` | Nix / Rust / Python / packaging |\n\nWhen unsure, match an existing entry of the same kind. Prefer this list; if you genuinely need a new prefix, raise it with maintainers and update this table in the same PR so the convention stays single-sourced.\n\n**Ordering**: within each version, group bullets by prefix in the order of the table above. Order within a prefix is free — keep the development order.\n\n## Highlights\n\nStarting from the next release, add `**Highlights**: …` under each version header (1–3 items most users will notice); mirror it as `**亮点**：…` in Chinese. Skip on releases that are only internal or `Lib:`. Highlights summarize — every highlighted item still needs its full bullet below. **Do not backfill historical versions.**\n",".agents/skills/gen-docs/SKILL.md":"---\nname: gen-docs\ndescription: Update Kimi Code CLI user documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n我们现在对代码库有了一些修改，请你参考最近的 git commit、staged changes、changelog.md 等的内容，根据 AGENTS.md 中的信息，必要时找到实际的代码全文，确保理解了所有变更对产品用户体验的真实改变，然后逐页、逐段地检查和更新文档内容。\n\n你应该首先确保英文 changelog 使用 `node docs/scripts/sync-changelog.mjs` 进行了同步，然后确保中文文档符合最新代码的行为，最后，使用 translate-docs skill 进行双语同步。\n",".agents/skills/gen-rust/SKILL.md":"---\nname: gen-rust\ndescription: Sync Rust implementation with Python changes (exclude UI/login) by reviewing recent changes, mapping modules, porting logic, and updating tests.\n---\n\n# gen-rust\n\nUse this skill when the user wants Rust (kagent/kosong/kaos) to stay logically identical to Python (kimi_cli/kosong/kaos), excluding UI and login/auth. This includes code and tests: Rust behavior and tests must be fully synchronized with Python changes.\n\nNote: The Rust binary is named `kagent`. User-facing CLI/output text in Rust must use `kagent`\ninstead of `kimi` to match the Rust command name.\n\n## Quick workflow\n\n1) **Build a complete change inventory**\n\nReview recent changes to understand what needs syncing:\n\n```sh\n# Check staged changes\ngit diff --cached --name-only\ngit diff --cached -- src packages\n\n# Check recent commits\ngit log --oneline -20 -- src packages\ngit diff HEAD~20..HEAD -- src packages\n\n# Review CHANGELOG.md for context\nhead -50 CHANGELOG.md\n```\n\n2) **Classify changes**\n\n- Exclude UI and login/auth changes (Shell/Print/ACP UI, login/logout commands).\n- Everything else must be mirrored in Rust.\n- Keep a small checklist: file -> change summary -> Rust target -> status.\n\n3) **Map Python -> Rust**\n\nCommon mappings:\n- `src/kimi_cli/llm.py` -> `rust/kagent/src/llm.rs`\n- `src/kimi_cli/soul/*` -> `rust/kagent/src/soul/*`\n- `src/kimi_cli/tools/*` -> `rust/kagent/src/tools/*`\n- `src/kimi_cli/utils/*` -> `rust/kagent/src/utils/*`\n- `src/kimi_cli/wire/*` -> `rust/kagent/src/wire/*`\n- `packages/kosong/*` -> `rust/kosong/*`\n- `packages/kaos/*` -> `rust/kaos/*`\n\n4) **Port logic carefully**\n\n- Match error messages and tool output text exactly (tests often assert strings).\n- Preserve output types (text vs parts) and ordering.\n- For media/tool outputs, verify ContentPart wrapping and serialization.\n- If Python adds new helper modules, mirror minimal Rust utilities.\n- Use `rg` to find existing analogs and references.\n\n5) **Update tests**\n\n- Update Rust tests that assert content/strings/parts.\n- Mirror Python unit and integration tests when they exist; add missing Rust tests so coverage matches intent.\n- Ensure E2E parity: use the existing Python E2E suite against the Rust binary by setting\n `KIMI_E2E_WIRE_CMD` (do not rewrite E2E in Rust). All E2E cases must pass or the gap must be documented.\n- Prefer targeted tests first (`cargo test -p kagent --test `), then full suite if asked.\n\n6) **Verification is mandatory**\n\n- Run the full Rust test suite and ensure all Rust tests pass.\n- Run E2E tests with the wire command swapped to Rust (set `KIMI_E2E_WIRE_CMD`), and ensure they pass.\n\n7) **Final report**\n\n- List synced files and logic.\n- Call out intentionally skipped UI/login changes.\n- List tests run and results (must include full Rust tests and Rust E2E with wire command override).\n\n## Pitfalls to avoid\n\n- Skipping `llm.py`: it often changes model capability logic.\n- Using commit message filtering instead of full diff.\n- Forgetting to update Rust tests when output text/parts change.\n- Mixing UI/login changes into core sync.\n- Leaving test parity ambiguous; always state unit/integration/E2E status.\n\n## Minimal diff checklist (template)\n\n- [ ] Recent changes reviewed (staged, commits, changelog)\n- [ ] Python diffs inspected for core logic\n- [ ] Rust mappings applied\n- [ ] Tests updated\n- [ ] Targeted tests run\n- [ ] Full Rust test suite passed\n- [ ] Rust E2E passed with `KIMI_E2E_WIRE_CMD`\n",".agents/skills/pull-request/SKILL.md":"---\nname: pull-request\ndescription: Create and submit a GitHub Pull Request.\ntype: flow\n---\n\n```mermaid\nflowchart TB\n A([\"BEGIN\"]) --> B[\"当前分支有没有 dirty change？\"]\n B -- 有 --> D([\"END\"])\n B -- 没有 --> n1[\"确保当前分支是一个不同于 main 的独立分支\"]\n n1 --> n2[\"根据当前分支相对于 main 分支的修改，push 并提交一个 PR（利用 gh 命令），用英文编写 PR 标题和 description，描述所做的更改。PR title 要符合先前的 commit message 规范（PR title 就是 squash merge 之后的 commit message）。\"]\n n2 --> D\n```\n",".agents/skills/release/SKILL.md":"---\nname: release\ndescription: Execute the release workflow for Kimi Code CLI packages.\n---\n\nRelease process for Kimi Code CLI packages. Tags are pushed without a `v` prefix and follow one of these patterns (matched by `.github/workflows/release-*.yml`):\n\n| Tag pattern | Releases |\n|---|---|\n| `1.42.0` (numeric) | `kimi-cli` (root) + `kimi-code` wrapper, released together — versions must stay aligned |\n| `kosong-0.53.0` | `packages/kosong` |\n| `pykaos-0.9.0` | `packages/kaos` (PyPI name `pykaos`) |\n| `kimi-sdk-0.3.0` | `sdks/kimi-sdk` |\n\nThe Rust implementation (`kagent`) lives in a separate repository and is **not** released from here.\n\n## Steps\n\n1. **Understand the automation.** Read `AGENTS.md` and `.github/workflows/release*.yml` so you know what each release workflow expects before changing any versions.\n\n2. **Detect changed packages.** Check each release unit under `packages/`, `sdks/`, and the repo root for changes since its last release tag. Use path-scoped diffs for subpackages so unrelated repo changes do not trigger a package release, e.g. `git diff kosong-0.53.0..HEAD -- packages/kosong`, `git diff pykaos-0.9.0..HEAD -- packages/kaos`, and `git diff kimi-sdk-0.2.1..HEAD -- sdks/kimi-sdk`. If nothing changed anywhere, stop and report that there is nothing to release. Note: `packages/kimi-code` is a thin wrapper and must stay version-synced with `kimi-cli`, so treat it as changed whenever the root package changes.\n\n3. **Confirm new versions with the user.** For each changed package, propose a new version and confirm before editing. Versioning policy:\n - Patch is always `0`.\n - Bump the minor version for any change.\n - Major only changes by explicit manual decision from the user.\n\n4. **Create the release branch.** Name it `bump--`. If multiple packages are being bumped together, use a single branch with a descriptive name.\n\n5. **Update version metadata and changelogs.** For each changed package:\n - Update its `pyproject.toml`.\n - Update `CHANGELOG.md`, keeping the `## Unreleased` header empty in place (do **not** rename it — add a new dated `## (YYYY-MM-DD)` section below it).\n - Update `breaking-changes.md` in both languages if there are breaking changes.\n - If bumping `packages/kosong` or `packages/kaos`, also update the root `pyproject.toml` pinned dependency (`kosong[contrib]==` or `pykaos==`) so root validation keeps passing.\n\n6. **Sync the `kimi-code` wrapper when the root version changes.** Bump `packages/kimi-code/pyproject.toml` `version` to match the new root version. It is a legacy stub with no dependencies — do not add a `kimi-cli` pin back.\n\n7. **Run `uv sync`** to refresh the lockfile.\n\n8. **Update docs.** Follow the `gen-docs` skill to make sure docs reflect the release.\n\n9. **Confirm with the user before opening the PR.** Summarize the staged changes and ask the user to explicitly confirm:\n - **Version numbers** — every updated `pyproject.toml` (changed package + `packages/kimi-code` if the root moved) reflects the version agreed in step 3.\n - **Dependency pins** — the root `pyproject.toml` pins (`kosong[contrib]==`, `pykaos==`) match the bumped versions.\n - **Documentation** — CHANGELOG entries are added below `## Unreleased` (Unreleased still present and empty), `breaking-changes.md` is updated in both languages if applicable, and `gen-docs` left no inconsistencies.\n\n Wait for explicit user approval before proceeding. If the user flags anything, fix it and re-confirm — do not push.\n\n10. **Open the PR.** Commit all changes, push, and open a PR with `gh`. The PR description must follow this structure (see https://github.com/MoonshotAI/kimi-cli/pull/2225 for reference):\n\n ```markdown\n ## Summary\n - Bump to \n - Move the current release notes under \n - (If applicable) Move breaking-change entries under \n - (If applicable) Any additional noteworthy changes (dependency pin updates, etc.)\n\n ## Validation\n - uv run python scripts/check_version_tag.py --pyproject --expected-version \n - (For root releases) uv run python scripts/check_version_tag.py --pyproject packages/kimi-code/pyproject.toml --expected-version \n - uv run python scripts/check_kimi_dependency_versions.py --root-pyproject pyproject.toml --kosong-pyproject packages/kosong/pyproject.toml --pykaos-pyproject packages/kaos/pyproject.toml\n - make check\n\n ## Post-merge\n After this PR lands, create and push the release tag:\n\n ```sh\n git tag \n git push origin \n ```\n ```\n\n11. **Hand off the tag step.** After merge, switch to `main`, pull latest, and tell the user the exact `git tag` command for the final release tag (pick the right tag pattern from the table above — e.g. `git tag 1.43.0` for a root release, `git tag kosong-0.54.0` for a kosong release). The user will run the tag and push tags themselves.\n\n## Stop conditions\n\nFail fast — never paper over an error to keep the release moving. Stop and report back to the user when any of these happen:\n\n- Nothing changed since the last tag → there is nothing to release.\n- `uv sync` fails or produces unexpected `uv.lock` churn beyond the version bump.\n- `gen-docs` reports a doc inconsistency you cannot resolve.\n- PR checks go red after push — investigate, do **not** `--no-verify` or force-merge.\n- The release workflow fails after tag push — read the workflow logs and surface the failure, do not retag silently.\n",".agents/skills/translate-docs/SKILL.md":"---\nname: translate-docs\ndescription: Translate and sync bilingual documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n中文文档和英文 changelog 已经确保是正确符合预期的，现在请你逐页、逐段地翻译文档内容，确保中英双语保持同步。\n\n## 翻译方向\n\n- **Changelog**: 以英文为准，翻译到中文\n- **其他所有页面**: 以中文为准，翻译到英文\n\n## 注意事项\n\n- 必要时可以参考代码文件以确保翻译的准确性\n- 要保证不同语言的表达风格、结构标记等保持一致\n- 但需要遵守两者可能不同的用词和排版偏好（主要是 sentence case、翻译对照之类的）\n",".agents/skills/worktree-status/SKILL.md":"---\nname: worktree-status\ndescription: Audit all git worktrees in the current project. Use when the user asks about worktree status, which branches are merged, which have uncommitted changes, or which worktrees can be safely cleaned up.\n---\n\n# worktree-status\n\nReport the status of every git worktree for the current project, covering\ndirty state and merge status.\n\n## When to use\n\n- User asks \"which worktrees can I clean up?\"\n- User asks \"what's the status of my worktrees / branches?\"\n- Before batch-cleaning worktrees, to avoid losing uncommitted work\n\n## Procedure\n\n### 1. Pull latest main (MANDATORY)\n\nYou MUST pull latest main before any status checks. Without this, merge\ndetection (both ancestry and content diff) will produce stale results and\nyou may mistakenly conclude a branch is not merged.\n\n```bash\ncd \"$(git rev-parse --show-toplevel)\" && git pull origin main\n```\n\n### 2. Collect worktree info\n\n```bash\nPROJECT_DIR=\"$(git rev-parse --show-toplevel)\"\n\nfor wt in $(git worktree list --porcelain | grep \"^worktree \" | sed 's/^worktree //' | grep -v \"$PROJECT_DIR$\"); do\n branch=$(git -C \"$wt\" branch --show-current 2>/dev/null)\n [ -z \"$branch\" ] && branch=\"(detached)\"\n name=$(basename \"$wt\")\n\n # dirty?\n if [ -z \"$(git -C \"$wt\" status --short 2>/dev/null)\" ]; then\n dirty=\"clean\"\n else\n dirty=\"DIRTY\"\n fi\n\n # merged into origin/main?\n # NOTE: This project uses squash merges exclusively. `git merge-base\n # --is-ancestor` does NOT detect squash-merged branches. Always follow\n # up with a content diff (step 3) for branches that appear \"not merged\".\n if [ \"$branch\" != \"(detached)\" ]; then\n if git merge-base --is-ancestor \"$branch\" origin/main 2>/dev/null; then\n merged=\"merged\"\n else\n merged=\"not merged (verify with content diff)\"\n fi\n else\n merged=\"n/a\"\n fi\n\n echo \"\"\n echo \"[$name] branch=$branch $dirty $merged\"\n if [ \"$dirty\" = \"DIRTY\" ]; then\n git -C \"$wt\" status --short 2>/dev/null | sed 's/^/ /'\n fi\ndone\n```\n\n### 3. Detect squash-merged branches (content diff)\n\nFor any branch that shows \"not merged\", check whether the branch's\nchanges are already in main. The correct method is:\n\n1. Find the files the branch actually changed (relative to merge-base).\n2. For each changed file, compare the branch version with main.\n If all files are identical, the branch was squash-merged.\n\n**⚠️ Do NOT use `git diff origin/main `** — that compares the\ntwo tips directly, so commits added to main *after* the branch diverged\nwill show up as false differences.\n\n```bash\nBRANCH=\"\"\nBASE=$(git merge-base origin/main \"$BRANCH\")\n\n# List files the branch touched\nFILES=$(git diff --name-only \"$BASE\" \"$BRANCH\")\n\n# Compare each file between branch and current main\nfor f in $FILES; do\n d=$(git diff \"$BRANCH\" origin/main -- \"$f\" | wc -l)\n if [ \"$d\" != \"0\" ]; then\n echo \"❌ $f — differs\"\n else\n echo \"✅ $f — identical in main\"\n fi\ndone\n# All ✅ = squash-merged\n```\n\n### 4. (Optional) Check for associated tmux sessions\n\nOnly run this if `tmux` is available and relevant (e.g. worktrees were\ncreated by codex-worker or similar tooling). Skip if not applicable.\n\n```bash\ntmux ls 2>/dev/null | grep -E 'codex-worker|' || true\n```\n\n### 5. Present results\n\n**Always present results as a Markdown table.** Every worktree must appear\nas a row. Never use abbreviated or prose-only summaries.\n\n| Worktree | Branch | Dirty | Merged | Can clean? |\n|---|---|---|---|---|\n| `example-wt` | `feat-foo` | ✅ clean | ✅ squash-merged | ✅ |\n| `another-wt` | `fix-bar` | ⚠️ 3 files | ❌ not merged | ❌ dirty + not merged |\n| `detached-wt` | (detached) | ⚠️ 14 files | n/a | ❌ has uncommitted changes |\n\nColumn definitions:\n\n- **Dirty**: `✅ clean` or `⚠️ N files`\n- **Merged**: `✅ merged` / `✅ squash-merged` (confirmed via content diff) / `❌ not merged` / `n/a`\n- **Can clean?**: `✅` only when merged (or squash-merged) AND clean\n\nAdd extra columns (e.g. tmux session, notes) only when relevant.\n\n### 6. Cleanup (only when asked)\n\nOnly clean worktrees the user explicitly approves. For each:\n\n```bash\nNAME=\"\"\ngit worktree remove \"/path/to/$NAME\"\ngit branch -D \"\" # only if the branch is no longer needed\n```\n","AGENTS.md":"# Kimi Code CLI\n\n## Quick commands (use uv)\n\n- `make prepare` (sync deps for all workspace packages and install git hooks)\n- `make format`\n- `make check`\n- `make test`\n- `make ai-test`\n- `make build` / `make build-bin`\n\nIf running tools directly, use `uv run ...`.\n\n## Project overview\n\nKimi Code CLI is a Python CLI agent for software engineering workflows. It supports an interactive\nshell UI, ACP server mode for IDE integrations, and MCP tool loading.\n\n## Tech stack\n\n- Python 3.12+ (tooling configured for 3.14)\n- CLI framework: Typer\n- Async runtime: asyncio\n- LLM framework: kosong\n- MCP integration: fastmcp\n- Logging: loguru\n- Package management/build: uv + uv_build; PyInstaller for binaries\n- Tests: pytest + pytest-asyncio; lint/format: ruff; types: pyright + ty\n\n## Architecture overview\n\n- **CLI entry**: `src/kimi_cli/cli/__init__.py` (Typer) parses flags (UI mode, agent spec, config, MCP)\n and routes into `KimiCLI` in `src/kimi_cli/app.py`.\n- **App/runtime setup**: `KimiCLI.create` loads config (`src/kimi_cli/config.py`), chooses a\n model/provider (`src/kimi_cli/llm.py`), builds a `Runtime` (`src/kimi_cli/soul/agent.py`),\n loads an agent spec, restores `Context`, then constructs `KimiSoul`.\n- **Agent specs**: YAML under `src/kimi_cli/agents/` loaded by `src/kimi_cli/agentspec.py`.\n Specs can `extend` base agents, select tools by import path, and register builtin subagent\n types via the `subagents` field. Subagent instances are persisted separately under the session\n directory and can be resumed by `agent_id`. System prompts live alongside specs; builtin args\n include `KIMI_NOW`, `KIMI_WORK_DIR`, `KIMI_WORK_DIR_LS`, `KIMI_AGENTS_MD`, `KIMI_SKILLS`, `KIMI_OS`, `KIMI_SHELL`\n (this file is injected via `KIMI_AGENTS_MD`).\n- **Tooling**: `src/kimi_cli/soul/toolset.py` loads tools by import path, injects dependencies,\n and runs tool calls. Built-in tools live in `src/kimi_cli/tools/` (agent, shell, file, web,\n todo, background, dmail, think, plan). MCP tools are loaded via `fastmcp`; CLI management is\n in `src/kimi_cli/mcp.py` and stored in the share dir.\n- **Subagents**: `LaborMarket` in `src/kimi_cli/soul/agent.py` registers builtin subagent types.\n The `Agent` tool (`src/kimi_cli/tools/agent/`) creates or resumes subagent instances, while\n `SubagentStore` persists instance metadata, prompts, wire logs, and context under\n `session/subagents//`.\n- **Core loop**: `src/kimi_cli/soul/kimisoul.py` is the main agent loop. It accepts user input,\n handles slash commands (`src/kimi_cli/soul/slash.py`), appends to `Context`\n (`src/kimi_cli/soul/context.py`), calls the LLM (kosong), runs tools, and performs compaction\n (`src/kimi_cli/soul/compaction.py`) when needed.\n- **Approvals**: `src/kimi_cli/soul/approval.py` is the tool-facing facade. `ApprovalRuntime`\n in `src/kimi_cli/approval_runtime/` is the session-level source of truth for pending approvals,\n and approval requests are projected onto the root wire stream for Shell/Web style UIs.\n- **UI/Wire**: `src/kimi_cli/soul/run_soul` connects `KimiSoul` to a `Wire`\n (`src/kimi_cli/wire/`) so UI loops can stream events. UIs live in `src/kimi_cli/ui/`\n (shell/print/acp/wire).\n- **Shell UI**: `src/kimi_cli/ui/shell/` handles interactive TUI input, shell command mode,\n and slash command autocomplete; it is the default interactive experience.\n- **Slash commands**: Soul-level commands live in `src/kimi_cli/soul/slash.py`; shell-level\n commands live in `src/kimi_cli/ui/shell/slash.py`. The shell UI exposes both and dispatches\n based on the registry. Standard skills register `/skill:` and load `SKILL.md`\n as a user prompt; flow skills register `/flow:` and execute the embedded flow.\n\n## Major modules and interfaces\n\n- `src/kimi_cli/app.py`: `KimiCLI.create(...)` and `KimiCLI.run(...)` are the main programmatic\n entrypoints; this is what UI layers use.\n- `src/kimi_cli/soul/agent.py`: `Runtime` (config, session, builtins), `Agent` (system prompt +\n toolset), and `LaborMarket` (builtin subagent type registry).\n- `src/kimi_cli/soul/kimisoul.py`: `KimiSoul.run(...)` is the loop boundary; it emits Wire\n messages and executes tools via `KimiToolset`.\n- `src/kimi_cli/soul/context.py`: conversation history + checkpoints; used by DMail for\n checkpointed replies.\n- `src/kimi_cli/soul/toolset.py`: load tools, run tool calls, bridge to MCP tools.\n- `src/kimi_cli/ui/*`: shell/print/acp frontends; they consume `Wire` messages.\n- `src/kimi_cli/wire/*`: event types and transport used between soul and UI.\n\n## Repo map\n\n- `src/kimi_cli/agents/`: built-in agent YAML specs and prompts\n- `src/kimi_cli/prompts/`: shared prompt templates\n- `src/kimi_cli/soul/`: core runtime/loop, context, compaction, approvals\n- `src/kimi_cli/tools/`: built-in tools\n- `src/kimi_cli/ui/`: UI frontends (shell/print/acp/wire)\n- `src/kimi_cli/acp/`: ACP server components\n- `packages/kosong/`, `packages/kaos/`: workspace deps\n + Kosong is an LLM abstraction layer designed for modern AI agent applications.\n It unifies message structures, asynchronous tool orchestration, and pluggable\n chat providers so you can build agents with ease and avoid vendor lock-in.\n + PyKAOS is a lightweight Python library providing an abstraction layer for agents\n to interact with operating systems. File operations and command executions via KAOS\n can be easily switched between local environment and remote systems over SSH.\n- `tests/`, `tests_ai/`: test suites\n- `klips`: Kimi Code CLI Improvement Proposals\n\n## Conventions and quality\n\n- Python >=3.12 (ty config uses 3.14); line length 100.\n- Ruff handles lint + format (rules: E, F, UP, B, SIM, I); pyright + ty for type checks.\n- Tests use pytest + pytest-asyncio; files are `tests/test_*.py`.\n- CLI entry points: `kimi` / `kimi-cli` -> `src/kimi_cli/__main__.py` (routes to `src/kimi_cli/cli/__init__.py`).\n- User config: `~/.kimi/config.toml`; logs, sessions, and MCP config live in `~/.kimi/`.\n\n## Git commit messages\n\nConventional Commits format:\n\n```\n(): \n```\n\nAllowed types:\n`feat`, `fix`, `test`, `refactor`, `chore`, `style`, `docs`, `perf`, `build`, `ci`, `revert`.\n\n## Versioning\n\nThe project follows a **minor-bump-only** versioning scheme (`MAJOR.MINOR.PATCH`):\n\n- **Patch** version is always `0`. Never bump it.\n- **Minor** version is bumped for any change: new features, improvements, bug fixes, etc.\n- **Major** version is only changed by explicit manual decision; it stays unchanged during\n normal development.\n\nExamples: `0.68.0` → `0.69.0` → `0.70.0`; never `0.68.1`.\n\nThis rule applies to all packages in the repo (root, `packages/*`, `sdks/*`) as well as release\nand skill workflows.\n\n## Release workflow\n\nFor the full procedure, follow the `release` skill (`.agents/skills/release/SKILL.md`). The summary:\n\n1. Ensure `main` is up to date (pull latest).\n2. Create a release branch, e.g. `bump-0.68` or `bump-pykaos-0.5.3`.\n3. Update `CHANGELOG.md`: add a new `## 0.68 (YYYY-MM-DD)` section below `## Unreleased` (do not rename `## Unreleased`).\n4. Update `pyproject.toml` version.\n5. Run `uv sync` to align `uv.lock`.\n6. Commit the branch and open a PR.\n7. Merge the PR, then switch back to `main` and pull latest.\n8. Tag and push:\n - `git tag 0.68` or `git tag pykaos-0.5.3`\n - `git push --tags`\n9. GitHub Actions handles the release after tags are pushed.\n","docs/AGENTS.md":"# Documentation Agent Guide\n\nThis repository uses VitePress for the documentation site. The current docs are structural scaffolds only; everything beyond the headings is placeholder guidance. The `Reference Code` blocks are there to guide future writing and should be removed once the docs are complete.\n\n## Structure\n\n- Locales live under `docs/en/` and `docs/zh/` with mirrored paths and filenames.\n- Main sections (nav + sidebar) are:\n - Guides: getting-started, use-cases, interaction, sessions, ides, integrations\n - Customization: mcp, skills, agents, print-mode, wire-mode\n - Configuration: config-files, providers, overrides, env-vars, data-locations\n - Reference: kimi-command, kimi-acp, kimi-mcp, slash-commands, keyboard, tools, exit-codes\n - FAQ: setup, interaction, acp, mcp, print-wire, updates\n - Release notes: changelog, breaking-changes\n- Navigation and sidebar are defined in `docs/.vitepress/config.ts`. Any new or renamed page must be wired there for both locales.\n\n## Source of truth\n\n- **Changelog page**: The English version (`docs/en/release-notes/changelog.md`) is the source of truth. It is auto-synced from the root `CHANGELOG.md` via script. The Chinese changelog should be translated from the English version.\n- **All other pages**: The Chinese version (`docs/zh/`) is the source of truth. English translations should be based on the Chinese docs.\n\nOnly the Chinese documentation and the English changelog are manually reviewed. Other translations (e.g., English versions of non-changelog pages) may be auto-generated by AI agents.\n\n## Authoring workflow\n\n- Each page is a scaffold: expand the bullets into prose while keeping the section ordering, and keep the `::: info Reference Code` blocks aligned with the relevant section.\n- For changelog: edit the root `CHANGELOG.md`, then run `npm run sync` to update the English docs.\n- For other pages: edit the Chinese version first, then translate to English.\n\n## Naming conventions\n\n- Filenames are kebab-case and mirror across locales (same slug in `docs/en/` and `docs/zh/`).\n- Use consistent section labels that match the sidebar titles.\n- Use backticks for flags, commands, subcommands, command arguments, file paths, code identifiers, type names, field names, field values, and keyboard shortcuts.\n\n## Wording conventions\n\n- Do not change H1 titles or nav/sidebar labels.\n- English H2+ headings use sentence case (only the first word capitalized unless it is a proper noun). Treat \"Wire\" as a proper noun; do not treat \"agent\", \"shell mode\", or \"print mode\" as proper nouns.\n- Chinese H2+ headings keep English words in sentence case; preserve proper nouns listed in the term table below.\n- Use `API key` in English and `API 密钥` in Chinese; keep `JSON`, `JSONL`, `OAuth`, `macOS`, and `uv` as-is.\n- Use straight double quotes with spaces for quoted content: `\"被引内容\"` (not curly quotes). Add a space before and after the quoted text when adjacent to CJK characters. Use corner brackets `「」` for special terms (e.g., `「工具」`, `「会话」`).\n- Prefer \"终端\" over \"命令行\" in Chinese when both are applicable (e.g., \"运行在终端中\", \"终端界面\", \"终端操作\").\n- Use \"工具调用\" / \"tool call\", not \"工具使用\" / \"tool use\".\n- Use inline code for tool names (e.g., `Task`, `ReadFile`, `Shell`).\n\nTerm mapping (Chinese <-> English, and proper noun handling):\n\n| Chinese | English | Proper noun (zh) | Proper noun (en) |\n| --- | --- | --- | --- |\n| Agent | agent | yes | no |\n| Shell | shell | yes | no |\n| Shell 模式 | shell mode | yes | no |\n| Print 模式 | print mode | yes | no |\n| Wire 模式 | Wire mode | yes | yes (Wire) |\n| Thinking 模式 | thinking mode | yes | no |\n| MCP | MCP | yes | yes |\n| ACP | ACP | yes | yes |\n| Kimi Code CLI | Kimi Code CLI | yes | yes |\n| Agent Skills | Agent Skills | yes | yes |\n| Skill | skill | yes | no |\n| 系统提示词 | system prompt | no | no |\n| 提示词 | prompt | no | no |\n| 会话 | session | no | no |\n| 上下文 | context | no | no |\n| 子 Agent | subagent | yes (Agent) | no |\n| API 密钥 | API key | yes | no |\n| JSON | JSON | yes | yes |\n| JSONL | JSONL | yes | yes |\n| OAuth | OAuth | yes | yes |\n| macOS | macOS | yes | yes |\n| uv | uv | yes | yes |\n| 审批请求 | approval request | no | no |\n| 斜杠命令 | slash command | no | no |\n| 工具调用 | tool call | no | no |\n| Frontmatter | frontmatter | yes | no |\n| User 消息 | user message | yes (User) | no |\n| Assistant 消息 | assistant message | yes (Assistant) | no |\n| Tool 消息 | tool message | yes (Tool) | no |\n| 轮次 | turn | no | no |\n| 供应商 | provider | no | no |\n| Prompt Flow | Prompt Flow | yes | yes |\n| Ralph 循环 | Ralph Loop | yes | yes |\n| Diff | diff | yes | no |\n\nJetBrains IDE terminology (Chinese UI translations):\n\n| English | Chinese |\n| --- | --- |\n| AI Chat | AI 聊天 |\n| Registry | 注册表 |\n| Configure ACP agents | (未翻译) |\n\n## Typography\n\n- **Spacing around mixed content**: Add a space between Chinese characters and English words, numbers, inline code, or links. Exception: no space before full-width punctuation.\n - ✓ 在 Python 中使用 \\`class\\` 关键字\n - ✗ 在Python中使用\\`class\\`关键字\n - ✓ 详见 \\[配置文件\\](./config.md)。\n - ✗ 详见\\[配置文件\\](./config.md)。\n- **Full-width punctuation**: Use full-width punctuation in Chinese text: `，。；：？！（）` not `, . ; : ? ! ( )`.\n- **Code block language**: Always specify language for fenced code blocks (e.g., ` ```sh `, ` ```toml `, ` ```json `). Exception: natural language examples (user prompts) may omit the language.\n- **Callout titles**: Use short category titles for callout blocks (`::: tip`, `::: warning`, `::: info`, `::: danger`). Put the detailed description in the block content, not the title.\n - Chinese: use `提示` for tip, `注意` for warning, `说明` for info, `警告` for danger.\n - English: use no title or short words like `Note` for warning.\n - ✓ `::: tip 提示` + content starting with the key point\n - ✓ `::: warning 注意` + content `\\`KIMI_SHARE_DIR\\` 不影响 Skills 的搜索路径。...`\n - ✗ `::: warning 不影响 Skills` (title too long, should be in content)\n - ✗ `::: tip Skills 路径独立于 KIMI_SHARE_DIR` (title too long)\n- **Version info blocks**: For version change callouts, use `::: info` with a category title (Added/Changed/Removed in English; 新增/变更/移除 in Chinese). The content should be a complete sentence.\n - ✓ `::: info 新增` + content `新增于 Wire 1.2。`\n - ✗ `::: info 新增于 Wire 1.2` (title too long)\n - ✓ `::: info Changed` + content `Renamed in Wire 1.1. ...`\n - ✗ `::: info Renamed in Wire 1.1` (title too long)\n\n## Writing style\n\n- **Natural narrative**: Organize content like writing an article, guiding readers smoothly through the material.\n- **Avoid fragmentation**: Don't turn every point into a subheading; use paragraph transitions instead.\n- **Global perspective**: \"Getting Started\" introduces core concepts only; detailed usage belongs in later pages.\n- **Progressive depth**: Guides → Customization → Configuration → Reference, information deepens gradually.\n- **No \"next steps\"**: VitePress already provides prev/next navigation; don't add manual `::: tip 接下来` blocks at page end.\n\n### Example: good vs bad\n\nOutline prompt:\n\n```\n* Install and upgrade\n * System requirements: Python 3.12+, recommend uv\n * Install, upgrade, uninstall steps\n```\n\n**Bad** (mechanical conversion to headings):\n\n```markdown\n## Install and upgrade\n\n### System requirements\n\n- Python 3.12+\n- Recommend uv\n\n### Install\n\n...\n\n### Upgrade\n\n...\n```\n\n**Good** (natural narrative):\n\n```markdown\n## Install and upgrade\n\nKimi Code CLI requires Python 3.12+. We recommend using uv for installation and management.\n\nIf you haven't installed uv yet, please refer to the uv installation docs first. Install Kimi Code CLI:\n\n(code block)\n\nVerify the installation:\n\n(code block)\n\nUpgrade to the latest version:\n\n(code block)\n```\n\n## Build and preview\n\n- Docs are built with VitePress from `docs/`.\n- Common commands (run inside `docs/`):\n - `npm install` (or `bun install` if you use bun)\n - `npm run dev`\n - `npm run build`\n - `npm run preview`\n- The build output is `docs/.vitepress/dist`.\n\n## Changelog syncing\n\nThe English changelog (`docs/en/release-notes/changelog.md`) is auto-generated from the root `CHANGELOG.md`. Do not edit it manually.\n\n- The sync script is `docs/scripts/sync-changelog.mjs`.\n- It runs automatically before `npm run dev` and `npm run build`.\n- To run manually: `npm run sync` (from the `docs/` directory).\n- The script converts title format (`## [0.69] - 2025-12-29` → `## 0.69 (2025-12-29)`) and removes HTML comments.\n","examples/custom-tools/README.md":"# Example: Custom Tools\n\nThis example demonstrates how to write custom tools for Kimi Code CLI and add them to your agent spec file.\n\n```sh\ncd examples/custom-tools\nuv sync --reinstall\nuv run main.py\n```\n","examples/sample-plugin/SKILL.md":"---\nname: sample-plugin\ndescription: |\n Sample plugin demonstrating the Skills + Tools model.\n Includes a Python tool (greeting) and a TypeScript tool (calculator).\n---\n\n# Sample Plugin\n\nA demo plugin with two tools in different languages, showing that plugin tools are language-agnostic.\n\n## Tools\n\n| Tool | Language | Description |\n|------|----------|-------------|\n| `py_greet` | Python | Generate a greeting in en/zh/ja |\n| `ts_calc` | TypeScript | Evaluate a math expression |\n\n## Usage\n\n- \"greet Alice in Chinese\" -> use `py_greet` with name=\"Alice\", lang=\"zh\"\n- \"what is 42 * 17 + 3\" -> use `ts_calc` with expression=\"42 * 17 + 3\"\n","examples/sample-plugin/plugin.json":"{\n \"name\": \"sample-plugin\",\n \"version\": \"1.0.0\",\n \"description\": \"Sample plugin demonstrating Skills + Tools with both Python and TypeScript tools\",\n \"tools\": [\n {\n \"name\": \"py_greet\",\n \"description\": \"Generate a greeting message (Python tool)\",\n \"command\": [\"python3\", \"scripts/greet.py\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Name to greet\"\n },\n \"lang\": {\n \"type\": \"string\",\n \"enum\": [\"en\", \"zh\", \"ja\"],\n \"description\": \"Language: en=English, zh=Chinese, ja=Japanese\"\n }\n },\n \"required\": [\"name\"]\n }\n },\n {\n \"name\": \"ts_calc\",\n \"description\": \"Evaluate a math expression and return the result (TypeScript tool)\",\n \"command\": [\"npx\", \"tsx\", \"scripts/calc.ts\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"expression\": {\n \"type\": \"string\",\n \"description\": \"Math expression to evaluate, e.g. '2 + 3 * 4'\"\n }\n },\n \"required\": [\"expression\"]\n }\n }\n ]\n}\n","packages/kaos/README.md":"# PyKAOS\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nPyKAOS is a lightweight Python library providing an abstraction layer for agents to interact with operating systems. File operations and command executions via KAOS can be easily switched between local environment and remote systems over SSH.\n","packages/kimi-code/README.md":"# kimi-code (PyPI): legacy package, archived\n\n> [!CAUTION]\n> **This PyPI package is NOT the new Kimi Code CLI.** It is a legacy alias of the archived Python [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) and is no longer maintained.\n>\n> PyPI 上的 `kimi-code` 是已归档的旧版 Python Kimi CLI 的别名包，**不是**新版 Kimi Code CLI。\n\n## Install the new Kimi Code CLI\n\n```sh\n# macOS / Linux\ncurl -fsSL https://code.kimi.com/kimi-code/install.sh | bash\n```\n\n```powershell\n# Windows (PowerShell)\nirm https://code.kimi.com/kimi-code/install.ps1 | iex\n```\n\nAlso available via Homebrew (`brew install kimi-code`) and npm (`npm install -g @moonshot-ai/kimi-code`).\n\nThen uninstall this package: `uv tool uninstall kimi-code` (or `pip uninstall kimi-code kimi-cli`, since pip does not remove the legacy `kimi-cli` dependency automatically).\n\nMigration guide: [English](https://moonshotai.github.io/kimi-code/en/guides/migration) | [中文](https://moonshotai.github.io/kimi-code/zh/guides/migration)\n\n## Note for existing users\n\nStarting from 1.51.0, running `kimi-code` from this package only prints the instructions above. The legacy CLI it used to install is no longer supported and will stop working, so please migrate to Kimi Code CLI.\n","packages/kosong/README.md":"# Kosong\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nKosong is an LLM abstraction layer designed for modern AI agent applications. It unifies message structures, asynchronous tool orchestration, and pluggable chat providers so you can build agents with ease and avoid vendor lock-in.\n\n> Kosong means \"empty\" in Malay and Indonesian.\n\n## Installation\n\nKosong requires Python 3.12 or higher. We recommend using uv as the package manager.\n\nInit your project with:\n\n```bash\nuv init --python 3.12 # or higher\n```\n\nThen add Kosong as a dependency:\n\n```bash\nuv add kosong\n```\n\nTo enable chat providers other than Kimi (e.g. Anthropic and Google Gemini), install the optional extra:\n\n```bash\nuv add 'kosong[contrib]'\n```\n\n## Examples\n\n### Simple chat completion\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Streaming output\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider import StreamedMessagePart\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n def output(message_part: StreamedMessagePart):\n print(message_part)\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n on_message_part=output,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Tool calling with `kosong.step`\n\n```python\nimport asyncio\n\nfrom pydantic import BaseModel\n\nimport kosong\nfrom kosong import StepResult\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\nfrom kosong.tooling import CallableTool2, ToolOk, ToolReturnValue\nfrom kosong.tooling.simple import SimpleToolset\n\n\nclass AddToolParams(BaseModel):\n a: int\n b: int\n\n\nclass AddTool(CallableTool2[AddToolParams]):\n name: str = \"add\"\n description: str = \"Add two integers.\"\n params: type[AddToolParams] = AddToolParams\n\n async def __call__(self, params: AddToolParams) -> ToolReturnValue:\n return ToolOk(output=str(params.a + params.b))\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n toolset = SimpleToolset()\n toolset += AddTool()\n\n history = [\n Message(role=\"user\", content=\"Please add 2 and 3 with the add tool.\"),\n ]\n\n result: StepResult = await kosong.step(\n chat_provider=kimi,\n system_prompt=\"You are a precise math tutor.\",\n toolset=toolset,\n history=history,\n )\n print(result.message)\n print(await result.tool_results())\n\n\nasyncio.run(main())\n```\n\n## Builtin Demo\n\nKosong comes with a builtin demo agent that you can run locally. To start the demo, run:\n\n```sh\nexport KIMI_BASE_URL=\"https://api.moonshot.ai/v1\"\nexport KIMI_API_KEY=\"your_kimi_api_key\"\n\nuv run python -m kosong kimi --with-bash\n```\n\n## Development\n\nTo set up a development environment, clone the repository and install the dependencies:\n\n```bash\ngit clone https://github.com/MoonshotAI/kosong.git\ncd kosong\nuv sync --all-extras\n\nmake check # run lint and type checks\nmake test # run tests\nmake format # format code\n```\n","src/kimi_cli/agents/default/system.md":"You are Kimi Code CLI, an interactive general AI agent running on a user's computer.\n\nYour primary goal is to help users with software engineering tasks by taking action — use the tools available to you to make real changes on the user's system. You should also answer questions when asked. Always adhere strictly to the following system instructions and the user's requirements.\n\n${ROLE_ADDITIONAL}\n\n# Prompt and Tool Use\n\nThe user's messages may contain questions and/or task descriptions in natural language, code snippets, logs, file paths, or other forms of information. Read them, understand them and do what the user requested. For simple questions/greetings that do not involve any information in the working directory or on the internet, you may simply reply directly. For anything else, default to taking action with tools. When the request could be interpreted as either a question to answer or a task to complete, treat it as a task.\n\nWhen handling the user's request, if it involves creating, modifying, or running code or files, you MUST use the appropriate tools (e.g., `WriteFile`, `Shell`) to make actual changes — do not just describe the solution in text. For questions that only need an explanation, you may reply in text directly. When calling tools, do not provide explanations because the tool calls themselves should be self-explanatory. You MUST follow the description of each tool and its parameters when calling tools.\n\nIf the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. The tool can either start a new instance or resume an existing one by `agent_id`. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context because a newly created subagent instance does not automatically see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it instead of creating a new instance. Default to foreground subagents. Use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes, and you do not need the result immediately to decide your next step.\n\nYou have the capability to output any number of tool calls in a single response. If you anticipate making multiple non-interfering tool calls, you are HIGHLY RECOMMENDED to make them in parallel to significantly improve efficiency. This is very important to your performance.\n\nThe results of the tool calls will be returned to you in a tool message. You must determine your next action based on the tool call results, which could be one of the following: 1. Continue working on the task, 2. Inform the user that the task is completed or has failed, or 3. Ask the user for more information.\n\nThe system may insert information wrapped in `` tags within user or tool messages. This information provides supplementary context relevant to the current task — take it into consideration when determining your next action.\n\nTool results and user messages may also include `` tags. Unlike `` tags, these are **authoritative system directives** that you MUST follow. They bear no direct relation to the specific tool results or user messages in which they appear. Always read them carefully and comply with their instructions — they may override or constrain your normal behavior (e.g., restricting you to read-only actions during plan mode).\n\nIf the `Shell`, `TaskList`, `TaskOutput`, and `TaskStop` tools are available and you are the root agent, you can use Background Bash for long-running shell commands. Launch it via `Shell` with `run_in_background=true` and a short `description`. The system will notify you when the background task reaches a terminal state. Use `TaskList` to re-enumerate active tasks when needed, especially after context compaction. Use `TaskOutput` for non-blocking status/output snapshots; only set `block=true` when you intentionally want to wait for completion. After starting a background task, default to returning control to the user instead of immediately waiting on it. Use `TaskStop` only when you need to cancel the task. For human users in the interactive shell, the only task-management slash command is `/task`. Do not tell users to run `/task list`, `/task output`, `/task stop`, `/tasks`, or any other invented slash subcommands. If you are a subagent or these tools are not available, do not assume you can create or control background tasks.\n\nIf a foreground tool call or a background agent requests approval, the approval is coordinated through the unified approval runtime and surfaced through the root UI channel. Do not assume approvals are local to a single subagent turn.\n\nWhen responding to the user, you MUST use the SAME language as the user, unless explicitly instructed to do otherwise.\n\n# General Guidelines for Coding\n\nWhen building something from scratch, you should:\n\n- Understand the user's requirements.\n- Ask the user for clarification if there is anything unclear.\n- Design the architecture and make a plan for the implementation.\n- Write the code in a modular and maintainable way.\n\nAlways use tools to implement your code changes:\n\n- Use `WriteFile` to create or overwrite source files. Code that only appears in your text response is NOT saved to the file system and will not take effect.\n- Use `Shell` to run and test your code after writing it.\n- Iterate: if tests fail, read the error, fix the code with `WriteFile` or `StrReplaceFile`, and re-test with `Shell`.\n\nWhen working on an existing codebase, you should:\n\n- Understand the codebase by reading it with tools (`ReadFile`, `Glob`, `Grep`) before making changes. Identify the ultimate goal and the most important criteria to achieve the goal.\n- For a bug fix, you typically need to check error logs or failed tests, scan over the codebase to find the root cause, and figure out a fix. If user mentioned any failed tests, you should make sure they pass after the changes.\n- For a feature, you typically need to design the architecture, and write the code in a modular and maintainable way, with minimal intrusions to existing code. Add new tests if the project already has tests.\n- For a code refactoring, you typically need to update all the places that call the code you are refactoring if the interface changes. DO NOT change any existing logic especially in tests, focus only on fixing any errors caused by the interface changes.\n- Make MINIMAL changes to achieve the goal. This is very important to your performance.\n- Follow the coding style of existing code in the project.\n- For broader codebase exploration and deep research, use the `Agent` tool with `subagent_type=\"explore\"`. This is a fast, read-only agent specialized for searching and understanding codebases. Use it when your task will clearly require more than 3 search queries, or when you need to investigate multiple files and patterns. You can launch multiple explore agents concurrently to investigate independent questions in parallel.\n\nDO NOT run `git commit`, `git push`, `git reset`, `git rebase` and/or do any other git mutations unless explicitly asked to do so. Ask for confirmation each time when you need to do git mutations, even if the user has confirmed in earlier conversations.\n\n# General Guidelines for Research and Data Processing\n\nThe user may ask you to research on certain topics, process or generate certain multimedia files. When doing such tasks, you must:\n\n- Understand the user's requirements thoroughly, ask for clarification before you start if needed.\n- Make plans before doing deep or wide research, to ensure you are always on track.\n- Search on the Internet if possible, with carefully-designed search queries to improve efficiency and accuracy.\n- Use proper tools or shell commands or Python packages to process or generate images, videos, PDFs, docs, spreadsheets, presentations, or other multimedia files. Detect if there are already such tools in the environment. If you have to install third-party tools/packages, you MUST ensure that they are installed in a virtual/isolated environment.\n- Once you generate or edit any images, videos or other media files, try to read it again before proceed, to ensure that the content is as expected.\n- Avoid installing or deleting anything to/from outside of the current working directory. If you have to do so, ask the user for confirmation.\n\n# Working Environment\n\n## Operating System\n\nYou are running on **${KIMI_OS}**. The Shell tool executes commands using **${KIMI_SHELL}**.{% if KIMI_OS == \"Windows\" %} Use Unix shell syntax inside Shell commands — `/dev/null` not `NUL`, forward slashes in paths (backslashes are escape characters in bash).{% endif +%}\n\nThe operating environment is not in a sandbox. Any actions you do will immediately affect the user's system. So you MUST be extremely cautious. Unless being explicitly instructed to do so, you should never access (read/write/execute) files outside of the working directory.\n\n## Date and Time\n\nThe current date and time in ISO format is `${KIMI_NOW}`. This is only a reference for you when searching the web, or checking file modification time, etc. If you need the exact time, use Shell tool with proper command.\n\n## Working Directory\n\nThe current working directory is `${KIMI_WORK_DIR}`. This should be considered as the project root if you are instructed to perform tasks on the project. Every file system operation will be relative to the working directory if you do not explicitly specify the absolute path. Tools may require absolute paths for some parameters, IF SO, YOU MUST use absolute paths for these parameters.\n\nThe directory listing of current working directory is:\n\n```\n${KIMI_WORK_DIR_LS}\n```\n\nUse this as your basic understanding of the project structure. The tree only shows the first two levels; entries marked \"... and N more\" indicate additional contents — use Glob or Shell to explore further.\n{% if KIMI_ADDITIONAL_DIRS_INFO %}\n\n## Additional Directories\n\nThe following directories have been added to the workspace. You can read, write, search, and glob files in these directories as part of your workspace scope.\n\n${KIMI_ADDITIONAL_DIRS_INFO}\n{% endif %}\n\n# Project Information\n\nMarkdown files named `AGENTS.md` usually contain the background, structure, coding styles, user preferences and other relevant information about the project. You should use this information to understand the project and the user's preferences. `AGENTS.md` files may exist at different locations in the project, but typically there is one in the project root.\n\n> Why `AGENTS.md`?\n>\n> `README.md` files are for humans: quick starts, project descriptions, and contribution guidelines. `AGENTS.md` complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.\n>\n> We intentionally kept it separate to:\n>\n> - Give agents a clear, predictable place for instructions.\n> - Keep `README`s concise and focused on human contributors.\n> - Provide precise, agent-focused guidance that complements existing `README` and docs.\n\nThe `AGENTS.md` instructions (merged from all applicable directories):\n\n`````````\n${KIMI_AGENTS_MD}\n`````````\n\n`AGENTS.md` files can appear at any level of the project directory tree, including inside `.kimi/` directories. Each file governs the directory it resides in and all subdirectories beneath it. When multiple `AGENTS.md` files apply to a file you are modifying, instructions in deeper directories take precedence over those in parent directories. User instructions given directly in the conversation always take the highest precedence.\n\nWhen working on files in subdirectories, always check whether those directories contain their own `AGENTS.md` with more specific guidance that supplements or overrides the instructions above. You may also check `README`/`README.md` files for more information about the project.\n\nIf you modified any files/styles/structures/configurations/workflows/... mentioned in `AGENTS.md` files, you MUST update the corresponding `AGENTS.md` files to keep them up-to-date.\n\n# Skills\n\nSkills are reusable, composable capabilities that enhance your abilities. Each skill is a self-contained directory with a `SKILL.md` file that contains instructions, examples, and/or reference material.\n\n## What are skills?\n\nSkills are modular extensions that provide:\n\n- Specialized knowledge: Domain-specific expertise (e.g., PDF processing, data analysis)\n- Workflow patterns: Best practices for common tasks\n- Tool integrations: Pre-configured tool chains for specific operations\n- Reference material: Documentation, templates, and examples\n\n## Available skills\n\nSkills are grouped by scope (`Project`, `User`, `Extra`, `Built-in`) so you can tell where each came from. When the user refers to \"the skill in this project\" or \"the user-scope skill\", use the scope heading to disambiguate. When multiple scopes define a skill with the same name, the more specific scope takes precedence: **Project overrides User overrides Extra overrides Built-in**.\n\n${KIMI_SKILLS}\n\n## How to use skills\n\nIdentify the skills that are likely to be useful for the tasks you are currently working on, read the `SKILL.md` file for detailed instructions, guidelines, scripts and more.\n\nOnly read skill details when needed to conserve the context window.\n\n# Ultimate Reminders\n\nAt any time, you should be HELPFUL, CONCISE, and ACCURATE. Be thorough in your actions — test what you build, verify what you change — not in your explanations.\n\n- Never diverge from the requirements and the goals of the task you work on. Stay on track.\n- Never give the user more than what they want.\n- Try your best to avoid any hallucination. Do fact checking before providing any factual information.\n- Think about the best approach, then take action decisively.\n- Do not give up too early.\n- ALWAYS, keep it stupidly simple. Do not overcomplicate things.\n- When the task requires creating or modifying files, always use tools to do so. Never treat displaying code in your response as a substitute for actually writing it to the file system.\n","src/kimi_cli/skills/kimi-cli-help/SKILL.md":"---\nname: kimi-cli-help\ndescription: Answer Kimi Code CLI usage, configuration, and troubleshooting questions. Use when user asks about Kimi Code CLI installation, setup, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, how something works internally, or any questions about Kimi Code CLI itself.\n---\n\n# Kimi Code CLI Help\n\nHelp users with Kimi Code CLI questions by consulting documentation and source code.\n\n## Strategy\n\n1. **Prefer official documentation** for most questions\n2. **Read local source** when in kimi-cli project itself, or when user is developing with kimi-cli as a library (e.g., importing from `kimi_cli` in their code)\n3. **Clone and explore source** for complex internals not covered in docs - **ask user for confirmation first**\n\n## Documentation\n\nBase URL: `https://moonshotai.github.io/kimi-cli/`\n\nFetch documentation index to find relevant pages:\n\n```\nhttps://moonshotai.github.io/kimi-cli/llms.txt\n```\n\n### Page URL Pattern\n\n- English: `https://moonshotai.github.io/kimi-cli/en/...`\n- Chinese: `https://moonshotai.github.io/kimi-cli/zh/...`\n\n### Topic Mapping\n\n| Topic | Page |\n|-------|------|\n| Installation, first run | `/en/guides/getting-started.md` |\n| Config files | `/en/configuration/config-files.md` |\n| Providers, models | `/en/configuration/providers.md` |\n| Environment variables | `/en/configuration/env-vars.md` |\n| Slash commands | `/en/reference/slash-commands.md` |\n| CLI flags | `/en/reference/kimi-command.md` |\n| Keyboard shortcuts | `/en/reference/keyboard.md` |\n| MCP | `/en/customization/mcp.md` |\n| Agents | `/en/customization/agents.md` |\n| Skills | `/en/customization/skills.md` |\n| FAQ | `/en/faq.md` |\n\n## Source Code\n\nRepository: `https://github.com/MoonshotAI/kimi-cli`\n\nWhen to read source:\n\n- In kimi-cli project directory (check `pyproject.toml` for `name = \"kimi-cli\"`)\n- User is importing `kimi_cli` as a library in their project\n- Question about internals not covered in docs (ask user before cloning)\n","src/kimi_cli/skills/skill-creator/SKILL.md":"---\nname: skill-creator\ndescription: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Kimi's capabilities with specialized knowledge, workflows, or tool integrations.\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Kimi's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Kimi from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n## Core Principles\n\n### Concise is Key\n\nThe context window is a public good. Skills share the context window with everything else Kimi needs: system prompt, conversation history, other Skills' metadata, and the actual user request.\n\n**Default assumption: Kimi is already very smart.** Only add context Kimi doesn't already have. Challenge each piece of information: \"Does Kimi really need this explanation?\" and \"Does this paragraph justify its token cost?\"\n\nPrefer concise examples over verbose explanations.\n\n### Set Appropriate Degrees of Freedom\n\nMatch the level of specificity to the task's fragility and variability:\n\n**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.\n\n**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.\n\n**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.\n\nThink of Kimi as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\nEvery SKILL.md consists of:\n\n- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Kimi reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.\n- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Kimi for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Kimi's process and thinking.\n\n- **When to include**: For documentation that Kimi should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Kimi determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Kimi produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Kimi to use files without loading them into context\n\n#### What to Not Include in a Skill\n\nA skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:\n\n- README.md\n- INSTALLATION_GUIDE.md\n- QUICK_REFERENCE.md\n- CHANGELOG.md\n- etc.\n\nThe skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Kimi (Unlimited because scripts can be executed without reading into context window)\n\n#### Progressive Disclosure Patterns\n\nKeep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.\n\n**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.\n\n**Pattern 1: High-level guide with references**\n\n```markdown\n# PDF Processing\n\n## Quick start\n\nExtract text with pdfplumber:\n[code example]\n\n## Advanced features\n\n- **Form filling**: See [FORMS.md](FORMS.md) for complete guide\n- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods\n- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns\n```\n\nKimi loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.\n\n**Pattern 2: Domain-specific organization**\n\nFor Skills with multiple domains, organize content by domain to avoid loading irrelevant context:\n\n```\nbigquery-skill/\n├── SKILL.md (overview and navigation)\n└── reference/\n ├── finance.md (revenue, billing metrics)\n ├── sales.md (opportunities, pipeline)\n ├── product.md (API usage, features)\n └── marketing.md (campaigns, attribution)\n```\n\nWhen a user asks about sales metrics, Kimi only reads sales.md.\n\nSimilarly, for skills supporting multiple frameworks or variants, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + provider selection)\n└── references/\n ├── aws.md (AWS deployment patterns)\n ├── gcp.md (GCP deployment patterns)\n └── azure.md (Azure deployment patterns)\n```\n\nWhen the user chooses AWS, Kimi only reads aws.md.\n\n**Pattern 3: Conditional details**\n\nShow basic content, link to advanced content:\n\n```markdown\n# DOCX Processing\n\n## Creating documents\n\nUse docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).\n\n## Editing documents\n\nFor simple edits, modify the XML directly.\n\n**For tracked changes**: See [REDLINING.md](REDLINING.md)\n**For OOXML details**: See [OOXML.md](OOXML.md)\n```\n\nKimi reads REDLINING.md or OOXML.md only when the user needs those features.\n\n**Important guidelines:**\n\n- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.\n- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Kimi can see the full scope when previewing.\n\n## Skill Locations and Discovery\n\nKimi Code CLI loads skills in layers (built-in -> user -> project). Within each layer, it uses the\nfirst existing directory in priority order. Built-in skills only load for LocalKaos or ACPKaos.\n\n**User level** (by priority):\n- `~/.config/agents/skills/` (recommended)\n- `~/.kimi/skills/`\n- `~/.claude/skills/`\n\n**Project level**:\n- `.agents/skills/`\n\n`--skills-dir` overrides discovery and loads only that directory (built-ins still load when\nsupported).\n\n## Skill Creation Process\n\nSkill creation involves these steps:\n\n1. Understand the skill with concrete examples\n2. Plan reusable skill contents (scripts, references, assets)\n3. Initialize the skill (run init_skill.py)\n4. Edit the skill (implement resources and write SKILL.md)\n5. Package the skill (run package_skill.py)\n6. Iterate based on real usage\n\nFollow these steps in order, skipping only if there is a clear reason why they are not applicable.\n\n### Skill Naming\n\n- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., \"Plan Mode\" -> `plan-mode`).\n- When generating names, generate a name under 64 characters (letters, digits, hyphens).\n- Prefer short, verb-led phrases that describe the action.\n- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).\n- Name the skill folder exactly after the skill name.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, create a new skill directory with a required `SKILL.md`\nfile and any optional resource directories that the skill needs (`scripts/`, `references/`,\n`assets/`). Create only the directories you intend to populate.\n\nAfter initialization, customize the SKILL.md and add resources as needed.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Kimi to use. Include information that would be beneficial and non-obvious to Kimi. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Kimi instance execute these tasks more effectively.\n\n#### Learn Proven Design Patterns\n\nCapture proven design patterns directly in this SKILL.md:\n\n- **Multi-step processes**: Clearly describe sequential workflows and conditional branches, including triggers, decision points, and expected outputs at each step.\n- **Specific output formats or quality standards**: Document required output shapes, templates, and examples directly in this SKILL.md so they are easy to follow.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAdded scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.\n\nDelete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.\n\n#### Update SKILL.md\n\n**Writing Guidelines:** Always use imperative/infinitive form.\n\n##### Frontmatter\n\nWrite the YAML frontmatter with `name` and `description`:\n\n- `name`: The skill name\n- `description`: This is the primary triggering mechanism for your skill, and helps Kimi understand when to use the skill.\n - Include both what the Skill does and specific triggers/contexts for when to use it.\n - Include all \"when to use\" information here - Not in the body. The body is only loaded after triggering, so \"When to Use This Skill\" sections in the body are not helpful to Kimi.\n - Example description for a `docx` skill: \"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Kimi needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks\"\n\nDo not include any other fields in YAML frontmatter.\n\n##### Body\n\nWrite instructions for using the skill and its bundled resources.\n\n### Step 5: Packaging a Skill\n\nOnce development of the skill is complete, package it into a distributable `.skill` file (a zip\narchive). Before packaging, validate that the skill meets all requirements:\n\n1. **Validate** the skill, checking:\n\n - YAML frontmatter format and required fields\n - Skill naming conventions and directory structure\n - Description completeness and quality\n - File organization and resource references\n\n2. **Package** the skill if validation passes:\n\n - Create an archive of the skill's root folder (the folder containing `SKILL.md` and all related files).\n - Ensure the archive preserves the internal directory structure.\n - Name the archive `.skill` (for example, `my-skill.skill`). The `.skill` file is a zip file with a `.skill` extension.\n\nExample packaging command:\n\n```bash\ncd \nzip -r my-skill.skill my-skill\n```\n\nIf validation fails (for example, due to malformed frontmatter, missing files, or an incomplete\ndescription), fix the issues and repackage the skill.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n","src/kimi_cli/tools/AGENTS.md":"# Kimi Code CLI Tools\n\n## Guidelines\n\n- Tools should not refer to types in `kimi_cli/wire/` unless they are explicitly implementing a UI / runtime bridge. When importing things like `ToolReturnValue` or `DisplayBlock`, prefer `kosong.tooling`.\n","tests_e2e/AGENTS.md":"# tests_e2e Wire E2E Guide\n\n## Goals and Scope\n- Test only `kimi --wire` JSON-RPC + wire messages; no Shell UI/Print/ACP/Term/shortcuts.\n- Do not test `--agent okabe`.\n- Do not test: W-23, W-26, W-29, W-27 (env overrides).\n\n## Execution Rules\n- Tests run via `uv run kimi` by default; set `KIMI_E2E_WIRE_CMD` to override the base command\n (e.g. `../kimi-agent-rs/target/debug/kimi-agent` or `kimi-agent` on PATH). `--wire` is appended if missing.\n- Always isolate `HOME`, `USERPROFILE`, and `KIMI_SHARE_DIR`, and use a temporary `--work-dir` to\n avoid touching real `~/.kimi`.\n- Use `inline_snapshot` for snapshot testing; snapshots can start empty and be updated later.\n- Wire traffic is line-delimited JSON; `event`/`request`/responses may interleave.\n\n## Test Matrix\n**Startup and Protocol**\n- W-01 Handshake: `initialize` returns `protocol_version=1.1`, `server`, and non-empty\n `slash_commands`.\n- W-02 External tool registration and call: register `external_tools`, trigger a\n `ToolCallRequest`, return `ToolResult`, turn finishes.\n- W-03 External tool conflict: registering a tool name that conflicts with a built-in is\n rejected with a reason.\n- W-04 Prompt without handshake: send `prompt` without `initialize`, turn still completes.\n- W-05 LLM not set: missing config yields `-32001` (LLM is not set).\n- W-06 Max steps: set a tiny `--max-steps-per-turn`, response is `status=max_steps_reached`.\n\n**Prompt and Event Stream**\n- W-07 Basic turn: `TurnBegin`/`StepBegin`/`ContentPart(text)`/`StatusUpdate` flow.\n- W-08 Multiline input: `TurnBegin.user_input` preserves newlines.\n- W-09 Content parts input: `user_input` as `ContentPart[]` (text/image/audio/video) with\n capabilities enabled.\n- W-10 Thinking toggle: `--thinking` emits `ContentPart(type=think)`, `--no-thinking` does not\n (real LLM).\n- W-11 Concurrent prompt: second `prompt` returns `-32000` (turn already in progress).\n- W-12 Cancel turn: `cancel` returns `{}`, original `prompt` becomes `status=cancelled`\n (may emit `StepInterrupted`, real LLM).\n\n**Tools and Approvals**\n- W-13 Shell approval: `Shell` triggers `ApprovalRequest`, `approve` yields `ToolResult`.\n- W-14 Approval reject: `reject` ends turn; tool does not run.\n- W-15 Session approval: `approve_for_session` removes subsequent blocking approvals.\n- W-16 YOLO: `--yolo` skips blocking approvals.\n- W-17 DisplayBlock coverage: `Shell`/`WriteFile`/`StrReplaceFile`/`SetTodoList` emit expected\n display types.\n- W-18 Tool args streaming: `ToolCallPart.arguments_part` can be stitched into full args.\n\n**Sessions and Context**\n- W-19 Session files: `--session ` writes `context.jsonl` and `wire.jsonl`.\n- W-20 Continue session: `--continue` appends to the same session files.\n- W-21 Clear context: `/clear` ensures the next `prompt` does not rely on prior context.\n- W-22 Manual compaction: `/compact` triggers `CompactionBegin/CompactionEnd`.\n- W-24 Status stats: `StatusUpdate.context_usage/token_usage` types are valid and change over time.\n\n**Config and Runtime Flags**\n- W-25 `--config` inline: JSON/TOML string config works.\n- W-28 CLI override: `--model` overrides `default_model`.\n- W-30 Work dir: `prompt` asks \"where is the current directory\", verify `--work-dir` (real LLM).\n\n**Extensions (Agents/Skills/MCP)**\n- W-31 Built-in agent boundary: `default` calling `SendDMail` fails or is rejected.\n- W-32 Custom agent: `--agent-file` excludes tool and calls are rejected.\n- W-33 Subagents: prompt \"parallel call two task tools, each runs shell sleep 0.5 and 1 second\";\n verify Task/SubagentEvent streaming/ToolResult/multiple approvals (real LLM).\n- W-34 Skill call: create a test skill, `/skill:test` injects `SKILL.md` (wire has no `/help`).\n- W-35 Flow skill: `/flow:` runs the flow until `END`.\n- W-36 MCP: use a Python fastmcp test server, load via `--mcp-config-file`, verify tool works.\n\n**Resilience and Errors**\n- W-37 Invalid JSON: malformed JSON line returns `-32700`.\n- W-38 Invalid request: missing fields returns `-32600`.\n- W-39 Unknown method: returns `-32601`.\n- W-40 Invalid params: bad structure returns `-32602`.\n- W-41 Cancel without active turn: returns `-32000`.\n- W-42 LLM errors: unsupported model `-32002` and service error `-32003`.\n\n## Real LLM Placeholders\n- W-10/W-12/W-30/W-33 require a real provider; everything else uses `_scripted_echo`.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Kimi Code CLI\n\n## Quick commands (use uv)\n\n- `make prepare` (sync deps for all workspace packages and install git hooks)\n- `make format`\n- `make check`\n- `make test`\n- `make ai-test`\n- `make build` / `make build-bin`\n\nIf running tools directly, use `uv run ...`.\n\n## Project overview\n\nKimi Code CLI is a Python CLI agent for software engineering workflows. It supports an interactive\nshell UI, ACP server mode for IDE integrations, and MCP tool loading.\n\n## Tech stack\n\n- Python 3.12+ (tooling configured for 3.14)\n- CLI framework: Typer\n- Async runtime: asyncio\n- LLM framework: kosong\n- MCP integration: fastmcp\n- Logging: loguru\n- Package management/build: uv + uv_build; PyInstaller for binaries\n- Tests: pytest + pytest-asyncio; lint/format: ruff; types: pyright + ty\n\n## Architecture overview\n\n- **CLI entry**: `src/kimi_cli/cli/__init__.py` (Typer) parses flags (UI mode, agent spec, config, MCP)\n and routes into `KimiCLI` in `src/kimi_cli/app.py`.\n- **App/runtime setup**: `KimiCLI.create` loads config (`src/kimi_cli/config.py`), chooses a\n model/provider (`src/kimi_cli/llm.py`), builds a `Runtime` (`src/kimi_cli/soul/agent.py`),\n loads an agent spec, restores `Context`, then constructs `KimiSoul`.\n- **Agent specs**: YAML under `src/kimi_cli/agents/` loaded by `src/kimi_cli/agentspec.py`.\n Specs can `extend` base agents, select tools by import path, and register builtin subagent\n types via the `subagents` field. Subagent instances are persisted separately under the session\n directory and can be resumed by `agent_id`. System prompts live alongside specs; builtin args\n include `KIMI_NOW`, `KIMI_WORK_DIR`, `KIMI_WORK_DIR_LS`, `KIMI_AGENTS_MD`, `KIMI_SKILLS`, `KIMI_OS`, `KIMI_SHELL`\n (this file is injected via `KIMI_AGENTS_MD`).\n- **Tooling**: `src/kimi_cli/soul/toolset.py` loads tools by import path, injects dependencies,\n and runs tool calls. Built-in tools live in `src/kimi_cli/tools/` (agent, shell, file, web,\n todo, background, dmail, think, plan). MCP tools are loaded via `fastmcp`; CLI management is\n in `src/kimi_cli/mcp.py` and stored in the share dir.\n- **Subagents**: `LaborMarket` in `src/kimi_cli/soul/agent.py` registers builtin subagent types.\n The `Agent` tool (`src/kimi_cli/tools/agent/`) creates or resumes subagent instances, while\n `SubagentStore` persists instance metadata, prompts, wire logs, and context under\n `session/subagents//`.\n- **Core loop**: `src/kimi_cli/soul/kimisoul.py` is the main agent loop. It accepts user input,\n handles slash commands (`src/kimi_cli/soul/slash.py`), appends to `Context`\n (`src/kimi_cli/soul/context.py`), calls the LLM (kosong), runs tools, and performs compaction\n (`src/kimi_cli/soul/compaction.py`) when needed.\n- **Approvals**: `src/kimi_cli/soul/approval.py` is the tool-facing facade. `ApprovalRuntime`\n in `src/kimi_cli/approval_runtime/` is the session-level source of truth for pending approvals,\n and approval requests are projected onto the root wire stream for Shell/Web style UIs.\n- **UI/Wire**: `src/kimi_cli/soul/run_soul` connects `KimiSoul` to a `Wire`\n (`src/kimi_cli/wire/`) so UI loops can stream events. UIs live in `src/kimi_cli/ui/`\n (shell/print/acp/wire).\n- **Shell UI**: `src/kimi_cli/ui/shell/` handles interactive TUI input, shell command mode,\n and slash command autocomplete; it is the default interactive experience.\n- **Slash commands**: Soul-level commands live in `src/kimi_cli/soul/slash.py`; shell-level\n commands live in `src/kimi_cli/ui/shell/slash.py`. The shell UI exposes both and dispatches\n based on the registry. Standard skills register `/skill:` and load `SKILL.md`\n as a user prompt; flow skills register `/flow:` and execute the embedded flow.\n\n## Major modules and interfaces\n\n- `src/kimi_cli/app.py`: `KimiCLI.create(...)` and `KimiCLI.run(...)` are the main programmatic\n entrypoints; this is what UI layers use.\n- `src/kimi_cli/soul/agent.py`: `Runtime` (config, session, builtins), `Agent` (system prompt +\n toolset), and `LaborMarket` (builtin subagent type registry).\n- `src/kimi_cli/soul/kimisoul.py`: `KimiSoul.run(...)` is the loop boundary; it emits Wire\n messages and executes tools via `KimiToolset`.\n- `src/kimi_cli/soul/context.py`: conversation history + checkpoints; used by DMail for\n checkpointed replies.\n- `src/kimi_cli/soul/toolset.py`: load tools, run tool calls, bridge to MCP tools.\n- `src/kimi_cli/ui/*`: shell/print/acp frontends; they consume `Wire` messages.\n- `src/kimi_cli/wire/*`: event types and transport used between soul and UI.\n\n## Repo map\n\n- `src/kimi_cli/agents/`: built-in agent YAML specs and prompts\n- `src/kimi_cli/prompts/`: shared prompt templates\n- `src/kimi_cli/soul/`: core runtime/loop, context, compaction, approvals\n- `src/kimi_cli/tools/`: built-in tools\n- `src/kimi_cli/ui/`: UI frontends (shell/print/acp/wire)\n- `src/kimi_cli/acp/`: ACP server components\n- `packages/kosong/`, `packages/kaos/`: workspace deps\n + Kosong is an LLM abstraction layer designed for modern AI agent applications.\n It unifies message structures, asynchronous tool orchestration, and pluggable\n chat providers so you can build agents with ease and avoid vendor lock-in.\n + PyKAOS is a lightweight Python library providing an abstraction layer for agents\n to interact with operating systems. File operations and command executions via KAOS\n can be easily switched between local environment and remote systems over SSH.\n- `tests/`, `tests_ai/`: test suites\n- `klips`: Kimi Code CLI Improvement Proposals\n\n## Conventions and quality\n\n- Python >=3.12 (ty config uses 3.14); line length 100.\n- Ruff handles lint + format (rules: E, F, UP, B, SIM, I); pyright + ty for type checks.\n- Tests use pytest + pytest-asyncio; files are `tests/test_*.py`.\n- CLI entry points: `kimi` / `kimi-cli` -> `src/kimi_cli/__main__.py` (routes to `src/kimi_cli/cli/__init__.py`).\n- User config: `~/.kimi/config.toml`; logs, sessions, and MCP config live in `~/.kimi/`.\n\n## Git commit messages\n\nConventional Commits format:\n\n```\n(): \n```\n\nAllowed types:\n`feat`, `fix`, `test`, `refactor`, `chore`, `style`, `docs`, `perf`, `build`, `ci`, `revert`.\n\n## Versioning\n\nThe project follows a **minor-bump-only** versioning scheme (`MAJOR.MINOR.PATCH`):\n\n- **Patch** version is always `0`. Never bump it.\n- **Minor** version is bumped for any change: new features, improvements, bug fixes, etc.\n- **Major** version is only changed by explicit manual decision; it stays unchanged during\n normal development.\n\nExamples: `0.68.0` → `0.69.0` → `0.70.0`; never `0.68.1`.\n\nThis rule applies to all packages in the repo (root, `packages/*`, `sdks/*`) as well as release\nand skill workflows.\n\n## Release workflow\n\nFor the full procedure, follow the `release` skill (`.agents/skills/release/SKILL.md`). The summary:\n\n1. Ensure `main` is up to date (pull latest).\n2. Create a release branch, e.g. `bump-0.68` or `bump-pykaos-0.5.3`.\n3. Update `CHANGELOG.md`: add a new `## 0.68 (YYYY-MM-DD)` section below `## Unreleased` (do not rename `## Unreleased`).\n4. Update `pyproject.toml` version.\n5. Run `uv sync` to align `uv.lock`.\n6. Commit the branch and open a PR.\n7. Merge the PR, then switch back to `main` and pull latest.\n8. Tag and push:\n - `git tag 0.68` or `git tag pykaos-0.5.3`\n - `git push --tags`\n9. GitHub Actions handles the release after tags are pushed.\n","isInternal":false,"tokens":2079,"sizeBytes":7403},{"name":"AGENTS.md","path":"docs/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/docs/AGENTS.md","title":"docs - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Documentation Agent Guide\n\nThis repository uses VitePress for the documentation site. The current docs are structural scaffolds only; everything beyond the headings is placeholder guidance. The `Reference Code` blocks are there to guide future writing and should be removed once the docs are complete.\n\n## Structure\n\n- Locales live under `docs/en/` and `docs/zh/` with mirrored paths and filenames.\n- Main sections (nav + sidebar) are:\n - Guides: getting-started, use-cases, interaction, sessions, ides, integrations\n - Customization: mcp, skills, agents, print-mode, wire-mode\n - Configuration: config-files, providers, overrides, env-vars, data-locations\n - Reference: kimi-command, kimi-acp, kimi-mcp, slash-commands, keyboard, tools, exit-codes\n - FAQ: setup, interaction, acp, mcp, print-wire, updates\n - Release notes: changelog, breaking-changes\n- Navigation and sidebar are defined in `docs/.vitepress/config.ts`. Any new or renamed page must be wired there for both locales.\n\n## Source of truth\n\n- **Changelog page**: The English version (`docs/en/release-notes/changelog.md`) is the source of truth. It is auto-synced from the root `CHANGELOG.md` via script. The Chinese changelog should be translated from the English version.\n- **All other pages**: The Chinese version (`docs/zh/`) is the source of truth. English translations should be based on the Chinese docs.\n\nOnly the Chinese documentation and the English changelog are manually reviewed. Other translations (e.g., English versions of non-changelog pages) may be auto-generated by AI agents.\n\n## Authoring workflow\n\n- Each page is a scaffold: expand the bullets into prose while keeping the section ordering, and keep the `::: info Reference Code` blocks aligned with the relevant section.\n- For changelog: edit the root `CHANGELOG.md`, then run `npm run sync` to update the English docs.\n- For other pages: edit the Chinese version first, then translate to English.\n\n## Naming conventions\n\n- Filenames are kebab-case and mirror across locales (same slug in `docs/en/` and `docs/zh/`).\n- Use consistent section labels that match the sidebar titles.\n- Use backticks for flags, commands, subcommands, command arguments, file paths, code identifiers, type names, field names, field values, and keyboard shortcuts.\n\n## Wording conventions\n\n- Do not change H1 titles or nav/sidebar labels.\n- English H2+ headings use sentence case (only the first word capitalized unless it is a proper noun). Treat \"Wire\" as a proper noun; do not treat \"agent\", \"shell mode\", or \"print mode\" as proper nouns.\n- Chinese H2+ headings keep English words in sentence case; preserve proper nouns listed in the term table below.\n- Use `API key` in English and `API 密钥` in Chinese; keep `JSON`, `JSONL`, `OAuth`, `macOS`, and `uv` as-is.\n- Use straight double quotes with spaces for quoted content: `\"被引内容\"` (not curly quotes). Add a space before and after the quoted text when adjacent to CJK characters. Use corner brackets `「」` for special terms (e.g., `「工具」`, `「会话」`).\n- Prefer \"终端\" over \"命令行\" in Chinese when both are applicable (e.g., \"运行在终端中\", \"终端界面\", \"终端操作\").\n- Use \"工具调用\" / \"tool call\", not \"工具使用\" / \"tool use\".\n- Use inline code for tool names (e.g., `Task`, `ReadFile`, `Shell`).\n\nTerm mapping (Chinese <-> English, and proper noun handling):\n\n| Chinese | English | Proper noun (zh) | Proper noun (en) |\n| --- | --- | --- | --- |\n| Agent | agent | yes | no |\n| Shell | shell | yes | no |\n| Shell 模式 | shell mode | yes | no |\n| Print 模式 | print mode | yes | no |\n| Wire 模式 | Wire mode | yes | yes (Wire) |\n| Thinking 模式 | thinking mode | yes | no |\n| MCP | MCP | yes | yes |\n| ACP | ACP | yes | yes |\n| Kimi Code CLI | Kimi Code CLI | yes | yes |\n| Agent Skills | Agent Skills | yes | yes |\n| Skill | skill | yes | no |\n| 系统提示词 | system prompt | no | no |\n| 提示词 | prompt | no | no |\n| 会话 | session | no | no |\n| 上下文 | context | no | no |\n| 子 Agent | subagent | yes (Agent) | no |\n| API 密钥 | API key | yes | no |\n| JSON | JSON | yes | yes |\n| JSONL | JSONL | yes | yes |\n| OAuth | OAuth | yes | yes |\n| macOS | macOS | yes | yes |\n| uv | uv | yes | yes |\n| 审批请求 | approval request | no | no |\n| 斜杠命令 | slash command | no | no |\n| 工具调用 | tool call | no | no |\n| Frontmatter | frontmatter | yes | no |\n| User 消息 | user message | yes (User) | no |\n| Assistant 消息 | assistant message | yes (Assistant) | no |\n| Tool 消息 | tool message | yes (Tool) | no |\n| 轮次 | turn | no | no |\n| 供应商 | provider | no | no |\n| Prompt Flow | Prompt Flow | yes | yes |\n| Ralph 循环 | Ralph Loop | yes | yes |\n| Diff | diff | yes | no |\n\nJetBrains IDE terminology (Chinese UI translations):\n\n| English | Chinese |\n| --- | --- |\n| AI Chat | AI 聊天 |\n| Registry | 注册表 |\n| Configure ACP agents | (未翻译) |\n\n## Typography\n\n- **Spacing around mixed content**: Add a space between Chinese characters and English words, numbers, inline code, or links. Exception: no space before full-width punctuation.\n - ✓ 在 Python 中使用 \\`class\\` 关键字\n - ✗ 在Python中使用\\`class\\`关键字\n - ✓ 详见 \\[配置文件\\](./config.md)。\n - ✗ 详见\\[配置文件\\](./config.md)。\n- **Full-width punctuation**: Use full-width punctuation in Chinese text: `，。；：？！（）` not `, . ; : ? ! ( )`.\n- **Code block language**: Always specify language for fenced code blocks (e.g., ` ```sh `, ` ```toml `, ` ```json `). Exception: natural language examples (user prompts) may omit the language.\n- **Callout titles**: Use short category titles for callout blocks (`::: tip`, `::: warning`, `::: info`, `::: danger`). Put the detailed description in the block content, not the title.\n - Chinese: use `提示` for tip, `注意` for warning, `说明` for info, `警告` for danger.\n - English: use no title or short words like `Note` for warning.\n - ✓ `::: tip 提示` + content starting with the key point\n - ✓ `::: warning 注意` + content `\\`KIMI_SHARE_DIR\\` 不影响 Skills 的搜索路径。...`\n - ✗ `::: warning 不影响 Skills` (title too long, should be in content)\n - ✗ `::: tip Skills 路径独立于 KIMI_SHARE_DIR` (title too long)\n- **Version info blocks**: For version change callouts, use `::: info` with a category title (Added/Changed/Removed in English; 新增/变更/移除 in Chinese). The content should be a complete sentence.\n - ✓ `::: info 新增` + content `新增于 Wire 1.2。`\n - ✗ `::: info 新增于 Wire 1.2` (title too long)\n - ✓ `::: info Changed` + content `Renamed in Wire 1.1. ...`\n - ✗ `::: info Renamed in Wire 1.1` (title too long)\n\n## Writing style\n\n- **Natural narrative**: Organize content like writing an article, guiding readers smoothly through the material.\n- **Avoid fragmentation**: Don't turn every point into a subheading; use paragraph transitions instead.\n- **Global perspective**: \"Getting Started\" introduces core concepts only; detailed usage belongs in later pages.\n- **Progressive depth**: Guides → Customization → Configuration → Reference, information deepens gradually.\n- **No \"next steps\"**: VitePress already provides prev/next navigation; don't add manual `::: tip 接下来` blocks at page end.\n\n### Example: good vs bad\n\nOutline prompt:\n\n```\n* Install and upgrade\n * System requirements: Python 3.12+, recommend uv\n * Install, upgrade, uninstall steps\n```\n\n**Bad** (mechanical conversion to headings):\n\n```markdown\n## Install and upgrade\n\n### System requirements\n\n- Python 3.12+\n- Recommend uv\n\n### Install\n\n...\n\n### Upgrade\n\n...\n```\n\n**Good** (natural narrative):\n\n```markdown\n## Install and upgrade\n\nKimi Code CLI requires Python 3.12+. We recommend using uv for installation and management.\n\nIf you haven't installed uv yet, please refer to the uv installation docs first. Install Kimi Code CLI:\n\n(code block)\n\nVerify the installation:\n\n(code block)\n\nUpgrade to the latest version:\n\n(code block)\n```\n\n## Build and preview\n\n- Docs are built with VitePress from `docs/`.\n- Common commands (run inside `docs/`):\n - `npm install` (or `bun install` if you use bun)\n - `npm run dev`\n - `npm run build`\n - `npm run preview`\n- The build output is `docs/.vitepress/dist`.\n\n## Changelog syncing\n\nThe English changelog (`docs/en/release-notes/changelog.md`) is auto-generated from the root `CHANGELOG.md`. Do not edit it manually.\n\n- The sync script is `docs/scripts/sync-changelog.mjs`.\n- It runs automatically before `npm run dev` and `npm run build`.\n- To run manually: `npm run sync` (from the `docs/` directory).\n- The script converts title format (`## [0.69] - 2025-12-29` → `## 0.69 (2025-12-29)`) and removes HTML comments.\n","isInternal":false,"tokens":2325,"sizeBytes":8765},{"name":"AGENTS.md","path":"tests_e2e/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/tests_e2e/AGENTS.md","title":"tests_e2e - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# tests_e2e Wire E2E Guide\n\n## Goals and Scope\n- Test only `kimi --wire` JSON-RPC + wire messages; no Shell UI/Print/ACP/Term/shortcuts.\n- Do not test `--agent okabe`.\n- Do not test: W-23, W-26, W-29, W-27 (env overrides).\n\n## Execution Rules\n- Tests run via `uv run kimi` by default; set `KIMI_E2E_WIRE_CMD` to override the base command\n (e.g. `../kimi-agent-rs/target/debug/kimi-agent` or `kimi-agent` on PATH). `--wire` is appended if missing.\n- Always isolate `HOME`, `USERPROFILE`, and `KIMI_SHARE_DIR`, and use a temporary `--work-dir` to\n avoid touching real `~/.kimi`.\n- Use `inline_snapshot` for snapshot testing; snapshots can start empty and be updated later.\n- Wire traffic is line-delimited JSON; `event`/`request`/responses may interleave.\n\n## Test Matrix\n**Startup and Protocol**\n- W-01 Handshake: `initialize` returns `protocol_version=1.1`, `server`, and non-empty\n `slash_commands`.\n- W-02 External tool registration and call: register `external_tools`, trigger a\n `ToolCallRequest`, return `ToolResult`, turn finishes.\n- W-03 External tool conflict: registering a tool name that conflicts with a built-in is\n rejected with a reason.\n- W-04 Prompt without handshake: send `prompt` without `initialize`, turn still completes.\n- W-05 LLM not set: missing config yields `-32001` (LLM is not set).\n- W-06 Max steps: set a tiny `--max-steps-per-turn`, response is `status=max_steps_reached`.\n\n**Prompt and Event Stream**\n- W-07 Basic turn: `TurnBegin`/`StepBegin`/`ContentPart(text)`/`StatusUpdate` flow.\n- W-08 Multiline input: `TurnBegin.user_input` preserves newlines.\n- W-09 Content parts input: `user_input` as `ContentPart[]` (text/image/audio/video) with\n capabilities enabled.\n- W-10 Thinking toggle: `--thinking` emits `ContentPart(type=think)`, `--no-thinking` does not\n (real LLM).\n- W-11 Concurrent prompt: second `prompt` returns `-32000` (turn already in progress).\n- W-12 Cancel turn: `cancel` returns `{}`, original `prompt` becomes `status=cancelled`\n (may emit `StepInterrupted`, real LLM).\n\n**Tools and Approvals**\n- W-13 Shell approval: `Shell` triggers `ApprovalRequest`, `approve` yields `ToolResult`.\n- W-14 Approval reject: `reject` ends turn; tool does not run.\n- W-15 Session approval: `approve_for_session` removes subsequent blocking approvals.\n- W-16 YOLO: `--yolo` skips blocking approvals.\n- W-17 DisplayBlock coverage: `Shell`/`WriteFile`/`StrReplaceFile`/`SetTodoList` emit expected\n display types.\n- W-18 Tool args streaming: `ToolCallPart.arguments_part` can be stitched into full args.\n\n**Sessions and Context**\n- W-19 Session files: `--session ` writes `context.jsonl` and `wire.jsonl`.\n- W-20 Continue session: `--continue` appends to the same session files.\n- W-21 Clear context: `/clear` ensures the next `prompt` does not rely on prior context.\n- W-22 Manual compaction: `/compact` triggers `CompactionBegin/CompactionEnd`.\n- W-24 Status stats: `StatusUpdate.context_usage/token_usage` types are valid and change over time.\n\n**Config and Runtime Flags**\n- W-25 `--config` inline: JSON/TOML string config works.\n- W-28 CLI override: `--model` overrides `default_model`.\n- W-30 Work dir: `prompt` asks \"where is the current directory\", verify `--work-dir` (real LLM).\n\n**Extensions (Agents/Skills/MCP)**\n- W-31 Built-in agent boundary: `default` calling `SendDMail` fails or is rejected.\n- W-32 Custom agent: `--agent-file` excludes tool and calls are rejected.\n- W-33 Subagents: prompt \"parallel call two task tools, each runs shell sleep 0.5 and 1 second\";\n verify Task/SubagentEvent streaming/ToolResult/multiple approvals (real LLM).\n- W-34 Skill call: create a test skill, `/skill:test` injects `SKILL.md` (wire has no `/help`).\n- W-35 Flow skill: `/flow:` runs the flow until `END`.\n- W-36 MCP: use a Python fastmcp test server, load via `--mcp-config-file`, verify tool works.\n\n**Resilience and Errors**\n- W-37 Invalid JSON: malformed JSON line returns `-32700`.\n- W-38 Invalid request: missing fields returns `-32600`.\n- W-39 Unknown method: returns `-32601`.\n- W-40 Invalid params: bad structure returns `-32602`.\n- W-41 Cancel without active turn: returns `-32000`.\n- W-42 LLM errors: unsupported model `-32002` and service error `-32003`.\n\n## Real LLM Placeholders\n- W-10/W-12/W-30/W-33 require a real provider; everything else uses `_scripted_echo`.\n","isInternal":false,"tokens":1202,"sizeBytes":4334},{"name":"SKILL.md","path":".agents/skills/codex-worker/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/codex-worker/SKILL.md","title":"codex-worker","category":"anthropic-skill","format":"markdown","content":"---\nname: codex-worker\ndescription: Spawn and manage multiple Codex CLI agents via tmux to work on tasks in parallel. Use whenever a task can be decomposed into independent subtasks (e.g. batch triage, parallel fixes, multi-file refactors). When codex and tmux are available, prefer this over the built-in Task tool for parallelism.\n---\n\n# codex-worker\n\nOrchestrate multiple Codex CLI (`codex`) agents running in parallel, each in its\nown git worktree and tmux session.\n\n**When to use:** Whenever you identify that a task can be split into independent\nsubtasks — don't wait for the user to ask for parallelism. Examples:\n- User says \"triage all open issues updated in the last 7 days\" → fetch the\n issue list, then spawn one codex worker per issue.\n- User says \"refactor these 5 modules\" → one worker per module.\n- User says \"fix lint errors across packages\" → one worker per package.\n\n**Replaces Task tool:** When `codex` and `tmux` are available in the\nenvironment, use codex workers instead of the built-in Task (subagent) tool.\nCodex workers are full-featured agents with their own file system access, shell,\nand isolated worktree — far more capable than subagents.\n\n## Preflight check\n\n```bash\ncommand -v codex && codex login status && command -v tmux\n```\n\nAll three must succeed. The project must be a git repository.\n\n## Naming convention\n\nGit branch and worktree directory share a **task name**:\n\n```\n--\n```\n\nThe tmux session adds a `codex-worker-` prefix so workers are easy to filter:\n\n| | Format | Example |\n|---|---|---|\n| Task name | `--` | `issue-836-prompt-dollar-sign` |\n| Git branch | same as task name | `issue-836-prompt-dollar-sign` |\n| Worktree dir | `.worktrees/` | `kimi-cli.worktrees/issue-836-prompt-dollar-sign` |\n| tmux session | `codex-worker-` | `codex-worker-issue-836-prompt-dollar-sign` |\n\nMore examples:\n- `issue-518-mcp-config-isolation`\n- `fix-share-dir-skills-path`\n- `feat-ask-user-tool`\n- `refactor-jinja-templates`\n\nList only codex workers: `tmux ls | grep ^codex-worker-`\n\n## Usage\n\nPrefer tmux + interactive codex for all tasks. It supports multi-turn dialogue,\nthe user can `tmux attach` to inspect or intervene, and you can send follow-up\nprompts from outside.\n\n### Spawn a worker\n\n```bash\nNAME=\"issue-836-prompt-dollar-sign\" # task name\nSESSION=\"codex-worker-$NAME\" # tmux session name\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\n# 1. Create worktree (skip if exists)\ngit worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n\n# 2. Launch interactive codex inside tmux\ntmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n```\n\n### Send a prompt\n\nThe Codex TUI needs time to initialize before it accepts input.\nAfter launching a session, **wait at least 5 seconds** before sending\na prompt. Then send the text followed by `Enter`. If the prompt stays\nin the input field without being submitted, send an additional `Enter`.\n\n```bash\nsleep 5 # wait for Codex TUI to initialize\ntmux send-keys -t \"$SESSION\" \"Your prompt here\" Enter\n# If it doesn't submit, send another Enter:\n# tmux send-keys -t \"$SESSION\" Enter\n```\n\n### Peek at output\n\n```bash\ntmux capture-pane -t \"$SESSION\" -p | tail -30\n```\n\n### Attach for hands-on interaction\n\n```bash\ntmux attach -t \"$SESSION\"\n```\n\n### Parallel fan-out\n\n```bash\nTASKS=(\n \"issue-518-mcp-config-isolation|Triage #518: MCP config 被子 agent 继承的隔离问题。分析根因，给出修复方案。\"\n \"issue-836-prompt-dollar-sign|Triage #836: prompt 包含 $ 时启动静默失败。分析根因，给出修复方案。\"\n)\n\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\nfor entry in \"${TASKS[@]}\"; do\n NAME=\"${entry%%|*}\"\n PROMPT=\"${entry#*|}\"\n SESSION=\"codex-worker-$NAME\"\n git worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n tmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n sleep 5 # wait for Codex TUI to fully initialize\n tmux send-keys -t \"$SESSION\" \"$PROMPT\" Enter\ndone\n```\n\n### Fallback: `codex exec`\n\nOnly use `codex exec` when you explicitly don't need follow-up (e.g. CI, pure\nanalysis with `-o` output). It does not support multi-turn dialogue.\n\n```bash\ncodex exec --dangerously-bypass-approvals-and-sandbox \\\n -o \"/tmp/$NAME-result.md\" \\\n \"Your prompt here\"\n```\n\n## Lifecycle management\n\nList active workers:\n\n```bash\ntmux ls | grep ^codex-worker-\n```\n\nKill a finished worker:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\"\n```\n\nClean up worktree after merging:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\" 2>/dev/null\ngit worktree remove \"$WORKTREE_DIR/$NAME\"\ngit branch -d \"$NAME\"\n```\n\nBatch cleanup of dead sessions:\n\n```bash\ntmux list-sessions -F '#{session_name}:#{pane_dead}' \\\n | grep ':1$' \\\n | cut -d: -f1 \\\n | xargs -I{} tmux kill-session -t {}\n```\n","frontmatter":{"name":"codex-worker","description":"Spawn and manage multiple Codex CLI agents via tmux to work on tasks in parallel. Use whenever a task can be decomposed into independent subtasks (e.g. batch triage, parallel fixes, multi-file refactors). When codex and tmux are available, prefer this over the built-in Task tool for parallelism."},"isInternal":false,"tokens":1406,"sizeBytes":5016},{"name":"prompt-patterns.md","path":".agents/skills/feature-smoke-test/references/prompt-patterns.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/feature-smoke-test/references/prompt-patterns.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Prompt 模板\n\n以下模板作为脚手架使用。运行前替换占位符。\n\n## 单轮还是多轮\n\n满足以下任一条件时使用多轮：\n\n- 功能有状态\n- 功能依赖时序或并发\n- 功能需要审批、清理或恢复\n- session 产物本身是证据的一部分\n- 工具接口可能近期发生过变化\n\n仅对无状态的窄范围检查使用单轮。\n\n## 变量\n\n起草 prompt 前填写以下字段：\n\n- `` — 被测功能名称\n- `` — 当前场景的目标\n- `` — 需要阅读的源码路径\n- `` — 执行约束\n- `` — 成功信号\n- `` — 失败信号\n- `` — 需要检查的产物路径\n- `` — session 目录路径\n\n## 探索 prompt\n\n```text\n我要验证 。\n\n先阅读这些文件并只总结当前真实对外接口，不要假设旧文档、旧 prompt 或旧 tool 名称仍然正确：\n\n\n然后给我一个最小 smoke test 计划，只包含：\n1. happy path\n2. 一个边界/异常场景\n3. 一个清理、恢复或中断场景\n\n每个场景都写清楚目标、预期信号和要检查的产物。\n```\n\n## 执行 prompt\n\n```text\n在当前 session 里只执行这个场景：\n\n约束：\n\n\n执行前先复述你将使用的工具或命令。执行时记录关键 task id、输出片段、文件路径和任何需要后续复盘的标识符。不要扩展到其他场景。\n```\n\n## 观察 prompt\n\n```text\n现在不要继续跑新的测试。\n\n只读取并总结这次运行已经产生的状态和文件：\n\n\n请明确指出哪些证据支持了预期，哪些证据反驳了预期，哪些地方仍然不确定。\n```\n\n## 复盘 prompt\n\n```text\n请根据这个 session 目录复盘整个 smoke test：\n\n\n重点阅读 context.jsonl、wire.jsonl 和相关运行产物。输出：\n1. 实际执行流程\n2. 关键 tool 调用与结果\n3. 与预期不一致的点\n4. 最小复现步骤\n```\n\n## 兼容性校验 prompt\n\n```text\n在运行 smoke test 之前，先从提供的文档或代码中复述当前真实可用的工具及其准确名称。不要臆造旧版工具名。如果任务涉及状态或时序，将工作拆分为多轮而非一次性长回复。\n```\n","isInternal":false,"tokens":768,"sizeBytes":2277},{"name":"SKILL.md","path":".agents/skills/feature-smoke-test/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/feature-smoke-test/SKILL.md","title":"feature-smoke-test","category":"anthropic-skill","format":"markdown","content":"---\nname: feature-smoke-test\ndescription: 针对 Kimi Code CLI 的新增或变更功能，规划并执行可重复的端到端冒烟测试。从 git diff 推断功能边界，读取相关文档和代码，设计测试 prompt，以 --print 非交互模式运行本地 CLI，检查进程退出码和 session 产物，总结预期与实际行为之间的差异。发现问题时自动启动多路并行探查以定位根因。\n---\n\n冒烟测试是运行时验证，不是写完 prompt 或读完代码就结束。必须实际执行、实际检查产物。\n\n## 确定测试范围\n\n动手之前，先从代码变更推断功能边界：\n\n```sh\ngit diff main --name-only\ngit diff main --stat\n```\n\n根据变更文件集合，明确写下：\n\n- 被测的功能边界\n- 用户可感知的行为变化\n- 运行前的准备工作和运行后的清理工作\n- 能够证明成功或失败的证据\n\n如果功能涉及状态、异步、审批流或时序敏感逻辑，默认认为单条 prompt 不够。\n\n## 先读事实来源\n\n读取定义该功能真实行为的最小文件集合：\n\n- 面向用户的文档、changelog 或设计笔记\n- 暴露该功能的 agent prompt 或 tool prompt\n- 实现层入口\n- 已有测试——当测试比文档更准确地描述行为时优先看测试\n\n不要信任过时的 prompt 示例。先从代码或当前文档重建真实的工具接口。\n\n## 制定最小测试计划\n\n默认覆盖三个场景：\n\n1. 正常路径\n2. 边界条件、非法输入或容量极限\n3. 中断、重试、清理或恢复\n\n每个场景记录：\n\n- `目标`\n- `前置准备`\n- `prompt 策略`\n- `成功信号`\n- `失败信号`\n- `需要检查的产物`\n\n如果功能存在竞态条件，必须显式标注时序。用长时间运行的命令或刻意的等待来制造时序窗口，不要用\"快速再跑一个\"这种模糊说法。\n\n## 优先使用多轮 prompt\n\n默认采用多轮流程：\n\n1. 探索轮：让 agent 在阅读事实来源后复述当前真实接口\n2. 执行轮：只执行一个场景\n3. 观察轮：只读取输出、工具状态和产物文件，不扩大范围\n4. 清理轮：停止、回滚或关闭有状态资源\n\n仅对无状态的简单功能使用单轮 prompt。\n\n多轮测试时，每一轮单独调用 CLI，在两轮之间检查上一轮的输出和产物，再决定下一轮的 prompt。不要把多轮 prompt 一次性塞进 stdin——那是盲写，无法根据上一轮结果调整。\n\n测试时，显式要求 agent 先列举当前可用的工具，不要臆造历史工具名。可复用的 prompt 模板见 `references/prompt-patterns.md`。\n\n## 以非交互模式隔离运行 CLI\n\n使用 `/tmp` 下的一次性目录作为 `--work-dir`，实现 session 隔离。CLI 的 session 路径由 `~/.kimi/sessions//` 决定，不同的 work-dir 自动产生独立的 session 命名空间，不会污染正常项目的 session。认证状态保留在 `~/.kimi` 下，无需额外配置。\n\n### 环境准备\n\n```sh\nSMOKE_DIR=\"$(mktemp -d /tmp/kimi-smoke-XXXXXX)\"\n```\n\n如果功能需要仓库上下文（读取代码、git 信息等），把仓库文件复制或软链到 `SMOKE_DIR`。如果功能会编辑文件，绝不要用活跃仓库作为 work-dir。\n\n### 默认执行方式\n\n绝大多数场景使用这个模式：\n\n```sh\nuv run python -m kimi_cli.cli \\\n --print \\\n --prompt \"你的测试 prompt\" \\\n --work-dir \"$SMOKE_DIR\"\necho \"exit_code=$?\"\n```\n\n`--print` 会自动启用 `--yolo`（自动批准所有操作），适合无人值守的冒烟测试。\n\n执行后**必须先检查退出码**：非零表示 CLI 本身崩溃或超时，应优先排查进程级错误，再看 session 产物。\n\n### 备选执行模式\n\n当默认方式不满足需求时，按需选用：\n\n- **长 prompt**：通过 stdin 传入——`cat <<'PROMPT' | uv run python -m kimi_cli.cli --print --input-format text --work-dir \"$SMOKE_DIR\"`\n- **结构化输出**：加 `--output-format stream-json`，输出逐行 JSON，便于程序化解析\n- **只看最终结果**：用 `--quiet`，等价于 `--print --output-format text --final-message-only`\n\n### 注意事项\n\n- 运行过程中记录这些路径：`SMOKE_DIR`、最终 session 目录（可通过 `inspect_session.py` 定位）、功能特定的输出文件。\n\n## 刻意执行\n\n执行过程中维护一份简短的运行日志：\n\n- 使用的完整 prompt\n- 关键的工具调用或命令\n- 功能产生的 task id、输出路径或审批 id\n- 时序敏感时记录时间戳\n\n不要仅凭 assistant 的最终文本推断正确性。运行时文件和工具结果才是事实来源。\n\n## 检查 session 产物\n\n首先检查：\n\n- `~/.kimi/sessions/.../context.jsonl`\n- `~/.kimi/sessions/.../wire.jsonl`\n- 功能创建的 session 级文件\n\n使用 `scripts/inspect_session.py` 查找并汇总最新 session：\n\n```sh\nuv run python .agents/skills/feature-smoke-test/scripts/inspect_session.py --share-dir ~/.kimi\n```\n\n脚本退出码含义：0 = 正常汇总，1 = session 目录缺失或无法解析。\n\n如果功能会创建后台任务、通知或附属文件，直接检查这些文件，不要只依赖模型摘要。\n\n## 汇报结论\n\n将结果分为三类：\n\n- **已确认**的行为\n- **与预期不符**的行为\n- **仍有歧义**、需要更确定性复现的行为\n\n对于每个 bug 或回归，记录：\n\n- 触发它的 prompt\n- 精确的 session 路径\n- 证明它的产物路径\n- 能推导出的最小复现步骤\n\n## 问题探查\n\n当发现与预期不符的行为时，不要停在报告层面。启动并行探查流程定位根因：\n\n### 探查策略\n\n针对每个发现的问题，**同时启动多个独立的探查方向**（使用 Agent 工具并行执行）。根据问题的具体表现自行判断最有价值的探查角度，常见方向包括但不限于：\n\n- 从触发问题的入口沿调用链追踪实际执行路径\n- 检查输入数据经过各处理阶段后的变化\n- 检查持久化状态（session 文件、后台任务、通知记录等）是否一致\n- 运行相关单元测试和集成测试，确认测试是否覆盖了出问题的路径\n\n不必机械地覆盖所有方向。根据 session 产物中的具体异常信号，选择最可能命中根因的 2-3 个方向并行展开。\n\n### 探查输出\n\n每条探查方向独立汇报：\n\n- 探查的具体方向和范围\n- 发现的事实（附文件路径和行号）\n- 该方向的结论：已定位根因 / 已排除 / 需要进一步调查\n\n### 综合定位\n\n汇总所有探查结果后，输出：\n\n- **根因**：一句话总结问题的本质原因\n- **证据链**：从触发 prompt → 代码路径 → 出错点 → 产物表现的完整链路\n- **修复建议**：最小改动方案，附具体文件和行号\n- **回归风险**：修复后需要额外验证的相关功能\n","frontmatter":{"name":"feature-smoke-test","description":"针对 Kimi Code CLI 的新增或变更功能，规划并执行可重复的端到端冒烟测试。从 git diff 推断功能边界，读取相关文档和代码，设计测试 prompt，以 --print 非交互模式运行本地 CLI，检查进程退出码和 session 产物，总结预期与实际行为之间的差异。发现问题时自动启动多路并行探查以定位根因。"},"isInternal":false,"tokens":2315,"sizeBytes":6779},{"name":"SKILL.md","path":".agents/skills/gen-changelog/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/gen-changelog/SKILL.md","title":"gen-changelog","category":"anthropic-skill","format":"markdown","content":"---\nname: gen-changelog\ndescription: Generate changelog entries for code changes.\n---\n\nGenerate changelog entries for changes on the current branch relative to `main`, then sync to the docs site.\n\n## Steps\n\n1. **Inspect**: `git log main..HEAD --oneline` + `git diff main..HEAD --stat`.\n2. **Edit root CHANGELOG**: add bullets under `## Unreleased` in `CHANGELOG.md` using the prefix table below. For changes scoped to a subpackage under `packages/` or `sdks/`, **also** update that subpackage's `CHANGELOG.md` — subpackage CHANGELOGs follow their own prefix conventions (e.g. `packages/kosong/CHANGELOG.md` uses provider prefixes like `Kimi:` / `Anthropic:`); only the root CHANGELOG follows the table below.\n3. **Sync English docs**: `node docs/scripts/sync-changelog.mjs`.\n4. **Translate to Chinese**: hand-write equivalents under `## 未发布` in `docs/zh/release-notes/changelog.md`. Use the full-width colon `：`. Follow `docs/AGENTS.md` terminology.\n5. **Breaking changes**: if any, add a section under `## Unreleased` in `docs/en/release-notes/breaking-changes.md` with **Affected** + **Migration** subsections, and under `## 未发布` in `docs/zh/release-notes/breaking-changes.md` with **受影响** + **迁移** subsections.\n\n## Entry format\n\n```\n- : — \n```\n\n- **First sentence stands alone** — readers should know after one sentence whether the bullet matters to them.\n- **One change per bullet.** No `; also`, `; and`, or nested em-dashes. Two changes = two bullets.\n- **Verb-led**: `Fix …` / `Add …` / `Switch …` / `Bump …`.\n- **User-meaningful only.** No internal refactors, test churn, or CI tweaks — except `Lib:` for SDK-facing changes.\n\n## Prefixes — pick from this list, do not invent new ones\n\n| Prefix | Scope |\n|---|---|\n| `Shell` | Interactive TUI: keys, status bar, slash commands, terminal rendering |\n| `Web` | `kimi web` |\n| `Vis` | `kimi vis` tracing visualizer |\n| `CLI` | Top-level flags, subcommands, `--print` / `--yolo` / `--afk` |\n| `ACP` | Zed / JetBrains and other ACP integrations |\n| `Core` | Agent runtime, step loop, approval, quota, turns, background tasks |\n| `Tool` | Any built-in tool; name the specific tool in the body (ReadFile, Grep, Todo, Plan, …) |\n| `Skill` | Skill discovery/loading, Flow, Loop (always singular — not `Skills:`) |\n| `MCP` | MCP server integration |\n| `Plugin` | Plugin system, `kimi plugin` subcommands |\n| `LLM` | Provider-agnostic or cross-provider; name the provider in the body (Kimi / Anthropic / OpenAI / DeepSeek …). **Do not** create per-provider prefixes |\n| `Kosong` | Changes to the `kosong` LLM abstraction layer surfaced in the root CHANGELOG (the subpackage's own CHANGELOG uses provider prefixes) |\n| `Wire` | Wire protocol events, version |\n| `Auth` | OAuth, token refresh, `/login` |\n| `Config` | Config schema, env vars |\n| `Lib` | SDK-facing API changes |\n| `Build` | Nix / Rust / Python / packaging |\n\nWhen unsure, match an existing entry of the same kind. Prefer this list; if you genuinely need a new prefix, raise it with maintainers and update this table in the same PR so the convention stays single-sourced.\n\n**Ordering**: within each version, group bullets by prefix in the order of the table above. Order within a prefix is free — keep the development order.\n\n## Highlights\n\nStarting from the next release, add `**Highlights**: …` under each version header (1–3 items most users will notice); mirror it as `**亮点**：…` in Chinese. Skip on releases that are only internal or `Lib:`. Highlights summarize — every highlighted item still needs its full bullet below. **Do not backfill historical versions.**\n","frontmatter":{"name":"gen-changelog","description":"Generate changelog entries for code changes."},"isInternal":false,"tokens":965,"sizeBytes":3738},{"name":"SKILL.md","path":".agents/skills/gen-docs/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/gen-docs/SKILL.md","title":"gen-docs","category":"anthropic-skill","format":"markdown","content":"---\nname: gen-docs\ndescription: Update Kimi Code CLI user documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n我们现在对代码库有了一些修改，请你参考最近的 git commit、staged changes、changelog.md 等的内容，根据 AGENTS.md 中的信息，必要时找到实际的代码全文，确保理解了所有变更对产品用户体验的真实改变，然后逐页、逐段地检查和更新文档内容。\n\n你应该首先确保英文 changelog 使用 `node docs/scripts/sync-changelog.mjs` 进行了同步，然后确保中文文档符合最新代码的行为，最后，使用 translate-docs skill 进行双语同步。\n","frontmatter":{"name":"gen-docs","description":"Update Kimi Code CLI user documentation."},"isInternal":false,"tokens":227,"sizeBytes":766},{"name":"SKILL.md","path":".agents/skills/gen-rust/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/gen-rust/SKILL.md","title":"gen-rust","category":"anthropic-skill","format":"markdown","content":"---\nname: gen-rust\ndescription: Sync Rust implementation with Python changes (exclude UI/login) by reviewing recent changes, mapping modules, porting logic, and updating tests.\n---\n\n# gen-rust\n\nUse this skill when the user wants Rust (kagent/kosong/kaos) to stay logically identical to Python (kimi_cli/kosong/kaos), excluding UI and login/auth. This includes code and tests: Rust behavior and tests must be fully synchronized with Python changes.\n\nNote: The Rust binary is named `kagent`. User-facing CLI/output text in Rust must use `kagent`\ninstead of `kimi` to match the Rust command name.\n\n## Quick workflow\n\n1) **Build a complete change inventory**\n\nReview recent changes to understand what needs syncing:\n\n```sh\n# Check staged changes\ngit diff --cached --name-only\ngit diff --cached -- src packages\n\n# Check recent commits\ngit log --oneline -20 -- src packages\ngit diff HEAD~20..HEAD -- src packages\n\n# Review CHANGELOG.md for context\nhead -50 CHANGELOG.md\n```\n\n2) **Classify changes**\n\n- Exclude UI and login/auth changes (Shell/Print/ACP UI, login/logout commands).\n- Everything else must be mirrored in Rust.\n- Keep a small checklist: file -> change summary -> Rust target -> status.\n\n3) **Map Python -> Rust**\n\nCommon mappings:\n- `src/kimi_cli/llm.py` -> `rust/kagent/src/llm.rs`\n- `src/kimi_cli/soul/*` -> `rust/kagent/src/soul/*`\n- `src/kimi_cli/tools/*` -> `rust/kagent/src/tools/*`\n- `src/kimi_cli/utils/*` -> `rust/kagent/src/utils/*`\n- `src/kimi_cli/wire/*` -> `rust/kagent/src/wire/*`\n- `packages/kosong/*` -> `rust/kosong/*`\n- `packages/kaos/*` -> `rust/kaos/*`\n\n4) **Port logic carefully**\n\n- Match error messages and tool output text exactly (tests often assert strings).\n- Preserve output types (text vs parts) and ordering.\n- For media/tool outputs, verify ContentPart wrapping and serialization.\n- If Python adds new helper modules, mirror minimal Rust utilities.\n- Use `rg` to find existing analogs and references.\n\n5) **Update tests**\n\n- Update Rust tests that assert content/strings/parts.\n- Mirror Python unit and integration tests when they exist; add missing Rust tests so coverage matches intent.\n- Ensure E2E parity: use the existing Python E2E suite against the Rust binary by setting\n `KIMI_E2E_WIRE_CMD` (do not rewrite E2E in Rust). All E2E cases must pass or the gap must be documented.\n- Prefer targeted tests first (`cargo test -p kagent --test `), then full suite if asked.\n\n6) **Verification is mandatory**\n\n- Run the full Rust test suite and ensure all Rust tests pass.\n- Run E2E tests with the wire command swapped to Rust (set `KIMI_E2E_WIRE_CMD`), and ensure they pass.\n\n7) **Final report**\n\n- List synced files and logic.\n- Call out intentionally skipped UI/login changes.\n- List tests run and results (must include full Rust tests and Rust E2E with wire command override).\n\n## Pitfalls to avoid\n\n- Skipping `llm.py`: it often changes model capability logic.\n- Using commit message filtering instead of full diff.\n- Forgetting to update Rust tests when output text/parts change.\n- Mixing UI/login changes into core sync.\n- Leaving test parity ambiguous; always state unit/integration/E2E status.\n\n## Minimal diff checklist (template)\n\n- [ ] Recent changes reviewed (staged, commits, changelog)\n- [ ] Python diffs inspected for core logic\n- [ ] Rust mappings applied\n- [ ] Tests updated\n- [ ] Targeted tests run\n- [ ] Full Rust test suite passed\n- [ ] Rust E2E passed with `KIMI_E2E_WIRE_CMD`\n","frontmatter":{"name":"gen-rust","description":"Sync Rust implementation with Python changes (exclude UI/login) by reviewing recent changes, mapping modules, porting logic, and updating tests."},"isInternal":false,"tokens":861,"sizeBytes":3445},{"name":"SKILL.md","path":".agents/skills/pull-request/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/pull-request/SKILL.md","title":"pull-request","category":"anthropic-skill","format":"markdown","content":"---\nname: pull-request\ndescription: Create and submit a GitHub Pull Request.\ntype: flow\n---\n\n```mermaid\nflowchart TB\n A([\"BEGIN\"]) --> B[\"当前分支有没有 dirty change？\"]\n B -- 有 --> D([\"END\"])\n B -- 没有 --> n1[\"确保当前分支是一个不同于 main 的独立分支\"]\n n1 --> n2[\"根据当前分支相对于 main 分支的修改，push 并提交一个 PR（利用 gh 命令），用英文编写 PR 标题和 description，描述所做的更改。PR title 要符合先前的 commit message 规范（PR title 就是 squash merge 之后的 commit message）。\"]\n n2 --> D\n```\n","frontmatter":{"name":"pull-request","description":"Create and submit a GitHub Pull Request.","type":"flow"},"isInternal":false,"tokens":184,"sizeBytes":605},{"name":"SKILL.md","path":".agents/skills/release/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/release/SKILL.md","title":"release","category":"anthropic-skill","format":"markdown","content":"---\nname: release\ndescription: Execute the release workflow for Kimi Code CLI packages.\n---\n\nRelease process for Kimi Code CLI packages. Tags are pushed without a `v` prefix and follow one of these patterns (matched by `.github/workflows/release-*.yml`):\n\n| Tag pattern | Releases |\n|---|---|\n| `1.42.0` (numeric) | `kimi-cli` (root) + `kimi-code` wrapper, released together — versions must stay aligned |\n| `kosong-0.53.0` | `packages/kosong` |\n| `pykaos-0.9.0` | `packages/kaos` (PyPI name `pykaos`) |\n| `kimi-sdk-0.3.0` | `sdks/kimi-sdk` |\n\nThe Rust implementation (`kagent`) lives in a separate repository and is **not** released from here.\n\n## Steps\n\n1. **Understand the automation.** Read `AGENTS.md` and `.github/workflows/release*.yml` so you know what each release workflow expects before changing any versions.\n\n2. **Detect changed packages.** Check each release unit under `packages/`, `sdks/`, and the repo root for changes since its last release tag. Use path-scoped diffs for subpackages so unrelated repo changes do not trigger a package release, e.g. `git diff kosong-0.53.0..HEAD -- packages/kosong`, `git diff pykaos-0.9.0..HEAD -- packages/kaos`, and `git diff kimi-sdk-0.2.1..HEAD -- sdks/kimi-sdk`. If nothing changed anywhere, stop and report that there is nothing to release. Note: `packages/kimi-code` is a thin wrapper and must stay version-synced with `kimi-cli`, so treat it as changed whenever the root package changes.\n\n3. **Confirm new versions with the user.** For each changed package, propose a new version and confirm before editing. Versioning policy:\n - Patch is always `0`.\n - Bump the minor version for any change.\n - Major only changes by explicit manual decision from the user.\n\n4. **Create the release branch.** Name it `bump--`. If multiple packages are being bumped together, use a single branch with a descriptive name.\n\n5. **Update version metadata and changelogs.** For each changed package:\n - Update its `pyproject.toml`.\n - Update `CHANGELOG.md`, keeping the `## Unreleased` header empty in place (do **not** rename it — add a new dated `## (YYYY-MM-DD)` section below it).\n - Update `breaking-changes.md` in both languages if there are breaking changes.\n - If bumping `packages/kosong` or `packages/kaos`, also update the root `pyproject.toml` pinned dependency (`kosong[contrib]==` or `pykaos==`) so root validation keeps passing.\n\n6. **Sync the `kimi-code` wrapper when the root version changes.** Bump `packages/kimi-code/pyproject.toml` `version` to match the new root version. It is a legacy stub with no dependencies — do not add a `kimi-cli` pin back.\n\n7. **Run `uv sync`** to refresh the lockfile.\n\n8. **Update docs.** Follow the `gen-docs` skill to make sure docs reflect the release.\n\n9. **Confirm with the user before opening the PR.** Summarize the staged changes and ask the user to explicitly confirm:\n - **Version numbers** — every updated `pyproject.toml` (changed package + `packages/kimi-code` if the root moved) reflects the version agreed in step 3.\n - **Dependency pins** — the root `pyproject.toml` pins (`kosong[contrib]==`, `pykaos==`) match the bumped versions.\n - **Documentation** — CHANGELOG entries are added below `## Unreleased` (Unreleased still present and empty), `breaking-changes.md` is updated in both languages if applicable, and `gen-docs` left no inconsistencies.\n\n Wait for explicit user approval before proceeding. If the user flags anything, fix it and re-confirm — do not push.\n\n10. **Open the PR.** Commit all changes, push, and open a PR with `gh`. The PR description must follow this structure (see https://github.com/MoonshotAI/kimi-cli/pull/2225 for reference):\n\n ```markdown\n ## Summary\n - Bump to \n - Move the current release notes under \n - (If applicable) Move breaking-change entries under \n - (If applicable) Any additional noteworthy changes (dependency pin updates, etc.)\n\n ## Validation\n - uv run python scripts/check_version_tag.py --pyproject --expected-version \n - (For root releases) uv run python scripts/check_version_tag.py --pyproject packages/kimi-code/pyproject.toml --expected-version \n - uv run python scripts/check_kimi_dependency_versions.py --root-pyproject pyproject.toml --kosong-pyproject packages/kosong/pyproject.toml --pykaos-pyproject packages/kaos/pyproject.toml\n - make check\n\n ## Post-merge\n After this PR lands, create and push the release tag:\n\n ```sh\n git tag \n git push origin \n ```\n ```\n\n11. **Hand off the tag step.** After merge, switch to `main`, pull latest, and tell the user the exact `git tag` command for the final release tag (pick the right tag pattern from the table above — e.g. `git tag 1.43.0` for a root release, `git tag kosong-0.54.0` for a kosong release). The user will run the tag and push tags themselves.\n\n## Stop conditions\n\nFail fast — never paper over an error to keep the release moving. Stop and report back to the user when any of these happen:\n\n- Nothing changed since the last tag → there is nothing to release.\n- `uv sync` fails or produces unexpected `uv.lock` churn beyond the version bump.\n- `gen-docs` reports a doc inconsistency you cannot resolve.\n- PR checks go red after push — investigate, do **not** `--no-verify` or force-merge.\n- The release workflow fails after tag push — read the workflow logs and surface the failure, do not retag silently.\n","frontmatter":{"name":"release","description":"Execute the release workflow for Kimi Code CLI packages."},"isInternal":false,"tokens":1416,"sizeBytes":5571},{"name":"SKILL.md","path":".agents/skills/translate-docs/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/translate-docs/SKILL.md","title":"translate-docs","category":"anthropic-skill","format":"markdown","content":"---\nname: translate-docs\ndescription: Translate and sync bilingual documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n中文文档和英文 changelog 已经确保是正确符合预期的，现在请你逐页、逐段地翻译文档内容，确保中英双语保持同步。\n\n## 翻译方向\n\n- **Changelog**: 以英文为准，翻译到中文\n- **其他所有页面**: 以中文为准，翻译到英文\n\n## 注意事项\n\n- 必要时可以参考代码文件以确保翻译的准确性\n- 要保证不同语言的表达风格、结构标记等保持一致\n- 但需要遵守两者可能不同的用词和排版偏好（主要是 sentence case、翻译对照之类的）\n","frontmatter":{"name":"translate-docs","description":"Translate and sync bilingual documentation."},"isInternal":false,"tokens":275,"sizeBytes":790},{"name":"SKILL.md","path":".agents/skills/worktree-status/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/.agents/skills/worktree-status/SKILL.md","title":"worktree-status","category":"anthropic-skill","format":"markdown","content":"---\nname: worktree-status\ndescription: Audit all git worktrees in the current project. Use when the user asks about worktree status, which branches are merged, which have uncommitted changes, or which worktrees can be safely cleaned up.\n---\n\n# worktree-status\n\nReport the status of every git worktree for the current project, covering\ndirty state and merge status.\n\n## When to use\n\n- User asks \"which worktrees can I clean up?\"\n- User asks \"what's the status of my worktrees / branches?\"\n- Before batch-cleaning worktrees, to avoid losing uncommitted work\n\n## Procedure\n\n### 1. Pull latest main (MANDATORY)\n\nYou MUST pull latest main before any status checks. Without this, merge\ndetection (both ancestry and content diff) will produce stale results and\nyou may mistakenly conclude a branch is not merged.\n\n```bash\ncd \"$(git rev-parse --show-toplevel)\" && git pull origin main\n```\n\n### 2. Collect worktree info\n\n```bash\nPROJECT_DIR=\"$(git rev-parse --show-toplevel)\"\n\nfor wt in $(git worktree list --porcelain | grep \"^worktree \" | sed 's/^worktree //' | grep -v \"$PROJECT_DIR$\"); do\n branch=$(git -C \"$wt\" branch --show-current 2>/dev/null)\n [ -z \"$branch\" ] && branch=\"(detached)\"\n name=$(basename \"$wt\")\n\n # dirty?\n if [ -z \"$(git -C \"$wt\" status --short 2>/dev/null)\" ]; then\n dirty=\"clean\"\n else\n dirty=\"DIRTY\"\n fi\n\n # merged into origin/main?\n # NOTE: This project uses squash merges exclusively. `git merge-base\n # --is-ancestor` does NOT detect squash-merged branches. Always follow\n # up with a content diff (step 3) for branches that appear \"not merged\".\n if [ \"$branch\" != \"(detached)\" ]; then\n if git merge-base --is-ancestor \"$branch\" origin/main 2>/dev/null; then\n merged=\"merged\"\n else\n merged=\"not merged (verify with content diff)\"\n fi\n else\n merged=\"n/a\"\n fi\n\n echo \"\"\n echo \"[$name] branch=$branch $dirty $merged\"\n if [ \"$dirty\" = \"DIRTY\" ]; then\n git -C \"$wt\" status --short 2>/dev/null | sed 's/^/ /'\n fi\ndone\n```\n\n### 3. Detect squash-merged branches (content diff)\n\nFor any branch that shows \"not merged\", check whether the branch's\nchanges are already in main. The correct method is:\n\n1. Find the files the branch actually changed (relative to merge-base).\n2. For each changed file, compare the branch version with main.\n If all files are identical, the branch was squash-merged.\n\n**⚠️ Do NOT use `git diff origin/main `** — that compares the\ntwo tips directly, so commits added to main *after* the branch diverged\nwill show up as false differences.\n\n```bash\nBRANCH=\"\"\nBASE=$(git merge-base origin/main \"$BRANCH\")\n\n# List files the branch touched\nFILES=$(git diff --name-only \"$BASE\" \"$BRANCH\")\n\n# Compare each file between branch and current main\nfor f in $FILES; do\n d=$(git diff \"$BRANCH\" origin/main -- \"$f\" | wc -l)\n if [ \"$d\" != \"0\" ]; then\n echo \"❌ $f — differs\"\n else\n echo \"✅ $f — identical in main\"\n fi\ndone\n# All ✅ = squash-merged\n```\n\n### 4. (Optional) Check for associated tmux sessions\n\nOnly run this if `tmux` is available and relevant (e.g. worktrees were\ncreated by codex-worker or similar tooling). Skip if not applicable.\n\n```bash\ntmux ls 2>/dev/null | grep -E 'codex-worker|' || true\n```\n\n### 5. Present results\n\n**Always present results as a Markdown table.** Every worktree must appear\nas a row. Never use abbreviated or prose-only summaries.\n\n| Worktree | Branch | Dirty | Merged | Can clean? |\n|---|---|---|---|---|\n| `example-wt` | `feat-foo` | ✅ clean | ✅ squash-merged | ✅ |\n| `another-wt` | `fix-bar` | ⚠️ 3 files | ❌ not merged | ❌ dirty + not merged |\n| `detached-wt` | (detached) | ⚠️ 14 files | n/a | ❌ has uncommitted changes |\n\nColumn definitions:\n\n- **Dirty**: `✅ clean` or `⚠️ N files`\n- **Merged**: `✅ merged` / `✅ squash-merged` (confirmed via content diff) / `❌ not merged` / `n/a`\n- **Can clean?**: `✅` only when merged (or squash-merged) AND clean\n\nAdd extra columns (e.g. tmux session, notes) only when relevant.\n\n### 6. Cleanup (only when asked)\n\nOnly clean worktrees the user explicitly approves. For each:\n\n```bash\nNAME=\"\"\ngit worktree remove \"/path/to/$NAME\"\ngit branch -D \"\" # only if the branch is no longer needed\n```\n","frontmatter":{"name":"worktree-status","description":"Audit all git worktrees in the current project. Use when the user asks about worktree status, which branches are merged, which have uncommitted changes, or which worktrees can be safely cleaned up."},"isInternal":false,"tokens":1184,"sizeBytes":4261},{"name":"SKILL.md","path":"examples/sample-plugin/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/examples/sample-plugin/SKILL.md","title":"sample-plugin","category":"anthropic-skill","format":"markdown","content":"---\nname: sample-plugin\ndescription: |\n Sample plugin demonstrating the Skills + Tools model.\n Includes a Python tool (greeting) and a TypeScript tool (calculator).\n---\n\n# Sample Plugin\n\nA demo plugin with two tools in different languages, showing that plugin tools are language-agnostic.\n\n## Tools\n\n| Tool | Language | Description |\n|------|----------|-------------|\n| `py_greet` | Python | Generate a greeting in en/zh/ja |\n| `ts_calc` | TypeScript | Evaluate a math expression |\n\n## Usage\n\n- \"greet Alice in Chinese\" -> use `py_greet` with name=\"Alice\", lang=\"zh\"\n- \"what is 42 * 17 + 3\" -> use `ts_calc` with expression=\"42 * 17 + 3\"\n","frontmatter":{"name":"sample-plugin","description":"Sample plugin demonstrating the Skills + Tools model.\nIncludes a Python tool (greeting) and a TypeScript tool (calculator).\n"},"isInternal":false,"tokens":165,"sizeBytes":640},{"name":"SKILL.md","path":"src/kimi_cli/skills/kimi-cli-help/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/src/kimi_cli/skills/kimi-cli-help/SKILL.md","title":"kimi-cli-help","category":"anthropic-skill","format":"markdown","content":"---\nname: kimi-cli-help\ndescription: Answer Kimi Code CLI usage, configuration, and troubleshooting questions. Use when user asks about Kimi Code CLI installation, setup, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, how something works internally, or any questions about Kimi Code CLI itself.\n---\n\n# Kimi Code CLI Help\n\nHelp users with Kimi Code CLI questions by consulting documentation and source code.\n\n## Strategy\n\n1. **Prefer official documentation** for most questions\n2. **Read local source** when in kimi-cli project itself, or when user is developing with kimi-cli as a library (e.g., importing from `kimi_cli` in their code)\n3. **Clone and explore source** for complex internals not covered in docs - **ask user for confirmation first**\n\n## Documentation\n\nBase URL: `https://moonshotai.github.io/kimi-cli/`\n\nFetch documentation index to find relevant pages:\n\n```\nhttps://moonshotai.github.io/kimi-cli/llms.txt\n```\n\n### Page URL Pattern\n\n- English: `https://moonshotai.github.io/kimi-cli/en/...`\n- Chinese: `https://moonshotai.github.io/kimi-cli/zh/...`\n\n### Topic Mapping\n\n| Topic | Page |\n|-------|------|\n| Installation, first run | `/en/guides/getting-started.md` |\n| Config files | `/en/configuration/config-files.md` |\n| Providers, models | `/en/configuration/providers.md` |\n| Environment variables | `/en/configuration/env-vars.md` |\n| Slash commands | `/en/reference/slash-commands.md` |\n| CLI flags | `/en/reference/kimi-command.md` |\n| Keyboard shortcuts | `/en/reference/keyboard.md` |\n| MCP | `/en/customization/mcp.md` |\n| Agents | `/en/customization/agents.md` |\n| Skills | `/en/customization/skills.md` |\n| FAQ | `/en/faq.md` |\n\n## Source Code\n\nRepository: `https://github.com/MoonshotAI/kimi-cli`\n\nWhen to read source:\n\n- In kimi-cli project directory (check `pyproject.toml` for `name = \"kimi-cli\"`)\n- User is importing `kimi_cli` as a library in their project\n- Question about internals not covered in docs (ask user before cloning)\n","frontmatter":{"name":"kimi-cli-help","description":"Answer Kimi Code CLI usage, configuration, and troubleshooting questions. Use when user asks about Kimi Code CLI installation, setup, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, how something works internally, or any questions about Kimi Code CLI itself."},"isInternal":false,"tokens":490,"sizeBytes":2018},{"name":"SKILL.md","path":"src/kimi_cli/skills/skill-creator/SKILL.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/src/kimi_cli/skills/skill-creator/SKILL.md","title":"skill-creator","category":"anthropic-skill","format":"markdown","content":"---\nname: skill-creator\ndescription: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Kimi's capabilities with specialized knowledge, workflows, or tool integrations.\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Kimi's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Kimi from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n## Core Principles\n\n### Concise is Key\n\nThe context window is a public good. Skills share the context window with everything else Kimi needs: system prompt, conversation history, other Skills' metadata, and the actual user request.\n\n**Default assumption: Kimi is already very smart.** Only add context Kimi doesn't already have. Challenge each piece of information: \"Does Kimi really need this explanation?\" and \"Does this paragraph justify its token cost?\"\n\nPrefer concise examples over verbose explanations.\n\n### Set Appropriate Degrees of Freedom\n\nMatch the level of specificity to the task's fragility and variability:\n\n**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.\n\n**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.\n\n**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.\n\nThink of Kimi as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\nEvery SKILL.md consists of:\n\n- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Kimi reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.\n- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Kimi for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Kimi's process and thinking.\n\n- **When to include**: For documentation that Kimi should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Kimi determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Kimi produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Kimi to use files without loading them into context\n\n#### What to Not Include in a Skill\n\nA skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:\n\n- README.md\n- INSTALLATION_GUIDE.md\n- QUICK_REFERENCE.md\n- CHANGELOG.md\n- etc.\n\nThe skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Kimi (Unlimited because scripts can be executed without reading into context window)\n\n#### Progressive Disclosure Patterns\n\nKeep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.\n\n**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.\n\n**Pattern 1: High-level guide with references**\n\n```markdown\n# PDF Processing\n\n## Quick start\n\nExtract text with pdfplumber:\n[code example]\n\n## Advanced features\n\n- **Form filling**: See [FORMS.md](FORMS.md) for complete guide\n- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods\n- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns\n```\n\nKimi loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.\n\n**Pattern 2: Domain-specific organization**\n\nFor Skills with multiple domains, organize content by domain to avoid loading irrelevant context:\n\n```\nbigquery-skill/\n├── SKILL.md (overview and navigation)\n└── reference/\n ├── finance.md (revenue, billing metrics)\n ├── sales.md (opportunities, pipeline)\n ├── product.md (API usage, features)\n └── marketing.md (campaigns, attribution)\n```\n\nWhen a user asks about sales metrics, Kimi only reads sales.md.\n\nSimilarly, for skills supporting multiple frameworks or variants, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + provider selection)\n└── references/\n ├── aws.md (AWS deployment patterns)\n ├── gcp.md (GCP deployment patterns)\n └── azure.md (Azure deployment patterns)\n```\n\nWhen the user chooses AWS, Kimi only reads aws.md.\n\n**Pattern 3: Conditional details**\n\nShow basic content, link to advanced content:\n\n```markdown\n# DOCX Processing\n\n## Creating documents\n\nUse docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).\n\n## Editing documents\n\nFor simple edits, modify the XML directly.\n\n**For tracked changes**: See [REDLINING.md](REDLINING.md)\n**For OOXML details**: See [OOXML.md](OOXML.md)\n```\n\nKimi reads REDLINING.md or OOXML.md only when the user needs those features.\n\n**Important guidelines:**\n\n- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.\n- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Kimi can see the full scope when previewing.\n\n## Skill Locations and Discovery\n\nKimi Code CLI loads skills in layers (built-in -> user -> project). Within each layer, it uses the\nfirst existing directory in priority order. Built-in skills only load for LocalKaos or ACPKaos.\n\n**User level** (by priority):\n- `~/.config/agents/skills/` (recommended)\n- `~/.kimi/skills/`\n- `~/.claude/skills/`\n\n**Project level**:\n- `.agents/skills/`\n\n`--skills-dir` overrides discovery and loads only that directory (built-ins still load when\nsupported).\n\n## Skill Creation Process\n\nSkill creation involves these steps:\n\n1. Understand the skill with concrete examples\n2. Plan reusable skill contents (scripts, references, assets)\n3. Initialize the skill (run init_skill.py)\n4. Edit the skill (implement resources and write SKILL.md)\n5. Package the skill (run package_skill.py)\n6. Iterate based on real usage\n\nFollow these steps in order, skipping only if there is a clear reason why they are not applicable.\n\n### Skill Naming\n\n- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., \"Plan Mode\" -> `plan-mode`).\n- When generating names, generate a name under 64 characters (letters, digits, hyphens).\n- Prefer short, verb-led phrases that describe the action.\n- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).\n- Name the skill folder exactly after the skill name.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, create a new skill directory with a required `SKILL.md`\nfile and any optional resource directories that the skill needs (`scripts/`, `references/`,\n`assets/`). Create only the directories you intend to populate.\n\nAfter initialization, customize the SKILL.md and add resources as needed.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Kimi to use. Include information that would be beneficial and non-obvious to Kimi. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Kimi instance execute these tasks more effectively.\n\n#### Learn Proven Design Patterns\n\nCapture proven design patterns directly in this SKILL.md:\n\n- **Multi-step processes**: Clearly describe sequential workflows and conditional branches, including triggers, decision points, and expected outputs at each step.\n- **Specific output formats or quality standards**: Document required output shapes, templates, and examples directly in this SKILL.md so they are easy to follow.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAdded scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.\n\nDelete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.\n\n#### Update SKILL.md\n\n**Writing Guidelines:** Always use imperative/infinitive form.\n\n##### Frontmatter\n\nWrite the YAML frontmatter with `name` and `description`:\n\n- `name`: The skill name\n- `description`: This is the primary triggering mechanism for your skill, and helps Kimi understand when to use the skill.\n - Include both what the Skill does and specific triggers/contexts for when to use it.\n - Include all \"when to use\" information here - Not in the body. The body is only loaded after triggering, so \"When to Use This Skill\" sections in the body are not helpful to Kimi.\n - Example description for a `docx` skill: \"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Kimi needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks\"\n\nDo not include any other fields in YAML frontmatter.\n\n##### Body\n\nWrite instructions for using the skill and its bundled resources.\n\n### Step 5: Packaging a Skill\n\nOnce development of the skill is complete, package it into a distributable `.skill` file (a zip\narchive). Before packaging, validate that the skill meets all requirements:\n\n1. **Validate** the skill, checking:\n\n - YAML frontmatter format and required fields\n - Skill naming conventions and directory structure\n - Description completeness and quality\n - File organization and resource references\n\n2. **Package** the skill if validation passes:\n\n - Create an archive of the skill's root folder (the folder containing `SKILL.md` and all related files).\n - Ensure the archive preserves the internal directory structure.\n - Name the archive `.skill` (for example, `my-skill.skill`). The `.skill` file is a zip file with a `.skill` extension.\n\nExample packaging command:\n\n```bash\ncd \nzip -r my-skill.skill my-skill\n```\n\nIf validation fails (for example, due to malformed frontmatter, missing files, or an incomplete\ndescription), fix the issues and repackage the skill.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n","frontmatter":{"name":"skill-creator","description":"Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Kimi's capabilities with specialized knowledge, workflows, or tool integrations."},"isInternal":false,"tokens":3807,"sizeBytes":18120},{"name":"AGENTS.md","path":"src/kimi_cli/tools/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/src/kimi_cli/tools/AGENTS.md","title":"Tools Skill","category":"anthropic-skill","format":"markdown","content":"# Kimi Code CLI Tools\n\n## Guidelines\n\n- Tools should not refer to types in `kimi_cli/wire/` unless they are explicitly implementing a UI / runtime bridge. When importing things like `ToolReturnValue` or `DisplayBlock`, prefer `kosong.tooling`.\n","isInternal":false,"tokens":57,"sizeBytes":244},{"name":"system.md","path":"src/kimi_cli/agents/default/system.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/src/kimi_cli/agents/default/system.md","title":"Subagent: system","category":"subagent-persona","format":"markdown","content":"You are Kimi Code CLI, an interactive general AI agent running on a user's computer.\n\nYour primary goal is to help users with software engineering tasks by taking action — use the tools available to you to make real changes on the user's system. You should also answer questions when asked. Always adhere strictly to the following system instructions and the user's requirements.\n\n${ROLE_ADDITIONAL}\n\n# Prompt and Tool Use\n\nThe user's messages may contain questions and/or task descriptions in natural language, code snippets, logs, file paths, or other forms of information. Read them, understand them and do what the user requested. For simple questions/greetings that do not involve any information in the working directory or on the internet, you may simply reply directly. For anything else, default to taking action with tools. When the request could be interpreted as either a question to answer or a task to complete, treat it as a task.\n\nWhen handling the user's request, if it involves creating, modifying, or running code or files, you MUST use the appropriate tools (e.g., `WriteFile`, `Shell`) to make actual changes — do not just describe the solution in text. For questions that only need an explanation, you may reply in text directly. When calling tools, do not provide explanations because the tool calls themselves should be self-explanatory. You MUST follow the description of each tool and its parameters when calling tools.\n\nIf the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. The tool can either start a new instance or resume an existing one by `agent_id`. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context because a newly created subagent instance does not automatically see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it instead of creating a new instance. Default to foreground subagents. Use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes, and you do not need the result immediately to decide your next step.\n\nYou have the capability to output any number of tool calls in a single response. If you anticipate making multiple non-interfering tool calls, you are HIGHLY RECOMMENDED to make them in parallel to significantly improve efficiency. This is very important to your performance.\n\nThe results of the tool calls will be returned to you in a tool message. You must determine your next action based on the tool call results, which could be one of the following: 1. Continue working on the task, 2. Inform the user that the task is completed or has failed, or 3. Ask the user for more information.\n\nThe system may insert information wrapped in `` tags within user or tool messages. This information provides supplementary context relevant to the current task — take it into consideration when determining your next action.\n\nTool results and user messages may also include `` tags. Unlike `` tags, these are **authoritative system directives** that you MUST follow. They bear no direct relation to the specific tool results or user messages in which they appear. Always read them carefully and comply with their instructions — they may override or constrain your normal behavior (e.g., restricting you to read-only actions during plan mode).\n\nIf the `Shell`, `TaskList`, `TaskOutput`, and `TaskStop` tools are available and you are the root agent, you can use Background Bash for long-running shell commands. Launch it via `Shell` with `run_in_background=true` and a short `description`. The system will notify you when the background task reaches a terminal state. Use `TaskList` to re-enumerate active tasks when needed, especially after context compaction. Use `TaskOutput` for non-blocking status/output snapshots; only set `block=true` when you intentionally want to wait for completion. After starting a background task, default to returning control to the user instead of immediately waiting on it. Use `TaskStop` only when you need to cancel the task. For human users in the interactive shell, the only task-management slash command is `/task`. Do not tell users to run `/task list`, `/task output`, `/task stop`, `/tasks`, or any other invented slash subcommands. If you are a subagent or these tools are not available, do not assume you can create or control background tasks.\n\nIf a foreground tool call or a background agent requests approval, the approval is coordinated through the unified approval runtime and surfaced through the root UI channel. Do not assume approvals are local to a single subagent turn.\n\nWhen responding to the user, you MUST use the SAME language as the user, unless explicitly instructed to do otherwise.\n\n# General Guidelines for Coding\n\nWhen building something from scratch, you should:\n\n- Understand the user's requirements.\n- Ask the user for clarification if there is anything unclear.\n- Design the architecture and make a plan for the implementation.\n- Write the code in a modular and maintainable way.\n\nAlways use tools to implement your code changes:\n\n- Use `WriteFile` to create or overwrite source files. Code that only appears in your text response is NOT saved to the file system and will not take effect.\n- Use `Shell` to run and test your code after writing it.\n- Iterate: if tests fail, read the error, fix the code with `WriteFile` or `StrReplaceFile`, and re-test with `Shell`.\n\nWhen working on an existing codebase, you should:\n\n- Understand the codebase by reading it with tools (`ReadFile`, `Glob`, `Grep`) before making changes. Identify the ultimate goal and the most important criteria to achieve the goal.\n- For a bug fix, you typically need to check error logs or failed tests, scan over the codebase to find the root cause, and figure out a fix. If user mentioned any failed tests, you should make sure they pass after the changes.\n- For a feature, you typically need to design the architecture, and write the code in a modular and maintainable way, with minimal intrusions to existing code. Add new tests if the project already has tests.\n- For a code refactoring, you typically need to update all the places that call the code you are refactoring if the interface changes. DO NOT change any existing logic especially in tests, focus only on fixing any errors caused by the interface changes.\n- Make MINIMAL changes to achieve the goal. This is very important to your performance.\n- Follow the coding style of existing code in the project.\n- For broader codebase exploration and deep research, use the `Agent` tool with `subagent_type=\"explore\"`. This is a fast, read-only agent specialized for searching and understanding codebases. Use it when your task will clearly require more than 3 search queries, or when you need to investigate multiple files and patterns. You can launch multiple explore agents concurrently to investigate independent questions in parallel.\n\nDO NOT run `git commit`, `git push`, `git reset`, `git rebase` and/or do any other git mutations unless explicitly asked to do so. Ask for confirmation each time when you need to do git mutations, even if the user has confirmed in earlier conversations.\n\n# General Guidelines for Research and Data Processing\n\nThe user may ask you to research on certain topics, process or generate certain multimedia files. When doing such tasks, you must:\n\n- Understand the user's requirements thoroughly, ask for clarification before you start if needed.\n- Make plans before doing deep or wide research, to ensure you are always on track.\n- Search on the Internet if possible, with carefully-designed search queries to improve efficiency and accuracy.\n- Use proper tools or shell commands or Python packages to process or generate images, videos, PDFs, docs, spreadsheets, presentations, or other multimedia files. Detect if there are already such tools in the environment. If you have to install third-party tools/packages, you MUST ensure that they are installed in a virtual/isolated environment.\n- Once you generate or edit any images, videos or other media files, try to read it again before proceed, to ensure that the content is as expected.\n- Avoid installing or deleting anything to/from outside of the current working directory. If you have to do so, ask the user for confirmation.\n\n# Working Environment\n\n## Operating System\n\nYou are running on **${KIMI_OS}**. The Shell tool executes commands using **${KIMI_SHELL}**.{% if KIMI_OS == \"Windows\" %} Use Unix shell syntax inside Shell commands — `/dev/null` not `NUL`, forward slashes in paths (backslashes are escape characters in bash).{% endif +%}\n\nThe operating environment is not in a sandbox. Any actions you do will immediately affect the user's system. So you MUST be extremely cautious. Unless being explicitly instructed to do so, you should never access (read/write/execute) files outside of the working directory.\n\n## Date and Time\n\nThe current date and time in ISO format is `${KIMI_NOW}`. This is only a reference for you when searching the web, or checking file modification time, etc. If you need the exact time, use Shell tool with proper command.\n\n## Working Directory\n\nThe current working directory is `${KIMI_WORK_DIR}`. This should be considered as the project root if you are instructed to perform tasks on the project. Every file system operation will be relative to the working directory if you do not explicitly specify the absolute path. Tools may require absolute paths for some parameters, IF SO, YOU MUST use absolute paths for these parameters.\n\nThe directory listing of current working directory is:\n\n```\n${KIMI_WORK_DIR_LS}\n```\n\nUse this as your basic understanding of the project structure. The tree only shows the first two levels; entries marked \"... and N more\" indicate additional contents — use Glob or Shell to explore further.\n{% if KIMI_ADDITIONAL_DIRS_INFO %}\n\n## Additional Directories\n\nThe following directories have been added to the workspace. You can read, write, search, and glob files in these directories as part of your workspace scope.\n\n${KIMI_ADDITIONAL_DIRS_INFO}\n{% endif %}\n\n# Project Information\n\nMarkdown files named `AGENTS.md` usually contain the background, structure, coding styles, user preferences and other relevant information about the project. You should use this information to understand the project and the user's preferences. `AGENTS.md` files may exist at different locations in the project, but typically there is one in the project root.\n\n> Why `AGENTS.md`?\n>\n> `README.md` files are for humans: quick starts, project descriptions, and contribution guidelines. `AGENTS.md` complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.\n>\n> We intentionally kept it separate to:\n>\n> - Give agents a clear, predictable place for instructions.\n> - Keep `README`s concise and focused on human contributors.\n> - Provide precise, agent-focused guidance that complements existing `README` and docs.\n\nThe `AGENTS.md` instructions (merged from all applicable directories):\n\n`````````\n${KIMI_AGENTS_MD}\n`````````\n\n`AGENTS.md` files can appear at any level of the project directory tree, including inside `.kimi/` directories. Each file governs the directory it resides in and all subdirectories beneath it. When multiple `AGENTS.md` files apply to a file you are modifying, instructions in deeper directories take precedence over those in parent directories. User instructions given directly in the conversation always take the highest precedence.\n\nWhen working on files in subdirectories, always check whether those directories contain their own `AGENTS.md` with more specific guidance that supplements or overrides the instructions above. You may also check `README`/`README.md` files for more information about the project.\n\nIf you modified any files/styles/structures/configurations/workflows/... mentioned in `AGENTS.md` files, you MUST update the corresponding `AGENTS.md` files to keep them up-to-date.\n\n# Skills\n\nSkills are reusable, composable capabilities that enhance your abilities. Each skill is a self-contained directory with a `SKILL.md` file that contains instructions, examples, and/or reference material.\n\n## What are skills?\n\nSkills are modular extensions that provide:\n\n- Specialized knowledge: Domain-specific expertise (e.g., PDF processing, data analysis)\n- Workflow patterns: Best practices for common tasks\n- Tool integrations: Pre-configured tool chains for specific operations\n- Reference material: Documentation, templates, and examples\n\n## Available skills\n\nSkills are grouped by scope (`Project`, `User`, `Extra`, `Built-in`) so you can tell where each came from. When the user refers to \"the skill in this project\" or \"the user-scope skill\", use the scope heading to disambiguate. When multiple scopes define a skill with the same name, the more specific scope takes precedence: **Project overrides User overrides Extra overrides Built-in**.\n\n${KIMI_SKILLS}\n\n## How to use skills\n\nIdentify the skills that are likely to be useful for the tasks you are currently working on, read the `SKILL.md` file for detailed instructions, guidelines, scripts and more.\n\nOnly read skill details when needed to conserve the context window.\n\n# Ultimate Reminders\n\nAt any time, you should be HELPFUL, CONCISE, and ACCURATE. Be thorough in your actions — test what you build, verify what you change — not in your explanations.\n\n- Never diverge from the requirements and the goals of the task you work on. Stay on track.\n- Never give the user more than what they want.\n- Try your best to avoid any hallucination. Do fact checking before providing any factual information.\n- Think about the best approach, then take action decisively.\n- Do not give up too early.\n- ALWAYS, keep it stupidly simple. Do not overcomplicate things.\n- When the task requires creating or modifying files, always use tools to do so. Never treat displaying code in your response as a substitute for actually writing it to the file system.\n","isInternal":false,"tokens":2929,"sizeBytes":14305},{"name":"README.md","path":"examples/custom-tools/README.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/examples/custom-tools/README.md","title":"custom-tools Documentation","category":"plugin-manifest","format":"markdown","content":"# Example: Custom Tools\n\nThis example demonstrates how to write custom tools for Kimi Code CLI and add them to your agent spec file.\n\n```sh\ncd examples/custom-tools\nuv sync --reinstall\nuv run main.py\n```\n","isInternal":false,"tokens":49,"sizeBytes":204},{"name":"plugin.json","path":"examples/sample-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/examples/sample-plugin/plugin.json","title":"sample-plugin","category":"plugin-manifest","format":"json","content":"{\n \"name\": \"sample-plugin\",\n \"version\": \"1.0.0\",\n \"description\": \"Sample plugin demonstrating Skills + Tools with both Python and TypeScript tools\",\n \"tools\": [\n {\n \"name\": \"py_greet\",\n \"description\": \"Generate a greeting message (Python tool)\",\n \"command\": [\"python3\", \"scripts/greet.py\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Name to greet\"\n },\n \"lang\": {\n \"type\": \"string\",\n \"enum\": [\"en\", \"zh\", \"ja\"],\n \"description\": \"Language: en=English, zh=Chinese, ja=Japanese\"\n }\n },\n \"required\": [\"name\"]\n }\n },\n {\n \"name\": \"ts_calc\",\n \"description\": \"Evaluate a math expression and return the result (TypeScript tool)\",\n \"command\": [\"npx\", \"tsx\", \"scripts/calc.ts\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"expression\": {\n \"type\": \"string\",\n \"description\": \"Math expression to evaluate, e.g. '2 + 3 * 4'\"\n }\n },\n \"required\": [\"expression\"]\n }\n }\n ]\n}\n","frontmatter":{"name":"sample-plugin","version":"1.0.0","description":"Sample plugin demonstrating Skills + Tools with both Python and TypeScript tools","tools":[{"name":"py_greet","description":"Generate a greeting message (Python tool)","command":["python3","scripts/greet.py"],"parameters":{"type":"object","properties":{"name":{"type":"string","description":"Name to greet"},"lang":{"type":"string","enum":["en","zh","ja"],"description":"Language: en=English, zh=Chinese, ja=Japanese"}},"required":["name"]}},{"name":"ts_calc","description":"Evaluate a math expression and return the result (TypeScript tool)","command":["npx","tsx","scripts/calc.ts"],"parameters":{"type":"object","properties":{"expression":{"type":"string","description":"Math expression to evaluate, e.g. '2 + 3 * 4'"}},"required":["expression"]}}]},"isInternal":false,"tokens":294,"sizeBytes":1178},{"name":"README.md","path":"packages/kaos/README.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/packages/kaos/README.md","title":"kaos Documentation","category":"plugin-manifest","format":"markdown","content":"# PyKAOS\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nPyKAOS is a lightweight Python library providing an abstraction layer for agents to interact with operating systems. File operations and command executions via KAOS can be easily switched between local environment and remote systems over SSH.\n","isInternal":false,"tokens":131,"sizeBytes":605},{"name":"README.md","path":"packages/kimi-code/README.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/packages/kimi-code/README.md","title":"kimi-code Documentation","category":"plugin-manifest","format":"markdown","content":"# kimi-code (PyPI): legacy package, archived\n\n> [!CAUTION]\n> **This PyPI package is NOT the new Kimi Code CLI.** It is a legacy alias of the archived Python [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) and is no longer maintained.\n>\n> PyPI 上的 `kimi-code` 是已归档的旧版 Python Kimi CLI 的别名包，**不是**新版 Kimi Code CLI。\n\n## Install the new Kimi Code CLI\n\n```sh\n# macOS / Linux\ncurl -fsSL https://code.kimi.com/kimi-code/install.sh | bash\n```\n\n```powershell\n# Windows (PowerShell)\nirm https://code.kimi.com/kimi-code/install.ps1 | iex\n```\n\nAlso available via Homebrew (`brew install kimi-code`) and npm (`npm install -g @moonshot-ai/kimi-code`).\n\nThen uninstall this package: `uv tool uninstall kimi-code` (or `pip uninstall kimi-code kimi-cli`, since pip does not remove the legacy `kimi-cli` dependency automatically).\n\nMigration guide: [English](https://moonshotai.github.io/kimi-code/en/guides/migration) | [中文](https://moonshotai.github.io/kimi-code/zh/guides/migration)\n\n## Note for existing users\n\nStarting from 1.51.0, running `kimi-code` from this package only prints the instructions above. The legacy CLI it used to install is no longer supported and will stop working, so please migrate to Kimi Code CLI.\n","isInternal":false,"tokens":344,"sizeBytes":1252},{"name":"README.md","path":"packages/kosong/README.md","rawUrl":"https://raw.githubusercontent.com/MoonshotAI/kimi-cli/HEAD/packages/kosong/README.md","title":"kosong Documentation","category":"plugin-manifest","format":"markdown","content":"# Kosong\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nKosong is an LLM abstraction layer designed for modern AI agent applications. It unifies message structures, asynchronous tool orchestration, and pluggable chat providers so you can build agents with ease and avoid vendor lock-in.\n\n> Kosong means \"empty\" in Malay and Indonesian.\n\n## Installation\n\nKosong requires Python 3.12 or higher. We recommend using uv as the package manager.\n\nInit your project with:\n\n```bash\nuv init --python 3.12 # or higher\n```\n\nThen add Kosong as a dependency:\n\n```bash\nuv add kosong\n```\n\nTo enable chat providers other than Kimi (e.g. Anthropic and Google Gemini), install the optional extra:\n\n```bash\nuv add 'kosong[contrib]'\n```\n\n## Examples\n\n### Simple chat completion\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Streaming output\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider import StreamedMessagePart\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n def output(message_part: StreamedMessagePart):\n print(message_part)\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n on_message_part=output,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Tool calling with `kosong.step`\n\n```python\nimport asyncio\n\nfrom pydantic import BaseModel\n\nimport kosong\nfrom kosong import StepResult\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\nfrom kosong.tooling import CallableTool2, ToolOk, ToolReturnValue\nfrom kosong.tooling.simple import SimpleToolset\n\n\nclass AddToolParams(BaseModel):\n a: int\n b: int\n\n\nclass AddTool(CallableTool2[AddToolParams]):\n name: str = \"add\"\n description: str = \"Add two integers.\"\n params: type[AddToolParams] = AddToolParams\n\n async def __call__(self, params: AddToolParams) -> ToolReturnValue:\n return ToolOk(output=str(params.a + params.b))\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n toolset = SimpleToolset()\n toolset += AddTool()\n\n history = [\n Message(role=\"user\", content=\"Please add 2 and 3 with the add tool.\"),\n ]\n\n result: StepResult = await kosong.step(\n chat_provider=kimi,\n system_prompt=\"You are a precise math tutor.\",\n toolset=toolset,\n history=history,\n )\n print(result.message)\n print(await result.tool_results())\n\n\nasyncio.run(main())\n```\n\n## Builtin Demo\n\nKosong comes with a builtin demo agent that you can run locally. To start the demo, run:\n\n```sh\nexport KIMI_BASE_URL=\"https://api.moonshot.ai/v1\"\nexport KIMI_API_KEY=\"your_kimi_api_key\"\n\nuv run python -m kosong kimi --with-bash\n```\n\n## Development\n\nTo set up a development environment, clone the repository and install the dependencies:\n\n```bash\ngit clone https://github.com/MoonshotAI/kosong.git\ncd kosong\nuv sync --all-extras\n\nmake check # run lint and type checks\nmake test # run tests\nmake format # format code\n```\n","isInternal":false,"tokens":1069,"sizeBytes":4317}],"systemPromptSnippet":"\n\n# Kimi Code CLI\n\n## Quick commands (use uv)\n\n- `make prepare` (sync deps for all workspace packages and install git hooks)\n- `make format`\n- `make check`\n- `make test`\n- `make ai-test`\n- `make build` / `make build-bin`\n\nIf running tools directly, use `uv run ...`.\n\n## Project overview\n\nKimi Code CLI is a Python CLI agent for software engineering workflows. It supports an interactive\nshell UI, ACP server mode for IDE integrations, and MCP tool loading.\n\n## Tech stack\n\n- Python 3.12+ (tooling configured for 3.14)\n- CLI framework: Typer\n- Async runtime: asyncio\n- LLM framework: kosong\n- MCP integration: fastmcp\n- Logging: loguru\n- Package management/build: uv + uv_build; PyInstaller for binaries\n- Tests: pytest + pytest-asyncio; lint/format: ruff; types: pyright + ty\n\n## Architecture overview\n\n- **CLI entry**: `src/kimi_cli/cli/__init__.py` (Typer) parses flags (UI mode, agent spec, config, MCP)\n and routes into `KimiCLI` in `src/kimi_cli/app.py`.\n- **App/runtime setup**: `KimiCLI.create` loads config (`src/kimi_cli/config.py`), chooses a\n model/provider (`src/kimi_cli/llm.py`), builds a `Runtime` (`src/kimi_cli/soul/agent.py`),\n loads an agent spec, restores `Context`, then constructs `KimiSoul`.\n- **Agent specs**: YAML under `src/kimi_cli/agents/` loaded by `src/kimi_cli/agentspec.py`.\n Specs can `extend` base agents, select tools by import path, and register builtin subagent\n types via the `subagents` field. Subagent instances are persisted separately under the session\n directory and can be resumed by `agent_id`. System prompts live alongside specs; builtin args\n include `KIMI_NOW`, `KIMI_WORK_DIR`, `KIMI_WORK_DIR_LS`, `KIMI_AGENTS_MD`, `KIMI_SKILLS`, `KIMI_OS`, `KIMI_SHELL`\n (this file is injected via `KIMI_AGENTS_MD`).\n- **Tooling**: `src/kimi_cli/soul/toolset.py` loads tools by import path, injects dependencies,\n and runs tool calls. Built-in tools live in `src/kimi_cli/tools/` (agent, shell, file, web,\n todo, background, dmail, think, plan). MCP tools are loaded via `fastmcp`; CLI management is\n in `src/kimi_cli/mcp.py` and stored in the share dir.\n- **Subagents**: `LaborMarket` in `src/kimi_cli/soul/agent.py` registers builtin subagent types.\n The `Agent` tool (`src/kimi_cli/tools/agent/`) creates or resumes subagent instances, while\n `SubagentStore` persists instance metadata, prompts, wire logs, and context under\n `session/subagents//`.\n- **Core loop**: `src/kimi_cli/soul/kimisoul.py` is the main agent loop. It accepts user input,\n handles slash commands (`src/kimi_cli/soul/slash.py`), appends to `Context`\n (`src/kimi_cli/soul/context.py`), calls the LLM (kosong), runs tools, and performs compaction\n (`src/kimi_cli/soul/compaction.py`) when needed.\n- **Approvals**: `src/kimi_cli/soul/approval.py` is the tool-facing facade. `ApprovalRuntime`\n in `src/kimi_cli/approval_runtime/` is the session-level source of truth for pending approvals,\n and approval requests are projected onto the root wire stream for Shell/Web style UIs.\n- **UI/Wire**: `src/kimi_cli/soul/run_soul` connects `KimiSoul` to a `Wire`\n (`src/kimi_cli/wire/`) so UI loops can stream events. UIs live in `src/kimi_cli/ui/`\n (shell/print/acp/wire).\n- **Shell UI**: `src/kimi_cli/ui/shell/` handles interactive TUI input, shell command mode,\n and slash command autocomplete; it is the default interactive experience.\n- **Slash commands**: Soul-level commands live in `src/kimi_cli/soul/slash.py`; shell-level\n commands live in `src/kimi_cli/ui/shell/slash.py`. The shell UI exposes both and dispatches\n based on the registry. Standard skills register `/skill:` and load `SKILL.md`\n as a user prompt; flow skills register `/flow:` and execute the embedded flow.\n\n## Major modules and interfaces\n\n- `src/kimi_cli/app.py`: `KimiCLI.create(...)` and `KimiCLI.run(...)` are the main programmatic\n entrypoints; this is what UI layers use.\n- `src/kimi_cli/soul/agent.py`: `Runtime` (config, session, builtins), `Agent` (system prompt +\n toolset), and `LaborMarket` (builtin subagent type registry).\n- `src/kimi_cli/soul/kimisoul.py`: `KimiSoul.run(...)` is the loop boundary; it emits Wire\n messages and executes tools via `KimiToolset`.\n- `src/kimi_cli/soul/context.py`: conversation history + checkpoints; used by DMail for\n checkpointed replies.\n- `src/kimi_cli/soul/toolset.py`: load tools, run tool calls, bridge to MCP tools.\n- `src/kimi_cli/ui/*`: shell/print/acp frontends; they consume `Wire` messages.\n- `src/kimi_cli/wire/*`: event types and transport used between soul and UI.\n\n## Repo map\n\n- `src/kimi_cli/agents/`: built-in agent YAML specs and prompts\n- `src/kimi_cli/prompts/`: shared prompt templates\n- `src/kimi_cli/soul/`: core runtime/loop, context, compaction, approvals\n- `src/kimi_cli/tools/`: built-in tools\n- `src/kimi_cli/ui/`: UI frontends (shell/print/acp/wire)\n- `src/kimi_cli/acp/`: ACP server components\n- `packages/kosong/`, `packages/kaos/`: workspace deps\n + Kosong is an LLM abstraction layer designed for modern AI agent applications.\n It unifies message structures, asynchronous tool orchestration, and pluggable\n chat providers so you can build agents with ease and avoid vendor lock-in.\n + PyKAOS is a lightweight Python library providing an abstraction layer for agents\n to interact with operating systems. File operations and command executions via KAOS\n can be easily switched between local environment and remote systems over SSH.\n- `tests/`, `tests_ai/`: test suites\n- `klips`: Kimi Code CLI Improvement Proposals\n\n## Conventions and quality\n\n- Python >=3.12 (ty config uses 3.14); line length 100.\n- Ruff handles lint + format (rules: E, F, UP, B, SIM, I); pyright + ty for type checks.\n- Tests use pytest + pytest-asyncio; files are `tests/test_*.py`.\n- CLI entry points: `kimi` / `kimi-cli` -> `src/kimi_cli/__main__.py` (routes to `src/kimi_cli/cli/__init__.py`).\n- User config: `~/.kimi/config.toml`; logs, sessions, and MCP config live in `~/.kimi/`.\n\n## Git commit messages\n\nConventional Commits format:\n\n```\n(): \n```\n\nAllowed types:\n`feat`, `fix`, `test`, `refactor`, `chore`, `style`, `docs`, `perf`, `build`, `ci`, `revert`.\n\n## Versioning\n\nThe project follows a **minor-bump-only** versioning scheme (`MAJOR.MINOR.PATCH`):\n\n- **Patch** version is always `0`. Never bump it.\n- **Minor** version is bumped for any change: new features, improvements, bug fixes, etc.\n- **Major** version is only changed by explicit manual decision; it stays unchanged during\n normal development.\n\nExamples: `0.68.0` → `0.69.0` → `0.70.0`; never `0.68.1`.\n\nThis rule applies to all packages in the repo (root, `packages/*`, `sdks/*`) as well as release\nand skill workflows.\n\n## Release workflow\n\nFor the full procedure, follow the `release` skill (`.agents/skills/release/SKILL.md`). The summary:\n\n1. Ensure `main` is up to date (pull latest).\n2. Create a release branch, e.g. `bump-0.68` or `bump-pykaos-0.5.3`.\n3. Update `CHANGELOG.md`: add a new `## 0.68 (YYYY-MM-DD)` section below `## Unreleased` (do not rename `## Unreleased`).\n4. Update `pyproject.toml` version.\n5. Run `uv sync` to align `uv.lock`.\n6. Commit the branch and open a PR.\n7. Merge the PR, then switch back to `main` and pull latest.\n8. Tag and push:\n - `git tag 0.68` or `git tag pykaos-0.5.3`\n - `git push --tags`\n9. GitHub Actions handles the release after tags are pushed.\n\n\n# Documentation Agent Guide\n\nThis repository uses VitePress for the documentation site. The current docs are structural scaffolds only; everything beyond the headings is placeholder guidance. The `Reference Code` blocks are there to guide future writing and should be removed once the docs are complete.\n\n## Structure\n\n- Locales live under `docs/en/` and `docs/zh/` with mirrored paths and filenames.\n- Main sections (nav + sidebar) are:\n - Guides: getting-started, use-cases, interaction, sessions, ides, integrations\n - Customization: mcp, skills, agents, print-mode, wire-mode\n - Configuration: config-files, providers, overrides, env-vars, data-locations\n - Reference: kimi-command, kimi-acp, kimi-mcp, slash-commands, keyboard, tools, exit-codes\n - FAQ: setup, interaction, acp, mcp, print-wire, updates\n - Release notes: changelog, breaking-changes\n- Navigation and sidebar are defined in `docs/.vitepress/config.ts`. Any new or renamed page must be wired there for both locales.\n\n## Source of truth\n\n- **Changelog page**: The English version (`docs/en/release-notes/changelog.md`) is the source of truth. It is auto-synced from the root `CHANGELOG.md` via script. The Chinese changelog should be translated from the English version.\n- **All other pages**: The Chinese version (`docs/zh/`) is the source of truth. English translations should be based on the Chinese docs.\n\nOnly the Chinese documentation and the English changelog are manually reviewed. Other translations (e.g., English versions of non-changelog pages) may be auto-generated by AI agents.\n\n## Authoring workflow\n\n- Each page is a scaffold: expand the bullets into prose while keeping the section ordering, and keep the `::: info Reference Code` blocks aligned with the relevant section.\n- For changelog: edit the root `CHANGELOG.md`, then run `npm run sync` to update the English docs.\n- For other pages: edit the Chinese version first, then translate to English.\n\n## Naming conventions\n\n- Filenames are kebab-case and mirror across locales (same slug in `docs/en/` and `docs/zh/`).\n- Use consistent section labels that match the sidebar titles.\n- Use backticks for flags, commands, subcommands, command arguments, file paths, code identifiers, type names, field names, field values, and keyboard shortcuts.\n\n## Wording conventions\n\n- Do not change H1 titles or nav/sidebar labels.\n- English H2+ headings use sentence case (only the first word capitalized unless it is a proper noun). Treat \"Wire\" as a proper noun; do not treat \"agent\", \"shell mode\", or \"print mode\" as proper nouns.\n- Chinese H2+ headings keep English words in sentence case; preserve proper nouns listed in the term table below.\n- Use `API key` in English and `API 密钥` in Chinese; keep `JSON`, `JSONL`, `OAuth`, `macOS`, and `uv` as-is.\n- Use straight double quotes with spaces for quoted content: `\"被引内容\"` (not curly quotes). Add a space before and after the quoted text when adjacent to CJK characters. Use corner brackets `「」` for special terms (e.g., `「工具」`, `「会话」`).\n- Prefer \"终端\" over \"命令行\" in Chinese when both are applicable (e.g., \"运行在终端中\", \"终端界面\", \"终端操作\").\n- Use \"工具调用\" / \"tool call\", not \"工具使用\" / \"tool use\".\n- Use inline code for tool names (e.g., `Task`, `ReadFile`, `Shell`).\n\nTerm mapping (Chinese <-> English, and proper noun handling):\n\n| Chinese | English | Proper noun (zh) | Proper noun (en) |\n| --- | --- | --- | --- |\n| Agent | agent | yes | no |\n| Shell | shell | yes | no |\n| Shell 模式 | shell mode | yes | no |\n| Print 模式 | print mode | yes | no |\n| Wire 模式 | Wire mode | yes | yes (Wire) |\n| Thinking 模式 | thinking mode | yes | no |\n| MCP | MCP | yes | yes |\n| ACP | ACP | yes | yes |\n| Kimi Code CLI | Kimi Code CLI | yes | yes |\n| Agent Skills | Agent Skills | yes | yes |\n| Skill | skill | yes | no |\n| 系统提示词 | system prompt | no | no |\n| 提示词 | prompt | no | no |\n| 会话 | session | no | no |\n| 上下文 | context | no | no |\n| 子 Agent | subagent | yes (Agent) | no |\n| API 密钥 | API key | yes | no |\n| JSON | JSON | yes | yes |\n| JSONL | JSONL | yes | yes |\n| OAuth | OAuth | yes | yes |\n| macOS | macOS | yes | yes |\n| uv | uv | yes | yes |\n| 审批请求 | approval request | no | no |\n| 斜杠命令 | slash command | no | no |\n| 工具调用 | tool call | no | no |\n| Frontmatter | frontmatter | yes | no |\n| User 消息 | user message | yes (User) | no |\n| Assistant 消息 | assistant message | yes (Assistant) | no |\n| Tool 消息 | tool message | yes (Tool) | no |\n| 轮次 | turn | no | no |\n| 供应商 | provider | no | no |\n| Prompt Flow | Prompt Flow | yes | yes |\n| Ralph 循环 | Ralph Loop | yes | yes |\n| Diff | diff | yes | no |\n\nJetBrains IDE terminology (Chinese UI translations):\n\n| English | Chinese |\n| --- | --- |\n| AI Chat | AI 聊天 |\n| Registry | 注册表 |\n| Configure ACP agents | (未翻译) |\n\n## Typography\n\n- **Spacing around mixed content**: Add a space between Chinese characters and English words, numbers, inline code, or links. Exception: no space before full-width punctuation.\n - ✓ 在 Python 中使用 \\`class\\` 关键字\n - ✗ 在Python中使用\\`class\\`关键字\n - ✓ 详见 \\[配置文件\\](./config.md)。\n - ✗ 详见\\[配置文件\\](./config.md)。\n- **Full-width punctuation**: Use full-width punctuation in Chinese text: `，。；：？！（）` not `, . ; : ? ! ( )`.\n- **Code block language**: Always specify language for fenced code blocks (e.g., ` ```sh `, ` ```toml `, ` ```json `). Exception: natural language examples (user prompts) may omit the language.\n- **Callout titles**: Use short category titles for callout blocks (`::: tip`, `::: warning`, `::: info`, `::: danger`). Put the detailed description in the block content, not the title.\n - Chinese: use `提示` for tip, `注意` for warning, `说明` for info, `警告` for danger.\n - English: use no title or short words like `Note` for warning.\n - ✓ `::: tip 提示` + content starting with the key point\n - ✓ `::: warning 注意` + content `\\`KIMI_SHARE_DIR\\` 不影响 Skills 的搜索路径。...`\n - ✗ `::: warning 不影响 Skills` (title too long, should be in content)\n - ✗ `::: tip Skills 路径独立于 KIMI_SHARE_DIR` (title too long)\n- **Version info blocks**: For version change callouts, use `::: info` with a category title (Added/Changed/Removed in English; 新增/变更/移除 in Chinese). The content should be a complete sentence.\n - ✓ `::: info 新增` + content `新增于 Wire 1.2。`\n - ✗ `::: info 新增于 Wire 1.2` (title too long)\n - ✓ `::: info Changed` + content `Renamed in Wire 1.1. ...`\n - ✗ `::: info Renamed in Wire 1.1` (title too long)\n\n## Writing style\n\n- **Natural narrative**: Organize content like writing an article, guiding readers smoothly through the material.\n- **Avoid fragmentation**: Don't turn every point into a subheading; use paragraph transitions instead.\n- **Global perspective**: \"Getting Started\" introduces core concepts only; detailed usage belongs in later pages.\n- **Progressive depth**: Guides → Customization → Configuration → Reference, information deepens gradually.\n- **No \"next steps\"**: VitePress already provides prev/next navigation; don't add manual `::: tip 接下来` blocks at page end.\n\n### Example: good vs bad\n\nOutline prompt:\n\n```\n* Install and upgrade\n * System requirements: Python 3.12+, recommend uv\n * Install, upgrade, uninstall steps\n```\n\n**Bad** (mechanical conversion to headings):\n\n```markdown\n## Install and upgrade\n\n### System requirements\n\n- Python 3.12+\n- Recommend uv\n\n### Install\n\n...\n\n### Upgrade\n\n...\n```\n\n**Good** (natural narrative):\n\n```markdown\n## Install and upgrade\n\nKimi Code CLI requires Python 3.12+. We recommend using uv for installation and management.\n\nIf you haven't installed uv yet, please refer to the uv installation docs first. Install Kimi Code CLI:\n\n(code block)\n\nVerify the installation:\n\n(code block)\n\nUpgrade to the latest version:\n\n(code block)\n```\n\n## Build and preview\n\n- Docs are built with VitePress from `docs/`.\n- Common commands (run inside `docs/`):\n - `npm install` (or `bun install` if you use bun)\n - `npm run dev`\n - `npm run build`\n - `npm run preview`\n- The build output is `docs/.vitepress/dist`.\n\n## Changelog syncing\n\nThe English changelog (`docs/en/release-notes/changelog.md`) is auto-generated from the root `CHANGELOG.md`. Do not edit it manually.\n\n- The sync script is `docs/scripts/sync-changelog.mjs`.\n- It runs automatically before `npm run dev` and `npm run build`.\n- To run manually: `npm run sync` (from the `docs/` directory).\n- The script converts title format (`## [0.69] - 2025-12-29` → `## 0.69 (2025-12-29)`) and removes HTML comments.\n\n\n# tests_e2e Wire E2E Guide\n\n## Goals and Scope\n- Test only `kimi --wire` JSON-RPC + wire messages; no Shell UI/Print/ACP/Term/shortcuts.\n- Do not test `--agent okabe`.\n- Do not test: W-23, W-26, W-29, W-27 (env overrides).\n\n## Execution Rules\n- Tests run via `uv run kimi` by default; set `KIMI_E2E_WIRE_CMD` to override the base command\n (e.g. `../kimi-agent-rs/target/debug/kimi-agent` or `kimi-agent` on PATH). `--wire` is appended if missing.\n- Always isolate `HOME`, `USERPROFILE`, and `KIMI_SHARE_DIR`, and use a temporary `--work-dir` to\n avoid touching real `~/.kimi`.\n- Use `inline_snapshot` for snapshot testing; snapshots can start empty and be updated later.\n- Wire traffic is line-delimited JSON; `event`/`request`/responses may interleave.\n\n## Test Matrix\n**Startup and Protocol**\n- W-01 Handshake: `initialize` returns `protocol_version=1.1`, `server`, and non-empty\n `slash_commands`.\n- W-02 External tool registration and call: register `external_tools`, trigger a\n `ToolCallRequest`, return `ToolResult`, turn finishes.\n- W-03 External tool conflict: registering a tool name that conflicts with a built-in is\n rejected with a reason.\n- W-04 Prompt without handshake: send `prompt` without `initialize`, turn still completes.\n- W-05 LLM not set: missing config yields `-32001` (LLM is not set).\n- W-06 Max steps: set a tiny `--max-steps-per-turn`, response is `status=max_steps_reached`.\n\n**Prompt and Event Stream**\n- W-07 Basic turn: `TurnBegin`/`StepBegin`/`ContentPart(text)`/`StatusUpdate` flow.\n- W-08 Multiline input: `TurnBegin.user_input` preserves newlines.\n- W-09 Content parts input: `user_input` as `ContentPart[]` (text/image/audio/video) with\n capabilities enabled.\n- W-10 Thinking toggle: `--thinking` emits `ContentPart(type=think)`, `--no-thinking` does not\n (real LLM).\n- W-11 Concurrent prompt: second `prompt` returns `-32000` (turn already in progress).\n- W-12 Cancel turn: `cancel` returns `{}`, original `prompt` becomes `status=cancelled`\n (may emit `StepInterrupted`, real LLM).\n\n**Tools and Approvals**\n- W-13 Shell approval: `Shell` triggers `ApprovalRequest`, `approve` yields `ToolResult`.\n- W-14 Approval reject: `reject` ends turn; tool does not run.\n- W-15 Session approval: `approve_for_session` removes subsequent blocking approvals.\n- W-16 YOLO: `--yolo` skips blocking approvals.\n- W-17 DisplayBlock coverage: `Shell`/`WriteFile`/`StrReplaceFile`/`SetTodoList` emit expected\n display types.\n- W-18 Tool args streaming: `ToolCallPart.arguments_part` can be stitched into full args.\n\n**Sessions and Context**\n- W-19 Session files: `--session ` writes `context.jsonl` and `wire.jsonl`.\n- W-20 Continue session: `--continue` appends to the same session files.\n- W-21 Clear context: `/clear` ensures the next `prompt` does not rely on prior context.\n- W-22 Manual compaction: `/compact` triggers `CompactionBegin/CompactionEnd`.\n- W-24 Status stats: `StatusUpdate.context_usage/token_usage` types are valid and change over time.\n\n**Config and Runtime Flags**\n- W-25 `--config` inline: JSON/TOML string config works.\n- W-28 CLI override: `--model` overrides `default_model`.\n- W-30 Work dir: `prompt` asks \"where is the current directory\", verify `--work-dir` (real LLM).\n\n**Extensions (Agents/Skills/MCP)**\n- W-31 Built-in agent boundary: `default` calling `SendDMail` fails or is rejected.\n- W-32 Custom agent: `--agent-file` excludes tool and calls are rejected.\n- W-33 Subagents: prompt \"parallel call two task tools, each runs shell sleep 0.5 and 1 second\";\n verify Task/SubagentEvent streaming/ToolResult/multiple approvals (real LLM).\n- W-34 Skill call: create a test skill, `/skill:test` injects `SKILL.md` (wire has no `/help`).\n- W-35 Flow skill: `/flow:` runs the flow until `END`.\n- W-36 MCP: use a Python fastmcp test server, load via `--mcp-config-file`, verify tool works.\n\n**Resilience and Errors**\n- W-37 Invalid JSON: malformed JSON line returns `-32700`.\n- W-38 Invalid request: missing fields returns `-32600`.\n- W-39 Unknown method: returns `-32601`.\n- W-40 Invalid params: bad structure returns `-32602`.\n- W-41 Cancel without active turn: returns `-32000`.\n- W-42 LLM errors: unsupported model `-32002` and service error `-32003`.\n\n## Real LLM Placeholders\n- W-10/W-12/W-30/W-33 require a real provider; everything else uses `_scripted_echo`.\n\n\n---\nname: codex-worker\ndescription: Spawn and manage multiple Codex CLI agents via tmux to work on tasks in parallel. Use whenever a task can be decomposed into independent subtasks (e.g. batch triage, parallel fixes, multi-file refactors). When codex and tmux are available, prefer this over the built-in Task tool for parallelism.\n---\n\n# codex-worker\n\nOrchestrate multiple Codex CLI (`codex`) agents running in parallel, each in its\nown git worktree and tmux session.\n\n**When to use:** Whenever you identify that a task can be split into independent\nsubtasks — don't wait for the user to ask for parallelism. Examples:\n- User says \"triage all open issues updated in the last 7 days\" → fetch the\n issue list, then spawn one codex worker per issue.\n- User says \"refactor these 5 modules\" → one worker per module.\n- User says \"fix lint errors across packages\" → one worker per package.\n\n**Replaces Task tool:** When `codex` and `tmux` are available in the\nenvironment, use codex workers instead of the built-in Task (subagent) tool.\nCodex workers are full-featured agents with their own file system access, shell,\nand isolated worktree — far more capable than subagents.\n\n## Preflight check\n\n```bash\ncommand -v codex && codex login status && command -v tmux\n```\n\nAll three must succeed. The project must be a git repository.\n\n## Naming convention\n\nGit branch and worktree directory share a **task name**:\n\n```\n--\n```\n\nThe tmux session adds a `codex-worker-` prefix so workers are easy to filter:\n\n| | Format | Example |\n|---|---|---|\n| Task name | `--` | `issue-836-prompt-dollar-sign` |\n| Git branch | same as task name | `issue-836-prompt-dollar-sign` |\n| Worktree dir | `.worktrees/` | `kimi-cli.worktrees/issue-836-prompt-dollar-sign` |\n| tmux session | `codex-worker-` | `codex-worker-issue-836-prompt-dollar-sign` |\n\nMore examples:\n- `issue-518-mcp-config-isolation`\n- `fix-share-dir-skills-path`\n- `feat-ask-user-tool`\n- `refactor-jinja-templates`\n\nList only codex workers: `tmux ls | grep ^codex-worker-`\n\n## Usage\n\nPrefer tmux + interactive codex for all tasks. It supports multi-turn dialogue,\nthe user can `tmux attach` to inspect or intervene, and you can send follow-up\nprompts from outside.\n\n### Spawn a worker\n\n```bash\nNAME=\"issue-836-prompt-dollar-sign\" # task name\nSESSION=\"codex-worker-$NAME\" # tmux session name\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\n# 1. Create worktree (skip if exists)\ngit worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n\n# 2. Launch interactive codex inside tmux\ntmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n```\n\n### Send a prompt\n\nThe Codex TUI needs time to initialize before it accepts input.\nAfter launching a session, **wait at least 5 seconds** before sending\na prompt. Then send the text followed by `Enter`. If the prompt stays\nin the input field without being submitted, send an additional `Enter`.\n\n```bash\nsleep 5 # wait for Codex TUI to initialize\ntmux send-keys -t \"$SESSION\" \"Your prompt here\" Enter\n# If it doesn't submit, send another Enter:\n# tmux send-keys -t \"$SESSION\" Enter\n```\n\n### Peek at output\n\n```bash\ntmux capture-pane -t \"$SESSION\" -p | tail -30\n```\n\n### Attach for hands-on interaction\n\n```bash\ntmux attach -t \"$SESSION\"\n```\n\n### Parallel fan-out\n\n```bash\nTASKS=(\n \"issue-518-mcp-config-isolation|Triage #518: MCP config 被子 agent 继承的隔离问题。分析根因，给出修复方案。\"\n \"issue-836-prompt-dollar-sign|Triage #836: prompt 包含 $ 时启动静默失败。分析根因，给出修复方案。\"\n)\n\nPROJECT_DIR=\"$(pwd)\"\nWORKTREE_DIR=\"$PROJECT_DIR.worktrees\"\n\nfor entry in \"${TASKS[@]}\"; do\n NAME=\"${entry%%|*}\"\n PROMPT=\"${entry#*|}\"\n SESSION=\"codex-worker-$NAME\"\n git worktree add \"$WORKTREE_DIR/$NAME\" -b \"$NAME\" main 2>/dev/null\n tmux new-session -d -s \"$SESSION\" -x 200 -y 50 \\\n \"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox\"\n sleep 5 # wait for Codex TUI to fully initialize\n tmux send-keys -t \"$SESSION\" \"$PROMPT\" Enter\ndone\n```\n\n### Fallback: `codex exec`\n\nOnly use `codex exec` when you explicitly don't need follow-up (e.g. CI, pure\nanalysis with `-o` output). It does not support multi-turn dialogue.\n\n```bash\ncodex exec --dangerously-bypass-approvals-and-sandbox \\\n -o \"/tmp/$NAME-result.md\" \\\n \"Your prompt here\"\n```\n\n## Lifecycle management\n\nList active workers:\n\n```bash\ntmux ls | grep ^codex-worker-\n```\n\nKill a finished worker:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\"\n```\n\nClean up worktree after merging:\n\n```bash\ntmux kill-session -t \"codex-worker-$NAME\" 2>/dev/null\ngit worktree remove \"$WORKTREE_DIR/$NAME\"\ngit branch -d \"$NAME\"\n```\n\nBatch cleanup of dead sessions:\n\n```bash\ntmux list-sessions -F '#{session_name}:#{pane_dead}' \\\n | grep ':1$' \\\n | cut -d: -f1 \\\n | xargs -I{} tmux kill-session -t {}\n```\n\n\n# Prompt 模板\n\n以下模板作为脚手架使用。运行前替换占位符。\n\n## 单轮还是多轮\n\n满足以下任一条件时使用多轮：\n\n- 功能有状态\n- 功能依赖时序或并发\n- 功能需要审批、清理或恢复\n- session 产物本身是证据的一部分\n- 工具接口可能近期发生过变化\n\n仅对无状态的窄范围检查使用单轮。\n\n## 变量\n\n起草 prompt 前填写以下字段：\n\n- `` — 被测功能名称\n- `` — 当前场景的目标\n- `` — 需要阅读的源码路径\n- `` — 执行约束\n- `` — 成功信号\n- `` — 失败信号\n- `` — 需要检查的产物路径\n- `` — session 目录路径\n\n## 探索 prompt\n\n```text\n我要验证 。\n\n先阅读这些文件并只总结当前真实对外接口，不要假设旧文档、旧 prompt 或旧 tool 名称仍然正确：\n\n\n然后给我一个最小 smoke test 计划，只包含：\n1. happy path\n2. 一个边界/异常场景\n3. 一个清理、恢复或中断场景\n\n每个场景都写清楚目标、预期信号和要检查的产物。\n```\n\n## 执行 prompt\n\n```text\n在当前 session 里只执行这个场景：\n\n约束：\n\n\n执行前先复述你将使用的工具或命令。执行时记录关键 task id、输出片段、文件路径和任何需要后续复盘的标识符。不要扩展到其他场景。\n```\n\n## 观察 prompt\n\n```text\n现在不要继续跑新的测试。\n\n只读取并总结这次运行已经产生的状态和文件：\n\n\n请明确指出哪些证据支持了预期，哪些证据反驳了预期，哪些地方仍然不确定。\n```\n\n## 复盘 prompt\n\n```text\n请根据这个 session 目录复盘整个 smoke test：\n\n\n重点阅读 context.jsonl、wire.jsonl 和相关运行产物。输出：\n1. 实际执行流程\n2. 关键 tool 调用与结果\n3. 与预期不一致的点\n4. 最小复现步骤\n```\n\n## 兼容性校验 prompt\n\n```text\n在运行 smoke test 之前，先从提供的文档或代码中复述当前真实可用的工具及其准确名称。不要臆造旧版工具名。如果任务涉及状态或时序，将工作拆分为多轮而非一次性长回复。\n```\n\n\n---\nname: feature-smoke-test\ndescription: 针对 Kimi Code CLI 的新增或变更功能，规划并执行可重复的端到端冒烟测试。从 git diff 推断功能边界，读取相关文档和代码，设计测试 prompt，以 --print 非交互模式运行本地 CLI，检查进程退出码和 session 产物，总结预期与实际行为之间的差异。发现问题时自动启动多路并行探查以定位根因。\n---\n\n冒烟测试是运行时验证，不是写完 prompt 或读完代码就结束。必须实际执行、实际检查产物。\n\n## 确定测试范围\n\n动手之前，先从代码变更推断功能边界：\n\n```sh\ngit diff main --name-only\ngit diff main --stat\n```\n\n根据变更文件集合，明确写下：\n\n- 被测的功能边界\n- 用户可感知的行为变化\n- 运行前的准备工作和运行后的清理工作\n- 能够证明成功或失败的证据\n\n如果功能涉及状态、异步、审批流或时序敏感逻辑，默认认为单条 prompt 不够。\n\n## 先读事实来源\n\n读取定义该功能真实行为的最小文件集合：\n\n- 面向用户的文档、changelog 或设计笔记\n- 暴露该功能的 agent prompt 或 tool prompt\n- 实现层入口\n- 已有测试——当测试比文档更准确地描述行为时优先看测试\n\n不要信任过时的 prompt 示例。先从代码或当前文档重建真实的工具接口。\n\n## 制定最小测试计划\n\n默认覆盖三个场景：\n\n1. 正常路径\n2. 边界条件、非法输入或容量极限\n3. 中断、重试、清理或恢复\n\n每个场景记录：\n\n- `目标`\n- `前置准备`\n- `prompt 策略`\n- `成功信号`\n- `失败信号`\n- `需要检查的产物`\n\n如果功能存在竞态条件，必须显式标注时序。用长时间运行的命令或刻意的等待来制造时序窗口，不要用\"快速再跑一个\"这种模糊说法。\n\n## 优先使用多轮 prompt\n\n默认采用多轮流程：\n\n1. 探索轮：让 agent 在阅读事实来源后复述当前真实接口\n2. 执行轮：只执行一个场景\n3. 观察轮：只读取输出、工具状态和产物文件，不扩大范围\n4. 清理轮：停止、回滚或关闭有状态资源\n\n仅对无状态的简单功能使用单轮 prompt。\n\n多轮测试时，每一轮单独调用 CLI，在两轮之间检查上一轮的输出和产物，再决定下一轮的 prompt。不要把多轮 prompt 一次性塞进 stdin——那是盲写，无法根据上一轮结果调整。\n\n测试时，显式要求 agent 先列举当前可用的工具，不要臆造历史工具名。可复用的 prompt 模板见 `references/prompt-patterns.md`。\n\n## 以非交互模式隔离运行 CLI\n\n使用 `/tmp` 下的一次性目录作为 `--work-dir`，实现 session 隔离。CLI 的 session 路径由 `~/.kimi/sessions//` 决定，不同的 work-dir 自动产生独立的 session 命名空间，不会污染正常项目的 session。认证状态保留在 `~/.kimi` 下，无需额外配置。\n\n### 环境准备\n\n```sh\nSMOKE_DIR=\"$(mktemp -d /tmp/kimi-smoke-XXXXXX)\"\n```\n\n如果功能需要仓库上下文（读取代码、git 信息等），把仓库文件复制或软链到 `SMOKE_DIR`。如果功能会编辑文件，绝不要用活跃仓库作为 work-dir。\n\n### 默认执行方式\n\n绝大多数场景使用这个模式：\n\n```sh\nuv run python -m kimi_cli.cli \\\n --print \\\n --prompt \"你的测试 prompt\" \\\n --work-dir \"$SMOKE_DIR\"\necho \"exit_code=$?\"\n```\n\n`--print` 会自动启用 `--yolo`（自动批准所有操作），适合无人值守的冒烟测试。\n\n执行后**必须先检查退出码**：非零表示 CLI 本身崩溃或超时，应优先排查进程级错误，再看 session 产物。\n\n### 备选执行模式\n\n当默认方式不满足需求时，按需选用：\n\n- **长 prompt**：通过 stdin 传入——`cat <<'PROMPT' | uv run python -m kimi_cli.cli --print --input-format text --work-dir \"$SMOKE_DIR\"`\n- **结构化输出**：加 `--output-format stream-json`，输出逐行 JSON，便于程序化解析\n- **只看最终结果**：用 `--quiet`，等价于 `--print --output-format text --final-message-only`\n\n### 注意事项\n\n- 运行过程中记录这些路径：`SMOKE_DIR`、最终 session 目录（可通过 `inspect_session.py` 定位）、功能特定的输出文件。\n\n## 刻意执行\n\n执行过程中维护一份简短的运行日志：\n\n- 使用的完整 prompt\n- 关键的工具调用或命令\n- 功能产生的 task id、输出路径或审批 id\n- 时序敏感时记录时间戳\n\n不要仅凭 assistant 的最终文本推断正确性。运行时文件和工具结果才是事实来源。\n\n## 检查 session 产物\n\n首先检查：\n\n- `~/.kimi/sessions/.../context.jsonl`\n- `~/.kimi/sessions/.../wire.jsonl`\n- 功能创建的 session 级文件\n\n使用 `scripts/inspect_session.py` 查找并汇总最新 session：\n\n```sh\nuv run python .agents/skills/feature-smoke-test/scripts/inspect_session.py --share-dir ~/.kimi\n```\n\n脚本退出码含义：0 = 正常汇总，1 = session 目录缺失或无法解析。\n\n如果功能会创建后台任务、通知或附属文件，直接检查这些文件，不要只依赖模型摘要。\n\n## 汇报结论\n\n将结果分为三类：\n\n- **已确认**的行为\n- **与预期不符**的行为\n- **仍有歧义**、需要更确定性复现的行为\n\n对于每个 bug 或回归，记录：\n\n- 触发它的 prompt\n- 精确的 session 路径\n- 证明它的产物路径\n- 能推导出的最小复现步骤\n\n## 问题探查\n\n当发现与预期不符的行为时，不要停在报告层面。启动并行探查流程定位根因：\n\n### 探查策略\n\n针对每个发现的问题，**同时启动多个独立的探查方向**（使用 Agent 工具并行执行）。根据问题的具体表现自行判断最有价值的探查角度，常见方向包括但不限于：\n\n- 从触发问题的入口沿调用链追踪实际执行路径\n- 检查输入数据经过各处理阶段后的变化\n- 检查持久化状态（session 文件、后台任务、通知记录等）是否一致\n- 运行相关单元测试和集成测试，确认测试是否覆盖了出问题的路径\n\n不必机械地覆盖所有方向。根据 session 产物中的具体异常信号，选择最可能命中根因的 2-3 个方向并行展开。\n\n### 探查输出\n\n每条探查方向独立汇报：\n\n- 探查的具体方向和范围\n- 发现的事实（附文件路径和行号）\n- 该方向的结论：已定位根因 / 已排除 / 需要进一步调查\n\n### 综合定位\n\n汇总所有探查结果后，输出：\n\n- **根因**：一句话总结问题的本质原因\n- **证据链**：从触发 prompt → 代码路径 → 出错点 → 产物表现的完整链路\n- **修复建议**：最小改动方案，附具体文件和行号\n- **回归风险**：修复后需要额外验证的相关功能\n\n\n---\nname: gen-changelog\ndescription: Generate changelog entries for code changes.\n---\n\nGenerate changelog entries for changes on the current branch relative to `main`, then sync to the docs site.\n\n## Steps\n\n1. **Inspect**: `git log main..HEAD --oneline` + `git diff main..HEAD --stat`.\n2. **Edit root CHANGELOG**: add bullets under `## Unreleased` in `CHANGELOG.md` using the prefix table below. For changes scoped to a subpackage under `packages/` or `sdks/`, **also** update that subpackage's `CHANGELOG.md` — subpackage CHANGELOGs follow their own prefix conventions (e.g. `packages/kosong/CHANGELOG.md` uses provider prefixes like `Kimi:` / `Anthropic:`); only the root CHANGELOG follows the table below.\n3. **Sync English docs**: `node docs/scripts/sync-changelog.mjs`.\n4. **Translate to Chinese**: hand-write equivalents under `## 未发布` in `docs/zh/release-notes/changelog.md`. Use the full-width colon `：`. Follow `docs/AGENTS.md` terminology.\n5. **Breaking changes**: if any, add a section under `## Unreleased` in `docs/en/release-notes/breaking-changes.md` with **Affected** + **Migration** subsections, and under `## 未发布` in `docs/zh/release-notes/breaking-changes.md` with **受影响** + **迁移** subsections.\n\n## Entry format\n\n```\n- : — \n```\n\n- **First sentence stands alone** — readers should know after one sentence whether the bullet matters to them.\n- **One change per bullet.** No `; also`, `; and`, or nested em-dashes. Two changes = two bullets.\n- **Verb-led**: `Fix …` / `Add …` / `Switch …` / `Bump …`.\n- **User-meaningful only.** No internal refactors, test churn, or CI tweaks — except `Lib:` for SDK-facing changes.\n\n## Prefixes — pick from this list, do not invent new ones\n\n| Prefix | Scope |\n|---|---|\n| `Shell` | Interactive TUI: keys, status bar, slash commands, terminal rendering |\n| `Web` | `kimi web` |\n| `Vis` | `kimi vis` tracing visualizer |\n| `CLI` | Top-level flags, subcommands, `--print` / `--yolo` / `--afk` |\n| `ACP` | Zed / JetBrains and other ACP integrations |\n| `Core` | Agent runtime, step loop, approval, quota, turns, background tasks |\n| `Tool` | Any built-in tool; name the specific tool in the body (ReadFile, Grep, Todo, Plan, …) |\n| `Skill` | Skill discovery/loading, Flow, Loop (always singular — not `Skills:`) |\n| `MCP` | MCP server integration |\n| `Plugin` | Plugin system, `kimi plugin` subcommands |\n| `LLM` | Provider-agnostic or cross-provider; name the provider in the body (Kimi / Anthropic / OpenAI / DeepSeek …). **Do not** create per-provider prefixes |\n| `Kosong` | Changes to the `kosong` LLM abstraction layer surfaced in the root CHANGELOG (the subpackage's own CHANGELOG uses provider prefixes) |\n| `Wire` | Wire protocol events, version |\n| `Auth` | OAuth, token refresh, `/login` |\n| `Config` | Config schema, env vars |\n| `Lib` | SDK-facing API changes |\n| `Build` | Nix / Rust / Python / packaging |\n\nWhen unsure, match an existing entry of the same kind. Prefer this list; if you genuinely need a new prefix, raise it with maintainers and update this table in the same PR so the convention stays single-sourced.\n\n**Ordering**: within each version, group bullets by prefix in the order of the table above. Order within a prefix is free — keep the development order.\n\n## Highlights\n\nStarting from the next release, add `**Highlights**: …` under each version header (1–3 items most users will notice); mirror it as `**亮点**：…` in Chinese. Skip on releases that are only internal or `Lib:`. Highlights summarize — every highlighted item still needs its full bullet below. **Do not backfill historical versions.**\n\n\n---\nname: gen-docs\ndescription: Update Kimi Code CLI user documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n我们现在对代码库有了一些修改，请你参考最近的 git commit、staged changes、changelog.md 等的内容，根据 AGENTS.md 中的信息，必要时找到实际的代码全文，确保理解了所有变更对产品用户体验的真实改变，然后逐页、逐段地检查和更新文档内容。\n\n你应该首先确保英文 changelog 使用 `node docs/scripts/sync-changelog.mjs` 进行了同步，然后确保中文文档符合最新代码的行为，最后，使用 translate-docs skill 进行双语同步。\n\n\n---\nname: gen-rust\ndescription: Sync Rust implementation with Python changes (exclude UI/login) by reviewing recent changes, mapping modules, porting logic, and updating tests.\n---\n\n# gen-rust\n\nUse this skill when the user wants Rust (kagent/kosong/kaos) to stay logically identical to Python (kimi_cli/kosong/kaos), excluding UI and login/auth. This includes code and tests: Rust behavior and tests must be fully synchronized with Python changes.\n\nNote: The Rust binary is named `kagent`. User-facing CLI/output text in Rust must use `kagent`\ninstead of `kimi` to match the Rust command name.\n\n## Quick workflow\n\n1) **Build a complete change inventory**\n\nReview recent changes to understand what needs syncing:\n\n```sh\n# Check staged changes\ngit diff --cached --name-only\ngit diff --cached -- src packages\n\n# Check recent commits\ngit log --oneline -20 -- src packages\ngit diff HEAD~20..HEAD -- src packages\n\n# Review CHANGELOG.md for context\nhead -50 CHANGELOG.md\n```\n\n2) **Classify changes**\n\n- Exclude UI and login/auth changes (Shell/Print/ACP UI, login/logout commands).\n- Everything else must be mirrored in Rust.\n- Keep a small checklist: file -> change summary -> Rust target -> status.\n\n3) **Map Python -> Rust**\n\nCommon mappings:\n- `src/kimi_cli/llm.py` -> `rust/kagent/src/llm.rs`\n- `src/kimi_cli/soul/*` -> `rust/kagent/src/soul/*`\n- `src/kimi_cli/tools/*` -> `rust/kagent/src/tools/*`\n- `src/kimi_cli/utils/*` -> `rust/kagent/src/utils/*`\n- `src/kimi_cli/wire/*` -> `rust/kagent/src/wire/*`\n- `packages/kosong/*` -> `rust/kosong/*`\n- `packages/kaos/*` -> `rust/kaos/*`\n\n4) **Port logic carefully**\n\n- Match error messages and tool output text exactly (tests often assert strings).\n- Preserve output types (text vs parts) and ordering.\n- For media/tool outputs, verify ContentPart wrapping and serialization.\n- If Python adds new helper modules, mirror minimal Rust utilities.\n- Use `rg` to find existing analogs and references.\n\n5) **Update tests**\n\n- Update Rust tests that assert content/strings/parts.\n- Mirror Python unit and integration tests when they exist; add missing Rust tests so coverage matches intent.\n- Ensure E2E parity: use the existing Python E2E suite against the Rust binary by setting\n `KIMI_E2E_WIRE_CMD` (do not rewrite E2E in Rust). All E2E cases must pass or the gap must be documented.\n- Prefer targeted tests first (`cargo test -p kagent --test `), then full suite if asked.\n\n6) **Verification is mandatory**\n\n- Run the full Rust test suite and ensure all Rust tests pass.\n- Run E2E tests with the wire command swapped to Rust (set `KIMI_E2E_WIRE_CMD`), and ensure they pass.\n\n7) **Final report**\n\n- List synced files and logic.\n- Call out intentionally skipped UI/login changes.\n- List tests run and results (must include full Rust tests and Rust E2E with wire command override).\n\n## Pitfalls to avoid\n\n- Skipping `llm.py`: it often changes model capability logic.\n- Using commit message filtering instead of full diff.\n- Forgetting to update Rust tests when output text/parts change.\n- Mixing UI/login changes into core sync.\n- Leaving test parity ambiguous; always state unit/integration/E2E status.\n\n## Minimal diff checklist (template)\n\n- [ ] Recent changes reviewed (staged, commits, changelog)\n- [ ] Python diffs inspected for core logic\n- [ ] Rust mappings applied\n- [ ] Tests updated\n- [ ] Targeted tests run\n- [ ] Full Rust test suite passed\n- [ ] Rust E2E passed with `KIMI_E2E_WIRE_CMD`\n\n\n---\nname: pull-request\ndescription: Create and submit a GitHub Pull Request.\ntype: flow\n---\n\n```mermaid\nflowchart TB\n A([\"BEGIN\"]) --> B[\"当前分支有没有 dirty change？\"]\n B -- 有 --> D([\"END\"])\n B -- 没有 --> n1[\"确保当前分支是一个不同于 main 的独立分支\"]\n n1 --> n2[\"根据当前分支相对于 main 分支的修改，push 并提交一个 PR（利用 gh 命令），用英文编写 PR 标题和 description，描述所做的更改。PR title 要符合先前的 commit message 规范（PR title 就是 squash merge 之后的 commit message）。\"]\n n2 --> D\n```\n\n\n---\nname: release\ndescription: Execute the release workflow for Kimi Code CLI packages.\n---\n\nRelease process for Kimi Code CLI packages. Tags are pushed without a `v` prefix and follow one of these patterns (matched by `.github/workflows/release-*.yml`):\n\n| Tag pattern | Releases |\n|---|---|\n| `1.42.0` (numeric) | `kimi-cli` (root) + `kimi-code` wrapper, released together — versions must stay aligned |\n| `kosong-0.53.0` | `packages/kosong` |\n| `pykaos-0.9.0` | `packages/kaos` (PyPI name `pykaos`) |\n| `kimi-sdk-0.3.0` | `sdks/kimi-sdk` |\n\nThe Rust implementation (`kagent`) lives in a separate repository and is **not** released from here.\n\n## Steps\n\n1. **Understand the automation.** Read `AGENTS.md` and `.github/workflows/release*.yml` so you know what each release workflow expects before changing any versions.\n\n2. **Detect changed packages.** Check each release unit under `packages/`, `sdks/`, and the repo root for changes since its last release tag. Use path-scoped diffs for subpackages so unrelated repo changes do not trigger a package release, e.g. `git diff kosong-0.53.0..HEAD -- packages/kosong`, `git diff pykaos-0.9.0..HEAD -- packages/kaos`, and `git diff kimi-sdk-0.2.1..HEAD -- sdks/kimi-sdk`. If nothing changed anywhere, stop and report that there is nothing to release. Note: `packages/kimi-code` is a thin wrapper and must stay version-synced with `kimi-cli`, so treat it as changed whenever the root package changes.\n\n3. **Confirm new versions with the user.** For each changed package, propose a new version and confirm before editing. Versioning policy:\n - Patch is always `0`.\n - Bump the minor version for any change.\n - Major only changes by explicit manual decision from the user.\n\n4. **Create the release branch.** Name it `bump--`. If multiple packages are being bumped together, use a single branch with a descriptive name.\n\n5. **Update version metadata and changelogs.** For each changed package:\n - Update its `pyproject.toml`.\n - Update `CHANGELOG.md`, keeping the `## Unreleased` header empty in place (do **not** rename it — add a new dated `## (YYYY-MM-DD)` section below it).\n - Update `breaking-changes.md` in both languages if there are breaking changes.\n - If bumping `packages/kosong` or `packages/kaos`, also update the root `pyproject.toml` pinned dependency (`kosong[contrib]==` or `pykaos==`) so root validation keeps passing.\n\n6. **Sync the `kimi-code` wrapper when the root version changes.** Bump `packages/kimi-code/pyproject.toml` `version` to match the new root version. It is a legacy stub with no dependencies — do not add a `kimi-cli` pin back.\n\n7. **Run `uv sync`** to refresh the lockfile.\n\n8. **Update docs.** Follow the `gen-docs` skill to make sure docs reflect the release.\n\n9. **Confirm with the user before opening the PR.** Summarize the staged changes and ask the user to explicitly confirm:\n - **Version numbers** — every updated `pyproject.toml` (changed package + `packages/kimi-code` if the root moved) reflects the version agreed in step 3.\n - **Dependency pins** — the root `pyproject.toml` pins (`kosong[contrib]==`, `pykaos==`) match the bumped versions.\n - **Documentation** — CHANGELOG entries are added below `## Unreleased` (Unreleased still present and empty), `breaking-changes.md` is updated in both languages if applicable, and `gen-docs` left no inconsistencies.\n\n Wait for explicit user approval before proceeding. If the user flags anything, fix it and re-confirm — do not push.\n\n10. **Open the PR.** Commit all changes, push, and open a PR with `gh`. The PR description must follow this structure (see https://github.com/MoonshotAI/kimi-cli/pull/2225 for reference):\n\n ```markdown\n ## Summary\n - Bump to \n - Move the current release notes under \n - (If applicable) Move breaking-change entries under \n - (If applicable) Any additional noteworthy changes (dependency pin updates, etc.)\n\n ## Validation\n - uv run python scripts/check_version_tag.py --pyproject --expected-version \n - (For root releases) uv run python scripts/check_version_tag.py --pyproject packages/kimi-code/pyproject.toml --expected-version \n - uv run python scripts/check_kimi_dependency_versions.py --root-pyproject pyproject.toml --kosong-pyproject packages/kosong/pyproject.toml --pykaos-pyproject packages/kaos/pyproject.toml\n - make check\n\n ## Post-merge\n After this PR lands, create and push the release tag:\n\n ```sh\n git tag \n git push origin \n ```\n ```\n\n11. **Hand off the tag step.** After merge, switch to `main`, pull latest, and tell the user the exact `git tag` command for the final release tag (pick the right tag pattern from the table above — e.g. `git tag 1.43.0` for a root release, `git tag kosong-0.54.0` for a kosong release). The user will run the tag and push tags themselves.\n\n## Stop conditions\n\nFail fast — never paper over an error to keep the release moving. Stop and report back to the user when any of these happen:\n\n- Nothing changed since the last tag → there is nothing to release.\n- `uv sync` fails or produces unexpected `uv.lock` churn beyond the version bump.\n- `gen-docs` reports a doc inconsistency you cannot resolve.\n- PR checks go red after push — investigate, do **not** `--no-verify` or force-merge.\n- The release workflow fails after tag push — read the workflow logs and surface the failure, do not retag silently.\n\n\n---\nname: translate-docs\ndescription: Translate and sync bilingual documentation.\n---\n\n现在我们正在为当前项目 Kimi Code CLI 编写和维护用户文档，文档内容在 docs 目录下，docs/AGENTS.md 中有对文档的说明。\n\n中文文档和英文 changelog 已经确保是正确符合预期的，现在请你逐页、逐段地翻译文档内容，确保中英双语保持同步。\n\n## 翻译方向\n\n- **Changelog**: 以英文为准，翻译到中文\n- **其他所有页面**: 以中文为准，翻译到英文\n\n## 注意事项\n\n- 必要时可以参考代码文件以确保翻译的准确性\n- 要保证不同语言的表达风格、结构标记等保持一致\n- 但需要遵守两者可能不同的用词和排版偏好（主要是 sentence case、翻译对照之类的）\n\n\n---\nname: worktree-status\ndescription: Audit all git worktrees in the current project. Use when the user asks about worktree status, which branches are merged, which have uncommitted changes, or which worktrees can be safely cleaned up.\n---\n\n# worktree-status\n\nReport the status of every git worktree for the current project, covering\ndirty state and merge status.\n\n## When to use\n\n- User asks \"which worktrees can I clean up?\"\n- User asks \"what's the status of my worktrees / branches?\"\n- Before batch-cleaning worktrees, to avoid losing uncommitted work\n\n## Procedure\n\n### 1. Pull latest main (MANDATORY)\n\nYou MUST pull latest main before any status checks. Without this, merge\ndetection (both ancestry and content diff) will produce stale results and\nyou may mistakenly conclude a branch is not merged.\n\n```bash\ncd \"$(git rev-parse --show-toplevel)\" && git pull origin main\n```\n\n### 2. Collect worktree info\n\n```bash\nPROJECT_DIR=\"$(git rev-parse --show-toplevel)\"\n\nfor wt in $(git worktree list --porcelain | grep \"^worktree \" | sed 's/^worktree //' | grep -v \"$PROJECT_DIR$\"); do\n branch=$(git -C \"$wt\" branch --show-current 2>/dev/null)\n [ -z \"$branch\" ] && branch=\"(detached)\"\n name=$(basename \"$wt\")\n\n # dirty?\n if [ -z \"$(git -C \"$wt\" status --short 2>/dev/null)\" ]; then\n dirty=\"clean\"\n else\n dirty=\"DIRTY\"\n fi\n\n # merged into origin/main?\n # NOTE: This project uses squash merges exclusively. `git merge-base\n # --is-ancestor` does NOT detect squash-merged branches. Always follow\n # up with a content diff (step 3) for branches that appear \"not merged\".\n if [ \"$branch\" != \"(detached)\" ]; then\n if git merge-base --is-ancestor \"$branch\" origin/main 2>/dev/null; then\n merged=\"merged\"\n else\n merged=\"not merged (verify with content diff)\"\n fi\n else\n merged=\"n/a\"\n fi\n\n echo \"\"\n echo \"[$name] branch=$branch $dirty $merged\"\n if [ \"$dirty\" = \"DIRTY\" ]; then\n git -C \"$wt\" status --short 2>/dev/null | sed 's/^/ /'\n fi\ndone\n```\n\n### 3. Detect squash-merged branches (content diff)\n\nFor any branch that shows \"not merged\", check whether the branch's\nchanges are already in main. The correct method is:\n\n1. Find the files the branch actually changed (relative to merge-base).\n2. For each changed file, compare the branch version with main.\n If all files are identical, the branch was squash-merged.\n\n**⚠️ Do NOT use `git diff origin/main `** — that compares the\ntwo tips directly, so commits added to main *after* the branch diverged\nwill show up as false differences.\n\n```bash\nBRANCH=\"\"\nBASE=$(git merge-base origin/main \"$BRANCH\")\n\n# List files the branch touched\nFILES=$(git diff --name-only \"$BASE\" \"$BRANCH\")\n\n# Compare each file between branch and current main\nfor f in $FILES; do\n d=$(git diff \"$BRANCH\" origin/main -- \"$f\" | wc -l)\n if [ \"$d\" != \"0\" ]; then\n echo \"❌ $f — differs\"\n else\n echo \"✅ $f — identical in main\"\n fi\ndone\n# All ✅ = squash-merged\n```\n\n### 4. (Optional) Check for associated tmux sessions\n\nOnly run this if `tmux` is available and relevant (e.g. worktrees were\ncreated by codex-worker or similar tooling). Skip if not applicable.\n\n```bash\ntmux ls 2>/dev/null | grep -E 'codex-worker|' || true\n```\n\n### 5. Present results\n\n**Always present results as a Markdown table.** Every worktree must appear\nas a row. Never use abbreviated or prose-only summaries.\n\n| Worktree | Branch | Dirty | Merged | Can clean? |\n|---|---|---|---|---|\n| `example-wt` | `feat-foo` | ✅ clean | ✅ squash-merged | ✅ |\n| `another-wt` | `fix-bar` | ⚠️ 3 files | ❌ not merged | ❌ dirty + not merged |\n| `detached-wt` | (detached) | ⚠️ 14 files | n/a | ❌ has uncommitted changes |\n\nColumn definitions:\n\n- **Dirty**: `✅ clean` or `⚠️ N files`\n- **Merged**: `✅ merged` / `✅ squash-merged` (confirmed via content diff) / `❌ not merged` / `n/a`\n- **Can clean?**: `✅` only when merged (or squash-merged) AND clean\n\nAdd extra columns (e.g. tmux session, notes) only when relevant.\n\n### 6. Cleanup (only when asked)\n\nOnly clean worktrees the user explicitly approves. For each:\n\n```bash\nNAME=\"\"\ngit worktree remove \"/path/to/$NAME\"\ngit branch -D \"\" # only if the branch is no longer needed\n```\n\n\n---\nname: sample-plugin\ndescription: |\n Sample plugin demonstrating the Skills + Tools model.\n Includes a Python tool (greeting) and a TypeScript tool (calculator).\n---\n\n# Sample Plugin\n\nA demo plugin with two tools in different languages, showing that plugin tools are language-agnostic.\n\n## Tools\n\n| Tool | Language | Description |\n|------|----------|-------------|\n| `py_greet` | Python | Generate a greeting in en/zh/ja |\n| `ts_calc` | TypeScript | Evaluate a math expression |\n\n## Usage\n\n- \"greet Alice in Chinese\" -> use `py_greet` with name=\"Alice\", lang=\"zh\"\n- \"what is 42 * 17 + 3\" -> use `ts_calc` with expression=\"42 * 17 + 3\"\n\n\n---\nname: kimi-cli-help\ndescription: Answer Kimi Code CLI usage, configuration, and troubleshooting questions. Use when user asks about Kimi Code CLI installation, setup, configuration, slash commands, keyboard shortcuts, MCP integration, providers, environment variables, how something works internally, or any questions about Kimi Code CLI itself.\n---\n\n# Kimi Code CLI Help\n\nHelp users with Kimi Code CLI questions by consulting documentation and source code.\n\n## Strategy\n\n1. **Prefer official documentation** for most questions\n2. **Read local source** when in kimi-cli project itself, or when user is developing with kimi-cli as a library (e.g., importing from `kimi_cli` in their code)\n3. **Clone and explore source** for complex internals not covered in docs - **ask user for confirmation first**\n\n## Documentation\n\nBase URL: `https://moonshotai.github.io/kimi-cli/`\n\nFetch documentation index to find relevant pages:\n\n```\nhttps://moonshotai.github.io/kimi-cli/llms.txt\n```\n\n### Page URL Pattern\n\n- English: `https://moonshotai.github.io/kimi-cli/en/...`\n- Chinese: `https://moonshotai.github.io/kimi-cli/zh/...`\n\n### Topic Mapping\n\n| Topic | Page |\n|-------|------|\n| Installation, first run | `/en/guides/getting-started.md` |\n| Config files | `/en/configuration/config-files.md` |\n| Providers, models | `/en/configuration/providers.md` |\n| Environment variables | `/en/configuration/env-vars.md` |\n| Slash commands | `/en/reference/slash-commands.md` |\n| CLI flags | `/en/reference/kimi-command.md` |\n| Keyboard shortcuts | `/en/reference/keyboard.md` |\n| MCP | `/en/customization/mcp.md` |\n| Agents | `/en/customization/agents.md` |\n| Skills | `/en/customization/skills.md` |\n| FAQ | `/en/faq.md` |\n\n## Source Code\n\nRepository: `https://github.com/MoonshotAI/kimi-cli`\n\nWhen to read source:\n\n- In kimi-cli project directory (check `pyproject.toml` for `name = \"kimi-cli\"`)\n- User is importing `kimi_cli` as a library in their project\n- Question about internals not covered in docs (ask user before cloning)\n\n\n---\nname: skill-creator\ndescription: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Kimi's capabilities with specialized knowledge, workflows, or tool integrations.\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Kimi's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Kimi from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n## Core Principles\n\n### Concise is Key\n\nThe context window is a public good. Skills share the context window with everything else Kimi needs: system prompt, conversation history, other Skills' metadata, and the actual user request.\n\n**Default assumption: Kimi is already very smart.** Only add context Kimi doesn't already have. Challenge each piece of information: \"Does Kimi really need this explanation?\" and \"Does this paragraph justify its token cost?\"\n\nPrefer concise examples over verbose explanations.\n\n### Set Appropriate Degrees of Freedom\n\nMatch the level of specificity to the task's fragility and variability:\n\n**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.\n\n**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.\n\n**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.\n\nThink of Kimi as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│ ├── YAML frontmatter metadata (required)\n│ │ ├── name: (required)\n│ │ └── description: (required)\n│ └── Markdown instructions (required)\n└── Bundled Resources (optional)\n ├── scripts/ - Executable code (Python/Bash/etc.)\n ├── references/ - Documentation intended to be loaded into context as needed\n └── assets/ - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\nEvery SKILL.md consists of:\n\n- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Kimi reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.\n- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Kimi for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Kimi's process and thinking.\n\n- **When to include**: For documentation that Kimi should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Kimi determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Kimi produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Kimi to use files without loading them into context\n\n#### What to Not Include in a Skill\n\nA skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:\n\n- README.md\n- INSTALLATION_GUIDE.md\n- QUICK_REFERENCE.md\n- CHANGELOG.md\n- etc.\n\nThe skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Kimi (Unlimited because scripts can be executed without reading into context window)\n\n#### Progressive Disclosure Patterns\n\nKeep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.\n\n**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.\n\n**Pattern 1: High-level guide with references**\n\n```markdown\n# PDF Processing\n\n## Quick start\n\nExtract text with pdfplumber:\n[code example]\n\n## Advanced features\n\n- **Form filling**: See [FORMS.md](FORMS.md) for complete guide\n- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods\n- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns\n```\n\nKimi loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.\n\n**Pattern 2: Domain-specific organization**\n\nFor Skills with multiple domains, organize content by domain to avoid loading irrelevant context:\n\n```\nbigquery-skill/\n├── SKILL.md (overview and navigation)\n└── reference/\n ├── finance.md (revenue, billing metrics)\n ├── sales.md (opportunities, pipeline)\n ├── product.md (API usage, features)\n └── marketing.md (campaigns, attribution)\n```\n\nWhen a user asks about sales metrics, Kimi only reads sales.md.\n\nSimilarly, for skills supporting multiple frameworks or variants, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + provider selection)\n└── references/\n ├── aws.md (AWS deployment patterns)\n ├── gcp.md (GCP deployment patterns)\n └── azure.md (Azure deployment patterns)\n```\n\nWhen the user chooses AWS, Kimi only reads aws.md.\n\n**Pattern 3: Conditional details**\n\nShow basic content, link to advanced content:\n\n```markdown\n# DOCX Processing\n\n## Creating documents\n\nUse docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).\n\n## Editing documents\n\nFor simple edits, modify the XML directly.\n\n**For tracked changes**: See [REDLINING.md](REDLINING.md)\n**For OOXML details**: See [OOXML.md](OOXML.md)\n```\n\nKimi reads REDLINING.md or OOXML.md only when the user needs those features.\n\n**Important guidelines:**\n\n- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.\n- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Kimi can see the full scope when previewing.\n\n## Skill Locations and Discovery\n\nKimi Code CLI loads skills in layers (built-in -> user -> project). Within each layer, it uses the\nfirst existing directory in priority order. Built-in skills only load for LocalKaos or ACPKaos.\n\n**User level** (by priority):\n- `~/.config/agents/skills/` (recommended)\n- `~/.kimi/skills/`\n- `~/.claude/skills/`\n\n**Project level**:\n- `.agents/skills/`\n\n`--skills-dir` overrides discovery and loads only that directory (built-ins still load when\nsupported).\n\n## Skill Creation Process\n\nSkill creation involves these steps:\n\n1. Understand the skill with concrete examples\n2. Plan reusable skill contents (scripts, references, assets)\n3. Initialize the skill (run init_skill.py)\n4. Edit the skill (implement resources and write SKILL.md)\n5. Package the skill (run package_skill.py)\n6. Iterate based on real usage\n\nFollow these steps in order, skipping only if there is a clear reason why they are not applicable.\n\n### Skill Naming\n\n- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., \"Plan Mode\" -> `plan-mode`).\n- When generating names, generate a name under 64 characters (letters, digits, hyphens).\n- Prefer short, verb-led phrases that describe the action.\n- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).\n- Name the skill folder exactly after the skill name.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, create a new skill directory with a required `SKILL.md`\nfile and any optional resource directories that the skill needs (`scripts/`, `references/`,\n`assets/`). Create only the directories you intend to populate.\n\nAfter initialization, customize the SKILL.md and add resources as needed.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Kimi to use. Include information that would be beneficial and non-obvious to Kimi. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Kimi instance execute these tasks more effectively.\n\n#### Learn Proven Design Patterns\n\nCapture proven design patterns directly in this SKILL.md:\n\n- **Multi-step processes**: Clearly describe sequential workflows and conditional branches, including triggers, decision points, and expected outputs at each step.\n- **Specific output formats or quality standards**: Document required output shapes, templates, and examples directly in this SKILL.md so they are easy to follow.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAdded scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.\n\nDelete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.\n\n#### Update SKILL.md\n\n**Writing Guidelines:** Always use imperative/infinitive form.\n\n##### Frontmatter\n\nWrite the YAML frontmatter with `name` and `description`:\n\n- `name`: The skill name\n- `description`: This is the primary triggering mechanism for your skill, and helps Kimi understand when to use the skill.\n - Include both what the Skill does and specific triggers/contexts for when to use it.\n - Include all \"when to use\" information here - Not in the body. The body is only loaded after triggering, so \"When to Use This Skill\" sections in the body are not helpful to Kimi.\n - Example description for a `docx` skill: \"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Kimi needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks\"\n\nDo not include any other fields in YAML frontmatter.\n\n##### Body\n\nWrite instructions for using the skill and its bundled resources.\n\n### Step 5: Packaging a Skill\n\nOnce development of the skill is complete, package it into a distributable `.skill` file (a zip\narchive). Before packaging, validate that the skill meets all requirements:\n\n1. **Validate** the skill, checking:\n\n - YAML frontmatter format and required fields\n - Skill naming conventions and directory structure\n - Description completeness and quality\n - File organization and resource references\n\n2. **Package** the skill if validation passes:\n\n - Create an archive of the skill's root folder (the folder containing `SKILL.md` and all related files).\n - Ensure the archive preserves the internal directory structure.\n - Name the archive `.skill` (for example, `my-skill.skill`). The `.skill` file is a zip file with a `.skill` extension.\n\nExample packaging command:\n\n```bash\ncd \nzip -r my-skill.skill my-skill\n```\n\nIf validation fails (for example, due to malformed frontmatter, missing files, or an incomplete\ndescription), fix the issues and repackage the skill.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n\n\n# Kimi Code CLI Tools\n\n## Guidelines\n\n- Tools should not refer to types in `kimi_cli/wire/` unless they are explicitly implementing a UI / runtime bridge. When importing things like `ToolReturnValue` or `DisplayBlock`, prefer `kosong.tooling`.\n\n\nYou are Kimi Code CLI, an interactive general AI agent running on a user's computer.\n\nYour primary goal is to help users with software engineering tasks by taking action — use the tools available to you to make real changes on the user's system. You should also answer questions when asked. Always adhere strictly to the following system instructions and the user's requirements.\n\n${ROLE_ADDITIONAL}\n\n# Prompt and Tool Use\n\nThe user's messages may contain questions and/or task descriptions in natural language, code snippets, logs, file paths, or other forms of information. Read them, understand them and do what the user requested. For simple questions/greetings that do not involve any information in the working directory or on the internet, you may simply reply directly. For anything else, default to taking action with tools. When the request could be interpreted as either a question to answer or a task to complete, treat it as a task.\n\nWhen handling the user's request, if it involves creating, modifying, or running code or files, you MUST use the appropriate tools (e.g., `WriteFile`, `Shell`) to make actual changes — do not just describe the solution in text. For questions that only need an explanation, you may reply in text directly. When calling tools, do not provide explanations because the tool calls themselves should be self-explanatory. You MUST follow the description of each tool and its parameters when calling tools.\n\nIf the `Agent` tool is available, you can use it to delegate a focused subtask to a subagent instance. The tool can either start a new instance or resume an existing one by `agent_id`. Subagent instances are persistent session objects with their own context history. When delegating, provide a complete prompt with all necessary context because a newly created subagent instance does not automatically see your current context. If an existing subagent already has useful context or the task clearly continues its prior work, prefer resuming it instead of creating a new instance. Default to foreground subagents. Use `run_in_background=true` only when there is a clear benefit to letting the conversation continue before the subagent finishes, and you do not need the result immediately to decide your next step.\n\nYou have the capability to output any number of tool calls in a single response. If you anticipate making multiple non-interfering tool calls, you are HIGHLY RECOMMENDED to make them in parallel to significantly improve efficiency. This is very important to your performance.\n\nThe results of the tool calls will be returned to you in a tool message. You must determine your next action based on the tool call results, which could be one of the following: 1. Continue working on the task, 2. Inform the user that the task is completed or has failed, or 3. Ask the user for more information.\n\nThe system may insert information wrapped in `` tags within user or tool messages. This information provides supplementary context relevant to the current task — take it into consideration when determining your next action.\n\nTool results and user messages may also include `` tags. Unlike `` tags, these are **authoritative system directives** that you MUST follow. They bear no direct relation to the specific tool results or user messages in which they appear. Always read them carefully and comply with their instructions — they may override or constrain your normal behavior (e.g., restricting you to read-only actions during plan mode).\n\nIf the `Shell`, `TaskList`, `TaskOutput`, and `TaskStop` tools are available and you are the root agent, you can use Background Bash for long-running shell commands. Launch it via `Shell` with `run_in_background=true` and a short `description`. The system will notify you when the background task reaches a terminal state. Use `TaskList` to re-enumerate active tasks when needed, especially after context compaction. Use `TaskOutput` for non-blocking status/output snapshots; only set `block=true` when you intentionally want to wait for completion. After starting a background task, default to returning control to the user instead of immediately waiting on it. Use `TaskStop` only when you need to cancel the task. For human users in the interactive shell, the only task-management slash command is `/task`. Do not tell users to run `/task list`, `/task output`, `/task stop`, `/tasks`, or any other invented slash subcommands. If you are a subagent or these tools are not available, do not assume you can create or control background tasks.\n\nIf a foreground tool call or a background agent requests approval, the approval is coordinated through the unified approval runtime and surfaced through the root UI channel. Do not assume approvals are local to a single subagent turn.\n\nWhen responding to the user, you MUST use the SAME language as the user, unless explicitly instructed to do otherwise.\n\n# General Guidelines for Coding\n\nWhen building something from scratch, you should:\n\n- Understand the user's requirements.\n- Ask the user for clarification if there is anything unclear.\n- Design the architecture and make a plan for the implementation.\n- Write the code in a modular and maintainable way.\n\nAlways use tools to implement your code changes:\n\n- Use `WriteFile` to create or overwrite source files. Code that only appears in your text response is NOT saved to the file system and will not take effect.\n- Use `Shell` to run and test your code after writing it.\n- Iterate: if tests fail, read the error, fix the code with `WriteFile` or `StrReplaceFile`, and re-test with `Shell`.\n\nWhen working on an existing codebase, you should:\n\n- Understand the codebase by reading it with tools (`ReadFile`, `Glob`, `Grep`) before making changes. Identify the ultimate goal and the most important criteria to achieve the goal.\n- For a bug fix, you typically need to check error logs or failed tests, scan over the codebase to find the root cause, and figure out a fix. If user mentioned any failed tests, you should make sure they pass after the changes.\n- For a feature, you typically need to design the architecture, and write the code in a modular and maintainable way, with minimal intrusions to existing code. Add new tests if the project already has tests.\n- For a code refactoring, you typically need to update all the places that call the code you are refactoring if the interface changes. DO NOT change any existing logic especially in tests, focus only on fixing any errors caused by the interface changes.\n- Make MINIMAL changes to achieve the goal. This is very important to your performance.\n- Follow the coding style of existing code in the project.\n- For broader codebase exploration and deep research, use the `Agent` tool with `subagent_type=\"explore\"`. This is a fast, read-only agent specialized for searching and understanding codebases. Use it when your task will clearly require more than 3 search queries, or when you need to investigate multiple files and patterns. You can launch multiple explore agents concurrently to investigate independent questions in parallel.\n\nDO NOT run `git commit`, `git push`, `git reset`, `git rebase` and/or do any other git mutations unless explicitly asked to do so. Ask for confirmation each time when you need to do git mutations, even if the user has confirmed in earlier conversations.\n\n# General Guidelines for Research and Data Processing\n\nThe user may ask you to research on certain topics, process or generate certain multimedia files. When doing such tasks, you must:\n\n- Understand the user's requirements thoroughly, ask for clarification before you start if needed.\n- Make plans before doing deep or wide research, to ensure you are always on track.\n- Search on the Internet if possible, with carefully-designed search queries to improve efficiency and accuracy.\n- Use proper tools or shell commands or Python packages to process or generate images, videos, PDFs, docs, spreadsheets, presentations, or other multimedia files. Detect if there are already such tools in the environment. If you have to install third-party tools/packages, you MUST ensure that they are installed in a virtual/isolated environment.\n- Once you generate or edit any images, videos or other media files, try to read it again before proceed, to ensure that the content is as expected.\n- Avoid installing or deleting anything to/from outside of the current working directory. If you have to do so, ask the user for confirmation.\n\n# Working Environment\n\n## Operating System\n\nYou are running on **${KIMI_OS}**. The Shell tool executes commands using **${KIMI_SHELL}**.{% if KIMI_OS == \"Windows\" %} Use Unix shell syntax inside Shell commands — `/dev/null` not `NUL`, forward slashes in paths (backslashes are escape characters in bash).{% endif +%}\n\nThe operating environment is not in a sandbox. Any actions you do will immediately affect the user's system. So you MUST be extremely cautious. Unless being explicitly instructed to do so, you should never access (read/write/execute) files outside of the working directory.\n\n## Date and Time\n\nThe current date and time in ISO format is `${KIMI_NOW}`. This is only a reference for you when searching the web, or checking file modification time, etc. If you need the exact time, use Shell tool with proper command.\n\n## Working Directory\n\nThe current working directory is `${KIMI_WORK_DIR}`. This should be considered as the project root if you are instructed to perform tasks on the project. Every file system operation will be relative to the working directory if you do not explicitly specify the absolute path. Tools may require absolute paths for some parameters, IF SO, YOU MUST use absolute paths for these parameters.\n\nThe directory listing of current working directory is:\n\n```\n${KIMI_WORK_DIR_LS}\n```\n\nUse this as your basic understanding of the project structure. The tree only shows the first two levels; entries marked \"... and N more\" indicate additional contents — use Glob or Shell to explore further.\n{% if KIMI_ADDITIONAL_DIRS_INFO %}\n\n## Additional Directories\n\nThe following directories have been added to the workspace. You can read, write, search, and glob files in these directories as part of your workspace scope.\n\n${KIMI_ADDITIONAL_DIRS_INFO}\n{% endif %}\n\n# Project Information\n\nMarkdown files named `AGENTS.md` usually contain the background, structure, coding styles, user preferences and other relevant information about the project. You should use this information to understand the project and the user's preferences. `AGENTS.md` files may exist at different locations in the project, but typically there is one in the project root.\n\n> Why `AGENTS.md`?\n>\n> `README.md` files are for humans: quick starts, project descriptions, and contribution guidelines. `AGENTS.md` complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.\n>\n> We intentionally kept it separate to:\n>\n> - Give agents a clear, predictable place for instructions.\n> - Keep `README`s concise and focused on human contributors.\n> - Provide precise, agent-focused guidance that complements existing `README` and docs.\n\nThe `AGENTS.md` instructions (merged from all applicable directories):\n\n`````````\n${KIMI_AGENTS_MD}\n`````````\n\n`AGENTS.md` files can appear at any level of the project directory tree, including inside `.kimi/` directories. Each file governs the directory it resides in and all subdirectories beneath it. When multiple `AGENTS.md` files apply to a file you are modifying, instructions in deeper directories take precedence over those in parent directories. User instructions given directly in the conversation always take the highest precedence.\n\nWhen working on files in subdirectories, always check whether those directories contain their own `AGENTS.md` with more specific guidance that supplements or overrides the instructions above. You may also check `README`/`README.md` files for more information about the project.\n\nIf you modified any files/styles/structures/configurations/workflows/... mentioned in `AGENTS.md` files, you MUST update the corresponding `AGENTS.md` files to keep them up-to-date.\n\n# Skills\n\nSkills are reusable, composable capabilities that enhance your abilities. Each skill is a self-contained directory with a `SKILL.md` file that contains instructions, examples, and/or reference material.\n\n## What are skills?\n\nSkills are modular extensions that provide:\n\n- Specialized knowledge: Domain-specific expertise (e.g., PDF processing, data analysis)\n- Workflow patterns: Best practices for common tasks\n- Tool integrations: Pre-configured tool chains for specific operations\n- Reference material: Documentation, templates, and examples\n\n## Available skills\n\nSkills are grouped by scope (`Project`, `User`, `Extra`, `Built-in`) so you can tell where each came from. When the user refers to \"the skill in this project\" or \"the user-scope skill\", use the scope heading to disambiguate. When multiple scopes define a skill with the same name, the more specific scope takes precedence: **Project overrides User overrides Extra overrides Built-in**.\n\n${KIMI_SKILLS}\n\n## How to use skills\n\nIdentify the skills that are likely to be useful for the tasks you are currently working on, read the `SKILL.md` file for detailed instructions, guidelines, scripts and more.\n\nOnly read skill details when needed to conserve the context window.\n\n# Ultimate Reminders\n\nAt any time, you should be HELPFUL, CONCISE, and ACCURATE. Be thorough in your actions — test what you build, verify what you change — not in your explanations.\n\n- Never diverge from the requirements and the goals of the task you work on. Stay on track.\n- Never give the user more than what they want.\n- Try your best to avoid any hallucination. Do fact checking before providing any factual information.\n- Think about the best approach, then take action decisively.\n- Do not give up too early.\n- ALWAYS, keep it stupidly simple. Do not overcomplicate things.\n- When the task requires creating or modifying files, always use tools to do so. Never treat displaying code in your response as a substitute for actually writing it to the file system.\n\n\n# Example: Custom Tools\n\nThis example demonstrates how to write custom tools for Kimi Code CLI and add them to your agent spec file.\n\n```sh\ncd examples/custom-tools\nuv sync --reinstall\nuv run main.py\n```\n\n\n{\n \"name\": \"sample-plugin\",\n \"version\": \"1.0.0\",\n \"description\": \"Sample plugin demonstrating Skills + Tools with both Python and TypeScript tools\",\n \"tools\": [\n {\n \"name\": \"py_greet\",\n \"description\": \"Generate a greeting message (Python tool)\",\n \"command\": [\"python3\", \"scripts/greet.py\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"description\": \"Name to greet\"\n },\n \"lang\": {\n \"type\": \"string\",\n \"enum\": [\"en\", \"zh\", \"ja\"],\n \"description\": \"Language: en=English, zh=Chinese, ja=Japanese\"\n }\n },\n \"required\": [\"name\"]\n }\n },\n {\n \"name\": \"ts_calc\",\n \"description\": \"Evaluate a math expression and return the result (TypeScript tool)\",\n \"command\": [\"npx\", \"tsx\", \"scripts/calc.ts\"],\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"expression\": {\n \"type\": \"string\",\n \"description\": \"Math expression to evaluate, e.g. '2 + 3 * 4'\"\n }\n },\n \"required\": [\"expression\"]\n }\n }\n ]\n}\n\n\n# PyKAOS\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nPyKAOS is a lightweight Python library providing an abstraction layer for agents to interact with operating systems. File operations and command executions via KAOS can be easily switched between local environment and remote systems over SSH.\n\n\n# kimi-code (PyPI): legacy package, archived\n\n> [!CAUTION]\n> **This PyPI package is NOT the new Kimi Code CLI.** It is a legacy alias of the archived Python [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) and is no longer maintained.\n>\n> PyPI 上的 `kimi-code` 是已归档的旧版 Python Kimi CLI 的别名包，**不是**新版 Kimi Code CLI。\n\n## Install the new Kimi Code CLI\n\n```sh\n# macOS / Linux\ncurl -fsSL https://code.kimi.com/kimi-code/install.sh | bash\n```\n\n```powershell\n# Windows (PowerShell)\nirm https://code.kimi.com/kimi-code/install.ps1 | iex\n```\n\nAlso available via Homebrew (`brew install kimi-code`) and npm (`npm install -g @moonshot-ai/kimi-code`).\n\nThen uninstall this package: `uv tool uninstall kimi-code` (or `pip uninstall kimi-code kimi-cli`, since pip does not remove the legacy `kimi-cli` dependency automatically).\n\nMigration guide: [English](https://moonshotai.github.io/kimi-code/en/guides/migration) | [中文](https://moonshotai.github.io/kimi-code/zh/guides/migration)\n\n## Note for existing users\n\nStarting from 1.51.0, running `kimi-code` from this package only prints the instructions above. The legacy CLI it used to install is no longer supported and will stop working, so please migrate to Kimi Code CLI.\n\n\n# Kosong\n\n> [!CAUTION]\n> **Archived: no longer maintained.** This package was developed in the [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) monorepo, which has been archived. Published versions remain available on PyPI, but there will be no further releases, bug fixes, or security updates. The source code remains available under the Apache License 2.0.\n\nKosong is an LLM abstraction layer designed for modern AI agent applications. It unifies message structures, asynchronous tool orchestration, and pluggable chat providers so you can build agents with ease and avoid vendor lock-in.\n\n> Kosong means \"empty\" in Malay and Indonesian.\n\n## Installation\n\nKosong requires Python 3.12 or higher. We recommend using uv as the package manager.\n\nInit your project with:\n\n```bash\nuv init --python 3.12 # or higher\n```\n\nThen add Kosong as a dependency:\n\n```bash\nuv add kosong\n```\n\nTo enable chat providers other than Kimi (e.g. Anthropic and Google Gemini), install the optional extra:\n\n```bash\nuv add 'kosong[contrib]'\n```\n\n## Examples\n\n### Simple chat completion\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Streaming output\n\n```python\nimport asyncio\n\nimport kosong\nfrom kosong.chat_provider import StreamedMessagePart\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n history = [\n Message(role=\"user\", content=\"Who are you?\"),\n ]\n\n def output(message_part: StreamedMessagePart):\n print(message_part)\n\n result = await kosong.generate(\n chat_provider=kimi,\n system_prompt=\"You are a helpful assistant.\",\n tools=[],\n history=history,\n on_message_part=output,\n )\n print(result.message)\n print(result.usage)\n\n\nasyncio.run(main())\n```\n\n### Tool calling with `kosong.step`\n\n```python\nimport asyncio\n\nfrom pydantic import BaseModel\n\nimport kosong\nfrom kosong import StepResult\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\nfrom kosong.tooling import CallableTool2, ToolOk, ToolReturnValue\nfrom kosong.tooling.simple import SimpleToolset\n\n\nclass AddToolParams(BaseModel):\n a: int\n b: int\n\n\nclass AddTool(CallableTool2[AddToolParams]):\n name: str = \"add\"\n description: str = \"Add two integers.\"\n params: type[AddToolParams] = AddToolParams\n\n async def __call__(self, params: AddToolParams) -> ToolReturnValue:\n return ToolOk(output=str(params.a + params.b))\n\n\nasync def main() -> None:\n kimi = Kimi(\n base_url=\"https://api.moonshot.ai/v1\",\n api_key=\"your_kimi_api_key_here\",\n model=\"kimi-k2-turbo-preview\",\n )\n\n toolset = SimpleToolset()\n toolset += AddTool()\n\n history = [\n Message(role=\"user\", content=\"Please add 2 and 3 with the add tool.\"),\n ]\n\n result: StepResult = await kosong.step(\n chat_provider=kimi,\n system_prompt=\"You are a precise math tutor.\",\n toolset=toolset,\n history=history,\n )\n print(result.message)\n print(await result.tool_results())\n\n\nasyncio.run(main())\n```\n\n## Builtin Demo\n\nKosong comes with a builtin demo agent that you can run locally. To start the demo, run:\n\n```sh\nexport KIMI_BASE_URL=\"https://api.moonshot.ai/v1\"\nexport KIMI_API_KEY=\"your_kimi_api_key\"\n\nuv run python -m kosong kimi --with-bash\n```\n\n## Development\n\nTo set up a development environment, clone the repository and install the dependencies:\n\n```bash\ngit clone https://github.com/MoonshotAI/kosong.git\ncd kosong\nuv sync --all-extras\n\nmake check # run lint and type checks\nmake test # run tests\nmake format # format code\n```\n"}