技能依赖层收敛:agent-executor-init 逐行离线探测,只把镜像缺的包装进 deps 外挂层(PYTHONPATH 上移到 executor 容器 env 并放行白名单,技能与 AI 终端都可见,无需 rebuild);core 删除 ensureDeps/execSyncCapture/marker 读写等全部安装逻辑;同步 ARCHITECTURE 与 skills README

This commit is contained in:
2026-09-16 12:19:02 +08:00
parent 6969c5d949
commit 5f04e9375a
6 changed files with 71 additions and 139 deletions
+8 -112
View File
@@ -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>/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];
+5 -1
View File
@@ -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
+11 -12
View File
@@ -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/<session-id>/`):每个会话一个目录;Core 与 Executor 都可读写;sh 命令默认 cwd 即此目录。
**技能目录**(`cfg.skills_root/<skill-name>/`):所有会话共享;`deps/` 子目录是 pip `--target` 共享的 Python 依赖,**与技能目录同级**(不是技能子目录)。`RESERVED_DIRS = {deps}` 在 `routes/skills.js` 里被排除以免被当成技能。
**技能目录**(`cfg.skills_root/<skill-name>/`):所有会话共享;`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 <skills_root>/deps`(共享 `deps/`,`PYTHONPATH` 追加);`install.sh` → bash 执行。
- `.deps_installed` 标记文件记录两份 hash,变化才重装。
- `runSkill` 流程:`skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`) → `ensureDeps` → 选 `python3 run.py '<json>'` 或 `bash run.sh '<json>'` → `runEntry`。
- **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`),env 只传 `PYTHONPATH=<deps_root>`。
- **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/<sid>` 看到的就是本会话数据,`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 '<json>'` 或 `bash run.sh '<json>'` → `runEntry`。
- **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`);env 不额外传,依赖层由容器 env 提供。
- **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/<sid>` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。
### 5.6 `remote-exec.js` —— 远端 executor 客户端
@@ -563,7 +562,7 @@ sequenceDiagram
1. 在 `skills/<name>/` 建目录,写 `SKILL.md`(含 YAML front matter `name`/`description`/`input_schema`)+ `run.py` 或 `run.sh`。
2. 入口脚本约定:唯一 argv = `'<JSON 字符串>'`(含全部 `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 服务
+40 -8
View File
@@ -2,14 +2,13 @@
// agent-executor-init:executor 启动前的一次性技能准备。
//
// 只处理“运行期可变”的依赖:
// - requirements.txt → python3 -m pip install --target <skills>/deps -r ...
// - requirements.txt → 先离线探测(镜像预烘包优先),只把缺失的装进 <skills>/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:<sha1>|install:<sha1>),以便复用宿主上已有的 .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;
+2 -2
View File
@@ -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];
}
+5 -4
View File
@@ -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 维护)。
---