PrismX 是面向量化投研、金融数据分析和可视化看板生成的 AI 工作台。用户用自然语言提出研究问题，平台会调度 Agent Runtime、读取真实数据、生成可运行工作空间，并通过自动验证、视觉检查、产物契约和评测链路把结果收敛到“好看、可用、可追溯”。
生成内容仅用于研究、复盘和辅助决策，不构成投资建议、收益承诺或即时交易指令。
如果你是第一次打开这个项目，不必急着把所有模块都看完。先把本地环境跑起来，再按下面的学习路径一层一层读。PrismX 的能力比较多，但核心脉络其实很清楚：真实数据进入本地库，Agent 基于 skills 生成工作空间，平台再用验证和评测把结果收紧。
- AI 工作台：任务入口、项目聊天、工作空间预览、任务记录和自动修复链路。
- 量化数据底座：PostgreSQL + TimescaleDB + Redis，承载应用状态、时序行情、估值因子、缓存和补数任务状态。
- 市场数据服务：Python/FastAPI 后端，提供行情、K 线、财务、公告、指标、补数、基础组件和策略平台接口。
- 策略平台：股票池、ETF/指数池、策略目录、板块资金、基础组件、金融知识和后续回测入口。
- 投研日报：围绕自选池生成证据型日报，沉淀 Markdown/JSON 报告、运行历史和推送记录。
- Skills 能力层：管理
.claude/skills，沉淀量化规划、数据质量、可视化生成和自修复能力。 - 评测与运维：评测平台、数据平台、运维平台共同覆盖生成质量、数据契约、工作空间健康、运行 trace 和集中日志。
第一次启动按下面顺序来：依赖、数据库、可选观测组件、市场数据后端、主前端。主前端现在使用 Next.js 默认开发链路；npm run dev 会调用 scripts/dev/run-web.js，负责端口选择、环境文件同步、稳定 CSS 生成、数据库 schema 检查和 Next dev 缓存清理。
npm install
cp .env.example .env
cp .env.example .env.local把 .env 或 .env.local 中的模型 token 改成自己的值，真实密钥不要提交到 Git。当前默认运行时是 Claude Code / Mimo V2.5 Pro。
npm run db:up
npm run db:init如需集中日志和 Grafana 排查界面，可再启动本地可观测性组件：
npm run obs:upcd services/market-data
uv sync --extra baostock --extra akshare
uv run quantpilot-market-api回到项目根目录：
npm run dev默认访问 http://localhost:3000。如果 3000 被占用，启动器会在 3000-3099 内选择可用端口并同步 .env / .env.local 中的 PORT、WEB_PORT 和 NEXT_PUBLIC_APP_URL。生成项目预览端口池从 4100 开始，Loki 使用 3100，不要把主前端长期放到这些端口上。
不启动 Loki/Grafana 时，运维平台会自动降级到本地文件日志；不启动市场数据后端时，策略平台和数据平台只能展示有限兜底信息。
| 入口 | 地址 | 说明 |
|---|---|---|
| AI 工作台 | http://localhost:3000 |
创建任务、进入项目聊天和预览 |
| 策略平台 | http://localhost:3000/strategy-platform |
股票池、ETF/指数池、板块资金、策略目录、基础组件和金融知识 |
| 投研日报 | http://localhost:3000/research-reports |
管理观察池、生成日报、查看证据、运行历史和推送记录 |
| Skills 管理 | http://localhost:3000/skills |
编辑、发布、回滚和导入核心 skills |
| 数据平台 | http://localhost:3000/data-platform |
查看能力域、数据接口、契约和验证边界 |
| 运维平台 | http://localhost:3000/ops-platform |
查看 workspace 健康、产物、队列和 trace |
| 评测平台 | http://localhost:3000/eval-platform |
运行评测、管理评测集、查看队列和报告 |
| 场景 | 命令 |
|---|---|
| 主前端开发 | npm run dev |
| 指定主前端端口 | npm run dev -- --port 3000 |
| 前端质量门 | npm run lint && npm run type-check && npm run build |
| 数据库启动 | npm run db:up && npm run db:init |
| 数据库检查 | npm run db:doctor |
| Redis CLI | npm run redis:cli |
| 可观测性启动 | npm run obs:up |
| 可观测性日志 | npm run obs:logs |
| Skills 检查 | npm run check:skills |
| 验证修复链路检查 | npm run check:validation-repair |
| 首页视觉 smoke | npm run check:homepage |
| 量化后端 | cd services/market-data && uv run quantpilot-market-api |
| 后端质量门 | cd services/market-data && uv run ruff check . && uv run pytest |
以下内容默认不进入 Git：.env、.env.local、.next/、node_modules/、data/、tmp/、public/uploads/、public/generated/、services/market-data/.venv/、services/**/.ruff_cache/。
首次使用需要的 PostgreSQL / TimescaleDB SQL 放在 sqls/。生成工作空间源码和大产物放在 data/projects/，平台数据库只保存索引、状态和摘要。
npm run obs:up 会拉起 Loki、Grafana 和 Grafana Alloy。Alloy 会采集 Docker 容器日志，并读取 tmp/runtime/*.log、评测队列日志和 Next.js dev 日志写入 Loki。Loki 默认宿主机端口是 3100，生成项目预览端口池从 4100 开始；Grafana 默认入口是 http://localhost:3001，默认账号密码来自 .env；运维平台的“日志”页会优先展示 Loki 集中日志，同时保留本地文件日志兜底。
主前端不再接入 next-rspack 或自定义 bundler 切换逻辑。npm run dev 直接启动 next dev，Next.js 16 在开发态使用自己的默认链路；项目侧只保留启动前后的工程保护：
scripts/dev/setup-env.js：确保.env、.env.local、data/projects/存在，并写入主前端端口、应用 URL 和预览端口池。scripts/dev/run-web.js：生成稳定 Tailwind CSS，探测降级组件恢复情况，必要时同步 Prisma schema，清理过期 Next dev lock/cache，再启动npx next dev。scripts/build/run-build.js：生产构建入口；默认跳过耗时的 per-route output tracing，需要桌面或 standalone 产物时使用npm run build:standalone。
.env 中的 QUANTPILOT_DEGRADATION_MODE 控制组件缺失时的行为：auto 适合本地开发，可选组件缺失时自动降级；strict 适合 CI/生产，必需组件缺失会失败；offline 会跳过可选外部组件探测，优先使用文件日志、内置数据源注册表和本地兜底数据。可通过 QUANTPILOT_DATABASE_ENABLED、QUANTPILOT_MARKET_API_ENABLED、QUANTPILOT_OBSERVABILITY_ENABLED、QUANTPILOT_REDIS_CACHE_ENABLED 等开关精确控制。