This commit is contained in:
lxp
2026-10-16 17:01:53 +08:00
parent 909abe9f1d
commit 7d0267d2f3
13 changed files with 347 additions and 82 deletions
+30 -16
View File
@@ -2,7 +2,7 @@
供社区列表、项目详情、登录、我的工作区和在线文件编辑页面使用。前端通过 Community 后端完成所有业务操作;登录 Token 是平台 Token,前端不连接 Gitea、不持有 Gitea 凭据。
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞,以及可配置开启的 AI 项目助手(查找、创建空项目、Fork)。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、独立工作区实体或项目类型表。
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、独立工作区实体或项目类型表。
## 阅读导航
@@ -19,7 +19,7 @@
- [社区发布和撤回](#社区发布和撤回)
- [社区详情和 Fork](#社区详情和-fork)
- [评论和点赞](#评论和点赞)
- [AI 项目助手](#ai-项目助手)
- [Maker AI](#maker-ai)
- [错误码与前端处理](#错误码与前端处理)
- [页面调用顺序](#页面调用顺序)
- [前端请求示例](#前端请求示例)
@@ -140,7 +140,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 项目助手 |
| POST | `/api/community/ai/chat` | 是 | SSE 事件流,见 Maker AI |
## 响应数据结构
@@ -995,18 +995,22 @@ content 非空,最多 2000 字符,保存时去掉首尾空格。成功 data
均无请求体,成功 data 为 null,两者幂等。点赞接口不返回最新计数,成功后重新请求社区详情获取 liked、likeCount;可以先做乐观更新,失败时恢复并刷新详情。
## AI 项目助手
## Maker AI
`POST /api/community/ai/chat`,需要登录。请求头为 `Content-Type: application/json`、`Accept: text/event-stream` 和 `Authorization: Bearer <平台 token>`。普通 JSON 请求封装不能用于读取该接口的成功响应。
Maker AI 支持身份介绍、日常闲聊、一般知识和技术问答,可在回复中给出文本代码示例。聊天基于模型知识,不联网、不执行代码、不写入项目;例如发送 `{"message":"你是谁"}`,会介绍自己为 Maker AI,而不是要求补充项目需求。聊天与项目操作共用同一个接口和最近6轮历史。
查找时只检索社区已发布、仓库就绪且未删除项目的名称、描述和类型,不读取 README、代码或评论。模型先提取条件,后端查询最多20个候选,再由模型排序;最终返回最多5张经过校验的项目卡片。名称、描述没有写明的技术能力无法可靠匹配,缺少依据的偏好通过 unverifiedRequirements 提示;明确要求缺少依据时不作为满足条件的结果。
### 支持的操作
接口根据当前 message 识别操作,history 用于补充需求和理解指代。明确要求且信息充分时直接执行,不增加确认步骤;每轮最多执行一次创建或 Fork,多项写入要求先请用户选择一项。历史中已完成的操作不会再次执行。
接口根据当前 message 识别操作,history 用于聊天上下文、补充需求和理解指代。明确要求且信息充分时直接执行,不增加确认步骤;每轮最多执行一次创建或 Fork,多项写入要求先请用户选择一项。问候、感谢和普通聊天不会触发历史中的待办操作,历史中已完成的操作不会再次执行。明确查找平台项目或追问候选项目详情走项目检索,一般概念解释和创意讨论直接回答。
| 操作 | 示例 | 行为 |
| --- | --- | --- |
| 聊天与身份介绍 | 你好,你是谁 | 以 Maker AI 身份自然回答,返回 CHAT,不进行候选检索或项目写入 |
| 知识与技术问答 | 什么是 ROS2?用 Java 写一个循环示例 | 直接解答,可返回文本代码示例,不创建项目或实际执行代码 |
| 查找 | 找适合教学、支持 ROS2 的四足项目 | 返回最多5张有依据的社区项目卡片 |
| 创建空项目 | 创建一个轮式导航实验项目,叫“我的导航实验” | 提取或生成名称和目标描述,类型无法判断时使用 GENERAL;初始化私有仓库和默认 README,不生成业务代码、不自动发布 |
| 按编码 Fork | Fork 项目 7m4k9x2p8q6r,副本叫“我的实验” | 后端核验来源,复制执行时的当前发布版本到本人工作区 |
@@ -1034,9 +1038,9 @@ Fork 不使用模型生成的 SHA。后端在执行前读取来源的当前发
| --- | --- |
| message | 必填,非空,最多2000字符,当前问题不重复放入 history |
| history | 可省略或为 null,最多12条,保留最近6轮完整 user/assistant 对话;从 user 开始、交替排列并以 assistant 结束;每条 content 非空且最多2000字符,不接受 system 角色 |
| previousProjectCodes | 可省略或为 null,最多5个项目编码,每个非空且最多32字符;按上一轮卡片展示顺序提交,用于理解“第二个项目”等指代,后端只读取其中仍可见的社区项目 |
| previousProjectCodes | 可省略或为 null,最多5个项目编码,每个非空且最多32字符;按最近一次项目结果的卡片展示顺序提交,穿插 CHAT 时保留,用于理解“第二个项目”等指代,后端只读取其中仍可见的社区项目 |
前端在内存维护对话,仅在收到 result 后将当前问题和 reply 组成完整的一轮追加到 history,下一次提交前保留末尾12条。同步使用本轮 projects 的编码列表替换 previousProjectCodes,包括 NEEDS_SELECTION 的候选;CREATED、FORKED 的 projects 为空,应清空上一轮候选编码。error、网络失败或主动取消时不追加未完成对话。新建对话或刷新页面清空两者,无服务端会话创建、恢复或删除接口。
前端在内存维护对话,仅在收到 result 后将当前问题和 reply 组成完整的一轮追加到 history,下一次提交前保留末尾12条。CHAT 同样追加历史,但保留原 previousProjectCodes,不用空 projects 覆盖,也不必清除已展示的项目卡片,支持“搜索 → 闲聊 → Fork 第二个”。其他状态使用本轮 projects 的编码列表替换 previousProjectCodes,包括 NEEDS_SELECTION 的候选;CREATED、FORKED 的 projects 为空,应清空上一轮候选编码。error、网络失败或主动取消时不追加未完成对话。新建对话或刷新页面清空两者,无服务端会话创建、恢复或删除接口。
### SSE 事件与响应类型
@@ -1064,8 +1068,8 @@ export interface AiProjectCard {
}
export interface AiChatResult {
status: 'MATCHED' | 'NO_MATCH' | 'NEEDS_CLARIFICATION' | 'NEEDS_SELECTION' | 'CREATED' | 'FORKED';
reply: string;
status: 'CHAT' | 'MATCHED' | 'NO_MATCH' | 'NEEDS_CLARIFICATION' | 'NEEDS_SELECTION' | 'CREATED' | 'FORKED';
reply: string; // CHAT 为非空完整回复,最多2000字符,可直接追加到 history
projects: AiProjectCard[]; // MATCHED、NEEDS_SELECTION 返回候选,其他状态为空数组
project: Project | null; // CREATED、FORKED 返回操作后的项目,其他状态为 null
}
@@ -1073,11 +1077,11 @@ export interface AiChatResult {
| 事件 | data 类型 | 行为 |
| --- | --- | --- |
| progress | `ApiResponse<AiProgress>` | 展示阶段;空候选或需要澄清时可能提前结束,不保证所有阶段全部出现;直接创建或 Fork 无搜索阶段 |
| result | `ApiResponse<AiChatResult>` | 一次最终结果,随后关闭连接;所有状态均为正常业务结果;NEEDS_SELECTION 展示候选等待选择,CREATED/FORKED 使用 project.projectCode 进入工作区 |
| progress | `ApiResponse<AiProgress>` | 展示阶段;CHAT 只有 understanding 阶段;空候选或需要澄清时可能提前结束,不保证所有阶段全部出现;直接创建或 Fork 无搜索阶段 |
| result | `ApiResponse<AiChatResult>` | 一次最终结果,随后关闭连接;所有状态均为正常业务结果;CHAT 展示 reply、保留候选编码;NEEDS_SELECTION 展示候选等待选择,CREATED/FORKED 使用 project.projectCode 进入工作区 |
| error | `ApiResponse<{ projectCode?: string } \| null>`,code 非 OK | 显示错误并结束本轮;初始化异常可能携带项目编码,先核对工作区,不要自动重试 |
阶段消息是服务端进度,不是逐字生成的模型文字。心跳使用 `:keep-alive` 注释行,没有 JSON 数据,解析器直接忽略。项目和推荐文字按纯文本渲染;链接由前端使用 project.projectCode 生成,不将模型文字当作 HTML 或链接执行。点击搜索卡片后使用既有社区详情接口重新读取当前项目,撤下的项目可能返回404。CREATED、FORKED 使用 result.project.projectCode 打开工作区详情,不能用社区详情接口读取尚未发布的新项目。
阶段消息是服务端进度,不是逐字生成的模型文字。聊天复用一次意图识别调用生成完整 reply,事件顺序为 understanding → result,不新增逐字输出事件。心跳使用 `:keep-alive` 注释行,没有 JSON 数据,解析器直接忽略。聊天回复、代码示例、项目和推荐文字按纯文本渲染;链接由前端使用 project.projectCode 生成,不将模型文字当作 HTML 或链接执行。点击搜索卡片后使用既有社区详情接口重新读取当前项目,撤下的项目可能返回404。CREATED、FORKED 使用 result.project.projectCode 打开工作区详情,不能用社区详情接口读取尚未发布的新项目。
事件流示例:
@@ -1086,7 +1090,7 @@ event:progress
data:{"code":"OK","message":"成功","data":{"stage":"understanding","message":"正在理解需求"},"requestId":"44444444444444444444444444444444"}
event:result
data:{"code":"OK","message":"成功","data":{"status":"NO_MATCH","reply":"暂未找到有充分资料匹配要求的社区项目,可以尝试调整类型或减少条件。","projects":[],"project":null},"requestId":"44444444444444444444444444444444"}
data:{"code":"OK","message":"成功","data":{"status":"CHAT","reply":"我是 Maker AI,可以陪你聊天、解答问题、讨论创意,也能帮你查找、创建和 Fork 社区项目。","projects":[],"project":null},"requestId":"44444444444444444444444444444444"}
```
@@ -1099,7 +1103,7 @@ data:{"code":"OK","message":"成功","data":{"status":"NO_MATCH","reply":"暂未
| AI_RATE_LIMITED | 超过当前用户频率限制,入口 HTTP 429,稍后手动重试 |
| AI_TIMEOUT | 模型调用或整次处理超时;涉及创建或 Fork 时先核对工作区,不能直接重试 |
| AI_PROVIDER_FAILURE | 上游 HTTP 错误、响应不完整或格式异常,提示服务异常 |
| AI_INVALID_RESPONSE | 模型结果的操作、参数、编码或引用未通过校验,不执行该操作 |
| AI_INVALID_RESPONSE | 模型结果的操作、参数、编码、引用或聊天回复未通过校验(如空白、超长或 CHAT 夹带项目参数),不执行该操作 |
| AI_SEARCH_FAILURE | 服务内部异常,携带 requestId 联系后端;涉及写入时先核对工作区 |
| NOT_FOUND / CONFLICT | Fork 来源不可访问或发布版本变化,不自动重新选择或换版本执行 |
| FORK_UNAVAILABLE / FORK_BUSY / FORK_RESOURCE_LIMIT / FORK_COPY_FAILED / FORK_TIMEOUT / FORK_CANCELLED | 按上文 Fork 错误码处理;error 事件不会改变已建立 SSE 的 HTTP 200 状态 |
@@ -1184,13 +1188,23 @@ async function chatAi(
// 点击“停止”或离开页面时执行 controller.abort()。
const controller = new AbortController();
// 实际页面应将两者保存在组件状态中,并在后续请求时复用。
let history: NonNullable<AiChatRequest['history']> = [];
let previousProjectCodes: string[] = [];
const message = '找适合教学的四足机器人,最好支持ROS2';
const result = await chatAi(
{ message: '找适合教学的四足机器人,最好支持ROS2' },
{ message, history, previousProjectCodes },
token,
progress => console.log(progress.message),
controller.signal,
);
// 收到 result 后更新页面和最近6轮 history,按 result.projects 更新 previousProjectCodes。
// 收到 result 后更新页面和最近6轮 history;CHAT 不覆盖候选编码。
history.push({ role: 'user', content: message }, { role: 'assistant', content: result.reply });
history = history.slice(-12);
if (result.status !== 'CHAT') {
previousProjectCodes = result.projects.map(card => card.project.projectCode);
}
// CHAT 展示完整 reply,保留此前卡片及候选编码。
// MATCHED/NEEDS_SELECTION 展示候选;CREATED/FORKED 使用 result.project.projectCode 打开工作区。
// 捕获 ApiError 时读取 error.data?.projectCode(先做类型判断),用于核对初始化未完成的项目。
```