插件开发工具包
插件描述为 一 manifest.json. 在开发过程中验证清单的合同，与平台在安装时强制执行的合同是相同的，所以一个通过验证的清单 validate 是市场会接受的清单。 aihummer plugin CLI 覆盖整个生命周期：从脚手架到签名和发布。
一份清单，一份合同
一个插件只有一个真实来源——它的 manifest.json. 它声明了插件类型（kind），它是如何配置的（config[]）、其功能，以及——对于主机本地服务—— install[] 步骤和启动命令 Systemd部署器 运行。因为开发和安装使用相同的验证协议，“有效清单”和“可安装插件”意味着相同的东西。
[!NOTE] 清单描述了插件的 合同，而不是它的商店页面名称。 机器
slug来自目录/捆绑包名称（私有侧载）或来自 你填写的提交表 «我的插件» 发布社区插件时 — 看 发布插件.
命令行界面
aihummer plugin 捆绑开发、打包和发布命令：
# Scaffold a manifest (kind: connector | service | openapi | mcp)
aihummer plugin init <kind> [dir]
# Validate a manifest against the install contract
aihummer plugin validate <manifest.json>
# Generate an ed25519 author key (writes <prefix>.key and <prefix>.pub)
aihummer plugin keygen [--out <prefix>]
# Build and package the plugin into a release tarball + .sha256
aihummer plugin package <dir> [--out <file>] [--slug <slug>] [--build "<cmd>"]
# Sign the release identity (slug\0version\0source_ref); with --manifest the
# signature is embedded into the manifest.signature field
aihummer plugin sign --key <priv> [--manifest <m.json>] <bundle|dir>
# Upload a private plugin into your own instance (side-load)
aihummer plugin publish --private --instance <url> --token <admin> <bundle.tar.gz>发布一个 社区 为每个人的插件，你做 不 使用 CLI 命令——你上传你打包并签名的工件 我的插件 在个人柜台（上传 → AI 审核 → 审核）。见 提交插件.
| 命令 | 它的作用 |
|---|---|
init <kind> [dir] |
写一个入门者 manifest.json 为所选择的种类。 |
validate <m.json> |
使用与安装相同的契约验证清单。 |
keygen |
生成作者密钥对： .key (私密，保密) 和 .pub，打印了 key id. |
package <dir> |
构建（可选） --build) 并打包成 <slug>-<version>.tar.gz 带有一个 --strip-components=1 布局，写作 .sha256. 从不打包 .env, *.key, node_modules, .git. |
sign --key <priv> |
签署释放身份；打印签名并 key id; 与 --manifest 将签名嵌入清单中。 |
publish --private |
将一个捆绑包上传到您的实例 POST /v1/admin/modules/upload. |
两种发布方式——私有侧载和通过个人控制面板进行社区发布——均在…中有详细说明 发布插件.
清单字段
某个字段是否为必填取决于 善良 以及插件是否公开。基础和身份字段：
| 字段 | 类型 | 必填 | 目的 |
|---|---|---|---|
kind |
字符串 | 总是 | 种类： connector | service | openapi | mcp. |
version |
字符串 | 是 | 插件版本（语义化版本），例如 1.0.0. |
contract |
字符串 | 用于频道 | 合同编号，例如 aihummer.channel.v1. |
scope |
字符串 | 不 | 访问模型： shared (默认) 或 personal. |
capabilities |
字符串数组 | 不 | 声明的能力。 |
config |
对象数组 | 不 | 配置表单字段；每个都需要 key，加 label, secret, required. |
oauth |
物体 | 不 | OAuth2 (authorize_url, token_url, scopes[]) 连接用户的账户。 |
signature |
字符串 | 签署时 | 对发布身份的 base64 ed25519 签名（嵌入者 sign). |
特定类型字段 — 恰好一个 块根据…填充 kind:
| 字段 | 对于善良 | 必填 | 目的 |
|---|---|---|---|
host_native.exec_start |
连接器，服务 | 是 | 运行长期运行服务的命令。 |
host_native.runtime |
连接器，服务，MCP | 不 | node | python | binary. |
host_native.install |
连接器，服务，MCP | 不 | 安装步骤（shell 命令数组），在解压后在主机上运行。 |
host_native.port |
连接器，服务 | 不 | 首选 TCP 端口（部署者可以通过重新分配） $PORT). |
host_native.health_path |
连接器，服务 | 不 | 健康检查路径（默认 /healthz). |
openapi.spec_url |
开放API | 是 | OpenAPI 3.x 规范的 URL。 |
openapi.base_url |
开放API | 不 | 覆盖 servers[0].url. |
openapi.allowed_hosts |
开放API | 不 | 合成工具的出口允许列表。 |
openapi.auth |
开放API | 不 | 地图 securityScheme → 秘密名称。 |
openapi.tool_prefix |
开放API | 不 | 工具名称前缀。 |
mcp.transport |
mcp | 是 | stdio 或者 http. |
mcp.command / mcp.args |
mcp（标准输入输出） | 是的，用于标准输入输出 | 服务器可执行文件和参数。 |
mcp.url |
mcp（http） | 是的，用于 http | MCP 端点 URL。 |
mcp.auth_header / mcp.secret_token_key |
mcp（http） | 不 | 承载令牌的头部和密钥。 |
商店页面和身份字段（用于社区插件）
清单还可以包含发布者身份和商店页面字段。对于一个 社区 插件这些是目录显示的，但你通常在…中输入它们 «我的插件» 在提交时在你的个人控制面板中的商店页面填写（名称、描述、图标、截图、类别、捐赠链接），而不是手动在清单中填写。私下侧载不需要这些——这样的插件在实例级别是被信任的。
| 字段 | 类型 | 必填 | 目的 |
|---|---|---|---|
visibility |
字符串 | 不 | public | private | unlisted. 空白 = 传统/第一方（无需身份要求）。 |
publisher |
字符串 | 公开的 | 发布者命名空间， ^[a-z0-9][a-z0-9-]{1,38}$公共蛞蝓被命名 @publisher/slug. |
publisher_key_id |
字符串 | 公开的 | key id 用该文物签署的钥匙的 |
description |
字符串 | 公开的 | 目录中的商店页面简介。 |
icon |
字符串 | 公开的 | 插件图标：一个 https:// URL 或一个 data: 统一资源标识符 |
screenshots |
字符串数组 | 不 | 商店页面截图（数组） https:// URL；每个非空的。 |
[!TIP] 跑
aihummer plugin validate在你提交之前。安装和验证 合同是相同的，因此在本地通过的清单将被两者接受 由市场部署者和你个人柜中的市场审核进行。
最小化清单
A service 脚手架（什么 aihummer plugin init service 写道）:
{
"version": "1.0.0",
"kind": "service",
"scope": "shared",
"contract": "aihummer.channel.v1",
"host_native": {
"runtime": "node",
"install": ["npm ci --omit=dev"],
"exec_start": "node dist/main.js",
"port": 8800,
"health_path": "/healthz"
},
"config": [
{ "key": "api_token", "label": "API token", "secret": true, "required": true }
]
}零代码 openapi 清单甚至更短——它只是指向规范：
{
"version": "1.0.0",
"kind": "openapi",
"scope": "shared",
"openapi": {
"spec_url": "https://api.example.com/openapi.json",
"tool_prefix": "example_",
"allowed_hosts": ["api.example.com"],
"auth": { "bearerAuth": "api_token" }
},
"config": [
{ "key": "api_token", "label": "API token", "secret": true, "required": true }
]
}一 mcp 清单（stdio 传输）:
{
"version": "1.0.0",
"kind": "mcp",
"scope": "shared",
"host_native": { "runtime": "node", "install": ["npm ci --omit=dev"] },
"mcp": { "transport": "stdio", "command": "node", "args": ["server.js"] }
}从清单到市场
验证后，插件被打包（package），签署（sign）并以两种方式之一发布：
- 私人（仅限自己） — 通过管理员用户界面侧加载到您的实例中，或
publish --private. 该物品从不离开副本。 - 社区（面向所有人） — 从中上传打包并签名的工件 我的插件 在你的个人柜子里； 在人工智能审核和人工监管之后，它被签署并发布到社区 目录
看 发布插件 完整指南。