ZZTL (ZZ Terminal Tools)
in 码农笔记 with 0 comment

ZZTL (ZZ Terminal Tools)

in 码农笔记 with 0 comment

ZZTL (ZZ Terminal Tools)

ZZ Terminal Tools 是一个功能强大的终端工具集，专为与多个平台 API 交互而设计。它支持自动登录、Cookie 管理、验证码处理等功能，可以极大提高开发和测试效率。

目录

功能特点

安装方法

全局安装（推荐）

npm install -g @zz-yp/zz-terminal-tools

全局安装后，可以在任何目录使用 zztl 命令：

zztl

本地安装

# 在项目中安装
npm install @zz-yp/zz-terminal-tools

# 使用 npx 运行
npx zztl

开发安装

如果要进行二次开发或贡献代码，可以克隆仓库后安装：

# 克隆仓库
（暂无仓库）

# 进入目录
cd zz-terminal-tools

# 安装依赖
npm install

# 启动应用
npm start

命令格式

基本命令格式：

zztl [选项]

命令选项

选项说明
--debug设置日志级别为 DEBUG（最详细）
--log-level <级别>设置日志级别 (DEBUG, INFO, PRODUCT)
--quiet设置日志级别为 PRODUCT（最精简）
--help显示帮助信息
--dev启用开发者模式，显示开发者工具
--developer-mode同上，启用开发者模式
--clear-login清除所有平台的登录信息（凭证和cookie）
--clear-credentials同上，清除所有平台的登录信息
--clear-platform <平台>清除指定平台的登录信息

命令示例

# 调试模式运行（详细日志）
zztl --debug

# 指定日志级别
zztl --log-level INFO

# 安静模式运行（最少日志）
zztl --quiet

# 清除所有登录信息
zztl --clear-login

# 清除特定平台的登录信息
zztl --clear-platform beetle

# 启用开发者模式（显示开发者工具）
zztl --dev

# 显示帮助信息
zztl-help

# 查看插件日志
zztl-logs

使用流程

  1. 首次运行：

    • 执行 zztl 命令
    • 系统会展示可用工具列表，使用上下箭头选择工具
    • 首次使用平台相关功能时，系统会提示输入登录信息

  2. 日常使用：

    • 登录信息会保存在配置文件中，下次使用无需重复输入
    • 选择需要使用的工具，按照提示完成操作

  3. 清除登录信息：

    • 如需更换账号，可使用 zztl --clear-login 清除所有登录信息
    • 或使用 zztl --clear-platform <平台名> 清除特定平台的登录信息

  4. 查看日志：

    • 使用 zztl-logs 命令查看插件的操作日志
    • 选择要查看的插件和对应的日志文件

支持的平台

ZZTL 目前支持以下平台：

  1. beetle：内部开发平台
  2. zzsso：单点登录系统

每个平台都有各自的登录处理器和功能模块。

可用工具

ZZTL 提供多种工具，包括但不限于：

  1. 示例工具：演示插件系统的基本功能
  2. 个人需求工具：处理个人需求相关的功能
  3. 组件更新工具：用于更新组件

运行 zztl 命令后，会看到完整的可用工具列表。

配置文件

配置文件保存在用户目录下的 .zz-terminal-tools/config.json 中，包含以下主要内容：

一般情况下，无需手动修改配置文件。

日志系统

日志级别

ZZTL 支持三级日志输出：

查看插件日志

ZZTL 提供了专门的命令用于查看插件的操作日志：

zztl-logs

该命令会引导您：

  1. 选择要查看的插件
  2. 选择要查看的日志文件

日志文件按时间戳命名，最新的日志文件会显示在列表前面。

插件开发

ZZTL 采用插件架构，使开发者能够轻松扩展和定制工具功能。每个插件都是一个独立的功能模块，通过统一的接口与核心系统交互。

插件创建

使用插件生成器（推荐）

最简单的创建插件方法是使用内置的插件生成器：

# 运行工具并启用开发者模式
zztl --dev

# 然后选择"创建插件"选项

插件生成器将引导您完成以下步骤：

  1. 输入插件名称（小写，用连字符分隔单词）
  2. 输入插件描述
  3. 选择是否包含示例代码

手动创建

也可以手动创建插件：

  1. 在 src/plugins 目录下创建一个新文件夹
  2. 文件夹名应该反映插件的功能，例如 my-feature
  3. 创建必要的文件（index.js, config.js, README.md）
  4. 创建 logs 子目录用于存放日志

插件目录结构

所有插件都采用文件夹形式，包含以下文件：

这种结构便于管理插件代码和相关资源，尤其是日志文件。

插件开发基础

所有插件都继承自 BasePlugin 类，必须实现 execute 方法：

const BasePlugin = require('../../core/base-plugin');
const inquirer = require('inquirer');
const logger = require('../../../utils/logger');
const config = require('./config');

class MyPlugin extends BasePlugin {
  constructor() {
    super('my-plugin', '我的插件描述');
  }

  async execute() {
    // 初始化日志系统
    this.initLogger();
    this.log('开始执行插件', 'info');

    try {
      // 插件主要逻辑...
    } catch (error) {
      logger.error('执行插件出错:', error.message);
      this.log('执行插件出错: ' + error.message, 'error');
    }
  }
}

module.exports = new MyPlugin();

插件日志功能

插件内置了日志系统，可以记录执行过程中的信息：

// 初始化日志系统（在execute方法开始时调用）
this.initLogger();

// 写入日志（支持多种日志级别）
this.log('普通消息', 'info');
this.log('警告消息', 'warn');
this.log('错误消息', 'error');
this.log('成功消息', 'success');

// 清除日志文件
await this.clearLogs();

日志文件存储在插件目录下的 logs/ 子目录中，格式为 plugin-name-YYYY-MM-DD-HH-mm-ss.log。用户可通过 zztl-logs 命令查看这些日志。

工具与辅助函数

ZZTL 提供了多种工具和辅助函数，帮助开发者更轻松地创建插件：

Logger

const logger = require("../../../utils/logger");

logger.info("普通信息");
logger.debug("调试信息");
logger.warn("警告信息");
logger.error("错误信息");
logger.success("成功信息");
logger.important("重要信息");

API请求

const { beetleAPI, zzssoAPI } = require("../../../utils/api");

// 使用beetleAPI发送GET请求
async function fetchData() {
  try {
    const response = await beetleAPI.get('/some/endpoint');
    return response.data;
  } catch (err) {
    logger.error('API请求失败:', err.message);
    return null;
  }
}

用户交互

const inquirer = require('inquirer');

async function promptUser() {
  const answers = await inquirer.prompt([
    {
      type: 'list',
      name: 'action',
      message: '请选择操作:',
      choices: [
        { name: '选项1', value: 'option1' },
        { name: '选项2', value: 'option2' }
      ]
    }
  ]);
  
  return answers.action;
}

最佳实践

  1. 初始化日志：始终在 execute 方法开始时调用 this.initLogger()
  2. 错误处理：使用 try-catch 包裹异步代码，提供有意义的错误消息
  3. 代码组织：将复杂功能拆分为多个小函数，使用异步/await处理异步操作
  4. 配置文件：将配置信息放在 config.js 中，便于维护
  5. 文档：为插件编写清晰的文档，说明功能和使用方法
  6. 用户体验：提供用户友好的交互界面和提示信息

示例插件

ZZTL 提供了多个示例插件，可以作为参考：

  1. example-plugin：基础示例，展示插件开发的基本结构
  2. personal-requirements：展示更复杂的功能实现
  3. update-components：组件更新工具，完整的实用插件
  4. beetle-helper：展示平台API调用的插件示例
  5. test-plugin：示例测试工具

常见问题

sharp 模块安装失败

如果遇到 sharp 模块安装失败，系统会自动使用备用 OCR 方案。这种情况下验证码识别率可能会降低，但不影响基本功能。

M1/M2/M3 Mac 用户可能需要手动重建 sharp：

npm rebuild sharp --platform=darwin --arch=arm64

验证码识别失败

如果验证码识别经常失败，可能是因为：

  1. OCR 引擎无法正确识别验证码
  2. sharp 模块安装不正确，无法进行图像预处理

解决方案：

插件无法被识别

如果创建的插件没有出现在选择列表中，请检查：

技术支持

如有问题，请联系开发团队：b2c-fe

技术栈

许可证

ISC

流程图补充

项目整体流程图

插件系统架构

插件执行流程图

插件生命周期

插件开发时序图

插件目录结构

插件开发工作流

交互式命令执行示例

本文由 小但 创作
全文共：7616个字
采用 知识共享署名4.0 国际许可协议进行许可
本站文章除注明转载，均为作者原创，转载前请务必署名
最后编辑时间为: Apr 2, 2025 at 10:29 pm

→ ↓ ↑
留言：