fix(local): 预览网关按 executor/preview.js 对齐数据面,去掉白屏与冷启动卡顿

对照服务器实现(executor/preview.js)逐条补齐,这些不是优化而是缺功能:

- vendor 页把根绝对 `/` 当作「自身最新 HTML」比对,网关必须按 Referer 把它转给 watch。
  原来只转 `/events`、`/api/*`,`/` 回 404 → 页面判定自身过期 → location.reload(),
  用户看到的就是白屏后重新加载
- 就绪判定改为真发一次 `GET /`(首帧渲染在那次请求里完成);裸 TCP 连上只说明 Kestrel bind 好了
- HEAD 探针等槽位就绪(上限 15s)再回 200:冷启动渲染不再落到 iframe 的导航请求上
- 导航请求绝不为启动/自愈阻塞:未就绪或外部改动 → 立刻中转页 + 后台热槽;缺尾斜杠补 301
- 外部写盘靠 mtime 指纹 + 2s 轮询 POST /api/switch 触发重读;实现 __pv-touch(编辑命令的事后一脚)
- 转发看门狗、conns 计数、失败摘槽并原地复活重试一次、404 带 no-store

本地实测:冷 HEAD 3.3s 回 200、热导航 10ms、根绝对 / 与页面 HTML 逐字节相同、冷启动导航
2.7ms 回中转页、touch 后 SSE 收到 action:full、kill -9 watch 后自动换代重起。

顺带给 office 封装层注入 OFFICE_GATEWAY_PORT(它那段 __pv-touch 写死 3100)。
This commit is contained in:
2026-11-11 22:34:47 +08:00
parent f6665e904e
commit ffca861dc1
3 changed files with 486 additions and 198 deletions
+12 -3
View File
@@ -337,10 +337,14 @@ health 只作为「端口上有服务但不是本启动器拉起的」兜底提
于是本地网关只剩数据面:
- `/preview/<会话id>/<相对路径>` → 解析真实文件 → 确保有 watch → 剥前缀转发
- `/events`(SSE)与 `/api/*`(选区回读、切换、发送)→ 按 `Referer` 认领槽位再转发
- `/`、`/events`(SSE)与 `/api/*` → 按 `Referer` 认领槽位转发(`/` 尤其关键:vendor 把根绝对
`/` 当「自身最新 HTML」比对,回 404 它就 `location.reload()`,用户看到的是白屏后重载)
- 4 个槽位,LRU 挤占 + 闲置回收;watch 端口从 26315 起按代轮转,跳过已被占用的
- 槽位带活性校验:watch 自己退了(vendor 崩溃/被外部 kill)就丢掉槽位重起,转发出错也立即丢;
否则那份 dead port 会一直转到下次闲置回收,面板上只有一句「预览服务不可达」
- 就绪 = 真发一次 `GET /`(首帧渲染在那次请求里完成);裸 TCP 连上只说明 Kestrel bind 好了
- HEAD 探针等槽位就绪再回 200(有上限):冷启动渲染不落到 iframe 的导航请求上
- 导航请求绝不为启动/自愈阻塞:未就绪或外部改动 → 立刻中转页 + 后台热槽;缺尾斜杠补 301
- 外部写盘靠 mtime 指纹 + 2s 轮询 `POST /api/switch` 触发重读;`__pv-touch` 是编辑命令的事后一脚
- 槽位带活性校验:watch 自己退了就丢掉重起,转发出错也立即摘槽(GET/HEAD 再自愈重试一次)
- 缺 `officecli` 时给「安装说明页」,而不是无限转圈:服务器那份二进制是构建期必装的,
`preview.js` 从没为「没装」设计;本地全新 clone 一定没有,这是常态不是异常
@@ -386,6 +390,11 @@ POSIX 补 `chmod +x`、`officecli-*` 资产名也认)。其余只用 Node 内
| 预览数据面:`/events` 是真 SSE、`/api/selection` 204、`/api/send` 200;无 `Referer` 404 | 通过 |
| 缺 `officecli`:给安装说明页,HEAD 仍 200(面板不闪死链) | 通过 |
| 网关退出:watch 端口释放,无残留进程 | 通过 |
| 冷 HEAD 等首帧(3.3s)回 200;随后热导航 10ms 拿到页面 | 通过 |
| vendor 的根绝对 `/`(带 Referer):200 且与页面 HTML 逐字节相同(不再触发 `location.reload()` 白屏) | 通过 |
| 冷启动导航:2.7ms 回中转页(不等启动),4 秒后刷新即真页面 | 通过 |
| 缺尾斜杠导航:301 到带斜杠的页面 | 通过 |
| `__pv-touch`:命中活槽位 → `{"touched":true}`;外部 `touch` 文件 → 2s 轮询 POST `/api/switch` → SSE 收到 `"action":"full"` | 通过 |
| 槽位自愈:`kill -9` 掉 watch 后再请求,自动在下一代端口重起(26315 → 26316),页面照常返回 | 通过 |
| 经 core 的 `/preview` 端到端(含手选工作目录、`work_dir` 在 `tasks/` 外的会话) | 待复验 |
| `osascript` 真实选目录弹窗 | 未验证(用桩跑的「没选→回落 `~/AgentWork`」分支) |
+473 -195
View File
@@ -1,19 +1,26 @@
#!/usr/bin/env node
// local/preview-gateway.js —— 本地 office 文档预览网关(对位服务器上 executor 的 :3100)。
//
// 为什么要有它:服务器上「点开 docx」这条链路是 core → 反代 /preview → executor 预览网关 →
// 为什么要有它:服务器上「点开 docx」这条链是 core → 反代 /preview → executor 预览网关 →
// 网关自己按需 spawn `officecli watch`。本地没有 executor,那条链路会断,面板里是个空 iframe。
// 这里用零依赖 Node 复刻网关的数据面,但不复刻它的隔离层:
// 服务器给 watch 造 pid/mount ns 牢笼、bind 挂会话 .tmp 到 /tmp,是为了让**沙箱里的命令**
// 这里用零依赖 Node 复刻 executor/preview.js 的**数据面**,但不复刻它的隔离层:
// 服务器给 watch 造 pid/mount ns 牢笼、bind 会话 .tmp 到 /tmp,是为了让**沙箱里的命令**
// 和 watch 看见同一个世界(vendor 用 TMPDIR 下的 .port 文件 + TCP 回环发现彼此)。
// 本地既没有沙箱,命令和 watch 本来就在同一个文件系统、同一个临时目录里,
// 那些 unshare/nsenter 不但用不上,有些平台上根本不存在。于是这里只剩四件事:
// 那些 unshare/nsenter 不但用不上,有些平台上根本不存在。于是这里只剩数据面:
//
// 1. /preview/<会话id>/<相对路径>/ → 解析成真实文件 → 确保它有 watch → 转发
// 2. /events(SSE)与 /api/*(选区/改内容/切换)→ 按 Referer 找归属的 watch 转发
// 2. 页内数据面(/events、/api/*、以及 vendor 拿去比对自身的 /)→ 按 Referer 认领槽位转发
// 3. 槽位:最多 N 个并发 watch,挤占最久未用的,闲置回收
// 4. 缺 officecli 时给人能看懂的一页,而不是无限转圈(服务器那份二进制是构建期必装的,
// 所以它没为「没装」设计过;本地全新 clone 一定没有,这是常态不是异常)
// 所以 executor 那份没为「没装」设计过;本地全新 clone 一定没有,这是常态不是异常)
//
// 与服务器实现逐条对齐的几处(都踩过,别简化掉):
// - 探活 = 真发一次 `GET /`(首帧渲染就在这次请求里完成),裸 TCP 连上只说明 Kestrel bind 好了
// - HEAD 探针等槽位就绪(有上限)再回 200:否则冷启动的首次渲染全砸在 iframe 的导航请求上
// - 导航请求绝不为启动/自愈阻塞首字节:未就绪 → 立刻回中转页 + 后台热槽
// - vendor 页把 `/` 当作「自身最新 HTML」来比对,回 404 它就 location.reload() —— 用户看到白屏
// - 外部写盘(不走 officecli 的)靠 mtime 指纹 + 2s 轮询 POST /api/switch 触发重读
//
// 平台:只用 Node 内置能力,进程回收/二进制名/可执行位都按平台分支,不假设 POSIX。
// 监听回环(默认 127.0.0.1:3100),唯一入口仍是 core 的 /preview 反代(登录门禁在那边)。
@@ -22,7 +29,6 @@ const fs = require('node:fs');
const fsp = require('node:fs').promises;
const http = require('node:http');
const net = require('node:net');
const os = require('node:os');
const path = require('node:path');
const { spawn } = require('node:child_process');
@@ -35,12 +41,13 @@ const SLOTS = Math.max(1, Number(process.env.OFFICE_SLOTS || 4));
const WATCH_BASE = Number(process.env.OFFICE_WATCH_BASE || 26315);
const WATCH_SPAN = Math.max(SLOTS, Number(process.env.OFFICE_WATCH_SPAN || 64));
const IDLE_MS = Number(process.env.OFFICE_IDLE_MS || 6 * 3600 * 1000);
const START_TIMEOUT_MS = Number(process.env.OFFICE_START_TIMEOUT_MS || 20000); // 冷启动实测 2~6s,大文档更久
const NAV_WAIT_MS = Number(process.env.OFFICE_NAV_WAIT_MS || 8000); // 导航请求最多等这么久,超时给中转页
const COOLDOWN_MS = Number(process.env.OFFICE_COOLDOWN_MS || 8000); // 启动失败后短期内不再重试
const RESPOND_TIMEOUT_MS = Number(process.env.OFFICE_RESPOND_TIMEOUT_MS || 15000); // 数据请求等首响包
const NAV_TIMEOUT_MS = Number(process.env.OFFICE_NAV_TIMEOUT_MS || 5000); // 导航请求更短:失败转中转页
const COOLDOWN_MS = Number(process.env.OFFICE_COOLDOWN_MS || 8000); // 启动失败后短期不再重试
const HEAD_WAIT_MS = Number(process.env.OFFICE_HEAD_WAIT_MS || 15000); // 探针等首帧的上限
const NAV_TIMEOUT_RETRIES = 3; // 连续导航超时几次才判死
// 会话真实目录:默认 <tasks 根>/<会话id>;手选过工作目录的会话要问 core 拿 work_dir(本地免鉴权)。
// tasks 根就是配置里的 workspace_root(local 形态下它等于 <工作目录>/tasks)。
const TASKS_ROOT = path.resolve(process.env.AGENT_TASKS_ROOT || process.cwd());
const SKILLS_ROOT = path.resolve(process.env.AGENT_SKILLS_ROOT || path.join(TASKS_ROOT, '..', 'skills'));
const REPO_ROOT = path.resolve(process.env.AGENT_REPO_ROOT || path.join(__dirname, '..'));
@@ -49,11 +56,11 @@ const CORE_URL = process.env.AGENT_CORE_URL || '';
const EXTS = new Set(['.docx', '.xlsx', '.pptx']);
const SID_RE = /^task-[0-9A-Za-z_-]+$/;
const slots = new Map(); // 文件绝对路径 → { port, child, lastUsed, conns }
const slots = new Map(); // 文件绝对路径 → { file, port, watch, pageDec, ready, readyP, lastUsed, conns, ... }
const starting = new Map(); // 文件绝对路径 → Promise:同文件并发请求合并成一次 spawn
const cooldown = new Map(); // 文件绝对路径 → 冷却截止时间戳
const dirCache = new Map(); // 会话id → 真实目录(只缓存命中,避免会话晚建时永久失效)
let portGen = 0;
let watchGen = 0; // watch 端口按代轮转:残留孤儿占着旧口也不会被新槽撞上
const log = (msg) => process.stdout.write(new Date().toISOString() + ' ' + msg + '\n');
@@ -102,21 +109,48 @@ function resolveBin() {
return null;
}
// 端口能不能连上(判「有没有人在听」)。注意它**不能**当就绪判定:Kestrel bind 完成就能连,
// 首帧还没渲染;就绪一律用 portUp(真发一次 GET /)。
function portListening(port) {
return new Promise((resolve) => {
const s = net.connect({ host: '127.0.0.1', port });
s.setTimeout(400);
s.once('connect', () => { s.destroy(); resolve(true); });
s.once('timeout', () => { s.destroy(); resolve(false); });
s.once('error', () => resolve(false));
const s = net.connect({ host: '127.0.0.1', port, timeout: 800 });
let done = false;
const fin = (v) => { if (done) return; done = true; try { s.destroy(); } catch (_) {} resolve(v); };
s.once('connect', () => fin(true));
s.once('timeout', () => fin(false)); // 回环上不回 SYN 几乎不存在,按空闲处理
s.once('error', () => fin(false));
});
}
// watch 端口按代轮转,跳过被占用的:AI 手动起的 watch 会占着固定口,不能硬撞。
// 就绪探活:真发一次 `GET /`(首帧渲染在这次请求里完成,后续浏览器请求走 vendor 的页内缓存)。
// 任何状态码都算活着;拒连/超时继续重试,预算 40 次 x 250ms。
function portUp(port, tries = 40) {
return new Promise((resolve, reject) => {
let n = 0;
const probe = () => {
const rq = http.get({ host: '127.0.0.1', port, path: '/', timeout: 2000 }, (up) => {
up.resume();
resolve();
});
const retry = () => {
if (++n >= tries) return reject(new Error('watch 未在预期时间内就绪'));
setTimeout(probe, 250);
};
rq.on('error', retry);
rq.on('timeout', () => { try { rq.destroy(); } catch (_) {} retry(); });
};
probe();
});
}
// 端口代次轮转 + 领取前确认空闲:AI 手动起的 watch、以及被杀的旧 watch 残留,都占着固定口。
async function allocPort() {
for (let i = 0; i < WATCH_SPAN; i++) {
const p = WATCH_BASE + ((portGen + i) % WATCH_SPAN);
if (!(await portListening(p))) { portGen = (portGen + i + 1) % WATCH_SPAN; return p; }
const p = WATCH_BASE + (watchGen++ % WATCH_SPAN);
let used = false;
for (const s of slots.values()) if (s.port === p) { used = true; break; }
if (used) continue;
if (!(await portListening(p))) return p;
}
throw new Error('没有空闲的 watch 端口(' + WATCH_BASE + '~' + (WATCH_BASE + WATCH_SPAN - 1) + ')');
}
@@ -133,24 +167,20 @@ function killTree(child) {
try { child.kill('SIGKILL'); } catch (_) {}
}
function killSlot(abs) {
const s = slots.get(abs);
if (!s) return;
slots.delete(abs);
function killWatch(entry) {
// 已退出的进程不再按 pid 杀:pid 可能已被系统回给别的进程组(POSIX 上是 -pid)
if (s.child && s.child.exitCode === null && s.child.signalCode === null) killTree(s.child);
if (entry.watch && entry.watch.exitCode === null && entry.watch.signalCode === null) killTree(entry.watch);
}
function evictOne(keep) {
const list = [...slots.entries()].filter(([k]) => k !== keep).sort((a, b) => a[1].lastUsed - b[1].lastUsed);
const idle = list.filter(([, s]) => !s.conns);
const victim = (idle.length ? idle : list)[0];
if (!victim) return;
killSlot(victim[0]);
log('挤占槽位 ' + victim[0]);
function stopEntry(entry, why) {
const key = entry.file;
if (slots.get(key) === entry) slots.delete(key);
killWatch(entry);
if (why) log('回收槽位 ' + path.basename(key) + '(' + why + ')');
}
function htmlPage(res, title, body, autoRefresh) {
// ---------- 页面 ----------
function htmlPage(res, title, body, autoRefresh, code) {
const html = '<!doctype html><html lang="zh-CN"><head><meta charset="utf-8">' +
'<title>' + escapeHtml(title) + '</title>' +
(autoRefresh ? '<meta http-equiv="refresh" content="' + autoRefresh + '">' : '') +
@@ -158,10 +188,22 @@ function htmlPage(res, title, body, autoRefresh) {
'h1{font-size:18px;margin:0 0 12px}code{background:#f2f2f2;padding:1px 5px;border-radius:3px;font-size:13px}' +
'p{margin:8px 0;max-width:46em;color:#444}</style></head><body>' +
'<h1>' + escapeHtml(title) + '</h1>' + body + '</body></html>';
res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
res.writeHead(code || 200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
res.end(html);
}
// 中转页:槽位在启动/刚死,先给浏览器一个纯 CSS 转圈 + 自动刷新,别白屏干等(与服务器同一张页)。
function loading(res) {
res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
res.end('<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="2">' +
'<title>正在准备预览</title><style>' +
'html,body{height:100%;margin:0;font-family:system-ui,-apple-system,sans-serif;background:#fafafa;color:#666}' +
'.w{position:absolute;top:50%;left:50%;transform:translate(-50%,-50%);text-align:center}' +
'.s{width:36px;height:36px;margin:0 auto 14px;border:3px solid #ddd;border-top-color:#4a90d9;border-radius:50%;animation:r 1s linear infinite}' +
'@keyframes r{to{transform:rotate(360deg)}}p{font-size:14px}' +
'</style><div class="w"><div class="s"></div><p>正在准备预览,请稍候。</p></div>');
}
function installPage(res) {
const bin = path.join(SKILLS_ROOT, 'office', 'bin', WIN ? 'officecli.exe' : 'officecli');
htmlPage(res, 'office 预览组件未安装',
@@ -172,7 +214,19 @@ function installPage(res) {
'<p><button onclick="location.reload()">刷新</button></p>');
}
// ---------- 会话目录解析 ----------
function notFound(res) {
// no-store:前端拿 HEAD 当探针,404 一旦被浏览器缓存,文件补上后还会继续显示「暂无文档」
res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' })
.end('无匹配预览(文档不存在、不在会话目录下,或不是 .docx/.xlsx/.pptx)');
}
function fail502(res) {
if (!res.headersSent) {
res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }).end('预览暂时不可用,请稍后重试');
}
}
// ---------- 会话目录与路径护栏 ----------
function coreGet(pathname) {
return new Promise((resolve, reject) => {
if (!CORE_URL) return reject(new Error('未配置 AGENT_CORE_URL'));
@@ -197,10 +251,10 @@ async function sessionDir(sid) {
const plain = path.join(TASKS_ROOT, sid);
let dir = fs.existsSync(plain) ? plain : '';
if (!dir) {
// 手选工作目录的会话:只有 core 知道真实路径(sessions.work_dir)
// 手选工作目录的会话:只有 core 知道真实路径(sessions.work_dir)。
// 接口回的是 { session, ... },limit=1 只为别把整段历史拉回来。
try {
const row = await coreGet('/api/sessions/' + encodeURIComponent(sid) + '?limit=1');
// 接口回的是 { session, messages, ... },work_dir 在 session 里(limit=1 只为别把整段历史拉回来)
const wd = String((row && row.session && row.session.work_dir) || '');
if (wd && fs.existsSync(wd)) dir = wd;
} catch (_) { /* core 没起来 / 会话不存在:下面按缺失处理 */ }
@@ -209,230 +263,454 @@ async function sessionDir(sid) {
return dir;
}
// /preview/<sid>/<rel...> → { sid, dir, abs };逐段解码再拼(整串解码会把 %2F 变成路径分隔符)。
// 越界(..、绝对路径)一律当不存在。
async function resolvePreview(rawPath) {
const rest = rawPath.slice(PREFIX.length).replace(/^\/+/, '');
const rawSeg = rest.split('/');
const rawSid = rawSeg.shift() || '';
let sid;
try { sid = decodeURIComponent(rawSid); } catch (_) { return null; }
// /preview/<会话id>/<相对路径> → { sid, dir, abs, rel };越界(..、绝对路径)与非办公文档一律 null。
async function guard(sid, rawRel) {
if (!SID_RE.test(sid)) return null;
let rel;
try { rel = rawSeg.map(decodeURIComponent).join('/'); } catch (_) { return null; }
const dir = await sessionDir(sid);
if (!dir) return null;
const abs = path.resolve(dir, rel.replace(/\/+$/, ''));
const rel = rawRel.replace(/^\/+/, '');
const abs = path.resolve(dir, rel);
if (abs !== dir && !abs.startsWith(dir + path.sep)) return null;
return { sid, dir, abs };
if (!EXTS.has(path.extname(abs).toLowerCase())) return null;
try { await fsp.access(abs); } catch (_) { return null; }
return { sid, dir, abs, rel: path.relative(dir, abs).split(path.sep).join('/') };
}
function pageOf(t) {
return '/' + t.sid + '/' + t.rel; // 页面前缀(已解码):槽位按它寻址
}
// 路由:rel = 已解码、剥掉 PREFIX 的请求路径(形如 /task-x/doc.docx/…);最长前缀优先。
// exact = 命中的就是页面本身(此时缺尾斜杠要 301,否则页面内相对资源会解析错)。
function matchPage(rel) {
if (!rel) return null;
const rr = rel.startsWith('/') ? rel : '/' + rel;
const cut = rr.replace(/\/+$/, '');
let best = null;
for (const s of slots.values()) {
if (cut === s.pageDec) return { entry: s, exact: true };
if (cut.startsWith(s.pageDec + '/')) {
if (!best || s.pageDec.length > best.entry.pageDec.length) best = { entry: s, exact: false };
}
}
return best;
}
// ---------- watch 生命周期 ----------
async function spawnWatch(abs, dir) {
async function spawnWatch(t) {
const bin = resolveBin();
if (!bin) {
const e = new Error('缺少 officecli 二进制');
e.code = 'MISSING_BIN';
throw e;
}
if (slots.size >= SLOTS) evictOne(abs);
// 槽满:优先踢「就绪且无活动连接」里最久未用的;正在启动的槽最后才动(踢掉它等于白费冷启动)
if (slots.size >= SLOTS) {
const list = [...slots.values()];
const pick = (list.filter((s) => !s.conns && s.ready).length ? list.filter((s) => !s.conns && s.ready)
: list.filter((s) => !s.conns).length ? list.filter((s) => !s.conns) : list)
.sort((a, b) => a.lastUsed - b.lastUsed)[0];
if (pick) stopEntry(pick, '槽满挤占');
}
const port = await allocPort();
try { await fsp.mkdir(RUNTIME, { recursive: true }); } catch (_) {}
const logPath = path.join(RUNTIME, 'watch-' + port + '.log');
const fd = fs.openSync(logPath, 'a');
const child = spawn(bin, ['watch', abs, '--port', String(port)], {
cwd: dir,
const child = spawn(bin, ['watch', t.abs, '--port', String(port)], {
cwd: t.dir,
detached: !WIN, // POSIX:自成进程组便于整组回收;Windows 靠 taskkill /T
windowsHide: true,
stdio: ['ignore', fd, fd],
env: Object.assign({}, process.env, {
// 与技能封装层同一组开关:无 ICU 环境跑 .NET 不变式模式、改动即落盘、关自动 resident
// 与技能封装层同一组开关:不变式模式跑 .NET、改动即落盘、关自动 resident
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: '1',
OFFICECLI_NO_AUTO_RESIDENT: '1',
OFFICECLI_RESIDENT_FLUSH: 'each',
}),
});
try { fs.closeSync(fd); } catch (_) {}
let exited = null;
child.on('exit', (code, sig) => { exited = { code, sig }; });
child.on('error', (e) => { exited = { code: -1, sig: String((e && e.message) || e) }; });
const deadline = Date.now() + START_TIMEOUT_MS;
while (Date.now() < deadline) {
if (await portListening(port)) {
const entry = { port, child, lastUsed: Date.now(), conns: 0 };
slots.set(abs, entry);
log('起 watch ' + path.basename(abs) + ' @' + port);
return entry;
}
if (exited) break;
await new Promise((r) => setTimeout(r, 250));
const entry = {
file: t.abs, port, watch: child, pageDec: pageOf(t),
lastUsed: Date.now(), conns: 0, ready: false, readyP: null, navTimeouts: 0,
mtimeMs: 0, size: -1, logPath,
};
let exited = null;
child.on('exit', (code, sig) => {
exited = { code, sig };
if (slots.get(entry.file) === entry) slots.delete(entry.file); // 死了就别留在册(否则一直转发到死端口)
});
child.on('error', (e) => { exited = { code: -1, sig: String((e && e.message) || e) }; });
slots.set(entry.file, entry); // 同步占坑(未就绪):并发请求等 readyP,绝不盲转发
let markDead;
const dead = new Promise((_, rej) => { markDead = rej; });
const deadTimer = setInterval(() => { if (exited) markDead(new Error('watch 进程提前退出')); }, 100);
deadTimer.unref();
entry.readyP = Promise.race([
portUp(port).then(() => { entry.ready = true; log('起 watch ' + path.basename(t.abs) + ' @' + port); }),
dead,
]).catch((e) => {
if (slots.get(entry.file) === entry) slots.delete(entry.file);
killWatch(entry);
throw e instanceof Error ? e : new Error('watch 启动失败:' + ((e && e.message) || e));
}).finally(() => clearInterval(deadTimer));
try {
await entry.readyP;
} catch (e) {
let tail = '';
try { tail = fs.readFileSync(logPath, 'utf8').split('\n').slice(-3).join(' | ').trim(); } catch (_) {}
const err = new Error(e.message + (tail ? ':' + tail : ''));
err.logPath = logPath;
throw err;
}
killTree(child);
let tail = '';
try { tail = fs.readFileSync(logPath, 'utf8').split('\n').slice(-4).join(' | ').trim(); } catch (_) {}
const e = new Error('watch 启动失败' + (exited ? '(进程已退出)' : '(超时)') + (tail ? ':' + tail : ''));
e.code = 'START_FAILED';
e.logPath = logPath;
throw e;
// mtime+size 作为本次渲染的指纹:导航侧对照,外部写盘后回收重渲染
try { const st = await fsp.stat(t.abs); entry.mtimeMs = st.mtimeMs; entry.size = st.size; } catch (_) {}
return entry;
}
async function ensureWatch(abs, dir) {
const have = slots.get(abs);
if (have) {
// watch 可能自己退了(vendor 崩溃、被外部 kill):槽位留着就会一直往死端口转发,
// 面板上只看得到一个 502。每次拿槽位前探活,死了就丢掉重起。
if (await portListening(have.port)) { have.lastUsed = Date.now(); return have; }
log('槽位失效,重起 watch ' + path.basename(abs));
killSlot(abs);
}
const cool = cooldown.get(abs);
if (cool && Date.now() < cool) {
const e = new Error('刚才启动失败,稍后再试');
e.code = 'COOLDOWN';
throw e;
}
if (starting.has(abs)) return starting.get(abs);
const p = spawnWatch(abs, dir).then(
(entry) => { starting.delete(abs); cooldown.delete(abs); return entry; },
async function startWatch(t) {
const have = slots.get(t.abs);
if (have) { have.lastUsed = Date.now(); return have; }
const cool = cooldown.get(t.abs);
if (cool && Date.now() < cool) throw new Error('刚才启动失败,稍后再试');
if (starting.has(t.abs)) return starting.get(t.abs);
const p = spawnWatch(t).then(
(entry) => { starting.delete(t.abs); cooldown.delete(t.abs); return entry; },
(err) => {
starting.delete(abs);
cooldown.set(abs, Date.now() + COOLDOWN_MS);
log('watch 启动失败 ' + abs + ':' + err.message);
starting.delete(t.abs);
cooldown.set(t.abs, Date.now() + COOLDOWN_MS);
log('watch 启动失败 ' + t.abs + ':' + err.message);
throw err;
},
);
starting.set(abs, p);
starting.set(t.abs, p);
return p;
}
// 未命中兜底:请求路径本身就是存在的会话文档 → 就地冷启动。不行 = null。
async function revive(decRel) {
const rr = (decRel || '').replace(/\/+$/, '');
if (!rr) return null;
const segs = rr.split('/').filter(Boolean);
const sid = segs.shift() || '';
const t = await guard(sid, segs.join('/'));
if (!t) return null;
try { await startWatch(t); return { entry: slots.get(t.abs), exact: false }; } catch (_) { return null; }
}
// 数据请求用:拿到「就绪」的槽位,等正在启动的那次;启动刚失败就再补一次。
async function waitReady(decRel) {
for (let round = 0; round < 2; round++) {
let m = matchPage(decRel);
if (!m) m = await revive(decRel);
if (!m || !m.entry) return null;
if (m.entry.ready) return m;
await m.entry.readyP.catch(() => {});
if (m.entry.ready) return m;
}
return null;
}
// 探针预热:把槽位等到「就绪」(= 首帧渲染完成),复用时直接返回。任何失败/超时都静默。
async function warmSlot(decRel, t) {
let timer;
try {
await Promise.race([
(async () => {
const have = slots.get(t.abs);
if (have && have.ready) return;
const e = await startWatch(t);
if (!e.ready) await e.readyP.catch(() => {});
})(),
new Promise((r) => { timer = setTimeout(r, HEAD_WAIT_MS); }),
]);
} catch (_) {} finally { clearTimeout(timer); }
}
// 就地重读:POST watch /api/switch(同路径 = 强制从磁盘重载),watch 原生推 doc-switched,页面自刷。
function notifySwitch(entry) {
try {
const q = http.request({ host: '127.0.0.1', port: entry.port, path: '/api/switch', method: 'POST', timeout: 8000,
headers: { 'content-type': 'application/json' } }, (up) => { up.resume(); });
q.on('error', () => {});
q.on('timeout', () => { try { q.destroy(); } catch (_) {} });
q.end(JSON.stringify({ file: entry.file }));
} catch (_) {}
}
// ---------- 转发 ----------
const PASS_HEADERS = new Set(['accept', 'accept-encoding', 'cache-control', 'pragma', 'content-type',
'content-length', 'if-modified-since', 'if-none-match', 'last-event-id', 'referer', 'user-agent']);
function forward(port, req, res, outPath, abs) {
const headers = {};
for (const k of Object.keys(req.headers)) if (PASS_HEADERS.has(k)) headers[k] = req.headers[k];
// watch 的同源校验只认回环:从别的名字(host 名解析到 127.0.0.1)打开 core 时会被 403。
// 网关本身只监听回环、可达即本机,这里把 Origin 归一成上游自己的地址。
if (req.headers.origin) headers.origin = 'http://127.0.0.1:' + port;
// 单次转发:拒连/首响应超时 → reject(此时尚未向浏览器写出任何字节,可安全改道);
// 已出字节的流内失败只能毁掉响应(SSE 长流的正常路径不受看门狗影响)。
function tryForward(entry, req, res, innerPath, respondTimeoutMs) {
return new Promise((resolve, reject) => {
const selfHost = '127.0.0.1:' + entry.port;
const headers = {};
for (const k of Object.keys(req.headers)) if (PASS_HEADERS.has(k)) headers[k] = req.headers[k];
// watch 的同源校验只认回环:从别的名字(host 名解析到 127.0.0.1)打开 core 时会被 403
if (req.headers.origin) headers.origin = 'http://' + selfHost;
const upstream = http.request({ host: '127.0.0.1', port, path: outPath, method: req.method, headers }, (up) => {
const h = Object.assign({}, up.headers);
delete h.connection; delete h['keep-alive'];
if (String(h['content-type'] || '').includes('text/event-stream')) {
h['cache-control'] = 'no-cache';
h['x-accel-buffering'] = 'no';
}
res.writeHead(up.statusCode || 502, h);
up.pipe(res);
const search = req.url.indexOf('?') >= 0 ? req.url.slice(req.url.indexOf('?')) : '';
const inner = innerPath.startsWith('/') ? innerPath : '/' + innerPath;
entry.lastUsed = Date.now();
entry.conns = (entry.conns || 0) + 1;
let released = false;
const release = () => { if (!released) { released = true; entry.conns = Math.max(0, entry.conns - 1); } };
res.once('close', release);
res.once('finish', release);
let started = false;
let upRes = null;
const upstream = http.request(
{ host: '127.0.0.1', port: entry.port, path: encodeURI(inner) + search, method: req.method, headers },
(up) => {
started = true;
upRes = up;
clearTimeout(watchdog);
const h = Object.assign({}, up.headers);
delete h.connection; delete h['keep-alive'];
const isSSE = String(h['content-type'] || '').includes('text/event-stream');
if (isSSE) { h['cache-control'] = 'no-cache'; h['x-accel-buffering'] = 'no'; }
res.writeHead(up.statusCode || 502, h);
up.on('data', (d) => {
entry.lastUsed = Date.now();
// 抓到「真改文档」的原生推送(牢笼内 CLI 编辑会推 excel-patch/full 等):给轮询器一个吸收窗口。
// 只认改文档的 action —— selection-update/mark-update 是 UI 态,把页内编辑的救场 switch 也吸掉就永不刷新了
if (isSSE && /"action":"(?:full|excel-patch|word-patch|replace|add|remove)"/.test(String(d))) entry.lastNative = Date.now();
});
up.pipe(res);
resolve();
});
const watchdog = setTimeout(() => {
if (started) return;
try { upstream.destroy(); } catch (_) {}
release();
if (!res.headersSent) reject(new Error('watch 响应超时'));
}, respondTimeoutMs || RESPOND_TIMEOUT_MS);
upstream.on('error', () => {
clearTimeout(watchdog);
release();
if (!started && !res.headersSent) return reject(new Error('watch 不可达'));
// 已开始回写后上游报错:留一拍再判(watch 会在响应其实已完整时断链,对 HEAD 必现)
setTimeout(() => {
if (res.writableEnded) return;
try { res.destroy(); } catch (_) {}
}, upRes && upRes.complete ? 0 : 120);
});
req.pipe(upstream);
});
upstream.on('error', () => {
// 上游已死:立刻把槽位扔掉,下一次导航(面板重开 / 刷新)会重新拉起,
// 而不是让这个会话在槽位闲置回收(6h)之前一直 502。
if (abs) killSlot(abs);
if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }).end('预览服务不可达,刷新可重新拉起');
else res.destroy();
});
req.pipe(upstream);
}
function notFound(res) {
res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
res.end('预览不存在');
// 转发自愈一次:失败 → 摘槽 → 同页原地复活 → 重试。GET/HEAD 才可重试(无请求体,重放无副作用)。
async function forwardHealed(entry, req, res, innerPath) {
try { await tryForward(entry, req, res, innerPath); return true; }
catch (e) {
stopEntry(entry, '转发失败:' + String((e && e.message) || e));
if (res.headersSent || !/^(GET|HEAD)$/.test(req.method)) return false;
await new Promise((r) => setTimeout(r, 400)); // 给内核回收旧 listen 套接字留个极短窗口
const m2 = await waitReady(entry.pageDec);
if (!m2 || !m2.entry) return false;
try {
await tryForward(m2.entry, req, res, innerPath);
return true;
} catch (_) { return false; }
}
}
// 数据请求(SSE / api):按 Referer 认领,和 core 反代那段兜底同一套信任模型。
function refererPath(req) {
// 槽位过期:外部(非 officecli)写盘改的是文件,watch 内存里的渲染不感知 → 导航时比对指纹回收重渲染
function fileChanged(entry) {
try {
const st = fs.statSync(entry.file);
return st.mtimeMs !== entry.mtimeMs || st.size !== entry.size;
} catch (_) { return false; }
}
// 浏览器导航请求判定:只有地址栏/iframe 直开页面带 text/html
function isNav(req) {
return req.method === 'GET' && /text\/html/.test(String(req.headers.accept || ''));
}
// 数据请求(资源/API/SSE/Referer 兜底):按 Referer 找回来源页面
function refererRel(req) {
const ref = req.headers.referer || req.headers.referrer || '';
if (!ref) return null;
try {
const p = new URL(ref).pathname; // 不解码:下面按段解,避免 %2F 被当成分隔符
return p === PREFIX || p.startsWith(PREFIX + '/') ? p : null;
const rp = decodeURIComponent(new URL(ref).pathname);
if (!rp.startsWith(PREFIX + '/')) return null;
return rp.slice(PREFIX.length);
} catch (_) { return null; }
}
// ---------- 编辑命令的事后一脚 ----------
// office 封装层改动成功后 fire-and-forget 打这里(本地没有沙箱,原生通知本来就能到 watch;
// 这一脚是无害的补强,也让行为与服务器保持一致)。
function handleTouch(req, res) {
let body = '';
req.on('data', (d) => { body += d; if (body.length > 4096) req.destroy(); });
req.on('end', () => {
let f = '';
try { f = String(JSON.parse(body || '{}').file || ''); } catch (_) {}
let hit = null;
if (f) {
const rp = path.resolve(f);
for (const s of slots.values()) if (s.file === rp) { hit = s; break; }
}
if (hit && hit.ready) {
hit.lastUsed = Date.now();
notifySwitch(hit);
try { const st = fs.statSync(hit.file); hit.mtimeMs = st.mtimeMs; hit.size = st.size; } catch (_) {}
res.writeHead(200, { 'content-type': 'application/json' }).end('{"touched":true}');
} else {
res.writeHead(200, { 'content-type': 'application/json' }).end('{"touched":false}');
}
});
req.on('error', () => {});
}
// ---------- 路由 ----------
const server = http.createServer((req, res) => {
(async () => {
let rawPath;
try { rawPath = new URL(req.url, 'http://127.0.0.1').pathname; } catch (_) { return notFound(res); }
// ---- 预览入口 ----
if (rawPath === PREFIX || rawPath.startsWith(PREFIX + '/')) {
const target = await resolvePreview(rawPath);
if (!target) return notFound(res);
if (!EXTS.has(path.extname(target.abs).toLowerCase())) return notFound(res);
let exists = true;
try { await fsp.access(target.abs); } catch (_) { exists = false; }
// HEAD 是面板的探针(判断「这份文档在不在」),立刻回,不陪着等冷启动。
if (req.method === 'HEAD') {
if (exists) ensureWatch(target.abs, target.dir).catch(() => {});
res.writeHead(exists ? 200 : 404, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store', 'content-length': '0' });
return res.end();
}
if (!exists) return notFound(res);
if (!resolveBin()) return installPage(res);
let entry = null;
try {
entry = await Promise.race([
ensureWatch(target.abs, target.dir),
new Promise((r) => setTimeout(() => r(null), NAV_WAIT_MS)),
]);
} catch (e) {
// 启动失败:给人能看懂的一页(附日志位置),别让面板停在转圈上
return htmlPage(res, '预览启动失败',
'<p>' + escapeHtml(e.message) + '</p>' +
(e.logPath ? '<p>日志:<code>' + escapeHtml(e.logPath) + '</code></p>' : '') +
'<p>稍后点刷新即可重试。</p><p><button onclick="location.reload()">重试</button></p>',
Math.ceil(COOLDOWN_MS / 1000));
}
if (!entry) {
// 冷启动还没完:给中转页自动刷新,别让 iframe 白屏干等
return htmlPage(res, '正在准备预览…', '<p>首次打开需要启动预览进程(大文档要几秒)。</p>', 1);
}
entry.lastUsed = Date.now();
return forward(entry.port, req, res, rawPath.slice(PREFIX.length) || '/', target.abs);
}
// ---- 页内数据面:/events(SSE)与 /api/* 都是根绝对路径 ----
if (rawPath === '/events' || rawPath.startsWith('/api/')) {
const refPath = refererPath(req);
if (!refPath) return notFound(res);
const target = await resolvePreview(refPath);
if (!target) return notFound(res);
const entry = slots.get(target.abs);
if (!entry) return notFound(res); // 槽位已被回收:页面下次导航会重新起
entry.lastUsed = Date.now();
return forward(entry.port, req, res, req.url, target.abs);
}
return notFound(res);
})().catch((e) => {
log('请求失败 ' + req.url + ':' + (e && e.message));
if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
res.end('预览网关内部错误');
route(req, res).catch((e) => {
log('请求失败 ' + req.url + ':' + ((e && e.message) || e));
if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' }).end('预览网关内部错误');
});
});
// 闲置回收:watch 是常驻进程,不回收会一直占着内存与端口(服务器那份是 6h)
const timer = setInterval(() => {
const now = Date.now();
for (const [abs, s] of [...slots.entries()]) {
if (!s.conns && now - s.lastUsed > IDLE_MS) { killSlot(abs); log('回收闲置 watch ' + path.basename(abs)); }
async function route(req, res) {
if (req.method === 'POST' && req.url.split('?')[0] === '/__pv-touch') return handleTouch(req, res);
let u;
try { u = decodeURIComponent((req.url || '/').split('?')[0]); } catch (_) { res.writeHead(400).end('bad path'); return; }
if (req.method === 'GET' && u === '/gateway-healthz') {
const body = JSON.stringify({ ok: true, prefix: PREFIX, slots: slots.size, bin: resolveBin() });
res.writeHead(200, { 'content-type': 'application/json' }).end(body);
return;
}
if (u === PREFIX + '/' || u.startsWith(PREFIX + '/')) {
const rel = u.slice(PREFIX.length) || '/';
const rr = rel.replace(/\/+$/, ''); // 去掉尾斜杠后的页面路径
const segs = rel.split('/').filter(Boolean);
const sid = segs.shift() || '';
const wantSlash = !/\/$/.test(u); // 缺尾斜杠:相对资源会解析错,要补 301
// HEAD = 前端预览窗的「这份文档能不能预览」探针。存在性只在本地按文件系统回答,绝不上探 watch;
// 但回 200 前要等槽位就绪(有上限):冷启动的首次渲染很贵,这里等掉,iframe 一挂上就是渲染好的页面。
if (req.method === 'HEAD') {
const t = await guard(sid, segs.join('/'));
if (t) {
if (!resolveBin()) {
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store', 'content-length': '0' }).end();
return;
}
await warmSlot(rel, t);
res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store', 'content-length': '0' }).end();
return;
}
if (EXTS.has(path.extname(rr).toLowerCase())) return notFound(res);
}
if (isNav(req)) {
// 导航请求 = 用户正盯着这一刻:绝不为启动/自愈阻塞首字节。未就绪 → 中转页 + 后台热槽。
const t = await guard(sid, segs.join('/'));
if (!t) return notFound(res);
if (!resolveBin()) return installPage(res);
const m = matchPage(rr);
if (!m || !m.entry.ready) {
startWatch(t).catch(() => {});
return loading(res);
}
if (fileChanged(m.entry)) {
stopEntry(m.entry, '外部变更');
startWatch(t).catch(() => {});
return loading(res);
}
if (m.exact && wantSlash) { res.writeHead(301, { location: (req.url || u) + '/' }).end(); return; }
const cut = PREFIX.length + m.entry.pageDec.length;
try {
await tryForward(m.entry, req, res, u.length > cut ? u.slice(cut) : '/', NAV_TIMEOUT_MS);
m.entry.navTimeouts = 0;
return;
} catch (e) {
const msg = String((e && e.message) || e);
// 超时 ≠ 死:大文档首次渲染可能超过 5s。单次超时保留槽位,连续几次才判死重启。
m.entry.navTimeouts = /超时/.test(msg) ? (m.entry.navTimeouts || 0) + 1 : NAV_TIMEOUT_RETRIES;
if (m.entry.navTimeouts >= NAV_TIMEOUT_RETRIES) {
stopEntry(m.entry, msg);
startWatch(t).catch(() => {});
}
if (!res.headersSent) return loading(res);
return;
}
}
// 非导航(页面资源/API/SSE):等就绪槽位后自愈转发——用户看不见这些请求,值得原地救活
const m = await waitReady(rel);
if (m && m.entry) {
if (m.exact && wantSlash) { res.writeHead(301, { location: (req.url || u) + '/' }).end(); return; }
const cut = PREFIX.length + m.entry.pageDec.length;
if (await forwardHealed(m.entry, req, res, u.length > cut ? u.slice(cut) : '/')) return;
return fail502(res);
}
}
// vendor 页面把交互 API 与「自身最新 HTML」硬编码成根绝对路径(/、/events、/api/*):
// 按 Referer 找回来源页,原路径原样转发(不剥页面前缀)。`/` 尤其关键——回 404 页面会
// 判定自身过期并 location.reload(),用户看到的就是白屏后重新加载。
const rrel = refererRel(req);
if (rrel) {
const mv = await waitReady(rrel);
if (mv && mv.entry) {
if (await forwardHealed(mv.entry, req, res, u)) return;
return fail502(res);
}
}
notFound(res);
}
// 闲置回收:watch 是常驻进程,不回收会一直占着内存与端口(与服务器一致 6h)。
const idleTimer = setInterval(() => {
const now = Date.now();
for (const s of [...slots.values()]) {
if (!s.conns && now - s.lastUsed > IDLE_MS) stopEntry(s, '闲置回收');
}
for (const [k, v] of cooldown) if (v <= now) cooldown.delete(k);
}, 60000);
timer.unref();
idleTimer.unref();
// 带外写盘兜底 + 页内编辑(POST /api/send 实测只落盘不推事件)的唯一刷新通道:
// 开着页面时比对 mtime,变了就对活槽位 POST /api/switch 就地重读。
const pollTimer = setInterval(() => {
const now = Date.now();
for (const s of [...slots.values()]) {
let st = null;
try { st = fs.statSync(s.file); } catch (_) {}
if (!st) { stopEntry(s, '文件已删除'); continue; } // 会话被删/文件被移走
if (!s.conns) continue; // 没人开着页面:导航侧的指纹门会兜住
if (!s.ready || st.mtimeMs === s.mtimeMs) continue;
if (now - (s.lastNative || 0) < 10000) { s.mtimeMs = st.mtimeMs; s.size = st.size; continue; }
s.mtimeMs = st.mtimeMs;
s.size = st.size;
notifySwitch(s);
}
}, 2000);
pollTimer.unref();
function shutdown() {
for (const abs of [...slots.keys()]) killSlot(abs);
for (const s of [...slots.values()]) stopEntry(s);
process.exit(0);
}
process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);
// 退出/崩溃时别把 spawn 出去的 watch 养成孤儿
process.on('exit', () => { for (const abs of [...slots.keys()]) killSlot(abs); });
process.on('unhandledRejection', (e) => log('未处理的 Promise 拒绝:' + (e && e.message)));
process.on('exit', () => { for (const s of [...slots.values()]) killWatch(s); });
process.on('unhandledRejection', (e) => log('未处理的 Promise 拒绝:' + ((e && e.message) || e)));
server.listen(PORT, HOST, () => {
log('预览网关 listening ' + HOST + ':' + PORT + ' prefix=' + PREFIX + '/' +
+1
View File
@@ -889,6 +889,7 @@ start_core() {
PYTHONPATH="$SKILLS_DIR/deps" \
AGENT_SKILLS_DEPS="$SKILLS_DIR/deps" \
PREVIEW_PROXIES="[{\"name\":\"office\",\"prefix\":\"/preview\",\"host\":\"$HOST_ADDR\",\"port\":${PREVIEW_PORT:-3100}}]" \
OFFICE_GATEWAY_PORT="${PREVIEW_PORT:-3100}" \
node server/server.js >>"$LOG" 2>&1 ) &
CORE_PID=$!
}