tako 文档 GitHub

21 · 同会话历史查找

性质:已定案,施工完成(台账 tmp/21-历史查找/,H1–H5 全拍落地、2026-10-12 交审中)。 当日经讨论并入两处修订:§3.4 子代理由「拒绝壳」改为「继承真工具」、新增「截断落盘」 (§3.2 / §3.3 末节,三子裁定随文);收口拍 H4 观察点裁定:截断后内联首行计数报全量数(§3.2)。

本篇不加端点、不加帧 kind、不加表、不加索引。doc/16 索引与 19v6 index 的回填已随 H5 落地。

1. 要解决的那一行

用户还在同一个会话里追问更早一轮的原文。页面上那一行还在,模型这次的输入里没有。

具体一场是这样的。用户在会话 s_1 里让模型读文件。工具结果里有一行 E_DECK_17。这场 EndRun 把工具返回的全文写进 runlog_entries,同时也写进 run_model_messages。页面以后只读 runlog_entries,按 seq 排,刷新仍能看见这行。

对话变长。下一场发送前,程序做折叠,改的是 run_model_messages:早期行标成 compacted=true,不再送给模型,换成一条摘要。摘要末尾有一块 fileOps。程序从被压掉的 tool_calls 参数里抽出路径,钉在摘要正文最后,形如 - /workspace/output/deck.html(write_file,r_XXXX)。这块里有路径和工具名,没有工具返回的正文。模型当时也没有调用 memory。notes 里没有这个错误码。

用户仍用 s_1 再发一条:「上次那个错误码是什么」。模型这次读到的是三样东西:系统提示(Instruction 加上起手冻住的笔记快照)、那条摘要、窗口里还留着的近期行。三样里都没有 E_DECK_17。模型只能说不记得,或者编一个。runlog_entries 里那一行并没有丢。

链路停在「模型组装输入」这一环。上游是用户用同一个 sessionId 再发一条消息。下游本该是模型答出错误码。中间缺的是:有人拿问句里的原词,去已经提交的历史行里把那一行取回来,放进这一轮的工具结果。

search_history 就是这一环。查完的文字只出现在当轮 tool_result 里。下一场的系统提示不因此变长。

2. 旁边三处各管什么

这三处继续留着。本篇不改它们的字数、格式和写入时机。

笔记。模型调用 memory 之后,writeNote 把短句写入 notes。下一场 run 起手把未替代行渲染成快照,接在系统提示末尾。agent 合计 2200 字,user 合计 1375 字,超出拒绝新增。它装的是以后每一场都要遵守的短规矩。E_DECK_17 这种只在某一轮工具结果里出现的字,模型没调用 memory,表里就没有。把上限放开也变不出这一行,而且快照会进以后每一场的系统提示,mid-run 折叠数的就是拼上快照之后的系统消息,笔记越长,本轮的工具往返越早被折掉。

fileOps 块。折叠定案后,程序把路径钉在摘要末尾。deck 的路径靠它活着。工具返回正文不在参数的 path 字段里,提取程序拿不到 E_DECK_17。

摘要散文。摘要模型可以抄下重要事实,也可以不抄。没抄的那一行,模型下一次看不到。摘要文本本身本篇不改。

3. 工具

名字 search_history。进父池,排在 memory 后面。file_effect 登记为 write:截断发生时它把完整结果写进 workspace 的 .tako/search/(§3.2 / §3.3 末节的「截断落盘」)。它对 runlog_entries 仍然只读不写;落盘写的是程序命名的新文件,一次一写,不覆盖既有文件。

四个 API 的路径和字节不变。调用走现有的 tool_call / tool_result。runlog_entries 仍是历史真源。工具只读它,不写它,也不读 run_model_messages。

会话号不作为参数。模型传入另一个 sessionId 就能翻到别人的历史。程序从这场 run 的 noteBox 里取 session 和 run。noteBox 今天已经带着这两项:memory 用 run 和 user 行的 seq 填笔记的来源。缺 noteBox 时与 memory 相同,返回 Go error,由现有的工具错误包装变成工具结果,不查库。

查询排除本场 run_id。本场的 user 行在抢闸时已经进了 runlog_entries。用户若把错误码打在问句里,按 seq 从新到旧取结果时,最新一行会是问句自己,把真正的工具结果挤出名额。本场的工具行要等 EndRun 才写入,查询进行的时候本来也不在表里。所以这把工具解决的是下一场来问。本场中途刚被折掉、还没提交的那段,它拿不到。

3.1 模型看见的说明

说明写在工具 schema 上,不改 Instruction 的字节。全文如下:

在本会话已经落库的历史里按词查找原文。摘要和笔记里都没有、用户在问本会话更早一轮的错误码、原句或工具返回中的一截时使用。query 传原文里会原样出现的词;多个词用空格分开,必须同时出现。around_seq 传上一次结果里的 seq,用来看相邻几行。不要用它读文件的当前内容,也不要把查到的长文写进 memory。

参数:

参数 含义
query 要找的词。空格分开。around_seq 大于 0 时忽略
around_seq 上一次结果里的 seq。大于 0 时改看这一行的相邻行
limit 命中条数。不传是 5,最大 10。只在按词查找时用
window around_seq 左右各取几行。不传是 2,最大 5
roles 逗号分隔。不传是 user,assistant,tool_result。只在按词查找时用

tool_call 行的 text 是 name(args),路径多半已经在 fileOps 块里。默认不搜它。模型要连调用参数一起看,把 roles 写成带 tool_call。四个 role 以外的值返回错误文本,不查库。

3.2 按词查找

query 去掉首尾空白后按空白拆开。拆出 0 个词,返回 query 为空。传入原文里会原样出现的词。 超过 8 个词,返回 query 拆出 N 个词,最多 8 个。 其中一词超过 200 字,返回 有一个词超过 200 字。 这三句都不查库。

每个词做一次子串条件,必须同时成立。用 ILIKE,不用 LIKE:库里是 E_DECK_17,问句写成 e_deck_17 时 LIKE 落空,ILIKE 仍中。中文两种写法结果相同。

词里的 \、%、_ 先转义,模式再用 ESCAPE '\'。否则用户或模型传入的 % 会变成通配符,一条查询扫出整段历史。

范围是 session_id 等于 noteBox.session,run_id 不等于 noteBox.run,role 在请求的名单里。ORDER BY seq DESC,条数是 limit。不建新索引。扫描量是这一会话里、本场之前的行数。行数大到这次查询变慢,再单独立项,本篇不预建。

2026-10-12 在开发库 PostgreSQL 17.4 上对过同一句话 上次那个错误码是 E_DECK_17,deck 放在 output/deck.html。默认全文配置是 pg_catalog.english。to_tsvector 把中文整段切成一个词 上次那个错误码是,把错误码拆成 e、deck、17,deck。plainto_tsquery 查 错误码 和 E_DECK_17 都是不命中。ILIKE 两个都命中。可用扩展里没有 pg_search,也没有中文分词扩展。本篇不换 ParadeDB,也不走 to_tsvector。

命中后不把整行塞进工具结果。以第一个词在该行 text 里第一次出现的位置为中心,向前、向后各取 200 字(按 rune,不按字节)。行比窗口短就整行返回。前面被切掉时,片段以 ……(前略) 起头。后面被切掉时,以 ……(后略) 收尾。

结果文本:

命中 1 条。范围:本会话里本场 run 之前已提交的行。
---
seq=12 role=tool_result agent=researcher
……(前略)
E_DECK_17
……(后略)

agent 为空表示主代理,等号后面留空。0 条时整段结果就是 没有命中。 多条之间用 --- 分隔,从新到旧。首行的「命中 N 条」N 恒为全量命中数(喂入上限内的块总数,不超过 limit),截断丢块不改写——内联首行与落盘文件首行因此一致,「其余命中已截断。」的「其余」才有先行词。全部结果超过 4000 字时,从后面的命中丢起,最后加一行 其余命中已截断。 这一上限是为了避免一次工具结果把刚折掉的正文原样灌回窗口,下一轮又触发折叠。

截断落盘。 截断发生(有命中被 4000 字上限丢掉)时,完整结果另写一份进文件:同一份渲染、摘掉字上限——文件内容就是未截断的工具结果本身(不含 其余命中已截断。 这一行),落在 <workspace>/.tako/search/ 下一个程序命名的 .md 文件(每场 run 一个计数器顺编,主代理与子代理共用同一份计数,一次一写、永不覆盖);内联结果在 其余命中已截断。 之后再加一行 完整结果已写入 .tako/search/<runId>_<n>.md。(workspace 相对路径)。文件写失败(目录只读等)不报错,退化为今天的纯截断行为、不加这一行。未被截断时不落盘,结果一个字节不变。

3.3 看相邻行

around_seq 大于 0 时不看 query 和 roles。在同一 session_id 里取 seq 落在 [around_seq - window, around_seq + window] 的行,含这一行自己,按 seq 升序。这里不再排除本场 run_id:调用方已经从上一笔结果拿到了 seq,相邻的 user 行或 tool_call 行就是上下文。本会话没有这个 seq 时,返回 本会话没有 seq=N。

每一行最多 800 字,从行首起取。超出写 ……(后略)。结果文本:

seq=12 的窗口,前后各 2 行。
---
seq=10 role=tool_call agent=
get_time({"timezone":"Asia/Shanghai"})
---
seq=12 role=tool_result agent=researcher
E_DECK_17

窗口结果同样受 4000 字总上限,超出时从离 around_seq 最远的行丢起,并加 其余命中已截断。 截断同样触发落盘,规则与 §3.2 一致:完整窗口(含被丢的行,不含截断标记行)写进 .tako/search/,内联结果加同样的路径行;写失败退化,无截断不落盘。

3.4 子代理

researcher.md 没有 tools 行,子代理装载时拿到父池的一份拷贝,search_history 随拷贝进子代理池——真工具本身,同一对象、同一份说明、同一条实现,不设拒绝壳。(2026-10-16 起 researcher 写的是 exclude_tools 排除名单,走的是「继承父池减去列出的名字」这一档而不是整份拷贝——doc/26 §3 的第四态,search_history 不在排除项里。本节结论一个字不变:排除路同样只做原对象搬运,池里那把仍是同一个真工具、不换壳;agents_test.go 的 TestSubagentPoolKeepsRealSearchHistory 用的仍是手造的继承路规格值,出厂配置的一致性另由 TestShippedAgentSpecToolGuards 钉。)身份仍从 ctx 的 noteBox 取,是主 run 的 (session, run):子代理查的是主会话、排除本场 run,语义与主代理调用完全一致。

这样设计,是因为挖掘型追问(多轮按词查、拿 around_seq 开窗回看、归类分析)正该吃在子代理自己的窗口里:中间每一轮查询死在子代理自己的上下文中,主线程只见终稿;截断落盘给出的 md 路径还可以在终稿里交回主代理(和用户),主线程从头到尾不被工具结果逐轮灌入。若在这里拦一道壳,这些查询会逐轮落回主线程自己的历史,mid-run 折叠被提前触发,子代理的独立窗口形同虚设。

折叠隔离的是体积,不是秘密:主代理本来就能用这把工具有界地取回已折掉的行,子代理经终稿回传的内容也被同一条 50 KB 上限管着。本篇不改 researcher.md。

4. 本篇不做

新开一个会话时,runlog_entries 里没有上一份会话的行。跨会话仍靠笔记里的短句。本篇不按 workspace 去扫所有会话。

本场 EndRun 之前,这一轮的工具往返只在内存里。本篇不读这份内存,避免工具在提交前看见还可能被丢弃的半截生成。

问法换成了另一套词,和那一行没有共同字串。ILIKE 找不到。不为此加向量、不加 BM25、不换数据库。

不把命中写进 notes。模型若认为这是以后每场都要遵守的短规矩,仍走现有的 memory。本篇不自动记。

不改折叠、不改 fileOps 块、不改笔记的上限。

截断落盘不突破 limit / window 的钳制:词模式仍最多取 10 条命中、窗口仍前后各 5 行。被 4000 字上限丢的行有文件可去;被 limit 挡住不查的行(第 11 条及更旧)仍不可达。放宽钳制做批量导出另立拍,真用到再说。

.tako/search/ 下的文件不自动清理。截断是低频事件,累积可忽略;要清理时单独立项(连同 dev reset 是否顺手删一起裁)。

5. 验收

验收打在跑着的引擎上,走现有四个 API。先 lsof 看端口,被占就换,不杀别人的进程。Redis 与 PostgreSQL 用开发库现端口。模型不调用工具时,把任务文字写直白,写明工具名和要传的词。

第一场写入原文。投一条消息,让模型把下面这句原样写进某个工具结果能留下的回复里,或直接让助手回复里含这句。最省事的做法是:用户消息本身先写上 E_DECK_17,助手回复引用它。EndRun 之后 runlog_entries 里至少有 user 行含这个词。

第二场用同一个 sessionId 再投一条,正文写明:不要凭记忆,调用 search_history,query 传 E_DECK_17。frames 里出现 name 为 search_history 的 tool_call,以及 tool_result。output 里有 命中、seq=、E_DECK_17。GET /api/sessions/{sessionId}/log 的字段与行序保持原样。

再投一条,正文写明调用 search_history 且 around_seq 用上一笔结果里的 seq。tool_result.output 以 seq= 开头并含 的窗口。

子代理这条靠活体委派,不靠模型自觉:主代理把一个挖掘任务(按词查、开窗回看、归类)交给 researcher,frames 里 researcher(agent 非空)的 tool_result 含真实命中(命中、seq=),终稿含分析结论。单测钉「装载后子代理池里的 search_history 是真工具」(类型断言),不建换壳机制。

截断落盘这条:连投数场,造出含同一词的行数超过 limit、总渲染超 4000 字的历史,再按词查该词——内联结果含 其余命中已截断。 与 完整结果已写入;随即用 read_text_file 读该路径,文件含被丢的行、且不含截断标记行。未触发截断的同形查询,结果与落盘机制存在前逐字节相同。

6. 所以这解决了什么

同一会话的下一场,摘要没抄、笔记也没记、fileOps 块里也没有的那一行原文,模型用问句里的原词从 runlog_entries 取回,放进当轮工具结果,然后回答。历史仍只以这张表为准。系统提示不因此变长。

挖掘型追问可以整包委派给子代理,主线程只见终稿;被 4000 字上限丢掉的部分落在 workspace 的 md 文件里,模型和人都能再打开。