Goods 注册协议

window.qqqGaea.register(def) — 唯一入口。一切 goods 经此注册到 IDE。

注册对象字段

字段	类型	必填	默认	说明
`id`	string	✅	—	唯一标识，全小写短横线
`title`	string	✅	—	显示名
`version`	string		`'1.0.0'`	语义版本
`protoVer`	number		`1`	协议版本。v2 新增 type/lifecycle/audio
`type`	string		`'panel'`	`'panel'`(A区面板) / `'process'`(后台进程)
`lifecycle`	string		`'attached'`	仅 process-type：`'attached'` / `'independent'`
`audio`	object		`{mode:'ide'}`	音量策略：`{mode:'ide'	'independent'}`
`process`	object		—	仅 process-type：`{script, runtime}`
`panel`	object		—	A 区面板：`{build(host,ctx)}` 或 `{url}`
`tabs`	object		—	X 区标签：`{id: {title, build(host,ctx)}}`
`services`	object		—	后台服务：`{name: {start(ctx), stop()}}`
`commands`	string[]		—	命令列表
`provides`	string[]		—	跨 goods 导出（预留）
`uses`	string[]		—	跨 goods 依赖（预留）

lifecycle 双轨（process-type goods）

模式	行为	主窗口关闭时	适用
`'attached'`	spawn 到当前进程树	`taskkill /F /T` 杀整棵树	依赖主窗口的工具
`'independent'`	detached spawn	也清理（`cleanupAllGaeaProcesses` 主动杀）	独立弹窗程序

audio 双轨

模式	行为	获取音量
`'ide'`	跟随 IDE 音量滑块	`qqqAudio.getVolume(id)` → 滑块值/100
`'independent'`	goods 自有音量	`qqqAudio.getVolume(id)` → `1.0`

IDE 自带音效（升级/子弹）经 getMainVolume() 读主路音量，播放统一走 bridge.audio.play（详参 audio-api.md）。

完整示例

process-type（后台进程）

// goods/kope-a/kope-a.js
(function () {
  'use strict';
  const DEF = {
    id: 'kope-a',
    title: 'kope-a',
    type: 'process',
    lifecycle: 'independent',
    audio: { mode: 'independent' },
    process: { script: 'goods/kope-a/q3.py', runtime: 'python' },
  };
  window.qqqGaea.register(DEF);
})();

panel-type（A 区面板）

// goods/rage/rage.js
window.qqqGaea.register({
  id: 'rage',
  title: 'Rage',
  panel: { build(host, ctx) { /* 构建 DOM */ } },
  tabs: { 'roam': { title:'Roam', build(host, ctx) {} } },
});

菜单集成（process-type goods）

menu-schema.js 的梦gaea 子菜单项需附加字段：

{
  label: 'kope-a',
  cmd: 'gaea.kopeA',
  hasGaeaProcess: 'kope-a',              // goods id
  gpScript: 'goods/kope-a/q3.py',        // 脚本路径（相对于 Data/webapp/）
  gpRuntime: 'python',                   // 运行时（python 或组件名）
  gpLifecycle: 'independent',            // lifecycle 模式
}

菜单渲染（shell-menu.js）自动读取这些字段生成启动/停止按钮 + 自启勾选框。

生命周期

register() → gaea-host 存 def → 若 process-type → 菜单行显示按钮
          → 自动调 qqqAudio.register(id, def)


remove()   → 停 services → 删 X区 tabs → 销毁 panel DOM
          → 调 qqqAudio.unregister(id)

文件布局（自包含）

server-app/goods/<id>/
├── <id>.js          ← goods 注册（浏览器加载）
├── q3.py            ← Python 脚本（gaea-process spawn）
└── assets/          ← 资源文件（音效等）

一个 goods 的所有文件在同一目录下。u 管线热更覆盖整个 goods/ 目录。

协议版本兼容

v1 goods（无 protoVer）永远可用 — host 自动映射旧字段
v2 goods 声明 protoVer: 2 使用新字段（type/lifecycle/audio）
协议版本 > host 版本 → 跳过注册 + console.warn

goods-protocol