中文版

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
• basic/cli/TEST_GENERATION.md
• agents/tester/system.md
• agents/ops/system.md
• packages/toolkit/create-zhin/template/skills/plugin-publish/SKILL.md
• packages/im/runtime/tests/console-feature-hmr.test.ts
• packages/im/agent/tests/plugin-runtime/native-knowledge-tool.test.ts

Testing & CI Harness

Zhin.js implements a multi-layered testing and Continuous Integration (CI) harness to maintain framework stability, enforce architectural boundaries, and ensure plugin quality. The harness combines Vitest for unit/integration testing with Turborepo for orchestrated builds and custom automated checks known as "harness engineering."

Sources: CLAUDE.md:120-130, AGENTS.md:60-75

Testing Framework & Execution

Zhin.js uses Vitest 4.x as its primary testing framework. The environment enables globals by default, removing the need to import describe, it, or expect in test files. Tests run in a node environment with a default timeout of 10 seconds.

Sources: CLAUDE.md:105-115, basic/cli/TEST_GENERATION.md:175-185

Key Test Execution Commands

Command	Action
pnpm test	Runs all Vitest tests across the workspace
pnpm test:watch	Starts Vitest in watch mode
pnpm test:coverage	Generates code coverage reports (v8 provider)
pnpm --filter <pkg> test	Runs tests for a specific package

Sources: CLAUDE.md:17-25, basic/cli/TEST_GENERATION.md:180-190

Coverage Thresholds

The project enforces minimum coverage requirements to ensure code reliability:

• Lines: 45%
• Branches: 35% Plugins generally aim for 60-70% base coverage, with a target of 90%+ for critical components.

Sources: CLAUDE.md:113-114, basic/cli/TEST_GENERATION.md:195-200, packages/toolkit/create-zhin/template/skills/plugin-publish/SKILL.md:65-70

Architecture & Dependency Harness

The harness enforces a strict one-way dependency flow to prevent circular dependencies and architectural degradation. The hierarchy moves from foundation to application: basic → kernel → ai → core → agent → zhin.

Sources: CLAUDE.md:65-75, AGENTS.md:70-80

Architectural Dependency Flow

The diagram represents the mandatory dependency direction where lower layers must not import from higher layers. Sources: CLAUDE.md:65-75, AGENTS.md:70-80

Custom Harness Checks

The pnpm check:all command executes various specialized scripts to validate repo constraints:

• check:architecture: Verifies that no package violates the dependency hierarchy.
• check:harness-paths: Detects plugins that bypass Adapter.sendMessage to call internal bot methods directly.
• check:no-koa: Ensures plugins use the framework's RouterContext instead of direct Koa imports.
• check:install-size: Validates that the core IM production node_modules remains ≤10MB.
• check:plugin: Confirms plugins include mandatory files (package.json, README, src, tests).

Sources: CLAUDE.md:30-45, AGENTS.md:85-95

CI/CD Pipeline & GitHub Actions

GitHub Actions manages the CI lifecycle through workflows defined in ci.yml. The pipeline runs on every Pull Request and push to the main branch, utilizing a matrix to test across multiple Node.js versions (22, 24, 26) and operating systems (Ubuntu, Windows).

Sources: CLAUDE.md:120-128, agents/ops/system.md:15-25

CI Pipeline Sequence

This flowchart illustrates the sequential gates required for a code change to be considered stable within the Zhin environment. Sources: CLAUDE.md:120-130, agents/ops/system.md:15-25

Automated Test Generation

The Zhin CLI provides automated test suite generation through the zhin new command. When you create a new plugin, service, or adapter, the CLI populates a tests/index.test.ts file with relevant boilerplate.

Sources: basic/cli/TEST_GENERATION.md:5-15

Template Capabilities

• Plugins: Includes lifecycle tests (start/stop), instance validation, and middleware execution.
• Adapters: Mocks endpoints to test message receiving, sending, and lifecycle events like message.receive.
• Services: Generates placeholders for dependency injection and method execution tests.

Sources: basic/cli/TEST_GENERATION.md:25-90

Quality Control & Release Roles

The harness includes specialized AI Agent roles to monitor and maintain quality:

1. Tester Agent: Performs functional verification of PRs, designs test cases for edge cases, and provides structured Bug reports if validation fails. Sources: agents/tester/system.md:5-15
2. Ops Agent: Monitors workflow status, manages release tags (v{major}.{minor}.{patch}), and ensures environment variables/secrets are not leaked in CI logs. Sources: agents/ops/system.md:5-15

Release Readiness Checklist

Before publishing a plugin, the harness requires:

• pnpm build (tsc) passes with zero errors.
• All tests pass with adequate coverage (≥60%).
• npm pack --dry-run confirms the presence of lib/, src/, and skills/ directories.
• No sensitive keys exist in .env or configuration files.

Sources: packages/toolkit/create-zhin/template/skills/plugin-publish/SKILL.md:40-100

Testing and CI in Zhin.js focus on early discovery of architectural violations and ensuring that every plugin provides a baseline level of verification through automated generation and strict CI gates.

Sources: CLAUDE.md:130-135, AGENTS.md:65