2.1 是什么、不是什么

• 是：A 股研究辅助工具，强调”研究结论、关键依据、风险揭示与情景分析”。
• 不是：交易指令系统。合规提示词明确禁止输出买卖/持有判断、目标价、止损止盈、仓位建议与择时结论。
• 许可：混合授权。tradingagents/、cli/、docs/、tests/ 为 Apache-2.0；app/、frontend/、core/ 为 source-available 专有组件，禁止再分发与商业使用。

2.2 版本演进

2.3 技术栈

2.4 代码规模（本快照）

合计约 52.4 万行。规模已经接近中型商业产品，理解成本主要来自”多代实现并存”，而不是单个模块的复杂度。

3.1 分层与组件

flowchart TB
    subgraph Client["客户端"]
        B["浏览器：Vue 3 SPA"]
        C["CLI：Typer"]
        X["外部系统：IM / MCP Client"]
    end

    subgraph Edge["接入层"]
        V["Vite dev server :3000<br/>/api 反向代理"]
        A["FastAPI :8000<br/>JWT / Session / 路由注册"]
    end

    subgraph App["应用服务层 app/"]
        AS["TaskAnalysisService"]
        Q["QueueService（Redis List）"]
        W["ThreadWorker（进程内消费者）"]
        UE["UnifiedAnalysisEngine"]
        IA["IntelligentAssistantService"]
        SC["ScreeningService"]
        SCH["SchedulerService（APScheduler）"]
    end

    subgraph Core["能力层 core/"]
        WE["WorkflowEngine<br/>validate → compile → execute"]
        LG["LangGraph StateGraph"]
        AR["AgentRegistry / AgentFactory"]
        TR["ToolRegistry（约 290 个注册点）"]
        SK["SkillRuntime / Sandbox"]
        MEM["MemoryService（mem0）"]
        LIC["LicenseManager（社区版 stub）"]
    end

    subgraph Engine["引擎与数据层 tradingagents/"]
        LLM["create_llm_by_provider"]
        DF["DataSourceManager / Toolkit"]
        PR["Prompt templates / 合规护栏"]
    end

    subgraph Infra["基础设施"]
        M[("MongoDB :27017")]
        R[("Redis :6379")]
        D["Tushare / AKShare / BaoStock / QMT / yfinance"]
    end

    B --> V --> A
    C --> LLM
    X --> A
    A --> AS
    AS --> Q --> W
    W --> AS
    AS --> UE --> WE --> LG
    LG --> AR
    AR --> TR
    AR --> MEM
    AR --> LLM
    TR --> DF --> D
    A --> SC
    A --> IA
    SCH --> Q
    A --> M
    Q --> R
    W --> M

3.2 目录职责

3.3 两代引擎的关系（关键）

这是理解本项目最重要的结构性事实。

证据：app/services/analysis_service.py 的 _get_trading_graph 直接 raise RuntimeError("TradingAgentsGraph 不再实例化")；app/services/unified_analysis_engine.py::_select_engine 拒绝 legacy；app/services/simple_analysis_service.py 的旧执行路径同样标记停用。因此：

• core/workflow 不是替换 LangGraph，而是替换了”把图写死在代码里”的做法，改为”从数据库读取图定义，再编译成 LangGraph”。
• tradingagents/ 仍然提供 LLM 工厂、数据源、提示词模板、Toolkit 等基础设施，并没有被整体废弃。
• 两套 LLM 栈并存：工作流 Agent 用 LangChain BaseChatModel（create_llm_by_provider），回测与工作流生成器用 core.llm.UnifiedLLMClient。

3.4 部署拓扑

flowchart LR
    U["浏览器"] -->|"3000 端口"| F["Vite / Vue"]
    F -->|"/api 代理"| B["Uvicorn :8000"]
    B --> M[("MongoDB :27017")]
    B --> R[("Redis :6379")]
    B -.->|"可选独立 Worker :8001"| W["AnalysisWorker"]
    W --> R
    W --> M
    B -->|"外部 API"| D["Tushare / AKShare / BaoStock / QMT"]

• start.sh：启动 ta-redis 容器（密码取自 .env）、检查 mongod、以 setsid 启动后端与前端，日志写入 logs/。
• deploy/systemd/：三个用户级 unit —— tradingagents-deps（等 MongoDB/Redis）、tradingagents-backend、tradingagents-frontend。
• start_dev.py：可用 --backend-only / --worker-only / --no-worker 控制进程；Windows 对应 start_backend.ps1 与 start_worker.ps1。
• 仓库内没有 Dockerfile、docker-compose 或 nginx 配置；systemd 的前端 unit 直接运行 npm run dev（Vite 开发服务器），而不是构建后的 dist/。

4.1 原则总览

4.2 配置即数据：三层来源与桥接

配置有三层，优先级随场景不同：

1. .env：数据库连接、JWT 密钥、管理员初始密码、端口、少量开关。它是启动前提，也是密钥的最后兜底。
2. MongoDB system_configs / llm_providers / model_catalog / prompt_templates / agent_configs / tool_configs / tool_agent_bindings / workflows：运行时权威来源，用户在 Web 设置页修改后即时生效。
3. config/*.json：社区版种子与数据库不可用时的后备；config/README.md 明确这些文件会被自动生成，修改前需备份。

app/core/config_bridge.py::bridge_config_to_env() 是这套设计的关键接缝：启动时把数据库中的厂商 API Key、默认快慢模型、数据源 token/超时/限流/TTL、系统运行时参数写入 os.environ，因为 tradingagents/ 的旧代码是通过环境变量读取配置的。桥接完成后再重新初始化 tradingagents 的 MongoDB 存储与定价表。这样既保留了”用户在界面改配置”的体验，又不用重写旧引擎的配置读取逻辑。

代价是配置来源多、排查链路长：同一个值可能同时存在于 .env、MongoDB、config/*.json 与环境变量中，且不同模块的优先级并不完全一致（例如厂商 Key 是 .env 优先，Tushare Token 是数据库优先）。排查配置问题时，应同时检查这四处。

4.3 Agent 即插件：注册表 + 工厂 + 元数据

一个 Agent 的最小定义是：

@register_agent
class MarketAnalystV2(AnalystAgent):
    metadata = AgentMetadata(
        id="market_analyst_v2",
        category=AgentCategory.ANALYST,
        inputs=[...],
        outputs=[AgentOutput(name="market_report", ...)],
        output_field="market_report",
        default_tools=["get_stock_market_data_unified"],
        max_tool_calls=3,
        execution_order=10,
        workflow_stage="analyst",
    )

AgentRegistry 保存类与元数据，AgentFactory.create() 负责实例化；当注册表中没有对应类、但数据库 agent_configs 中有配置时，回退到 UniversalAgent（完全由数据库配置驱动的通用 Agent）。工具绑定按”节点绑定 → 工作流绑定 → Agent 默认工具”三级解析（BindingManager.get_tools_for_node）。提示词按 agent_type/agent_name/preference_id 从模板库解析，失败时使用类内硬编码提示词。

这种设计的收益是新增一个角色通常不需要改编排代码：注册类、写元数据、在数据库绑定工具与提示词、在工作流里加一个节点即可。代价是行为高度依赖数据库状态，代码阅读只能看到”能力上限”，看不到”当前实际配置”。

4.4 工作流即数据：DSL 到 LangGraph

WorkflowDefinition 是一个可序列化的图：

• 节点类型：START、END、ANALYST、RESEARCHER、TRADER、RISK、MANAGER、CONDITION、PARALLEL、MERGE、DEBATE、POST_PROCESSOR。
• 边类型：NORMAL、CONDITIONAL。
• 节点可带 agent_id、config（角色、焦点、轮次引用）、position（前端画布坐标）。
• 工作流可带 input_config（表单字段）、output_config（产出物组装策略）、workflow_type。

运行时链路是：

WorkflowEngine.load() → WorkflowValidator.validate() → WorkflowBuilder.build()
   → LangGraph StateGraph.compile() → engine.execute(stream_mode="updates")

WorkflowBuilder 负责把每种节点翻译成 LangGraph 节点函数：普通 Agent 节点走 _create_agent_node，条件节点走条件边，PARALLEL/MERGE 做扇出/汇合，DEBATE 生成多轮条件边。状态 schema 默认动态生成（StateRegistry + StateSchemaBuilder），按 Agent 的输入输出字段合并并挂 reducer；生成失败时回退到 builder.py 中的静态大 schema。

4.5 契约驱动与报告聚合

Agent 元数据不仅用于展示，也用于报告组装：output_field 告诉引擎把结果写到哪个 state 字段，ReportAggregator 从元数据发现字段而不是硬编码字段名。这样新增分析师时，报告页与导出模块无需逐一改字段列表。质量门禁则在分析师产出后检查结构完整性，critical 时重试一次，仍失败则写入 quality_flags 并记录质量指标。

4.6 合规内建

合规不是事后过滤，而是提示词的一部分：

• compliance_prompting.py 定义通用禁止项与各角色输出要求；
• BaseAgent._apply_global_trading_advice_guard() 在每个 Agent 的最终提示词后追加统一约束；
• 报告文案、前端界面、用户手册统一使用”研究参考/情景分析”表述。

需要指出一个张力：旧的 SignalProcessor 仍要求 LLM 输出 买入/持有/卖出 与目标价，这与合规模板冲突。v3 的 Web 链路不再依赖该信号处理器，但 CLI 与旧引擎仍会调用它；在这条路径上，action 很可能因合规提示而退化为”持有”。

4.7 稳健性设计

• 数据源：DataSourceManager 从 MongoDB 读取按市场分类的优先级，逐级 fallback；缓存层有文件、MongoDB+Redis、自适应三种实现。
• LLM：UnifiedLLMClient 按 retry_times 指数退避；jdyun 厂商额外加 1 并发信号量与 3/6/12 秒退避；流式失败自动回退非流式。
• Agent：工具调用有最大轮次与分析师大类上限；报告有质量门禁；模板缺失有硬编码兜底。
• 任务：Redis 队列有 300 秒 visibility timeout、ack、失败集合、僵尸任务恢复与断点续跑接口。

4.8 渐进式迁移与社区/Pro 分离

代码里保留了清晰的”迁移痕迹”：多个模块头部标注 DEPRECATED 并写明替代文件与剩余引用数；core/compat/legacy_adapter.py 把旧 Toolkit 适配到新 ToolRegistry；_try_create_legacy_agent 直接返回 None。社区版则通过删除 app/pro/ 实现裁剪：app/router_registry.py 用 try/except ImportError 把 PRO_ROUTERS 降级为空列表，core/licensing/community_stub.py 让 require_pro/require_feature 放行或按 Free 配额限制。

4.9 工程协作约定

• 文档按”产品/用户/开发/运维/设计/知识/课程/博客/归档”分层，设计与归档目录强制带版本号（docs/README.md）。
• 数据库变更有版本化迁移（migrations/v*.py），要求幂等，启动时自动执行，失败只记录不阻断。
• 变更日志由 cliff.toml（git-cliff）生成；贡献需签署 CLA（CLA.md、CONTRIBUTING.md）。
• 测试以 pytest 为主，pytest.ini 默认排除 integration 标记与两个不稳定用例；e2e/ 提供 Playwright 场景。

5.1 Agent 运行时

core/agents/base.py::BaseAgent 是所有 Agent 的基类。它同时扮演两个角色：

1. LangGraph 节点：实现了 __call__(state)，引擎可以把实例直接当节点函数使用。
2. ReAct 执行器：execute(state) 由子类实现（分析师、研究员、经理、交易员、后处理器各有模板方法），内部通过 invoke_with_tools() 完成”提示词 → LLM → 工具调用 → 再提示 → 最终报告”的循环。

一次分析师执行的典型步骤：

读取 state（ticker、trade_date、上游报告、agent_context）
  → 解析提示词模板（DB 优先，失败回退）
  → 注入绑定知识与事实记忆
  → llm.bind_tools(可用工具)
  → 循环：LLM 返回 tool_calls → ToolRegistry 执行 → 结果回填
  → 生成结构化报告
  → 质量门禁校验（必要时重试一次）
  → 返回 state delta（如 {"market_report": "..."}）

关键点：

• 消息隔离：并行分析师各自维护 _market_messages、_news_messages 等独立消息列表，避免并行执行时消息互相污染。
• 工具上限：元数据 max_tool_calls 与运行时计数共同防死循环。
• 委派：invoke_agent() 支持 Agent 调用另一个 Agent，工厂会自动创建目标并继承同一 LLM。
• 记忆：MemoryManager.get_agent_memory() 注入历史经验；记忆关闭时返回 None，所有消费方都做了空值保护。

5.2 工作流引擎

core/workflow/engine.py::WorkflowEngine 的职责链：

节点执行时，_execute_agent_node_with_runtime() 会构造统一的 InvocationRequest，调用 Agent 后再把调用记录写入 MongoDB workflow_agent_invocations，附带 workflow_id、execution_id、thread_id、step_id、user_id 与可选执行轨迹。这是”可追溯”的主要落点。

工作流的持久化不是 LangGraph checkpointer，而是分层的业务记录：

• 定义：workflows + workflow_history（另有 data/workflows/*.json 文件后备）。
• 单次执行：WorkflowExecution 模型保存在引擎实例的 last_execution 上，随 API 返回。
• 单步调用：workflow_agent_invocations。
• 暂停/恢复：只有 Agent 工坊的会话图使用 MongoDB checkpoint（agent_builder_graph_sessions）；分析工作流没有 checkpointer，长任务恢复依赖任务表与队列。

5.3 LLM 接入

生产 Agent 通过 tradingagents/graph/trading_graph.py::create_llm_by_provider() 创建 LangChain ChatModel：

• openai / siliconflow / openrouter / ollama / jdyun 等走 ChatOpenAI 或 OpenAI 兼容适配器；
• google → ChatGoogleOpenAI；dashscope → ChatDashScopeOpenAI；deepseek → ChatDeepSeek；anthropic → ChatAnthropic；
• zhipu、volcengine、qianfan、custom_openai 走自定义 OpenAI 兼容工厂。

模型分”快思考”与”深思考”两类：分析师、研究员、交易员、风险辩论者用 quick；研究经理与风险评估师用 deep。quick_model_config / deep_model_config 支持分别指定 provider、model、base_url、api_key、temperature、max_tokens、timeout，因此可以混用厂商。volcengine 还支持按研究深度设置 reasoning_effort，快模型自动降两档。

另一套 core/llm/UnifiedLLMClient 提供统一的 chat/achat/chat_stream/astream 与工具循环，主要用于回测策略生成、工作流生成器等非 LangGraph 场景。适配器把各厂商的 tool_call 格式归一化（tool_normalizer.py）。

token 与成本统计在 tradingagents/config/config_manager.py::TokenTracker，写入 token_usage，价格来自 config/pricing.json；app/services/usage_statistics_service.py 再做按厂商/模型/日期的汇总。

5.4 数据与工具

数据访问有两层抽象：

1. DataSourceManager：按市场（A 股/美股/港股）维护数据源链，优先级来自 MongoDB system_configs.data_source_configs，默认文档顺序为 LOCAL > AKShare > Tushare > BaoStock；每个源有独立超时、限流、重试、缓存 TTL。MongoDB 缓存位于链首。
2. Toolkit：面向 Agent 的”统一工具”，一个工具内部按市场分派。例如 get_stock_market_data_unified 会剥离 .SZ/.SH/.BJ 后缀后判断 A/HK/US，再调用对应 provider。分析师只绑定统一工具，因此提示词与工作流不需要关心市场差异。

缓存有四层实现：文件缓存（JSON/pickle，MD5 key）、MongoDB+Redis 数据库缓存、自适应缓存（按配置选后端）、集成缓存（统一入口）。数据源失败时逐级降级，最终可能返回本地缓存或结构化错误。

A 股识别规则集中在 tradingagents/utils/stock_utils.py：6 位数字或 6位.SZ/SH/SS/XSHE/XSHG 视为 A 股；4–5 位数字（可带 .HK）视为港股；1–5 位大写字母视为美股。科创板 688、创业板 300/301、北交所 8xxxxx/4xxxxx/92xxxx 等前缀规则也在同文件。

5.5 记忆与知识

记忆分三代：

v3 的 scope 包括 conversation、user_preference、analysis_insight、skill_lesson、agent_builder_lesson、agent_experience、trade_pattern。分析工作流启动时，UnifiedAnalysisEngine._inject_memory_facts() 还会从 assistant_memory_facts 读取该股票未过期的”外部事实记忆”（带采集日期与来源），注入 memory_facts_summary，供多空辩论与风险评估引用。

知识库是标准 RAG：knowledge_finance 存金融知识，user_manual_v3 存用户手册；FinancialKnowledgeManager.search() 做语义检索 + 分类过滤（3 秒超时），retrieve_for_prompt() 取 top-k 片段注入提示词。助手与计划分析服务是主要调用方。

5.6 安全、合规与扩展边界

• 认证：POST /api/auth/login 校验用户后签发 JWT（1 小时）与 refresh token（7 天），同时在 user_sessions 建服务端会话；get_current_user 支持 Bearer JWT、Session Cookie、京东云 Basic Auth 三种方式，并要求 is_active 且 approval_status == approved。
• 授权：管理员路由用 _require_admin；Pro 能力用 require_pro / require_feature，社区版由 stub 放行或按 Free 配额限制。
• HITL：危险工具（CRITICAL_TOOL_IDS）在执行前写入 hitl_pending_operations，前端确认/拒绝后再继续；这套机制不依赖 LangGraph interrupt()，可跨 HTTP 请求存活。
• Skill 沙箱：AI 生成的 Skill 先经 AST 语法、黑名单调用、import 白名单、签名匹配校验，再在子进程隔离中执行（默认 30 秒超时，stdio 捕获）；脚本型 Skill 用 {baseDir} 替换与凭据注入，默认 60 秒超时。
• MCP：core/mcp/server.py 把 analyze_stock、get_report、chat_with_assistant、list_workflows、screen_stocks、get_market_overview 暴露为 MCP 工具；MCPApiKeyVerifier 把 Bearer API Key 映射到 user_id 并做日配额。
• IM 网关：core/gateway/ 提供飞书/QQ/钉钉/企业微信适配器与会话映射；社区版 app/routers/gateway.py 未注册，属于保留能力。

6.1 启动流程

app/main.py 没有应用工厂，模块导入时创建全局 app；lifespan 负责启动与关闭。启动步骤按顺序如下（每步大多包在 try/except 中，失败不阻断，只有配置校验会直接抛出）：

1. setup_logging() + validate_startup_config()：加载日志配置，校验必需配置；后者是唯一会中止启动的步骤。
2. init_db()：初始化 MongoDB 与 Redis，创建索引与 stock_screening_view 聚合视图。
3. MigrationRunner.run_pending()：执行未应用的 MongoDB 迁移（migration_history 记录）。
4. bootstrap_first_admin()：users 为空时用 .env 的 ADMIN_DEFAULT_PASSWORD 创建 admin。
5. import_bootstrap_config()：导入 install/community_bootstrap.json，仅对空集合生效，保证幂等。
6. 注册自定义工具、已启用的 Skill、外部 Skill、MCP 工具到 ToolRegistry。
7. bridge_config_to_env()：把数据库配置桥接为环境变量；重新初始化 tradingagents 的 MongoDB 存储与定价表。
8. 后台建索引：能力索引（CapabilityIndexService.ensure_index）与用户手册向量索引（UserManualManager.ensure_indexed），均延迟数秒执行，不阻塞启动。
9. ensure_system_prompt_templates()：补齐系统提示词模板。
10. initialize_builtin_workflows()：注册内置分析流配置（股票/持仓/ETF/复盘/组合健康度）。
11. start_thread_worker()：启动进程内任务消费者，20 秒超时。
12. TradingCalendarService.warm_up() + 可选行情回填。
13. 创建 AsyncIOScheduler，注册数据同步、新闻、自选分析、交易日历、HITL 过期清理等任务；未启用的任务加入后立即 pause_job。

关闭时依次停止线程池同步服务、财务同步服务、ThreadWorker、APScheduler、告警服务、用户服务，最后 close_db()。

首次登录前还需要在设置页配置 LLM API Key 与行情 Token；没有 Key 时系统能启动，但分析任务会在 LLM 调用处失败。

6.2 单股研究的端到端流程

这是系统最长、最能体现架构的一条链路。

sequenceDiagram
    autonumber
    participant U as 浏览器
    participant F as Vue 前端
    participant A as FastAPI 分析路由
    participant T as TaskAnalysisService
    participant Q as Redis 队列
    participant W as ThreadWorker
    participant E as UnifiedAnalysisEngine
    participant G as WorkflowEngine
    participant AG as Agents 与 Tools
    participant DB as MongoDB

    U->>F: 提交单股研究
    F->>A: POST /api/analysis/single
    A->>T: create_task()
    T->>DB: 写入 unified_analysis_tasks (pending)
    T->>Q: HSET qa:task:{id} + LPUSH qa:ready
    A-->>F: {task_id, status: pending}
    loop 每 1 秒
        W->>Q: RPOP qa:ready
    end
    W->>Q: 移入 qa:processing，设置 visibility timeout 300s
    W->>T: execute_task(task, wrapped_progress_callback)
    T->>E: execute_task()
    E->>G: _execute_via_workflow → WorkflowAPI.execute (to_thread)
    G->>AG: 按图执行节点（并行/辩论/串行）
    AG->>DB: 工具取数、缓存读写、调用记录
    AG-->>G: state delta
    G-->>T: 最终 state
    T->>DB: 写入 analysis_reports，任务置 completed
    W->>Q: ack_task → qa:completed
    loop 前端轮询
        F->>A: GET /api/analysis/tasks/{id}/status
        A-->>F: progress / current_step / message
    end
    F->>A: GET /api/analysis/tasks/{id}/result

具体步骤与代码位置：

1. 提交：app/routers/analysis.py::submit_single_analysis（约 248 行）。默认引擎为 AnalysisEngine.V2；显式传 legacy 会被 400 拒绝；ETF 代码会路由到 ETF_ANALYSIS 任务类型。
2. 建任务：TaskAnalysisService.create_task() 生成 task_id、写入 unified_analysis_tasks，同时在 MemoryStateManager 建一份内存态快照。
3. 入队：QueueService.enqueue_task() 写 qa:task:{id} 哈希并 LPUSH qa:ready，HTTP 立即返回。
4. 消费：ThreadWorker._queue_loop() 每 1 秒 RPOP，把任务移入 qa:processing，设置 qa:visibility:{id}（300 秒）；_process_task_async() 先做 JIT 数据同步（jit_sync_stock_data），再调用 TaskAnalysisService.execute_task()。
5. 执行：TaskAnalysisService.execute_task() 构造 wrapped_progress_callback，每次进度更新写 MongoDB 并检查取消标记；然后调用 UnifiedAnalysisEngine.execute_task()。
6. 选引擎：UnifiedAnalysisEngine._select_engine() 只允许 workflow 或 auto；_execute_via_workflow() 解析 workflow_id（数据库默认流 → 注册表 → 系统模板），通过 WorkflowAPI.execute() 在工作线程中执行，进度回调用 asyncio.run_coroutine_threadsafe 回到主事件循环。
7. 编译与执行：WorkflowEngine.load() → validate() → compile() → execute()；WorkflowAPI._prepare_system_variables() 在启动时统一准备公司名、行业、当前价、市场/币种、分析维度等系统变量，_prepare_inputs() 注入辩论/风险轮次与记忆开关。
8. 节点执行：LangGraph 按图调度；每个 Agent 节点经 AgentFactory 创建实例，BaseAgent.__call__ 执行 execute(state)；分析师并行取证，辩论节点多轮往返，经理节点汇总，风险节点质证。
9. 结果处理：TaskAnalysisService._format_analysis_result() 规范化结果，_save_to_analysis_reports() 写 analysis_reports；可选进行成长记录提取与邮件通知；任务状态置 completed、进度 100。
10. 确认与观察：QueueService.ack_task() 把任务移入 qa:completed 或 qa:failed；前端轮询状态与结果接口。

6.3 工作流内部的八个阶段

默认模板 core/workflow/templates/v2_stock_analysis_workflow.py（id=v2_stock_analysis）定义了如下结构：

flowchart LR
    S["start"] --> P["parallel_analysts"]
    P --> A1["大盘分析师"]
    P --> A2["板块分析师"]
    P --> A3["市场分析师"]
    P --> A4["基本面分析师"]
    P --> A5["新闻分析师"]
    P --> A6["社交媒体分析师"]
    A1 --> M["merge_analysts"]
    A2 --> M
    A3 --> M
    A4 --> M
    A5 --> M
    A6 --> M
    M --> D["debate：乐观 vs 审慎"]
    D --> RM["research_manager"]
    RM --> RD["risk_debate：高弹性 / 防御 / 基准"]
    RD --> RJ["risk_manager"]
    RJ --> T["trader：研究整合员"]
    T --> E["end"]

“研究深度”是 5 档，影响辩论轮次与风险路径：

后两档的”风险自我辩论”由 _risk_self_debate 开关控制，可用环境变量 RISK_SELF_DEBATE=on/off/auto 一键回退到三角色串行路径。

6.4 智能助手与通用研究

助手链路与单股分析不同：它不建队列任务，而是同步/流式地完成一次工具调用对话。

1. 前端 POST /api/assistant/chat/stream（app/routers/intelligent_assistant.py 约 411 行），使用 frontend/src/utils/fetchSSE.ts 读取流。
2. IntelligentAssistantService.stream_chat_with_assistant()（约 4718 行）组装系统提示词、用户偏好、项目记忆、知识库片段与可用工具，进入 LLM 工具循环。
3. 工具调用经 ToolRegistry 执行；涉及危险操作时走 HITL 确认；每次工具结果作为 SSE 事件推给前端。
4. 回答返回前经过 core/assistant/reply_gate.py::ReplyGate 统一质量出口：证据集校验、反捏造防御（defense.py）、路径注册表（paths.py）与股票名词典门禁（lexicon.py）。
5. 对话结束后，后台提取可复用事实写入记忆（assistant_memory_facts / mem0），供后续分析引用。

通用研究（/analysis/general）走计划分析服务 PlannedAnalysisService，先生成研究计划，再逐步执行并通过 SSE 输出。

6.5 股票筛选

• 条件筛选：POST /api/screening/run → ScreeningService.run()；条件被翻译为 pandas 表达式，在 MongoDB stock_screening_view 上取数后本地计算，返回命中股票与字段值。
• 智能筛选：POST /api/screening/intelligent/* → IntelligentScreeningService；自然语言先被 LLM 解析为结构化条件（字段、算子、值），再复用条件筛选；进度通过 WebSocket 推送。
• 因子与预设：factor_registry、screening_presets、supported-fields 等接口提供可用字段与模板。

6.6 定时任务与数据同步

SchedulerService 包装 APScheduler，任务定义集中在 app/main.py 的 lifespan：

• 多源股票基础信息同步、行情摄入、Tushare/AKShare/BaoStock 各类历史与财务同步、ETF 同步；
• 新闻抓取、自选股分析、月度模拟盘回测；
• 交易日历刷新（18:30）、HITL 过期清理（30 分钟）、Skill 审核过期清理（30 分钟）。

每个任务由 *_ENABLED 配置控制；关闭时不是不注册，而是注册后立即 pause_job。执行历史写 scheduler_executions / scheduler_history，并在 Redis 做短期缓存。启动时 SchedulerService.check_suspended_tasks_on_startup() 会恢复被挂起的任务。

6.7 失败、重试与恢复

• 队列层：任务出队后进入 qa:processing，visibility timeout 300 秒；未 ack 的任务可被重新拾取。QueueService.cleanup_expired_tasks() 清理超时任务。
• 任务层：TaskAnalysisService 在进度回调中检查取消标记，支持取消、重试、标记失败；/api/v2/tasks/{id}/resume 支持断点续跑。
• 执行层：LLM 调用有指数退避；数据源逐级 fallback；分析师报告质量门禁失败重试一次；模板/记忆/知识检索失败均降级为空或默认值。
• 进程层：独立 AnalysisWorker 有心跳与 _recover_stuck_tasks()；但默认 start.sh/systemd 只启动后端，由进程内 ThreadWorker 消费队列，独立 Worker 属于可选部署。

改进建议

• 收敛入口：以 WorkflowEngine 为唯一生产编排，给 legacy 模块加运行时告警与删除时间表；三个队列消费者只保留一个默认实现。
• 统一事件通道：为任务状态建 outbox/Redis Stream，前端统一用 SSE；轮询作为降级方案，而不是主方案。
• 固化前端交付：vite build 产物由 nginx/Caddy 托管，补齐 Dockerfile 与 compose；systemd 不再跑 dev server。
• 注册全局中间件：至少为 /api 加认证兜底与限流；把 AuthGuardMiddleware 或逐路由依赖二选一，避免”看起来有、实际没有”。
• 配置单一事实源：数据库为唯一运行时来源，.env 只保留密钥与连接串；Toolkit 改为实例级配置。
• 补 CI：至少跑 pytest -m "not integration" 的 smoke 子集、迁移 dry-run、前端 vue-tsc && vite build。
• 为工作流加 checkpointer：长任务支持真正的暂停/恢复，减少对队列 visibility timeout 的依赖。