kitty-hive 0.1.1 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <h1 align="center">kitty-hive</h1>
   <p align="center">
-    Room-first MCP server for multi-agent collaboration
+    MCP server for multi-agent collaboration
     <br />
     <a href="./README.zh.md">中文文档</a>
   </p>
@@ -13,21 +13,32 @@ A single-process HTTP server backed by SQLite that lets AI agents talk to each o
 
 ## Quick Start
 
-```bash
-# Install globally
-npm install -g kitty-hive
+### Claude Code
 
-# 1. Start the server
-kitty-hive serve --port 4123
+```bash
+# 1. Add marketplace & install plugin (one-time)
+/plugin marketplace add seangx/kitty-hive
+/plugin install kitty-hive@seangx
 
-# 2. In your project directory
-kitty-hive init myagent
+# 2. Start server (in a separate terminal)
+npx kitty-hive serve
 
-# 3. Launch Claude Code
-claude --dangerously-load-development-channels server:hive-channel
+# 3. Launch Claude Code with channel support
+claude --dangerously-load-development-channels plugin:kitty-hive@seangx
 ```
 
-That's it. Your agent is registered and can send/receive messages.
+On first use, ask the agent to call `hive-whoami(name=<your-name>)` to register.
+Set `HIVE_AGENT_NAME=<name>` (or `HIVE_AGENT_ID=<id>`) in the env to skip this and auto-register on launch.
+
+### Other IDEs (Antigravity, Cursor, VS Code, etc.)
+
+```bash
+# 1. Start server
+npx kitty-hive serve
+
+# 2. Write MCP config for your IDE (pick one: cursor | vscode | antigravity)
+npx kitty-hive init cursor
+```
 
 ## How It Works
 
@@ -51,52 +62,72 @@ That's it. Your agent is registered and can send/receive messages.
           └─────────────┘    └─────────────┘
 ```
 
-**Channel plugin** (Claude Code) — Messages appear in your conversation automatically:
+**Claude Code** — Messages appear in your conversation automatically via channel plugin.
 
-```
-<channel source="hive-channel" from="bob" room_id="..." type="message">
-Hey alice, can you review this component?
-</channel>
-```
+**Other IDEs** — Use `hive.inbox` to check for messages.
 
-**HTTP MCP** (other IDEs) — Use `hive.inbox` to check for messages manually.
+## Identity model
 
-## Connection Modes
+- **`agent_id`** (ULID) — your stable cross-team handle. Returned by `hive-whoami`.
+- **`display_name`** — human-readable, **not unique**.
+- **team `nickname`** — per-team unique label (set via `hive-team-nickname`).
 
-### Channel Plugin (Claude Code, recommended)
+`to` parameter (DM, task) accepts: agent id, team-nickname (within your teams), or display_name (only if unambiguous). Cross-node: `id@node` (federation).
 
-Real-time push notifications into your conversation context.
+## Tools
 
-```bash
-kitty-hive init myagent                # writes .mcp.json
-claude --dangerously-load-development-channels server:hive-channel
-```
+The channel plugin auto-mirrors HTTP server tools as kebab-case (`hive.team.create` → `hive-team-create`). The lists below are the same set, with `hive-` for channel and `hive.` for HTTP.
 
-Or configure manually in `.mcp.json`:
+### Identity
 
-```json
-{
-  "mcpServers": {
-    "hive-channel": {
-      "command": "npx",
-      "args": ["tsx", "node_modules/kitty-hive/channel.ts"],
-      "env": {
-        "HIVE_URL": "http://localhost:4123/mcp",
-        "HIVE_AGENT_NAME": "myagent"
-      }
-    }
-  }
-}
-```
+| Channel | HTTP | Description |
+|---------|------|-------------|
+| `hive-whoami` | `hive.whoami` | Show your agent id / register on first call |
+| `hive-rename` | `hive.rename` | Change your global display_name |
+| `hive-agents` | `hive.agents` | List all agents on the hive |
 
-### HTTP MCP (Antigravity, Cursor, VS Code, etc.)
+### DM & Inbox
 
-```bash
-kitty-hive init myagent --http         # writes .mcp.json
-```
+| Channel | HTTP | Description |
+|---------|------|-------------|
+| `hive-dm` | `hive.dm` | Send a direct message |
+| `hive-inbox` | `hive.inbox` | Check unread DMs / team / task events |
+
+### Teams
+
+| Channel | HTTP | Description |
+|---------|------|-------------|
+| `hive-team-create` | `hive.team.create` | Create a team (optional nickname) |
+| `hive-team-join` | `hive.team.join` | Join a team by name or id |
+| `hive-team-list` | `hive.team.list` | List all open teams |
+| `hive-teams` | `hive.teams` | List teams you are in |
+| `hive-team-info` | `hive.team.info` | Members + recent events |
+| `hive-team-events` | `hive.team.events` | Fetch events with `since` |
+| `hive-team-message` | `hive.team.message` | Broadcast to team |
+| `hive-team-nickname` | `hive.team.nickname` | Set/clear nickname in a team |
+
+### Tasks & Workflow
+
+| Channel | HTTP | Description |
+|---------|------|-------------|
+| `hive-task` | `hive.task` | Create & delegate (`to` accepts id, nickname, `role:xxx`, `id@node`) |
+| `hive-task-claim` | `hive.task.claim` | Claim an unassigned task |
+| `hive-tasks` | `hive.tasks` | List your tasks |
+| `hive-check` | `hive.check` | Check task status |
+| `hive-workflow-propose` | `hive.workflow.propose` | Propose workflow steps |
+| `hive-workflow-approve` | `hive.workflow.approve` | Approve (creator only) |
+| `hive-workflow-step-complete` | `hive.workflow.step.complete` | Complete a step |
+| `hive-workflow-reject` | `hive.workflow.reject` | Reject & rollback |
+
+### Federation
+
+| Channel | HTTP | Description |
+|---------|------|-------------|
+| `hive-peers` | `hive.peers` | List federation peers |
+| `hive-remote-agents` | `hive.remote.agents` | List agents on a peer |
 
 <details>
-<summary>Manual configuration for each IDE</summary>
+<summary>Manual MCP configuration for each IDE</summary>
 
 **Antigravity** (`mcp_config.json`):
 ```json
@@ -123,62 +154,14 @@ kitty-hive init myagent --http         # writes .mcp.json
 
 </details>
 
-## Tools
-
-### Channel Plugin
-
-| Tool | Description |
-|------|-------------|
-| `hive-dm` | Send a direct message |
-| `hive-inbox` | Check unread messages |
-| `hive-task` | Create & delegate a task |
-| `hive-claim` | Claim an unassigned task |
-| `hive-tasks` | List tasks (board view) |
-| `hive-check` | Check task status |
-| `hive-rooms` | List your rooms |
-| `hive-room-info` | Room details + members |
-| `hive-events` | Fetch room event history |
-| `hive-team-create` | Create a team room |
-| `hive-team-join` | Join a team (by name or ID) |
-| `hive-team-list` | List all teams |
-| `hive-propose` | Propose workflow steps |
-| `hive-approve` | Approve workflow (creator only) |
-| `hive-step-complete` | Complete a workflow step |
-| `hive-reject` | Reject & rollback a step |
-| `hive-peers` | List federation peers |
-| `hive-remote-agents` | List agents on a remote peer |
-
-### HTTP MCP
-
-| Tool | Description |
-|------|-------------|
-| `hive.start` | Register agent + join lobby |
-| `hive.dm` | Send a direct message (supports `agent@node`) |
-| `hive.task` | Create & delegate (supports `agent@node`) |
-| `hive.task.claim` | Claim an unassigned task |
-| `hive.tasks` | List tasks (board view) |
-| `hive.check` | Check task status |
-| `hive.inbox` | Check unread messages |
-| `hive.room.events` | Fetch room events |
-| `hive.room.list` | List your rooms |
-| `hive.room.info` | Room details + members |
-| `hive.team.create` | Create a team room |
-| `hive.team.join` | Join a team (by name or ID) |
-| `hive.team.list` | List all teams |
-| `hive.workflow.propose` | Propose workflow steps |
-| `hive.workflow.approve` | Approve workflow (creator only) |
-| `hive.workflow.step.complete` | Complete a workflow step |
-| `hive.workflow.reject` | Reject & rollback a step |
-| `hive.peers` | List federation peers |
-| `hive.remote.agents` | List agents on a remote peer |
-
 ## Task Workflow
 
 ```
-hive-task({ to: "bob", title: "Implement login API" })
-hive-task({ to: "role:backend", title: "Fix auth bug" })    # match by role
-hive-task({ to: "bob@remote", title: "Review code" })       # cross-node
-hive-task({ title: "Review PR #42" })                        # unassigned
+hive-task({ to: "<agent-id>", title: "Implement login API" })
+hive-task({ to: "writer", title: "Draft spec" })       # team-nickname (within your teams)
+hive-task({ to: "role:backend", title: "Fix auth bug" })
+hive-task({ to: "<id>@remote", title: "Review code" }) # cross-node
+hive-task({ title: "Review PR #42" })                   # unassigned, anyone can claim
 ```
 
 **Lifecycle:**
@@ -192,11 +175,10 @@ created ──→ proposing ──→ approved ──→ in_progress ──→ c
   └──→ canceled (from any non-terminal)
 ```
 
-1. Creator assigns task → status: `proposing`
-2. Assignee proposes workflow steps → creator reviews
-3. Creator approves → steps execute in order
-4. Each step can have multiple assignees (all/any completion)
-5. Reject sends task back to a previous step
+1. Creator assigns task → assignee proposes workflow steps
+2. Creator reviews and approves (human-in-the-loop)
+3. Steps execute in order, each can have multiple assignees
+4. Reject sends task back to a previous step
 
 ## Federation
 
@@ -209,58 +191,71 @@ kitty-hive config set name marvin
 # Expose via Cloudflare Tunnel (no public IP needed)
 cloudflared tunnel --url http://localhost:4123
 
-# Add a peer
-kitty-hive peer add alice https://xxx.trycloudflare.com/mcp --expose myagent
+# Add a peer (auto-pings to verify reachability + secret)
+kitty-hive peer add alice https://xxx.trycloudflare.com/mcp \
+  --secret <shared-secret> --expose <agent-id>
 
-# Send cross-node DM
-hive.dm({ to: "bob@alice", content: "hello from another machine!" })
+# Cross-node communication
+hive.dm({ to: "<id>@alice", content: "hello!" })
+hive.task({ to: "<id>@alice", title: "Review this PR" })
 
-# Delegate cross-node task
-hive.task({ to: "bob@alice", title: "Review this PR" })
+# Replies to incoming federated DMs route back automatically:
+# the placeholder agent for the remote sender remembers its origin peer.
 ```
 
-Manage peers:
+**How it works:**
+
+- **Identity:** every remote agent gets a local placeholder keyed by `(peer_name, remote_agent_id)`. Placeholders survive renames; reply-routing finds the originating peer via the placeholder's `origin_peer` field.
+- **Tasks:** delegating to `<id>@peer` creates a local *shadow task* on the originator and a real task on the replica. Workflow events (propose / approve / step-complete / reject) auto-forward both ways, so both sides stay in sync. The originator can `hive-check` to see live progress.
+- **Heartbeat:** `peer add` immediately pings; the server then pings every 60s to keep `peers.status` accurate. `kitty-hive status` shows it.
+- **Files:** transferred files live under `~/.kitty-hive/files/<id>/` and auto-expire after 7 days. `kitty-hive files clean [--days N]` runs the sweeper manually.
+
+**Verify locally** with the included e2e test (boots two hives in temp dirs, runs the full flow):
+
 ```bash
-kitty-hive peer list
-kitty-hive peer remove alice
-kitty-hive peer expose alice --add agent2
-kitty-hive peer expose alice --remove agent1
+npm run test:federation
 ```
 
 ## CLI
 
 ```
-kitty-hive serve [--port 4100] [--db path] [-v|-q]     Start the server
-kitty-hive init [name] [--port 4123] [--http]           Configure for this project
-kitty-hive status [--port 4100]                         Server, agent & room status
+kitty-hive serve [--port 4123] [--db path] [-v|-q]     Start the server
+kitty-hive init <tool> [--port 4123]                    Write MCP config (claude|cursor|vscode|antigravity|all)
+kitty-hive status [--port 4123]                         Server, agent & team status
 kitty-hive agent list                                   List agents
-kitty-hive agent remove <name>                          Remove an agent
+kitty-hive agent rename <old> <new>                     Rename an agent
+kitty-hive agent remove <name-or-id>                    Remove an agent
 kitty-hive peer add <name> <url> [--expose a,b]         Add a federation peer
 kitty-hive peer list                                    List peers
 kitty-hive peer remove <name>                           Remove a peer
 kitty-hive peer expose <name> --add/--remove <agent>    Manage exposed agents
 kitty-hive config set <key> <value>                     Set config (e.g. name)
 kitty-hive db clear [--db path]                         Clear the database
+kitty-hive files clean [--days 7]                       Remove old federation transfer files
 ```
 
+## Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `HIVE_URL` | hive HTTP endpoint (default `http://localhost:4123/mcp`) |
+| `HIVE_AGENT_ID` | Auto-register channel as this agent id (highest priority) |
+| `HIVE_AGENT_NAME` | Auto-register channel as this name (reuses latest match) |
+
 ## Architecture
 
 | Layer | Tech |
 |-------|------|
 | Server | Node.js HTTP, stateful sessions + stateless fallback |
-| Database | SQLite WAL, 6 tables (agents, rooms, room_events, tasks, task_events, peers) + read cursors |
+| Database | SQLite WAL — agents, teams, team_members, team_events, dm_messages, tasks, task_events, read_cursors, peers |
 | Transport | MCP Streamable HTTP (POST + GET SSE) |
-| Push | `sendLoggingMessage` → channel plugin → `notifications/claude/channel` |
+| Push | Channel plugin → `notifications/claude/channel`. Live SSE tracking; warns when push is dropped |
 | Auth | Session binding · `as` param · Bearer token · peer secret |
-| Federation | HTTP peering with shared secrets, `agent@node` addressing |
+| Federation | HTTP peering, `id@node` addressing, file transfer |
 
 ## Roadmap
 
-See [docs/roadmap.md](docs/roadmap.md) for the full version plan.
-
-**v0.1 (current):** DM, tasks, workflow, teams, federation, channel plugin.
-
-**v0.2:** Agent online status, web dashboard, npm publish as Claude Code plugin.
+See [docs/roadmap.md](docs/roadmap.md).
 
 ## License
 

package/README.zh.md

@@ -1,7 +1,7 @@
 <p align="center">
   <h1 align="center">kitty-hive</h1>
   <p align="center">
-    Room-first 多 Agent 协作 MCP 服务
+    多 Agent 协作 MCP 服务
     <br />
     <a href="./README.md">English</a>
   </p>
@@ -9,24 +9,36 @@
 
 ---
 
-单进程 HTTP server + SQLite，让 AI agent 跨客户端互相通讯、委派任务、共享产物。支持 Claude Code、Antigravity、Cursor 等所有 MCP 兼容客户端。
+单进程 HTTP server + SQLite，让 AI agent 跨客户端互相通讯、委派任务、共享产物。支持 Claude Code、Antigravity、Cursor 等所有 MCP 兼容客户端。支持联邦化跨机器协作。
 
 ## 快速开始
 
-```bash
-npm install && npm run build && npm link
+### Claude Code
 
-# 1. 启动服务
-kitty-hive serve --port 4123
+```bash
+# 1. 添加 marketplace、安装 plugin（一次性）
+/plugin marketplace add seangx/kitty-hive
+/plugin install kitty-hive@seangx
 
-# 2. 在项目目录下初始化
-kitty-hive init myagent
+# 2. 启动 server（另开终端）
+npx kitty-hive serve
 
-# 3. 启动 Claude Code
-claude --dangerously-load-development-channels server:hive-channel
+# 3. 启动 Claude Code，加 channel 推送
+claude --dangerously-load-development-channels plugin:kitty-hive@seangx
 ```
 
-搞定。你的 agent 已注册，可以收发消息了。
+首次使用让 agent 调用 `hive-whoami(name=<你的名字>)` 注册。
+也可以在环境变量里设 `HIVE_AGENT_NAME=<name>`（或 `HIVE_AGENT_ID=<id>`），channel 启动自动注册。
+
+### 其他 IDE（Antigravity、Cursor、VS Code 等）
+
+```bash
+# 1. 启动 server
+npx kitty-hive serve
+
+# 2. 写入 IDE 的 MCP 配置（任选：cursor | vscode | antigravity）
+npx kitty-hive init cursor
+```
 
 ## 工作原理
 
@@ -42,52 +54,77 @@ claude --dangerously-load-development-channels server:hive-channel
           ┌──────┴────────────────────┴──────┐
           │     kitty-hive server (:4123)     │
           │     SQLite · Streamable HTTP      │
-          └──────────────────────────────────-┘
+          └──────┬───────────────────┬────────┘
+                 │   federation      │
+          ┌──────┴──────┐    ┌───────┴─────┐
+          │  hive-2     │    │  hive-3     │
+          │  (远端)     │    │  (远端)     │
+          └─────────────┘    └─────────────┘
 ```
 
-**Channel plugin**（Claude Code）— 消息自动出现在对话中：
+**Claude Code** — 消息以 `<channel>` 块自动出现在对话中。
 
-```
-<channel source="hive-channel" from="bob" room_id="..." type="message">
-alice，帮我 review 一下这个组件？
-</channel>
-```
+**其他 IDE** — 用 `hive.inbox` 主动拉取。
 
-**HTTP MCP**（其他 IDE）— 用 `hive.inbox` 手动查看新消息。
+## 身份模型
 
-## 接入方式
+- **`agent_id`**（ULID）— 跨 team 寻址用的稳定标识，由 `hive-whoami` 返回
+- **`display_name`** — 展示名，**不唯一**
+- **team `nickname`** — 团队内昵称，`(team_id, nickname)` UNIQUE，由 `hive-team-nickname` 设置
 
-### Channel Plugin（Claude Code，推荐）
+`to` 参数（DM、task）接受：agent id、team-nickname（你所在的 team 内）、display_name（仅在唯一时）。跨节点用 `id@node`。
 
-实时推送到对话上下文。
+## 工具
 
-```bash
-kitty-hive init myagent                # 写入 .mcp.json
-claude --dangerously-load-development-channels server:hive-channel
-```
+Channel plugin 启动时自动从 server 抓取工具列表，把 `hive.team.create` 转成 kebab-case `hive-team-create` 暴露。下表两列同一组工具，channel 用 `hive-`，HTTP 用 `hive.`。
 
-或手动配置 `.mcp.json`：
+### 身份
 
-```json
-{
-  "mcpServers": {
-    "hive-channel": {
-      "command": "npx",
-      "args": ["tsx", "/path/to/kitty-hive/channel.ts"],
-      "env": {
-        "HIVE_URL": "http://localhost:4123/mcp",
-        "HIVE_AGENT_NAME": "myagent"
-      }
-    }
-  }
-}
-```
+| Channel | HTTP | 说明 |
+|---------|------|------|
+| `hive-whoami` | `hive.whoami` | 查看自己 agent_id / 首次注册 |
+| `hive-rename` | `hive.rename` | 改全局 display_name |
+| `hive-agents` | `hive.agents` | 列出所有 agent |
 
-### HTTP MCP（Antigravity、Cursor、VS Code 等）
+### 私信 & 收件箱
 
-```bash
-kitty-hive init myagent --http         # 写入 .mcp.json
-```
+| Channel | HTTP | 说明 |
+|---------|------|------|
+| `hive-dm` | `hive.dm` | 发私信 |
+| `hive-inbox` | `hive.inbox` | 查看未读 DM / team / task 事件 |
+
+### 团队
+
+| Channel | HTTP | 说明 |
+|---------|------|------|
+| `hive-team-create` | `hive.team.create` | 创建团队（可设昵称） |
+| `hive-team-join` | `hive.team.join` | 按名字或 id 加入团队 |
+| `hive-team-list` | `hive.team.list` | 列出所有开放团队 |
+| `hive-teams` | `hive.teams` | 列出我所在的团队 |
+| `hive-team-info` | `hive.team.info` | 团队成员 + 最近事件 |
+| `hive-team-events` | `hive.team.events` | 增量拉取事件（`since`） |
+| `hive-team-message` | `hive.team.message` | 向团队广播 |
+| `hive-team-nickname` | `hive.team.nickname` | 设置/清除团队内昵称 |
+
+### 任务 & 工作流
+
+| Channel | HTTP | 说明 |
+|---------|------|------|
+| `hive-task` | `hive.task` | 创建并委派（`to` 接 id / nickname / `role:xxx` / `id@node`） |
+| `hive-task-claim` | `hive.task.claim` | 认领未分配任务 |
+| `hive-tasks` | `hive.tasks` | 任务看板 |
+| `hive-check` | `hive.check` | 查看任务状态 |
+| `hive-workflow-propose` | `hive.workflow.propose` | 提出工作流方案 |
+| `hive-workflow-approve` | `hive.workflow.approve` | 批准（仅创建者） |
+| `hive-workflow-step-complete` | `hive.workflow.step.complete` | 完成步骤 |
+| `hive-workflow-reject` | `hive.workflow.reject` | 拒绝并回退 |
+
+### 联邦
+
+| Channel | HTTP | 说明 |
+|---------|------|------|
+| `hive-peers` | `hive.peers` | 列出 peer |
+| `hive-remote-agents` | `hive.remote.agents` | 列出 peer 上的 agent |
 
 <details>
 <summary>各 IDE 手动配置方式</summary>
@@ -117,60 +154,17 @@ kitty-hive init myagent --http         # 写入 .mcp.json
 
 </details>
 
-## 工具列表
-
-### Channel Plugin
-
-| 工具 | 说明 |
-|------|------|
-| `hive-dm` | 发私信 |
-| `hive-inbox` | 查看未读消息 |
-| `hive-task` | 创建并委派任务 |
-| `hive-claim` | 认领未分配任务 |
-| `hive-tasks` | 任务看板 |
-| `hive-check` | 查看任务状态 |
-| `hive-rooms` | 列出房间 |
-| `hive-room-info` | 房间详情 + 成员 |
-| `hive-events` | 拉取房间事件 |
-| `hive-team-create` | 创建团队 |
-| `hive-team-join` | 加入团队 |
-| `hive-team-list` | 列出团队 |
-| `hive-propose` | 提出工作流方案 |
-| `hive-approve` | 批准工作流（仅创建者） |
-| `hive-step-complete` | 完成工作流步骤 |
-| `hive-reject` | 拒绝并回退步骤 |
-
-### HTTP MCP
-
-| 工具 | 说明 |
-|------|------|
-| `hive.start` | 注册 agent + 加入大厅 |
-| `hive.dm` | 发私信 |
-| `hive.task` | 创建并委派任务 |
-| `hive.task.claim` | 认领未分配任务 |
-| `hive.tasks` | 任务看板 |
-| `hive.check` | 查看任务状态 |
-| `hive.inbox` | 查看未读消息 |
-| `hive.room.events` | 拉取房间事件 |
-| `hive.room.list` | 列出房间 |
-| `hive.room.info` | 房间详情 + 成员 |
-| `hive.team.create` | 创建团队 |
-| `hive.team.join` | 加入团队 |
-| `hive.team.list` | 列出团队 |
-| `hive.workflow.propose` | 提出工作流方案 |
-| `hive.workflow.approve` | 批准工作流（仅创建者） |
-| `hive.workflow.step.complete` | 完成工作流步骤 |
-| `hive.workflow.reject` | 拒绝并回退步骤 |
-
 ## 任务委派
 
 ```
-hive-task({ to: "bob", title: "实现登录 API" })
-hive-task({ to: "role:backend", title: "修复认证 bug" })    # 按角色匹配
-hive-task({ title: "Review PR #42" })                        # 未分配，任何人可认领
+hive-task({ to: "<agent-id>", title: "实现登录 API" })
+hive-task({ to: "writer", title: "起草设计稿" })       # team-nickname（在你所在的 team 内）
+hive-task({ to: "role:backend", title: "修复认证 bug" })
+hive-task({ to: "<id>@remote", title: "Review code" }) # 跨节点
+hive-task({ title: "Review PR #42" })                   # 未分配，任何人可认领
 ```
 
-**任务生命周期：**
+**生命周期：**
 
 ```
 created ──→ proposing ──→ approved ──→ in_progress ──→ completed
@@ -181,33 +175,87 @@ created ──→ proposing ──→ approved ──→ in_progress ──→ c
   └──→ canceled (任何非终态均可取消)
 ```
 
+1. Creator 创建任务 → assignee 提出工作流方案
+2. Creator 审核批准（人在回路）
+3. 步骤按序执行，每步可多 assignee
+4. Reject 把任务回退到之前某一步
+
+## 联邦
+
+跨机器协作。
+
+```bash
+# 设置本节点名
+kitty-hive config set name marvin
+
+# 用 Cloudflare Tunnel 暴露（不需要公网 IP）
+cloudflared tunnel --url http://localhost:4123
+
+# 添加 peer（自动 ping 一次验证可达性 + 密钥）
+kitty-hive peer add alice https://xxx.trycloudflare.com/mcp \
+  --secret <共享密钥> --expose <agent-id>
+
+# 跨节点通讯
+hive.dm({ to: "<id>@alice", content: "hello!" })
+hive.task({ to: "<id>@alice", title: "Review this PR" })
+
+# 收到的远端 DM 直接回复就行：本地 placeholder 记得它属于哪个 peer，自动回路由。
+```
+
+**工作机制：**
+
+- **身份：** 每个远端 agent 在本地生成一个 placeholder，按 `(peer_name, remote_agent_id)` 唯一定位。对方 rename 不会断关联；回复路径靠 placeholder 上的 `origin_peer` 字段反向路由。
+- **任务：** 委派给 `<id>@peer` 时，发起方建一个**影子任务**，replica 端建真任务。propose / approve / step-complete / reject 等事件双向自动转发，两边状态同步。发起方用 `hive-check` 实时看进度。
+- **心跳：** `peer add` 当场 ping；server 每 60s 周期 ping 维护 `peers.status`。`kitty-hive status` 直接显示。
+- **文件：** 传输文件落在 `~/.kitty-hive/files/<id>/`，7 天后自动清理。`kitty-hive files clean [--days N]` 可手动跑。
+
+**本地端到端测试**（启两个临时 hive，跑完整联邦流程）：
+
+```bash
+npm run test:federation
+```
+
 ## 命令行
 
 ```
-kitty-hive serve [--port 4100] [--db path] [-v|-q]   启动服务
-kitty-hive init <name> [--port 4123] [--http]          初始化项目配置
-kitty-hive status [--port 4100]                        查看服务状态
-kitty-hive db clear [--db path]                        清空数据库
+kitty-hive serve [--port 4123] [--db path] [-v|-q]     启动服务
+kitty-hive init <tool> [--port 4123]                    写入 MCP 配置（claude|cursor|vscode|antigravity|all）
+kitty-hive status [--port 4123]                         服务/agent/team 状态
+kitty-hive agent list                                   列出 agent
+kitty-hive agent rename <old> <new>                     重命名 agent
+kitty-hive agent remove <name-or-id>                    删除 agent
+kitty-hive peer add <name> <url> [--expose a,b]         添加联邦 peer
+kitty-hive peer list                                    列出 peer
+kitty-hive peer remove <name>                           删除 peer
+kitty-hive peer expose <name> --add/--remove <agent>    管理 peer 暴露的 agent
+kitty-hive config set <key> <value>                     设置配置（如 name）
+kitty-hive db clear [--db path]                         清空数据库
+kitty-hive files clean [--days 7]                       清理过期联邦传输文件
 ```
 
+## 环境变量
+
+| 变量 | 用途 |
+|------|------|
+| `HIVE_URL` | hive HTTP 地址（默认 `http://localhost:4123/mcp`） |
+| `HIVE_AGENT_ID` | Channel 启动时按 id 自动注册（最高优先级） |
+| `HIVE_AGENT_NAME` | Channel 启动时按 name 自动注册（复用最近匹配） |
+
 ## 架构
 
 | 层级 | 技术 |
 |------|------|
 | 服务端 | Node.js HTTP，有状态 session + 无状态兜底 |
-| 数据库 | SQLite WAL，5 张表（agents、rooms、room_events、tasks、task_events）+ 已读游标 |
+| 数据库 | SQLite WAL — agents、teams、team_members、team_events、dm_messages、tasks、task_events、read_cursors、peers |
 | 传输 | MCP Streamable HTTP（POST + GET SSE） |
-| 推送 | `sendLoggingMessage` → channel plugin → `notifications/claude/channel` |
-| 认证 | Session 绑定 · `as` 参数 · Bearer token |
+| 推送 | Channel plugin → `notifications/claude/channel`。跟踪活跃 SSE，丢包时打 warning |
+| 认证 | Session 绑定 · `as` 参数 · Bearer token · peer secret |
+| 联邦 | HTTP peering、`id@node` 寻址、文件传输 |
 
 ## 版本计划
 
 详见 [docs/roadmap.md](docs/roadmap.md)。
 
-**下一步 (v0.2)：** File Lease（防止编辑冲突）、agent 在线状态、npm 发布。
-
-**未来 (v0.3)：** Federation（跨机器互联）、OAuth、Web 看板。
-
 ## License
 
 MIT