Visindigo::Agent::Message Class
class Visindigo::Agent::Message对话中的一条消息. 详情...
| 头文件： | #include <Agent/Dialog.h> |
| 自以下版本： | Visindigo 0.17.0 |
公开类型
(自 Visindigo 0.17.0 引入) enum class | Role { System, User, Assistant, Tool, Prompt } |
公开成员函数
(自 Visindigo 0.17.0 引入) | Message() |
(自 Visindigo 0.17.0 引入) | Message(Visindigo::Agent::Message::Role role, const QString &content) |
(自 Visindigo 0.17.0 引入) | ~Message() |
(自 Visindigo 0.17.0 引入) bool | fromJson(const Visindigo::Utility::JsonConfig &json) |
(自 Visindigo 0.17.0 引入) QString | getContent() const |
(自 Visindigo 0.17.0 引入) QString | getName() const |
(自 Visindigo 0.17.0 引入) QString | getReasoning() const |
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Message::Role | getRole() const |
(自 Visindigo 0.17.0 引入) QString | getToolCallID() const |
(自 Visindigo 0.17.0 引入) QString | getToolCalls() const |
(自 Visindigo 0.17.0 引入) bool | isEmpty() const |
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Message & | setContent(const QString &content) |
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Message & | setName(const QString &name) |
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Message & | setReasoning(const QString &reasoning) |
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Message & | setRole(Visindigo::Agent::Message::Role role) |
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Message & | setToolCallID(const QString &id) |
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Message & | setToolCalls(const QString &rawJsonArray) |
(自 Visindigo 0.17.0 引入) Visindigo::Utility::JsonConfig | toJson() const |
详细说明
Message 是纯值类型，可以自由拷贝与序列化。它同时承担两种用途：一是请求体 里的 messages 数组元素，二是本地会话记录。两者字段基本重合，唯一的 差别是 getToolCalls()——它保存的是原始 JSON 数组文本，只在请求体重 逐字回传，本地展示时不使用。
成员类型文档
[since Visindigo 0.17.0] enum class Message::Role
消息在对话中扮演的角色。
| Constant | Value | Description |
|---|---|---|
Visindigo::Agent::Message::Role::System | 0 | 系统提示。通常由 Dialog::run() 自动生成，不需要手工添加。 |
Visindigo::Agent::Message::Role::User | 1 | 用户输入。 |
Visindigo::Agent::Message::Role::Assistant | 2 | 模型输出。 |
Visindigo::Agent::Message::Role::Tool | 3 | 工具执行结果。必须同时设置 Message::setToolCallID()， 否则服务端无法把它对应回某次调用。 |
Visindigo::Agent::Message::Role::Prompt | 4 | 由 Prompt::render() 生成的模板消息。 |
Note: Role::Prompt 只在本地区分"用户手打的"与"模板生成的"，发往服务端时 与 Role::User 同为 user 角色。
这个enum 从 Visindigo 0.17.0 开始支持。
成员函数文档
[since Visindigo 0.17.0] Message::Message()
构造一条空消息，角色默认为 Role::User。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Message::Message(Visindigo::Agent::Message::Role role, const QString &content)
以角色与内容构造消息。
role 消息角色。 content 消息正文。
这个function 从 Visindigo 0.17.0 开始支持。
[noexcept, since Visindigo 0.17.0] Message::~Message()
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] bool Message::fromJson(const Visindigo::Utility::JsonConfig &json)
从 JSON 对象恢复。
无法识别的角色字符串会退回 Role::User，因为把一条消息当作用户输入 与模型继续对话，比丢掉它造成的破坏更小。
json 已解析的 JSON 对象。
return 是否读到了可识别的角色。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] QString Message::getContent() const
返回正文。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] QString Message::getName() const
返回发送者名称。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] QString Message::getReasoning() const
返回本条助手消息的思考内容；非推理模型或未记录时为空串。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Agent::Message::Role Message::getRole() const
返回角色。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] QString Message::getToolCallID() const
返回本条消息对应的工具调用标识。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] QString Message::getToolCalls() const
返回助手消息请求的工具调用，形态为原始 JSON 数组文本。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] bool Message::isEmpty() const
判断消息是否既没有正文也没有工具调用。
Note: 一条只有工具调用的助手消息不算空：它的正文可能为空，但携带的调用 信息才是重点，把它当作空消息丢掉会让下一轮的请求缺一条必要的前置消息。
return 消息是否既没有正文也没有工具调用。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Agent::Message &Message::setContent(const QString &content)
设置正文。
content 新的正文文本。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Agent::Message &Message::setName(const QString &name)
设置发送者名称。
Note: 这个字段在标准协议里是可选的，多数服务端会忽略它。它在本模块中的 实际用途是记录模板消息来自哪个 Prompt，以及工具结果来自哪个工具。
name 发送者名称；模板消息可填模板名，工具结果可填工具名。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Agent::Message &Message::setReasoning(const QString &reasoning)
设置本条助手消息的思考内容。
推理模型会先输出一段思考再生出回答，这段思考被单独存下来，因为它属于这一次 回答本身：不看它，就无法理解模型当时为什么做出那个结论，事后重读对话时 只剩下一个看不出理由的结果。
Note: 它永远不会被发回服务端。思考是模型的中间产物，不是它已经说出口的话， 把上一轮的思考当作助手内容回传，会让模型以为自己已经给出过那个结论， 从而在下一轮里跳过论证直接引用它。
reasoning 本轮的思考内容。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Agent::Message &Message::setRole(Visindigo::Agent::Message::Role role)
设置角色。
role 新的角色。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Agent::Message &Message::setToolCallID(const QString &id)
设置本条消息对应的工具调用标识。仅对 Role::Tool 有意义。
id 必须与模型给出的调用标识完全一致，包括大小写。服务端按它把结果配回 具体的调用，配不上就会拒绝整条请求。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Agent::Message &Message::setToolCalls(const QString &rawJsonArray)
设置本条助手消息请求的工具调用，内容为原始 JSON 数组文本。
这里刻意不收结构化数据：字段只要原样回传就不会出错，一旦解析再重新拼装， 就得自己保证每个字段的形态与收到的完全一致，反而多出一处可能出错的地方。
Warning: 这段文本会被原样放进请求体。构造它的人应当确保它来自服务端响应， 而不是用户输入。
rawJsonArray 服务端给出的工具调用数组的原始 JSON 文本。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] Visindigo::Utility::JsonConfig Message::toJson() const
序列化为 JSON 对象，角色以字符串保存。
这个function 从 Visindigo 0.17.0 开始支持。