Code996 项目技术栈文档

November 16, 2025 · View on GitHub

📋 技术栈概览

Code996 是一个基于 TypeScript 开发的命令行工具，用于分析 Git 仓库中提交的时间分布，计算项目的"996指数"。本文档专注于项目的技术栈配置、依赖管理和开发流程。

技术选型原则

  • 类型安全: 优先选择支持 TypeScript 的工具和库
  • 开发效率: 使用现代化的开发工具和构建流程
  • 用户体验: 提供友好的命令行界面和清晰的输出格式
  • 性能优化: 优化 Git 数据采集和分析算法的性能
  • 可维护性: 采用模块化设计和清晰的代码结构

📦 依赖包详解

生产依赖 (Dependencies)

包名版本用途重要性
commander^11.1.0命令行参数解析和命令管理🟢 核心
chalk^4.1.2终端彩色输出，支持多种颜色和样式🟡 重要
cli-table3^0.6.5表格格式化输出，自适应终端宽度🟡 重要
ora^5.4.1加载动画和 spinner，提升用户体验🟢 辅助

核心依赖说明

Commander.js

  • 提供完整的命令行参数解析功能
  • 支持子命令、选项、参数验证
  • 自动生成帮助文档
  • 使用示例：code996 -y 2025 --self

Chalk

  • 终端彩色文本输出
  • 支持链式调用和样式组合
  • 跨平台兼容性好
  • 使用示例：chalk.red('错误信息')

CLI-Table3

  • 自适应终端宽度的表格输出
  • 支持多列对齐和边框样式
  • 自动处理长文本换行
  • 使用示例：分析结果的数据表格展示、多仓库对比表格

Ora

  • 简单易用的加载动画
  • 支持多种 spinner 样式
  • 自动检测是否支持 ANSI 转义序列
  • 使用示例：Git 数据采集时的加载提示

开发依赖 (DevDependencies)

包名版本用途重要性
typescript^5.9.3TypeScript 编译器和类型检查🟢 核心
jest^29.7.0单元测试框架🟢 核心
ts-jest^29.4.5Jest 的 TypeScript 支持🟡 重要
ts-node^10.9.2TypeScript 运行时，支持直接运行 ts 文件🟢 辅助
inquirer^7.10.1交互式命令行界面，支持多选和单选🟡 重要
@types/node^20.14.2Node.js 类型定义🟡 重要
@types/jest^29.5.14Jest 类型定义🟡 重要
@types/yargs^17.0.32Yargs 类型定义（兼容性支持）🟢 辅助
@types/inquirer^9.0.5Inquirer 类型定义🟡 重要
prettier^3.6.2代码格式化工具🟡 重要

🚀 构建和部署流程

开发流程

  1. 环境准备

    npm install  # 安装依赖

  2. 代码编写

    • 使用 TypeScript 编写代码
    • 遵循 Prettier 代码风格
    • 添加必要的类型定义

  3. 测试验证

    npm test     # 运行单元测试
npm run build # 构建验证

构建流程

  1. TypeScript 编译

    • 将 TypeScript 源码编译为 JavaScript
    • 生成声明文件 (.d.ts) 便于类型引用
    • 生成 SourceMap 便于调试

  2. 构建产物结构

    dist/
├── cli/
│   ├── index.js
│   └── commands/
│       ├── analyze.js
│       ├── multi.js
│       ├── report/
│       │   ├── index.js
│       │   ├── printer.js
│       │   ├── analysis.js
│       │   ├── multi-comparison.js
│       │   └── trend-printer.js
│       └── help.js
├── core/
├── git/
├── types/
└── utils/

  3. 发布包结构

    code996/
├── bin/code996          # CLI 入口
├── dist/                # 编译后的代码
├── package.json         # 包配置
└── README.md           # 项目文档

部署配置

Package.json 配置

{
  "bin": {
    "code996": "bin/code996"
  },
  "files": ["bin/", "dist/", "README.md"],
  "engines": {
    "node": ">=14.0.0"
  }
}

发布流程

  1. 确保所有测试通过
  2. 更新版本号
  3. 运行构建命令
  4. 执行发布命令：npm publish

🛠️ 开发工具和流程

开发环境配置

IDE 支持

  • VSCode: 完整的 TypeScript 支持
  • IntelliJ IDEA: 强大的代码分析和重构功能
  • WebStorm: 专业的 JavaScript/TypeScript 开发环境

类型检查

  • 严格模式: 启用所有 TypeScript 严格检查
  • 类型定义: 完整的内置和第三方库类型定义
  • 接口设计: 使用接口定义数据结构，确保类型安全

代码格式化

  • Prettier: 统一的代码风格
  • Git Hooks: 提交前自动格式化

📊 新增功能技术说明

多仓库分析功能

  • 交互式选择: 使用 inquirer 实现命令行多选界面
  • 批量数据采集: 串行处理多个 Git 仓库，支持错误跳过和进度显示
  • 数据合并策略: 按维度累加统计，支持小时分布、星期分布和时间合并
  • 对比分析: 生成多仓库对比表格，支持彩色标识和统计摘要

报表输出系统

  • 模块化设计: report/ 目录下包含 printer.ts 和 analysis.ts
  • 自适应输出: 根据终端宽度自动调整表格列宽
  • 彩色标识: 使用 chalk 实现不同风险等级的颜色标识
  • 智能分析: 基于多维度指标生成人性化分析文本和建议