Agent-Squad/squad/planner.go

package squad

import (
	"context"
	"fmt"
	"time"
)

// Planner 规划器：把 Goal 翻译为小队编制 + 工作流，或在信息不足时请求澄清。
// 规划器只做规划，不执行；执行归 SquadEngine。
type Planner interface {
	Name() string
	Plan(ctx context.Context, input PlanInput) (*PlanOutput, error)
}

// PlanInput 规划输入。
type PlanInput struct {
	Goal      Goal
	Blueprint *Blueprint // 命中模板时非 nil（基线步骤，规划器可微调）
	Registry  *RoleRegistry
	RunID     string
	// IntentCatalog 可选能力目录：启用意图编排时非 nil。规划者应把命中目录的
	// 子任务输出为 intent_id 步骤（必填槽位不足时改输出澄清，用目录的提问建议）。
	IntentCatalog *IntentCatalog
}

// PlanOutput 规划输出：计划或澄清请求二选一。
type PlanOutput struct {
	// Clarification 非 nil 时表示目标信息不足，引擎进入 awaiting_clarification。
	Clarification *Clarification
	// Plan 编制 + 工作流。
	Plan *SquadPlan
	// NeedsConfirmation 为 true 时计划先进入 awaiting_confirmation。
	NeedsConfirmation bool
	// ConfirmReason 计划需要确认的原因（高风险/写操作/超预算等）。
	ConfirmReason string
}

// SquadPlan 一次规划产物。
type SquadPlan struct {
	Squad    SquadConfig  `json:"squad"`
	Workflow WorkflowPlan `json:"workflow"`
	Template string       `json:"template,omitempty"` // 交付物骨架（蓝图携带或规划器生成）
}

// Clarification 澄清请求：问题 + 可选建议选项。
type Clarification struct {
	Reason    string     `json:"reason"`
	Questions []Question `json:"questions"`
}

// Question 单个澄清问题。
type Question struct {
	ID      string        `json:"id"`
	Text    string        `json:"text"`
	Options []HumanOption `json:"options,omitempty"`
}

// NewPlanID 生成工作流 ID。
func NewPlanID() string {
	return fmt.Sprintf("wf_%d", time.Now().UnixNano())
}