nodus-wechat 0.2.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # nodus-wechat
 
-CLI skeleton for the upcoming Nodus WeChat local agent installer.
+CLI installer for Nodus WeChat, Hermes common settings, and the local OpeniLink webhook runtime.
 
 Run:
 
@@ -11,25 +11,79 @@ npx nodus-wechat
 ## Commands
 
 ```sh
-npx nodus-wechat setup --api-key <your-sub2api-key>
+npx nodus-wechat setup
+npx nodus-wechat setup --install-hermes
+npx nodus-wechat install-hermes
 npx nodus-wechat doctor
 npx nodus-wechat start
+npx nodus-wechat status
+npx nodus-wechat logs
+npx nodus-wechat stop
 npx nodus-wechat uninstall --yes
 ```
 
+For a server-bound OpeniLink origin:
+
+```sh
+npx nodus-wechat setup \
+  --openilink-origin http://192.220.25.138:9800 \
+  --openilink-rp-id 192.220.25.138
+```
+
+`setup` prompts for the AstraGate API key when `--api-key` is not supplied.
+The default gateway base URL is `https://api.nodus.sbs/`.
+Use `--install-hermes` or `install-hermes` to run the official Hermes installer
+with `--skip-setup` and the same Hermes home used by this CLI.
+
 ## Current behavior
 
 - Creates local configuration at `~/.nodus-wechat/config.json`.
-- Stores sub2api base URL, api key, model, and local runtime status fields.
-- Checks Node.js and local configuration with `doctor`.
-- Reads configuration with `start` and reports that runtime integration is still pending.
+- Can install Hermes Agent CLI through the official NousResearch installer.
+- Installs the OpeniLink + webhook POC runtime at `~/.nodus-wechat/runtime`.
+- Writes Hermes common settings to `~/.hermes/config.yaml`.
+- Writes the AstraGate key to `~/.hermes/.env` as `ASTRAGATE_API_KEY`.
+- Writes runtime `.env`, Docker Compose, webhook server, helper scripts, and the OpeniLink reply plugin.
+- Stores gateway base URL, api key, model, Hermes paths, OpeniLink origin, webhook port, and runtime path.
+- Checks Node.js, local configuration, Hermes files, runtime files, Docker Compose availability, Hermes CLI availability, and WeChat app detection with `doctor`.
+- Starts/stops the local runtime through Docker Compose.
 - Removes only files created by this CLI with `uninstall --yes`.
 
 ## Current non-goals
 
-- Does not install Hermes.
-- Does not install or run iLink.
-- Does not automate, inject into, read, or control WeChat.
-- Does not start a daemon, LaunchAgent, service, or background worker.
+- Does not run a third-party installer unless `--install-hermes` or `install-hermes` is explicitly requested.
+- Does not automate, inject into, read, or control WeChat directly.
+- Does not start a daemon, LaunchAgent, or background worker outside Docker Compose.
+- Does not redeem real CDKs or mutate sub2api accounts; the bundled webhook keeps the existing dry-run POC boundary.
+
+## Runtime wiring
+
+After `setup` and `start`, open the OpeniLink Hub shown by the CLI. In the Channel
+Webhook settings, use:
+
+```text
+Webhook URL: http://poc-webhook:9811/webhook
+```
+
+If `--webhook-token` was configured, set the Channel Webhook auth header to:
+
+```text
+Authorization: Bearer <the same token>
+```
+
+The bundled webhook responds to:
+
+```text
+/ping
+/status plus
+/add-plus-dry-run
+```
+
+## Publish
+
+```sh
+npm run release:check
+npm publish
+```
 
-The real installer will be released in a later version.
+The package is configured for public npm access. If npm reports `E401`, run
+`npm login` first.

package/bin/nodus-wechat.js

@@ -5,10 +5,16 @@
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
+const childProcess = require("node:child_process");
 
-const VERSION = "0.2";
-const DEFAULT_BASE_URL = "https://api.nodus.sbs/v1";
+const VERSION = "0.5";
+const DEFAULT_BASE_URL = "https://api.nodus.sbs/";
 const DEFAULT_MODEL = "gpt-5.5";
+const DEFAULT_OPENILINK_ORIGIN = "http://localhost:9800";
+const DEFAULT_OPENILINK_RP_ID = "localhost";
+const DEFAULT_OPENILINK_PORT = 9800;
+const DEFAULT_WEBHOOK_PORT = 9811;
+const TEMPLATE_DIR = path.join(__dirname, "..", "templates", "wechat-agent-poc");
 
 function configHome() {
   return process.env.NODUS_WECHAT_HOME || path.join(os.homedir(), ".nodus-wechat");
@@ -18,24 +24,40 @@ function configPath() {
   return path.join(configHome(), "config.json");
 }
 
+function hermesHome() {
+  return process.env.NODUS_HERMES_HOME || path.join(os.homedir(), ".hermes");
+}
+
 function printHelp() {
   console.log(`nodus-wechat ${VERSION}
 
-Local CLI skeleton for the upcoming Nodus WeChat Agent installer.
+Local CLI installer for Nodus WeChat, Hermes settings, and the OpeniLink webhook runtime.
 
 Usage:
   nodus-wechat setup [--api-key <key>] [--base-url <url>] [--model <model>]
+                      [--runtime-dir <path>] [--openilink-origin <url>]
+                      [--openilink-rp-id <id>] [--webhook-port <port>]
+                      [--webhook-token <token>] [--install-hermes]
+  nodus-wechat install-hermes
   nodus-wechat doctor
   nodus-wechat start
+  nodus-wechat status
+  nodus-wechat logs
+  nodus-wechat stop
   nodus-wechat uninstall --yes
 
 Commands:
-  setup      Create or update local configuration.
-  doctor     Check local prerequisites and configuration.
-  start      Read configuration and show the current stub runtime status.
-  uninstall  Remove files created by this CLI.
-
-This version does not install Hermes, iLink, or control WeChat.`);
+  setup           Create or update local configuration and runtime files.
+  install-hermes  Install Hermes Agent CLI with the official installer.
+  doctor          Check local prerequisites and configuration.
+  start           Start the local OpeniLink + webhook runtime with Docker Compose.
+  status          Show Docker Compose service status.
+  logs            Follow webhook logs.
+  stop            Stop the local runtime.
+  uninstall       Remove files created by this CLI.
+
+This version installs an OpeniLink webhook POC runtime. It does not inject into,
+read, or control WeChat directly.`);
 }
 
 function parseArgs(argv) {
@@ -49,7 +71,7 @@ function parseArgs(argv) {
     }
 
     const key = item.slice(2);
-    if (key === "help" || key === "yes") {
+    if (key === "help" || key === "yes" || key === "install-hermes") {
       result[key] = true;
       continue;
     }
@@ -77,9 +99,204 @@ function writeConfig(config) {
   });
 }
 
+function parsePositiveInt(value, name) {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid value for --${name}: ${value}`);
+  }
+  return parsed;
+}
+
+function parseDotEnv(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+
+  const result = {};
+  for (const line of fs.readFileSync(filePath, "utf8").split(/\r?\n/)) {
+    if (!line || line.trimStart().startsWith("#") || !line.includes("=")) {
+      continue;
+    }
+    const index = line.indexOf("=");
+    result[line.slice(0, index)] = line.slice(index + 1);
+  }
+  return result;
+}
+
+function promptApiKey() {
+  if (process.stdin.isTTY && process.platform !== "win32") {
+    const result = childProcess.spawnSync(
+      "sh",
+      [
+        "-c",
+        [
+          'printf "Paste AstraGate API Key: " > /dev/tty',
+          "stty -echo < /dev/tty",
+          "IFS= read -r key < /dev/tty",
+          "status=$?",
+          "stty echo < /dev/tty",
+          'printf "\\n" > /dev/tty',
+          'printf "%s" "$key"',
+          "exit $status",
+        ].join("; "),
+      ],
+      { encoding: "utf8" },
+    );
+    if (!result.error && result.status === 0) {
+      return (result.stdout || "").trim();
+    }
+  }
+
+  process.stderr.write("Paste AstraGate API Key: ");
+  return fs.readFileSync(0, "utf8").split(/\r?\n/)[0].trim();
+}
+
+function resolveApiKey(options, existing) {
+  const apiKey = options["api-key"] || process.env.NODUS_WECHAT_API_KEY || existing.sub2api?.apiKey || "";
+  if (apiKey) {
+    return apiKey;
+  }
+
+  const prompted = promptApiKey();
+  if (!prompted) {
+    throw new Error("AstraGate API Key is required. Rerun setup and paste the key, or pass --api-key <key>.");
+  }
+  return prompted;
+}
+
+function yamlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function buildHermesConfig(config) {
+  return [
+    "_config_version: 10",
+    "model:",
+    `  default: ${yamlString(config.agent.model)}`,
+    '  provider: "custom"',
+    `  base_url: ${yamlString(config.sub2api.baseUrl)}`,
+    '  api_key: "${ASTRAGATE_API_KEY}"',
+    "agent:",
+    `  reasoning_effort: ${yamlString(config.agent.reasoningEffort)}`,
+    "terminal:",
+    '  backend: "local"',
+    '  cwd: "."',
+    "approvals:",
+    '  mode: "manual"',
+    "toolsets:",
+    '  - "all"',
+    "display:",
+    '  tool_progress: "all"',
+    "compression:",
+    "  enabled: true",
+    "",
+  ].join("\n");
+}
+
+function backupIfExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  fs.copyFileSync(filePath, `${filePath}.bak-${stamp}`);
+}
+
+function writeHermesEnv(envPath, apiKey) {
+  const existingLines = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8").split(/\r?\n/) : [];
+  const kept = existingLines.filter((line) => !line.startsWith("ASTRAGATE_API_KEY=") && line.trim() !== "");
+  kept.push(`ASTRAGATE_API_KEY=${apiKey}`);
+  fs.writeFileSync(envPath, `${kept.join("\n")}\n`, { mode: 0o600 });
+}
+
+function installHermesConfig(config) {
+  fs.mkdirSync(config.hermes.home, { recursive: true, mode: 0o700 });
+  backupIfExists(config.hermes.configPath);
+  backupIfExists(config.hermes.envPath);
+  fs.writeFileSync(config.hermes.configPath, buildHermesConfig(config), { mode: 0o600 });
+  writeHermesEnv(config.hermes.envPath, config.sub2api.apiKey);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+function hermesInstallCommand() {
+  return (
+    process.env.NODUS_WECHAT_HERMES_INSTALL_COMMAND ||
+    "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s --"
+  );
+}
+
+function runHermesInstaller(hermesDir) {
+  const args = ["--skip-setup", "--hermes-home", hermesDir];
+  const command = `${hermesInstallCommand()} ${args.map(shellQuote).join(" ")}`;
+  const result = childProcess.spawnSync(command, {
+    shell: true,
+    stdio: "inherit",
+    env: { ...process.env, HERMES_HOME: hermesDir },
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`Hermes installer failed with exit code ${result.status}`);
+  }
+}
+
+function writeRuntimeEnv(config, options) {
+  const envPath = path.join(config.runtime.dir, ".env");
+  const existing = parseDotEnv(envPath);
+  const webhookToken = options["webhook-token"] ?? existing.POC_WEBHOOK_TOKEN ?? "";
+  const lines = [
+    "OPENILINK_PORT=" + config.openilink.port,
+    "OPENILINK_DATA_DIR=" + path.join(config.runtime.dir, "openilink-hub-data"),
+    "POC_WEBHOOK_PORT=" + config.webhook.port,
+    "POC_WEBHOOK_BIND=127.0.0.1",
+    "",
+    "OPENILINK_PUBLIC_ORIGIN=" + config.openilink.publicOrigin,
+    "OPENILINK_RP_ID=" + config.openilink.rpId,
+    "",
+    "POC_WEBHOOK_TOKEN=" + webhookToken,
+    "",
+  ];
+
+  fs.writeFileSync(envPath, lines.join("\n"), { mode: 0o600 });
+}
+
+function installRuntime(config, options) {
+  fs.mkdirSync(config.runtime.dir, { recursive: true, mode: 0o700 });
+  fs.cpSync(TEMPLATE_DIR, config.runtime.dir, {
+    recursive: true,
+    force: true,
+    errorOnExist: false,
+  });
+
+  const scriptsDir = path.join(config.runtime.dir, "scripts");
+  if (fs.existsSync(scriptsDir)) {
+    for (const fileName of fs.readdirSync(scriptsDir)) {
+      if (fileName.endsWith(".sh")) {
+        fs.chmodSync(path.join(scriptsDir, fileName), 0o755);
+      }
+    }
+  }
+
+  writeRuntimeEnv(config, options);
+}
+
 function createConfig(options) {
   const existing = fs.existsSync(configPath()) ? readConfig() : {};
   const now = new Date().toISOString();
+  const runtimeDir = options["runtime-dir"] || existing.runtime?.dir || path.join(configHome(), "runtime");
+  const openilinkPort = parsePositiveInt(options["openilink-port"], "openilink-port") || existing.openilink?.port || DEFAULT_OPENILINK_PORT;
+  const webhookPort = parsePositiveInt(options["webhook-port"], "webhook-port") || existing.webhook?.port || DEFAULT_WEBHOOK_PORT;
+  const hermesDir = options["hermes-home"] || existing.hermes?.home || hermesHome();
+  const apiKey = resolveApiKey(options, existing);
 
   return {
     schemaVersion: 1,
@@ -87,7 +304,7 @@ function createConfig(options) {
     updatedAt: now,
     sub2api: {
       baseUrl: options["base-url"] || existing.sub2api?.baseUrl || DEFAULT_BASE_URL,
-      apiKey: options["api-key"] || process.env.NODUS_WECHAT_API_KEY || existing.sub2api?.apiKey || "",
+      apiKey,
     },
     agent: {
       model: options.model || existing.agent?.model || DEFAULT_MODEL,
@@ -95,12 +312,30 @@ function createConfig(options) {
       approvalMode: existing.agent?.approvalMode || "wechat-confirm",
     },
     wechat: {
-      connector: "ilink",
+      connector: "openilink",
       appPath: existing.wechat?.appPath || null,
       status: "pending",
     },
+    openilink: {
+      publicOrigin: options["openilink-origin"] || existing.openilink?.publicOrigin || DEFAULT_OPENILINK_ORIGIN,
+      rpId: options["openilink-rp-id"] || existing.openilink?.rpId || DEFAULT_OPENILINK_RP_ID,
+      port: openilinkPort,
+    },
+    webhook: {
+      port: webhookPort,
+      bind: "127.0.0.1",
+      tokenConfigured: Boolean(options["webhook-token"] || existing.webhook?.tokenConfigured),
+    },
+    runtime: {
+      status: "installed",
+      dir: runtimeDir,
+      composeFile: path.join(runtimeDir, "docker-compose.yml"),
+    },
     hermes: {
-      status: "not_installed",
+      status: "configured",
+      home: hermesDir,
+      configPath: path.join(hermesDir, "config.yaml"),
+      envPath: path.join(hermesDir, ".env"),
     },
     ilink: {
       status: "not_installed",
@@ -110,15 +345,34 @@ function createConfig(options) {
 
 function setup(options) {
   const config = createConfig(options);
+  installRuntime(config, options);
+  installHermesConfig(config);
+  if (options["install-hermes"]) {
+    runHermesInstaller(config.hermes.home);
+  }
   writeConfig(config);
 
   console.log(`Config written: ${configPath()}`);
-  console.log(`Base URL: ${config.sub2api.baseUrl}`);
-  console.log(`Model: ${config.agent.model}`);
-  if (!config.sub2api.apiKey) {
-    console.log("Warning: sub2api api key is empty. Run setup again with --api-key when ready.");
+  console.log(`Runtime installed: ${config.runtime.dir}`);
+  console.log(`Hermes configured: ${config.hermes.configPath}`);
+  if (!options["install-hermes"]) {
+    console.log("Hermes CLI install skipped. Run `nodus-wechat install-hermes` if `hermes` is not installed.");
   }
-  console.log("Hermes/iLink integration is pending in this CLI version.");
+  console.log(`Gateway Base URL: ${config.sub2api.baseUrl}`);
+  console.log(`Model: ${config.agent.model}`);
+  console.log(`OpeniLink Hub: ${config.openilink.publicOrigin}`);
+  console.log(`Webhook URL for OpeniLink: http://poc-webhook:${config.webhook.port}/webhook`);
+  console.log("Run `nodus-wechat start` to start the local runtime.");
+}
+
+function installHermes() {
+  const config = fs.existsSync(configPath())
+    ? readConfig()
+    : { hermes: { home: hermesHome() } };
+  const hermesDir = config.hermes?.home || hermesHome();
+  runHermesInstaller(hermesDir);
+  console.log(`Hermes installer completed for: ${hermesDir}`);
+  return 0;
 }
 
 function doctor() {
@@ -154,7 +408,35 @@ function doctor() {
       ok = false;
       console.log("sub2api: failed (api key missing)");
     }
-    console.log(`hermes: ${config.hermes?.status || "not_installed"}`);
+    if (config.runtime?.dir && fs.existsSync(path.join(config.runtime.dir, "docker-compose.yml"))) {
+      console.log(`runtime: installed (${config.runtime.dir})`);
+    } else {
+      ok = false;
+      console.log(`runtime: missing (${config.runtime?.dir || path.join(configHome(), "runtime")})`);
+    }
+    const docker = dockerComposeAvailable();
+    if (docker.ok) {
+      console.log(`docker compose: ok (${docker.version})`);
+    } else {
+      console.log("docker compose: missing (needed for `nodus-wechat start`)");
+    }
+    console.log(`openilink: ${config.openilink?.publicOrigin || DEFAULT_OPENILINK_ORIGIN}`);
+    console.log(`webhook: http://127.0.0.1:${config.webhook?.port || DEFAULT_WEBHOOK_PORT}/health`);
+    const hermesConfigPath = config.hermes?.configPath || path.join(hermesHome(), "config.yaml");
+    const hermesEnvPath = config.hermes?.envPath || path.join(hermesHome(), ".env");
+    const hermesEnv = parseDotEnv(hermesEnvPath);
+    if (fs.existsSync(hermesConfigPath) && hermesEnv.ASTRAGATE_API_KEY) {
+      console.log(`hermes: configured (${hermesConfigPath})`);
+    } else {
+      ok = false;
+      console.log(`hermes: missing (${hermesConfigPath})`);
+    }
+    const hermesCli = childProcess.spawnSync("hermes", ["--version"], { encoding: "utf8" });
+    if (hermesCli.error || hermesCli.status !== 0) {
+      console.log("hermes cli: missing (config is ready; install Hermes before using it)");
+    } else {
+      console.log(`hermes cli: ok (${(hermesCli.stdout || hermesCli.stderr || "").trim()})`);
+    }
     console.log(`ilink: ${config.ilink?.status || "not_installed"}`);
     console.log(`wechat: ${findWeChatApp() || "not detected"}`);
   } catch (error) {
@@ -170,20 +452,96 @@ function findWeChatApp() {
   return candidates.find((candidate) => fs.existsSync(candidate)) || null;
 }
 
-function start() {
+function dockerComposeAvailable() {
+  const result = childProcess.spawnSync("docker", ["compose", "version"], {
+    encoding: "utf8",
+  });
+  if (result.error || result.status !== 0) {
+    return { ok: false };
+  }
+
+  return {
+    ok: true,
+    version: (result.stdout || result.stderr || "").trim(),
+  };
+}
+
+function loadRuntimeConfig() {
   if (!fs.existsSync(configPath())) {
     console.error(`Config missing: ${configPath()}`);
     console.error("Run: nodus-wechat setup --api-key <key>");
-    return 1;
+    return null;
   }
 
   const config = readConfig();
-  console.log("Nodus WeChat runtime stub");
-  console.log(`Config: ${configPath()}`);
-  console.log(`Model: ${config.agent?.model || DEFAULT_MODEL}`);
-  console.log("Hermes/iLink are not integrated in this version.");
-  console.log("No WeChat automation, login access, or message handling has been started.");
-  return 0;
+  const runtimeDir = config.runtime?.dir || path.join(configHome(), "runtime");
+  if (!fs.existsSync(path.join(runtimeDir, "docker-compose.yml"))) {
+    console.error(`Runtime missing: ${runtimeDir}`);
+    console.error("Run: nodus-wechat setup");
+    return null;
+  }
+
+  return { ...config, runtime: { ...config.runtime, dir: runtimeDir } };
+}
+
+function runDockerCompose(config, args, stdio = "inherit") {
+  const docker = dockerComposeAvailable();
+  if (!docker.ok) {
+    console.error("Docker Compose is required for this command.");
+    console.error("Install Docker Desktop or OrbStack, then rerun `nodus-wechat start`.");
+    return 1;
+  }
+
+  const result = childProcess.spawnSync("docker", ["compose", ...args], {
+    cwd: config.runtime.dir,
+    stdio,
+    encoding: stdio === "pipe" ? "utf8" : undefined,
+  });
+
+  if (stdio === "pipe" && result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (stdio === "pipe" && result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  return result.status || 0;
+}
+
+function start() {
+  const config = loadRuntimeConfig();
+  if (!config) {
+    return 1;
+  }
+
+  return runDockerCompose(config, ["up", "-d"]);
+}
+
+function status() {
+  const config = loadRuntimeConfig();
+  if (!config) {
+    return 1;
+  }
+
+  return runDockerCompose(config, ["ps"]);
+}
+
+function logs() {
+  const config = loadRuntimeConfig();
+  if (!config) {
+    return 1;
+  }
+
+  return runDockerCompose(config, ["logs", "-f", "poc-webhook"]);
+}
+
+function stop() {
+  const config = loadRuntimeConfig();
+  if (!config) {
+    return 1;
+  }
+
+  return runDockerCompose(config, ["down"]);
 }
 
 function uninstall(options) {
@@ -212,21 +570,42 @@ function main() {
     return 0;
   }
 
-  if (command === "setup") {
-    setup(args);
-    return 0;
-  }
+  try {
+    if (command === "setup") {
+      setup(args);
+      return 0;
+    }
 
-  if (command === "doctor") {
-    return doctor();
-  }
+    if (command === "install-hermes") {
+      return installHermes();
+    }
 
-  if (command === "start") {
-    return start();
-  }
+    if (command === "doctor") {
+      return doctor();
+    }
+
+    if (command === "start") {
+      return start();
+    }
+
+    if (command === "status") {
+      return status();
+    }
 
-  if (command === "uninstall") {
-    return uninstall(args);
+    if (command === "logs") {
+      return logs();
+    }
+
+    if (command === "stop") {
+      return stop();
+    }
+
+    if (command === "uninstall") {
+      return uninstall(args);
+    }
+  } catch (error) {
+    console.error(error.message);
+    return 1;
   }
 
   console.error(`Unknown command: ${command}`);

package/package.json

@@ -1,17 +1,23 @@
 {
   "name": "nodus-wechat",
-  "version": "0.2.0",
-  "description": "CLI skeleton for the upcoming Nodus WeChat local agent installer.",
+  "version": "0.5.0",
+  "description": "CLI installer for Nodus WeChat, Hermes, and the local OpeniLink webhook runtime.",
   "license": "MIT",
   "private": false,
   "bin": {
     "nodus-wechat": "bin/nodus-wechat.js"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "release:check": "npm test && npm pack --dry-run",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "files": [
     "bin",
+    "templates",
     "README.md",
     "LICENSE"
   ],

package/templates/wechat-agent-poc/.env.example

@@ -0,0 +1,22 @@
+# Copy to .env before starting the POC.
+#
+# For local verification on this Mac:
+# OPENILINK_PUBLIC_ORIGIN=http://localhost:9800
+# OPENILINK_RP_ID=localhost
+#
+# For the 192 server, replace with the server address you open in the browser:
+# OPENILINK_PUBLIC_ORIGIN=http://192.220.25.138:9800
+# OPENILINK_RP_ID=192.220.25.138
+
+OPENILINK_PORT=9800
+OPENILINK_DATA_DIR=/opt/sub2api/openilink-hub-data
+POC_WEBHOOK_PORT=9811
+POC_WEBHOOK_BIND=127.0.0.1
+
+# WebAuthn / browser origin. For 192 deployment, use the 192 values below.
+OPENILINK_PUBLIC_ORIGIN=http://192.220.25.138:9800
+OPENILINK_RP_ID=192.220.25.138
+
+# Optional. If set, configure the OpeniLink Channel Webhook auth as:
+# Authorization: Bearer <this value>
+POC_WEBHOOK_TOKEN=

package/templates/wechat-agent-poc/README.md

@@ -0,0 +1,164 @@
+# WeChat Agent POC
+
+这个 POC 只验证三件事：
+
+1. 能不能扫码绑定微信机器人身份。
+2. 能不能把机器人/微信号拉进普通微信群。
+3. 群里发消息后，事件能不能进入 webhook，并能不能回复到群里。
+
+先不要接真实 CDK。这里的 `/add-plus-dry-run` 只返回假任务，确认通道可用后再接 `sub2api` 的真实加号工具。
+
+## Start
+
+```bash
+cd "/Users/zyaire/Documents/API Router/sub2api/deploy/wechat-agent-poc"
+cp .env.example .env
+./scripts/start.sh
+```
+
+打开：
+
+```text
+http://192.220.25.138:9800
+```
+
+本机开发时再把 `.env` 改回：
+
+```dotenv
+OPENILINK_PUBLIC_ORIGIN=http://localhost:9800
+OPENILINK_RP_ID=localhost
+```
+
+## OpeniLink Setup
+
+当前 192 POC 已经完成基础配置：
+
+```text
+Bot ID: 00612ba4-f96b-4f19-ad75-c3913e92cf75
+Channel: Sub2API POC
+Webhook URL: http://poc-webhook:9811/webhook
+Webhook script: plugins/reply-from-webhook.js
+AI auto-reply: disabled
+Data dir: /opt/sub2api/openilink-hub-data
+```
+
+如果重新从零部署，在 OpeniLink Hub 后台完成：
+
+1. 注册第一个账号，第一个注册用户会成为管理员。
+2. 进入 Bot 管理，扫码绑定微信机器人身份。
+3. 在这个 Bot 下创建一个 Channel。
+4. 在 Channel 设置中启用 Webhook。
+5. Webhook URL 填 `http://poc-webhook:9811/webhook`。
+6. 如果 `.env` 设置了 `POC_WEBHOOK_TOKEN`，认证方式选 Bearer Token，并填入同一个 token。
+7. 在 Channel 的 Webhook 插件里安装 `plugins/reply-from-webhook.js` 的内容。
+8. 关闭内置 AI 自动回复，先只测 Webhook 通道。
+
+OpeniLink 官方文档里，Webhook 会把消息 POST 到 URL；要把 webhook JSON 响应里的 `reply` 发回微信，需要响应后插件调用 `ctx.reply()`。
+
+## Verification
+
+先私聊机器人：
+
+```text
+/ping
+/status plus
+/add-plus-dry-run
+```
+
+再拉进普通微信群，群里发：
+
+```text
+@机器人 /ping
+@机器人 /status plus
+@机器人 /add-plus-dry-run
+```
+
+如果群聊不支持 `@机器人`，也测试直接发：
+
+```text
+/ping
+```
+
+## Logs
+
+本地探测 webhook：
+
+```bash
+./scripts/probe-webhook.sh
+```
+
+查看 webhook 是否收到事件：
+
+```bash
+./scripts/logs.sh
+```
+
+查看整体状态：
+
+```bash
+./scripts/status.sh
+```
+
+## Deploy To 192
+
+如果本机能 SSH 到 192：
+
+```bash
+./scripts/deploy-to-192.sh
+```
+
+默认目标：
+
+```text
+root@192.220.25.138:/opt/sub2api/wechat-agent-poc
+```
+
+如果服务器没有 Docker，并且是 Ubuntu：
+
+```bash
+ssh root@192.220.25.138
+cd /opt/sub2api/wechat-agent-poc
+./scripts/install-prereqs-ubuntu.sh
+./scripts/start.sh
+```
+
+关键字段：
+
+```text
+payload.type
+payload.content
+payload.sender.user_id
+payload.sessionID
+payload.channel_id
+```
+
+如果私聊能收、群里收不到，说明 Agent 层没有问题，限制在微信/iLink 群事件投递。不同 OpeniLink 版本的群字段可能叫 `group`、`room` 或只体现在 `sessionID` 里，所以先以日志里的实际 payload 为准。
+
+## Pass Criteria
+
+这几项都通过，再接 Hermes 和真实 sub2api 加号流程：
+
+```text
+私聊 /ping 有回复
+群里能看到机器人身份
+群里 @机器人 /ping 有回复
+webhook 日志里出现 group.id
+webhook 日志里 sender.id 稳定
+重复发送不会多次触发异常回复
+```
+
+## Next Step
+
+真实加号流程建议只暴露成受控工具：
+
+```text
+validate_cdk
+redeem_cdk_to_plus_account
+import_account_to_pool
+assign_group("plus")
+healthcheck_account
+enable_account
+report_result_to_wechat
+```
+
+CDK 不建议发在群里。群里只触发任务或查询状态，真实 CDK 走私聊或 sub2api 管理页面。

package/templates/wechat-agent-poc/docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  openilink:
+    image: ghcr.io/openilink/openilink-hub:latest
+    container_name: sub2api-openilink-poc
+    restart: unless-stopped
+    working_dir: /data
+    ports:
+      - "${OPENILINK_PORT:-9800}:9800"
+    environment:
+      RP_ORIGIN: "${OPENILINK_PUBLIC_ORIGIN:-http://localhost:9800}"
+      RP_ID: "${OPENILINK_RP_ID:-localhost}"
+    volumes:
+      - "${OPENILINK_DATA_DIR:-/opt/sub2api/openilink-hub-data}:/var/lib/openilink-hub"
+
+  poc-webhook:
+    image: python:3.12-alpine
+    container_name: sub2api-wechat-poc-webhook
+    restart: unless-stopped
+    working_dir: /app
+    command: ["python", "server.py"]
+    ports:
+      - "${POC_WEBHOOK_BIND:-127.0.0.1}:${POC_WEBHOOK_PORT:-9811}:9811"
+    environment:
+      POC_WEBHOOK_TOKEN: "${POC_WEBHOOK_TOKEN:-}"
+    volumes:
+      - ./poc-webhook:/app:ro

package/templates/wechat-agent-poc/plugins/reply-from-webhook.js

@@ -0,0 +1,27 @@
+// ==UserScript==
+// @name         Sub2API POC Reply From Webhook
+// @description  Replies to WeChat with the JSON reply field returned by the POC webhook.
+// @version      1.0.0
+// @match        *
+// @grant        none
+// @timeout      3000
+// ==/UserScript==
+
+function onResponse(ctx) {
+  if (!ctx.res || ctx.res.status < 200 || ctx.res.status >= 300) {
+    ctx.reply("POC webhook failed. Check docker compose logs -f poc-webhook.");
+    return;
+  }
+
+  let body = {};
+  try {
+    body = JSON.parse(ctx.res.body || "{}");
+  } catch (err) {
+    ctx.reply("POC webhook returned non-JSON response.");
+    return;
+  }
+
+  if (body.reply) {
+    ctx.reply(String(body.reply));
+  }
+}

package/templates/wechat-agent-poc/poc-webhook/server.py

@@ -0,0 +1,118 @@
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json
+import os
+import time
+
+
+def _compact(value):
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def _payload_value(payload, *paths):
+    for path in paths:
+        cur = payload
+        ok = True
+        for key in path:
+            if isinstance(cur, dict) and key in cur:
+                cur = cur[key]
+            else:
+                ok = False
+                break
+        if ok and cur not in (None, ""):
+            return cur
+    return None
+
+
+class Handler(BaseHTTPRequestHandler):
+    def _send_json(self, status, payload):
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self):
+        if self.path == "/health":
+            self._send_json(200, {"ok": True, "service": "sub2api-wechat-poc-webhook"})
+            return
+        self._send_json(404, {"ok": False, "error": "not_found"})
+
+    def do_POST(self):
+        expected_token = os.environ.get("POC_WEBHOOK_TOKEN", "")
+        if expected_token:
+            expected = f"Bearer {expected_token}"
+            if self.headers.get("Authorization") != expected:
+                self._send_json(401, {"ok": False, "error": "unauthorized"})
+                return
+
+        length = int(self.headers.get("Content-Length", "0"))
+        raw = self.rfile.read(length)
+        try:
+            payload = json.loads(raw.decode("utf-8") or "{}")
+        except json.JSONDecodeError:
+            self._send_json(400, {"ok": False, "error": "invalid_json"})
+            return
+
+        print(_compact({"ts": int(time.time()), "path": self.path, "payload": payload}), flush=True)
+
+        if payload.get("type") == "url_verification":
+            self._send_json(200, {"challenge": payload.get("challenge")})
+            return
+
+        content = (_payload_value(payload, ("content",), ("text",), ("event", "data", "content"), ("event", "data", "text")) or "").strip()
+        sender = _payload_value(payload, ("sender",), ("event", "data", "sender")) or {}
+        session_id = _payload_value(payload, ("sessionID",), ("session_id",), ("event", "data", "sessionID"))
+        channel_id = _payload_value(payload, ("channel_id",), ("channelID",), ("event", "channel_id"))
+        group = _payload_value(payload, ("group",), ("room",), ("event", "data", "group"), ("event", "data", "room"))
+
+        if content.startswith("/ping") or content == "ping":
+            self._send_json(200, {"reply": "pong: sub2api wechat POC webhook is alive"})
+            return
+
+        if content.startswith("/status") or "状态" in content:
+            group_name = "plus" if "plus" in content.lower() else "all"
+            self._send_json(
+                200,
+                {
+                    "reply": (
+                        f"POC status group={group_name}: total=3 active=2 disabled=1. "
+                        "This is mock data; WeChat event delivery is working."
+                    )
+                },
+            )
+            return
+
+        if content.startswith("/add-plus-dry-run") or "加号" in content:
+            self._send_json(
+                200,
+                {
+                    "reply": (
+                        "dry-run accepted: job=poc_plus_import_001, group=plus, "
+                        "no real CDK was redeemed."
+                    )
+                },
+            )
+            return
+
+        scope = "group" if group else "dm_or_unknown"
+        sender_id = sender.get("user_id") or sender.get("id") or "unknown"
+        group_id = None
+        if isinstance(group, dict):
+            group_id = group.get("id") or group.get("room_id") or group.get("user_id")
+        self._send_json(
+            200,
+            {
+                "reply": (
+                    f"received {scope} message. sender={sender_id}"
+                    + (f" group={group_id}" if group_id else "")
+                    + (f" session={session_id}" if session_id else "")
+                    + (f" channel={channel_id}" if channel_id else "")
+                    + ". Try /ping, /status plus, or /add-plus-dry-run."
+                )
+            },
+        )
+
+
+if __name__ == "__main__":
+    HTTPServer(("0.0.0.0", 9811), Handler).serve_forever()

package/templates/wechat-agent-poc/scripts/deploy-to-192.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOCAL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+REMOTE="${WECHAT_POC_REMOTE:-root@192.220.25.138}"
+REMOTE_DIR="${WECHAT_POC_REMOTE_DIR:-/opt/sub2api/wechat-agent-poc}"
+
+ssh "$REMOTE" "mkdir -p '$REMOTE_DIR'"
+rsync -az --delete \
+  --exclude '__pycache__' \
+  --exclude '.pytest_cache' \
+  "$LOCAL_DIR/" "$REMOTE:$REMOTE_DIR/"
+
+ssh "$REMOTE" "cd '$REMOTE_DIR' && chmod +x scripts/*.sh && ./scripts/start.sh"
+
+printf "OpeniLink Hub: http://192.220.25.138:9800\n"
+printf "Remote logs: ssh %s 'cd %s && ./scripts/logs.sh'\n" "$REMOTE" "$REMOTE_DIR"

package/templates/wechat-agent-poc/scripts/install-prereqs-ubuntu.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if command -v docker >/dev/null 2>&1 && docker compose version >/dev/null 2>&1; then
+  docker compose version
+  exit 0
+fi
+
+if ! command -v apt-get >/dev/null 2>&1; then
+  echo "This helper only supports apt-based Linux hosts. Install Docker manually, then rerun scripts/start.sh." >&2
+  exit 1
+fi
+
+sudo apt-get update
+sudo apt-get install -y ca-certificates curl gnupg
+sudo install -m 0755 -d /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+sudo chmod a+r /etc/apt/keyrings/docker.gpg
+
+. /etc/os-release
+echo \
+  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
+  ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
+
+sudo apt-get update
+sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+sudo systemctl enable --now docker
+docker compose version

package/templates/wechat-agent-poc/scripts/logs.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+docker compose logs -f poc-webhook

package/templates/wechat-agent-poc/scripts/probe-webhook.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+TOKEN=""
+if [ -f .env ]; then
+  TOKEN="$(awk -F= '$1=="POC_WEBHOOK_TOKEN"{print $2}' .env | tail -1)"
+fi
+
+AUTH_ARGS=()
+if [ -n "$TOKEN" ]; then
+  AUTH_ARGS=(-H "Authorization: Bearer $TOKEN")
+fi
+
+curl -fsS \
+  -H "Content-Type: application/json" \
+  "${AUTH_ARGS[@]}" \
+  -d '{"type":"message","content":"/ping","sender":{"user_id":"local_probe","user_name":"local probe"},"sessionID":"probe_session","channel_id":"probe_channel"}' \
+  "http://127.0.0.1:${POC_WEBHOOK_PORT:-9811}/webhook"
+printf "\n"

package/templates/wechat-agent-poc/scripts/start.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if [ ! -f .env ]; then
+  cp .env.example .env
+fi
+
+docker compose up -d
+docker compose ps

package/templates/wechat-agent-poc/scripts/status.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+docker compose ps
+printf "\nWebhook health:\n"
+curl -fsS "http://127.0.0.1:${POC_WEBHOOK_PORT:-9811}/health" || true
+printf "\n\nRecent webhook logs:\n"
+docker compose logs --tail=80 poc-webhook

package/templates/wechat-agent-poc/scripts/stop.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+docker compose down

package/templates/wechat-agent-poc/sub2api-tools-contract.md

@@ -0,0 +1,53 @@
+# Sub2API Agent Tools Contract
+
+这个文件定义下一步给 Hermes 或其他 Agent 调用的最小工具边界。当前 POC 只验证微信通道，暂不执行真实 CDK 兑换。
+
+## Tool Boundary
+
+Agent 只能调用 HTTP 工具服务，不直接连数据库，不直接读取 CDK 明文日志。
+
+推荐工具：
+
+```text
+GET  /agent-tools/pool/status?group=plus
+POST /agent-tools/plus/import-jobs
+GET  /agent-tools/plus/import-jobs/{id}
+POST /agent-tools/plus/import-jobs/{id}/retry
+POST /agent-tools/accounts/{id}/disable
+POST /agent-tools/accounts/{id}/enable
+```
+
+## Import Job
+
+```json
+{
+  "requester_wechat_id": "wxid_xxx",
+  "group": "plus",
+  "cdk": "redacted-at-rest",
+  "dry_run": true
+}
+```
+
+状态机：
+
+```text
+pending
+validating_cdk
+redeeming
+importing_account
+assigning_group
+healthchecking
+enabled
+failed
+```
+
+## Safety
+
+```text
+群聊只能查询状态和创建 dry-run job
+真实 CDK 只允许私聊或 sub2api 管理页提交
+所有写操作必须校验 requester_wechat_id allowlist
+所有 CDK 日志必须脱敏
+同一个 CDK hash 必须幂等
+失败 job 必须保留 error_code 和 redacted_error
+```