mirror of
https://github.com/MoonshotAI/kimi-code.git
synced 2026-07-31 12:05:17 +00:00
feat: support plugin-contributed custom agents (#2365)
* feat: support plugin-contributed custom agents * fix: await plugin loading before agent catalog * fix: refresh plugin agents on v1 reload * test(agent-core-v2): add enabledSystemPrompts to the plugin service stub
This commit is contained in:
7Sageer
GitHub
parent
1896d1a13a
commit
fa2c5ce18b
33 changed files with 641 additions and 33 deletions
|
|
@ -45,7 +45,7 @@ Beyond the three built-in sub-agents, you can define your own agents as Markdown
|
|||
|
||||
### Agent Locations
|
||||
|
||||
Kimi Code CLI discovers agent files by scope; more specific scopes take higher priority: **Explicit (`--agent-file`) > Project > Extra > User > Built-in**. When two files define the same `name`, the higher-priority scope wins. Each directory is scanned recursively for `.md` files.
|
||||
Kimi Code CLI discovers agent files by scope; more specific scopes take higher priority: **Explicit (`--agent-file`) > Project > Extra > User > Plugin > Built-in**. When two files define the same `name`, the higher-priority scope wins. Each directory is scanned recursively for `.md` files.
|
||||
|
||||
**User level** (applies to all projects):
|
||||
- `$KIMI_CODE_HOME/agents/` (default: `~/.kimi-code/agents/`)
|
||||
|
|
@ -63,6 +63,8 @@ The Kimi-specific user agent directory moves with `KIMI_CODE_HOME`, while the ge
|
|||
extra_agent_dirs = ["~/team-agents", ".agents/team-agents"]
|
||||
```
|
||||
|
||||
**Plugin level**: directories declared in an enabled plugin's manifest `agents` field (when omitted, the `agents/` directory under the plugin root is picked up automatically); see [Plugin Agents](./plugins.md#plugin-agents). Plugin agents outrank only the built-in agents.
|
||||
|
||||
**Built-in agents** are distributed with the CLI and have the lowest priority. A directory-discovered file does not override a same-name built-in Agent unless its frontmatter declares `override: true`. A file loaded through `--agent-file` is treated as explicit launch intent, may override a same-name built-in Agent, outranks every directory scope, and applies to the current launch only. Separately, `$KIMI_CODE_HOME/SYSTEM.md` permanently overrides the default main agent's system prompt (it is not part of agent-file discovery); its precedence interactions are covered in the SYSTEM.md section below.
|
||||
|
||||
::: warning Trust model
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Plugins
|
||||
|
||||
Plugins package reusable Kimi Code CLI capabilities into installable units — they can add [Agent Skills](./skills.md), automatically load a specified Skill at session start, contribute system-prompt instructions, and declare MCP servers to provide real tool capabilities. They are ideal for sharing workflows with a team, connecting to external services, or installing extensions from the official marketplace.
|
||||
Plugins package reusable Kimi Code CLI capabilities into installable units — they can add [Agent Skills](./skills.md), custom [agents](./agents.md), automatically load a specified Skill at session start, contribute system-prompt instructions, and declare MCP servers to provide real tool capabilities. They are ideal for sharing workflows with a team, connecting to external services, or installing extensions from the official marketplace.
|
||||
|
||||
## Installation and Management
|
||||
|
||||
|
|
@ -162,6 +162,7 @@ Supported fields:
|
|||
| `version`, `description`, `keywords`, `author`, `homepage`, `license` | Display metadata |
|
||||
| `interface` | Fields shown in `/plugins`: `displayName`, `shortDescription`, `longDescription`, `developerName`, `websiteURL` |
|
||||
| `skills` | One or more `./` paths; must be within the plugin root directory. When omitted, the `SKILL.md` in the root directory is treated as a single Skill root |
|
||||
| `agents` | One or more `./` paths; must be within the plugin root directory and point to directories containing [agent files](./agents.md#custom-agents). When omitted, the `agents/` directory under the plugin root (if present) is picked up automatically |
|
||||
| `sessionStart.skill` | Loads the specified plugin Skill into the main Agent when a new or resumed session starts |
|
||||
| `skillInstructions` | Additional instructions appended whenever a Skill from this plugin is loaded |
|
||||
| `systemPrompt` | Inline instructions contributed to the agent's system prompt while the plugin is enabled |
|
||||
|
|
@ -271,6 +272,19 @@ my-plugin/
|
|||
|
||||
Regardless of how a Skill is loaded (`sessionStart.skill`, `/skill:<name>`, or automatic model invocation), `skillInstructions` appears alongside that plugin's Skill.
|
||||
|
||||
## Plugin Agents
|
||||
|
||||
A plugin can ship custom agents: declare one or more `./` directories in the manifest's `agents` field (or simply place an `agents/` directory under the plugin root). The agent files inside use the same format as [custom agents](./agents.md#custom-agents) and, while the plugin is enabled, are discovered automatically and can be delegated to as sub-agents by the main Agent.
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
kimi.plugin.json
|
||||
agents/
|
||||
reviewer.md
|
||||
```
|
||||
|
||||
Plugin agents rank below every other file source: on a name collision, user-level, extra, project-level, and `--agent-file` agents all win over the plugin-provided one, and replacing a built-in agent still requires an explicit `override: true` in the frontmatter. After installing, enabling, disabling, or removing a plugin, the agent list refreshes in a new session (or on `/reload`); on the v2 engine the live session also refreshes after `/plugins reload`.
|
||||
|
||||
## MCP Servers in Plugins
|
||||
|
||||
When a plugin needs real tool capabilities, it can declare `mcpServers` in its manifest, reusing the [MCP](./mcp.md) schema.
|
||||
|
|
|
|||
|
|
@ -45,7 +45,7 @@ Kimi Code CLI 内置三种子 Agent，开箱即用，分别面向不同任务形
|
|||
|
||||
### Agent 目录
|
||||
|
||||
Kimi Code CLI 按作用域发现 Agent 文件，作用域越具体，优先级越高：**显式（`--agent-file`）> 项目 > 额外 > 用户 > 内置**。两个文件定义了相同的 `name` 时，高优先级作用域胜出。每个目录都会递归扫描 `.md` 文件。
|
||||
Kimi Code CLI 按作用域发现 Agent 文件，作用域越具体，优先级越高：**显式（`--agent-file`）> 项目 > 额外 > 用户 > Plugin > 内置**。两个文件定义了相同的 `name` 时，高优先级作用域胜出。每个目录都会递归扫描 `.md` 文件。
|
||||
|
||||
**用户级**（对所有项目生效）：
|
||||
- `$KIMI_CODE_HOME/agents/`（默认：`~/.kimi-code/agents/`）
|
||||
|
|
@ -63,6 +63,8 @@ Kimi 专属的用户 Agent 目录随 `KIMI_CODE_HOME` 移动，通用的 `~/.age
|
|||
extra_agent_dirs = ["~/team-agents", ".agents/team-agents"]
|
||||
```
|
||||
|
||||
**Plugin 级**：已启用 plugin 在其 manifest 的 `agents` 字段中声明的目录（省略时自动采用 plugin 根下的 `agents/` 目录），见[插件 Agent](./plugins.md#插件-agent)。Plugin Agent 优先级仅高于内置 Agent。
|
||||
|
||||
**内置 Agent** 随 CLI 分发，优先级最低。目录中发现的文件不会仅凭同名覆盖内置 Agent；如确需替换，必须在 Frontmatter 中声明 `override: true`。通过 `--agent-file` 加载的文件视为显式启动意图，可以覆盖同名内置 Agent，优先级高于所有目录作用域，且仅对本次启动生效。另外，`$KIMI_CODE_HOME/SYSTEM.md` 可永久覆盖默认主 Agent 的系统提示词（它不参与 Agent 文件发现），其优先级交互见下文 SYSTEM.md 小节。
|
||||
|
||||
::: warning 信任模型
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Plugins
|
||||
|
||||
Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元——可以添加 [Agent Skills](./skills.md)、在会话启动时自动加载指定 Skill、提供系统提示词指令，也可以声明 MCP servers 来提供真实工具能力。适合把工作流共享给团队、连接外部服务，或从官方 marketplace 安装扩展。
|
||||
Plugins 把可复用的 Kimi Code CLI 能力打包成可安装单元——可以添加 [Agent Skills](./skills.md)、自定义 [Agent](./agents.md)、在会话启动时自动加载指定 Skill、提供系统提示词指令，也可以声明 MCP servers 来提供真实工具能力。适合把工作流共享给团队、连接外部服务，或从官方 marketplace 安装扩展。
|
||||
|
||||
## 安装与管理
|
||||
|
||||
|
|
@ -162,6 +162,7 @@ Plugin 是一个带 manifest 的目录或 zip 文件。Manifest 可以放在以
|
|||
| `version`、`description`、`keywords`、`author`、`homepage`、`license` | 展示元数据 |
|
||||
| `interface` | 在 `/plugins` 中展示的字段：`displayName`、`shortDescription`、`longDescription`、`developerName`、`websiteURL` |
|
||||
| `skills` | 一个或多个 `./` 路径，必须位于 plugin 根目录内。省略时根目录的 `SKILL.md` 被当作单个 Skill root |
|
||||
| `agents` | 一个或多个 `./` 路径，必须位于 plugin 根目录内，指向含有 [Agent 文件](./agents.md#自定义-agent)的目录。省略时根下的 `agents/` 目录（若存在）被自动采用 |
|
||||
| `sessionStart.skill` | 在新会话或恢复会话开始时，把指定 plugin Skill 加载到主 Agent |
|
||||
| `skillInstructions` | 每次加载此 plugin 的 Skill 时一并附带的额外说明 |
|
||||
| `systemPrompt` | plugin 启用期间提供给 Agent 系统提示词的内联指令 |
|
||||
|
|
@ -271,6 +272,19 @@ my-plugin/
|
|||
|
||||
无论 Skill 通过哪种方式加载（`sessionStart.skill`、`/skill:<name>` 或模型自动调用），`skillInstructions` 都会随该 plugin 的 Skill 一起出现。
|
||||
|
||||
## 插件 Agent
|
||||
|
||||
Plugin 可以携带自定义 Agent：在 manifest 的 `agents` 字段里声明一个或多个 `./` 目录（或直接在 plugin 根下放置 `agents/` 目录），其中的 Agent 文件与[自定义 Agent](./agents.md#自定义-agent) 格式相同，会在 plugin 启用期间作为子 Agent 被主 Agent 自动发现和委派。
|
||||
|
||||
```text
|
||||
my-plugin/
|
||||
kimi.plugin.json
|
||||
agents/
|
||||
reviewer.md
|
||||
```
|
||||
|
||||
Plugin Agent 的优先级低于其他文件来源：同名时用户级、额外目录、项目级和 `--agent-file` 的 Agent 都会覆盖 plugin 提供的版本；替换内置 Agent 同样需要在 frontmatter 里显式写 `override: true`。安装、启用、禁用或移除 plugin 后，Agent 列表在新会话（或 `/reload`）时刷新；v2 引擎的当前会话还会在 `/plugins reload` 后刷新。
|
||||
|
||||
## Plugin 中的 MCP servers
|
||||
|
||||
当 plugin 需要真实工具能力时，可以在 manifest 中声明 `mcpServers`，复用 [MCP](./mcp.md) 的 schema。
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue