# LingFlow
### 基于 WebSocket 的 AI 技能驱动聊天服务框架
[](https://go.dev/)
[](https://aws.amazon.com/bedrock/)
[](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
[](https://vuejs.org/)
[](https://bun.sh/)
[](LICENSE)
[](CONTRIBUTING.md)
---
## 目录
- [项目概述](#项目概述)
- [核心特性](#核心特性)
- [系统架构](#系统架构)
- [快速开始](#快速开始)
- [环境配置详解](#环境配置详解)
- [AWS 基础设施准备](#aws-基础设施准备)
- [WebSocket 协议规范](#websocket-协议规范)
- [技能系统](#技能系统)
- [AI 技能创建（#create_skill）](#ai-技能创建create_skill)
- [认证与安全](#认证与安全)
- [事件溯源架构](#事件溯源架构)
- [运行模式](#运行模式)
- [API 参考](#api-参考)
- [测试指南](#测试指南)
- [部署指南](#部署指南)
- [监控与日志](#监控与日志)
- [性能与容量规划](#性能与容量规划)
- [常见问题解答](#常见问题解答)
- [项目结构](#项目结构)
- [演示应用（Vue.js）](#演示应用vuejs)
- [社区与贡献](#社区与贡献)
- [版本历史](#版本历史)
---
## 项目概述
**LingFlow** 是一个基于 **Go 语言**构建的 **WebSocket 实时 AI 聊天服务框架**，核心理念是通过 **S3 动态技能加载** 赋能 LLM（大语言模型），实现可热更新的领域知识注入。系统采用 **事件溯源（Event Sourcing）** 模式管理会话生命周期，支持流式响应（思考过程 + 最终回复），并提供完整的认证、安全防护和多云部署能力。
### 设计哲学
| 原则 | 说明 |
| ------------------- | -------------------------------------------------------------------------------- |
| **技能即 Markdown** | 技能以 `.md` 文件存储在 S3 中，无需重新编译即可热更新 |
| **流式透明** | 客户端实时接收 AI 的思考过程（`system_thinking`）和最终响应（`system_response`） |
| **事件驱动** | 所有状态变更以不可变事件记录，支持审计和回放 |
| **安全优先** | 内置提示注入检测、速率限制、TLS 强制、Origin 白名单等多层防护 |
| **多云就绪** | 支持本地服务器、EC2 和 AWS Lambda + API Gateway 三种部署模式 |
| **开发者友好** | 内置 Mock LLM 模式，无需 AWS 凭证即可快速开发测试 |
### 技术栈
| 层次 | 技术 | 版本 | 说明 |
| ---------- | -------------- | ------------ | ------------------ |
| **后端** | Go | 1.26.1 | 高性能服务端语言 |
| **前端** | Vue.js | 3.x | 响应式 UI 框架 |
| **运行时** | Bun | 1.x | 前端包管理和运行时 |
| **LLM** | AWS Bedrock | Converse API | 大语言模型服务 |
| **存储** | AWS S3 | - | 技能文件存储 |
| **通信** | WebSocket | RFC 6455 | 实时双向通信 |
| **架构** | Event Sourcing | - | 事件溯源模式 |
---
## 核心特性
### 1. WebSocket 流式通信
- 双向实时通信，支持 `system_thinking`（思考过程）和 `system_response`（最终响应）双阶段流式推送
- 应用层心跳机制（Ping/Pong），双向超时检测，自动清理僵尸连接
- 连接建立后服务端主动推送可用技能列表
### 2. S3 动态技能加载
- 技能以 Markdown 文件存储在 AWS S3 中，文件名即为技能标识符
- 服务启动时自动扫描 `skills/` 前缀下所有 `.md` 文件并加载
- 支持运行时通过 `#create_skill` 命令由 AI 自动生成并上传新技能
- 技能更新后无需重启服务，注册中心自动刷新
### 3. AWS Bedrock LLM 集成
- 使用 Bedrock **Converse API**（统一接口），兼容所有 Bedrock 模型
- 支持模型参数配置：Temperature、Top-P、Max Tokens、超时时间
- 内置 Mock LLM 模式，开发阶段无需真实 AWS 凭证即可测试
- 技能上下文自动注入到 System Prompt 中
### 4. 事件溯源（Event Sourcing）
- 会话连接/断开、消息接收/处理/广播、心跳事件全部持久化
- 聚合根（Aggregate Root）封装业务不变量
- 事件存储接口化设计，当前使用内存实现，可无缝替换为数据库
### 5. 安全防护体系
- **提示注入检测**：输入层 + 输出层双重正则模式检测
- **速率限制**：每用户每分钟最多 5 次技能创建请求
- **TLS 强制**：生产环境必须启用 `wss://`
- **认证机制**：HMAC-SHA256 Token 签名，支持查询参数和 Authorization 头
- **Origin 白名单**：防止跨域 WebSocket 劫持
- **IP 连接数限制**：防止单 IP 连接泛洪
- **帧大小限制**：64KB 上限防止内存耗尽
### 6. 完整前端演示
- 基于 Vue 3 + TypeScript + Bun 构建
- 支持技能选择、Markdown 渲染、流式响应
- 精美的 UI 设计，响应式布局
---
## 系统架构
### 整体架构图
> 也可通过 [architecture.puml](docs/images/architecture.puml) 文件查看源文件。
### 消息处理流程
> 也可通过 [message_flow.puml](docs/images/message_flow.puml) 文件查看源文件。
---
## 快速开始
### 前置条件
| 依赖 | 最低版本 | 说明 |
| -------------------------------------- | -------- | --------------------------- |
| [Go](https://go.dev/dl/) | 1.26.1 | Go 编程语言运行时 |
| [AWS CLI](https://aws.amazon.com/cli/) | 2.x | AWS 命令行工具（配置凭证） |
| [Bun](https://bun.sh/) | 1.x | 前端包管理工具（演示用） |
| AWS 账户 | — | 需要 S3 和 Bedrock 访问权限 |
### 步骤 1：克隆项目
```bash
git clone 
### 客户端 → 服务端消息
#### 用户聊天消息 (`user_chat`)
```json
{
"type": "user_chat",
"data": {
"id": 1,
"user_id": "user-123",
"message": "检测这个系统的安全漏洞",
"selected_skill": "/vulnerability_scanner"
},
"timestamp": "2026-07-09T10:30:00Z"
}
```
| 字段 | 类型 | 说明 |
| --------------------- | ------ | ------------------------------------------------------- |
| `data.id` | int64 | 消息唯一 ID |
| `data.user_id` | string | 用户 ID |
| `data.message` | string | 用户消息内容 |
| `data.selected_skill` | string | 用户手动选中的技能（可选，如 `/vulnerability_scanner`） |
#### 心跳消息 (`heartbeat_chat`)
```json
{
"type": "heartbeat_chat",
"data": {
"action": "ping",
"nonce": "abc123",
"timestamp": "2026-07-09T10:30:00Z"
},
"timestamp": "2026-07-09T10:30:00Z"
}
```
### 服务端 → 客户端消息
#### 技能列表推送 (`system_skills_list`)
连接建立后服务端自动推送：
```json
{
"type": "system_skills_list",
"data": {
"skills": [
{
"skill_identifier": "/vulnerability_scanner",
"skill_display_name": "漏洞扫描",
"skill_description": "检测系统漏洞和安全威胁",
"skill_category": "security",
"search_keywords": ["漏洞", "扫描", "安全", "威胁", "检测"]
}
],
"total": 1,
"source": "s3",
"updated_at": "2026-07-09T10:30:00Z"
},
"timestamp": "2026-07-09T10:30:00Z"
}
```
#### 系统思考 (`system_thinking`)
**技能匹配阶段：**
```json
{
"type": "system_thinking",
"data": {
"phase": "skill_selection",
"skill_matches": [
{
"skill_identifier": "/vulnerability_scanner",
"skill_display_name": "漏洞扫描",
"match_score": 0.95,
"skill_category": "security"
}
],
"selected_skill": {
"skill_identifier": "/vulnerability_scanner",
"skill_display_name": "漏洞扫描",
"match_score": 0.95,
"skill_category": "security"
},
"thought": "正在匹配用户查询与可用技能..."
},
"timestamp": "2026-07-09T10:30:01Z"
}
```
**LLM 生成阶段：**
```json
{
"type": "system_thinking",
"data": {
"phase": "llm_generation",
"thought": "正在调用 Bedrock 生成响应..."
},
"timestamp": "2026-07-09T10:30:02Z"
}
```
#### 系统响应 (`system_response`)
```json
{
"type": "system_response",
"data": {
"content": "这是你的漏洞扫描结果...",
"skill_used": {
"skill_identifier": "/vulnerability_scanner",
"skill_display_name": "漏洞扫描",
"match_score": 0.95,
"skill_category": "security"
},
"finish_reason": "end_turn",
"tokens_used": 150,
"latency_ms": 2500
},
"timestamp": "2026-07-09T10:30:03Z"
}
```
#### 心跳响应 (`heartbeat_chat`)
```json
{
"type": "heartbeat_chat",
"data": {
"action": "pong",
"nonce": "abc123",
"timestamp": "2026-07-09T10:30:00Z",
"latency": 50
},
"timestamp": "2026-07-09T10:30:00Z"
}
```
#### 系统通知 (`system_chat`)
错误或状态通知：
```json
{
"type": "system_chat",
"data": {
"event": "skill_creation_disabled",
"message": "#create_skill 功能未启用..."
},
"timestamp": "2026-07-09T10:30:00Z"
}
```
---
## 技能系统
### 技能文件格式
技能以 Markdown 文件存储在 S3 的 `skills/` 前缀下：
```
s3://your-bucket/
└── skills/
├── vulnerability_scanner.md → 技能标识: /vulnerability_scanner
├── threat_intel.md → 技能标识: /threat_intel
└── security_audit.md → 技能标识: /security_audit
```
**文件名规则：**
- 仅允许小写字母、数字和下划线：`^[a-z0-9_]{1,64}$`
- 文件名（不含 `.md` 扩展名）即为技能标识符
- 不允许嵌套目录结构
### 技能 Markdown 模板
```markdown
# 技能显示名称
description: 精确的一句话描述，说明该技能的核心能力和适用场景
category: 分类（general / analysis / security / coding / data / networking / devops）
keywords: 关键词 1, 关键词 2, 关键词 3, 关键词 4, 关键词 5
## 角色定义
定义 LLM 在使用该技能时应扮演的专家角色，包括专业背景、能力范围和行为准则。
## 核心能力
1. 能力一 — 附带简要说明
2. 能力二 — 附带简要说明
3. 能力三 — 附带简要说明
## 使用说明
详细说明技能如何被调用、输入格式要求、预期行为和输出格式。
## 执行步骤
1. 接收用户输入
2. 分析查询意图
3. 调用领域知识
4. 生成结构化响应
## 输出格式规范
明确定义响应的结构、格式要求、必须包含的字段。
## 约束与规则
1. 规则一
2. 规则二
3. 不提供具体攻击方法
## 触发示例
- 基础用例: "检测系统安全漏洞"
- 进阶用例: "评估 Web 应用安全风险"
- 边界情况: "没有漏洞时如何处理"
## 错误处理
当输入不完整或超出技能范围时，应如何优雅地处理和回复。
```
### 技能检索机制
LingFlow 使用基于关键词的混合检索策略：
> 也可通过 [skill_retrieval.puml](docs/images/skill_retrieval.puml) 文件查看源文件。
---
## AI 技能创建（#create_skill）
### 工作原理
用户在聊天中发送 `#create_skill` 命令，系统通过 AI 自动生成技能 Markdown 内容并上传到 S3：
```
用户: #create_skill threat_intel 分析安全威胁情报和攻击趋势
│ │
▼ ▼
技能名称 技能描述
```
### 创建流水线
```
┌──────────────────────────────────────────────────────────────────────┐
│ #create_skill 流水线 (14 步) │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ 1. 命令解析 → 提取技能名称和描述 │
│ ↓ │
│ 2. 名称验证 → 仅允许小写字母、数字、下划线 (1-64字符) │
│ ↓ │
│ 3. 速率限制检查 → 每用户每分钟最多 5 次 │
│ ↓ │
│ 4. 提示注入检测 → 输入层正则匹配 + 输出层内容审查 │
│ ↓ │
│ 5. 技能存在性检查 → S3 HeadObject 判断是否已存在 │
│ ↓ │
│ 6. 事务锁获取 → 创建空文件占位，防止并发竞态 │
│ ↓ │
│ 7. AI 内容生成 → 调用 Bedrock Converse API 生成 Markdown │
│ ↓ │
│ 8. 输出内容验证 → 确保生成内容符合技能模板格式 │
│ ↓ │
│ 9. S3 文件上传 → 两阶段提交：先上传内容再删除占位 │
│ ↓ │
│ 10. 技能注册表刷新 → 本地缓存重新加载 │
│ ↓ │
│ 11. 技能列表推送 → 向所有在线连接广播更新后的技能列表 │
│ ↓ │
│ 12. 事务清理 → 删除空文件占位 │
│ ↓ │
│ 13. 成功响应 → 向发起用户返回创建结果 │
│ ↓ │
│ 14. 错误处理 → 任意步骤失败则回滚并清理资源 │
│ │
└──────────────────────────────────────────────────────────────────────┘
```
### 使用示例
```
# 创建技能
#create_skill threat_intel 分析安全威胁情报和攻击趋势
# 创建成功响应
{
"type": "system_chat",
"data": {
"event": "skill_created",
"message": "技能 threat_intel 创建成功",
"skill_info": {
"skill_identifier": "/threat_intel",
"skill_display_name": "威胁情报分析",
"skill_description": "分析安全威胁情报和攻击趋势",
"skill_category": "security"
}
}
}
```
### 安全防护
| 防护措施 | 说明 |
| ------------ | ------------------------------------------- |
| 名称白名单 | 仅允许小写字母、数字、下划线 |
| 速率限制 | 每用户每分钟最多 5 次技能创建 |
| 提示注入检测 | 输入层 + 输出层双重正则检测 |
| 事务锁 | 空文件占位防止并发创建同一技能 |
| 内容验证 | 生成的 Markdown 必须符合技能模板格式 |
| 生产模式限制 | 仅在 IS_ALLOW_USER_CREATE_SKILL=true 时启用 |
---
