新增内置工具 mint_public_link,退役内网签发端口 8081

- mint_public_link:AI 只传文件名,core 在进程内直接 publicFiles.mint() 签出短命公网链接,返回单行 URL;校验 = base_url 已配 + resolveInTask 沙箱 + 确认是文件 + realpath 未跳出任务
目录

    - 删除 routes/public-link.js 与 server.js 里的签发端口(PUBLIC_LINK_PORT/8081):该接口对 AI 已冗余(进程内签发不绕 HTTP,也不存在带不了凭据的问题);public_link 配置项收窄为 mint_public_link 的开关,不再监听额外端口

    - 跟进:definitions.json/HANDLERS 注册;config.example.yml、config.js、public-files.js、download-token.js、routes/files.js 注释;ARCHITECTURE(目录树/部署图/关键约束/5.4 工具表)、DEPLOY 4.1、init.sh 自检改探 /p/<id>、两个 README(工具数 16、公网链接说明)

    - 注:docker-compose.yml 一并带上此前工作区的 VIRTUAL_HOST/my-app-network 改动
This commit is contained in:
2026-09-17 20:12:56 +08:00
parent ec587480d6
commit b65485b7e5
16 changed files with 79 additions and 130 deletions
+3 -3
View File
@@ -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 },
};
+3 -3
View File
@@ -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;
}
+2 -1
View File
@@ -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';
+2 -2
View File
@@ -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> 是另一套机制:短 ID + 内存表,见 ../public-files.js。)
const DOWNLOAD_TOKEN_TTL_MS = downloadToken.BROWSER_TTL_MS;
const signDownloadToken = downloadToken.signDownload;
const validDownloadToken = downloadToken.validDownload;
+1 -1
View File
@@ -1,4 +1,4 @@
// 公网临时文件的取用端点:GET /p/<id>(id 由 routes/public-link.js 在内网现签)。
// 公网临时文件的取用端点:GET /p/<id>(id 由内置工具 mint_public_link 在 core 进程内现签)。
//
// 这一跳的访问者是**外部服务**(如智谱服务器来拉参考图),它不带 cookie、不带 Authorization,
// 所以必须匿名可达。安全性完全来自:
-73
View File
@@ -1,73 +0,0 @@
// 公网临时链接签发(只在【内网监听】的端口上,见 server.js 里 PUBLIC_LINK_PORT 那段)。
//
// 用途:把任务目录里的文件变成一条短命的公网 URL,交给外部服务去取。第一个消费者是
// MCP video_gen:智谱服务器生成视频前要自己来拉参考图,它不带 cookie、不带 Authorization,
// 所以必须给它一条「不可猜 + 会过期」的链接。
// 产出的形态是一个不透明短 ID(见 public-files.js 为什么不用签名 URL):
// http://<IP>: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;
+1 -19
View File
@@ -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,
// 宿主机对应 <repo>/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(', '));
+17
View File
@@ -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": {
+24
View File
@@ -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/<id> 取用)。
// 这是唯一的签发入口:与 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,