diff --git a/README.en.md b/README.en.md index a391f777..2770d333 100644 --- a/README.en.md +++ b/README.en.md @@ -21,6 +21,8 @@ An agent only needs a BaseURL and a Secret Key to discover capabilities, read th > [!IMPORTANT] > tool-bridge is currently in **pre-launch** development. Node/Docker, the SDK, CLI, and Dashboard already form complete working flows, but there is no formal production environment or stability SLA yet. It is ready for self-hosted evaluation, internal integrations, and development; read the release notes and back up your data before upgrading. +**Getting around:** [Quick start](#quick-start-run-a-gateway-locally) · [Browser Dashboard](#browser-dashboard) · [Mobile app](#mobile-app) · [Agent integration](#let-an-agent-use-tool-bridge-directly) · [Use cases](#what-you-can-use-today) · [Deployment](#deploy-or-embed) + ## What is tool-bridge? tool-bridge is the reference implementation of [HTBP (HTTP ToolBridge Protocol)](https://github.com/TokenRollAI/HTBP). It projects capabilities spread across MCP servers, HTTP APIs, object stores, local machines, and other gateways into one tree: @@ -95,6 +97,86 @@ curl -X POST \ `~help` returns Markdown by default. Send `Accept: text/plain` for the compact Help DSL, or `Accept: application/json` for a structured representation with JSON Schema. +## Browser Dashboard + +After installing a gateway, open `/ui`; no separate desktop client is needed. The Dashboard and `tb` CLI use the same permissions. Tools hidden from the current SK remain hidden in the browser. + +![Browser capability tree with the device branch expanded to show connected computers and phones](docs/screenshots/dashboard-capability-tree.png) + +### Connect to your gateway + +1. Open your own Dashboard, for example `http://127.0.0.1:8787/ui`. +2. Keep the same-origin connection to use the current gateway. For another instance, fill in “其他网关地址” (other gateway address), such as `https://gateway.example.com`, without `/ui`. +3. Enter your Secret Key, give the connection profile a recognizable name, and click “连接工作区” (connect to workspace). + +
+View the browser connection page + +![Dashboard connection page with gateway selection, Secret Key input, and connection profile](docs/screenshots/dashboard-login.png) + +
+ +Connection profiles and SKs are saved in the current browser, so use a trusted device. Favorites and recent tools are also local to the current connection; they do not sync across browsers. Recent history stores tool entry points, not arguments or results. Screenshots show the Chinese interface. + +### Find a tool and make your first call + +1. Browse “工具” (tools), or use the top search bar (`⌘K` / `Ctrl+K`) to find a command. +2. Open the command, read its description and parameter requirements, fill in the form, and click “调用” (invoke). Inspect the response and elapsed time on the page. +3. Expand “等价 CLI / curl” to move the same call into a terminal or script. Favorite the tool to find it on the workspace next time. + +On a fresh installation, start with the `get` command under `system/status` to read gateway status. The equivalent CLI steps are: + +```sh +tb help system/status +tb call system/status/get +``` + +### Add tools, explore the tree, and manage devices + +| Goal | Dashboard action | +|---|---| +| Connect a third-party tool | Click “添加工具” (add tool), choose a built-in integration, MCP Server, or HTTP endpoint, and follow the setup form; OAuth integrations also require authorization | +| Explore the hierarchy | Open “能力树” (capability tree), expand directories, and select a node to inspect its description and commands | +| Check a computer or phone connection | Open “设备” (devices) to check status; “连接设备” provides connection guidance | +| Upload, download, or share attachments | Use “文件存储” (file storage) to upload files, copy stable URIs, or create short-lived shares | +| Scope an agent's access | Issue a path- and action-scoped SK in “访问密钥” (access keys); manage upstream credentials separately in “服务凭证” (service credentials) | + +![Browser devices page showing session status and tool entry points for two Linux computers and one phone](docs/screenshots/dashboard-devices.png) + +These browser screenshots show a configured instance. Your directories, devices, and available actions depend on what you connect and the current SK's permissions. + +Offline devices may remain in the tree. Whether a command can run or accept delayed delivery depends on its current contract and device state; see the [device SDK's Durable Mailbox guide](packages/sdk/README.md#durable-mailbox显式拉取). + +## Mobile app + +The mobile app separates reading content from agents and managing the phone into two tabs. These real usage screenshots show the inbox on the left and device connection and authorization status on the right. + + + + + + + + + + +
Inbox: reports and messagesDevice: connection and authorization
Mobile inbox with daily reports, message search, and all/unread filtersMobile device page with device ID, gateway connection status, and connection and authorization settings
+ +### Read agent reports + +Open “信箱” (inbox) to browse report titles and previews. Search for a message or switch to “未读” (unread) to focus on unread content. The screenshot shows release updates and daily news reports, illustrating how outputs from different agents can share one reading surface. + +### Check the phone's connection and authorization + +1. Open “设备” (device) to check the current device ID and gateway connection state. The ID lets agents identify this phone. +2. Use “连接配置” (connection settings) to check the target gateway. The phone must be able to reach it; `127.0.0.1` on a phone points to the phone itself, not a gateway running on your computer. +3. Review the invocation mode in “授权与安全” (authorization and security). “直接调用” (direct invocation) is enabled in this screenshot; that is this device's setting at capture time. System permissions and device restrictions still apply, and an emergency disable option is available. +4. Check the device in the browser's device page, then let the agent discover its actual exposed commands through live `~help`. + +The mobile **inbox** is a message-reading interface for people. **Durable Mailbox**, described below, is the gateway's persistent execution ledger for device commands. They serve different purposes, and Mailbox itself does not wake an app stopped by the operating system. + +Gateway addresses, device IDs, and messages in the screenshots are illustrative; use your own connection settings. Refer to the mobile app's release notes for installation and platform availability; this repository does not distribute mobile app installers. + ## Let an agent use tool-bridge directly The public [`tool-bridge` Agent Skill](https://github.com/TokenRollAI/tool-bridge-skill) installs into compatible agents such as Codex, Claude Code, Cursor, and OpenCode. It does not store a static catalog for one gateway. Instead, it teaches the agent to discover the current gateway through `~search`, `~tree`, and `~help` at runtime: @@ -129,6 +211,37 @@ The skill verifies the target, searches or browses progressively, reads the tool | Federate teams | Remote nodes, `system/federation` | Mount another HTBP tree without sharing the local caller's credentials | | Support MCP clients | `//~mcp` | Project the current identity's visible tools as an MCP server | +### Ask an agent to inspect phones and Linux devices + +After connecting devices, running `tb login`, and installing the Agent Skill, try requests such as: + +```text +Use the tb CLI to tell me the current status of my devices. +Inspect my two Linux devices using read-only checks. Summarize load, memory, disk usage, and failed services. +``` + +The agent discovers devices and commands before reading the status exposed by each device. To start from a terminal: + +```sh +tb device ls +tb tree device --depth 2 +# Replace with an actual path returned above +tb help +``` + +These actual conversation screenshots show a computer and phone status summary, including phone battery, network, and runtime state, followed by a comparison of two Linux machines. Results describe those devices at capture time; a fresh installation does not expose all these commands by default. + +![Agent using the tb CLI to summarize computer and Android phone connectivity, battery, and network state](docs/screenshots/agent-device-status.png) + +
+View the read-only inspection of two Linux devices + +![Agent comparing load, memory, disk usage, and failed services on two Linux devices](docs/screenshots/agent-linux-inspection.png) + +
+ +The Linux example uses the devices' authorized `shell/exec` capability. A newly connected device denies all shell commands until an explicit allowlist is configured; a structured command profile can instead expose fixed diagnostics. Phone commands depend on the app's actual declarations, system permissions, and device authorization. Agents should read live `~help` rather than infer command paths from screenshots. + ### Upload device artifacts and ordinary attachments Every standard deployment includes a default Store independent from Context, backed by an S3-compatible @@ -343,7 +456,7 @@ tb sk create \ |---|---| | `packages/core` | Pure tree, auth, protocol, store, and builtin logic | | `packages/app` | Host-neutral Hono application and provider orchestration | -| `packages/server` | Node/SQLite/filesystem/WebSocket host | +| `packages/server` | Node/PostgreSQL/S3/WebSocket host | | `packages/cli` | `tb` CLI, device connection, and deployment management | | `packages/dashboard` | Web management UI over the public API | | `packages/sdk` | Embedded instance, local providers, and reverse connection | @@ -360,7 +473,7 @@ pnpm verify # typecheck + lint + test pnpm turbo run build # also required after changing public packages, deps, or build config ``` -The local Compose flow starts the Node gateway, a real plugin Worker, and an authenticated mock MCP upstream: +The local Compose stack starts the Node gateway, PostgreSQL, and S3-compatible object storage: ```sh pnpm compose:up @@ -368,7 +481,7 @@ pnpm compose:smoke pnpm compose:down ``` -Code and generated artifacts are the source of truth for behavior. Start at [`llmdoc/index.md`](llmdoc/index.md) for architecture boundaries, protocol contracts, deployment, and verification guides. +Code and generated artifacts are the source of truth for behavior. Start at [`llmdoc/architecture.mdx`](llmdoc/architecture.mdx) for architecture boundaries, protocol contracts, deployment, and verification guides. ## License diff --git a/README.md b/README.md index 27d780f8..53036df3 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ Agent 只需要一个 BaseURL 和一个 Secret Key，就能发现能力、阅读 > [!IMPORTANT] > tool-bridge 目前处于 **pre-launch** 开发阶段。Node/Docker、SDK、CLI 和 Dashboard 已能组成完整使用闭环，但项目尚无正式生产环境，也暂不承诺稳定性 SLA。现在适合自托管试用、内部集成和参与开发；升级前请阅读发布说明并保留数据备份。 +**使用导航：** [快速开始](#快速开始本地运行一个网关) · [浏览器 Dashboard](#浏览器-dashboard) · [手机 App](#手机-app) · [Agent 接入](#让-agent-直接使用-tool-bridge) · [使用场景](#现在可以怎么用) · [部署](#部署与嵌入) + ## tool-bridge 是什么 tool-bridge 是 [HTBP（HTTP ToolBridge Protocol）](https://github.com/TokenRollAI/HTBP)的参考实现。它把原本分散在 MCP server、HTTP API、对象存储、本地机器和其他网关里的能力投影到同一棵树上： @@ -95,6 +97,86 @@ curl -X POST \ `~help` 默认返回 Markdown；使用 `Accept: text/plain` 可获得紧凑 Help DSL，使用 `Accept: application/json` 可获得包含 JSON Schema 的结构化描述。 +## 浏览器 Dashboard + +安装网关后，打开 `<网关地址>/ui` 即可使用，无需单独安装桌面客户端。Dashboard 与 `tb` CLI 使用同一套权限：当前 SK 看不到的工具，也不会因为进入浏览器就变得可见。 + +![浏览器能力树：从网关根目录展开设备分支，浏览已接入的电脑和手机](docs/screenshots/dashboard-capability-tree.png) + +### 连接你的网关 + +1. 打开自己部署的 Dashboard，例如 `http://127.0.0.1:8787/ui`。 +2. 使用当前网关时，保留同源连接；连接另一套实例时，填写「其他网关地址」，例如 `https://gateway.example.com`，不带 `/ui`。 +3. 输入访问密钥（Secret Key），为连接填写易辨认的档案名，再点击「连接工作区」。连接成功后进入工作台。 + +
+查看浏览器连接页 + +![浏览器 Dashboard 连接页：选择网关、输入访问密钥并保存连接档案](docs/screenshots/dashboard-login.png) + +
+ +连接档案和 SK 保存在当前浏览器，请在受信任设备上使用。收藏与最近使用也只属于本机的当前连接，不会同步到其他浏览器；最近使用保留工具入口，不保存调用参数和结果。 + +### 找到工具，完成第一次调用 + +1. 进入「工具」逐级浏览，或使用顶部搜索（`⌘K` / `Ctrl+K`）查找命令。 +2. 打开命令，阅读说明与参数要求，填写表单后点击「调用」，在页面中查看响应和耗时。 +3. 展开「等价 CLI / curl」，把同一次调用迁移到终端或脚本；点击收藏，下次从工作台直接进入。 + +刚安装的实例可以先打开 `system/status` 下的 `get` 命令，读取网关状态。对应的 CLI 操作是： + +```sh +tb help system/status +tb call system/status/get +``` + +### 添加工具、浏览能力树与管理设备 + +| 想做什么 | Dashboard 操作 | +|---|---| +| 接入第三方工具 | 点击「添加工具」，选择内置集成、MCP Server 或 HTTP 端点，按向导填写配置；需要 OAuth 的集成还需完成授权 | +| 查看工具之间的层级关系 | 打开「能力树」，展开目录，选中节点查看说明和命令 | +| 查看电脑或手机是否连接 | 打开「设备」查看设备状态；「连接设备」提供接入引导 | +| 上传、下载或分享附件 | 在「文件存储」中上传文件、复制稳定 URI，或创建短期分享 | +| 给 Agent 分配访问范围 | 在「访问密钥」中签发按路径和动作限制的 SK；第三方服务的上游凭证在「服务凭证」中管理 | + +![浏览器设备页：集中查看两台 Linux 电脑和一台手机的会话状态，并进入各设备工具](docs/screenshots/dashboard-devices.png) + +以上浏览器截图来自一个已配置的实例；你的目录、设备和可见操作取决于实际接入内容与当前 SK 权限。 + +设备离线后仍可能保留在能力树中。是否可以调用、是否支持延迟交付，要以命令当前声明的能力和设备状态为准，详见[离线设备交付](#给暂时离线的设备延迟交付)。 + +## 手机 App + +手机端把「查看 Agent 发来的内容」和「管理这台设备」放在两个页签中。下面是实际使用截图：左侧是信箱，右侧是设备连接与授权状态。 + + + + + + + + + + +
信箱：集中查看报告与消息设备：确认连接与授权状态
手机 App 信箱页，展示日报消息、搜索框和全部／未读筛选手机 App 设备页，展示设备 ID、已连接网关以及连接配置和授权与安全入口
+ +### 查看 Agent 报告 + +进入「信箱」，从消息标题和摘要浏览 Agent 发来的日报、更新汇总等内容；用搜索框查找消息，或切换「未读」筛选待处理内容。截图展示了版本动态与每日资讯报告：可以把不同 Agent 的产出集中到一个阅读入口。 + +### 确认手机连接与授权 + +1. 进入「设备」，查看当前设备 ID 和网关连接状态。设备 ID 用于让 Agent 识别这台手机。 +2. 通过「连接配置」检查连接目标。手机需要能访问该网关；手机上的 `127.0.0.1` 指向手机自身，不能用它连接电脑上运行的网关。 +3. 在「授权与安全」中检查调用模式。截图中的「直接调用」已开启，这是该设备当时的设置；系统权限与设备限制仍然有效，也可以紧急停用。 +4. 回到浏览器的「设备」页确认设备状态，让 Agent 通过实时 `~help` 发现该设备实际开放的命令。 + +手机 App 的「信箱」是面向人的消息阅读界面；下文的 **Durable Mailbox** 是网关为设备命令提供的持久化执行账本。两者用途不同，Mailbox 本身也不会唤醒被系统停止的 App。 + +截图中的网关地址、设备 ID 和消息仅用于展示，请使用自己的连接配置。手机 App 的安装包与平台支持请以其发布说明为准，本仓库不提供手机 App 安装包。 + ## 让 Agent 直接使用 tool-bridge 公开的 [`tool-bridge` Agent Skill](https://github.com/TokenRollAI/tool-bridge-skill) 可以安装到 Codex、Claude Code、Cursor、OpenCode 等兼容 Agent。它不会保存某个实例的静态工具清单，而是让 Agent 从当前网关的 `~search`、`~tree` 与 `~help` 实时发现能力： @@ -129,6 +211,37 @@ Skill 会先验证目标，再搜索或逐级浏览、读取工具级 schema 与 | 联邦多个团队 | remote 节点、`system/federation` | 把另一棵 HTBP 树挂成子树，不共享本地调用者凭据 | | 兼容 MCP 客户端 | `//~mcp` | 将当前身份可见的工具投影为 MCP server | +### 让 Agent 检查手机与 Linux 设备 + +接入设备、完成 `tb login` 并安装 Agent Skill 后，可以直接提出这样的请求： + +```text +使用 tb CLI 告诉我现在的设备状态。 +看看我的两台 Linux 设备的运行情况，只做只读检查，汇总负载、内存、磁盘和异常服务。 +``` + +Agent 先发现设备与命令，再按当前设备开放的能力读取状态。你也可以从终端开始： + +```sh +tb device ls +tb tree device --depth 2 +# 将 <设备路径> 替换为上一步返回的实际路径 +tb help <设备路径> +``` + +下面是两次实际对话截图：第一张汇总电脑和手机的在线状态，并读取手机电量、网络与运行状态；第二张对比两台 Linux 的资源使用和异常服务。具体结果来自截图当时的设备状态，不代表默认安装就开放这些命令。 + +![Agent 通过 tb CLI 查询电脑和 Android 手机状态，汇总在线状态、电量与网络](docs/screenshots/agent-device-status.png) + +
+展开查看：两台 Linux 设备的只读巡检 + +![Agent 对比两台 Linux 设备的负载、内存、磁盘和异常服务，并给出待检查项](docs/screenshots/agent-linux-inspection.png) + +
+ +Linux 巡检示例使用设备已授权的 `shell/exec`；新接入设备的 shell 默认拒绝所有命令，需要明确 allowlist，也可以使用结构化命令 profile 暴露固定诊断能力。手机命令以 App 实际声明、系统权限和设备授权为准；Agent 应读取实时 `~help`，不能从截图猜测命令路径。 + ### 上传设备产物与普通附件 每个标准部署都自带一个与 Context 独立的 default Store，通过 S3 兼容服务存储对象。 @@ -392,7 +505,7 @@ tb sk create \ |---|---| | `packages/core` | 树、授权、协议、store、builtin 等纯逻辑 | | `packages/app` | 宿主中立的 Hono 应用与 provider 编排 | -| `packages/server` | Node/SQLite/文件/WebSocket 宿主 | +| `packages/server` | Node/PostgreSQL/S3/WebSocket 宿主 | | `packages/cli` | `tb` CLI、设备连接与部署管理 | | `packages/dashboard` | 使用公开 API 的 Web 管理面 | | `packages/sdk` | 嵌入式实例、本地 provider 与反向连接 | @@ -409,7 +522,7 @@ pnpm verify # typecheck + lint + test pnpm turbo run build # 修改可发布包、依赖或打包配置时还必须执行 ``` -本地 Compose 闭环会启动 Node gateway、真实 plugin Worker 和受认证的 mock MCP 上游： +本地 Compose 栈会启动 Node gateway、PostgreSQL 和 S3 兼容对象存储： ```sh pnpm compose:up @@ -417,7 +530,7 @@ pnpm compose:smoke pnpm compose:down ``` -代码与生成产物是行为真源。架构边界、协议契约、部署和验证指南从 [`llmdoc/index.md`](llmdoc/index.md) 开始阅读。 +代码与生成产物是行为真源。架构边界、协议契约、部署和验证指南从 [`llmdoc/architecture.mdx`](llmdoc/architecture.mdx) 开始阅读。 ## License diff --git a/docs/screenshots/agent-device-status.png b/docs/screenshots/agent-device-status.png new file mode 100644 index 00000000..2b7f8cd4 Binary files /dev/null and b/docs/screenshots/agent-device-status.png differ diff --git a/docs/screenshots/agent-linux-inspection.png b/docs/screenshots/agent-linux-inspection.png new file mode 100644 index 00000000..f1442348 Binary files /dev/null and b/docs/screenshots/agent-linux-inspection.png differ diff --git a/docs/screenshots/dashboard-capability-tree.png b/docs/screenshots/dashboard-capability-tree.png new file mode 100644 index 00000000..57752990 Binary files /dev/null and b/docs/screenshots/dashboard-capability-tree.png differ diff --git a/docs/screenshots/dashboard-devices.png b/docs/screenshots/dashboard-devices.png new file mode 100644 index 00000000..fc0a8e8d Binary files /dev/null and b/docs/screenshots/dashboard-devices.png differ diff --git a/docs/screenshots/dashboard-login.png b/docs/screenshots/dashboard-login.png new file mode 100644 index 00000000..f7a2ebe6 Binary files /dev/null and b/docs/screenshots/dashboard-login.png differ diff --git a/docs/screenshots/mobile-device.jpg b/docs/screenshots/mobile-device.jpg new file mode 100644 index 00000000..e53db596 Binary files /dev/null and b/docs/screenshots/mobile-device.jpg differ diff --git a/docs/screenshots/mobile-inbox.jpg b/docs/screenshots/mobile-inbox.jpg new file mode 100644 index 00000000..3b28b386 Binary files /dev/null and b/docs/screenshots/mobile-inbox.jpg differ