cortico-world-image 0.1.3 → 0.2.0

package/README.md

@@ -2,11 +2,11 @@
 
 给 Coopanion 桌宠加两件事：**调用图片生成 API 画图，并把图交回对话**；以及**把本地任意一张图贴进控制台的「对话」页**——后者靠一套自愈补丁给桌宠加一个 `pet_show_image` 工具，程序自动更新把这些文件覆写回原样之后，扩展下次启动会自己补回来。
 
-这是一个 `cortico` 的 **World 扩展**（`kind: world`，`api: 5`），只补一个 `image` 世界，
+这是一个 `cortico` 的 **World 扩展**（`kind: world`，`api: 6`），只补一个 `image` 世界，
 不依赖任何第三方 npm 包（纯 ESM JS + Node 内置模块）。
 
 > **性质说明**：这是给 Coopanion 写的**非官方**扩展，走的是框架公开的扩展接口
-> （`kind: world` + `consoleClient` 面板）。唯一伸手动别人的地方是「对话页发图」那一节的
+> （`kind: world` + `webUiClient` 面板 + 必需的 `describe.json` 自描述）。唯一伸手动别人的地方是「对话页发图」那一节的
 > 自愈补丁——它按锚点改写安装目录下的几个文件（`resources/app` 里的浏览器 bundle、桌宠包
 > 的 `src/*.ts`，以及可选的第三方 QQ 扩展），改之前一律留 `.coopanion-orig` 备份，
 > 程序自动更新覆写后会自己补回来，细节与还原方式都在那一节里。不愿意让脚本动这些文件，
@@ -178,10 +178,10 @@
 `ws://127.0.0.1:17788/ws/providers/world%3Adesktop-pet/panels/chat` 发 `{"t":"hello"}` 会收到
 `init`（历史 267 项），桌宠说话也会收到 `item {kind:'say',…}`。**Ctrl+F5 硬刷新一次**就恢复了。
 
-还有一条是我们这边造成的：扩展面板脚本由服务端按 `/assets/extensions/<包>/<版本>/console.js`
+还有一条是我们这边造成的：扩展面板脚本由服务端按 `/assets/extensions/<包>/<版本>/webui.js`
 分配，响应头是 `Cache-Control: public, max-age=31536000, immutable`，而 URL 里的版本号来自
 `package.json`。所以**改了面板 UI 却没抬版本号时，浏览器会一直用旧脚本**（看不到新按钮）。
-改了 `dist/console.js` 就顺手把 `version` 抬一格，或者让用户硬刷新。
+改了 `dist/webui.js` 就顺手把 `version` 抬一格，或者让用户硬刷新。
 
 **程序内那个控制台窗口更顽固**（Coopanion.exe 自己的窗口，不是外部浏览器）：它是长驻的 Chromium
 渲染进程，磁盘缓存在 `<安装>\data\Cache`，而 `immutable` 让它在新鲜期内**连重启都不回源**。
@@ -192,9 +192,9 @@
 修法是抬版本 + 重启，主程序会在 Core 就绪时自动重载控制台外壳（
 `resources\app\app\main.cjs:285` `if (settings) settings.loadURL(consoleUrl());`）：
 
-1. 把 `package.json` 的 `version` 抬一格（例如 `0.1.2` → `0.1.3`）；
+1. 把 `package.json` 的 `version` 抬一格（例如 `0.1.3` → `0.1.4`）；
 2. 重启控制台（状态页「重启控制台」或 `node tools/patch.mjs --restart`）；
-3. 程序内窗口自动重载 → 新的 URL `/assets/extensions/cortico-world-image/0.1.3/console.js`
+3. 程序内窗口自动重载 → 新的 URL `/assets/extensions/cortico-world-image/0.2.0/webui.js`
    取到新脚本，旧 URL 立刻变 404。
 
 不想抬版本也行，但要**先完全退出程序**再删缓存目录：`<安装>\data\Cache`、
@@ -230,7 +230,7 @@ registry 上有版本时直接从 npm 装；想自己改代码、或者 `npm vie
 或者用命令行，在 `data/extensions` 目录里（`extensions/package.json` 所在处）执行：
 
 ```powershell
-pnpm add cortico-world-image --ignore-workspace        # 想钉住版本就写 cortico-world-image@0.1.3
+pnpm add cortico-world-image --ignore-workspace        # 想钉住版本就写 cortico-world-image@0.1.4
 ```
 
 装完重启。升级同理：重跑一遍（控制台的「扩展」页会显示已装版本与最新版本），装完同样要重启。
@@ -341,7 +341,7 @@ pnpm add "D:\path\to\cortico-world-image" --ignore-workspace
 走完「落盘 → 索引 → 面板取图 → 缩略图显示」整条路。看不到这张图，说明是扩展或面板的问题，
 不是图片接口的问题。
 
-开发侧一共有四份检查脚本，外加一份发布前自检。
+开发侧一共有五份检查脚本，外加一份发布前自检。
 
 不碰 DOM 的那份覆盖模块形状、dry-mount 那套判据、工具回执、索引与两个面板的挂载（自带假 DOM）：
 
@@ -361,6 +361,16 @@ node --experimental-transform-types tools/drymount.mts
 > 参数属性（报 `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`），所以必须带
 > `--experimental-transform-types`（node 22.6+）。带上这个开关就不需要任何额外的 loader。
 
+框架 0.2 起每个扩展还要带一份**自描述**（`cortico.describe` → `describe.json`：工具表、事件表，
+以及环境提示词模板的原文）。这份脚本按同一套判据从定义重新生成一遍，跟包里那份逐字比对：
+
+```powershell
+node --experimental-transform-types tools/describe.mts          # 生成 / 刷新 describe.json
+node --experimental-transform-types tools/describe.mts --check  # 只核对，不写盘
+```
+
+改了工具描述、`describe.events` 或 `ENV_PROMPT.md` 之后要重新生成一次，否则发布前自检会拦下来。
+
 第三份会**真的联网画一张图**：拿部署里已有端点的密钥（只读那份 `.env`，不打印密钥），
 走完「工具回执带图 → 落盘 → 索引 → 面板取图 → 状态页读数」整条路，图存在临时目录里：
 
@@ -379,10 +389,11 @@ node tools/live.mjs                                       # 可加 LIVE_BASE_URL
 node tools/patch.mjs
 ```
 
-第五份是**发布前自检**：按宿主 `manifest.ts` 的同一套规则验 `package.json`（`type: module`、
-`cortico.api` 是否等于当前框架的 `world` 契约、`consoleClient` 是否真在包里、keywords 里有没有
+还有一份是**发布前自检**：按宿主 `manifest.ts` 的同一套规则验 `package.json`（`type: module`、
+`cortico.api` 是否等于当前框架的 `world` 契约、`webUiClient` 与 `describe` 是否真在包里、keywords 里有没有
 `cortico-world`）、按 `files` 展开一遍发布物、扫本机路径与私有端点之类的痕迹、逐个 `node --check`，
-然后自动跑上面的 `check.mjs`（找得到本机 Coopanion 安装时连 `patch.mjs` 自测与 `drymount.mts` 一起跑）。
+然后自动跑上面的 `check.mjs`（找得到本机 Coopanion 安装时连 `patch.mjs` 自测、`drymount.mts`
+与 `describe.mts --check` 一起跑）。
 
 ```powershell
 node tools/prepublish.mjs                              # 或 npm run selfcheck
@@ -396,7 +407,7 @@ node tools/prepublish.mjs --only-static                # 只做静态检查
 
 ```
 cortico-world-image/
-├─ package.json        # cortico: { kind: world, api: 5, consoleClient: dist/console.js }
+├─ package.json        # cortico: { kind: world, api: 6, webUiClient: dist/webui.js, describe: describe.json }
 ├─ README.md
 ├─ PUBLISH.md          # 发布流程（维护者用，不打进 npm 包）
 ├─ ENV_PROMPT.md       # 随环境提示词交给桌宠的说明（含 {{image.dir}} / {{image.ready}} 占位符）
@@ -409,9 +420,11 @@ cortico-world-image/
 │  ├─ api.js           # OpenAI 兼容客户端的取图/落盘/错误归一化
 │  ├─ gallery.js       # 作品仓库：目录 + index.json
 │  └─ png.js           # 零依赖 PNG 编码器 + 自检样图
-├─ dist/console.js     # 浏览器侧面板 bundle（export default { panels })
+├─ describe.json       # 自描述（框架 0.2 起必需）：工具表、事件表、环境提示词原文
+├─ dist/webui.js       # 浏览器侧面板 bundle（export default { panels })
 └─ tools/
    ├─ check.mjs        # 离线检查（自带假 DOM）
+   ├─ describe.mts     # 生成 / 核对 describe.json（--check 只核对）
    ├─ drymount.mts     # 用框架自带判据跑 dry-mount
    ├─ live.mjs         # 联网真画一张（自测整条链路）
    ├─ patch.mjs        # 对话页发图补丁：自测 / --apply / --backups / --restore / --restart
@@ -437,7 +450,7 @@ cortico-world-image/
 这个仓库同时就是 npm 包 `cortico-world-image` 的源码。发一版的流程：
 
 1. 改完代码、跑完自检（`node tools/prepublish.mjs --app <安装目录>\resources\app` 全绿）；
-2. 抬 `package.json` 的 `version`（改了 `dist/console.js` 必须抬，否则浏览器缓存旧脚本）；
+2. 抬 `package.json` 的 `version`（改了 `dist/webui.js` 必须抬，否则浏览器缓存旧脚本）；
 3. 把本仓库整份同步到发布目录（一份纯产物副本，`npm publish` 的根）；
 4. 提交并推进 GitHub；
 5. 在发布目录里 `npm publish --registry https://registry.npmjs.org/`。

package/describe.json

@@ -0,0 +1,132 @@
+{
+  "tools": [
+    {
+      "name": "image_draw",
+      "description": "Draw a picture from a text description through the configured image API. The picture is saved to disk, attached to this conversation so you can see it, and shown in the Image Studio console page. The reply carries the absolute file path; hand that path to a channel tool such as qq_send_image to actually deliver the picture to someone.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "description": "What to draw: subject, style, composition, lighting. Any language."
+          },
+          "note": {
+            "type": "string",
+            "description": "Short label for this picture in the studio list."
+          },
+          "size": {
+            "type": "string",
+            "description": "Override the configured size, e.g. 1024x1024 or 1024x1536."
+          },
+          "quality": {
+            "type": "string",
+            "description": "Override the configured quality, e.g. low / medium / high."
+          }
+        },
+        "required": [
+          "prompt"
+        ]
+      },
+      "tags": [
+        "act"
+      ],
+      "summary": {
+        "zh": "按一段文字描述画一张新图，存到磁盘、贴进对话，并显示在作品页。",
+        "en": "Draw a new picture from a text description, save it to disk and show it in the conversation."
+      }
+    },
+    {
+      "name": "image_edit",
+      "description": "Redraw an existing local picture with the image API, following a text instruction. `image` takes an absolute file path, or a picture id from image_gallery. Works with endpoints that implement /images/edits (multipart upload) and with those that take a base64 `image` field on /images/generations instead (e.g. Aliyun Bailian).",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "prompt": {
+            "type": "string",
+            "description": "What to change or how to restyle it."
+          },
+          "image": {
+            "type": "string",
+            "description": "Absolute path of the source picture, or a picture id from image_gallery."
+          },
+          "note": {
+            "type": "string",
+            "description": "Short label for the result in the studio list."
+          },
+          "size": {
+            "type": "string",
+            "description": "Override the configured size."
+          },
+          "quality": {
+            "type": "string",
+            "description": "Override the configured quality."
+          }
+        },
+        "required": [
+          "prompt",
+          "image"
+        ]
+      },
+      "tags": [
+        "act"
+      ],
+      "summary": {
+        "zh": "按一句指令改一张已有的本地图，结果同样落盘并贴进对话。",
+        "en": "Redraw an existing local picture following a text instruction."
+      }
+    },
+    {
+      "name": "image_gallery",
+      "description": "List pictures drawn so far, newest first, with their ids and absolute file paths. Ids can be handed to image_show.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "description": "How many to list, 1-50. Defaults to 12."
+          }
+        },
+        "required": []
+      },
+      "tags": [
+        "read"
+      ],
+      "summary": {
+        "zh": "列出已经画好的图，最新的在前，带编号与绝对路径。",
+        "en": "List pictures drawn so far, newest first, with their ids and absolute paths."
+      }
+    },
+    {
+      "name": "image_show",
+      "description": "Put an existing picture back in front of the user: it is re-attached to this conversation and highlighted in the Image Studio console page. Use it to look at or talk about an older picture again.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Picture id from image_gallery, or its absolute path."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "tags": [
+        "speak"
+      ],
+      "summary": {
+        "zh": "把一张已有的图重新贴回对话，并在作品页高亮。",
+        "en": "Put an existing picture back in front of the user."
+      }
+    }
+  ],
+  "events": [],
+  "prompts": [
+    {
+      "key": "worlds.image.envPrompt",
+      "title": "环境说明（图片工坊）",
+      "role": "envPrompt",
+      "content": "你可以作画。这一节说明工具箱和规矩。\n\n## 四个工具\n\n- `image_draw`：按一段文字描述画一张新图。图会存到磁盘、附加进本次对话（你自己看得到）、并显示在控制台「图片工坊 → 作品」页。\n- `image_edit`：拿一张已有的图按指令改（换风格、改细节）。`image` 给绝对路径，或 `image_gallery` 里的编号。服务端支不支持改图由接口决定，报错就照实告诉用户。\n- `image_gallery`：列出画过的图，最新的在前，带编号和绝对路径。编号可以交给 `image_show` 或 `image_edit`。\n- `image_show`：把一张旧图重新放回眼前（重新附加进对话，并在作品页高亮）。\n\n图片保存目录：`{{image.dir | 尚未确定；先看控制台「图片工坊 → 状态」。}}`\n\n当前接口状态：`{{image.ready | 未知。不确定就别调用，先告诉用户去控制台「图片工坊 → 状态」看看。}}`\n\n## 规矩\n\n1. **别每轮都画。** 用户明确想看/想让你画，或者确实需要一张图来解释、来送人，才调用。闲聊、讨论、解释概念都不需要配图。\n2. **一次画一张。** 想要不同方向就画一张、看一眼、再决定要不要重画或改。不要一次调好几个 `image_draw` 碰运气。\n3. **描述要具体。** 主体、画风、构图、光线、色调、背景，一句到位；别只给两三个词，也别把整段聊天记录塞进去。\n4. **说人话，不念路径。** 回执里的绝对路径是给工具用的，不是给用户看的。画完就用一句自然的话告诉用户画了什么，像 `pet_say` 那样说话。不要把路径、编号、`blobs`、JSON 念出来，也不要贴 Markdown 图片语法。\n5. **发到别处要另走一步。** 图默认只在你自己的界面里。\n   - 想让主人在控制台的「对话」页看到它，画完之后再调 `pet_show_image`：`path` 填 `image_draw` 回执里的绝对路径，`caption` 可选（一句配文）。它只贴图、不出声，也不会引发语音。\n   - 要发到 QQ 会话，画完之后再调 `qq_send_image`，`image` 参数填 `image_draw` 回执里那个绝对路径。\n6. **失败就停。** 如果回执说没配密钥、接口报错、超时，不要换个说法反复重试。把情况告诉用户，让他去控制台「图片工坊 → 状态」里填密钥或改接口地址。\n7. **别凭空说画好了。** 只有工具回执真的带着图回来，才算画好了。\n"
+    }
+  ]
+}

package/dist/{console.js → webui.js}

@@ -1,7 +1,7 @@
 /**
  * 图片工坊的控制台面板（浏览器侧 bundle）。
  *
- * 宿主按 `/assets/extensions/<包>/<版本>/dist/console.js` 取这个文件，
+ * 宿主按 `/assets/extensions/<包>/<版本>/dist/webui.js` 取这个文件，
  * 直接 `import()` 它的 default 导出；所以它是纯浏览器 ES 模块：
  * 不 import 任何东西（`cortico/*` 在这里只允许 `import type`），只用 ctx.ui。
  */

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "cortico-world-image",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Image Studio（图片工坊）—— 给 Coopanion 桌宠的 cortico World 扩展：用任意 OpenAI 兼容的图片接口画图/改图、落盘成作品库、把图贴进控制台「对话」页，并自带一套自动重打的自愈补丁。 / A cortico World extension that draws through any OpenAI-compatible image API, keeps pictures on disk and shows them in the console.",
+  "description": "【注意：未升级0.2.0以上版本请安装本插件的上一个历史版本】Image Studio（图片工坊）—— 给 Coopanion 桌宠的 cortico World 扩展：用任意 OpenAI 兼容的图片接口（包括阿里）画图/改图、落盘成作品库、把图贴进控制台「对话」页，并自带一套自动重打的自愈补丁。 / A cortico World extension that draws through any OpenAI-compatible image API, keeps pictures on disk and shows them in the console.",
   "license": "MIT",
   "author": "lostdegree",
   "homepage": "https://github.com/Lostdegree/cortico-world-image#readme",
@@ -34,6 +34,7 @@
     "src",
     "dist",
     "tools",
+    "describe.json",
     "ENV_PROMPT.md",
     "README.md"
   ],
@@ -46,8 +47,9 @@
   },
   "cortico": {
     "kind": "world",
-    "api": 5,
+    "api": 6,
     "displayName": "图片工坊",
-    "consoleClient": "dist/console.js"
+    "webUiClient": "dist/webui.js",
+    "describe": "describe.json"
   }
 }

package/src/chat-image-patch.js

@@ -320,22 +320,32 @@ const QQ_SEND_NEW = 'const p = resolveLocalImagePath(image, this.config.memoryDi
 const QQ_VIEW_OLD = "const p = isAbsolute(url) ? url : join(this.packageDir || '.', url);";
 const QQ_VIEW_NEW = 'const p = resolveLocalImagePath(url, this.config.memoryDir, this.packageDir);';
 
-/** 工具说明里那三处「相对扩展目录」要跟着改成「相对桌宠工作区」——模型只看得到说明。 */
+/**
+ * 工具说明里那三处要跟着改成「相对桌宠工作区」——模型只看得到说明。
+ * 上游爱改措辞（0.1.16 就把 image 那句换成了「如 /home/user/pics/a.png」），所以每条列出
+ * 见过的旧写法：一条都对不上只跳过、不判失败；整条补丁一句都认不出来才算版本变了。
+ */
 const QQ_HINTS = [
   {
-    from: "description: '本地文件路径（绝对路径，或相对扩展目录）或 http(s) 链接。'",
+    from: [
+      "description: '本地文件路径（绝对路径，或相对扩展目录）或 http(s) 链接。'",
+      "description: '本地文件路径（如 /home/user/pics/a.png）或 http(s) 链接。'",
+    ],
     to: "description: '本地文件路径（绝对路径，或相对桌宠工作区的路径，如 blobs/xx.jpg）或 http(s) 链接。'",
   },
   {
-    from: '或本地文件路径；给了就不再翻缓冲。',
+    from: ['或本地文件路径；给了就不再翻缓冲。'],
     to: '或本地文件路径（绝对路径，或相对桌宠工作区的路径，如 blobs/xx.jpg）；给了就不再翻缓冲。',
   },
   {
-    from: '给某个会话发一张图。`image` 给本地文件路径或 http(s) 链接（本机下载后再发），二者挑一个。',
+    from: ['给某个会话发一张图。`image` 给本地文件路径或 http(s) 链接（本机下载后再发），二者挑一个。'],
     to: '给某个会话发一张图。`image` 给本地文件路径（绝对路径，或相对桌宠工作区的路径，如 blobs/xx.jpg）或 http(s) 链接（本机下载后再发），二者挑一个。',
   },
 ];
 
+/** 这条说明还没改成我们的说法、而且上游还有它认得的旧写法 → 需要动手。 */
+const hintNeedsWork = (text, h) => !text.includes(h.to) && [].concat(h.from).some((from) => text.includes(from));
+
 /**
  * 每个补丁：`file` 是绝对路径，`done` 说这段原文是不是已经改过了，
  * `apply` 返回新文本或 `{ error }`。全部按顺序跑，互不依赖。
@@ -467,14 +477,26 @@ export function rulesFor(id) {
       };
     case 'qq-image-hints':
       return {
-        done: (text) => QQ_HINTS.every((h) => text.includes(h.to)),
+        // 已经有一处是我们的说法，且没有哪处还留着认得的旧写法 → 不用再管（上游换掉的措辞不再拖住这条）。
+        done: (text) => QQ_HINTS.some((h) => text.includes(h.to)) && QQ_HINTS.every((h) => !hintNeedsWork(text, h)),
         apply: (text) => {
           let work = text;
+          let recognized = 0;
           for (const h of QQ_HINTS) {
-            const out = swap(work, h.from, h.to);
-            if (out === null) return { error: `工具说明对不上：${h.from.slice(0, 40)}` };
-            work = out;
+            if (work.includes(h.to)) {
+              recognized += 1;
+              continue;
+            }
+            for (const from of [].concat(h.from)) {
+              const out = swap(work, from, h.to);
+              if (out !== null) {
+                work = out;
+                recognized += 1;
+                break;
+              }
+            }
           }
+          if (recognized === 0) return { error: `工具说明已大改，一句都认不出来：${[].concat(QQ_HINTS[0].from)[0].slice(0, 40)}` };
           return { text: work };
         },
       };

package/src/definition.js

@@ -3,6 +3,7 @@
  * 所以构造函数必须是纯的（不建目录、不发请求、不读密钥也行）。
  */
 import { DEFAULTS, ID, LABEL } from './config.js';
+import { toolDescribe } from './tools.js';
 import { ImageWorld } from './world.js';
 
 export const imageDefinition = {
@@ -10,6 +11,14 @@ export const imageDefinition = {
   label: LABEL,
   /** `worlds.image` 段的默认值；启用与否由部署决定，定义里恒为 false。 */
   defaults: () => structuredClone(DEFAULTS),
+  /**
+   * 自描述（框架 0.2 起必需）：全部工具与会推出的事件，给人和扩展市场看，不进提示词。
+   * 工具表来自 src/tools.js，与实例 tools() 同一份；这个 World 不推事件（面板推送走 stream，不算事件）。
+   */
+  describe: {
+    tools: toolDescribe(),
+    events: [],
+  },
   preflight: () => {
     if (typeof fetch !== 'function' || typeof FormData !== 'function' || typeof Blob !== 'function') {
       throw new Error('图片工坊需要 Node 22+ 的全局 fetch / FormData / Blob');

package/src/index.js

@@ -1,6 +1,6 @@
 /**
  * 扩展入口：默认导出必须是 WorldDefinition。
- * `cortico.<kind> = world`、`api = 5` 与 `keywords` 里的 `cortico-world` 见 package.json。
+ * `cortico.<kind> = world`、`api = 6` 与 `keywords` 里的 `cortico-world` 见 package.json。
  */
 import definition, { imageDefinition } from './definition.js';
 

package/src/tools.js

@@ -0,0 +1,106 @@
+/**
+ * 工具声明与自描述共用同一份数据。
+ *
+ * `tools()` 拿它加 handler，`describe.tools`（框架 0.2 起必需）直接把它去掉 handler 交出去，
+ * 两边就不会漂移：框架只核对实例给出的工具**名**都在 describe.tools 里，
+ * 描述或参数写岔了它看不出来，所以只能靠这里共用一份。
+ *
+ * 每条里 `summary` 是给人和扩展市场看的一句话（`{ zh, en }`），不进提示词，也不进 `tools()`。
+ */
+
+export const TOOL_SPECS = [
+  {
+    name: 'image_draw',
+    description: 'Draw a picture from a text description through the configured image API. '
+      + 'The picture is saved to disk, attached to this conversation so you can see it, and shown in the Image Studio console page. '
+      + 'The reply carries the absolute file path; hand that path to a channel tool such as qq_send_image to actually deliver the picture to someone.',
+    tags: ['act'],
+    parameters: {
+      type: 'object',
+      properties: {
+        prompt: {
+          type: 'string',
+          description: 'What to draw: subject, style, composition, lighting. Any language.',
+        },
+        note: {
+          type: 'string',
+          description: 'Short label for this picture in the studio list.',
+        },
+        size: {
+          type: 'string',
+          description: 'Override the configured size, e.g. 1024x1024 or 1024x1536.',
+        },
+        quality: {
+          type: 'string',
+          description: 'Override the configured quality, e.g. low / medium / high.',
+        },
+      },
+      required: ['prompt'],
+    },
+    summary: {
+      zh: '按一段文字描述画一张新图，存到磁盘、贴进对话，并显示在作品页。',
+      en: 'Draw a new picture from a text description, save it to disk and show it in the conversation.',
+    },
+  },
+  {
+    name: 'image_edit',
+    description: 'Redraw an existing local picture with the image API, following a text instruction. '
+      + '`image` takes an absolute file path, or a picture id from image_gallery. '
+      + 'Works with endpoints that implement /images/edits (multipart upload) and with those that take a base64 `image` field on /images/generations instead (e.g. Aliyun Bailian).',
+    tags: ['act'],
+    parameters: {
+      type: 'object',
+      properties: {
+        prompt: { type: 'string', description: 'What to change or how to restyle it.' },
+        image: { type: 'string', description: 'Absolute path of the source picture, or a picture id from image_gallery.' },
+        note: { type: 'string', description: 'Short label for the result in the studio list.' },
+        size: { type: 'string', description: 'Override the configured size.' },
+        quality: { type: 'string', description: 'Override the configured quality.' },
+      },
+      required: ['prompt', 'image'],
+    },
+    summary: {
+      zh: '按一句指令改一张已有的本地图，结果同样落盘并贴进对话。',
+      en: 'Redraw an existing local picture following a text instruction.',
+    },
+  },
+  {
+    name: 'image_gallery',
+    description: 'List pictures drawn so far, newest first, with their ids and absolute file paths. '
+      + 'Ids can be handed to image_show.',
+    tags: ['read'],
+    parameters: {
+      type: 'object',
+      properties: {
+        limit: { type: 'integer', description: 'How many to list, 1-50. Defaults to 12.' },
+      },
+      required: [],
+    },
+    summary: {
+      zh: '列出已经画好的图，最新的在前，带编号与绝对路径。',
+      en: 'List pictures drawn so far, newest first, with their ids and absolute paths.',
+    },
+  },
+  {
+    name: 'image_show',
+    description: 'Put an existing picture back in front of the user: it is re-attached to this conversation and highlighted in the Image Studio console page. '
+      + 'Use it to look at or talk about an older picture again.',
+    tags: ['speak'],
+    parameters: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Picture id from image_gallery, or its absolute path.' },
+      },
+      required: ['id'],
+    },
+    summary: {
+      zh: '把一张已有的图重新贴回对话，并在作品页高亮。',
+      en: 'Put an existing picture back in front of the user.',
+    },
+  },
+];
+
+/** 给 describe 的工具表：去掉 handler，保留发给模型的字段与给人看的一句话。 */
+export const toolDescribe = () => TOOL_SPECS.map(({ name, description, parameters, tags, summary }) => ({
+  name, description, parameters, tags, summary,
+}));

package/src/world.js

@@ -18,6 +18,7 @@ import { applyChatImagePatches, consolePort, patchBackupStatus, requestConsoleRe
 import { DEFAULTS, ID, configGroup, text } from './config.js';
 import { Gallery } from './gallery.js';
 import { samplePng } from './png.js';
+import { TOOL_SPECS } from './tools.js';
 
 /** 扩展包自带的模板；部署侧的覆盖文件由框架自己接在后面。 */
 const ENV_PROMPT_FILE = fileURLToPath(new URL('../ENV_PROMPT.md', import.meta.url));
@@ -235,85 +236,25 @@ export class ImageWorld {
   // -------------------------------------------------------------------------
 
   tools() {
-    return [
-      {
-        name: 'image_draw',
-        description: 'Draw a picture from a text description through the configured image API. '
-          + 'The picture is saved to disk, attached to this conversation so you can see it, and shown in the Image Studio console page. '
-          + 'The reply carries the absolute file path; hand that path to a channel tool such as qq_send_image to actually deliver the picture to someone.',
-        tags: ['act'],
-        parameters: {
-          type: 'object',
-          properties: {
-            prompt: {
-              type: 'string',
-              description: 'What to draw: subject, style, composition, lighting. Any language.',
-            },
-            note: {
-              type: 'string',
-              description: 'Short label for this picture in the studio list.',
-            },
-            size: {
-              type: 'string',
-              description: 'Override the configured size, e.g. 1024x1024 or 1024x1536.',
-            },
-            quality: {
-              type: 'string',
-              description: 'Override the configured quality, e.g. low / medium / high.',
-            },
-          },
-          required: ['prompt'],
-        },
-        handler: async (args) => this.#draw(args ?? {}),
-      },
-      {
-        name: 'image_edit',
-        description: 'Redraw an existing local picture with the image API, following a text instruction. '
-          + '`image` takes an absolute file path, or a picture id from image_gallery. '
-          + 'Works with endpoints that implement /images/edits (multipart upload) and with those that take a base64 `image` field on /images/generations instead (e.g. Aliyun Bailian).',
-        tags: ['act'],
-        parameters: {
-          type: 'object',
-          properties: {
-            prompt: { type: 'string', description: 'What to change or how to restyle it.' },
-            image: { type: 'string', description: 'Absolute path of the source picture, or a picture id from image_gallery.' },
-            note: { type: 'string', description: 'Short label for the result in the studio list.' },
-            size: { type: 'string', description: 'Override the configured size.' },
-            quality: { type: 'string', description: 'Override the configured quality.' },
-          },
-          required: ['prompt', 'image'],
-        },
-        handler: async (args) => this.#edit(args ?? {}),
-      },
-      {
-        name: 'image_gallery',
-        description: 'List pictures drawn so far, newest first, with their ids and absolute file paths. '
-          + 'Ids can be handed to image_show.',
-        tags: ['read'],
-        parameters: {
-          type: 'object',
-          properties: {
-            limit: { type: 'integer', description: 'How many to list, 1-50. Defaults to 12.' },
-          },
-          required: [],
-        },
-        handler: async (args) => this.#list(args ?? {}),
-      },
-      {
-        name: 'image_show',
-        description: 'Put an existing picture back in front of the user: it is re-attached to this conversation and highlighted in the Image Studio console page. '
-          + 'Use it to look at or talk about an older picture again.',
-        tags: ['speak'],
-        parameters: {
-          type: 'object',
-          properties: {
-            id: { type: 'string', description: 'Picture id from image_gallery, or its absolute path.' },
-          },
-          required: ['id'],
-        },
-        handler: async (args) => this.#show(args ?? {}),
-      },
-    ];
+    // 声明在 src/tools.js，definition 的 describe.tools 用的是同一份（框架 0.2 起必需）。
+    return TOOL_SPECS.map(({ name, description, parameters, tags }) => ({
+      name,
+      description,
+      parameters,
+      tags,
+      handler: async (args) => this.#runTool(name, args ?? {}),
+    }));
+  }
+
+  /** 按名字把 handler 接到各工具的实现上；名字表就是 TOOL_SPECS。 */
+  async #runTool(name, args) {
+    switch (name) {
+      case 'image_draw': return await this.#draw(args);
+      case 'image_edit': return await this.#edit(args);
+      case 'image_gallery': return await this.#list(args);
+      case 'image_show': return await this.#show(args);
+      default: throw new Error(`未知工具：${name}`);
+    }
   }
 
   async #draw(args) {
@@ -541,7 +482,7 @@ export class ImageWorld {
   // 控制台
   // -------------------------------------------------------------------------
 
-  console(language = 'zh') {
+  webUi(language = 'zh') {
     this.language = language === 'en' ? 'en' : 'zh';
     const t = this.#text();
     const env = this.#envState();

package/tools/check.mjs

@@ -1,8 +1,8 @@
 /**
  * 图片工坊的离线检查。
  *
- * 不联网、不装 DOM：用一份假 DOM 把 dist/console.js 的两个面板真的挂起来跑，
- * 服务端那侧则直接调 ImageWorld 的工具与控制台方法。
+ * 不联网、不装 DOM：用一份假 DOM 把 dist/webui.js 的两个面板真的挂起来跑，
+ * 服务端那侧则直接调 ImageWorld 的工具与 WebUI 方法。
  *
  *   node tools/check.mjs
  */
@@ -368,7 +368,7 @@ try {
   check(world.id === definition.id, 'world.id 与 def.id 一致');
   check(typeof world.envPromptVars === 'function', '有 envPromptVars()');
   check(typeof world.tools === 'function', '有 tools()');
-  check(typeof world.console === 'function', '有 console()');
+  check(typeof world.webUi === 'function', '有 webUi()');
 
   section('工具声明');
   const tools = world.tools();
@@ -392,11 +392,11 @@ try {
   check(isAbsolute(String(vars?.['image.dir'] ?? '')), 'image.dir 是绝对路径', String(vars?.['image.dir']));
   check(typeof vars?.['image.ready'] === 'string' && vars['image.ready'] !== '', 'image.ready 非空', String(vars?.['image.ready']));
 
-  section('控制台声明（对齐 dry-mount）');
-  const declined = world.console('zh');
-  check(declined && typeof declined === 'object', 'console() 返回对象');
-  check(typeof declined.invoke === 'function', 'console().invoke 是函数');
-  check(typeof declined.stream === 'function', 'console().stream 是函数');
+  section('WebUI 声明（对齐 dry-mount）');
+  const declined = world.webUi('zh');
+  check(declined && typeof declined === 'object', 'webUi() 返回对象');
+  check(typeof declined.invoke === 'function', 'webUi().invoke 是函数');
+  check(typeof declined.stream === 'function', 'webUi().stream 是函数');
   const panelIds = (declined.panels ?? []).map((p) => p.id);
   check(panelIds.length > 0, '声明了面板');
   check(panelIds.every((id) => /^[a-z0-9-]+$/.test(id)), '面板 id 合法', panelIds.join(','));
@@ -583,8 +583,8 @@ try {
   check(stored?.value === '', 'clearKey 把值写空');
 
   section('浏览器面板 bundle');
-  const consoleSrc = readFileSync(join(pkgDir, 'dist', 'console.js'), 'utf8');
-  const bundle = (await import(pathToFileURL(join(pkgDir, 'dist', 'console.js')).href)).default;
+  const webUiSrc = readFileSync(join(pkgDir, 'dist', 'webui.js'), 'utf8');
+  const bundle = (await import(pathToFileURL(join(pkgDir, 'dist', 'webui.js')).href)).default;
   check(!!bundle?.panels?.gallery?.mount, 'bundle 提供 gallery.mount');
   check(!!bundle?.panels?.status?.mount, 'bundle 提供 status.mount');
   const declaredIds = panelIds.slice().sort().join(',');
@@ -593,14 +593,14 @@ try {
 
   section('文案完整性');
   const dictKeys = (name) => {
-    const start = consoleSrc.indexOf(`const ${name} = {`);
-    const end = consoleSrc.indexOf('\n};', start);
-    const body = consoleSrc.slice(start, end);
+    const start = webUiSrc.indexOf(`const ${name} = {`);
+    const end = webUiSrc.indexOf('\n};', start);
+    const body = webUiSrc.slice(start, end);
     return new Set([...body.matchAll(/^\s*([A-Za-z0-9_]+):/gm)].map((m) => m[1]));
   };
   const zhKeys = dictKeys('ZH');
   const enKeys = dictKeys('EN');
-  const usedKeys = new Set([...consoleSrc.matchAll(/\btx\.([A-Za-z0-9_]+)/g)].map((m) => m[1]));
+  const usedKeys = new Set([...webUiSrc.matchAll(/\btx\.([A-Za-z0-9_]+)/g)].map((m) => m[1]));
   for (const key of usedKeys) {
     if (!zhKeys.has(key)) fail('中文文案缺键', `tx.${key}`);
     if (!enKeys.has(key)) fail('英文文案缺键', `tx.${key}`);
@@ -609,6 +609,54 @@ try {
   for (const key of enKeys) if (!zhKeys.has(key)) fail('英文有、中文没有的键', key);
   pass(`文案键：中文 ${zhKeys.size}、英文 ${enKeys.size}，代码用到 ${usedKeys.size}`);
 
+  section('契约与自描述（框架 0.2）');
+  const pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+  const manifest = pkg.cortico ?? {};
+  check(pkg.version === '0.2.0', 'version 抬到 0.2.0', String(pkg.version));
+  check(manifest.api === 6, 'cortico.api 是 6', String(manifest.api));
+  check(manifest.webUiClient === 'dist/webui.js', 'webUiClient 指向 dist/webui.js', String(manifest.webUiClient));
+  check(manifest.describe === 'describe.json', 'describe 指向 describe.json', String(manifest.describe));
+  for (const need of ['dist', 'describe.json']) {
+    check((pkg.files ?? []).includes(need), `files 带上 ${need}`);
+  }
+  check(existsSync(join(pkgDir, 'dist', 'webui.js')), 'dist/webui.js 在包里');
+  check(!existsSync(join(pkgDir, 'dist', 'console.js')), '旧的 dist/console.js 已经清掉');
+  check(/export default/.test(webUiSrc), '面板脚本有 export default');
+  check(!/^\s*import\s/m.test(webUiSrc), '面板脚本不 import 任何东西');
+  check(/\bctx\.ui\./.test(webUiSrc) && /\bctx\.invoke\(/.test(webUiSrc), '面板只用 ctx.ui / ctx.invoke');
+
+  const describeDecl = definition.describe;
+  check(!!describeDecl, 'definition 带上 describe');
+  check(Array.isArray(describeDecl?.tools), 'describe.tools 是数组');
+  check(Array.isArray(describeDecl?.events), 'describe.events 是数组');
+  const descToolNames = (describeDecl?.tools ?? []).map((t) => t.name);
+  check(
+    descToolNames.join(',') === names.slice().join(','),
+    'describe 里的工具名与 tools() 完全一致',
+    `${descToolNames.join(',')} vs ${names.join(',')}`,
+  );
+
+  const describePath = manifest.describe ?? 'describe.json';
+  let describeFile = null;
+  try {
+    describeFile = JSON.parse(readFileSync(join(pkgDir, describePath), 'utf8'));
+    pass(`${describePath} 是合法 JSON`);
+  } catch (err) {
+    fail(`${describePath} 读不了或不是合法 JSON`, String(err?.message ?? err));
+  }
+  if (describeFile) {
+    const fileToolNames = (describeFile.tools ?? []).map((t) => t.name);
+    check(
+      fileToolNames.join(',') === names.slice().join(','),
+      'describe.json 里的工具名与定义一致',
+      `${fileToolNames.join(',')} vs ${names.join(',')}`,
+    );
+    check((describeFile.events ?? []).length === (describeDecl?.events ?? []).length, 'describe.json 的事件条数与定义一致');
+    const envPrompt = (describeFile.prompts ?? []).find((p) => p.role === 'envPrompt');
+    check(!!envPrompt, 'describe.json 带上 envPrompt 角色');
+    check(/image_draw/.test(envPrompt?.content ?? ''), 'envPrompt 正文里有工具说明');
+  }
+
   section('作品页挂载');
   const gallery = makeEnv(world, 'gallery');
   bundle.panels.gallery.mount(gallery.ctx);
@@ -746,6 +794,28 @@ try {
   check(qqRules.done(qqPatched?.text ?? ''), '改完认成「已打过」（幂等）');
   check(qqPatched.text.includes("import { existsSync } from 'node:fs';"), '导入本来就够时不多改一行');
 
+  // 上游爱改工具说明的措辞（0.1.16 就把 image 那句换成了「如 /home/user/pics/a.png」）：
+  // 一条对不上不该让整条补丁失败；但一句都认不出来仍然要报。
+  const hintRules = patchMod.rulesFor('qq-image-hints');
+  check(typeof hintRules?.done === 'function' && typeof hintRules?.apply === 'function', 'QQ 说明补丁有 done/apply');
+  const hintFixture = [
+    "  parameters: [{ name: 'url', description: '可选：直接给图片链接（事件里带的图）或本地文件路径；给了就不再翻缓冲。' }],",
+    "  description: '给某个会话发一张图。`image` 给本地文件路径或 http(s) 链接（本机下载后再发），二者挑一个。',",
+    "  parameters: [{ name: 'image', description: '本地文件路径（如 /home/user/pics/a.png）或 http(s) 链接。' }],",
+    '',
+  ].join('\n');
+  check(!hintRules.done(hintFixture), '夹具还是「只认绝对路径」的说明（有东西可改）');
+  const hinted = hintRules.apply(hintFixture);
+  check(!hinted?.error, '上游换了说明措辞也照改，不报失败', String(hinted?.error ?? 'ok'));
+  check((hinted?.text ?? '').includes('或本地文件路径（绝对路径，或相对桌宠工作区的路径，如 blobs/xx.jpg）；给了就不再翻缓冲。'), '认得出的那两处照改');
+  check(!(hinted?.text ?? '').includes('相对扩展目录'), '旧说法不再残留在说明里');
+  check(hintRules.done(hinted?.text ?? ''), '改完认成「已打过」（幂等）');
+  const reworded = hintFixture.replace("'本地文件路径（如 /home/user/pics/a.png）或 http(s) 链接。'", "'图片本地路径或链接。'");
+  const rewordedOut = hintRules.apply(reworded);
+  check(!rewordedOut?.error && hintRules.done(rewordedOut?.text ?? ''), '上游整句换掉时跳过那一处，不算失败也不算没打', String(rewordedOut?.error ?? 'ok'));
+  check(Boolean(hintRules.apply('export const nope = 1;\n')?.error), '一句都认不出来时仍然报失败');
+  check(!hintRules.done('export const nope = 1;\n'), '文件整个换了写法时不谎报「已打过」');
+
   // pet_show_image 也要能认相对路径（按桌宠工作区解析）。
   const petSpecs = specs.filter((s) => s.id.startsWith('pet-workspace-'));
   check(petSpecs.length === 3 && petSpecs.every((s) => s.optional !== true), '桌宠工作区相对路径那 3 处是必备补丁', JSON.stringify(petSpecs.map((s) => s.id)));
@@ -833,7 +903,7 @@ try {
   check(Array.isArray(restored?.restored?.restored) && String(restored?.restored?.skipped ?? '').includes('COOPANION_CHAT_IMAGE_PATCH'), '检查模式下 restore 不动安装目录', JSON.stringify(restored?.restored));
   const st = await world.invoke('status', 'state', []);
   check(Array.isArray(st?.patch?.backups), '状态里能读到备份列表', JSON.stringify(st?.patch?.backups));
-  const badge = (world.console('zh').badges ?? []).find((b) => b.label === '发图补丁');
+  const badge = (world.webUi('zh').badges ?? []).find((b) => b.label === '发图补丁');
   check(!!badge, '控制台徽章里有「发图补丁」');
   check(badge?.value === '未检查', '检查模式下徽章显示「未检查」', String(badge?.value));
 

package/tools/describe.mts

@@ -0,0 +1,113 @@
+/**
+ * describe.json（框架 0.2 的自描述）生成与核对：
+ *   node --experimental-transform-types tools/describe.mts          生成（内容真变了才写盘）并核对
+ *   node --experimental-transform-types tools/describe.mts --check  只核对，不写盘
+ *
+ * 判据直接读这套安装里的框架源码（`<安装>/resources/app/build/cortico/src/extensions/`），不靠手抄：
+ * `parseExtensionManifest()` 过 manifest、`exportDescribe()` 从定义生成自描述、
+ * `checkDescribe()` 复核包里那份与代码一致、`dryMountWorld()` 在假部署里造实例查工具与配置路径。
+ * 框架位置按 `COOPANION_APP_ROOT` → 从本包往上找 `resources/app` 的顺序定位；
+ * 用 tsx 跑会因为 esbuild 起子进程被沙箱拦（spawn EPERM）；node 自带的类型擦除不吃参数属性，
+ * 所以必须带 --experimental-transform-types。
+ */
+import { existsSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const pkgDir = fileURLToPath(new URL('..', import.meta.url));
+const checkOnly = process.argv.includes('--check');
+const scratchDir = mkdtempSync(join(tmpdir(), 'image-describe-'));
+
+/** 找这套安装的 `resources/app`：显式变量优先，其次从本包目录往上找。 */
+function findAppRoot(): string {
+  const explicit = process.env.COOPANION_APP_ROOT;
+  if (explicit && existsSync(join(explicit, 'build', 'cortico', 'src', 'extensions', 'dry-mount.ts'))) return explicit;
+  let dir = pkgDir;
+  for (let i = 0; i < 8; i += 1) {
+    const cand = join(dir, 'resources', 'app');
+    if (existsSync(join(cand, 'build', 'cortico', 'src', 'extensions', 'dry-mount.ts'))) return cand;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '';
+}
+
+const appRoot = findAppRoot();
+if (!appRoot) {
+  console.error('找不到这套安装的 resources/app —— 用 COOPANION_APP_ROOT 指一下（例如 D:\\Coopanion\\resources\\app）');
+  process.exit(2);
+}
+const frameworkDir = join(appRoot, 'build', 'cortico', 'src', 'extensions');
+const { checkDescribe, exportDescribe, DEFAULT_DESCRIBE_FILE } = await import(pathToFileURL(join(frameworkDir, 'describe-export.ts')).href);
+const { EXTENSION_API_VERSIONS, parseExtensionManifest } = await import(pathToFileURL(join(frameworkDir, 'manifest.ts')).href);
+const { dryMountWorld } = await import(pathToFileURL(join(frameworkDir, 'dry-mount.ts')).href);
+
+let passed = 0;
+let warned = 0;
+let failed = 0;
+const ok = (line: string): void => { passed++; console.log(`  ok    ${line}`); };
+const bad = (line: string): void => { failed++; console.log(`  FAIL  ${line}`); };
+const hint = (line: string): void => { warned++; console.log(`  提醒  ${line}`); };
+
+try {
+  const manifest = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+  const { default: def } = await import(pathToFileURL(join(pkgDir, 'src', 'index.js')).href);
+  const opts = { scratchDir, packageDir: pkgDir };
+
+  console.log('manifest');
+  const parsed = parseExtensionManifest(manifest);
+  if (!parsed.ok) bad(`框架解析 manifest 失败：${parsed.reasons.join('；')}`);
+  else {
+    const expected = EXTENSION_API_VERSIONS[parsed.manifest.kind];
+    ok(`框架解析 manifest 通过（kind=${parsed.manifest.kind}，api=${parsed.manifest.api}，框架期望 ${expected}）`);
+    if (parsed.manifest.api !== expected) bad(`api=${parsed.manifest.api} 与框架的 ${expected} 不等，装配层会拒绝加载。`);
+    if (parsed.manifest.id !== undefined && def?.id !== parsed.manifest.id) {
+      bad(`manifest 里的 id（${parsed.manifest.id}）与 def.id（${def?.id}）不一致`);
+    }
+    const client = parsed.manifest.webUiClient;
+    if (client && !existsSync(join(pkgDir, client))) bad(`manifest 声明的 ${client} 不在包里`);
+    else if (client) ok(`manifest 声明的面板产物 ${client} 在包里`);
+    else hint('manifest 没有声明 webUiClient：这个 World 没有浏览器面板。');
+  }
+  for (const warning of parsed.warnings ?? []) hint(warning);
+
+  console.log('\n自描述');
+  const file = await exportDescribe('world', def, opts);
+  if (!file) {
+    bad('定义里没有 describe：框架 0.2 起每个 World 都要声明全部工具与事件。');
+  } else {
+    const rel = manifest.cortico?.describe ?? DEFAULT_DESCRIBE_FILE;
+    const target = join(pkgDir, rel);
+    const next = `${JSON.stringify(file, null, 2)}\n`;
+    const toolNames = (file.tools ?? []).map((tool) => tool.name);
+    ok(`定义生成的工具表：${toolNames.length ? toolNames.join(', ') : '(空)'}；事件表：${(file.events ?? []).length} 个`);
+    if (checkOnly) {
+      if (!existsSync(target)) bad(`${rel} 不存在（去掉 --check 生成它）`);
+      else ok(`${rel} 在包里（${readFileSync(target, 'utf8').length} 字节）`);
+    } else if (existsSync(target) && readFileSync(target, 'utf8') === next) {
+      ok(`${rel} 已是最新，未改动`);
+    } else {
+      writeFileSync(target, next);
+      ok(`写入 ${rel}（${next.length} 字节）`);
+    }
+    const report = await checkDescribe('world', def, manifest.cortico?.describe, opts);
+    for (const line of report.ok) ok(line);
+    for (const line of report.warnings) hint(line);
+    for (const line of report.failures) bad(line);
+  }
+
+  console.log('\n假部署装配');
+  const report = await dryMountWorld(def, { ...opts, hasWebUiClient: Boolean(manifest.cortico?.webUiClient) });
+  for (const line of report.ok) ok(line);
+  for (const line of report.warnings) hint(line);
+  for (const line of report.failures) bad(line);
+} catch (error) {
+  bad(`未捕获的异常：${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+} finally {
+  rmSync(scratchDir, { recursive: true, force: true });
+}
+
+console.log(`\n结果：${passed} 项通过，${warned} 个提醒，${failed} 个失败`);
+process.exit(failed === 0 ? 0 : 1);

package/tools/drymount.mts

@@ -100,7 +100,7 @@ try {
   console.log('用框架自带的判据检查');
   console.log(`  包目录：${pkgDir}`);
   console.log(`  世界：${def?.id} / ${def?.label}`);
-  console.log(`  manifest：kind=${manifest.cortico?.kind} api=${manifest.cortico?.api} consoleClient=${manifest.cortico?.consoleClient ?? '(无)'}`);
+  console.log(`  manifest：kind=${manifest.cortico?.kind} api=${manifest.cortico?.api} webUiClient=${manifest.cortico?.webUiClient ?? '(无)'} describe=${manifest.cortico?.describe ?? '(无)'}`);
 
   const parsed = parseExtensionManifest(manifest);
   if (!parsed.ok) {
@@ -116,10 +116,18 @@ try {
   }
   for (const warning of parsed.warnings ?? []) hint(warning);
 
-  const clientFile = manifest.cortico?.consoleClient;
-  const hasConsoleClient = typeof clientFile === 'string' && clientFile.length > 0;
-  if (hasConsoleClient && !existsSync(join(pkgDir, clientFile))) bad(`manifest 声明的 ${clientFile} 不在包里`);
-  else if (hasConsoleClient) ok(`manifest 声明的 ${clientFile} 在包里`);
+  const clientFile = manifest.cortico?.webUiClient;
+  const hasWebUiClient = typeof clientFile === 'string' && clientFile.length > 0;
+  if (hasWebUiClient && !existsSync(join(pkgDir, clientFile))) bad(`manifest 声明的 ${clientFile} 不在包里`);
+  else if (hasWebUiClient) ok(`manifest 声明的 ${clientFile} 在包里`);
+
+  const describeFile = manifest.cortico?.describe;
+  if (typeof describeFile === 'string' && describeFile.length > 0) {
+    if (existsSync(join(pkgDir, describeFile))) ok(`manifest 声明的 ${describeFile} 在包里`);
+    else bad(`manifest 声明的 ${describeFile} 不在包里`);
+  } else {
+    bad('manifest 没有声明 describe（0.2 起自描述是必需的）');
+  }
 
   const { taken, skipped } = collectToolNames([def], { scratchDir, packageDir: pkgDir });
   for (const extra of skipped) bad(`收集工具名时构造失败 ${extra}`);
@@ -128,7 +136,7 @@ try {
   if (conflicts.size === 0) ok(`其它已装扩展里没有同名工具（扫了 ${extensionsDir}）`);
   else for (const [name, owner] of conflicts) bad(`工具名「${name}」已被 ${owner} 占用`);
 
-  const report = await dryMountWorld(def, { scratchDir, packageDir: pkgDir, hasConsoleClient, takenToolNames: conflicts });
+  const report = await dryMountWorld(def, { scratchDir, packageDir: pkgDir, hasWebUiClient, takenToolNames: conflicts });
   for (const line of report.ok) ok(line);
   for (const line of report.warnings) hint(line);
   for (const line of report.failures) bad(line);

package/tools/patch.mjs

@@ -142,7 +142,7 @@ const QQ_FIXTURE_TS = [
   'export const qqSendImage = {',
   "  name: 'qq_send_image',",
   "  description: '给某个会话发一张图。`image` 给本地文件路径或 http(s) 链接（本机下载后再发），二者挑一个。',",
-  "  parameters: [{ name: 'image', description: '本地文件路径（绝对路径，或相对扩展目录）或 http(s) 链接。' }],",
+  "  parameters: [{ name: 'image', description: '本地文件路径（如 /home/user/pics/a.png）或 http(s) 链接。' }],",
   '};',
   'export class QQWorld implements World {',
   "  private packageDir = '.';",

package/tools/prepublish.mjs

@@ -4,13 +4,16 @@
  * 静态部分（不联网、不需要 npm 账号、不需要装 Coopanion）：
  *   package.json 必填字段、npm 包名与版本号、`type: module`、
  *   `cortico` 声明按宿主 `src/extensions/manifest.ts` 的规则复刻校验、
- *   关键词、入口文件存在、`files` 覆盖到入口与控制台面板、
+ *   关键词、入口文件存在、`files` 覆盖到入口与面板产物、`cortico.describe` 指向的自描述在包里且是合法 JSON、
  *   发布物里没有 `*.coopanion-orig` / `.chat-image-patch.json` / 本机路径、
  *   每个要发布的 `.js`/`.mjs` 过一遍 `node --check`。
  *
- * 宿主相关的三套测试只在找得到本机 Coopanion 安装时才跑：
+ * 宿主相关的三套测试只在找得到**契约版本对得上**的本机 Coopanion 安装时才跑（0.1 的安装没有
+ * `describe-export.ts`、契约号也更低：自动发现到这种旧安装时只提醒并跳过，不算失败；
+ * 显式 `--app`/`COOPANION_APP_ROOT` 指到不支持的宿主才算失败）：
  *   `tools/check.mjs`（离线，永远跑）、`tools/patch.mjs`（补丁自测）、
- *   `tools/drymount.mts`（用框架自己的判据真跑装配检查）。
+ *   `tools/drymount.mts`（用框架自己的判据真跑装配检查）、
+ *   `tools/describe.mts --check`（核对 describe.json 与代码里的自描述一致）。
  *
  * 跑法：
  *   node tools/prepublish.mjs                                     # 自动找宿主
@@ -44,8 +47,10 @@ const section = (title) => console.log(`\n${title}`);
 const PACKAGE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const EXTENSION_KINDS = ['world', 'provider', 'bot'];
-const EXTENSION_API = { world: 5, provider: 5, bot: 6 };
+const EXTENSION_API = { world: 6, provider: 6, bot: 7 };
 const EXTENSION_KEYWORDS = { world: 'cortico-world', provider: 'cortico-provider', bot: 'cortico-bot' };
+/** 与宿主 `describe-export.ts` 的 `DEFAULT_DESCRIBE_FILE` 一致。 */
+const DEFAULT_DESCRIBE_FILE = 'describe.json';
 const ICON_TYPES = ['.png', '.webp', '.svg'];
 
 /** 包内相对路径：只用 `/`，不认盘符、`\`、`..`、空段。 */
@@ -148,19 +153,38 @@ if (!block || typeof block !== 'object' || Array.isArray(block)) {
   } else if (kindOk) {
     ok(`keywords 含 "${EXTENSION_KEYWORDS[kind]}"`);
   }
-  const client = block.consoleClient;
+  const client = block.webUiClient;
+  /* 0.2 之前的键名：框架只认新名，旧键留着等于没声明。 */
+  for (const [legacy, now] of [['consoleClient', 'webUiClient'], ['consoleStyle', 'webUiStyle']]) {
+    if (block[legacy] !== undefined) bad(`cortico.${legacy} 是 0.1 的旧键名，框架 0.2 只认 cortico.${now}：改个名`);
+  }
   if (client !== undefined) {
-    if (!safeRelativeFile(client)) bad(`consoleClient 必须是包内相对路径（只用 /）：${JSON.stringify(client)}`);
-    else if (!/\.m?js$/.test(client)) bad(`consoleClient 必须是 .js / .mjs：${client}`);
-    else if (!existsSync(join(pkgDir, client))) bad(`consoleClient 指向的 ${client} 不在包里`);
-    else ok(`consoleClient＝${client} 在包里`);
-  } else hint('没有 consoleClient：这个扩展不会有控制台面板');
-  const style = block.consoleStyle;
+    if (!safeRelativeFile(client)) bad(`webUiClient 必须是包内相对路径（只用 /）：${JSON.stringify(client)}`);
+    else if (!/\.m?js$/.test(client)) bad(`webUiClient 必须是 .js / .mjs：${client}`);
+    else if (!existsSync(join(pkgDir, client))) bad(`webUiClient 指向的 ${client} 不在包里`);
+    else ok(`webUiClient＝${client} 在包里`);
+  } else hint('没有 webUiClient：这个扩展不会有 WebUI 面板');
+  const style = block.webUiStyle;
   if (style !== undefined) {
-    if (client === undefined) bad('有 consoleStyle 却没有 consoleClient：宿主会报错');
-    else if (!safeRelativeFile(style) || !/\.css$/.test(style)) bad(`consoleStyle 必须是包内相对 .css：${JSON.stringify(style)}`);
-    else if (!existsSync(join(pkgDir, style))) bad(`consoleStyle 指向的 ${style} 不在包里`);
-    else ok(`consoleStyle＝${style} 在包里`);
+    if (client === undefined) bad('有 webUiStyle 却没有 webUiClient：宿主会报错');
+    else if (!safeRelativeFile(style) || !/\.css$/.test(style)) bad(`webUiStyle 必须是包内相对 .css：${JSON.stringify(style)}`);
+    else if (!existsSync(join(pkgDir, style))) bad(`webUiStyle 指向的 ${style} 不在包里`);
+    else ok(`webUiStyle＝${style} 在包里`);
+  }
+  const describePath = block.describe;
+  if (describePath === undefined) {
+    bad(`没有 cortico.describe：0.2 起自描述是必需的，宿主 check:extension 会判失败（补一个 "${DEFAULT_DESCRIBE_FILE}"）`);
+  } else if (!safeRelativeFile(describePath) || !/\.json$/.test(describePath)) {
+    bad(`cortico.describe 必须是包内相对 .json：${JSON.stringify(describePath)}`);
+  } else if (!existsSync(join(pkgDir, describePath))) {
+    bad(`cortico.describe 指向的 ${describePath} 不在包里`);
+  } else {
+    try {
+      const describeFile = JSON.parse(readFileSync(join(pkgDir, describePath), 'utf8'));
+      ok(`describe＝${describePath} 在包里且是合法 JSON（${(describeFile.tools ?? []).length} 个工具 / ${(describeFile.events ?? []).length} 个事件）`);
+    } catch (error) {
+      bad(`cortico.describe 指向的 ${describePath} 不是合法 JSON：${error instanceof Error ? error.message : String(error)}`);
+    }
   }
   const icon = block.icon;
   if (icon !== undefined) {
@@ -192,12 +216,13 @@ ok(`会发布的文件 ${shipped.length} 个，展开后约 ${(totalBytes / 1024
 
 const mustShip = [...new Set([
   ...entryPoints.map(clean),
-  ...(pkg.cortico?.consoleClient ? [clean(pkg.cortico.consoleClient)] : []),
+  ...(pkg.cortico?.webUiClient ? [clean(pkg.cortico.webUiClient)] : []),
+  ...(pkg.cortico?.describe ? [clean(pkg.cortico.describe)] : []),
 ])];
 for (const need of mustShip) {
   if (!shippedRel.includes(need)) bad(`${need} 没有被 files 覆盖：发出去的包里会缺这个文件`);
 }
-if (!mustShip.some((need) => !shippedRel.includes(need))) ok('入口与控制台面板都在 files 里');
+if (!mustShip.some((need) => !shippedRel.includes(need))) ok('入口、面板产物与自描述都在 files 里');
 
 for (const pattern of [/\.coopanion-orig$/, /\.chat-image-patch\.json$/, /\.env$/i, /\.log$/i]) {
   const hits = shippedRel.filter((file) => pattern.test(file));
@@ -248,11 +273,35 @@ function runSuite(title, args, env) {
 
 runSuite('离线检查（tools/check.mjs）', [join('tools', 'check.mjs')]);
 
-const appRoot = opt('app') || process.env.COOPANION_APP_ROOT || (() => {
+const hostManifest = join('build', 'cortico', 'src', 'extensions', 'manifest.ts');
+const hostDescribe = join('build', 'cortico', 'src', 'extensions', 'describe-export.ts');
+
+/** 宿主 `manifest.ts` 里 `EXTENSION_API_VERSIONS.world` 声明的契约号；读不出来算 0。 */
+function hostDeclaredWorld(root) {
+  try {
+    const text = readFileSync(join(root, hostManifest), 'utf8');
+    const at = text.indexOf('EXTENSION_API_VERSIONS');
+    const m = at >= 0 ? /world:\s*(\d+)/.exec(text.slice(at, at + 400)) : null;
+    return m ? Number(m[1]) : 0;
+  } catch { return 0; }
+}
+
+/**
+ * 宿主能不能跑后面三项：既要有 0.2 才有的 `describe-export.ts`，
+ * 声明的 world 契约号也要和本包一致（0.1 的安装是 v5）。
+ */
+function hostUsable(root) {
+  if (!root || !existsSync(join(root, hostManifest)) || !existsSync(join(root, hostDescribe))) return false;
+  const want = Number(block.api ?? 0);
+  return !want || hostDeclaredWorld(root) === want;
+}
+
+const explicitApp = opt('app') || process.env.COOPANION_APP_ROOT || '';
+const appRoot = explicitApp || (() => {
   let dir = pkgDir;
   for (let i = 0; i < 8; i += 1) {
     const cand = join(dir, 'resources', 'app');
-    if (existsSync(join(cand, 'build', 'cortico', 'src', 'extensions', 'manifest.ts'))) return cand;
+    if (existsSync(join(cand, hostManifest))) return cand;
     const parent = dirname(dir);
     if (parent === dir) break;
     dir = parent;
@@ -260,15 +309,27 @@ const appRoot = opt('app') || process.env.COOPANION_APP_ROOT || (() => {
   return '';
 })();
 
+/** 为什么跳过宿主那三项；空串＝能跑。 */
+const skipReason = (() => {
+  if (!appRoot) return '没找到本机 Coopanion 安装（用 --app <安装>\\resources\\app 指一下）';
+  if (!hostUsable(appRoot)) {
+    return `宿主 ${appRoot} 只声明 world 契约 v${hostDeclaredWorld(appRoot) || '?'}，本包要 v${block.api}`
+      + '（0.1 的安装没有 describe-export.ts）：用 --app <安装>\\resources\\app 或环境变量 COOPANION_APP_ROOT 指到 0.2 的安装';
+  }
+  return '';
+})();
+
 if (flag('only-static')) {
-  hint('--only-static：跳过补丁自测与 dry-mount');
-} else if (!appRoot || !existsSync(join(appRoot, 'build', 'cortico', 'src', 'extensions', 'manifest.ts'))) {
-  if (flag('quiet-host')) hint('没找到本机 Coopanion 安装：跳过补丁自测与 dry-mount');
-  else hint('没找到本机 Coopanion 安装（用 --app <安装>\\resources\\app 指一下）：跳过补丁自测与 dry-mount');
+  hint('--only-static：跳过补丁自测、dry-mount 与自描述核对');
+} else if (skipReason) {
+  if (explicitApp) bad(skipReason);
+  else if (flag('quiet-host')) console.log(`宿主相关三项跳过：${skipReason}`);
+  else hint(`${skipReason}：跳过补丁自测、dry-mount 与自描述核对`);
 } else {
   console.log(`\n宿主：${appRoot}`);
   runSuite('补丁自测（tools/patch.mjs）', [join('tools', 'patch.mjs'), '--app', appRoot], { COOPANION_APP_ROOT: appRoot });
   runSuite('dry-mount（tools/drymount.mts）', ['--experimental-transform-types', join('tools', 'drymount.mts')], { COOPANION_APP_ROOT: appRoot });
+  runSuite('自描述核对（tools/describe.mts --check）', ['--experimental-transform-types', join('tools', 'describe.mts'), '--check'], { COOPANION_APP_ROOT: appRoot });
 }
 
 if (!hadStateFile && existsSync(stateFile)) {