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
+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. 回滚