QuantPilot 是建立在通用 Data Agent 与开源 PI Agent 执行内核之上的金融量化应用。用户用自然语言提出研究问题，Finance Domain Pack 会组合证券解析、真实数据、Skills、工具、Mission 和可视化规则，生成可运行工作空间，并通过自动验证、视觉检查、产物契约和评测链路把结果收敛到“好看、可用、可追溯”。同一套框架可以继续接入零售、运营、制造等业务 Domain Pack，而不把业务规则写回 Agent 内核。
生成内容仅用于研究、复盘和辅助决策，不构成投资建议、收益承诺或即时交易指令。
如果你是第一次打开这个项目，先选择模型与 Memory 运行方式，再把本地环境跑起来。核心链路是：真实数据进入本地库，Agent 基于 skills 生成工作空间，平台再用验证和评测把结果收紧。
- 通用 Data Agent：使用版本化 Task、Dataset、Connector、Domain Pack、Agent Profile、Delivery Pack 和 Execution Plan 合同组合业务能力；
DataAgentApplicationCatalog让 Profile Adapter 负责 workspace 初始化，项目和任务同时持久化 Profile/Domain/Delivery/capability 版本锁与 SHA-256。当前金融实现是finance.quant，通用 Next.js 交付实现是workspace.next-dashboard。完整边界与新业务接入流程见 Data Agent 平台与 Domain Pack 架构。 - AI 工作台：任务入口、项目聊天、工作空间预览、任务记录和自动修复链路。
- 量化数据底座：PostgreSQL + TimescaleDB + Redis，承载应用状态、时序行情、估值因子、缓存和补数任务状态。
- 市场数据服务：Python/FastAPI 后端，提供行情、K 线、财务、公告、指标、补数、基础组件和策略平台接口。
- 策略平台：股票池、ETF/指数池、策略目录、板块资金、基础组件、金融知识和后续回测入口。
- 投研情报中心：围绕观察池生成证据型日报，沉淀结构化报告、主题洞察、运行历史和推送回执。
- LLM-first Query Rewrite：
preview与正式执行都由项目选中的模型生成 schema v4 语义合同，时间范围、宽域范围和 answer-only 意图必须有原文字面证据；证券 Resolver 独立确认代码。模型不可用时停止规划和预取，不以关键词结果冒充成功。 - PI Agent 执行内核 + QuantPilot 治理层：
@earendil-works/pi-agent-core负责完整多轮 Agent loop，默认通过 ModelPort 使用本地 Qwen，日常 DeepSeek 经 ModelPort 的 Anthropic 上游 provider，也可为项目显式选择官方 OpenAI-compatible 直连并完全绕过 ModelPort；QuantPilot 保留上下文治理、信息增益 Observation Ledger、受信副作用工具的人工批准/编辑/拒绝、PostgreSQL generation job/事务 outbox、独立 Worker registry、数据库全局 Worker 槽位、按用户公平 claim、用户排队/运行双层结构配额、项目编排/AgentRun/Mission 分层 lease 与 fencing、共享文件系统资源锁、durable run/approval/operation ledger、预算、取消和显式结果提交。审批等待会把 AgentRun 原子切到waiting并写公开 checkpoint，决策通过后才允许 prepare/execute；Worker 丢失则关闭旧 attempt 并重新规划，不复用已批准的旧调用。Worker 启动时会持久注册进程身份与心跳，并拒绝加入全局容量配置不一致的存活集群；运行治理中心直接展示进程、槽位和队列事实。HTTP 入口只负责接收与调度，金融规划/取数由独立应用服务完成；生产 Worker 与本地 inline 模式都使用 schema v3 execution envelope，按 Profile handler 执行并核对项目、request、workspace、跨平台 scope 和组合哈希。Memory Recall 与受治理知识准备快照随任务固化，避免排队后重复检索导致 evidence 与实际输入漂移。PiAgent*类型和结构化 JSON 合同由通用治理层定义，Domain Pack 只注入领域能力；内核不内置证券、量化工具、dashboard 路径或金融 Mission。版本与边界见 PI Agent 采用与治理边界。 - Skills 能力层：仓库
.pi/**是唯一权威源，通过 registry/lock、版本与 SHA-256 完整性校验；项目初始化把参考镜像配置到 workspace.pi/skills，Agent 执行按 source-first/package-fallback 规则只读编译有界上下文，不从 workspace 镜像发现能力，也不解析旧 Skill ID。 - 业务与治理：业务知识中心、评测平台和运行治理中心共同覆盖能力知识、交付契约、生成质量、工作空间健康、运行 trace 和集中日志。
- 受治理上下文接入：通过独立 HTTP 契约组合 Memory Usage Receipt 与 AKEP ContextPack，Agent 前落无正文联合清单，Mission 验收后记录 AKEP Usage，用户明确评价后再分别回传 Memory Outcome 与 AKEP Feedback；不共享数据库或源码。
- 生成代码隔离：build/preview 默认进入 Linux user、mount、network、PID namespace，工作区只读且不注入平台密钥；preview 只经工作区 Unix Socket 对浏览器开放，并获得一条固定目标的无凭据 market-data 桥接，不能访问其他宿主服务或外网。
第一次启动按下面顺序来。npm install 的 postinstall 会创建缺失的 .env 和 .env.local；也可以显式执行 ensure:env。不要把整份 .env.example 复制到 .env.local，后者只应保存本机凭据与少量覆盖。
npm install
npm run ensure:env推荐模式只需在 .env.local 添加 ModelPort 签发的受限客户端凭据：
MODELPORT_API_KEY="replace-with-scoped-modelport-client-key"本地 Qwen 是默认模型，日常 DeepSeek 也经 ModelPort 使用。DeepSeek 上游 Anthropic Key 只配置在 ModelPort；如果明确要绕过 ModelPort，则在 QuantPilot 注入 DEEPSEEK_API_KEY，并显式选择 deepseek-v4-flash。Memory 是独立可选组件，可用 QUANTPILOT_MEMORY_ENABLED=0 完全关闭。
跨平台作用域采用 Consumer + Workspace 两层隔离：ModelPort API Key 固定绑定 QuantPilot 项目账本，Memory 使用 QuantPilot 独占 tenant，AKEP 每轮只查询 shared Space 与当前 Project.id 派生的 project Space；统一作用域摘要写入数据库和 workspace evidence。详见 联合上下文与项目隔离。
| 运行方式 | .env.local 最小配置 |
额外动作 |
|---|---|---|
| 推荐：Qwen + ModelPort DeepSeek | MODELPORT_API_KEY=... |
ModelPort 配置 Qwen 与 DeepSeek provider |
| 只使用 Qwen | MODELPORT_API_KEY=... |
客户端 Key 只授权 local_qwen 即可 |
| DeepSeek 官方直连 | DEEPSEEK_API_KEY=... |
项目/全局设置选择 deepseek-v4-flash |
| 不启用 Memory | QUANTPILOT_MEMORY_ENABLED=0 |
无需启动或配置 Memory 服务 |
完整的文件优先级、可复制组合、生产 secret 边界和验证命令见 配置、模型接入与可选组件指南。
npm run db:up
npm run db:init如需集中日志和 Grafana 排查界面，可再启动本地可观测性组件：
npm run obs:up在项目根目录启动完整开发栈。npm run dev 调用 scripts/dev/run-full.js，先启动或复用 market-data，再由 run-web.js 完成端口选择、环境文件同步、稳定 CSS 生成、数据库 schema 检查、Next dev 缓存清理和 Web 启动：
npm run dev默认访问 http://localhost:3000。如果 3000 被占用，启动器会在 3000-3099 内选择可用端口并同步 .env / .env.local 中的 PORT、WEB_PORT 和 NEXT_PUBLIC_APP_URL。生成项目预览端口池从 4100 开始；本地 Loki 默认映射到宿主机 33100，不要把主前端长期放到这些端口上。
不启动 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/business-knowledge |
查看业务能力、典型场景、交付规范和执行依赖 |
| 运行治理中心 | http://localhost:3000/ops-platform |
统一查看 Worker/队列、服务依赖、工作空间交付、生成链路和运行日志 |
| 评测平台 | http://localhost:3000/eval-platform |
运行评测、管理评测集、查看队列和报告 |
| 场景 | 命令 |
|---|---|
| 完整开发环境（前端 + market-data） | npm run dev |
| 仅启动主前端 | npm run dev:web |
| 仅启动量化后端 | npm run dev:market |
| 指定主前端端口 | npm run dev -- --port 3000 |
| 单元与后端测试 | npm test |
| 确定性发布质量门 | npm run release:check |
| 含依赖审计与运行态诊断 | npm run release:check:full |
| 数据库启动 | npm run db:up && npm run db:init |
| 数据库检查 | npm run db:doctor |
| 本地单次消费 generation job | PI_AGENT_DISPATCH_MODE=worker npm run worker:generation:once |
| 刷新交易日历、日线并校验覆盖 | npm run market:maintain |
| 只检查行情维护参数 | npm run market:maintain:dry-run |
| 初始化/维护登录管理员 | npm run auth:bootstrap |
| 验证完整用户生命周期 | npm run auth:verify |
| 清理过期认证数据与配额预留 | npm run auth:cleanup |
| 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 |
| 全平台响应式视觉 smoke | 启动 Web 后运行 npm run check:platform-visuals |
| 量化后端 | cd services/market-data && uv run quantpilot-market-api |
| 后端质量门 | cd services/market-data && uv run ruff check . && uv run pytest |
| 文档本地链接检查 | npm run check:docs |
| 四类生成模板真实构建 | npm run check:scaffold-templates |
| 模型配置边界检查 | npm run check:ai-provider-boundary |
| 模型目录与凭据连通性检查 | npm run check:models |
| Qwen、ModelPort DeepSeek、Memory 基础契约联调 | npm run check:integrations |
| ModelPort、Memory、AKEP 30 题真实体验验收 | npm run check:triad-experience |
| 四组自然语言变体、共 120 题真实压力验收 | npm run check:triad-experience:large |
| 50 题 Qwen + Memory + AKEP 持久闭环验收 | 先在 AKEP 运行 pnpm seed:quantpilot-acceptance-50 -- --output=<manifest>，再运行 npm run check:memory-knowledge-50 -- --manifest=<manifest>；数据默认保留 |
| 创建真实任务、生成 Workspace 并验收预览 | npm run check:task-e2e -- --campaign=<批次>（完整通过后自动清理测试项目） |
配置、架构和运行文档统一从 docs/README.md 进入；数据库与 E2E 清理先读 数据生命周期与安全清理，不要凭表名或创建时间直接删除数据。
项目知识集中放在 docs/。根 README 只放少量入口，完整索引看 文档总览。
| 你要做什么 | 入口 |
|---|---|
| 不知道从哪篇开始 | 文档总览与角色路径 |
想选择模型、关闭 Memory 或理解 .env |
配置、模型接入与可选组件指南 |
| 想系统学习项目 | 教学路径 |
| 想参与开发或判断代码放哪 | 项目结构与分层边界 / 模块边界 |
| 想理解或扩展 Agent 框架 | PI Agent 采用与治理边界 / PI Agent 架构 |
| 想查接口、字段或数据源口径 | API 总览 / 数据字典 / 行情数据源知识库 |
| 想做每日投研报告和推送 | 投研情报中心与日报自动化指南 |
| 想排障或做发布前检查 | 运行手册 / 故障排查 |
| 想启用登录或配置权限/用量配额 | 用户、权限、配额与会话管理 |
| 想接入、使用或排查用户记忆 | 用户记忆服务接入、使用与效果验证 |
| 想理解 Memory、Knowledge 与 QuantPilot 的联合归因 | 联合上下文与结果归因 |
| 想看后续优先级 | 持续完善路线图 |
如果是第一次接触项目，建议按这个顺序读：
| 阶段 | 文档 | 目标 |
|---|---|---|
| 先找阅读路径 | 文档总览与角色路径 | 按启动、开发、排障、策略、评测、skills 等目标选择阅读顺序 |
| 选择运行拓扑 | 配置、模型接入与可选组件指南 | 选择 ModelPort、官方直连和 Memory 开关 |
| 先建立全局图 | 项目学习地图 | 知道产品、数据、生成和质量四条主线 |
| 再跑通本地环境 | 本地启动与健康检查 | 拉起数据库、后端、前端和可选观测组件 |
| 理解内部组件 | 内部组件学习指南 | 把页面、服务、数据、Skills、验证和运维串起来 |
| 学会生成链路 | AI 工作空间生成链路 | 理解 run plan、data、evidence、validation 和 repair plan |
| 学会数据与策略 | 市场数据与策略平台 | 理解股票池、K 线、补数、因子和基础组件 |
| 学会查接口和字段 | API 总览 / 数据字典 | 知道页面读哪个接口、字段来自哪里 |
| 学会 Skills | Skills 编写与迭代教程 | 知道如何修改、发布、打包和验证 skill |
| 看后续优先级 | 持续完善路线图 | 知道哪些事该先做，哪些事暂时不该做 |
文档维护也算项目能力的一部分。改代码时如果改变了页面入口、组件职责、数据字段、环境变量、SQL 或 skill 行为，请同步更新对应文档；具体写法见 文档写作风格指南。
以下内容默认不进入 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 默认映射到宿主机 33100；Grafana 容器端口 3000 默认映射到 http://localhost:33012，账号密码来自 .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 会跳过多项可选外部组件探测，优先使用本地兜底。只关闭一个组件应使用其 ENABLED=0，例如不启用 Memory 使用 QUANTPILOT_MEMORY_ENABLED=0，不要为了关闭单一组件切到 offline。完整开关见 配置指南。