spill

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 9 Imported by: 0

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 NewFileStore

func NewFileStore(root string) *FileSpillStore

NewFileStore 创建本地文件后端。

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 渲染。

func (SpillLocator) String

func (l SpillLocator) String() string

String 返回句柄原始串(for fmt/logging)。

type SpillOwner

type SpillOwner struct {
	// SessionID 产生该工件的会话 id。
	SessionID brand.SessionID `json:"sessionId"`
}

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` 的单方法抽象服务。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL