gitx

GitX

默认操作

在不带参数的调用中——$gitx、gitx，或不带额外命令的技能 UI 调用——立即执行 Smart commit 工作流。第一步必须检查仓库的 Git 状态和相关差异。检查后，创建适当的提交；如果没有内容需要提交，则报告这一点。

将不带参数的调用视为操作，而不是帮助请求。不要宣布 GitX 已加载，不要列出命令或示例，不要询问要运行哪个命令，也不要等待进一步指示。只有当用户明确请求帮助或可用命令时，才显示命令列表。

命令与分发

将自然语言请求匹配到以下命令。当用户想要只读摘要时，将“check my changes”或“show git status”分发到 Status；将“run tests before committing”分发到 Checks。使用 Doctor 诊断 Git 工作流问题，使用 Plan 预览提交。仅当工作流适用或满足加载条件时，才读取配套参考资料。

根据参数形式分发 gitx issue，而不是根据措辞暗示的意图。参数仅包含 issue 编号时，例如 123 或 #123，选择现有 issue 的实现工作流。其他所有非空参数均视为新 GitHub issue 的描述，即使其中包含“fix”“update”或“resolve”等词语。没有参数时，询问 issue 描述。绝不要实现通过非数字 gitx issue 描述提供的问题。

gitx issue <description> 明确要求发布到 GitHub。仓库本地的跟踪约定不会将此命令重定向到本地文件；请遵循 GitHub issue 创建工作流，包括其中的失败处理方式。

对于 gitx ship [base]，可选参数是 PR 的目标分支，绝不是新功能分支的名称。例如，gitx ship dev 的目标是 dev。分发到 Ship，而不是直接分发到 Branch 或 Pull requests。

命令	操作
gitx	创建智能提交。
gitx setup	预览并将项目偏好设置保存到仓库的 .gitx.json 中。
gitx body	创建包含实用提交正文的智能提交。
gitx branch [name]	创建并切换到一个分支。
gitx branch check	创建默认分支，运行检查，然后创建智能提交。
gitx pull	安全地拉取当前分支的更新。
gitx push	将当前分支推送到 origin。
gitx pr [base]	创建 GitHub 拉取请求，将其合并到指定、已配置或默认的基础分支。
gitx ship [base]	必要时创建功能分支，运行检查、提交、推送，并创建拉取请求，将其合并到指定、已配置或默认的基础分支。
gitx issue <description>	使用生成的标题和正文创建 GitHub issue。
gitx issue <number>	修复对应编号的 GitHub issue。
gitx resolve	解决进行中的合并或变基冲突。
gitx check	运行相关检查，然后创建智能提交。
gitx status	显示 Git 状态和更改文件摘要；不做任何更改。
gitx doctor [problem]	诊断仓库问题并建议后续步骤；不做任何更改。
gitx tree	显示精简的 Git 历史树和仓库上下文；不做任何更改。
gitx scan	扫描更改和历史记录，查找暴露的机密信息和敏感文件；不做任何更改。
gitx plan	预览拟议的提交分组和消息；不做任何更改。
gitx type <type>	使用指定的 Conventional Commit 类型创建智能提交。
gitx scope <scope>	使用指定的作用域创建智能提交。
gitx files <paths>	仅使用指定文件创建智能提交。
gitx amend	请求确认后，修改最近一次提交。

项目偏好设置

在应用提交、规划、分支、检查、PR 或发布的默认设置之前，先在当前工作树根目录（git rev-parse --show-toplevel）查找 .gitx.json。如果存在，请阅读 项目偏好设置，验证配置，并仅应用与所请求工作流相关的字段。如果不存在，则保留现有行为。不要在常规命令期间创建配置，也不要仅仅因为该文件存在就执行已配置的检查。

用户明确指定的选择优先于已保存的偏好设置；已保存的偏好设置优先于 GitX 推断的默认设置。仍须遵守仓库要求和执行权限。无效配置必须在相关变更操作前说明；只读命令可以报告问题，但无需因此停止无关检查。

对于 gitx setup，请按照参考文档检查本地惯例，预览确切的拟议 JSON，并且只创建或更新根目录下的 .gitx.json。Setup 不会运行检查、暂存、提交、推送、创建 PR，也不需要 GitHub 身份验证。

智能提交

1. 检查 git status 以及已暂存和未暂存的差异。优先使用已暂存的更改；否则使用所有安全的已更改文件。对于 gitx files <paths>，仅在这些路径范围内应用此偏好。如果选择已暂存的更改，部分暂存文件只包含其已暂存的编辑。保留排除的已暂存更改和所有未选中的工作树编辑。

2. 包含已修改的受跟踪文件、安全的未跟踪文件和已删除文件。排除被忽略的文件，并在包含有风险的文件前发出警告。

3. 按用途对所选更改分组，包括同一文件中的单独编辑。如果一个文件涉及多个分组，或暂存操作必须与未选中的编辑隔离，请阅读 同一文件的提交拆分。除非存在连贯的中间版本序列，否则应将相互重叠或存在依赖关系的编辑放在一起；按顺序先处理前置事项。

4. 如果适合用一个提交，则创建一条清晰的 Conventional Commit。对于 gitx type <type> 或 gitx scope <scope>，使用提供的类型或范围。推断范围时，如果存在已配置的 commitScopes，则使用它；如果没有合适的范围，就省略范围，不要凭空编造。将此规则应用于每个拟议分组，包括 gitx plan。

5. 如果适合创建两个或更多提交，则计算实际逻辑分组数量并询问：

   你希望我创建 N 个提交，还是一个提交？

   提问前，展示每条拟议提交消息及其包含的编辑；如果某个文件涉及多个分组，请指出相应函数或代码块。将 N 替换为实际数量。绝不要按字面显示 N 或 {count}。只有用户选择多个提交时才创建多个提交；否则创建一个提交。按照参考文档所述，使用仅针对索引的补丁执行已批准的分组；如果某个文件包含未选中或延后处理的编辑，不要将整个文件暂存。

6. 对于 gitx body，为每条提交消息添加有用的正文。

7. 智能提交时不要推送。只有在执行 gitx push 或用户明确要求推送时才推送。

提交规划

对于 gitx plan，使用智能提交的选择和分组规则，并展示拟议的提交分组数量、每组的文件和编辑摘要，以及拟议的 Conventional Commit 消息。指出共享文件、依赖关系，以及必须放在一起的编辑。不要修改文件或索引，不要创建 Git 对象、提交、分支或进行推送；参考文档中的执行步骤仅适用于提交。

分支

对于 gitx branch [name]：

1. 保留现有更改；除非用户明确要求，否则不要丢弃或暂存这些更改。
2. 如果提供了有效的分支名称，则原样使用。如果未提供名称，则生成一个小写 kebab-case 名称，并在配置了 branchPrefix 时应用它：如果是字符串，则将其用作固定前缀；如果是数组，则根据项目偏好选择最合适的前缀。否则，根据预期工作推断合适的前缀：新功能用 feat/，错误修复用 fix/，仅紧急生产修复用 hotfix/，文档用 docs/，结构调整用 refactor/，测试用 test/，维护工作用 chore/。如果前缀不明确，请询问用户；切勿默认使用 hotfix/。
3. 检查该分支是否已在本地或 origin 上存在。如果存在，询问用户是要切换到该分支，还是选择其他名称。切勿覆盖现有分支。
4. 使用 git switch -c <branch-name> 创建并切换分支。
5. 除非命令是 gitx branch check，或用户明确要求，否则不要提交或推送。

对于 gitx branch check，根据上述命名规则创建分支，然后遵循 Checks 行为和 Smart commit 行为。

检查

对于 gitx check，如果存在已配置的 checks，则按顺序使用；否则检测相关检查，例如 npm test、npm run lint、pnpm test、pytest、cargo test、go test ./... 或 make test。遵循偏好参考中的命令检查和工作目录规则。即使仓库指令要求的检查不在已配置列表中，也必须执行。如果检查失败，询问用户是否仍要提交。Ship 在失败时采用更严格的停止行为。

拆分提交时，按照参考说明，对每个拟议的暂存快照分别运行用户要求的检查。对完整工作树的检查通过，并不能验证中间提交。普通的智能提交需要检查差异和依赖项，但不会默认要求运行测试套件。报告测试过哪些快照，以及哪些检查无法运行。

拉取

对于 gitx pull：

1. 检查当前分支、上游分支和工作树。若未提交的更改可能被覆盖，则不要拉取；说明当前状态并询问用户如何继续。
2. 检查是否存在名为 origin 的远程。如果不存在，说明没有拉取任何内容；不要自动选择其他远程。
3. 根据仓库现有的拉取／变基配置，从 origin 拉取当前分支。如果 origin 上没有同名分支，说明没有可拉取的内容。不要使用 --force，也不要丢弃本地工作。
4. 如果集成过程产生冲突，则停止拉取工作流，并遵循冲突解决行为。

推送

对于 gitx push：

1. 检查是否存在名为 origin 的远程。如果不存在，说明没有推送任何内容；不要自动选择其他远程。
2. 将当前分支推送到 origin。如果当前分支没有上游分支，则立即使用 git push -u origin <branch> 创建上游分支。

拉取请求

对于 gitx pr [base]，请阅读拉取请求，了解基础分支解析、发布、现有 PR 的处理方式和创建流程。该参考还规定了与 Ship 共享的标题、正文和就绪状态约定。

Ship

对于 gitx ship [base]，请阅读Ship 工作流。此命令授权在需要时创建功能分支、运行检查、提交选定的更改、将源分支推送到 origin，并通过该推送创建或更新开放的 PR。此命令不授权合并 PR、强制推送或自动集成已分叉的历史记录。

复用分支命名、智能提交选择和分组、检查检测以及项目偏好。准备 PR 时，请阅读共享的 PR 约定。Ship 的参考规定了发布顺序，包括检查失败时的处理方式，以及返回现有 PR 前的推送步骤。

GitHub issues

对于 gitx issue，使用上文的参数形状分派，然后阅读 GitHub issues 中选定的工作流。该参考文档定义了先决条件、实现边界和新建 issue 模板。

冲突解决

对于 gitx resolve 或正在进行的合并或 rebase 冲突：

1. 检查操作状态、历史记录和每个冲突文件。
2. 追溯每个冲突两侧的来源提交，并理解每项更改的意图。阅读提交消息，以及本地可用的 issue 或 PR 上下文（如有）。
3. 解决每个冲突块时，尽可能保留双方意图。如果两者冲突，则选择最符合集成目标的行为，并清楚说明其中的取舍。不要擅自加入无关行为，也不要中止操作，除非用户明确要求。
4. 运行项目相关检查；如果已配置 checks，则按其列出的顺序执行，并包含仓库要求的检查；否则通常依次运行类型检查、测试和格式检查。修复由冲突解决引入的问题。
5. 暂存已解决的文件并完成操作：提交合并，或运行 git rebase --continue，并重复此过程直至 rebase 完成。不要强制推送。

状态和历史记录

对于 gitx status，显示当前分支、已暂存文件、未暂存文件、未跟踪文件，以及简洁的文件变更摘要。不要修改仓库。

对于 gitx tree，显示当前分支及其上游、工作树摘要、相对于上游或 origin 的领先／落后提交数、当前 PR（如有），以及最近 20 个提交的紧凑图表。不要 fetch、pull、push、创建分支或以其他方式修改仓库。

仓库诊断

对于 gitx doctor [problem]，阅读 仓库诊断。检查本地仓库状态和用户提供的任何错误，说明发现的阻塞因素及其实际影响，并建议最小的适当后续步骤。可选的问题描述用于聚焦诊断；它不代表授权进行修复。如果未提供问题描述，则检查常见的工作流阻塞因素。

诊断必须保持只读：不要 fetch、修改文件或 Git 状态、运行项目检查或钩子、测试 push、启动身份验证或应用修复。区分已确认的发现、可能的原因和无法获取的信息。本地远程跟踪引用可能已过期，且无法总是根据本地状态解释失败的 Git 操作。不要仅仅因为存在更改或冲突，就将 doctor 请求转入 Smart commit 或冲突解决。

密钥扫描

对于 gitx scan，阅读 密钥扫描，了解只读扫描范围、工具选择、暴露情况分类、脱敏方式，以及报告格式和评级。

Amend

对于 gitx amend，先请求确认并显示拟定的修改后提交消息。只有在用户确认后，才能修改最近一次提交。不要修改合并提交。不要强制推送；如果修改后的提交已推送，则说明常规 push 会被拒绝，并询问用户希望如何处理。

安全与风险文件

在纳入可能包含密钥、凭据、私钥、日志或构建产物的文件前，始终发出警告，包括 .env、*.pem、*.key、credentials、token、secret、api_key、*.log、dist/、build/ 和 node_modules/。