mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 13:55:50 +00:00
feat: 整合功能恢复与技能学习闭环(含 ECC v2.1 parity + Opus 4.7 接入 + prompt 工程优化)
主要变更: - Skill Learning 闭环系统 (9/9 AC) - Opus 4.7 模型层接入 + adaptive thinking - Prompt 工程优化 (64 审计测试) - Agent Teams 简化门控 (默认启用) - Windows Terminal 后端修复 (EncodedCommand/WT_SESSION) - TF-IDF 技能搜索精准化 (字段加权/CJK 优化) - Autonomy 系统 (/autonomy 命令) - ACP 协议完整实现 - mock.module 泄漏修复 (CI 全绿) - 152+ lint/type 修复
This commit is contained in:
unraid
221
docs/codex-analysis-methodology.md
Normal file
221
docs/codex-analysis-methodology.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 为什么用 Codex 分析官方 Claude Code CLI
|
||||
|
||||
> 文档日期: 2026-04-15
|
||||
> 适用范围: 本 fork 项目的逆向工程与功能恢复工作流
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
本项目是 Anthropic 官方 Claude Code CLI 的逆向/反编译版本。官方发行版是经过 bundle + minify 的产物，核心逻辑被混淆，大量模块被 stub 化或 feature-flag 门控。我们的目标是：
|
||||
|
||||
1. 恢复被 stub 的核心功能
|
||||
2. 理解 feature flag 之间的依赖关系
|
||||
3. 确保恢复后的代码与上游 API 协议兼容
|
||||
4. 发现潜在的运行时陷阱（如空 beta header、缺失的 GrowthBook 门控）
|
||||
|
||||
这些任务的共同特点是：**代码量巨大、上下文分散、需要跨文件追踪调用链**。单靠人工审阅或单一 AI 助手效率有限，且容易形成"自我确认偏差"。
|
||||
|
||||
---
|
||||
|
||||
## 为什么选择 Codex 做交叉验证
|
||||
|
||||
### 1. 独立视角消除确认偏差
|
||||
|
||||
Claude Code 在分析自己的代码时，存在天然的盲区：
|
||||
|
||||
- **上下文惯性**: Claude 在长对话中容易沿着已有假设继续推理，而不会从零开始质疑
|
||||
- **自我一致性倾向**: 如果 Claude 在第 10 轮说"这个 feature 是 COMPLETE"，到第 50 轮它倾向于维持这个结论
|
||||
- **上下文窗口压力**: 对话越长，早期细节越容易被压缩丢失
|
||||
|
||||
Codex 作为完全独立的分析引擎，从零读取代码，不受前序对话影响。它的判断是"冷启动"的，正好补偿了 Claude 的"热启动"偏差。
|
||||
|
||||
**实际案例**:
|
||||
- Claude 最初将 22 个 feature flag 标记为 COMPLETE
|
||||
- Codex 独立审查后降级了其中 9 个（见 `docs/features/feature-flags-codex-review.md`）
|
||||
- 后续验证证实 Codex 的降级判断全部正确
|
||||
|
||||
### 2. 全代码库扫描能力
|
||||
|
||||
官方 CLI 代码量巨大（`src/` 下超过 400 个文件），关键逻辑分散在多层调用链中。典型的分析任务需要：
|
||||
|
||||
| 任务类型 | 需要跨越的文件数 | 示例 |
|
||||
|----------|-----------------|------|
|
||||
| Feature flag 审计 | 10-30 | 编译常量 → 门控函数 → 调用点 → stub 实现 |
|
||||
| Beta header 追踪 | 5-15 | 常量定义 → betas 组装 → SDK 调用 → API 响应处理 |
|
||||
| 工具系统分析 | 20-50 | Tool 接口 → 注册表 → 权限检查 → 执行器 → UI 渲染 |
|
||||
|
||||
Codex 的 `full-auto` 模式可以不受上下文窗口限制地逐文件扫描，不会遗漏角落。
|
||||
|
||||
### 3. 成本效率
|
||||
|
||||
| 方法 | 单次审查耗时 | Token 消耗 | 可重复性 |
|
||||
|------|-------------|-----------|---------|
|
||||
| 人工审阅 | 4-8 小时 | — | 低（疲劳、遗漏） |
|
||||
| Claude 单次分析 | 10-30 分钟 | ~100K | 中（受上下文窗口限制） |
|
||||
| Codex full-auto | 5-15 分钟 | ~200-300K | 高（确定性扫描） |
|
||||
| Claude + Codex 交叉验证 | 20-40 分钟 | ~400K | 高（互补覆盖） |
|
||||
|
||||
最后一种方式的总成本适中，但显著提高了结论可信度。
|
||||
|
||||
---
|
||||
|
||||
## 工作流
|
||||
|
||||
### 阶段一：Claude 初步分析
|
||||
|
||||
```
|
||||
用户提出问题/任务
|
||||
↓
|
||||
Claude 在对话中分析代码、形成初步结论
|
||||
↓
|
||||
输出结构化的发现报告（文件路径、行号、状态判断）
|
||||
```
|
||||
|
||||
### 阶段二：Codex 独立验证
|
||||
|
||||
```
|
||||
将 Claude 的结论（或原始问题）交给 Codex
|
||||
↓
|
||||
Codex 从零开始读代码，独立形成判断
|
||||
↓
|
||||
输出验证报告，标注 同意/降级/升级/补充 发现
|
||||
```
|
||||
|
||||
### 阶段三：差异调和
|
||||
|
||||
```
|
||||
对比 Claude 和 Codex 的结论差异
|
||||
↓
|
||||
对分歧点进行针对性深入分析（读代码、跑测试）
|
||||
↓
|
||||
形成最终结论，更新文档
|
||||
```
|
||||
|
||||
### 流程图
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 用户提出任务 │
|
||||
└───────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌───────▼───────┐
|
||||
│ Claude 初步分析 │
|
||||
└───────┬───────┘
|
||||
│ 输出初步结论
|
||||
┌───────▼──────────┐
|
||||
│ Codex 独立验证 │ ← 不看 Claude 的结论，从零分析
|
||||
└───────┬──────────┘
|
||||
│ 输出验证报告
|
||||
┌───────▼──────────┐
|
||||
│ 差异对比与调和 │
|
||||
│ • 一致 → 确认 │
|
||||
│ • 分歧 → 深入 │
|
||||
└───────┬──────────┘
|
||||
│
|
||||
┌───────▼──────────┐
|
||||
│ 最终结论 + 实施 │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 适用场景
|
||||
|
||||
### 强烈推荐使用 Codex 验证的场景
|
||||
|
||||
1. **Feature flag 状态审计** — 判断一个 feature 是否真正可用，需要追踪 stub → 门控 → 运行时依赖的完整链路
|
||||
2. **API 协议兼容性** — beta header、请求参数、响应格式等涉及与上游 API 的契约
|
||||
3. **安全相关变更** — 权限模型、认证流程、输入验证
|
||||
4. **大范围重构评估** — 跨 10+ 文件的改动影响面分析
|
||||
|
||||
### 不需要 Codex 的场景
|
||||
|
||||
1. 单文件 bug 修复 — 上下文足够小，Claude 单独即可
|
||||
2. 新功能开发 — 不涉及逆向分析
|
||||
3. 文档更新 — 不需要代码验证
|
||||
4. UI 调整 — 可视化验证更有效
|
||||
|
||||
---
|
||||
|
||||
## 实际成果记录
|
||||
|
||||
### 案例 1: Feature Flags 审计（2026-04-05）
|
||||
|
||||
- **任务**: 验证 22 个标记为 COMPLETE 的 feature flag
|
||||
- **Claude 初步判断**: 22 个均为 COMPLETE
|
||||
- **Codex 验证结果**: 9 个被降级
|
||||
- `CONTEXT_COLLAPSE` — 后端全是 stub，`isContextCollapseEnabled()` 硬编码 `false`
|
||||
- `TEAMMEM` — 需要 GrowthBook `tengu_herring_clock` 门控
|
||||
- `CACHED_MICROCOMPACT` — `cachedMicrocompact.ts` 全 stub
|
||||
- 等（详见 `docs/features/feature-flags-codex-review.md`）
|
||||
- **影响**: 避免了在生产构建中启用实际不工作的功能
|
||||
|
||||
### 案例 2: Beta Header 空值问题（2026-04-15）
|
||||
|
||||
- **现象**: API 返回 400，`Unexpected value(s) `` for the 'anthropic-beta' header`
|
||||
- **Claude 追踪**: 定位到 `CACHE_EDITING_BETA_HEADER = ''` 和多个可能的注入点
|
||||
- **Codex 验证**: 确认根因是 `CACHED_MICROCOMPACT` 路径把空字符串推入 betas 数组，排除了 `CLI_INTERNAL_BETA_HEADER` 和 `AFK_MODE_BETA_HEADER`（它们有 truthy 保护）
|
||||
- **修复**: 3 处防御性过滤 + truthy 检查
|
||||
|
||||
### 案例 3: WebBrowserTool 收口（2026-04-15）
|
||||
|
||||
- **任务**: 判断 WebBrowserTool 是否可以从待办移除
|
||||
- **Claude 判断**: 测试全过，可以移除
|
||||
- **Codex 验证**: 指出面板 stub 未清理、schema 暴露了未实现的 action
|
||||
- **结论**: 删掉面板 stub，承认 browser-lite 不需要面板
|
||||
|
||||
---
|
||||
|
||||
## Codex 使用方式
|
||||
|
||||
### 本地 CLI 调用
|
||||
|
||||
```bash
|
||||
# 单文件分析
|
||||
codex -a full-auto "分析 src/constants/betas.ts 中所有可能产生空字符串的 beta header 常量"
|
||||
|
||||
# 跨文件追踪
|
||||
codex -a full-auto "追踪 CACHE_EDITING_BETA_HEADER 从定义到 API 请求的完整调用链，列出每个中间步骤"
|
||||
|
||||
# 审计型任务
|
||||
codex -a full-auto "审查 docs/features/feature-flags-audit-complete.md 中标记为 COMPLETE 的所有 flag，验证每个的真实状态"
|
||||
```
|
||||
|
||||
### 提示词模板
|
||||
|
||||
对于审计型任务，推荐以下结构：
|
||||
|
||||
```
|
||||
你是代码审查员，负责独立验证以下结论的正确性。
|
||||
|
||||
## 待验证的结论
|
||||
[粘贴 Claude 的分析结果]
|
||||
|
||||
## 你的任务
|
||||
1. 不要假设上述结论是正确的
|
||||
2. 从源码出发，独立追踪每个断言
|
||||
3. 对每个断言标注: ✅ 确认 / ❌ 反驳 / ⚠️ 补充
|
||||
4. 列出你发现的但上述结论遗漏的问题
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 局限性与注意事项
|
||||
|
||||
1. **Codex 也不是万能的** — 它同样可能遗漏复杂的运行时行为（如 memoize 缓存、异步时序）
|
||||
2. **Token 成本** — full-auto 模式的扫描通常消耗 200-300K tokens，需注意预算
|
||||
3. **不替代测试** — 静态分析能发现"代码写错了"，但不能发现"逻辑不符合预期"，仍需配合实际运行测试
|
||||
4. **结论时效性** — 代码在持续变化，Codex 的分析是时间快照，不能替代持续集成
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
在逆向工程场景下，**双模型交叉验证**（Claude + Codex）是我们验证代码理解正确性的核心方法论。它的价值不在于某一个模型更"聪明"，而在于**独立视角的碰撞消除了单一分析链条中的系统性偏差**。
|
||||
|
||||
这种方法已在本项目中多次验证有效，推荐在以下关键节点使用：
|
||||
- Feature flag 批量启用前
|
||||
- 重大重构提交前
|
||||
- API 协议变更时
|
||||
- 安全相关代码变更时
|
||||
Reference in New Issue
Block a user