{"owner":"labring","repo":"FastGPT","hasSkills":true,"totalSkillsCount":4,"totalTokensCount":3812,"categories":["root-instruction","mcp-config","marketplace","plugin-manifest"],"hasMcp":true,"mcpConfig":{"mcpServers":{"FastGPT":{"command":"npx","args":["-y","@modelcontextprotocol/server-FastGPT"]}}},"found":["AGENTS.md",".cursor/mcp.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json"],"skills":{"AGENTS.md":"# AGENTS.md\n\n本文件为 Agent 在本仓库中工作时提供指导说明。\n\n## 项目概述\n\nFastGPT 是一个 AI Agent 构建平台,提供开箱即用的数据处理、模型调用能力和可视化工作流编排。这是一个基于 NextJS 构建的全栈 TypeScript 应用,后端使用 MongoDB/PostgreSQL。\n\n**技术栈**: NextJS + TypeScript + ChakraUI + MongoDB + VectorDB(PG, Milvus, Zilliz, OceanBase, SeekDB, OpenGauss......)\n\n## 设计文档\n\n你可以参考 [项目设计文档](./.agents/design/) 来了解 FastGPT 已有的设计方案。\n\n## 架构\n\n这是一个使用 pnpm workspaces 的 monorepo,主要结构如下:\n\n### Packages (库代码)\n- `packages/global/` - 所有项目共享的类型、常量、工具函数\n- `packages/service/` - 后端服务、数据库模型、API 控制器、工作流引擎\n- `packages/web/` - 共享的前端组件、hooks、样式、国际化\n\n### Projects (应用程序)\n- `projects/app/` - 主 NextJS Web 应用(前端 + API 路由)\n- `projects/code-sandbox/` - Bun + Hono 代码执行沙箱服务\n- `projects/mcp_server/` - Model Context Protocol 服务器实现\n\n### 关键目录\n- `document/` - 文档站点(NextJS 应用及内容)\n- `plugins/` - 外部插件(模型、爬虫等)\n- `deploy/` - Docker 和 Helm 部署配置\n- `test/` - 集中的测试文件和工具\n\n## 开发命令\n\n常用开发命令见 [FastGPT 开发命令](./.agents/code/commands.md)。\n\n## 测试\n\n项目使用 Vitest 进行测试并生成覆盖率报告。主要测试命令:\n- `pnpm test` - 运行所有测试\n- `pnpm test <file-path...>` - 顺序运行跨 workspace 的局部测试，关闭覆盖率并限制为单 worker，避免多个 Vitest/Mongo 实例争抢本地资源\n- `FASTGPT_TEST_SCOPE=app pnpm test` - 只运行指定 workspace；支持逗号分隔多个 scope，以及 `workspace`、`repo`\n- `FASTGPT_TEST_MODE=integration pnpm test` - 运行 service 集成测试；`sandbox` 运行沙箱集成测试，`all` 运行 workspace 单测和 service 集成测试\n- 测试文件位于 `test/` 目录和 `projects/{{name}}/test/`，代表这`packages`和`单个 project`的测试文件目录。\n- 覆盖率报告生成在 `coverage/` 目录\n\n测试范围要求：\n\n- 默认只测试本次改动的代码及可能受影响的代码，根据依赖关系选择最小且足以验证改动的测试范围。\n- 在开发和交付过程中不主动运行全量测试。\n- 只有用户完成最终验收后，才运行完整测试。\n\n## 代码组织模式\n\n### Monorepo 结构\n- 共享代码存放在 `packages/` 中,通过 workspace 引用导入\n- `projects/` 中的每个项目都是独立的应用程序\n- 使用 `@fastgpt/global`、`@fastgpt/service`、`@fastgpt/web` 导入共享包\n\n### API 结构\n- NextJS API 路由在 `projects/app/src/pages/api/`\n- API 路由合约定义在`packages/global/openapi/`, 对应的\n- 通用服务端业务逻辑在 `packages/service/`和`projects/app/src/service`\n- 数据库模型在 `packages/service/` 中,使用 MongoDB/Mongoose\n\n### 前端架构\n- React 组件在 `projects/app/src/components/` 和 `packages/web/components/`\n- 使用 Chakra UI 进行样式设计,自定义主题在 `packages/web/styles/theme.ts`\n- 国际化支持文件在 `packages/web/i18n/`\n- 使用 React Context 和 Zustand 进行状态管理\n\n## 开发注意事项\n\n- **包管理器**: 使用 pnpm 及 workspace 配置\n- **Node 版本**: 需要 Node.js >=20.x, pnpm =10.x\n- **数据库**: 支持 MongoDB、带 pgvector 的 PostgreSQL 或 Milvus 向量存储\n- **AI 集成**: 通过统一接口支持多个 AI 提供商\n- **国际化**: 完整支持中文、英文和日文\n- **部署配置保护**: 修改代码过程中不得修改任何部署相关的 `.yml` 或 `.yaml` 文件；如果需求确实需要调整部署配置，必须先获得用户明确确认。\n\n## 关键文件模式\n\n- `.ts` 和 `.tsx` 文件全部使用 TypeScript\n- 数据库模型使用 Mongoose 配合 TypeScript\n- API 路由遵循 NextJS 约定\n- 组件文件使用 React 函数式组件和 hooks\n- 共享类型定义在 `packages/global/`中\n\n## 代码规范\n\n- 所有代码编写、修改、重构和测试调整都必须遵守 [FastGPT 代码规范](./.agents/code/syntax.md)。开始改动前先查看相关规范；如果规范与当前实现习惯冲突，优先按规范执行，并只在有明确业务或兼容性理由时说明例外。\n\n### MongoDB Schema 与索引维护\n\n- 所有由 FastGPT 管理的当前索引和废弃索引都必须通过 `defineIndex(schema, { key, options, deprecated })` 声明：`deprecated` 默认是 `false`，当前索引省略该字段；只有废弃索引显式使用 `deprecated: true`。不要直接调用 `schema.index()`，也不要在字段定义中使用 `index: true` 或 `unique: true` 隐式创建索引。\n- 每当新增、修改、删除或重命名 MongoDB/Mongoose Schema 字段、索引定义、唯一约束、TTL、partialFilterExpression、collation 等索引相关配置时，必须同步检查是否有 FastGPT 旧版本创建的索引不再被当前 Schema 使用。\n- 如果历史索引可能继续影响写入约束、查询计划或存储成本，应在所属 Schema 文件中通过 `defineIndex(schema, { key, options, deprecated: true })` 紧邻当前索引声明登记删除定义，并补充/调整 `packages/service/test/common/mongo/indexManager.test.ts` 的清理行为覆盖。索引名默认由 key 推导，也可通过 `options.name` 显式指定；删除前按 name 定位，再精确匹配 key（text 索引兼容 `_fts/_ftsx` 与 weights）；options 不参与匹配。\n- 不要登记客户自建索引、无法确认来源的索引，或仅凭当前 Schema 未声明就推断为废弃的索引。主动同步只允许删除 FastGPT 明确创建过、明确废弃且与 Schema 本地声明精确匹配的历史索引。\n\n### API 入参校验\n\n- 编写或修改 NextJS API 路由时，如果需要校验接口入参（`req.body`、`req.query`、`req.params`），必须使用 `parseApiInput`，不要直接写 `SomeSchema.parse(req.body)`、`SomeSchema.parse(req.query)` 或 `SomeSchema.parse(req.params)`。\n- `parseApiInput` 从 `@fastgpt/service/common/zod/requestParseError` 导入，用法示例：\n\n```ts\nimport { parseApiInput } from '@fastgpt/service/common/zod/requestParseError';\n\nconst { body, query } = parseApiInput({\n  req,\n  bodySchema: CreateSomethingBodySchema,\n  querySchema: GetSomethingQuerySchema\n});\n```\n\n- 这个 helper 只用于 API 边界的请求入参校验。内部业务数据、数据库记录、模型返回、工具调用参数等 schema 校验仍使用普通 `Schema.parse(...)`，因为这些错误应按内部 bug 上报。\n- 相关设计见 [Zod 请求入参错误降噪设计](./.agents/design/api/zod-request-parse-error-handling.md)。\n\n### 函数注释\n\n- 编写或拆分函数时，必须关注函数注释。对导出函数、核心业务函数、hook、复杂工具函数、跨模块复用函数，优先使用 `/** ... */` 形式补充函数级注释。\n- 函数注释应说明函数职责、输入输出约定、关键分支、边界行为和设计原因，尤其是容易误解的计费、权限、requestId、错误处理、流式响应、缓存、并发、兼容逻辑。\n- 避免写无意义注释，例如只复述“设置变量”“返回结果”。如果函数逻辑简单且语义已经完全由命名表达，可以不写冗余注释。\n- 对复杂函数内部的关键判断，也应补充简短中文注释，说明为什么这样处理，而不是逐行解释代码。\n\n### 子函数位置\n\n- 拆分子函数时，优先把只被单个函数使用的 helper 放在该函数内部，减少模块级私有函数的暴露范围和阅读负担。\n- 只有跨函数复用、需要单独导出测试、或语义上属于模块公共能力的 helper，才放到模块级；放到模块级时应补充函数级注释说明职责和边界。\n- 对于递归、错误处理、权限校验、路径处理、计费/requestId 等容易误解的局部 helper，应在局部函数或关键分支旁补充简短中文注释说明设计原因。\n\n## 运行要求\n\n### 基础要求\n\n1. 保持怀疑态度，要深入思考和分析现有代码，提出问题，并让用户确认。\n2. 编写单个需求时，只运行覆盖改动代码和可能受影响代码的局部测试；用户完成最终验收前，不主动运行全量测试。\n\n### 输出规范\n\n1. 输出文档位置:\n   1.1. 设计文档: [.agents/design](.agents/design)，todo 跟在设计文档后面。\n   1.2. 问题分析文档: [.agents/issue](.agents/issue)\n2. 相同需求文档，尽量写在一起（内容超过 500 行，可以分批写入），或者创建要给目录一起管理，不要随意平铺一堆不同版本的相同问题的文档。\n3. 文件输出，使用正确的编码格式，例如UTF-8。\n4. 除非用户指明，否则不要编写总结报告。\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/plugin.json)"},"files":{"AGENTS.md":"# AGENTS.md\n\n本文件为 Agent 在本仓库中工作时提供指导说明。\n\n## 项目概述\n\nFastGPT 是一个 AI Agent 构建平台,提供开箱即用的数据处理、模型调用能力和可视化工作流编排。这是一个基于 NextJS 构建的全栈 TypeScript 应用,后端使用 MongoDB/PostgreSQL。\n\n**技术栈**: NextJS + TypeScript + ChakraUI + MongoDB + VectorDB(PG, Milvus, Zilliz, OceanBase, SeekDB, OpenGauss......)\n\n## 设计文档\n\n你可以参考 [项目设计文档](./.agents/design/) 来了解 FastGPT 已有的设计方案。\n\n## 架构\n\n这是一个使用 pnpm workspaces 的 monorepo,主要结构如下:\n\n### Packages (库代码)\n- `packages/global/` - 所有项目共享的类型、常量、工具函数\n- `packages/service/` - 后端服务、数据库模型、API 控制器、工作流引擎\n- `packages/web/` - 共享的前端组件、hooks、样式、国际化\n\n### Projects (应用程序)\n- `projects/app/` - 主 NextJS Web 应用(前端 + API 路由)\n- `projects/code-sandbox/` - Bun + Hono 代码执行沙箱服务\n- `projects/mcp_server/` - Model Context Protocol 服务器实现\n\n### 关键目录\n- `document/` - 文档站点(NextJS 应用及内容)\n- `plugins/` - 外部插件(模型、爬虫等)\n- `deploy/` - Docker 和 Helm 部署配置\n- `test/` - 集中的测试文件和工具\n\n## 开发命令\n\n常用开发命令见 [FastGPT 开发命令](./.agents/code/commands.md)。\n\n## 测试\n\n项目使用 Vitest 进行测试并生成覆盖率报告。主要测试命令:\n- `pnpm test` - 运行所有测试\n- `pnpm test <file-path...>` - 顺序运行跨 workspace 的局部测试，关闭覆盖率并限制为单 worker，避免多个 Vitest/Mongo 实例争抢本地资源\n- `FASTGPT_TEST_SCOPE=app pnpm test` - 只运行指定 workspace；支持逗号分隔多个 scope，以及 `workspace`、`repo`\n- `FASTGPT_TEST_MODE=integration pnpm test` - 运行 service 集成测试；`sandbox` 运行沙箱集成测试，`all` 运行 workspace 单测和 service 集成测试\n- 测试文件位于 `test/` 目录和 `projects/{{name}}/test/`，代表这`packages`和`单个 project`的测试文件目录。\n- 覆盖率报告生成在 `coverage/` 目录\n\n测试范围要求：\n\n- 默认只测试本次改动的代码及可能受影响的代码，根据依赖关系选择最小且足以验证改动的测试范围。\n- 在开发和交付过程中不主动运行全量测试。\n- 只有用户完成最终验收后，才运行完整测试。\n\n## 代码组织模式\n\n### Monorepo 结构\n- 共享代码存放在 `packages/` 中,通过 workspace 引用导入\n- `projects/` 中的每个项目都是独立的应用程序\n- 使用 `@fastgpt/global`、`@fastgpt/service`、`@fastgpt/web` 导入共享包\n\n### API 结构\n- NextJS API 路由在 `projects/app/src/pages/api/`\n- API 路由合约定义在`packages/global/openapi/`, 对应的\n- 通用服务端业务逻辑在 `packages/service/`和`projects/app/src/service`\n- 数据库模型在 `packages/service/` 中,使用 MongoDB/Mongoose\n\n### 前端架构\n- React 组件在 `projects/app/src/components/` 和 `packages/web/components/`\n- 使用 Chakra UI 进行样式设计,自定义主题在 `packages/web/styles/theme.ts`\n- 国际化支持文件在 `packages/web/i18n/`\n- 使用 React Context 和 Zustand 进行状态管理\n\n## 开发注意事项\n\n- **包管理器**: 使用 pnpm 及 workspace 配置\n- **Node 版本**: 需要 Node.js >=20.x, pnpm =10.x\n- **数据库**: 支持 MongoDB、带 pgvector 的 PostgreSQL 或 Milvus 向量存储\n- **AI 集成**: 通过统一接口支持多个 AI 提供商\n- **国际化**: 完整支持中文、英文和日文\n- **部署配置保护**: 修改代码过程中不得修改任何部署相关的 `.yml` 或 `.yaml` 文件；如果需求确实需要调整部署配置，必须先获得用户明确确认。\n\n## 关键文件模式\n\n- `.ts` 和 `.tsx` 文件全部使用 TypeScript\n- 数据库模型使用 Mongoose 配合 TypeScript\n- API 路由遵循 NextJS 约定\n- 组件文件使用 React 函数式组件和 hooks\n- 共享类型定义在 `packages/global/`中\n\n## 代码规范\n\n- 所有代码编写、修改、重构和测试调整都必须遵守 [FastGPT 代码规范](./.agents/code/syntax.md)。开始改动前先查看相关规范；如果规范与当前实现习惯冲突，优先按规范执行，并只在有明确业务或兼容性理由时说明例外。\n\n### MongoDB Schema 与索引维护\n\n- 所有由 FastGPT 管理的当前索引和废弃索引都必须通过 `defineIndex(schema, { key, options, deprecated })` 声明：`deprecated` 默认是 `false`，当前索引省略该字段；只有废弃索引显式使用 `deprecated: true`。不要直接调用 `schema.index()`，也不要在字段定义中使用 `index: true` 或 `unique: true` 隐式创建索引。\n- 每当新增、修改、删除或重命名 MongoDB/Mongoose Schema 字段、索引定义、唯一约束、TTL、partialFilterExpression、collation 等索引相关配置时，必须同步检查是否有 FastGPT 旧版本创建的索引不再被当前 Schema 使用。\n- 如果历史索引可能继续影响写入约束、查询计划或存储成本，应在所属 Schema 文件中通过 `defineIndex(schema, { key, options, deprecated: true })` 紧邻当前索引声明登记删除定义，并补充/调整 `packages/service/test/common/mongo/indexManager.test.ts` 的清理行为覆盖。索引名默认由 key 推导，也可通过 `options.name` 显式指定；删除前按 name 定位，再精确匹配 key（text 索引兼容 `_fts/_ftsx` 与 weights）；options 不参与匹配。\n- 不要登记客户自建索引、无法确认来源的索引，或仅凭当前 Schema 未声明就推断为废弃的索引。主动同步只允许删除 FastGPT 明确创建过、明确废弃且与 Schema 本地声明精确匹配的历史索引。\n\n### API 入参校验\n\n- 编写或修改 NextJS API 路由时，如果需要校验接口入参（`req.body`、`req.query`、`req.params`），必须使用 `parseApiInput`，不要直接写 `SomeSchema.parse(req.body)`、`SomeSchema.parse(req.query)` 或 `SomeSchema.parse(req.params)`。\n- `parseApiInput` 从 `@fastgpt/service/common/zod/requestParseError` 导入，用法示例：\n\n```ts\nimport { parseApiInput } from '@fastgpt/service/common/zod/requestParseError';\n\nconst { body, query } = parseApiInput({\n  req,\n  bodySchema: CreateSomethingBodySchema,\n  querySchema: GetSomethingQuerySchema\n});\n```\n\n- 这个 helper 只用于 API 边界的请求入参校验。内部业务数据、数据库记录、模型返回、工具调用参数等 schema 校验仍使用普通 `Schema.parse(...)`，因为这些错误应按内部 bug 上报。\n- 相关设计见 [Zod 请求入参错误降噪设计](./.agents/design/api/zod-request-parse-error-handling.md)。\n\n### 函数注释\n\n- 编写或拆分函数时，必须关注函数注释。对导出函数、核心业务函数、hook、复杂工具函数、跨模块复用函数，优先使用 `/** ... */` 形式补充函数级注释。\n- 函数注释应说明函数职责、输入输出约定、关键分支、边界行为和设计原因，尤其是容易误解的计费、权限、requestId、错误处理、流式响应、缓存、并发、兼容逻辑。\n- 避免写无意义注释，例如只复述“设置变量”“返回结果”。如果函数逻辑简单且语义已经完全由命名表达，可以不写冗余注释。\n- 对复杂函数内部的关键判断，也应补充简短中文注释，说明为什么这样处理，而不是逐行解释代码。\n\n### 子函数位置\n\n- 拆分子函数时，优先把只被单个函数使用的 helper 放在该函数内部，减少模块级私有函数的暴露范围和阅读负担。\n- 只有跨函数复用、需要单独导出测试、或语义上属于模块公共能力的 helper，才放到模块级；放到模块级时应补充函数级注释说明职责和边界。\n- 对于递归、错误处理、权限校验、路径处理、计费/requestId 等容易误解的局部 helper，应在局部函数或关键分支旁补充简短中文注释说明设计原因。\n\n## 运行要求\n\n### 基础要求\n\n1. 保持怀疑态度，要深入思考和分析现有代码，提出问题，并让用户确认。\n2. 编写单个需求时，只运行覆盖改动代码和可能受影响代码的局部测试；用户完成最终验收前，不主动运行全量测试。\n\n### 输出规范\n\n1. 输出文档位置:\n   1.1. 设计文档: [.agents/design](.agents/design)，todo 跟在设计文档后面。\n   1.2. 问题分析文档: [.agents/issue](.agents/issue)\n2. 相同需求文档，尽量写在一起（内容超过 500 行，可以分批写入），或者创建要给目录一起管理，不要随意平铺一堆不同版本的相同问题的文档。\n3. 文件输出，使用正确的编码格式，例如UTF-8。\n4. 除非用户指明，否则不要编写总结报告。\n",".cursor/mcp.json":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.cursor/mcp.json)",".claude-plugin/marketplace.json":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/marketplace.json)",".claude-plugin/plugin.json":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/plugin.json)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/labring/FastGPT/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\n本文件为 Agent 在本仓库中工作时提供指导说明。\n\n## 项目概述\n\nFastGPT 是一个 AI Agent 构建平台,提供开箱即用的数据处理、模型调用能力和可视化工作流编排。这是一个基于 NextJS 构建的全栈 TypeScript 应用,后端使用 MongoDB/PostgreSQL。\n\n**技术栈**: NextJS + TypeScript + ChakraUI + MongoDB + VectorDB(PG, Milvus, Zilliz, OceanBase, SeekDB, OpenGauss......)\n\n## 设计文档\n\n你可以参考 [项目设计文档](./.agents/design/) 来了解 FastGPT 已有的设计方案。\n\n## 架构\n\n这是一个使用 pnpm workspaces 的 monorepo,主要结构如下:\n\n### Packages (库代码)\n- `packages/global/` - 所有项目共享的类型、常量、工具函数\n- `packages/service/` - 后端服务、数据库模型、API 控制器、工作流引擎\n- `packages/web/` - 共享的前端组件、hooks、样式、国际化\n\n### Projects (应用程序)\n- `projects/app/` - 主 NextJS Web 应用(前端 + API 路由)\n- `projects/code-sandbox/` - Bun + Hono 代码执行沙箱服务\n- `projects/mcp_server/` - Model Context Protocol 服务器实现\n\n### 关键目录\n- `document/` - 文档站点(NextJS 应用及内容)\n- `plugins/` - 外部插件(模型、爬虫等)\n- `deploy/` - Docker 和 Helm 部署配置\n- `test/` - 集中的测试文件和工具\n\n## 开发命令\n\n常用开发命令见 [FastGPT 开发命令](./.agents/code/commands.md)。\n\n## 测试\n\n项目使用 Vitest 进行测试并生成覆盖率报告。主要测试命令:\n- `pnpm test` - 运行所有测试\n- `pnpm test <file-path...>` - 顺序运行跨 workspace 的局部测试，关闭覆盖率并限制为单 worker，避免多个 Vitest/Mongo 实例争抢本地资源\n- `FASTGPT_TEST_SCOPE=app pnpm test` - 只运行指定 workspace；支持逗号分隔多个 scope，以及 `workspace`、`repo`\n- `FASTGPT_TEST_MODE=integration pnpm test` - 运行 service 集成测试；`sandbox` 运行沙箱集成测试，`all` 运行 workspace 单测和 service 集成测试\n- 测试文件位于 `test/` 目录和 `projects/{{name}}/test/`，代表这`packages`和`单个 project`的测试文件目录。\n- 覆盖率报告生成在 `coverage/` 目录\n\n测试范围要求：\n\n- 默认只测试本次改动的代码及可能受影响的代码，根据依赖关系选择最小且足以验证改动的测试范围。\n- 在开发和交付过程中不主动运行全量测试。\n- 只有用户完成最终验收后，才运行完整测试。\n\n## 代码组织模式\n\n### Monorepo 结构\n- 共享代码存放在 `packages/` 中,通过 workspace 引用导入\n- `projects/` 中的每个项目都是独立的应用程序\n- 使用 `@fastgpt/global`、`@fastgpt/service`、`@fastgpt/web` 导入共享包\n\n### API 结构\n- NextJS API 路由在 `projects/app/src/pages/api/`\n- API 路由合约定义在`packages/global/openapi/`, 对应的\n- 通用服务端业务逻辑在 `packages/service/`和`projects/app/src/service`\n- 数据库模型在 `packages/service/` 中,使用 MongoDB/Mongoose\n\n### 前端架构\n- React 组件在 `projects/app/src/components/` 和 `packages/web/components/`\n- 使用 Chakra UI 进行样式设计,自定义主题在 `packages/web/styles/theme.ts`\n- 国际化支持文件在 `packages/web/i18n/`\n- 使用 React Context 和 Zustand 进行状态管理\n\n## 开发注意事项\n\n- **包管理器**: 使用 pnpm 及 workspace 配置\n- **Node 版本**: 需要 Node.js >=20.x, pnpm =10.x\n- **数据库**: 支持 MongoDB、带 pgvector 的 PostgreSQL 或 Milvus 向量存储\n- **AI 集成**: 通过统一接口支持多个 AI 提供商\n- **国际化**: 完整支持中文、英文和日文\n- **部署配置保护**: 修改代码过程中不得修改任何部署相关的 `.yml` 或 `.yaml` 文件；如果需求确实需要调整部署配置，必须先获得用户明确确认。\n\n## 关键文件模式\n\n- `.ts` 和 `.tsx` 文件全部使用 TypeScript\n- 数据库模型使用 Mongoose 配合 TypeScript\n- API 路由遵循 NextJS 约定\n- 组件文件使用 React 函数式组件和 hooks\n- 共享类型定义在 `packages/global/`中\n\n## 代码规范\n\n- 所有代码编写、修改、重构和测试调整都必须遵守 [FastGPT 代码规范](./.agents/code/syntax.md)。开始改动前先查看相关规范；如果规范与当前实现习惯冲突，优先按规范执行，并只在有明确业务或兼容性理由时说明例外。\n\n### MongoDB Schema 与索引维护\n\n- 所有由 FastGPT 管理的当前索引和废弃索引都必须通过 `defineIndex(schema, { key, options, deprecated })` 声明：`deprecated` 默认是 `false`，当前索引省略该字段；只有废弃索引显式使用 `deprecated: true`。不要直接调用 `schema.index()`，也不要在字段定义中使用 `index: true` 或 `unique: true` 隐式创建索引。\n- 每当新增、修改、删除或重命名 MongoDB/Mongoose Schema 字段、索引定义、唯一约束、TTL、partialFilterExpression、collation 等索引相关配置时，必须同步检查是否有 FastGPT 旧版本创建的索引不再被当前 Schema 使用。\n- 如果历史索引可能继续影响写入约束、查询计划或存储成本，应在所属 Schema 文件中通过 `defineIndex(schema, { key, options, deprecated: true })` 紧邻当前索引声明登记删除定义，并补充/调整 `packages/service/test/common/mongo/indexManager.test.ts` 的清理行为覆盖。索引名默认由 key 推导，也可通过 `options.name` 显式指定；删除前按 name 定位，再精确匹配 key（text 索引兼容 `_fts/_ftsx` 与 weights）；options 不参与匹配。\n- 不要登记客户自建索引、无法确认来源的索引，或仅凭当前 Schema 未声明就推断为废弃的索引。主动同步只允许删除 FastGPT 明确创建过、明确废弃且与 Schema 本地声明精确匹配的历史索引。\n\n### API 入参校验\n\n- 编写或修改 NextJS API 路由时，如果需要校验接口入参（`req.body`、`req.query`、`req.params`），必须使用 `parseApiInput`，不要直接写 `SomeSchema.parse(req.body)`、`SomeSchema.parse(req.query)` 或 `SomeSchema.parse(req.params)`。\n- `parseApiInput` 从 `@fastgpt/service/common/zod/requestParseError` 导入，用法示例：\n\n```ts\nimport { parseApiInput } from '@fastgpt/service/common/zod/requestParseError';\n\nconst { body, query } = parseApiInput({\n  req,\n  bodySchema: CreateSomethingBodySchema,\n  querySchema: GetSomethingQuerySchema\n});\n```\n\n- 这个 helper 只用于 API 边界的请求入参校验。内部业务数据、数据库记录、模型返回、工具调用参数等 schema 校验仍使用普通 `Schema.parse(...)`，因为这些错误应按内部 bug 上报。\n- 相关设计见 [Zod 请求入参错误降噪设计](./.agents/design/api/zod-request-parse-error-handling.md)。\n\n### 函数注释\n\n- 编写或拆分函数时，必须关注函数注释。对导出函数、核心业务函数、hook、复杂工具函数、跨模块复用函数，优先使用 `/** ... */` 形式补充函数级注释。\n- 函数注释应说明函数职责、输入输出约定、关键分支、边界行为和设计原因，尤其是容易误解的计费、权限、requestId、错误处理、流式响应、缓存、并发、兼容逻辑。\n- 避免写无意义注释，例如只复述“设置变量”“返回结果”。如果函数逻辑简单且语义已经完全由命名表达，可以不写冗余注释。\n- 对复杂函数内部的关键判断，也应补充简短中文注释，说明为什么这样处理，而不是逐行解释代码。\n\n### 子函数位置\n\n- 拆分子函数时，优先把只被单个函数使用的 helper 放在该函数内部，减少模块级私有函数的暴露范围和阅读负担。\n- 只有跨函数复用、需要单独导出测试、或语义上属于模块公共能力的 helper，才放到模块级；放到模块级时应补充函数级注释说明职责和边界。\n- 对于递归、错误处理、权限校验、路径处理、计费/requestId 等容易误解的局部 helper，应在局部函数或关键分支旁补充简短中文注释说明设计原因。\n\n## 运行要求\n\n### 基础要求\n\n1. 保持怀疑态度，要深入思考和分析现有代码，提出问题，并让用户确认。\n2. 编写单个需求时，只运行覆盖改动代码和可能受影响代码的局部测试；用户完成最终验收前，不主动运行全量测试。\n\n### 输出规范\n\n1. 输出文档位置:\n   1.1. 设计文档: [.agents/design](.agents/design)，todo 跟在设计文档后面。\n   1.2. 问题分析文档: [.agents/issue](.agents/issue)\n2. 相同需求文档，尽量写在一起（内容超过 500 行，可以分批写入），或者创建要给目录一起管理，不要随意平铺一堆不同版本的相同问题的文档。\n3. 文件输出，使用正确的编码格式，例如UTF-8。\n4. 除非用户指明，否则不要编写总结报告。\n","isInternal":false,"tokens":2912,"sizeBytes":8895},{"name":"marketplace.json","path":".claude-plugin/marketplace.json","rawUrl":"https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/marketplace.json","title":"Claude Plugin Marketplace Catalog","category":"marketplace","format":"json","content":"# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/marketplace.json)","tokens":300,"sizeBytes":194},{"name":"plugin.json","path":".claude-plugin/plugin.json","rawUrl":"https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/plugin.json","title":"claude-plugin Plugin Manifest","category":"plugin-manifest","format":"json","content":"# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/plugin.json)","tokens":300,"sizeBytes":180},{"name":"mcp.json","path":".cursor/mcp.json","rawUrl":"https://raw.githubusercontent.com/labring/FastGPT/HEAD/.cursor/mcp.json","title":"Model Context Protocol (MCP) Configuration","category":"mcp-config","format":"json","content":"# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.cursor/mcp.json)","tokens":300,"sizeBytes":173}],"systemPromptSnippet":"<yakaai_skills repo=\"labring/FastGPT\">\n<!-- File: AGENTS.md (Tokens: ~2912 | Category: root-instruction) -->\n# AGENTS.md\n\n本文件为 Agent 在本仓库中工作时提供指导说明。\n\n## 项目概述\n\nFastGPT 是一个 AI Agent 构建平台,提供开箱即用的数据处理、模型调用能力和可视化工作流编排。这是一个基于 NextJS 构建的全栈 TypeScript 应用,后端使用 MongoDB/PostgreSQL。\n\n**技术栈**: NextJS + TypeScript + ChakraUI + MongoDB + VectorDB(PG, Milvus, Zilliz, OceanBase, SeekDB, OpenGauss......)\n\n## 设计文档\n\n你可以参考 [项目设计文档](./.agents/design/) 来了解 FastGPT 已有的设计方案。\n\n## 架构\n\n这是一个使用 pnpm workspaces 的 monorepo,主要结构如下:\n\n### Packages (库代码)\n- `packages/global/` - 所有项目共享的类型、常量、工具函数\n- `packages/service/` - 后端服务、数据库模型、API 控制器、工作流引擎\n- `packages/web/` - 共享的前端组件、hooks、样式、国际化\n\n### Projects (应用程序)\n- `projects/app/` - 主 NextJS Web 应用(前端 + API 路由)\n- `projects/code-sandbox/` - Bun + Hono 代码执行沙箱服务\n- `projects/mcp_server/` - Model Context Protocol 服务器实现\n\n### 关键目录\n- `document/` - 文档站点(NextJS 应用及内容)\n- `plugins/` - 外部插件(模型、爬虫等)\n- `deploy/` - Docker 和 Helm 部署配置\n- `test/` - 集中的测试文件和工具\n\n## 开发命令\n\n常用开发命令见 [FastGPT 开发命令](./.agents/code/commands.md)。\n\n## 测试\n\n项目使用 Vitest 进行测试并生成覆盖率报告。主要测试命令:\n- `pnpm test` - 运行所有测试\n- `pnpm test <file-path...>` - 顺序运行跨 workspace 的局部测试，关闭覆盖率并限制为单 worker，避免多个 Vitest/Mongo 实例争抢本地资源\n- `FASTGPT_TEST_SCOPE=app pnpm test` - 只运行指定 workspace；支持逗号分隔多个 scope，以及 `workspace`、`repo`\n- `FASTGPT_TEST_MODE=integration pnpm test` - 运行 service 集成测试；`sandbox` 运行沙箱集成测试，`all` 运行 workspace 单测和 service 集成测试\n- 测试文件位于 `test/` 目录和 `projects/{{name}}/test/`，代表这`packages`和`单个 project`的测试文件目录。\n- 覆盖率报告生成在 `coverage/` 目录\n\n测试范围要求：\n\n- 默认只测试本次改动的代码及可能受影响的代码，根据依赖关系选择最小且足以验证改动的测试范围。\n- 在开发和交付过程中不主动运行全量测试。\n- 只有用户完成最终验收后，才运行完整测试。\n\n## 代码组织模式\n\n### Monorepo 结构\n- 共享代码存放在 `packages/` 中,通过 workspace 引用导入\n- `projects/` 中的每个项目都是独立的应用程序\n- 使用 `@fastgpt/global`、`@fastgpt/service`、`@fastgpt/web` 导入共享包\n\n### API 结构\n- NextJS API 路由在 `projects/app/src/pages/api/`\n- API 路由合约定义在`packages/global/openapi/`, 对应的\n- 通用服务端业务逻辑在 `packages/service/`和`projects/app/src/service`\n- 数据库模型在 `packages/service/` 中,使用 MongoDB/Mongoose\n\n### 前端架构\n- React 组件在 `projects/app/src/components/` 和 `packages/web/components/`\n- 使用 Chakra UI 进行样式设计,自定义主题在 `packages/web/styles/theme.ts`\n- 国际化支持文件在 `packages/web/i18n/`\n- 使用 React Context 和 Zustand 进行状态管理\n\n## 开发注意事项\n\n- **包管理器**: 使用 pnpm 及 workspace 配置\n- **Node 版本**: 需要 Node.js >=20.x, pnpm =10.x\n- **数据库**: 支持 MongoDB、带 pgvector 的 PostgreSQL 或 Milvus 向量存储\n- **AI 集成**: 通过统一接口支持多个 AI 提供商\n- **国际化**: 完整支持中文、英文和日文\n- **部署配置保护**: 修改代码过程中不得修改任何部署相关的 `.yml` 或 `.yaml` 文件；如果需求确实需要调整部署配置，必须先获得用户明确确认。\n\n## 关键文件模式\n\n- `.ts` 和 `.tsx` 文件全部使用 TypeScript\n- 数据库模型使用 Mongoose 配合 TypeScript\n- API 路由遵循 NextJS 约定\n- 组件文件使用 React 函数式组件和 hooks\n- 共享类型定义在 `packages/global/`中\n\n## 代码规范\n\n- 所有代码编写、修改、重构和测试调整都必须遵守 [FastGPT 代码规范](./.agents/code/syntax.md)。开始改动前先查看相关规范；如果规范与当前实现习惯冲突，优先按规范执行，并只在有明确业务或兼容性理由时说明例外。\n\n### MongoDB Schema 与索引维护\n\n- 所有由 FastGPT 管理的当前索引和废弃索引都必须通过 `defineIndex(schema, { key, options, deprecated })` 声明：`deprecated` 默认是 `false`，当前索引省略该字段；只有废弃索引显式使用 `deprecated: true`。不要直接调用 `schema.index()`，也不要在字段定义中使用 `index: true` 或 `unique: true` 隐式创建索引。\n- 每当新增、修改、删除或重命名 MongoDB/Mongoose Schema 字段、索引定义、唯一约束、TTL、partialFilterExpression、collation 等索引相关配置时，必须同步检查是否有 FastGPT 旧版本创建的索引不再被当前 Schema 使用。\n- 如果历史索引可能继续影响写入约束、查询计划或存储成本，应在所属 Schema 文件中通过 `defineIndex(schema, { key, options, deprecated: true })` 紧邻当前索引声明登记删除定义，并补充/调整 `packages/service/test/common/mongo/indexManager.test.ts` 的清理行为覆盖。索引名默认由 key 推导，也可通过 `options.name` 显式指定；删除前按 name 定位，再精确匹配 key（text 索引兼容 `_fts/_ftsx` 与 weights）；options 不参与匹配。\n- 不要登记客户自建索引、无法确认来源的索引，或仅凭当前 Schema 未声明就推断为废弃的索引。主动同步只允许删除 FastGPT 明确创建过、明确废弃且与 Schema 本地声明精确匹配的历史索引。\n\n### API 入参校验\n\n- 编写或修改 NextJS API 路由时，如果需要校验接口入参（`req.body`、`req.query`、`req.params`），必须使用 `parseApiInput`，不要直接写 `SomeSchema.parse(req.body)`、`SomeSchema.parse(req.query)` 或 `SomeSchema.parse(req.params)`。\n- `parseApiInput` 从 `@fastgpt/service/common/zod/requestParseError` 导入，用法示例：\n\n```ts\nimport { parseApiInput } from '@fastgpt/service/common/zod/requestParseError';\n\nconst { body, query } = parseApiInput({\n  req,\n  bodySchema: CreateSomethingBodySchema,\n  querySchema: GetSomethingQuerySchema\n});\n```\n\n- 这个 helper 只用于 API 边界的请求入参校验。内部业务数据、数据库记录、模型返回、工具调用参数等 schema 校验仍使用普通 `Schema.parse(...)`，因为这些错误应按内部 bug 上报。\n- 相关设计见 [Zod 请求入参错误降噪设计](./.agents/design/api/zod-request-parse-error-handling.md)。\n\n### 函数注释\n\n- 编写或拆分函数时，必须关注函数注释。对导出函数、核心业务函数、hook、复杂工具函数、跨模块复用函数，优先使用 `/** ... */` 形式补充函数级注释。\n- 函数注释应说明函数职责、输入输出约定、关键分支、边界行为和设计原因，尤其是容易误解的计费、权限、requestId、错误处理、流式响应、缓存、并发、兼容逻辑。\n- 避免写无意义注释，例如只复述“设置变量”“返回结果”。如果函数逻辑简单且语义已经完全由命名表达，可以不写冗余注释。\n- 对复杂函数内部的关键判断，也应补充简短中文注释，说明为什么这样处理，而不是逐行解释代码。\n\n### 子函数位置\n\n- 拆分子函数时，优先把只被单个函数使用的 helper 放在该函数内部，减少模块级私有函数的暴露范围和阅读负担。\n- 只有跨函数复用、需要单独导出测试、或语义上属于模块公共能力的 helper，才放到模块级；放到模块级时应补充函数级注释说明职责和边界。\n- 对于递归、错误处理、权限校验、路径处理、计费/requestId 等容易误解的局部 helper，应在局部函数或关键分支旁补充简短中文注释说明设计原因。\n\n## 运行要求\n\n### 基础要求\n\n1. 保持怀疑态度，要深入思考和分析现有代码，提出问题，并让用户确认。\n2. 编写单个需求时，只运行覆盖改动代码和可能受影响代码的局部测试；用户完成最终验收前，不主动运行全量测试。\n\n### 输出规范\n\n1. 输出文档位置:\n   1.1. 设计文档: [.agents/design](.agents/design)，todo 跟在设计文档后面。\n   1.2. 问题分析文档: [.agents/issue](.agents/issue)\n2. 相同需求文档，尽量写在一起（内容超过 500 行，可以分批写入），或者创建要给目录一起管理，不要随意平铺一堆不同版本的相同问题的文档。\n3. 文件输出，使用正确的编码格式，例如UTF-8。\n4. 除非用户指明，否则不要编写总结报告。\n\n<!-- File: .claude-plugin/marketplace.json (Tokens: ~300 | Category: marketplace) -->\n# Claude Plugin Marketplace Catalog\n\nPath: `.claude-plugin/marketplace.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/marketplace.json)\n\n<!-- File: .claude-plugin/plugin.json (Tokens: ~300 | Category: plugin-manifest) -->\n# claude-plugin Plugin Manifest\n\nPath: `.claude-plugin/plugin.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.claude-plugin/plugin.json)\n\n<!-- File: .cursor/mcp.json (Tokens: ~300 | Category: mcp-config) -->\n# Model Context Protocol (MCP) Configuration\n\nPath: `.cursor/mcp.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/labring/FastGPT/HEAD/.cursor/mcp.json)\n</yakaai_skills>"}