企业官网建设流程全解析

本文为 LangAlpha 开发者入门 指南，带你完成开源项目 LangAlpha（Claude Code for Financial Market，AI 智能体金融交易平台）的完整上手流程：Docker 一键拉起全栈、宿主机本地开发、读懂源码结构，最后跑通测试并提交你的第一个贡献。全程无需付费 API Key，零密钥也能体验核心功能。

什么是 LangAlpha：一张图建立整体心智模型

LangAlpha 是一个开源的 AI 智能体交易框架：AI 智能体自主研究市场、建立投资论点、在你的授权范围内操作券商账户。它的核心设计是「交易是一个闭环」——研究、论点、仓位、下单、监控，新证据不断回灌到论点中：

全栈架构如下：多 Worker 的 FastAPI 后端驱动 Agent 运行，Agent 在 Daytona/Docker 沙箱中工作，PostgreSQL + Redis 承担状态与传输：

仓库目录速览

第1步：环境准备与前置条件清单

来自 CONTRIBUTING.md 的官方要求：

• Docker + Docker Compose（Docker 方式唯一硬性依赖）
• 宿主机开发（可选）：Python 3.13+ + uv、Node.js 22+ + pnpm

⚠️ Python 必须 3.13 而非 3.12：Redis 连接池在asyncio.Condition上阻塞，低版本存在通知丢失缺陷（见 pyproject.toml 中的注释说明）。

配置文件分为两类，务必分清：

• 凭据 / URL 类 → .env.example（复制为.env）
• 行为设置类 → agent_config.yaml 与 config.yaml

第2步：Docker 一键跑起全栈（最快上手路径）

这是官方推荐的开发者入门路径，整栈（后端、前端、PostgreSQL、Redis）全部容器化：

git clone https://gitcode.com/gh_mirrors/la/LangAlpha cd LangAlpha cp .env.example .env make config # 交互式向导：LLM、数据源、沙箱、网页搜索 make up # 构建并启动全栈

• 后端 API→http://localhost:8000（热重载，./src直接挂载进容器）
• 前端→http://localhost:5173（热重载）
• 健康检查：curl http://localhost:8000/health返回{"status": "healthy"}即成功
• 停止：make down（make clean会额外回收沙箱容器的磁盘）

零密钥也能用？是的

make config（由 scripts/configure.sh 驱动）会按你拥有的服务逐项配置。即使不填任何 Key：

• 沙箱：自动回落到本地 Docker 容器
• 数据：Yahoo Finance MCP 提供免费行情、基本面与筛选
• LLM：填一个 API Key（.env.example 支持 Anthropic / OpenAI / Gemini 等），或直接在 UI 里用 ChatGPT / Claude 订阅 OAuth 登录

第3步：宿主机本地开发（不用容器跑前后端）

想脱离容器调试时，按 CONTRIBUTING.md 的 Quick Start：

make install # uv 装后端依赖 + pnpm 装前端依赖 make setup-db # Docker 里只起 PostgreSQL + Redis 并建表 make dev # 后端 :8000 热重载 make dev-web # 前端 :5173（另开一个终端）

宿主机跑网页抓取还需安装浏览器依赖：

source .venv/bin/activate && scrapling install

第4步：读懂代码的 3 个「单一事实来源」文件

LangAlpha 为 AI 编码助手维护了三份 AGENTS.md，它们同样是新人理解架构的最快路径：

几个新人必须知道的约定：

• 无 ORM：全部原始 SQL，psycopg3 异步连接池
• 异步优先：handler 与 service 一律async def
• 工具 docstring 即提示词：模型调用时直接读它，改 docstring 等于改产品行为，且有快照锁测试守护（tests/unit/mcp_servers/ 的 docstring lock 文件），顺嘴改写会导致默认单测失败
• 多 Worker 服务器：状态只在 Postgres / Redis，进程内存不算事实来源

第5步：跑通测试——分层测试命令速查

测试入口统一收敛在 Makefile，官方 CI 等价命令：

make test # 后端单元测试（默认跑 tests/unit/，排除集成类） make test-web # 前端 Vitest 单元测试 make lint # Ruff（后端）+ ESLint（前端） make test-all # 后端 + 前端 + market-protocol + 内存沙箱集成

理解 pytest 的测试分层

pyproject.toml 的[tool.pytest.ini_options]默认addopts = "-m 'not integration and not slow and not regression'"，即make test只跑单元层。需要更高层验证时显式选择：

前端另有pnpm typecheck（tsc -b，类型检查是硬门禁）与pnpm test:e2e（Playwright）。

第6步：提交贡献——官方 4 步流程

1. 功能先开 Issue：新特性请先提 Issue 提案，让维护者早期介入；Bug 修复可直接提 PR
2. 新依赖先打招呼：添加第三方依赖或外部服务前，先与维护者确认
3. 证明你的改动能工作：端到端验证真实行为，并为改动区域补上防回归测试（先跑make test、make test-web、make lint全绿）
4. 对 main 提 PR：清晰描述改了什么、如何验证

代码风格红线

• 后端：Ruff lint（仅全局忽略E741），uv run ruff check src/
• 前端：ESLint flat config + shadcn/ui + Tailwind
• 代码与文档字符串一律英文（Issue 可用中文交流）

常见问题排查

💡 跑make help可列出全部目标（含migrate、data-probe、test-sandbox等），Makefile 本身就是最好的命令手册。

写在最后

按「Docker 拉栈 → 宿主机调试 → 读懂 AGENTS.md → 分层跑测试 → 按流程提 PR」这条路径走一遍，你就完成了 LangAlpha 开发者入门的全部动作。从你跑通第一条make test开始，这个仓库的每个提交都等你参与。🚀