适用于 fn 0.4.4 / SDK 0.3.4，manifest 为 0.3。先按安装指南安装 fn；旧名称插件和旧应用数据不迁移。
为什么不能开始翻译
先看「设置 → 模型服务」是否有可用模型。新安装不包含模拟模型；ChatGPT 登录成功后仍需从账号目录添加模型。账号退出、授权失效或最后一个模型被删除时，插件会停用生成。
保存 API Key 不会自动验证额度。请求失败时检查服务商返回的错误、API 地址、模型 ID 和账号权限。
浏览器登录失败
优先选择现有记录并点击重试，不必反复创建账号。登录等待可以取消；切换应用页面不会中断登录。只完成身份授权而没有订阅使用权限时，不能推理。
登录回调在本机处理，不要分享带参数的回调链接或访问令牌。fn 使用文件存储，不请求钥匙串授权。
凭证文件错误
fn 使用独立数据目录中的 chatgpt-auth.json。首次需授权并添加模型，不读取或迁移旧应用登录。
出现凭证文件错误时，检查数据目录是否可读写、磁盘空间是否足够，以及文件是否为空或损坏；修复后重启应用。应用不会自动覆盖损坏文件。确认无法恢复时，可自行移走该凭证文件并重新登录；已有订阅模型需重新添加。该文件明文包含登录凭证，不要上传文件、备份或原始错误日志。
网络与代理
应用启动时优先读取显式 HTTP / HTTPS 代理环境变量，否则跟随 macOS 手动 HTTP / HTTPS 系统代理。更改代理后重新启动应用。当前不转换系统 PAC 或 SOCKS 配置。
如果服务商返回地区限制错误，检查该服务在当前网络和地区的可用性；这不等于模型配置格式有错。不要关闭 TLS 校验来处理连接问题。
插件安装失败
确认本地路径真实存在，manifest 与 SDK 版本兼容，且 dist 已构建。npm / Git 安装禁用生命周期脚本，不会替你生成缺失的入口文件。
查看应用中心的任务状态与错误；CLI 可读取 plugins.jobs。插件 ID 重复、使用保留名称或入口超出包目录都会被拒绝。
fn 仅接受当前 @semicoder/fn-sdk 和 fn 清单字段，不适配旧插件。提示缺少 Bun 时安装 Bun >=1.4.2；源码宿主固定使用 1.4.3。缺少项目依赖时在插件目录运行 bun install --ignore-scripts，再执行 fn plugin check。
为什么切页或重启后草稿不见了
未声明 keepAlive: true 的插件默认切页卸载。开启它也只保留当前窗口运行中的状态，不能跨刷新、重启和应用更新恢复草稿。需要长期保存的内容必须写入 KV。
卸载插件保留 KV 与运行历史。开发实例与安装应用使用不同数据目录，不能把另一个实例的数据未显示当成删除。
找不到置顶按钮或重启后未保留
置顶按钮由 FIA 提供，在标题栏浏览器入口左侧。置顶只保留当前窗口生命周期，退出应用后恢复默认；浏览器页面不提供此原生控制。
两个 fn 图标相同
0.3.0 的开发和预览构建分别显示 Dev / Preview 名称与 DEV / PREV 标记，数据与正式版分开，可以同时运行；直接打开普通 dist/fn.app 默认共用正式数据目录，不能据应用路径判断隔离。
fn 开发、预览和正式数据隔离，详见本地构建。
更新与安装包
fn 尚无新名称的正式下载，请按本地构建说明使用；不要下载历史框架归档代替应用。
更新时，有模型、插件或登录任务会延迟切换。代码失败回退不恢复旧数据；原生运行时改变时需重新安装完整应用。
反馈问题
向维护者提供系统版本、芯片、应用版本、复现步骤与脱敏后的错误。不要附带模型 API Key、授权链接、完整个人输入或账号数据。
浏览器界面提示连接已结束
后端重启、更新或手动断开后，回到原生应用，点击标题栏最右侧“在浏览器中打开”重新进入。普通地址、旧授权链接和刷新都不能重新授权。授权链接仅一次有效、60 秒过期。浏览器必须支持本机安全上下文中的 Service Worker，初始化失败时不会降级开放 API。此界面与模型服务的 OAuth 登录页是不同用途。
若开发版点击“选择本地包”报告 Could not connect to the FIA Native Runtime，检查开发进程和框架构建报告；开发命令会自动准备共仓 FIA，框架变化后自动重启应用，不再手动刷新相邻包。旧 Vite 缓存可能保留不支持浏览器握手票据的客户端；FIA 0.17.0 已按实际 SDK 内容更新缓存指纹。文件选择已在浏览器权限白名单内，无需开放钥匙串、屏幕捕获等其他原生能力。文件面板等待用户操作，不再受普通 30 秒调用期限打断；主动取消或撤销授权仍会中止等待。
市场刷新或更新失败
先检查网络与 HTTPS 市场地址。刷新失败时显示上次成功缓存及时间，安装和更新仍需连接原市场，不能只用过期缓存安装。来源被停用或删除不会影响已安装插件运行；重新添加相同地址不会自动改变已安装绑定。
哈希、包身份或 SDK 不符时拒绝安装；同版本和降级被拒绝。运行中的模型任务或插件方法会阻止替换，等待或取消后重试。失败保留旧版；若激活恢复也失败，按插件错误详情排查可信插件自身行为。