claude-code-best · Leo-K-cell · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/.codex/agents/hello-agent.toml b/.codex/agents/hello-agent.toml
@@ -0,0 +1,15 @@
+name = "hello-agent"
+description = "A friendly greeting agent that introduces the project"
+developer_instructions = """
+You are a friendly greeting agent. Your job is to greet the user and provide helpful information about the current project.
+
+Instructions:
+1. Read the project's AGENTS.md to understand the project context.
+2. Greet the user warmly.
+3. Provide a brief summary of the project based on what you learned from AGENTS.md.
+4. Offer to help with any questions about the project.
+
+Style:
+- Be concise and friendly.
+- Respond in 简体中文.
+- Keep responses short — no more than a few sentences."""
diff --git a/.gitignore b/.gitignore
@@ -55,4 +55,5 @@ credentials.json
 .claude-recovery.md
 .test-progress.md
 .squash-tmp/
+.worktrees/
 .git.*-backup
diff --git a/README.md b/README.md
@@ -164,14 +164,105 @@ bun run build
 
 > ℹ️ 支持所有 Anthropic API 兼容服务（如 OpenRouter、AWS Bedrock 代理等），只要接口兼容 Messages API 即可。
 
+## 🎛️ Remote Control 本地全链路联调（新 Web UI）
+
+Remote Control 让你在**浏览器**里操作跑在**其他机器**上的 Claude Code。三方接力：
+
+```
+浏览器(新 UI) ──HTTP/SSE──▶ RCS 中继服务器 ──WebSocket──▶ ccb CLI(某台机=“环境”) ──▶ Claude API
+     ▲                          (端口 3000                      ▲ 真正干活、读写你的仓库
+     └────────── 事件推送 ◀──────  同时托管 UI)  ◀── 消息中继 ────┘
+```
+
+- **RCS** 只是“中转站”，自己不思考、不写代码；`packages/remote-control-server/`，对话和消息历史存入 SQLite，实时连接状态保留在内存中。
+- **“环境”** 才是真正的 Claude Code：在目标机器上跑 `ccb remote-control`（源码版 `bun run dev remote-control`）把自己注册进 RCS。
+- **新 Web UI** 仿 claude.ai，分 **Chat / Code** 双界面 + 项目管理，源码在 `packages/remote-control-server/web/`。
+
+> ⚠️ **命令来源**：`ccb` 是**装了 npm 版或构建后**才有的可执行命令。源码开发目录里没有 `ccb`，请用下表的 `bun run dev …` 等价写法。所有命令都在**仓库根目录**（含 `package.json` 的 `Real-Agentic/`）执行。
+>
+> | 装了 npm 版 | 源码目录里 |
+> | --- | --- |
+> | `ccb` | `bun run dev` |
+> | `ccb remote-control` | `bun run dev remote-control` |
+
+### 一条命令在本机跑通整条链路
+
+在仓库根目录运行：
+
+```bash
+bun run rcs:local
+```
+
+该命令以前台 supervisor 方式同时启动 RCS Server 和 Bridge Worker，自动生成并在两个子进程间传递临时 transport secret；Web 构建产物缺失时只构建一次。浏览器打开 <http://127.0.0.1:3000/code/> 即可。终端中的 `Ctrl-C` 会统一关闭两个子进程。
+
+开发 Web UI 时使用：
+
+```bash
+bun run rcs:dev
+```
+
+它会额外启动 Vite，浏览器打开 <http://127.0.0.1:5173/code/>。其他分层入口：
+
+| 命令 | 用途 |
+| --- | --- |
+| `bun run rcs:local` | 推荐的本地日常入口：RCS + Bridge，缺失时构建 Web |
+| `bun run rcs:dev` | RCS + Bridge + Vite 热更新 |
+| `bun run rcs:server` | 只启动 RCS Server，用于分离部署和排障 |
+| `bun run rcs:worker` | 只启动 Bridge Worker，需自行配置 `CLAUDE_BRIDGE_*` |
+| `bun run rcs` | `rcs:server` 的兼容别名 |
+
+这里有两类不同的 key：
+
+- **Transport secret**：`RCS_API_KEYS` / `CLAUDE_BRIDGE_OAUTH_TOKEN`，只负责 RCS 与 Worker 互相信任；`rcs:local` 和 `rcs:dev` 会自动配对。
+- **模型 Provider key**：Anthropic、OpenAI、Gemini、Grok 等模型凭据，由 `/login` 或 Web Provider 设置页持久化；启动器不会打印、复制或写入这些凭据。
+
+个人本地脚本默认绑定 `127.0.0.1` 并启用单用户模式；对话历史仍写入 SQLite。关键环境变量：
+
+| 变量 | 作用 |
+| --- | --- |
+| `RCS_SINGLE_USER=1` | **单用户模式**：显式关闭 Web 会话按浏览器 UUID 的归属隔离，任意浏览器都能看到并操作同一批对话。浏览器 UUID 仅保留为兼容/配对标识；bridge 设备与工作区仍分别识别。默认关闭，多人或公网部署不要设。 |
+| `RCS_DB_PATH`（默认 `./data/rcs.sqlite`） | 会话 + 事件历史落 SQLite，**RCS 重启后对话还在**，隔天回来接着聊。 |
+
+> `rcs:local` 只在 Web `dist/index.html` 缺失时自动构建。修改 UI 源码后请使用 `rcs:dev` 热更新，或显式运行 `cd packages/remote-control-server && bun run build:web`。
+
+### 须知 / 常见坑
+
+- **目录别搞错**：命令必须在 `Real-Agentic/`（仓库根，含 `package.json`），不是外层文件夹。
+- **分离部署时两个 token 要一致**：手工使用 `rcs:server` + `rcs:worker` 时，`CLAUDE_BRIDGE_OAUTH_TOKEN` 必须匹配 `RCS_API_KEYS` 中的一个值；统一入口会自动处理。
+- **设备身份是安装级的**：bridge 首次运行会在 Claude 配置目录生成 `remote-control-device.json`。重启进程不会改变设备 ID；若复制了整个配置目录到另一台机器，请删除该文件后重启 bridge 以生成新设备 ID。
+- **环境身份是稳定的**：同一账户、设备、工作区和 worker 类型会复用同一个 `environment_id`。每次 bridge 重启只接管新的连接租约，不会制造新的孤儿环境。
+- **自建 bridge 免授权门**：设了 `CLAUDE_BRIDGE_BASE_URL` 即视为自托管，会绕过 GrowthBook 授权与最低版本校验（`src/bridge/bridgeConfig.ts` 的 `isSelfHostedBridge`）。
+- **模型要先配好**：链路通了但发消息报 `There's an issue with the selected model …`，说明这台机器的模型没配。到 ② 那台机器 `/login` 配一个可用模型即可（与 UI/链路无关）。
+- **UI 里的“项目”= 接入的环境**：没有环境接入时项目页为空，属正常。ACP agent 类型的环境需 WebSocket 直连，不出现在“新建会话”的环境选择里。
+- **停止**：统一入口只需一次 `Ctrl-C`；RCS 的临时连接状态会清空，对话历史保留在 `RCS_DB_PATH` 指定的 SQLite 数据库中。
+
+生产/Docker 自托管部署见 `docs/features/remote-control-self-hosting.md`。
+
 ## Feature Flags
 
-所有功能开关通过 `FEATURE_<FLAG_NAME>=1` 环境变量启用，例如：
+先查看当前 dev 或构建产物实际包含的能力：
+
+```bash
+bun run dev capabilities
+bun run dev capabilities --json
+# 构建产物：ccb capabilities --json
+```
+
+Feature 环境变量接受 `1/true/yes/on`（启用）和 `0/false/no/off`（禁用，且可覆盖默认项），忽略大小写。例如：
 
 ```bash
 FEATURE_BUDDY=1 FEATURE_FORK_SUBAGENT=1 bun run dev
+FEATURE_BUDDY=0 bun run dev
 ```
 
+交互式与 RCS 模型消息默认使用 streaming。Headless 若需要逐事件输出：
+
+```bash
+ccb --print --verbose --output-format stream-json --include-partial-messages "你的任务"
+```
+
+RCS Web 会用完整已生成文本快照实时更新当前助手消息；这些 partial 快照只走 live 通道，不写入 SQLite。模型完成后，最终 `assistant` 消息才作为权威记录持久化，因此刷新或断线重连不会依赖中途快照，也不会重复正文。源码目录中可把上面的 `ccb` 换成 `bun run dev`。
+
 各 Feature 的详细说明见 [`docs/features/`](docs/features/) 目录，欢迎投稿补充。
 
 ## VS Code 调试

diff --git a/build.ts b/build.ts
@@ -2,18 +2,16 @@ import { readdir, readFile, writeFile, cp } from 'fs/promises'
 import { join } from 'path'
 import { getMacroDefines } from './scripts/defines.ts'
 import { DEFAULT_BUILD_FEATURES } from './scripts/defines.ts'
+import { resolveEnabledFeatures } from './scripts/feature-resolution.ts'
 
 const outdir = 'dist'
 
 // Step 1: Clean output directory
 const { rmSync } = await import('fs')
 rmSync(outdir, { recursive: true, force: true })
 
-// Collect FEATURE_* env vars → Bun.build features
-const envFeatures = Object.keys(process.env)
-  .filter(k => k.startsWith('FEATURE_'))
-  .map(k => k.replace('FEATURE_', ''))
-const features = [...new Set([...DEFAULT_BUILD_FEATURES, ...envFeatures])]
+// Collect defaults plus explicit FEATURE_* true/false overrides.
+const features = resolveEnabledFeatures(DEFAULT_BUILD_FEATURES, process.env)
 
 // Step 2: Bundle with splitting
 const result = await Bun.build({
@@ -23,7 +21,7 @@ const result = await Bun.build({
   splitting: true,
   sourcemap: 'linked',
   define: {
-    ...getMacroDefines(),
+    ...getMacroDefines(features),
     // React production mode — eliminates _debugStack Error objects
     // (6,889 objects × ~1.7KB = 12MB in development builds) and removes
     // prop-type / key warnings not useful in a production CLI tool.

diff --git a/bun.lock b/bun.lock
diff --git a/docs/features/all-features-guide.md b/docs/features/all-features-guide.md
@@ -182,11 +182,23 @@ bun run dev
 
 ### 使用
 ```bash
+# 查看当前产物的真实编译状态、激活条件和使用方式
+bun run dev capabilities
+bun run dev capabilities --json
+
 # 通过环境变量启用任意 feature
 FEATURE_PROACTIVE=1 bun run dev
 
-# dev/build 模式有各自的默认启用列表
-# 查看 scripts/dev.ts 中的 DEFAULT_FEATURES
+# 显式关闭默认 feature（false/no/off 同样有效，忽略大小写）
+FEATURE_BRIDGE_MODE=0 bun run dev
+```
+
+只有 `1`、`true`、`yes`、`on` 会启用；`0`、`false`、`no`、`off` 会禁用。未知值会被忽略并输出警告。dev、Bun build 和 Vite 使用同一解析规则，默认集合集中在 `scripts/defines.ts`。
+
+模型 API 原生使用 streaming，不依赖额外 feature。交互式与 RCS 自动消费流；headless 逐事件输出使用：
+
+```bash
+ccb --print --verbose --output-format stream-json --include-partial-messages "你的任务"
 ```
 
 ### 关键 feature flags
@@ -518,8 +530,8 @@ AI 也可通过 `SnipTool` 自动截断过长的对话：
 
 | Flag | 默认 | 说明 |
 |------|------|------|
-| `BUDDY` | ✅ dev only | 伴侣系统 |
-| `BRIDGE_MODE` | ✅ dev only | 远程控制 |
+| `BUDDY` | ✅ dev+build | 伴侣系统 |
+| `BRIDGE_MODE` | ✅ dev+build | 远程控制 |
 | `VOICE_MODE` | ✅ dev+build | 语音模式 |
 | `CHICAGO_MCP` | ✅ dev+build | Computer Use + Chrome |
 | `AGENT_TRIGGERS_REMOTE` | ✅ dev+build | 定时任务 |

diff --git a/docs/features/bridge-mode.md b/docs/features/bridge-mode.md
@@ -11,6 +11,7 @@ BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他
 ### 核心特性
 
 - **环境注册**：本地 CLI 向 Anthropic 服务器注册为可用的 bridge 环境
+- **稳定身份**：安装级设备 ID + 规范化工作区 key 共同确定逻辑环境，进程重启只轮换连接租约
 - **工作轮询**：长轮询（long-poll）等待远程任务分配
 - **会话管理**：创建、恢复、归档远程会话
 - **权限透传**：远程权限请求发送到控制面，用户在 claude.ai 上批准/拒绝
@@ -34,7 +35,7 @@ Bridge API Client 提供 9 个核心操作：
 
 | 操作 | HTTP | 说明 |
 |------|------|------|
-| `registerBridgeEnvironment` | POST `/v1/environments/bridge` | 注册本地环境，获取 `environment_id` + `environment_secret` |
+| `registerBridgeEnvironment` | POST `/v1/environments/bridge` | 注册/复用逻辑环境，获取 `environment_id`、凭据和连接租约 |
 | `pollForWork` | GET `/v1/environments/{id}/work/poll` | 长轮询等待任务（10s 超时） |
 | `acknowledgeWork` | POST `/v1/environments/{id}/work/{workId}/ack` | 确认接收任务 |
 | `stopWork` | POST `/v1/environments/{id}/work/{workId}/stop` | 停止任务 |
@@ -47,9 +48,12 @@ Bridge API Client 提供 9 个核心操作：
 ### 2.3 认证流程
 
 ```
-注册: OAuth Bearer Token → 获取 environment_secret
-轮询: environment_secret 作为 Authorization
+注册: OAuth Bearer Token + device/workspace/connection identity
+     → 获取 environment_secret + lease_token + lease_epoch
+轮询/确认/心跳/停止/注销: environment_secret 作为 Authorization
+                         + X-Bridge-Lease 进行连接 fencing
   ├── 401 → 尝试 OAuth token 刷新（onAuth401）
+  ├── 409 lease_superseded → 旧进程立即停止，不得影响新连接
   └── 刷新成功 → 重试一次
 ```
 
@@ -60,17 +64,32 @@ Bridge API Client 提供 9 个核心操作：
 - **路径穿越防护**：`validateBridgeId()` 使用 `/^[a-zA-Z0-9_-]+$/` 白名单验证所有服务端 ID
 - **BridgeFatalError**：不可重试的错误（401/403/404/410）直接抛出，阻止重试循环
 - **可信设备令牌**：v2 通过 `X-Trusted-Device-Token` header 增强安全层级
-- **幂关注册**：支持 `reuseEnvironmentId` 实现会话恢复，避免重复创建环境
+- **稳定逻辑环境**：RCS 按 `account_id + device_id + workspace_key + worker_type` 幂等复用环境；`environment_id` 持久化到 SQLite
+- **租约 fencing**：每次注册生成新的 `lease_token` 并递增 `lease_epoch`，旧进程请求返回 `lease_superseded`
+- **精确迁移**：`resume_session_id` 只迁移 pointer 明确指向的会话，不批量认领旧环境下的孤儿会话
 
-### 2.5 数据流
+### 2.5 身份层级
+
+```text
+账户 → 设备 → 工作区 → 逻辑环境 → 连接租约 → 会话
+```
+
+- `device_id`：首次运行随机生成并持久化到 Claude 配置目录的 `remote-control-device.json`
+- `device_name`：仅用于展示，通常为 hostname，不参与身份判断
+- `workspace_key`：规范化绝对目录与 Git remote 的哈希
+- `environment_id`：RCS 持久化的稳定逻辑环境 ID
+- `connection_id` / `lease_token`：单次 bridge 进程连接；新连接会 fence 旧连接
+- `session_id`：持久化对话；`archived` 才是终态，worker 离线不关闭会话
+
+### 2.6 数据流
 
 ```
 claude.ai 用户选择远程环境
          │
          ▼
 POST /v1/environments/bridge (注册)
          │
-         ◀── environment_id + environment_secret
+         ◀── environment_id + environment_secret + lease_token
          │
          ▼
 GET .../work/poll (长轮询)
@@ -88,11 +107,12 @@ sessionRunner 创建 REPL session
          └── 任务完成 → 自动归档
 ```
 
-### 2.6 模块结构
+### 2.7 模块结构
 
 | 模块 | 文件 | 职责 |
 |------|------|------|
 | API Client | `bridgeApi.ts` | HTTP 通信（注册/轮询/确认/心跳/注销） |
+| Bridge Identity | `bridgeIdentity.ts` | 持久化设备 ID，派生工作区 key 和临时 connection ID |
 | Session Runner | `sessionRunner.ts` | 创建/恢复 REPL 会话 |
 | Bridge Config | `bridgeConfig.ts` | 配置管理（machine name、max sessions 等） |
 | Transport | `replBridgeTransport.ts` | Bridge 传输层 |
@@ -108,9 +128,10 @@ sessionRunner 创建 REPL session
 
 1. **长轮询而非 WebSocket**：`pollForWork` 使用 HTTP GET + 10s 超时。简单可靠，无需维护 WebSocket 连接
 2. **OAuth 刷新内嵌**：API client 自带 `withOAuthRetry`，无需外层重试逻辑
-3. **ETag 条件请求**：注册时支持 `reuseEnvironmentId` 实现幂等会话恢复
+3. **身份与连接分离**：稳定环境由设备和工作区决定，`reuseEnvironmentId` 仅作为旧环境迁移提示；每次连接由 lease 单独 fencing
 4. **v1/v2 共存**：代码中同时存在两套实现，v2 是更安全的升级版
 5. **权限双向流动**：本地权限请求发送到 claude.ai，用户在 web 上审批
+6. **兼容边界**：ACP 与 env-less/v2 继续走旧身份协议，由兼容适配层接入，不纳入第一阶段身份语义
 
 ## 四、使用方式
 
@@ -138,6 +159,7 @@ FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev
 | 文件 | 行数 | 职责 |
 |------|------|------|
 | `src/bridge/bridgeApi.ts` | 541 | API Client（核心） |
+| `src/bridge/bridgeIdentity.ts` | — | 设备、工作区和连接身份 |
 | `src/bridge/sessionRunner.ts` | — | 会话运行器 |
 | `src/bridge/bridgeConfig.ts` | — | 配置管理 |
 | `src/bridge/replBridgeTransport.ts` | — | 传输层 |