protocol

type ChartEdge struct {
	From   string `json:"from"`
	To     string `json:"to"`
	Label  string `json:"label,omitempty"`
	Status string `json:"status,omitempty"` // ok|warn|down|空
}

type ChartEvent struct {
	Time   string `json:"time,omitempty"`
	Label  string `json:"label"`
	Status string `json:"status,omitempty"` // ok|warn|down|空（漂移词在解码期归一）
	Desc   string `json:"desc,omitempty"`
}

type ChartItem struct {
	Label string  `json:"label"`
	Value float64 `json:"value"`
}

type ChartNode struct {
	ID     string `json:"id"`
	Label  string `json:"label"`
	Status string `json:"status,omitempty"` // ok|warn|down|空（漂移词在解码期归一）
	Group  string `json:"group,omitempty"`  // 分层/分区名（接入层/应用层…）
}

type ChartPoint struct {
	T string  `json:"t,omitempty"`
	V float64 `json:"v"`
}

type ChartSeries struct {
	Label  string       `json:"label"`
	Points []ChartPoint `json:"points"`
}

type ChartSpec struct {
	Type   string        `json:"type"` // pie|line|bar|topo|timeline（空=无效 spec，调用方跳过）
	Title  string        `json:"title,omitempty"`
	Unit   string        `json:"unit,omitempty"`
	Items  []ChartItem   `json:"items,omitempty"`
	Series []ChartSeries `json:"series,omitempty"`
	Nodes  []ChartNode   `json:"nodes,omitempty"`  // type=topo 用
	Edges  []ChartEdge   `json:"edges,omitempty"`  // type=topo 用
	Events []ChartEvent  `json:"events,omitempty"` // type=timeline 用
}

type Evidence struct {
	Tool           string `json:"tool"`
	Snippet        string `json:"snippet"`
	Interpretation string `json:"interpretation"`
	ID             string `json:"id,omitempty"`
}

type ExploreGap struct {
	Aspect string `json:"aspect"`
	Query  string `json:"query,omitempty"`
}

type Followup struct {
	By   string `json:"by,omitempty"`
	What string `json:"what"`
	Why  string `json:"why,omitempty"`
}

type Rec struct {
	Action            string     `json:"action"` // kill_and_restart|tune|none
	Steps             StringList `json:"steps"`
	RequiresExecution bool       `json:"requires_execution"`
	RequiresApproval  bool       `json:"requires_approval"`
	ChangeRef         string     `json:"change_ref,omitempty"`    // 编目变更块 slug（可选）
	ChangeParams      StringMap  `json:"change_params,omitempty"` // 编目参数（string_list 值逗号分隔；容错解码见 StringMap）
	CuratedRisk       int        `json:"curated_risk,omitempty"`  // 编目声明风险档 1-4（引擎基线下限；LLM 评估只升不降）
}

type RenderOptions struct {
	// DefaultTitle AgentName 为空时的标题兜底。留空 = 用中性兜底「诊断报告」。
	DefaultTitle string
}

type Report struct {
	AgentName      string      `json:"agent_name"`
	Domain         string      `json:"domain"`
	Symptom        string      `json:"symptom"` // 首句须含「检测对象：」标注
	Conclusion     string      `json:"conclusion"`
	Evidence       []Evidence  `json:"evidence,omitempty"`
	Charts         []ChartSpec `json:"charts,omitempty"` // 可视化附件（占比→pie、时序→line、对比→bar、部署/依赖→topo、演进/时间线→timeline），畸形由 ChartSpec 容错
	Impact         string      `json:"impact,omitempty"`
	ImpactScopes   StringList  `json:"impact_scopes,omitempty"` // 受影响对象清单（批次一百三十七，结构化补缺：host/服务/pod 级；聚合去重合并）
	Severity       string      `json:"severity,omitempty"`      // 严重度 info|low|medium|high|critical（批次一百三十七；聚合取最高、dispute 钳 ≤medium；空=未评估）
	Recommendation *Rec        `json:"recommendation,omitempty"`
	RequestType    string      `json:"request_type,omitempty"` // 细粒度动作类别（风险分级用）
	Risk           string      `json:"risk,omitempty"`
	Rollback       string      `json:"rollback,omitempty"`
	RollbackSteps  StringList  `json:"rollback_steps,omitempty"`
	NeedsFollowup  StringList  `json:"needs_followup,omitempty"`
	Confidence     string      `json:"confidence"`          // high|medium|low
	Verdicts       Verdicts    `json:"verdicts,omitempty"`  // 合议裁决（workflow/verdict-judge 专属）
	Followups      []Followup  `json:"followups,omitempty"` // 结构化接力指令（批次一百二十七；引擎侧填写，非 LLM 输出字段）
	Meta           *StepMeta   `json:"meta,omitempty"`      // 环节执行元数据（批次一百二十七；引擎回填，非 LLM 输出字段）
	// ExploreGaps 勘探缺口（批次二百零八）：GE2 迭代勘探的综合环节输出通道——LLM 在
	// iterative_explore 开时按提示词输出，引擎按缺口发起受限续轮扇出。与 Followups 同属
	// 「特定流专属通道」，其余流出现即无消费方。
	ExploreGaps []ExploreGap `json:"explore_gaps,omitempty"`
	// Profile 报告形态档（批次二百一十七，引擎侧确定性填写，非 LLM 输出字段）：flow
	// 按轨设置，空=diagnosis 存量兼容。随 FinalReportJSON 落库，handler 受众投影
	// （view=summary 重渲染）因此自动按档分支，消费面零改动。
	Profile       ReportProfile `json:"profile,omitempty"`
	Summary       string        `json:"summary"`
	Scope         string        `json:"scope,omitempty"`    // in|out（kyaiops 扩展字段）
	Redirect      string        `json:"redirect,omitempty"` // scope=out 时的目标 slug，仅一层
	Decision      string        `json:"decision,omitempty"` // pending_approval|approved|rejected
	ExecutedSteps StringList    `json:"executed_steps,omitempty"`
	// AwaitingUser 待确认态专属标记（批次三百三十四，调度器 clarify 分支持位，非 LLM
	// 输出字段）：反问轮的回答不是诊断结论——渲染器以「待确认」替代「结论」标签，
	// 消除「要诊断哪个集群？」落 **结论** 体的生硬文案（可点选卡照常承担交互）。
	AwaitingUser bool `json:"awaiting_user,omitempty"`
	// Guidance 对话直答标记（引擎侧确定性填写，非 LLM 输出字段）：置位表示本条是
	// 调度引导/元问题/寒暄一类的对话回复而非诊断报告，markdown 走轻装视图
	// （不出 agent 标题与置信度）。内核不依赖任何命名约定判定该形态——判定依据
	// 由宿主通过本字段或 SetGuidanceAgentNames 注册，二选一。
	Guidance bool `json:"guidance,omitempty"`
}

type ReportProfile string

type ReportView string

type StepMeta struct {
	DurationMS int64 `json:"duration_ms,omitempty"`
	ToolCalls  int   `json:"tool_calls,omitempty"`
	Iterations int   `json:"iterations,omitempty"`
}

type StringList []string

type StringMap map[string]string

type Verdict struct {
	// Source 判定来源（DecisionSource 词表）。
	Source string `json:"source"`
	// Kind 置信语义种类（ConfidenceKind 词表）。
	Kind string `json:"confidence_kind"`
	// Value 判定结果（标签；语义由来源决定）。
	Value string `json:"value"`
	// Confidence 数值置信（0-1）。仅 kind=calibrated_distribution / self_reported 有意义。
	Confidence float64 `json:"confidence,omitempty"`
	// Ordinal 序数置信档（high|medium|low）。仅 kind=ordinal 有意义。
	Ordinal string `json:"confidence_ordinal,omitempty"`
	// Distribution 概率分布（候选 → 概率）；判定面给，生成面可空。
	Distribution map[string]float64 `json:"distribution,omitempty"`
	// Reason 一句话依据（可空）。
	Reason string `json:"reason,omitempty"`
}

type VerdictItem struct {
	Agent  string `json:"agent"`
	Stance string `json:"stance"` // adopt|dispute|reject
	Reason string `json:"reason,omitempty"`
	// EvidenceIDs 裁决依据的证据编号（批次一百三十七）：引用所依据报告的 evidence.id
	//（形如 specialists/memory-analysis#E2）——「引用证据说理」从 prompt 软要求升级为
	// 结构化引用通道；容忍单字符串/数组双形态（StringList 宽容解码），引用不存在的
	// 编号由引擎侧合并后校验（CheckEvidenceRefs），只在留痕面告警不拦截。
	EvidenceIDs StringList `json:"evidence_ids,omitempty"`
}

type Verdicts []VerdictItem