feat(local): 声明技能 Python 依赖,并放开「缺包自装进 skills/deps」

本地没有 agent-executor-init,技能的 requirements.txt 从来没人读:
document-photo-to-pdf(numpy/Pillow/pymupdf)与 image-process(Pillow)
在本机只是碰巧用户的 python 里已经装了。

- 两个技能补 requirements.txt,一律不写版本号:服务端 init 用
  pip install --no-index --dry-run 探测,pin 到与镜像不同的版本会让探测失败,
  反而往 skills/deps 装一份旧的(PYTHONPATH 优先级高于系统 site-packages)
- start.sh 起 core 时注入 AGENT_SKILLS_DEPS(该目录本来就在 PYTHONPATH 里),
  把路径交给模型;terminal 与技能子进程都继承 core 的 env,装完下次运行即生效
- env-local.txt 把「永远不要自己装任何东西」换成「缺包时 --target 装进共享依赖层,
  别动系统 Python」。用 --target 是因为 pip 对它的 PEP 668 拦截明确豁免,
  Homebrew 那种 externally-managed 解释器也能装
- 文档同步:local/README 已知限制、docs/local-mode.md 新增 4.13 记录取舍

服务端不受影响:这三行在 executor 镜像里都已满足(实测 --no-index --dry-run
均 exit 0),init 只写一个 gitignore 里的 .deps_installed 就跳过。
This commit is contained in:
2026-11-11 16:59:28 +08:00
parent 29e4f6e6ea
commit 8764fedabc
6 changed files with 59 additions and 4 deletions
+6 -1
View File
@@ -3,4 +3,9 @@
and `/tmp` is the system temp directory (shared, never cleaned for you). Work
inside the working directory; treat everything outside it as the user's.
- `python3` may be missing; when the skills list below is empty it is not
available. Never install runtimes or system packages yourself.
available. Never install runtimes, system packages, or modify the user's Python
environment. If a skill fails because a Python package is missing
(`ModuleNotFoundError`), install just that package into the shared deps dir and
retry: `python3 -m pip install --target "$AGENT_SKILLS_DEPS" <package>` — that
dir is already on `PYTHONPATH`, and `--target` also works on externally-managed
Pythons (e.g. Homebrew) where a bare `pip install` is refused.
+23 -1
View File
@@ -243,6 +243,28 @@ health 只作为「端口上有服务但不是本启动器拉起的」兜底提
- 看门狗只用 `SIGKILL`:先 `TERM` 会先干掉外壳让 npm 变成孤儿(`PPID=1`),`kill -0` 判不到,
再想硬杀就找不到它了。
### 4.13 Python 包:不预装,交给模型按提示词装进 `skills/deps`
服务器上技能依赖由 `agent-executor-init` 一次性装进 `skills/deps`(compose 再把它放进
`PYTHONPATH`)。本地没有这套东西,`start.sh` 也不去跑 pip——安装时机、镜像源、半成品清理
是另一整套逻辑,收益不抵成本。做法改成「缺了再装」:
- `start.sh` 起 core 时注入 `PYTHONPATH=<仓库>/skills/deps`(**原本就有**)与
`AGENT_SKILLS_DEPS=<仓库>/skills/deps`(新增,只为把路径交给模型)。
`terminal` 与技能子进程都继承 core 的 env,所以装进去的东西**下次运行就能 import**,不用重启。
- `templates/env-local.txt` 把原来的「永远不要自己装任何东西」换成「缺包时按
`pip install --target "$AGENT_SKILLS_DEPS" <包>` 装进这个目录,别动系统 Python」。
技能失败时 stdout+stderr 是合并回给模型的,它能看到 `ModuleNotFoundError` 自己判断。
- 用 `--target` 而不是 `--user`:pip 的 PEP 668 拦截对 `--target`/`--prefix`/`--root` 明确豁免
(`pip/_internal/commands/install.py`),Homebrew 那种 externally-managed 解释器也不会报
`externally-managed-environment`;而且不污染用户的 Python,删目录即撤销。
- 技能自己的 `requirements.txt` 一律**不写版本号**:服务端 init 用
`pip install --no-index --dry-run` 探测,pin 到与镜像不同的版本会让探测失败 → 真的往
`skills/deps` 装一份旧的,而 `PYTHONPATH` 优先于系统 site-packages,等于反向遮蔽镜像包。
需要系统库的包(`weasyprint` → pango/cairo)pip 装不了,仍需用户 `brew install`;这类不在
自动修复范围内,模型只报结论。
## 5. 验证结果(macOS 12.7.6 / x86_64 / Node 22.21 / python3 3.10 / 本机无 ffmpeg)
静态检查:`sh -n local/start.sh`、`sh -n local/stop.sh`、`node --check` 均通过。
@@ -313,7 +335,7 @@ tail -f local/.runtime/core.log # 以及 npm-install.log / mcp-*.log
| `mcp_asr` 监听 `0.0.0.0` | 它只认 `PORT` 环境变量、`listen` 不带 host(已启动时才是问题)。不存密钥(上游参数随请求带入),暴露面有限;要收紧需给 `mcp/asr` 加 `--host` 支持 |
| Windows 不支持 | `spawn('/bin/sh')`、`process.kill(-pid)`、模型写的 bash 语法都是 POSIX 语义 |
| `mint_public_link` 不可用 | 本地 `public_link.base_url` 为空,工具会回明确的「未配置」错误 |
| 技能依赖 | 有 `requirements.txt` 的技能需手工装进 `skills/deps`(服务器上由 `agent-executor-init` 在构建期做)。默认只保证纯标准库技能 |
| 技能依赖 | 本地不预装:缺包时模型按提示词把包 `pip install --target "$AGENT_SKILLS_DEPS"` 装进 `skills/deps`(已在该进程 `PYTHONPATH`)。需要系统库的包(`weasyprint`→pango/cairo)pip 装不了,仍需手工 `brew install`。服务器上由 `agent-executor-init` 处理 |
| 首个 `npm install` 要联网 | 支持 `NPM_REGISTRY` 覆盖源;`app/package-lock.json` 的 `resolved` 已改指向公共 registry(原来钉在内网镜像,外部机器必失败) |
## 8. 回滚
+5 -2
View File
@@ -138,8 +138,11 @@ git pull
- **Windows 暂不支持**:本机执行走 `spawn('/bin/sh')` 与 `process.kill(-pid)`,都是 POSIX 语义。
- **`mint_public_link` 不可用**:`public_link.base_url` 未配置(本地生成的链接只有本机能打开),
模型调用该工具会得到明确的「未配置」错误。
- **技能依赖**:有 `requirements.txt` 的技能需要自己把包装进 `skills/deps`
(服务器上这一步由 `agent-executor-init` 在构建期完成)。默认只保证纯标准库技能可用。
- **技能依赖不预装**:本地没有 `agent-executor-init`,`skills/*/requirements.txt` 不会在启动时
自动安装。技能缺包时会报 `ModuleNotFoundError`,模型会把缺的包 `pip install --target`
进 `skills/deps`(`AGENT_SKILLS_DEPS` 指向它,且已在该进程的 `PYTHONPATH` 里,装完下次
运行即生效)。需要系统库的包(如 `weasyprint` 依赖 pango/cairo)pip 装不了,得自己
`brew install`。
- **首个 `npm install` 要联网**:启动器会自动选源、换源重试、并把装好的依赖缓存到
`~/.cache/agent-local/`;之后重启 / 换 clone 都是本地解压,不需要网络。真要手动指定源:
`NPM_REGISTRY=https://registry.npmmirror.com ./local/start.sh`。中途失败留下的半成品
+5
View File
@@ -813,6 +813,10 @@ check_mcp() {
}
start_core() {
# PYTHONPATH 把技能共享依赖层 skills/deps 放进 python 的搜索路径(与服务器上 executor 容器
# 的 PYTHONPATH 对齐,那边由 compose 注入)。本地没有 agent-executor-init 替我们装包,
# 所以另外把目录路径作为 AGENT_SKILLS_DEPS 传下去:模型在 terminal 里发现技能缺包时,
# 按提示词里的写法 pip install --target "$AGENT_SKILLS_DEPS" 即可,技能下次运行就能 import。
( cd "$ROOT/app" && exec env \
PORT="$PORT" \
HOST="$HOST_ADDR" \
@@ -821,6 +825,7 @@ start_core() {
AGENT_LOCAL_PICK=1 \
ASR_URL="$ASR_URL" \
PYTHONPATH="$ROOT/skills/deps" \
AGENT_SKILLS_DEPS="$ROOT/skills/deps" \
node server/server.js >>"$LOG" 2>&1 ) &
CORE_PID=$!
}
@@ -0,0 +1,13 @@
# 这份文件主要给「本地端」(local/)用:本机 python 缺包时,启动器或模型自己可以按它补装。
#
# 刻意不写版本号:服务端 agent-executor-init 的判定是
# python3 -m pip install --no-index --dry-run <本行>
# 退出码 0 即视为已满足、直接跳过装包(executor 镜像已烘了 numpy/Pillow/pymupdf)。
# 一旦写了 pin 而镜像里是别的版本,探测就会失败 → 真的往 skills/deps 装一份老版本,
# 而 PYTHONPATH 优先于系统 site-packages,等于用外挂层遮蔽镜像版,会牵连其它技能。
#
# pypdfium2 是 check.py 里 fitz 缺失时的兜底渲染器,不是必需,故不声明。
numpy
Pillow
pymupdf
+7
View File
@@ -0,0 +1,7 @@
# 本技能只用 Pillow(Image/ImageDraw/ImageFont/ImageOps)。
#
# 这份文件主要给「本地端」(local/)用:本机 python 缺包时按它补装。
# 不写版本号的原因见 skills/document-photo-to-pdf/requirements.txt 顶部的说明:
# 服务端 init 用 `pip install --no-index --dry-run` 探测,pin 到与镜像不同的版本会反向遮蔽镜像包。
Pillow