从第一个缺少成功变量的阶段开始排查。下载可打开只证明安装器能运行；连接测试通过只证明已配置服务响应；两者都不能证明宿主编辑器能够捕获并替换文本。
找到失败阶段
| 阶段 | 成功变量 | 缺少时 |
|---|---|---|
| 1. 键盘或输入源 | UnimeType 出现在系统键盘选择器中，并能输入普通字符 | 重查平台设置与权限 |
| 2. 动作触发 | 选择 Convert、Polish 或 Explain 后出现进行中状态或结果 | 重查当前输入源、快捷键、完全访问与 AI 处理同意 |
| 3. AI 服务 | 测试连接成功，且所选路径具备账号访问或完整服务商字段 | 重查登录、积分、Base URL、Model ID、API Key 与网络 |
| 4. 文本捕获 | 预期的选区、句子或段落成为动作目标 | 显式选中文字后重试 |
| 5. 校验与写回 | Convert 或 Polish 只改变预期宿主范围 | 请求期间不要改原文；显式选择；查看可见状态 |
成功写回后，变更文字留在当前应用，不会保留单独的成功标签。
1. 找不到键盘或输入源
iPhone 与 iPad
打开 设置 › 通用 › 键盘 › 键盘，确认列表中有 UnimeType。在输入框长按地球键，选中 UnimeType。若键盘出现但 AI 动作不启动，请确认 允许完全访问 与 AI 处理同意。见 iPhone 与 iPad 设置。
Mac
确认 UnimeType 已安装到「应用程序」、出现在 macOS 键盘设置中，并且是当前输入源。Caps Lock 转换只在 UnimeType 已选中且相应快捷键已启用时工作。
Windows
确认已签名安装器完成安装，且 UnimeType 出现在 Windows 输入语言菜单中。测试 Caps Lock 或 Alt + Enter 前先选中它。若普通输入可用，但特定编辑器无法替换，请继续查文本捕获与写回。
Android
打开 UnimeType 应用，选择 启用键盘，在 Android 输入法设置中启用，再用 选择键盘 选中。Android 不使用 iOS 的完全访问权限。
2. 动作不启动
- 排查桌面快捷键前，先点一次键盘上的动作。成功变量是出现进行中状态或 Explain 面板。
- 若点按可用但快捷键无效，重新启用该快捷键，并确认 UnimeType 是当前输入源。
- 若所有 AI 动作都不启动，请授予 AI 处理同意；iOS 还要确认 允许完全访问。
- 等上一个动作完成。已有动作进行中时，UnimeType 不会启动第二个。
3. AI 服务或模型失败
打开设置，对所选路径运行 测试连接。
- UnimeType 余额： 刷新登录与余额状态。该路径需要具备可用服务访问的账号。
- 自带 API Key： 重新复制服务商、Base URL、准确 Model ID 与 API Key。服务商必须允许该凭据使用所选模型。
- 模型列表为空或失败，表示带鉴权的
GET /models没有返回可用列表。你仍可手动填写已知 Model ID 后测试。 - 连接测试通过，不代表 Convert 一定改变每条输入；模型可能返回相同文本。
见 AI 服务、模型与积分。
4. 文本捕获或写回失败
未找到可转换输入
把光标放在新输入文字末尾，或显式选中准确目标。显式选区优先于自动句子与段落捕获。
文字被插入而不是替换
确认原文仍在，显式选中后重试。不同编辑器暴露不同替换 API，选区是最可移植的目标。macOS 特定宿主行为见 Mac 应用兼容性。
新追加的词没有被包含
Convert 可能只处理上一次成功转换后新加的文字。需要再次处理整段时，请选中完整段落。见文本范围策略。
写回前文字已更改
请求进行中不要编辑目标。对当前文字重新运行。捕获原文不再匹配时，UnimeType 会拒绝覆盖该范围。
5. 输入语言或 Language Pack 结果不对
Convert 选错语言
关闭不用的转换语言，把目标语言设为 首选语言，显式选中后重试。英文始终保留，最多启用 3 种非英文语言。见输入语言。
Language Pack 没有效果
确认 Pack 已下载且已启用，再检查其能力是否适用于当前动作。本地中文快捷短语必须是单独使用、完整且只含小写 a–z 的输入，同时启用中文。当前不提供知识检索与文档索引。见 Language Packs。
消息与下一步
| 消息或症状 | 含义 | 下一步 |
|---|---|---|
| 文本未改变 | 模型返回了相同且结构合法的文字 | 选择更清楚的目标、补充上下文或换模型 |
| 未找到可转换输入 | 找不到选区或新输入目标 | 把光标放在文字后，或显式选中 |
| 上一个动作仍在处理 | 另一个动作尚未完成 | 完成前不要启动新动作 |
| 写回前文本已更改 | 请求期间捕获原文被编辑 | 对当前文字重新运行 |
| 此编辑器需要文本选区 | 宿主无法从仅光标目标完成替换 | 选中准确文字后重试 |
| 无法替换文本 | 宿主未接受已验证写回 | 确认原文、选中后重试 |
| 网络不可用 | 请求无法到达所选服务或超时 | 检查连接后重试 |
| AI 服务错误 | 服务响应不可用，或本地校验拒绝 | 重新测试服务、模型与输入 |
| 请先完成 AI 服务设置 | 缺少必填服务字段或托管访问状态 | 在设置中完成所选路径 |
| 动作已取消 | 未允许 AI 文本处理 | 使用 AI 动作前启用处理同意 |
文本未改变、网络不可用 与 AI 服务错误 是不同结果。未改变表示路径返回了可用但相同的文字；网络不可用表示无法到达路径；AI 服务错误表示响应未能完成产品的服务或校验约定。
报告可复现问题
请提供以下可观察对象，不要包含私人输入或凭据：
- 平台与 UnimeType 版本
- 宿主应用名称与字段类型
- 使用的动作，以及是否显式选择文字
- 准确的可见状态消息
- 普通输入、测试连接、以及在纯文本编辑器运行同一动作是否分别成功
- 能复现问题的最短非敏感示例
内部状态标识与校验器案例单独列在高级技术参考。它们是诊断标签，不是用户操作说明，也不能证明另一平台存在相同失败。