nexus-agent-cli 0.1.0__tar.gz

nexus_agent_cli-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Secrets / local creds
+credentials.json
+*.env
+.env*

nexus_agent_cli-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: nexus-agent-cli
+Version: 0.1.0
+Summary: Nexus internal agent ops CLI — pull run params, push analysis results, send notifications. Admin only.
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# nexus-agent-cli
+
+Nexus **内部** agent 运维 CLI。用于把"每周分析任务"从 AWS 跑逐步迁到本地 Claude 跑：
+拉取运行参数、回传分析结果、发通知 —— 让 S3 / SES / Google Sheets 凭证只留在服务端。
+
+> 与 strategy provider 用的 `nexusquant-cli` 区分开：这是 **admin 专用** 工具。
+> 需要 Cognito `custom:userType=admin`。
+
+## 安装
+
+```bash
+cd nexus-agent-cli
+pip install -e .
+```
+
+## 登录（一次）
+
+```bash
+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 互不影响。
+
+## 命令
+
+```bash
+# 拉取本周运行参数（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
+
+# 服务端 SES 发通知邮件
+nexus-agent notify --to a@x.com --to b@y.com --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:8252/callback` | 本地回调（须 localhost+端口） |
+
+例如指向本地后端调试：
+
+```bash
+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/`。
+
+## 迁移说明
+
+当前 AWS（EventBridge → ECS Fargate）的每周定时运行**保持不变**。本 CLI 提供并行的
+"本地驱动"路径，逐步把运行从云上挪到本地，详见 nexus-claude-plugin 的
+`nexus-agent / weekly-analysis-run` skill。

nexus_agent_cli-0.1.0/README.md

@@ -0,0 +1,77 @@
+# nexus-agent-cli
+
+Nexus **内部** agent 运维 CLI。用于把"每周分析任务"从 AWS 跑逐步迁到本地 Claude 跑：
+拉取运行参数、回传分析结果、发通知 —— 让 S3 / SES / Google Sheets 凭证只留在服务端。
+
+> 与 strategy provider 用的 `nexusquant-cli` 区分开：这是 **admin 专用** 工具。
+> 需要 Cognito `custom:userType=admin`。
+
+## 安装
+
+```bash
+cd nexus-agent-cli
+pip install -e .
+```
+
+## 登录（一次）
+
+```bash
+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 互不影响。
+
+## 命令
+
+```bash
+# 拉取本周运行参数（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
+
+# 服务端 SES 发通知邮件
+nexus-agent notify --to a@x.com --to b@y.com --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:8252/callback` | 本地回调（须 localhost+端口） |
+
+例如指向本地后端调试：
+
+```bash
+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/`。
+
+## 迁移说明
+
+当前 AWS（EventBridge → ECS Fargate）的每周定时运行**保持不变**。本 CLI 提供并行的
+"本地驱动"路径，逐步把运行从云上挪到本地，详见 nexus-claude-plugin 的
+`nexus-agent / weekly-analysis-run` skill。

nexus_agent_cli-0.1.0/nexus_agent_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

nexus_agent_cli-0.1.0/nexus_agent_cli/__main__.py

@@ -0,0 +1,4 @@
+from nexus_agent_cli.main import app
+
+if __name__ == "__main__":
+    app()

nexus_agent_cli-0.1.0/nexus_agent_cli/api_client.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+
+from nexus_agent_cli.auth_pkce import ensure_fresh_id_token
+from nexus_agent_cli.config import api_base_url
+
+
+def _headers() -> dict[str, str]:
+    token = ensure_fresh_id_token()
+    return {"Authorization": f"Bearer {token}", "Accept": "application/json"}
+
+
+def _raise_for_error(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    try:
+        detail: Any = response.json()
+    except json.JSONDecodeError:
+        detail = response.text
+    raise RuntimeError(f"HTTP {response.status_code}: {detail}")
+
+
+def get_json(path: str, *, params: dict[str, Any] | None = None, timeout: float = 60.0) -> Any:
+    with httpx.Client(timeout=timeout) as client:
+        response = client.get(f"{api_base_url()}{path}", headers=_headers(), params=params)
+    _raise_for_error(response)
+    return response.json()
+
+
+def post_json(path: str, body: Any, *, timeout: float = 120.0) -> Any:
+    headers = {**_headers(), "Content-Type": "application/json"}
+    with httpx.Client(timeout=timeout) as client:
+        response = client.post(f"{api_base_url()}{path}", headers=headers, json=body)
+    _raise_for_error(response)
+    return response.json()
+
+
+# ── Nexus agent endpoints (admin only) ──────────────────────────────────────
+
+
+def get_run_config(tickers: str | None = None) -> Any:
+    """GET /nexus-agent/run-config/ — tickers + date range for this week's run."""
+    params = {"tickers": tickers} if tickers else None
+    return get_json("/nexus-agent/run-config/", params=params)
+
+
+def upload_market_analysis(ticker: str, content: str, language: str = "zh") -> Any:
+    """POST /nexus-agent/upload/market-analysis/"""
+    return post_json(
+        "/nexus-agent/upload/market-analysis/",
+        {"ticker": ticker, "content": content, "language": language},
+    )
+
+
+def upload_portfolio_recommendation(
+    content: str, content_cn: str | None = None, time_range: str | None = None
+) -> Any:
+    """POST /nexus-agent/upload/portfolio-recommendation/"""
+    body: dict[str, Any] = {"content": content}
+    if content_cn is not None:
+        body["content_cn"] = content_cn
+    if time_range is not None:
+        body["time_range"] = time_range
+    return post_json("/nexus-agent/upload/portfolio-recommendation/", body)
+
+
+def upload_backtest(ticker: str, levels: dict[str, Any]) -> Any:
+    """POST /nexus-agent/upload/backtest/ — levels: {aggressive/conservative/normal: {...}}"""
+    return post_json("/nexus-agent/upload/backtest/", {"ticker": ticker, **levels})
+
+
+def notify(
+    to: list[str], subject: str, body_text: str | None = None, body_html: str | None = None
+) -> Any:
+    """POST /nexus-agent/notify/ — send a notification email via server-side SES."""
+    body: dict[str, Any] = {"to": to, "subject": subject}
+    if body_text is not None:
+        body["body_text"] = body_text
+    if body_html is not None:
+        body["body_html"] = body_html
+    return post_json("/nexus-agent/notify/", body)

nexus_agent_cli-0.1.0/nexus_agent_cli/auth_pkce.py

@@ -0,0 +1,233 @@
+"""
+Cognito Hosted UI login via OAuth 2.0 Authorization Code + PKCE.
+
+Ported from nexusquant-cli. Nexus service reads ``custom:userType`` from JWT
+claims; the new agent endpoints require ``admin``. The CLI stores and sends the
+ID token as ``Authorization: Bearer``, refreshing via the Cognito refresh token
+when the ID token is near expiry.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import threading
+import time
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+
+import httpx
+
+from nexus_agent_cli.config import (
+    clear_credentials,
+    cognito_client_id,
+    cognito_domain_host,
+    load_credentials,
+    redirect_uri,
+    save_credentials,
+)
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(48)
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+def _parse_query(path: str) -> dict[str, str]:
+    query = urllib.parse.urlparse(path).query
+    return dict(urllib.parse.parse_qsl(query))
+
+
+def _token_url(domain_host: str) -> str:
+    return f"https://{domain_host}/oauth2/token"
+
+
+def _post_token(domain_host: str, body: dict[str, Any]) -> dict[str, Any]:
+    with httpx.Client(timeout=30.0) as client:
+        response = client.post(
+            _token_url(domain_host),
+            data=body,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+    if response.status_code >= 400:
+        try:
+            detail: Any = response.json()
+        except json.JSONDecodeError:
+            detail = response.text
+        raise RuntimeError(f"Cognito token endpoint error ({response.status_code}): {detail}")
+    return response.json()
+
+
+def refresh_tokens(*, domain_host: str, client_id: str, refresh_token: str) -> dict[str, Any]:
+    return _post_token(
+        domain_host,
+        {
+            "grant_type": "refresh_token",
+            "client_id": client_id,
+            "refresh_token": refresh_token,
+        },
+    )
+
+
+def exchange_code_for_tokens(
+    *,
+    domain_host: str,
+    client_id: str,
+    code: str,
+    redirect_uri_value: str,
+    code_verifier: str,
+) -> dict[str, Any]:
+    return _post_token(
+        domain_host,
+        {
+            "grant_type": "authorization_code",
+            "client_id": client_id,
+            "code": code,
+            "redirect_uri": redirect_uri_value,
+            "code_verifier": code_verifier,
+        },
+    )
+
+
+def run_browser_login() -> dict[str, Any]:
+    domain_host = cognito_domain_host()
+    client_id = cognito_client_id()
+    redirect_uri_value = redirect_uri()
+    verifier, challenge = _pkce_pair()
+
+    auth_params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri_value,
+        "scope": "openid email phone",
+        "code_challenge_method": "S256",
+        "code_challenge": challenge,
+    }
+    auth_url = f"https://{domain_host}/oauth2/authorize?{urllib.parse.urlencode(auth_params)}"
+
+    code_holder: dict[str, str | None] = {"code": None, "error": None}
+    done = threading.Event()
+
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, _format: str, *_args: object) -> None:
+            return
+
+        def do_GET(self) -> None:  # noqa: N802
+            params = _parse_query(self.path)
+            if "code" in params:
+                code_holder["code"] = params["code"]
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(
+                    b"<html><body><p>Nexus agent CLI login successful. You can close this tab.</p></body></html>"
+                )
+            else:
+                error = (
+                    params.get("error_description") or params.get("error") or "unknown_error"
+                )
+                code_holder["error"] = error
+                self.send_response(400)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(
+                    f"<html><body><p>Nexus agent CLI login failed: {error}</p></body></html>".encode(
+                        "utf-8"
+                    )
+                )
+            done.set()
+
+    parsed = urllib.parse.urlparse(redirect_uri_value)
+    if parsed.hostname not in ("127.0.0.1", "localhost") or not parsed.port:
+        raise RuntimeError("NEXUS_AGENT_REDIRECT_URI must be localhost with a port.")
+
+    bind_host = "127.0.0.1" if parsed.hostname == "localhost" else parsed.hostname
+    server = HTTPServer((bind_host or "127.0.0.1", parsed.port), Handler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    webbrowser.open(auth_url)
+
+    if not done.wait(timeout=300):
+        server.shutdown()
+        raise TimeoutError("No OAuth callback received within 5 minutes.")
+    server.shutdown()
+
+    if code_holder["error"]:
+        raise RuntimeError(f"Cognito error: {code_holder['error']}")
+    code = code_holder["code"]
+    if not code:
+        raise RuntimeError("No authorization code in callback.")
+
+    tokens = exchange_code_for_tokens(
+        domain_host=domain_host,
+        client_id=client_id,
+        code=code,
+        redirect_uri_value=redirect_uri_value,
+        code_verifier=verifier,
+    )
+    if "id_token" not in tokens:
+        raise RuntimeError("Cognito token response missing id_token.")
+    return tokens
+
+
+def persist_tokens(tokens: dict[str, Any]) -> None:
+    save_credentials(
+        {
+            "id_token": tokens["id_token"],
+            "access_token": tokens.get("access_token"),
+            "refresh_token": tokens.get("refresh_token"),
+            "expires_in": int(tokens.get("expires_in") or 0),
+            "saved_at": time.time(),
+        }
+    )
+
+
+def ensure_fresh_id_token(*, force_refresh: bool = False) -> str:
+    creds = load_credentials()
+    if not creds or not creds.get("id_token"):
+        raise RuntimeError("尚未登录。请先执行：nexus-agent auth")
+
+    expires_in = int(creds.get("expires_in") or 0)
+    saved_at = float(creds.get("saved_at") or 0)
+    remaining = saved_at + expires_in - time.time() if expires_in > 0 else 999999
+    refresh_token = creds.get("refresh_token")
+    if not force_refresh and (remaining > 120 or not refresh_token):
+        return str(creds["id_token"])
+    if not refresh_token:
+        return str(creds["id_token"])
+
+    try:
+        new_tokens = refresh_tokens(
+            domain_host=cognito_domain_host(),
+            client_id=cognito_client_id(),
+            refresh_token=refresh_token,
+        )
+    except RuntimeError as exc:
+        if "invalid_grant" in str(exc):
+            clear_credentials()
+            raise RuntimeError(
+                "Refresh token expired or revoked. Please run: nexus-agent auth"
+            ) from exc
+        raise
+    merged = {
+        "id_token": new_tokens.get("id_token") or creds["id_token"],
+        "access_token": new_tokens.get("access_token") or creds.get("access_token"),
+        "refresh_token": new_tokens.get("refresh_token") or refresh_token,
+        "expires_in": int(new_tokens.get("expires_in") or expires_in),
+        "saved_at": time.time(),
+    }
+    save_credentials(merged)
+    return str(merged["id_token"])
+
+
+def login_and_save() -> None:
+    persist_tokens(run_browser_login())

nexus_agent_cli-0.1.0/nexus_agent_cli/commands/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import typer
+
+from nexus_agent_cli.commands.auth.cmd import register as register_auth
+from nexus_agent_cli.commands.run.cmd import register as register_run
+
+
+def register_all(app: typer.Typer) -> None:
+    register_auth(app)
+    register_run(app)

nexus_agent_cli-0.1.0/nexus_agent_cli/commands/auth/cmd.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from nexus_agent_cli.auth_pkce import ensure_fresh_id_token, login_and_save
+from nexus_agent_cli.config import CREDENTIALS_PATH, clear_credentials, load_credentials
+
+console = Console()
+
+
+def register(app: typer.Typer) -> None:
+    @app.command(
+        "auth",
+        help=(
+            "Login with Cognito Hosted UI and save local tokens. Use --refresh to force "
+            "refresh, --status to inspect local login state, or --logout to clear tokens."
+        ),
+    )
+    def auth(
+        logout: bool = typer.Option(False, "--logout", help="Remove saved tokens and exit."),
+        refresh: bool = typer.Option(
+            False, "--refresh", help="Refresh the saved ID token using the refresh token."
+        ),
+        status: bool = typer.Option(
+            False, "--status", help="Print local login state without showing token values."
+        ),
+    ) -> None:
+        """Authenticate this machine (admin) for Nexus agent API calls."""
+        if logout:
+            clear_credentials()
+            console.print("[green]已退出登录（本机保存的 token 已清除）。[/green]")
+            raise typer.Exit(0)
+
+        if status:
+            creds = load_credentials()
+            if creds and creds.get("id_token"):
+                console.print(f"[green]已登录。本地凭据: {CREDENTIALS_PATH}[/green]")
+            else:
+                console.print("[yellow]尚未登录。请执行：nexus-agent auth[/yellow]")
+            raise typer.Exit(0)
+
+        try:
+            if refresh:
+                ensure_fresh_id_token(force_refresh=True)
+                console.print("[green]token 已刷新。[/green]")
+            else:
+                login_and_save()
+                console.print("[green]登录成功，token 已保存在本机。[/green]")
+        except Exception as e:
+            console.print(f"[red]{e}[/red]")
+            raise typer.Exit(1) from e

nexus_agent_cli-0.1.0/nexus_agent_cli/commands/run/cmd.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.json import JSON
+
+from nexus_agent_cli import api_client
+
+console = Console()
+
+
+def _run_err(e: Exception) -> None:
+    console.print(f"[red]{e}[/red]")
+    raise typer.Exit(1) from e
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("run-config", help="Pull this week's run params (tickers + date range).")
+    def run_config(
+        tickers: str = typer.Option(
+            None, "--tickers", help="Comma-separated override, e.g. TQQQ,SOXL,IBIT."
+        ),
+    ) -> None:
+        try:
+            data = api_client.get_run_config(tickers=tickers)
+        except Exception as e:
+            _run_err(e)
+        console.print(JSON(json.dumps(data)))
+
+    @app.command(
+        "push-market-analysis", help="Upload a market analysis markdown report for one ticker."
+    )
+    def push_market_analysis(
+        ticker: str = typer.Option(..., "--ticker", help="tqqq / soxl / ibit."),
+        file: Path = typer.Option(
+            ..., "--file", exists=True, readable=True, help="Path to the markdown report."
+        ),
+        language: str = typer.Option("zh", "--language", help="zh (default) or en."),
+    ) -> None:
+        try:
+            content = file.read_text(encoding="utf-8")
+            data = api_client.upload_market_analysis(ticker, content, language=language)
+        except Exception as e:
+            _run_err(e)
+        console.print(f"[green]已上传:[/green] {data.get('key')}")
+
+    @app.command(
+        "push-portfolio", help="Upload a portfolio recommendation report (English + optional CN)."
+    )
+    def push_portfolio(
+        file: Path = typer.Option(
+            ..., "--file", exists=True, readable=True, help="English markdown report."
+        ),
+        file_cn: Path = typer.Option(
+            None, "--file-cn", exists=True, readable=True, help="Chinese markdown report (optional)."
+        ),
+        time_range: str = typer.Option(
+            None, "--time-range", help="e.g. 2026-06-01_2026-06-14 (optional, for the S3 key)."
+        ),
+    ) -> None:
+        try:
+            content = file.read_text(encoding="utf-8")
+            content_cn = file_cn.read_text(encoding="utf-8") if file_cn else None
+            data = api_client.upload_portfolio_recommendation(
+                content, content_cn=content_cn, time_range=time_range
+            )
+        except Exception as e:
+            _run_err(e)
+        console.print(JSON(json.dumps(data)))
+
+    @app.command("push-backtest", help="Upload aggregated backtest JSON for one ticker.")
+    def push_backtest(
+        ticker: str = typer.Option(..., "--ticker", help="tqqq / soxl / ibit."),
+        aggressive: Path = typer.Option(
+            None, "--aggressive", exists=True, readable=True, help="aggressive_aggregated.json"
+        ),
+        conservative: Path = typer.Option(
+            None, "--conservative", exists=True, readable=True, help="conservative_aggregated.json"
+        ),
+        normal: Path = typer.Option(
+            None, "--normal", exists=True, readable=True, help="normal_aggregated.json"
+        ),
+    ) -> None:
+        levels: dict[str, object] = {}
+        for name, path in (
+            ("aggressive", aggressive),
+            ("conservative", conservative),
+            ("normal", normal),
+        ):
+            if path is not None:
+                try:
+                    levels[name] = json.loads(path.read_text(encoding="utf-8"))
+                except Exception as e:
+                    _run_err(e)
+        if not levels:
+            console.print("[red]至少提供一个档位文件: --aggressive / --conservative / --normal[/red]")
+            raise typer.Exit(1)
+        try:
+            data = api_client.upload_backtest(ticker, levels)
+        except Exception as e:
+            _run_err(e)
+        console.print(JSON(json.dumps(data)))
+
+    @app.command("notify", help="Send a notification email via server-side SES.")
+    def notify(
+        to: list[str] = typer.Option(..., "--to", help="Recipient (repeatable)."),
+        subject: str = typer.Option(..., "--subject", help="Email subject."),
+        body_file: Path = typer.Option(
+            None, "--body-file", exists=True, readable=True, help="Plain-text body file."
+        ),
+        body: str = typer.Option(None, "--body", help="Inline plain-text body."),
+    ) -> None:
+        body_text = body
+        if body_file is not None:
+            body_text = body_file.read_text(encoding="utf-8")
+        if not body_text:
+            console.print("[red]需要 --body 或 --body-file 之一。[/red]")
+            raise typer.Exit(1)
+        try:
+            data = api_client.notify(list(to), subject, body_text=body_text)
+        except Exception as e:
+            _run_err(e)
+        console.print(f"[green]已发送:[/green] {data}")

nexus_agent_cli-0.1.0/nexus_agent_cli/config.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+
+# 独立的凭据目录，避免与 strategy-provider 用的 nexusquant-cli 互相覆盖。
+CONFIG_DIR = Path(user_config_dir("nexus-agent-cli", appauthor=False))
+CREDENTIALS_PATH = CONFIG_DIR / "credentials.json"
+
+# 默认指向生产 nexus-service（与 nexusquant-cli 同一后端），admin 身份登录。
+DEFAULT_API_ENDPOINT = "https://api.nexusquant.co"
+DEFAULT_COGNITO_DOMAIN = "auth.lookatwallstreet.com"
+DEFAULT_COGNITO_CLIENT_ID = "5o7hhd4hn4birr8c29vndehiat"
+# 与 nexusquant-cli (8251) 错开端口，便于两套 CLI 同机登录。
+DEFAULT_REDIRECT_URI = "http://127.0.0.1:8252/callback"
+
+
+def _env(name: str, default: str | None = None) -> str | None:
+    value = os.environ.get(name)
+    if value is not None and value.strip():
+        return value.strip()
+    return default
+
+
+def api_base_url() -> str:
+    endpoint = (
+        _env("NEXUS_AGENT_API_ENDPOINT", DEFAULT_API_ENDPOINT) or DEFAULT_API_ENDPOINT
+    ).rstrip("/")
+    base_override = _env("NEXUS_AGENT_API_BASE_URL")
+    if base_override:
+        return base_override.rstrip("/")
+    return f"{endpoint}/api"
+
+
+def cognito_domain_host() -> str:
+    domain = (
+        _env("NEXUS_AGENT_COGNITO_DOMAIN", DEFAULT_COGNITO_DOMAIN) or DEFAULT_COGNITO_DOMAIN
+    )
+    return domain.removeprefix("https://").removeprefix("http://").split("/")[0]
+
+
+def cognito_client_id() -> str:
+    return (
+        _env("NEXUS_AGENT_COGNITO_CLIENT_ID", DEFAULT_COGNITO_CLIENT_ID)
+        or DEFAULT_COGNITO_CLIENT_ID
+    )
+
+
+def redirect_uri() -> str:
+    return _env("NEXUS_AGENT_REDIRECT_URI", DEFAULT_REDIRECT_URI) or DEFAULT_REDIRECT_URI
+
+
+def load_credentials() -> dict[str, Any] | None:
+    if not CREDENTIALS_PATH.is_file():
+        return None
+    try:
+        return json.loads(CREDENTIALS_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save_credentials(data: dict[str, Any]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_PATH.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    try:
+        CREDENTIALS_PATH.chmod(0o600)
+    except OSError:
+        pass
+
+
+def clear_credentials() -> None:
+    try:
+        CREDENTIALS_PATH.unlink(missing_ok=True)
+    except OSError:
+        pass

nexus_agent_cli-0.1.0/nexus_agent_cli/main.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from nexus_agent_cli import __version__
+from nexus_agent_cli.commands import register_all
+
+console = Console()
+app = typer.Typer(
+    name="nexus-agent",
+    help=(
+        "Nexus internal agent ops CLI. Login once with Cognito (admin), then pull "
+        "run params, push analysis results (market analysis / portfolio / backtest), "
+        "and send notifications — keeping S3/SES/Sheets credentials server-side. "
+        "Requires custom:userType=admin."
+    ),
+    no_args_is_help=True,
+)
+
+register_all(app)
+
+
+@app.command("version", help="Print this CLI package version string.")
+def version_cmd() -> None:
+    console.print(__version__)
+
+
+if __name__ == "__main__":
+    app()

nexus_agent_cli-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nexus-agent-cli"
+version = "0.1.0"
+description = "Nexus internal agent ops CLI — pull run params, push analysis results, send notifications. Admin only."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27",
+  "platformdirs>=4.2",
+  "rich>=13.7",
+  "typer>=0.12",
+]
+
+[project.scripts]
+nexus-agent = "nexus_agent_cli.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["nexus_agent_cli"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"