@dhf-hermes/grix 0.1.0

package/grix-egg/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: grix-egg
+description: 在 Grix 安装私聊里处理 OpenClaw 或 Claude 侧安装工作流时使用。适用于收到 `install_id`、`egg/install`、`main_agent`、`install.route` 等上下文后，按安装路线完成安装、回报进度、发送卡片、拉群验收，并在身份不正确时继续修复。
+---
+
+# Grix Egg
+
+这是安装总编排技能。
+
+开始前，先用 helper 校验安装上下文：
+
+```bash
+node scripts/validate_install_context.mjs --from-file ./install-context.json
+```
+
+## 绝对规则
+
+- 远端 Grix 查询走 [grix-query](../grix-query/SKILL.md)
+- 远端群动作走 [grix-group](../grix-group/SKILL.md)
+- 远端 agent / 分类动作走 [grix-admin](../grix-admin/SKILL.md)
+- 消息卡片优先走 [message-send](../message-send/SKILL.md)
+- 本地 OpenClaw 配置只能走官方 CLI
+- 安装进行中不要主动改 `openclaw.json`
+
+## 安装状态
+
+开始、成功、失败都应发送独立状态卡。
+
+格式参考：
+
+- [Grix Card Links](../shared/references/grix-card-links.md)
+- [Acceptance Checklist](references/acceptance-checklist.md)
+
+需要生成卡片时，优先用：
+
+```bash
+node scripts/card-link.mjs egg-status --install-id <INSTALL_ID> --status running --step downloading --summary 已下载
+node scripts/card-link.mjs conversation --session-id <SESSION_ID> --session-type group --title 验收测试群
+```
+
+## 推荐主线
+
+### `openclaw_create_new` / `openclaw_existing`
+
+1. 识别安装包和目标路线
+2. 如需新建远端 agent，先走 `grix-admin create_agent`
+3. 本地绑定继续走 `grix-admin bind-local`
+4. 下载并落位安装内容
+5. 写入并校验 OpenClaw 配置
+6. 如需自动更新，补 `grix auto update` cron
+7. 创建测试群并拿到准确 `session_id`
+8. 回当前私聊单独发送测试群会话卡片
+9. 在测试群里做身份验收
+10. 回答不正确就继续修，直到身份正确
+
+### `claude_existing`
+
+1. 定位目标 Claude agent
+2. 安装 `skill.zip`
+3. 如需同步 OpenClaw 配置，继续用官方 CLI
+4. 校验后再决定是否需要拉群验收
+
+## 验收规则
+
+- 验收群一旦创建成功，就保存准确 `session_id`
+- 后续所有群测消息都发到这个 `session_id`
+- 如果拿到了准确 `session_id`，必须补一张会话卡片
+- 配置已确认正确但人格还是旧结果时，才把 `openclaw gateway restart` 当成定向补救
+
+## 收尾
+
+- 成功：状态卡 + Agent 资料卡 + 下一步说明
+- 失败：失败状态卡 + 清楚说明停在哪一步

package/grix-egg/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Grix Egg"
+  short_description: "Run Grix installation and acceptance workflows."
+  default_prompt: "Use $grix-egg to run a Grix install flow and finish acceptance in a test group."
+
+policy:
+  allow_implicit_invocation: true

package/grix-egg/references/acceptance-checklist.md

@@ -0,0 +1,10 @@
+# Acceptance Checklist
+
+`grix-egg` 安装成功前，至少确认：
+
+1. 目标内容已经落位
+2. 必要的 OpenClaw 配置已经写入并通过 `config validate`
+3. 如果创建了新 agent，Grix 绑定已经存在
+4. 如果建了测试群，已经保存准确 `session_id`
+5. 已向当前私聊单独发送测试群会话卡片
+6. 验收群里目标 agent 的身份回答正确

package/grix-egg/scripts/card-link.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const cardScript = path.resolve(scriptDir, "../../message-send/scripts/card-link.mjs");
+const result = spawnSync(process.execPath, [cardScript, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/grix-egg/scripts/validate_install_context.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+
+function cleanText(value) {
+  return String(value ?? "").trim();
+}
+
+function readPayload(argv) {
+  const fileIndex = argv.indexOf("--from-file");
+  if (fileIndex >= 0 && argv[fileIndex + 1]) {
+    return JSON.parse(fs.readFileSync(argv[fileIndex + 1], "utf8"));
+  }
+  const stdin = fs.readFileSync(0, "utf8").trim();
+  if (!stdin) {
+    throw new Error("No install context JSON provided.");
+  }
+  return JSON.parse(stdin);
+}
+
+function requiredForRoute(route) {
+  if (route === "openclaw_create_new" || route === "openclaw_existing") {
+    return ["install_id", "main_agent"];
+  }
+  if (route === "claude_existing") {
+    return ["install_id"];
+  }
+  return ["install_id"];
+}
+
+function buildSteps(route) {
+  if (route === "openclaw_create_new" || route === "openclaw_existing") {
+    return [
+      "准备安装上下文",
+      "必要时创建远端 API agent",
+      "写入并校验 OpenClaw 配置",
+      "发送安装状态卡",
+      "创建测试群并保存准确 session_id",
+      "向当前私聊发送测试群会话卡片",
+      "在测试群做身份验收并修到正确"
+    ];
+  }
+  if (route === "claude_existing") {
+    return [
+      "准备 Claude 安装上下文",
+      "安装目标技能或包",
+      "必要时同步 OpenClaw 配置",
+      "发送状态卡并决定是否群测"
+    ];
+  }
+  return ["识别路由并补齐上下文"];
+}
+
+try {
+  const payload = readPayload(process.argv.slice(2));
+  const install = payload.install && typeof payload.install === "object" ? payload.install : {};
+  const route = cleanText(install.route || payload.route || payload.install_route);
+  const required = requiredForRoute(route);
+  const missing = required.filter((key) => !cleanText(payload[key] ?? install[key]));
+  const result = {
+    ok: true,
+    route,
+    missing,
+    is_ready: missing.length === 0 && Boolean(route),
+    steps: buildSteps(route),
+  };
+  console.log(JSON.stringify(result, null, 2));
+} catch (error) {
+  console.error(JSON.stringify({
+    ok: false,
+    error: error instanceof Error ? error.message : String(error)
+  }, null, 2));
+  process.exit(1);
+}

package/grix-group/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: grix-group
+description: 管理 Grix 群聊生命周期和成员关系时使用。适用于建群、查群详情、退群、加人、移人、改角色、全员禁言、成员禁言、解散群等场景。通过 `terminal` 执行 `../shared/cli/grix-hermes.mjs group`。
+---
+
+# Grix Group
+
+群治理动作统一走共享 CLI，不假设 Hermes 内核里存在 `grix_group` tool。
+
+## 执行方式
+
+统一用：
+
+```bash
+node scripts/group.mjs --action <action> ...
+```
+
+常用例子：
+
+```bash
+node scripts/group.mjs --action create --name 版本验收群 --member-ids 1001,2001 --member-types 1,2
+node scripts/group.mjs --action detail --session-id <SESSION_ID>
+node scripts/group.mjs --action leave --session-id <SESSION_ID>
+node scripts/group.mjs --action add_members --session-id <SESSION_ID> --member-ids 1002,1003 --member-types 1,1
+```
+
+## 规则
+
+- 一次业务动作只做一次 CLI 调用
+- `leave` 静默执行，不要先去群里发告别消息
+- `memberIds` 和 `memberTypes` 数量要对应
+- 不要把本地 agent 名、本地 `main_agent`、OpenClaw 本地 ID 直接当成 Grix 成员 ID
+
+## 输出要求
+
+- 成功时返回 `session_id`
+- 如果是详情，返回成员数、禁言状态、关键配置
+- 如果是加人/移人/角色更新，说明目标成员和结果
+
+## 参考
+
+- [Hermes Grix Runtime](../shared/references/hermes-grix-config.md)

package/grix-group/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Grix Group"
+  short_description: "Manage Grix groups and membership actions."
+  default_prompt: "Use $grix-group to create a Grix test group or manage its members."
+
+policy:
+  allow_implicit_invocation: true

package/grix-group/scripts/group.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const sharedCli = path.resolve(scriptDir, "../../shared/cli/grix-hermes.mjs");
+const result = spawnSync(process.execPath, [sharedCli, "group", ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/grix-query/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: grix-query
+description: 查询 Grix 联系人、会话、消息历史时使用。适用于 Hermes 里需要查联系人、找会话、读某个会话历史、按关键词搜消息，但又不能改 Hermes 内核的场景。通过 `terminal` 执行 `../shared/cli/grix-hermes.mjs query`，走 Hermes 已配置的 Grix websocket 凭证。
+---
+
+# Grix Query
+
+只做只读查询。
+
+## 入口
+
+先判断用户要的是哪一类：
+
+- `contact_search`
+- `session_search`
+- `message_history`
+- `message_search`
+
+如果用户要读消息，但没有准确 `session_id`，先做一次 `session_search`。
+
+## 执行方式
+
+统一用 `terminal` 执行：
+
+```bash
+node scripts/query.mjs --action <action> ...
+```
+
+常用例子：
+
+```bash
+node scripts/query.mjs --action contact_search --keyword alice
+node scripts/query.mjs --action session_search --keyword 测试群
+node scripts/query.mjs --action message_history --session-id <SESSION_ID> --limit 20
+node scripts/query.mjs --action message_search --session-id <SESSION_ID> --keyword 身份 --limit 20
+```
+
+## 分页规则
+
+- 第一页先用一个合理 `limit`
+- 继续翻页时复用同一个 `session_id`
+- `message_history` / `message_search` 下一页要带 `before_id`
+
+## 输出要求
+
+- 成功时明确返回关键 ID
+- 联系人带 `peer_id` / `peer_type`
+- 会话带 `session_id`
+- 消息带 `msg_id` 和必要时间信息
+
+## 参考
+
+- [Hermes Grix Runtime](../shared/references/hermes-grix-config.md)

package/grix-query/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Grix Query"
+  short_description: "Find Grix contacts, sessions, and messages."
+  default_prompt: "Use $grix-query to find the right Grix session or inspect recent messages."
+
+policy:
+  allow_implicit_invocation: true

package/grix-query/scripts/query.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const sharedCli = path.resolve(scriptDir, "../../shared/cli/grix-hermes.mjs");
+const result = spawnSync(process.execPath, [sharedCli, "query", ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/grix-register/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: grix-register
+description: 用户需要注册 Grix 账号、发送邮箱验证码、登录、创建首个 API agent 并继续完成本地绑定时使用。注册链路走 `scripts/grix_auth.py` 的 HTTP 组件，创建完 API agent 后继续交给 `grix-admin` 的本地绑定流程。
+---
+
+# Grix Register
+
+这个技能负责 HTTP 注册链路，不依赖 Hermes 内核改造。
+
+## 执行方式
+
+统一通过 `terminal` 调用：
+
+```bash
+python3 scripts/grix_auth.py <subcommand> ...
+```
+
+## 常用子命令
+
+```bash
+python3 scripts/grix_auth.py send-email-code --email <EMAIL> --scene register
+python3 scripts/grix_auth.py register --email <EMAIL> --password <PASSWORD> --email-code <CODE>
+python3 scripts/grix_auth.py login --email <EMAIL> --password <PASSWORD>
+python3 scripts/grix_auth.py create-api-agent --access-token <TOKEN> --agent-name <NAME>
+```
+
+## 主线
+
+1. 发送邮箱验证码
+2. 完成注册或登录
+3. 创建首个 `provider_type=3` 的 API agent
+4. 从脚本返回里拿：
+   - `agent_name`
+   - `agent_id`
+   - `api_endpoint`
+   - `api_key`
+5. 继续执行 [grix-admin](../grix-admin/SKILL.md) 的 `bind-local`
+
+如果你想把“创建 API agent + 本地绑定”一次跑完，优先用：
+
+```bash
+python3 scripts/create_api_agent_and_bind.py \
+  --access-token <TOKEN> \
+  --agent-name <NAME> \
+  --model <MODEL> \
+  --json
+```
+
+如果已经有一份 `create-api-agent` 的 JSON 结果，也可以：
+
+```bash
+python3 scripts/create_api_agent_and_bind.py \
+  --agent-json-file ./created-agent.json \
+  --model <MODEL> \
+  --dry-run \
+  --json
+```
+
+## 规则
+
+- 不要求用户自己开浏览器
+- HTTP 只用于注册、登录、验证码、首个 API agent 创建
+- 本地 OpenClaw 绑定不在这个技能里手工拼，创建完就继续交给 `grix-admin`
+
+## 参考
+
+- [Hermes Grix Runtime](../shared/references/hermes-grix-config.md)
+- [Handoff To grix-admin](references/handoff-contract.md)

package/grix-register/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Grix Register"
+  short_description: "Register Grix and bootstrap the first API agent."
+  default_prompt: "Use $grix-register to register a Grix account and create the first API agent."
+
+policy:
+  allow_implicit_invocation: true

package/grix-register/references/handoff-contract.md

@@ -0,0 +1,21 @@
+# Handoff To grix-admin
+
+`grix-register` 在完成注册、登录和首个 API agent 创建后，不再自己手工写本地 OpenClaw 配置。
+
+它应继续把下面这组字段交给 `grix-admin`：
+
+- `agent_name`
+- `agent_id`
+- `api_endpoint`
+- `api_key`
+
+推荐后续命令：
+
+```bash
+python3 ../grix-admin/scripts/bind_local.py \
+  --agent-name <AGENT_NAME> \
+  --agent-id <AGENT_ID> \
+  --api-endpoint <WS_URL> \
+  --api-key <API_KEY> \
+  --model <MODEL>
+```

package/grix-register/scripts/create_api_agent_and_bind.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Create one API agent through grix_auth.py and optionally bind it locally."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+from typing import Any
+
+
+def load_or_create_payload(args: argparse.Namespace) -> dict[str, Any]:
+    if args.agent_json_file:
+        return json.loads(Path(args.agent_json_file).read_text(encoding="utf-8"))
+
+    auth_script = Path(__file__).with_name("grix_auth.py")
+    cmd = [
+        sys.executable,
+        str(auth_script),
+        "--base-url",
+        args.base_url,
+        "create-api-agent",
+        "--access-token",
+        args.access_token,
+        "--agent-name",
+        args.agent_name,
+    ]
+    if args.avatar_url:
+        cmd.extend(["--avatar-url", args.avatar_url])
+    result = subprocess.run(cmd, text=True, capture_output=True)
+    if result.returncode != 0:
+        raise RuntimeError((result.stderr or result.stdout or "").strip())
+    return json.loads(result.stdout)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Create one API agent and continue to local bind.")
+    parser.add_argument("--access-token", default="")
+    parser.add_argument("--agent-name", default="")
+    parser.add_argument("--avatar-url", default="")
+    parser.add_argument("--base-url", default="https://grix.dhf.pub")
+    parser.add_argument("--agent-json-file", default="", help="Use an existing create-api-agent JSON result instead of calling HTTP.")
+    parser.add_argument("--model", default="")
+    parser.add_argument("--openclaw", default="openclaw")
+    parser.add_argument("--openclaw-home", default="")
+    parser.add_argument("--skip-current", action="store_true")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    try:
+        if not args.agent_json_file and (not args.access_token or not args.agent_name):
+            raise RuntimeError("Need --agent-json-file or both --access-token and --agent-name.")
+        created_payload = load_or_create_payload(args)
+
+        bind_script = Path(__file__).resolve().parents[2] / "grix-admin" / "scripts" / "bind_from_json.py"
+        cmd = [
+            sys.executable,
+            str(bind_script),
+        ]
+        if args.model:
+            cmd.extend(["--model", args.model])
+        if args.openclaw:
+            cmd.extend(["--openclaw", args.openclaw])
+        if args.openclaw_home:
+            cmd.extend(["--openclaw-home", args.openclaw_home])
+        if args.skip_current:
+            cmd.append("--skip-current")
+        if args.dry_run:
+            cmd.append("--dry-run")
+        if args.json:
+            cmd.append("--json")
+
+        bind_result = subprocess.run(
+            cmd,
+            input=json.dumps(created_payload, ensure_ascii=False),
+            text=True,
+            capture_output=True,
+        )
+        if bind_result.returncode != 0:
+            raise RuntimeError((bind_result.stderr or bind_result.stdout or "").strip())
+
+        if args.json:
+            payload = {
+                "ok": True,
+                "created_agent": created_payload,
+                "bind_result": json.loads(bind_result.stdout) if bind_result.stdout.strip() else None,
+            }
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+        else:
+            if bind_result.stdout:
+                sys.stdout.write(bind_result.stdout)
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False, indent=2), file=sys.stderr)
+        else:
+            print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())