StockSenate

多角色投研合议系统
7 角色研报 · 多空辩论 · 三档风控 · 投决终审 · 回测推演

研究框架，不是投资产品 · 不接实盘 · 不输出可执行价位

StockSenate 是自研的 A 股多角色投研合议系统： 7 位分析师并行产出研报，经多空辩论、研究经理汇总、交易员提案、三档风控审查，由组合经理终审； 数据采集不在议事层实现，统一交给 TickHub-CN / TickHub-US / Newsieve 提供， StockSenate 自身只负责「多智能体合议 + 回测推演」。

• 完整合议链路：7 分析师 → 多空辩论 → 研究经理 → 交易员 → 三档风险辩论 → 投资经理终审 → 质量门控，节点与输出契约稳定。
• 数据层独立：议事层不直连东财/巨潮/通达信；DataAccessLayer 统一消费 TickHub-CN（A 股）、TickHub-US（美/港股）、Newsieve（资讯），也可离线读取本地 JSON、文本与 SQL。
• 生产级增强：Pydantic 输出强约束、单节点局部重试、辩论收敛、增量分析、上下文压缩、长期反思记忆、安全护栏、HITL 审批（CLI + WebUI）、LLM-as-a-Judge、全链路追踪、任务熔断、告警引擎、批量队列、独立 WebUI、MCP Server。
• 一套环境装全部模型：MiniMax / DeepSeek / Qwen / GLM / OpenAI / Anthropic / Google / xAI / OpenRouter / Ollama / OpenAI 兼容网关。

定位边界：本项目面向研究与教学，不构成投资建议，不提供荐股服务。 框架内没有建仓价、止损位、目标价、仓位比例这类输出——不是默认关闭，是设计上不做。 所有 AI 生成内容均可能有误，投资决策请咨询持牌专业机构。

能力一览

架构

┌───────────────────────────┐   ┌───────────────────────────┐   ┌───────────────────────────┐
│  StockSenate WebUI        │   │  StockSenate MCP Server   │   │  数据底座控制台（外部）      │
│  独立进程 · 127.0.0.1:8788 │   │  stdio / http :8765       │   │  TickHub Admin :8787      │
└─────────────┬─────────────┘   └─────────────┬─────────────┘   └─────────────┬─────────────┘
              │                               │                               │
              └───────────────┬───────────────┘                               │
                              ▼                                               │
                 ┌──────────────────────────┐                                 │
                 │  SenateGraph 工作流       │   只读展示数据状态 + 跳转          │
                 │  7 分析师 → 多空辩论      │                                 │
                 │  → 研究经理 → 交易员      │                                 │
                 │  → 三档风控 → 投决终审    │                                 │
                 └────────────┬─────────────┘                                 │
                              ▼                                               │
                 ┌──────────────────────────┐                                 │
                 │  DataAccessLayer         │                                 │
                 │  DataEnvelope + 路由 +    │                                 │
                 │  溯源 + 降级标记          │                                 │
                 └────────────┬─────────────┘                                 │
                              ▼                                               │
        ┌─────────────────────┴─────────────────────┐                          │
        ▼                     ▼                     ▼                          │
  TickHub-CN (A 股)     TickHub-US (美/港股)    Newsieve (资讯)  ◄──────────────┘
  MCP stdio/http        MCP stdio/http          MCP stdio/http
  或 local import       或 local import          或 local import
        │                     │                     │
        └──────────┬──────────┴──────────┬──────────┘
                   ▼                     ▼
            本地 JSON 归档          文本 / SQL（只读）

职责边界

角色体系

默认 7 个分析师全部内置，role_llms 键位固定如下：

自定义角色通过 config/agent_roles.toml 声明，上限默认 12 个（7 内置 + 5 自定义）。 新增角色必须定义：名称与提示词、工具白名单、Pydantic 输出 Schema、模型层级、阶段、是否参与辩论及权重。 自定义角色失败可跳过主流程，报告标注 partial。

安装

需要 Python ≥ 3.11（与 TickHub-CN 保持一致）。

pip install stocksenate              # 核心
pip install "stocksenate[all]"       # 全功能
pip install -e ".[dev]"              # 开发

可选 extras：stockdata（TickHub 本地直连）、mcp（MCP Server）、webui（Starlette + uvicorn 控制台，见 DEC-008）、all。回测为纯 Python 实现，无独立 extra。

cp .env.example .env          # 按文件内【必填】备注填写，模板不含任何真实密钥
ssenate config validate       # 启动时自动读取当前目录的 .env；已导出的变量优先

快速开始

命令行

# 单标的分析
ssenate analyze 600000 --date 2024-12-31

# 动态启停角色 / 调权重
ssenate analyze 600000 --date 2024-12-31 --disable custom_macro
ssenate analyze 600000 --date 2024-12-31 --enable custom_macro --weight 0.6

# 角色管理
ssenate role list
ssenate role show fundamentals
ssenate role validate
ssenate role enable custom_macro
ssenate role disable custom_macro

# 回测（基于已保存决策记录）
ssenate backtest run --code 600000 --start 2024-01-01 --end 2024-12-31

# 告警
ssenate alert list
ssenate alert rules validate

# 报告版本 Diff
ssenate report diff --code 600000 --from 2024-11-30 --to 2024-12-31

# 批量队列
ssenate queue status
ssenate queue submit --file tasks.csv

# 配置
ssenate config validate
ssenate config migrate

# MCP Server
ssenate mcp stdio
ssenate mcp http --port 8765

# 独立 WebUI
ssenate webui --host 127.0.0.1 --port 8788

完整命令、参数与退出码以 ssenate --help 及各子命令的 --help 为准； 退出码常量定义在 src/stock_senate/cli.py。

Python API

from stock_senate import SenateGraph

graph = SenateGraph()
final_state, decision = graph.propagate(code="600000", date="2024-12-31")
print(decision["rating"], decision["reason"])

• propagate(code, date) 返回 (final_state, decision) 二元组，签名稳定。
• TradingAgentsGraph 保留为 SenateGraph 的别名。
• summary.json、complete_report.md 是衍生输出，不替代返回值。

旧命令兼容

tradingagents analyze 600000     # 可用，启动时打印弃用警告并提示迁移到 ssenate

配置

所有配置集中在 config/，运行时合并用户目录 ~/.stock_senate/：

• 旧目录 ~/.tradingagents/ 在首次启动时只读扫描并迁移到 ~/.stock_senate/，旧目录不删除。
• 环境变量前缀 STOCKSENATE_*；同时兼容读取旧前缀 TRADINGAGENTS_*，新前缀优先。
• 所有配置文件提供 JSON Schema 校验与迁移脚本（ssenate config validate / ssenate config migrate）。

工作流增强开关（config/workflow.toml）

数据接入

DataAccessLayer 输出统一 DataEnvelope：

class DataEnvelope(BaseModel):
    domain: str  # kline / financial / announcement / research / risk_event ...
    code: str
    data_as_of: date
    payload: dict
    source: str  # tickhub_cn / tickhub_us / json / text_doc / sql
    source_detail: str
    fetched_at: datetime
    freshness: str  # realtime / cached / archive
    confidence: str  # high / medium / low
    data_source_status: str  # ok / degraded / missing

四种模式（config/data_source.toml）：

硬约束：

• 数值类数据（财务、K 线、资金）只允许来自数据底座或结构化数据库，禁止从 TXT/PDF/Word 抽取。
• 文本类数据只用于公告、研报、政策、新闻分析。
• 实时采集默认关闭；开启后必须带超时、降级与防重复采集锁。
• 本地源不可用不得静默返回空，必须标记 data_source_status=missing|degraded。

WebUI 与 MCP

独立 WebUI

ssenate webui --host 127.0.0.1 --port 8788

独立进程、独立端口、独立鉴权；默认只监听本机，未配置鉴权令牌时拒绝写操作。 页面：分析工作台、辩论过程、最终报告、历史记录、报告 Diff、回测中心、告警面板、角色管理、工作流拓扑、批量队列、人工审批、配置校验、数据状态只读卡。

运维监控不在本界面重复建设，只做只读展示并跳转数据底座控制台（默认 :8787）。

MCP Server

ssenate mcp stdio          # 供 Cursor / Claude Desktop 等客户端
ssenate mcp http --port 8765

• stdio 模式 stdout 只输出 MCP 协议报文，所有日志走 stderr。
• http 模式默认 127.0.0.1，对外必须鉴权。
• 与数据底座的 MCP 分开命名、分开鉴权、分开日志，通过 trace_id 串联。
• 暴露工具：分析任务、回测、告警查询、报告查询、配置查询。

回测与 performance 的区别

不要把 performance 当回测，也不要把回测当策略业绩。

兼容与迁移

项目资料

需求基线、产品规格、逐任务验收证据与架构决策记录由团队私有归档保管，不随仓库发布。 仓库内以本 README、NOTICE（第三方归属与许可证）和源码内联说明为唯一描述。

开发

pip install -e ".[dev]"
pytest -q
ruff check .
mypy src
python -m build

测试口径：pytest 只依赖 .[dev]，不安装任何可选 extra，也不需要外部服务、网络或 API Key；用例全部走本地 fixture 与 offline provider，当前 341 例全部通过。 Windows 传统控制台（PYTHONIOENCODING=cp1252）下 role list --output json 依然输出 UTF-8 JSON。

CI 覆盖：pytest + ruff + mypy + pip-audit + 全提供商同环境 import smoke test + 打包检查。 依赖锁定使用 uv.lock；发布包只声明最小依赖范围。

License

Apache License 2.0。本项目为独立实现，研究框架的语境与术语受 TradingAgents 论文启发； TradingAgentsGraph 兼容别名仅为接口便利，不包含第三方项目源码。 归属与第三方许可证声明见 NOTICE。