OpenSpec Long-Running Agent Harness

概述

整合 OpenSpec 规范与 Anthropic "Effective Harnesses for Long-Running Agents" 最佳实践，为跨多个 context window 的 Agent 任务提供：

状态持久化 - 通过 feature_list.json 和 session_state.json 跨会话保持进度
增量进展 - 每个 session 只处理一个 feature，明确记录进展
Gate Enforcement - 会话结束前必须验证：工作区干净、新 commit、E2E 通过
并行执行 - 支持 3-6 个独立子任务并发，依赖链串行

触发条件（必须命中）

满足任一条件就必须调用本技能：

用户使用 /opsx:apply 或 /openspec:apply 且项目存在 openspec/harness/ 目录
用户明确要求 "long-running" 或 "harness" 模式
用户提到 "跨会话"、"持久化状态"、"增量进展" 并涉及 OpenSpec 工作流
项目已初始化 OpenSpec 结构，需要实现多个 feature

核心文件结构

openspec/harness/
├── feature_list.json     # 功能清单（Feature 定义 + 状态）
├── progress.log.md       # 进度日志（结构化会话记录）
├── session_state.json    # 当前会话状态
└── init.sh               # 环境检查脚本

状态机

                    ┌─────────────────────────────────────┐
                    │                                     │
                    ▼                                     │
┌──────────┐   ┌───────────────┐   ┌──────────┐   ┌─────────────┐
│ pending  │──▶│ in_progress   │──▶│ verifying│──▶│  passing    │
└──────────┘   └───────────────┘   └──────────┘   └─────────────┘
     │                │                   │              │
     │                │                   │              │
     │                ▼                   ▼              │
     │          ┌───────────┐       ┌──────────┐        │
     └─────────▶│ blocked   │◀──────│  failed  │◀───────┘
                └───────────┘       └──────────┘

执行规则

会话开始例行（必须按序执行）

确认目录 - pwd 确认当前工作目录
读取进度 - 读取 progress.log.md 了解最近工作
选择任务 - 读取 feature_list.json 选择下一个任务
环境检查 - 运行 init.sh 验证环境
更新状态 - 更新 session_state.json

会话执行规则

单一 Feature - 每个 session 只处理一个 feature
并行粒度 - 支持 3-6 个独立子任务并发
依赖串行 - 有依赖关系的任务必须串行执行
只改状态 - 禁止修改 feature_list.json 的 feature 定义，只能修改 status
写冲突避免 - 并行任务不得修改同一文件重叠区域

会话结束例行（Gate Enforcement）

工作区检查 - git status 确认工作区干净
Commit 验证 - 确认存在新 commit（相对 session 开始）
E2E 验证 - 运行 E2E 测试，必须通过
状态更新 - 标记 feature 为 passing（如果 E2E 通过）
摘要写入 - 写会话摘要到 progress.log.md

标准流程

Phase 1: 初始化 Harness

# 如果项目没有 harness 结构，先初始化
./scripts/harness-init.sh <project-name>

创建：

openspec/harness/feature_list.json
openspec/harness/progress.log.md
openspec/harness/session_state.json
openspec/harness/init.sh

Phase 2: 启动会话

./scripts/harness-start.sh

执行：

运行 init.sh 检查环境
读取 progress.log.md 最近进度
调用 harness-pick-next.sh 选择任务
更新 session_state.json

Phase 3: 实现任务

按以下模式工作：

并行模式（3-6 个子任务）：

适用于：无依赖关系的独立任务
执行：同时启动多个 Sub Agent
汇总：统一收集结果，检查一致性

串行模式：

适用于：强依赖链 A → B → C
执行：按序完成，每步验证后再下一步

Phase 4: 结束会话

./scripts/harness-end.sh

执行：

运行 harness-verify-e2e.sh E2E 验证
检查 gate conditions
更新 feature 状态
写会话摘要

任务选择策略

harness-pick-next.sh 按以下优先级选择：

Priority: P1 > P2 > P3
Status: failed > in_progress > blocked > pending
依赖: 无阻塞的 feature 优先

输出模板

会话开始输出

## Session {N} Started - {date}

### Environment
- Directory: {pwd}
- Git Branch: {branch}
- Start Commit: {hash}

### Selected Task
- ID: {feature-id}
- Priority: {P1|P2|P3}
- Description: {description}
- Steps: {step count}

### Parallel Plan (3-6 tasks)
1. {Task A}: {goal} → {output}
2. {Task B}: {goal} → {output}
3. {Task C}: {goal} → {output}
...

会话结束输出

## Session {N} Ended - {date}

### Completed
- Feature: {id} - {description}
- Commits: {hash list}
- Duration: {time}

### Gate Results
- [x] Working tree clean
- [x] New commit created: {hash}
- [x] E2E verification passed

### Progress Log Updated
- Status: passing
- Files modified: {count}

### Next Steps
- Next feature: {id}
- Remaining: {count} features

并发执行指南

可并行的场景

不同文件的修改
不同模块的功能
独立的测试用例
并行的调研任务

必须串行的场景

同一文件的修改
有依赖关系（A 的输出是 B 的输入）
共享状态更新
最终合并提交

冲突处理

检测 - 分析任务文件边界
重排 - 按文件/模块边界重新划分任务
降级 - 无法避免冲突时改为串行

错误处理

E2E 验证失败

标记 feature 为 failed
记录失败原因到 progress.log.md
不提交 code，保持工作区状态供调试
下次 session 优先处理 failed feature

环境检查失败

记录问题到 progress.log.md
标记 feature 为 blocked
记录 blocked_reason
提示用户手动修复

依赖阻塞

标记为 blocked
记录依赖的 feature id
在依赖 feature 完成后自动解除

与 OpenSpec 命令集成

OpenSpec 命令	Harness 集成
`/opsx:new`	初始化 harness + 创建 `feature_list.json`
`/opsx:apply`	选择下一个 failing feature，启动实现
`/opsx:verify`	运行 E2E 验证，更新状态
`/opsx:archive`	验证所有 features passing，归档

最佳实践

小步提交 - 每个 feature 拆分为多个小 commit
频繁验证 - 每个 subtask 完成后局部验证
清晰记录 - progress.log.md 记录关键决策和问题
环境隔离 - init.sh 确保环境一致性
增量进展 - 宁可小步前进，不要大步跳跃

参考资源

Anthropic Article: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
OpenSpec Parallel Agents: ../openspec-parallel-agents/SKILL.md
Spec Kit Orchestrator: ../spec-kit-parallel-orchestrator/SKILL.md

openspec-long-running-harness