@dhf-openclaw/grix 0.4.9 → 0.4.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dhf-openclaw/grix",
-  "version": "0.4.9",
-  "description": "Connect OpenClaw to grix.dhf.pub for OpenClaw website management with mobile PWA support",
+  "version": "0.4.11",
+  "description": "Unified Grix OpenClaw plugin with channel transport, typed admin tools, and operator CLI",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -28,9 +28,7 @@
     "README.md",
     "openclaw.plugin.json",
     "dist/index.js",
-    "skills/message-send/SKILL.md",
-    "skills/message-unsend/SKILL.md",
-    "skills/message-unsend/flowchart.mermaid"
+    "skills"
   ],
   "publishConfig": {
     "access": "public",
@@ -44,7 +42,7 @@
     "publish:npm": "npm run publish:npm:preview",
     "publish:npm:preview": "bash ./scripts/publish_npm.sh",
     "publish:npm:release": "bash ./scripts/publish_npm.sh --publish",
-    "test": "node --test src/*.test.ts"
+    "test": "node --test src/*.test.ts src/admin/*.test.ts"
   },
   "devDependencies": {
     "esbuild": "0.27.4",

package/skills/grix-admin/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: grix-admin
+description: 负责 OpenClaw 本地配置与后续 agent 管理；支持接收 grix-register 交接参数直接落地，也支持在已有主密钥下新建 agent 再落地。
+---
+
+# Grix Agent Admin
+
+`grix-admin` 只负责本地配置和管理动作。支持两个入口模式，二选一执行。
+
+## Mode A: bind-local（来自 grix-register 的首次交接）
+
+输入参数（全必填）：
+
+1. `mode=bind-local`
+2. `agent_name`
+3. `agent_id`
+4. `api_endpoint`
+5. `api_key`
+
+执行规则：
+
+1. 不做远端创建，直接执行本地绑定：
+
+```bash
+scripts/grix_agent_bind.py configure-local-openclaw \
+  --agent-name <agent_name> \
+  --agent-id <agent_id> \
+  --api-endpoint '<api_endpoint>' \
+  --api-key '<api_key>' \
+  --apply
+```
+
+2. 可选执行检查：
+
+```bash
+scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>
+```
+
+## Mode B: create-and-bind（已有主密钥时的后续管理）
+
+输入参数：
+
+1. `agentName`（必填）：`^[a-z][a-z0-9-]{2,31}$`
+2. `describeMessageTool`（必填）：`actions` 非空
+3. `accountId`（可选）
+4. `avatarUrl`（可选）
+
+执行规则：
+
+1. 先检查 `~/.openclaw/openclaw.json` 的 `channels.grix.apiKey`。
+2. 若缺失或为空，说明主通道还没完成，不做本模式，立刻切回 `grix-register`。
+3. 若已存在，再调用 `grix_agent_admin` 创建远端 agent（仅一次，不自动重试）。
+4. 创建成功后，执行本地绑定命令（同 Mode A）。
+
+## Guardrails（两种模式都适用）
+
+1. Never ask user for website account/password.
+2. `bind-local` 模式禁止再次回调 `grix-register`，避免循环路由。
+3. 远端创建（Mode B）视为非幂等，不确认不自动重试。
+4. 完整 `api_key` 仅一次性回传，不要重复明文回显。
+5. 本地 `--apply` 没成功前，不得宣称配置完成。
+
+## Error Handling Rules
+
+1. `bind-local` 缺少字段：明确指出缺哪个字段并停止。
+2. invalid name（Mode B）：要求用户提供合法小写英文名。
+3. `403/20011`：提示 owner 授权 `agent.api.create`。
+4. `401/10001`：检查本地 `agent_api_key` 或 grix 账号配置。
+5. `409/20002`：要求更换 agent 名称。
+6. 本地 apply 失败：返回失败命令与结果并停止。
+
+## Response Style
+
+1. 明确写出当前执行的是 `bind-local` 还是 `create-and-bind`。
+2. 分阶段汇报：远端（如有）+ 本地绑定。
+3. 明确说明本地是否已生效，失败则给具体原因。
+
+## References
+
+1. [references/api-contract.md](references/api-contract.md)
+2. [scripts/grix_agent_bind.py](scripts/grix_agent_bind.py)

package/skills/grix-admin/references/api-contract.md

@@ -0,0 +1,106 @@
+# API Contract
+
+## Purpose
+
+`grix-admin` 负责本地绑定，支持两种入口：
+
+1. `bind-local`：接收 `grix-register` 交接参数，直接本地绑定。
+2. `create-and-bind`：在已有主密钥下先远端创建，再本地绑定。
+
+## Base Rules
+
+1. Base path: `/v1/agent-api`
+2. Auth: `Authorization: Bearer <agent_api_key>`
+3. Caller must be `provider_type=3` and `status=active`.
+4. Route must pass scope middleware before service business checks.
+5. Do not ask users to provide website account/password for this flow.
+
+## Action Mapping (create-and-bind only)
+
+| Tool | Method | Route | Required Scope |
+|---|---|---|---|
+| `grix_agent_admin` | `POST` | `/agents/create` | `agent.api.create` |
+
+## Payload Template
+
+```json
+{
+  "agentName": "ops-assistant",
+  "avatarUrl": "https://example.com/avatar.png",
+  "describeMessageTool": {
+    "actions": ["unsend", "delete"]
+  }
+}
+```
+
+`agentName` validation rule for this skill:
+
+- regex: `^[a-z][a-z0-9-]{2,31}$`
+- only lowercase English letters, digits, and hyphen
+
+`describeMessageTool` is required and must align with OpenClaw SDK discovery shape (`actions` required, optional `capabilities` and `schema`).
+
+## Success Payload Highlights
+
+```json
+{
+  "code": 0,
+  "data": {
+    "id": "2029786829095440384",
+    "agent_name": "ops-assistant",
+    "provider_type": 3,
+    "api_endpoint": "ws://host/v1/agent-api/ws?agent_id=2029786829095440384",
+    "api_key": "ak_2029786829095440384_xxx",
+    "api_key_hint": "xxxxxx12"
+  }
+}
+```
+
+## Error Matrix
+
+| HTTP/BizCode | Meaning | Skill Response |
+|---|---|---|
+| `403/20011` | `agent.api.create` scope missing | Ask owner to grant scope |
+| `401/10001` | invalid or missing auth | Check `api_key` and account config |
+| `403/10002` | caller agent inactive / invalid provider | Ask owner to activate caller agent |
+| `409/20002` | duplicate agent name | Ask user for another `agent_name` |
+| `400/20004` | owner quota exceeded | Ask owner to clean up unused agents |
+| `400/10003` | invalid payload | Ask for corrected parameters |
+
+## Retry Policy
+
+1. Never auto-retry `agent_api_create` unless user explicitly confirms.
+2. Do not retry scope/auth/parameter failures.
+3. Network transient errors can be retried once after explicit confirmation.
+
+## Post-Create Handover
+
+After `code=0` (or when using `bind-local` mode), continue with local OpenClaw binding via bundled script:
+
+1. apply local changes directly:
+   - `scripts/grix_agent_bind.py configure-local-openclaw --agent-name <agent_name> --agent-id <agent_id> --api-endpoint '<api_endpoint>' --api-key '<api_key>' --apply`
+2. optionally run inspect after apply when you need state verification:
+   - `scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>`
+
+Local apply writes:
+
+1. `agents.list` entry
+2. `channels.grix.accounts.<agent_name>` entry
+3. `bindings` route for `channel=grix`
+4. required tools config and gateway restart
+
+## bind-local Input Contract
+
+When called from `grix-register`, `grix-admin` should accept:
+
+```json
+{
+  "mode": "bind-local",
+  "agent_name": "grix-main",
+  "agent_id": "2029786829095440384",
+  "api_endpoint": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=2029786829095440384",
+  "api_key": "ak_xxx"
+}
+```
+
+In this mode, skip remote create and execute local bind directly.