# agent-harness

**Repository Path**: oldtime15672/agent-harness

## Basic Information

- **Project Name**: agent-harness
- **Description**: 基于opencode的harness插件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Harness Plugin

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6.svg)](https://www.typescriptlang.org/)

平台无关的 AI 代理任务编排引擎，支持 OpenCode、OpenClaw 等多平台扩展。提供文件锁互斥、Git 分支隔离和合同边界，让 AI 代理像项目经理一样拆分任务、调度执行、验证结果。

## 特性

- **核心与扩展分离** — 核心逻辑零平台依赖，通过扩展适配不同 AI 平台
- **独立 Session 上下文** — 多 Session 并行时互不污染，通过持久化元数据协作
- **按需任务编排** — 简单消息直接回复；复杂目标自动拆分为最小原子子任务
- **拓扑排序调度** — `harness_plan` 自动分析依赖关系，生成并行执行计划
- **智能文件锁** — 单任务模式零开销，仅在并行任务修改相同文件时启用锁
- **Git 分支隔离** — 写入型子任务自动创建分支，完成后由用户决定合并或丢弃
- **合同边界** — 限制子代理只能编辑声明的文件和执行允许的命令
- **自动重试** — 子任务失败后可配置重试次数

## 快速开始

### 安装

```bash
git clone https://gitee.com/oldtime15672/agent-harness.git
cd agent-harness
npm install
npm run build
```

### 配置

在目标项目的 `opencode.json` 中注册插件和代理：

```json
{
  "default_agent": "harness",
  "plugin": ["./agent-harness"],
  "agent": {
    "harness": {
      "description": "Harness 主协调器",
      "mode": "primary",
      "prompt": "{file:./agent-harness/skills/harness/SKILL.md}"
    },
    "executor": {
      "description": "执行器",
      "mode": "subagent",
      "prompt": "{file:./agent-harness/templates/executor.md}",
      "permission": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "allow"
      }
    }
  }
}
```

项目级配置文件 `.agent_harness/config.jsonc`：

```jsonc
{
  "git": {
    "enabled": true,              // 启用 Git 分支隔离
    "branch_prefix": "harness/",  // 分支前缀
    "fallback_to_cache": true,    // 非 Git 项目使用缓存回退
    "default_branch": "main"      // 默认分支
  },
  "task": {
    "max_retries": 3,             // 子任务最大重试次数
    "lock_timeout_minutes": 10    // 文件锁超时（分钟）
  }
}
```

## 架构

```
agent-harness/
├── src/                          # 核心模块（零平台依赖）
│   ├── adapter/types.ts          # 适配器接口定义
│   ├── tools/handlers/           # 纯业务逻辑处理函数
│   │   ├── task.ts               # 任务生命周期
│   │   ├── plan.ts               # 执行计划生成
│   │   ├── lock.ts               # 文件锁管理
│   │   └── session.ts            # 会话管理
│   ├── core/                     # 核心编排（类型、注册表、拓扑排序）
│   ├── contract/                 # 合同系统（路径边界、命令检查、文件锁）
│   ├── git/                      # Git 隔离（分支管理、缓存回退）
│   ├── session/                  # 会话上下文（每 Session 独立）
│   ├── config/                   # 配置加载（JSONC 解析）
│   └── logging/                  # 日志（仅写文件，不输出到 CLI）
│
├── extensions/
│   ├── opencode/                 # OpenCode 平台适配
│   │   ├── index.ts              # 插件入口（Plugin 工厂）
│   │   ├── tools.ts              # 工具定义（Zod schema）
│   │   └── hooks.ts              # 钩子适配
│   │
│   └── openclaw/                 # OpenClaw 平台适配
│       ├── index.ts              # 插件入口
│       └── hooks.ts              # EventEmitter 适配
│
├── templates/                    # 子代理提示模板
└── skills/                       # 主协调器技能定义
```

### 核心概念

| 概念 | 说明 |
|------|------|
| `HarnessTask` | 复杂目标的主任务边界，聚合所有子任务的状态、锁和分支 |
| `SubTask` | 最小执行单元，包含单一目标、工具权限和文件/命令合同 |
| `executor` | 子代理，只执行收到的单个 GOAL，不规划、不派生子任务 |
| `SessionContext` | 每个 Session 的独立上下文，不跨 Session 共享 |
| `parallel` | 任务标记，指示是否需要文件锁保护（plan 自动检测设置） |

### 工具 API

<details>
<summary>harness_task — 任务生命周期管理</summary>

| action | 用途 | 关键参数 |
|--------|------|---------|
| `start` | 开始主任务 | task, target_files, success_criteria?, allowed_commands? |
| `subtask` | 注册子任务 | task_id, subtask_id, goal, target_files?, retry_count? |
| `subtask_start` | 开始子任务（创建子分支） | task_id, subtask_id |
| `subtask_done` | 子任务完成（合并子分支） | task_id, subtask_id, passed, evidence, output? |
| `status` | 查看状态 | task_id? (无则列出所有) |
| `detailed_status` | 获取详细状态（含锁信息） | task_id |
| `verify` | 验证主任务 | task_id, passed, evidence |
| `complete` | 完成主任务 | task_id, outcome (merged/discarded), note? |
| `result` | 获取子任务结果 | task_id, subtask_ids? |

</details>

<details>
<summary>harness_plan — 执行计划生成</summary>

| 参数 | 类型 | 说明 |
|------|------|------|
| task_id | string | 主任务 ID |
| tasks | TaskPlan[] | 子任务列表（id, goal, dependencies, target_files?, retry_count?, timeout?） |
| with_instructions? | boolean | 是否包含调度指令（默认 true） |

**自动行为**：
- 检测到并行任务组 + 文件重叠 → 设置 `parallel: true`，启用文件锁
- 否则 → `parallel: false`，单任务模式零锁开销

</details>

<details>
<summary>harness_lock — 文件锁管理</summary>

| action | 用途 | 关键参数 |
|--------|------|---------|
| `acquire` | 获取文件锁（支持等待） | file_path, task_id?, subtask_id?, wait_ms?, retry_interval_ms? |
| `release` | 释放文件锁 | file_path, task_id? |
| `status` | 查询锁状态 | file_path |
| `release_all` | 释放任务的所有锁 | task_id? |

</details>

<details>
<summary>harness_session — 会话和系统信息</summary>

| action | 用途 | 关键参数 |
|--------|------|---------|
| `config` | 获取当前配置 | 无 |
| `session` | 获取会话信息 | 无 |
| `branches` | 列出所有 harness 分支 | 无 |
| `cleanup` | 释放所有锁并清理 | 无 |
| `sessions` | 列出所有会话 | 无 |
| `tasks` | 列出任务摘要 | 无 |
| `learnings` | 列出学习记录 | 无 |
| `memory` | 获取所有记忆 | 无 |
| `set_memory` | 设置记忆值 | key, value |
| `add_learning` | 添加学习记录 | learning_type, description, tags? |

</details>

## 工作流

### 自动生命周期

```
opencode 启动 → event hook 初始化 SessionContext
  │
  ├─ 简单消息 → 直接回复，不创建任务
  │
  └─ 复杂目标 → harness_task start 创建 HarnessTask
        ├─ 拆分为 SubTask（最小原子操作）
        ├─ harness_plan 生成执行计划（拓扑排序 + 并行分组）
        │     └─ 检测并行 + 文件重叠 → parallel: true
        ├─ 按并行组调度 executor
        │     ├─ 只读任务：不创建分支，不获取锁
        │     ├─ 写入任务（parallel=false）：创建分支，直接写入
        │     └─ 写入任务（parallel=true）：创建分支 + 获取锁
        ├─ subtask_done → 提交到主任务分支，释放锁
        └─ verify → complete → 等待用户确认合并/丢弃
```

### 手动模式

```
harness_task start     → 创建主任务 + 合同
harness_task subtask   → 注册子任务
harness_plan           → 生成执行计划（自动设置 parallel 标记）
harness_task subtask_start  → 开始子任务
@executor 执行         → tool-guard 拦截（仅 parallel=true 时检查锁）
harness_task subtask_done   → 完成子任务
harness_task verify    → 验证
harness_task complete  → 等待用户确认
```

## 设计细节

<details>
<summary>Git 分支结构</summary>

```
main
└── harness/{task_id}         # 主任务分支（第一个写入子任务时创建）
    └── 子任务更改直接提交到主任务分支
```

- 主任务分支在第一个需要文件修改的子任务出现时自动创建
- 只读子任务不创建分支、不获取写锁
- 写入子任务成功后将 `target_files` 提交到主任务分支，然后清理子分支
- `complete` 只保留元数据，**必须由用户手动确认合并或丢弃**

</details>

<details>
<summary>文件锁 & 多任务并发</summary>

**智能锁策略**：仅在并行任务修改相同文件时启用锁

| 场景 | parallel=false（默认） | parallel=true |
|------|----------------------|---------------|
| read | 直接读取 | 检查锁 |
| edit/write | 合约检查 → 直接写入 | 合约检查 → 获取锁 → 写入 |
| bash | 合约检查 | 合约检查 |

**锁机制**：
- 锁标识：`task_id + subtask_id`；同标识重入，不同标识冲突
- 锁 TTL：默认 10 分钟（`lock_timeout_minutes`），过期自动释放
- 锁等待：最多 30 秒，每 100ms 重试
- 孤儿锁：超过 24 小时自动清理

</details>

<details>
<summary>异常恢复</summary>

| 场景 | 行为 |
|------|------|
| opencode 异常退出 | 释放锁，保留分支和任务元数据 |
| 进程被 kill | 重启后旧 task 标记为 `failed`，孤儿锁自动清理 |
| 删除 `.agent_harness/` | 下次调用自动重建 |
| 子任务失败 | 丢弃子分支，可重试 |

</details>

<details>
<summary>数据存储</summary>

```
~/.config/agent_harness/
├── context.json                  # 全局上下文（会话、任务、学习记录、记忆）
└── sessions/{sessionId}/
    └── session.log               # 会话日志

<project>/.agent_harness/
├── config.jsonc                  # 项目配置
├── state/tasks.json              # 任务注册表
├── state/task-results/           # 子任务执行结果
├── contracts/                    # 合同存储
├── locks/                        # 文件锁
└── cache/branches/               # 非 Git 项目缓存
```

</details>

## 开发

```bash
npm run build          # tsc 编译
npm run dev            # tsc --watch 监听模式
npm test               # vitest run
```

### 添加新平台支持

1. 创建 `extensions/new-platform/`
2. 实现 2-3 个文件：`index.ts`, `hooks.ts`, 可选 `tools.ts`
3. 核心逻辑零改动

## 参与贡献

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/my-feature`
3. 提交更改：`git commit -m "feat: add my feature"`
4. 推送分支：`git push origin feature/my-feature`
5. 提交 Pull Request

请确保 `npm run build` 和 `npm test` 通过后再提交。

## 许可证

本项目采用 [MIT 许可证](LICENSE)。