feat: paragraph api and readme

ui/README.md

@@ -4,7 +4,7 @@ MaxKB 企业级 AI 智能体平台的前端工程，使用 Vue 3.5、TypeScript
 Tailwind CSS 4、Pinia 3 和 Vue Router 5，工作流画布基于 LogicFlow。
 
 项目采用 Admin 和 Chat 双入口。Admin 包含登录、工作空间资源、系统管理和工作流编辑等功能；
-Chat 已配置独立入口与路由，当前 `ChatView.vue` 仍为空白占位页，`src/api/chat/` 的独立请求体系尚未实现。
+Chat 包含单应用与门户认证、智能体列表及正式对话，使用独立的 Router、Pinia 和请求客户端。
 
 ## 本地开发
 
@@ -65,35 +65,7 @@ ESLint 检查的依据。需要检查代码时，可运行 `npx eslint <待检
 静态资源使用相对路径（`base: './'`）；部署时仍需为 History 路由配置对应入口回退，
 并由部署服务转发 API 和文件请求。Vite 的开发代理不会随静态构建产物部署。
 
-## 代码目录
-
-| 目录或文件                      | 职责                                                 |
-| ------------------------------- | ---------------------------------------------------- |
-| `src/main.ts` / `src/chat.ts`   | Admin / Chat 启动入口                                |
-| `src/api/`                      | 请求基础设施、业务 API、后端枚举与共享类型           |
-| `src/components/`               | 全局 Mk 组件、跨页面业务组件及其他共享组件           |
-| `src/layout/`                   | 应用头部、侧栏与资源详情布局                         |
-| `src/views/`                    | 登录、工作空间、系统管理、资源详情和工作流等路由页面 |
-| `src/workflow-canvas/`          | 画布内核、节点配置、节点实现、执行详情与资源查询缓存 |
-| `src/router/`                   | Admin / Chat 独立路由                                |
-| `src/permission/`               | 权限策略、分业务权限方法与 Admin `$perm` 插件        |
-| `src/stores/`                   | 共享 Pinia 实例及认证、用户、主题状态                |
-| `src/styles/`                   | 主题变量、Tailwind、Element Plus 集成与全局样式      |
-| `src/constants/` / `src/utils/` | 跨功能常量与工具函数                                 |
-| `src/assets/` / `public/`       | 源码导入资源 / 保留原始路径的静态资源                |
-
-## 开发约定与文档
-
-修改前先阅读 [AGENTS.md](AGENTS.md)，再阅读涉及领域的规则文档：
-
-- [样式](src/styles/STYLE_README.md)
-- [组件](src/components/COMPONENT_README.md)
-- [路由](src/router/ROUTE_README.md)
-- [API](src/api/API_README.md)
-- [页面](src/views/VIEW_README.md)
-- [工作流画布](src/workflow-canvas/WORKFLOW_README.md)
-- [常量](src/constants/CONSTANT_README.md)
-- [工具函数](src/utils/UTILS_README.md)
-
-详细规则由各领域 README 维护；目录、公共接口或使用约定变化时同步对应文档。
-`src/components.d.ts` 由组件自动注册插件生成，不手动编辑。
+## 开发规则
+
+目录职责、开发约束和专题文档索引统一见 [AGENTS.md](AGENTS.md)。
+修改代码前读取对应专题，文档只维护当前实现和使用规则。

ui/src/api/admin/system/resource-management/knowledge/paragraph.ts

@@ -0,0 +1,86 @@
+import { del, get, post, put } from '@/api/admin/core/request'
+import type { ParamsPage, ResponsePage } from '@/api/admin/core/types'
+import type {
+  ParagraphCreatePayload,
+  ParagraphDetail,
+  ParagraphEditPayload,
+  ParagraphGeneratePayload,
+  ParagraphItem,
+  ParagraphProblem,
+  ParagraphQuery,
+} from '@/api/types'
+
+const getPrefix = (knowledgeId: string, documentId: string) => `/system/resource/knowledge/${knowledgeId}/document/${documentId}/paragraph`
+
+/** 分页查询文档分段，供详情页滚动加载。 */
+const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
+  get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
+
+/** 在指定位置新增分段，默认首位，由服务端触发索引。 */
+const postParagraph = (knowledgeId: string, documentId: string, payload: ParagraphCreatePayload) =>
+  post<ParagraphCreatePayload, ParagraphDetail>(getPrefix(knowledgeId, documentId), payload)
+
+/** 查询分段正文、召回统计及关联问题。 */
+const getParagraphDetail = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 更新分段正文或启用状态，返回最新详情。 */
+const putParagraph = (knowledgeId: string, documentId: string, paragraphId: string, payload: ParagraphEditPayload) =>
+  put<ParagraphEditPayload, ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`, payload)
+
+/** 新增问题并关联到当前分段。 */
+const postParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, content: string) =>
+  post<{ content: string }, ParagraphProblem>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`, { content })
+
+/** 获取当前分段关联的全部问题。 */
+const getParagraphProblems = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphProblem[]>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`)
+
+/** 将知识库中的已有问题关联到当前分段。 */
+const putAssociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/association`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 解除当前分段的问题关联，保留问题及其他分段的关联。 */
+const putUnassociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/unassociation`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 将所选分段迁移至目标知识库的文档。 */
+const putMigrateParagraphs = (knowledgeId: string, documentId: string, targetKnowledgeId: string, targetDocumentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/migrate/knowledge/${targetKnowledgeId}/document/${targetDocumentId}`, {
+    id_list: paragraphIds,
+  })
+
+/** 为所选分段生成问题。 */
+const putGenerateParagraphQuestions = (knowledgeId: string, documentId: string, payload: ParagraphGeneratePayload) =>
+  put<ParagraphGeneratePayload, void>(`${getPrefix(knowledgeId, documentId)}/batch_generate_related`, payload)
+
+/** 批量删除当前文档中所选的分段。 */
+const putBatchDeleteParagraphs = (knowledgeId: string, documentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/batch_delete`, { id_list: paragraphIds })
+
+/** 删除当前文档的单个分段及其关联数据。 */
+const deleteParagraph = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  del<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 调整分段顺序，由服务端同步更新受影响的分段位置。 */
+const putParagraphPosition = (knowledgeId: string, documentId: string, paragraphId: string, position: number) =>
+  put<undefined, void>(`${getPrefix(knowledgeId, documentId)}/adjust_position`, undefined, {
+    paragraph_id: paragraphId,
+    new_position: position,
+  })
+
+export default {
+  getParagraphPage,
+  postParagraph,
+  getParagraphDetail,
+  putParagraph,
+  postParagraphProblem,
+  getParagraphProblems,
+  putAssociateParagraphProblem,
+  putUnassociateParagraphProblem,
+  putMigrateParagraphs,
+  putGenerateParagraphQuestions,
+  putBatchDeleteParagraphs,
+  deleteParagraph,
+  putParagraphPosition,
+}

ui/src/api/admin/system/shared-resources/knowledge/paragraph.ts

@@ -0,0 +1,86 @@
+import { del, get, post, put } from '@/api/admin/core/request'
+import type { ParamsPage, ResponsePage } from '@/api/admin/core/types'
+import type {
+  ParagraphCreatePayload,
+  ParagraphDetail,
+  ParagraphEditPayload,
+  ParagraphGeneratePayload,
+  ParagraphItem,
+  ParagraphProblem,
+  ParagraphQuery,
+} from '@/api/types'
+
+const getPrefix = (knowledgeId: string, documentId: string) => `/system/shared/knowledge/${knowledgeId}/document/${documentId}/paragraph`
+
+/** 分页查询文档分段，供详情页滚动加载。 */
+const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
+  get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
+
+/** 在指定位置新增分段，默认首位，由服务端触发索引。 */
+const postParagraph = (knowledgeId: string, documentId: string, payload: ParagraphCreatePayload) =>
+  post<ParagraphCreatePayload, ParagraphDetail>(getPrefix(knowledgeId, documentId), payload)
+
+/** 查询分段正文、召回统计及关联问题。 */
+const getParagraphDetail = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 更新分段正文或启用状态，返回最新详情。 */
+const putParagraph = (knowledgeId: string, documentId: string, paragraphId: string, payload: ParagraphEditPayload) =>
+  put<ParagraphEditPayload, ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`, payload)
+
+/** 新增问题并关联到当前分段。 */
+const postParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, content: string) =>
+  post<{ content: string }, ParagraphProblem>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`, { content })
+
+/** 获取当前分段关联的全部问题。 */
+const getParagraphProblems = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphProblem[]>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}/problem`)
+
+/** 将知识库中的已有问题关联到当前分段。 */
+const putAssociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/association`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 解除当前分段的问题关联，保留问题及其他分段的关联。 */
+const putUnassociateParagraphProblem = (knowledgeId: string, documentId: string, paragraphId: string, problemId: string) =>
+  put<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/unassociation`, undefined, { paragraph_id: paragraphId, problem_id: problemId })
+
+/** 将所选分段迁移至目标知识库的文档。 */
+const putMigrateParagraphs = (knowledgeId: string, documentId: string, targetKnowledgeId: string, targetDocumentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/migrate/knowledge/${targetKnowledgeId}/document/${targetDocumentId}`, {
+    id_list: paragraphIds,
+  })
+
+/** 为所选分段生成问题。 */
+const putGenerateParagraphQuestions = (knowledgeId: string, documentId: string, payload: ParagraphGeneratePayload) =>
+  put<ParagraphGeneratePayload, void>(`${getPrefix(knowledgeId, documentId)}/batch_generate_related`, payload)
+
+/** 批量删除当前文档中所选的分段。 */
+const putBatchDeleteParagraphs = (knowledgeId: string, documentId: string, paragraphIds: string[]) =>
+  put<{ id_list: string[] }, boolean>(`${getPrefix(knowledgeId, documentId)}/batch_delete`, { id_list: paragraphIds })
+
+/** 删除当前文档的单个分段及其关联数据。 */
+const deleteParagraph = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  del<undefined, boolean>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+/** 调整分段顺序，由服务端同步更新受影响的分段位置。 */
+const putParagraphPosition = (knowledgeId: string, documentId: string, paragraphId: string, position: number) =>
+  put<undefined, void>(`${getPrefix(knowledgeId, documentId)}/adjust_position`, undefined, {
+    paragraph_id: paragraphId,
+    new_position: position,
+  })
+
+export default {
+  getParagraphPage,
+  postParagraph,
+  getParagraphDetail,
+  putParagraph,
+  postParagraphProblem,
+  getParagraphProblems,
+  putAssociateParagraphProblem,
+  putUnassociateParagraphProblem,
+  putMigrateParagraphs,
+  putGenerateParagraphQuestions,
+  putBatchDeleteParagraphs,
+  deleteParagraph,
+  putParagraphPosition,
+}

ui/src/api/admin/workspace/knowledge/paragraph.ts

@@ -14,10 +14,6 @@ import { getWorkspaceId } from '@/utils/resource-context'
 const getPrefix = (knowledgeId: string, documentId: string) =>
   `/workspace/${getWorkspaceId()}/knowledge/${knowledgeId}/document/${documentId}/paragraph`
 
-/** 查询文档的全部分段，按位置排序，支持标题和内容筛选。 */
-const getParagraphList = (knowledgeId: string, documentId: string, query?: ParagraphQuery) =>
-  get<ParagraphItem[]>(getPrefix(knowledgeId, documentId), { ...query })
-
 /** 分页查询文档分段，供详情页滚动加载。 */
 const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
   get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
@@ -76,7 +72,6 @@ const putParagraphPosition = (knowledgeId: string, documentId: string, paragraph
   })
 
 export default {
-  getParagraphList,
   getParagraphPage,
   postParagraph,
   getParagraphDetail,

ui/src/api/admin/workspace/shared/knowledge/paragraph.ts

@@ -0,0 +1,17 @@
+import { get } from '../../../core/request'
+import type { ParamsPage, ResponsePage } from '../../../core/types'
+import type { ParagraphDetail, ParagraphItem, ParagraphQuery } from '@/api/types'
+import { getWorkspaceId } from '@/utils/resource-context'
+
+const getPrefix = (knowledgeId: string, documentId: string) =>
+  `/system/shared/workspace/${getWorkspaceId()}/knowledge/${knowledgeId}/document/${documentId}/paragraph`
+
+/** 分页查询共享知识库文档分段。 */
+const getParagraphPage = (knowledgeId: string, documentId: string, page: ParamsPage, query?: ParagraphQuery) =>
+  get<ResponsePage<ParagraphItem>>(`${getPrefix(knowledgeId, documentId)}/${page.currentPage}/${page.pageSize}`, { ...query })
+
+/** 查询共享知识库分段正文、召回统计及关联问题。 */
+const getParagraphDetail = (knowledgeId: string, documentId: string, paragraphId: string) =>
+  get<ParagraphDetail>(`${getPrefix(knowledgeId, documentId)}/${paragraphId}`)
+
+export default { getParagraphPage, getParagraphDetail }