diff --git a/app/server/templates/env-local.txt b/app/server/templates/env-local.txt index b0b2edc..6609447 100644 --- a/app/server/templates/env-local.txt +++ b/app/server/templates/env-local.txt @@ -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" ` — that + dir is already on `PYTHONPATH`, and `--target` also works on externally-managed + Pythons (e.g. Homebrew) where a bare `pip install` is refused. diff --git a/docs/local-mode.md b/docs/local-mode.md index d05093e..6ae0082 100644 --- a/docs/local-mode.md +++ b/docs/local-mode.md @@ -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. 回滚 diff --git a/local/README.md b/local/README.md index e31d849..296963a 100644 --- a/local/README.md +++ b/local/README.md @@ -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`。中途失败留下的半成品 diff --git a/local/start.sh b/local/start.sh index 97db55f..260f4ac 100755 --- a/local/start.sh +++ b/local/start.sh @@ -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=$! } diff --git a/skills/document-photo-to-pdf/requirements.txt b/skills/document-photo-to-pdf/requirements.txt new file mode 100644 index 0000000..7dbd6ce --- /dev/null +++ b/skills/document-photo-to-pdf/requirements.txt @@ -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 diff --git a/skills/image-process/requirements.txt b/skills/image-process/requirements.txt new file mode 100644 index 0000000..e2630dc --- /dev/null +++ b/skills/image-process/requirements.txt @@ -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