@dhf-hermes/grix 0.1.0

package/shared/cli/config.mjs

@@ -0,0 +1,141 @@
+import fs from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import YAML from "yaml";
+
+const DEFAULT_BASE_URL = "https://grix.dhf.pub";
+const DEFAULT_CAPABILITIES = ["session_route", "thread_v1", "inbound_media_v1", "local_action_v1"];
+const DEFAULT_LOCAL_ACTIONS = ["exec_approve", "exec_reject"];
+
+function parseEnvFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  const result = {};
+  for (const rawLine of fs.readFileSync(filePath, "utf8").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq <= 0) {
+      continue;
+    }
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+
+function readYaml(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  const text = fs.readFileSync(filePath, "utf8");
+  if (!text.trim()) {
+    return {};
+  }
+  const parsed = YAML.parse(text);
+  return parsed && typeof parsed === "object" ? parsed : {};
+}
+
+function cleanText(value) {
+  return String(value ?? "").trim();
+}
+
+function cleanList(value, fallback = []) {
+  if (Array.isArray(value)) {
+    return value.map((item) => cleanText(item)).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return [...fallback];
+}
+
+function cleanInt(value, fallback) {
+  const numeric = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function resolveHermesHome(overrides = {}) {
+  return path.resolve(
+    cleanText(overrides.hermesHome)
+      || cleanText(process.env.HERMES_HOME)
+      || path.join(homedir(), ".hermes")
+  );
+}
+
+function resolvePlatformConfig(configYaml) {
+  const topLevel = configYaml?.platforms?.grix;
+  if (topLevel && typeof topLevel === "object") {
+    return topLevel;
+  }
+  const nested = configYaml?.gateway?.platforms?.grix;
+  if (nested && typeof nested === "object") {
+    return nested;
+  }
+  return {};
+}
+
+function mergedEnv(hermesHome) {
+  const envFile = path.join(hermesHome, ".env");
+  return {
+    ...parseEnvFile(envFile),
+    ...process.env
+  };
+}
+
+export function resolveRuntimeConfig(overrides = {}) {
+  const hermesHome = resolveHermesHome(overrides);
+  const env = mergedEnv(hermesHome);
+  const configYaml = readYaml(path.join(hermesHome, "config.yaml"));
+  const grix = resolvePlatformConfig(configYaml);
+  const extra = grix?.extra && typeof grix.extra === "object" ? grix.extra : {};
+
+  const endpoint = cleanText(overrides.endpoint)
+    || cleanText(env.GRIX_ENDPOINT)
+    || cleanText(extra.endpoint);
+  const agentId = cleanText(overrides.agentId)
+    || cleanText(env.GRIX_AGENT_ID)
+    || cleanText(extra.agent_id);
+  const apiKey = cleanText(overrides.apiKey)
+    || cleanText(env.GRIX_API_KEY)
+    || cleanText(grix?.api_key)
+    || cleanText(grix?.token);
+  const accountId = cleanText(overrides.accountId)
+    || cleanText(env.GRIX_ACCOUNT_ID)
+    || cleanText(extra.account_id)
+    || "main";
+
+  if (!endpoint || !agentId || !apiKey) {
+    throw new Error(
+      "Missing Grix runtime config. Need endpoint, agent_id, and api_key from Hermes env/config."
+    );
+  }
+
+  return {
+    hermesHome,
+    baseUrl: cleanText(overrides.baseUrl) || cleanText(env.GRIX_WEB_BASE_URL) || DEFAULT_BASE_URL,
+    connection: {
+      endpoint,
+      agentId,
+      apiKey,
+      accountId,
+      client: cleanText(overrides.client) || cleanText(env.GRIX_CLIENT) || cleanText(extra.client) || "grix-hermes",
+      clientType: cleanText(overrides.clientType) || cleanText(env.GRIX_CLIENT_TYPE) || cleanText(extra.client_type) || "hermes",
+      clientVersion: cleanText(overrides.clientVersion) || cleanText(extra.client_version) || "0.1.0",
+      hostType: cleanText(overrides.hostType) || cleanText(extra.host_type) || "hermes",
+      hostVersion: cleanText(overrides.hostVersion) || cleanText(extra.host_version) || undefined,
+      contractVersion: cleanInt(overrides.contractVersion || extra.contract_version, 1),
+      capabilities: cleanList(overrides.capabilities || env.GRIX_CAPABILITIES || extra.capabilities, DEFAULT_CAPABILITIES),
+      localActions: cleanList(overrides.localActions || extra.local_actions, DEFAULT_LOCAL_ACTIONS),
+      connectTimeoutMs: cleanInt(overrides.connectTimeoutMs || env.GRIX_CONNECT_TIMEOUT_MS || extra.connect_timeout_ms, 10000),
+      requestTimeoutMs: cleanInt(overrides.requestTimeoutMs || env.GRIX_REQUEST_TIMEOUT_MS || extra.request_timeout_ms, 20000)
+    }
+  };
+}

package/shared/cli/grix-hermes.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+import { AibotWsClient } from "./aibot-client.mjs";
+import { runAdmin, runGroup, runQuery, runSend, runUnsend } from "./actions.mjs";
+import { resolveRuntimeConfig } from "./config.mjs";
+
+function printHelp() {
+  console.log(`grix-hermes ws cli
+
+Usage:
+  node shared/cli/grix-hermes.mjs send --to <session-or-route> --message "..."
+  node shared/cli/grix-hermes.mjs query --action session_search --keyword xxx
+  node shared/cli/grix-hermes.mjs group --action create --name dev --member-ids 1001,1002 --member-types 1,2
+  node shared/cli/grix-hermes.mjs admin --action create_agent --agent-name my-agent
+  node shared/cli/grix-hermes.mjs unsend --message-id 2033371385615093760 --session-id <session>
+`);
+}
+
+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 };
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const command = positional[0];
+  if (!command || command === "help" || command === "--help" || command === "-h" || flags.help) {
+    printHelp();
+    return;
+  }
+
+  const runtime = resolveRuntimeConfig(flags);
+  const options = {
+    ...flags,
+    accountId: flags.accountId || runtime.connection.accountId
+  };
+
+  const client = new AibotWsClient(runtime.connection);
+  await client.connect();
+  try {
+    let result;
+    if (command === "query") {
+      result = await runQuery(client, options);
+    } else if (command === "send") {
+      result = await runSend(client, options);
+    } else if (command === "group") {
+      result = await runGroup(client, options);
+    } else if (command === "admin") {
+      result = await runAdmin(client, options);
+    } else if (command === "unsend") {
+      result = await runUnsend(client, options);
+    } else {
+      throw new Error(`Unsupported command: ${command}`);
+    }
+    console.log(JSON.stringify(result, null, 2));
+  } finally {
+    await client.disconnect();
+  }
+}
+
+main().catch((error) => {
+  console.error(JSON.stringify({
+    ok: false,
+    error: error instanceof Error ? error.message : String(error)
+  }, null, 2));
+  process.exit(1);
+});

package/shared/cli/targets.mjs

@@ -0,0 +1,119 @@
+function cleanText(value) {
+  return String(value ?? "").trim();
+}
+
+function isRouteSessionKey(value) {
+  return /^agent:main:grix:/i.test(cleanText(value));
+}
+
+function normalizeAibotSessionTarget(raw) {
+  return cleanText(raw).replace(/^grix:/i, "").replace(/^session:/i, "").trim();
+}
+
+export async function resolveAibotOutboundTarget({ client, accountId, to }) {
+  const rawTarget = cleanText(to);
+  if (!rawTarget) {
+    throw new Error("grix outbound target must be non-empty");
+  }
+  const normalizedTarget = normalizeAibotSessionTarget(rawTarget);
+  if (!normalizedTarget) {
+    throw new Error("grix outbound target must contain session_id or route_session_key");
+  }
+  if (!isRouteSessionKey(rawTarget) && !isRouteSessionKey(normalizedTarget)) {
+    if (normalizedTarget.includes(":")) {
+      const [sessionId, threadId] = normalizedTarget.split(/:(.+)/, 2);
+      return {
+        sessionId: cleanText(sessionId),
+        threadId: cleanText(threadId) || undefined,
+        rawTarget,
+        normalizedTarget,
+        resolveSource: "direct"
+      };
+    }
+    return {
+      sessionId: normalizedTarget,
+      threadId: undefined,
+      rawTarget,
+      normalizedTarget,
+      resolveSource: "direct"
+    };
+  }
+  const ack = await client.resolveSessionRoute("grix", accountId, isRouteSessionKey(rawTarget) ? rawTarget : normalizedTarget);
+  return {
+    sessionId: cleanText(ack.session_id),
+    threadId: undefined,
+    rawTarget,
+    normalizedTarget,
+    resolveSource: "sessionRouteMap"
+  };
+}
+
+export async function resolveAibotDeleteTarget({ client, accountId, sessionId, to, topic, currentChannelId }) {
+  const rawTarget = cleanText(sessionId) || cleanText(to) || cleanText(topic) || cleanText(currentChannelId);
+  if (!rawTarget) {
+    return "";
+  }
+  const resolved = await resolveAibotOutboundTarget({
+    client,
+    accountId,
+    to: rawTarget
+  });
+  return resolved.sessionId;
+}
+
+function normalizeMessageId(value) {
+  const normalized = cleanText(value);
+  return /^\d+$/.test(normalized) ? normalized : "";
+}
+
+export async function resolveSilentUnsendPlan(params) {
+  const targetMessageId = normalizeMessageId(params.messageId);
+  if (!targetMessageId) {
+    throw new Error("Grix unsend requires numeric messageId.");
+  }
+  const targetSessionId = await resolveAibotDeleteTarget({
+    client: params.client,
+    accountId: params.accountId,
+    sessionId: params.targetSessionId,
+    to: params.targetTo,
+    topic: params.targetTopic,
+    currentChannelId: params.currentChannelId
+  });
+  if (!targetSessionId) {
+    throw new Error("Grix unsend requires sessionId or to, or must run inside an active Grix conversation.");
+  }
+  const targetDelete = {
+    sessionId: targetSessionId,
+    messageId: targetMessageId
+  };
+  const currentMessageId = normalizeMessageId(params.currentMessageId);
+  if (!currentMessageId) {
+    return { targetDelete };
+  }
+  if (currentMessageId === targetMessageId) {
+    return {
+      targetDelete,
+      completionMessageId: currentMessageId
+    };
+  }
+  const currentChannelId = cleanText(params.currentChannelId);
+  if (!currentChannelId) {
+    return { targetDelete };
+  }
+  const currentSessionId = await resolveAibotDeleteTarget({
+    client: params.client,
+    accountId: params.accountId,
+    currentChannelId
+  });
+  if (!currentSessionId) {
+    throw new Error("Grix unsend could not resolve the current command message session.");
+  }
+  return {
+    targetDelete,
+    commandDelete: {
+      sessionId: currentSessionId,
+      messageId: currentMessageId
+    },
+    completionMessageId: currentMessageId
+  };
+}

package/shared/references/grix-card-links.md

@@ -0,0 +1,27 @@
+# Grix Card Links
+
+当你已经拿到准确的 `session_id` 时：
+
+- 会话卡片：
+
+```md
+[进入测试群](grix://card/conversation?session_id=<SESSION_ID>&session_type=group&title=<URI_ENCODED_TITLE>)
+```
+
+- Agent 资料卡：
+
+```md
+[查看 Agent 资料](grix://card/user_profile?user_id=<AGENT_ID>&peer_type=2&nickname=<URI_ENCODED_AGENT_NAME>&avatar_url=<URI_ENCODED_AVATAR_URL>)
+```
+
+- 安装状态卡：
+
+```md
+[安装进行中](grix://card/egg_install_status?install_id=<INSTALL_ID>&status=running&step=<STEP>&summary=<URI_ENCODED_SUMMARY>)
+```
+
+注意：
+
+1. 这类链接要单行
+2. 要单独作为一条消息发送
+3. 在 Hermes 里应优先用 `send_message` 发送，不要依赖普通 Grix 回复

package/shared/references/hermes-grix-config.md

@@ -0,0 +1,30 @@
+# Hermes Grix Runtime
+
+本项目不改 Hermes 内核，只复用 Hermes 已经配置好的 Grix 运行参数。
+
+共享 CLI 的参数来源顺序：
+
+1. 命令行显式参数
+2. 进程环境变量
+3. `HERMES_HOME/.env`
+4. `HERMES_HOME/config.yaml`
+
+至少需要这 3 个值：
+
+- `GRIX_ENDPOINT`
+- `GRIX_AGENT_ID`
+- `GRIX_API_KEY`
+
+默认 `HERMES_HOME`：
+
+```text
+~/.hermes
+```
+
+如果你在多 profile 或自定义目录下运行，先设置：
+
+```bash
+export HERMES_HOME=/path/to/hermes-home
+```
+
+共享 CLI 会自动复用同一套 Grix 凭证发起短连接请求，不要求额外手动登录。