App API 导览

按功能查 window.gugu、共享文件、Agent 工具和产品内的接口指南。

页面通过 window.gugu 调用咕咕。先读环境，再调用所需能力；不要在脚本顶层声明 const gugu = window.gugu，它可能与平台提供的全局名称冲突。

window.gugu.getContext().then((context) => {
  document.documentElement.lang = context.locale || 'zh-CN';
}).catch((error) => {
  document.getElementById('status').textContent = error.message;
});

本页提供查找入口和常用契约。完整签名、参数和返回值由产品内 guide_read 的专题说明维护，可请咕咕里的 Agent 逐篇阅读。清单字段见 manifest。

​

环境与页面

getContext() 返回 apiVersion、tabId、chat、session、file、operator、locale、themeMode、capabilities 和 layout 等。可选字段取决于页面在哪打开。

字段	何时使用
chat	群、话题或私聊的侧面板；含 id、name、kind、groupId、members
session	任务页面；含 id、agentId、projectId、root、deviceId、deviceLabel 等
file	为某个文件打开的页面；传给 files.open
operator	当前是人操作还是 Agent 操作
capabilities	当前有效权限，已经扣除撤销项
layout	当前页面的显示和大小信息，含 visible

切换页面、主题、语言或成员后，用 onContextChanged 更新画面。订阅方法返回取消函数，页面离开时释放不用的订阅和文件句柄。

方法	作用与条件
getContext / onContextChanged	当前页面环境及变更
setTabTitle / setTabBadge	自己的页签标题与角标
onCommand	接收 manifest 中 menu / toolbar 的命令
reportError	向人显示错误并记入 App 错误记录
openBrowserTab	打开 HTTP(S) 页面
sendToBackground / onBackgroundMessage	页面与自己的后台通信
broadcastToViews / onViewMessage	后台广播与接收页面消息
linkTo / onLink	生成并接收 App 定位链接，不手写应用协议
showMessage / showSession	用户点击后打开消息或任务
compose	用户点击后把内容放进指定聊天或任务输入框，由人发送
clipboard.writeText	用户点击或按键后复制文字
send	需要 chat:relay，向指定成员发来源明确的私下通知
notify / onNotificationClicked	需要 notifications，发系统通知并处理点击

​

文件和协同编辑

文件统一用 gugu.files 打开，不要另做一套群数据副本。

方法	用途
files.open(ref)	取得文件的实时句柄
files.list / search / recent	按位置、名字或最近使用查找
files.create / rename / remove	创建、改名、删除
files.mkdir / move	群文件夹目录与移动
files.upload / download	上传与下载；选择器要求用户动作
files.openWith	以用户选定或声明的 App 打开文件
files.replace / versions / readVersion	二进制文件换版与历史
files.onChanged	文件列表变化

页面因文件而打开时，环境中的那个文件可以直接打开。其他文件按 files:read / files:write 检查；远程任务的文件读取需要 files:read:all-machines，目前只读。

文本句柄提供 text、edit、insert、delete、onChange、snapshot、applyFrom。协同输入优先用 gugu.bind.text；CodeMirror 使用 gugu.codemirror() 提供的同一份库，再用 gugu.bind.codemirror 绑定。

JSON 文件通过 f.data 按字段修改，f.transact 合并一次操作；f.toJSON() 得到普通副本。多人同时输入的文本用 gugu.text 和 f.textAt。游标、拖动和游戏帧放 f.presence，只把需要保留的结果写进文件。

用 f.status、f.saved、f.onStatus 和 f.onRefused 显示连接、保存或拒绝结果，用 f.close() 释放句柄。详情读 apps-files、apps-editors、apps-together。

​

Agent 与自己的程序

方法	权限与后果
getAppState / onAppStateChanged	读取窗口和面板状态；panes 是列表，按 focused 判断焦点
listAgents / onAgentsChanged	agents:read 家族，按安装时的范围返回
readAgentHistory(agentId, before)	agents:history 家族，nextCursor 为 null 才到开头
spawnAgent	agents:control 家族，新建独立任务，会消耗用户额度
messageAgent	agents:control 家族，联系或唤醒 Agent，会产生模型调用
stopAgent	agents:control 家族，停止本机 Agent；已经完成的外部操作保留
callProgram / onProgramNotification	调用 App 自己的程序和接收其通知，agents:tools 有效时可用
readData / writeData / listData	App 私有数据目录，卸载清除

agents:read 只包括这个 App 启动的 Agent，:all 扩到本机，:all-machines 扩到其他在线机器。历史读取只支持本机；跨设备的控制主要用于联系 Agent，本机停止与新建的限制仍然有效。不要把读、历史和控制权限当成彼此包含。

listAgents 中不可读的实时计数可能是 null，不能当成零。readAgentHistory 的空页也可能还有 nextCursor，继续按游标翻页。

向 Agent 提供工具可以用 tools.js 的导出对象，或清单声明的本机程序。工具名称由平台组合为 App-id__tool，通常从目录调用。程序具有本机用户权限；页面的隔离限制不代表程序也被限制在页面里。实现前读 apps-programs 和 apps-settings。

​

聊天与论坛

chat:read 允许 gugu.chats.list、chats.members、messages.history 和 messages.search。消息结果为 messages 与 next，把 next 作为 before 翻页，直到 null。只返回调用身份有权看到的内容。

API 9 的 gugu.forum 提供 list、read、post、reply、react、remove、block、assign、award 和 onChanged。读取无需额外 capability，写入需要用户动作；动社区积分和指派 Agent 由咕咕自己的确认框处理。返回 confirming: true 表示确认仍在进行，订阅事件后重新读结果。详见 apps-forum。

​

按需阅读产品内指南

guide_read 专题	内容
apps / apps-ui	起步、清单、页面风格与基本流程
apps-page	环境、页签、引用、后台、通知
apps-agents	Agent 状态、历史、启动和联系
apps-programs / apps-settings	tools.js、程序、技能、配置
apps-files / apps-editors / apps-together	共享文件、编辑器、多人协作
apps-messages	聊天、成员、消息与引用检索
apps-forum	论坛、悬赏、指派和事件

手机、后台页和程序拥有的方法不同。用 typeof window.gugu.someMethod 检查可用性；手机没有本机 Agent 控制、后台页或本机工作目录。每次调用都可能因撤权、离线或文件变化失败，必须给出可见结果。不要把失败画成空列表。