AI代理交易控制平台

代理控制平面

本地MCP本地控制平面，用于测试AI代理在以下情况下的交易行为 政策检查, 风险解释, 人类认可, 模拟执行，以及 审计回放.

需求

• python 3.11+ （需要 StrEnum, mcp，以及打印堆栈）。
• 用于web UI的节点20+。

设置

cd ai-project
python3.11 -m pip install -e ".[dev]"
npm run install:web

环境

运行API（仪表板后端）

export FINANCE_DB_PATH="$PWD/data/finance.db"
python3.11 -m uvicorn api.main:app --reload --host 127.0.0.1 --port 8001

运行web UI

从 仓库根目录:

npm run dev

或者： cd web && npm run dev.

打开 http://127.0.0.1:5173.Vite代理 /api 到 8001.

你需要 二 过程： uvicorn （8001）和 npm run dev (5173).

评估场景（代理回归）

JSON文件 scenarios/eval/ 由...运营 finance_core.eval_runner （参见 tests/test_eval_scenarios.py).

python3.11 scripts/run_eval.py

MCP服务器（光标/克劳德桌面）

使用相同 FINANCE_DB_PATH 作为API。可选： FINANCE_QUOTE_BACKEND=yahoo MCP中的实时报价。

{
  "mcpServers": {
    "finance-market": {
      "command": "python3.11",
      "args": ["/absolute/path/to/ai-project/servers/market_mcp.py"],
      "env": {}
    },
    "finance-portfolio": {
      "command": "python3.11",
      "args": ["/absolute/path/to/ai-project/servers/portfolio_mcp.py"],
      "env": {
        "FINANCE_DB_PATH": "/absolute/path/to/ai-project/data/finance.db"
      }
    }
  }
}

工具： get_quote, list_symbols · get_state, place_order （可选 order_kind 市场/限额， limit_price), cancel_order, list_recent_orders, list_recent_fills, get_risk_metrics，代理+回溯测试助手。

数量/ML（与API相同的DB）： list_quant_strategies, set_quant_strategy_active, run_quant_strategies_once, list_quant_signals, start_quant_engine, stop_quant_engine, get_quant_engine_status, finance_stack_health, get_ml_alpha_diagnostics, get_strategy_diagnostics, get_risk_snapshot, stress_portfolio, reconcile_ledger_vs_broker, forward_strategy_signals_to_alpaca （需要 SIGNALS_TO_ALPACA=1), create_pending_order_intent, list_pending_order_intents, approve_pending_order_intent。代理可以设置 allowed_mcp_tools （JSON数组）在使用时限制这些工具 agent_id.

REST（已选择）： GET /api/risk/snapshot, POST /api/risk/stress, GET /api/broker/reconciliation, GET /api/execution-events, GET /api/execution-events/replay, POST /api/order-intents, GET /api/order-intents/pending, POST /api/order-intents/{id}/approve|reject, POST /api/strategies/forward-signals-alpaca （标记）。政策： max_gross_exposure_multiple, slippage_impact_bps_per_million.Env： HEALTH_CHECK_ALPACA, SIGNALS_TO_ALPACA, BROKER_EXECUTION_MODE (internal 或 alpaca_paper)（参见 .env.example).

看 IMPLEMENTATION_PLAN.md 关于发货内容与可选的后续步骤。

脚本演示（无LLM）

export FINANCE_DB_PATH="$PWD/data/finance.db"
python3.11 scripts/demo_scenario.py

测试和CI

python3.11 -m pytest tests/ -v
ruff check api packages/core servers scripts tests

GET /api/health 检查SQLite(SELECT 1)并报告策略引擎线程是否正在运行；回报 503 如果数据库检查失败。CI运行全套（包括MCP导入烟雾和 ml_alpha 抵制指标测试）。

GitHub操作(.github/workflows/ci.yml): 颈毛, 测试 (FINANCE_QUOTE_BACKEND=mock), 网页构建.

生产Docker部署

docker build -t agent-control-plane .
docker run --rm \
  -e FINANCE_DB_PATH=/app/data/finance.db \
  -e FINANCE_QUOTE_BACKEND=mock \
  -e REQUIRE_AUTH=false \
  -p 8000:8000 \
  -v agent-control-plane-data:/app/data \
  agent-control-plane

该容器从一个来源为登录页、React应用程序、API、WebSocket和静态资产提供服务：

• 登录页面： http://localhost:8000/
• 应用程序： http://localhost:8000/app
• 健康检查： http://localhost:8000/api/health

为了快速公开部署，请使用附带的 render.yaml 蓝图。从这个GitHub仓库创建一个新的渲染蓝图；Render将构建Dockerfile，在 /app/data，并使用 /api/health 作为健康检查。

安全

看 安全.md 信任边界和演示限制。

布局