From c7394dc45f9fb3efb7c84977e876808d295e3313 Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 11 Nov 2026 17:01:20 +0800 Subject: [PATCH] =?UTF-8?q?chore(local):=20=E6=8F=90=E7=A4=BA=E8=AF=8D?= =?UTF-8?q?=E5=8F=AA=E6=8C=87=E8=B7=AF=EF=BC=8C=E4=B8=8D=E6=95=99=E6=A8=A1?= =?UTF-8?q?=E5=9E=8B=E6=80=8E=E4=B9=88=E8=A3=85=E5=8C=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit env-local 关于 Python 缺包那段从 7 行压到 3 行:只说「缺模块就装进 $AGENT_SKILLS_DEPS 再重试」,不提 pip/--target,也不提镜像源。 具体怎么装、走不走镜像,让模型自己判断;我们只负责给出那个 已经在 PYTHONPATH 上的路径,避免它装到别处或去动系统 Python。 docs/local-mode 4.13 与 local/README 同步措辞。 --- app/server/templates/env-local.txt | 8 ++------ docs/local-mode.md | 13 +++++++------ local/README.md | 7 +++---- 3 files changed, 12 insertions(+), 16 deletions(-) diff --git a/app/server/templates/env-local.txt b/app/server/templates/env-local.txt index 6609447..daaa2b5 100644 --- a/app/server/templates/env-local.txt +++ b/app/server/templates/env-local.txt @@ -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" ` — 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. diff --git a/docs/local-mode.md b/docs/local-mode.md index 6ae0082..a979d27 100644 --- a/docs/local-mode.md +++ b/docs/local-mode.md @@ -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. 回滚 diff --git a/local/README.md b/local/README.md index 296963a..b14919a 100644 --- a/local/README.md +++ b/local/README.md @@ -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`。中途失败留下的半成品