# Clavue 功能模块评分卡 — 最高标准审计

Date: 2026-04-16
Auditor: Copilot (Claude Opus 4.6)
Scope: `src/` 全部已有源代码，含 build/test/scripts 基础设施
Method: 逐文件源码审计 + 架构级交叉分析，以最高工程标准评判

---

## 总体判定

**总分: 6.9 / 10**

| 维度 | 分数 |
|------|------|
| 产品能力完备度 | 9.0 / 10 |
| 核心运行时复杂度 | 8.3 / 10 |
| 架构纯净度 | 5.6 / 10 |
| 可持续维护性 | 6.1 / 10 |
| 安全与信任模型 | 7.9 / 10 |
| 测试与验证体系 | 7.2 / 10 |
| 构建与发布系统 | 8.8 / 10 |

**结论**: 这是一个**功能极其丰富、运行时架构成熟**的产品代码库。但它**不是纯粹的高质量代码**——原因不在语法或风格，而在于**核心路径上的架构集中度过高**，以及少数关键模块承担了太多职责。

---

## 评分标尺

| 分段 | 含义 |
|------|------|
| 9.0-10.0 | 卓越: 教科书级分离, 极低回归风险 |
| 7.5-8.9 | 强: 生产级代码, 可控结构债务 |
| 6.0-7.4 | 良: 能力强但核心路径有实质设计债务 |
| 4.5-5.9 | 中: 能用, 但架构显著增加回归风险 |
| < 4.5 | 弱: 结构上脆弱 |

---

## 模块评分详表

### A 级 (8.5+) — 架构优秀

| 模块 | 分数 | 评级 | 评估 |
|------|------|------|------|
| CLI 引导/快速路径 | 8.6 | A- | 启动成本感知强, 快速路径设计正确 |
| 工具注册/工具池装配 | 8.4 | A- | 清晰的注册中心, 良好的运行时过滤 |
| 核心查询循环/流执行 | 8.1 | A- | 流式优先设计正确, 工具编排合理 |
| 构建系统 (build-plugin.mjs) | 9.0 | A | 成熟的 esbuild 插件, 烟雾测试完备 |
| 协调器模式 | 9.0 | A | 系统级指导提示, 多工人编排 |
| 声音服务 | 9.0 | A | 跨平台降级链, 延迟加载设计优秀 |
| Hook 模式定义 | 9.0 | A | 区分联合体, 循环依赖处理精细 |

### B 级 (7.0-8.4) — 生产级强度

| 模块 | 分数 | 评级 | 评估 |
|------|------|------|------|
| QueryEngine (无头运行时) | 7.8 | B+ | 最佳核心抽象之一, 但边界不完全清晰 |
| 权限/信任/策略/沙箱 | 7.9 | B+ | 信任边界显式化, 安全逻辑内嵌而非外挂 |
| MCP 集成 | 7.5 | B | 深度集成, 但 2000+ 行客户端过于越界 |
| 斜杠命令/技能/工作流加载 | 7.2 | B | 统一扩展模型, 但 commands.ts 正在膨胀 |
| 插件系统 | 8.0 | B+ | 内建/捆绑区分清晰, 可切换 UI |
| 伙伴/同伴系统 | 8.0 | B+ | 确定性的种子 PRNG, 可扩展人格系统 |
| 服务器/DirectConnect | 8.0 | B+ | WebSocket 协议清晰, 会话持久化 |
| 迁移系统 | 8.0 | B+ | 顺序执行, 每个迁移独立 |
| 源码纯净检查 | 8.0 | B+ | 有效但不可配置 |
| 测试体系 | 7.2 | B | 60+ 测试套件, 覆盖策略/回归/集成 |

### C 级 (5.0-6.9) — 能力强但结构问题显著

| 模块 | 分数 | 评级 | 评估 |
|------|------|------|------|
| 应用状态 (AppStateStore) | 6.0 | C+ | 50+ 字段的巨型 store, 无清晰所有权 |
| 远程/桥接/助手/守护进程 | 6.2 | B- | 产品能力丰富, 但增加分支复杂度 |
| 上下文构建 (context.ts) | 6.5 | B- | Git 子进程成本高, 记忆过期无 TTL |
| 成本追踪 | 6.5 | B- | 全局可变状态, 两个真相来源 |
| 品牌/产品一致性 | 5.8 | C+ | 命名在 fork/上游表面混合 |
| query.ts (查询编排) | 5.8 | C+ | 1400+ 行, 三套压缩系统无序 |
| 任务注册 | 7.0 | B- | 简单但 feature flag 未强制执行 |

### D 级 (< 5.0) — 需要重构

| 模块 | 分数 | 评级 | 评估 |
|------|------|------|------|
| 启动编排 (main.tsx) | 4.2 | D+ | **2600+ 行, 15+ 职责**, 回归爆炸半径极高 |
| 交互运行时 (REPL.tsx) | 4.0 | D | **4600+ 行, 20+ 职责**, UI 与编排纠缠 |
| Provider 配置/路由 | 4.5 | D+ | 读路径有写副作用, 过度耦合 |

---

## 核心问题深度分析

### 问题 1: main.tsx — 产品级控制塔 (4.2)

**文件行数**: ~2600 行
**职责数量**: 15+

| 嵌入的职责 | 应该在哪 |
|------------|----------|
| CLI 参数解析 | `cli/argumentParser.ts` |
| 设置 & 迁移 | `setup/settingsMigrations.ts` |
| 插件/技能/代理加载 | `setup/extensionLoader.ts` |
| MCP 配置装配 | `services/mcp/config.ts` |
| 会话初始化 | `setup/sessionInit.ts` |
| 信任/权限门控 | `setup/trustGate.ts` |
| 远程/助手模式路由 | `setup/modeRouter.ts` |

**具体缺陷**:
- 130+ imports, 80+ 模块直接耦合
- 设置迁移顺序执行, 部分 async 部分 sync — MDM 竞态
- MCP 服务器过滤在 `parseMcpConfig()` 加载所有服务器**之后** — 应在实例化前过滤
- Resume 逻辑分支不锁定会话文件, 并发恢复无保护
- 命令在 main() 内部构建而非懒加载 — 脚本模式也付出全量初始化成本

### 问题 2: REPL.tsx — 单体 React 组件 (4.0)

**文件行数**: ~4600 行
**职责数量**: 20+

这是代码库中**最严重的架构问题**。一个 React 组件承担了:
- UI 渲染 + 状态协调 + 消息队列 + 输入处理 + 查询执行 + 推测 + 蜂群生命周期 + 权限对话 + MCP 授权 + 成本追踪 + 技能调查 + 后台任务 + 会话持久化 + 键绑定 + IDE 集成 + 语音 + 主题 + Tmux + WebBrowser

**具体缺陷**:
- 20+ useState/useRef 相互依赖, 级联重渲染
- 权限请求分散在 4 个文件 (PermissionRequest.tsx / REPL.tsx / permissionSync.js / leaderPermissionBridge.js)
- `isQueryActive` 状态与 `queryGuard` 外部状态可能失同步 — 双击 Enter 可创建两个并行查询
- 任务状态清理 useEffect 有竞态 — setAppState 异步但 task.onDone() 可能同步触发
- 虚拟消息列表 `useLayoutEffect` 在 paint 后运行 — 压缩时可见抖动

### 问题 3: Provider 路由域 (4.5)

**核心问题**: 读路径产生写副作用

`getProviderProfiles()` 在返回存储的配置之前触发兼容性导入。一个**读表面不应该静默导入、同步、激活和持久化状态**。

额外缺陷:
- 模型能力检测的缓存结果存在 `globalConfig.json`, 并发 CLI 实例会竞争
- Profile 删除后 `CURRENT_PROVIDER_PROFILE_ID` 变过期, 无验证
- 6 个职责混合在一个区域: 配置持久化 + 兼容性导入 + 活跃配置同步 + 进程环境应用 + 模型元数据 + 验证/探测

### 问题 4: 循环依赖地狱

| 循环链 | 影响 |
|--------|------|
| REPL.tsx → query.ts → REPL.tsx (appState 更新) | 关键路径 |
| main.tsx → commands.ts → main.tsx (lazy require) | 启动路径 |
| tools.ts → permissions/denialTracking → tools.ts (Tool 类型) | 工具系统 |

### 问题 5: AppState 巨型 Store (6.0)

500+ 行, 50+ 字段, 没有清晰的领域分离:
- 任务状态 (tasks, foregroundedTaskId)
- MCP 状态 (clients, tools, commands)
- 插件状态 (enabled, disabled, errors)
- 推测状态 (含可变 refs, 与 DeepImmutable 矛盾)
- 同伴状态、Tmux 状态、WebBrowser 状态 — 全部 ad-hoc

### 问题 6: query.ts 三套压缩系统无清晰顺序 (5.8)

1400+ 行, 含 3 个并行压缩系统:
1. **Snip** (历史修剪)
2. **Microcompact** (工具结果缓存)
3. **ContextCollapse** (结构化消息摘要)

顺序: Snip → Microcompact → ContextCollapse → AutoCompact
但 ContextCollapse 在 Microcompact 之后、AutoCompact 之前 — **顺序未文档化**。

工具结果预算在消息发送**之前**强制执行 — API 永远看不到原始大小。

---

## 跨模块风险

### 全局可变状态散布

| 全局状态位置 | 用途 |
|-------------|------|
| bootstrap/state.js | 会话 ID, 成本, token 计数 |
| config.js | 全局配置, 项目配置 |
| providerProfiles.ts | Provider 缓存 |

跨会话恢复时持久化不一致。

### Feature Flag 散布

50+ `feature()` 调用散布在代码库中。移除一个 feature 需要 grep 全库。测试无法验证 feature 消除是否完整。

### 回调链过深

1. **工具使用权限**: REPL → permissionSync → leaderBridge → localAgentTask → teammate (6 步)
2. **MCP 认证**: client.ts → handleElicitation → REPL.tsx → PromptDialog → 用户 → 反向回调链
3. **推测**: REPL → speculation.ts → setAppState → 重渲染

---

## 最强子系统 TOP 5

| 排名 | 模块 | 分数 | 原因 |
|------|------|------|------|
| 1 | 构建系统 | 9.0 | 成熟 esbuild 插件, 编译时 dead-code 消除, 烟雾测试 |
| 2 | 协调器模式 | 9.0 | 百科全书级系统提示, 真正的验证定义 |
| 3 | Hook 模式定义 | 9.0 | 区分联合体精确, 循环依赖处理优秀 |
| 4 | 声音服务 | 9.0 | 跨平台降级链完备, 延迟加载 1-8s 开销控制 |
| 5 | 工具注册中心 | 8.4 | 清晰真相来源, prompt-cache 稳定性考量 |

## 最弱子系统 TOP 5

| 排名 | 模块 | 分数 | 原因 |
|------|------|------|------|
| 1 | REPL.tsx | 4.0 | 4600 行 20+ 职责, 代码库中最严重架构问题 |
| 2 | main.tsx | 4.2 | 2600 行 15+ 职责, 回归爆炸半径极高 |
| 3 | Provider 路由 | 4.5 | 读路径写副作用, 6 种职责混合 |
| 4 | query.ts | 5.8 | 三套压缩系统无序, 异步生成器状态管理复杂 |
| 5 | 品牌一致性 | 5.8 | Fork/上游命名混合 |

---

## 向上提升路线图

### 最高杠杆改动 (按优先级)

1. **拆分 REPL.tsx** — 从 4600 行拆为 5-8 个专注 hook + 纯 UI 层
   - 消息队列管理 → `useMessageQueue.ts`
   - 权限请求编排 → `usePermissionOrchestration.ts`
   - 键绑定设置 → `keybindings/replKeybindings.ts`
   - 蜂群协调 → `useSwarmCoordination.ts`
   - 查询执行 → `useQueryExecution.ts`

2. **拆分 main.tsx** — 从 2600 行拆为明确的启动阶段
   - `startup/cliSetup.ts` (参数解析)
   - `startup/settingsInit.ts` (设置 + 迁移)
   - `startup/extensionLoader.ts` (插件/技能/代理)
   - `startup/mcpConfig.ts` (MCP 装配)
   - `startup/sessionInit.ts` (会话恢复)
   - `startup/modeRouter.ts` (交互/无头/远程分发)

3. **Provider 读路径纯化** — 移除 `getProviderProfiles()` 中的导入副作用为显式命令

4. **AppState 分裂** — 拆为 CoreState + UIState + TransientState

5. **query.ts 压缩逻辑提取** — 三套压缩系统各自独立为模块, 顺序文档化

---

## 这是"纯粹的高质量代码"吗?

**不是。**

精确回答:
- 它是**严肃的生产代码** ✓
- 它有**多个真正优秀的子系统** ✓
- 它在**产品深度和运行时复杂度上优于平均水平** ✓
- 但它**核心架构债务**恰好集中在**最重要的位置**:
  - 启动编排 (main.tsx = 2600 行)
  - 交互编排 (REPL.tsx = 4600 行)
  - Provider 路由域边界
  - 查询流压缩系统

> **强大的产品代码库, 尚未达到高纯度架构。**

---

*审计基于: 全部核心 src/ 文件逐文件检查，架构关键表面深度探查，构建/测试/基础设施完整扫描。*
