plugin

type BuiltinDef struct {
	// Name 内置插件名称(必须唯一,不能与已注册插件冲突)
	Name string
	// Description 描述
	Description string
	// Version 版本,可留空(默认 "0.0.0")
	Version string
	// Skills 内置技能列表
	Skills []*Skill
	// Hooks 内置 hook 定义
	Hooks map[string][]HookDef
	// MCPServers 内置 MCP 服务器配置
	MCPServers []MCPServerDef
}

type ConfigFieldDef struct {
	// Key 配置项的键名(在 user config map 中对应的 key)
	Key string `json:"key"`
	// Type 值类型:"string" / "number" / "boolean"
	// 空字符串时默认视为 "string"
	Type string `json:"type"`
	// Required 是否为必填项.
	// true 时若用户配置 map 中不存在该 key,ValidatePluginConfig 返回错误.
	Required bool `json:"required"`
	// Default 默认值(字符串表示,非必填项可以有默认).
	// 校验时若 key 缺失且 Required==false,可用此值填充.
	// 历史包袱(LEGACY): 当前校验器不自动填充默认值(只报告缺失),
	// 调用方(Host.SetPluginConfig)负责应用默认值.
	// 未来如有需要,可在 ValidatePluginConfig 中补充自动填充逻辑.
	Default string `json:"default,omitempty"`
	// Description 人类可读的字段描述(用于 help 输出和 UI 展示)
	Description string `json:"description,omitempty"`
	// Secret 标记此字段是否为敏感值(如 API Key,密码).
	// true 时日志/错误消息中对该字段值进行脱敏(显示为 "***").
	//
	// 升华改进(ELEVATED): Secret 标记让引擎主动保护敏感值--
	// 插件作者只需声明"这是秘密",引擎层统一处理脱敏,
	// 无需每个插件自己实现 mask 逻辑.
	// 替代方案:<命名约定(key 包含 "secret"/"password" 的自动脱敏)>
	// - 否决:名称约定脆弱,容易遗漏("api_key" vs "apiKey" vs "key").
	Secret bool `json:"secret"`
}

type Definition struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Source      string `json:"source"` // 插件标识符
}

type HookDef struct {
	// Command 要执行的 shell 命令
	Command string `json:"command"`
	// Timeout 超时时间(秒),默认 30
	Timeout int `json:"timeout"`
}

type HooksDef struct {
	// Hooks 按 hook 类型分组的 hook 定义列表
	Hooks map[string][]HookDef `json:"hooks"`
}

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

type LoadResult struct {
	// Enabled 成功加载并启用的插件列表
	Enabled []*Plugin
	// Disabled 因依赖降级而被禁用的插件列表
	// 精妙之处(CLEVER): 保留禁用插件而非直接丢弃,使消费层可以展示"因 X 禁用了 Y"的诊断信息.
	Disabled []*Plugin
	// Errors 致命错误列表(插件完全无法加载)
	Errors []PluginError
	// Warnings 非致命警告列表(插件加载但有降级)
	Warnings []PluginError
}

type MCPDef struct {
	// Transport 传输方式:stdio / sse / http / ws
	Transport string `json:"transport"`
	// Command stdio 模式下的可执行命令
	Command string `json:"command,omitempty"`
	// Args 命令参数
	Args []string `json:"args,omitempty"`
	// URL sse/http/ws 模式下的服务器 URL
	URL string `json:"url,omitempty"`
	// Env 环境变量
	Env map[string]string `json:"env,omitempty"`
}

type MCPServerDef struct {
	// Name 服务器名称
	Name string
	// PluginName 来源插件名称
	PluginName string
	// MCPDef 服务器配置
	MCPDef
}

type Manifest struct {
	// Name 插件名称(唯一标识符)
	Name string `json:"name"`
	// Description 插件描述
	Description string `json:"description"`
	// Version 插件版本(语义化版本号)
	Version string `json:"version"`
	// SkillsPath 技能文件目录的相对路径(相对于插件目录)
	SkillsPath string `json:"skills_path"`
	// HooksPath hooks 配置文件的相对路径
	HooksPath string `json:"hooks_path"`
	// MCPServers MCP 服务器配置.
	//
	// 升华改进(ELEVATED): JSON 字段名从 "mcp_servers" 改为 "mcpServers",
	// 与 Claude Code 插件格式对齐.这样同一个 plugin.json 可直接被 Claude Code 读取,
	// 无需手动转换,降低跨平台插件的维护成本.
	// 早期方案字段名 <"mcp_servers"> - 保留为向后兼容在下方 UnmarshalJSON 中处理.
	MCPServers map[string]MCPDef `json:"mcpServers"`
	// Dependencies 依赖的其他插件名称列表
	Dependencies []string `json:"dependencies"`
	// ConfigSchema 插件配置字段定义(12.6 Plugin Config Schema).
	//
	// 升华改进(ELEVATED): 插件声明自己需要哪些配置项,引擎在加载时验证用户提供的
	// 配置是否满足 Required 字段,并提供类型约束和描述.
	// 等价于 npm package.json 里的 peerDependencies + engines 约束--
	// 消费层不必逐一阅读插件源码就能知道"这个插件需要我提供什么".
	// 替代方案:<文档约定(README 里写需要什么环境变量)>
	// - 否决:文档和代码分离,容易过期;机器无法校验,只能靠人工排查.
	ConfigSchema []ConfigFieldDef `json:"config_schema,omitempty"`

	// Tools 是 plugin 声明式注册的 shell tool 列表 (2026-04-15 新增).
	//
	// 每个 PluginToolDef 在加载时被 loadPluginTools 翻译成一个 pluginShellTool
	// 实例 (实现 tools.Tool interface), 存放在 Plugin.Tools 里, 供消费层
	// (Host.GetAllTools) 注册到全局 tools.Registry.
	//
	// 这是 plugin 扩展 tool 的**第二条路径** (第一条是 MCPServers 配置).
	// 适用场景: 单 tool / 无状态 / shell 脚本就能搞定的简单扩展.
	// 详见 plugin_tool.go 的 "为什么同时需要 MCP server 和 declarative tool" 段落.
	Tools []PluginToolDef `json:"tools,omitempty"`
}

type NoopVerifier struct{}

type Plugin struct {
	// Name 插件名称(唯一标识符)
	Name string
	// Description 插件描述
	Description string
	// Version 插件版本
	Version string
	// Path 插件目录的绝对路径(内置插件为空字符串)
	Path string
	// Source 插件的来源级别(内置/用户级/项目级)
	// 影响依赖解析中的跨来源规则.
	Source Source
	// Manifest 插件清单(plugin.json 的解析结果);内置插件为 nil
	Manifest *Manifest
	// Enabled 插件是否启用
	Enabled bool
	// Skills 插件提供的技能列表
	Skills []*Skill
	// Hooks 插件提供的 hook 定义,key 是 hook 类型
	Hooks map[string][]HookDef
	// MCPServers 插件提供的 MCP 服务器配置
	MCPServers []MCPServerDef
	// Tools 插件通过 plugin.json 的 tools 字段声明式注册的 shell tool 运行时实例.
	//
	// 区别于 MCPServers 字段: MCPServers 是配置 (启动外部 MCP server 进程),
	// Tools 是已经实例化的 tools.Tool, 可以直接注册到 tools.Registry.
	// 详见 plugin_tool.go 的 "为什么同时需要 MCP server 和 declarative tool
	// 两条路径" 段落.
	//
	// 消费层 (Host 或 engine) 通过 Host.GetAllTools() 收集所有启用插件的 tools,
	// 并调用 tools.Registry.Register() 逐个注册.
	Tools []tools.Tool
}

type PluginError struct {
	// Code 错误分类码
	Code PluginErrorCode
	// PluginName 触发错误的插件名称
	PluginName string
	// Message 人类可读的错误描述
	Message string
	// Cause 底层原因(可选)
	Cause error
}

type PluginErrorCode int

type PluginToolDef struct {
	// Name 是 tool 的本地名称 (不含 plugin 前缀).
	// 最终注册到 Registry 的名字是 "pluginName:Name".
	// 必填, 空值会被 loadPluginTools 跳过.
	Name string `json:"name"`

	// Description 是给 LLM 的 tool 描述. 必填 (否则 LLM 不知道该不该调).
	Description string `json:"description"`

	// InputSchema 是 tool 参数的 JSON Schema. 可选, 缺省为空对象 schema
	// ({"type":"object","properties":{},"additionalProperties":true}),
	// 即"接受任意 JSON 对象"- 适合无参数或参数非常灵活的 tool.
	InputSchema json.RawMessage `json:"input_schema,omitempty"`

	// Command 是要执行的命令 (可以是 $PATH 里的名字如 "python", 或绝对/
	// 相对路径如 "/usr/bin/env" / "./script.sh"). 必填.
	// 相对路径会相对于 WorkDir (默认为 pluginDir) 解析, 由 exec.Command 处理.
	Command string `json:"command"`

	// Args 是传给 Command 的命令行参数 (不含 command 本身).
	Args []string `json:"args,omitempty"`

	// Env 是要注入子进程环境变量的 key/value. 会叠加到白名单 OS env
	// (PATH/HOME/LANG/LC_ALL) 之上, 同名变量以 Env 里的为准. Value 支持
	// ${HOST_VAR} / $HOST_VAR 展开宿主 env, 未设置的引用会导致 tool error.
	// 常用于传 API Key / endpoint / plugin config. 详见 pkg/execenv 包.
	Env map[string]string `json:"env,omitempty"`

	// WorkDir 是子进程的工作目录. 可选:
	//   - 空字符串 (默认): 使用 pluginDir
	//   - 相对路径: 相对于 pluginDir 解析
	//   - 绝对路径: 直接使用
	WorkDir string `json:"work_dir,omitempty"`

	// TimeoutSeconds 是子进程执行的超时时间 (秒). <=0 或未指定 → 30s 默认.
	// 超时后进程被 SIGKILL, Execute 返回 IsError=true 的 Result.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`

	// PermissionClass 是权限检查类型 (参见 tools.Metadata.PermissionClass).
	// 空字符串默认 "bash" (命令执行类, 子命令分割 + 危险命令检测).
	PermissionClass string `json:"permission_class,omitempty"`

	// ConcurrencySafe 声明本 tool 是否可以与其他 tool 并发执行.
	// 保守默认 false (和 tools.GetMetadata 的 fallback 一致).
	ConcurrencySafe bool `json:"concurrency_safe,omitempty"`

	// ReadOnly 声明本 tool 是否只读 (无副作用).
	// 保守默认 false.
	ReadOnly bool `json:"read_only,omitempty"`

	// Destructive 声明本 tool 是否会造成不可逆的破坏
	// (rm / DROP TABLE / kubectl delete 等).
	// 保守默认 false.
	Destructive bool `json:"destructive,omitempty"`
}

type RejectUnsignedVerifier struct {
	// Inner 是实际执行验证的 verifier. 通常是 NewSHA256IntegrityVerifier().
	// 为 nil 时默认使用 SHA256IntegrityVerifier{}.
	Inner SignatureVerifier
}

type SHA256IntegrityVerifier struct{}

type SignatureVerifier interface {
	// Verify 验证 plugin 目录的完整性 / 签名.
	//
	// 参数:
	//   - pluginDir: plugin 目录的绝对路径
	//   - manifest:  已加载的 Manifest (可能为 nil, 虽然 LoadPluginWithVerifier
	//                总是传非 nil, 但 verifier 应该容错处理)
	//
	// 返回 nil 表示通过, 非 nil 表示拒绝加载.
	Verify(pluginDir string, manifest *Manifest) error
}

type Skill struct {
	// Name 技能名称(命名空间化后的名称,格式:pluginName:skillName)
	Name string
	// RawName 技能原始名称(不含插件前缀)
	RawName string
	// PluginName 来源插件名称
	PluginName string
	// Description 技能描述
	Description string
	// WhenToUse 何时使用此技能的说明
	WhenToUse string
	// AllowedTools 此技能允许使用的工具列表
	AllowedTools []string
	// Content 技能正文内容(markdown)
	Content string
	// FilePath 技能文件的原始路径
	FilePath string
}

type Source int

type ValidationResult struct {
	// Valid 清单是否通过所有验证
	Valid bool
	// Errors 阻断加载的验证错误
	Errors []PluginError
	// Warnings 不阻断加载的警告(如建议字段缺失)
	Warnings []PluginError
}