@zhin.js/core

Zhin 机器人框架核心包，基于 HMR（热模块替换）系统构建的现代化机器人开发框架。

核心特性

- 🔥 热模块替换: 基于 @zhin.js/hmr 的热更新系统
- 🔌 插件化架构: 完整的插件生命周期管理
- 🤖 多平台适配: 支持多种聊天平台适配器
- 🎯 命令系统: 基于 segment-matcher 的智能消息匹配
- 🧩 组件系统: 支持模板渲染、属性绑定、插槽的组件化开发
- ⚡ 中间件链: 灵活的消息处理中间件机制
- 🔧 TypeScript: 完整的类型支持

核心组件

$3

应用核心类，继承自 HMR：

``typescript
import { App } from '@zhin.js/core'

// 直接使用 App 类创建实例
const app = new App('./zhin.config.ts')

// 启动应用
await app.start()
`

或者使用主包的便捷方法：

`typescript
import { createApp } from 'zhin.js'

// 创建应用实例
const app = await createApp({
plugin_dirs: ['./plugins'],
plugins: ['my-plugin'],
bots: [{
context: 'process',
name: 'my-bot'
}],
debug: true
})

// 启动应用
await app.start()
`

主要功能：
- 插件生命周期管理
- 配置文件加载和管理
- 适配器和机器人实例管理
- 消息路由和分发
- 热更新监听

$3

插件基类，继承自 Dependency：

`typescript
import { usePlugin, addMiddleware, addCommand, addComponent } from '@zhin.js/core'

const plugin = usePlugin()

// 添加中间件
addMiddleware(async (message, next) => {
console.log([${plugin.name}] 收到消息:, message.raw)
await next()
})

// 添加命令
addCommand(new MessageCommand('hello')
.action(async (message) => {
return '你好！'
})
)
`

主要功能：
- 中间件链管理
- 命令注册和处理
- 组件管理
- 事件监听和分发
- 消息发送前处理 (beforeSend)

$3

适配器基类，用于连接不同聊天平台：

`typescript
import { Adapter, Bot, Plugin } from '@zhin.js/core'

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)
`

$3

基于 SegmentMatcher 的命令处理器：

`typescript
import { MessageCommand } from '@zhin.js/core'

const command = new MessageCommand('echo ')
.action(async (message, result) => {
const content = result.params.content
return 你说了：${content}
})

addCommand(command)
`

$3

强大的组件渲染系统：

`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 ${context.message}
}
})

// 注册组件
addComponent(MyComponent)

// 在消息中使用
//
`

Hooks API

$3


`typescript
// 获取应用实例
const app = useApp()

// 获取当前插件
const plugin = usePlugin()

// 获取插件日志器
const logger = useLogger()
`

$3


`typescript
// 监听所有消息
onMessage(async (message) => {
console.log('收到消息:', message.raw)
})

// 监听群聊消息
onGroupMessage(async (message) => {
if (message.raw.includes('帮助')) {
await message.reply('这里是帮助信息')
}
})

// 监听私聊消息
onPrivateMessage(async (message) => {
await message.reply('私聊回复')
})

// 自定义事件监听
onEvent('custom.event', (data) => {
console.log('自定义事件:', data)
})
`

$3


`typescript
// 插件挂载时
onMounted(async (plugin) => {
console.log('插件已挂载:', plugin.name)
})

// 插件销毁时
onDispose(() => {
console.log('插件正在销毁')
})
`

$3


`typescript
// 注册上下文
register({
name: 'database',
async mounted(plugin) {
const db = new Database()
await db.connect()
return db
},
async dispose(db) {
await db.disconnect()
}
})

// 使用上下文依赖
useContext('database', async (db) => {
const users = await db.getUsers()
console.log('用户列表:', users)
})
`

$3


`typescript
import { registerAdapter } from '@zhin.js/core'

registerAdapter(new Adapter('my-platform', MyBot))
`

$3


`typescript
// 发送消息前处理
beforeSend(async (options) => {
console.log('即将发送消息:', options)
// 可以修改消息内容
return options
})

// 发送消息
await sendMessage({
type: 'group',
id: '123456',
context: 'onebot11',
bot: 'my-bot',
content: '你好世界！'
})
`

类型定义

$3


`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
}

interface MessageSegment {
type: string
data: Record
}

type SendContent = string | MessageSegment | (string | MessageSegment)[]
`

$3


`typescript
interface AppConfig {
bots?: BotConfig[]
plugin_dirs?: string[]
plugins?: string[]
disable_dependencies?: string[]
debug?: boolean
}

interface BotConfig {
name: string
context: string
[key: string]: any
}
`

$3


`typescript
interface Bot {
config: T
connected?: boolean
connect(): Promise
disconnect(): Promise
sendMessage(options: SendOptions): Promise
}
`

中间件系统

`typescript
type MessageMiddleware = (
message: Message,
next: () => Promise
) => Promise | 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
import { defineConfig } from 'zhin.js'

export default defineConfig({
database: {
dialect: 'sqlite',
filename: './data/bot.db'
},
plugin_dirs: ['./src/plugins', 'node_modules', 'node_modules/@zhin.js'],
plugins: ['http', 'console', 'adapter-process'],
bots: [
{
context: 'process',
name: 'console-bot'
}
],
log_level: 1,
debug: process.env.NODE_ENV === 'development'
})
`

开发工具

$3


`bash

自动生成环境类型定义

npx zhin dev # 开发时自动生成
`

$3

`bash

开发模式启动，支持热更新

npx zhin dev
`

依赖项

- @zhin.js/hmr - 热模块替换系统
- segment-matcher - 消息片段匹配器
- yaml - YAML 配置文件支持
- toml - TOML 配置文件支持
- dotenv` - 环境变量支持

许可证

MIT License
MIT License