> ## Documentation Index
> Fetch the complete documentation index at: https://gugu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# App API 导览

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

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

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

本页提供查找入口和常用契约。完整签名、参数和返回值由产品内 `guide_read` 的专题说明维护，可请咕咕里的 Agent 逐篇阅读。清单字段见 [manifest](/apps/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 控制、后台页或本机工作目录。每次调用都可能因撤权、离线或文件变化失败，必须给出可见结果。不要把失败画成空列表。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.