# 使用指南

适用于 **1.0.0 首个正式版本**。安装方法见[项目首页](../README.md)。

## 选择生成方式

开启「启用预测消息」后，可选择：

- **自动**：助手正常回复后生成一次预测，也可手动触发。
- **仅手动**：空输入框没有建议时，快速按两次 → 生成；选择后点击「保存更改」。

自动模式在助手正常回复结束、输入框为空且可编辑时直接请求预测，不设置额外触发等待或跨轮调用间隔。每轮最多生成一次；模型响应仍需时间，失败不会自动重发。输入文字、离开会话或关闭预测会取消未完成的请求。

旧聊天也可手动触发，无需先发一轮新消息。新建空会话尚无对话内容，不能生成预测。

已有建议时不会重新生成。填入或自行输入只暂时隐藏灰字；撤销至空草稿或清空文字后，可继续使用原建议。按 Esc 才会丢弃本轮建议。

## 查看预测状态

模型选择左侧的圆形图标表示当前状态：

| 显示 | 含义 |
| --- | --- |
| 灰色空心圆 | 暂无可用预测 |
| 转圈 | 正在生成 |
| 绿色空心圆 | 已有本轮预测 |

鼠标悬停可查看具体状态，包括失败和超时。图标只显示状态，点击不会生成或刷新预测。关闭预测或使用效果测试时，图标隐藏。

灰圈悬停显示「等待自动生成」时，表示会话仍在加载，或另一个预测／连接测试仍在进行；就绪后自动继续，不会叠加并发请求。

## 选择预测模型

「预测模型」默认跟随当前会话。也可选择宿主已配置的模型，或点击「自定义连接」接入其他服务商。选择只影响预测，不改变主聊天模型。

### 自定义连接

仅支持 **OpenAI 兼容 Chat Completions**，使用非流式响应。

| 设置项 | 填写方法 |
| --- | --- |
| API 地址 | 填基础地址，如 `https://api.example.com/v1`，不包含 `/chat/completions` |
| API Key | 填对应服务的密钥 |
| 模型名称 | 与服务商提供的模型 ID 一致 |
| 测试连接 | 用当前填写内容发送一次简短请求，可能产生费用 |
| 保存并使用 | 保存连接与参数，并将其用于预测 |

地址不能包含账号密码、查询参数或片段。请求地址会自动追加 `/chat/completions`，不会尝试 Responses 或 Messages 接口。

已存密钥只显示「已保存密钥」，需要时点击「更换」。测试连接不会自动保存或启用预测；修改参数后，原测试结果失效。保存按钮置灰表示没有可保存的有效修改；保存失败时内容会保留，可明确重试。

### 限制输出长度

- **关闭**：完全不发送 `max_tokens`，使用服务商默认上限。
- **开启**：填写大于等于 1 的整数。插件不设固定最大值，实际范围由服务商决定。

数值过小可能导致生成失败，思考过程也可能消耗输出额度。关闭此项不代表服务商没有上限，也不会取消请求超时。

跟随会话或使用宿主模型时，最长输出在「更多设置」中调整；自定义模型使用自己的独立设置。

### 自定义参数

点击「添加参数」，逐行填写参数名、类型和值。参数作为请求体的顶层字段发送，不会自动转换厂商名称或参数含义。

| 类型 | 值示例 | 实际发送 |
| --- | --- | --- |
| 文本 | `low` | 字符串 `"low"` |
| 数字 | `0` | 数字 `0` |
| 布尔 | `false` | 布尔值 `false` |
| JSON | `{"type":"disabled"}` | JSON 对象 |

例如，服务商文档要求 `reasoning_effort: "low"` 时，参数名填 `reasoning_effort`，类型选「文本」，值填 `low`。这组参数已在 GLM-5.3-Flash 的一次真实预测中通过；其他模型是否支持仍以其文档为准。

JSON 用于嵌套对象或数组，点号不会自动变成嵌套路径。文档中 Python SDK 的 `extra_body` 是 SDK 写法，请将里面的实际参数分别填写。

表单会阻止空参数名、重复名称、非法数字、无效 JSON，以及覆盖模型、消息、流式、工具或认证字段。必须通过上方开关设置 `max_tokens`；需要 `max_completion_tokens` 的模型可关闭该开关，再将替代字段作为数字参数填写，两者不能同时启用。

各厂商、型号支持的参数可能不同。不要将不同服务商的示例全部加到同一个模型上；测试和预测失败时，不会自动替你改参数或重发请求。

## 更多设置

「更多设置」可调整上下文范围、宿主模型的最长输出和可选输入／输出单价。开启总开关即时保存；其他设置按页面的保存按钮提交。

「效果测试」使用固定文字，不调用模型，开启后暂停真实预测。关闭效果测试后才会恢复真实预测。

同一台 Harness 服务的客户端共享设置。其他窗口已保存新配置时，当前编辑可能提示冲突；草稿会保留，可读取最新设置后重新调整。

## Token 和费用

调用预测和测试连接会产生模型用量，费用由服务商收取。插件没有每日次数、Token 或金额上限，不需要预测时可以关闭，或使用「仅手动」。

「查看明细」展示今日与累计用量。统计只包含本插件，不包含主聊天；日期按 UTC+8 归档。失败或取消后若没有完整用量，记为「待核对」，不能理解为免费。

单价由你选填，金额仅作估算；未填写完整单价时不会把未知费用记成零。插件不内置官方价目表，实际账单以服务商为准。

已有建议的接受、撤销、清空恢复、缓存读取和刷新恢复，不额外调用预测模型。

## 对话内容与隐私

默认最多读取近期 8 条用户／助手文字，每条最多保留末尾 500 个字符，整个对话输入约 4000 字符。系统指令、工具日志、注入文件、附件和思考过程不进入预测上下文。

上述近期对话文字会发送至你选用的模型服务。自定义模型的 API Key 通过宿主公开凭据服务保存，普通插件设置只保留引用，界面不回显已存值。

## 常见问题

**按两次 → 没反应。** 先确认已启用真实预测、输入框为空，并且会话有正常完成的回复。附件、引用、排队消息、输入法组合或会话正在运行时不会触发。已有建议时两次 → 会保留原建议。

**一直转圈，最后失败。** 请求超过 12 秒会超时，不自动重试。悬停状态图标查看原因，检查服务或参数后，可在空输入框手动重试。

**模型返回了内容却没有灰字。** 插件只显示完整、简短的单行预测。被截断、返回工具调用、没有有效正文或不符合预测要求的结果不会显示。思考模型可尝试调高或关闭输出上限，并按服务商文档设置思考参数。

**连接测试成功，实际预测失败。** 预测使用真实聊天上下文，比连接测试复杂；检查输出上限、思考消耗、服务商模型权限及响应时间。

**Ctrl+Z 没撤销。** 在刚执行本地命令的会话中，首次填入可能无法单步撤销，可选中后删除。一般会话中的接受、撤销与缓存恢复已验证。

**断线或换窗口后没有旧建议。** 断线时会隐藏预测，恢复连接或返回输入框时读取缓存；不会因此重新调用模型。同源窗口支持建议丢弃同步，跨设备不承诺实时同步。