@zhin.js/adapter-napcat 1.1.20 → 1.1.21

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @zhin.js/adapter-napcat
 
+## 1.1.21
+
+### Patch Changes
+
+- af8f803: Use the current Endpoint's platform profile for Agent account identity, with per-field configured fallbacks and scoped, identity-approved profile tools. Keep SOUL first-person and independent of account names. Profile ports preserve the source Client, cancellation, truthful update outcomes and private image authority.
+
+  Adapter Feature API 2.1 and Tool Feature API 1.1 describe the additive profile requirements; new Core, official adapters and generated plugins declare the corresponding floors. Existing compatible API-2.0/API-1.0 plugins remain accepted by the newer providers. npm releases remain patch.
+
+  Private IM assets now bind to the full canonical conversation and principal. Existing IM asset records that contain only the earlier lossy hash remain on disk until their original expiry, but cannot be safely rebound; recapture them. No automatic file deletion, platform profile mutation or workspace SOUL rewrite occurs during upgrade.
+
+- Updated dependencies [b88e988]
+- Updated dependencies [f78eb84]
+- Updated dependencies [c15cef9]
+- Updated dependencies [b0c02a2]
+- Updated dependencies [af8f803]
+- Updated dependencies [26fda97]
+- Updated dependencies [976886c]
+- Updated dependencies [032dc96]
+  - @zhin.js/adapter@1.1.27
+  - @zhin.js/client@1.1.23
+  - @zhin.js/im-contract@1.1.10
+  - @zhin.js/core@1.1.55
+  - @zhin.js/tool@1.1.14
+  - @zhin.js/page@1.1.13
+  - @zhin.js/host-http@1.1.13
+  - @zhin.js/agent-feature@1.1.12
+  - @zhin.js/feature-kit@1.1.11
+  - @zhin.js/permission@1.1.11
+  - @zhin.js/skill@1.1.12
+
 ## 1.1.20
 
 ### Patch Changes

package/README.md

@@ -116,3 +116,14 @@ MIT License
 ### 高阶消息支持边界
 
 NapCat 官方消息兼容表标明 share 仅接收，不支持发送；Markdown 仅可在双层合并转发内发送，不支持直接消息。Canonical `markdown`、`share`、`keyboard` 直接出站明确返回 `unsupported_operation / not_sent`，不会将占位段或原始协议猜测报告成功。当前未实现合并转发 Markdown，亦无原生按钮回调闭环。参考：[官方兼容表](https://napneko.github.io/develop/msg)。
+
+## 当前账号资料
+
+三个传输模式（WS、反向 WS、HTTP）共用当前账号资料端口。读取通过 `get_login_info` 定位真实账号，再取该账号的 `get_stranger_info`；写入只作用于当前登录账号，沿用 Agent 身份类审批。
+
+- 可读：昵称、性别、年龄、个性签名。
+- 可写：昵称、性别、签名、头像。年龄、生日、兴趣和独立个人简介没有接到已验证的写接口。
+- `set_qq_profile.personal_note` 是签名，不冒充个人简介；性别变更按上游要求携带当前昵称，其他资料由 NapCat 自身保留。平台接口不提供跨外部客户端的 CAS，因此同时在 QQ 客户端改名可能与此类读后写操作竞争。
+- `set_qq_profile` 内层 `result` 非零同样视为拒绝。头像修改只报告平台已确认成功，不查询或返回修改后的头像 URL，也不把上传源链接或 base64 当成平台头像。
+
+`nickname` / `profile` 配置仅补足缺失字段，Endpoint 项可覆盖适配器默认值，配置不写回 QQ。接口语义依据 [NapCat 的资料设置实现](https://github.com/NapNeko/NapCatQQ/blob/main/packages/napcat-onebot/action/go-cqhttp/SetQQProfile.ts) 与 [账号信息实现](https://github.com/NapNeko/NapCatQQ/blob/main/packages/napcat-onebot/action/go-cqhttp/GetStrangerInfo.ts)。

package/agents/napcat/skills/napcat-account/tools/set_profile/index.js

@@ -8,7 +8,7 @@ export default defineAgentTool({
         company: z.string().optional().describe('公司（可选）'),
         email: z.string().optional().describe('邮箱（可选）'),
         college: z.string().optional().describe('学校（可选）'),
-        personal_note: z.string().optional().describe('个人说明（可选）'),
+        personal_note: z.string().optional().describe('个性签名（可选）'),
     }),
     adapter: 'napcat',
     tags: ['napcat', 'qq'],

package/agents/napcat/skills/napcat-account/tools/set_profile/index.ts

@@ -8,7 +8,7 @@ export default defineAgentTool<{ nickname: string; company?: string; email?: str
     company: z.string().optional().describe('公司（可选）'),
     email: z.string().optional().describe('邮箱（可选）'),
     college: z.string().optional().describe('学校（可选）'),
-    personal_note: z.string().optional().describe('个人说明（可选）'),
+    personal_note: z.string().optional().describe('个性签名（可选）'),
   }),
   adapter: 'napcat',
   tags: ['napcat', 'qq'],

package/lib/client.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from 'node:events';
 import { callNapCatHttpAction, type NapCatEvent, type ResolvedNapCatConfig } from './protocol.js';
 import { type NapCatRpc } from './ws-transport.js';
+import { type SelfProfile } from '@zhin.js/im-contract';
 import type { PendingRpcRequest } from 'zhin.js/adapter';
 import type { NapCatWsSocket } from './ws-types.js';
 export type NapcatApiCall = (action: string, params?: Record<string, unknown>) => Promise<unknown>;
@@ -43,6 +44,8 @@ export declare class NapcatClient extends EventEmitter<Record<string, [NapCatEve
     protected transportSocket?: NapCatWsSocket;
     protected readonly rpc: NapCatRpc;
     protected readonly protocolConfig: ResolvedNapCatConfig;
+    /** Confirmed native self facts shared by platform tools and the semantic profile port. */
+    get currentSelfProfile(): Readonly<SelfProfile>;
     constructor(options: NapcatClientOptions);
     ingest(event: NapCatEvent): void;
     protected get actionSocket(): NapCatWsSocket | undefined;

package/lib/client.js

@@ -9,6 +9,11 @@ export class NapcatClient extends EventEmitter {
     protocolConfig;
     #httpAction;
     #executionSignal;
+    #selfAccountId;
+    #selfProfile = Object.freeze({});
+    #profileRevision = 0;
+    /** Confirmed native self facts shared by platform tools and the semantic profile port. */
+    get currentSelfProfile() { return this.#selfProfile; }
     constructor(options) {
         super();
         this.protocolConfig = options.config;
@@ -28,6 +33,7 @@ export class NapcatClient extends EventEmitter {
     callApi = (action, params = {}) => this.requestApi({ action, params });
     /** A semantic operation supplies its caller lifetime to the same native protocol owner. */
     async requestApi(request) {
+        const profileRevision = this.#profileRevision;
         const signals = [this.#executionSignal, request.signal].filter((signal) => !!signal);
         const signal = signals.length ? AbortSignal.any(signals) : undefined;
         if (signal?.aborted)
@@ -38,7 +44,9 @@ export class NapcatClient extends EventEmitter {
                     access_token: this.protocolConfig.access_token, signal }, request.action, request.params ?? {});
                 if (signal?.aborted)
                     throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation cancelled', 'unknown');
-                return readNapCatActionResponse(response).data;
+                const data = readNapCatActionResponse(response).data;
+                this.#observeSelfProfile(request, data, profileRevision, signal);
+                return data;
             }
             catch (cause) {
                 if (cause instanceof EndpointDeliveryError)
@@ -47,7 +55,70 @@ export class NapcatClient extends EventEmitter {
             }
         }
         const response = await this.rpc.call({ ...request, signal });
-        return readNapCatActionResponse(response).data;
+        const data = readNapCatActionResponse(response).data;
+        this.#observeSelfProfile(request, data, profileRevision, signal);
+        return data;
+    }
+    /** Observe the one native action after its acknowledgement; never submit a second platform effect. */
+    #observeSelfProfile(request, data, revision, signal) {
+        if (signal?.aborted)
+            return;
+        const result = data && typeof data === 'object' ? data : undefined;
+        if (typeof result?.result === 'number' && result.result !== 0)
+            return;
+        const params = request.params ?? {};
+        let facts = {};
+        switch (request.action) {
+            case 'get_login_info': {
+                if (revision !== this.#profileRevision)
+                    return;
+                const id = result?.user_id;
+                if ((typeof id !== 'number' && typeof id !== 'string') || !String(id).trim() || id === 0 || id === '0')
+                    return;
+                if (this.#selfAccountId !== undefined && this.#selfAccountId !== String(id))
+                    this.#selfProfile = Object.freeze({});
+                this.#selfAccountId = String(id);
+                if (typeof result?.nickname === 'string')
+                    facts = { nickname: result.nickname };
+                break;
+            }
+            case 'get_stranger_info': {
+                if (revision !== this.#profileRevision)
+                    return;
+                if (!this.#selfAccountId || String(params.user_id) !== this.#selfAccountId || String(result?.user_id) !== this.#selfAccountId)
+                    return;
+                facts = {
+                    ...(typeof result?.nickname === 'string' ? { nickname: result.nickname } : {}),
+                    ...(result?.sex === 'male' || result?.sex === 'female' || result?.sex === 'unknown' ? { gender: result.sex } : {}),
+                    ...(typeof result?.age === 'number' && Number.isFinite(result.age) ? { age: result.age } : {}),
+                    ...(typeof result?.long_nick === 'string' ? { signature: result.long_nick } : {}),
+                };
+                break;
+            }
+            case 'set_qq_profile': {
+                const gender = params.sex === 1 || params.sex === '1' ? 'male'
+                    : params.sex === 2 || params.sex === '2' ? 'female'
+                        : params.sex === 0 || params.sex === '0' ? 'unknown' : undefined;
+                facts = { ...(typeof params.nickname === 'string' ? { nickname: params.nickname } : {}),
+                    ...(typeof params.personal_note === 'string' ? { signature: params.personal_note } : {}),
+                    ...(gender ? { gender } : {}),
+                };
+                break;
+            }
+            case 'set_self_longnick':
+                if (typeof params.longNick === 'string')
+                    facts = { signature: params.longNick };
+                break;
+            case 'set_qq_avatar': {
+                const { avatar: _previousAvatar, ...rest } = this.#selfProfile;
+                this.#selfProfile = Object.freeze(rest);
+                this.#profileRevision += 1;
+                return;
+            }
+            default: return;
+        }
+        this.#selfProfile = Object.freeze({ ...this.#selfProfile, ...facts });
+        this.#profileRevision += 1;
     }
     async setTitle({ groupId, userId, title, duration = -1 }) {
         await this.callApi('set_group_special_title', {

package/lib/http-endpoint.js

@@ -2,6 +2,7 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { createEndpointSpecification, endpointSpec, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { createNapcatSelfProfile } from './self-profile.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, callNapCatHttpAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
@@ -32,6 +33,7 @@ export class NapCatHttpEndpoint extends NapcatClient {
             close: () => this.#close(), stop: () => this.#stop(),
             send: request => this.#send(request),
             management: this.#management, control: this.#control, content: this.#content,
+            profile: createNapcatSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
             get transportState() { return readTransportState(); },
         });
         this.on('event', event => {

package/lib/protocol.d.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 /**
  * NapCat protocol helpers (OneBot 11 + NapCat extensions).
  * No legacy Adapter/Endpoint / segment-mapper.
@@ -5,7 +6,7 @@
  */
 import { type MediaRef, type ConversationRef } from '@zhin.js/im-contract';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface NapCatEndpointConfig {
+export interface NapCatEndpointConfig extends EndpointProfileConfiguration {
     readonly connection?: 'ws' | 'wss' | 'http';
     readonly id: string;
     readonly access_token?: string;

package/lib/self-profile.d.ts

@@ -0,0 +1,9 @@
+import type { EndpointProfile, PendingRpcRequest } from 'zhin.js/adapter';
+import { type SelfProfile } from '@zhin.js/im-contract';
+interface NapcatSelfProfileClient {
+    readonly currentSelfProfile?: Readonly<SelfProfile>;
+    requestApi(request: PendingRpcRequest): Promise<unknown>;
+}
+/** All three transports share the native action contract and their existing cancellation owner. */
+export declare function createNapcatSelfProfile(client: NapcatSelfProfileClient, reportAccount?: (id: string) => void): EndpointProfile;
+export {};

package/lib/self-profile.js

@@ -0,0 +1,72 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+/** All three transports share the native action contract and their existing cancellation owner. */
+export function createNapcatSelfProfile(client, reportAccount) {
+    const account = async (signal) => {
+        const value = await client.requestApi({ action: 'get_login_info', signal });
+        if (!value?.user_id || typeof value.nickname !== 'string')
+            throw new Error('NapCat self account is unavailable');
+        reportAccount?.(String(value.user_id));
+        return value;
+    };
+    return Object.freeze({
+        writableFields: Object.freeze(['nickname', 'gender', 'signature', 'avatar']),
+        get current() { return client.currentSelfProfile ?? {}; },
+        async read({ signal }) {
+            const self = await account(signal);
+            const raw = await client.requestApi({ action: 'get_stranger_info', params: { user_id: String(self.user_id), no_cache: true }, signal });
+            if (!raw || String(raw.user_id) !== String(self.user_id))
+                throw new Error('NapCat returned another account profile');
+            const profile = {
+                ...(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.long_nick === 'string' ? { signature: raw.long_nick } : {}),
+            };
+            return profile;
+        },
+        async write({ change, signal }) {
+            let action;
+            let params;
+            switch (change.field) {
+                case 'nickname':
+                    action = 'set_qq_profile';
+                    params = { nickname: change.value };
+                    break;
+                case 'gender': {
+                    if (change.value === 'other')
+                        return { status: 'rejected', message: 'NapCat supports male, female or unknown gender' };
+                    // The native API requires nickname even when only changing sex.
+                    let self;
+                    try {
+                        self = await account(signal);
+                    }
+                    catch (cause) {
+                        throw new EndpointDeliveryError('endpoint_unavailable', 'NapCat profile change was not sent: self account lookup failed', 'not_sent', { cause });
+                    }
+                    action = 'set_qq_profile';
+                    params = { nickname: self.nickname, sex: change.value === 'male' ? 1 : change.value === 'female' ? 2 : 0 };
+                    break;
+                }
+                case 'signature':
+                    action = 'set_self_longnick';
+                    params = { longNick: change.value };
+                    break;
+                case 'avatar': {
+                    if (change.value.kind === 'file') {
+                        return { status: 'rejected', message: 'NapCat avatar requires resolved image bytes, URL or remote path' };
+                    }
+                    action = 'set_qq_avatar';
+                    params = { file: change.value.kind === 'base64' ? `base64://${change.value.value}` : change.value.value };
+                    break;
+                }
+                default: return { status: 'rejected', message: `NapCat cannot safely update ${change.field}` };
+            }
+            const result = await client.requestApi({ action, params, signal });
+            if (result && typeof result.result === 'number' && result.result !== 0) {
+                return { status: 'rejected', message: result.errMsg ?? 'NapCat rejected the profile change' };
+            }
+            return change.field === 'avatar' ? { status: 'updated' }
+                : { status: 'updated', profile: { [change.field]: change.value } };
+        },
+    });
+}

package/lib/ws-endpoint.js

@@ -6,6 +6,7 @@ import WebSocket from 'ws';
 import { createEndpointSpecification, endpointSpec, createRecallEndpointControl, createEndpointLifecycle, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { createNapcatSelfProfile } from './self-profile.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, buildWsConnectOptions, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
@@ -32,6 +33,7 @@ export class NapCatWsEndpoint extends NapcatClient {
             close: () => this.#close(), stop: () => this.#stop(),
             send: request => this.#send(request),
             management: this.#management, control: this.#control, content: this.#content,
+            profile: createNapcatSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
             get transportState() { return readTransportState(); },
         });
         this.on('event', event => {

package/lib/wss-endpoint.js

@@ -5,6 +5,7 @@ import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { createEndpointSpecification, endpointSpec, createEndpointLifecycle, createRecallEndpointControl, } from 'zhin.js/adapter';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { createNapcatSelfProfile } from './self-profile.js';
 import { InboundMessageDeduper, isNapCatBotMentioned, isSelfMessage, normalizeMessage, } from './napcat-inbound.js';
 import { buildSendAction, formatInboundContent, formatOutboundSegments, isMessageEvent, napcatInboundConversation, napcatOutboundTarget, senderNickname, senderUserId, } from './protocol.js';
 import { receiveNapCatSideEvent } from './side-event-dispatch.js';
@@ -36,6 +37,7 @@ export class NapCatWssEndpoint extends NapcatClient {
             close: () => this.#close(), stop: () => this.#stop(),
             send: request => this.#send(request),
             management: this.#management, control: this.#control, content: this.#content,
+            profile: createNapcatSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
             get transportState() { return readTransportState(); },
         });
         this.on('event', event => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-napcat",
-  "version": "1.1.20",
+  "version": "1.1.21",
   "description": "Zhin.js NapCat adapter for Plugin Runtime (WebSocket client, OneBot11 + NapCat extensions)",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,19 +45,19 @@
   },
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/adapter": "1.1.26",
-    "@zhin.js/agent-feature": "1.1.11",
-    "@zhin.js/client": "1.1.22",
+    "@zhin.js/adapter": "1.1.27",
+    "@zhin.js/agent-feature": "1.1.12",
+    "@zhin.js/client": "1.1.23",
     "@zhin.js/console-contract": "1.1.3",
-    "@zhin.js/core": "1.1.54",
-    "@zhin.js/feature-kit": "1.1.10",
-    "@zhin.js/host-http": "1.1.12",
-    "@zhin.js/im-contract": "1.1.9",
+    "@zhin.js/core": "1.1.55",
+    "@zhin.js/feature-kit": "1.1.11",
+    "@zhin.js/host-http": "1.1.13",
+    "@zhin.js/im-contract": "1.1.10",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.12",
-    "@zhin.js/permission": "1.1.10",
-    "@zhin.js/skill": "1.1.11",
-    "@zhin.js/tool": "1.1.13"
+    "@zhin.js/page": "1.1.13",
+    "@zhin.js/permission": "1.1.11",
+    "@zhin.js/skill": "1.1.12",
+    "@zhin.js/tool": "1.1.14"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -65,15 +65,15 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.12",
-    "zhin.js": "1.1.19"
+    "@zhin.js/host-http": "1.1.13",
+    "zhin.js": "1.1.20"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.26",
-    "@zhin.js/command": "^1.1.12",
-    "@zhin.js/core": "^1.1.54",
-    "zhin.js": "^1.1.19"
+    "@zhin.js/adapter": "^1.1.27",
+    "@zhin.js/command": "^1.1.13",
+    "@zhin.js/core": "^1.1.55",
+    "zhin.js": "^1.1.20"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -107,7 +107,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^2.0.0"
+        "api": "^2.1.0"
       },
       {
         "package": "@zhin.js/command",
@@ -115,7 +115,7 @@
       },
       {
         "package": "@zhin.js/tool",
-        "api": "^1.0.0"
+        "api": "^1.1.0"
       },
       {
         "package": "@zhin.js/skill",

package/schema.json

@@ -132,6 +132,27 @@
           "id": {
             "type": "string",
             "description": "NapCat bot name"
+          },
+          "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": [
@@ -153,9 +174,93 @@
           "description": "Command prefix. The default empty string allows unprefixed commands; '/' requires a leading slash. Each endpoints[i] can override it."
         }
       }
+    },
+    "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": [
     "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/client.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'node:events';
 import { callNapCatHttpAction, readNapCatActionResponse, type NapCatEvent, type ResolvedNapCatConfig } from './protocol.js';
 import { createNapCatRpc, type NapCatRpc } from './ws-transport.js';
-import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { EndpointDeliveryError, type SelfProfile } from '@zhin.js/im-contract';
 import type { PendingRpcRequest } from 'zhin.js/adapter';
 import type { NapCatWsSocket } from './ws-types.js';
 
@@ -52,6 +52,12 @@ export class NapcatClient extends EventEmitter<Record<string, [NapCatEvent]>> {
   protected readonly protocolConfig: ResolvedNapCatConfig;
   readonly #httpAction: typeof callNapCatHttpAction;
   readonly #executionSignal?: AbortSignal;
+  #selfAccountId?: string;
+  #selfProfile: Readonly<SelfProfile> = Object.freeze({});
+  #profileRevision = 0;
+
+  /** Confirmed native self facts shared by platform tools and the semantic profile port. */
+  get currentSelfProfile(): Readonly<SelfProfile> { return this.#selfProfile; }
 
   constructor(options: NapcatClientOptions) {
     super();
@@ -75,6 +81,7 @@ export class NapcatClient extends EventEmitter<Record<string, [NapCatEvent]>> {
 
   /** A semantic operation supplies its caller lifetime to the same native protocol owner. */
   async requestApi(request: PendingRpcRequest): Promise<unknown> {
+    const profileRevision = this.#profileRevision;
     const signals = [this.#executionSignal, request.signal].filter((signal): signal is AbortSignal => !!signal);
     const signal = signals.length ? AbortSignal.any(signals) : undefined;
     if (signal?.aborted) throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation ended', 'not_sent');
@@ -83,14 +90,71 @@ export class NapcatClient extends EventEmitter<Record<string, [NapCatEvent]>> {
         const response = await this.#httpAction({ http_url: this.protocolConfig.http_url,
           access_token: this.protocolConfig.access_token, signal }, request.action, request.params ?? {});
         if (signal?.aborted) throw new EndpointDeliveryError('endpoint_inactive', 'Endpoint operation cancelled', 'unknown');
-        return readNapCatActionResponse(response).data;
+        const data = readNapCatActionResponse(response).data;
+        this.#observeSelfProfile(request, data, profileRevision, signal);
+        return data;
       } catch (cause) {
         if (cause instanceof EndpointDeliveryError) throw cause;
         throw new EndpointDeliveryError('delivery_unconfirmed', cause instanceof Error ? cause.message : String(cause), 'unknown', { cause });
       }
     }
     const response = await this.rpc.call({ ...request, signal });
-    return readNapCatActionResponse(response).data;
+    const data = readNapCatActionResponse(response).data;
+    this.#observeSelfProfile(request, data, profileRevision, signal);
+    return data;
+  }
+
+  /** Observe the one native action after its acknowledgement; never submit a second platform effect. */
+  #observeSelfProfile(request: PendingRpcRequest, data: unknown, revision: number, signal?: AbortSignal): void {
+    if (signal?.aborted) return;
+    const result = data && typeof data === 'object' ? data as Record<string, unknown> : undefined;
+    if (typeof result?.result === 'number' && result.result !== 0) return;
+    const params = request.params ?? {};
+    let facts: SelfProfile = {};
+    switch (request.action) {
+      case 'get_login_info': {
+        if (revision !== this.#profileRevision) return;
+        const id = result?.user_id;
+        if ((typeof id !== 'number' && typeof id !== 'string') || !String(id).trim() || id === 0 || id === '0') return;
+        if (this.#selfAccountId !== undefined && this.#selfAccountId !== String(id)) this.#selfProfile = Object.freeze({});
+        this.#selfAccountId = String(id);
+        if (typeof result?.nickname === 'string') facts = { nickname: result.nickname };
+        break;
+      }
+      case 'get_stranger_info': {
+        if (revision !== this.#profileRevision) return;
+        if (!this.#selfAccountId || String(params.user_id) !== this.#selfAccountId || String(result?.user_id) !== this.#selfAccountId) return;
+        facts = {
+          ...(typeof result?.nickname === 'string' ? { nickname: result.nickname } : {}),
+          ...(result?.sex === 'male' || result?.sex === 'female' || result?.sex === 'unknown' ? { gender: result.sex } : {}),
+          ...(typeof result?.age === 'number' && Number.isFinite(result.age) ? { age: result.age } : {}),
+          ...(typeof result?.long_nick === 'string' ? { signature: result.long_nick } : {}),
+        };
+        break;
+      }
+      case 'set_qq_profile': {
+        const gender = params.sex === 1 || params.sex === '1' ? 'male'
+          : params.sex === 2 || params.sex === '2' ? 'female'
+            : params.sex === 0 || params.sex === '0' ? 'unknown' : undefined;
+        facts = { ...(typeof params.nickname === 'string' ? { nickname: params.nickname } : {}),
+          ...(typeof params.personal_note === 'string' ? { signature: params.personal_note } : {}),
+          ...(gender ? { gender } : {}),
+        };
+        break;
+      }
+      case 'set_self_longnick':
+        if (typeof params.longNick === 'string') facts = { signature: params.longNick };
+        break;
+      case 'set_qq_avatar': {
+        const { avatar: _previousAvatar, ...rest } = this.#selfProfile;
+        this.#selfProfile = Object.freeze(rest);
+        this.#profileRevision += 1;
+        return;
+      }
+      default: return;
+    }
+    this.#selfProfile = Object.freeze({ ...this.#selfProfile, ...facts });
+    this.#profileRevision += 1;
   }
 
   async setTitle({ groupId, userId, title, duration = -1 }: NapcatMemberTitleRequest): Promise<boolean> {

package/src/http-endpoint.ts

@@ -15,6 +15,7 @@ import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { createNapcatSelfProfile } from './self-profile.js';
 import {
   InboundMessageDeduper,
   isNapCatBotMentioned,
@@ -73,6 +74,7 @@ export class NapCatHttpEndpoint extends NapcatClient implements Endpoint {
       close: () => this.#close(), stop: () => this.#stop(),
       send: request => this.#send(request),
       management: this.#management, control: this.#control, content: this.#content,
+      profile: createNapcatSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
       get transportState() { return readTransportState(); },
     });
     this.on('event', event => {

package/src/protocol.ts

@@ -1,3 +1,4 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 /**
  * NapCat protocol helpers (OneBot 11 + NapCat extensions).
  * No legacy Adapter/Endpoint / segment-mapper.
@@ -9,7 +10,7 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('napcat');
 
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface NapCatEndpointConfig {
+export interface NapCatEndpointConfig extends EndpointProfileConfiguration {
   readonly connection?: 'ws' | 'wss' | 'http';
   readonly id: string;
   readonly access_token?: string;

package/src/self-profile.ts

@@ -0,0 +1,75 @@
+import type { EndpointProfile, PendingRpcRequest } from 'zhin.js/adapter';
+import { EndpointDeliveryError, type SelfProfile } from '@zhin.js/im-contract';
+
+interface NapcatSelfProfileClient {
+  readonly currentSelfProfile?: Readonly<SelfProfile>;
+  requestApi(request: PendingRpcRequest): Promise<unknown>;
+}
+interface NapcatAccount { readonly user_id?: number | string; readonly nickname?: string; }
+interface NapcatUserProfile extends NapcatAccount {
+  readonly age?: number;
+  readonly sex?: 'male' | 'female' | 'unknown';
+  readonly long_nick?: string;
+}
+
+/** All three transports share the native action contract and their existing cancellation owner. */
+export function createNapcatSelfProfile(client: NapcatSelfProfileClient, reportAccount?: (id: string) => void): EndpointProfile {
+  const account = async (signal: AbortSignal): Promise<NapcatAccount> => {
+    const value = await client.requestApi({ action: 'get_login_info', signal }) as NapcatAccount;
+    if (!value?.user_id || typeof value.nickname !== 'string') throw new Error('NapCat self account is unavailable');
+    reportAccount?.(String(value.user_id));
+    return value;
+  };
+  return Object.freeze<EndpointProfile>({
+    writableFields: Object.freeze(['nickname', 'gender', 'signature', 'avatar']),
+    get current() { return client.currentSelfProfile ?? {}; },
+    async read({ signal }) {
+      const self = await account(signal);
+      const raw = await client.requestApi({ action: 'get_stranger_info', params: { user_id: String(self.user_id), no_cache: true }, signal }) as NapcatUserProfile;
+      if (!raw || String(raw.user_id) !== String(self.user_id)) throw new Error('NapCat returned another account profile');
+      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.long_nick === 'string' ? { signature: raw.long_nick } : {}),
+      };
+      return profile;
+    },
+    async write({ change, signal }) {
+      let action: string;
+      let params: Record<string, unknown>;
+      switch (change.field) {
+        case 'nickname': action = 'set_qq_profile'; params = { nickname: change.value }; break;
+        case 'gender': {
+          if (change.value === 'other') return { status: 'rejected', message: 'NapCat supports male, female or unknown gender' };
+          // The native API requires nickname even when only changing sex.
+          let self: NapcatAccount;
+          try { self = await account(signal); }
+          catch (cause) {
+            throw new EndpointDeliveryError('endpoint_unavailable',
+              'NapCat profile change was not sent: self account lookup failed', 'not_sent', { cause });
+          }
+          action = 'set_qq_profile';
+          params = { nickname: self.nickname, sex: change.value === 'male' ? 1 : change.value === 'female' ? 2 : 0 };
+          break;
+        }
+        case 'signature': action = 'set_self_longnick'; params = { longNick: change.value }; break;
+        case 'avatar': {
+          if (change.value.kind === 'file') {
+            return { status: 'rejected', message: 'NapCat avatar requires resolved image bytes, URL or remote path' };
+          }
+          action = 'set_qq_avatar';
+          params = { file: change.value.kind === 'base64' ? `base64://${change.value.value}` : change.value.value };
+          break;
+        }
+        default: return { status: 'rejected', message: `NapCat cannot safely update ${change.field}` };
+      }
+      const result = await client.requestApi({ action, params, signal }) as { result?: number; errMsg?: string } | null | undefined;
+      if (result && typeof result.result === 'number' && result.result !== 0) {
+        return { status: 'rejected', message: result.errMsg ?? 'NapCat rejected the profile change' };
+      }
+      return change.field === 'avatar' ? { status: 'updated' }
+        : { status: 'updated', profile: { [change.field]: change.value } };
+    },
+  });
+}

package/src/ws-endpoint.ts

@@ -17,6 +17,7 @@ import {
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { createNapcatSelfProfile } from './self-profile.js';
 import {
   InboundMessageDeduper,
   isNapCatBotMentioned,
@@ -77,6 +78,7 @@ export class NapCatWsEndpoint extends NapcatClient implements Endpoint {
       close: () => this.#close(), stop: () => this.#stop(),
       send: request => this.#send(request),
       management: this.#management, control: this.#control, content: this.#content,
+      profile: createNapcatSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
       get transportState() { return readTransportState(); },
     });
     this.on('event', event => {

package/src/wss-endpoint.ts

@@ -16,6 +16,7 @@ import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
 import { createNapCatEndpointManagement } from './endpoint-management.js';
+import { createNapcatSelfProfile } from './self-profile.js';
 import {
   InboundMessageDeduper,
   isNapCatBotMentioned,
@@ -76,6 +77,7 @@ export class NapCatWssEndpoint extends NapcatClient implements Endpoint {
       close: () => this.#close(), stop: () => this.#stop(),
       send: request => this.#send(request),
       management: this.#management, control: this.#control, content: this.#content,
+      profile: createNapcatSelfProfile(this, id => this[endpointSpec].reportSelfUserId(id)),
       get transportState() { return readTransportState(); },
     });
     this.on('event', event => {