Cindy 插件目录结构实战指南:从 ghost.json 身份卡到 panel.html 的最小可用骨架
Cindy 插件目录结构实战指南:从 ghost.json 身份卡到 panel.html 的最小可用骨架
本文以 Cindy 内置创作技能 cindy-plugin-creator 的《插件源码与包目录结构(§1)》为主线,逐项拆解一个可打包 .cindy 插件的源码目录长什么样、每个文件在什么条件下是“必须”的、以及宿主在打包期如何校验它们。读完后你能独立搭出最小可用骨架,也能判断自己的插件该不该引入 node/、locales/、main-view.html 这些可选目录,并避开“打包通过但安装失败”“声明了文件但实际缺失”这两类最常见的坑。
一、最小可用目录结构全景
原文档给出的骨架如下(注释为各文件与目录的职责边界):
my-ghost/
├── ghost.json ← 身份卡(必须,zip 根部)
├── main.js ← 电子脑:后台逻辑入口(声明了 tools/cindy 时必须)
├── assets/
│ └── icon.png ← 建议:插件图标(声明 icon 字段时必须存在;scaffold 会生成占位图,请替换成自己的)
├── locales/ ← 可选:宿主驱动的清单文案翻译(声明 locales 时英文必须存在)
│ ├── en.json
│ ├── zh-CN.json
│ ├── ja.json
│ └── ko.json
├── node/
│ └── worker.cjs ← 可选:随包 Node/stdio MCP 入口(声明 node 时必须,见 §4.12)
├── panel.html ← 面板界面(声明了 panel.html 时必须)
├── panel.css
├── panel.js
├── main-view.html ← 一级主视图(声明了 mainView.html 时必须,见 §4.20)
└── settings.html ← 自定义设置区(声明了 settingsHtml 时必须,见 §4.8)
把“是否必须”整理成一张表,比盯着树状图更不容易漏项:
| 路径 | 必须性判定条件 | 缺失时的后果 |
|---|---|---|
ghost.json |
永远必须,且必须在包根 | 打包报 MANIFEST_INVALID |
main.js |
声明了 tools 或 cindy 能力时必须 |
打包报 ENTRY_MISSING |
assets/icon.png |
声明了 icon 字段时必须存在 |
打包报 ENTRY_MISSING;未声明 icon 时宿主显示默认拼图占位符 |
locales/en.json 等 |
声明了 locales 时,en 必须提供 |
打包/安装期拒绝 |
node/worker.cjs |
声明了 node.entry 时必须存在 |
打包报 ENTRY_MISSING |
panel.html |
声明了 panel.html 时必须存在 |
打包报 ENTRY_MISSING |
main-view.html |
声明了 mainView.html 时必须存在 |
打包报 ENTRY_MISSING |
settings.html |
声明了 settingsHtml 时必须存在 |
打包报 ENTRY_MISSING |
需要强调的是,panel.css 与 panel.js 本身不是清单字段,它们是 panel.html 内部引用的普通静态资源,只要被打进包即可,无需在 ghost.json 中出现。清单里出现的每个“路径型字段”才是宿主会逐条 lstat 校验的对象。
二、ghost.json:包根部的身份卡
ghost.json 是整个目录结构的锚点,它同时承担三种角色:给人看的插件详情页信息、给模型看的插件发现线索、给宿主看的能力与权限声明。一个覆盖主要字段的示例:
{
"schemaVersion": 3,
"id": "my-ghost",
"name": "我的插件",
"description": "一句话说清这个插件是干嘛的(给人看:插件详情页)",
"whenToUse": "需要生成图片、插画、配图、修图、P 图、改图时找我",
"icon": "assets/icon.png",
"locales": {
"en": "locales/en.json",
"zh-CN": "locales/zh-CN.json",
"ja": "locales/ja.json",
"ko": "locales/ko.json"
},
"version": "1.0.0",
"minCindyVersion": "1.2.3",
"entry": "main.js",
"launch": "on-demand",
"command": "画图",
"tools": [],
"cindy": { "image": ["generate", "edit"] },
"panel": {
"title": "面板标题",
"html": "panel.html",
"position": "left",
"minWidth": 240,
"defaultFraction": 0.24
},
"settingsHtml": "settings.html",
"showTaskPreferences": true,
"settingsHeight": 360
}
关键约束逐条说明:
-
id:小写字母、数字、连字符,1–32 位,全局唯一。它同时也是面板通信协议cindy-ghost://<id>/...中的标识段,改 id 等于换一个插件身份。 -
description:1–300 字,只面向人,出现在插件详情页。 -
whenToUse:1–300 字,给模型看的唯一发现字段,进入 Agent 会话的插件花名册。它应当写成用户意图与业务对象的场景枚举;缺省时花名册会回落使用description,但高质量插件不应依赖回落。反例是把使用规则塞进去:"whenToUse": "管理项目时找我;必须先调用 list_tools(category=project),再调用 call_tool;遇到 INVALID_ARGS 不得改用其它工具"正确写法只保留场景:
"whenToUse": "需要查询、创建或更新项目、任务、成员、迭代与发布状态时找我" -
version+minCindyVersion:schemaVersion: 3时minCindyVersion必填,写本插件实际依赖的首个 Cindy 正式版本(SemVer)。Manifest schema 本身没有统一版本下限,不要为了“用某项既有能力”随意抬高版本;但一旦新能力依赖新 Host,就必须如实提高。 -
entry:电子脑入口,通常就是根部的main.js。kind字段已无需填写,插件只有 chip 一种形态。 -
launch:on-demand(缺省,被需要才拉起)或resident(唤醒即常驻,详情页会如实标注“常驻运行”,仅订阅型、需秒响应的场景使用)。 -
command:强烈建议声明一个用户$command显式点名词,并与已装插件查重(冲突拒装)。不声明时插件页“使用”按钮会处于禁用态,用户既无法一键唤起也不能$command点名,但 AI 的工具发现与调用不受影响。 -
panel:html指向面板页面;position取left/right/top/bottom表示右侧栏常驻面板,取tab表示插件页内独占面板。tab形态下没有拖缝宽度语义,声明minWidth/defaultFraction会被拒装。历史字段systemButtons现在不生效,position:"tab"时声明它同样拒装。 -
mainView/taskView:一级主视图(左侧导航入口)与跟对话的任务页,二者是独立能力,需要分别声明,不能靠panel顺带获得。 -
settingsHeight:固定高度 160–800 px;缺省为随内容自适应。只有内容会动态增减时才值得固定,避免抖动。
关于能力声明,文档给出的记忆规则很实用:带详单的是对象字段(tools、cindy、agent、panel、mainView、taskView、card、subscribe、network、node、preview、skill),布尔能力写成字面量 true(notify、badge、confirm、fs、library、deviceSync、sessionContext、pick、workspace)。不能写 false,不用的字段直接省略;card: {} 与 agent: {} 分别表示基础聊天卡片能力和“用户点击后发起 Agent 回合”。v3 未识别的顶层字段会被原样保留,旧版 Cindy 不展示、不授权、也不阻止安装——这也意味着靠未知字段“提前用上新能力”是无效的,必须同时提高 minCindyVersion。
更完整的清单字段解释见 插件身份卡与能力声明 ghost.json(§2)。
三、main.js:电子脑入口的必须条件与最小实现
原文档写明 main.js 是“后台逻辑入口(声明了 tools/cindy 时必须)”。这句话的背后逻辑是:清单里的 tools、cindy 等能力必须有一个运行时代码去接收工具调用并回传结果,entry 指向的文件就是那个执行体。
一个能跑通的最小沙箱实现(与 Forge plain 模板产出一致):
cindy.onHostMessage(async function (msg) {
if (msg.type !== 'tool-call' || msg.tool !== 'hello') return;
await cindy.send({
type: 'tool-result',
callId: msg.callId,
ok: true,
result: { message: '插件已经正常工作。' }
});
});
配套的清单片段只需要一个 tools 条目:
"tools": [
{
"name": "hello",
"description": "返回一句问候,用来确认插件已经正常工作。",
"parameters": { "type": "object", "properties": {} }
}
]
从源码结构看,main.js 始终是浏览器沙箱代码,不直接持有 Node 能力;需要 CLI、JS 依赖或 stdio MCP 时必须落到 node/ 工作进程,再由 main.js 通过 cindy.node.request 转发(见 随包 Node 工作进程(§4.12))。这条边界决定了目录结构:沙箱入口在根部,Node 入口在子目录,两者不能混写。
Cindy 提供四种起步模板:plain(普通沙箱工具)、agent-action(卡片点击后让 Agent 继续工作)、node-json-rpc(普通随包 Node 服务)、node-mcp(随包 stdio MCP)。模板清单在 forge.ts 中显式定义为常量,脚手架据此决定要不要额外生成 node/worker.cjs:
export const FORGE_SCAFFOLD_TEMPLATES = [
'plain',
'agent-action',
'node-json-rpc',
'node-mcp',
] as const;
四、assets/icon.png:图标的位置、格式与体积红线
文档把图标定位为“建议”,但一旦清单里写了 icon,文件就必须真实存在。仓库里能查到三条硬规则:
- 扩展名白名单:只接受
.png/.jpg/.jpeg/.webp/.gif,不收 svg。原因写在共享类型定义里——svg 可携带脚本,虽然经<img>渲染不执行,仍不开放这个面(ghost.ts)。 - 体积上限 512KB:图标会以 data URL 形态同步下发给 Renderer,所以安装、本地读取与 Forge overlay 必须共用同一硬顶,否则会出现“能打包但不能安装”。
- 路径必须是安全相对路径:
entry/panel.html/settingsHtml与图标共用同一套校验——正斜杠分段、无盘符、无反斜杠、无空段、无./..、每段符合^<a href="https://link.gitcode.com/i/309c8d8f363f2d61144ff3e5bca70c8c" target="_blank">a-zA-Z0-9_][a-zA-Z0-9._-]{0,63}$、整串不超过 256 字符([ghost.ts)。
脚手架默认就会生成 assets/icon.png 占位图,并对齐官方插件仓“图标放 assets/icon.png”的惯例:
const common = {
// ...
entry: 'main.js',
icon: 'assets/icon.png',
};
const files: Record<string, string | Buffer> = {
[GHOST_MANIFEST_FILE]: `${JSON.stringify(manifest, null, 2)}\n`,
'main.js': /* ... */,
'assets/icon.png': Buffer.from(SCAFFOLD_ICON_PNG_BASE64, 'base64'),
};
见 forge.ts 与 forge.ts。占位图是内嵌的 128×128 纯色 PNG,目的是让“有图标”成为骨架默认值,避免作者到发布前才发现插件在面板和身份头里只有一个默认拼图。
五、locales/:宿主驱动的清单文案翻译
locales/ 是可选目录,但一旦在 ghost.json 里声明 locales,规则就变严:
- 插件语言只跟随 Cindy 宿主当前语言。不要读取
navigator.language、操作系统语言或浏览器偏好,也不要在插件内保存另一份语言选择。 - 宿主当前支持
zh-CN / en / ja / ko;插件没提供宿主当前语言时固定回退英文,因此只要声明locales就必须提供en。 - locale JSON 覆盖清单中已有的可本地化字段,翻译是可选项:提供的条目必须合法,未提供的条目运行时回退原 manifest 文案。完整翻译(含每个工具参数的
title/description)是高质量插件的推荐标准,但不是打包或装入门槛。
一个典型的 locale 文件结构:
{
"name": "My Plugin",
"description": "What this plugin does.",
"whenToUse": "Use it when ...",
"tools": {
"do_thing": {
"description": "Do the task and return the result.",
"parameters": {
"/properties/query": {
"title": "Query",
"description": "Describe what to search for."
}
}
}
},
"panel": { "title": "Plugin panel" },
"mainView": { "title": "Workspace" },
"taskView": { "title": "Simulator" },
"network": {
"secrets": {
"api_key": { "label": "API key", "hint": "Create one in account settings." }
},
"connections": {
"instance": { "label": "Service instance", "hint": "Enter the instance URL and token." }
}
},
"node": {
"secretBindings": {
"worker_key": { "label": "Worker key", "hint": "Used only by the local worker." }
}
},
"setup": {
"kv": {
"default_repo": { "label": "Default repository" }
}
}
}
可翻译字段包括 name、description、whenToUse、tools(工具 description 与参数文案)、panel.title、mainView.title、taskView.title、network.secrets / connections、node.secretBindings、setup 的 kv 标签。工具按稳定的 tool name 对齐,参数用 JSON Pointer 对齐(如 /properties/query,根节点用空字符串 "");参数名、类型、枚举和协议结构不翻译;凭证、连接、Node 凭证和 kv 项按稳定 key 对齐,提供某个 key 的条目时 label 必填、hint 可选。
缺译不拒绝,只回退原文;但翻译错位仍是硬错误:未知 key、未知字段、原清单没有的条目、类型或长度不合格、文件缺失、路径大小写与磁盘不一致、无效 JSON、单文件超过 64KB,都会在 Forge 打包期、内置播种期与安装期拒绝。此外所有会作为对象索引的稳定标识(tool name、network secrets / connections key、node.secretBindings key、setup kv key)都不能使用 __proto__、constructor、prototype——这些是宿主保留键,打包时直接拒绝。
六、node/worker.cjs:随包 Node 与 stdio MCP 入口
声明 node 时,node.entry 指向的文件必须存在,且只认 .js / .cjs。一个完整的详单如下:
"node": {
"entry": "node/worker.cjs",
"protocol": "json-rpc-stdio",
"lifecycle": "on-demand",
"idleTimeoutSeconds": 120,
"entries": ["node/build.cjs"],
"childSpawn": true,
"secretBindings": [
{
"key": "mail_code",
"label": "邮箱授权码",
"methods": ["mail/action"],
"entry": "node/worker.cjs",
"hint": "请填写服务商授权码",
"url": "https://mail.example.com/settings"
}
]
}
字段语义与边界:
protocol:json-rpc-stdio(自定义 Node 服务)或mcp-stdio(stdio MCP)。lifecycle:on-demand(缺省)或resident(常驻,详情页单列高风险权限)。idleTimeoutSeconds:仅按需档可用,30–3600;resident禁写。entries:最多 4 条附加工作进程入口,每个入口一个独立进程,调用时用entry指名;不能与主entry、浏览器沙箱入口或彼此重复。childSpawn:允许 worker 请宿主代启“申报入口的原样 stdio 子进程”,详情页单列一行。secretBindings:1–4 条,把 safeStorage 持久化凭证按 JSON-RPC 方法临时注入 Worker;key小写字母开头、1–32 位小写/数字/下划线、插件内唯一,并禁用宿主保留键。
详单不接受 command / args / shell / env 或其它自造字段:入口固定使用 Cindy 随包运行时启动,用户不需要另装 Node、CLI 或 MCP。文档还特别警告:不要在 worker 里用 process.execPath / child_process.fork 再生 Node 子进程——正式包关闭了 RunAsNode,那样生出来的不是 Node;需要多进程就把入口申报进 entries,由主机代开。
通信链是固定的:
Node worker ↔ JSON-RPC stdio ↔ 你的 main.js ↔ Cindy 主机能力
Node 不能直接拿到 cindy、Electron IPC 或 Agent 会话;它向主机发反向 JSON-RPC 请求时,主机会固定返回 -32601。需要 Cindy 能力时,Node 先把数据回给 main.js,再由 main.js 调 Cindy 通道。脚手架为两种协议都提供了零依赖 worker:json-rpc-stdio 版只需 node:readline 逐行解析并按 method 分支回包,mcp-stdio 版则实现 initialize / tools/list / tools/call 三个方法(forge.ts)。另外一条硬规矩:stdout 只能写协议消息,日志写 stderr。
七、panel.html / panel.css / panel.js:面板界面
声明 panel.html 后,该文件必须存在。面板的形态由 panel.position 决定,两种形态的面板代码完全一样,只是宿主容器不同:
left(缺省)/right/top/bottom:右侧栏常驻面板。插件启用后自动成为聊天区对应边页签组中一个不跟对话的全局页签,切任务时留在原位,用户可拖到任何一边、最大化、弹成独立 OS 窗口或关闭。用户放置过后主机记住位置,清单声明只是首次出现时的默认。"tab":插件页内的独占面板,由插件页自己承载,不进右侧栏页签容器;用户在插件页点插件卡的「使用」按钮打开,同一时刻至多一个,离开插件页即关闭卸载。此形态请把界面做成自适应宽度,并且不要假设自己会在后台长期存活——每次打开都可能是全新加载,状态要自己持久化。
右侧栏形态的页签与标题由主机绘制:标题取 panel.title,关闭/最大化/弹出控件由右侧栏统一提供,所以你的 panel.html 只画内容区,不要自己再画一条标题栏。
与电子脑的协作依赖几条约定(详见 插件面板与主题适配(§5)):
- 同源通信使用
BroadcastChannel('<自定名>'),电子脑发、面板收; - 面板取自己的媒体用
cindy-ghost://<id>/media/<指纹><后缀>,主机查账验归属,别人的图返回 404; - 重启回放用
fetch('cindy-ghost://<id>/gallery'),返回本插件作品清单[{src, caption}]; - 叫醒电子脑用
fetch('cindy-ghost://<id>/wake')(幂等,已在跑立即返回)。电子脑是按需拉起的,面板刚打开时它多半没在跑、广播没人听,所以要先/wake再广播,并按reqId每几百毫秒重发直到收到回执(电子脑侧记得按reqId去重); - 主题用主机注入的 CSS 变量并给回退值,如
var(--panel-bg, #f7f7f5)、var(--text-primary, #1a1a1a)。
八、main-view.html 与 settings.html:两个独立的 UI 贡献项
main-view.html 对应一级主视图,需要从 Cindy 左侧导航进入完整页面时声明:
"mainView": {
"title": "工作台",
"icon": "puzzle",
"html": "main-view.html"
}
html必须是包内安全相对路径且文件真实存在;title可省略,省略时回退插件name;声明过基础 title 后,locale 文件才能用"mainView": { "title": "Workspace" }翻译。icon可省略,缺省puzzle。可用值与 Cindy 系统图标名完全一致(puzzle、globe、code、folder、database、chart-column、image、message-circle、calendar-days),不接受别名、任意图标名或图片路径;它只控制左侧导航入口,不替代根级icon品牌图。mainView与panel是两种独立贡献项,可以让两者指向同一 HTML,但必须分别声明;主视图不接受position、宽度或systemButtons。- 同一视图缺省单实例,避免两份界面互相覆盖;只有自己已处理好多视图一致性(共享写入方 / 保存带版本号 /
BroadcastChannel同步)的插件才声明"multiple": true。
settings.html 对应设置页的「自定义设置区」自绘界面。声明了用户填写的凭证时它仍必填,用于长期管理、替换与清除;调用前缺失时主机也会在统一 Setup 卡内联收单。与它配套的两个字段是 showTaskPreferences(是否显示宿主「模型与任务」卡,缺省 true)和 settingsHeight(固定高度 160–800 px)。细节见 插件设置页(§4.8)。
九、打包期校验:目录结构如何被逐条核实
目录结构不是约定俗成,而是打包器逐项核对的产物。Forge 在 forge.ts 中把所有“清单里提到的路径”汇总成一张必存在清单:
const mustExist: string[] = [];
if (manifest.entry) mustExist.push(manifest.entry);
if (manifest.node?.entry) {
mustExist.push(manifest.node.entry, ...(manifest.node.entries ?? []));
}
if (manifest.panel?.html) mustExist.push(manifest.panel.html);
if (manifest.mainView?.html) mustExist.push(manifest.mainView.html);
if (manifest.taskView?.html) mustExist.push(manifest.taskView.html);
if (manifest.settingsHtml) mustExist.push(manifest.settingsHtml);
for (const item of manifest.skill?.items ?? []) mustExist.push(`${item.dir}/SKILL.md`);
if (iconPng === undefined && manifest.icon) mustExist.push(manifest.icon);
随后对每一项执行 lstat 并要求是普通文件,否则返回 ENTRY_MISSING。这里用 lstat 而不是 stat 有一个精巧的原因:收集侧遍历目录时用的是 Dirent 语义,符号链接不会被收集进包;若校验侧用 stat,符号链接会被判为“在场”,结果包缺入口、运行期才 404。
打包时还会跳过开发残留,规则实现在 forge.ts:
function shouldSkip(name: string): boolean {
if (name.startsWith('.')) return true; // .git / .DS_Store / .disabled 等
if (name.toLowerCase() === 'node_modules') return true;
if (name.toLowerCase().endsWith('.cindy')) return true; // 上次打包产物,防套娃
return false;
}
由此可以推出几条实践结论:
.git、node_modules、旧的.cindy产物不会进包,源码目录里存在它们不影响产物体积,但也不要在运行时依赖它们。- 空目录不进包:Forge 只收集普通文件,zip 写入时也关掉了自动补目录(
createFolders: false);装入侧对目录 entry 一律mkdir后跳过,写文件分支本来就会建父目录,所以丢空目录不会造成问题。 - Unix 权限原样进入包(特殊位会被剥除):随包的本机可执行程序必须在打包前就
chmod 755,不要指望宿主按扩展名或bin/目录去猜。 - 产物落在源码目录里,命名为
<id>-<version>.cindy;同版本再次打包会覆盖,下次打包自动跳过。
打包入口是 ghost_forge_pack({ dir }),它只做校验和打包,不安装、不更新插件。若源码目录恰好是已安装插件目录或 Host 托管的状态目录,会返回 SOURCE_IS_INSTALLED_PLUGIN,此时不要用重试、改大小写、软链接或 junction 绕过,而应先把源码复制/迁出到独立作者目录再打包;工作目录之外的路径还可能返回 SOURCE_OUTSIDE_WORKDIR。完整流程见 插件打包、安装与验证(§7)。
清单本身也有体积门:ghost.json 源码读取上限为 256KB(ghost.ts),并且 Forge 在应用图标 overlay、重排 JSON 之后会再核一次安装侧上限,避免“打包成功、安装被拒”的口径漂移。
十、真实范例与契约优先级
要看真实完整范例,官方插件源码仓中的组织方式是:仓库根下每个含 ghost.json 的一级目录(如 cindy-art、cindy-github、cindy-web-search)都是一个已上架插件的全部源码,聊天卡片、面板、网络、设置页各类能力都有现成写法可对照;而 .tests、docs 这类没有 ghost.json 的目录属于仓库自身基础设施,不是插件。识别“一个目录是不是插件”,看根部有没有 ghost.json 就足够了。
需要理解宿主侧能力实现(某项能力的代发细节、校验器行为)时,可参考主仓 apps/desktop/src/main/cindy-brain/,但API 契约一律以随包手册为准。原文档对此给了明确理由:线上 main 分支可能领先或落后用户当前安装的主机版本,照 main 写码可能装进旧版就不工作。本仓库中该手册位于 apps/desktop/resources/system-skills/cindy-plugin-creator,结构章节即 plugin-structure.md。
十一、目录结构自查清单
打包前按顺序过一遍,能挡掉绝大多数返工:
ghost.json在包根,不是某个子目录;schemaVersion: 3时minCindyVersion已填且是真实依赖的首个正式版本。id符合小写字母/数字/连字符、1–32 位;command已声明且与常见插件不冲突。- 声明了
tools或cindy,就有真实的entry文件;main.js里能处理tool-call并回tool-result。 icon指向的文件存在、扩展名在白名单内、体积不超过 512KB;若用了 scaffold 且没换图,记得那还是占位图。- 声明
locales时en.json一定存在;所有 key 都能在当前清单里找到对应项,没有未知字段与保留键。 - 声明
node时node/worker.cjs存在、扩展名是.js/.cjs、protocol只有两个合法值、entries不超过 4 条且不重复。 - 声明
panel.html、mainView.html、taskView.html、settingsHtml时,对应文件都在包内且是普通文件(不是符号链接)。 panel.position: "tab"时已移除minWidth/defaultFraction/systemButtons。- 所有路径都是“正斜杠分段、无
..、无盘符、无空段”的安全相对路径。 - 需要随包可执行文件时,打包前已设好执行位。
把这些条目和 Forge 的 ENTRY_MISSING / MANIFEST_INVALID / SOURCE_IS_INSTALLED_PLUGIN / TOO_LARGE 错误码对应起来看,目录结构就不再是一张示意图,而是一份可被机器逐条验证的契约。