koishi-plugin-tx-cos 0.0.1

package/lib/index.d.ts

@@ -0,0 +1,14 @@
+import Assets from '@koishijs/assets';
+import { Context, Schema } from 'koishi';
+export declare const name = "tx-cos";
+export declare const inject: string[];
+export interface Config extends Assets.Config {
+    secretId: string;
+    secretKey: string;
+    bucket: string;
+    region: string;
+    baseUrl: string;
+    prefix?: string;
+}
+export declare const Config: Schema<Config>;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,130 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name2 in all)
+    __defProp(target, name2, { get: all[name2], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Config: () => Config,
+  apply: () => apply,
+  inject: () => inject,
+  name: () => name
+});
+module.exports = __toCommonJS(src_exports);
+var import_assets = __toESM(require("@koishijs/assets"));
+var import_cos_nodejs_sdk_v5 = __toESM(require("cos-nodejs-sdk-v5"));
+var import_koishi = require("koishi");
+var import_path = require("path");
+var name = "tx-cos";
+var inject = ["http"];
+var Config = import_koishi.Schema.intersect([
+  import_koishi.Schema.object({
+    secretId: import_koishi.Schema.string().required().role("secret").description("腾讯云 COS SecretId。"),
+    secretKey: import_koishi.Schema.string().required().role("secret").description("腾讯云 COS SecretKey。"),
+    bucket: import_koishi.Schema.string().required().description("腾讯云 COS 存储桶名称，格式为 bucket-appid。"),
+    region: import_koishi.Schema.string().required().description("腾讯云 COS 存储桶地域，例如 ap-guangzhou。"),
+    baseUrl: import_koishi.Schema.string().required().role("link").description("CDN 或 COS 公网访问根地址。"),
+    prefix: import_koishi.Schema.string().default("koishi-assets").description("上传到 COS 时使用的对象前缀。")
+  }),
+  import_assets.default.Config
+]);
+function apply(ctx, config) {
+  ctx.plugin(TxCosAssets, config);
+}
+__name(apply, "apply");
+var TxCosAssets = class extends import_assets.default {
+  static {
+    __name(this, "TxCosAssets");
+  }
+  static inject = ["http"];
+  client;
+  baseUrl;
+  prefix;
+  uploadedKeys = /* @__PURE__ */ new Set();
+  _stats = {
+    assetCount: 0,
+    assetSize: 0
+  };
+  constructor(ctx, config) {
+    super(ctx, {
+      ...config,
+      whitelist: config.whitelist ?? []
+    });
+    this.client = new import_cos_nodejs_sdk_v5.default({
+      SecretId: config.secretId,
+      SecretKey: config.secretKey
+    });
+    this.baseUrl = (0, import_koishi.trimSlash)(config.baseUrl);
+    this.prefix = this.normalizePrefix(config.prefix || "koishi-assets");
+  }
+  normalizePrefix(prefix) {
+    return prefix.split("/").map((segment) => this.safeName(segment)).filter(Boolean).join("/");
+  }
+  safeName(name2) {
+    return name2.replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "");
+  }
+  safeFile(file) {
+    const name2 = this.safeName((0, import_path.basename)(file || ""));
+    return name2 || void 0;
+  }
+  getKey(filename) {
+    return this.prefix ? `${this.prefix}/${filename}` : filename;
+  }
+  getUrl(key) {
+    return `${this.baseUrl}/${key}`;
+  }
+  async upload(url, file = "") {
+    if (url.startsWith(`${this.baseUrl}/`)) return url;
+    const { buffer, filename, type } = await this.analyze(url, this.safeFile(file));
+    const key = this.getKey(filename);
+    const publicUrl = this.getUrl(key);
+    if (this.uploadedKeys.has(key)) return publicUrl;
+    await this.client.putObject({
+      Bucket: this.config.bucket,
+      Region: this.config.region,
+      Key: key,
+      Body: buffer,
+      ContentLength: buffer.byteLength,
+      ContentType: type
+    });
+    this.uploadedKeys.add(key);
+    this._stats.assetCount += 1;
+    this._stats.assetSize += buffer.byteLength;
+    return publicUrl;
+  }
+  async stats() {
+    return this._stats;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Config,
+  apply,
+  inject,
+  name
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "koishi-plugin-tx-cos",
+  "description": "来用腾讯cos作为assets服务吧",
+  "version": "0.0.1",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "dist"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "chatbot",
+    "koishi",
+    "plugin"
+  ],
+  "peerDependencies": {
+    "koishi": "4.18.11"
+  },
+  "dependencies": {
+    "@koishijs/assets": "^1.1.2",
+    "cos-nodejs-sdk-v5": "^2.15.4"
+  },
+  "koishi": {
+    "service": {
+      "required": [
+        "http"
+      ],
+      "implements": [
+        "assets"
+      ]
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,152 @@
+# koishi-plugin-tx-cos
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-tx-cos?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-tx-cos)
+
+使用腾讯云对象存储（COS）作为 Koishi 的 `assets` 服务。插件会将消息中的图片、音频和视频上传到指定存储桶，并把资源地址替换为可公开访问的 COS 或 CDN URL。
+
+## 功能特点
+
+- 实现 Koishi `assets` 服务，可直接配合各类图片、音频和视频消息使用
+- 支持 HTTP URL、Data URL 等 Koishi HTTP 服务能够读取的资源
+- 使用文件内容的 SHA-1 摘要生成对象名，相同内容会得到稳定的存储路径
+- 支持自定义对象路径前缀、COS 公网域名或 CDN 域名
+- 支持 URL 白名单，指定资源可跳过上传
+- 自动跳过已经指向当前 `baseUrl` 的资源，避免重复处理
+
+## 使用要求
+
+- Koishi 4.18
+- 腾讯云 COS 存储桶
+- 对目标存储桶具有对象写入权限的腾讯云 API 密钥
+- 可公开读取对象的 COS 访问地址，或已正确配置回源的 CDN 域名
+- 已启用 Koishi `http` 服务
+
+插件返回的是不带临时签名的公开 URL，因此存储桶或 CDN 必须允许客户端读取对应对象。建议为插件使用权限最小化的独立密钥，不要将密钥提交到代码仓库。
+
+## 安装
+
+在 Koishi 插件市场搜索 `tx-cos`，或通过包管理器安装：
+
+```bash
+yarn add koishi-plugin-tx-cos
+```
+
+启用插件并填写 COS 配置后，它会注册为当前 Koishi 实例的 `assets` 服务。一个 Koishi 实例通常只应启用一个 `assets` 服务实现，以免服务冲突。
+
+## 腾讯云 COS 准备
+
+1. 创建 COS 存储桶，并记下完整存储桶名称和地域。
+2. 创建具有目标存储桶对象写入权限的 API 密钥，获取 `SecretId` 和 `SecretKey`。
+3. 配置存储桶公开读取，或配置能够公开访问对象的 CDN 域名。
+4. 将公网访问根地址填写到 `baseUrl`，不要包含对象路径前缀。
+
+例如：
+
+```text
+bucket: example-1250000000
+region: ap-guangzhou
+baseUrl: https://example-1250000000.cos.ap-guangzhou.myqcloud.com
+prefix: koishi-assets
+```
+
+上传后的资源地址类似：
+
+```text
+https://example-1250000000.cos.ap-guangzhou.myqcloud.com/koishi-assets/6c6f0e...a1.png
+```
+
+使用自定义 CDN 域名时，`baseUrl` 也可以填写为 `https://static.example.com`，但该域名必须正确回源到配置的存储桶和路径。
+
+## 配置项
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `secretId` | `string` | 必填 | 腾讯云 API 密钥的 SecretId |
+| `secretKey` | `string` | 必填 | 腾讯云 API 密钥的 SecretKey，控制台中会按敏感字段显示 |
+| `bucket` | `string` | 必填 | 完整存储桶名称，格式为 `bucket-appid` |
+| `region` | `string` | 必填 | 存储桶地域，例如 `ap-guangzhou` |
+| `baseUrl` | `string` | 必填 | COS 公网访问或 CDN 根地址 |
+| `prefix` | `string` | `koishi-assets` | 上传对象的路径前缀 |
+| `whitelist` | `string[]` | `[]` | 不进行上传和地址替换的 URL 前缀列表 |
+
+`baseUrl` 末尾的 `/` 会被自动处理。`prefix` 中不安全的字符会替换为 `-`，多级路径可以使用 `/` 分隔。
+
+## 配置示例
+
+推荐通过环境变量保存密钥：
+
+```yaml
+plugins:
+  tx-cos:
+    secretId: ${{env.COS_SECRET_ID}}
+    secretKey: ${{env.COS_SECRET_KEY}}
+    bucket: ${{env.COS_BUCKET}}
+    region: ${{env.COS_REGION}}
+    baseUrl: ${{env.COS_BASE_URL}}
+    prefix: koishi-assets
+    whitelist:
+      - https://trusted.example.com/static/
+```
+
+对应的环境变量示例：
+
+```dotenv
+COS_SECRET_ID=AKIDxxxxxxxxxxxxxxxx
+COS_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+COS_BUCKET=example-1250000000
+COS_REGION=ap-guangzhou
+COS_BASE_URL=https://static.example.com
+```
+
+请根据实际 Koishi 配置结构放置插件配置；控制台安装时可直接在插件配置页面填写这些字段。
+
+## 工作方式
+
+当 Koishi 处理消息中的 `<img>`、`<audio>` 或 `<video>` 元素时，插件会：
+
+1. 检查资源 URL 是否命中 `whitelist`，或是否已经使用当前 `baseUrl`。
+2. 通过 Koishi `http` 服务读取资源内容。
+3. 根据内容计算 SHA-1 摘要，并结合传入的文件名或检测到的扩展名生成对象名。
+4. 将对象上传到 `bucket` 的 `prefix` 路径下，同时保留资源的 Content-Type。
+5. 返回公开 URL，替换消息中的原始资源地址。
+
+同一进程内成功上传过的对象会记录在内存中，再次遇到同一对象时直接返回公开 URL。Bot 重启后这份记录会清空；由于对象名由内容生成，重复上传仍会写入同一个对象键。
+
+## 白名单
+
+`whitelist` 使用 URL 前缀匹配。命中白名单的资源会保留原地址，不会下载或上传到 COS。
+
+```yaml
+whitelist:
+  - https://q.qlogo.cn/
+  - https://third-party.example.com/public/
+```
+
+只有确认目标平台可以直接访问这些 URL 时才应加入白名单。
+
+## 常见问题
+
+### 上传成功但消息中的资源无法访问
+
+检查以下项目：
+
+- `baseUrl` 是否能公开访问，而不是腾讯云控制台内部地址。
+- 存储桶是否允许读取对象，或 CDN 是否已正确配置回源和访问权限。
+- CDN 回源路径是否与 `prefix` 一致。
+- `bucket` 是否包含 AppId，`region` 是否与存储桶实际地域一致。
+
+### 出现 `AccessDenied` 或签名错误
+
+检查 `secretId`、`secretKey` 是否正确，以及密钥是否拥有向目标存储桶执行对象写入操作的权限。还应确认服务器时间准确，且 `bucket` 和 `region` 没有填错。
+
+### 为什么统计数量与存储桶中的对象数不一致
+
+插件的 `stats()` 只统计当前进程启动后成功执行的上传次数和字节数，不会读取 COS 中已有对象，也不会在 Bot 重启后保留统计结果。
+
+### 是否会自动删除 COS 中的旧文件
+
+不会。插件只负责上传和返回资源地址，不会清理对象。需要自动清理时，请在腾讯云 COS 中配置生命周期规则，并确认生命周期策略不会误删仍在使用的资源。
+
+## 许可证
+
+MIT