move system plugin config (#5803) (#5813)

* move system plugin config (#5803)

* move system plugin config

* extract tag bar

* filter

* tool detail temp

* marketplace

* params

* fix

* type

* search

* tags render

* status

* ui

* code

* connect to backend (#5815)

* feat: marketplace apis & type definitions (#5817)

* chore: marketplace init

* chore: marketplace list api type

* chore: detail api

* marketplace & import

* feat: marketplace ui (#5826)

* temp

* marketplace

* import

* feat: detail return readme

* chore: cache data expire 10 mins

* chore: update docs

* feat: marketplace ui

---------

Co-authored-by: heheer <[email protected]>

* feat: marketplace (#5830)

* temp

* marketplace

* chore: tool list tag filter

* chore: adjust

---------

Co-authored-by: heheer <[email protected]>

* tool detail drawer

* remove tag filter

* fix

* fix

* fix build

* update pnpm-lock

* fix type

* perf code

* marketplace router

* fix build

* navbar icon

* fix ui

* fix init

* docs: marketplace/plugin (#5832)

* temp

* marketplace

* docs(plugin): system tool docs

---------

Co-authored-by: heheer <[email protected]>

* default url

* feat: i18n/ docker build (#5833)

* chore: docker build

* feat: i18n selector

* fix

* fix

* fix: i18n parse

* fix: i18n parse

---------

Co-authored-by: heheer <[email protected]>
Co-authored-by: Finley Ge <[email protected]>
Co-authored-by: heheer <[email protected]>

Author: 3 people

.eslintignore

@@ -23,4 +23,6 @@ vitest.config.mts
 bin/
 scripts/
 deploy/
-document/
+document/
+
+projects/marketplace

.github/workflows/marketplace.yml

@@ -0,0 +1,86 @@
+name: Build and Deploy Marketplace
+
+on:
+  workflow_dispatch:
+    inputs:
+      base_url:
+        description: 'Base URL for the application'
+        required: false
+        default: ''
+        type: string
+      tag:
+        description: 'Docker image tag'
+        required: false
+        default: 'latest'
+        type: string
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/marketplace
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.14.0'
+          cache: 'pnpm'
+
+      - name: Install pnpm
+        run: npm install -g [email protected]
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Log in to Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=raw,value=${{ github.event.inputs.tag || 'latest' }}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./projects/marketplace/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            base_url=${{ github.event.inputs.base_url || '' }}
+            proxy=${{ vars.PROXY || '' }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+
+    steps:
+      - name: Deploy notification
+        run: |
+          echo "🚀 Marketplace image has been built and pushed to registry"
+          echo "📦 Image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.event.inputs.tag || 'latest' }}"
+          echo "🌐 Base URL: ${{ github.event.inputs.base_url || 'not specified' }}"

document/content/docs/introduction/development/design/design_plugin.mdx

@@ -32,7 +32,7 @@ description: FastGPT 系统插件设计方案
 
 1. 使用 ts-rest 作为 RPC 框架进行交互，提供 sdk 供 FastGPT 主项目调用
 2. 使用 zod 进行类型验证
-3. 用 bun 进行编译，每个工具编译为单一的 `.js` 文件，支持热插拔。
+3. 用 bun 进行编译，每个工具编译为单一的 `.pkg` 文件，支持热插拔。
 
 ## 项目结构
 
@@ -48,7 +48,8 @@ description: FastGPT 系统插件设计方案
 	- **model** 模型预设
 - **scripts** 脚本（编译、创建新工具）
 - **sdk**: SDK 定义，供外部调用，发布到了 npm
-- **src**: 运行时，express 服务
+- **runtime**: 运行时，express 服务
+- **lib**: 库文件，提供工具函数和类库
 - **test**: 测试相关
 
 系统工具的结构可以参考 [如何开发系统工具](/docs/introduction/guide/plugins/dev_system_tool)。
@@ -78,7 +79,7 @@ zod 可以实现在运行时的类型校验，也可以提供更高级的功能
 
 ### 使用 bun 进行打包
 
-将插件 bundle 为一个单一的 `.js` 文件是一个重要的设计。这样可以将插件发布出来直接通过网络挂载等的形式使用。
+将插件 bundle 为一个单一的 `.pkg` 文件是一个重要的设计。这样可以将插件发布出来直接通过网络挂载等的形式使用。
 
 ## 未来规划
 

document/content/docs/introduction/guide/plugins/dev_system_tool.mdx

@@ -5,7 +5,9 @@ description: FastGPT 系统工具开发指南
 
 ## 介绍
 
-FastGPT 系统工具项目从 4.10.0 版本后移动到独立的`fastgpt-plugin`项目中，采用纯代码的模式进行工具编写。你可以在`fastgpt-plugin`项目中进行独立开发和调试好插件后，直接向 FastGPT 官方提交 PR 即可，无需运行 FastGPT 主服务。
+FastGPT 系统工具项目从 4.10.0 版本后移动到独立的`fastgpt-plugin`项目中，采用纯代码的模式进行工具编写。
+在 4.14.0 版本插件市场更新后，系统工具开发流程有所改变，请依照最新文档贡献代码。
+你可以在`fastgpt-plugin`项目中进行独立开发和调试好插件后，直接向 FastGPT 官方提交 PR 即可，无需运行 FastGPT 主服务。
 
 ## 概念
 
@@ -14,29 +16,74 @@ FastGPT 系统工具项目从 4.10.0 版本后移动到独立的`fastgpt-plugin`
 
 在`fastgpt-plugin`中，你可以每次创建一个工具/工具集，每次提交时，仅接收一个工具/工具集。如需开发多个，可以创建多个 PR 进行提交。
 
-## 1. 准备工作
+## 1. 准备开发环境
 
-- Fork [fastgpt-plugin 项目](https://github.com/labring/fastgpt-plugin)
-- 安装 [Bun](https://bun.sh/)
-- 部署一套 Minio，也可以直接使用 FastGPT 的 `docker-compose.yml` 中的 Minio。
-- 本地 clone 项目 `git clone [email protected]:[your-github-username]/fastgpt-plugin.git`
-- 拷贝示例环境变量文件，并修改连接到开发环境的 Minio `cp .env.example .env.local`
-- 安装依赖 `bun install`
-- 运行开发环境 `bun run dev`
+### 1.1 安装 Bun
 
-在 dev 环境下，Bun 将监听修改并热更新。
+- 安装 [Bun](https://bun.sh/), FastGPT-plugin 使用 Bun 作为包管理器
 
-## 2. 初始化一个新的工具/工具集
+### 1.2 Fork FastGPT-plugin 仓库
 
-### 2.1 执行创建命令
+Fork 本仓库 `https://github.com/labring/fastgpt-plugin`
 
+### 1.3 搭建开发脚手架
+
+<Tabs items={['通过 Bunx 一键搭建','手动搭建']}>
+<Tab value="通过 Bunx 一键搭建">
+注意：由于使用了 bun 特有的 API，必须使用 bunx 进行安装，使用 npx/npx 等会报错
+
+创建一个新的目录，在该目录下执行：
+```bash
+bunx @fastgpt-sdk/plugin-cli
+```
+
+上述命令会在当前目录下创建 fastgpt-plugin 目录，并且添加两个 remote:
+- upstream 指向官方仓库
+- origin 指向你自己的仓库
+
+默认使用 sparse-checkout 避免拉取所有的官方插件代码
+
+</Tab>
+<Tab value="手动搭建">
+- 本地在一个新建目录下初始化一个 `git`:
+
+```bash
+git init
+```
+
+如果配置了 Git SSH Key, 则可以：
+```bash
+git remote add origin [email protected]:[your-name]/fastgpt-plugin.git
+git remote add upstream [email protected]:labring/fastgpt-plugin.git
+```
+
+否则使用 https:
+```bash
+git remote add origin https://github.com/[your-name]/fastgpt-plugin.git
+git remote add upstream https://github.com/labring/fastgpt-plugin.git
+```
+
+- (可选）使用稀疏检出 (Sparse-checkout) 以避免拉取所有插件代码，如果不进行稀疏检出，则会拉取所有官方插件
+```bash
+git sparse-checkout init --no-cone
+git sparse-checkout add "/*" "!/modules/tool/packages/*"
+git pull
+```
+
+使用命令创建新工具
 ```bash
+bun i
 bun run new:tool
 ```
 
-依据提示分别选择创建工具/工具集，以及目录名（使用 camelCase 小驼峰法命名）。
+</Tab>
+</Tabs>
+
+## 2. 编写工具代码
 
-执行完后，系统会在 `modules/tool/packages/[your-tool-name]` 下生成一个工具/工具集的目录。
+### 2.1 工具代码结构
+
+依据提示分别选择创建工具/工具集，以及目录名（使用 camelCase 小驼峰法命名）。
 
 系统工具 (Tool) 文件结构如下:
 
@@ -48,26 +95,30 @@ test // 测试样例
 config.ts // 配置，配置工具的名称、描述、类型、图标等
 index.ts // 入口，不要改这个文件
 logo.svg // Logo，替换成你的工具的 Logo
+README.md // （可选）README 文件，用于展示工具的使用说明和示例
+assets/ // （可选）assets 目录，用于存放工具的资源文件，如图片、音频等
 package.json // npm 包
 ```
 
 工具集(toolset) 的文件结构如下：
 
 ```plaintext
 children
-└── tool // 这个里面的结构就和上面的 tool 基本一致
+└── tool // 这个里面的结构就和上面的 tool 一致，但是没有 README 和 assets 目录
 config.ts
 index.ts
 logo.svg
+README.md
+assets/
 package.json
 ```
 
 ### 2.2 修改 config.ts
 
 - **name** 和 **description** 字段为中文和英文两种语言
-- **courseUrl** 密钥获取链接，或官网链接，教程链接等。
+- **courseUrl**（可选） 密钥获取链接，或官网链接，教程链接等，如果提供 README.md，则可以写到 README 里面
 - **author** 开发者名
-- **type** 为枚举类型，目前有:
+- **tags** 工具默认的标签，有如下可选标签(枚举类型)
 	- tools: 工具
 	- search: 搜索
 	- multimodal: 多模态
@@ -204,7 +255,7 @@ dalle3 的 outputs 参数格式如下：
 }
 ```
 
-## 2. 编写处理逻辑
+### 2.3 编写处理逻辑
 
 在 `[your-tool-name]/src/index.ts` 为入口编写处理逻辑，需要注意：
 
@@ -234,30 +285,70 @@ export async function tool(props: z.infer<typeof InputType>): Promise<z.infer<ty
 
 上述例子给出了一个传入 formatStr （格式化字符串）并且返回当前时间的简单样例，如需安装包，可以在`/modules/tools/packages/[your-tool-name]`路径下，使用`bun install PACKAGE` 进行安装。
 
-## 3. 调试
+## 4. 构建/打包
+
+FastGPT v4.14.0 后，打包方式变为系统插件打包为一个 `.pkg` 文件，使用命令：
+```bash
+bun run build:pkg
+```
+将本地所有插件构建打包为 `.pkg` 文件，构建目录为 `dist/pkgs`
+
+## 5. 单元测试
+
+FastGPT-plugin 使用 Vitest 作为单测框架。
+
+### 5.1 编写单测样例
 
-### 单测
+在 `test/index.test.ts` 中编写测试样例，使用 `bun run test index.test.ts 完整路径` 即可运行测试。
 
-在 `test/index.test.ts` 中编写测试样例，使用 `bun run test index.test.ts完整路径` 即可运行测试。
+> 注意：不要把你的 secret 密钥等写到测试样例中
+>
+> 使用 Agent 工具编写测试样例时，可能 Agent 工具会修改您的处理逻辑甚至修改整个测试框架的逻辑。
 
-### 从 Scalar 进行测试
+### 5.2 查看测试样例覆盖率（coverage)
 
-浏览器打开`localhost:3000/openapi`可进入`fastgpt-plugin`的 OpenAPI 页面，进行 API 调试。
+浏览器打开 coverage/index.html 可以插件各个模块的覆盖率
+
+提交插件给官方仓库，必须编写单元测试样例，并且达到：
+- 90% 以上代码覆盖率
+- 100% 函数覆盖率
+- 100% 分支条件覆盖率
+
+## 6. E2E （端到端）测试
+
+对于简单的工具，可能并不需要进行 E2E 测试，而如果工具过于复杂，官方人员可能会要求您完成 E2E 测试。
+
+### 6.1 部署 E2E 测试环境
+
+1. 参考 [快速开始本地开发](/docs/introduction/development/intro)，在本地部署一套 FastGPT 开发环境
+2. `cd runtime && cp .env.template .env.local` 复制环境变量样例文件，连接到上一步部署的 Minio, Mongo, Redis 中
+3. `bun run dev` 运行开发环境，修改 FastGPT 的环境变量，连接到你刚刚启动的 fastgpt-plugin
+
+### 6.2 从 Scalar 进行测试
+
+运行 fastgpt-plugin 开发环境
+
+浏览器打开`http://localhost:PORT/openapi`可进入`fastgpt-plugin`的 OpenAPI 页面，进行 API 调试。
+PORT 为你的 fastgpt-plugin 的端口
 
 ![](/imgs/plugin-openapi.png)
 
 可以先通过`/tool/list`接口，获取工具列表，找到需要调试的工具的`toolId`。紧接着，通过`/tool/runStream`来运行工具获取实际结果。
 
 ![](/imgs/plugin-openapi2.png)
 
-### 从 FastGPT 主服务进行测试
+### 6.3 在开发环境下 e2e 测试（有热更新）
+
+默认情况下，fastgpt-plugin 会自动加载在 modules/tool/packages/ 下的所有工具，并自动监听文件修改并进行热更新。
+可以在 FastGPT 中使用这些工具
 
-如果本地运行有`FastGPT`主服务，则可以直接添加对应的工具进行测试。
+### 6.4 在开发环境下上传工具进行 e2e 测试（没有热更新）
 
-### 可视化调试（TODO）
+设置 FastGPT-plugin 的环境变量 `DISABLE_DEV_TOOLS=true` 会禁用自动加载开发环境下的工具，此时可以测试工具的上传。
 
-## 4. 提交工具至官方目录
+## 7. 提交工具至官方目录
 
-完毕上述所有内容后，向官方仓库 `https://github.com/labring/fastgpt-plugin` 提交 PR。官方人员审核通过后即可收录为 FastGPT 的官方插件。
+完毕上述所有内容后，向官方仓库 `https://github.com/labring/fastgpt-plugin` 提交 PR。
+官方人员审核通过后即可收录为 FastGPT 的官方插件。
 
-如无需官方收录，可自行对该项目进行 Docker 打包，并替换官方镜像即可。
+如无需官方收录，则可以参考 [上传系统工具](upload_system_tool) 在自己部署的 FastGPT 中使用。