小程序常见问题

使用类

装到个人和装到群里有什么区别？

个人安装只出现在你的侧边栏「小程序」分区，点开即用；群安装对该群所有成员生效，用 #指令 调用。两边的数据（KV）互不相通。

「加为好友」是什么意思？

只是列表里多一个入口，方便一键打开，不是好友关系：没有私聊窗口、不会出现在好友列表、也不会有好友申请。

群里谁都能装小程序吗？

任何群成员都可以添加到本群；卸载和改授权需要安装者本人，或该群的群主 / 管理员。

小程序代发的消息是谁发的？

以调用者的名义发出（气泡显示的是你的头像和名字），底部会有一个很小的「via 小程序名」标记。消息同样受禁言、处罚、敏感词等既有规则约束。

卸载后数据还在吗？

不在了。卸载会清掉该小程序在这个命名空间下的 KV 数据，这是刻意设计。

能不能发图片 / 文件？

不能。当前只提供文本发送（message.send）。需要富媒体时，可以在消息里放链接。

能不能读取历史消息？

只能读当前会话最近 100 条（chat.read）。没有全量检索接口。

小程序之间能互相调用吗？

不能。每个小程序只有自己的命名空间和自己的令牌，跨调用会被 403 拒绝。

能不能在页面里用 localStorage？

技术上可以，但沙箱是不透明源，存储随时可能被清掉、也不跨设备。要持久化就用 CircleChat.kv。

为什么 CircleChat.ready() 返回 null？

握手 4 秒超时。常见原因：页面不是被平台加载的（浏览器直接打开）、SDK 没加载成功、宿主页面已关闭。页面应当在这种状态下仍然可用（至少不白屏）。

小程序能拿到 Cookie 或用户密码吗？

不能。沙箱没有 allow-same-origin，拿不到 Cookie，也碰不到宿主 DOM。身份完全由平台的 RPC / 令牌代理。

支持哪些浏览器？

与 CircleChat 主程序一致（现代 Chromium / Firefox / Safari）。注意 srcdoc + sandbox 在很旧的浏览器上可能受限。

官方源能不能换？

能。管理面板里改源配置即可，也可以停用官方源只用自建源。

索引多久更新一次？

启动加载一次 + 30 分钟缓存；管理员可手动刷新。

第三方源会不会偷数据？

平台不会把 Cookie 或令牌发给第三方服务器：索引由服务端（或无凭据跨域请求）拉取，令牌仅通过 postMessage 在运行时下发。但第三方页面的脚本仍运行在你的用户浏览器里（沙箱内、受授权约束），所以只应添加可信源。

更多排查见部署者指南。