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 core125 步全过(含新增的用例 32 读分页、33 bash 输出留存);check-expected.sh用例号集合一致;check-master-plan.sh通过。 参照:dshdeepseek-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/);pipackages/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 今天有两处「拿不到就永远拿不到」:
read_file读超过 200KB 的文件直接报错,模型只剩head/tail两条路——没有任何办法读到文件中间;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 行) |
offset:1-based 起始行号,默认 1;给 0 或负数 → 报错offset 须为正整数(给的是 N)。limit:本次最多返回多少行,默认 2000、上限 2000;给超过 → 报错limit 不得大于 2000(给的是 N)。head/tail删掉(dsh 的 read 只有这三个参数):一套截读方言比两套好——模型不必在「前 N 行/后 N 行/第几行起」之间做选择题,也没有「两个参数打架」的组合要判。- 代价(认):想读尾部要两跳——先读一次拿到总行数,再
offset=总-N+1读第二页。 - 缓解:页脚恒带总行数(dsh 的
(End of file - total N lines)也带),模型第一跳就知道该从哪跳。
- 代价(认):想读尾部要两跳——先读一次拿到总行数,再
offset超出文件末尾 → 报错offset %d 超出文件末尾(共 %d 行)。
两处字节变化(要认):
- 读出来的文本统一是「行用
\n连接」,末尾那个换行不再保留。今天无界读是把文件原样直出(末尾换行带着),而 head/tail 分支是拼行(末尾换行已经没了)——改后两条路合成一条,形状统一。影响面:所有以\n收尾的文件,read 的返回值少一个末尾换行。 - 每次 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 已有流式实现,内存恒定);② 数总行数;③ 只把请求的那一页收进内存。
- 行数口径:以
\n收尾的文件,末尾那个换行不算多出一行(沿用今天 head/tail 分支的TrimSuffix规则);空文件 = 0 行。 - 单行超长:一行本身超过 2000 字符时,不切半行——按字符截到上限内,行尾标
…(本行超长已截断),并在页脚说明「本次被 50KB 上限截断」(dsh 的READ_MAX_LINE_LENGTH = 2000)。 - 单行扫描:一行可以很长(几 MB 的 minified JS),所以读一行的循环只累计前 2000 字符,后面的字节照读照丢(否则一个无换行的文件能把内存吃穿)——dsh 的
buildWindow就是这个形状。
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 契约
- 内存上限:每流 64,000 字节(dsh 的
maxOutputBytes默认值;stdout / stderr 各一份,与今天同口径——今天也是每流一份上限,只是数是 32KB)。 - 留的那一半翻转:今天留头、丢尾;改后留尾、丢头(尾 = 报错、失败原因、最后几行——这才是模型要的)。留的是字节精确的尾窗(dsh 的
OutputCollector:整块丢头块,头块装不下时按字节切准到上限)。 - 丢的那一半不再丢:首次溢出时建文件,把已有字节先补写进去,之后边到边写 → 文件里是该流的全文。
- 落盘上限:每流 64MB(dsh 的
maxSpillBytes)。装不下全文就把文件删掉(dsh 的discardSpill)——只报「内存尾窗」,不报路径。- 这是 dsh 最值钱的一处纪律:要么是全文,要么不存在。留一个半截文件比不留更坏——模型读到的是一份看起来完整、其实缺了尾巴的输出。
- 落盘位置(doc/82 施工批改定):后台命令输出落命令自己的固定目录——挂项目的会话是
runtime/tmp/bash/jobs/<bj>/、纯会话是.tako/bash/jobs/<bj>/(stdout.out与stderr.out,内容是该流的原始字节,从首字节起落盘,不等溢出)。- doc/58 原设计按 runId 建目录(
<作业根>/.tako/bash/<runId>/),doc/82 改为按命令号:命令要活过前台窗口、可被来源会话之外的面板读取,落点跟着 job 走而不是跟着 run 走;首字节起落盘同样是为了转后台后的早期输出不丢。 - 旧历史消息里的
.tako/bash/<runId>/…回执路径由resolveRuntimeReadPath映射读取,不迁移文件。 - 「作业根」= 会话挂项目时是项目目录,没挂项目时是会话目录(
runWorkspace的口径)——.tako/search、.tako/fetch用的是同一个根。 .tako/已经是内部目录(workspaceInternalDirs,用户与产品 API 都看不见)→ 不会混进项目文件清单。- 落在作业根下 →
read_file能直接读它(resolveInWorkspace允许根内任意路径),路径按相对作业根给模型。
- doc/58 原设计按 runId 建目录(
- 回执行(追加在那一流的内容之后):
(stderr 完整输出已存到 .tako/bash/r_01ABC/2.err,共 123456 字节;用 read_file 分页读它)- 哪一流超限就提哪一路;两路都超就提两行(每流一行)。
- 全文没超 → 不落盘、不追加(今天的字节逐字不变)。
4.2 为什么是「留尾」而不是「留头 + 留尾各一半」
- 留头 + 留尾各一半(dsh 的 spill 预览、pi 的
truncateMiddle那种)是给通用大结果用的:既要开头(结论)又要结尾(报错)。 - bash 的输出有明确的「结论在最后」性质:装依赖、跑测试、跑 grep 的失败信息都在尾部。留一半开头等于把预算花在最没用的地方。
- dsh 与 pi 都是留尾(dsh 的
OutputCollector注释直说「Tail-keep rationale (pi/OpenCode): 报错和最终结果都聚在命令输出的末尾」)。照它们走,不自己发明第三种。
4.3 全文落盘怎么做到「文件是全文」
今天 capWriter 只留头、其余直接丢——被丢的字节当场没了。改后照 dsh 的 OutputCollector 做(它与 pi 的 OutputAccumulator 同构):
- 内存里滚动保留尾部 ≤64,000 字节(整块丢头块;头块装不下时按字节切准到上限,保证尾窗字节精确);
- 一旦累计超过 64,000 字节 → 建文件,先把已有的全部字节补写进去(此刻内存里还握着整条流的前缀),之后的字节边到边写;
- 收尾时文件里就是该流的全文,内存里那份尾部是给模型看的;
- 文件写失败(磁盘满、目录不可写)→ 弃掉文件、继续留尾(dsh 的 fail-open:落盘是补救手段,不是执行的前提),并只报一次。
内存占用 ≤ 64KB/流(尾部)+ 一份正在写的文件;未超限的调用一个文件都不建(磁盘零开销)。
4.4 落盘文件的去处(保留期 30 天)
保留 30 天(dsh 的 cleanupPeriodDays 默认值)。dsh 的理由照搬:「保留期是刻意的——被恢复或被分叉的会话可能还在引用一个更早的路径,直到它过期」。
清扫触发点(doc/82 施工批改定):bash 落盘的清理归后台命令的清理循环(bash_job_sweeper.go,每小时一轮、终态行超 30 天连输出目录一起删、主键 DELETE 幂等多副本可同跑);.tako/search、.tako/fetch 仍是「每次 bash 调用前扫一次」的旧触发点,失败只记日志,不影响命令执行。
5. 明确不做(登记,未来用例逼出再立项)
- 不做通用 spill 插件(dsh 那种「所有 tool_result 都流经它」的横切层):tako 只有两处真需要(read 分页、bash 输出),为一个需求建一层横切机制不值;真出现第三个大结果来源再说。
- 不跟 dsh 的行号前缀输出(dsh 的 read 回
1: text带行号):tako 的edit_file要求old_text与文件逐字符一致,带行号的回读文本没法直接喂给它——为了看行号牺牲「读到的能直接改」不值。(dsh 没有edit_file这个约束,所以它能这么选。) - 不做
read的 range/字节区间参数:offset(行)+limit(行)已经够用,字节区间会让模型算偏移量。 - 不做
write_file的乐观并发(doc/35 已拍远期缝):本篇不动写路径。 - 不做 bash 单命令超时可配:doc/56 §4.6 提到 pi 每次调用可选
timeout,但那是另一条需求(今天 bash 固定 30 秒,见 bash.go),不在本篇范围,另立项。 - 不改
search_files/read_media_file/read_pdf_text:它们的返回面已经有自己的上限口径。 - 已知缺口(登记不修):bash 落盘文件不进租户存储配额(tako 的配额在
write_file/工具上传那条路上,bash 输出是执行副产物)——靠 64MB/流的上限兜底;真出现磁盘压力再立项。
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 大输出的结果里有 完整输出已存到 与一个能真的读出来的路径。 |
另外三处同批改(改行为必改的旁证):
doc/19-v6/19v6-08-file-tools.md§3 契约表两行(read_text_file/read_file):入参加offset/limit、删掉head/tail两列、错误分支去掉「>200KB」、返回列写明页上限与页脚;§2/§3 的「上限是减灾档」一段补「分页后每页 50KB/2000 行」。doc/19-v6/19v6-04-验收-curl.md+scripts/acceptance/expected.json:同批改,用例号两边一致(scripts/acceptance/check-expected.sh守)。doc/16总纲 +doc/README.md索引:本篇登记后要两页同批更新(见 §7 拍板 5 与 §8)。
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 的滚动尾部各是一个独立的小任务,不混在一拍里。