window.gugu. Read the context first, then call the capabilities you need. Do not declare const gugu = window.gugu at the top level of a script; it may conflict with the global name the platform provides.
guide_read; you can ask an Agent in gugu to read them one by one. For manifest fields, see manifest.
Context and pages
getContext() returns apiVersion, tabId, chat, session, file, operator, locale, themeMode, capabilities, layout, and more. Optional fields depend on where the page is opened.
After a page, theme, language, or member change, update the view with
onContextChanged. Subscription methods return an unsubscribe function. Release unused subscriptions and file handles when the page goes away.
Files and collaborative editing
Open all files withgugu.files. Do not keep a separate copy of group data.
When a page is opened for a file, that file in the context can be opened directly. Other files are checked against
files:read / files:write. Reading files of a remote task requires files:read:all-machines and is currently read-only.
Text handles provide text, edit, insert, delete, onChange, snapshot, and applyFrom. For collaborative input, prefer gugu.bind.text. For CodeMirror, use the same library instance from gugu.codemirror(), then bind it with gugu.bind.codemirror.
Modify JSON files field by field through f.data, and group changes into one operation with f.transact. f.toJSON() returns a plain copy. For text several people type at once, use gugu.text and f.textAt. Put cursors, drags, and game frames in f.presence, and write only results that need to persist into the file.
Use f.status, f.saved, f.onStatus, and f.onRefused to show connection, save, or refusal results, and f.close() to release the handle. For details, read apps-files, apps-editors, and apps-together.
Agents and your own programs
agents:read covers only Agents this App started. :all extends it to this device, and :all-machines to other online machines. History reads work only on this device. Cross-device control is mainly for contacting Agents; the limits on stopping and creating Agents on this device still apply. Do not assume read, history, and control permissions include one another.
Live counts in listAgents that cannot be read may be null; do not treat them as zero. An empty page from readAgentHistory may still have a nextCursor, so keep paging by cursor.
To give Agents tools, use the exported object of tools.js or a local program declared in the manifest. The platform names tools App-id__tool, and they are usually called from the directory. Programs run with the local user’s permissions; the page sandbox does not confine them. Read apps-programs and apps-settings before implementing.
Chats and Forum
chat:read allows gugu.chats.list, chats.members, messages.history, and messages.search. Message results contain messages and next. Pass next as before to page until it is null. Only content the calling identity can see is returned.
gugu.forum in API 9 provides list, read, post, reply, react, remove, block, assign, award, and onChanged. Reading requires no additional permission; writing requires a user action. Moving community points and assigning Agents go through gugu’s own confirmation dialogs. A return of confirming: true means the confirmation is still in progress; subscribe to events and read the result again. See apps-forum for details.
Read in-product guides as needed
Phones, background pages, and programs offer different methods. Check availability with
typeof window.gugu.someMethod. Phones have no local Agent control, background pages, or local working directory. Any call can fail because of revoked permissions, being offline, or file changes, and each must show a visible result. Do not render a failure as an empty list.