Skip to content

Commit 170f00c

Browse files
claude-code-bestclaude-code-best
committed
docs: 进行 v6 设计文档的编写
1 parent 280be43 commit 170f00c

22 files changed

Lines changed: 1878 additions & 0 deletions

File tree

‎specs/feature-cli-transport/design.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# CLI 传输层设计
2+
3+
> 来源: V6.md 四 4.17
4+
> 优先级: P3 (入口层基础设施)
5+
> 风险: 低
6+
7+
```
8+
┌───────────────────────────────────────────────────────────────────┐
9+
│ packages/cli (~12700行) │
10+
│ src/cli/ (127文件) │
11+
│ │
12+
│ ┌─────────────────────────────────────────────────────────────┐ │
13+
│ │ Transport 层 (可插拔 I/O 传输) │ │
14+
│ │ │ │
15+
│ │ ├─ HybridTransport 混合模式 (本地 + 远程) │ │
16+
│ │ ├─ SSETransport Server-Sent Events │ │
17+
│ │ ├─ WebSocketTransport WebSocket 双向通信 │ │
18+
│ │ ├─ WorkerStateTransport Worker 线程通信 │ │
19+
│ │ └─ SerialBatchTransport 串行批处理 │ │
20+
│ └─────────────────────────────────────────────────────────────┘ │
21+
│ │
22+
│ ┌─────────────────────────────────────────────────────────────┐ │
23+
│ │ Handler 模块 (8个, 按 subcommand 分发) │ │
24+
│ │ ├─ agents / auth / mcp / autoMode / ... │ │
25+
│ │ ├─ StructuredIO (结构化输入输出) │ │
26+
│ │ └─ Rollback 机制 │ │
27+
│ └─────────────────────────────────────────────────────────────┘ │
28+
└───────────────────────────────────────────────────────────────────┘
29+
```
30+
31+
## 当前问题
32+
33+
127文件独立目录但未抽为 package
34+
35+
## 改动范围
36+
37+
提取为 `packages/cli/`, 仅被 entry layer 引用
38+
39+
## 依赖方向
40+
41+
← cli.tsx / main.tsx; → packages/agent

‎specs/feature-command-system/design.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# 命令系统设计
2+
3+
> 来源: V6.md 八
4+
> 优先级: P2
5+
> 风险: 低
6+
7+
## 用户输入 "/" 触发流程
8+
9+
```
10+
REPL.tsx (用户按 Enter)
11+
│
12+
▼
13+
handlePromptSubmit.ts (610行)
14+
│
15+
▼
16+
processUserInput.ts (605行) ─── 识别 "/" 前缀
17+
│
18+
▼
19+
processSlashCommand.tsx (921行) ─── 命令分发器
20+
│
21+
│ 解析命令名 + 参数
22+
│ findCommand() → 查找 Command 对象
23+
│
24+
├──────────────┬──────────────────┬─────────────────┐
25+
▼ ▼ ▼ ▼
26+
┌─────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────┐
27+
│ local │ │ local-jsx │ │ prompt │ │ 未知命令 │
28+
│ │ │ │ │ │ │ → 错误 │
29+
│ load() │ │ load() │ │ getPrompt() │ └──────────┘
30+
│ →call() │ │ →call() │ │ → 注入消息 │
31+
│ →结果 │ │ → ReactNode│ │ → 发送查询 │
32+
└─────────┘ └─────────────┘ └──────────────┘
33+
│ │ │
34+
└──────────────┴──────────────────┘
35+
│
36+
▼
37+
返回结果给 REPL
38+
```
39+
40+
## 命令注册
41+
42+
`src/commands.ts (~470行)`
43+
44+
```
45+
┌───────────────────────────────────────────────────────────────────┐
46+
│ COMMANDS() ─── 静态注册 ~96 个命令 │
47+
│ (71个静态导入 + 条件feature控制 + ~25个INTERNAL_ONLY) │
48+
│ │
49+
│ ┌─ src/commands/ (93个目录, 228文件) ─── 每个命令: │
50+
│ │ name, description, aliases, type │
51+
│ │ load: () => import('./impl.js') ← 懒加载 │
52+
│ │ isEnabled(), availability │
53+
│ └──────────────────────────────────────────────────────────────── │
54+
└───────────────────────────────────────────────────────────────────┘
55+
+
56+
┌───────────────────────────────────────────────────────────────────┐
57+
│ getCommands() ─── 动态源 (合并到最终列表) │
58+
│ │
59+
│ ├─ getSkillDirCommands() .claude/commands/ + skills/ │
60+
│ ├─ getBundledSkills() 内置 skill │
61+
│ ├─ getPluginSkills() 插件 skill │
62+
│ ├─ getPluginCommands() 插件命令 │
63+
│ ├─ getWorkflowCommands() workflow 脚本命令 │
64+
│ └─ getDynamicSkills() 运行时动态发现 │
65+
└───────────────────────────────────────────────────────────────────┘
66+
│
67+
▼
68+
过滤: isEnabled → meetsAvailability → 去重
69+
│
70+
▼
71+
findCommand() / getCommand() / hasCommand()
72+
(按 name, alias 查找, Fuse.js 模糊匹配)
73+
```
74+
75+
## 自动补全
76+
77+
`useTypeahead (1384行)`
78+
79+
```
80+
用户键入 "/"
81+
│
82+
▼
83+
generateCommandSuggestions() (567行)
84+
│
85+
▼
86+
Fuse.js 模糊搜索 ─── 精确 > alias > 前缀 > 模糊
87+
│
88+
▼
89+
Ghost Text 补全 / 列表选择 / Tab/Enter 确认
90+
```
91+
92+
## 耦合特征
93+
94+
- commands.ts (~470行) 静态导入所有命令, 新增命令必须手动注册
95+
- src/commands/ 93个目录 228文件, 每个命令独立目录
96+
- processSlashCommand.tsx switch 分发, 新命令类型需改分发器
97+
- SkillTool (1109行) 提供第二条路径: 模型直接调用 skill
98+
- REMOTE_SAFE_COMMANDS / BRIDGE_SAFE_COMMANDS 硬编码安全列表

‎specs/feature-compaction/design.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Compaction 服务设计
2+
3+
> 来源: V6.md 四 4.11
4+
> 优先级: P2
5+
> 风险: 低
6+
7+
```
8+
┌───────────────────────────────────────────────────────────────────┐
9+
│ CompactionService (packages/agent 内) │
10+
│ src/services/compact/ (29文件, 4267行) │
11+
│ │
12+
│ ┌─────────────────────────────────────────────────────────────┐ │
13+
│ │ CompactionStrategy (策略模式) │ │
14+
│ │ │ │
15+
│ │ ├─ SnipCompaction 精确裁剪 (保留首尾, 裁剪中间) │ │
16+
│ │ ├─ MicroCompaction 摘要压缩 (每 N 轮自动摘要) │ │
17+
│ │ └─ AutoCompaction 智能压缩 (按 token budget 触发) │ │
18+
│ └──────────────────────────┬──────────────────────────────────┘ │
19+
│ │ │
20+
│ ┌──────────────────────────▼──────────────────────────────────┐ │
21+
│ │ ContextWindowManager │ │
22+
│ │ ├─ token 计数 / budget 分配 │ │
23+
│ │ ├─ 触发阈值检测 (80%/90%/95%) │ │
24+
│ │ └─ prompt 构造 (摘要请求 → 模型 → 替换历史) │ │
25+
│ └─────────────────────────────────────────────────────────────┘ │
26+
└───────────────────────────────────────────────────────────────────┘
27+
```
28+
29+
## 当前问题
30+
31+
逻辑分散在 query.ts + services/compact/ 两处
32+
33+
## 改动范围
34+
35+
统一到 `packages/agent/compaction/`
36+
37+
## 依赖方向
38+
39+
← QueryEngine 调用; → packages/provider (摘要请求)

‎specs/feature-config/design.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# 配置管理系统设计
2+
3+
> 来源: V6.md 四 4.9
4+
> 优先级: P2 (基础设施层)
5+
> 风险: 低-中
6+
7+
```
8+
┌───────────────────────────────────────────────────────────────────┐
9+
│ packages/config (~9700行) │
10+
│ │
11+
│ ┌─────────────────────────────────────────────────────────────┐ │
12+
│ │ SettingsManager │ │
13+
│ │ ├─ 7 层优先级合并 (低→高, 后者覆盖前者): │ │
14+
│ │ │ 1. userSettings ~/.claude/settings.json │ │
15+
│ │ │ 2. projectSettings .claude/settings.json │ │
16+
│ │ │ 3. localSettings .claude/local/settings.json │ │
17+
│ │ │ 4. policySettings 企业管理 (远程下发) │ │
18+
│ │ │ 5. flagSettings GrowthBook feature flags │ │
19+
│ │ │ 6. cliArg --allowed-tools 等 CLI 参数 │ │
20+
│ │ │ 7. session 临时 ("始终允许" 按钮产生) │ │
21+
│ │ └─ get(key) / set(key, value, source) / watch(key, cb) │ │
22+
│ └─────────────────────────────────────────────────────────────┘ │
23+
│ │
24+
│ ┌──────────────────────┐ ┌──────────────────────────────────┐ │
25+
│ │ FeatureFlagProvider │ │ SettingsSync │ │
26+
│ │ ├─ BunBundle │ │ ├─ 跨设备同步 (已部分实现) │ │
27+
│ │ ├─ EnvVar │ │ ├─ 冲突检测/合并 │ │
28+
│ │ ├─ ConfigFile │ │ └─ RemoteManagedSettings │ │
29+
│ │ ├─ Remote (GrowthBook)│ │ (企业管控配置) │ │
30+
│ │ └─ feature(name)→bool│ └──────────────────────────────────┘ │
31+
│ └──────────────────────┘ │
32+
│ │
33+
│ ┌─────────────────────────────────────────────────────────────┐ │
34+
│ │ GlobalConfig (src/utils/config.ts, 1821行) │ │
35+
│ │ ├─ apiKey / oauthToken / customApiKeyResponses │ │
36+
│ │ ├─ preferredNotifChannel / projects (per-project) │ │
37+
│ │ ├─ saveGlobalConfig / getGlobalConfig (文件锁+新鲜度监控) │ │
38+
│ │ └─ trust dialog / config backup / default factory │ │
39+
│ └─────────────────────────────────────────────────────────────┘ │
40+
└───────────────────────────────────────────────────────────────────┘
41+
```
42+
43+
## 当前问题
44+
45+
- settings/(3文件 1411行) + config.ts(1821行) 混在utils
46+
- feature() 使用181处, 分布在30+文件, 提取需谨慎
47+
48+
## 改动范围
49+
50+
提取为独立 package, 作为最底层基础设施
51+
52+
## 依赖方向
53+
54+
被 packages/agent, packages/permission 等所有模块依赖

‎specs/feature-context-pipeline/design.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Context Pipeline 设计
2+
3+
> 来源: V6.md 四 4.6
4+
> 优先级: P2
5+
> 风险: 低
6+
7+
```
8+
┌──────────────────────────────────────────────────┐
9+
│ System Prompt 装配 │
10+
│ │
11+
│ ┌────────────────────────────────────────────┐ │
12+
│ │ ContextProvider[] │ │
13+
│ │ (按 priority 排序, 可插拔) │ │
14+
│ │ │ │
15+
│ │ ┌─ GitStatusProvider ──── priority: 10 │ │
16+
│ │ ├─ ClaudeMdProvider ──── priority: 20 │ │
17+
│ │ ├─ DateProvider ──────── priority: 30 │ │
18+
│ │ ├─ AttributionProvider ─ priority: 40 │ │
19+
│ │ ├─ AdvisorProvider ──── priority: 50 │ │
20+
│ │ └─ CustomProvider ────── priority: 99 │ │
21+
│ │ (用户通过配置注册) │ │
22+
│ └────────────────────────────────────────────┘ │
23+
│ │ │
24+
│ ▼ │
25+
│ 最终 System Prompt │
26+
└──────────────────────────────────────────────────┘
27+
```
28+
29+
## 当前问题
30+
31+
- context.ts (189行, 轻量) 提供上下文
32+
- claude.ts buildSystemPromptBlocks() 做 prompt 缓存分块
33+
- 无自定义 hook 点
34+
35+
## 改动范围
36+
37+
集中在 prompt 装配逻辑 (claude.ts + context.ts)

0 commit comments

Comments
 (0)