Files
agent/mcp/officecli/README.md
T
2026-10-19 09:11:16 +08:00

121 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/<id>` 交付能力链签发与取件;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 <file> html` / `screenshot` / `svg` / `pdf` / `forms`(需无头浏览器/导出插件)拦截,返回 `view <mode> is disabled by environment policy. Use 'view <file> outline' or 'view <file> issues' for structural/semantic checks.` |
| 回包文案 | `create` / `open` / `push` 成功只回 `Created/Opened/Imported: <相对会话目录文件名>`;预览链接不随回包出现(固定格式 `<公网前缀>/preview/<会话id>/<相对路径>/`,前端自己拼,AI 面不需要知道);`save` / `close` 成功附 `download url:`(限时取件链,同文件复用同一链接);失败文案剥掉工作区路径前缀与 vendor 异常包装,只留文件名 |
| 桥内拦截(对 AI 不公示) | `watch` / `unwatch <file>` 仅本会话目录(必须拦截:vendor 原生 watch 会占死 stdio;help 里同步不显示);`unwatch --session <id> [--purge]` 校验 id==X-Session-Dir 尾段,core 会话清理钩子专用 [--purge 杀槽外连带删会话目录副本,幂等];`get-pos <file>` 改写原生 `get … selected --json`;`push <url> <file>` 外链拉入(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://<core 公网地址>/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 按任务组织:文档必须在会话目录下(`<WORKSPACE>/<会话id>/…`,任务根下不可预览);重启换槽不影响链接含义。
- 预览 url 不由本服务下发:链接按固定格式 `<公网前缀>/preview/<会话id>/<文档相对路径>/` 由前端自拼;`X-Public-Base` 仅供桥内 watch 状态/日志用,对 AI 的回包里 `url`/`path` 字段已被剥掉。
- 回包可附通用 UI 卡片块 `{type:'ui_card', action, arg, title?, note?}`(非 text:core 的 MCP 层剥离后不进模型面,整块经 SSE `ui_card` 转前端,动作注册表驱动渲染)。当前动作 `open_preview`:arg=相对会话目录的文件路径,聊天流出可点卡片直接开预览窗(无需等文件回任务盘);create/open/push 成功自动附带(文案由产生方给)。卡片为实时事件不落库,刷新后从任务文件列表进入。
- 槽位数 `OFFICE_SLOTS`(默认 4);满了优先踢「无活动连接且最久未用」;闲置超 `OFFICE_IDLE_MS`(默认 6h)回收,挂着活动连接的槽不回收;预览每一帧回传与 AI 命令都会续命。
- 槽位是缓存不是承诺:预览链接按任务路径寻址,被回收/挤占后页面再访问由网关就地复活(一次冷启动)。
- AI 面不公示 watch/unwatch(也没有 watch ls / --all 这类跨会话动作):预览完全由前端拼链接、网关按需复活槽位 + LRU 管理;core 删会话时经校验的 `unwatch --session <id> --purge` 清槽并删工作区目录副本(不等 scratch TTL)。
- 同一文件同时只允许一个 watch(vendor 限制;同文件并发 watch 已合并为一次启动)。
## 两份盘与同步(push / download url)
容器工作区与 `agent/tasks/<会话id>/` 是两份盘;桥负责在响应里教会 AI 换盘动线(拦截即教学,不设协议):
| 方向 | 动线 | 执行者 |
| --- | --- | --- |
| 任务目录 → 工作区 | `mint_public_link` 签发外链 → `officecli push <url> <file>` | 桥拉入(护栏:WORKSPACE 内、白名单扩展名(office/图片/常见数据)、100MB、非覆盖需 --force) |
| 工作区 → 任务目录 | `save <file>` / `close <file>` 回包尾附 `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 <file> 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 生效)。