feat(qzone): add QQ space message publishing and image upload (#1965)

airline233 · web-flow · commit 288cc7c54fb5 · 2026-07-20T20:30:17.000+08:00
- Add QzonePublishResponse interface and parsing logic for publish API responses
- Add buildQzonePublishBody function to construct publish request parameters
- Add buildQzoneUploadImageBody function to construct image upload request parameters
- Add parseQzoneUploadImageResponseText function to parse upload API responses
- Add toQzoneRichval function to format image data for publish requests
- Add publishQzoneMsg method to NTQQWebApi for publishing space messages with optional images
- Add uploadImageToQzone method to NTQQWebApi for uploading images to QQ space
- Add getQzoneAuth private method to retrieve authentication tokens (skey, pskey, g_tk)
- Add SendQzoneMsg action handler to expose QQ space publishing via OneBot API
- Add comprehensive unit tests for all Qzone data construction and parsing functions
- Update action router to register SendQzoneMsg action
- Update action examples to demonstrate Qzone publishing usage
diff --git a/packages/napcat-core/apis/webapi.ts b/packages/napcat-core/apis/webapi.ts
@@ -13,6 +13,14 @@ import { createHash } from 'node:crypto';
 import { basename } from 'node:path';
 import { qunAlbumControl } from '../data/webapi';
 import { createAlbumCommentRequest, createAlbumFeedPublish, createAlbumMediaFeed } from '../data/album';
+import {
+  buildQzonePublishBody,
+  buildQzoneUploadImageBody,
+  parseQzonePublishResponse,
+  parseQzoneUploadImageResponseText,
+  toQzoneRichval,
+  QzonePublishResponse,
+} from '../data/qzone';
 export interface SetNoticeRetSuccess {
   ec: number;
   em: string;
@@ -540,6 +548,63 @@ export class NTQQWebApi {
     );
   }
 
+  private async getQzoneAuth () {
+    const skey = await this.core.apis.UserApi.getSKey() || '';
+    const pskey = (await this.core.apis.UserApi.getPSkey(['qzone.qq.com'])).domainPskeyMap.get('qzone.qq.com') || '';
+    const uin = this.core.selfInfo.uin || '10001';
+    const g_tk = this.getBknFromSKey(skey);
+    const cookie = `p_uin=o${uin}; p_skey=${pskey}; skey=${skey}; uin=o${uin}`;
+    return { skey, pskey, uin, g_tk, cookie };
+  }
+
+  /**
+   * 上传图片到 QQ 空间相册, 返回可用于发说说的 richval 字符串
+   * @param base64 图片Base64编码内容(不带data:前缀)
+   */
+  async uploadImageToQzone (base64: string): Promise<string> {
+    const { skey, pskey, uin, g_tk, cookie } = await this.getQzoneAuth();
+    const body = buildQzoneUploadImageBody({ uin, skey, pskey, g_tk, base64 });
+    const api = `https://up.qzone.qq.com/cgi-bin/upload/cgi_upload_image?g_tk=${g_tk}`;
+    const resultText = await RequestUtil.HttpGetText(api, 'POST', body, {
+      Cookie: cookie,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    });
+    const parsed = parseQzoneUploadImageResponseText(resultText);
+    if (parsed.code !== undefined && parsed.code !== 0) {
+      throw new Error(parsed.msg || `QQ空间图片上传失败, code=${parsed.code}`);
+    }
+    if (!parsed.data) {
+      throw new Error('QQ空间图片上传失败, 响应缺少data字段');
+    }
+    return toQzoneRichval(parsed.data);
+  }
+
+  /**
+   * 发表QQ空间说说
+   * @param content 说说正文
+   * @param richvals 每张图片对应的richval数组, 为空表示纯文字说说
+   * @param ugcRight 查看权限 1所有人可见 4好友可见 16部分好友可见 64仅自己可见 128部分好友不可见
+   * @param targetUins 权限作用QQ号数组, ugcRight为16/128时使用
+   */
+  async publishQzoneMsg (content: string, richvals: string[], ugcRight: number, targetUins?: number[]) {
+    const { uin, g_tk, cookie } = await this.getQzoneAuth();
+    const richval = richvals.length > 0 ? richvals.join('\t') : undefined;
+    const allowUins = targetUins && targetUins.length > 0 ? targetUins.join('|') : undefined;
+    const body = buildQzonePublishBody({
+      hostuin: uin,
+      content,
+      richval,
+      ugcRight,
+      allowUins,
+    });
+    const api = `https://user.qzone.qq.com/proxy/domain/taotao.qzone.qq.com/cgi-bin/emotion_cgi_publish_v6?g_tk=${g_tk}`;
+    const result = await RequestUtil.HttpGetJson<QzonePublishResponse>(api, 'POST', body, {
+      Cookie: cookie,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    }, true, false);
+    return parseQzonePublishResponse(result);
+  }
+
   async getDaySignedList (groupCode: string) {
     const pSkey = (await this.core.apis.UserApi.getPSkey(['qun.qq.com'])).domainPskeyMap.get('qun.qq.com')!;
     const selfUin = this.core.selfInfo.uin;
diff --git a/packages/napcat-core/data/qzone.ts b/packages/napcat-core/data/qzone.ts
@@ -0,0 +1,159 @@
+/**
+ * QQ空间(Qzone)发说说/上传图片相关的纯数据构造与解析函数
+ * 不发起任何网络请求，方便单独测试
+ */
+
+export interface QzoneUploadImageParams {
+  uin: string;
+  skey: string;
+  pskey: string;
+  g_tk: string;
+  base64: string;
+}
+
+/**
+ * 构造上传图片到 QQ 空间的表单请求体 (application/x-www-form-urlencoded)
+ * 对齐 https://up.qzone.qq.com/cgi-bin/upload/cgi_upload_image
+ */
+export function buildQzoneUploadImageBody (params: QzoneUploadImageParams): string {
+  const { uin, skey, pskey, g_tk, base64 } = params;
+  const backUrls = `http://upbak.photo.qzone.qq.com/cgi-bin/upload/cgi_upload_image,http://119.147.64.75/cgi-bin/upload/cgi_upload_image&url=https://up.qzone.qq.com/cgi-bin/upload/cgi_upload_image?g_tk=${g_tk}`;
+  const query = new URLSearchParams({
+    filename: 'filename',
+    uin,
+    skey,
+    zzpaneluin: uin,
+    p_uin: uin,
+    p_skey: pskey,
+    uploadtype: '1',
+    albumtype: '7',
+    exttype: '0',
+    refer: 'shuoshuo',
+    output_type: 'jsonhtml',
+    charset: 'utf-8',
+    output_charset: 'utf-8',
+    upload_hd: '1',
+    hd_width: '2048',
+    hd_height: '10000',
+    hd_quality: '96',
+    backUrls,
+    base64: '1',
+    jsonhtml_callback: 'callback',
+    picfile: base64,
+    qzreferrer: `https://user.qzone.qq.com/${uin}/main`,
+  });
+  return query.toString();
+}
+
+export interface QzoneUploadImageData {
+  albumid: string;
+  lloc: string;
+  type: string;
+  height: string;
+  width: string;
+  url?: string;
+}
+
+export interface QzoneUploadImageRawResponse {
+  code?: number;
+  msg?: string;
+  data?: QzoneUploadImageData;
+}
+
+/**
+ * 解析上传图片接口返回的 `frameElement.callback({...});</script>` 包裹响应
+ */
+export function parseQzoneUploadImageResponseText (raw: string): QzoneUploadImageRawResponse {
+  const startTag = 'frameElement.callback';
+  const endTag = '</script>';
+  const startIdx = raw.indexOf(startTag);
+  const endIdx = raw.indexOf(endTag);
+  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+    throw new Error('QQ空间图片上传响应格式异常');
+  }
+  const segment = raw.slice(startIdx + startTag.length, endIdx);
+  const jsonStart = segment.indexOf('(');
+  const jsonEnd = segment.lastIndexOf(')');
+  if (jsonStart === -1 || jsonEnd === -1 || jsonEnd <= jsonStart) {
+    throw new Error('QQ空间图片上传响应解析失败');
+  }
+  const jsonText = segment.slice(jsonStart + 1, jsonEnd);
+  try {
+    return JSON.parse(jsonText) as QzoneUploadImageRawResponse;
+  } catch {
+    throw new Error('QQ空间图片上传响应JSON解析失败');
+  }
+}
+
+/**
+ * 依据上传图片返回数据拼接 richval 字段
+ * 格式: ,albumid,lloc,sloc,type,height,width,,height,width (sloc 与 lloc 一致)
+ */
+export function toQzoneRichval (data: QzoneUploadImageData): string {
+  const { albumid, lloc, type, height, width } = data;
+  return `,${albumid},${lloc},${lloc},${type},${height},${width},,${height},${width}`;
+}
+
+export interface QzonePublishParams {
+  hostuin: string;
+  content: string;
+  /** 多张图片使用 \t 拼接后的 richval，无图时不传 */
+  richval?: string;
+  ugcRight: number;
+  /** ugc_right 为 16/128 时必填，多个QQ号使用 | 拼接 */
+  allowUins?: string;
+}
+
+/**
+ * 构造发表说说的表单请求体 (application/x-www-form-urlencoded)
+ * 对齐 https://user.qzone.qq.com/proxy/domain/taotao.qzone.qq.com/cgi-bin/emotion_cgi_publish_v6
+ */
+export function buildQzonePublishBody (params: QzonePublishParams): string {
+  const { hostuin, content, richval, ugcRight, allowUins } = params;
+  const fields: Record<string, string> = {
+    syn_tweet_verson: '1',
+    paramstr: '1',
+    con: content,
+    feedversion: '1',
+    ver: '1',
+    ugc_right: String(ugcRight),
+    to_sign: '0',
+    hostuin,
+    code_version: '1',
+    format: 'json',
+    qzreferrer: `https://user.qzone.qq.com/${hostuin}/main`,
+  };
+  if (richval) {
+    fields['richtype'] = '1';
+    fields['richval'] = richval;
+  }
+  if (allowUins) {
+    fields['allow_uins'] = allowUins;
+    fields['who'] = '1';
+  }
+  return new URLSearchParams(fields).toString();
+}
+
+export interface QzonePublishResponse {
+  subcode?: number;
+  code?: number;
+  tid?: string;
+  t1_tid?: string;
+  message?: string;
+  msg?: string;
+}
+
+/**
+ * 解析发表说说接口返回的 JSON, 提取 tid
+ */
+export function parseQzonePublishResponse (json: QzonePublishResponse): { tid: string; } {
+  const subcode = json.subcode ?? json.code;
+  if (subcode !== undefined && subcode !== 0) {
+    throw new Error(json.message || json.msg || `QQ空间发说说失败, subcode=${subcode}`);
+  }
+  const tid = json.t1_tid || json.tid;
+  if (!tid) {
+    throw new Error('QQ空间发说说失败, 未返回tid');
+  }
+  return { tid };
+}
diff --git a/packages/napcat-onebot/action/example/ExtendsActionsExamples.ts b/packages/napcat-onebot/action/example/ExtendsActionsExamples.ts
@@ -42,4 +42,8 @@ export const ExtendsActionsExamples = {
     payload: { group_id: '123456', user_id: '123456789', special_title: '头衔' },
     response: null,
   },
+  SendQzoneMsg: {
+    payload: { content: '今天天气不错', images: [], ugc_right: 1, target_uins: [] },
+    response: { tid: '1234567890abcdef1234567890' },
+  },
 };
diff --git a/packages/napcat-onebot/action/extends/SendQzoneMsg.ts b/packages/napcat-onebot/action/extends/SendQzoneMsg.ts
@@ -0,0 +1,73 @@
+import { uriToLocalFile } from 'napcat-common/src/file';
+import { OneBotAction } from '@/napcat-onebot/action/OneBotAction';
+import { ActionName } from '@/napcat-onebot/action/router';
+import { Static, Type } from '@sinclair/typebox';
+import { existsSync, readFileSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
+import { ExtendsActionsExamples } from '../example/ExtendsActionsExamples';
+
+const ValidUgcRights = [1, 4, 16, 64, 128] as const;
+
+const PayloadSchema = Type.Object({
+  content: Type.String({ description: '说说正文' }),
+  images: Type.Optional(Type.Array(Type.String(), { description: '图片数组, 支持 file:// http(s):// base64:// , 自动上传' })),
+  ugc_right: Type.Optional(Type.Union([Type.Number(), Type.String()], { default: 1, description: '查看权限: 1所有人可见 4好友可见 16部分好友可见 64仅自己可见 128部分好友不可见' })),
+  target_uins: Type.Optional(Type.Array(Type.Union([Type.Number(), Type.String()]), { description: 'ugc_right为16/128时, 权限作用的QQ号数组' })),
+});
+
+type PayloadType = Static<typeof PayloadSchema>;
+
+const ReturnSchema = Type.Object({
+  tid: Type.String({ description: '说说Tid' }),
+}, { description: '发说说结果' });
+
+type ReturnType = Static<typeof ReturnSchema>;
+
+export class SendQzoneMsg extends OneBotAction<PayloadType, ReturnType> {
+  override actionName = ActionName.SendQzoneMsg;
+  override actionSummary = '发表QQ空间说说';
+  override actionDescription = '在QQ空间(Qzone)发表说说, 支持纯文字或带(多)图, 可设置查看权限';
+  override actionTags = ['扩展接口'];
+  override payloadExample = ExtendsActionsExamples.SendQzoneMsg.payload;
+  override returnExample = ExtendsActionsExamples.SendQzoneMsg.response;
+
+  override payloadSchema = PayloadSchema;
+  override returnSchema = ReturnSchema;
+
+  async _handle (payload: PayloadType): Promise<ReturnType> {
+    const ugcRight = payload.ugc_right !== undefined ? +payload.ugc_right : 1;
+    if (!ValidUgcRights.includes(ugcRight as typeof ValidUgcRights[number])) {
+      throw new Error(`ugc_right 参数不合法, 允许的值为: ${ValidUgcRights.join(', ')}`);
+    }
+    const targetUins = payload.target_uins?.map((uin) => +uin).filter((uin) => !Number.isNaN(uin));
+    if ((ugcRight === 16 || ugcRight === 128) && (!targetUins || targetUins.length === 0)) {
+      throw new Error('ugc_right 为 16 或 128 时, target_uins 不能为空');
+    }
+
+    const richvals: string[] = [];
+    const cleanupPaths: string[] = [];
+    try {
+      for (const image of payload.images ?? []) {
+        const downloadResult = await uriToLocalFile(this.core.NapCatTempPath, image);
+        if (!downloadResult.success) {
+          throw new Error(`图片${image}处理失败, ${downloadResult.errMsg}`);
+        }
+        if (!downloadResult.isLocal) {
+          cleanupPaths.push(downloadResult.path);
+        }
+        const base64 = readFileSync(downloadResult.path).toString('base64');
+        const richval = await this.core.apis.WebApi.uploadImageToQzone(base64);
+        richvals.push(richval);
+      }
+
+      const result = await this.core.apis.WebApi.publishQzoneMsg(payload.content, richvals, ugcRight, targetUins);
+      return result;
+    } finally {
+      for (const p of cleanupPaths) {
+        if (existsSync(p)) {
+          await unlink(p).catch(() => { });
+        }
+      }
+    }
+  }
+}
diff --git a/packages/napcat-onebot/action/index.ts b/packages/napcat-onebot/action/index.ts
@@ -160,6 +160,7 @@ import { RefuseOnlineFile } from './file/online/RefuseOnlineFile';
 import { GetFilesetId } from './file/flash/GetFilesetIdByCode';
 import { FetchPttText } from '@/napcat-onebot/action/msg/FetchPttText';
 import { GetGroupSignedList } from './extends/GetGroupSignedList';
+import { SendQzoneMsg } from './extends/SendQzoneMsg';
 
 export function getAllHandlers (obContext: NapCatOneBot11Adapter, core: NapCatCore) {
   const actionHandlers = [
@@ -216,6 +217,7 @@ export function getAllHandlers (obContext: NapCatOneBot11Adapter, core: NapCatCo
     new RenameGroupFile(obContext, core),
     new TransGroupFile(obContext, core),
     new GetGroupSignedList(obContext, core),
+    new SendQzoneMsg(obContext, core),
     // onebot11
     new SendLike(obContext, core),
     new GetMsg(obContext, core),
diff --git a/packages/napcat-onebot/action/router.ts b/packages/napcat-onebot/action/router.ts
@@ -214,4 +214,7 @@ export const ActionName = {
   CancelOnlineFile: 'cancel_online_file',
 
   GetGroupSignedList: 'get_group_signed_list',
+
+  // QQ 空间扩展
+  SendQzoneMsg: 'send_qzone_msg',
 } as const;
diff --git a/packages/napcat-test/qzone.test.ts b/packages/napcat-test/qzone.test.ts
