refactor(skills): 本机环境说明改放技能目录的 AGENTS.md,启动器不再特判任何技能

上一版把安装说明写成 INSTALL.md 并在 SKILL.md 里加段落,两处都不对:SKILL.md 是用法说明,
不该塞安装内容;启动器为 office 单独注入 PATH 也不成立,再加技能就得逐条改 start.sh。

- 删除 4 个 INSTALL.md,改为各技能目录下的 AGENTS.md(只写命令:下载/安装/验证、
  平台资产名、字体路径),SKILL.md 恢复原样
- start.sh 去掉 office 的 PATH 注入;技能要命令入口时由 AGENTS.md 指导按次前缀
  (PATH="$SK/scripts:$PATH" office ...)。启动器只保留 AGENT_SKILLS_DEPS 这个路径变量
- 找不到依赖时的指路不放在 core 里做特征匹配,而是各自报错带自己 AGENTS.md 的绝对路径
  (office 封装层 ENOENT / x2pdf 缺包或无后端 / image-process 缺字体)
- env-local 提示词加一句:技能失败就读其目录下的 AGENTS.md

实测:无 PATH 时 office 报 command not found,按 AGENTS.md 加前缀后 --version 正常;
三条缺依赖报错均给出 AGENTS.md 绝对路径。
This commit is contained in:
2026-11-11 19:12:01 +08:00
parent a52b227d8b
commit 4e1c1f36d0
19 changed files with 130 additions and 184 deletions
+16
View File
@@ -0,0 +1,16 @@
# document-photo-to-pdf:本机环境
```sh
SK="$(dirname "$AGENT_SKILLS_DEPS")/document-photo-to-pdf"
```
缺依赖时(`ModuleNotFoundError`,最先撞到的是 `numpy`):
```sh
python3 -m pip install --target "$AGENT_SKILLS_DEPS" -r "$SK/requirements.txt"
python3 -c "import numpy, PIL, fitz"
```
- `fitz` 是 `pymupdf` 的 import 名
- `pypdfium2` 不必装:只在 `pymupdf` 也缺失时才用得上
- 自检渲染优先系统 `pdftoppm`(poppler,可选)
-29
View File
@@ -1,29 +0,0 @@
# 本机安装 Python 依赖(document-photo-to-pdf 技能)
依赖由同目录 `requirements.txt` 声明(服务器 init 按它装;本机自己装)。纯 wheel,无编译、无系统库。
下文「技能目录」= `$(dirname "$AGENT_SKILLS_DEPS")/document-photo-to-pdf`。
```bash
python3 -m pip install --target "$AGENT_SKILLS_DEPS" \
-r "$(dirname "$AGENT_SKILLS_DEPS")/document-photo-to-pdf/requirements.txt"
```
## 依赖说明
| 包 | 用途 |
|---|---|
| `numpy` | 透视校正、统计与阈值计算 |
| `Pillow` | 图片读写、缩放、调色 |
| `pymupdf` | 生成 PDF(import 名是 `fitz`)与自检渲染 |
自检渲染优先用系统 `pdftoppm`(poppler,可选);没有就用 `pymupdf`;再不行才落到 `pypdfium2`。
`pypdfium2` **不必装**,只在 `pymupdf` 也缺失时才有意义。
## 验证
```bash
python3 -c "import numpy, PIL, fitz"
```
缺依赖时技能会抛 `ModuleNotFoundError`(最先撞到的是 `numpy`)。装完不需要重启 agent:
每次 `skill run` 都是新进程,`$AGENT_SKILLS_DEPS` 已在 `PYTHONPATH` 里。
-4
View File
@@ -59,7 +59,3 @@ input_schema:
- 一图一纸;同框多纸只取最大。
- 建议 ≤20 页;更多或 300dpi 可能超 120s,可分批。
- `out/` 里的原图是自然尺寸(不缩放、不调色),页与页尺寸可能不同;PDF 仍按纸张/批次统一。
## 环境
缺 Python 依赖时按同目录 `INSTALL.md` 自己装(服务器由镜像 + `requirements.txt` 提供)。
+26
View File
@@ -0,0 +1,26 @@
# image-process:本机环境
```sh
SK="$(dirname "$AGENT_SKILLS_DEPS")/image-process"
```
## Pillow
```sh
python3 -m pip install --target "$AGENT_SKILLS_DEPS" -r "$SK/requirements.txt"
python3 -c "import PIL"
```
## 中文水印缺字体
技能不内置字体,也不跨平台查找。报「中文水印缺少字体」时传 `font` 参数:
- macOS:`/System/Library/Fonts/Hiragino Sans GB.ttc`(简体)、`/System/Library/Fonts/PingFang.ttc`
- Linux:`/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc`
- Windows:`C:\Windows\Fonts\msyh.ttc`
```json
{"action":"watermark","input":"a.jpg","text":"机密","font":"/System/Library/Fonts/Hiragino Sans GB.ttc"}
```
英文/数字水印不需要字体;其余动作只依赖 Pillow。
-30
View File
@@ -1,30 +0,0 @@
# 本机安装依赖与字体(image-process 技能)
下文「技能目录」= `$(dirname "$AGENT_SKILLS_DEPS")/image-process`。
## Python 包:Pillow
```bash
python3 -m pip install --target "$AGENT_SKILLS_DEPS" \
-r "$(dirname "$AGENT_SKILLS_DEPS")/image-process/requirements.txt"
python3 -c "import PIL" # 验证
```
## 中文字体:只在 `watermark` 且文字含中文时需要
技能不内置字体,也不做跨平台查找,只认两条 Linux 路径(镜像里预装文泉驿)。
本机缺字体时报「中文水印缺少字体」,这时**传 `font` 参数**指向任意中文字体即可:
| 平台 | 常见字体路径 |
|---|---|
| macOS | `/System/Library/Fonts/Hiragino Sans GB.ttc`(简体,推荐)、`/System/Library/Fonts/PingFang.ttc` |
| Linux | `/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc` |
| Windows | `C:\Windows\Fonts\msyh.ttc` |
```json
{"action":"watermark","input":"a.jpg","text":"机密",
"font":"/System/Library/Fonts/Hiragino Sans GB.ttc"}
```
英文/数字水印不需要字体(走 Pillow 内置默认字体)。其余动作(info / convert / resize / crop /
compress / slice / grid)只依赖 Pillow。
+2 -2
View File
@@ -106,5 +106,5 @@ output_schema:
- 本技能**只做确定性图像处理**(转换/缩放/裁剪/压缩/水印/拼图),不含 AI 生成、抠图、换脸、扩图、修复等生成式/语义编辑能力。
- 若用户的需求属于"文生图 / AI 修图"等生成式范畴,不要用本技能硬凑,应说明能力边界并推荐第三方工具(豆包、即梦、可灵、Photoshop 等)。
- 任何操作都不会覆盖输入原图;输出目录不存在时自动创建。
- 中文水印需要字体:优先用 `font` 参数指定;否则依赖系统字体(镜像预装文泉驿)。
- 输入依赖 Pillow;本机缺 Pillow 或字体时按同目录 `INSTALL.md` 自己装(服务器由镜像 + `requirements.txt` 提供)。
- 中文水印需要字体:优先用 `font` 参数指定;否则依赖系统字体(镜像预装文泉驿,install.sh 会兑底安装)。
- 输入依赖预装的 Pillow,无需额外 Python 依赖;系统级字体依赖见 install.sh。
+2 -2
View File
@@ -249,8 +249,8 @@ def action_watermark(img, fmt, args):
if font_path:
font = ImageFont.truetype(font_path, font_size)
elif need_cjk:
raise ValueError('中文水印缺少字体:传 font 参数(TTF/TTC 路径);各平台常见字体路径见 %s'
% (Path(__file__).resolve().parent / 'INSTALL.md'))
raise ValueError('中文水印缺少字体:传 font 参数(TTF/TTC 路径);本机环境见 %s'
% (Path(__file__).resolve().parent / 'AGENTS.md'))
else:
try:
font = ImageFont.load_default(size=font_size)
+27
View File
@@ -0,0 +1,27 @@
# office:本机环境
服务器由镜像与 `agent-executor-init` 准备(跑同目录 `install.sh`)。本机不要跑它,按下面装,装完不需要重启。
```sh
SK="$(dirname "$AGENT_SKILLS_DEPS")/office"
```
## 缺二进制(报 `office.core binary missing`)
```sh
mkdir -p "$SK/bin"
curl -fL --progress-bar -o "$SK/bin/officecli" \
https://github.com/iOfficeAI/OfficeCLI/releases/latest/download/officecli-mac-x64
chmod +x "$SK/bin/officecli" && "$SK/bin/officecli" --version
```
资产名:mac Intel `officecli-mac-x64`、Apple Silicon `officecli-mac-arm64`、Linux `officecli-linux-x64` / `officecli-linux-arm64`。
GitHub 慢时加 `https://gh-proxy.com/` 前缀。用 `latest` 即可,不必对齐服务器的 pin。
## `office` 命令不在 PATH
本机启动器不注入 PATH。按次指定目录:
```sh
PATH="$SK/scripts:$PATH" office help
```
-46
View File
@@ -1,46 +0,0 @@
# 本机安装 officecli(office 技能)
技能三件套:本文件同目录的 `SKILL.md`(用法)、`scripts/office`(Node 封装层,已在 `PATH` 里)、
`bin/officecli`(.NET 单文件二进制,**不入库**)。
服务器上由镜像构建 / `agent-executor-init` 跑同目录的 `install.sh`(只处理 linux-x64)。
**本机不要跑 `install.sh`**,按下面自己下:先装才用,不需要重启 agent(封装层每次执行时才解析二进制路径)。
下文「技能目录」= `$(dirname "$AGENT_SKILLS_DEPS")/office`(本地形态 `AGENT_SKILLS_DEPS` 指向 `<仓库>/skills/deps`)。
## 1. 下载对应平台的资产
| 平台 | 资产名 |
|---|---|
| macOS Apple Silicon | `officecli-mac-arm64` |
| macOS Intel | `officecli-mac-x64` |
| Linux x64 | `officecli-linux-x64` |
| Linux arm64 | `officecli-linux-arm64` |
```bash
mkdir -p "$(dirname "$AGENT_SKILLS_DEPS")/office/bin"
curl -fL --progress-bar \
-o "$(dirname "$AGENT_SKILLS_DEPS")/office/bin/officecli" \
https://github.com/iOfficeAI/OfficeCLI/releases/latest/download/officecli-mac-x64
```
- 用 `latest` 就够(officecli 首次运行也会把自己更新到 latest),不用对齐服务器 pin 的版本。
- 国内慢就换源:`https://gh-proxy.com/https://github.com/iOfficeAI/OfficeCLI/releases/latest/download/<资产>`。
- 约 34MB,超时/断流就重试;`curl -fL` 失败时不会留下半截文件可用。
## 2. 赋可执行位并验证
```bash
chmod +x "$(dirname "$AGENT_SKILLS_DEPS")/office/bin/officecli"
office --version # 或 office help
```
`office` 命令由本地启动器注入 `PATH` 提供(`skills/office/scripts` 目录),不需要建软链、不需要 root。
如果 `office` 不在 PATH(例如手工起 core 没带启动器),可以直接跑
`node "$(dirname "$AGENT_SKILLS_DEPS")/office/scripts/office" help`。
## 3. 装不上怎么办
封装层会报 `office.core binary missing: <路径>`,说明二进制没到位;文档的创建/编辑/读取全部依赖它,
没有它就用别的路子(例如要 PDF 用 `x2pdf` 技能)。**不要**为此改系统目录或去装 .NET 运行时——
该二进制是自包含的。
-1
View File
@@ -34,5 +34,4 @@ create/open 成功后,用户可自行查看该文档的实时预览(预览
## 注意
- 所有操作文档在任务目录里。
- 缺 `bin/officecli`(报 `binary missing`)时:按同目录 `INSTALL.md` 自己装;服务器端由镜像构建 / `agent-executor-init` 提供,本机不要跑 `install.sh`。
- `view` 的渲染族(html/screenshot/pdf 等)本环境不可用;要 PDF 用 x2pdf 技能。
+1 -1
View File
@@ -92,7 +92,7 @@ try {
}
if (r.error) {
if (r.error.code === 'ENOENT') {
err('office.core binary missing: ' + BIN + '\nLocal install steps: ' + path.resolve(__dirname, '..', 'INSTALL.md')
err('office.core binary missing: ' + BIN + '\nLocal env: ' + path.resolve(__dirname, '..', 'AGENTS.md')
+ ' (server: docker compose up -d agent-executor-init)');
}
err(String(r.error.message || r.error));
+30
View File
@@ -0,0 +1,30 @@
# x2pdf:本机环境
```sh
SK="$(dirname "$AGENT_SKILLS_DEPS")/x2pdf"
```
## 文本类 md / txt / html
```sh
python3 -m pip install --target "$AGENT_SKILLS_DEPS" -r "$SK/requirements.txt"
brew install pango # macOS;Linux 的系统库见 install.sh
```
不装 pango 也能用:技能在 WeasyPrint 不可用时回落 LibreOffice,代价是 `page` 的边距/页码与部分 CSS 不生效。
## Office 类 docx / xlsx / pptx / odt / ods / odp
必须有 LibreOffice(文本类也可用它渲染):
```sh
brew install --cask libreoffice # macOS:soffice 在 app bundle 内,技能会自己找到
apt-get install libreoffice-writer libreoffice-calc libreoffice-impress # Linux(镜像已预装)
```
## 验证
```sh
python3 -c "import weasyprint, markdown"
/Applications/LibreOffice.app/Contents/MacOS/soffice --version
```
-33
View File
@@ -1,33 +0,0 @@
# 本机安装渲染后端(x2pdf 技能)
两条渲染路径,依赖各不相同。`requirements.txt` 列的是 Python 包(服务器 init 也按它装)。
下文「技能目录」= `$(dirname "$AGENT_SKILLS_DEPS")/x2pdf`。
## 文本类(md / txt / html):默认 WeasyPrint
```bash
python3 -m pip install --target "$AGENT_SKILLS_DEPS" -r "$(dirname "$AGENT_SKILLS_DEPS")/x2pdf/requirements.txt"
```
WeasyPrint 除了 Python 包,还要系统库 pango/cairo:
- macOS:`brew install pango`
- Linux:见同目录 `install.sh`(apt 装 那串 `libpango*` / `libcairo2` / 字体)
**不想装 pango 也行**:装 LibreOffice(见下),技能在 WeasyPrint 不可用时(缺包或缺 pango 符号)
会自动回落到 LibreOffice 渲染文本。代价是 `page` 的边距/页码与大部分 CSS 不生效——够看,不够精确。
## Office 类(docx / xlsx / pptx / odt / ods / odp):必须 LibreOffice
- macOS:`brew install --cask libreoffice`
装完**不需要**把 `soffice` 加进 `PATH`,技能会自己找 `/Applications/LibreOffice.app/Contents/MacOS/soffice`。
- Linux:`apt-get install libreoffice-writer libreoffice-calc libreoffice-impress`(服务器镜像已预装)。
## 验证
```bash
python3 -c "import weasyprint, markdown" # 文本类(走 WeasyPrint)
/Applications/LibreOffice.app/Contents/MacOS/soffice --version # LibreOffice
```
两者都没有时,技能会报「这台机器没有可用的 PDF 渲染后端」。装完不需要重启 agent。
-5
View File
@@ -90,8 +90,3 @@ output_schema:
```json
{"input": "layout.html", "css": "print-override.css"}
```
## 环境
缺渲染后端时按同目录 `INSTALL.md` 自己装(文本类 WeasyPrint/或 LibreOffice;Office 类必须 LibreOffice)。
服务器由镜像 + `requirements.txt` / `install.sh` 提供,本机不要跑 `install.sh`。
+1 -1
View File
@@ -51,7 +51,7 @@ def find_soffice():
def req_hint():
return '安装步骤: %s(依赖清单 requirements.txt)' % (SKILL_DIR / 'INSTALL.md')
return '本机环境: %s' % (SKILL_DIR / 'AGENTS.md')
# 默认样式:黑白友好、打印向。字号用 em 相对值,整体缩放只依赖 html font-size
# (由 page.font_size 参数注入),因此压单页只需调小字号/边距。