插件管理

了解如何管理和创建插件，扩展工作空间能力

插件管理

插件是 Knodo 的扩展机制，让您可以添加自定义的 Agent 和工具。本文档介绍插件的管理和创建方法。

什么是插件？

插件是包含 Agent 定义和工具函数的扩展包。

插件目录结构可参考官方示例：apps/plugins/javis

插件管理

进入插件管理

进入工作空间设置
点击"插件管理"选项卡

插件列表

显示工作空间中的插件：

插件列表管理界面

字段	说明
名称	插件名称
版本	当前版本
来源	市场/自定义
状态	启用/禁用
Agent 数	包含的 Agent 数量
工具数	包含的工具数量

绑定插件

从技能市场

最简单的方式是从技能市场安装：

进入技能市场
找到需要的Skill
点击或文字要求AI安装

详细了解：技能市场

上传自定义插件

上传自己创建的插件：

上传插件界面

准备插件 ZIP 文件
点击"上传插件"按钮
选择 ZIP 文件
等待上传和验证
完成绑定

绑定限制

ZIP 文件大小有限制限制，具体见界面要求
代码经过安全检查

管理插件

启用/禁用

在插件列表找到目标插件
点击启用/禁用开关

禁用的插件：

Agent 不会出现在对话中
工具不可使用
配置保留

更新插件

找到有更新的插件
点击"更新"按钮
确认更新

解绑插件

找到目标插件
点击"解绑"按钮
确认操作

解绑后：

插件从工作空间移除
Agent 和工具不再可用

查看插件详情

基本信息

点击插件名称查看详情：

插件名称和描述
版本信息
作者信息
包含的 Agent 列表
包含的工具列表

Agent 详情

点击 Agent 名称查看：

Agent 名称和描述
完整的 Prompt 内容
使用的工具

工具详情

点击工具名称查看：

工具名称和描述
输入参数
返回值说明

创建自定义插件

插件结构

my-plugin/
├── .claude-plugin/           # 元数据目录（必需）
│   └── plugin.json          # 插件清单
├── commands/                 # 自定义斜杠命令（可选）
│   └── my-command.md
├── agents/                   # 子代理定义（可选）
│   └── my-agent.md
├── skills/                   # 自动技能（可选）
│   └── my-skill/
│       └── SKILL.md
├── hooks/                    # 事件钩子配置（可选）
│   └── pre-commit.json
├── .mcp.json                # MCP 服务器配置（可选）
├── .lsp.json                # LSP 服务器配置（可选）
└── scripts/                 # 钩子执行脚本（可选）
    └── validate.sh

目录说明

目录/文件	必需	说明
`.claude-plugin/`	是	元数据目录，包含 plugin.json
`plugin.json`	是	插件清单文件，定义插件基本信息
`commands/`	否	自定义斜杠命令，用户可通过 `/命令` 调用
`agents/`	否	子代理定义，每个 Agent 一个 Markdown 文件
`skills/`	否	自动技能，按标准 Skill 目录结构组织
`hooks/`	否	事件钩子配置，响应特定事件
`.mcp.json`	否	MCP (Model Context Protocol) 服务器配置
`.lsp.json`	否	LSP (Language Server Protocol) 服务器配置
`scripts/`	否	钩子执行脚本，被 hooks 调用

plugin.json

插件清单文件，位于 .claude-plugin/ 目录：

{
  "version": "1.0.0",
  "description": "我的自定义插件",
  "author": {
    "name": "Dev Team",
    "email": "dev@example.com"
  },
  "license": "MIT",
  "agents": [
    "./agents/xxx-agent.md"
  ],
  "skills": "./skills/",
  "commands": "./commands/"
}

Agent 定义

Agent 使用 Markdown 文件定义，存放在 agents/ 目录：

---
name: 我的 Agent
description: 这是一个自定义 Agent
---

# 角色设定

你是一个专业的助手...

# 任务说明

你需要帮助用户...

# 输出格式

请按以下格式输出...

Skill 定义

技能使用标准 Skill 目录结构，存放在 skills/ 目录：

skills/
└── my-skill/
    ├── SKILL.md              # 核心指令文件
    ├── templates/            # 模板文件（可选）
    ├── examples/             # 示例文件（可选）
    └── references/           # 参考资料（可选）

详细的 Skill 目录结构请参考：技能市场 - 技能目录结构

打包插件

将插件目录打包为 ZIP 文件：

zip -r my-plugin.zip my-plugin/

上传测试

上传到工作空间
测试 Agent 和工具
修改并迭代

环境变量

插件中的脚本和工具可以访问系统内置环境变量和用户自定义环境变量：

内置环境变量：系统自动注入的会话上下文信息（如工作空间 ID、用户名、认证令牌等），详见内置环境变量
自定义环境变量：用户在工作空间/组织/个人维度配置的变量（如 API Key、密钥等），详见环境变量管理

运行时兼容性

插件在不同 AgentOS 运行时的支持情况有所不同。

组件支持对比

组件类型	Claude Code	Cortexa	OpenCode	说明
Agent	✅ 原生	✅ 原生	✅ 自动转换	OpenCode 会转换 frontmatter 格式
Skill	✅ 原生	✅ 原生	✅ 共用格式	所有运行时使用相同的 SKILL.md 格式
Command	✅ 原生	❌ 不支持	✅ 软链接	Cortexa 不支持 Command
MCP Server	✅ 原生	✅ 原生	✅ 自动转换	OpenCode 会转换 JSON 配置格式
Hook	✅ 原生	✅ 原生	❌ 不支持	OpenCode 不支持 Hook 机制

OpenCode 转换机制

当使用 OpenCode 运行时时，系统会自动转换 Claude Code 格式的插件组件：

Agent 转换规则：

name、description 字段保留
capabilities、skills、tools 数组转为 Markdown 列表
添加 mode: primary 标记

MCP 转换规则：

Claude Code 格式:
{ "mcpServers": { "name": { "command": "node", "args": ["server.js"] } } }

转换为 OpenCode 格式:
{ "type": "local", "command": ["node", "server.js"], "enabled": true }

Hook 处理：

Hook 组件会被跳过
系统会记录警告日志
不影响其他组件正常工作

最佳实践

优先使用通用组件：Agent、Skill、Command 在所有运行时都能工作
谨慎使用 Hook：如果需要跨运行时兼容，避免依赖 Hook 功能
测试多运行时：发布前在不同运行时测试插件功能

详细的运行时对比请参考：运行时对比

插件最佳实践

1. 清晰的命名

# 好的命名
name: code-review-helper
description: 代码审查助手，帮助检查代码质量

# 避免
name: plugin1
description: 一个插件

2. 完整的文档

在 plugin.json 中提供详细描述
为每个 Agent 写清晰的说明
为 Skill 添加完整的使用指南

3. 版本管理

"version": "1.0.0"  // 初始版本
"version": "1.1.0"  // 新增功能
"version": "1.0.1"  // Bug 修复

常见问题

Q：插件可以分享给其他人吗？

A：可以。将 ZIP 文件分享给他人，或提交到技能市场。

Q：跨组织绑定 PUBLIC 插件时会发生什么？

A：系统会自动将插件文件拷贝到目标组织的存储中。后续源插件更新时，绑定会标记为「有更新」，用户可手动触发同步。这确保了不同组织的数据隔离和离线可用性。

Q：跨组织插件的同步状态有哪些？

A：有四种状态：

NONE - 同组织绑定，无需同步
SYNCED - 已同步到最新版本
OUTDATED - 源插件有新版本可用
SYNC_FAILED - 同步失败，可点击重试

Q：插件中的脚本可以访问外部 API 吗？

A：可以，但需要在安全沙箱内执行，部分能力受限。

Q：如何调试插件？

A：上传后在对话中测试，查看错误信息进行调试。

Q：插件会影响其他工作空间吗？

A：不会。插件只在绑定的工作空间中生效。

Q：插件支持哪些配置文件格式？

A：plugin.json 使用 JSON 格式，Agent 和 Skill 使用 Markdown 格式。

插件管理

插件管理

什么是插件？

插件管理

进入插件管理

插件列表

绑定插件

从技能市场

上传自定义插件

绑定限制

管理插件

启用/禁用

更新插件

解绑插件

查看插件详情

基本信息

Agent 详情

工具详情

创建自定义插件

插件结构

目录说明

plugin.json

Agent 定义

Skill 定义

打包插件

上传测试

环境变量

运行时兼容性

组件支持对比

OpenCode 转换机制

最佳实践

插件最佳实践

1. 清晰的命名

2. 完整的文档

3. 版本管理

常见问题

相关文档