新增内置工具 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
+1 -1
View File
@@ -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/<id>`——由 AI 在内网 `curl http://agent-core:8081/public-link?path=…` 现签(签发端口不映射宿主机,所以不需要凭据),见 `docs/DEPLOY.md` 第 4.1 节。
**对外只开这一个端口**(executor 与 mcp 服务都不映射宿主机)。其中一条是反向入站:外部服务(如智谱)生成视频前要拉参考图,走的是 core 的匿名短链 `GET /p/<id>`——由 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`。
+1 -1
View File
@@ -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)
+4 -4
View File
@@ -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/<id> 取文件。
# 全程不监听额外端口、不搬字节(文件始终在任务目录里)。
# base_url 填本服务的对外地址(就是浏览器访问的 http://<服务器IP>:<AGENT_PORT>),只用于拼绝对地址;
# 留空 = 该功能整体关闭(对应 MCP 服务里需要公网 URL 的那部分就用不了)。
# 留空 = 该功能整体关闭(mint_public_link 会直接报错,对应 MCP 服务里需要公网 URL 的那部分就用不了)。
# 容器 env 里配了 VIRTUAL_HOST(nginx-proxy 域名 + HTTPS 那套)时,本项会被它盖住:链接前缀直接用
# https://<第一个域名>,不需要改这里(也避开了“重跑 init 脚本又把它写回 ip:port”的麻烦)。
public_link:
+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,
+2 -2
View File
@@ -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/<id>(见 public_link):AI 调内置工具
# mint_public_link 在 core 进程内现签短链,不需要 executor 反查 core 的额外端口
agent-mcp-net:
name: agent-mcp-net
driver: bridge
+7 -9
View File
@@ -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/<id> 公网临时文件取用(匿名)
│ │ │ └── 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/<id>`(匿名,22 字符随机 ID + 服务端过期,见 `routes/public-files.js`);这个 id 由内网
签发入口 `GET /public-link` 现签,所以链接里既没有会话名也没有文件名。
`GET /p/<id>`(匿名,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>` 短 ID。前者需要在 URL 末段带文件名(给安卓下载器猜名),后者刻意不带文件名/会话名。
- **`routes/public-link.js` 只挂在【不映射宿主机】的内网端口上**(`PUBLIC_LINK_PORT`,默认 8081):它不需要凭据(沙箱里的 AI 带不了凭据),所以安全性完全依赖“外部连不上这个端口”。**绝不要**把它挂到对外的 8090 上,也不要 publish 该端口。
- `GET /p/<id>` 是 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/<id>` 是 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` 之内(含根),防穿越。
+8 -9
View File
@@ -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 分钟;签完尽快用掉。
+3 -2
View File
@@ -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/<id> 已挂上):"
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