Documentation
¶
Overview ¶
本文件对应任务 M10:PromptContext 动态注册与快照。
对齐上游:packages/core/system-prompt/context-prompt
与 PromptSection 的差异:
- Section → system prompt 前缀,静态声明(M09);
- Context → user-msg 末尾追加的动态片段(如运行时上下文快照),可增删;
- compaction 删除老上下文后仍保留最新快照(change-only 持久化),保证可重建。
本文件对应任务 N05(D4 纪律):PromptContext change-only 注入 + Compaction 保留 snapshot。
对齐上游:packages/core/system-prompt/context-prompt + compaction
设计要点:
- 复用 M10 ContextRegistry 的 Compute()(状态变化时 hash 变 / 无变化时稳定);
- ChangeOnlyInjector:持久化"已注入的最后 hash",仅在 hash 变化时注入为新 user-msg, **不修改** system prompt(走 user-msg 追加);
- 状态变更(plan mode 切换 / goal 设置 / approval policy 变更)都走 user-msg 追加;
- CompactPreserve:compaction 后仍保留最后一次 context snapshot,供 derived messages 重建。
interpolate.go 复刻官方 system-prompt 的严格变量插值:把文本中完整的 {{name}} 组替换为 variables 中的值,变量名须为 [a-z][a-z0-9_]*,未知或无值 变量报错,替换进去的值不再二次扫描;没有后续 }} 的孤立 {{ 作为字面文本。
order_tools.go 复刻官方 system-prompt 的 orderTools:按配置顺序排列工具, 未在配置中列出的工具在 ToolOrderRest 标记处按名称插入;配置必须恰好包含一次 rest 标记、不得重复、不得引用不存在的工具名。
本文件对应任务 N03(D2 纪律):System Prompt 模板纯函数 + 静态检测。
对齐上游:packages/core/system-prompt/src/sections/*.ts
设计要点:
- 每个 Section 是**纯函数**:同一输入渲染 1000 次输出逐字节相同(不含 time.Now / os.Getwd / rand / 动态 env);
- StaticCheck 对 Section 文本做静态扫描,识别"会破坏 prefix cache"的动态值模式 (D2 反模式),0 violation 才算通过;
- SystemHash 对组装后的 system prompt 计算稳定哈希,用于跨轮比对(缓存友好验证), 并证明"同一配置下 system prompt 逐字节稳定"。
Package sysprompt 提供系统提示词(System Prompt)的 Section 注册与有序组装。
对齐上游:packages/core/system-prompt
设计要点:
- PromptSection{Name/Order/Text}:每个能力块是一个 Section,注册时给定固定的 order;
- Assembler 按 order 升序合并所有 Section,构成最终 system prompt;
- 顺序被写死为常量(对齐上游):persona → policy → runtime-context-snapshot → plan:policy → tools schema → skill catalog。顺序错误会导致模型行为漂移, 因此 order 必须来自常量字段而非运行时推导。
Index ¶
- Constants
- func CheckSections(a *Assembler) (violations []string, forbidden bool)
- func Interpolate(text string, variables map[string]string) (string, error)
- func IsPure(sectionText string) bool
- func OrderTools(names, configured []string) ([]string, error)
- func StaticCheck(text string) []string
- func StripBanned(s string) string
- func SystemHash(sys string) string
- func ToolsSectionText(toolList []*tools.Tool) (string, error)
- type Assembler
- type ChangeOnlyInjector
- type CompactPreserve
- type ContextRegistry
- func (r *ContextRegistry) Compute() (text string, hash string)
- func (r *ContextRegistry) LastHash() string
- func (r *ContextRegistry) Register(name string, order int, content string) bool
- func (r *ContextRegistry) SetLastHash(h string)
- func (r *ContextRegistry) Snapshot() map[string]string
- func (r *ContextRegistry) Unregister(name string)
- type GoalRoundContext
- type RuntimeContext
- type Section
Constants ¶
const ( // SectionOrderPersona 角色设定。 SectionOrderPersona = 100 // SectionOrderPolicy 通用策略。 SectionOrderPolicy = 200 // SectionOrderRuntimeContext 运行时上下文快照。 SectionOrderRuntimeContext = 300 // SectionOrderPlanPolicy 计划模式策略(仅在 plan mode 注入)。 SectionOrderPlanPolicy = 500 // SectionOrderToolsSchema 工具 JSON Schema。 SectionOrderToolsSchema = 600 // SectionOrderSkillCatalog 技能目录(D3 纪律:稳定序列化 + change-only 注入)。 SectionOrderSkillCatalog = 700 )
Section 顺序常量(数值即上游原始 order)。
const ClearedContextText = "Current runtime context: none. Earlier runtime-context snapshots no longer apply."
MightInject 对比 Compute() 哈希:变化时注入并返回文本,否则不注入。 ClearedContextText 是快照从有内容变为空时注入的"已清空"标记,让模型明确 知道此前的运行时上下文不再适用(而不是收到一条没有信息量的空消息)。
const ToolOrderRest = "<unlisted-tools>"
ToolOrderRest 是"其余工具"的保留标记。
Variables ¶
This section is empty.
Functions ¶
func CheckSections ¶
CheckSections 对组装器全部已注册 section 做静态检查,返回 (violations, forbidden). forbidden=true 表示存在任一违规(将破坏缓存)。
func Interpolate ¶
Interpolate 对 text 做严格变量插值。
func OrderTools ¶
OrderTools 按 configured 指定的顺序排列 names。
func StaticCheck ¶
StaticCheck 扫描一段 section 文本,返回命中的反模式说明(空表示无违规)。
func SystemHash ¶
SystemHash 计算组装后 system prompt 的稳定 sha256(proof of 纯函数/缓存稳定)。
Types ¶
type Assembler ¶
type Assembler struct {
// contains filtered or unexported fields
}
Assembler 是 Section 注册与有序组装器。
func (*Assembler) Assemble ¶
Assemble 将所有 Section 按 order 升序拼接为最终 system prompt。 相邻 Section 之间以一个空行分隔。
func (*Assembler) AssembleHash ¶
AssembleHash 返回组装器当前 prompt 的稳定哈希。
type ChangeOnlyInjector ¶
type ChangeOnlyInjector struct {
// contains filtered or unexported fields
}
ChangeOnlyInjector 是 PromptContext 的 change-only 注入器。 记录最近一次已注入的 hash;Compute() 的 hash 未变则不注入。
func NewChangeOnlyInjector ¶
func NewChangeOnlyInjector(reg *ContextRegistry, persistedHash string) *ChangeOnlyInjector
NewChangeOnlyInjector 创建变更注入器(可传入持久化的 lastHash 恢复跨轮状态)。
func (*ChangeOnlyInjector) InjectCount ¶
func (in *ChangeOnlyInjector) InjectCount() int
InjectCount 返回累计注入次数。
func (*ChangeOnlyInjector) LastHash ¶
func (in *ChangeOnlyInjector) LastHash() string
LastHash 返回已注入的 last hash(供持久化恢复)。
func (*ChangeOnlyInjector) MightInject ¶
func (in *ChangeOnlyInjector) MightInject() (text string, injected bool)
type CompactPreserve ¶
type CompactPreserve struct {
// contains filtered or unexported fields
}
CompactPreserve 是"保留最后一次 context snapshot"的 compaction 辅助。 compaction 删除老上下文节点后,仍可通过 last 恢复最新的 user-msg 追加。
func (*CompactPreserve) Latest ¶
func (c *CompactPreserve) Latest() (text, hash string, ok bool)
Latest 返回保留的最后一次 snapshot(compaction 后仍可用)。
func (*CompactPreserve) Record ¶
func (c *CompactPreserve) Record(text, hash string)
Record 记录一次计算出的 snapshot(覆盖为最新)。
type ContextRegistry ¶
type ContextRegistry struct {
// contains filtered or unexported fields
}
ContextRegistry 是 PromptContext 注册表 + 快照哈希。
func (*ContextRegistry) Compute ¶
func (r *ContextRegistry) Compute() (text string, hash string)
Compute 按 order 升序拼接全部上下文片段(确定性),并计算稳定哈希。
func (*ContextRegistry) LastHash ¶
func (r *ContextRegistry) LastHash() string
LastHash 返回最近一次 Compute 的哈希(用于 change-only 注入判断)。
func (*ContextRegistry) Register ¶
func (r *ContextRegistry) Register(name string, order int, content string) bool
Register 注册(或更新)一个上下文片段。返回是否发生变化(hash diff)。
func (*ContextRegistry) SetLastHash ¶
func (r *ContextRegistry) SetLastHash(h string)
SetLastHash 记录已注入的哈希(避免重复注入)。
func (*ContextRegistry) Snapshot ¶
func (r *ContextRegistry) Snapshot() map[string]string
Snapshot 返回当前全部片段的稳定快照(change-only 持久化用)。
func (*ContextRegistry) Unregister ¶
func (r *ContextRegistry) Unregister(name string)
Unregister 移除一个上下文片段。
type GoalRoundContext ¶
type GoalRoundContext struct {
// Active 目标是否处于活跃状态。
Active bool
// Round 当前轮次。
Round int
// GoalDesc 目标描述。
GoalDesc string
}
GoalRoundContext 是目标续轮的动态上下文(goal.active 时注入,完成时停止)。
func (*GoalRoundContext) Render ¶
func (g *GoalRoundContext) Render() string
Render 渲染续轮提示文本(goal.active 时才有内容)。
type RuntimeContext ¶
type RuntimeContext struct {
// Name 唯一标识。
Name string
// Order 排序(决定在 user-msg 末尾的拼接顺序)。
Order int
// Content 动态内容(由调用方每次提供最新快照)。
Content string
}
RuntimeContext 是动态上下文片段(注册表管理,增删即生效)。