@dhf-hermes/grix 0.1.0

package/grix-register/scripts/grix_auth.py

@@ -0,0 +1,487 @@
+#!/usr/bin/env python3
+import argparse
+import base64
+import json
+import os
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+
+DEFAULT_BASE_URL = "https://grix.dhf.pub"
+DEFAULT_TIMEOUT_SECONDS = 15
+
+
+def resolve_default_base_url() -> str:
+    return (os.environ.get("GRIX_WEB_BASE_URL", "") or "").strip() or DEFAULT_BASE_URL
+
+
+def derive_portal_url(raw_base_url: str) -> str:
+    base = (raw_base_url or "").strip() or resolve_default_base_url()
+    parsed = urllib.parse.urlparse(base)
+    if not parsed.scheme or not parsed.netloc:
+        raise ValueError(f"Invalid base URL: {base}")
+
+    path = parsed.path.rstrip("/")
+    if path.endswith("/v1"):
+        path = path[: -len("/v1")]
+
+    normalized = parsed._replace(path=path or "/", params="", query="", fragment="")
+    return urllib.parse.urlunparse(normalized).rstrip("/") + "/"
+
+
+class GrixAuthError(RuntimeError):
+    def __init__(self, message, status=0, code=-1, payload=None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.payload = payload
+
+
+def normalize_base_url(raw_base_url: str) -> str:
+    base = (raw_base_url or "").strip() or resolve_default_base_url()
+    parsed = urllib.parse.urlparse(base)
+    if not parsed.scheme or not parsed.netloc:
+        raise ValueError(f"Invalid base URL: {base}")
+
+    path = parsed.path.rstrip("/")
+    if not path:
+        path = "/v1"
+    elif not path.endswith("/v1"):
+        path = f"{path}/v1"
+
+    normalized = parsed._replace(path=path, params="", query="", fragment="")
+    return urllib.parse.urlunparse(normalized).rstrip("/")
+
+
+def request_json(method: str, path: str, base_url: str, body=None, headers=None):
+    api_base_url = normalize_base_url(base_url)
+    url = f"{api_base_url}{path if path.startswith('/') else '/' + path}"
+    data = None
+    final_headers = dict(headers or {})
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        final_headers["Content-Type"] = "application/json"
+
+    req = urllib.request.Request(url=url, data=data, headers=final_headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=DEFAULT_TIMEOUT_SECONDS) as resp:
+            status = getattr(resp, "status", 200)
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        status = exc.code
+        raw = exc.read().decode("utf-8", errors="replace")
+    except urllib.error.URLError as exc:
+        raise GrixAuthError(f"network error: {exc.reason}") from exc
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise GrixAuthError(f"invalid json response: {raw[:256]}", status=status) from exc
+
+    code = int(payload.get("code", -1))
+    msg = str(payload.get("msg", "")).strip() or "unknown error"
+    if status >= 400 or code != 0:
+        raise GrixAuthError(msg, status=status, code=code, payload=payload)
+
+    return {
+        "api_base_url": api_base_url,
+        "status": status,
+        "data": payload.get("data"),
+        "payload": payload,
+    }
+
+
+def maybe_write_captcha_image(b64s: str):
+    text = (b64s or "").strip()
+    if not text.startswith("data:image/"):
+        return ""
+
+    marker = ";base64,"
+    idx = text.find(marker)
+    if idx < 0:
+        return ""
+
+    encoded = text[idx + len(marker) :]
+    try:
+        content = base64.b64decode(encoded)
+    except Exception:
+        return ""
+
+    fd, path = tempfile.mkstemp(prefix="grix-captcha-", suffix=".png")
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(content)
+    except Exception:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+        return ""
+    return path
+
+
+def print_json(payload):
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+
+
+def build_auth_result(action: str, result: dict, base_url: str):
+    data = result.get("data") or {}
+    user = data.get("user") or {}
+    return {
+        "ok": True,
+        "action": action,
+        "api_base_url": result["api_base_url"],
+        "access_token": data.get("access_token", ""),
+        "refresh_token": data.get("refresh_token", ""),
+        "expires_in": data.get("expires_in", 0),
+        "user_id": user.get("id", ""),
+        "portal_url": derive_portal_url(base_url),
+        "data": data,
+    }
+
+
+def build_agent_result(action: str, result: dict):
+    data = result.get("data") or {}
+    agent_id = str(data.get("id", "")).strip()
+    api_endpoint = str(data.get("api_endpoint", "")).strip()
+    api_key = str(data.get("api_key", "")).strip()
+    agent_name = str(data.get("agent_name", "")).strip()
+    bind_local_payload = {
+        "agent_name": agent_name,
+        "agent_id": agent_id,
+        "api_endpoint": api_endpoint,
+        "api_key": api_key,
+    }
+    handoff_task = "\n".join(
+        [
+            "bind-local",
+            f"agent_name={agent_name}",
+            f"agent_id={agent_id}",
+            f"api_endpoint={api_endpoint}",
+            f"api_key={api_key}",
+            "do_not_create_remote_agent=true",
+        ]
+    )
+
+    return {
+        "ok": True,
+        "action": action,
+        "api_base_url": result["api_base_url"],
+        "agent_id": agent_id,
+        "agent_name": agent_name,
+        "provider_type": data.get("provider_type", 0),
+        "api_endpoint": api_endpoint,
+        "api_key": api_key,
+        "api_key_hint": data.get("api_key_hint", ""),
+        "session_id": data.get("session_id", ""),
+        "handoff": {
+            "target_tool": "grix_admin",
+            "task": handoff_task,
+            "bind_local": bind_local_payload,
+        },
+        "data": data,
+    }
+
+
+def login_with_credentials(base_url: str, account: str, password: str, device_id: str, platform: str):
+    result = request_json(
+        "POST",
+        "/auth/login",
+        base_url,
+        body={
+            "account": account,
+            "password": password,
+            "device_id": device_id,
+            "platform": platform,
+        },
+    )
+    return build_auth_result("login", result, base_url)
+
+
+def create_api_agent(base_url: str, access_token: str, agent_name: str, avatar_url: str):
+    request_body = {
+        "agent_name": agent_name.strip(),
+        "provider_type": 3,
+        "is_main": True,
+    }
+    normalized_avatar_url = (avatar_url or "").strip()
+    if normalized_avatar_url:
+        request_body["avatar_url"] = normalized_avatar_url
+
+    result = request_json(
+        "POST",
+        "/agents/create",
+        base_url,
+        body=request_body,
+        headers={
+            "Authorization": f"Bearer {access_token.strip()}",
+        },
+    )
+    return build_agent_result("create-api-agent", result)
+
+
+def list_agents(base_url: str, access_token: str):
+    result = request_json(
+        "GET",
+        "/agents/list",
+        base_url,
+        headers={
+            "Authorization": f"Bearer {access_token.strip()}",
+        },
+    )
+    data = result.get("data") or {}
+    items = data.get("list") or []
+    if not isinstance(items, list):
+        items = []
+    return items
+
+
+def rotate_api_agent_key(base_url: str, access_token: str, agent_id: str):
+    result = request_json(
+        "POST",
+        f"/agents/{str(agent_id).strip()}/api/key/rotate",
+        base_url,
+        body={},
+        headers={
+            "Authorization": f"Bearer {access_token.strip()}",
+        },
+    )
+    return build_agent_result("rotate-api-agent-key", result)
+
+
+def find_existing_api_agent(agents, agent_name: str):
+    normalized_name = (agent_name or "").strip()
+    if not normalized_name:
+        return None
+
+    for item in agents:
+        if not isinstance(item, dict):
+            continue
+        if str(item.get("agent_name", "")).strip() != normalized_name:
+            continue
+        if int(item.get("provider_type", 0) or 0) != 3:
+            continue
+        if int(item.get("status", 0) or 0) == 3:
+            continue
+        return item
+    return None
+
+
+def create_or_reuse_api_agent(
+    base_url: str,
+    access_token: str,
+    agent_name: str,
+    avatar_url: str,
+    prefer_existing: bool,
+    rotate_on_reuse: bool,
+):
+    if prefer_existing:
+        agents = list_agents(base_url, access_token)
+        existing = find_existing_api_agent(agents, agent_name)
+        if existing is not None:
+            if not rotate_on_reuse:
+                raise GrixAuthError(
+                    "existing provider_type=3 agent found but rotate-on-reuse is disabled; cannot obtain api_key safely",
+                    payload={"existing_agent": existing},
+                )
+            rotated = rotate_api_agent_key(base_url, access_token, str(existing.get("id", "")).strip())
+            rotated["source"] = "reused_existing_agent_with_rotated_key"
+            rotated["existing_agent"] = existing
+            return rotated
+
+    created = create_api_agent(base_url, access_token, agent_name, avatar_url)
+    created["source"] = "created_new_agent"
+    return created
+
+
+def default_device_id(platform: str) -> str:
+    normalized_platform = (platform or "").strip() or "web"
+    return f"{normalized_platform}_{uuid.uuid4()}"
+
+
+def handle_fetch_captcha(args):
+    result = request_json("GET", "/auth/captcha", args.base_url)
+    data = result.get("data") or {}
+    image_path = maybe_write_captcha_image(str(data.get("b64s", "")))
+    payload = {
+        "ok": True,
+        "action": "fetch-captcha",
+        "api_base_url": result["api_base_url"],
+        "captcha_id": data.get("captcha_id", ""),
+        "b64s": data.get("b64s", ""),
+    }
+    if image_path:
+        payload["captcha_image_path"] = image_path
+    print_json(payload)
+
+
+def handle_send_email_code(args):
+    scene = args.scene.strip()
+    payload = {
+        "email": args.email.strip(),
+        "scene": scene,
+    }
+
+    captcha_id = (args.captcha_id or "").strip()
+    captcha_value = (args.captcha_value or "").strip()
+    if scene in {"reset", "change_password"}:
+        if not captcha_id or not captcha_value:
+            raise GrixAuthError("captcha_id and captcha_value are required for reset/change_password")
+    if captcha_id:
+        payload["captcha_id"] = captcha_id
+    if captcha_value:
+        payload["captcha_value"] = captcha_value
+
+    result = request_json(
+        "POST",
+        "/auth/send-code",
+        args.base_url,
+        body=payload,
+    )
+    print_json(
+        {
+            "ok": True,
+            "action": "send-email-code",
+            "api_base_url": result["api_base_url"],
+            "data": result.get("data"),
+        }
+    )
+
+
+def handle_register(args):
+    platform = (args.platform or "").strip() or "web"
+    device_id = (args.device_id or "").strip() or default_device_id(platform)
+    result = request_json(
+        "POST",
+        "/auth/register",
+        args.base_url,
+        body={
+            "email": args.email.strip(),
+            "password": args.password.strip(),
+            "email_code": args.email_code.strip(),
+            "device_id": device_id,
+            "platform": platform,
+        },
+    )
+    print_json(build_auth_result("register", result, args.base_url))
+
+
+def handle_login(args):
+    account = (args.email or args.account or "").strip()
+    if not account:
+        raise GrixAuthError("either --email or --account is required")
+
+    platform = (args.platform or "").strip() or "web"
+    device_id = (args.device_id or "").strip() or default_device_id(platform)
+    print_json(
+        login_with_credentials(
+            args.base_url,
+            account,
+            args.password.strip(),
+            device_id,
+            platform,
+        )
+    )
+
+
+def handle_create_api_agent(args):
+    print_json(
+        create_or_reuse_api_agent(
+            args.base_url,
+            args.access_token.strip(),
+            args.agent_name.strip(),
+            args.avatar_url,
+            not bool(args.no_reuse_existing_agent),
+            not bool(args.no_rotate_key_on_reuse),
+        )
+    )
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description="Grix public auth API helper")
+    parser.add_argument(
+        "--base-url",
+        default=resolve_default_base_url(),
+        help="Grix web base URL (defaults to GRIX_WEB_BASE_URL or https://grix.dhf.pub)",
+    )
+
+    subparsers = parser.add_subparsers(dest="action", required=True)
+
+    fetch_captcha = subparsers.add_parser("fetch-captcha", help="Fetch captcha image")
+    fetch_captcha.set_defaults(handler=handle_fetch_captcha)
+
+    send_email_code = subparsers.add_parser("send-email-code", help="Send email verification code")
+    send_email_code.add_argument("--email", required=True)
+    send_email_code.add_argument("--scene", required=True, choices=["register", "reset", "change_password"])
+    send_email_code.add_argument("--captcha-id", default="")
+    send_email_code.add_argument("--captcha-value", default="")
+    send_email_code.set_defaults(handler=handle_send_email_code)
+
+    register = subparsers.add_parser("register", help="Register by email verification code")
+    register.add_argument("--email", required=True)
+    register.add_argument("--password", required=True)
+    register.add_argument("--email-code", required=True)
+    register.add_argument("--device-id", default="")
+    register.add_argument("--platform", default="web")
+    register.set_defaults(handler=handle_register)
+
+    login = subparsers.add_parser("login", help="Login and obtain tokens")
+    login_identity = login.add_mutually_exclusive_group(required=True)
+    login_identity.add_argument("--account")
+    login_identity.add_argument("--email")
+    login.add_argument("--password", required=True)
+    login.add_argument("--device-id", default="")
+    login.add_argument("--platform", default="web")
+    login.set_defaults(handler=handle_login)
+
+    create_api_agent_parser = subparsers.add_parser(
+        "create-api-agent",
+        help="Create a provider_type=3 API agent with a user access token",
+    )
+    create_api_agent_parser.add_argument("--access-token", required=True)
+    create_api_agent_parser.add_argument("--agent-name", required=True)
+    create_api_agent_parser.add_argument("--avatar-url", default="")
+    create_api_agent_parser.add_argument("--no-reuse-existing-agent", action="store_true")
+    create_api_agent_parser.add_argument("--no-rotate-key-on-reuse", action="store_true")
+    create_api_agent_parser.set_defaults(handler=handle_create_api_agent)
+
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        args.handler(args)
+    except GrixAuthError as exc:
+        print_json(
+            {
+                "ok": False,
+                "action": args.action,
+                "status": exc.status,
+                "code": exc.code,
+                "error": str(exc),
+                "payload": exc.payload,
+            }
+        )
+        raise SystemExit(1)
+    except Exception as exc:
+        print_json(
+            {
+                "ok": False,
+                "action": args.action,
+                "status": 0,
+                "code": -1,
+                "error": str(exc),
+            }
+        )
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

package/grix-update/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: grix-update
+description: 需要检查或执行 OpenClaw 的 Grix 插件升级时使用。适用于手动维护或 cron 维护场景，只通过 `openclaw` 官方 CLI 完成检查、升级、校验、可选重启和健康检查。
+---
+
+# Grix Update
+
+这个技能只做 OpenClaw 运维。
+
+## 输入
+
+建议把输入理解成：
+
+- `mode`: `check-only` / `apply-update` / `check-and-apply`
+- `plugin_id`: 默认 `grix`
+- `allow_restart`: 默认 `true`
+
+## 执行顺序
+
+优先使用 helper：
+
+```bash
+python3 scripts/grix_update.py --mode check-and-apply --plugin-id grix --allow-restart true --json
+```
+
+它内部会按当前 OpenClaw CLI 真实命令执行：
+
+1. `openclaw plugins inspect <plugin_id> --json`
+2. `openclaw plugins update <plugin_id> --dry-run`
+3. 按模式决定是否真正升级
+4. 升级后执行：
+   - `openclaw plugins doctor`
+   - `openclaw gateway restart`（仅在允许时）
+   - `openclaw health --json`
+
+## Guardrails
+
+- 不要改用非官方脚本
+- 如果 `allow_restart=false`，明确告诉上层运行态可能还是旧版本
+- 如果没有明确通知目标，不要自行猜消息发送目标
+
+## 推荐 cron 接法
+
+```text
+Use the grix-update skill with {"mode":"check-and-apply","plugin_id":"grix","notify_on":"never","allow_restart":true}
+```
+
+## 参考
+
+- [Cron Setup](references/cron-setup.md)

package/grix-update/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Grix Update"
+  short_description: "Check and apply OpenClaw Grix plugin updates."
+  default_prompt: "Use $grix-update to check and apply the latest Grix plugin update."
+
+policy:
+  allow_implicit_invocation: true

package/grix-update/references/cron-setup.md

@@ -0,0 +1,11 @@
+# Cron Setup
+
+如果你要把 `grix-update` 接到定时任务，推荐让上层 cron 直接调用这个技能，而不是把升级逻辑散在多个地方。
+
+建议输入：
+
+```json
+{"mode":"check-and-apply","plugin_id":"grix","allow_restart":true}
+```
+
+如果 cron 自己负责通知，技能侧不要再猜消息目标。

package/grix-update/scripts/grix_update.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Run OpenClaw Grix plugin update flow with a stable CLI surface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from typing import Any
+
+
+def run_command(cmd: list[str], *, check: bool = True) -> dict[str, Any]:
+    result = subprocess.run(cmd, text=True, capture_output=True)
+    payload = {
+        "cmd": cmd,
+        "code": result.returncode,
+        "stdout": (result.stdout or "").strip(),
+        "stderr": (result.stderr or "").strip(),
+    }
+    if check and result.returncode != 0:
+        raise RuntimeError(payload["stderr"] or payload["stdout"] or f"command failed: {' '.join(cmd)}")
+    return payload
+
+
+def build_plan(args: argparse.Namespace) -> list[list[str]]:
+    openclaw_cmd = args.openclaw
+    plugin_id = args.plugin_id
+    inspect_cmd = [openclaw_cmd, "plugins", "inspect", plugin_id, "--json"]
+    update_probe_cmd = [openclaw_cmd, "plugins", "update", plugin_id, "--dry-run"]
+    apply_cmd = [openclaw_cmd, "plugins", "update", plugin_id]
+    doctor_cmd = [openclaw_cmd, "plugins", "doctor"]
+    restart_cmd = [openclaw_cmd, "gateway", "restart"]
+    health_cmd = [openclaw_cmd, "health", "--json"]
+
+    if args.mode == "check-only":
+        return [inspect_cmd, update_probe_cmd]
+
+    if args.mode == "apply-update":
+        commands = [inspect_cmd, apply_cmd, doctor_cmd]
+        if args.allow_restart:
+            commands.append(restart_cmd)
+        commands.append(health_cmd)
+        return commands
+
+    if args.mode == "check-and-apply":
+        commands = [inspect_cmd, update_probe_cmd, apply_cmd, doctor_cmd]
+        if args.allow_restart:
+            commands.append(restart_cmd)
+        commands.append(health_cmd)
+        return commands
+
+    raise RuntimeError(f"unsupported mode: {args.mode}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the Grix/OpenClaw plugin update workflow.")
+    parser.add_argument("--mode", choices=["check-only", "apply-update", "check-and-apply"], default="check-and-apply")
+    parser.add_argument("--plugin-id", default="grix")
+    parser.add_argument("--allow-restart", default="true", choices=["true", "false"])
+    parser.add_argument("--openclaw", default="openclaw")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+    args.allow_restart = args.allow_restart == "true"
+
+    try:
+        commands = build_plan(args)
+        results: list[dict[str, Any]] = []
+        if not args.dry_run:
+            for cmd in commands:
+                results.append(run_command(cmd))
+        payload = {
+            "ok": True,
+            "mode": args.mode,
+            "plugin_id": args.plugin_id,
+            "allow_restart": args.allow_restart,
+            "dry_run": bool(args.dry_run),
+            "commands": commands,
+            "results": results,
+        }
+        if args.json:
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+        else:
+            print(f"mode={args.mode} plugin_id={args.plugin_id} dry_run={args.dry_run}")
+            for cmd in commands:
+                print("$ " + " ".join(cmd))
+        return 0
+    except Exception as exc:  # noqa: BLE001
+        payload = {"ok": False, "error": str(exc)}
+        if args.json:
+            print(json.dumps(payload, ensure_ascii=False, indent=2), file=sys.stderr)
+        else:
+            print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())