{"id":47173591,"url":"https://github.com/wangdahoo/agent-harness","last_synced_at":"2026-04-03T19:02:17.484Z","repository":{"id":342260608,"uuid":"1173416316","full_name":"wangdahoo/agent-harness","owner":"wangdahoo","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-26T16:48:54.000Z","size":52,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T06:24:16.364Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wangdahoo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T10:44:05.000Z","updated_at":"2026-03-26T16:40:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wangdahoo/agent-harness","commit_stats":null,"previous_names":["wangdahoo/agent-harness"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wangdahoo/agent-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wangdahoo%2Fagent-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wangdahoo%2Fagent-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wangdahoo%2Fagent-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wangdahoo%2Fagent-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wangdahoo","download_url":"https://codeload.github.com/wangdahoo/agent-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wangdahoo%2Fagent-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31371647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-13T06:32:45.381Z","updated_at":"2026-04-03T19:02:17.462Z","avatar_url":"https://github.com/wangdahoo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Harness\n\n**Agent Harness** 是一个用于管理长期 AI 项目的 Claude Skill，使 Claude 能够跨多个上下文窗口执行复杂的多会话项目。基于 Sprint-Coding Agent 循环模式，确保代码质量和进度可追溯。\n\n## 核心特性\n\n- **跨上下文持续** - 通过结构化文件在上下文重置后保持项目状态\n- **双 Agent 协作** - Sprint Agent 规划，Coding Agent 实现\n- **进度可追溯** - 每个会话的详细日志和功能状态跟踪\n- **质量保证** - 每个会话结束时代码必须可工作\n- **依赖管理** - 自动处理功能依赖关系和实现顺序\n- **斜杠命令** - 支持简洁的命令快速访问核心功能\n\n## 安装\n\n```bash\nnpx skills install wangdahoo/agent-harness\n```\n\n## 兼容性\n\nAgent Harness 支持多种 AI CLI 工具：\n\n| CLI | 命令格式 | 配置目录 |\n|-----|----------|----------|\n| **OpenCode** | `/agent-harness-init` | `.opencode/commands/` |\n| **Claude Code** | `/agent-harness init` | `.claude/skills/` |\n\n两种 CLI 的功能完全相同，只是命令格式略有不同。\n\n## 快速开始\n\n### 1. 初始化项目\n\n**OpenCode:**\n```\n/agent-harness-init My Project\n```\n\n**Claude Code:**\n```\n/agent-harness init My Project\n```\n\n这将创建：\n- `features.json` - 功能和 Sprint 跟踪\n- `progress.md` - 会话日志\n\n### 2. 规划 Sprint\n\n**OpenCode:**\n```\n/agent-harness-sprint 实现用户认证系统，包括邮箱登录、社交登录和密码重置\n```\n\n**Claude Code:**\n```\n/agent-harness sprint 实现用户认证系统，包括邮箱登录、社交登录和密码重置\n```\n\nSprint Agent 会：\n1. 归档已完成的 Sprint（如果有）\n2. 分析需求并拆分为原子功能\n3. 为每个功能定义验收标准\n4. 按依赖关系排序\n5. 更新 `features.json` 和 `progress.md`\n\n### 3. 开始编码\n\n**OpenCode:**\n```\n/agent-harness-code\n```\n\n**Claude Code:**\n```\n/agent-harness code\n```\n\nCoding Agent 会：\n1. 查看 `progress.md` 和 `features.json`\n2. 选择下一个待实现的功能\n3. 实现并测试\n4. 更新跟踪文件\n5. 提交代码\n\n### 4. 查看状态\n\n**OpenCode:**\n```\n/agent-harness-status\n```\n\n**Claude Code:**\n```\n/agent-harness status\n```\n\n显示：\n- 当前 Sprint 和目标\n- 功能完成统计\n- 下一个推荐功能\n- 最近的会话记录\n\n## 斜杠命令\n\n输入 `/agent-harness` 可查看帮助信息。所有命令支持自动补全。\n\n### OpenCode 格式\n\n| 命令 | 用途 | 示例 |\n|------|------|------|\n| `/agent-harness` | 显示帮助信息 | `/agent-harness` |\n| `/agent-harness-init \u003cname\u003e` | 初始化新项目 | `/agent-harness-init Task Manager` |\n| `/agent-harness-sprint [req]` | 创建或更新 Sprint | `/agent-harness-sprint 添加用户仪表板` |\n| `/agent-harness-code` | 开始编码会话 | `/agent-harness-code` |\n| `/agent-harness-status` | 查看项目状态 | `/agent-harness-status` |\n| `/agent-harness-archive` | 归档完成的 Sprint | `/agent-harness-archive` |\n| `/agent-harness-force-archive` | 强制归档所有 Sprint | `/agent-harness-force-archive` |\n\n### Claude Code 格式\n\n| 命令 | 用途 | 示例 |\n|------|------|------|\n| `/agent-harness` | 显示帮助信息 | `/agent-harness` |\n| `/agent-harness init \u003cname\u003e` | 初始化新项目 | `/agent-harness init Task Manager` |\n| `/agent-harness sprint [req]` | 创建或更新 Sprint | `/agent-harness sprint 添加用户仪表板` |\n| `/agent-harness code` | 开始编码会话 | `/agent-harness code` |\n| `/agent-harness status` | 查看项目状态 | `/agent-harness status` |\n| `/agent-harness archive` | 归档完成的 Sprint | `/agent-harness archive` |\n| `/agent-harness force-archive` | 强制归档所有 Sprint | `/agent-harness force-archive` |\n\n## 核心概念\n\n### Sprint Agent（规划）\n\n**触发时机：**\n- 新项目初始化\n- 新 Sprint 迭代\n- 需求更新\n\n**职责：**\n1. 分析用户需求\n2. 拆分为原子功能（每个会话可完成）\n3. 定义清晰的验收标准\n4. 按依赖关系排序功能\n5. 文档化到 `features.json`\n\n### Coding Agent（实现）\n\n**触发时机：**\n- 每个开发会话\n\n**会话协议：**\n\n**开始阶段：**\n1. 确认工作目录 (`pwd`)\n2. 查看最近工作 (`progress.md`)\n3. 检查提交历史 (`git log`)\n4. 验证项目状态（lint/build）\n\n**工作阶段：**\n1. 选择 **一个** 功能\n2. 理解验收标准\n3. 增量实现\n4. 彻底测试\n\n**结束阶段：**\n1. 更新 `progress.md`\n2. 更新 `features.json` 状态\n3. 确保无错误\n4. 提交更改\n\n## 工作流程\n\n```\n用户需求\n    ↓\n┌─────────────────┐\n│  Sprint Agent   │ ← 拆分需求为功能\n└────────┬────────┘\n         │\n         ↓\n   features.json   ← 功能定义和状态\n         │\n         ↓\n┌─────────────────┐\n│  Coding Agent   │ ← 实现一个功能\n└────────┬────────┘\n         │\n         ↓\n   可工作的代码\n         │\n         ├─→ 更新 progress.md\n         ├─→ 更新 features.json\n         └─→ 提交更改\n         \n    (循环直到 Sprint 完成)\n```\n\n## 文件结构\n\n### 核心跟踪文件\n\n| 文件 | 用途 | 谁更新 |\n|------|------|--------|\n| `features.json` | Sprint 和功能定义 | Sprint Agent 创建，Coding Agent 更新状态 |\n| `progress.md` | 会话日志 | 所有 Agent |\n| `AGENTS.md` | 项目特定指令 | 用户 |\n\n### features.json 结构\n\n```json\n{\n  \"project\": {\n    \"name\": \"Project Name\",\n    \"description\": \"Project description\",\n    \"tech_stack\": [\"react\", \"node.js\"],\n    \"created_at\": \"2024-01-15\"\n  },\n  \"sprints\": [\n    {\n      \"id\": \"sprint-001\",\n      \"name\": \"Authentication Sprint\",\n      \"goal\": \"Implement user authentication\",\n      \"status\": \"in_progress\",\n      \"created_at\": \"2024-01-15\",\n      \"features\": [\n        {\n          \"id\": \"s1-feat-001\",\n          \"category\": \"auth\",\n          \"priority\": \"high\",\n          \"title\": \"Setup authentication provider\",\n          \"description\": \"Configure auth provider with proper credentials\",\n          \"acceptance_criteria\": [\n            \"Auth provider is configured\",\n            \"Environment variables are set\",\n            \"Connection can be established\"\n          ],\n          \"technical_notes\": \"Use Auth0 or custom JWT\",\n          \"status\": \"completed\",\n          \"dependencies\": [],\n          \"estimated_complexity\": \"small\",\n          \"files_affected\": [\"config/auth.ts\", \".env\"]\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"version\": \"1.0.0\",\n    \"last_updated\": \"2024-01-16\"\n  }\n}\n```\n\n### 功能字段说明\n\n- **id**: 唯一标识符 (如 `s1-feat-001`)\n- **category**: 功能类型 (`core`, `ui`, `api`, `auth`, `data`, `infra`)\n- **priority**: 优先级 (`high`, `medium`, `low`)\n- **status**: 状态 (`pending`, `in_progress`, `completed`, `blocked`)\n- **dependencies**: 依赖的功能 ID 数组\n- **estimated_complexity**: 复杂度估计 (`small` \u003c 2h, `medium` 2-4h, `large` \u003e 4h)\n- **files_affected**: 将被修改的文件路径\n\n### 状态值\n\n**功能状态：**\n- `pending` - 未开始\n- `in_progress` - 正在进行\n- `completed` - 完全实现并测试\n- `blocked` - 被阻塞\n\n**Sprint 状态：**\n- `planning` - 正在定义\n- `in_progress` - 功能正在实现\n- `completed` - 所有功能完成\n- `on_hold` - 暂时暂停\n\n## 内部脚本（供 slash 命令调用）\n\n以下脚本由 slash 命令内部调用，用户无需直接使用。了解这些脚本有助于理解系统工作原理。\n\n### init_project.py\n\n由 `/agent-harness-init` 调用，初始化项目跟踪文件。\n\n```bash\npython3 scripts/init_project.py \u003cname\u003e [-d description] [-o output-dir]\n```\n\n**选项：**\n- `-d, --description` - 项目描述\n- `-o, --output-dir` - 输出目录（默认当前目录）\n\n### status.py\n\n由 `/agent-harness-status` 调用，显示当前项目状态。\n\n```bash\npython3 scripts/status.py\n```\n\n### validate_structure.py\n\n由 Sprint Agent 和 Coding Agent 内部调用，验证 `features.json` 结构。\n\n```bash\npython3 scripts/validate_structure.py\n```\n\n检查：\n- 必需字段存在\n- 有效的状态值\n- 正确的 JSON 结构\n- 功能 ID 唯一性\n\n### archive_sprint.py\n\n由 `/agent-harness-archive` 和 `/agent-harness-force-archive` 调用，归档 Sprint。\n\n```bash\npython3 scripts/archive_sprint.py [--list] [--dry-run] [--force]\n```\n\n**选项：**\n- `--list` - 列出已完成的 Sprint\n- `--dry-run` - 预览归档操作\n- `--force` - 强制归档所有 Sprint（包括未完成的）\n- `--project-dir` - 项目目录（默认当前目录）\n\n归档后的 Sprint 移动到 `.agent-harness/archived/` 目录。\n\n## 设计原理\n\n### 为什么需要 Agent Harness？\n\n**问题：**\n1. **上下文限制** - Claude 的上下文窗口有限，无法在单个会话中处理大型项目\n2. **状态丢失** - 上下文重置后，之前的讨论和决策会丢失\n3. **质量保证** - 多会话项目容易产生不稳定的代码\n4. **进度追踪** - 难以了解项目的整体进度和下一步\n\n**解决方案：**\n1. **结构化文件** - 用 `features.json` 和 `progress.md` 持久化项目状态\n2. **双 Agent 模式** - Sprint Agent 专注规划，Coding Agent 专注实现\n3. **单功能会话** - 每个会话只实现一个功能，确保质量和焦点\n4. **强制协议** - 开始和结束会话的固定流程，确保一致性\n\n### 渐进式加载\n\nAgent Harness 使用三级加载系统：\n\n1. **元数据** - 始终在上下文中（~100 词）\n2. **SKILL.md 主体** - Skill 触发时加载（~150 行）\n3. **References** - 按需加载\n   - Sprint Agent 加载 `sprint-agent.md`\n   - Coding Agent 加载 `coding-agent.md`\n   - 示例按需从 `examples.md` 加载\n\n这确保了每个 Agent 只看到相关内容，最小化上下文占用。\n\n### Sprint-Coding 循环\n\n```\nSprint Agent        →  创建/更新 Sprint\n    ↓\nfeatures.json       →  功能定义和状态\n    ↓\nCoding Agent (会话 1)  →  实现功能 1\n    ↓\nCoding Agent (会话 2)  →  实现功能 2\n    ↓\nCoding Agent (会话 N)  →  实现功能 N\n    ↓\nSprint Agent        →  创建下一个 Sprint 或归档\n```\n\n这个循环确保：\n- 每次只处理一个功能，降低复杂度\n- 每个会话都留下可工作的代码\n- 进度可追溯，决策有记录\n\n## 关键规则\n\n1. **每个会话一个功能** - 不要试图做太多\n2. **始终留下可工作的代码** - 永远不要破坏构建\n3. **端到端测试** - 像用户一样验证\n4. **频繁提交** - 小提交支持回滚\n5. **永不删除功能** - 只更改状态\n6. **使用进度日志** - 记录每个会话\n\n## 最佳实践\n\n### Sprint Agent\n\n- 将大功能拆分为原子片段\n- 定义清晰的验收标准（Given-When-Then 格式）\n- 仔细考虑依赖关系\n- 平衡 Sprint 的复杂度组合\n- 文档化决策和优先级理由\n\n### Coding Agent\n\n- 严格遵循会话协议\n- 完成前测试\n- 使用清晰的消息频繁提交\n- 专注于一个功能\n- 遵循项目约定（见 `AGENTS.md`）\n\n### 项目组织\n\n- 每个项目维护自己的 `features.json` 和 `progress.md`\n- 使用 `AGENTS.md` 定义项目特定约定\n- 定期归档已完成的 Sprint\n- 在 `features.json` 中包含实际的技术栈\n\n## 常见场景\n\n### 场景 1：启动新项目\n\n**OpenCode:**\n```\n用户: /agent-harness-init Task Manager\nClaude: [创建 features.json 和 progress.md]\n\n用户: /agent-harness-sprint 构建任务管理应用，支持创建、编辑、删除任务，以及标签分类\nClaude: [分析需求 → 拆分为 8 个功能 → 更新 features.json]\n\n用户: /agent-harness-code\nClaude: [实现第一个功能 → 更新进度 → 提交]\n```\n\n**Claude Code:**\n```\n用户: /agent-harness init Task Manager\nClaude: [创建 features.json 和 progress.md]\n\n用户: /agent-harness sprint 构建任务管理应用，支持创建、编辑、删除任务，以及标签分类\nClaude: [分析需求 → 拆分为 8 个功能 → 更新 features.json]\n\n用户: /agent-harness code\nClaude: [实现第一个功能 → 更新进度 → 提交]\n```\n\n### 场景 2：继续现有项目\n\n**OpenCode:**\n```\n用户: /agent-harness-status\nClaude: [显示 Sprint 1 进行中，3/8 功能完成，下一个: s1-feat-004]\n\n用户: /agent-harness-code\nClaude: [查看进度 → 选择 s1-feat-004 → 实现 → 提交]\n```\n\n**Claude Code:**\n```\n用户: /agent-harness status\nClaude: [显示 Sprint 1 进行中，3/8 功能完成，下一个: s1-feat-004]\n\n用户: /agent-harness code\nClaude: [查看进度 → 选择 s1-feat-004 → 实现 → 提交]\n```\n\n### 场景 3：处理阻塞\n\n**OpenCode:**\n```\n用户: /agent-harness-status\nClaude: [显示 s1-feat-005 被阻塞: 等待第三方 API 密钥]\n\n用户: 先跳过这个，实现下一个\nClaude: [选择 s1-feat-006 (无依赖) → 实现 → 提交]\n```\n\n**Claude Code:**\n```\n用户: /agent-harness status\nClaude: [显示 s1-feat-005 被阻塞: 等待第三方 API 密钥]\n\n用户: 先跳过这个，实现下一个\nClaude: [选择 s1-feat-006 (无依赖) → 实现 → 提交]\n```\n\n### 场景 4：归档完成的 Sprint\n\n**OpenCode:**\n```\n用户: /agent-harness-archive\nClaude: [列出完成的 Sprint 1]\n用户: 确认\nClaude: [归档到 .agent-harness/archived/ → 清理 features.json]\n```\n\n**Claude Code:**\n```\n用户: /agent-harness archive\nClaude: [列出完成的 Sprint 1]\n用户: 确认\nClaude: [归档到 .agent-harness/archived/ → 清理 features.json]\n```\n\n### 场景 5：强制归档所有 Sprint\n\n当你需要重置项目或清理所有 Sprint 时：\n\n**OpenCode:**\n```\n用户: /agent-harness-force-archive\nClaude: [列出所有 3 个 Sprint，包括未完成的]\n用户: 确认强制归档\nClaude: [归档所有 Sprint 到 .agent-harness/archived/ → 清空 features.json 的 sprints]\n```\n\n**Claude Code:**\n```\n用户: /agent-harness force-archive\nClaude: [列出所有 3 个 Sprint，包括未完成的]\n用户: 确认强制归档\nClaude: [归档所有 Sprint 到 .agent-harness/archived/ → 清空 features.json 的 sprints]\n```\n\n**注意：** 这将归档所有 Sprint，不管它们的状态如何（包括 in_progress、planning、blocked 等）。\n\n### 场景 6：强制归档所有 Sprint\n\n当你需要清空当前项目状态，开始全新的规划时使用。\n\n**OpenCode:**\n```\n用户: /agent-harness-force-archive\nClaude: [警告：将归档所有 Sprint，包括未完成的]\n用户: 确认，我要开始新项目\nClaude: [归档所有 Sprint → 清空 features.json 中的 sprints → 保留 project 信息]\n```\n\n**Claude Code:**\n```\n用户: /agent-harness force-archive\nClaude: [警告：将归档所有 Sprint，包括未完成的]\n用户: 确认，我要开始新项目\nClaude: [归档所有 Sprint → 清空 features.json 中的 sprints → 保留 project 信息]\n```\n\n**使用场景：**\n- 项目方向完全改变\n- 需要重新规划整个项目\n- 清理旧的无用 Sprint\n\n**注意：** 归档的数据不会丢失，都保存在 `.agent-harness/archived/` 中。\n\n## 故障排除\n\n### 构建损坏\n\n1. 检查最近的提交\n2. 查看 `progress.md` 中的更改\n3. 修复错误\n4. 用 lint/build 验证\n\n### 功能太大\n\n1. Sprint Agent 将其拆分为更小的功能\n2. 每个成为独立的功能\n3. 如需要，标记依赖关系\n\n### 上下文丢失\n\n1. 读取 `progress.md` - 最近会话\n2. 读取 `features.json` - 当前状态\n3. 读取 `AGENTS.md` - 项目约定\n4. 检查 git log - 最近更改\n\n### 验证失败\n\nSprint Agent 和 Coding Agent 会自动验证 `features.json` 结构。如果需要手动检查：\n\n1. 使用 slash 命令触发验证（agent 会自动调用）\n2. 查看错误消息\n3. 修复 `features.json` 中的问题\n4. 重新运行相关命令\n\n## 参考\n\n- **[SKILL.md](SKILL.md)** - Skill 定义和命令\n- **[references/sprint-agent.md](references/sprint-agent.md)** - Sprint Agent 工作流程和模式\n- **[references/coding-agent.md](references/coding-agent.md)** - Coding Agent 会话协议\n- **[references/examples.md](references/examples.md)** - 完整的示例\n\n## 技术要求\n\n- **Python 3.8+** - 脚本使用标准库，无外部依赖\n- **Git** - 用于版本控制和提交\n- **文本编辑器** - 用于查看/编辑跟踪文件\n\n## 许可\n\n此 skill 可自由用于 Claude AI 助手。\n\n## 贡献\n\n欢迎改进和扩展！核心设计原则：\n\n1. **无外部依赖** - 脚本必须仅使用 Python 标准库\n2. **向后兼容** - 更改不应破坏现有的 `features.json` 文件\n3. **清晰的错误消息** - 所有错误应该是可操作的\n4. **渐进式加载** - 按 Agent 角色组织参考文档\n\n## 致谢\n\n基于 Anthropic 关于长期运行 agent 的有效 harness 研究。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwangdahoo%2Fagent-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwangdahoo%2Fagent-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwangdahoo%2Fagent-harness/lists"}