grix-connector 3.1.13 → 3.1.15

package/openclaw-plugin/skills/message-send/SKILL.md

@@ -1,197 +1,197 @@
----
-name: message-send
-description: Send messages. Supports current session replies and cross-session sending. For cross-session, use an exact `session_id` or an existing `route.sessionKey` as the `to` target; do not use the legacy `target=agent:...` format. Trigger words: send DM, DM, send message, notify.
----
-
-# Message Send Skill
-
-This skill is used to send messages through OpenClaw's `message` tool.
-
-## Two Sending Modes
-
-### 1. Current Session Reply
-
-If replying to the current Grix session, send directly without providing an additional target session.
-
-**Parameters**:
-- `action`: "send"
-- `channel`: "grix"
-- `accountId`: current account ID
-- `message`: message content
-
-**Example**:
-
-```json
-{
-  "action": "send",
-  "channel": "grix",
-  "accountId": "{accountId}",
-  "message": "Got it, processing now..."
-}
-```
-
-### 2. Cross-Session Sending
-
-If sending to another private chat or group chat, use `to` to point to the target session.
-
-**Parameters**:
-- `action`: "send"
-- `channel`: "grix"
-- `accountId`: current account ID
-- `to`: target session identifier
-- `message`: message content
-
-**Example**:
-
-```json
-{
-  "action": "send",
-  "channel": "grix",
-  "accountId": "{accountId}",
-  "to": "{targetSessionId}",
-  "message": "Need your confirmation on a development decision: ..."
-}
-```
-
-## Real Format of `to`
-
-The current plugin recognizes these two types of targets:
-
-1. Exact Grix `session_id` (recommended, usually a UUID)
-2. An existing `route.sessionKey` in the current runtime
-
-Recommended to pass the bare `session_id` directly:
-
-```text
-to=e72ce987-2d2e-40ed-bcc9-b336b4974512
-```
-
-In compatible formats, `grix:<session_id>` or `session:<session_id>` can also be parsed, but should not be used as the default format.
-
-Do not use these legacy formats:
-
-1. `target=agent:{agentId}:grix:direct:{sessionId}`
-2. Pure numeric user ID / agent ID
-3. Non-existent session aliases
-
-## How to Obtain the Target Session
-
-1. If replying to the current session, simply omit `to`
-2. If MEMORY.md already records the target `session_id`, reuse it directly
-3. If the target session is unknown, first use `grix_query`'s `session_search` to find the exact `session_id`
-
-Example:
-
-```json
-{
-  "action": "send",
-  "channel": "grix",
-  "accountId": "{accountId}",
-  "to": "{groupSessionId}",
-  "message": "Task completed, please check the results"
-}
-```
-
-## Key Parameter Reference
-
-| Parameter | Required | Description |
-|------|------|------|
-| `action` | ✅ | Fixed value `"send"` |
-| `channel` | ✅ | Fixed value `"grix"` |
-| `accountId` | ✅ | Current Grix account ID |
-| `message` | ✅ | Message content |
-| `to` | Required for cross-session | Exact `session_id` or resolvable `route.sessionKey` |
-
-## Important Notes
-
-1. Use `to`, not `target`
-2. `to` should preferably be an exact `session_id`; do not confuse user ID, agent ID, and session ID
-3. Pure numeric targets will fail directly; they will not auto-convert to private chats
-4. Before sending cross-session messages, confirm the current account has send permission for the target session
-5. Message content supports plain text and markdown
-
-## Conversation Card Message Protocol
-
-When the message content is **reminding the user to open a group chat**, **open a private chat conversation**, or **referencing a specific conversation entry point**, and you already have the exact `session_id`, do not send natural language links or frontend internal JSON; you must send a standalone `grix://card/conversation` Markdown link, which the frontend will uniformly parse and render as a clickable conversation card.
-
-### Standard Format
-
-Group chat:
-
-```text
-[Open Group](grix://card/conversation?session_id=<SESSION_ID>&session_type=group&title=<URI_ENCODED_GROUP_TITLE>)
-```
-
-Private chat:
-
-```text
-[Open Conversation](grix://card/conversation?session_id=<SESSION_ID>&session_type=private&title=<URI_ENCODED_CHAT_TITLE>&peer_id=<URI_ENCODED_PEER_ID>)
-```
-
-### Field Rules
-
-- `session_id`: Required. Must be the exact target session ID.
-- `session_type`: Required. Can only be `group` or `private`.
-- `title`: Required. The group title or private chat title displayed to the user.
-- `peer_id`: Optional for private chat only. Used to supplement private chat peer information, but frontend open behavior is still based on `session_id`.
-
-### Encoding Rules
-
-To prevent spaces, newlines, or reserved characters in titles, nicknames, URLs, and other fields from breaking the link, query parameter values should be URI component encoded before being written into the `grix://card` link.
-
-- Recommended: uniformly apply URI component encoding to `title`, `peer_id`, and any future text fields
-- `session_id` and `session_type` can be output as-is if they only contain safe characters
-- Link text is plain copy for the user to see and does not need URI encoding
-
-Example:
-
-```text
-[Open Group](grix://card/conversation?session_id=session-9&session_type=group&title=%E4%BA%A7%E5%93%81%E8%AE%A8%E8%AE%BA%E7%BE%A4%20A)
-```
-
-### Usage Requirements
-
-1. Only output a conversation card when the **exact `session_id` is known**
-2. If there is no `session_id`, can only send plain text explanation; cannot fabricate a conversation card
-3. Do not output `chat://...`, web links, or "click here to open session" style natural language link alternatives
-4. Do not construct frontend internal `biz_card` JSON or attempt to send Flutter/frontend private protocol structures
-5. The `grix://card/conversation` link must be on a single line and must be sent as a standalone message
-6. If additional explanation is needed, send the explanation text and the card as two separate messages; do not mix explanation and card in the same message
-7. Do not put multiple cards in the same message; when multiple jump entries are needed, send multiple messages
-8. If field values contain special characters, apply URI component encoding first, then assemble into the link
-
-### Examples
-
-Example 1: Remind user to enter a group chat
-
-```text
-[Open Product Group](grix://card/conversation?session_id=9d6a4b1d-5d37-4e38-ae6a-0c12a2c4c901&session_type=group&title=%E4%BA%A7%E5%93%81%E7%BE%A4)
-```
-
-Example 2: Remind user to enter a private chat
-
-```text
-[Open Alice Conversation](grix://card/conversation?session_id=e72ce987-2d2e-40ed-bcc9-b336b4974512&session_type=private&title=Alice&peer_id=1001)
-```
-
-Example 3: Send explanation and card as two separate messages
-
-```text
-Message 1: The test group has been created. Check the next card to enter directly.
-Message 2: [Open Test Group](grix://card/conversation?session_id=0fa947bd-bb4e-46ad-8308-5526bc98e002&session_type=group&title=%E6%B5%8B%E8%AF%95%E7%BE%A4)
-```
-
-## Error Handling
-
-- `to` cannot be resolved: confirm whether the `session_id` or `route.sessionKey` is correct
-- Insufficient permissions: check whether the current `accountId` has send permission for the target session
-- Missing parameters: ensure all required parameters are provided
-- Target format error: check whether `to` is an exact `session_id` or valid `route.sessionKey`
-
-## Best Practices
-
-1. For cross-session sending, prefer recording and reusing exact `session_id`
-2. When you need to find a session, use `grix_query.session_search` first
-3. Keep message content concise and highlight key points
-4. Do not abuse proactive messages to avoid disturbing the owner
-5. Prefer conversation cards over plain text explanations when navigation is needed
+---
+name: message-send
+description: Send messages. Supports current session replies and cross-session sending. For cross-session, use an exact `session_id` or an existing `route.sessionKey` as the `to` target; do not use the legacy `target=agent:...` format. Trigger words: send DM, DM, send message, notify.
+---
+
+# Message Send Skill
+
+This skill is used to send messages through OpenClaw's `message` tool.
+
+## Two Sending Modes
+
+### 1. Current Session Reply
+
+If replying to the current Grix session, send directly without providing an additional target session.
+
+**Parameters**:
+- `action`: "send"
+- `channel`: "grix"
+- `accountId`: current account ID
+- `message`: message content
+
+**Example**:
+
+```json
+{
+  "action": "send",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "message": "Got it, processing now..."
+}
+```
+
+### 2. Cross-Session Sending
+
+If sending to another private chat or group chat, use `to` to point to the target session.
+
+**Parameters**:
+- `action`: "send"
+- `channel`: "grix"
+- `accountId`: current account ID
+- `to`: target session identifier
+- `message`: message content
+
+**Example**:
+
+```json
+{
+  "action": "send",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "to": "{targetSessionId}",
+  "message": "Need your confirmation on a development decision: ..."
+}
+```
+
+## Real Format of `to`
+
+The current plugin recognizes these two types of targets:
+
+1. Exact Grix `session_id` (recommended, usually a UUID)
+2. An existing `route.sessionKey` in the current runtime
+
+Recommended to pass the bare `session_id` directly:
+
+```text
+to=e72ce987-2d2e-40ed-bcc9-b336b4974512
+```
+
+In compatible formats, `grix:<session_id>` or `session:<session_id>` can also be parsed, but should not be used as the default format.
+
+Do not use these legacy formats:
+
+1. `target=agent:{agentId}:grix:direct:{sessionId}`
+2. Pure numeric user ID / agent ID
+3. Non-existent session aliases
+
+## How to Obtain the Target Session
+
+1. If replying to the current session, simply omit `to`
+2. If MEMORY.md already records the target `session_id`, reuse it directly
+3. If the target session is unknown, first use `grix_query`'s `session_search` to find the exact `session_id`
+
+Example:
+
+```json
+{
+  "action": "send",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "to": "{groupSessionId}",
+  "message": "Task completed, please check the results"
+}
+```
+
+## Key Parameter Reference
+
+| Parameter | Required | Description |
+|------|------|------|
+| `action` | ✅ | Fixed value `"send"` |
+| `channel` | ✅ | Fixed value `"grix"` |
+| `accountId` | ✅ | Current Grix account ID |
+| `message` | ✅ | Message content |
+| `to` | Required for cross-session | Exact `session_id` or resolvable `route.sessionKey` |
+
+## Important Notes
+
+1. Use `to`, not `target`
+2. `to` should preferably be an exact `session_id`; do not confuse user ID, agent ID, and session ID
+3. Pure numeric targets will fail directly; they will not auto-convert to private chats
+4. Before sending cross-session messages, confirm the current account has send permission for the target session
+5. Message content supports plain text and markdown
+
+## Conversation Card Message Protocol
+
+When the message content is **reminding the user to open a group chat**, **open a private chat conversation**, or **referencing a specific conversation entry point**, and you already have the exact `session_id`, do not send natural language links or frontend internal JSON; you must send a standalone `grix://card/conversation` Markdown link, which the frontend will uniformly parse and render as a clickable conversation card.
+
+### Standard Format
+
+Group chat:
+
+```text
+[Open Group](grix://card/conversation?session_id=<SESSION_ID>&session_type=group&title=<URI_ENCODED_GROUP_TITLE>)
+```
+
+Private chat:
+
+```text
+[Open Conversation](grix://card/conversation?session_id=<SESSION_ID>&session_type=private&title=<URI_ENCODED_CHAT_TITLE>&peer_id=<URI_ENCODED_PEER_ID>)
+```
+
+### Field Rules
+
+- `session_id`: Required. Must be the exact target session ID.
+- `session_type`: Required. Can only be `group` or `private`.
+- `title`: Required. The group title or private chat title displayed to the user.
+- `peer_id`: Optional for private chat only. Used to supplement private chat peer information, but frontend open behavior is still based on `session_id`.
+
+### Encoding Rules
+
+To prevent spaces, newlines, or reserved characters in titles, nicknames, URLs, and other fields from breaking the link, query parameter values should be URI component encoded before being written into the `grix://card` link.
+
+- Recommended: uniformly apply URI component encoding to `title`, `peer_id`, and any future text fields
+- `session_id` and `session_type` can be output as-is if they only contain safe characters
+- Link text is plain copy for the user to see and does not need URI encoding
+
+Example:
+
+```text
+[Open Group](grix://card/conversation?session_id=session-9&session_type=group&title=%E4%BA%A7%E5%93%81%E8%AE%A8%E8%AE%BA%E7%BE%A4%20A)
+```
+
+### Usage Requirements
+
+1. Only output a conversation card when the **exact `session_id` is known**
+2. If there is no `session_id`, can only send plain text explanation; cannot fabricate a conversation card
+3. Do not output `chat://...`, web links, or "click here to open session" style natural language link alternatives
+4. Do not construct frontend internal `biz_card` JSON or attempt to send Flutter/frontend private protocol structures
+5. The `grix://card/conversation` link must be on a single line and must be sent as a standalone message
+6. If additional explanation is needed, send the explanation text and the card as two separate messages; do not mix explanation and card in the same message
+7. Do not put multiple cards in the same message; when multiple jump entries are needed, send multiple messages
+8. If field values contain special characters, apply URI component encoding first, then assemble into the link
+
+### Examples
+
+Example 1: Remind user to enter a group chat
+
+```text
+[Open Product Group](grix://card/conversation?session_id=9d6a4b1d-5d37-4e38-ae6a-0c12a2c4c901&session_type=group&title=%E4%BA%A7%E5%93%81%E7%BE%A4)
+```
+
+Example 2: Remind user to enter a private chat
+
+```text
+[Open Alice Conversation](grix://card/conversation?session_id=e72ce987-2d2e-40ed-bcc9-b336b4974512&session_type=private&title=Alice&peer_id=1001)
+```
+
+Example 3: Send explanation and card as two separate messages
+
+```text
+Message 1: The test group has been created. Check the next card to enter directly.
+Message 2: [Open Test Group](grix://card/conversation?session_id=0fa947bd-bb4e-46ad-8308-5526bc98e002&session_type=group&title=%E6%B5%8B%E8%AF%95%E7%BE%A4)
+```
+
+## Error Handling
+
+- `to` cannot be resolved: confirm whether the `session_id` or `route.sessionKey` is correct
+- Insufficient permissions: check whether the current `accountId` has send permission for the target session
+- Missing parameters: ensure all required parameters are provided
+- Target format error: check whether `to` is an exact `session_id` or valid `route.sessionKey`
+
+## Best Practices
+
+1. For cross-session sending, prefer recording and reusing exact `session_id`
+2. When you need to find a session, use `grix_query.session_search` first
+3. Keep message content concise and highlight key points
+4. Do not abuse proactive messages to avoid disturbing the owner
+5. Prefer conversation cards over plain text explanations when navigation is needed