Agent-Intent/intent/result.go

package intent

// Branch 识别分支。前两级命中即短路返回；rules 过阈后按置信度裁决。
type Branch string

const (
	// BranchGuardHit 守卫域命中（Stage 0）。典型用途是"识别即拒绝"：宿主拿到
	// 守卫意图后拒绝执行并给出引导，而不是把输入交给后续通道。
	BranchGuardHit Branch = "guard_hit"
	// BranchExpectationHit 会话挂起预期命中（Stage 1）。多轮澄清场景：
	// 宿主在上一轮声明了预期意图，本轮输入命中其中一个。
	BranchExpectationHit Branch = "expectation_hit"
	// BranchMatched 唯一意图以足够置信度过阈（Stage 3）。
	BranchMatched Branch = "matched"
	// BranchAmbiguous 多个候选过阈且分数贴近。宿主可澄清、交由 Classifier 或回落自由通道。
	BranchAmbiguous Branch = "ambiguous"
	// BranchFallback 无意图过阈。正常结果：交给宿主默认通道（如 agent 自由任务）。
	BranchFallback Branch = "fallback"
)

// Candidate 单个意图候选。Slots 与 MissingRequiredSlots 只在构成
// Top 候选时填充（含槽位抽取成本控制）；Candidates 列表内其余候选不抽槽位。
type Candidate struct {
	ID                   string
	Domain               string
	Version              int
	Confidence           float64
	Priority             int
	Risk                 string
	RequiresConfirm      bool
	Handler              string
	Metadata             map[string]string
	Slots                map[string]string
	MissingRequiredSlots []string
	// InvalidSlots 捕获到但未通过确定性校验的槽位（key→原因，如枚举不合法）。
	// 必填且非法只进此处（不重复进 Missing），宿主可区分"没给"与"给错了"。
	InvalidSlots map[string]string
	// Action 是 spec 的显式动作声明（I1 WP2），随候选透传；nil 表示未声明，
	// ActionRef 推导回落 blueprint/Handler/auto 顺序。
	Action *ActionRef
	// Reason 命中解释：命中词与模式，供宿主审计与 intentctl explain 复用。
	Reason string
}

// Result 识别结果。Query 语义：纯函数式、无副作用；error 只表示系统级失败，
// BranchFallback 是正常识别结果。
type Result struct {
	Input            string
	Branch           Branch
	Top              *Candidate
	Candidates       []Candidate
	SnapshotRevision int64
	// Commands 是把本结果展开的路由指令列表（I1 命令化识别）；
	// 可能为空（fallback / guard_hit / 宿主默认通道）。Branch 与 Top 保留，
	// 供诊断与尚未迁移到命令的消费方使用。
	Commands []Command
}

// ScoredSpec 诊断用：单个 spec 在某个阶段的得分与命中明细。
type ScoredSpec struct {
	ID          string
	Score       float64
	HitTerms    []string
	HitPatterns []string
}

// RejectedSpec 诊断用：被排除的 spec 与原因。
type RejectedSpec struct {
	ID     string
	Reason string
}

// ExpectationTrace 诊断用：挂起预期阶段的输入与结果。
type ExpectationTrace struct {
	PendingIDs []string
	HitID      string
}

// Trace 是 Snapshot.Explain 的输出：各阶段裁决轨迹。确定性、不含时间信息。
type Trace struct {
	InputLen        int
	Branch          Branch
	TopID           string
	Guard           []ScoredSpec
	GuardRejected   []RejectedSpec
	Expectation     *ExpectationTrace
	Rules           []ScoredSpec
	RulesRejected   []RejectedSpec
	AmbiguityMargin float64
}