config

type AgentConfig struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`

	// 执行画像 A 类(model/loop/reliability/digest/steps),agent 自己这一层:
	// 既配主循环,也作为其 component 的降级源。
	Profile `yaml:",inline"`

	Prompt       PromptConfig       `yaml:"prompt"`       // 提示词分层(L1 loop / L2 system)
	Capabilities CapabilitiesConfig `yaml:"capabilities"` // 能力选品 + 内置开关

	// Stores/Retrievers 是具名实例声明(仅定义);模块块的 store/retriever
	// 槽用 cap://store/... · cap://retriever/... 引用它们(见 StoreInstance)。
	Stores     []StoreInstance     `yaml:"stores"`
	Retrievers []RetrieverInstance `yaml:"retrievers"`

	// 会话状态(主循环专属,component 无状态调用没有):
	Session SessionConfig `yaml:"session"`
	Memory  MemoryConfig  `yaml:"memory"`
	Todo    TodoConfig    `yaml:"todo"`

	// 治理边界(Ring 0,agent 独占、不被 namespace 覆盖):审批 + 预算 +
	// 结构化输出,三块各自顶层。
	Approval ApprovalConfig `yaml:"approval"`
	// Delegate 启用动态委派(builtin delegate 工具):模型运行期把子任务
	// 委派给隔离子循环,治理面见 skill.DelegateConfig。缺省关。
	Delegate         skill.DelegateConfig  `yaml:"delegate"`
	Budget           BudgetConfig          `yaml:"budget"`
	StructuredOutput loop.StructuredConfig `yaml:"structured_output"`
}

type AgentFile struct {
	AgentConfig `yaml:",inline"`
	// Namespaces 是关联的 namespace 挂载(相对本文件),自动挂载其全部
	// 导出 skill;capabilities.exclude 可屏蔽个别。每个挂载可携带 per-mount
	// 覆盖画像(最高优),兼容裸字符串写法(仅路径),见 NamespaceMount。
	Namespaces []NamespaceMount `yaml:"namespaces"`
}

type AgentSpec struct {
	AgentFile
	Path   string
	Mounts []Mount
}

type App struct {
	Agents  map[string]*agent.Agent
	Catalog *source.Catalog
	Prompts *prompt.Resolver
	Server  *serving.Server // serving 未配置时为 nil
	// AgentMounts 是多文件路径下各 agent 的挂载目录(关联 namespaces
	// 导出的 skills),供巡检与调试;单文件路径为 nil。
	AgentMounts map[string]*source.Catalog
}

type AppConfig struct {
	Secrets SecretsConfig `yaml:"secrets"`

	Prompts PromptsConfig `yaml:"prompts"`

	// Sources 是全局兼容源(直挂 agent 工具面的通用工具,如 fs)。
	Sources []SourceConfig `yaml:"sources"`
	Catalog CatalogConfig  `yaml:"catalog"`

	// 执行画像基线(app 层)。model 取代原 default_model。
	Profile `yaml:",inline"`

	// Stores 是 app 层具名存储实例(全局共享后端,如所有 agent 共用一个
	// redis session 实例);agent 层可再声明私有实例。
	Stores     []StoreInstance     `yaml:"stores"`
	Retrievers []RetrieverInstance `yaml:"retrievers"`

	// DefaultModelLegacy:default_model 已改名 model(执行画像内嵌),
	// 旧键装配期报错指路。
	DefaultModelLegacy *ModelConfig `yaml:"default_model"`

	// 会话状态 / 治理边界的 app 层默认(可选,agent 未声明整块时回落至此)。
	Session          SessionConfig         `yaml:"session"`
	Memory           MemoryConfig          `yaml:"memory"`
	Todo             TodoConfig            `yaml:"todo"`
	Approval         ApprovalConfig        `yaml:"approval"`
	Budget           BudgetConfig          `yaml:"budget"`
	StructuredOutput loop.StructuredConfig `yaml:"structured_output"`

	// Agents 是 agent 文件路径列表,相对 app.yaml 所在目录。
	Agents []string `yaml:"agents"`

	Serving  ServingConfig   `yaml:"serving"`
	Channels []ChannelConfig `yaml:"channels"`
	Suspend  SuspendConfig   `yaml:"suspend"`

	// Skillpacks 是外部技能包策略(全 app 一份,namespace 里的 use: 链接同样生效)。
	Skillpacks SkillpacksConfig `yaml:"skillpacks"`
	// Models 是具名模型(skillpack frontmatter `model:` 按名引用)。
	Models []NamedModelConfig `yaml:"models"`
	Exec   ExecConfig         `yaml:"exec"`

	Observability ObservabilityConfig `yaml:"observability"`

	// StateDir 同单文件 Config.StateDir:可写运行状态目录。
	StateDir string `yaml:"state_dir"`
	// WorkDirLegacy:旧键 work_dir 装配期报错指路 state_dir。
	WorkDirLegacy *string `yaml:"work_dir"`
}

type AppSpec struct {
	App    AppConfig
	Agents []*AgentSpec
	Root   fs.FS
}

type ApprovalConfig struct {
	Mode                string           `yaml:"mode"` // interactive(默认) | auto | deny
	loop.ApprovalPolicy `yaml:",inline"` // remember, rules
	Store               string           `yaml:"store"`
	StoreConfig         map[string]any   `yaml:"store_config"`
}

type BudgetConfig struct {
	loop.BudgetConfig `yaml:",inline"` // max_model_calls, max_tokens
	Store             string           `yaml:"store"`
	StoreConfig       map[string]any   `yaml:"store_config"`
}

type BuildOptions struct {
	// Interactor 是 agent 的默认交互通道(CLI 场景传 interact.NewCLI());
	// IM 通道会在各自会话里覆盖它。
	Interactor runctx.Interactor
	// ExtraCapabilities 是代码侧构造的能力(local.Func、rpctool、子 agent),
	// 以 "local" source 入目录。
	ExtraCapabilities []capability.Capability
	Logger            *slog.Logger
}

type CapabilitiesConfig struct {
	Include []string `yaml:"include"`
	Exclude []string `yaml:"exclude"`
	AskUser *bool    `yaml:"ask_user"` // 内置交互能力(默认开,显式 false 关闭)
	// GoalCheck 开启目标达成核对(U4.1):多步任务收尾前强制一次"对照原始
	// 目标逐条自查"的重生成。**默认关**——真机 A/B 显示强模型 + 中等难度
	// 任务上,强制重生成可能丢内容、净负;价值在弱模型/更难/高风险任务上,
	// 待 eval 定位后再考虑放开默认。显式 true 开启。
	GoalCheck *bool `yaml:"goal_check"`
}

type CatalogConfig struct {
	MaxRisk string `yaml:"max_risk"` // 准入上限,默认 mutating(dangerous 不入目录)
}

type ChannelConfig struct {
	Name           string `yaml:"name"`
	Type           string `yaml:"type"`
	Agent          string `yaml:"agent"`
	SessionMapping string `yaml:"session_mapping"` // chat | chat_user
	ReplyMode      string `yaml:"reply_mode"`      // text | card | stream(无装饰器时的默认策略)
	// Placeholder 是 processing 占位文案(空 = 内置英文默认「⏳ Working…」)。
	Placeholder string `yaml:"placeholder"`
	// Texts 覆盖面向用户的文案(键 = serving.Texts 字段的 snake_case,如
	// placeholder/stopped/approval;空字段回落英文默认)。IM 部署在此配
	// 本地化文案。
	Texts map[string]string `yaml:"texts"`
	// Decorator/OnProgress 按名引用代码注册的扩展(serving.RegisterDecorator /
	// RegisterProgressHandler),装配期查名 fail fast。
	Decorator  string         `yaml:"decorator"`
	OnProgress string         `yaml:"on_progress"`
	Config     map[string]any `yaml:"config"`
}

type Config struct {
	Secrets SecretsConfig `yaml:"secrets"`

	Prompts PromptsConfig `yaml:"prompts"`

	Sources []SourceConfig `yaml:"sources"`
	Catalog CatalogConfig  `yaml:"catalog"`

	// 执行画像基线(app 层):model 取代原 default_model,reliability/loop/
	// digest/steps 为全体执行单元的降级源。
	Profile `yaml:",inline"`

	// Namespaces 是三层结构的主路径:tools(ns 内共享)→ components
	// (执行单元声明)→ skills(对外产品,唯一进目录的编排单元)。
	Namespaces []NamespaceConfig `yaml:"namespaces"`

	// Skills 是平铺声明的兼容路径,新配置建议用 namespaces。条目二选一:
	// 内部声明(prompt/engine/...)或外部引用(use: 链接,见 SkillEntry)。
	Skills []*SkillEntry `yaml:"skills"`
	Agents []AgentConfig `yaml:"agents"`

	// Skillpacks 是外部技能包策略(物化目录/获取策略/pin 政策)。
	Skillpacks SkillpacksConfig `yaml:"skillpacks"`
	// Models 是具名模型(skillpack frontmatter `model:` 按名引用)。
	Models []NamedModelConfig `yaml:"models"`
	Exec   ExecConfig         `yaml:"exec"`

	Serving  ServingConfig   `yaml:"serving"`
	Channels []ChannelConfig `yaml:"channels"`

	Suspend SuspendConfig `yaml:"suspend"`

	Observability ObservabilityConfig `yaml:"observability"`

	// StateDir 是可写运行状态目录,当前消费方是 skill 安装(skillpacks
	// 物化到 <state_dir>/agent-kit/.skills);file 后端与轨迹路径仍各自
	// 显式配置,尚未收口到这里。只读资源(配置/提示词/skill 包)不走
	// 这里——它们由资源 FS 承载(见 docs/resource-loading-design.md)。
	// 默认链:state_dir → 环境 AGENTKIT_STATE_DIR → $XDG_STATE_HOME/agentkit。
	StateDir string `yaml:"state_dir"`
	// WorkDirLegacy:work_dir 已拆义为只读根(资源 FS)+ 可写状态(state_dir),
	// 旧键装配期报错指路。
	WorkDirLegacy *string `yaml:"work_dir"`
	// DefaultModelLegacy:default_model 已改名 model(执行画像内嵌),
	// 旧键装配期报错指路。
	DefaultModelLegacy *ModelConfig `yaml:"default_model"`
	// contains filtered or unexported fields
}

type DigestProfile struct {
	Over     *int `yaml:"over"`
	Truncate *int `yaml:"truncate"`
	// DegradeKeep 是暂存后端不可用时的应急保留量(rune,缺省 24000):
	// 指针发不出去还只留 truncate 的量 = 不必要的数据损失;完全不截又会
	// 炸上下文窗(生产实测单结果 10 万字符)。中小结果在降级态零损失,
	// 极端长文仍有物理护栏。
	DegradeKeep *int           `yaml:"degrade_keep"`
	Store       string         `yaml:"store"`
	StoreConfig map[string]any `yaml:"store_config"`
}

type ExecConfig struct {
	// DefaultSandbox 是未显式配 sandbox/command 的 exec 工具的回落沙箱名
	// (需 impl/exec/* 空导入注册,如 docker)。
	DefaultSandbox string `yaml:"default_sandbox"`
	// SandboxConfig 是默认沙箱的构造配置(如 docker 的 image/network/memory)。
	SandboxConfig map[string]any `yaml:"sandbox_config"`
	// RequireSandbox 开启后禁止宿主直跑:无沙箱可用的 exec 工具装配即 fail fast。
	RequireSandbox bool `yaml:"require_sandbox"`
}

type LoopProfile struct {
	// MaxSteps 是工具调用的轮数上限(一轮 = 一次模型决策 + 一批工具执行;
	// react 装配时换算为 eino 的节点步数 2N+1,额外的 1 是收尾作答)。
	// 默认 12 轮。yaml 键 max_rounds——名实对齐(内部字段名沿用)。
	MaxSteps *int `yaml:"max_rounds"`
	// MaxStepsLegacy 已废弃:max_steps 语义即轮数,改名 max_rounds(报错指路)。
	MaxStepsLegacy *int                   `yaml:"max_steps"`
	Compaction     *loop.CompactionConfig `yaml:"compaction"`
}

type MemoryConfig struct {
	Store       string         `yaml:"store"`        // cap://store/memory/<name> 或裸 type
	StoreConfig map[string]any `yaml:"store_config"` // 裸 type 时的就地配置
	// ExposeTools 挂载 memory_save/search 工具(长期记忆的读写入口)。
	// 原名 tools 与"工具列表"惯用词冲突,已改名(旧键装配期报错)。
	ExposeTools bool  `yaml:"expose_tools"`
	ToolsLegacy *bool `yaml:"tools"` // 已废弃:改 expose_tools(报错指路)
	// Scope 是多用户隔离的作用域策略:write 对话写入落点(user 默认 |
	// shared | session),read 召回覆盖(缺省 [user, shared])。
	Scope MemoryScope `yaml:"scope"`
	// Recall 是长期记忆的自动召回(L4):top_k>0 启用,检索策略由后端决定。
	Recall struct {
		TopK int `yaml:"top_k"`
	} `yaml:"recall"`
	// Seed 装配期灌入共享池的知识条目(域共享知识的运维写入口)。
	Seed []MemorySeed `yaml:"seed"`
}

type MemoryScope struct {
	Write string   `yaml:"write"`
	Read  []string `yaml:"read"`
}

type MemorySeed struct {
	Key   string `yaml:"key"`
	Value string `yaml:"value"`
}

type ModelConfig struct {
	Provider string         `yaml:"provider"`
	Config   map[string]any `yaml:"config"`
}

type Mount struct {
	*NamespaceSpec
	Override Profile
}

type NamedModelConfig struct {
	Name     string         `yaml:"name"`
	Provider string         `yaml:"provider"`
	Config   map[string]any `yaml:"config"`
}

type NamespaceConfig struct {
	Name    string `yaml:"name"`
	Profile `yaml:",inline"`
	// Sources 声明能力供给源(与顶层 sources: 同构);"声明源用 sources、
	// 引用工具面用 tools"全库一致。
	Sources []SourceConfig `yaml:"sources"`
	// Tools 已废弃:源声明改用 sources(装配期报错指路)。
	ToolsLegacy []SourceConfig   `yaml:"tools"`
	Skills      []NamespaceSkill `yaml:"skills"`
	// Subagents 是本 namespace 声明的 sub-agent(挂载即对 agent 可见,
	// 与 skills 同一可见性规则)。
	Subagents []SubagentConfig `yaml:"subagents"`

	// ——已随概念收敛移除,误写装配期报错指路——
	ImportsLegacy    []string         `yaml:"imports"`
	ComponentsLegacy []map[string]any `yaml:"components"`
}

type NamespaceFile struct {
	NamespaceConfig `yaml:",inline"`
}

type NamespaceMount struct {
	Path    string `yaml:"path"`
	Profile `yaml:",inline"`
}

type NamespaceSkill struct {
	Name        string                          `yaml:"name"`
	Version     string                          `yaml:"version"`
	Description string                          `yaml:"description"`
	Params      map[string]capability.ParamDecl `yaml:"params"`
	// Prompt 是内联卡的任务书正文(与 from 互斥)。
	Prompt prompt.Value `yaml:"prompt"`
	// Tools:内联卡 = 直挂宿主的工具引用(tools/<source>/<name|*>);
	// from 包 = 在包的 allowed-tools 之上再收紧(交集)。
	Tools []string `yaml:"tools"`
	// From 集成一个外部 SKILL.md 技能包;须显式 name(命名归属团队)。
	From      string `yaml:"from"`
	Integrity string `yaml:"integrity"`
	// Context 是 from 包内部循环的起始上下文(fresh 缺省 | fork)。
	Context string `yaml:"context"`
	// MaxRounds 是 from 技能包内部循环的轮数覆盖(与平铺 SkillEntry 的
	// max_rounds 同义;两条 skillpack 装配路径同一配置面)。
	MaxRounds int `yaml:"max_rounds"`

	// ——已随编排族移除,误写装配期报错指路——
	StepsLegacy        []map[string]any `yaml:"steps"`
	UseLegacy          *string          `yaml:"use"`
	EngineLegacy       *string          `yaml:"engine"`
	OutputLegacy       *string          `yaml:"output"`
	DeliverLegacy      *string          `yaml:"deliver"`
	StepDefaultsLegacy map[string]any   `yaml:"step_defaults"`
}

type NamespaceSpec struct {
	NamespaceFile
	Path string // 资源 FS 内路径('/' 分隔),亦作源连接缓存键
}

type ObservabilityConfig struct {
	Log            bool   `yaml:"log"`
	TrajectoryPath string `yaml:"trajectory_path"`
}

type Profile struct {
	Model       *ModelConfig       `yaml:"model"`
	Loop        LoopProfile        `yaml:"loop"`
	Reliability ReliabilityProfile `yaml:"reliability"`
	Digest      DigestProfile      `yaml:"digest"`
	// StepDefaultsLegacy 已随编排族移除(固定流程下沉宿主 eino compose),
	// 误写装配期报错指路。
	StepDefaultsLegacy map[string]any `yaml:"step_defaults"`
}

type PromptConfig struct {
	System prompt.Value `yaml:"system"` // L2 业务 persona
	Loop   prompt.Value `yaml:"loop"`   // L1 框架规约覆盖(默认内置)
}

type PromptSourceConfig struct {
	Name   string         `yaml:"name"`
	Type   string         `yaml:"type"`
	Config map[string]any `yaml:"config"`
}

type PromptsConfig struct {
	Sources      []PromptSourceConfig `yaml:"sources"`
	DefaultLabel string               `yaml:"default_label"`
}

type ReliabilityProfile struct {
	ToolTimeout *loop.Duration    `yaml:"tool_timeout"`
	Retry       *loop.RetryConfig `yaml:"retry"`
}

type RetrieverInstance struct {
	Name   string         `yaml:"name"`
	Kind   string         `yaml:"kind"` // session
	Type   string         `yaml:"type"` // bigram | vector | ...
	Config map[string]any `yaml:"config"`
}

type SecretsConfig struct {
	Provider string         `yaml:"provider"` // env(默认)| file
	Config   map[string]any `yaml:"config"`
}

type ServingConfig struct {
	Addr string `yaml:"addr"`
}

type SessionConfig struct {
	Window      int            `yaml:"window"`       // 0 = 不启用会话记忆
	Store       string         `yaml:"store"`        // cap://store/session/<name> 或裸 type(inmemory/file/...)
	StoreConfig map[string]any `yaml:"store_config"` // 裸 type 时的就地配置
	// RecordTools 控制本轮工具轨迹随会话持久化的详略:
	// summary(默认)| full | off。off 退回只存问答(任务连续性受限)。
	RecordTools string `yaml:"record_tools"`
	// Recall 是窗口外会话历史的自动召回(L4):top_k>0 启用,retriever 指定
	// 检索策略(cap://retriever/session/<name> 或裸 type,缺省 bigram 词法)。
	Recall SessionRecall `yaml:"recall"`
}

type SessionRecall struct {
	TopK            int            `yaml:"top_k"`
	Retriever       string         `yaml:"retriever"`
	RetrieverConfig map[string]any `yaml:"retriever_config"`
}

type SkillEntry struct {
	skill.Declaration `yaml:",inline"`
	From              string   `yaml:"from"`      // 外部获取来源:github.com/...@ver | https://...zip | file:...
	Use               string   `yaml:"use"`       // 已废弃:外链改用 from(装配期报错指路)
	Integrity         string   `yaml:"integrity"` // sha256:<hex>,可选强校验
	Tools             []string `yaml:"tools"`     // 白名单收紧(∩ allowed-tools)
	Context           string   `yaml:"context"`   // from 包内部循环:fresh(默认)| fork
	// Model/MaxRounds 是 from 技能包的本地覆盖(内联卡没有内部循环,
	// 声明它们装配期报错)。
	Model     *skill.ModelDecl `yaml:"model"`
	MaxRounds int              `yaml:"max_rounds"`
}

type SkillpacksConfig struct {
	// Dir 覆盖安装目录(相对值以 state_dir 为基准)。默认固定约定:
	// <state_dir>/agent-kit/.skills——agent-kit 是 SDK,落盘产物收口在
	// 宿主项目的 agent-kit/ 命名空间下(对齐 node_modules/.terraform 心智)。
	Dir string `yaml:"dir"`
	// Sync:auto(默认,缺失即下载)| require-local(缺失 fail fast,
	// 为打包期物化预留的收紧档)。
	Sync string `yaml:"sync"`
	// AllowUnpinned 放行未锁定版本的 ref(lock 仍会锁死首次解析结果)。
	AllowUnpinned bool `yaml:"allow_unpinned"`
}

type SourceConfig struct {
	Name     string         `yaml:"name"`
	Type     string         `yaml:"type"`
	Required bool           `yaml:"required"`
	Priority int            `yaml:"priority"`
	Config   map[string]any `yaml:"config"`
}

type StoreInstance struct {
	Name   string         `yaml:"name"`
	Kind   string         `yaml:"kind"` // session | memory | todo | result | suspend | budget | approval
	Type   string         `yaml:"type"` // inmemory | file | redis | ...(各自后端注册表)
	Config map[string]any `yaml:"config"`
	TTL    loop.Duration  `yaml:"ttl"` // 保留时长(todo/result/approval/budget),0=不过期
}

type SubagentConfig struct {
	Name        string                          `yaml:"name"`
	Version     string                          `yaml:"version"`
	Description string                          `yaml:"description"`
	Params      map[string]capability.ParamDecl `yaml:"params"`
	// Prompt 是 persona + 任务书模板,params 以 {name} 占位渲染。
	Prompt prompt.Value `yaml:"prompt"`
	// Tools 是工具面引用:tools/<source>/<name|*>(本 ns 工具)。
	Tools []string `yaml:"tools"`
	// Context 是起始上下文:fresh(缺省)| fork(调用方对话快照起步)。
	// 心法:先把事实显式写进输入,写不进或写不全才 fork。
	Context string `yaml:"context"`
	// Deliver 是产出的交付语义(attach|always|direct,缺省=证据)。
	Deliver string `yaml:"deliver"`
	// Todo 给内部循环挂调用级临时清单(调用结束即弃)。默认关——
	// sub-agent 长到需要计划通常是"该拆成结构"的信号。
	Todo bool `yaml:"todo"`

	// 执行画像 A 类(loop/reliability/digest;不含 model)——sub-agent
	// 自己这一层,最近,压过 namespace/agent/app。
	Profile `yaml:",inline"`

	// ——已移除键,误写装配期报错指路——
	EngineLegacy       *string          `yaml:"engine"`
	EngineConfigLegacy map[string]any   `yaml:"engine_config"`
	ModeLegacy         *string          `yaml:"mode"`
	StepsLegacy        []map[string]any `yaml:"steps"`
	OutputLegacy       *string          `yaml:"output"`
	ExportLegacy       *bool            `yaml:"export"`
}

type SuspendConfig struct {
	Dir         string         `yaml:"dir"`
	Store       string         `yaml:"store"`
	StoreConfig map[string]any `yaml:"store_config"`
	// TTL 是挂起记录(轮次/交互/效果日志)的过期时长,缺省 168h(7 天):
	// 无人应答的挂起不该在后端永久堆积。具名 store 实例自带的 ttl 优先。
	TTL loop.Duration `yaml:"ttl"`
}

type TodoConfig struct {
	Enabled     *bool          `yaml:"enabled"` // 默认 true,显式 false 关闭
	Store       string         `yaml:"store"`   // cap://store/todo/<name> 或裸 type
	StoreConfig map[string]any `yaml:"store_config"`
}