JIANG800/coding-agent-harness

Coding Agent Harness "Refine"

一个自实现的 Coding Agent Harness，聚焦反馈闭环驱动的多轮自我修正。

项目简介

本项目从零实现一个 Coding Agent Harness 内核：agent 主循环、LLM 抽象层、工具分发、治理护栏、反馈闭环、记忆、配置。重点维度为反馈闭环——用确定性校验器（pytest/ruff/mypy）解析产物 → 失败分类 → 结构化反馈回灌 → 多轮自我修正。所有核心机制可用 MockLLM 确定性单测。

核心等式：Agent = LLM + Harness。LLM 只负责"决定下一步做什么"，harness 负责其余一切工程：组织上下文、调用 LLM、解析动作、分发工具、治理护栏、反馈闭环、记忆、配置。

安装

从源码安装

git clone <repo-url>
cd coding-agent-harness
pip install -e ".[dev]"

Docker 安装

docker build -t coding-agent-harness .
docker run -p 8000:8000 coding-agent-harness

运行

运行测试

pytest tests/ -v

启动 WebUI

uvicorn harness.webui.app:app --host 0.0.0.0 --port 8000

访问 http://localhost:8000

API Key 安全配置

1. 1.启动 WebUI 后，在页面上输入 API key（隐藏输入），点击 Store Key
2. 2.Key 通过 keyring 存入操作系统钥匙串（Windows Credential Manager / macOS Keychain / Linux Secret Service）
3. 3.Key 绝不硬编码、绝不进 git、绝不进日志
4. 4.查看状态：GET /api/credentials/status（仅返回布尔，不回显明文）
5. 5.清除：DELETE /api/credentials/openai_api_key

容器场景：Key 不烤进镜像。运行时通过 WebUI 录入，或通过环境变量注入（文档说明进程可见风险）。

分发命令

docker build -t coding-agent-harness .
docker run -p 8000:8000 coding-agent-harness

目录结构

src/harness/
├── core/          # agent 主循环、LLM 抽象、动作解析
├── tools/         # 文件读写、shell、测试运行
├── feedback/      # 反馈闭环（重点维度）
├── governance/    # 护栏、HITL、沙箱
├── memory/        # 跨会话记忆
├── config/        # 声明式配置
├── credentials/   # keyring 凭据管理
└── webui/         # FastAPI 仪表盘
tests/             # mock-LLM 确定性单测（99 个测试）

安全边界

• —凭据：keyring 存储，绝不硬编码/进 git/进日志；status() 不回显明文
• —沙箱：agent 只能操作 project_dir 内文件
• —护栏：危险命令（rm -rf / drop table / git push --force 等）被拦截并要求 HITL 审批
• —HITL：危险动作暂停等待人工审批

机制演示（§A.6）

pytest tests/test_mechanism_demo.py -v

三种确定性行为：

1. 1.治理护栏拦截 rm -rf / 危险动作
2. 2.注入失败（缺 import）→ 反馈闭环检测 → agent 据反馈修复 → 通过
3. 3.多轮自我修正：语法错误 → 修复 → 导入错误 → 修复 → 通过

已知限制

• —需 Docker 环境（容器分发）
• —容器内 keyring 数据在容器删除后丢失（需挂载卷持久化）
• —ruff/mypy 未安装时自动跳过
• —WebUI 轮询刷新（非实时推送）

第三方依赖

• —OpenAI Python SDK (MIT)
• —keyring (MIT)
• —FastAPI (MIT)
• —Jinja2 (BSD)
• —pytest (MIT)
• —PyYAML (MIT)