grix-connector 1.0.2

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

@@ -0,0 +1,310 @@
+---
+name: grix-update
+description: 负责 Grix 插件的后续版本维护。适用于检查是否有新版本、执行插件升级、在升级后完成校验与重启，并按规则静默或通知主 agent；不负责首次安装、账号注册、本地绑定或安装私聊流程。
+---
+
+# Grix Update
+
+这个技能只负责 **Grix 插件的版本维护**。  
+目标是让 `grix-connector` 在已经装进 OpenClaw 之后，能按固定规则完成检查更新、升级验收和失败告警。
+
+## 角色边界
+
+1. 本技能只做插件更新相关动作：检查、升级、校验、重启、通知。
+2. 本技能不做首次安装、不做账号注册、不做 agent 绑定。
+3. 本技能不接管安装私聊；如果当前上下文仍处在 egg 安装流程中，停止并交回 `grix-egg` / `grix-admin`。
+4. 只走 OpenClaw 官方 CLI，不手改 `openclaw.json`，不写临时脚本改插件安装目录。
+
+## 适用场景
+
+1. 用户要求“检查 grix 是否有新版本”。
+2. 用户要求“升级 grix 插件”。
+3. 需要给后续自动化提供一个单独的维护技能。
+4. 定时任务想要静默检查，只有失败时才通知主 agent。
+
+## 输入参数
+
+### 通用参数
+
+1. `mode`（必填）
+   - `check-only`
+   - `apply-update`
+   - `check-and-apply`
+2. `plugin_id`（可选）
+   - 默认值：`grix`
+3. `notify_on`（可选）
+   - `failure`（默认）
+   - `always`
+   - `never`
+4. `main_agent`（可选）
+   - 主要用于 cron 的 `--agent <main_agent>` 或上层工作流标记“谁负责本机维护”
+   - 它本身不是可直接发送 Grix 消息的 `to` / `session_id` 目标；如果没有明确的可投递会话，不要因为拿到了 `main_agent` 就自行猜通知目标
+5. `allow_restart`（可选）
+   - 默认值：`true`
+
+### 推荐默认输入
+
+```json
+{
+  "mode": "check-and-apply",
+  "plugin_id": "grix",
+  "notify_on": "failure",
+  "allow_restart": true
+}
+```
+
+## 完成标准
+
+只有同时满足下面条件，才算完成：
+
+1. 已确认目标插件是否存在。
+2. 已确认当前安装方式是否支持自动更新。
+3. 已执行检查动作，并给出明确结果：无更新 / 已升级 / 失败 / 不支持。
+4. 若执行了升级，已完成：
+   - `openclaw plugins doctor`
+   - `openclaw gateway restart`（仅在 `allow_restart=true` 时）
+   - `openclaw health`
+5. 若配置了通知规则，已按规则完成通知或静默结束。
+
+## 执行规则
+
+### 0. 先做上下文守卫
+
+1. 如果当前明显是 egg 安装私聊，或上下文里有 `install_id`、`egg`、`install.route` 这类安装字段，不要执行更新，直接说明当前场景不适合升级插件并停止。
+2. 不要在正在进行的安装对话里触发插件升级。
+
+### 1. 先确认插件存在
+
+优先执行：
+
+```bash
+openclaw plugins info <plugin_id> --json
+```
+
+规则：
+
+1. 若插件不存在，返回 `failed/not_installed` 并停止。
+2. 若命令失败，返回失败原因，不要继续猜测。
+
+### 2. 再确认当前是否支持自动更新
+
+先执行：
+
+```bash
+openclaw plugins update <plugin_id> --dry-run
+```
+
+规则：
+
+1. 如果 dry-run 明确表示当前插件不可更新、未被跟踪、不是 npm 安装，返回 `unsupported/not_npm_install` 并停止。
+2. 只有支持更新时，才能继续后续流程。
+3. 不要把本地目录安装、`--link` 安装、手工拷贝安装强行当作可自动更新。
+
+### 3. `check-only`
+
+只做检查，不做升级。
+
+规则：
+
+1. 运行 dry-run。
+2. 若没有新版本：
+   - 返回 `no_update`
+   - 默认静默结束
+3. 若发现新版本：
+   - 返回 `update_available`
+   - 不执行真正升级
+
+### 4. `apply-update`
+
+假定调用方已经决定升级，直接执行升级。
+
+执行顺序：
+
+```bash
+openclaw plugins update <plugin_id>
+openclaw plugins doctor
+openclaw gateway restart
+openclaw health
+```
+
+规则：
+
+1. 若 `allow_restart=false`，跳过 `openclaw gateway restart`，但要明确说明升级后尚未重启，运行态可能仍是旧版本。
+2. 任一步失败都要立刻停止，并返回失败点。
+3. 不要在失败后自动连续重试。
+
+### 5. `check-and-apply`
+
+这是给自动化最合适的模式。
+
+规则：
+
+1. 先跑 dry-run。
+2. 若没有新版本：
+   - 返回 `no_update`
+   - 静默结束
+3. 若发现新版本：
+   - 执行 `apply-update` 的完整流程
+
+## 校验顺序
+
+如果执行了升级，校验必须按这个顺序走：
+
+1. `openclaw plugins doctor`
+2. `openclaw gateway restart`（如果允许）
+3. `openclaw health`
+
+不要写完升级命令就直接宣称成功。
+
+## 通知规则
+
+`notify_on` 的行为固定如下：
+
+1. `never`
+   - 永远不发送通知
+2. `failure`
+   - 只有失败时通知主 agent
+3. `always`
+   - 成功和失败都通知主 agent
+
+补充规则：
+
+1. `main_agent` 只表示维护责任主体，不自动等价于某个可发送消息的会话目标。
+2. 如果当前上下文没有明确的维护会话或可复用的通知目标，就只返回结果，由上层 cron / 调用方处理通知；不要自行猜 `to`、`session_id` 或私聊目标。
+3. cron 场景优先用 `notify_on=never`，由 cron 运行记录收口。
+
+默认使用 `failure`。
+
+## 通知内容要求
+
+通知必须简短，只说结果，不展开技术细节。
+
+建议文案风格：
+
+1. 成功：
+   - `grix 插件已升级完成，当前检查正常。`
+2. 无更新：
+   - `grix 插件已检查，当前没有新版本。`
+3. 失败：
+   - `grix 插件自动更新失败，卡在 <步骤>。`
+4. 不支持自动更新：
+   - `grix 当前不是可自动更新的安装方式，需改成 npm 安装后再接自动更新。`
+
+## 返回结果
+
+技能应返回清晰、稳定的结果状态，推荐收口为以下几类：
+
+1. `no_update`
+2. `update_available`
+3. `updated`
+4. `failed`
+5. `unsupported`
+
+若失败，必须说明失败点属于哪一步：
+
+1. `plugins info`
+2. `plugins update --dry-run`
+3. `plugins update`
+4. `plugins doctor`
+5. `gateway restart`
+6. `health`
+
+## Guardrails
+
+1. 不改首次安装相关逻辑，不替代 `grix-register`、`grix-admin`、`grix-egg`。
+2. 不在安装私聊中做插件升级。
+3. 只用官方命令：
+   - `openclaw plugins info`
+   - `openclaw plugins update`
+   - `openclaw plugins doctor`
+   - `openclaw gateway restart`
+   - `openclaw health`
+4. 不直接修改插件目录，不手动覆盖 npm 包内容。
+5. 不为了“兼容”老安装方式去补各种旁路逻辑；不支持就是不支持。
+6. 如果升级后未重启，不得宣称运行态已经完成切换。
+7. 不自动高频重试；失败后交给下一个定时周期或人工介入。
+
+## 推荐自动化接法
+
+给定时任务使用时，优先采用：
+
+```json
+{
+  "mode": "check-and-apply",
+  "plugin_id": "grix",
+  "notify_on": "failure",
+  "main_agent": "main",
+  "allow_restart": true
+}
+```
+
+推荐频率：
+
+1. 每天 1 次
+2. 或每 6 小时 1 次
+
+默认策略：
+
+1. 没更新：静默
+2. 更新成功：静默
+3. 更新失败：通知主 agent
+
+## 推荐 Cron 挂法
+
+如果要在插件安装完成后自动维护，推荐直接创建一个隔离式 cron 任务，而不是把升级动作塞进主会话心跳。
+
+推荐命令：
+
+```bash
+openclaw cron add \
+  --name "grix auto update" \
+  --every "6h" \
+  --agent <main_agent> \
+  --session isolated \
+  --light-context \
+  --no-deliver \
+  --message 'Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}. If there is no update or the update succeeds, reply exactly NO_REPLY. If the install is unsupported or any step fails, return one short failure summary.'
+```
+
+规则：
+
+1. `--session isolated`：不要绑主会话，避免更新和重启打断当前聊天。
+2. `--no-deliver`：成功时保持静默。
+3. `notify_on` 在 cron 场景里建议固定为 `never`，由 cron 自己的运行记录负责排查。
+4. `main_agent` 应使用负责本机维护的主 agent。
+5. 推荐频率先用 `6h`；如果你想更保守，可改成每天 1 次。
+
+如果已经存在同名任务，不要重复创建，改用：
+
+```bash
+openclaw cron edit <job_id> \
+  --every "6h" \
+  --agent <main_agent> \
+  --session isolated \
+  --light-context \
+  --no-deliver \
+  --message 'Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}. If there is no update or the update succeeds, reply exactly NO_REPLY. If the install is unsupported or any step fails, return one short failure summary.'
+```
+
+创建后建议检查：
+
+```bash
+openclaw cron list
+openclaw cron status
+```
+
+## 与其他技能的分工
+
+1. `grix-register`
+   - 只负责云端账号和 API agent 参数
+2. `grix-admin`
+   - 只负责本地配置和绑定
+3. `grix-egg`
+   - 只负责安装私聊流程
+4. `grix-update`
+   - 只负责后续版本维护
+
+## References
+
+1. [references/update-contract.md](references/update-contract.md)
+2. [references/cron-setup.md](references/cron-setup.md)

package/openclaw-plugin/skills/grix-update/references/cron-setup.md

@@ -0,0 +1,56 @@
+# Grix Update Cron Setup
+
+这个文档固定插件安装完成后的自动维护接法。
+
+## 推荐目标
+
+安装完成后，应该存在一个定时 cron 任务，定期执行 `grix-update`。
+
+推荐要求：
+
+1. 使用 `isolated` 会话
+2. 默认静默执行
+3. 由负责本机维护的主 agent 执行
+4. 默认每 6 小时运行一次
+
+## 推荐创建命令
+
+```bash
+openclaw cron add \
+  --name "grix auto update" \
+  --every "6h" \
+  --agent <main_agent> \
+  --session isolated \
+  --light-context \
+  --no-deliver \
+  --message 'Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}. If there is no update or the update succeeds, reply exactly NO_REPLY. If the install is unsupported or any step fails, return one short failure summary.'
+```
+
+## 重复安装时的处理
+
+如果已经存在同名任务，不要重复创建，改用 `edit`：
+
+```bash
+openclaw cron edit <job_id> \
+  --every "6h" \
+  --agent <main_agent> \
+  --session isolated \
+  --light-context \
+  --no-deliver \
+  --message 'Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}. If there is no update or the update succeeds, reply exactly NO_REPLY. If the install is unsupported or any step fails, return one short failure summary.'
+```
+
+## 检查命令
+
+```bash
+openclaw cron list
+openclaw cron status
+openclaw cron runs --id <job_id> --limit 20
+```
+
+## 说明
+
+1. `--session isolated`：避免更新和 gateway 重启打断当前主聊天。
+2. `--no-deliver`：成功时不向外发消息。
+3. `notify_on=never`：cron 场景下不让技能自己发通知，统一由 cron 运行记录收口。
+4. 如果后续要做失败告警，应在上层 cron 规则里处理，不要把通知逻辑塞回技能里。

package/openclaw-plugin/skills/grix-update/references/update-contract.md

@@ -0,0 +1,149 @@
+# Grix Update Contract
+
+这个文档用于固定 `grix-update` 的最小执行契约，方便后续接定时任务、心跳提醒或其他维护流程时保持一致。
+
+## 目标
+
+`grix-update` 只做下面 5 件事：
+
+1. 确认插件是否存在
+2. 确认当前安装方式是否支持自动更新
+3. 检查是否有新版本
+4. 需要时执行升级
+5. 在升级后完成校验、重启和结果通知
+
+## 命令阶梯
+
+按顺序使用这些官方命令：
+
+```bash
+openclaw plugins info grix --json
+openclaw plugins update grix --dry-run
+openclaw plugins update grix
+openclaw plugins doctor
+openclaw gateway restart
+openclaw health
+```
+
+规则：
+
+1. 先 `info`，再 `dry-run`，不要跳步。
+2. `dry-run` 没显示可更新时，不执行真正升级。
+3. 真正升级后，不要跳过 `doctor`。
+4. 允许重启时，`doctor` 后面必须接 `gateway restart` 和 `health`。
+
+## 模式定义
+
+### `check-only`
+
+用途：只检查，不升级。
+
+收口：
+
+1. 没新版本：`no_update`
+2. 有新版本：`update_available`
+3. 插件不存在或安装方式不支持：`failed` / `unsupported`
+
+### `apply-update`
+
+用途：直接执行升级。
+
+收口：
+
+1. 升级并验收成功：`updated`
+2. 任一步失败：`failed`
+
+### `check-and-apply`
+
+用途：自动化默认模式。
+
+收口：
+
+1. 没新版本：`no_update`
+2. 有新版本且升级成功：`updated`
+3. 任一步失败：`failed`
+4. 安装方式不支持：`unsupported`
+
+## 返回值语义
+
+建议把结果理解成下面几种业务状态：
+
+1. `no_update`
+   - 已检查，没有可升级版本
+2. `update_available`
+   - 已检查，发现可升级版本，但本次没有执行升级
+3. `updated`
+   - 已完成升级，并且升级后检查通过
+4. `failed`
+   - 在检查、升级、重启或验收中的某一步失败
+5. `unsupported`
+   - 当前安装方式不支持自动更新
+
+## 失败点命名
+
+失败时，建议把失败点固定在这些步骤里：
+
+1. `plugins_info`
+2. `plugins_update_dry_run`
+3. `plugins_update`
+4. `plugins_doctor`
+5. `gateway_restart`
+6. `health`
+
+这样后续接自动化时更容易做统计和告警。
+
+## 通知契约
+
+`notify_on` 只允许这 3 个值：
+
+1. `never`
+2. `failure`
+3. `always`
+
+默认值：`failure`
+
+补充说明：
+
+1. `main_agent` 主要用于选择哪个本地 agent 负责执行维护任务，例如 cron 里的 `--agent <main_agent>`。
+2. `main_agent` 本身不是可直接发送 Grix 消息的目标；如果没有明确的通知会话，就只返回结果，由上层任务或 cron 记录处理通知。
+3. cron 默认用 `notify_on=never`，不要在技能内部再猜一条通知路径。
+
+建议通知文案保持一句话：
+
+1. 成功：`grix 插件已升级完成，当前检查正常。`
+2. 无更新：`grix 插件已检查，当前没有新版本。`
+3. 失败：`grix 插件自动更新失败，卡在 <步骤>。`
+4. 不支持：`grix 当前不是可自动更新的安装方式，需改成 npm 安装后再接自动更新。`
+
+## 自动化建议
+
+推荐给定时任务直接使用：
+
+```json
+{
+  "mode": "check-and-apply",
+  "plugin_id": "grix",
+  "notify_on": "never",
+  "main_agent": "main",
+  "allow_restart": true
+}
+```
+
+推荐频率：
+
+1. 每天 1 次
+2. 或每 6 小时 1 次
+
+默认行为：
+
+1. 没更新：静默结束
+2. 更新成功：静默结束
+3. 更新失败：在 cron 运行记录里保留失败结果，由维护者或上层任务统一处理
+
+## 禁止事项
+
+1. 不在 egg 安装私聊里触发升级
+2. 不直接修改插件目录
+3. 不手工覆盖 npm 包文件
+4. 不为了兼容旧安装方式写旁路逻辑
+5. 不在一次失败后做连续重试

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

@@ -0,0 +1,197 @@
+---
+name: message-send
+description: 发送消息。支持当前会话回复和跨会话发送。跨会话时使用准确的 `session_id` 或已存在的 `route.sessionKey` 作为 `to` 目标，不使用旧的 `target=agent:...` 格式。触发词：发私信、私信、发送消息、send message、notify。
+---
+
+# 消息发送技能
+
+这个技能用于通过 OpenClaw 的 `message` 工具发送消息。
+
+## 两种发送模式
+
+### 1. 当前会话回复
+
+如果就是回复当前 Grix 会话，直接发送，不需要额外提供目标会话。
+
+**参数**：
+- `action`: "send"
+- `channel`: "grix"
+- `accountId`: 当前账号 ID
+- `message`: 消息内容
+
+**示例**：
+
+```json
+{
+  "action": "send",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "message": "收到，正在处理中..."
+}
+```
+
+### 2. 跨会话发送
+
+如果要发到别的私聊或群聊，使用 `to` 指向目标会话。
+
+**参数**：
+- `action`: "send"
+- `channel`: "grix"
+- `accountId`: 当前账号 ID
+- `to`: 目标会话标识
+- `message`: 消息内容
+
+**示例**：
+
+```json
+{
+  "action": "send",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "to": "{targetSessionId}",
+  "message": "需要您确认一个开发决策：..."
+}
+```
+
+## `to` 的真实写法
+
+当前插件认的是下面两类目标：
+
+1. 准确的 Grix `session_id`（推荐，通常是 UUID）
+2. 已存在于当前运行时中的 `route.sessionKey`
+
+推荐直接传裸 `session_id`：
+
+```text
+to=e72ce987-2d2e-40ed-bcc9-b336b4974512
+```
+
+兼容写法里，`grix:<session_id>` 或 `session:<session_id>` 也能被解析，但不要作为默认格式。
+
+不要使用这些旧写法：
+
+1. `target=agent:{agentId}:grix:direct:{sessionId}`
+2. 纯数字用户 ID / agent ID
+3. 不存在的会话别名
+
+## 如何获取目标会话
+
+1. 如果就是回复当前会话，直接省略 `to`
+2. 如果 MEMORY.md 已记录目标 `session_id`，直接复用
+3. 如果还不知道目标会话，先用 `grix_query` 的 `session_search` 找到准确 `session_id`
+
+示例：
+
+```json
+{
+  "action": "send",
+  "channel": "grix",
+  "accountId": "{accountId}",
+  "to": "{groupSessionId}",
+  "message": "任务已完成，请查看结果"
+}
+```
+
+## 关键参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `action` | ✅ | 固定值 `"send"` |
+| `channel` | ✅ | 固定值 `"grix"` |
+| `accountId` | ✅ | 当前 Grix 账号 ID |
+| `message` | ✅ | 消息内容 |
+| `to` | 跨会话必填 | 准确 `session_id` 或可解析的 `route.sessionKey` |
+
+## 注意事项
+
+1. 使用 `to`，不要用 `target`
+2. `to` 优先传准确 `session_id`，不要混淆用户 ID、agent ID 和会话 ID
+3. 纯数字目标会直接失败，不会自动转成私聊
+4. 跨会话发消息前，先确认当前账号对目标会话有发送权限
+5. 消息内容支持纯文本和 markdown
+
+## 会话卡片消息协议
+
+当消息内容是在**提醒用户打开某个群聊**、**打开某个私聊对话**、**引用某个具体对话记录入口**时，如果已经拿到了准确的 `session_id`，不要发送自然语言链接，也不要发送前端内部 JSON；必须发送独立的 `grix://card/conversation` Markdown 链接，由前端统一解析并渲染为可点击的会话卡片。
+
+### 标准格式
+
+群聊：
+
+```text
+[打开群聊](grix://card/conversation?session_id=<SESSION_ID>&session_type=group&title=<URI_ENCODED_GROUP_TITLE>)
+```
+
+私聊：
+
+```text
+[打开对话](grix://card/conversation?session_id=<SESSION_ID>&session_type=private&title=<URI_ENCODED_CHAT_TITLE>&peer_id=<URI_ENCODED_PEER_ID>)
+```
+
+### 字段规则
+
+- `session_id`：必填。必须是准确的目标会话 ID。
+- `session_type`：必填。只能是 `group` 或 `private`。
+- `title`：必填。展示给用户看的群标题或私聊标题。
+- `peer_id`：仅私聊可选。用于补充私聊对象信息，但前端打开行为仍以 `session_id` 为准。
+
+### 编码规则
+
+为了避免标题、昵称、URL 等字段里的空格、换行或保留字符破坏链接，query 参数值应按 URI component 规则编码后再写入 `grix://card` 链接。
+
+- 推荐：对 `title`、`peer_id`、以及未来可能扩展的文本字段统一做 URI component 编码
+- `session_id` 和 `session_type` 如果本身只包含安全字符，可以直接原样输出
+- 链接文本是给用户看的普通文案，不需要做 URI 编码
+
+示例：
+
+```text
+[打开群聊](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)
+```
+
+### 使用要求
+
+1. 只有在**已知准确 `session_id`** 时，才允许输出会话卡片
+2. 如果没有 `session_id`，只能发送普通文本说明，不能伪造会话卡片
+3. 不要输出 `chat://...`、网页链接、或“点这里打开会话”之类的自然语言链接替代方案
+4. 不要构造前端内部 `biz_card` JSON，也不要尝试发送 Flutter/前端私有协议结构
+5. `grix://card/conversation` 链接必须单行，且必须单独作为一条消息发送
+6. 如果还要补说明，说明文字和卡片分两条消息发送；不要把说明和卡片混在同一条里
+7. 同一条消息里不要放多张卡片；需要多个跳转入口时，分多条消息发送
+8. 如果字段值包含特殊字符，先做 URI component 编码，再拼进链接
+
+### 示例
+
+示例 1：提醒用户进入群聊
+
+```text
+[打开产品群](grix://card/conversation?session_id=9d6a4b1d-5d37-4e38-ae6a-0c12a2c4c901&session_type=group&title=%E4%BA%A7%E5%93%81%E7%BE%A4)
+```
+
+示例 2：提醒用户进入某个私聊
+
+```text
+[打开 Alice 对话](grix://card/conversation?session_id=e72ce987-2d2e-40ed-bcc9-b336b4974512&session_type=private&title=Alice&peer_id=1001)
+```
+
+示例 3：带说明时分两条发送
+
+```text
+消息 1：测试群已经建好，你看下一条卡片就能直接进去。
+消息 2：[打开测试群](grix://card/conversation?session_id=0fa947bd-bb4e-46ad-8308-5526bc98e002&session_type=group&title=%E6%B5%8B%E8%AF%95%E7%BE%A4)
+```
+
+## 错误处理
+
+- `to` 无法解析：确认 `session_id` 或 `route.sessionKey` 是否正确
+- 权限不足：检查当前 `accountId` 是否有目标会话的发送权限
+- 参数缺失：确保必填参数都已提供
+- 目标格式错误：检查 `to` 是否是准确 `session_id` 或有效 `route.sessionKey`
+
+## 最佳实践
+
+1. 跨会话发送时，优先记录和复用准确 `session_id`
+2. 需要找会话时，先用 `grix_query.session_search`
+3. 消息内容保持简洁，突出重点
+4. 不要滥用主动消息，避免打扰 owner
+5. 需要跳转时优先用会话卡片，而不是发普通说明文字