# 入门 (/docs/plugins)

按下面做，Dex Buddy 启动后就能在侧边栏看到你的插件。插件不需要自己监听端口，也不需要知道 Electron 怎么启动。

Dex Buddy 负责三件事：扫描你的目录、运行你的 `index.js`、如果有界面就打开你的 HTML。

## 你要交出来的东西 [#你要交出来的东西]

一个目录，根上有 `plugin.manifest.json`。

```text
my-tool/
├── plugin.manifest.json
├── icon.png              # 可选。列表和详情用同一张
├── index.js              # 后端。没有后端逻辑可以不放
├── lib/
│   ├── dex-buddy-sdk.js  # 调模型与买断校验时从文档拷进去
│   └── dex_buddy_sdk.py  # 用 Python 调模型时再拷
└── ui/
    └── index.html        # 只有带界面的插件需要
```

两种插件：

| type | 侧边栏点开之后 | 必须有的文件 |
|---|---|---|
| `ui` | 右侧打开你的 HTML | `uiEntry` 指向的页面。通常还有 `index.js` |
| `headless` | 主区域说明它已在后台运行 | `index.js` |

`index.js` 在 Dex Buddy 主进程里按 CommonJS 执行。这里可以用 Node，例如 `fs`、`child_process`，也可以拉起本机脚本。页面跑在隔离窗口里，没有 Node，不能 `require`，只能调用 `window.dex.call`。页面不要自己调命令行，见 [运行](/docs/plugins/runtime)。

后端要用更严的写法时，仍交这份 `index.js`，按 [后端 JavaScript](/docs/plugins/typing) 用 `@ts-check` 和 JSDoc；不要改成 `.ts` 或另交编译目录。

不要把源码复制进 Dex Buddy 安装目录。正确路径是插件页「加载本地目录」，见 [发给同事](/docs/plugins/share)。

## 往下读 [#往下读]

- [清单](/docs/plugins/manifest)：`plugin.manifest.json` 的字段，以及图标尺寸。
- [设置](/docs/plugins/settings)：`configSchema`、分组、密钥和 `pluginEnv()`。
- [数据](/docs/plugins/data)：缓存、导出和数据库放在用户数据目录，不要写进安装目录。
- [运行](/docs/plugins/runtime)：`index.js`、页面里的 `dex.call`，以及 Python / Node 运行时。
- [模型](/docs/plugins/models)：拷 SDK → 本机填 `DEX_BUDDY_API_KEY` → `requireEntitlement(ctx)` 再 `bindModels(ctx)`（Python 子进程再加 `childEnv`）→ 上线不用改，谁用谁付钱。页面不接触网关。
- [后端 JavaScript](/docs/plugins/typing)：`@ts-check`、JSDoc、禁止 `any`；入口仍是 `.js`。
- [打包](/docs/plugins/pack)：宿主默认丢掉什么，以及 `dex-buddy-plugin.pack` 和 `dex-buddy-plugin.ignore` 怎么配合。
- [发给同事](/docs/plugins/share)：插件页加载本地目录、打成 zip 拖进工作台。
- [发到插件中心](/docs/plugins/publish)：改 version、推 `vX.Y.Z` tag。
- [配色](/docs/plugins/color)：页面建议色。可以用，也可以自定。
- [SDK 源码](/docs/plugins/helpers)：`dex-buddy-sdk.js` / `dex_buddy_sdk.py` 全文。