企业官网建设流程全解析

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 条提交,对齐既有提交风格

这四条命令分别对应三个分析目的:

1. 改动范围:git status列出所有被修改与未跟踪的文件,判断本次提交应覆盖哪些文件;
2. 改动内容:git diff与git diff --staged区分未暂存与已暂存两类改动,避免把尚未审完的代码误提交,也避免漏掉用户已经暂存的内容;
3. 风格对齐: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 标准的核心词汇表:

并特别注明:本仓库的提交不使用 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 的危险操作直接相关:

1. 绝不提交可能包含密钥的文件(与第 3 节呼应,从"跳过"升级为"绝不提交");
2. 未经用户明确要求,绝不使用git commit --amend——amend 会改写历史,在已推送的分支上极易引发协作事故;
3. 绝不使用--no-verify绕过钩子——这一点在 Documenso 仓库中有具体的工程背景:该仓库通过 Husky 安装了commit-msg与pre-commit两个钩子(见第 8 节),--no-verify会同时绕过 commitlint 与 lint-staged,等于放弃所有自动化质量门;
4. 若 pre-commit 钩子失败,应修复问题后新建一个提交,而不是反复重试或跳过钩子;
5. 如果没有任何可提交的改动,直接告知用户并停止,不做无意义提交。

此外还要求使用 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 --edit"

commitlint --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 中执行一次标准提交等价于以下完整流程:

1. git status/git diff/git diff --staged/git log --oneline -5完成改动分析,确认近期风格为无 scope 的type: description;
2. 甄别并git add相关改动,确认无.env、token 等敏感文件;若涉及依赖变更,pre-commit钩子会自动补齐package-lock.json;
3. 按第 4 节的 10 种 type 判定类型,按第 5 节规则书写 subject(祈使句、小写、≤50/72 字符)与可选 body(解释 why、72 字符换行);
4. 用 HEREDOC 方式执行git commit;
5. 若 pre-commit(Biome 增量 lint)或 commit-msg(commitlint)钩子失败,按 Rules 修复问题后新建提交,而非--amend或--no-verify。

9. 关键文件速查

这套设计的特点是"Agent 侧规范"与"工具链侧校验"同源:命令文件教 Agent 写出符合 Conventional Commits 的提交,commitlint 与 Husky 钩子则在本地把不符合规范的提交挡在 git 历史之外,两者共同保证了 Documenso 提交日志的一致性与可机器解析性。

【免费下载链接】documensoThe Open Source DocuSign Alternative.项目地址: https://gitcode.com/GitHub_Trending/do/documenso