<!-- 文档分类: MGMT-PLAN-004 | 阶段: 项目管理 | 原路径: docs/指南/三项目改进计划-2026-05-24.md -->
# KHY 三项目取长补短深度分析

> 日期: 2026-05-24
> 参考项目: Hermes Agent (Python) / Claude Code (TypeScript) / DeepSeek-TUI (Rust)

## 一、三项目核心架构对比

| 维度 | Hermes Agent | Claude Code | DeepSeek-TUI | KHY 现状 |
|------|-------------|-------------|-------------|---------|
| 语言 | Python ~170万行 | TypeScript/Bun ~1987文件 | Rust 15 crate | Node.js |
| 流式管道 | 队列桥接 + 同步→异步 | AsyncGenerator 链 | Op/Event 双向 channel | SSE + onChunk 回调 |
| 背压 | 自适应速率 + 洪水控制 | AsyncGenerator 隐式 | 8MB 高水位 + 双速 | **无** |
| 工具并发 | ThreadPoolExecutor | StreamingToolExecutor | FuturesUnordered + RwLock | 串行执行 |
| 循环护栏 | ToolCallGuardrail 分级 | siblingAbortController | LoopGuard hash 去重 | toolLoopDetector 8检测器 |
| 上下文压缩 | 可插拔引擎 + 图像感知 | 5层渐进 + ReactiveCompact | CycleManager + SeamManager | 3层 + taskSnapshot |
| 错误重试 | 分类器+抖动退避+凭证轮换 | withRetry AsyncGen+fallback | 错误分类+Token Bucket | retryWithBackoff 简单 |
| 凭证管理 | 多策略池(4种)+冷却时间 | 多层权限+分类器预热 | API Key 直配 | round-robin 仅 |
| 取消机制 | interrupt_requested 标志 | parent→sibling→child 3层 | CancellationToken+原因 | 单一 AbortController |
| 会话持久化 | SQLite WAL + FTS5双索引 | JSONL transcript | Actor(latest-wins)合并 | sessionPersistence.js |
| 钩子系统 | 3层(网关+插件+Shell) | 完整生命周期20+事件 | 无(配置驱动) | hookSystem.js 基础 |
| MCP | 动态工具注册+generation | 官方SDK 6种传输 | McpPool 管理多server | mcpClient.js 基础 |

## 二、各项目独特优势

### Hermes Agent 独有
1. **AST 静态分析工具发现** — `ast.parse` 检查是否包含 `registry.register()` 再导入
2. **消息序列自修复** — 每次 API 调用前修复角色交替/孤立工具结果
3. **双 FTS5 索引** — unicode61 + trigram 覆盖 CJK 子串搜索
4. **凭证池 4 策略** — fill_first / round_robin / random / least_used
5. **stale-call 检测器** — 后台线程运行 API 调用，主循环轮询超时终止
6. **子代理深度控制** — max_spawn_depth + 角色系统 (leaf/orchestrator)
7. **流式上下文清洗器** — 状态机过滤跨 chunk 的 `<memory-context>` 标签
8. **迭代预算退还** — execute_code 不计入预算 + 耗尽后一次 grace call

### Claude Code 独有
1. **StreamingToolExecutor** — 边流式边执行，不等 API 完成
2. **5 层渐进压缩** — toolResultBudget → snip → micro → collapse → auto
3. **ReactiveCompact** — API 返回 prompt_too_long 紧急压缩重试
4. **Content Replacement Budget** — 大结果持久化磁盘，API 只看预览
5. **Tombstone Protocol** — fallback 清理无效 thinking signatures
6. **Speculative Classifier Pre-warming** — 权限分类器并行预热
7. **Feature Gate Dead Code Elimination** — bundle-time 功能门控
8. **Max Output Tokens Recovery** — 从 8k 自动升级 64k 续写

### DeepSeek-TUI 独有
1. **Op/Event 双向 channel** — UI 和 Engine 完全解耦
2. **自适应分块策略** — Smooth/CatchUp 双速 + 滞环切换
3. **Cycle Manager** — 检查点-重启替代压缩（避免 Frankenstein 上下文）
4. **Seam Manager** — append-only 分层上下文（不破坏 prefix cache）
5. **前缀缓存三区域** — 不可变前缀 / 追加历史 / 最新用户消息
6. **InteractiveTerminalGuard** — RAII 终端状态管理 (future 取消不泄漏)
7. **Persistence Actor** — 异步持久化 + latest-wins 请求合并
8. **Fake Tool Wrapper 检测** — 过滤模型文本中伪造的工具调用标记

## 三、KHY 11 项改进计划

### P0 — 管道阻塞与核心可靠性
| # | 改进项 | 借鉴 | 核心文件 | 行数 |
|---|--------|------|---------|------|
| 1 | SSE 流式背压机制 | DeepSeek-TUI | sseBackpressure.js(新), sseKeepalive.js | ~240 |
| 2 | Stale Call 检测终止 | Hermes Agent | aiGateway.js, fetchTimeout.js | ~100 |
| 3 | ToolCallGuardrail 防循环 | Hermes Agent | toolGuards.js, toolUseLoop.js | ~190 |

### P1 — 性能与可靠性增强
| # | 改进项 | 借鉴 | 核心文件 | 行数 |
|---|--------|------|---------|------|
| 4 | 五层渐进压缩管道 | Claude Code | compactPipeline.js, queryEngine.js | ~200 |
| 5 | 凭证池多策略+故障转移 | Hermes Agent | apiKeyPool.js, keySelector.js | ~170 |
| 6 | 双层 AbortController 级联 | Claude Code | toolUseLoop.js, streamingToolExecutor.js | ~95 |
| 7 | 消息序列自修复 | Hermes Agent | transcriptRepair.js | ~80 |
| 8 | 错误分类差异化重试 | Claude+Hermes | retryWithBackoff.js, aiGateway.js | ~110 |

### P2 — 增强功能
| # | 改进项 | 借鉴 | 核心文件 | 行数 |
|---|--------|------|---------|------|
| 9 | 大工具结果磁盘持久化 | Claude Code | toolUseLoop.js, cleanupService.js | ~75 |
| 10 | 流式工具执行前置启动 | Claude Code | toolUseLoop.js, streamingToolExecutor.js | ~120 |
| 11 | Fake Tool Wrapper 检测 | DeepSeek-TUI | toolUseLoop.js | ~60 |

**总计**: ~1470 行改动，新建 1 文件，修改 16 文件

### 实施路线
- **Phase 1** (P0): #1-#3 → 消除管道阻塞和工具死循环
- **Phase 2** (P1): #4-#8 → 压缩增强+凭证管理+取消机制+自修复+重试
- **Phase 3** (P2): #9-#11 → 大结果持久化+流式预执行+伪造检测

## 四、架构设计模式借鉴清单

| 模式 | 来源 | 应用点 |
|------|------|--------|
| 队列桥接(sync→async) | Hermes | sseBackpressure.js |
| 滞环切换(hysteresis) | DeepSeek | lineBuffer.js 帧率控制 |
| 幂等/变更区分 | Hermes | toolGuards.js 循环检测 |
| 分级响应(warn→critical→block) | Hermes | toolCallGuardrail |
| 渐进压缩(多层由轻到重) | Claude Code | compactPipeline.js |
| fill_first 策略 | Hermes | keySelector.js |
| parent→sibling→child 取消 | Claude Code | toolUseLoop.js |
| 角色交替自修复 | Hermes | transcriptRepair.js |
| 错误分类→策略映射 | Claude+Hermes | retryWithBackoff.js |
| Content Replacement Budget | Claude Code | toolUseLoop.js 大结果 |
| 增量解析+预执行 | Claude Code | StreamingToolExecutor |
| Marker 状态机过滤 | DeepSeek | _parseToolCalls() |
