chrome-control-proxy 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# chrome-control-proxy
+
+在宿主机上提供 **HTTP 代理服务**，用于：
+
+- 启动 / 停止 / 重启带 **远程调试端口（默认 9222）** 的 Chrome
+- 通过 **Playwright（CDP 连接）** 提供 `page-dom`、脚本执行等能力，供本机或 Docker 内 OpenClaw 等客户端调用
+
+**要求：Node.js ≥ 18**（Playwright 与 Express 5 需要）。
+
+---
+
+## 安装
+
+全局安装（推荐，可在任意目录执行 `ccp`）：
+
+```bash
+npm install -g chrome-control-proxy
+```
+
+验证：
+
+```bash
+ccp help
+ccp status   # 需先启动服务，否则显示 unreachable
+```
+
+---
+
+## CLI：`ccp`
+
+管理 **HTTP 服务进程**（`node index.js`），不是替代 `curl` 调接口。
+
+| 命令 | 说明 |
+|------|------|
+| `ccp start` | 后台启动服务，PID 写入 `CCP_PID_FILE`（默认系统临时目录下 `chrome-control-proxy.pid`），日志默认 `chrome-control-proxy.log` |
+| `ccp stop` | 按 PID 结束进程；若无 PID 或失败，会 `pkill -f` 匹配本包 `index.js` 路径 |
+| `ccp restart` | `stop` 后 `start` |
+| `ccp status` | 请求 `GET /health`、`/browser/status`、`/playwright/status`（服务不可达时退出码 1） |
+
+环境变量：
+
+| 变量 | 含义 |
+|------|------|
+| `PORT` | HTTP 端口，默认 `3333` |
+| `HOST` | 绑定地址，默认 `127.0.0.1` |
+| `CHROME_PORT` | Chrome 远程调试端口，默认 `9222` |
+| `CHROME_PROFILE_DIR` | Chrome 用户数据目录 |
+| `CHROME_BINARY` | Chrome 可执行文件路径 |
+| `CDP_URL` | Playwright 连接地址，默认 `http://127.0.0.1:${CHROME_PORT}` |
+| `PLAYWRIGHT_PAGE_DEFAULT_TIMEOUT_MS` | `locator`/`click` 等未写 `timeout` 时的默认上限，默认 **60000**（避免 CDP 页面上仍为 10s 导致 `waitFor` 易超时） |
+| `PLAYWRIGHT_NAVIGATION_DEFAULT_TIMEOUT_MS` | `goto` 等导航默认上限，未设时取 **max(动作超时, 90000)** |
+| `JSON_BODY_LIMIT` | 请求体大小上限，默认 `16mb` |
+| `LOG_LEVEL` | 日志级别：`error` / `warn` / `info` / `debug`，默认 `info` |
+| `LOG_DIR` | 若设置，除控制台外**按日期写入目录**：`ccp-YYYY-MM-DD.log` |
+| `LOG_MAX_FILE_MB` | 单日单文件最大体积（MB），超出则同日内分片为 `…-YYYY-MM-DD.1.log`、`.2.log`…；不设置则不按大小切分 |
+| `LOG_CONSOLE` | 是否仍输出到 stdout/stderr，默认 `true`；仅写文件时可设 `false` |
+| `CCP_PID_FILE` | 覆盖 PID 文件路径 |
+| `CCP_LOG_FILE` | `ccp start` 子进程 stdout/stderr 重定向文件（与 `LOG_DIR` 应用内日志不同） |
+
+前台直接运行（不用 `ccp`）：
+
+```bash
+npm start
+# 或
+node index.js
+```
+
+日志默认输出到 **stdout**，前缀为 `[chrome-control-proxy]`。设置 **`LOG_DIR`** 后，会额外写入按日期的文件（可选 **`LOG_MAX_FILE_MB`** 按大小分片）。`ccp start` 后台进程仍可将输出重定向到 **`CCP_LOG_FILE`**，与应用内 `LOG_DIR` 可分开配置。生产环境也可用系统 **logrotate** 管理 `LOG_DIR` 下文件。
+
+---
+
+## HTTP 接口一览
+
+### 健康与 Chrome
+
+| 路径 | 方法 | 说明 |
+|------|------|------|
+| `/health` | GET | 服务与 Chrome 端口探测 |
+| `/browser/status` | GET | Chrome 是否在监听 |
+| `/browser/start` | POST | 启动 Chrome（带 `--remote-debugging-port`） |
+| `/browser/stop` | POST | 结束 Chrome |
+| `/browser/restart` | POST | 重启 Chrome |
+
+### Playwright（与 `/browser/start` 启动的 Chrome 同一 CDP）
+
+| 路径 | 方法 | 说明 |
+|------|------|------|
+| `/playwright/status` | GET | CDP 是否可连 |
+| `/playwright/page-dom` | POST | 页面快照：HTML / innerText / a11y / **Playwright 专用可交互列表** |
+| `/playwright/run` | POST | 在 VM 中执行用户脚本（注入 `page`、`context`、`browser`） |
+
+`POST /playwright/page-dom` 与 `POST /playwright/run` 在服务端 **串行排队**，避免多请求抢同一浏览器。
+
+---
+
+## 调用示例（宿主机）
+
+```bash
+curl -s http://127.0.0.1:3333/health
+curl -s -X POST http://127.0.0.1:3333/browser/start
+curl -s http://127.0.0.1:3333/playwright/status
+```
+
+## 调用示例（Docker 内访问宿主机）
+
+将 `127.0.0.1` 换成 `host.docker.internal`（Mac/Win Docker Desktop 常见；Linux 可能需 `extra_hosts`）。
+
+```bash
+curl -s http://host.docker.internal:3333/health
+```
+
+---
+
+## `POST /playwright/page-dom` 要点
+
+- **`includeHtml: false`**：不返回整页 HTML，利于降 token。
+- **`includePlaywrightSnapshot: true`**：返回 `playwright.targets[]`（含 **`suggestedLocator`**），便于生成脚本。
+- **`selector`**：只截取子树。
+- **`includeInnerText` / `includeAccessibility`**：按需打开。
+
+---
+
+## `POST /playwright/run` 要点
+
+- 脚本为 **async 函数体**，可 `await`、`return`；返回值会尽量 JSON 序列化后返回。
+- **不要在请求体里同时滥用外层 `url` 与脚本内 `goto`**：若外层传 `url`，会先导航再执行脚本；**退出登录再登录** 等流程宜 **外层不传 `url`**，只在脚本里 `clearCookies` + `goto`。
+- 默认 **`scriptTimeout`** 见环境变量 `PLAYWRIGHT_RUN_DEFAULT_MS`。
+
+---
+
+## 安全与边界
+
+- 默认只监听 `127.0.0.1`；若改为 `0.0.0.0` 暴露局域网，需自行鉴权。
+- `/playwright/run` 执行用户脚本，仅适用于可信环境。
+- 测试账号与密码勿写入仓库。
+
+---
+
+## OpenClaw 集成说明
+
+更完整的调用顺序、踩坑说明见仓库内 **`host-chrome-control/SKILL.md`**（随代码维护；**不会**打进 `npm pack` 的默认包文件，clone 仓库即可见）。

package/bin/ccp.js

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, execSync } = require('child_process');
+const log = require(path.join(__dirname, '..', 'lib', 'logger.js'));
+
+const ROOT = path.resolve(__dirname, '..');
+const INDEX_JS = path.join(ROOT, 'index.js');
+const PID_FILE = process.env.CCP_PID_FILE || path.join(os.tmpdir(), 'chrome-control-proxy.pid');
+const LOG_FILE = process.env.CCP_LOG_FILE || path.join(os.tmpdir(), 'chrome-control-proxy.log');
+const HOST = process.env.HOST || '127.0.0.1';
+const PORT = Number(process.env.PORT) || 3333;
+
+function sleepSync(ms) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    /* spin */
+  }
+}
+
+function httpJson(method, p) {
+  return new Promise((resolve, reject) => {
+    const opts = {
+      hostname: HOST,
+      port: PORT,
+      path: p,
+      method,
+      timeout: 8000,
+    };
+    const req = http.request(opts, (res) => {
+      let d = '';
+      res.on('data', (c) => {
+        d += c;
+      });
+      res.on('end', () => {
+        try {
+          resolve(d ? JSON.parse(d) : {});
+        } catch {
+          resolve({ raw: d });
+        }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('timeout'));
+    });
+    req.end();
+  });
+}
+
+function readPid() {
+  try {
+    const n = Number(fs.readFileSync(PID_FILE, 'utf8').trim());
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+function isAlive(pid) {
+  if (!pid) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function serviceReachable() {
+  try {
+    const h = await httpJson('GET', '/health');
+    return Boolean(h && h.ok);
+  } catch {
+    return false;
+  }
+}
+
+async function cmdStatus() {
+  const pid = readPid();
+  console.log(`ccp: pid file ${PID_FILE}`);
+  if (pid) {
+    console.log(`ccp: recorded pid ${pid} ${isAlive(pid) ? '(running)' : '(not running)'}`);
+  }
+  const up = await serviceReachable();
+  console.log(`ccp: http://${HOST}:${PORT} ${up ? 'reachable' : 'unreachable'}`);
+  if (!up) {
+    process.exit(1);
+  }
+  try {
+    const h = await httpJson('GET', '/health');
+    console.log('health:', JSON.stringify(h, null, 2));
+  } catch (e) {
+    console.error('health:', e.message);
+  }
+  try {
+    const b = await httpJson('GET', '/browser/status');
+    console.log('browser:', JSON.stringify(b, null, 2));
+  } catch (e) {
+    console.error('browser:', e.message);
+  }
+  try {
+    const p = await httpJson('GET', '/playwright/status');
+    console.log('playwright:', JSON.stringify(p, null, 2));
+  } catch (e) {
+    console.error('playwright:', e.message);
+  }
+}
+
+async function cmdStart() {
+  log.info('ccp', 'start requested', { port: PORT, host: HOST });
+  if (await serviceReachable()) {
+    log.warn('ccp', 'service already responding', { port: PORT });
+    console.error('ccp: service already responding on port', PORT);
+    process.exit(1);
+  }
+  const oldPid = readPid();
+  if (oldPid && isAlive(oldPid)) {
+    log.warn('ccp', 'stale pid file', { pid: oldPid });
+    console.error('ccp: stale pid file points to running process', oldPid);
+    process.exit(1);
+  }
+  if (oldPid && !isAlive(oldPid)) {
+    try {
+      fs.unlinkSync(PID_FILE);
+    } catch {
+      /* */
+    }
+  }
+
+  let logFd;
+  try {
+    logFd = fs.openSync(LOG_FILE, 'a');
+  } catch {
+    logFd = 'ignore';
+  }
+
+  const child = spawn(process.execPath, [INDEX_JS], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    cwd: ROOT,
+    env: { ...process.env },
+  });
+  child.unref();
+  fs.writeFileSync(PID_FILE, String(child.pid));
+  log.info('ccp', 'spawned server process', { pid: child.pid, logFile: LOG_FILE, index: INDEX_JS });
+  console.log('ccp: started pid', child.pid);
+  console.log('ccp: log', LOG_FILE);
+
+  sleepSync(400);
+  if (await serviceReachable()) {
+    log.info('ccp', 'service reachable');
+    console.log('ccp: service is up');
+  } else {
+    log.error('ccp', 'service not reachable after start', new Error(`check ${LOG_FILE}`));
+    console.error('ccp: service not yet reachable; check log:', LOG_FILE);
+    process.exit(1);
+  }
+}
+
+function killProcessTree(pid) {
+  if (!isAlive(pid)) {
+    return;
+  }
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch {
+    /* */
+  }
+  for (let i = 0; i < 40; i++) {
+    if (!isAlive(pid)) {
+      return;
+    }
+    sleepSync(100);
+  }
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    /* */
+  }
+}
+
+function cmdStop() {
+  log.info('ccp', 'stop requested', { pidFile: PID_FILE });
+  const pid = readPid();
+  if (pid && isAlive(pid)) {
+    log.info('ccp', 'killing pid', { pid });
+    killProcessTree(pid);
+  }
+  try {
+    fs.unlinkSync(PID_FILE);
+  } catch {
+    /* */
+  }
+  try {
+    const esc = INDEX_JS.replace(/'/g, "'\\''");
+    execSync(`pkill -f '${esc}'`, { stdio: 'ignore' });
+  } catch {
+    /* */
+  }
+  log.info('ccp', 'stop finished');
+  console.log('ccp: stopped');
+}
+
+async function cmdRestart() {
+  log.info('ccp', 'restart requested');
+  cmdStop();
+  sleepSync(500);
+  await cmdStart();
+}
+
+function printHelp() {
+  console.log(`Usage: ccp <command>
+
+Commands:
+  start    Start HTTP proxy (node index.js), write pid to ${PID_FILE}
+  stop     Stop process from pid file, fallback pkill by index.js path
+  restart  stop then start
+  status   GET /health, /browser/status, /playwright/status
+
+Environment:
+  PORT           HTTP port (default 3333)
+  HOST           Bind host (default 127.0.0.1)
+  CCP_PID_FILE   Override pid file path
+  CCP_LOG_FILE   Override log file path
+`);
+}
+
+async function main() {
+  const sub = process.argv[2] || 'help';
+  switch (sub) {
+    case 'start':
+      await cmdStart();
+      break;
+    case 'stop':
+      cmdStop();
+      break;
+    case 'restart':
+      await cmdRestart();
+      break;
+    case 'status':
+      await cmdStatus();
+      break;
+    case 'help':
+    case '-h':
+    case '--help':
+      printHelp();
+      break;
+    default:
+      console.error('ccp: unknown command:', sub);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  log.error('ccp', 'cli fatal', e);
+  console.error(e);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,198 @@
+const express = require('express');
+const log = require('./lib/logger');
+const {
+  getChromeStatus,
+  startChrome,
+  stopChrome,
+  restartChrome,
+} = require('./lib/browser-controller');
+const {
+  CDP_URL,
+  PLAYWRIGHT_RUN_DEFAULT_MS,
+  getPlaywrightBrowser,
+  enqueuePlaywright,
+  getPageDomPayload,
+  runPlaywrightUserScript,
+  packScriptReturnValue,
+} = require('./lib/playwright-controller');
+
+process.on('uncaughtException', (e) => {
+  log.error('process', 'uncaughtException', e);
+  process.exit(1);
+});
+process.on('unhandledRejection', (r) => {
+  log.error('process', 'unhandledRejection', r);
+});
+
+function shutdown(signal) {
+  log.info('server', `shutdown ${signal}`);
+  const { closeFileSink } = require('./lib/logger');
+  closeFileSink()
+    .catch(() => {})
+    .finally(() => {
+      process.exit(0);
+    });
+}
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+const app = express();
+const JSON_BODY_LIMIT = process.env.JSON_BODY_LIMIT || '16mb';
+app.use(express.json({ limit: JSON_BODY_LIMIT }));
+
+app.use((req, res, next) => {
+  const t0 = Date.now();
+  res.on('finish', () => {
+    log.info('http', `${req.method} ${req.path} -> ${res.statusCode} ${Date.now() - t0}ms`);
+  });
+  next();
+});
+
+const HOST = process.env.HOST || '127.0.0.1';
+const PORT = process.env.PORT || 3333;
+
+function sendPlaywrightError(res, err) {
+  log.error('http', `response error ${err.code || 500}`, err);
+  const currentUrl = err.currentUrl;
+  const base = {
+    ok: false,
+    error: err.message || String(err),
+    ...(currentUrl && { currentUrl }),
+    ...(err.name && err.name !== 'Error' && { errorName: err.name }),
+  };
+  if (err.code === 'CHROME_DOWN') {
+    return res.status(503).json({ ...base, code: err.code });
+  }
+  return res.status(500).json(base);
+}
+
+app.get('/health', async (_req, res) => {
+  const status = await getChromeStatus();
+  res.json({
+    ok: true,
+    service: 'chrome-control',
+    browser: status,
+  });
+});
+
+app.get('/browser/status', async (_req, res) => {
+  const status = await getChromeStatus();
+  res.json({
+    ok: true,
+    ...status,
+  });
+});
+
+app.post('/browser/start', async (_req, res) => {
+  log.info('http', 'POST /browser/start');
+  const result = await startChrome();
+  res.json({
+    ok: true,
+    ...result,
+  });
+});
+
+app.post('/browser/stop', async (_req, res) => {
+  log.info('http', 'POST /browser/stop');
+  const result = await stopChrome();
+  res.json({
+    ok: true,
+    ...result,
+  });
+});
+
+app.post('/browser/restart', async (_req, res) => {
+  log.info('http', 'POST /browser/restart');
+  const result = await restartChrome();
+  res.json({
+    ok: true,
+    ...result,
+  });
+});
+
+app.get('/playwright/status', async (_req, res) => {
+  try {
+    const browser = await getPlaywrightBrowser();
+    res.json({
+      ok: true,
+      connected: browser.isConnected(),
+      cdpUrl: CDP_URL,
+      contextCount: browser.contexts().length,
+    });
+  } catch (err) {
+    sendPlaywrightError(res, err);
+  }
+});
+
+app.post('/playwright/page-dom', async (req, res) => {
+  try {
+    const b = req.body || {};
+    log.info('http', 'POST /playwright/page-dom');
+    const payload = await enqueuePlaywright(() =>
+      getPageDomPayload({
+        url: b.url,
+        waitUntil: b.waitUntil || 'load',
+        timeout: b.timeout ?? 30000,
+        target: b.target || 'first',
+        maxHtmlChars: b.maxHtmlChars,
+        maxTextChars: b.maxTextChars,
+        maxA11yChars: b.maxA11yChars,
+        maxPlaywrightJsonChars: b.maxPlaywrightJsonChars,
+        selector: b.selector,
+        includeHtml: b.includeHtml !== false,
+        includeInnerText: Boolean(b.includeInnerText),
+        includeAccessibility: Boolean(b.includeAccessibility),
+        includePlaywrightSnapshot: Boolean(b.includePlaywrightSnapshot),
+        maxPlaywrightTargets: b.maxPlaywrightTargets,
+      }),
+    );
+    res.json({
+      ok: true,
+      step: 'page-dom',
+      ...payload,
+    });
+  } catch (err) {
+    sendPlaywrightError(res, err);
+  }
+});
+
+app.post('/playwright/run', async (req, res) => {
+  try {
+    const { script, url, waitUntil, timeout, target, scriptTimeout } = req.body || {};
+    if (script === undefined || script === null || script === '') {
+      log.warn('http', 'POST /playwright/run rejected: empty script');
+      return res.status(400).json({ ok: false, error: 'script is required' });
+    }
+    log.info('http', 'POST /playwright/run', { scriptLen: String(script).length });
+    const { page, result } = await enqueuePlaywright(() =>
+      runPlaywrightUserScript(String(script), {
+        url,
+        waitUntil,
+        timeout,
+        target,
+        scriptTimeout: scriptTimeout ?? PLAYWRIGHT_RUN_DEFAULT_MS,
+      }),
+    );
+    res.json({
+      ok: true,
+      step: 'run',
+      currentUrl: page.url(),
+      ...packScriptReturnValue(result),
+    });
+  } catch (err) {
+    if (err.code === 'BAD_SCRIPT' || err.code === 'SCRIPT_TOO_LARGE') {
+      log.warn('http', `playwright/run client error ${err.code}`, err.message);
+      return res.status(400).json({
+        ok: false,
+        error: err.message,
+        code: err.code,
+        ...(err.currentUrl && { currentUrl: err.currentUrl }),
+      });
+    }
+    sendPlaywrightError(res, err);
+  }
+});
+
+app.listen(PORT, HOST, () => {
+  log.info('server', `listening http://${HOST}:${PORT}`, { cdpUrl: CDP_URL });
+});