<!-- 文档分类: MGMT-RPT-013 | 阶段: 项目管理 | 原路径: docs/指南/cc-对标-第六轮-2026-05-26.md -->
# KHY → Claude Code 对标第六轮：结构性修复报告 (2026-05-26)

## 1. 背景

- 用户评分基线：CC=100，KHY 从 10 → 15 → 25 → 30
- 核心诉求："给 KHY 一个编码任务，能像 CC 一样自主完成"
- 本轮方法：三路并行诊断（上下文管理 / 工具执行 / 系统提示词）+ 整合 Codex 外部评估

---

## 2. 诊断发现

### 2.1 提示词噪音（每次调用浪费 3000-5000 令牌）

| 问题 | 位置 | 浪费量 | 详情 |
|------|------|--------|------|
| claudeAdapter 注入 `<khy-agentic-guidance>` | claudeAdapter.js:368-392 | ~300 令牌 | 与系统提示词的 doingTasks/outputEfficiency/toneAndStyle 段高度重叠 |
| intentDirective 双重注入 | ai.js:3190 + claudeAdapter.js:386 | ~200 令牌 | 同一段 CODING_DIRECTIVE 出现两次 |
| `buildNaturalToolGuide` + `_toolCallingFallbackProfile` 双重工具列表 | khyUpgradeRuntime.js:1336 + prompts.js:402 | ~500-800 令牌 | hasNativeToolUse=false 时两处都注入 |
| selfProfile "I am"/"I cannot"/boundaries | selfProfile.js:364-377 | ~200-300 令牌 | CC 不注入自我描述，模型从工具定义中了解自身能力 |
| 每轮 `[任务指引]` 重复注入 | toolUseLoop.js:2902-2905 | ~150 令牌/轮 | 10 轮累计 1500 令牌，系统提示词已有足够指导 |
| snake_case/camelCase 重复工具定义 | toolCalling.js:2954 | ~1000 令牌 | `shell_command` 与 `shellCommand` 等 5 对重复 |
| 不可用工具混入定义 | toolCalling.js:2946 | ~1000-2000 令牌 | coordinator-only/no-git/no-PowerShell 工具白白占令牌 |

**CC 对比**：CC 的系统提示词约 3000-4000 令牌（不含动态段），KHY 约 4000-5500 令牌基础加大量冗余。CC 只有一层系统提示词段，不在适配器层额外注入。

### 2.2 输入破坏

| 问题 | 位置 | 具体后果 |
|------|------|---------|
| `inputPurify` 填充词剥离正则过于激进 | khyUpgradeRuntime.js:306-313 | `请` 匹配 "请求体"→"求体"；`一下` 匹配 "这一下午"→"这午"；`吧` 匹配 "网吧"→"网"；`呢` 匹配有意义上下文 |

**CC 对比**：CC 完全不做填充词剥离，信任模型能处理口语化输入。

### 2.3 上下文管理缺陷

| 问题 | 位置 | 后果 |
|------|------|------|
| 摘要输入硬截断 8000 字符 | contextCompressor.js:424 | 50K 令牌历史只有约 4% 被送给 AI 摘要，96% 信息丢失 |
| 摘要用 `effort: 'low'` | contextCompressor.js:435 | 低精度摘要遗漏关键细节 |
| 摘要消息标记不明确 | contextCompressor.js:457 | 模型可能将压缩摘要误认为用户消息 |
| HARD_FLOOR_TOKENS=32768 硬编码 | contextRouter.js:28 | 8K 上下文小模型永不触发压缩，直到 API 返回 413 |
| 多层压缩参数不协调 | pruneContext → guard → compressor | 各层独立判断保留比例，叠加可能只保留原始的 15% |
| 反抖动冷却期 30 秒 | contextCompressor.js:35-37 | 密集工具循环（每轮 < 30 秒）中上下文持续膨胀 |

**CC 对比**：CC 使用单一压缩入口，分段摘要（分块合并），硬底线与模型上下文窗口成比例。

### 2.4 适配器级联效率

| 问题 | 位置 | 后果 |
|------|------|------|
| 暂态错误不触发快速失败 | aiGateway.js:170-173 | rate_limit/timeout/network 后仍立即重试同一适配器，浪费 3-20 秒 |
| 拦截器只匹配 `chunk.tool` | ai.js:2102 | relayApiAdapter 用 `chunk.name`、kiroAdapter 用 `tool_use_end`，拦截器收不到 |

**已有机制**：系统已有快速失败 + 断路器 + 自愈探针 + Redis 持久化，但 `_shouldUseFastFail` 只覆盖 4 种永久性错误（auth/permission/unavailable/process），不覆盖暂态错误。

### 2.5 工具执行质量

| 问题 | 位置 | 后果 |
|------|------|------|
| 工具结果丢弃元数据 | toolUseLoop.js:2854 | 只取 output/content/result 文本，丢弃 truncated/totalLines/count/size |
| cronScheduler shell 硬超时 | cronScheduler.js:328 | `execSync` 180 秒墙钟超时，活跃进程被硬杀 |
| cronScheduler AI 硬超时 | cronScheduler.js:341 | `Promise.race` 180 秒，无活跃度感知 |

---

## 3. 已实施的修复（共 19 项）

### 3.1 提示词噪音清理

| 序号 | 修复内容 | 文件 | 效果 |
|------|----------|------|------|
| 1 | 移除 `<khy-agentic-guidance>` 代码块，保留问候检测 | claudeAdapter.js | 节省约 300 令牌 + 消除指令冲突 |
| 2 | 移除 `buildNaturalToolGuide` 重复注入 | khyUpgradeRuntime.js:1336 | 节省约 500-800 令牌 |
| 3 | selfProfile 精简到仅保留适配器/模型信息 | selfProfile.js:357-380 | 从约 200 令牌降到约 30 令牌 |
| 4 | 移除每轮 `[任务指引]` 注入 | toolUseLoop.js:2902-2905 | 节省约 150 令牌/轮 |
| 5 | 工具定义用 `getEnabledDefinitions()` 过滤不可用工具 | toolCalling.js:2946 | 节省约 1000-2000 令牌 |
| 6 | snake_case/camelCase 标准化去重 | toolCalling.js:2954 | 节省约 1000 令牌 |

### 3.2 输入与上下文

| 序号 | 修复内容 | 文件 | 效果 |
|------|----------|------|------|
| 7 | 云端模型跳过填充词剥离 | khyUpgradeRuntime.js:299 + ai.js:3102 | 防止"请求"→"求"等破坏 |
| 8 | 摘要分段提取（12K×4 块 + 关键点提取） | contextCompressor.js:421-455 | 覆盖率从约 4% 提升到约 50%+ |
| 9 | 摘要精度从 low 提升到 medium | contextCompressor.js:435 | 更准确的摘要 |
| 10 | 摘要消息用 `<compressed_context>` 标记 | contextCompressor.js:457 | 模型明确知道是压缩上下文 |
| 11 | HARD_FLOOR 动态化 `min(32768, budget*0.15)` | contextRouter.js:28-32 | 小模型正确触发压缩 |

### 3.3 适配器与工具执行

| 序号 | 修复内容 | 文件 | 效果 |
|------|----------|------|------|
| 12 | 暂态错误冷却期（rate_limit 20 秒 / timeout 10 秒 / network 12 秒） | aiGateway.js:170-185 | 减少盲探测延迟 |
| 13 | 拦截器兼容 `chunk.tool || chunk.name` + `tool_use_end` | ai.js:2102-2115 | 所有适配器的工具使用块都能被收集 |
| 14 | 工具结果附加元数据 `[Metadata: truncated, N lines, ...]` | toolUseLoop.js:2873-2879 | 模型知道搜索是否截断 |

### 3.4 超时与杂项

| 序号 | 修复内容 | 文件 | 效果 |
|------|----------|------|------|
| 15 | cronScheduler shell 改用 spawn + 空闲计时器 | cronScheduler.js:324-349 | 活跃进程不再被硬杀 |
| 16 | cronScheduler 默认超时 180 秒 → 300 秒 | cronScheduler.js:23 | AI 原子调用有更多时间 |
| 17 | liteRepl 传递 `chatOpts: {}` 到 toolUseLoop | liteRepl.js:3358 | 行为与 repl 一致 |
| 18 | 清理死代码：`_fallbackContextSummary` 的 `[意图]/[问题]` 解析 | khyUpgradeRuntime.js:348-386 | 移除不再匹配的正则 |
| 19 | 清理死代码：claudeAdapter 的 `[意图]/[问题]` 剥离 | claudeAdapter.js:321-323 | 移除遗留清理逻辑 |

---

## 4. Codex 外部评估的批判性分析

Codex 以 15/100 评估 KHY，给出 5 项 P0 建议。

### 评估视角错位

Codex 把 KHY 当作通用命令行产品评估（命令数量、入口统一、文档版本），而非 AI 编码助手。用户的核心诉求是"AI 编码任务交付质量"，这和"110 个命令认知负担高"完全不是一个维度。CC 本身也有 100+ 功能点。

### P0 建议逐条评估

| Codex P0 建议 | 对 AI 编码质量的实际影响 | 是否采纳 |
|---------------|----------------------|----------|
| 模式化命令视图 `khy code/quant/ops` | 接近零 — AI 不通过命令菜单工作 | 否 |
| 未闭环能力下线 | 低 — 除非工具定义干扰 AI 选择 | 部分（已通过 isEnabled 过滤） |
| 统一入口策略 | 零 — 不影响 AI 执行链路 | 否 |
| AI 路由优化/冷却期 | **中高** — 减少无效探测等待 | **是**（已实施暂态冷却） |
| 统一超时模型 | **中高** — 活跃任务不被硬杀 | **是**（已实施活跃度感知） |

### Codex 完全没诊断到的核心差距

- 内容块格式（Anthropic 原生 tool_result 对比纯文本）
- 提示词噪音/重复注入（`<khy-agentic-guidance>` + 双重工具列表 + 双重指令）
- `inputPurify` 破坏用户输入
- 摘要 8K 字符截断丢失 96% 信息
- 工具结果元数据丢失
- 拦截器块收集格式不匹配

---

## 5. 适配器级联与冷却机制架构

### 四层防护

```
请求进入 → 快速失败检查 → 暂态冷却检查 → 速率限制 → 实际调用
                ↓                  ↓              ↓           ↓
         auth/perm/unavail    rate_limit/     分布式限流    adapter.generate()
         → 30 秒跳过          timeout/network  + 指数退避        ↓
                              → 10-20 秒跳过                 成功 → 清除错误
                                                            失败 → 记录 + 可能触发断路器
                                                                     ↓
                                                              连续 ≥3 次 → 断路器开
                                                              → 指数冷却（上限 5 分钟）
                                                              → 中间点自愈探针
```

### 暂态冷却参数（新增）

| 错误类型 | 冷却时间 | 环境变量覆盖 |
|---------|---------|------------|
| rate_limit | 20 秒 | `GATEWAY_RATE_LIMIT_COOLDOWN_MS` |
| overloaded | 15 秒 | `GATEWAY_OVERLOADED_COOLDOWN_MS` |
| timeout | 10 秒 | `GATEWAY_TIMEOUT_COOLDOWN_MS` |
| network | 12 秒 | `GATEWAY_NETWORK_COOLDOWN_MS` |

---

## 6. 上下文管理架构参考

### 五层架构

| 层 | 文件 | 职责 |
|----|------|------|
| 路由决策 | contextRouter.js | 4 路由策略选择 |
| 压缩引擎 | contextCompressor.js | AI 摘要 + 增量更新 + 循环边界 |
| 压缩管线 | compactPipeline.js | 5 阶段渐进压缩 |
| 滑动窗口 | khyUpgradeRuntime.js:buildSlidingWindow | 集成调度 |
| 工具截断 | smartTruncation.js | 按工具类型噪声过滤 |

### 关键设计原则

1. **硬底线必须与模型上下文窗口成比例** — `min(默认值, budget * 0.15)`
2. **摘要不能暴力截断** — 应分段提取关键点（文件路径、工具调用、错误信息）
3. **摘要消息必须有明确标记** — `<compressed_context>` 让模型知道这不是用户输入
4. **摘要精度不应低于 medium** — low 精度会遗漏关键细节

---

## 7. 设计原则总结

### "信任模型而非教模型"

| CC 做法 | KHY 过去做法 | KHY 现在做法 |
|---------|------------|------------|
| 单层系统提示词 | 三层（系统 + 适配器 + 指令） | 单层系统提示词 |
| 依赖工具定义自描述 | 提示词内教工具格式 | 原生时跳过，非原生只在一处教 |
| 不做填充词剥离 | 激进正则破坏内容 | 云端模型直通 |
| 不注入自我描述 | "I am"/"I cannot"/boundaries | 仅保留适配器/模型信息 |
| 不在每轮注入行为指导 | `[任务指引]` 每轮注入 | 移除，依赖系统提示词 |

### 单一职责原则

- 行为指令只在系统提示词段中出现，不在适配器层重复
- 环境信息只在 `getEnvironmentSection()` 出现，不在 selfProfile 重复
- 工具格式教学只在 `_toolCallingFallbackProfile` 出现，不在 `buildNaturalToolGuide` 重复

---

## 8. 剩余待做

### P0（直接影响 AI 质量）

- [ ] 增量摘要新增内容截断 6000 字符（contextCompressor.js:584）需扩大
- [ ] 循环边界延续预算从 1500 令牌提升到 4000-6000
- [ ] MODEL_CAPABILITIES 表过时（ai.js:259-271），缺少 Claude 3.5 Haiku、GPT-4.1、Gemini 2.5 Pro 等

### P1（稳健性）

- [ ] 类别 B 外部依赖工具添加 `isEnabled()` 守卫（strategyList/backtest/pdfToWord/imageOcr 等约 10 个）
- [ ] 多层压缩参数协调 — 避免 pruneContext → guard → compressor 叠加过度压缩
- [ ] smartTruncation 的缩放系数改为非线性（当前线性对小模型过于激进）

### P2（代码质量）

- [ ] `tools/lsp.js` 6 个孤立工具定义是死代码，可删除
- [ ] BUILTIN_TOOLS 中已有注册表对应版本的工具应迁移清理
