Documentation
¶
Overview ¶
Package spill 提供 Spill Storage(大结果溢出接缝)。
对齐上游:packages/spill/spill + spill-local + spill-policy
本文件对应任务 M42:Spill Storage 溢出接缝。
设计要点:
- SpillStore 只有一个操作 saveText:把超宽文本原样持久化,返回不透明 locator、 精确字节数与检索提示(retrievalHint);失败即拒绝(权限/ENOSPC/后端不可用);
- 本地后端写到 `<root>/session-<sha256(sessionId)>/<random>-<safeName>`,root 为 私有(0700),写入用独占(wx)且 owner-only(0600),避免被符号链接重定向;
- SpillPolicy(spill-policy 消费端)作为 tools/post-execute / Bash listener: 结果文本超过 maxInlineBytes → spill,并保留 head/tail 预览;保存失败 best-effort 保留原内联结果(不把成功调用搞成 isError)。
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FileSpillStore ¶
type FileSpillStore struct {
// Root 私有根目录(默认自动创建,0700)。
Root string
}
FileSpillStore 把溢出工件写到宿主文件系统的私有、会话作用域目录。
func (*FileSpillStore) ReadText ¶
func (s *FileSpillStore) ReadText(locator SpillLocator) (string, error)
ReadText 按 locator 读取溢出内容(供消费者/测试还原源字节)。
func (*FileSpillStore) SaveText ¶
func (s *FileSpillStore) SaveText(input SaveTextSpill) (SpillRef, error)
SaveText 实现 SpillStore:把 content 写到会话私有目录下。
type SaveTextSpill ¶
type SaveTextSpill struct {
// Owner 存储命名空间。
Owner SpillOwner `json:"owner"`
// Source 来源描述(起名/检视)。
Source SpillSource `json:"source"`
// SuggestedName 调用方建议的基础名(如 web_fetch.txt);后端净化成单一安全路径段。
SuggestedName string `json:"suggestedName"`
// Content 要原样持久化的完整文本(UTF-8)。
Content string `json:"content"`
}
SaveTextSpill 是一次持久化文本的请求。
type SpillLocator ¶
type SpillLocator string
SpillLocator 是单个溢出工件的不透明模型向句柄。 本地后端渲染为文件系统路径;远程/数据库后端可为 URI 或 key。消费方不解析它, 而按 retrievalHint 渲染。
type SpillOwner ¶
SpillOwner 是保存时的存储命名空间(按产生会话分组)。
type SpillRef ¶
type SpillRef struct {
// Locator 不透明模型向句柄。
Locator SpillLocator `json:"locator"`
// Bytes 精确编码字节数。
Bytes int `json:"bytes"`
// RetrievalHint 模型侧检索引导(如 "read <path>" / "grep ... <path>")。
RetrievalHint string `json:"retrievalHint"`
}
SpillRef 是一个已保存的溢出工件:locator + 字节数 + 后端检索提示。
func Apply ¶
func Apply(store SpillStore, input SaveTextSpill, text string, maxInlineBytes, previewBytes int) (inline string, ref *SpillRef, err error)
Apply 把过宽结果溢出,并返回内联预览 + 可选 ref。
- text 未超过 maxInlineBytes → 返回原 text 与 nil ref;
- 超过 → spill,返回 head/tail 预览与 ref;
- 保存失败 best-effort:保留原 text,返回错误(调用方决定是否视为 isError)。
type SpillSource ¶
type SpillSource struct {
// ToolName 产生结果的工具名。
ToolName string `json:"toolName"`
// CallID 结果所属的模型调用 id。
CallID brand.ToolCallID `json:"callId"`
// Label 工件简短标签。
Label string `json:"label"`
}
SpillSource 是产生某溢出工件的工具与调用(仅用于起名/检视,不用于访问控制)。
type SpillStore ¶
type SpillStore interface {
// SaveText 原样持久化完整 content;真实存储失败时返回错误。
SaveText(input SaveTextSpill) (SpillRef, error)
}
SpillStore 是 `ctx.spillStore` 的单方法抽象服务。
Click to show internal directories.
Click to hide internal directories.