# 双层记忆架构概述

> **系列**: 个人知识管理系统 | **更新**: 2026-04-07

---

## 一、背景与动机

### 传统知识管理的痛点

在 AI Agent 开发过程中，我遇到了几个核心问题：

1. **记忆碎片化** — 每次对话都是新会话，Agent 无法记住之前学到的内容
2. **检索效率低** — 日志文件堆积，关键时刻找不到关键信息
3. **人机脱节** — Agent 知道的，我不知道；我知道的，Agent 不知道

### Karpathy 的启示

Andrej Karpathy 提出的核心理念：

> **"让 AI 成为知识库的主动维护者，而不是被动查询者"**

这启发我设计双层记忆架构。

---

## 二、双层记忆架构设计

**双层记忆** = **Wiki 层（人可读）** + **LanceDB 层（机可检索）**

```
OpenClaw Agent（定时任务驱动）
       ↓ 调用工具
wiki_tools.py（统一接口层）
       ↓ 读写
┌──────────────────┬──────────────────────┐
│  Wiki 层         │  LanceDB 层          │
│  (Markdown)      │  (向量索引)          │
│  人可读          │  机可检索            │
│  Obsidian 查看   │  text-embedding-v4   │
└──────────────────┴──────────────────────┘
```

---

## 三、两层的分工

| 维度 | Wiki 层 | LanceDB 层 |
|------|---------|------------|
| 格式 | Markdown | 向量 + 结构化字段 |
| 检索 | 目录浏览 | 语义搜索 |
| 受众 | 人类 | Agent |
| 更新 | 定时任务整合 | 实时写入 |
| 特点 | 可读性强 | 检索效率高 |

---

## 四、核心价值

1. **人机共享** — Agent 写入的内容，人类可以阅读
2. **主动维护** — 定时任务自动整合日志、检查健康状态
3. **语义检索** — 用自然语言提问，找到最相关的记忆
4. **智能去重** — 自动检测重复记录

---

## 五、系列文章

1. 架构概述（本文）
2. Wiki 层详解
3. LanceDB 层详解
4. 双层联动机制
5. 定时任务与自动化
6. 开发工作流集成
7. 个人知识管理
8. 最佳实践与避坑指南

双层记忆架构（第1章）架构概述

# Harness Engineering v4 - 完整文档

> TypeScript 多 Agent 协作执行系统 | 2026-04-01

---

## 📋 目录

1. [项目概述](#项目概述)
2. [技术架构](#技术架构)
3. [核心能力](#核心能力)
4. [开发进度](#开发进度)
5. [TODO 清单](#todo-清单)
6. [实战验证](#实战验证)
7. [问题与解决](#问题与解决)
8. [技术要点](#技术要点)
9. [使用指南](#使用指南)

---

## 项目概述

### 定位

**Harness v4** 是一个基于 TypeScript 的多 Agent 协作执行系统，能够自动扫描 TODO 任务、生成解决方案、评审执行、持久化结果。

### 核心价值

```
传统自动化脚本: 固定流程，无智能决策
Harness v4: LLM 驱动，多 Agent 协作，自动执行 + 验证 + 回滚
```

### 技术栈

| 层级 | 技术 | 版本 |
|------|------|------|
| 运行时 | Bun | v1.3.11 |
| 语言 | TypeScript | ES2022 |
| 存储 | MySQL | 阿里云 RDS |
| 监控 | OpenTelemetry | 阿里云 ARMS |
| Web | Fastify | v5.8.4 |
| PDF | Puppeteer | v24.40.0 |
| 图表 | Chart.js | CDN |

---

## 技术架构

### 五层架构

```
┌─────────────────────────────────────────────┐
│  Layer 5: Delivery Layer (交付层)            │
│  - 微信推送、PDF 导出、Web UI                 │
├─────────────────────────────────────────────┤
│  Layer 4: Observability Layer (可观测层)     │
│  - OpenTelemetry、Dashboard、JSONL 日志      │
├─────────────────────────────────────────────┤
│  Layer 3: Orchestrator Layer (协调层)        │
│  - Generator → Evaluator → Reviewer         │
│  - 多 Agent 协作、任务调度                    │
├─────────────────────────────────────────────┤
│  Layer 2: Guard Layer (护栏层)               │
│  - BashSecurity 7层防护                      │
│  - 危险命令拦截、风险评估                     │
├─────────────────────────────────────────────┤
│  Layer 1: Persistence Layer (持久层)         │
│  - MySQL 任务存储、检查点、历史记录           │
└─────────────────────────────────────────────┘
```

### 项目结构

```
~/Documents/harness-v4/
├── src/
│   ├── core/               # 核心组件
│   │   ├── TaskManager.ts      # 任务生命周期
│   │   ├── Orchestrator.ts     # 多 Agent 协调
│   │   ├── TaskExecutor.ts     # 任务执行引擎
│   │   ├── CodeModifier.ts     # 代码修改工具
│   │   ├── Guard.ts            # 护栏规则
│   │   └── Config.ts           # 配置管理
│   ├── database/           # 数据库层
│   │   └ MySQLClient.ts        # MySQL 连接池
│   ├── api/                # API 层
│   │   └ OpenClawClient.ts     # OpenClaw API
│   ├── security/           # 安全层
│   │   └ BashSecurity.ts       # 7层安全验证
│   ├── telemetry/          # 监控层
│   │   └ TelemetryClient.ts    # OpenTelemetry
│   ├── memory/             # 记忆系统
│   │   └ AgentMemory.ts        # 三层记忆
│   ├── tracker/            # 进度追踪
│   │   ├── ProgressTracker.ts  # 进度管理
│   │   └ CheckpointManager.ts  # 检查点
│   ├── tools/              # 工具集成
│   │   └ MCPTool.ts            # MCP 协议
│   ├── ui/                 # 终端 UI
│   │   └ Dashboard.tsx         # Ink + React
│   └── types/              # TypeScript 类型
│       ├── Task.ts
│       ├── Event.ts
│       └ Config.ts
├── scripts/                # 可执行脚本
│   ├── auto_scan.ts            # TODO 自动扫描
│   ├── stock_trend_report.ts   # 股票趋势
│   ├── risk_monitor.ts         # 风险监控
│   ├── account_manager.ts      # 账户管理
│   ├── export_pdf_report.ts    # PDF 导出
│   └ all_accounts_summary.ts   # 多账户汇总
│   └ test_code_modifier.ts     # 代码修改测试
├── server/                 # Web API
│   └ api.ts                    # Fastify (端口 5556)
├── web/                    # 前端界面
│   └ index.html                # Chart.js
├── tests/                  # 测试文件
│   ├── core.test.ts            # 核心模块测试
│   └ integration.test.ts       # 集成测试
├── docs/                   # 设计文档
│   ├── architecture.md
│   ├── migration-plan.md
│   ├── ts-implementation.md
│   ├── otel-integration.md
│   └ FULL-REPORT.md           # 本文档
├── SKILL.md                # OpenClaw 技能文档
├── skill.json              # OpenClaw 技能配置
├── TODO.md                 # 待办事项
├── PROGRESS.md             # 进度追踪
└── package.json            # 依赖配置
```

---

## 核心能力

### 1. 自动扫描 TODO

```typescript
// scripts/auto_scan.ts
// 解析 TODO.md，识别未完成任务
// 创建任务到 MySQL
// 触发多 Agent 协作执行
```

**流程**:
1. 扫描 `~/Documents/stock-optimizer/TODO.md`
2. 扫描 `~/Documents/harness-v4/TODO.md`
3. 解析 P0/P1/P2 优先级
4. 创建任务到 `tasks` 表
5. 触发 Generator Agent

### 2. 多 Agent 协作

```
Generator Agent   → 生成解决方案
Evaluator Agent   → 评审方案（风险分析）
Reviewer Agent    → 最终确认（批准/拒绝）
TaskExecutor      → 实际执行（MySQL/代码修改）
```

**协作流程**:
```
[扫描] → [创建任务] → [Generator] → [Evaluator] → [Reviewer]
                                    ↓
                              [approved?]
                              ├── yes → [执行] → [验证] → [完成]
                              └── no  → [改进方案] → [重新评审]
```

### 3. MySQL 持久化

**表结构**:

| 表名 | 用途 | 字段 |
|------|------|------|
| `tasks` | 任务队列 | id, status, priority, session_key |
| `events` | 事件日志 | task_id, event_type, details(JSON) |
| `stock_accounts` | 股票账户 | id, account_name, created_at |
| `stock_daily_records` | 每日记录 | account_id, total_asset, profit_loss |
| `stock_holdings` | 持仓明细 | record_id, stock_name, profit_pct |
| `execution_history` | 执行历史 | task_id, status, files_modified(JSON) |

### 4. CodeModifier 代码修改

```typescript
// src/core/CodeModifier.ts
class CodeModifier {
  // 精确替换（自动备份）
  async edit(filePath, oldText, newText) {
    const backup = filePath + '.backup.' + Date.now();
    fs.writeFileSync(backup, original);
    // ... 精确替换
  }
  
  // 创建文件
  async write(filePath, content) { }
  
  // 批量编辑
  async batchEdit(edits[]) { }
  
  // 执行验证命令
  async verify(command) { }
  
  // 恢复备份
  async restore(backupPath, originalPath) { }
}
```

**安全特性**:
- 自动备份: `.backup.{timestamp}` 文件
- oldText 检查: 不存在则返回错误
- 回滚恢复: restore() 可恢复任意备份

### 5. OpenTelemetry 监控

**接入点**:
```
Trace: http://tracing-analysis-dc-hz.aliyuncs.com/.../api/otlp/traces
Metric: http://tracing-analysis-dc-hz.aliyuncs.com/.../api/otlp/metrics
```

**上报内容**:
- 任务执行 Span
- Agent 协作事件
- 错误追踪
- 性能指标

### 6. Web UI 界面

**端口**: 5556

**API 端点**:
- `/api/summary` - 资产卡片（总资产/盈亏）
- `/api/holdings` - 持仓表格
- `/api/trends/:id` - 资产趋势
- `/api/accounts` - 多账户列表

**前端**:
- Chart.js 资产趋势图
- Tailwind CSS 样式
- 单页 HTML（无需构建）

---

## 开发进度

### Phase 完成状态

```
Phase 0: 准备工作    [██████████] 100% ✅
Phase 1: 核心迁移    [██████████] 100% ✅
Phase 2: 扩展能力    [██████████] 100% ✅
Phase 3: 集成测试    [██████████] 100% ✅
Phase 4: 文档发布    [██████████] 100% ✅
Phase 5: 脚本修复    [██████████] 100% ✅
```

### 统计

| 项目 | 数量 |
|------|------|
| TS 源文件 | 18 个 |
| 测试文件 | 2 个 |
| 测试通过 | 26 个 |
| 脚本文件 | 7 个 |
| 文档文件 | 10 个 |
| 代码行数 | ~3000 行 |

### 验收标准达成

| 标准 | 状态 |
|------|------|
| TypeScript 编译 | ✅ 通过 |
| MySQL 连接 | ✅ 正常 |
| OpenClaw API | ✅ 调用成功 |
| OpenTelemetry | ✅ 上报正常 |
| 测试覆盖 | ✅ 26 pass |

---

## TODO 清单

### P0 紧急 ✅ 全部完成

- [x] TypeScript 重构完成
- [x] MySQL 连接实现
- [x] OpenClaw sessions_spawn 集成

### P1 重要 ✅ 全部完成

- [x] 自动扫描 TODO.md 任务
- [x] 多 Agent 协作流程
- [x] Stock Optimizer 集成

### P2 一般 ✅ 全部完成

- [x] 创建 OpenClaw 技能包装
- [x] 多 Agent 协作执行优化
- [x] 自动调用代码修改工具
- [x] 执行结果验证和回滚（方案通过）

### 已知问题

| 问题 | 影响 | 解决方案 |
|------|------|----------|
| Cron 超时限制 | 多 Agent 协作需要 300s+，当前 ~120s | 手动执行或增加 timeout |
| Reviewer 拒绝 | Generator 方案质量不足 | 改进方案生成逻辑 |

---

## 实战验证

### 验证项目: Stock Optimizer

**场景**: 股票持仓管理 + 盈亏追踪

### P0 任务验证 ✅

| 任务 | 验证结果 |
|------|----------|
| 百炼 API 图片识别 | ✅ 正常识别持仓截图 |
| MySQL 存储表结构 | ✅ 3 表 + 10 条数据 |
| 持仓对比算法 | ✅ 计算 ¥-2,356.58 |

**数据验证**:
```
总资产: ¥100,079.97 ✅
持仓盈亏: ¥-2,356.58 ✅
盈利股票: 1 只（港股汽车ETF +6.05%）✅
亏损股票: 8 只 ✅
```

### P1 任务验证 ✅

| 任务 | 验证结果 |
|------|----------|
| 定时提醒截图 | ✅ Cron 09:30/15:00 |
| 持仓趋势可视化 | ✅ Chart.js 图表 |
| 风险预警阈值 | ✅ MySQL alert_configs |

### P2 任务验证 ✅

| 任务 | 验证结果 |
|------|----------|
| 多账户管理 | ✅ account_manager.ts |
| PDF 导出 | ✅ Puppeteer 生成 |
| Web UI | ✅ localhost:5556 |

### 多 Agent 协作验证 ✅

```
执行流程:
[Generator] → 生成表结构方案
[Evaluator] → 评审风险 + 建议
[Reviewer] → 批准执行
[Executor] → 创建表 + 插入数据

结果: 
✅ stock_accounts (1 条)
✅ stock_daily_records (1 条)
✅ stock_holdings (9 条)
```

---

## 问题与解决

### 问题 1: Cron 超时中断

**现象**: 多 Agent 协作需要 300s+，Cron 限制 ~120s

**影响**: 自动扫描经常超时中断

**解决方案**:
```bash
# 方案 A: 手动执行（已采用）
cd ~/Documents/harness-v4 && bun run scripts/auto_scan.ts

# 方案 B: 增加 timeout（待配置）
# skill.json 添加 timeoutSeconds: 300
```

### 问题 2: 图片识别错误

**现象**: 肉眼识别持仓截图错误

**影响**: 把持仓总览误认为买入委托

**解决方案**:
```typescript
// 使用百炼 qwen3.5-plus 多模态
const response = await dashscope.multimodal({
  model: 'qwen3.5-plus',
  image: imagePath,
  prompt: '识别股票持仓截图内容'
});
```

### 问题 3: MySQL 精度丢失

**现象**: DECIMAL(10,2) 存储股票金额丢失精度

**影响**: ¥100,079.97 → ¥100,079.90

**解决方案**:
```sql
-- 使用 DECIMAL(10,4)
ALTER TABLE stock_daily_records 
MODIFY profit_loss DECIMAL(10,4);
```

### 问题 4: Reviewer 拒绝执行

**现象**: Reviewer Agent 返回内容不包含 "approved"

**影响**: 多 Agent 协作中断

**解决方案**:
```typescript
// 改进 Reviewer 决策逻辑
const approved = response.includes('approved') || 
                 response.includes('同意') ||
                 response.includes('批准');
```

---

## 技术要点

### BashSecurity 7层防护（参考 Claude Code）

```
┌─────────────────────────────────────────┐
│ Layer 7: Execution (执行层)              │
│ - 超时控制、沙箱隔离                      │
├─────────────────────────────────────────┤
│ Layer 6: Environment Isolation          │
│ - PATH 限制、环境变量过滤                 │
├─────────────────────────────────────────┤
│ Layer 5: Permission Check               │
│ - 文件访问权限验证                        │
├─────────────────────────────────────────┤
│ Layer 4: Param Validation               │
│ - 特殊参数过滤（--force, -rf）            │
├─────────────────────────────────────────┤
│ Layer 3: Whitelist                      │
│ - 允许命令列表（ls, cat, pwd）            │
├─────────────────────────────────────────┤
│ Layer 2: Blacklist                      │
│ - 危险命令拦截（rm -rf, mkfs）            │
├─────────────────────────────────────────┤
│ Layer 1: Input Validation               │
│ - 类型检查、长度限制                      │
└─────────────────────────────────────────┘
```

### AgentMemory 三层架构

```typescript
class AgentMemory {
  // 短期记忆: 最近 10 轮对话
  shortTerm: MemoryEntry[] = [];
  
  // 中期记忆: 任务上下文（JSONL 文件）
  midTermFile: string = 'memory/context.jsonl';
  
  // 长期记忆: 知识库（MySQL + MD 文件）
  longTermDB: MySQLClient;
}
```

### CodeModifier 安全设计

```typescript
// 核心原则:
1. 自动备份: edit() 创建 .backup.{timestamp} 文件
2. 精确匹配: oldText 必须完全匹配，否则返回错误
3. 回滚恢复: restore() 可恢复任意备份
4. 验证命令: verify() 执行 bun test 验证修改
```

### ExecutionManager 流程

```typescript
async executeWithVerification(edits, verifyCommand, autoRollback) {
  // 1. 创建快照
  const snapshot = await this.createSnapshot(files);
  
  // 2. 执行修改（记录操作日志）
  const operations = [];
  for (const edit of edits) {
    const result = await this.codeModifier.edit(...);
    operations.push(result);
  }
  
  // 3. 验证修改
  const verification = await this.codeModifier.verify(verifyCommand);
  
  // 4. 验证失败自动回滚
  if (!verification.success && autoRollback) {
    await this.rollbackOperations(operations);
    return { status: 'rolled_back' };
  }
  
  // 5. 保存执行历史到 MySQL
  await this.saveExecutionHistory(snapshot, operations, verification);
  
  return { status: 'success' };
}
```

---

## 使用指南

### 环境配置

```bash
# MySQL 环境变量
export MYSQL_HOST=
export MYSQL_USER=
export MYSQL_PASSWORD=
export MYSQL_DATABASE=

# OpenClaw API
export OPENCLAW_API_URL=http://localhost:18789
```

### 启动 Web UI

```bash
cd ~/Documents/harness-v4
bun run server/api.ts

# 访问: http://localhost:5556
```

### 自动扫描 TODO

```bash
cd ~/Documents/harness-v4
bun run scripts/auto_scan.ts
```

### 股票相关脚本

```bash
# 趋势报告
bun run scripts/stock_trend_report.ts

# 风险监控
bun run scripts/risk_monitor.ts

# 多账户汇总
bun run scripts/all_accounts_summary.ts

# PDF 导出
bun run scripts/export_pdf_report.ts

# 账户管理
bun run scripts/account_manager.ts list
```

### 测试

```bash
# 运行测试
bun test

# 结果: 26 tests passed
```

---

## 附录

### OpenClaw Skill 配置

```json
{
  "name": "harness-v4",
  "version": "1.0.0",
  "runtime": "bun",
  "entry": "scripts/auto_scan.ts",
  "capabilities": [
    "auto-scan",
    "multi-agent-execution",
    "mysql-storage",
    "stock-analysis",
    "pdf-export",
    "web-ui"
  ],
  "config": {
    "mysql": {
      "host": "${MYSQL_HOST}",
      "user": "${MYSQL_USER}",
      "password": "${MYSQL_PASSWORD}",
      "database": "${MYSQL_DATABASE}"
    }
  }
}
```

### MySQL 连接信息

```
Host: 
Port: 
User: 
Database: 
Provider: 阿里云 RDS
```

### OpenTelemetry 接入点

```
Region: 华东1（杭州）
Trace: http://tracing-analysis-dc-hz.aliyuncs.com/.../api/otlp/traces
Metric: http://tracing-analysis-dc-hz.aliyuncs.com/.../api/otlp/metrics
```

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v1.0.0 | 2026-04-01 | TypeScript 重构完成 |
| v0.5.0 | 2026-03-31 | Python v3 版本 |
| v0.4.0 | 2026-03-23 | AgentScope Bridge |
| v0.3.0 | 2026-03-14 | MySQL 集成 |

---

## 作者

**lazyoun**

**项目地址**: `~/Documents/harness-v4/`

**博客地址**: https://blog.lazyyoun.xyz

---

## 关键词

multi-agent, automation, mysql, typescript, stock-optimizer, bun, openclaw, opentelemetry

---

*文档生成时间: 2026-04-01 21:00*

Harness Engineering v4 - TypeScript 多 Agent 协作系统

Claude Code 源码泄露完整技术分析

Harness 系统升级调研报告 V21

# Harness AutoExecutor V3 + Telemetry 系统上线

> 发布时间：2026-03-31
> 重点：OpenTelemetry 兼容的数据记录系统

---

## 一、核心改进

| 版本 | 特性 |
|------|------|
| V1 | 基础 AutoExecutor |
| V2 | sessions_spawn 真执行 |
| **V3** | **Telemetry Enabled** ✅ |

### V3 新特性

1. **OpenTelemetry 兼容**
   - Trace: 任务执行的完整链路
   - Metric: 执行时间、成功率、任务数量
   - Log: 结构化事件日志

2. **数据持久化**
   - MySQL: harness_traces + harness_metrics + harness_logs
   - JSONL: 本地 events.jsonl 文件
   - 后续接入 OpenTelemetry 只需替换 exporter

3. **完整监控**
   - 每个操作都有 span 记录
   - 关键事件都有 log 记录
   - 执行指标都有 metric 记录

---

## 二、数据表结构

### harness_traces (链路追踪)

CREATE TABLE harness_traces (
    trace_id VARCHAR(64),
    span_id VARCHAR(64),
    parent_span_id VARCHAR(64),
    operation_name VARCHAR(255),
    start_time DATETIME,
    end_time DATETIME,
    duration_ms INT,
    status VARCHAR(20),
    attributes JSON,
    events JSON
);

### harness_metrics (指标)

CREATE TABLE harness_metrics (
    metric_name VARCHAR(128),
    value DECIMAL(10,2),
    unit VARCHAR(20),
    attributes JSON
);

### harness_logs (日志)

CREATE TABLE harness_logs (
    trace_id VARCHAR(64),
    span_id VARCHAR(64),
    severity VARCHAR(20),
    message TEXT,
    attributes JSON
);

---

## 三、使用示例

### Python 代码

from harness_telemetry import HarnessTelemetry

# 创建 telemetry recorder
telemetry = HarnessTelemetry(service_name='my-service')

# 开始 trace
telemetry.start_trace('task-001')

# 开始 span
span = telemetry.start_span('execute_task', attributes={'task_id': 'admin-M1'})

# 添加事件
telemetry.add_event('subagent_spawned', {'session_key': 'xxx'})

# 结束 span
telemetry.end_span(status='ok', message='Task completed')

# 记录指标
telemetry.record_metric('task_duration_ms', 2000, unit='ms')

---

## 四、OpenTelemetry 接入计划

### 当前架构

HarnessTelemetry → MySQL + JSONL

### 后续接入

1. 安装 opentelemetry-sdk
2. 配置 exporter (OTLP/Jaeger/Prometheus)
3. 使用 OpenTelemetryAdapter 替换 HarnessTelemetry

### 兼容性

- 数据结构符合 OpenTelemetry 规范
- Trace/Span/Event/Metric 对应 OTel 概念
- 无需修改代码，只需替换底层实现

---

## 五、成果展示

### 数据记录示例

Trace ID: autoexecutor-20260331-202253

Spans:
- autoexecutor_main (0ms)
- ensure_project_dir (0ms)
- query_pending_tasks (194ms)

Metrics:
- tasks_pending_count = 0
- autoexecutor_idle = 1

---

## 六、文件位置

| 文件 | 路径 |
|------|------|
| Telemetry 模块 | claude-harness/telemetry/harness_telemetry.py |
| AutoExecutor V3 | claude-harness/scripts/auto_executor_v3.py |
| 日志文件 | claude-harness/telemetry/events.jsonl |

---

## 七、下一步

| 计划 | 说明 |
|------|------|
| OpenTelemetry 接入 | OTLP exporter 配置 |
| Dashboard 可视化 | Grafana/Jaeger 集成 |
| Python 日志采集 | OpenTelemetry logging handler |

---

*本系统已上线，后续可直接接入 OpenTelemetry 采集系统。*

双层记忆架构概述

Harness Engineering v4 - 完整文档

Claude Code 源码泄露完整技术分析

Harness 系统升级完整调研报告（V21 最终版）

Harness AutoExecutor V3 + Telemetry 系统上线