long-running-harness

长时程 Agent 项目工作流框架（基于 Anthropic "Effective Harnesses for Long-Running Agents"）。 用于创建、管理和调度跨多个上下文窗口的长期项目任务。 Use when: 启动新项目、初始化项目工作流、管理项目任务列表、调度子Agent增量开发、 恢复项...

Security Scan

The skill's instructions are coherent with a long-running project harness, but the SKILL.md expects shell tools and running arbitrary project init scripts (which may install software or run network operations) while the skill declares no required binaries or environment access—this mismatch and the ability to execute repo-provided scripts merit caution.

Purpose & Capability

The name/description (long-running project harness) matches the actions in SKILL.md: creating project folders, reading/writing features.json and progress.md, selecting tasks, committing git changes, spawning child sessions, and optionally scheduling cron checks. However the instructions assume availability of system tools (git, bash, curl, npm, pip, python, pytest) and the ability to run project-provided init.sh and tests, yet the skill metadata lists no required binaries or environment requirements — an incoherence that should be addressed.

Instruction Scope

Instructions remain within the declared purpose (manage project state, run one feature per session, enforce tests, update files, git commit). But they explicitly direct the agent to run shell commands and any project-provided init.sh, which can execute arbitrary code, perform package installs, start services, and make network requests. That behavior is expected for a harness but expands the runtime authority significantly and should only be applied to trusted project repositories or sandboxed environments.

Install Mechanism

There is no install spec (instruction-only), which is low risk from the skill distribution perspective. However the provided init.sh templates instruct package installation (npm, pip) and starting services — these actions would download and run third-party code at runtime. The lack of an install step in the skill itself is consistent, but users should note that the skill will routinely execute repository scripts that may install software.

Credentials

The skill declares no required environment variables or credentials, which aligns with its general purpose. But practical execution often relies on system credentials (git remotes requiring git credentials, DB access, package registry/network access). The skill does not request or document these, so users must be aware the agent may attempt operations that implicitly depend on external credentials or network access.

Persistence & Privilege

always:false and normal autonomous invocation settings are used. The skill writes/commits to project directories (its intended scope) but does not request persistent system-wide privileges. The scheduling/cron example can make the agent run periodically, so users should control whether and how those schedules are created.

What to consider before installing

This skill appears to do what it says (manage long-running project tasks) but it will run shell commands and project-provided init.sh scripts that can install packages, start services, and execute arbitrary code. Things to consider before installing or using it: - Only run this on repositories/projects you trust. Review any init.sh, init_db.sh, package.json, requirements.txt, and test scripts before allowing the agent to execute them. - The skill assumes tools (git, bash, curl, npm, pip, python, pytest) are available but the metadata doesn't declare them — ensure your environment provides these or update the skill metadata to reflect requirements. - The agent will perform git commits; ensure your git credentials and remote configuration are what you expect, and don't let it commit secrets or credentials into repos. - If you need strong containment, run the harness in an isolated/sandboxed environment (container/VM) or deny network access so package installs cannot fetch remote code. - Be cautious with cron job scheduling — the skill includes an example for periodic checks; only enable scheduled runs when you have control over what the agent will execute autonomously. If you want to reduce risk: require explicit user confirmation before running any init.sh or performing installs, restrict which project paths the skill can act on, and add explicit declarations of required binaries and any expected external credentials.

长时程 Agent 工作流框架

基于 Anthropic 工程团队的 Effective Harnesses for Long-Running Agents 方法论，适配 OpenClaw 环境。

---

核心原则

1. 持久化优于记忆 — 用文件系统记录状态，不依赖 Agent 上下文记忆
2. 结构化优于自由文本 — 关键状态用 JSON，进度日志用 Markdown
3. 验证优于声明 — 每个功能完成后必须验证，不接受未测试的 "完成"
4. 增量优于大步 — 每次 Agent 会话只做一个功能点，保持可回滚
5. 标准化优于临时 — 固定的启动例程和结束例程，减少混乱

---

项目结构

每个受管理项目遵循以下标准结构：

projects/<project-name>/
├── PROJECT.md              # 项目概述、目标、技术栈
├── progress.md             # Agent 工作日志（每次会话追加）
├── features.json           # 功能列表（状态追踪，仅修改 passes 字段）
├── init.sh                 # 环境初始化脚本（可选）
├── src/                    # 项目源码
└── tests/                  # 测试代码（如有）

---

生命周期

阶段一：初始化（Init）

当用户要求启动新项目或初始化工作流时执行：

1. 创建项目目录 projects/<project-name>/
2. 编写 PROJECT.md — 包含：
   • 项目名称和目标
   • 技术栈和依赖
   • 验收标准
   • 关键约束
3. 编写 features.json — 功能列表，格式如下：

   {
     "project": "项目名称",
     "created": "2026-03-18",
     "features": [
       {
         "id": "feat-001",
         "name": "功能名称",
         "description": "功能详细描述",
         "category": "functional|infra|docs|perf|fix",
         "priority": "high|medium|low",
         "passes": false,
         "tests": [
           "测试步骤 1",
           "测试步骤 2"
         ],
         "notes": ""
       }
     ]
   }
   

4. 创建 progress.md — 模板：

   # 项目工作日志
   
   ## 初始化
   - 日期：2026-03-18
   - 初始化人：主 Agent
   - 功能总数：N
   

5. 初始化 git — git init + 首次提交
6. 如果适用，编写 init.sh

重要： 功能列表要尽量详尽，把大功能拆成小功能。200 个小功能 > 10 个大功能。

阶段二：增量开发（Each Session）

当用户说"继续开发"、"next feature"、"继续项目"或调度子Agent开发时：

启动例程（每个会话必须执行）：

1. pwd 确认工作目录
2. cat projects/<name>/progress.md — 读取工作日志
3. git log --oneline -10 — 查看最近提交
4. cat projects/<name>/features.json — 读取功能列表
5. 选择优先级最高且 passes: false 的功能
6. 运行 init.sh（如有）+ 基础验证测试
7. 确认环境正常后，开始实现

工作约束：

• 每次只做一个功能
• 实现完成后必须验证（运行测试、手动检查等）
• 验证通过后才能将 features.json 中对应功能的 passes 改为 true
• 禁止删除或修改功能条目（只改 passes 和 notes 字段）

结束例程（每个会话必须执行）：

1. 更新 features.json 中完成状态
2. 追加会话记录到 progress.md：

   ## 会话 N — 日期
   - **目标功能：** feat-XXX - 功能名称
   - **状态：** ✅ 完成 / ⏳ 部分完成 / ❌ 失败
   - **完成内容：** 具体做了什么
   - **遇到的问题：** 问题描述和解决方案
   - **下次继续：** 待办事项
   - **Git commits：** hash - message
   

3. git add . && git commit -m "feat: 完成功能描述"

阶段三：进度报告

当用户问"项目进度"、"project status"时：

1. 读取 features.json
2. 统计完成率（passes: true / 总数）
3. 按优先级列出未完成功能
4. 读取 progress.md 最近条目
5. 生成进度摘要

输出格式：

📋 项目进度：项目名称
━━━━━━━━━━━━━━━━━━
✅ 完成：X / Y（Z%）
🔴 待做（高优先级）：...
🟡 待做（中优先级）：...
🟢 待做（低优先级）：...
━━━━━━━━━━━━━━━━━━
最近会话：[简要摘要]

---

调度子Agent（sessions_spawn）

将单个功能委派给子Agent开发时，task 描述必须自包含：

{
  "task": "## 任务：实现 feat-XXX 功能\n\n### 项目信息\n- 路径：projects/project-name/\n- 技术栈：...\n\n### 你的目标\n实现以下功能并验证：\n[功能描述]\n\n### 启动例程\n1. 读取 projects/project-name/features.json 找到 feat-XXX\n2. 读取 projects/project-name/progress.md 了解历史\n3. 运行 git log --oneline -5\n4. 运行 projects/project-name/init.sh（如有）\n5. 运行基础测试确认环境正常\n\n### 工作要求\n- 只做这一个功能\n- 完成后必须验证\n- 结束时更新 features.json 的 passes 字段\n- 结束时追加 progress.md 日志\n- 结束时 git commit",
  "sessionKey": "alpha",
  "runTimeoutSeconds": 600
}

关键： task 必须包含所有上下文。子Agent看不到主对话历史。

---

定时巡检（Cron Job）

对于重要项目，可设置定时 cron job 巡检进度：

schedule: kind=cron, expr="0 */4 * * *"
payload: kind=agentTurn, message="读取 projects/<name>/progress.md 和 features.json，检查是否有功能卡住超过3个会话未完成。如有，输出简要报告。"

---

故障模式预防

故障模式	预防措施
Agent 试图一次性做完所有功能	强制每次只选一个 passes: false 的功能
Agent 过早宣布项目完成	features.json 有明确的状态追踪
Agent 留下的代码有 bug	启动时运行基础测试；结束时 git commit 便于回滚
Agent 花时间理解环境	使用 init.sh 标准化启动
上下文丢失导致重复工作	progress.md + git log 提供完整历史
功能未真正完成就标记 passes	要求验证后才能修改 passes 字段

---

通用领域扩展

此框架不限于软件开发。对于非代码类长期任务：

• 研究项目： features.json 中的 tests 改为 research objectives，passes 表示研究是否完成
• 写作项目： features 拆分为章节/段落，passes 表示是否已写完并审校
• 数据分析： features 拆分为分析步骤，passes 表示结果是否已验证

使用不同 category 区分：research|writing|analysis|infra|docs