diff --git a/mcp/.gitignore b/mcp/.gitignore index 88b017e..09cb07f 100644 --- a/mcp/.gitignore +++ b/mcp/.gitignore @@ -1,3 +1,5 @@ node_modules/ # 编排变量(调试端口等),含部署相关的地址,不进库 .env +# officecli 二进制:部署前由 ./officecli/get-officecli.sh 生成,不进库 +officecli/bin/ diff --git a/mcp/README.md b/mcp/README.md index cfa8e55..b7ac8ef 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -1,12 +1,16 @@ # MCP 服务集合 -三个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: +四个独立 MCP(Model Context Protocol)服务,各占一个目录,共用仓库根目录的 `docker-compose.yml`: | 目录 | 容器名 | 作用 | 容器内端口 | MCP 端点 | |---|---|---|---|---| | `web_search/` | `mcp_web_search` | 免费网页搜索(Parallel / Exa,无需 key) | `3000` | `POST /` | | `image_task/` | `mcp_image_task` | 智谱 CogView 图片生成(单工具 op=create) | `3000` | `POST /mcp` | | `video_task/` | `mcp_video_task` | 智谱 CogVideo 视频生成(异步,单工具 op=create/get) | `3000` | `POST /mcp` | +| `officecli/` | `mcp_officecli` | Office 文档(docx/xlsx/pptx)创建修改 + 浏览器实时预览 | `3000`/`3100` | `POST /` | + +officecli 的预览页面同样不占宿主机端口:浏览器走 agent-core 的通用预览反代 +`/preview/<会话id>/<文档>/…`(登录 cookie 门禁),链路与槽位细节见 `officecli/README.md`。 **这些服务一个宿主机端口都不占**——它们只挂在 `agent-mcp-net` 上,由 `agent-core` / `agent-executor` 按容器名访问。所以整台服务器对外只需要开 agent-core 那一个端口(`AGENT_PORT`,默认 8090)。 @@ -30,6 +34,9 @@ cd /root/workspace/tools/mcp && docker compose up -d --build `image_task` / `video_task` 需要智谱 token,但 token **不由服务端保存**——每个请求从 header 读取 (agent 侧配在 `config.yml` 的 `mcp_servers[].headers`)。所以这里不用配任何密钥。 +`officecli` 与 agent **不共盘**:工作区是独立 scratch 卷(容器内布局同构 `/workspace/tasks/<会话id>/...`, +容器对会话数据盲视),数据交换只走桥的 push(mint 外链拉入)/ save 交付链(AI 在自己会话目录 curl 回写);且要先起 agent(external 网络 `agent-mcp-net` 由 agent 的 compose 创建)。 + ### 环境变量 写在仓库顶层 `.env` 里即可(不写就用默认值): @@ -66,6 +73,7 @@ AI 把拿到的 URL 当 image_url 交给 video_task:3000/mcp | `mcp_web_search` | 无 | 服务端无鉴权,**永远不要映射出去**(会被白嫖搜索额度);agent 走内网访问 | | `mcp_image_task` | 无 | token 由调用方自带,暴露后可被拿去消耗你的智谱额度 | | `mcp_video_task` | 无 | 它需要的公开临时 URL 由 agent 侧集成的工具提供,自己不占端口 | +| `mcp_officecli` | 无 | MCP 口与预览网关口都只在内网;预览页由 agent-core 通用预览反代加登录 cookie 门禁 | ## 单独调试 diff --git a/mcp/docker-compose.yml b/mcp/docker-compose.yml index e503405..710653a 100644 --- a/mcp/docker-compose.yml +++ b/mcp/docker-compose.yml @@ -32,8 +32,35 @@ services: networks: - agent-mcp-net + mcp_officecli: + build: ./officecli + container_name: mcp_officecli + restart: unless-stopped + environment: + # 关自动 resident:实测对时延零增益(瓶颈是 .NET 进程启动),换来无 file_locked 冲突、无常驻进程堆积 + - OFFICECLI_NO_AUTO_RESIDENT=1 + # 每次改动命令返回前落盘(含 open 起的 resident):编辑即自动保存,save/close 只为签发取件链接 + - OFFICECLI_RESIDENT_FLUSH=each + # scratch 卫生:闲置 7 天整目录回收;容量水位 2G(超限按目录 mtime 从旧到新删,删到 80% 为止) + - OFFICE_SCRATCH_TTL_MS=604800000 + - OFFICE_SCRATCH_MAX_BYTES=2147483648 + volumes: + # officecli 二进制缓存:entrypoint 首启拉取(镜像内 pin 版本+sha256,每次启动都校验),容器重建不重拉;down -v 后下次启动自动重拉;纯离线机改 bind 挂载手工放置(见 officecli/README) + - officecli-bin:/opt/officecli + # 刻意不挂 ../agent/tasks:容器对会话数据盲视,只有自己的 scratch 工作区(布局同构 /workspace/tasks/<会话id>/...)。 + # 与交付区的数据交换全部经 push(拉 mint 外链进来)/ pull(AI 在 executor 里执行 curl 写回自己目录)。 + - office-scratch:/workspace/tasks + networks: + - agent-mcp-net + networks: # 与 agent 仓库共用:网络由 agent 的 compose 创建并命名(所以要先起 agent), # 这里声明为 external 直接加入。agent-core / agent-executor 按容器名访问这些服务。 agent-mcp-net: external: true + +volumes: + # officecli 工作区:丢了不要紧(push/pull 流程会重建),down -v 即清空 + office-scratch: + # officecli 二进制缓存:丢了也不要紧,下次启动 entrypoint 自动重新拉取 + officecli-bin: diff --git a/mcp/officecli/Dockerfile b/mcp/officecli/Dockerfile new file mode 100644 index 0000000..2510f83 --- /dev/null +++ b/mcp/officecli/Dockerfile @@ -0,0 +1,29 @@ +FROM node:22-slim + +# libssl3: officecli is a .NET self-contained binary and hard-requires libssl. +# ICU is NOT needed: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 disables globalization. +# curl: the entrypoint fetches the officecli binary at FIRST boot (image intentionally +# does NOT vendor the binary -> nothing to pre-run after clone, `docker compose up` is the whole entry). +RUN apt-get update -qq \ + && apt-get install -y -qq --no-install-recommends libssl3 ca-certificates curl \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /app + +# Zero npm deps: node shim (server.js + watch.js + gateway.js). +# scripts/entrypoint.sh downloads the pinned officecli into /opt/officecli (named volume +# `officecli-bin`, cached across restarts; sha256 verified every boot, GitHub -> gh-proxy fallback) +# then execs CMD. /opt/officecli goes first in PATH so the shim still spawns bare `officecli`. +COPY package.json server.js watch.js gateway.js ./ +COPY scripts/entrypoint.sh /app/scripts/entrypoint.sh +RUN chmod +x /app/scripts/entrypoint.sh + +ENV PATH=/opt/officecli:${PATH} +ENV DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 +ENV OFFICE_WORKSPACE=/workspace/tasks +ENV PORT=3000 + +EXPOSE 3000 + +ENTRYPOINT ["/app/scripts/entrypoint.sh"] +CMD ["node", "server.js"] diff --git a/mcp/officecli/README.md b/mcp/officecli/README.md new file mode 100644 index 0000000..fad43e8 --- /dev/null +++ b/mcp/officecli/README.md @@ -0,0 +1,119 @@ +# officecli + +Office 文档(.docx / .xlsx / .pptx)创建、检视、修改 + 浏览器实时预览的 MCP 服务。 + +上游开源 CLI:[officecli](https://d.officecli.ai)(.NET self-contained 单文件二进制,**不进 git 也不进镜像**;容器首次启动由 `scripts/entrypoint.sh` 拉取到命名卷缓存,pin 版本 + 每次启动 sha256 校验)。 +本目录是一个**零 npm 依赖**的 node shim:把 officecli 自带的 stdio 形态 MCP 桥成 +Streamable HTTP,外加一个按任务路径路由的预览网关。 + +- 协议:MCP **Streamable HTTP**,端点 `POST /`(任何路径都收) +- 鉴权:**无服务端鉴权**,只挂 `agent-mcp-net`(公网必须经 agent-core 登录门禁反代进来),永远不要映射出去 +- 端口:`3000`(MCP)+ `3100`(预览网关,单入口);`26315..26318` 是 watch 进程内部回环端口,不出容器 + +## 结构 + +| 文件 | 职责 | +| --- | --- | +| `server.js` | 入口(容器 PID1):常驻 `officecli mcp` stdio 子进程 + JSON-RPC id 重映射;命令治理(绝对化 / 隐去命令 / 扩展命令 / help 对齐,见下);save/close 附交付取件链、文件缺失附同步教学;桥级失败自动换子进程 | +| `watch.js` | 预览槽位管理:spawn `officecli watch`(只绑 127.0.0.1,vendor 限制),url 按任务组织,槽位号不出容器;`/f/` 交付能力链签发与取件;scratch 过期清理 | +| `gateway.js` | 预览网关(:3100):按路径把请求路由到槽位 watch;Referer 兜底 vendor 页面硬编码的根绝对 API;Host/Origin 成对改写回环自源 + 头白名单 | +| `scripts/entrypoint.sh` | 容器入口(ENTRYPOINT):确保二进制就位(`/opt/officecli`,compose 挂命名卷 `officecli-bin` 缓存;pin 在本文件,镜像升级=版本升级;源链 GitHub → gh-proxy 备源,可 `OFFICECLI_URL`/`OFFICECLI_MIRROR` 加源)→ exec 服务命令;拉不到 fail fast 教手动动作 | + +## 工具面与命令治理 + +只有**一个工具** `officecli`(command 字符串或 argv 数组,原样交给 CLI;schema 查询 `{"command":"help docx paragraph"}`)。 +模型看到的描述 = vendor 原文 + 一句扩展命令能力陈述;**行为约束全部代码化,不写教条**: + +| 机制 | 行为 | +| --- | --- | +| 相对路径自动绝对化 | 调用方(agent-core)每请求带 `X-Session-Dir`,裸文件名/相对路径自动补全会话目录(`key=value` 属性值亦可,如 `src=a.png`;AI 无感,与 terminal 直觉一致);`--type picture` 的 `path=` 属性自动别名为 vendor 真名 `src=` | +| 隐去命令(报原生风格 `Unrecognized command or argument 'X'.`,help 清单同步对齐:删隐去行、补录扩展行) | `mcp`(自锁死)、`skills` / `install` / `plugins`(装环境类);`watch` 的 mark/unmark/marks/goto 子命令同理 | +| `view` 渲染族屏蔽 | 其它模式(outline/stats/issues/text/annotated)照常透传;仅渲染族 `view html` / `screenshot` / `svg` / `pdf` / `forms`(需无头浏览器/导出插件)拦截,返回 `view is disabled by environment policy. Use 'view outline' or 'view issues' for structural/semantic checks.` | +| 回包文案 | `create` / `open` / `push` 成功只回 `Created/Opened/Imported: <相对会话目录文件名>`;预览链接不随回包出现(固定格式 `<公网前缀>/preview/<会话id>/<相对路径>/`,前端自己拼,AI 面不需要知道);`save` / `close` 成功附 `download url:`(限时取件链,同文件复用同一链接);失败文案剥掉工作区路径前缀与 vendor 异常包装,只留文件名 | +| 桥内拦截(对 AI 不公示) | `watch` / `unwatch ` 仅本会话目录(必须拦截:vendor 原生 watch 会占死 stdio;help 里同步不显示);`unwatch --session [--purge]` 校验 id==X-Session-Dir 尾段,core 会话清理钩子专用 [--purge 杀槽外连带删会话目录副本,幂等];`get-pos ` 改写原生 `get … selected --json`;`push ` 外链拉入(http(s) only、100MB、非覆盖需 `--force`;读不到外链时报「读取文件失败」而非「下载失败」——AI 视角是上传) | +| 用法指引投递 | `load_skill office-preview` 只讲:get-pos / 两份盘同步;不出现 watch、不出现预览 url | + +`get` / `query` / `set` 等短命令照常透传(与槽位 watch 进程同容器 IPC 直达);`get-pos` 即桥内改写的 `get … selected --json`。 + +## 预览链路(为什么 watch 必须待在本容器) + +刷新信号 = officecli watch 进程内的 IPC,所以 watch 只能与 officecli 同容器; +槽位进程由shim(容器 PID1)托管才能跨 MCP 调用存活。浏览器不直连本容器, +必须经 agent-core 的通用预览反代(登录 cookie 即门禁,对外依旧只开 core 一个端口): + +``` +用户浏览器(已登录 agent) + │ https:///preview/<会话id>/<文档相对路径>/... + ▼ +agent-core routes/preview-proxy.js(注册表驱动,信任模型同 data-page) + │ 头白名单转发(Referer 兜底 vendor 页面的根绝对 /api/*、/events) + ▼ +mcp_officecli:3100 gateway.js ——按路径找槽位、改写 Host/Origin 回环自源──► 127.0.0.1:26315+N officecli watch +``` + +- url 按任务组织:文档必须在会话目录下(`/<会话id>/…`,任务根下不可预览);重启换槽不影响链接含义。 +- 预览 url 不由本服务下发:链接按固定格式 `<公网前缀>/preview/<会话id>/<文档相对路径>/` 由前端自拼;`X-Public-Base` 仅供桥内 watch 状态/日志用,对 AI 的回包里 `url`/`path` 字段已被剥掉。 +- 槽位数 `OFFICE_SLOTS`(默认 4);满了优先踢「无活动连接且最久未用」;闲置超 `OFFICE_IDLE_MS`(默认 6h)回收,挂着活动连接的槽不回收;预览每一帧回传与 AI 命令都会续命。 +- 槽位是缓存不是承诺:预览链接按任务路径寻址,被回收/挤占后页面再访问由网关就地复活(一次冷启动)。 +- AI 面不公示 watch/unwatch(也没有 watch ls / --all 这类跨会话动作):预览完全由前端拼链接、网关按需复活槽位 + LRU 管理;core 删会话时经校验的 `unwatch --session --purge` 清槽并删工作区目录副本(不等 scratch TTL)。 +- 同一文件同时只允许一个 watch(vendor 限制;同文件并发 watch 已合并为一次启动)。 + +## 两份盘与同步(push / download url) + +容器工作区与 `agent/tasks/<会话id>/` 是两份盘;桥负责在响应里教会 AI 换盘动线(拦截即教学,不设协议): + +| 方向 | 动线 | 执行者 | +| --- | --- | --- | +| 任务目录 → 工作区 | `mint_public_link` 签发外链 → `officecli push ` | 桥拉入(护栏:WORKSPACE 内、白名单扩展名(office/图片/常见数据)、100MB、非覆盖需 --force) | +| 工作区 → 任务目录 | `save ` / `close ` 回包尾附 `download url` → AI 在自己终端下载 | AI(executor 的会话 jail 天然框住写路径,core 零改动零新 API) | + +- 每次改动命令返回前落盘(compose 置 `OFFICECLI_RESIDENT_FLUSH=each`):编辑即自动保存,save/close 的主要作用只是签发取件链。 +- 成功/失败文案只带相对文件名,不出现工作区绝对路径:工作区与任务目录同名不同盘,全路径极易让 AI 误判文件落点。 + +- 取件链 `GET /f/<随机id>`:与 core `/p/` 同款能力链(随机不可猜 + TTL + 只吐 guard 过的路径),只在内部网络可达(core 反代只转 `/preview`,公网够不着)。同一文件重复 save/close 复用原 token(滑动 TTL,链接永远指向盘上最新内容)。过期 404 文案提示重新 save。 +- vendor 命令报"文件不存在"且引用路径确实缺失时,桥在错误尾附 push/交付动线提示;`X-Session-Dir` 首次出现时桥顺手 mkdir 会话目录。 +- core 会话删除时 `engine.deleteSession` 尽力打一发 `unwatch --session <会话id> --purge`(`mcp.notifyTool`,失败只记日志):桥端杀预览槽 + 删 `tasks/<会话id>` 工作区副本,幂等。 + +## 请求头契约(调用方 → 本服务) + +| 头 | 说明 | +| --- | --- | +| `X-Public-Base` | core 公网前缀(已归一),仅供桥内 watch 状态展示;预览 url 不再下发给 AI,缺省也无影响 | +| `X-Session-Dir` | 本次调用的会话工作目录,用于裸文件名/相对路径补全;core 的 mcp.js 从工具执行 ctx 自动注入,其它 MCP 服务忽略即可 | + +## 环境变量 + +| 变量 | 默认 | 说明 | +| --- | --- | --- | +| `OFFICE_WORKSPACE` | `/workspace/tasks` | 容器内工作区根(独立 scratch 卷,布局同构 `/<会话id>/...`;与 core 的 tasks 不同盘,数据交换只走 push / save 交付链) | +| `OFFICE_SLOTS` | `4` | 预览槽位数(内部端口段宽度) | +| `OFFICE_IDLE_MS` | `21600000`(6h) | 槽位闲置回收阈值;有活动预览连接的槽不回收,链接再访问自动复活 | +| `OFFICE_PREVIEW_PORT` | `3100` | 预览网关端口(与 core 注册表对齐) | +| `OFFICE_PREVIEW_PREFIX` | `/preview` | 预览 url 的路径前缀(与 core 注册表 prefix 一致) | +| `OFFICECLI_TIMEOUT_MS` | `120000` | 单次 MCP 请求等 officecli 回包的上限,超时 换子进程 | +| `OFFICE_DL_BASE` | `http://mcp_officecli:3100` | download url 的前缀(executor 可达的内网地址;改服务名时覆盖) | +| `OFFICE_DL_TTL_MS` | `1800000`(30min) | 取件链有效期,过期 404 并提示重新 save | +| `OFFICE_SCRATCH_TTL_MS` | `604800000`(7d) | scratch 会话目录闲置清理阈值(每小时一次 + 启动后 10s 首扫;槽位占用的目录不碰;0=关) | +| `OFFICE_SCRATCH_MAX_BYTES` | `2147483648`(2G) | scratch 容量水位:总量超限时按目录 mtime 从旧到新删非 busy 目录,删到 80% 为止(0=关) | +| `OFFICECLI_NO_AUTO_RESIDENT` | compose 置 `1` | 关 vendor 自动 resident:实测时延零增益,消掉 file_locked 冲突与常驻进程堆积(vendor 未公开变量,help 只写 `OFFICECLI_RESIDENT_FLUSH`) | +| `OFFICECLI_RESIDENT_FLUSH` | compose 置 `each` | 每次改动命令返回前落盘(含 open 起的 resident):编辑即自动保存,save/close 只为签发取件链 | + +## 部署与调试 + +`docker-compose.yml` 中的 `mcp_officecli` 服务构建本目录;工作区用独立命名卷 `office-scratch`, +**刻意不挂 `../agent/tasks`**:容器对会话数据盲视,泄漏面归零;容器内路径仍同构 `/workspace/tasks/<会话id>/...`,AI 无感。 + +二进制不进库也不进镜像:首次启动 entrypoint 自动拉取到命名卷 `officecli-bin`(容器重建不重拉;每次启动 sha256 秒级校验;版本 pin 在 `scripts/entrypoint.sh`,改版本=改文件重新 build)。GitHub 不通自动落 gh-proxy 备源;都失败则启动 fail fast(日志教手动动作,`unless-stopped` 重启即重试);`down -v` 清卷后下次启动自动重拉。 + +**离线放置**:GitHub 与备源都不可达的机器,把同名二进制放进挂载目录即可(sha256 对上就认):`docker cp mcp_officecli:/opt/officecli/officecli` 后 restart,或把 compose 里 `officecli-bin` 卷换成 bind 挂载。 + +```bash +docker compose up -d --build mcp_officecli # clone 后即可直接起;首启多一次二进制下载(仅首次) +# MCP 健康检查(含预览槽位列表) +docker exec mcp_officecli node -e "fetch('http://localhost:3000/').then(r=>r.json()).then(j=>console.log(JSON.stringify(j)))" +#预览网关健康检查 +docker exec mcp_officecli node -e "fetch('http://localhost:3100/gateway-healthz').then(r=>r.text()).then(console.log)" +``` + +agent 侧两处登记(缺一不可):`config.yml` 的 `mcp_servers: [{name: officecli, url: "http://mcp_officecli:3000/"}]`; +core 预览注册表默认已含 officecli(`routes/preview-proxy.js`,改 config.yml 后重启 core 生效)。 diff --git a/mcp/officecli/gateway.js b/mcp/officecli/gateway.js new file mode 100644 index 0000000..278d816 --- /dev/null +++ b/mcp/officecli/gateway.js @@ -0,0 +1,89 @@ +// 预览网关:单入口端口(:OFFICE_PREVIEW_PORT,默认 3100)按路径路由到槽位 watch —— 槽位号不出容器。 +// 主路由:/<会话id>/<文档相对路径>/** → 槽位注册表最长前缀匹配 → 转发该槽位 watch。 +// 自愈:路由未命中但请求路径本身是存在的会话文档 → 就地复活 watch(watch.revive)—— +// 槽位只是缓存不是承诺,闲置回收/被别的会话挤掉后,页面再访问 = 正常冷启动。 +// 兜底:vendor 预览页把交互 API 硬编码成根绝对路径(/api/selection、/events…)→ 按 Referer 找回槽位,原样转发。 +// masquerade:头白名单 + Host/Origin 成对改写为目标回环自源(watch 自带 DNS-rebinding/跨源防护); +// 凭据永不转发(core 那层已过滤,这里是容器内第二道防线)。 +'use strict'; +const http = require('node:http'); +const watch = require('./watch'); + +const PREFIX = watch.PREFIX; +// 上游(watch)确实用得到的头;cookie/authorization/referer/sec-fetch/user-agent 等一律不进 +const PASS = new Set(['accept', 'accept-encoding', 'cache-control', 'pragma', 'content-type', 'content-length', 'last-event-id', 'if-modified-since', 'if-none-match']); + +function forwardTo(entry, req, res, innerPath) { // innerPath:页面内相对路径(主路由剥前缀)或根绝对原路径(Referer 兜底),不再二次加工 + const selfHost = '127.0.0.1:' + entry.port; + const fwd = { host: selfHost }; + for (const k of Object.keys(req.headers)) if (PASS.has(k)) fwd[k] = req.headers[k]; + if (req.headers.origin) fwd.origin = 'http://' + selfHost; + const qpos = req.url.indexOf('?'); + const search = qpos >= 0 ? req.url.slice(qpos) : ''; + const inner = innerPath.startsWith('/') ? innerPath : '/' + innerPath; + // 槽位续命信号:建连即续,此后每帧回传再续(SSE 是长连接,只在建连那刻续会把长驻页面误判成闲置)。 + // conns 记「正在回传」的请求数:conns>0 = 有人正开着预览页,闲置回收/槽位挤占都绕着它走。 + 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); + const upstream = http.request( + { host: '127.0.0.1', port: entry.port, path: encodeURI(inner) + search, method: req.method, headers: fwd }, + (up) => { + const h = Object.assign({}, up.headers); + if (String(h['content-type'] || '').includes('text/event-stream')) { h['cache-control'] = 'no-cache'; h['x-accel-buffering'] = 'no'; } + res.writeHead(up.statusCode, h); + up.on('data', () => { entry.lastUsed = Date.now(); }); // 含 SSE 心跳/事件帧:任何回传 = 上游活着 + up.pipe(res); + }); + upstream.on('error', () => { + if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' }).end('预览槽位不可达(可能刚停止或已到期回收)'); + else res.destroy(); + release(); // 上面两条终结路径各自触发 close/finish 前,这里幂等兜底 + }); + req.pipe(upstream); +} + +function matchReferer(req) { + const ref = req.headers.referer || req.headers.referrer || ''; + if (!ref) return null; + try { + const rp = decodeURIComponent(new URL(ref).pathname); + if (!rp.startsWith(PREFIX + '/')) return null; + return watch.matchPage(rp.slice(PREFIX.length)); + } catch (_) { return null; } +} + +function start(port, host) { + return http.createServer((req, res) => { + route(req, res).catch(() => { if (!res.headersSent) res.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' }).end('预览网关内部错误'); }); + }).listen(port, host); +} + +async function route(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: watch.status('').length }); + res.writeHead(200, { 'content-type': 'application/json' }).end(body); + return; + } + if (req.method === 'GET' && u.startsWith('/f/')) return watch.serveDl(decodeURIComponent(u.slice(3)), req, res); // 交付取件口:URL 即能力,只在内部网络可达(core 反代只转 /preview) + if (u === PREFIX + '/' || u.startsWith(PREFIX + '/')) { + const rel = u.slice(PREFIX.length) || '/'; + let m = watch.matchPage(rel); + if (!m) m = await watch.revive(rel); // 槽=缓存:页面重开/冷槽就地复活 + if (m) { + if (m.exact && !u.endsWith('/')) { res.writeHead(301, { location: (req.url || u) + '/' }).end(); return; } // 相对路径资源解析需要尾斜杠 + const cut = PREFIX.length + m.entry.pageDec.length; // 剥掉「前缀+页面路径」才是 watch 的内层路径 + return forwardTo(m.entry, req, res, u.length > cut ? u.slice(cut) : '/'); + } + } + const viaRef = matchReferer(req); // vendor 页面的根绝对 API:Referer 找回来源槽位,原路径原样转发(不剥页面前缀!) + if (viaRef) return forwardTo(viaRef.entry, req, res, u); + res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('无匹配预览(文档不存在/不在会话目录下,或不是 .docx/.xlsx/.pptx;若文档在任务目录里,先 officecli push 进来)'); +} + +module.exports = { start }; diff --git a/mcp/officecli/package.json b/mcp/officecli/package.json new file mode 100644 index 0000000..8179d05 --- /dev/null +++ b/mcp/officecli/package.json @@ -0,0 +1,8 @@ +{ + "name": "officecli-mcp", + "version": "0.1.0", + "private": true, + "description": "Streamable-HTTP MCP shim bridging officecli mcp (stdio) + live preview slots", + "main": "server.js", + "scripts": { "start": "node server.js" } +} diff --git a/mcp/officecli/scripts/entrypoint.sh b/mcp/officecli/scripts/entrypoint.sh new file mode 100755 index 0000000..1c59c2e --- /dev/null +++ b/mcp/officecli/scripts/entrypoint.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# 容器入口:确保 officecli 二进制就位(命名卷缓存)→ exec 真正的服务命令。 +# +# - 二进制不进 git 也不进镜像:首次启动下载到 /opt/officecli(compose 挂命名卷 officecli-bin), +# 之后每次启动只做 sha256 秒级校验,容器重建不重复下载;卷删了(down -v)下次启动自动重拉。 +# - 信任锚是镜像里的 pin(本脚本写死版本+sha256;镜像升级=版本升级): +# 缓存有效性 = 实际 sha256 与 pin 一致——换版本后旧缓存自动作废,无需额外标记文件。 +# - 源链(依次尝试,产物一律过 sha256):OFFICECLI_URL 整URL覆盖 → GitHub → gh-proxy 备源 → OFFICECLI_MIRROR 前缀。 +# - 离线兜底:往挂载目录放一份同名二进制即可(sha 对上就认),见 README「离线放置」。 +# - 拉取失败:fail fast 非零退出(unless-stopped 重启即重试),日志教手动动作。 +set -euo pipefail + +VERSION="${OFFICECLI_VERSION:-v1.0.157}" +SHA256="${OFFICECLI_SHA256:-f8eefe88dbfa7464bee421e5421efe57fc26bc3180b30e56eef58594c8245c94}" +ASSET="officecli-linux-x64" +GH_URL="https://github.com/iOfficeAI/OfficeCLI/releases/download/${VERSION}/${ASSET}" + +BIN_DIR="${OFFICECLI_DIR:-/opt/officecli}" +BIN="${BIN_DIR}/officecli" + +log() { echo "[officecli-fetch] $*"; } + +sha_ok() { printf '%s %s\n' "${SHA256}" "$1" | sha256sum -c --status - >/dev/null 2>&1; } + +# 缓存命中 = 可执行 + sha256 与镜像内 pin 一致(顺带覆盖 docker cp / 手工放置的兜底场景) +if [ -x "${BIN}" ] && sha_ok "${BIN}"; then + log "officecli ${VERSION} in place (${BIN}); skip fetch" + exec "$@" +fi + +urls=() +if [ -n "${OFFICECLI_URL:-}" ]; then urls+=("${OFFICECLI_URL}"); fi +urls+=( "${GH_URL}" "https://gh-proxy.com/${GH_URL}" ) +if [ -n "${OFFICECLI_MIRROR:-}" ]; then + p="${OFFICECLI_MIRROR}"; case "${p}" in */) ;; *) p="${p}/";; esac + urls+=( "${p}${GH_URL}" ) +fi + +mkdir -p "${BIN_DIR}" +rm -f "${BIN_DIR}"/.dl.* 2>/dev/null || true # 清理上次被中断的半成品 +tmp="$(mktemp "${BIN_DIR}/.dl.XXXXXX")" # 与目标同目录:最后 mv 原子就位,中断永远不会留下残缺拷贝 +trap 'rm -f "${tmp}"' EXIT + +for url in "${urls[@]}"; do + log "trying ${url}" + if curl -fsSL --connect-timeout 10 --retry 1 --max-time 600 -o "${tmp}" "${url}"; then + got="$(sha256sum "${tmp}" | awk '{print $1}')" + if [ "${got}" = "${SHA256}" ]; then + chmod +x "${tmp}" + mv -f "${tmp}" "${BIN}" + log "officecli ${VERSION} installed -> ${BIN}" + exec "$@" + fi + log "sha256 mismatch (got ${got}), trying next source" + fi + rm -f "${tmp}" +done + +log "FATAL: officecli ${VERSION} 所有源都拉不到(或校验不过)。" +log " asset: ${GH_URL}" +log " sha256: ${SHA256}" +log " 手动放置(sha 对上就认):docker cp <本地二进制> mcp_officecli:${BIN} && docker compose restart mcp_officecli" +log " 或把 compose 里 officecli-bin 卷换成 bind 挂载(./某目录:${BIN_DIR})离线放置,再 up -d。" +exit 1 diff --git a/mcp/officecli/server.js b/mcp/officecli/server.js new file mode 100644 index 0000000..63e3f80 --- /dev/null +++ b/mcp/officecli/server.js @@ -0,0 +1,551 @@ +// officecli MCP 服务 shim —— Streamable HTTP(:3000) ⇄ officecli mcp(stdio) 桥。 +// +// 为什么需要这么一层:officecli 的 MCP 只有 stdio 形态;且 watch(预览)必须与 +// officecli 同容器(刷新信号=进程内 IPC)、与 shim 同父(躲开任何命令级进程回收)。 +// 本进程是容器 PID1:常驻 officecli mcp 子进程 + watch.js 管槽位 watch 子进程。 +// +// 工具面:单工具 officecli(command 字符串透传 + 桥内命令治理):create/open/push 成功只回文件名确认, +// 预览链接固定格式由前端自拼(AI 面不出现 url);save/close 自带 download url,点选回读 get-pos;watch/unwatch 桥内拦截但不向 AI 公示 +//(必须拦截:vendor 原生 watch 会占死 stdio;且仅开放本会话目录);隐去命令报原生风格 Unrecognized, +// help 同步对齐可见面;用法指引走 load_skill office-preview(见 DEPLOY_SKILL),零教条。 +// 环境变量:OFFICE_WORKSPACE(= /workspace/tasks)、OFFICE_SLOTS(=4)、OFFICE_PREVIEW_PORT(=3100)。 +// 公网 url 前缀不配置在这里:调用方(agent-core)每请求用 X-Public-Base 头注入(真相只在 core 一处), +// 会话工作目录同理经 X-Session-Dir 头注入(裸文件名自动补全会话目录,AI 无感)。 +'use strict'; +const http = require('node:http'); +const { createServer } = http; +const fs = require('node:fs'); +const path = require('node:path'); +const { spawn } = require('node:child_process'); + +// 启动自检:officecli 缺失/不可执行不在首个 MCP 请求时以诡异超时现身——PID1 直接 fail fast 并教部署动作。 +if (!(process.env.PATH || '').split(':').some((d) => { try { fs.accessSync(path.join(d, 'officecli'), fs.constants.X_OK); return true; } catch (_) { return false; } })) { + console.error("[bridge] FATAL: officecli binary not found in PATH (expected /opt/officecli/officecli,由 entrypoint 拉取就位)。" + + "查 [officecli-fetch] 启动日志;离线放置见 officecli/README「离线放置」(sha256 对上就认)。"); + process.exit(1); +} + +const watch = require('./watch'); +const gateway = require('./gateway'); + +const PORT = Number(process.env.PORT || 3000); +const PREVIEW_PORT = Number(process.env.OFFICE_PREVIEW_PORT || 3100); +const HOST = process.env.HOST || '0.0.0.0'; +const CALL_TIMEOUT_MS = Number(process.env.OFFICECLI_TIMEOUT_MS || 120000); +const SERVER_NAME = 'officecli-mcp'; + +// ---------- stdio 桥:单条常驻 officecli mcp 子进程 ---------- +let child = null; +let ready = false; // officecli 子进程是否已完成 initialize 握手 +let buf = ''; +let seq = 0; +const pending = new Map(); // bridge id -> {res 回调, timer:http 等待方} + +function resetChild() { + for (const [, p] of pending) { clearTimeout(p.timer); p.reject(new Error('officecli process exited, retry')); } + pending.clear(); buf = ''; child = null; ready = false; +} + +function ensureChild() { + if (child) return child; + // cwd 进共享卷:否则相对路径产物落在容器根 fs(/app),core/executor 都看不见 + child = spawn('officecli', ['mcp'], { stdio: ['pipe', 'pipe', 'inherit'], cwd: watch.WORKSPACE }); + const me = child; // 身份守卫:只有当前子进程的 exit 才重置桥(换新后的旧进程迟到的 exit 不得误伤) + child.stdout.on('data', (d) => { + buf += d; let i; + while ((i = buf.indexOf('\n')) >= 0) { + const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1); + if (!line) continue; + let msg; try { msg = JSON.parse(line); } catch (_) { continue; } + if (msg.id !== undefined && pending.has(msg.id)) { + const p = pending.get(msg.id); pending.delete(msg.id); + clearTimeout(p.timer); p.resolve(msg); + } else if (msg.method) { + console.log('[bridge] officecli 通知:', msg.method); // 桥接侧暂无需处理 + } + } + }); + me.on('exit', (code) => { console.log('[bridge] officecli mcp 退出', code); if (child === me) resetChild(); }); + return child; +} +// 向 officecli 子进程发一条 JSON-RPC 请求并等回包(id 重映射,多 HTTP 请求并发安全) +function rpc(method, params) { + return new Promise((resolve, reject) => { + const c = ensureChild(); + const id = ++seq; + const timer = setTimeout(() => { + if (!pending.has(id)) return; + pending.delete(id); reject(new Error('Timeout waiting for officecli response: ' + method)); + }, CALL_TIMEOUT_MS); + pending.set(id, { resolve, reject, timer }); + c.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n'); + }); +} + +function sendNotify(method, params) { + const c = ensureChild(); + c.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n'); +} + +// 桥自己补一次 initialize 握手(兜底:子进程重建后,客户端还没发过 initialize 就来请求) +async function selfInit() { + await rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'officecli-mcp-shim', version: '0' } }); + sendNotify('notifications/initialized', {}); +} + +// 会话 id 从预览 url 拷回来时可能是百分号编码形态;解不动就用原样(id 字符集本不需编码) +function decSafe(s) { try { return decodeURIComponent(s); } catch (_) { return s; } } + +// ---------- 部署面治理:隐藏命令报原生风格 unrecognized,help 同步对齐(AI 眼里 = 原生 CLI)---------- +const unrecognized = (v) => "Unrecognized command or argument '" + v + "'."; +const HIDDEN_SUBS = new Set(['mark', 'unmark', 'marks', 'goto']); // 标注/滚动族:本部署只保留 watch / watch ls / unwatch / get-pos +const HIDDEN_VERBS = 'mcp|skills|install|plugins'; // 与 handle 里的 mblk 黑名单同步(view 已放开,只拦 html/screenshot 渲染模式) +const HIDDEN_LINE = /^ {2}(?:mcp|skills|install|plugins)\b/; // 注意:绝不能用字符串拼 RegExp,'\b' 在 JS 字符串里是退格符 +const HELP_STRIP = /^ {2}(?:watch|unwatch)\b/; // 预览已自动化(create/open/push 附链接):help 也不出示 watch/unwatch,防 AI 想起没用过的命令 +const VIEW_BLOCKED = new Set(['html', 'screenshot', 'svg', 'pdf', 'forms']); // view 渲染族:需无头浏览器/导出插件,本环境一律屏蔽 + +// push 护栏:目标必须落在 WORKSPACE 内且是白名单扩展名(office + 资源图 + 常见数据;目标可以尚不存在,故不复用 watch.guard)。 +// 裸相对名以会话目录为基准(absolutize 只处理 office/图片,其余允许类型若按 WORKSPACE 根解会落到会话外,与回执/files 列表不一致); +// 显式绝对路径仍可指向工作区任意位置(既有设计)。pushTarget(p, base):base 越界时退回 WORKSPACE。 +function pushTarget(p, base) { + const wsRoot = path.resolve(watch.WORKSPACE); + const root = base && path.resolve(base).startsWith(wsRoot + path.sep) ? path.resolve(base) : wsRoot; + const abs = path.resolve(root, String(p || '')); + const rel = path.relative(wsRoot, abs); + if (!rel || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) throw new Error('Target must be inside the workspace (' + watch.WORKSPACE + '): ' + p); + if (!PUSH_EXT_RE.test(abs)) throw new Error('Unsupported file type: ' + p + '. Allowed: office (.docx/.xlsx/.pptx), images (png/jpg/jpeg/gif/webp/bmp/tiff), pdf/csv/txt/json/md'); + return abs; +} +const PUSH_TIMEOUT_MS = 60000; +const PUSH_MAX_BYTES = 100 * 1024 * 1024; + +// 交付取件链接前缀:executor 与本源同网,AI 终端里的 curl 直接用它(改名部署时用 env 覆盖) +const DL_BASE = (process.env.OFFICE_DL_BASE || 'http://mcp_officecli:' + PREVIEW_PORT).replace(/\/+$/, ''); +const SYNC_TEACH = 'Your task directory and the officecli workspace are two separate disks. To edit a file that already ' + + 'exists in your task directory: sign a link for it with mint_public_link, then run officecli push ' + + 'to sync it in. When done editing, save the file and download the returned download url back into your task directory.'; + +// help 照透传,但文本过一道:隐去的命令行删掉、桥扩展命令补进 Commands 清单(可见面 = 可调用面) +const HELP_ADD = [ + ' get-pos Read what the user selected in the live preview (returns JSON).', + ' push Download an http(s) URL into the workspace as .', + ' files List files under the current workspace directory (server-side).', +]; +function alignHelp(reply) { + const items = reply && reply.result && Array.isArray(reply.result.content) ? reply.result.content : []; + for (const it of items) { + if (!it || typeof it.text !== 'string' || !it.text.includes('Commands:')) continue; + const text = it.text.replace(/ ?Subcommands \(mark\/unmark\/marks\/goto\) operate on the running preview\./g, ''); + const out = []; + let added = false; + for (const ln of text.split('\n')) { + if (HIDDEN_LINE.test(ln) || HELP_STRIP.test(ln)) continue; + out.push(ln); + if (!added && /^ {2}help\s/.test(ln)) { out.push(...HELP_ADD); added = true; } + } + if (!added) out.push(...HELP_ADD); + it.text = out.join('\n'); + } +} + +// 成功回执三词式:vendor 原文带工作区绝对路径(与 AI 任务目录同名不同盘,极易误判落点),统一替换成 +// "Created/Opened: <相对会话目录文件名>"。预览链接是固定格式(<公网前缀>/preview/<会话id>/<相对路径>/), +// 调用方自拼,不再随回包附带。 +function ackNote(cmd, reply, sessDir) { + const verb = /^create\b/.test(cmd) ? 'Created' : /^open\b/.test(cmd) ? 'Opened' : ''; + if (!verb) return; + const res = reply && reply.result; + if (!res || res.isError || !Array.isArray(res.content)) return; + const first = res.content.find((c) => c && typeof c.text === 'string'); + if (!first) return; + const t = (tokenizeCmd(cmd) || []).find((x) => x.startsWith(watch.WORKSPACE + '/') && OFFICE_EXT_RE.test(x)); + if (!t) return; + const jail = sessDir && sessDir.startsWith('/') ? path.resolve(sessDir) : ''; + first.text = verb + ': ' + (jail && t.startsWith(jail + '/') ? path.relative(jail, t) : path.basename(t)); +} + +// 失败文案整形:剥掉工作区路径前缀只留文件名(与任务目录同名不同盘,全路径只会诱发误判); +// 顺带拆掉 vendor resident 异常包装("Resident process exited. Unhandled exception: X.CliException: …")只留内层真错 +const WS_PATH_RE = new RegExp(watch.WORKSPACE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '/(?:[^\\s\'"`,;:()()]+/)*', 'g'); +function scrubErr(reply) { + const res = reply && reply.result; + if (!res || !res.isError || !Array.isArray(res.content)) return; + for (const c of res.content) { + if (!c || typeof c.text !== 'string') continue; + c.text = c.text + .replace(/Resident process exited\.\s*Unhandled exception:\s*[\w.]*Exception:\s*/g, '') + .replace(WS_PATH_RE, ''); + } +} + +// 透传报错误且引用的工作区路径确实不存在:十有八九是文件只在任务目录里 —— 拦截即教学(push 方向) +function teachOnMiss(cmd, reply) { + const res = reply && reply.result; + if (!res || !res.isError) return; + const txt = (res.content || []).map((c) => (c && c.text) || '').join(' '); + if (/unrecognized/i.test(txt)) return; + const toks = tokenizeCmd(cmd) || []; + // key=value 属性里的路径同样检查(如 src=/workspace/…):缺失才附同步教学 Hint + if (!toks.some((x) => { const v = x.includes('=') && !x.slice(0, x.indexOf('=')).includes('/') ? x.slice(x.indexOf('=') + 1) : x; return v.startsWith(watch.WORKSPACE + '/') && !fs.existsSync(v); })) return; + const first = (res.content || []).find((c) => c && typeof c.text === 'string'); + if (first) first.text += '\nHint: ' + SYNC_TEACH; +} + +// save/close 是 AI 的原生收尾仪式:成功时附限时取件链接(同 core /p/:URL 即能力),下载回任务目录的动作留给 AI +function deliverNote(cmd, reply) { + if (!/^(save|close)\b/.test(cmd)) return; + const res = reply && reply.result; + if (!res || res.isError || !Array.isArray(res.content)) return; + const toks = (tokenizeCmd(cmd) || []).filter((t) => t.startsWith(watch.WORKSPACE + '/') && OFFICE_EXT_RE.test(t) && fs.existsSync(t)); + if (!toks.length) return; + const first = res.content.find((c) => c && typeof c.text === 'string'); + if (!first) return; + first.text += toks.map((t) => '\ndownload url: ' + DL_BASE + '/f/' + watch.dlMint(t)).join(''); +} + +// ---------- 预览伪命令(桥内拦截,不落 vendor 进程)---------- +// watch 族命令不走透传(常驻服务占死 stdio 会挂满超时):从命令尾取文件参数,跳过旗标,支持引号 +function watchArg(rest) { + let s = String(rest || '').trim(); + s = s.replace(/^--port(?:\s*=|\s+)\S+\s*/, ''); + s = s.replace(/\s+--port(?:\s*=|\s+)\S+/, ''); + const m = /^"([^"]*)"|^'([^']*)'|^(\S+)/.exec(s); + return m ? (m[1] !== undefined ? m[1] : m[2] !== undefined ? m[2] : m[3]) : ''; +} + +// ---------- 命令治理:路径自动绝对化 / 黑名单 / 部署技能(能用代码处理的绝不写成提示词) ---------- +const quoteArg = (s) => (/[\s"'\\]/.test(s) ? "'" + s.replace(/'/g, "'\\''") + "'" : s); + +// 引号感知分词;引号不闭合返回 null(调用方放弃改写,不动原命令) +function tokenizeCmd(s) { + const out = []; let cur = null, q = null; + for (const c of s) { + if (q) { if (c === q) q = null; else cur += c; continue; } + if (c === '"' || c === "'") { if (cur === null) cur = ''; q = c; continue; } + if (/\s/.test(c)) { if (cur !== null) { out.push(cur); cur = null; } continue; } + if (cur === null) cur = ''; + cur += c; + } + if (q !== null) return null; + if (cur !== null) out.push(cur); + return out; +} + +const OFFICE_EXT_RE = /\.(?:docx|xlsx|pptx)$/i; +// 资源图(插图命令的参数)也要绝对化:vendor cwd 是工作区根而非会话目录,裸 logo.png 会错解到 /workspace/logo.png +const RESOURCE_EXT_RE = /\.(?:png|jpe?g|gif|webp|bmp|tiff?)$/i; +// --input 类数据文件同样要绝对化:原生 cwd 是工作区根而非会话目录,裸名永远碰不到会话目录里的文件 +const DATA_EXT_RE = /\.(?:json|csv|tsv|txt|md)$/i; +// push 目标类型白名单:office + 资源图 + 常见数据;服务端不落盘执行任何内容,风险主要是工作区积灰,白名单聊胜于无 +const PUSH_EXT_RE = /\.(?:docx|xlsx|pptx|pdf|csv|txt|json|md|png|jpe?g|gif|webp|bmp|tiff?)$/i; +function absToken(t, sess) { + if (!t || t.startsWith('-') || t.startsWith('/') || /:\/\//.test(t)) return t; + // key=value 属性(如 src=a.png):只对值部分绝对化再拼回 key= 前缀;整体拼会把 src= 也吃进路径 + let key = ''; + let val = t; + const eq = t.indexOf('='); + if (eq > 0 && !t.slice(0, eq).includes('/')) { key = t.slice(0, eq + 1); val = t.slice(eq + 1); } + if (!val || val.startsWith('-') || val.startsWith('/') || /:\/\//.test(val)) return t; + const core = val.replace(/^(?:\.\.?\/)+/, ''); + if (!OFFICE_EXT_RE.test(core) && !RESOURCE_EXT_RE.test(core) && !DATA_EXT_RE.test(core)) return t; + return key + sess + '/' + core; +} +// 裸文件名/相对路径 → 会话目录绝对路径(X-Session-Dir);没有实际改动时原样返回,最小侵入 vendor 解析 +function absolutize(cmd, sessDir) { + if (!sessDir || !sessDir.startsWith('/')) return cmd; + const sess = sessDir.replace(/\/+$/, ''); + const toks = tokenizeCmd(cmd); + if (!toks) return cmd; + let changed = false; + const out = toks.map((t) => { const a = absToken(t, sess); if (a !== t) changed = true; return a; }); + return changed ? out.map(quoteArg).join(' ') : cmd; +} + +// 用法指引:只讲 AI 用得上的(预览链接是固定格式、前端自拼,AI 面不出现 url;也从不要求 AI 主动 watch) +const DEPLOY_SKILL = `# office-preview usage + +## Read back the user's selection +get-pos +Returns the structured node the user selected in the live preview. The @id= in its path stays stable across later edits; use it directly with set / get to target the change. + +## Sync: your task directory and the workspace are two separate disks +Check: files lists what the workspace (server side) already holds. +Pull in: to edit a file that already exists in your task directory, sign its link with mint_public_link first, then push . +Hand back: every edit is flushed to disk automatically. Before delivery, save to get the download url and download it into your task directory; if you edit again afterwards, save and download again. close does the same.`; + +// tools/list 时追加的唯一一句:能力 + 指针,零教条(规矩全在代码与错误文案里) +const DESC_PATCH = '\n\nExtensions: push pulls a URL file into the workspace; files lists the files already inside the workspace (server side); get-pos reads back what the user selected in the live preview; every edit is auto-saved to disk; before delivery run save and download the returned download url into your task directory. Full usage: load_skill office-preview.'; +// ---------- Streamable HTTP 入口 ---------- +// vendor 的 picture 类型收图片属性名为 src,AI 惯写 path=(会被报 'src' property is required): +// --type picture/image 时把属性键 path= 别名成 src=(token 层替换,不碰值) +// --commands 内联 JSON 保护:分词器按 POSIX 规则吞词中引号,绝对化触发整行重组后 +// JSON 会被剥光双引号(原生报 invalid start of property name)。在分词前从原始串 +// 扫描出配平的 JSON,单引号包裹后放回(原生认单引号包裹,含内部双引号/空格)。 +// 但原生不认 POSIX 的单引号转义 '\'':JSON 内含 ' 时改写会话目录点文件走 --input +// (绝对路径通道已实测可靠;点文件对 files 隐藏,随会话 purge/TTL 回收)。 +// 解析不了就原样放行,桥不装懂。 +function quoteInlineJson(cmd, sessDir) { + const m = /(^|\s)--commands(?:=|[ \t]+)/.exec(cmd); + if (!m) return cmd; + const head = cmd.slice(0, m.index) + m[1]; + const valStart = m.index + m[0].length; + const rest = cmd.slice(valStart); + const lead = /^\s*/.exec(rest)[0]; + const body = rest.slice(lead.length); + if (body[0] === "'" || body[0] === '"') return cmd; // 已自带外层引号,交给现有分词管线 + const json = scanBalancedJson(body); + if (!json) return cmd; + const tail = body.slice(json.length).replace(/^\s+/, ''); + let flag = '--commands', val; + if (!json.includes("'")) val = quoteArg(json); + else if (sessDir && sessDir.startsWith('/')) { + const fp = sessDir.replace(/\/+$/, '') + '/.batch-inline-' + Date.now().toString(36) + '.json'; + try { fs.writeFileSync(fp, json); flag = '--input'; val = quoteArg(fp); } catch (_) { return cmd; } + } else return cmd; + return head + flag + ' ' + val + (tail ? ' ' + tail : ''); +} + +// 从首个 [ / { 起扫描 balanced JSON 片段(处理 "..." 字符串与 \ 转义); +// 配平后再 JSON.parse 验真,不成 = 返回 null 放弃改写 +function scanBalancedJson(s) { + if (s[0] !== '[' && s[0] !== '{') return null; + let depth = 0, inStr = false, esc = false; + for (let i = 0; i < s.length; i++) { + const c = s[i]; + if (inStr) { if (esc) esc = false; else if (c === '\\') esc = true; else if (c === '"') inStr = false; continue; } + if (c === '"') inStr = true; + else if (c === '[' || c === '{') depth++; + else if (c === ']' || c === '}') { + depth--; + if (depth === 0) { + const frag = s.slice(0, i + 1); + try { JSON.parse(frag); return frag; } catch (_) { return null; } + } + } + } + return null; +} + +function pictureSrcAlias(cmd) { + if (!/(?:^|\s)--type\s+(?:picture|image)(?:\s|$)/.test(cmd)) return cmd; + const toks = tokenizeCmd(cmd); + if (!toks) return cmd; + let changed = false; + const out = toks.map((t) => { if (!/^path=/.test(t)) return t; changed = true; return 'src=' + t.slice(5); }); + return changed ? out.map(quoteArg).join(' ') : cmd; +} + +function json(res, code, obj) { + const body = JSON.stringify(obj); + res.writeHead(code, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) }); + res.end(body); +} + +function toolText(resObj) { + return { content: [{ type: 'text', text: typeof resObj === 'string' ? resObj : JSON.stringify(resObj, null, 2) }], isError: false }; +} +function toolErr(msg) { + return { content: [{ type: 'text', text: 'Error: ' + (msg && msg.message || String(msg)) }], isError: true }; +} + +async function handle(msg, pubBase, sessDir) { // pubBase/sessDir:调用方每请求注入(X-Public-Base / X-Session-Dir) + const isReq = msg.id !== undefined && msg.id !== null; + let helpCmd = false; // 本次调用是否为 help 族:透传后要把文本对齐可调用面 + // 通知(含 notifications/initialized):透传不等回包 + if (!isReq) { sendNotify(msg.method, msg.params || {}); return null; } + + if (msg.method === 'tools/call') { + const args = msg.params && msg.params.arguments || {}; + // 命令归一:argv 数组 → 命令串;相对路径自动绝对化(会话目录由调用方头注入) + let cmd = Array.isArray(args.command) ? args.command.map((a) => quoteArg(String(a))).join(' ') : String(args.command || ''); + cmd = absolutize(pictureSrcAlias(quoteInlineJson(cmd, sessDir)), sessDir).trim(); + args.command = cmd; + // 会话目录在 scratch 卷里可能尚不存在(首建):顺手补齐,create/push 才有落点(仅工作区内); + // 但 unwatch(含 --purge)是清理命令,不得反向重建刚删的目录 + if (sessDir && !/^unwatch\b/.test(cmd)) { + const sd = path.resolve(sessDir); + if (sd.startsWith(watch.WORKSPACE + '/')) { try { fs.mkdirSync(sd, { recursive: true }); } catch (_) {} } + } + + // 本部署不合适的命令(装自己/装环境那族):报原生风格 unrecognized,不露壳; + // help 清单里的这些行同步在 alignHelp 删除,可见面 = 可调用面。 + const mblk = /^(mcp|skills|install|plugins)(?:\s|$)/.exec(cmd) || /^help\s+(mcp|skills|install|plugins)(?:\s|$)/.exec(cmd); + if (mblk) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized(mblk[1])) }; + helpCmd = /^help(?:\s|$)/.test(cmd) || /(?:^|\s)(?:--help|-h)(?:\s|$)/.test(cmd); + // view 放开结构/语义模式(outline/stats/issues/text/annotated),只拦渲染族(需无头浏览器/导出插件,本环境没有); + // 给模型指明替代路径,别让它抱着文档里的强制渲染门反复试错。 + if (!helpCmd && /^view(?:\s|$)/.test(cmd)) { + const vpos = (tokenizeCmd(cmd) || []).slice(1).filter((t) => !t.startsWith('-')); // [file, mode, ...] + const vmode = String(vpos[1] || '').toLowerCase(); + if (VIEW_BLOCKED.has(vmode)) { + return { jsonrpc: '2.0', id: msg.id, result: toolErr( + "view " + vmode + " is disabled by environment policy. Use 'view outline' or 'view issues' for structural/semantic checks.") }; + } + } + // 部署技能:伪装进 vendor 的 load_skill 机制;无名/vendor 已知名照旧透传(清单/其它技能) + const ms = /^load_skill\b\s*([\s\S]*)$/.exec(cmd); + if (ms && /^(?:office[-_]?preview|preview)$/.test(ms[1].trim().replace(/^["']|["']$/g, ''))) { + return { jsonrpc: '2.0', id: msg.id, result: toolText(DEPLOY_SKILL) }; + } + // files(桥扩展):列当前会话目录(工作区侧)下的文件,AI 据此判断哪些文件已同步进来; + // 只报相对文件名,隐藏文件/目录略去,深度与条数封顶。 + if (!helpCmd && /^files(?:\s|$)/.test(cmd)) { + const root = sessDir ? path.resolve(sessDir) : ''; + if (!root.startsWith(watch.WORKSPACE + '/')) return { jsonrpc: '2.0', id: msg.id, result: toolErr('files: no workspace session directory for this request') }; + const names = []; + (function walk(dir, depth) { + if (depth > 4 || names.length >= 500) return; + let ents; + try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; } + for (const e of ents) { + if (e.name.startsWith('.')) continue; + const p = path.join(dir, e.name); + if (e.isDirectory()) walk(p, depth + 1); + else if (names.length < 500) names.push(path.relative(root, p)); + } + })(root, 0); + return { jsonrpc: '2.0', id: msg.id, result: toolText('# Workspace (server-side):\n' + (names.length ? names.join('\n') : '(no files)')) }; + } + // 桥内拦截(不占 vendor stdio;对 AI 不公示,见 DEPLOY_SKILL):watch/unwatch 仅本会话目录, + // unwatch --session <本会话id> 供 core 会话清理钩子,get-pos 改写原生回读,push 外链拉入 + const mr = /^(watch|unwatch|get-pos|push)\b([\s\S]*)$/.exec(cmd); + if (mr) { + const rest = String(mr[2] || '').trim(); + const file = watchArg(rest.replace(/(?:^|\s)--session(?:\s*=|\s+)\S+/g, ' ')); + const jail = sessDir ? path.resolve(sessDir) : watch.WORKSPACE; + const inJail = (x) => x && path.resolve(x).startsWith(jail + '/'); + try { + if (mr[1] !== 'push' && HIDDEN_SUBS.has(file)) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized(file)) }; + if (mr[1] === 'push') { + const toks = tokenizeCmd(rest) || []; + const url = String(toks[0] || ''); + const dest = toks[1] || ''; + if (!/^https?:\/\//i.test(url) || !dest) throw new Error('Usage: push (url is typically a link signed by mint_public_link)'); + const abs = pushTarget(dest, jail); + // 成功/失败文案只带相对文件名:工作区绝对路径对 AI 是干扰项(与任务目录同名不同盘) + let name = path.relative(jail, abs); if (name.startsWith('..')) name = path.basename(abs); + if (fs.existsSync(abs) && !/(?:^|\s)--force\b/.test(rest)) throw new Error('File already exists: ' + name + '. Use --force to overwrite.'); + // AI 视角是把文件「上传」进工作区,不说 download + let r; + try { r = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(PUSH_TIMEOUT_MS) }); } + catch (e) { throw new Error('Failed to read file: ' + String(e && e.message || e).slice(0, 120) + ' (link expired or unreachable? re-sign with mint_public_link and retry)'); } + if (!r.ok) throw new Error('Failed to read file: HTTP ' + r.status + ' (link expired? re-sign with mint_public_link and retry)'); + const data = Buffer.from(await r.arrayBuffer()); + if (data.length > PUSH_MAX_BYTES) throw new Error('File too large: limit is ' + Math.floor(PUSH_MAX_BYTES / 1048576) + ' MB'); + fs.mkdirSync(path.dirname(abs), { recursive: true }); + fs.writeFileSync(abs, data); + return { jsonrpc: '2.0', id: msg.id, result: toolText('Imported: ' + name) }; + } + if (mr[1] === 'watch') { + if (!file) throw new Error('Usage: watch '); + if (!inJail(file)) throw new Error('Preview is only available for documents inside the current session directory: ' + file); + // 预览链接是固定格式、前端自拼:url/path 不透给 AI 面 + const winfo = Object.assign({}, await watch.start(file, pubBase)); + delete winfo.url; delete winfo.path; + return { jsonrpc: '2.0', id: msg.id, result: toolText(winfo) }; + } + if (mr[1] === 'get-pos') { + if (!file) throw new Error('Usage: get-pos (works once the user opens the preview and selects something)'); + // 文件不存在:vendor 风格失败信封 {success:false, message},只报相对文件名,顺手带上两盘同步指引 + if (!fs.existsSync(path.resolve(file))) { + let nm = path.relative(jail, path.resolve(file)); if (nm.startsWith('..')) nm = path.basename(file); + return { jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: JSON.stringify({ + success: false, + message: 'File not found: ' + nm + '. If it lives in your task directory, sign a link with mint_public_link and pull it in with push .' + }, null, 2) }], isError: true } }; + } + // 没有预览槽在跑 = 没有选区来源:直接回空结果(信封与 vendor 一致:{success, data})。 + // watch 与否不需要 AI 关心,别把这事抛回给模型。 + if (![...watch.slots.values()].some((s) => s.file === path.resolve(file))) { + return { jsonrpc: '2.0', id: msg.id, result: toolText({ success: true, data: { matches: 0, results: [] } }) }; + } + cmd = 'get ' + quoteArg(file) + ' selected --json'; // 语义糖:改写为原生命令走原生回读实现 + args.command = cmd; + } else { + const msess = /(?:^|\s)--session(?:\s*=|\s+)(\S+)/.exec(rest); // core 会话清理专用:会话号必须等于本次请求的会话目录 + if (msess) { + const sid = decSafe(msess[1]); + // --purge(资源篮/core 删会话专用):杀槽之外连带删会话目录副本(幂等) + const purge = /(?:^|\s)--purge(?:\s|$)/.test(rest); + if (sid && sid === path.basename(jail)) return { jsonrpc: '2.0', id: msg.id, result: toolText(watch.stopSession(sid, purge)) }; + return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized('unwatch')) }; + } + if (!file) throw new Error('Usage: unwatch '); + if (!inJail(file)) return { jsonrpc: '2.0', id: msg.id, result: toolErr(unrecognized('unwatch')) }; + return { jsonrpc: '2.0', id: msg.id, result: toolText(watch.stopOne(file)) }; + } + } catch (e) { + const t = String(e && e.message || e); + return { jsonrpc: '2.0', id: msg.id, result: toolErr(/文件不存在|not found/i.test(t) ? t + ' Hint: ' + SYNC_TEACH : t) }; + } + } + watch.touch(cmd); // 命中的预览槽位续命 + } + + try { + if (msg.method === 'initialize') { + if (!ready) { + // 子进程新鲜:客户端握手就是它的真握手(顺序天然正确) + const fresh = await rpc('initialize', msg.params || {}); + sendNotify('notifications/initialized', {}); + ready = true; fresh.id = msg.id; + return fresh; + } + // 子进程已被桥自举初始化:.NET SDK 不容二次握手、officecli 又单实例不容换新 —— 桥层合成应答 + return { jsonrpc: '2.0', id: msg.id, result: { + protocolVersion: (msg.params && msg.params.protocolVersion) || '2024-11-05', + capabilities: { tools: {} }, + serverInfo: { name: 'officecli', version: '1.0' } } }; + } + if (!ready) { await selfInit(); ready = true; } + const reply = await rpc(msg.method, msg.params || {}); + if (msg.method === 'tools/list' && reply.result && Array.isArray(reply.result.tools)) { + for (const t of reply.result.tools) { + if (t) t.description = String(t.description || '') + DESC_PATCH; // 部署侧须知随描述发给模型 + } + } + if (helpCmd) alignHelp(reply); // help 文本对齐可调用面:隐去命令删行,扩展命令补录 + if (msg.method === 'tools/call' && sessDir) { // 两份盘的教学与交付链都附在响应里(cmd 作用域仅限 tools/call 块,这里从参数重建) + const c = String((msg.params && msg.params.arguments || {}).command || ''); + teachOnMiss(c, reply); deliverNote(c, reply); ackNote(c, reply, sessDir); scrubErr(reply); + } + reply.id = msg.id; // 桥接 id 换回调用方 id + return reply; + } catch (e) { + try { if (child) child.kill(); } catch (_) {} + resetChild(); // 桥级失败(超时/进程死):换掉子进程,下次请求从干净状态重建 + return { jsonrpc: '2.0', id: msg.id, error: { code: -32603, message: String(e && e.message || e) } }; + } +} + +const server = createServer((req, res) => { + const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`); + if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/health')) { + return json(res, 200, { name: SERVER_NAME, transport: 'streamable-http->stdio', preview: { port: PREVIEW_PORT, prefix: watch.PREFIX }, preview_slots: watch.status('') }); + } + if (req.method !== 'POST') return json(res, 404, { error: 'POST / only' }); + let body = ''; + req.on('data', (c) => { body += c; }); + req.on('end', () => { + let msg; try { msg = JSON.parse(body); } catch (_) { return json(res, 400, { error: 'bad json' }); } + handle(msg, String(req.headers['x-public-base'] || '').replace(/\/+$/, ''), String(req.headers['x-session-dir'] || '')).then((r) => { if (r === null) { res.writeHead(202).end(); return; } json(res, 200, r); }) + .catch((e) => json(res, 500, { error: String(e && e.message || e) })); + }); +}); + +// ---------- 优雅退出(容器 PID1 惯例,同 web_search) ---------- +function shutdown(sig) { + console.log(`[${SERVER_NAME}] 收到 ${sig},停止服务`); + try { if (child) child.kill(); } catch (_) {} + try { previewServer.close(); } catch (_) {} + server.close(() => process.exit(0)); + setTimeout(() => process.exit(0), 3000).unref(); +} +process.on('SIGTERM', () => shutdown('SIGTERM')); +process.on('SIGINT', () => shutdown('SIGINT')); + +const previewServer = gateway.start(PREVIEW_PORT, HOST); // 预览网关:单入口按任务路径路由,槽位号不出容器 + +server.listen(PORT, HOST, () => { + console.log(`${SERVER_NAME} HTTP listening on http://${HOST}:${PORT} (officecli mcp bridge, workspace=${watch.WORKSPACE}, slots=${process.env.OFFICE_SLOTS || 4}, preview=:${PREVIEW_PORT}${watch.PREFIX}/…)`); +}); diff --git a/mcp/officecli/watch.js b/mcp/officecli/watch.js new file mode 100644 index 0000000..53b7a07 --- /dev/null +++ b/mcp/officecli/watch.js @@ -0,0 +1,328 @@ +// watch 槽位管理:officecli watch 只绑 127.0.0.1(实测),且 watch 进程必须与 +// officecli MCP 子进程同容器(刷新信号 = 进程内 IPC,跨容器收不到)。 +// 本模块在 shim(容器 PID1)里 spawn watch 子进程 → 跨命令存活。 +// 不再开对外 TCP 转发口:预览路由交给 gateway.js —— url 按任务身份组织 +// (/preview/<会话id>/<文档相对路径>/),槽位号不出容器。 +// 槽位语义 = 可再生缓存而非承诺:链接按任务路径寻址,被回收/被别人挤掉后 +// 页面再访问由 gateway 就地复活(revive)。因此闲置阈值可以放心激进,AI 忘了 +// unwatch 不再有实质危害。 +'use strict'; +const net = require('node:net'); +const fs = require('node:fs'); +const path = require('node:path'); +const crypto = require('node:crypto'); +const { spawn } = require('node:child_process'); + +const WORKSPACE = process.env.OFFICE_WORKSPACE || '/workspace/tasks'; +const SLOTS = Number(process.env.OFFICE_SLOTS || 4); +const WATCH_BASE = Number(process.env.OFFICE_WATCH_BASE || 26315); // watch 自身端口(+slot),仅容器内回环 +const PREFIX = (process.env.OFFICE_PREVIEW_PREFIX || '/preview').replace(/\/+$/, ''); +const IDLE_MS = Number(process.env.OFFICE_IDLE_MS || 6 * 3600 * 1000); // 闲置回收阈值(默认 6h;槽=缓存,链接自愈,激进无副作用) +const EXTS = new Set(['.docx', '.xlsx', '.pptx']); + +const slots = new Map(); // slot -> {file, task, rel, port, watch, lastUsed, conns, pageDec, pageEnc} +const starting = new Map(); // 文件绝对路径 -> Promise:同文件并发 watch 合并为一次 spawn(watch 启动需秒级,窗口不窄) + +function log(...a) { console.log('[watch]', ...a); } + +// 路径护栏:限定 WORKSPACE 下的办公文档,禁止穿越 +function guard(p) { + const abs = path.resolve(WORKSPACE, String(p || '')); + const rel = path.relative(path.resolve(WORKSPACE), abs); + if (rel.startsWith('..') || path.isAbsolute(rel)) throw new Error('Path must be inside ' + WORKSPACE + ': ' + p); + if (!EXTS.has(path.extname(abs).toLowerCase())) throw new Error('Only .docx/.xlsx/.pptx files are supported: ' + p); + if (!fs.existsSync(abs)) throw new Error('File not found: ' + p); + return abs; +} + +// 文件 → 预览页前缀:WORKSPACE/<会话>/ → /<会话>/(另有分段编码形态供 url 用)。 +// 任务根下的文件没有预览页(url 必须挂在会话身份下,才能鉴权/稳定),要求至少两层。 +function pageOf(abs) { + const segs = path.relative(path.resolve(WORKSPACE), abs).split(path.sep).filter(Boolean); + if (segs.length < 2) throw new Error('Preview only supports files under a session directory (<' + WORKSPACE + '//...>): ' + abs); + return { + task: segs[0], + rel: segs.slice(1).join('/'), + pageDec: '/' + segs.join('/'), + pageEnc: '/' + segs.map((s) => encodeURIComponent(s)).join('/'), + }; +} + +function portUp(port, tries = 40) { + return new Promise((res, rej) => { + let n = 0; + (function probe() { + const s = net.connect(port, '127.0.0.1'); + s.on('connect', () => { s.destroy(); res(); }); + s.on('error', () => { s.destroy(); if (++n >= tries) return rej(new Error('watch server did not come up')); setTimeout(probe, 250); }); + })(); + }); +} + +async function start(file, publicBase) { + const abs = guard(file); + for (const [slot, s] of slots) if (s.file === abs) { s.lastUsed = Date.now(); return info(slot, publicBase); } + if (starting.has(abs)) { // vendor 限制同文件只许一个 watch:并发调用共享在飞的启动结果 + try { await starting.get(abs); } catch (_) {} + for (const [slot, s] of slots) if (s.file === abs) return info(slot, publicBase); + throw new Error('Failed to start watch (concurrent start for the same file); retry'); + } + const p = spawnWatch(abs, publicBase).finally(() => starting.delete(abs)); + starting.set(abs, p); + return p; +} + +async function spawnWatch(abs, publicBase) { + const page = pageOf(abs); // 先验证 url 可组织,再占坑 + let slot = -1; + for (let i = 0; i < SLOTS; i++) if (!slots.has(i)) { slot = i; break; } + if (slot < 0) { // 槽位满:优先踢「没有在看且最久未用」;全都有活动连接(= 页面开着)才抢最冷的活跃槽 + const ent = [...slots.entries()]; + const idle = ent.filter(([, s]) => !s.conns); + slot = (idle.length ? idle : ent).sort((a, b) => a[1].lastUsed - b[1].lastUsed)[0][0]; + stop(slot); + } + const wp = WATCH_BASE + slot; + const child = spawn('officecli', ['watch', abs, '--port', String(wp)], { stdio: 'ignore' }); + child.on('exit', () => { if (slots.get(slot)?.watch === child) stop(slot); }); + const entry = { file: abs, task: page.task, rel: page.rel, port: wp, watch: child, lastUsed: Date.now(), conns: 0, pageDec: page.pageDec, pageEnc: page.pageEnc }; + slots.set(slot, entry); // 同步占坑:等端口就绪期间也不给并发 spawn 踩同一槽 + try { + await portUp(wp); + } catch (e) { + child.kill(); + if (slots.get(slot) === entry) slots.delete(slot); + throw new Error('Failed to start watch (only one watch per file is allowed): ' + e.message); + } + log(`slot${slot} ${abs} watch:${wp} page=${PREFIX}${page.pageDec}`); + return info(slot, publicBase); +} + +function stop(slot) { + const s = slots.get(slot); + if (!s) return false; + try { s.watch.kill(); } catch (_) {} + slots.delete(slot); + log(`slot${slot} 已停止`); + return true; +} + +function stopOne(file) { + const abs = guard(file); + for (const [slot, s] of slots) if (s.file === abs) { stop(slot); return { stopped: abs }; } + throw new Error('No watch running for this file: ' + abs); +} + +// command 透传时顺带给命中的槽位续命(AI 活跃 = 预览还有人关心) +function touch(command) { + for (const s of slots.values()) if (String(command || '').includes(s.file)) s.lastUsed = Date.now(); +} + +function info(slot, publicBase) { + const s = slots.get(slot); + return { + slot: slot, file: s.file, + path: PREFIX + s.pageEnc + '/', + url: (publicBase || '') + PREFIX + s.pageEnc + '/', + idle_min: Math.round((Date.now() - s.lastUsed) / 60000), // 闲置分钟(watch ls 给模型/用户看活性) + conns: s.conns || 0, // 正在回传的预览请求数(SSE 在场 = 页面开着) + }; +} + +// gateway 路由用:rel = 已解码、剥掉 PREFIX 的请求路径(以 / 开头); +// exact = 正好是页面本身(缺尾斜杠由 gateway 补 301),prefix = 页面下的资源/端点。最长前缀优先。 +function matchPage(rel) { + if (!rel) return null; + const rr = rel.startsWith('/') ? rel : '/' + rel; + let best = null; + for (const s of slots.values()) { + if (rr === s.pageDec) return { entry: s, exact: true }; + if (rr.startsWith(s.pageDec + '/')) { + if (!best || s.pageDec.length > best.entry.pageDec.length) best = { entry: s, exact: false }; + } + } + return best; +} + +function status(publicBase) { + return [...slots.keys()].map((slot) => info(slot, publicBase)); +} + +// 会话结束批量清理:core 删会话时经桥打一发 unwatch --session <会话id> [--purge]。 +// --purge:连带删除该会话在本工作区的目录副本(任务真相在 core/executor 侧,这里只是可再生 scratch); +// purge 语义下幂等:无槽/目录不存在都不报错,只在会话号非法时拒(防穿越)。 +function stopSession(taskId, purge) { + const t = String(taskId || ''); + const stopped = []; + for (const [slot, s] of slots) if (s.task === t) { stop(slot); stopped.push(s.file); } + let purged = false; + if (purge) { + if (!t || t === '.' || t === '..' || /[/\\]/.test(t) || t.includes('\0')) throw new Error('Invalid session id.'); + const dir = path.join(path.resolve(WORKSPACE), t); + if (path.relative(path.resolve(WORKSPACE), dir) !== t) throw new Error('Invalid session id.'); + if (fs.existsSync(dir)) { try { fs.rmSync(dir, { recursive: true, force: true }); purged = true; log('会话 purge:', t); } catch (_) {} } + } + if (!stopped.length && !purge) throw new Error('No watch running for this session: ' + t); + return { session: t, stopped, purged }; +} + +// gateway 未命中兜底:请求路径本身就是一个存在的会话文档 → 回收/被挤掉后就地复活。 +// 只接受整体形如办公文档的路径(扩展名把关);/api/… 等资源路径无扩展名 → null,404 语义不变。 +async function revive(rel) { + const rr = (rel || '').replace(/\/+$/, ''); + if (!rr || rr === '/') return null; + try { + await start(path.join(WORKSPACE, rr)); // guard/pageOf 复核越界、存在性、会话层级;不行 = 维持原 404 + return matchPage(rr); + } catch (_) { return null; } +} + +// 纯路径推导预览页地址(无需 watch 在场;布局不满足——越界/任务根下——返回 null) +function pageUrl(abs, publicBase) { + const rel = path.relative(path.resolve(WORKSPACE), abs); + if (!rel || rel === '..' || rel.startsWith('..' + path.sep) || path.isAbsolute(rel)) return null; + let page; + try { page = pageOf(abs); } catch (_) { return null; } + const p = PREFIX + page.pageEnc + '/'; + return { path: p, url: (publicBase || '') + p }; +} + +// ---------- /f/ 交付能力链:save/close 成功时签发(同 core /p/ 的设计:随机 id + TTL,URL 即能力)---------- +const DL_TTL_MS = Number(process.env.OFFICE_DL_TTL_MS || 30 * 60 * 1000); +const DL_MAX = 512; +const dls = new Map(); // token -> { abs, exp } +const MIME = { + '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', + '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', + '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation', +}; + +function dlMint(abs) { + const now = Date.now(); + for (const [k, v] of dls) if (v.exp <= now) dls.delete(k); + // 同一文件重复 save/close 复用原 token(滑动 TTL):serveDl 实时读盘,链接永远指向盘上最新内容,AI 改完重新下载原链即可 + for (const [k, v] of dls) if (v.abs === abs) { v.exp = now + DL_TTL_MS; return k; } + while (dls.size >= DL_MAX) dls.delete(dls.keys().next().value); + const token = crypto.randomBytes(16).toString('base64url'); + dls.set(token, { abs, exp: now + DL_TTL_MS }); + return token; +} + +function serveDl(token, req, res) { + const e = token ? dls.get(token) : null; + if (!e || e.exp <= Date.now()) { + if (e) dls.delete(token); + res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('Link not found or expired. Run save on the file again to issue a new link.'); + return; + } + let st; + try { st = fs.statSync(e.abs); } catch (_) { + dls.delete(token); + res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('File is no longer in the workspace; save or push it again first'); + return; + } + if (!st.isFile()) { res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('File is no longer in the workspace; save or push it again first'); return; } + const base = path.basename(e.abs); + const ascii = base.replace(/[^\x20-\x7e]|["\\]/g, '_') || 'document'; + res.writeHead(200, { + 'content-type': MIME[path.extname(base).toLowerCase()] || 'application/octet-stream', + 'content-length': String(st.size), + 'content-disposition': 'attachment; filename="' + ascii + '"; filename*=UTF-8\'\'' + encodeURIComponent(base), + 'cache-control': 'no-store', + }); + fs.createReadStream(e.abs).pipe(res); +} + +// ---------- scratch 卫生:这份盘只是工作副本(交付真相在 core 的 tasks),两道闸:闲置 TTL + 容量水位 ---------- +const SCRATCH_TTL_MS = Number(process.env.OFFICE_SCRATCH_TTL_MS || 7 * 24 * 3600 * 1000); +// 容量水位:总量(含 busy)超上限时,按目录最新 mtime 从旧到新删非 busy 目录,删到低水位为止。 +// busy(正开预览)永不触碰,宁可短时超水位也不打扰活跃会话;编辑即落盘会把 mtime 刷新,活跃会话天然排最后。 +const SCRATCH_MAX_BYTES = Number(process.env.OFFICE_SCRATCH_MAX_BYTES || 2 * 1073741824); // 0 = 关 +const SCRATCH_LOW_RATIO = 0.8; + +function newestMtime(dir, budget) { // 目录树最新 mtime;budget 封顶防巨目录卡住定时器 + let best = 0; + try { best = fs.statSync(dir).mtimeMs; } catch (_) { return 0; } + const stack = [dir]; + while (stack.length && budget.n > 0) { + const d = stack.pop(); + let ents; + try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { continue; } + for (const en of ents) { + if (budget.n-- <= 0) break; + const p = path.join(d, en.name); + if (en.isSymbolicLink()) continue; + if (en.isDirectory()) { stack.push(p); continue; } + try { const m = fs.statSync(p).mtimeMs; if (m > best) best = m; } catch (_) {} + } + } + return best; +} + +function dirSize(dir, budget) { // 目录树总字节;budget 封顶,截断时偏小(水位是粗粒度启发式,可接受) + let total = 0; + const stack = [dir]; + while (stack.length && budget.n > 0) { + const d = stack.pop(); + let ents; + try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch (_) { continue; } + for (const en of ents) { + if (budget.n-- <= 0) break; + const p = path.join(d, en.name); + if (en.isSymbolicLink()) continue; + if (en.isDirectory()) { stack.push(p); continue; } + try { total += fs.statSync(p).size; } catch (_) {} + } + } + return total; +} + +function pruneScratch() { + if (!(SCRATCH_TTL_MS > 0) && !(SCRATCH_MAX_BYTES > 0)) return []; + const now = Date.now(); + const busy = new Set([...slots.values()].map((s) => path.relative(WORKSPACE, s.file).split(path.sep)[0])); + let tops; + try { tops = fs.readdirSync(WORKSPACE, { withFileTypes: true }); } catch (_) { return []; } + const removed = []; + // 道闸一:闲置 TTL(整目录最新 mtime 超时即回收) + if (SCRATCH_TTL_MS > 0) { + for (const en of tops) { + if (!en.isDirectory() || en.isSymbolicLink() || busy.has(en.name)) continue; + const dir = path.join(WORKSPACE, en.name); + const m = newestMtime(dir, { n: 800 }); + if (m && now - m > SCRATCH_TTL_MS) { + try { fs.rmSync(dir, { recursive: true, force: true }); removed.push(en.name); } catch (_) {} + } + } + } + // 道闸二:容量水位总量超限则从旧到新删非 busy 目录,删到低水位或候选耗尽 + if (SCRATCH_MAX_BYTES > 0) { + const infos = []; + let total = 0; + for (const en of tops) { + if (!en.isDirectory() || en.isSymbolicLink()) continue; + const dir = path.join(WORKSPACE, en.name); + const size = dirSize(dir, { n: 4000 }); + total += size; + if (!busy.has(en.name) && !removed.includes(en.name)) infos.push({ name: en.name, dir, size, m: newestMtime(dir, { n: 800 }) }); + } + infos.sort((a, b) => a.m - b.m); + const lowLimit = SCRATCH_MAX_BYTES * SCRATCH_LOW_RATIO; + for (const it of infos) { + if (total <= lowLimit) break; + try { fs.rmSync(it.dir, { recursive: true, force: true }); total -= it.size; removed.push(it.name); } catch (_) {} + } + } + if (removed.length) log('scratch 清理:', removed.join(', ')); + return removed; +} +setInterval(pruneScratch, 3600 * 1000).unref(); +setTimeout(pruneScratch, 10000).unref(); // 重启后不等整点,早扫一轮 + +setInterval(() => { + const now = Date.now(); + // 有活动连接的槽 = 有人正开着页面,永不闲置回收(槽满时它最后被抢,见 spawnWatch) + for (const [slot, s] of slots) if (!s.conns && now - s.lastUsed > IDLE_MS) { log(`slot${slot} 闲置回收`); stop(slot); } +}, 60000).unref(); + +module.exports = { start, stop, stopOne, stopSession, touch, status, guard, slots, IDLE_MS, matchPage, revive, pageUrl, dlMint, serveDl, pruneScratch, DL_TTL_MS, WORKSPACE, PREFIX };