长时间运行 Agent 系统 (Long-Running Agent Harness)

基于 Anthropic 文章：Effective harnesses for long-running agents 搭建的长时间运行、多会话的 Autonomous Coding Agent 系统。

核心思想（来自文章）

• 问题：Agent 在多个 context window 间没有记忆，容易「一次做太多」「半成品留坑」「过早宣布完成」「不充分测试」。
• 方案：双阶段 Harness
  1. Initializer Agent（首轮）：搭建环境，产出「单一事实来源」和可恢复状态。
  2. Coding Agent（后续每轮）：增量完成一个 feature，留下清晰产物，便于下一轮接手。

环境与产物

产物	作用
feature_list.json	功能清单（含测试步骤），只允许改 passes，防止漏功能或过早宣布完成
claude-progress.txt	每轮进度摘要，供下一轮快速「接盘」
init.sh	一键启动开发环境（依赖 + 服务）
Git 提交	可回滚、可恢复，每轮结束前提交

每轮 Coding Agent 固定流程：先读 feature_list + progress + git log → 启动服务 → 做 1–2 个回归测试 → 选一个未完成 feature 实现 → 用浏览器自动化验证 → 只把对应项改为 passes: true → 提交 + 更新 progress。

项目结构

ai-sub/
├── autonomous_agent_demo.py   # 主入口
├── agent.py                   # 会话循环（Initializer / Coding）
├── client.py                  # Claude Agent SDK 客户端与安全配置
├── security.py                # Bash 白名单与校验
├── progress.py                # feature_list 进度统计与打印
├── prompts.py                 # 加载 initializer / coding prompt
├── prompts/
│   ├── app_spec.txt           # 应用规格（可改成你要做的产品）
│   ├── initializer_prompt.md  # 首轮 Agent 说明
│   └── coding_prompt.md       # 后续轮 Agent 说明
├── requirements.txt
└── README.md

依赖与前置

• Python 3.10+
• Claude Code CLI（与 Claude Agent SDK 配套）
• 设置 ANTHROPIC_API_KEY

# 安装 Claude Code CLI（需与 SDK 版本匹配）
npm install -g @anthropic-ai/claude-code

# 安装 Python 依赖
pip install -r requirements.txt

# 设置 API Key
export ANTHROPIC_API_KEY='your-api-key'

使用

# 在新目录启动（首轮为 Initializer，之后为 Coding Agent）
python autonomous_agent_demo.py --project-dir ./my_project

# 限制轮数（便于先跑通流程）
python autonomous_agent_demo.py --project-dir ./my_project --max-iterations 3

# 指定模型
python autonomous_agent_demo.py --project-dir ./my_project --model claude-sonnet-4-5-20250929

• 首轮：会复制 prompts/app_spec.txt 到项目目录，Agent 生成 feature_list.json、init.sh、初始化 git 并搭基础结构。耗时可能较长（例如 10–20 分钟），属正常。
• 后续轮：自动从 feature_list.json 和 claude-progress.txt 接续，每轮专注 1 个 feature，验证后再改 passes、提交、写 progress。
• 中断：Ctrl+C 停止后，再次执行相同命令即可从当前进度继续。

自定义要做的应用

• 修改 prompts/app_spec.txt：写清要做的产品/功能、技术栈、验收标准。
• 若希望首轮更快，可改 prompts/initializer_prompt.md 里对 feature 数量的要求（例如从 200 改为 20–50）。

安全（client.py + security.py）

• 沙箱：Bash 在隔离环境中执行。
• 读写范围：仅限 --project-dir 下文件。
• Bash 白名单：仅允许 security.ALLOWED_COMMANDS 中的命令（如 ls/cat/git/npm/node/./init.sh 等），pkill/chmod/init.sh 有额外校验。

仓库与 Checkpoint

• GitHub: codepotter66/ai-sub
• Clone: git clone git@github.com:codepotter66/ai-sub.git
• 本仓库已设置 user.name=codepotter66、user.email=kylehe22@gmail.com（仅此仓库）。
• 做 checkpoint：在项目根执行 git add . && git commit -m "..." && git push。

参考

• Effective harnesses for long-running agents
• Claude Agent SDK
• anthropics/claude-quickstarts - autonomous-coding