grix-connector 4.2.3 → 4.2.4

package/openclaw-plugin/skills/grix-admin/SKILL.md

@@ -1,164 +1,130 @@
 ---
 name: grix-admin
-description: Responsible for OpenClaw local configuration, binding, and runtime convergence; can create new remote API agents through the current agent's WS channel, and supports querying, creating, modifying agent categories and assigning categories to agents.
+description: Grix agent administration for OpenClaw — create remote API agents, manage agent categories, and rotate API keys through `grix_admin`, and bind an agent's remote parameters into the local OpenClaw configuration with validation and routing verification. Trigger when the user asks to create a new agent, bind an agent into this OpenClaw host, or manage agent categories.
 ---
 
-# Grix Agent Admin
-
-`grix-admin` is responsible for three things:
-
-1. Landing existing remote agent parameters into local OpenClaw and handling runtime convergence after binding.
-2. When the current main agent is already online and has the corresponding scope, creating new remote API agents through `grix_admin`'s direct actions, then continuing with local landing.
-3. During agent creation or subsequent agent management, reusing `grix_admin`'s direct actions to query categories, create categories, modify categories, and assign categories to agents.
-
-## Entry Method
-
-1. In most cases, enter this skill from `grix_admin`'s `task` entry; the first line of `task` must clearly state `bind-local`, `create-and-bind`, or `category-manage`.
-2. Only when executing remote API agent creation or category operations within this skill should you directly call `grix_admin` once, without passing `task` again.
-3. In new flows, always explicitly pass `action` when directly calling `grix_admin`:
-   - `create_agent`
-   - `list_categories`
-   - `create_category`
-   - `update_category`
-   - `assign_category`
-4. The legacy direct call format for `create_agent` is still compatible, but should not be used in new flows.
-
-## Agent Creation Intake
-
-Before any `create_agent` API call:
-
-1. Ensure both `agentName` and `introduction` are present and specific. Never create an Agent with an empty, generic, or placeholder introduction.
-2. If either the Agent name or a usable introduction is missing or too vague, pause before calling the tool and ask one concise question: “这个 Agent 主要做什么？核心职责、服务对象和工作边界是什么？”
-3. Convert the user's answer into:
-   - A concise, professional `agentName` that reflects the Agent's role.
-   - A professional `introduction` that states its purpose, core responsibilities, intended users or scenarios, operating expectations, and important boundaries.
-4. Preserve the user's facts and intent. Do not invent permissions, business authority, expertise, or responsibilities that the user did not grant.
-5. Treat `introduction` as the Agent's behavioral specification, not promotional copy.
-6. Pass the finalized professional text in the actual `introduction` field of `action=create_agent`.
-
-## Direct Action List
-
-1. `action=create_agent`
-   - Required by this skill: `agentName`, `introduction`
-   - Optional: `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder`
-   - `categoryId` and `categoryName` cannot be provided simultaneously
-   - When `categoryName` is given, it first checks for duplicates under `parentCategoryId`; if not found, creates and assigns
-2. `action=list_categories`
-   - Required: none
-3. `action=create_category`
-   - Required: `name`, `parentId`
-   - Optional: `sortOrder`
-4. `action=update_category`
-   - Required: `categoryId`, `name`, `parentId`
-   - Optional: `sortOrder`
-5. `action=assign_category`
-   - Required: `agentId`, `categoryId`
-   - `categoryId=0` means clear the category
-
-## Mode A: bind-local (OpenClaw Local Binding)
-
-Input fields (written in `grix_admin.task`):
-
-1. First line must be `bind-local`
-2. `agent_name` (required)
-3. `agent_id` (required)
-4. `api_endpoint` (required)
-5. `api_key` (required)
-
-Execution rules:
-
-1. Do not perform remote creation; execute local binding directly. Do not call scripts that directly modify `openclaw.json`.
-2. Prepare local directories:
-   - `workspace=~/.openclaw/workspace-<agent_name>`
-   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
-   - Persona files belong only in the workspace root; add minimal `IDENTITY.md`, `SOUL.md`, and `AGENTS.md` if required files are missing.
-3. Read the current account, agent, tool profile, tool allowlist, session visibility, and binding configuration.
-4. Resolve `model` by reusing the existing agent model, then `agents.defaults.model.primary`; if neither exists, report the missing model and stop.
-5. Merge the account and agent entries, bind the agent to `grix:<agent_name>`, set the coding tool profile and required Grix tools, and restore `channels.grix.enabled=true` only if it is explicitly disabled.
-6. Use official OpenClaw CLI commands item by item; do not overwrite the entire config.
-7. Perform static validation:
+# Grix Agent Admin (OpenClaw)
+
+Three workflows:
+
+| Workflow | What it does |
+|---|---|
+| [`bind-local`](#workflow-a--bind-local) | Bind an existing remote agent's parameters into local OpenClaw, validate, verify routing |
+| [`create-and-bind`](#workflow-b--create-and-bind) | Create a remote agent via `grix_admin`, then run `bind-local` |
+| [`category-manage`](#workflow-c--category-manage) | List / create / update / assign categories via `grix_admin` |
+
+## Two ways `grix_admin` is called
+
+1. **Delegated workflow** — the caller passes only `task`, whose first line
+   names the workflow (`bind-local`, `create-and-bind`, `category-manage`)
+   followed by `key=value` lines. `grix-register` hands off this way. You then
+   run the workflow described below.
+2. **Direct action** — pass `action` plus its fields (table below). Use this
+   for every remote call *inside* a workflow. `task` and `action` cannot be
+   combined in one call.
+
+All remote operations go through `grix_admin` on the current account's WS
+channel — never hand-written HTTP or scripts, never across accounts, and
+never ask the user for a website account or password.
+
+## `grix_admin` direct actions
+
+| `action` | Required | Optional |
+|---|---|---|
+| `create_agent` | `agentName`, `introduction` | `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder` |
+| `list_categories` | — | — |
+| `create_category` | `name`, `parentId` | `sortOrder` |
+| `update_category` | `categoryId`, `name`, `parentId` | `sortOrder` |
+| `assign_category` | `agentId`, `categoryId` (`0` clears) | — |
+| `rotate_api_key` | `agentId` | — |
+
+Notes:
+
+- `categoryId` and `categoryName` are mutually exclusive — report the conflict
+  and stop if both are given.
+- With `categoryName`, the backend looks for an exact match under
+  `parentCategoryId`, creating it if absent. If several exact matches exist,
+  stop and ask the owner for an explicit `categoryId`.
+- `isMain=true` only when actually creating a new main API agent.
+- `code=4003` means a missing scope — report the exact `agent.api.create` or
+  `agent.category.*` scope.
+
+## Agent creation intake (before any `create_agent`)
+
+1. `agentName` and `introduction` must both be present and specific. Never
+   create an agent with an empty, generic, or placeholder introduction.
+2. If either is missing or vague, ask one concise question in the user's
+   language: what does this agent mainly do — core responsibilities, whom it
+   serves, and its boundaries?
+3. Turn the answer into a concise professional `agentName` and an
+   `introduction` that states purpose, core responsibilities, intended users or
+   scenarios, operating expectations, and boundaries. Treat `introduction` as
+   the agent's behavioral specification, not marketing copy.
+4. Preserve the user's facts and intent; do not invent permissions, authority,
+   or expertise they did not grant.
+
+## Workflow A — `bind-local`
+
+Inputs: `agent_name`, `agent_id`, `api_endpoint`, `api_key` (all required).
+Missing field → say which and stop. Do not create anything remotely, and do
+not call back to `grix-register`.
+
+1. Prepare local directories: `workspace=~/.openclaw/workspace-<agent_name>`
+   and `agentDir=~/.openclaw/agents/<agent_name>/agent`. Persona files live
+   only in the workspace root; add minimal `IDENTITY.md`, `SOUL.md`, and
+   `AGENTS.md` if missing.
+2. Read the current account, agent, tool profile, tool allowlist, session
+   visibility, and binding configuration.
+3. Resolve `model`: reuse the existing agent model, else
+   `agents.defaults.model.primary`; if neither exists, report the missing
+   model and stop.
+4. Merge the account and agent entries, bind the agent to
+   `grix:<agent_name>`, set the coding tool profile and required Grix tools,
+   and restore `channels.grix.enabled=true` only if it was explicitly
+   disabled. Apply each change with the official OpenClaw CLI item by item —
+   never overwrite or hand-edit `openclaw.json`.
+5. Static validation:
    - `openclaw config validate`
    - `openclaw config get --json channels.grix.accounts.<agent_name>`
    - `openclaw config get --json agents.list`
    - `openclaw agents bindings --agent <agent_name> --json`
-8. If real routing verification is available, perform it immediately. Falling back to the main agent, default assistant behavior, an old persona, or an ID mismatch means the runtime has not switched.
-9. Only when static validation passes but real routing verification fails may one `openclaw gateway restart` be used as targeted remediation; then repeat the same verification once.
-10. If real verification is unavailable, state “config has been written, runtime not yet tested, needs subsequent upper-level flow to continue verification”.
-
-## Mode B: create-and-bind (Create Remote Agent Then Bind Locally)
-
-Fields written in `grix_admin.task`:
-
-1. First line must be `create-and-bind`
-2. `agentName` (required)
-3. `introduction` (required; professionally organized according to **Agent Creation Intake**)
-4. `isMain` (optional, default `false`)
-5. `categoryId` (optional)
-6. `categoryName` (optional)
-7. `parentCategoryId` (optional, default `0`)
-8. `categorySortOrder` (optional)
-
-Execution rules:
-
-1. Confirm the current session is bound to a valid Grix account; cross-account execution is prohibited.
-2. If both `categoryId` and `categoryName` are provided, report an error and stop.
-3. Call `grix_admin` once with `action=create_agent`, passing `agentName`, `introduction`, and the supplied optional fields.
-4. Read `createdAgent.id`, `createdAgent.agent_name`, `createdAgent.api_endpoint`, and `createdAgent.api_key` from the result.
-5. If category assignment was requested but not completed by the return result, supplement it through the appropriate direct category actions.
-6. In the `categoryName` flow, if multiple exact matches exist under the same parent, stop and ask the owner to use an explicit `categoryId`.
-7. Continue immediately with `bind-local` using the returned parameters.
-8. `isMain=true` should only be used when actually creating a new main API agent.
-9. Do not claim completion until static validation and any available real routing verification pass.
-
-## Mode C: category-manage (Category Management)
-
-Fields written in `grix_admin.task`:
-
-1. First line must be `category-manage`
-2. `operation` (required): `list`, `create`, `update`, or `assign`
-3. `name` (`create` / `update` required)
-4. `parentId` (`create` / `update` required)
-5. `sortOrder` (`create` / `update` optional)
-6. `categoryId` (`update` / `assign` required; `0` clears an assignment)
-7. `agentId` (`assign` required)
-
-Execution rules:
-
-1. Strictly bind all operations to the current session account; cross-account execution is prohibited.
-2. Complete all remote steps through `grix_admin` direct actions; do not hand-write HTTP or temporary scripts.
-3. Map operations directly: `list_categories`, `create_category`, `update_category`, or `assign_category`.
-4. If the task also creates a new agent, use `create-and-bind` instead.
-
-## Remote Creation Fallback
-
-If the task has neither existing agent parameters nor an online main channel with `agent.api.create`, stop and ask the owner to create the remote agent through the backend admin path. After obtaining the parameters, proceed with `bind-local`.
-
-## Guardrails
-
-1. Never ask for a website account or password.
-2. `bind-local` must not call back to `grix-register`.
-3. All remote creation and category actions must go through `grix_admin` direct actions via the current account's WS channel.
-4. Never repeatedly echo the complete `api_key` in plaintext.
-5. Do not manually modify `openclaw.json`; use official OpenClaw CLI commands.
-6. Do not claim full convergence until static validation and any available real routing verification pass.
-7. Use at most one targeted gateway restart, only under the failure conditions defined by `bind-local`.
-
-## Error Handling
-
-1. For missing fields, clearly state which field is missing and stop.
-2. If `agentName` or a usable `introduction` is missing, ask for the Agent's purpose, responsibilities, intended users, and boundaries before remote creation.
-3. If both `categoryId` and `categoryName` are supplied, report the conflict and stop.
-4. For `code=4003`, report the exact missing `agent.api.create` or `agent.category.*` scope.
-5. Report the exact failed OpenClaw CLI command and validation result.
-6. If one permitted restart and retest still fail, report the flow as failed or partially complete.
-
-## Response Style
-
-1. Clearly state whether the execution is `bind-local`, `create-and-bind`, or `category-manage`.
-2. Report remote creation, category handling, local config writing, and validation as separate phases when applicable.
-3. Clearly distinguish static configuration success from verified runtime convergence.
-4. If a later phase fails after remote creation, report the overall result as partially complete.
-
-## References
-
-1. [references/api-contract.md](references/api-contract.md)
+6. If real routing verification is available, run it now. Falling back to the
+   main agent, default assistant behavior, an old persona, or an ID mismatch
+   means the runtime has not switched.
+7. Only when static validation passes but routing verification fails, run
+   **one** `openclaw gateway restart` and repeat the verification once.
+
+Reporting: distinguish "config written and statically valid" from "runtime
+verified". If verification cannot be run, say "config has been written,
+runtime not yet tested, needs the upper-level flow to continue verification".
+Never echo the full `api_key` in plaintext.
+
+## Workflow B — `create-and-bind`
+
+Inputs: `agentName`, `introduction` (required; run the intake above);
+`isMain`, `categoryId` | `categoryName`, `parentCategoryId` (default `0`),
+`categorySortOrder` (optional).
+
+1. Call `grix_admin` once with `action=create_agent` and the supplied fields.
+2. Read `createdAgent.id`, `agent_name`, `api_endpoint`, `api_key` from the
+   result. If a requested category was not applied, finish it with the
+   category actions.
+3. Continue immediately with Workflow A using those values.
+4. Report remote creation and local binding as separate phases; if binding
+   fails after creation succeeded, report the overall result as partial.
+
+Fallback: if no agent parameters exist and the current account lacks
+`agent.api.create`, stop and ask the owner to create the agent in the backend
+admin, then run Workflow A with the parameters they provide.
+
+## Workflow C — `category-manage`
+
+Inputs: `operation` (`list` | `create` | `update` | `assign`) plus the fields
+required by the matching action above. Map directly to `list_categories`,
+`create_category`, `update_category`, `assign_category`. If the request also
+creates an agent, use Workflow B instead.
+
+## Reference
+
+[references/api-contract.md](references/api-contract.md) — request/response
+shapes for each action and the local binding checklist.

package/openclaw-plugin/skills/grix-group/SKILL.md

@@ -3,162 +3,55 @@ 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
-
-Operate group-governance actions through the `grix_group` tool.  
-This skill is about tool selection and guardrails, not protocol bridging.
-
-## Workflow
-
-1. Parse the user request into one action:
-   `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.
-5. Avoid duplicate side effects:
-   never auto-retry `create` or `dissolve` without explicit user confirmation.
-
-## Tool Contract
-
-For Grix group governance, always call:
-
-1. Tool: `grix_group`
-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:
-
-1. Pass business parameters with their exact typed field names.
-2. Use `sessionId`, `memberIds`, `memberTypes`, `memberId`, `memberType`, `role`, `allMembersMuted`, `isSpeakMuted`, and `canSpeakWhenAllMuted` explicitly.
-3. Do not invent aliases or fallback fields.
-4. Keep one tool call per action for audit clarity.
-
-## Action Contracts
-
-### create
-
-Purpose: create a new group session.
-
-Required input:
-
-1. `name` (non-empty string)
-2. `memberIds` (optional string array; each item numeric text)
-3. `memberTypes` (optional int array; align with `memberIds`)
-
-Guardrails:
-
-1. Ask for clarification if group name is missing.
-2. Ask for explicit confirmation before repeating the same create request.
-3. Treat this action as non-idempotent.
-
-### add_members
-
-Purpose: add members into an existing group.
-
-Required input:
-
-1. `sessionId` (non-empty string)
-2. `memberIds` (non-empty string array; each item numeric text)
-3. `memberTypes` (optional int array; align with `memberIds`)
-
-Guardrails:
-
-1. Reject empty `sessionId` before calling the tool.
-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. Only execute this when the requester is clearly the current Agent owner, or an already-established authorized operator in the current context.
-2. If the requester identity is unclear, ask for confirmation first; if it is clearly unauthorized, reject directly and do not call `grix_group`.
-3. This action is only for the current Agent leaving its own group membership.
-4. Never translate a request to remove other members into `leave`; use `remove_members` for that.
-5. Do not send `memberId`, `memberIds`, or `memberTypes` with this action.
-6. This action does not require scope and should not be described as a scope-grant workflow.
-7. Execute `leave` silently: do not send any pre-leave or farewell message to the group before leaving.
-
-### remove_members
-
-Required input:
-
-1. `sessionId`
-2. `memberIds`
-
-### update_member_role
-
-Required input:
-
-1. `sessionId`
-2. `memberId`
-3. `role`
-
-Guardrails:
-
-1. Only use `memberType=1` for role updates.
-2. Never guess a role value; confirm when unclear.
-
-### update_all_members_muted
-
-Required input:
-
-1. `sessionId`
-2. `allMembersMuted`
-
-Guardrails:
-
-1. Only use this for group-wide mute state changes.
-2. Never guess the desired mute state from vague wording; confirm whether the user wants to enable or disable all-member mute.
-
-### update_member_speaking
-
-Required input:
-
-1. `sessionId`
-2. `memberId`
-3. At least one of `isSpeakMuted` or `canSpeakWhenAllMuted`
-
-Guardrails:
-
-1. Only use `memberType=1` or `memberType=2`.
-2. Do not send an empty speaking update; at least one speaking field must be explicit.
-3. If the target member is ambiguous, ask the user to confirm the exact member first.
-
-### detail / dissolve
-
-Required input:
-
-1. `sessionId`
-
-## Error Handling Rules
-
-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`:
-   report agent is not active or invalid provider type.
-4. `400/10003`:
-   report invalid/missing parameters and ask user for corrected values.
-5. Other errors:
-   return backend `msg` and stop automatic retries.
-
-## Response Style
-
-1. State action result first.
-2. Include key identifiers (`session_id`, member count, mute state) when successful.
-3. Include exact remediation when failed.
-4. Never hide scope or auth errors behind generic wording.
-5. For `leave`, report result to the requester only; do not post extra messages into the group session.
-
-## References
-
-1. Load [references/api-contract.md](references/api-contract.md) when you need exact tool mapping, payload examples, and scope matrix.
+# Grix Group
+
+Use `grix_group` for group lifecycle and membership management. The Grix
+account is resolved from the current agent context; you do not pass it.
+
+## Tool contract
+
+Call `grix_group` with one `action`; use the exact typed field names below.
+
+| `action` | Required | Optional |
+|---|---|---|
+| `create` | `name` | `memberIds` (numeric strings) + `memberTypes` (1=user, 2=agent), aligned by index |
+| `detail` | `sessionId` | — |
+| `leave` | `sessionId` | — (never send member fields) |
+| `dissolve` | `sessionId` | — |
+| `add_members` / `remove_members` | `sessionId`, `memberIds` | `memberTypes`, aligned by index |
+| `update_member_role` | `sessionId`, `memberId`, `role` (1=admin, 2=member) | — (`memberType` is always 1) |
+| `update_all_members_muted` | `sessionId`, `allMembersMuted` | — |
+| `update_member_speaking` | `sessionId`, `memberId`, at least one of `isSpeakMuted` / `canSpeakWhenAllMuted` | `memberType` (1 or 2) |
+
+## Rules
+
+1. Validate required fields before calling; reject non-numeric `memberIds`
+   and empty `sessionId` yourself. Resolve an unknown or ambiguous group with
+   `grix_query` (`session_search`) and confirm with the user first.
+2. One call per business action. `create` and `dissolve` are not idempotent —
+   never auto-retry them; ask for explicit confirmation before repeating.
+3. Never guess a role or mute state from vague wording; confirm whether the
+   user wants it enabled or disabled.
+4. `leave` removes only the current agent from the group. Execute it only
+   for the owner or an already-established authorized operator; if identity
+   is unclear, confirm first. Leave silently — no farewell message — and
+   report the result only to the requester. To remove someone else use
+   `remove_members`. `leave` needs no scope, so never answer a `leave`
+   failure with scope-grant guidance.
+5. On errors, report the exact failure and fix; do not retry blindly:
+   - `403/20011` — missing scope (usually not an admin of that group); ask the
+     owner to grant it in the agent permission page.
+   - `401/10001` — invalid key/auth; check agent config or rotate the key.
+   - `403/10002` — agent not active or invalid provider type.
+   - `400/10003` — invalid or missing parameters.
+
+## Response style
+
+State the result first with key identifiers (`session_id`, member count,
+mute state); on failure give the exact remediation and never hide scope or
+auth errors behind generic wording.
+
+## Reference
+
+[references/api-contract.md](references/api-contract.md) — exact tool
+mapping, payload examples, and scope matrix.