记忆系统 Harness Engineering 体系

核心公式：Agent = Model + Harness 本记忆系统即为 AI IDE Agent 的 Harness（驾驭系统），通过约束机制、反馈回路、控制平面三大支柱，确保 AI 行为可控、可预测、可优化。

⚠️ 本文件为架构设计文档，AI 日常操作所需的内容（约束分类、职责边界、使用流程、维护指南、冲突解决）已融合进 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 §五

触发条件：

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

记录分类：

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

记录格式：

| 日期 | 场景 | 规则 | 来源 |
|---|---|---|---|
| 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 记忆系统

harness_engineering.md 11 KB Permalink History Raw