grix-connector 3.1.13 → 3.1.14

package/dist/default-skills/grix-agent-dispatch/SKILL.md

@@ -1,89 +1,89 @@
----
-name: grix-agent-dispatch
-description: Dispatch one of the owner's other agents to do work in a given directory (`grix_dispatch_agent`), and update an agent's text introduction (`grix_agent_update`). Trigger when the user asks to hand a task to another agent, run work in a specific directory via a sibling agent, or change an agent's introduction.
-trigger: 当用户要把任务派发给 owner 名下的另一个 Agent、让某个 Agent 在指定目录干活、或修改某个 Agent 的简介时
----
-
-# Grix Agent Dispatch
-
-Manage and delegate to the owner's other agents.
-
-## Dispatch a task — `grix_dispatch_agent`
-
-Hand work to another of the owner's agents. The backend opens (or reuses) a
-private session between the owner and that agent, binds the working directory
-when the agent type requires it (claude/codex/etc.), and sends the task in **as
-the owner** so the agent starts working.
-
-- `agent_id` (required) — target agent's numeric ID, as a string.
-- `cwd` (required) — absolute working directory for the task.
-- `task` (required) — what to do, **written in the owner's first-person voice
-  and tone**. The task is delivered into the session as the owner, so the target
-  agent sees it as the owner speaking directly to it. Phrase it the way the owner
-  would talk to the agent (e.g. "帮我把…改好", "你去 X 目录跑一下测试"), not as a
-  third-person relay ("请帮 owner 完成…") and not as yourself narrating on the
-  owner's behalf.
-
-## After dispatching — monitor and report back (don't fire-and-forget)
-
-Dispatching is only step one. After `grix_dispatch_agent` succeeds, **do not end
-your turn there**. Stay and watch the dispatched session until it reaches a
-terminal state, then report the actual result back to the user.
-
-1. **Capture the session.** Take the target session id from the dispatch result.
-   If it isn't clearly present, list sessions with `grix_chat_state_query` (each
-   entry carries its `task_title`) and match the one you just created.
-
-2. **Poll the state.** Call `grix_chat_state_query` with that `session_id` on a
-   calm cadence — wait ~15–30s between polls, never spin in a tight loop. Each
-   entry has one mutually-exclusive `state`; act on it:
-   - `running` — still working. Keep polling.
-   - `completed` — done. Go to step 3.
-   - `failed` — errored. Fetch recent messages (step 3) to capture the error,
-     then report the failure.
-   - `waiting_approval` / `waiting_question` — the agent is blocked on the owner
-     (approve/deny, or answer a question) and will **not** progress on its own.
-     Fetch the latest message to see what it's asking, surface that to the user,
-     and stop polling — the user has to act.
-   - `idle` — no active task / stopped. If it never hit `completed`, fetch recent
-     messages to see what happened, then report.
-
-3. **Read the answer.** Once the state is terminal, pull the agent's final reply
-   with `grix_query` (`action: "message_history"`, `sessionId: <session>`). Read
-   the latest agent message(s) and summarize the outcome — don't dump raw logs.
-
-4. **Reply the result.** Send the conclusion back to the user: what the
-   dispatched agent did and how it turned out.
-
-### Long-running tasks
-- If `running` persists past a few minutes (≈3 min), send a short interim
-  progress note to the user so they know it's still working, then keep polling.
-  Repeat at sensible intervals so the user is never left in the dark.
-- A single turn can't run forever. If the task is still `running` when you've
-  watched for a long stretch (≈20 min) and must wrap up, do **not** promise to
-  notify the user later — you cannot send anything after the turn ends. Report
-  the current state plainly and tell them how to re-check (ping you again to
-  resume monitoring; the dispatched session keeps running on its own).
-
-## Update an introduction — `grix_agent_update`
-
-Change the text introduction of one of the owner's agents.
-
-- `agent_id` (required) — target agent's numeric ID, as a string.
-- `introduction` (required) — new introduction text (max 300 chars).
-
-## Rules
-
-1. You need the exact numeric `agent_id`. Resolve it with `grix_query` first if
-   you only have a name; never guess an ID.
-2. `cwd` must be an absolute path the target agent can access.
-3. Dispatch runs the task as the owner in a separate session — confirm the
-   target agent and directory with the user when the task is consequential.
-4. The `task` is delivered AS THE OWNER, so always write it in the owner's
-   first-person voice and tone — never as a third-person relay and never in your
-   own narrating voice.
-5. Dispatch is **not** fire-and-forget. After dispatching, monitor the session
-   state (`grix_chat_state_query`), read the final answer when it completes
-   (`grix_query` message_history), and report the result. Never promise a future
-   notification you cannot send — if you must stop while it's still running, say
-   so plainly and give the user a way to re-check.
+---
+name: grix-agent-dispatch
+description: Dispatch one of the owner's other agents to do work in a given directory (`grix_dispatch_agent`), and update an agent's text introduction (`grix_agent_update`). Trigger when the user asks to hand a task to another agent, run work in a specific directory via a sibling agent, or change an agent's introduction.
+trigger: 当用户要把任务派发给 owner 名下的另一个 Agent、让某个 Agent 在指定目录干活、或修改某个 Agent 的简介时
+---
+
+# Grix Agent Dispatch
+
+Manage and delegate to the owner's other agents.
+
+## Dispatch a task — `grix_dispatch_agent`
+
+Hand work to another of the owner's agents. The backend opens (or reuses) a
+private session between the owner and that agent, binds the working directory
+when the agent type requires it (claude/codex/etc.), and sends the task in **as
+the owner** so the agent starts working.
+
+- `agent_id` (required) — target agent's numeric ID, as a string.
+- `cwd` (required) — absolute working directory for the task.
+- `task` (required) — what to do, **written in the owner's first-person voice
+  and tone**. The task is delivered into the session as the owner, so the target
+  agent sees it as the owner speaking directly to it. Phrase it the way the owner
+  would talk to the agent (e.g. "帮我把…改好", "你去 X 目录跑一下测试"), not as a
+  third-person relay ("请帮 owner 完成…") and not as yourself narrating on the
+  owner's behalf.
+
+## After dispatching — monitor and report back (don't fire-and-forget)
+
+Dispatching is only step one. After `grix_dispatch_agent` succeeds, **do not end
+your turn there**. Stay and watch the dispatched session until it reaches a
+terminal state, then report the actual result back to the user.
+
+1. **Capture the session.** Take the target session id from the dispatch result.
+   If it isn't clearly present, list sessions with `grix_chat_state_query` (each
+   entry carries its `task_title`) and match the one you just created.
+
+2. **Poll the state.** Call `grix_chat_state_query` with that `session_id` on a
+   calm cadence — wait ~15–30s between polls, never spin in a tight loop. Each
+   entry has one mutually-exclusive `state`; act on it:
+   - `running` — still working. Keep polling.
+   - `completed` — done. Go to step 3.
+   - `failed` — errored. Fetch recent messages (step 3) to capture the error,
+     then report the failure.
+   - `waiting_approval` / `waiting_question` — the agent is blocked on the owner
+     (approve/deny, or answer a question) and will **not** progress on its own.
+     Fetch the latest message to see what it's asking, surface that to the user,
+     and stop polling — the user has to act.
+   - `idle` — no active task / stopped. If it never hit `completed`, fetch recent
+     messages to see what happened, then report.
+
+3. **Read the answer.** Once the state is terminal, pull the agent's final reply
+   with `grix_query` (`action: "message_history"`, `sessionId: <session>`). Read
+   the latest agent message(s) and summarize the outcome — don't dump raw logs.
+
+4. **Reply the result.** Send the conclusion back to the user: what the
+   dispatched agent did and how it turned out.
+
+### Long-running tasks
+- If `running` persists past a few minutes (≈3 min), send a short interim
+  progress note to the user so they know it's still working, then keep polling.
+  Repeat at sensible intervals so the user is never left in the dark.
+- A single turn can't run forever. If the task is still `running` when you've
+  watched for a long stretch (≈20 min) and must wrap up, do **not** promise to
+  notify the user later — you cannot send anything after the turn ends. Report
+  the current state plainly and tell them how to re-check (ping you again to
+  resume monitoring; the dispatched session keeps running on its own).
+
+## Update an introduction — `grix_agent_update`
+
+Change the text introduction of one of the owner's agents.
+
+- `agent_id` (required) — target agent's numeric ID, as a string.
+- `introduction` (required) — new introduction text (max 300 chars).
+
+## Rules
+
+1. You need the exact numeric `agent_id`. Resolve it with `grix_query` first if
+   you only have a name; never guess an ID.
+2. `cwd` must be an absolute path the target agent can access.
+3. Dispatch runs the task as the owner in a separate session — confirm the
+   target agent and directory with the user when the task is consequential.
+4. The `task` is delivered AS THE OWNER, so always write it in the owner's
+   first-person voice and tone — never as a third-person relay and never in your
+   own narrating voice.
+5. Dispatch is **not** fire-and-forget. After dispatching, monitor the session
+   state (`grix_chat_state_query`), read the final answer when it completes
+   (`grix_query` message_history), and report the result. Never promise a future
+   notification you cannot send — if you must stop while it's still running, say
+   so plainly and give the user a way to re-check.

package/dist/default-skills/grix-chat-state/SKILL.md

@@ -1,56 +1,56 @@
----
-name: grix-chat-state
-description: Observe chat state — query the task state of all the owner's chats (`grix_chat_state_query`), and check the current MCP connection status (`grix_status`). Trigger when the user asks which chats are running/done/waiting, or to verify the Grix connection is healthy.
-trigger: 当用户问哪些聊天任务在跑/已完成/在等待审批,或要确认 Grix 连接是否正常时
----
-
-# Grix Chat State & Status
-
-Read-only observation of chat task state and connection state.
-
-## Chat task states — `grix_chat_state_query`
-
-Query the task state across all the owner's chats (direct and group sessions).
-Supports pagination and optional state filtering.
-
-Parameters:
-- `session_id` — query a single session; omit to return all sessions
-- `page` — page number, default 1
-- `page_size` — items per page, default 10, max 100
-- `state` — filter by state; omit to return all
-
-Returns one entry per session with a single mutually-exclusive state:
-
-- `running` — working
-- `waiting_approval` — blocked on the owner to approve/deny
-- `waiting_question` — asked the owner a question, awaiting reply
-- `completed` / `failed` — finished
-- `idle` — no task / stopped
-
-Also returns `task_title` for easy identification of each chat.
-
-Use it to see at a glance which chats are done, still running, or waiting on the
-owner.
-
-## Connection status — `grix_status`
-
-Query the Grix connection status of the current MCP session. Takes no
-parameters. Use it to confirm the agent is connected before relying on other
-grix tools.
-
-## Manually update a chat state — `grix_chat_state_update`
-
-Override the task state of a specific chat session. Useful when you need to
-mark a chat as done, failed, or idle outside of a normal task lifecycle.
-
-Parameters:
-- `session_id` — **(required)** the session to update
-- `state` — **(required)** one of: `running`, `waiting_approval`, `waiting_question`, `completed`, `failed`, `idle`
-- `reason` — **(optional)** reason for the change, written to `stop_reason`
-
-## Rules
-
-1. `grix_chat_state_query` is read-only — safe to call any time to orient yourself.
-2. `grix_chat_state_update` only updates existing records; it will error if the session has no prior state entry.
-3. `grix_chat_state_query` reports per-session state, not per-message; pair it with
-   `grix_query` (`message_history`) when you need the actual content.
+---
+name: grix-chat-state
+description: Observe chat state — query the task state of all the owner's chats (`grix_chat_state_query`), and check the current MCP connection status (`grix_status`). Trigger when the user asks which chats are running/done/waiting, or to verify the Grix connection is healthy.
+trigger: 当用户问哪些聊天任务在跑/已完成/在等待审批,或要确认 Grix 连接是否正常时
+---
+
+# Grix Chat State & Status
+
+Read-only observation of chat task state and connection state.
+
+## Chat task states — `grix_chat_state_query`
+
+Query the task state across all the owner's chats (direct and group sessions).
+Supports pagination and optional state filtering.
+
+Parameters:
+- `session_id` — query a single session; omit to return all sessions
+- `page` — page number, default 1
+- `page_size` — items per page, default 10, max 100
+- `state` — filter by state; omit to return all
+
+Returns one entry per session with a single mutually-exclusive state:
+
+- `running` — working
+- `waiting_approval` — blocked on the owner to approve/deny
+- `waiting_question` — asked the owner a question, awaiting reply
+- `completed` / `failed` — finished
+- `idle` — no task / stopped
+
+Also returns `task_title` for easy identification of each chat.
+
+Use it to see at a glance which chats are done, still running, or waiting on the
+owner.
+
+## Connection status — `grix_status`
+
+Query the Grix connection status of the current MCP session. Takes no
+parameters. Use it to confirm the agent is connected before relying on other
+grix tools.
+
+## Manually update a chat state — `grix_chat_state_update`
+
+Override the task state of a specific chat session. Useful when you need to
+mark a chat as done, failed, or idle outside of a normal task lifecycle.
+
+Parameters:
+- `session_id` — **(required)** the session to update
+- `state` — **(required)** one of: `running`, `waiting_approval`, `waiting_question`, `completed`, `failed`, `idle`
+- `reason` — **(optional)** reason for the change, written to `stop_reason`
+
+## Rules
+
+1. `grix_chat_state_query` is read-only — safe to call any time to orient yourself.
+2. `grix_chat_state_update` only updates existing records; it will error if the session has no prior state entry.
+3. `grix_chat_state_query` reports per-session state, not per-message; pair it with
+   `grix_query` (`message_history`) when you need the actual content.

package/dist/default-skills/grix-egg/SKILL.md

@@ -1,90 +1,90 @@
----
-name: grix-egg
-description: Install a Grix egg skill package into your own skill directory. Use when you receive an instruction containing a line like "技能包: <URL>" and are asked to install / incubate it as a skill for yourself.
-trigger: 当收到含「技能包: <URL>」的安装指令、要求把虾蛋技能包装进自己的技能目录时
----
-
-# Grix Egg — 技能包自装
-
-虾蛋（egg）孵化对你这类 agent 来说就是一件事：**把一个技能包装进你自己的技能目录**，让你之后能用上它。
-
-当你收到一条带有 `技能包: <URL>` 的安装指令时，就用本技能完成安装、自检，再回发一张安装状态卡片。整件事由你自己在本机完成——没有别的 agent 会替你装，主 agent 也碰不到你的技能目录。
-
-## 指令里会给你什么
-
-- `技能包: <URL>` —— 要安装的技能包下载地址（必有）。
-- `install_id: <ID>` —— 这次安装的编号，回发状态卡片时要原样带上（必有）。
-- `grix agent id: <ID>` —— 你自己的 grix agent id，回发状态卡片时作为 `target_agent_id`（可能有）。
-
-## 你要做的事
-
-1. 取出 `技能包:` 后面的下载 URL。
-2. 确定你自己的技能目录：就是**本 grix-egg 技能所在目录的上一级**。例如本技能在 `~/.codex/skills/grix-egg/`，技能目录就是 `~/.codex/skills/`；在 `~/.claude/skills/grix-egg/` 则是 `~/.claude/skills/`，以此类推。
-3. 下载技能包、解压。
-4. 把解压出来的每个技能（含 `SKILL.md` 的目录）整目录拷进你的技能目录。
-5. 确认技能目录里已经出现新技能的 `SKILL.md`。
-6. **回发安装状态卡片**（见下），让平台把这次安装收口成成功/失败。
-7. 再用一句自然语言告诉用户：装好了哪个/哪些技能。
-
-## 第 2~5 步：安装（用 shell 执行）
-
-把两处尖括号替换成真实值后执行。`SKILLS_DIR` 取本技能所在目录的上一级。
-
-```bash
-set -e
-URL="<技能包 URL>"
-SKILLS_DIR="<你的技能目录绝对路径>"
-
-TMP="$(mktemp -d)"
-curl -fsSL "$URL" -o "$TMP/skill.zip"
-mkdir -p "$TMP/unpacked"
-unzip -o -q "$TMP/skill.zip" -d "$TMP/unpacked"
-
-# 把每个含 SKILL.md 的技能目录整目录拷进技能目录
-found=0
-while IFS= read -r -d '' f; do
-  d="$(dirname "$f")"
-  cp -R "$d" "$SKILLS_DIR/"
-  found=1
-done < <(find "$TMP/unpacked" -name SKILL.md -print0)
-
-# 兜底：SKILL.md 直接在解压根目录（散文件），按 name 建一个技能目录放进去
-if [ "$found" -eq 0 ] && [ -f "$TMP/unpacked/SKILL.md" ]; then
-  name="$(grep -m1 '^name:' "$TMP/unpacked/SKILL.md" | sed 's/^name:[[:space:]]*//')"
-  [ -z "$name" ] && name="egg-skill"
-  mkdir -p "$SKILLS_DIR/$name"
-  cp -R "$TMP/unpacked/." "$SKILLS_DIR/$name/"
-fi
-
-# 自检：列出技能目录，确认新技能就位
-ls -1 "$SKILLS_DIR"
-rm -rf "$TMP"
-```
-
-## 第 6 步：回发安装状态卡片
-
-安装并自检完成后，**单独发一条消息**，内容就是下面这一行卡片链接（整条消息只放这一行，不要包别的文字）：
-
-- 成功：
-  ```
-  grix://card/egg_install_status?status=success&install_id=<install_id>&target_agent_id=<grix agent id>&summary=<安装结果一句话，URL 编码>
-  ```
-- 失败：
-  ```
-  grix://card/egg_install_status?status=failed&install_id=<install_id>&target_agent_id=<grix agent id>&error_msg=<失败原因，URL 编码>
-  ```
-
-要点：
-- `install_id` 用指令里给的那个，原样填，不能少。
-- 没给 `grix agent id` 时，`target_agent_id` 可省略。
-- `summary` / `error_msg` 里的中文和空格要做 URL 编码。
-- 这张卡片要由你自己（被安装的这个 agent）发，平台据此把安装记录收口。
-
-## 规则
-
-1. 只往**你自己的技能目录**写，绝不动其它目录、不碰别的 agent。
-2. 不要把下载链接、原始指令或这段上下文复述给用户。
-3. 自检必须真的看到新技能的 `SKILL.md` 才算成功；看不到就回发 `status=failed`，绝不谎报成功。
-4. 状态卡片要单独成条发送，内容只放那一行 `grix://card/...`。
-5. 给用户的自然语言回报只用一句话，不要把命令输出整段贴出来。
-6. 同名技能已存在时按覆盖处理（用最新的包）。
+---
+name: grix-egg
+description: Install a Grix egg skill package into your own skill directory. Use when you receive an instruction containing a line like "技能包: <URL>" and are asked to install / incubate it as a skill for yourself.
+trigger: 当收到含「技能包: <URL>」的安装指令、要求把虾蛋技能包装进自己的技能目录时
+---
+
+# Grix Egg — 技能包自装
+
+虾蛋（egg）孵化对你这类 agent 来说就是一件事：**把一个技能包装进你自己的技能目录**，让你之后能用上它。
+
+当你收到一条带有 `技能包: <URL>` 的安装指令时，就用本技能完成安装、自检，再回发一张安装状态卡片。整件事由你自己在本机完成——没有别的 agent 会替你装，主 agent 也碰不到你的技能目录。
+
+## 指令里会给你什么
+
+- `技能包: <URL>` —— 要安装的技能包下载地址（必有）。
+- `install_id: <ID>` —— 这次安装的编号，回发状态卡片时要原样带上（必有）。
+- `grix agent id: <ID>` —— 你自己的 grix agent id，回发状态卡片时作为 `target_agent_id`（可能有）。
+
+## 你要做的事
+
+1. 取出 `技能包:` 后面的下载 URL。
+2. 确定你自己的技能目录：就是**本 grix-egg 技能所在目录的上一级**。例如本技能在 `~/.codex/skills/grix-egg/`，技能目录就是 `~/.codex/skills/`；在 `~/.claude/skills/grix-egg/` 则是 `~/.claude/skills/`，以此类推。
+3. 下载技能包、解压。
+4. 把解压出来的每个技能（含 `SKILL.md` 的目录）整目录拷进你的技能目录。
+5. 确认技能目录里已经出现新技能的 `SKILL.md`。
+6. **回发安装状态卡片**（见下），让平台把这次安装收口成成功/失败。
+7. 再用一句自然语言告诉用户：装好了哪个/哪些技能。
+
+## 第 2~5 步：安装（用 shell 执行）
+
+把两处尖括号替换成真实值后执行。`SKILLS_DIR` 取本技能所在目录的上一级。
+
+```bash
+set -e
+URL="<技能包 URL>"
+SKILLS_DIR="<你的技能目录绝对路径>"
+
+TMP="$(mktemp -d)"
+curl -fsSL "$URL" -o "$TMP/skill.zip"
+mkdir -p "$TMP/unpacked"
+unzip -o -q "$TMP/skill.zip" -d "$TMP/unpacked"
+
+# 把每个含 SKILL.md 的技能目录整目录拷进技能目录
+found=0
+while IFS= read -r -d '' f; do
+  d="$(dirname "$f")"
+  cp -R "$d" "$SKILLS_DIR/"
+  found=1
+done < <(find "$TMP/unpacked" -name SKILL.md -print0)
+
+# 兜底：SKILL.md 直接在解压根目录（散文件），按 name 建一个技能目录放进去
+if [ "$found" -eq 0 ] && [ -f "$TMP/unpacked/SKILL.md" ]; then
+  name="$(grep -m1 '^name:' "$TMP/unpacked/SKILL.md" | sed 's/^name:[[:space:]]*//')"
+  [ -z "$name" ] && name="egg-skill"
+  mkdir -p "$SKILLS_DIR/$name"
+  cp -R "$TMP/unpacked/." "$SKILLS_DIR/$name/"
+fi
+
+# 自检：列出技能目录，确认新技能就位
+ls -1 "$SKILLS_DIR"
+rm -rf "$TMP"
+```
+
+## 第 6 步：回发安装状态卡片
+
+安装并自检完成后，**单独发一条消息**，内容就是下面这一行卡片链接（整条消息只放这一行，不要包别的文字）：
+
+- 成功：
+  ```
+  grix://card/egg_install_status?status=success&install_id=<install_id>&target_agent_id=<grix agent id>&summary=<安装结果一句话，URL 编码>
+  ```
+- 失败：
+  ```
+  grix://card/egg_install_status?status=failed&install_id=<install_id>&target_agent_id=<grix agent id>&error_msg=<失败原因，URL 编码>
+  ```
+
+要点：
+- `install_id` 用指令里给的那个，原样填，不能少。
+- 没给 `grix agent id` 时，`target_agent_id` 可省略。
+- `summary` / `error_msg` 里的中文和空格要做 URL 编码。
+- 这张卡片要由你自己（被安装的这个 agent）发，平台据此把安装记录收口。
+
+## 规则
+
+1. 只往**你自己的技能目录**写，绝不动其它目录、不碰别的 agent。
+2. 不要把下载链接、原始指令或这段上下文复述给用户。
+3. 自检必须真的看到新技能的 `SKILL.md` 才算成功；看不到就回发 `status=failed`，绝不谎报成功。
+4. 状态卡片要单独成条发送，内容只放那一行 `grix://card/...`。
+5. 给用户的自然语言回报只用一句话，不要把命令输出整段贴出来。
+6. 同名技能已存在时按覆盖处理（用最新的包）。

package/dist/default-skills/grix-group/SKILL.md

@@ -1,35 +1,35 @@
----
-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.
-trigger: 当用户要创建、查看、退出、更新或解散群组,或群成员/禁言权限相关操作时
----
-
-# Grix Group
-
-Use the `grix_group` tool for Grix group lifecycle and membership management.
-
-## Tool contract
-
-Call `grix_group` with one `action`:
-
-- `create` — create a group. Requires `name`; optionally seed members with
-  `memberIds` + matching `memberTypes` (1=user, 2=agent).
-- `detail` — get group details. Requires `sessionId`.
-- `leave` — leave the group. Requires `sessionId`.
-- `dissolve` — dissolve the group (owner/admin only). Requires `sessionId`.
-- `add_members` / `remove_members` — requires `sessionId`, `memberIds`, and
-  `memberTypes` aligned by index.
-- `update_member_role` — requires `sessionId`, `memberId`, `role` (1=admin,
-  2=member).
-- `update_all_members_muted` — requires `sessionId`, `allMembersMuted`.
-- `update_member_speaking` — requires `sessionId`, `memberId`, `isSpeakMuted`,
-  and optionally `canSpeakWhenAllMuted`.
-
-## Rules
-
-1. `memberIds` and `memberTypes` are parallel arrays — keep them the same length
-   and order.
-2. Any action except `create` needs the target group's `sessionId`; resolve it
-   with `grix_query` (`session_search`) first if unknown.
-3. Scope or permission errors usually mean the current agent is not an admin of
-   that group — surface the exact error and required role, don't retry blindly.
+---
+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.
+trigger: 当用户要创建、查看、退出、更新或解散群组,或群成员/禁言权限相关操作时
+---
+
+# Grix Group
+
+Use the `grix_group` tool for Grix group lifecycle and membership management.
+
+## Tool contract
+
+Call `grix_group` with one `action`:
+
+- `create` — create a group. Requires `name`; optionally seed members with
+  `memberIds` + matching `memberTypes` (1=user, 2=agent).
+- `detail` — get group details. Requires `sessionId`.
+- `leave` — leave the group. Requires `sessionId`.
+- `dissolve` — dissolve the group (owner/admin only). Requires `sessionId`.
+- `add_members` / `remove_members` — requires `sessionId`, `memberIds`, and
+  `memberTypes` aligned by index.
+- `update_member_role` — requires `sessionId`, `memberId`, `role` (1=admin,
+  2=member).
+- `update_all_members_muted` — requires `sessionId`, `allMembersMuted`.
+- `update_member_speaking` — requires `sessionId`, `memberId`, `isSpeakMuted`,
+  and optionally `canSpeakWhenAllMuted`.
+
+## Rules
+
+1. `memberIds` and `memberTypes` are parallel arrays — keep them the same length
+   and order.
+2. Any action except `create` needs the target group's `sessionId`; resolve it
+   with `grix_query` (`session_search`) first if unknown.
+3. Scope or permission errors usually mean the current agent is not an admin of
+   that group — surface the exact error and required role, don't retry blindly.