AC State Tracker 是一个用于自主编码的持久化状态管理工具，主要解决跨会话（cross-session）场景下的状态保存与恢复问题。
用途 该工具用于在自主编码过程中维护所有状态，包括功能列表跟踪（passes: false → true）、执行状态（迭代、成本、状态）、进度日志、交接包以及检查点管理。它适合需要跨多个会话持续推进、并希望保留完整进度记录的场景。
主要能力
- 功能列表跟踪：通过 feature_list.json 记录每个功能的 id、描述、分类、状态、passes、测试用例、依赖、预估与实际工作量、开始与完成时间等。
- 执行状态管理：通过 autonomous-state.json 记录 session_id、迭代次数、状态、预估成本、连续失败次数、当前功能、最后任务、开始时间、上下文使用率等。
- 主状态管理：通过 master-state.json 记录项目 id、目标、已用会话数、总功能数、已完成功能数、当前阶段、最后交接时间等。
- 进度日志：生成人类可读的 claude-progress.txt，以及追加式的 autonomous-log.jsonl 活动日志。
- 检查点：支持创建检查点（可包含 git commit）并恢复到指定检查点，恢复 feature_list.json 和 git 状态。
- 交接包：支持保存 handoff 信息，如当前功能、上下文摘要、下一步操作。
- 进度摘要：可获取已完成数、总数、百分比、当前功能、预估剩余时间等。
使用方式 通过 Python 脚本使用 StateTracker 类：
初始化： from scripts.state_tracker import StateTracker state = StateTracker(project_dir) await state.initialize()
保存/加载状态： await state.save() current_state = await state.load()
更新功能状态： await state.update_feature("auth-001", passes=True) await state.update_feature(feature_id="auth-002", status="in_progress")
创建检查点： checkpoint = await state.create_checkpoint(name="before-refactor", git_commit=True)
恢复检查点： await state.restore_checkpoint("checkpoint-20250115-100000")
记录活动： await state.log_activity(action="CONTINUE", details="Implementing login endpoint", iteration=12)
保存交接： await state.save_handoff({"current_feature": "auth-002", "context_summary": "Completed auth, starting profile...", "next_action": "Implement profile page"})
获取进度摘要： progress = await state.get_progress()
状态文件结构 project/ ├── feature_list.json ├── claude-progress.txt └── .claude/ ├── master-state.json ├── autonomous-state.json ├── autonomous-log.jsonl ├── handoffs/ │ └── current.json └── checkpoints/ └── checkpoint-*.json
关键规则 功能只能从 passes: false 转换为 true，绝不能删除或编辑功能，以防止智能体通过移除任务来“解决”问题。
集成点 可与 ac-config-manager（加载路径配置）、ac-session-manager（触发状态保存/加载）、ac-autonomous-loop（更新功能状态）、ac-checkpoint-manager（创建/恢复检查点）、ac-handoff-coordinator（管理交接包）等组件集成。
参考与脚本 参考文档包括 references/STATE-SCHEMA.md 和 references/FEATURE-LIFECYCLE.md。脚本包括 scripts/state_tracker.py、scripts/feature_manager.py、scripts/checkpoint_store.py、scripts/progress_logger.py。
适用场景 适用于需要跨会话持续进行的自主编码项目，尤其是需要跟踪大量功能完成情况、管理检查点与回滚、记录进度日志以及在不同会话之间交接上下文的场景。
限制 资料未提供关于收费、价格、平台支持范围、性能效果等方面的信息。功能状态只能单向变更，不可删除或编辑功能。