@zhin.js/core 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @zhin.js/core
+
+## 1.0.2
+
+### Patch Changes
+
+- 15fc934: fix: 支持 jsx
+- 3ecd487: fix: 函数式组件,更新文档
+
+## 1.0.1
+
+### Patch Changes
+
+- efdd58a: fix: init
+- Updated dependencies [efdd58a]
+  - @zhin.js/hmr@1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,159 +1,380 @@
 # @zhin.js/core
 
-Zhin Bot Framework的核心包，基于HMR系统构建的机器人框架核心实现。
+Zhin 机器人框架核心包，基于 HMR（热模块替换）系统构建的现代化机器人开发框架。
 
-## 主要组件
+## 核心特性
 
-### App
+- 🔥 **热模块替换**: 基于 @zhin.js/hmr 的热更新系统
+- 🔌 **插件化架构**: 完整的插件生命周期管理
+- 🤖 **多平台适配**: 支持多种聊天平台适配器
+- 🎯 **命令系统**: 基于 segment-matcher 的智能消息匹配
+- 🧩 **组件系统**: 支持模板渲染、属性绑定、插槽的组件化开发
+- ⚡ **中间件链**: 灵活的消息处理中间件机制
+- 🔧 **TypeScript**: 完整的类型支持
 
-继承自HMR的应用核心类，提供：
-- 插件管理
-- 配置管理
-- 适配器管理
-- 消息路由
-- 热更新支持
+## 核心组件
+
+### App 类
+
+应用核心类，继承自 `HMR<Plugin>`：
 
 ```typescript
 import { createApp } from '@zhin.js/core'
 
+// 创建应用实例
 const app = await createApp({
   plugin_dirs: ['./plugins'],
-  plugins: ['plugin1'],
+  plugins: ['my-plugin'],
   bots: [{
-    context: 'adapter-name',
-    name: 'bot-name',
-    config: {}
-  }]
+    context: 'onebot11',
+    name: 'my-bot',
+    url: 'ws://localhost:8080'
+  }],
+  debug: true
 })
 
+// 启动应用
 await app.start()
 ```
 
-### Plugin
+**主要功能**：
+- 插件生命周期管理
+- 配置文件加载和管理
+- 适配器和机器人实例管理
+- 消息路由和分发
+- 热更新监听
 
-继承自Dependency的插件基类，提供：
-- 中间件系统
-- 事件监听
-- 定时任务
-- 上下文管理
-- 消息处理
+### Plugin 类
+
+插件基类，继承自 `Dependency<Plugin>`：
 
 ```typescript
-import { usePlugin, onMessage, addMiddleware } from '@zhin.js/core'
+import { usePlugin, addMiddleware, addCommand, addComponent } from '@zhin.js/core'
 
 const plugin = usePlugin()
 
+// 添加中间件
 addMiddleware(async (message, next) => {
-  console.log('收到消息:', message)
+  console.log(`[${plugin.name}] 收到消息:`, message.raw)
   await next()
 })
 
-onMessage(async (message) => {
-  // 处理消息
-})
+// 添加命令
+addCommand(new MessageCommand('hello')
+  .action(async (message) => {
+    return '你好！'
+  })
+)
 ```
 
-### Adapter
+**主要功能**：
+- 中间件链管理
+- 命令注册和处理
+- 组件管理
+- 事件监听和分发
+- 消息发送前处理 (beforeSend)
+
+### Adapter 类
+
+适配器基类，用于连接不同聊天平台：
 
-适配器基类，用于实现不同平台的机器人适配：
 ```typescript
-import { Adapter, Bot } from '@zhin.js/core'
+import { Adapter, Bot, Plugin } from '@zhin.js/core'
 
-class MyAdapter extends Adapter {
-  constructor() {
-    super('my-adapter', (plugin, config) => new MyBot(plugin, config))
+class MyBot implements Bot {
+  constructor(public plugin: Plugin, public config: BotConfig) {}
+  
+  async connect() {
+    // 连接逻辑
+  }
+  
+  async disconnect() {
+    // 断开连接逻辑
+  }
+  
+  async sendMessage(options: SendOptions) {
+    // 发送消息逻辑
   }
 }
+
+// 注册适配器
+const adapter = new Adapter('my-platform', MyBot)
 ```
 
-### Bot
+### MessageCommand 类
+
+基于 `SegmentMatcher` 的命令处理器：
 
-机器人接口定义：
 ```typescript
-export interface Bot<T extends BotConfig=BotConfig> {
-  config: T
-  connected?: boolean
-  connect(): Promise<void>
-  disconnect(): Promise<void>
-  sendMessage(options: SendOptions): Promise<void>
-}
+import { MessageCommand } from '@zhin.js/core'
+
+const command = new MessageCommand('echo <content:text>')
+  .action(async (message, result) => {
+    const content = result.args.content
+    return `你说了：${content}`
+  })
+
+addCommand(command)
+```
+
+### Component 系统
+
+强大的组件渲染系统：
+
+```typescript
+import { defineComponent, addComponent } from '@zhin.js/core'
+
+// 定义组件
+const MyComponent = defineComponent({
+  name: 'my-comp',
+  props: {
+    title: String,
+    count: { type: Number, default: 0 }
+  },
+  data(this: { title: string, count: number }) {
+    return {
+      message: `${this.title}: ${this.count}`
+    }
+  },
+  render(props, context) {
+    return `<text>${context.message}</text>`
+  }
+})
+
+// 注册组件
+addComponent(MyComponent)
+
+// 在消息中使用
+// <my-comp title="计数器" :count="5"/>
 ```
 
 ## Hooks API
 
-### 插件相关
+### 应用和插件
 ```typescript
-// 获取插件实例
+// 获取应用实例
+const app = useApp()
+
+// 获取当前插件
 const plugin = usePlugin()
 
-// 监听事件
-onEvent('event.name', handler)
+// 获取插件日志器
+const logger = useLogger()
+```
 
-// 监听群消息
-onGroupMessage(handler)
+### 事件监听
+```typescript
+// 监听所有消息
+onMessage(async (message) => {
+  console.log('收到消息:', message.raw)
+})
+
+// 监听群聊消息
+onGroupMessage(async (message) => {
+  if (message.raw.includes('帮助')) {
+    await message.reply('这里是帮助信息')
+  }
+})
 
 // 监听私聊消息
-onPrivateMessage(handler)
+onPrivateMessage(async (message) => {
+  await message.reply('私聊回复')
+})
 
-// 监听所有消息
-onMessage(handler)
+// 自定义事件监听
+onEvent('custom.event', (data) => {
+  console.log('自定义事件:', data)
+})
+```
 
-// 添加中间件
-addMiddleware(middleware)
+### 生命周期
+```typescript
+// 插件挂载时
+onMounted(async (plugin) => {
+  console.log('插件已挂载:', plugin.name)
+})
 
-// 添加定时任务
-addCronJob(job)
+// 插件销毁时
+onDispose(() => {
+  console.log('插件正在销毁')
+})
 ```
 
-### 上下文相关
+### 上下文管理
 ```typescript
 // 注册上下文
 register({
-  name: 'myContext',
+  name: 'database',
   async mounted(plugin) {
-    return { /* context data */ }
+    const db = new Database()
+    await db.connect()
+    return db
+  },
+  async dispose(db) {
+    await db.disconnect()
   }
 })
 
-// 使用上下文
-const ctx = use('myContext')
-
-// 声明上下文依赖
-useContext('ctx1', 'ctx2', async (ctx1, ctx2) => {
-  // 使用上下文
+// 使用上下文依赖
+useContext('database', async (db) => {
+  const users = await db.getUsers()
+  console.log('用户列表:', users)
 })
 ```
 
-### 生命周期
+### 适配器注册
 ```typescript
-// 挂载时
-onMounted(async (plugin) => {
-  // 初始化
+import { registerAdapter } from '@zhin.js/core'
+
+registerAdapter(new Adapter('my-platform', MyBot))
+```
+
+### 消息处理
+```typescript
+// 发送消息前处理
+beforeSend(async (options) => {
+  console.log('即将发送消息:', options)
+  // 可以修改消息内容
+  return options
 })
 
-// 销毁时
-onDispose(() => {
-  // 清理
+// 发送消息
+await sendMessage({
+  type: 'group',
+  id: '123456',
+  context: 'onebot11',
+  bot: 'my-bot',
+  content: '你好世界！'
 })
 ```
 
-## 配置
+## 类型定义
+
+### 消息相关
+```typescript
+interface Message {
+  id: string
+  adapter: string
+  bot: string
+  content: MessageSegment[]
+  sender: MessageSender
+  channel: MessageChannel
+  timestamp: number
+  raw: string
+  reply(content: SendContent, quote?: boolean | string): Promise<void>
+}
+
+interface MessageSegment {
+  type: string
+  data: Record<string, any>
+}
+
+type SendContent = string | MessageSegment | (string | MessageSegment)[]
+```
 
+### 配置相关
 ```typescript
 interface AppConfig {
+  bots?: BotConfig[]
   plugin_dirs?: string[]
   plugins?: string[]
-  bots?: BotConfig[]
+  disable_dependencies?: string[]
   debug?: boolean
 }
 
 interface BotConfig {
-  context: string
   name: string
-  config: any
+  context: string
+  [key: string]: any
+}
+```
+
+### 机器人接口
+```typescript
+interface Bot<T extends BotConfig = BotConfig> {
+  config: T
+  connected?: boolean
+  connect(): Promise<void>
+  disconnect(): Promise<void>
+  sendMessage(options: SendOptions): Promise<void>
 }
 ```
 
+## 中间件系统
+
+```typescript
+type MessageMiddleware = (
+  message: Message, 
+  next: () => Promise<void>
+) => Promise<void> | void
+
+// 添加身份验证中间件
+addMiddleware(async (message, next) => {
+  if (isAdmin(message.sender.id)) {
+    await next()
+  } else {
+    await message.reply('权限不足')
+  }
+})
+
+// 添加日志中间件
+addMiddleware(async (message, next) => {
+  const start = Date.now()
+  await next()
+  const duration = Date.now() - start
+  console.log(`处理消息耗时: ${duration}ms`)
+})
+```
+
+## 配置文件支持
+
+支持多种配置文件格式：
+- `zhin.config.ts` - JavaScript 配置
+- `zhin.config.ts` - TypeScript 配置  
+- `zhin.config.json` - JSON 配置
+- `zhin.config.yaml` - YAML 配置
+- `zhin.config.toml` - TOML 配置
+
+```typescript
+// zhin.config.ts
+export default {
+  plugin_dirs: ['./plugins', './node_modules'],
+  plugins: ['my-plugin'],
+  bots: [
+    {
+      context: 'onebot11',
+      name: 'bot1',
+      url: 'ws://localhost:8080',
+      access_token: 'your-token'
+    }
+  ],
+  debug: process.env.NODE_ENV === 'development'
+}
+```
+
+## 开发工具
+
+### 类型生成
+```bash
+# 自动生成环境类型定义
+npx zhin dev  # 开发时自动生成
+```
+
+### 热更新
+```bash
+# 开发模式启动，支持热更新
+npx zhin dev
+```
+
+## 依赖项
+
+- `@zhin.js/hmr` - 热模块替换系统
+- `segment-matcher` - 消息片段匹配器
+- `yaml` - YAML 配置文件支持
+- `toml` - TOML 配置文件支持
+- `dotenv` - 环境变量支持
+
 ## 许可证
 
+MIT License
 MIT License

package/lib/adapter.d.ts

@@ -0,0 +1,39 @@
+import { Bot, BotConfig } from "./bot.js";
+import { Plugin } from "./plugin.js";
+/**
+ * Adapter类：适配器抽象，管理多平台Bot实例。
+ * 负责根据配置启动/关闭各平台机器人，统一异常处理。
+ */
+export declare class Adapter<R extends Bot = Bot> {
+    #private;
+    name: string;
+    /** 当前适配器下所有Bot实例，key为bot名称 */
+    bots: Map<string, R>;
+    /**
+     * 构造函数
+     * @param name 适配器名称（如 'process'、'qq' 等）
+     * @param botFactory Bot工厂函数或构造器
+     */
+    constructor(name: string, botFactory: Adapter.BotFactory<R>);
+    /**
+     * 启动适配器，自动根据配置创建并连接所有Bot
+     * @param plugin 所属插件实例
+     */
+    start(plugin: Plugin): Promise<void>;
+    /**
+     * 停止适配器，断开并移除所有Bot实例
+     * @param plugin 所属插件实例
+     */
+    stop(plugin: Plugin): Promise<void>;
+}
+export declare namespace Adapter {
+    type BotBotConstructor<T extends Bot> = T extends Bot<infer F, infer S> ? {
+        new (plugin: Plugin, config: S): T;
+    } : {
+        new (plugin: Plugin, config: BotConfig): T;
+    };
+    function isBotConstructor<T extends Bot>(fn: BotFactory<T>): fn is BotBotConstructor<T>;
+    type BotCreator<T extends Bot> = T extends Bot<infer F, infer S> ? (plugin: Plugin, config: S) => T : (plugin: Plugin, config: BotConfig) => T;
+    type BotFactory<T extends Bot> = BotBotConstructor<T> | BotCreator<T>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/lib/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,GAAG,EAAC,SAAS,EAAC,MAAM,UAAU,CAAC;AACvC,OAAO,EAAC,MAAM,EAAC,MAAM,aAAa,CAAC;AACnC;;;GAGG;AACH,qBAAa,OAAO,CAAC,CAAC,SAAS,GAAG,GAAC,GAAG;;IASf,IAAI,EAAC,MAAM;IAR9B,8BAA8B;IACvB,IAAI,EAAC,GAAG,CAAC,MAAM,EAAC,CAAC,CAAC,CAAqB;IAE9C;;;;OAIG;gBACgB,IAAI,EAAC,MAAM,EAAC,UAAU,EAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAG/D;;;OAGG;IACG,KAAK,CAAC,MAAM,EAAC,MAAM;IA2BzB;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAC,MAAM;CAkB3B;AACD,yBAAiB,OAAO,CAAC;IACrB,KAAY,iBAAiB,CAAC,CAAC,SAAS,GAAG,IAAE,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,EAAC,MAAM,CAAC,CAAC,GAAG;QAC1E,KAAI,MAAM,EAAC,MAAM,EAAC,MAAM,EAAC,CAAC,GAAE,CAAC,CAAA;KAChC,GAAE;QACC,KAAI,MAAM,EAAC,MAAM,EAAC,MAAM,EAAC,SAAS,GAAE,CAAC,CAAA;KACxC,CAAA;IACD,SAAgB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAG7F;IACD,KAAY,UAAU,CAAC,CAAC,SAAS,GAAG,IAAE,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,EAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,EAAC,MAAM,EAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAC,MAAM,EAAC,MAAM,EAAE,SAAS,KAAK,CAAC,CAAA;IAC9I,KAAY,UAAU,CAAC,CAAC,SAAS,GAAG,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAC,UAAU,CAAC,CAAC,CAAC,CAAA;CAC7E"}

package/{dist → lib}/adapter.js

@@ -1,11 +1,25 @@
+/**
+ * Adapter类：适配器抽象，管理多平台Bot实例。
+ * 负责根据配置启动/关闭各平台机器人，统一异常处理。
+ */
 export class Adapter {
     name;
+    /** 当前适配器下所有Bot实例，key为bot名称 */
     bots = new Map();
     #botFactory;
+    /**
+     * 构造函数
+     * @param name 适配器名称（如 'process'、'qq' 等）
+     * @param botFactory Bot工厂函数或构造器
+     */
     constructor(name, botFactory) {
         this.name = name;
         this.#botFactory = botFactory;
     }
+    /**
+     * 启动适配器，自动根据配置创建并连接所有Bot
+     * @param plugin 所属插件实例
+     */
     async start(plugin) {
         const configs = plugin.app.getConfig().bots?.filter(c => c.context === this.name);
         if (!configs?.length)
@@ -20,7 +34,7 @@ export class Adapter {
                     bot = this.#botFactory(plugin, config);
                 }
                 try {
-                    await bot.connect();
+                    await bot.$connect();
                     plugin.logger.info(`bot ${config.name} of adapter ${this.name} connected`);
                     this.bots.set(config.name, bot);
                 }
@@ -36,11 +50,15 @@ export class Adapter {
             throw error;
         }
     }
+    /**
+     * 停止适配器，断开并移除所有Bot实例
+     * @param plugin 所属插件实例
+     */
     async stop(plugin) {
         try {
             for (const [name, bot] of this.bots) {
                 try {
-                    await bot.disconnect();
+                    await bot.$disconnect();
                     plugin.logger.info(`bot ${name} of adapter ${this.name} disconnected`);
                     this.bots.delete(name);
                 }

package/lib/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,OAAO;IASG;IARnB,8BAA8B;IACvB,IAAI,GAAe,IAAI,GAAG,EAAa,CAAA;IAC9C,WAAW,CAAsB;IACjC;;;;OAIG;IACH,YAAmB,IAAW,EAAC,UAAgC;QAA5C,SAAI,GAAJ,IAAI,CAAO;QAC1B,IAAI,CAAC,WAAW,GAAC,UAAU,CAAA;IAC/B,CAAC;IACD;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,MAAa;QACrB,MAAM,OAAO,GAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAA,EAAE,CAAA,CAAC,CAAC,OAAO,KAAG,IAAI,CAAC,IAAI,CAAC,CAAA;QAC3E,IAAG,CAAC,OAAO,EAAE,MAAM;YAAE,OAAM;QAC3B,IAAI,CAAC;YACD,KAAI,MAAM,MAAM,IAAI,OAAO,EAAC,CAAC;gBACzB,IAAI,GAAM,CAAA;gBACV,IAAI,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC7C,GAAG,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,EAAC,MAAM,CAAM,CAAA;gBAClD,CAAC;qBAAM,CAAC;oBACJ,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAC,MAAM,CAAM,CAAA;gBAC9C,CAAC;gBACD,IAAI,CAAC;oBACD,MAAM,GAAG,CAAC,QAAQ,EAAE,CAAA;oBACpB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,CAAC,IAAI,eAAe,IAAI,CAAC,IAAI,YAAY,CAAC,CAAA;oBAC1E,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAC,GAAG,CAAC,CAAA;gBAClC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACb,kBAAkB;oBAClB,MAAM,KAAK,CAAA;gBACf,CAAC;YACL,CAAC;YAED,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,UAAU,CAAC,CAAA;QACtD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,WAAW;YACX,MAAM,KAAK,CAAA;QACf,CAAC;IACL,CAAC;IACD;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,MAAa;QACpB,IAAI,CAAC;YACD,KAAI,MAAM,CAAC,IAAI,EAAC,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,EAAC,CAAC;gBAC/B,IAAI,CAAC;oBACD,MAAM,GAAG,CAAC,WAAW,EAAE,CAAA;oBACvB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,eAAe,IAAI,CAAC,IAAI,eAAe,CAAC,CAAA;oBACtE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACb,oBAAoB;oBACpB,MAAM,KAAK,CAAA;gBACf,CAAC;YACL,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,UAAU,CAAC,CAAA;QACtD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,WAAW;YACX,MAAM,KAAK,CAAA;QACf,CAAC;IACL,CAAC;CACJ;AACD,WAAiB,OAAO;IAMpB,SAAgB,gBAAgB,CAAgB,EAAiB;QAC7D,OAAO,EAAE,CAAC,SAAS;YACf,EAAE,CAAC,SAAS,CAAC,WAAW,KAAK,EAAE,CAAA;IACvC,CAAC;IAHe,wBAAgB,mBAG/B,CAAA;AAGL,CAAC,EAZgB,OAAO,KAAP,OAAO,QAYvB"}