未提交改动审查交接(2026-09-30)
范围与结论
审查对象是当时工作区的未提交改动,包括未跟踪的 Go 文件;本文不是实现计划,也没有修改业务代码。主要改动:read_file 改为 enhanced 工具以返回图片片段,mediaoffload 将历史内联媒体落盘,msgtext 给事件和摘要提取多模态消息文字,guard 补齐 enhanced 工具钩子,WebUI 按既定计划迁移到 Gin。
组件边界整体可用:tools 负责产生工具回执,mediaoffload 负责模型输入中的媒体生命周期,guard 负责调用/输出策略,msgtext 负责文本呈现。优先改的是媒体的轮次身份、重新读取契约和缓存存储语义,而不是再拆更多包。
Gin 迁移已有独立决策与等价迁移计划(docs/superpowers/plans/2026-09-30-webui-gin-migration.md):handler 内继续用 c.Request / c.Writer 是有意控制响应差异,不作为本次重构问题。
待处理问题
1. P1:read_file 在限制大小前读完整文件
- 证据:
yk-tako-eino/internal/tools/files.go:45-57先os.ReadFile,后判断图片是否超过 5 MiB、文本是否截断到 4000 字节。 - 影响:上限只控制送给模型的结果;读取一个巨大的允许访问的文件,仍会先分配并读入整份数据,文本路径还会构造完整字符串。
- 建议:打开文件后读取足够识别 MIME 的文件头;普通文件先取大小,图片超限直接返回,文本只读截断所需前缀,并保留真实总字节数供提示使用。非普通文件/读取过程也要有硬性字节上限,不能仅依赖
Stat。 - 验收:巨大文本和巨大图片不因读取大小而线性占用内存;现有小图片、UTF-8 截断和超限提示行为保持一致。注意现有
files_test.go只断言回执形状,没断言实际读取量。
2. P2:同轮主动重读相同图片仍被抑制
- 证据:
yk-tako-eino/internal/mediaoffload/offload.go:124-131仅按 SHA 判断本轮是否已见;再次调用read_file会生成新的工具结果,但同一 SHA 随即被换成占位符。 - 影响:占位符提示模型“用 read_file 重新看”,但同一轮按提示操作并不能再看到原图。现有端到端测试
internal/mediaoffload/integration_test.go特意读了两张不同的图,没有覆盖同图重读。 - 建议:把“这个媒体内容见过”与“这个工具结果出现过且已交付给模型”分开。基于稳定的片段/工具结果身份记录交付状态:首次出现的结果允许呈现一次,之后才替换;另一个工具调用即使 SHA 相同,也应有一次呈现机会。同一次模型输入里重复的同图仍可按既有规则去重。
- 验收:同一轮首次读取、下一次调用变占位符、显式再次读取相同路径后模型再看到图,随后再变占位符;覆盖并行工具结果重复图片的情形。
3. P2:用历史消息数量推断轮次会与压缩冲突
- 证据:
yk-tako-eino/internal/mediaoffload/offload.go:59-65,134-145使用当前输入里的用户消息条数决定是否清空seen;internal/compact/plan.go可以删除历史轮并加入摘要。 - 影响:压缩后历史用户消息条数会下降,新一轮新增用户消息后条数可能恰好与上一轮一样,导致
seen未重置。本轮首次读取与上一轮同 SHA 的图会被直接换成占位符。 - 建议:由会话/run 生命周期提供稳定轮次标识,而不是从可裁剪的
state.Messages反推。REPL 和 WebUI 已分别有CurrentRunID();在装配层把轮次提供给媒体组件,保持媒体包不依赖 WebUI 或压缩实现。还要明确审批恢复时仍属于同一轮。 - 验收:历史压缩后用户消息数碰撞、新的一轮读取旧 SHA、审批暂停/恢复、同一轮多次模型调用,均能正确区分轮次。
4. P2:缓存文件未原子发布
- 证据:
yk-tako-eino/internal/mediaoffload/store.go:77-85先os.Stat,再直接os.WriteFile到最终路径;cmd/yktako/main.go的 Store 由各会话共享。 - 影响:另一会话可能在写入未完成时将“文件已存在”当作命中,随后读到不完整的图片;写入失败也可能留下半文件,之后一直被当成完整缓存。
- 建议:在同目录创建临时文件,完整写入并关闭后原子发布最终路径;失败清理临时文件。命中最终路径时至少保证它由已完成写入产生,不应把任意已有文件直接视作可信缓存。
- 验收:并发同 SHA 写入/读取、模拟写入失败后重试、已存在目标文件等场景都不会暴露半文件。
5. P2:共享缓存缺少生命周期/总量边界
- 证据:
yk-tako-eino/internal/mediaoffload/store.go:68-76只有单个媒体的 32 MiB 上限;共享目录.media-cache没有总容量、过期或清理策略。 - 影响:长期使用不断写入不同媒体会持续占用工作区磁盘。
- 建议:将容量和清理策略留在
Store层统一实现,但先定义“占位符还能否重读”的契约:直接按会话结束删除或简单 TTL 淘汰,会让保存在历史/归档里的路径失效。可选策略是保留仍被历史引用的文件,或明确缓存过期后read_file的可恢复反馈;确定契约后再选择容量、引用追踪或过期机制。 - 验收:超过总量后行为可预测;仍被有效占位符引用的媒体可重读,或能明确报告已过期;清理不影响其他会话。
推荐顺序
- 先修
read_file的有界读取,再修 Store 的原子发布,封住资源与不完整文件问题。 - 再统一“轮次 ID + 片段交付 ID”的状态模型,同时修复问题 2、3;不要只改
seen的重置条件。 - 最后确定缓存的引用/清理契约,再实现容量策略。避免先做清理、再补偿已经失效的占位符。
验证记录
- 审查时运行
git diff --check、go test ./...:通过。 - 运行
go test -race ./internal/mediaoffload ./internal/guard ./internal/tools ./internal/webui:通过。 - 这些测试没有覆盖上述关键边界;修复时需增加对应单测及至少一条真实 Agent 调用链的集成测试。
本文只记录审查与接手建议;工作区原有的未提交改动应原样保留。