chore(local): 提示词只指路,不教模型怎么装包

env-local 关于 Python 缺包那段从 7 行压到 3 行:只说「缺模块就装进
$AGENT_SKILLS_DEPS 再重试」,不提 pip/--target,也不提镜像源。
具体怎么装、走不走镜像,让模型自己判断;我们只负责给出那个
已经在 PYTHONPATH 上的路径,避免它装到别处或去动系统 Python。

docs/local-mode 4.13 与 local/README 同步措辞。
This commit is contained in:
2026-11-11 17:01:20 +08:00
parent 8764fedabc
commit c7394dc45f
3 changed files with 12 additions and 16 deletions
+2 -6
View File
@@ -3,9 +3,5 @@
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, 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.
available. Never install runtimes or system packages. If a skill lacks a Python
module, install it into `$AGENT_SKILLS_DEPS` and retry.
+7 -6
View File
@@ -252,12 +252,13 @@ health 只作为「端口上有服务但不是本启动器拉起的」兜底提
- `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」。
- `templates/env-local.txt` 把原来的「永远不要自己装任何东西」改成「缺模块就装进
`$AGENT_SKILLS_DEPS` 再重试」——**只给路径,不给命令**,怎么装由模型自己决定。
技能失败时 stdout+stderr 是合并回给模型的,它能看到 `ModuleNotFoundError` 自己判断。
- 用 `--target` 而不是 `--user`:pip 的 PEP 668 拦截对 `--target`/`--prefix`/`--root` 明确豁免
(`pip/_internal/commands/install.py`),Homebrew 那种 externally-managed 解释器也不会报
`externally-managed-environment`;而且不污染用户的 Python,删目录即撤销。
- 为什么给一个目录而不是让模型自己选:那个目录已经在 `PYTHONPATH` 里,装进去下次运行就能
import;而不指定位置的话,它很可能装到别处(或去改系统 Python)。pip 对 `--target` 的
PEP 668 拦截明确豁免(`pip/_internal/commands/install.py`),所以这条路在 Homebrew 那种
externally-managed 解释器上也走得通——但这话不写进提示词,交给模型自己判断。
- 技能自己的 `requirements.txt` 一律**不写版本号**:服务端 init 用
`pip install --no-index --dry-run` 探测,pin 到与镜像不同的版本会让探测失败 → 真的往
`skills/deps` 装一份旧的,而 `PYTHONPATH` 优先于系统 site-packages,等于反向遮蔽镜像包。
@@ -335,7 +336,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` 为空,工具会回明确的「未配置」错误 |
| 技能依赖 | 本地不预装:缺包时模型按提示词把包 `pip install --target "$AGENT_SKILLS_DEPS"` 装进 `skills/deps`(已在该进程 `PYTHONPATH`)。需要系统库的包(`weasyprint`→pango/cairo)pip 装不了,仍需手工 `brew install`。服务器上由 `agent-executor-init` 处理 |
| 技能依赖 | 本地不预装:缺包时模型会把包装进 `skills/deps`(`$AGENT_SKILLS_DEPS`,已在该进程 `PYTHONPATH` 里,装完下次运行即生效)。怎么装由模型自己决定。需要系统库的包(`weasyprint`→pango/cairo)pip 装不了,仍需手工 `brew install`。服务器上由 `agent-executor-init` 处理 |
| 首个 `npm install` 要联网 | 支持 `NPM_REGISTRY` 覆盖源;`app/package-lock.json` 的 `resolved` 已改指向公共 registry(原来钉在内网镜像,外部机器必失败) |
## 8. 回滚
+3 -4
View File
@@ -139,10 +139,9 @@ git pull
- **`mint_public_link` 不可用**:`public_link.base_url` 未配置(本地生成的链接只有本机能打开),
模型调用该工具会得到明确的「未配置」错误。
- **技能依赖不预装**:本地没有 `agent-executor-init`,`skills/*/requirements.txt` 不会在启动时
自动安装。技能缺包时会报 `ModuleNotFoundError`,模型会把缺的包 `pip install --target`
进 `skills/deps`(`AGENT_SKILLS_DEPS` 指向它,且已在该进程的 `PYTHONPATH` 里,装完下次
运行即生效)。需要系统库的包(如 `weasyprint` 依赖 pango/cairo)pip 装不了,得自己
`brew install`。
自动安装。技能缺包时会报 `ModuleNotFoundError`,模型会把缺的包装进 `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`。中途失败留下的半成品