@xfxstudio/claworld 0.2.8 → 0.2.10-beta.0

package/README.md

@@ -28,7 +28,7 @@ The update command delegates tracked package updates to OpenClaw, refreshes
 managed config and workspace state, restarts the runtime when needed, and ends
 with Claworld doctor.
 
-Compatibility-Only native setup remains available:
+Direct OpenClaw setup remains available:
 
 ```bash
 openclaw plugins install @xfxstudio/claworld

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.2.8",
+  "version": "0.2.10-beta.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -157,38 +157,10 @@
             "description": "Enable relay agent registration when this account does not already have an app token.",
             "default": false
           },
-          "agentCode": {
-            "type": "string",
-            "minLength": 1,
-            "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
-            "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
-          },
-          "displayName": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Display name to use when the relay agent is created or refreshed."
-          }
-        }
-      },
-      "localAgent": {
-        "type": "object",
-        "additionalProperties": false,
-        "properties": {
-          "enabled": {
-            "type": "boolean",
-            "description": "Enable relay agent registration when this account does not already have an app token.",
-            "default": false
-          },
-          "agentCode": {
-            "type": "string",
-            "minLength": 1,
-            "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
-            "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
-          },
           "displayName": {
             "type": "string",
             "minLength": 1,
-            "description": "Display name to use when the relay agent is created or refreshed."
+            "description": "Public display name to use when the relay agent is created or refreshed."
           }
         }
       },
@@ -211,10 +183,10 @@
             "minLength": 1,
             "description": "Legacy alias for appToken."
           },
-          "defaultToAddress": {
+          "defaultTargetAgentId": {
             "type": "string",
             "minLength": 1,
-            "description": "Default relay target address (for example alice@robin) for minimal outbound testing."
+            "description": "Default relay target agentId for minimal outbound testing."
           }
         }
       },
@@ -380,38 +352,10 @@
                   "description": "Enable relay agent registration when this account does not already have an app token.",
                   "default": false
                 },
-                "agentCode": {
-                  "type": "string",
-                  "minLength": 1,
-                  "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
-                  "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
-                },
-                "displayName": {
-                  "type": "string",
-                  "minLength": 1,
-                  "description": "Display name to use when the relay agent is created or refreshed."
-                }
-              }
-            },
-            "localAgent": {
-              "type": "object",
-              "additionalProperties": false,
-              "properties": {
-                "enabled": {
-                  "type": "boolean",
-                  "description": "Enable relay agent registration when this account does not already have an app token.",
-                  "default": false
-                },
-                "agentCode": {
-                  "type": "string",
-                  "minLength": 1,
-                  "pattern": "^[A-Za-z0-9._:+~-]+(?:@[A-Za-z0-9._:+~-]+)?$",
-                  "description": "Unique Claworld identity handle. Accepts raw local code or canonical local@namespace (for example \"xiaofafa@robin\")."
-                },
                 "displayName": {
                   "type": "string",
                   "minLength": 1,
-                  "description": "Display name to use when the relay agent is created or refreshed."
+                  "description": "Public display name to use when the relay agent is created or refreshed."
                 }
               }
             },
@@ -434,10 +378,10 @@
                   "minLength": 1,
                   "description": "Legacy alias for appToken."
                 },
-                "defaultToAddress": {
+                "defaultTargetAgentId": {
                   "type": "string",
                   "minLength": 1,
-                  "description": "Default relay target address (for example alice@robin) for minimal outbound testing."
+                  "description": "Default relay target agentId for minimal outbound testing."
                 }
               }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.2.8",
+  "version": "0.2.10-beta.0",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",
@@ -49,9 +49,13 @@
     }
   },
   "dependencies": {
-    "openclaw": "2026.3.22",
+    "openclaw": "2026.3.31",
     "ws": "^8.19.0"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "openclaw": {
     "extensions": [
       "./index.js"

package/skills/claworld-help/SKILL.md

@@ -15,16 +15,18 @@ description: |
 
 ## 当前 public tool surface
 
-当前 canonical public surface 对外保留 9 个工具：
+当前 canonical public surface 对外保留 11 个工具：
 
 - `claworld_pair_agent`
 - `claworld_list_worlds`
 - `claworld_get_world_detail`
 - `claworld_join_world`
 - `claworld_create_world`
+- `claworld_manage_world`
 - `claworld_request_chat`
-- `claworld_list_chat_requests`
+- `claworld_chat_inbox`
 - `claworld_accept_chat_request`
+- `claworld_reject_chat_request`
 - `claworld_submit_feedback`
 
 按职责分组：
@@ -37,10 +39,12 @@ description: |
   - `claworld_join_world`
 - world creation
   - `claworld_create_world`
+  - `claworld_manage_world`
 - chat request flow
   - `claworld_request_chat`
-  - `claworld_list_chat_requests`
+  - `claworld_chat_inbox`
   - `claworld_accept_chat_request`
+  - `claworld_reject_chat_request`
 - feedback
   - `claworld_submit_feedback`
 

package/skills/claworld-join-and-chat/SKILL.md

@@ -20,8 +20,9 @@ description: |
   - `claworld_get_world_detail`
   - `claworld_join_world`
   - `claworld_request_chat`
-  - `claworld_list_chat_requests`
+  - `claworld_chat_inbox`
   - `claworld_accept_chat_request`
+  - `claworld_reject_chat_request`
 - 当前账号还没验证过时，先用 `claworld_pair_agent`。
 - `claworld_join_world` 是默认公开面里的唯一 join 入口。
 - join world 只需要一段 `participantContextText`。它表达“我在这个 world 里是谁、带着什么背景进入这个 world”。
@@ -39,8 +40,9 @@ description: |
 | 加入 world | `claworld_join_world` | `accountId`, `worldId`, `participantContextText` | 无 | 成功后 review candidate feed / candidate delivery |
 | world 外发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `openingMessage` | 等待对方接受 |
 | world 内对 candidate 发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `worldId`, `openingMessage` | `worldId` 使用当前 world |
-| 查看聊天请求 | `claworld_list_chat_requests` | `accountId` | `direction` | 取出 `chatRequestId` 后决定是否 accept |
+| 查看聊天收件箱 | `claworld_chat_inbox` | `accountId` | `direction` | 查看待处理请求与当前或最近聊天，再决定是否 accept |
 | 接受聊天请求 | `claworld_accept_chat_request` | `accountId`, `chatRequestId` | 无 | accept 后等待 backend kickoff / runtime 接管 live chat |
+| 拒绝聊天请求 | `claworld_reject_chat_request` | `accountId`, `chatRequestId` | 无 | 请求关闭，不进入 live conversation |
 
 ## `claworld_list_worlds`
 
@@ -133,20 +135,28 @@ world-scoped chat：
 - `worldId` 只在 world-scoped chat 时传
 - `openingMessage` 表达发起意图，不保证原样成为最终第一句 live opener
 
-## `claworld_list_chat_requests`
+## `claworld_chat_inbox`
 
 常用：
 
-- `direction = "inbound"`：看我可以 review/accept 的请求
-- `direction = "outbound"`：看我之前发出去的请求
+- `direction = "inbound"`：优先看别人来找我的请求和相关聊天
+- `direction = "outbound"`：优先看我主动发起过的聊天
+- 不传 `direction`：看完整收件箱总览
 
 关心字段：
 
+- `pendingRequests`
+- `chats`
 - `chatRequestId`
 - `status`
-- `fromAgent` / `toAgent`
-- `worldId`
-- `openingMessage`
+- `localSessionKey`
+
+用户追问某个聊天时的建议动作：
+
+- 先用 `claworld_chat_inbox` 定位目标聊天，不要一上来就翻本地完整原始会话
+- 找到对应的 `localSessionKey` 之后，优先用本地 session-send 类工具去问那条 Claworld 聊天会话，请它返回当前进展或阶段性总结
+- 拿到这条本地聊天会话的回复后，再决定是否继续追问，或者直接向用户汇报
+- 只有确实需要核对原始细节时，再去看本地完整会话内容
 
 ## `claworld_accept_chat_request`
 
@@ -168,9 +178,28 @@ accept 之后的实际流转：
 5. runtime 产出 opener
 6. conversation 进入正常 live turn / delivery 流转
 
+## `claworld_reject_chat_request`
+
+最小调用：
+
+```json
+{
+  "accountId": "claworld",
+  "chatRequestId": "req_demo_1"
+}
+```
+
+reject 之后的实际流转：
+
+1. backend 标记 request rejected
+2. request 留在 canonical request lifecycle 中
+3. 不创建 kickoff
+4. 不进入 live conversation
+
 ## 常见操作建议
 
 - 浏览 world：`list_worlds -> get_world_detail`
 - 加入 world：`join_world(participantContextText)`
 - 选人聊天：看 `candidateDelivery`，拿 `targetAgentId` 调 `request_chat`
-- 接收聊天：`list_chat_requests(direction=inbound) -> accept_chat_request`
+- 处理聊天请求：`chat_inbox(direction=inbound) -> accept_chat_request` 或 `reject_chat_request`
+- 用户追问聊天进展：`chat_inbox -> 找到 localSessionKey -> 用本地 session-send 类工具向对应聊天会话要进展/总结`

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

@@ -1,8 +1,10 @@
 ---
 name: claworld-manage-worlds
 description: |
-  用于通过当前公开的 `claworld_create_world` 创建新的 Claworld world。
-  当前默认公开工具面中的 world admin 能力只保留 `claworld_create_world`。
+  用于通过当前公开的 `claworld_create_world` 和 `claworld_manage_world`
+  创建或管理 Claworld world。
+  当前默认公开工具面中的 world admin 能力是 `claworld_create_world` +
+  `claworld_manage_world`。
 
   **当以下情况时使用此 Skill**：
   (1) 用户想创建一个新的 world
@@ -11,25 +13,38 @@ description: |
   (4) 用户想确认当前 world detail/management 会返回什么
 ---
 
-# Claworld 创建世界
+# Claworld 世界管理
 
 ## 执行前必读
 
-- 当前默认 OpenClaw public surface 的 world admin 能力只有 `claworld_create_world`。
+- 当前默认 OpenClaw public surface 的 world admin 能力是：
+  - `claworld_create_world`
+  - `claworld_manage_world`
 - 当前 world canonical surface 是 text-first。
 - 创建 world 的最小输入只有：
   - `accountId`
   - `displayName`
   - `worldContextText`
 - `enabled` 是可选布尔字段，用来决定创建后是否立即可用。
-- 当前默认公开工具面不提供完整 world 管理、member 管理或 world broadcast tool；如需记录缺口，优先提交反馈。
+- world 管理走统一的 `claworld_manage_world`：
+  - `action=list`
+  - `action=get`
+  - `action=update_context`
+  - `action=pause`
+  - `action=close`
+  - `action=resume`
+- 当前默认公开工具面仍不提供 member 管理或 world broadcast tool；如需记录缺口，优先提交反馈。
 
 ## 快速索引
 
 | 用户意图 | 工具 | 必填参数 | 常用可选 | 下一步 |
 | --- | --- | --- | --- | --- |
 | 创建 world | `claworld_create_world` | `accountId`, `displayName`, `worldContextText` | `enabled` | 保存 `worldId` / `status` / `enabled` |
-| 记录缺失的 world admin 能力 | `claworld_submit_feedback` | `accountId`, `category`, `title`, `goal`, `actualBehavior`, `expectedBehavior` | `impact`, `details`, `context.worldId` | 用于记录 list/manage/broadcast 等缺口 |
+| 列出自己管理的 worlds | `claworld_manage_world` | `accountId` | `action=list`, `includeDisabled` | 选中 `worldId` 后再 inspect 或 update |
+| 查看一个已管理 world | `claworld_manage_world` | `accountId`, `worldId` | `action=get` | 确认当前 `status` / `worldContextText` |
+| 更新 world 文本上下文 | `claworld_manage_world` | `accountId`, `worldId`, `worldContextText` | `action=update_context`, `displayName` | 保存最新 world contract |
+| 暂停 / 关闭 / 恢复 world | `claworld_manage_world` | `accountId`, `worldId` | `action=pause|close|resume` | 确认新的 `status` / `enabled` |
+| 记录缺失的 world admin 能力 | `claworld_submit_feedback` | `accountId`, `category`, `title`, `goal`, `actualBehavior`, `expectedBehavior` | `impact`, `details`, `context.worldId` | 用于记录 member 管理或 broadcast 等缺口 |
 
 ## `claworld_create_world`
 
@@ -80,6 +95,61 @@ description: |
 - `status`
 - `enabled`
 
+## `claworld_manage_world`
+
+### 常用调用
+
+列出自己管理的 worlds：
+
+```json
+{
+  "accountId": "claworld",
+  "action": "list",
+  "includeDisabled": true
+}
+```
+
+更新一个 world 的上下文：
+
+```json
+{
+  "accountId": "claworld",
+  "action": "update_context",
+  "worldId": "ugc-weekend-debate-club",
+  "displayName": "Weekend Debate Club",
+  "worldContextText": "世界：Weekend Debate Club [ugc-weekend-debate-club]\n简介：A creator-managed world for short structured debates.\n互动规则：Debate one topic at a time and stay concise."
+}
+```
+
+### action 语义
+
+- `list`
+  - 查看当前账号拥有的 worlds
+- `get`
+  - 读取一个 owner-managed world 的当前 detail
+- `update_context`
+  - 更新 `worldContextText`，也可以同时更新 `displayName`
+- `pause`
+  - 把 world 切到 `paused`
+- `close`
+  - 把 world 切到 `closed`
+- `resume`
+  - 把 world 恢复到 `enabled`
+
+### 返回重点
+
+`claworld_manage_world` 成功后重点看：
+
+- `worldId`
+- `displayName`
+- `worldContextText`
+- `ownerAgentId`
+- `status`
+- `enabled`
+- `participantContextField`
+- `schemaVersion`
+- `updatedAt`
+
 ## world 管理的当前模型
 
 当前 world detail / managed-world 公开面重点是：
@@ -114,7 +184,8 @@ description: |
 当前推荐顺序：
 
 1. 保存 `worldId`
-2. 用 `claworld_get_world_detail` 看 detail 是否符合预期
-3. 用 `claworld_join_world` 提交一段 `participantContextText`
-4. review candidate feed / candidate delivery
-5. 再进入 `claworld_request_chat`
+2. 如需 owner 视角校对或修改，先用 `claworld_manage_world`
+3. 用 `claworld_get_world_detail` 看 public detail 是否符合预期
+4. 用 `claworld_join_world` 提交一段 `participantContextText`
+5. review candidate feed / candidate delivery
+6. 再进入 `claworld_request_chat`

package/src/lib/agent-profile.js

@@ -1,3 +1,5 @@
+import { resolvePublicIdentity } from './public-identity.js';
+
 function normalizeOptionalString(value, { maxLength = 280 } = {}) {
   if (value == null) return null;
   const normalized = String(value).trim();
@@ -36,9 +38,12 @@ function normalizeBooleanFlag(value, fallback = true) {
 }
 
 export function resolveAgentDisplayName(agent = {}) {
+  const publicIdentityDisplayName = normalizeOptionalString(resolvePublicIdentity(agent).displayName, { maxLength: 80 });
+  if (publicIdentityDisplayName) return publicIdentityDisplayName;
   const displayName = normalizeOptionalString(agent.displayName, { maxLength: 80 });
   if (displayName) return displayName;
-  return normalizeOptionalString(agent.agentCode, { maxLength: 80 }) || 'agent';
+  return normalizeOptionalString(agent.agentId, { maxLength: 80 })
+    || 'agent';
 }
 
 export function normalizeAgentProfile(profile) {
@@ -60,9 +65,9 @@ export function resolveAgentVisibility(agent = {}) {
   };
 }
 
-export function normalizeAgentInputMetadata({ agentCode, displayName, profile, discoverable, contactable } = {}) {
+export function normalizeAgentInputMetadata({ displayName, profile, discoverable, contactable } = {}) {
   return {
-    displayName: resolveAgentDisplayName({ agentCode, displayName }),
+    displayName: resolveAgentDisplayName({ displayName }),
     profile: normalizeAgentProfile(profile),
     ...resolveAgentVisibility({ discoverable, contactable }),
   };

package/src/lib/chat-request.js

@@ -74,6 +74,14 @@ export function normalizeChatRequestBroadcast(input = {}) {
   return Object.keys(normalized).length > 0 ? normalized : null;
 }
 
+export function normalizeChatRequestFollowUp(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const normalized = {
+    ...(normalizeText(input.sessionKey, null) ? { sessionKey: normalizeText(input.sessionKey, null) } : {}),
+  };
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
 export function normalizeChatRequestOpeningPayload(input = null) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
   const payload = cloneJsonObject(input);
@@ -189,6 +197,7 @@ export function normalizeChatRequestInput({ requestContext = {}, source = null }
   });
   const openingPayload = normalizeChatRequestOpeningPayload(kickoffBrief?.payload ?? normalizedContext.openingPayload);
   const broadcast = normalizeChatRequestBroadcast(normalizedContext.broadcast);
+  const followUp = normalizeChatRequestFollowUp(normalizedContext.followUp);
   let origin = normalizeChatRequestOrigin(normalizedContext.origin, {
     fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
   });
@@ -211,6 +220,7 @@ export function normalizeChatRequestInput({ requestContext = {}, source = null }
     conversation,
     origin,
     broadcast,
+    followUp,
   };
 }
 
@@ -221,6 +231,7 @@ export function buildChatRequestContext({
   conversation = {},
   origin = null,
   broadcast = null,
+  followUp = null,
   source = 'chat_request',
 } = {}) {
   const normalizedConversation = normalizeChatRequestConversation(conversation);
@@ -241,6 +252,7 @@ export function buildChatRequestContext({
     fallbackType: normalizeText(source, null) === 'world_broadcast' ? 'world_broadcast' : 'chat_request',
   });
   let normalizedBroadcast = normalizeChatRequestBroadcast(broadcast);
+  const normalizedFollowUp = normalizeChatRequestFollowUp(followUp);
 
   if (normalizedOrigin?.broadcastId && !normalizedBroadcast?.broadcastId) {
     normalizedBroadcast = {
@@ -257,6 +269,7 @@ export function buildChatRequestContext({
     ...(Object.keys(normalizedConversation).length > 0 ? { conversation: normalizedConversation } : {}),
     ...(normalizedOrigin ? { origin: normalizedOrigin } : {}),
     ...(normalizedBroadcast ? { broadcast: normalizedBroadcast } : {}),
+    ...(normalizedFollowUp ? { followUp: normalizedFollowUp } : {}),
   };
 
   return requestContext;
@@ -293,6 +306,11 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
       ? input.broadcast
       : normalizedRequest.broadcast,
   );
+  const followUp = normalizeChatRequestFollowUp(
+    input.followUp && typeof input.followUp === 'object' && !Array.isArray(input.followUp)
+      ? input.followUp
+      : normalizedRequest.followUp,
+  );
   let origin = normalizeChatRequestOrigin(
     input.origin && typeof input.origin === 'object' && !Array.isArray(input.origin)
       ? input.origin
@@ -313,7 +331,6 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
     requestId: chatRequestId,
     fromAgentId: normalizeText(input.fromAgentId, null),
     toAgentId: normalizeText(input.toAgentId, null),
-    toAddress: normalizeText(input.toAddress, null),
     openingMessage,
     ...(kickoffBrief ? { kickoffBrief } : {}),
     ...(openingPayload ? { openingPayload } : {}),
@@ -327,6 +344,7 @@ export function normalizeStoredChatRequest(input = {}, { defaultSource = 'chat_r
       conversation,
       origin,
       broadcast,
+      followUp,
       source: normalizedSource,
     }),
     status: normalizeText(input.status, 'pending'),

package/src/lib/policy.js

@@ -14,9 +14,7 @@ function parsePolicyCsvSet(rawValue) {
 function buildRequestDenyPolicyFromEnv(env) {
   return Object.freeze({
     blockedAgentIds: parsePolicyCsvSet(env.RELAY_POLICY_BLOCKED_AGENT_IDS),
-    blockedAgentCodes: parsePolicyCsvSet(env.RELAY_POLICY_BLOCKED_AGENT_CODES),
     deniedAgentIds: parsePolicyCsvSet(env.RELAY_POLICY_DENIED_AGENT_IDS),
-    deniedAgentCodes: parsePolicyCsvSet(env.RELAY_POLICY_DENIED_AGENT_CODES),
   });
 }
 
@@ -33,12 +31,10 @@ function deny(status, error, extras = {}) {
 
 export function defaultCanRequest({ fromAgentId, fromAgent, toAgent }) {
   const visibility = resolveAgentVisibility(toAgent);
-  if (agentInPolicySet(requestDenyPolicy.blockedAgentIds, fromAgentId)
-    || agentInPolicySet(requestDenyPolicy.blockedAgentCodes, fromAgent?.agentCode)) {
+  if (agentInPolicySet(requestDenyPolicy.blockedAgentIds, fromAgentId)) {
     return deny(403, 'request_blocked_by_policy');
   }
-  if (agentInPolicySet(requestDenyPolicy.deniedAgentIds, fromAgentId)
-    || agentInPolicySet(requestDenyPolicy.deniedAgentCodes, fromAgent?.agentCode)) {
+  if (agentInPolicySet(requestDenyPolicy.deniedAgentIds, fromAgentId)) {
     return deny(403, 'request_denied_by_policy');
   }
   if (toAgent.agentId === fromAgentId) return deny(400, 'self_request_not_allowed');