InvesResearch Docs › Agent › API · CLI + REST

API · docs/api.md · v0.2.0

satagent CLI + FastAPI REST

CLI 用于本地灌数据与脚本化回测; API 用于前端 / 别的 Agent 调用; 同一套 repository 层 支撑, 行为一致。--db 可被环境变量 SATAGENT_DB 覆盖, 默认在 agent/data/agent.db。

CLI 子命令9 REST 端点8 + health 错误码422 · 404 · 500 典型工作流3

§1 CLI · satagent

CLI · 9 个子命令

所有子命令支持 --db PATH 全局参数。错误从 stderr 输出, 非零 exit code。--text 必填项缺失时退出码 2。

CLIinit

初始化 · 建 schema + 写入 84 条市场模型 + 6 家公司 seed · 幂等

无参数

CLIclassify

只分类不入库 · 用于调试规则 · 支持 stdin

--text <str>

CLIingest

录入单条事件 · 自动分类 + 公司反哺

--title --text --source --url --occurred-at --indicators --companies

CLIingest-file

批量灌入 JSONL · 每行一个事件对象

<jsonl_path>

CLIevents

查询事件 · 返回反序列化后的 JSON array

--limit --thread --since --until

CLIreport

周报 · 默认 7 天窗口 · markdown 或 JSON

--window --end --format md|json

CLImarket-model

市场模型查询 · 全量 84 条或按 thread/year 过滤

--thread --year

CLIcompanies

公司卡片查询 · 按 thread 过滤

--thread

CLIregress

分类器回归 · 整体 + per-thread P/R/F1 + 失败列表

<jsonl_path> --format --no-company-enrich

§2 REST · FastAPI

REST · 8 业务端点 + /health

启动: uvicorn satellite_agent.api:app --reload · Swagger UI: http://127.0.0.1:8000/docs

GET/health

健康检查 · 返回 status + version

POST/classify

只做分类, 不入库

body { text: str }

POST/events/ingest

录入事件 + 分类 · companies=null 自动 alias 匹配

body { title? text source? url? occurred_at? next_indicators? companies? }

GET/events

查询事件列表

query thread? since? until? limit(1-500, 默认 50)

GET/events/{event_id}

单事件详情 · 404 表示不存在

path event_id: int

GET/report/weekly

周报 · format=md 返回 { markdown: str }

query window(1-90, 默认 7) end? format(json|md)

GET/market-model

市场模型查询

query thread? year?

GET/companies

公司卡片 · products/customers/aliases 已反序列化

query thread?

§3 Errors

错误码 · MVP 默认

MVP 阶段 FastAPI 用默认 422 / 404 / 500, 无自定义错误码。

422

请求体不符 pydantic 模型 · 路径/查询参数类型错

404

event id 不存在

500

内部异常 未捕获

CLI --text 必填项缺失

§4 典型工作流

3 个典型 workflow

本地日常跟踪 · 前端对接 · CI 回归门。

4.1 · 本地日常跟踪

分析师 · CLI

# 把今天的几条新闻塞进 JSONL
cat > today.jsonl <<EOF
{"title":"...","content":"...","occurred_at":"2026-06-01T10:00:00"}
{"title":"...","content":"...","occurred_at":"2026-06-01T15:30:00"}
EOF

satagent ingest-file today.jsonl
satagent report --window 7 --format md > weekly.md

4.2 · 前端对接

前端 · JS

// 1. 灌入事件
const r = await fetch('/events/ingest', {
  method: 'POST',
  headers: {'content-type': 'application/json'},
  body: JSON.stringify({title, text, occurred_at}),
});
const { id, classification } = await r.json();

// 2. 拉本周报告
const w = await fetch('/report/weekly?window=7&format=json').then(r => r.json());
// w.thread_scores / w.risks / w.next_tracking ...

4.3 · CI 回归门

GitHub Actions

# .github/workflows/regression.yml
- run: pip install -e ".[dev]"
- run: pytest -q                                 # 含 test_regression.py
- run: satagent regress samples/labeled_regression.jsonl