From 0ec9aec93ec85d8f752a24c23569acdf72cf7ff0 Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 11 Nov 2026 19:18:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(skills):=20README=20=E4=B8=8E=E7=8E=B0?= =?UTF-8?q?=E7=8A=B6=E5=AF=B9=E9=BD=90=E2=80=94=E2=80=94=E4=B8=8D=E5=86=99?= =?UTF-8?q?=E7=89=88=E6=9C=AC=E5=8F=B7=E3=80=81AGENTS.md=20=E7=BA=A6?= =?UTF-8?q?=E5=AE=9A=E3=80=81image-process=20=E4=BE=9D=E8=B5=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/skills/README.md b/skills/README.md index b7b3a66..00c305d 100644 --- a/skills/README.md +++ b/skills/README.md @@ -25,6 +25,7 @@ skills/ ├── run.py # 技能主入口(Python 脚本,推荐)或 run.sh ├── requirements.txt # Python 依赖(可选,若需要第三方包) ├── install.sh # 系统级依赖安装脚本(可选,如 apt-get) + ├── AGENTS.md # 本机排错命令(可选;core 不读,只在技能报错信息里被指向) └── ... # 其他技能相关文件(如字体、模板等) ``` @@ -163,12 +164,13 @@ def main(): 示例 `requirements.txt`: ``` -requests==2.28.1 -beautifulsoup4==4.11.1 +requests +beautifulsoup4 ``` - 依赖安装使用 `pip install --target`,不会污染系统全局;镜像已带的包不会重复装。 -- 所有技能**共享**同一个 `deps` 目录,请注意版本冲突(后装的覆盖先装的)。建议锁定精确版本。 +- 所有技能**共享**同一个 `deps` 目录,请注意版本冲突(后装的覆盖先装的)。 +- 默认**不写版本号**:init 用 `pip install --no-index --dry-run <行>` 探测是否已满足,写死版本而镜像/外挂层里是别的版本时探测失败,会往 `deps` 再装一份,而 `PYTHONPATH` 优先于系统 site-packages,等于用旧版本遮蔽镜像包。确有兼容约束才 pin(如 `weasyprint==65.1` 与 pydyf 的编码兼容)。 - 运行期 skills 目录只读;若上线后经 UI 改了 `requirements.txt`,需重启(`docker compose up -d`)触发重新 init,否则该技能会因依赖未就绪而失败。 ### 5.2 系统级依赖 @@ -288,7 +290,7 @@ A:确保 `requirements.txt` 存在且列出了所有需要的包,并检查 ` A:检查网络连接和 pip 源是否可用,查看 Skill Manager 输出的错误日志。 **Q:多个技能依赖冲突如何解决?** -A:目前所有技能共享同一个 `deps` 目录,建议锁定精确版本,或考虑将冲突的技能拆分到不同的环境中(未来可能支持隔离)。 +A:目前所有技能共享同一个 `deps` 目录,后装的覆盖先装的。真遇到冲突才给冲突的包 pin(pin 会让离线探测失败,把该版本强行装进 `deps` 并遮蔽镜像包);能升到共同版本更好。 --- @@ -296,7 +298,7 @@ A:目前所有技能共享同一个 `deps` 目录,建议锁定精确版本 查看现有的 `x2pdf` 技能(位于 `skills/x2pdf/`)可以了解一个较为完整的实现,包括如何自带声明 Python 依赖与系统级依赖(不假设镜像预烘)、按扩展名分派渲染后端、参数化版式 CSS 等。但请根据自身技能的实际需求进行设计,不必拘泥于该示例。 -图像处理类需求可参考 `skills/image-process/`:它演示了一个纯 Python + 预装 Pillow 的实现(转换/缩放/裁剪/压缩/水印/切片/拼图,无 requirements.txt,仅靠 install.sh 保证中文字体),并明确区分“确定性图像处理”与“AI 生成/修图”的能力边界。 +图像处理类需求可参考 `skills/image-process/`:它演示了一个纯 Python + 预装 Pillow 的实现(转换/缩放/裁剪/压缩/水印/切片/拼图,Python 依赖只列 Pillow,中文字体由 install.sh 保证),并明确区分“确定性图像处理”与“AI 生成/修图”的能力边界。 ---