@dhf-hermes/grix 0.1.0

package/lib/manifest.mjs

@@ -0,0 +1,68 @@
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILLS = [
+  {
+    name: "grix-admin",
+    description: "Remote Grix agent creation/category management plus local OpenClaw binding."
+  },
+  {
+    name: "grix-egg",
+    description: "Install-flow orchestrator for Grix/OpenClaw package delivery and acceptance."
+  },
+  {
+    name: "grix-group",
+    description: "Grix group lifecycle and membership governance over the bundled websocket CLI."
+  },
+  {
+    name: "grix-query",
+    description: "Read-only Grix contact, session, and message lookup over the bundled websocket CLI."
+  },
+  {
+    name: "grix-register",
+    description: "HTTP-based Grix registration and first-agent bootstrap for Hermes/OpenClaw."
+  },
+  {
+    name: "grix-update",
+    description: "OpenClaw plugin update workflow for Grix-related deployments."
+  },
+  {
+    name: "message-send",
+    description: "Hermes-native Grix message sending and conversation-card rules."
+  },
+  {
+    name: "message-unsend",
+    description: "Silent Grix unsend workflow over the bundled websocket CLI."
+  },
+  {
+    name: "openclaw-memory-setup",
+    description: "OpenClaw memory provider setup and validation."
+  }
+];
+
+export const SUPPORT_ENTRIES = ["shared"];
+
+export function projectRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function defaultInstallDir() {
+  const hermesHome = process.env.HERMES_HOME
+    ? path.resolve(process.env.HERMES_HOME)
+    : path.join(homedir(), ".hermes");
+  return path.join(hermesHome, "skills", "grix-hermes");
+}
+
+export function installEntries() {
+  return [...SKILLS.map((skill) => skill.name), ...SUPPORT_ENTRIES];
+}
+
+export function manifestData() {
+  return {
+    name: "grix-hermes",
+    version: "0.1.0",
+    install_dir: defaultInstallDir(),
+    skills: SKILLS
+  };
+}

package/message-send/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: message-send
+description: 需要在 Hermes 里向 Grix 当前会话或其他会话发送消息时使用。优先使用 Hermes 自带 `send_message`，并遵守 Grix `session_id`、`route_session_key`、会话卡片、状态卡片的发送规则。
+---
+
+# Message Send
+
+这个技能现在有两条路：
+
+1. 当前会话内普通回复：直接回复
+2. 跨会话、卡片、独立投递：优先用本技能自带的 WS helper
+
+## 发送主线
+
+### 当前会话回复
+
+如果就是回复当前会话，直接正常回复即可。
+
+### 跨会话发送
+
+优先使用：
+
+```bash
+node scripts/send.mjs --to <SESSION_ID_OR_ROUTE_SESSION_KEY> --message "..."
+```
+
+如果上层明确要求走 Hermes 自带 `send_message`，再使用：
+
+```json
+{
+  "action": "send",
+  "target": "grix:<SESSION_ID_OR_ROUTE_SESSION_KEY>",
+  "message": "..."
+}
+```
+
+不要把裸 `session_id` 当成 Hermes `send_message.target`。
+
+## 如何拿目标会话
+
+- 已知准确 `session_id`：直接发
+- 只有 `route_session_key`：也可以直接发
+- 还不知道目标：先用 [grix-query](../grix-query/SKILL.md) 找准确会话
+
+## 卡片规则
+
+如果你要发：
+
+- 会话卡片
+- 安装状态卡
+- Agent 资料卡
+
+都应优先通过本技能的 helper 先生成单行 Markdown 链接，再单独一条消息发送。
+
+参考格式见：
+
+- [Grix Card Links](../shared/references/grix-card-links.md)
+
+如果要稳定生成卡片链接，优先用本技能自带 helper：
+
+```bash
+node scripts/send.mjs --to <SESSION_ID_OR_ROUTE_SESSION_KEY> --message "$(node scripts/card-link.mjs conversation --session-id <SESSION_ID> --session-type group --title 测试群)"
+node scripts/card-link.mjs conversation --session-id <SESSION_ID> --session-type group --title 测试群
+node scripts/card-link.mjs user-profile --user-id <AGENT_ID> --nickname writer-openclaw
+node scripts/card-link.mjs egg-status --install-id <INSTALL_ID> --status running --step installing --summary 已开始安装
+```
+
+## 注意
+
+- `grix://card` 链接不要混在普通说明文字里
+- 如果还要补充说明，另发一条普通文本

package/message-send/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Message Send"
+  short_description: "Send Grix messages and card links with Hermes."
+  default_prompt: "Use $message-send to deliver a Grix message or a conversation card with Hermes."
+
+policy:
+  allow_implicit_invocation: true

package/message-send/scripts/card-link.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+import { dispatchCardBuilder } from "../../shared/cli/card-links.mjs";
+
+function toCamelFlag(key) {
+  return key.replace(/-([a-z])/g, (_match, ch) => ch.toUpperCase());
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      positional.push(token);
+      continue;
+    }
+    const key = toCamelFlag(token.slice(2));
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    i += 1;
+  }
+  return { positional, flags };
+}
+
+const { positional, flags } = parseArgs(process.argv.slice(2));
+const kind = positional[0];
+if (!kind || ["help", "--help", "-h"].includes(kind)) {
+  console.log(`Usage:
+  node scripts/card-link.mjs conversation --session-id <id> --session-type group --title <title>
+  node scripts/card-link.mjs user-profile --user-id <id> --nickname <name> [--avatar-url <url>]
+  node scripts/card-link.mjs egg-status --install-id <id> --status running --step installing --summary <text>`);
+  process.exit(0);
+}
+
+console.log(dispatchCardBuilder(kind, flags));

package/message-send/scripts/send.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, "send", ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/message-unsend/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: message-unsend
+description: 需要在 Hermes 里静默撤回 Grix 消息时使用。适用于撤回 agent 自己刚发出的错误消息、状态消息或卡片消息。通过 `terminal` 执行 `../shared/cli/grix-hermes.mjs unsend`，按静默双重撤回规则处理。
+---
+
+# Message Unsend
+
+这个技能只做静默撤回。
+
+## 执行方式
+
+统一用：
+
+```bash
+node scripts/unsend.mjs --message-id <MSG_ID> --session-id <SESSION_ID>
+```
+
+如果目标不是直接 `session_id`，也可以传：
+
+```bash
+node scripts/unsend.mjs --message-id <MSG_ID> --to <ROUTE_SESSION_KEY_OR_SESSION_ID>
+```
+
+如果你还知道当前命令消息所在通道和消息 ID，就一起传，让它做静默双重撤回：
+
+```bash
+node scripts/unsend.mjs --message-id <TARGET_MSG_ID> --session-id <SESSION_ID> --current-channel-id <CURRENT_CHANNEL_ID> --current-message-id <CURRENT_MSG_ID>
+```
+
+## 规则
+
+- `messageId` 必须是数字字符串
+- 优先用于撤回 agent 自己刚发的消息
+- 默认静默执行，不要先发“我来撤回一下”
+- 如果消息不存在或不可撤回，不要额外制造噪音
+
+## 参考
+
+- [Hermes Grix Runtime](../shared/references/hermes-grix-config.md)

package/message-unsend/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Message Unsend"
+  short_description: "Silently retract Grix messages through websocket."
+  default_prompt: "Use $message-unsend to silently retract an incorrect Grix message."
+
+policy:
+  allow_implicit_invocation: true

package/message-unsend/scripts/unsend.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, "unsend", ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/openclaw-memory-setup/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: openclaw-memory-setup
+description: 配置 OpenClaw memory provider、Ollama embedding 模型、校验并重建索引时使用。适用于新机器初始化、已有配置调整、provider 切换和资源受限主机的 memory 健康检查。通过本技能自带脚本和 `openclaw` 官方 CLI 完成。
+---
+
+# OpenClaw Memory Setup
+
+## 进入方式
+
+如果用户已经给了明确 provider / model / endpoint / api key，就直接改配置。
+
+如果机器情况还不清楚，先体检，再挑候选模型，再做实测。
+
+## 可用脚本
+
+```bash
+python3 scripts/survey_host_readiness.py --json
+python3 scripts/bench_ollama_embeddings.py --json --model nomic-embed-text
+python3 scripts/set_openclaw_memory_model.py --preview ...
+python3 scripts/set_openclaw_memory_model.py ...
+```
+
+## 主线
+
+1. 需要时先跑 `survey_host_readiness.py`
+2. 如需本地模型比较，再跑 `bench_ollama_embeddings.py`
+3. 用 `set_openclaw_memory_model.py` 预览或写入配置
+4. 写完后必须执行：
+   - `openclaw --profile <profile> config validate`
+   - `openclaw --profile <profile> gateway restart`
+   - `openclaw --profile <profile> memory index --force`
+   - `openclaw --profile <profile> memory status`
+   - `openclaw --profile <profile> status`
+
+## 结果判断
+
+- 只改了配置但没重建索引，不算完成
+- `memory status` 和 `status` 都正常，才算完成

package/openclaw-memory-setup/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "OpenClaw Memory Setup"
+  short_description: "Configure and validate OpenClaw memory."
+  default_prompt: "Use $openclaw-memory-setup to configure and verify OpenClaw memory."
+
+policy:
+  allow_implicit_invocation: true

package/openclaw-memory-setup/scripts/bench_ollama_embeddings.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""Benchmark Ollama embedding models on the current machine."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import sys
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+DEFAULT_TEXT = (
+    "Generate a stable semantic embedding for this short bilingual memory sample. "
+    "It should be suitable for retrieval, recall, and near-duplicate detection."
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Benchmark Ollama embedding models with single and batched requests."
+    )
+    parser.add_argument(
+        "models",
+        nargs="+",
+        help="Model names to benchmark, for example embeddinggemma:300m-qat-q8_0",
+    )
+    parser.add_argument(
+        "--host",
+        default="http://127.0.0.1:11434",
+        help="Ollama host. Default: %(default)s",
+    )
+    parser.add_argument(
+        "--rounds",
+        type=int,
+        default=1,
+        help="Measured rounds per test after warmup. Default: %(default)s",
+    )
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=4,
+        help="Number of inputs in the batch test. Default: %(default)s",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=300.0,
+        help="Request timeout in seconds. Default: %(default)s",
+    )
+    parser.add_argument(
+        "--single-text",
+        default=DEFAULT_TEXT,
+        help="Text used for the single-input benchmark.",
+    )
+    parser.add_argument(
+        "--skip-warmup",
+        action="store_true",
+        help="Skip the initial warmup request for each model.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit full JSON results instead of a human table.",
+    )
+    args = parser.parse_args()
+    if args.rounds < 1:
+        parser.error("--rounds must be at least 1")
+    if args.batch_size < 1:
+        parser.error("--batch-size must be at least 1")
+    return args
+
+
+def build_batch_inputs(text: str, batch_size: int) -> list[str]:
+    return [f"{text} [sample {index + 1}]" for index in range(batch_size)]
+
+
+def post_embed(host: str, model: str, inputs: list[str], timeout: float) -> dict[str, Any]:
+    url = host.rstrip("/") + "/api/embed"
+    payload = {"model": model, "input": inputs if len(inputs) > 1 else inputs[0]}
+    body = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            data = json.load(response)
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"HTTP {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Cannot reach Ollama at {url}: {exc}") from exc
+
+    embeddings = data.get("embeddings")
+    if not isinstance(embeddings, list):
+        raise RuntimeError(f"Unexpected Ollama response for {model}: {data}")
+    return data
+
+
+def run_one(host: str, model: str, inputs: list[str], timeout: float) -> dict[str, Any]:
+    started = time.perf_counter()
+    response = post_embed(host, model, inputs, timeout)
+    elapsed = time.perf_counter() - started
+    total_duration = response.get("total_duration")
+    api_seconds = None
+    if isinstance(total_duration, (int, float)):
+        api_seconds = float(total_duration) / 1_000_000_000.0
+    embeddings = response.get("embeddings", [])
+    return {
+        "wall_seconds": elapsed,
+        "api_seconds": api_seconds,
+        "items": len(embeddings),
+        "vector_dims": len(embeddings[0]) if embeddings else 0,
+    }
+
+
+def median_or_none(values: list[float | None]) -> float | None:
+    usable = [value for value in values if value is not None]
+    if not usable:
+        return None
+    return statistics.median(usable)
+
+
+def benchmark_model(
+    host: str,
+    model: str,
+    single_text: str,
+    batch_inputs: list[str],
+    rounds: int,
+    timeout: float,
+    skip_warmup: bool,
+) -> dict[str, Any]:
+    if not skip_warmup:
+        run_one(host, model, [single_text], timeout)
+
+    single_runs = [run_one(host, model, [single_text], timeout) for _ in range(rounds)]
+    batch_runs = [run_one(host, model, batch_inputs, timeout) for _ in range(rounds)]
+
+    return {
+        "model": model,
+        "ok": True,
+        "single_wall_seconds": statistics.median(run["wall_seconds"] for run in single_runs),
+        "single_api_seconds": median_or_none([run["api_seconds"] for run in single_runs]),
+        "batch_wall_seconds": statistics.median(run["wall_seconds"] for run in batch_runs),
+        "batch_api_seconds": median_or_none([run["api_seconds"] for run in batch_runs]),
+        "batch_size": len(batch_inputs),
+        "vector_dims": single_runs[-1]["vector_dims"],
+        "rounds": rounds,
+    }
+
+
+def format_seconds(value: float | None) -> str:
+    if value is None:
+        return "-"
+    return f"{value:.2f}"
+
+
+def print_table(results: list[dict[str, Any]], batch_size: int) -> None:
+    headers = [
+        "Model",
+        "Single(s)",
+        f"Batch{batch_size}(s)",
+        "API Single(s)",
+        f"API Batch{batch_size}(s)",
+        "Dims",
+        "Status",
+    ]
+    rows: list[list[str]] = []
+    for result in results:
+        if result["ok"]:
+            rows.append(
+                [
+                    result["model"],
+                    format_seconds(result["single_wall_seconds"]),
+                    format_seconds(result["batch_wall_seconds"]),
+                    format_seconds(result["single_api_seconds"]),
+                    format_seconds(result["batch_api_seconds"]),
+                    str(result["vector_dims"]),
+                    "ok",
+                ]
+            )
+        else:
+            rows.append(
+                [
+                    result["model"],
+                    "-",
+                    "-",
+                    "-",
+                    "-",
+                    "-",
+                    result["error"],
+                ]
+            )
+
+    widths = [
+        max(len(header), *(len(row[index]) for row in rows))
+        for index, header in enumerate(headers)
+    ]
+
+    def emit(columns: list[str]) -> None:
+        print("  ".join(value.ljust(widths[index]) for index, value in enumerate(columns)))
+
+    emit(headers)
+    emit(["-" * width for width in widths])
+    for row in rows:
+        emit(row)
+
+    successful = [result for result in results if result["ok"]]
+    if successful:
+        ranked = sorted(
+            successful,
+            key=lambda item: (
+                item["batch_wall_seconds"],
+                item["single_wall_seconds"],
+                item["model"],
+            ),
+        )
+        print()
+        print(f"Recommended by speed: {ranked[0]['model']}")
+
+
+def main() -> int:
+    args = parse_args()
+    batch_inputs = build_batch_inputs(args.single_text, args.batch_size)
+    results: list[dict[str, Any]] = []
+
+    for model in args.models:
+        try:
+            result = benchmark_model(
+                host=args.host,
+                model=model,
+                single_text=args.single_text,
+                batch_inputs=batch_inputs,
+                rounds=args.rounds,
+                timeout=args.timeout,
+                skip_warmup=args.skip_warmup,
+            )
+        except Exception as exc:  # noqa: BLE001
+            result = {"model": model, "ok": False, "error": str(exc)}
+        results.append(result)
+
+    successful = [result for result in results if result["ok"]]
+    if args.json:
+        print(json.dumps({"results": results}, indent=2))
+    else:
+        print_table(results, args.batch_size)
+
+    return 0 if successful else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())