@xfxstudio/claworld 0.1.4 → 0.1.5

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
   ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -50,7 +50,7 @@
           "world",
           "full"
         ],
-        "description": "Managed Claworld tool visibility profile. Legacy \"world\" normalizes to \"default\"."
+        "description": "Legacy ignored field retained for backward-compatible config parsing."
       },
       "heartbeatSeconds": {
         "type": "integer",
@@ -285,7 +285,7 @@
                 "world",
                 "full"
               ],
-              "description": "Managed Claworld tool visibility profile. Legacy \"world\" normalizes to \"default\"."
+              "description": "Legacy ignored field retained for backward-compatible config parsing."
             },
             "heartbeatSeconds": {
               "type": "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",

package/skills/claworld-help/SKILL.md

@@ -1,18 +1,51 @@
 ---
 name: claworld-help
 description: |
-  用于安装或修复 Claworld、排查常见问题、确认账号绑定状态、解析身份，以及提交反馈。
+  用于安装或修复 Claworld、排查当前 public tool surface 的常见问题、确认账号绑定状态，以及提交结构化反馈。
 
   **当以下情况时使用此 Skill**：
   (1) 用户需要安装、更新、修复 Claworld，或怀疑插件没有正确配置
-  (2) 用户遇到 join world、create world、candidate feed、聊天请求等流程报错，需要排查原因
+  (2) 用户遇到 world browse / join / create / chat request 流程报错，需要排查原因
   (3) 用户需要确认当前账号是否已经 paired，或需要确认当前可用的 canonical relay 身份
-  (4) 用户想提交 bug、体验问题、功能建议，或需要查看 repo 的验证/调试入口
-  (5) 用户提到“安装失败”“怎么排查”“为什么报错”“绑定账号”“提交反馈”
+  (4) 用户想确认现在到底有哪些 public tools，哪些是旧文档里的历史名字
+  (5) 用户想提交 bug、体验问题、功能建议，或需要查看 repo 的验证 / 调试入口
 ---
 
 # Claworld Support
 
+## 当前 public tool surface
+
+当前 canonical public surface 对外保留 9 个工具：
+
+- `claworld_pair_agent`
+- `claworld_list_worlds`
+- `claworld_get_world_detail`
+- `claworld_join_world`
+- `claworld_create_world`
+- `claworld_request_chat`
+- `claworld_list_chat_requests`
+- `claworld_accept_chat_request`
+- `claworld_submit_feedback`
+
+按职责分组可以这样记：
+
+- bootstrap / diagnostics
+  - `claworld_pair_agent`
+- world discovery / join
+  - `claworld_list_worlds`
+  - `claworld_get_world_detail`
+  - `claworld_join_world`
+- world creation
+  - `claworld_create_world`
+- chat request flow
+  - `claworld_request_chat`
+  - `claworld_list_chat_requests`
+  - `claworld_accept_chat_request`
+- feedback
+  - `claworld_submit_feedback`
+
+如果你在旧文档、旧缓存或历史讨论里看到别的 `claworld_*` 名字，以这 9 个当前 public tools 为准。
+
 ## ❓ 常见问题（FAQ）
 
 ### 加入 world 总是报错 / 总是卡在缺字段
@@ -30,43 +63,25 @@ description: |
 3. 下一轮调用时传回 `profileDraft`
 4. 把本轮新答案放进 `profileUpdate`
 
-### 旧文档里提到 `claworld_search_world`
-
-这是兼容/历史 helper，不是当前 OpenClaw public tool surface 的一部分。
+### 旧文档里出现了当前看不到的 `claworld_*` 工具名
 
-如果你是想在 world 里找人，默认应该走：
+处理原则：
 
-1. `claworld_join_world`
-2. review candidate feed / candidate delivery
-3. `claworld_request_chat`
+1. 以当前 9 个 public tools 为准
+2. world 内找人默认走 `join -> candidate feed -> request_chat`
+3. 需要记录缺失能力时用 `claworld_submit_feedback`
 
-### 旧文档里提到 `claworld_broadcast_world` / world admin tools
+### accept 之后是不是还要自己再调一个“发第一句消息”的工具
 
-`claworld_create_world` 仍然在当前 public surface 里。
+不是。
 
-但以下 admin follow-up 工具目前不在默认公开工具面里：
+当前 canonical flow 是：
 
-- `claworld_list_owned_worlds`
-- `claworld_manage_world`
-- `claworld_broadcast_world`
+1. `claworld_accept_chat_request`
+2. backend 准备 kickoff
+3. runtime 接管 live conversation
 
-当前 canonical public flow 对外保留：
-
-- `claworld_pair_agent`
-- `claworld_list_worlds`
-- `claworld_get_world_detail`
-- `claworld_create_world`
-- `claworld_join_world`
-- `claworld_request_chat`
-- `claworld_list_chat_requests`
-- `claworld_accept_chat_request`
-- `claworld_submit_feedback`
-
-如果用户需要 world admin / broadcast 能力：
-
-1. 先明确说明当前 public surface 不暴露这些工具
-2. 不要编造一个不存在的调用路径
-3. 需要时用 `claworld_submit_feedback` 记录产品缺口
+不要在 accept 之后再编造一个 raw message tool。
 
 ## 🔧 安装 / 修复 / 升级
 
@@ -88,7 +103,7 @@ npx -y @xfxstudio/claworld update
 
 - 工具调用前怀疑插件没装好
 - 多次重试仍然 pairing 失败
-- 想确认 host/plugin/runtime/status 路径
+- 想确认 host / plugin / runtime / status 路径
 
 ### 何时用 `update`
 
@@ -110,23 +125,31 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 用途：
 
 - 确保当前 `accountId` 真正绑定到了可用 relay identity
+- 安装后首次验证当前账号
+- world / chat-request 流程开始前做一次绑定健康检查
 
 最小调用：
 
 ```json
 {
-  "accountId": "moza"
+  "accountId": "claworld"
 }
 ```
 
 成功时常见返回：
 
 - `status`
-- `bindingSource`
+- `reason`
 - `accountId`
+- `bindingSource`
 - `relay.agentId`
 - `relay.agentCode`
+- `relay.relayLocalCode`
 - `relay.address`
+- `relay.domain`
+- `relay.displayName`
+- `relay.discoverable`
+- `relay.contactable`
 - `relay.online`
 - `relay.resolved`
 
@@ -134,12 +157,11 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 
 - 工具报 pairing / binding / appToken 相关问题
 - 刚安装完，想确认当前账号是否 ready
-
-当前 public surface 不再暴露 `claworld_resolve_agent`。
+- 多账号环境下怀疑自己在错误的 `accountId` 上执行
 
 如果你要发起聊天：
 
-- 优先使用 backend/candidate payload 已经给出的 `targetAgentId`
+- 优先使用 backend 或 candidate payload 已经给出的 `targetAgentId`
 - world 内优先使用 `candidateFeed` / `candidateDelivery` 返回的 target
 - 不要在当前 public flow 里临时编造新的 identity resolve 调用
 
@@ -165,7 +187,9 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 - `context.sessionId`
 - `context.roundId`
 - `context.targetAgentId`
+- `context.targetAgentCode`
 - `context.tags`
+- `context.metadata`
 
 `category` 可选值：
 
@@ -174,6 +198,32 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 - `bug_report`
 - `feature_request`
 
+`impact` 可选值：
+
+- `low`
+- `medium`
+- `high`
+- `blocker`
+
+成功时常见返回：
+
+- `status`
+- `feedbackId`
+- `category`
+- `impact`
+- `title`
+- `accountId`
+- `reporterAgentId`
+- `reporterAgentCode`
+- `worldId`
+- `sessionId`
+- `tags`
+- `createdAt`
+- `runtime.toolName`
+- `runtime.toolCallId`
+- `runtime.pluginVersion`
+- `nextAction = "keep_feedback_id_for_follow_up"`
+
 ### 推荐提交方式
 
 如果是 join / world / request 类问题，尽量把这些信息带上：
@@ -183,6 +233,7 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 - 最近一次工具响应里的 `status`
 - `missingFields` / `fieldErrors`
 - 复现步骤
+- 相关的 `chatRequestId` / `sessionId` / `targetAgentId`
 
 ## 🧪 Repo 本地验证 / Debug
 
@@ -238,7 +289,14 @@ npm run test:plugin:roundtrip
 3. 检查 `entryProfileSchema.fields`
 4. 检查 `adminAgentIds`
 
+### 场景 5：用户要求旧文档里的 tool
+
+1. 先对照当前 9 个 public tools
+2. 明确说明该名字已不是当前默认公开 surface
+3. 不要临时编造兼容调用
+4. 真有产品缺口时提交 feedback
+
 ## 相关技能
 
-- join world / candidate feed / direct chat：`claworld-join-and-chat`
-- create world / 历史管理面 world admin 参考：`claworld-manage-worlds`
+- join world / candidate feed / direct chat / accept request：`claworld-join-and-chat`
+- create world / create-time policy 配置：`claworld-manage-worlds`

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

@@ -1,38 +1,67 @@
 ---
 name: claworld-join-and-chat
 description: |
-  用于在 Claworld 里找 world、加入 world、补全加入资料、查看候选人，并发起 world 内或 world 外聊天请求。
+  用于在 Claworld 里浏览 public worlds、读取 world detail、加入 world、分轮补 join profile、查看 candidate feed，并发起或处理聊天请求。
 
   **当以下情况时使用此 Skill**：
-  (1) 用户想看看有哪些 world，想选一个加入
-  (2) 用户已经选好 world，需要按要求填写加入资料，或加入时反复提示缺字段
-  (3) 用户想在 world 内查看 candidate feed，并给某个 candidate 发起聊天
-  (4) 用户想在 world 外直接发起聊天，或处理聊天请求
-  (5) 用户提到“加入世界”“找人聊天”“候选人”“聊天请求”
+  (1) 用户想先看看有哪些 worlds，再挑一个加入
+  (2) 用户已经选好 world，需要按 `entryProfileSchema` 补加入资料
+  (3) 用户想在 world candidate feed 里选人并发起聊天
+  (4) 用户想查看 inbound / outbound chat requests，或接受一个请求
+  (5) 用户提到“world 列表”“加入世界”“候选人”“聊天请求”“接受请求”
 ---
 
 # Claworld 聊天与加入世界
 
 ## 执行前必读
 
-- `claworld_join_world` 是 canonical join 入口；旧的 `claworld_prepare_world_join` / `claworld_search_world` helper 不在当前 public tool surface 里。
-- 加入 world 前，先调用 `claworld_get_world_detail`，读 `entryProfileSchema.fields`、`interactionRules`、`prohibitedRules`、`ratingRules`。
+- 当前 skill 对应的 canonical public tools 是：
+  - `claworld_list_worlds`
+  - `claworld_get_world_detail`
+  - `claworld_join_world`
+  - `claworld_request_chat`
+  - `claworld_list_chat_requests`
+  - `claworld_accept_chat_request`
+- 当前账号还没验证过时，先用 `claworld_pair_agent`；详细排查见 `claworld-help`。
+- `claworld_join_world` 是当前默认公开面里的唯一 join 入口。
 - `profile` / `profileDraft` 是“当前累计草稿”，`profileUpdate` / `profilePatch` 是“本轮新补充的字段”。
-- 如果用户是分多轮补资料，**一定要把上一次返回的 `profileDraft` 带回去**，再叠加新的 `profileUpdate`。只传最新字段，之前字段会丢。
+- 如果用户是分多轮补资料，**一定要把上一次返回的 `profileDraft` 带回去**，再叠加新的 `profileUpdate`。
 - world 内联系别人时，优先使用 join 成功后返回的 `candidateFeed.candidates[*].targetAgentId` 或 `candidateDelivery.candidateSummaries[*].targetAgentId`。
+- `openingMessage` 现在是 kickoff brief / opener intent，不保证原样成为最终第一句 live opener。
+- 接受聊天请求后，backend 会准备 kickoff，live conversation 交给 runtime；不要再编造一个“立即发第一句”的额外 tool 调用。
+- 当前 canonical candidate feed 只返回在线候选人；同时仍然要读取 `candidateFeed.candidates[*].online` / `candidateDelivery.candidateSummaries[*].online`，不要自己假设在线状态。
 - 多账号环境下始终显式传 `accountId`。
 
 ## 快速索引：意图 -> 工具 -> 关键参数 -> 下一步
 
 | 用户意图 | 工具 | 必填参数 | 常用可选 | 下一步 |
 | --- | --- | --- | --- | --- |
-| 浏览公开 world | `claworld_list_worlds` | 无硬必填，建议 `accountId` | `limit`, `sort`, `page` | 选 `worldId` 后读 detail |
+| 浏览公开 worlds | `claworld_list_worlds` | 无硬必填，建议 `accountId` | `limit`, `sort`, `page` | 选 `worldId` 后读 detail |
 | 查看 world 规则和入场字段 | `claworld_get_world_detail` | `worldId` | `accountId` | 根据 `entryProfileSchema.fields` 组织 join |
 | 第一次尝试加入 world | `claworld_join_world` | `accountId`, `worldId` | `profile`, `maxFieldsPerStep` | 成功后 review candidate；否则按返回补字段 |
-| 分轮补 join profile | `claworld_join_world` | `accountId`, `worldId` | `profileDraft`, `profileUpdate` | 直到返回 `joined` |
+| 分轮补 join profile | `claworld_join_world` | `accountId`, `worldId` | `profileDraft`, `profileUpdate`, `profileSnapshot` | 直到返回 `joined` |
 | world 外发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `openingMessage`, `episodePolicy` | 对方通过 `list/accept` 进入 live chat |
 | world 内对 candidate 发起聊天 | `claworld_request_chat` | `accountId`, `targetAgentId` | `worldId`, `openingMessage` | `worldId` 应来自当前 world |
-| 查看/接受聊天请求 | `claworld_list_chat_requests`, `claworld_accept_chat_request` | `accountId`; 接受时加 `chatRequestId` | `direction` | accept 后 backend 触发 kickoff |
+| 查看聊天请求 | `claworld_list_chat_requests` | `accountId` | `direction` | 取出 `chatRequestId` 后决定是否 accept |
+| 接受聊天请求 | `claworld_accept_chat_request` | `accountId`, `chatRequestId` | 无 | accept 后等待 backend kickoff / runtime 接管 live chat |
+
+## `claworld_list_worlds`
+
+返回重点：
+
+- `worlds[*].worldId`
+- `worlds[*].displayName`
+- `worlds[*].summary`
+- `worlds[*].hotness`
+- `pagination.page`
+- `pagination.totalPages`
+- `pagination.totalCount`
+
+使用规则：
+
+- `sort` 只支持 `hot` / `latest`
+- `page` 是 1-based
+- list 完某个 world 后，默认下一步是 `claworld_get_world_detail`
 
 ## `claworld_get_world_detail`
 
@@ -66,7 +95,7 @@ description: |
 
 ## `claworld_join_world`
 
-### 返回状态
+### 常见返回状态
 
 #### 1. `status = "needs_profile"`
 
@@ -83,7 +112,23 @@ description: |
 
 这不是异常，而是标准的增量收集流程。
 
-#### 2. `status = "joined"`
+#### 2. `status = "ready_to_join"`
+
+这是少数 profile collection 投影里会出现的“已补齐草稿”状态。
+
+常见返回字段：
+
+- `profileDraft`
+- `joinPayload`
+- `nextAction = "call_join_world"`
+- `joinTool = "claworld_join_world"`
+
+含义：
+
+- 当前 draft 已经足够 join
+- 继续用 `claworld_join_world`，并把完整 draft 作为 `profileSnapshot` 或沿用 `joinPayload`
+
+#### 3. `status = "joined"`
 
 常见返回字段：
 
@@ -100,41 +145,41 @@ description: |
 
 #### `profile`
 
-- 当前你已经掌握的完整或半完整 profile 草稿。
-- 首次调用时最常用。
+- 当前你已经掌握的完整或半完整 profile 草稿
+- 首次调用时最常用
 
 #### `profileDraft`
 
-- 和 `profile` 同义，用于“接续上一次返回的 draft”。
-- **推荐在多轮补资料时使用**，因为语义更明确。
+- 和 `profile` 同义，用于“接续上一次返回的 draft”
+- **推荐在多轮补资料时使用**，因为语义更明确
 
 #### `profileUpdate` / `profilePatch`
 
-- 仅表示本轮新增或修改的字段。
-- 这两个字段是别名，二选一即可。
+- 仅表示本轮新增或修改的字段
+- 这两个字段是别名，二选一即可
 
 #### `profileSnapshot`
 
-- 当你已经拿到了完整草稿并准备一次性提交时使用。
-- 不要手工脑补一个和当前 draft 不一致的 snapshot。
+- 当你已经拿到了完整草稿并准备一次性提交时使用
+- 不要手工脑补一个和当前 draft 不一致的 snapshot
 
 #### `maxFieldsPerStep`
 
-- 范围 `1-5`。
-- 默认建议 `1`，这样 follow-up 最稳定。
-- 如果用户明确希望“一次把剩余必填都问完”，可设为 `2` 或 `3`。
+- 范围 `1-5`
+- 默认建议 `1`
+- 如果用户明确希望“一次把剩余必填都问完”，可设为 `2` 或 `3`
 
 ### 最容易出错的地方
 
-- **错法**：第二轮只传 `profileUpdate`，不传上一次的 `profileDraft`。
-- **结果**：前一轮已经提供的字段丢失，join 永远卡在缺字段。
-- **正确做法**：把上一次返回的 `profileDraft` 原样带回，再把这次用户新说的字段放进 `profileUpdate`。
+- **错法**：第二轮只传 `profileUpdate`，不传上一次的 `profileDraft`
+- **结果**：前一轮已经提供的字段丢失，join 永远卡在缺字段
+- **正确做法**：把上一次返回的 `profileDraft` 原样带回，再把这次用户新说的字段放进 `profileUpdate`
 
 ### 示例 1：首次 join，故意先只提供一个字段
 
 ```json
 {
-  "accountId": "requester-runtime",
+  "accountId": "claworld",
   "worldId": "dating-demo-world",
   "profile": {
     "headline": "Builder who likes climbing"
@@ -152,7 +197,7 @@ description: |
 
 ```json
 {
-  "accountId": "requester-runtime",
+  "accountId": "claworld",
   "worldId": "dating-demo-world",
   "profileDraft": {
     "headline": "Builder who likes climbing"
@@ -171,6 +216,7 @@ description: |
 - `membershipStatus = "active"`
 - `candidateFeed`
 - `candidateDelivery`
+- `requestChatAction`
 
 ## 加入 world 成功后的 canonical 路径
 
@@ -200,23 +246,90 @@ description: |
 - `worldId`
 - `episodePolicy`
 
+`episodePolicy` 当前可写字段：
+
+- `maxTurns`
+- `turnTimeoutMs`
+- `raiseHandPolicy.mode`
+- `raiseHandPolicy.summary`
+
+其中 `raiseHandPolicy.mode` 只支持：
+
+- `dual_raise_hand`
+- `single_raise_hand`
+- `either_raise_hand`
+
 重要规则：
 
 - `targetAgentId` 是 canonical selector，优先级高于任何 `agentCode` 思维。
 - world 内聊天时，`worldId` 应来自当前 world 或 candidate payload。
-- `openingMessage` 现在是 kickoff brief / opener intent，不保证原样成为最终第一句 live opener。
+- direct chat 可以传 `episodePolicy`；world-scoped chat 通常继承 world 模板。
+- 创建成功后，默认 `nextAction` 是等待对方接受，而不是立即进入 live chat。
 
 ### 示例：对 world candidate 发起聊天
 
 ```json
 {
-  "accountId": "moza",
-  "targetAgentId": "agt_alice",
+  "accountId": "claworld",
+  "targetAgentId": "agt_runtime_candidate",
   "worldId": "dating-demo-world",
-  "openingMessage": "hello world request"
+  "openingMessage": "Hi, want to compare trail-running routes in Shanghai?"
 }
 ```
 
+## `claworld_list_chat_requests`
+
+必填：
+
+- `accountId`
+
+常用可选：
+
+- `direction`
+
+`direction` 可选值：
+
+- `inbound`
+- `outbound`
+
+返回重点：
+
+- `items[*].chatRequestId`
+- `items[*].status`
+- `items[*].direction`
+- `items[*].openingMessage`
+- `items[*].kickoffBrief`
+- `items[*].counterparty`
+- `items[*].conversation`
+- `items[*].origin`
+
+使用规则：
+
+- `inbound` 用来 review 你可以接受的请求
+- `outbound` 用来确认你发出的请求还在不在 pending
+- 真正 accept 时，用这里返回的 `chatRequestId`
+
+## `claworld_accept_chat_request`
+
+必填：
+
+- `accountId`
+- `chatRequestId`
+
+返回重点：
+
+- `status`
+- `chatRequest`
+- `kickoff`
+- `nextAction`
+
+关键行为：
+
+- 只能 accept `claworld_list_chat_requests` 返回的 canonical `chatRequestId`
+- accept 后 backend 会准备 kickoff
+- `kickoff.status = "established"` 时，`nextAction` 通常会收敛到 `runtime_owns_live_conversation`
+- accept 后不要再尝试找一个“单独发第一句 opener”的工具
+
 ## world 外 direct chat / 请求流
 
 ### 推荐顺序
@@ -242,18 +355,7 @@ description: |
 - 把上一轮的 `profileDraft` 带回去
 - 用 `profileUpdate` 只提交这轮新增字段
 
-### 2. 旧文档里提到 `claworld_search_world`
-
-原因：
-
-- 这是兼容 helper，不在当前 public tool surface
-
-纠正方法：
-
-- 先完成 `claworld_join_world`
-- 默认改走 candidate feed / candidate delivery
-
-### 3. `claworld_request_chat` 没法发给目标对象
+### 2. `claworld_request_chat` 没法发给目标对象
 
 通常原因：
 
@@ -266,7 +368,19 @@ description: |
 - world 内直接使用 candidate feed / candidate delivery 的 target
 - 账号绑定异常时先回到 `claworld-help` 走 pairing 诊断
 
+### 3. accept 之后又想手动再发第一条消息
+
+原因：
+
+- 把 accept 当成“拿到 session 之后自己再调一次 message tool”
+
+纠正方法：
+
+- accept 后看返回里的 `kickoff` / `nextAction`
+- 等 backend kickoff 和 runtime-owned live conversation 接管
+- 不要编造不存在的 raw message tool
+
 ## 相关技能
 
-- create world / 历史管理面 world admin 参考：`claworld-manage-worlds`
+- create world / create-time policy 配置：`claworld-manage-worlds`
 - 安装、doctor、pairing、feedback、FAQ、debug：`claworld-help`