acde: 模块
每个模块同时有命名导出和默认导出:
import { fs } from 'acde:fs'import fs from 'acde:fs'类型在 @dopame/acde-api: @dopame/acde-api/app 声明应用能导入的模块, @dopame/acde-api/shell 再加上 shell 模块, 包的根声明全部. 能力怎么申请、怎么批准见 系统能力.
谁能导入什么. 「应用」指自己单独一个包的应用; 「系统应用」随桌面的包一起发 (桌面配置的 apps). 格子里的名字是应用必须声明的能力:
| 模块 | 应用 | 系统应用 | 桌面页面 |
|---|---|---|---|
acde:window |
✓ | ✓ | |
acde:capabilities |
✓ | ✓ | ✓ |
acde:apps |
✓ | ✓ | ✓ |
acde:open |
✓ (打开应用要 open) |
✓ (同样) | ✓ |
acde:fs |
fs |
fs |
✓ |
acde:terminal |
terminal |
terminal |
✓ |
acde:network |
network |
network |
✓ |
acde:system |
system |
system |
✓ |
acde:bluetooth |
bluetooth |
bluetooth |
✓ |
acde:audio |
audio |
audio |
✓ |
acde:devices |
devices |
devices |
✓ |
acde:power |
power |
power |
✓ |
acde:input |
input |
input |
✓ |
acde:display |
display |
display |
✓ |
acde:office |
office |
office |
✓ |
acde:openPath acde:handlers |
openFiles |
openFiles |
✓ |
acde:launch |
launch 或 slots |
launch 或 slots |
✓ |
acde:windows acde:packages acde:session acde:desktops acde:inspect acde:desktop acde:setDefault acde:permissions (shell 模块) |
模块的名字: "windows": true |
✓ | |
acde:<服务> |
services 里的服务名 |
同样 | ✓ |
平台上没有的模块, 在那里谁都拿不到 (见 平台支持). 不允许的导入以 AcdeError 失败 (code: 'forbidden', status: 403, module 是去掉 acde: 的名字), 消息里写明缺的是哪条声明, 比如 acde:terminal needs "terminal" in the capabilities of Notes; 提供这个模块的服务停了时, 代码是 service_not_running, 状态是 503. 见 错误. 桌面服务不能导入 acde: 模块; 桌面授予了外壳模块的服务从 ctx.import() 拿到它们; 见 服务接口.
事件用 on(type, handler) 订阅, 返回退订函数. 遇到模块没有的事件类型, on() 抛 TypeError, 比如 acde:window has no nosuch event (activate, deactivate, …). acde:terminal 改用回调 (subscribe); acde:network 有 on('changed'), 也可以用 watch 传回调.
错误
错误 一节的链接系统模块 (acde:network、acde:system、acde:bluetooth、acde:audio、acde:devices、acde:power、acde:input、acde:display) 失败时只有一种错误, 不管是方法同步抛出还是它的 Promise reject: name === 'AcdeError' 的 Error, 带 status、code 和 module (去掉 acde: 的模块名). 原因放在 cause 里, 原因自己有代码时放在可选的 reason 里. 类型是 @dopame/acde-api 里的 AcdeError 和 AcdeErrorCode; 用 error.name === 'AcdeError' 判断这种错误. 代码有:
code |
status |
什么时候 |
|---|---|---|
bad_request |
400 | 参数不对, 比如主机名、时区、电源设置、亮度或设备 id |
forbidden |
403 | 应用没被给予这个模块或这个调用 (不在它的能力里) |
unsupported |
501 | 这个运行时或平台做不了 |
service_not_running |
503 | 它需要的系统服务或总线不在 (NetworkManager、BlueZ、UPower、fcitx5 之类) |
failed |
500 | 其他情况 |
try { await network.connect('Home', 'secret')} catch (error) { if (error.name === 'AcdeError' && error.code === 'service_not_running') showOffline() else throw error}导入应用没被给予的模块, 以同样的错误失败, code: 'forbidden' (见上文).
acde:window
acde:window 一节的链接interface AcdeWindow { readonly id: number readonly state: WindowState readonly output: WindowOutput readonly hostControls: boolean readonly minimizable: boolean readonly host: WindowHost mount(app: WindowApp): void setTitle(title: string): void setMenus(menus: readonly AppMenu[]): void close(): Promise<boolean> minimize(): Promise<void> requestAttention(): Promise<void> requestState(state: WindowState): void requestMode(mode: WindowMode): void setGrabHint(rect: WindowRect, edges?: readonly ('top' | 'bottom' | 'left' | 'right')[]): void setBackdrop(rect: WindowRect | null, effect?: { radius?: number; blur?: number; saturate?: number; brightness?: number }): void requestActivate(): void requestGrab(kind: 'pointer' | 'keyboard'): void releaseGrab(kind: 'pointer' | 'keyboard'): void shortcut(combo: string): Promise<void> unshortcut(combo: string): Promise<void> on(name: 'beforeclose', handler: () => boolean | void | Promise<boolean | void>): () => boolean on<R extends AppRequest = AppRequest>(name: 'request', handler: (request: SystemRequest | R) => void): () => boolean on(name: 'activate' | 'deactivate', handler: () => void): () => boolean on(name: 'state', handler: (event: { readonly state: WindowState; readonly previous: WindowState }) => void): () => boolean on(name: 'output', handler: (output: WindowOutput) => void): () => boolean on(name: 'hostcontrols', handler: (hostControls: boolean) => void): () => boolean on(name: 'minimizable', handler: (minimizable: boolean) => void): () => boolean on(name: 'shortcut', handler: (event: ShortcutEvent) => void): () => boolean on(name: 'grab', handler: (event: { readonly kind: 'pointer' | 'keyboard'; readonly granted: boolean }) => void): () => boolean on(name: 'grablost', handler: (event: { readonly kind: 'lost'; readonly reason: 'esc' | 'other_window' | 'focus_lost' | 'denied' }) => void): () => boolean on(name: 'suspend' | 'resume', handler: () => void): () => boolean}
type WindowState = 'normal' | 'minimized' | 'filled' | 'fullscreen'type WindowMode = 'free' | 'fixed' | 'pinned'
interface WindowRect { x: number; y: number; width: number; height: number }interface WindowOutput { width: number; height: number; scale: number; workArea: WindowRect }
interface ShortcutEvent { type: 'shortcut'; window: number; key: string; title: 'session' | 'desktop' | 'app' }
interface AppMenu { id: string label: string items: ({ type: 'separator' } | AppMenuItem)[]}interface AppMenuItem { id: string label: string shortcut?: string checked?: boolean disabled?: boolean onSelect?(): void | Promise<void>}
interface WindowApp { mount(element: Element, host: WindowHost): () => void}interface WindowHost { setTitle(title: string): void setMenus(menus: readonly AppMenu[]): void}- 全屏是一种状态:
requestState('fullscreen').requestMode('fullscreen')抛TypeError, 不认识的状态也一样.requestState没有结果, 看state事件. 见 窗口状态. close()关掉窗口, 不问beforeclose.- 窗口不能最小化时 (
minimizable是false),minimize()以status: 409、code: 'unavailable'reject: 只跑一个应用的会话, 在 macOS 上和 headless 时, 应用的窗口报的是window 1048576 cannot be minimized: it fills the host window, which only the host window's own controls minimize here. 那里requestState('minimized')什么都不变. suspend和resume有声明, 但运行时现在还不发.- 坐标是页面 (内容区) 的逻辑像素. 快捷键组合写成
ctrl+alt+t: 键是 xkb keysym 名, 也就是 X11 和 Wayland 用的键名 (t、return、escape、f5、space, 不分大小写), Shift 写进组合.
acde:capabilities
acde:capabilities 一节的链接interface AcdeCapabilities { readonly level: number readonly platform: 'linux' | 'win32' | 'darwin' readonly mode: 'session' | 'desktop' | 'standalone' readonly window: { readonly backdrop: 'full' | 'approximated' | 'unsupported' } get(name: string): CapabilityStatus list(): CapabilityStatus[] request(name: string): Promise<CapabilityStatus>}
interface CapabilityStatus { name: string kind: 'system' | 'service' state: 'available' | 'not-asked' | 'asking' | 'not-declared' | 'unsupported' | 'service-not-running' | 'shell-only' | 'denied' reason: string optional: boolean}level 是契约级别 (1). request(name) 就一项需要批准的能力询问用户, 用户回答后以它的状态 resolve; 别的名字立刻 resolve. 需要批准的能力只有在用户允许之后才是 available: 提示之前是 not-asked, 提示在等的时候是 asking, 被拒绝或批准被收回之后是 denied. 被批准拦下的调用失败, 带 status: 403、capability, code 是 not_asked、asking、denied 之一. 名字可以是能力名、共享位置的 fs.<位置> (fs.downloads)、服务名和 notifications (标准的 Notification 接口: available, 在这种运行方式没有通知的地方是 unsupported). 见 系统能力.
acde:fs
acde:fs 一节的链接interface AcdeFs { roots(): Promise<FinderRoot[]> list(root: string, path?: string, hidden?: boolean): Promise<{ root: FinderRoot; path: string; entries: FinderEntry[]; truncated: boolean; skipped?: number }> stat(root: string, path: string): Promise<FinderEntry & { path: string }> readText(root: string, path: string): Promise<{ text: string; modifiedMs: number; size: number; version: string }> readBytes(root: string, path: string): Promise<{ data: Uint8Array; modifiedMs: number; size: number; version: string }> readRange(root: string, path: string, offset: number, length: number, options?: { ifVersion?: string }): Promise<{ data: Uint8Array; offset: number; size: number; modifiedMs: number; version: string }> writeFile(root: string, path: string, data: string | Uint8Array, options?: { create?: 'always' | 'new' | 'never' ifVersion?: string ifModifiedMs?: number mkdirs?: boolean }): Promise<FinderEntry> openWrite(root: string, path: string, options?: { keepExistingData?: boolean create?: 'always' | 'new' | 'never' ifVersion?: string mkdirs?: boolean }): Promise<{ id: string; size: number }> writeChunk(id: string, offset: number, data: string | Uint8Array): Promise<void> truncateWrite(id: string, size: number): Promise<void> commitWrite(id: string): Promise<FinderEntry> abortWrite(id: string): Promise<void> mkdir(root: string, path: string, options?: { recursive?: boolean }): Promise<FinderEntry> rename(root: string, from: string, to: string): Promise<FinderEntry> delete(root: string, path: string): Promise<{ status: 'deleted'; path: string }> copy(fromRoot: string, fromPath: string, toRoot: string, toDir: string): Promise<FinderEntry & { path: string }> preview(root: string, path: string): Promise<FinderPreview> download(root: string, path: string): Promise<{ name: string; contentType: string; data: Uint8Array }> revoke(root: string): Promise<void> locate(path: string): Promise<{ root: string; path: string }> openPath(root: string, path: string): Promise<{ root: string; path: string; file: string }>}
interface FinderRoot { id: string label: string source: 'private' | 'place' | 'granted' | 'desktop' | 'downloads' | 'default' place?: 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos' path?: string mode: 'writable' | 'read_only' | 'unavailable' reason: string | null exists: boolean}
interface FinderEntry { name: string kind: 'directory' | 'file' | 'symlink' | 'other' size: number modifiedMs: number target?: string version?: string inPlace?: true}
interface FinderPreview { path: string name: string size: number modifiedMs: number kind: 'text' | 'image' | 'binary' | 'too_large' content?: string truncated?: boolean}root是roots()里某一项的id:private、共享位置的名字, 或选中的文件夹的folder-…; 永远不是路径. 应用的根的source是private、place(带place) 或granted, 没有path.- 只有列了共享位置的系统应用和桌面页面才有
path.locate和openPath也只对它们有效; 在别的应用里以EACCESreject. - 桌面页面的根是按路径给的文件夹 (
source是desktop、downloads、default或granted), 它们的id就是路径. list不含隐藏项, 除非hidden是true;skipped是名字不是合法 Unicode 而被跳过的项数.copy把一个根里的文件或文件夹复制进另一个根的文件夹toDir; 名字被占了就加一个编号 (todo 2.md),path是副本在toRoot里的位置.revoke交还用户选中的一个文件夹.version是一个不透明的字符串, 代表文件的一个状态; 把它作为ifVersion传进去, 文件在那之后变了的话, 写 (或readRange) 以ECONFLICT失败.inPlace标出一次没能经过临时文件的写. 见 安全地写.openWrite开始一次分块的写: 在任意偏移处writeChunk、truncateWrite, 然后commitWrite把文件放到位 (或abortWrite). 放着 10 分钟不管的写会被放弃. 见 大文件.- 上限:
readText/readBytes/writeFile64 MiB;readRange/writeChunk每次调用 16 MiB;list5000 项 (truncated);preview的文字 256 KiB. download回的contentType是系统按文件名认出的类型:note.md是text/markdown,shot.png是image/png, 名字认不出类型的 (data.xyz) 是application/octet-stream. 类型来自系统, 见 文件和链接 里的说明.- 错误带
code和status, 见 文件与文件夹.
acde:open
acde:open 一节的链接interface AcdeOpen { (app: string, request?: null, options?: OpenWindowOptions): Promise<{ window: number }> <R extends AppRequest>(app: string, request: R, options?: OpenWindowOptions): Promise<{ window: number }> (app: string, request: SystemRequest): Promise<Opened> (request: SystemRequest): Promise<Opened>}
type AppRequest<K extends string = string, Fields extends object = Record<never, never>> = { readonly kind: K } & { readonly [P in keyof Fields]: Fields[P] }
type SystemRequest = | { kind: 'open-file'; handle?: FileSystemFileHandle | FileSystemDirectoryHandle; url?: string; root?: string; path?: string; file?: string | null } | { kind: 'open-link'; url: string }
interface OpenWindowOptions { parent?: number; modal?: boolean }interface Opened { kind: 'acdev' | 'native'; id: string; window?: number }open(app)和open(app, request)需要open能力允许app. 发给应用的请求必须有kind, 而且是目标在自己的requests里列了的 (400untyped_request、409not_accepted).open(request)带系统请求而不带应用时需要openFiles: 由系统挑应用. 带应用时, 目标必须声明了这个文件的类型 (mimeTypes) 或这个链接的 scheme (schemes).- 接收的应用拿到的文件是
{ kind: 'open-file', handle }; 列了共享位置的系统应用还会拿到url. 发文件用handle(这个页面从选择器、拖放或请求里拿到的句柄), 或者在调用方知道路径的地方用url. - 接收方用
AppRequest<K, Fields>给自己的请求写类型:type ShowImage = AppRequest<'show-image', { image: string }>, 然后self.on<ShowImage>('request', …)按kind收窄.SystemRequest和AppRequest也在acde:window的request事件里 (见上).
见 打开应用.
acde:apps
acde:apps 一节的链接interface AcdeAppList { list(): Promise<DesktopApp[]> open: AcdeOpen on(type: 'changed', handler: (event: { type: 'appschanged'; apps: readonly DesktopApp[] }) => void): () => boolean}
interface DesktopApp { id: string; label: string; icon: string; script: string }list() 给出能在这里跑的应用; open 就是 acde:open 的那个函数. 列表变了, changed 就带着新的列表触发. 摄像头或麦克风被拒绝时, 应用仍留在列表里. 安装包和原生程序在 acde:packages 里.
acde:openPath / acde:handlers / acde:setDefault
acde:openPath / acde:handlers / acde:setDefault 一节的链接function openPath(path: string, options?: { app?: string; select?: boolean }): Promise<{ kind: 'acdev' | 'native'; id: string; window?: number }>function handlers(path: string): Promise<{ mime: string; association: string | null; handlers: OpenHandler[] }>function setDefault(association: string, handler: string): Promise<string>
interface OpenHandler { kind: 'acdev' | 'native' id: string label: string icon: string default: boolean system?: boolean}path 可以是路径或 URI. openPath 和 handlers 需要 openFiles; 对应用来说, 文件必须在它的某个根里 (404 outside_roots). setDefault 是 shell 模块. association 是记住一次选择时用的键: MIME 类型, 或 Windows 上文件的扩展名 (.md); 系统不知道文件的类型时 mime 是 ''. system 标出系统自己的默认程序 (Windows).
acde:launch
acde:launch 一节的链接需要 launch (用 start) 或 slots (用 embed).
interface AcdeLaunch { start(argv: readonly string[], options?: LaunchOptions): Promise<number> embed(argv: readonly string[], options?: LaunchOptions): Promise<number> close(window: number): Promise<boolean> list(): NativeWindow[] on<K extends WindowsEventType>(type: K, handler: (event: WindowsEventMap[K]) => void): () => boolean}
interface LaunchOptions { cwd?: string; env?: Record<string, string> }start 运行一个原生程序, embed 运行一个嵌在应用自己窗口里的原生程序 (仅 Dopame OS). close 关掉应用自己起的窗口; 别的窗口以 403 forbidden 拒绝. 事件就是 acde:windows 的那些.
acde:terminal
acde:terminal 一节的链接需要 terminal.
interface AcdeTerminals { open(cols: number, rows: number): Promise<{ id: string }> subscribe(id: string, callback: (events: TerminalEvent[]) => void): Promise<void> input(id: string, data: string): Promise<{ ok: true }> resize(id: string, cols: number, rows: number): Promise<{ cols: number; rows: number }> close(id: string): Promise<{ closed: string }>}
type TerminalEvent = | { type: 'output'; data: string } | { type: 'cwd'; path: string } | { type: 'exit'; code: number | null; signal: number | null }acde:network
acde:network 一节的链接仅 Linux (Dopame OS, 或任何有 NetworkManager 的 Linux). 需要 network.
interface AcdeNetwork { state(): Promise<NetworkState> networks(scan?: boolean): Promise<WifiNetwork[]> connect(ssid: string, password?: string): Promise<void> activate(iface: string): Promise<void> disconnect(iface: string): Promise<void> setWifiEnabled(on: boolean): Promise<void> on(type: 'changed', handler: (state: NetworkState) => void): () => boolean watch(callback: (state: NetworkState) => void): void}
interface NetworkState { wifiEnabled: boolean connectivity: 'full' | 'limited' | 'portal' | 'none' | 'unknown' primary: 'wifi' | 'ethernet' | string | null devices: NetworkDevice[]}
interface NetworkDevice { iface: string type: 'wifi' | 'ethernet' state: 'connected' | 'connecting' | 'disconnecting' | 'disconnected' | 'unavailable' | 'unmanaged' | 'failed' connection: string | null ip4: string | null ssid?: string strength?: number carrier?: boolean speed?: number}
interface WifiNetwork { ssid: string strength: number secure: boolean band: '2.4GHz' | '5GHz' active: boolean saved: boolean}acde:system
acde:system 一节的链接仅 Linux. 需要 system. 它的错误是 AcdeError.
interface AcdeSystem { info(): Promise<SystemInfo> storage(): Promise<SystemVolume[]> time(): Promise<SystemTime> timezones(): Promise<string[]> setTimezone(zone: string): Promise<void> setNtp(on: boolean): Promise<void> setHostname(name: string): Promise<void> user(): Promise<SystemUser> on(type: 'changed', handler: (change: SystemChange) => void): () => boolean}这台计算机: info() (主机名和其他信息)、storage() (它的卷)、time() (带 timezone 和 ntp)、timezones(), 设置项 setTimezone、setNtp 和 setHostname, 以及 user(). 其中一项变了时, changed 给出 {storage, hostname, timezone, ntp}, 每次都是完整的一份; 有人在听时每 30 秒查一次, 这个页面设了其中一项之后也马上查一次. 状态的类型在 @dopame/acde-api 里.
acde:bluetooth
acde:bluetooth 一节的链接仅 Linux. 需要 bluetooth. 它的错误是 AcdeError.
interface AcdeBluetooth { state(): Promise<BluetoothState> setPowered(on: boolean): Promise<void> setDiscoverable(on: boolean, timeout?: number): Promise<void> setName(name: string): Promise<void> scan(on: boolean): Promise<void> pair(id: string): Promise<void> answer(id: string, accept: boolean, pin?: string): Promise<void> connect(id: string): Promise<void> disconnect(id: string): Promise<void> forget(id: string): Promise<void> setTrusted(id: string, on: boolean): Promise<void> setBlocked(id: string, on: boolean): Promise<void> rename(id: string, name: string): Promise<void> setOnLogin(mode: 'remember' | 'on' | 'off'): Promise<void> on(type: 'changed', handler: (state: BluetoothState) => void): () => boolean on(type: 'pairing', handler: (request: BluetoothPairing) => void): () => boolean}蓝牙适配器和它的设备 (BlueZ). changed 给出完整的 BluetoothState; pairing 请页面确认一次配对、显示或输入 PIN 或配对码, 或授权一项服务, 页面用 answer(id, accept, pin?) 回答. 状态的类型在 @dopame/acde-api 里.
acde:audio
acde:audio 一节的链接仅 Linux. 需要 audio. 它的错误是 AcdeError.
interface AcdeAudio { state(): Promise<AudioState> setDefault(id: string): Promise<void> setVolume(id: string, volume: number): Promise<void> setMuted(id: string, muted: boolean): Promise<void> setBalance(id: string, balance: number): Promise<void> setPort(id: string, port: string): Promise<void> setProfile(card: string, profile: string): Promise<void> moveStream(id: string, device: string | null): Promise<void> on(type: 'changed', handler: (state: AudioState) => void): () => boolean}声卡、输出、输入和正在播放的音频流: 默认设备、音量、静音、平衡、端口和声卡配置, 以及一个音频流在哪个设备上播放. changed 给出完整的 AudioState. 状态的类型在 @dopame/acde-api 里.
acde:devices
acde:devices 一节的链接仅 Linux. 需要 devices. 它的错误是 AcdeError.
interface AcdeDevices { state(): Promise<DevicesState> mount(id: string): Promise<string> unmount(id: string): Promise<void> eject(id: string): Promise<void> setAutomount(patch: Partial<Pick<Automount, 'onLogin' | 'onAttach' | 'unknown'>>): Promise<void> setDeviceAutomount(id: string, patch: Partial<Pick<AutomountDevice, 'login' | 'attach'>>): Promise<void> forgetDevice(id: string): Promise<void> setDefaultPrinter(id: string): Promise<void> pausePrinter(id: string): Promise<void> resumePrinter(id: string): Promise<void> jobs(printer: string): Promise<PrintJob[]> cancelJob(printer: string, job: number): Promise<void> on(type: 'changed', handler: (state: DevicesState) => void): () => boolean on(type: 'added', handler: (drive: Drive) => void): () => boolean}驱动器 (U 盘、存储卡、光盘、手机、磁盘: 挂载、卸载、弹出, 以及自动挂载的设置) 和打印机 (默认打印机、暂停、恢复、任务). changed 给出完整的 DevicesState; 插入一个驱动器时 added 给出它. 状态的类型在 @dopame/acde-api 里.
acde:power
acde:power 一节的链接仅 Linux. 需要 power. 它的错误是 AcdeError.
interface AcdePower { state(): Promise<PowerState> setProfile(profile: PowerProfile): Promise<void> configure(patch: PowerSettingsPatch): Promise<void> setScreenOff(seconds: number | null): Promise<void> setSleep(seconds: number | null): Promise<void> suspend(): Promise<void> hibernate(): Promise<void> setBrightness(value: number): Promise<void> setChargeLimit(percent: number | null): Promise<void> on(type: 'changed', handler: (state: PowerState) => void): () => boolean on(type: 'prompt', handler: (event: PowerPromptEvent) => void): () => boolean on(type: 'critical', handler: (event: PowerCriticalEvent) => void): () => boolean}电池、电源模式、合上盖子、按电源键和空闲时做什么 (接通电源时、用电池时和电量低时)、关屏和睡眠的计时、挂起和休眠、背光, 以及充电上限. changed 给出完整的 PowerState; prompt ({type: 'prompt'}) 请页面给出电源选项, critical ({type: 'critical', action, seconds}) 说明电池电量极低, 以及多少秒后会发生什么. 状态的类型在 @dopame/acde-api 里.
acde:input
acde:input 一节的链接仅 Linux. 需要 input. 它的错误是 AcdeError.
interface AcdeInput { state(): Promise<InputState> set(patch: InputPatch): Promise<void> catalog(): Promise<InputCatalog> on(type: 'changed', handler: (state: InputState) => void): () => boolean}键盘 (型号、布局、选项、Num Lock)、鼠标和触摸板的设置, 以及输入法. set() 接受要改的部分; catalog() 列出可选的型号、布局、选项和输入法. changed 给出完整的 InputState. 状态的类型在 @dopame/acde-api 里.
acde:display
acde:display 一节的链接仅 Linux. 需要 display. 它的错误是 AcdeError.
interface AcdeDisplay { state(): Promise<DisplayState> configure(id: string, patch: DisplayPatch): Promise<void> setBrightness(id: string, value: number): Promise<void> setNightLight(patch: Partial<NightLight>): Promise<void> on(type: 'changed', handler: (state: DisplayState) => void): () => boolean}显示器 (模式、缩放、旋转等, 用 configure 设置)、它们的亮度, 以及夜间模式. changed 给出完整的 DisplayState. 状态的类型在 @dopame/acde-api 里.
acde:session
acde:session 一节的链接shell 模块: 只有桌面页面和它的包里 (能力里写了 "session": true 的) 系统应用能导入; 普通应用不能, 即使声明了 session.
interface AcdeSession { own(): boolean logout(): Promise<void> reboot(): Promise<void> poweroff(): Promise<void> setLanguage(tag: string): Promise<void>}own(): 是不是真正的 Dopame OS 会话 (acdev dev 的宿主窗口里是 false). setLanguage 之后页面收到 languagechange.
acde:desktops
acde:desktops 一节的链接shell 模块.
interface AcdeDesktops { list(): Promise<{ desktops: DesktopInfo[]; current: string }> choose(id: string, remember?: boolean): Promise<void>}
interface DesktopInfo { kind: 'acdev' | 'session' id: string name: string description: string | null package: string | null}kind: 'session' 是系统里别的 Wayland 会话 (GNOME、KDE ……).
acde:packages
acde:packages 一节的链接shell 模块.
interface AcdePackages { refresh(): Promise<DesktopApp[]> install(dir: string): Promise<{ id: string; dir: string; apps: DesktopApp[] }> natives(): Promise<NativeApp[]> runNative(id: string): Promise<number> on(type: 'changed', handler: (event: { type: 'appschanged'; apps: readonly DesktopApp[] }) => void): () => boolean}
interface NativeApp { id: string name: string comment: string | null icon: string keywords: string[] wmClass: string | null}natives() 列出系统里的原生程序 (.desktop 文件, 仅 Linux).
acde:windows
acde:windows 一节的链接shell 模块: 会话里的每一个窗口.
interface AcdeWindows { on<K extends WindowsEventType>(type: K, handler: (event: WindowsEventMap[K]) => void): () => boolean list(): NativeWindow[] close(id: number): void requestState(id: number, state: WindowState): Promise<void> kill(id: number): Promise<boolean> focus(id: number): Promise<void> hide(id: number): Promise<void> show(id: number): Promise<void> invokeMenu(id: number, menu: string, item: string): Promise<void> stats(): Promise<Record<string, number>> animate(id: number, options: { opacity?: number; scale?: number; dx?: number; dy?: number duration?: number; delay?: number easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' }): Promise<void> shortcut(combo: string, scope?: 'session' | 'desktop'): Promise<void> unshortcut(combo: string, scope?: 'session' | 'desktop'): Promise<void> launch(argv: string[], options?: { cwd?: string; env?: Record<string, string>; slot?: boolean }): number | Promise<number>}
interface NativeWindow { id: number; appId: string | null; title: string | null; web?: boolean; state: WindowState }WindowsEventType: open close title state activate minsize parent menus crash hang responsive attention ready show animated. 每个事件都是 { type: 'window<名字>', window: number, … }:
| 事件 | 额外的字段 |
|---|---|
open |
appId、title、web、icon |
title |
appId、title |
state |
state、previous |
minsize |
width、height |
parent |
parent |
menus |
menus: 应用的菜单, 每一项带 action: boolean, 没有 onSelect |
crash |
reason |
- 窗口状态的变化由
state报告; 全屏和最小化没有自己的事件.requestState遇到不认识的状态以TypeErrorreject. close(id)会问应用 (beforeclose);kill(id)不问, 直接结束窗口.- 运行时做不了动画的地方,
animate可能立刻结束;animated照样触发. list()的每一行都带窗口当前的state,list()里有每一个窗口, 在窗口打开之后才启动的系统应用里也一样.- 应用用
acde:launch起原生程序, 不用这里的launch.
acde:desktop
acde:desktop 一节的链接shell 模块.
interface AcdeDesktop { apps(): Promise<{ apps: DesktopApp[] }> pin(element: Element, options?: { margin?: number; reserve?: PanelReserve }): PinnedPanel setDoubleClick(action: 'fill' | 'minimize' | 'none'): void setFrameTheme(theme: FrameTheme | null): void on(type: 'notification', handler: (e: NotificationEvent) => void): () => boolean on(type: 'download', handler: (e: DownloadEvent) => void): () => boolean on(type: 'screenshot', handler: (e: { type: 'screenshot'; path: string; width: number; height: number } | { type: 'screenshot'; path: string; error: string }) => void): () => boolean on(type: 'shortcut', handler: (e: ShortcutEvent) => void): () => boolean on(type: 'edge', handler: (e: { type: 'screenedge'; edge: 'top' | 'right' | 'bottom' | 'left'; entered: boolean; output: string }) => void): () => boolean}
interface PanelReserve { edge: 'top' | 'bottom' | 'left' | 'right'; thickness?: number }interface PinnedPanel { update(): void unpin(): void reserve(reserve: PanelReserve | null): void}
interface FrameTheme { active?: FrameColors inactive?: FrameColors light?: { active?: FrameColors; inactive?: FrameColors } buttonStyle?: 'dots' | 'glyphs' buttonSide?: 'left' | 'right' titleAlign?: 'center' | 'start'}interface FrameColors { background?: string; title?: string; line?: string; buttons?: string }
interface NotificationEvent { type: 'notification' window: number app: string | null label: string | null title: string body: string icon: string tag: string}
interface DownloadEvent { type: 'download' window: number app: string | null path: string name: string size: number}- 指针到达 (
entered: true) 或离开屏幕的一条边时触发edge, 每条边一次 (在角上是两次);output是屏幕的名字, 在宿主窗口里是host. 它不抢焦点, 给要把藏起来的菜单栏或 Dock 再显示出来的桌面用. light: 给页面没声明支持深色 (color-scheme里没有dark) 的窗口用的标题栏颜色; 这时active/inactive给声明了支持深色的页面用. 每次setFrameTheme调用给的都是整套主题; 值不对会抛TypeError, 不认识的键被忽略, 日志里打一条警告.- 声明了
"desktop": true的系统应用拿到apps()、setDoubleClick、setFrameTheme, 以及notification、download和edge事件;pin、screenshot和shortcut只给桌面页面.
见 桌面.
acde:permissions
acde:permissions 一节的链接shell 模块: 批准提示, 以及对它们作出的决定.
interface AcdePermissions { pending(): Promise<PermissionPrompt[]> answer(id: number, allow: boolean): Promise<void> list(app?: string): Promise<PermissionDecision[]> revoke(app: string, capability: string): Promise<boolean> on(type: 'prompt', handler: (event: PermissionPrompt & { type: 'permissionprompt' }) => void): () => boolean on(type: 'answered', handler: (event: { type: 'permissionanswered'; id: number; app: string; capability: string; allowed: boolean }) => void): () => boolean}
interface PermissionPrompt { id: number app: string label: string capability: string reason: 'request'}
interface PermissionDecision { app: string label: string | null capability: string decision: 'granted' | 'denied' folder?: { label: string; exists: boolean }}提示的 capability 是 camera、microphone 或 idleDetection, 只有这几个能力会问用户; 在决定里还可以是 fs.folder-…, 即用户为这个应用选中的文件夹 (带 folder). 没有决定时 revoke resolve 成 false. 每个提示都在第一次使用时提出, reason: 'request'. 见 桌面.
acde:inspect
acde:inspect 一节的链接shell 模块, 也以 ctx.inspect 给桌面服务. 把屏幕变成文字的语义树, 并按 ref 操作; 给 AI agent 用. acdev inspect / acdev act 和 MCP 用的就是它.
interface AcdeInspect { snapshot(options?: { window?: string; ref?: string; all?: boolean; diff?: boolean limit?: number; find?: string; tree?: boolean; offscreen?: boolean }): Promise<{ text: string; windows: InspectWindow[]; trees: Record<string, InspectNode[]> }> act(ref: string, action: InspectAction, arg?: string | number | readonly string[] | null): Promise<{ ok: boolean; text: string }> run(steps: readonly { ref: string; action: InspectAction; text?: InspectArg }[]): Promise<{ ok: boolean; text: string }> open(name: string): Promise<{ ok: boolean; text: string }> query(options: { selector: string; window?: string; ref?: string; limit?: number; attributes?: readonly string[] }): Promise<{ window: string; count: number; nodes: InspectMatch[] }>}
type InspectAction = 'click' | 'double' | 'right' | 'hover' | 'drag' | 'type' | 'settext' | 'select' | 'key' | 'scroll' | 'focus' | 'close' | 'minimize' | 'restore' | 'fill' | 'fullscreen'窗口 ref 是 w0 (桌面)、w1 ……, 元素 ref 是 w3.12. 文字形式一行一个节点:
- button "新建文件夹" [pressed] [w1.52]acde:office
acde:office 一节的链接仅 Linux. 办公文档 (文字、表格、演示) 的编辑服务, 给 Dopame 自带的办公应用用; 接口还可能变化.