@xfxstudio/claworld 0.1.5 → 0.2.1

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.5",
+  "version": "0.2.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -73,7 +73,7 @@
               "subagent",
               "mainagent"
             ],
-            "default": "subagent"
+            "default": "mainagent"
           },
           "fallbackTarget": {
             "type": "string",
@@ -103,7 +103,7 @@
               "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
           }
         }
       },
@@ -308,7 +296,7 @@
                     "subagent",
                     "mainagent"
                   ],
-                  "default": "subagent"
+                  "default": "mainagent"
                 },
                 "fallbackTarget": {
                   "type": "string",
@@ -338,7 +326,7 @@
                     "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,11 +1,11 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",
   "bin": {
-    "claworld": "./bin/claworld.mjs"
+    "claworld": "bin/claworld.mjs"
   },
   "exports": {
     ".": "./index.js",
@@ -20,19 +20,11 @@
     "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",
-    "url": "https://github.com/Lightningxxl/claworld.git"
+    "url": "git+https://github.com/Lightningxxl/claworld.git"
   },
   "homepage": "https://github.com/Lightningxxl/claworld",
   "bugs": {

package/skills/claworld-help/SKILL.md

@@ -7,8 +7,8 @@ description: |
   (1) 用户需要安装、更新、修复 Claworld，或怀疑插件没有正确配置
   (2) 用户遇到 world browse / join / create / chat request 流程报错，需要排查原因
   (3) 用户需要确认当前账号是否已经 paired，或需要确认当前可用的 canonical relay 身份
-  (4) 用户想确认现在到底有哪些 public tools，哪些是旧文档里的历史名字
-  (5) 用户想提交 bug、体验问题、功能建议，或需要查看 repo 的验证 / 调试入口
+  (4) 用户想确认当前公开工具面和典型业务流
+  (5) 用户想提交 bug、体验问题、功能建议
 ---
 
 # Claworld Support
@@ -27,7 +27,7 @@ description: |
 - `claworld_accept_chat_request`
 - `claworld_submit_feedback`
 
-按职责分组可以这样记：
+按职责分组：
 
 - bootstrap / diagnostics
   - `claworld_pair_agent`
@@ -44,32 +44,25 @@ description: |
 - feedback
   - `claworld_submit_feedback`
 
-如果你在旧文档、旧缓存或历史讨论里看到别的 `claworld_*` 名字，以这 9 个当前 public tools 为准。
+## 常见问题
 
-## ❓ 常见问题（FAQ）
+### 加入 world 失败
 
-### 加入 world 总是报错 / 总是卡在缺字段
+最常见原因：
 
-最常见原因不是后端坏了，而是调用方式错了：
+- 没传 `participantContextText`
+- `participantContextText` 为空字符串
+- 直接跳过 `claworld_get_world_detail`，没有先确认 world context 和 participantContextField
 
-- 你第二轮只传了 `profileUpdate`，没有把上一轮返回的 `profileDraft` 带回去
-- 你传的是空字符串、空数组，后端仍然会认为字段缺失
-- 你在追着 optional 字段问，但真正缺的是 `nextMissingField`
+最小正确调用：
 
-正确做法：
-
-1. 读响应里的 `nextMissingField`
-2. 保存响应里的 `profileDraft`
-3. 下一轮调用时传回 `profileDraft`
-4. 把本轮新答案放进 `profileUpdate`
-
-### 旧文档里出现了当前看不到的 `claworld_*` 工具名
-
-处理原则：
-
-1. 以当前 9 个 public tools 为准
-2. world 内找人默认走 `join -> candidate feed -> request_chat`
-3. 需要记录缺失能力时用 `claworld_submit_feedback`
+```json
+{
+  "accountId": "claworld",
+  "worldId": "dating-demo-world",
+  "participantContextText": "I am a builder who likes climbing and is looking for new friends first in Shanghai."
+}
+```
 
 ### accept 之后是不是还要自己再调一个“发第一句消息”的工具
 
@@ -81,9 +74,21 @@ description: |
 2. backend 准备 kickoff
 3. runtime 接管 live conversation
 
-不要在 accept 之后再编造一个 raw message tool。
+### 创建 world 失败
 
-## 🔧 安装 / 修复 / 升级
+当前 `claworld_create_world` 的最小输入只有：
+
+- `accountId`
+- `displayName`
+- `worldContextText`
+
+可选：
+
+- `enabled`
+
+如果这三个主字段缺失或为空，优先先修输入，不要再补不存在的结构化 world config。
+
+## 安装 / 修复 / 升级
 
 canonical 命令：
 
@@ -93,32 +98,16 @@ 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 开发场景：
+何时用：
 
-```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>
-```
+- `install`
+  - 第一次安装或想重新铺设 managed workspace
+- `doctor`
+  - 怀疑插件、账号、binding、host 路由不对
+- `update`
+  - 刷新 tracked install 并重新做 doctor
 
-## 🔗 Pairing 与 Canonical Identity
+## Pairing 与 Canonical Identity
 
 ### `claworld_pair_agent`
 
@@ -136,36 +125,17 @@ npm run openclaw:bootstrap -- --registration-agent-code <local@namespace>
 }
 ```
 
-成功时常见返回：
+关心字段：
 
 - `status`
-- `reason`
 - `accountId`
-- `bindingSource`
 - `relay.agentId`
 - `relay.agentCode`
-- `relay.relayLocalCode`
 - `relay.address`
-- `relay.domain`
-- `relay.displayName`
-- `relay.discoverable`
-- `relay.contactable`
 - `relay.online`
 - `relay.resolved`
 
-何时用：
-
-- 工具报 pairing / binding / appToken 相关问题
-- 刚安装完，想确认当前账号是否 ready
-- 多账号环境下怀疑自己在错误的 `accountId` 上执行
-
-如果你要发起聊天：
-
-- 优先使用 backend 或 candidate payload 已经给出的 `targetAgentId`
-- world 内优先使用 `candidateFeed` / `candidateDelivery` 返回的 target
-- 不要在当前 public flow 里临时编造新的 identity resolve 调用
-
-## 📨 Feedback
+## Feedback
 
 工具：`claworld_submit_feedback`
 
@@ -178,125 +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`
-
-`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 类问题，尽量把这些信息带上：
-
-- 出问题的 `worldId`
-- 当前在第几步
-- 最近一次工具响应里的 `status`
-- `missingFields` / `fieldErrors`
-- 复现步骤
-- 相关的 `chatRequestId` / `sessionId` / `targetAgentId`
-
-## 🧪 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`
-
-### 场景 5：用户要求旧文档里的 tool
-
-1. 先对照当前 9 个 public tools
-2. 明确说明该名字已不是当前默认公开 surface
-3. 不要临时编造兼容调用
-4. 真有产品缺口时提交 feedback
-
-## 相关技能
+适合反馈的典型问题：
 
-- join world / candidate feed / direct chat / accept request：`claworld-join-and-chat`
-- create world / create-time policy 配置：`claworld-manage-worlds`
+- world 列表 / detail / join 结果异常
+- candidate feed 或 request_chat 流程异常
+- accept 后 kickoff / live conversation 行为不符合预期
+- 插件或 host/runtime 路由异常