koishi-plugin-telegraph-image-manager 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.1.2 - 2026-09-08
+
+- 补充 Koishi 插件市场及 npm 包名安装、升级说明。
+- 固定 npm 官方发布仓库和公开访问设置。
+- 说明 GitHub 安装包的 npm 发布与市场自动收录流程。
+- 沿用 0.1.1 的功能、配置和列表图片预览行为。
+
+## 0.1.1 - 2026-09-08
+
+首次 GitHub 公开发布。
+
+- 列表、下一页和上一页默认附带图片预览，缺失原文件名时仍能根据预览识别图片。
+- 新增 `listThumbnails` 配置，支持恢复纯文字列表；单张查看不受影响。
+- 黑名单记录和非图片文件保留序号与文字，不自动预览。
+- 补充分页、空页、群聊、私聊和预览开关测试。
+
+## 0.1.0 - 2026-09-08
+
+初始本地交付。
+
+- 支持 Koishi 4.18.11 与 OneBot v11，通过同条消息或引用消息上传图片。
+- 支持图库分页、图片查看、直链与 Markdown、重命名、收藏、黑白名单管理。
+- 管理权限支持 Koishi 权限等级及用户标识白名单。
+- 删除需要与用户及会话绑定的限时确认码，仅删除图床管理记录和短链接映射。
+- 提供上传队列、网络超时、图片来源与内容校验，隔离管理和上传凭据。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Telegraph-Image Manager contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# koishi-plugin-telegraph-image-manager
+
+在 Koishi 聊天指令中上传、浏览和管理现有 Telegraph-Image 图床。图片仍通过图床自身的上传接口存储，管理结果与网页后台共享。
+
+适配 Koishi 4.18.11；使用官方 OneBot v11 适配器接收 QQ 图片。支持同条消息附图、引用图片消息、图片预览、直链与 Markdown、分页、重命名、收藏、黑名单、白名单和删除确认。
+
+## 安装
+
+环境要求：Koishi 4.18.11 或兼容的 Koishi 4、Node.js 18.20 以上、已启用的 `http` 服务，以及正常工作的 OneBot v11 适配器。建议沿用现有 Koishi 的受支持 Node.js 版本。
+
+### 插件市场
+
+在 Koishi 控制台的「插件市场」中搜索 `telegraph-image-manager` 并安装。插件名为 `telegraph-image-manager`，npm 包名为 [`koishi-plugin-telegraph-image-manager`](https://www.npmjs.com/package/koishi-plugin-telegraph-image-manager)。新版本发布后，市场索引和所用 npm 镜像可能需要一段时间同步。
+
+也可以在 Koishi 项目目录中使用项目原有的包管理器安装：
+
+```sh
+yarn add koishi-plugin-telegraph-image-manager
+```
+
+使用 npm 的项目执行 `npm install koishi-plugin-telegraph-image-manager`。不要混用两种包管理器。
+
+### 安装包
+
+也可从 [GitHub Releases](https://github.com/Lance0174/koishi-plugin-telegraph-image-manager/releases/latest) 下载 `.tgz` 安装包。每个版本同时提供源码压缩包和 SHA256 校验文件，变更记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+将安装包放入服务器上的 Koishi 项目目录，即包含 `package.json`、`koishi.yml` 和现有依赖锁文件的目录。使用该项目原有的包管理器安装：
+
+```sh
+yarn add ./koishi-plugin-telegraph-image-manager-0.1.2.tgz
+```
+
+使用 npm 的项目执行下面这一条，不要混用两种包管理器：
+
+```sh
+npm install ./koishi-plugin-telegraph-image-manager-0.1.2.tgz
+```
+
+Docker 部署需要把安装包放入挂载的 Koishi 项目目录，并在运行 Koishi 的容器内、该目录下执行安装。保留安装包和依赖变更所在的数据卷，确保重建容器后仍能安装依赖。
+
+安装后重启 Koishi，在控制台的「插件配置」中添加 `telegraph-image-manager` 并填写下列配置。
+
+从 0.1.0 或 0.1.1 的本地安装包升级时，在同一个 Koishi 项目内用上述命令改为按包名安装，或安装新版 `.tgz`，然后重启 Koishi。沿用原有插件配置即可，列表图片预览默认开启。
+
+## 连接与授权
+
+| 配置项 | 填写内容 |
+| --- | --- |
+| `baseUrl` | 自己部署的 Telegraph-Image 地址，例如 `https://your-site.pages.dev` |
+| `adminUser` | Cloudflare 中当前的 `BASIC_USER`，默认填 `admin` |
+| `adminPassword` | 当前的 `BASIC_PASS`，控制台显示为密码字段 |
+| `adminUsers` | 添加你自己的 `onebot:QQ号`，例如 `onebot:123456789` |
+| `uploadUser` / `uploadPassword` | 公开上传时两项留空；启用上传认证时填写对应的专用凭据 |
+
+插件不使用 Telegram Bot Token，也不需要新建机器人或修改现有 OneBot 连接。后台密码不会被写进聊天回复、下载请求或公开上传请求。
+
+填写后启用插件。在 QQ 中发送 `图床 身份` 可以核对自己的管理员标识，再发送 `图床 状态` 检查公开配置、发送 `图床 列表` 验证后台认证。
+
+默认允许 Koishi 权限等级至少为 3 的用户，以及 `adminUsers` 中精确匹配的用户浏览和管理图库。两者满足其一即可；QQ 群管理员身份本身不等于 Koishi 3 级权限。没有数据库时，可直接使用 `adminUsers` 授权。
+
+默认普通用户可以上传。`uploadAuthority` 默认为 1；未使用数据库时，普通用户按 1 级处理。图床管理权限持有者始终可以上传。若只允许管理员上传，将 `uploadAuthority` 调为 5，并用 `adminUsers` 指定管理员。
+
+图库权限涵盖整个图床。群内查询的结果会显示在群中，管理操作建议在私聊中执行。列表序号与分页状态按机器人、用户和会话隔离，默认 10 分钟后失效，重启也会清空。
+
+## 指令
+
+下面的 `1` 表示当前列表里的序号，也可写 `#1`。管理指令还接受完整文件 ID 或当前图床的长链接。
+
+| 指令 | 行为 |
+| --- | --- |
+| `图床` | 显示指令菜单 |
+| `图床 身份` | 查看管理员标识和自身权限 |
+| `图床 状态` | 检查存储、后台是否启用及上传认证要求 |
+| `图床 上传` 加图片 | 上传同一条消息中的图片；也可引用已有图片消息后发送 |
+| `图床 列表` | 获取带图片预览的第一页，刷新当前会话的序号 |
+| `图床 下一页` / `图床 上一页` | 翻页并显示对应记录的图片预览 |
+| `图床 查看 1` | 发送图片预览和直链 |
+| `图床 链接 1` | 返回直链及 Markdown |
+| `图床 重命名 1 新名字.png` | 修改后台显示名称，允许名称包含空格 |
+| `图床 收藏 1` | 切换收藏状态 |
+| `图床 拉黑 1` | 加入黑名单 |
+| `图床 白名单 1` | 加入白名单，解除黑名单限制并信任该图片 |
+| `图床 删除 1` | 生成 60 秒有效的删除确认码 |
+| `图床 确认 ABC123` | 使用机器人刚返回的确认码执行删除 |
+| `图床 取消` | 取消当前会话的删除申请 |
+
+如 Koishi 设置了指令前缀，需要带上原有前缀；群聊是否需要 @机器人由现有 Koishi 配置决定。可用 `command` 修改本插件的主指令名。
+
+列表按 Cloudflare KV 游标顺序返回，并非按上传时间排序；内部短链接记录可能造成空页，可以继续翻页。默认每页 5 条，可配置为 1 至 20 条。
+
+每条图片记录的序号和名称下方会附上预览图，即使没有原始文件名、名称仅为文件 ID，也能直接识别图片。QQ 客户端负责缩略显示，点击图片可查看大图。黑名单记录和非图片文件仅保留文字及序号。预览使用图床直链，OneBot 服务需要能够访问这些链接；未在图床创建额外的缩略图文件。
+
+插件配置中的 `listThumbnails` 默认为开启，关闭后列表恢复为纯文字，单张 `图床 查看 1` 不受影响。
+
+上传结果可以是图床短链接。管理接口需要完整文件 ID，因此短链接不能直接用于删除或重命名，需要先在列表中选择对应记录。
+
+删除确认绑定申请时选中的完整 ID，之后翻页不会改变删除目标。确认码只允许申请者在原会话使用一次。删除调用原项目的管理接口，移除 KV 管理记录及其短链接映射，**不会删除 Telegram 源文件**；原有长链接可能仍然可访问，访问还可能重新生成管理记录。不要将其视为源文件彻底删除。
+
+Cloudflare KV 存在传播延迟，刚上传或修改的记录在其他地区不一定立即可见。
+
+## 网络与图片限制
+
+- 默认每条指令最多上传 3 张图片，单张最大 20 MiB。允许 PNG、JPEG、GIF、WebP、BMP、AVIF；实际文件内容会参与格式校验。
+- 下载来源默认允许 `*.qpic.cn`、`*.qq.com`、`*.qq.com.cn` 及图床域名。其他来源需要在 `imageHosts` 中添加可信域名；禁止本地文件、IP 地址、URL 内账号密码和非标准端口，重定向目标也要通过检查。
+- OneBot 应提供图片的 HTTP(S) URL 或 base64 数据。仅提供缓存文件名、文件路径或合并转发外壳的消息无法直接上传。先从合并转发中取出图片，再附图或引用图片消息。
+- 默认网络超时为 30 秒，包含读取响应；上传队列串行执行，上次上传结束后默认等待至少 3.5 秒再开始下一任务，最多排队 20 个任务。Telegram 存储建议保留该间隔。
+- 使用 Koishi 的 `http` 服务及其代理配置。服务器需要能够访问 QQ 图片 CDN 和图床；OneBot 服务需要能够访问图床直链，才能发送预览。
+- 本插件不会自动重试上传、收藏切换和其他写入请求。若发生超时，请先到网页后台检查结果，再决定是否重新上传或操作。
+
+## 修改后台密码
+
+在 Cloudflare Pages 项目的「设置」中修改生产环境的 `BASIC_PASS`，然后重新部署使其生效。用户名对应 `BASIC_USER`。同步修改 Koishi 插件的 `adminPassword` / `adminUser`，保存并重新启用插件。公开上传时保持 `uploadUser` / `uploadPassword` 为空。
+
+## 故障定位
+
+| 现象 | 检查项 |
+| --- | --- |
+| 找不到插件 | 确认在实际 Koishi 项目中安装，并重启 Koishi；Docker 中确认目录已持久化 |
+| 插件未启动 | 确认启用 `http` 服务，地址完整且账号密码已填写 |
+| 没有管理权限 | 发送 `图床 身份`，把显示的完整标识加入 `adminUsers` |
+| 认证失败 | 检查当前 `BASIC_USER` / `BASIC_PASS`；状态命令本身不验证后台密码 |
+| 来源域名未被允许 | 检查 OneBot 提供的实际图片域名，按需加入 `imageHosts` |
+| 有直链但图片预览失败 | 检查 OneBot 所在服务器能否访问图片直链，以及账号发送图片是否被限制 |
+| 只有缓存文件名或引用取不到图片 | 检查 OneBot 的图片 URL 和 `get_msg` 支持；可尝试将图片与上传指令放在同条消息 |
+| 列表序号失效 | 在当前会话重新发送 `图床 列表` |
+| Dashboard 未启用 | 检查图床是否绑定 `img_url` KV，绑定后重新部署 |
+
+## 开发与验证
+
+```sh
+git clone https://github.com/Lance0174/koishi-plugin-telegraph-image-manager.git
+cd koishi-plugin-telegraph-image-manager
+npm ci
+npm test
+npm pack
+```
+
+源码使用 TypeScript，安装包包含编译后的 CommonJS 和类型声明。`file-type` 通过动态导入加载，安装包无需在服务器上编译。
+
+测试使用 Koishi 4.18.11、官方 Mock 插件 2.6.6、官方 OneBot 适配器 6.9.4、本地 HTTP 图床测试服务和本地 WebSocket 协议端。覆盖权限、真实命令解析、图片内容上传、分页隔离、删除确认、认证隔离、超时、图片来源限制及 OneBot 双向消息转换。所有测试图片和管理操作只发生在本地测试服务中。
+
+接口基于 `cf-pages/Telegraph-Image` 的现有 `/upload`、`/api/config` 与 `/api/manage/*`。上游代码检查版本为 `ef69018df1967708ec026a671e3976f5524ff490`。
+
+本地协议测试不等于在你的服务器和实际 QQ 账号上验收；安装启用后，按“身份、状态、列表、上传一张图片、查看”的顺序完成实际连接检查。
+
+## 发布
+
+主分支和 Pull Request 会执行 CI。维护者更新 `package.json`、`package-lock.json`、变更记录和 `docs/releases/v版本号.md` 后，提交并推送与包版本一致的 `v版本号` 标签。
+
+标签工作流会验证版本、运行测试、构建安装包、归档标签对应的源码、计算 SHA256 并发布 GitHub Release。工作流只使用仓库的内置令牌，不需要图床或 Telegram 凭据。
+
+npm 发布由维护者单独执行，GitHub 标签工作流不会自动发布到 npm。下载对应 GitHub Release 的 `.tgz` 并核对 `SHA256SUMS.txt`，在已登录 npm 的环境中先检查发布内容，再发布同一个安装包：
+
+```sh
+npm publish ./koishi-plugin-telegraph-image-manager-0.1.2.tgz --dry-run --access public --registry https://registry.npmjs.org
+npm publish ./koishi-plugin-telegraph-image-manager-0.1.2.tgz --access public --registry https://registry.npmjs.org
+```
+
+`publishConfig` 固定使用 npm 官方仓库并公开发布。npm 账号认证仅放在本机 npm 配置或专用凭据管理中，不要提交到仓库。按 [Koishi 官方规范](https://koishi.chat/zh-CN/guide/develop/publish.html)，满足命名和依赖要求的 npm 包会自动进入插件市场，通常在发布后 15 分钟内收录。

package/lib/api.d.ts

@@ -0,0 +1,36 @@
+import type { Context } from 'koishi';
+import type { Config } from './config';
+export interface ImageRecord {
+    id: string;
+    fileName: string;
+    fileSize: number;
+    timestamp: number;
+    liked: boolean;
+    listType: string;
+}
+export interface ImagePage {
+    items: ImageRecord[];
+    cursor?: string;
+    complete: boolean;
+}
+export interface SiteStatus {
+    ready: boolean;
+    storageProvider: string;
+    dashboard: string;
+    uploadRequiresAuth: boolean;
+}
+export declare function validId(value: string): boolean;
+export declare class ImageApi {
+    private http;
+    private config;
+    private shutdown;
+    readonly base: URL;
+    constructor(http: Context['http'], config: Config, shutdown: AbortSignal);
+    private call;
+    status(): Promise<SiteStatus>;
+    list(cursor?: string): Promise<ImagePage>;
+    fileUrl(id: string): string;
+    parseId(reference: string): string;
+    upload(bytes: Uint8Array, mime: string, fileName: string): Promise<string>;
+    modify(action: 'editName' | 'toggleLike' | 'block' | 'white' | 'delete', id: string, newName?: string): Promise<unknown>;
+}

package/lib/api.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageApi = void 0;
+exports.validId = validId;
+const http_1 = require("./http");
+const idPattern = /^[A-Za-z0-9_-]+\.[A-Za-z0-9]{1,12}$/;
+function validId(value) {
+    return value.length <= 512 && idPattern.test(value);
+}
+function object(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function basic(user, password) {
+    return `Basic ${Buffer.from(`${user}:${password}`, 'utf8').toString('base64')}`;
+}
+class ImageApi {
+    http;
+    config;
+    shutdown;
+    base;
+    constructor(http, config, shutdown) {
+        this.http = http;
+        this.config = config;
+        this.shutdown = shutdown;
+        try {
+            this.base = new URL(config.baseUrl);
+        }
+        catch {
+            throw new http_1.UserError('图床地址必须是完整的 HTTP 或 HTTPS URL。');
+        }
+        if (!['https:', 'http:'].includes(this.base.protocol) || this.base.username || this.base.password || this.base.search || this.base.hash) {
+            throw new http_1.UserError('图床地址不能包含账号密码、查询参数或片段。');
+        }
+        this.base.pathname = `${this.base.pathname.replace(/\/+$/, '')}/`;
+        if (!config.adminUser || !config.adminPassword || config.adminUser.includes(':')) {
+            throw new http_1.UserError('请配置有效的后台账号和密码。');
+        }
+        if (!!config.uploadUser !== !!config.uploadPassword || config.uploadUser.includes(':')) {
+            throw new http_1.UserError('上传账号和密码必须同时填写或同时留空。');
+        }
+    }
+    async call(path, admin = false, method = 'GET', data, params) {
+        const url = new URL(path, this.base);
+        for (const [key, value] of Object.entries(params ?? {}))
+            url.searchParams.set(key, value);
+        const headers = { Accept: 'application/json' };
+        if (admin)
+            headers.Authorization = basic(this.config.adminUser, this.config.adminPassword);
+        else if (path === 'upload' && this.config.uploadUser)
+            headers.Authorization = basic(this.config.uploadUser, this.config.uploadPassword);
+        return (0, http_1.request)(this.http, url.href, this.config.timeout, this.shutdown, { method, data, headers }, async (response) => {
+            if (!response.ok) {
+                await response.body?.cancel();
+                (0, http_1.checkStatus)(response.status);
+            }
+            const text = new TextDecoder().decode(await (0, http_1.readLimited)(response, 2 * 1024 * 1024));
+            if (text.includes('Dashboard is disabled.'))
+                throw new http_1.UserError('图床后台未启用，请绑定 img_url KV 并重新部署。');
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new http_1.UserError('图床返回格式不兼容，请检查地址是否指向 Telegraph-Image。');
+            }
+        });
+    }
+    async status() {
+        const data = await this.call('api/config');
+        if (!object(data) || typeof data.ready !== 'boolean' || !object(data.setup))
+            throw new http_1.UserError('图床配置接口版本不兼容。');
+        return {
+            ready: data.ready,
+            storageProvider: String(data.setup.storageProvider),
+            dashboard: String(data.setup.dashboard),
+            uploadRequiresAuth: !!data.uploadRequiresAuth,
+        };
+    }
+    async list(cursor) {
+        const params = { limit: String(this.config.pageSize) };
+        if (cursor)
+            params.cursor = cursor;
+        const data = await this.call('api/manage/list', true, 'GET', undefined, params);
+        if (!object(data) || !Array.isArray(data.keys) || typeof data.list_complete !== 'boolean')
+            throw new http_1.UserError('图库列表格式不兼容。');
+        if (!data.list_complete && (typeof data.cursor !== 'string' || !data.cursor || data.cursor === cursor))
+            throw new http_1.UserError('图库分页游标无效，请重新列出图库。');
+        const items = [];
+        for (const key of data.keys) {
+            if (!object(key) || typeof key.name !== 'string' || !validId(key.name))
+                continue;
+            const metadata = object(key.metadata) ? key.metadata : {};
+            items.push({
+                id: key.name,
+                fileName: typeof metadata.fileName === 'string' ? metadata.fileName.slice(0, 300) : key.name,
+                fileSize: typeof metadata.fileSize === 'number' ? metadata.fileSize : 0,
+                timestamp: typeof metadata.TimeStamp === 'number' ? metadata.TimeStamp : 0,
+                liked: metadata.liked === true,
+                listType: typeof metadata.ListType === 'string' ? metadata.ListType : 'None',
+            });
+        }
+        return { items, complete: data.list_complete, cursor: data.list_complete ? undefined : data.cursor };
+    }
+    fileUrl(id) {
+        if (!validId(id))
+            throw new http_1.UserError('图片 ID 无效；请使用列表序号或完整文件 ID。');
+        return new URL(`file/${encodeURIComponent(id)}`, this.base).href;
+    }
+    parseId(reference) {
+        let id = reference;
+        if (/^https?:/i.test(reference)) {
+            let url;
+            try {
+                url = new URL(reference);
+            }
+            catch {
+                throw new http_1.UserError('图片链接无效。');
+            }
+            const prefix = `${this.base.pathname}file/`;
+            if (url.origin !== this.base.origin || url.username || url.password || !url.pathname.startsWith(prefix))
+                throw new http_1.UserError('请使用当前图床的图片链接。');
+            try {
+                id = decodeURIComponent(url.pathname.slice(prefix.length));
+            }
+            catch {
+                throw new http_1.UserError('图片链接无效。');
+            }
+        }
+        if (!validId(id))
+            throw new http_1.UserError('请使用列表序号、完整文件 ID 或长链接；短链接请先在列表中选择对应记录。');
+        return id;
+    }
+    async upload(bytes, mime, fileName) {
+        const form = new FormData();
+        form.append('file', new Blob([Buffer.from(bytes)], { type: mime }), fileName);
+        const data = await this.call('upload', false, 'POST', form);
+        if (!Array.isArray(data) || !object(data[0]) || typeof data[0].src !== 'string')
+            throw new http_1.UserError('上传响应缺少图片链接，请在后台确认上传结果。');
+        const src = data[0].src;
+        if (!/^\/file\/[A-Za-z0-9_.-]+$/.test(src) || src.includes('..'))
+            throw new http_1.UserError('上传响应包含无效链接。');
+        return new URL(src.slice(1), this.base).href;
+    }
+    async modify(action, id, newName) {
+        if (!validId(id))
+            throw new http_1.UserError('图片 ID 无效。');
+        const result = await this.call(`api/manage/${action}/${encodeURIComponent(id)}`, true, 'POST', undefined, newName === undefined ? undefined : { newName });
+        if (action === 'delete' && result !== id)
+            throw new http_1.UserError('删除响应异常，请重新列出图库确认状态。');
+        if (action === 'toggleLike' && (!object(result) || typeof result.liked !== 'boolean'))
+            throw new http_1.UserError('收藏响应异常，请重新列出图库。');
+        if (action === 'editName' && (!object(result) || result.success !== true))
+            throw new http_1.UserError('重命名响应异常，请重新列出图库。');
+        if (['block', 'white'].includes(action) && !object(result))
+            throw new http_1.UserError('图片记录不存在。');
+        return result;
+    }
+}
+exports.ImageApi = ImageApi;

package/lib/config.d.ts

@@ -0,0 +1,21 @@
+import { Schema } from 'koishi';
+export interface Config {
+    baseUrl: string;
+    adminUser: string;
+    adminPassword: string;
+    uploadUser: string;
+    uploadPassword: string;
+    command: string;
+    adminUsers: string[];
+    managementAuthority: number;
+    uploadAuthority: number;
+    pageSize: number;
+    listThumbnails: boolean;
+    sessionMinutes: number;
+    timeout: number;
+    maxFileSizeMB: number;
+    maxBatch: number;
+    uploadInterval: number;
+    imageHosts: string[];
+}
+export declare const Config: Schema<Config>;

package/lib/config.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = void 0;
+const koishi_1 = require("koishi");
+exports.Config = koishi_1.Schema.intersect([
+    koishi_1.Schema.object({
+        baseUrl: koishi_1.Schema.string().role('link').required().description('Telegraph-Image 地址，例如 https://your-site.pages.dev。'),
+        adminUser: koishi_1.Schema.string().default('admin').description('后台 BASIC_USER。'),
+        adminPassword: koishi_1.Schema.string().role('secret').required().description('当前后台 BASIC_PASS；更改后台密码后需要同步更新。'),
+        uploadUser: koishi_1.Schema.string().default('').description('上传入口账号。公开上传时留空。'),
+        uploadPassword: koishi_1.Schema.string().role('secret').default('').description('上传入口密码。公开上传时留空。'),
+    }).description('图床连接'),
+    koishi_1.Schema.object({
+        command: koishi_1.Schema.string().pattern(/^[\p{L}\p{N}_-]+$/u).default('图床').description('主指令名称。'),
+        adminUsers: koishi_1.Schema.array(koishi_1.Schema.string()).default([]).description('管理员标识，例如 onebot:123456789。发送“图床 身份”可查看自己的标识。'),
+        managementAuthority: koishi_1.Schema.number().min(1).max(5).step(1).default(3).description('允许浏览和管理图库的 Koishi 权限等级；管理员标识也可独立授权。'),
+        uploadAuthority: koishi_1.Schema.number().min(0).max(5).step(1).default(1).description('允许上传的最低权限等级。无数据库时普通用户按 1 级处理。'),
+    }).description('指令与权限'),
+    koishi_1.Schema.object({
+        pageSize: koishi_1.Schema.number().min(1).max(20).step(1).default(5).description('每页记录数。'),
+        listThumbnails: koishi_1.Schema.boolean().default(true).description('在列表和翻页回复中显示图片预览。关闭后仅显示文字；不影响单张查看。'),
+        sessionMinutes: koishi_1.Schema.number().min(1).max(60).step(1).default(10).description('列表序号和分页状态的有效期（分钟）。'),
+        timeout: koishi_1.Schema.number().min(1000).max(120000).step(1000).default(30000).role('ms').description('单次网络请求超时，包含读取响应。'),
+        maxFileSizeMB: koishi_1.Schema.number().min(1).max(20).default(20).description('单张图片大小上限（MiB）。'),
+        maxBatch: koishi_1.Schema.number().min(1).max(10).step(1).default(3).description('单条指令最多上传的图片数。'),
+        uploadInterval: koishi_1.Schema.number().min(0).max(60000).step(100).default(3500).role('ms').description('上次上传结束到下次任务开始的最小间隔。Telegram 存储建议保持默认值。'),
+        imageHosts: koishi_1.Schema.array(koishi_1.Schema.string()).default(['*.qpic.cn', '*.qq.com', '*.qq.com.cn']).description('允许下载图片的来源域名。默认覆盖 QQ CDN，自动包含图床域名；可按其他适配器需要添加精确域名或 *.example.com。'),
+    }).description('图片与网络'),
+]);

package/lib/http.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from 'koishi';
+export declare class UserError extends Error {
+}
+export declare function readLimited(response: Response, limit: number): Promise<Uint8Array>;
+export declare function request<T>(http: Context['http'], url: string, timeout: number, shutdown: AbortSignal, options: {
+    method?: 'GET' | 'POST';
+    data?: unknown;
+    headers?: Record<string, string>;
+    redirect?: RequestRedirect;
+}, decoder: (response: Response) => Promise<T>): Promise<T>;
+export declare function checkStatus(status: number): void;

package/lib/http.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserError = void 0;
+exports.readLimited = readLimited;
+exports.request = request;
+exports.checkStatus = checkStatus;
+class UserError extends Error {
+}
+exports.UserError = UserError;
+async function readLimited(response, limit) {
+    const advertised = Number(response.headers.get('content-length'));
+    if (advertised > limit) {
+        await response.body?.cancel();
+        throw new UserError('文件或响应超过大小限制。');
+    }
+    if (!response.body)
+        throw new UserError('服务器返回了空响应。');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > limit)
+                throw new UserError('文件或响应超过大小限制。');
+            chunks.push(value);
+        }
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+async function request(http, url, timeout, shutdown, options, decoder) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (shutdown.aborted)
+        throw new UserError('插件已停止。');
+    shutdown.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, timeout);
+    try {
+        const response = await http(url, {
+            ...options,
+            timeout,
+            signal: controller.signal,
+            redirect: options.redirect ?? 'error',
+            validateStatus: () => true,
+            responseType: decoder,
+        });
+        return response.data;
+    }
+    catch (error) {
+        if (error instanceof UserError)
+            throw error;
+        if (controller.signal.aborted)
+            throw new UserError('请求已取消或超时，请稍后重试。');
+        // HTTP errors may contain signed attachment URLs or request credentials.
+        throw new UserError('网络请求失败，请检查图床地址、HTTP 服务及代理配置。');
+    }
+    finally {
+        clearTimeout(timer);
+        shutdown.removeEventListener('abort', abort);
+    }
+}
+function checkStatus(status) {
+    if (status >= 200 && status < 300)
+        return;
+    if (status === 401 || status === 403)
+        throw new UserError('图床认证失败，请检查对应的账号密码和访问策略。');
+    if (status === 429)
+        throw new UserError('请求过于频繁，请稍后重试。');
+    if (status === 404)
+        throw new UserError('图片记录或接口不存在。');
+    throw new UserError(`图床请求失败（HTTP ${status}）。`);
+}

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+import { Context, type Session } from 'koishi';
+import { Config } from './config';
+export { Config };
+export declare const name = "telegraph-image-manager";
+export declare const reusable = true;
+export declare const inject: string[];
+export declare const usage = "\u586B\u5199\u56FE\u5E8A\u5730\u5740\u53CA\u5F53\u524D\u540E\u53F0\u8D26\u53F7\u5BC6\u7801\u3002\u9ED8\u8BA4\u6307\u4EE4\u4E3A\u201C\u56FE\u5E8A\u201D\uFF1BOneBot \u7BA1\u7406\u5458\u6807\u8BC6\u683C\u5F0F\u4E3A onebot:QQ\u53F7\uFF0C\u4E5F\u53EF\u4F7F\u7528 Koishi 3 \u7EA7\u53CA\u4EE5\u4E0A\u6743\u9650\u3002\u56FE\u7247\u4E0A\u4F20\u652F\u6301\u540C\u6761\u6D88\u606F\u9644\u56FE\u6216\u5F15\u7528\u56FE\u7247\u6D88\u606F\u3002\u5220\u9664\u4EC5\u79FB\u9664\u7BA1\u7406\u8BB0\u5F55\uFF0C\u4E0D\u5220\u9664 Telegram \u6E90\u6587\u4EF6\u3002";
+export declare function canManage(session: Pick<Session<'authority'>, 'platform' | 'userId' | 'user'>, config: Config): boolean;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,256 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usage = exports.inject = exports.reusable = exports.name = exports.Config = void 0;
+exports.canManage = canManage;
+exports.apply = apply;
+const koishi_1 = require("koishi");
+const config_1 = require("./config");
+Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_1.Config; } });
+const api_1 = require("./api");
+const http_1 = require("./http");
+const media_1 = require("./media");
+const state_1 = require("./state");
+exports.name = 'telegraph-image-manager';
+exports.reusable = true;
+exports.inject = ['http'];
+exports.usage = '填写图床地址及当前后台账号密码。默认指令为“图床”；OneBot 管理员标识格式为 onebot:QQ号，也可使用 Koishi 3 级及以上权限。图片上传支持同条消息附图或引用图片消息。删除仅移除管理记录，不删除 Telegram 源文件。';
+function canManage(session, config) {
+    return config.adminUsers.includes(`${session.platform}:${session.userId}`)
+        || (session.user?.authority ?? 0) >= config.managementAuthority;
+}
+function size(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return '大小未知';
+    return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KiB` : `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+}
+function clean(text) { return text.replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 300); }
+function apply(ctx, config) {
+    const shutdown = new AbortController();
+    const api = new api_1.ImageApi(ctx.http, config, shutdown.signal);
+    const galleries = new state_1.ExpiringStore(config.sessionMinutes * 60000);
+    const deletions = new state_1.ExpiringStore(60000);
+    const busy = new Set();
+    const uploading = new Set();
+    const queue = new state_1.UploadQueue(config.uploadInterval, shutdown.signal);
+    const logger = ctx.logger(exports.name);
+    const prefix = config.command;
+    ctx.on('dispose', () => {
+        shutdown.abort();
+        galleries.clear();
+        deletions.clear();
+        busy.clear();
+        uploading.clear();
+    });
+    function fail(error) {
+        if (error instanceof http_1.UserError)
+            return koishi_1.h.text(error.message);
+        logger.warn('Unexpected command failure; request details omitted.');
+        return koishi_1.h.text('操作失败，请检查插件配置后重试。');
+    }
+    async function manage(session, callback) {
+        if (!session)
+            return;
+        if (!canManage(session, config))
+            return koishi_1.h.text('你没有图库管理权限。');
+        const key = (0, state_1.sessionKey)(session);
+        if (busy.has(key))
+            return koishi_1.h.text('当前会话还有操作正在执行，请稍后再试。');
+        busy.add(key);
+        try {
+            return await callback(session, key);
+        }
+        catch (error) {
+            return fail(error);
+        }
+        finally {
+            busy.delete(key);
+        }
+    }
+    function resolve(reference, key) {
+        if (!reference)
+            throw new http_1.UserError(`缺少图片参数，请使用“${prefix}”查看指令菜单。`);
+        if (/^#?\d+$/.test(reference)) {
+            const gallery = galleries.get(key);
+            if (!gallery)
+                throw new http_1.UserError(`列表序号已过期或不属于当前会话，请先发送“${prefix} 列表”。`);
+            const index = Number(reference.replace(/^#/, '')) - 1;
+            const record = gallery.page.items[index];
+            if (!Number.isSafeInteger(index) || !record)
+                throw new http_1.UserError('列表中没有这个序号。');
+            return { id: record.id, record };
+        }
+        const id = api.parseId(reference);
+        return { id, record: galleries.get(key)?.page.items.find((record) => record.id === id) };
+    }
+    function render(gallery) {
+        const elements = [koishi_1.h.text(`图库第 ${gallery.offset + gallery.index + 1} 页 · ${gallery.page.items.length} 条记录\n`)];
+        for (const [index, record] of gallery.page.items.entries()) {
+            const labels = [size(record.fileSize)];
+            if (record.liked)
+                labels.push('已收藏');
+            if (record.listType === 'Block')
+                labels.push('黑名单');
+            if (record.listType === 'White')
+                labels.push('白名单');
+            elements.push(koishi_1.h.text(`\n${index + 1}. ${clean(record.fileName)}\n   ${labels.join(' · ')}\n`));
+            if (config.listThumbnails && record.listType !== 'Block' && /\.(?:jpe?g|png|gif|webp|bmp|avif|apng)$/i.test(record.id)) {
+                elements.push(koishi_1.h.image(api.fileUrl(record.id)), koishi_1.h.text('\n'));
+            }
+        }
+        const lines = [];
+        if (!gallery.page.items.length)
+            lines.push(gallery.page.complete ? '当前页没有图片记录。' : '当前页没有图片记录，可以继续翻页。');
+        lines.push(`${prefix} 查看 1 | ${prefix} 链接 1`);
+        if (gallery.index > 0)
+            lines.push(`${prefix} 上一页`);
+        if (!gallery.page.complete)
+            lines.push(`${prefix} 下一页`);
+        elements.push(koishi_1.h.text(lines.join('\n')));
+        return (0, koishi_1.h)('message', elements);
+    }
+    const root = ctx.command(prefix, 'Telegraph-Image 图床', { authority: 0 })
+        .action(() => koishi_1.h.text([
+        `${prefix} 上传 [附图]（也支持引用图片消息）`,
+        `${prefix} 列表 / 下一页 / 上一页`,
+        `${prefix} 查看 <序号或ID>`,
+        `${prefix} 链接 <序号或ID>`,
+        `${prefix} 重命名 <序号或ID> <新名称>`,
+        `${prefix} 收藏 / 拉黑 / 白名单 / 删除 <序号或ID>`,
+        `${prefix} 状态 / 身份`,
+    ].join('\n')));
+    function command(decl, description) {
+        return root.subcommand(`.${decl}`, description, { authority: 0, captureQuote: false }).userFields(['authority']);
+    }
+    command('身份', '查看自己的管理员标识').action(({ session }) => {
+        if (!session)
+            return;
+        return koishi_1.h.text(`用户标识：${session.platform}:${session.userId}\nKoishi 权限：${session.user?.authority ?? '未使用数据库'}\n图库管理：${canManage(session, config) ? '已授权' : '未授权'}`);
+    });
+    command('状态', '检查图床连接和运行配置').action(async () => {
+        try {
+            const status = await api.status();
+            return koishi_1.h.text(`图床：${status.ready ? '就绪' : '配置不完整'}\n存储：${status.storageProvider}\n后台：${status.dashboard === 'ok' ? '已启用' : '未启用'}\n上传认证：${status.uploadRequiresAuth ? '需要' : '公开'}`);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    command('上传 [content:text]', '上传附图或引用消息中的图片').action(async ({ session }) => {
+        if (!session)
+            return;
+        if (!canManage(session, config) && (session.user?.authority ?? 1) < config.uploadAuthority)
+            return koishi_1.h.text('你没有上传权限。');
+        const images = (0, media_1.attachments)(session);
+        if (!images.length)
+            return koishi_1.h.text(`请将图片与“${prefix} 上传”一起发送，或引用图片消息后发送该指令。`);
+        if (images.length > config.maxBatch)
+            return koishi_1.h.text(`单次最多上传 ${config.maxBatch} 张图片，本次未开始上传。`);
+        const key = (0, state_1.sessionKey)(session);
+        if (uploading.has(key))
+            return koishi_1.h.text('你的上一批图片仍在上传，请稍后重试。');
+        uploading.add(key);
+        try {
+            const results = [];
+            for (const [index, image] of images.entries()) {
+                try {
+                    const uploaded = await queue.run(async () => {
+                        const file = await (0, media_1.downloadImage)(ctx.http, image, config, shutdown.signal);
+                        return { url: await api.upload(file.bytes, file.mime, file.fileName), fileName: file.fileName };
+                    });
+                    results.push(`${index + 1}. ${clean(uploaded.fileName)}\n${uploaded.url}\nMarkdown: ![](${uploaded.url})`);
+                }
+                catch (error) {
+                    results.push(`${index + 1}. ${error instanceof http_1.UserError ? error.message : '上传失败，请检查图片与配置。'}`);
+                }
+            }
+            return koishi_1.h.text(results.join('\n\n'));
+        }
+        finally {
+            uploading.delete(key);
+        }
+    });
+    command('列表', '重新列出图库第一页').action(({ session }) => manage(session, async (_, key) => {
+        const gallery = { page: await api.list(), cursors: [undefined], index: 0, offset: 0 };
+        galleries.set(key, gallery);
+        return render(gallery);
+    }));
+    for (const direction of [1, -1]) {
+        command(direction === 1 ? '下一页' : '上一页', '翻页浏览图库').action(({ session }) => manage(session, async (_, key) => {
+            const gallery = galleries.get(key);
+            if (!gallery)
+                throw new http_1.UserError(`请先发送“${prefix} 列表”。`);
+            if (direction === 1 && gallery.page.complete)
+                return koishi_1.h.text('已经是最后一页。');
+            if (direction === -1 && gallery.index === 0)
+                return koishi_1.h.text(gallery.offset ? '更早的分页缓存已释放，请重新列出图库。' : '已经是第一页。');
+            const nextIndex = gallery.index + direction;
+            const cursor = direction === 1 ? gallery.page.cursor : gallery.cursors[nextIndex];
+            const page = await api.list(cursor);
+            if (direction === 1)
+                gallery.cursors.splice(nextIndex, gallery.cursors.length, cursor);
+            gallery.index = nextIndex;
+            gallery.page = page;
+            if (gallery.cursors.length > 100) {
+                gallery.cursors.shift();
+                gallery.index--;
+                gallery.offset++;
+            }
+            galleries.set(key, gallery);
+            return render(gallery);
+        }));
+    }
+    command('查看 <target>', '预览指定图片').action(({ session }, target) => manage(session, async (_, key) => {
+        const { id, record } = resolve(target, key);
+        const url = api.fileUrl(id);
+        if (record?.listType === 'Block')
+            return koishi_1.h.text(`此图片已列入黑名单。\n${url}`);
+        return (0, koishi_1.h)('message', [koishi_1.h.text(`${clean(record?.fileName ?? id)}\n${url}\n`), koishi_1.h.image(url)]);
+    }));
+    command('链接 <target>', '获取直链与 Markdown').action(({ session }, target) => manage(session, async (_, key) => {
+        const url = api.fileUrl(resolve(target, key).id);
+        return koishi_1.h.text(`${url}\nMarkdown: ![](${url})`);
+    }));
+    command('重命名 <target> <newName:text>', '修改图片的显示名称').action(({ session }, target, newName) => manage(session, async (_, key) => {
+        if (!newName?.trim() || newName.length > 240 || /[\x00-\x1f\x7f]/.test(newName))
+            throw new http_1.UserError('名称须为 1 至 240 个字符，且不包含控制字符。');
+        const { id, record } = resolve(target, key);
+        await api.modify('editName', id, newName.trim());
+        if (record)
+            record.fileName = newName.trim();
+        return koishi_1.h.text(`已重命名为：${newName.trim()}`);
+    }));
+    for (const [label, action] of [['收藏', 'toggleLike'], ['拉黑', 'block'], ['白名单', 'white']]) {
+        command(`${label} <target>`, label === '收藏' ? '切换收藏状态' : `将图片加入${action === 'block' ? '黑名单' : '白名单'}`).action(({ session }, target) => manage(session, async (_, key) => {
+            const { id, record } = resolve(target, key);
+            const result = await api.modify(action, id);
+            if (record) {
+                if (action === 'toggleLike')
+                    record.liked = result.liked;
+                else
+                    record.listType = action === 'block' ? 'Block' : 'White';
+            }
+            return koishi_1.h.text(action === 'toggleLike' ? (result.liked ? '已收藏。' : '已取消收藏。') : `已加入${action === 'block' ? '黑名单' : '白名单'}。`);
+        }));
+    }
+    command('删除 <target>', '申请删除一条图片管理记录').action(({ session }, target) => manage(session, async (_, key) => {
+        const { id, record } = resolve(target, key);
+        const pending = (0, state_1.deletion)(id, clean(record?.fileName ?? id));
+        deletions.set(key, pending);
+        return koishi_1.h.text(`将删除管理记录：${pending.label}\nID：${id}\nTelegram 源文件不会删除。\n60 秒内发送“${prefix} 确认 ${pending.token}”执行，或发送“${prefix} 取消”。`);
+    }));
+    command('确认 <token>', '确认删除指定记录').action(({ session }, token) => manage(session, async (_, key) => {
+        if (!token)
+            throw new http_1.UserError('缺少确认码，请使用删除申请中返回的确认码。');
+        const pending = deletions.get(key);
+        if (!pending || pending.token !== token.toUpperCase())
+            throw new http_1.UserError('确认码不正确、已过期或不属于当前会话。');
+        deletions.delete(key);
+        await api.modify('delete', pending.id);
+        galleries.delete(key);
+        return koishi_1.h.text(`已删除管理记录：${pending.label}\nTelegram 源文件保留。列表序号已清除，请重新列出图库。`);
+    }));
+    command('取消', '取消当前会话的删除申请').action(({ session }) => manage(session, async (_, key) => {
+        deletions.delete(key);
+        return koishi_1.h.text('已取消删除申请。');
+    }));
+}

package/lib/media.d.ts

@@ -0,0 +1,13 @@
+import { type Context, type Session } from 'koishi';
+import type { Config } from './config';
+export interface Attachment {
+    src: string;
+    name?: string;
+}
+export declare function attachments(session: Pick<Session, 'elements' | 'quote'>): Attachment[];
+export declare function allowedImageUrl(source: string, hosts: string[]): URL;
+export declare function downloadImage(http: Context['http'], attachment: Attachment, config: Config, shutdown: AbortSignal): Promise<{
+    bytes: Uint8Array<ArrayBufferLike>;
+    mime: import("file-type", { with: { "resolution-mode": "import" } }).MimeType;
+    fileName: string;
+}>;

package/lib/media.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachments = attachments;
+exports.allowedImageUrl = allowedImageUrl;
+exports.downloadImage = downloadImage;
+const node_net_1 = require("node:net");
+const node_path_1 = require("node:path");
+const koishi_1 = require("koishi");
+const http_1 = require("./http");
+function attachments(session) {
+    const collect = (elements) => [...koishi_1.h.select(elements, 'img'), ...koishi_1.h.select(elements, 'image')]
+        .map((element) => ({ src: element.attrs.src || element.attrs.url, name: element.attrs.filename || element.attrs.name }))
+        .filter((item) => typeof item.src === 'string' && !!item.src);
+    let found = collect(session.elements ?? []);
+    if (!found.length && session.quote)
+        found = collect(session.quote.elements ?? koishi_1.h.parse(session.quote.content ?? ''));
+    return found.filter((item, index) => found.findIndex((other) => other.src === item.src) === index);
+}
+function allowedImageUrl(source, hosts) {
+    let url;
+    try {
+        url = new URL(source);
+    }
+    catch {
+        throw new http_1.UserError('图片来源地址无效。');
+    }
+    const host = url.hostname.toLowerCase();
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.port || (0, node_net_1.isIP)(host.replace(/^\[|\]$/g, ''))) {
+        throw new http_1.UserError('图片来源必须是允许域名下的 HTTP(S) 地址，不能使用本地文件或 IP 地址。');
+    }
+    const allowed = hosts.some((pattern) => {
+        pattern = pattern.trim().toLowerCase();
+        if (pattern.startsWith('*.')) {
+            const suffix = pattern.slice(2);
+            return !!suffix && (host === suffix || host.endsWith(`.${suffix}`));
+        }
+        return host === pattern;
+    });
+    if (!allowed)
+        throw new http_1.UserError('图片来源域名未被允许，请由管理员检查 imageHosts 配置。');
+    return url;
+}
+async function downloadImage(http, attachment, config, shutdown) {
+    const max = Math.floor(config.maxFileSizeMB * 1024 * 1024);
+    let bytes;
+    if (attachment.src.startsWith('data:') || attachment.src.startsWith('base64://')) {
+        const match = /^(?:data:image\/[a-z0-9.+-]+;base64,|base64:\/\/)([a-z0-9+/]*={0,2})$/i.exec(attachment.src);
+        if (!match || match[1].length > Math.ceil(max / 3) * 4)
+            throw new http_1.UserError('内嵌图片格式无效或超过大小限制。');
+        bytes = Buffer.from(match[1], 'base64');
+        if (bytes.length > max)
+            throw new http_1.UserError('图片超过大小限制。');
+    }
+    else {
+        const hosts = [...config.imageHosts, new URL(config.baseUrl).hostname];
+        let url = allowedImageUrl(attachment.src, hosts);
+        bytes = new Uint8Array();
+        for (let redirects = 0;; redirects++) {
+            const result = await (0, http_1.request)(http, url.href, config.timeout, shutdown, { redirect: 'manual' }, async (response) => {
+                if (response.status >= 300 && response.status < 400) {
+                    await response.body?.cancel();
+                    const location = response.headers.get('location');
+                    if (!location || redirects >= 3)
+                        throw new http_1.UserError('图片来源重定向次数过多或缺少目标地址。');
+                    return allowedImageUrl(new URL(location, url).href, hosts);
+                }
+                if (!response.ok) {
+                    await response.body?.cancel();
+                    (0, http_1.checkStatus)(response.status);
+                }
+                return (0, http_1.readLimited)(response, max);
+            });
+            if (result instanceof URL)
+                url = result;
+            else {
+                bytes = result;
+                break;
+            }
+        }
+    }
+    if (!bytes.byteLength)
+        throw new http_1.UserError('收到的图片为空。');
+    const { fileTypeFromBuffer } = await import('file-type');
+    const type = await fileTypeFromBuffer(bytes).catch(() => undefined);
+    if (!type || !['png', 'jpg', 'gif', 'webp', 'bmp', 'avif', 'apng'].includes(type.ext)) {
+        throw new http_1.UserError('无法识别图片内容；支持 PNG、JPEG、GIF、WebP、BMP 和 AVIF。');
+    }
+    const original = typeof attachment.name === 'string' ? (0, node_path_1.basename)(attachment.name.replace(/\\/g, '/')) : 'image';
+    const stem = (0, node_path_1.parse)(original).name.replace(/[\x00-\x1f\x7f]/g, '').trim().slice(0, 180) || 'image';
+    return { bytes, mime: type.mime, fileName: `${stem}.${type.ext}` };
+}

package/lib/state.d.ts

@@ -0,0 +1,34 @@
+import type { Session } from 'koishi';
+import type { ImagePage } from './api';
+export declare function sessionKey(session: Pick<Session, 'platform' | 'selfId' | 'userId' | 'channelId' | 'guildId'>): string;
+export interface Gallery {
+    page: ImagePage;
+    cursors: (string | undefined)[];
+    index: number;
+    offset: number;
+}
+export interface Deletion {
+    id: string;
+    label: string;
+    token: string;
+}
+export declare class ExpiringStore<T> {
+    private ttl;
+    private now;
+    private entries;
+    constructor(ttl: number, now?: () => number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): void;
+    clear(): void;
+}
+export declare function deletion(id: string, label: string): Deletion;
+export declare class UploadQueue {
+    private interval;
+    private shutdown;
+    private tail;
+    private count;
+    private nextReady;
+    constructor(interval: number, shutdown: AbortSignal);
+    run<T>(callback: () => Promise<T>): Promise<T>;
+}

package/lib/state.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadQueue = exports.ExpiringStore = void 0;
+exports.sessionKey = sessionKey;
+exports.deletion = deletion;
+const node_crypto_1 = require("node:crypto");
+const http_1 = require("./http");
+function sessionKey(session) {
+    return JSON.stringify([session.platform, session.selfId, session.userId, session.guildId, session.channelId]);
+}
+class ExpiringStore {
+    ttl;
+    now;
+    entries = new Map();
+    constructor(ttl, now = Date.now) {
+        this.ttl = ttl;
+        this.now = now;
+    }
+    get(key) {
+        const item = this.entries.get(key);
+        if (!item)
+            return;
+        if (item.until <= this.now()) {
+            this.entries.delete(key);
+            return;
+        }
+        return item.value;
+    }
+    set(key, value) {
+        for (const [key, item] of this.entries)
+            if (item.until <= this.now())
+                this.entries.delete(key);
+        this.entries.delete(key);
+        if (this.entries.size >= 256)
+            this.entries.delete(this.entries.keys().next().value);
+        this.entries.set(key, { value, until: this.now() + this.ttl });
+    }
+    delete(key) { this.entries.delete(key); }
+    clear() { this.entries.clear(); }
+}
+exports.ExpiringStore = ExpiringStore;
+function deletion(id, label) {
+    return { id, label, token: (0, node_crypto_1.randomBytes)(3).toString('hex').toUpperCase() };
+}
+class UploadQueue {
+    interval;
+    shutdown;
+    tail = Promise.resolve();
+    count = 0;
+    nextReady = 0;
+    constructor(interval, shutdown) {
+        this.interval = interval;
+        this.shutdown = shutdown;
+    }
+    async run(callback) {
+        if (this.count >= 20)
+            throw new http_1.UserError('上传队列已满，请稍后重试。');
+        this.count++;
+        const job = this.tail.then(async () => {
+            if (this.shutdown.aborted)
+                throw new http_1.UserError('插件已停止。');
+            const delay = Math.max(0, this.nextReady - Date.now());
+            if (delay)
+                await new Promise((resolve, reject) => {
+                    const abort = () => { clearTimeout(timer); reject(new http_1.UserError('插件已停止。')); };
+                    const timer = setTimeout(() => { this.shutdown.removeEventListener('abort', abort); resolve(); }, delay);
+                    this.shutdown.addEventListener('abort', abort, { once: true });
+                });
+            try {
+                return await callback();
+            }
+            finally {
+                this.nextReady = Date.now() + this.interval;
+            }
+        });
+        this.tail = job.then(() => { }, () => { });
+        try {
+            return await job;
+        }
+        finally {
+            this.count--;
+        }
+    }
+}
+exports.UploadQueue = UploadQueue;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "koishi-plugin-telegraph-image-manager",
+  "version": "0.1.2",
+  "description": "Upload, browse and manage Telegraph-Image from Koishi and OneBot v11.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lance0174/koishi-plugin-telegraph-image-manager.git"
+  },
+  "homepage": "https://github.com/Lance0174/koishi-plugin-telegraph-image-manager#readme",
+  "bugs": { "url": "https://github.com/Lance0174/koishi-plugin-telegraph-image-manager/issues" },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": ["lib", "README.md", "CHANGELOG.md", "LICENSE"],
+  "license": "MIT",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "engines": { "node": ">=18.20" },
+  "keywords": ["koishi", "plugin", "telegraph-image", "onebot", "image-hosting"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test --test-concurrency=1 test/*.test.cjs",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": { "koishi": "^4.18.11" },
+  "dependencies": { "file-type": "^19.6.0" },
+  "devDependencies": {
+    "@koishijs/plugin-mock": "2.6.6",
+    "@types/node": "^18.19.0",
+    "koishi": "4.18.11",
+    "koishi-plugin-adapter-onebot": "6.9.4",
+    "typescript": "^5.9.0"
+  },
+  "koishi": {
+    "description": { "zh": "Telegraph-Image 图床上传、图库浏览和管理，支持 OneBot v11 图片与引用消息。" },
+    "service": { "required": ["http"] }
+  }
+}