常见问题与故障排查

先找日志Copy Anchor Link

大部分问题看一眼日志就能定位。日志在应用数据目录的 logs/main.log(macOS:~/Library/Application Support/ 下以应用名命名的目录;Windows:%APPDATA% 下同名目录)。超过 1MB 会重写。

反馈时请带上:客户端版本、系统版本、复现步骤、日志里对应时间段的片段。不要贴密钥或私人文件内容。

登录Copy Anchor Link

收不到验证码Copy Anchor Link

1. 检查垃圾邮件、垃圾箱、邮箱拦截规则;
2. 国内邮箱可能延迟 1–2 分钟,稍等;
3. 连续发送有冷却,别狂点;
4. 确认邮箱地址没打错。

每次都让我重新登录Copy Anchor Link

本地令牌失效了。常见原因:重装、清过应用数据、服务端吊销、换了设备。正常登录一次即可。如果同一台机器反复要求登录,把这当作 bug 反馈。

新电脑登录后岛是空的Copy Anchor Link

这是设计如此,不是 bug。群岛不做跨设备同步,新设备 = 新岛。要带走的文件请自己从 ~/群岛/ 拷。

更新Copy Anchor Link

macOS 更新失败 / 一直转圈Copy Anchor Link

1. 设置 → 关于 → 手动检查一次;
2. 取消当前下载后重试(取消是安全的);
3. 仍然失败时,更新器会自动退回「下载 DMG + 手动拖装」——直接去下载页手动装;
4. 差分缓存损坏偶发会导致下载卡住,重试一次通常就好。

Windows 提示「不支持更新」Copy Anchor Link

Windows 版暂未接入应用内更新器。去下载页重新安装覆盖即可,数据不受影响。

被强制升级Copy Anchor Link

低于最低版本的客户端会被要求升级——老版本可能已经和后端协议对不上。升级不会动工作区与数据。

网络与代理Copy Anchor Link

• 群岛遵循系统代理。代理开着但连不上时,先确认系统代理本身正常。
• 网页抓取对内网地址与带凭证的地址一律拒绝,并且不走云端兜底——这是防内网探测的红线,不是网络故障。
• 云端搜索与抓取有独立限速。触发限速时,稍等再试,或改用本机抓取。

居民一直「正在想」Copy Anchor Link

群岛的三层兜底:

1. 流首字节超时 60 秒:流建立后 60 秒没有任何内容(心跳不算)就判定挂起,自动断开重试;
2. 瞬时故障重试:过载秒拒、网络断开时按 1s → 3s 退避自动重发,最多 2 次;
3. 每回合累计重试上限 6 次,防极端场景放大。

重试耗尽才会弹错误,并且会附错误码方便反馈。已吐字后中断不重发(避免内容重复),所以有时你只会感觉「这次想了有点久」。

积分Copy Anchor Link

余额还有但发不出去Copy Anchor Link

以设置 → 套餐与积分的余额为准。低于 200 会亮预警,用完会暂停发送;服务端 403 是最终兜底。若页面数字和实际拦截长期不一致,报 bug。

之前明明够用,今天扣得很快Copy Anchor Link

• 上下文越长每回合越贵;长会话建议拆成任务会话;
• web_search 每次 1 积分;
• 检查是否开了群聊多居民回合(群预算按成员数放大)。

兑换码说无效Copy Anchor Link

• 检查是否已过期、是否已被使用;
• 活动码可能限制席位数;
• 入账失败不会吞码,可以重试。

审批Copy Anchor Link

找不到审批卡Copy Anchor Link

审批卡可能在你看不到的会话里。看这四处:侧栏会话头像角标、侧栏顶部待审横条、聊天头部琥珀线、Dock 角标。有未处理审批的会话会在消息列表置顶。

快捷键误触了「允许」Copy Anchor Link

「批准当次有效」,不会延续成默认。如果担心,去居民档案把档位调回半自动,并在回合时间线里查看那次的执行记录。

「本回合不再问」会一直生效吗Copy Anchor Link

不会。它只对本回合、本会话生效,回合结束即失效,也不会漏给同一居民的其它任务会话。

文件与工作区Copy Anchor Link

居民说文件找不到Copy Anchor Link

1. 确认它说的是哪个工作区——居民默认工作区在 ~/群岛/<居民名>-<短号>/;
2. 如果给居民指过真实项目目录,确认目录还在、没被移动;
3. 如果文件是居民自己生成的,看居民档案的**「文件」页签**,那里列出 TA 经手写过的所有文件,点行可直接打开。

居民把文件写到奇怪的地方Copy Anchor Link

半自动档下工作区外写入会弹审批卡。如果你批准过,那就是你批准的那次。全自动档会在回合时间线留「全自动放行」回执签,可以回看。

任务会话把我原来的目录改了?Copy Anchor Link

任务会话绑定 git 仓库时默认隔离:改动落在任务自己的分支与工作树上,你的原目录逐字节不动。非 git 目录才会走直连模式,而且授权卡上会明示「无隔离」。如果怀疑现场被破坏,先不要结束任务——脏现场默认保留,不会强删。

技能卡Copy Anchor Link

导入失败Copy Anchor Link

按错误提示对号:

居民记不住我教的技能Copy Anchor Link

技能卡的生效方式是下次遇到同类事情时按卡办,不是「永远记得」。装多了会切名册模式,正文只在需要时调取。想让某张卡常驻,把正文写短(常驻总量上限 8,000 字)。

反馈Copy Anchor Link

两个渠道,都不用另外注册:

1. 邮局 → 群岛联络站:每座岛默认自带这位官方好友,注册就会收到欢迎信。直接回信即可提问题、建议、bug。这条通道不可删除、不可拉黑。
2. 吩咐任意居民代寄给联络站,署名是「居民名 · 岛名」。

也可以在仓库提 issue:xianglifei/archipelago-app。

文档本身写错了?每页右上角有「编辑此页」,直接提 PR。