Documentation
¶
Overview ¶
Package spill 溢出存档平面单源(批三百零一):budgetTool 截断落盘(engine/runner)/
生命周期: Stable(v0.33.0 定级)——只允许 additive 变更(新增导出符号 / 新增方法且给零值默认实现 / 新增错误值);改签名、改语义、改默认值、 删导出符号都算 breaking,判定规则与变更流程见 docs/api-compat.md, 逐包理由见 api-lifecycle.yaml。
read_spill 工具取回(engine/tools)/控制台取回面(biz/handler)/写侧清理共用同一套 文件名净化、会话隔离与分页语义——LLM 面与控制台面各写一份必漂移(会话隔离三重守卫 的判据只应存在一处)。纯 stdlib 叶子层(kbgroup 先例)。
提示文案契约单源:截断提示文本由 TruncHint 生成、ParseHint 解析——前端 web/src/utils/timeline/mappers.ts spillHintOf 按同一契约解析(双侧钉档:文案变更 须同步该文件与其单测)。
Index ¶
Constants ¶
const ( DefaultLimit = 8192 MaxLimit = 16384 )
单次取回字节缺省/上限(自 read_spill 迁出:取回文本直接进上下文,上限与输出 预算同数量级——防「分页取回」退化成「全文重塞」)。
Variables ¶
var ErrBadName = errors.New("定位符非法(只允许本会话存档目录下的裸文件名)")
ErrBadName 定位符非法(含分隔符/点段/空名)。
Functions ¶
func ParseHint ¶
ParseHint 解析截断提示:返回定位符与截断旗标(无提示=零值)。Go 侧消费者 (tool_result 事件结构化字段)与前端 spillHintOf 同判据——改契约双侧同步。
Types ¶
type Page ¶
type Page struct {
Name string `json:"name"`
Offset int64 `json:"offset"`
Bytes int `json:"bytes"`
Total int64 `json:"total"`
EOF bool `json:"eof"`
Content string `json:"content"`
NextOffset int64 `json:"next_offset,omitempty"`
}
Page 分页取回结果(read_spill 回包与控制台取回面同构)。
func ReadPage ¶
ReadPage 会话隔离分页取回:off<0 视作 0、>total 收到 total;limit<=0 用缺省, 超上限收上限(LLM 面与控制台面同一缺省/上限)。
页边界不切坏字符(issue #199) ¶
分页按字节预算切,但 Page.Content 直接进 read_spill 回包 / 控制台取回面 (字段带 json 标签,encoding/json 对非法 UTF-8 替换为 U+FFFD)——页边界 落在多字节字符中间 = 每个跨页字符丢 1–2 字节且不可复原,与截断提示承诺的 「分页取回中段原文」直接冲突。修法三条:
- **尾部回退**:预算终点落在字符中间时回退到最近的 rune 起点,被截的 字符**整字符挪到下一页**(NextOffset 指向它的起点)——顺序分页逐页 拼接与原文逐字节相等,无丢无损;
- **头部回退**:非顺序分页传入的 off 落在字符中间时,回退到所在字符 的起点再读(页与页允许重叠,不允许跳字节——任何字节都在某一页里);
- **进度保底**:limit 小于单字符宽度(回退后整页装不下一个字符)时, 至少前进一个完整字符(Bytes 可略超 limit,至多 utf8.UTFMax-1), 分页器不死循环。