one hk

one hk 通过 One 选择的 mise（优先系统版本，否则按需下载并托管） 运行固定版本的 hk。Go、JS/TS 和混合工作区使用同一套入口，不需要为了 Git hooks 安装 Husky 或 commitlint。

日常使用

one hk check                 # 检查变更文件
one hk check --all           # 检查整个工作区，也可用于 CI
one hk check --plan --json   # 查看检查计划，不执行检查
one hk fix                   # 显式修复，默认不暂存修改
one hk validate              # 校验 hk 配置

One 从工作区根目录运行 hk；指定文件时使用相对工作区根目录的路径，例如 one hk check apps/web/src/App.tsx。hk 参数、标准输出和退出码直接透传。

提交前检查失败时，One 会提示在工作区根目录执行 one hk fix。hk 会自动进入各项目目录，使用对应的 lint/format 工具；修复后检查改动，用 git add 重新暂存，再提交。无法自动修复的问题仍需根据检查输出手动处理。

one mise 保留当前工作目录。hk 输出中的 package.json、src/... 等路径可能相对于子项目，不能直接在工作区根目录复制执行。手动运行 web 项目的格式化工具时，应明确进入该项目：

cd apps/web
one mise exec -- pnpm exec oxfmt --write package.json

oxfmt 来自项目的开发依赖；如果项目目录内仍提示找不到命令，先在工作区根目录运行 one mise exec -- pnpm install。

新工作区自动安装本地 pre-commit 和 commit-msg 启动器，继续正常使用 git commit。克隆已有工作区后，运行一次：

one init hooks

Git 启动器记录本次 One 可执行文件的位置，并通过它解析和运行 mise；不依赖终端的 mise 激活状态。移动或更换 One 安装位置后，可以重新执行 one init hooks。

默认检查

阶段	行为
提交前	检查暂存内容；临时保存并恢复未暂存修改，不自动修复或暂存文件
提交信息	hk 内置的 Conventional Commits 基础检查，支持中文描述
Go 项目	使用该项目的 Go 版本检查 gofmt 格式；修复时调用 gofmt -w
JS/TS 项目	使用项目已经声明的 oxlint / oxfmt，按文件筛选并读取项目配置
其他 Node 工具	存在时复用 lint、format:check 和相应的 :fix 脚本；脚本可能检查整个项目

提交检查按暂存文件执行；Go 模板的 check 只做格式和 vet 检查，tidy 单独执行。构建、类型检查和测试仍可通过项目原有命令执行，也可以自行加入 hk 配置。

工具版本由 mise 提供，首次需要时下载并缓存。mise 本身优先使用系统版本，本地没有可用程序时由 One 下载并托管；hk 是单独安装的工作区工具。JS 检查使用项目依赖，需要先安装依赖；one dev -p <project> 会准备开发依赖，也可运行 one mise exec -- pnpm install。

配置与项目增量更新

• .config/hk.pkl：工作区唯一的 hk 配置，hk 会从根目录自动发现它；检查项中的项目路径仍相对工作区根目录。
• mise.toml：声明固定的 hk 版本。
• Git hooks：安装到当前仓库的 Git hooks 目录，不写用户全局 Git 配置。

直接在 .config/hk.pkl 中增加检查或修改设置。one add 和 one init hooks 会按检查项增量更新：未改动的默认检查自动刷新，用户修改与注释保留。同一检查项同时被用户和 One 改动时，报告 HOOKS_CONFIG_CONFLICT，保留当前文件。

请保留 // one:begin、// one:end、// one:insert 和末尾的 // one:managed-v1 跟踪注释。自定义检查可加在 steps 块内、生成项的标记之外；删除某个默认检查时，连同它对应的 begin/end 标记一起删除，后续刷新会保留这次删除。已有且不带 One 标记的 .config/hk.pkl 完全由用户维护，One 不会替换它。

新增自定义 hook 事件时，需要自行接入对应 Git 启动器；One 默认安装 pre-commit 和 commit-msg。如果已有根目录 hk.pkl，请把配置合并到 .config/hk.pkl 后移除根文件，避免 hk 优先读取旧文件。

迁移旧工作区

one init hooks --dry-run -o json
one init hooks
one mise exec -- pnpm install

预览会列出配置、Git 启动器以及将移除的默认文件。只有 One 以前生成的默认 Husky / commitlint 配置会自动迁移；自定义规则、额外的 Husky hook、已有的其他 hook 目录会报告 HOOKS_CONFIG_CONFLICT，保留原文件供手动整合。

迁移移除根 package.json 中的 Husky / commitlint 依赖以及默认 prepare: husky，保留已有的 Changesets 等其他配置。最后使用实际包管理器执行安装，以更新锁文件；命令本身不会猜测或重写包管理器锁文件。

hk 的基础提交检查不等价于 commitlint 的全部规则。例如自定义的长度、大小写和插件规则，需要显式补充到 .config/hk.pkl 中。

CI

准备 One 和项目依赖后运行 one hk check --all。该命令复用本地检查配置，不安装 Git hooks，也不自动修复代码；现有构建和测试步骤继续保留。