# 插件与市场

> 清单格式与路径逃逸检查、未支持字段的诊断、插件能带来的七类东西、tier 与三级信任标签、GitHub 直装。

- 作者：David（道雾轩）
- 专栏：Kimi Code 源码解读（https://daiw.org/manual/kimi-code.md）
- 最后更新：2026-09-19
- 原文：https://daiw.org/manual/kimi-code/plugins
- 转载与引用：请注明出处并附原文链接（https://daiw.org/about/copyright）

插件是把 [skills](https://daiw.org/manual/kimi-code/skills)、[MCP 服务器](https://daiw.org/manual/kimi-code/mcp)、[hooks](https://daiw.org/manual/kimi-code/hooks)、命令等打包分发的容器。v0.29 时代实现在 `packages/agent-core/src/plugin/`；现在搬到 `packages/agent-core-v2/src/app/plugin/`，作为 App 作用域的 `IPluginService` 全进程共享。文件拆分基本沿用（`manifest.ts`、`manager.ts`、`source.ts`、`github-resolver.ts`、`archive.ts`、`store.ts`、`commands.ts`），另加了 `marketplace.ts` 与服务层。

## 清单

`app/plugin/manifest.ts:16`：

```ts
const KIMI_PLUGIN_ROOT_PATH = 'kimi.plugin.json';
const KIMI_PLUGIN_DIR_PATH = '.kimi-plugin/plugin.json';
```

两个位置任选：仓库根的 `kimi.plugin.json`，或 `.kimi-plugin/plugin.json`（不想污染根目录时用）。两个都在时根目录的生效，另一个记为 `shadowedManifestPath` 供诊断。

清单复用了配置层的 schema（`manifest.ts:4`）：

```ts
import { HookDefSchema, type HookDefConfig } from '#/features/externalHooks/configSection';
import { McpServerConfigSchema, type McpServerConfig } from '#/mcpCore/config-schema';
```

**插件能声明的 hook 与 MCP 服务器 = 用户能在配置里写的**，共用同一套 zod schema，保证「插件装上」与「用户手写配置」行为一致。官方插件 `kimi-datasource` 的清单核心就是一个 stdio MCP 服务器（节选）：

```json
{
  "name": "kimi-datasource",
  "version": "3.4.0",
  "mcpServers": {
    "data": {
      "command": "node",
      "args": ["./bin/kimi-datasource.mjs"],
      "cwd": "./"
    }
  }
}
```

## 未支持字段：诊断而非静默忽略

`manifest.ts:21`：

```ts
const UNSUPPORTED_RUNTIME_FIELDS = [
  'tools',
  'apps',
  'inject',
  'configFile',
  'config_file',
  'bootstrap',
] as const;
```

生态里的插件常常同时面向多家 agent 工具，清单里会带别家的字段。Kimi Code **不执行**这些字段，但也**不静默丢弃**——每个都发一条 info 级 `PluginDiagnostic`：`"tools" is present but not supported by Kimi plugins`。v1 那段说明这些字段来自哪些工具的注释随禁注释规则删掉了，行为照旧。

静默忽略是最糟的选择：作者以为配了，用户以为装好了，实际什么都没发生。

插件名受 `PLUGIN_NAME_REGEX`（`/^[a-z0-9][a-z0-9_-]{0,63}$/`）约束。路径字段必须以 `./` 开头，并用 `realpath` 解析后检查仍在插件目录内，否则报 `path resolves outside the plugin`——符号链接也逃不出去。

## 插件能带来什么

```text
插件（分发容器）
  ├── skills        → 插件 skill 来源（优先级 5）
  ├── agents        → 插件 agent profile
  ├── mcpServers    → 垫在 mcp.json 之下合并
  ├── hooks         → 并入外部 hook 执行器
  ├── commands      → TUI 的 /<插件>:<命令>
  ├── sessionStart  → 会话开始时注入指定 skill
  └── systemPrompt  → 系统提示里的 Plugin Instructions（≤32 KB）
```

`skills` 缺省时回退到根目录的 `SKILL.md`，`agents` 缺省时找 `./agents`。命令是 Markdown 文件，正文里的 `$ARGUMENTS` 替换为用户参数。插件带来的系统提示被明确标注为「插件提供的参考数据，不是特权指令通道」，与用户在对话里的指令冲突时让位。

插件本身不引入新的能力类型，它只是**打包分发层**——扩展点还是那几个，插件只解决「怎么把它们一起装上」。会话中途装卸插件时，`agent/plugin/agentPluginService.ts` 会给模型一条提醒：本会话仍沿用开场时的提示词与工具，要 `/new` 或 `/reload` 才生效。

## 三级信任

`plugins/marketplace.json`（节选）：

```json
{
  "version": "1",
  "plugins": [
    {
      "id": "kimi-datasource",
      "tier": "official",
      "source": "./official/kimi-datasource"
    },
    {
      "id": "superpowers",
      "tier": "curated",
      "homepage": "https://github.com/obra/superpowers",
      "source": "https://github.com/obra/superpowers"
    }
  ]
}
```

目录里现有 2 个 official（`kimi-datasource`、`kimi-webbridge`）和 4 个 curated。客户端默认从 `https://code.kimi.com/kimi-code/plugins/marketplace.json` 拉取，可用 `KIMI_CODE_PLUGIN_MARKETPLACE_URL` 改；`tier` 只认 `official` 与 `curated`。

真正展示给用户的是 TUI 算出的三级标签（`apps/kimi-code/src/tui/utils/plugin-source-label.ts`）：

| 标签 | 判定 |
| --- | --- |
| `official` | 从 Kimi 官方 CDN 的官方插件路径下载的 zip |
| `curated` | 从 Kimi CDN 的 `/kimi-code/plugins/curated/` 路径下载的 zip |
| `third-party` | 其余一切：本地路径、GitHub 仓库、其他 URL |

判定只看**安装来源**，不看清单里的名字——冒用官方插件名的仓库照样是 third-party。安装第三方插件前会弹出确认，默认选项是 Exit，必须主动选 Trust and install。README 的说法：

> Install skills, MCP servers, and data sources from the marketplace or any GitHub repo, **with each install's trust level surfaced up front**.

这是对的做法——插件能注册 hook（在本机执行命令）与 MCP 服务器（外部代码），信任级别必须在决策时摆到台面上，而不是藏在文档里。

## GitHub 直装

`app/plugin/source.ts` 的 `resolveInstallSource()` 把安装源分成三类：`github.com` 的仓库地址（可带 `tree/<ref>`、`releases/tag/<tag>`、`commit/<sha>`）、其他 http(s) 链接（当 zip 下载）、绝对路径。GitHub 源由 `github-resolver.ts` 换成 codeload 的 tarball 地址，需要把分支解析成 SHA 时读仓库的 commit atom feed。安装记录写在 `~/.kimi-code/plugins/installed.json`，托管副本放在 `plugins/managed/<id>`。

「任意 GitHub 仓库」直接可装，降低了分发门槛，这也是信任标签必须显眼的原因。

## 数据源

`marketplace.json` 里第一个官方插件是 `kimi-datasource`，对应文档 `docs/zh/customization/datasource.md`。它把金融、新闻、宏观、学术、法律等外部数据以 MCP 服务器的形式接进 agent 上下文，是插件生态里的一类特殊用途。

下一篇：[pi-tui 差分渲染](https://daiw.org/manual/kimi-code/pi-tui)。