This commit is contained in:
lxp
2026-10-14 16:55:07 +08:00
parent fb1a31f782
commit 92b2251f25
29 changed files with 1769 additions and 12 deletions
+182 -2
View File
@@ -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 跳转。
```
## 错误码与前端处理
### 错误响应示例