编辑器素材库 OpenAPI 增加服务端分页筛选与按 ID 读取，减少 AGC 全库拉取 #574

New Issue

2026-10-01T18:46:45+08:00

lhk229 commented

2026-10-01 18:46:45 +08:00

背景与优先级

从 #549 拆出的后端查询效率改进，优先级为 Low。#549 优先处理 AGC 客户端因账户素材总量超过 500 而拒绝查询、导入的功能阻断；本 issue 不作为 #549 修复或关闭的前置条件。

当前行为

GET /api/external/v1/editor/assets/library 返回当前账号的完整素材库快照，没有服务端 folderId/query/offset/limit 查询参数。AGC 获取全库后在内存中筛选、分页，只把当前页的安全元数据作为工具文本结果交给 Agent（单页最多 100 项），并非把全库保存为 JSON 附件再让 Agent 读取。

指定 assetId 导入也先读取全库再选取目标。因此，即使客户端解除 500 项拒绝门槛，单次小查询和指定 ID 导入的网络及处理开销仍随账户素材总量增长。

代码依据

只读核查基线：97617608ba9f40cb601cf4319a48e45c764def73。

后端素材库快照接口：读取账号素材库，未接收分页筛选参数。
AGC 全库请求：请求完整素材库并解析。
AGC 本地筛选分页。
权威公开契约：docs/openapi/genarrative-external-v1.openapi.json。

改进范围

为账户素材提供真正的服务端有界筛选/分页查询，以及按指定 ID（或有界 ID 批次）的读取能力，并让 AGC 相关调用接入。避免仅在服务端仍组装完整快照后截取一页，或客户端循环拉完所有页再本地筛选。

实现前明确稳定排序、名称/文件夹名称匹配、分页结果字段，以及现有账户素材与绑定项目画布资源合并查询的语义；保持既有公开调用方兼容，不擅自把快照响应改成含义不同的分页响应。

验收

账户超过 500 项时，按文件夹、关键词查询及连续翻页可用，后续页面不受固定 offset=500 门槛阻断。
查询单页或导入指定 ID 时，AGC 不再下载完整账户素材库；返回条数和响应大小有界，并核对后端数据读取及处理开销。
按 ID 读取仍校验当前账号归属、删除状态、权限和支持的媒体类型；Agent 只接收安全元数据，下载引用与凭据留在客户端。
保留单页/批次数量、下载大小和会话校验等有效边界。
同步 OpenAPI、DTO、工具 schema/说明及相关技术文档；补充定向分页、按 ID 读取和权限契约测试。

核查边界

本 issue 记录静态代码确认的接口能力与效率问题，尚无性能压测结论；未实施代码修改或远端付费操作。账户总量超过 500 即拒绝的客户端行为由 #549 单独修复。

## 背景与优先级从 #549 拆出的后端查询效率改进，优先级为 Low。#549 优先处理 AGC 客户端因账户素材总量超过 500 而拒绝查询、导入的功能阻断；本 issue 不作为 #549 修复或关闭的前置条件。 ## 当前行为 `GET /api/external/v1/editor/assets/library` 返回当前账号的完整素材库快照，没有服务端 folderId/query/offset/limit 查询参数。AGC 获取全库后在内存中筛选、分页，只把当前页的安全元数据作为工具文本结果交给 Agent（单页最多 100 项），并非把全库保存为 JSON 附件再让 Agent 读取。指定 assetId 导入也先读取全库再选取目标。因此，即使客户端解除 500 项拒绝门槛，单次小查询和指定 ID 导入的网络及处理开销仍随账户素材总量增长。 ## 代码依据只读核查基线：97617608ba9f40cb601cf4319a48e45c764def73。 - [后端素材库快照接口](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/97617608ba9f40cb601cf4319a48e45c764def73/server-rs/crates/api-server/src/external_editor_api.rs#L451)：读取账号素材库，未接收分页筛选参数。 - [AGC 全库请求](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/97617608ba9f40cb601cf4319a48e45c764def73/apps/ai-game-creator-shell/src-tauri/src/commands.rs#L2568)：请求完整素材库并解析。 - [AGC 本地筛选分页](https://git.genarrative.world/git/GenarrativeAI/Genarrative/src/commit/97617608ba9f40cb601cf4319a48e45c764def73/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs#L1508)。 - 权威公开契约：`docs/openapi/genarrative-external-v1.openapi.json`。 ## 改进范围为账户素材提供真正的服务端有界筛选/分页查询，以及按指定 ID（或有界 ID 批次）的读取能力，并让 AGC 相关调用接入。避免仅在服务端仍组装完整快照后截取一页，或客户端循环拉完所有页再本地筛选。实现前明确稳定排序、名称/文件夹名称匹配、分页结果字段，以及现有账户素材与绑定项目画布资源合并查询的语义；保持既有公开调用方兼容，不擅自把快照响应改成含义不同的分页响应。 ## 验收 - [ ] 账户超过 500 项时，按文件夹、关键词查询及连续翻页可用，后续页面不受固定 offset=500 门槛阻断。 - [ ] 查询单页或导入指定 ID 时，AGC 不再下载完整账户素材库；返回条数和响应大小有界，并核对后端数据读取及处理开销。 - [ ] 按 ID 读取仍校验当前账号归属、删除状态、权限和支持的媒体类型；Agent 只接收安全元数据，下载引用与凭据留在客户端。 - [ ] 保留单页/批次数量、下载大小和会话校验等有效边界。 - [ ] 同步 OpenAPI、DTO、工具 schema/说明及相关技术文档；补充定向分页、按 ID 读取和权限契约测试。 ## 核查边界本 issue 记录静态代码确认的接口能力与效率问题，尚无性能压测结论；未实施代码修改或远端付费操作。账户总量超过 500 即拒绝的客户端行为由 #549 单独修复。

lhk229 added the Kind/Enhancement

Priority

Low

4

labels 2026-10-01 18:46:45 +08:00

lhk229 referenced this issue

2026-10-01 18:47:11 +08:00

AGC 账户素材超过 500 项后，分页查询与指定素材导入均被全库上限阻断 #549

lhk229 referenced this issue

2026-10-01 19:17:03 +08:00

Fix Issue 549 #573

lhk229 referenced this issue