From 46867f8274f7298ca2f9d3e4c053425caf775dcb Mon Sep 17 00:00:00 2001 From: kicer Date: Mon, 5 Oct 2026 07:29:15 +0800 Subject: [PATCH] =?UTF-8?q?feat(tools):=20read=5Ffile=20=E6=94=AF=E6=8C=81?= =?UTF-8?q?=20@/=20=E5=8F=AA=E8=AF=BB=E7=AA=A5=E7=9C=8B=E5=8E=86?= =?UTF-8?q?=E5=8F=B2=E4=BC=9A=E8=AF=9D=E6=96=87=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 查看可过墙、字节落地仍只走 copy_path:复用 resolvePastPath 校验单点(形状/存在/同用户/沙箱), 历史图片直接拒绝并引导 copy_path(签外链必须经本会话,不做藏进 .imgcache 的偷偷导入); 写侧 write_file/edit_file 显式拒 @,definitions.json 与 ARCHITECTURE.md 同步该不变量。 --- app/server/tools/definitions.json | 10 +++---- app/server/tools/executor.js | 50 ++++++++++++++++++++++++------- docs/ARCHITECTURE.md | 5 ++-- 3 files changed, 47 insertions(+), 18 deletions(-) diff --git a/app/server/tools/definitions.json b/app/server/tools/definitions.json index 142d4e1..b68c509 100644 --- a/app/server/tools/definitions.json +++ b/app/server/tools/definitions.json @@ -3,7 +3,7 @@ "type": "function", "function": { "name": "copy_path", - "description": "Copies a file or directory, preserving the original; directories are copied recursively. More efficient than reading then writing contents. Returns confirmation with the destination path.\n\nImport past work: source_path accepts '@/' to copy from your OWN past session (find the id with recall, browse with list_directory). destination_path never accepts '@' - past stays read-only, imports land in the current session directory. The destination must not exist yet; nothing is overwritten.\n\nAfter import the file is fully local: read_file (images included), terminal, mint_public_link all work on it.\n\nLimits: max 200 MB / 200 files per call; symlinks refused.", + "description": "Copies a file or directory, preserving the original; directories are copied recursively. More efficient than reading then writing contents. Returns confirmation with the destination path.\n\nImport past work: source_path accepts '@/' to copy from your OWN past session (find the id with recall, browse with list_directory). destination_path never accepts '@' - past stays read-only, imports land in the current session directory. The destination must not exist yet; nothing is overwritten.\n\nAfter import the file is fully local: read_file (images included), terminal, mint_public_link all work on it. You can peek a past text file without importing (read_file takes the same '@' form); importing is what makes it workable (terminal, edit_file, images).\n\nLimits: max 200 MB / 200 files per call; symlinks refused.", "parameters": { "type": "object", "required": [ @@ -83,7 +83,7 @@ "properties": { "path": { "type": "string", - "description": "Path of the file to edit, relative to the session working directory. Absolute paths are also accepted." + "description": "Path of the file to edit, relative to the session working directory. Absolute paths are also accepted. '@' paths are rejected here — copy a past file in with copy_path first." }, "edits": { "type": "array", @@ -253,7 +253,7 @@ "type": "function", "function": { "name": "read_file", - "description": "Reads the content of a file.\n\nText files: each returned line is prefixed with a line number right-aligned in a 6-character field, followed by a tab, then the line content.\n\nLarge text files (roughly over 16 KB) are not returned in full: you get an outline listing top-level symbols (or Markdown headings) with line numbers instead. The outline IS a successful response — do NOT retry the same call without a line range; use the outline line numbers with `start_line` / `end_line` to read specific sections. If no outline can be extracted, a first-1KB excerpt is returned instead. Supplying `start_line` or `end_line` disables outline mode.\n\nImage files (PNG, JPEG, WebP, GIF, BMP, TIFF) are returned as visual content you can analyze directly, but only if the current model supports vision; otherwise a text placeholder is returned — that placeholder is not an error. The tool result itself carries a text notice only; the actual image pixels arrive in a separate user message right after the batch of tool results: that message lists per-image labels matching each image to its read_file receipt, then the image blocks in receipt order, and asks you to briefly describe each image before continuing. Never re-read an image already delivered in the current turn; if pixels never arrive, tell the user instead of retrying. Very large images (roughly over 50 MB) are skipped, and images may be downscaled (long edge ~2000 px, re-encoded as JPEG) before being returned.\n\nBinary files are not returned as text; a short notice is returned instead. Text files over 32 MB cannot be read by this tool — use `terminal` (grep -n / head / sed -n).", + "description": "Reads the content of a file.\n\nText files: each returned line is prefixed with a line number right-aligned in a 6-character field, followed by a tab, then the line content.\n\nCross-session peek: `path` accepts '@/' to read a text file from your OWN past session, read-only (find the id with recall op=search, browse with list_directory). It is a look, not an import: nothing lands in your session directory, so `terminal`, grep and `edit_file` cannot see it, and past images are refused. When you need to work with a file or view a past image, `copy_path` it first (its `source_path` takes the same '@' form). '@' is never accepted by `write_file` or `edit_file`.\n\nLarge text files (roughly over 16 KB) are not returned in full: you get an outline listing top-level symbols (or Markdown headings) with line numbers instead. The outline IS a successful response — do NOT retry the same call without a line range; use the outline line numbers with `start_line` / `end_line` to read specific sections. If no outline can be extracted, a first-1KB excerpt is returned instead. Supplying `start_line` or `end_line` disables outline mode.\n\nImage files (PNG, JPEG, WebP, GIF, BMP, TIFF) are returned as visual content you can analyze directly, but only if the current model supports vision; otherwise a text placeholder is returned — that placeholder is not an error. The tool result itself carries a text notice only; the actual image pixels arrive in a separate user message right after the batch of tool results: that message lists per-image labels matching each image to its read_file receipt, then the image blocks in receipt order, and asks you to briefly describe each image before continuing. Never re-read an image already delivered in the current turn; if pixels never arrive, tell the user instead of retrying. Very large images (roughly over 50 MB) are skipped, and images may be downscaled (long edge ~2000 px, re-encoded as JPEG) before being returned.\n\nBinary files are not returned as text; a short notice is returned instead. Text files over 32 MB cannot be read by this tool — use `terminal` (grep -n / head / sed -n).", "parameters": { "type": "object", "required": [ @@ -262,7 +262,7 @@ "properties": { "path": { "type": "string", - "description": "Path of the file to read, relative to the session working directory. Absolute paths are also accepted." + "description": "Path of the file to read, relative to the session working directory. Absolute paths are also accepted. '@/' reads a same-user past session's file (text only; past images need copy_path first)." }, "start_line": { "type": "integer", @@ -457,7 +457,7 @@ "properties": { "path": { "type": "string", - "description": "Path of the file to create or overwrite, relative to the session working directory. Absolute paths inside the working directory are also accepted." + "description": "Path of the file to create or overwrite, relative to the session working directory. Absolute paths inside the working directory are also accepted. '@' paths are rejected here — the past is read-only." }, "content": { "type": "string", diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index e0f5fd6..baa20b2 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -38,11 +38,14 @@ function relOf(taskDir, abs) { return path.relative(path.resolve(taskDir), abs) || '.'; } -// ---------- 跨会话路径:@<会话id>/(历史只读,数据过墙只走 copy_path 一道门) ---------- +// ---------- 跨会话路径:@<会话id>/(历史只读,「看一眼」可过墙,「字节落地」只走 copy_path) ---------- // 背景:terminal 在远端 executor 容器里跑(compose:wrapper 启动即 unmount host-tasks), // 别的会话目录在 shell 物理视图里根本不存在;core 进程内的文件工具又被 resolveInTask -// 锁死本会话。跨会话取旧成果只剩这一个口子,同用户校验单点在此(承自 recall 旧 files/link, +// 锁死本会话。跨会话只有这一个解析口子,同用户校验单点在此(承自 recall 旧 files/link, // 那两个 op 是 ls/mint 的沙箱外克隆,已整删——克隆会漂移:link 漏抄 mint 的 realpath 防线)。 +// 接受 @ 的三个入口都是只读语义:list_directory(列举)、read_file(读文本进上下文)、 +// copy_path 的 source_path(导入)。写侧 write_file / edit_file / copy_path 目标一律显式拒绝, +// 否则 '@task-x/y' 会被 resolveInTask 当相对路径、在本会话里造出字面 '@task-x' 目录。 const PAST_RE = /^@([^\s/]+)(?:\/([\s\S]*))?$/; function resolvePastPath(ctx, p) { const m = PAST_RE.exec(p); @@ -211,12 +214,34 @@ async function readImageAsBlocks(ctx, abs, rel, size) { } async function toolReadFile(ctx, args) { - const abs = resolveInTask(ctx.taskDir, args.path); + const p = typeof args.path === 'string' ? args.path.trim() : ''; + const isPast = p.startsWith('@'); + let abs; let disp; + if (isPast) { + // 历史会话只读「看一眼」:形状/存在/同用户/沙箱校验全在 resolvePastPath,与另两个 @ 入口同源。 + // 字节不落本会话 → terminal/grep/edit_file 看不见它;图片在此拒绝(见下),要干活仍须 copy_path。 + const past = resolvePastPath(ctx, p); + abs = past.abs; + const inner = relOf(past.dir, abs); + disp = inner === '.' ? '@' + past.sid : '@' + past.sid + '/' + inner; + } else { + abs = resolveInTask(ctx.taskDir, args.path); + // 本会话沿用绝对路径做展示(大纲/首 1KB 头,历史行为不变);历史会话只暴露 @/ 形, + // 不把别的会话的 workspace_root 绝对路径喂进上下文。 + disp = abs; + } let st; try { st = await fsp.stat(abs); } - catch (_) { throw new Error('文件不存在:' + args.path); } - if (st.isDirectory()) throw new Error(args.path + ' 是目录不是文件,用 list_directory 查看。'); + catch (_) { throw new Error('文件不存在:' + p); } + if (st.isDirectory()) throw new Error(p + ' 是目录不是文件,用 list_directory 查看。'); if (IMAGE_EXTS.has(path.extname(abs).toLowerCase())) { + if (isPast) { + // 不做「偷偷复制」:图片要出现在模型视野里,字节必须落到本会话才能签外链(engine 的 + // mintImageUrl 与前端下载路由都以当前 taskDir 为根),那本质已是一次导入——与其藏进 + // .imgcache 不进文件表,不如让模型明确知道历史图片必须先 copy_path。 + return '[图片文件] ' + disp + '(' + st.size + ' 字节)历史会话图片不支持直接读取。' + + '图片需要先 copy_path(source_path 用这个 @ 路径)导入本会话,再 read_file——导入后图片、terminal、mint 全量生效。'; + } const rel = relOf(ctx.taskDir, abs); if (!ctx.vision) { return '[图片文件] ' + rel + '(' + st.size + ' 字节)。图片文件,当前模型不支持视觉识别,无法回传图片内容。'; @@ -226,7 +251,7 @@ async function toolReadFile(ctx, args) { } return await readImageAsBlocks(ctx, abs, rel, st.size); } - if (isProbablyBinary(abs)) return '[二进制文件,跳过文本读取] ' + relOf(ctx.taskDir, abs); + if (isProbablyBinary(abs)) return '[二进制文件,跳过文本读取] ' + (isPast ? disp : relOf(ctx.taskDir, abs)); if (st.size > TEXT_FULL_READ_CAP) { return '(文件过大:' + Math.round(st.size / 1048576) + ' MB,超过 read_file 全文读取上限 ' + (TEXT_FULL_READ_CAP / 1048576) + ' MB,拒绝整读;请用 terminal 的 grep -n / head / sed -n 定位阅读)'; @@ -244,11 +269,11 @@ async function toolReadFile(ctx, args) { if (endLine < startLine) throw new Error('end_line 必须 >= start_line(got start_line=' + startLine + ', end_line=' + args.end_line + ')'); // 对齐 Zed:未指定范围且文件超过 16KB 时返回大纲;提取不到大纲则回退回首 1KB。 if (!args.start_line && !args.end_line && Buffer.byteLength(text, 'utf8') > AUTO_OUTLINE_SIZE) { - const outline = buildOutline(abs, text); + const outline = buildOutline(disp, text); if (outline) return outlineWrapper(outline); let head = text.slice(0, 1024); try { while (Buffer.byteLength(head, 'utf8') > 1024) head = head.slice(0, -1); } catch (_) {} - return outlineWrapper('# First 1KB of ' + abs + ' (file too large to show full content, and no outline available)\n\n' + head); + return outlineWrapper('# First 1KB of ' + disp + ' (file too large to show full content, and no outline available)\n\n' + head); } lines = lines.slice(startLine - 1, Math.min(endLine, total)); return lines.map((l, i) => String(startLine + i).padStart(6, ' ') + '\t' + l).join('\n'); @@ -301,9 +326,10 @@ async function toolListDirectory(ctx, args) { return out; } -// copy_path:普通复制 + 历史成果的唯一进口。源可 '@/'(同用户校验在 resolvePastPath); -// 目标永不接受 @——历史只读、写只进本会话,「导入后文件即本地」让 read_file/vision/mint 全量生效, -// 不必给它们开跨墙特例。撞名拒绝覆盖(保用户现作)。 +// copy_path:普通复制 + 历史成果的唯一「落地」进口。源可 '@/'(同用户校验在 resolvePastPath); +// 目标永不接受 @——历史只读、写只进本会话。「导入后文件即本地」仍是完整能力的前提: +// terminal/grep 检索、edit_file 修改、vision 回图、mint 外链都只对本地文件生效(read_file 可只读 +// 窥看历史文本,但不落盘,替代不了导入)。撞名拒绝覆盖(保用户现作)。 async function toolCopyPath(ctx, args) { const sp = String(args.source_path || '').trim(); const dp = String(args.destination_path || '').trim(); @@ -345,6 +371,7 @@ async function toolCopyPath(ctx, args) { } async function toolWriteFile(ctx, args) { + if (String(args.path || '').trim().startsWith('@')) throw new Error('write_file 不支持 @ 路径(历史只读;要改旧成果先 copy_path 导入本会话)'); const abs = resolveInTask(ctx.taskDir, args.path); // 纵深防御:引擎 checkToolArgs 已把 null 判缺,但直调 executor(测试等)不经过它; // 旧版 `?? ''` 会把 null 洗成空串静默清空已有文件,这里显式拒绝。 @@ -585,6 +612,7 @@ function applyEdit(text, edit, i) { // 对齐 Zed:edits 顺序应用到内存态;若第 N 条失败,前 N-1 条仍保存落盘, // 错误信息告知模型已应用了多少、需重新 read_file。 async function toolEditFile(ctx, args) { + if (String(args.path || '').trim().startsWith('@')) throw new Error('edit_file 不支持 @ 路径(历史只读;要改旧成果先 copy_path 导入本会话)'); const abs = resolveInTask(ctx.taskDir, args.path); let st; try { st = await fsp.stat(abs); } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 3adda8e..da635dd 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -334,9 +334,9 @@ stateDiagram-v2 | 工具 | 实现要点 | |---|---| -| `read_file` | 走 `resolveInTask` 防路径穿越;图像(PNG/JPEG/WebP/GIF/BMP/TIFF)按 vision 能力走 `sharp` 压缩后落盘 `.imgcache/` 并回传 `image_rel`(长边 ≤ 2000px,JPEG q=80;文件名带源文件 mtime+size 指纹,重读复用不增殖;重编码无收益时不落盘、直指原文件),发送前由 `llm.buildMessages` 现签成公网外链(engine 侧 mint 前 realpath 复核);大文本/二进制给 outline,超 32MB 拒读并引导 terminal;行号前缀格式 "`<6位右对齐行号>\\t<原文>`"(`edit_file` 用) | +| `read_file` | 走 `resolveInTask` 防路径穿越;图像(PNG/JPEG/WebP/GIF/BMP/TIFF)按 vision 能力走 `sharp` 压缩后落盘 `.imgcache/` 并回传 `image_rel`(长边 ≤ 2000px,JPEG q=80;文件名带源文件 mtime+size 指纹,重读复用不增殖;重编码无收益时不落盘、直指原文件),发送前由 `llm.buildMessages` 现签成公网外链(engine 侧 mint 前 realpath 复核);大文本/二进制给 outline,超 32MB 拒读并引导 terminal;`path` 可 `@/` 只读窥看同用户历史会话的文本(校验单点 `resolvePastPath`,与 list_directory/copy_path 同源)——字节不落本会话,terminal/edit_file 看不见它,历史图片直接拒绝并引导 copy_path(图片进模型视野必须经本会话签外链,藏进 .imgcache 等于偷偷导入);行号前缀格式 "`<6位右对齐行号>\\t<原文>`"(`edit_file` 用) | | `write_file` / `edit_file` | `edit_file` 用模糊定位(Zed 风格):先精确匹配,失败后用 Levenshtein DP 找最相似行;超 32MB 拒绝整文件读写(OOM 防护);DP 候选区间不连续(中间跳过无关 buffer 行)即弃用,防静默吞行;空 `new_text` = 整行干净删除(精确/模糊两层统一,对齐 `"".lines()` 零行语义);`old_text`/`new_text` 协议见 `definitions.json` | -| 已移除的工具(部分复活) | `list_directory` / `copy_path` 于 2026-09 复活并加 `@/` 只读记号:当年删除理由是「环境固定,统一走 terminal」,但生产 terminal 在远端 executor 容器(compose:wrapper 启动即 unmount host-tasks),其他会话目录在 shell 物理视图里不存在——跨会话取旧成果只剩 core 进程一个口子。校验单点 `resolvePastPath`(形状+存在+同用户,承自 recall 旧 files/link);list_directory 单层 ls(≤200 条、隐藏项不列,@ 模式条目带 '@/' 全形前缀可直接抄进 copy_path);copy_path 源可 @、目标拒 @(历史只读,导入落本会话后 read_file/vision/mint 全量生效,不给存量工具开跨墙特例),预算 200 文件/200MB,符号链接拒收防逃逸(mint 同款防线)。同批拆除 recall 的 files/link 两 op(沙箱外克隆必漂移:link 漏抄 mint 的 realpath 防线),recall 收敛为纯记忆 search/days/day。仍移除:`create_directory` / `delete_path` / `move_path` / `find_path` / `grep`(写删检索继续走 terminal);17→10 大盘不变,复活两件+后续 db/profile → 现 15 项 | +| 已移除的工具(部分复活) | `list_directory` / `copy_path` 于 2026-09 复活并加 `@/` 只读记号:当年删除理由是「环境固定,统一走 terminal」,但生产 terminal 在远端 executor 容器(compose:wrapper 启动即 unmount host-tasks),其他会话目录在 shell 物理视图里不存在——跨会话取旧成果只剩 core 进程一个口子。校验单点 `resolvePastPath`(形状+存在+同用户,承自 recall 旧 files/link);list_directory 单层 ls(≤200 条、隐藏项不列,@ 模式条目带 '@/' 全形前缀可直接抄进 copy_path);copy_path 源可 @、目标拒 @(历史只读,导入落本会话后 read_file/vision/mint 全量生效),预算 200 文件/200MB,符号链接拒收防逃逸(mint 同款防线);2026-10 给 read_file 开了只读窥看特例:跨墙不变量从「数据过墙只走 copy_path 一道门」放宽为「查看可过墙(list/read 文本),字节落地仍只走 copy_path」,写侧 write_file/edit_file 显式拒 @(否则 resolveInTask 会把 @ 当相对路径、在本会话造出字面 @ 目录)。同批拆除 recall 的 files/link 两 op(沙箱外克隆必漂移:link 漏抄 mint 的 realpath 防线),recall 收敛为纯记忆 search/days/day。仍移除:`create_directory` / `delete_path` / `move_path` / `find_path` / `grep`(写删检索继续走 terminal);17→10 大盘不变,复活两件+后续 db/profile → 现 15 项 | | `terminal` | **唯一一个走 executor 的内置工具**(当 `rexec.isRemote(cfg)`);本地分支用 `spawn` + `detached` + 进程组 kill;远端分支 `rexec.run` SSE 收流,结果套上超时/截断/取消注解后 `truncate(text, cfg.terminal.max_output_chars)` 返回 | | `fetch` | `AbortController` 覆盖全生命周期(响应头之后的 body 读流同样被超时/取消打断,取消用与 terminal 同款的 200ms 轮询);content-type 先行,非文本只回状态/类型/尺寸不读 body;**下载/返回双上限解耦**:流式读到 `cfg.fetch.max_bytes`(默认 1MB)即断开(下载不占上下文可宽松),返回窗默认 `max_chars`(12000)字符,模型显式传 `max_chars` 夹在 `max_chars_hard`(64000)硬帽内;超窗尾部拼 `offset` 续读提示,转换后全文缓在 `ctx.run.fetchCache`(回合级 LRU 3 条),续读纯本地切片不重抓;**SSRF 防护**:主机名解析结果含回环/私有/链路本地地址即拒(`allow_private: true` 才放行),`redirect:'manual'` 逐跳复查至多 5 次(残余风险:undici 建连时二次解析,DNS 重绑定不可根治);按响应 charset 解码(full-icu 支持 gbk/gb18030 等,未知编码退回 UTF-8);HTML 用 `htmlToMarkdown` 转(剥 script/style/head 及 nav/header/footer/aside/form 整块,class/id 样板词启发式丢块,`` 提成首行);HTML 实体单遍解码(常见命名实体+数字实体通吃,修 `&` 双重解码);字节截断切在多字节字符中时尾 U+FFFD 去噪;网络错误解包 `err.cause` 直述 ENOTFOUND/TLS 等真因,SSRF/重定向类错误带 `fetchUserError` 标记直接冒泡;engine 不截工具结果,返回值末尾另有 `truncate` 1MB 字符兜底护栏 | | `mint_public_link` | **唯一的 mint 入口**:与 core 同进程,直接 `publicFiles.mint()`,不绕任何 HTTP;`ctx.taskDir` 就是会话目录,`relOf` 的结果正是取用侧要的 `rel`。校验:`public_link.base_url` 已配 + `resolveInTask` 沙箱 + 确认是文件 + `realpath` 未沿符号链接跳出任务目录;返回单行 URL | @@ -720,6 +720,7 @@ sequenceDiagram - **所有用户可传入的路径**都必须经 `resolveInTask(taskDir, relOrAbs)` 校验落在任务目录之内(含根),不允许 `..` 穿越。 - 技能文件管理(`routes/skills.js`)走 `safeRel`(`path.posix.normalize` + 拒绝 `../` 前缀 + 拒绝绝对路径)+ `absInSkill`(解析后必须以技能目录开头)。 - `terminal` 命令的 `cd` 同样经 `resolveInTask` 校验。 +- `@<session-id>/<rel>` 是唯一的跨会话记号,解析/同用户校验单点在 `resolvePastPath`,只接三个只读入口(list_directory、read_file、copy_path 源);写侧(write_file/edit_file/copy_path 目标)显式拒 @,历史永远只读,落地只走 copy_path。 ### 12.4 异步 / DB