Visindigo::Agent::Function Class
class Visindigo::Agent::Function可供模型调用的工具接口. 详情...
| 头文件： | #include <Agent/Function.h> |
| 自以下版本： | Visindigo 0.17.0 |
公开成员函数
(自 Visindigo 0.17.0 引入) virtual | ~Function() |
(自 Visindigo 0.17.0 引入) virtual QString | getDescription() const = 0 |
(自 Visindigo 0.17.0 引入) virtual QString | getId() const = 0 |
(自 Visindigo 0.17.0 引入) virtual QString | getName() const = 0 |
(自 Visindigo 0.17.0 引入) virtual Visindigo::Utility::JsonConfig | getParameterSchema() const = 0 |
(自 Visindigo 0.17.0 引入) virtual Visindigo::Utility::JsonConfig | invoke(const Visindigo::Utility::JsonConfig &arguments) = 0 |
(自 Visindigo 0.17.0 引入) virtual void | invokeAsync(const Visindigo::Utility::JsonConfig &arguments, std::function<void (const Visindigo::Utility::JsonConfig &)> callback) |
详细说明
继承本类并实现五个纯虚函数，即可把一个本地能力暴露给模型。Visindigo 会把 getParameterSchema() 转换成请求里的工具声明，模型决定调用后 再把参数交回 invoke()。
getId() 同时充当"发给模型的工具名"，因此它必须满足模型对函数名的 字符集限制（字母、数字、下划线、连字符，长度不超过 64），并且不含空格 与点号。用人类可读的中文名做 id 会导致请求被服务端直接拒绝，所以 getName() 与 getId() 是两个独立的概念：前者用于展示，后者用于协议。
所有函数对象的所有权归 Center 或 Dialog，二者按 id 索引，因此一份 对话不会因为函数被复制而重复执行。实现者不需要自己做单例或缓存。
成员函数文档
[virtual noexcept, since Visindigo 0.17.0] Function::~Function()
虚析构，保证通过基类指针释放子类对象是安全的。
这个function 从 Visindigo 0.17.0 开始支持。
[pure virtual, since Visindigo 0.17.0] QString Function::getDescription() const
返回工具用途说明。
说明是模型判断"该不该调用这个工具"的唯一依据，因此应当写清楚它做什么、 什么时候用、以及什么情况下不要用。一句话的工具几乎不会被正确调用。
这个function 从 Visindigo 0.17.0 开始支持。
[pure virtual, since Visindigo 0.17.0] QString Function::getId() const
返回工具名，必须匹配 ^[a-zA-Z0-9_-]{1,64}$。
这个 id 会出现在模型的输出里，也会出现在随后的工具结果消息里，因此它在 一次对话内必须保持稳定——同名工具在不同轮次指向不同实现，会让模型的行为 变得不可预测。
这个function 从 Visindigo 0.17.0 开始支持。
[pure virtual, since Visindigo 0.17.0] QString Function::getName() const
返回人类可读的名称，用于界面展示。
这个function 从 Visindigo 0.17.0 开始支持。
[pure virtual, since Visindigo 0.17.0] Visindigo::Utility::JsonConfig Function::getParameterSchema() const
返回参数的 JSON Schema 对象。
通常是 "type": "object", "properties": {...}, "required": [...]。 参数名应当简洁且自解释：模型的调用正确率很大程度上取决于字段名与字段描述 是否写得明白，而不是取决于参数有多少个。
这个function 从 Visindigo 0.17.0 开始支持。
[pure virtual, since Visindigo 0.17.0] Visindigo::Utility::JsonConfig Function::invoke(const Visindigo::Utility::JsonConfig &arguments)
同步执行工具，arguments 是模型给出的参数对象。
返回值会被序列化成紧凑 JSON 作为工具结果文本交回模型，因此需要交互的 自由文本应当包成一个对象，例如只放一个键。执行失败时也应当正常返回一段 描述失败原因的结果，而不是抛出异常：模型看到"文件不存在"通常会换个路径 重试，而一个被异常打断的对话只能从头再来。
这个function 从 Visindigo 0.17.0 开始支持。
[virtual, since Visindigo 0.17.0] void Function::invokeAsync(const Visindigo::Utility::JsonConfig &arguments, std::function<void (const Visindigo::Utility::JsonConfig &)> callback)
异步执行工具。默认实现直接调用 invoke() 并立即回调，等价于同步执行。
Note: 默认实现是在调用线程上完成的，因此回调会在 invokeAsync() 返回 之前就被触发。需要在回调里发起新请求的实现必须覆写本函数把工作交给 事件循环，否则会在同一个调用栈里层层嵌套。
arguments 模型给出的参数对象。 callback 执行完成后调用的回调。
这个function 从 Visindigo 0.17.0 开始支持。