LiuCodeAgent - 基于 Harness 架构的代码编写 Agent

架构概览

┌─────────────────────────────────────────────┐
│                 CLI / API                     │
├─────────────────────────────────────────────┤
│              Harness Layer                    │
│  ┌─────────┐ ┌──────────┐ ┌─────────────┐ │
│  │ Control │ │ Context  │ │ Permission  │ │
│  │ Loop    │ │ Compress │ │ Manager     │ │
│  └─────────┘ └──────────┘ └─────────────┘ │
│  ┌─────────┐ ┌──────────┐ ┌─────────────┐ │
│  │ Tool    │ │ Session  │ │ Orchestrator│ │
│  │ Router  │ │ Manager  │ │ (Multi-Agent)│ │
│  └─────────┘ └──────────┘ └─────────────┘ │
├─────────────────────────────────────────────┤
│              Tool Layer (MCP)                 │
│  File │ Shell │ Git │ Test │ Search          │
├─────────────────────────────────────────────┤
│              Environment Layer                │
│  Sandbox (Docker/Local) + Workspace           │
├─────────────────────────────────────────────┤
│              Model Layer                        │
│  OpenAI │ Anthropic │ Local │ Mock           │
└─────────────────────────────────────────────┘

核心特性

1. Harness 控制循环 (ReAct)

• 持续调用模型，维持 Thought → Action → Observation 循环
• 支持中断和状态恢复
• Token 预算和轮次限制

2. 三层懒加载工具系统 (Hermes)

• Tier 1: 仅加载工具名称 (~50 tokens/tool)
• Tier 2: 按需加载完整 Schema (~300 tokens/tool)
• Tier 3: 预测性选择 Top-K 工具

3. 4层上下文压缩 (Claude Code)

• Snip: 截断过长输出
• Microcompact: 提取关键行
• Collapse: 合并早期历史为决策摘要
• Autocompact: LLM 生成摘要

4. 并发安全执行

• 读操作并行执行
• 写操作串行执行（保证事务性）
• 权限分级（5层防御）

5. 多 Agent 编排

• Star Topology 架构
• Agent 原型：Explorer / Builder / Surgeon / Tester / Reviewer
• DAG 并行执行复杂任务

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 运行示例

# 单任务模式 - 创建文件
python cli.py "创建一个 hello.py 文件，包含 greet 函数" --scenario write_file

# 单任务模式 - 编辑文件
python cli.py "在 hello.py 中添加 goodbye 函数" --scenario edit_file

# 复杂任务模式
python cli.py "创建一个完整的 Flask Web API" --scenario complex_task --complexity complex

# 交互模式
python cli.py -i

# 使用真实模型（需配置 API Key）
export OPENAI_API_KEY="your-key"
python cli.py "创建项目" --model openai

项目结构

liuagent/
├── harness/               # Harness 核心层
│   ├── core_loop.py      # ReAct 控制循环
│   ├── context_compressor.py  # 4层上下文压缩
│   └── orchestrator.py   # 多 Agent 编排
├── model/                # 模型层
│   └── engine.py         # 多模型引擎
├── tools/                # 工具层
│   ├── tool_registry.py  # 三层懒加载注册表
│   └── implementations.py # 工具实现
├── environment/           # 环境层
│   └── sandbox.py        # 沙箱环境
├── cli.py                # 主入口
├── requirements.txt
└── README.md

扩展开发

添加新工具

from tools.tool_registry import ToolRegistry

registry.register(
    name="my_tool",
    description="我的工具描述",
    parameters={"type": "object", "properties": {...}},
    handler=my_handler,
    is_read_only=True,
    tags=["custom"]
)

接入真实模型

from model.engine import OpenAIEngine

model = OpenAIEngine(api_key="your-key", model="gpt-4")
harness = Harness(model_engine=model, ...)

启用 Docker 沙箱

sandbox = Sandbox(
    use_docker=True,
    docker_image="python:3.11-slim",
    permission="write-workspace"
)

参考

• Anthropic: Building Effective Agents
• Hermes: The Design and Implementation of an Agentic AI System
• OpenAI Codex CLI
• Claude Code Engineering