@dhf-openclaw/grix 0.4.9 → 0.4.10

package/skills/grix-group-governance/SKILL.md

@@ -0,0 +1,144 @@
+---
+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.
+---
+
+# 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`, `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`, `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
+
+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.
+
+### 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.
+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.
+
+## References
+
+1. Load [references/api-contract.md](references/api-contract.md) when you need exact tool mapping, payload examples, and scope matrix.

package/skills/grix-group-governance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Grix Group Governance"
+  short_description: "Use the typed grix_group tool for Grix group operations."
+  default_prompt: "Use this skill when users ask to create, inspect, update, or dissolve Grix groups. Validate parameters, call grix_group exactly once per action, and return clear remediation for scope/auth/parameter failures."

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

@@ -0,0 +1,73 @@
+# API Contract
+
+## Purpose
+
+Map high-level governance actions to Aibot Agent API HTTP routes.
+
+## Base Rules
+
+1. Base path: `/v1/agent-api`
+2. Auth: `Authorization: Bearer <agent_api_key>`
+3. Only `provider_type=3` and `status=active` agent can access.
+4. Scope middleware executes before service business checks.
+
+## Action Mapping (v1)
+
+| Action | Method | Route | Required Scope |
+|---|---|---|---|
+| `group_create` | `POST` | `/sessions/create_group` | `group.create` |
+| `group_member_add` | `POST` | `/sessions/members/add` | `group.member.add` |
+
+## OpenClaw Tool Mapping
+
+Use the native `grix_group` tool with typed fields:
+
+| Tool action | HTTP action | Required fields |
+|---|---|---|
+| `create` | `group_create` | `name` |
+| `detail` | `group_detail_read` | `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` |
+| `update_all_members_muted` | `group_all_members_muted_update` | `sessionId`, `allMembersMuted` |
+| `update_member_speaking` | `group_member_speaking_update` | `sessionId`, `memberId`, `isSpeakMuted` or `canSpeakWhenAllMuted` |
+| `dissolve` | `group_dissolve` | `sessionId` |
+
+## Payload Templates
+
+### create
+
+```json
+{
+  "action": "create",
+  "name": "项目协作群",
+  "memberIds": ["1002", "9991"],
+  "memberTypes": [1, 2]
+}
+```
+
+### add_members
+
+```json
+{
+  "action": "add_members",
+  "sessionId": "task_room_9083",
+  "memberIds": ["1003"],
+  "memberTypes": [1]
+}
+```
+
+## Error Matrix
+
+| HTTP/BizCode | Meaning | Skill Response |
+|---|---|---|
+| `403/20011` | agent scope forbidden | Tell owner to grant corresponding scope |
+| `400/10003` | invalid request payload | Ask for missing or corrected parameters |
+| `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 |
+
+## Retry Policy
+
+1. Never auto-retry `group_create` unless user confirms.
+2. Allow one retry for transient network failure only.
+3. Do not retry auth/scope/parameter failures automatically.

package/skills/grix-query/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: grix-query
+description: Use the typed `grix_query` tool for Grix contact search, session search, and session message history lookup. Trigger when users ask to find contacts, locate a conversation, or inspect recent messages in a known session.
+---
+
+# Grix Query
+
+Use the `grix_query` tool for read-only Grix lookup actions.  
+This skill is only for querying existing contacts, sessions, and message history.
+
+## Workflow
+
+1. Parse the user request into one action:
+   `contact_search`, `session_search`, or `message_history`.
+2. Validate required fields before any tool call.
+3. Call `grix_query` exactly once per business action.
+4. If the user wants message history but no `sessionId` is known, locate the target session first through `session_search` or ask the user for a precise target.
+5. Return exact remediation for scope, auth, and parameter failures.
+
+## Tool Contract
+
+For Grix query actions, always call:
+
+1. Tool: `grix_query`
+2. `action`: one of `contact_search`, `session_search`, or `message_history`
+3. `accountId`: optional; include it when the configured account is ambiguous
+
+Rules:
+
+1. Pass query parameters with their exact typed field names.
+2. Use `id` for `contact_search` and `session_search`.
+3. Use `sessionId`, `beforeId`, and `limit` explicitly for message history.
+4. Never invent a `sessionId`. Resolve it from context, from a previous tool result, or ask the user.
+5. Keep one tool call per action for audit clarity.
+
+## Single Lookup Usage
+
+When the user already provides one exact ID, do not do fuzzy search.  
+Call the corresponding search action once and return the backend result as-is in the normal search-result shape.
+
+1. Single contact lookup:
+   use `action: "contact_search"` and pass `id`
+2. Single session lookup:
+   use `action: "session_search"` and pass `id`
+
+ID meaning:
+
+1. `contact_search.id`:
+   contact or Agent numeric ID, for example `1002` or `9992`
+2. `session_search.id`:
+   exact session ID string, for example `task_room_9083`
+
+Examples:
+
+```json
+{
+  "action": "contact_search",
+  "id": "1002"
+}
+```
+
+```json
+{
+  "action": "session_search",
+  "id": "task_room_9083"
+}
+```
+
+## Action Contracts
+
+### contact_search
+
+Purpose: search the owner's Grix contact directory.
+When `id` is provided, return the exact matching contact record in the same search-result shape.
+
+Required input:
+
+1. `id` (contact ID, numeric string)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the target contact ID is already known and you need the exact contact entry.
+2. Do not jump directly to session history from a vague contact hint; resolve the contact or session first.
+3. `id` must be the current contact's numeric ID, not username, nickname, remark name, or session ID.
+
+### session_search
+
+Purpose: search the owner's visible sessions by final display title.
+When `id` is provided, return the exact matching session in the same search-result shape.
+
+Required input:
+
+1. `id` (session ID)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the target session ID is already known and you need the exact session entry.
+2. If multiple sessions match, present the candidates and let the user choose before reading history.
+3. `id` must be the exact current `session_id`, not group name, title text, or contact ID.
+
+### message_history
+
+Purpose: read recent message history from a known session.
+
+Required input:
+
+1. `sessionId`
+
+Optional input:
+
+1. `beforeId`
+2. `limit`
+
+Guardrails:
+
+1. Only call this after the target session is unambiguous.
+2. Use `beforeId` only for older-page pagination.
+3. Do not claim to have full history if only one page was fetched.
+
+## Error Handling Rules
+
+1. `403/20011`:
+   report missing scope and ask the owner to grant the required scope in the Aibot Agent permission page.
+2. `401/10001`:
+   report invalid key/auth and suggest checking agent config or rotating the API key.
+3. `403/10002`:
+   report the agent is not active or has an invalid provider type.
+4. `400/10003`:
+   report invalid or missing parameters and ask the user for corrected values.
+5. `404/4004`:
+   report the target session does not exist or is not visible.
+6. Other errors:
+   return the backend `msg` and stop automatic retries.
+
+## Response Style
+
+1. State the query result first.
+2. Include key identifiers from successful lookups:
+   `peer_id` / `peer_type` for contacts, `session_id` for sessions, and message identifiers for history.
+3. If history results may be partial, state that clearly.
+4. Never hide scope or auth errors behind generic wording.

package/skills/grix-query/agents/openai.yaml

@@ -0,0 +1,4 @@
+version: 1
+agent:
+  name: grix-query
+  default_prompt: "Use this skill when users ask to find Grix contacts, locate sessions, or inspect a known session's message history. Validate required parameters, call grix_query exactly once per action, and do not fabricate a sessionId."