Research Tracker
CLI tool for managing autonomous research agents with append-only state, instruction queues, and oversight.
Prerequisites
CODEBLOCK0
Or: INLINECODE0
Quick Start
Start a research project
CODEBLOCK1
As the research agent — log progress
CODEBLOCK2
Check status (from main session or heartbeat)
CODEBLOCK3
Send instructions to running agent
CODEBLOCK4
Agent checks for instructions
CODEBLOCK5
Commands Reference
| Command | Purpose |
|---|
| INLINECODE1 | Create project with objective |
| INLINECODE2 |
List projects (includes
needs_attention flag) |
|
show <id> | Project details + recent events |
|
stop <id> | Stop project, send STOP instruction |
|
archive <id> | Archive completed project |
|
log <id> <event> [--step N] | Log event (STEP_BEGIN, CHECKPOINT, BLOCKED, etc.) |
|
heartbeat <id> | Update alive timestamp |
|
block <id> --reason "..." | Mark blocked, needs input |
|
complete <id> | Mark done |
|
status <id> [--json] | Current state summary |
|
context <id> [--last N] | Truncated context for agent prompts |
|
instruct <id> "text" | Send instruction |
|
pending <id> | List unacked instructions |
|
ack <id> [--all] | Acknowledge instructions |
|
check-stop <id> | Exit code: 0=stop, 1=continue |
|
audit <id> --verdict pass\|drift | Log audit result |
Event Types
INLINECODE18 , STEP_BEGIN, STEP_COMPLETE, CHECKPOINT, BLOCKED, UNBLOCKED, AUDIT_PASS, AUDIT_DRIFT, HEARTBEAT, DONE, STOPPED, INLINECODE29
Integration Pattern
Spawning a research agent
CODEBLOCK6
Agent loop (in spawned agent)
CODEBLOCK7
Attention Detection
INLINECODE30 includes needs_attention: true when:
- - Last event is BLOCKED
- Has unacked URGENT or STOP instructions
- Heartbeat stale (>5 min since last HEARTBEAT event)
- Last audit was AUDIT_DRIFT
Database
SQLite at ~/.config/research-tracker/research.db (WAL mode, append-only events).
Run research db migrate after install. Schema auto-migrates on first use.
研究追踪器
用于管理自主研究代理的命令行工具，支持仅追加状态、指令队列和监督功能。
前置条件
bash
brew tap 1645labs/tap
brew install julians-research-tracker
或者：go install github.com/1645labs/julians-research-tracker/cmd/research@latest
快速开始
启动研究项目
bash
research init market-q1 --name 第一季度市场分析 --objective 分析竞争对手定价与市场定位
作为研究代理——记录进度
bash
export RESEARCH
SESSIONID=$SESSION_KEY # 追踪写入代理
research log market-q1 STEP_BEGIN --step 1 --payload {task:收集来源}
... 执行工作 ...
research log market-q1 STEP_COMPLETE --step 1
research heartbeat market-q1
检查状态（从主会话或心跳）
bash
research status market-q1 --json
research context market-q1 --last 5 # 用于提示的截断上下文
向运行中的代理发送指令
bash
research instruct market-q1 重点关注企业级市场 --priority URGENT
research stop-signal market-q1 # 请求优雅停止
代理检查指令
bash
research pending market-q1 --json
research ack market-q1 --all # 处理完成后确认
research check-stop market-q1 # 退出码0=停止，退出码1=继续
命令参考
| 命令 | 用途 |
|---|
| init <id> -o ... | 创建带有目标的项目 |
| list [--status active\ |
done\|all] | 列出项目（包含needs_attention标记） |
| show
| 项目详情 + 最近事件 |
| stop | 停止项目，发送STOP指令 |
| archive | 归档已完成项目 |
| log [--step N] | 记录事件（STEP_BEGIN, CHECKPOINT, BLOCKED等） |
| heartbeat | 更新存活时间戳 |
| block --reason ... | 标记为阻塞，需要输入 |
| complete | 标记完成 |
| status [--json] | 当前状态摘要 |
| context [--last N] | 用于代理提示的截断上下文 |
| instruct 文本 | 发送指令 |
| pending | 列出未确认的指令 |
| ack [--all] | 确认指令 |
| check-stop | 退出码：0=停止，1=继续 |
| audit --verdict pass\|drift | 记录审计结果 |
事件类型
STARTED, STEPBEGIN, STEPCOMPLETE, CHECKPOINT, BLOCKED, UNBLOCKED, AUDITPASS, AUDITDRIFT, HEARTBEAT, DONE, STOPPED, TIMEOUT
集成模式
生成研究代理
- 1. research init --objective ...
- sessions_spawn 包含任务：
- 项目ID和目标
- 使用research CLI管理状态的指令
- 每一步前检查停止信号
- 通过心跳记录进度
- 3. 心跳监控：research list --json | 检查 needs_attention
- 通过以下方式发送指令：research instruct ...
代理循环（在生成的代理中）
bash
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。首次使用时自动迁移架构。
