kimi-code/docs/zh/customization/plugins.md

Plugins

Plugins 围绕 kimi.plugin.json manifest 打包可复用的 Kimi Code CLI 行为。一个 plugin 可以贡献 Skills、插件级 Skill 说明、声明式 session-start Skill、展示元数据，以及 MCP servers。多宿主仓库可以把同一份 Kimi manifest 放在 .kimi-plugin/plugin.json，避免占用仓库根目录。

安装 plugin 本身不会执行 plugin 提供的 Python、Node.js、Shell 或 hook 脚本。当前版本的 Kimi Code CLI 不运行命令型 plugin tools；真实工具应通过 plugin 声明的 MCP servers 暴露。

安装与管理 plugins

在 TUI 中运行 /plugins 会打开交互式 plugin 管理器。选择器会列出已安装的 plugins，并让你安装、查看、启用、禁用、移除、重载、浏览官方 marketplace，以及启用或禁用 plugin MCP servers。用 Enter 或 → 打开详情，用 Space 启用或禁用已安装 plugin，用 M 管理该 plugin 的 MCP servers，用 ← 或 Esc 返回。Marketplace 里 Enter 或 Space 会安装或更新当前选中的 plugin。

Kimi Code CLI 目前只支持 user/global（用户全局）plugin 安装。已安装 plugins 记录在 $KIMI_CODE_HOME/plugins/ 下，并对当前用户的所有项目可用。暂不支持项目本地、仓库共享、托管/管理员范围，以及带 --scope 的 plugin 安装。

快捷命令仍然可用于快速操作或脚本：

/plugins
/plugins list
/plugins install /absolute/path/to/plugin
/plugins install ./relative-plugin
/plugins install https://example.com/plugin.zip
/plugins marketplace
/plugins marketplace ./plugins/marketplace.json
/plugins info <id>
/plugins enable <id>
/plugins disable <id>
/plugins remove <id>
/plugins reload
/plugins mcp enable <id> <server>
/plugins mcp disable <id> <server>

当前可直接安装的示例包：

/plugins install https://kimi-1300010026.cos.ap-beijing.myqcloud.com/kimi-datasource.zip
/plugins install https://kimi-1300010026.cos.ap-beijing.myqcloud.com/superpowers-kimi-5.1.0-kimi.1.zip

官方 marketplace 默认从 https://cdn.kimi.com/kimi-code/plugins/marketplace.json 加载。在 /plugins 中选择 Browse official marketplace，即可查看 marketplace 条目并直接安装。CDN 可以托管整个 marketplace 目录，目录根部放 marketplace.json；相对 plugin source 会按这个文件所在目录解析。

要从当前仓库生成可上传到 CDN 的 marketplace 目录，运行：

pnpm run build:plugin-marketplace

这个命令会写出 plugins/cdn/marketplace.json，并在 plugins/cdn/ 下生成 plugin zip 包。上传时需要把整个目录作为一个整体上传，这样 marketplace.json 里的相对 source 才会继续指向生成好的 zip 文件。

需要测试预发 CDN 文件或其他 marketplace 时，可以覆盖 marketplace 来源：

KIMI_CODE_PLUGIN_MARKETPLACE_URL=https://staging.example.com/plugins/marketplace.json kimi

也可以不改环境变量，临时打开一个 marketplace 文件：

/plugins marketplace plugins/marketplace.json

CLI 开发时，pnpm dev:cli 会为仓库的 plugins/ 目录启动一个 loopback marketplace server，并只为这次 dev 进程临时设置 KIMI_CODE_PLUGIN_MARKETPLACE_URL=http://127.0.0.1:<port>/marketplace.json。这个 server 会把本地目录型 source 临时改成 zip URL，让 marketplace 安装走和 CDN 一样的下载路径。需要在 dev 中测试真实 CDN 时，运行 KIMI_CODE_PLUGIN_MARKETPLACE_URL=https://cdn.kimi.com/kimi-code/plugins/marketplace.json pnpm dev:cli；dev wrapper 会使用这个值，不再启动本地 marketplace server。

本地目录和 zip URL 都会复制到 Kimi Code CLI 管理的 plugin 目录 $KIMI_CODE_HOME/plugins/managed/<id>/。再次安装同一个 plugin id 会覆盖这份托管副本，并保留 plugin 的启用状态和 MCP server 开关。installed.json 记录这份托管副本，同时保留原始来源用于展示。移除 plugin 会先二次确认，确认后只删除安装记录，不会删除托管副本或原始本地源码目录。

Plugin 变更只对新会话生效。安装、启用、禁用、移除、重载 plugin，或修改 plugin MCP server 开关后，需要通过 /new 开启新会话，新的 Skills、sessionStart.skill 和 MCP servers 才会进入会话。已有会话继续使用启动时的快照。

重载操作会重新读取 installed.json 和每个 plugin manifest，让 /plugins 与 /plugins info <id> 展示最新安装状态和 diagnostics。它不会热更新当前会话里的 Skills 或 MCP 连接。因为本地路径安装实际运行的是托管副本，安装后继续修改原始源码目录不会影响已安装 plugin；需要重新安装才会更新。

Manifest 格式

Kimi Code CLI 把根目录 kimi.plugin.json 作为优先 plugin manifest：

<plugin_root>/kimi.plugin.json

如果没有 kimi.plugin.json，Kimi Code CLI 会读取 Kimi 专属 manifest：

<plugin_root>/.kimi-plugin/plugin.json

Kimi Code CLI 不读取根目录 plugin.json 或 .codex-plugin/plugin.json。如果同时存在 kimi.plugin.json 和 .kimi-plugin/plugin.json，根目录 kimi.plugin.json 胜出，.kimi-plugin manifest 会在 /plugins info 中显示为 shadowed。

一个典型的 plugin manifest 如下：

{
  "name": "kimi-finance",
  "version": "1.0.0",
  "description": "Finance data and analysis workflows for Kimi Code CLI",
  "keywords": ["finance", "mcp"],
  "skills": "./skills/",
  "sessionStart": {
    "skill": "using-finance"
  },
  "skillInstructions": "Prefer the finance MCP tools for live market data. Do not invent live prices.",
  "mcpServers": {
    "data": {
      "command": "node",
      "args": ["./bin/finance-mcp.mjs"],
      "cwd": "./"
    }
  },
  "interface": {
    "displayName": "Kimi Finance",
    "shortDescription": "Market data and financial analysis workflows"
  }
}

支持的字段：

字段	说明
name	必填，作为 plugin id 来源。必须匹配 [a-z0-9][a-z0-9_-]{0,63}。
version、description、keywords、author、homepage、license	展示元数据。
skills	一个路径或路径数组。每个路径必须以 ./ 开头，并且符号链接解析后仍位于 plugin 根目录内。
根目录 SKILL.md	如果省略 skills，且 plugin 根目录存在 SKILL.md，则根目录会作为单 Skill root 处理。
sessionStart.skill	声明式地在新会话或恢复会话开始时，把指定 Skill 注入到主 Agent。
skillInstructions	每次加载此 plugin 的 Skill 时，附加到 Skill 内容前面的额外说明。
mcpServers	MCP server 声明。Servers 默认启用，可以在 /plugins 中禁用，或使用 /plugins mcp disable <id> <server> 禁用。
interface	/plugins info 的展示字段，例如 displayName、shortDescription、longDescription、developerName 和 websiteURL。

tools、commands、configFile、config_file、inject、bootstrap、hooks、apps 等不支持的运行时字段只会产生 diagnostics 并被忽略。

Skills 与 session start

Plugin Skills 使用和普通 Agent Skills 相同的 SKILL.md 格式。常见目录布局如下：

my-plugin/
  kimi.plugin.json
  skills/
    using-my-plugin/
      SKILL.md
    another-workflow/
      SKILL.md

sessionStart.skill 是声明式会话启动规则：它会在会话开始时，把某个 Skill 一次性加载到主 Agent 上下文中。它不会执行代码。适合用于 plugin 需要在第一个用户任务前建立工作规则的场景，例如把另一个工具环境里的术语映射到 Kimi Code CLI 工具。

无论 Skill 是通过 sessionStart.skill、/skill:<name>，还是模型自动调用加载，skillInstructions 都会跟 Skill 内容放在一起。

Plugin 中的 MCP servers

Plugin MCP servers 复用 MCP 的 server schema。可以声明 stdio server：

{
  "mcpServers": {
    "finance": {
      "command": "uvx",
      "args": ["kimi-finance-mcp"]
    }
  }
}

也可以声明 HTTP server：

{
  "mcpServers": {
    "docs": {
      "url": "https://example.com/mcp"
    }
  }
}

对于 stdio server，command 可以是 PATH 上的命令，也可以是 plugin 根目录内以 ./ 开头的路径。如果省略 cwd，Kimi Code CLI 会从托管 plugin 根目录启动 server。如果设置 cwd，它必须以 ./ 开头，并且位于 plugin 根目录内。Plugin MCP servers 会继承当前进程环境变量；写在 env 里的值是字面量覆盖，不是 ${VAR} 插值。

Plugin MCP servers 默认启用，但仍然只会在新会话中启动。要交互式禁用或重新启用，运行 /plugins，选中 plugin，然后按 M 管理它的 servers。也可以使用快捷命令：

/plugins mcp disable kimi-finance finance
/new

/plugins mcp enable kimi-finance finance
/new

启用状态保存在 $KIMI_CODE_HOME/plugins/installed.json。新会话启动后，已启用的 plugin MCP servers 会进入普通 MCP 生命周期，包括状态事件、工具命名和权限审批流程。

安全模型

Plugins 会被保守加载：

• 安装和会话启动时，只读取 kimi.plugin.json、.kimi-plugin/plugin.json 与 Markdown Skill 文件。
• 命令型 plugin tools、hooks 和旧式工具运行时不会由 plugin loader 执行。
• Plugin 路径在解析符号链接后必须仍位于 plugin 根目录内。
• 已启用 plugin 声明的 MCP servers 默认启用，但只会在新会话中启动，并且可以在 /plugins 中禁用，或使用 /plugins mcp disable 禁用。
• 损坏的 manifest 或不安全路径会变成 /plugins info <id> 中的 diagnostics，不会让无关会话崩溃。