Metadata-Version: 2.4
Name: Liu-Agent
Version: 0.1.1
Summary: LiuCodeAgent - 基于 Harness 架构的自主代码编写 Agent
Author: LiuCodeAgent Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/liu-agent
Project-URL: Repository, https://github.com/your-org/liu-agent
Keywords: agent,ai,code,harness,llm,automation,liuagent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Requires-Dist: tiktoken>=0.5.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
Provides-Extra: docker
Requires-Dist: docker>=6.0.0; extra == "docker"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: tiktoken>=0.5.0; extra == "all"
Requires-Dist: anthropic>=0.18.0; extra == "all"
Requires-Dist: docker>=6.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# 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. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 运行示例
```bash
# 单任务模式 - 创建文件
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
```

## 扩展开发

### 添加新工具
```python
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"]
)
```

### 接入真实模型
```python
from model.engine import OpenAIEngine

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

### 启用 Docker 沙箱
```python
sandbox = Sandbox(
    use_docker=True,
    docker_image="python:3.11-slim",
    permission="write-workspace"
)
```

## 参考

- [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents)
- [Hermes: The Design and Implementation of an Agentic AI System](https://arxiv.org/abs/2505.14737)
- [OpenAI Codex CLI](https://github.com/openai/codex)
- [Claude Code Engineering](https://www.youtube.com/watch?v=6kE3lXZlLi0)
