名称： research-tracker
描述： 基于 SQLite 状态追踪管理自主 AI 研究代理。适用于启动长期运行的研究子代理、追踪多步骤调查、协调代理交接或监控后台工作。触发场景：研究项目、子代理协调、自主调查、进度追踪、代理监督。

研究追踪器

用于管理自主研究代理的 CLI 工具，具备仅追加状态、指令队列和监督功能。

前提条件

brew tap 1645labs/tap
brew install julians-research-tracker

或：go install github.com/1645labs/julians-research-tracker/cmd/research@latest

快速开始

启动研究项目

research init market-q1 --name "第一季度市场分析" --objective "分析竞争对手定价与定位"

作为研究代理 — 记录进度

export RESEARCH_SESSION_ID="$SESSION_KEY"  # 追踪当前写入的代理

research log market-q1 STEP_BEGIN --step 1 --payload '{"task":"收集资料"}'
# ... 执行工作 ...
research log market-q1 STEP_COMPLETE --step 1
research heartbeat market-q1

检查状态（从主会话或心跳）

research status market-q1 --json
research context market-q1 --last 5  # 截断上下文用于提示

向运行中的代理发送指令

research instruct market-q1 "聚焦企业级市场" --priority URGENT
research stop-signal market-q1  # 请求优雅停止

代理检查指令

research pending market-q1 --json
research ack market-q1 --all  # 处理完成后确认
research check-stop market-q1  # 退出码 0 = 停止，1 = 继续

命令参考

事件类型

STARTED、STEP_BEGIN、STEP_COMPLETE、CHECKPOINT、BLOCKED、UNBLOCKED、AUDIT_PASS、AUDIT_DRIFT、HEARTBEAT、DONE、STOPPED、TIMEOUT

集成模式

启动研究代理

1. research init <project> --objective "..."
2. sessions_spawn 包含以下任务：
   - 项目 ID 和目标
   - 使用 research CLI 管理状态的指令
   - 每个步骤前检查停止信号
   - 记录进度并发送心跳
3. 心跳监控：research list --json | 检查 needs_attention
4. 发送指令：research instruct <project> "..."

代理循环（在启动的代理中）

while research check-stop $PROJECT; [ $? -eq 1 ]; do
  research pending $PROJECT --json  # 检查指令
  research log $PROJECT STEP_BEGIN --step $STEP
  # ... 执行工作 ...
  research log $PROJECT STEP_COMPLETE --step $STEP
  research heartbeat $PROJECT
  STEP=$((STEP + 1))
done
research complete $PROJECT

关注检测

research list --json 在以下情况包含 needs_attention: true：
- 最近事件为 BLOCKED
- 存在未确认的 URGENT 或 STOP 指令
- 心跳过期（距离上次 HEARTBEAT 事件 >5 分钟）
- 最近审计结果为 AUDIT_DRIFT

数据库

SQLite 数据库位于 ~/.config/research-tracker/research.db（WAL 模式，仅追加事件）。

安装后运行 research db migrate。首次使用时自动迁移架构。