介绍
# Research Tracker
用于管理自主研究代理的 CLI 工具，具有仅追加状态、指令队列和监督功能。
## 前置条件
```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 "Q1 Market Analysis" --objective "Analyze competitor pricing and positioning" ```
### 作为研究代理 —— 记录进度 ```bash 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 ```
### 检查状态（从主会话或心跳） ```bash research status market-q1 --json research context market-q1 --last 5 # Truncated context for prompts ```
### 向运行中的代理发送指令 ```bash research instruct market-q1 "Focus on enterprise segment" --priority URGENT research stop-signal market-q1 # Request graceful stop ```
### 代理检查指令 ```bash research pending market-q1 --json research ack market-q1 --all # Acknowledge after processing research check-stop market-q1 # Exit 0 = stop, Exit 1 = continue ```
## 命令参考
| 命令 | 用途 | |---------|---------| | `init <id> -o "..."` | 创建项目并设定目标 | | `list [--status active\|done\|all]` | 列出项目（包含 `needs_attention` 标志） | | `show <id>` | 项目详情 + 最近事件 | | `stop <id>` | 停止项目，发送 STOP 指令 | | `archive <id>` | 归档已完成项目 | | `log <id> <event> [--step N]` | 记录事件 (STEP_BEGIN, CHECKPOINT, BLOCKED 等) | | `heartbeat <id>` | 更新存活时间戳 | | `block <id> --reason "..."` | 标记为阻塞，需要输入 | | `complete <id>` | 标记为完成 | | `status <id> [--json]` | 当前状态摘要 | | `context <id> [--last N]` | 用于代理提示词的截断上下文 | | `instruct <id> "text"` | 发送指令 | | `pending <id>` | 列出未确认指令 | | `ack <id> [--all]` | 确认指令 | | `check-stop <id>` | 退出代码：0=停止，1=继续 | | `audit <id> --verdict pass\|drift` | 记录审计结果 |
## 事件类型
`STARTED`, `STEP_BEGIN`, `STEP_COMPLETE`, `CHECKPOINT`, `BLOCKED`, `UNBLOCKED`, `AUDIT_PASS`, `AUDIT_DRIFT`, `HEARTBEAT`, `DONE`, `STOPPED`, `TIMEOUT`
## 集成模式
### 生成研究代理
``` 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> "..." ```
### 代理循环（在生成的代理中）
```bash 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 ```
## 注意力检测
当满足以下条件时，`research list --json` 包含 `needs_attention: true`： - 最后一个事件是 BLOCKED - 有未确认的 URGENT 或 STOP 指令 - 心跳过时（距离上次 HEARTBEAT 事件超过 5 分钟） - 最后一次审计是 AUDIT_DRIFT
## 数据库
位于 `~/.config/research-tracker/research.db` 的 SQLite（WAL 模式，仅追加事件）。
安装后运行 `research db migrate`。首次使用时会自动迁移架构。