## 1. Project Overview & Quickstart (GopeedLab/CONTRIBUTING_zh-CN)

## 1. Project Overview & Quickstart (GopeedLab/CONTRIBUTING_zh-CN)

# CONTRIBUTING_zh-CN

Open-source repository GopeedLab/CONTRIBUTING_zh-CN

### Repository Details
- **Repository:** [GopeedLab/CONTRIBUTING_zh-CN](https://github.com/GopeedLab/CONTRIBUTING_zh-CN)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (GopeedLab/docs)

## File: README.md

> [!WARNING]
> This repository is deprecated. The documentation has been migrated to [https://github.com/GopeedLab/website](https://github.com/GopeedLab/website).

## Access

[https://gopeed.com/docs](https://gopeed.com/docs)

## Getting Started

```
pnpm install
pnpm run docs:dev
```

---

## File: package.json

{
  "name": "gopeed-docs-redirect",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "15.5.12"
  },
  "devDependencies": {
    "@types/node": "^25.3.3",
    "@types/react": "^19.2.14",
    "typescript": "^5.9.3"
  }
}

---

## File: tsconfig.json

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

---

## File: .github/workflows/ci.yaml

name: GitHub Actions Vercel Production Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
on:
  workflow_dispatch:
  push:
    branches:
      - main
jobs:
  CI:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Vercel CLI
        run: npm install vercel@canary
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build Project Artifacts
        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

## 2. Official Technical Reference & Guides (GopeedLab/website)

## File: content/docs/ru/dev.mdx

---
title: Руководство
---

В настоящее время Gopeed предоставляет два способа расширения функциональности: подключение через HTTP API и расширение возможностей через разработку расширений на JavaScript.

## Интеграция API

Пожалуйста, обратитесь к [документации по интеграции API](dev-api)

## Разработка расширений

Пожалуйста, обратитесь к [документации по разработке расширений](dev-extension)

---

## File: content/docs/ru/dev-api.mdx

---
title: Интеграция API
---

Gopeed предоставляет интерфейс HTTP API для внешнего использования, позволяющий управлять загрузками через API.

## Включение API

Сначала необходимо установить протокол связи TCP. Перейдите в **Настройки -> Дополнительно -> Протокол связи** и установите протокол связи на TCP. Затем задайте IP-адрес и порт, как показано на рисунке ниже:



<Callout type="info">
  Вы можете установить любой `порт`, но убедитесь, что он не занят другими
  приложениями или не зарезервирован системой, так как это может привести к
  ошибкам доступа.
</Callout>

После этого вы сможете получить доступ к API по адресу `http://127.0.0.1:9999`. В целях безопасности рекомендуется установить токен. Перейдите в **Настройки -> Дополнительно -> API Token** и задайте токен, как показано на рисунке ниже:



> Примечание: Вышеуказанные настройки вступают в силу после перезапуска.

## Использование JS SDK

Gopeed предоставляет официальную библиотеку JS, которую необходимо сначала установить, выполнив `npm install @gopeed/rest`:

```
npm install @gopeed/rest
```

Затем вы можете приступить к использованию, например:

```js
import { Client } from "@gopeed/rest";

(async function () {
  // Создание клиента
  const client = new Client();
  // Создание задачи
  const res = await client.createTask({
    req: {
      url: "https://example.com/file.zip",
    },
  });
})();
```

Дополнительные примеры использования, исходный код и обновления пакетов доступны в [официальном репозитории Gopeed JS](https://github.com/GopeedLab/gopeed-js).

## Использование Python SDK

Python SDK от пользователя сообщества [@tick97115115](https://github.com/tick97115115).

```bash
pip install gospeed_api
```

- Github：https://github.com/tick97115115/gospeed_api
- Пример：https://github.com/tick97115115/gospeed_api/blob/main/tests/test_index.py

## Использование HTTP API

Конечно, вы также можете напрямую вызывать API через HTTP-запросы. Подробнее см. в [документации API](/docs/openapi).

---

## File: content/docs/ru/dev-extension.mdx

---
title: Разработка расширений
---

Gopeed поддерживает разработку расширений на `JavaScript`. Расширения могут расширять функциональность Gopeed, например, загружать видео или музыку с веб-сайтов. Вы можете быстро узнать больше об этом из [официальных примеров](https://github.com/GopeedLab/gopeed-extension-samples/blob/main/README_zh-CN.md).

Расширения Gopeed основаны на `git` для реализации децентрализованного управления расширениями. Пока исходный код расширения размещён в удалённом git-репозитории, оно может быть установлено и обновлено через Gopeed. Поэтому будь то `github`, `gitee`, `gitlab` или другие платформы хостинга git — все они могут использоваться в качестве репозиториев расширений.

## Быстрый старт

### Использование скаффолдинга

Gopeed предоставляет скаффолдинг для быстрого создания шаблона проекта разработки расширения:

```sh
npx create-gopeed-ext@latest
```

В процессе создания вы увидите следующие подсказки:

```sh
√ Project name (gopeed-extension-demo) ...
√ Choose a template » Webpack

Success! Created gopeed-extension-demo at D:\code\study\js\gopeed-extension-demo
Inside that directory, you can run several commands:

  git init
    Initialize git repository

  npm install
    Install dependencies

  npm run dev
    Compiles and hot-reloads for development.

  npm run build
    Compiles and minifies for production.

We suggest that you begin by typing:

  cd gopeed-extension-demo

Happy coding!
```

### Ручная настройка

Если вы не знакомы с инструментами `node.js`, вы также можете вручную создать проект со следующей структурой файлов:

```sh
├── index.js
├── manifest.json
```

## Локальная отладка

После создания проекта необходимо выполнить локальную отладку. Вы можете установить локальный проект расширения в Gopeed для отладки. Конкретные шаги:

1. Включите режим разработчика `Gopeed` — нажмите кнопку установки `5 раз подряд` на странице расширений, чтобы включить режим разработчика.



2. Нажмите кнопку и выберите директорию расширения в диалоге выбора для установки.

3. Если вы используете режим `webpack` в скаффолдинге, вы можете запустить автоматическую компиляцию через `npm run dev`.

4. Создайте задачу, чтобы увидеть, как расширение работает.



Видно, что пример расширения, созданный через скаффолдинг, может анализировать файл `example/index.html` при создании задачи с использованием ссылки `https://github.com/hello`.

> Примечание: Режим разработчика доступен только на десктопной платформе.

## Описание разработки

В предыдущем разделе мы смогли создать базовое расширение и отладить его локально, но что происходит под капотом?

Сначала давайте рассмотрим файл `manifest.json` — это манифест расширения, описывающий информацию о расширении. Каждый проект расширения должен содержать файл `manifest.json` в корневой директории. Пример файла в этом разделе:

```json
{
  "name": "gopeed-extention-demo",
  "author": "",
  "title": "gopeed extention demo title",
  "description": "gopeed extention demo description",
  "icon": "",
  "version": "1.0.0",
  "homepage": "",
  "repository": {
    "url": ""
  },
  "scripts": [
    {
      "event": "onResolve",
      "match": {
        "urls": ["*://github.com/*"]
      },
      "entry": "dist/index.js"
    }
  ],
  "settings": []
}
```

Теперь рассмотрим значение каждого поля:

- `name` и `author`: Gopeed использует `<author>@<name>` в качестве идентификатора расширения. Заполнив `author`, вы гарантируете, что расширение не будет случайно перезаписано другими расширениями, поэтому настоятельно рекомендуется заполнять поле `author`.
- `title` и `description`: Название и описание расширения.
- `icon`: Иконка расширения, укажите относительный путь, например: `icon.png`.
- `version`: Версия расширения, используется спецификация semver. При обновлении расширения сравнение происходит по этому полю, поэтому убедитесь, что номер версии соответствует спецификации.
- `homepage`: Домашняя страница расширения, например: `https://gopeed.com`.
- `repository`: Адрес git-репозитория, к которому принадлежит расширение. Расширения Gopeed используют `git` для децентрализованного управления расширениями. Поэтому, если вы хотите, чтобы пользователи могли устанавливать и обновлять ваше расширение, вы должны разместить исходный код в удалённом git-репозитории и настроить это поле.

  Например:

  ```json
  {
    "url": "https://github.com/gopeed/gopeed-extension-demo"
  }
  ```

  Если git-репозиторий содержит несколько проектов расширений, вы можете указать подкаталог через атрибут `directory`, например:

  ```json
  {
    "url": "https://github.com/GopeedLab/gopeed-extension-samples",
    "directory": "github-contributor-avatars-sample"
  }
  ```

  При установке в Gopeed необходимо использовать `#` в качестве разделителя, например: `https://github.com/GopeedLab/gopeed-extension-samples#github-contributor-avatars-sample`.

- `scripts`: `Обратите внимание!` Это конфигурация событий активации расширения Gopeed.

  Событие `onResolve`, настроенное в примере проекта, срабатывает при анализе задач. Поле `match.urls` используется для сопоставления URL-адреса, созданного задачей. При успешном совпадении будет выполнен файл скрипта, указанный в поле `entry`.

  > Правила сопоставления совпадают с правилами сопоставления расширений Chrome, подробнее см. [здесь](https://developer.chrome.com/docs/extensions/mv3/match_patterns/)

- `settings`: Настройки расширения. Через объявление конфигурации в Gopeed может быть сгенерирована соответствующая страница настроек для пользовательских параметров, таких как пользовательский `Cookie`, пользовательский `User-Agent` и т. д., например:

  ```json
  [
    {
      "name": "cookie",
      "title": "Website Cookie",
      "description": "Cookie can be obtained through browser developer tools",
      "type": "string"
    },
    {
      "name": "quality",
      "title": "Default Quality",
      "type": "number",
      "value": "1080",
      "options": [
        {
          "label": "1080P",
          "value": "1080"
        },
        {
          "label": "720P",
          "value": "720"
        },
        {
          "label": "480P",
          "value": "480"
        }
      ]
    }
  ]
  ```

  - `name`: Имя параметра, обязательно.
  - `title`: Заголовок параметра, обязательно.
  - `description`: Описание параметра, необязательно.
  - `type`: Тип параметра, допустимые значения: `string`, `number`, `boolean`.
  - `value`: Значение параметра по умолчанию, необязательно.

## Написание скриптов

В предыдущем разделе мы узнали, как настроить манифест, а теперь рассмотрим, как писать скрипты расширения.

### Среда выполнения

Скриптовый движок расширений Gopeed реализован на базе [goja](https://github.com/dop251/goja) — интерпретатора JavaScript, написанного на чистом Go. Однако, поскольку goja является только средой выполнения JS, API `browser` и `node.js` не поддерживаются. В настоящее время `Gopeed` реализует API `XMLHttpRequest` и `fetch`, что означает, что вы можете использовать эти два API или сторонние библиотеки на их основе для выполнения сетевых запросов, такие как `axios`, `superagent` и т. д.

Также следует отметить, что goja изначально поддерживает большую часть синтаксиса `es6+`, но некоторые конструкции не поддерживаются, например, `async generator`. Но это не проблема — проект, созданный через скаффолдинг, уже настроен с `babel`, поэтому вы можете свободно использовать новейший синтаксис ES, и скрипт в итоге будет скомпилирован в синтаксис `es5`.

### Описание демо-скрипта

Когда событие срабатывает, выполняется файл скрипта, указанный в поле `entry`. Скрипт из примера проекта выглядит следующим образом:

```js
gopeed.events.onResolve((ctx) => {
  ctx.res = {
    name: "example",
    files: [
      {
        name: "index.html",
        req: {
          url: "https://example.com",
        },
      },
    ],
  };
});
```

Рассмотрим содержимое скрипта:

- `gopeed.events.onResolve`: Регистрирует обработчик события `onResolve`, в котором resides логика расширения.
- `ctx`: Контекст события, содержащий информацию о текущем событии. В событии `onResolve` `ctx` содержит:
  - `req`: Информация о запросе, включая URL-адрес ресурса, заголовки и т. д.
  - `res`: Информация об ответе, скрипт должен присвоить список проанализированных файлов в `ctx.res`, и Gopeed выполнит загрузку в соответствии с возвращённым списком файлов.

Проще говоря, в функции обратного вызова `onResolve` необходимо проанализировать список файлов для загрузки на основе информации запроса из `ctx.req` и присвоить его в `ctx.res`.

> Подробнее о типах расширений и связанном исходном коде см. в [официальном репозитории Gopeed JS](https://github.com/GopeedLab/gopeed-js).

## Хранилище расширения

Gopeed предоставляет API для хранения, чтобы поддерживать постоянные данные расширения, например `токены входа`. Пример:

```js
gopeed.events.onResolve((ctx) => {
  // Получаем token; если его нет, выполняем вход
  const token = gopeed.storage.get("token");
  if (!token) {
    const token = await login();
    gopeed.storage.set("token", token);
  }

  // Затем делаем что-то с token
  // ...
});
```

> Примечание: Подробную информацию об API см. в [документации](https://docs.gopeed.com/site/reference/interfaces/gopeed.Storage.html).

## Отладка расширения

В скриптах можно использовать объект `gopeed.logger` для вывода логов. Он поддерживает уровни `debug`, `info`, `warn` и `error`. Пример:

```js
gopeed.logger.debug("debug");
gopeed.logger.info("info");
gopeed.logger.warn("warn");
gopeed.logger.error("error");
```

Файлы логов находятся в каталоге `logs` внутри каталога установки Gopeed, имя файла — `extension.log`. Для просмотра логов в реальном времени можно использовать `tail -f extension.log`.

> Примечание: Логи уровня `debug` работают только для расширений, установленных в режиме разработчика.

## Публикация расширения

После завершения разработки, если проект был создан через скаффолдинг и использует `webpack`, его нужно собрать:

```sh
npm run build
```

Затем нужно создать `удалённый репозиторий`. Например, если на `github` создан репозиторий `https://github.com/xxx/gopeed-extension-demo`, соответствующим образом обновите поле `repository` в `manifest.json`:

```json
{
  "repository": {
    "url": "https://github.com/xxx/gopeed-extension-demo"
  }
}
```

> Правильная настройка `repository` позволяет расширению получать удалённые обновления. Если расширение находится в подкаталоге внутри git-репозитория, можно указать подкаталог через атрибут `directory`, например:
>
> ```json
> {
>   "repository": {
>     "url": "https://github.com/xxx/gopeed-extension-demo",
>     "directory": "path"
>   }
> }
> ```

Также не забудьте корректно задать поля `author` и `name`, чтобы снизить риск совпадения имени с другими расширениями.

Затем отправьте проект в удалённый репозиторий, чтобы завершить публикацию. Чтобы пользователям было проще находить расширения Gopeed на `github`, рекомендуется использовать префикс `gopeed-extension-` в названии проекта, например `gopeed-extension-demo`, и помечать проект тегом `gopeed-extension` на `github`.

## Установка расширения

После публикации в удалённый репозиторий его можно установить в Gopeed. Откройте страницу расширений, введите HTTP-адрес `git clone` расширения (можно опустить суффикс `.git`) и нажмите кнопку `Установить`.

> Примечание: Если расширение находится в подкаталоге, добавьте к адресу `#`, а затем имя подкаталога, например `https://github.com/xxx/gopeed-extension-demo#path`.

## Официальные примеры

Gopeed предоставляет два показательных примера расширений для справки:

- [github-contributor-avatars-sample](https://github.com/GopeedLab/gopeed-extension-samples/tree/main/github-contributor-avatars-sample)

  Это расширение зависит от `node.js` и подходит для сложных сценариев. Оно использует библиотеку `cheerio` для разбора `DOM` страницы и получения списка файлов для загрузки.

- [github-release-sample](https://github.com/GopeedLab/gopeed-extension-samples/tree/main/github-release-sample)

  Это расширение представляет собой проект на `чистом JS` без зависимостей. Оно подходит для простых сценариев и использует `fetch` для сетевых запросов и получения списка файлов для загрузки.

---

## File: content/docs/ru/donate.mdx

---
title: Поддержка проекта
---

Спасибо, что рассматриваете возможность поддержки проекта Gopeed! Ваша помощь позволяет нам продолжать разработку и поддерживать наше программное обеспечение.

|                                 WeChat                                 |                              Alipay                              |
| :--------------------------------------------------------------------: | :--------------------------------------------------------------: |
|  |  |

### Криптовалюта

- **BTC**: 35jYkPN8bgkh7AWjt3B1VgMQHqtGYcvF6p
- **ETH:** 0x928a7fd2398c941Ac6713704e606Fa414595e3A0
- **Matic:** 0x928a7fd2398c941Ac6713704e606Fa414595e3A0
- **BNB:** 0x928a7fd2398c941Ac6713704e606Fa414595e3A0
- **USDT(ERC20)**: 0x928a7fd2398c941Ac6713704e606Fa414595e3A0

---

## File: content/docs/ru/index.mdx

---
title: Введение
---

Gopeed (полное название Go Speed) — это высокоскоростной менеджер загрузок, разработанный на `Golang` + `Flutter`, который поддерживает загрузку по протоколам `HTTP`, `BitTorrent`, `Magnet` и `ed2k`, а также работает на всех платформах, включая:

- [x] **Windows**
- [x] **Macos**
- [x] **Linux**
- [x] **Android**
- [x] **iOS**
- [x] **Web**
- [x] **Docker**
- [x] **Командная строка**

## Возможности

Как современный менеджер загрузок, Gopeed обладает множеством возможностей. Ниже приведено краткое описание.

### Основные

- Поддержка HTTP и HTTPS
- Поддержка BitTorrent, Magnet и ed2k
- Seed, DHT, PEX, uTP, Webtorrent, Upnp
- Автоматическое ежедневное обновление списка трекеров
- Интернационализация
- Тёмная тема

### Расширенные

Помимо базовых функций загрузки, существует множество расширенных возможностей, которые делают Gopeed более гибким.

- **Открытый HTTP API**

  Через RESTful API вы можете легко взаимодействовать с Gopeed, например, управлять загрузками, паузой, удалением и т. д. через API.

- **Децентрализованные расширения**

  Вы можете писать расширения на `JavaScript` для расширения возможностей загрузки Gopeed, например, загружать видео с веб-сайтов или скачивать музыку и т. д.

## Почему не...?

Ниже приведено сравнение с популярными менеджерами загрузок на рынке, которое наглядно демонстрирует преимущества Gopeed.

| Функция                | Gopeed | Motrix                    | IDM              |
| ---------------------- | ------ | ------------------------- | ---------------- |
| HTTP                   | ✔️     | ✔️                        | ✔️               |
| BitTorrent             | ✔️     | ✔️                        | ❌               |
| Magnet                 | ✔️     | ✔️                        | ❌               |
| Кроссплатформенность   | ✔️     | ❌ (только десктоп)       | ❌ (только Windows) |
| Бесплатный             | ✔️     | ✔️                        | ❌               |
| Открытый исходный код  | ✔️     | ✔️                        | ❌               |
| Не на Electron         | ✔️     | ❌                        | ✔️               |
| Открытый API           | ✔️     | ✔️                        | ❌               |
| Поддержка расширений   | ✔️     | ❌                        | ❌               |

Конечно, у Gopeed может быть много недостатков, но мы будем продолжать его совершенствовать.

Кроме того, Gopeed имеет открытый исходный код — вы можете в любое время предлагать свои идеи или напрямую вносить вклад в код, чтобы сделать Gopeed лучше.

---

## File: content/docs/ru/install.mdx

---
title: Инструкция по установке
---

Следующие способы подходят для быстрой загрузки Gopeed на всех платформах:

1. Перейдите на [официальный сайт](https://gopeed.com) для загрузки — версия будет автоматически выбрана в соответствии с вашей операционной системой.
2. Перейдите на [GitHub](https://github.com/GopeedLab/gopeed/releases) для загрузки — вы можете самостоятельно выбрать нужную версию.

## Руководство по установке для конкретных платформ

### Windows

Для Windows доступно два дистрибутива: портативная версия и версия с установщиком. Портативная версия не требует установки — достаточно распаковать архив и запустить. Версия с установщиком требует установки, процесс такой же, как и для другого программного обеспечения. Вы можете выбрать подходящий вариант.

> Имя файла портативной версии: Gopeed-v1.x.x-windows-amd64-portable.zip

Помимо прямой загрузки, вы также можете установить или обновить Gopeed через пакетные менеджеры:

- [Scoop](https://github.com/ScoopInstaller/Scoop): Менеджер пакетов командной строки для Windows, поддерживаемый сообществом. Лёгкий и гибкий, не требует прав администратора для установки, упрощает управление и обновление программного обеспечения.

  ```powershell
  scoop bucket add extras
  scoop install extras/gopeed
  ```

- [Winget](https://learn.microsoft.com/ru-ru/windows/package-manager/winget): Официальный пакетный менеджер от Microsoft, глубоко интегрированный в операционную систему Windows.

  ```powershell
  winget install -e --id monkeyWie.Gopeed
  ```

#### Ложное срабатывание брандмауэра

В системе Windows некоторые антивирусные программы могут ложно обнаруживать два основных компонента Gopeed: `host.exe` для связи с расширениями браузера и `updater.exe` для обновления приложения. Чтобы обеспечить корректную работу расширения браузера по перехвату задач загрузки и автоматическое обновление приложения, добавьте `директорию установки Gopeed` в белый список вашего брандмауэра или антивирусного ПО.

<Callout type="info">
**Безопасная загрузка**: Обязательно загружайте Gopeed способами, описанными в этом документе — с [официального сайта](https://gopeed.com), из [официального репозитория GitHub](https://github.com/GopeedLab/gopeed/releases) или через Scoop/Winget. Избегайте использования сторонних источников для обеспечения безопасности программного обеспечения.

**О ложных срабатываниях**: Это может быть связано с особенностями приложений, скомпилированных на языке Go, и в настоящее время нет хорошего решения. В будущем мы рассмотрим возможность миграции компонентов на разработку на Rust для решения этой проблемы.

</Callout>

### Linux

В системе Linux мы предоставляем пакеты `.deb` и `.AppImage` для установки — вы можете выбрать подходящий вариант. Кроме того, вы можете быстро установить с помощью следующих команд:

- Flatpak

  ```sh
  flatpak install flathub com.gopeed.Gopeed
  ```

- Snap

  ```sh
  sudo snap install gopeed
  ```

### macOS

Версия для macOS предоставляет файл `.dmg`, который можно установить двойным щелчком. Установочный пакет поддерживает две архитектуры: `intel` и `apple silicon`.

> Совет: Если приложение не открывается в macOS, выполните команду `xattr -d com.apple.quarantine /Applications/Gopeed.app` в терминале

### Android

Версия для Android предоставляет файл `.apk`, который можно загрузить и установить напрямую, поддерживает все архитектуры процессоров.

### iOS

В настоящее время для платформы iOS предоставляется только файл `.ipa`, который необходимо подписать и установить самостоятельно. Рекомендуется использовать [TrollStore](https://github.com/opa334/TrollStore) для установки.

> Почему нет в App Store?
>
> Из-за механизма проверки Apple, приложения, связанные с протоколом BitTorrent, не допускаются к публикации.
>
> Почему нет в TestFlight?
>
> Потому что нет денег! Проект существует исключительно на энтузиазме. Если будет получено достаточно спонсорской помощи, он будет немедленно размещён в TestFlight. Поэтому, пожалуйста, поддержите нас. Открытый исходный код — это непросто. Спасибо!

### Web

Если вам нужна служба удалённых загрузок, вы можете использовать веб-версию. Gopeed предоставляет веб-версии для различных платформ. Вы можете загрузить нужную версию в зависимости от вашей системы и архитектуры процессора.



Ниже приведён пример использования веб-версии на платформе Windows, на других платформах использование аналогично.

1. Загрузите веб-версию, после распаковки вы получите папку. Поместите её в удобное для вас место.
2. Откройте терминал в корневой директории папки и выполните `./gopeed.exe`. При успешном запуске вы увидите следующий вывод:

   ```bash
      _______   ______   .______    _______  _______  _______
    /  _____| /  __  \  |   _  \  |   ____||   ____||       \
    |  |  __  |  |  |  | |  |_)  | |  |__   |  |__   |  .--.  |
    |  | |_ | |  |  |  | |   ___/  |   __|  |   __|  |  |  |  |
    |  |__| | |  `--'  | |  |      |  |____ |  |____ |  '--'  |
    \______|  \______/  | _|      |_______||_______||_______/

    Server start success on http://[::]:9999
   ```

3. Откройте браузер и перейдите по адресу `http://localhost:9999`.

#### Конфигурация веб-версии

Веб-версия поддерживает конфигурацию через параметры командной строки или файл конфигурации. Параметры командной строки можно просмотреть через `./gopeed.exe -h`:

```sh
$ ./gopeed.exe -h
Usage of C:\Users\levi\Downloads\gopeed-web-v1.3.13-windows-amd64\gopeed.exe:
  -A string
        Bind Address (default "0.0.0.0")
  -P int
        Bind Port (default 9999)
  -T string
        API token, that can only be used when basic authentication is enabled.
  -c string
        Config file path (default "./config.json")
  -d string
        Storage directory
  -p string
        HTTP Basic Auth Password
  -u string
        HTTP Basic Auth Username (default "gopeed")
```

Также поддерживается конфигурация через файл конфигурации. Создайте файл `config.json` в корневой директории со следующим содержимым:

```json
{
  "address": "",
  "port": 0,
  "username": "",
  "password": "",
  "apiToken": "",
  "storageDir": "",
  "whiteDownloadDirs": ["/root/downloads", "/root/dir/*", "/root/dir?abc"]
}
```

Также поддерживается конфигурация через переменные окружения, по правилу `GOPEED_ConfigKey`, например:

```sh
export GOPEED_ADDRESS="0.0.0.0"
export GOPEED_PORT="9999"
export GOPEED_USERNAME="gopeed"
export GOPEED_PASSWORD="xxx"
export GOPEED_APITOKEN=""
export GOPEED_STORAGEDIR=""
export GOPEED_WHITEDOWNLOADDIRS="/root/downloads,/root/dir/*,/root/dir?abc"
```

<Callout type="warn">
  Если вы развёртываете на публичном IP-адресе, обязательно включите аутентификацию,
  иначе возникнут риски безопасности.
</Callout>

#### Конфигурация загрузки по умолчанию

Если вам нужно настроить конфигурацию загрузки по умолчанию при первом запуске сервера, вы можете добавить поле `downloadConfig` в `config.json`. Подробнее о конфигурации см. в [DownloaderStoreConfig](https://pkg.go.dev/github.com/GopeedLab/gopeed/pkg/base#DownloaderStoreConfig). Пример:

```json
{
  "address": "127.0.0.1",
  "port": 9999,
  "downloadConfig": {
    "downloadDir": "d:/test"
  }
}
```

### Docker

Одна команда:

```sh
docker run --name gopeed -d -p 9999:9999 liwei2633/gopeed
```

Монтирование директории загрузок

```sh
docker run --name gopeed -d -p 9999:9999 \
    -v /path/to/download:/app/Downloads \
    liwei2633/gopeed
```

Монтирование директории данных

```sh
docker run --name gopeed -d -p 9999:9999 \
    -v /path/to/download:/app/Downloads \
    -v /path/to/storage:/app/storage liwei2633/gopeed
```

Указание ID группы и пользователя контейнера

```sh
docker run --name gopeed -d -p 9999:9999 \
    -e PGID=100 \
    -e PUID=1000 \
    liwei2633/gopeed
```

Если вам нужно включить аутентификацию, можно передать переменные окружения:

```sh
docker run --name gopeed -d -p 9999:9999 \
    -e GOPEED_USERNAME="admin" \
    -e GOPEED_PASSWORD="123" \
    -v /path/to/download:/app/Downloads \
    -v /path/to/storage:/app/storage \
    liwei2633/gopeed
```

### Командная строка

Для версии командной строки требуется среда `Golang`. Если у вас не установлена среда `Golang`, обратитесь к [инструкции по установке](https://golang.org/doc/install).

Команда установки:

```sh
go install github.com/GopeedLab/gopeed/cmd/gopeed@latest
```

После установки вы можете использовать команду `gopeed` для загрузок. Подробнее об использовании можно узнать через `gopeed -h`:

```sh
$ gopeed -h
Usage of gopeed:
  -C int
        Concurrent connections. (default 16)
  -D string
        Store directory. (default "C:\\Users\\levi")
```

#### Примеры использования командной строки

Загрузка HTTP-ресурса:

```sh
gopeed https://example.com/file.zip
```

Загрузка торрент-файла:

```sh
gopeed D:/Downloads/file.torrent
```

Загрузка magnet-ссылки:

```sh
gopeed magnet:?xt=urn:btih:xxxx
```

Загрузка ed2k-ссылки:

```sh
gopeed 'ed2k://|file|example.iso|123456789|0123456789ABCDEF0123456789ABCDEF|/'
```

---

## File: content/docs/ru/scheme.mdx

---
title: Протокол Scheme
---

Gopeed регистрирует пользовательский протокол `gopeed:`, позволяя запускать Gopeed напрямую из браузера, другого приложения или командной строки для выполнения действий.

## Формат URI

```
gopeed:///create?params=<base64-encoded JSON>
gopeed:///extension?params=<base64-encoded JSON>
```

- ``: Тип действия, в настоящее время поддерживается `/create` и `/extension`
- `params`: JSON-параметры в кодировке Base64

## Создание задачи загрузки

Путь: `/create`

### Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `req.url` | string | URL загрузки (HTTP, magnet, ed2k и т. д.) |

Полная структура параметров соответствует телу запроса API создания задачи. Подробнее см. в [документации API создания задач](https://gopeed.com/docs/openapi#tag/tasks/POST/api/v1/tasks).

### Пример

JSON параметров:

```json
{
  "req": {
    "url": "https://example.com/file.zip"
  }
}
```

Сгенерированный URI:

<SchemeUriBlock uri="gopeed:///create?params=eyJyZXEiOnsidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9maWxlLnppcCJ9fQ==" />

## Установка расширения

Путь: `/extension`

### Параметры

| Поле | Тип | Описание |
| --- | --- | --- |
| `url` | string | URL git-репозитория расширения |
| `devMode` | boolean | Установка в режиме разработчика, по умолчанию `false` |

### Пример

JSON параметров:

```json
{
  "url": "https://github.com/user/gopeed-extension-example",
  "devMode": false
}
```

Сгенерированный URI:

<SchemeUriBlock uri="gopeed:///extension?params=eyJ1cmwiOiJodHRwczovL2dpdGh1Yi5jb20vdXNlci9nb3BlZWQtZXh0ZW5zaW9uLWV4YW1wbGUiLCJkZXZNb2RlIjpmYWxzZX0=" />

## Конструктор URI

Используйте инструмент ниже для динамической генерации полного URI `gopeed:` на основе параметров:

<SchemeUriBuilder />

## Перехват загрузок на Android

На Android Gopeed регистрирует стандартный Intent Filter для обработки загрузок. После установки, когда вы нажимаете на ссылку загрузки в браузере или другом приложении, система покажет диалог выбора приложения, в котором вы сможете выбрать Gopeed для обработки загрузки.

Поддерживаемые сценарии:

- Выбор Gopeed, когда браузер показывает диалог загрузки
- Выбор Gopeed при передаче HTTP/HTTPS ссылок из других приложений
- Установка Gopeed в качестве обработчика загрузок по умолчанию в настройках приложений Android по умолчанию

<Callout type="info">
  После установки новой версии Android может потребоваться повторное сканирование приложений для распознавания новых Intent Filters. Попробуйте очистить кеш приложения, перезагрузить устройство или сбросить настройки приложений по умолчанию в системных настройках.
</Callout>

---

## File: content/docs/ru/script.mdx

---
title: Выполнение скриптов
---

Gopeed поддерживает автоматическое выполнение указанных скриптов-перехватчиков при **успешном завершении** задачи загрузки. Используйте эту функцию для автоматического перемещения файлов, отправки уведомлений, запуска транскодирования и многого другого.

## Как включить

1. Откройте клиент Gopeed
2. Перейдите в **Настройки** → **Дополнительно** → **Разработчик**
3. Найдите раздел **Выполнение скриптов** и включите переключатель
4. Добавьте полный путь к файлу скрипта

## Поддерживаемые типы скриптов

Gopeed автоматически выбирает интерпретатор на основе расширения файла:

| Расширение | Интерпретатор | Платформа |
| --- | --- | --- |
| `.sh` / `.bash` | Bash | macOS / Linux |
| `.py` | Python 3 | Все платформы |
| `.js` | Node.js | Все платформы |
| `.bat` / `.cmd` | cmd.exe | Только Windows |
| `.ps1` | PowerShell | Все платформы |
| Без расширения | Прямое выполнение (требуется shebang или права на выполнение) | macOS / Linux |

## Переменные окружения

Скрипты получают следующие переменные окружения при выполнении:

| Переменная | Описание | Пример |
| --- | --- | --- |
| `GOPEED_EVENT` | Тип события | `DOWNLOAD_DONE` |
| `GOPEED_TASK_ID` | Уникальный идентификатор задачи | `abc123-def456` |
| `GOPEED_TASK_NAME` | Отображаемое имя задачи | `ubuntu-24.04.iso` |
| `GOPEED_TASK_STATUS` | Статус задачи | `done` |
| `GOPEED_TASK_PATH` | Полный путь к загруженному файлу или папке | `/downloads/ubuntu-24.04.iso` |

`GOPEED_TASK_PATH` адаптируется к типу задачи:
- **Задачи с одним файлом**: Указывает путь к загруженному файлу
- **Задачи с несколькими файлами**: Указывает путь к загруженной папке

## Примеры скриптов

### Автоматическое перемещение файлов в определённую директорию

```bash
#!/bin/bash
# move_to_hdd.sh - Автоматическое перемещение с SSD на HDD после загрузки
DEST="/data/hdd/downloads/"
mkdir -p "$DEST"
mv "$GOPEED_TASK_PATH" "$DEST"
echo "Moved $GOPEED_TASK_NAME to $DEST"
```

### Отправка уведомления о завершении загрузки

```python
#!/usr/bin/env python3
# notify.py - Отправка уведомления после завершения загрузки
import os
import urllib.request
import json

task_name = os.environ.get("GOPEED_TASK_NAME", "Unknown")
task_path = os.environ.get("GOPEED_TASK_PATH", "")

# Замените на URL вашего сервиса уведомлений
notify_url = "https://your-notify-service.com/api/send"
data = json.dumps({
    "title": "Download Complete",
    "body": f"{task_name}\nPath: {task_path}"
}).encode()

req = urllib.request.Request(notify_url, data=data, headers={"Content-Type": "application/json"})
urllib.request.urlopen(req)
```

## Примечания

- Скрипты запускаются только при **успешных** загрузках; при неудачных загрузках скрипты не выполняются
- Можно настроить несколько путей к скриптам, и они будут выполняться по порядку
- Убедитесь, что файлы скриптов имеют соответствующие права на выполнение (используйте `chmod +x` на macOS/Linux)

---

## File: content/docs/ru/webhook.mdx

---
title: Webhook
---

Gopeed поддерживает настройку вебхуков, автоматически отправляя HTTP POST запросы на указанный URL при завершении или ошибке задачи загрузки. Эта функция интегрируется с такими сервисами уведомлений, как Gotify, Bark, WeCom, DingTalk и Telegram Bot, чтобы вы были в курсе статуса загрузок в реальном времени.

## Как включить

1. Откройте клиент Gopeed
2. Перейдите в **Настройки** → **Дополнительно** → **Разработчик**
3. Найдите раздел **Webhook** и нажмите, чтобы добавить URL
4. Введите HTTP-адрес для получения уведомлений и нажмите подтвердить

## Формат отправки

Вебхуки используют HTTP POST запросы с `Content-Type: application/json`. Структура тела запроса:

```json
{
  "event": "DOWNLOAD_DONE",
  "time": 1712000000000,
  "payload": {
    "task": {
      "id": "task-uuid",
      "protocol": "http",
      "meta": {
        "req": {
          "url": "https://example.com/file.zip"
        },
        "opts": {
          "name": "file.zip",
          "path": "/downloads"
        },
        "res": {
          "size": 104857600,
          "files": [
            { "name": "file.zip", "size": 104857600 }
          ]
        }
      }
    }
  }
}
```

### Типы событий

| Событие | Описание |
| --- | --- |
| `DOWNLOAD_DONE` | Задача загрузки завершена |
| `DOWNLOAD_ERROR` | Ошибка задачи загрузки |

## Тестирование вебхука

При добавлении URL вебхука вы можете нажать кнопку **Тест**. Gopeed отправит смоделированное событие `DOWNLOAD_DONE` на указанный URL. Тест считается успешным только тогда, когда сервер возвращает HTTP 200.

## Поддержка нескольких URL

Вы можете настроить несколько URL вебхуков. События загрузки будут отправлены на все настроенные адреса одновременно, что упрощает интеграцию с несколькими каналами уведомлений.

## Типичные сценарии использования

- **Push-уведомления**: Интеграция с собственными сервисами push-уведомлений, такими как Gotify, Bark или Pushover
- **Мессенджеры**: Отправка уведомлений о загрузках через вебхуки WeCom/DingTalk/Telegram Bot
- **Автоматизация**: Запуск последующих задач, таких как распаковка, транскодирование или архивирование

---

## File: content/docs/zh/dev.mdx

---
title: 指南
---

Gopeed 目前提供两种方式对外进行扩展，一种是通过对接 HTTP API，另一种是通过`JavaScript`脚本开发扩展进行增强。

## API 对接

请参考 [API 对接文档](dev-api)

## 扩展开发

请参考 [扩展开发文档](dev-extension)

---

## File: content/docs/zh/dev-api.mdx

---
title: API 对接
---

Gopeed 对外提供了 HTTP API 接口，可以通过 API 进行下载管理。

## 启用接口

首先需要设置通讯协议为 TCP，通过**设置 -> 高级 -> 通讯协议**，将通讯协议设置为 TCP，并设置 IP 和端口，如下图所示：



<Callout type="info">
  可以设置任意`端口`，但是需要注意不要使用被占用的或者系统保留的端口号，不然可能会导致访问失败。
</Callout>

这样就可以通过`http://127.0.0.1:9999`访问 API 了，但是出于安全考虑，建议设置一个令牌，通过**设置 -> 高级 -> 接口令牌**，设置一个令牌，如下图所示：



> 注：以上设置需要重启后生效。

## 使用 JS SDK

Gopeed 提供了官方的 js 库，首先需要安装`@gopeed/rest`库：

```
npm install @gopeed/rest
```

然后就可以愉快的使用了，示例：

```js
import { Client } from "@gopeed/rest";

(async function () {
  // 创建客户端
  const client = new Client();
  // 调用API创建任务
  const res = await client.createTask({
    req: {
      url: "https://example.com/file.zip",
    },
  });
})();
```

更多使用方法、源码与包更新请参考[官方 Gopeed JS 仓库](https://github.com/GopeedLab/gopeed-js)。

## 使用 Python SDK

来着社区用户 [@tick97115115](https://github.com/tick97115115) 提供的 Python SDK.

```bash
pip install gospeed_api
```

- Github：https://github.com/tick97115115/gospeed_api
- 示例：https://github.com/tick97115115/gospeed_api/blob/main/tests/test_index.py

## 使用 HTTP 请求

当然也可以直接通过 HTTP 请求来调用 API，具体请参考 [接口文档](/docs/openapi)。

---

## File: content/docs/zh/dev-extension.mdx

---
title: 扩展开发
---

Gopeed 支持使用`JavaScript`进行扩展开发，扩展可以增强 Gopeed 的功能，比如下载某个网站的视频，或者下载某个网站的音乐等等，可以通过[官方示例](https://github.com/GopeedLab/gopeed-extension-samples/blob/main/README_zh-CN.md)快速了解一下。

Gopeed 扩展基于`git`来实现去中心化的扩展管理，只要将扩展源码托管到远程 git 仓库中，就可以通过 Gopeed 进行安装和更新，所以无论是`github`、`gitee`、`gitlab`还是其它 git 托管平台，都可以作为扩展的托管仓库。

## 快速开始

### 使用脚手架搭建

Gopeed 提供了脚手架来帮助你快速创建一个扩展开发项目模版：

```sh
npx create-gopeed-ext@latest
```

在创建过程中，将会看到以下提示：

```sh
√ Project name (gopeed-extension-demo) ...
√ Choose a template » Webpack

Success! Created gopeed-extension-demo at D:\code\study\js\gopeed-extension-demo
Inside that directory, you can run several commands:

  git init
    Initialize git repository

  npm install
    Install dependencies

  npm run dev
    Compiles and hot-reloads for development.

  npm run build
    Compiles and minifies for production.

We suggest that you begin by typing:

  cd gopeed-extension-demo

Happy coding!
```

### 手动搭建

如果你对`node.js`周边工具不太熟悉，也可以手动创建一个项目，文件结构如下：

```sh
├── index.js
├── manifest.json
```

## 本地调试

在项目搭建好之后，需要进行本地调试，可以将本地的扩展项目安装到 Gopeed 中进行调试，具体步骤如下：

1. 开启 `Gopeed` 开发者模式，在扩展页面`连续点击 5 次`安装按钮，即可开启开发者模式。



2. 点击按钮在目录选择器中选择扩展目录，进行安装。

3. 如果使用脚手架中`webpack`模式，可以通过`npm run dev`启动自动编译。

4. 创建任务即可看到扩展生效了。



可以看到通过脚手架创建的示例扩展，可以实现使用`https://github.com/hello`链接创建任务时，解析出一个`example/index.html`文件

> 注：开发者模式只在桌面平台有效。

## 开发解析

上一节中，已经能够创建一个基础的扩展并进行本地调试了，但是在面纱之下，它究竟是怎么运作的呢？

首先我们来看一下`manifest.json`文件，这个是扩展的清单文件，它描述了扩展的信息，每个扩展项目根目录中必须包含一个`manifest.json`文件，本节中的示例文件如下：

```json
{
  "name": "gopeed-extention-demo",
  "author": "",
  "title": "gopeed extention demo title",
  "description": "gopeed extention demo description",
  "icon": "",
  "version": "1.0.0",
  "homepage": "",
  "repository": {
    "url": ""
  },
  "scripts": [
    {
      "event": "onResolve",
      "match": {
        "urls": ["*://github.com/*"]
      },
      "entry": "dist/index.js"
    }
  ],
  "settings": []
}
```

接下来逐一介绍一下各个字段的含义：

- `name`和`author`：Gopeed 中会使用`<author>@<name>`作为扩展的 ID，填写`author`后能确保不容易和别的扩展重名导致被覆盖安装，所以强烈建议填写`author`字段。
- `title`和`description`：扩展的标题和描述。
- `icon`：扩展图标，填写相对路径，示例：`icon.png`。
- `version`：扩展版本，使用 semver 规范，扩展更新时是基于此字段进行比较的，所以请确保版本号是符合规范的。
- `homepage`：扩展主页，示例：`https://gopeed.com`。
- `repository`：扩展所属 git 仓库地址，Gopeed 扩展依赖`git`来实现去中心化的扩展管理，所以如果你的扩展需要被用户安装和更新，那么就必须将扩展源码托管到远程 git 仓库中，并配置此字段

  示例：

  ```json
  {
    "url": "https://github.com/gopeed/gopeed-extension-demo"
  }
  ```

  如果一个 git 仓库中包含多个扩展项目的话，可以通过`directory`属性指定子目录，示例：

  ```json
  {
    "url": "https://github.com/GopeedLab/gopeed-extension-samples",
    "directory": "github-contributor-avatars-sample"
  }
  ```

  在 Gopeed 安装时，需要通过`#`进行分割，即安装链接为`https://github.com/GopeedLab/gopeed-extension-samples#github-contributor-avatars-sample`。

- `scripts`：`敲重点！`这里是 Gopeed 扩展激活事件的配置。

  示例项目中配置的`onResolve`事件会在解析任务时触发，通过`match.urls`字段来匹配任务创建的 url，如果匹配成功，则会运行`entry`字段指定的脚本文件。

  > 匹配规则和 chrome 扩展的匹配规则一致，可以参考[这里](https://developer.chrome.com/docs/extensions/mv3/match_patterns/)

- `settings`：扩展设置项，通过配置声明可以在 Gopeed 中生成对应的设置界面，提供用户自定义设置，例如自定义`Cookie`、自定义`User-Agent`等等，示例：

  ```json
  [
    {
      "name": "ua",
      "title": "User-Agent",
      "description": "自定义 User-Agent",
      "type": "string",
      "value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko)"
    }
  ]
  ```

  - `name`：设置项名称，必填。
  - `title`：设置项标题，必填。
  - `description`：设置项描述，可选。
  - `type`：设置项类型，可选值：`string`、`number`、`boolean`。
  - `value`：设置项默认值，可选。

## 脚本编写

上一节中，我们已经知道了如何配置清单，接下来就来介绍下扩展脚本的编写。

### 运行环境

Gopeed 扩展脚本引擎是由[goja](https://github.com/dop251/goja)来实现的，它是一个纯 Go 编写的 JavaScript 解释器，但是由于 goja 只是一个纯 js 运行时，所以`浏览器`和`node.js`的 API 都是不支持的，目前`Gopeed`实现了`XMLHttpRequest`、`fetch`两个 API，意味着你可以通过这两个 API 或者基于它们的第三方库来实现网络请求，比如`axios`、`superagent`等等。

另外需要注意一点的是，goja 原生支持大部分`es6+`的语法，但是极少部分语法是不支持的，比如`async generator`，但是没关系，通过脚手架创建的项目中已经配置好了`babel`，你可以愉快的使用最新的 es 语法，脚本最终会被编译成`es5`语法。

### 示例脚本解析

每当事件触发时，会运行`entry`字段指定的脚本文件，示例项目中的脚本文件如下：

```js
gopeed.events.onResolve((ctx) => {
  ctx.res = {
    name: "example",
    files: [
      {
        name: "index.html",
        req: {
          url: "https://example.com",
        },
      },
    ],
  };
});
```

接下来，我们逐一介绍一下脚本的内容：

- `gopeed.events.onResolve`：这里是注册`onResolve`事件，方法里面就是扩展的具体逻辑了。
- `ctx`：事件上下文，包含了当前事件的一些信息，在`onResolve`事件中，`ctx`包含了以下字段：
  - `req`：请求信息，包含了资源的 url、headers 等等。
  - `res`：响应信息，脚本需要将解析出的文件列表赋值给`ctx.res`，Gopeed 会根据里面返回的文件列表进行下载。

简而言之就是需要在`onResolve`回调函数中，根据`ctx.req`里的请求信息，解析出需要下载的文件列表赋值给`ctx.res`即可。

> 关于`ctx`相关类型定义与扩展源码，可以参考[官方 Gopeed JS 仓库](https://github.com/GopeedLab/gopeed-js)。

## 扩展存储

Gopeed 提供了一套存储 API，以支持扩展持久化存储数据，例如`登录token`等等，示例：

```js
gopeed.events.onResolve((ctx) => {
  // 获取 token，如果不存在则登录
  const token = gopeed.storage.get("token");
  if (!token) {
    const token = await login();
    gopeed.storage.set("token", token);
  }

  // 然后使用 token 做一些事情
  // ...
});
```

> 注：详细的 API 可以参考[文档](https://docs.gopeed.com/site/reference/interfaces/gopeed.Storage.html)。

## 扩展调试

在脚本中可以通过`gopeed.logger`对象进行日志输出，支持`debug`、`info`、`warn`、`error`三种级别，示例：

```js
gopeed.logger.debug("debug");
gopeed.logger.info("info");
gopeed.logger.warn("warn");
gopeed.logger.error("error");
```

日志文件在 Gopeed 安装目录里的`logs`目录下，文件名称为`extension.log`，可以通过`tail -f extension.log`命令实时查看日志。

> 注：debug 级别的日志仅在开发者模式安装的扩展中生效。

## 扩展发布

扩展开发完成后，如果是脚手架创建的`webpack`工程，需要编译一下：

```sh
npm run build
```

然后我们要创建一个`远程仓库`，例如在`github`上创建了一个`https://github.com/xxx/gopeed-extension-demo`仓库，然后对应的修改一下`manifest.json`中的`repository`字段：

```json
{
  "repository": {
    "url": "https://github.com/xxx/gopeed-extension-demo"
  }
}
```

> 正确的配置`repository`，可以让扩展获得远程更新的功能，如果扩展属于 git 仓库下的一个子目录，可以通过`directory`属性指定子目录，示例：
>
> ```json
> {
>   "repository": {
>     "url": "https://github.com/xxx/gopeed-extension-demo",
>     "directory": "path"
>   }
> }
> ```

这里还要记得配置好扩展的`author`和`name`字段，以降低和其它扩展重名的风险。

然后将项目推送到远程仓库即可完成发布，为了让用户更方便的在`github`检索 Gopeed 扩展，建议项目名字统一以`gopeed-extension-`开头，例如`gopeed-extension-demo`，并且在`github`中为项目打上`gopeed-extension`标签。

## 扩展安装

发布到远端仓库之后，就可以在 Gopeed 中安装了，打开扩展页面，输入扩展的 HTTP 协议的`git clone`地址(可以省略掉后面的`.git`后缀)，点击`安装`按钮即可进行安装。

> 注：如果扩展目录是一个子目录，需要在地址后面加上`#`，再加上子目录名称，例如`https://github.com/xxx/gopeed-extension-demo#path`。

## 官方示例

官方提供了两个具有代表性的示例扩展供参考，分别是：

- [github-contributor-avatars-sample](https://github.com/GopeedLab/gopeed-extension-samples/tree/main/github-contributor-avatars-sample)

  此扩展是依赖于`node.js`的项目，适用于复杂需求开发，通过`cheerio`库解析网页`DOM`，来获取需要下载的文件列表。

- [github-release-sample](https://github.com/GopeedLab/gopeed-extension-samples/tree/main/github-release-sample)

  此扩展是`纯js`项目，无任何依赖，适用于简单需求开发，通过`fetch`实现网络请求，来获取需要下载的文件列表。