tako 文档 GitHub

58 · 读分页与输出留存(read 分页 + bash 留尾落盘)

性质:方案(2026-11-01 点头;五条待裁按 dsh 定)。回答「模型怎么把一份大的东西完整拿到手里」。 状态:已落地(2026-11-01,A0–A8 全部施工并验收;bash 落盘落点与清扫触发点后被 doc/82 改定——落命令目录、首字节起落盘、清理归 job sweeper,见本文 §4.1/§4.4)。read 改成 offset/limit 分页(撤 200KB 硬报错、删 head/tail);bash 改成留尾 64000 字节/流 + 全文落盘 + 回路径(30 天保留)。四条产品 API 的请求/响应字节一个没动——本篇改的是模型看见的工具结果字节。 代码落点:yk-tako-eino/internal/runengine/{readwindow.go,filetools.go,bash.go,bashspill.go,notes.go,product_api.go};快闸单测 filetools_test.go、bashspill_test.go;契约字节 scripts/acceptance/expected.json(用例 32/33)与 doc/19-v6/19v6-04-验收-curl.md(用例 32/33);契约表 doc/19-v6/19v6-08-file-tools.md §3。 验收(2026-11-01,隔离引擎 8943):go test -count=1 ./internal/runengine 全绿;assert_contract.py --tier core 125 步全过(含新增的用例 32 读分页、33 bash 输出留存);check-expected.sh 用例号集合一致;check-master-plan.sh 通过。 参照:dsh deepseek-harness(packages/fs/tool-fs/src/{read.ts,read-render.ts}、packages/shell/{bash-local,tool-bash}/src/、packages/subprocess/subprocess-local/src/output.ts、packages/spill/spill-local/src/);pi packages/coding-agent/src/core/{tools/read.ts,tools/truncate.ts,tools/output-accumulator.ts,bash-executor.ts}。 上游:doc/57(web_fetch 把整页落盘、模型自己读)——本文是它的下游:doc/57 的「落盘之后模型自己读」要成立,read 必须能分页。立项来源是 doc/56 §4.6 的那句「coding agent 该补的是『留尾 + 全文落盘 + 回路径』与『分页读』」。


0. 一句话结论

tako 今天有两处「拿不到就永远拿不到」:

  1. read_file 读超过 200KB 的文件直接报错,模型只剩 head / tail 两条路——没有任何办法读到文件中间;
  2. bash 的输出超 32KB 时留头丢尾,尾部那半(报错、失败原因、最后几行)当场销毁、不可恢复。

本篇把两处都改成「分页」与「留尾 + 全文落盘 + 回路径」: read 加 offset/limit(dsh 与 pi 各自独立同形),bash 改成留尾并把全文写到盘上、回一个可读的路径(dsh 与 pi 同形)。


1. 病灶:两个会真实发生的失败故事

1.1 故事一:抓回来的文档,读不到中间

doc/57 的 web_fetch 把整页 Markdown 落盘 .tako/fetch/,工具只回三行描述(来源/链接/token/路径)。

场景:用户问「这份技术规范里,接口限流阈值是多少」。模型 web_fetch 拿到描述段 → read_file 读那个文件 →

错误:文件 .tako/fetch/https-example-com-spec.md 有 812345 字节、超过 200KB 上限,
无界读会灌爆上下文——请用 head(前 N 行)或 tail(后 N 行)截读

模型只剩两条路:head 100 读到的是文档开头的目录与前言;tail 100 读到的是末尾的版权声明与联系方式。限流阈值在第 4000 行,两条路都到不了。结果是模型瞎猜、或者答「未能查证」。

这条故事同时说明 doc/57 §10 的一句话今天是假的:「模型 read_file 读到全文,答案有出处」——对大页不成立。

1.2 故事二:装依赖跑测试,报错看不见

场景:模型跑 npm ci && npm test。这条命令输出 60KB:前 45KB 是安装日志(added 812 packages…),尾部 3KB 是

npm ERR! code ELIFECYCLE
npm ERR! src/parser.spec.ts:42:9  expected 3 received 4

tako 的 bash 每流 32KB 上限、留头丢尾(bash.go 的 capWriter)→ 模型拿到 32KB 安装日志 + 一句「(stdout 超 32 KB 已截断——把需要的内容写进文件再读,不要直接重跑打印)」。

报错那 3KB 已经不存在了:没落盘、不可恢复。模型看到「装了一堆包」,最可能的下一步是原样再跑一遍(命令相同 → 输出相同 → 还是看不到报错),或者改命令瞎试。doc/56 §4.6 记的就是这件事:「装依赖、跑测试的错误通常在尾部,模型会看到开头、看不到报错,这比『上限小』更糟」。


2. 借谁:dsh 为主,pi 为辅

2026-11-01 拍板:五条待裁(§7)一律以 dsh 的实现为准——dsh 是这两件事上把同一形状做全的那一套(read 的分页、bash 的留尾与全文落盘、落盘文件的保留期都有一套自洽的数),pi 的形状与它同构,互为印证。

参考 借什么 不借什么
dsh tool-fs 的 read(read.ts / read-render.ts) offset(1-based)+ limit(行)+ 页脚续读提示;页上限 2000 行 / 50KB / 单行 2000 字符;offset 越界报错;read 只有这三个参数,没有 head/tail 它的 file_path 参数名;它的 MCP 目录工具族;它的行号前缀输出(1: text)——见 §5
pi 的 read(packages/coding-agent/src/core/tools/read.ts) 同上(另一套独立实现:两家各自收敛到同一形状 → 这不是某人的口味,是被两代实现验证过的形状) pi 的图片处理分支(tako 有 read_media_file/read_pdf_text 另走)
dsh subprocess-local 的 OutputCollector + bash-local 的配置(output.ts / index.ts) 内存滚动留尾(字节精确的尾窗);首次溢出时建文件并把已有字节补写进去(文件是全文);内存上限 64,000 字节/流、落盘上限 64MB/流;文件装不下全文就删掉它(不做半截文件) dsh 落系统临时目录(tako 落作业根内、跟着租户与保留窗口走)
pi 的 bash + output-accumulator 留尾(不是留头)+ 全文落盘 + 回路径(与 dsh 同构) pi 落在系统临时目录、进程退出即失的位置(tako 要落在作业根内、跟着租户与保留窗口走)
dsh spill-local 的 cleanupPeriodDays 落盘全文保留 30 天(默认),到期清扫;清扫失败只记日志 dsh 的「启动时扫一次」触发点(tako 是长驻进程,见 §4.4)

一处必须说清的差别:dsh 的 web_fetch 超限时真丢内容——它既没有 range 参数,也不落盘。pi 的 bash 不丢:落盘可回读。

tako 在 doc/57 里已经选了「整页落盘」这条路(DeepSeek Fetch 接口只认 url、不给 range → 唯一的出路就是整页落盘),所以 tako's read 必须能分页,否则 doc/57 的设计在长文档上自相矛盾。这两篇是一件事的两半。


3. 方案 A:read 分页(read_file / read_text_file)

read_file 与 read_text_file 是同一实现的两个名字(19v6-08 §3),两个名字一起改。

3.1 契约

项 今天 改后(dsh 形态)
入参 path + head?/tail? path + offset? + limit?(head/tail 删掉)
读超大文件 报错「超过 200KB 上限」 不报错:返回第 1 页 + 页脚续读提示
单次上限 无界读 ≤ 200KB 2000 行 / 50KB / 单行 2000 字符(先到先算,与 dsh 同数)
行数 不报 报总行数(共 N 行)

两处字节变化(要认):

  1. 读出来的文本统一是「行用 \n 连接」,末尾那个换行不再保留。今天无界读是把文件原样直出(末尾换行带着),而 head/tail 分支是拼行(末尾换行已经没了)——改后两条路合成一条,形状统一。影响面:所有以 \n 收尾的文件,read 的返回值少一个末尾换行。
  2. 每次 read 都追加一行页脚(dsh 的三态页脚,见 §3.2)——小文件的读回值也多这一行。

3.2 页脚(字节定死,是契约)

三种情形,三条固定文案(都追加在正文之后、空行分隔):

情形 追加的那一行
还有更多(2000 行用尽,或模型自带 limit 停早) (已显示第 3-2002 行,共 50230 行;继续读用 offset=2003)
字节上限先到(50KB) (已显示第 3-847 行,共 50230 行;本次被 50KB 上限截断,继续读用 offset=848)
读完了 (已读到文件末尾,共 50230 行)

行号用 ASCII -;共 N 行 是总行数;offset= 是下一次调用的起始行号。

为什么要分「还有更多」与「被 50KB 截断」两条:前者可以靠调大 limit 解决,后者不行(行数再多也超 50KB),只能靠 offset 跳着读。混成一条会让模型反复调大 limit 空转——pi 特意分开,dsh 也分开。

为什么「读完了」也要带总行数(dsh 的 (End of file - total N lines)):head/tail 删掉之后,总行数是模型唯一的定位坐标——它要跳到第 N 行附近,就必须先知道 N 在哪。

3.3 怎么读:一遍流式,不把整文件读进内存

今天的实现是 os.ReadFile 整份进内存(≤200KB 才放行)。改后文件可能几十 MB,不能整份进内存:

一趟流式扫描同时干三件事——① 算整文件 sha256(fingerprintOf 已有流式实现,内存恒定);② 数总行数;③ 只把请求的那一页收进内存。

3.4 指纹不变(写前判据不受影响)

write_file 的「先读后写」纪律靠 fileBaseline 里那份整文件指纹判冲突(filefp.go)。改后虽然只把一页收进内存,但 sha256 仍是整文件的(流式算的),判据逐字不变——尾部被改动照样会被 write_file 拒。

3.5 今天那条错误会消失

文件 %s 有 %d 字节、超过 200KB 上限… 这条错误在改后不再存在(大文件走分页,不再是错误)。它今天出现在 filetools.go 的实现里、filetools_test.go 有一条单测钉它、19v6-08 §3 表格里写着它——三处同批改(见 §6)。


4. 方案 B:bash 留尾 + 全文落盘 + 回路径

4.1 契约

4.2 为什么是「留尾」而不是「留头 + 留尾各一半」

4.3 全文落盘怎么做到「文件是全文」

今天 capWriter 只留头、其余直接丢——被丢的字节当场没了。改后照 dsh 的 OutputCollector 做(它与 pi 的 OutputAccumulator 同构):

内存占用 ≤ 64KB/流(尾部)+ 一份正在写的文件;未超限的调用一个文件都不建(磁盘零开销)。

4.4 落盘文件的去处(保留期 30 天)

保留 30 天(dsh 的 cleanupPeriodDays 默认值)。dsh 的理由照搬:「保留期是刻意的——被恢复或被分叉的会话可能还在引用一个更早的路径,直到它过期」。

清扫触发点(doc/82 施工批改定):bash 落盘的清理归后台命令的清理循环(bash_job_sweeper.go,每小时一轮、终态行超 30 天连输出目录一起删、主键 DELETE 幂等多副本可同跑);.tako/search、.tako/fetch 仍是「每次 bash 调用前扫一次」的旧触发点,失败只记日志,不影响命令执行。


5. 明确不做(登记,未来用例逼出再立项)


6. 契约字节与验收(两台机器各管一段)

层 落点 钉什么
dev 钩子 POST /api/dev/workspace/read(本篇新增,形状照既有的 POST /api/dev/workspace/bash——那个也是直接调 bash 工具、回 data.output) read 的输出字节是模型侧字节,四个 API 打不到它。没有这个口,「read 的字节对不对」只能靠「起 run + 盼模型照着调」来验(模型不听就假红)。它让 read 的契约可 curl、可逐字节断言,且只在 -dev 模式注册。
快闸 yk-tako-eino/internal/runengine/filetools_test.go、bash_test.go(或新文件) read 的三条页脚逐字、offset 越界文案、bash 留尾后的结果形状、落盘文件是全文。期望字节不许手写——先跑一次把真实字节抄进去。
活体 scripts/acceptance/(新增一条用例,或并进现有 workspace-files 用例) 真实起引擎、真实跑一轮:模型分页读大文件的结果里有 共 N 行 与 继续读用 offset=;bash 大输出的结果里有 完整输出已存到 与一个能真的读出来的路径。

另外三处同批改(改行为必改的旁证):


7. 待拍项(2026-11-01 已拍:五条一律照 dsh)

# 问题 拍板 依据与代价
1 head/tail 保留还是废掉? 废掉(read 只剩 path/offset/limit) dsh 的 read 就是这三个参数(read.ts 的 parameters 只有 file_path/offset/limit)。代价:读尾部要两跳(先拿总行数再跳);缓解:页脚恒带总行数。收益:一套截读方言而不是两套,少一组「参数打架」的组合,少两个入参的 token
2 read 的单次字节上限取多少? 2000 行 / 50KB / 单行 2000 字符 dsh 的 READ_LIMIT = 2000、READ_MAX_BYTES = 50 * 1024、READ_MAX_LINE_LENGTH = 2000(read.ts / read-render.ts)。今天 200KB 是「无界读的减灾档」,有了分页就不该再让一次调用吞 200KB
3 bash 的上限取多少? 内存 64,000 字节/流、落盘 64MB/流 dsh bash-local 的 maxOutputBytes 默认 64_000、maxSpillBytes 默认 64MB(bash-local/src/index.ts)。落盘上限从 dsh 抄,因为「装不下全文就删文件」这条纪律要求有个明确上限
4 bash 全文文件怎么清? 保留 30 天 + 每次 bash 调用前扫一次 dsh 的 cleanupPeriodDays 默认 30(spill-local/src/index.ts)。触发点与 dsh 不同(dsh 扫一次,tako 长驻 → 改成调用前扫),理由见 §4.4
5 本篇登记进 doc/16 §2 能力表的哪个位置? 挂在第 1 行(主循环 + 工具)下作子项,不新开能力号 这是既有能力(文件工具 / bash)的缺陷收口,不是新能力;doc/49 的做法同此

8. 分阶段(按 §7 拍板结果拆 action)

阶段 做什么 验收的第一行(打一个跑着的东西)
R1 ① POST /api/dev/workspace/read 钩子(打 read 工具、回它的输出原文)② read 加 offset/limit + 分页语义 + 页脚(head/tail 暂留、与之互斥,免得中间态出现「大文件反而读不了」的倒退)③ 换流式读 + 50KB/2000 行/单行 2000 字符页上限 + 删 head/tail + 大文件不再报错 起隔离引擎 → curl POST /api/dev/workspace/read → 看工具结果字节
R2 bash 留尾(64,000 字节/流)→ 全文落盘 + 回路径(≤64MB/流,要么完整要么不存在)→ 30 天清扫(落点与触发点后被 doc/82 改定:命令目录、job sweeper 清理) 起隔离引擎 → curl POST /api/dev/workspace/bash → 看尾部与落盘路径
R3 契约字节与文档同批收口(快闸单测 + expected.json + 19v6-04 + 19v6-08 + doc/57 §10 + doc/56 + doc/16 + doc/README) scripts/acceptance/check-expected.sh 绿 + go test ./internal/runengine 绿 + scripts/check-master-plan.sh 绿

顺序理由:R1 先做,因为 doc/57 的「落盘之后模型自己读」在它之后才成立;R2 独立于 R1(两处是不同的失败故事),但同样先于 R3(契约字节要一次收口)。

每一拍的 diff 目标 ≤80 行;R1 的流式读取与 R2 的滚动尾部各是一个独立的小任务,不混在一拍里。