PYTA Research
多市场 AI 推演引擎

面向投资研究场景的有状态多市场 AI 推演系统。
两种完全独立的分析模式：一级市场（VC/PE 深度尽调）与 二级市场（多 Agent 并行模拟）。
每次推演持久化为 Checkpoint，支持多轮累积、断点恢复、全链路审计。

1双市场模式

PYTA 支持两条完全独立的分析流水线，通过 MarketModeSelector 在 UI 中一键切换。

2一级市场：4 层 DAG 引擎

DAG 执行图

推演数据流

前端提交公司信息 + 投资人画像 + 参照系
  → POST /api/v1/primary/run-stream (SSE)
  → PrimaryOrchestrator.run()
      → [一次性] CompetitiveLandscapeAgent (G3)
      → [一次性] FounderAnalysis (G2) + KeyAssumptions
      → 第 N 轮循环:
          → 6 维度 Agent (通过 DimensionRegistry)
          → FinancialLens: G4 单位经济 + G6 估值
          → AssumptionChecker → PathForkService
          → ConvergenceJudge (语义三门停止)
          → [可选] HITL Gate (环境修正提案)
          → Checkpoint 持久化
      → L2-L3: 上下文组装 + Lens 校准 + 决策合成
  → SSE 流式推送 → 前端 DAG + Deep Dive

三门停止条件（语义化）

DimensionRegistry（数据驱动，PR #116/#117）

维度通过 DimensionDescriptor 冻结数据类定义在中央注册表中，替代了隐式的枚举遍历。维度 ID 使用纯字符串（非 enum），新增维度只需在 build_default_registry() 中添加一行，无需修改任何 enum 定义。

Registry API

2.5V2 推演引擎生命周期

一次 POST /primary/run 的完整生命周期。默认最多 3 轮，每轮串行跑 6 个维度 Agent，然后经过假设验证 → 路径分叉 → 收敛判定。

多轮推演流程

三个 Abort Gate

每轮结束后按顺序检查，命中任一即停止迭代：

Health Check（每轮）

PathFork — 5 种分叉触发

PathForkService 在每轮末尾检查以下条件。触发时生成替代路径分叉（scenario_if_holds / scenario_if_fails），记入最终报告。

HITL Gate（Human-in-the-Loop）

Checkpoint & Restore

3G1-G6 加固模块

6 个结构化分析模块，覆盖从公司画像到估值分析的完整 VC 决策链。

4Deep Dive 审计层

不是"换个地方展示数据" — 而是推理过程的审计层。 让用户回溯"系统为什么得出这个结论"，每一步的输入、推导、校准都可追溯。

8 个 Section 布局（右侧 slide-over · 单列可折叠）

设计原则

• 单列可折叠纵向流 — 审计文档是线性阅读的，不是 dashboard
• Per-round ReasoningTrace 携带完整 Agent 输出（score、confidence、narrative、signals、矛盾检测）
• 收敛轨迹 Sparkline：每个维度一条横向折线，显示跨轮 score 演化
• 无数据时显示占位符（"数据待补充"）而不是隐藏 section
• 一键 Markdown 导出完整推理轨迹

5二级市场：Agent 沙盘

单轮并行模拟。输入市场事件后，4 个 Agent 同时推演。

执行模型

输入：标的 + 市场事件
  → SecondaryOrchestrator.run()
      → 拉取市场数据 (yfinance, DB 缓存)
      → 4 个 Agent 并行推演 (asyncio.gather)
      → 超时/失败：复用上轮视角或注入默认视角
      → 持久化 AgentSnapshot → SandboxEventRecord
      → InteractionResolver: 聚合多空博弈关系
  → 输出：MarketReadingReport + InteractionResolution

6感知层

推演前的信息预处理阶段 — 正式推演开始前的前置准备。

感知状态机

PENDING → IN_PROGRESS → COMPLETE
                  ↓
              confidence_gate.check()
                  ↓
          通过：进入推演流程
          未通过：请求补充数据或用户输入

7数据源接入系统

通过三策略提供商识别实现自动化数据源集成。

8技术栈

9系统架构图

10代码地图

开发时 80% 的时间在这些文件。

目录结构概览

pyta-research/
+-- src/
|   +-- api/                        # FastAPI 路由层
|   |   +-- routers/primary.py       # 一级市场核心 API
|   |   +-- routers/sandbox.py       # 二级市场 API
|   +-- sandbox/                    # 推演引擎核心
|   |   +-- orchestrator/primary.py  # DAG 编排器
|   |   +-- orchestrator/secondary.py# Agent 沙盘
|   |   +-- agents/templates/        # LLM prompt 模板
|   |   +-- schemas/                 # Pydantic 数据结构
|   |   |   +-- primary_market.py    # 核心数据结构
|   |   |   +-- dimension_registry.py# 维度注册表（单一数据源）
|   |   |   +-- investor_profile.py  # 投资人配置
|   |   +-- services/                # 业务逻辑
|   |   |   +-- convergence.py       # 语义收敛
|   |   |   +-- context_assembler.py # S 曲线 + 投资人
|   |   |   +-- path_fork.py         # 路径分叉（5 触发类型）
|   |   +-- tools/                   # Agent 工具框架
|   |   +-- llm/client.py            # LLM 客户端
|   +-- perception/                 # 推演前预处理
|   |   +-- intake_agent.py          # ReAct 数据接入
|   |   +-- intake_orchestrator.py   # 任务编排
|   |   +-- confidence_gate.py       # 质量预检
|   +-- data/connectors/            # 数据源接入系统
|   +-- db/models.py                 # 数据库表定义
+-- frontend/src/
|   +-- pages/ResearchCanvasPage.tsx  # 顶层入口
|   +-- components/layout/           # 布局组件
|   +-- components/canvas/primary/   # 一级市场 UI
|   +-- hooks/usePrimaryRun.ts       # 一级市场状态管理
|   +-- hooks/useSandboxRun.ts       # 二级市场状态管理
|   +-- lib/api/primary.ts           # API 客户端 + 映射
|   +-- lib/types/primaryCanvas.ts   # 类型定义
+-- tests/                           # pytest（34 unit + 35 extensibility + 2 integration）
+-- frontend/tests/                  # Playwright E2E
+-- alembic/versions/                # 10 个 DB migration

11开发全流程

从领取任务到代码合并的完整步骤。

12分支与命名规范

分支命名

Commit 信息规范

• feat: 新增 G7 行业分析模块，补全行业周期判断能力
• fix: 修复 SSE 超时后前端未重连，导致 DAG 节点卡在 running
• refactor: 拆分 primary_market.py 中 200+ 行的 ValuationAnalysis 到独立文件
• update code — 太模糊，无法追溯
• fix bug — 没说修了什么 bug
• wip — 不应该出现在 main 分支

13PR 规范

PR 模板 5 个 Section

合并规则

• 等 CI 3 个 job 全绿后，在 GitHub 页面手动 merge
• 不要用 gh pr merge 自动合并
• CI 未通过时不要强行 merge

14CI 流水线

本地预检命令（Push 前必须跑）

# 前端
cd frontend
npx tsc --noEmit          # TypeScript 编译检查
npm run lint              # ESLint
npm run build             # Vite 构建
npm run test:e2e:critical # E2E critical 测试

# 后端
cd ..
poetry run pytest -q      # Python 测试

15测试规范

后端测试（pytest）

poetry run pytest                            # 全量
poetry run pytest tests/unit/test_xxx.py -v  # 单文件
poetry run pytest -s                         # 带输出

异步测试直接用 async def test_xxx()，asyncio_mode = "auto" 已配置。

前端 E2E 测试（Playwright）

cd frontend
npm run test:e2e              # 全量
npm run test:e2e:critical     # 只跑 @critical
npx playwright test --ui      # 调试模式

data-testid 规范（强制）

命名规则： {区域}-{组件}-{元素}

选择器对比

// 正确：用 data-testid
page.getByTestId('primary-run-button')

// 禁止：用文本（文案改了就坏）
page.getByText('开始推演')

// 禁止：用 CSS class（样式改了就坏）
page.locator('.run-btn')

@critical 标记

不依赖后端的纯 UI 测试加 @critical，会在每个 PR 中运行：

test.describe('我的纯 UI 测试 @critical', () => {
  test('某个 UI 状态', async ({ page }) => {
    // ...
  })
})

16代码规范

数据全链路规范（新增分析模块时）

# 完整链路：后端 → 前端
Python Pydantic schema      # 1. 定义数据结构
  → DimensionRegistry      # 2. 注册到 Registry（如果是维度）
  → LLM prompt             # 3. 要求 LLM 输出对应 JSON
  → TS interface            # 4. 前端类型定义
  → PrimaryReportRaw        # 5. API 原始响应
  → snake → camelCase     # 6. 数据映射
  → DAG Node                # 7. DAG 执行图渲染
  → Deep Dive section       # 8. 审计层展示

17数据库变更流程

关键表

18高风险文件 & 合并注意事项

以下文件被多个模块依赖，修改时需格外小心：

合并原则

• 修改前先 git pull origin main 确保最新
• 分支落后且有冲突时，优先从最新 main 重建分支
• 详细冲突处理流程见 docs/BRANCH_CONFLICT_PLAYBOOK.md
• 不要在这些文件上做大范围重构而不提前沟通

19常见开发场景

20快速启动

5 步环境搭建

# 1. 克隆
git clone git@github.com:justicengg/pyta-research.git
cd pyta-research

# 2. 后端依赖
poetry install

# 3. 前端依赖
cd frontend && npm install && cd ..

# 4. 环境变量
cp .env.example .env
# 编辑 .env 或启动后在前端 UI 配置 LLM

# 5. 启动
./scripts/dev-up.sh

常用命令速查

服务地址

LLM 配置

两种方式（UI 优先级更高）：

一级市场核心 API