快速开始 — LingFlow 文档

前置条件

在开始之前，请确认本地环境已安装以下依赖。Mock 模式下仅需 Go 即可运行，无需真实 AWS 凭证；若需对接真实 LLM 与 S3 技能存储，请准备完整的 AWS 凭证。

依赖	最低版本	说明
Go	1.26.1	Go 编程语言运行时
AWS CLI	2.x	AWS 命令行工具（配置凭证）
Bun	1.x	前端包管理工具（演示用）
AWS 账户	—	需要 S3 和 Bedrock 访问权限

步骤 1：克隆项目

将 LingFlow 仓库克隆到本地工作目录。如果你 fork 了仓库，请替换为你的仓库地址。

bash

git clone <your-repository-url>
cd LingFlow

步骤 2：配置环境变量

LingFlow 通过 .env 文件管理运行配置。从示例文件复制一份并填入你的 AWS 凭证和配置。

bash

cp .env.example .env

编辑 .env 文件，填入 AWS 凭证和配置。若你只是想快速体验，可以使用 Mock 模式跳过真实 AWS 凭证。

最小可运行配置（Mock 模式）

bash

LLM_MOCK_MODE=true
MODE=development

提示：使用 Mock 模式无需真实 AWS 凭证即可快速启动和测试。服务会返回模拟的 LLM 响应，便于本地开发与功能验证。

步骤 3：启动服务

通过 Go 直接运行或编译为二进制后运行，两种方式任选其一。服务启动后监听 ws://localhost:4030/chat/{会话ID}。

bash

# 直接运行
go run main.go

# 或编译后运行
go build -o lingflow main.go
./lingflow

服务启动后监听 ws://localhost:4030/chat/{会话ID}。控制台会输出加载的技能数量、事件溯源状态等关键信息。

步骤 4：验证服务

通过 HTTP 接口获取认证 Token，然后使用该 Token 建立 WebSocket 连接。

获取认证 Token

bash

curl -X POST http://localhost:4030/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test-user"}'

预期响应

json

{
  "token": "debug-token-test-user",
  "expires_at": 0,
  "user_id": "test-user",
  "ttl": "unlimited"
}

WebSocket 连接

拿到 Token 后，即可通过 WebSocket 客户端连接到 LingFlow 进行对话。将 {会话ID} 替换为任意唯一字符串以隔离不同会话。

text

ws://localhost:4030/chat/my-session?token=debug-token-test-user

步骤 5：启动前端演示（可选）

LingFlow 提供基于 Vue 3 + TypeScript 的前端演示应用，采用 MVVM 架构，可用于直观体验 WebSocket 流式响应与技能调用。

bash

cd demo
bun install
bun run dev

访问 http://localhost:3000 查看演示界面。演示应用默认连接本地的 LingFlow 服务，可在设置中修改后端地址。

项目结构概览

LingFlow 采用清晰的分层架构，核心代码位于 internal/ 目录下，按职责拆分为连接管理、事件溯源、数据模型、业务服务和工具函数。

text

LingFlow/
├── main.go                         # 应用入口
├── internal/
│   ├── connections/wss.go          # WebSocket 连接管理
│   ├── events/                     # 事件溯源（Event Sourcing）
│   ├── models/                     # 数据模型定义
│   ├── services/                   # 核心业务服务
│   └── utilities/                  # 工具函数
├── demo/                           # Vue 3 前端演示
├── k8s/                            # Kubernetes 部署配置
├── docs/                           # 文档和图片资源
├── .github/                        # GitHub 社区健康文件
├── .gitcode/                       # GitCode 模板
├── .gitee/                         # Gitee 模板
├── .env.example                    # 环境变量示例
└── README.md                       # 项目文档

各目录职责说明：

main.go — 应用入口，负责初始化配置、注册路由、启动 HTTP 服务。
internal/connections/ — WebSocket 连接管理、心跳检测、认证鉴权。
internal/events/ — 事件溯源实现，包含聚合根、事件总线、命令总线、事件存储。
internal/models/ — 数据模型与响应结构定义。
internal/services/ — 核心业务服务，包括聊天处理、技能执行、S3 加载等。
internal/utilities/ — 通用工具函数，如配置加载、日志、AWS 工具。
demo/ — Vue 3 + TypeScript 前端演示应用。
k8s/ — Kubernetes 部署所需的 Deployment、Service、Ingress 等清单。