nexus-agent-cli 0.5.0

Nexus internal agent ops CLI — pull run params, push analysis results, send notifications. Admin only.

nexus-agent-cli

Nexus 内部 agent 运维 CLI。用于把"每周分析任务"从 AWS 跑逐步迁到本地 Claude 跑： 拉取运行参数、回传分析结果、发通知 —— 让 S3 / SES / Google Sheets 凭证只留在服务端。

与 strategy provider 用的 nexusquant-cli 区分开：这是 admin 专用 工具。 需要 Cognito custom:userType=admin。

安装

pip install nexus-agent-cli

本地开发（可编辑安装）：

git clone https://github.com/lookatwallstreet/nexus-agent-cli.git
cd nexus-agent-cli && pip install -e .

登录（一次）

nexus-agent auth            # 打开浏览器走 Cognito 登录（admin 账号）
nexus-agent auth --status   # 查看本机登录状态
nexus-agent auth --refresh  # 刷新 token
nexus-agent auth --logout   # 清除本机 token

凭据存放在当前用户的 config 目录（如 macOS ~/Library/Application Support/nexus-agent-cli/credentials.json），权限 0600，与 nexusquant-cli 互不影响。

命令

# 拉取本周运行参数（tickers + 日期区间）
nexus-agent run-config
nexus-agent run-config --tickers TQQQ,SOXL,IBIT

# 回传市场分析报告（markdown）
nexus-agent push-market-analysis --ticker tqqq --file report_cn.md --language zh

# 回传投资组合推荐（英文必填，中文可选）
nexus-agent push-portfolio --file portfolio.md --file-cn portfolio_cn.md \
    --time-range 2026-06-01_2026-06-14

# 回传回测聚合数据（至少一个档位）
nexus-agent push-backtest --ticker tqqq \
    --aggressive aggressive_aggregated.json \
    --conservative conservative_aggregated.json \
    --normal normal_aggregated.json

# 回读 S3（均为只读，登录即可）：最新回测 / 市场分析报告 / 组合推荐
nexus-agent get-backtest --ticker tqqq --out tqqq_backtest.json
nexus-agent get-market-analysis --ticker tqqq --out tqqq_market.json
nexus-agent get-portfolio --out portfolio.json

# 拉取 S3 上最新的 signal_position 基线 config（Position-Research 阶段用）
nexus-agent pull-config --ticker tqqq --kind normal --out tqqq-normal.json

# 历史版本（by-date）：列出 → 取指定版本
nexus-agent pull-config --ticker tqqq --kind normal --list --since 2026-06-01
nexus-agent pull-config --ticker tqqq --kind normal --date 2026-06-01_to_2026-06-14 --out old.json
nexus-agent get-market-analysis --ticker tqqq --list
nexus-agent get-portfolio --list --since 2026-06-01

# 回传 Position-Research 产出的 3 套仓位 config（≠ push-backtest 的回测聚合）
nexus-agent push-config --ticker tqqq --time-range 2026-06-01_2026-06-14 \
    --aggressive tqqq-aggressive.json \
    --conservative tqqq-conservative.json \
    --normal tqqq-normal.json

# 服务端 SES 发通知邮件
nexus-agent notify --to [e-mail] --to [e-mail] --subject "Weekly report" --body-file summary.txt

配置（环境变量，均可选）

变量	默认	说明
NEXUS_AGENT_API_ENDPOINT	https://api.nexusquant.co	后端 host（会自动加 /api）
NEXUS_AGENT_API_BASE_URL	—	直接覆盖完整 API base（含 /api）
NEXUS_AGENT_COGNITO_DOMAIN	auth.lookatwallstreet.com	Cognito Hosted UI 域名
NEXUS_AGENT_COGNITO_CLIENT_ID	（内置）	Cognito app client id
NEXUS_AGENT_REDIRECT_URI	http://127.0.0.1:8251/callback	本地回调（须 localhost+端口；端口必须已加入 Cognito app client 的 Allowed callback URLs）

例如指向本地后端调试：

NEXUS_AGENT_API_BASE_URL=http://127.0.0.1:8000/api nexus-agent run-config

对应后端

这些命令调用 nexus-service apps/nexus_agent 的 admin 端点： run-config/、upload/market-analysis/、upload/portfolio-recommendation/、 upload/backtest/、notify/。

发布新版本

# 1. 改 pyproject.toml 的 version
# 2. 构建并发布到 PyPI（用 .zshrc 里的 UV_PUBLISH_PASSWORD all-projects token）
rm -rf dist && python -m build
TWINE_USERNAME=__token__ TWINE_PASSWORD="$UV_PUBLISH_PASSWORD" twine upload dist/*

迁移说明

当前 AWS（EventBridge → ECS Fargate）的每周定时运行保持不变。本 CLI 提供并行的 "本地驱动"路径，逐步把运行从云上挪到本地，详见 nexus-claude-plugin 的 nexus-agent / weekly-analysis-run skill。