openilink-app-runner 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# openilink-app-runner
+
+将本地命令行工具桥接到微信 —— 通过 OpeniLink Hub 接收微信命令，在本地执行，返回结果。
+
+## 工作原理
+
+```
+微信用户 → /weather 北京 → Hub → WebSocket → Runner → curl wttr.in/北京 → 结果返回微信
+```
+
+1. 在 YAML 配置中定义命令（名称 + shell 命令）
+2. Runner 启动时自动同步命令到 Hub
+3. 通过 WebSocket 保持连接，接收来自微信的命令事件
+4. 在本地执行对应 shell 命令，将输出返回给微信用户
+
+## 安装
+
+```bash
+npm install -g openilink-app-runner
+```
+
+## 快速开始
+
+### 1. 初始化配置
+
+```bash
+openilink-app-runner init --hub-url https://hub.openilink.com --token app_xxx
+```
+
+这会在当前目录创建 `runner.yaml` 配置文件。
+
+### 2. 添加命令
+
+```bash
+# 添加查天气命令
+openilink-app-runner add weather "curl -s 'wttr.in/\${args}?format=3'" -d "查天气" -t 5
+
+# 添加查 IP 命令
+openilink-app-runner add ip "curl -s ifconfig.me" -d "查公网 IP" -t 5
+
+# 查看已添加的命令
+openilink-app-runner list
+```
+
+添加命令时会自动同步到 Hub。
+
+### 3. 启动
+
+```bash
+openilink-app-runner start
+```
+
+现在在微信中发送 `/weather 北京` 即可看到天气结果。
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `init --hub-url <url> --token <token>` | 初始化配置文件 |
+| `add <name> <exec> [-d desc] [-t timeout]` | 添加命令 |
+| `remove <name>` | 删除命令 |
+| `list` | 查看已配置的命令 |
+| `sync` | 手动同步命令到 Hub |
+| `start` | 启动 runner，连接 Hub 并监听命令 |
+
+所有命令支持 `-c, --config <path>` 指定配置文件路径，默认为 `runner.yaml`。
+
+## 配置文件格式
+
+```yaml
+hub_url: "https://hub.openilink.com"
+app_token: "app_your_token_here"
+max_output: 2000  # 输出最大字符数
+
+commands:
+  weather:
+    description: "查天气"
+    exec: "curl -s 'wttr.in/${args}?format=3'"
+    timeout: 5  # 秒，默认 30
+  ip:
+    description: "查公网 IP"
+    exec: "curl -s ifconfig.me"
+    timeout: 5
+```
+
+### 字段说明
+
+- `hub_url` — Hub 服务地址（必填）
+- `app_token` — App Token，在 Hub 中创建 App 后获取（必填）
+- `max_output` — 命令输出最大字符数，超出截断（默认 2000）
+- `commands` — 命令映射
+  - `description` — 命令描述，会显示在微信中
+  - `exec` — 要执行的 shell 命令，支持 `${args}` 占位符接收用户输入
+  - `timeout` — 超时秒数（默认 30）
+
+## 安全提示
+
+`${args}` 会直接替换到 shell 命令中，存在命令注入风险。请注意：
+
+- 仅在信任的微信群/用户中使用
+- 避免在 `exec` 中使用 `${args}` 执行危险操作（如 `rm`、`sudo` 等）
+- 设置合理的 `timeout` 防止命令卡住
+- `max_output` 限制输出大小，防止刷屏
+
+## 示例：集成 opencli
+
+```yaml
+commands:
+  hn:
+    description: "HackerNews 热门"
+    exec: "opencli hackernews top --format json"
+    timeout: 10
+  github:
+    description: "GitHub 趋势"
+    exec: "opencli github trending ${args}"
+    timeout: 10
+```
+
+## 自动重连
+
+Runner 会自动维护 WebSocket 连接。断开后每 5 秒自动重连，同时通过 ping/pong 保持心跳。
+
+---
+
+## English
+
+### What is this?
+
+`openilink-app-runner` bridges local CLI commands to WeChat via [OpeniLink Hub](https://github.com/openilink/openilink-hub). Define commands in a YAML config, and WeChat users can invoke them by sending `/command args`.
+
+### How it works
+
+1. Define commands in `runner.yaml` (name + shell command)
+2. Runner syncs commands to Hub on startup
+3. Stays connected via WebSocket, receives command events from WeChat
+4. Executes shell commands locally, returns output to WeChat
+
+### Quick start
+
+```bash
+npm install -g openilink-app-runner
+
+openilink-app-runner init --hub-url https://hub.openilink.com --token app_xxx
+openilink-app-runner add weather "curl -s 'wttr.in/\${args}?format=3'" -d "Weather" -t 5
+openilink-app-runner start
+```
+
+### Security
+
+`${args}` is interpolated directly into shell commands. Only use in trusted environments. Set reasonable timeouts and output limits.
+
+## License
+
+MIT

package/dist/bin/runner.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/runner.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const config_1 = require("../src/config");
+const sync_1 = require("../src/sync");
+const hub_1 = require("../src/hub");
+const handler_1 = require("../src/handler");
+const program = new commander_1.Command();
+program
+    .name("openilink-app-runner")
+    .description("Run local commands as OpeniLink Hub App tools")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("初始化配置文件")
+    .option("-c, --config <path>", "配置文件路径", "runner.yaml")
+    .requiredOption("--hub-url <url>", "Hub URL")
+    .requiredOption("--token <token>", "App Token")
+    .action((opts) => {
+    (0, config_1.initConfig)(opts.config, opts.hubUrl, opts.token);
+    console.log(`✓ 配置已写入 ${opts.config}`);
+});
+program
+    .command("add <name> <exec>")
+    .description("添加命令")
+    .option("-c, --config <path>", "配置文件路径", "runner.yaml")
+    .option("-d, --desc <description>", "命令描述")
+    .option("-t, --timeout <seconds>", "超时时间", "30")
+    .action(async (name, exec, opts) => {
+    const configPath = (0, config_1.getConfigPath)(opts.config);
+    const config = (0, config_1.loadConfig)(configPath);
+    config.commands[name] = {
+        exec,
+        description: opts.desc || name,
+        timeout: parseInt(opts.timeout, 10),
+    };
+    (0, config_1.saveConfig)(configPath, config);
+    console.log(`✓ 已添加命令 /${name}`);
+    // Auto-sync to Hub
+    try {
+        await (0, sync_1.syncTools)(config);
+    }
+    catch (err) {
+        console.error(`⚠ 同步到 Hub 失败: ${err.message}`);
+    }
+});
+program
+    .command("remove <name>")
+    .description("删除命令")
+    .option("-c, --config <path>", "配置文件路径", "runner.yaml")
+    .action(async (name, opts) => {
+    const configPath = (0, config_1.getConfigPath)(opts.config);
+    const config = (0, config_1.loadConfig)(configPath);
+    if (!config.commands[name]) {
+        console.error(`命令 /${name} 不存在`);
+        process.exit(1);
+    }
+    delete config.commands[name];
+    (0, config_1.saveConfig)(configPath, config);
+    console.log(`✓ 已删除命令 /${name}`);
+    // Auto-sync to Hub
+    try {
+        await (0, sync_1.syncTools)(config);
+    }
+    catch (err) {
+        console.error(`⚠ 同步到 Hub 失败: ${err.message}`);
+    }
+});
+program
+    .command("list")
+    .description("查看已配置的命令")
+    .option("-c, --config <path>", "配置文件路径", "runner.yaml")
+    .action((opts) => {
+    const config = (0, config_1.loadConfig)((0, config_1.getConfigPath)(opts.config));
+    const cmds = Object.entries(config.commands);
+    if (cmds.length === 0) {
+        console.log("暂无命令。使用 add <name> <exec> 添加。");
+        return;
+    }
+    console.log(`Hub: ${config.hub_url}`);
+    console.log(`命令 (${cmds.length}):`);
+    for (const [name, cmd] of cmds) {
+        console.log(`  /${name} — ${cmd.description || "(无描述)"}`);
+        console.log(`    exec: ${cmd.exec}`);
+        if (cmd.timeout)
+            console.log(`    timeout: ${cmd.timeout}s`);
+    }
+});
+program
+    .command("sync")
+    .description("手动同步命令到 Hub")
+    .option("-c, --config <path>", "配置文件路径", "runner.yaml")
+    .action(async (opts) => {
+    const config = (0, config_1.loadConfig)((0, config_1.getConfigPath)(opts.config));
+    await (0, sync_1.syncTools)(config);
+});
+program
+    .command("start")
+    .description("启动 runner，连接 Hub 并监听命令")
+    .option("-c, --config <path>", "配置文件路径", "runner.yaml")
+    .action(async (opts) => {
+    const config = (0, config_1.loadConfig)((0, config_1.getConfigPath)(opts.config));
+    const cmdCount = Object.keys(config.commands).length;
+    console.log(`openilink-app-runner v0.1.0`);
+    console.log(`Hub: ${config.hub_url}`);
+    console.log(`命令: ${cmdCount} 个`);
+    if (cmdCount === 0) {
+        console.log("⚠ 没有配置命令。使用 add <name> <exec> 添加。");
+    }
+    // Sync tools on startup
+    try {
+        await (0, sync_1.syncTools)(config);
+    }
+    catch (err) {
+        console.error(`⚠ 同步 tools 失败: ${err.message}`);
+        console.log("继续启动...");
+    }
+    // Connect to Hub
+    const handler = (0, handler_1.createHandler)(config);
+    const hub = new hub_1.HubConnection(config, handler);
+    // Handle graceful shutdown
+    process.on("SIGINT", () => {
+        console.log("\n正在停止...");
+        hub.stop();
+        process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+        hub.stop();
+        process.exit(0);
+    });
+    hub.connect();
+});
+// Default: show help
+if (process.argv.length <= 2) {
+    program.help();
+}
+program.parse();

package/dist/src/config.d.ts

@@ -0,0 +1,5 @@
+import { RunnerConfig } from "./types";
+export declare function getConfigPath(custom?: string): string;
+export declare function loadConfig(configPath: string): RunnerConfig;
+export declare function saveConfig(configPath: string, config: RunnerConfig): void;
+export declare function initConfig(configPath: string, hubUrl: string, appToken: string): void;

package/dist/src/config.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigPath = getConfigPath;
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.initConfig = initConfig;
+const fs = __importStar(require("fs"));
+const yaml = __importStar(require("js-yaml"));
+const DEFAULT_PATH = "runner.yaml";
+function getConfigPath(custom) {
+    return custom || DEFAULT_PATH;
+}
+function loadConfig(configPath) {
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`Config file not found: ${configPath}`);
+    }
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const config = yaml.load(raw);
+    if (!config.hub_url)
+        throw new Error("hub_url is required in config");
+    if (!config.app_token)
+        throw new Error("app_token is required in config");
+    if (!config.commands)
+        config.commands = {};
+    if (!config.max_output)
+        config.max_output = 2000;
+    return config;
+}
+function saveConfig(configPath, config) {
+    const raw = yaml.dump(config, { lineWidth: -1, noRefs: true });
+    fs.writeFileSync(configPath, raw, "utf-8");
+}
+function initConfig(configPath, hubUrl, appToken) {
+    const config = {
+        hub_url: hubUrl,
+        app_token: appToken,
+        max_output: 2000,
+        commands: {},
+    };
+    saveConfig(configPath, config);
+}

package/dist/src/executor.d.ts

@@ -0,0 +1,2 @@
+import { CommandConfig } from "./types";
+export declare function executeCommand(cmdConfig: CommandConfig, args: string, maxOutput: number): Promise<string>;

package/dist/src/executor.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeCommand = executeCommand;
+const child_process_1 = require("child_process");
+function executeCommand(cmdConfig, args, maxOutput) {
+    return new Promise((resolve) => {
+        const command = cmdConfig.exec.replace(/\$\{args\}/g, args || "");
+        const timeout = (cmdConfig.timeout || 30) * 1000;
+        (0, child_process_1.exec)(command, { timeout, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+            if (error) {
+                if (error.killed) {
+                    resolve(`命令超时（${cmdConfig.timeout || 30}s）`);
+                    return;
+                }
+                const errMsg = stderr?.trim() || error.message;
+                resolve(`命令执行失败: ${errMsg}`.slice(0, maxOutput));
+                return;
+            }
+            let output = stdout.trim();
+            if (!output && stderr?.trim()) {
+                output = stderr.trim();
+            }
+            if (!output) {
+                output = "(无输出)";
+            }
+            // Truncate to max_output
+            if (output.length > maxOutput) {
+                output = output.slice(0, maxOutput - 20) + "\n... (输出已截断)";
+            }
+            resolve(output);
+        });
+    });
+}

package/dist/src/handler.d.ts

@@ -0,0 +1,2 @@
+import { RunnerConfig, HubEvent } from "./types";
+export declare function createHandler(config: RunnerConfig): (event: HubEvent, sendReply: (content: string) => void) => Promise<void>;

package/dist/src/handler.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHandler = createHandler;
+const executor_1 = require("./executor");
+function createHandler(config) {
+    return async (event, sendReply) => {
+        if (event.event.type !== "command")
+            return;
+        const cmdName = event.event.data.command;
+        const text = event.event.data.text || "";
+        const sender = event.event.data.sender;
+        console.log(`← /${cmdName} ${text} (from ${sender?.name || "unknown"})`);
+        const cmdConfig = config.commands[cmdName];
+        if (!cmdConfig) {
+            const available = Object.keys(config.commands).map(c => `/${c}`).join(", ");
+            sendReply(`未知命令: /${cmdName}\n可用命令: ${available}`);
+            return;
+        }
+        try {
+            const result = await (0, executor_1.executeCommand)(cmdConfig, text, config.max_output || 2000);
+            console.log(`→ (${result.length} chars)`);
+            sendReply(result);
+        }
+        catch (err) {
+            console.error(`命令执行出错:`, err);
+            sendReply(`执行失败: ${err.message}`);
+        }
+    };
+}

package/dist/src/hub.d.ts

@@ -0,0 +1,15 @@
+import { RunnerConfig, HubEvent } from "./types";
+export type EventHandler = (event: HubEvent, sendReply: (content: string) => void) => void;
+export declare class HubConnection {
+    private ws;
+    private config;
+    private onEvent;
+    private reconnectTimer;
+    private pingTimer;
+    private stopped;
+    constructor(config: RunnerConfig, onEvent: EventHandler);
+    connect(): void;
+    sendReply(content: string): void;
+    stop(): void;
+    private cleanup;
+}

package/dist/src/hub.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HubConnection = void 0;
+const ws_1 = __importDefault(require("ws"));
+class HubConnection {
+    ws = null;
+    config;
+    onEvent;
+    reconnectTimer = null;
+    pingTimer = null;
+    stopped = false;
+    constructor(config, onEvent) {
+        this.config = config;
+        this.onEvent = onEvent;
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        const wsUrl = `${this.config.hub_url.replace(/^http/, "ws")}/bot/v1/ws?token=${this.config.app_token}`;
+        this.ws = new ws_1.default(wsUrl);
+        this.ws.on("open", () => {
+            console.log("✓ 已连接到 Hub");
+            // Start ping interval
+            this.pingTimer = setInterval(() => {
+                if (this.ws?.readyState === ws_1.default.OPEN) {
+                    this.ws.send(JSON.stringify({ type: "ping" }));
+                }
+            }, 30000);
+        });
+        this.ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                if (msg.type === "init") {
+                    console.log(`  Bot: ${msg.data.bot_id}`);
+                    console.log(`  App: ${msg.data.app_slug}`);
+                    return;
+                }
+                if (msg.type === "event") {
+                    this.onEvent(msg, (content) => this.sendReply(content));
+                    return;
+                }
+                if (msg.type === "pong" || msg.type === "ack")
+                    return;
+                if (msg.type === "error") {
+                    console.error(`Hub 错误: ${msg.error}`);
+                    return;
+                }
+            }
+            catch (err) {
+                console.error("消息解析失败:", err);
+            }
+        });
+        this.ws.on("close", () => {
+            console.log("与 Hub 断开连接");
+            this.cleanup();
+            if (!this.stopped) {
+                console.log("5 秒后重连...");
+                this.reconnectTimer = setTimeout(() => this.connect(), 5000);
+            }
+        });
+        this.ws.on("error", (err) => {
+            console.error("连接错误:", err.message);
+        });
+    }
+    sendReply(content) {
+        if (this.ws?.readyState === ws_1.default.OPEN) {
+            this.ws.send(JSON.stringify({ type: "send", content }));
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.cleanup();
+        this.ws?.close();
+    }
+    cleanup() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+}
+exports.HubConnection = HubConnection;

package/dist/src/sync.d.ts

@@ -0,0 +1,2 @@
+import { RunnerConfig } from "./types";
+export declare function syncTools(config: RunnerConfig): Promise<void>;

package/dist/src/sync.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncTools = syncTools;
+async function syncTools(config) {
+    const tools = Object.entries(config.commands).map(([name, cmd]) => ({
+        name,
+        description: cmd.description || name,
+        command: name,
+        parameters: {
+            type: "object",
+            properties: {
+                args: { type: "string", description: "命令参数" },
+            },
+        },
+    }));
+    const resp = await fetch(`${config.hub_url}/bot/v1/installation/tools`, {
+        method: "PUT",
+        headers: {
+            Authorization: `Bearer ${config.app_token}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ tools }),
+    });
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`同步 tools 失败: ${resp.status} ${text}`);
+    }
+    const result = await resp.json();
+    console.log(`✓ 已同步 ${result.tool_count} 个命令到 Hub`);
+}

package/dist/src/types.d.ts

@@ -0,0 +1,26 @@
+export interface CommandConfig {
+    description?: string;
+    exec: string;
+    timeout?: number;
+}
+export interface RunnerConfig {
+    hub_url: string;
+    app_token: string;
+    max_output?: number;
+    commands: Record<string, CommandConfig>;
+}
+export interface HubEvent {
+    type: string;
+    v: number;
+    trace_id: string;
+    installation_id: string;
+    bot: {
+        id: string;
+    };
+    event: {
+        type: string;
+        id: string;
+        timestamp: number;
+        data: Record<string, any>;
+    };
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "openilink-app-runner",
+  "version": "0.1.0",
+  "description": "Run local commands as OpeniLink Hub App tools — bridge CLI to WeChat",
+  "bin": {
+    "openilink-app-runner": "dist/bin/runner.js"
+  },
+  "files": ["dist/", "runner.example.yaml", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["openilink", "wechat", "cli", "bot"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openilink/openilink-app-runner"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "js-yaml": "^4.1.0",
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/ws": "^8.0.0",
+    "@types/js-yaml": "^4.0.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/runner.example.yaml

@@ -0,0 +1,20 @@
+# OpeniLink App Runner 配置
+# 文档: https://github.com/openilink/openilink-app-runner
+
+hub_url: "https://hub.openilink.com"
+app_token: "app_your_token_here"
+max_output: 2000
+
+commands:
+  hn:
+    description: "HackerNews 热门"
+    exec: "opencli hackernews top --format json"
+    timeout: 10
+  weather:
+    description: "查天气"
+    exec: "curl -s 'wttr.in/${args}?format=3'"
+    timeout: 5
+  ip:
+    description: "查公网 IP"
+    exec: "curl -s ifconfig.me"
+    timeout: 5