<!-- 文档分类: MGMT-PLAN-005 | 阶段: 项目管理 | 原路径: docs/指南/自主生产计划-r2-2026-05-24.md -->
# KHY 自主生产能力提升计划 (Round 2)

> 日期: 2026-05-24
> 参考项目: Hermes Agent / Claude Code / DeepSeek-TUI
> 前序: Round 1 已完成 11 项管道阻塞+可靠性修复 (见 THREE_PROJECT_IMPROVEMENT_PLAN_2026-05-24.md)
> 本轮聚焦: **项目独自生产能力** — 会话持久化、任务自主分解、自验证、记忆系统、错误自愈、安全沙箱、可观测性

---

## 一、十维能力现状评分

| # | 维度 | KHY 现状 | Claude Code | Hermes Agent | DeepSeek-TUI | 差距优先级 |
|---|------|---------|-------------|--------------|-------------|-----------|
| D1 | 会话持久化 | JSON 文件+原子写 (5/10) | JSONL+parentUuid (8/10) | SQLite WAL+FTS5 (9/10) | Actor+原子写 (7/10) | **P0** |
| D2 | 任务自主分解 | taskBoard+workerAgent (6/10) | Coordinator+Fork (8/10) | Kanban+CAS (9/10) | — | **P0** |
| D3 | 自验证 | verificationAgent+deliveryGate (7/10) | 对抗性 Agent+VERDICT (9/10) | 幻觉门+诊断 (8/10) | CI Gate (7/10) | **P1** |
| D4 | 记忆系统 | RAG+知识教学 (6/10) | CLAUDE.md+compact (7/10) | 插件化 Provider (8/10) | BM25 归档 (6/10) | **P1** |
| D5 | 错误自愈 | retryByErrorKind (7/10) | — | 结构化信封+恢复提示 (9/10) | 分层错误 (7/10) | **P1** |
| D6 | 安全沙箱 | bwrap (仅Linux) (5/10) | Seatbelt+bubblewrap (8/10) | — | 三平台 (9/10) | **P2** |
| D7 | 可观测性 | telemetryService (5/10) | GrowthBook (7/10) | — | 三源 Rollup (8/10) | **P2** |
| D8 | 配置自调优 | systemSetting (5/10) | FastMode 状态机 (8/10) | — | 智能终端检测 (8/10) | **P2** |
| D9 | 输出质量 | acceptanceCriteria (7/10) | 流式清洗+结构化 (8/10) | 上下文围栏 (8/10) | — | P3 |
| D10 | 多代理协调 | workerAgent mailbox (7/10) | Fork+Coordinator (9/10) | MoA 聚合 (7/10) | 七角色 (7/10) | P3 |

---

## 二、P0 改进项 (管道核心能力)

### P0-1: 会话持久化升级 — JSONL + parentUuid 链 + FTS5 搜索

**借鉴**: Claude Code JSONL transcript + Hermes SQLite WAL/FTS5 + DeepSeek-TUI 原子写
**痛点**: 当前 JSON 文件级存储无增量追加、无搜索索引、崩溃恢复弱

**方案**:
- 修改 `backend/src/services/sessionPersistence.js`:
  - 底层从 JSON 切换为 **append-only JSONL**，每条消息带 `uuid` + `parentUuid` (~60行)
  - 崩溃恢复: 从 JSONL 最后一行反向遍历重建对话链 (~30行)
  - 保留原子写检查点作为快照备份 (~10行)
- 修改 `backend/src/services/sessionSearchIndex.js`:
  - 增加 **SQLite FTS5 索引**，中文 trigram 分词 (~80行)
  - 写入时同步更新 FTS5 表 (~20行)
  - 搜索接口: `searchSessions(query, {limit, since})` (~30行)
- 预计 ~230行

### P0-2: 任务自主分解 — Kanban 状态机 + CAS 认领 + 子任务链

**借鉴**: Hermes Agent Kanban CAS + Claude Code Coordinator 模式
**痛点**: taskBoard 文件锁不可靠，缺少子任务链和自动状态流转

**方案**:
- 修改 `backend/src/coordinator/taskBoard.js`:
  - 底层从文件切换为 SQLite (复用 sessionSearchIndex 的 DB) (~40行)
  - `claimTask()` 使用 `BEGIN IMMEDIATE + WHERE status='ready' AND claim_lock IS NULL` 实现 CAS (~30行)
  - 状态机: `triage → todo → ready → running → blocked/done → archived` (~20行)
  - 子任务链: `parent_id` 字段 + 依赖完成检查 (~25行)
- 修改 `backend/src/coordinator/workerAgent.js`:
  - `completeTask()` 增加子任务验证门: 验证报告的子卡片是否真实存在 (~30行)
  - 连续失败检测: `consecutive_failures >= max_retries` → dead_letter (~15行)
- 预计 ~160行

### P0-3: 结构化错误信封 + 恢复提示

**借鉴**: Hermes Agent ClassifiedError + FailoverReason 18种分类
**痛点**: `retryByErrorKind` 只返回分类字符串，调用方需自行决定恢复策略

**方案**:
- 修改 `backend/src/services/retryWithBackoff.js`:
  - 新增 `ClassifiedError` 类: `{ reason, retryable, shouldCompress, shouldRotateCredential, shouldFallback, retryAfter, detail }` (~40行)
  - `classifyError()` 返回 `ClassifiedError` 实例而非字符串 (~30行更新)
  - 新增 `FailoverReason` 枚举 (18种，含 `AUTH_PERMANENT/BILLING/IMAGE_TOO_LARGE/THINKING_SIGNATURE` 等) (~25行)
- 修改 `backend/src/services/gateway/aiGateway.js`:
  - `generate()` 错误处理路径使用 `ClassifiedError` 自动执行恢复:
    - `shouldCompress` → 触发 ReactiveCompact
    - `shouldRotateCredential` → 调用 keySelector 切换凭证
    - `shouldFallback` → 尝试 fallback model (~40行)
- 预计 ~135行

---

## 三、P1 改进项 (质量与韧性)

### P1-1: 对抗性验证 Agent — VERDICT 协议

**借鉴**: Claude Code Verification Agent (read-only + disallowedTools + VERDICT)
**痛点**: verificationAgent 只跑静态 lint/test，不尝试破坏实现

**方案**:
- 修改 `backend/src/services/verificationAgent.js`:
  - 新增 `adversarialVerify()` 模式: 使用 AI 审查变更，尝试找边界用例 (~80行)
  - VERDICT 协议: `VERDICT: PASS | FAIL | PARTIAL` 结构化输出解析 (~20行)
  - 工具白名单: 只允许 read_file/grep/glob/shell(只读命令)，禁止写入工具 (~15行)
- 修改 `backend/src/services/deliveryGate.js`:
  - `evaluateDelivery()` 增加可选 adversarial 阶段 (~20行)
  - 自动重试: FAIL → 生成修复 prompt → 重跑 → 再验证 (最多2轮) (~30行)
- 预计 ~165行

### P1-2: 记忆系统 — 可插拔 Provider + 上下文围栏

**借鉴**: Hermes Agent MemoryProvider ABC + StreamingContextScrubber
**痛点**: RAG 直接注入 prompt，无围栏标记；无法扩展外部记忆后端

**方案**:
- 新建 `backend/src/services/memoryProvider.js` (~120行):
  - `MemoryProvider` 基类: `initialize/prefetch/syncTurn/shutdown` 生命周期
  - `BuiltinProvider`: 封装现有 ragRetrievalService (~30行)
  - `MemoryManager`: 内建 + 最多1个外部 provider (~40行)
  - `buildMemoryContextBlock()`: `<memory-context>` XML 围栏 (~15行)
  - 流式清洗: 状态机过滤跨 chunk 的围栏标签 (~35行)
- 修改 `backend/src/services/toolUseLoop.js`:
  - system prompt 组装时调用 `memoryManager.buildMemoryContextBlock()` (~10行)
- 预计 ~130行

### P1-3: 幻觉检测门 — 任务+文件双重验证

**借鉴**: Hermes Agent `_verify_created_cards` + `_scan_prose_for_phantom_ids`
**痛点**: worker 报告完成但实际未创建文件/子任务

**方案**:
- 修改 `backend/src/coordinator/workerAgent.js`:
  - `completeTask()` 增加文件存在性验证: 扫描 output 中引用的路径 (~30行)
  - phantom ID 扫描: 正则匹配 `task_xxxx` 格式，验证是否存在 (~20行)
  - 验证失败 → 任务保持 running + 注入修复提示 (~15行)
- 修改 `backend/src/services/deliveryGate.js`:
  - `evaluateDelivery()` 增加幻觉文件检测 (~20行)
- 预计 ~85行

---

## 四、P2 改进项 (平台能力)

### P2-1: 跨平台安全沙箱 — macOS Seatbelt + Windows Job Object

**借鉴**: DeepSeek-TUI 三平台沙箱 + Claude Code Seatbelt 策略
**痛点**: bwrap 沙箱仅 Linux 可用，macOS/Windows 无 OS 级隔离

**方案**:
- 修改 `backend/src/services/toolSandbox.js`:
  - macOS: 动态生成 SBPL 策略 + `sandbox-exec` 执行 (~80行)
  - Windows: Job Object 限制 (通过 PowerShell `New-ProcessJob`) (~50行)
  - 统一 `SandboxManager.prepare()` 接口，按平台自动选择 backend (~30行)
- 预计 ~160行

### P2-2: 三源可观测 Rollup — 审计+会话+运行时

**借鉴**: DeepSeek-TUI `metrics.rs` 三源聚合
**痛点**: telemetryService 只有内存计数器，缺离线分析

**方案**:
- 修改 `backend/src/services/telemetryService.js`:
  - 审计日志: append-only JSONL (`~/.khyquant/audit.log`) (~30行)
  - 三源 Rollup: audit + session + runtime 聚合到统一指标 (~60行)
  - Per-tool stats: 调用数/成功率/P50/P95 延迟 (~40行)
  - `khy metrics` CLI 子命令 + `--since 7d` 时间过滤 (~30行)
- 预计 ~160行

### P2-3: 配置自调优 — FastMode 状态机 + 智能终端检测

**借鉴**: Claude Code FastMode + DeepSeek-TUI `apply_env_overrides()`
**痛点**: 无自适应降级，终端能力不检测

**方案**:
- 新建 `backend/src/services/adaptiveConfig.js` (~120行):
  - FastMode 状态机: `active → cooldown(rate_limit|overloaded) → active` (~40行)
  - 智能终端检测: TERM_PROGRAM/SSH_CLIENT/ConHost → 自动降级动画/颜色 (~40行)
  - 环境信号优先级: env > terminal detection > 用户设置 > 默认值 (~25行)
  - `getEffectiveConfig()` 合并所有层级返回最终配置 (~15行)
- 修改 `backend/src/services/gateway/aiGateway.js`:
  - rate_limit/overloaded 错误触发 FastMode cooldown (~15行)
- 预计 ~135行

---

## 五、文件影响矩阵

| 文件 | 改动项 | 预计行数 | 新/改 |
|------|--------|---------|------|
| `backend/src/services/sessionPersistence.js` | P0-1 | ~100 | 改 |
| `backend/src/services/sessionSearchIndex.js` | P0-1 | ~130 | 改 |
| `backend/src/coordinator/taskBoard.js` | P0-2 | ~115 | 改 |
| `backend/src/coordinator/workerAgent.js` | P0-2, P1-3 | ~110 | 改 |
| `backend/src/services/retryWithBackoff.js` | P0-3 | ~95 | 改 |
| `backend/src/services/gateway/aiGateway.js` | P0-3, P2-3 | ~55 | 改 |
| `backend/src/services/verificationAgent.js` | P1-1 | ~115 | 改 |
| `backend/src/services/deliveryGate.js` | P1-1, P1-3 | ~70 | 改 |
| `backend/src/services/memoryProvider.js` | P1-2 | ~120 | **新** |
| `backend/src/services/toolUseLoop.js` | P1-2 | ~10 | 改 |
| `backend/src/services/toolSandbox.js` | P2-1 | ~160 | 改 |
| `backend/src/services/telemetryService.js` | P2-2 | ~160 | 改 |
| `backend/src/services/adaptiveConfig.js` | P2-3 | ~120 | **新** |

**总计**: ~1360行 (新建 2 文件, 修改 11 文件)

---

## 六、实施顺序

```
Phase 1 (P0): 管道核心
  ├── P0-1: JSONL 持久化 + FTS5 搜索
  ├── P0-2: Kanban SQLite + CAS 认领
  └── P0-3: 结构化错误信封

Phase 2 (P1): 质量韧性
  ├── P1-1: 对抗性验证 Agent
  ├── P1-2: 可插拔记忆 Provider
  └── P1-3: 幻觉检测门

Phase 3 (P2): 平台能力
  ├── P2-1: 跨平台沙箱
  ├── P2-2: 三源 Rollup
  └── P2-3: 配置自调优
```

## 七、验证策略

每项改动完成后:
1. `node -c` 语法检查所有修改文件
2. 相关测试文件 `npx jest --forceExit`
3. Phase 结束后全量回归 `npx jest backend/tests/ --forceExit`

---

## 八、KHY 独有优势 (保持不动)

以下能力三大参考项目均不具备，应作为差异化保留:
- `acceptanceCriteria.js` — 机器可读验收标准
- `deliveryGate.js` — 后循环交付验证门
- `knowledgeTeachingService.js` — 知识教学+XP 等级系统
- `selfProfile.js` — 自我画像三重输出
- `workerAgent.js` mailbox — ACK 消息队列
- `canonicalState.js` — 六维规范状态快照

---

## 九、实施完成记录

> Round 2 全部 9 项已于 **2026-05-24** 完成实施。

| # | 改进项 | 优先级 | 状态 | 修改/新建文件 |
|---|--------|--------|------|---------------|
| P0-1 | JSONL 持久化 + FTS5 搜索 | P0 | **完成** | sessionPersistence.js, sessionSearchIndex.js |
| P0-2 | Kanban SQLite + CAS 认领 | P0 | **完成** | taskBoard.js (重写) |
| P0-3 | 结构化错误信封 + 恢复提示 | P0 | **完成** | retryWithBackoff.js |
| P1-1 | 对抗性验证 Agent + VERDICT | P1 | **完成** | verificationAgent.js, deliveryGate.js |
| P1-2 | 可插拔记忆 Provider + 上下文围栏 | P1 | **完成** | memoryProvider.js (新建) |
| P1-3 | 幻觉检测门 | P1 | **完成** | workerAgent.js |
| P2-1 | 跨平台安全沙箱 | P2 | **完成** | toolSandbox.js |
| P2-2 | 三源可观测 Rollup | P2 | **完成** | telemetryService.js |
| P2-3 | 配置自调优 FastMode | P2 | **完成** | adaptiveConfig.js (新建), aiGateway.js |

**全量语法检查**: 12 文件均通过 `node -c`。
