fix: delete agent 500 error + dynamic personality + deployment guide

- Fix delete agent 500: clean up FK records (agent_llm_logs, permissions, schedules, executions, team_members) and unbind goals/tasks before delete - Remove hardcoded personality templates in Android, replace with dynamic system prompt generation from name + description - Set promptSectionsEnabled=false to bypass PromptComposer for personality - Add Tencent Cloud Linux deployment guide (Docker Compose) - Accumulated backend service updates, frontend UI fixes, Android app changes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-06-29 01:17:21 +08:00
parent 86b98865e3
commit beff3fac8d
1084 changed files with 117315 additions and 1281 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -87,75 +87,326 @@

 ## 四、核心业务模块

-### 1. 用户模块
- **注册/登录**：邮箱 + 密码，JWT Token 发放
- **Token 刷新**：Access Token (短期) + Refresh Token (长期)
+### 1. 用户与权限模块
+- **注册/登录**：用户名 + 密码，JWT Token 发放
+- **Token 刷新**：Access Token (30min) + Refresh Token (7d)
 - **个人中心**：信息查看与修改
+- **角色权限**：admin / workspace_admin / member，支持 14 个权限端点
+- **多租户**：Workspace 级数据隔离，飞书应用按 workspace 隔离

-### 2. 智能体模块
+### 2. 智能体模块 (Agent)
 - 智能体的创建、配置、发布、下架
- 支持配置 LLM 参数、提示词、工具调用
- 知识库关联
+- **Agent 类型**：specialist（专家）/ main（主路由）
+- 工作流配置 `workflow_config`（nodes + edges）
+- 执行预算 `budget_config`（max_steps / max_llm_invocations / max_tool_calls）
+- 输入/输出 Schema 约束（JSON Schema）
+- **Agent 市场**：发布/安装/评分(Fork)/收藏/升级
+- **Agent 编排**：5 种模式（route / sequential / debate / pipeline / graph）
+- **Agent 蜂群**：Swarm Leader 分解任务 → Teammate 并行执行 → 聚合结果

 ### 3. 知识库模块
- 文档上传与解析（PDF、TXT、Markdown）
- 向量化存储（对接嵌入模型）
- 语义检索
+- 文档上传与解析（PDF、TXT、Markdown、HTML、CSV、JSON）
+- 文档分块 → 向量嵌入（支持 OpenAI / DeepSeek Embedding）
+- 语义检索（余弦相似度 + 混合检索）
+- **RAG 增强生成**：检索 → 增强 Prompt → 生成
+- **知识图谱**：KnowledgeEntity（节点）+ KnowledgeRelation（关系边）
+- **知识进化**：Celery Beat 定时提取 → LLM 提炼 → 入库
+- **知识仪表盘**：增长曲线、复用排行、类别分布

 ### 4. 对话模块
- 用户与智能体的实时对话
- 上下文管理
- 流式输出（SSE）
+- 用户与智能体的实时对话（SSE 流式输出）
+- **事件类型**：plan / think / tool_call / tool_result / final / done
+- 上下文管理与会话恢复（session_id）
+- 对话分支（Branch）：分支创建 / 查看 / 恢复
+- **记忆系统**：短期记忆（向量 RAG）+ 长期记忆（PersistentUserMemory）+ 全局知识池
+
+### 5. 工作流模块
+- 可视化 DAG 工作流（开始 → LLM/工具/条件/循环 → 结束）
+- **节点类型**：start / llm / tool / condition / code / switch / parallel / subworkflow / orchestrator / evaluator
+- **节点配置**：提示词模板（支持 `{{variable}}` 变量）、工具列表、模型参数
+- **节点级功能**：自动重试（retry_config）、错误处理（error_handler）、人工审批（HITL）
+- 版本管理（WorkflowVersion）：保存 / 列表 / 回滚
+- 版本对比：节点变更可视化
+- 节点搜索/筛选、自动布局（Dagre 算法）
+- 工作流验证：死循环检测、孤立节点检测、类型兼容性检查
+- **Subworkflow**：嵌套子工作流，含深度防护
+
+### 6. 工具系统
+- **内置工具**：56 个开箱即用工具（文件 / 文本 / HTTP / 代码 / 搜索 / 计算 / 日期 / JSON / 知识图谱 等）
+- **工具分类**：file_ops / text_processing / web / code / data / knowledge / search / math
+- **工具参数过滤**：防止注入、类型校验
+- **工具动态注册**：HTTP 工具 / 代码工具 / 工作流工具，支持热更新
+- **工具市场**：发布 / 安装 / 版本管理
+
+### 7. 监控与告警
+- **系统监控**：概览 / 执行统计 / 节点类型用量 / 最近动态
+- **Agent 监控**：LLM 调用统计 / Agent 统计 / 工具用量 / 每日趋势
+- **告警系统**：规则 CRUD + 告警日志 + 通知（邮件/Webhook/站内）
+- **Prometheus 指标**：`/metrics` 端点，业务指标 + 系统指标
+- **Grafana 仪表板**：系统/业务双面板
+- **ELK 日志聚合**：Filebeat → Logstash → Elasticsearch → Kibana
+
+### 8. 商业化模块
+- **模板市场**：11 个行业模板（客服/研发/PR Review/面试调度/竞品监控/测试报告/入职引导/风险预警/学习助手/日报/日志分析）
+- **场景契约 DSL**：统一输入契约（目标/约束/产物/验收），模板复用
+- **定时任务**：Cron 表达式，支持手动触发
+- **Android App**：原生 Kotlin + Compose，对话/历史/语音/TTS/推送
+- **飞书 Bot**：6 个 Bot，WebSocket 长连接，交互卡片，对话上下文连续性
+- **PWA 移动端**：manifest + Service Worker + 离线缓存 + 浏览器推送
+
+### 9. 集成与通知
+- **第三方集成**：飞书 / 微信 / Slack（Webhook）
+- **推送通知**：PushSubscription 模型 + push_service + 浏览器 Push API
+- **FCM 推送**：Firebase Cloud Messaging for Android
+- **WebSocket 实时推送**：执行状态实时更新
+- **审批系统**：approval_manager + 危险工具自动审批流程

 ---

-## 五、数据流示例（对话请求）
+## 五、Agent 运行时架构
+
+### ReAct 循环

 ```
-1. 用户输入消息
-       │
-2. Axios POST /api/v1/conversations/{id}/messages
-       │
-3. Nginx 代理到后端 8037
-       │
-4. FastAPI 接收请求
-   ├── JWT 中间件验证 Token
-   ├── 路由分发到对应 Handler
-   ├── Service 层处理业务逻辑
-   │   ├── 查询对话历史 (MySQL)
-   │   ├── 检索相关知识 (知识库)
-   │   └── 调用 LLM API (异步)
-   │
-5. Celery 异步执行 LLM 调用
-   ├── 进度通过 Redis Pub/Sub 推送
-   └── SSE 推送给前端
-       │
-6. 前端流式渲染响应内容
+用户输入 → [Think → Act → Observe] × N → Final Answer
+
+每个迭代：
+1. Think: LLM 分析当前状态，决定下一步
+2. Act:  调用工具或执行操作
+3. Observe: 获取工具结果，更新上下文
+```
+
+### 核心执行流程
+
+```
+AgentRuntime.execute()
+├── 加载 Agent 配置（workflow_config, system_prompt, tools）
+├── 初始化上下文（memory, conversation_history, session_state）
+├── ReAct 循环（最多 max_iterations 轮）
+│   ├── _think(): LLM 推理，决定调用哪个工具
+│   ├── _act():  执行工具调用
+│   │   ├── 参数过滤（防止注入）
+│   │   ├── 审批检查（HITL — 危险工具需人工审批）
+│   │   └── 执行工具（内置 / HTTP / 代码 / 工作流）
+│   ├── _observe(): 记录结果，更新记忆
+│   └── _should_continue(): 判断是否继续（任务完成？达到上限？）
+├── 聚合结果 → Final Answer
+└── 记录执行日志（AgentLLMLog + AgentExecutionLog + ExecutionLog）
+```
+
+### 记忆系统三层架构
+
+```
+┌──────────────────────────────────────────┐
+│  第一层：短期记忆（对话上下文）             │
+│  • 当前会话的历史消息                       │
+│  • memory_max_history 条消息              │
+│  • 滑动窗口自动截断                        │
+├──────────────────────────────────────────┤
+│  第二层：向量记忆（语义检索）               │
+│  • AgentVectorMemory 表                   │
+│  • Embedding → 向量相似度检索              │
+│  • 跨会话语义相关性查找                    │
+│  • 配置：memory_vector_top_k 条           │
+├──────────────────────────────────────────┤
+│  第三层：长期记忆（持久化）                 │
+│  • PersistentUserMemory 表               │
+│  • 关键信息跨会话保存                      │
+│  • 用户画像、偏好、学习进度                 │
+│  • memory_persist + memory_learning       │
+└──────────────────────────────────────────┘
+```
+
+### 多 Agent 编排模式
+
+| 模式 | 描述 | API |
+|------|------|------|
+| **route** | 主 Agent 分析输入 → 路由到最合适的子 Agent | `/agent-chat/orchestrate` |
+| **sequential** | 多个 Agent 按顺序执行，前者输出为后者输入 | `/agent-chat/orchestrate` |
+| **debate** | 多个 Agent 同时回答，汇总比较 | `/agent-chat/orchestrate` |
+| **pipeline** | 流水线模式，每个 Agent 处理一个阶段 | `/agent-chat/orchestrate` |
+| **graph** | DAG 图模式，任意拓扑结构，并行分支 | `/agent-chat/orchestrate/graph` |
+| **swarm** | Leader 分解 → Teammate 并行 → 聚合 | `/swarm/run` |
+
+---
+
+## 六、实时通信架构
+
+### SSE（Server-Sent Events）
+
+```
+Client                          Server
+  │                                │
+  │  POST /agent-chat/{id}/stream  │
+  │  Accept: text/event-stream     │
+  │───────────────────────────────>│
+  │                                │
+  │  event: plan                   │
+  │  data: {"title":"...",         │
+  │         "steps":[...]}         │
+  │<───────────────────────────────│
+  │                                │
+  │  event: think                  │
+  │  data: {"content":"...",       │
+  │         "iteration":0}         │
+  │<───────────────────────────────│
+  │                                │
+  │  event: tool_call              │
+  │  data: {"tool_name":"...",     │
+  │         "tool_input":"..."}    │
+  │<───────────────────────────────│
+  │                                │
+  │  event: tool_result            │
+  │  data: {"tool_name":"...",     │
+  │         "tool_result":"..."}   │
+  │<───────────────────────────────│
+  │                                │
+  │  event: final                  │
+  │  data: {"content":"...",       │
+  │         "iterations_used":3}   │
+  │<───────────────────────────────│
+  │                                │
+  │  event: done                   │
+  │  data: {"session_id":"..."}    │
+  │<───────────────────────────────│
+```
+
+### WebSocket
+
+```
+Client                               Server
+  │                                     │
+  │  WS /ws/executions/{execution_id}   │
+  │────────────────────────────────────>│
+  │                                     │
+  │  {"type":"progress","pct":50}       │
+  │<────────────────────────────────────│
+  │                                     │
+  │  {"type":"node_start",              │
+  │   "node_id":"llm-1"}               │
+  │<────────────────────────────────────│
+  │                                     │
+  │  {"type":"node_complete",           │
+  │   "node_id":"llm-1",               │
+  │   "output":"..."}                   │
+  │<────────────────────────────────────│
+  │                                     │
+  │  {"type":"execution_complete",      │
+  │   "status":"success"}                │
+  │<────────────────────────────────────│
 ```

 ---

-## 六、安全设计
+## 七、数据库架构

-| 安全措施 | 说明 |
-|:---------|:-----|
-| JWT 认证 | Access Token 有效期短，Refresh Token 轮换 |
-| 密码加密 | bcrypt 哈希存储 |
-| CORS 配置 | 仅允许指定域名跨域访问 |
-| 输入验证 | Pydantic 严格校验所有输入 |
-| SQL 注入防护 | SQLAlchemy ORM 参数化查询 |
-| HTTPS | Nginx 侧终止 SSL（生产环境） |
+### 核心表关系
+
+```
+users (用户)
+├── agents (智能体)
+│   ├── agent_ratings (评分)
+│   ├── agent_favorites (收藏)
+│   ├── agent_schedules (定时任务)
+│   ├── agent_llm_logs (LLM 调用日志)
+│   ├── agent_vector_memories (向量记忆)
+│   └── agent_learning_patterns (学习模式)
+├── workflows (工作流)
+│   └── workflow_versions (版本历史)
+├── executions (执行记录)
+│   └── execution_logs (执行日志)
+├── knowledge_bases (知识库)
+│   ├── documents (文档)
+│   └── document_chunks (文档分块)
+├── notifications (通知)
+├── feedback_records (用户反馈)
+├── conversation_branches (对话分支)
+├── goals (目标)
+│   └── tasks (任务)
+├── orchestration_templates (编排模板)
+├── node_templates (节点模板)
+├── plugins (插件)
+├── alert_rules (告警规则)
+│   └── alert_logs (告警日志)
+├── persistent_user_memories (长期记忆)
+├── knowledge_entities (知识图谱节点)
+├── knowledge_relations (知识图谱关系)
+├── push_subscriptions (推送订阅)
+├── fcm_tokens (FCM Token)
+├── user_feishu_open_ids (飞书绑定)
+├── scene_contracts (场景契约 DSL)
+└── workspaces (工作区)
+    └── workspace_memberships (成员关系)
+```
+
+### 数据库索引策略
+
+- 所有外键列均有索引
+- 常用查询列（status / category / is_public / created_at）索引
+- 时间范围查询列（timestamp / triggered_at）索引
+- 复合索引用于高频组合查询（agent_id + created_at）

 ---

-## 七、扩展性 & 可维护性
+## 八、安全架构

- **水平扩展**：FastAPI 为无状态应用，可多实例部署 + Nginx 负载均衡
- **异步任务**：Celery Worker 可独立扩展，处理大量异步任务
- **模块化**：后端按业务拆分为 `modules/`，新增功能不影响现有模块
- **数据库迁移**：Alembic 管理 Schema 变更，支持回滚
- **前端组件化**：Vue 组件按功能拆解，提升复用性
+| 安全措施 | 实现方式 | 位置 |
+|:---------|:---------|:------|
+| JWT 认证 | HS256 签名，30min Access + 7d Refresh | `auth.py` middleware |
+| 密码安全 | bcrypt 哈希（12 rounds） | `auth.py` |
+| CORS 保护 | FastAPI CORSMiddleware，白名单域名 | `main.py` |
+| 输入验证 | Pydantic v2 严格验证所有 endpoint 输入 | 全部 schemas |
+| SQL 注入防护 | SQLAlchemy 2.0+ 参数化查询 | 全部 models |
+| XSS 防护 | CSP 头 + 输出转义（前端 Vue 3） | 前端 `index.html` |
+| CSRF 防护 | SameSite Cookie + Token Header | 前端 axios 配置 |
+| Rate Limiting | Redis 滑动窗口（登录 5/min，Webhook 60/min） | `rate_limiter.py` |
+| 安全头 | HSTS / X-Content-Type-Options / X-Frame-Options | `security_headers.py` |
+| 文件上传安全 | 类型检查 + 大小限制 + 病毒扫描 | `uploads.py` |
+| HTTPS | Nginx 侧 SSL 终止 | nginx.conf |
+| 密钥管理 | `.env` 文件 + `.env.example` 模板，不提交 Git | root |

 ---

-> 📎 **相关文档**：[项目结构概览](./project-structure.md) | [开发指南](./development-guide.md)
+## 九、可扩展性设计
+
+- **水平扩展**：FastAPI 无状态 → 多实例 + Nginx 负载均衡
+- **数据库读写分离**：MySQL 主从复制（生产环境可配置）
+- **缓存策略**：Redis 缓存热点数据（用户信息、Agent 配置）
+- **异步任务**：Celery Worker 独立扩展，处理 LLM 调用、文件处理、通知推送
+- **日志聚合**：ELK Stack（Filebeat → Elasticsearch → Kibana）
+- **监控告警**：Prometheus + Grafana，业务/系统双面板
+- **CI/CD**：GitHub Actions（ci.yml + deploy.yml + security.yml）
+- **容器化部署**：Docker Compose（dev/staging/prod 三套环境）
+- **多环境管理**：ENVIRONMENT 变量驱动的配置切换
+
+---
+
+## 十、前端架构
+
+```
+src/
+├── api/              # API 调用封装（axios 实例 + 拦截器）
+├── components/       # 公共组件库
+│   ├── chat/         # 聊天相关（StreamingText, MarkdownRenderer）
+│   ├── workflow/     # 工作流编辑器（DAG 画布、节点面板）
+│   ├── charts/       # 图表组件（ECharts）
+│   └── common/       # 通用组件（按钮、表单、弹窗）
+├── composables/      # 组合式 API（useSpeechRecognition, useTTS, usePWA）
+├── layouts/          # 布局组件（MainLayout, AdminLayout）
+├── router/           # 路由配置（32 个路由，全部懒加载）
+├── stores/           # Pinia 状态管理
+├── views/            # 页面组件（28 个页面）
+│   ├── MainConsole   # 主控台仪表盘
+│   ├── AgentDesigner # Agent 设计器
+│   ├── WorkflowEditor# 工作流编辑器
+│   ├── TemplateMarket# 模板市场
+│   ├── AgentMarket   # Agent 市场
+│   ├── KnowledgeBase # 知识库管理
+│   ├── Monitoring    # 系统监控
+│   └── ...           # 更多
+└── utils/            # 工具函数
+```
+
+---
+
+> 相关文档：[项目结构概览](./project-structure.md) | [开发指南](./development-guide.md) | [API 参考](./api-reference.md) | [插件开发指南](./plugin-development-guide.md)