feat(tools): read_file 支持 @<sid>/<rel> 只读窥看历史会话文本
查看可过墙、字节落地仍只走 copy_path:复用 resolvePastPath 校验单点(形状/存在/同用户/沙箱), 历史图片直接拒绝并引导 copy_path(签外链必须经本会话,不做藏进 .imgcache 的偷偷导入); 写侧 write_file/edit_file 显式拒 @,definitions.json 与 ARCHITECTURE.md 同步该不变量。
This commit is contained in:
@@ -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 '@<session-id>/<rel>' 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 '@<session-id>/<rel>' 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 '@<session-id>/<rel>' 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. '@<session-id>/<rel>' 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",
|
||||
|
||||
@@ -38,11 +38,14 @@ function relOf(taskDir, abs) {
|
||||
return path.relative(path.resolve(taskDir), abs) || '.';
|
||||
}
|
||||
|
||||
// ---------- 跨会话路径:@<会话id>/<rel>(历史只读,数据过墙只走 copy_path 一道门) ----------
|
||||
// ---------- 跨会话路径:@<会话id>/<rel>(历史只读,「看一眼」可过墙,「字节落地」只走 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 头,历史行为不变);历史会话只暴露 @<sid>/<rel> 形,
|
||||
// 不把别的会话的 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:普通复制 + 历史成果的唯一进口。源可 '@<sid>/<rel>'(同用户校验在 resolvePastPath);
|
||||
// 目标永不接受 @——历史只读、写只进本会话,「导入后文件即本地」让 read_file/vision/mint 全量生效,
|
||||
// 不必给它们开跨墙特例。撞名拒绝覆盖(保用户现作)。
|
||||
// copy_path:普通复制 + 历史成果的唯一「落地」进口。源可 '@<sid>/<rel>'(同用户校验在 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); }
|
||||
|
||||
@@ -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` 可 `@<sid>/<rel>` 只读窥看同用户历史会话的文本(校验单点 `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 复活并加 `@<session-id>/<rel>` 只读记号:当年删除理由是「环境固定,统一走 terminal」,但生产 terminal 在远端 executor 容器(compose:wrapper 启动即 unmount host-tasks),其他会话目录在 shell 物理视图里不存在——跨会话取旧成果只剩 core 进程一个口子。校验单点 `resolvePastPath`(形状+存在+同用户,承自 recall 旧 files/link);list_directory 单层 ls(≤200 条、隐藏项不列,@ 模式条目带 '@<sid>/' 全形前缀可直接抄进 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 复活并加 `@<session-id>/<rel>` 只读记号:当年删除理由是「环境固定,统一走 terminal」,但生产 terminal 在远端 executor 容器(compose:wrapper 启动即 unmount host-tasks),其他会话目录在 shell 物理视图里不存在——跨会话取旧成果只剩 core 进程一个口子。校验单点 `resolvePastPath`(形状+存在+同用户,承自 recall 旧 files/link);list_directory 单层 ls(≤200 条、隐藏项不列,@ 模式条目带 '@<sid>/' 全形前缀可直接抄进 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 样板词启发式丢块,`<title>` 提成首行);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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user