Craft-Agent

Craft-Agent 是一个开源的智能体系统，结合了「深度研究助手」与「网站自动生成」两大核心能力。它基于大语言模型、多智能体工作流编排和现代化 Web 技术栈构建，适用于研究人员、开发者或任何需要将想法快速转化为结构化内容与前端页面的用户。

项目源码托管于 GitHub，采用 MIT 开源协议，支持本地部署与容器化运行。下面我们将从功能特性、技术架构、部署方式、使用流程到开发扩展，系统性地介绍 Craft-Agent。

核心功能

多步深度研究工作流

Craft-Agent 能够自动规划研究路径：

• 拆解用户输入的问题为多个子任务
• 依次执行网页搜索、内容抓取、文本阅读与信息提炼
• 最终输出结构化的研究报告（如大纲、摘要、引用来源等）

整个过程支持 Human-in-the-loop 模式：用户可在任意节点介入，调整研究重点、增删信息源，或修正中间结论。

网站生成（Web Dev）

在 Web Dev 页面，你只需用自然语言描述网站需求，例如：

“一个展示 AI 项目案例的单页网站，包含标题、简介、三个项目卡片，使用深色主题和圆角按钮。”

系统会：

• 自动生成完整的项目结构（HTML/CSS/React 组件）
• 提供可视化代码编辑区域
• 内置本地预览功能，实时查看渲染效果

生成的代码基于现代前端技术栈，可直接用于部署或二次开发。

工具与集成能力

• 网页爬虫：基于 Jina Reader 与 Readability，高效提取正文内容
• Python 执行沙箱：支持在安全环境中运行代码片段（如数据处理、格式转换）
• LangChain 工具扩展：可接入自定义 API、数据库或内部服务

现代 Web 用户体验

前端采用：

• Next.js 15 + React 19 + TypeScript
• TailwindCSS + shadcn/ui 组件库
• 支持流畅动画与响应式布局
• 中英文双语切换（语言文件位于 web/messages/ 目录）

技术架构

后端（Python / FastAPI）

• 使用 FastAPI 构建 RESTful API，所有接口以 /api 为前缀
• 核心功能包括：
  • 加载模型与工具配置（RAG、LLM 等）
  • 支持流式响应的深度研究对话
  • 流式网站代码生成
  • 静态预览服务（挂载于 /api/preview）

智能体工作流由 LangGraph 编排，状态管理与节点逻辑集中在 src/graph/ 目录。

前端（Next.js）

• 页面路由：
  • /chat：研究工作室
  • /web-dev：网站生成器
  • /landing：项目介绍页
• 状态管理、组件复用、多语言支持均按模块化设计

部署方式

方式一：Docker Compose（推荐）

适合快速体验或生产部署：

git clone https://github.com/ipvoov/Craft-Agent
cd Craft-Agent

cp .env.example .env
cp config.yaml.example config.yaml
# 编辑 .env 和 config.yaml，填入你的 LLM API 密钥

docker-compose up -d

访问地址：

• 前端：http://localhost:3001
• API：http://localhost:8001

镜像：

• 前端：pveev/craft-agent-frontend:latest（约 300MB）
• 后端：pveev/craft-agent-backend:latest（约 500MB）

如需修改端口，请编辑 docker-compose.yml 中的 ports 字段。

方式二：本地开发（使用 uv）

适合开发者调试或二次开发：

git clone https://github.com/ipvoov/Craft-Agent
cd Craft-Agent

uv sync  # 自动创建虚拟环境并安装依赖
cp .env.example .env
cp config.yaml.example config.yaml
# 配置 API 密钥

cd web && pnpm install
./start.sh

服务启动后，同样通过 http://localhost:3001 访问。

典型使用流程

1. 深度研究（Research Studio）

• 访问 http://localhost:3001/chat
• 选择语言（中文/英文）
• 输入研究问题，例如：“分析 2024 年 AI 创业公司的融资趋势”
• 可选开启“深度思考模式”
• 系统自动执行多步研究，最终输出结构化报告

2. 网站生成（Web Dev）

• 访问 http://localhost:3001/web-dev
• 描述网站需求（结构、风格、内容）
• 提交后，系统生成完整前端项目
• 在右侧查看代码，并点击“预览”实时查看效果

开发与扩展

工作流定制

• 修改 src/graph/State.py 调整状态定义
• 在 src/graph/nodes/ 中新增或修改节点逻辑
• 支持条件分支、循环、人工审核等复杂流程

工具扩展

• 在 src/tools/ 目录添加新的 LangChain 工具
• 通过配置文件接入第三方服务（如企业内部数据库、搜索 API）

MCP 服务器集成

前端支持通过 JSON 配置注册 MCP（Model Control Protocol）服务器，相关文案位于 web/messages/en.json 和 zh.json 的 settings.mcp 字段。

⚠️ 安全提示：切勿将 API 密钥、密码等敏感信息提交至代码仓库。

常见问题排查

❌ 前端无法连接后端（404 / 超时）

• 检查 docker-compose.yml 中 NEXT_PUBLIC_API_URL 是否为 http://localhost:8001
• 运行 docker-compose ps 确认后端容器正在运行
• 查看日志：docker-compose logs backend
• 检查 Docker 网络：docker network ls

❌ 镜像拉取失败

• 确认网络畅通
• 镜像名称是否正确：pveev/craft-agent-backend:latest
• 尝试 docker login 登录 Docker Hub

❌ 容器内存溢出（OOM）

• 在 Docker Desktop 或 docker-compose.yml 中增加内存限制
• 检查日志中的异常堆栈
• 考虑降低 LLM 上下文长度或使用更轻量模型