// Package promptkit defines the three-layer prompt assembly framework for
// Flyto Agent. Mirrors the public mechanism Claude Code uses internally:
// static base + conditional sections + runtime reminders.
//
// promptkit 包定义 Flyto Agent 的三层 prompt 装配框架. mirror Claude Code
// 内部公开机制: 静态基座 + 条件块 + 运行时 reminder.
//
// # Three layers
//
//	Layer 1 - BaseSections: always-on sections forming the cache-stable
//	          prefix. The engine places a cache_control marker after the
//	          last base section so prompt cache hits ~90% on subsequent
//	          turns. Examples: role identity, doing-tasks guidance, tone.
//	          始终在的 cache 稳定前缀, engine 在末尾打 cache_control marker
//	          让后续轮次 cache 命中率 ~90%. 例: 角色定位 / 任务流程 / 语气.
//
//	Layer 2 - ConditionalSections: evaluated once at session setup (NOT
//	          per-turn). Caller-defined predicates decide which sections
//	          fire. Examples: git status snapshot only when in git repo,
//	          MCP server instructions only when configured.
//	          会话启动时判定一次 (不每轮跑). 调用方定义条件谓词决定哪些段
//	          触发. 例: 检测到 git 仓库才加 git status, 配 MCP 才加 instructions.
//
//	Layer 3 - ReminderTriggers: runtime hooks that fire on engine-emitted
//	          events (tool result, file read, mtime drift, permission
//	          wait, token budget low, custom). Rendered text injects into
//	          the messages array (NOT system prompt) preserving cache
//	          stability. Wrapped in <system-reminder> XML tags by
//	          convention.
//	          运行时 hook, 在 engine 发出事件时触发 (tool 返回 / 文件读 /
//	          mtime 漂 / 权限等待 / token budget 紧张 / 自定义). 渲染文本注入
//	          messages 数组 (不进 system prompt) 保持 cache 稳定. 按惯例用
//	          <system-reminder> XML 标签包.
//
// # Why three layers
//
// Pre-ADR-0005 Flyto's engine baked Claude Code's coding-assistant
// content into the engine itself: 8-section system prompt unconditionally
// injected (~16KB), reminders re-injected per-turn even when SystemPrompt
// override claimed to bypass them, no prompt cache. This package abstracts
// the cc mechanism — caller fills content; framework owns assembly + cache
// boundary placement. First implementation: core/extra/preset-coding/
// (Claude Code preset). Second implementation (planned): preset-extraction
// for logistics quote extraction.
//
// ADR-0005 之前 Flyto 引擎硬塞 Claude Code 内容: 8 段无条件注入 (~16KB) /
// SystemPrompt 名义 override 仍每轮塞 reminder / 没接 prompt cache. 本包
// 抽象 cc 机制 — 调用方填内容, framework 负责装配 + cache 边界. 首个实现:
// core/extra/preset-coding/ (Claude Code preset). 计划第二实现:
// preset-extraction 给物流报价表抽取场景.
//
// # Escape hatch
//
// Callers who find this interface too rigid can bypass entirely via
// engine.Config.SystemPrompt (literal string sent to LLM, no decoration,
// no three-layer assembly). Mutually exclusive with cfg.PromptBundle.
// See ADR-0005 § 2.3 for the design rationale.
//
// 嫌接口僵硬的调用方可走 engine.Config.SystemPrompt 字符串路径绕过 (字面
// 字符串发给 LLM, 零装饰, 不走三层). 与 cfg.PromptBundle 互斥. 设计依据
// 见 ADR-0005 § 2.3.
//
// # See also
//
//   - ADR-0005 § 2.3 — interface signatures + escape hatch rationale.
//   - core/extra/preset-coding/ — first PromptBundle implementation.
//   - https://www.dbreunig.com/2026/04/04/how-claude-code-builds-a-system-prompt.html
//     — external reference for cc three-layer mechanism.
package promptkit