中文版

Generated reference snapshot

Original Cubic page · captured 2026-09-23 · source commit. This AI-generated page has not been verified against the current code. Use the Zhin documentation for current behavior and see known corrections.

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• AGENTS.md
• README.md
• packages/toolkit/create-zhin/README.md
• packages/toolkit/scaffold-wizard/README.md
• packages/toolkit/create-zhin/src/workspace.ts
• basic/cli/src/commands/setup.ts

System Architecture & Layering

Zhin.js organizes its functionality as a multi-platform, AI-driven chatbot framework built with TypeScript. The system uses a monorepo structure managed by pnpm workspaces and Turborepo to enforce strict dependency boundaries between its various functional layers.

Sources: CLAUDE.md:16-24, README.md:13-20

Dependency Layers

The Zhin.js architecture follows a strict bottom-to-top dependency hierarchy. Lower layers provide foundational services and must never import from higher layers. This restriction ensures system stability and prevents circular dependencies.

The diagram shows the one-way dependency flow from high-level orchestration down to foundation utilities.

Layer Descriptions

Layer	Package Path	Role & Responsibilities
Foundation	basic/	Provides logger, schema validation, database drivers, and the CLI base.
Kernel	packages/im/kernel	Handles task scheduling, identity management, and error hierarchies.
AI Engine	packages/im/ai	Manages model providers, agents, memory compaction, and cost tracking.
Core	packages/im/core	Defines IM runtime, message contracts, and interaction rendering.
Agent	packages/im/agent	Orchestrates ZhinAgent, security policies, and MCP clients.
Main Entry	packages/im/zhin	Assembles the canonical IM runtime; acts as the user-facing entry point.

Sources: CLAUDE.md:41-71, AGENTS.md:57-75

Message Pipeline Architecture

Zhin.js processes messages through a normalized pipeline. This pipeline transforms platform-specific inbound events into standard internal message formats, which then interact with commands, middleware, or AI agents.

The diagram illustrates how messages flow from inbound adapters through processing logic to the outbound send chain.

Outbound Send Chain Constraints

All outbound messages must follow the unified send chain. Developers must use Message.$reply or Adapter.sendMessage. The system then processes these through an OutboundRenderer and outbound middleware before reaching the platform Endpoint. Bypassing this chain is strictly prohibited to ensure consistent rendering and logging.

Sources: README.md:53-73, CLAUDE.md:73-76

Plugin System & Feature Discovery

The Plugin Runtime serves as the sole entry path for extending the framework. Zhin.js uses a convention-based discovery mechanism where capabilities are loaded from specific directories rather than being registered imperatively.

Plugin Definition

A plugin must default-export a definePlugin() definition in a plugin.ts file. The PluginScopeAssembler throws an error if this export is missing.

// Example plugin structure
import { definePlugin } from 'zhin.js';

export default definePlugin({
  name: 'my-plugin',
  setup(context) {
    // Lifecycle and resource provisioning
    return () => cleanup();
  },
});

Sources: CLAUDE.md:81-93, packages/toolkit/create-zhin/src/workspace.ts:257-264

Convention Directories

The framework automatically discovers features based on their file paths within a plugin:

Directory	Feature Type	Authoring API
commands/	Bot Commands	defineCommand()
middlewares/	Message Filters	defineMiddleware()
handlers/	Event Listeners	defineHandler()
tools/	AI Agent Tools	defineAgentTool()
skills/	AI Workflows	SKILL.md (Markdown)
pages/	Console UI	definePage()

Sources: CLAUDE.md:95-108, AGENTS.md:104-108

Project Scaffolding and Configuration

The architecture supports both fresh project creation and incremental configuration through shared tools.

• create-zhin-app: Generates the initial workspace file tree and manages pnpm workspace setup.
• scaffold-wizard: A shared library used by both the creator and the CLI setup command to handle interactive prompts for databases, adapters, and AI providers.
• Generation Lifecycle: Plugin updates occur through hot-reloads managed as "Generation" transactions. Next plugin trees are prepared off-path and published atomically to ensure a failed update does not crash the active runtime.

Sources: packages/toolkit/create-zhin/README.md:105-115, packages/toolkit/scaffold-wizard/README.md:5-15, README.md:96-105

Architectural Safeguards

The framework employs "Harness Engineering" to enforce architectural integrity:

1. Architecture Checks: pnpm check:architecture validates that dependency directions are respected.
2. Send Chain Enforcement: pnpm check:harness-paths detects if plugins attempt to bypass the standard Adapter.sendMessage path.
3. API Restriction: check:no-removed-plugin-api prevents the use of legacy or deleted APIs like zhin.js/node.

Sources: CLAUDE.md:31-40, AGENTS.md:120-130

Zhin.js architecture prioritizes a clear separation between the foundational IM framework and the optional AI agent stack. By enforcing strict layering and convention-based feature discovery, the system maintains high operability and safety in both development and production environments.