From 25f9e157ad46d31d15c31ab80fe31ad71fe06461 Mon Sep 17 00:00:00 2001 From: kicer Date: Thu, 12 Nov 2026 10:05:46 +0800 Subject: [PATCH] =?UTF-8?q?docs(skills):=20=E6=8E=92=E9=94=99=E6=B8=85?= =?UTF-8?q?=E5=8D=95=E7=BB=9F=E4=B8=80=E6=88=90=E3=80=8C=E6=8A=A5=E9=94=99?= =?UTF-8?q?=20=E2=86=92=20=E6=80=8E=E4=B9=88=E5=8A=9E=20=E2=86=92=20?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=E3=80=8D=EF=BC=8Coffice=20=E6=94=B9=E4=B8=BA?= =?UTF-8?q?=E5=BB=BA=E8=BD=AF=E9=93=BE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 技能目录的 AGENTS.md 只在报错时被读,所以只写「报错原文 → 怎么办 → 命令」,一节一个 现象,不写背景。命令块前统一声明「仅为示例,具体以本机平台实际情况为准」——路径分隔符、 可执行名、包管理器交给模型按本机情况自愈,不逐平台列出。 office:`command not found` 从按次拼 PATH 前缀改成建一次 $HOME/.local/bin/office 软链。 每条 terminal 命令都是新 shell,前缀不跨命令生效,按次拼的写法容易被反复踩。 image-process:PIL 缺包与「中文水印缺字体」拆成两节。 x2pdf:后端代价表压成三条列表,四个现象(ModuleNotFoundError / 没有可用排版能力 / could not import some external libraries / 排版降级)各自成节。 document-photo-to-pdf:单节化,保留 fitz 是 pymupdf 的 import 名这条坑。 data-page 只用标准库,不需要 AGENTS.md。 --- skills/document-photo-to-pdf/AGENTS.md | 8 +++++-- skills/image-process/AGENTS.md | 10 ++++++-- skills/office/AGENTS.md | 13 ++++++++--- skills/x2pdf/AGENTS.md | 32 +++++++++++++++----------- 4 files changed, 43 insertions(+), 20 deletions(-) diff --git a/skills/document-photo-to-pdf/AGENTS.md b/skills/document-photo-to-pdf/AGENTS.md index c5e9459..6fcb0e7 100644 --- a/skills/document-photo-to-pdf/AGENTS.md +++ b/skills/document-photo-to-pdf/AGENTS.md @@ -1,9 +1,13 @@ # document-photo-to-pdf -`ModuleNotFoundError`(`numpy` / `PIL` / `fitz`):把依赖装进 `$AGENT_SKILLS_DEPS` +以下命令仅为示例,具体以本机平台实际情况为准。 + +## ModuleNotFoundError: numpy / PIL / fitz + +把依赖装进 `$AGENT_SKILLS_DEPS`。 ```sh python3 -m pip install --upgrade --target "$AGENT_SKILLS_DEPS" -r "$(dirname "$AGENT_SKILLS_DEPS")/document-photo-to-pdf/requirements.txt" ``` -`fitz` 是 `pymupdf` 的 import 名,`pypdfium2` 不用装。没有 `python3` 先装运行时(Windows 上解释器常是 `python` / `py`)。 +`fitz` 是 `pymupdf` 的 import 名,`pypdfium2` 不用装;没有 `python3` 先装运行时(Windows 常是 `python` / `py`)。 diff --git a/skills/image-process/AGENTS.md b/skills/image-process/AGENTS.md index a1151c7..dd440d3 100644 --- a/skills/image-process/AGENTS.md +++ b/skills/image-process/AGENTS.md @@ -1,12 +1,18 @@ # image-process -`ModuleNotFoundError: No module named 'PIL'`:把依赖装进 `$AGENT_SKILLS_DEPS` +以下命令仅为示例,具体以本机平台实际情况为准。 + +## ModuleNotFoundError: No module named 'PIL' + +把依赖装进 `$AGENT_SKILLS_DEPS`。 ```sh python3 -m pip install --upgrade --target "$AGENT_SKILLS_DEPS" -r "$(dirname "$AGENT_SKILLS_DEPS")/image-process/requirements.txt" ``` -`中文水印缺少字体`:传 `font` 参数,指向本机任意中文字体文件(ttf/ttc) +## 中文水印缺少字体 + +传 `font` 参数,指向本机任意中文字体文件(ttf/ttc)。 ```json {"action":"watermark","input":"a.jpg","text":"机密","font":"<本机中文字体路径>"} diff --git a/skills/office/AGENTS.md b/skills/office/AGENTS.md index 55ae2ac..5ca7225 100644 --- a/skills/office/AGENTS.md +++ b/skills/office/AGENTS.md @@ -1,12 +1,19 @@ # office -`office: command not found`:用技能自带入口 +以下命令仅为示例,具体以本机平台实际情况为准(自行判断路径、可执行名、分隔符)。 + +## office: command not found + +入口不在 PATH:建一次软链,之后一直能用。 ```sh -PATH="$(dirname "$AGENT_SKILLS_DEPS")/office/scripts:$PATH" office help +mkdir -p "$HOME/.local/bin" +ln -sfn "$(dirname "$AGENT_SKILLS_DEPS")/office/scripts/office" "$HOME/.local/bin/office" ``` -`office.core binary missing`:按本机平台下载对应资产到 `bin/officecli`(Windows 存成 `bin/officecli.exe`),再 `chmod +x` +## office.core binary missing + +按本机平台下载对应资产到 `bin/officecli`(Windows 存成 `bin/officecli.exe`),再 `chmod +x`。 ```sh SK="$(dirname "$AGENT_SKILLS_DEPS")/office" diff --git a/skills/x2pdf/AGENTS.md b/skills/x2pdf/AGENTS.md index 68f89ce..b659d5a 100644 --- a/skills/x2pdf/AGENTS.md +++ b/skills/x2pdf/AGENTS.md @@ -1,29 +1,35 @@ # x2pdf -`ModuleNotFoundError`(`markdown`):把依赖装进 `$AGENT_SKILLS_DEPS` +以下命令仅为示例,具体以本机平台实际情况为准。 + +## ModuleNotFoundError: markdown + +把依赖装进 `$AGENT_SKILLS_DEPS`。 ```sh python3 -m pip install --upgrade --target "$AGENT_SKILLS_DEPS" -r "$(dirname "$AGENT_SKILLS_DEPS")/x2pdf/requirements.txt" ``` -## 后端缺哪个,代价多大 +## 没有可用的 PDF 排版能力 -| 后端 | 缺了的影响 | 怎么补 | -|---|---|---| -| LibreOffice | **Office 类(docx/xlsx/pptx)完全不能转**,必装 | Linux `apt install libreoffice`;macOS `brew install --cask libreoffice`;Windows `winget install TheDocumentFoundation.LibreOffice` | -| 浏览器 | 文本类落到 LibreOffice,CSS 基本失效 | 通常不用装:已有 Chrome / Chromium / Edge 就自动用 | -| WeasyPrint | 文本类没有页码、`@page` 精确排版失效 | 先装 Python 包(见上),再补系统库 pango/cairo:Linux `apt install libpango-1.0-0 libpangocairo-1.0-0 libcairo2`;macOS `brew install pango`;Windows 补 GTK 运行库,装不上就跳过 | +文本类有三个后端可退,从便宜到贵补,别一次全装: -报「没有可用的 PDF 排版能力」时:文本类有三个后端可退,按上表从便宜到贵补,别一次全装。 -输出带着「排版降级」(无页码/边距偏差)不是失败,是后端不全,按需补。 -系统级安装(几百 MB,老系统上可能源码编译十几分钟)先跟用户说清代价,由他决定装还是接受降级。 +- 浏览器:有 Chrome / Chromium / Edge 就自动用,通常不用装 +- LibreOffice:Office 类(docx/xlsx/pptx)必装——Linux `apt install libreoffice`;macOS `brew install --cask libreoffice`;Windows `winget install TheDocumentFoundation.LibreOffice` +- WeasyPrint:先装上面的 Python 包,再补系统库 pango/cairo(见下节) -## 装完必须验证 +系统级安装几百 MB,先跟用户说清代价,由他决定装还是接受降级。 -`pip install` 成功不代表能用,缺系统库时 import 就炸: +## could not import some external libraries + +系统库没到位,不是 Python 包的问题:Linux `apt install libpango-1.0-0 libpangocairo-1.0-0 libcairo2`;macOS `brew install pango`;Windows 补 GTK 运行库,装不上就跳过。 + +装完验证: ```sh python3 -c "import weasyprint; print(weasyprint.__version__)" ``` -报 `could not import some external libraries` = 系统库(pango/cairo)还没到位,不是 Python 包的问题。 +## 输出带「排版降级」 + +无页码或边距偏差不是失败,是后端不全,按需补。