# 附录二：Forward Widget 开发者支持

本章节将介绍由第三方开发者开发的的开发工具库 [`@forward-widget/libs`](https://www.npmjs.com/package/@forward-widget/libs)，帮助你高效开发、测试和调试属于自己的模块。

***

### 🚀 工具库简介

`@forward-widget/libs` 是一个专为 Forward Widget 开发者设计的工具库，具备以下特性：

* 提供类型定义（支持 TypeScript 和 JSDoc）
* 提供 `WidgetAdaptor` 用于模拟运行环境
* 支持 TMDB 接口测试
* 适配 `@rstest/core` 单元测试框架

***

### 🛠️ 类型定义支持

#### TypeScript 项目

在项目中创建 `.d.ts` 文件，添加以下引用：

```ts
ts复制编辑// forward-widget-env.d.ts
/// <reference types="@forward-widget/libs/env" />
```

即可获得类型提示与补全，例如：

```ts
ts复制编辑const metadata: WidgetMetadata = {
  name: "My Widget",
  version: "1.0.0",
};
```

#### JavaScript 项目（使用 JSDoc）

若使用 JS 编写模块，可通过 JSDoc 获取类型提示：

```js
js复制编辑/**
 * @type {import('@forward-widget/libs/env').WidgetMetadata}
 */
const WidgetMetadata = {
  name: "My Widget",
  version: "1.0.0",
};
```

***

### 🧪 单元测试支持

通过 `WidgetAdaptor` 可模拟 Forward Widget 的运行环境。

搭配 `@rstest/core` 使用示例：

```ts
ts复制编辑import { expect, test, beforeAll } from "@rstest/core";

beforeAll(async () => {
  const { WidgetAdaptor } = await import("@forward-widget/libs/widget-adaptor");
  rstest.stubGlobal("Widget", WidgetAdaptor);
});

test("测试 HTTP 请求", async () => {
  const response = await Widget.http.get("https://api.example.com/data");
  expect(response.status).toBe(200);
});
```

***

### 🎞️ 使用 TMDB 接口（可选）

若你的模块需要调用 TMDB（电影数据库）接口，需配置环境变量：

#### .env 文件中添加：

```env
env复制编辑TMDB_API_KEY=your_tmdb_key_here
```

#### 在测试配置中启用环境：

```ts
ts复制编辑// rstest.config.ts
import { defineConfig } from "@rstest/core";

export default defineConfig({
  testEnvironment: "node",
  pool: {
    type: "forks",
    execArgv: ["--env-file=.env"],
  },
});
```

***

### 模块加密工具

近期有部分 Widget 作者反馈，在 GitHub 上保存模块时，出现了 **仓库被删除或账号被封禁** 的情况。具体原因不明。

为避免类似情况带来的风险，Forward 提供了一个 **模块加密工具**。\
开发者可以在发布或备份模块时，对模块文件进行加密处理。

> 加密为 **可选功能**，未加密的模块仍然可以正常使用。

目前 **最新版 TestFlight** 已支持 **导入加密模块**。

***

## 使用方式

模块加密工具目前提供三种使用方式：

### 1 在线工具

最简单的方式是使用在线加密工具。

打开以下页面，将模块文件拖入即可完成加密：

<https://flux.inch.red/encrypt>

***

### 2 命令行方式

如果你希望在自动化流程或脚本中使用，可以通过命令行调用接口进行加密：

```bash
curl -s -X POST https://widgetencrypt.inchmade.ai --data-binary @<filepath> -o <filepath>
```

说明：

| 参数           | 说明          |
| ------------ | ----------- |
| `<filepath>` | 需要加密的模块文件路径 |

执行后会在原路径输出加密后的文件。

***

### 3 AI Skill

官方 GitHub 仓库中提供了一个[ **AI Skill**](https://github.com/InchStudio/ForwardWidgets/blob/master/.claude/commands/fw-encrypt.md)，可以让 AI 直接对模块进行处理。

开发者可以通过 AI 调用该 Skill 完成模块加密。

具体说明请查看官方仓库文档。

***

## 反馈与支持

如果在使用过程中遇到问题，欢迎随时反馈。🤝 参与贡献

欢迎提交 Issue 或 Pull Request：

* GitHub 仓库地址：<https://github.com/baranwang/forward-widget-libs>
* 包管理地址：<https://www.npmjs.com/package/@forward-widget/libs>

***

### 📄 许可证

本项目采用 MIT License，可自由使用、修改与发布。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://forward-2.gitbook.io/forward/fu-lu-er-forward-widget-kai-fa-zhe-zhi-chi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.