EverOS 分支模型与/new-branch工作流基于 main 保护策略的 Git 协作规范【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOS本篇文章深入解析 EverOS 仓库中.claude/skills/new-branch/SKILL.md所定义的 GitHub 分支创建规范从分支类型模型、操作步骤到命名约定并延伸讲解仓库中配套的提交信息、PR 校验与 CI 门禁帮助贡献者与维护者建立一套可复制、可校验的分支协作流程。读完本文你将掌握 EverOS 的分支命名体系、从main切出特性分支的标准命令序列以及仓库如何用 gitlint、pre-commit 与脚本门禁保证这条规范不被绕过。一、为什么需要一套统一的分支模型EverOS 是一个以main为默认分支、且默认受保护default and protected branch的仓库。在 CONTRIBUTING.md 的「For maintainers (core team)」一节中项目明确规定不要直接向main推送Do not push directly tomain不要对共享分支强制推送所有变更必须通过 PR 合入且需在必需检查通过之后。.claude/skills/new-branch/SKILL.md正是把这一协作约束固化为 Claude Code 斜杠命令/new-branch的完整定义。它的价值在于当开发者尤其是 AI 辅助开发环境需要新建分支时不用再去回忆「这个改动该用feat/还是fix/前缀」而是由技能文件给出确定性的分支模型、步骤与命名规范从源头保证仓库历史清晰、可审计、可回溯。二、分支模型六类分支与各自的职责边界/new-branch技能将仓库分支收敛为如下模型main default and protected branch feat/* feature work fix/* bug fixes docs/* documentation-only changes ci/* CI, build, and developer-experience changes chore/* repository maintenance refactor/* behavior-preserving code structure changes这一模型与 CONTRIBUTING.md 中维护者分支策略表完全一致两者互为印证分支职责main默认且受保护的分支feat/scope-desc功能开发fix/scope-desc缺陷修复docs/scope-desc仅文档变更ci/scope-descCI、构建与开发者体验相关变更其中refactor/*的语义值得注意它专指保持行为不变的代码结构重构behavior-preserving code structure changes。如果某次重构改变了外部行为那它本质上应当归类为feat/或fix/而不是refactor/。这个区分确保评审者在看到分支名时就能预判改动的风险等级。三、标准操作步骤从同步 main 到提交 PR/new-branch的核心流程只有四步但每一步都有明确约束第 1 步确认变更类型先询问或根据上下文推断本次变更属于哪一类feat、fix、docs、ci、chore或refactor。类型判断是后续一切命名与 PR 归类的前提.claude/skills/pr/SKILL.md 中 PR 模板的Area一栏也要求勾选 architecture / benchmark / use case / docs / DX / CI-build-release 等区域与分支类型形成对应关系。第 2 步先更新 main任何新分支都必须从最新的main切出避免基于过期主干开发git checkout main git pull --ff-only使用--ff-only是关键细节它强制快进合并一旦本地main与远端产生分叉就会直接失败从而杜绝「本地 main 落后却继续在其上开分支」的隐患。第 3 步以 kebab-case 短横线命名创建分支git checkout -b type/short-slug例如git checkout -b feat/add-agentic-rerank。slug 应尽量短小精炼short-slug仅描述本次改动的核心目的。第 4 步保持单一职责并提交 PR分支必须「一个分支只做一件事」Keep the branch scoped to one purpose最终通过 Pull Request 合回main。这与 .claude/skills/commit/SKILL.md 中「一次提交只包含一个逻辑变更、保持历史可 bisect」的要求一脉相承。四、命名规范类型前缀 kebab-case技能文件给出了明确的命名规则示例feat/add-agentic-rerank、fix/empty-profile-crash、docs/quickstart-config、ci/check-github-docs规则全部小写、用连字符hyphen分隔、不允许空格、尽量简洁注意前缀类型与提交信息的 type 字段遵循同一套词表。在 scripts/check_commit_messages.py 中ALLOWED_TYPES被定义为 11 种feat, fix, refactor, test, docs, style, perf, chore, build, ci, revert分支命名所用的类型是该集合的子集保持「分支名 → 提交信息 → PR 标题」三者风格统一。五、绝不对 main 直接提交多层防护机制/new-branch的最终约束是Never commit directly tomain— always use a branch and pull request。这句话在仓库中并不是一句口号而是被多层工具链强制执行的1. gitlintcommit-msg 阶段的提交信息门禁仓库根目录的 .gitlint 配置启用了contrib-title-conventional-commits并显式声明忽略 merge / revert / fixup / squash 提交[general] contribcontrib-title-conventional-commits ignore-merge-commitstrue ignore-revert-commitstrue ignore-fixup-commitstrue ignore-squash-commitstrue [contrib-title-conventional-commits] typesfeat,fix,refactor,test,docs,style,perf,chore,build,ci,revert [title-max-length] line-length72也就是说提交标题必须以合法 type 开头、总长不超过 72 字符否则commit-msg钩子直接拒绝。2. pre-commit 钩子矩阵.pre-commit-config.yaml 中通过make install内部执行uv run pre-commit install与uv run pre-commit install --hook-type commit-msg同时安装 pre-commit 与 commit-msg 两个阶段的钩子gitlint 只在commit-msg阶段运行stages: [commit-msg]其余钩子ruff、trailing-whitespace、check-yaml、check-merge-conflict、detect-private-key 等在提交前阶段拦截格式与安全隐患。3. 脚本门禁与 Makefile 入口Makefile 提供了两个直接对应本主题的目标make check-commits # python3 scripts/check_commit_messages.py $(RANGE) make check-pr-title # python3 scripts/check_pr_title.pyscripts/check_commit_messages.py 会扫描指定 git 范围内默认根据GITHUB_EVENT_NAME、GITHUB_SHA等环境变量推导的所有提交校验主题长度MAX_TITLE_LENGTH 72与正则^(|.join(ALLOWED_TYPES))(\([A-Za-z0-9._/-]\))?(!)?: .即type[(scope)][!]: description格式scripts/check_pr_title.py 复用同一策略模块校验 PR 标题并支持从PR_TITLE环境变量读取标题便于 CI 集成。其配套单测 tests/unit/test_scripts/test_check_pr_title.py 覆盖了「合法标题放行」「[codex] ...这类非规范前缀被拦截」「超过 72 字符被拦截」三类典型场景。这三层防线本地钩子、脚本门禁、CI 工作流共同保证即便开发者绕过/new-branch手动操作不合规的分支/提交/PR 标题也无法通过合入门槛。六、与 /commit、/pr 的协作闭环/new-branch不是孤立存在的。在 CONTRIBUTING.md 的「Slash commands (Claude Code)」一节中EverOS 提供了三个成体系的斜杠命令/new-branch— 按正确命名规范创建分支/commit— 生成符合 Conventional Commits 的提交信息/pr— 以正确目标分支打开 GitHub PR.claude/skills/pr/SKILL.md 展示了完整闭环先确认 base 分支是main、head 分支是feat/*之类的 scoped 分支本地跑make ci确保全部检查通过后再git push -u origin HEAD最后gh pr create --base main --fill-first并补全 PR 模板。也就是说一个标准的 EverOS 贡献周期是/new-branch切分支 → 开发 →/commit规范提交 →make ci全量校验 →/pr合入 main。本文所讲的分支模型是这个周期里的第一环也是后续所有门禁生效的前提。七、实战小结一份可直接执行的分支操作清单综合以上内容给出 EverOS 中一次合规变更的完整命令序列# 1. 同步 main git checkout main git pull --ff-only # 2. 按变更类型创建 kebab-case 分支 git checkout -b fix/empty-profile-crash # 3. 开发并规范提交gitlint 在 commit-msg 阶段校验 git add changed-files git commit -m fix(search): guard empty profile # 4. 全量校验 make ci # 5. 推送并打开指向 main 的 PR git push -u origin HEAD gh pr create --base main --fill-first需要特别提醒的两点约束其一分支名与提交信息必须为纯小写 连字符的 kebab-case杜绝空格与大写其二永远不要绕过 PR 直接向main推送——这条规则同时被 CONTRIBUTING.md、.gitlint 与脚本门禁三重背书是 EverOS 协作模型不可动摇的底线。【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 EverOS 分支模型与 `/new-branch` 工作流：基于 main 保护策略的 Git 协作规范
EverOS 分支模型与/new-branch工作流基于 main 保护策略的 Git 协作规范【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOS本篇文章深入解析 EverOS 仓库中.claude/skills/new-branch/SKILL.md所定义的 GitHub 分支创建规范从分支类型模型、操作步骤到命名约定并延伸讲解仓库中配套的提交信息、PR 校验与 CI 门禁帮助贡献者与维护者建立一套可复制、可校验的分支协作流程。读完本文你将掌握 EverOS 的分支命名体系、从main切出特性分支的标准命令序列以及仓库如何用 gitlint、pre-commit 与脚本门禁保证这条规范不被绕过。一、为什么需要一套统一的分支模型EverOS 是一个以main为默认分支、且默认受保护default and protected branch的仓库。在 CONTRIBUTING.md 的「For maintainers (core team)」一节中项目明确规定不要直接向main推送Do not push directly tomain不要对共享分支强制推送所有变更必须通过 PR 合入且需在必需检查通过之后。.claude/skills/new-branch/SKILL.md正是把这一协作约束固化为 Claude Code 斜杠命令/new-branch的完整定义。它的价值在于当开发者尤其是 AI 辅助开发环境需要新建分支时不用再去回忆「这个改动该用feat/还是fix/前缀」而是由技能文件给出确定性的分支模型、步骤与命名规范从源头保证仓库历史清晰、可审计、可回溯。二、分支模型六类分支与各自的职责边界/new-branch技能将仓库分支收敛为如下模型main default and protected branch feat/* feature work fix/* bug fixes docs/* documentation-only changes ci/* CI, build, and developer-experience changes chore/* repository maintenance refactor/* behavior-preserving code structure changes这一模型与 CONTRIBUTING.md 中维护者分支策略表完全一致两者互为印证分支职责main默认且受保护的分支feat/scope-desc功能开发fix/scope-desc缺陷修复docs/scope-desc仅文档变更ci/scope-descCI、构建与开发者体验相关变更其中refactor/*的语义值得注意它专指保持行为不变的代码结构重构behavior-preserving code structure changes。如果某次重构改变了外部行为那它本质上应当归类为feat/或fix/而不是refactor/。这个区分确保评审者在看到分支名时就能预判改动的风险等级。三、标准操作步骤从同步 main 到提交 PR/new-branch的核心流程只有四步但每一步都有明确约束第 1 步确认变更类型先询问或根据上下文推断本次变更属于哪一类feat、fix、docs、ci、chore或refactor。类型判断是后续一切命名与 PR 归类的前提.claude/skills/pr/SKILL.md 中 PR 模板的Area一栏也要求勾选 architecture / benchmark / use case / docs / DX / CI-build-release 等区域与分支类型形成对应关系。第 2 步先更新 main任何新分支都必须从最新的main切出避免基于过期主干开发git checkout main git pull --ff-only使用--ff-only是关键细节它强制快进合并一旦本地main与远端产生分叉就会直接失败从而杜绝「本地 main 落后却继续在其上开分支」的隐患。第 3 步以 kebab-case 短横线命名创建分支git checkout -b type/short-slug例如git checkout -b feat/add-agentic-rerank。slug 应尽量短小精炼short-slug仅描述本次改动的核心目的。第 4 步保持单一职责并提交 PR分支必须「一个分支只做一件事」Keep the branch scoped to one purpose最终通过 Pull Request 合回main。这与 .claude/skills/commit/SKILL.md 中「一次提交只包含一个逻辑变更、保持历史可 bisect」的要求一脉相承。四、命名规范类型前缀 kebab-case技能文件给出了明确的命名规则示例feat/add-agentic-rerank、fix/empty-profile-crash、docs/quickstart-config、ci/check-github-docs规则全部小写、用连字符hyphen分隔、不允许空格、尽量简洁注意前缀类型与提交信息的 type 字段遵循同一套词表。在 scripts/check_commit_messages.py 中ALLOWED_TYPES被定义为 11 种feat, fix, refactor, test, docs, style, perf, chore, build, ci, revert分支命名所用的类型是该集合的子集保持「分支名 → 提交信息 → PR 标题」三者风格统一。五、绝不对 main 直接提交多层防护机制/new-branch的最终约束是Never commit directly tomain— always use a branch and pull request。这句话在仓库中并不是一句口号而是被多层工具链强制执行的1. gitlintcommit-msg 阶段的提交信息门禁仓库根目录的 .gitlint 配置启用了contrib-title-conventional-commits并显式声明忽略 merge / revert / fixup / squash 提交[general] contribcontrib-title-conventional-commits ignore-merge-commitstrue ignore-revert-commitstrue ignore-fixup-commitstrue ignore-squash-commitstrue [contrib-title-conventional-commits] typesfeat,fix,refactor,test,docs,style,perf,chore,build,ci,revert [title-max-length] line-length72也就是说提交标题必须以合法 type 开头、总长不超过 72 字符否则commit-msg钩子直接拒绝。2. pre-commit 钩子矩阵.pre-commit-config.yaml 中通过make install内部执行uv run pre-commit install与uv run pre-commit install --hook-type commit-msg同时安装 pre-commit 与 commit-msg 两个阶段的钩子gitlint 只在commit-msg阶段运行stages: [commit-msg]其余钩子ruff、trailing-whitespace、check-yaml、check-merge-conflict、detect-private-key 等在提交前阶段拦截格式与安全隐患。3. 脚本门禁与 Makefile 入口Makefile 提供了两个直接对应本主题的目标make check-commits # python3 scripts/check_commit_messages.py $(RANGE) make check-pr-title # python3 scripts/check_pr_title.pyscripts/check_commit_messages.py 会扫描指定 git 范围内默认根据GITHUB_EVENT_NAME、GITHUB_SHA等环境变量推导的所有提交校验主题长度MAX_TITLE_LENGTH 72与正则^(|.join(ALLOWED_TYPES))(\([A-Za-z0-9._/-]\))?(!)?: .即type[(scope)][!]: description格式scripts/check_pr_title.py 复用同一策略模块校验 PR 标题并支持从PR_TITLE环境变量读取标题便于 CI 集成。其配套单测 tests/unit/test_scripts/test_check_pr_title.py 覆盖了「合法标题放行」「[codex] ...这类非规范前缀被拦截」「超过 72 字符被拦截」三类典型场景。这三层防线本地钩子、脚本门禁、CI 工作流共同保证即便开发者绕过/new-branch手动操作不合规的分支/提交/PR 标题也无法通过合入门槛。六、与 /commit、/pr 的协作闭环/new-branch不是孤立存在的。在 CONTRIBUTING.md 的「Slash commands (Claude Code)」一节中EverOS 提供了三个成体系的斜杠命令/new-branch— 按正确命名规范创建分支/commit— 生成符合 Conventional Commits 的提交信息/pr— 以正确目标分支打开 GitHub PR.claude/skills/pr/SKILL.md 展示了完整闭环先确认 base 分支是main、head 分支是feat/*之类的 scoped 分支本地跑make ci确保全部检查通过后再git push -u origin HEAD最后gh pr create --base main --fill-first并补全 PR 模板。也就是说一个标准的 EverOS 贡献周期是/new-branch切分支 → 开发 →/commit规范提交 →make ci全量校验 →/pr合入 main。本文所讲的分支模型是这个周期里的第一环也是后续所有门禁生效的前提。七、实战小结一份可直接执行的分支操作清单综合以上内容给出 EverOS 中一次合规变更的完整命令序列# 1. 同步 main git checkout main git pull --ff-only # 2. 按变更类型创建 kebab-case 分支 git checkout -b fix/empty-profile-crash # 3. 开发并规范提交gitlint 在 commit-msg 阶段校验 git add changed-files git commit -m fix(search): guard empty profile # 4. 全量校验 make ci # 5. 推送并打开指向 main 的 PR git push -u origin HEAD gh pr create --base main --fill-first需要特别提醒的两点约束其一分支名与提交信息必须为纯小写 连字符的 kebab-case杜绝空格与大写其二永远不要绕过 PR 直接向main推送——这条规则同时被 CONTRIBUTING.md、.gitlint 与脚本门禁三重背书是 EverOS 协作模型不可动摇的底线。【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考