@tunnelbox/core 0.1.0 → 0.1.7

package/README.md

@@ -1,23 +1,28 @@
 # @tunnelbox/core
 
-tunnelbox 共享核心，供各智能体适配器复用：
+[English](README.md) · [简体中文](README.zh-CN.md)
 
-| 模块 | 说明 |
+Shared core for tunnelbox, reused by the agent adapters:
+
+| Module | Description |
 |---|---|
-| `types.ts` | 统一协议类型 + `envelope()`（与 relay/web 镜像互通） |
-| `relay.ts` | `RelayClient`：出站 WS + 指数退避**静默**重连 |
-| `state.ts` | 状态持久化（`remote-state[.type].json`，多 agent 隔离）+ 配对文件 |
-| `qr.ts` | `printPairing`：终端二维码 + 配对码打印 |
+| `types.ts` | Unified protocol types + `envelope()` (interoperable with relay/web mirrors) |
+| `relay.ts` | `RelayClient`: outbound WS with exponential-backoff **silent** reconnect |
+| `state.ts` | State persistence (`remote-state[.type].json`, isolated per agent) + pairing files |
+| `env.ts` | `injectedRelayUrl()`: default relay injected at build time via esbuild `__TB_DEFAULT_RELAY__` (no URL literals in source) |
+| `qr.ts` | `printPairing`: terminal QR code + pairing code printing |
 
-## 使用
+## Usage
 
 ```ts
-import { RelayClient, envelope, loadState, printPairing } from "@tunnelbox/core";
+import { RelayClient, envelope, loadState, printPairing, injectedRelayUrl } from "@tunnelbox/core";
 
-const state = loadState("dsh"); // 多智能体：各适配器独立状态文件
+const state = loadState("dsh"); // multiple agents: each adapter keeps its own state file
+// Relay resolution: explicit (TUNNELBOX_RELAY_URL / config) > injectedRelayUrl() (default injected by build --env).
+// Config files live in plugin/env/.env.{development,test,production}; state.relayUrl is informational only.
 const ws = new RelayClient();
-ws.connect(`${state.relayUrl}/ws/agent`, { Authorization: `Bearer ${state.agentId}` }, { … });
+ws.connect(`${injectedRelayUrl()}/ws/agent`, { Authorization: `Bearer ${state.agentId}` }, { … });
 ws.send(envelope("agent.info", { name: "host", type: "dsh", version: "0.1.0" }));
 ```
 
-消费方（`plugin/opencode` / `plugin/dsh-tunnelbox` / 各适配器）通过 bundler（esbuild/vite）直接打包本包 TS 源码；无需独立构建步骤。
+Consumers (`plugin/opencode` / `plugin/dsh-tunnelbox` / the adapters) bundle this package's TS source directly with a bundler (esbuild/vite); no separate build step is needed.

package/README.zh-CN.md

@@ -0,0 +1,28 @@
+# @tunnelbox/core
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+tunnelbox 共享核心，供各智能体适配器复用：
+
+| 模块 | 说明 |
+|---|---|
+| `types.ts` | 统一协议类型 + `envelope()`（与 relay/web 镜像互通） |
+| `relay.ts` | `RelayClient`：出站 WS + 指数退避**静默**重连 |
+| `state.ts` | 状态持久化（`remote-state[.type].json`，多 agent 隔离）+ 配对文件 |
+| `env.ts` | `injectedRelayUrl()`：构建期 esbuild `__TB_DEFAULT_RELAY__` 注入的默认中继（源码无 URL 字面量） |
+| `qr.ts` | `printPairing`：终端二维码 + 配对码打印 |
+
+## 使用
+
+```ts
+import { RelayClient, envelope, loadState, printPairing, injectedRelayUrl } from "@tunnelbox/core";
+
+const state = loadState("dsh"); // 多智能体：各适配器独立状态文件
+// 中继地址解析：显式(TUNNELBOX_RELAY_URL/配置) > injectedRelayUrl()（构建 --env 注入的默认）。
+// 配置文件见 plugin/env/.env.{development,test,production}；state.relayUrl 仅信息用途。
+const ws = new RelayClient();
+ws.connect(`${injectedRelayUrl()}/ws/agent`, { Authorization: `Bearer ${state.agentId}` }, { … });
+ws.send(envelope("agent.info", { name: "host", type: "dsh", version: "0.1.0" }));
+```
+
+消费方（`plugin/opencode` / `plugin/dsh-tunnelbox` / 各适配器）通过 bundler（esbuild/vite）直接打包本包 TS 源码；无需独立构建步骤。