frontend-workload

前端开发团队工作量全流程管理工具：月度统计模板生成 + 工时汇总分析。

文档分工

| 文档 | 读者 | 内容 | |------|------|------| | README.md（本文件） | 使用者 / 维护者 | 安装、使用方式、配置修改、发布、FAQ | | SKILL.md | AI Agent | 触发条件、执行流程、校验标准（运行时加载） | | docs/template_spec.md | AI（生成模板时） | 模板结构与样式规范 | | docs/extraction_rules.md | AI（汇总时） | 数据提取与同日记录处理规则 |

快速开始

1. 安装

# 安装到通用标准目录（推荐，所有 AI 工具通用）
npx @qilitt-mickey/frontend-workload install universal

# 安装到所有支持的工具
npx @qilitt-mickey/frontend-workload install all

2. 使用

在支持 Skills 的 AI 工具中：

/frontend-workload template 生成2026年10月模板
/frontend-workload summary 汇总 E:\work\2026年8月前端工作量统计.xlsx

安装命令

# 安装到指定目标
npx @qilitt-mickey/frontend-workload install universal   # 通用标准
npx @qilitt-mickey/frontend-workload install trae        # Trae
npx @qilitt-mickey/frontend-workload install cursor      # Cursor
npx @qilitt-mickey/frontend-workload install claude      # Claude Code
npx @qilitt-mickey/frontend-workload install all         # 全部工具

# 安装到指定项目目录
npx @qilitt-mickey/frontend-workload install all --project ./my-project

# 更新到最新版
npx @qilitt-mickey/frontend-workload@latest update

# 查看已安装情况
npx @qilitt-mickey/frontend-workload list

# 卸载
npx @qilitt-mickey/frontend-workload uninstall all

支持的安装目标

| 目标 | 说明 | 默认路径 | |------|------|----------| | universal | 通用标准（推荐） | ~/.agents/skills/frontend-workload/ | | trae | Trae | ~/.trae-cn/skills/frontend-workload/ | | cursor | Cursor | ~/.cursor/skills/frontend-workload/ | | claude | Claude Code | ~/.claude/skills/frontend-workload/ | | all | 安装到全部工具 | — |

功能

| 子命令 | 功能 | |--------|------| | template | 按周拆分生成含下拉验证、斑马纹、汇总公式的 Excel 模板 | | summary | 从已填写的 Excel 中提取工时数据，生成汇总报表 |

特性

• 模板生成：按周拆分工作表、成员数据区、下拉验证（任务类型/项目分类/项目负责人）、斑马纹样式、周末灰底、SUM 汇总公式、冻结首行
• 工时汇总：9 项前置校验、自动分区识别、5 种同日记录处理策略、与官方汇总对比验证、按人员+项目维度输出报表
• 多目标安装：支持 universal/trae/cursor/claude，install all 一键全装
• 自动更新：npx ...@latest update 一键更新所有已安装目标
• 自动发布：git pre-push hook 自动升版本并发布到 npm

前置依赖

• Node.js >= 14
• Python >= 3.8
• Python 包：openpyxl、pandas、python-calamine

安装时会自动检查并安装 Python 依赖。如需手动安装：

pip install openpyxl pandas python-calamine

配置说明

默认配置在 scripts/generate_template.py 顶部的 DEFAULT_* 变量中：

| 变量 | 说明 | |------|------| | DEFAULT_MEMBERS | 团队成员（默认 10 人） | | DEFAULT_TASK_TYPES | 任务类型下拉 | | DEFAULT_PROJECT_CATEGORIES | 项目分类下拉 | | DEFAULT_PROJECT_MANAGERS | 项目负责人下拉 |

修改后重新安装或直接使用本地脚本即可生效。AI 执行时会读取脚本中的最新值，不会使用 SKILL.md 中的硬编码列表。

维护者指南

目录结构

frontend-workload/
├── package.json               # npm 包定义
├── release.js                 # 发布脚本
├── SKILL.md                   # AI 运行时指令
├── README.md                  # 本文件
├── bin/cli.js                 # npx 安装器入口
├── scripts/
│   ├── generate_template.py   # 模板生成
│   └── summarize_workload.py  # 工时汇总
└── docs/
    ├── template_spec.md
    └── extraction_rules.md

开发与发布

# 首次配置 pre-push hook
npm run setup-hook

# 之后 git push 自动升补丁版本并发布
git add -A && git commit -m "fix: xxx" && git push

# 手动发布
npm run release           # 补丁版本 1.0.x
npm run release:minor     # 次版本 1.x.0
npm run release:major     # 主版本 x.0.0

# 模拟发布
node release.js --dry-run

发布流程：检查 npm 认证 → 升版本 → Git 提交 → 推送 Gitee → 发布 npmjs.org

npm 认证：

npm config set //registry.npmjs.org/:_authToken npm_你的token

Token 需启用 Bypass 2FA 和 Read and write 权限。

常见问题

安装后找不到 skill？

检查安装输出路径是否在对应工具的 skills 目录中。使用 list 命令查看已安装位置：

npx @qilitt-mickey/frontend-workload list

Python 依赖安装失败？

手动执行 pip install openpyxl pandas python-calamine。内网环境可能需要配置 pip 镜像源。

生成的模板下拉数据不显示？

下拉数据在隐藏的「下拉配置」工作表中，Excel 打开时需启用数据验证功能。

汇总时提示「未提取到任何有效工时记录」？

源文件必须是已填写数据的工作量统计文件，空白模板无法汇总。请先用 template 生成模板，团队填写后再 summary。

怎么更新到最新版？

npx @qilitt-mickey/frontend-workload@latest update

License

MIT