检测到已有配置文件时使用 overwrite、merge、skip 或 cancel\n --merge 合并支持合并的文件，其余已有文件跳过\n --skip-existing 跳过已存在的配置文件和 hook 文件\n --interactive / --no-interactive 强制开启或关闭交互式冲突处理\n --no-package-json 不更新 package.json scripts/devDependencies/config\n --no-husky 不写入 Husky hooks\n --no-prettier 不写入 Prettier 配置\n --no-commitlint 不写入 commitlint 配置和 commit-msg hook\n --no-lint-staged 不写入 lint-staged 配置和 pre-commit hook\n```\n\n`{pm}` 会被替换为自动识别或显式传入的包管理器。\n\n`--dry-run` 会打印和真实初始化一致的文件统计，但不会写入文件、修改 hook 权限或安装依赖。\n\n默认会写入普通 Husky hooks，执行 `lint-staged` 和 `commitlint`。使用 `--agentils-hooks` 时，会改为写入 AgentILS 自定义 hook 模板。\n\n初始化结果会使用类似 `git --stat` 的文件统计输出。覆盖写入的文件会按 rewrite 统计展示新增和删除，即使最终内容一致，用户也能看出命令确实执行了重写。\n\n## 冲突处理\n\n命令行参数优先。如果传入 `--conflict`、`--force`、`--merge` 或 `--skip-existing`，初始化器会直接按参数执行。\n\n如果没有传冲突策略，并且当前运行环境是交互式 TTY，初始化器会先检测已有配置文件和 hook 文件，再通过上下箭头让用户选择下一步：\n\n- `overwrite`：覆盖已有配置文件和 hook 文件\n- `merge`：合并支持安全合并的文件，其余无法安全合并的文件跳过\n- `skip`：保留已有配置文件和 hook 文件\n- `cancel`：在写入任何内容前取消操作\n\n目前 `.prettierignore` 支持按行合并。JavaScript 配置文件和 Husky hooks 在选择 `merge` 时会跳过，因为它们的安全结构化合并依赖具体项目代码。\n\n选择 `skip` 时，已有文件会显示为 skipped。选择 `merge` 且某个文件无法安全合并时，才会显示 cannot be merged safely。\n\n## 写入内容\n\n默认会写入或合并：\n\n- `package.json` 中的 `scripts` 和 `devDependencies`\n- `.czrc`\n- `prettier.config.mjs`\n- `.prettierignore`\n- `commitlint.config.mjs`\n- `lint-staged.config.mjs`\n- `.husky/pre-commit`\n- `.husky/commit-msg`\n\n生成或更新的 `package.json` scripts 包括：\n\n- `prepare`：`husky`\n- `commit`：`git-cz`\n- `format`：`prettier --write .`\n- `format:check`：`prettier --check .`\n- `changelog`：`conventional-changelog -p conventionalcommits -i CHANGELOG.md -s`\n- `changelog:all`：`conventional-changelog -p conventionalcommits -i CHANGELOG.md -s -r 0`\n- `generate:changelog`：同 `changelog`\n- `generate:changelog:first`：同 `changelog:all`\n\n默认加入的目标项目 `devDependencies`：\n\n- `husky`\n- `lint-staged`\n- `prettier`\n- `@commitlint/cli`\n- `@commitlint/config-conventional`\n- `commitizen`\n- `cz-conventional-changelog`\n- `conventional-changelog-cli`\n- `eslint`，仅在使用 `--with-eslint` 时加入\n\n## 模板目录\n\n配置模板和 help 文本位于源码 `templates/`，不会和 CLI 主逻辑混在一起。构建时会复制到 `dist/templates/`，因此压缩后的 CLI 只依赖构建产物也能运行。\n\n## Precommit 流水线（`agentils-precommit-gate`）\n\n本包同时安装第二个 bin —— `agentils-precommit-gate`，它会在 Husky `pre-commit` 阶段渲染一块 A320 ECAM 风格的 TUI 面板：每一步都有实时旋转指示、可选的 `[i/N]` 进度数字、以及最终的颜色块，把 commit 时的反馈从一坨灰色子进程日志变成可视化的检查清单。\n\n\n ![\"dry-run](\"https://raw.githubusercontent.com/bugfix2020/AgentILS/main/packages/quality-gate/preview/dry-run.gif\")
\n
\n Dry-run：所有步骤通过，面板收敛为绿色 ECAM 概要。\n
\n\n\n ![\"error](\"https://raw.githubusercontent.com/bugfix2020/AgentILS/main/packages/quality-gate/preview/error.gif\")
\n
\n 失败路径：失败步骤变红，整体以非零状态退出。\n
\n\n接到 Husky：\n\n```sh\n# .husky/pre-commit\n#!/bin/sh\nnpx agentils-precommit-gate\n```\n\n或直接从 `node_modules` 调用：\n\n```sh\nnode node_modules/@agent-ils/quality-gate/dist/precommit.js\n```\n\n### 配置文件发现（ESLint flat-config 风格）\n\n`agentils-precommit-gate` 会从当前目录逐层向上查找，每个目录内按以下顺序，命中第一个就停：\n\n```\nagentils-gate.config.js\nagentils-gate.config.mjs\nagentils-gate.config.cjs\nagentils-gate.config.ts\nagentils-gate.config.mts\nagentils-gate.config.cts\n```\n\n- 最近的目录优先（项目根的 config 覆盖 home 目录的）。\n- `--config ` 显式覆盖查找，直接加载该路径。\n- `--print-config` 打印命中的源路径和步骤列表后退出 0，CI debug 利器。\n- `.ts*` 配置要求项目里装了 [`jiti` ≥ 2.2](https://www.npmjs.com/package/jiti)，或 Node ≥ 22.13 加上 `--experimental-strip-types`。否则会报清晰错误指向缺失的加载器。\n- 找不到任何 config 时，落到内建 fallback：仅一步 `pnpm exec lint-staged`。这个 fallback 故意做得最小，让 npm 全新安装的用户开箱即用。\n\n### Schema\n\n```js\n// agentils-gate.config.mjs\nexport default {\n steps: [\n {\n label: 'LINT-STAGED',\n cmd: 'pnpm exec lint-staged', // shell 命令，或者…\n },\n {\n label: 'GENERATE FLOWCHARTS',\n argv: { command: 'node', args: ['scripts/render.mjs'] }, // …直接 argv 形式\n },\n ],\n}\n```\n\n每个 step 接受：\n\n- `label`（必填，非空字符串）— 面板上显示的名字。\n- `cmd` 与 `argv` 二选一（互斥，必须有一个）— `cmd` 走用户 shell；`argv` 不经 shell。\n- `render(state) => string`（可选）— 自定义行内容渲染（两个 `║` 之间的部分）。设置后面板原样使用你返回的字符串，不再走默认的 `[indicator] LABEL ... N/M` 布局。`render` 抛错也安全：面板会改显示红色的 `[render error] ![\"npm\"](\"https://img.shields.io/npm/v/@agent-ils/quality-gate?label=npm&color=CB3837\")
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white\"){kind=icon}
\n ![\"Node.js\"](\"https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white\"){kind=icon}
\n ![\"tsup\"](\"https://img.shields.io/badge/tsup-minified-7C3AED\"){kind=icon}
\n ![\"Prettier\"](\"https://img.shields.io/badge/Prettier-3.5-F7B93E?logo=prettier&logoColor=black\"){kind=icon}
\n ![\"Husky\"](\"https://img.shields.io/badge/Husky-9.1-111827\"){kind=icon}
\n