EnjoyHarness 🚀

工业级 AI Agent「自动驾驶操作系统」

给 AI Agent 装上工业级「自动驾驶操作系统」，解决落地稳定性、可控性、可复用性核心痛点

享受自动驾驶

English | 中文文档

中文文档

🎯 项目简介

EnjoyHarness 是一个工业级 AI Agent 驾驶操作系统，通过 18 个核心技能skills实现稳定的、可控的、可复用的AI自动驾驶工程化能力。

本项目核心能力：

✅ 目标追踪防偏离（目标残差链接防止长时任务目标主键偏离）
✅ 自我进化持续改进（自我学习自我进化越用越聪明）
✅ 子代理完全隔离（subagent）
✅ 三层熔断机制（迭代级 + Token级 + 任务级）
✅ 纯文件驱动零依赖（Markdown + Shell 脚本）

🌟 核心特性

1. 纯文件驱动架构

最小依赖：核心状态和技能定义以 Git 仓库 + Markdown 文件保存
运行层脚本化：会话守护、tmux 交接、自动编排由 Shell 脚本驱动
跨平台通用：支持 macOS / Linux；在 Windows 上建议使用兼容终端或 WSL
可追溯性强：所有操作留痕到 .EnjoyHarness/EVENT_LOG.md

2. 强制入口机制

唯一启动入口：必须先执行 harness-init 初始化技能
双重保障：钩子自动触发 + 技能内部检查
跨平台安全：确保系统在任何环境下都能正确初始化

3. 三层熔断保障

┌─────────────────────────────────────────┐
│ 迭代级熔断：总迭代 ≥ 100次               │ ← 防止无限循环
├─────────────────────────────────────────┤
│ Token级熔断：单任务 > 10000 tokens       │ ← 控制成本
├─────────────────────────────────────────┤
│ 任务级熔断：同一任务失败 ≥ 3次           │ ← 防止错误扩散
└─────────────────────────────────────────┘

4. 去中心化技能联动

文件驱动：技能通过读写文件实现联动，无中心调度器
事件总线：.EnjoyHarness/EVENT_LOG.md 作为事件传递通道
脚本编排层：守护进程和 tmux 负责会话切换与事件消费

5. 目录约定

目录策略详见 docs/DIRECTORY_POLICY.md
不要随便在仓库根目录创建新目录，新内容优先放入已有标准目录
临时内容统一放到 temp/
备份内容统一放到 backup/
正式测试内容统一放到 tests/
临时测试素材如确实需要可放到 test/
文档内容统一放到 docs/
根目录只保留正式入口和已经约定的顶层目录，例如 skills/、scripts/、docs/、tests/、test/

📦 18个核心技能

EnjoyHarness 包含 18 个核心技能，分为 6 个层次：

📋 点击展开查看所有技能详情

🔹 核心基础层（4个）

技能名	描述	前置依赖
harness-init	全局初始化（强制入口）	无
harness-build-core-manifest	构建核心规则清单（≤60行）	harness-init
harness-build-context-index	构建上下文索引（4级优先级）	harness-build-core-manifest
harness-enforce-architecture-guardrails	架构护栏（强制约束）	harness-build-core-manifest

🔹 调度执行层（5个）

技能名	描述	前置依赖
harness-build-deterministic-workflow	构建确定性工作流	harness-build-context-index
harness-spawn-subharness-agent	生成子代理（完全隔离）	harness-build-deterministic-workflow
harness-monitor-subharness-agent	监控子代理状态	harness-spawn-subharness-agent
harness-merge-subharness-result	合并子代理结果	harness-monitor-subharness-agent
harness-enable-circuit-breaker	熔断机制（含执行追踪）	harness-init

🔹 验证优化层（4个）

技能名	描述	前置依赖
harness-validate-output	输出校验（对照架构规则）	harness-enforce-architecture-guardrails
harness-diagnose-and-improve	错误诊断与规则反哺	harness-enable-circuit-breaker
harness-evaluate-performance	效果量化评估	harness-merge-subharness-result
harness-evolve	自我进化（含技术债清理+迭代飞轮）	harness-diagnose-and-improve

🔹 目标追踪层（1个）

技能名	描述	前置依赖
harness-goal	目标追踪	harness-init

🔹 兜底层（2个）

技能名	描述	前置依赖
harness-handle-failure	失败处理（含自动回滚）	harness-enable-circuit-breaker
harness-escalate-to-human	人工转交	harness-handle-failure

🔹 开发流程层（2个）

技能名	描述	前置依赖
harness-brainstorm	头脑风暴	harness-init
harness-plan	计划编写	harness-brainstorm

📦 安装

⚠️ 重要说明：

Claude Code 用户：推荐使用"插件市场安装"或"快速安装"方式，自动初始化系统

Cursor/OpenCode 用户：请使用下方对应平台的安装脚本，手动安装 Skill 文件

所有平台的核心功能完全一致，仅自动守护进程功能有差异

方式一：插件市场安装（最推荐）

Claude Code 用户（通过插件市场）

# 1. 添加 EnjoyHarness 插件市场
claude plugin marketplace add konglong87/enjoy_harness

# 2. 安装 EnjoyHarness 插件
claude plugin install enjoy_harness@enjoy_harness

# 3. 验证安装
claude plugin list

# 4. 初始化系统（在 Claude Code 中输入）
harness-init

插件市场安装的优势：

✅ 一键安装，无需手动克隆仓库
✅ 自动更新，保持最新版本
✅ 依赖自动管理
✅ 完整的Hook支持和自动守护进程

方式二：快速安装（推荐）

Claude Code 用户（本地克隆）

# 1. 克隆仓库
git clone https://github.com/konglong87/enjoy_harness.git
cd enjoy_harness

# 2. 执行初始化
# 在 Claude Code 中输入：harness-init

# 3. 验证安装
ls -la .EnjoyHarness/
# 应看到：GLOBAL_STATE.md, EVENT_LOG.md, ITERATION_COUNTER.md, SKILL_REGISTRY.md

Cursor 用户

Cursor 使用 .cursor/rules 目录存放全局规则，SKILL.md 格式完全兼容。

一键安装所有技能：

#!/bin/bash
SKILLS=(
  "harness-init"
  "harness-build-core-manifest"
  "harness-build-context-index"
  "harness-enforce-architecture-guardrails"
  "harness-build-deterministic-workflow"
  "harness-spawn-subharness-agent"
  "harness-monitor-subharness-agent"
  "harness-merge-subharness-result"
  "harness-enable-circuit-breaker"
  "harness-validate-output"
  "harness-diagnose-and-improve"
  "harness-evaluate-performance"
  "harness-evolve"
  "harness-goal"
  "harness-handle-failure"
  "harness-escalate-to-human"
  "harness-brainstorm"
  "harness-plan"
)

BASE_URL="https://raw.githubusercontent.com/konglong87/enjoy_harness/main/skills"

mkdir -p ~/.cursor/rules

for skill in "${SKILLS[@]}"; do
  echo "Installing $skill..."
  curl -fsSL "$BASE_URL/$skill/SKILL.md" -o ~/.cursor/rules/$skill.md
done

echo "✅ All EnjoyHarness skills installed!"

验证安装：

ls -la ~/.cursor/rules/
# 应看到所有 harness-*.md 文件

OpenCode 用户

OpenCode 支持全局 skills 安装，将 SKILL.md 文件放置到 ~/.opencode/skills/ 目录即可。

一键安装所有技能：

#!/bin/bash
SKILLS=(
  "harness-init"
  "harness-build-core-manifest"
  "harness-build-context-index"
  "harness-enforce-architecture-guardrails"
  "harness-build-deterministic-workflow"
  "harness-spawn-subharness-agent"
  "harness-monitor-subharness-agent"
  "harness-merge-subharness-result"
  "harness-enable-circuit-breaker"
  "harness-validate-output"
  "harness-diagnose-and-improve"
  "harness-evaluate-performance"
  "harness-evolve"
  "harness-goal"
  "harness-handle-failure"
  "harness-escalate-to-human"
  "harness-brainstorm"
  "harness-plan"
)

BASE_URL="https://raw.githubusercontent.com/konglong87/enjoy_harness/main/skills"

for skill in "${SKILLS[@]}"; do
  echo "Installing $skill..."
  mkdir -p ~/.opencode/skills/$skill
  curl -fsSL "$BASE_URL/$skill/SKILL.md" -o ~/.opencode/skills/$skill/SKILL.md
done

echo "✅ All EnjoyHarness skills installed!"

验证安装：

ls -la ~/.opencode/skills/
# 应看到所有 harness-* 目录

方式三：本地开发安装

适用于需要修改技能文档或参与开发的用户。

# 1. 克隆仓库
git clone https://github.com/konglong87/enjoy_harness.git
cd enjoy_harness

# 2. 在 Claude Code 中打开项目
claude .

# 3. 执行初始化
# 在 Claude Code 中输入：harness-init

# 4. 验证安装
ls -la .EnjoyHarness/

方式四：仅下载核心技能

如果只需要特定技能，可以单独下载：

# 创建技能目录
mkdir -p ~/.opencode/skills/harness-init

# 下载单个技能
curl -fsSL https://raw.githubusercontent.com/konglong87/enjoy_harness/main/skills/harness-init/SKILL.md \
  -o ~/.opencode/skills/harness-init/SKILL.md

🎯 开始使用

安装完成后，按照以下步骤开始使用：

步骤1：初始化系统

在 AI 工具中输入：

harness-init

系统将自动：

✅ 创建核心文件体系
✅ 初始化全局状态
✅ 注册所有技能
✅ 启动会话守护进程（自动防止上下文超载）

步骤2：验证初始化

ls -la .EnjoyHarness/
# 应看到：GLOBAL_STATE.md, EVENT_LOG.md, ITERATION_COUNTER.md, SKILL_REGISTRY.md

步骤3：选择使用模式

方式1: 自动执行全流程（推荐）

在 AI 工具中输入：harness-auto-full-execution
系统将自动执行完整流程
需求确认后默认进入无人值守执行

方式2: 单个技能使用

# 功能开发流程
在 AI 工具中输入：harness-brainstorm（设计）
在 AI 工具中输入：harness-plan（拆分任务）
在 AI 工具中输入：harness-executing-plans（执行任务）

补充说明：

harness-plan 默认自动选择推荐执行方式：Parallel Session
harness-executing-plans 默认自动恢复、自动重试、失败超阈值再恢复/诊断

📖 详细指导: 查看用户手册第2章了解更多启动方式

🔧 平台支持对比

平台	安装方式	Hook 支持	自动守护进程	核心功能
Claude Code	本地克隆	✅ 完整	✅ 完整	✅ 完整
Cursor	全局规则	❌ 无	❌ 无	✅ 完整
OpenCode	全局技能	❌ 无	❌ 无	✅ 完整
Codex	符号链接	❌ 无	❌ 无	✅ 完整

💡 推荐使用 Claude Code 以获得最佳体验

📁 文件结构

📂 点击展开查看完整文件结构

enjoy_harness/
├── EnjoyHarness_MANIFEST.md     # 全局唯一入口
├── AGENTS_MANIFEST.md           # 核心规则清单（≤60行）
│
├── .EnjoyHarness/               # 核心配置目录
│   ├── GLOBAL_STATE.md          # 全局状态
│   ├── EVENT_LOG.md             # 事件总线
│   ├── ITERATION_COUNTER.md     # 全局迭代计数器
│   ├── SKILL_REGISTRY.md        # 技能注册表
│   ├── CONTEXT_INDEX.md         # 上下文索引
│   ├── ARCHITECTURE_GUARDRAILS.md  # 架构护栏规则
│   ├── CODE_CHECKLIST.md        # 代码自检清单
│   ├── TOOLSET_SPEC.md          # 工具配置规范
│   ├── WORKFLOW_TEMPLATES.md    # 工作流模板库
│   ├── ERROR_HANDBOOK.md        # 错误处理手册
│   └── daemon.log               # 守护进程日志
│
├── skills/                      # 技能目录（纯 Markdown）
│   ├── harness-init/
│   │   └── SKILL.md
│   ├── harness-build-core-manifest/
│   │   └── SKILL.md
│   └── ... (其他16个技能)
│
├── scripts/                     # 守护进程脚本目录
│   ├── harness-daemon.sh        # 会话守护进程
│   ├── start-auto.sh            # 新项目统一自动入口
│   ├── start-daemon.sh          # 启动守护进程
│   ├── stop-daemon.sh           # 停止守护进程
│   └── daemon-status.sh         # 查看守护进程状态
│
├── .subharness/                 # 子代理隔离目录
│   └── {task-id}/
│       ├── SUBTASK_MANIFEST.md
│       ├── CONTEXT_INDEX.md
│       ├── EXECUTION_TRACE.md
│       ├── STATUS.md
│       └── WORK_TREE/
│
├── .trace/                      # 执行追踪目录
│   ├── GLOBAL_TRACE.md
│   ├── ERROR_TRACE.md
│   └── ARCHIVE/
│
└── .learnings/                  # 经验学习目录
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

🎓 使用场景

📖 详细使用指南: 查看用户手册第3章了解所有技能的详细使用方法

场景1：功能开发

用户输入：实现用户登录功能
系统执行：
harness-init
→ harness-goal（创建SMART目标）
→ harness-brainstorm（设计方案）
→ harness-plan（拆分为bite-sized任务）
→ harness-build-deterministic-workflow
→ harness-spawn-subharness-agent（生成多个子代理）
→ harness-validate-output（校验输出）
→ harness-merge-subharness-result（合并结果）
→ harness-evaluate-performance（评估效果）

场景2：Bug修复

用户输入：修复飞书API调用失败问题
系统执行：
harness-init
→ harness-goal（创建修复目标）
→ harness-diagnose-and-improve（诊断根因）
→ harness-spawn-subharness-agent（生成修复子代理）
→ harness-validate-output（验证修复）
→ harness-evolve（记录经验）

场景3：重构优化

用户输入：重构认证模块，降低复杂度30%
系统执行：
harness-init
→ harness-goal（创建重构目标）
→ harness-enforce-architecture-guardrails（检查架构约束）
→ harness-spawn-subharness-agent（生成重构子代理）
→ harness-validate-output（验证架构合规）
→ harness-evaluate-performance（评估复杂度改善）
→ harness-evolve（推广重构经验）

📊 性能优化

Token 消耗优化

确定性节点不调用LLM：降低 40% Token
精准上下文加载：P0-P3 优先级分层
子代理隔离：避免上下文污染
目标追踪：防止无效尝试
熔断机制：避免无限重试

预期效果

Token 消耗降低：≥40%
执行时长缩短：≥50%
人工介入次数：≤1次/任务

🔧 配置与扩展

自定义迭代限制

编辑 .EnjoyHarness/ITERATION_COUNTER.md：

---
max_iterations: 100 # 可根据需求调整
current_iteration: 0
---

启用/禁用技能

编辑 .EnjoyHarness/SKILL_REGISTRY.md：

harness-init: enabled
harness-evolve: enabled
# harness-brainstorm: disabled # 禁用特定技能

添加新技能

创建技能目录：skills/harness-{name}/
编写 SKILL.md（遵循模板）
注册到 .EnjoyHarness/SKILL_REGISTRY.md
测试技能独立性
测试技能联动

🧪 测试

单元测试

# 测试单个技能
# 在 Claude Code 中输入：harness-init

# 验证文件创建
ls -la .EnjoyHarness/

集成测试

# 测试技能联动
# 执行 harness-auto-full-execution
# 观察事件日志
cat .EnjoyHarness/EVENT_LOG.md

🤝 贡献指南

欢迎贡献！请遵循以下流程：

Fork 本仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'feat: add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

代码规范

技能文档遵循 SKILL.md 模板
文件命名遵循小写+连字符规则
提交信息遵循 Conventional Commits
所有操作必须留痕到 EVENT_LOG.md

📝 更新日志

[v3.1.0] - 2026-03-29

新增

完整的Skills安装指南（支持Claude Code、Cursor、OpenCode多平台）
平台支持对比表，清晰展示各平台功能差异
一键安装脚本，支持18个核心技能批量安装
自动会话交接系统文档（v3.1新增）

变更

重构README结构，从混乱变为清晰分层
安装章节前置，用户快速上手
技能详情折叠显示，减少初始阅读负担
文件结构折叠显示，核心内容更突出

[v3.0.0] - 2026-03-28

新增

采用 18 个技能实用方案（平衡原子性和精简性）
Markdown 技能文档 + Shell 运行层协同工作
三层熔断机制（迭代级 + Token级 + 任务级）
强制入口机制（harness-init）

变更

恢复核心基础层的原子技能（build-core-manifest, build-context-index）
恢复调度执行层的子代理独立技能（spawn, monitor, merge）
合理合并验证优化层技能（evolve含技术债清理+迭代飞轮）
保持兜底层技能独立性（handle-failure含自动回滚，escalate独立）
新增开发流程技能（brainstorm, plan）

优化

Token 消耗降低 ≥40%
执行时长缩短 ≥50%
人工介入次数 ≤1次/任务

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

所有开源项目和为此项目开源贡献的作者

📞 联系方式

作者: 恐龙🦖
Email: 2235998553@qq.com
项目地址: https://github.com/konglong87/enjoy_harness
文档: docs/
问题反馈: Issues

🆕 自动会话交接系统（v3.1新增）

📖 详细配置与管理: 查看守护进程脚本使用指南了解完整配置和管理方法

核心功能

EnjoyHarness 实现了完全自动化的会话交接机制，解决了长时间任务执行中上下文超载的核心问题：

执行任务（每2个任务检测）
↓
创建交接文件（剩余任务清单+上下文摘要+ACK 占位）
↓
守护进程自动检测
↓
通过 tmux 启动新会话
↓
新会话写入 ACK
↓
旧会话确认后退出
↓
归档交接文件到历史记录

关键特性

1. 零手动干预

✅ harness-init自动启动守护进程
✅ 任务执行自动检测计数
✅ 交接文件、ACK 与交接锁自动生成
✅ 新 tmux 会话自动启动
✅ 新会话自动写入 ACK
✅ 交接历史自动归档

2. 质量第一原则

每个交接文件都明确传递：

质量第一原则：宁可慢，不可乱。优先保证代码质量和系统稳定性，不追求速度而牺牲质量。

3. 完整历史记录

.EnjoyHarness/handoff_history/
├── NEXT_SESSION_PROMPT_20260328_214500.md
├── NEXT_SESSION_PROMPT_20260328_220000.md
└── ...

用户可以：

✅ 回溯每次交接的完整历史
✅ 查看任务清单变化
✅ 追踪重要决策演进
✅ 审计风险识别

当前运行时状态文件：

.EnjoyHarness/NEXT_SESSION_PROMPT.md
.EnjoyHarness/HANDOFF_ACK.md
.EnjoyHarness/HANDOFF_LOCK.md
.EnjoyHarness/TMUX_SESSION_STATE.md

4. 文件驱动架构

守护进程：纯Shell脚本，零编程依赖
交接文件：Markdown格式，人可读
历史归档：自动创建，永久保存
会话容器：tmux session 承载 Claude loop

使用方式

方式1：自动模式（推荐）

# 在AI工具中触发harness技能
> harness-init

# 系统会自动：
# 1. 初始化系统
# 2. 启动守护进程
# 3. 执行任务
# 4. 自动交接
# 5. 继续执行

方式2：手动启动守护进程（可选）

# 启动守护进程
./scripts/start-daemon.sh

# 查看状态
./scripts/daemon-status.sh

# 停止守护进程
./scripts/stop-daemon.sh

本地使用 `ccc` 直接触发自动交接

如果你的本地 Claude 启动命令是 ccc，把它写进 .EnjoyHarness/CONFIG.md：

claude_command: "ccc"
tasks_per_session: 2
user_name: ""
user_phone: ""
user_email: ""
brainstorm_user_participation: false
use_tmux_sessions: true
tmux_session_prefix: "eh-loop-local"
tmux_ack_timeout_seconds: 30
close_old_session_after_ack: true

如果你想让自动提交、AGENT.md 和 CLAUDE.md 里使用真实身份信息，填上：

user_name: "你的姓名"
user_phone: "你的手机号"
user_email: "你的邮箱"

留空时，初始化会优先回退到本机 git config user.name / git config user.email，user_phone 作为可选补充信息。

如果你希望“只有需求头脑风暴阶段允许用户参与，之后全部自动”，把它改成：

brainstorm_user_participation: true

规则是：

false 或不配置：保持现状，brainstorm 也全自动
true：只在 harness-brainstorm 阶段允许用户参与，一旦确认完成，后续全部恢复无人值守

如果是一个全新的项目，建议直接执行统一自动入口：

./scripts/start-auto.sh --root "$(pwd)"

这个入口会自动判断是否需要补齐前置动作，并按需依次执行：

git init
EnjoyHarness_MANIFEST.md
.EnjoyHarness/CONFIG.md
AGENT.md
CLAUDE.md
底层会按需自动调用 harness-bootstrap.sh
start-daemon.sh
tmux-handoff-manager.sh prepare
tmux-handoff-manager.sh launch
daemon-status.sh

如果你希望自动完成后直接进入 tmux 会话，可以再加上 --attach：

./scripts/start-auto.sh --root "$(pwd)" --attach

补充说明：

ccc 会通过 zsh 交互环境解析，所以建议保持它作为 claude_command 的值。
如果 user_name / user_email 为空，初始化会优先读取本机 git config 作为默认身份。
start-auto.sh 会先自动检测是否需要 bootstrap，再启动 harness-daemon.sh 和 harness-orchestrator.sh，最后按需拉起 tmux 会话。
start-daemon.sh 仍可单独使用，适合高级用户做局部排查。
如果当前已经在 tmux 里面，tmux-attach.sh 会自动切换到目标会话。
如果找不到当前会话，脚本会优先提示你运行 start-auto.sh。

自治执行验收测试

如果你想验证“需求确认后，无需用户继续参与，系统自动推进直到完成”，可以运行：

bash tests/test_full_autonomous_project.sh
bash tests/test_autonomous_mode_contract.sh

这个脚本会验证：

EXECUTION_CONTRACT.md 已锁定为 autonomous_after_confirmation
编排器能连续消费多轮下游事件
tmux handoff 会多次归档并恢复到 ACTIVE
最终写入 SUPER_SKILL_COMPLETE | harness-auto-full-execution | ... | SUCCESS
核心技能文档没有重新引入需求确认后的交互式阻塞项

方式3：查看历史记录

# 查看所有交接历史
ls -lt .EnjoyHarness/handoff_history/

# 查看最近一次交接
cat .EnjoyHarness/handoff_history/$(ls -t .EnjoyHarness/handoff_history/ | head -1)

# 统计执行进度
for file in .EnjoyHarness/handoff_history/*.md; do
  grep "remaining_tasks:" "$file"
done

配置参数

# 配置任务阈值（默认每2个任务切换会话）
export TASKS_PER_SESSION=2

# 或修改为其他值（如10个任务）
export TASKS_PER_SESSION=10

技术实现

组件	文件	说明
守护进程	`scripts/harness-daemon.sh`	每5秒检测交接文件
启动脚本	`scripts/start-daemon.sh`	一键启动守护进程
状态查看	`scripts/daemon-status.sh`	查看守护进程和会话状态
会话进入	`scripts/tmux-attach.sh`	一键进入当前 tmux 会话
兼容入口	`scripts/tmux-resume.sh`	`tmux-attach.sh` 的兼容别名
会话交接技能	`skills/harness-session-handoff/SKILL.md`	生成交接文件逻辑
自动启动	`skills/harness-init/SKILL.md`	自动启动守护进程

存储成本

每个交接文件：~10KB
每天10次交接：~100KB
保留30天：~3MB

结论：存储成本可忽略，历史价值巨大！

常见问题

Q: handoff_history目录不存在？

A: 这是正常的！目录会在第一次交接时自动创建。

Q: 如何查看交接日志？

A: tail -f .EnjoyHarness/daemon.log

Q: 交接文件会被删除吗？

A: 不会，所有交接文件都会归档到handoff_history/目录，永久保存。

📖 完整文档导航

📘 用户指导文档

1. 用户手册 - 完整使用指南

包含内容：

第1章: 系统概述 - EnjoyHarness简介、核心架构、文件驱动设计
第2章: 快速开始 - 环境准备、初始化、第一个任务
第3章: 技能使用 - 18个核心技能详细使用说明
第4章: 高级特性 - 自动会话交接、三层熔断、目标追踪
第5章: 故障排查 - 常见问题诊断与解决方案

2. 守护进程脚本使用指南