Zhin.js

Appearance

架构概览 ​

Zhin.js 采用分层架构设计，从底层通用基建到上层 IM 应用逐层抽象。每层职责明确、可独立使用，也可组合构建完整的聊天机器人应用。

分层架构图 ​

各层详解 ​

基础层 (basic/) ​

框架无关的基础设施，所有上层包共享的底层能力。各包均在 monorepo 内作为普通路径管理（不再使用 git submodule）。

包名路径说明
@zhin.js/loggerbasic/logger结构化日志系统，支持多级别、彩色输出
@zhin.js/databasebasic/database统一数据库抽象（SQLite、MySQL、MongoDB 等）
@zhin.js/schemabasic/schema配置校验与序列化
@zhin.js/clibasic/cli命令行工具（dev、start、new、build、pub）

@zhin.js/kernel（运行时内核） ​

与 IM/AI 无关的通用运行时，可独立用于 Web 后端、CLI 工具、自动化脚本等任意 Node.js 应用。

模块说明
PluginBase轻量级插件系统，支持 DI（provide/inject）、生命周期、插件树结构
Feature可追踪、可序列化的插件功能基类，支持变更事件
Cron基于 croner 的 cron 表达式调度器
Scheduler持久化定时任务调度系统，可自定义 JobStore
错误体系ZhinError 层级 + RetryManager + CircuitBreaker + ErrorManager
工具函数evaluate/execute（vm 沙盒）、compiler（模板）、Time（时间常量）等

@zhin.js/ai（AI 引擎层） ​

与 IM 无关的通用 AI 引擎，可独立用于任何需要 LLM 集成的应用。按三个子模块组织：

agent/ — Agent 引擎 ​

模块说明
Agent无状态 Agent 引擎，执行多轮 tool-calling 循环
CostTrackerToken 用量与成本追踪，支持按模型/Provider 统计（Claude Code 风格）
ToolFilter / CachedToolFilterTF-IDF 工具相关性过滤与带缓存的过滤器

memory/ — 会话与上下文 ​

模块说明
SessionManager会话管理（内存 / 数据库持久化），统一工厂 createSessionManager
ContextManager按场景落库、读历史与总结的多平台上下文管理
ConversationMemory话题切换 + 链式摘要的长期记忆

compaction/ — 上下文压缩 ​

模块说明
compaction分阶段摘要、上下文窗口守护、自动压缩管线
MicroCompact旧工具结果轻量占位清理（主压缩前）
token-counter极简 token 估算（字符/4）

顶层模块 ​

模块说明
AIProviderLLM 提供者统一接口（OpenAI、Anthropic、Ollama、DeepSeek、Moonshot、Zhipu 等）
ModelRegistry模型自动发现、Tier 评分、缓存与智能选择（支持自动降级）
FileStateCache文件状态缓存，减少重复磁盘读取
outputAI 文本解析为结构化 OutputElement[]（文本/图片/音频/卡片等）
RateLimiter请求速率限制
ToneDetector消息情绪感知
Storage统一存储抽象（内存 / 数据库可热切换）

@zhin.js/core（IM 层） ​

IM 聊天机器人的核心框架，在 kernel 基础上添加 IM 领域概念。不再自带 AI Provider 实现（已迁至 @zhin.js/ai），而是从 @zhin.js/ai 选择性 re-export。

模块说明
Plugin完整的插件类，实现 PluginLike 接口，含 IM 特有功能（消息中间件、命令、组件）
Adapter适配器抽象基类，管理 Bot 连接、群管理方法自动检测
BotBot 接口，规范连接/发消息/撤回/格式化等方法
MessageDispatcher消息三阶段调度：Guardrail → Route → Handle
Feature 子类CommandFeature、ToolFeature、SkillFeature、CronFeature、DatabaseFeature、ComponentFeature、PermissionFeature、ConfigFeature
消息类型Message、MessageElement、segment（消息段工具）
AI re-export从 @zhin.js/ai 选择性导出 Provider、Agent、Session、Memory、Compaction 等

@zhin.js/agent（Agent 编排层） ​

IM 场景下的 AI Agent 编排，在 @zhin.js/ai 基础上添加 IM 集成逻辑。按五个子模块组织：

orchestrator/ — 中央编排 ​

模块说明
AgentOrchestrator聚合五类注册表，provide('agent') 对外暴露，支持 common vs agentId 作用域
ToolRegistryIM 工具权限（ToolPermissionLevel）、ZhinTool 契约、与 @zhin.js/ai 过滤集成
SkillRegistrySkill 注册、按名索引、评分搜索
SubAgentRegistry子代理定义 + AgentPreset 并存注册
McpRegistryMCP 服务端条目注册与连接/工具/资源聚合
HookRegistryAI 生命周期 Hook（错误隔离触发）
ResourceRegistry<T>通用注册表基类（公共 vs 专有、增删与监听）

discovery/ — 文件化能力发现 ​

模块说明
tools.ts扫描 *.tool.md，解析 frontmatter 并构建可注册工具
skills.ts扫描 SKILL.md，依赖检查、常驻技能与摘要 XML
agents.ts扫描 *.agent.md 预设元数据
utils.ts发现路径优先级、目录列表等共享工具

security/ — 安全策略 ​

模块说明
ExecPolicyBash 执行安全（6 层纵深防御：黑名单、环境变量剥离、wrapper 剥离、复合命令拆分、只读放行、审批集成）
FilePolicy文件访问安全（路径检查、设备路径拦截、命令读写分类）

mcp-client/ — MCP 客户端 ​

模块说明
McpClientManager多连接管理，与编排层注册/断开配合
McpClientConnection单个 MCP Server 连接生命周期与状态
bridgeMCP 能力到 AgentTool / orchestrator 资源的转换

顶层模块 ​

模块说明
ZhinAgentAI 全局大脑，编排工具选择、多轮对话、引导文件注入
AIServiceAI 服务管理器，Provider 注册与路由
SubagentManager后台子任务管理
UserProfileStore用户画像管理（跨会话个性化）
PersistentCronEngineAI 感知的持久化 cron 引擎
BootstrapLoader引导文件加载（SOUL.md / AGENTS.md / TOOLS.md）
PromptBuilder系统提示词构建器（10 段结构化架构）
defaults/默认工具/子代理/Hook 注册（registerDefaultTools 等）
common-adapter-tools适配器群管方法 → AI 工具自动生成
内置工具bash、read_file、write_file、ask_user、web_search、chat_history 等

zhin.js（应用层） ​

面向终端用户的主入口包，组合所有层并提供一键启动能力。

模块说明
配置加载从 zhin.config.yml / .ts 加载配置
项目根锁定setZhinProjectRoot 防止后续 chdir 导致插件路径偏移
插件加载基于锁定的项目根自动发现和加载插件（支持热重载）
Bot 连接按配置连接各平台适配器的 Bot
AI 注册初始化 AI Provider、Agent、SessionManager
信号处理优雅关闭（SIGINT/SIGTERM）
重新导出直接 export * from '@zhin.js/core'，选择性 re-export @zhin.js/agent（不再使用 re-exports/ 垫片文件）

依赖关系 ​

核心设计原则：

  • kernel 和 ai 不依赖任何 IM 概念，可被非 IM 应用直接使用
  • core 只依赖 kernel，引入 IM 领域概念
  • agent 桥接 core + ai，实现 IM 场景的 AI 编排
  • zhin.js 作为 facade 层，组合所有包并提供完整的应用启动流程

消息处理流程 ​

入站顺序（与源码一致）：平台 → Adapter.emit('message.receive')（内部 await MessageDispatcher.dispatch）→ await 根插件 message.receive（生命周期） → 再通知 adapter.on('message.receive') 注册的观察者（如控制台 UI）。默认路由 exclusive（命令与 AI 互斥）；双轨见配置 dispatcher.mode: dual。详见仓库根目录 AGENTS.md 与 消息如何流转。

出站消息（发送链） ​

所有「机器人主动发到会话」的逻辑应走 同一套发送管道，避免在 core 中新增与 Adapter.sendMessage 并行的旁路 API。

推荐链（概念顺序）：

  1. 业务或框架代码调用 Message.$reply(...)，或直接调用 Adapter.sendMessage(...)（与具体 Bot API 封装一致）。
  2. Adapter 内经过 renderSendMessage 等渲染/规范化（如 segment → 平台格式）。
  3. 根插件 的 before.sendMessage 生命周期：可读取/改写即将发出的 options（例如统一润色 content、审计、限流）。
  4. 最终落到具体 Bot / 平台 SDK（如 bot.$sendMessage）。

Dispatcher 出站润色（packages/core/src/built/dispatcher.ts）：在调用 $reply 的异步上下文中，用 AsyncLocalStorage 标记「本次发送由 Dispatcher 发起的回复」；addOutboundPolish 向根注册额外的 before.sendMessage，仅在存储命中时修改 options.content。这样润色与普通插件发消息走同一 before.sendMessage 链，行为一致、可组合。

扩展阅读：docs/advanced/ai.md（若涉及 AI 触发与出站）；根目录 AGENTS.md（速查表）；Harness / 不变量见 docs/architecture/ 下 im-queue-outbound-invariants.md 与 harness-engineering-sources.md。

插件系统 ​

Zhin.js 使用 AsyncLocalStorage 实现插件上下文管理。开发者通过 usePlugin() 获取当前插件 API：

typescript
import { usePlugin, MessageCommand } from 'zhin.js'

const { addCommand, addTool, onMounted } = usePlugin()

插件支持：

  • 依赖注入 — provide / inject / useContext
  • 生命周期 — onMounted / onDispose
  • 热重载 — 文件修改后自动重载（dev 模式）
  • 树状结构 — 子插件自动继承父插件上下文

适配器与群管理 ​

适配器通过覆写 IGroupManagement 接口方法来声明群管理能力。Adapter.start() 会自动检测已覆写的方法并生成对应的 AI 工具；技能说明由包内 skills/（SKILL.md）提供：

typescript
class MyAdapter extends Adapter<MyBot> {
  async kickMember(botId, sceneId, userId) { /* ... */ }
  async muteMember(botId, sceneId, userId, duration) { /* ... */ }

  async start() {
    await super.start() // 自动检测 → 生成 Tool → 注册 Skill
  }
}

可复用性 ​

由于 @zhin.js/kernel 和 @zhin.js/ai 与 IM 无关，它们可被直接用于：

  • Web 后端服务的插件架构
  • CLI 工具的模块化设计
  • AI 驱动的自动化脚本
  • 任何需要 DI + 生命周期管理的 Node.js 应用
  • 任何需要 LLM 集成（对话、工具调用、记忆）的应用
typescript
import { PluginBase } from '@zhin.js/kernel'
import { Agent, OpenAIProvider } from '@zhin.js/ai'

const app = new PluginBase({ name: 'my-web-app' })
const provider = new OpenAIProvider({ apiKey: '...' })
const agent = new Agent(provider, logger)

基于 MIT 许可发布

Copyright © 2024-present lc-cn