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>
This commit is contained in:
283
docs/faq.md
Normal file
283
docs/faq.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# ❓ 常见问题 FAQ
|
||||
|
||||
> **Frequently Asked Questions** — 天工智能体平台使用中的常见问题与解答
|
||||
|
||||
---
|
||||
|
||||
## 一、通用问题
|
||||
|
||||
### Q1: 天工智能体平台是什么？
|
||||
|
||||
天工是一个 AI Agent 搭建与工作流编排平台。你可以用它创建专属的 AI 数字员工，通过可视化拖拽设计工作流，让 Agent 调用工具自动完成任务。
|
||||
|
||||
### Q2: 平台收费吗？
|
||||
|
||||
目前为社区版，免费使用。商业化版本（专业版/企业版）规划中，将提供多租户、高级监控等增强功能。
|
||||
|
||||
### Q3: 支持哪些 LLM 模型？
|
||||
|
||||
支持 OpenAI (GPT-4o)、DeepSeek (V3/R1)、Anthropic (Claude Opus/Sonnet/Haiku) 及兼容 OpenAI API 格式的其他模型。在 Agent 配置中可自由选择和切换。
|
||||
|
||||
### Q4: 数据安全吗？
|
||||
|
||||
- 数据库连接支持 SSL/TLS
|
||||
- JWT 认证 + 密码哈希存储
|
||||
- API 速率限制保护
|
||||
- 安全响应头 (HSTS/X-Frame-Options/X-XSS-Protection)
|
||||
- 危险工具需人工审批 (HITL)
|
||||
|
||||
---
|
||||
|
||||
## 二、Agent 相关
|
||||
|
||||
### Q5: 如何创建一个好的 Agent？
|
||||
|
||||
见《最佳实践指南》。核心要点：明确的角色描述 + 合适的工具集 + 清晰的工作流设计 + 充分的测试。
|
||||
|
||||
### Q6: Agent 状态一直显示"草稿"怎么办？
|
||||
|
||||
点击 Agent 设计器中的「部署」按钮，Agent 将依次经过：草稿 → 发布中 → 已发布。
|
||||
|
||||
### Q7: 已部署的 Agent 可以修改吗？
|
||||
|
||||
可以。修改后需要重新部署。旧版本会自动保存为工作流版本，可在版本管理中回滚。
|
||||
|
||||
### Q8: Agent 执行到一半卡住了？
|
||||
|
||||
1. 检查执行记录中的节点日志
|
||||
2. 查看 LLM API 是否配额耗尽或超时
|
||||
3. 检查工具调用是否有循环依赖
|
||||
4. 查看 Celery Worker 日志确认任务是否正常消费
|
||||
|
||||
### Q9: 为什么看不到"使用"按钮？
|
||||
|
||||
只有状态为「已发布」或「运行中」的 Agent 才显示使用按钮。草稿状态的 Agent 只有创建者可以在设计器中测试。
|
||||
|
||||
### Q10: 一个用户可以创建多少个 Agent？
|
||||
|
||||
无数量限制。
|
||||
|
||||
### Q11: Agent 如何记住之前的对话？
|
||||
|
||||
在 Agent 配置中开启「启用记忆」，设置记忆范围（个人/团队）。Agent 会将对话精简压缩存入向量数据库，下次对话时自动检索相关记忆。
|
||||
|
||||
### Q12: Agent 间能共享知识吗？
|
||||
|
||||
同一团队的 Agent 可以通过「团队记忆」共享知识。启用后，一个 Agent 学到的内容可以被同团队其他 Agent 检索使用。
|
||||
|
||||
---
|
||||
|
||||
## 三、工作流相关
|
||||
|
||||
### Q13: 工作流节点有哪些类型？
|
||||
|
||||
触发器、LLM 节点、工具节点、条件分支、循环节点、子工作流、评估器、编排器、输出节点。详见《用户使用手册》第四章。
|
||||
|
||||
### Q14: 如何让 LLM 节点引用上游输出？
|
||||
|
||||
在提示词模板中使用 `{{变量名}}` 语法。例如：`{{trigger.output}}` 引用触发器的输出，`{{node_1.result}}` 引用节点1的结果。
|
||||
|
||||
### Q15: 工作流可以嵌套吗？
|
||||
|
||||
可以。使用「子工作流」节点调用另一个工作流，支持输入映射和深度保护（防止无限递归）。
|
||||
|
||||
### Q16: 多个分支可以并行执行吗？
|
||||
|
||||
可以。DAG 工作流的多分支通过 `asyncio.gather` 并发执行，无依赖关系的节点同时运行。
|
||||
|
||||
### Q17: 节点执行失败会自动重试吗？
|
||||
|
||||
在工作流编辑器中选中节点，配置「重试策略」：最大重试次数、重试间隔、错误处理方式（重试/通知/停止）。
|
||||
|
||||
### Q18: 如何调试工作流？
|
||||
|
||||
1. 使用「节点测试」功能单独测试每个节点
|
||||
2. 查看执行记录的节点级日志（输入/输出/耗时）
|
||||
3. 使用评估器节点验证输出质量
|
||||
|
||||
### Q19: 工作流版本如何管理？
|
||||
|
||||
每次保存工作流自动生成版本。在版本管理中可查看历史版本、对比差异、回滚到任一历史版本。
|
||||
|
||||
---
|
||||
|
||||
## 四、知识库相关
|
||||
|
||||
### Q20: 支持哪些文档格式？
|
||||
|
||||
PDF、TXT、Markdown、Word (.docx)、Excel (.xlsx)、HTML、CSV。
|
||||
|
||||
### Q21: 文档上传后多久能被检索到？
|
||||
|
||||
上传后自动切片和向量化，通常在 30 秒内完成。大文档可能需要 1-2 分钟。
|
||||
|
||||
### Q22: 知识库能存多少文档？
|
||||
|
||||
取决于向量数据库容量。建议单个知识库不超过 10,000 个文档，单个文档不超过 50MB。
|
||||
|
||||
### Q23: RAG 检索不准怎么办？
|
||||
|
||||
1. 确保文档内容清晰结构化
|
||||
2. 拆分过大的文档为多个小文档
|
||||
3. 使用更精确的系统提示词引导 Agent 如何使用检索结果
|
||||
|
||||
### Q24: 知识会自动更新吗？
|
||||
|
||||
会。Celery Beat 定时任务每小时从 Agent 对话中提取新知识点自动入库，形成知识进化闭环。
|
||||
|
||||
---
|
||||
|
||||
## 五、账号与权限
|
||||
|
||||
### Q25: 默认账号密码是什么？
|
||||
|
||||
默认管理员：`admin` / `123456`
|
||||
|
||||
**⚠️ 生产环境请第一时间修改默认密码。**
|
||||
|
||||
### Q26: 忘记密码怎么办？
|
||||
|
||||
联系管理员重置密码。自助找回密码功能规划中。
|
||||
|
||||
### Q27: 如何创建新用户？
|
||||
|
||||
当前版本通过注册接口创建：`POST /api/v1/auth/register`。管理后台用户管理界面规划中。
|
||||
|
||||
### Q28: 权限级别有哪些？
|
||||
|
||||
目前支持：管理员（admin）和普通用户（user）。多租户的 workspace_admin / member 角色规划中。
|
||||
|
||||
---
|
||||
|
||||
## 六、API 与集成
|
||||
|
||||
### Q29: 如何通过 API 调用 Agent？
|
||||
|
||||
```bash
|
||||
# 1. 登录获取 token
|
||||
curl -X POST http://localhost:8038/api/v1/auth/login \
|
||||
-d "username=admin&password=123456"
|
||||
|
||||
# 2. 通过 agent-chat 接口对话
|
||||
curl -X POST http://localhost:8038/api/v1/agent-chat/bare \
|
||||
-H "Authorization: Bearer <TOKEN>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "你的问题"}'
|
||||
```
|
||||
|
||||
详细 API 文档见：`/docs` (Swagger UI) 或 `/redoc`。
|
||||
|
||||
### Q30: 支持哪些认证方式？
|
||||
|
||||
JWT Bearer Token。登录获得 access_token，在请求头中携带 `Authorization: Bearer <token>`。
|
||||
|
||||
### Q31: API 有限流吗？
|
||||
|
||||
有。登录接口 5 次/分钟，Webhook 接口 60 次/分钟，其他接口默认 120 次/分钟。
|
||||
|
||||
### Q32: 飞书 Bot 如何配置？
|
||||
|
||||
参见《飞书智能体配置手册》(`docs/飞书智能体配置手册.md`)。
|
||||
|
||||
---
|
||||
|
||||
## 七、部署运维
|
||||
|
||||
### Q33: 最低服务器配置要求？
|
||||
|
||||
- 开发环境：2 核 CPU / 4 GB 内存 / 20 GB 磁盘
|
||||
- 生产环境：8 核 CPU / 16 GB 内存 / 100 GB SSD
|
||||
|
||||
### Q34: 支持哪些部署方式？
|
||||
|
||||
1. Docker Compose 一键部署（推荐）
|
||||
2. 手动安装（Python + Node.js）
|
||||
3. Kubernetes（规划中）
|
||||
|
||||
详见《部署与运维指南》。
|
||||
|
||||
### Q35: 如何备份数据？
|
||||
|
||||
- **数据库**：使用腾讯云自动备份 或 `mysqldump` 每日备份
|
||||
- **配置文件**：`.env` 文件纳入 Git 私有仓库管理
|
||||
- 详见 `install.sh` / `upgrade.sh` / `uninstall.sh` 脚本
|
||||
|
||||
### Q36: 如何升级版本？
|
||||
|
||||
运行 `upgrade.sh` 脚本，自动完成：备份 → 拉取新镜像 → 滚动重启服务 → 清理旧镜像。
|
||||
|
||||
### Q37: 日志在哪里查看？
|
||||
|
||||
- **API 日志**：`backend/logs/app.log`（自动轮转，保留 30 天）
|
||||
- **Docker 日志**：`docker-compose logs -f`
|
||||
- **Celery 日志**：Worker 标准输出
|
||||
- **系统日志**：前端「系统日志」页面
|
||||
|
||||
---
|
||||
|
||||
## 八、故障排查
|
||||
|
||||
### Q38: 前端页面空白或加载失败？
|
||||
|
||||
1. 检查后端 API 是否正常：访问 `/health` 端点
|
||||
2. 检查浏览器控制台是否有 CORS 错误
|
||||
3. 确认 Vite 代理目标端口正确（默认 8038）
|
||||
|
||||
### Q39: API 返回 502 Bad Gateway？
|
||||
|
||||
后端服务未启动或已崩溃。检查：
|
||||
```bash
|
||||
docker-compose ps backend
|
||||
docker-compose logs backend
|
||||
```
|
||||
|
||||
### Q40: 数据库连接失败？
|
||||
|
||||
1. 检查 `.env` 中 `DATABASE_URL` 是否正确
|
||||
2. 确认数据库服务器网络可达
|
||||
3. 检查防火墙是否放行数据库端口
|
||||
|
||||
### Q41: LLM 调用返回超时或错误？
|
||||
|
||||
1. 检查 API Key 是否有效且配额充足
|
||||
2. 检查网络是否能访问 LLM API 地址
|
||||
3. 尝试切换模型或配置 Fallback LLM
|
||||
4. 增大工具超时时间
|
||||
|
||||
### Q42: Celery Worker 不消费任务？
|
||||
|
||||
1. 确认 Redis 是否正常运行
|
||||
2. 检查 Worker 是否启动：`celery -A app.core.celery_app worker --loglevel=info`
|
||||
3. 检查任务队列是否有积压
|
||||
|
||||
### Q43: Agent 说"没有可用工具"？
|
||||
|
||||
1. 检查 Agent 配置中是否启用了工具
|
||||
2. 检查 `/health` 端点确认内置工具已注册（56 个）
|
||||
3. 重启 Celery Worker 确保工具引导完成
|
||||
|
||||
---
|
||||
|
||||
## 九、其他
|
||||
|
||||
### Q44: 可以在移动端使用吗？
|
||||
|
||||
可以。访问 `/mobile-chat` 路径使用移动端优化版。支持 PWA 安装到手机桌面，以及语音输入/播报。
|
||||
|
||||
### Q45: 支持哪些语言？
|
||||
|
||||
平台界面为中文，Agent 对话支持任意语言（取决于 LLM 模型能力）。
|
||||
|
||||
### Q46: 有视频教程吗？
|
||||
|
||||
规划中。目前可参考《用户使用手册》和《快速开始指南》。
|
||||
|
||||
### Q47: 如何反馈问题或建议？
|
||||
|
||||
- 提交 GitHub Issue
|
||||
- 联系平台开发团队
|
||||
- 在飞书 Bot 中反馈
|
||||
|
||||
---
|
||||
|
||||
> 最后更新：2026-06-14 | 适用版本 v1.0+
|
||||
Reference in New Issue
Block a user