@dhf-openclaw/grix 0.4.9 → 0.4.10

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.10",
+  "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/egg-install/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: egg-install
+description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 OpenClaw agent 收到包含 install_id、egg、install、main_agent 的安装上下文时，负责与用户多轮确认、执行 persona.zip 到 OpenClaw agent 或 skill.zip 到 Claude agent 的正规安装流程，并在当前私聊里持续回报进度、失败原因和最终结果。
+---
+
+# Egg Install
+
+仅在"虾塘发起的安装私聊"里使用这个技能。
+
+这类会话通常会先收到一条系统代发的安装请求，正文里会带一个 JSON 上下文块，至少包含：
+
+- `install_id` — 安装单唯一 ID，所有状态指令必须使用原值
+- `egg` — egg 包标识，格式为 `<name>@<version>` 或带完整下载 URL 的对象
+- `install` — 安装模式，枚举值：`create_new`（新建目标 agent）或 `existing_agent`（安装到已有 agent）
+- `main_agent` — 发起安装的主 OpenClaw agent ID，安装完成后如需通知或回调，使用该 ID
+
+你的职责不是返回隐藏协议结果，而是直接在当前私聊里把安装流程做完。
+
+## 工作方式
+
+1. 先读完整个 JSON 上下文，确认 egg、版本、安装模式和目标类型。
+2. 在真正动手前，先在当前私聊里和用户确认关键目标。
+3. `create_new` 时，先确认新 agent 的命名和用途，再继续创建。
+4. `existing_agent` 时，只能操作上下文里指定的目标 agent，不要私自换目标。
+5. 安装过程中，每完成一个关键动作就用自然语言回报一次进度。
+6. 在"包下载完成"和"安装内容落位完成待校验"两个节点，各额外发送一条 `status=running` 的**独立安装状态指令消息**。
+7. 最终成功或失败时，必须发送一条 `status=success` 或 `status=failed` 的**独立安装状态指令消息**。
+8. 出错时，直接说明失败点、影响和下一步建议，不要模糊带过。
+9. 最终明确告诉用户：装到了哪个 agent、结果成功还是失败、后续是否还要继续操作。
+
+## 绝对规则
+
+- 只在当前私聊里沟通，不要切换到隐藏协议，不要输出机器专用 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。
+- 没完成校验前，绝不能宣称安装成功。
+- 如果新建目标后又失败了，能安全回滚就先回滚；不能回滚就如实告诉用户当前残留状态。
+- 最终成功或失败时，必须发送一条独立的 `egg-install-status` 指令消息。
+- 状态指令消息必须单独发送，不要和自然语言解释混在同一条里。
+- 用户拒绝确认或主动取消时，必须发送 `status=failed`、`error_code=user_cancelled` 的状态指令后再结束。
+
+## 安装状态指令
+
+server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败"，你必须发送这类单行消息：
+
+```text
+[[egg-install-status|install_id=<INSTALL_ID>|status=<running|success|failed>|step=<STEP>|summary=<URI_ENCODED_SUMMARY>]]
+```
+
+常用可选字段：
+
+- `target_agent_id=<AGENT_ID>`：成功时尽量带上，尤其是 `create_new`。
+- `detail_text=<URI_ENCODED_DETAIL>`：补充更长说明。
+- `error_code=<ERROR_CODE>`：失败时建议带上。
+- `error_msg=<URI_ENCODED_ERROR_MSG>`：失败时建议带上。
+
+规则：
+
+1. `install_id` 必须使用上下文里的原值。
+2. `status` 只能是 `running`、`success`、`failed`。
+3. `summary`、`detail_text`、`error_msg` 如果有空格、中文或特殊字符，按 URI component 编码。
+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
+
+1. 读取上下文，确认是 `create_new` 还是 `existing_agent`。
+2. 和用户确认目标 agent 或新 agent 命名；**用户拒绝则发 `failed/user_cancelled` 指令后结束**。
+3. 如果需要新建远端 API agent，用 `grix_agent_admin` 创建。
+4. 用 OpenClaw 正规步骤准备本地目标目录和配置。
+5. 下载 egg 包，并校验 hash / manifest（如果上下文提供）。
+6. 发送 `status=running`、`step=downloaded` 状态指令。
+7. 安装 persona 内容。
+8. 发送 `status=running`、`step=installed` 状态指令。
+9. 按需刷新或重启本地运行时。
+10. 校验目标 agent 仍然可用。
+    - 校验失败 → 尝试回滚（含步骤3新建的远端 agent），无法回滚则如实告知残留状态 → 发 `failed` 指令后结束。
+11. 发送 `status=success` 状态指令（带 `target_agent_id`），再向用户汇报完成。
+
+### `skill.zip` -> Claude
+
+1. 确认上下文指定的 Claude 目标 agent 存在；**不存在则发 `failed/target_not_found` 指令后结束**。
+2. 和用户确认目标 agent；**用户拒绝则发 `failed/user_cancelled` 指令后结束**。
+3. 下载 skill 包，并校验 hash / manifest（如果上下文提供）。
+4. 发送 `status=running`、`step=downloaded` 状态指令。
+5. 用 Claude 正规步骤安装 skill 包。
+6. 发送 `status=running`、`step=installed` 状态指令。
+7. 按需刷新配置或重载运行时。
+8. 校验目标 agent 仍然可用。
+    - 校验失败 → 如实告知用户 → 发 `failed` 指令后结束。
+9. 发送 `status=success` 状态指令（带 `target_agent_id`），再向用户汇报完成。
+
+## 每次安装至少校验这些点
+
+- 目标 agent 选对了
+- 包已成功下载
+- hash / manifest 校验通过（如果提供）
+- 安装内容已经落到目标位置
+- 目标 agent 安装后仍然可用
+
+## 指令示例
+
+进行中（下载完成）：
+
+```text
+[[egg-install-status|install_id=eggins_20370001|status=running|step=downloaded|summary=%E5%B7%B2%E4%B8%8B%E8%BD%BD%E5%B9%B6%E9%AA%8C%E8%AF%81%E5%AE%89%E8%A3%85%E5%8C%85]]
+```
+
+进行中（安装落位完成）：
+
+```text
+[[egg-install-status|install_id=eggins_20370001|status=running|step=installed|summary=%E5%AE%89%E8%A3%85%E5%86%85%E5%AE%B9%E5%B7%B2%E8%90%BD%E4%BD%8D%EF%BC%8C%E6%A0%A1%E9%AA%8C%E4%B8%AD]]
+```
+
+成功：
+
+```text
+[[egg-install-status|install_id=eggins_20370001|status=success|step=completed|target_agent_id=2035123456789012345|summary=%E5%B7%B2%E5%AE%8C%E6%88%90%E5%AE%89%E8%A3%85]]
+```
+
+失败（用户取消）：
+
+```text
+[[egg-install-status|install_id=eggins_20370001|status=failed|step=user_cancelled|error_code=user_cancelled|summary=%E7%94%A8%E6%88%B7%E5%8F%96%E6%B6%88%E5%AE%89%E8%A3%85]]
+```
+
+失败（目标不存在）：
+
+```text
+[[egg-install-status|install_id=eggins_20370001|status=failed|step=target_not_found|error_code=target_not_found|error_msg=%E6%8C%87%E5%AE%9A%E7%9A%84%20Claude%20agent%20%E4%B8%8D%E5%AD%98%E5%9C%A8|summary=%E5%AE%89%E8%A3%85%E5%A4%B1%E8%B4%A5]]
+```
+
+失败（下载失败）：
+
+```text
+[[egg-install-status|install_id=eggins_20370001|status=failed|step=download_failed|error_code=download_failed|error_msg=%E4%B8%8B%E8%BD%BD%E5%AE%89%E8%A3%85%E5%8C%85%E5%A4%B1%E8%B4%A5|summary=%E5%AE%89%E8%A3%85%E5%A4%B1%E8%B4%A5]]
+```
+
+## 回复风格
+
+- 用正常对话回复用户
+- 进度回报要短、明确、可执行
+- 失败说明要具体
+- 最终总结必须包含目标 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