Documenso/commit命令解析:基于 Conventional Commits 的标准化 Git 提交流程【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso本文以 Documenso 仓库中的 Agent 命令文件 .opencode/commands/commit.md 为主体,完整讲解该命令定义的分析改动、暂存文件、判定提交类型、撰写提交信息四步流程,并结合同仓库中 commitlint 配置、Husky 钩子与 lint-staged 脚本,说明这套提交流程如何在 CI/钩子层面得到强制校验,帮助读者在 Documenso(或同类 monorepo)中规范地构造可追溯、可被工具链校验的提交。1. 文件定位:一个 OpenCode Agent 命令,而不是一篇普通说明.opencode/commands/commit.md 是 OpenCode 这类 AI 编码助手的斜杠命令(slash command)定义文件,与同目录下的implement.md、create-plan.md、interview.md等文件共同构成仓库的 Agent 工作流。文件开头的 YAML frontmatter 声明了命令元数据:--- description: Add and commit changes using conventional commits allowed-tools: Bash, Read, Glob, Grep ---description说明该命令的用途是按照 Conventional Commits 标准添加并提交改动;allowed-tools约束了执行该命令时 Agent 只能使用Bash、Read、Glob、Grep四类工具,即允许运行 git 命令、读取文件、做文件名与内容检索,但不会放开文件写入之外的其他能力。在 CONTRIBUTING.md 的命令表中,它以/commit的形式对外暴露:|/commit| Create a conventional commit for staged changes |并且被纳入推荐的Typical Workflow最后一步:/create-plan起草规格 →/interview细化需求 →/implement实现 →/continue续写 →/commit创建符合规范的提交。也就是说,该命令是 Documenso 面向 AI 辅助开发流程设计的提交收尾环节,其目标是在人类与 Agent 共同产出代码时,保证最终进入 git 历史的提交信息风格一致、可被工具链自动校验。2. 提交前:用 4 条 git 命令完成工作区分析命令文件要求 Agent 在动手前必须先执行以下四条命令,把当前改动的全貌看清楚:git status # 查看所有 modified/untracked 文件 git diff # 查看未暂存的工作区改动 git diff --staged # 查看已暂存(staged)的改动 git log --oneline -5 # 查看最近 5 条提交,对齐既有提交风格这四条命令分别对应三个分析目的:改动范围:git status列出所有被修改与未跟踪的文件,判断本次提交应覆盖哪些文件;改动内容:git diff与git diff --staged区分未暂存与已暂存两类改动,避免把尚未审完的代码误提交,也避免漏掉用户已经暂存的内容;风格对齐:git log --oneline -5回看近期提交,使新提交与该仓库既有的type: description习惯保持一致。以本仓库浅克隆可见的历史提交为例,最近一条就是标准写法:fix: add patches back to dockerfile (#3324)可以看到fix:类型前缀、祈使句描述、无 scope 的格式,与命令文件的要求完全吻合。3. 暂存文件:相关改动全加,密钥类文件必须跳过命令文件对git add阶段给出两条硬性约束:用git add暂存所有相关的改动(而非git add -A盲目全加);绝不暂存疑似包含密钥的文件,如.env、credentials、API keys、tokens;若检测到潜在密钥,必须先向用户告警并跳过这些文件。这条规则针对的是 AI Agent 辅助开发中的典型风险:Agent 在调试中可能生成临时.env或写入测试用的 token,如果不加甄别地全量暂存,密钥就会永久进入提交历史。后文Rules一节进一步把该规则升级为 NEVER commit files that may contain secrets,形成两次强调。4. 判定提交类型:Conventional Commits 的 10 种 type命令文件给出了完整的 type 判定表,这是 Conventional Commits 标准的核心词汇表:type适用场景feat新功能或新能力fix缺陷修复docs仅文档改动style格式化、空白字符(非 CSS 改动)refactor不改变行为的重构perf性能优化test新增或更新测试build构建系统或依赖变更ciCI/CD 配置chore维护性任务、工具链、配置并特别注明:本仓库的提交不使用 scope(文档原文 NOTE: Do not use a scope for commits)。这里有一个值得注意的细节:命令文件给出的通用格式模板写作type[scope]: subject,即 scope 在模板层面是可选段;但针对 Documenso 仓库的 NOTE 进一步收紧为一律不加 scope。二者并不矛盾——模板描述的是 Conventional Commits 的通用形态,而 NOTE 是仓库级约束。结合 git 历史中fix: add patches back to dockerfile (#3324)这类无 scope 的实际提交,可以推断 Documenso 的约定就是无 scope 的type: subject。5. 撰写提交信息:subject 与 body 的量化规则5.1 Subject 行格式为type: description,并给出四条可度量的书写规则:祈使语气:用 add 而不是 added;小写开头,句尾不加句号;长度:尽量不超过 50 字符,硬性上限 72 字符。5.2 Body(可选正文)解释的是why(为什么改),而不是 what(改了什么);每行在 72 字符处换行;与 subject 之间用一个空行分隔。5.3 命令文件中的两个示例简单改动(仅 subject):fix: handle empty input in parser without throwing带 body 的改动:feat: add streaming response support Large responses were causing memory issues in production. Streaming allows processing chunks incrementally.第二个示例体现了 explain why 的原则:body 说明大响应在内存上的问题,而不是复述添加了 streaming。6. Rules:五条不可触碰的硬规则命令文件的 Rules 一节用 NEVER 措辞给出了五条硬约束,其中多条与 git 的危险操作直接相关:绝不提交可能包含密钥的文件(与第 3 节呼应,从跳过升级为绝不提交);未经用户明确要求,绝不使用git commit --amend——amend 会改写历史,在已推送的分支上极易引发协作事故;绝不使用--no-verify绕过钩子——这一点在 Documenso 仓库中有具体的工程背景:该仓库通过 Husky 安装了commit-msg与pre-commit两个钩子(见第 8 节),--no-verify会同时绕过 commitlint 与 lint-staged,等于放弃所有自动化质量门;若 pre-commit 钩子失败,应修复问题后新建一个提交,而不是反复重试或跳过钩子;如果没有任何可提交的改动,直接告知用户并停止,不做无意义提交。此外还要求使用 HEREDOC 传递提交信息以保证多行 body 的换行格式不被 shell 破坏,例如:git commit -m $(cat EOF feat: add streaming response support Large responses were causing memory issues in production. EOF )7. 仓库侧的证据:同样的规则如何被钩子与 CI 强制命令文件规定的是Agent 应当怎么写,而 Documenso 仓库在工具链层面配置了对应的校验,使上述规范具有强制性。以下均为仓库内可直接查看的配置:7.1 commitlint:提交信息的最终校验器根目录 commitlint.config.cjs 只有两行:module.exports { extends: [commitlint/config-conventional], };即直接继承 Conventional Commits 官方预设,校验规则与第 4、5 节的 type 表、subject 长度与格式完全同源。package.json 的 devDependencies 中锁定了commitlint/cli与commitlint/config-conventional,并提供脚本(见 package.json):commitlint: commitlint --editcommitlint --edit的语义是:读取本次git commit所编辑的 message 文件并执行校验,校验失败则提交被拒绝。7.2 Husky 钩子:commit-msg 与 pre-commit 双保险仓库的.husky/目录包含两个钩子文件:.husky/commit-msg 内容为一行npm run commitlint -- $1,即把 commitlint 接到每次提交的信息校验上;.husky/pre-commit 则执行三步:先运行node scripts/copy-wellknown.cjs把.well-known/内容复制进构建产物,再git add apps/remix/public/纳入这些生成文件,最后执行npx lint-staged对暂存文件做增量检查。钩子的安装由 package.json 的prepare脚本在npm install后自动触发:prepare: husky husky install || true这与命令文件 Rules 中不要用--no-verify绕过钩子钩子失败要修复后新建提交两条规则形成闭环:钩子确实存在、确实会被触发,绕开它们意味着跳过真实的工程检查。7.3 lint-staged:只检查暂存文件lint-staged.config.cjs 定义了两条增量检查规则:module.exports { **/*.{ts,tsx,cts,mts,js,jsx,cjs,mjs,json,css}: npm run lint:staged, **/*/package.json: npm run precommit, };所有暂存的源码/样式/JSON 文件会执行npm run lint:staged(对应 package.json 中的biome check --write --no-errors-on-unmatched),即 Biome 对暂存文件做格式与 lint 修复;任何工作区目录下的package.json被暂存时,执行npm run precommit,而该脚本(见 package.json)为:precommit: npm install git add package.json package-lock.json也就是说,改动依赖的提交会自动把package-lock.json的变化同步暂存进来,避免锁文件与package.json脱节。这正是第 3 节暂存所有相关改动要求的一个自动化实现。8. 在 Documenso 工作流中完整走一遍/commit把命令文件与仓库证据串起来,在 Documenso 中执行一次标准提交等价于以下完整流程:git status/git diff/git diff --staged/git log --oneline -5完成改动分析,确认近期风格为无 scope 的type: description;甄别并git add相关改动,确认无.env、token 等敏感文件;若涉及依赖变更,pre-commit钩子会自动补齐package-lock.json;按第 4 节的 10 种 type 判定类型,按第 5 节规则书写 subject(祈使句、小写、≤50/72 字符)与可选 body(解释 why、72 字符换行);用 HEREDOC 方式执行git commit;若 pre-commit(Biome 增量 lint)或 commit-msg(commitlint)钩子失败,按 Rules 修复问题后新建提交,而非--amend或--no-verify。9. 关键文件速查文件作用.opencode/commands/commit.md/commit命令定义:流程、type 表、格式规则、硬规则commitlint.config.cjs继承commitlint/config-conventional,校验提交信息.husky/commit-msg提交时触发npm run commitlint.husky/pre-commit复制 well-known 资源、暂存生成文件、运行 lint-stagedlint-staged.config.cjs暂存文件增量 Biome 检查;package.json 变更时同步锁文件package.jsoncommitlint、precommit、prepare(husky 安装)等脚本定义CONTRIBUTING.md/commit在 Agent 工作流中的位置与用法说明这套设计的特点是Agent 侧规范与工具链侧校验同源:命令文件教 Agent 写出符合 Conventional Commits 的提交,commitlint 与 Husky 钩子则在本地把不符合规范的提交挡在 git 历史之外,两者共同保证了 Documenso 提交日志的一致性与可机器解析性。【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考