lazyyoun's blog
Harness Engineering v4 - TypeScript 多 Agent 协作系统
编辑
2026-04-01
技术
00
请注意，本文编写于 101 天前，最后修改于 101 天前，其中某些信息可能已经过时。

目录

Harness Engineering v4 - 完整文档
📋 目录
项目概述
定位
核心价值
技术栈
技术架构
五层架构
项目结构
核心能力
1. 自动扫描 TODO
2. 多 Agent 协作
3. MySQL 持久化
4. CodeModifier 代码修改
5. OpenTelemetry 监控
6. Web UI 界面
开发进度
Phase 完成状态
统计
验收标准达成
TODO 清单
P0 紧急 ✅ 全部完成
P1 重要 ✅ 全部完成
P2 一般 ✅ 全部完成
已知问题
实战验证
验证项目: Stock Optimizer
P0 任务验证 ✅
P1 任务验证 ✅
P2 任务验证 ✅
多 Agent 协作验证 ✅
问题与解决
问题 1: Cron 超时中断
问题 2: 图片识别错误
问题 3: MySQL 精度丢失
问题 4: Reviewer 拒绝执行
技术要点
BashSecurity 7层防护（参考 Claude Code）
AgentMemory 三层架构
CodeModifier 安全设计
ExecutionManager 流程
使用指南
环境配置
启动 Web UI
自动扫描 TODO
股票相关脚本
测试
附录
OpenClaw Skill 配置
MySQL 连接信息
OpenTelemetry 接入点
版本历史
作者
关键词

Harness Engineering v4 - 完整文档

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

📋 目录

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

项目概述

定位

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

核心价值

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

技术栈

层级技术版本
运行时Bunv1.3.11
语言TypeScriptES2022
存储MySQL阿里云 RDS
监控OpenTelemetry阿里云 ARMS
WebFastifyv5.8.4
PDFPuppeteerv24.40.0
图表Chart.jsCDN

技术架构

五层架构

┌─────────────────────────────────────────────┐
│  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 紧急 ✅ 全部完成

  • TypeScript 重构完成
  • MySQL 连接实现
  • OpenClaw sessions_spawn 集成

P1 重要 ✅ 全部完成

  • 自动扫描 TODO.md 任务
  • 多 Agent 协作流程
  • Stock Optimizer 集成

P2 一般 ✅ 全部完成

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

已知问题

问题影响解决方案
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.02026-04-01TypeScript 重构完成
v0.5.02026-03-31Python v3 版本
v0.4.02026-03-23AgentScope Bridge
v0.3.02026-03-14MySQL 集成

作者

lazyoun

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

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

关键词

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

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

本文作者:lazyyoun

本文链接:

版权声明:本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！