# 记忆系统 Harness Engineering 体系

> **核心公式**：Agent = Model + Harness
> 本记忆系统即为 AI IDE Agent 的 Harness（驾驭系统），通过约束机制、反馈回路、控制平面三大支柱，确保 AI 行为可控、可预测、可优化。
>
> ⚠️ **本文件为架构设计文档**，AI 日常操作所需的内容（约束分类、职责边界、使用流程、维护指南、冲突解决）已融合进 [SKILL.md](./SKILL.md)。本文件仅作为设计参考保留。

---

## 一、三大支柱映射

### 1.1 约束机制（Constraints）

**三级权重体系**（数字越大优先级越高）：

```
L3 本地私有配置 (权重:100) ← 最高优先级，覆盖所有下层
    ↓ 覆盖
L2 仓库共享配置 (权重:75)  ← 项目级技术事实
    ↓ 覆盖
L1 公司统一配置 (权重:25)  ← 安全红线（只读不可覆盖）+ 技术规范 + 语言约束
```

**约束分类**：

| 类别 | 示例 | 层级 |
|---|---|---|
| 安全红线 | 禁止硬编码密钥、SQL注入防护 | L1（只读） |
| 编码底线 | 命名自解释、单一职责、DRY | L1 |
| 技术选型原则 | 活跃维护、社区规模、安全记录 | L1 |
| 技术栈偏好 | React/Vue 选择、工具链配置 | L1 |
| 项目事实 | Java 17 + Vue 3 + Spring Cloud | L2 |
| 语言详细规范 | Java 命名约定、Vue2/Vue3 组件模板、Tofly 约束 | L1 language/*/ |
| 本地环境 | 端口配置、调试习惯、注释偏好 | L3 |

### 1.2 反馈回路（Feedback Loops）

**已实现**：
- ✅ **权重覆盖机制**：冲突时自动选择高优先级规则
- ✅ **动态路由加载**：按任务类型精确加载配置片段，避免全量加载
- ✅ **质量门禁**：前端改动自动运行 `lint` + `typecheck`，后端运行 `compile`
- ✅ **环境变量超权**：权重 150，运行时可覆盖所有配置
- ✅ **命令行参数超权**：权重 200，最高优先级临时覆盖
- ✅ **用户习惯记录**：L3 §五 持续学习和更新

**待强化**：
- ⚠️ Agent 自我反思机制（任务完成后的自检清单）
- ⚠️ 决策追溯日志（记录关键决策点和理由）
- ⚠️ 配置漂移检测（对比 memory_bak 与当前差异）

### 1.3 控制平面（Control Plane）

| 控制维度 | 实现方式 | 位置 |
|---|---|---|
| 任务调度 | TodoWrite 工具 | 入口文件 §1.1 |
| 权限控制 | 禁止行为清单 | L1 安全红线 + L3 工作规范 |
| 行为边界 | 浏览器规则、文档创建限制 | L3 §一 |
| 交互协议 | AskUserQuestion（歧义必问） | L1 §五 + 入口文件 §1.3 |
| 环境感知 | 项目结构/依赖自动检测 | L2 §一 + §二 |
| 输出质量 | 语言/风格/格式规范 | L1 §五 + L3 §一 |
| 习惯记忆 | 用户习惯记录（持续学习） | L3 §五 |

---

## 二、渐进式披露架构

```
Layer 0: 入口导航（始终加载 ~70 行）
└── configure_entrance.md
    ├── Tier 0: 底线规则（内联，无需额外加载）
    └── Tier 1+: 动态路由表（按需加载）

Layer 1: 全局基线（进入项目时按需加载）
├── L1 公司统一配置（安全红线 + 技术选型 + 编码底线 + 沟通 AI 行为）
└── L1+ language/（各语言详细约束，按语言动态加载）
    ├── language/java.md  （Java / Spring Boot / Tofly）
    ├── language/vue2.md  （Tofly Vue2）
    ├── language/vue3.md  （Vue 3 + Vben Admin 5.0）
    ├── language/vben2.md （Vben Admin v2 CRUD 页面生成）
    └── language/python.md（Python）

Layer 2: 项目上下文（任务触发时按需加载）
└── L2 仓库共享配置（项目技术栈 + 架构约定 + 构建命令 + Git 补充 + 测试）

Layer 3: 环境细节（当前工作时按需加载）
└── L3 本地私有配置（行为规范 + 浏览器规则 + 本地环境 + 个人习惯 + 用户习惯记录）
```

**Token 消耗对比**：
- 原方案（4层全量加载）：~945 行
- 新方案（纯问答）：~70 行（节省 93%）
- 新方案（写代码）：~200-210 行（节省 78%）

---

## 三、动态路由机制

### 3.1 路由决策流程

```
用户提问
  │
  ├─→ 判断任务类型（可多选）
  │     ├─ 【代码编写】→ 按语言加载 L2 §一 + language/xxx.md
  │     ├─ 【技术选型】→ L1 §二 + L2 §二
  │     ├─ 【Git 操作】→ L1 §四 + L2 §四
  │     ├─ 【调试排错】→ L3 §二
  │     ├─ 【构建运行】→ L3 §四
  │     ├─ 【测试】→ L2 §五
  │     └─ 【纯问答】→ 无需额外加载 ✅
  │
  └─→ 使用 Read 工具精确读取指定章节
```

### 3.2 语言检测优先级

```
用户明确提到 > 文件扩展名 > 项目上下文 > 默认主栈(Java+Vue)
```

### 3.3 用户习惯记录

**位置**：[L3 §五](./local_private_config.md#L129-L172)

**触发条件**：
- 每次对话开始时自动读取
- 用户说"记住这个""以后都这样"时更新
- 用户纠正 AI 行为时更新

**记录分类**：

| 分类 | 内容 | 示例 |
|---|---|---|
| 编码习惯 | 变量命名、函数拆分、代码风格 | "数组用 List 后缀" |
| 沟通习惯 | 回复长度、代码展示方式 | "直接给代码就行" |
| 工作流习惯 | 提交前检查、分支策略 | "提交前跑 lint" |
| 项目特定 | 特定项目的约定 | "这个项目 API 返回格式是 { code, data, msg }" |
| 禁止行为 | 用户明确禁止的行为 | "不要自己装依赖" |

**记录格式**：
```markdown
| 日期 | 场景 | 规则 | 来源 |
|---|---|---|---|
| YYYY-MM-DD | 场景描述 | 具体规则 | "用户原话" |
```

---

## 四、配置文件职责边界

| 层级 | 文件 | 核心职责 | 独有内容 |
|---|---|---|---|
| **L1** | company_unified_config.md | 安全红线 + 技术选型原则 + 编码底线 + 沟通 AI 行为 | 安全红线（只读）、Git 规范、技术栈偏好 |
| **L1+** | language/*.md | 各语言详细编码规范和框架约束 | Java 命名/分层、Tofly 约束、Vue2/Vue3 组件模板 |
| **L2** | warehouse_shared_config.md | 项目技术事实 + 团队共识 | 具体技术栈、架构约定、构建命令、PR 补充 |
| **L3** | local_private_config.md | 本地环境 + 个人偏好 + 用户习惯 | 浏览器规则、调试习惯、注释偏好、习惯记录 |

**职责划分原则**：
- L1 只定义"原则与底线 + 语言约束"，语言细节委托 language/ 文件夹
- L2 声明项目技术事实和团队共识
- L3 仅定义本地临时偏好和个人习惯，不重复上层内容

---

## 五、健康度评估

### 5.1 当前优势

| 维度 | 评分 | 说明 |
|---|---|---|
| 约束完备性 | ★★★★★ | 三级权重体系完善，安全红线只读 |
| 分层设计 | ★★★★★ | L1-L3 层级清晰，language/ 按语言解耦 |
| 渐进披露 | ★★★★★ | 动态路由机制，Token 消耗优化 78%-93% |
| 控制粒度 | ★★★★☆ | 从安全红线到命名约定的多粒度控制 |
| 可维护性 | ★★★★☆ | Markdown 格式 + 锚点定位，language/ 模块化 |

### 5.2 待改进领域

| 维度 | 当前状态 | 改进方向 |
|---|---|---|
| 自动化验证 | 手动阅读配置 | 增加 JSON Schema 校验 |
| 反馈闭环 | 质量门禁已实现 | 增加 Agent 自我反思机制 |
| 决策追溯 | 无 | 记录关键决策点和理由 |
| 漂移检测 | 无 | 定期对比 memory_bak 与当前差异 |
| 冲突检测 | 权重覆盖解决 | 同层级隐式冲突告警 |

---

## 六、关键设计决策

### 6.1 为什么从4层精简为3层？

**问题**：4层架构中 L2（个人全局配置）与 L1/L3 存在职责重叠，维护成本高

**方案**：3层架构
- L1（权重25）：公司级安全红线 + 技术选型 + 编码底线 + 沟通 AI 行为（原 L1 + 原 L2 内容合并）
- L2（权重75）：项目级技术事实 + 架构约定 + 构建命令（保留原 L3）
- L3（权重100）：本地临时偏好 + 个人习惯 + 用户习惯记录（保留原 L4）

**收益**：
- 减少一层配置的维护和同步成本
- 消除 L1/L2 间的职责模糊地带
- 动态路由更简单直接

### 6.2 为什么将语言约束独立为 language/ 文件夹？

**问题**：各语言编码规范内容庞大（Java ~350行，Vue ~340行），全量放在 L1 主文件中导致 Token 浪费

**方案**：language/ 文件夹按语言独立，按需加载
- `language/java.md`：Java / Spring Boot / Tofly 约束
- `language/vue2.md`：Tofly Vue2 约束
- `language/vue3.md`：Vue 3 + Vben Admin 5.0 约束
- `language/vben2.md`：Vben Admin v2 CRUD 页面生成技能
- `language/python.md`：Python 规范

**收益**：
- 非 Java/Vue 任务不加载语言约束，节省 ~700 行 Token
- 语言约束可独立更新，不影响主配置文件
- 新增语言只需添加文件 + 更新路由表

### 6.3 为什么安全红线标记为只读？

**问题**：安全规则可能被更高层级配置意外覆盖

**方案**：L1 安全红线部分标记为只读，任何层级不可覆盖

**收益**：
- 强制保障公司安全底线
- 防止配置冲突导致安全漏洞
- 明确责任边界（安全 vs 灵活性）

---

## 七、使用指南

### 7.1 AI Agent 使用流程

```
1. 启动时加载 configure_entrance.md（~70 行）
2. 读取 L3 §五 用户习惯记录，了解历史偏好
3. 收到用户问题后判断任务类型
4. 根据路由表精确加载对应配置片段
5. 执行任务时遵循权重覆盖规则
6. 完成后运行质量门禁（lint/typecheck/compile）
7. 如用户有新偏好，更新 L3 §五 用户习惯记录
8. 简要总结做了什么
```

### 7.2 配置维护指南

| 场景 | 应修改的文件 | 示例 |
|---|---|---|
| 公司安全策略变更 | L1（安全红线部分） | 新增禁止使用的依赖 |
| 技术栈偏好调整 | L1 §二 | 从 React 切换到 Vue |
| 语言/框架编码规范 | language/xxx.md | 更新 Java 命名约定 |
| 项目技术栈升级 | L2 §一 | Spring Boot 2.x → 3.x |
| 项目构建命令变更 | L2 §三 | 新增 Docker Compose 服务 |
| 本地调试临时配置 | L3 | 开启 verbose 日志 |
| 用户习惯/偏好记录 | L3 §五 | "记住数组用 List 后缀" |

### 7.3 冲突解决原则

```
1. 安全红线（L1 §一）优先级最高，任何层级不可覆盖
2. 同一内容在不同层级出现时，高权重层级优先
3. 同层级内隐式冲突时，遵循"后定义覆盖先定义"原则
4. 无法确定时，主动询问用户确认
```

---

## 八、度量指标

| 指标 | 目标 | 当前状态 |
|---|---|---|
| Token 消耗（纯问答） | ≤ 80 行 | ✅ ~70 行 |
| Token 消耗（写代码） | ≤ 250 行 | ✅ ~200-210 行 |
| 配置覆盖率 | 100% 安全红线覆盖 | ✅ 已实现 |
| 质量门禁通过率 | ≥ 95% | ⚠️ 待统计 |
| 配置冲突率 | 0%（安全红线） | ✅ 已实现 |
| 动态路由准确率 | ≥ 90% | ⚠️ 待统计 |
| 用户习惯记录更新 | 按需更新 | ⚠️ 需手动更新 |

---

*最后更新：2026-04-18*
*版本：4.0.0*
*适用范围：AI IDE Agent 记忆系统*