create-zhin-app

快速创建 Zhin 机器人 workspace 项目的脚手架工具，提供一键创建和配置新项目的能力。

核心特性

• 🚀 一键创建: 使用标准的 npm create / yarn create / pnpm create 命令
• 📦 Workspace 结构: 自动创建 pnpm workspace，支持插件开发
• 🔧 智能配置: 自动安装 pnpm、项目依赖
• 🎯 交互式配置: 选择运行时、配置格式、数据库类型
• 🗄️ 数据库支持: 支持 SQLite、MySQL、PostgreSQL、MongoDB、Redis
• 🔐 安全配置: 自动生成 HTTP Token 认证和环境变量管理
• 📊 日志配置: 内置完整的日志等级和清理配置
• 🌐 零安装: 无需全局安装，直接使用

快速开始

使用不同包管理器创建项目

# npm（推荐）
npm create zhin-app my-awesome-bot

# pnpm
pnpm create zhin-app my-awesome-bot

# 使用最新版本
npx create-zhin-app@latest my-awesome-bot

创建后的步骤

# 进入项目
cd my-awesome-bot

# 开发模式启动
pnpm dev

# 创建插件
zhin new my-plugin

# 构建插件
pnpm build

工作原理

create-zhin-app 是独立的项目脚手架工具，它的工作流程如下：

1. 启动脚手架: 当你运行 npm create zhin-app 时
2. 检测 pnpm: 自动检测并安装 pnpm（如果未安装）
3. 交互式配置: 询问项目名称、运行时、配置格式
4. HTTP Token 认证配置: 配置 Web 控制台访问 Token
   • 默认 Token：随机生成 32 位 hex 字符串
5. 数据库配置: 选择数据库类型和连接参数
   • SQLite (默认，零配置)
   • MySQL、PostgreSQL、MongoDB、Redis
   • 自动安装对应的数据库驱动包
6. 创建 Workspace: 生成 pnpm workspace 结构
7. 生成配置文件: 包含数据库、日志等完整配置
8. 生成 .env 文件: 保存 HTTP Token 和数据库连接信息
9. 自动安装依赖: 在项目根目录执行 pnpm install
10. 完成提示: 显示 Token、数据库配置和下一步操作

支持的参数

基础用法

# 交互式创建（推荐）
npm create zhin-app my-bot

# 指定项目名称
npm create zhin-app my-awesome-bot

交互式配置流程：

1. 📝 输入项目名称
2. ⚙️ 选择运行时（Node.js / Bun）
3. 📄 选择配置格式（TypeScript / JavaScript / YAML / JSON）
4. 🔐 配置 Web 控制台 Token
   • Token（默认：随机 32 位 hex 字符串，用于 Authorization: Bearer 或 ?token= 认证）
5. 🗄️ 配置数据库
   • SQLite（推荐，零配置）
   • MySQL（主机、端口、用户名、密码、数据库名）
   • PostgreSQL（主机、端口、用户名、密码、数据库名）
   • MongoDB（连接字符串、数据库名）
   • Redis（主机、端口、密码、数据库索引）

快速创建（跳过交互）

# 使用默认配置（YAML + Node.js + 随机 Token）
npm create zhin-app my-bot -y
# 或
npm create zhin-app my-bot --yes

参数详解

| 参数 | 说明 | 默认值 | |------|------|--------| | [project-name] | 项目名称（可选，会提示输入） | my-zhin-bot | | -y, --yes | 跳过交互，使用默认配置 | false |

默认配置（使用 -y 时）：

• 配置格式: YAML (zhin.config.yml)
• 运行时: Node.js
• 包管理器: pnpm（自动安装）
• 数据库: SQLite (./data/bot.db, WAL 模式)
• HTTP Token: 随机生成 32 位 hex 字符串
• 日志等级: INFO
• 日志清理: 7 天，10000 条记录

使用场景

1. 快速原型开发

# 使用默认配置快速创建
npm create zhin-app quick-prototype -y
cd quick-prototype
npm run dev

2. 生产项目创建

# 使用 TypeScript + pnpm + node 的生产配置
npm create zhin-app production-bot -- -c ts -p pnpm -r node

3. 团队标准项目

# 为团队创建标准化项目
npm create zhin-app team-bot -- \
  --config ts \
  --package-manager pnpm \
  --runtime node \
  --yes

4. 实验性项目

# 使用最新技术栈
npm create zhin-app experimental-bot -- -c ts -r node -y

生成的项目结构

执行 create-zhin-app 后会生成 pnpm workspace 项目结构：

my-awesome-bot/
├── src/                      # 应用源代码
│   ├── index.ts             # 主入口文件
│   └── plugins/             # 本地插件目录
│       └── example.ts       # 示例插件
├── client/                   # 客户端页面
│   └── index.tsx            # 示例页面
├── data/                     # 数据存储目录
├── plugins/                  # 插件开发目录（独立包）
│   └── .gitkeep
├── zhin.config.ts            # 配置文件
├── package.json             # 根 package.json（包含依赖和脚本）
├── tsconfig.json            # TypeScript 根配置
├── pnpm-workspace.yaml      # workspace 配置
├── .gitignore               # Git 忽略规则
├── .env                     # 环境变量（包含 HTTP 认证信息）
├── .env.example             # 环境变量模板
└── README.md                # 项目说明文档

⚠️ 重要: .env 文件包含敏感信息（HTTP Token），已自动添加到 .gitignore，不会被提交到版本控制。

Workspace 配置 (pnpm-workspace.yaml):

packages:
  - '.'              # 根目录即为主应用
  - 'plugins/*'      # plugins 下的所有插件包

根 package.json 脚本:

{
  "scripts": {
    "dev": "zhin dev",                          // 开发模式
    "start": "zhin start",                      // 生产启动
    "daemon": "zhin start --daemon",            // 后台运行
    "stop": "zhin stop",                        // 停止服务
    "build": "pnpm --filter \"./plugins/*\" build"  // 构建所有插件
  }
}

配置文件格式

JavaScript 配置 (推荐)

// zhin.config.ts
import { defineConfig } from 'zhin.js';

export default defineConfig(async (env) => {
  return {
    bots: [
      {
        context: 'process',
        name: `${process.pid}`,
      }
    ],
    plugin_dirs: ['./src/plugins', 'node_modules'],
    plugins: ['process', 'test-plugin'],
    debug: env.DEBUG === 'true'
  };
});

TypeScript 配置

// zhin.config.ts
import { defineConfig } from 'zhin.js';
import type { AppConfig } from 'zhin.js';

export default defineConfig<AppConfig>(async (env) => {
  return {
    bots: [
      {
        context: 'process',
        name: `${process.pid}`,
      }
    ],
    plugin_dirs: ['./src/plugins', 'node_modules', 'node_modules/@zhin.js'],
    plugins: [
      'adapter-process',
      'http',
      'console',
      'example'
    ],
    http: {
      port: 8086,
      token: process.env.HTTP_TOKEN || 'your-token',
      base: '/api'
    },
    debug: process.env.NODE_ENV === 'development'
  };
});

完整工作流

项目创建完成后，可以执行以下操作：

1. 进入项目目录

cd my-awesome-bot

2. 开发模式启动（依赖已自动安装）

pnpm dev

访问 http://localhost:8086 查看 Web 控制台

访问信息：

• Token 在创建项目时已配置
• 保存在 .env 文件中
• 创建完成时会在终端显示

💡 修改 Token: 编辑 .env 文件中的 HTTP_TOKEN

3. 创建插件

# 创建新插件（自动添加到依赖）
zhin new my-awesome-plugin

# 插件会创建在 plugins/my-awesome-plugin/
# 自动添加到根 package.json 的 dependencies

4. 开发插件

# 编辑插件文件
# plugins/my-awesome-plugin/src/index.ts              # 插件逻辑
# plugins/my-awesome-plugin/skills/my-awesome-plugin/SKILL.md  # AI 技能说明（可选完善）
# plugins/my-awesome-plugin/client/                   # 控制台客户端页面

# 保存后自动热重载 ⚡

5. 构建插件

# 构建所有插件
pnpm build

# 或只构建特定插件
zhin build my-awesome-plugin

6. 在配置中启用插件

编辑 zhin.config.ts：

export default defineConfig({
  plugins: [
    'adapter-process',
    'http',
    'console',
    'example',           // 内置示例
    'my-awesome-plugin'  // 你的插件
  ]
});

7. 生产环境部署

# 确保插件已构建
pnpm build

# 生产启动
pnpm start

# 或后台运行
pnpm daemon

# 停止服务
pnpm stop

错误处理

常见错误及解决方案

1. 网络连接问题

   # 使用国内镜像
   npm config set registry https://registry.npmmirror.com
   npm create zhin-app my-bot

2. 权限问题

   # macOS/Linux
   sudo chown -R $USER ~/.npm
      
   # Windows (以管理员身份运行)
   npm create zhin-app my-bot

3. Node.js 版本问题

   # 检查 Node.js 版本（需要 ^20.19.0 或 >=22.12.0）
   node --version
      
   # 升级 Node.js
   # 使用 nvm 或从官网下载最新版本

环境要求

• Node.js: ^20.19.0 或 >=22.12.0
• npm: >= 8.0.0 (或对应版本的 yarn/pnpm)
• 操作系统: Windows 10+, macOS 10.15+, Linux (现代发行版)

与其他工具对比

| 特性 | create-zhin-app | create-react-app | create-vue | |------|-------------|------------------|------------| | 零配置创建 | ✅ | ✅ | ✅ | | 多配置格式 | ✅ | ❌ | ✅ |
| 多运行时支持 | ✅ | ❌ | ❌ | | 机器人框架 | ✅ | ❌ | ❌ | | 热重载开发 | ✅ | ✅ | ✅ |

高级用法

自定义模板

虽然 create-zhin-app 主要调用 CLI 工具，但你可以通过环境变量自定义行为：

# 设置自定义模板路径
ZHIN_TEMPLATE_DIR=/path/to/custom/template npm create zhin-app my-bot

批量创建

#!/bin/bash
# 批量创建多个项目
for name in bot1 bot2 bot3; do
  npm create zhin-app $name -- -y
done

CI/CD 集成

# GitHub Actions 示例
- name: create zhin-app Bot Project
  run: |
    npm create zhin-app test-bot -- --yes
    cd test-bot
    npm run build
    npm run test

故障排查

调试模式

# 启用详细日志
DEBUG=create-zhin-app npm create zhin-app my-bot

# 检查参数传递
npm create zhin-app my-bot -- --help

清理缓存

# 清理 npm 缓存
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf node_modules package-lock.json
npm install

贡献指南

create-zhin-app 是开源项目，欢迎贡献：

1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 创建 Pull Request

许可证

MIT License