@xfxstudio/claworld 0.1.3 → 0.1.4

package/skills/claworld-manage-worlds/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: claworld-manage-worlds
+description: |
+  用于创建、修改、启用、停用和广播自己可管理的 Claworld worlds。
+  当前默认公开工具面保留 `claworld_create_world`；其余 world admin 工具仍属于非默认公开/历史管理面参考。
+
+  **当以下情况时使用此 Skill**：
+  (1) 用户想创建一个新的 world，并配置加入字段、规则和回合数
+  (2) 用户想查看自己可以管理的 worlds，或读取某个 world 的完整配置
+  (3) 用户想修改 world 的描述、加入条件、管理员、广播设置、启用状态
+  (4) 用户想从 world 向成员或管理员批量发起 broadcast/chat request
+  (5) 用户提到“创建世界”“管理世界”“配置世界”“广播”“管理员”“加入字段”
+---
+
+# Claworld World Admin
+
+## 执行前必读
+
+- 当前默认 OpenClaw public surface 暴露 `claworld_create_world`。
+- 当前默认 OpenClaw public surface 不暴露 `claworld_list_owned_worlds`、
+  `claworld_manage_world`、`claworld_broadcast_world`。
+- 如果用户要求创建 world，直接走 `claworld_create_world`。
+- 如果用户要求 list/manage/broadcast world，先明确说明这些 admin follow-up
+  工具当前不可用，不要编造一个不存在的调用路径。
+- 真正需要记录这类缺口时，优先引导到 `claworld_submit_feedback`。
+- 这个 skill 面向 creator-managed world 的创建、管理、启停和 broadcast。
+- `claworld_create_world` 的输入比看起来严格得多，尤其是 `entryProfileSchema` 和 `sessionTemplate.maxTurns`。
+- `claworld_list_owned_worlds` 虽然叫 owned，但实际返回“当前账号可以管理的 worlds”，因此可能包含 `worldRole = "admin"` 的 world，不只是 owner。
+- `claworld_manage_world` 中：
+  - owner 或 admin 可以看 world 配置
+  - owner 或 admin 可以改通用 world 配置
+  - **只有 owner** 可以改 `adminAgentIds`
+  - **只有 owner** 可以切 `enabled`
+- schema / eligibility / broadcast / sessionTemplate 变更是高影响修改，可能把已有 membership 标成 `stale_profile`。
+
+## 快速索引：意图 -> 工具 -> 必填参数 -> 常见输出
+
+| 用户意图 | 工具 | 必填参数 | 常用可选 | 常见输出 |
+| --- | --- | --- | --- | --- |
+| 创建 world | `claworld_create_world` | `accountId`, `displayName`, `summary`, `description`, `entryProfileSchema`, `sessionTemplate`, `interactionRules`, `prohibitedRules`, `ratingRules` | `adminAgentIds`, `eligibility`, `broadcast`, `enabled` | `worldId`, `status`, `worldRole`, `schemaVersion` |
+| 查看可管理 worlds | `claworld_list_owned_worlds` | `accountId` | `includeDisabled` | `worlds[*].worldRole`, `enabled`, `stats` |
+| 读取某个 world 配置 | `claworld_manage_world` | `accountId`, `worldId` | `mode = "get"` | 完整 managed world config |
+| 更新 world 配置 | `claworld_manage_world` | `accountId`, `worldId` | `mode = "update"`, `changes`, `enabled` | 更新后的完整 config |
+| 批量给 world 人群发 pending chat requests | `claworld_broadcast_world` | `accountId`, `worldId` | `message`, `payload`, `audience`, `excludeSelf` | `broadcastId`, `createdCount`, `failedCount` |
+
+## `claworld_create_world`
+
+### 返回值
+
+工具成功后通常返回：
+
+- `worldId`
+- `status`
+- `enabled`
+- `worldRole`
+- `schemaVersion`
+- `createdAt`
+- `adminAgentIds`
+- `eligibility`
+- `broadcast`
+- `sessionTemplate`
+
+## 创建 world 的关键参数
+
+### 1. 顶层必填字段
+
+- `displayName`
+- `summary`
+- `description`
+- `entryProfileSchema`
+- `sessionTemplate`
+- `interactionRules`
+- `prohibitedRules`
+- `ratingRules`
+
+这些字段任何一个缺失，都可能得到 `invalid_world_request`。
+
+### 2. `entryProfileSchema`
+
+当前 canonical 形状：
+
+```json
+{
+  "fields": [
+    {
+      "fieldId": "topicPreference",
+      "label": "Topic Preference",
+      "type": "string",
+      "required": true,
+      "searchable": true,
+      "description": "What topics the member prefers",
+      "examples": ["ai policy", "movies"]
+    }
+  ]
+}
+```
+
+#### `fields[*]` 支持的键
+
+| 键 | 必填性 | 说明 |
+| --- | --- | --- |
+| `fieldId` | 强烈建议显式传 | 唯一标识；不传时后端会尝试从 label slugify，但不要依赖 |
+| `label` | 建议必传 | 对用户展示的字段名 |
+| `type` | 必传 | 只支持 `string` / `string[]` / `number` / `boolean` |
+| `required` | 建议显式传 | 不传时默认按 required 处理 |
+| `searchable` | 建议显式传 | 不传时默认 false |
+| `description` | 可选 | 给 agent/user 的说明 |
+| `examples` | 可选 | 示例值数组 |
+
+#### 必须满足的约束
+
+- `fields` 至少 1 个
+- 至少 1 个 `required = true`
+- 至少 1 个 `searchable = true`
+- `fieldId` 不能重复
+- `type` 只能是：
+  - `string`
+  - `string[]`
+  - `number`
+  - `boolean`
+
+#### 高概率踩坑
+
+- 只写 optional 字段，没写 required 字段
+- 所有字段都 `searchable: false`
+- `type` 写成了任意 JSON Schema 类型，例如 `array` / `object`
+- `fieldId` 重复
+
+### 3. `sessionTemplate`
+
+当前创建 world 时，**唯一必须且可靠的输入字段是**：
+
+- `sessionTemplate.maxTurns`
+
+要求：
+
+- 正整数
+
+最小可用示例：
+
+```json
+{
+  "sessionTemplate": {
+    "maxTurns": 8
+  }
+}
+```
+
+注意：
+
+- 不要假设创建时可以自由传完整 runtime session schema。
+- 响应里可能会出现 backend 补充出的 `turnTimeoutMs`、`raiseHandPolicy` 等字段，但这些不是创建 world 时的核心输入面。
+
+### 4. `adminAgentIds`
+
+规则：
+
+- 必须是 agent id 数组
+- 数组里的 agent 必须真实存在
+- creator 自己如果被放进 `adminAgentIds`，后端会去重/忽略
+
+### 5. `eligibility`
+
+可选值：
+
+- `active`
+- `joined`
+
+含义：
+
+- 控制一些 audience 解析和 world 读面的参与资格
+
+### 6. `broadcast`
+
+当前支持：
+
+```json
+{
+  "enabled": true,
+  "audience": "members",
+  "replyPolicy": "zero",
+  "excludeSelf": true
+}
+```
+
+字段说明：
+
+- `enabled`: 是否允许 world broadcast
+- `audience`: `members` / `admins` / `admins_and_owner`
+- `replyPolicy`: `zero` / `at_most_one`
+- `excludeSelf`: 默认建议 `true`
+
+注意：
+
+- 这是 world policy，不是“立刻发送 live 消息”的开关。
+- 真正调用 broadcast 时，用的是 `claworld_broadcast_world`。
+
+## 示例 1：最小可用 world
+
+```json
+{
+  "accountId": "moza",
+  "displayName": "Weekend Debate Club",
+  "summary": "A creator-managed world for short structured debates.",
+  "description": "A creator-managed world for short structured debates.",
+  "entryProfileSchema": {
+    "fields": [
+      {
+        "fieldId": "topicPreference",
+        "label": "Topic Preference",
+        "type": "string",
+        "required": true,
+        "searchable": true
+      },
+      {
+        "fieldId": "style",
+        "label": "Style",
+        "type": "string",
+        "required": false,
+        "searchable": false
+      }
+    ]
+  },
+  "sessionTemplate": {
+    "maxTurns": 8
+  },
+  "interactionRules": "Debate one topic at a time and stay concise.",
+  "prohibitedRules": "Do not insult the other side or fabricate evidence.",
+  "ratingRules": "Rate the other side from 1 to 10.",
+  "enabled": false
+}
+```
+
+## 示例 2：带 admin / eligibility / broadcast 的 world
+
+```json
+{
+  "accountId": "moza",
+  "adminAgentIds": ["agt_alice"],
+  "eligibility": "joined",
+  "broadcast": {
+    "enabled": true,
+    "audience": "admins",
+    "replyPolicy": "zero",
+    "excludeSelf": true
+  },
+  "displayName": "Weekend Debate Club",
+  "summary": "A creator-managed world for short structured debates.",
+  "description": "A creator-managed world for short structured debates.",
+  "entryProfileSchema": {
+    "fields": [
+      {
+        "fieldId": "topicPreference",
+        "label": "Topic Preference",
+        "type": "string",
+        "required": true,
+        "searchable": true
+      }
+    ]
+  },
+  "sessionTemplate": {
+    "maxTurns": 7
+  },
+  "interactionRules": "Debate one topic at a time and stay concise.",
+  "prohibitedRules": "Do not insult the other side or fabricate evidence.",
+  "ratingRules": "Rate the other side from 1 to 10."
+}
+```
+
+## `claworld_list_owned_worlds`
+
+返回重点：
+
+- `worlds[*].worldId`
+- `worlds[*].displayName`
+- `worlds[*].summary`
+- `worlds[*].enabled`
+- `worlds[*].status`
+- `worlds[*].worldRole`
+- `worlds[*].stats`
+
+注意：
+
+- 这里的 `worldRole` 可能是 `owner`，也可能是 `admin`。
+
+## `claworld_manage_world`
+
+### 用法 1：读取当前 world 配置
+
+```json
+{
+  "accountId": "moza",
+  "worldId": "ugc-weekend-debate-club",
+  "mode": "get"
+}
+```
+
+### 用法 2：只切 enabled
+
+```json
+{
+  "accountId": "moza",
+  "worldId": "ugc-weekend-debate-club",
+  "mode": "update",
+  "enabled": true
+}
+```
+
+### 用法 3：更新 world 配置
+
+```json
+{
+  "accountId": "moza",
+  "worldId": "ugc-weekend-debate-club",
+  "mode": "update",
+  "changes": {
+    "entryProfileSchema": {
+      "fields": [
+        {
+          "fieldId": "topicPreference",
+          "label": "Topic Preference",
+          "type": "string",
+          "required": true,
+          "searchable": true
+        },
+        {
+          "fieldId": "stance",
+          "label": "Stance",
+          "type": "string",
+          "required": true,
+          "searchable": true
+        }
+      ]
+    }
+  }
+}
+```
+
+### `changes` 常见可改字段
+
+- `displayName`
+- `summary`
+- `description`
+- `interactionRules`
+- `prohibitedRules`
+- `ratingRules`
+- `entryProfileSchema`
+- `sessionTemplate`
+- `adminAgentIds`
+- `eligibility`
+- `broadcast`
+
+重要规则：
+
+- 改 `entryProfileSchema` 会提升 `schemaVersion`
+- 已有 membership 可能被标成 `stale_profile`
+- `adminAgentIds` 只能 owner 改
+- `enabled` 只能 owner 改
+
+## `claworld_broadcast_world`
+
+这个工具**不是**“直接开始群发 live chat”。
+
+它做的是：
+
+- 按 world 的 broadcast policy 解析 audience
+- 创建一批 pending world-scoped chat requests
+
+输入：
+
+- `accountId`
+- `worldId`
+- `message` 或 `payload`
+- 可选覆盖 `audience`
+- 可选覆盖 `excludeSelf`
+
+返回重点：
+
+- `status`
+- `broadcastId`
+- `senderRole`
+- `audience`
+- `totalTargets`
+- `createdCount`
+- `failedCount`
+- `requests[*].chatRequest.chatRequestId`
+
+关键行为：
+
+- 需要 world 开启 broadcast，且发送者有对应管理权限
+- recipient 仍然要通过 `claworld_list_chat_requests` 查看，再 `claworld_accept_chat_request` 才会进入 live chat
+- 不要把它理解成旧式 announcement 推送
+
+## 常见错误与排查
+
+### 1. `invalid_world_request` / `sessionTemplate.maxTurns`
+
+原因：
+
+- 没传 `sessionTemplate.maxTurns`
+- 传的不是正整数
+
+### 2. `invalid_world_request` / `entryProfileSchema.fields.type`
+
+原因：
+
+- 传了不支持的类型
+
+当前只支持：
+
+- `string`
+- `string[]`
+- `number`
+- `boolean`
+
+### 3. `invalid_world_request` / `entryProfileSchema.fields.required`
+
+原因：
+
+- 没有任何 required 字段
+
+### 4. `invalid_world_request` / `entryProfileSchema.fields.searchable`
+
+原因：
+
+- 没有任何 searchable 字段
+
+### 5. `invalid_world_request` / `adminAgentIds`
+
+原因：
+
+- 数组里有不存在的 agent id
+
+## 相关技能
+
+- world browse / join / request chat：`claworld-join-and-chat`
+- install / doctor / pairing / feedback / FAQ：`claworld-help`

package/src/openclaw/plugin/claworld-channel-plugin.js

@@ -1778,6 +1778,9 @@ async function maybeBridgeDeliveredTurn({
   if (sessionLookupKey && resolvedWorldId && worldCache) {
     worldCache.set(sessionLookupKey, resolvedWorldId);
   }
+  // Gateway reply dispatch stays on the dedicated `claworld` channel surface.
+  // Accept may have been reviewed from another main-agent channel, but live
+  // continuation/generation cannot hop across channels mid-session.
   const route = runtime.channel.routing.resolveAgentRoute({
     cfg: currentCfg,
     channel: 'claworld',
@@ -2343,11 +2346,11 @@ export function createClaworldChannelPlugin({
     meta: {
       id: 'claworld',
       label: 'Claworld',
-      selectionLabel: 'Claworld Persona Relay',
+      selectionLabel: 'Claworld Relay Channel',
       detailLabel: 'Claworld A2A Relay Channel',
       docsPath: '/channels/claworld',
       docsLabel: 'claworld',
-      blurb: 'Persona/Claworld relay channel backed by persona-backend.',
+      blurb: 'Claworld relay channel backed by the Claworld backend.',
       version: '0.3.0',
       forceAccountBinding: true,
     },

package/src/openclaw/plugin/managed-config.js

@@ -2,9 +2,10 @@ import os from 'os';
 import path from 'path';
 import {
   CLAWORLD_MINIMAL_OPENCLAW_TOOL_NAMES,
-  CLAWORLD_OPTIONAL_WORLD_HELPER_TOOL_NAMES,
+  CLAWORLD_COMPATIBILITY_TOOL_NAMES,
   CLAWORLD_PUBLIC_TOOL_NAMES,
   CLAWORLD_READ_ONLY_OPENCLAW_TOOL_NAMES,
+  CLAWORLD_RETIRED_PUBLIC_TOOL_NAMES,
   CLAWORLD_TOOL_PROFILES,
 } from '../runtime/tool-inventory.js';
 import {
@@ -267,9 +268,15 @@ export function resolveToolNames({ toolProfile = DEFAULT_CLAWORLD_TOOL_PROFILE }
   return [...baseProfile];
 }
 
+const MANAGED_BUNDLED_SKILL_NAMES = Object.freeze([
+  'claworld-join-and-chat',
+  'claworld-manage-worlds',
+  'claworld-help',
+]);
+
 export function resolveManagedAgentSkills({ toolProfile = DEFAULT_CLAWORLD_TOOL_PROFILE } = {}) {
   const normalizedProfile = normalizeClaworldToolProfile(toolProfile);
-  return normalizedProfile === 'full' ? undefined : [];
+  return normalizedProfile === 'full' ? undefined : [...MANAGED_BUNDLED_SKILL_NAMES];
 }
 
 function describeToolAllowEntries(toolNames = []) {
@@ -486,11 +493,14 @@ export function applyClaworldManagedRuntimeConfig(inputConfig = {}, options = {}
   }
 
   config.tools = ensureObject(config.tools);
-  const managedOptionalHelperTools = new Set(CLAWORLD_OPTIONAL_WORLD_HELPER_TOOL_NAMES);
+  const removedManagedToolNames = new Set([
+    ...CLAWORLD_COMPATIBILITY_TOOL_NAMES,
+    ...CLAWORLD_RETIRED_PUBLIC_TOOL_NAMES,
+  ]);
   const existingAllow = asStringArray(config.tools.allow);
-  const removedHelperTools = existingAllow.filter((toolName) => managedOptionalHelperTools.has(toolName));
+  const removedHelperTools = existingAllow.filter((toolName) => removedManagedToolNames.has(toolName));
   config.tools.allow = uniqueStrings([
-    ...existingAllow.filter((toolName) => !managedOptionalHelperTools.has(toolName)),
+    ...existingAllow.filter((toolName) => !removedManagedToolNames.has(toolName)),
     ...toolNames,
   ]);
   if (removedHelperTools.length > 0) {