gongzhiyongandClaude Sonnet 4.6
04d8fbb740
- 前端文件移入 frontend/ 子目录 - 新建 backend/ 目录（待开发） - 新增 CLAUDE.md、claudehd.md、EXTERNAL_SERVICES.md Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
107 lines
4.2 KiB
Markdown
107 lines
4.2 KiB
Markdown
# claudehd.md — so-c-chat-clone 后端功能方案
|
||
|
||
**前端代码未经明确指定不允许修改。**
|
||
|
||
---
|
||
|
||
## 功能一：基础对话
|
||
|
||
**做什么：** 用户发送消息，后端调用 LLM 生成回复，返回 Markdown 文本给前端渲染。
|
||
|
||
**用什么：**
|
||
- **FastAPI**（Python）— 提供 `POST /chat` 接口，接收 `message` + `thread_id` + `model`
|
||
- **Azure OpenAI SDK（异步）** — 调用 gpt-5.4 部署，返回文本内容
|
||
- **内存字典** — 按 `thread_id` 存储多轮对话历史，拼入每次请求的 messages 数组实现上下文连续
|
||
|
||
**模型行为：**
|
||
- `model=flash` → `max_tokens=500`，`temperature=0.2`，快速简洁
|
||
- `model=pro` → `max_tokens=4096`，`temperature=0.3`，深度详细
|
||
|
||
---
|
||
|
||
## 功能二：内部知识库检索
|
||
|
||
**做什么：** 用户在输入框激活"内部知识库"工具后，发送消息前先检索企业知识库，将相关文档片段注入 LLM prompt，让回复基于内部知识。
|
||
|
||
**用什么：**
|
||
- **httpx（异步）** — 调用 KB Agent REST API（Azure AI Search 代理）
|
||
- 检索参数：`search_mode=hybrid`，`top=5`
|
||
- 检索结果格式化为背景材料追加到 system prompt，LLM 基于此生成回复
|
||
|
||
---
|
||
|
||
## 功能三：外部 AI 搜索
|
||
|
||
**做什么：** 用户激活"搜索"工具后，后端联网检索实时信息（含图片、视频），经重排后注入 LLM，回复引用真实来源。
|
||
|
||
**用什么：**
|
||
- **Jina Search API** (`https://s.jina.ai/`) — 搜索网页，返回标题+摘要+URL
|
||
- **Jina Reader API** (`https://r.jina.ai/{url}`) — 读取搜索结果全文
|
||
- **Jina Rerank API** (`jina-reranker-v2-base-multilingual`) — 对结果按相关性重排，提升准确度
|
||
- **httpx（异步）** — 并发调用以上三个接口
|
||
|
||
**按模型深度区分：**
|
||
- `flash` → 搜索 top=3，timeout=8s，跳过重排，追求速度
|
||
- `pro` → 搜索 top=10，timeout=20s，Rerank 取 top=5，追求准确
|
||
|
||
---
|
||
|
||
## 功能四：沙盒代码执行
|
||
|
||
**做什么：** 用户激活"沙盒"工具并提出编程需求时，后端在隔离环境中执行代码，将 stdout/stderr 格式化为 Markdown 代码块注入回复。
|
||
|
||
**用什么：**
|
||
- **Daytona API** (`https://app.daytona.io/api`) — 创建隔离 workspace → 上传代码 → 执行 → 获取输出 → 销毁 workspace
|
||
- **httpx（异步）** — 调用 Daytona REST API
|
||
- 执行结果以 Markdown 代码块形式追加到 LLM 最终回复
|
||
|
||
---
|
||
|
||
## 功能五：文档生成
|
||
|
||
**做什么：** 用户激活"文档生成"工具并描述需求时，后端调用 Doc Creator Agent 生成 Word/PPT/表格文件，将下载链接追加到回复末尾。
|
||
|
||
**用什么：**
|
||
- **Doc Creator Agent** (`http://doc-creator-agent-b0d02105-a557fe.taijiagnet.com`) — 传入 prompt，返回生成文件的 URL
|
||
- **httpx（异步）** — 调用 Agent REST API
|
||
- 输出类型自动识别：含 ppt/slides → PPT；含 table/excel → 表格；其余 → Word
|
||
|
||
---
|
||
|
||
## 功能六：工单数据接入
|
||
|
||
**做什么：** 前端 ExtensionsPanel 连接工单系统后，展示真实工单列表（P0-P3 优先级、状态）。后端作为代理拉取 Gongdan 工单数据。
|
||
|
||
**用什么：**
|
||
- **FastAPI** — 提供 `GET /tickets` 接口，支持 `page` / `pageSize` 分页参数
|
||
- **httpx（异步）** — 代理调用 Gongdan API，透传工单数据
|
||
- 返回字段严格对齐前端 `TicketData` 类型：`id / title / status / priority / createdAt`
|
||
|
||
---
|
||
|
||
## 功能七：多轮对话持久化
|
||
|
||
**做什么：** 对话历史在服务重启后不丢失，支持恢复历史对话上下文。
|
||
|
||
**用什么：**
|
||
- **PostgreSQL**（Azure，`dataope.postgres.database.azure.com`）— 存储 thread 和 message 记录
|
||
- **asyncpg** — 异步数据库驱动，不阻塞事件循环
|
||
- 未配置 `DATABASE_URL` 时自动降级为内存字典（开发模式）
|
||
|
||
---
|
||
|
||
## 技术栈总览
|
||
|
||
| 层 | 技术 |
|
||
|----|------|
|
||
| Web 框架 | FastAPI + Uvicorn |
|
||
| LLM | Azure OpenAI SDK (AsyncAzureOpenAI) |
|
||
| HTTP 客户端 | httpx（全异步） |
|
||
| 外部搜索 | Jina Search / Reader / Rerank |
|
||
| 知识库 | KB Agent (Azure AI Search 代理) |
|
||
| 沙盒 | Daytona API |
|
||
| 文档生成 | Doc Creator Agent |
|
||
| 工单 | Gongdan API（只读代理） |
|
||
| 数据库 | PostgreSQL / asyncpg（可选） |
|
||
| 部署 | Azure Web App (Python 3.11) |
|