131 lines
6.1 KiB
Markdown
131 lines
6.1 KiB
Markdown
# 技术栈（Tech Focus）
|
||
|
||
**分析日期：** 2026-04-07
|
||
|
||
## 语言
|
||
|
||
**主语言：**
|
||
- Python 3.12+：后端网关、Agent Runtime、MCP/工具系统（`backend/pyproject.toml`、`backend/.python-version`、`backend/langgraph.json`、`backend/packages/harness/pyproject.toml`）
|
||
- TypeScript（ES2022）：前端 App Router、API 代理、状态管理与 UI 组件（`frontend/package.json`、`frontend/tsconfig.json`）
|
||
|
||
**次要语言：**
|
||
- JavaScript（ESM）：Next.js/工具链配置（`frontend/next.config.js`、`frontend/eslint.config.js`、`frontend/prettier.config.js`）
|
||
- YAML：运行时模型与工具编排配置（`config.example.yaml`、`config.yaml`）
|
||
|
||
**结论：**
|
||
- 代码库是 Python + TypeScript 双栈，后端偏 AI runtime 编排，前端偏 Next.js 应用层；版本锚点明确（Python 3.12、Node 22）。
|
||
|
||
## 运行时
|
||
|
||
**后端运行时：**
|
||
- Python 3.12（`backend/.python-version`、`backend/langgraph.json`）
|
||
- FastAPI + Uvicorn（`backend/pyproject.toml`、`backend/Makefile`）
|
||
- LangGraph Server（`backend/Makefile` 的 `uv run langgraph dev`）
|
||
|
||
**前端运行时：**
|
||
- Node.js 22+（`frontend/README.md`；CI 也固定 Node 22，见 `.github/workflows/lint-check.yml`）
|
||
- Next.js 16 + React 19（`frontend/package.json`）
|
||
|
||
**结论：**
|
||
- 运行时依赖在文档与 CI 双重约束，团队应以 Python 3.12 + Node 22 作为本地/CI 基线。
|
||
|
||
## 依赖与包管理
|
||
|
||
**后端：**
|
||
- 包管理器：`uv`（`Makefile`、`backend/Makefile`）
|
||
- 工作区：`backend` 主工程 + `backend/packages/harness`（`backend/pyproject.toml` 的 `[tool.uv.workspace]`）
|
||
- 锁文件：`backend/uv.lock`（存在）
|
||
|
||
**前端：**
|
||
- 包管理器：`pnpm@10.26.2`（`frontend/package.json`）
|
||
- 锁文件：`frontend/pnpm-lock.yaml`（存在）
|
||
|
||
**结论：**
|
||
- 后端与前端均已锁版本；规划阶段应坚持 `uv sync` + `pnpm install --frozen-lockfile`，避免跨环境漂移。
|
||
|
||
## 核心框架
|
||
|
||
**后端核心：**
|
||
- `langgraph` / `langgraph-api`：Agent 图运行与 API 能力（`backend/packages/harness/pyproject.toml`）
|
||
- `langchain` 生态：模型适配、工具接口、回调（`backend/packages/harness/pyproject.toml`、`backend/packages/harness/deerflow/models/factory.py`）
|
||
- `fastapi` + `sse-starlette`：网关 REST 与流式接口（`backend/pyproject.toml`、`backend/app/gateway/routers/runs.py`）
|
||
|
||
**前端核心：**
|
||
- `next` 16（App Router）+ `react` 19（`frontend/package.json`）
|
||
- `@tanstack/react-query`：前端数据获取与缓存（`frontend/src/core/*/hooks.ts`）
|
||
- `@langchain/langgraph-sdk`：前端直连 LangGraph API（`frontend/src/core/api/api-client.ts`）
|
||
|
||
**结论：**
|
||
- 架构重心是 LangGraph runtime + FastAPI gateway + Next.js UI 三段式，新增能力应优先挂靠这三层边界。
|
||
|
||
## 构建与开发工具
|
||
|
||
**后端：**
|
||
- 启动：`uv run langgraph dev`、`uv run uvicorn ...`（`backend/Makefile`）
|
||
- 测试：`pytest`（`backend/pyproject.toml`、`backend/Makefile`）
|
||
- 质量：`ruff`（`backend/ruff.toml`）
|
||
|
||
**前端：**
|
||
- 开发：`next dev --turbo`（`frontend/package.json`）
|
||
- 构建：`next build`（`frontend/package.json`）
|
||
- 质量：`eslint` + `typescript-eslint` + `prettier`（`frontend/eslint.config.js`、`frontend/prettier.config.js`）
|
||
- E2E：`playwright`（`frontend/playwright.config.ts`）
|
||
|
||
**CI：**
|
||
- GitHub Actions：后端单测、前后端 lint/type/build（`.github/workflows/backend-unit-tests.yml`、`.github/workflows/lint-check.yml`）
|
||
|
||
**结论：**
|
||
- 工具链完整，且 CI 已覆盖“格式/Lint/类型/构建/后端单测”；后续 phase 应直接复用现有流水线，不建议新建并行脚本体系。
|
||
|
||
## 关键依赖（对规划最有影响）
|
||
|
||
**AI 与模型：**
|
||
- `langchain-openai`、`langchain-anthropic`、`langchain-google-genai`、`langchain-deepseek`（`backend/packages/harness/pyproject.toml`）
|
||
- `langgraph-sdk`（前后端均使用，`backend/pyproject.toml`、`frontend/package.json`）
|
||
|
||
**集成与工具：**
|
||
- `langchain-mcp-adapters`（MCP 多服务接入，`backend/packages/harness/pyproject.toml`）
|
||
- `slack-sdk`、`python-telegram-bot`、`lark-oapi`、`wecom-aibot-python-sdk`（`backend/pyproject.toml`、`backend/app/channels/*.py`）
|
||
- `tavily-python`、`firecrawl-py`、`ddgs`、`duckdb`（`backend/packages/harness/pyproject.toml`）
|
||
|
||
**前端平台能力：**
|
||
- `better-auth`（鉴权，`frontend/src/server/better-auth/config.ts`）
|
||
- `@t3-oss/env-nextjs` + `zod`（环境变量校验，`frontend/src/env.js`）
|
||
|
||
**结论：**
|
||
- 依赖风险主要在第三方模型/搜索/IM SDK 的 API 兼容性；规划中应为这些“边缘适配层”预留回归验证。
|
||
|
||
## 配置体系
|
||
|
||
**应用配置：**
|
||
- 主配置：`config.yaml`（示例：`config.example.yaml`），支持 `$ENV_VAR` 解析（`backend/packages/harness/deerflow/config/app_config.py`）
|
||
- 扩展配置：`extensions_config.json`（MCP servers + skills 状态，`backend/packages/harness/deerflow/config/extensions_config.py`）
|
||
|
||
**前端配置：**
|
||
- 运行时环境校验：`frontend/src/env.js`
|
||
- 前端 API 基址解析：`frontend/src/core/config/index.ts`
|
||
|
||
**敏感配置文件存在性（仅记录存在，不读取值）：**
|
||
- 根目录 `.env`
|
||
- 前端 `frontend/.env`、`frontend/.env.example`
|
||
|
||
**结论：**
|
||
- 配置源分层清晰（主业务配置 + 扩展配置 + 前端 env）；新功能应优先扩展现有配置模型，不要散落新增私有配置文件。
|
||
|
||
## 平台与部署要求
|
||
|
||
**开发：**
|
||
- `make install` 安装前后端依赖（`Makefile`）
|
||
- `make dev` 一键启动（LangGraph + Gateway + Frontend + Nginx，见 `Makefile` 和 `backend/README.md`）
|
||
|
||
**生产/容器：**
|
||
- 前端 `next.config.js` 使用 `output: "standalone"`（`frontend/next.config.js`）
|
||
- 支持 Docker 部署脚本与编排目录（`docker/docker-compose.yaml`、`docker/docker-compose-dev.yaml`、`scripts/deploy.sh`、`scripts/docker.sh`）
|
||
|
||
**结论：**
|
||
- 默认目标是容器化/反向代理下的整套部署；后续规划应把“网关端口与反代路径一致性”作为上线前强校验项。
|
||
|
||
---
|
||
|
||
*栈分析完成于 2026-04-07（基于 `backend`、`frontend`、根目录构建脚本与配置文件的静态审计）*
|