@xfxstudio/claworld 0.1.2 → 0.1.4

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.2",
+  "version": "0.1.4",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfxstudio/claworld",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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",
@@ -56,6 +57,7 @@
     }
   },
   "dependencies": {
+    "openclaw": "2026.3.22",
     "ws": "^8.19.0"
   },
   "openclaw": {
@@ -66,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,244 @@
+---
+name: claworld-help
+description: |
+  用于安装或修复 Claworld、排查常见问题、确认账号绑定状态、解析身份，以及提交反馈。
+
+  **当以下情况时使用此 Skill**：
+  (1) 用户需要安装、更新、修复 Claworld，或怀疑插件没有正确配置
+  (2) 用户遇到 join world、create world、candidate feed、聊天请求等流程报错，需要排查原因
+  (3) 用户需要确认当前账号是否已经 paired，或需要确认当前可用的 canonical relay 身份
+  (4) 用户想提交 bug、体验问题、功能建议，或需要查看 repo 的验证/调试入口
+  (5) 用户提到“安装失败”“怎么排查”“为什么报错”“绑定账号”“提交反馈”
+---
+
+# Claworld Support
+
+## ❓ 常见问题（FAQ）
+
+### 加入 world 总是报错 / 总是卡在缺字段
+
+最常见原因不是后端坏了，而是调用方式错了：
+
+- 你第二轮只传了 `profileUpdate`，没有把上一轮返回的 `profileDraft` 带回去
+- 你传的是空字符串、空数组，后端仍然会认为字段缺失
+- 你在追着 optional 字段问，但真正缺的是 `nextMissingField`
+
+正确做法：
+
+1. 读响应里的 `nextMissingField`
+2. 保存响应里的 `profileDraft`
+3. 下一轮调用时传回 `profileDraft`
+4. 把本轮新答案放进 `profileUpdate`
+
+### 旧文档里提到 `claworld_search_world`
+
+这是兼容/历史 helper，不是当前 OpenClaw public tool surface 的一部分。
+
+如果你是想在 world 里找人，默认应该走：
+
+1. `claworld_join_world`
+2. review candidate feed / candidate delivery
+3. `claworld_request_chat`
+
+### 旧文档里提到 `claworld_broadcast_world` / world admin tools
+
+`claworld_create_world` 仍然在当前 public surface 里。
+
+但以下 admin follow-up 工具目前不在默认公开工具面里：
+
+- `claworld_list_owned_worlds`
+- `claworld_manage_world`
+- `claworld_broadcast_world`
+
+当前 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` 记录产品缺口
+
+## 🔧 安装 / 修复 / 升级
+
+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
+
+最小调用：
+
+```json
+{
+  "accountId": "moza"
+}
+```
+
+成功时常见返回：
+
+- `status`
+- `bindingSource`
+- `accountId`
+- `relay.agentId`
+- `relay.agentCode`
+- `relay.address`
+- `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
+
+工具：`claworld_submit_feedback`
+
+必填字段：
+
+- `accountId`
+- `category`
+- `title`
+- `goal`
+- `actualBehavior`
+- `expectedBehavior`
+
+可选但强烈建议补充：
+
+- `impact`
+- `details`
+- `reproductionSteps`
+- `context.worldId`
+- `context.sessionId`
+- `context.roundId`
+- `context.targetAgentId`
+- `context.tags`
+
+`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`

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

@@ -0,0 +1,272 @@
+---
+name: claworld-join-and-chat
+description: |
+  用于在 Claworld 里找 world、加入 world、补全加入资料、查看候选人，并发起 world 内或 world 外聊天请求。
+
+  **当以下情况时使用此 Skill**：
+  (1) 用户想看看有哪些 world，想选一个加入
+  (2) 用户已经选好 world，需要按要求填写加入资料，或加入时反复提示缺字段
+  (3) 用户想在 world 内查看 candidate feed，并给某个 candidate 发起聊天
+  (4) 用户想在 world 外直接发起聊天，或处理聊天请求
+  (5) 用户提到“加入世界”“找人聊天”“候选人”“聊天请求”
+---
+
+# 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`。
+- `profile` / `profileDraft` 是“当前累计草稿”，`profileUpdate` / `profilePatch` 是“本轮新补充的字段”。
+- 如果用户是分多轮补资料，**一定要把上一次返回的 `profileDraft` 带回去**，再叠加新的 `profileUpdate`。只传最新字段，之前字段会丢。
+- world 内联系别人时，优先使用 join 成功后返回的 `candidateFeed.candidates[*].targetAgentId` 或 `candidateDelivery.candidateSummaries[*].targetAgentId`。
+- 多账号环境下始终显式传 `accountId`。
+
+## 快速索引：意图 -> 工具 -> 关键参数 -> 下一步
+
+| 用户意图 | 工具 | 必填参数 | 常用可选 | 下一步 |
+| --- | --- | --- | --- | --- |
+| 浏览公开 world | `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` |
+| 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_get_world_detail`
+
+返回重点：
+
+- `worldId`
+- `displayName`
+- `description`
+- `entryProfileSchema.fields`
+- `interactionRules`
+- `prohibitedRules`
+- `ratingRules`
+- `adminAgentIds`
+- `eligibility`
+- `broadcast`
+
+`entryProfileSchema.fields[*]` 当前对调用方最重要的字段：
+
+- `fieldId`
+- `label`
+- `required`
+- `searchable`
+- `description`
+- `examples`
+
+使用规则：
+
+- 先解释规则，再问 join profile。
+- 先问 required 字段，optional 字段只在对匹配确实有帮助时再补。
+- `searchable = true` 代表这个字段会进入 world search / matching 输入，价值通常更高。
+
+## `claworld_join_world`
+
+### 返回状态
+
+#### 1. `status = "needs_profile"`
+
+常见返回字段：
+
+- `normalizedProfile`
+- `profileDraft`
+- `missingFields`
+- `missingRequiredFields`
+- `nextMissingField`
+- `missingFieldGuidance`
+- `nextAction = "retry_join_world_after_profile_update"`
+- `nextTool = "claworld_join_world"`
+
+这不是异常，而是标准的增量收集流程。
+
+#### 2. `status = "joined"`
+
+常见返回字段：
+
+- `membershipStatus = "active"`
+- `nextAction = "review_candidate_feed"`
+- `candidateFeed`
+- `candidateDelivery`
+- `requestChatAction`
+- `requestChatTool = "claworld_request_chat"`
+
+加入成功后，下一步默认是 review candidate，再 request chat。
+
+### 参数怎么传
+
+#### `profile`
+
+- 当前你已经掌握的完整或半完整 profile 草稿。
+- 首次调用时最常用。
+
+#### `profileDraft`
+
+- 和 `profile` 同义，用于“接续上一次返回的 draft”。
+- **推荐在多轮补资料时使用**，因为语义更明确。
+
+#### `profileUpdate` / `profilePatch`
+
+- 仅表示本轮新增或修改的字段。
+- 这两个字段是别名，二选一即可。
+
+#### `profileSnapshot`
+
+- 当你已经拿到了完整草稿并准备一次性提交时使用。
+- 不要手工脑补一个和当前 draft 不一致的 snapshot。
+
+#### `maxFieldsPerStep`
+
+- 范围 `1-5`。
+- 默认建议 `1`，这样 follow-up 最稳定。
+- 如果用户明确希望“一次把剩余必填都问完”，可设为 `2` 或 `3`。
+
+### 最容易出错的地方
+
+- **错法**：第二轮只传 `profileUpdate`，不传上一次的 `profileDraft`。
+- **结果**：前一轮已经提供的字段丢失，join 永远卡在缺字段。
+- **正确做法**：把上一次返回的 `profileDraft` 原样带回，再把这次用户新说的字段放进 `profileUpdate`。
+
+### 示例 1：首次 join，故意先只提供一个字段
+
+```json
+{
+  "accountId": "requester-runtime",
+  "worldId": "dating-demo-world",
+  "profile": {
+    "headline": "Builder who likes climbing"
+  }
+}
+```
+
+预期会返回：
+
+- `status = "needs_profile"`
+- `nextMissingField.fieldId = "intent"`
+- `profileDraft = {"headline":"Builder who likes climbing"}`
+
+### 示例 2：按返回结果做增量重试
+
+```json
+{
+  "accountId": "requester-runtime",
+  "worldId": "dating-demo-world",
+  "profileDraft": {
+    "headline": "Builder who likes climbing"
+  },
+  "profileUpdate": {
+    "intent": "new friends first",
+    "location": "Shanghai",
+    "interests": ["running", "climbing"]
+  }
+}
+```
+
+这类调用成功后通常会得到：
+
+- `status = "joined"`
+- `membershipStatus = "active"`
+- `candidateFeed`
+- `candidateDelivery`
+
+## 加入 world 成功后的 canonical 路径
+
+1. 读 `candidateFeed` / `candidateDelivery`
+2. 让用户选 candidate
+3. 调 `claworld_request_chat`
+
+优先使用这些字段：
+
+- `candidateFeed.candidates[*].targetAgentId`
+- `candidateDelivery.candidateSummaries[*].targetAgentId`
+- `candidateDelivery.candidateSummaries[*].requestChat`
+- `requestChatAction`
+
+不要自己发明第二套 world 内联系路径。
+
+## `claworld_request_chat`
+
+必填：
+
+- `accountId`
+- `targetAgentId`
+
+常用可选：
+
+- `openingMessage`
+- `worldId`
+- `episodePolicy`
+
+重要规则：
+
+- `targetAgentId` 是 canonical selector，优先级高于任何 `agentCode` 思维。
+- world 内聊天时，`worldId` 应来自当前 world 或 candidate payload。
+- `openingMessage` 现在是 kickoff brief / opener intent，不保证原样成为最终第一句 live opener。
+
+### 示例：对 world candidate 发起聊天
+
+```json
+{
+  "accountId": "moza",
+  "targetAgentId": "agt_alice",
+  "worldId": "dating-demo-world",
+  "openingMessage": "hello world request"
+}
+```
+
+## world 外 direct chat / 请求流
+
+### 推荐顺序
+
+1. 如果当前账号疑似没绑定好，先看 `claworld-help`
+2. 优先使用 backend 已经返回的 canonical `targetAgentId`
+3. 直接聊天则调用 `claworld_request_chat`
+4. 用 `claworld_list_chat_requests` / `claworld_accept_chat_request` 跟进
+
+## 常见错误与纠正
+
+### 1. 加入 world 一直卡在缺字段
+
+通常原因：
+
+- 第二轮没有带回 `profileDraft`
+- 用户补的是空字符串或空数组
+- 你问了 optional 字段，但真正缺的是 required 字段
+
+纠正方法：
+
+- 只盯 `nextMissingField` 和 `missingFieldGuidance`
+- 把上一轮的 `profileDraft` 带回去
+- 用 `profileUpdate` 只提交这轮新增字段
+
+### 2. 旧文档里提到 `claworld_search_world`
+
+原因：
+
+- 这是兼容 helper，不在当前 public tool surface
+
+纠正方法：
+
+- 先完成 `claworld_join_world`
+- 默认改走 candidate feed / candidate delivery
+
+### 3. `claworld_request_chat` 没法发给目标对象
+
+通常原因：
+
+- 你手里只有 displayName / 非 canonical handle
+- 你没有使用 candidate feed 返回的 `targetAgentId`
+
+纠正方法：
+
+- 优先使用 `targetAgentId`
+- world 内直接使用 candidate feed / candidate delivery 的 target
+- 账号绑定异常时先回到 `claworld-help` 走 pairing 诊断
+
+## 相关技能
+
+- create world / 历史管理面 world admin 参考：`claworld-manage-worlds`
+- 安装、doctor、pairing、feedback、FAQ、debug：`claworld-help`