插件管理

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

插件管理

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

什么是插件？

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

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

插件管理

插件列表

显示工作空间中的插件：

插件列表管理界面

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

绑定插件

从技能市场

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

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

详细了解：技能市场

上传自定义插件

上传自己创建的插件：

上传插件界面

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

上传 Skill 包

如果您只有 Skill 包（不含 plugin.json 的完整插件结构），可以直接上传 Skill 包，系统会自动创建 Plugin 包装。

上传 Skill 界面

点击"上传 Skill"按钮
选择包含 SKILL.md 的 ZIP 文件
系统自动解析 SKILL.md 中的名称和描述
自动生成 Plugin 元数据并创建

上传 Skill 界面

Skill 包要求：

必须包含 SKILL.md 文件
SKILL.md 需包含 YAML frontmatter（--- 包裹），至少提供 name 和 description
可选包含 templates/、examples/、references/、scripts/ 目录

Skill 包示例结构：

my-skill/
├── SKILL.md          # 必须 - 含 YAML frontmatter
├── templates/        # 可选 - 代码模板
├── examples/         # 可选 - 示例文件
├── references/       # 可选 - 参考文档
└── scripts/          # 可选 - 自动化脚本

SKILL.md frontmatter 示例：

---
name: my-skill
description: "描述这个 Skill 的用途"
keywords:
  - keyword1
  - keyword2
---

# Skill 标题

Skill 的详细说明...

向已有插件添加 Skill

在插件详情页，可以将新的 Skill 包添加为已有插件的组件：

进入插件详情页
点击"添加 Skill"按钮
选择包含 SKILL.md 的 ZIP 文件
Skill 会被解压到插件的 skills/ 目录中

⚠️ 注意：如果插件中已存在同名 Skill，系统会提示冲突错误

绑定限制

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

云端沙箱同名插件处理

云端沙箱中的插件挂载路径为 /plugins/{插件名}。不同组织可以拥有同名插件，但同一个沙箱中每个插件名称只挂载一个来源，不能同时加载同名插件的多个版本。

当空间绑定、当前会话的助手或连接器插件、已有容器保留的动态插件发生同名冲突时，依次优先使用：空间显式绑定 > 当前请求动态插件 > 容器保留的动态插件。同一来源层级中，优先工作空间所属组织的插件，其余按组织 slug 稳定排序选择。相同组织和名称的动态插件在当前请求中重新出现时，使用当前请求解析到的版本和状态。已禁用插件不参与选择，也不会进入挂载、指纹或动态保留集合；显式请求已禁用的动态插件会返回不可用错误，不会加载其内容。

例如，空间绑定了组织 A 的 superpowers，助手绑定了组织 B 的同名插件，实际挂载的是空间绑定的版本。若需要助手绑定的版本，请先将空间与助手的绑定统一为同一个插件。后端会记录冲突中保留和跳过的插件来源、版本及优先级，不会重复挂载同一个目录。

插件来源、集合或读写状态变化时，即使空间采用永久保留或仅随镜像版本更新的策略，且关闭指纹变化时的 SSE 排空功能，新请求也不会静默复用不匹配的旧挂载。旧沙箱仍有运行中的任务或会话时，本次请求返回明确错误，请等待执行结束后重试；空闲时重建沙箱。已记录挂载身份的容器仅发生插件版本变化时，仍遵循原有保留策略。

旧版本容器没有完整挂载身份记录时，首次插件指纹变化会采用同样的检查和重建流程，以确认实际来源；不会仅因部署升级就统一重建所有空间。

管理插件

插件状态

插件状态修改

插件有三种状态：

状态	说明	挂载模式
草稿	开发中，可编辑	读写（rw）
已发布	稳定版本，只读	只读（ro）
已禁用	暂停使用	不挂载

编辑权限管理

默认情况下，插件发布后仅创建人可以编辑。创建人可以将编辑权限授权给同组织的其他成员，支持协作编辑。

添加可编辑者：创建人在插件详情页的「可编辑者」字段中添加组织成员
移除可编辑者：创建人可随时移除已授权的编辑者
可编辑者权限：被授权者拥有与创建人同等的编辑能力（编辑元数据、组件、状态等），但不能管理可编辑者列表或转让插件
转让插件：创建人可以将插件所有权转让给同组织成员，转让后原创建人自动保留编辑权限

插件编辑者

成员离开组织后，其编辑权限自动失效。

草稿状态：

草稿状态是为插件开发者设计的。传统方式下，开发插件需要反复经历"本地修改 → 打包 ZIP → 上传 → 测试"的循环，效率低下。草稿模式让开发者可以直接在 Knodo 平台上开发和调试插件，修改即时生效，大幅缩短开发迭代周期。

新创建的插件默认为草稿状态
容器以读写模式挂载插件目录
可以直接在工作空间内修改插件文件（包括 Agent 定义、工具代码等）
修改即时生效，无需重新打包上传（最好新启动会话来全新测试）

已发布状态：

容器以只读模式挂载插件目录
防止运行时意外修改
确保插件稳定性和可重复使用

⚠️ 注意：状态切换会触发容器重启，需要新启动一个会话才能使新的挂载模式生效

发布插件

将草稿插件发布为稳定版本：

在插件列表找到草稿状态的插件
点击操作菜单（⋮）
选择"发布"
确认发布

发布后：

插件状态变为"已发布"
容器以只读模式挂载
无法在运行时修改插件文件

切回草稿

如需修改已发布的插件：

在插件列表找到已发布的插件
点击操作菜单（⋮）
选择"切回草稿"
确认操作

切回草稿后：

插件状态变为"草稿"
容器以读写模式挂载
可以继续修改插件文件

⚠️ 注意：状态切换会触发容器重启，需要新启动一个会话才能使新的挂载模式生效

启用/禁用

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

禁用的插件：

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	Codex	OpenCode	说明
Agent	✅ 原生	❌ 首期不自动兼容	✅ 自动转换	Codex 不自动把 Claude Agent 注册为子代理
Skill	✅ 原生	✅ 复用 `skills/`	✅ 共用格式	Codex 通过 app-server `skills/extraRoots/set` 加载
Command	✅ 原生	⚠️ 后续适配候选	✅ 软链接	Codex 首期不自动注册 Claude command
MCP Server	✅ 原生	✅ 复用 `.mcp.json`	✅ 自动转换	Codex 通过 CLI `-c` MCP override 注入
Hook	✅ 原生	❌ 首期不自动兼容	❌ 不支持	Claude Hook 与 Codex Hook schema 不等价

Codex 复用范围

Codex 使用同一套插件绑定、解绑和远程同步入口，不需要单独创建 Codex 专用插件流程。当前首期支持直接复用两类 Claude Code 插件资产：

.mcp.json：转换为 Codex CLI 启动参数中的 MCP 配置覆盖，不默认写入用户全局 CODEX_HOME/config.toml
skills/<name>/SKILL.md：作为 Codex app-server 的额外 Skill Root 注入，不把 Skill 内容拼接到系统提示词

首期不会自动兼容 commands/、agents/、hooks/、themes、output-styles、lspServers、settings、bin 等 Claude Code 专有能力。这些项目会进入 Codex 复用报告，展示为后续适配候选或不可复用原因。

会话影响规则：

云端沙箱：插件绑定、解绑或同步变化会停止旧 sandbox，后续 Codex 会话使用最新插件快照
本地执行机：插件变化默认只影响新 Codex 对话，已有对话保留创建时插件快照；如需立即生效，需要重建对应 Codex app-server 会话

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 格式。

插件管理

插件管理

什么是插件？

插件管理

插件列表

绑定插件

从技能市场

上传自定义插件

上传 Skill 包

向已有插件添加 Skill

绑定限制

云端沙箱同名插件处理

管理插件

插件状态

编辑权限管理

发布插件

切回草稿

启用/禁用

更新插件

解绑插件

查看插件详情

基本信息

Agent 详情

工具详情

创建自定义插件

插件结构

目录说明

plugin.json

Agent 定义

Skill 定义

打包插件

上传测试

环境变量

运行时兼容性

组件支持对比

Codex 复用范围

OpenCode 转换机制

最佳实践

插件最佳实践

1. 清晰的命名

2. 完整的文档

3. 版本管理

常见问题

相关文档