AI 对话与模型

一次 AI 回复通常由四层配置共同决定：Bot 是否启用 AI、当前聊天选择的 Provider 和模型、系统提示词，以及这次请求允许使用的工具。面板负责保存和审计配置，Telegram 命令适合快速查看和切换。

查找和分享某个设置

进入 Bot 的 AI 设置，在顶部搜索框输入设置名称，例如“超时”、OCR 或 MCP。搜索覆盖回复行为、记忆、工具、权限与群组中的折叠设置；选择结果会切换到对应分类、展开并定位到该设置。也可以用上下方向键选择结果、Enter 打开，Escape 关闭搜索结果。

打开设置后，地址会包含对应的分类和设置位置。复制当前页面地址，再次打开时可直接回到该设置；浏览器前进、后退也会恢复位置。分享链接不会授予接收者访问权限，也不会包含尚未保存的配置内容。

折叠行在手机上也会保留已有的状态摘要，便于检查开关、模式或数量。搜索和分类切换只负责查找设置；修改配置后仍需按页面提示保存或应用。

保存设置与保留草稿

页面顶部会持续显示已保存、未保存、正在保存或操作失败，手机上也能看到。没有更改时 保存 不可用；修改后可保存，保存过程中会暂时禁用编辑和重复提交。若按钮不可用，旁边会说明原因。

当前回复选择 单独使用 应用选择：它决定后续回复实际使用的服务商、模型和小程序展示方式。试选后不想应用，可以点击 撤销选择草稿，恢复最近读取到的已保存选择。此操作不撤销其他设置草稿。需要先应用或撤销当前选择，才能保存服务商目录等配置。

搜索设置、切换分类和展开项目会保留当前草稿。带着未保存更改跳转到其他管理页面时，会出现离开确认：留下并继续编辑 保留输入，不保存并离开 放弃草稿并跳转。主动退出登录前也会先确认；会话失效时仍需重新登录。刷新或关闭标签页时由浏览器提供离开提示。草稿仅保留在当前页面，不会自动保存，也不会包含在分享链接中。

普通保存失败会保留草稿并显示错误，可以修正后重试。若提示配置已经保存、但 Bot 未能应用，请按页面提示重试应用；若提示其他页面已修改配置，请重新载入并核对最新值后再操作。

Provider 和模型

Provider 是模型服务的连接配置；同一个 Provider 可以暴露多个模型。面板会根据当前 Provider 返回可用模型，模型列表和能力标签取决于外部服务以及管理员配置。

新发现模型的能力标签会参考 models.dev 目录；目录中同名模型的能力不一致或没有匹配项时，回退到名称推断。标签是配置参考，不代表已对当前服务商执行能力测试。目录刷新失败或返回无效、空数据时保留上次有效缓存；HTTP 错误响应的未读取正文会被释放，不影响后续刷新；已有模型的手动能力配置不会被覆盖。

每次进入 服务商与模型 页面时，面板会自动获取所有已配置服务商的模型列表，并将新模型加入目录，无需再勾选导入。已有模型的名称、能力标签、参数和默认选择会保留；单个服务商获取失败不会清空已有列表，也不影响其他服务商更新。未配置模型发现路径或 API Key 的服务商仍可手动添加模型 ID。

手动移除模型后，该服务商会记录排除的模型 ID，后续自动获取或点击 刷新模型 都不会把它加回来。需要恢复时，在 添加模型 ID 中重新添加即可；改名也会排除原 ID。模型目录和排除记录沿用页面的 保存 流程，保存后才会用于 Bot，并在下次打开时保留。旧版本没有记录删除历史，升级后若曾删除的模型再次出现，需要重新移除并保存一次。

在 Telegram 中：

/provider
/provider 2
/provider reset
/model
/model 2
/model reset

没有参数时只查看当前值和可用列表。编号从 1 开始；也可以使用模型 ID 或 Provider 名称。切换会写入当前聊天的覆盖值，reset 返回 Bot 或工作区默认值。不同实例可能把这些配置限制为管理员，或者允许所有参与者在治理范围内切换。

系统提示词和回复行为

系统提示词定义 Bot 的角色、语气和额外约束。修改前先记录原值，保存后在测试私聊和测试群分别验证：同一句问题在不同聊天可能因历史、权限、模型或群配置而不同。

回复模式、富文本增强和 AI 开关是独立设置。/stop 会停用 AI 回复并中断当前调用，/resume 恢复；管理员也可以在面板中查看 Bot 生命周期状态。停用 Bot 或 AI 不会删除已有对话和日志。

群聊消息补充图片识别等内容时，会清除原内容的检索向量，并为更新后的内容重新生成；迟到的旧结果不会覆盖新内容。内容不变的重复保存保留已有向量，新向量生成失败也不会恢复过期向量。

工具能力

根据配置和上下文，AI 可能看到以下工具类别：

• 历史搜索、人物档案和长期记忆；
• 网页搜索或网页读取；
• Telegram 回复、反应、贴纸和媒体操作；
• 图片生成、RSS 阅读和群聊总结；
• MCP 服务器、艺术作品检索和 GitHub 操作。
• 管理员专用的运行状态、有效配置和请求链路诊断。

工具并不是“模型想用就能用”。运行时会按聊天、用户、Bot、管理员身份和功能开关组装可见工具；具有副作用的工具还会经过一次性保护、用量治理或确认流程。

检索默认通过 search 获取摘要，再按需读取引用。在 AI 设置 → 工具 → 统一检索 可切回旧工具；支持的来源、分页限制和权限说明见统一检索指南。

对话选择按钮

AI 发出的选择按钮只接受原聊天、原消息上的有效选项。异常或过期回调不会推进对话；异常回调也不会消耗仍有效的选择。若选择指定了回答者，其他成员不能代答。

同一轮工具调用前后的正文都会保留，避免剧情只剩选择提示或收尾句。选择按钮由工具即时发送；分段回复的正文在本轮生成完成后投递。点击后若当前聊天仍有任务，续写会排队，日志中的 AI continuation queued 表示等待执行，并不表示回复已经发送。

若某一步正文已通过 multi_message 完整送达，收尾时只补发尚未送达的步骤。只确认部分内容送达时仍保留该步完整正文，避免去重误删尚未发送的内容。

步骤数与等待时间

在 AI 设置 → 记忆 → 对话记忆 调整主 AI 的最大步骤数，当前默认 128 步；工具 → Agent 工具 调整子 Agent 步骤数，当前默认 64 步。步骤是模型与工具交替执行的一轮，可以包含多个工具调用。达到主 AI 的最后一步时，Bot 会保留这一轮用于生成正文。升级后的默认值不会覆盖已经保存的配置；旧 Bot 若仍是 10 步或 15 步，需要在面板修改并保存。

回复行为 → 超时设置 控制单轮总等待、单次模型调用、搜索、网页获取、图片生成和子 Agent 等时间。单轮 AI 回复默认最多等待 1 小时；单步计时在工具执行期间暂停，单轮总计时仍继续。插件工具和检索、MCP 工具单次调用各最多等待 10 分钟，仍受当前调用的取消信号和单轮总时限约束。MCP 超时或取消会停止本地等待并向上游传递取消请求。

管理员确认后的 ASR 转录 在独立后台运行，使用媒体任务自己的时限。PixAI 后台任务使用单独的任务轮询超时设置。

成本和失败排查

模型调用、图片生成、总结和 JEV 观察都可能产生外部服务费用。使用面板中的 Usage、日志和治理页面查看次数、并发、冷却以及错误；不要仅根据“消息已发送”判断模型任务完全成功。

常见检查顺序：

1. Provider 是否连接成功，模型列表是否为空。
2. 当前聊天是否保存了过期的 Provider 或模型覆盖。
3. AI 是否被 /stop、Bot 生命周期或群组开关停用。
4. 是否命中了用量、并发或冷却限制。
5. 日志中的请求、工具和错误是否显示外部服务拒绝、超时或返回格式错误。

模型在流式生成期间上报错误时，Bot 会立即结束当前模型请求并保留原始错误，避免继续等待连接关闭或本轮超时。已完成的工具调用不会因这类错误自动重放。延长时限可以允许更长的正常处理，但服务商返回的生成错误仍需单独排查。

模型等待与超时

一次回复的总超时和每次模型调用的单步超时可在 AI 设置 → 回复行为 → 超时设置 中配置。模型请求使用这些超时和取消信号；持续等待模型推理或总结时，客户端不会再额外施加固定五分钟的 HTTP 响应空闲限制。/stop 和停止 Bot 仍会中断正在等待的模型请求。

外部服务或其代理也可能主动断开连接，延长本地超时无法改变外部服务的限制。日志中的 terminated 是底层连接结束的通用文案，需要继续查看 cause：UND_ERR_BODY_TIMEOUT、UND_ERR_HEADERS_TIMEOUT 和 UND_ERR_CONNECT_TIMEOUT 会归类为超时，UND_ERR_SOCKET 表示连接断开。超时失败不会自动重跑整轮工具调用；确认工具是否已经执行后，再决定是否重试。

缓存用量的含义

一次 AI 回复可能经过多次模型调用，例如先调用工具，再根据工具结果作答。新记录的输入、输出和总 token 按整轮累计；缓存读取和写入也按整轮统计。修复前的历史记录不会自动回填，多步调用的旧记录可能低估总用量，甚至出现缓存 token 命中率超过 100%。

• 缓存观察率：有完整缓存读取数据的回复数占全部用量记录的比例。
• 缓存 token 命中率：仅在已观测记录中，用缓存读取 token 除以输入 token。
• 缓存请求命中率：已观测记录中，缓存读取 token 大于零的回复比例。一次多步回复仍算一条记录。
• 未知与零：服务明确报告零，才表示已观测到未命中。没有上报、SDK 未保留字段，或任一步骤缺少指标时，该整轮指标保持未知。读取和写入分别判断；没有可用数据时显示 —。

OpenAI-compatible 服务可以通过标准 prompt_tokens_details.cached_tokens 上报缓存读取量，也支持 DeepSeek 的 prompt_cache_hit_tokens。未命中的输入 token 不等于缓存写入 token。部分非标准字段（例如嵌套的 cache_write_tokens）可能被当前 SDK 丢弃，不能据此认为写入量为零。

缓存指纹用于比较模型、静态提示词及工具定义，指纹相同并不能证明服务端命中。工具 schema 的 hash 会忽略对象键顺序，但这不保证实际请求的序列化字节相同。

验证真实缓存效果

真实模型请求会产生费用。准备验证时，先确定服务、模型、预算，以及该服务的缓存门槛和有效期；使用不含私人信息的专用测试聊天，不要直接拿生产群试验。

1. 固定 Provider、模型、静态提示词和工具集，先执行一次预热，再在有效期内重复对话，分别记录普通回复与工具多步回复。
2. 对照已有日志和用量记录中的 provider、模型、缓存指纹、输入 token、缓存读取／写入量及未知记录数量。
3. 分开报告观察率、请求命中率和 token 命中率，并注明是否排除预热请求、样本数量和测试时间窗口；不能把某项比例直接称为“静态前缀命中率”。
4. 只有真实服务返回的缓存数据才能证明命中。要判断费用收益，还需对照服务实际计费；本地模拟响应只验证采集链路，不证明命中率、延迟或节省金额。

诊断时保护隐私

诊断日志可以帮助定位关联请求、工具调用和失败原因，但可能包含有界的消息正文或工具输入输出。分享日志前应先移除用户 ID、消息正文、URL 中的密钥、Cookie、Authorization 头和任何 Token。详见隐私、历史与记忆。

分析已缓存的人物头像

启用人物档案记忆后，AI 可在明确请求下通过 get_profile_avatar 读取当前 Bot 缓存的头像，并把图片加入本次视觉上下文。需要回复模型支持图像输入；只支持文本的模型无法保证视觉分析。隐私权限、缓存状态与角色保存步骤见角色与提示词资产库。

工具步骤与空回复

工具调用与最后的文字回答共用本轮步骤预算。最后一步保留给文字回答，以便 Bot 根据已经取得的字幕或检索结果输出总结。读取插件字幕属于只读操作；模型没有生成正文时，会明确显示“AI 未生成回复内容”，不会把字幕读取当作已经完成总结。实际修改或发送工具成功后，模型仍没有正文时，可以显示操作完成回执。