Skip to content

Commit 5ee49fd

Browse files
claude-code-bestclaude-code-best
committed
docs: 添加一大堆 feature 的描述
1 parent 22ca3a1 commit 5ee49fd

21 files changed

Lines changed: 3276 additions & 363 deletions

‎README.md‎

Lines changed: 9 additions & 363 deletions
Large diffs are not rendered by default.

‎docs/feature-exploration-plan.md‎

Lines changed: 457 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/features/bash-classifier.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# BASH_CLASSIFIER — Bash 命令分类器
2+
3+
> Feature Flag: `FEATURE_BASH_CLASSIFIER=1`
4+
> 实现状态：bashClassifier.ts 全部 Stub，yoloClassifier.ts 完整实现可参考
5+
> 引用数：45
6+
7+
## 一、功能概述
8+
9+
BASH_CLASSIFIER 使用 LLM 对 bash 命令进行意图分类（允许/拒绝/询问），实现自动权限决策。用户不需要逐个审批 bash 命令，分类器根据命令内容和上下文自动判断安全性。
10+
11+
### 核心特性
12+
13+
- **LLM 驱动分类**：使用 Opus 模型评估命令安全性
14+
- **两阶段分类**：快速阻止/允许 → 深度思考链
15+
- **自动审批**：分类器判定安全的命令自动通过
16+
- **UI 集成**：权限对话框显示分类器状态和审核选项
17+
18+
## 二、实现架构
19+
20+
### 2.1 模块状态
21+
22+
| 模块 | 文件 | 状态 | 说明 |
23+
|------|------|------|------|
24+
| Bash 分类器 | `src/utils/permissions/bashClassifier.ts` | **Stub** | 所有函数返回空操作。注释："ANT-ONLY" |
25+
| YOLO 分类器 | `src/utils/permissions/yoloClassifier.ts` | **完整** | 1496 行，两阶段 XML 分类器 |
26+
| 审批信号 | `src/utils/classifierApprovals.ts` | **完整** | Map + 信号管理分类器决策 |
27+
| 权限 UI | `src/components/permissions/BashPermissionRequest.tsx` | **布线** | 分类器状态显示、审核选项 |
28+
| 权限管道 | `src/hooks/toolPermission/handlers/*.ts` | **布线** | 分类器结果路由到决策 |
29+
| API beta 标头 | `src/services/api/withRetry.ts` | **布线** | 启用时发送 `bash_classifier` beta |
30+
31+
### 2.2 参考实现：yoloClassifier.ts
32+
33+
文件：`src/utils/permissions/yoloClassifier.ts`（1496 行）
34+
35+
这是已实现的完整分类器，可作为 bashClassifier.ts 的参考：
36+
37+
```
38+
两阶段分类：
39+
1. 快速阶段：构建对话记录 → 调用 sideQuery（Opus）→ 快速阻止/允许
40+
2. 深度阶段：思考链分析 → 最终决策
41+
```
42+
43+
特性：
44+
- 构建完整对话记录上下文
45+
- 调用安全系统提示的 sideQuery
46+
- GrowthBook 配置和指标
47+
- 错误处理和降级
48+
49+
### 2.3 分类器在权限管道中的位置
50+
51+
```
52+
bash 命令到达
53+
│
54+
▼
55+
bashPermissions.ts 权限检查
56+
│
57+
├── 传统规则匹配（字符串级别）
58+
│
59+
└── [BASH_CLASSIFIER] LLM 分类
60+
│
61+
├── allow → 自动通过
62+
├── deny → 自动拒绝
63+
└── ask → 显示权限对话框
64+
│
65+
├── 分类器自动审批标记
66+
└── 审核选项（用户可覆盖）
67+
```
68+
69+
## 三、需要补全的内容
70+
71+
| 函数 | 需要实现 | 说明 |
72+
|------|---------|------|
73+
| `classifyBashCommand()` | LLM 调用评估安全性 | 参考 yoloClassifier.ts 的两阶段模式 |
74+
| `isClassifierPermissionsEnabled()` | GrowthBook/配置检查 | 控制分类器是否激活 |
75+
| `getBashPromptDenyDescriptions()` | 返回基于提示的拒绝规则 | 权限设置描述 |
76+
| `getBashPromptAskDescriptions()` | 返回询问规则 | 需要用户确认的命令 |
77+
| `getBashPromptAllowDescriptions()` | 返回允许规则 | 自动通过的命令 |
78+
| `generateGenericDescription()` | LLM 生成命令描述 | 为权限对话框提供说明 |
79+
| `extractPromptDescription()` | 解析规则内容 | 从规则中提取描述 |
80+
81+
## 四、关键设计决策
82+
83+
1. **ANT-ONLY 标记**：bashClassifier.ts 标注为 "ANT-ONLY"，可能是 Anthropic 内部服务端分类器的客户端适配
84+
2. **两阶段分类**：快速阶段处理明确情况（减少延迟），深度阶段处理模糊情况
85+
3. **分类器结果可审核**：权限 UI 显示分类器决策，用户可覆盖
86+
4. **YOLO 分类器参考**：yoloClassifier.ts 提供完整的分类器实现模式，可直接参考
87+
88+
## 五、使用方式
89+
90+
```bash
91+
# 启用 feature
92+
FEATURE_BASH_CLASSIFIER=1 bun run dev
93+
94+
# 配合 TREE_SITTER_BASH 使用（AST + LLM 双重安全）
95+
FEATURE_BASH_CLASSIFIER=1 FEATURE_TREE_SITTER_BASH=1 bun run dev
96+
```
97+
98+
## 六、文件索引
99+
100+
| 文件 | 行数 | 职责 |
101+
|------|------|------|
102+
| `src/utils/permissions/bashClassifier.ts` | — | Bash 分类器（stub，ANT-ONLY） |
103+
| `src/utils/permissions/yoloClassifier.ts` | 1496 | YOLO 分类器（完整参考实现） |
104+
| `src/utils/classifierApprovals.ts` | — | 分类器审批信号管理 |
105+
| `src/components/permissions/BashPermissionRequest.tsx:261-469` | — | 分类器 UI |
106+
| `src/hooks/toolPermission/handlers/interactiveHandler.ts` | — | 交互式权限处理 |
107+
| `src/services/api/withRetry.ts:81` | — | API beta 标头 |

‎docs/features/bridge-mode.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# BRIDGE_MODE — 远程控制
2+
3+
> Feature Flag: `FEATURE_BRIDGE_MODE=1`
4+
> 实现状态：完整可用（v1 + v2 实现）
5+
> 引用数：28
6+
7+
## 一、功能概述
8+
9+
BRIDGE_MODE 将本地 CLI 注册为"bridge 环境"，可从 claude.ai 或其他控制面远程驱动。本地终端变为一个"执行者"，接受远程指令并执行。
10+
11+
### 核心特性
12+
13+
- **环境注册**：本地 CLI 向 Anthropic 服务器注册为可用的 bridge 环境
14+
- **工作轮询**：长轮询（long-poll）等待远程任务分配
15+
- **会话管理**：创建、恢复、归档远程会话
16+
- **权限透传**：远程权限请求发送到控制面，用户在 claude.ai 上批准/拒绝
17+
- **心跳保活**：定期发送 heartbeat 延长任务租约
18+
- **可信设备**：v2 支持可信设备令牌增强安全性
19+
20+
## 二、实现架构
21+
22+
### 2.1 版本演进
23+
24+
| 版本 | 实现 | 特点 |
25+
|------|------|------|
26+
| v1（env-based） | `src/bridge/replBridge.ts` | 基于环境变量的传统 bridge |
27+
| v2（env-less） | `src/bridge/remoteBridgeCore.ts` | 无需环境变量，更安全的 bridge |
28+
29+
### 2.2 API 协议
30+
31+
文件：`src/bridge/bridgeApi.ts`
32+
33+
Bridge API Client 提供 7 个核心操作：
34+
35+
| 操作 | HTTP | 说明 |
36+
|------|------|------|
37+
| `registerBridgeEnvironment` | POST `/v1/environments/bridge` | 注册本地环境，获取 `environment_id` + `environment_secret` |
38+
| `pollForWork` | GET `/v1/environments/{id}/work/poll` | 长轮询等待任务（10s 超时） |
39+
| `acknowledgeWork` | POST `/v1/environments/{id}/work/{workId}/ack` | 确认接收任务 |
40+
| `stopWork` | POST `/v1/environments/{id}/work/{workId}/stop` | 停止任务 |
41+
| `heartbeatWork` | POST `/v1/environments/{id}/work/{workId}/heartbeat` | 续约任务租约 |
42+
| `deregisterEnvironment` | DELETE `/v1/environments/bridge/{id}` | 注销环境 |
43+
| `archiveSession` | POST `/v1/sessions/{id}/archive` | 归档会话（409 = 已归档，幂等） |
44+
| `sendPermissionResponseEvent` | POST `/v1/sessions/{id}/events` | 发送权限审批结果 |
45+
| `reconnectSession` | POST `/v1/environments/{id}/bridge/reconnect` | 重连已存在的会话 |
46+
47+
### 2.3 认证流程
48+
49+
```
50+
注册: OAuth Bearer Token → 获取 environment_secret
51+
轮询: environment_secret 作为 Authorization
52+
├── 401 → 尝试 OAuth token 刷新（onAuth401）
53+
└── 刷新成功 → 重试一次
54+
```
55+
56+
**OAuth 刷新**：API client 内置 `withOAuthRetry` 机制。401 时调用 `handleOAuth401Error`（同 withRetry.ts 的 v1/messages 模式），刷新后重试一次。
57+
58+
### 2.4 安全设计
59+
60+
- **路径穿越防护**：`validateBridgeId()` 使用 `/^[a-zA-Z0-9_-]+$/` 白名单验证所有服务端 ID
61+
- **BridgeFatalError**：不可重试的错误（401/403/404/410）直接抛出，阻止重试循环
62+
- **可信设备令牌**：v2 通过 `X-Trusted-Device-Token` header 增强安全层级
63+
- **幂关注册**：支持 `reuseEnvironmentId` 实现会话恢复，避免重复创建环境
64+
65+
### 2.5 数据流
66+
67+
```
68+
claude.ai 用户选择远程环境
69+
│
70+
▼
71+
POST /v1/environments/bridge (注册)
72+
│
73+
◀── environment_id + environment_secret
74+
│
75+
▼
76+
GET .../work/poll (长轮询)
77+
│
78+
◀── WorkResponse { id, data: { type, sessionId } }
79+
│
80+
▼
81+
POST .../work/{id}/ack (确认)
82+
│
83+
▼
84+
sessionRunner 创建 REPL session
85+
│
86+
├── 权限请求 → sendPermissionResponseEvent
87+
├── 心跳 → heartbeatWork (续约)
88+
└── 任务完成 → 自动归档
89+
```
90+
91+
### 2.6 模块结构
92+
93+
| 模块 | 文件 | 职责 |
94+
|------|------|------|
95+
| API Client | `bridgeApi.ts` | HTTP 通信（注册/轮询/确认/心跳/注销） |
96+
| Session Runner | `sessionRunner.ts` | 创建/恢复 REPL 会话 |
97+
| Bridge Config | `bridgeConfig.ts` | 配置管理（machine name、max sessions 等） |
98+
| Transport | `replBridgeTransport.ts` | Bridge 传输层 |
99+
| Permission Callbacks | `bridgePermissionCallbacks.ts` | 权限请求处理 |
100+
| Pointer | `bridgePointer.ts` | 当前活跃 bridge 状态指针 |
101+
| Flush Gate | `flushGate.ts` | 刷新控制 |
102+
| JWT Utils | `jwtUtils.ts` | JWT 令牌工具 |
103+
| Trusted Device | `trustedDevice.ts` | 可信设备管理 |
104+
| Debug Utils | `debugUtils.ts` | 调试日志 |
105+
| Types | `types.ts` | 类型定义 |
106+
107+
## 三、关键设计决策
108+
109+
1. **长轮询而非 WebSocket**：`pollForWork` 使用 HTTP GET + 10s 超时。简单可靠，无需维护 WebSocket 连接
110+
2. **OAuth 刷新内嵌**：API client 自带 `withOAuthRetry`，无需外层重试逻辑
111+
3. **ETag 条件请求**：注册时支持 `reuseEnvironmentId` 实现幂等会话恢复
112+
4. **v1/v2 共存**：代码中同时存在两套实现，v2 是更安全的升级版
113+
5. **权限双向流动**：本地权限请求发送到 claude.ai，用户在 web 上审批
114+
115+
## 四、使用方式
116+
117+
```bash
118+
# 启用 bridge mode
119+
FEATURE_BRIDGE_MODE=1 bun run dev
120+
121+
# 从 claude.ai/code 远程连接
122+
# 在 web 界面选择已注册的环境
123+
124+
# 配合 DAEMON 使用（后台守护）
125+
FEATURE_BRIDGE_MODE=1 FEATURE_DAEMON=1 bun run dev
126+
```
127+
128+
## 五、外部依赖
129+
130+
| 依赖 | 说明 |
131+
|------|------|
132+
| Anthropic OAuth | claude.ai 订阅登录 |
133+
| GrowthBook | `tengu_ccr_bridge` 门控 |
134+
| Bridge API | `/v1/environments/bridge` 系列端点 |
135+
136+
## 六、文件索引
137+
138+
| 文件 | 行数 | 职责 |
139+
|------|------|------|
140+
| `src/bridge/bridgeApi.ts` | 540 | API Client（核心） |
141+
| `src/bridge/sessionRunner.ts` | — | 会话运行器 |
142+
| `src/bridge/bridgeConfig.ts` | — | 配置管理 |
143+
| `src/bridge/replBridgeTransport.ts` | — | 传输层 |
144+
| `src/bridge/bridgePermissionCallbacks.ts` | — | 权限回调 |
145+
| `src/bridge/bridgePointer.ts` | — | 状态指针 |
146+
| `src/bridge/flushGate.ts` | — | 刷新控制 |
147+
| `src/bridge/jwtUtils.ts` | — | JWT 工具 |
148+
| `src/bridge/trustedDevice.ts` | — | 可信设备 |
149+
| `src/bridge/remoteBridgeCore.ts` | — | v2 核心实现 |
150+
| `src/bridge/types.ts` | — | 类型定义 |
151+
| `src/bridge/debugUtils.ts` | — | 调试工具 |
152+
| `src/bridge/pollConfigDefaults.ts` | — | 轮询配置默认值 |
153+
| `src/bridge/bridgeUI.ts` | — | UI 组件 |
154+
| `src/bridge/codeSessionApi.ts` | — | 代码会话 API |
155+
| `src/bridge/peerSessions.ts` | — | 对等会话管理 |
156+
| `src/bridge/sessionIdCompat.ts` | — | Session ID 兼容层 |
157+
| `src/bridge/createSession.ts` | — | 会话创建 |
158+
| `src/bridge/replBridgeHandle.ts` | — | Bridge 句柄 |

0 commit comments

Comments
 (0)