@jacksontian/kite-worker 0.1.0

package/config.example.yaml

@@ -0,0 +1,43 @@
+# kite Worker 配置模板（Mac Mini）。
+# 复制为实际配置文件（如 worker.yaml）后填写，启动时显式传入：
+#   node worker.js --config /path/to/worker.yaml
+# 实际配置文件含密钥，不要提交到 git。
+
+# 必填：云端 API 根地址（https；无证书的 VPS 可临时用 http，启动时会打印明文传输警告）
+apiUrl: https://your-vps.example.com
+
+# 必填：与云端 server 相同的签名密钥（永不在网络上传输，只用于本地 HMAC 签名）
+apiSecret: 换成你生成的密钥
+
+# Worker 标识，默认取 hostname
+workerId: mac-mini
+
+# 兜底轮询间隔（秒）；通知通道在线时任务即时送达，此值仅断线兜底用
+pollIntervalSec: 5
+
+# script 任务的白名单脚本目录；建议写绝对路径；相对路径相对启动工作目录解析
+scriptsDir: ./scripts
+
+# agent / shell / pty 任务的工作根目录；~ 展开为 HOME，同样建议绝对路径
+workspaceDir: ~/agent-workspace
+
+# Agent 注册表：commands 为「Agent 名: 命令模板」映射，{prompt} 会被替换为
+# $RW_PROMPT。注意：占位符必须放在引号内（否则带空格的 prompt 会被 shell 拆词）。
+# Agent 列表由心跳上报，手机端自动出现在下拉选择中
+agents:
+  # 任务未指定 Agent 时的默认值，必须存在于 commands 中
+  default: claude
+  commands:
+    claude: claude -p "{prompt}"
+    qoder: qodercli -p "{prompt}"
+
+# chat 任务的可选钩子，{message} 会被替换为 $RW_MESSAGE（同样要放引号内）；
+# 留空则只记入 workspace 的 inbox.log
+chatHook: ""
+
+# 单任务超时（秒）
+taskTimeoutSec: 1800
+
+# pty 交互终端会话空闲（无任何输入输出）回收秒数；
+# 交互会话不走 taskTimeoutSec，只按空闲超时回收
+ptyIdleTimeoutSec: 3600

package/config.js

@@ -0,0 +1,259 @@
+/**
+ * Mac Mini Worker 配置加载与校验。
+ *
+ * 只认 --config 指定的 YAML 配置文件（不再读取环境变量或 .env 文件）：
+ *   node worker.js --config /path/to/worker.yaml
+ * scriptsDir/workspaceDir 支持 ~ 展开；相对路径相对启动工作目录解析
+ * （launchd 请在 plist 里固定 WorkingDirectory），建议直接写绝对路径。
+ * 结构与类型校验由 zod schema 完成（CONFIG_SCHEMA）：未知配置项、
+ * 类型错误、缺必填项一次性报全后 exit 1；两个目录的可创建/可写校验
+ * 是运行时行为，仍在校验通过后单独执行。模板见包内 config.example.yaml。
+ */
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { z } from 'zod';
+
+/** 解析启动参数；--config 必填，缺失/重复/取不到值立即退出 */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const values = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--config' || args[i] === '-c') {
+      values.push(args[i + 1]);
+      i++;
+    } else if (args[i].startsWith('--config=')) {
+      values.push(args[i].slice('--config='.length));
+    }
+  }
+  if (values.length === 0) {
+    console.error('[worker] 缺少启动参数：node worker.js --config <配置文件路径>');
+    console.error('[worker] 配置模板见包内 config.example.yaml');
+    process.exit(1);
+  }
+  if (values.length > 1) {
+    console.error('[worker] --config 只能指定一次');
+    process.exit(1);
+  }
+  const file = String(values[0] ?? '').trim();
+  if (!file || file.startsWith('-')) {
+    console.error('[worker] --config 后需要给出配置文件路径');
+    process.exit(1);
+  }
+  return path.resolve(file);
+}
+
+function fail(errors, tag) {
+  console.error(`[${tag}] 配置错误，无法启动：`);
+  for (const e of errors) console.error('  - ' + e);
+  console.error(`[${tag}] 请检查 --config 指定的 YAML 文件，模板见包内 config.example.yaml`);
+  process.exit(1);
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/** 可选字符串：缺省/给 null 都按空串处理，统一 trim
+ * （zod v4 中 union(z.undefined()) 不能让对象键变可选，须用 .optional()） */
+const optStr = (errMsg) =>
+  z.string({ error: errMsg }).trim().optional().nullable().transform((v) => v ?? '');
+
+/** 正数字段（宽容接受数字字符串） */
+const posNum = (name) =>
+  z.coerce.number({ error: `${name} 必须是数字` }).positive(`${name} 必须是正数`);
+
+/** 把 zod issues 转成错误行：未知配置项逐条展开并附该层级可用项清单；
+ * custom/各叶子的报错文案均已自带字段名，直接透传 */
+function formatIssues(issues, knownByPath) {
+  const out = [];
+  for (const iss of issues) {
+    if (iss.code === 'unrecognized_keys') {
+      const known = knownByPath[iss.path.join('.')] || [];
+      for (const key of iss.keys) out.push(`未知配置项 "${key}"（可用：${known.join(', ')}）`);
+      continue;
+    }
+    // agents.commands 下的值错误补出 Agent 名上下文（文案本身不含字段名）
+    if (iss.path.length === 3 && iss.path[0] === 'agents' && iss.path[1] === 'commands') {
+      out.push(`agents.commands.${iss.path[2]} ${iss.message}`);
+      continue;
+    }
+    out.push(iss.message);
+  }
+  return out;
+}
+
+const AGENT_KNOWN = ['default', 'commands'];
+
+const CONFIG_SCHEMA = z.strictObject({
+  apiUrl: z
+    .string({
+      error: (iss) =>
+        iss.input === undefined || iss.input === null
+          ? '缺少 apiUrl（云端 API 根地址，如 https://api.example.com）'
+          : 'apiUrl 必须是字符串',
+    })
+    .trim()
+    .min(1, '缺少 apiUrl（云端 API 根地址，如 https://api.example.com）'),
+  apiSecret: z
+    .string({
+      error: (iss) =>
+        iss.input === undefined || iss.input === null
+          ? '缺少 apiSecret（与云端 server 相同的签名密钥）'
+          : 'apiSecret 必须是字符串（建议加引号，避免被 YAML 解析为数字）',
+    })
+    .trim()
+    .min(1, '缺少 apiSecret（与云端 server 相同的签名密钥）'),
+  workerId: optStr('workerId 必须是字符串'),
+  pollIntervalSec: posNum('pollIntervalSec').default(5),
+  // 路径语义（~ 展开 / 相对启动工作目录 / 可写校验）无法纯声明式表达，
+  // schema 只约束类型，解析后命令式处理
+  scriptsDir: optStr('scriptsDir 必须是字符串'),
+  workspaceDir: optStr('workspaceDir 必须是字符串'),
+  // 多 Agent 注册表：commands 为「Agent 名 -> 命令模板」映射，
+  // default 指定任务未指明 Agent 时的默认项
+  agents: z.strictObject(
+    {
+      default: z
+        .string({
+          error: (iss) =>
+            iss.input === undefined || iss.input === null
+              ? '缺少 agents.default（任务未指定 Agent 时的默认值）'
+              : 'agents.default 必须是字符串',
+        })
+        .trim()
+        .min(1, '缺少 agents.default（任务未指定 Agent 时的默认值）'),
+      commands: z
+        .record(z.string(), z.string({ error: '命令模板必须是字符串' }).trim(), {
+          error: 'agents.commands 必须是「Agent 名: 命令模板」的映射',
+        })
+        .superRefine((map, ctx) => {
+          for (const [name, tpl] of Object.entries(map)) {
+            if (!tpl) ctx.addIssue({ code: 'custom', message: `agents.commands.${name} 命令模板不能为空` });
+          }
+          if (!Object.keys(map).length) {
+            ctx.addIssue({ code: 'custom', message: 'agents.commands 至少要配置一个 Agent' });
+          }
+        }),
+    },
+    {
+      error: (iss) => {
+        if (iss.code === 'unrecognized_keys') return undefined; // 交给 formatIssues 出中文清单
+        return iss.input === undefined || iss.input === null
+          ? '缺少 agents 配置（至少包含 default 与 commands，见 config.example.yaml）'
+          : 'agents 必须是映射（含 default 与 commands 两个键）';
+      },
+    },
+  ),
+  chatHook: optStr('chatHook 必须是字符串'),
+  taskTimeoutSec: posNum('taskTimeoutSec').default(1800),
+  ptyIdleTimeoutSec: posNum('ptyIdleTimeoutSec').default(3600),
+});
+
+/** 加载并校验配置，返回归一化后的常量对象 */
+export async function loadWorkerConfig() {
+  const tag = 'worker';
+  const configFile = parseArgs();
+
+  let raw;
+  try {
+    raw = await fs.promises.readFile(configFile, 'utf8');
+  } catch (err) {
+    console.error(`[${tag}] 无法读取配置文件 ${configFile}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const doc = YAML.parseDocument(raw);
+  if (doc.errors.length) {
+    console.error(`[${tag}] 配置文件 YAML 语法错误（${configFile}）：`);
+    for (const e of doc.errors) console.error('  - ' + e.message);
+    process.exit(1);
+  }
+  const cfg = doc.toJS();
+  if (!isPlainObject(cfg)) {
+    console.error(`[${tag}] 配置文件内容必须是一个键值映射（${configFile}）`);
+    process.exit(1);
+  }
+
+  const parsed = CONFIG_SCHEMA.safeParse(cfg);
+  if (!parsed.success) {
+    fail(
+      formatIssues(parsed.error.issues, { '': Object.keys(CONFIG_SCHEMA.shape), agents: AGENT_KNOWN }),
+      tag,
+    );
+  }
+  const v = parsed.data;
+  const errors = [];
+
+  const apiUrl = v.apiUrl.replace(/\/+$/, '');
+  let parsedUrl = null;
+  try {
+    parsedUrl = new URL(apiUrl);
+  } catch {
+    errors.push(`apiUrl 不是合法 URL: "${apiUrl}"（检查是否带 https:// 前缀、有无多余空格）`);
+  }
+  if (parsedUrl && !['http:', 'https:'].includes(parsedUrl.protocol)) {
+    // 非 http(s) 协议（如 htp: 笔误）会被 URL 解析器宽容地接受，必须显式拦截
+    errors.push(`apiUrl 协议必须是 http/https，当前是 "${parsedUrl.protocol}"（检查是否笔误）`);
+  }
+  if (parsedUrl && parsedUrl.protocol === 'http:' && !['localhost', '127.0.0.1'].includes(parsedUrl.hostname)) {
+    // 无 HTTPS 证书的 VPS 只能走 HTTP：允许启动，但风险必须被看见。
+    // 密钥与任务内容在网络上明文传输，缓解措施见 README「仅 HTTP 部署」一节。
+    console.warn(
+      `[worker] 警告：apiUrl 是明文 HTTP（${apiUrl}），密钥签名可被链路上任意节点窃听。` +
+        '条件允许时请优先配置 HTTPS（如 Caddy 自动证书）。',
+    );
+  }
+
+  // Agent 名统一小写归一化；default 必须存在于 commands 中
+  const defaultAgent = v.agents.default.toLowerCase();
+  const agents = {};
+  for (const [name, tpl] of Object.entries(v.agents.commands)) {
+    agents[name.toLowerCase()] = tpl;
+  }
+  if (!agents[defaultAgent]) {
+    errors.push(`agents.default "${defaultAgent}" 不在 agents.commands 中（可用：${Object.keys(agents).join(', ')}）`);
+  }
+
+  // ~ 展开为主目录（YAML 不会替我们做这件事）；
+  // 相对路径相对启动工作目录解析（path.resolve 默认行为），建议写绝对路径
+  const expandHome = (p) =>
+    p === '~' ? os.homedir() : p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p;
+  const scriptsDir = path.resolve(expandHome(v.scriptsDir || 'scripts'));
+  const workspaceDir = path.resolve(expandHome(v.workspaceDir || path.join(os.homedir(), 'agent-workspace')));
+  // 启动前校验可创建、可写：误配在这里一次性报清（workspace 要写 inbox.log、
+  // agent 项目目录），而不是任务执行时才失败
+  for (const [name, dir] of [['scriptsDir', scriptsDir], ['workspaceDir', workspaceDir]]) {
+    try {
+      await fs.promises.mkdir(dir, { recursive: true });
+      const probe = path.join(dir, '.rw-write-probe');
+      await fs.promises.writeFile(probe, '');
+      await fs.promises.rm(probe);
+    } catch (err) {
+      if (err.code === 'EEXIST' || err.code === 'ENOTDIR') {
+        errors.push(`${name} 指向的路径已存在但不是目录：${dir}`);
+      } else {
+        errors.push(`${name} 无法创建或不可写（${dir}）：${err.message}；请确认运行用户对该目录有读写权限`);
+      }
+    }
+  }
+
+  if (errors.length) fail(errors, tag);
+
+  return {
+    configFile,
+    apiUrl,
+    apiSecret: v.apiSecret,
+    workerId: v.workerId || os.hostname(),
+    pollIntervalMs: v.pollIntervalSec * 1000,
+    scriptsDir,
+    workspaceDir,
+    agents,
+    defaultAgent,
+    chatHook: v.chatHook,
+    taskTimeoutMs: v.taskTimeoutSec * 1000,
+    ptyIdleTimeoutMs: v.ptyIdleTimeoutSec * 1000,
+  };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jacksontian/kite-worker",
+  "version": "0.1.0",
+  "description": "kite Mac Mini Worker：出站通知长连接 + 轮询兜底领取任务并执行（Agent CLI / Shell / 白名单脚本），不监听任何端口",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "kitew": "worker.js"
+  },
+  "main": "worker.js",
+  "files": [
+    "worker.js",
+    "config.js",
+    "scripts/",
+    "config.example.yaml"
+  ],
+  "keywords": [
+    "remote",
+    "agent",
+    "worker",
+    "polling",
+    "hmac"
+  ],
+  "scripts": {
+    "postinstall": "chmod +x node_modules/node-pty/prebuilds/*/spawn-helper 2>/dev/null || true"
+  },
+  "dependencies": {
+    "node-pty": "^1.1.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/scripts/hello.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# 示例白名单脚本：手机提交 script 任务时，脚本名填 hello.sh
+# 可以在这个目录下添加自己的脚本（备份、构建、拉数据等）
+set -euo pipefail
+
+echo "hello from mac-mini: $(date)"
+echo "args: $*"
+echo "workspace: $(pwd)"

package/worker.js

@@ -0,0 +1,522 @@
+#!/usr/bin/env node
+/**
+ * kite Mac Mini Worker
+ *
+ * 只向云端发起出站连接：任务到达通知走 /worker/ws 长连接（断线自动重连，
+ * 轮询兜底不丢任务），心跳 + 日志/结果上报走 HTTP 短连接。不监听任何端口。Node >= 24。
+ *
+ * 配置文件（--config 传入的 YAML 文件，唯一配置来源，不再读取环境变量或
+ * .env 文件；字段说明与模板见包内 config.example.yaml）：
+ *   apiUrl             必填，云端 API 根地址，如 https://api.example.com
+ *   apiSecret          必填，与云端一致的签名密钥（永不在网络上传输）
+ *   workerId           可选，默认取 hostname
+ *   pollIntervalSec    可选，兜底轮询间隔秒数（通知通道在线时任务即时送达），默认 5
+ *   scriptsDir         可选，script 任务的白名单脚本目录，默认 ./scripts；
+ *                      相对路径相对启动工作目录解析，支持 ~ 展开，建议写绝对路径
+ *   workspaceDir       可选，agent/shell 任务的工作目录，默认 ~/agent-workspace；
+ *                      两个目录启动前校验可创建、可写，不满足直接报错退出
+ *   agents             必填，Agent 注册表：commands 为「Agent 名: 命令模板」映射
+ *                      （{prompt} 占位符），default 指定任务未指明 Agent 时的默认项
+ *   chatHook           可选，chat 任务的自定义处理命令模板，
+ *                      未配置时仅记录到 workspace 的 inbox.log
+ *   taskTimeoutSec     可选，单任务超时秒数，默认 1800
+ *   ptyIdleTimeoutSec  可选，pty 交互终端会话空闲（无任何输入输出）回收秒数，默认 3600；
+ *                      交互会话不走 taskTimeoutSec，只按空闲超时回收
+ */
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { loadWorkerConfig } from './config.js';
+
+// pty 任务依赖 node-pty（原生模块）；装不上时其余任务类型不受影响，
+// 只是 pty 任务会以明确的错误信息失败
+let pty = null;
+try {
+  pty = await import('node-pty');
+} catch (err) {
+  console.warn(`[worker] node-pty 不可用（${err.message}），pty 交互终端任务将被拒绝；` +
+    '请执行 npm i node-pty 安装');
+}
+
+const {
+  configFile: CONFIG_FILE,
+  apiUrl: API_URL,
+  apiSecret: API_SECRET,
+  workerId: WORKER_ID,
+  pollIntervalMs: POLL_INTERVAL,
+  scriptsDir: SCRIPTS_DIR,
+  workspaceDir: WORKSPACE_DIR,
+  agents: AGENTS,
+  defaultAgent: DEFAULT_AGENT,
+  chatHook: CHAT_HOOK,
+  taskTimeoutMs: TASK_TIMEOUT,
+  ptyIdleTimeoutMs: PTY_IDLE_TIMEOUT,
+} = await loadWorkerConfig();
+
+// 非致命提醒：模板缺 {prompt} 占位符时任务仍会执行，但 prompt 会被静默丢弃
+for (const [name, tpl] of Object.entries(AGENTS)) {
+  if (!tpl.includes('{prompt}')) {
+    console.warn(`[worker] 警告：Agent "${name}" 的命令模板缺少 {prompt} 占位符，任务 prompt 将不会传给 CLI`);
+  }
+}
+
+// SCRIPTS_DIR/WORKSPACE_DIR 的存在性与可写性已由 config.js 启动校验保证
+
+// ---------------------------------------------------------------------------
+// HTTP 客户端：每个请求 HMAC 签名，密钥本身永不上网
+// ---------------------------------------------------------------------------
+
+function signHeaders(method, pathname, bodyStr) {
+  const ts = Math.floor(Date.now() / 1000);
+  const nonce = crypto.randomBytes(16).toString('hex');
+  const bodySha = crypto.createHash('sha256').update(bodyStr).digest('hex');
+  // 签名串必须与 server 一致：方法、完整路径、时间戳、nonce、请求体摘要
+  const sig = crypto
+    .createHmac('sha256', API_SECRET)
+    .update([method, pathname, ts, nonce, bodySha].join('\n'))
+    .digest('hex');
+  return { 'X-RW-Ts': String(ts), 'X-RW-Nonce': nonce, 'X-RW-Sig': sig };
+}
+
+async function api(pathname, body) {
+  const method = body === undefined ? 'GET' : 'POST';
+  const bodyStr = body === undefined ? '' : JSON.stringify(body);
+  const res = await fetch(API_URL + pathname, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      ...signHeaders(method, pathname, bodyStr),
+    },
+    body: body === undefined ? undefined : bodyStr,
+    // 避免云端/反代挂住连接时整个任务循环停摆
+    signal: AbortSignal.timeout(30_000),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`API ${res.status}: ${data.error || res.statusText}`);
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// 日志回传：缓冲 + 定时批量推送
+// ---------------------------------------------------------------------------
+
+function createLogSender(taskId) {
+  let buffer = [];
+  let timer = null;
+
+  async function flush() {
+    if (!buffer.length) return;
+    const lines = buffer;
+    buffer = [];
+    try {
+      await api(`/api/tasks/${taskId}/logs`, { lines });
+    } catch (err) {
+      console.error(`[worker] 日志推送失败: ${err.message}`);
+      // 推送失败时把日志放回队列头部，避免丢失
+      buffer = [...lines.slice(-500), ...buffer].slice(-1000);
+    }
+  }
+
+  return {
+    push(line) {
+      buffer.push(String(line).slice(0, 4000));
+      if (!timer) timer = setTimeout(() => { timer = null; flush(); }, 1500);
+    },
+    async done() {
+      if (timer) { clearTimeout(timer); timer = null; }
+      // 任务结束前最后一段日志有限次重试，避免静默丢失
+      for (let i = 0; i < 3 && buffer.length; i++) {
+        await flush();
+        if (buffer.length) await new Promise((r) => setTimeout(r, 1000));
+      }
+      buffer = [];
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 通用命令执行：流式收集 stdout/stderr，支持超时
+// ---------------------------------------------------------------------------
+
+function runCommand(command, { cwd, onLine, timeoutMs, extraEnv }) {
+  return new Promise((resolve) => {
+    const child = spawn('bash', ['-lc', command], {
+      cwd,
+      env: { ...process.env, ...extraEnv },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // detached：成为进程组组长，超时时可以整组杀掉（否则会留下孤儿孙进程）
+      detached: true,
+    });
+    let settled = false;
+    const killGroup = () => {
+      try { process.kill(-child.pid, 'SIGKILL'); } catch { /* 进程组已退出 */ }
+    };
+    const timeout = setTimeout(() => {
+      onLine(`[worker] 任务超时（${Math.round(timeoutMs / 1000)}s），终止进程组`);
+      killGroup();
+    }, timeoutMs);
+
+    const pipeLines = (stream) => {
+      let tail = '';
+      stream.setEncoding('utf8');
+      stream.on('data', (chunk) => {
+        const parts = (tail + chunk).split('\n');
+        tail = parts.pop();
+        for (const line of parts) onLine(line);
+      });
+      stream.on('end', () => { if (tail) onLine(tail); });
+    };
+    pipeLines(child.stdout);
+    pipeLines(child.stderr);
+
+    child.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      resolve(code ?? 1);
+    });
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      onLine(`[worker] 启动失败: ${err.message}`);
+      killGroup();
+      resolve(127);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 任务执行器
+// ---------------------------------------------------------------------------
+
+/** script 任务：只允许执行 SCRIPTS_DIR 下的白名单脚本 */
+async function execScript(task, log) {
+  const name = String(task.payload.script || '');
+  const args = Array.isArray(task.payload.args) ? task.payload.args : [];
+  if (!/^[\w.-]+$/.test(name)) throw new Error('非法脚本名');
+  const scriptPath = path.join(SCRIPTS_DIR, name);
+  if (!scriptPath.startsWith(SCRIPTS_DIR)) {
+    throw new Error(`脚本不存在或不在白名单目录: ${name}`);
+  }
+  try {
+    await fs.promises.access(scriptPath);
+  } catch {
+    throw new Error(`脚本不存在或不在白名单目录: ${name}`);
+  }
+  // 统一用 bash 执行，避免脚本缺少执行位导致 Permission denied
+  const quoted = ['bash', scriptPath, ...args.map((a) => `'${String(a).replace(/'/g, "'\\''")}'`)].join(' ');
+  log.push(`$ ${quoted}`);
+  const code = await runCommand(quoted, {
+    cwd: WORKSPACE_DIR,
+    onLine: (l) => log.push(l),
+    timeoutMs: TASK_TIMEOUT,
+  });
+  return { exitCode: code, ok: code === 0 };
+}
+
+/** shell 任务：在 WORKSPACE_DIR 执行任意命令 */
+async function execShell(task, log) {
+  const command = String(task.payload.command || '').trim();
+  if (!command) throw new Error('command 不能为空');
+  log.push(`$ ${command}`);
+  const code = await runCommand(command, {
+    cwd: WORKSPACE_DIR,
+    onLine: (l) => log.push(l),
+    timeoutMs: TASK_TIMEOUT,
+  });
+  return { exitCode: code, ok: code === 0 };
+}
+
+/** agent 任务：调用编码 Agent CLI（无头模式），prompt 由手机端下发 */
+async function execAgent(task, log) {
+  const prompt = String(task.payload.prompt || '').trim();
+  if (!prompt) throw new Error('prompt 不能为空');
+  const agent = String(task.payload.agent || DEFAULT_AGENT).toLowerCase();
+  const template = AGENTS[agent];
+  if (!template) {
+    throw new Error(`未配置的 Agent: ${agent}（可用：${Object.keys(AGENTS).join(', ')}）`);
+  }
+  const project = String(task.payload.project || 'default');
+  // 防止 ../../xxx 之类的目录名逃逸出 workspace
+  if (!/^[\w.-]+$/.test(project) || project.includes('..')) {
+    throw new Error(`非法项目目录名: ${project}`);
+  }
+  const workdir = path.join(WORKSPACE_DIR, project);
+  await fs.promises.mkdir(workdir, { recursive: true });
+  // 替换时不再加引号：由模板自身的引号保护（默认模板为 claude -p "{prompt}"），
+  // 否则会出现双重引号导致 $RW_PROMPT 落在引号外被 bash 拆词
+  const command = template.replace(/\{prompt\}/g, '$RW_PROMPT');
+  log.push(`[worker] cwd=${workdir}`);
+  log.push(`[worker] agent=${agent} command: ${template}`);
+  const code = await runCommand(command, {
+    cwd: workdir,
+    onLine: (l) => log.push(l),
+    timeoutMs: TASK_TIMEOUT,
+    extraEnv: { RW_PROMPT: prompt },
+  });
+  return { exitCode: code, ok: code === 0, workdir };
+}
+
+/** chat 任务：记入 inbox.log；配置了 CHAT_HOOK 则同时执行钩子 */
+async function execChat(task, log) {
+  const message = String(task.payload.message || '').trim();
+  if (!message) throw new Error('message 不能为空');
+  const stamp = new Date().toISOString();
+  await fs.promises.appendFile(path.join(WORKSPACE_DIR, 'inbox.log'), `[${stamp}] ${message}\n`);
+  log.push(`[worker] 已记入 inbox.log: ${message}`);
+  if (CHAT_HOOK) {
+    const command = CHAT_HOOK.replace(/\{message\}/g, '$RW_MESSAGE');
+    const code = await runCommand(command, {
+      cwd: WORKSPACE_DIR,
+      onLine: (l) => log.push(l),
+      timeoutMs: TASK_TIMEOUT,
+      extraEnv: { RW_MESSAGE: message },
+    });
+    return { exitCode: code, ok: code === 0 };
+  }
+  return { ok: true, note: '未配置 CHAT_HOOK，仅记录' };
+}
+
+/**
+ * pty 任务：node-pty 起真终端（bash -il），IO 走 /worker/ws 双向中继成
+ * 控制台上的 xterm.js 交互终端。与其他任务不同：
+ *   - 不套 TASK_TIMEOUT（交互式会话时长不可预期），改按空闲超时 PTY_IDLE_TIMEOUT 回收
+ *   - Promise 在 PTY 退出时才 resolve；期间输入/改尺寸/关闭由通知通道消息驱动
+ * 通知通道断开期间会话不杀：PTY 继续跑（输出暂存丢弃），重连后输入恢复可用
+ */
+const ptySessions = new Map(); // taskId -> { ptyProc, lastActiveAt }
+
+function execPty(task, log) {
+  return new Promise((resolve) => {
+    if (!pty) {
+      log.push('[worker] node-pty 未安装，无法启动交互终端（在 Worker 上执行 npm i node-pty）');
+      return resolve({ ok: false, error: 'node-pty 未安装' });
+    }
+    const project = String(task.payload.project || 'default');
+    // 与 agent 任务同规则：防目录名逃逸出 workspace
+    if (!/^[\w.-]+$/.test(project) || project.includes('..')) {
+      log.push(`[worker] 非法项目目录名: ${project}`);
+      return resolve({ ok: false, error: `非法项目目录名: ${project}` });
+    }
+    const workdir = path.join(WORKSPACE_DIR, project);
+    const cols = Math.max(2, Math.min(Number(task.payload.cols) || 80, 500));
+    const rows = Math.max(2, Math.min(Number(task.payload.rows) || 24, 200));
+
+    let proc;
+    try {
+      fs.promises.mkdir(workdir, { recursive: true }).catch(() => {});
+      proc = pty.spawn('bash', ['-il'], {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        cwd: workdir,
+        env: { ...process.env, TERM: 'xterm-256color' },
+      });
+    } catch (err) {
+      log.push(`[worker] PTY 启动失败: ${err.message}`);
+      return resolve({ ok: false, error: err.message });
+    }
+
+    const session = { ptyProc: proc, lastActiveAt: Date.now() };
+    ptySessions.set(task.id, session);
+    log.push(`[worker] 交互终端已启动: pid=${proc.pid} cwd=${workdir}`);
+    wsSend({ type: 'session.started', taskId: task.id, pid: proc.pid });
+
+    proc.onData((data) => {
+      session.lastActiveAt = Date.now();
+      // 通道断开时丢弃输出（无缓冲回放设计，重连后终端从当前画面继续）
+      wsSend({ type: 'session.output', taskId: task.id, data });
+    });
+    proc.onExit(({ exitCode }) => {
+      ptySessions.delete(task.id);
+      wsSend({ type: 'session.exited', taskId: task.id, exitCode });
+      log.push(`[worker] 终端会话结束，exit=${exitCode}`);
+      resolve({ ok: exitCode === 0, exitCode });
+    });
+
+    // 空闲回收：长时间无任何输入输出才杀，避免忘关的会话常驻
+    const idleTimer = setInterval(() => {
+      if (Date.now() - session.lastActiveAt > PTY_IDLE_TIMEOUT) {
+        clearInterval(idleTimer);
+        log.push(`[worker] 会话空闲超过 ${Math.round(PTY_IDLE_TIMEOUT / 1000)}s，已回收`);
+        try { proc.kill(); } catch { /* 已退出 */ }
+      }
+    }, 30 * 1000).unref();
+  });
+}
+
+/** 通知通道消息驱动的会话控制（输入/改尺寸/关闭），见 connectNotifyChannel */
+function handleSessionMessage(msg) {
+  const session = ptySessions.get(msg.taskId);
+  if (!session) return;
+  session.lastActiveAt = Date.now();
+  if (msg.type === 'session.input' && typeof msg.data === 'string') {
+    try { session.ptyProc.write(msg.data.slice(0, 65536)); } catch { /* 进程已退出 */ }
+  } else if (msg.type === 'session.resize') {
+    const cols = Math.max(2, Math.min(Number(msg.cols) || 80, 500));
+    const rows = Math.max(2, Math.min(Number(msg.rows) || 24, 200));
+    try { session.ptyProc.resize(cols, rows); } catch { /* 进程已退出 */ }
+  } else if (msg.type === 'session.close') {
+    try { session.ptyProc.kill(); } catch { /* 已退出 */ }
+  }
+}
+
+const EXECUTORS = { script: execScript, shell: execShell, agent: execAgent, chat: execChat, pty: execPty };
+
+// ---------------------------------------------------------------------------
+// 任务通知长连接：服务端建新任务即推 task.available，收到后立刻走 HTTP claim
+// 领取（原子性仍以 HTTP 为准）。心跳/日志/结果保持短连接。断线指数退避重连，
+// 断线窗口内的任务由轮询兜底，不丢任务。用 Node 24 内置 WebSocket，零依赖。
+// ---------------------------------------------------------------------------
+
+const WS_URL = API_URL.replace(/^http(s?):/, 'ws$1:') + '/worker/ws';
+let wsReconnectDelay = 1000;
+let wake = null; // 主循环休眠的唤醒信号
+let notifyWs = null; // 当前已鉴权的通知通道，pty 会话输出经它上行
+
+/** 向服务端发送通知通道消息；通道未就绪时静默丢弃（pty 输出可丢，不堆积背压） */
+function wsSend(msg) {
+  if (notifyWs && notifyWs.readyState === WebSocket.OPEN) {
+    notifyWs.send(JSON.stringify(msg));
+  }
+}
+
+/** 休眠至多 ms；期间收到任务通知（或通道断开需要补拉）时提前唤醒 */
+function sleepUntilWakeup(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    wake = done;
+    function done() {
+      clearTimeout(timer);
+      if (wake === done) wake = null;
+      resolve();
+    }
+  });
+}
+
+function connectNotifyChannel() {
+  const ws = new WebSocket(WS_URL);
+  ws.addEventListener('open', () => {
+    wsReconnectDelay = 1000;
+    notifyWs = ws; // 鉴权是首条消息，后续会话消息服务端按序处理，可提前挂载
+    // 鉴权方式与控制台 /ws 相同：sig = HMAC(密钥, "WS\nTS\nNONCE")
+    const ts = Math.floor(Date.now() / 1000);
+    const nonce = crypto.randomBytes(16).toString('hex');
+    const sig = crypto
+      .createHmac('sha256', API_SECRET)
+      .update(['WS', ts, nonce].join('\n'))
+      .digest('hex');
+    ws.send(JSON.stringify({ type: 'auth', workerId: WORKER_ID, ts, nonce, sig }));
+    console.log(`[worker] 通知通道已连接: ${WS_URL}`);
+    // 重连场景：把仍存活的 pty 会话重新上报，服务端将其挂到本条新连接
+    for (const taskId of ptySessions.keys()) {
+      ws.send(JSON.stringify({ type: 'session.started', taskId, reattach: true }));
+    }
+  });
+  ws.addEventListener('message', (ev) => {
+    let msg;
+    try {
+      msg = JSON.parse(String(ev.data));
+    } catch {
+      return;
+    }
+    if (msg.type === 'task.available') return wake?.();
+    // pty 会话的控制消息（输入/改尺寸/关闭）由服务端从控制台路由过来
+    if (msg.type && msg.type.startsWith('session.')) return handleSessionMessage(msg);
+  });
+  ws.addEventListener('close', () => {
+    if (notifyWs === ws) notifyWs = null;
+    console.warn(`[worker] 通知通道断开，${wsReconnectDelay / 1000}s 后重连（期间靠轮询兜底）`);
+    setTimeout(connectNotifyChannel, wsReconnectDelay);
+    wsReconnectDelay = Math.min(wsReconnectDelay * 2, 30_000);
+    // 断线前一刻可能刚建了任务，立即唤醒主循环去领一次
+    wake?.();
+  });
+  // 必须监听 error 事件：连接失败时未监听会让进程直接崩溃；
+  // 出错后主动 close，统一走 close 里的重连路径
+  ws.addEventListener('error', (ev) => {
+    console.error(`[worker] 通知通道错误: ${ev.error?.message || 'unknown'}`);
+    ws.close();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 主循环
+// ---------------------------------------------------------------------------
+
+async function runTask(task) {
+  const log = createLogSender(task.id);
+  const started = Date.now();
+  log.push(`[worker] 开始执行任务 ${task.type}: ${task.title || task.id}`);
+
+  // 执行与结果上报解耦：执行成功但上报抖动时重试即可，不能反转为 failed
+  let status;
+  let result;
+  try {
+    const r = await EXECUTORS[task.type](task, log);
+    status = r.ok ? 'done' : 'failed';
+    result = { ...r, durationMs: Date.now() - started };
+  } catch (err) {
+    log.push(`[worker] 错误: ${err.message}`);
+    status = 'failed';
+    result = { error: err.message, durationMs: Date.now() - started };
+  }
+
+  await log.done();
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      await api(`/api/tasks/${task.id}/finish`, { status, result });
+      return;
+    } catch (err) {
+      console.error(`[worker] finish 上报失败（${attempt}/3）: ${err.message}`);
+      await new Promise((r) => setTimeout(r, 2000 * attempt));
+    }
+  }
+  console.error(`[worker] finish 上报最终失败，任务 ${task.id} 实际状态: ${status}`);
+}
+
+async function heartbeat() {
+  try {
+    await api('/api/worker/heartbeat', {
+      workerId: WORKER_ID,
+      hostname: os.hostname(),
+      node: process.version,
+      agents: Object.keys(AGENTS),
+    });
+  } catch {
+    // 网络抖动忽略，下一轮重试
+  }
+}
+
+async function main() {
+  console.log(`[worker] ${WORKER_ID} 启动，API=${API_URL}，兜底轮询间隔 ${POLL_INTERVAL / 1000}s`);
+  console.log(`[worker] 配置文件: ${CONFIG_FILE}`);
+  await heartbeat();
+  setInterval(heartbeat, 30 * 1000);
+  connectNotifyChannel();
+
+  for (;;) {
+    try {
+      const { task } = await api('/api/worker/claim', { workerId: WORKER_ID });
+      if (task) {
+        if (task.type === 'pty') {
+          // 交互会话可能长时间挂着，异步执行，不阻塞领取其他任务
+          runTask(task).catch((err) => console.error(`[worker] pty 任务异常: ${err.message}`));
+        } else {
+          await runTask(task);
+        }
+        continue; // 领到任务就立刻看下一个
+      }
+    } catch (err) {
+      console.error(`[worker] 轮询失败: ${err.message}`);
+    }
+    // 通知通道在线时，新任务推送会提前唤醒；断线则按轮询间隔兜底
+    await sleepUntilWakeup(POLL_INTERVAL);
+  }
+}
+
+main();