promptkit

type BuildContext struct {
	// Cwd is the engine's working directory.
	// 引擎工作目录.
	Cwd string

	// ModelFamily is a coarse model classifier (e.g. "claude", "openai",
	// "qwen"). Used by sections that adjust phrasing per model family.
	// 模型粗分类 (e.g. "claude" / "openai" / "qwen"). 给按模型家族调整措辞的段用.
	ModelFamily string

	// Language is an optional language hint (e.g. "zh-CN", "en-US").
	// Empty = caller didn't specify; section may default.
	// 可选语言提示. 空 = 调用方未指定, 段可默认.
	Language string

	// HasGitRepo: a git repository was detected at or above Cwd.
	// 在 Cwd 或祖先目录检测到 git 仓库.
	HasGitRepo bool

	// HasMCPServer: at least one MCP server is configured.
	// 至少配了一个 MCP server.
	HasMCPServer bool

	// HasFLYTOMD: a FLYTO.md file was found in any of the standard
	// search locations (project root, cwd, ~/.flyto/).
	// 在标准搜索位置 (项目根 / cwd / ~/.flyto/) 找到 FLYTO.md.
	HasFLYTOMD bool

	// Custom is for caller-defined predicates. Section implementations
	// type-assert keys they recognize.
	// 调用方自定义谓词. Section 实现按识别的 key 做类型断言.
	Custom map[string]any
}

type Context = BuildContext

type Event struct {
	// Type identifies which TriggerEvent fired.
	// 触发的事件类型.
	Type TriggerEvent

	// ToolName is set for EventToolResult / EventFileRead.
	// 给 EventToolResult / EventFileRead 用.
	ToolName string

	// FilePath is set for EventFileRead / EventFileMTimeDrift.
	// 给 EventFileRead / EventFileMTimeDrift 用.
	FilePath string

	// Payload carries event-specific data. Trigger implementations
	// type-assert keys they recognize.
	// 事件特定数据. Trigger 实现按识别的 key 做类型断言.
	Payload map[string]any

	// Custom is the discriminator for EventCustom sub-types.
	// EventCustom 子类型的区分字符串.
	Custom string
}

type PromptBundle interface {
	// BaseSections returns the cache-stable always-on prefix.
	// Engine places cache_control marker after the last base section.
	//
	// 始终在的 cache 稳定前缀. engine 在末尾打 cache_control marker.
	BaseSections() []Section

	// ConditionalSections evaluates trigger predicates once at session
	// setup (NOT per-turn) and returns sections whose condition matched.
	//
	// 会话启动时判定一次 (不每轮跑), 返回触发段.
	ConditionalSections(ctx BuildContext) []Section

	// ReminderTriggers returns runtime reminder hooks. Engine fires them
	// on matching events and injects rendered content into messages array.
	//
	// 运行时 reminder hook. engine 在匹配事件触发, 注入 messages 数组.
	ReminderTriggers() []Trigger
}

type Section interface {
	// Name returns a stable identifier for debugging and cache-key derivation.
	// Implementations should return the same value across the process lifetime.
	//
	// 稳定标识符, 用于调试和 cache key 派生. 实现者应返回进程生命期不变的值.
	Name() string

	// Render produces the text content. Context carries cwd, model family,
	// language, etc. — engine-provided invariants, NOT domain content.
	// Empty string return is legal (signals "section produces nothing this time").
	//
	// 产出文本. Context 带 cwd / model family / language 等 engine 提供的不变量,
	// 不带 domain 内容. 返回空串合法 (表示"本次此段不产出").
	Render(ctx Context) (string, error)
}

type SectionRenderError struct {
	Layer   string
	Section string
	Cause   error
}

type Trigger interface {
	// On returns the event type this trigger listens for.
	//
	// 监听的事件类型.
	On() TriggerEvent

	// Inject decides whether to fire on this specific event instance and
	// returns the reminder text if firing. Empty string = skip.
	// Returned text is wrapped by the engine in <system-reminder> tags.
	//
	// 决定是否在此具体事件触发, 返回 reminder 文本; 空串 = 跳过.
	// 返回文本由 engine 包 <system-reminder> 标签.
	Inject(evt Event) string
}

type TriggerEvent int