尧图网页设计 
Corsair 集成 CustomGPT用 40 个类型安全操作管理 AI Agent 的完整指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsaircorsair-dev/customgpt是 Corsair 官方的 CustomGPT 插件包把 CustomGPT.ai 的以自有业务内容训练的自定义 ChatGPT 式 Agent能力接入你的应用安装插件后即可通过corsair.customgpt.api.*调用 40 个类型安全操作覆盖 Agent项目生命周期、知识库文档、数据源、会话消息、报告分析和用户管理。读完本文你将掌握该插件的安装接入、API Key 认证机制、全部 40 个操作的分域用法、风险分级与权限控制以及它背后的 REST 映射、错误重试和本地缓存实现。插件是什么Corsair 与 CustomGPT 之间的连接层Corsair 是一个开源集成层为 AI Agent 与应用之间提供 OAuth、Token 刷新、Webhook、限流等能力并把每个连接的凭据加密存储在你自己的数据库中。customgpt插件是这个生态中面向 CustomGPT.ai 的接入包其定位在 packages/customgpt/README.md 中写得很直接CustomGPT plugin for Corsair。从源码结构看这个包是一份典型的 Corsair 插件实现packages/customgpt/index.tscustomgpt()工厂函数返回一个满足CorsairPlugin接口的插件对象声明了id: customgpt、认证配置、数据库 schema、端点树、端点元数据与错误处理器端点按域组织成嵌套结构projects / pages / sources / licenses / settings / personas / conversations / messages / reports / limits / user调用时通过corsair.customgpt.api.domain.action()访问每个端点都配有 zod 输入/输出契约customGPTEndpointSchemas和风险级别元数据customGPTEndpointMeta。在 package.json 中插件的peerDependencies声明为corsair 0.1.0与zod ^4.1.13这意味着你需要先安装 Corsair 核心 SDK 才能使用本插件。安装与接入三步把 CustomGPT 挂进你的应用第一步安装依赖pnpm add corsair corsair-dev/customgpt如果你的包管理器是 npm 或 yarn命令等价替换即可。插件本身以dist/index.js作为主入口类型声明一并随包发布见 package.json。第二步注册到 Corsair 实例参照 Corsair 的通用插件接入方式见 docs/guides/plugins.mdx在创建createCorsair时把customgpt()加入plugins数组import { createCorsair } from corsair; import { customgpt } from corsair-dev/customgpt; export const corsair createCorsair({ plugins: [ customgpt(), // ...其他插件 ], kek: process.env.CORSAIR_KEK!, // 信封加密用的密钥加密密钥 multiTenancy: false, // 单租户多租户场景设为 true });第三步配置 API Key认证方式为 API KeyREADME 原文Auth: API key. Corsair prompts your tenant for credentials on first use.。首次使用时Corsair 会提示你的租户提供凭据。密钥可以通过 Corsair 的通用配置流程提供——CLI、环境变量或应用内 setup 流程皆可见 docs/concepts/api-key.mdx。CLI 命令沿用 Corsair 的setup模式pnpm corsair setup --plugincustomgpt api_keyyour-customgpt-api-key在单租户solo模式下一个 API Key 被整个应用共享开启multiTenancy: true后每个租户持有各自的密钥Corsair 会为每个租户分别加密存储。底层认证逻辑keyBuilder 源码解读插件如何拿到 API Key答案在 packages/customgpt/index.ts 的keyBuilder回调中keyBuilder: async (ctx, source) { if (source endpoint options.key) { return options.key; // ① 构造时直接注入静态 key } if (source endpoint ctx.authType api_key) { const res await ctx.keys.get_api_key(); // ② 从加密存储中读取 if (!res) { throw new AuthMissingError(customgpt, api_key); } return res; } throw new AuthMissingError(customgpt, api_key); },也就是说优先使用构造选项里的key否则从 Corsair 的密钥存储中读取两者都缺失时抛出AuthMissingError提示租户先完成凭据配置。这正好印证了 README 中首次使用提示租户提供凭据的行为。40 个操作全景按域分组的使用指南README 完整列出了 40 个操作测试文件 packages/customgpt/api.test.ts 的用例注释也明确写着All 40 Operations。每个操作都有唯一的 Operation ID形如customgpt.api.domain.action和风险级别。下面按域分组完整展开。1. projectsAgent项目生命周期管理CustomGPT API 把 Agent 称为项目project这是全插件的核心域。OperationOperation IDRisk说明projects.listcustomgpt.api.projects.listread列出当前认证用户的所有 CustomGPT 项目Agent返回含 ID、名称、类型、聊天状态与时间戳的完整信息支持page分页。用于发现可用 Agent 或遍历全部项目projects.getcustomgpt.api.projects.getread获取单个 Agent 的完整配置与当前状态。用于检查处理进度、查看设置或读取元数据projects.createcustomgpt.api.projects.createwrite通过 sitemap URL 或文件上传创建新 Agent创建后立即开始处理内容以构建知识库。sitemap_path或file必须提供其一projects.updatecustomgpt.api.projects.updatewrite更新 Agent 的名称或配置不触碰知识库返回完整更新后的项目信息projects.deletecustomgpt.api.projects.deletedestructive按 ID 永久删除 Agent。[DESTRUCTIVE · IRREVERSIBLE]projects.clonecustomgpt.api.projects.clonewrite克隆 Agent完整复制其知识库、人设persona与设置。用于测试变体或模板化复用projects.statscustomgpt.api.projects.statsread获取 Agent 统计会话总数、查询次数、文档统计与处理信息。用于监控 Agent 表现或生成用量报告projects.pluginscustomgpt.api.projects.pluginsread读取特定 Agent 的插件配置、状态与元数据从 packages/customgpt/endpoints/projects.ts 可以看到这些操作的 REST 映射projects.list对应GET /projectsprojects.create对应POST /projectsmultipart 表单projects.clone对应POST /projects/{projectId}/replicateprojects.plugins对应GET /projects/{projectId}/actions。创建与更新操作会调用fileFormFields把 base64 文件解码为真正的File对象参与上传见 packages/customgpt/endpoints/shared.ts。2. pages知识库文档管理CustomGPT API 把知识库中的文档称为页面page。OperationOperation IDRisk说明pages.listcustomgpt.api.pages.listread列出 Agent 知识库中的所有文档含网页、PDF 与上传文件。支持按抓取/索引状态过滤和分页用于审计知识来源或验证文档入库pages.deletecustomgpt.api.pages.deletedestructive永久删除知识库中的文档删除后 Agent 不再引用该内容。警告不可撤销。[DESTRUCTIVE · IRREVERSIBLE]pages.reindexcustomgpt.api.pages.reindexwrite重新抓取并索引基于 URL 的文档以更新内容。仅对 URL 型文档生效适合源内容变更时使用pages.getMetadatacustomgpt.api.pages.getMetadataread获取文档元数据标题、来源 URL、字数、自定义元数据字段pages.updateMetadatacustomgpt.api.pages.updateMetadatawrite更新文档的自定义元数据字段标题、描述、URL、图片等用于给文档打标签、分类或补充组织信息3. sources数据源管理数据源是知识库的输入管道可以是 sitemap、文件上传或集成。OperationOperation IDRisk说明sources.listcustomgpt.api.sources.listread列出 Agent 连接的所有数据源sitemap、Google Drive 文件夹、SharePoint 站点或上传文件用于管理知识库内容来源sources.addcustomgpt.api.sources.addwrite通过 sitemap URL、文件上传或集成添加数据源创建后立即开始索引。适合接入文档、FAQ 或知识内容sources.updatecustomgpt.api.sources.updatewrite更新数据源索引与同步设置自动同步频率、抓取深度、文件过滤、刷新行为。可精细调优 sitemap 抓取JavaScript 执行、图片提取、控制同步增删页面、设置自定义刷新计划sources.deletecustomgpt.api.sources.deletedestructive删除数据源及其全部文档。[DESTRUCTIVE · IRREVERSIBLE]sources.update的能力在 schema/database.ts 的CustomGPTSourceSettings中有完整刻画data_refresh_frequency取值never / daily / weekly / monthly / advancedrefresh_existing_pages取值never / always / if_updated还包含executive_js是否执行 JS、create_new_pages、remove_unexist_pages、image_extraction_typenone / sync_from_sitemap等开关。4. licenses许可证管理许可证用于向最终用户分发 Agent 访问权。OperationOperation IDRisk说明licenses.listcustomgpt.api.licenses.listread列出项目全部许可证返回含 ID、类型、状态与时间戳的数组项目无许可证或未启用该功能时返回空数组licenses.getcustomgpt.api.licenses.getread按许可证 ID 获取单个许可证详情licenses.updatecustomgpt.api.licenses.updatewrite更新许可证名称。前置条件项目套餐需启用许可证、项目 ID 与许可证 ID 有效。本操作只改名称其余属性不可修改licenses.deletecustomgpt.api.licenses.deletedestructive删除许可证需要数字型项目 ID 与许可证 ID。操作是幂等的——即使许可证不存在404也视为成功项目套餐需启用许可证功能。[DESTRUCTIVE · IRREVERSIBLE]5. settingsAgent 配置OperationOperation IDRisk说明settings.getcustomgpt.api.settings.getread读取 Agent 配置聊天头像、背景、默认提示词、示例问题、回答来源、语言与品牌偏好。注意部分新建项目尚未初始化设置会返回 404settings.updatecustomgpt.api.settings.updatewrite更新 Agent 配置人设指令、回答格式、引用风格、品牌与部署设置。只传要改的字段未传字段保持原值6. personas人设版本管理OperationOperation IDRisk说明personas.listcustomgpt.api.personas.listread列出 Agent 的人设版本历史。每次人设更新都会自动保存快照结果分页。需要 Custom 套餐personas.activatecustomgpt.api.personas.activatewrite恢复历史人设版本为当前生效版本。回滚会在历史中新增一条版本记录不覆盖保留完整审计轨迹。需要 Custom 套餐7. conversations messages会话与消息conversations.create是会话入口消息操作全部挂在会话之下。OperationOperation IDRisk说明conversations.createcustomgpt.api.conversations.createwrite为 Agent 创建新会话返回 session ID 用于后续发送消息可传name便于识别messages.listcustomgpt.api.messages.listread读取会话全部消息用户提问与 AI 回答用于查看完整聊天历史会话不存在或无消息时返回空列表messages.getcustomgpt.api.messages.getread获取单条消息完整详情用户提示、Agent 回答、时间戳、引用citations与附加元数据messages.getTrustScorecustomgpt.api.messages.getTrustScoreread获取消息的验证信任分按回答主张被源文档支持的程度计算分数越高表示回答越有据可依messages.verifycustomgpt.api.messages.verifywrite触发事实核查流程逐条比对消息主张与源文档报告每条主张是支持、部分支持还是不支持的messages.submitFeedbackcustomgpt.api.messages.submitFeedbackwrite为消息提交点赞/点踩反馈记录用户满意度信号可重复提交新值来更改反馈从 packages/customgpt/endpoints/conversations.ts 可看到消息域的路由细节messages.getTrustScore对应GET /projects/{projectId}/conversations/{sessionId}/messages/{promptId}/trust-scoremessages.verify对应POST .../verifymessages.submitFeedback对应PUT .../feedback请求体为{ reaction }。每个消息端点都会把结果镜像写入messages缓存conversations.create的结果则按session_id写入conversations缓存。8. reports分析报告OperationOperation IDRisk说明reports.getAnalysiscustomgpt.api.reports.getAnalysisread获取图表时间序列数据支持按天/周聚合的会话数、查询数、每会话查询比等指标。用于生成使用报告、跟踪项目参与度、可视化聊天机器人趋势reports.getConversationscustomgpt.api.reports.getConversationsread获取会话分析总会话数、平均每会话查询数等参与度统计reports.getTrafficcustomgpt.api.reports.getTrafficread获取流量分析独立访客数、会话数、地理分布与设备类型reports.getIntelligencecustomgpt.api.reports.getIntelligenceread获取 AI 分析的用户洞察常见意图、情绪倾向、高频主题与新兴趋势reports.exportLeadscustomgpt.api.reports.exportLeadsread导出会话中捕获的线索邮箱、姓名、电话与自定义字段支持分页与日期范围过滤。用于同步 CRM 或营销工具schema/database.ts中的CustomGPTCustomerIntelligence类型揭示了getIntelligence返回的丰富字段除user_intent、user_emotion、language外还包含risk_fidelity、risk_jailbreak、risk_prompt_leakage、risk_profanity、accuracy等风险与准确性标注字段。9. limits user配额与账户OperationOperation IDRisk说明limits.getUsagecustomgpt.api.limits.getUsageread获取账户用量限额已用/上限对比项目数、存储额度即索引字符数、API 查询数。用于监控配额消耗user.getProfilecustomgpt.api.user.getProfileread获取当前用户资料用于登录后展示或校验认证用户信息user.updateProfilecustomgpt.api.user.updateProfilewrite更新当前用户资料显示名、邮箱、头像 URL。所有字段可选只更新传入字段user.searchTeamMemberscustomgpt.api.user.searchTeamMembersread按邮箱或用户 ID 搜索团队成员用于分配权限或管理团队访问。需要 Owner 或 Admin 角色风险分级与权限控制README 为每个操作标注了三种风险级别这在 Corsair 的权限体系中直接生效见 docs/concepts/permissions.mdx风险级别含义示例操作read只读安全放行projects.list、reports.getAnalysis、limits.getUsagewrite会写入或修改数据projects.create、messages.verify、sources.adddestructive不可逆的破坏性操作projects.delete、pages.delete、sources.delete、licenses.deleteCorsair 的permissions.mode把每个风险级别映射到策略readonly模式allow / deny / deny只放行读操作cautious模式allow / allow / require_approval允许读写、破坏性操作需人工审批standard模式allow / require_approval / deny连写操作也要审批。对 Agent 工作负载cautious是常用默认。还可以用overrides对单个端点收紧或放宽customgpt({ permissions: { mode: cautious, overrides: { projects.delete: deny, // 收紧禁止删除 Agent pages.delete: require_approval, // 收紧删文档需人工审批 }, }, });overrides的键是插件端点树的点号路径路径写错会在编译期报错——projects.delete、pages.delete、sources.delete、licenses.delete这些键正是来自 packages/customgpt/index.ts 中customGPTEndpointsNested的实际嵌套结构。底层实现REST 客户端、错误处理与本地缓存请求管线与统一错误类型所有端点共用makeCustomGPTRequestpackages/customgpt/client.tsbase URL 固定为 CustomGPT 官方 REST API路径前缀/api/v1已折叠进常量各端点模块只传裸资源路径如projects/1/pages认证采用 HTTP Bearer Token即账户的 API Key数组查询参数序列化为重复键filtersqueriesfiltersconversations与官方 OpenAPI 文档中style: form, explode: true的声明一致multipart 端点故意不设置 Content-Type让 fetch 依据 FormData 实例自动生成 boundary任何失败的调用都会包装成CustomGPTAPIError并携带上游 HTTPstatus、statusText、body与retryAfter供错误处理器决策无需重新解析错误字符串。错误处理与重试策略插件的默认错误处理器packages/customgpt/error-handlers.ts覆盖了完整的失败分类错误类别匹配依据重试策略RATE_LIMIT_ERRORHTTP 429 或消息含 rate limit / too many requests 等最多 3 次指数退避 抖动尊重Retry-AfterAUTH_ERRORHTTP 401 或消息含 unauthorized / token 等0 次重试PERMISSION_ERRORHTTP 403 或消息含 permission / forbidden0 次重试NOT_FOUND_ERRORHTTP 404 或消息含 not found0 次重试BAD_REQUEST_ERRORHTTP 400 或消息含 invalid0 次重试SERVER_ERRORHTTP 5xx 或消息含 server error最多 2 次指数退避DEFAULT兜底0 次重试所有重试策略都从CustomGPTAPIError携带的结构化字段判断而不是依赖字符串匹配。你也可以在构造插件时通过errorHandlers选项覆盖个别类别源码中会用你的实现替换对应类别DEFAULT兜底则保持二选一。本地实体缓存插件通过 zod schema 定义了一套持久化实体packages/customgpt/schema/index.tsexport const CustomGPTSchema { version: 1.0.0, entities: { projects: CustomGPTProject, pages: CustomGPTPage, sources: CustomGPTSource, conversations: CustomGPTConversation, messages: CustomGPTMessage, licenses: CustomGPTLicense, leads: CustomGPTLead, }, };每次 API 调用成功后返回数据会被镜像写入对应实体表ctx.db.entity.upsertByEntityId并附带syncedAt时间戳。缓存写入是尽力而为的——存储失败只会打印告警绝不会让一次成功的 API 调用失败见 endpoints/shared.ts 的cacheEntity。所有 schema 都用.loose()声明上游新增字段会被原样保留而不是被丢弃同时所有非标识字段均为可选以适应官方规范未标注任何响应属性为必填的情况。数据建模与 CustomGPT 官方术语一致API 称 Agent 为项目project、文档为页面page实体命名跟随 API 而非 UI。测试验证40 个操作的全部请求映射插件附带完整的 Jest 测试packages/customgpt/api.test.ts测试名即CustomGPT Endpoint Handlers — All 40 Operations Request Mapping。测试用 spy 拦截corsair/http的request函数逐一对 40 个操作断言三件事URL 与方法例如projects.list应发出GET /projects查询参数原样透传{ page: 2, order: asc }缓存写入响应中的实体应按正确主键写入 mock 数据库如项目按String(id)upsert事件记录每个操作成功后都会通过logEventFromContext记录形如customgpt.projects.list的完成事件。该测试同时印证了认证注入请求配置中的BASE指向 CustomGPT API 根地址TOKEN为传入的 API Key。关于 Webhooks 与许可证README 明确说明本插件无 WebhooksNo webhooks。源码也验证了这一点customGPTWebhooksNested {} as const插件对象中webhooks与pluginWebhookMatcher均为空/未定义。因此需要实时接收 CustomGPT 事件的应用无法依赖本插件内置 webhook应通过主动轮询如projects.stats、reports.*、pages.list来获取状态变化。插件以Apache-2.0协议开源见 package.json 的license字段。完整的包说明、端点参考与类型导出以 packages/customgpt/README.md 和 packages/customgpt/index.ts 的导出声明含全部CustomGPTEndpointInputs/Outputs与各响应类型为准。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Corsair 集成 CustomGPT：用 40 个类型安全操作管理 AI Agent 的完整指南
Corsair 集成 CustomGPT用 40 个类型安全操作管理 AI Agent 的完整指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsaircorsair-dev/customgpt是 Corsair 官方的 CustomGPT 插件包把 CustomGPT.ai 的以自有业务内容训练的自定义 ChatGPT 式 Agent能力接入你的应用安装插件后即可通过corsair.customgpt.api.*调用 40 个类型安全操作覆盖 Agent项目生命周期、知识库文档、数据源、会话消息、报告分析和用户管理。读完本文你将掌握该插件的安装接入、API Key 认证机制、全部 40 个操作的分域用法、风险分级与权限控制以及它背后的 REST 映射、错误重试和本地缓存实现。插件是什么Corsair 与 CustomGPT 之间的连接层Corsair 是一个开源集成层为 AI Agent 与应用之间提供 OAuth、Token 刷新、Webhook、限流等能力并把每个连接的凭据加密存储在你自己的数据库中。customgpt插件是这个生态中面向 CustomGPT.ai 的接入包其定位在 packages/customgpt/README.md 中写得很直接CustomGPT plugin for Corsair。从源码结构看这个包是一份典型的 Corsair 插件实现packages/customgpt/index.tscustomgpt()工厂函数返回一个满足CorsairPlugin接口的插件对象声明了id: customgpt、认证配置、数据库 schema、端点树、端点元数据与错误处理器端点按域组织成嵌套结构projects / pages / sources / licenses / settings / personas / conversations / messages / reports / limits / user调用时通过corsair.customgpt.api.domain.action()访问每个端点都配有 zod 输入/输出契约customGPTEndpointSchemas和风险级别元数据customGPTEndpointMeta。在 package.json 中插件的peerDependencies声明为corsair 0.1.0与zod ^4.1.13这意味着你需要先安装 Corsair 核心 SDK 才能使用本插件。安装与接入三步把 CustomGPT 挂进你的应用第一步安装依赖pnpm add corsair corsair-dev/customgpt如果你的包管理器是 npm 或 yarn命令等价替换即可。插件本身以dist/index.js作为主入口类型声明一并随包发布见 package.json。第二步注册到 Corsair 实例参照 Corsair 的通用插件接入方式见 docs/guides/plugins.mdx在创建createCorsair时把customgpt()加入plugins数组import { createCorsair } from corsair; import { customgpt } from corsair-dev/customgpt; export const corsair createCorsair({ plugins: [ customgpt(), // ...其他插件 ], kek: process.env.CORSAIR_KEK!, // 信封加密用的密钥加密密钥 multiTenancy: false, // 单租户多租户场景设为 true });第三步配置 API Key认证方式为 API KeyREADME 原文Auth: API key. Corsair prompts your tenant for credentials on first use.。首次使用时Corsair 会提示你的租户提供凭据。密钥可以通过 Corsair 的通用配置流程提供——CLI、环境变量或应用内 setup 流程皆可见 docs/concepts/api-key.mdx。CLI 命令沿用 Corsair 的setup模式pnpm corsair setup --plugincustomgpt api_keyyour-customgpt-api-key在单租户solo模式下一个 API Key 被整个应用共享开启multiTenancy: true后每个租户持有各自的密钥Corsair 会为每个租户分别加密存储。底层认证逻辑keyBuilder 源码解读插件如何拿到 API Key答案在 packages/customgpt/index.ts 的keyBuilder回调中keyBuilder: async (ctx, source) { if (source endpoint options.key) { return options.key; // ① 构造时直接注入静态 key } if (source endpoint ctx.authType api_key) { const res await ctx.keys.get_api_key(); // ② 从加密存储中读取 if (!res) { throw new AuthMissingError(customgpt, api_key); } return res; } throw new AuthMissingError(customgpt, api_key); },也就是说优先使用构造选项里的key否则从 Corsair 的密钥存储中读取两者都缺失时抛出AuthMissingError提示租户先完成凭据配置。这正好印证了 README 中首次使用提示租户提供凭据的行为。40 个操作全景按域分组的使用指南README 完整列出了 40 个操作测试文件 packages/customgpt/api.test.ts 的用例注释也明确写着All 40 Operations。每个操作都有唯一的 Operation ID形如customgpt.api.domain.action和风险级别。下面按域分组完整展开。1. projectsAgent项目生命周期管理CustomGPT API 把 Agent 称为项目project这是全插件的核心域。OperationOperation IDRisk说明projects.listcustomgpt.api.projects.listread列出当前认证用户的所有 CustomGPT 项目Agent返回含 ID、名称、类型、聊天状态与时间戳的完整信息支持page分页。用于发现可用 Agent 或遍历全部项目projects.getcustomgpt.api.projects.getread获取单个 Agent 的完整配置与当前状态。用于检查处理进度、查看设置或读取元数据projects.createcustomgpt.api.projects.createwrite通过 sitemap URL 或文件上传创建新 Agent创建后立即开始处理内容以构建知识库。sitemap_path或file必须提供其一projects.updatecustomgpt.api.projects.updatewrite更新 Agent 的名称或配置不触碰知识库返回完整更新后的项目信息projects.deletecustomgpt.api.projects.deletedestructive按 ID 永久删除 Agent。[DESTRUCTIVE · IRREVERSIBLE]projects.clonecustomgpt.api.projects.clonewrite克隆 Agent完整复制其知识库、人设persona与设置。用于测试变体或模板化复用projects.statscustomgpt.api.projects.statsread获取 Agent 统计会话总数、查询次数、文档统计与处理信息。用于监控 Agent 表现或生成用量报告projects.pluginscustomgpt.api.projects.pluginsread读取特定 Agent 的插件配置、状态与元数据从 packages/customgpt/endpoints/projects.ts 可以看到这些操作的 REST 映射projects.list对应GET /projectsprojects.create对应POST /projectsmultipart 表单projects.clone对应POST /projects/{projectId}/replicateprojects.plugins对应GET /projects/{projectId}/actions。创建与更新操作会调用fileFormFields把 base64 文件解码为真正的File对象参与上传见 packages/customgpt/endpoints/shared.ts。2. pages知识库文档管理CustomGPT API 把知识库中的文档称为页面page。OperationOperation IDRisk说明pages.listcustomgpt.api.pages.listread列出 Agent 知识库中的所有文档含网页、PDF 与上传文件。支持按抓取/索引状态过滤和分页用于审计知识来源或验证文档入库pages.deletecustomgpt.api.pages.deletedestructive永久删除知识库中的文档删除后 Agent 不再引用该内容。警告不可撤销。[DESTRUCTIVE · IRREVERSIBLE]pages.reindexcustomgpt.api.pages.reindexwrite重新抓取并索引基于 URL 的文档以更新内容。仅对 URL 型文档生效适合源内容变更时使用pages.getMetadatacustomgpt.api.pages.getMetadataread获取文档元数据标题、来源 URL、字数、自定义元数据字段pages.updateMetadatacustomgpt.api.pages.updateMetadatawrite更新文档的自定义元数据字段标题、描述、URL、图片等用于给文档打标签、分类或补充组织信息3. sources数据源管理数据源是知识库的输入管道可以是 sitemap、文件上传或集成。OperationOperation IDRisk说明sources.listcustomgpt.api.sources.listread列出 Agent 连接的所有数据源sitemap、Google Drive 文件夹、SharePoint 站点或上传文件用于管理知识库内容来源sources.addcustomgpt.api.sources.addwrite通过 sitemap URL、文件上传或集成添加数据源创建后立即开始索引。适合接入文档、FAQ 或知识内容sources.updatecustomgpt.api.sources.updatewrite更新数据源索引与同步设置自动同步频率、抓取深度、文件过滤、刷新行为。可精细调优 sitemap 抓取JavaScript 执行、图片提取、控制同步增删页面、设置自定义刷新计划sources.deletecustomgpt.api.sources.deletedestructive删除数据源及其全部文档。[DESTRUCTIVE · IRREVERSIBLE]sources.update的能力在 schema/database.ts 的CustomGPTSourceSettings中有完整刻画data_refresh_frequency取值never / daily / weekly / monthly / advancedrefresh_existing_pages取值never / always / if_updated还包含executive_js是否执行 JS、create_new_pages、remove_unexist_pages、image_extraction_typenone / sync_from_sitemap等开关。4. licenses许可证管理许可证用于向最终用户分发 Agent 访问权。OperationOperation IDRisk说明licenses.listcustomgpt.api.licenses.listread列出项目全部许可证返回含 ID、类型、状态与时间戳的数组项目无许可证或未启用该功能时返回空数组licenses.getcustomgpt.api.licenses.getread按许可证 ID 获取单个许可证详情licenses.updatecustomgpt.api.licenses.updatewrite更新许可证名称。前置条件项目套餐需启用许可证、项目 ID 与许可证 ID 有效。本操作只改名称其余属性不可修改licenses.deletecustomgpt.api.licenses.deletedestructive删除许可证需要数字型项目 ID 与许可证 ID。操作是幂等的——即使许可证不存在404也视为成功项目套餐需启用许可证功能。[DESTRUCTIVE · IRREVERSIBLE]5. settingsAgent 配置OperationOperation IDRisk说明settings.getcustomgpt.api.settings.getread读取 Agent 配置聊天头像、背景、默认提示词、示例问题、回答来源、语言与品牌偏好。注意部分新建项目尚未初始化设置会返回 404settings.updatecustomgpt.api.settings.updatewrite更新 Agent 配置人设指令、回答格式、引用风格、品牌与部署设置。只传要改的字段未传字段保持原值6. personas人设版本管理OperationOperation IDRisk说明personas.listcustomgpt.api.personas.listread列出 Agent 的人设版本历史。每次人设更新都会自动保存快照结果分页。需要 Custom 套餐personas.activatecustomgpt.api.personas.activatewrite恢复历史人设版本为当前生效版本。回滚会在历史中新增一条版本记录不覆盖保留完整审计轨迹。需要 Custom 套餐7. conversations messages会话与消息conversations.create是会话入口消息操作全部挂在会话之下。OperationOperation IDRisk说明conversations.createcustomgpt.api.conversations.createwrite为 Agent 创建新会话返回 session ID 用于后续发送消息可传name便于识别messages.listcustomgpt.api.messages.listread读取会话全部消息用户提问与 AI 回答用于查看完整聊天历史会话不存在或无消息时返回空列表messages.getcustomgpt.api.messages.getread获取单条消息完整详情用户提示、Agent 回答、时间戳、引用citations与附加元数据messages.getTrustScorecustomgpt.api.messages.getTrustScoreread获取消息的验证信任分按回答主张被源文档支持的程度计算分数越高表示回答越有据可依messages.verifycustomgpt.api.messages.verifywrite触发事实核查流程逐条比对消息主张与源文档报告每条主张是支持、部分支持还是不支持的messages.submitFeedbackcustomgpt.api.messages.submitFeedbackwrite为消息提交点赞/点踩反馈记录用户满意度信号可重复提交新值来更改反馈从 packages/customgpt/endpoints/conversations.ts 可看到消息域的路由细节messages.getTrustScore对应GET /projects/{projectId}/conversations/{sessionId}/messages/{promptId}/trust-scoremessages.verify对应POST .../verifymessages.submitFeedback对应PUT .../feedback请求体为{ reaction }。每个消息端点都会把结果镜像写入messages缓存conversations.create的结果则按session_id写入conversations缓存。8. reports分析报告OperationOperation IDRisk说明reports.getAnalysiscustomgpt.api.reports.getAnalysisread获取图表时间序列数据支持按天/周聚合的会话数、查询数、每会话查询比等指标。用于生成使用报告、跟踪项目参与度、可视化聊天机器人趋势reports.getConversationscustomgpt.api.reports.getConversationsread获取会话分析总会话数、平均每会话查询数等参与度统计reports.getTrafficcustomgpt.api.reports.getTrafficread获取流量分析独立访客数、会话数、地理分布与设备类型reports.getIntelligencecustomgpt.api.reports.getIntelligenceread获取 AI 分析的用户洞察常见意图、情绪倾向、高频主题与新兴趋势reports.exportLeadscustomgpt.api.reports.exportLeadsread导出会话中捕获的线索邮箱、姓名、电话与自定义字段支持分页与日期范围过滤。用于同步 CRM 或营销工具schema/database.ts中的CustomGPTCustomerIntelligence类型揭示了getIntelligence返回的丰富字段除user_intent、user_emotion、language外还包含risk_fidelity、risk_jailbreak、risk_prompt_leakage、risk_profanity、accuracy等风险与准确性标注字段。9. limits user配额与账户OperationOperation IDRisk说明limits.getUsagecustomgpt.api.limits.getUsageread获取账户用量限额已用/上限对比项目数、存储额度即索引字符数、API 查询数。用于监控配额消耗user.getProfilecustomgpt.api.user.getProfileread获取当前用户资料用于登录后展示或校验认证用户信息user.updateProfilecustomgpt.api.user.updateProfilewrite更新当前用户资料显示名、邮箱、头像 URL。所有字段可选只更新传入字段user.searchTeamMemberscustomgpt.api.user.searchTeamMembersread按邮箱或用户 ID 搜索团队成员用于分配权限或管理团队访问。需要 Owner 或 Admin 角色风险分级与权限控制README 为每个操作标注了三种风险级别这在 Corsair 的权限体系中直接生效见 docs/concepts/permissions.mdx风险级别含义示例操作read只读安全放行projects.list、reports.getAnalysis、limits.getUsagewrite会写入或修改数据projects.create、messages.verify、sources.adddestructive不可逆的破坏性操作projects.delete、pages.delete、sources.delete、licenses.deleteCorsair 的permissions.mode把每个风险级别映射到策略readonly模式allow / deny / deny只放行读操作cautious模式allow / allow / require_approval允许读写、破坏性操作需人工审批standard模式allow / require_approval / deny连写操作也要审批。对 Agent 工作负载cautious是常用默认。还可以用overrides对单个端点收紧或放宽customgpt({ permissions: { mode: cautious, overrides: { projects.delete: deny, // 收紧禁止删除 Agent pages.delete: require_approval, // 收紧删文档需人工审批 }, }, });overrides的键是插件端点树的点号路径路径写错会在编译期报错——projects.delete、pages.delete、sources.delete、licenses.delete这些键正是来自 packages/customgpt/index.ts 中customGPTEndpointsNested的实际嵌套结构。底层实现REST 客户端、错误处理与本地缓存请求管线与统一错误类型所有端点共用makeCustomGPTRequestpackages/customgpt/client.tsbase URL 固定为 CustomGPT 官方 REST API路径前缀/api/v1已折叠进常量各端点模块只传裸资源路径如projects/1/pages认证采用 HTTP Bearer Token即账户的 API Key数组查询参数序列化为重复键filtersqueriesfiltersconversations与官方 OpenAPI 文档中style: form, explode: true的声明一致multipart 端点故意不设置 Content-Type让 fetch 依据 FormData 实例自动生成 boundary任何失败的调用都会包装成CustomGPTAPIError并携带上游 HTTPstatus、statusText、body与retryAfter供错误处理器决策无需重新解析错误字符串。错误处理与重试策略插件的默认错误处理器packages/customgpt/error-handlers.ts覆盖了完整的失败分类错误类别匹配依据重试策略RATE_LIMIT_ERRORHTTP 429 或消息含 rate limit / too many requests 等最多 3 次指数退避 抖动尊重Retry-AfterAUTH_ERRORHTTP 401 或消息含 unauthorized / token 等0 次重试PERMISSION_ERRORHTTP 403 或消息含 permission / forbidden0 次重试NOT_FOUND_ERRORHTTP 404 或消息含 not found0 次重试BAD_REQUEST_ERRORHTTP 400 或消息含 invalid0 次重试SERVER_ERRORHTTP 5xx 或消息含 server error最多 2 次指数退避DEFAULT兜底0 次重试所有重试策略都从CustomGPTAPIError携带的结构化字段判断而不是依赖字符串匹配。你也可以在构造插件时通过errorHandlers选项覆盖个别类别源码中会用你的实现替换对应类别DEFAULT兜底则保持二选一。本地实体缓存插件通过 zod schema 定义了一套持久化实体packages/customgpt/schema/index.tsexport const CustomGPTSchema { version: 1.0.0, entities: { projects: CustomGPTProject, pages: CustomGPTPage, sources: CustomGPTSource, conversations: CustomGPTConversation, messages: CustomGPTMessage, licenses: CustomGPTLicense, leads: CustomGPTLead, }, };每次 API 调用成功后返回数据会被镜像写入对应实体表ctx.db.entity.upsertByEntityId并附带syncedAt时间戳。缓存写入是尽力而为的——存储失败只会打印告警绝不会让一次成功的 API 调用失败见 endpoints/shared.ts 的cacheEntity。所有 schema 都用.loose()声明上游新增字段会被原样保留而不是被丢弃同时所有非标识字段均为可选以适应官方规范未标注任何响应属性为必填的情况。数据建模与 CustomGPT 官方术语一致API 称 Agent 为项目project、文档为页面page实体命名跟随 API 而非 UI。测试验证40 个操作的全部请求映射插件附带完整的 Jest 测试packages/customgpt/api.test.ts测试名即CustomGPT Endpoint Handlers — All 40 Operations Request Mapping。测试用 spy 拦截corsair/http的request函数逐一对 40 个操作断言三件事URL 与方法例如projects.list应发出GET /projects查询参数原样透传{ page: 2, order: asc }缓存写入响应中的实体应按正确主键写入 mock 数据库如项目按String(id)upsert事件记录每个操作成功后都会通过logEventFromContext记录形如customgpt.projects.list的完成事件。该测试同时印证了认证注入请求配置中的BASE指向 CustomGPT API 根地址TOKEN为传入的 API Key。关于 Webhooks 与许可证README 明确说明本插件无 WebhooksNo webhooks。源码也验证了这一点customGPTWebhooksNested {} as const插件对象中webhooks与pluginWebhookMatcher均为空/未定义。因此需要实时接收 CustomGPT 事件的应用无法依赖本插件内置 webhook应通过主动轮询如projects.stats、reports.*、pages.list来获取状态变化。插件以Apache-2.0协议开源见 package.json 的license字段。完整的包说明、端点参考与类型导出以 packages/customgpt/README.md 和 packages/customgpt/index.ts 的导出声明含全部CustomGPTEndpointInputs/Outputs与各响应类型为准。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考