From 5f04e9375a85a0b8b5c99c6f1f748a91bd5a488a Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 16 Sep 2026 12:19:02 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8A=80=E8=83=BD=E4=BE=9D=E8=B5=96=E5=B1=82?= =?UTF-8?q?=E6=94=B6=E6=95=9B=EF=BC=9Aagent-executor-init=20=E9=80=90?= =?UTF-8?q?=E8=A1=8C=E7=A6=BB=E7=BA=BF=E6=8E=A2=E6=B5=8B=EF=BC=8C=E5=8F=AA?= =?UTF-8?q?=E6=8A=8A=E9=95=9C=E5=83=8F=E7=BC=BA=E7=9A=84=E5=8C=85=E8=A3=85?= =?UTF-8?q?=E8=BF=9B=20deps=20=E5=A4=96=E6=8C=82=E5=B1=82=EF=BC=88PYTHONPA?= =?UTF-8?q?TH=20=E4=B8=8A=E7=A7=BB=E5=88=B0=20executor=20=E5=AE=B9?= =?UTF-8?q?=E5=99=A8=20env=20=E5=B9=B6=E6=94=BE=E8=A1=8C=E7=99=BD=E5=90=8D?= =?UTF-8?q?=E5=8D=95=EF=BC=8C=E6=8A=80=E8=83=BD=E4=B8=8E=20AI=20=E7=BB=88?= =?UTF-8?q?=E7=AB=AF=E9=83=BD=E5=8F=AF=E8=A7=81=EF=BC=8C=E6=97=A0=E9=9C=80?= =?UTF-8?q?=20rebuild=EF=BC=89=EF=BC=9Bcore=20=E5=88=A0=E9=99=A4=20ensureD?= =?UTF-8?q?eps/execSyncCapture/marker=20=E8=AF=BB=E5=86=99=E7=AD=89?= =?UTF-8?q?=E5=85=A8=E9=83=A8=E5=AE=89=E8=A3=85=E9=80=BB=E8=BE=91=EF=BC=9B?= =?UTF-8?q?=E5=90=8C=E6=AD=A5=20ARCHITECTURE=20=E4=B8=8E=20skills=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/server/tools/skills.js | 120 +++---------------------------------- docker-compose.yml | 6 +- docs/ARCHITECTURE.md | 23 ++++--- executor/init-skills.js | 48 ++++++++++++--- executor/server.js | 4 +- skills/README.md | 9 +-- 6 files changed, 71 insertions(+), 139 deletions(-) diff --git a/app/server/tools/skills.js b/app/server/tools/skills.js index 44c7a19..39750bb 100644 --- a/app/server/tools/skills.js +++ b/app/server/tools/skills.js @@ -1,11 +1,12 @@ -// Skill Manager:发现、查看与执行技能,并在执行前自动检查与安装依赖。 +// Skill Manager:发现、查看与执行技能。 +// 依赖不由 core 安装:requirements.txt 与技能资产(install.sh)在 executor 启动前由 agent-executor-init +// 一次性处理——镜像已带的包跳过,缺的装进 skills/deps,运行期经 executor 容器 env 的 PYTHONPATH 可见。 // 技能统一存放于技能根目录(cfg.skills_root,所有任务/会话共享;容器内挂 ./skills → /workspace/skills),每个技能一个子目录: // /SKILL.md(必须)、run.py | run.sh(入口)、requirements.txt、install.sh(可选)。 // 入口脚本约定接收一个 JSON 字符串作为唯一命令行参数(含全部 input_args)。 const fs = require('fs'); const fsp = require('fs').promises; const path = require('path'); -const crypto = require('crypto'); const { spawn } = require('child_process'); const YAML = require('yaml'); const log = require('../log'); @@ -17,9 +18,6 @@ class SkillNotFoundError extends Error { class SkillExecutionError extends Error { constructor(msg, code) { super(msg); this.name = 'SkillExecutionError'; this.code = code; } } -class DependencyInstallError extends Error { - constructor(msg, code) { super(msg); this.name = 'DependencyInstallError'; this.code = code; } -} // 技能根目录:优先 cfg.skills_root(config.yml 配置,所有任务共享);缺省取 workspace_root 的同级 skills 目录。 function skillsRoot(ctx) { @@ -92,105 +90,6 @@ async function getSkillInfo(ctx, skillName) { return fsp.readFile(mdPath, 'utf8'); } -// ---------- 依赖安装 ---------- -// 不用虚拟环境(每个技能一份 .venv 太占空间,且容器重建后全丢): -// pip install --target 装到技能根目录下的共享 deps 目录(容器内 /workspace/skills/deps, -// 随挂载卷持久化,重建镜像不丢);运行时通过 PYTHONPATH 让 Python 找到它们。 -function depsRoot(ctx) { - return path.join(skillsRoot(ctx), 'deps'); -} - -// 技能子进程环境:PYTHONPATH 追加共享依赖目录(sys.path 的搜索路径,非标准库覆盖)。 -function skillEnv(ctx) { - const deps = depsRoot(ctx); - const existing = process.env.PYTHONPATH; - return Object.assign({}, process.env, { PYTHONPATH: existing ? deps + ':' + existing : deps }); -} - -function hashFile(p) { - try { return crypto.createHash('sha1').update(fs.readFileSync(p)).digest('hex'); } catch (_) { return ''; } -} - -// 在技能目录下执行一个前台命令,返回 stdout+stderr;非零退出抛 DependencyInstallError。 -// 安装命令兼有硬超时(默认 10 分钟),防 pip/apt 挂死阻塞会话。 -// 配了 executor:命令拼成单条 shell 行交远端执行(core 镜像已不带 python/pip)。 -// 注意传 PYTHONPATH=共享 deps:远端进程原有 PYTHONPATH 会被覆盖(executor 容器不预装到 site-packages,仅影响技能依赖可见性)。 -function execSyncCapture(ctx, cmd, args, cwd, timeoutMs) { - const limit = timeoutMs || 600000; - const cfg = ctx && ctx.cfg; - if (cfg && rexec.isRemote(cfg)) { - return rexec.run(cfg, { command: rexec.shellLine(cmd, args), cwd, timeout_ms: limit, env: { PYTHONPATH: depsRoot(ctx) } }) - .then(r => { - if (r.killed_by === 'timeout') throw new DependencyInstallError('依赖安装超时(' + limit + 'ms)已终止:\n' + r.out.trim(), -1); - if (r.code === 0) return r.out.trim(); - throw new DependencyInstallError((r.out.trim() || ('依赖命令退出码 ' + r.code)) + ' [exit: ' + r.code + ']', r.code); - }, e => { - if (e instanceof DependencyInstallError) throw e; - throw new DependencyInstallError('依赖命令远程执行失败:' + e.message, -1); - }); - } - return new Promise((resolve, reject) => { - const child = spawn(cmd, args, { cwd, env: process.env, detached: true }); - let out = ''; - let settled = false; - const onData = d => { out += d.toString(); }; - child.stdout.on('data', onData); - child.stderr.on('data', onData); - const timer = setTimeout(() => { - if (settled) return; - settled = true; - try { process.kill(-child.pid, 'SIGKILL'); } catch (_) { try { child.kill('SIGKILL'); } catch (__) {} } - reject(new DependencyInstallError('依赖安装超时(' + limit + 'ms)已终止:\n' + out.trim(), -1)); - }, limit); - child.on('error', err => { - if (settled) return; - settled = true; clearTimeout(timer); - reject(new DependencyInstallError('依赖命令启动失败:' + err.message, -1)); - }); - child.on('close', code => { - if (settled) return; - settled = true; clearTimeout(timer); - if (code === 0) resolve(out.trim()); - else reject(new DependencyInstallError((out.trim() || ('依赖命令退出码 ' + code)) + ' [exit: ' + code + ']', code)); - }); - }); -} - -// 安装依赖并写缓存标记 .deps_installed(内容为依赖文件 hash,变化则重装)。 -// Python 依赖装进共享 deps 目录;install.sh 用于系统级依赖,直接执行。 -async function ensureDeps(ctx, dir, skillName) { - const reqPath = path.join(dir, 'requirements.txt'); - const installPath = path.join(dir, 'install.sh'); - const hasReq = fs.existsSync(reqPath); - const hasInstall = fs.existsSync(installPath); - if (!hasReq && !hasInstall) return; - - const need = 'req:' + hashFile(reqPath) + '|install:' + hashFile(installPath); - const markerPath = path.join(dir, '.deps_installed'); - if (fs.existsSync(markerPath) && fs.readFileSync(markerPath, 'utf8') === need) { - log.debug('skills', skillName + ' 依赖已安装(命中缓存)'); - return; - } - - try { - if (hasReq) { - const target = depsRoot(ctx); - fs.mkdirSync(target, { recursive: true }); - log.debug('skills', skillName + ':pip install --target ' + target); - await execSyncCapture(ctx, 'python3', ['-m', 'pip', 'install', '--target', target, '-r', reqPath], dir); - } - if (hasInstall) { - log.debug('skills', skillName + ':执行 install.sh'); - await execSyncCapture(ctx, 'bash', ['install.sh'], dir); - } - } catch (e) { - if (e instanceof DependencyInstallError) throw e; - throw new DependencyInstallError('依赖安装失败:' + e.message, -1); - } - fs.writeFileSync(markerPath, need, 'utf8'); - log.debug('skills', skillName + ':依赖安装完成'); -} - // ---------- 参数路径预处理 ---------- // 技能进程的工作目录是技能目录,而 Agent 习惯传相对会话任务目录的路径; // 执行前统一把路径样式的相对参数转成绝对路径,技能脚本无感知。 @@ -227,14 +126,13 @@ function validateArgs(fm, inputArgs, skillName) { // 前台执行技能入口,带超时与取消支持;成功 resolve stdout,失败 reject SkillExecutionError。 // 配了 executor:入口命令拼成单条 shell 行(参数单引号转义,JSON payload 安全)交远端执行, -// cwd 由调用方给出(run_skill 传会话目录以命中 session 隔离与虚拟视图;依赖安装仍传技能目录), -// PYTHONPATH 指向共享 deps;core 与 executor 同路径挂载 skills,无需翻译。 +// cwd 由调用方给出(run_skill 传会话目录以命中 session 隔离与虚拟视图); +// 技能依赖的 PYTHONPATH 由 executor 容器 env 提供,core 不感知依赖层。 function runEntry(ctx, entry, args, cwd, timeoutMs) { const cfg = ctx.cfg; if (cfg && rexec.isRemote(cfg)) { return rexec.run(cfg, { - command: rexec.shellLine(entry, args), cwd, timeout_ms: timeoutMs, - env: { PYTHONPATH: depsRoot(ctx) }, run: ctx.run, + command: rexec.shellLine(entry, args), cwd, timeout_ms: timeoutMs, run: ctx.run, }).then(r => { const trimmed = r.out.replace(/\n+$/, '').trim(); if (r.killed_by === 'timeout') throw new SkillExecutionError('技能执行超时(' + timeoutMs + 'ms)已终止:\n' + trimmed, -1); @@ -244,7 +142,7 @@ function runEntry(ctx, entry, args, cwd, timeoutMs) { }); } return new Promise((resolve, reject) => { - const child = spawn(entry, args, { cwd, env: skillEnv(ctx), detached: true }); + const child = spawn(entry, args, { cwd, env: process.env, detached: true }); if (ctx.run && ctx.run.procs) ctx.run.procs.add(child); let out = ''; let settled = false; @@ -308,13 +206,11 @@ async function runSkill(ctx, skillName, inputArgs) { try { fm = parseFrontMatter(await fsp.readFile(mdPath, 'utf8')); } catch (_) {} validateArgs(fm, args, skillName); - await ensureDeps(ctx, dir, skillName); - let entry, cmdArgs; const runPy = path.join(dir, 'run.py'); const runSh = path.join(dir, 'run.sh'); if (fs.existsSync(runPy)) { - // PYTHONPATH 已指向共享 deps,直接走系统 python3。 + // 直接走系统 python3(技能依赖由 executor 容器 env 的 PYTHONPATH 提供)。 // 入口一律用绝对路径:远端 cwd 是会话目录,相对的 'run.py' 会找不到。 entry = 'python3'; cmdArgs = [runPy, payload]; diff --git a/docker-compose.yml b/docker-compose.yml index cc7c12a..7894d6f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -25,7 +25,8 @@ services: - agent-mcp-net # 技能准备(一次性,跑完退出):把各技能的“运行期可变”依赖落到宿主 ./skills—— - # requirements.txt → pip --target 共享 deps 目录;install.sh → 技能资产(如字体提取)。 + # requirements.txt → 先离线探测,只把镜像缺的包装进共享 deps 目录(镜像已带的不重复装); + # install.sh → 技能资产(如字体提取)。deps 由 executor 容器 env 的 PYTHONPATH 可见。 # 系统层依赖(apt 等)不在这里做,由镜像的 skills 构建阶段烘进(才持久且对命令只读)。 # 只挂 ./skills(不挂 ./tasks),因此看不到任何会话数据;read_only 根 + tmpfs /tmp。 agent-executor-init: @@ -79,6 +80,9 @@ services: - EXECUTOR_LOG_LEVEL=info # 防止 Python 在 skills 目录生成 __pycache__ - PYTHONDONTWRITEBYTECODE=1 + # 技能依赖外挂层:镜像缺的包由 agent-executor-init 装进挂载卷 skills/deps, + # 由此处进容器 env(server.js 白名单同步放行),使技能与 AI 终端命令都能 import 到。 + - PYTHONPATH=/workspace/skills/deps # 定义隔离基路径,server.js 需读取此变量以执行 umount 和 bind mount - EXECUTOR_ISOLATION_BASE=/mnt/host-tasks diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index f27fc1b..115cb46 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -42,7 +42,7 @@ agent/ │ │ ├── tools/ │ │ │ ├── definitions.json 内置 15 个工具的 OpenAI function 格式定义 │ │ │ ├── executor.js 工具执行器(文件类 + terminal + skill 委托) -│ │ │ └── skills.js Skill Manager(list/info/run + 依赖安装 + 路径预处理) +│ │ │ └── skills.js Skill Manager(list/info/run + 路径预处理) │ │ ├── download-token.js 下载链接签名(浏览器原生下载用;密钥进程内随机) │ │ ├── download-send.js 单文件下载响应(Content-Disposition / 缓存策略) │ │ ├── public-files.js 公网临时文件短 ID 表(mint/resolve + 过期) @@ -109,7 +109,7 @@ graph LR Zhipu -->|匿名 GET /p/id| Core Core <-->|读写| Tasks Exec <-->|读写| Tasks - Core <-->|技能 + deps| Skills + Core <-->|技能| Skills Exec <-->|技能 + deps| Skills Core --> DB ``` @@ -130,7 +130,7 @@ graph LR - Core 通过环境变量 `EXECUTOR_URL` / `EXECUTOR_TOKEN` 注入 executor 端点(也可用 `config.yml` 的 `executor` 段覆盖)。**token 从 `.env` 读取**(compose 变量替换 `${EXECUTOR_TOKEN:?...}`,未设置直接报错,杜绝静默无鉴权);`.env` 已 gitignore,模板见 `.env.example`,生成:`openssl rand -hex 32`。 - Executor **拒绝来自容器自身(回环/本机网卡)的 `/exec`**:隔离只 unshare mount+pid,命令与 executor 同 net ns,能打到 `127.0.0.1:9000`;据此即使 token 泄漏也无法在会话内调用 `/exec` 越权读他人会话(core 在另一容器,不受影响)。本机集成测试用 `EXECUTOR_ALLOW_LOCAL_ORIGIN=1` 放行,生产不得设置。 - Executor 镜像分两阶段(`executor/Dockerfile`):`base` = M(长期不变,仅系统工具 + 预烘 Python 包),`skills` = M' = M + 技能“系统层”依赖。compose 用 `build.target: skills`、上下文为仓库根(`.dockerignore` 只放行 `executor/`、`skills/`)。管理员增删/改动 skills 后 `docker compose build agent-executor` 重建 M',M 不动。 -- `agent-executor-init` 在 executor 启动前一次性执行(`executor/init-skills.js`):把各技能 `requirements.txt`(`pip --target` 共享 deps)与 `install.sh` 生成的资产落到宿主 `./skills`,跑完即退出;只挂 `./skills`(不挂 `./tasks`,看不到会话数据)、无特权、`read_only`。executor `depends_on` 其 `service_completed_successfully`。 +- `agent-executor-init` 在 executor 启动前一次性执行(`executor/init-skills.js`):逐行离线探测各技能 `requirements.txt`,只把镜像缺的包 `pip --target` 装进共享 `deps/`,并执行 `install.sh` 生成技能资产,全部落到宿主 `./skills`,跑完即退出;只挂 `./skills`(不挂 `./tasks`,看不到会话数据)、无特权、`read_only`(系统层写不进去,只能写挂载卷)。executor `depends_on` 其 `service_completed_successfully`。 - Executor 在 compose 里加了 cgroup/ulimit 护栏(`cpus 2.0` / `mem_limit 2g` / `pids_limit 512` / `ulimits.fsize 2G`)——详见 `executor/server.js` 头注释。 --- @@ -210,7 +210,7 @@ stateDiagram-v2 **任务目录**(`cfg.workspace_root//`):每个会话一个目录;Core 与 Executor 都可读写;sh 命令默认 cwd 即此目录。 -**技能目录**(`cfg.skills_root//`):所有会话共享;`deps/` 子目录是 pip `--target` 共享的 Python 依赖,**与技能目录同级**(不是技能子目录)。`RESERVED_DIRS = {deps}` 在 `routes/skills.js` 里被排除以免被当成技能。 +**技能目录**(`cfg.skills_root//`):所有会话共享;`deps/` 子目录是 pip `--target` 共享的 Python 依赖(只放镜像缺失的包,镜像已带的不重复装),**与技能目录同级**(不是技能子目录)。`RESERVED_DIRS = {deps}` 在 `routes/skills.js` 里被排除以免被当成技能。 **版本与提交号**:git short hash 来自 `version.json`(post-commit 钩子自动写)→ 容器通过 bind mount 读到;无 `version.json` 时回退 `git rev-parse`;都没有则只显示 package.json 版本。 @@ -286,13 +286,12 @@ stateDiagram-v2 ### 5.5 `tools/skills.js` —— Skill Manager - 技能 = 单层子目录,含 `SKILL.md`(YAML front matter 可选,含 `description` / `input_schema`)+ `run.py` 或 `run.sh` 入口(接收 JSON 字符串作为唯一 argv)。 -- 依赖: - - `requirements.txt` → `pip install --target /deps`(共享 `deps/`,`PYTHONPATH` 追加);`install.sh` → bash 执行。 - - `.deps_installed` 标记文件记录两份 hash,变化才重装。 -- `runSkill` 流程:`skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`) → `ensureDeps` → 选 `python3 run.py ''` 或 `bash run.sh ''` → `runEntry`。 -- **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`),env 只传 `PYTHONPATH=`。 -- **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。`ensureDeps` 的安装命令仍传技能目录(依赖是技能私有资源,且 skills 为 `:ro`,运行期不应安装)。 -- **依赖就绪时机**:系统层依赖(apt 等,`install.sh` 的副作用)在镜像 `skills` 阶段烘入 M';pip 依赖与技能资产(如字体提取)在服务启动前由 `agent-executor-init` 落到宿主 `./skills`(hash/marker 与 `ensureDeps` 同格式)。运行期 skills `:ro`,`runSkill` 的 `ensureDeps` 命中 marker 即跳过;若运行期经 UI 改了依赖,需 `docker compose up -d` 重新 init(否则该技能会报依赖安装失败)。 +- 依赖不由 core 安装(core 只发现与执行):系统层依赖(apt 等,`install.sh` 的副作用)在镜像 `skills` 阶段烘入 M'(需重建镜像);pip 依赖与技能资产(如字体提取)在服务启动前由 `agent-executor-init` 一次性落到宿主 `./skills`。 + - init 的 pip 步骤先离线探测(`pip install --no-index --dry-run <逐行>`,不联网):镜像已带的包直接跳过,只把缺的装进 `deps/`;`.deps_installed` marker(requirements/install.sh 两份 hash)也在那里维护。 + - 外挂层可见性:`skills/deps` 由 compose 放进 executor 容器 env 的 `PYTHONPATH`(`server.js` 白名单同步放行),技能入口与 AI 终端命令都能 import;运行期 skills 与 deps 均 `:ro`,**加包只需改 `requirements.txt` 后 `docker compose up -d`(重跑 init),不需重建镜像**。 +- `runSkill` 流程:`skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`) → 选 `python3 run.py ''` 或 `bash run.sh ''` → `runEntry`。 +- **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`);env 不额外传,依赖层由容器 env 提供。 +- **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。 ### 5.6 `remote-exec.js` —— 远端 executor 客户端 @@ -563,7 +562,7 @@ sequenceDiagram 1. 在 `skills//` 建目录,写 `SKILL.md`(含 YAML front matter `name`/`description`/`input_schema`)+ `run.py` 或 `run.sh`。 2. 入口脚本约定:唯一 argv = `''`(含全部 `input_args`)。 3. 路径类参数会被 `absolutizeArgs` 自动按任务目录转绝对;如需输出到特定位置,传 `output` / `dest` / `target` 之类的 key 名触发"目录型参数"启发。 -4. 依赖:`requirements.txt`(pip)或 `install.sh`(系统级)放同目录;`.deps_installed` 由 `ensureDeps` 自动维护。 +4. 依赖:`requirements.txt`(pip)或 `install.sh`(系统级)放同目录;镜像缺的包在启动时由 `agent-executor-init` 装进 `deps/`(改完依赖跑 `docker compose up -d`,不用重建镜像),`install.sh` 与 `.deps_installed` marker 也在那里维护。 5. 改完文件后 **无需重启**——`routes/skills.js` 的 `refreshSkillPrompt()` 会重建 system prompt 段落。 ### 11.3 加一个 MCP 服务 diff --git a/executor/init-skills.js b/executor/init-skills.js index 7049f60..057e3c6 100644 --- a/executor/init-skills.js +++ b/executor/init-skills.js @@ -2,14 +2,13 @@ // agent-executor-init:executor 启动前的一次性技能准备。 // // 只处理“运行期可变”的依赖: -// - requirements.txt → python3 -m pip install --target /deps -r ... +// - requirements.txt → 先离线探测(镜像预烘包优先),只把缺失的装进 /deps // - install.sh → 在技能目录执行(生成技能自带资产,如从系统字体提取 cjk.ttf) // 系统层依赖(apt 等)不在这里做——那部分由派生镜像 M'(executor/Dockerfile 的 skills 阶段) -// 承载,才持久且对命令只读。 +// 承载,才持久且对命令只读(本容器根文件系统 read_only,系统层也写不进去)。 // // 无特权:不做任何 mount;只挂 ./skills(不挂 ./tasks),因此看不到任何会话数据。 -// 幂等:按 requirements.txt/install.sh 的内容 hash(与 core 的 ensureDeps 同格式)比对 -// .deps_installed,命中即跳过。 +// 幂等:按 requirements.txt/install.sh 的内容 hash 比对 .deps_installed,命中即跳过。 // 退出码恒为 0:单个技能失败只告警,不阻断 executor 启动(该技能暂不可用,其余照常)。 'use strict'; const fs = require('fs'); @@ -25,18 +24,41 @@ function log() { console.log('[' + new Date().toISOString() + '] [skills-init]', ...args); } -// 与 core(app/server/tools/skills.js 的 hashFile/ensureDeps)保持完全一致的 hash 与 marker 格式。 +// hash 与 marker 格式沿用原 core 实现(req:|install:),以便复用宿主上已有的 .deps_installed。 function hashFile(p) { try { return crypto.createHash('sha1').update(fs.readFileSync(p)).digest('hex'); } catch (_) { return ''; } } +// 技能子进程的依赖可见性:与运行期一致(运行期由 compose 把同一个 deps 目录放进 executor 的 PYTHONPATH)。 +function skillEnv() { + const existing = process.env.PYTHONPATH; + return Object.assign({}, process.env, { PYTHONPATH: existing ? DEPS + ':' + existing : DEPS }); +} + function run(cmd, args, cwd) { log('run:', cmd, args.join(' '), '(cwd=' + cwd + ')'); - const r = spawnSync(cmd, args, { cwd, stdio: 'inherit', env: process.env }); + const r = spawnSync(cmd, args, { cwd, stdio: 'inherit', env: skillEnv() }); if (r.error) { log('spawn 失败:' + r.error.message); return false; } return r.status === 0; } +// requirements 逐行解析:去掉注释与空行 +function reqLines(p) { + try { + return fs.readFileSync(p, 'utf8').split('\n') + .map(l => l.replace(/#.*$/, '').trim()) + .filter(Boolean); + } catch (_) { return []; } +} + +// 离线探测一行依赖是否已可用(镜像预烘包优先,其次已在外挂层): +// --no-index 只对当前环境求值、不联网;--dry-run 不写盘。exit 0 = 已满足。 +function satisfied(line, cwd) { + const r = spawnSync('python3', ['-m', 'pip', 'install', '--no-index', '--dry-run', line], + { cwd, env: skillEnv(), stdio: 'pipe', encoding: 'utf8' }); + return r.status === 0; +} + function initSkill(name) { const dir = path.join(ROOT, name); const reqPath = path.join(dir, 'requirements.txt'); @@ -58,8 +80,18 @@ function initSkill(name) { let ok = true; try { if (hasReq) { - fs.mkdirSync(DEPS, { recursive: true }); - ok = run('python3', ['-m', 'pip', 'install', '--no-cache-dir', '--target', DEPS, '-r', reqPath], dir) && ok; + const lines = reqLines(reqPath); + const missing = lines.filter(l => !satisfied(l, dir)); + if (!missing.length) { + log('依赖全部已满足(镜像/外挂层),跳过 pip:' + name); + } else { + log('缺失依赖装入外挂层(' + missing.length + '/' + lines.length + '):' + missing.join(', ')); + fs.mkdirSync(DEPS, { recursive: true }); + // --upgrade:外挂层已有旧版本时允许覆盖(--target 默认遇同名文件只告警不替换) + ok = run('python3', ['-m', 'pip', 'install', '--no-cache-dir', '--upgrade', '--target', DEPS].concat(missing), dir) && ok; + const still = missing.filter(l => !satisfied(l, dir)); + if (still.length) { log('安装后仍缺失:' + still.join(', ')); ok = false; } + } } if (hasInstall) { ok = run('bash', ['install.sh'], dir) && ok; diff --git a/executor/server.js b/executor/server.js index d235efe..caac9e2 100644 --- a/executor/server.js +++ b/executor/server.js @@ -515,9 +515,9 @@ async function handleExec(req, res) { if (!isFinite(maxChars) || maxChars <= 0) maxChars = DEFAULT_MAX_OUT; maxChars = Math.min(maxChars, DEFAULT_MAX_OUT); - // 环境变量白名单 + // 环境变量白名单(AI 命令与技能子进程共用;PYTHONPATH 用于技能依赖外挂层) const env = {}; - for (const key of ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TZ', 'PYTHONUNBUFFERED', + for (const key of ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TZ', 'PYTHONUNBUFFERED', 'PYTHONPATH', 'PYTHONDONTWRITEBYTECODE', 'PYTHONPYCACHEPREFIX', 'MPLBACKEND']) { if (process.env[key]) env[key] = process.env[key]; } diff --git a/skills/README.md b/skills/README.md index 7bc7c91..cf3e93a 100644 --- a/skills/README.md +++ b/skills/README.md @@ -128,7 +128,7 @@ def main(): ### 5.1 Python 依赖 -在技能目录下放置 `requirements.txt` 文件,列出所有需要的第三方包。服务启动前,`agent-executor-init`(`executor/init-skills.js`)会**自动安装**这些依赖到共享的 `deps` 目录(技能根目录下的 `deps/`),运行期通过 `PYTHONPATH` 注入;结果按 `requirements.txt` 的 hash 缓存(`.deps_installed`),未变化则跳过。 +在技能目录下放置 `requirements.txt` 文件,列出所有需要的第三方包。服务启动前,`agent-executor-init`(`executor/init-skills.js`)会逐行**离线探测**:镜像已预烘的包(见 `executor/Dockerfile`)直接跳过,只把缺的装到共享 `deps` 目录(技能根目录下的 `deps/`),运行期由 executor 容器 env 的 `PYTHONPATH` 可见(技能脚本与 AI 终端命令都能 import,无需 rebuild 镜像);结果按 `requirements.txt` 的 hash 缓存(`.deps_installed`),未变化则整个技能跳过。 示例 `requirements.txt`: @@ -137,7 +137,7 @@ requests==2.28.1 beautifulsoup4==4.11.1 ``` -- 依赖安装使用 `pip install --target`,不会污染系统全局。 +- 依赖安装使用 `pip install --target`,不会污染系统全局;镜像已带的包不会重复装。 - 所有技能**共享**同一个 `deps` 目录,请注意版本冲突(后装的覆盖先装的)。建议锁定精确版本。 - 运行期 skills 目录只读;若上线后经 UI 改了 `requirements.txt`,需重启(`docker compose up -d`)触发重新 init,否则该技能会因依赖未就绪而失败。 @@ -158,12 +158,13 @@ apt-get install -y -qq some-package ``` - `install.sh` 必须可执行(`chmod +x install.sh`)。 -- 请保持幂等:两处都以内容 hash 为缓存,仅在变化时执行。 +- 请保持幂等:init 侧以内容 hash 缓存(`.deps_installed`),构建侧靠 Docker 层缓存;脚本应在“依赖已就绪”时快速跳过。 +- 想两处都跑不报错:apt 类语句加 `|| true` 容错,并在脚本末尾自行校验“要的东西是否就绪”,就绪则 exit 0、否则 exit 1(参考 `md2pdf/install.sh`)。否则 init 阶段(根文件系统只读)的 apt 失败会让整个技能被标记为“未就绪”。 - 改动 `install.sh` 后:系统包需 `docker compose build agent-executor`,资产需 `docker compose up -d`(或两者一起 `build && up`)。 ### 5.3 缓存机制 -Skill Manager 会为每个技能生成一个 `.deps_installed` 标记文件,记录依赖文件的哈希值。只有当 `requirements.txt` 或 `install.sh` 内容改变时,才会重新安装。手动删除该文件可强制重装。 +`agent-executor-init` 会为每个技能生成一个 `.deps_installed` 标记文件,记录依赖文件的哈希值。只有当 `requirements.txt` 或 `install.sh` 内容改变时,才会重新安装/重新生成资产。手动删除该文件可强制重跑(core 运行期不再读写依赖,标记只由 init 维护)。 ---