核心用法
research-tracker 是一款专为自主 AI 研究代理设计的 CLI 状态管理工具，基于 SQLite 构建 append-only 事件日志系统。核心工作流分为三个层次：
项目管理层：通过 research init 创建研究项目并设定目标，list/show/status 实时查看项目状态，archive 归档已完成项目。
代理执行层：子代理通过环境变量 RESEARCH_SESSION_ID 标识身份，使用 log 记录事件（STEP_BEGIN/CHECKPOINT/BLOCKED 等），heartbeat 保活，pending/ack 处理主会话下发的指令，check-stop 轮询优雅停止信号。
监控协调层：主会话通过 instruct 发送优先级指令（URGENT/STOP），list --json 的 needs_attention 字段自动标记需人工介入的场景（阻塞、心跳超时、审计漂移等）。
显著优点
1. 轻量可靠：单二进制文件 + SQLite（WAL 模式），无外部依赖，适合本地和 CI 环境
2. 代理原生设计：指令队列、停止信号、事件日志均为 AI 代理执行模型优化
3. 审计完整：append-only 事件流支持事后复盘，内置 audit 命令标记漂移
4. 多代理协调：通过项目 ID 和环境变量实现跨会话、跨进程的代理交接
潜在局限
- 单机架构：SQLite 限制多机分布式部署，高并发场景需自行封装
- 无内置重试：BLOCKED 状态需外部逻辑处理恢复
- CLI 优先：暂无 REST/gRPC 接口，与 Web 服务集成需包装层
适合人群
- 需要编排多个长周期研究子代理的 AI 系统开发者
- 构建自主 agent 工作流（如 OpenAI Assistants、Claude 工具使用）的工程师
- 追求可观测性的个人研究者（替代 ad-hoc 的 JSON 文件或 Redis）
常规风险
- 数据丢失：默认路径
~/.config/research-tracker/需纳入备份策略 - 僵尸代理：心跳超时 5 分钟判定，但依赖代理正确实现
check-stop轮询 - 指令竞态：URGENT 指令无强制抢占机制，代理需高频轮询
pending