# 技术栈（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`、根目录构建脚本与配置文件的静态审计）*