# Clavue v8.8 底层架构分析与升级建议

> 对比基线：Claude Code 当前公开能力（模型以已确认配置为准，不臆造 Opus 4.7 / 1M context）
> 分析日期：2026-05-07
> 分析范围：src/ 1965 文件，242K 行 TypeScript/TSX/JS

---

## 一、核心架构差异总结

| 维度 | Claude Code (当前) | Clavue v8.8 | 差距评估 |
|------|-------------------|-------------|----------|
| 上下文管理 | 服务端 context management + 自动 compaction | 已接入 `context_management.edits` + 客户端 fallback | **启用范围与测试差距** |
| 模型路由 | 单一 Anthropic 原生路由 | 多 provider profile + coding route policy | 复杂度过高 |
| 工具系统 | 原生 tool_use，服务端管理 | 双协议适配器 (messages + responses) | 兼容性风险 |
| Agent 架构 | 原生 sub-agent + team | 同 + MAO supervisor + Codex runtime | 维护负担重 |
| Companion 系统 | 无 | girl/boy/bigdaddy 角色系统 | 独有特性 |
| 构建系统 | Bun bundle (官方) | esbuild + 手动 dist 管理 | 构建链脆弱 |
| 源码纯度 | 严格 TS-only src/ | 55 个 .js 文件混入 src/ | 违反自身 purity rules |

---

## 二、底层逻辑问题诊断

### 问题 1：Context Management 结论需修正（严重但不是空白）

**现状修正**：Clavue 已经接入 Anthropic beta 的服务端 context management 主路径，不是完全停留在客户端 compaction。

```
src/services/compact/
├── apiMicrocompact.ts      ← 生成 context_management.edits
├── microCompact.ts         ← 维护 cached microcompact 的 pending/pinned cache edits
├── reactiveCompact.ts      ← prompt_too_long 后的 fallback 恢复
├── autoCompact.ts          ← 客户端 proactive fallback
├── cacheSharingGuard.js    ← 手动 cache 保护
└── summaryInput.js         ← summary compact fallback 输入

src/services/api/claude.ts  ← 统一发送 betas、context_management、cache_edits、cache_reference
src/utils/betas.ts          ← beta header 合并与 SDK allowlist
```

**实际数据流**：
- `getAPIContextManagement()` 生成 `context_management.edits`，包含 `clear_tool_uses_20250919` 与 `clear_thinking_20251015`
- `paramsFromContext()` 只在 beta header 存在时把 `context_management` 写入 Anthropic 请求体
- cached microcompact 通过 `cache_edits` / `cache_reference` 在 API 层维护 cache 边界
- `reactiveCompact` 和 summary compact 仍作为 fallback 存在

**仍存在的问题**：
- 工具清理策略依赖 `USER_TYPE === 'ant'` 与环境变量 `USE_API_CLEAR_TOOL_RESULTS` / `USE_API_CLEAR_TOOL_USES`，外部用户默认不走完整 server-side tool clearing
- 文档和命名容易误导：代码叫 `context_management.edits`，不是 `context_edits`
- cached microcompact 的 `cache_edits` 插入逻辑位置敏感，仍是维护风险
- 客户端 fallback 仍然复杂，但不能直接删除

**建议**：不需要另起一个 Clavue 服务器来实现 context edits；如果直连 Anthropic，客户端传 beta header 与请求体即可。只有当请求经过自建 proxy/gateway 时，服务端才必须透传 `betas`、`context_management`、`cache_edits`、`cache_reference`，否则会退化或 400。短期升级应聚焦：扩大安全启用范围、补测试、减少 fallback 复杂度。

---

### 问题 2：双协议适配器的脆弱性（严重）

**现状**：`openaiResponsesAdapter.ts` 是一个 ~500 行的协议翻译层，把 Anthropic messages 格式转成 OpenAI Responses/Chat Completions 格式。

```typescript
// 翻译链路：
Anthropic tool_use schema
  → OpenAI function calling schema
  → 上游 gateway 执行
  → OpenAI streaming events
  → 翻译回 Anthropic streaming events
```

**问题**：
1. **有损翻译**：Anthropic 的 `cache_control`、`citations`、`thinking` blocks 无法映射到 OpenAI 格式
2. **流式翻译状态机复杂**：`StreamTranslationState` 需要跟踪 block 类型、function call 映射、message 生命周期
3. **错误表面积大**：404 fallback、tool schema 丢失、partial responses 等边界情况多
4. **Claude Code 不需要这层**：原生只走 Anthropic messages API

**性能影响**：
- 每个 streaming chunk 都要经过翻译 = 额外延迟
- JSON parse/stringify 在热路径上
- 翻译错误会导致整个 turn 失败

**建议**：
- 对 OpenRouter/GLM/Minimax/Kimi 等 gateway，考虑直接用它们的原生 SDK 而不是翻译
- 把适配器从请求热路径移到独立的 provider adapter 层
- 对不支持 tool_use 的 provider，降级到 chat_only 而不是强行翻译

---

### 问题 3：Coding Route Policy 过度工程化（中等）

**现状**：`codingRoutePolicyCore.js` 是一个 ~250 行的决策引擎，输出 12 个字段的 policy decision。

```typescript
type CodingRoutePolicyDecision = {
  routeId, model, transport, transportReason,
  qualityTier, qualityReason[], workflowMode,
  forcedToolNames, blockedToolNames,
  planDiscipline, verificationDiscipline,
  recoveryMode, familyShaping, warnings, repairHints
}
```

**问题**：
- 这个决策在每次 API 调用前都要执行
- `ProviderModelCapabilitySnapshot` 需要预先验证（/provider validate）才能填充
- 新用户首次使用时 snapshot 为空 → 走 degraded/blocked 路径 → 体验差
- Claude Code 不需要这层：它只有一个 provider，永远是 native tier

**建议**：
- 简化为 2 层：`native`（Anthropic 直连）和 `adapted`（其他 provider）
- 去掉 `planDiscipline`/`verificationDiscipline`/`recoveryMode` 这些从 route policy 派生的字段 — 这些应该是独立的用户偏好
- 首次使用时默认 `compatible` 而不是 `blocked`

---

### 问题 4：src/ 中混入 55 个 .js 文件（中等）

**现状**：ARCHITECTURE.md 明确声明 "No generated stubs in src/"，但实际有 55 个 .js 文件：

```
src/services/mao/*.js          (8 files)
src/services/compact/*.js      (4 files)
src/services/workflow/*.js     (1 file)
src/utils/*.js                 (15+ files)
src/tools/AgentTool/*.js       (2 files)
src/commands/*/index.js        (15+ files)
```

**问题**：
- 这些 .js 文件没有类型检查 → 运行时错误风险
- 和 .ts 文件混合导致构建配置复杂
- 违反项目自身的 purity rules
- 很多是核心逻辑（codingRoutePolicyCore、supervisor、jobRunner）

**根因推测**：这些文件可能是为了绕过 TypeScript 编译问题或快速迭代而直接写的 JS。

**建议**：
- 优先级 1：把核心逻辑 .js 迁移到 .ts（mao/*, compact/*, codingRoutePolicyCore）
- 优先级 2：把 utils/*.js 迁移到 .ts
- 优先级 3：commands/*/index.js 可以保持（如果是简单的 re-export）

---

### 问题 5：MAO Supervisor 架构的可维护性（中等）

**现状**：MAO 是一个内嵌的 multi-agent orchestrator，通过 spawn 子进程运行 Codex：

```
src/services/mao/
├── supervisor.js         ← 任务分配、角色定义、文件锁
├── jobRunner.js          ← 进程管理、tree-kill
├── codexRuntime.js       ← @openai/codex 集成
├── providerBridge.js     ← provider 适配
├── commandBuilders.js    ← CLI 命令构造
└── jobState.js           ← 状态持久化
```

**问题**：
1. **依赖 @openai/codex 0.118.0**：这是一个外部 CLI 工具，版本锁定 → 上游 breaking change 风险
2. **进程管理复杂**：tree-kill、platform-specific 逻辑（Windows taskkill vs Unix SIGTERM）
3. **和 Claude Code 原生 Agent/Team 系统重叠**：Claude Code 已有 sub-agent、team、worktree 隔离
4. **文件锁机制自建**：`ownedPathGlobs`/`forbiddenPathGlobs` 是简单的 glob 匹配，不是真正的文件锁

**建议**：
- 评估是否可以用 Claude Code 原生的 Agent tool + worktree isolation 替代 MAO
- 如果保留 MAO，把 Codex 依赖做成可插拔的 runtime backend
- 文件锁应该用 OS 级别的 advisory lock（proper-lockfile 已在依赖中）

---

### 问题 6：Companion 系统的 prompt 膨胀（低）

**现状**：buddy/ 目录有 20+ 文件，实现了一个完整的 companion 角色系统：

```
src/buddy/
├── runtime.ts            ← 角色定义（girl/boy/bigdaddy）
├── advisor.ts            ← 建议生成
├── memoryCapture.ts      ← 记忆捕获
├── overlayMemory.ts      ← 覆盖记忆
├── reactionMemory.ts     ← 反应记忆
├── suggestionPolicy.ts   ← 建议策略
├── postSampling.ts       ← 后采样处理
└── ...
```

**问题**：
- 每个 turn 都要注入 companion context → 消耗 token budget
- 多个 memory 系统并行（companion memory + session memory + auto dream）→ 冲突风险
- Claude Code 没有这层 → 所有 token 都用于实际任务

**建议**：
- 把 companion 做成可选的 system prompt addon，不在默认路径上
- 合并 memory 系统：一个统一的 memory layer，companion 只是一个 consumer

---

## 三、与 Claude Code 当前版本的关键 API 差距

### 3.1 关键 API 特性差距

| 特性 | Claude Code 状态 | Clavue 状态 | 影响 |
|------|-----------------|-------------|------|
| Server-side context management | 已使用 | 已接入 `context_management.edits`，但启用范围偏保守 | 外部用户和代理路由可能退化 |
| Extended thinking (streaming) | 原生支持 | 通过 SDK 支持 | 无差距 |
| Token-efficient tool results | 已使用 | 部分依赖 beta 与环境开关 | 需要补覆盖测试 |
| Prompt caching (server-managed) | 自动 | `cache_edits` / `cache_reference` + cacheSharingGuard 混合维护 | 命中率与边界维护风险 |
| Citations | 原生支持 | 适配器中丢失 | 3P provider 无法用 |
| Files API | 已使用 | 已使用 | 无差距 |
| Batch API | 可用 | 未确认 | 批量任务效率 |

### 3.2 模型支持差距

Clavue 的 `configs.ts` 已经包含到 Opus 4.6 / Sonnet 4.6 的配置，这说明模型跟进是及时的。但：

- 当前只确认 Opus 4.6 / Sonnet 4.6 配置；不要在没有权威模型 ID 前添加 Opus 4.7 或 1M context 声明
- 模型配置是硬编码的 → 每次新模型发布都需要代码更新
- 更稳的方向是动态模型发现或 provider bootstrap，而不是把未确认模型写死

---

## 四、升级路线图建议

### Phase 1：基础设施对齐（1-2 周）

1. **扩大 server-side context management 安全启用范围**
   - 基于现有 `context_management.edits` 路径补齐 beta/header/body 透传测试
   - 保留 reactive compact 作为 fallback
   - 梳理客户端 token 计数逻辑，能退场的退场，不能退场的明确边界

2. **源码纯度修复**
   - 把 55 个 .js 文件迁移到 .ts
   - 启用 strict TypeScript 检查

3. **模型发现机制替代臆造配置**
   - 保留已确认的 Opus 4.6 / Sonnet 4.6 配置
   - 不添加未确认的 Opus 4.7 / 1M context 声明
   - 考虑动态模型发现机制

### Phase 2：架构简化（2-3 周）

4. **简化 Coding Route Policy**
   - 从 12 字段决策简化为 3 层：native / adapted / chat-only
   - 去掉 discipline/recovery 从 route 派生的逻辑
   - 首次使用默认 compatible

5. **重构 OpenAI Responses Adapter**
   - 把翻译层从请求热路径移出
   - 对每个 3P provider 做独立的 adapter（不共享一个翻译器）
   - 明确标记有损翻译的边界

6. **评估 MAO vs 原生 Agent**
   - 如果原生 Agent + worktree 能覆盖 MAO 的场景，逐步迁移
   - 如果不能，把 Codex 依赖做成可插拔 backend

### Phase 3：差异化增强（持续）

7. **Companion 系统优化**
   - 做成 opt-in addon
   - 统一 memory 层

8. **Provider Profile 体验优化**
   - 首次使用零配置可用
   - 验证流程异步化（不阻塞首次使用）

---

## 五、性能瓶颈预测

基于代码分析，以下是最可能的性能热点：

```
1. 启动时间
   - MDM raw read (subprocess)
   - Keychain prefetch (subprocess)
   - GrowthBook init
   - Bootstrap API call
   - Provider profile resolve
   预测：冷启动 > 500ms

2. 每轮延迟
   - Coding route policy resolve
   - OpenAI responses adapter (if 3P)
   - Companion context injection
   - Memory overlay merge
   预测：每轮额外 50-100ms overhead

3. 长会话退化
   - 客户端 compact 不精确 → 多余的 API 调用
   - Cache miss 率高（客户端管理 vs 服务端管理）
   - Memory 系统累积 → prompt 膨胀
   预测：20+ turns 后明显变慢
```

---

## 六、总结

Clavue 在 Claude Code 2.0.88 基础上做了大量创新（多 provider 路由、MAO 多 agent、Companion 系统），但也引入了显著的架构复杂度。核心问题是：

1. **Context management 启用范围不足** — 已有 `context_management.edits`，短板是外部用户默认启用、代理透传、测试覆盖和 fallback 收敛
2. **双协议适配器脆弱** — 每次上游 API 变更都是风险
3. **过度工程化的决策引擎** — 增加了每次请求的开销和新用户的门槛
4. **源码纯度退化** — 55 个无类型检查的 .js 文件在核心路径上

建议优先级：**Context Management > 源码纯度 > Route Policy 简化 > Adapter 重构 > MAO 评估**
