【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载Gentle-AIgentle-ai是一个用 Go 编写的 CLI/TUI 生态配置器用于统一配置 Claude Code、Cursor、OpenCode、Codex、Pi 等 AI 编码 Agent。本文基于仓库根目录的 CONTRIBUTING.md 展开完整梳理该项目无 Issue 不 PR的协作流程、AI 辅助贡献政策、标签体系、本地开发与多级测试矩阵单元测试、Docker E2E、Cross-Lane Battery、Benchmark、Conventional Commits 提交规范以及400 行 / 60 分钟的 PR 认知负载预算。读完本文你将掌握如何在该仓库中从零发起一个会被 CI 放行、并最终合入主线的贡献先开被批准的 Issue再写工作单元提交最后以正确格式的 PR 完成交付。Issue-First无 Issue 的 PR 一律拒绝项目采用严格的问题先行issue-first工作流核心原则只有一句No PR without an issue. No exceptions.标准流程分四步开 Issue使用对应模板提交 [Bug Report] 或 [Feature Request]在仓库 Issues 页选择对应模板。等待批准只有 Issue 被贴上status:approved标签后工作才允许开始。根据规范中的表述在没有当前直接指令与目标主机能力授予精确动作的情况下应在评论中等待而不是直接开工。在 Issue 上留言声明你正在处理它让其他人知晓避免重复劳动。打开 PR 并关联已批准的 Issue。未关联已批准 Issue 的 PR 会被 CI自动拒绝——这不是人工抽查而是流水线级的强制约束。PR 验证工作流的实现位于 .github/workflows/pr-check.yml其中check-issue-reference与check-issue-approved两个 job 分别校验 PR 正文是否包含格式正确的 Issue 引用、以及被引用 Issue 是否携带status:approved标签任何一项不满足都会直接core.setFailedPR 无法通过。想找活干从 Community Roadmap 出发。所有带up-for-grabs标签的 Issue 都满足三个条件有明确范围问题被陈述、失败可复现或行为被定义、指明了代码树中的位置、已获批准携带status:approved可以开 PR、无人认领。评论一句我来做即可认领。而没有该标签的 Issue 通常处于status:needs-info等待信息补充或status:needs-design等待架构决策状态——这两种情况应先参与讨论因为决策落地前就动手往往意味着工作被丢弃。AI 辅助贡献允许使用但必须完全拥有提交项目明确允许 AI 辅助贡献但人类贡献者必须理解、审查、验证并全权负责整个提交。打开 PR 前需要逐项确认变更与已批准 Issue 的范围一致逐行检查每一处改动移除编造的、不可验证的或无关的输出找出真正的根因与不变量invariant确认修复解决了根因而非掩盖或转移症状移除重复权限、不必要的抽象与无关复杂度保持修复与问题相称运行适用的测试并如实报告结果能够解释设计与取舍在 PR 中披露实质性的 AI 辅助。披露边界、必填细节、署名规则与评审方期望详见规范的 AI-Assisted Contribution Policy。该政策要点包括实质性 AI 辅助代码、测试、文档、设计、提示词、技能、schema、工作流乃至实质性审查分析必须在 PR 声明中说明工具或模型、辅助的范围、贡献者所做的验证维护者可能要求解释、提示词摘要、来源信息、佐证或额外测试无法解释、验证或辩护的工作会被拒绝AI 工具不得获得人类署名如Co-Authored-By、Reviewed-by、Signed-off-by等可选的Assisted-bytrailer 可以被接受但 PR 声明本身已足够。项目目前通过评审者判断与书面评审决定执行该政策不采用自动 AI 检测或自动披露门禁。标签系统Type / Size / Status / Priority标签系统是 CI 自动检查的数据基础分四类Type 标签应用于 PR必须恰好一个标签描述type:bugBug 修复type:feature新功能或增强type:docs仅文档type:refactor代码重构无行为变化type:chore构建、CI、工具链变更type:breaking-change破坏性变更Size 标签应用于 PR标签描述size:exception维护者批准的例外用于超出 400 变更行评审预算的 PRStatus 标签应用于 Issue标签描述status:needs-review新开启等待维护者评审status:approved批准实现——可以开工status:in-progress正在处理status:blocked被其他 Issue 或外部依赖阻塞status:wont-fix超出范围或不处理Priority 标签标签描述priority:critical阻塞性 Issue、安全漏洞priority:high重要影响大量用户priority:medium正常优先级priority:low锦上添花注意priority表示维护者的排序而非难度——priority:high不代表难priority:low也不代表简单。CI 中对type:*的检查.github/workflows/pr-check.yml 的check-type-labeljob要求 PR恰好拥有一个type:*标签零个或多余一个都会失败。开发环境与本地构建前置条件Go 1.25.10仓库根目录 go.mod 声明go 1.25.10构建工具链需满足该版本约束Docker用于 E2E 测试Git 2.38。克隆与构建git clone https://gitcode.com/gh_mirrors/ge/gentle-ai cd gentle-ai go build -o gentle-ai ./cmd/gentle-ai从源码结构看cmd/gentle-ai/main.go 是入口version变量由 GoReleaser 在构建时通过 ldflags 注入默认为devmain调用internal/app包的app.Run()出错时向 stderr 输出并以退出码 1 结束。本地构建产出的二进制即为./gentle-ai可立即运行./gentle-ai测试体系从单元测试到跨通道电池该项目的测试分四个层次覆盖从纯逻辑到真实宿主环境的完整纵深。单元测试# 全量单测 go test ./... # 指定包 go test ./internal/tui/... # 详细输出 go test -v ./...E2E 测试Docker 多平台E2E 是基于 Docker 的 shell 脚本运行前必须确保 Docker 已启动cd e2e chmod x docker-test.sh ./docker-test.sh⚠️ E2E 测试会拉起容器来模拟真实安装环境可能需要数分钟才能完成。从 e2e/docker-test.sh 的实现看测试按平台矩阵ubuntu / arch / fedora分别对应Dockerfile.ubuntu、Dockerfile.arch、Dockerfile.fedora构建并运行容器默认只跑 Tier 1二进制存在性 --dry-run快速测试可通过环境变量扩展RUN_FULL_E2E1开启 Tier 2 完整安装测试会写文件系统RUN_BACKUP_TESTS1开启 Tier 3 备份/恢复测试容器内部执行的是 e2e/e2e_test.sh。每个平台的构建与运行都被timeout默认 900 秒可用E2E_PLATFORM_TIMEOUT_SECONDS调整兜底防止 CI runner 无限挂起任一平台失败则整体以非零退出码结束。Cross-Lane Battery本地回归网Cross-Lane Battery入口脚本 scripts/cross-lane-battery.sh实现位于 scripts/crosslane/其中包含battery.go、opencode.go、claude.go、codex.go、host.go、hostcodex.go、hostpi.go、hostopencode.go、schema.go、advisory.go等通道是一张刻意不接入 CI的本地回归网——它的可选层级会消耗真实的评审模型调用与真实的宿主会话。它用一个真实的gentle-ai二进制端到端地驱动所有受支持的 agent 宿主评审集成边界。先构建二进制再按成本预算选择层级go build -o /tmp/gentle-ai ./cmd/gentle-ai ./scripts/cross-lane-battery.sh --binary /tmp/gentle-ai [--with-model] [--with-host] [--keep-work]层级标志成本画像覆盖内容Deterministic无始终运行免费且快速真实 OpenCode 传输插件字节通过模拟的 Task hook 表面宿主帧模拟、一条完整的 Claude 通道生命周期加一次中等级候选同意往返、以及每个捕获信封对contracts/review-integration/的 schema 一致性校验Model--with-model真实评审模型运行模型费用额外运行真实编译的 claude-code 评审运行时Host--with-host真实宿主会话加模型费用启动真实宿主应用经编译的 Codex 适配器执行codex exec、已安装的gentle-pi打印模式 Pi 中继、以及沙箱 HOME 中带真实传输插件的无头opencode run会话预期行为每个宿主命令有界宿主命令 12 分钟、非宿主命令 20 分钟挂起的宿主会以有界通道失败呈现而不是拖死整个电池运行结束打印每个检查的 PASS/FAIL/SKIP 表格以及真实模型运行消耗任何失败检查都会使电池以非零退出已知红色检查仍然失败——在缺陷逃逸的精确接缝处变红正是电池在起作用工作根目录在每次退出时都会被清理包括失败时传--keep-work可保留供检查。在合入任何触及评审生命周期表面facade、传输层、契约、宿主适配器的变更前、以及构建了一个打算实际演练的新二进制后运行一次电池。运行电池并报告红色检查本身就是有价值的贡献——用 PASS/FAIL/SKIP 表格和你测试的二进制/提交开一个 Issue。Benchmark 验证bench/ 是独立的 Go module根模块的测试不会验证它。Benchmark 变更需要从bench/目录内运行go build ./... go vet ./... go test ./...独立模块是有意为之基准工具绝不能破坏、拖慢或进入它所测量产品的发布构建。它用--binary接收被测二进制以黑盒子进程方式驱动gentle-ai的评审生命周期从不探测产品内部因此可以同样测量旧版本与当前构建核心语料库确定性且离线绝不调用模型每个 journey 都在全新的临时目录中运行独立HOME、XDG_*、一次性 git 仓库。model-picker轴j97与受损存储崩溃恢复 journeys 使用bench_fixture产品构建标签——仅当运行这些可选轴时才从仓库根目录构建该产品二进制具体驱动命令见 bench/README.md。Benchmark 验证适用于评审生命周期、门禁、恢复、交付、benchmark 实现/语料库/分类器以及 benchmark 声明相关变更。对可测量的产品行为变更使用驱动模式并报告命令、被测二进制或提交、所选子集或轴、以及结果摘要仅在声称可测量的摩擦变化时才做前后对比。无关变更应标记 Benchmark 验证为N/A并简述理由。Windows 已知测试限制部分单元测试需要 Windows 默认受限的 OS 级能力符号链接测试SeCreateSymbolicLinkPrivilege创建符号链接的测试例如internal/components/filemerge中在进程缺少SeCreateSymbolicLinkPrivilegeERROR_PRIVILEGE_NOT_HELDerrno 1314的 Windows 构建上会被自动跳过。这是 Windows 安全策略不是代码缺陷。可选方案启用开发者模式设置 → 系统 → 开发者选项 → 开发者模式为所有进程授予符号链接创建权限无需管理员权限以管理员身份运行以管理员身份打开终端再执行go test ./...通过组策略显式授予本地安全策略 → 用户权限分配 → 创建符号链接。Linux 与 macOS 上这些测试无需额外设置始终运行。提交规范与分支命名Conventional Commits项目采用 [Conventional Commits] 规范。提交信息必须匹配如下模式^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]\))?!?: .格式type(optional-scope)!: description [optional body] [optional footer]允许的类型类型用途feat新功能fixBug 修复docs仅文档refactor代码变更无行为变化chore维护、依赖、工具链style格式化、lint无逻辑变化perf性能改进test增加或更新测试build构建系统或外部依赖ciCI 配置revert回退先前提交示例feat(tui): add progress bar to installation steps fix(agent): correct Claude Code detection on macOS docs: update contributing guide chore(deps): bump bubbletea to v0.26 refactor(pipeline): extract step executor style: fix linter warnings in catalog package perf(system): cache OS detection result test(installer): add coverage for catalog step execution build: update goreleaser config for arm64 ci: split unit and e2e test jobs revert: undo model picker redesign破坏性变更在 type/scope 后加!并在 footer 中写明BREAKING CHANGE:feat(cli)!: rename --config flag to --config-file BREAKING CHANGE: the --config flag has been renamed to --config-file. Update your scripts and aliases accordingly.破坏性变更对应type:breaking-change标签。分支命名分支名必须匹配^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]$规则全小写用连字符、点或下划线作分隔符无空格、无大写描述简短且有含义。示例feat/user-login、fix/crash-on-startup、docs/api-reference、ci/add-e2e-job。PR 规则交付策略、大小预算与自动化检查ODD 变更的交付策略对实质性的 ODD 工作应依据功能任务清单预估将产生的变更行数并从工作单元提交持续跟踪运行计数。当预估值或运行计数在下一次提交前超过约 400 行时选择一个可评审的交付边界。该任务规模启发式不取代下述 PR 大小预算。策略何时使用交付边界会发生什么ask-on-risk默认仅当预估值或运行计数超出预算时才选择拆分询问一次链式策略stacked-to-main或feature-branch-chainauto-chain变更应分片评审询问缺失的链式策略然后记录每个分片的工作单元提交single-pr变更必须原子性落地超预算的 PR 仍需维护者批准size:exceptionexception-ok维护者已批准超大 PR记录已批准的例外不视为开 PR 的许可决策清单一位评审者能否在约 60 分钟内理解PR 是否在 400 变更行以内每个工作单元提交是否同时包含代码、测试与文档任一答案为否选择auto-chain或获取显式size:exception批准。心智模型工作单元提交是砖块链式 PR 是墙体分段。不要让评审者在一次评审中检查整栋建筑。PR 大小预算400 行 / 60 分钟PR 应控制在400 变更行以内additions deletions。这是刻意的认知负载限制一次 PR 应在约60 分钟内可评审完避免将评审者推向疲劳。放不下就拆成链式或堆叠 PR让每次评审保持聚焦。大型生成/供应商/迁移 diff 可使用size:exception标签但仅当维护者认可该大 diff 不可避免时。CI 侧的落实不止一处.github/workflows/pr-check.yml 的check-pr-sizejob 用 GitHub Actions 脚本直接读取 PR 的additions/deletions超过 400 行且无size:exception标签即失败有标签则降级为 warning.github/workflows/pr-size-policy.yml 则通过pull_request_target事件从默认分支稀疏检出可信的策略脚本.github/scripts/check-pr-size.cjs与.github/grandfather-size-exceptions.json读取实时 PR 事实后计算并强制执行策略失败时同样 fail closed。工作单元提交按可交付单元组织提交而不是按文件类型。一个好的提交应包含理解与验证一个行为或工作流所需的代码、测试与文档。偏好feat(auth): validate tokens at login而不是拆成独立的models、services、tests提交保持回滚合理回退一个提交不应移除无关工作当 PR 接近 400 变更行时将工作单元提交提升为链式或堆叠 PR。评审意见评审反馈应当温暖、直接、快速有用。先给出可行动的关键点必要时解释原因避免在给出反馈前复述整个 PR。开 PR 前检查清单有已批准 Issue 的链接Closes #N、Fixes #N、Resolves #N或非关闭式Refs #NPR 在 400 变更行以内或维护者批准了size:exception提交按可交付工作单元组织全部单元测试通过go test ./...E2E 测试通过cd e2e ./docker-test.shBenchmark 验证已完成或本次变更不适用于 benchmark在测试计划中说明原因提交符合 Conventional Commits 格式代码已自我评审理解并对完整提交负责且在 PR 中披露了实质性 AI 辅助PR 标题与提交信息一样使用 Conventional Commits 格式feat(tui): add keyboard shortcut help overlay fix(agent): handle missing HOME env var gracefully自动化 PR 检查所有 PR 都会经过自动化检查全部通过才能合入检查验证内容Check PR Cognitive LoadPR 保持在 400 变更行内additions deletions除非有size:exception标签Check Issue ReferencePR 正文包含可见、格式正确的基仓库Closes/Fixes/Resolves #N或非关闭式Refs #N畸形、跨仓库、以及对同一 Issue 混用关闭/非关闭引用都会失败Check Issue Has status:approved被链接 Issue 在规范的 Issue 创建工作流契约下具有status:approvedCheck PR Has type:Label*恰好应用一个type:*标签Unit Testsgo test ./...通过E2E Testscd e2e ./docker-test.sh通过在 .github/workflows/pr-check.yml 中可以看到这些检查的实际实现check-issue-reference直接解析事件负载中的 PR 正文刻意不使用重新拉取的 body因为 CodeRabbit 等工具会在事件触发后改写 PR 描述重新拉取将导致每次 PR 都 fail closed解析器错误一律 fail closedcheck-issue-approved复用前者的解析输出通过 GitHub API 读取 Issue 标签status:approved缺失即失败并提示在没有当前直接指令与目标主机能力授予精确动作的情况下评论并等待。关联你的 IssuePR 正文中包含以下任一形式Closes #42 Fixes #42 Resolves #42 Refs #42Closes/Fixes/Resolves在合入时关闭 Issue非关闭式的已批准 Issue 链接使用Refs #N。位于 HTML 注释内的引用、畸形引用、跨仓库引用以及对同一 Issue 同时使用关闭与非关闭形式都会导致 CI 失败。行为准则与沟通渠道保持尊重大家是一起建设。评论代码不要评论人评审中保持建设性欢迎新人违反者可能被移出项目。关于提问与一般性讨论请使用项目的 Discussions 板块而不是 Issue——Issue 留给明确的缺陷与功能请求。若你的变更触及评审、交付或 RDD 行为动手前建议先阅读 Organic RDD 架构候选如何作为证据被评审而交付始终遵循普通仓库策略、评审权限威胁模型权限存储防御什么、刻意不防御什么与 有机实现路由评审运行前工作如何被路由。RDD 即Receipt-Driven Development其评审证据绝不授权 commit、push、PR、release 或 archive——评审与普通仓库交付策略是分离的。赞分享【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载相关推荐Taichi 贡献指南全解从提 Issue 到合入 PR 的完整协作规范Taichi 贡献指南全解从提 Issue 到合入 PR 的完整协作规范 本文以 TaichiPython 高性能 GPU 编程框架官方贡献指南为主线系编程语言编译器高性能计算Relax CMS 贡献指南从 Issue 提交到 PR 合入的完整开发协作规范Relax CMS 贡献指南从 Issue 提交到 PR 合入的完整开发协作规范 本指南以 Relax基于 React、Redux 与 GraphQL 的新后端前端CKEditor 5 贡献指南从 Issue 到 PR 的完整协作流程与工程规范CKEditor 5 贡献指南从 Issue 到 PR 的完整协作流程与工程规范 CKEditor 5 是一个模块化架构的开源富文本编辑器框架其代码库以单一前端富文本UI组件上一篇三小时构建企业级后台管理系统的终极方案ThinkAdmin实战指南下一篇Text-to-CAD智能设计工具用文字生成专业CAD图纸的革命性技术创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gentle-AI 贡献指南：从 Issue 审批到 PR 合入的完整工程协作规范
【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载Gentle-AIgentle-ai是一个用 Go 编写的 CLI/TUI 生态配置器用于统一配置 Claude Code、Cursor、OpenCode、Codex、Pi 等 AI 编码 Agent。本文基于仓库根目录的 CONTRIBUTING.md 展开完整梳理该项目无 Issue 不 PR的协作流程、AI 辅助贡献政策、标签体系、本地开发与多级测试矩阵单元测试、Docker E2E、Cross-Lane Battery、Benchmark、Conventional Commits 提交规范以及400 行 / 60 分钟的 PR 认知负载预算。读完本文你将掌握如何在该仓库中从零发起一个会被 CI 放行、并最终合入主线的贡献先开被批准的 Issue再写工作单元提交最后以正确格式的 PR 完成交付。Issue-First无 Issue 的 PR 一律拒绝项目采用严格的问题先行issue-first工作流核心原则只有一句No PR without an issue. No exceptions.标准流程分四步开 Issue使用对应模板提交 [Bug Report] 或 [Feature Request]在仓库 Issues 页选择对应模板。等待批准只有 Issue 被贴上status:approved标签后工作才允许开始。根据规范中的表述在没有当前直接指令与目标主机能力授予精确动作的情况下应在评论中等待而不是直接开工。在 Issue 上留言声明你正在处理它让其他人知晓避免重复劳动。打开 PR 并关联已批准的 Issue。未关联已批准 Issue 的 PR 会被 CI自动拒绝——这不是人工抽查而是流水线级的强制约束。PR 验证工作流的实现位于 .github/workflows/pr-check.yml其中check-issue-reference与check-issue-approved两个 job 分别校验 PR 正文是否包含格式正确的 Issue 引用、以及被引用 Issue 是否携带status:approved标签任何一项不满足都会直接core.setFailedPR 无法通过。想找活干从 Community Roadmap 出发。所有带up-for-grabs标签的 Issue 都满足三个条件有明确范围问题被陈述、失败可复现或行为被定义、指明了代码树中的位置、已获批准携带status:approved可以开 PR、无人认领。评论一句我来做即可认领。而没有该标签的 Issue 通常处于status:needs-info等待信息补充或status:needs-design等待架构决策状态——这两种情况应先参与讨论因为决策落地前就动手往往意味着工作被丢弃。AI 辅助贡献允许使用但必须完全拥有提交项目明确允许 AI 辅助贡献但人类贡献者必须理解、审查、验证并全权负责整个提交。打开 PR 前需要逐项确认变更与已批准 Issue 的范围一致逐行检查每一处改动移除编造的、不可验证的或无关的输出找出真正的根因与不变量invariant确认修复解决了根因而非掩盖或转移症状移除重复权限、不必要的抽象与无关复杂度保持修复与问题相称运行适用的测试并如实报告结果能够解释设计与取舍在 PR 中披露实质性的 AI 辅助。披露边界、必填细节、署名规则与评审方期望详见规范的 AI-Assisted Contribution Policy。该政策要点包括实质性 AI 辅助代码、测试、文档、设计、提示词、技能、schema、工作流乃至实质性审查分析必须在 PR 声明中说明工具或模型、辅助的范围、贡献者所做的验证维护者可能要求解释、提示词摘要、来源信息、佐证或额外测试无法解释、验证或辩护的工作会被拒绝AI 工具不得获得人类署名如Co-Authored-By、Reviewed-by、Signed-off-by等可选的Assisted-bytrailer 可以被接受但 PR 声明本身已足够。项目目前通过评审者判断与书面评审决定执行该政策不采用自动 AI 检测或自动披露门禁。标签系统Type / Size / Status / Priority标签系统是 CI 自动检查的数据基础分四类Type 标签应用于 PR必须恰好一个标签描述type:bugBug 修复type:feature新功能或增强type:docs仅文档type:refactor代码重构无行为变化type:chore构建、CI、工具链变更type:breaking-change破坏性变更Size 标签应用于 PR标签描述size:exception维护者批准的例外用于超出 400 变更行评审预算的 PRStatus 标签应用于 Issue标签描述status:needs-review新开启等待维护者评审status:approved批准实现——可以开工status:in-progress正在处理status:blocked被其他 Issue 或外部依赖阻塞status:wont-fix超出范围或不处理Priority 标签标签描述priority:critical阻塞性 Issue、安全漏洞priority:high重要影响大量用户priority:medium正常优先级priority:low锦上添花注意priority表示维护者的排序而非难度——priority:high不代表难priority:low也不代表简单。CI 中对type:*的检查.github/workflows/pr-check.yml 的check-type-labeljob要求 PR恰好拥有一个type:*标签零个或多余一个都会失败。开发环境与本地构建前置条件Go 1.25.10仓库根目录 go.mod 声明go 1.25.10构建工具链需满足该版本约束Docker用于 E2E 测试Git 2.38。克隆与构建git clone https://gitcode.com/gh_mirrors/ge/gentle-ai cd gentle-ai go build -o gentle-ai ./cmd/gentle-ai从源码结构看cmd/gentle-ai/main.go 是入口version变量由 GoReleaser 在构建时通过 ldflags 注入默认为devmain调用internal/app包的app.Run()出错时向 stderr 输出并以退出码 1 结束。本地构建产出的二进制即为./gentle-ai可立即运行./gentle-ai测试体系从单元测试到跨通道电池该项目的测试分四个层次覆盖从纯逻辑到真实宿主环境的完整纵深。单元测试# 全量单测 go test ./... # 指定包 go test ./internal/tui/... # 详细输出 go test -v ./...E2E 测试Docker 多平台E2E 是基于 Docker 的 shell 脚本运行前必须确保 Docker 已启动cd e2e chmod x docker-test.sh ./docker-test.sh⚠️ E2E 测试会拉起容器来模拟真实安装环境可能需要数分钟才能完成。从 e2e/docker-test.sh 的实现看测试按平台矩阵ubuntu / arch / fedora分别对应Dockerfile.ubuntu、Dockerfile.arch、Dockerfile.fedora构建并运行容器默认只跑 Tier 1二进制存在性 --dry-run快速测试可通过环境变量扩展RUN_FULL_E2E1开启 Tier 2 完整安装测试会写文件系统RUN_BACKUP_TESTS1开启 Tier 3 备份/恢复测试容器内部执行的是 e2e/e2e_test.sh。每个平台的构建与运行都被timeout默认 900 秒可用E2E_PLATFORM_TIMEOUT_SECONDS调整兜底防止 CI runner 无限挂起任一平台失败则整体以非零退出码结束。Cross-Lane Battery本地回归网Cross-Lane Battery入口脚本 scripts/cross-lane-battery.sh实现位于 scripts/crosslane/其中包含battery.go、opencode.go、claude.go、codex.go、host.go、hostcodex.go、hostpi.go、hostopencode.go、schema.go、advisory.go等通道是一张刻意不接入 CI的本地回归网——它的可选层级会消耗真实的评审模型调用与真实的宿主会话。它用一个真实的gentle-ai二进制端到端地驱动所有受支持的 agent 宿主评审集成边界。先构建二进制再按成本预算选择层级go build -o /tmp/gentle-ai ./cmd/gentle-ai ./scripts/cross-lane-battery.sh --binary /tmp/gentle-ai [--with-model] [--with-host] [--keep-work]层级标志成本画像覆盖内容Deterministic无始终运行免费且快速真实 OpenCode 传输插件字节通过模拟的 Task hook 表面宿主帧模拟、一条完整的 Claude 通道生命周期加一次中等级候选同意往返、以及每个捕获信封对contracts/review-integration/的 schema 一致性校验Model--with-model真实评审模型运行模型费用额外运行真实编译的 claude-code 评审运行时Host--with-host真实宿主会话加模型费用启动真实宿主应用经编译的 Codex 适配器执行codex exec、已安装的gentle-pi打印模式 Pi 中继、以及沙箱 HOME 中带真实传输插件的无头opencode run会话预期行为每个宿主命令有界宿主命令 12 分钟、非宿主命令 20 分钟挂起的宿主会以有界通道失败呈现而不是拖死整个电池运行结束打印每个检查的 PASS/FAIL/SKIP 表格以及真实模型运行消耗任何失败检查都会使电池以非零退出已知红色检查仍然失败——在缺陷逃逸的精确接缝处变红正是电池在起作用工作根目录在每次退出时都会被清理包括失败时传--keep-work可保留供检查。在合入任何触及评审生命周期表面facade、传输层、契约、宿主适配器的变更前、以及构建了一个打算实际演练的新二进制后运行一次电池。运行电池并报告红色检查本身就是有价值的贡献——用 PASS/FAIL/SKIP 表格和你测试的二进制/提交开一个 Issue。Benchmark 验证bench/ 是独立的 Go module根模块的测试不会验证它。Benchmark 变更需要从bench/目录内运行go build ./... go vet ./... go test ./...独立模块是有意为之基准工具绝不能破坏、拖慢或进入它所测量产品的发布构建。它用--binary接收被测二进制以黑盒子进程方式驱动gentle-ai的评审生命周期从不探测产品内部因此可以同样测量旧版本与当前构建核心语料库确定性且离线绝不调用模型每个 journey 都在全新的临时目录中运行独立HOME、XDG_*、一次性 git 仓库。model-picker轴j97与受损存储崩溃恢复 journeys 使用bench_fixture产品构建标签——仅当运行这些可选轴时才从仓库根目录构建该产品二进制具体驱动命令见 bench/README.md。Benchmark 验证适用于评审生命周期、门禁、恢复、交付、benchmark 实现/语料库/分类器以及 benchmark 声明相关变更。对可测量的产品行为变更使用驱动模式并报告命令、被测二进制或提交、所选子集或轴、以及结果摘要仅在声称可测量的摩擦变化时才做前后对比。无关变更应标记 Benchmark 验证为N/A并简述理由。Windows 已知测试限制部分单元测试需要 Windows 默认受限的 OS 级能力符号链接测试SeCreateSymbolicLinkPrivilege创建符号链接的测试例如internal/components/filemerge中在进程缺少SeCreateSymbolicLinkPrivilegeERROR_PRIVILEGE_NOT_HELDerrno 1314的 Windows 构建上会被自动跳过。这是 Windows 安全策略不是代码缺陷。可选方案启用开发者模式设置 → 系统 → 开发者选项 → 开发者模式为所有进程授予符号链接创建权限无需管理员权限以管理员身份运行以管理员身份打开终端再执行go test ./...通过组策略显式授予本地安全策略 → 用户权限分配 → 创建符号链接。Linux 与 macOS 上这些测试无需额外设置始终运行。提交规范与分支命名Conventional Commits项目采用 [Conventional Commits] 规范。提交信息必须匹配如下模式^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]\))?!?: .格式type(optional-scope)!: description [optional body] [optional footer]允许的类型类型用途feat新功能fixBug 修复docs仅文档refactor代码变更无行为变化chore维护、依赖、工具链style格式化、lint无逻辑变化perf性能改进test增加或更新测试build构建系统或外部依赖ciCI 配置revert回退先前提交示例feat(tui): add progress bar to installation steps fix(agent): correct Claude Code detection on macOS docs: update contributing guide chore(deps): bump bubbletea to v0.26 refactor(pipeline): extract step executor style: fix linter warnings in catalog package perf(system): cache OS detection result test(installer): add coverage for catalog step execution build: update goreleaser config for arm64 ci: split unit and e2e test jobs revert: undo model picker redesign破坏性变更在 type/scope 后加!并在 footer 中写明BREAKING CHANGE:feat(cli)!: rename --config flag to --config-file BREAKING CHANGE: the --config flag has been renamed to --config-file. Update your scripts and aliases accordingly.破坏性变更对应type:breaking-change标签。分支命名分支名必须匹配^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]$规则全小写用连字符、点或下划线作分隔符无空格、无大写描述简短且有含义。示例feat/user-login、fix/crash-on-startup、docs/api-reference、ci/add-e2e-job。PR 规则交付策略、大小预算与自动化检查ODD 变更的交付策略对实质性的 ODD 工作应依据功能任务清单预估将产生的变更行数并从工作单元提交持续跟踪运行计数。当预估值或运行计数在下一次提交前超过约 400 行时选择一个可评审的交付边界。该任务规模启发式不取代下述 PR 大小预算。策略何时使用交付边界会发生什么ask-on-risk默认仅当预估值或运行计数超出预算时才选择拆分询问一次链式策略stacked-to-main或feature-branch-chainauto-chain变更应分片评审询问缺失的链式策略然后记录每个分片的工作单元提交single-pr变更必须原子性落地超预算的 PR 仍需维护者批准size:exceptionexception-ok维护者已批准超大 PR记录已批准的例外不视为开 PR 的许可决策清单一位评审者能否在约 60 分钟内理解PR 是否在 400 变更行以内每个工作单元提交是否同时包含代码、测试与文档任一答案为否选择auto-chain或获取显式size:exception批准。心智模型工作单元提交是砖块链式 PR 是墙体分段。不要让评审者在一次评审中检查整栋建筑。PR 大小预算400 行 / 60 分钟PR 应控制在400 变更行以内additions deletions。这是刻意的认知负载限制一次 PR 应在约60 分钟内可评审完避免将评审者推向疲劳。放不下就拆成链式或堆叠 PR让每次评审保持聚焦。大型生成/供应商/迁移 diff 可使用size:exception标签但仅当维护者认可该大 diff 不可避免时。CI 侧的落实不止一处.github/workflows/pr-check.yml 的check-pr-sizejob 用 GitHub Actions 脚本直接读取 PR 的additions/deletions超过 400 行且无size:exception标签即失败有标签则降级为 warning.github/workflows/pr-size-policy.yml 则通过pull_request_target事件从默认分支稀疏检出可信的策略脚本.github/scripts/check-pr-size.cjs与.github/grandfather-size-exceptions.json读取实时 PR 事实后计算并强制执行策略失败时同样 fail closed。工作单元提交按可交付单元组织提交而不是按文件类型。一个好的提交应包含理解与验证一个行为或工作流所需的代码、测试与文档。偏好feat(auth): validate tokens at login而不是拆成独立的models、services、tests提交保持回滚合理回退一个提交不应移除无关工作当 PR 接近 400 变更行时将工作单元提交提升为链式或堆叠 PR。评审意见评审反馈应当温暖、直接、快速有用。先给出可行动的关键点必要时解释原因避免在给出反馈前复述整个 PR。开 PR 前检查清单有已批准 Issue 的链接Closes #N、Fixes #N、Resolves #N或非关闭式Refs #NPR 在 400 变更行以内或维护者批准了size:exception提交按可交付工作单元组织全部单元测试通过go test ./...E2E 测试通过cd e2e ./docker-test.shBenchmark 验证已完成或本次变更不适用于 benchmark在测试计划中说明原因提交符合 Conventional Commits 格式代码已自我评审理解并对完整提交负责且在 PR 中披露了实质性 AI 辅助PR 标题与提交信息一样使用 Conventional Commits 格式feat(tui): add keyboard shortcut help overlay fix(agent): handle missing HOME env var gracefully自动化 PR 检查所有 PR 都会经过自动化检查全部通过才能合入检查验证内容Check PR Cognitive LoadPR 保持在 400 变更行内additions deletions除非有size:exception标签Check Issue ReferencePR 正文包含可见、格式正确的基仓库Closes/Fixes/Resolves #N或非关闭式Refs #N畸形、跨仓库、以及对同一 Issue 混用关闭/非关闭引用都会失败Check Issue Has status:approved被链接 Issue 在规范的 Issue 创建工作流契约下具有status:approvedCheck PR Has type:Label*恰好应用一个type:*标签Unit Testsgo test ./...通过E2E Testscd e2e ./docker-test.sh通过在 .github/workflows/pr-check.yml 中可以看到这些检查的实际实现check-issue-reference直接解析事件负载中的 PR 正文刻意不使用重新拉取的 body因为 CodeRabbit 等工具会在事件触发后改写 PR 描述重新拉取将导致每次 PR 都 fail closed解析器错误一律 fail closedcheck-issue-approved复用前者的解析输出通过 GitHub API 读取 Issue 标签status:approved缺失即失败并提示在没有当前直接指令与目标主机能力授予精确动作的情况下评论并等待。关联你的 IssuePR 正文中包含以下任一形式Closes #42 Fixes #42 Resolves #42 Refs #42Closes/Fixes/Resolves在合入时关闭 Issue非关闭式的已批准 Issue 链接使用Refs #N。位于 HTML 注释内的引用、畸形引用、跨仓库引用以及对同一 Issue 同时使用关闭与非关闭形式都会导致 CI 失败。行为准则与沟通渠道保持尊重大家是一起建设。评论代码不要评论人评审中保持建设性欢迎新人违反者可能被移出项目。关于提问与一般性讨论请使用项目的 Discussions 板块而不是 Issue——Issue 留给明确的缺陷与功能请求。若你的变更触及评审、交付或 RDD 行为动手前建议先阅读 Organic RDD 架构候选如何作为证据被评审而交付始终遵循普通仓库策略、评审权限威胁模型权限存储防御什么、刻意不防御什么与 有机实现路由评审运行前工作如何被路由。RDD 即Receipt-Driven Development其评审证据绝不授权 commit、push、PR、release 或 archive——评审与普通仓库交付策略是分离的。赞分享【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载相关推荐Taichi 贡献指南全解从提 Issue 到合入 PR 的完整协作规范Taichi 贡献指南全解从提 Issue 到合入 PR 的完整协作规范 本文以 TaichiPython 高性能 GPU 编程框架官方贡献指南为主线系编程语言编译器高性能计算Relax CMS 贡献指南从 Issue 提交到 PR 合入的完整开发协作规范Relax CMS 贡献指南从 Issue 提交到 PR 合入的完整开发协作规范 本指南以 Relax基于 React、Redux 与 GraphQL 的新后端前端CKEditor 5 贡献指南从 Issue 到 PR 的完整协作流程与工程规范CKEditor 5 贡献指南从 Issue 到 PR 的完整协作流程与工程规范 CKEditor 5 是一个模块化架构的开源富文本编辑器框架其代码库以单一前端富文本UI组件上一篇三小时构建企业级后台管理系统的终极方案ThinkAdmin实战指南下一篇Text-to-CAD智能设计工具用文字生成专业CAD图纸的革命性技术创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考