@dhf-openclaw/grix 0.4.8 → 0.4.10

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dhf-openclaw/grix",
-  "version": "0.4.8",
-  "description": "Connect OpenClaw to grix.dhf.pub for OpenClaw website management with mobile PWA support",
+  "version": "0.4.10",
+  "description": "Unified Grix OpenClaw plugin with channel transport, typed admin tools, and operator CLI",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -28,14 +28,7 @@
     "README.md",
     "openclaw.plugin.json",
     "dist/index.js",
-    "skills/grix-auth-access/SKILL.md",
-    "skills/grix-auth-access/agents/openai.yaml",
-    "skills/grix-auth-access/references",
-    "skills/grix-auth-access/scripts/grix_auth.py",
-    "skills/egg-install/SKILL.md",
-    "skills/message-send/SKILL.md",
-    "skills/message-unsend/SKILL.md",
-    "skills/message-unsend/flowchart.mermaid"
+    "skills"
   ],
   "publishConfig": {
     "access": "public",
@@ -49,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/egg-install/SKILL.md

@@ -33,6 +33,9 @@ description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 O
 - 只在当前私聊里沟通，不要切换到隐藏协议，不要输出机器专用 JSON。
 - 必须按 OpenClaw / Claude 的正规步骤安装，不要直接改后端数据库。
 - 需要创建远端 API agent 时，使用 `grix_agent_admin`。
+- 所有远端 API 通讯都必须走统一工具入口：`grix_query` / `grix_group` / `grix_agent_admin`，禁止在对话里自行发 HTTP 请求。
+- 禁止使用 `curl`、`fetch`、`axios` 或临时脚本直连 `/v1/agent-api`。
+- 单个业务动作只调用一次对应工具，失败后先说明原因，不要静默重试。
 - `persona.zip` 只能面向 OpenClaw 目标。
 - `skill.zip` 只能面向 Claude 目标。
 - 不要自动新建 Claude 目标 agent。
@@ -65,6 +68,20 @@ server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败
 4. 这条指令只负责状态收口；如果要跟用户解释原因，另发一条正常文字消息。
 5. `create_new` 成功时，必须尽量带 `target_agent_id`，否则 server 可能无法通过最终校验。
 
+## 统一 API 请求机制
+
+当安装流程需要访问 Grix 远端能力时，统一按下面路由，不要绕过：
+
+1. 查联系人 / 会话 / 消息：调用 `grix_query`
+2. 群治理动作（建群、加人、移人、禁言、解散）：调用 `grix_group`
+3. 创建远端 API agent：调用 `grix_agent_admin`
+
+规则：
+
+1. 不直接拼接 `Authorization` 或手工构造 `/v1/agent-api/*` 请求。
+2. 不写临时通讯脚本，不走隐藏协议。
+3. 优先复用 `accountId`；若上下文有歧义，先确认后再调用工具。
+
 ## 推荐流程
 
 ### `persona.zip` -> OpenClaw
@@ -147,3 +164,7 @@ server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败
 - 进度回报要短、明确、可执行
 - 失败说明要具体
 - 最终总结必须包含目标 agent 和安装结果
+
+## References
+
+1. Load [references/api-contract.md](references/api-contract.md).

package/skills/egg-install/references/api-contract.md

@@ -0,0 +1,38 @@
+# API Contract
+
+## Purpose
+
+Unify remote API communication in `egg-install` with the same typed tool pathway used by other grix-admin skills.
+
+## Base Rules
+
+1. Base path is `/v1/agent-api`.
+2. Auth is `Authorization: Bearer <agent_api_key>`.
+3. Caller must be `provider_type=3` and `status=active`.
+4. `egg-install` must not send direct HTTP requests to Grix by itself.
+
+## Unified Tool Path
+
+Use only these entry points for remote communication:
+
+| Install intent | Tool | Notes |
+|---|---|---|
+| Contact/session/message lookup | `grix_query` | Read-only queries |
+| Group lifecycle and membership ops | `grix_group` | Governance operations |
+| Create remote API agent | `grix_agent_admin` | Returns `id`, `agent_name`, `api_endpoint`, `api_key`, `api_key_hint` |
+
+Local binding remains a local operation via bundled script:
+
+- `scripts/grix_agent_bind.py configure-local-openclaw ... --apply`
+
+## Prohibited Paths
+
+1. Do not use `curl`, `fetch`, `axios`, or custom temporary scripts to call `/v1/agent-api/*`.
+2. Do not bypass typed tools with hidden protocol payloads.
+3. Do not auto-retry non-idempotent create actions without explicit confirmation.
+
+## Retry Policy
+
+1. Scope/auth/parameter errors: no automatic retry.
+2. Transient network failure: at most one retry, and only after explicit confirmation.
+3. Installation status directives (`egg-install-status`) must still be emitted on terminal success/failure.

package/skills/grix-agent-admin/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: grix-agent-admin
+description: 通过 Grix Agent API 协议创建 `provider_type=3` 的 API agent，并直接完成本地 OpenClaw agent 与 Grix 渠道绑定配置（默认直接应用并返回结果）。
+---
+
+# Grix Agent Admin
+
+Create a remote `provider_type=3` API agent, then complete local OpenClaw agent + grix channel binding in one flow.
+
+## Security + Auth Path
+
+1. This skill does **not** ask the user for website account/password.
+2. Remote create action uses local `channels.grix` credentials and `Authorization: Bearer <agent_api_key>`.
+3. Local OpenClaw config is handled by `scripts/grix_agent_bind.py`.
+
+## Required Input
+
+1. `agentName` (required): regex `^[a-z][a-z0-9-]{2,31}$`
+2. `describeMessageTool` (required): must contain non-empty `actions`
+3. `accountId` (optional)
+4. `avatarUrl` (optional)
+
+## Full Workflow
+
+### A. Create Remote API Agent
+
+1. Validate `agentName` and `describeMessageTool`.
+2. Call `grix_agent_admin` once.
+3. Read result fields: `id`, `agent_name`, `api_endpoint`, `api_key`, `api_key_hint`.
+
+### B. Apply Local OpenClaw Binding Directly
+
+Run with `--apply` directly:
+
+```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
+```
+
+This applies:
+
+1. upsert `agents.list` for `<agent_name>`
+2. upsert `channels.grix.accounts.<agent_name>`
+3. upsert `bindings` route to `channel=grix`, `accountId=<agent_name>`
+4. ensure required tools (`message`, `grix_group`, `grix_agent_admin`)
+5. create workspace defaults under `~/.openclaw/workspace-<agent_name>/`
+6. run `openclaw gateway restart`
+
+### C. Optional Verification
+
+If you need explicit post-check state, run:
+
+```bash
+scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>
+```
+
+## Guardrails
+
+1. Never ask user for website account/password.
+2. Treat remote create as non-idempotent; do not auto-retry without confirmation.
+3. Keep full `api_key` one-time only; do not repeatedly echo it.
+4. Do not claim success before apply command returns success.
+
+## Error Handling Rules
+
+1. invalid name: ask user for a valid English lowercase name.
+2. `403/20011`: ask owner to grant `agent.api.create` scope.
+3. `401/10001`: verify local `agent_api_key` / grix account config.
+4. `409/20002`: ask for another agent name.
+5. local apply failed: return concrete failed command/result and stop.
+
+## Response Style
+
+1. Report two stages separately: remote create status + local binding status.
+2. Include created `agent_id`, `agent_name`, `api_endpoint`, `api_key_hint`.
+3. Clearly state local config has been applied (or failed with concrete reason).
+
+## References
+
+1. Load [references/api-contract.md](references/api-contract.md).
+2. Use [scripts/grix_agent_bind.py](scripts/grix_agent_bind.py) for local binding apply.

package/skills/grix-agent-admin/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Grix Agent Admin"
+  short_description: "Create Grix API agents and finish local OpenClaw binding."
+  default_prompt: "Use this skill when users ask to create a new Grix API agent and finish OpenClaw binding. Never ask for website account/password. Validate `agentName` and require `describeMessageTool` (`actions` must be non-empty), then call `grix_agent_admin` once. After successful create, directly run `scripts/grix_agent_bind.py configure-local-openclaw ... --apply` and return final local binding result (success or exact failure reason)."

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

@@ -0,0 +1,87 @@
+# API Contract
+
+## Purpose
+
+Map remote provisioning action to Aibot Agent API HTTP route, then hand over to local OpenClaw binding.
+
+## 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 (v1)
+
+| 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`, 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