@zhin.js/adapter-icqq 1.1.20 → 1.1.22

package/schema.json

@@ -433,6 +433,27 @@
               "endpoint",
               "id"
             ]
+          },
+          "nickname": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "账号昵称兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account nickname"
+              }
+            }
+          },
+          "profile": {
+            "$ref": "#/$defs/selfProfileFallback",
+            "description": "账号资料兜底",
+            "x-i18n": {
+              "en": {
+                "description": "Fallback account profile"
+              }
+            }
           }
         },
         "required": [
@@ -541,10 +562,94 @@
         "endpoint",
         "id"
       ]
+    },
+    "nickname": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "账号昵称兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account nickname"
+        }
+      }
+    },
+    "profile": {
+      "$ref": "#/$defs/selfProfileFallback",
+      "description": "账号资料兜底",
+      "x-i18n": {
+        "en": {
+          "description": "Fallback account profile"
+        }
+      }
     }
   },
   "required": [
     "master",
     "endpoints"
-  ]
+  ],
+  "$defs": {
+    "selfProfileFallback": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gender": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "enum": [
+            "male",
+            "female",
+            "other",
+            "unknown",
+            null
+          ]
+        },
+        "age": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "birthday": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
+        },
+        "signature": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "avatar": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^(https?://[^\\s/?#]+(?:[/?#].*)?|)$"
+        },
+        "interests": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "bio": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
 }

package/src/endpoint.ts

@@ -33,7 +33,8 @@ import {
   type EndpointGroupNoticeRequest,
 } from 'zhin.js/adapter';
 import type { EndpointContentPort } from '@zhin.js/adapter';
-import { receiveOneBotLikeSideEvent, buildSystem, toCanonicalSegments, type LoginAssist, type LoginAssistEndpointIdentity, type PendingLoginTask } from '@zhin.js/core';
+import { receiveOneBotLikeSideEvent } from '@zhin.js/adapter-onebot-events';
+import { buildSystem, toCanonicalSegments, type LoginAssist, type LoginAssistEndpointIdentity, type PendingLoginTask } from '@zhin.js/core';
 import { EndpointDeliveryError, type EndpointSendPart, type EndpointSendResult, type MessageRef } from '@zhin.js/im-contract';
 import { formatCompact, getAdapterLogger, truncatePreview } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -77,8 +78,10 @@ import {
 } from './protocol.js';
 import type { SystemMessage as IcqqSystemMessage } from './types.js';
 import { ManagedIcqqClient, type IcqqBackgroundOperation } from './managed-client.js';
+import { createIcqqActionPorts } from './group-actions.js';
 import { inspectGroupMember, moderateGroupMember } from './group-moderation.js';
 import { inspectGroupMemberProfile, inspectGroupScene } from './group-scene.js';
+import { createIcqqSelfProfile } from './self-profile.js';
 
 export interface IcqqEndpointOptions {
   readonly id: CapabilityId;
@@ -188,6 +191,7 @@ export class IcqqEndpoint extends ManagedIcqqClient implements Endpoint {
         throw new Error('QQ did not confirm the group notice');
       }
     },
+    ...createIcqqActionPorts(() => this),
   });
 
   readonly #control: EndpointControl = Object.freeze<EndpointControl>({
@@ -239,7 +243,7 @@ export class IcqqEndpoint extends ManagedIcqqClient implements Endpoint {
       start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(), stop: () => this.#stopFramework(),
       send: request => this.#sendFramework(request), get name() { return name(); },
       get transportState() { return state(); },
-      management: this.#management, control: this.#control,
+      management: this.#management, control: this.#control, profile: createIcqqSelfProfile(this),
       get content() { return content(); },
     });
     this.#contentResolver = new IcqqContentResolver(this);

package/src/group-actions.ts

@@ -0,0 +1,105 @@
+import type { Client, MemberInfo } from '@icqqjs/icqq';
+import { createEndpointOperation, type EndpointManagement, type EndpointOperation } from 'zhin.js/adapter';
+
+type ActionPorts = Pick<
+  EndpointManagement,
+  | 'pokeUser'
+  | 'unmuteGroupMember'
+  | 'muteAllGroupMembers'
+  | 'setGroupCard'
+  | 'setGroupTitle'
+  | 'setGroupEssence'
+  | 'inviteGroupMember'
+>;
+
+function numericId(value: string): number {
+  const id = Number(value);
+  if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(id)) throw new Error('Invalid QQ identifier');
+  return id;
+}
+
+/** Uncached member lookup; `pickMember` and the cached roster would report stale roles. */
+async function freshMember(operation: EndpointOperation, client: Client, group: number, user: number): Promise<MemberInfo | undefined> {
+  try {
+    const member = await operation.prepare(() => client.getGroupMemberInfo(group, user, true));
+    return member.user_id === user && member.group_id === group ? member : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function requireBotRole(operation: EndpointOperation, client: Client, group: number, roles: readonly string[], message: string): Promise<void> {
+  const self = await freshMember(operation, client, group, client.uin);
+  if (!self || !roles.includes(self.role)) throw new Error(message);
+}
+
+function confirmed(ok: unknown, what: string): void {
+  if (ok === false) throw new Error(`QQ did not confirm ${what}`);
+}
+
+/**
+ * ADR 0044 action ports of the icqq endpoint. Where the bot's role decides the outcome the role is
+ * read fresh from the platform first, so a stale cache can neither allow nor refuse the action.
+ * Each request carries its own lifetime: reads are `prepare`, the native effect is `run`.
+ */
+export function createIcqqActionPorts(getClient: () => Client): ActionPorts {
+  return {
+    async pokeUser({ userId, groupId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const user = numericId(userId);
+      confirmed(
+        groupId === undefined
+          ? await operation.run(() => client.pickFriend(user).poke(false))
+          : await operation.run(() => client.sendGroupPoke(numericId(groupId), user)),
+        'poke',
+      );
+    },
+    async unmuteGroupMember({ groupId, userId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupBan(group, numericId(userId), 0)), 'unmute');
+    },
+    async muteAllGroupMembers({ groupId, enabled, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupWholeBan(group, enabled)), 'whole-group mute');
+    },
+    async setGroupCard({ groupId, userId, card, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      if (user !== client.uin) await requireBotRole(operation, client, group, ['owner', 'admin'], 'Bot is not a group admin');
+      confirmed(await operation.run(() => client.setGroupCard(group, user, card)), 'card change');
+    },
+    async setGroupTitle({ groupId, userId, title, durationSeconds, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      await requireBotRole(operation, client, group, ['owner'], 'Only the group owner can set special titles');
+      if (!await freshMember(operation, client, group, user)) throw new Error('Target is not a group member');
+      confirmed(await operation.run(() => client.setGroupSpecialTitle(group, user, title, durationSeconds ?? -1)), 'title change');
+    },
+    async setGroupEssence({ groupId, messageId, enabled, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      await requireBotRole(operation, client, numericId(groupId), ['owner', 'admin'], 'Bot is not a group admin');
+      if (enabled) await operation.run(() => client.setEssenceMessage(messageId));
+      else await operation.run(() => client.removeEssenceMessage(messageId));
+    },
+    async inviteGroupMember({ groupId, userId, signal }) {
+      const client = getClient();
+      const operation = createEndpointOperation({ signal });
+      const group = numericId(groupId);
+      const user = numericId(userId);
+      if (await freshMember(operation, client, group, user)) throw new Error('Target is already a group member');
+      confirmed(await operation.run(() => client.inviteFriend(group, user)), 'invitation');
+    },
+  };
+}

package/src/protocol.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 import type { MessageElem, Sendable, ShareElem } from '@icqqjs/icqq';
 import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { resolveAdapterNotifyTarget, type AdapterNotifyTarget, type ResolvedAdapterNotifyTarget } from 'zhin.js/adapter';
@@ -232,7 +233,7 @@ export const Actions = {
 } as const;
 
 /** One expanded ICQQ endpoint configuration produced by AdapterIndex. */
-export interface IcqqEndpointConfig {
+export interface IcqqEndpointConfig extends EndpointProfileConfiguration {
   readonly id: string;
   readonly autoReconnect?: boolean;
   readonly outboundMedia?: 'file' | 'base64';

package/src/self-profile.ts

@@ -0,0 +1,55 @@
+import type { Client } from '@icqqjs/icqq';
+import { createEndpointOperation, type EndpointProfile } from 'zhin.js/adapter';
+import type { SelfProfile } from '@zhin.js/im-contract';
+
+type IcqqProfileClient = Pick<Client,
+  'uin' | 'nickname' | 'isOnline' | 'getProfile' | 'setNickname' | 'setGender' |
+  'setSignature' | 'setDescription' | 'setAvatar'>;
+
+/** ICQQ owns the platform facts; config fallbacks and call leases belong to Adapter. */
+export function createIcqqSelfProfile(client: IcqqProfileClient): EndpointProfile {
+  return Object.freeze<EndpointProfile>({
+    writableFields: Object.freeze(['nickname', 'gender', 'signature', 'bio', 'avatar']),
+    get current() { return client.isOnline() ? { nickname: client.nickname } : {}; },
+    async read({ signal }) {
+      const raw = await createEndpointOperation({ signal }).prepare(() => client.getProfile(client.uin));
+      const profile: SelfProfile = {
+        ...(typeof raw.nickname === 'string' ? { nickname: raw.nickname } : {}),
+        ...(raw.sex === 'male' || raw.sex === 'female' || raw.sex === 'unknown' ? { gender: raw.sex } : {}),
+        ...(typeof raw.age === 'number' && Number.isFinite(raw.age) ? { age: raw.age } : {}),
+        ...(typeof raw.signature === 'string' ? { signature: raw.signature } : {}),
+        ...(typeof raw.avatar?.url === 'string' ? { avatar: raw.avatar.url } : {}),
+      };
+      return profile;
+    },
+    async write({ change, signal }) {
+      const operation = createEndpointOperation({ signal });
+      let accepted: boolean;
+      switch (change.field) {
+        case 'nickname': accepted = await operation.run(() => client.setNickname(change.value)); break;
+        case 'gender': {
+          if (change.value === 'other') return { status: 'rejected', message: 'ICQQ supports male, female or unknown gender' };
+          const gender = change.value === 'male' ? 1 : change.value === 'female' ? 2 : 0;
+          accepted = await operation.run(() => client.setGender(gender));
+          break;
+        }
+        case 'signature': accepted = await operation.run(() => client.setSignature(change.value)); break;
+        case 'bio': accepted = await operation.run(() => client.setDescription(change.value)); break;
+        case 'avatar': {
+          if (change.value.kind === 'file') {
+            return { status: 'rejected', message: 'ICQQ avatar requires resolved image bytes, URL or local path' };
+          }
+          const image = change.value.kind === 'base64' ? Buffer.from(change.value.value, 'base64') : change.value.value;
+          await operation.run(() => client.setAvatar(image));
+          // The input is not the platform CDN URL; it must not become an observed avatar.
+          return { status: 'updated' };
+        }
+        default: return { status: 'rejected', message: `ICQQ cannot safely update ${change.field}` };
+      }
+      if (accepted && change.field === 'nickname') client.nickname = change.value;
+      return accepted
+        ? { status: 'updated', profile: { [change.field]: change.value } }
+        : { status: 'rejected', message: `ICQQ rejected the ${change.field} change` };
+    },
+  });
+}

package/src/sensitive-commands.ts

@@ -0,0 +1,19 @@
+import type { SensitiveExecCommandRule } from '@zhin.js/agent';
+
+/**
+ * The `icqq` command-line client can kick members, move money and delete files. Under an `allowlist`
+ * exec policy its non-sensitive subcommands run freely, while these need owner approval (ADR 0044:
+ * this knowledge lives with the adapter, the exec policy only reads the registered rule).
+ */
+export const ICQQ_SENSITIVE_SUBCOMMAND_REGEXES: readonly RegExp[] = Object.freeze([
+  /\bicqq\s+friend\s+(?:delete|block|move)\b/i,
+  /\bicqq\s+group\s+(?:kick|mute|set|admin|announce|transfer|quit|dissolve|invite)\b/i,
+  /\bicqq\s+(?:request|wallet|pay|recall)\b/i,
+  /\bicqq\s+file\s+(?:upload|delete)\b/i,
+  /\bicqq\s+gfs\b.*\b(?:rm|delete|del)\b/i,
+]);
+
+export const icqqSensitiveExecRule: SensitiveExecCommandRule = Object.freeze({
+  command: 'icqq',
+  sensitive: ICQQ_SENSITIVE_SUBCOMMAND_REGEXES,
+});