skill

type AgentDecl struct {
	// Name 形如 "research/analyst",namespace/name。
	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"`
	// Capabilities 是内部工具面(最小权限子集),CapRef 模式;命名空间
	// 装配层用 tools: 短形态预解析注入(Deps.Capabilities),此字段供
	// 程序化装配按目录选品。
	Capabilities struct {
		Include []string `yaml:"include"`
		Exclude []string `yaml:"exclude"`
	} `yaml:"capabilities"`
	// Model 是专属模型,nil 跟随宿主(装配层按画像链解析后注入)。
	Model *ModelDecl `yaml:"model"`
	// MaxSteps 是内部循环轮数上限(yaml 键 max_rounds,0 用默认)。
	MaxSteps       int  `yaml:"max_rounds"`
	MaxStepsLegacy *int `yaml:"max_steps"` // 已废弃:改 max_rounds
	// Deliver 是产出的交付语义:attach(存底,终答引用 #dN 即原文随行)
	// | always(恒随行)| direct(独占轮次时原文即终答);缺省 = 证据。
	Deliver string `yaml:"deliver"`
	// Compaction 启用内部循环的上下文压缩(长任务建议开启)。
	Compaction loop.CompactionConfig `yaml:"compaction"`
	// Context 是起始上下文:fresh(缺省,零上下文起步)| fork(以调用方
	// 对话快照+任务书起步;背景无损继承,内部过程仍不回流)。心法:
	// 先把事实显式写进输入,写不进或写不全才 fork。
	Context string `yaml:"context"`
	// Todo 给内部循环挂调用级临时清单:键 = 本次执行域,生命周期 =
	// 一次调用,结束即弃——宿主计划不受影响,sub-agent 保持无状态
	// 可重入。默认关;长到需要计划通常是"该拆成结构"的信号。
	Todo bool `yaml:"todo"`

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

type Declaration struct {
	// Kind 是产物的 cap kind:空=skill。
	Kind string `yaml:"-"`
	// Name 形如 "research/competitor_report",namespace/name。
	Name        string                          `yaml:"name"`
	Version     string                          `yaml:"version"`
	Description string                          `yaml:"description"`
	Params      map[string]capability.ParamDecl `yaml:"params"`
	// Prompt 是任务书模板(业务知识所在),params 以 {name} 占位渲染。
	Prompt prompt.Value `yaml:"prompt"`

	// ——以下键已随概念收敛移除(skill 永远在主循环执行,没有内部
	// 循环;隔离执行体声明成 sub-agent)。误写装配期报错指路。——
	ModeLegacy         *string        `yaml:"mode"`
	EngineLegacy       *string        `yaml:"engine"`
	EngineConfigLegacy map[string]any `yaml:"engine_config"`
	DeliverLegacy      *string        `yaml:"deliver"`
	TodoLegacy         *bool          `yaml:"todo"`
	CompactionLegacy   map[string]any `yaml:"compaction"`
	MaxStepsLegacy     *int           `yaml:"max_steps"`
}

type DelegateConfig struct {
	Enabled     bool `yaml:"enabled"`
	MaxRounds   int  `yaml:"max_rounds"`   // 子循环轮数缺省 8;调用参数只可收紧
	MaxParallel int  `yaml:"max_parallel"` // 并发上限缺省 4,超出排队
}

type Deps struct {
	Catalog      Selector
	Prompts      prompt.Source
	DefaultModel einomodel.ToolCallingChatModel
	// LoopPrompt 是 L1 框架规约,sub-agent 内部循环复用,保持运行纪律一致。
	LoopPrompt string
	// Capabilities 是预解析的工具面。非空时跳过 Catalog 选品,由调用方
	// (命名空间装配层)负责引用解析与边界校验。
	Capabilities []capability.Capability
	// ToolTimeout 是内部工具面的单次调用超时(0 默认,<0 关闭)。
	ToolTimeout time.Duration
	// Retry 是专属模型的瞬时错误重试策略(DefaultModel 由上层包装)。
	Retry loop.RetryConfig
	// DigestOver 启用内部工具面的大结果消化:超过该 rune 数的工具
	// 结果先落 run 级暂存,由模型带任务提取要点后入上下文(0 关闭)。
	DigestOver int
	// Truncate 是工具结果硬截断上限(rune;0 用内置默认)。与宿主 agent
	// 同一画像键(digest.truncate),装配层透传,保证子循环同一纪律。
	Truncate int
	// DegradeKeep 是暂存降级时的应急保留量(rune;0 用内置默认 24000),
	// 画像键 digest.degrade_keep。
	DegradeKeep int
	// Todo 是 sub-agent 调用级清单的持有对象(仅 decl.Todo 时用),由装配层
	// 注入后端。清单是调用级临时草稿(结束即弃),用进程内后端即可。
	Todo *todo.Todo
	// AgentHub 按名解析已装配 agent(skillpack frontmatter `agent:` 字段,
	// eino AgentHub 的本地等价物)。装配层注入;查找延迟到调用期(agent
	// 可能晚于技能装配),名字合法性由装配层在装配期校验。
	AgentHub func(name string) (capability.Capability, bool)
	// ModelHub 按名解析具名模型(skillpack frontmatter `model:` 字段)。
	// 装配层注入,装配期解析,查不到 fail fast。
	ModelHub func(ctx context.Context, name string) (einomodel.ToolCallingChatModel, error)
}

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

type PackDir struct {
	Dir     string // 本地目录(.skills/<ns>/<name>@<version>)
	Ref     string
	NS      string
	Name    string
	Version string
	SHA     string // 内容树哈希(sha256)
}

type PackManifest struct {
	NS, Name     string
	Version      string
	Description  string
	Body         string   // SKILL.md 正文(L2)
	AllowedTools []string // frontmatter allowed-tools(CapRef 模式)
	Dir          string   // 本地物化目录
	Ref          string   // 来源 ref(观测/回溯)
	SHA          string   // 内容树哈希
	HasFiles     bool     // 除 SKILL.md 外还有文件(决定挂不挂 pack_read)
	// Runtimes 是包内脚本类型(按扩展名检测:.py→python .js/.mjs→node
	// .sh→bash),非空说明是脚本型技能包:装配层据此绑定 exec 工具
	// (工作目录=包目录),包风险经 exec 工具传播为 Dangerous。
	Runtimes []string
	// 以下来自 frontmatter,与 eino ADK Skill middleware 协议对齐:
	// Context 已归一为全库统一词表:""/fresh(隔离,默认)| fork(带
	// 调用方对话快照)。第三方包的旧值在解析处兼容映射(fork→fresh、
	// fork_with_context→fork)并记 warn。Agent/Model 按名指定执行
	// agent 或模型,经 Deps.AgentHub/ModelHub 解析。
	Context string
	Agent   string
	Model   string
}

type PackOptions struct {
	RequireLocal  bool // true:缺失即错(为打包期物化预留的收紧档)
	AllowUnpinned bool // true:放行未 pin 的 ref(lock 仍会锁死首次解析结果)
}

type PackOverrides struct {
	Model    *ModelDecl // 专属模型,nil 跟随宿主默认
	MaxSteps int
	Tools    []string // 白名单收紧(与 allowed-tools 求交集)
	Context  string   // "" | fresh | fork(与编排步骤同义)
}

type PackSpec struct {
	Use       string // ref 字符串
	Integrity string // "sha256:<hex>",可选:强校验归档字节
	Name      string // 本地覆盖 "ns/name",可空(取 frontmatter)
}

type Selector interface {
	Select(include, exclude []string) ([]capability.Capability, error)
}