研究追踪器

用于管理自主研究代理的命令行工具，具备只增状态、指令队列和监督功能。

前提条件

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 "Q1 Market Analysis" --objective "Analyze competitor pricing and positioning"

作为研究代理 — 记录进度

export RESEARCH_SESSION_ID="$SESSION_KEY"  # Track which agent is writing

research log market-q1 STEP_BEGIN --step 1 --payload '{"task":"gather sources"}'
# ... do work ...
research log market-q1 STEP_COMPLETE --step 1
research heartbeat market-q1

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

research status market-q1 --json
research context market-q1 --last 5  # Truncated context for prompts

向运行中的代理发送指令

research instruct market-q1 "Focus on enterprise segment" --priority URGENT
research stop-signal market-q1  # Request graceful stop

代理检查指令

research pending market-q1 --json
research ack market-q1 --all  # Acknowledge after processing
research check-stop market-q1  # Exit 0 = stop, Exit 1 = continue

命令参考

事件类型

已开始,步骤开始,步骤完成,检查点,已阻塞,已解除阻塞,审计通过,审计漂移,心跳,已完成,已停止,超时

集成模式

启动研究代理

1. research init <project> --objective "..."
2. sessions_spawn with task including:
   - Project ID and objective
   - Instructions to use research CLI for state
   - Check stop signal before each step
   - Log progress with heartbeat
3. Heartbeat monitors: research list --json | check needs_attention
4. Send instructions via: research instruct <project> "..."

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

while research check-stop $PROJECT; [ $? -eq 1 ]; do
  research pending $PROJECT --json  # Check instructions
  research log $PROJECT STEP_BEGIN --step $STEP
  # ... do work ...
  research log $PROJECT STEP_COMPLETE --step $STEP
  research heartbeat $PROJECT
  STEP=$((STEP + 1))
done
research complete $PROJECT

注意力检测

研究列表 --json包含需要关注：true当：

• 最后一个事件是 BLOCKED
• 存在未确认的 URGENT 或 STOP 指令
• 心跳陈旧（自上次 HEARTBEAT 事件后 >5 分钟）
• 上次审计是 AUDIT_DRIFT

数据库

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

运行research db migrate安装后。模式在首次使用时自动迁移。