builtin

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 9, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package builtin 提供框架内置的工具（如 get_weather）。

约定：所有内置工具都直接实现 tool.Tool（通常用 tool.NewFunc 构造），不引入 adapter 层；新工具在本包新建文件实现后，把构造函数追加到 All()，并在 Deps 中 暴露它需要的进程级静态依赖即可接入各 Provider 的 tool-call 链路。

依赖约定：进程级静态服务（分析节点执行器 / 浏览器 / 技能解析等）通过构造函数 从 Deps 注入；随请求变化的事实（用户 / 会话 / 项目 / RuntimeContext）与权限 仍由 Provider 在执行工具前注入 ctx。

Index

Constants

View Source 
const AddFileToDatasetToolName = "add_file_to_dataset"

AddFileToDatasetToolName 是「把文件添加到数据集」的工具名。

View Source 
const BuildAnalysisNodeParamsToolName = "build_analysis_node_params"

BuildAnalysisNodeParamsToolName 是「生成分析节点参数」工具名。

View Source 
const CreateAgentAnalysisToolName = "create_agent_analysis"

CreateAgentAnalysisToolName 是「创建命令型分析节点（可选运行）」的工具名。

View Source 
const CreateScriptAnalysisToolName = "create_script_analysis"

CreateScriptAnalysisToolName 是「为已有脚本创建分析节点（可选运行）」工具名。

View Source 
const CreateScriptToolName = "create_script"

CreateScriptToolName 是「创建脚本 + 分析节点」工具名。

View Source 
const DefaultScriptType = "qmd"

DefaultScriptType 是 create_script 未指定 script_type 时使用的脚本类型。

View Source 
const GetAnalysisNodeToolName = "get_analysis_node"

GetAnalysisNodeToolName 是「按 ID 查看分析节点」工具名。

View Source 
const GetContainerTemplateToolName = "get_container_template"

GetContainerTemplateToolName 是「按 @container:<id> 查看容器模板」的工具名。

View Source 
const GetDatasetToolName = "get_dataset"

GetDatasetToolName 是「按 @dataset:<id> 查看数据集」的工具名。

View Source 
const GetProjectDatabasePathToolName = "get_project_database_path"

GetProjectDatabasePathToolName 是「获取项目默认数据库目录」的工具名。

View Source 
const GetReportContextToolName = "get_report_context"

GetReportContextToolName 是「按 @report:<id> 获取报告撰写上下文」工具名。

View Source 
const GetScriptToolName = "get_script"

GetScriptToolName 是「按 ID 查看脚本」工具名。

View Source 
const ListContainerTemplatesToolName = "list_container_templates"

ListContainerTemplatesToolName 是「列出全部容器模板」工具名。

View Source 
const ListProjectScriptsToolName = "list_project_scripts"

ListProjectScriptsToolName 是「列出当前项目全部脚本」工具名。

View Source 
const ReadFileByIDToolName = "read_file_by_id"

ReadFileByIDToolName 是「根据文件 ID 读取文件」工具名。

View Source 
const RunAnalysisNodeToolName = "run_analysis_node"

RunAnalysisNodeToolName 是「运行分析节点」工具名。

View Source 
const SaveMemoryToolName = "save_memory"

SaveMemoryToolName 是「保存长期记忆」工具名。

View Source 
const TerminalExecToolName = "terminal_exec"

TerminalExecToolName 是「向用户的容器模板终端写入命令」的工具名。

View Source 
const UpdateAgentAnalysisToolName = "update_agent_analysis"

UpdateAgentAnalysisToolName 是「更新命令型分析节点」工具名。

View Source 
const UpdateScriptAnalysisToolName = "update_script_analysis"

UpdateScriptAnalysisToolName 是「更新脚本型分析节点」工具名。

View Source 
const UpdateScriptToolName = "update_script"

UpdateScriptToolName 是「更新脚本基本信息」工具名。

Variables

This section is empty.

Functions

func AddFileToDataset added in v0.2.0 

func AddFileToDataset(writer runtimecontext.DatasetWriter) tool.Tool

AddFileToDataset 返回一个「把文件添加到数据集」工具。

行为：

  • 解析 dataset_id（容错剥离 @dataset: 前缀）；
  • 项目取自执行事实（tool.ProjectIDFrom），数据集必须属于当前激活项目；
  • path 为绝对路径时要求位于存储根目录内，相对路径相对数据集工作目录解析；
  • 复用 AddFileToDataset 业务链路：登记（或复用）go_file 并建立 go_dataset_file 绑定，按 role 归档文件。

该工具会写库 / 可能复制文件，因此声明 write 授权，授权路径取入参 path。

func All 

func All(d Deps) []tool.Tool

All 返回框架内置的全部工具。新增内置工具时在此追加，并把所需依赖从 Deps 传入。

func BuildAnalysisNodeParams added in v0.2.0 

func BuildAnalysisNodeParams(builder runtimecontext.AnalysisNodeParamsBuilder) tool.Tool

BuildAnalysisNodeParams 返回一个「按 io_schema 生成分析节点参数」工具。

使用流程（供模型理解）：

  1. 读脚本 io_schema.json（create_script 返回的 io_schema_path，或工作目录里的软链）；
  2. 按 io_schema 的 inputs 拼出 request_param（键为各条目 name）；
  3. 调用本工具：按脚本表单解析 request_param，刷新节点的 inputs_patterns / output_patterns / resolved_inputs / request_param，并生成 params.json；
  4. 调用 run_analysis_node 以刚生成的 params.json 运行脚本。

该工具会写库并写盘（params.json / run.sh 等运行期文件），因此声明 write 授权：上层在 执行前会先走权限门禁。返回的 Error 为空即表示 params.json 已就绪。

func CreateAgentAnalysis added in v0.2.0 

func CreateAgentAnalysis(runner runtimecontext.AgentAnalysisRunner) tool.Tool

CreateAgentAnalysis 返回一个「创建命令型分析节点（可选运行）」工具。

行为：

  • 从 RuntimeContext 取当前项目 ID；
  • 创建一个命令型 AnalysisNode（ContainerTemplateID + Command），run.sh 由 command 生成；
  • run 为 true（默认）时复用通用节点链路提交运行并等待终态； run 为 false 时只创建节点并生成 run.sh，不提交运行；
  • 返回节点状态、是否运行、退出码与命令日志。

该工具会创建分析节点（写库并写出 run.sh），默认还会触发一次运行，因此声明 write 授权， 与其它业务写入类工具共用许可策略。

func CreateScript added in v0.2.0 

func CreateScript(creator runtimecontext.ScriptCreator) tool.Tool

CreateScript 返回一个「创建脚本」工具（只建脚本，不建分析节点）。

行为：

  • 从 RuntimeContext 取当前项目 ID（缺失时直接报错，避免写到错误项目）；
  • script_type 为空时按 DefaultScriptType（qmd）处理；
  • container_template_id 为空时由 ScriptCreator 解析系统默认容器模板， 没有默认模板时回到模型一个错误提示，让用户先去容器模板页配置默认模板；
  • inputs / outputs 非空时写入脚本目录的 io_schema.json（这是脚本的参数契约， 之后 create_script_analysis 会按它初始化节点的 inputs_patterns / output_patterns）；
  • 通过注入的 ScriptCreator 落库 Script 并初始化脚本目录（主文件、io_schema.json）；
  • 把新脚本主文件路径与 io_schema.json 路径回传给模型。

该工具会创建业务数据（写库 + 写盘），因此声明 write 授权：上层在执行前会先走权限门禁。

func CreateScriptAnalysis added in v0.2.0 

func CreateScriptAnalysis(creator runtimecontext.AnalysisNodeCreator, runner runtimecontext.AnalysisNodeRunner) tool.Tool

CreateScriptAnalysis 返回一个「为已有脚本创建分析节点（可选运行）」工具。

行为：按脚本最新 io_schema.json 初始化节点的 inputs_patterns / output_patterns； request_param 非空时按脚本表单解析出 resolved_inputs 并写入节点，同时生成 params.json / run.sh 等运行期文件。run 为 true（默认）时紧接着用通用节点运行链路 提交运行并等待终态，返回状态、执行日志与关键路径；run 为 false 时只创建节点。

该工具会创建业务数据（写库 + 写盘），并在默认情况下触发一次节点运行，因此声明 write 授权。

func GetAnalysisNode added in v0.2.0 

func GetAnalysisNode(browser runtimecontext.AnalysisNodeBrowser) tool.Tool

GetAnalysisNode 返回一个「按 ID 查看分析节点」工具。

行为：

  • 解析必填入参 analysis_node_id（容错剥离 @analysis_node: 引用前缀）；
  • 项目归属取自执行事实（tool.ProjectIDFrom），节点必须属于当前激活项目，否则报错。
  • 回传节点名称、节点类型（creation_source / node_type：agent / script / scheduler）、 工作目录（绝对路径）与 params.json 路径；
  • 按类型区分回传字段：agent 节点回传 command_path（run.sh 绝对路径）， 不回传 script_id / request_param；script / scheduler 节点回传 script_id 与 已保存的 request_param，不回传 command_path。

该工具是只读的，因此声明 read 授权：上层在执行前会先走权限门禁。

func GetContainerTemplate added in v0.2.0 

func GetContainerTemplate(browser runtimecontext.ContainerTemplateBrowser) tool.Tool

GetContainerTemplate 返回一个「按 ID 查看容器模板」工具。

行为：

  • 解析入参 container_template_id（容错剥离 @container: 前缀）；
  • 按主键读取 go_container_template_definition（容器模板是全局资产，不按项目隔离）；
  • 回传绑定行自身的 display_name / description，以及 image_name / pull_policy / is_default / spec_name 等运行信息。

该工具是只读的，因此声明 read 授权：上层在执行前会先走权限门禁。

func GetDataset added in v0.2.0 

func GetDataset(browser runtimecontext.DatasetBrowser) tool.Tool

GetDataset 返回一个「按 ID 查看数据集」工具。

行为：

  • 解析入参 dataset_id（容错剥离 @dataset: 前缀）；
  • 项目归属取自执行事实（tool.ProjectIDFrom），数据集必须绑定到当前激活项目；
  • 回传数据集名称、描述与工作目录绝对路径。

该工具是只读的，因此声明 read 授权：上层在执行前会先走权限门禁。

func GetProjectDatabasePath added in v0.2.0 

func GetProjectDatabasePath(writer runtimecontext.DatasetWriter) tool.Tool

GetProjectDatabasePath 返回一个「获取项目默认数据库目录」工具。

行为：

  • 项目取自执行事实（tool.ProjectIDFrom）；
  • 查找 dataset_key == types.DatasetKeyDatabases（"DATABASES"）的数据集， 不存在时自动创建并绑定到当前项目；
  • 回传该数据集工作目录的绝对路径，模型可直接把参考数据库放在这里复用。

该工具会创建数据集（写库），因此声明 write 授权。

func GetReportContext added in v0.2.0 

func GetReportContext(browser runtimecontext.ProjectReportContextResolver) tool.Tool

GetReportContext 返回一个「按报告 ID 获取报告撰写上下文」工具。

行为：

  • 解析必填入参 report_id（容错剥离 @report: 前缀）；
  • 通过构造注入的 ProjectReportContextResolver 按报告 ID 解析报告标题、工作目录、输出文件与 条目列表（名称 / 内容 / 来源类型），条目解析口径与原 RuntimeContextResolver 的 projectReport 分支一致；
  • 用内置 pongo2 模板把上述事实渲染成一段 Markdown 文本，作为工具结果返回给模型。

该工具是只读的，因此声明 read 授权：上层在执行前会先走权限门禁。

func GetScript added in v0.2.0 

func GetScript(browser runtimecontext.ScriptBrowser) tool.Tool

GetScript 返回一个「按 ID 查看脚本」工具。

行为：

  • 解析必填入参 script_id；
  • 项目归属取自执行事实（tool.ProjectIDFrom），脚本必须属于当前激活项目，否则报错。
  • 回传脚本名称、描述、绑定的容器模板 ID、主文件路径与 io_schema.json 路径。

该工具是只读的，因此声明 read 授权：上层在执行前会先走权限门禁。

func GetWeather 

func GetWeather() tool.Tool

GetWeather 返回一个「获取天气」工具（当前返回模拟数据，供演示 / 联调）。

同一城市返回确定的温度，便于测试断言。后续接入真实天气服务时，只需替换 mockWeather 的内部实现，工具定义与签名保持不变。

该工具需要访问外部天气服务，因此声明 network（fetch）授权：上层在执行前会 先走权限门禁（Runtime.RequestPermission → OperationNetwork）。

func ListContainerTemplates added in v0.2.0 

func ListContainerTemplates(browser runtimecontext.ContainerTemplateBrowser) tool.Tool

ListContainerTemplates 返回一个「列出全部容器模板」工具。

行为：

  • 通过构造注入的 ContainerTemplateBrowser 列出全部 go_container_template_definition；
  • 每行回传 definition 的 ID 及关联 ContainerTemplateSpec 的 Name / Description。

该工具是只读的，因此声明 read 授权：上层在执行前会先走权限门禁。

func ListProjectScripts added in v0.2.0 

func ListProjectScripts(browser runtimecontext.ScriptBrowser) tool.Tool

ListProjectScripts 返回一个「列出当前项目全部脚本」工具。

行为：

  • 从 RuntimeContext 取当前项目 ID（缺失时直接报错）；
  • 通过构造注入的 ScriptBrowser 列出该项目下的全部脚本；
  • 每个脚本回传名称、描述、主文件路径与 io_schema.json 路径。

该工具是只读的，因此声明 read 授权：上层在执行前会先走权限门禁。

func ReadFileByID added in v0.2.0 

func ReadFileByID(reader runtimecontext.FileReader) tool.Tool

ReadFileByID 返回一个「根据文件 ID 读取文件」工具。

行为：

  • 解析入参 file_id（对应用户输入里的 @file:<id> 引用）；
  • 通过注入的 FileReader 按 ID 读取文件元信息与内容预览；
  • 对 tsv / csv / xlsx（全部 sheet）返回列名与前若干行数据，其它格式仅返回文件路径。

该工具是只读的，因此声明 read 授权：路径取自入参 file_id 解析后的文件，上层在执行前 会先走权限门禁。

func RunAnalysisNode added in v0.2.0 

func RunAnalysisNode(runner runtimecontext.AnalysisNodeRunner) tool.Tool

RunAnalysisNode 返回一个「运行分析节点」工具。

适用节点类型：全部三种（creation_source = agent / script / scheduler）， 即 get_analysis_node 返回的 node_type 为 agent / script / scheduler 均可运行。

行为：

  • 解析必填入参 analysis_node_id；
  • agent 命令节点（create_agent_analysis 创建、无脚本）：按节点自身的 run.sh 运行；
  • script / scheduler 脚本节点（create_script_analysis / 前端独立节点 / DAG 调度器）： 使用节点上已保存的 request_param，按脚本最新 io_schema.json 解析并回写节点， 然后重新生成 params.json 再提交运行；
  • 等待节点进入终态，返回执行日志、params_path、params.json 正文与本次生效的 request_param。

运行前会清空节点输出目录（output），因此返回结果只包含本次运行的产物。

本工具不接受 request_param：脚本型节点需要改参数时，先调用 build_analysis_node_params； 想直接运行节点上已保存的参数，直接调用本工具即可。

该工具会改变计算状态（触发一次节点运行），因此声明 analysis_node 授权：与直接执行 shell / 脚本（execute）区分开，便于按动作粒度配置许可策略（如允许 execute 但限制 analysis_node，或反之）。上层在执行前会先走权限门禁。

func SaveMemory added in v0.2.0 

func SaveMemory(saver runtimecontext.MemorySaver) tool.Tool

SaveMemory 返回一个「保存长期记忆」工具。

使用场景（供模型理解）：

  • 调用工具（create_script / run_analysis_node / build_analysis_node_params 等）反复 出现同一类可复现错误时，把「错误现象 + 根因 + 下次如何规避」写成一条 note 记忆；
  • 后续轮次开始时，相关记忆会随系统提示词的「相关记忆」块注入，从而避免重复踩坑。

归属用户由执行事实（见 tool.UserIDFrom）提供，不由模型填写，避免把记忆 写到别的用户名下。

该工具会写入用户级持久化数据，因此声明 write 授权：上层在执行前会先走权限门禁。

func TerminalExec added in v0.2.0 

func TerminalExec(runner runtimecontext.ContainerTerminalRunner) tool.Tool

TerminalExec 返回「在用户容器模板终端里执行命令」的工具。

terminal_exec 写入用户的终端容器，命令输出会实时显示在前端 xterm 中。

持久性由 Persistent 控制：默认 false（一次性，命令结束即回收容器）， true 时跨调用保留终端状态，并通过 realtime 通知前端打开终端标签； 前端打开终端后会话也会被视为持久。

该工具会向容器内写入命令，因此声明 execute 授权：与直接执行 shell 命令共用许可策略。

func UpdateAgentAnalysis added in v0.2.0 

func UpdateAgentAnalysis(updater runtimecontext.AnalysisNodeUpdater, runner runtimecontext.AnalysisNodeRunner, browser runtimecontext.AnalysisNodeBrowser) tool.Tool

UpdateAgentAnalysis 返回一个「更新 Agent 命令节点」工具。

适用节点类型：仅 creation_source=agent（get_analysis_node 返回 node_type=agent）的 命令型节点，即 create_agent_analysis 创建、无绑定脚本、run.sh 由 Agent 生成的节点。 script / scheduler 类型（绑定脚本）请改用 update_script_analysis。

行为：

  • analysis_node_id 必填；node_name / command / container_template_id 至少给出一个；
  • 项目归属取自执行事实（tool.ProjectIDFrom），节点必须属于当前激活项目；
  • 只更新给出的字段，未给出的保持原值；
  • command 会直接写入节点 run.sh（命令不落库），并重建 env.sh / params.json、 清空节点输出目录（output）；
  • run 可选且默认为 true：更新成功后立即运行该节点并等待结束，返回状态与执行日志； run=false 时只更新节点，不提交运行。

该工具会修改业务数据并重写运行期文件，并在默认情况下触发一次节点运行，因此声明 write 授权。

func UpdateScript added in v0.2.0 

func UpdateScript(updater runtimecontext.ScriptUpdater) tool.Tool

UpdateScript 返回一个「更新脚本 name / description」工具。

行为：

  • script_id 为必填，缺省直接报错；
  • 只覆盖本次给出的字段，未给出的字段保持数据库原值；
  • 项目归属取自执行事实（tool.ProjectIDFrom），脚本必须属于当前激活项目，否则报错；
  • 回传更新后的名称 / 描述与脚本主文件、io_schema.json 路径。

该工具会修改业务数据（写库），因此声明 write 授权：上层在执行前会先走权限门禁。

func UpdateScriptAnalysis added in v0.2.0 

func UpdateScriptAnalysis(updater runtimecontext.AnalysisNodeUpdater, runner runtimecontext.AnalysisNodeRunner, browser runtimecontext.AnalysisNodeBrowser) tool.Tool

UpdateScriptAnalysis 返回一个「更新脚本节点」工具。

适用节点类型：仅 creation_source=script 或 scheduler（get_analysis_node 返回 node_type=script / scheduler）的节点，即绑定脚本、参数由脚本 io_schema 解析的节点； agent 类型（无脚本的命令节点）请改用 update_agent_analysis。

行为：

  • analysis_node_id 必填；node_name / request_param 至少给出一个；
  • 项目归属取自执行事实（tool.ProjectIDFrom），节点必须属于当前激活项目；
  • 只更新给出的字段，未给出的保持原值；
  • request_param 非 nil 时按脚本最新 io_schema.json 重新解析并刷新节点参数， 重新生成 params.json 并清空节点输出目录（output）；空对象表示清空参数；
  • run 可选且默认为 true：更新成功后立即运行该节点并等待结束，返回状态与执行日志； run=false 时只更新节点，不提交运行。

该工具会写库并重写 params.json，并在默认情况下触发一次节点运行，因此声明 write 授权。

Types

type AddFileToDatasetInput added in v0.2.0 

type AddFileToDatasetInput struct {
	DatasetID string `json:"dataset_id"`          // 数据集 ID（支持 "@dataset:<id>" 形式）
	Path      string `json:"path"`                // 文件路径：绝对路径或相对数据集目录
	Role      string `json:"role,omitempty"`      // 文件角色，缺省 DEFAULT
	FileName  string `json:"file_name,omitempty"` // 展示文件名，缺省取 basename
	IsPrefix  bool   `json:"is_prefix,omitempty"`
	IsCopy    bool   `json:"is_copy,omitempty"`
}

AddFileToDatasetInput 是 add_file_to_dataset 工具的入参。

DatasetID 对应用户消息里的 @dataset:<id> 引用；Path 必须是文件路径（IsPrefix 为 true 时可以是前缀）。其余字段与 types.AddFileToDatasetRequest 语义一致。

type AddFileToDatasetOutput added in v0.2.0 

type AddFileToDatasetOutput struct {
	DatasetID int64  `json:"dataset_id,string"`
	FileID    int64  `json:"file_id,string"`
	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"`
	Message   string `json:"message,omitempty"`
	Error     string `json:"error,omitempty"`
}

AddFileToDatasetOutput 是 add_file_to_dataset 工具返回给模型的结果。

type BuildAnalysisNodeParamsInput added in v0.2.0 

type BuildAnalysisNodeParamsInput struct {
	AnalysisNodeID string         `json:"analysis_node_id"`
	RequestParam   map[string]any `json:"request_param"`
}

BuildAnalysisNodeParamsInput 是 build_analysis_node_params 工具的入参。

AnalysisNodeID 为必填：模型必须显式给出要生成参数的分析节点 ID，不再从运行时上下文回退。

RequestParam 的键必须与脚本 io_schema.json 中的 name 一一对应；它是对象而不是字符串， 因此这里声明为 map，由工具框架直接把模型生成的 JSON 对象反序列化进来。

type BuildAnalysisNodeParamsOutput added in v0.2.0 

type BuildAnalysisNodeParamsOutput struct {
	AnalysisNodeID int64          `json:"analysis_node_id,string"`
	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"`
	ParamsJSON     string         `json:"params_json,omitempty"`
	ResolvedInputs map[string]any `json:"resolved_inputs,omitempty"`
	Warnings       []string       `json:"warnings,omitempty"`
	Error          string         `json:"error,omitempty"`
}

BuildAnalysisNodeParamsOutput 是 build_analysis_node_params 工具返回给模型的结果。

ParamsJSON 是写入 params.json 的实际正文：模型据此确认 io_schema 参数到运行期参数的 映射是否正确，随后可直接调用 run_analysis_node 以这份参数运行脚本。

type ContainerTemplateItem added in v0.2.0 

type ContainerTemplateItem struct {
	ID          int64  `json:"id,string"`
	SpecID      int64  `json:"spec_id,string"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

ContainerTemplateItem 是单个容器模板的摘要（工具回传给模型的字段）。

ID 是 go_container_template_definition 主键（即对外 ContainerTemplate.ID）， 可原样作为 script.container_template_id 等引用字段使用；Name / Description 来自该绑定行关联的 go_container_template_spec。

type CreateAgentAnalysisInput added in v0.2.0 

type CreateAgentAnalysisInput struct {
	Name string `json:"name"` // 节点名称（也用作容器资源名）
	// ContainerTemplateID 可选：为空时使用系统默认容器模板（is_default）。
	ContainerTemplateID string `json:"container_template_id"` // 容器模板 ID（字符串以保精度）
	Command             string `json:"command"`               // 要执行的 shell 命令
	// Run 可选：是否在创建后立即运行。nil / true 表示运行（默认），false 表示只创建节点。
	Run            *bool `json:"run"`
	TimeoutSeconds int   `json:"timeout_seconds"` // 等待完成的超时（秒），可选
}

CreateAgentAnalysisInput 是 create_agent_analysis 工具的入参。

ProjectID 不由模型提供：它取自执行事实（tool.ProjectIDFrom，当前用户激活项目）， 避免把任务写到别的项目下。

type CreateAgentAnalysisOutput added in v0.2.0 

type CreateAgentAnalysisOutput struct {
	AgentAnalysisID     int64  `json:"agent_analysis_id,string"`
	ContainerInstanceID int64  `json:"container_instance_id,string,omitempty"`
	Status              string `json:"status"`
	Ran                 bool   `json:"ran"` // 本次是否提交了运行（run=false 时为 false）
	Success             bool   `json:"success"`
	ExitCode            int    `json:"exit_code"`
	// Log 是命令日志（超出上限时截断保留末尾，可用 LogPath 读取完整内容）。
	Log string `json:"log,omitempty"`
	// LogPath / WorkspaceDir / CommandPath 便于模型在任务结束后复核产物与命令。
	LogPath      string `json:"log_path,omitempty"`
	WorkspaceDir string `json:"workspace_dir,omitempty"`
	CommandPath  string `json:"command_path,omitempty"`
	Error        string `json:"error,omitempty"`
}

CreateAgentAnalysisOutput 是 create_agent_analysis 工具返回给模型的结果。

type CreateScriptAnalysisInput added in v0.2.0 

type CreateScriptAnalysisInput struct {
	ScriptID     string         `json:"script_id"`     // 脚本主键 ID（必填，字符串以保精度）
	NodeName     string         `json:"node_name"`     // 节点名称，留空时用脚本名称
	RequestParam map[string]any `json:"request_param"` // 初始请求参数（键为 io_schema inputs 的 name），可留空
	// Run 可选：是否在创建后立即运行。nil / true 表示运行（默认），false 表示只创建节点。
	Run            *bool `json:"run"`
	TimeoutSeconds int   `json:"timeout_seconds"` // 等待节点完成的超时（秒），可选
}

CreateScriptAnalysisInput 是 create_script_analysis 工具的入参。

ProjectID 不由模型提供：它取自执行事实（tool.ProjectIDFrom，当前用户激活项目）。

type CreateScriptAnalysisOutput added in v0.2.0 

type CreateScriptAnalysisOutput struct {
	AnalysisNodeID int64          `json:"analysis_node_id,string,omitempty"`
	NodeName       string         `json:"node_name,omitempty"`
	ScriptID       int64          `json:"script_id,string,omitempty"`
	ScriptName     string         `json:"script_name,omitempty"`
	ScriptType     string         `json:"script_type,omitempty"`
	ScriptFilePath string         `json:"script_file_path,omitempty"`
	IOSchemaPath   string         `json:"io_schema_path,omitempty"`
	WorkspaceDir   string         `json:"workspace_dir,omitempty"`
	ParamsPath     string         `json:"params_path,omitempty"`
	RequestParam   map[string]any `json:"request_param,omitempty"`
	// Ran 表示本次是否提交了运行（run=false 时为 false，Status/Log 等运行期字段为空）。
	Ran    bool   `json:"ran"`
	Status string `json:"status,omitempty"` // 节点终态（success / failed / timeout ...）
	// Success 为 true 表示节点以成功终态结束。
	Success bool `json:"success"`
	// Log 是命令日志（超出上限时截断保留末尾，可用 LogPath 读取完整内容）。
	Log string `json:"log,omitempty"`
	// LogPath / CommandPath 便于模型复核本次运行的日志与 run.sh。
	LogPath     string `json:"log_path,omitempty"`
	CommandPath string `json:"command_path,omitempty"`
	Error       string `json:"error,omitempty"`
}

CreateScriptAnalysisOutput 是 create_script_analysis 工具返回给模型的结果。

除节点自身的路径（WorkspaceDir / ParamsPath）之外，也回传脚本在磁盘上的关键路径：

  • ScriptFilePath：脚本主文件（如 main.R），由 utils.GetScriptFile 推导；
  • IOSchemaPath：脚本目录下的 io_schema.json（节点 patterns 的来源）。

type CreateScriptInput added in v0.2.0 

type CreateScriptInput struct {
	Name                string `json:"name"`                  // 脚本名称（Script.Name）
	Description         string `json:"description"`           // 脚本描述（Script.Description）
	ContainerTemplateID string `json:"container_template_id"` // 容器运行配置 ID（字符串以保精度），为空时取默认模板
	ScriptType          string `json:"script_type"`           // 脚本类型：qmd（默认）/ r / python / shell / jupyter
	// Inputs / Outputs 是脚本的输入输出契约（写入 io_schema.json 的 inputs / outputs）。
	// 为空时使用系统的默认 schema。
	Inputs  []map[string]any `json:"inputs"`
	Outputs []map[string]any `json:"outputs"`
}

CreateScriptInput 是 create_script 工具的入参（只创建脚本，不创建分析节点）。

ProjectID 不由模型提供：它取自执行事实（tool.ProjectIDFrom，当前用户激活项目）， 避免模型把脚本写到别的项目里。

type CreateScriptOutput added in v0.2.0 

type CreateScriptOutput struct {
	ScriptID       int64  `json:"script_id,string"`
	ScriptKey      string `json:"script_key,omitempty"`
	ScriptName     string `json:"script_name,omitempty"`
	ScriptFilePath string `json:"script_file_path,omitempty"`
	IOSchemaPath   string `json:"io_schema_path,omitempty"`
	// ScriptType 是实际生效的脚本类型（未传时为 qmd）。
	ScriptType string `json:"script_type,omitempty"`

	// ContainerTemplateID / ContainerTemplateName 是实际生效的容器模板：
	// 未传 container_template_id 时为系统默认模板。
	ContainerTemplateID   int64  `json:"container_template_id,string,omitempty"`
	ContainerTemplateName string `json:"container_template_name,omitempty"`

	Error string `json:"error,omitempty"`
}

CreateScriptOutput 是 create_script 工具返回给模型的结果。

除 ID 之外，把新脚本在磁盘上的关键路径一并返回，模型可直接读写：

  • ScriptFilePath：脚本主文件（如 main.R），由 utils.GetScriptFile 推导；
  • IOSchemaPath：脚本目录下的 io_schema.json，由 utils.ScriptIOSchemaPath 推导。

需要运行脚本时，再用 create_script_analysis 建节点（节点 ID / 工作目录 / params.json 路径由该工具返回）。

type Deps added in v0.2.0 

type Deps struct {
	// Runner 运行分析节点（run_analysis_node / create_script_analysis / update_*）。
	Runner runtimecontext.AnalysisNodeRunner
	// AgentRunner 创建并（可选）运行命令型分析节点（create_agent_analysis）。
	AgentRunner runtimecontext.AgentAnalysisRunner
	// Terminal 向用户的持久终端会话写入命令（terminal_exec）。
	Terminal runtimecontext.ContainerTerminalRunner
	// FileReader 按 go_file 主键读取文件（read_file_by_id）。
	FileReader runtimecontext.FileReader
	// ScriptCreator 创建脚本（create_script）；同时实现 ScriptUpdater 时也用于 update_script。
	ScriptCreator runtimecontext.ScriptCreator
	// NodeCreator 为已有脚本创建分析节点（create_script_analysis）。
	NodeCreator runtimecontext.AnalysisNodeCreator
	// ParamsBuilder 按 io_schema 生成节点参数（build_analysis_node_params）。
	ParamsBuilder runtimecontext.AnalysisNodeParamsBuilder
	// NodeUpdater 更新分析节点（update_agent_analysis / update_script_analysis）。
	NodeUpdater runtimecontext.AnalysisNodeUpdater
	// MemorySaver 保存用户长期记忆（save_memory）。
	MemorySaver runtimecontext.MemorySaver

	// 以下为只读浏览能力，按资源拆成窄接口。
	ScriptBrowser   runtimecontext.ScriptBrowser
	NodeBrowser     runtimecontext.AnalysisNodeBrowser
	TemplateBrowser runtimecontext.ContainerTemplateBrowser
	DatasetBrowser  runtimecontext.DatasetBrowser
	ReportContext   runtimecontext.ProjectReportContextResolver
	// DatasetWriter 准备已知 key 的数据集 / 向数据集登记文件
	// （get_project_database_path / add_file_to_dataset）。
	DatasetWriter runtimecontext.DatasetWriter

	// Skills 技能解析能力（get_skill / load_skill_resource）。
	Skills runtimecontext.SkillResolver
}

Deps 是内置工具集的进程级静态依赖。

这些能力在进程启动时由 container 一次性装配（见 buildAgentClient），随工具构造函数 注入，而不是在每次调用时塞进 context：工具依赖因此对编译器可见、可单测，也不再需要 为每个能力维护一套 With/From。

与业务相关的动态事实（RuntimeContext / TaskFacts / 权限）仍然走工具执行 ctx， 因为它们随请求变化、且 RuntimeContext 会随 agent_tasks.request 序列化落库。

字段按工具消费者拆成窄接口（见 runtimecontext 包），容器用一个实现即可同时满足； 测试 fake 只需实现被用到的那一个。

type GetAnalysisNodeInput added in v0.2.0 

type GetAnalysisNodeInput struct {
	AnalysisNodeID string `json:"analysis_node_id"` // 分析节点主键 ID（必填，支持 "@analysis_node:<id>" 形式，字符串以保精度）
}

GetAnalysisNodeInput 是 get_analysis_node 工具的入参。

AnalysisNodeID 为必填：模型必须显式给出要查看的分析节点 ID，不再从运行时上下文回退。 可以直接传用户消息里的 @analysis_node:<id> 引用文本（前缀会被容错剥离）。 项目归属取自执行事实（tool.ProjectIDFrom），节点必须属于当前激活项目。

type GetAnalysisNodeOutput added in v0.2.0 

type GetAnalysisNodeOutput struct {
	AnalysisNodeID      int64  `json:"analysis_node_id,string"`
	NodeName            string `json:"node_name"`
	CreationSource      string `json:"creation_source,omitempty"`       // 落库值：agent / script / scheduler
	NodeType            string `json:"node_type,omitempty"`             // 归一化节点类型：agent / script / scheduler
	NodeTypeDescription string `json:"node_type_description,omitempty"` // 节点类型中文说明与可用工具
	// ScriptID 仅 script / scheduler 节点返回；agent 命令节点无脚本，该字段不出现。
	ScriptID int64 `json:"script_id,string,omitempty"`
	// WorkspaceDir 是节点根目录（绝对路径），output / params.json / run.sh / command.log 均在其下。
	WorkspaceDir string `json:"workspace_dir"`
	// CommandPath 仅 agent 命令节点返回，是节点本次执行的 run.sh 绝对路径。
	CommandPath string `json:"command_path,omitempty"`
	ParamsPath  string `json:"params_path"`
	// RequestParam 仅 script / scheduler 节点返回（键为脚本 io_schema inputs 的 name）；agent 节点不返回。
	RequestParam map[string]any `json:"request_param,omitempty"`
	Error        string         `json:"error,omitempty"`
}

GetAnalysisNodeOutput 是 get_analysis_node 工具返回给模型的结果。

WorkspaceDir 是节点根目录（绝对路径），ParamsPath 由它派生。

节点类型只有三种，由 CreationSource 标识，NodeType 是其归一化结果（两者取值一致）：

  • agent：Agent 命令节点（无脚本，run.sh 由 Agent 生成），用 update_agent_analysis 修改；
  • script：脚本节点（前端独立节点 / create_script_analysis 创建），用 update_script_analysis 修改；
  • scheduler：DAG 调度器节点（绑定脚本），用 update_script_analysis 修改。

回传字段按节点类型区分，避免模型拿错口径：

  • agent：返回 command_path（run.sh 绝对路径），不返回 script_id / request_param；
  • script / scheduler：返回 script_id 与 request_param（键为脚本 io_schema inputs 的 name）， 不返回 command_path。

三种类型都可以用 run_analysis_node 运行。

type GetContainerTemplateInput added in v0.2.0 

type GetContainerTemplateInput struct {
	ContainerTemplateID string `json:"container_template_id"` // 容器模板 ID（支持 "@container:<id>" 形式）
}

GetContainerTemplateInput 是 get_container_template 工具的入参。

ContainerTemplateID 对应用户消息里的 @container:<id> 引用（如 "@container:2109711590457610240"）， 它是 go_container_template_definition 主键，可直接作为 create_script / create_agent_analysis 的 container_template_id 使用。

type GetContainerTemplateOutput added in v0.2.0 

type GetContainerTemplateOutput struct {
	ContainerTemplateID int64  `json:"container_template_id,string"`
	SpecID              int64  `json:"spec_id,string"`
	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 是该绑定行关联的共享运行配置名称，便于区分「模板展示名」与「配置名」。
	SpecName string `json:"spec_name,omitempty"`
	Error    string `json:"error,omitempty"`
}

GetContainerTemplateOutput 是 get_container_template 工具返回给模型的结果。

DisplayName / Description 原样取自绑定行 ContainerTemplateDefinition： DisplayName 是模板展示名，Description 是该模板（可运行配置 × 镜像）自身的说明。

type GetDatasetInput added in v0.2.0 

type GetDatasetInput struct {
	DatasetID string `json:"dataset_id"` // 数据集 ID（支持 "@dataset:<id>" 形式）
}

GetDatasetInput 是 get_dataset 工具的入参。

DatasetID 对应用户消息里的 @dataset:<id> 引用（如 "@dataset:2109711590457610240"）， 它是 go_dataset 主键；所属项目取自执行事实（tool.ProjectIDFrom）。

type GetDatasetOutput added in v0.2.0 

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

GetDatasetOutput 是 get_dataset 工具返回给模型的结果。

Path 是数据集工作目录的绝对路径（utils.GetDatasetDir），模型可直接在该目录下 读取 / 写入数据集文件。

type GetProjectDatabasePathInput added in v0.2.0 

type GetProjectDatabasePathInput struct{}

GetProjectDatabasePathInput 是 get_project_database_path 工具的入参。

固定使用当前激活项目，不接受模型传入 ID，避免读到别的项目的数据库目录。

type GetProjectDatabasePathOutput added in v0.2.0 

type GetProjectDatabasePathOutput struct {
	ProjectID   int64  `json:"project_id,string"`
	DatasetID   int64  `json:"dataset_id,string"`
	DatasetKey  string `json:"dataset_key"`
	DatasetName string `json:"dataset_name"`
	Path        string `json:"path"`
	// Created 表示本次调用是否新建了 DATABASES 数据集。
	Created bool   `json:"created"`
	Message string `json:"message,omitempty"`
	Error   string `json:"error,omitempty"`
}

GetProjectDatabasePathOutput 是 get_project_database_path 工具返回给模型的结果。

Path 是数据集工作目录的绝对路径（utils.GetDatasetDir），模型可直接在该目录下 读取 / 写入参考数据库文件（如 reference genome、索引、注释库）。

type GetReportContextInput added in v0.2.0 

type GetReportContextInput struct {
	ReportID string `json:"report_id"` // 项目报告主键 ID（支持 "@report:<id>" 形式，字符串以保精度）
}

GetReportContextInput 是 get_report_context 工具的入参。

ReportID 对应用户消息里的 @report:<id> 引用（如 "@report:2109711590457610240"）， 它是项目报告主键 ID（t_project_report.id），必填：模型必须显式给出要撰写的报告， 不再从系统提示词注入的 project_report_items 变量回退。

type GetScriptInput added in v0.2.0 

type GetScriptInput struct {
	ScriptID string `json:"script_id"` // 脚本主键 ID（必填，字符串以保精度）
}

GetScriptInput 是 get_script 工具的入参。

ScriptID 为必填：模型必须显式给出要查看的脚本 ID，不再从运行时上下文回退。 项目归属取自执行事实（tool.ProjectIDFrom），脚本必须属于当前激活项目。

type GetScriptOutput added in v0.2.0 

type GetScriptOutput struct {
	ScriptID int64 `json:"script_id,string"`
	// ContainerTemplateID 是脚本绑定的容器模板 ID（go_container_template_definition 主键，
	// 即对外 ContainerTemplate.ID）；0 表示脚本尚未绑定容器模板。
	ContainerTemplateID int64  `json:"container_template_id,string"`
	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"`
	Error               string `json:"error,omitempty"`
}

GetScriptOutput 是 get_script 工具返回给模型的结果。

ScriptFilePath / IOSchemaPath 由 utils.GetScriptFile / utils.WorkflowIOSchemaPath 推导， 模型可直接按这两个路径读写脚本主文件与 io_schema.json。

type GetWeatherInput 

type GetWeatherInput struct {
	City string `json:"city"` // 城市名（必填）
	Unit string `json:"unit"` // 温度单位：celsius / fahrenheit，默认 celsius
}

GetWeatherInput 是 get_weather 工具的入参。

type GetWeatherOutput 

type GetWeatherOutput struct {
	City        string  `json:"city"`
	Temperature float64 `json:"temperature"`
	Unit        string  `json:"unit"`
	Condition   string  `json:"condition"`
	Humidity    int     `json:"humidity"`
}

GetWeatherOutput 是 get_weather 工具的返回。

type ListContainerTemplatesInput added in v0.2.0 

type ListContainerTemplatesInput struct{}

ListContainerTemplatesInput 是 list_container_templates 工具的入参。

容器模板是全局资产（不属于某个项目），因此不需要任何参数；模型直接调用即可。

type ListContainerTemplatesOutput added in v0.2.0 

type ListContainerTemplatesOutput struct {
	Total     int                     `json:"total"`
	Templates []ContainerTemplateItem `json:"container_templates"`
	Message   string                  `json:"message,omitempty"`
	Error     string                  `json:"error,omitempty"`
}

ListContainerTemplatesOutput 是 list_container_templates 工具返回给模型的结果。

type ListProjectScriptsInput added in v0.2.0 

type ListProjectScriptsInput struct{}

ListProjectScriptsInput 是 list_project_scripts 工具的入参。

ProjectID 不由模型提供：它取自执行事实（tool.ProjectIDFrom，当前用户激活项目）， 避免模型去查别的项目的脚本。

type ListProjectScriptsOutput added in v0.2.0 

type ListProjectScriptsOutput struct {
	ProjectID int64               `json:"project_id,string"`
	Total     int                 `json:"total"`
	Scripts   []ProjectScriptItem `json:"scripts"`
	Message   string              `json:"message,omitempty"`
	Error     string              `json:"error,omitempty"`
}

ListProjectScriptsOutput 是 list_project_scripts 工具返回给模型的结果。

type ProjectScriptItem added in v0.2.0 

type ProjectScriptItem 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"`
	IOSchemaPath   string `json:"io_schema_path"`
}

ProjectScriptItem 是单个脚本的摘要（工具回传给模型的字段）。

ScriptFilePath / IOSchemaPath 由 utils.GetScriptFile / utils.WorkflowIOSchemaPath 推导， 模型可直接按这两个路径读写脚本主文件与 io_schema.json。

type ReadFileByIDInput added in v0.2.0 

type ReadFileByIDInput struct {
	FileID string `json:"file_id"` // 文件 ID（go_file 主键，字符串以保精度）
}

ReadFileByIDInput 是 read_file_by_id 工具的入参。

FileID 对应用户输入里的 @file:<id> 引用（如 "@file:2109711590457610240"），它是 go_file 主键 ID，等价于一条文件路径。

type ReadFileByIDOutput added in v0.2.0 

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

ReadFileByIDOutput 是 read_file_by_id 工具返回给模型的结果。

无论格式如何都会返回 FilePath；对 tsv / csv / xlsx（全部 sheet）额外返回每个 sheet 的列名（Columns）与前若干行预览数据（Rows）。

type ReadFileSheetTab added in v0.2.0 

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

ReadFileSheetTab 是单个 sheet / 数据表的内容预览。

type RunAnalysisNodeInput added in v0.2.0 

type RunAnalysisNodeInput struct {
	AnalysisNodeID string `json:"analysis_node_id"` // 分析节点 ID（必填，字符串以保精度）
	TimeoutSeconds int    `json:"timeout_seconds"`  // 等待完成的超时（秒），可选，默认 600
}

RunAnalysisNodeInput 是 run_analysis_node 工具的入参。

AnalysisNodeID 为必填：模型必须显式给出要运行的分析节点 ID，不再从运行时上下文回退。 工具不接受 request_param：脚本型节点使用节点上已保存的 request_param（由 build_analysis_node_params / create_script_analysis 写入），命令型节点直接运行 节点自身的 run.sh。

type RunAnalysisNodeOutput added in v0.2.0 

type RunAnalysisNodeOutput struct {
	AnalysisNodeID int64 `json:"analysis_node_id,string"`
	// ScriptID 是该节点绑定的脚本 ID，便于模型接着用 get_script 查看脚本或定位脚本文件。
	ScriptID int64 `json:"script_id,string"`

	Status       string `json:"status"`                  // 节点终态（success / failed / timeout ...）
	Success      bool   `json:"success"`                 // 是否为成功终态
	Log          string `json:"log,omitempty"`           // 节点执行日志（command.log 内容）
	LogPath      string `json:"log_path,omitempty"`      // 节点 command.log 绝对路径（Log 截断时可读全文）
	WorkspaceDir string `json:"workspace_dir,omitempty"` // 节点根目录
	CommandPath  string `json:"command_path,omitempty"`  // 本次执行的 run.sh 路径
	ParamsPath   string `json:"params_path,omitempty"`   // 本次运行的 params.json 路径
	// RequestParam 是本次运行实际生效的请求参数（键为 io_schema inputs 的 name），
	// 取自节点记录并在运行前按 io_schema 解析校验；命令型节点无参数（为空）。
	RequestParam map[string]any `json:"request_param,omitempty"`
	// ResolvedInputs 是按脚本 io_schema 解析后的结构化输入（已写入节点）。
	ResolvedInputs map[string]any `json:"resolved_inputs,omitempty"`
	// ParamsJSON 是本次运行实际使用的 params.json 正文，便于确认脚本拿到的参数。
	ParamsJSON string `json:"params_json,omitempty"`
	// ParamsUpdated 表示本次运行前是否按 io_schema 解析并更新了节点参数（命令型节点为 false）。
	ParamsUpdated bool `json:"params_updated,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"`
	Error          string   `json:"error,omitempty"` // 失败原因（如有）
}

RunAnalysisNodeOutput 是 run_analysis_node 工具返回给模型的结果。

除状态与日志外，还回传节点在磁盘上的关键路径与本次实际生效的参数：

  • WorkspaceDir：节点根目录（output / params.json / run.sh / command.log 均在其下）；
  • CommandPath：本次实际执行的 run.sh；
  • ParamsPath：本次运行读取的 params.json；
  • LogPath：本次执行的 command.log（Log 字段被截断时可据此读取完整日志）；
  • RequestParam / ParamsJSON：本次实际生效的请求参数与 params.json 正文。

type SaveMemoryInput added in v0.2.0 

type SaveMemoryInput struct {
	MemoryID   int64          `json:"memory_id,string,omitempty"`
	Kind       string         `json:"kind,omitempty"`
	Content    string         `json:"content"`
	Importance int            `json:"importance,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

SaveMemoryInput 是 save_memory 工具的入参。

用户归属（user_id）不在入参里：它由 RuntimeContext 提供，避免模型把记忆写到别的用户 名下。MemoryID 为 0 表示新建（主键由持久化层 BeforeCreate 分配），> 0 表示更新既有记忆 （例如补充 / 纠正同一条注意事项）。

type SaveMemoryOutput added in v0.2.0 

type SaveMemoryOutput struct {
	MemoryID   int64  `json:"memory_id,string,omitempty"`
	Kind       string `json:"kind,omitempty"`
	Importance int    `json:"importance,omitempty"`
	Created    bool   `json:"created"`
	Message    string `json:"message,omitempty"`
	Error      string `json:"error,omitempty"`
}

SaveMemoryOutput 是 save_memory 工具返回给模型的结果。

type TerminalExecInput added in v0.2.0 

type TerminalExecInput struct {
	ContainerTemplateID string `json:"container_template_id"` // 容器模板 ID（支持 "@container:<id>"）
	Command             string `json:"command"`               // 要在终端里执行的 shell 命令
	TimeoutSeconds      int    `json:"timeout_seconds"`       // 等待命令结束的超时（秒），可选，默认 300
	Wait                *bool  `json:"wait"`                  // 是否等待结束，默认 true
	CreateIfMissing     *bool  `json:"create_if_missing"`     // 终端未打开时是否自动创建，默认 true
	Persistent          *bool  `json:"persistent"`            // 是否创建/升级为持久终端，默认 false（持久终端会通知前端打开终端标签）
}

TerminalExecInput 是 terminal_exec 工具的入参。

ProjectID / UserID 不由模型提供：它们取自执行事实（tool.ProjectIDFrom / tool.UserIDFrom）。

type TerminalExecOutput added in v0.2.0 

type TerminalExecOutput struct {
	ContainerTemplateID int64   `json:"container_template_id,string"`
	SessionID           string  `json:"session_id,omitempty"`
	Accepted            bool    `json:"accepted"`
	Running             bool    `json:"running,omitempty"`
	Success             bool    `json:"success"`
	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"`
	Error               string  `json:"error,omitempty"`
}

TerminalExecOutput 是 terminal_exec 工具返回给模型的结果。

type UpdateAgentAnalysisInput added in v0.2.0 

type UpdateAgentAnalysisInput struct {
	AnalysisNodeID      string `json:"analysis_node_id"`      // 分析节点 ID（必填，字符串以保精度）
	NodeName            string `json:"node_name"`             // 新节点名称，留空表示不修改
	Command             string `json:"command"`               // 新 shell 命令（写入 run.sh），留空表示不修改
	ContainerTemplateID string `json:"container_template_id"` // 新容器模板 ID（字符串以保精度），留空表示不修改
	// Run 可选：更新后是否立即运行该节点。nil / true 表示运行（默认），false 表示只更新不运行。
	Run *bool `json:"run"`
	// TimeoutSeconds 是等待节点完成的超时（秒），可选；run=false 时忽略。
	TimeoutSeconds int `json:"timeout_seconds"`
}

UpdateAgentAnalysisInput 是 update_agent_analysis 工具的入参。

AnalysisNodeID 为必填：模型必须显式给出要更新的 command 节点 ID。 其余字段均可选：留空表示不修改对应字段；至少需要给出一个可更新字段。

type UpdateAgentAnalysisOutput added in v0.2.0 

type UpdateAgentAnalysisOutput struct {
	AnalysisNodeID      int64    `json:"analysis_node_id,string"`
	NodeName            string   `json:"node_name,omitempty"`
	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             []string `json:"changed,omitempty"`
	// Ran 表示本次是否提交了运行（run=false 时为 false，Status/Log 等运行期字段为空）。
	Ran    bool   `json:"ran"`
	Status string `json:"status,omitempty"` // 节点终态（success / failed / timeout ...）
	// Success 为 true 表示节点以成功终态结束。
	Success bool   `json:"success"`
	Log     string `json:"log,omitempty"`
	LogPath string `json:"log_path,omitempty"`
	Error   string `json:"error,omitempty"`
}

UpdateAgentAnalysisOutput 是 update_agent_analysis 工具返回给模型的结果。

type UpdateScriptAnalysisInput added in v0.2.0 

type UpdateScriptAnalysisInput struct {
	AnalysisNodeID string         `json:"analysis_node_id"` // 分析节点 ID（必填，字符串以保精度）
	NodeName       string         `json:"node_name"`        // 新节点名称，留空表示不修改
	RequestParam   map[string]any `json:"request_param"`    // 新请求参数，nil 表示不修改
	// Run 可选：更新后是否立即运行该节点。nil / true 表示运行（默认），false 表示只更新不运行。
	Run *bool `json:"run"`
	// TimeoutSeconds 是等待节点完成的超时（秒），可选；run=false 时忽略。
	TimeoutSeconds int `json:"timeout_seconds"`
}

UpdateScriptAnalysisInput 是 update_script_analysis 工具的入参。

AnalysisNodeID 为必填：模型必须显式给出要更新的脚本节点 ID。 其余字段均可选：留空表示不修改对应字段；至少需要给出一个可更新字段。

RequestParam 的键必须与脚本 io_schema.json 中的 name 一一对应。字段缺省时保持原值； 显式传入空对象（{}）表示清空节点已保存的参数。

type UpdateScriptAnalysisOutput added in v0.2.0 

type UpdateScriptAnalysisOutput struct {
	AnalysisNodeID int64          `json:"analysis_node_id,string"`
	NodeName       string         `json:"node_name,omitempty"`
	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       []string       `json:"warnings,omitempty"`
	Changed        []string       `json:"changed,omitempty"`
	// Ran 表示本次是否提交了运行（run=false 时为 false，Status/Log 等运行期字段为空）。
	Ran    bool   `json:"ran"`
	Status string `json:"status,omitempty"` // 节点终态（success / failed / timeout ...）
	// Success 为 true 表示节点以成功终态结束。
	Success bool   `json:"success"`
	Log     string `json:"log,omitempty"`
	LogPath string `json:"log_path,omitempty"`
	Error   string `json:"error,omitempty"`
}

UpdateScriptAnalysisOutput 是 update_script_analysis 工具返回给模型的结果。

type UpdateScriptInput added in v0.2.0 

type UpdateScriptInput struct {
	ScriptID    string `json:"script_id"`   // 脚本主键 ID（必填，字符串以保精度）
	Name        string `json:"name"`        // 新脚本名称，留空表示不修改
	Description string `json:"description"` // 新脚本描述，留空表示不修改
}

UpdateScriptInput 是 update_script 工具的入参。

只开放 name / description 两个元数据字段：脚本内容由模型直接写文件，io_schema 与 容器模板有各自的维护入口，不在本工具职责内。

ScriptID 为必填：模型必须显式给出要更新的脚本 ID，不再从运行时上下文回退。

type UpdateScriptOutput added in v0.2.0 

type UpdateScriptOutput struct {
	ScriptID       int64  `json:"script_id,string"`
	ScriptName     string `json:"script_name,omitempty"`
	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"`
	Error   string   `json:"error,omitempty"`
}

UpdateScriptOutput 是 update_script 工具返回给模型的结果。

除更新后的元数据外，回传脚本主文件与 io_schema.json 路径，便于模型继续读写脚本内容。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.