@zhin.js/core 1.0.25 → 1.0.26

package/src/built/config.ts

@@ -1,142 +1,252 @@
+/**
+ * ConfigFeature
+ * 配置管理服务，继承自 Feature 抽象类
+ * 保留原有 ConfigLoader / ConfigService 逻辑，增加 addConfig 扩展
+ */
 import path from "node:path";
 import fs from "node:fs";
-import { stringify as stringifyYaml,parse as parseYaml } from "yaml";
+import { stringify as stringifyYaml, parse as parseYaml } from "yaml";
 import { Schema } from "@zhin.js/schema";
-export class ConfigLoader<T extends object>{
-    #data: T;
-    get data(): T {
-        return this.#proxy(this.#data,this);
-    }
-    get raw(): T {
-        return this.#data;
-    }
-    get extension() {
-        return path.extname(this.filename).toLowerCase();
-    }
-    constructor(public filename: string, public initial:T, public schema?: Schema<T>) {
-        this.#data = this.initial;
-    }
-    #proxy<R extends object>(data: R, loader: ConfigLoader<T>) {
-        return new Proxy(data, {
-            get(target, prop, receiver) {
-                // 对于特殊属性（如 Symbol、prototype 等），直接返回原始值
-                if (typeof prop === 'symbol' || prop === 'constructor' || prop === 'prototype') {
-                    return Reflect.get(target, prop, receiver);
-                }
-                
-                const result= Reflect.get(target, prop, receiver);
-                
-                // 对于函数属性（如数组的 map、filter 等），直接返回，不进行代理
-                if (typeof result === 'function') {
-                    return result;
-                }
-                
-                // 对于对象和数组，递归代理（但排除函数）
-                if(result instanceof Object && result!==null && typeof result !== 'function') {
-                    return loader.#proxy(result,loader);
-                }
-                
-                // 处理环境变量占位符
-                if(typeof result==='string') {
-                    if(result.startsWith('\\${') && result.endsWith('}')) return result.slice(1);
-                    if(/^\$\{(.*)\}$/.test(result)){
-                        const content = result.slice(2, -1);
-                        const [key, ...rest] = content.split(':');
-                        const defaultValue = rest.length > 0 ? rest.join(':') : undefined;
-                        return process.env[key] ?? defaultValue ?? (loader.initial as any)[key] ?? result;
-                    }
-                }
-                return result;
-            },
-            set(target, prop, value, receiver) {
-                const result= Reflect.set(target, prop, value, receiver);
-                loader.save(loader.filename);
-                return result;
-            },
-            deleteProperty(target, prop) {
-                const result= Reflect.deleteProperty(target, prop);
-                loader.save(loader.filename);
-                return result;
-            }
-        });
-    }
-    load() {
-        const fullPath=path.resolve(process.cwd(), this.filename);
-        if (!fs.existsSync(fullPath)) {
-            this.save(fullPath);
+import { Feature, FeatureJSON } from "../feature.js";
+import { getPlugin } from "../plugin.js";
+
+// ============================================================================
+// ConfigLoader（保持不变）
+// ============================================================================
+
+export class ConfigLoader<T extends object> {
+  #data: T;
+  get data(): T {
+    return this.#proxy(this.#data, this);
+  }
+  get raw(): T {
+    return this.#data;
+  }
+  get extension() {
+    return path.extname(this.filename).toLowerCase();
+  }
+  constructor(public filename: string, public initial: T, public schema?: Schema<T>) {
+    this.#data = this.initial;
+  }
+  #proxy<R extends object>(data: R, loader: ConfigLoader<T>) {
+    return new Proxy(data, {
+      get(target, prop, receiver) {
+        if (typeof prop === 'symbol' || prop === 'constructor' || prop === 'prototype') {
+          return Reflect.get(target, prop, receiver);
         }
-        const content = fs.readFileSync(fullPath, "utf-8");
-        let rawConfig: any;
-        switch (this.extension) {
-            case ".json":
-                rawConfig = JSON.parse(content);
-                break;
-            case ".yaml":
-            case ".yml":
-                rawConfig = parseYaml(content);
-                break;
+
+        const result = Reflect.get(target, prop, receiver);
+
+        if (typeof result === 'function') {
+          return result;
         }
-        if(this.schema){
-            this.#data = this.schema(rawConfig || this.initial) as T;
-        }else{
-            this.#data = rawConfig as T;
+
+        if (result instanceof Object && result !== null && typeof result !== 'function') {
+          return loader.#proxy(result, loader);
         }
-    }
-    save(fullPath: string) {
-        switch (this.extension) {
-            case ".json":
-                fs.writeFileSync(fullPath, JSON.stringify(this.#data, null, 2));
-                break;
-            case ".yaml":
-            case ".yml":
-                fs.writeFileSync(fullPath, stringifyYaml(this.#data));
-                break;
+
+        if (typeof result === 'string') {
+          if (result.startsWith('\\${') && result.endsWith('}')) return result.slice(1);
+          if (/^\$\{(.*)\}$/.test(result)) {
+            const content = result.slice(2, -1);
+            const [key, ...rest] = content.split(':');
+            const defaultValue = rest.length > 0 ? rest.join(':') : undefined;
+            return process.env[key] ?? defaultValue ?? (loader.initial as any)[key] ?? result;
+          }
         }
-    }
-}
-export namespace ConfigLoader{
-    export const supportedExtensions = [".json", ".yaml", ".yml"];
-    export function load<T extends object>(filename: string, initial?:T, schema?: Schema<T>) {
-        const result = new ConfigLoader<T>(filename, initial??{} as T, schema);
-        result.load();
         return result;
+      },
+      set(target, prop, value, receiver) {
+        const result = Reflect.set(target, prop, value, receiver);
+        loader.save(loader.filename);
+        return result;
+      },
+      deleteProperty(target, prop) {
+        const result = Reflect.deleteProperty(target, prop);
+        loader.save(loader.filename);
+        return result;
+      }
+    });
+  }
+  load() {
+    const fullPath = path.resolve(process.cwd(), this.filename);
+    if (!fs.existsSync(fullPath)) {
+      this.save(fullPath);
     }
-}
-export class ConfigService{
-    configs: Map<string, ConfigLoader<any>> = new Map();
-    constructor() {
+    const content = fs.readFileSync(fullPath, "utf-8");
+    let rawConfig: any;
+    switch (this.extension) {
+      case ".json":
+        rawConfig = JSON.parse(content);
+        break;
+      case ".yaml":
+      case ".yml":
+        rawConfig = parseYaml(content);
+        break;
     }
-    load<T extends object>(filename: string, initial?:Partial<T>, schema?: Schema<T>) {
-        const ext = path.extname(filename).toLowerCase();
-        if (!ConfigLoader.supportedExtensions.includes(ext)) {
-            throw new Error(`不支持的配置文件格式: ${ext}`);
-        }
-        const config = ConfigLoader.load(filename, initial as T, schema);
-        this.configs.set(filename, config);
-        return config;
+    if (this.schema) {
+      this.#data = this.schema(rawConfig || this.initial) as T;
+    } else {
+      this.#data = rawConfig as T;
     }
-    get<T extends object>(filename: string, initial?:Partial<T>, schema?: Schema<T>): T {
-        if(!this.configs.has(filename)) this.load(filename, initial, schema);
-        const config = this.configs.get(filename);
-        if(!config) throw new Error(`配置文件 ${filename} 未加载`);
-        return config.data as T;
+  }
+  save(fullPath: string) {
+    switch (this.extension) {
+      case ".json":
+        fs.writeFileSync(fullPath, JSON.stringify(this.#data, null, 2));
+        break;
+      case ".yaml":
+      case ".yml":
+        fs.writeFileSync(fullPath, stringifyYaml(this.#data));
+        break;
     }
-    getRaw<T extends object>(filename: string, initial?:Partial<T>, schema?: Schema<T>): T {
-        if(!this.configs.has(filename)) this.load(filename, initial, schema);
-        const config = this.configs.get(filename);
-        if(!config) throw new Error(`配置文件 ${filename} 未加载`);
-        return config.raw as T;
+  }
+}
+
+export namespace ConfigLoader {
+  export const supportedExtensions = [".json", ".yaml", ".yml"];
+  export function load<T extends object>(filename: string, initial?: T, schema?: Schema<T>) {
+    const result = new ConfigLoader<T>(filename, initial ?? {} as T, schema);
+    result.load();
+    return result;
+  }
+}
+
+// ============================================================================
+// ConfigFeature
+// ============================================================================
+
+/**
+ * 配置项声明记录
+ */
+export interface ConfigRecord {
+  key: string;
+  defaultValue: any;
+}
+
+/**
+ * ConfigFeature 扩展方法类型
+ */
+export interface ConfigContextExtensions {
+  /** 声明插件配置项（key + 默认值），如果配置文件中不存在则写入默认值 */
+  addConfig(key: string, defaultValue: any): () => void;
+}
+
+declare module "../plugin.js" {
+  namespace Plugin {
+    interface Extensions extends ConfigContextExtensions {}
+    interface Contexts {
+      config: ConfigFeature;
     }
-    /**
-     * 更新配置文件内容
-     * @param filename 配置文件名
-     * @param data 新的配置数据
-     */
-    set<T extends object>(filename: string, data: T): void {
-        const config = this.configs.get(filename);
-        if(!config) throw new Error(`配置文件 ${filename} 未加载`);
-        // 直接更新内部数据（会触发 Proxy 的 set 拦截器并自动保存）
-        Object.assign(config.raw, data);
-        config.save(path.resolve(process.cwd(), filename));
+  }
+}
+
+export class ConfigFeature extends Feature<ConfigRecord> {
+  readonly name = 'config' as const;
+  readonly icon = 'Settings';
+  readonly desc = '配置';
+
+  /** 内部配置文件管理 */
+  readonly configs: Map<string, ConfigLoader<any>> = new Map();
+
+  /** 主配置文件名（第一个加载的配置文件） */
+  #primaryConfigFile: string = '';
+
+  /**
+   * 加载配置文件
+   */
+  load<T extends object>(filename: string, initial?: Partial<T>, schema?: Schema<T>): ConfigLoader<T> {
+    const ext = path.extname(filename).toLowerCase();
+    if (!ConfigLoader.supportedExtensions.includes(ext)) {
+      throw new Error(`不支持的配置文件格式: ${ext}`);
+    }
+    const config = ConfigLoader.load(filename, initial as T, schema);
+    this.configs.set(filename, config);
+    if (!this.#primaryConfigFile) {
+      this.#primaryConfigFile = filename;
     }
-}
+    return config;
+  }
+
+  /**
+   * 获取配置数据（代理模式，自动保存）
+   */
+  get<T extends object>(filename: string, initial?: Partial<T>, schema?: Schema<T>): T {
+    if (!this.configs.has(filename)) this.load(filename, initial, schema);
+    const config = this.configs.get(filename);
+    if (!config) throw new Error(`配置文件 ${filename} 未加载`);
+    return config.data as T;
+  }
+
+  /**
+   * 获取原始配置数据
+   */
+  getRaw<T extends object>(filename: string, initial?: Partial<T>, schema?: Schema<T>): T {
+    if (!this.configs.has(filename)) this.load(filename, initial, schema);
+    const config = this.configs.get(filename);
+    if (!config) throw new Error(`配置文件 ${filename} 未加载`);
+    return config.raw as T;
+  }
+
+  /**
+   * 更新配置文件内容
+   */
+  set<T extends object>(filename: string, data: T): void {
+    const config = this.configs.get(filename);
+    if (!config) throw new Error(`配置文件 ${filename} 未加载`);
+    Object.assign(config.raw, data);
+    config.save(path.resolve(process.cwd(), filename));
+  }
+
+  /**
+   * 序列化为 JSON
+   */
+  toJSON(pluginName?: string): FeatureJSON {
+    const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+    return {
+      name: this.name,
+      icon: this.icon,
+      desc: this.desc,
+      count: list.length,
+      items: list.map(r => ({
+        name: r.key,
+        // 不暴露 defaultValue 以防止泄露密钥/令牌
+      })),
+    };
+  }
+
+  /**
+   * 提供给 Plugin.prototype 的扩展方法
+   */
+  get extensions() {
+    const feature = this;
+    return {
+      addConfig(key: string, defaultValue: any) {
+        const plugin = getPlugin();
+
+        // 尝试写入主配置文件（如果 key 不存在）
+        if (feature.#primaryConfigFile) {
+          const config = feature.configs.get(feature.#primaryConfigFile);
+          if (config) {
+            const raw = config.raw as Record<string, any>;
+            if (!(key in raw)) {
+              raw[key] = defaultValue;
+              config.save(path.resolve(process.cwd(), feature.#primaryConfigFile));
+            }
+          }
+        }
+
+        const record: ConfigRecord = { key, defaultValue };
+        const dispose = feature.add(record, plugin.name);
+        plugin.recordFeatureContribution(feature.name, key);
+        plugin.onDispose(dispose);
+        return dispose;
+      },
+    };
+  }
+}
+
+/**
+ * @deprecated Use ConfigFeature instead
+ */
+export const ConfigService = ConfigFeature;

package/src/built/cron.ts

@@ -1,9 +1,10 @@
 /**
- * Cron Context
- * 管理所有插件注册的定时任务
+ * CronFeature
+ * 管理所有插件注册的定时任务，继承自 Feature 抽象类
  */
+import { Feature, FeatureJSON } from "../feature.js";
 import { Cron } from "../cron.js";
-import { Context, Plugin, getPlugin } from "../plugin.js";
+import { Plugin, getPlugin } from "../plugin.js";
 
 /**
  * CronContext 扩展方法类型
@@ -18,123 +19,138 @@ declare module "../plugin.js" {
   namespace Plugin {
     interface Extensions extends CronContextExtensions {}
     interface Contexts {
-      cron: CronService;
+      cron: CronFeature;
     }
   }
 }
 
 /**
- * 定时任务服务数据
+ * 定时任务服务 Feature
  */
-export interface CronService {
-  /** 任务列表 */
-  readonly items: Cron[];
+export class CronFeature extends Feature<Cron> {
+  readonly name = 'cron' as const;
+  readonly icon = 'Clock';
+  readonly desc = '定时任务';
+
   /** 按 ID/表达式 索引 */
-  readonly byName: Map<string, Cron>;
-  /** 添加任务 */
-  add(cron: Cron, pluginName: string): () => void;
-  /** 移除任务 */
-  remove(cron: Cron): boolean;
-  /** 按名称获取 */
-  get(id: string): Cron | undefined;
-  /** 停止所有任务 */
-  stopAll(): void;
-  /** 启动所有任务 */
-  startAll(): void;
-  /** 获取状态 */
+  readonly byName = new Map<string, Cron>();
+
+  /**
+   * 添加定时任务，自动启动
+   */
+  add(cron: Cron, pluginName: string): () => void {
+    this.byName.set(cron.id || cron.cronExpression, cron);
+    // 自动启动
+    if (!cron.running) {
+      cron.run();
+    }
+    return super.add(cron, pluginName);
+  }
+
+  /**
+   * 移除定时任务，自动停止
+   */
+  remove(cron: Cron): boolean {
+    if (cron.running) {
+      cron.stop();
+    }
+    this.byName.delete(cron.id || cron.cronExpression);
+    return super.remove(cron);
+  }
+
+  /**
+   * 按 ID/表达式 获取
+   */
+  get(id: string): Cron | undefined {
+    return this.byName.get(id);
+  }
+
+  /**
+   * 停止所有任务
+   */
+  stopAll(): void {
+    for (const cron of this.items) {
+      if (cron.running) {
+        cron.stop();
+      }
+    }
+  }
+
+  /**
+   * 启动所有任务
+   */
+  startAll(): void {
+    for (const cron of this.items) {
+      if (!cron.running && !cron.disposed) {
+        cron.run();
+      }
+    }
+  }
+
+  /**
+   * 获取所有任务状态
+   */
   getStatus(): Array<{
     expression: string;
     running: boolean;
     nextExecution: Date | null;
     plugin: string;
-  }>;
-}
-
-/**
- * 创建定时任务 Context
- */
-export function createCronService(): Context<'cron', CronContextExtensions> {
-  const items: Cron[] = [];
-  const byName = new Map<string, Cron>();
-  const pluginMap = new Map<Cron, string>();
-  
-  const value: CronService = {
-    items,
-    byName,
-    
-    add(cron, pluginName) {
-      items.push(cron);
-      byName.set(cron.id || cron.cronExpression, cron);
-      pluginMap.set(cron, pluginName);
-      // 自动启动
-      if (!cron.running) {
-        cron.run();
-      }
-      return () => value.remove(cron);
-    },
-    
-    remove(cron) {
-      const index = items.indexOf(cron);
-      if (index !== -1) {
-        // 自动停止
-        if (cron.running) {
-          cron.stop();
+  }> {
+    return this.items.map(cron => {
+      // 从 pluginItems 中找到对应的插件名
+      let pluginName = 'unknown';
+      for (const [name, items] of this.pluginItems) {
+        if (items.includes(cron)) {
+          pluginName = name;
+          break;
         }
-        items.splice(index, 1);
-        byName.delete(cron.id || cron.cronExpression);
-        pluginMap.delete(cron);
-        return true;
       }
-      return false;
-    },
-    
-    get(id) {
-      return byName.get(id);
-    },
-    
-    stopAll() {
-      for (const cron of items) {
-        if (cron.running) {
-          cron.stop();
-        }
-      }
-    },
-    
-    startAll() {
-      for (const cron of items) {
-        if (!cron.running && !cron.disposed) {
-          cron.run();
-        }
-      }
-    },
-    
-    getStatus() {
-      return items.map(cron => ({
+      return {
         expression: cron.cronExpression,
         running: cron.running,
         nextExecution: cron.running ? cron.getNextExecutionTime() : null,
-        plugin: pluginMap.get(cron) || 'unknown',
-      }));
-    }
-  };
-  
-  return {
-    name: 'cron',
-    description: '定时任务服务',
-    value,
-    
-    dispose() {
-      value.stopAll();
-    },
-    
-    extensions: {
+        plugin: pluginName,
+      };
+    });
+  }
+
+  /**
+   * 生命周期: 销毁时停止所有任务
+   */
+  dispose(): void {
+    this.stopAll();
+  }
+
+  /**
+   * 序列化为 JSON
+   */
+  toJSON(pluginName?: string): FeatureJSON {
+    const list = pluginName ? this.getByPlugin(pluginName) : this.items;
+    return {
+      name: this.name,
+      icon: this.icon,
+      desc: this.desc,
+      count: list.length,
+      items: list.map(c => ({
+        expression: c.cronExpression,
+        running: c.running,
+      })),
+    };
+  }
+
+  /**
+   * 提供给 Plugin.prototype 的扩展方法
+   */
+  get extensions() {
+    const feature = this;
+    return {
       addCron(cron: Cron) {
         const plugin = getPlugin();
-        const dispose = value.add(cron, plugin.name);
+        const dispose = feature.add(cron, plugin.name);
+        plugin.recordFeatureContribution(feature.name, cron.id || cron.cronExpression);
         plugin.onDispose(dispose);
         return dispose;
-      }
-    }
-  };
+      },
+    };
+  }
 }
-