基于 Anthropic 论文 "Effective Harnesses for Long-Running Agents" 实现的离线长期记忆系统。
这个系统解决了 AI 代理在长期运行任务中的核心挑战：如何在多个独立会话之间保持记忆和上下文连续性。
- 上下文窗口限制：复杂项目无法在单个会话中完成
- 会话间断：每个新会话开始时都没有之前的记忆
- 过度尝试：代理倾向于一次性做太多事情
- 过早完成：代理容易在未完全完成任务时宣布胜利
通过结构化的状态持久化和智能会话管理，让 AI 代理像优秀的人类工程师一样工作。
claude_long/
├── core/ # 核心功能模块
│ ├── progress_manager.py # 进度管理器
│ ├── feature_manager.py # 特征列表管理器
│ ├── session_manager.py # 会话管理器
│ └── git_manager.py # Git 集成管理器
├── templates/ # 模板文件
│ ├── progress.txt.template # 进度文件模板
│ ├── feature_list.json.template # 特征列表模板
│ └── init.sh.template # 初始化脚本模板
├── examples/ # 使用示例
│ └── web_app_example/ # Web 应用开发示例
├── docs/ # 文档
│ ├── architecture.md # 架构文档
│ ├── best_practices.md # 最佳实践
│ └── api_reference.md # API 参考
└── README.md # 本文件
cd your_project
python claude_long/core/session_manager.py init这会创建：
claude-progress.txt- 进度日志文件feature_list.json- 功能需求列表init.sh- 项目初始化脚本.git/- Git 仓库（如果不存在）
每次开始新的编码会话时：
python claude_long/core/session_manager.py start系统会自动：
- 读取进度文件和 Git 日志
- 加载功能列表
- 运行初始化脚本
- 验证项目状态
- 选择下一个待完成功能
会话结束时：
python claude_long/core/session_manager.py end "完成了用户登录功能"系统会：
- 更新进度文件
- 创建 Git 提交
- 更新功能列表状态
- 保存会话摘要
- 用于项目的第一个会话
- 创建功能列表文件
- 设置 Git 仓库
- 编写初始化脚本
- 用于所有后续会话
- 每次只处理一个功能
- 进行增量开发
- 留下结构化的进度更新
记录每个会话完成的工作：
=== Session 1: 2026-03-30 ===
- Created project structure
- Set up database schema
- Implemented user model
Status: Database connected successfully
=== Session 2: 2026-03-30 ===
- Implemented user registration API
- Added input validation
- Wrote unit tests for registration
Status: 15/20 tests passing, need to fix email validation
结构化的功能需求文件：
[
{
"id": "F001",
"category": "authentication",
"priority": 1,
"description": "User registration with email",
"steps": [
"Create registration form",
"Validate email format",
"Hash password securely",
"Save user to database",
"Send confirmation email"
],
"passes": false,
"notes": ""
}
]- 每个功能完成后提交
- 描述性提交消息
- 便于回滚错误更改
核心原则：
- 一次一个功能 - 避免同时处理多个任务
- 保持干净状态 - 代码有序、测试通过、文档完善
- 彻底测试 - 端到端验证功能
- 结构化更新 - 清晰记录完成的工作
工作流程：
选择功能 → 实现 → 测试 → 提交 → 更新进度 → 标记完成
每个编码会话的标准启动步骤：
def start_session():
# 1. 确认工作目录
pwd = get_current_directory()
# 2. 读取上下文
progress = read_progress_file()
features = read_feature_list()
git_log = get_recent_commits(20)
# 3. 启动开发环境
run_init_script()
# 4. 验证基本功能
run_smoke_tests()
# 5. 选择下一个任务
next_feature = select_next_feature(features)
return next_feature你是一个项目初始化代理。你的任务是为长期运行的编码项目设置环境。
请执行以下步骤：
1. 分析项目需求规范
2. 创建功能列表文件（feature_list.json），包含所有需要实现的功能
3. 初始化 Git 仓库并创建初始提交
4. 创建进度文件（claude-progress.txt）
5. 编写初始化脚本（init.sh）用于启动开发服务器
6. 所有功能初始标记为 "passes": false
功能列表应包含：
- 功能 ID
- 类别和优先级
- 详细描述
- 实现步骤
- 测试标准
完成后，项目应处于"干净状态"，下一个代理可以立即开始工作。
你是一个编码代理，继续进行长期运行的项目。
会话启动流程：
1. 运行 pwd 确认工作目录
2. 读取 claude-progress.txt 了解最近的工作
3. 读取 feature_list.json 查看待完成功能
4. 查看 git log --oneline -20 了解最近提交
5. 运行 init.sh 启动开发服务器
6. 进行基本测试确保应用未损坏
7. 选择一个 passes=false 的高优先级功能开始工作
核心规则：
- 每次只处理一个功能
- 完成功能后进行端到端测试
- 测试通过后提交到 Git 并附上描述性消息
- 更新 claude-progress.txt 记录完成的工作
- 只有在彻底测试后才将功能标记为 passes=true
- 绝不删除或编辑功能列表中的测试项
- 会话结束时确保代码处于"干净状态"
"干净状态"意味着：
- 没有重大错误
- 代码有序且文档完善
- 所有测试通过
- 下一个开发者可以轻松继续工作
好的功能定义：
{
"description": "User can register with email and password",
"steps": [
"Create registration form UI",
"Validate email format",
"Hash password with bcrypt",
"Save user to database",
"Return success response"
]
}不好的功能定义：
{
"description": "Implement authentication system",
"steps": ["Build auth"] // 太宽泛
}好的进度记录：
=== Session 5: 2026-03-30 ===
Implemented: User login endpoint
- Created POST /api/login route
- Added JWT token generation
- Implemented password verification
- Wrote 8 unit tests (all passing)
- Tested login flow end-to-end in browser
Next steps:
- Implement token refresh mechanism
- Add rate limiting for login attempts
Status: Login feature working correctly, ready for next feature
不好的进度记录：
Worked on login stuff. Mostly done.
端到端测试：
# 不要只依赖单元测试
pytest tests/test_login.py # 不够
# 进行真实的用户流程测试
python claude_long/core/session_manager.py test "login_flow"
# 这会启动浏览器并模拟用户操作测试检查清单：
- 功能在浏览器中手动测试
- 单元测试通过
- 集成测试通过
- 边界情况已覆盖
- 错误处理已验证
好的提交：
git commit -m "feat: implement user login with JWT
- Add POST /api/login endpoint
- Implement password verification
- Generate JWT tokens with 24h expiration
- Add rate limiting (5 attempts per minute)
- Include comprehensive error messages
Tests: 8/8 passing
Closes: #F002"不好的提交：
git commit -m "update"| 问题 | 解决方案 |
|---|---|
| 一次做太多事情 | 严格遵守"一次一个功能"原则 |
| 测试不充分 | 必须进行端到端测试，不只是单元测试 |
| 过早宣布完成 | 仅在所有测试步骤通过后标记为 true |
| 留下错误状态 | 会话结束前运行完整测试套件 |
| 模糊的进度记录 | 使用结构化格式，包含具体细节 |
from claude_long.core.progress_manager import ProgressManager
pm = ProgressManager("claude-progress.txt")
# 读取进度
progress = pm.read()
# 添加会话记录
pm.add_session(
session_id="Session 5",
date="2026-03-30",
completed_work=[
"Implemented login endpoint",
"Added JWT authentication"
],
status="Tests passing, ready for next feature"
)
# 获取最近会话
recent = pm.get_recent_sessions(5)from claude_long.core.feature_manager import FeatureManager
fm = FeatureManager("feature_list.json")
# 加载功能列表
features = fm.load()
# 获取下一个待完成功能
next_feature = fm.get_next_pending_feature()
# 标记功能完成
fm.mark_as_complete(
feature_id="F002",
notes="Login working with JWT, all tests passing"
)
# 验证功能列表完整性
is_valid = fm.validate()from claude_long.core.session_manager import SessionManager
sm = SessionManager(project_dir=".")
# 初始化新项目
sm.initialize(project_spec="spec.md")
# 开始新会话
context = sm.start_session()
# 返回：{
# "progress": "...",
# "git_log": "...",
# "features": [...],
# "next_feature": {...}
# }
# 结束会话
sm.end_session(
summary="Completed login feature",
completed_features=["F002"]
)from claude_long.core.git_manager import GitManager
gm = GitManager()
# 获取最近提交
commits = gm.get_recent_commits(20)
# 创建提交
gm.commit(
message="feat: add user login",
files=["api/login.py", "tests/test_login.py"]
)
# 回滚最后一次提交
gm.rollback()
# 检查工作目录状态
status = gm.get_status()对于复杂项目，可以使用专门的代理：
# 编码代理
coding_agent = SessionManager(agent_type="coding")
# 测试代理
test_agent = SessionManager(agent_type="testing")
# 重构代理
refactor_agent = SessionManager(agent_type="refactoring")
# 协调工作流
workflow = MultiAgentWorkflow([coding_agent, test_agent, refactor_agent])
workflow.run(){
"id": "F001",
"type": "feature", // feature, bugfix, refactor, test
"category": "authentication",
"priority": 1,
"complexity": "medium", // low, medium, high
"estimated_sessions": 2,
"dependencies": [],
"description": "User login with OAuth",
"acceptance_criteria": [
"User can login with Google",
"User can login with GitHub",
"Session persists across page reloads"
],
"steps": [...],
"passes": false,
"test_results": {},
"notes": ""
}from claude_long.core.session_manager import SessionManager
sm = SessionManager()
# 运行自动化测试套件
results = sm.run_tests(
test_type="e2e",
feature_id="F002"
)
if results.all_passed:
sm.mark_feature_complete("F002")
else:
sm.add_failure_notes("F002", results.failures)解决方案：
# 1. 查看最近的提交
git log --oneline -10
# 2. 回滚到最后一个工作状态
git reset --hard <commit-hash>
# 3. 在进度文件中记录回滚
echo "Rolled back to commit <hash> due to broken state" >> claude-progress.txt
# 4. 继续工作
python claude_long/core/session_manager.py start解决方案：
# 运行同步检查
python claude_long/core/feature_manager.py sync-check
# 这会：
# 1. 分析代码库
# 2. 对比功能列表
# 3. 报告差异
# 4. 提供修正建议解决方案：
# 归档旧会话
python claude_long/core/progress_manager.py archive --keep-recent 20
# 这会：
# 1. 保留最近 20 个会话
# 2. 将旧会话移到 claude-progress-archive.txt
# 3. 保持文件大小可控这个系统基于 Anthropic 的研究，核心思想是：
- 增量进步优于一次性完成 - 每次专注一个功能
- 结构化状态优于临时记忆 - 使用文件系统持久化状态
- 测试驱动优于假设正确 - 始终验证功能端到端工作
- 清晰记录优于隐式知识 - 明确记录完成的工作和遗留问题
- 版本控制优于代码快照 - Git 提供完整的历史和回滚能力
欢迎提交 Issue 和 Pull Request。
MIT License
- Anthropic: Effective Harnesses for Long-Running Agents
- 项目灵感来源于真实软件工程师的工作方式
- Git 工作流程最佳实践
让 AI 代理像优秀的人类工程师一样工作。