Claude Harness Skill 设计深度分析

撰写时间：2026-03-31 16:30 目的：为优化稳定运行提供参考

一、核心原理

1.1 Harness Engineering 理念

核心理念："Humans steer, agents execute" —— 人类掌舵，代理执行

为 AI 编程助手构建一套完整的控制系统：

缰绳（Harness）：限制 AI 的行动范围
护栏（Guardrails）：拦截危险操作
仪表盘（Dashboard）：实时监控进度
刹车系统（Intervention）：人工介入机制

1.2 五层架构设计

第一层：上下文知识 - 目标定义、里程碑规划、验收标准第二层：执行工具 - Shell 执行、文件操作、Git 提交第三层：护栏约束 - 边界校验、权限控制、危险操作拦截第四层：可观测性 - Trace 追踪、进度日志、状态快照第五层：持续清理 - 垃圾回收、代码熵治理、重构 PR

1.3 多 Agent 协同模式

用户目标 → Planner 分解 → 里程碑列表 → Coordinator 调度 → Executor 执行 → Supervisor 审查 → 完成/重做

二、当前 Skill 实现

2.1 模块清单

脚本	功能	状态
orchestrator.py	多 Agent 协调器	✅ 实现
guard.py	护栏检查器	✅ 实现
observability.py	可观测性系统	✅ 实现
intervention.py	人工介入系统	✅ 实现
delivery.py	测试交付系统	✅ 实现
auto_executor.py	自动执行器	⚠️ 问题较多
adversarial.py	对抗评审	✅ 实现
continuous.py	持续运行	✅ 实现

2.2 数据表设计（7 张表）

harness_tasks（任务主表）：id, name, status, progress, parent_task_id, priority, retry_count

harness_agents（Agent 记录表）：id, task_id, agent_type, status, output, token_used, duration_ms

harness_checkpoints（检查点表）：id, task_id, iteration, status_snapshot, files_modified

harness_events（事件日志表）：id, task_id, event_type, event_level, message

harness_milestones（里程碑表）：id, task_id, name, status, order_index

harness_reviews（评审记录表）：id, task_id, round_id, producer_output, critic_comments

harness_system_health（系统健康表）：id, check_time, module_name, status, details

三、与 Harness Engineering 的关系

3.1 理念对应

理论概念	Skill 实现	对应模块
缰绳	上下文约束	orchestrator.py
护栏	危险操作拦截	guard.py
仪表盘	状态追踪	observability.py
刹车	人工介入	intervention.py
验收	测试交付	delivery.py

3.2 实现差距

理论要求	当前状态	差距
真正执行	⚠️ 部分	AutoExecutor 假执行问题
状态同步	⚠️ 不稳定	数据库与实际不一致
持续监控	⚠️ 部分	巡检不够详细
对抗评审	✅ 实现	已有 adversarial.py
人工介入	✅ 实现	已有 intervention.py

四、OpenClaw 框架能力

4.1 sessions_spawn（子 Agent 启动）

参数：runtime（subagent/acp）、mode（run/session）、task、label、timeoutSeconds

关键发现：sessions_spawn 是异步的，需要 sessions_yield 等待结果推送

4.2 sessions_yield（等待结果）

用途：结束当前 turn，等待 subagent 推送结果

关键：没有 sessions_yield，主 session 会立即结束

4.3 Cron、A2A、Compaction

关键发现：当前 openclaw.json 中这些配置都是空对象，需要添加

五、确保稳定运行的设计要点

5.1 问题清单

#	问题	严重程度	状态
1	AutoExecutor 假执行	🔴 Critical	⚠️ 部分
2	不等待 sessions_yield	🔴 Critical	⚠️ 部分
3	数据库状态不同步	🟠 Major	⚠️ 不稳定
4	Cron 配置丢失	🟠 Major	❌ 待修复

5.2 关键设计原则

原则	说明
真执行	必须调用 sessions_spawn，不模拟
真等待	必须调用 sessions_yield，等待推送
双写验证	数据库 + 文件双写，两者一致才完成
检查点恢复	定期保存检查点，失败可恢复
状态同步	执行记录文件 → 数据库

5.3 标准执行流程

Step 1: 查询 MySQL → 找 pending 任务 Step 2: sessions_spawn → 启动 subagent Step 3: sessions_yield → 等待完成推送 Step 4: 检查执行记录文件 → 验证真正完成 Step 5: UPDATE MySQL → 更新状态 Step 6: 保存检查点 → 记录快照

六、优化建议

6.1 立即修复

优先级	问题	方案
P0	AutoExecutor 假执行	强制 sessions_spawn
P0	不等待结果	强制 sessions_yield
P1	数据库不同步	双写验证机制
P1	Cron 配置丢失	添加 cron 配置

6.2 建议添加的配置

harness-autoexecutor：每 10 分钟执行 harness-monitor：每 5 分钟监控 A2A：maxPingPongTurns: 5 Compaction：safeguard 模式

七、附录：Admin 项目执行链路

7.1 实际执行方式

任务	执行方式	Session Key
M3	手动 sessions_spawn	agent:main:subagent
M4	手动 sessions_spawn	agent:main:subagent:91817697
M5	手动 sessions_spawn	agent:main:subagent

7.2 AutoExecutor 报告 vs 实际

14:49 "模拟执行成功" → ❌ 假 14:53 "M4-1/M4-2 成功" → ❌ 假 15:03 "成功" → ❌ 假 15:13 "系统空闲" → ✅ 真（手动完成）

本文档供用户分析优化参考。

目录