AIO 设备助手 / AIO Device Companion

统一管理设备连接、任务执行和本机授权，包含文件同步、Finder 云端取回、磁盘扫描、加密归档、终端、桌面、剪切板、ADB 和技能同步。所有功能保留在同一插件仓库，对外只使用 aio device …。

宿主提供可信 HTTPS 局域网入口时，设备自动优先经局域网进行同步、归档、任务和 Codex 通信；不可达时回退公网。已有配对无需重做。网络选择及请求不重放规则见 传输说明。

Bidirectional file and folder sync, Finder status badges and cloud recovery, local disk scanning, Cargo cache cleanup, encrypted archives, a web terminal, and app-window remote control. Distributed through the AIO CLI plugin marketplace and run on each computer you want to manage.

安装 / Installation

npm install -g @zjarlin/aio
# macOS
brew install restic
# Linux 请安装 restic、openssh-client、lsof 和 coreutils
# On Linux install restic, openssh-client, lsof and coreutils

@zjarlin/aio 随包安装设备组件，无需再单独安装或使用第二个 CLI。临时运行可使用 npx -y @zjarlin/aio device --help。从 AIO 插件市场安装“设备助手”可固定组件版本并分发随包技能。源码开发执行 npm ci && npm run build，再通过统一入口加载该组件。

The AIO CLI bundles Device Companion. Use aio device or npx -y @zjarlin/aio device; a second global CLI is not required. The marketplace installs an exact component version and its bundled skill.

配对并使用 / Pairing & Usage

插件已统一为 aio-plugin-device。已有设备安装新版 @zjarlin/aio 后执行 aio device worker --background，沿用原配对，不要重新执行 connect。持久化目录 ~/.config/aio-space、AIO_SPACE_CONFIG_DIR、归档标签、Finder bundle/URL 标识及后台服务名保持不变，避免遗失历史、重复 worker 或重置系统授权。

aio device connect

浏览器打开 AIO，使用已有注册账号登录，点击“授权这台设备”。配对完成后 worker 自动常驻后台，并自动开启远程终端与桌面控制能力；关闭终端仍在线。macOS 使用用户 LaunchAgent，Linux 使用用户 systemd；用户未登录时 Linux 是否继续运行由系统 linger 配置决定。

Open AIO in a browser, log in with an existing registered account and click “授权这台设备” (Authorize this device). After pairing, the worker stays resident in the background automatically — it stays online even after the terminal closes. macOS uses a user LaunchAgent, Linux a user systemd; whether Linux keeps running when the user is logged out is decided by the system linger configuration. 屏幕锁定但系统未睡眠时，macOS LaunchAgent 通常继续运行，worker 会继续心跳和接收任务；合盖休眠、系统睡眠或用户注销后进程被挂起或不存在，设备会显示离线。锁屏本身不等于离线。

“我的设备”负责设备配对。文件同步由设备助手插件接管；macOS 菜单栏和 Finder 显示同步状态，扫描、归档与恢复通过下方 CLI 命令执行。不需要配置 SSH、远端目录或归档密码；数据归属当前账号及工作区。用户登录密码不进入 worker，不用作归档加密密钥；设备撤销不会删除归档。

“我的设备” (My Devices) handles pairing. Device Companion manages file sync; its macOS menu bar app and Finder show status, while the CLI below provides scanning, archives and recovery. No SSH, remote directory or archive password configuration is needed. Data belongs to the current account and workspace; the login password never enters the worker or becomes an archive key. Revoking a device does not delete archives.

macOS 客户端支持启动已安装的应用。通过 aio device desktop-enable 启用应用控制后，Agent 可提交 desktop.open-app 任务，例如打开 Postman。客户端只接受应用名称或 bundle ID，不接受命令、路径或启动参数；只有核对到应用真实进程后才报告成功。旧设备升级后沿用原配对，应用控制单独启用。

The macOS client can launch installed apps. After aio device desktop-enable, the Agent can submit desktop.open-app tasks, e.g. opening Postman. The client accepts only an app name or bundle ID and reports success only after matching the app's real process. Upgraded devices keep their existing pairing; app control is enabled separately. 网页终端使用 PTY 运行当前用户的登录 shell，不受 --root 工作区目录限制；配对、升级或后台 worker 启动时会自动配置。AIO 站内插件工作台还提供基于截图和最新观察凭据的应用窗口远程控制；它不是 VNC 或全屏系统串流。

自建 AIO 使用 aio device connect --server https://your-aio.example。需要限定本机目录时加 --root /path/to/workspace，默认当前用户目录。已有配对使用 aio device worker 在前台运行；调试配对可加 --foreground。

Self-hosted AIO uses aio device connect --server https://your-aio.example. Add --root /path/to/workspace to restrict local directories (default: the current user's home). An existing pairing runs in the foreground with aio device worker; add --foreground for debugging pairing.

archive 保留原件，清理只作用于明确选中的 Cargo target。归档由 restic 加密和去重；AIO 托管仓库密钥，并通过设备凭据控制访问。恢复必须使用新目录，完成后校验内容。管理员需备份服务端归档目录、worker_vaults 和宿主 keyring。

archive keeps originals; cleanup only affects explicitly selected Cargo targets. Archives are encrypted and deduplicated by restic; AIO hosts the repository key and controls access via device credentials. Restore must use a new directory and verifies content on completion. Administrators must back up the server-side archive directory, worker_vaults and the host keyring.

原先的独立 CLI 高级命令仍可通过 --help 查看。配对后优先使用 AIO 归档，旧手工仓库的数据不会自动删除或迁移。

The original standalone CLI advanced commands remain available via --help. After pairing, AIO archives take priority; old manual repository data is neither auto-deleted nor migrated.

worker 凭据经 AES-256-GCM 加密后保存到 ~/.config/aio-space/worker.json；本机密钥 .worker-key 与状态文件权限均为 0600。旧配置第一次读取时原地迁移，无需重新配对。密钥不使用用户密码；需同时保护状态目录和密钥文件，拥有整个本机账号权限的人仍可解密。macOS 后台日志位于同目录 worker.log。服务仅执行固定能力，不接受任意 shell/代码；网络中断后重连，租约丢失时终止子进程并让平台标记任务结果待确认，不自动重放删除操作。

Worker credentials are AES-256-GCM encrypted into ~/.config/aio-space/worker.json; the local key .worker-key and state files are 0600. Old configs migrate in place on first read — no re-pairing needed. The key does not use the user password; protect both the state directory and key file, since anyone with full local-account rights can still decrypt. macOS background logs live in worker.log in the same directory. The service only executes fixed capabilities and accepts no arbitrary shell/code; it reconnects after network loss, terminates child processes and has the platform mark results as pending when a lease is lost, and never auto-replays deletions.

开发和发布 / Development & Publishing

npm ci
npm run typecheck
npm test
npm pack --dry-run

测试使用临时目录和真实 restic 本地仓库，不触及用户数据；需先安装 restic、du、lsof。自动发布和 AIO 市场同步见 AIO.md。

Tests use temp directories and a real local restic repository, never touching user data; install restic, du and lsof first. Auto-publishing and AIO marketplace sync are documented in AIO.md.

Skill 双向同步 / Skill Two-Way Sync

已配对设备可沿用 AIO 账号：

Paired devices can reuse the AIO account:

aio device skills-enable --path ~/.agents/skills
aio device skills-sync
aio device skills-disable

开启后后台每 30 秒与 AIO 智能体技能库同步。网页入口「智能体 → Skill 管理」。 设备只访问当前租户已启用并声明 skills.sync 的服务；多个服务时使用 --service ID 明确选择。 同步正文、脚本和图片资源，不执行脚本。隐藏文件、Git、缓存、凭据与链接不进入同步。 单文件最大 2 MiB；云端个人库最大 32 MiB / 4096 文件。 两端同时修改时显示冲突，网页选择保留本机或云端后下一轮处理；过期选择不能覆盖新修改。 覆盖和删除前备份到私有状态目录 skills-sync/<绑定>/backups，云端保留加密历史。 删除会双向传播，重新放回备份文件即可恢复同步。关闭同步或撤销设备后不再传输。

Once enabled, the background syncs with the AIO Agent skill library every 30 seconds. Web entry: 「智能体 → Skill 管理」 (Agent → Skill Management). Devices only access services that the current tenant has enabled and that declare skills.sync; use --service ID to pick explicitly when several exist. Bodies, scripts and image assets sync; scripts never execute. Hidden files, Git, caches, credentials and links never sync. A single file caps at 2 MiB; the cloud personal library caps at 32 MiB / 4096 files. Concurrent edits on both sides show a conflict; after choosing keep-local or keep-cloud on the web, the next round processes it, and stale choices cannot overwrite newer changes. Overwrites and deletions are backed up first to the private state directory skills-sync/<binding>/backups, and the cloud keeps encrypted history. Deletions propagate both ways; putting a backup file back restores sync. After disabling sync or revoking the device, transfer stops.

长期在线与网络恢复 / Long-Lived Online & Network Recovery

一次性配对码只用于首次授权；授权后的设备凭据长期有效，直到撤销设备或停用账号。不要用配对码维持在线。 Worker 主动发起 HTTPS 长轮询，每次最多等待 25 秒，收到任务立即续接；独立设备心跳为 15 秒，任务租约每 20 秒续约。NAT 后的客户端不需要开放端口、公网地址或 WebSocket Upgrade。

The one-time pairing code is only for initial authorization; authorized device credentials stay valid until the device is revoked or the account disabled. Do not keep the device online with a pairing code. The worker initiates HTTPS long-polling itself, waiting at most 25 seconds per request and immediately picking up tasks; standalone device heartbeats are 15 seconds and task leases renew every 20 seconds. NAT'd clients need no open ports, public addresses or WebSocket Upgrade.

短暂断网、连接重置、服务器重启会按 1～30 秒带抖动的指数退避自动重连。任务领取 ID 和完成结果保存到加密日志，丢失回执时重传相同请求；进程崩溃或租约失效后不自动重做有副作用的任务。超过 110 秒未确认续约会停止受控子进程。已经发生的外部副作用无法撤回，需在 AIO 检查“结果待确认”的任务。本机无法提交的记录保留为 unreported-<任务ID>.json。

Brief outages, connection resets and server restarts auto-reconnect with jittered exponential backoff of 1–30 seconds. Task claim IDs and completion results are stored in encrypted logs; a lost receipt retransmits the same request. After a process crash or lease expiry, side-effecting tasks are not auto-redone. A lease unconfirmed for over 110 seconds stops controlled child processes. External side effects that already happened cannot be undone; check “结果待确认” (result pending confirmation) tasks in AIO. Records that cannot be submitted locally are kept as unreported-<任务ID>.json.

网络必须允许访问 AIO 的 HTTPS 出站。可设置 HTTPS_PROXY、HTTP_PROXY、NO_PROXY，企业证书使用 NODE_EXTRA_CA_CERTS；后台服务安装时会保留这些环境变量。禁止全部出站的防火墙不能凭协议绕过，解除阻断后自动恢复。TLS 校验始终开启。 升级 CLI 或修改代理后执行 aio device worker --background 更新后台程序，沿用已有设备授权。 后台服务使用已安装包的真实入口及其依赖目录；请保留安装目录，长期运行建议全局安装 CLI，升级后重新执行上述命令。

Network must allow HTTPS outbound to AIO. HTTPS_PROXY, HTTP_PROXY and NO_PROXY are supported; enterprise certificates use NODE_EXTRA_CA_CERTS; the background service install preserves these environment variables. A firewall blocking all outbound traffic cannot be bypassed by protocol — recovery is automatic once the block is lifted. TLS verification is always on. After upgrading the CLI or changing proxies, run aio device worker --background to update the background program, reusing the existing device authorization.

协议故障测试在 test/channel.test.mjs，包括响应丢失、代理拒绝、服务端重启、进程崩溃、重复进程、短暂续约失败、持续失联超过租约预算和退出中断。npm test 约需 2.5 分钟，其中租约测试使用真实计时。

Protocol fault tests live in test/channel.test.mjs, covering lost responses, proxy rejection, server restarts, process crashes, duplicate processes, short lease failures, sustained disconnects beyond the lease budget and exit interruption. npm test takes about 2.5 minutes; lease tests use real timing.

Finder 文件与文件夹双向同步

已配对的设备沿用当前 AIO 账号授权。文件保留原位置；家目录在展示中写作 ~，跨设备按各自家目录映射，不要求用户名相同。

aio device config-add --path "$HOME/Documents/notes"
aio device config-add --path "$HOME/.add_fn"
aio device shell-sync
aio device finder-install
aio device worker --background

macOS 在 Finder 扩展设置中启用 AIO Device 后，右键文件或文件夹可选“纳入 AIO 双向同步”“退出 AIO 双向同步”“释放本地空间”“下载回本机”。已同步显示绿色对勾，待同步显示蓝色箭头，后台状态过期显示橙色暂停，错误显示红色提示，释放后显示云图标。文件夹包含空目录以及各设备后续新增的文件。退出同步只暂停本机，不删除文件或云端版本。

小型 UTF-8 文本使用 Yjs CRDT，保存操作身份并合并离线编辑；不再为 .add_fn 拆分 alias、函数或生成额外 shell 入口。JSON 和 shell 配置在写回前检查语法。旧正文迁移必须与本机规范化后的内容一致；首次同名文件不一致时保留本机副本并报告。CRDT 保证数据收敛，不保证并发修改后的脚本业务含义正确。

二进制及首次登记超过 128 KiB 的文件使用 restic 加密、去重归档；Yjs 同步不可变版本引用，并发版本均保留。确定性选择一个版本用于本机呈现，不合并二进制字节。归档版本可通过 archive-list 和 archive-restore 取回；同步状态与云端历史加密保存。文本 CRDT 编码历史上限 256 KiB，超过时保留原件并报告。

“释放本地空间”先完成同步、归档、远端恢复和 SHA-256 校验，再移除本机正文，留下同目录的 原文件名.aio-cloud 引用。文件仍打开或校验期间变化时拒绝释放。右键此引用或其文件夹“下载回本机”会取回当前云端版本；下载期间不覆盖新出现的本机文件。引用是显式恢复入口，不是 macOS File Provider 占位文件，不支持双击自动下载。退出同步前请先取回需要保留的云端文件。

aio device config-release --path "$HOME/Documents/notes"
aio device config-download --path "$HOME/Documents/notes"
aio device config-remove --path "$HOME/Documents/notes"

家目录外显式登记的路径在源设备保留原位置，其他设备默认落在 ~/AIO Sync/External/<标识>/。普通文件不限制扩展名；目录递归跳过 Git、依赖、构建目录、内部同步状态和链接，最多登记 4096 项。显式软链接仅支持指向家目录内的小型文本，并固定校验目标；不能释放软链接入口。已打开的数据库应先关闭再释放，文件同步不提供应用事务级快照。

Finder 扩展从随包源码在本机通过 Xcode Command Line Tools 编译；可用 AIO_FINDER_SIGN_IDENTITY 指定签名身份，默认本机 ad-hoc 签名。宿主须提供 /personal-config/protocol；旧客户端遇到 CRDT 条目会被要求升级，避免把编码状态误写成文件正文。

安装后 AIO Device 登录时自动在菜单栏常驻，不显示 Dock 图标，也不自动弹出窗口。菜单栏和 Finder 的“查看同步状态”可查看每个文件的同步结果及最近检查时间；家目录显示为 ~。关闭状态窗口或退出菜单栏不会停止独立的后台同步服务。Finder 的勾选表示已纳入同步，状态文字及徽标分别表示已同步、等待同步、仅云端或同步异常；超过一分钟未收到后台状态会明确显示“后台状态已过期”，保留最近检查时间，不把旧记录显示成正在传输。

排查长时间等待时，先确认后台服务实际使用的配置目录、设备配对和最近报告，再检查具体文件。自定义 AIO_SPACE_CONFIG_DIR 使用独立的后台服务名称，不会替换默认服务。本机测试配对必须指定独立配置目录；默认设备重新连接时复用仍有效的配对，保留已有同步历史。没有变化的文本文件在云端版本、本机内容和执行权限均匹配时跳过正文下载及状态重写。

多个 Finder 扩展监控同一目录时，macOS 可能只展示其中一个扩展的徽标；这不代表文件停止同步。菜单栏状态窗口独立于 Finder 徽标，始终可查看后台报告。安装程序保留其他扩展的启用设置。

在网页使用设备助手 / Device Workbench

装配 web-client 的 AIO 网站在「工作空间 → 设备助手」提供云端文件、远程终端、远程桌面和 ADB 管理页面。页面只接受本插件固定的设备动作，身份仍来自当前 AIO 会话；设备配对或后台服务重启时会自动同步终端和桌面能力。站内入口随 AIO Web 发布，CLI 的 npm 安装不会自动更新站点。

本机也可打开独立核验页：

aio device config-web
# 不自动打开浏览器，打印本机会话地址
aio device config-web --no-browser

保持终端运行，在网页按路径搜索并刷新云端文件清单，查看云端版本、更新时间及各设备最近同步报告。关闭终端或按 Ctrl+C 结束网页服务。页面只在 127.0.0.1 的随机端口和会话路径开放；每次刷新直接读取 AIO 云端元数据，不显示文件正文或设备凭据，不提供删除或覆盖操作。

“云端已有版本”证明服务器保存了条目，不表示本机当前内容已核验一致。页面标明同步载荷的大小和摘要，它们不是原文件大小或文件 SHA-256。设备报告过期表示最近结果无法确认，不能据此推断设备在线。本机 config-web 仍只提供只读核验；终端、远程桌面、ADB 管理和设备任务只存在于 AIO 站内 设备助手插件页面。

旧版个人配置模式（0.6）

以下环境变量、函数清单与 chezmoi 功能适用于旧版配置模式。新的 config-enable 默认登记 ~/.add_fn 并切换到上述文件模式；旧模式中的其他配置不会自动登记到新模式。

在 MacBook Pro、Mac mini 分别用同一 AIO 租户下的账号配对，再启用同步。配置独立于智能体，不调用模型。

aio device connect
aio device config-enable
aio device config-import --preview       # 检查 chezmoi 已管理文件
aio device config-import                 # 导入当前生效文件，不改 chezmoi 源仓库
aio device config-add --path ~/.gitconfig
aio device command-add --name doubao --bundle com.bot.pc.doubao
aio device env-set --name EDITOR --value vim
aio device env-set --name PATH --value '["{{aio.home}}/.local/bin"]'
aio device function-set --name where_aio --value "printf '%s\\n' '{{aio.home}}'"
aio device config-status

AIO 账号菜单“个人配置”管理配置文件、环境变量、应用命令、个人资源和同步设备；支持编辑、删除、最近十版恢复及冲突选择。共享配置可用 --layer os:darwin 或 --layer device:设备ID 覆盖。最高层完整覆盖同名文件/变量，删除覆盖项会隐藏该项，不会自动回落。

文件监听通常在修改稳定 250ms 后唤醒同步；云端出站 HTTPS 长轮询最长 25 秒，每秒检查变更。无需本机监听端口或 NAT 端口映射，断网后自动重连、重新合并。代理需要允许访问 AIO 的出站 HTTPS；全断网期间无法实时同步。代理 403 与设备授权撤销分别处理。

文本三方合并，JSON/JSONC 按键合并并保留本地注释。同一处并发修改保留冲突，不写冲突标记进文件。符号链接、硬链接和路径穿越不写入；配置先备份再原子替换。云端正文与历史、客户端基线均加密，备份目录仅当前用户可读。首次同名文件不同不自动覆盖，需要在网页选择版本。

环境变量保存在 ~/.config/aio-space/environment.json，可在本机直接编辑后双向同步；只同步此文件登记的变量，不上传所有进程环境。PATH 是附加目录数组。新终端自动加载，已有终端可执行 source ~/.config/aio-space/environment.sh。外部 worker 无法修改已经运行的父进程环境。生成脚本不执行变量中的 $()、反引号等内容。{{aio.home}} 在各设备展开为自己的主目录。

Bash 函数保存在 ~/.config/aio-space/functions.json，格式为 {"where_aio":"printf '%s\\n' '{{aio.home}}'"}，值只填函数体，不包含函数名和外层大括号。也可在网页“个人配置 → Bash 函数”编辑，或运行 aio device function-set --name where_aio --value "printf '%s\\n' '{{aio.home}}'"。清单更改经文件监听和 HTTPS 长轮询双向同步；functions.bash 由 worker 语法检查后生成，并由新启动的 Bash 从 .bashrc（已有 .bash_profile 也会接入）加载。既有 shell 会话不会被远程修改；运行 source ~/.config/aio-space/functions.bash 可在当前 Bash 加载。Bash 函数本质上是用户代码，调用时拥有当前本机账号权限；不要同步不可信来源的函数体。函数不自动导入 .bashrc、进程变量或凭据，且不会在 zsh 或 Windows PowerShell 中运行。对同名函数的并发编辑保留冲突，由网页明确选择版本。

应用命令目前支持 macOS bundle ID，生成固定的 open -b 包装脚本；可以继续传入 . 或路径。应用需已安装。已有同名脚本会阻止接管，确需替换时加 --adopt，原脚本先备份。使用 CLI/网页修改命令定义；手工改生成脚本会报告冲突，不会被无声覆盖。

首次导入将 Library/ 配置设为 macOS 层、.config/shell/local.* 设为当前设备层，其余使用指定层。排除 GitHub CLI / Docker 登录凭据、Skill、缓存、会话凭据、私钥、数据库和无效/二进制文件。Skill 继续使用独立的 skills-enable。AIO 与 chezmoi 不应持续同时自动 apply 同一文件；导入后可保留 chezmoi 源仓库作为备份。config-disable 停止同步并保留本机现有配置。

安装包和杂物使用个人资源库：

aio device asset-add --path ~/Downloads/example.dmg
aio device asset-get --id 资源ID --to ~/Downloads/restored-example

复用 AIO 托管的 restic 加密归档、去重和校验，原件保留，不自动运行安装包；恢复目标必须不存在，并保留原始路径层级。网页可选择自己的其他设备发起恢复，在“我的设备”看任务结果。删除资源目录记录不删除远端快照。

本机工作区与蜂群执行

已配对的 macOS/Linux 设备可以显式登记项目，让 AIO 在一个任务内并行执行独立工作区的 Git 查询、文件读写、构建和测试：

aio device workspace-add --name app --path /path/to/project
# 以下操作会授权写入与指定项目命令；命令清单须放在项目外并 chmod 600
# commands.json: {"build":{"command":"npm","args":["run","build"],"timeoutMs":120000}}
aio device workspace-add --name app --path /path/to/project --execute --manifest /private/path/commands.json
aio device workspace-list
aio device workspace-remove --name app
aio device workspace-disable

只读为默认值。最多 8 个作业、3 个独立工作区同时执行，同根及父子目录串行；一个失败不取消其他作业。文件限制为 32 KiB UTF-8 文本，写入要求先读取取得 hash 并使用 CAS，覆盖前备份。隐藏文件、凭据目录及链接拒绝访问。远程只发送本机登记的 ID/命令名，不接受任意路径、shell、argv 或环境变量。授权项目命令以当前用户权限运行，不是操作系统沙箱。退出码、超时、取消、输出截断均出现在各作业回执中；每项输出限制 16 KiB。正常退出、超时和取消会清理同组后代进程。

本机授权保存在私有状态目录的 workspaces.json，每个作业启动前重读；移除会阻止后续作业，正在运行的作业需取消其任务。注册自动同步设备能力，最后移除自动关闭；网络失败后可执行 workspace-enable / workspace-disable 重试。现有设备升级后沿用配对；升级程序后用 aio device worker --background 更新后台入口。完整协议、manifest 和边界说明见 工作区说明。

桌面操作 / Desktop control

配对和后台服务启动会自动开启原生桌面观察与输入；desktop-status 查看本机开关，desktop-disable 可显式关闭且不会被自动配置重新打开。需要macOS 辅助功能与录屏权限；桌面授权覆盖当前账号的桌面操作，不受工作区目录授权限制。当前 macOS 已实测通过 worker 生成、保存并在 WPS 打开 XLSX，画面显示“小明/18”；WPS 首页点击兼容性及其他平台仍待验收。源代码中的 src/desktop/README.md 记录协议与生命周期。

远程终端 / Remote terminal

配对和后台服务启动会自动开启浏览器远程终端；terminal-status 查看本机开关，terminal-disable 可显式关闭且不会被自动配置重新打开。打开 AIO 的“设备助手 → 远程终端”选择设备连接即可获得交互式 shell；关闭浏览器标签页或点击“断开”会结束会话。终端以当前操作系统用户的登录 shell 运行，不受 --root 工作区目录限制，等同于在锁屏计算机上直接操作，请只在可信设备上开启。设备离线、休眠或断网时无法连接，仅锁屏不影响会话。源代码中的 src/terminal/pty.ts 记录协议与生命周期。

Android TV ADB 管理 / Android TV ADB control

在同一局域网的 macOS/Linux 主机安装 Android 平台工具（adb 命令），配对并保持 worker 在线。AIO 的「设备助手 → ADB 管理」可以选择该主机，发现或无线连接 Android TV，并使用遥控按键、文字、应用管理、日志、截图、文件传输和 APK 安装。普通 ADB 管理需要在该主机运行 aio device adb-enable 显式开启，之后只提交固定动作和受限参数。

原始 ADB Shell 默认关闭，必须在该主机的本地终端显式运行 aio device adb-shell-enable；adb-shell-status 查看，adb-shell-disable 立即关闭。网页不能远程开启此权限。APK、推送和拉取路径仍受 --root 授权目录约束；设备端 Shell 命令只应在已授权的 Android 设备上使用。

剪切板接力 / Clipboard relay

同一账号下已配对并开启通道的设备共享一个剪切板槽位：在任一设备的「设备助手 → 剪切板接力」发送文本、图片或任意二进制，其他设备可以在页面预览、下载，或把条目投递到指定设备的本机剪切板。文本与二进制共用同一通道，图片按原始字节传输，不经过 UTF-8 转码。

在目标设备的本机终端显式开启通道：

aio device clipboard-enable
aio device clipboard-status
aio device clipboard-disable

• clipboard-enable 先向宿主申请 clipboard.sync，成功后才在本机写入开关；clipboard-disable 先关闭本机开关再撤销授权，网络失败也不会继续读写剪切板。
• 只有在设备本机开启后，网页才能把条目投递到该设备；网页侧只能停用，不能远程开启。投递任务只携带条目 ID，设备凭自身通道拉取加密正文，因此图片和二进制不受任务输入配额限制。
• 开启通道的设备会参与自动接力：本机剪切板内容变化时上传，云端出现新条目时写回本机。为避免回读自己刚写入的内容造成重复上传，进程内记录最近应用的条目摘要。macOS 使用 pbpaste/pbcopy 与 osascript 处理文本和图片；Linux 依次尝试 wl-clipboard 和 xclip，未安装时视为本机不支持，不会中断其他能力。
• 内容按用户加密存储，单个用户保留最近 64 条，单条上限 8 MiB；超限或非 UTF-8 文本会被拒绝。撤销配对或账号停用后，设备的剪切板请求立即失效。

在 AIO 网页使用原版 Codex

通过 Codex Buddy 打开已安装的 Codex，然后在原已配对设备运行 aio device codex-enable，到 AIO 的 Codex Buddy 插件选择在线设备。默认不开通，无需重新配对。aio device codex-status 查询本地授权；aio device codex-disable 关闭本地授权并撤销平台能力。

Mac 默认读取标准 Codex 安装目录；自定义位置或其他系统用 --asar /path/to/resources/app.asar，运行时描述可用 --descriptor /path/to/desktop-runtime-v1.json。这些路径只在设备保存，网页不接收设备票据。设备必须持续运行支持 WEB 发现接口的 Buddy，服务器须支持 codex.web 设备视图和 WebSocket Upgrade。

每次连接网页重新发现当前 Buddy 端口和安装资源。Buddy 重启或更新后可直接重新连接，无需重启设备 worker；已经提交的操作不重放。

执行发生在所选设备及原生 Host，使用原版 UI、会话和工具；断线后的操作结果需要回原会话确认，不会自动重发。设备助手 0.12.2 支持网页文件选择、文件拖入、文件粘贴，以及配套 AIO 宿主 2026.10.11 中的目录拖入。目录保留相对层级和空目录，全部文件完整写入设备后才将根路径交给原版界面。取消或断线清理未交付目录及其中的子文件，已交付内容保留在系统临时目录供任务继续读取；单文件最多 128 MiB，每个视图最多 512 MiB、4096 个文件和目录项，相对路径最多 32 层。网页沿用原版浏览器菜单与链接拖拽分支；原版菜单、文件拖出及 Electron 嵌套 webview 仍需继续接入或验收，官方更新后仍需桥接兼容性验收。详见 src/codex/README.md。