From a7eecdbe977a4bd3ee9068aa2f63a01cd4dea812 Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 11 Nov 2026 17:07:20 +0800 Subject: [PATCH] =?UTF-8?q?feat(local):=20=E6=8A=80=E8=83=BD=E4=B8=8D?= =?UTF-8?q?=E5=86=8D=E5=9B=A0=E7=BC=BA=20python3=20=E6=95=B4=E4=BD=93?= =?UTF-8?q?=E9=9A=90=E8=97=8F=EF=BC=9B=E7=BC=BA=E8=A7=A3=E9=87=8A=E5=99=A8?= =?UTF-8?q?=E6=97=B6=E5=85=88=E9=97=AE=E7=94=A8=E6=88=B7=E5=86=8D=E8=A3=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A1:link_skills 恒指向仓库 skills。原来没有 python3 就把 skills_root 指到空目录, 把所有技能一起藏掉——但技能不一定是 Python 的(office 是 SKILL.md + terminal 里调 officecli,跟 python3 无关),一刀切会误伤。而 run.py 类技能缺解释器时 skills.js 的 runEntry 对 spawn error 有处理,模型拿到「技能入口启动失败:spawn python3 ENOENT」, 干净可读,不需要靠藏清单避险。状态页/终端文案同步改成「python3 未安装:Python 技能 会失败,非 Python 技能不受影响」。 B2:env-local 允许模型装运行时,但必须先问用户;仍禁止 sudo 与装系统包。 macOS 的 /usr/bin/python3 是 CLT 桩,真装要走 brew 或官方安装器,耗时长且可能改 PATH / 要管理员权限,这种改动不能默许自主执行。 文档同步:docs/local-mode 4.4 重写(记录为什么不再切换)、4.13 补 B2 理由、 验证表该行标为待复测;local/README 的可选能力表与已知限制同步。 --- app/server/templates/env-local.txt | 6 +++--- docs/local-mode.md | 30 +++++++++++++++++++++--------- local/README.md | 8 +++++--- local/start.sh | 19 ++++++++++++------- 4 files changed, 41 insertions(+), 22 deletions(-) diff --git a/app/server/templates/env-local.txt b/app/server/templates/env-local.txt index daaa2b5..8be7e1c 100644 --- a/app/server/templates/env-local.txt +++ b/app/server/templates/env-local.txt @@ -2,6 +2,6 @@ real shell with their permissions, other conversations share the same machine, 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. If a skill lacks a Python - module, install it into `$AGENT_SKILLS_DEPS` and retry. +- `python3` may be missing. Never run `sudo` or install system packages. When a + skill lacks a Python module, install it into `$AGENT_SKILLS_DEPS` and retry; + when `python3` itself is missing, ask the user before installing a runtime. diff --git a/docs/local-mode.md b/docs/local-mode.md index a979d27..3503e1c 100644 --- a/docs/local-mode.md +++ b/docs/local-mode.md @@ -14,7 +14,7 @@ - **和服务器端同一份代码**,不 fork 新仓库、不长期开 branch;靠运行时开关分叉 - **`app/` 最小化改动**(最终只有 2 个后端文件,前端 0 改动) -- **组件按需**:node 必需;ffmpeg 决定语音;python3 决定技能 +- **组件按需**:node 必需;ffmpeg 决定语音;python3 决定 Python 类技能能否执行(非 Python 技能如 `office` 不受影响) - **Windows 暂时不做**(本机执行依赖 POSIX 语义,见第 7 节) - 不用 Docker(用户明确否决) @@ -117,15 +117,23 @@ 装完 ffmpeg 后**重跑脚本**即生效,配置文件一个字不用改。 -### 4.4 python3 用软链切换,与配置解耦 +### 4.4 技能目录用软链固定指向仓库,不再按 python3 有无切换 -`skills.js` 对技能根目录不存在的行为是「warn + 返回空列表」,不报错不阻塞。于是配置里永远写 -`skills_root: <仓库>/local/.runtime/skills`,启动器每次都重建这个软链: +配置里永远写 `skills_root: <仓库>/local/.runtime/skills`(首次生成后不覆盖),启动器每次都重建这个 +软链,恒指向 `<仓库>/skills`。 -- 有可用 python3 → 指向 `<仓库>/skills` -- 没有 → 指向 `.runtime/empty-skills`(空目录) +早期版本在「没有 python3」时把它指向一个空目录,想的是“别让模型看到跑不了的工具”。两个问题: -装完 python3 重跑脚本即生效。**没有改 `skills.js` 一行代码。** +1. **技能不一定是 Python 的**。`office` 只有 `SKILL.md` + `scripts/office`,模型在 `terminal` 里调 + `office `,完全不需要 python3——一刀切会把这类技能一并藏掉。 +2. **没必要防**。`skills.js` 的 `runEntry` 对 `spawn` 的 `error` 有处理,缺解释器时模型拿到的是 + 「技能入口启动失败:spawn python3 ENOENT」,干净可读、不崩不挂。模型能据此自己决定:装模块、 + 问你装运行时,或者放弃。 + +所以现在只有一种行为:技能总是可见;python3 缺失只影响 `run.py` 类技能能否执行。装好 python3 后 +(若在 core 启动时 `PATH` 已有的目录里,如 brew 的 `/opt/homebrew/bin`)无需重启即生效,否则重跑脚本。 + +**没有改 `skills.js` 一行代码。** ### 4.5 启动器必须是守护进程 @@ -259,6 +267,10 @@ health 只作为「端口上有服务但不是本启动器拉起的」兜底提 import;而不指定位置的话,它很可能装到别处(或去改系统 Python)。pip 对 `--target` 的 PEP 668 拦截明确豁免(`pip/_internal/commands/install.py`),所以这条路在 Homebrew 那种 externally-managed 解释器上也走得通——但这话不写进提示词,交给模型自己判断。 +- 缺 `python3` 本体时:提示词允许模型装运行时,但**必须先问用户**(`ask the user before + installing a runtime`)。理由:macOS 的 `/usr/bin/python3` 是 Xcode CLT 的桩,真装要走 brew + 或官方安装器,耗时长且可能改 `PATH`/要管理员权限——这种级别的改动不能默许模型自主做。 + 同时仍然禁止 `sudo` 与装系统包。 - 技能自己的 `requirements.txt` 一律**不写版本号**:服务端 init 用 `pip install --no-index --dry-run` 探测,pin 到与镜像不同的版本会让探测失败 → 真的往 `skills/deps` 装一份旧的,而 `PYTHONPATH` 优先于系统 site-packages,等于反向遮蔽镜像包。 @@ -280,7 +292,7 @@ health 只作为「端口上有服务但不是本启动器拉起的」兜底提 | 越界保护:`read_file ~/.ssh/config`、`terminal cd /etc` 均报「路径越界」 | 通过 | | `/tmp` 一致性:`write_file /tmp/x` → `terminal cat /tmp/x` 与 `read_file /tmp/x` 内容一致 | 通过 | | 无 ffmpeg:`/api/asr/status` = `enabled:false`(麦克风隐藏),asr 子进程不启动,8094 不监听 | 通过 | -| 有 python3:技能列表有内容;桩掉 python3 后 `/api/skills` 返回 `[]`、状态页显示「技能:已关闭」 | 通过 | +| 有 python3:Python 技能可执行;桩掉 python3 后技能清单不变(`/api/skills` 照常返回),执行 `run.py` 类技能报「技能入口启动失败:spawn python3 ENOENT」,`office` 这类非 Python 技能不受影响 | 待复测 | | 四个 MCP 在具备条件时均能发现工具(`[mcp] web_search / image_task / video_task / asr: 发现 1 个工具`) | 通过 | | 前台模式 `Ctrl-C` 与 `TERM`:8090 与 8091~8094 全部释放,无残留进程 | 通过 | | 二次启动:沿用配置、跳过依赖安装(时间戳生效) | 通过 | @@ -336,7 +348,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` 为空,工具会回明确的「未配置」错误 | -| 技能依赖 | 本地不预装:缺包时模型会把包装进 `skills/deps`(`$AGENT_SKILLS_DEPS`,已在该进程 `PYTHONPATH` 里,装完下次运行即生效)。怎么装由模型自己决定。需要系统库的包(`weasyprint`→pango/cairo)pip 装不了,仍需手工 `brew install`。服务器上由 `agent-executor-init` 处理 | +| 技能依赖 | 本地不预装:缺包时模型会把包装进 `skills/deps`(`$AGENT_SKILLS_DEPS`,已在该进程 `PYTHONPATH` 里,装完下次运行即生效)。怎么装由模型自己决定。缺 `python3` 本体时它会先问你,同意后才装。需要系统库的包(`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 b14919a..a614659 100644 --- a/local/README.md +++ b/local/README.md @@ -65,12 +65,13 @@ cd agent | 能力 | 需要 | 没有时的表现 | |---|---|---| | 语音输入 | `ffmpeg` + 设置页给 `asr` 填上游(`X-ASR-Base-Url` / `X-ASR-Model`) | 麦克风入口自动隐藏(`/api/asr/status` 返回 `enabled:false`),`mcp_asr` 子进程也不启动 | -| 技能 | `python3` | 技能清单为空,其余功能不受影响 | +| 技能 | `python3`(仅 Python 类技能需要) | 技能清单照常显示;调 `run.py` 类技能报「入口启动失败」,`office` 这类非 Python 技能不受影响 | | 网页搜索 | 无 | 装了 Node 就有(内置免费后端) | | 图片 / 视频生成 | 设置页给对应 MCP 填上游 key | 调用时报明确的缺参错误 | -装完 `ffmpeg` / `python3` 之后**重跑一次 `./local/start.sh`** 即可生效——这两项都不写进配置, -靠「起不起子进程 / 软链指向哪 / 注入什么环境变量」切换。 +装完 `ffmpeg` 之后**重跑一次 `./local/start.sh`** 即可生效。`python3` 稍特殊:技能清单本来就在, +只要新装的解释器落在 core 启动时 `PATH` 已包含的目录里(如 brew 的 `/opt/homebrew/bin`)就无需重启; +换了目录就重跑脚本。这三项都不写进配置,靠「起不起子进程 / 注入什么环境变量」切换。 ## 配置放哪 @@ -141,6 +142,7 @@ git pull - **技能依赖不预装**:本地没有 `agent-executor-init`,`skills/*/requirements.txt` 不会在启动时 自动安装。技能缺包时会报 `ModuleNotFoundError`,模型会把缺的包装进 `skills/deps` (`AGENT_SKILLS_DEPS` 指向它,且已在该进程的 `PYTHONPATH` 里,装完下次运行即生效)。 + 连 `python3` 都没有时,技能清单仍是完整的,模型会先问你、得到同意后才装解释器。 需要系统库的包(如 `weasyprint` 依赖 pango/cairo)pip 装不了,得自己 `brew install`。 - **首个 `npm install` 要联网**:启动器会自动选源、换源重试、并把装好的依赖缓存到 `~/.cache/agent-local/`;之后重启 / 换 clone 都是本地解压,不需要网络。真要手动指定源: diff --git a/local/start.sh b/local/start.sh index 260f4ac..979084e 100755 --- a/local/start.sh +++ b/local/start.sh @@ -2,7 +2,7 @@ # local/start.sh —— 本机(macOS / Linux)一键启动 agent-core。 # # 这个脚本只负责「把容器部署的形状换成本机形状」,不改任何业务逻辑: -# 1. 探测环境(node 必需;ffmpeg 决定能不能语音;python3 决定技能可不可用) +# 1. 探测环境(node 必需;ffmpeg 决定能不能语音;python3 决定 Python 技能能否执行) # 2. 首次运行:选工作目录 + 生成 local/config.local.yml # 3. 起 core(+ 四个同栈 MCP 子进程),就绪后打开浏览器 # 4. 守护:core 退出就拉起来 @@ -353,8 +353,8 @@ ui_checks() { else ui_step "Node.js 缺失或版本过低:$NODE_HINT" bad; fi if [ "$NPM_OK" = 1 ]; then ui_step 'npm 可用(装依赖用)' ok else ui_step 'npm 缺失:随 Node.js 一起装,重装 Node 即可' bad; fi - if [ "$PY_OK" = 1 ]; then ui_step "python3 ${PY_VER}(技能可用)" ok - else ui_step 'python3 未安装(可选,技能清单为空)' warn; fi + if [ "$PY_OK" = 1 ]; then ui_step "python3 ${PY_VER}(Python 技能可用)" ok + else ui_step 'python3 未安装(Python 技能会失败;office 等非 Python 技能不受影响)' warn; fi if [ "$FF_OK" = 1 ]; then ui_step "ffmpeg ${FF_VER}(语音可用)" ok else ui_step 'ffmpeg 未安装(可选,麦克风入口隐藏)' warn; fi if [ "$PORT_FREE" = 1 ]; then ui_step "端口 $PORT 可用" ok @@ -415,10 +415,15 @@ EOF say "工作目录:$ws" } -# ---------- 技能目录:用软链切换,不动配置 ---------- +# ---------- 技能目录:软链到仓库 skills,不动配置 ---------- +# 为什么不再按 python3 有无切换成空目录:技能不一定是 Python 的。office 就是 +# SKILL.md + scripts/office,模型在 terminal 里调 `office `,跟 python3 无关; +# 一刀切会把这类技能一并藏起来。而 Python 技能缺解释器时,skills.js 的 runEntry 对 +# spawn 的 error 有处理,模型拿到的是「技能入口启动失败:spawn python3 ENOENT」, +# 干净可读,不会崩也不会挂住——没必要靠藏清单来避险。 link_skills() { link="$RUNTIME/skills" - if [ "$PY_OK" = 1 ]; then dest="$ROOT/skills"; else dest="$RUNTIME/empty-skills"; mkdir -p "$dest"; fi + dest="$ROOT/skills" rm -f "$link" 2>/dev/null || true # 万一上次留下了真目录(老版本行为),先挪走再建软链 if [ -d "$link" ] && [ ! -L "$link" ]; then rm -rf "$link"; fi @@ -957,7 +962,7 @@ fi if link_skills; then if [ "$PY_OK" = 1 ]; then ui_step '技能:已启用(python3 就绪)' ok - else ui_step '技能:已关闭(未安装 python3,装好后重跑脚本即可)' warn; fi + else ui_step '技能已暴露,但 python3 未安装:Python 技能会执行失败' warn; fi else ui_step '技能目录软链创建失败,技能不可用' warn fi @@ -1028,7 +1033,7 @@ while :; do if [ "$PY_OK" = 1 ]; then say '技能:已启用(python3 就绪)' else - say '技能:已关闭(未安装 python3;装好后重跑本脚本即可)' + say '技能:已暴露,但 python3 未安装——Python 技能调用会失败,其余照常' fi if [ "$FIRST_RUN" = 1 ]; then printf '\n首次使用:左下角「用户区」→ 设置 → 模型池,添加平台和 API Key,然后点「重启」。\n'