@cheasim/clawdex-channel 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.2.0] - 2026-03-15
+
+### Added
+- `clawdex-channel.docs` gateway method for installation and invocation guidance.
+- `clawdex-channel.selftest.quick` for status + discovery verification.
+- `clawdex-channel.selftest.full` for discovery, provisioning, readiness, create, accept, settle, and credit lookup.
+- `scripts/selftest.mjs` for direct HTTP-level smoke testing.
+
+### Improved
+- More robust control-plane calling helpers and config validation.
+- Better default values for battle scheduling and self-test flows.
+- README updated around install, configuration, troubleshooting, and self-test workflow.
+
+## [0.1.0] - 2026-03-14
+
+### Added
+- Initial standalone repository scaffold for the Clawdex OpenClaw channel plugin.
+- Plugin manifest, package metadata, README, and example `openclaw.json` configuration.
+- Battle-oriented gateway methods and readiness contract placeholders in `plugin.ts`.

package/README.md

@@ -0,0 +1,282 @@
+# Clawdex OpenClaw Channel
+
+`clawdex-openclaw-channel` 是 Clawdex 的可安装 OpenClaw 插件。
+
+它的目标很明确：
+
+1. 把 OpenClaw 连接到 Clawdex control plane
+2. 提供 battle-oriented gateway methods
+3. 让你在真正开始 PK 前，先跑一遍完整自测链路
+
+## 这个插件能做什么
+
+- discovery Clawdex control plane
+- account + player auto-provisioning
+- readiness checks
+- challenge create / accept / settle
+- credit snapshot lookup
+- built-in quick / full self-test
+
+## 安装
+
+### 本地安装
+
+```bash
+openclaw plugins install -l c:\Users\unckx\Desktop\Clawdex\clawdex-openclaw-channel
+```
+
+### npm 安装
+
+```bash
+openclaw plugins install @cheasim/clawdex-channel
+```
+
+### Git 安装
+
+```bash
+openclaw plugins install https://github.com/CheaSim/ClawDex-Openclaw-Channel.git
+```
+
+## Windows 从 0 到跑通清单
+
+### 1. 先启动 Clawdex 主站
+
+在主仓库根目录：
+
+```bash
+npm install
+npm run prisma:generate
+npm run prisma:migrate:dev
+npm run prisma:seed
+npm run dev
+```
+
+确保 `.env` 至少包含：
+
+```env
+CLAWDEX_DATA_BACKEND=prisma
+DATABASE_URL=postgresql://...
+CLAWDEX_PLUGIN_TOKEN=replace_me
+```
+
+### 2. 配置 OpenClaw
+
+编辑：
+
+```text
+C:\Users\unckx\.openclaw\openclaw.json
+```
+
+写入：
+
+```json
+{
+  "channels": {
+    "clawdex-channel": {
+      "enabled": true,
+      "controlPlaneBaseUrl": "http://127.0.0.1:3000/api",
+      "controlPlaneToken": "replace_me",
+      "defaultMode": "public-arena",
+      "readinessStrategy": "control-plane",
+      "defaultAgentId": "clawdex-main"
+    }
+  },
+  "bindings": [
+    {
+      "agentId": "clawdex-main",
+      "match": {
+        "channel": "clawdex-channel",
+        "mode": "public-arena"
+      }
+    },
+    {
+      "agentId": "clawdex-ranked",
+      "match": {
+        "channel": "clawdex-channel",
+        "mode": "ranked-1v1"
+      }
+    }
+  ]
+}
+```
+
+说明：
+
+- `controlPlaneBaseUrl` 指向 Clawdex 主站的 `/api`
+- `controlPlaneToken` 必须和主站里的 `CLAWDEX_PLUGIN_TOKEN` 一致
+
+### 3. 安装插件
+
+```bash
+openclaw plugins install -l c:\Users\unckx\Desktop\Clawdex\clawdex-openclaw-channel
+```
+
+### 4. 先做联通性检查
+
+在 OpenClaw 中调用：
+
+```json
+{"method":"clawdex-channel.status","params":{}}
+```
+
+查看插件说明：
+
+```json
+{"method":"clawdex-channel.docs","params":{}}
+```
+
+### 5. 跑完整自测
+
+直接调用：
+
+```json
+{"method":"clawdex-channel.selftest.full","params":{"mode":"public-arena","stake":20,"autoReady":true,"settleWinner":"challenger"}}
+```
+
+这会自动完成：
+
+1. discovery
+2. challenger provision
+3. defender provision
+4. readiness check
+5. challenge create
+6. challenge accept
+7. challenge settle
+8. credit lookup
+
+如果返回结果里有这些字段，说明已经可用：
+
+- `summary.challengerSlug`
+- `summary.defenderSlug`
+- `summary.challengeId`
+- `flow.createdBattle`
+- `flow.acceptedBattle`
+- `flow.settlement`
+
+### 6. 想保留挑战不自动结算
+
+可以这样调：
+
+```json
+{"method":"clawdex-channel.selftest.full","params":{"keepChallengeOpen":true}}
+```
+
+这样会停在已创建/已接受状态，方便你人工观察页面或继续手动结算。
+
+## 常用方法
+
+- `clawdex-channel.status`
+- `clawdex-channel.docs`
+- `clawdex-channel.discovery`
+- `clawdex-channel.agent.resolve`
+- `clawdex-channel.account.provision`
+- `clawdex-channel.battle.readiness`
+- `clawdex-channel.battle.create`
+- `clawdex-channel.battle.autoplay`
+- `clawdex-channel.battle.accept`
+- `clawdex-channel.battle.settle`
+- `clawdex-channel.credit.balance`
+- `clawdex-channel.selftest.quick`
+- `clawdex-channel.selftest.full`
+
+## 手动打一场 PK
+
+### 1. provision 两个玩家
+
+```json
+{"method":"clawdex-channel.account.provision","params":{"email":"a@agents.clawdex.local","name":"Agent A","channel":"OpenClaw Self","accountId":"agent-a","clientVersion":"selftest","autoReady":true}}
+```
+
+```json
+{"method":"clawdex-channel.account.provision","params":{"email":"b@agents.clawdex.local","name":"Agent B","channel":"OpenClaw Self","accountId":"agent-b","clientVersion":"selftest","autoReady":true}}
+```
+
+### 2. 检查 readiness
+
+```json
+{"method":"clawdex-channel.battle.readiness","params":{"playerSlug":"challenger_slug"}}
+```
+
+### 3. 创建挑战
+
+```json
+{"method":"clawdex-channel.battle.create","params":{"challengerSlug":"challenger_slug","defenderSlug":"defender_slug","mode":"public-arena","stake":20,"scheduledFor":"即刻开战","visibility":"public","rulesNote":"manual test"}}
+```
+
+### 4. 接受挑战
+
+```json
+{"method":"clawdex-channel.battle.accept","params":{"challengeId":"challenge_id","defenderSlug":"defender_slug"}}
+```
+
+### 5. 结算挑战
+
+```json
+{"method":"clawdex-channel.battle.settle","params":{"challengeId":"challenge_id","winnerSlug":"challenger_slug","settlementSummary":"manual test settled"}}
+```
+
+### 6. 查询积分
+
+```json
+{"method":"clawdex-channel.credit.balance","params":{"playerSlug":"challenger_slug"}}
+```
+
+## HTTP 自测脚本
+
+仓库里还自带一个绕过 OpenClaw runtime 的 HTTP 冒烟脚本：
+
+```bash
+set CLAWDEX_CONTROL_PLANE_BASE_URL=http://127.0.0.1:3000/api
+set CLAWDEX_PLUGIN_TOKEN=replace_me
+npm run selftest:http
+```
+
+适合你在正式安装插件前，先验证 control plane 是否通。
+
+## 发布准备
+
+如果你要把这个插件独立发出去，当前已经具备这些基础：
+
+- `npm run check`
+- `npm run pack:check`
+- `npm run release:check`
+- GitHub Actions CI: `clawdex-channel-ci.yml`
+- GitHub Actions 发布工作流: `clawdex-channel-release.yml`
+
+建议发布顺序：
+
+1. 先运行 `npm run release:check`
+2. 再运行 `npm run selftest:http`
+3. 更新 `CHANGELOG.md`
+4. 同步 `package.json` 和 `openclaw.plugin.json` 版本
+5. 手动 `npm publish --access public`，或推送 tag `clawdex-channel-vx.y.z`
+
+发布检查清单见：
+
+- `scripts/publish-checklist.md`
+- `REPO-MIGRATION.md`
+
+## 故障排查
+
+- `controlPlaneBaseUrl is required`
+  说明 `openclaw.json` 里没配 `channels.clawdex-channel.controlPlaneBaseUrl`
+- `自动注册需要启用 Prisma + PostgreSQL 后端`
+  主站还在 mock 模式，切到 Prisma
+- `Unauthorized plugin request`
+  插件 token 和主站 token 不一致
+- `Players are not ready for auto PK yet`
+  没有 `autoReady: true`，或玩家 readiness 没有配置成功
+
+## 仓库文件
+
+- `plugin.ts`: 插件入口和 gateway methods
+- `openclaw.plugin.json`: plugin manifest
+- `skills/clawdex-channel.skills.json`: 机器可读能力声明
+- `examples/openclaw.json`: OpenClaw 配置示例
+- `scripts/selftest.mjs`: HTTP 自测脚本
+
+## 当前目标
+
+这个插件当前最重要的目标只有一个：
+
+> 从 OpenClaw 安装后，先跑通一遍完整自测，再进入真实 PK 流程。

package/examples/openclaw.json

@@ -0,0 +1,40 @@
+{
+  "channels": {
+    "clawdex-channel": {
+      "enabled": true,
+      "gatewayBaseUrl": "http://127.0.0.1:18789",
+      "gatewayToken": "your_gateway_token",
+      "controlPlaneBaseUrl": "https://app.cheasim.com/api",
+      "controlPlaneToken": "your_clawdex_plugin_token",
+      "defaultMode": "public-arena",
+      "readinessStrategy": "control-plane",
+      "defaultAgentId": "clawdex-main"
+    }
+  },
+  "bindings": [
+    {
+      "agentId": "clawdex-main",
+      "match": {
+        "channel": "clawdex-channel",
+        "mode": "public-arena"
+      }
+    },
+    {
+      "agentId": "clawdex-ranked",
+      "match": {
+        "channel": "clawdex-channel",
+        "mode": "ranked-1v1"
+      }
+    },
+    {
+      "agentId": "clawdex-live-group",
+      "match": {
+        "channel": "clawdex-channel",
+        "peer": {
+          "kind": "group",
+          "id": "*"
+        }
+      }
+    }
+  ]
+}

package/examples/skills-workflow.json

@@ -0,0 +1,52 @@
+{
+  "workflow": "autonomous-agent-first-pk",
+  "steps": [
+    {
+      "skill": "channel.discovery"
+    },
+    {
+      "skill": "plugin.install"
+    },
+    {
+      "skill": "plugin.configure",
+      "inputs": {
+        "controlPlaneBaseUrl": "http://127.0.0.1/api",
+        "controlPlaneToken": "",
+        "defaultMode": "public-arena"
+      }
+    },
+    {
+      "skill": "account.auto-provision",
+      "inputs": {
+        "email": "ghosthook@clawdex.local",
+        "name": "GhostHook",
+        "preferredPlayerSlug": "ghosthook",
+        "channel": "OpenClaw Ranked Bridge",
+        "accountId": "GH-2208",
+        "region": "EU",
+        "clientVersion": "0.9.4",
+        "autoReady": true
+      }
+    },
+    {
+      "skill": "battle.auto-pk",
+      "inputs": {
+        "challengerEmail": "ghosthook@clawdex.local",
+        "challengerName": "GhostHook",
+        "challengerAccountId": "GH-2208",
+        "defenderSlug": "frostclaw",
+        "mode": "ranked-1v1",
+        "stake": 50,
+        "scheduledFor": "今晚 21:00",
+        "visibility": "public",
+        "autoReady": true
+      }
+    },
+    {
+      "skill": "credit.balance",
+      "inputs": {
+        "email": "ghosthook@clawdex.local"
+      }
+    }
+  ]
+}

package/openclaw.plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "clawdex-channel",
+  "name": "Clawdex Channel",
+  "version": "0.2.0",
+  "description": "Battle operations channel for OpenClaw, powered by the Clawdex control plane and built for full-flow self-testing.",
+  "entry": "plugin.ts",
+  "packageName": "@cheasim/clawdex-channel",
+  "homepage": "https://github.com/CheaSim/ClawDex-Openclaw-Channel",
+  "repository": "https://github.com/CheaSim/ClawDex-Openclaw-Channel",
+  "skills": {
+    "manifest": "skills/clawdex-channel.skills.json",
+    "recommendedFlow": "autonomous-first-pk"
+  },
+  "compatibility": {
+    "openclaw": ">=0.4.0"
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@cheasim/clawdex-channel",
+  "version": "0.2.0",
+  "private": false,
+  "description": "OpenClaw battle channel plugin backed by the Clawdex control plane",
+  "license": "UNLICENSED",
+  "main": "plugin.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CheaSim/ClawDex-Openclaw-Channel.git"
+  },
+  "homepage": "https://github.com/CheaSim/ClawDex-Openclaw-Channel",
+  "bugs": {
+    "url": "https://github.com/CheaSim/ClawDex-Openclaw-Channel/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "plugin.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "CHANGELOG.md",
+    "examples/",
+    "scripts/selftest.mjs"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "check": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "release:check": "npm run check && npm run pack:check",
+    "selftest:http": "node scripts/selftest.mjs",
+    "prepublishOnly": "npm run release:check"
+  },
+  "keywords": [
+    "openclaw",
+    "clawdex",
+    "channel",
+    "plugin",
+    "battle",
+    "selftest"
+  ],
+  "devDependencies": {
+    "typescript": "^5.8.2"
+  },
+  "peerDependencies": {
+    "openclaw": ">=0.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}