agentcontinuity

package
v0.3.1 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package agentcontinuity 实现 Agent 连续工作的产品编排层。

Continuity Pack 是 runtime context 的产品 projection,不创建第二套 memory ranking、ledger 或 source resolver。它只编排 scope resolution、 handoff selection、context compilation、source coverage、budget truncation 和 safe next actions。

Index

Constants

View Source
const (
	// PackStatusReady 表示 handoff、决策与来源均可解析且无冲突。
	PackStatusReady = "ready"
	// PackStatusPartial 表示部分来源 missing/stale、存在 conflict 或
	// handoff 缺失;其余可信 section 保留。
	PackStatusPartial = "partial"

	// EvidenceStatusResolved 表示全部 source 成功解析。
	EvidenceStatusResolved = "resolved"
	// EvidenceStatusPartial 表示至少一个 source stale/missing/ambiguous。
	EvidenceStatusPartial = "partial"
	// EvidenceStatusNotMeasured 表示 total=0(不得当成 100%)。
	EvidenceStatusNotMeasured = "not_measured"

	// FreshnessStatusFresh 表示最新 evidence 在 freshness policy 内。
	FreshnessStatusFresh = "fresh"
	// FreshnessStatusStale 表示 evidence observed/revision time 超出 policy。
	FreshnessStatusStale = "stale"
	// FreshnessStatusNotMeasured 表示没有可计算 freshness 的 evidence。
	FreshnessStatusNotMeasured = "not_measured"

	// FreshnessPolicy 是 evidence freshness 策略窗口(14 天)。
	FreshnessPolicy = 14 * 24 * time.Hour
)

状态常量(additive English enum values,machine contract 稳定)。

View Source
const (
	WarningHandoffMissing   = "handoff_missing"
	WarningDecisionConflict = "decision_conflict"
	WarningSourceMissing    = "source_missing"
	WarningSourceStale      = "source_stale"
	WarningSourceAmbiguous  = "source_ambiguous"
	WarningContextDegraded  = "context_degraded"
	WarningBindingMissing   = "binding_missing"
	WarningReviewAttention  = "review_attention"
	// WarningReviewAttentionUnavailable 表示 inbox 状态不可读(IO/store 故障),
	// 0 条 review attention 是"未测量"而不是"没有待办"。
	WarningReviewAttentionUnavailable = "review_attention_unavailable"
)

稳定 warning code(Resume Card 展示;conflict/source warning 不得被 budget 丢弃,排序固定以便 golden test)。

View Source
const ContinuitySchemaVersion = "yeisme.agent_continuity.v1"

ContinuitySchemaVersion 是 continuity pack 的 schema 版本。

Variables

This section is empty.

Functions

func SummaryLine

func SummaryLine(pack ContinuityPack) string

SummaryLine 返回 pack 的一行摘要(用于 human output)。

Types

type ContinuityBudget

type ContinuityBudget struct {
	MaxItems   int `json:"max_items"`
	MaxChars   int `json:"max_chars"`
	MaxSources int `json:"max_sources"`
}

ContinuityBudget 限制 continuity pack 的 section 大小。

func DefaultBudget

func DefaultBudget() ContinuityBudget

DefaultBudget 返回合理的默认 budget。

type ContinuityPack

type ContinuityPack struct {
	SchemaVersion string                  `json:"schema_version"`
	Principal     agentprotocol.Principal `json:"principal"`
	Scope         agentprotocol.Scope     `json:"scope"`
	Task          string                  `json:"task,omitempty"`
	// Objective 来自最近的 handoff 或 scope 推断。
	Objective string `json:"objective,omitempty"`
	// CurrentState 描述任务当前进度。
	CurrentState string `json:"current_state,omitempty"`
	// Sections 按 kind 组织的 bounded sections。
	Sections []ContinuitySection `json:"sections"`
	// Conflicts 描述当前 scope 的记忆冲突。
	Conflicts []agentprotocol.ContextConflict `json:"conflicts,omitempty"`
	// Sources 引用的来源(bounded,不含 body)。
	Sources agentprotocol.SourceRefList `json:"sources,omitempty"`
	// SourceCoverage 描述来源解析情况。
	SourceCoverage SourceCoverage `json:"source_coverage"`
	// HandoffStatus 表示 handoff 的可用性。
	HandoffStatus HandoffStatus `json:"handoff_status"`
	// HandoffID 是被消费的 handoff ID(如有)。
	HandoffID string `json:"handoff_id,omitempty"`
	// Truncated 表示 pack 是否被 budget 截断。
	Truncated bool `json:"truncated"`
	// Freshness 是支持本 pack 的最新 evidence 的 observed/revision 时间。
	// 没有任何 evidence 时为零值;生成时刻见 GeneratedAt。
	Freshness time.Time `json:"freshness"`
	// GeneratedAt 是本次响应的生成时刻(additive;不得冒充 evidence freshness)。
	GeneratedAt time.Time `json:"generated_at,omitempty"`
	// FreshnessStatus 是 freshness 相对 policy 的状态(fresh|stale|not_measured)。
	FreshnessStatus string `json:"freshness_status,omitempty"`
	// EvidenceStatus 是 source evidence 的整体状态(resolved|partial|not_measured)。
	EvidenceStatus string `json:"evidence_status,omitempty"`
	// PackStatus 是 pack 整体状态(ready|partial)。
	PackStatus string `json:"pack_status,omitempty"`
	// WarningCodes 是稳定 warning 分类(bounded,固定排序)。
	WarningCodes []string `json:"warning_codes,omitempty"`
	// RecommendedNextAction 是首屏唯一推荐的下一步;其余 actions 在 NextActions。
	RecommendedNextAction *agentprotocol.NextAction `json:"recommended_next_action,omitempty"`
	// ReviewAttentionCount 是与当前 continuation 相关的 review item 数。
	ReviewAttentionCount int `json:"review_attention_count,omitempty"`
	// ReviewAttention 是唯一 inline 提示的 bounded review item(≤1)。
	ReviewAttention *ReviewAttention `json:"review_attention,omitempty"`
	// ReviewAttentionUnavailable 表示 inbox 状态不可读:0 条 attention 是
	// 未测量而非没有待办,receipt 必须携带 warning code 以区分两者。
	ReviewAttentionUnavailable bool `json:"review_attention_unavailable,omitempty"`
	// BindingStatus 是 binding 解析状态(additive,由 app 层填充)。
	BindingStatus string `json:"binding_status,omitempty"`
	// BindingIDDigest 是解析到的 binding 的 bounded digest(additive)。
	BindingIDDigest string `json:"binding_id_digest,omitempty"`
	// ContinuityRunID 是 opt-in recorded run 的 opaque ID(仅 --record-run)。
	ContinuityRunID string `json:"continuity_run_id,omitempty"`
	// NextActions 是安全的 drill-down 操作建议。
	NextActions []agentprotocol.NextAction `json:"next_actions,omitempty"`
	// Experimental 标记此 surface 为实验性。
	Experimental bool `json:"experimental"`
}

ContinuityPack 是 orchestrator 产出的 bounded 产品 projection。 它包含目标、关键决策、偏好、未完成事项、失败经验、冲突、来源和下一步命令。 完整 note body、完整 transcript、raw prompt 与 provider payload 永不进入。

func (ContinuityPack) AssertNoBody

func (p ContinuityPack) AssertNoBody(maxItemChars int) error

AssertNoBody 检查 pack 是否泄漏了看起来像完整 body 的大段文本。

func (*ContinuityPack) RefreshDerived added in v0.3.0

func (p *ContinuityPack) RefreshDerived()

RefreshDerived 重新计算 FreshnessStatus/EvidenceStatus/PackStatus、 WarningCodes 和 RecommendedNextAction。

状态与排序规则(deterministic,中文注释):

  1. warning 顺序固定:handoff_missing → decision_conflict → source_missing → source_stale → source_ambiguous → context_degraded → review_attention。conflict/source warning 是风险信号,不被 budget 截断,任何 renderer 不得丢弃。
  2. evidence_status:total=0 → not_measured;存在任何 unresolved → partial;全部 resolved → resolved。
  3. freshness_status:无 evidence → not_measured;最新 evidence 超出 FreshnessPolicy(14 天)→ stale;否则 fresh。生成时刻不参与判断。
  4. pack_status:handoff 缺失、存在 conflict 或 evidence 非 resolved → partial;其余 ready。partial 不丢弃可信 section。
  5. recommended_next_action 只取一个:handoff 缺失优先给 checkpoint action(context-only resume 的恢复路径),其次 conflict、source、 review attention,最后回退到第一个 drill-down action。

func (ContinuityPack) SectionCount

func (p ContinuityPack) SectionCount() int

SectionCount 返回所有 section 的 item 总数。

type ContinuityRequest

type ContinuityRequest struct {
	SchemaVersion string                  `json:"schema_version"`
	Principal     agentprotocol.Principal `json:"principal"`
	Scope         agentprotocol.Scope     `json:"scope"`
	Task          string                  `json:"task,omitempty"`
	// Intent 描述用户意图(可选),用于 entity boosting。
	Intent string `json:"intent,omitempty"`
	// Budget 限制 continuity pack 的大小。
	Budget ContinuityBudget `json:"budget"`
	// HandoffID 显式指定要消费的 handoff;空则自动选择最近可消费 handoff。
	HandoffID string `json:"handoff_id,omitempty"`
}

ContinuityRequest 描述一次 continuity compilation 请求。 Principal 和 Scope 必须显式提供;intent/task 可选。

func (ContinuityRequest) Validate

func (r ContinuityRequest) Validate() error

Validate 检查 request 必填字段。

type ContinuitySection

type ContinuitySection struct {
	Kind      string   `json:"kind"`
	Title     string   `json:"title"`
	Items     []string `json:"items,omitempty"`
	Truncated bool     `json:"truncated,omitempty"`
	Omitted   int      `json:"omitted,omitempty"`
}

ContinuitySection 是 continuity pack 中的一个 bounded section。

type HandoffStatus

type HandoffStatus string

HandoffStatus 表示 handoff 在 continuity 中的可用状态。

const (
	// HandoffStatusConsumed 表示找到了可消费的 handoff。
	HandoffStatusConsumed HandoffStatus = "consumed"
	// HandoffStatusMissing 表示没有匹配的 handoff,degrade to context-only。
	HandoffStatusMissing HandoffStatus = "missing"
	// HandoffStatusExplicit 表示用户显式指定了 handoff。
	HandoffStatusExplicit HandoffStatus = "explicit"
	// HandoffStatusDegraded 表示 handoff 存在但 adapter degraded。
	HandoffStatusDegraded HandoffStatus = "degraded"
)

type Orchestrator

type Orchestrator struct {
	// contains filtered or unexported fields
}

Orchestrator 编译 bounded continuity pack。 它只编排 scope resolution、handoff selection、context compilation、 source coverage、budget truncation 和 safe next actions。 不创建第二套 memory ranking、ledger 或 source resolver。

func NewOrchestrator

func NewOrchestrator(store *agentmemory.Store, compiler *agentcontext.Compiler) *Orchestrator

NewOrchestrator 构造 orchestrator。

func (*Orchestrator) Compile

Compile 执行 continuity compilation 管线。

type ReviewAttention added in v0.3.0

type ReviewAttention struct {
	ItemID      string   `json:"item_id"`
	Subject     string   `json:"subject"`
	ReasonCodes []string `json:"reason_codes"`
	Risk        string   `json:"risk"`
}

ReviewAttention 是与当前 continuation 相关的单个 bounded review 提示。 不含 proposal body;只有会改变 objective/decision/blocker/conflict/ recommended next action 的 pending item 才能进入。

type SourceCoverage

type SourceCoverage struct {
	// Total 是 pack 引用的来源总数。
	Total int `json:"total"`
	// Resolved 是成功解析的来源数。
	Resolved int `json:"resolved"`
	// Missing 是无法解析的来源数。
	Missing int `json:"missing"`
	// Stale 是存在但过期的来源数。
	Stale int `json:"stale"`
	// Ambiguous 是 ref 不能唯一解析的来源数(additive)。
	Ambiguous int `json:"ambiguous,omitempty"`
}

SourceCoverage 描述 continuity pack 中来源的解析情况。 Ambiguous 是 additive optional 分桶:ref 不能唯一解析时计入, 同时整体视为 unresolved;旧 total/resolved/missing/stale 语义不变。

func (SourceCoverage) ResolvableRatio

func (sc SourceCoverage) ResolvableRatio() float64

ResolvableRatio 返回来源可解析比例。

Jump to

Keyboard shortcuts

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