# Tapilot 官方接入说明

更新日期：2026-11-06

请帮我将 Tapilot 接入当前 AI 客户端。先读取 https://tapilot.lifeos.md/install/agent.zh.md 。识别实际宿主及执行环境的操作系统、架构；宿主无法确认时只问一次。只安装我选择的客户端。检查并复用已有安装，保留配置和手机配对。只下载适合环境的官方包，校验 SHA-256，使用现有安装器及返回的实际 launcher、skillFolder、pluginDirectory，不要索要开发者源码目录。优先打开会话原生面板或内置浏览器侧栏。需要导入 Skill、启用连接器或确认权限时，只给出当前一步的具体操作，必要时等我完成后继续。需要时引导手机配对，不擅自切换已有设备。首次验证只读取当前屏幕，不点击、不输入、不改变设置。实际读取截图，并保留实时面板让我核对。分别报告安装、协议检查、宿主面板和手机读取的结果，不用一句“已经打开”代替实际画面验收。未完成项保留 manual/not_tested 状态。工具不足或平台不支持时，说明具体限制并提供官方手动接入方式。不要进行 Cursor 原生测试。

## 开始安装（无需预装 Skill）

读取 https://tapilot.lifeos.md/releases/clients/latest.json 。仅当 status 为 published，且有 HTTPS 下载地址、SHA-256 和文件大小时，才可下载。已发布接入包：macOS Apple Silicon、macOS Intel、Windows x64、Windows ARM64、Linux x64、Linux ARM64。安装生命周期已通过 CI 验证；客户端在各系统上的可用性、原生面板和真机读屏需分别确认。 按清单 artifacts 中的 platform 和 arch 精确选择，不要仅使用顶层兼容字段。没有匹配包就停止自动安装，转到 https://tapilot.lifeos.md/zh/install。远程 DSH 必须匹配运行 DSH 的主机。Linux 验证环境为 Ubuntu 24.04；Windows 验证环境为 Windows Server 2025 x64 和 Windows 11 ARM64，不代表所有发行版或普通用户会话均已验收。 Codex 走下方原生插件路线。

自动接入需要读取网页、下载文件、执行本地命令及读取图片。无法读取网页时，请用户从手动入口复制这份说明；无法执行本地命令时，由用户运行安装器。不要把只有 MCP 的宿主说成能自动完成本地安装。

1. 根据当前会话证据识别宿主，通过本地工具检查操作系统和架构。用户已选目标时不重复询问；无法确定时只问一次。不批量安装检测到的客户端。
2. 检查所选客户端的已有安装，优先复用实际启动器进行诊断。保留配置、用户修改过的 Skill、手机配对、隐私暂停状态及 DSH_HOME。不通过卸载或强制覆盖来解决冲突。
3. 将清单中匹配的包下载到新的临时目录，核对完整文件大小及 SHA-256（macOS 用 shasum -a 256，Linux 用 sha256sum，Windows PowerShell 用 Get-FileHash -Algorithm SHA256）。不一致则停止。校验后解压；包内自带 Node 和依赖，不需要 npm install，也不需要先装 Skill。
4. 在解压后的接入包目录，POSIX 用 ./bin/node，Windows PowerShell 用 & .\bin\node.exe；以下 bin/node 表示对应系统入口。以 bin/node runtime/server/cli.mjs detect 收集只读证据，再执行 bin/node runtime/server/cli.mjs onboard --client NAME，仅传下方所选客户端 ID。路径使用参数数组或正确的 shell 引号。手动方式：macOS 双击 Install Tapilot.command，Windows 运行 Install Tapilot.cmd，Linux 运行 sh install-tapilot.sh 并选择一个客户端；该向导的可选参数是客户端 ID 本身，不接受 --client。
5. 消费 JSON 返回值中的 launcher.command、launcher.args、skillFolder、pluginDirectory 和 onboarding.checks，不猜路径。一次说明一个手动步骤，必要时等用户完成再继续。需要重载或新会话时明确说明，不把未完成状态记作成功。
6. 用同一安装后 CLI 执行 doctor --client NAME，再从返回的 skillFolder 读取产品 Skill。Codex 读取原生插件附带的 Skill。安装和协议检查不证明原生面板或手机读取已成功。

## 客户端步骤与实测边界

### WorkBuddy（ID：workbuddy）

内置浏览器侧栏；MCP 预览只读。

安装器合并本地 MCP 配置并链接 Skill。在客户端信任、启用 Tapilot，再新建任务。手机操作使用 Skill CLI。

中英文真实会话和浏览器侧栏已实测；MCP 面板仍待原生验收。

### Doubao Work / 豆包工作（ID：doubao）

内置浏览器侧栏；MCP 面板稳定性仍待验收。

用返回的 launcher.command 和 launcher.args 添加自定义 STDIO 连接器，导入 skillFolder，启用两者并开始本地电脑任务。个人用户即可完成，无需企业资质。更新后可能需要重新导入 Skill。

英文真实会话和浏览器侧栏已实测；完整中文案例及 MCP 面板稳定性待验收。

### Cherry Studio（ID：cherry）

桌面 Work Agent 会话内置浏览器；无需添加 Tapilot MCP。

设置 → 技能 → 添加技能 → 本地导入，选择返回的 skillFolder。全局启用并绑定到 Work Agent，开启 Shell、图片读取和 Browser 工具。Skill 更新后重新导入。

中英文真实会话、截图读取和浏览器侧栏已实测。普通对话、移动端及桌面 MCP Apps 不属于这条路线。

### DSH Web（ID：dsh）

从会话标题处打开 Tapilot 原生右侧栏。

在运行 DSH 的主机安装（>=0.2.1-rc.5 <0.3.0-0），保留已有 DSH_HOME。执行安装器根据 pluginDirectory 生成的注册命令，重载 Web，再从会话标题打开 Tapilot。远程 Linux 主机不能使用 macOS 包。

中英文真实会话和原生侧栏已实测。DSH Go 是另一条路线，尚未通过原生验收。

### Codex（ID：codex）

已有 Tapilot 原生插件的会话面板。

复用原生插件，不添加重复 MCP 或 Skill。本地市场命令须在含 .claude-plugin/marketplace.json 的仓库根目录执行：codex plugin marketplace add .，然后 codex plugin add tapilot@tapilot-local。统一接入包不是这个仓库。公开插件分发入口仍待完善；可复用已有安装，否则明确报告限制。

保留原生插件路线；本轮未重新完成原生客户端完整验收。

### VS Code Copilot（ID：vscode）

Copilot MCP App 面板，待原生验收。

安装器合并 MCP 配置并链接 Skill。信任、启动 Tapilot 并启用 Skill，在已登录的 Copilot Agent 模式中新开会话。

配置和协议检查已覆盖；原生会话与实际面板仍待验收。

### Other agents / 其他客户端（ID：skill）

Skill + CLI；不保证会话内嵌面板。

需要本地命令与图片读取能力，通过宿主的 Skill 机制导入返回的 skillFolder。只有 MCP 的宿主需要外部安装或支持的市场入口，一段提示词不能补出缺失的本地执行工具。

需逐个宿主验收；本次不进行 Cursor 原生测试。

## 配对与首次只读验证

按照导出 Skill 中的真实 CLI 入口执行，不猜全局命令。先运行 devices 和 status，保留当前选中的手机。没有合适的已配对手机时，引导用户按 https://tapilot.lifeos.md/zh/guide/start 安装手机端，开启无线控制，再用手机 Tapilot 内的扫码入口扫描配对页二维码。不要在聊天中索取配对密钥，也不要代用户确认。不能抢占其他控制器正在使用的手机，不能擅自恢复隐私暂停或切换设备。

优先使用原生面板。WorkBuddy 和豆包的 MCP 面板恢复一次仍失败时，改用宿主内置浏览器侧栏；Cherry 使用桌面 Work Agent 浏览器。运行 CLI preview 时不加 --open，通过宿主浏览器打开返回的完整地址，保留用于授权的 URL fragment，但不能把 fragment 输出到聊天或日志。独立系统浏览器只是回退，不算会话内面板验收。

用 CLI 获取新截图，并通过图片工具实际读图，描述可见内容，与面板中的真实像素核对。缺少任何工具就标明该项未验证。保留实时面板供用户核对。首次验证不点击、不输入、不导航、不改变设置、不切换设备；手机操作保持 not_tested。

分别报告本地安装、协议检查（或 not_applicable）、宿主面板位置和真实显示、手机截图读取、手机操作（not_tested）。工具连接成功或模型一句“已打开”不等于画面验收。历史模拟器截图不证明当前用户的手机能用。

## 更新与排查

用新版已校验包选择同一个客户端，保留配对和用户配置，再重载或重启连接器、宿主。豆包和 Cherry 的导入副本可能需要重新导入；DSH 保留 DSH_HOME，使用返回的固定 pluginDirectory。当前是显式安装包更新，不是无人值守网络自动升级。

找不到 Skill：启用并绑定到当前 Agent。面板空白：恢复一次后使用已支持的内置浏览器路线，系统浏览器回退要明确标注。版本仍旧：重启连接器，检查账号侧 Skill 是否需要重新导入。已配对但无画面：检查手机解锁、无线控制、网络可达性、控制器占用和隐私暂停，不删除配对。配置被用户修改：保留并报告冲突。模型认证失败：先在宿主修复，安装 Tapilot 不能修复模型认证。