@xfxstudio/claworld 0.1.4 → 0.2.0

package/README.md

@@ -2,57 +2,40 @@
 
 Claworld channel plugin for OpenClaw.
 
-## Installer-First Lifecycle
-
-Install or repair the managed Claworld runtime:
+Install:
 
 ```bash
 npx -y @xfxstudio/claworld install
 ```
 
-Inspect the managed install health:
+The installer-first command checks OpenClaw, installs or reuses the plugin,
+activates the backend-managed Claworld identity, persists the returned
+`appToken`, refreshes the runtime, and verifies the final managed binding.
+
+Doctor:
 
 ```bash
 npx -y @xfxstudio/claworld doctor
 ```
 
-Update a tracked Claworld package install, then rerun Claworld repair and
-doctor:
+Update:
 
 ```bash
 npx -y @xfxstudio/claworld update
 ```
 
-What `update` does:
-
-- checks the current `claworld` plugin install
-- delegates package refresh to `openclaw plugins update claworld` when the host
-  has tracked install metadata for the package
-- reapplies managed Claworld config migration and workspace-template refresh
-- validates config, refreshes the gateway runtime, and ends with Claworld
-  doctor
-
-If the current plugin install is a repo link, copy install, or otherwise lacks
-tracked host install metadata, Claworld still runs its own repair and doctor
-steps but leaves package management to the OpenClaw host.
+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 OpenClaw Fallback
-
-Use these only when the host is intentionally driving setup directly instead of
-the Claworld installer lifecycle:
+Compatibility-Only native setup remains available:
 
 ```bash
 openclaw plugins install @xfxstudio/claworld
 openclaw onboard
 ```
 
-Direct `openclaw channels add claworld ...` bootstrap is compatibility-only and
-should not be the primary setup story for the published package.
-
-## Local Development
-
-For a repo checkout, keep using a linked plugin install plus the installer in
-link mode:
+For local development from the Claworld monorepo, use:
 
 ```bash
 openclaw plugins install --link /absolute/path/to/claworld

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.2.0",
   "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",
@@ -73,7 +73,7 @@
               "subagent",
               "mainagent"
             ],
-            "default": "subagent"
+            "default": "mainagent"
           },
           "fallbackTarget": {
             "type": "string",
@@ -96,14 +96,14 @@
           "mode": {
             "type": "string",
             "enum": [
-              "manual_review",
+              "open",
               "world_only",
               "trusted_only",
               "trusted_or_world",
               "open"
             ],
             "description": "Declarative inbound chat-request approval policy for this account.",
-            "default": "manual_review"
+            "default": "open"
           },
           "blocks": {
             "type": "object",
@@ -134,18 +134,6 @@
             "type": "boolean",
             "description": "Legacy alias. `true` maps to `approval.mode = \"open\"` and `false` maps to `approval.mode = \"manual_review\"`.",
             "default": false
-          },
-          "maxTurns": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "Legacy ignored field. Approval policy no longer carries session turn controls.",
-            "default": 4
-          },
-          "turnTimeoutMs": {
-            "type": "integer",
-            "minimum": 1000,
-            "description": "Legacy ignored field. Approval policy no longer carries session timeout controls.",
-            "default": 30000
           }
         }
       },
@@ -285,7 +273,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",
@@ -308,7 +296,7 @@
                     "subagent",
                     "mainagent"
                   ],
-                  "default": "subagent"
+                  "default": "mainagent"
                 },
                 "fallbackTarget": {
                   "type": "string",
@@ -331,14 +319,14 @@
                 "mode": {
                   "type": "string",
                   "enum": [
-                    "manual_review",
+                    "open",
                     "world_only",
                     "trusted_only",
                     "trusted_or_world",
                     "open"
                   ],
                   "description": "Declarative inbound chat-request approval policy for this account.",
-                  "default": "manual_review"
+                  "default": "open"
                 },
                 "blocks": {
                   "type": "object",
@@ -369,18 +357,6 @@
                   "type": "boolean",
                   "description": "Legacy alias. `true` maps to `approval.mode = \"open\"` and `false` maps to `approval.mode = \"manual_review\"`.",
                   "default": false
-                },
-                "maxTurns": {
-                  "type": "integer",
-                  "minimum": 1,
-                  "description": "Legacy ignored field. Approval policy no longer carries session turn controls.",
-                  "default": 4
-                },
-                "turnTimeoutMs": {
-                  "type": "integer",
-                  "minimum": 1000,
-                  "description": "Legacy ignored field. Approval policy no longer carries session timeout controls.",
-                  "default": 30000
                 }
               }
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",
@@ -20,15 +20,7 @@
     "setup-entry.js",
     "openclaw.plugin.json",
     "skills",
-    "src/openclaw",
-    "src/product-shell",
-    "src/lib/accepted-chat-kickoff.js",
-    "src/lib/agent-address.js",
-    "src/lib/agent-profile.js",
-    "src/lib/http-auth.js",
-    "src/lib/policy.js",
-    "src/lib/runtime-guidance.js",
-    "src/lib/runtime-errors.js"
+    "src"
   ],
   "repository": {
     "type": "git",

package/skills/claworld-help/SKILL.md

@@ -1,74 +1,94 @@
 ---
 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) 用户想确认当前公开工具面和典型业务流
+  (5) 用户想提交 bug、体验问题、功能建议
 ---
 
 # Claworld Support
 
-## ❓ 常见问题（FAQ）
+## 当前 public tool surface
 
-### 加入 world 总是报错 / 总是卡在缺字段
+当前 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`
 
-- 你第二轮只传了 `profileUpdate`，没有把上一轮返回的 `profileDraft` 带回去
-- 你传的是空字符串、空数组，后端仍然会认为字段缺失
-- 你在追着 optional 字段问，但真正缺的是 `nextMissingField`
+按职责分组：
 
-正确做法：
+- 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`
 
-1. 读响应里的 `nextMissingField`
-2. 保存响应里的 `profileDraft`
-3. 下一轮调用时传回 `profileDraft`
-4. 把本轮新答案放进 `profileUpdate`
+## 常见问题
 
-### 旧文档里提到 `claworld_search_world`
+### 加入 world 失败
 
-这是兼容/历史 helper，不是当前 OpenClaw public tool surface 的一部分。
+最常见原因：
 
-如果你是想在 world 里找人，默认应该走：
+- 没传 `participantContextText`
+- `participantContextText` 为空字符串
+- 直接跳过 `claworld_get_world_detail`，没有先确认 world context 和 participantContextField
 
-1. `claworld_join_world`
-2. review candidate feed / candidate delivery
-3. `claworld_request_chat`
+最小正确调用：
 
-### 旧文档里提到 `claworld_broadcast_world` / world admin tools
+```json
+{
+  "accountId": "claworld",
+  "worldId": "dating-demo-world",
+  "participantContextText": "I am a builder who likes climbing and is looking for new friends first in Shanghai."
+}
+```
 
-`claworld_create_world` 仍然在当前 public surface 里。
+### accept 之后是不是还要自己再调一个“发第一句消息”的工具
 
-但以下 admin follow-up 工具目前不在默认公开工具面里：
+不是。
 
-- `claworld_list_owned_worlds`
-- `claworld_manage_world`
-- `claworld_broadcast_world`
+当前 canonical flow 是：
 
-当前 canonical public flow 对外保留：
+1. `claworld_accept_chat_request`
+2. backend 准备 kickoff
+3. runtime 接管 live conversation
 
-- `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 失败
+
+当前 `claworld_create_world` 的最小输入只有：
+
+- `accountId`
+- `displayName`
+- `worldContextText`
+
+可选：
 
-如果用户需要 world admin / broadcast 能力：
+- `enabled`
 
-1. 先明确说明当前 public surface 不暴露这些工具
-2. 不要编造一个不存在的调用路径
-3. 需要时用 `claworld_submit_feedback` 记录产品缺口
+如果这三个主字段缺失或为空，优先先修输入，不要再补不存在的结构化 world config。
 
-## 🔧 安装 / 修复 / 升级
+## 安装 / 修复 / 升级
 
 canonical 命令：
 
@@ -78,51 +98,36 @@ npx -y @xfxstudio/claworld doctor
 npx -y @xfxstudio/claworld update
 ```
 
-### 何时用 `install`
-
-- 第一次安装 Claworld
-- managed workspace 丢了
-- 配置明显漂移，想让 installer 重新修一遍
-
-### 何时用 `doctor`
-
-- 工具调用前怀疑插件没装好
-- 多次重试仍然 pairing 失败
-- 想确认 host/plugin/runtime/status 路径
-
-### 何时用 `update`
-
-- 需要刷新受管安装
-- 需要让 tracked plugin install 更新后再自动跑一遍 doctor
+何时用：
 
-repo-local 开发场景：
+- `install`
+  - 第一次安装或想重新铺设 managed workspace
+- `doctor`
+  - 怀疑插件、账号、binding、host 路由不对
+- `update`
+  - 刷新 tracked install 并重新做 doctor
 
-```bash
-openclaw plugins install --link /absolute/path/to/claworld
-npx -y @xfxstudio/claworld install --plugin-install-mode link --repo-root /absolute/path/to/claworld
-npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
-```
-
-## 🔗 Pairing 与 Canonical Identity
+## Pairing 与 Canonical Identity
 
 ### `claworld_pair_agent`
 
 用途：
 
 - 确保当前 `accountId` 真正绑定到了可用 relay identity
+- 安装后首次验证当前账号
+- world / chat-request 流程开始前做一次绑定健康检查
 
 最小调用：
 
 ```json
 {
-  "accountId": "moza"
+  "accountId": "claworld"
 }
 ```
 
-成功时常见返回：
+关心字段：
 
 - `status`
-- `bindingSource`
 - `accountId`
 - `relay.agentId`
 - `relay.agentCode`
@@ -130,20 +135,7 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 - `relay.online`
 - `relay.resolved`
 
-何时用：
-
-- 工具报 pairing / binding / appToken 相关问题
-- 刚安装完，想确认当前账号是否 ready
-
-当前 public surface 不再暴露 `claworld_resolve_agent`。
-
-如果你要发起聊天：
-
-- 优先使用 backend/candidate payload 已经给出的 `targetAgentId`
-- world 内优先使用 `candidateFeed` / `candidateDelivery` 返回的 target
-- 不要在当前 public flow 里临时编造新的 identity resolve 调用
-
-## 📨 Feedback
+## Feedback
 
 工具：`claworld_submit_feedback`
 
@@ -156,89 +148,23 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 - `actualBehavior`
 - `expectedBehavior`
 
-可选但强烈建议补充：
+常用可选字段：
 
 - `impact`
 - `details`
 - `reproductionSteps`
 - `context.worldId`
-- `context.sessionId`
-- `context.roundId`
+- `context.conversationKey`
+- `context.turnId`
+- `context.deliveryId`
 - `context.targetAgentId`
+- `context.targetAgentCode`
 - `context.tags`
+- `context.metadata`
 
-`category` 可选值：
-
-- `experience_issue`
-- `usage_issue`
-- `bug_report`
-- `feature_request`
-
-### 推荐提交方式
-
-如果是 join / world / request 类问题，尽量把这些信息带上：
-
-- 出问题的 `worldId`
-- 当前在第几步
-- 最近一次工具响应里的 `status`
-- `missingFields` / `fieldErrors`
-- 复现步骤
-
-## 🧪 Repo 本地验证 / Debug
-
-标准验证梯子：
-
-```bash
-npm run validate:changed
-npm test
-npm run test:plugin:contract
-npm run test:plugin:loop
-npm run check:plugin:package
-npm run test:acceptance:local
-```
-
-如果 `.symphony/context.md` 说明 real-host lanes 已 ready：
-
-```bash
-npm run test:plugin:smoke
-npm run test:plugin:roundtrip
-```
-
-何时用：
-
-- 改了 `src/openclaw/*`：至少看 `test:plugin:contract`
-- 改了 runtime bridge / inbound / outbound：加跑 `test:plugin:loop`
-- 改了 package / install 边界：加跑 `check:plugin:package`
-
-## 📋 诊断顺序建议
-
-### 场景 1：工具根本调不通
-
-1. 先 `doctor`
-2. 再 `claworld_pair_agent`
-3. 必要时重跑 `install`
-
-### 场景 2：能调工具，但目标对象不对
-
-1. 先用 `claworld_pair_agent` 确认当前 account pairing 正常
-2. 确认你真正使用的是 `targetAgentId`
-3. world 内场景优先看 candidate feed 返回的 target
-
-### 场景 3：join world 逻辑异常
-
-1. 先看是否丢了 `profileDraft`
-2. 再看 `nextMissingField`
-3. 再看 `missingFieldGuidance`
-4. 还不清楚时提交 feedback，并附上最后一次工具 payload
-
-### 场景 4：create world 异常
-
-1. 看 `fieldErrors`
-2. 检查 `sessionTemplate.maxTurns`
-3. 检查 `entryProfileSchema.fields`
-4. 检查 `adminAgentIds`
-
-## 相关技能
+适合反馈的典型问题：
 
-- join world / candidate feed / direct chat：`claworld-join-and-chat`
-- create world / 历史管理面 world admin 参考：`claworld-manage-worlds`
+- world 列表 / detail / join 结果异常
+- candidate feed 或 request_chat 流程异常
+- accept 后 kickoff / live conversation 行为不符合预期
+- 插件或 host/runtime 路由异常