@tt-a1i/hive 2.1.1 → 2.1.3

package/README.md

@@ -5,264 +5,409 @@
 # Hive
 
 <p align="center">
-  <img src="./assets/hive-hero.png" alt="Hive 本机多 agent 协作工作台" />
+  <img src="./assets/hive-hero.png" alt="Hive local-first multi-agent collaboration workspace hero image" />
 </p>
 
-**Hive 是浏览器里的 Agent 协作工作台——一群 Agent 在你本机各自开工，一个当 Orchestrator 派活、归总进展，其余各司其职。** Orchestrator 本身就是一个真实的 `agy` / `claude` / `codex` / `opencode` / `gemini` / `hermes` / `qwen` 进程——不是你、也不是脚本——它派单的 Worker 同样是真 CLI agent。所有 agent 都是本机真实的 PTY 进程，通过 Hive 注入到 shell 里的小型 `team` 协议互相通信，共享 `<workspace>/.hive/tasks.md` 这份 markdown 任务图。
+**Run Claude Code, Codex, Gemini, OpenCode, Qwen, and other CLI agents as a visible local team.** Hive gives you one browser workbench where an
+Orchestrator plans and delegates while workers implement, review, test,
+research, and report back — all as real PTY processes on your laptop.
 
-写代码、做调研、起草文档、做翻译——凡是能拆给一群人协作的脑力活，都可以让一群 Agent 合伙干。
-
-全程可以用国产 CLI 组队——Qwen Code 是内置预设，GLM 等国内模型也能通过其支持的 coding CLI 或自定义命令接入——不强制依赖境外 API。Windows 原生支持（非 WSL），详见[平台支持](#平台支持)。
+Use Hive when one agent is not enough, but a pile of terminal windows is not a workflow.
 
 [![npm](https://img.shields.io/npm/v/@tt-a1i/hive.svg)](https://www.npmjs.com/package/@tt-a1i/hive)
 [![ci](https://img.shields.io/github/actions/workflow/status/tt-a1i/hive/release.yml?branch=main&label=ci)](https://github.com/tt-a1i/hive/actions/workflows/release.yml)
 [![Website](https://img.shields.io/badge/website-hivehq.dev-5a8a8a.svg)](https://hivehq.dev)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-3c873a.svg)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/license-BUSL--1.1-orange.svg)](./LICENSE.BSL)
-[![Platforms](https://img.shields.io/badge/platforms-macOS%20%C2%B7%20Linux%20%C2%B7%20Windows%20(best--effort)-lightgrey.svg)](#平台支持)
+[![Platforms](https://img.shields.io/badge/platforms-macOS%20%C2%B7%20Linux%20%C2%B7%20Windows%20(best--effort)-lightgrey.svg)](#platform-support)
 
-🌐 **官网**：[hivehq.dev](https://hivehq.dev/)（[English](https://hivehq.dev/en/)）
+🌐 **Website**: [hivehq.dev/en/](https://hivehq.dev/en/) · [中文](https://hivehq.dev/)
 
-[English](./README.en.md) · 简体中文
+English · [简体中文](./README.zh.md)
 
-> Hive 是本机优先的工具，只监听 `127.0.0.1`，面向已经在用 CLI Agent 的人。最新稳定版本见 [npm](https://www.npmjs.com/package/@tt-a1i/hive)，上面的 badge 会指向它。
+> Hive is local-first, runs on `127.0.0.1`, and is intended for anyone who
+> already runs CLI agents. The latest stable release is on
+> [npm](https://www.npmjs.com/package/@tt-a1i/hive) and the badge above resolves
+> to it.
 
 <p align="center">
-  <img src="./assets/hive-team-view.png" alt="Hive 工作台：4 个 CLI Agent 团队，Orchestrator 派单、Worker 各自开工" />
+  <img src="./assets/hive-team-view.png" alt="Hive workbench with a 4-agent team — orchestrator dispatching while workers run" />
 </p>
 
-## 为什么需要 Hive
+## Why Hive
 
-CLI Agent 各自都很强，但同时管几个就有点别扭：
+CLI agents are powerful, but coordinating several of them manually is
+awkward:
 
-- 长任务的会话散在好几个终端里，注意力来回切。
-- 想把活儿分给几个 Agent（写代码 / review / 测试，或者调研 / 起草 / 事实核查之类），却缺一层来居中调度。
-- Worker 的进度淹在 scrollback 里，回头看找不到。
-- 想重启接着干，全看每个 CLI 自己的 session 恢复行为，散乱不可控。
+- Long-running sessions are spread across terminals.
+- Splitting work across agents — implementation/review/testing,
+  research/drafting/fact-checking, or any other division of labor — needs a
+  routing layer you don't have.
+- Worker progress disappears into scrollback.
+- Restart recovery depends on each CLI's native session behavior.
 
-Hive 加上这一层调度，**不替换**任何 CLI。Agent 还是真实跑在你电脑上的终端进程，Hive 只是它们外面的"团队 shell"。
+Hive adds the coordination layer without replacing the CLIs. The Orchestrator
+is a real `agy` / `claude` / `codex` / `opencode` / `gemini` / `hermes` /
+`qwen` process, not a scripted PM. Workers are real CLI agents too. Hive
+injects a small `team` command into their shells, so they can dispatch,
+report, and keep a shared markdown task graph at `<workspace>/.hive/tasks.md`.
 
-## 先看看 demo
+## Use It For
 
-还没装任何 agent CLI？运行 `hive`、打开它打印出的本地地址、在 first-run 向导里点 **Try Demo**。当前的 demo 是一段 Bilibili 演示视频（需要联网才能播放），外加侧边栏里的一个示例团队，让你不安装、不登录任何真实 CLI agent 就能看到 Orchestrator 派单、Worker 干活的样子。适合决定要不要继续装真 CLI。
+**Ship a PR with a reviewer in the loop**
 
-## 快速开始
+Ask the Orchestrator to implement a change, spawn a reviewer, and keep the
+review feedback visible before you merge. The coder edits; the reviewer checks
+the diff; the Orchestrator decides what still needs work.
 
-前置条件：
+```text
+Ship the settings search bugfix. Use one worker to implement it and another to
+review edge cases before the final report.
+```
 
-- Node.js 22 或更新版本
-- 至少一个支持的 Agent CLI 已经安装好、登录过、在 `PATH` 上可调用
+**Run a parallel bug hunt**
 
-安装并启动 Hive：
+Give several workers separate slices of a flaky behavior: one reads the server
+path, one checks the UI path, one looks for regressions in recent commits. You
+watch the reports converge instead of juggling terminals.
 
-```bash
-npm install -g @tt-a1i/hive
-hive
+```text
+Find why mobile reconnect sometimes stalls. Split server transport, browser UI,
+and recent commit history across separate workers.
 ```
 
-国内网络从 npmmirror 镜像安装更快：
-
-```bash
-npm install -g @tt-a1i/hive --registry=https://registry.npmmirror.com
-```
+**Research, draft, and fact-check without losing the thread**
 
-安装时如果看到 `npm warn allow-scripts` 或 `prebuild-install@7.1.3 deprecated`，先看最后是否显示 `added ... packages`。这些 warning 多数来自 npm 对安装脚本的安全审查，以及 `node-pty` / `better-sqlite3` / `esbuild` 这类原生依赖的二进制安装链路；不代表 Hive 启动失败。下面的故障排查里有逐项解释。
+Let one worker gather sources, another draft, and a reviewer check claims. The
+task graph and reports stay in one workspace, so the handoff is inspectable
+instead of trapped in chat scrollback.
 
-打开终端打印出来的本机地址，通常是 `http://127.0.0.1:3000/`。如果你想指定端口，可以用 `hive --port 4010`。
+```text
+Write a technical note on our release flow. Have one worker collect evidence,
+one draft, and one verify every command and file reference.
+```
 
-升级到最新版本：
+## Try the demo first
 
-```bash
-hive update
-```
+Don't have an agent CLI installed yet? Run `hive`, open the printed URL, and
+click **Try Demo** in the first-run wizard. The demo is a pure client-side
+replay: a fake terminal types through planning, `team spawn`, `team send`,
+worker reports, and `.hive/tasks.md` checkoffs. It does not need network
+access, an installed CLI, or any sign-in, and it never calls demo workspace
+server routes.
 
-`hive update` 会在原位运行 `npm install -g @tt-a1i/hive@latest`，完事后重启 Hive 就能用上新版。如果当初是用 pnpm / yarn 装的 Hive，请用同一个包管理器升级，避免装出第二份。
+## Quick Start
 
-把 Hive 装为应用（可选）：
+Prerequisites:
 
-在 Chrome / Edge / Brave 里打开 `http://127.0.0.1:3000/`，点浏览器地址栏右侧的安装图标即可。装好后 Hive 会以独立窗口启动、有自己的 dock 图标，且 dock 右键菜单上会显示 **添加 Workspace** / **试用演示** 两个快捷入口。Firefox 和 Safari 暂未实现 PWA install-prompt 协议，浏览器地址栏的安装图标只在 Chromium 系浏览器里出现。
+- Node.js 22 or newer.
+- At least one supported agent CLI installed, authenticated, and available on
+  `PATH`.
 
-PWA 只是 UI 壳，Hive 后端仍需要在终端里跑着。如果启动 PWA 时后端没起，会看到 “Hive 后端未启动” 页面，等你跑起 `hive` 后会自动刷新。PWA 的 install scope 按 origin（含端口）划分，所以 `hive --port 4011` 跟 `hive --port 3000` 在浏览器看来是两个独立应用。卸载方法：浏览器地址栏访问 `chrome://apps`，右键 Hive 图标，选 **从 Chrome 中移除…**。
+Install and start Hive:
 
-关闭 PWA 窗口或 tab 时 Hive 会主动请求浏览器弹原生确认对话框，避免关闭快捷键（macOS 上是 Cmd+W、Windows / Linux 上是 Ctrl+W）误关丢失会话。但现代浏览器要求你跟页面"交互过"（点击 / 滚动 / 输入）才会真的弹这个对话框——刚打开 PWA 立刻按关闭快捷键仍会直接关闭，这是浏览器策略，不是 Hive 的 bug。
+```bash
+npm install -g @tt-a1i/hive
+hive
+```
 
-首次使用流程：
+If npm prints `npm warn allow-scripts` or `prebuild-install@7.1.3 deprecated`
+during install, first check whether the command ends with `added ... packages`.
+Those warnings usually come from npm's install-script review plus native
+binary setup for `node-pty`, `better-sqlite3`, and `esbuild`; they do not mean
+Hive failed to install. The troubleshooting section below breaks them down.
 
-1. 选择一个项目目录作为 workspace。
-2. 挑一个 Orchestrator 预设。
-3. Hive 会创建 `<workspace>/.hive/tasks.md`，启动 Orchestrator 的 PTY，把内部的 `team` 命令注入这个 agent 会话。
-4. 在 Team Members 面板里添加 Worker。
-5. 跟 Orchestrator 说一声让它派活，它会用 `team send <worker-name> "<task>"` 发任务，Worker 完事后用 `team report` 回报。
+Open the printed local URL, usually `http://127.0.0.1:3000/`. Use
+`hive --port 4010` when you need a specific local port.
 
-想让 Orchestrator 自己决定团队规模，可以保留 **自动组队** 开关开启（默认开启）：它会按任务需要临时 `team spawn` 合适数量的 coder / tester / reviewer，任务结束后自动收回临时成员。
+To upgrade in place:
 
-想试更强的自动化，可以在右上角设置里开启实验性的 **Workflow** 开关。开启后，Orchestrator 可以编写并运行多 agent workflow，把一个目标拆成 fan-out / review / test 等阶段；顶部的 **Workflows** 面板会显示运行记录、阶段结果、定时任务和停止按钮。Workflow 创建的新 agent 默认使用哪种 CLI、允许使用哪些 CLI，也可以在 Workflows 面板里配置。
+```bash
+hive update
+```
 
-## 工作方式
+`hive update` runs `npm install -g @tt-a1i/hive@latest` in place. Restart any
+in-flight Hive process to pick up the new version. If you installed Hive with
+pnpm or yarn, upgrade through the same package manager — otherwise the new
+npm copy will shadow your existing install.
+
+Install Hive as an app (optional):
+
+Open `http://127.0.0.1:3000/` in Chrome, Edge, or Brave and click the install
+icon at the right edge of the browser's omnibox. The PWA launches in its own
+dock-anchored window without browser chrome and shows **Add Workspace** /
+**Try Demo** shortcuts from the dock right-click menu. Firefox and Safari
+currently don't implement the install-prompt protocol, so the omnibox icon
+only appears in Chromium-based browsers.
+
+The Hive daemon must still be running for the PWA to do anything; if the
+runtime isn't reachable when you launch the app, you'll see a "Hive runtime
+is not running" page that auto-reloads once `hive` is back on `127.0.0.1`.
+The PWA install scope is keyed by origin, so `hive --port 4011` installs as
+a separate app from `hive --port 3000`. To uninstall, visit `chrome://apps`,
+right-click the Hive tile, and choose **Remove from Chrome…**.
+
+Hive asks the browser to confirm before closing the tab or PWA window so an
+accidental close shortcut (Cmd-W on macOS, Ctrl-W on Windows/Linux) doesn't
+drop your session. Modern browsers gate that prompt on prior page interaction
+— if you open the PWA and immediately press the close shortcut without
+clicking or typing anywhere first, it still closes cleanly. That's a browser
+policy, not a Hive bug.
+
+First-run flow:
+
+1. Create a workspace from a project folder.
+2. Choose an Orchestrator preset.
+3. Hive creates `<workspace>/.hive/tasks.md`, starts the Orchestrator PTY, and
+   injects the internal `team` command into the agent session.
+4. Add workers from the Team Members panel.
+5. Ask the Orchestrator to delegate work. It sends tasks with
+   `team send <worker-name> "<task>"`; workers report back with `team report`.
+
+If you want the Orchestrator to size the team itself, leave **Auto-staff**
+enabled (it is on by default). It can `team spawn` the right temporary mix of
+coders, testers, and reviewers for the task, then Hive dismisses those
+temporary workers when their work is done.
+
+For stronger automation, enable the experimental **Workflows** toggle in
+settings. The Orchestrator can then author and run multi-agent workflows that
+fan out across implementation, review, testing, or other stages. The topbar
+**Workflows** panel shows runs, phase results, logs, schedules, and stop
+controls. The same panel also lets you choose which CLI workflow-created
+agents use by default and which CLIs they are allowed to use.
+
+## How It Works
 
 ```text
-浏览器 UI 跑在 127.0.0.1
-  任务 · 团队 · 终端 · 汇报
+Browser UI on 127.0.0.1
+  tasks, team, terminals, reports
           |
           | HTTP + WebSocket
           v
-Hive Runtime
-  SQLite 元数据 · PTY 生命周期 · 任务派单
+Hive runtime
+  SQLite metadata, PTY lifecycle, task dispatch
           |
           +-- Orchestrator PTY
-          |     可调用：team send、team list、team report
+          |     can call: team send, team list, team report
           |
           +-- Worker PTY
-          |     可调用：team report
+          |     can call: team report
           |
           +-- Worker PTY
-                可调用：team report
+                can call: team report
 
-Workspace 任务图：
+Workspace task graph:
   <workspace>/.hive/tasks.md
 ```
 
-三个细节值得记住：
+Three details matter:
 
-- Agent 是真正的 CLI 进程，不是模拟的 subagent。
-- `team` 命令**只**在 Hive 管理的 agent 会话里可用——通过把包内 bin 目录 prepend 到 PATH 实现，不会装成全局命令。
-- 任务图就是 workspace 里的一份 markdown 文件，你可以在编辑器里直接看或者改。
+- Agents are real CLI processes, not simulated subagents.
+- `team` is injected only inside Hive-managed agent sessions by prepending the
+  package's internal bin directory to `PATH`; it is not installed as a global
+  command.
+- The task graph is a markdown file in the workspace, so you can inspect or
+  edit it outside the app.
 
-## Agent 预设
+## Agent Presets
 
-| 预设 | `PATH` 上的命令 | 默认 bypass 模式 | 会话恢复 |
+| Preset | Command expected on `PATH` | Default bypass mode | Session resume |
 | --- | --- | --- | --- |
 | Antigravity CLI | `agy` | `--dangerously-skip-permissions` | `--conversation <session_id>` |
-| Claude Code | `claude` | `--dangerously-skip-permissions`、`--permission-mode=bypassPermissions` | `--resume <session_id>` |
+| Claude Code | `claude` | `--dangerously-skip-permissions`, `--permission-mode=bypassPermissions` | `--resume <session_id>` |
 | Codex | `codex` | `--dangerously-bypass-approvals-and-sandbox` | `resume <session_id>` |
-| OpenCode | `opencode` | 由 `~/.config/opencode/opencode.json` 配置 | `--session <session_id>` |
+| OpenCode | `opencode` | Config-driven in `~/.config/opencode/opencode.json` | `--session <session_id>` |
 | Gemini | `gemini` | `--yolo` | `--resume <session_id>` |
 | Hermes | `hermes` | `--yolo` | `--resume <session_id>` |
 | Qwen Code | `qwen` | `--approval-mode yolo` | `--resume <session_id>` |
-| Cursor CLI | `cursor` | `--force` | 暂未自动捕获 session id |
-| Grok Build | `grok` | `--always-approve` | 暂未自动捕获 session id |
-| 自定义 | 任意可执行文件 | 自己配 | 自己配 |
-
-Hive 不替你安装这些 CLI。请在启动 Hive 的同一个 shell 环境里先装好、登录好。
-
-## Hive 提供什么
-
-- Workspace 侧边栏，方便在多个本机项目之间切换。
-- Orchestrator 和 Worker 终端都是真实 PTY 支撑的。
-- Add Worker 预置 coder / reviewer / tester 等角色模板，也支持完全自定义 prompt 与命令——把任何 CLI agent 编排成你需要的角色。
-- 自动组队（实验性，默认开启）：Orchestrator 可以根据任务动态创建临时 coder / tester / reviewer，完成后自动回收。
-- Workflows（实验性，默认关闭）：Orchestrator 可以运行多阶段、多 agent 的 workflow，Hive 在 Workflows 面板里展示运行、日志、结果、定时任务和停止控制。
-- Workflow CLI 策略：为 workflow 创建的 agent 选择默认 CLI，并限制允许使用的 CLI，避免脚本误启未配置的 agent。
-- `.hive/tasks.md` 编辑器，带外部文件冲突处理。
-- PTY 后台保留 + 尽力使用各 CLI 原生 session 恢复。
-- 升级后的 What's New 弹窗，用简短 release highlights 告诉你新版改了什么。
-- 元数据存在本机 SQLite，Windows 默认在 `%APPDATA%\hive`，macOS / Linux 默认在 `~/.config/hive`，也可以通过 `$HIVE_DATA_DIR` 指定。
-
-Hive **不**提供 sandbox 隔离、多用户认证，也不自带任何 agent 模型。它只负责调度你已经在用的本机 CLI。
-
-## 远程访问（可选，默认关闭）
-
-如果想在外面用手机查看、操作正在本机跑着的 Hive，可以开启可选的 **Remote access**。开启后，手机浏览器在网关上用 GitHub / Google 登录、跟桌面完成一次配对，就能通过端到端加密隧道访问**完整**的 Hive Web UI——已配对的手机是与本地浏览器**等权**的受信任设备。
+| Cursor CLI | `cursor` | `--force` | Session id capture not wired yet |
+| Grok Build | `grok` | `--always-approve` | Session id capture not wired yet |
+| Custom | Any executable | User configured | User configured |
 
-需要清楚的几点：
+Hive does not install these CLIs for you. Install and authenticate them in the
+same shell environment you use to start Hive.
 
-- **默认关闭**。不开就没有任何出站连接、没有监听，行为跟现在一模一样。
-- **需要一个网关**。隧道要经过一个网关中转（你本机的 daemon 主动出站连它，不开端口、不动路由器）。网关地址可配置：可以 **自己 self-host** 一个 Cloudflare Workers 网关，也可以接一个已部署的网关。Hive **没有**现成的一键托管服务——这一步要你自己搭。
-- **数据和执行永远在本机**。网关只做身份（OAuth 登录）和路由，看不到明文——它只转发密文。网关挂了，本机 `127.0.0.1` 上的一切照常。
-- **端到端加密**。手机 ↔ daemon 之间所有数据帧端到端加密，网关只见密文和路由头。诚实的边界：手机端的加密代码由网关分发（web 端 E2E 的经典局限，跟 Proton / WhatsApp Web 同类），缓解手段是 SRI + 版本化 bundle + PWA 缓存形成 TOFU。我们不宣传"网关被攻破也绝对安全"。
-- **信任根在桌面**。新设备配对必须人在电脑前确认（桌面弹窗 + 6 位 SAS 短码校验）；已配对手机不能凭自己批准新设备。设备随时可吊销。
+### CLI support tiers
 
-完整的开启、登录（`hive remote login`）、配对、吊销和 self-host 网关步骤见 [docs/remote-access.md](docs/remote-access.md)。
-
-## 平台支持
-
-| 平台 | 状态 | 说明 |
+| Tier | CLIs | Commitment |
+| --- | --- | --- |
+| Tier 1 | Claude Code, Codex | Minimum compatibility report in CI (`pnpm compat:cli:report`): Node 22, `node-pty`, `better-sqlite3`, and CLI version detection when installed. |
+| Tier 2 | Gemini, OpenCode, Qwen Code, Hermes, Cursor CLI, Grok Build, Antigravity CLI | Built-in presets and manual smoke coverage; upstream CLI changes may require user reports before Hive catches up. |
+| Custom | Any executable | User-maintained command, args, and auth behavior. Hive preserves the PTY/session wrapper but cannot promise CLI-specific compatibility. |
+
+## What Hive Provides
+
+- Workspace sidebar for switching between local projects.
+- Orchestrator and worker terminals backed by real PTYs.
+- Add Worker flow with role presets for coder, reviewer, tester, and fully
+  custom prompts and commands — wire any CLI agent into the role you need.
+- Auto-staff (experimental, on by default): the Orchestrator can create
+  temporary coders, testers, and reviewers based on the task, and Hive cleans
+  them up after their dispatch reports back.
+- Workflows (experimental, off by default): the Orchestrator can run
+  multi-stage, multi-agent workflows while Hive shows runs, logs, results,
+  schedules, and stop controls in the Workflows panel.
+- Workflow CLI policy: choose the default CLI for workflow-created agents and
+  restrict which CLIs workflow scripts may launch.
+- `.hive/tasks.md` editor with external-file conflict handling.
+- Background PTY preservation and best-effort native session resume.
+- A What's New dialog after upgrades with curated release highlights.
+- Local SQLite metadata under `%APPDATA%\hive` on Windows and `~/.config/hive`
+  on macOS / Linux by default, or `$HIVE_DATA_DIR` when set.
+
+Hive does not provide sandboxing, multi-user auth, or any bundled agent
+model. It coordinates the CLIs you already run locally.
+
+## Remote Access (optional, off by default)
+
+If you want to reach your running Hive from your phone while you're away,
+turn on the optional **Remote access** feature. Once enabled, a phone browser
+logs in at a gateway with GitHub or Google, pairs once with the desktop, and
+then reaches the **full** Hive web UI over an end-to-end encrypted tunnel — a
+paired phone is a trusted device with the **same authority** as the local
+browser.
+
+A few things to be clear about:
+
+- **Off by default.** With it off there are no outbound connections and
+  nothing listening — behavior is exactly what it is today.
+- **Requires a gateway.** The tunnel is relayed through a gateway (your
+  local daemon dials out to it — no open ports, no router changes). The
+  gateway URL is configurable: **self-host** a Cloudflare Workers gateway,
+  or point at one that's already deployed. There is **no turnkey hosted
+  service** — you stand the gateway up yourself.
+- **Data and execution stay local.** The gateway only does identity (OAuth
+  login) and routing; it never sees plaintext, only relays ciphertext. If the
+  gateway is down, everything on local `127.0.0.1` keeps working.
+- **End-to-end encrypted.** Every data frame between the phone and the daemon
+  is end-to-end encrypted; the gateway sees only ciphertext and routing
+  headers. The honest caveat: the phone's crypto code is served by the gateway
+  (the classic limit of web-delivered E2E, like Proton or WhatsApp Web),
+  mitigated by SRI, versioned bundles, and PWA caching that forms a TOFU
+  baseline. We don't claim "secure even if the gateway is compromised."
+- **Trust root stays on the desktop.** Pairing a new device must be confirmed
+  in person at the computer (a desktop dialog plus a 6-digit SAS check); a
+  paired phone can't approve new devices on its own. Devices can be revoked at
+  any time.
+
+See [docs/remote-access.md](docs/remote-access.md) for the full enable,
+login (`hive remote login`), pairing, revoke, and self-host-gateway walkthrough.
+
+## Platform Support
+
+| Platform | Status | Notes |
 | --- | --- | --- |
-| macOS | Tier 1 | 主要开发与发版验证平台。 |
-| Linux | Tier 1 | CI 验证。原生目录选择器依赖 `zenity`，没有也可以手动粘贴路径。 |
-| Windows | Tier 2 | **原生支持，无需 WSL**。CI 跑 Windows 测试子集（`pnpm test:windows`）和打包安装冒烟，包内含 `team.cmd`。按 best-effort 维护：每次发版前的完整 Windows 验证仍是手动步骤。 |
+| macOS | Tier 1 | Main development and release verification target. |
+| Linux | Tier 1 | CI verified. Native folder picking expects `zenity`; manual path entry works without it. |
+| Windows | Tier 2 | Native, no WSL required. CI runs `pnpm test:windows`, packaged-install smoke, and `pnpm compat:cli:report` on `windows-latest` to catch `node-pty` / `better-sqlite3` prebuild failures. Workspace selection uses Hive's in-browser server filesystem picker by default, starting at "This PC" so other drives are visible; the package includes `team.cmd`. |
 
-所有平台都需要 Node.js 22+。Hive 依赖 `node-pty` 和 `better-sqlite3` 这类原生包，没有预编译二进制时需要你本机有原生构建工具链。
+All platforms require Node.js 22+. Hive depends on native packages
+(`node-pty` and `better-sqlite3`), so native install tooling may be required
+when prebuilt binaries are unavailable.
 
-## 安全模型
+## Safety Model
 
-Hive 是本机开发工具，**不是**托管服务。
+Hive is a local development tool, not a hosted service.
 
-- Runtime 只监听 `127.0.0.1`。不要把 Hive 端口通过公网隧道、反向代理或任何共享网络接口暴露出去。
-- 内置预设会主动传 CLI 的 non-interactive / bypass flag。Worker 在选中的 workspace 里有跟启动 shell **同等**的执行权限——把它当成"会自动跑命令的你自己"。
-- 只打开你信任的 workspace。Worker 拥有跟你登录账户一样的文件系统访问权限。
-- Agent token 是 session 级的，由本机 runtime 生成，注入到 agent 进程环境变量里，**不**用于跨网络通信。
-- Hive 不做多用户认证。任何能从本机访问到端口的进程都视为可信本地访问。
-- 浏览器 UI token 只是本机会话保护，不是用来防同一系统账户下其他进程的安全边界。
+- The runtime binds to `127.0.0.1`. Do not expose the Hive port through a public
+  tunnel, reverse proxy, or shared network interface.
+- Built-in presets intentionally use each CLI's non-interactive or bypass mode
+  where available. Treat workers as able to run arbitrary shell commands inside
+  the selected workspace.
+- Open only trusted workspaces. A worker has the same filesystem access as the
+  shell account running Hive.
+- Agent tokens are session scoped, generated by the local runtime, injected into
+  agent process environments, and not intended as internet-facing credentials.
+- Hive has no multi-user authentication boundary. Treat same-machine processes
+  that can reach the local port as trusted local access.
+- The browser UI token is a local session guard, not protection against other
+  processes already running as your OS user.
 
-在敏感仓库里用 Hive 之前，请先读 [SECURITY.md](SECURITY.md)。
+Read [SECURITY.md](SECURITY.md) before using Hive with sensitive repositories.
 
-## 数据位置
+## Data Locations
 
-| 数据 | 位置 |
+| Data | Location |
 | --- | --- |
-| Runtime 元数据 | Windows: `%APPDATA%\hive`；macOS / Linux: `~/.config/hive`；或 `$HIVE_DATA_DIR` |
-| Workspace 任务图 | `<workspace>/.hive/tasks.md` |
-| 内部 `team` 命令 | 包内 `dist/bin/`，通过 PATH 注入 PTY |
-| Web UI 资源 | 由 runtime 从包内 `web/dist` 直接服务 |
+| Runtime metadata | Windows: `%APPDATA%\hive`; macOS / Linux: `~/.config/hive`; or `$HIVE_DATA_DIR` |
+| Workspace tasks | `<workspace>/.hive/tasks.md` |
+| Internal `team` command | Packaged under `dist/bin/`, injected into PTYs |
+| Web UI assets | Served by the runtime from the packaged `web/dist` build |
 
-## 故障排查
+## Troubleshooting
 
-**找不到 Agent CLI**
+**Agent CLI not found**
 
-确认选中的命令已经安装好、登录好、在启动 Hive 那个 shell 里能直接调用，且在 `PATH` 上。
+Check that the selected command is installed, authenticated, executable from the
+same shell, and available on `PATH`.
 
-**端口被占用**
+**Port already in use**
 
-换个本机端口启动：
+Start Hive with another local port:
 
 ```bash
 hive --port 4020
 ```
 
-**原生包构建失败**
+**Native package install fails**
 
-Hive 依赖 `node-pty` 和 `better-sqlite3`，它们用原生二进制。确认 Node.js 22+，清干净 package manager 缓存，并准备好你平台的构建工具（macOS Xcode CLI、Linux build-essential + python3、Windows VS Build Tools）。
+Hive depends on `node-pty` and `better-sqlite3`, which use native binaries. Use
+Node.js 22+, keep your package manager cache clean, and verify your platform
+build tools are available.
 
-安装成功但看到 npm warning 时，可以按来源判断：
+When install succeeds but npm prints warnings, read them by source:
 
-| warning | 来源 | 处理 |
+| warning | Source | What to do |
 | --- | --- | --- |
-| `allow-scripts @tt-a1i/hive` | Hive 的 postinstall 会修正打包后的 native/PTY helper 权限。 | 安装成功后可忽略。 |
-| `allow-scripts better-sqlite3` | SQLite 原生绑定需要下载预编译二进制，失败时会本机构建。 | 安装成功后可忽略；失败再检查构建工具链。 |
-| `allow-scripts node-pty` | 终端 PTY 原生绑定需要准备平台二进制。 | 安装成功后可忽略；失败再检查构建工具链。 |
-| `allow-scripts esbuild` | esbuild 会校验/选择当前平台的二进制包。 | 安装成功后可忽略。 |
+| `allow-scripts @tt-a1i/hive` | Hive's postinstall fixes executable bits for packaged native / PTY helpers. | Safe to ignore after a successful install. |
+| `allow-scripts better-sqlite3` | SQLite native bindings download a prebuilt binary, then fall back to local build. | Safe to ignore after success; check build tools only if install fails. |
+| `allow-scripts node-pty` | The terminal PTY binding prepares platform binaries. | Safe to ignore after success; check build tools only if install fails. |
+| `allow-scripts esbuild` | esbuild verifies/selects the binary package for the current platform. | Safe to ignore after a successful install. |
 
-这是 npm 11 的安装脚本审查提示。当前 npm 版本仍是提示性质，未来可能要求用户显式批准这些脚本。你想审查时可以运行 `npm approve-scripts --allow-scripts-pending` 查看待审列表。
+This is npm 11's install-script review notice. The current npm release still
+treats it as advisory; future npm versions may require explicit approval. To
+review the list yourself, run `npm approve-scripts --allow-scripts-pending`.
 
-安装时如果看到 `prebuild-install@7.1.3` 的 deprecated warning，可以忽略。它来自 `better-sqlite3` 的原生二进制下载链路，只是上游安装器维护状态提示，不代表 Hive 安装失败，也不会影响运行。
+If npm prints a deprecated warning for `prebuild-install@7.1.3`, it is safe to
+ignore. The warning comes from `better-sqlite3`'s native binary download chain;
+it is an upstream installer maintenance notice, not a Hive install failure, and
+does not affect runtime behavior.
 
-**Linux 上目录选择器不弹**
+**Folder picker does not open on Linux**
 
-装 `zenity`，或者直接在对话框里粘路径。
+Install `zenity`, or paste the workspace path manually.
 
-**Windows 上目录选择器**
+**Folder picker on Windows**
 
-Windows 版默认使用浏览器内的服务器文件系统浏览器来添加 Workspace，不再弹 PowerShell 原生目录选择器。浏览器会从“此电脑”开始列出可访问盘符，所以可以进入 `C:\`、`D:\` 等其他盘；如果目标目录不在浏览器列表里，可以展开“高级：粘贴路径”直接输入绝对路径。
+Hive uses the in-browser server filesystem browser by default on Windows
+instead of launching the PowerShell native folder picker. This avoids the
+system dialog getting hidden behind the browser window. The browser starts at
+"This PC" and lists accessible drives, so `C:\`, `D:\`, and other drives are
+reachable. If the target directory is not visible in the browser list, expand
+"Advanced: paste path" and enter the absolute path directly.
 
-**Tasks 文件冲突 banner 出现**
+**Tasks file conflict banner appears**
 
-Hive 检测到磁盘上的 `.hive/tasks.md` 比 UI 里的新。`Reload` 接受磁盘版本，`Keep Local` 保留 UI 编辑并覆盖保存。
+Hive detected a newer `.hive/tasks.md` on disk. Use `Reload` to accept the file
+from disk, or `Keep Local` to keep the editor contents and save again.
 
-**Worker 卡在 `working` 状态**
+**Worker appears stuck in `working`**
 
-Hive 不通过进程活动猜测任务完成。Worker 只有在调 `team report` 时才会回到 `idle`。如果它确实卡了，从 UI 里 Stop 或 Restart。
+Hive does not guess task completion from process activity. Workers move back to
+`idle` when they call `team report`. If a worker is blocked, stop or restart it
+from the UI.
 
-## 开发
+## Development
 
 ```bash
 pnpm install
 pnpm dev
 ```
 
-开发模式下 runtime 跑在 `127.0.0.1:4010`，Vite 跑在 `127.0.0.1:5180`，把 API 和 WebSocket 代理到 runtime。
+Development mode runs the runtime on `127.0.0.1:4010`; Vite runs on
+`127.0.0.1:5180` and proxies API and WebSocket traffic to the runtime.
 
-常用命令：
+Useful checks:
 
 ```bash
 pnpm check
@@ -270,40 +415,38 @@ pnpm build
 pnpm test
 ```
 
-预演 production 构建：
+Production-style local run:
 
 ```bash
 pnpm build
 node dist/src/cli/hive.js --port 4010
 ```
 
-Production 模式下 runtime 直接服务构建好的 web UI，不需要单独的 Vite。
+The production server serves the built web UI directly. No Vite server is
+needed after `pnpm build`.
 
-## 发布
+## Release
 
-维护者本地预演：
+Maintainer dry run:
 
 ```bash
 pnpm release:dry
 ```
 
-完整 tag 发版清单见 [docs/release.md](docs/release.md)，里面包含 Windows 手动 smoke 步骤。
+See [docs/release.md](docs/release.md) for the full tagged release checklist,
+including manual Windows smoke steps.
 
-带 `v*` 的 tag push 会触发 GitHub Actions release workflow。workflow 会在 macOS、Ubuntu、Windows 三平台验证，然后用 `NPM_TOKEN` 发布到 npm。
+Tag pushes matching `v*` run the GitHub Actions release workflow. The workflow
+verifies macOS, Ubuntu, and Windows, then publishes to npm with `NPM_TOKEN`.
 
-## 状态
+## Status
 
-Hive 目前处于 alpha 阶段，核心流程已可用。当前重点是继续打磨多 Agent 协作体验、Windows 支持和更清晰的调度可观测性。欢迎试用、提 issue——反馈会直接影响后续节奏。
+Hive is in alpha. The core flow is usable today; current work focuses on
+polishing the multi-agent collaboration workflow, Windows support, and clearer
+orchestration observability. Try it out and open issues — feedback shapes what
+gets prioritized next.
 
-## 交流群
-
-有问题、想反馈，或者就想聊聊 Agent 协作，欢迎进 QQ 群：**Ai Native 交流群**（群号 `1098836554`）。
-
-<p align="center">
-  <img src="./assets/qq-group.jpg" width="240" alt="Ai Native 交流群 QQ 群二维码，群号 1098836554" />
-</p>
-
-## 在路上：跨 Agent 的长时记忆
+## On the roadmap: cross-agent long-term memory
 
 <p align="center">
   <a href="https://github.com/EverMind-AI/EverOS">
@@ -311,45 +454,53 @@ Hive 目前处于 alpha 阶段，核心流程已可用。当前重点是继续
   </a>
 </p>
 
-单 agent 现在已经各有各的"记忆"了——但风格其实差很多：
-
-- **Claude Code 的 [Auto Dream](https://claudefa.st/blog/guide/mechanics/auto-dream)（俗称"做梦"）** 走 **离线批处理** 路线：`/dream` 触发（或 24h 自动），Claude 在云端把 JSONL 会话归并去重抽模式，产出新版本 memory 库给你审查再采纳——像人类的 REM 睡眠，**清醒 / 睡眠二相**。
-- **Hermes Agent** 反过来走 **嵌入式 / 在场** 路线：不睡，每 N 轮对话后台 fork 一个 sub-agent review，结果直接落进本地的 **多层记忆**——`MEMORY.md`（事实/规则）·`USER.md`（用户画像）·SQLite + FTS5（情景检索）·Honcho（第三人称表征）·`skills/`（程序性记忆）——而且 agent 允许边走边改自己的 skill 文件，记忆和能力是一回事。
+Single-agent memory already exists, but the styles diverge:
 
-但 **这些都是单 agent 内部的记忆**。Hive 是多 agent 协作工作台，正在把它们打通：让整支团队 **共享一座长时记忆库**——Worker A 今天踩的坑，明天 Orchestrator 派给 Worker B 时能自动调来当上下文。
+- **Claude Code's [Auto Dream](https://claudefa.st/blog/guide/mechanics/auto-dream)** is **batch / offline** — invoked via `/dream` (or on a 24h timer), Claude consolidates JSONL session logs in the cloud, merges duplicates, extracts patterns, and proposes a new memory file for you to review and adopt. REM-sleep style, with a clean wake/sleep separation.
+- **Hermes Agent** runs the opposite playbook — **embedded and in-stride**. Every N turns it forks a background sub-agent to review the recent exchange and writes directly into a **multi-organ local store**: `MEMORY.md` (facts/rules) · `USER.md` (who-you-are) · SQLite + FTS5 (episodic search) · Honcho (third-person model) · `skills/` (procedural memory). The agent is allowed to edit its own skill files in stride — memory and capability are the same thing.
 
-第一阶段先走本地优先：Hive 用 SQLite 保存协作历史和显式团队记忆，支持 `team recall` / `team memory`、派单和恢复时的自动注入、`<workspace>/.hive/memory.md` 单向导出，以及 Dream 整理。Dream 会按 workspace 空闲和增量阈值创建维护 run，把有界协议窗口注入 Orchestrator；Orchestrator 可自己整理，或派 worker 只读评审并回报建议，最后由 Orchestrator 用 `team memory apply --run <id> --stdin` 提交去重/改写/归档/新增。每次 run 保留 diff 报告和回滚入口。
+But these are all **per-agent** memories. Hive coordinates *teams* of agents, so the next step is wiring them together: let the whole team **share one long-term memory store** — what Worker A learned today becomes context the Orchestrator can dispatch to Worker B tomorrow.
 
-下一阶段再接 **[EverOS](https://github.com/EverMind-AI/EverOS)**（[EverMind](https://evermind.ai/) 出品的开源长时记忆 OS，目前在 LoCoMo / LongMemEval / HaluMem 三个记忆 benchmark 上 SOTA）这类外部 provider。EverOS 的四层架构（Agentic / Memory / Index / API+MCP）跟 Hive 的多 PTY 协作模型很搭：每个 agent 各跑各的 CLI session，团队级的事实和模式凝在 provider，Orchestrator 派单时一并喂给 worker。
+We're planning to back this with **[EverOS](https://github.com/EverMind-AI/EverOS)**
+— an open-source long-term memory OS from [EverMind](https://evermind.ai/),
+currently SOTA on the LoCoMo / LongMemEval / HaluMem memory benchmarks.
+Its four-layer architecture (Agentic / Memory / Index / API+MCP) maps
+cleanly onto Hive's multi-PTY model: each agent keeps its in-CLI memory,
+team-level facts flow through EverOS, and the Orchestrator joins both
+when dispatching.
 
-进度跟踪：[#6](https://github.com/tt-a1i/hive/issues/6)——想看进度或提建议，在 issue 留 +1。
+Track progress at [#6](https://github.com/tt-a1i/hive/issues/6) — drop a
++1 or comment with your use case to influence priority.
 
-## 另一种形态：squad
+## A different form factor: squad
 
-如果你更喜欢 **纯 CLI、零后台进程、能直接在 SSH 进的远端服务器上跑** 的形态，[squad](https://github.com/mco-org/squad) 是同一个想法的另一条路线——SQLite 当通信层，每个 agent 各自开一个终端。两个项目互不替代，按工作流挑就行：
+If you'd rather have **pure CLI, zero background process, and the ability to
+run on a remote SSH box**, [squad](https://github.com/mco-org/squad) takes the
+same idea down a different path — SQLite as the protocol layer, one terminal
+per agent. The two projects don't replace each other; pick by workflow:
 
-- **Hive** — 想要可视化工作台、一键重启、侧边栏切 workspace、给团队演示
-- **squad** — 活在 tmux 里、SSH 远端开发、不想跑额外后台进程、Windows server
+- **Hive** — visual workbench, one-click restart, workspace sidebar, easier to demo to a team
+- **squad** — lives in tmux, SSH remote dev, no extra background process, Windows servers
 
-## 鸣谢
+## Acknowledgements
 
-Hive 的"模板市场"内置了两份社区角色 prompt 库的快照，两份都按各自上游的 MIT 许可分发：
+The built-in template marketplace ships snapshots of two community-maintained prompt libraries, both distributed under their upstream MIT licenses:
 
-- 英文版（界面切到 EN 时使用）：[`msitarzewski/agency-agents`](https://github.com/msitarzewski/agency-agents)
-- 中文版（界面切到中文时使用）：[`jnMetaCode/agency-agents-zh`](https://github.com/jnMetaCode/agency-agents-zh)
+- English (used when the UI is set to EN): [`msitarzewski/agency-agents`](https://github.com/msitarzewski/agency-agents)
+- Chinese (used when the UI is set to 中文): [`jnMetaCode/agency-agents-zh`](https://github.com/jnMetaCode/agency-agents-zh)
 
-上游内容未做修改，许可证文本保留在 `vendor/marketplace/<lang>/LICENSE`；快照通过 `pnpm sync:marketplace` 在 hive 发版前刷新。
+Upstream content is mirrored verbatim, license files are kept under `vendor/marketplace/<lang>/LICENSE`, and snapshots are refreshed by `pnpm sync:marketplace` before each Hive release.
 
 ## License
 
-Hive 是 **source-available（源码可得）** 项目，以 **Business Source License 1.1（BUSL-1.1）** 提供源码。它**不是** OSI 定义的开源（open source）许可，我们也不自称开源项目。
+Hive is **source-available under the Business Source License 1.1 (BUSL-1.1)**. It is **not** open source as defined by the OSI, and we don't describe it as such.
 
 ### License FAQ
 
-**为什么不是 OSI 开源？** BUSL-1.1 对生产使用附带一条限制（见下条），不满足开放源代码定义的要求——BUSL 许可文本自己也写明它 "is not an Open Source license"。与其模糊表述，我们选择如实写 source-available。
+**Why isn't it OSI open source?** BUSL-1.1 places one restriction on production use (next answer), which keeps it outside the Open Source Definition — the BUSL license text itself states it "is not an Open Source license". Rather than blur that line, we say source-available plainly.
 
-**个人 / 团队日常使用受影响吗？** 不受影响。[LICENSE.BSL](LICENSE.BSL) 的 Additional Use Grant 明确允许生产使用，唯一例外是：以收费或其他营收安排（含付费支持等）向第三方提供托管 / 嵌入的 Hive、且与 Hive 的多 CLI agent 编排产品形成竞争。个人使用、组织内部部署、嵌入非竞争产品、非商业 fork 都不属于"竞争性产品"。
+**Does it affect personal or team use?** No. The Additional Use Grant in [LICENSE.BSL](LICENSE.BSL) explicitly allows production use; the only carve-out is offering Hive to third parties — hosted or embedded, on a paid basis or under any other revenue-generating arrangement (including paid support) — in a way that competes with Hive's multi-CLI-agent orchestration product. Personal use, internal deployment within your organization, embedding into a non-competitive product, and non-commercial forks are all fine.
 
-**以后会变开源吗？** 会。每个版本在 Change Date（2030-05-16）或该版本首次公开发布满四年（以先到者为准）自动转为 **Apache License 2.0**。
+**Will it become open source later?** Yes. Each version converts to the **Apache License 2.0** on the Change Date (2030-05-16) or four years after that version's first public release, whichever comes first.
 
-详细条款以 [LICENSE.BSL](LICENSE.BSL) 为准。Fork 或再分发版本必须保留 [NOTICE](NOTICE)、[LICENSE.BSL](LICENSE.BSL) 和相关许可证文件。Hive 名称、logo 和视觉识别不随源码许可证授权；品牌使用边界见 [TRADEMARK.md](TRADEMARK.md)。
+See [LICENSE.BSL](LICENSE.BSL) for the exact terms. Forks and redistributions must preserve [NOTICE](NOTICE), [LICENSE.BSL](LICENSE.BSL), and the applicable license files. The Hive name, logo, and visual identity are not licensed by the source license; see [TRADEMARK.md](TRADEMARK.md) for brand usage boundaries.