diff --git a/README.md b/README.md index 2bcd784..53a172e 100644 --- a/README.md +++ b/README.md @@ -803,7 +803,7 @@ networks: 无域名/反代时,compose 直接把容器 8090 映射到宿主机 8090,浏览器访问 `http://<服务器IP>:8090`(端口可用 `.env` 的 `AGENT_PORT` 改)。网络 `agent-mcp-net` 与 `mcp` 仓库的服务共用、由本仓库创建(无需手动 `docker network create`,但因此要**先起 agent 再起 mcp**):core 与 executor 都靠它按容器名访问 MCP。认证用应用内置的多用户登录(`config.yml` 的 `auth.users`,登录页 `/login`),多用户共享同一任务库,不做任务隔离。 -**对外只开这一个端口**(executor 与 mcp 服务都不映射宿主机)。其中一条是反向入站:外部服务(如智谱)生成视频前要拉参考图,走的是 core 的匿名短链 `GET /p/`——由 AI 在内网 `curl http://agent-core:8081/public-link?path=…` 现签(签发端口不映射宿主机,所以不需要凭据),见 `docs/DEPLOY.md` 第 4.1 节。 +**对外只开这一个端口**(executor 与 mcp 服务都不映射宿主机)。其中一条是反向入站:外部服务(如智谱)生成视频前要拉参考图,走的是 core 的匿名短链 `GET /p/`——由 AI 调内置工具 `mint_public_link`(传文件名,core 在进程内现签)拿到,没有任何额外的签发端口,见 `docs/DEPLOY.md` 第 4.1 节。 HTTP 直连时浏览器不认为这是“安全上下文”:PWA/Service Worker 不注册、`navigator.clipboard` 降级(前端已有回退),登录 cookie 无 `Secure` 标志可正常工作。日后若加 HTTPS 反代,**SSE 需关代理缓冲**(`proxy_buffering off`),详见 `docs/DEPLOY.md`。 diff --git a/app/README.md b/app/README.md index befd927..43b3656 100644 --- a/app/README.md +++ b/app/README.md @@ -19,7 +19,7 @@ app/ │ │ ├── messages.js # 消息/SSE/start/stop(10.2) │ │ └── files.js # 文件上传/列表/下载/删除(10.3) │ ├── tools/ -│ │ ├── definitions.json # 内置 12 个工具的 JSON Schema +│ │ ├── definitions.json # 内置 16 个工具的 JSON Schema │ │ └── executor.js # 内置工具执行器(任务目录沙箱;未知工具名转 MCP) │ ├── templates/system-prompt.txt # System prompt 模板(直接编辑) │ └── public/ # H5 前端(Vanilla JS + SSE) diff --git a/app/config.example.yml b/app/config.example.yml index ef8802d..a0a8bbc 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -57,11 +57,11 @@ data_root: "./data" # token: "change-me" # 选填;executor 侧配同值才校验 # 公网临时链接(给"自己来拉文件"的外部服务用:例如智谱视频生成前要下载参考图)。 -# 配了 base_url 后,core 会额外在**内网**监听一个不映射宿主机的端口(env PUBLIC_LINK_PORT,默认 8081), -# 上面只挂一条 GET /public-link?path=<文件的绝对路径>;沙箱里的 AI 命令 curl 它,即可换回一条 -# 短命的公网下载链接(复用登录下载那套签名:不可猜 / 会过期 / 绑会话 / 重启即全部失效)。 +# 机制:沙箱里的 AI 调内置工具 mint_public_link(传文件名),core 在进程内直接签出一条 +# 短命的公网下载链接(不可猜 / 会过期 / 绑会话 / 重启即全部失效),外部服务再匿名 GET /p/ 取文件。 +# 全程不监听额外端口、不搬字节(文件始终在任务目录里)。 # base_url 填本服务的对外地址(就是浏览器访问的 http://<服务器IP>:),只用于拼绝对地址; -# 留空 = 该功能整体关闭(对应 MCP 服务里需要公网 URL 的那部分就用不了)。 +# 留空 = 该功能整体关闭(mint_public_link 会直接报错,对应 MCP 服务里需要公网 URL 的那部分就用不了)。 # 容器 env 里配了 VIRTUAL_HOST(nginx-proxy 域名 + HTTPS 那套)时,本项会被它盖住:链接前缀直接用 # https://<第一个域名>,不需要改这里(也避开了“重跑 init 脚本又把它写回 ip:port”的麻烦)。 public_link: diff --git a/app/server/config.js b/app/server/config.js index 59287ec..3051945 100644 --- a/app/server/config.js +++ b/app/server/config.js @@ -43,9 +43,9 @@ const DEFAULTS = { // MCP 服务列表:每项 {name?, url, headers?, enable?(默认 true,false 时启动不加载)};启动时发现其工具并追加到内置工具之后。 // 注意与内置工具(definitions.json)严格分离:这里只配外部 MCP 服务。 mcp_servers: [], - // 公网临时链接:base_url 非空时,core 额外在内网监听一个**不映射宿主机**的端口(PUBLIC_LINK_PORT, - // 默认 8081),上面只挂 GET /public-link:沙箱里的 AI 命令 curl 它,换一条短命的公网下载链接 - // (给智谱那类"自己来拉文件"的外部服务用)。base_url = 本服务的对外地址(如 http://1.2.3.4:8090)。 + // 公网临时链接:内置工具 mint_public_link 的唯一开关。base_url 非空时,工具会把会话目录里的 + // 文件签成一条短命的公网下载链接(给智谱那类"自己来拉文件"的外部服务用);留空则工具报错。 + // base_url = 本服务的对外地址(如 http://1.2.3.4:8090),只用于拼绝对地址;不监听任何额外端口。 public_link: { base_url: '', ttl_ms: 1800000 }, }; diff --git a/app/server/download-token.js b/app/server/download-token.js index 7736b3d..13ce58a 100644 --- a/app/server/download-token.js +++ b/app/server/download-token.js @@ -1,10 +1,10 @@ -// 临时链接签名(files.js 的浏览器下载链接、routes/public-link.js 的公网链接共用同一套)。 +// 临时链接签名(files.js 的浏览器下载链接用)。 // // 设计要点: // - 密钥进程内随机:重启后所有旧链接自动失效。公网链接本来就该短命,这是免费拿到的性质。 // - 签名覆盖「会话 + 路径 + 过期时间」三项,任何一项被改都会验签失败; // 验签用 timingSafeEqual,不做按字节比较的旁路。 -// - 这里只提供"怎么签";"给谁签、能签什么"由调用方决定(见 routes/public-link.js 的边界校验)。 +// - 这里只提供"怎么签";"给谁签、能签什么"由调用方决定(见 routes/files.js 的校验)。 'use strict'; const crypto = require('crypto'); @@ -30,7 +30,7 @@ function validPayload(payload, expires, t) { return sameHex(signPayload(payload), t); } -// 下载链接的报文形状(唯一一份;files.js 验签、public-link.js 签发都走它,避免两边写歪) +// 下载链接的报文形状(唯一一份;files.js 签发与验签都走它,避免两边写歪) function downloadPayload(sessionId, rel, expires) { return sessionId + '\n' + rel + '\n' + expires; } diff --git a/app/server/public-files.js b/app/server/public-files.js index cdfc9b3..31b29c5 100644 --- a/app/server/public-files.js +++ b/app/server/public-files.js @@ -8,7 +8,8 @@ // 状态放本进程内存:重启即全部失效 —— 与签名方案语义一致(签名密钥本来就是进程内随机的), // 所以不是退步,而是把「不可猜」从 HMAC 换成了随机 ID 本身。 // -// 边界:只有内网签发入口(routes/public-link.js,不映射宿主机)能 mint; +// 边界:mint 只有一个入口 —— 内置工具 mint_public_link(tools/executor.js,与 core 同进程), +// 它先做“沙箱内 + 已存在且是文件 + realpath 未跳出任务目录”的校验; // 取用侧(routes/public-files.js)只按 ID 查表,查不到/过期一律 404。 'use strict'; diff --git a/app/server/routes/files.js b/app/server/routes/files.js index 31d4162..ec02be7 100644 --- a/app/server/routes/files.js +++ b/app/server/routes/files.js @@ -90,8 +90,8 @@ router.get('/:id/files', function (req, res) { // 移动端浏览器 fetch+blob 下载会丢失文件名(uuid.bin);改为短时效签名链接, // 前端拿到后 window.location.href 导航下载,走原生下载流程。 // 密钥随进程启动随机生成,重启后旧 token 自动失效。 -// 签名实现(密钥、报文形状、验签)统一在 ../download-token.js: -// routes/public-link.js 给外部服务签的是同一种链接,两边共用一份形状,避免“签得出、验不过”。 +// 签名实现(密钥、报文形状、验签)统一在 ../download-token.js。 +// (外部服务取文件的 GET /p/ 是另一套机制:短 ID + 内存表,见 ../public-files.js。) const DOWNLOAD_TOKEN_TTL_MS = downloadToken.BROWSER_TTL_MS; const signDownloadToken = downloadToken.signDownload; const validDownloadToken = downloadToken.validDownload; diff --git a/app/server/routes/public-files.js b/app/server/routes/public-files.js index 22d0ce6..69181f8 100644 --- a/app/server/routes/public-files.js +++ b/app/server/routes/public-files.js @@ -1,4 +1,4 @@ -// 公网临时文件的取用端点:GET /p/(id 由 routes/public-link.js 在内网现签)。 +// 公网临时文件的取用端点:GET /p/(id 由内置工具 mint_public_link 在 core 进程内现签)。 // // 这一跳的访问者是**外部服务**(如智谱服务器来拉参考图),它不带 cookie、不带 Authorization, // 所以必须匿名可达。安全性完全来自: diff --git a/app/server/routes/public-link.js b/app/server/routes/public-link.js deleted file mode 100644 index 2fec5ec..0000000 --- a/app/server/routes/public-link.js +++ /dev/null @@ -1,73 +0,0 @@ -// 公网临时链接签发(只在【内网监听】的端口上,见 server.js 里 PUBLIC_LINK_PORT 那段)。 -// -// 用途:把任务目录里的文件变成一条短命的公网 URL,交给外部服务去取。第一个消费者是 -// MCP video_gen:智谱服务器生成视频前要自己来拉参考图,它不带 cookie、不带 Authorization, -// 所以必须给它一条「不可猜 + 会过期」的链接。 -// 产出的形态是一个不透明短 ID(见 public-files.js 为什么不用签名 URL): -// http://:8090/p/9fQ2mZ7xK4tR1vBn -// 这解决的是:**沙箱里的 AI 怎么拿到一条公网链接**(签发接口要登录,executor 里没有凭据)。 -// -// 为什么单独一个端口、且不映射到宿主机: -// 这条接口没法用凭据保护(AI 的命令带不了凭据),那就干脆让外部**连都连不上**。 -// 鉴权靠网络边界(不 publish),不靠密钥 —— 比任何 token 都可靠,也不会把密钥漏到会话记录里。 -// -// 边界(改这里务必保持): -// 1. 只接受绝对路径,且必须落在 workspace_root 内;再反查会话表确认会话真实存在。 -// 2. 取 realpath 复核仍在任务根内:挡住“先 ln -s 一个外泄目标,再签它的链接”。 -// 3. 只签“已存在且是文件”的路径;取用侧(routes/public-files.js)会再复核一次目录边界。 -// 4. 返回 text/plain 而不是 JSON:AI 用 `curl -s` 拿到的 stdout 就是现成 URL,免解析。 -'use strict'; - -const path = require('path'); -const fs = require('fs'); -const express = require('express'); -const engine = require('../engine'); -const publicFiles = require('../public-files'); -const log = require('../log'); - -const router = express.Router(); - -function bad(res, status, msg) { - return res.status(status).type('text/plain').send('ERROR: ' + msg + '\n'); -} - -router.get('/public-link', function (req, res) { - const cfg = engine.getConfig(); - const pl = cfg.public_link || {}; - if (!pl.base_url) return bad(res, 503, 'public_link.base_url 未配置,无法签发公网链接'); - - const raw = String(req.query.path || '').trim(); - if (!raw) return bad(res, 400, '缺少 path 参数(要文件的绝对路径,如 /workspace/tasks/<会话>/foo.png)'); - if (!path.isAbsolute(raw)) return bad(res, 400, 'path 必须是绝对路径(与你在命令里看到的路径一致)'); - - const root = path.resolve(cfg.workspace_root); - const abs = path.normalize(raw); - if (abs !== root && abs.indexOf(root + path.sep) !== 0) { - return bad(res, 400, 'path 必须位于任务根目录内:' + root); - } - - const rel = path.relative(root, abs); - const sid = rel.split(path.sep)[0]; - const fileRel = rel.slice(sid.length + 1); - if (!sid || !fileRel) return bad(res, 400, 'path 要指向会话目录下的某个文件,不能是目录本身'); - if (!engine.getSession(sid)) return bad(res, 404, '会话不存在:' + sid); - - let real; - try { - if (!fs.statSync(abs).isFile()) return bad(res, 400, '不是文件:' + raw); - real = fs.realpathSync(abs); - } catch (_) { - return bad(res, 404, '文件不存在:' + raw); - } - if (real !== abs && real.indexOf(fs.realpathSync(root) + path.sep) !== 0) { - return bad(res, 400, 'path 经符号链接指向了任务根之外,拒绝签发'); - } - - const id = publicFiles.mint({ sessionId: sid, rel: fileRel, ttlMs: pl.ttl_ms }); - const url = pl.base_url + '/p/' + id; - - log.info('public-link', sid + ' 签发公网链接(' + Math.round(pl.ttl_ms / 60000) + ' 分钟):' + fileRel + ' → /p/' + id); - res.type('text/plain').send(url + '\n'); -}); - -module.exports = router; diff --git a/app/server/server.js b/app/server/server.js index b7a4071..7c75a3c 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -87,24 +87,6 @@ app.get('/api/health', (req, res) => res.json({ ok: true, time: Date.now() })); const PORT = process.env.PORT || cfg.port; -// 公网临时链接的【签发】端口:只在容器内监听、**不映射到宿主机**(compose 也不 publish), -// 所以外部连不上,于是这条接口不需要任何凭据 —— executor 里的 AI 命令可以 curl 它换一条 -// 短命的公网链接(见 routes/public-link.js 头注释)。未配 public_link.base_url 则不启动。 -const PUBLIC_LINK_PORT = Number(process.env.PUBLIC_LINK_PORT) || 8081; - -function startPublicLinkServer() { - const pl = cfg.public_link || {}; - if (!pl.base_url) { - log.info('startup', ' public_link=未配置(public_link.base_url 为空),不启动签发端口'); - return; - } - const plApp = express(); - plApp.use(require('./routes/public-link')); - plApp.listen(PUBLIC_LINK_PORT, () => { - log.info('startup', ' public_link=' + pl.base_url + ' (签发端口 :' + PUBLIC_LINK_PORT + ' 仅内网,未映射宿主机)'); - }); -} - // 启动成功后把模型实际收到的各部分 dump 到文件方便人工核对(data_root 默认 ./data, // 宿主机对应 /data/prompt.txt,已被 gitignore)。包含两部分: // 1) system 消息:模板 + 可用技能段落 + 语言指令(进程内恒定,仅技能增删时变); @@ -135,7 +117,7 @@ mcp.init(cfg).then(async () => { } server.listen(PORT, () => { log.info('startup', 'Agent server listening on ' + PORT); - startPublicLinkServer(); + log.info('startup', ' public_link=' + ((cfg.public_link || {}).base_url || '未配置(mint_public_link 不可用)')); log.info('startup', ' workspace_root=' + cfg.workspace_root); log.info('startup', ' data_root=' + cfg.data_root); log.info('startup', ' models=' + cfg.models.map(m => m.id + '@' + m.url).join(', ')); diff --git a/app/server/tools/definitions.json b/app/server/tools/definitions.json index f67b1e4..83707bd 100644 --- a/app/server/tools/definitions.json +++ b/app/server/tools/definitions.json @@ -178,6 +178,23 @@ } } }, + { + "type": "function", + "function": { + "name": "mint_public_link", + "description": "Create a short-lived, publicly reachable URL for a local file, so an external service that cannot authenticate can download it.\nUse this when another tool or API needs to fetch a local file by URL. Returns the URL as plain text on a single line.", + "parameters": { + "type": "object", + "required": ["path"], + "properties": { + "path": { + "type": "string", + "description": "Path of the file to publish, relative to the session working directory. Absolute paths inside the session working directory are also accepted." + } + } + } + } + }, { "type": "function", "function": { diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index c4151ab..c7d922b 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -8,6 +8,7 @@ const { Minimatch } = require('minimatch'); const mcp = require('../mcp'); const skills = require('./skills'); const rexec = require('../remote-exec'); +const publicFiles = require('../public-files'); function makeMatcher(pattern, opts) { const mm = new Minimatch(pattern, opts || {}); @@ -695,11 +696,34 @@ function recordFile(ctx, abs) { } catch (_) { /* 文件表仅用于展示,失败不影响主流程 */ } } +// mint_public_link:把当前会话目录里的文件签成一条短命公网链接(由 GET /p/ 取用)。 +// 这是唯一的签发入口:与 core 同进程,直接调 publicFiles.mint,不必绕任何 HTTP; +// 而 ctx.taskDir 就是会话目录,relOf 的结果正是取用侧(routes/public-files.js)要的 rel。 +async function toolMintPublicLink(ctx, args) { + const pl = (ctx.cfg && ctx.cfg.public_link) || {}; + if (!pl.base_url) throw new Error('public_link.base_url 未配置,无法签发公网链接'); + const abs = resolveInTask(ctx.taskDir, args.path); + const rel = relOf(ctx.taskDir, abs); + if (rel === '.') throw new Error('path 要指向一个文件,不能是任务目录本身'); + let st; + try { st = fs.statSync(abs); } catch (_) { throw new Error('文件不存在:' + rel); } + if (!st.isFile()) throw new Error('不是文件:' + rel); + // 符号链接外泄防护:签出去的链接是公网可拉的,realpath 必须仍在任务目录内。 + const real = fs.realpathSync(abs); + const rootReal = fs.realpathSync(ctx.taskDir); + if (!real.startsWith(rootReal + path.sep)) { + throw new Error('path 经符号链接指向了任务目录之外,拒绍签发'); + } + const id = publicFiles.mint({ sessionId: ctx.sessionId, rel, ttlMs: pl.ttl_ms }); + return pl.base_url + '/p/' + id; +} + const HANDLERS = { read_file: toolReadFile, write_file: toolWriteFile, edit_file: toolEditFile, list_directory: toolListDirectory, + mint_public_link: toolMintPublicLink, create_directory: toolCreateDirectory, delete_path: toolDeletePath, move_path: toolMovePath, diff --git a/docker-compose.yml b/docker-compose.yml index 7894d6f..f9255a4 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -127,8 +127,8 @@ networks: # 全部服务共用一个网络;由本仓库创建(固定名字,避免被加上 compose 项目名前缀),mcp 侧声明为 # external 直接加入 —— 所以全新机器上要【先起 agent,再起 mcp】。 # - core 与 executor 靠它按容器名访问 MCP 服务(如 http://mcp_web_search:3000/) - # - executor 靠它 curl core 的内网签发入口(http://agent-core:8081/public-link), - # 把本地图片换成一个短命的公网链接给外部服务用(不经过公网、不搬字节) + # - 外部服务取参考图走的是 core 对外的 GET /p/(见 public_link):AI 调内置工具 + # mint_public_link 在 core 进程内现签短链,不需要 executor 反查 core 的额外端口 agent-mcp-net: name: agent-mcp-net driver: bridge diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 115cb46..cd32e58 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -40,7 +40,7 @@ agent/ │ │ ├── balance.js 余额查询适配器(按 platform.type 分发) │ │ ├── version.js 版本信息(package.json + git 短提交号) │ │ ├── tools/ -│ │ │ ├── definitions.json 内置 15 个工具的 OpenAI function 格式定义 +│ │ │ ├── definitions.json 内置 16 个工具的 OpenAI function 格式定义 │ │ │ ├── executor.js 工具执行器(文件类 + terminal + skill 委托) │ │ │ └── skills.js Skill Manager(list/info/run + 路径预处理) │ │ ├── download-token.js 下载链接签名(浏览器原生下载用;密钥进程内随机) @@ -53,7 +53,6 @@ agent/ │ │ │ ├── config.js /api/config 读写(含 api_key/password 脱敏) │ │ │ ├── platforms.js /api/platforms/balance 余额查询 │ │ │ ├── skills.js /api/skills 技能文件管理 -│ │ │ ├── public-link.js GET /public-link 签发公网短链(只挂内网端口) │ │ │ ├── public-files.js GET /p/ 公网临时文件取用(匿名) │ │ │ └── system.js /api/system/status + /restart 优雅重启 │ │ ├── templates/ @@ -105,7 +104,6 @@ graph LR Core -->|POST /chat/completions| LLM Core -->|tools/call| MCP MCP -->|提交任务| Zhipu - Exec -->|curl /public-link 现签短链| Core Zhipu -->|匿名 GET /p/id| Core Core <-->|读写| Tasks Exec <-->|读写| Tasks @@ -116,16 +114,15 @@ graph LR 所有容器都在同一个 `agent-mcp-net` 上(core 与 executor 同时靠它访问 MCP);外网只暴露 Core (宿主机端口映射)。注意其中一条**反向**的入站链路:外部服务(如智谱)来拉文件时,走的是 Core 的 -`GET /p/`(匿名,22 字符随机 ID + 服务端过期,见 `routes/public-files.js`);这个 id 由内网 -签发入口 `GET /public-link` 现签,所以链接里既没有会话名也没有文件名。 +`GET /p/`(匿名,22 字符随机 ID + 服务端过期,见 `routes/public-files.js`);这个 id 由内置工具 +`mint_public_link` 在 core 进程内现签(AI 只传文件名,不走任何 HTTP),所以链接里既没有会话名也没有文件名。 **关键约束**(改 compose 时务必保持): -- 全部容器同一个网络 `agent-mcp-net`(由本仓库 compose 创建,mcp 侧 external 加入)——core 与 executor 都靠它按容器名访问 MCP 服务(executor 还要靠它 curl core 的签发入口)。 +- 全部容器同一个网络 `agent-mcp-net`(由本仓库 compose 创建,mcp 侧 external 加入)——core 与 executor 都靠它按容器名访问 MCP 服务。 - `agent-core` 与 `agent-executor` 须把**同一份宿主机 `./tasks`、`./skills`**挂到相同的容器路径(默认 `/workspace/tasks`、`/workspace/skills`)。这是文件工具在 Core 本地直接读、命令在远端写,二者能"看到"彼此产物的根本约定。 - **两条公网文件路径分工别搞混**:浏览器原生下载走 `download-token.js` 的签名链接(前端用 `download-token` 接口换 URL,`auth.js` 的 `isSignedDownload` 放行 `?t=`);外部服务取文件走 `GET /p/` 短 ID。前者需要在 URL 末段带文件名(给安卓下载器猜名),后者刻意不带文件名/会话名。 -- **`routes/public-link.js` 只挂在【不映射宿主机】的内网端口上**(`PUBLIC_LINK_PORT`,默认 8081):它不需要凭据(沙箱里的 AI 带不了凭据),所以安全性完全依赖“外部连不上这个端口”。**绝不要**把它挂到对外的 8090 上,也不要 publish 该端口。 -- `GET /p/` 是 Core 上唯一的匿名读取入口:安全性 = 22 字符随机 ID + 服务端过期(`public-files.js` 的内存表)。它**必须挂在 `auth.middleware` 之前**,未命中/过期一律 404。签发侧仍要做路径校验(`workspace_root` 前缀 + 会话表 + realpath 复核,挡 `ln -s` 外泄);未配 `public_link.base_url`(且容器 env 没给 `VIRTUAL_HOST`)则不启动签发端口:配了 `VIRTUAL_HOST`(nginx-proxy 域名 + HTTPS)时,前缀自动用 `https://<第一个域名>`,env 优先于 config.yml。 +- `GET /p/` 是 Core 上唯一的匿名入口(只有读、必须挂在 `auth.middleware` 之前,未命中/过期一律 404):安全性 = 22 字符随机 ID + 服务端过期(`public-files.js` 的内存表)。**唯一的签发入口是内置工具 `mint_public_link`**(在 core 进程内,与 Core 同属一个信任边界,不再额外监听端口),它自己做路径校验(`resolveInTask` 沙箱 + 会话表 + realpath 复核,挡 `ln -s` 外泄);未配 `public_link.base_url`(且容器 env 没给 `VIRTUAL_HOST`)时工具直接报错:配了 `VIRTUAL_HOST`(nginx-proxy 域名 + HTTPS)时,前缀自动用 `https://<第一个域名>`,env 优先于 config.yml。 - nginx-proxy 前置时**必须 `proxy_buffering off`**,否则 SSE 流被缓冲。详见 `docs/DEPLOY.md`。 - 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` 放行,生产不得设置。 @@ -268,7 +265,7 @@ stateDiagram-v2 - session 补偿:MCP 规范的 `Mcp-Session-Id` 缓存在 `server.sessionId`;过期(400 + 含 "session" 字样)自动重 initialize 后重试一次。 - 某些老服务无 `initialize` → catch `Method not found` 不阻断。 -### 5.4 `tools/executor.js` —— 内置 15 工具的派发器 +### 5.4 `tools/executor.js` —— 内置 16 工具的派发器 `HANDLERS` 是 `name → async(ctx, args) → result` 的表;`executeTool(ctx, name, args)` 按 `name` 派发;**未知名直接转发给 MCP**(若 `mcp.hasTool(name)`,调 `mcp.callTool`)。 @@ -279,6 +276,7 @@ stateDiagram-v2 | `list_directory` / `create_directory` / `delete_path` / `move_path` / `copy_path` / `find_path` / `grep` | 标准文件操作,全部 `resolveInTask` 约束;`grep` 走 `ripgrep`(`rg`)优先 | | `terminal` | **唯一一个走 executor 的内置工具**(当 `rexec.isRemote(cfg)`);本地分支用 `spawn` + `detached` + 进程组 kill;远端分支 `rexec.run` SSE 收流,结果套上超时/截断/取消注解后 `truncate(text, cfg.terminal.max_output_chars)` 返回 | | `fetch` | `AbortController` + UA + redirect + content-type 简单判断;HTML 用 `htmlToMarkdown` 转 | +| `mint_public_link` | **唯一的 mint 入口**:与 core 同进程,直接 `publicFiles.mint()`,不绕任何 HTTP;`ctx.taskDir` 就是会话目录,`relOf` 的结果正是取用侧要的 `rel`。校验:`public_link.base_url` 已配 + `resolveInTask` 沙箱 + 确认是文件 + `realpath` 未沿符号链接跳出任务目录;返回单行 URL | | `list_skills` / `get_skill_info` / `run_skill` | 委托 `tools/skills.js` | `resolveInTask(taskDir, relOrAbs)`:把相对路径或绝对路径解析为绝对路径并校验落在 `taskDir` 之内(含根),防穿越。 diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md index 04d809c..3a99869 100644 --- a/docs/DEPLOY.md +++ b/docs/DEPLOY.md @@ -133,14 +133,13 @@ docker compose logs -f agent-core # 看到 "Agent server listening on 8090" 所以必须有一条公网匿名可达的 URL。做法是给一个**不透明短 ID**(`app/server/public-files.js`): 22 字符随机串,服务端内存表记着它对应哪个会话的哪个文件、什么时候过期。 -AI 拿链接的姿势:core 额外在**内网**监听一个**不映射到宿主机**的端口(`PUBLIC_LINK_PORT`,默认 8081), -上面只有一条签发接口。因为压根没 publish,外部连不上,所以它**不需要任何凭据**: +AI 拿链接的姿势:直接调内置工具 `mint_public_link`(只传文件名),core 在进程内签好并把 URL 当 +工具结果返回。没有任何额外的 HTTP 签发端口,也不存在“AI 的命令带不了凭据”这个问题: -```bash -# AI 在 executor 沙箱里执行(路径就是它平时看到的那个绝对路径) -curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/_cgi-bin_..._d92292d.jpg" -# → http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn -# stdout 就是现成 URL(约 50 字符、纯 ASCII),直接当 image_url 用 +``` +mint_public_link({ path: "_cgi-bin_..._d92292d.jpg" }) +→ http://124.221.199.237:8090/p/9fQ2mZ7xK4tR1vBn + 返回的就是现成 URL(约 50 字符、纯 ASCII),直接当 image_url 用 ``` ``` @@ -154,8 +153,8 @@ curl -s "http://agent-core:8081/public-link?path=/workspace/tasks/<会话>/_cgi- > 满是 `%XX`)。而这条 URL 会被模型抄进工具参数、并且**永久留在会话历史里每轮重发**, > 太长又难抄,还白烧 token。短 ID 把三个问题一次解决了。 -- 必须在 `config.yml` 配 `public_link.base_url = "http://<服务器IP>:8090"`;不配则不启动签发端口, - video_gen 的工具描述里也不会出现那条命令(它会退化成“请运维配 PUBLIC_LINK_URL”)。 +- 必须在 `config.yml` 配 `public_link.base_url = "http://<服务器IP>:8090"`;不配则 `mint_public_link` 直接报错 + (需要公网 URL 的那部分功能就用不了,例如 video_gen 拉不到参考图)。 例外:容器 env 里配了 `VIRTUAL_HOST`(nginx-proxy 域名 + HTTPS 那套)时,前缀自动用 `https://<域名>`, 不用改 `config.yml`(改也盖不住它)。 - 链接有效期 `public_link.ttl_ms`,默认 30 分钟;签完尽快用掉。 diff --git a/scripts/init.sh b/scripts/init.sh index 9395f1e..177268f 100755 --- a/scripts/init.sh +++ b/scripts/init.sh @@ -295,8 +295,9 @@ if [ "$UP" = "1" ]; then echo info "看日志: docker compose logs -f agent-core" if [ -d "$MCP_DIR" ]; then - info "自检(期望 400 缺 path 参数,说明签发链路通了):" - info " docker exec mcp_video_gen node -e \"fetch('http://agent-core:8081/public-link').then(async r=>console.log(r.status, await r.text()))\"" + info "自检(期望 404,说明公网取用入口 /p/ 已挂上):" + info " docker exec mcp_video_gen node -e \"fetch('http://agent-core:8090/p/selfcheck').then(async r=>console.log(r.status, await r.text()))\"" + info "签发本身已内置为工具 mint_public_link(AI 传文件名即可拿链接),不再需要 curl 内网端口。" fi info "注意:安全组/防火墙需放行 ${AGENT_PORT}(mcp 各服务都不映射宿主机端口)" fi