AI接口
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
供社区列表、项目详情、登录、我的工作区和在线文件编辑页面使用。前端通过 Community 后端完成所有业务操作;登录 Token 是平台 Token,前端不连接 Gitea、不持有 Gitea 凭据。
|
||||
|
||||
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、AI 检索、独立工作区实体或项目类型表。
|
||||
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞,以及可配置开启的 AI 对话搜索。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、独立工作区实体或项目类型表。
|
||||
|
||||
## 阅读导航
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
- [社区发布和撤回](#社区发布和撤回)
|
||||
- [社区详情和 Fork](#社区详情和-fork)
|
||||
- [评论和点赞](#评论和点赞)
|
||||
- [AI 对话搜索](#ai-对话搜索)
|
||||
- [错误码与前端处理](#错误码与前端处理)
|
||||
- [页面调用顺序](#页面调用顺序)
|
||||
- [前端请求示例](#前端请求示例)
|
||||
@@ -41,7 +42,7 @@
|
||||
|
||||
### 统一响应
|
||||
|
||||
除成功的文件下载外,响应为以下 JSON 结构。所有成功接口使用 HTTP 200,创建、删除、退出登录也不返回 201 或 204。
|
||||
除成功的文件下载和 AI 对话 SSE 外,响应为以下 JSON 结构;SSE 每个事件的 data 也使用此包装。所有成功接口使用 HTTP 200,创建、删除、退出登录也不返回 201 或 204。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -122,6 +123,7 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。
|
||||
| DELETE | `/api/comments/{commentCode}` | 是 | null |
|
||||
| PUT | `/api/community/projects/{projectCode}/like` | 是 | null |
|
||||
| DELETE | `/api/community/projects/{projectCode}/like` | 是 | null |
|
||||
| POST | `/api/community/ai/chat` | 是 | SSE 事件流,见 AI 对话搜索 |
|
||||
|
||||
## 响应数据结构
|
||||
|
||||
@@ -714,6 +716,184 @@ content 非空,最多 2000 字符,保存时去掉首尾空格。成功 data
|
||||
|
||||
均无请求体,成功 data 为 null,两者幂等。点赞接口不返回最新计数,成功后重新请求社区详情获取 liked、likeCount;可以先做乐观更新,失败时恢复并刷新详情。
|
||||
|
||||
## AI 对话搜索
|
||||
|
||||
`POST /api/community/ai/chat`,需要登录。请求头为 `Content-Type: application/json`、`Accept: text/event-stream` 和 `Authorization: Bearer <平台 token>`。普通 JSON 请求封装不能用于读取该接口的成功响应。
|
||||
|
||||
该功能只检索社区已发布、仓库就绪且未删除项目的名称、描述和类型,不读取 README、代码或评论。模型先提取条件,后端查询最多20个候选,再由模型排序;最终返回最多5张经过校验的项目卡片。名称、描述没有写明的技术能力无法可靠匹配,缺少依据的偏好通过 unverifiedRequirements 提示;明确要求缺少依据时不作为满足条件的结果。
|
||||
|
||||
### 请求与对话维护
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "改成轮式,其他要求不变",
|
||||
"history": [
|
||||
{ "role": "user", "content": "找四足机器人,必须支持ROS2,最好适合教学" },
|
||||
{ "role": "assistant", "content": "为你找到 1 个候选项目,请结合匹配依据和未确认事项查看详情。" }
|
||||
],
|
||||
"previousProjectCodes": ["11111111111111111111111111111111"]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 限制及用途 |
|
||||
| --- | --- |
|
||||
| message | 必填,非空,最多2000字符,当前问题不重复放入 history |
|
||||
| history | 可省略或为 null,最多12条,保留最近6轮完整 user/assistant 对话;从 user 开始、交替排列并以 assistant 结束;每条 content 非空且最多2000字符,不接受 system 角色 |
|
||||
| previousProjectCodes | 可省略或为 null,最多5个项目编码,每个非空且最多32字符;按上一轮卡片展示顺序提交,用于理解“第二个项目”等指代,后端只读取其中仍可见的社区项目 |
|
||||
|
||||
前端在内存维护对话,仅在收到 result 后将当前问题和 reply 组成完整的一轮追加到 history,下一次提交前保留末尾12条。同步使用本轮 projects 的编码列表替换 previousProjectCodes。error、网络失败或主动取消时不追加未完成对话。新建对话或刷新页面清空两者,无服务端会话创建、恢复或删除接口。
|
||||
|
||||
### SSE 事件与响应类型
|
||||
|
||||
```typescript
|
||||
export interface AiChatRequest {
|
||||
message: string;
|
||||
history?: Array<{ role: 'user' | 'assistant'; content: string }>;
|
||||
previousProjectCodes?: string[];
|
||||
}
|
||||
|
||||
export interface AiProgress {
|
||||
stage: 'understanding' | 'searching' | 'ranking' | 'validating';
|
||||
message: string;
|
||||
}
|
||||
|
||||
export interface AiProjectCard {
|
||||
project: Project; // 复用上文项目类型,包含 projectCode 和 publishedCommitSha
|
||||
reason: string;
|
||||
evidence: Array<{
|
||||
field: 'name' | 'description' | 'projectType';
|
||||
quote: string; // 在对应字段中核验过的连续原文
|
||||
requirement: string | null; // 该证据对应的要求或偏好;一般依据为 null
|
||||
}>;
|
||||
unverifiedRequirements: string[]; // 未确认的偏好,不代表已经满足
|
||||
}
|
||||
|
||||
export interface AiChatResult {
|
||||
status: 'MATCHED' | 'NO_MATCH' | 'NEEDS_CLARIFICATION';
|
||||
reply: string;
|
||||
projects: AiProjectCard[];
|
||||
}
|
||||
```
|
||||
|
||||
| 事件 | data 类型 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| progress | `ApiResponse<AiProgress>` | 展示阶段;空候选或需要澄清时可能提前结束,不保证四个阶段全部出现 |
|
||||
| result | `ApiResponse<AiChatResult>` | 一次最终结果,随后关闭连接;NO_MATCH 与 NEEDS_CLARIFICATION 的 projects 为空数组,均为正常业务结果 |
|
||||
| error | `ApiResponse<null>`,code 非 OK | 显示错误并结束本轮;不要自动重试 |
|
||||
|
||||
阶段消息是服务端进度,不是逐字生成的模型文字。心跳使用 `:keep-alive` 注释行,没有 JSON 数据,解析器直接忽略。项目和推荐文字按纯文本渲染;链接由前端使用 project.projectCode 生成,不将模型文字当作 HTML 或链接执行。点击卡片后使用既有社区详情接口重新读取当前项目,撤下的项目可能返回404。
|
||||
|
||||
事件流示例:
|
||||
|
||||
```text
|
||||
event:progress
|
||||
data:{"code":"OK","message":"成功","data":{"stage":"understanding","message":"正在理解需求"},"requestId":"44444444444444444444444444444444"}
|
||||
|
||||
event:result
|
||||
data:{"code":"OK","message":"成功","data":{"status":"NO_MATCH","reply":"暂未找到有充分资料匹配要求的社区项目,可以尝试调整类型或减少条件。","projects":[]},"requestId":"44444444444444444444444444444444"}
|
||||
|
||||
```
|
||||
|
||||
鉴权、参数、功能关闭和入口限流发生在建流前,按 HTTP 400/401/429/503 返回普通 JSON;流建立后发生的模型异常通过 error 事件返回,此时 HTTP 状态仍为200。requestId 与入口响应头一致。
|
||||
|
||||
| 错误码 | 含义与前端处理 |
|
||||
| --- | --- |
|
||||
| AI_UNAVAILABLE | AI 未启用或正在停止,提示暂不可用,保留普通搜索入口 |
|
||||
| AI_BUSY | 达到全局并发上限,入口 HTTP 429,稍后手动重试 |
|
||||
| AI_RATE_LIMITED | 超过当前用户频率限制,入口 HTTP 429,稍后手动重试 |
|
||||
| AI_TIMEOUT | 模型调用或整次搜索超时,可减少条件后手动重试 |
|
||||
| AI_PROVIDER_FAILURE | 上游 HTTP 错误、响应不完整或格式异常,提示服务异常 |
|
||||
| AI_INVALID_RESPONSE | 模型结果的编码、字段或引用未通过校验,本轮不展示推荐 |
|
||||
| AI_SEARCH_FAILURE | 服务内部异常,携带 requestId 联系后端 |
|
||||
|
||||
默认每次模型调用30秒,整次搜索65秒,全局并发4个、每用户滑动一分钟最多10次,超限不排队。主动取消通过 AbortController;服务端在检测连接断开后尽力取消上游,实际工作结束后释放并发名额。不要在页面上同时启动多个搜索;代理应关闭 SSE 缓冲,读取超时至少90秒。
|
||||
|
||||
### fetch 接收 SSE 示例
|
||||
|
||||
以下示例复用下文的 API_BASE、ApiError 和上文的数据类型。它处理跨网络分块的 UTF-8 文本和 SSE 边界,不使用不能携带 Bearer 请求头的原生 EventSource。
|
||||
|
||||
```typescript
|
||||
async function chatAi(
|
||||
input: AiChatRequest,
|
||||
token: string,
|
||||
onProgress: (progress: AiProgress) => void,
|
||||
signal?: AbortSignal,
|
||||
): Promise<AiChatResult> {
|
||||
const response = await fetch(`${API_BASE}/community/ai/chat`, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
Authorization: `Bearer ${token}`,
|
||||
'Content-Type': 'application/json',
|
||||
Accept: 'text/event-stream',
|
||||
},
|
||||
body: JSON.stringify(input),
|
||||
signal,
|
||||
});
|
||||
const requestId = response.headers.get('X-Request-Id');
|
||||
if (!response.ok) {
|
||||
const failure: ApiResponse<null> = await response.json();
|
||||
throw new ApiError(response.status, failure.code, failure.message,
|
||||
failure.requestId ?? requestId);
|
||||
}
|
||||
if (!response.body || !response.headers.get('Content-Type')?.includes('text/event-stream')) {
|
||||
throw new ApiError(response.status, 'BAD_RESPONSE', '接口未返回事件流', requestId);
|
||||
}
|
||||
|
||||
const reader = response.body.getReader();
|
||||
const decoder = new TextDecoder();
|
||||
let buffer = '';
|
||||
let eventName = '';
|
||||
let dataLines: string[] = [];
|
||||
let result: AiChatResult | undefined;
|
||||
|
||||
function dispatch() {
|
||||
if (!dataLines.length) { eventName = ''; return; }
|
||||
const event: ApiResponse<AiProgress | AiChatResult> = JSON.parse(dataLines.join('\n'));
|
||||
dataLines = [];
|
||||
if (eventName === 'error' || event.code !== 'OK') {
|
||||
throw new ApiError(response.status, event.code, event.message,
|
||||
event.requestId ?? requestId);
|
||||
}
|
||||
if (eventName === 'progress') onProgress(event.data as AiProgress);
|
||||
if (eventName === 'result') result = event.data as AiChatResult;
|
||||
eventName = '';
|
||||
}
|
||||
|
||||
try {
|
||||
while (true) {
|
||||
const { value, done } = await reader.read();
|
||||
buffer += decoder.decode(value, { stream: !done });
|
||||
let end: number;
|
||||
while ((end = buffer.indexOf('\n')) >= 0) {
|
||||
const line = buffer.slice(0, end).replace(/\r$/, '');
|
||||
buffer = buffer.slice(end + 1);
|
||||
if (!line) dispatch();
|
||||
else if (line.startsWith('event:')) eventName = line.slice(6).trim();
|
||||
else if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart());
|
||||
// 注释心跳及其他字段忽略。
|
||||
}
|
||||
if (result) return result;
|
||||
if (done) break;
|
||||
}
|
||||
throw new ApiError(response.status, 'AI_STREAM_INCOMPLETE',
|
||||
'连接提前结束,未收到搜索结果', requestId); // 前端封装错误码
|
||||
} finally {
|
||||
await reader.cancel().catch(() => {});
|
||||
reader.releaseLock();
|
||||
}
|
||||
}
|
||||
|
||||
// 点击“停止”或离开页面时执行 controller.abort()。
|
||||
const controller = new AbortController();
|
||||
const result = await chatAi(
|
||||
{ message: '找适合教学的四足机器人,最好支持ROS2' },
|
||||
token,
|
||||
progress => console.log(progress.message),
|
||||
controller.signal,
|
||||
);
|
||||
// 收到 result 后更新页面和最近6轮 history,卡片通过 project.projectCode 跳转。
|
||||
```
|
||||
|
||||
## 错误码与前端处理
|
||||
|
||||
### 错误响应示例
|
||||
Reference in New Issue
Block a user