Move external-shims.d.ts to files in tsconfig

external-shims.d.ts was moved from the include array to the files array in tsconfig.json to ensure it is always included explicitly. This change clarifies the intent and may help with TypeScript's file resolution.

Refactor napcat-types package and update plugin deps

Refactored napcat-types to provide more accurate shims, added real type dependencies, and improved build/test scripts. Updated napcat-plugin and napcat-plugin-builtin to depend on napcat-types instead of napcat-onebot. Adjusted imports in affected packages to use napcat-types, and updated pnpm-lock.yaml accordingly.

Add build and test scripts to napcat-types package

Introduced 'build' and 'test' scripts in the napcat-types package.json for easier development and testing. Also updated dependencies in the lockfile.

packages/napcat-plugin-builtin/index.ts

@@ -1,7 +1,7 @@
-import type { ActionMap } from 'napcat-onebot/action';
-import { EventType } from 'napcat-onebot/event/OneBotEvent';
-import type { PluginModule } from 'napcat-onebot/network/plugin';
-import type { OB11Message, OB11PostSendMsg } from 'napcat-onebot/types/message';
+import type { ActionMap } from 'napcat-types/dist/napcat-onebot/action/index';
+import { EventType } from 'napcat-types/dist/napcat-onebot/event/index';
+import type { PluginModule } from 'napcat-types/dist/napcat-onebot/network/plugin-manger';
+import type { OB11Message, OB11PostSendMsg } from 'napcat-types/dist/napcat-onebot/types/index';
 
 let actions: ActionMap | undefined = undefined;
 let startTime: number = Date.now();

packages/napcat-plugin-builtin/package.json

@@ -6,7 +6,7 @@
   "description": "NapCat 内置插件",
   "author": "NapNeko",
   "dependencies": {
-    "napcat-onebot": "workspace:*"
+    "napcat-types": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^22.0.1"

packages/napcat-plugin/index.ts

@@ -1,6 +1,6 @@
-import type { createActionMap } from 'napcat-onebot/action';
-import { EventType } from 'napcat-onebot/event/OneBotEvent';
-import type { PluginModule } from 'napcat-onebot/network/plugin';
+import type { createActionMap } from 'napcat-types/dist/napcat-onebot/action/index.js';
+import { EventType } from 'napcat-types/dist/napcat-onebot/event/index.js';
+import type { PluginModule } from 'napcat-types/dist/napcat-onebot/network/plugin-manger';
 
 /**
  * 导入 napcat 包时候不使用 @/napcat...，直接使用 napcat...

packages/napcat-plugin/package.json

@@ -5,7 +5,7 @@
   "main": "index.mjs",
   "description": "一个高级的 NapCat 插件示例",
   "dependencies": {
-    "napcat-onebot": "workspace:*"
+    "napcat-types": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^22.0.1"

packages/napcat-types/external-shims.d.ts

@@ -1,99 +1,98 @@
-// 外部模块全部声明为 unknown，确保类型包不依赖外部环境
+// 外部模块 shim，提供最小的可运行值和类型，避免类型包依赖外部环境
 // node:* 模块移除 mock，使用系统自带类型
 
-declare module 'ws' {
-  export class WebSocket { }
-  export class WebSocketServer { }
-  const _ws_default: unknown;
-  export default _ws_default;
-}
-
-declare module 'express' {
-  export interface Request { }
-  export interface Response { }
-  export interface NextFunction { }
-  export interface Express { }
-  const _express_default: unknown;
-  export default _express_default;
-}
-
-declare module 'winston' {
-  export const Logger: unknown;
-  export const format: unknown;
-  export const transports: unknown;
-  const _winston_default: unknown;
-  export default _winston_default;
-}
+// (ws/express/winston) now provided by real type deps (@types/ws, @types/express, winston)
 
 declare module 'ffmpeg-static' {
-  const _ffmpeg_static_default: unknown;
+  const _ffmpeg_static_default: any;
   export default _ffmpeg_static_default;
 }
 
 declare module 'fluent-ffmpeg' {
-  const _fluent_ffmpeg_default: unknown;
+  const _fluent_ffmpeg_default: any;
   export default _fluent_ffmpeg_default;
 }
 
 declare module 'sharp' {
-  const _sharp_default: unknown;
+  const _sharp_default: any;
   export default _sharp_default;
 }
 
 declare module 'uuid' {
-  export const v4: unknown;
+  export function v4 (...args: any[]): string;
 }
 
 declare module 'axios' {
-  const _axios_default: unknown;
+  const _axios_default: any;
   export default _axios_default;
 }
 
 declare module 'body-parser' {
-  const _body_parser_default: unknown;
+  const _body_parser_default: any;
   export default _body_parser_default;
 }
 
 declare module 'cors' {
-  const _cors_default: unknown;
+  const _cors_default: any;
   export default _cors_default;
 }
 
 declare module 'file-type' {
-  export const fileTypeFromFile: unknown;
+  export function fileTypeFromFile (path: string): Promise<any>;
 }
 
 declare module 'image-size' {
-  const _image_size_default: unknown;
+  const _image_size_default: any;
   export default _image_size_default;
 }
 
 declare module 'jimp' {
-  const _jimp_default: unknown;
+  const _jimp_default: any;
   export default _jimp_default;
 }
 
 declare module 'qrcode' {
-  const _qrcode_default: unknown;
+  const _qrcode_default: any;
   export default _qrcode_default;
 }
 
 declare module 'yaml' {
-  export const parse: unknown;
-  export const stringify: unknown;
+  export const parse: (...args: any[]) => any;
+  export const stringify: (...args: any[]) => any;
 }
 
 declare module 'async-mutex' {
-  const _async_mutex_default: unknown;
+  export class Mutex {
+    acquire (): Promise<() => void>;
+    runExclusive<T> (callback: () => T | Promise<T>): Promise<T>;
+  }
+  export class Semaphore {
+    acquire (): Promise<[() => void, number]>;
+    runExclusive<T> (callback: () => T | Promise<T>): Promise<T>;
+    release (): void;
+  }
+  const _async_mutex_default: { Mutex: typeof Mutex; Semaphore: typeof Semaphore; };
   export default _async_mutex_default;
-  export interface Mutex { }
-  export interface Semaphore { }
 }
 
 declare module '@sinclair/typebox' {
-  export const Type: unknown;
-  export type Static<T = any> = any;
-  export interface TSchema { }
+  export const Type: {
+    Object: (...args: any[]) => any;
+    String: (...args: any[]) => any;
+    Number: (...args: any[]) => any;
+    Boolean: (...args: any[]) => any;
+    Array: (...args: any[]) => any;
+    Union: (...args: any[]) => any;
+    Literal: (...args: any[]) => any;
+    Optional: (...args: any[]) => any;
+    Record: (...args: any[]) => any;
+    Any: (...args: any[]) => any;
+  } & any;
+
+  // Make Static<> actually resolve to a structural type so optional properties work.
+  export type Static<T> = T extends { static: infer S; } ? S : any;
+
+  export interface TSchema { static?: any; }
   export interface TObject<T = any> extends TSchema { }
   export interface TOptional<T = any> extends TSchema { }
   export interface TNumber extends TSchema { }
@@ -109,22 +108,71 @@ declare module '@sinclair/typebox' {
 }
 
 declare module 'napcat-protobuf' {
-  export type NapProtoEncodeStructType<T> = unknown;
-  export type NapProtoDecodeStructType<T> = unknown;
-  export type ScalarProtoFieldType<T> = unknown;
-  export type MessageProtoFieldType<T> = unknown;
-  export type ScalarType = unknown;
+  export class NapProtoMsg<T = any> {
+    constructor (schema: any);
+    decode (buffer: any): T;
+    encode (value: any): Uint8Array;
+  }
+  export function ProtoField (...args: any[]): any;
+  export type NapProtoEncodeStructType<T> = any;
+  export type NapProtoDecodeStructType<T> = any;
+  export type ScalarProtoFieldType<T> = any;
+  export type MessageProtoFieldType<T> = any;
+  export const ScalarType: {
+    STRING: any;
+    INT64: any;
+    INT32: any;
+    UINT32: any;
+    UINT64: any;
+    BYTES: any;
+    BOOL: any;
+    [key: string]: any;
+  };
 }
 
 declare module 'inversify' {
-  const _inversify_default: unknown;
+  export class Container {
+    bind: (...args: any[]) => any;
+    get: <T = any>(id: any) => T;
+  }
+  export function injectable (...args: any[]): any;
+  export function inject (...args: any[]): any;
+  export interface ServiceIdentifier<T = any> { }
+  const _inversify_default: any;
   export default _inversify_default;
-  export interface Container { }
-  export interface ServiceIdentifier<T> { }
 }
 
 declare module 'ajv' {
-  const _ajv_default: unknown;
-  export default _ajv_default;
-  export interface AnySchema { }
+  export interface AnySchema { [key: string]: any; }
+
+  export interface ErrorObject {
+    keyword: string;
+    instancePath: string;
+    schemaPath: string;
+    params: any;
+    message?: string;
+  }
+
+  export interface ValidateFunction<T = any> {
+    (data: any): data is T;
+    errors: ErrorObject[] | null;
+  }
+
+  class Ajv {
+    constructor (...args: any[]);
+    compile<T = any> (schema: any): ValidateFunction<T>;
+    validate (schemaOrRef: any, data: any): boolean;
+    errorsText (errors?: any, options?: any): string;
+    errors: ErrorObject[] | null;
+  }
+
+  export default Ajv;
+  export { Ajv, ValidateFunction, ErrorObject };
+}
+
+declare module 'ip' {
+  export function toBuffer (ip: any, buffer?: Buffer, offset?: number): Buffer;
+  export function toString (buffer: any, offset?: number, length?: number): string;
+  const _ip_default: any;
+  export default _ip_default;
 }

packages/napcat-types/index.ts

@@ -4,3 +4,6 @@ export * from '../napcat-core/index';
 
 // 聚合导出 OneBot 的所有内容
 export * from '../napcat-onebot/index';
+
+// Ensure the shims file exists next to the emitted JS as well.
+export type { };

packages/napcat-types/package.json

@@ -3,11 +3,26 @@
   "version": "0.0.1",
   "private": true,
   "type": "module",
-  "main": "./index.ts",
-  "types": "./index.ts",
+  "types": "./dist/napcat-types/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json && tsc-alias --project tsconfig.json --outDir dist",
+    "test": "pnpm -s exec tsc --project tsconfig.json --noEmit"
+  },
   "dependencies": {
     "napcat-core": "workspace:*",
-    "napcat-onebot": "workspace:*"
+    "napcat-onebot": "workspace:*",
+    "@types/node": "^22.10.7",
+    "@types/express": "^4.17.21",
+    "@types/ws": "^8.5.12",
+    "@types/cors": "^2.8.17",
+    "@types/multer": "^1.4.12",
+    "@types/winston": "^2.4.4",
+    "@types/yaml": "^1.9.7",
+    "@types/ip": "^1.1.3",
+    "compressing": "^1.10.3"
   },
   "devDependencies": {
     "tsc-alias": "^1.8.16"

packages/napcat-types/test-dist.ts

@@ -1,12 +1,12 @@
-import { 
-    ChatType, 
-    ElementType, 
-    NapCatCore, 
-    NTQQMsgApi, 
-    NapCatOneBot11Adapter, 
-    OB11Message,
-    OB11BaseMessageEvent,
-    OB11BaseMetaEvent
+import {
+  ChatType,
+  ElementType,
+  NapCatCore,
+  NTQQMsgApi,
+  NapCatOneBot11Adapter,
+  OB11Message,
+  OB11BaseMessageEvent,
+  OB11BaseMetaEvent,
 } from './dist/napcat-types/index';
 
 console.log('--- NapCat Comprehensive Type Test ---');
@@ -29,10 +29,10 @@ console.log('OneBot types and events access check: OK');
 
 // 4. 验证导出完整性
 if (ChatType.KCHATTYPEGROUP === 2 && ElementType.TEXT === 1) {
-    console.log('\n✅ ALL TESTS PASSED: Types, Enums and Events are correctly exported and accessible.');
+  console.log('\n✅ ALL TESTS PASSED: Types, Enums and Events are correctly exported and accessible.');
 } else {
-    console.error('\n❌ TESTS FAILED: Enum value mismatch.');
-    throw new Error('Test Failed');
+  console.error('\n❌ TESTS FAILED: Enum value mismatch.');
+  throw new Error('Test Failed');
 }
 
 

packages/napcat-types/tsconfig.json

@@ -7,6 +7,8 @@
     "declaration": true,
     "emitDeclarationOnly": true,
     "skipLibCheck": true,
+    "stripInternal": true,
+    "noEmitOnError": false,
     "paths": {
       "napcat-core": [
         "../napcat-core/index.ts"
@@ -33,11 +35,13 @@
   },
   "include": [
     "./index.ts",
-    "./external-shims.d.ts",
     "../napcat-core/**/*.ts",
     "../napcat-onebot/**/*.ts",
     "../napcat-common/**/*.ts"
   ],
+  "files": [
+    "./external-shims.d.ts"
+  ],
   "exclude": [
     "node_modules",
     "dist"