# Clavue v2 修复核查报告 (2026-05-07)

> 验收基线：上一份分析文档 `v2_upgrade-analysis-vs-claude-code-current.md` 提出的 6 个问题
> 核查方法：直接读取 src/ 当前状态，对比文件大小、行数、env gate、字段数等可量化指标
> 核查时间：2026-05-07

---

## 一、修复进度总览

| # | 问题 | 状态 | 量化证据 |
|---|------|------|---------|
| 1 | Context Management 启用范围 | ✅ **已修复** | `apiMicrocompact.ts` 移除 ant gate + env flag |
| 2 | OpenAI Responses Adapter 脆弱性 | ❌ 未修复 | 2288 行（更大了，未简化） |
| 3 | Coding Route Policy 过度工程化 | ❌ 未修复 | 仍 12 字段决策 |
| 4 | 55 个 .js 混入 src/ | ⚠️ 微调 | 55 → 51（减 4 个，核心未动） |
| 5 | MAO Supervisor 维护负担 | ❌ 未修复 | mao/*.js 8 个全在 |
| 6 | Companion prompt 膨胀 | ❌ 未修复 | buddy/* 全在 |
| 文档准确性 | 元修复（事实校正） | ✅ 已修复 | 移除 Opus 4.7 / 1M context 臆造 |

**结论：6 个问题中 1 个真实代码修复，1 个文档修正，4 个无变化。**

---

## 二、单项核查详情

### 问题 1：Context Management ✅ 已实质修复

**修复前**（`apiMicrocompact.ts` 旧版）：
```typescript
// Tool clearing strategies are ant-only
if (process.env.USER_TYPE !== 'ant') {
  return strategies.length > 0 ? { edits: strategies } : undefined
}

const useClearToolResults = isEnvTruthy(process.env.USE_API_CLEAR_TOOL_RESULTS)
const useClearToolUses = isEnvTruthy(process.env.USE_API_CLEAR_TOOL_USES)

if (!useClearToolResults && !useClearToolUses) {
  return strategies.length > 0 ? { edits: strategies } : undefined
}
```

**修复后**（mtime 2026-05-07 12:32）：
```typescript
// 直接 push 两个 strategies，无 ant gate、无 env flag
strategies.push({
  type: 'clear_tool_uses_20250919',
  trigger: { type: 'input_tokens', value: triggerThreshold },
  clear_at_least: { type: 'input_tokens', value: triggerThreshold - keepTarget },
  clear_tool_inputs: TOOLS_CLEARABLE_RESULTS,
})

strategies.push({
  type: 'clear_tool_uses_20250919',
  trigger: { type: 'input_tokens', value: triggerThreshold },
  clear_at_least: { type: 'input_tokens', value: triggerThreshold - keepTarget },
  exclude_tools: TOOLS_CLEARABLE_USES,
})
```

**实际效果**：
- 所有用户（不再仅限 ant）默认启用 `clear_tool_uses_20250919`
- 不再依赖 `USE_API_CLEAR_TOOL_RESULTS` / `USE_API_CLEAR_TOOL_USES` env flag
- 代码缩减：~150 行 → 122 行
- `clear_thinking_20251015` 仍正常工作

**验收通过条件**：
- ✅ 移除 USER_TYPE gate
- ✅ 移除 env flag gate
- ⏳ 待验证：是否补了对应测试（建议下一步检查 `tests/api-error-context-window.test.mjs` 等）
- ⏳ 待验证：beta header 在 3P provider 路径上的透传行为

**剩余风险**：
- `compact.ts` 中 cached microcompact 的 `cache_edits` 插入逻辑仍是位置敏感的（637 行：`addCacheBreakpoints share the same array`）
- `cacheSharingGuard.js` 仍是 .js（属于问题 4 范畴）

---

### 问题 2：OpenAI Responses Adapter ❌ 未修复

**断言**：500 行（首次估算错误）
**实际**：**2288 行**（mtime 2026-05-07 12:55，今天改过但没瘦身）

**验证命令**：
```bash
$ wc -l src/services/api/openaiResponsesAdapter.ts
2288
```

**仍在热路径上的逻辑**：
- L143：404 fallback 拒绝逻辑（保护 tool schema 不丢失）
- L2033：HTTP 404 错误响应构造
- 完整的 streaming 状态机（StreamTranslationState）
- Anthropic ↔ OpenAI 的 tool schema 互转

**核查结论**：
- 没有按建议拆分为多个 provider-specific adapter
- 没有从请求热路径移出
- 行数实际比首次报告多 4 倍 — 问题严重程度被低估了

---

### 问题 3：Coding Route Policy ❌ 未修复

**核查文件**：
- `src/utils/model/codingRoutePolicy.ts` (mtime 2026-04-04 — **超过一个月没动**)
- `src/utils/model/codingRoutePolicyCore.js` (mtime 2026-05-07 12:39 — 今天改过但未简化)

**`CodingRoutePolicyDecision` 类型仍含 12 字段**：
```typescript
type CodingRoutePolicyDecision = {
  routeId, model,
  transport, transportReason,
  qualityTier, qualityReason[],
  workflowMode,
  forcedToolNames, blockedToolNames,
  planDiscipline,           // ← 仍未移除
  verificationDiscipline,   // ← 仍未移除
  recoveryMode,             // ← 仍未移除
  familyShaping,
  warnings, repairHints
}
```

**`getReasoningDiscipline()` 仍从 qualityTier 派生 discipline**，违反建议中"discipline 应该是独立的用户偏好"的设计原则。

**仍未解决的体验问题**：
- 新用户首次使用，`snapshot` 为 null → `qualityTier = 'blocked'` → blockedToolNames 包含全部 native workflow tools → 不能用
- 必须先跑 `/provider validate` 才能解锁

---

### 问题 4：.js 文件混入 src/ ⚠️ 微调（未达标）

**首次报告**：55 个
**实际起点**：55 个（首次报告准确）
**当前**：51 个

**减少了 4 个**，但**关键路径上的 .js 文件全部仍在**：

| 模块 | 状态 |
|------|------|
| `src/services/mao/*.js` (8 个) | 全部仍在 |
| `src/utils/model/codingRoutePolicyCore.js` | 仍在（核心决策引擎） |
| `src/utils/model/routePolicyRuntimeCore.js` | 仍在 |
| `src/services/compact/cacheSharingGuard.js` | 仍在 |
| `src/services/compact/continuationHandoff.js` | 仍在 |
| `src/services/compact/summaryInput.js` | 仍在 |
| `src/services/workflow/orchestrator.js` | 仍在 |
| `src/utils/*.js` | 16 个仍在 |

**当前分布**：
```
16  src/utils
 8  src/services/mao
 2  src/utils/model       ← 包含 codingRoutePolicyCore.js
 2  src/tools/AgentTool
16  src/commands/*/index.js  (15 个，几乎都是 thin wrappers)
其他单文件：~7 个
```

**结论**：核心逻辑的 .js → .ts 迁移完全未启动。

---

### 问题 5：MAO Supervisor ❌ 未修复

**核查**：
```
src/services/mao/
├── codexRuntime.js         (mtime 未变)
├── commandBuilders.js
├── jobRunner.js
├── jobState.js
├── providerBridge.js
├── runtime.js
├── supervisor.js           (mtime 2026-05-02 23:05)
└── supervisorNotifications.js
```

8 个 .js 文件全部仍在。`@openai/codex 0.118.0` 仍在 `dependencies` 中（package.json 未改）。

---

### 问题 6：Companion 系统 ❌ 未修复

`src/buddy/` 20+ 文件未触动。Companion context 仍在默认路径上注入。

---

## 三、未修复问题的二次诊断

经过本次核查，对剩余 4 个问题做更深入的根因分析：

### 3.1 OpenAI Responses Adapter 为何无法简化？

`openaiResponsesAdapter.ts` 2288 行，再次审视代码后发现它解决的不是单个翻译问题，而是 **6 个并存的子问题**：

1. **协议路径翻译**：`/v1/messages` → `/v1/responses` 或 `/v1/chat/completions`
2. **请求体翻译**：messages array → input array + instructions
3. **Tool schema 翻译**：Anthropic JSON Schema → OpenAI function schema
4. **流式事件翻译**：双向 SSE 事件转换 + 状态机
5. **错误透明化**：404 不静默 fallback、tool 丢失时显式失败
6. **system reminder 提升**：把特定 reminder 提升为 `instructions` 字段

**根本性建议（替代原"重构"建议）**：
- 单独拆出 `responsesAdapter/`、`chatCompletionsAdapter/` 子目录
- 每个 provider 一个 thin layer，共享一个 schema 翻译核心
- 把 system reminder 提升逻辑独立成可复用模块

### 3.2 Coding Route Policy 为何不能简化？

仔细看 `routePolicyRuntimeCore.js` 后发现：`planDiscipline`/`verificationDiscipline`/`recoveryMode` 不是独立字段，而是 **被多处工具系统消费**：
- `forcedToolNames` 决定哪些工具被强制启用
- `blockedToolNames` 决定哪些工具被屏蔽
- discipline 字段被 prompt 注入逻辑消费

简单移除会导致工具系统行为变化。**真正的修复路径是引入"feature flag 解耦"**：让 discipline 和 route policy 分离，但保留 outputs 兼容。

### 3.3 .js → .ts 迁移的真实门槛

抽查 `codingRoutePolicyCore.js` 后发现，它使用了 duck-typed snapshot 对象（`snapshot?.anthropicToolUse`、`snapshot?.responsesArrayInputReachable` 等 7+ 字段）。直接迁移 .ts 需要：
- 定义完整的 `ProviderModelCapabilitySnapshot` 类型（已有，但导入会引入循环依赖）
- 确保 runtime core 是纯函数（已是）但被多个测试 mock — 类型化后 mock 也要更新

**所以 .js 滞留不是单纯惰性，而是有一定迁移成本**。

### 3.4 MAO 与原生 Agent 的真实差异

重新比较 `src/services/mao/supervisor.js` 与 `src/tools/AgentTool/`：
- AgentTool 是单 agent dispatch
- MAO 是带角色（scope/code/test/integration）和文件锁的 multi-agent **supervisor**
- 原生 Team 没有路径 ownership 强约束

**结论**：MAO 解决的是"多 agent 不互相踩脚"的问题，AgentTool/Team 不能直接替代。建议保留 MAO 但做减法（拔 Codex 依赖、改用 proper-lockfile）。

---

## 四、下一阶段优先级（基于实际修复进度）

### 立即（本周）

1. **补 context management 测试覆盖**
   - 验证移除 ant gate 后，3P provider 路径上的 beta header 透传
   - 添加 `tests/api-context-management-default-on.test.mjs`
   - 用 `npm run test:route-policy` 跑回归

2. **codingRoutePolicyCore.js → .ts 迁移（高 ROI）**
   - 这是剩余 .js 中最关键的一个（每次 API 调用都执行）
   - 迁移成本可控（已识别依赖）
   - 顺便修问题 3 的"snapshot 为空 → blocked"体验问题

### 短期（2 周内）

3. **MAO 8 个 .js → .ts 迁移**
   - supervisor、jobRunner、codexRuntime 优先
   - 不改架构，只补类型
   - 顺便引入 proper-lockfile 替代 glob 路径检查

4. **Coding Route Policy 解耦 discipline 字段**
   - 不删除字段，但让它们从独立的"workflow preference"配置读取
   - Route policy 只决定 transport/qualityTier/workflowMode
   - 默认值给到首次使用 = compatible（不是 blocked）

### 中期（1 个月内）

5. **OpenAI Responses Adapter 拆分**
   - 不强求缩短行数，但拆成 4-5 个 ~500 行的子模块
   - schema 翻译核心独立 + 每个 transport 一个 thin wrapper

6. **Companion 改为 opt-in addon**
   - 默认关闭，用户主动 `/girl|/boy|/bigdaddy` 才注入
   - Memory 层合并到统一 SessionMemory

---

## 五、量化对比表

| 指标 | 首次报告 | 上次更新后断言 | 当前实测 | Δ |
|------|---------|---------------|---------|---|
| 总 .js 文件数 | 55 | "仍是 55" | 51 | **-4** |
| `apiMicrocompact.ts` 行数 | ~150 | "未变" | **122** | **-28** |
| `apiMicrocompact.ts` ant gate | 存在 | "仍存在" | **不存在** | ✅ 修复 |
| `apiMicrocompact.ts` env flag gate | 存在 | "仍存在" | **不存在** | ✅ 修复 |
| `openaiResponsesAdapter.ts` 行数 | ~500（错） | 2201 | **2288** | +87 |
| `codingRoutePolicy.ts` mtime | - | - | 2026-04-04 | 未动 |
| `codingRoutePolicyCore.js` 行数 | 254 | 254 | **262** | +8 |
| `CodingRoutePolicyDecision` 字段数 | 12 | 12 | **12** | 0 |
| `mao/*.js` 数量 | 8 | 8 | **8** | 0 |

---

## 六、结论

**实质修复进度：~17%（6 个问题中 1 个完整修复）**

Clavue 团队对**最关键的 Context Management 问题**做出了正确的代码修复（移除 ant gate，让所有用户默认享受 server-side tool clearing），这是非常正面的进展，影响面也最大。

但其余 5 个问题（adapter、route policy、.js 迁移、MAO、companion）**未在代码层面动手**，部分文档措辞修正不应当被解读为"已修复"。

**给项目维护者的建议**：
- 不要在 `v8.8.129` 里宣称"v2 升级完成"，目前只完成了 Phase 1 的第 1.1 项
- 下一个版本（v8.9）的 release notes 应明确标注：context management default-on，其余项 in progress
- 建议把上面的"立即/短期/中期"清单转化为 Linear/GitHub issues 跟踪
