tako 文档 GitHub

19v6-08 · 文件工具族(F 系列)

立项(2026-10-11 交审):T 系列(19v6-05)延拍。把 fileOps 目录名单(19v6-07 §5) 从「lint 对照表上的纸面名字」落成第一方真工具。本文是 F 系列的机制与契约真源; 施工台账在 tmp/19-v6/filetools/;冲突以本文为准、回头改台账。

2026-10-20:文件工具新增 read_pdf_text(doc/32 A8-1)。 fileEffectToolNames 那份目录名单不变。read_pdf_text 只登记 firstPartyFileEffects,不进那份名单。 2026-10-20 A8-2:页码超出、无文本层、加密或损坏、非 PDF,都降级成正常结果或「错误:…」,run 继续。TAKO_MEDIA_SEND=off 时这把工具仍可读。PDF 正文里印着的回执行不附图。 2026-10-22:同文件并发写底座落地(filefp.go)——write_file 的「先读后写」纪律、 edit_file 的现读带过、write_file/edit_file/move_file 的 flock 写锁。成功体与既有错误 分支不变;新增的拒绝是工具结果文本(走既有 wrapToolErrors 通道),不是 HTTP 业务码。 机制与边界见 doc/42 §2.4,施工台账 tmp/文件写入并发/。 2026-11-01(doc/58):读工具改成分页——入参换成 offset?/limit?(head/tail 删掉), 一次一页(2000 行 / 50KB / 单行 2000 字符),每次追加一行页脚;「>200KB 且无 head/tail」 那条错误分支撤掉(大文件照样分页读)。bash 侧同期改成留尾 + 全文落盘 + 回路径 (.tako/bash/<runId>/<seq>.out,每流 64,000 字节尾窗 / 64MB 落盘上限、保留 30 天), 机制与出处见 doc/58。

§0 立项由来:两个「空转」等这拍转正

背景故事(病灶):C5-A4 落成了 fileOps 提取器 + 启动 lint(19v6-07 §5),但今天它们都在 对空气工作——firstPartyFileEffects 是张空表,lint 拿空表跑恒过;提取器的「注册表声明位」 分支(判定 ①)从没吃到过真声明,因为池内唯一的工具 get_time 不碰文件。同时模型手里 没有一只能读写工作区的手:想让它存个文件,它只能把内容喷在回复正文里。

「把这些工具落地」同时解开三件事:

  1. lint 转正:注册表第一次非空、且每个文件工具都带 file_effect 声明 → lint 从 空转变成真检查(漏声明 = 启动失败)。
  2. 提取器转正:真 tool_calls 带真声明进来 → 折叠时「改过/读过」清单第一次出现真路径, C5-A5 的 file-ops 块有东西可钉。
  3. 模型长手:工作区内读写文件成为模型可用的动作,防重建保险丝(19v6-07 §5 的 WeKnora 战例)有了真实用武之地。

§1 范围与非目标

范围内:目录名单里的名字全部落地为第一方工具(read_text_file、read_media_file、 write_file、edit_file、move_file、create_directory、list_directory、 directory_tree、get_file_info、search_files、read_file),逐个带 file_effect 声明进注册表,受启动 lint 管辖。2026-10-20 起文件工具另增加 read_pdf_text。 它不在目录名单里,启动 lint 不拿它做「名单内必须声明」的对照;firstPartyFileEffects 给它登记 read,父池在 read_media_file 之后装配。

明确不做(本节登记,未来用例逼出再立项):

§2 workspace 与路径约束

所有文件工具只在 workspace 根内作业。这不是体验决定,是事故防线:

§3 工具契约表(v1)

通用约定:

工具 声明 入参(JSON) 返回文本(成功) 错误分支
write_file write path,content 已写入 <path>(<n> 字节) 越界;没读过就写(覆盖已存在文件前必须先 read_file);内容与读到的不一致(被 bash 或另一个 agent 改过);读过但文件已没了(被删/被移走);拿不到写锁(30s 内被占)
read_text_file read path,offset?(起始行,1-based,默认 1),limit?(本次最多读多少行,默认 2000、上限 2000) 文件文本原文(纯文本直出)+ 空行 + 一行页脚(doc/58 §3.2 三态:还有更多 / 被 50KB 截断 / 读完了) 不存在;是目录;offset 非正整数;limit 非正整数或 >2000;offset 超出文件末尾
edit_file edit path,old_text,new_text,replace_all?(默认 false) 已编辑 <path>(替换 n 处) 越界;old_text 找不到;多处出现且未置 replace_all;拿不到写锁
read_file read 同 read_text_file 同 read_text_file 同
move_file edit path(源),destination 已移动 <path> → <destination> 越界(任一端);目标已存在(不覆盖)
create_directory write path 已建目录 <path>(已存在 = 幂等成功,返回「已存在」) 越界
list_directory read path 每行一个条目,目录以 / 结尾,按名排序,不含 ./..;空目录返回 (空目录) 越界;不是目录
directory_tree read path,depth?(默认 3,上限 5) 缩进树(两空格一级),目录以 / 结尾;超深处标 …;节点上限 500、超出标 (已截断) 越界;不是目录
get_file_info read path 四行:size: <n> 字节 / modified: <RFC3339> / mode: <-rw-r--r--> / type: 文件|目录 越界;不存在
search_files read path(起始目录),query(固定子串),file_glob?(如 *.go) 命中行 relpath:行号:行内容,上限 50 条、超出标 (更多命中已省略);单文件 >1MB 跳过 越界;不是目录
read_media_file read path 单行 [media path=… mime=… size=…B sha=…;已按路径读取。媒体字节不会写入对话记录,请勿重复调用](doc/32 A2/A3-2) 越界;不存在;>5MB(提示太大)
read_pdf_text read path,page_from?,page_to? 页眉 [pdf path=… pages=N;第 a-b 页;文本层抽取],随后 --- page N --- 与该页文本。默认第 1-3 页,单次最多 10 页、16KB。扫描件与页码超出是正常结果 越界;不存在;不是 .pdf;不是普通文件;>5MB;加密或损坏

语义裁定:

§4 装配与登记

§5 与 fileOps / C5 的咬合

§6 挂账