runtimecontext

type AgentAnalysisInput struct {
	// ProjectID 取自 RuntimeContext.ProjectID（当前用户激活项目）。
	ProjectID int64
	// Name 是任务名称（同时用作节点名称与容器资源名）。
	Name string
	// ContainerTemplateID 是模型选择的容器模板；<=0 表示未指定，由实现回退到系统默认模板。
	ContainerTemplateID int64
	// Command 是要执行的 shell 命令，由实现写入节点工作目录的 run.sh。
	Command string
	// Run 控制创建后是否立即运行：nil / true 表示运行（默认），false 表示只创建节点。
	Run *bool
	// TimeoutSeconds <= 0 时使用实现默认超时。
	TimeoutSeconds int
}

type AgentAnalysisResult struct {
	AgentAnalysisID     int64  `json:"agent_analysis_id"`
	ContainerInstanceID int64  `json:"container_instance_id,omitempty"`
	Status              string `json:"status"`
	// Ran 表示是否实际提交了运行（Run=false 时为 false）。
	Ran          bool   `json:"ran"`
	Success      bool   `json:"success"`
	ExitCode     int    `json:"exit_code"`
	Log          string `json:"log,omitempty"`
	LogPath      string `json:"log_path,omitempty"`
	WorkspaceDir string `json:"workspace_dir,omitempty"`
	CommandPath  string `json:"command_path,omitempty"`
}

type AgentAnalysisRunner interface {
	// CreateAgentAnalysis 创建一条命令型 AnalysisNode（工作目录、run.sh、容器模板）；
	// Run 为 nil / true 时复用通用节点链路运行到终态并返回状态、退出码与命令日志，
	// Run 为 false 时只创建节点。超时 / 取消时返回错误。
	CreateAgentAnalysis(ctx context.Context, in AgentAnalysisInput) (AgentAnalysisResult, error)
}

type AgentAnalysisUpdateInput struct {
	// ProjectID 是节点所属项目（取自 RuntimeContext.ProjectID）。
	ProjectID int64 `json:"project_id,string"`
	// AnalysisNodeID 是分析节点主键，必须为正数。
	AnalysisNodeID int64 `json:"analysis_node_id,string"`
	// NodeName 为 nil 表示不修改；非 nil 时覆盖节点名称（不能为空）。
	NodeName *string `json:"node_name,omitempty"`
	// Command 为 nil 表示不修改；非 nil 时覆盖 run.sh 正文（不能为空）。
	Command *string `json:"command,omitempty"`
	// ContainerTemplateID 为 nil 表示不修改；非 nil 时覆盖节点容器模板（必须为正数）。
	ContainerTemplateID *int64 `json:"container_template_id,omitempty,string"`
}

type AgentAnalysisUpdateResult struct {
	AnalysisNodeID      int64  `json:"analysis_node_id,string"`
	NodeName            string `json:"node_name"`
	Command             string `json:"command,omitempty"`
	ContainerTemplateID int64  `json:"container_template_id,string,omitempty"`
	WorkspaceDir        string `json:"workspace_dir,omitempty"`
	CommandPath         string `json:"command_path,omitempty"`
	ParamsPath          string `json:"params_path,omitempty"`
	// Changed 列出本次实际被修改的字段（node_name / command / container_template_id）。
	Changed []string `json:"changed,omitempty"`
}

type AnalysisNodeBrief struct {
	AnalysisNodeID int64  `json:"analysis_node_id"`
	NodeName       string `json:"node_name"`
	// CreationSource 是落库的 creation_source 原值（agent / script / scheduler）。
	CreationSource string `json:"creation_source,omitempty"`
	// NodeType 是归一化后的节点类型（agent / script / scheduler）。
	NodeType string `json:"node_type,omitempty"`
	// NodeTypeDescription 是节点类型的中文说明（含可用的更新 / 运行工具指引）。
	NodeTypeDescription string         `json:"node_type_description,omitempty"`
	ScriptID            int64          `json:"script_id,omitempty"`
	WorkspaceDir        string         `json:"workspace_dir"`
	CommandPath         string         `json:"command_path,omitempty"`
	ParamsPath          string         `json:"params_path"`
	RequestParam        map[string]any `json:"request_param,omitempty"`
}

type AnalysisNodeBrowser interface {
	// GetAnalysisNodeByID 按主键读取分析节点（必须属于当前激活项目，否则返回错误）。
	//
	// 返回的 WorkspaceDir 是绝对路径，ParamsPath 由 WorkspaceDir 派生。
	GetAnalysisNodeByID(ctx context.Context, projectID int64, nodeID int64) (AnalysisNodeBrief, error)
}

type AnalysisNodeCreateInput struct {
	// ProjectID 是脚本所属项目（取自 RuntimeContext.ProjectID），用于校验脚本归属。
	ProjectID int64 `json:"project_id,string"`
	// ScriptID 是 Script 主键（pipeline_components.id）。
	ScriptID int64 `json:"script_id,string"`
	// NodeName 为节点名称，为空时回落脚本名称。
	NodeName string `json:"node_name,omitempty"`
	// RequestParam 是初始请求参数（键为 io_schema inputs 的 name）；为空时节点只带 patterns。
	RequestParam map[string]any `json:"request_param,omitempty"`
}

type AnalysisNodeCreateResult struct {
	AnalysisNodeID int64  `json:"analysis_node_id,string"`
	NodeName       string `json:"node_name"`
	ScriptID       int64  `json:"script_id,string"`
	// ScriptName / ScriptType 是脚本的基本信息（便于模型确认节点绑定哪个脚本）。
	ScriptName string `json:"script_name,omitempty"`
	ScriptType string `json:"script_type,omitempty"`
	// ScriptFilePath 是脚本主文件（如 main.R）的绝对路径，由 utils.GetScriptFile 推导。
	ScriptFilePath string `json:"script_file_path,omitempty"`
	// IOSchemaPath 是脚本目录下 io_schema.json 的绝对路径（节点 patterns 的来源）。
	IOSchemaPath string         `json:"io_schema_path,omitempty"`
	WorkspaceDir string         `json:"workspace_dir"`
	ParamsPath   string         `json:"params_path"`
	RequestParam map[string]any `json:"request_param,omitempty"`
}

type AnalysisNodeCreator interface {
	// CreateAnalysisNode 为已有脚本创建一个独立分析节点。
	//
	// 脚本必须属于 input.ProjectID；request_param 非空时按脚本 io_schema 解析出
	// resolved_inputs 并写出 params.json，为空时节点只按 io_schema 初始化 patterns。
	//
	// 节点在创建时必然要落地 inputs_patterns / output_patterns，因此 io_schema.json
	// 必须已经写好（先 CreateScript，或至少已写入一份契约）；缺失时返回错误。
	CreateAnalysisNode(ctx context.Context, input AnalysisNodeCreateInput) (AnalysisNodeCreateResult, error)
}

type AnalysisNodeParamsBuilder interface {
	// BuildAnalysisNodeParams 为指定分析节点生成运行期参数文件并落库。
	//
	// analysisNodeID <= 0 或 requestParam 为空时返回错误；projectID > 0 时用于校验节点归属，
	// 避免模型把参数写到别的项目的节点上。
	BuildAnalysisNodeParams(ctx context.Context, input AnalysisNodeParamsInput) (AnalysisNodeParamsResult, error)
}

type AnalysisNodeParamsInput struct {
	// AnalysisNodeID 是目标分析节点主键。
	AnalysisNodeID int64 `json:"analysis_node_id,string"`
	// ProjectID 是当前激活项目 ID（>0 时校验节点归属）。
	ProjectID int64 `json:"project_id,string"`
	// RequestParam 是模型依据 io_schema.json 生成的请求参数，键为 io_schema 中的 name。
	RequestParam map[string]any `json:"request_param"`
}

type AnalysisNodeParamsResult struct {
	AnalysisNodeID int64 `json:"analysis_node_id,string"`
	ScriptID       int64 `json:"script_id,string"`

	WorkspaceDir string `json:"workspace_dir"`
	ParamsPath   string `json:"params_path"`
	CommandPath  string `json:"command_path,omitempty"`
	// ParamsJSON 是写入 params.json 的实际内容（缩进后的 JSON 文本）。
	ParamsJSON string `json:"params_json"`
	// ResolvedInputs 是按脚本表单解析后的结构化输入（即写入 params.json 的主体）。
	ResolvedInputs map[string]any `json:"resolved_inputs,omitempty"`
	// Warnings 是解析过程中发现的非致命问题（如 io_schema 参数未被提供）。
	Warnings []string `json:"warnings,omitempty"`
}

type AnalysisNodeRunResult struct {
	NodeID int64 `json:"analysis_node_id"`
	// ScriptID 是该节点绑定的脚本 ID：运行后用它配合 get_script / 脚本路径定位
	// 本次实际执行的脚本，无需再额外查节点。
	ScriptID int64  `json:"script_id,omitempty"`
	Status   string `json:"status"`  // 节点终态（如 success / failed / timeout）
	Log      string `json:"log"`     // 节点 command.log 的内容
	Success  bool   `json:"success"` // 是否为成功终态

	// WorkspaceDir 是节点根目录（绝对路径），节点的 params.json / run.sh / output /
	// command.log 全部由它派生，方便模型在该目录下定位产物。
	WorkspaceDir string `json:"workspace_dir,omitempty"`
	// CommandPath 是本次运行实际执行的 run.sh 绝对路径，便于模型读脚本复核参数。
	CommandPath string `json:"command_path,omitempty"`
	// ParamsPath 是节点 params.json 的绝对路径（本次运行的输入参数）。
	ParamsPath string `json:"params_path,omitempty"`
	// LogPath 是节点命令日志 command.log 的绝对路径。Log 会按 maxLogBytes 截断，
	// 模型可在需要完整日志时用 read_file 类工具按该路径读取。
	LogPath string `json:"log_path,omitempty"`
	// ParamsJSON 是本次运行实际使用的 params.json 正文（运行前由 runner 重新生成），
	// 便于模型确认脚本实际拿到的参数，无需再读盘。
	ParamsJSON string `json:"params_json,omitempty"`
	// RequestParam 是本次运行使用的请求参数（键为 io_schema inputs 的 name）。
	// 传入 request_param 时为本次入参，未传时从节点记录的 request_param 反解而来。
	RequestParam map[string]any `json:"request_param,omitempty"`
	// ResolvedInputs 是按脚本 io_schema 解析 request_param 后的结构化输入。
	ResolvedInputs map[string]any `json:"resolved_inputs,omitempty"`
	// InputValidationErrors / OutputValidationErrors 是本次运行前写回节点的校验错误
	// 快照（运行前会被清空，由编排器在运行期重新填充）。
	InputValidationErrors  []any `json:"input_validation_errors,omitempty"`
	OutputValidationErrors []any `json:"output_validation_errors,omitempty"`
	// ParamsWarnings 是参数解析阶段发现的非致命问题（如缺少必填输入、
	// 存在 io_schema 未声明的键）。
	ParamsWarnings []string `json:"params_warnings,omitempty"`
}

type AnalysisNodeRunner interface {
	// RunAnalysisNode 触发分析节点执行并阻塞等待其进入终态，返回执行日志内容。
	//
	// requestParam 是本次运行的请求参数（键为脚本 io_schema inputs 的 name），可选：
	// 非空时以它为准（并回写节点记录），为空时回退到 AnalysisNode 记录上已保存的
	// request_param。
	//
	// 实现必须在每次运行前按 analysisform.BuildParseAnalysisResult 解析 request_param：
	// 先把解析结果（request_param / resolved_inputs / inputs_patterns / output_patterns）
	// 回写到 AnalysisNode，清空上一轮 input_validation_errors / output_validation_errors，
	// 再重新生成 params.json，最后提交运行。
	//
	// timeoutSeconds <= 0 时由实现选取默认超时。节点运行失败（非成功终态 /
	// 超时）时返回错误，同时返回已读取到的日志片段（可能为空）。
	RunAnalysisNode(ctx context.Context, nodeID int64, requestParam map[string]any, timeoutSeconds int) (AnalysisNodeRunResult, error)
}

type AnalysisNodeUpdater interface {
	// UpdateAgentAnalysis 更新 agent 节点（命令节点，无脚本）。
	//
	// 可更新 node_name / command / container_template_id；未给出的字段保持原值。
	// command 变更后会重新生成 run.sh。节点必须属于 projectID，且节点类型必须为 agent。
	UpdateAgentAnalysis(ctx context.Context, input AgentAnalysisUpdateInput) (AgentAnalysisUpdateResult, error)

	// UpdateScriptAnalysis 更新 script / scheduler 节点（绑定脚本）。
	//
	// 可更新 node_name / request_param；request_param 非 nil 时按脚本最新 io_schema 重新解析
	// resolved_inputs 并重新生成 params.json（空对象表示清空参数）。
	// 节点必须属于 projectID，且节点必须绑定脚本（类型为 script 或 scheduler）。
	UpdateScriptAnalysis(ctx context.Context, input ScriptAnalysisUpdateInput) (ScriptAnalysisUpdateResult, error)
}

type ContainerTemplateBrief struct {
	DefinitionID int64  `json:"definition_id"`
	SpecID       int64  `json:"spec_id"`
	Name         string `json:"name"`
	Description  string `json:"description,omitempty"`
}

type ContainerTemplateBrowser interface {
	// ListContainerTemplates 返回全部可运行容器模板。
	//
	// 每一项对应一行 go_container_template_definition（ID 即对外的容器模板 ID），
	// Name / Description 取自该绑定行关联的 go_container_template_spec。
	ListContainerTemplates(ctx context.Context) ([]ContainerTemplateBrief, error)

	// GetContainerTemplateByID 按主键读取一个可运行容器模板（绑定行 + 绑定的共享运行配置）。
	GetContainerTemplateByID(ctx context.Context, containerTemplateID int64) (ContainerTemplateDetail, error)
}

type ContainerTemplateDetail struct {
	DefinitionID int64  `json:"definition_id"`
	SpecID       int64  `json:"spec_id"`
	DisplayName  string `json:"display_name"`
	Description  string `json:"description"`
	ImageName    string `json:"image_name,omitempty"`
	PullPolicy   string `json:"pull_policy,omitempty"`
	IsDefault    bool   `json:"is_default"`
	SpecName     string `json:"spec_name,omitempty"`
}

type ContainerTerminalExecInput struct {
	// UserID 取自执行事实（tool.UserIDFrom）。
	UserID int64
	// ProjectID 取自执行事实（tool.ProjectIDFrom，当前用户激活项目）。
	ProjectID int64
	// AgentSessionID 是发起本次调用的 Agent 会话 ID（tool.SessionIDFrom）。
	//
	// 终端会话按 (ContainerTemplateID, AgentSessionID) 唯一：同一 Agent 会话在同一个模板上
	// 多次执行命令会复用同一个终端会话（同一容器与 PTY）。必须 > 0。
	AgentSessionID int64
	// ContainerTemplateID 是必填的容器模板 ID。
	ContainerTemplateID int64
	// Command 是要在终端里执行的 shell 命令。
	Command string
	// TimeoutSeconds <= 0 时使用实现默认超时。
	TimeoutSeconds int
	// Wait 为 true 时等待命令结束。
	Wait bool
	// CreateIfMissing 为 true 时允许自动创建终端会话（容器）。
	CreateIfMissing bool
	// Persistent 为 true 时把会话标记为持久：命令结束后不回收容器，
	// 直到空闲 TTL 到期或用户显式关闭。false（默认）= 一次性会话，
	// 命令结束后若没有前端终端连接则立即删除会话与容器。
	Persistent bool
}

type ContainerTerminalExecResult struct {
	SessionID       string  `json:"session_id,omitempty"`
	Accepted        bool    `json:"accepted"`
	Running         bool    `json:"running,omitempty"`
	ExitCode        int     `json:"exit_code"`
	TimedOut        bool    `json:"timed_out,omitempty"`
	DurationSeconds float64 `json:"duration_seconds,omitempty"`
	Output          string  `json:"output,omitempty"`
	OutputTruncated bool    `json:"output_truncated,omitempty"`
}

type ContainerTerminalRunner interface {
	// RunInTerminal 把 command 写入会话的串行队列。
	//
	// Wait=true 时等待命令结束并返回退出码与输出尾部；Wait=false 时只投递并立即返回
	// （Accepted=true，Running=true）。
	//
	// 命令结束（含超时 / 失败）后实现方必须「解绑」本次调用：
	// 一次性会话（Persistent=false）若已无前端终端连接会被立即回收，
	// 持久会话（Persistent=true）则保留，直到空闲 TTL 或显式关闭。
	RunInTerminal(ctx context.Context, in ContainerTerminalExecInput) (ContainerTerminalExecResult, error)
}

type DatasetBrief struct {
	DatasetID   int64  `json:"dataset_id"`
	DatasetName string `json:"dataset_name"`
	Description string `json:"description,omitempty"`
	Path        string `json:"path"`
}

type DatasetBrowser interface {
	// GetDatasetByID 按主键读取数据集（必须属于当前激活项目，否则返回错误）。
	//
	// 用于解析用户输入里的 @dataset:<id> 引用：返回数据集名称 / 描述与其工作目录的
	// 绝对路径（utils.GetDatasetDir），模型可直接按该路径读取 / 写入数据集文件。
	GetDatasetByID(ctx context.Context, projectID int64, datasetID int64) (DatasetBrief, error)
}

type DatasetFileAddInput struct {
	// ProjectID 取自执行事实（tool.ProjectIDFrom，当前用户激活项目）。
	ProjectID int64
	// DatasetID 是目标数据集主键（go_dataset）。
	DatasetID int64
	// Path 是要登记的文件路径：绝对路径或相对数据集工作目录的路径。
	Path string
	// Role 是文件角色（go_file.role），空时由实现回退到 DEFAULT。
	Role string
	// FileName 是展示文件名，空时由实现取 Path 的 basename。
	FileName string
	// IsPrefix 为 true 时把 Path 当作前缀（不校验文件是否存在）。
	IsPrefix bool
	// IsCopy 为 true 时把文件复制到数据集目录后再登记。
	IsCopy bool
}

type DatasetFileAddResult struct {
	DatasetID int64  `json:"dataset_id"`
	FileID    int64  `json:"file_id"`
	FilePath  string `json:"file_path"`
	FileName  string `json:"file_name"`
	Role      string `json:"role,omitempty"`
	Format    string `json:"format,omitempty"`
	Size      int64  `json:"size,omitempty"`
}

type DatasetWriter interface {
	// EnsureDatasetByKey 返回当前激活项目下 dataset_key 匹配的数据集；不存在时按
	// key 作为名称创建并绑定到项目。第二个返回值表示本次是否新建。
	EnsureDatasetByKey(ctx context.Context, projectID int64, datasetKey string) (DatasetBrief, bool, error)

	// AddFileToDataset 把 Path 指向的文件登记为 DatasetID 的数据集文件。
	//
	// 绝对路径必须在存储根目录（storage.base_dir）内；相对路径相对数据集工作目录
	// （utils.GetDatasetDir）解析。IsPrefix / IsCopy 语义与
	// types.AddFileToDatasetRequest 一致。
	AddFileToDataset(ctx context.Context, in DatasetFileAddInput) (DatasetFileAddResult, error)
}

type FileReadResult struct {
	FileID   int64          `json:"file_id"`
	FileName string         `json:"file_name,omitempty"`
	FilePath string         `json:"file_path"`
	Format   string         `json:"format,omitempty"`
	Sheets   []FileSheetTab `json:"sheets,omitempty"`
	Message  string         `json:"message,omitempty"`
}

type FileReader interface {
	// ReadFileByID 按 go_file 主键 ID 读取文件，返回文件元信息与内容预览。
	//
	// fileID 非法（<=0）或文件不存在时返回错误。
	ReadFileByID(ctx context.Context, fileID int64) (FileReadResult, error)
}

type FileSheetTab struct {
	Name    string           `json:"name"`
	Columns []string         `json:"columns,omitempty"`
	Rows    []map[string]any `json:"rows,omitempty"`
}

type MemorySaveInput struct {
	UserID int64 `json:"user_id,string"`
	// ID 为 0 表示新建（主键由 Memory.BeforeCreate 分配）；> 0 表示更新既有记忆。
	ID int64 `json:"id,omitempty,string"`
	// SessionID 可选：把记忆与某个具体会话关联（会话主键，0 表示不关联）。
	SessionID int64 `json:"session_id,omitempty,string"`
	// ProjectID 可选：记忆所属项目（写入 Metadata["project_id"]），用于上下文优先检索。
	ProjectID int64 `json:"project_id,omitempty,string"`
	// Kind 是记忆类别（fact / summary / note / event），非法值由实现兜底为 note。
	Kind string `json:"kind,omitempty"`
	// Content 是记忆正文（注意事项 / 事实 / 摘要）。
	Content string `json:"content"`
	// Importance 是重要度（0-10），用于检索排序。
	Importance int `json:"importance,omitempty"`
	// Metadata 是扩展信息（来源、标签等）。
	Metadata map[string]any `json:"metadata,omitempty"`
}

type MemorySaveResult struct {
	ID         int64  `json:"id,string"`
	Kind       string `json:"kind"`
	Importance int    `json:"importance"`
	// Created 标识本次是新建（true）还是更新既有记忆（false）。
	Created bool `json:"created"`
}

type MemorySaver interface {
	// SaveMemory 创建或更新一条记忆。
	//
	// input.ID > 0 表示更新该条记忆（不存在时返回错误），为 0 表示新建；新建时主键由
	// 持久化层的 agent.Memory.BeforeCreate 统一分配（雪花 ID）。
	SaveMemory(ctx context.Context, input MemorySaveInput) (MemorySaveResult, error)
}

type ProjectReportContext struct {
	ReportID  int64 `json:"report_id"`
	ProjectID int64 `json:"project_id"`
	// ReportTitle 是报告标题。
	ReportTitle string `json:"report_title"`
	// WorkingDir 是报告工作目录（<baseDir>/data/<projectId>/report/<reportId>）。
	WorkingDir string `json:"workspace_directory"`
	// OutputFile 是报告输出文件（工作目录下的 output.md，见 types.DefaultProjectReportFilename）。
	OutputFile string `json:"output_file"`
	// Items 是报告条目（按树的前序遍历，与前端 tree 顺序一致）。
	Items []ProjectReportItemBrief `json:"project_report_items"`
}

type ProjectReportContextResolver interface {
	// GetReportContext 返回报告标题、工作目录、输出文件与已解析的条目列表。
	//
	// reportID 必须属于当前激活项目（projectID），否则返回错误；userID 用于校验报告
	// 条目列表的访问权限。
	GetReportContext(ctx context.Context, userID int64, projectID int64, reportID int64) (ProjectReportContext, error)
}

type ProjectReportItemBrief struct {
	Name      string `json:"name"`
	Content   string `json:"content"`
	OwnerType string `json:"owner_type"`
}

type RuntimeContext struct {
	// Type 是归一化后的业务类型（script / analysis / analysisNode / projectReport，
	// 为空表示默认工作区）。
	Type string `json:"type,omitempty"`
	// Label 是人类可读的上下文名称（如节点名 / 报告标题），用于前端展示。
	Label string `json:"label,omitempty"`
	// SystemPromptVars 是渲染 Profile 系统提示词模板（pongo2）所需的变量
	// （如 analysis_node_id / workspace_directory / script_file_path 等）。
	SystemPromptVars map[string]any `json:"system_prompt_vars,omitempty"`
}

type ScriptAnalysisUpdateInput struct {
	// ProjectID 是节点所属项目（取自 RuntimeContext.ProjectID）。
	ProjectID int64 `json:"project_id,string"`
	// AnalysisNodeID 是分析节点主键，必须为正数。
	AnalysisNodeID int64 `json:"analysis_node_id,string"`
	// NodeName 为 nil 表示不修改；非 nil 时覆盖节点名称（不能为空）。
	NodeName *string `json:"node_name,omitempty"`
	// RequestParam 为 nil 表示不修改；非 nil 时按脚本 io_schema 重新解析并覆盖节点参数。
	RequestParam map[string]any `json:"request_param,omitempty"`
}

type ScriptAnalysisUpdateResult struct {
	AnalysisNodeID int64          `json:"analysis_node_id,string"`
	NodeName       string         `json:"node_name"`
	ScriptID       int64          `json:"script_id,string,omitempty"`
	WorkspaceDir   string         `json:"workspace_dir,omitempty"`
	ParamsPath     string         `json:"params_path,omitempty"`
	CommandPath    string         `json:"command_path,omitempty"`
	RequestParam   map[string]any `json:"request_param,omitempty"`
	// Warnings 是参数解析阶段的非致命提示（缺少必填输入 / 存在 io_schema 未声明的键）。
	Warnings []string `json:"warnings,omitempty"`
	// Changed 列出本次实际被修改的字段（node_name / request_param）。
	Changed []string `json:"changed,omitempty"`
}

type ScriptBrief struct {
	ScriptID int64 `json:"script_id"`
	// ContainerTemplateID 是脚本绑定的容器模板 ID（go_container_template_definition 主键，
	// 即对外 ContainerTemplate.ID），可直接用于 list_container_templates 的查询结果对账 /
	// 运行配置核对；0 表示脚本尚未绑定容器模板。
	ContainerTemplateID int64  `json:"container_template_id,omitempty"`
	ScriptName          string `json:"script_name"`
	Description         string `json:"description,omitempty"`
	ScriptType          string `json:"script_type,omitempty"`
	ScriptFilePath      string `json:"script_file_path"`
	IOSchemaPath        string `json:"io_schema_path"`
}

type ScriptBrowser interface {
	// ListScriptsByProject 返回指定项目下的全部脚本（item_type/pipeline 中 component_type=script）。
	//
	// 结果按 id 倒序，不分页（项目内脚本数量有限）；projectID 必须为正数。
	ListScriptsByProject(ctx context.Context, projectID int64) ([]ScriptBrief, error)

	// GetScriptByID 按主键读取脚本（必须属于当前激活项目，否则返回错误）。
	//
	// projectID 取自执行事实，scriptID 是 pipeline_components 主键。
	GetScriptByID(ctx context.Context, projectID int64, scriptID int64) (ScriptBrief, error)
}

type ScriptCreateInput struct {
	// ProjectID 是脚本所属项目（取自 RuntimeContext.ProjectID）。
	ProjectID int64 `json:"project_id,string"`
	// 以下为 Script 字段。
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// ContainerTemplateID 为 0 时表示未指定，由实现解析系统默认容器模板。
	ContainerTemplateID int64  `json:"container_template_id,string"`
	ScriptType          string `json:"script_type"`
	// Inputs / Outputs 是脚本的输入输出契约（io_schema.json 的 inputs / outputs）。
	// 非空时由实现写入脚本目录的 io_schema.json；为空时实现回落默认 schema。
	// 每一项至少应包含 name / type，可选 label / required / description 等字段。
	Inputs  []map[string]any `json:"inputs,omitempty"`
	Outputs []map[string]any `json:"outputs,omitempty"`
}

type ScriptCreateResult struct {
	ScriptID int64 `json:"script_id,string"`
	// ScriptKey 是 Script.ScriptID（组件业务 ID，脚本目录名）。
	ScriptKey      string `json:"script_key"`
	ScriptName     string `json:"script_name"`
	ScriptFilePath string `json:"script_file_path"`
	IOSchemaPath   string `json:"io_schema_path"`
	// ScriptType 是实际生效的脚本类型（未传时为默认类型）。
	ScriptType string `json:"script_type,omitempty"`

	// ContainerTemplateID 是脚本最终使用的容器模板 ID（未显式指定时为解析出的默认模板）。
	ContainerTemplateID   int64  `json:"container_template_id,string"`
	ContainerTemplateName string `json:"container_template_name,omitempty"`
}

type ScriptCreator interface {
	// CreateScript 创建脚本并初始化脚本目录，返回脚本 ID 与主文件 / io_schema.json 路径。
	//
	// projectID 取自 RuntimeContext.ProjectID（当前用户激活项目），必须为正数。
	// input.ContainerTemplateID 为空（0）时由实现解析系统默认容器模板；
	// 没有配置默认模板时返回错误，提示用户先到容器模板页设置默认模板。
	CreateScript(ctx context.Context, input ScriptCreateInput) (ScriptCreateResult, error)
}

type ScriptUpdateInput struct {
	// ProjectID 是脚本所属项目（取自 RuntimeContext.ProjectID）。
	ProjectID int64 `json:"project_id,string"`
	// ScriptID 是 Script 主键（pipeline_components.id），必须为正数。
	ScriptID int64 `json:"script_id,string"`
	// Name / Description 为 nil 表示不修改；非 nil 时覆盖对应字段。
	Name        *string `json:"name,omitempty"`
	Description *string `json:"description,omitempty"`
}

type ScriptUpdateResult struct {
	ScriptID       int64  `json:"script_id,string"`
	ScriptName     string `json:"script_name"`
	Description    string `json:"description,omitempty"`
	ScriptType     string `json:"script_type,omitempty"`
	ScriptFilePath string `json:"script_file_path,omitempty"`
	IOSchemaPath   string `json:"io_schema_path,omitempty"`
	// Changed 列出本次实际被修改的字段名（name / description），便于模型确认。
	Changed []string `json:"changed,omitempty"`
}

type ScriptUpdater interface {
	// UpdateScriptInfo 更新脚本的 name / description，返回更新后的关键信息。
	//
	// projectID 取自 RuntimeContext.ProjectID（当前用户激活项目）：脚本必须属于该项目，
	// 否则返回错误（避免模型改到别的项目的脚本）。
	// scriptID 是 Script 主键（int64），必须为正数。
	// name / description 为指针：nil 表示「不修改该字段」，非 nil 时按值覆盖
	// （description 允许被显式置为空字符串以清空描述）。
	UpdateScriptInfo(ctx context.Context, input ScriptUpdateInput) (ScriptUpdateResult, error)
}

type SkillInfo struct {
	Name         string
	Description  string
	SkillPath    string
	SkillFile    string
	Instructions string
	// DisableRender 为 true 时，技能文本（指令正文 / 附属资源）按原文返回，
	// 不做 pongo2 模板渲染（见 skill.Skill.DisableRender）。
	DisableRender bool
}

type SkillResolver interface {
	// Get 按名称解析技能；不存在时 ok 为 false。
	Get(name string) (SkillResource, bool)
	// Names 返回全部可用技能名（用于错误提示）。
	Names() []string
}

type SkillResource interface {
	// SkillInfo 返回技能的元信息与指令正文（SKILL.md 内容）。
	SkillInfo() SkillInfo
	// SkillVersion 返回技能版本（manifest.json 优先，回退 frontmatter version）。
	SkillVersion() string
	// SkillResources 返回技能目录下的附属资源相对路径（已排序）。
	SkillResources() []string
	// ReadSkillResource 读取技能目录内的附属资源（相对路径），返回内容与绝对路径。
	ReadSkillResource(path string) (content string, absPath string, err error)
}