refactor(skills): 本地安装改成「README 式说明」,install.sh/requirements.txt 归服务器

按三条原则收紧:
1) 线上零影响:office/install.sh 回退成原来的 linux-only 版本(本地本来就不该跑它);
   image-process 的字体候选表撤回(那是在代码里写环境兼容,方向错了)。
2) install.sh / requirements.txt 只做服务器工件:镜像构建与 agent-executor-init 读它们,
   行为一字未变。
3) 本机缺东西时由 .md 指路,模型自己去装:四个技能各加 INSTALL.md(具体命令 + 平台
   资产/字体表 + 验证方式),并在 SKILL.md 里各加一行指向它(skill get 就能看到)。
   报错文案带上 INSTALL.md 的绝对路径,所以「撞到缺依赖」的那一刻就能拿到说明书。

保留的两处代码钩子都不是环境探测,而是「说明书里写的安装方式得真能生效」:
- office: start.sh 把 skills/office/scripts 塞进 PATH(本地没 root 写 /usr/local/bin);
  封装层 ENOENT 指向 INSTALL.md。
- x2pdf: find_soffice() 探 macOS app bundle(brew cask 装的 soffice 不在 PATH);
  WeasyPrint 不可用时回落 LibreOffice,让本地只需一个后端而不是 pango+WeasyPrint 两条链。

INSTALL.md 里 officecli 指向 releases/latest(它会自更新,实测 1.0.157 跑一次变 1.0.160),
不要求与服务器 pin 对齐。

实测:office --version / office create / office view outline 正常;x2pdf 缺 markdown 与
image-process 缺字体两条报错都给出 INSTALL.md 绝对路径,按 font 参数即通过。
This commit is contained in:
2026-11-11 17:34:30 +08:00
parent 317397154e
commit a52b227d8b
14 changed files with 194 additions and 83 deletions
+23 -13
View File
@@ -277,21 +277,31 @@ health 只作为「端口上有服务但不是本启动器拉起的」兜底提
需要系统库的包(`weasyprint` → pango/cairo)pip 装不了,仍需用户 `brew install`;这类不在
自动修复范围内,模型只报结论。
### 4.14 `office` 本地化:平台矩阵 + PATH 直塞,不碰 `app/`
### 4.14 本地安装:`install.sh` / `requirements.txt` 归服务器,本机走 `INSTALL.md`
`office` 技能是 `SKILL.md` + `scripts/office`(Node 封装层)+ `bin/officecli`(.NET 单文件二进制)。
本地化只做两件小事:
原则:**不为了本地去改安装脚本**。`install.sh`(系统依赖/资产)与 `requirements.txt`(Python 包)
是服务器工件:镜像构建与 `agent-executor-init` 读它们,行为保持不变;`install.sh` 里只有 apt 与
linux-x64 资产,本来也不该在 mac 上跑。
- **PATH**:服务器上靠镜像里的 `/usr/local/bin/office` 软链;本地没 root 写不了系统目录,
本机「真要用到却缺东西」时,由技能自己的 `INSTALL.md` 告诉模型怎么装(`SKILL.md` 里各加一行
指向它)。写法是具体命令 + 平台表(哪些包、什么 URL、字体在哪),**不写兼容代码**:没有平台矩阵、
没有自动探测多套运行时。“不要尝试兼容所有环境”就是这个意思。
只有两处代码级的必要钩子,都不是环境探测:
- **`office` 的 PATH**:服务器靠镜像里的 `/usr/local/bin/office` 软链;本地没 root 写不了系统目录,
`start.sh` 起 core 时把 `skills/office/scripts` 直接塞进 `PATH`(脚本自身可执行,不复制、不装软链)。
`terminal` 继承 core 的 env,模型调 `office <cmd>` 即命中。
- **二进制**:`install.sh` 改成按 `uname -s/-m` 选资产(linux x64/arm64、mac x64/arm64),
校验和 pin 到上游 release 的 `SHA256SUMS`(八个平台都有,不用猜);mac 没有 `sha256sum`,
用 `shasum -a 256` 兜底。但已经存在的二进制只要能跑就沿用:officecli 会把自己更新到上游
latest(实测 1.0.157 跑一次变 1.0.160,大小与 latest 资产完全一致),拿 pin 去比对只会反复
重拉 34MB。pin 因此只约束「本次下载的东西」;服务器上卷是 `:ro`,二进制不会漂,仍走 sha 比对。
**启动器不预下载**:首次用到时,封装层报错里带 `install.sh` 的绝对路径,
模型跑一次即可(~34MB,GitHub 慢时自动换 gh-proxy)。
`terminal` 继承 core 的 env,模型调 `office <cmd>` 即命中。报错文案指向 `INSTALL.md` 绝对路径。
- **`x2pdf` 的 `find_soffice()`**:`brew install --cask libreoffice` 后 `soffice` 不在 `PATH`
(在 `/Applications/LibreOffice.app/Contents/MacOS/`),不探这几个默认位置,`INSTALL.md`
里写的“装 LibreOffice 即可”就是假的。同理保留了 WeasyPrint 不可用时回落 LibreOffice:
这让本地只需一个后端,而不是 pango + WeasyPrint 两套链。
`officecli` 会把自己更新到上游 latest(实测 1.0.157 跑一次变 1.0.160),所以 `INSTALL.md` 直接
指向 `releases/latest`,不要求与服务器 pin 的版本对齐。
没做的是预览:预览卡片要 executor 的 `:3100` 网关,本地没有。要补就相当于把
`executor/preview.js` 的槽位管理搬进 core,不值得。
没做的是预览:预览卡片要 executor 的 `:3100` 网关,本地没有。要补就相当于把
`executor/preview.js` 的槽位管理搬进 core,不值得。
@@ -367,7 +377,7 @@ tail -f local/.runtime/core.log # 以及 npm-install.log / mcp-*.log
| Windows 不支持 | `spawn('/bin/sh')`、`process.kill(-pid)`、模型写的 bash 语法都是 POSIX 语义 |
| `mint_public_link` 不可用 | 本地 `public_link.base_url` 为空,工具会回明确的「未配置」错误 |
| 技能依赖 | 本地不预装:缺包时模型会把包装进 `skills/deps`(`$AGENT_SKILLS_DEPS`,已在该进程 `PYTHONPATH` 里,装完下次运行即生效);连 `python3` 都没有时也由它自己装。怎么装由模型自己决定。需要系统库的包(`weasyprint`→pango/cairo)pip 装不了,仍需手工 `brew install`。服务器上由 `agent-executor-init` 处理 |
| `office` 二进制 | 不入库、镜像阶段不下载:首次用到时由模型按报错提示跑一次 `skills/office/install.sh`(按 `uname` 选 linux/mac 资产,下载时校验和 pin 到上游 `SHA256SUMS`,约 34MB;GitHub 慢时自动换 gh-proxy)。不需要 root,装完不需重启。officecli 会自更新到上游 latest,版本比 pin 新属正常 |
| `office` 二进制 | 不入库、也不预装:首次用到时封装层报 `binary missing` 并给出同目录 `INSTALL.md` 的绝对路径,模型按它自己下载(`releases/latest`,mac/linux 资产表,~34MB,GitHub 慢就用 gh-proxy)。不需要 root、不需重启。officecli 会自更新到 latest,版本比服务器 pin 的新属正常 |
| `office` 预览 | 预览卡片走 core → executor 的 `:3100` 网关,本地没有这个网关 → 点开打不开。文档创建/编辑/读取不受影响 |
| 首个 `npm install` 要联网 | 支持 `NPM_REGISTRY` 覆盖源;`app/package-lock.json` 的 `resolved` 已改指向公共 registry(原来钉在内网镜像,外部机器必失败) |