Upsonic Bug-Fix 工作流为 AI 协作者设计的四阶段缺陷修复规范【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant本文是 Upsonicsrc/upsonic/框架内部面向 AI 助手编写的缺陷修复操作指南定义了修复 bug 时必须依次通过的四个阶段——复现Reproduce→ 诊断Diagnose→ 修复Fix→ 验证Verify以及每个阶段的进入门禁Entry Gate、操作要点、退出门禁Exit Gate和跨阶段硬门禁Hard Gates总表。读完本文你将掌握一套可执行的缺陷修复流程如何把偶发故障变成确定性复现用例、如何用一句话定位根因并审计关联代码路径、如何交付最小修复与回归测试以及在宣称已修复之前必须逐项勾选的验证清单。1. 文档定位与适用范围本文是 feature.md新增功能工作流、coding-standards.md代码书写规范、commit.md提交规范三份指南的姊妹文档。它解决的问题形状与功能开发不同复现 → 根因 → 最小修复 → 回归测试涉及面更小因此本文使用与feature.md相同的 RFC 2119 词汇表和门禁结构但共享的横切关注点Aspect直接交叉引用feature.md §4不再重复罗列。1.1 目标读者面向在src/upsonic/中修复已报告 bug 的 AI 助手。人类贡献者同样可以受益但文档按 AI 消费方式编写规定式prescriptive、强门禁gated、并交叉引用仓库中的真实文件。1.2 适用场景In Scope出现以下任一情况时应使用本指南存在已报告的 bug、失败的测试、traceback、回归或意外行为行为与 docstring、类型注解或已声明的契约相矛盾崩溃、挂起、死锁或竞态条件静默错误输出计算值不正确而不仅是报错。1.3 不适用场景Out of Scope我想加个功能让它换个方式工作→ 使用 feature.md代码没问题只是想整理一下→ 使用 refactor.md有意改变已文档化的行为→ 属于破坏性变更使用 feature.md。1.4 边界情况判定修复需要新增一个类型化异常写入exceptions.py仍属于 bug-fix。新增异常是最小修复的一部分随同一变更一起提交。仓库中异常体系的根类是 src/upsonic/exceptions.py 中的UpsonicError所有自定义异常ConfigurationError、ProviderError、RateLimitError、AuthenticationError、ExecutionTimeoutError等都继承自它保证用户可以用一个类捕获全部框架错误——这与 coding-standards.md §9.1 的单一根异常原则一致修复过程中暴露出相邻的死代码或混乱结构立即停止。bug-fix 必须保持狭窄将清理项记入后续的独立重构走 refactor.md严禁捆绑进本次变更bug 无法复现不要提交投机性修复停下来向用户索取更多上下文。2. 如何使用本指南指南由三部分组成§3 四阶段主流程复现 → 诊断 → 修复 → 验证是整份文档的脊柱必须按顺序依次通过全部四个阶段。每个阶段包含进入门禁、操作要点、指向feature.md §4的 Aspect 引用、退出门禁§4 硬门禁总表每个阶段边界处的预检清单§5 反模式清单AI 在修 bug 时最常见的错误。2.1 RFC 2119 关键词MUST、MUST NOT、SHOULD、SHOULD NOT、MAY均采用 RFC 2119 语义。任何标记为MUST的项都是硬门禁违反它需要获得用户的明确批准。2.2 Aspect 处理规则阶段中引用的每一个 Aspect必须被处理。如果某个 Aspect 不适用必须用一句话显式说明原因例如Observability CostN/A本次修复不调用模型、不新增任何 I/O。静默跳过是禁止的。3. 四阶段工作流详解Phase 1 — Reproduce复现进入门禁存在 bug 报告、失败的测试、traceback或观察到的契约违背。操作要点把报告读两遍。区分症状用户看到的现象与底层行为构建一个确定性复现。记录精确的命令、输入和环境复现必须是一个可运行的测试或脚本。我偶尔能看到不算复现如果无法复现必须停下来向用户索取更多上下文禁止提交投机性修复。Aspect 引用Tests— 见 feature.md §4.5。Phase 1 的复现用例将在 Phase 3 转变为回归测试。退出门禁存在一个与用户描述以相同方式失败的可运行命令或测试失败在多次运行间是确定性的。仓库佐证仓库的测试体系按功能镜像src/目录划分——纯逻辑测试放 tests/unit_tests/不依赖网络、磁盘、外部服务I/O 与外部服务相关放 tests/smoke_tests/跨子系统行为放 tests/integration_tests/。一个合格的复现用例应当落在与其触碰面匹配的层级后续直接转成回归测试。Phase 2 — Diagnose诊断进入门禁Phase 1 退出门禁已通过。操作要点通过阅读真实代码路径从症状追踪到根因不要凭记忆做模式匹配用一句话陈述根因。如果你做不到说明诊断尚未完成审计与根因相关的其他代码路径。同一模块形状相似的其他模块别处是否也有同样的except Exception:吞噬同样的 off-by-one 模式只关闭多站点 bug 中一个站点的修复是部分修复如果 bug 横跨多个子系统例如agent/tools/必须在提出修复方案前逐一识别每个受影响的子系统对不明显的 bug可使用superpowers:systematic-debugging技能。Aspect 引用Architecture Subsystem Fit— 见 feature.md §4.1。识别根因归属哪个子系统Reliability Safety— 见 feature.md §4.3。类型化异常、错误语义、禁止裸except。退出门禁根因已用一句话陈述相关代码路径的检查清单已列出——要么确认干净要么已为其各自划定了修复范围。Phase 3 — Fix修复进入门禁Phase 2 退出门禁已通过。操作要点编写针对根因的最小修复diff 应当很小把 Phase 1 的复现用例转成回归测试在同一变更中提交测试放置位置纯逻辑 bug →tests/unit_tests/subsystem/I/O / 外部服务 bug →tests/smoke_tests/subsystem/如果修复需要新的类型化异常在同一变更中写入 src/upsonic/exceptions.py同步 异步对等如果 bug 同时存在于name()和aname()必须在同一变更中同时修复见 feature.md §4.2。这是本仓库async-first工程文化的硬性要求——coding-standards.md §5.2 明确规定公开 I/O 方法必须成对提供同步版本与a前缀异步版本异步版本是唯一事实来源同步版本只是薄包装禁止范围蔓延发现的死代码、怪异的命名、过时的注释记下来留给后续 refactor.md 处理不要包含在本次变更中新增关键字参数必须默认保持原有行为。公开 API 面是契约。Aspect 引用API Discipline— 见 feature.md §4.2。同步/异步对等禁止破坏性默认参数Reliability Safety— 见 feature.md §4.3。类型化异常禁止except: passTests— 见 feature.md §4.5。回归测试的放置位置与层级。退出门禁回归测试在修复前代码上失败回归测试在修复后代码上通过触碰代码通过mypy --strictdiff 中无无关变更。仓库佐证异常体系的实际形态可在 src/upsonic/exceptions.py 中直接验证——根类UpsonicError之下是按语义划分的类型化层级如ProviderError之下的ModelNotFoundError、ConfigurationError、RunCancelledException、ExecutionTimeoutError等这正是捕获类型化、重新抛出类型化这一规则落地的载体。项目使用uv管理依赖见 pyproject.toml测试运行器配置在 pytest.iniasyncio_mode strict测试发现规则为test_*.py/Test*/test_*。Phase 4 — Verify验证进入门禁Phase 3 退出门禁已通过。操作要点运行完整单元测试套件uv run --all-extras pytest tests/unit_tests -v如果触碰了 I/O运行make smoke_tests运行pre-commit run --all-files对src/运行mypy --strict手动追踪原始失败路径穿过新代码——确认 bug 已消失手动追踪 Phase 2 中审计过的一条相关代码路径——确认它仍然工作bug-fix 对用户可见向用户标注 CHANGELOG / 版本号提升的影响如果触碰了任何遥测路径确认UPSONIC_TELEMETRYFalse仍然被尊重。Aspect 引用Tests— 见 feature.md §4.5Observability Cost— 见 feature.md §4.4。UPSONIC_TELEMETRYFalse被尊重错误消息中不含 PII。退出门禁§4 硬门禁总表中的每一项都通过。硬门禁在门禁清空之前MUST NOT称该工作已修复已完成或已就绪。原始测试通过了远远不够门禁是 §4 中的每一项都通过。仓库佐证make smoke_tests目标的实际行为可查 Makefile——它会先执行deps_smokeuv sync --extra storage --extra faiss安装可选依赖并自动拉起 tests/smoke_tests/docker-compose.yml 中的 Docker 服务用于存储相关测试再运行uv run pytest tests/smoke_tests -v排除 HITL 相关交互用例。也就是说I/O 被触碰后跑 smoke tests并非空话而是带真实基础设施的端到端验证。遥测开关UPSONIC_TELEMETRY的实现见 src/upsonic/utils/logging_config.py——enable_telemetry()读取该环境变量作为 Sentry DSN为空或为 false 时禁用遥测因此任何新增遥测钩子都必须先检查该标志再上报。4. 硬门禁总表Hard Gates Summary这是每个阶段边界的预检清单以下各项在没有用户明确批准的情况下不可协商─── 离开 REPRODUCE 阶段之前 ───────────────────────────── [ ] 存在确定性复现可运行命令或测试 [ ] 复现的失败模式与报告一致 ─── 离开 DIAGNOSE 阶段之前 ───────────────────────────── [ ] 根因已用一句话陈述 [ ] 相关代码路径已审计要么干净要么已划定修复范围 [ ] 没有投机性的我觉得是因为……——有实际证据 ─── 离开 FIX 阶段之前 ────────────────────────────────── [ ] diff 最小——无无关变更 [ ] 已添加回归测试如适用则同步和异步都要 [ ] 使用类型化异常无裸 except [ ] 触碰代码通过 mypy --strict [ ] 无新增关键字参数而不带保持行为的默认值 ─── 宣称 bug-fix DONE 之前 ───────────────────────────── [ ] 回归测试在修复前代码上失败、在修复后通过 [ ] uv run --all-extras pytest tests/unit_tests 通过 [ ] make smoke_tests 通过如触碰 I/O [ ] pre-commit run --all-files 干净 [ ] mypy --strict 干净 [ ] 手动追踪原始失败路径确认修复生效 [ ] 手动追踪一条相关路径确认无回归 [ ] 已标注 CHANGELOG / 版本号提升影响 [ ] 准备移交给提交工作流commit.md如果任何一项无法勾选bug-fix 就不算完成。允许将某条目标为 N/A但必须附带一句话理由。仓库佐证清单中的命令与仓库现状一一对应——uv run --all-extras pytest tests/unit_tests -v依赖uv包管理器pyproject.toml 声明了全部可选依赖组make smoke_tests由 Makefile 定义pre-commit与mypy --strict的配置目标在 coding-standards.md §2.1 中说明ruff、mypy、行尾修复器、尾随空白检查CI 重跑相同钩子。5. 反模式清单Anti-Patterns这是在本框架修 bug 时最常见的 AI 错误每个模式最终都会引入一个新 bug请识别其形状并避免修症状不修根因。包一层try/except或加一个None检查却不追究None为什么出现。你刚加的except吞噬就是下一个 bugAspect: §4.3没有复现只有猜测。把报告模式匹配到某个已知 bug 形状就直接提交修复从不运行失败用例。绝大多数没有复现的修复修不掉 bugAspect: §4.5把重构捆绑进修复。顺手清理了周围代码会让 diff 大到无法审查修复被淹没在其中。保持 bug-fix 狭窄重构走 refactor.mdAspect: §4.2没有修复也能通过的测试。无论是否应用修复都通过的回归测试不是回归测试。先在未修复代码上运行确认它失败Aspect: §4.5只修复多站点 bug 中的一个站点。三个文件里都有裸 except只修一个等于发布部分修复并假装问题已关闭。Phase 2 就要审计相关路径Aspect: §4.1忘记异步孪生。bug 同时存在于read和aread修复却只落在read。同步 异步对等同样适用于修复Aspect: §4.2捕获异常只为吞噬。修复写成捕获并记录会丢失信息并制造下一个 bug。捕获类型化、重新抛出类型化Aspect: §4.3bug-fix 静默改变公开 API。修复引入带非保持默认值的新关键字参数现有调用方全部被破坏。公开面是契约默认值必须保持旧行为Aspect: §4.2。6. 快速地图Quick MapPhase 1: Reproduce — 确定性失败用例没有它就没有修复 Phase 2: Diagnose — 一句话根因审计相关路径 Phase 3: Fix — 最小变更 回归测试 同步/异步对等 Phase 4: Verify — 测试、类型检查、手动追踪失败路径与相关路径 然后: commit.md — 提出提交消息等待批准提交在任何节点感到不确定时重读对应阶段章节以及 feature.md §4 中被交叉引用的 Aspect 规则。§4 的硬门禁总表是整份文档最重要的一页。7. 收尾移交给提交工作流Phase 4 退出门禁清空后工作进入 commit.md 定义的提交流程。需要特别强调的是本仓库的硬规则——未经批准绝不提交不得运行git commit、git push或任何改写历史的命令reset --hard、rebase、amend、force-push直到人类审阅 diff 并明确同意。提交消息遵循type(scope): subject格式bug-fix 对应的 type 是fix主题行使用祈使句、小写、≤ 72 字符正文仅在需要解释为什么时编写并在 72 字符处换行。bug-fix 属于用户可见变更若修复值得记录按仓库惯例以chore: New Version X.Y.Z类型的提交触发版本提升并在 CHANGELOG.md 的 Fixed 分组下补一条记录。至此从一份 bug 报告到一次可审查、可回滚、带回归测试的最小修复整个闭环全部打通。【免费下载链接】gpt-computer-assistantBuild autonomous AI agents in Python.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-computer-assistant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考