插件

插件是经过审查的分发包，可以贡献技能、命令、智能体配置、钩子、MCP server、可执行文件和输出样式。安装插件会增加能力，但不会扩大任务工作区、权限配置或管理员安全上限。

组织可以通过批准的 Marketplace、私有 Git、npm registry 或本地包分发插件。Kairo Code 接受兼容的 plugin.json manifest，并把经审查字节安装为不可变快照。

仅限本地 Host 管理

安装、激活、启停、回滚和卸载会改变 Host 可执行能力面，只能在回环本地 Host 或桌面 SSH 到这样的远程 Host 执行。JWT、API token、配对设备、LAN 和正确配置的反向代理只能查看有界目录，不能修改。不要把开启 loopback bypass 的监听器暴露给公共代理。

安装与激活

打开 Settings → Extensions → Plugins，选择 Marketplace、Git、npm 或本地来源。激活前审查：

来源及准确版本/修订；
新增技能、智能体配置、Hook、命令、MCP server 与可执行文件；
来源是否钉住不可变字节，还是以后可能解析成不同内容。

安装、审查和激活是三个步骤。激活只影响新任务；已有任务保持启动时的能力快照，另一个窗口的改变不会静默修改运行中的智能体。详情页会列出保留快照，选择旧快照只回滚该插件；激活失败时会恢复上一可用项。

编写插件

只含一个技能的最小布局：

text

my-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

json

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Adds my custom skill",
  "author": "@me",
  "license": "MIT"
}

还接受 .kairo-plugin/plugin.json、.claude-plugin/plugin.json 和根目录 plugin.json。多个 manifest 同时存在时优先级为 Kairo → Claude → Codex → 根文件；Kairo 在安装制品内规范化布局，不改写源码目录。

支持 skills/、agents/、commands/、hooks/、bin/ 和 output-styles/。MCP server 不从 mcp/ 自动发现，应写在根 .mcp.json 的 mcpServers 对象，或所选 manifest 的 mcpServers 字段；同名时 manifest 胜出。

智能体配置（`agents/*.md`）

每个文件定义一个配置，必须解析出非空名称、委派描述和指令正文。文件名是默认名称，description 写在 YAML frontmatter，正文写指令；任何一项为空都会跳过。

markdown

---
name: code-reviewer
description: 审查差异并只返回发现，不修改工作区
tools:
  - read
  - grep
---
审查正确性、安全性和缺失验证，只返回发现。

model、model_reasoning_effort、sandbox_mode、tools、skills、mcp_servers 使用与工作区配置相同的能力上限；它们只能继承或收窄父任务。激活后以 my-plugin:code-reviewer 一类限定名注册，仍通过同一个 task 工具执行任务范围的子智能体，不会创建持久 Team 或第二套编排。完整字段见创建智能体配置。

引用插件根目录

命令或 MCP 定义需要安装位置时使用 ${KAIRO_PLUGIN_ROOT}：

json

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${KAIRO_PLUGIN_ROOT}/server.js"]
    }
  }
}

远程 HTTP/SSE 定义使用 url（可带 type、headers）代替 command/args。带有明确 .claude-plugin/plugin.json 的导入源可以包含三个旧 ${CLAUDE_*} 插件占位符。上游加载器会在返回 manifest 前于内存中将其改写为对应的 KAIRO_* 名称；Kairo 原生源或无 manifest 的源若仍残留这些占位符，将直接拒绝加载。

存储与回滚

有效数据目录下按用途分离：

plugins/cache/：下载缓存；
plugins/artifacts/<name>/<version>/<sha256>/<name>/：不可变运行快照；
plugins/data/<plugin-name>/：运行时可写数据。

运行时始终引用按内容寻址的 artifact，不引用下载缓存或原始本地目录。编辑本地源码不会静默修改已安装插件；卸载移除运行注册，但保留不可变 artifact 供去重和回滚。

Marketplace 来源

来源必须有 CURATED、REVIEWED 或 COMMUNITY 信任等级，并使用无凭据 HTTPS 目录 URL。移除来源不会卸载已经安装的插件或技能。

Git 目录可钉 branch、tag 或完整 SHA；界面显示解析后的 commit，并在远程临时不可用时继续提供最后验证快照。完整 SHA 是不可变坐标；branch/tag 仍可安装，但审查会标为可变。界面记录最后检查、最后成功刷新、脱敏失败原因和当前 Git commit。刷新失败会把来源标为 degraded，但保留最后成功目录。

插件 ​

安装与激活 ​

编写插件 ​

智能体配置（agents/*.md） ​

引用插件根目录 ​

存储与回滚 ​

Marketplace 来源 ​