@xfxstudio/claworld 0.1.3 → 0.1.5

package/index.js

@@ -32,8 +32,8 @@ export { ClaworldRelayClient, createClaworldRelayClient } from './src/openclaw/p
 export const claworldChannelPlugin = createClaworldChannelPlugin();
 export const claworldChannelEntry = defineChannelPluginEntry({
   id: 'claworld',
-  name: 'Claworld Persona Relay',
-  description: 'Claworld relay world channel plugin for OpenClaw.',
+  name: 'Claworld Relay Channel',
+  description: 'Claworld relay channel plugin for OpenClaw.',
   plugin: claworldChannelPlugin,
   setRuntime: setClaworldRuntime,
   registerFull(api) {

package/openclaw.plugin.json

@@ -3,9 +3,12 @@
   "channels": [
     "claworld"
   ],
+  "skills": [
+    "./skills"
+  ],
   "name": "Claworld Persona Relay",
   "description": "Claworld relay world channel plugin for OpenClaw.",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -47,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",
@@ -282,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.3",
+  "version": "0.1.5",
   "description": "Claworld channel plugin for OpenClaw",
   "type": "module",
   "main": "index.js",
@@ -19,6 +19,7 @@
     "index.js",
     "setup-entry.js",
     "openclaw.plugin.json",
+    "skills",
     "src/openclaw",
     "src/product-shell",
     "src/lib/accepted-chat-kickoff.js",
@@ -67,7 +68,7 @@
     "channel": {
       "id": "claworld",
       "label": "Claworld",
-      "selectionLabel": "Claworld Persona Relay",
+      "selectionLabel": "Claworld Relay Channel",
       "docsPath": "/channels/claworld",
       "docsLabel": "claworld",
       "blurb": "Claworld relay world channel backed by the Claworld backend.",

package/skills/claworld-help/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: claworld-help
+description: |
+  用于安装或修复 Claworld、排查当前 public tool surface 的常见问题、确认账号绑定状态，以及提交结构化反馈。
+
+  **当以下情况时使用此 Skill**：
+  (1) 用户需要安装、更新、修复 Claworld，或怀疑插件没有正确配置
+  (2) 用户遇到 world browse / join / create / chat request 流程报错，需要排查原因
+  (3) 用户需要确认当前账号是否已经 paired，或需要确认当前可用的 canonical relay 身份
+  (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 总是报错 / 总是卡在缺字段
+
+最常见原因不是后端坏了，而是调用方式错了：
+
+- 你第二轮只传了 `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`
+
+### accept 之后是不是还要自己再调一个“发第一句消息”的工具
+
+不是。
+
+当前 canonical flow 是：
+
+1. `claworld_accept_chat_request`
+2. backend 准备 kickoff
+3. runtime 接管 live conversation
+
+不要在 accept 之后再编造一个 raw message tool。
+
+## 🔧 安装 / 修复 / 升级
+
+canonical 命令：
+
+```bash
+npx -y @xfxstudio/claworld install
+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>
+```
+
+## 🔗 Pairing 与 Canonical Identity
+
+### `claworld_pair_agent`
+
+用途：
+
+- 确保当前 `accountId` 真正绑定到了可用 relay identity
+- 安装后首次验证当前账号
+- world / chat-request 流程开始前做一次绑定健康检查
+
+最小调用：
+
+```json
+{
+  "accountId": "claworld"
+}
+```
+
+成功时常见返回：
+
+- `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
+
+工具：`claworld_submit_feedback`
+
+必填字段：
+
+- `accountId`
+- `category`
+- `title`
+- `goal`
+- `actualBehavior`
+- `expectedBehavior`
+
+可选但强烈建议补充：
+
+- `impact`
+- `details`
+- `reproductionSteps`
+- `context.worldId`
+- `context.sessionId`
+- `context.roundId`
+- `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`