跳转至

husky — 禅道工时 Git Hooks

📄 创建: 未记录 

https://doc.xpku.com/raw/tools/husky.md

强制提交信息带禅道编号,有工时则自动录入禅道(经 devmgt 代理)。纯 shell / PowerShell,零依赖(无 node/axios),跨平台。

特性

  • 零依赖:无 node / axios,Windows 用 PowerShell,Mac/Linux 用 bash + curl
  • 跨平台:Windows(cmd / PowerShell)、macOS、Linux
  • 一条命令:安装 / 卸载 / 更新 三合一菜单
  • 编号强制 + 工时可选:编号(task-/bug-)必须;工时有则录入、无则放行不阻断
  • 录入非阻断:工时录入失败绝不影响提交
  • commit 时自动补 .gitignore:防止 .husky / 配置(含 key) / 日志 误提交
  • task + bug 工时都支持:task 走 submit-effort,bug 走 bug-effort(MCP 2026-07-31 上线)

一条命令(菜单:安装 / 卸载 / 更新)

Windows(cmd / PowerShell):

powershell -c "irm https://doc.xpku.com/mcp/files/husky.ps1 | iex"

macOS / Linux:

curl -fsSL https://doc.xpku.com/mcp/files/husky.sh | bash

两个都弹出同一个菜单:

操作 [1]安装 [2]卸载 [3]更新(默认 1)
操作 行为 会问
1 安装 装到全局或当前项目 范围 / DEVMGT_URL / API-KEY(全局还问是否强制)
2 卸载 删 hooks + 配置 + 清 .gitignore + unset hooksPath 范围 / 确认 [y/N]
3 更新 重新下载只覆盖 hooks 文件,保留你的配置和 key 范围

未配置 API-KEY 时:编号校验仍生效;有工时也不录入(无 key)——可先规范编号,后补 key。

提交信息格式

<禅道编号> <类型>(<作用域>): <标题> [工时]
  • 编号(必填):task-xxxx 或 bug-xxxx(不区分大小写)——缺则阻断提交
  • 工时(可选):2h / 1.5h / 2H / 3 h,位置任意。有则录入禅道,无则跳过录入直接放行
  • 类型:feat / fix / refactor / style / perf / docs / test / chore / revert

示例:

task-19201 feat(login): 适配 APEX 环境登录流程 2h      ← 有工时,录入
task-19201 feat(login): 快速调整                        ← 无工时,放行不录入
bug-12345 fix(api): 修复请求超时未重试 1.5h             ← bug 工时,录入

Merge / Revert / Squash / Cherry-pick / fixup! / squash! 自动放行,不受此格式约束。

工作原理(commit-msg)

git commit -m "..."
  ├─ 未启用(无配置且非强制) → 放行
  ├─ Merge/Revert/Squash 等 → 放行
  ├─ 校验 task-/bug- 前缀        → 缺则阻断
  ├─ 有工时(Nh)? → 是:调录入(失败仅警告,不阻断)
  │                否:跳过录入,直接放行
  └─ 补 .gitignore(.husky/.bams-zentao-config/.zentao-logs/)

配置

KEY=VALUE 格式。位置:

  • 全局:~/.bams-zentao-config(本机所有项目共享)
  • 项目级:<项目>/.bams-zentao-config(仅当前项目,已自动加入 .gitignore)
DEVMGT_URL="http://dns.xpku.com:5121/dev"
DEVMGT_API_KEY=""                # 完整 64 字符 X-Api-Key(唯一鉴权)
ZENTAO_DEFAULT_HOURS="1"
ZENTAO_DISABLED="false"
ENFORCE_ALL_PROJECTS="false"     # 仅全局:true=本机所有项目强制验证

优先级:项目级 > 环境变量 > 全局 > 默认。ZENTAO_DISABLED 为或逻辑(任一层 true 即禁用)。

获取 X-Api-Key

  1. devmgt agent 管理页新建 agent,owner 设为你的禅道账号(owner 必须登过 devmgt,否则录入失败)
  2. 复制完整 64 字符 key(别用前 8 位简写)

工时录入(task + bug)

提交类型 接口 body
task-xxxx POST /api/req/submit-effort {task_id, hours, comment}
bug-xxxx POST /api/req/bug-effort {bug_id, hours, comment}

均经 devmgt 代理,X-Api-Key 鉴权(per-agent,用你 owner 的禅道账号)。只有提交信息含工时时才触发录入;无工时直接放行,不录入、不阻断。

.gitignore 自动补全

每次 commit 时,hook 自动确保项目 .gitignore 含(无则创建,缺则追加,幂等):

  • .husky — hooks 个人本地,不进 git
  • .bams-zentao-config — 含 API-KEY,绝不能提交
  • .zentao-logs/ — 录入日志

临时跳过 / 卸载 / 更新

ZENTAO_DISABLED=true git commit -m "..."   # 单次跳过整个 hook

卸载 / 更新:重跑上面的「一条命令」,菜单选 2 或 3。

录入失败排查

录入失败不影响提交(始终 exit 0)。失败时控制台提示日志路径(.zentao-logs/commit-*.log),常见原因:

  • 任务/bug不存在:提交的 task-xxxx / bug-xxxx 在禅道不存在(编号写错)
  • 鉴权失败:API-KEY 非完整 64 字符,或 agent 的 owner 未登过 devmgt
  • URL 错误:填了禅道原生地址,应填 devmgt 代理 http://dns.xpku.com:5121/dev

仓库与发布

  • 公网安装器:https://doc.xpku.com/mcp/files/husky.sh(Mac/Linux)、husky.ps1(Windows)
  • 服务器目录:/opt/mcp-kb-data/static/(nginx 映射到 /mcp/files/)
  • 维护:改代码后 bash build-release.sh 重新打包 husky.sh,scp 上传覆盖