pi-browser-use-lite 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# CHANGELOG
+
+本文件记录已发布版本的用户可见变更。更细的过程见 git log。破坏性变更标 **BREAKING**。
+
+## 0.1.1 — 2026-11-09
+
+- 补中文 README：`README.zh-CN.md`，英文版顶部有切换链接，npm 包同时收录两份。
+
+## 0.1.0 — 2026-11-08
+
+首版。
+
+- 五个工具：`chrome_act`（navigate、click、type、fill、press、hover、drag、scroll、upload、eval、wait、batch）、`chrome_see`（refs、text、changes、full，另可取 console 与 network 日志）、`chrome_tab`（list、new、switch、close）、`chrome_vision`（截图落盘）、`chrome_cdp`（裸 CDP 调用）。
+- `/chrome` 命令：`authorize on|off`、`background on|off`、`status`。扩展装好之前，命令与工具都报 `extension_missing` 并给出装扩展三步。
+- 本地桥：只绑 `127.0.0.1`，多 Pi 会话共用一个服务端，其余退成客户端。扩展每 100 毫秒轮询一次。
+- 每个会话一个独立的浏览器窗口：动作在本次会话的 target 里执行，别的窗口不动，退出时按配置关掉标签。
+- 截图默认落在 `<agent dir>/pi-browser-use-lite/screenshots`，跟着 `PI_CODING_AGENT_DIR` 走，不写进家目录的 `~/.pi/screenshots`。
+- 发布：`CHANGELOG.md` 与 `browser-extension/` 一起进 `files`。用户从 npm 装到扩展源码后 load unpacked。
+- 扩展版本落后于包时自己重载一次，不必再去扩展页手动刷新。
+- 轮询断了由扩展的 1 秒定时器重起；`chrome.alarms` 只作服务工作进程被回收后的兜底。
+- `chrome_act eval` 省掉超长 `data` 时，说明接在正文末尾；此前这条说明到不了模型。
+- 包内带 `README.md`：安装、配置、开发各一节，扩展目录由 `/chrome status` 打印。

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024-2026 pi-chrome contributors
+Copyright (c) 2026 setwhite
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# pi-browser-use-lite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[简体中文](README.zh-CN.md) | **English**
+
+Five `chrome_*` tools that drive your own browser: the tabs you are already logged into, with your cookies and your sessions.
+
+The package has two halves. The pi extension registers the tools and runs a local bridge on `127.0.0.1`. The companion Chrome extension polls that bridge and runs each command through `chrome.debugger`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `chrome_act` | navigate, click, type, fill, press, hover, drag, scroll, upload, eval, wait, batch |
+| `chrome_see` | snapshot the page as refs, text, changes or full; read console and network logs |
+| `chrome_tab` | list, new, switch, close |
+| `chrome_vision` | screenshot the viewport or the full page |
+| `chrome_cdp` | one raw CDP call for anything the other four do not cover |
+
+Behaviour worth knowing:
+
+- Each session gets its own browser window. The tools do not touch your own tabs. The tabs the session opened are closed when the session ends.
+- Input goes through trusted CDP events, so pages that reject synthetic events still react.
+- Console and network capture starts at navigation, not at the first read.
+- Every failure carries a class and a `hint` that says what to do next.
+
+## Install
+
+```bash
+pi install npm:pi-browser-use-lite
+```
+
+The extension ships inside the package. Load it once per browser:
+
+1. Run `/chrome status` in pi. When the extension is missing, the reply prints the directory to load.
+2. Open `chrome://extensions`, turn on Developer mode, click Load unpacked and pick that directory.
+3. Run `/chrome status` again. `connected: yes` means the bridge sees the extension.
+
+Then authorize the tools for this session:
+
+```
+/chrome authorize on
+```
+
+Authorization ends with the session. Set `policy.authorizeOnStart` to skip this step.
+
+## Configuration
+
+One JSON file: `<agent dir>/pi-browser-use-lite/config.json`. The agent dir is `PI_CODING_AGENT_DIR`, or `~/.pi/agent` when the variable is unset.
+
+Without the file every value is the default. A wrong type or an unknown key fails startup and names every bad field at once. An unknown enum value falls back to the default. An out-of-range number is clamped to the nearest bound. The comments below only explain. A real file must be strict JSON.
+
+**Minimal configuration**: nothing. All five tools work on the defaults.
+
+```json
+{}
+```
+
+**Full example**: every key follows with its default and when to change it.
+
+```jsonc
+{
+  // The local bridge. The extension has the same port compiled in
+  // (browser-extension/background/transport.js): change both, then reload the extension
+  "bridge": { "port": 17318 },
+
+  // Session rules
+  "policy": {
+    "authorizeOnStart": false,  // true = the tools work without /chrome authorize on
+    "background": true,         // true = block every focusing call, chrome_tab switch included.
+                                //        Turn it off when the model must bring a page to the front
+    "closeOwnTabsOnExit": true  // close the tabs this session opened when the session ends
+  },
+
+  // Input and timing
+  "input": {
+    "dragSteps": 10,            // mouse moves between press and release
+    "scrollSteps": 5            // wheel events per scroll call
+  },
+  "timing": { "navigateTimeoutMs": 15000 },  // wait for the load event; the navigate call gets this plus 2s
+
+  // Model-visible output
+  "output": {
+    "maxElements": 80,          // snapshot element cap
+    "textChars": 18000          // body text cap in see mode=text; the rest is dropped with a note
+  },
+
+  // Screenshots
+  "screenshot": {
+    "dir": "/home/me/.pi/agent/pi-browser-use-lite/screenshots",  // created on first use
+    "format": "png",            // png | jpeg
+    "keepNewest": 20            // older screenshots in that directory are deleted
+  },
+
+  // Global rules for the system prompt. These replace the three defaults; they do not extend them
+  "prompt": {
+    "guidelines": ["chrome_act: this is the user's real browser; confirm before destructive actions."]
+  },
+
+  // Tool switches and names. Keep at least one enabled; names must be unique and must not shadow a host tool
+  "tools": {
+    "chrome_act": { "enabled": true, "name": "chrome_act" },
+    "chrome_see": { "enabled": true, "name": "chrome_see" },
+    "chrome_tab": { "enabled": true, "name": "chrome_tab" },
+    "chrome_vision": { "enabled": true, "name": "chrome_vision" },
+    "chrome_cdp": { "enabled": true, "name": "chrome_cdp" }
+  },
+
+  // Override the built-in prompts per tool. "" clears description or promptSnippet; [] adds no rules
+  "guidance": {
+    "chrome_act": {
+      "description": "Drive the user's real browser.",
+      "promptSnippet": "Drive the browser",
+      "promptGuidelines": ["chrome_act: pass see: refs on navigate."]
+    }
+  }
+}
+```
+
+Every key is optional. `src/config/schema.ts` holds the ranges and the defaults.
+
+## Docs
+
+| Document | Content |
+|---|---|
+| [ARCHITECTURE](docs/ARCHITECTURE.md) | Module boundaries and seams; read it before changing the structure |
+| [GLOSSARY](docs/GLOSSARY.md) | One name per concept |
+| [Modules](docs/modules/) | Trade-offs and traps per module |
+| [Decisions](docs/decisions/) | Why the shape is what it is |
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm -C packages/pi-browser-use-lite lint
+pnpm -C packages/pi-browser-use-lite check:imports
+pnpm -C packages/pi-browser-use-lite typecheck
+pnpm -C packages/pi-browser-use-lite test
+```
+
+The end-to-end test drives a real browser. Load the extension from `packages/pi-browser-use-lite/browser-extension`, keep one Chromium browser open with that extension enabled, then run:
+
+```bash
+pnpm -C packages/pi-browser-use-lite test:e2e
+```
+
+Close every other browser that has this extension. Two copies poll the same bridge, and the commands go to whichever copy asks first.
+
+The extension reloads itself when the bridge reports a different version. After editing extension code without a version bump, reload it by hand on the extensions page.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,153 @@
+# pi-browser-use-lite
+
+**[简体中文](README.zh-CN.md)** | [English](README.md)
+
+五个 `chrome_*` 工具，操作你自己的浏览器：你已经登录的标签页、你的 cookie 和会话。
+
+包分两半。pi 扩展注册这些工具，并在 `127.0.0.1` 上跑一个本地桥。配套的 Chrome 扩展轮询这个桥，用 `chrome.debugger` 执行每条命令。
+
+## 工具
+
+| 工具 | 做什么 |
+|---|---|
+| `chrome_act` | navigate、click、type、fill、press、hover、drag、scroll、upload、eval、wait、batch |
+| `chrome_see` | 快照：refs、text、changes、full；读控制台与网络日志 |
+| `chrome_tab` | list、new、switch、close |
+| `chrome_vision` | 截视口或整页 |
+| `chrome_cdp` | 一条裸 CDP 调用，另四个盖不住的用它 |
+
+值得知道的行为：
+
+- 每个会话一个独立浏览器窗口。工具不碰你自己的标签页。会话结束时关掉本会话开的标签。
+- 输入走可信 CDP 事件，拒绝合成事件的页面也会响应。
+- 控制台与网络抓取从导航开始，不从第一次读取开始。
+- 每次失败都带类别和一句 `hint`，说明下一步做什么。
+
+## 安装
+
+```bash
+pi install npm:pi-browser-use-lite
+```
+
+扩展就在包里。每个浏览器装一次：
+
+1. 在 pi 里运行 `/chrome status`。扩展没连上时，回复会打印要加载的目录。
+2. 打开 `chrome://extensions`，开开发者模式，点「加载已解压的扩展程序」，选那个目录。
+3. 再跑一次 `/chrome status`。`connected: yes` 表示桥看到了扩展。
+
+然后给这次会话授权：
+
+```
+/chrome authorize on
+```
+
+授权随会话结束。想省这一步，把 `policy.authorizeOnStart` 设为 true。
+
+## 配置
+
+一个 JSON 文件：`<agent dir>/pi-browser-use-lite/config.json`。agent dir 是 `PI_CODING_AGENT_DIR`，没设时是 `~/.pi/agent`。
+
+没有这个文件时全部取默认值。类型错或未知键会让启动失败，并一次列出所有坏字段。枚举值不认识时取默认值。数字越界时夹到最近的边界。下面的注释只作解释，真正的文件必须是严格 JSON。
+
+**最小配置**：不用写。五个工具在默认值下都能用。
+
+```json
+{}
+```
+
+**完整示例**：每个键都跟着默认值，以及什么时候该改。
+
+```jsonc
+{
+  // 本地桥。扩展里编译了同一个端口
+  // （browser-extension/background/transport.js）：两处一起改，然后重载扩展
+  "bridge": { "port": 17318 },
+
+  // 会话规则
+  "policy": {
+    "authorizeOnStart": false,  // true = 不用 /chrome authorize on 就能用工具
+    "background": true,         // true = 挡掉所有聚焦动作，chrome_tab switch 也算。
+                                //        需要模型把页面带到前台时关掉
+    "closeOwnTabsOnExit": true  // 会话结束时关掉本会话开的标签
+  },
+
+  // 输入与时限
+  "input": {
+    "dragSteps": 10,            // 按下与松开之间的鼠标移动次数
+    "scrollSteps": 5            // 每次 scroll 的滚轮事件数
+  },
+  "timing": { "navigateTimeoutMs": 15000 },  // 等 load 事件的时长；navigate 调用再多给 2 秒
+
+  // 模型可见的输出
+  "output": {
+    "maxElements": 80,          // 快照元素上限
+    "textChars": 18000          // see 的 text 模式正文上限，其余带提示丢掉
+  },
+
+  // 截图
+  "screenshot": {
+    "dir": "/home/me/.pi/agent/pi-browser-use-lite/screenshots",  // 第一次用时创建
+    "format": "png",            // png | jpeg
+    "keepNewest": 20            // 这个目录里更旧的截图会被删掉
+  },
+
+  // 系统提示里的全局规则。这三条换成你的，不是追加
+  "prompt": {
+    "guidelines": ["chrome_act: 这是用户真实的浏览器，破坏性操作前先问一句。"]
+  },
+
+  // 工具开关与名字。至少留一个启用；名字不能重复，也不能盖住宿主已有的工具
+  "tools": {
+    "chrome_act": { "enabled": true, "name": "chrome_act" },
+    "chrome_see": { "enabled": true, "name": "chrome_see" },
+    "chrome_tab": { "enabled": true, "name": "chrome_tab" },
+    "chrome_vision": { "enabled": true, "name": "chrome_vision" },
+    "chrome_cdp": { "enabled": true, "name": "chrome_cdp" }
+  },
+
+  // 按工具改内置提示。"" 清空 description 或 promptSnippet；[] 表示不加规则
+  "guidance": {
+    "chrome_act": {
+      "description": "操作用户真实的浏览器。",
+      "promptSnippet": "操作浏览器",
+      "promptGuidelines": ["chrome_act: navigate 时带上 see: refs。"]
+    }
+  }
+}
+```
+
+每个键都可选。范围与默认值在 `src/config/schema.ts`。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [ARCHITECTURE](docs/ARCHITECTURE.md) | 模块边界与 seam；改结构之前先读它 |
+| [GLOSSARY](docs/GLOSSARY.md) | 一个概念只用一个词 |
+| [Modules](docs/modules/) | 每个模块的取舍与坑 |
+| [Decisions](docs/decisions/) | 为什么是这个形状 |
+
+## 开发
+
+在仓库根执行：
+
+```bash
+pnpm -C packages/pi-browser-use-lite lint
+pnpm -C packages/pi-browser-use-lite check:imports
+pnpm -C packages/pi-browser-use-lite typecheck
+pnpm -C packages/pi-browser-use-lite test
+```
+
+端到端测试会驱动真实浏览器。把 `packages/pi-browser-use-lite/browser-extension` 加载进扩展，留一个开着的 Chromium 系浏览器，然后运行：
+
+```bash
+pnpm -C packages/pi-browser-use-lite test:e2e
+```
+
+关掉其他装了本扩展的浏览器。两份扩展会抢同一个桥，命令落到先问的那一份。
+
+桥报出的版本与扩展不同的时候，扩展会自己重载。改了扩展代码但没升版本号时，去扩展页手动重载一次。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。

package/browser-extension/background/capture.js

@@ -0,0 +1,267 @@
+/**
+ * 日志捕获：用 CDP 事件流记 console 与 network，按标签存一份。
+ * 缓冲区在后台而不是页面里，所以同一标签再导航一次也不会丢。
+ */
+
+import { attach, sendCommand } from "./input/debugger.js";
+import { trackedTabIds } from "./target.js";
+
+const KEY_PREFIX = "capture.logs.";
+const CONSOLE_LIMIT = 500;
+const NETWORK_LIMIT = 1_000;
+const BODY_LIMIT = 200_000;
+
+/** tabId → { console, network, starts, capturing, offReason } */
+const buffers = new Map();
+/** 正在从存储里读的缓冲区。两个调用同时到时共用同一次读，不各建一份。 */
+const pending = new Map();
+let subscribed = false;
+
+subscribe();
+
+/** 事件监听在模块加载时注册，service worker 才会被它们唤醒。 */
+function subscribe() {
+	const debuggerApi = globalThis.chrome?.debugger;
+	if (subscribed || debuggerApi === undefined) return;
+	subscribed = true;
+	debuggerApi.onEvent.addListener(onEvent);
+	debuggerApi.onDetach.addListener(onDetach);
+}
+
+/**
+ * 在这个标签上开抓。已经开着就只补一次 attach，不重复开域。
+ * 挂不上调试器时只记一句说明，不挡动作。
+ * @param {number} tabId 标签 id
+ * @returns {Promise<void>}
+ */
+export async function startCapture(tabId) {
+	subscribe();
+	const buffer = await bufferOf(tabId);
+	buffer.offReason = undefined;
+	try {
+		await attach(tabId);
+		if (buffer.capturing !== true) {
+			await sendCommand(tabId, "Runtime.enable");
+			await sendCommand(tabId, "Network.enable");
+			buffer.capturing = true;
+		}
+	} catch (error) {
+		buffer.capturing = false;
+		buffer.offReason = `capture is off for this tab: ${messageOf(error)}`;
+	}
+	await save(tabId, buffer);
+}
+
+/**
+ * `chrome.webNavigation.onCommitted` 的处理。只抓本会话台账里的标签。
+ * @param {{ tabId?: number, frameId?: number }} details 导航详情
+ * @returns {Promise<void>}
+ */
+export async function onCommitted({ tabId, frameId } = {}) {
+	if (frameId !== 0 || !Number.isInteger(tabId)) return;
+	if (!(await trackedTabIds()).has(tabId)) return;
+	await startCapture(tabId);
+}
+
+/**
+ * 读 console 条目，最旧的在前。
+ * @param {number} tabId 标签 id
+ * @param {{ clear?: boolean }} [options] `clear` 读完清空
+ * @returns {Promise<{ records: object[], note?: string }>} 条目与说明
+ */
+export async function listConsole(tabId, { clear = false } = {}) {
+	const buffer = await bufferOf(tabId);
+	const records = buffer.console.slice();
+	if (clear) {
+		buffer.console.length = 0;
+		await save(tabId, buffer);
+	}
+	return withNote(records, buffer.offReason);
+}
+
+/**
+ * 读网络请求，最早的在前。
+ * @param {number} tabId 标签 id
+ * @param {{ clear?: boolean }} [options] `clear` 读完清空
+ * @returns {Promise<{ records: object[], note?: string }>} 请求与说明
+ */
+export async function listNetwork(tabId, { clear = false } = {}) {
+	const buffer = await bufferOf(tabId);
+	const records = buffer.network.map((record) => ({ ...record }));
+	if (clear) {
+		buffer.network.length = 0;
+		await save(tabId, buffer);
+	}
+	return withNote(records, buffer.offReason);
+}
+
+/**
+ * 单条请求的详情，顺带取回响应体。
+ * @param {number} tabId 标签 id
+ * @param {string} requestId 请求 id
+ * @returns {Promise<object>} 请求记录
+ */
+export async function networkRequest(tabId, requestId) {
+	const buffer = await bufferOf(tabId);
+	const record = buffer.network.find((entry) => entry.id === requestId);
+	if (record === undefined)
+		throw new Error(`bad_args: no request with id ${requestId}`);
+
+	const detail = { ...record };
+	try {
+		const body = await sendCommand(tabId, "Network.getResponseBody", {
+			requestId,
+		});
+		if (body?.base64Encoded === true)
+			detail.responseBodyNote = "the response body is binary";
+		else if (typeof body?.body === "string")
+			detail.responseBody = clipBody(body.body);
+	} catch (error) {
+		detail.responseBodyNote = `could not read the response body: ${messageOf(error)}`;
+	}
+	return detail;
+}
+
+function onEvent(source, method, params = {}) {
+	void handleEvent(source, method, params);
+}
+
+/// 调试器事件可能在 startCapture 之前到（service worker 刚醒来），所以先按标签建缓冲区。
+async function handleEvent(source, method, params) {
+	const tabId = source?.tabId;
+	if (!Number.isInteger(tabId)) return;
+	const buffer = await bufferOf(tabId);
+	if (buffer.offReason !== undefined) return;
+	if (method === "Runtime.consoleAPICalled") pushConsole(buffer, params);
+	else if (method === "Network.requestWillBeSent") pushRequest(buffer, params);
+	else if (method === "Network.responseReceived") markStatus(buffer, params);
+	else if (method === "Network.loadingFinished") markDuration(buffer, params);
+	else return;
+	await save(tabId, buffer);
+}
+
+function onDetach(source, reason) {
+	const buffer = buffers.get(source?.tabId);
+	if (buffer === undefined) return;
+	buffer.capturing = false;
+	buffer.offReason = `capture is off for this tab: ${reason}`;
+}
+
+function pushConsole(buffer, { type, args = [], timestamp }) {
+	buffer.console.push({
+		level: levelOf(type),
+		text: args.map(textOf).join(" "),
+		time: Math.round(timestamp ?? Date.now()),
+	});
+	if (buffer.console.length > CONSOLE_LIMIT)
+		buffer.console.splice(0, buffer.console.length - CONSOLE_LIMIT);
+}
+
+function pushRequest(buffer, { requestId, request = {}, timestamp }) {
+	const record = {
+		id: requestId,
+		method: request.method ?? "GET",
+		url: request.url ?? "",
+		status: undefined,
+		durationMs: undefined,
+	};
+	if (typeof request.postData === "string") {
+		record.requestBody = clipBody(request.postData);
+		if (record.requestBody !== request.postData)
+			record.requestBodyTruncated = true;
+	}
+	buffer.starts.set(requestId, timestamp);
+	buffer.network.push(record);
+	if (buffer.network.length > NETWORK_LIMIT)
+		buffer.network.splice(0, buffer.network.length - NETWORK_LIMIT);
+}
+
+function markStatus(buffer, { requestId, response = {} }) {
+	const record = buffer.network.find((entry) => entry.id === requestId);
+	if (record !== undefined) record.status = response.status;
+}
+
+function markDuration(buffer, { requestId, timestamp }) {
+	const record = buffer.network.find((entry) => entry.id === requestId);
+	const startedAt = buffer.starts.get(requestId);
+	if (record === undefined || startedAt === undefined) return;
+	record.durationMs = Math.round((timestamp - startedAt) * 1000);
+}
+
+async function bufferOf(tabId) {
+	const existing = buffers.get(tabId);
+	if (existing !== undefined) return existing;
+	let loading = pending.get(tabId);
+	if (loading === undefined) {
+		const key = KEY_PREFIX + tabId;
+		loading = chrome.storage.session.get(key).then((stored) => {
+			const saved = stored?.[key] ?? {};
+			return {
+				console: saved.console ?? [],
+				network: saved.network ?? [],
+				starts: new Map(Object.entries(saved.starts ?? {})),
+				capturing: saved.capturing === true,
+				offReason: saved.offReason,
+			};
+		});
+		pending.set(tabId, loading);
+	}
+	const buffer = await loading;
+	buffers.set(tabId, buffer);
+	pending.delete(tabId);
+	return buffer;
+}
+
+async function save(tabId, buffer) {
+	await chrome.storage.session.set({
+		[KEY_PREFIX + tabId]: {
+			console: buffer.console,
+			network: buffer.network,
+			starts: Object.fromEntries(buffer.starts),
+			capturing: buffer.capturing,
+			offReason: buffer.offReason,
+		},
+	});
+}
+
+function withNote(records, offReason) {
+	return offReason === undefined ? { records } : { records, note: offReason };
+}
+
+function levelOf(type) {
+	if (type === "warning") return "warn";
+	if (type === "error" || type === "assert") return "error";
+	if (type === "debug" || type === "trace") return "debug";
+	if (type === "info") return "info";
+	return "log";
+}
+
+function textOf(arg) {
+	if (arg?.value !== undefined) return String(arg.value);
+	if (typeof arg?.description === "string") return arg.description;
+	return String(arg?.type ?? "");
+}
+
+/** 按上限切请求体。说明占的字符也算在上限内，丢掉的数量与实际切掉的一致。 */
+function clipBody(text) {
+	if (text.length <= BODY_LIMIT) return text;
+	let kept = BODY_LIMIT;
+	let dropped = text.length - kept;
+	// 说明里的数字位数会改变说明本身的长度，迭代到不再变为止。
+	for (;;) {
+		const next = BODY_LIMIT - bodyNote(dropped).length;
+		const nextDropped = text.length - next;
+		if (next === kept) break;
+		kept = next;
+		dropped = nextDropped;
+	}
+	return text.slice(0, kept) + bodyNote(dropped);
+}
+
+function bodyNote(dropped) {
+	return `\n[truncated ${dropped} chars]`;
+}
+
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}