skill

type AliasResolver interface {
	CanonicalName(ctx context.Context, name string) (string, bool)
}

type Decl struct {
	Name     string `yaml:"name" json:"name"`
	Version  string `yaml:"version,omitempty" json:"version,omitempty"`
	Optional bool   `yaml:"optional,omitempty" json:"optional,omitempty"`
}

type Deprecated struct {
	Reason      string `yaml:"reason,omitempty" json:"reason,omitempty"`
	ReplacedBy  string `yaml:"replaced_by,omitempty" json:"replaced_by,omitempty"` // 替代技能名（可空）
	RemoveAfter string `yaml:"remove_after,omitempty" json:"remove_after,omitempty"`
}

type FileProvider struct {
	Root string
	// contains filtered or unexported fields
}

type LibEntry struct {
	Full string // 全文（含 frontmatter）
	Body string // 剥 frontmatter 正文
	Meta LibMeta
	// contains filtered or unexported fields
}

type LibMeta struct {
	Name        string   `yaml:"name,omitempty" json:"name"`
	Title       string   `yaml:"-" json:"-"` // frontmatter name（展示名）；目录名规范
	Description string   `yaml:"description,omitempty" json:"description"`
	Mode        string   `yaml:"mode" json:"mode"`
	Version     string   `yaml:"version,omitempty" json:"version,omitempty"`
	Maturity    string   `yaml:"maturity,omitempty" json:"maturity,omitempty"`
	RequiresMCP []MCPDep `yaml:"requires_mcp,omitempty" json:"requires_mcp,omitempty"`
	// RequiresConfig 技能依赖的集成配置类型（bianque 集成平面）：如 [rag, s3]。
	// 声明级契约——缺失由调用方告警，不拦截加载。
	RequiresConfig []string    `yaml:"requires_config,omitempty" json:"requires_config,omitempty"`
	Deprecated     *Deprecated `yaml:"deprecated,omitempty" json:"deprecated,omitempty"`
	Provides       []string    `yaml:"provides,omitempty" json:"provides,omitempty"` // 能力标签（登记/展示；重复声明由调用方告警）
	Compatibility  string      `yaml:"compatibility,omitempty" json:"compatibility,omitempty"`
	Source         string      `yaml:"-" json:"source"` // 来源前缀标签
	Path           string      `yaml:"-" json:"-"`      // SKILL.md 相对路径
}

type Library struct {
	// contains filtered or unexported fields
}

type Lister interface {
	ListSkills(ctx context.Context) ([]Meta, error)
}

type LoadOption func(*loadConfig)

type MCPDep struct {
	Server     string   `yaml:"server" json:"server"`
	Tools      []string `yaml:"tools,omitempty" json:"tools,omitempty"`
	MinVersion string   `yaml:"min_version,omitempty" json:"min_version,omitempty"`
	Comment    string   `yaml:"comment,omitempty" json:"comment,omitempty"`
}

type Meta struct {
	// Name 规范引用名（目录名/文件名）——use_skill 加载与 allowed 清单的唯一依据。
	Name string
	// Title 展示名（frontmatter name；与 Name 相同或目录缺失时为空）。
	// 仅用于清单展示，加载仍按 Name；模型若用 Title 调用，AsSkillTool 会归一化。
	Title       string
	Version     string
	Description string
}

type Provider interface {
	Resolve(ctx context.Context, ref Ref) (*Skill, error)
}

type Ref struct {
	Name    string
	Version string
	Source  string // file（v3.0 仅实现 file）
}

type Skill struct {
	Name        string
	Version     string // frontmatter 声明（未声明为空串）；ref.Version 是请求约束/缓存键，不回显
	Description string // frontmatter description（无则空）
	Content     string // frontmatter 之后的正文
	// Checksum 内容校验和，canonical 口径：sha256(正文) 前 16 位 hex——绑定
	// 实际注入提示词的内容（frontmatter 是元数据，不进 prompt）。
	// FileProvider 与 Library 两个 Provider 一致，观测守卫的比对基准不随 Provider 漂移。
	Checksum string
}

type ToolOption func(*skillToolCfg)