插件管理

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

插件管理

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

什么是插件？

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

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

插件管理

进入插件管理

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

插件列表

显示工作空间中的插件：

绑定插件

从技能市场

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

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

详细了解：技能市场

上传自定义插件

上传自己创建的插件：

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

绑定限制

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

管理插件

启用/禁用

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

禁用的插件：

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

更新插件

1. 找到有更新的插件
2. 点击"更新"按钮
3. 确认更新

解绑插件

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

解绑后：

• 插件从工作空间移除
• 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

目录说明

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/

上传测试

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

内置环境变量

插件中的脚本和工具可以访问以下内置环境变量，用于获取当前会话的上下文信息：

使用示例

在 Skill 或工具脚本中访问环境变量：

Bash 脚本：

#!/bin/bash
echo "当前工作空间: $JAVIS_WORKSPACE_NAME"
echo "当前用户: $JAVIS_LOGIN_USERNAME"

Python：

import os

workspace_name = os.environ.get('JAVIS_WORKSPACE_NAME', '')
user_email = os.environ.get('JAVIS_LOGIN_USER_EMAIL', '')

print(f"工作空间: {workspace_name}, 用户邮箱: {user_email}")

调用后端 API

使用 JAVIS_AUTH_TOKEN 和 JAVIS_FRONTEND_BASE_URL 可以调用后端 API：

curl -X GET "${JAVIS_FRONTEND_BASE_URL}/api/v1/workspaces/${JAVIS_WORKSPACE_ID}" \
  -H "Authorization: Bearer ${JAVIS_AUTH_TOKEN}"

注意： JAVIS_AUTH_TOKEN 包含用户认证信息，请勿在日志中输出或分享给第三方。

运行时兼容性

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

组件支持对比

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 组件会被跳过
• 系统会记录警告日志
• 不影响其他组件正常工作

最佳实践

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

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

插件最佳实践

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：插件中的脚本可以访问外部 API 吗？

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

Q：如何调试插件？

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

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

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

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

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

相关文档

• 技能市场
• AI Agent 团队
• 运行时对比
• 成员与权限