From 74952908687fa702810a3582687c92310354d390 Mon Sep 17 00:00:00 2001
From: Phant <phantivia@gmail.com>
Date: Mon, 19 Oct 2026 14:18:11 -0500
Subject: [PATCH 1/3] =?UTF-8?q?fix(webui):=20=E5=AD=98=E5=82=A8=E9=A1=B9?=
 =?UTF-8?q?=E6=8C=89=E5=BD=92=E5=B1=9E=E4=B8=8E=20key=20=E4=B8=80=E8=B5=B7?=
 =?UTF-8?q?=E5=8C=BA=E5=88=86,=E5=90=8C=E5=90=8D=20key=20=E4=B8=8D?=
 =?UTF-8?q?=E5=86=8D=E4=B8=B2=E5=88=B0=E5=88=AB=E7=9A=84=20World?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 根因:manifest 只带 storageKeys,数据页按 key 过滤、清除接口按 key 取第一个匹配;
  两个 World 声明同一个 key 时,数据页列出对方的项,清除可能清到对方的数据。
- manifest 改带 storageParts(owner + key),页贡献的 storage 项由装配层盖上归属;
  清除接口加可选 owner,省略且 key 有多个归属时回 409,一键清空的逐项结果带 owner。
- 不为同名 key 报错,也不给 key 自动加前缀,已有数据的位置不变。
- 测试:两个 World 同名 key 时各自数据页只画自己那项;带 owner 只清对应 World,不带回 409。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/webui.md                           |  4 +--
 src/bot.ts                              |  8 +++---
 src/web/client/features/storage/view.ts |  6 ++---
 src/web/client/webui-pages/host.ts      | 36 ++++++++++++++-----------
 src/web/server.ts                       | 19 +++++++------
 src/web/shared/webui-protocol.ts        | 18 ++++++++-----
 src/web/strings.de.ts                   |  1 +
 src/web/strings.es-419.ts               |  1 +
 src/web/strings.fr.ts                   |  1 +
 src/web/strings.it.ts                   |  1 +
 src/web/strings.ja.ts                   |  1 +
 src/web/strings.ko.ts                   |  1 +
 src/web/strings.pt-BR.ts                |  1 +
 src/web/strings.ru.ts                   |  1 +
 src/web/strings.ts                      |  2 ++
 src/web/strings.zh-Hant.ts              |  1 +
 tests/web/feature-generic.test.ts       |  6 ++---
 tests/web/hardening-webui.test.ts       | 20 +++++++++++---
 tests/web/storage.test.ts               | 27 +++++++++++++++++++
 tests/web/webui-pages.test.ts           |  4 +--
 tests/web/webui-protocol.test.ts        |  9 ++++---
 21 files changed, 117 insertions(+), 51 deletions(-)

diff --git a/docs/webui.md b/docs/webui.md
index 714598ea3..de3852768 100644
--- a/docs/webui.md
+++ b/docs/webui.md
@@ -74,7 +74,7 @@ bot 的展示名。面板、配置组与提示词文档由贡献方声明;
 数据接口)、`stream`(面板的推送通道)。World 通过 `World.webUi()` 声明,Persona 通过
 `Persona.webUi()` 声明。面板方法只接受 POST;`getMethods` 点名的方法才接受 GET(轮询读、
 `<audio src>` 这类只能带 URL 的场合)。存储项由装配层按来源盖上归属 `owner`(`core` / `persona` /
-`memory` / `world:<id>`),`/api/storage` 原样回它。
+`memory` / `world:<id>`),`/api/storage` 原样回它;不同归属可以有同名 key,manifest 的 `storageParts` 与清除接口都按归属和 key 一起认。
 
 面板带 `slot` 就没有自己的页签,由同页某块面板调 `ctx.mountSlot(slot, 容器, 作用域)` 挂进去,
 同一插槽的多块按声明顺序排,作用域进子面板的 `ctx.scope`;返回的句柄结束这一批。`llm:*` 页的面板
@@ -105,7 +105,7 @@ bot 的展示名。面板、配置组与提示词文档由贡献方声明;
 | `GET /api/config/options/:kind` | schema 里 `x-options` 为 `kind` 的配置项的当前候选值 |
 | `GET /api/blob?handle=` | 附件字节 |
 | `GET /api/worlds`、`POST /api/worlds/activation` | World 清单;激活或停用,体 `{ id, enabled }` |
-| `POST /api/storage/clear?key=` | 清除一个存储部分;`key` 取自各页 manifest 的 `storageKeys`,Core 自己的对话历史是 `session` |
+| `POST /api/storage/clear?owner=&key=` | 清除一个存储部分;`owner` 与 `key` 取自各页 manifest 的 `storageParts`,Core 自己的对话历史是 `core` 的 `session`。省略 `owner` 时 `key` 须只有一个归属,有多个时回 409 |
 | `GET /api/theme`、`POST /api/theme` | 部署的配色;GET 回 `{ defaultScheme, theme }`,POST 体是 `StoredTheme`(`src/web/shared/theme.ts`),回 `{ ok, theme }` |
 | `GET /api/avatar`、`POST /api/avatar` | bot 头像 PNG,没有时 404;POST 体是 `image/png` 原始字节，不是 PNG 时回 400 |
 | `GET /api/usage` | 用量聚合;查询参数 `bucket`(`auto`/`minute`/`hour`/`day`/`week`/`month`)、`currency`、`basis`(`marginal`/`equivalent`)、`from`、`to`、`days`(不小于 1 的整数) |
diff --git a/src/bot.ts b/src/bot.ts
index 6409a49f8..b17e3fd53 100644
--- a/src/bot.ts
+++ b/src/bot.ts
@@ -132,7 +132,7 @@ export interface WebUiContribution {
 /** 装配层向 bot WebUI 声明函数提供的共享数据。 */
 export interface WebUiPageBuildContext {
   /** 与 /api/storage 共用同一批对象的存储清单，文案使用请求语言。 */
-  storage: readonly StoragePart[];
+  storage: readonly OwnedStoragePart[];
   /** 发起这次请求的浏览器的界面语言。 */
   language: Language;
 }
@@ -625,7 +625,7 @@ export function ioPageContribution(
   if (decl?.links?.length) out.links = decl.links;
   if (decl?.config?.length) out.config = decl.config;
   if (decl?.promptDocs?.length) out.promptDocs = decl.promptDocs;
-  if (decl?.storage?.length) out.storage = decl.storage;
+  if (decl?.storage?.length) out.storage = decl.storage.map((p) => ({ ...p, owner: `world:${worldId}` }));
   if (info?.declared !== undefined) out.declared = info.declared;
   if (info?.status === 'missing') out.reason = info.reason;
   if (info?.status === 'active') {
@@ -665,7 +665,7 @@ export function personaPageContribution(
   if (declaredPanels.length) out.panels = normalizePanelDecls(declaredPanels);
   if (decl.config?.length) out.config = decl.config;
   if (decl.promptDocs?.length) out.promptDocs = decl.promptDocs;
-  if (decl.storage?.length) out.storage = decl.storage;
+  if (decl.storage?.length) out.storage = decl.storage.map((p) => ({ ...p, owner: 'persona' }));
   const invoke = decl.invoke;
   if (invoke) {
     out.invoke = (panel, method, args) =>
@@ -695,7 +695,7 @@ export function memoryPageContribution(
   };
   if (panels.length) out.panels = normalizePanelDecls(panels);
   if (promptDocs.length) out.promptDocs = promptDocs;
-  if (storage.length) out.storage = storage;
+  if (storage.length) out.storage = storage.map((p) => ({ ...p, owner: 'memory' }));
   const invoke = persona.webUi?.(language)?.invoke;
   if (invoke) out.invoke = (panel, method, args) => invoke(panel, method, args);
   return out;
diff --git a/src/web/client/features/storage/view.ts b/src/web/client/features/storage/view.ts
index dc4aa333c..99ab9dd00 100644
--- a/src/web/client/features/storage/view.ts
+++ b/src/web/client/features/storage/view.ts
@@ -87,7 +87,7 @@ export function createStorageView(deps: StorageViewDeps): StorageView {
     const lock = ui.disable(btn);
     try {
       const out = await post<{ result?: string }>(
-        `/api/storage/clear?key=${encodeURIComponent(p.key)}`,
+        `/api/storage/clear?owner=${encodeURIComponent(p.owner)}&key=${encodeURIComponent(p.key)}`,
         undefined,
         { signal },
       );
@@ -112,7 +112,7 @@ export function createStorageView(deps: StorageViewDeps): StorageView {
     if (!ok || signal.aborted) return;
     const lock = ui.disable(nukeBtn);
     try {
-      const out = await post<{ results?: Array<{ key: string; ok: boolean }> }>(
+      const out = await post<{ results?: Array<{ owner: string; key: string; ok: boolean }> }>(
         '/api/storage/clear-all',
         undefined,
         { signal },
@@ -120,7 +120,7 @@ export function createStorageView(deps: StorageViewDeps): StorageView {
       if (signal.aborted) return;
       const results = out.results || [];
       const bad = results.filter((x) => !x.ok);
-      setMsg(bad.length ? S.partialFailed(bad.map((x) => x.key).join(',')) : S.nukedAll(results.length), bad.length > 0);
+      setMsg(bad.length ? S.partialFailed(bad.map((x) => `${x.owner} ${x.key}`).join(',')) : S.nukedAll(results.length), bad.length > 0);
       await load();
     } catch (err) {
       if (isAbort(err) || signal.aborted) return;
diff --git a/src/web/client/webui-pages/host.ts b/src/web/client/webui-pages/host.ts
index b8c7e6f2b..6f972bdce 100644
--- a/src/web/client/webui-pages/host.ts
+++ b/src/web/client/webui-pages/host.ts
@@ -6,6 +6,7 @@ import {
   WEBUI_PROTOCOL_VERSION,
   type WebUiManifest,
   type WebUiPageManifest,
+  type WebUiStorageRef,
   type WebUiPanelManifest,
 } from '../../shared/webui-protocol.ts';
 import type { WebUiMemo, WebUiPanel, WebUiPanelContext, Disposable } from '../../shared/client-panel.ts';
@@ -218,12 +219,12 @@ export class WebUiPageHost {
     const panels = tabbed(page);
     const prompts = asArray(page.prompts);
     const configGroups = this.configGroupsOf(page);
-    const storageKeys = this.storageKeysOf(page);
+    const storage = this.storageOf(page);
     const tools = this.toolsTabOf(page);
     const wanted = panelId ?? panels[0]?.id
       ?? (configGroups.length ? PROVIDER_CONFIG_ROUTE : undefined)
       ?? (prompts.length ? PROVIDER_PROMPTS_ROUTE : undefined)
-      ?? (storageKeys.length ? PROVIDER_STORAGE_ROUTE : undefined)
+      ?? (storage.length ? PROVIDER_STORAGE_ROUTE : undefined)
       ?? (tools ? PROVIDER_TOOLS_ROUTE : undefined);
     if (wanted === PROVIDER_CONFIG_ROUTE && configGroups.length) {
       this.renderChrome(pageId, PROVIDER_CONFIG_ROUTE);
@@ -235,9 +236,9 @@ export class WebUiPageHost {
       await this.showPrompts(pageId, prompts.map((doc) => doc.key), gen);
       return;
     }
-    if (wanted === PROVIDER_STORAGE_ROUTE && storageKeys.length) {
+    if (wanted === PROVIDER_STORAGE_ROUTE && storage.length) {
       this.renderChrome(pageId, PROVIDER_STORAGE_ROUTE);
-      await this.showStorage(pageId, storageKeys, gen);
+      await this.showStorage(pageId, storage, gen);
       return;
     }
     if (wanted === PROVIDER_TOOLS_ROUTE && tools) {
@@ -249,7 +250,7 @@ export class WebUiPageHost {
     if (!panel) {
       this.renderChrome(pageId, wanted);
       if (panels.length === 0 && prompts.length === 0 && configGroups.length === 0
-        && storageKeys.length === 0 && !tools) {
+        && storage.length === 0 && !tools) {
         this.appendNote(S.noPanels(page.label));
       } else {
         this.renderError(
@@ -258,7 +259,7 @@ export class WebUiPageHost {
             ...panels.map((p) => p.id),
             ...(configGroups.length ? [PROVIDER_CONFIG_ROUTE] : []),
             ...(prompts.length ? [PROVIDER_PROMPTS_ROUTE] : []),
-            ...(storageKeys.length ? [PROVIDER_STORAGE_ROUTE] : []),
+            ...(storage.length ? [PROVIDER_STORAGE_ROUTE] : []),
             ...(tools ? [PROVIDER_TOOLS_ROUTE] : []),
           ].join(' / ')),
         );
@@ -389,10 +390,10 @@ export class WebUiPageHost {
     return asArray(page.configGroups);
   }
 
-  /** 仅返回当前页声明且部署支持 storage 能力的存储项 key。 */
-  private storageKeysOf(page: WebUiPageManifest): readonly string[] {
+  /** 仅返回当前页声明且部署支持 storage 能力的存储项。 */
+  private storageOf(page: WebUiPageManifest): readonly WebUiStorageRef[] {
     if (this.snapshot?.framework?.capabilities?.storage === false) return [];
-    return asArray(page.storageKeys);
+    return asArray(page.storageParts);
   }
 
   /** Persona 页才有工具表页签,且要部署挂着 /api/tool-schemas。 */
@@ -427,8 +428,8 @@ export class WebUiPageHost {
     if (gen !== this.generation) lifecycle.dispose();
   }
 
-  /** 这一页声明的存储项走同一张 /api/storage 清单;这里只按 key 挑出自己的。 */
-  private async showStorage(pageId: string, keys: readonly string[], gen: number): Promise<void> {
+  /** 这一页声明的存储项走同一张 /api/storage 清单;这里按归属与 key 挑出自己的。 */
+  private async showStorage(pageId: string, refs: readonly WebUiStorageRef[], gen: number): Promise<void> {
     const { slot } = this.ensurePanes();
     const lifecycle = new Lifecycle(this.deps.onError);
     this.mounted = { pageId, panelId: PROVIDER_STORAGE_ROUTE, lifecycle };
@@ -438,8 +439,11 @@ export class WebUiPageHost {
       signal: lifecycle.signal,
       doc: this.deps.doc,
     });
-    const wanted = new Set(keys);
-    const view = createStorageView({ ui, signal: lifecycle.signal, filter: (part) => wanted.has(part.key) });
+    const view = createStorageView({
+      ui,
+      signal: lifecycle.signal,
+      filter: (part) => refs.some((r) => r.owner === part.owner && r.key === part.key),
+    });
     const sheet = ui.sheet({ title: S.storageTitle, en: 'storage', desc: S.storageDesc });
     sheet.body.appendChild(view.el);
     slot.appendChild(sheet.el);
@@ -576,10 +580,10 @@ export class WebUiPageHost {
     const panels = tabbed(page);
     const prompts = asArray(page.prompts);
     const configGroups = this.configGroupsOf(page);
-    const storageKeys = this.storageKeysOf(page);
+    const storage = this.storageOf(page);
     const tools = this.toolsTabOf(page);
     if (panels.length + (configGroups.length ? 1 : 0) + (prompts.length ? 1 : 0)
-      + (storageKeys.length ? 1 : 0) + (tools ? 1 : 0) > 1) {
+      + (storage.length ? 1 : 0) + (tools ? 1 : 0) > 1) {
       const tabs = ui.rowbar();
       const go = (panelId: string): void => this.deps.router.navigate(this.routeOf(page.id, panelId));
       for (const p of panels) {
@@ -604,7 +608,7 @@ export class WebUiPageHost {
           onClick: () => go(PROVIDER_PROMPTS_ROUTE),
         }));
       }
-      if (storageKeys.length) {
+      if (storage.length) {
         tabs.appendChild(ui.button(S.storageTab, {
           size: 'sm',
           variant: activePanel === PROVIDER_STORAGE_ROUTE ? 'primary' : 'plain',
diff --git a/src/web/server.ts b/src/web/server.ts
index 41dc609b2..08bea322d 100644
--- a/src/web/server.ts
+++ b/src/web/server.ts
@@ -1790,20 +1790,23 @@ export class WebApp {
       res.json({ parts });
     }));
 
-    // 清除某个存储部分(运维动作;POST,key走query免body解析)
+    // 清除某个存储部分(运维动作;POST,owner 与 key 走 query 免 body 解析)。不同归属可以同 key:省略 owner 时 key 须唯一。
     app.post('/api/storage/clear', (req: Request, res: Response) => {
       void (async () => {
         const language = this.languageOf(req);
         const key = strParam(req.query.key);
         if (!key) { res.status(400).json({ error: serverText(language).missingField('key') }); return; }
-        const part = (this.deps.storage?.(language) ?? []).find((p) => p.key === key);
-        if (!part) { res.status(404).json({ error: serverText(language).noStoragePart(key) }); return; }
+        const owner = strParam(req.query.owner);
+        const matches = (this.deps.storage?.(language) ?? []).filter((p) => p.key === key && (!owner || p.owner === owner));
+        const part = matches[0];
+        if (!part) { res.status(404).json({ error: serverText(language).noStoragePart(owner ? `${owner} ${key}` : key) }); return; }
+        if (matches.length > 1) { res.status(409).json({ error: serverText(language).ambiguousStoragePart(key, matches.map((p) => p.owner)) }); return; }
         try {
           const result = await part.clear();
-          this.deps.log.warn(`存储部分已清除: ${key}`, { result });
+          this.deps.log.warn(`存储部分已清除: ${part.owner} ${key}`, { result });
           res.json({ ok: true, result });
         } catch (err) {
-          this.deps.log.error(`存储清除失败: ${key}`, { error: String(err) });
+          this.deps.log.error(`存储清除失败: ${part.owner} ${key}`, { error: String(err) });
           res.status(500).json({ error: String(err) });
         }
       })();
@@ -1815,12 +1818,12 @@ export class WebApp {
         const language = this.languageOf(req);
         const parts = [...(this.deps.storage?.(language) ?? [])].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
         if (!parts.length) { res.status(404).json({ error: serverText(language).noStorageParts }); return; }
-        const results: Array<{ key: string; ok: boolean; result: string }> = [];
+        const results: Array<{ owner: string; key: string; ok: boolean; result: string }> = [];
         for (const part of parts) {
           try {
-            results.push({ key: part.key, ok: true, result: String(await part.clear()) });
+            results.push({ owner: part.owner, key: part.key, ok: true, result: String(await part.clear()) });
           } catch (err) {
-            results.push({ key: part.key, ok: false, result: String(err) });
+            results.push({ owner: part.owner, key: part.key, ok: false, result: String(err) });
           }
         }
         this.deps.log.warn('存储已一键清空', { results });
diff --git a/src/web/shared/webui-protocol.ts b/src/web/shared/webui-protocol.ts
index e9a0cf9b3..9d67c25a0 100644
--- a/src/web/shared/webui-protocol.ts
+++ b/src/web/shared/webui-protocol.ts
@@ -4,7 +4,7 @@
  * 协议保持通用，具体页的语义和实现由贡献方提供。
  */
 
-import type { ConfigGroup, StoragePart } from '../../core/types.ts';
+import type { ConfigGroup, OwnedStoragePart, StorageOwner } from '../../core/types.ts';
 
 /** 前端拒绝渲染不支持的协议版本。 */
 export const WEBUI_PROTOCOL_VERSION = 1;
@@ -254,8 +254,8 @@ export interface WebUiPageContribution {
   config?: ConfigGroup[];
   /** 可编辑的固定提示词源文件 */
   promptDocs?: WebUiPromptDocDecl[];
-  /** 这一页自己攒下的、可清除的存储 */
-  storage?: StoragePart[];
+  /** 这一页自己攒下的、可清除的存储,每项带装配层盖的归属 */
+  storage?: OwnedStoragePart[];
 
   /**
    * 面板数据面。WebUI 只把 HTTP 请求翻译成一次 `(panel, method, args)` 调用——
@@ -371,6 +371,12 @@ export interface WebUiPromptManifest {
   description: string;
 }
 
+/** manifest 里的一条存储项引用。 */
+export interface WebUiStorageRef {
+  owner: StorageOwner;
+  key: string;
+}
+
 export interface WebUiPageManifest {
   id: string;
   kind: ContributingKind;
@@ -386,8 +392,8 @@ export interface WebUiPageManifest {
    * 归属不从 owner 推断；未认领的组显示在框架设置页。
    */
   configGroups?: string[];
-  /** 这一页声明的存储项 key;清单与清除仍走 /api/storage。 */
-  storageKeys?: string[];
+  /** 这一页声明的存储项;不同归属的项可以同 key,按 owner 与 key 一起认。清单与清除仍走 /api/storage。 */
+  storageParts?: WebUiStorageRef[];
   links?: WebUiLink[];
 
   declared?: boolean;
@@ -561,7 +567,7 @@ export function toPageManifest(
   }
   // 只上 id:归属够用了,schema 与当前值仍只走 /api/config。
   if (c.config?.length) out.configGroups = c.config.map((g) => g.id);
-  if (c.storage?.length) out.storageKeys = c.storage.map((p) => p.key);
+  if (c.storage?.length) out.storageParts = c.storage.map((p) => ({ owner: p.owner, key: p.key }));
   if (c.promptDocs?.length) {
     out.prompts = c.promptDocs.map((doc) => ({
       key: doc.key,
diff --git a/src/web/strings.de.ts b/src/web/strings.de.ts
index d1a01f61a..ca742980e 100644
--- a/src/web/strings.de.ts
+++ b/src/web/strings.de.ts
@@ -48,6 +48,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args muss ein JSON-Array sein',
   noSession: (id: string) => `Keine solche Session: ${id}`,
   noStoragePart: (key: string) => `Kein solcher Speicherteil: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `Der Speicherschlüssel ${key} gehört zu ${owners.join(', ')}; gib owner an, um den zu löschenden zu wählen`,
   noStorageParts: 'Auf dem Server ist keine Speicherliste eingebunden',
   statFailed: (error: string) => `Statistik fehlgeschlagen: ${error}`,
   promptTooLarge: 'Der Prompt ist größer als 1MB und wurde nicht gespeichert',
diff --git a/src/web/strings.es-419.ts b/src/web/strings.es-419.ts
index 74823042a..fb2dccb4f 100644
--- a/src/web/strings.es-419.ts
+++ b/src/web/strings.es-419.ts
@@ -49,6 +49,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args debe ser un arreglo JSON',
   noSession: (id: string) => `No existe esa sesión: ${id}`,
   noStoragePart: (key: string) => `No existe esa parte del almacenamiento: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `La clave de almacenamiento ${key} pertenece a ${owners.join(', ')}; indica owner para elegir cuál borrar`,
   noStorageParts: 'El servidor no tiene montada una lista de almacenamiento',
   statFailed: (error: string) => `Falló la estadística: ${error}`,
   promptTooLarge: 'El prompt supera 1MB y no se guardó',
diff --git a/src/web/strings.fr.ts b/src/web/strings.fr.ts
index bc061f6d2..21d06451b 100644
--- a/src/web/strings.fr.ts
+++ b/src/web/strings.fr.ts
@@ -48,6 +48,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args doit être un tableau JSON',
   noSession: (id: string) => `Session introuvable : ${id}`,
   noStoragePart: (key: string) => `Partie de stockage introuvable : ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `La clé de stockage ${key} appartient à ${owners.join(', ')} ; précisez owner pour choisir laquelle effacer`,
   noStorageParts: "Le serveur n'a pas de liste de stockage montée",
   statFailed: (error: string) => `Échec des statistiques : ${error}`,
   promptTooLarge: "Le prompt dépasse 1MB et n'a pas été enregistré",
diff --git a/src/web/strings.it.ts b/src/web/strings.it.ts
index 61726053c..64da12237 100644
--- a/src/web/strings.it.ts
+++ b/src/web/strings.it.ts
@@ -48,6 +48,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args deve essere un array JSON',
   noSession: (id: string) => `Sessione inesistente: ${id}`,
   noStoragePart: (key: string) => `Parte di archiviazione inesistente: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `La chiave di archiviazione ${key} appartiene a ${owners.join(', ')}; indica owner per scegliere quale cancellare`,
   noStorageParts: 'Il server non ha un elenco di archiviazione montato',
   statFailed: (error: string) => `Statistiche non riuscite: ${error}`,
   promptTooLarge: 'Il prompt supera 1MB e non è stato salvato',
diff --git a/src/web/strings.ja.ts b/src/web/strings.ja.ts
index ec680e243..48e8a999e 100644
--- a/src/web/strings.ja.ts
+++ b/src/web/strings.ja.ts
@@ -48,6 +48,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args は JSON 配列である必要があります',
   noSession: (id: string) => `そのセッションはありません：${id}`,
   noStoragePart: (key: string) => `そのストレージ項目はありません：${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `ストレージ項目 ${key} は ${owners.join(', ')} にあります。owner でどれを消去するか指定してください`,
   noStorageParts: 'サーバーにストレージ一覧がマウントされていません',
   statFailed: (error: string) => `集計に失敗しました：${error}`,
   promptTooLarge: 'プロンプトが 1MB を超えているため保存しませんでした',
diff --git a/src/web/strings.ko.ts b/src/web/strings.ko.ts
index 583c7e5c7..c2dc4dca8 100644
--- a/src/web/strings.ko.ts
+++ b/src/web/strings.ko.ts
@@ -48,6 +48,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args는 JSON 배열이어야 합니다',
   noSession: (id: string) => `해당 세션이 없습니다: ${id}`,
   noStoragePart: (key: string) => `해당 저장소 항목이 없습니다: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `저장소 항목 ${key}이(가) ${owners.join(', ')}에 있습니다. owner로 지울 항목을 지정하세요`,
   noStorageParts: '서버에 저장소 목록이 마운트되지 않았습니다',
   statFailed: (error: string) => `통계 실패: ${error}`,
   promptTooLarge: '프롬프트가 1MB를 넘어 저장하지 않았습니다',
diff --git a/src/web/strings.pt-BR.ts b/src/web/strings.pt-BR.ts
index a37b88bb1..6d595fce0 100644
--- a/src/web/strings.pt-BR.ts
+++ b/src/web/strings.pt-BR.ts
@@ -49,6 +49,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args precisa ser um array JSON',
   noSession: (id: string) => `Sessão inexistente: ${id}`,
   noStoragePart: (key: string) => `Parte de armazenamento inexistente: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `A chave de armazenamento ${key} pertence a ${owners.join(', ')}; informe owner para escolher qual limpar`,
   noStorageParts: 'O servidor não tem uma lista de armazenamento montada',
   statFailed: (error: string) => `Falha na estatística: ${error}`,
   promptTooLarge: 'O prompt passa de 1MB e não foi salvo',
diff --git a/src/web/strings.ru.ts b/src/web/strings.ru.ts
index 8e57d697d..c64e76a13 100644
--- a/src/web/strings.ru.ts
+++ b/src/web/strings.ru.ts
@@ -55,6 +55,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args должен быть массивом JSON',
   noSession: (id: string) => `Нет такой сессии: ${id}`,
   noStoragePart: (key: string) => `Нет такой части хранилища: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `Ключ хранилища ${key} есть у ${owners.join(', ')}; укажите owner, чтобы выбрать, что очистить`,
   noStorageParts: 'На сервере не подключён список хранилища',
   statFailed: (error: string) => `Не удалось получить статистику: ${error}`,
   promptTooLarge: 'Промпт больше 1MB и не сохранён',
diff --git a/src/web/strings.ts b/src/web/strings.ts
index a844f7183..0efdc594f 100644
--- a/src/web/strings.ts
+++ b/src/web/strings.ts
@@ -60,6 +60,7 @@ const zh = {
   argsNotArray: 'args 必须是 JSON 数组',
   noSession: (id: string) => `没有这个 session: ${id}`,
   noStoragePart: (key: string) => `没有这个存储部分: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `存储项 ${key} 分属 ${owners.join(', ')},请用 owner 参数指明清除哪一个`,
   noStorageParts: '服务端未挂载存储清单',
   statFailed: (error: string) => `统计失败: ${error}`,
   promptTooLarge: '提示词超过 1MB，拒绝保存',
@@ -148,6 +149,7 @@ export const en: typeof zh = {
   argsNotArray: 'args must be a JSON array',
   noSession: (id: string) => `No such session: ${id}`,
   noStoragePart: (key: string) => `No such storage part: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `Storage key ${key} belongs to ${owners.join(', ')}; pass owner to choose which one to clear`,
   noStorageParts: 'The server has no storage list mounted',
   statFailed: (error: string) => `Stats failed: ${error}`,
   promptTooLarge: 'The prompt exceeds 1MB and was not saved',
diff --git a/src/web/strings.zh-Hant.ts b/src/web/strings.zh-Hant.ts
index 84cc9c61f..af3720071 100644
--- a/src/web/strings.zh-Hant.ts
+++ b/src/web/strings.zh-Hant.ts
@@ -48,6 +48,7 @@ export const serverText: Partial<typeof en> = {
   argsNotArray: 'args 必須是 JSON 陣列',
   noSession: (id: string) => `沒有這個 session: ${id}`,
   noStoragePart: (key: string) => `沒有這個儲存部分: ${key}`,
+  ambiguousStoragePart: (key: string, owners: string[]) => `儲存項 ${key} 分屬 ${owners.join(', ')},請用 owner 參數指明清除哪一個`,
   noStorageParts: '伺服器端未掛載儲存清單',
   statFailed: (error: string) => `統計失敗: ${error}`,
   promptTooLarge: '提示詞超過 1MB，拒絕儲存',
diff --git a/tests/web/feature-generic.test.ts b/tests/web/feature-generic.test.ts
index 09bbd572c..df1fdb8cf 100644
--- a/tests/web/feature-generic.test.ts
+++ b/tests/web/feature-generic.test.ts
@@ -821,7 +821,7 @@ describe('存储页', () => {
     answerConfirm(doc, true);
     await flush();
 
-    expect(calls[0].url).toBe('/api/storage/clear?key=events');
+    expect(calls[0].url).toBe('/api/storage/clear?owner=core&key=events');
     expect(root.find('msgline')!.textContent).toContain('已删 128 条');
     expect(calls.some((c) => c.url === '/api/storage')).toBe(true); // 清完重取
   });
@@ -834,7 +834,7 @@ describe('存储页', () => {
     stubFetch({
       '/api/storage/clear-all': {
         ok: false,
-        results: [{ key: 'events', ok: true }, { key: 'cache', ok: false }],
+        results: [{ owner: 'core', key: 'events', ok: true }, { owner: 'world:a', key: 'cache', ok: false }],
       },
       '/api/storage': { parts },
     });
@@ -845,7 +845,7 @@ describe('存储页', () => {
     answerConfirm(doc, true);
     await flush();
     const msg = root.find('msgline')!;
-    expect(msg.textContent).toContain('部分失败: cache');
+    expect(msg.textContent).toContain('部分失败: world:a cache');
     expect(msg.classList.contains('bad')).toBe(true);
   });
 
diff --git a/tests/web/hardening-webui.test.ts b/tests/web/hardening-webui.test.ts
index d284aa18b..5f55b9db1 100644
--- a/tests/web/hardening-webui.test.ts
+++ b/tests/web/hardening-webui.test.ts
@@ -309,8 +309,8 @@ interface ProviderDecl {
   links?: Array<{ label: string; href: string; inheritTheme?: boolean }>;
   /** 这个 provider 认领的配置组 id(归属),配置页据此只画自己那几组。 */
   configGroups?: string[];
-  /** 这个 provider 声明的存储项 key,数据页签据此只画自己那几项。 */
-  storageKeys?: string[];
+  /** 这个 provider 声明的存储项,数据页签据此只画自己那几项。 */
+  storageParts?: Array<{ owner: string; key: string }>;
 }
 
 interface Stage {
@@ -1601,6 +1601,8 @@ describe('数据页签', () => {
   const STORAGE_PARTS = {
     parts: [
       { key: 'a-log', owner: 'world:a', label: 'A 日志', kind: 'disk', stat: '3 条' },
+      { key: 'cache', owner: 'world:a', label: 'A 缓存', kind: 'disk', stat: '1 条' },
+      { key: 'cache', owner: 'world:b', label: 'B 缓存', kind: 'disk', stat: '2 条' },
       { key: 'events', owner: 'core', label: '事件库', kind: 'disk', stat: '9 条' },
     ],
   };
@@ -1614,7 +1616,7 @@ describe('数据页签', () => {
   afterEach(() => { vi.unstubAllGlobals(); });
 
   it('只画 manifest 里点名的那几项;页签上多一颗「数据」', async () => {
-    const stage = makeStage([{ id: 'world:a', label: 'A World', storageKeys: ['a-log'], panels: [{ id: 'one', title: '面板一' }] }], {});
+    const stage = makeStage([{ id: 'world:a', label: 'A World', storageParts: [{ owner: 'world:a', key: 'a-log' }], panels: [{ id: 'one', title: '面板一' }] }], {});
     await stage.host.load();
     await stage.host.show('world:a', '~storage');
     await flush();
@@ -1623,6 +1625,18 @@ describe('数据页签', () => {
     expect(stage.slotText()).not.toContain('事件库');
   });
 
+  it('两个 World 声明同名 key,各自的数据页只画自己那一项', async () => {
+    const stage = makeStage([
+      { id: 'world:a', label: 'A World', storageParts: [{ owner: 'world:a', key: 'cache' }] },
+      { id: 'world:b', label: 'B World', storageParts: [{ owner: 'world:b', key: 'cache' }] },
+    ], {});
+    await stage.host.load();
+    await stage.host.show('world:b', '~storage');
+    await flush();
+    expect(stage.slotText()).toContain('B 缓存');
+    expect(stage.slotText()).not.toContain('A 缓存');
+  });
+
   it('没声明存储项的页没有这颗页签,直接进 ~storage 是一张"没有这个面板"的卡', async () => {
     const stage = makeStage([{ id: 'world:b', label: 'B World', panels: [{ id: 'one', title: '面板一' }, { id: 'two', title: '面板二' }] }], {});
     await stage.host.load();
diff --git a/tests/web/storage.test.ts b/tests/web/storage.test.ts
index a5a5b41f5..46d1f3164 100644
--- a/tests/web/storage.test.ts
+++ b/tests/web/storage.test.ts
@@ -165,3 +165,30 @@ describe('POST /api/storage/clear', () => {
     await bare.stop();
   });
 });
+
+describe('两个 World 声明同名 key', () => {
+  it('带 owner 只清那一个 World 的;不带 owner 回 409 并列出归属', async () => {
+    const hits: string[] = [];
+    const same = (owner: OwnedStoragePart['owner']): OwnedStoragePart => ({
+      key: 'log', owner, label: `${owner} 日志`, kind: 'disk', stat: () => '1条',
+      clear: () => { hits.push(owner); return `${owner} 已清`; },
+    });
+    const twin = new WebApp({
+      store: new FakeStore(),
+      memoryDir: dir,
+      dataDir: dir,
+      getStatus: () => ({}),
+      storage: () => [same('world:a'), same('world:b')],
+      log: nullLogger(),
+    });
+    const p2 = await twin.start(0);
+    const r = await req(`http://127.0.0.1:${p2}/api/storage/clear?owner=world:b&key=log`, 'POST');
+    expect(r.body).toEqual({ ok: true, result: 'world:b 已清' });
+    expect(hits).toEqual(['world:b']);
+    const ambiguous = await req(`http://127.0.0.1:${p2}/api/storage/clear?key=log`, 'POST');
+    expect(ambiguous.status).toBe(409);
+    expect(ambiguous.body.error).toContain('world:a, world:b');
+    expect(hits).toEqual(['world:b']);
+    await twin.stop();
+  });
+});
diff --git a/tests/web/webui-pages.test.ts b/tests/web/webui-pages.test.ts
index 4b0786c3e..6c1637118 100644
--- a/tests/web/webui-pages.test.ts
+++ b/tests/web/webui-pages.test.ts
@@ -195,7 +195,7 @@ describe('manifest 组装', () => {
     });
   });
 
-  it('World 声明的存储项:manifest 只带 key,stat 与 clear 不上线', async () => {
+  it('World 声明的存储项:manifest 只带归属与 key,stat 与 clear 不上线', async () => {
     const sources = deriveWebUiPageSources(facts(), {
       assembly: WorldAssembly.ofInstances([new FakeWorld('demo', () => ({
         storage: [{ key: 'demo-log', label: '日志', kind: 'disk' as const, stat: () => '1', clear: () => '清了' }],
@@ -203,7 +203,7 @@ describe('manifest 组装', () => {
     });
     await withApp({ webUiPageSources: sources }, async (base) => {
       const p = byId(await manifestOf(base), 'world:demo');
-      expect(p?.storageKeys).toEqual(['demo-log']);
+      expect(p?.storageParts).toEqual([{ owner: 'world:demo', key: 'demo-log' }]);
       expect(JSON.stringify(p)).not.toContain('清了');
     });
   });
diff --git a/tests/web/webui-protocol.test.ts b/tests/web/webui-protocol.test.ts
index 71c567841..e66b24f44 100644
--- a/tests/web/webui-protocol.test.ts
+++ b/tests/web/webui-protocol.test.ts
@@ -439,6 +439,7 @@ describe('toPageManifest 序列化公开字段', () => {
     }],
     storage: [{
       key: 'alpha.cache',
+      owner: 'world:alpha',
       label: '缓存',
       kind: 'disk',
       location: 'data/alpha',
@@ -465,7 +466,7 @@ describe('toPageManifest 序列化公开字段', () => {
   });
 
   it('config 只上线组 id(归属),schema 与属性名不上线——正文仍走 /api/config', () => {
-    const m = toPageManifest(full());
+    const { storageParts: _, ...m } = toPageManifest(full());
     expect(m.configGroups).toEqual(['alpha']);
     const text = JSON.stringify(m);
     expect(text).not.toContain('阿尔法旋钮');
@@ -478,9 +479,9 @@ describe('toPageManifest 序列化公开字段', () => {
     expect('configGroups' in toPageManifest(provider())).toBe(false);
   });
 
-  it('storage 只上 key:stat 与 clear 是函数,连键名都不该出现', () => {
+  it('storage 只上归属与 key:stat 与 clear 是函数,连键名都不该出现', () => {
     const text = JSON.stringify(toPageManifest(full()));
-    expect(text).toContain('"storageKeys":["alpha.cache"]');
+    expect(text).toContain('"storageParts":[{"owner":"world:alpha","key":"alpha.cache"}]');
     expect(text).not.toContain('stat');
     expect(text).not.toContain('clear');
   });
@@ -501,7 +502,7 @@ describe('toPageManifest 序列化公开字段', () => {
       { id: 'runtime', title: '运行时', slot: 'instance' },
     ],
       configGroups: ['alpha'],
-      storageKeys: ['alpha.cache'],
+      storageParts: [{ owner: 'world:alpha', key: 'alpha.cache' }],
       prompts: [{ key: 'worlds.alpha.main', title: '主提示词', description: '说明' }],
       links: [{ label: '打开', href: '/alpha/page' }],
       declared: true,

From 9fadefc3796a17bc10ff68de89b9ffa73faaafcf Mon Sep 17 00:00:00 2001
From: Phant <phantivia@gmail.com>
Date: Mon, 19 Oct 2026 14:18:11 -0500
Subject: [PATCH 2/3] =?UTF-8?q?fix(world):=20=E5=AE=9E=E4=BE=8B=20id=20?=
 =?UTF-8?q?=E4=B8=8E=E5=AE=9A=E4=B9=89=20id=20=E4=B8=8D=E4=B8=80=E8=87=B4?=
 =?UTF-8?q?=E6=97=B6=E6=8C=89=E5=8A=A0=E8=BD=BD=E5=A4=B1=E8=B4=A5=E5=A4=84?=
 =?UTF-8?q?=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 根因:装配层调 create() 后不核对实例 id,Core 按实例 id 归属工具与事件、
  装配层按定义 id 找槽位,缺 id 时日志记到 worlds.undefined、设置页也找不到这个 World。
- 现在不建槽位、不挂载,进 missing,原因写明两个 id;与 check:extension 的检查一致。
- 测试:实例 id 不一致的定义进 missing,其余 World 照常挂载。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/strings.de.ts      |  1 +
 src/strings.es-419.ts  |  1 +
 src/strings.fr.ts      |  1 +
 src/strings.it.ts      |  1 +
 src/strings.ja.ts      |  1 +
 src/strings.ko.ts      |  1 +
 src/strings.pt-BR.ts   |  1 +
 src/strings.ru.ts      |  1 +
 src/strings.ts         |  2 ++
 src/strings.zh-Hant.ts |  1 +
 src/world.ts           | 11 +++++++++++
 tests/world.test.ts    |  9 +++++++++
 12 files changed, 31 insertions(+)

diff --git a/src/strings.de.ts b/src/strings.de.ts
index 148d0905a..e7e755569 100644
--- a/src/strings.de.ts
+++ b/src/strings.de.ts
@@ -106,6 +106,7 @@ export const botText: Partial<typeof botEn> = {
 };
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `Erstellung fehlgeschlagen: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `Die von create() gelieferte Instanz-ID „${instanceId}“ weicht von der Definitions-ID „${definitionId}“ ab; die ID einer World-Instanz muss der ID ihrer Definition entsprechen`,
   notImplemented: 'Lokal wurde keine Implementierung dieser World gefunden.',
   unknownWorld: (id: string) => `Unbekannte World: ${id}`,
   alreadyRunning: (label: string) => `${label} ist bereits aktiviert`,
diff --git a/src/strings.es-419.ts b/src/strings.es-419.ts
index 492e23de5..c57287b57 100644
--- a/src/strings.es-419.ts
+++ b/src/strings.es-419.ts
@@ -109,6 +109,7 @@ export const botText: Partial<typeof botEn> = {
 
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `Falló la construcción: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `El id de instancia "${instanceId}" que devuelve create() no coincide con el id de definición "${definitionId}"; el id de una instancia de World debe ser el de su definición`,
   notImplemented: 'No se encontró localmente una implementación de este World.',
   unknownWorld: (id: string) => `World desconocido: ${id}`,
   alreadyRunning: (label: string) => `${label} ya está activado`,
diff --git a/src/strings.fr.ts b/src/strings.fr.ts
index d263f8e5a..2e6df808f 100644
--- a/src/strings.fr.ts
+++ b/src/strings.fr.ts
@@ -106,6 +106,7 @@ export const botText: Partial<typeof botEn> = {
 };
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `Échec de la construction : ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `L'id d'instance « ${instanceId} » renvoyé par create() diffère de l'id de définition « ${definitionId} » ; l'id d'une instance de World doit être celui de sa définition`,
   notImplemented: "Aucune implémentation de ce World n'a été trouvée localement.",
   unknownWorld: (id: string) => `World inconnu : ${id}`,
   alreadyRunning: (label: string) => `${label} est déjà activé`,
diff --git a/src/strings.it.ts b/src/strings.it.ts
index 8d9c30293..485560a02 100644
--- a/src/strings.it.ts
+++ b/src/strings.it.ts
@@ -106,6 +106,7 @@ export const botText: Partial<typeof botEn> = {
 };
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `Costruzione non riuscita: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `L'id di istanza "${instanceId}" restituito da create() è diverso dall'id di definizione "${definitionId}"; l'id di un'istanza di World deve coincidere con quello della definizione`,
   notImplemented: 'Nessuna implementazione di questo World trovata in locale.',
   unknownWorld: (id: string) => `World sconosciuto: ${id}`,
   alreadyRunning: (label: string) => `${label} è già attivato`,
diff --git a/src/strings.ja.ts b/src/strings.ja.ts
index eb22e9653..bc9f32785 100644
--- a/src/strings.ja.ts
+++ b/src/strings.ja.ts
@@ -107,6 +107,7 @@ export const botText: Partial<typeof botEn> = {
 
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `構築に失敗しました：${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `create() が返したインスタンス id「${instanceId}」が定義 id「${definitionId}」と一致しません。World インスタンスの id は定義の id と同じにしてください`,
   notImplemented: 'この World の実装がローカルに見つかりません。',
   unknownWorld: (id: string) => `不明な World：${id}`,
   alreadyRunning: (label: string) => `${label} は既に有効です`,
diff --git a/src/strings.ko.ts b/src/strings.ko.ts
index 31b5e1c7a..46750647d 100644
--- a/src/strings.ko.ts
+++ b/src/strings.ko.ts
@@ -107,6 +107,7 @@ export const botText: Partial<typeof botEn> = {
 
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `생성 실패: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `create()가 반환한 인스턴스 id "${instanceId}"가 정의 id "${definitionId}"와 다릅니다. World 인스턴스의 id는 정의의 id와 같아야 합니다`,
   notImplemented: '이 World의 구현을 로컬에서 찾지 못했습니다.',
   unknownWorld: (id: string) => `알 수 없는 World: ${id}`,
   alreadyRunning: (label: string) => `${label}은(는) 이미 활성화되어 있습니다`,
diff --git a/src/strings.pt-BR.ts b/src/strings.pt-BR.ts
index 4c1862d5c..3be35cc44 100644
--- a/src/strings.pt-BR.ts
+++ b/src/strings.pt-BR.ts
@@ -109,6 +109,7 @@ export const botText: Partial<typeof botEn> = {
 
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `Falha na construção: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `O id de instância "${instanceId}" retornado por create() difere do id de definição "${definitionId}"; o id de uma instância de World deve ser o da sua definição`,
   notImplemented: 'Nenhuma implementação deste World foi encontrada localmente.',
   unknownWorld: (id: string) => `World desconhecido: ${id}`,
   alreadyRunning: (label: string) => `${label} já está ativado`,
diff --git a/src/strings.ru.ts b/src/strings.ru.ts
index aa8bf2d6c..3946d7f24 100644
--- a/src/strings.ru.ts
+++ b/src/strings.ru.ts
@@ -113,6 +113,7 @@ export const botText: Partial<typeof botEn> = {
 
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `Ошибка создания: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `Id экземпляра «${instanceId}», который вернул create(), не совпадает с id определения «${definitionId}»; id экземпляра World должен совпадать с id определения`,
   notImplemented: 'Реализация этого World локально не найдена.',
   unknownWorld: (id: string) => `Неизвестный World: ${id}`,
   alreadyRunning: (label: string) => `${label}: уже включено`,
diff --git a/src/strings.ts b/src/strings.ts
index ce04016af..6b399944a 100644
--- a/src/strings.ts
+++ b/src/strings.ts
@@ -226,6 +226,7 @@ export const botText = (language: Language) => pick(language, {
 /** 装配层给 WebUI 的回执与拒绝理由,按发起请求的界面语言取。 */
 const assemblyZh = {
   constructFailed: (detail: string) => `构造失败: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `create() 返回的实例 id「${instanceId}」与定义 id「${definitionId}」不一致,World 实例的 id 须等于定义的 id`,
   notImplemented: '本地没有找到这个 World 的实现。',
   unknownWorld: (id: string) => `未知 World: ${id}`,
   alreadyRunning: (label: string) => `${label} 已启用`,
@@ -240,6 +241,7 @@ const assemblyZh = {
 };
 export const assemblyEn: typeof assemblyZh = {
   constructFailed: (detail: string) => `Construction failed: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `Instance id "${instanceId}" returned by create() differs from definition id "${definitionId}"; a World instance's id must equal its definition's id`,
   notImplemented: 'No implementation of this World was found locally.',
   unknownWorld: (id: string) => `Unknown World: ${id}`,
   alreadyRunning: (label: string) => `${label} is already enabled`,
diff --git a/src/strings.zh-Hant.ts b/src/strings.zh-Hant.ts
index f87f61366..e17d1335b 100644
--- a/src/strings.zh-Hant.ts
+++ b/src/strings.zh-Hant.ts
@@ -107,6 +107,7 @@ export const botText: Partial<typeof botEn> = {
 
 export const assemblyText: Partial<typeof assemblyEn> = {
   constructFailed: (detail: string) => `建構失敗: ${detail}`,
+  instanceIdMismatch: (instanceId: string, definitionId: string) => `create() 回傳的實例 id「${instanceId}」與定義 id「${definitionId}」不一致,World 實例的 id 須等於定義的 id`,
   notImplemented: '本機沒有找到這個 World 的實作。',
   unknownWorld: (id: string) => `未知 World: ${id}`,
   alreadyRunning: (label: string) => `${label} 已啟用`,
diff --git a/src/world.ts b/src/world.ts
index 6fd52fc9f..945c62f00 100644
--- a/src/world.ts
+++ b/src/world.ts
@@ -227,6 +227,17 @@ export class WorldAssembly {
         });
         continue;
       }
+      // Core 按实例 id 归属工具与事件,装配层按定义 id 找槽位,两者须一致。
+      if (instance.id !== def.id) {
+        const instanceId = String(instance.id);
+        this.missing.push({
+          id: def.id,
+          label: def.label,
+          declared: declared.has(def.id),
+          reason: (language) => text(language).instanceIdMismatch(instanceId, def.id),
+        });
+        continue;
+      }
       const clash = section.enabled ? this.toolClash(instance, this.mounted) : null;
       if (clash) {
         this.missing.push({ id: def.id, label: def.label, declared: declared.has(def.id), reason: clash });
diff --git a/tests/world.test.ts b/tests/world.test.ts
index 77728b48b..bf329eea7 100644
--- a/tests/world.test.ts
+++ b/tests/world.test.ts
@@ -14,6 +14,7 @@ import type { BotDefinition } from '../src/bot.ts';
 import type { CoreConfig, ToolDef, World, WorldHost, WorldLifecycleEvent } from '../src/core/types.ts';
 import type { Language } from '../src/core/language.ts';
 import { makeCfg } from './core/helpers.ts';
+import { assemblyText } from '../src/strings.ts';
 
 interface ProbeSection { enabled: boolean; port: number; nested: { name: string; tags: string[] } }
 
@@ -307,6 +308,14 @@ describe('构造隔离与生命周期', () => {
     expect(assembly.missing[0]).toMatchObject({ id: 'boom', declared: false });
   });
 
+  it('实例 id 与定义 id 不一致 → 进 missing 并说明两个 id,不建槽位不挂载', () => {
+    const stray = probeDefinition('stray', { create: (ctx) => new Probe('other', ctx) });
+    const { assembly } = assemblyOf([stray, probeDefinition('a')], ['stray', 'a']);
+    expect(assembly.slots.map((s) => s.id)).toEqual(['a']);
+    expect(assembly.mounted.map((m) => m.id)).toEqual(['a']);
+    expect(missingOf(assembly)).toEqual([{ id: 'stray', label: 'stray 探针', declared: true, reason: assemblyText('zh').instanceIdMismatch('other', 'stray') }]);
+  });
+
   it('激活 / 停用 / 重启 / 对账各报一次生命周期事件;启动期初始挂载与失败的激活不报', async () => {
     const { assembly, lifecycle, loaded } = assemblyOf([probeDefinition('a'), probeDefinition('b')], ['a'], {
       b: { enabled: false },

From 1d804b1fab78b67593062eb7beb11acf6da81ab8 Mon Sep 17 00:00:00 2001
From: Phant <phantivia@gmail.com>
Date: Mon, 19 Oct 2026 14:18:11 -0500
Subject: [PATCH 3/3] =?UTF-8?q?docs:=20=E5=86=99=E6=98=8E=20World=20?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E7=9A=84=E7=94=9F=E6=95=88=E8=A7=84=E5=88=99?=
 =?UTF-8?q?=E4=B8=8E=20dataDir=20=E7=9A=84=E5=91=BD=E5=90=8D=E7=BA=A6?=
 =?UTF-8?q?=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/configuration.md | 2 +-
 docs/worlds.md        | 9 +++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 631f41b1c..404842c27 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -52,7 +52,7 @@ WebUI 按 schema 渲染表单。owner 是 `core`、`persona`、`world:<id>` 或
 
 | 键 | 作用 |
 |---|---|
-| `x-hot` | `false` 时前端标「重启生效」;Core 组每一项都是热改 |
+| `x-hot` | `false`:改动要等所属实例重新构造才生效,前端标「重启生效」。省略或 `true`:读取方每次现读,保存后立即生效。Core 组每一项都是热改;World 的读法见 [worlds.md](worlds.md) |
 | `x-scale`、`x-suffix` | 显示倍率与单位 |
 | `x-options` | 下拉项 |
 | `x-path` | 用本机路径选择器填 |
diff --git a/docs/worlds.md b/docs/worlds.md
index ec4773f21..c46f6d125 100644
--- a/docs/worlds.md
+++ b/docs/worlds.md
@@ -80,6 +80,15 @@ World 应通过事件报告服务器起停、存档切换、连接变化等状
 `configOptions(kind, language)` 每次传入(见 [webui.md](webui.md))。WebUI 里的 World 名取
 `webUi(language).label`,没有时取定义的 `label`,两者都按请求现读。
 
+`ctx.cfg` 是部署配置里 `worlds.<id>` 段的共享引用,WebUI 改配置时原地写入这个对象。World 用到时现读
+`ctx.cfg.<键>`,改动立即生效;构造时存进字段、或用来建立连接和启动进程的值,要等实例重新构造(停用后
+再启用、World 重启、bot 重启)才生效。这类项在 schema 里标 `x-hot: false`,设置页显示「重启生效」;没标的项
+按立即生效显示。
+
+`ctx.dataDir` 是部署的数据目录,Core 与这个部署的全部 World 共用,同名文件会互相覆盖。World 的文件名与
+`webUi().storage` 的 key 都以 World id 开头,仓内 World 写作 `minecraft-chests.json` 与 `minecraft-chests`。
+装配层给每个存储项盖上归属 `world:<id>`,数据页和清除接口按归属与 key 一起区分。
+
 仓内定义列在 `src/worlds/index.ts`,由 `loadBuiltinWorlds(ids?)` 按 id 动态导入 `src/worlds/<id>/definition.ts`;
 不给 `ids` 时带上全部(`BUILTIN_WORLD_IDS`),有不认识的 id 时抛错。启动器带上全部仓内 World,与扩展定义
 合并后通过 `withWorlds()` 交给 bot 定义。