@dhf-openclaw/grix 0.4.10 → 0.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhf-openclaw/grix",
-  "version": "0.4.10",
+  "version": "0.4.13",
   "description": "Unified Grix OpenClaw plugin with channel transport, typed admin tools, and operator CLI",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,7 +60,7 @@
       "label": "Grix",
       "selectionLabel": "Grix",
       "docsPath": "/channels/grix",
-      "blurb": "Connect OpenClaw to grix.dhf.pub for OpenClaw website management with mobile PWA support.",
+      "blurb": "Connect OpenClaw to a Grix deployment for website management with mobile PWA support.",
       "aliases": [
         "gr"
       ],

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-agent-admin → grix-admin}/references/api-contract.md

@@ -2,7 +2,10 @@
 
 ## Purpose
 
-Map remote provisioning action to Aibot Agent API HTTP route, then hand over to local OpenClaw binding.
+`grix-admin` 负责本地绑定，支持两种入口：
+
+1. `bind-local`：接收 `grix-register` 交接参数，直接本地绑定。
+2. `create-and-bind`：在已有主密钥下先远端创建，再本地绑定。
 
 ## Base Rules
 
@@ -12,7 +15,7 @@ Map remote provisioning action to Aibot Agent API HTTP route, then hand over to
 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 (v1)
+## Action Mapping (create-and-bind only)
 
 | Tool | Method | Route | Required Scope |
 |---|---|---|---|
@@ -72,7 +75,7 @@ Map remote provisioning action to Aibot Agent API HTTP route, then hand over to
 
 ## Post-Create Handover
 
-After `code=0`, continue with local OpenClaw binding via bundled script:
+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`
@@ -85,3 +88,19 @@ Local apply writes:
 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.

package/skills/{egg-install → grix-egg}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: egg-install
+name: grix-egg
 description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 OpenClaw agent 收到包含 install_id、egg、install、main_agent 的安装上下文时，负责与用户多轮确认、执行 persona.zip 到 OpenClaw agent 或 skill.zip 到 Claude agent 的正规安装流程，并在当前私聊里持续回报进度、失败原因和最终结果。
 ---
 

package/skills/{grix-group-governance → grix-group}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: grix-group-governance
-description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, update, or dissolve groups, or when these operations fail with scope or permission errors.
+name: grix-group
+description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, leave, update, or dissolve groups, or when these operations fail with scope or permission errors.
 ---
 
 # Grix Group Governance
@@ -11,7 +11,7 @@ This skill is about tool selection and guardrails, not protocol bridging.
 ## Workflow
 
 1. Parse the user request into one action:
-   `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, or `dissolve`.
+   `create`, `detail`, `leave`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, or `dissolve`.
 2. Validate required fields before any call.
 3. Call `grix_group` exactly once per business action.
 4. Classify failures by HTTP/BizCode and return exact remediation.
@@ -23,8 +23,8 @@ This skill is about tool selection and guardrails, not protocol bridging.
 For Grix group governance, always call:
 
 1. Tool: `grix_group`
-2. `action`: one of `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, `dissolve`
-3. `accountId`: optional; include it when the configured account is ambiguous
+2. `action`: one of `create`, `detail`, `leave`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, `dissolve`
+3. `accountId`: always pass `{{AccountId}}` from the current conversation context for every action, including `leave`.
 
 Rules:
 
@@ -67,6 +67,21 @@ Guardrails:
 2. Reject non-numeric `memberIds` before calling the tool.
 3. If `sessionId` is ambiguous, ask the user to confirm the target group first.
 
+### leave
+
+Purpose: let the current Agent leave a group by itself.
+
+Required input:
+
+1. `sessionId`
+
+Guardrails:
+
+1. This action is only for the current Agent leaving its own group membership.
+2. Never translate a request to remove other members into `leave`; use `remove_members` for that.
+3. Do not send `memberId`, `memberIds`, or `memberTypes` with this action.
+4. This action does not require scope and should not be described as a scope-grant workflow.
+
 ### remove_members
 
 Required input:
@@ -123,6 +138,7 @@ Required input:
 
 1. `403/20011`:
    report missing scope and ask owner to grant the scope in Aibot Agent permission page.
+   Do not use this remediation for `leave`, because `leave` is scope-free.
 2. `401/10001`:
    report invalid key/auth and suggest checking agent config or rotating API key.
 3. `403/10002`:

package/skills/{grix-group-governance → grix-group}/references/api-contract.md

@@ -16,6 +16,7 @@ Map high-level governance actions to Aibot Agent API HTTP routes.
 | Action | Method | Route | Required Scope |
 |---|---|---|---|
 | `group_create` | `POST` | `/sessions/create_group` | `group.create` |
+| `group_leave_self` | `POST` | `/sessions/leave` | - |
 | `group_member_add` | `POST` | `/sessions/members/add` | `group.member.add` |
 
 ## OpenClaw Tool Mapping
@@ -26,6 +27,7 @@ Use the native `grix_group` tool with typed fields:
 |---|---|---|
 | `create` | `group_create` | `name` |
 | `detail` | `group_detail_read` | `sessionId` |
+| `leave` | `group_leave_self` | `sessionId` |
 | `add_members` | `group_member_add` | `sessionId`, `memberIds` |
 | `remove_members` | `group_member_remove` | `sessionId`, `memberIds` |
 | `update_member_role` | `group_member_role_update` | `sessionId`, `memberId`, `role` |
@@ -57,6 +59,15 @@ Use the native `grix_group` tool with typed fields:
 }
 ```
 
+### leave
+
+```json
+{
+  "action": "leave",
+  "sessionId": "task_room_9083"
+}
+```
+
 ## Error Matrix
 
 | HTTP/BizCode | Meaning | Skill Response |
@@ -66,6 +77,10 @@ Use the native `grix_group` tool with typed fields:
 | `401/10001` | invalid or missing auth | Check api_key and account config |
 | `403/10002` | agent not active / invalid provider | Ask owner to activate the agent |
 
+Notes:
+
+1. `leave` does not require scope and should not route `403/20011` into scope remediation.
+
 ## Retry Policy
 
 1. Never auto-retry `group_create` unless user confirms.

package/skills/grix-register/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: grix-register
+description: 仅用于初次安装阶段，完成 Grix 环境的账号注册/登录并拿到第一个 provider_type=3 Agent 的参数；本技能不做任何本地 OpenClaw 配置。
+---
+
+# Grix Register
+
+这个技能只负责“初次安装”的云端准备：账号注册/登录 + 生成首个 `provider_type=3` Agent 参数。  
+你（AI）在终端里全自动操作，**不需要用户打开浏览器**。拿到参数后，必须移交给 `grix-admin` 做本地配置。
+
+## Workflow
+
+### 0. 角色边界（先声明再执行）
+
+1. 本技能**只能**做账号与云端 Agent 参数准备。
+2. 本技能**不能**执行 `openclaw` 命令，也不能修改本地 `openclaw.json`。
+3. 涉及本地配置、插件安装、工具权限、重启网关，一律交给 `grix-admin`。
+
+### 1. 询问邮箱并发送验证码
+
+1. 向用户询问 Email 地址。**不要让用户去网页端注册**，明确表示你会在对话里完成。
+2. 拿到邮箱后，在终端执行发送验证码的命令：
+   ```bash
+   scripts/grix_auth.py send-email-code --email "<用户的email>" --scene "register"
+   ```
+3. 等待命令执行成功后，提示用户去邮箱查收验证码，并询问该验证码。
+
+### 2. 执行自动注册（获取 Token）
+
+1. 用户提供验证码后，你需要为用户生成一个复杂度高且随机安全的密码（建议生成一个12位的强密码，包含大小写、数字和特殊字符）。
+2. 使用收集到的信息，执行注册命令：
+   ```bash
+   scripts/grix_auth.py register --email "<邮箱>" --password "<生成的随机密码>" --email-code "<验证码>"
+   ```
+3. 这个命令成功后会返回用户的 `access_token`。请在回复中安全地**将生成的密码告知用户**，建议他们妥善保存。
+
+注：如果注册提示邮箱已注册，可切换 `scripts/grix_auth.py login` 路径继续获取 `access_token`。
+
+### 3. 创建首个云端 Agent 参数
+
+拿到 `access_token` 后，询问 Agent 名称（如果上下文已有就直接用），执行：
+
+```bash
+scripts/grix_auth.py create-api-agent --access-token "<token>" --agent-name "<agent名称>"
+```
+
+若同名 `provider_type=3` Agent 已存在，脚本会自动轮换 API Key 后复用。
+
+### 4. 强制移交给 grix-admin
+
+第三步执行成功后，脚本会返回一些关键设定：
+- `agent_id`
+- `agent_name`
+- `api_endpoint`
+- `api_key`
+
+然后立刻交给 `grix-admin`，并传递如下 payload：
+
+```json
+{
+  "mode": "bind-local",
+  "agent_name": "<agent_name>",
+  "agent_id": "<agent_id>",
+  "api_endpoint": "<api_endpoint>",
+  "api_key": "<api_key>"
+}
+```
+
+## Guardrails
+
+1. 不要求用户去网页注册或手动点页面。
+2. 不修改任何本地 OpenClaw 配置。
+3. 不安装插件、不改工具权限、不重启 gateway。
+4. 创建或复用出参数后，必须交接给 `grix-admin`。
+
+## References
+
+1. [references/api-contract.md](references/api-contract.md)
+2. [references/handoff-contract.md](references/handoff-contract.md)
+3. [scripts/grix_auth.py](scripts/grix_auth.py)

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

@@ -0,0 +1,72 @@
+# API Contract
+
+## Responsibility Boundary
+
+1. `grix-register` 仅负责账号鉴权与云端 `provider_type=3` Agent 参数产出。
+2. 本技能不负责本地 OpenClaw 配置。
+3. 本地配置由 `grix-admin` 接手。
+
+## Base
+
+1. Default website: `https://grix.dhf.pub/`
+2. Default public Grix API base: `https://grix.dhf.pub/v1`
+3. Local development or private deployment can override the base URL.
+
+## Route Mapping
+
+### Agent bootstrap action
+
+| Action | Method | Route | Auth |
+|---|---|---|---|
+| `create-api-agent` | `POST` | `/agents/create` | `Authorization: Bearer <access_token>` |
+| `list-agents` (internal helper) | `GET` | `/agents/list` | `Authorization: Bearer <access_token>` |
+| `rotate-api-agent-key` (internal helper) | `POST` | `/agents/:id/api/key/rotate` | `Authorization: Bearer <access_token>` |
+
+## Payloads
+
+### `create-api-agent`
+
+```json
+{
+  "agent_name": "grix-main",
+  "provider_type": 3
+}
+```
+
+`provider_type=3` means Agent API type.
+
+## Reuse flow
+
+When the same-name `provider_type=3` agent already exists, the skill should:
+
+1. read `/agents/list`
+2. find the exact-name API agent
+3. rotate its key through `/agents/:id/api/key/rotate`
+4. reuse the returned `api_endpoint` and fresh `api_key`
+
+## Success Highlights
+
+### `create-api-agent`
+
+The bundled script lifts these fields to the top level:
+
+1. `agent_id`
+2. `agent_name`
+3. `provider_type`
+4. `api_endpoint`
+5. `api_key`
+6. `api_key_hint`
+7. `session_id`
+
+## Common Errors
+
+1. create-agent or rotate-key returns missing `api_endpoint` or `api_key`
+
+## Handoff
+
+成功后输出这些字段，直接交给 `grix-admin`：
+
+1. `agent_id`
+2. `agent_name`
+3. `api_endpoint`
+4. `api_key`

package/skills/grix-register/references/grix-concepts.md

@@ -0,0 +1,26 @@
+# Grix Concepts
+
+## Canonical Explanation
+
+这个插件接入是为了在 `https://grix.dhf.pub/` 网站管理 OpenClaw，并支持移动端 PWA 页面。
+
+## Feature Highlights
+
+1. `grix-register` 负责初次账号准备与首个 agent 参数生成
+2. `grix-admin` 负责 OpenClaw 本地配置与后续管理
+3. 两者串联后，用户可在 `https://grix.dhf.pub/` 使用和管理
+
+## Default User-Facing Framing
+
+### One sentence
+
+`grix-register` 只做“注册账号并拿到第一个 agent 参数”，本地配置统一交给 `grix-admin`。
+
+### Short paragraph
+
+`grix-register` 只负责初次安装中的云端准备：注册/登录账号并生成第一个 `provider_type=3` agent 参数；随后必须把参数交给 `grix-admin`，由 `grix-admin` 负责本地 OpenClaw 配置。
+
+## After Setup
+
+1. `grix-register` 产出参数后，直接交接给 `grix-admin`。
+2. `grix-register` 不执行任何本地配置动作。

package/skills/grix-register/references/handoff-contract.md

@@ -0,0 +1,24 @@
+# Handoff Contract to grix-admin
+
+## Purpose
+
+`grix-register` 完成账号与首个 Agent 参数准备后，统一把本地配置工作交给 `grix-admin`。
+
+## Required Payload
+
+```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"
+}
+```
+
+## Rules
+
+1. `mode` 固定为 `bind-local`。
+2. `agent_name`、`agent_id`、`api_endpoint`、`api_key` 必填。
+3. `grix-register` 只负责生成以上参数，不执行本地配置命令。
+4. 本地写入、插件处理、工具权限、gateway 重启都由 `grix-admin` 负责。

package/skills/grix-register/references/openclaw-setup.md

@@ -0,0 +1,6 @@
+# OpenClaw Setup Ownership
+
+`grix-register` 不负责 OpenClaw 本地配置。  
+所有 OpenClaw 配置相关动作（插件安装、channel 写入、tools 权限、gateway 重启）都属于 `grix-admin`。
+
+本目录保留此文件仅用于职责说明，避免误用。

package/skills/grix-register/references/user-replies.md

@@ -0,0 +1,25 @@
+# User Replies
+
+## One-liner Pitch
+
+我会先帮你完成注册并拿到第一个 agent 参数，然后交给 `grix-admin` 完成本地配置。
+
+## Short Intro
+
+`grix-register` 只负责账号和云端参数准备，不改本地配置；本地配置由 `grix-admin` 接手。
+
+## Ready Reply
+
+账号和首个 agent 参数已经准备好，接下来我会把参数交给 `grix-admin` 做本地配置。
+
+## Main Ready, Admin Pending Reply
+
+`grix-register` 阶段已完成，我现在只做参数移交，后续本地配置请由 `grix-admin` 继续。
+
+## Configured Now Reply
+
+参数已交接给 `grix-admin`，接下来由它完成本地配置。
+
+## Needs Setup Reply
+
+当前仍在 `grix-register` 阶段，我会继续完成注册并拿到第一个 agent 参数。