技能与 ToolBank API
AI 特工之所以能“干活”而不是只聊天，靠的是两层受控能力：技能（Skill） 与 ToolBank API。这两层都在 AI 配置窗口中透明可见、可开关、可测试——你随时能看清 AI 打算调用什么、参数是什么、上次执行结果如何。
一次 AI 调用的完整链路
要点：
- AI 不直接碰宿主：模型只能“请求”调用某个具名 API，真正执行由宿主完成并校验；
- 参数有模板：每个 API / 技能声明了参数（名称、类型、必填、默认值），AI 不能乱传；
- 全程可审计：技能页签能看到「渲染后 Prompt / 执行日志 / 结果 / 原始响应」，API 页签能看到「参数签名 / 调用示例 / 执行 API / 原始签名 / C# SDK 示例」。
一、技能（Skill）
技能是把“一段指令模板 / 一个平台能力”包装成可命名、可启用、可测试的单元。每个特工通过技能白名单决定自己能用哪些技能。
内置通用技能
| 技能 | 作用 |
|---|---|
| 会话整理 | 把一段多轮对话压缩成要点，用于换特工 / 交接 / 写纪要 |
| 当前选择识别 | 识别“你当前选中了什么”（节点图节点 / 变量 / 焦点控件），配合上下文提问 |
| 算子帮助 | 针对某个算子名解释参数定义、示例图或报错文本 |
| 通用翻译 | 翻成目标语言（默认中文） |
| 内容总结 | 按要点数 / 目标读者（研发 / 产品 / 客户）总结文本 |
| 代码审查 | 按语言审查代码片段（特工版代码审查的底层能力） |
| 需求讨论 | 把一段需求按依赖顺序拆解成子任务并给出优先级 |
每类“API · xxx”也会自动生成一条同名技能（见下节），所以技能列表里常能看到
API · 获取流程图快照这类条目。
二、ToolBank API：AI 能调用平台的哪些能力
配置窗口的 ToolBank API 页签展示全部可调用能力，按业务域分类。这里不逐条罗列（界面里可搜索、可展开），把能力面讲清楚：
| 能力域 | 用户视角的含义 | 典型例子 |
|---|---|---|
| 已接入 SK 上下文 | 工作空间 / 程序 / 选中内容摘要 | 获取工作空间摘要、程序与 Job 摘要、选中内容与鼠标区域 |
| 工具元信息 | 询问内置算子本身 | 查某个算子分类、输入输出、参数含义（喂给“算子帮助”） |
| Job 管理 | 程序与 Job 的结构查询 | 当前有哪些 Job、每个 Job 什么结构 |
| 算子编辑 | 程序内算子级查询 / 调整 | 定位算子、读写参数值 |
| 运行控制 | 执行类操作 | 运行 Job、单步、读各算子执行状态（成功 / 失败 / 跳过） |
| 变量读写 | 读取 / 写入运行变量 | 把检测结果数值、图像读到对话里分析 |
| 图像变量 | 图像变量的元数据读取 | 尺寸、通道、帧数等 |
| 用户视图 | 用户视图与流程图 | 抓流程图快照、新增 / 修改节点（需求分析师的看家本领） |
| 控件插件 | 视图控件级查询 | 当前打开的控件类型 / 状态 |
| 工作空间 | 工程级信息 | 工作空间路径、程序文件 |
| 诊断信息 | 排错辅助 | 读取最后一次报错、调用堆栈（JSON） |
| 对外运行期 SDK 子集 | 面向客户二次开发的子集 | 与 二次开发 SDK 同源的只读子集 |
这些能力是"只读为主，写入需明确指令"
- 查询 / 摘要类：AI 自己就能调用，用于“看懂你的工程”。
- 执行类（运行 Job、单步、读写变量）：界面里每个 API 都有「执行 API」按钮——你可以在配置窗口亲测每个 API，看到真实入参出参后再决定是否让 AI 使用。习惯上把这类能力留给明确授权的特工或你自己操作。
- 修改类（新增 / 修改流程图节点）：仅需求分析师类特工启用，且模型必须输出结构化指令（
flowchart-actions）才会落笔——保证“AI 改你的图”只发生在你说了“加 / 改”之后。
三、为什么说它是安全的：四道闸
- 白名单：每个特工的技能列表即闸门一；默认只开与职责匹配的技能。
- 参数模板：API 参数声明了必填与默认值，AI 填错会被宿主拒绝并给出原因。
- 执行审计：技能页签的「执行日志 / 原始响应」记录每次真实调用；配置窗口可以随时停用某个技能，等于一键撤销 AI 的某项能力。
- 可离线：用 Ollama 本地模型时，整个链路（含 ToolBank API 执行）不依赖任何外部服务。
四、动手试：一个技能 / 一个 API
试技能（不接触宿主）：技能页签选中“内容总结” → 参数区填测试值 → 看「渲染后 Prompt」（模型实际看到的提示词）→ 点执行 → 看「结果 / 原始响应」。
试 API（真实执行，谨慎使用）：ToolBank API 页签选中例如“获取程序与 Job 摘要” → 「调用示例」给出可运行的 JSON → 「执行 API」直接调用宿主并显示结果。试试诊断类的“读取最后一次报错”，能立刻复现上次失败原因。
提示：若某个 API 执行后想恢复现场，重新运行一次 Job 即可；修改类 API 建议先在备份的工作空间上试。