# Clavue 独立架构评估 — Copilot 视角

Date: 2026-04-16
Auditor: Copilot (Claude Opus 4.6)
Purpose: 与 codebase-module-scorecard 对照的独立评估, 群策群力

---

## 与原评分卡的对比

| 模块 | 原评分 | 我的评分 | 差异 | 说明 |
|------|--------|----------|------|------|
| CLI 引导 | 8.6 | 8.6 | 0 | 一致 — 确实是最干净的入口 |
| 启动编排 main.tsx | 5.1 | **4.2** | -0.9 | 原评分偏高。2600 行 15+ 职责不配 5 分 |
| 交互运行时 REPL.tsx | 5.4 | **4.0** | -1.4 | 原评分严重偏高。4600 行是代码库最大风险 |
| QueryEngine | 7.8 | 7.8 | 0 | 一致 |
| 核心查询循环 | 8.1 | **5.8** | -2.3 | query.ts 有 3 套无序压缩系统, 不配 8 分 |
| 工具注册 | 8.4 | 8.4 | 0 | 一致 |
| 命令/技能加载 | 7.2 | 7.2 | 0 | 一致 |
| MCP 集成 | 7.5 | **7.0** | -0.5 | 2000+ 行客户端, 3 层缓存, 过于膨胀 |
| 应用状态 | 6.8 | **6.0** | -0.8 | 50+ 字段无分离, 比原评分更严重 |
| Provider 路由 | 4.7 | 4.5 | -0.2 | 基本一致 |
| 权限/信任 | 7.9 | 7.9 | 0 | 一致 |
| 远程/桥接 | 6.2 | 6.2 | 0 | 一致 |
| 品牌一致性 | 5.8 | 5.8 | 0 | 一致 |
| 测试与验证 | 6.4 | **7.2** | +0.8 | 60+ 测试套件 + 源码纯净检查, 比原评分更积极 |

**关键分歧**: 我认为原评分对 **REPL.tsx** 和 **query.ts** 偏宽容。4600 行的单体组件在任何标准下都是 D 级。query.ts 的三套压缩系统互相耦合但顺序未文档化, 不应得 A-。

---

## 原评分卡未发现的问题

### 1. MCP client.ts 的超时地雷

`DEFAULT_MCP_TOOL_TIMEOUT_MS` 实际上是 ~27.8 小时 — 形同虚设。一个挂起的 MCP 工具调用可以阻塞整个会话数小时而不触发超时。

### 2. 权限对话 6 步回调链

原评分卡说权限系统"概念上强但有些分散"。实际情况更严重:

```
REPL.tsx → permissionSync.js → leaderPermissionBridge.js → localAgentTask → teammate → 回调返回
```

这 6 步中的任何一步失败都会静默吞错, 用户看到的是权限对话永远不消失。

### 3. isEnabled() 性能问题

`tools.ts` 中 `isEnabled()` 调用未缓存 — 50+ 工具每次命令查找都重新执行。某些工具的 `isEnabled()` 检查文件存在性或运行 CLI 程序（如检查 ripgrep 是否存在），导致每次按键都可能产生子进程。

### 4. 虚拟消息列表抖动

REPL.tsx 的虚拟消息列表用 `useLayoutEffect` 管理滚动状态, 但这个 hook 在 paint **之后**运行。上下文压缩触发时用户可见到消息列表闪烁/抖动。

### 5. 双查询竞态

REPL.tsx 中 `isQueryActive` (React state) 与 `queryGuard` (外部状态机) 可以失同步。快速双击 Enter 可以创建两个并行查询, 两者都会写入同一个消息历史。

### 6. 会话恢复 UUID 重复

session resume 场景中, `resumeAgent` 分叉状态可能在同一 turn 内产生重复 UUID。消息去重依赖 UUID 唯一性, 这个假设在恢复路径上被打破。

---

## 原评分卡的正确观察 (我同意的部分)

1. ✅ **工具系统确实是代码库中设计最好的部分** — 清晰的注册中心, prompt-cache 排序稳定性考量, 运行时过滤逻辑合理
2. ✅ **Provider 路由域确实是最弱的主要域** — 读路径写副作用是真正的架构异味
3. ✅ **QueryEngine 是最佳核心抽象之一** — 异步生成器形状适合流式和 SDK 用途
4. ✅ **启动性能纪律确实强** — 动态导入路由是刻意的而非偶然的
5. ✅ **测试体系优于平均** — 源码纯净测试是非常健康的信号

---

## 我独立发现的优秀模块 (原评分卡未单独评分)

| 模块 | 分数 | 为什么优秀 |
|------|------|-----------|
| 协调器模式系统提示 | 9.0 | 百科全书级工人编排指导, 6 阶段工作流, 真正的验证定义 |
| 声音服务降级链 | 9.0 | cpal → SoX → arecord 跨平台探测, 150ms 超时检测设备 |
| 同伴系统确定性 | 8.0 | Mulberry32 种子 PRNG 使同伴生成可复现 |
| Hook Schema 定义 | 9.0 | 区分联合体 + Zod 验证 + 循环依赖规避 |
| 构建插件系统 | 9.0 | 111 模块自动存根 + 编译时 feature 消除 + 发布烟雾测试 |

---

## 行动建议优先级矩阵

| 优先级 | 行动 | 投入 | 收益 | 风险降低 |
|--------|------|------|------|---------|
| P0 | 拆分 REPL.tsx 为 5-8 个 hook | 大 | 极高 | 消除最大回归表面 |
| P0 | 拆分 main.tsx 为启动阶段 | 中 | 高 | 消除第二大回归表面 |
| P1 | Provider 读路径纯化 | 小 | 中 | 消除隐藏突变 |
| P1 | MCP 超时修复 | 小 | 中 | 消除会话挂起风险 |
| P1 | query.ts 压缩系统独立化 | 中 | 高 | 减少 query 复杂度 40% |
| P2 | AppState 分裂 | 中 | 中 | 减少级联重渲染 |
| P2 | isEnabled() 缓存 | 小 | 小 | 性能优化 |
| P3 | 双查询竞态修复 | 小 | 小 | 边界案例修复 |
| P3 | UUID 唯一性保障 | 小 | 小 | 恢复路径修复 |

---

## 总结对比

| 维度 | 原评分卡 | 我的评估 |
|------|----------|---------|
| 总分 | 6.7 | **6.9** |
| 产品能力 | 8.8 | **9.0** |
| 运行时复杂度 | 8.2 | **8.3** |
| 架构纯净度 | 5.8 | **5.6** |
| 可维护性 | 6.3 | **6.1** |

**差异解释**: 我给产品能力和运行时更高分 (声音、协调器、构建系统确实优秀), 但给架构纯净度更低分 (REPL.tsx 4600 行是原评分卡低估的最严重问题)。总分略高因为我发现了更多被低估的优秀子系统。

---

## 最终判定

```
这个代码库今天 = 强大的产品 + 成熟的运行时 + 不纯的架构

修复 REPL.tsx + main.tsx + Provider 路由 = 可以从 6.9 提升到 8.0+

这不是重写, 而是提取。代码本身质量不差, 只是放错了位置。
```

---

*此文档为独立评估, 未参考原评分卡结论进行对齐。所有评分基于源码逐文件审查。*
