@yvhitxcel/opencode-remote 0.17.0 → 0.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenCode Remote Control Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -156,6 +156,59 @@ A: 需要一台电脑运行 bot，手机上通过 IM 控制。OpenCode 也运行
 **Q: 如何更新？**
 A: `npm update -g @yvhitxcel/opencode-remote`
 
+## 全局命令
+
+安装后使用 `opencode-remote` 命令（不是 `remote-control`）。
+
+### 命令原理
+
+`package.json` 的 `bin` 字段声明了全局命令：
+
+```json
+"bin": {
+    "opencode-remote": "bin/opencode-remote.js",
+    "opencode-weixin": "bin/opencode-weixin.js"
+}
+```
+
+`npm install -g` 时，npm 在全局目录（Windows: `%APPDATA%\npm\`）创建三个包装脚本：
+
+| 文件 | 作用 |
+|------|------|
+| `opencode-remote.cmd` | CMD 入口 |
+| `opencode-remote.ps1` | PowerShell 入口 |
+| `opencode-remote` | Unix Shell 入口 |
+
+包装脚本调用 `node <pkg>/dist/cli.js <args>`。`cli.js` 内置了自动重启机制：
+- 首次启动以父进程模式运行，`spawn` 子进程执行实际逻辑
+- 子进程退出码 `200` 时父进程自动重启
+
+### 多 Bot 实例
+
+```bash
+opencode-remote weixin                   # 启动微信
+opencode-remote weixin --id bot1         # 多账号：第一个
+opencode-remote weixin --id bot2         # 多账号：第二个
+opencode-remote telegram                 # 启动 Telegram
+opencode-remote feishu                   # 启动飞书
+opencode-remote                          # 启动所有已配置的 Bot
+```
+
+### 别名
+
+如果习惯 `remote-control` 这个命令名，创建别名文件：
+
+**PowerShell** (`$PROFILE`):
+```powershell
+Set-Alias -Name remote-control -Value opencode-remote
+```
+
+**CMD** (`remote-control.cmd`):
+```bat
+@echo off
+opencode-remote %*
+```
+
 ## 系统要求
 
 - Node.js >= 18.0.0
@@ -164,6 +217,22 @@ A: `npm update -g @yvhitxcel/opencode-remote`
 
 本项目基于 [opencode-remote-control](https://github.com/ceociocto/opencode-remote-control) 开发。
 
+## 文档
+
+- [架构总览](docs/ARCHITECTURE.md) — 进程模型、模块图、消息流、错误传播理念
+- [故障排查](docs/TROUBLESHOOTING.md) — 常见问题诊断与解决
+- [配置说明](docs/CONFIG.md) — 环境变量、路径、超时矩阵
+- [错误处理规范](docs/ERROR_HANDLING.md) — 错误处理契约，新代码必须遵循
+- [快速开始](QUICKSTART.md) — 入门指南
+
+## 质量保障
+
+- ✅ TypeScript 类型检查 (`npm run typecheck`)
+- ✅ 32 项自动化测试 (`npm test`)
+- ✅ 多平台 CI（GitHub Actions: Ubuntu + Windows × Node 20/22）
+- ✅ 容器化部署 (`docker compose up`)
+- ✅ MIT 许可证
+
 ## 许可证
 
-MIT License
+MIT License — 详见 [LICENSE](LICENSE) 文件

package/dist/cli.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 // OpenCode Remote Control - CLI entry point
-import { watch } from 'fs';
-import { dirname } from 'path';
+// @ts-nocheck — process.env spread has type issues with strict @types/node
+import { watch, existsSync, writeFileSync, unlinkSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
 import { fileURLToPath } from 'url';
-import { spawn } from 'child_process';
+import { spawn, execSync } from 'child_process';
+import { createServer } from 'http';
 import { setGlobalProxy } from './opencode/client.js';
 import { printBanner, VERSION, runConfig, runConfigTimeout } from './core/setup.js';
 import { runStart, runTelegramOnly, runFeishuOnly, runWeixinOnly, runAgentsCommand } from './bot-runner.js';
@@ -76,11 +79,79 @@ Examples:
 // Main CLI
 // 父进程管理：如果不是子进程，则启动父进程模式
 if (process.env.OPENCODE_CHILD !== '1') {
+    process.on('unhandledRejection', (reason) => { console.error('[parent] Unhandled Rejection:', reason); });
+
+    // PID 文件锁：确保只有一个父进程实例
+    const PID_FILE = join(homedir(), '.opencode-remote', 'parent.pid');
+    try {
+        if (existsSync(PID_FILE)) {
+            const oldPid = parseInt(readFileSync(PID_FILE, 'utf8').trim(), 10);
+            if (oldPid && oldPid !== process.pid) {
+                try { process.kill(oldPid, 'SIGTERM'); } catch { console.debug('[pid] old process already dead'); }
+                try { execSync(`taskkill /F /T /PID ${oldPid}`, { timeout: 2000 }); } catch { console.debug('[pid] taskkill failed'); }
+            }
+        }
+    } catch (e) { console.debug('[pid] Failed to read PID file:', e.message); }
+    try { writeFileSync(PID_FILE, String(process.pid), 'utf8'); } catch (e) { console.debug('[pid] Failed to write PID file:', e.message); }
+    process.on('exit', () => { try { unlinkSync(PID_FILE); } catch {} });
+
+    // Health check HTTP server (for Docker healthcheck / monitoring)
+    function startHealthServer() {
+        const port = parseInt(process.env.HEALTH_PORT || '9090', 10);
+        if (isNaN(port) || port < 1 || port > 65535) return;
+        const server = createServer((req, res) => {
+            if (req.url !== '/health' && req.url !== '/') {
+                res.writeHead(404); res.end('Not found');
+                return;
+            }
+            const childAlive = childProc && childProc.exitCode === null && childProc.killed === false;
+            const hbOk = Date.now() - lastHeartbeatTs < 120_000;
+            const healthy = childAlive && hbOk && !shuttingDown;
+            const status = healthy ? 200 : 503;
+            const body = JSON.stringify({
+                status: healthy ? 'ok' : 'degraded',
+                pid: process.pid,
+                uptime: process.uptime(),
+                childAlive,
+                lastHeartbeatAgo: Date.now() - lastHeartbeatTs,
+                shuttingDown,
+            });
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(body);
+        });
+        server.listen(port, '127.0.0.1', () => {
+            console.log(`[health] HTTP health endpoint at http://127.0.0.1:${port}/health`);
+        });
+        server.unref();
+    }
+
     let childProc = null;
     let shuttingDown = false;
     let isRestart = false;
+    let crashCount = 0;
+    let lastCrashTs = 0;
+    let lastSpawnTs = 0;
+    let lastHeartbeatTs = Date.now();
+    let heartbeatCheckTimer = null;
+
+    function cleanupPorts() {
+        for (const port of [4096, 4097, 4098]) {
+            try {
+                const out = execSync(`netstat -ano | findstr ":${port} "`, { timeout: 3000 });
+                for (const line of out.toString().trim().split('\n')) {
+                    const parts = line.trim().split(/\s+/);
+                    const pid = parts[parts.length - 1];
+                    if (pid && pid !== '0') {
+                        try { execSync(`taskkill /F /PID ${pid}`, { timeout: 2000 }); } catch { console.debug('[cleanup] kill failed (already dead?)', pid); }
+                    }
+                }
+            } catch { console.debug('[cleanup] no process on port', port); }
+        }
+    }
 
     const spawnChild = (fromRestart = false) => {
+        cleanupPorts();
+        lastSpawnTs = Date.now();
         if (shuttingDown) return;
         if (childProc) {
             try { childProc.kill('SIGTERM'); } catch {}
@@ -101,30 +172,68 @@ if (process.env.OPENCODE_CHILD !== '1') {
         childProc.stderr.on('data', (d) => process.stderr.write(d));
 
         childProc.on('close', (code) => {
-            console.log(`[parent] Child process closed with code: ${code}`);
+            const wasSignal = code === null;
+            console.log(`[parent] Child process closed with code: ${code}${wasSignal ? ' (signal)' : ''}`);
             if (shuttingDown) {
                 console.log('[parent] Shutting down, not restarting');
                 return;
             }
-            if (code === 200 || code === null) {
-                console.log(`\n🔄 Bot exited (code ${code}), restarting...`);
+
+            // 区分：200=主动重启请求, null=信号杀, 其他=异常退出
+            if (code === 200) {
+                // 主动 /restart
                 isRestart = true;
                 setTimeout(() => spawnChild(true), 1000);
+                return;
+            }
+
+            // 崩溃检测: 60 秒内连续多次崩溃 → 不再重启 (避免崩循环)
+            const now = Date.now();
+            if (now - lastCrashTs < 60_000) {
+                crashCount++;
             } else {
-                console.log(`[parent] Bot exited with code ${code}, not restarting`);
+                crashCount = 1;
+            }
+            lastCrashTs = now;
+
+            if (crashCount >= 5) {
+                console.error(`[parent] ${crashCount} crashes in 60s, giving up. Manual restart required.`);
+                process.exit(1);
             }
+
+            // 退避重启: 1s, 2s, 4s, 8s
+            const backoff = Math.min(8000, 1000 * Math.pow(2, crashCount - 1));
+            console.log(`[parent] Bot ${wasSignal ? 'killed by signal' : `crashed (code ${code})`}, restarting in ${backoff}ms (crash #${crashCount})`);
+            isRestart = true;
+            setTimeout(() => spawnChild(true), backoff);
         });
 
         childProc.on('error', (err) => {
             console.error('[parent] Child error:', err.message);
         });
+
+        // IPC 心跳：子进程每 30s 发心跳，超过 120s 无心跳视为卡死
+        childProc.on('message', (msg) => {
+            if (msg?.type === 'heartbeat') lastHeartbeatTs = Date.now();
+        });
+        lastHeartbeatTs = Date.now();
+        clearInterval(heartbeatCheckTimer);
+        heartbeatCheckTimer = setInterval(() => {
+            if (shuttingDown) return;
+            if (Date.now() - lastHeartbeatTs > 120_000) {
+                console.error('[parent] No heartbeat for 120s, killing stuck child...');
+                isRestart = true;
+                try { childProc.kill('SIGKILL'); } catch {}
+            }
+        }, 30_000);
+        if (heartbeatCheckTimer.unref) heartbeatCheckTimer.unref();
     };
 
-    // 文件监控 - 代码变化时自动重启
+    // 文件监控 - 代码变化时自动重启 (spawn 后 3s 静默, 避免重启循环)
     const distDir = __dirname;
     let debounceTimer = null;
     watch(distDir, { recursive: true }, (eventType, filename) => {
-        if (filename && filename.endsWith('.js') && !shuttingDown) {
+        if (filename && filename.endsWith('.js') && !shuttingDown && Date.now() - lastSpawnTs > 3000) {
             clearTimeout(debounceTimer);
             debounceTimer = setTimeout(() => {
                 console.log(`\n📝 ${filename} changed, restarting...`);
@@ -136,6 +245,8 @@ if (process.env.OPENCODE_CHILD !== '1') {
         }
     });
 
+    startHealthServer();
+
     process.on('SIGINT', () => {
         if (shuttingDown) return;
         shuttingDown = true;

package/dist/core/adapter.js

@@ -0,0 +1,12 @@
+// BotAdapter interface — all platform adapters must implement these methods
+//   reply(threadId, text)                — send a text message to user
+//   sendTypingIndicator(threadId)         — show typing indicator (start)
+//   sendTypingEnd?(threadId)              — stop typing indicator [optional]
+//   updateMessage?(threadId, msgId, text) — edit a message [optional]
+//   deleteMessage?(threadId, msgId)       — delete a message [optional]
+//   platform                             — string identifier ('weixin'|'feishu'|'telegram')
+
+export {};
+
+// This module only exists as the contract reference.
+// Each platform adapter (weixin/adapter.js etc.) independently satisfies this shape.

package/dist/core/agent-registry.js

@@ -0,0 +1,77 @@
+// Global registry of running agent/CLI processes
+// /esc uses this to kill the actual subprocess, not just abort the SDK session
+import { logger } from './log.js';
+
+const _registry = new Map();  // threadId -> { process, agentName, killed, killTimer }
+
+export function registerAgentProcess(threadId, proc, agentName) {
+    // 若已存在先杀掉旧的
+    const old = _registry.get(threadId);
+    if (old && !old.killed) {
+        try { old.process.kill('SIGKILL'); } catch {}
+    }
+    _registry.set(threadId, { process: proc, agentName, killed: false, killTimer: null });
+    logger.info('agent-process:registered', { threadId, agentName, pid: proc.pid });
+}
+
+export function unregisterAgentProcess(threadId) {
+    const e = _registry.get(threadId);
+    if (!e) return;
+    if (e.killTimer) clearTimeout(e.killTimer);
+    _registry.delete(threadId);
+    logger.info('agent-process:unregistered', { threadId });
+}
+
+/**
+ * Kill the running agent process for a thread.
+ * @param {string} threadId
+ * @param {number} forceAfterMs - if process doesn't die, SIGKILL after this many ms
+ * @returns {{ killed: boolean, agentName: string|null }}
+ */
+export function killAgentProcess(threadId, forceAfterMs = 3000) {
+    const e = _registry.get(threadId);
+    if (!e) return { killed: false, agentName: null };
+    if (e.killed) return { killed: true, agentName: e.agentName };
+    e.killed = true;
+    try {
+        e.process.kill('SIGTERM');
+        logger.warn('agent-process:sigterm', { threadId, agentName: e.agentName, pid: e.process.pid });
+    } catch (err) {
+        logger.error('agent-process:sigterm-failed', { threadId, error: err.message });
+    }
+    e.killTimer = setTimeout(() => {
+        try {
+            e.process.kill('SIGKILL');
+            logger.warn('agent-process:sigkill', { threadId, agentName: e.agentName });
+        } catch {}
+    }, forceAfterMs);
+    return { killed: true, agentName: e.agentName };
+}
+
+export function getAgentProcess(threadId) {
+    return _registry.get(threadId) || null;
+}
+
+export function listAgentProcesses() {
+    const out = [];
+    for (const [tid, e] of _registry.entries()) {
+        out.push({ threadId: tid, agentName: e.agentName, pid: e.process.pid, killed: e.killed });
+    }
+    return out;
+}
+
+/**
+ * Kill ALL registered agent processes (used during graceful shutdown).
+ * Sends SIGTERM first, escalates to SIGKILL after 1s to avoid hanging on stuck children.
+ * @param {number} forceAfterMs
+ * @returns {Array<{ threadId: string, agentName: string, killed: boolean }>}
+ */
+export function killAllAgentProcesses(forceAfterMs = 1000) {
+    const results = [];
+    for (const [tid, e] of _registry.entries()) {
+        if (e.killed) continue;
+        const r = killAgentProcess(tid, forceAfterMs);
+        results.push({ threadId: tid, agentName: r.agentName || e.agentName, killed: r.killed });
+    }
+    return results;
+}

package/dist/core/crypto.js

@@ -0,0 +1,80 @@
+// AES-256-GCM credential encryption
+// Key derived from machine fingerprint + user-level salt
+// Format: {iv, tag, data} all base64
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, createHash } from 'crypto';
+import { hostname, userInfo, homedir, platform } from 'os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+const SALT_FILE = join(homedir(), '.opencode-remote', '.cred_salt');
+
+function getMachineFingerprint() {
+    const parts = [
+        hostname(),
+        userInfo().username,
+        platform(),
+        homedir(),
+        process.env.COMPUTERNAME || '',
+    ].join('|');
+    return createHash('sha256').update(parts).digest('hex');
+}
+
+function getOrCreateSalt() {
+    const dir = join(homedir(), '.opencode-remote');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    if (existsSync(SALT_FILE)) {
+        return readFileSync(SALT_FILE);
+    }
+    const salt = randomBytes(32);
+    writeFileSync(SALT_FILE, salt, { mode: 0o600 });
+    return salt;
+}
+
+function deriveKey() {
+    const fp = getMachineFingerprint();
+    const salt = getOrCreateSalt();
+    return scryptSync(fp, salt, 32, { N: 16384, r: 8, p: 1 });
+}
+
+/**
+ * Encrypt a plain string with AES-256-GCM
+ * @param {string} plaintext
+ * @returns {string} JSON envelope {iv, tag, data} all base64
+ */
+export function encryptCredential(plaintext) {
+    if (plaintext == null) return null;
+    const key = deriveKey();
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const enc = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return JSON.stringify({
+        v: 1,
+        iv: iv.toString('base64'),
+        tag: tag.toString('base64'),
+        data: enc.toString('base64'),
+    });
+}
+
+export function decryptCredential(envelope) {
+    if (envelope == null) return null;
+    // 兼容旧明文 (不是 JSON envelope)
+    if (typeof envelope === 'string' && !envelope.startsWith('{')) {
+        return envelope;
+    }
+    try {
+        const obj = typeof envelope === 'string' ? JSON.parse(envelope) : envelope;
+        if (obj.v !== 1) return null;
+        const key = deriveKey();
+        const iv = Buffer.from(obj.iv, 'base64');
+        const tag = Buffer.from(obj.tag, 'base64');
+        const data = Buffer.from(obj.data, 'base64');
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAuthTag(tag);
+        const dec = Buffer.concat([decipher.update(data), decipher.final()]);
+        return dec.toString('utf8');
+    } catch (e) {
+        console.error('[crypto] decrypt failed:', e.message);
+        return null;
+    }
+}

package/dist/core/git-push.js

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
@@ -55,27 +55,47 @@ function parseOriginUrl(url) {
     return { auth, host, userRepo };
 }
 
-export function gitPush({ message, branch } = {}) {
+// Whitelist validation for git refs (branch names, remote names). Git itself
+// also validates these, but we add a defensive check so a malicious caller
+// can't pass things like "main && rm -rf /" (even though execFileSync + args
+// array would block shell injection on its own, this is defense in depth).
+function isValidGitRef(s) {
+    return typeof s === 'string' && /^[a-zA-Z0-9._\/-]+$/.test(s) && s.length > 0 && s.length < 256;
+}
+
+/**
+ * @param {{ message?: string, branch?: string }} [opts]
+ */
+export function gitPush(opts) {
+    const { message, branch } = opts || {};
     const cwd = process.cwd();
 
     let currentBranch;
     try {
-        currentBranch = execSync('git branch --show-current', { cwd, encoding: 'utf-8' }).trim();
+        currentBranch = execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf-8' }).trim();
     } catch (e) {
         return { ok: false, error: '不在 git 仓库中' };
     }
     const targetBranch = branch || currentBranch;
 
-    const status = execSync('git status --porcelain', { cwd, encoding: 'utf-8' }).trim();
+    // Defensive validation of branch name (caller-supplied)
+    if (branch && !isValidGitRef(branch)) {
+        return { ok: false, error: `非法 branch 名称: ${branch}` };
+    }
+
+    const status = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf-8' }).trim();
     if (status) {
-        execSync('git add -A', { cwd });
+        execFileSync('git', ['add', '-A'], { cwd });
         const msg = (message || `auto update ${new Date().toISOString().slice(0, 19)}`).replace(/"/g, '\\"');
-        execSync(`git commit -m "${msg}"`, { cwd, stdio: 'pipe' });
+        // execFileSync with args array — msg is passed as a single argv element
+        // to git, never interpreted by shell. Even if msg contains `;` or `&`
+        // or shell metachars, git just stores it as the commit message.
+        execFileSync('git', ['commit', '-m', msg], { cwd, stdio: 'pipe' });
     }
 
     let originUrl;
     try {
-        originUrl = execSync('git remote get-url origin', { cwd, encoding: 'utf-8' }).trim();
+        originUrl = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd, encoding: 'utf-8' }).trim();
     } catch (e) {
         return { ok: false, error: '没有找到 remote origin' };
     }
@@ -89,7 +109,7 @@ export function gitPush({ message, branch } = {}) {
     let pushAuth = parsed.auth;
     if (originUrl.startsWith('https://') && !originUrl.includes('@')) {
         try {
-            const ghToken = execSync('gh auth token', { encoding: 'utf-8' }).trim();
+            const ghToken = execFileSync('gh', ['auth', 'token'], { encoding: 'utf-8' }).trim();
             if (ghToken) {
                 pushAuth = `https://${ghToken}@`;
             }
@@ -104,17 +124,20 @@ export function gitPush({ message, branch } = {}) {
         const remoteName = `m_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
         console.log(`[git-push] trying ${host}...`);
         try {
-            execSync(`git remote add ${remoteName} "${pushUrl}"`, { cwd, stdio: 'pipe' });
-            execSync(`git push ${remoteName} ${targetBranch} --follow-tags`, { cwd, stdio: 'pipe', timeout: 30000 });
-            execSync(`git remote remove ${remoteName}`, { cwd, stdio: 'pipe' });
-            results.push({ host, ok: true });
+            // All execFileSync calls below use args arrays — no shell interpolation.
+            // remoteName, pushUrl, targetBranch, branch are passed as argv elements,
+            // never interpreted by shell.
+            execFileSync('git', ['remote', 'add', remoteName, pushUrl], { cwd, stdio: 'pipe' });
+            execFileSync('git', ['push', remoteName, targetBranch, '--follow-tags'], { cwd, stdio: 'pipe', timeout: 30000 });
+            execFileSync('git', ['remote', 'remove', remoteName], { cwd, stdio: 'pipe' });
+            results.push({ host, ok: true, url: pushUrl });
             return { ok: true, results, successUrl: pushUrl };
         } catch (e) {
-            try { execSync(`git remote remove ${remoteName}`, { cwd, stdio: 'pipe' }); } catch (_) {}
+            try { execFileSync('git', ['remote', 'remove', remoteName], { cwd, stdio: 'pipe' }); } catch (_) {}
             const msg = e.stderr?.toString()?.trim() || e.message || '';
-            results.push({ host, ok: false, error: msg.slice(0, 150) });
+            results.push({ host, ok: false, url: pushUrl, error: msg.slice(0, 150) });
         }
     }
 
     return { ok: false, results };
-}
+}