PentestGPT 重构候选清单实战在 TDD 循环中识别坏味道并安全重构【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT在 .agents/skills/tdd/SKILL.md 定义的红-绿-重构Red-Green-Refactor工作流中重构阶段的质量直接决定测试是否真正成为行为的守护者而不是被实现细节绑架的脆性文档。本文以 .agents/skills/tdd/refactoring.md 中的重构候选清单为核心骨架逐条拆解六类最常见的代码坏味道及其对应重构手法并借助 PentestGPT 仓库中pentestgpt_agent模块的真实源码与测试依赖注入、深模块设计、面向行为的集成式测试、产物审计作为可验证的落地佐证。读完本文你将掌握一套可直接执行的重构决策框架什么时候动手、对什么动手、如何用测试兜底、以及如何在像 PentestGPT 这样具备持久化状态与外部 LLM 边界的复杂系统中安全地推进重构。一、先回到上下文重构在整个 TDD 循环中的位置.agents/skills/tdd/refactoring.md的第一句话是 After TDD cycle, look for:——重构候选的排查永远发生在 TDD 循环之后。这背后是一条硬性纪律在 SKILL.md 中被强调为Never refactor while RED.Get to GREEN first.也就是说重构只允许在测试全部通过GREEN的状态下进行。原因很朴素测试是重构的安全网。如果代码处于 RED 状态测试失败的原因可能是行为尚未实现而非重构破坏了行为此时任何重构都会让诊断变得不可信。重构阶段的完整动作清单来自 SKILL.md 第 4 步包括Extract duplication抽取重复代码Deepen modules加深模块把复杂性藏到简单接口后面Apply SOLID principles where natural在自然处应用 SOLID 原则Consider what new code reveals about existing code思考新代码揭示了既有代码的什么问题Run tests after each refactor step每步重构后都要跑测试最后一条每步重构后跑测试是重构得以小步快跑的前提——每次只做一个原子变更跑一次测试确认行为没有变化再进入下一步。二、六类重构候选逐一拆解.agents/skills/tdd/refactoring.md全文精炼地给出了六类重构候选。下面逐条展开补齐每类的识别信号、重构手法与风险提示。1. Duplication重复→ Extract function/class提取函数/类识别信号同一段逻辑在多个函数、多个分支或多个文件中反复出现修改需求时需要记得同步修改多处遗漏一处即产生不一致。重构手法提取函数Extract Function适用于片段级重复——把重复语句块收拢为一个语义清晰的私有方法提取类Extract Class适用于跨对象的职责重复——把共享状态与行为打包进独立类型。关键纪律提取出的函数/类应通过公共接口被测试覆盖。你在重构阶段移动代码但行为测试behavioral tests不受影响这正是测试存活于重构tests survive refactors的体现。仓库佐证PentestGPT 的 trial.py 是一个反例与正例并存的好教材——它在多处重复了写 JSON 文件的原子操作_write_json被run_trial与_trial_identity写入路径反复调用因此将这一操作收敛为私有辅助函数并统一实现了先写.tmp再replace的原子替换trial.py#L279-L283def _write_json(path: Path, value: dict[str, Any]) - None: temporary path.with_suffix(path.suffix .tmp) temporary.write_text(json.dumps(value, indent2, sort_keysTrue) \n, encodingutf-8) temporary.chmod(0o600) temporary.replace(path)同样_provider_environment(backend)trial.py#L58-L65把为 claude 后端注入环境变量、为 codex 后端返回空字典的重复逻辑集中到一处并且该函数被_build_roles与_trial_identity两处复用——这就是提取函数消灭重复的直接例证。2. Long methods长方法→ Break into private helpers拆分为私有辅助方法识别信号一个函数超过一屏、缩进层级过深嵌套 if/for 三层以上、局部变量数量失控、一段代码需要滚动才能看全。重构手法把方法按单一日志段落拆分为多个私有辅助方法每个辅助方法只做一件事。但测试仍然只挂在公共接口上——辅助方法作为实现细节存在不在测试中直接暴露。这正是 tests.md 反复强调的测试描述 WHAT 而非 HOW。仓库佐证run_trialtrial.py#L107-L182是 PentestGPT 最长的函数之一它同时负责参数校验、run 目录创建/续跑判定、角色装配、主循环驱动、异常兜底与 summary 持久化。为了控制长度作者把它拆成了一系列私有辅助函数_build_roles装配 Supervisor/Executor、_snapshot_if_present容错取快照、_trial_summary汇总结果、_trial_identity生成身份指纹、_write_json、_parse_args。这些函数全部是模块私有下划线开头__all__只导出[TrialConfig, main, run_trial]——公共接口保持极小内部复杂度被收敛在私有辅助函数中。这就是长方法拆私有辅助测试保公共接口的典型形态。3. Shallow modules浅模块→ Combine or deepen合并或加深识别信号模块接口比实现还厚——公开了一堆方法但每个方法只有两三行转发逻辑或者一个模块只做了一件微不足道的事却占用了独立的命名空间与导入路径。重构手法二选一——要么合并Combine把相邻的浅模块揉进一个职责更完整的模块要么加深Deepen让模块保持小接口但把真正的复杂性校验、状态机、边界处理吸收进实现内部。设计理念深模块deep module意味着简单接口 深层实现调用者只面对很小的认知负担而复杂性被封装在内部。在编写代码前SKILL.md 的 Planning 阶段就要求识别深模块机会可配合/codebase-designskill 获取词汇表与可测试性检查项。仓库佐证identifiers.pypentestgpt_agent/src/pentestgpt_agent/identifiers.py全文只有 18 行是教科书级的深模块。它对外的公共接口只有一个函数validate_opaque_id(value, *, label)但其实现封装了一条完整的路径安全契约拒绝.与..用正则[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z限定 1-128 个 ASCII 字符非法输入抛 ValueError。所有调用方如 trial.py#L118 对 run_id 的校验只需一行调用路径穿越防护的复杂性全部藏在模块内部——这正是合并或加深中加深路线的实践。4. Feature envy依恋情结→ Move logic to where data lives把逻辑搬去数据所在处识别信号一个函数大量访问其他对象的字段与方法而对自己所在类的成员几乎不感兴趣。读代码时你会感觉这段逻辑明明应该属于那个对象。重构手法Move Function / Move Field——把行为迁移到它真正操作的数据旁边。这样数据与行为内聚调用方代码变薄职责边界变清晰。仓库佐证PentestGPT 把与持久化状态相关的全部操作集中在MemoryKernelmemory.py凡是读写 run 快照、提交计划、提交执行结果、提交失败的分支逻辑都放在数据所在地SQLite 数据库之上而 loop.py 的PentestLoop只通过memory.commit_plan(...)、memory.commit_execution(...)等窄接口编排不在循环体内直接拼 SQL。同理_trial_summary把从 trace 目录聚合 usage/cost 字段的逻辑放在 trial 模块内而不是散落在main中——逻辑跟着它消费的数据走。5. Primitive obsession基本类型偏执→ Introduce value objects引入值对象识别信号代码用裸字符串/整数表达领域概念——比如把 run_id 当作普通字符串到处传、把 effort 当作自由字符串、把目标 URL 当作str。导致的问题校验逻辑散落各处、传参顺序易错、类型系统无法在编译/静态检查阶段拦截非法值。重构手法为领域概念建立值对象或至少建立集中的校验/归一化函数把合法值是什么的约束内聚到一处。仓库佐证PentestGPT 通过两个层次治理基本类型偏执集中校验run_trial在入口处一次性完成所有基本类型参数的合法性校验trial.py#L116-L136targets 非空、backend 必须是claude/codex、model 长度 ≤ 256、effort 必须属于后端合法集合claude 支持low/medium/high/xhigh/maxcodex 支持low/medium/high/xhigh/none/minimal、max_decisions 在 1-1000、supervisor_max_turns 在 1-100、executor_max_turns 在 2-100。结构化配置对象TrialConfigtrial.py#L42-L55用 frozen dataclass 把 run_id、goal、targets、backend、model、runs_root、workspace_root、effort、各类 turn 上限、resume 标志打包成值对象取代散落的裸参数targets用tuple[str, ...]保证不可变。这就是为领域概念引入值对象的直接体现。6. Existing code the new code reveals as problematic新代码暴露的既有问题识别信号在 TDD 过程中为了让新测试通过而编写的代码暴露出既有模块的坏味道——比如既有函数的边界过于宽松、既有数据结构与新逻辑摩擦、既有模块的命名误导、旧代码里藏着与新逻辑重复的实现。重构手法这是六类候选中最容易遗漏的一类。TDD 的价值之一就在于以新代码为镜新增行为迫使你重新审视旧代码。处理原则是小步迁移——把旧代码中与新逻辑冲突的部分按前面五类手法提取、加深、移动、值对象逐步改造每改一步就跑一遍全部测试让旧模块逐步向新代码揭示出的更优形态收敛。仓库佐证PentestGPT 的重构史就是新代码揭示旧问题的活例证——仓库中的 PENTESTGPT_AGENT_NEW_MIGRATION_REPORT.md 与 PENTESTGPT_AGENT_NEW_PRODUCTION_HARDENING_REPORT.md 记录了 agent 从旧实现向pentestgpt_agent新实现迁移并做生产加固的过程而 audit.py 的引入正是新需求可审计、可验证、防篡改的 run 产物暴露旧 trace 体系缺少完整性校验的产物——例如audit_run会逐项检查 episodes 是否完整、观察是否直接引用原始输出all_observations_are_direct_quotes、transition 时间线是否闭环等。三、重构的安全网行为测试而非实现测试六类重构手法全部依赖同一个前提测试绑定行为不绑定实现。如果测试绑定了实现任何重构都会让测试红灯而红灯的原因是实现变了而不是行为坏了测试就失去了作为安全网的价值。.agents/skills/tdd/tests.md 给出了好测试与坏测试的明确对比// GOOD: Tests observable behavior test(user can checkout with valid cart, async () { const cart createCart(); cart.add(product); const result await checkout(cart, paymentMethod); expect(result.status).toBe(confirmed); });// BAD: Tests implementation details test(checkout calls paymentService.process, async () { const mockPayment jest.mock(paymentService); await checkout(cart, payment); expect(mockPayment.process).toHaveBeenCalledWith(cart.total); });坏测试的红旗信号包括mock 内部协作者、测试私有方法、断言调用次数/顺序、重构后行为未变但测试碎裂、测试名描述 HOW 而非 WHAT、绕过接口去外部验证比如直接查数据库而不是走公开 API。对应地好测试只关心用户/调用方关心的行为只用公共 API能存活于内部重构描述 WHAT 而非 HOW每个测试只有一个逻辑断言。仓库佐证PentestGPT 的 test_trial.py 是行为测试的正面教材test_trial_writes_a_run_that_the_artifact_auditor_can_verifytest_trial.py#L276-L389不关心 Supervisor/Executor 内部怎么实现而是注入两个剧本化后端TrialSupervisorBackend/TrialExecutorBackend断言run_trial返回的 summary 状态、attempt 状态、transition 序列、summary.json 落盘以及审计通过——测试描述的是一次 trial 能跑完且产物可被审计这一行为。测试还会篡改产物验证审计能力把events.jsonl中命令的exit_code改成 255或直接改 SQLite 中的 observation 文本断言all_observations_are_direct_quotes翻转、passed变为 False。这同样是对防篡改行为的测试而非对某个函数内部结构的测试。四、重构与 Mock 的边界只在系统边界打桩重构时最常踩的坑之一是为了隔离改动而过度 mock 自己的模块。这会让测试逐渐退化为测试 mock 配置最终在重构时大面积碎裂。.agents/skills/tdd/mocking.md 给出了清晰的边界规则该 mock 的系统边界外部 API支付、邮件等、数据库有时优先测试库、时间/随机性、文件系统有时。不该 mock 的你自己的类/模块、内部协作者、任何你掌控的东西。同时mock 边界要求接口设计成易于打桩依赖注入把外部依赖作为参数传入而不是在函数内部new出来——processPayment(order, paymentClient)好于在函数体里new StripeClient(...)。偏好 SDK 风格接口而非通用 fetcherapi.getUser(id)、api.getOrders(userId)各自可独立 mock而api.fetch(endpoint, options)会让 mock 里塞满条件分支。仓库佐证PentestGPT 完美执行了这两条。依赖注入run_trial(config, *, supervisorNone, executorNone)trial.py#L107-L113允许调用方注入自定义的 Supervisor/Executor且要求成对注入否则抛ValueError。生产路径走_build_roles装配真实的UnifiedAgent测试路径注入剧本化后端——例如 test_trial.py#L408-L426 中把TrialSupervisorBackend包进UnifiedAgent再传给run_trial。SDK 风格接口UnifiedAgent对外暴露stream(prompt, opts)剧本化后端如TrialSupervisorBackend.stream按调用次数返回预设的TurnCompleted结构化输出新任务、finish 决策等。mock 里没有任何条件逻辑去模拟某个内部函数被调用了几次——它模拟的是外部 LLM 边界的返回这正是mock at system boundaries。五、仓库实践全景一次可验证的完整重构落地路径把上面所有原则串起来PentestGPT 的pentestgpt_agent展示了一条完整的、可复制的重构落地路径依赖注入边界run_trial接受注入的 supervisor/executortrial.py#L107-L159测试用剧本化后端替换真实 LLM确保测试不触碰网络。深模块沉淀路径安全校验identifiers.py、状态持久化MemoryKernel、trace 存取TraceStore、执行编译compile_execution各自以窄接口封装深实现重构发生时影响面可控。行为测试兜底端到端注入式测试test_trial.py与循环级测试test_loop.py共同保证行为契约transition 序列、状态机、失败兜底被锁定重构阶段每一步后跑这些测试即可确认行为未漂移。产物审计闭环audit_runaudit.py把 run 产物的完整性检查episodes 完整、观察直接引用、basis 有效、timeline 闭环做成可程序化验证的合同test_trial.py#L334-L349 对 14 项审计检查逐项断言——这既守护了重构也守护了运行产物本身。CLI 与配置校验_parse_argstrial.py#L320-L348把所有命令行参数归一化为TrialConfig值对象test_cli_returns_nonzero_for_a_canonical_failed_runtest_trial.py#L625验证失败 run 的 CLI 退出码——参数即契约重构不破坏契约。六、每轮重构的检查清单综合 refactoring.md 的六类候选与 SKILL.md 的周期检查表一次完整的重构应该逐项核对检查项说明仅当 GREEN 时动手测试全绿才允许重构RED 状态绝不重构一次只做一个原子步骤每个提取/移动/改名之后立即跑测试重复代码已收敛Duplication → Extract function/class长方法已拆私有辅助测试仍只挂在公共接口上浅模块已合并或加深优先加深窄接口 深实现依恋逻辑已迁移Feature envy → Move logic to where data lives基本类型已值对象化Primitive obsession → Introduce value objects新代码揭示的旧问题已处理按上述手法小步迁移旧代码测试描述行为而非实现测试名是 WHAT只用公共 API能存活于内部重构Mock 只发生在系统边界不 mock 自己的模块与内部协作者未添加投机性功能代码只为当前测试最小实现不预支未来需求这份清单可以直接贴在每一次 RED→GREEN 循环的收尾处先逐条排查六类重构候选再确认测试仍然是行为测试、mock 仍在边界内最后跑完整测试套件确认绿灯延续。以 PentestGPT 的 tests 与 pentestgpt_agent/tests 为参照系你可以用同样的节奏在自己的 agent 系统上把重构做成低风险、可验证、可持续的日常动作。【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PentestGPT 重构候选清单实战：在 TDD 循环中识别坏味道并安全重构
PentestGPT 重构候选清单实战在 TDD 循环中识别坏味道并安全重构【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT在 .agents/skills/tdd/SKILL.md 定义的红-绿-重构Red-Green-Refactor工作流中重构阶段的质量直接决定测试是否真正成为行为的守护者而不是被实现细节绑架的脆性文档。本文以 .agents/skills/tdd/refactoring.md 中的重构候选清单为核心骨架逐条拆解六类最常见的代码坏味道及其对应重构手法并借助 PentestGPT 仓库中pentestgpt_agent模块的真实源码与测试依赖注入、深模块设计、面向行为的集成式测试、产物审计作为可验证的落地佐证。读完本文你将掌握一套可直接执行的重构决策框架什么时候动手、对什么动手、如何用测试兜底、以及如何在像 PentestGPT 这样具备持久化状态与外部 LLM 边界的复杂系统中安全地推进重构。一、先回到上下文重构在整个 TDD 循环中的位置.agents/skills/tdd/refactoring.md的第一句话是 After TDD cycle, look for:——重构候选的排查永远发生在 TDD 循环之后。这背后是一条硬性纪律在 SKILL.md 中被强调为Never refactor while RED.Get to GREEN first.也就是说重构只允许在测试全部通过GREEN的状态下进行。原因很朴素测试是重构的安全网。如果代码处于 RED 状态测试失败的原因可能是行为尚未实现而非重构破坏了行为此时任何重构都会让诊断变得不可信。重构阶段的完整动作清单来自 SKILL.md 第 4 步包括Extract duplication抽取重复代码Deepen modules加深模块把复杂性藏到简单接口后面Apply SOLID principles where natural在自然处应用 SOLID 原则Consider what new code reveals about existing code思考新代码揭示了既有代码的什么问题Run tests after each refactor step每步重构后都要跑测试最后一条每步重构后跑测试是重构得以小步快跑的前提——每次只做一个原子变更跑一次测试确认行为没有变化再进入下一步。二、六类重构候选逐一拆解.agents/skills/tdd/refactoring.md全文精炼地给出了六类重构候选。下面逐条展开补齐每类的识别信号、重构手法与风险提示。1. Duplication重复→ Extract function/class提取函数/类识别信号同一段逻辑在多个函数、多个分支或多个文件中反复出现修改需求时需要记得同步修改多处遗漏一处即产生不一致。重构手法提取函数Extract Function适用于片段级重复——把重复语句块收拢为一个语义清晰的私有方法提取类Extract Class适用于跨对象的职责重复——把共享状态与行为打包进独立类型。关键纪律提取出的函数/类应通过公共接口被测试覆盖。你在重构阶段移动代码但行为测试behavioral tests不受影响这正是测试存活于重构tests survive refactors的体现。仓库佐证PentestGPT 的 trial.py 是一个反例与正例并存的好教材——它在多处重复了写 JSON 文件的原子操作_write_json被run_trial与_trial_identity写入路径反复调用因此将这一操作收敛为私有辅助函数并统一实现了先写.tmp再replace的原子替换trial.py#L279-L283def _write_json(path: Path, value: dict[str, Any]) - None: temporary path.with_suffix(path.suffix .tmp) temporary.write_text(json.dumps(value, indent2, sort_keysTrue) \n, encodingutf-8) temporary.chmod(0o600) temporary.replace(path)同样_provider_environment(backend)trial.py#L58-L65把为 claude 后端注入环境变量、为 codex 后端返回空字典的重复逻辑集中到一处并且该函数被_build_roles与_trial_identity两处复用——这就是提取函数消灭重复的直接例证。2. Long methods长方法→ Break into private helpers拆分为私有辅助方法识别信号一个函数超过一屏、缩进层级过深嵌套 if/for 三层以上、局部变量数量失控、一段代码需要滚动才能看全。重构手法把方法按单一日志段落拆分为多个私有辅助方法每个辅助方法只做一件事。但测试仍然只挂在公共接口上——辅助方法作为实现细节存在不在测试中直接暴露。这正是 tests.md 反复强调的测试描述 WHAT 而非 HOW。仓库佐证run_trialtrial.py#L107-L182是 PentestGPT 最长的函数之一它同时负责参数校验、run 目录创建/续跑判定、角色装配、主循环驱动、异常兜底与 summary 持久化。为了控制长度作者把它拆成了一系列私有辅助函数_build_roles装配 Supervisor/Executor、_snapshot_if_present容错取快照、_trial_summary汇总结果、_trial_identity生成身份指纹、_write_json、_parse_args。这些函数全部是模块私有下划线开头__all__只导出[TrialConfig, main, run_trial]——公共接口保持极小内部复杂度被收敛在私有辅助函数中。这就是长方法拆私有辅助测试保公共接口的典型形态。3. Shallow modules浅模块→ Combine or deepen合并或加深识别信号模块接口比实现还厚——公开了一堆方法但每个方法只有两三行转发逻辑或者一个模块只做了一件微不足道的事却占用了独立的命名空间与导入路径。重构手法二选一——要么合并Combine把相邻的浅模块揉进一个职责更完整的模块要么加深Deepen让模块保持小接口但把真正的复杂性校验、状态机、边界处理吸收进实现内部。设计理念深模块deep module意味着简单接口 深层实现调用者只面对很小的认知负担而复杂性被封装在内部。在编写代码前SKILL.md 的 Planning 阶段就要求识别深模块机会可配合/codebase-designskill 获取词汇表与可测试性检查项。仓库佐证identifiers.pypentestgpt_agent/src/pentestgpt_agent/identifiers.py全文只有 18 行是教科书级的深模块。它对外的公共接口只有一个函数validate_opaque_id(value, *, label)但其实现封装了一条完整的路径安全契约拒绝.与..用正则[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z限定 1-128 个 ASCII 字符非法输入抛 ValueError。所有调用方如 trial.py#L118 对 run_id 的校验只需一行调用路径穿越防护的复杂性全部藏在模块内部——这正是合并或加深中加深路线的实践。4. Feature envy依恋情结→ Move logic to where data lives把逻辑搬去数据所在处识别信号一个函数大量访问其他对象的字段与方法而对自己所在类的成员几乎不感兴趣。读代码时你会感觉这段逻辑明明应该属于那个对象。重构手法Move Function / Move Field——把行为迁移到它真正操作的数据旁边。这样数据与行为内聚调用方代码变薄职责边界变清晰。仓库佐证PentestGPT 把与持久化状态相关的全部操作集中在MemoryKernelmemory.py凡是读写 run 快照、提交计划、提交执行结果、提交失败的分支逻辑都放在数据所在地SQLite 数据库之上而 loop.py 的PentestLoop只通过memory.commit_plan(...)、memory.commit_execution(...)等窄接口编排不在循环体内直接拼 SQL。同理_trial_summary把从 trace 目录聚合 usage/cost 字段的逻辑放在 trial 模块内而不是散落在main中——逻辑跟着它消费的数据走。5. Primitive obsession基本类型偏执→ Introduce value objects引入值对象识别信号代码用裸字符串/整数表达领域概念——比如把 run_id 当作普通字符串到处传、把 effort 当作自由字符串、把目标 URL 当作str。导致的问题校验逻辑散落各处、传参顺序易错、类型系统无法在编译/静态检查阶段拦截非法值。重构手法为领域概念建立值对象或至少建立集中的校验/归一化函数把合法值是什么的约束内聚到一处。仓库佐证PentestGPT 通过两个层次治理基本类型偏执集中校验run_trial在入口处一次性完成所有基本类型参数的合法性校验trial.py#L116-L136targets 非空、backend 必须是claude/codex、model 长度 ≤ 256、effort 必须属于后端合法集合claude 支持low/medium/high/xhigh/maxcodex 支持low/medium/high/xhigh/none/minimal、max_decisions 在 1-1000、supervisor_max_turns 在 1-100、executor_max_turns 在 2-100。结构化配置对象TrialConfigtrial.py#L42-L55用 frozen dataclass 把 run_id、goal、targets、backend、model、runs_root、workspace_root、effort、各类 turn 上限、resume 标志打包成值对象取代散落的裸参数targets用tuple[str, ...]保证不可变。这就是为领域概念引入值对象的直接体现。6. Existing code the new code reveals as problematic新代码暴露的既有问题识别信号在 TDD 过程中为了让新测试通过而编写的代码暴露出既有模块的坏味道——比如既有函数的边界过于宽松、既有数据结构与新逻辑摩擦、既有模块的命名误导、旧代码里藏着与新逻辑重复的实现。重构手法这是六类候选中最容易遗漏的一类。TDD 的价值之一就在于以新代码为镜新增行为迫使你重新审视旧代码。处理原则是小步迁移——把旧代码中与新逻辑冲突的部分按前面五类手法提取、加深、移动、值对象逐步改造每改一步就跑一遍全部测试让旧模块逐步向新代码揭示出的更优形态收敛。仓库佐证PentestGPT 的重构史就是新代码揭示旧问题的活例证——仓库中的 PENTESTGPT_AGENT_NEW_MIGRATION_REPORT.md 与 PENTESTGPT_AGENT_NEW_PRODUCTION_HARDENING_REPORT.md 记录了 agent 从旧实现向pentestgpt_agent新实现迁移并做生产加固的过程而 audit.py 的引入正是新需求可审计、可验证、防篡改的 run 产物暴露旧 trace 体系缺少完整性校验的产物——例如audit_run会逐项检查 episodes 是否完整、观察是否直接引用原始输出all_observations_are_direct_quotes、transition 时间线是否闭环等。三、重构的安全网行为测试而非实现测试六类重构手法全部依赖同一个前提测试绑定行为不绑定实现。如果测试绑定了实现任何重构都会让测试红灯而红灯的原因是实现变了而不是行为坏了测试就失去了作为安全网的价值。.agents/skills/tdd/tests.md 给出了好测试与坏测试的明确对比// GOOD: Tests observable behavior test(user can checkout with valid cart, async () { const cart createCart(); cart.add(product); const result await checkout(cart, paymentMethod); expect(result.status).toBe(confirmed); });// BAD: Tests implementation details test(checkout calls paymentService.process, async () { const mockPayment jest.mock(paymentService); await checkout(cart, payment); expect(mockPayment.process).toHaveBeenCalledWith(cart.total); });坏测试的红旗信号包括mock 内部协作者、测试私有方法、断言调用次数/顺序、重构后行为未变但测试碎裂、测试名描述 HOW 而非 WHAT、绕过接口去外部验证比如直接查数据库而不是走公开 API。对应地好测试只关心用户/调用方关心的行为只用公共 API能存活于内部重构描述 WHAT 而非 HOW每个测试只有一个逻辑断言。仓库佐证PentestGPT 的 test_trial.py 是行为测试的正面教材test_trial_writes_a_run_that_the_artifact_auditor_can_verifytest_trial.py#L276-L389不关心 Supervisor/Executor 内部怎么实现而是注入两个剧本化后端TrialSupervisorBackend/TrialExecutorBackend断言run_trial返回的 summary 状态、attempt 状态、transition 序列、summary.json 落盘以及审计通过——测试描述的是一次 trial 能跑完且产物可被审计这一行为。测试还会篡改产物验证审计能力把events.jsonl中命令的exit_code改成 255或直接改 SQLite 中的 observation 文本断言all_observations_are_direct_quotes翻转、passed变为 False。这同样是对防篡改行为的测试而非对某个函数内部结构的测试。四、重构与 Mock 的边界只在系统边界打桩重构时最常踩的坑之一是为了隔离改动而过度 mock 自己的模块。这会让测试逐渐退化为测试 mock 配置最终在重构时大面积碎裂。.agents/skills/tdd/mocking.md 给出了清晰的边界规则该 mock 的系统边界外部 API支付、邮件等、数据库有时优先测试库、时间/随机性、文件系统有时。不该 mock 的你自己的类/模块、内部协作者、任何你掌控的东西。同时mock 边界要求接口设计成易于打桩依赖注入把外部依赖作为参数传入而不是在函数内部new出来——processPayment(order, paymentClient)好于在函数体里new StripeClient(...)。偏好 SDK 风格接口而非通用 fetcherapi.getUser(id)、api.getOrders(userId)各自可独立 mock而api.fetch(endpoint, options)会让 mock 里塞满条件分支。仓库佐证PentestGPT 完美执行了这两条。依赖注入run_trial(config, *, supervisorNone, executorNone)trial.py#L107-L113允许调用方注入自定义的 Supervisor/Executor且要求成对注入否则抛ValueError。生产路径走_build_roles装配真实的UnifiedAgent测试路径注入剧本化后端——例如 test_trial.py#L408-L426 中把TrialSupervisorBackend包进UnifiedAgent再传给run_trial。SDK 风格接口UnifiedAgent对外暴露stream(prompt, opts)剧本化后端如TrialSupervisorBackend.stream按调用次数返回预设的TurnCompleted结构化输出新任务、finish 决策等。mock 里没有任何条件逻辑去模拟某个内部函数被调用了几次——它模拟的是外部 LLM 边界的返回这正是mock at system boundaries。五、仓库实践全景一次可验证的完整重构落地路径把上面所有原则串起来PentestGPT 的pentestgpt_agent展示了一条完整的、可复制的重构落地路径依赖注入边界run_trial接受注入的 supervisor/executortrial.py#L107-L159测试用剧本化后端替换真实 LLM确保测试不触碰网络。深模块沉淀路径安全校验identifiers.py、状态持久化MemoryKernel、trace 存取TraceStore、执行编译compile_execution各自以窄接口封装深实现重构发生时影响面可控。行为测试兜底端到端注入式测试test_trial.py与循环级测试test_loop.py共同保证行为契约transition 序列、状态机、失败兜底被锁定重构阶段每一步后跑这些测试即可确认行为未漂移。产物审计闭环audit_runaudit.py把 run 产物的完整性检查episodes 完整、观察直接引用、basis 有效、timeline 闭环做成可程序化验证的合同test_trial.py#L334-L349 对 14 项审计检查逐项断言——这既守护了重构也守护了运行产物本身。CLI 与配置校验_parse_argstrial.py#L320-L348把所有命令行参数归一化为TrialConfig值对象test_cli_returns_nonzero_for_a_canonical_failed_runtest_trial.py#L625验证失败 run 的 CLI 退出码——参数即契约重构不破坏契约。六、每轮重构的检查清单综合 refactoring.md 的六类候选与 SKILL.md 的周期检查表一次完整的重构应该逐项核对检查项说明仅当 GREEN 时动手测试全绿才允许重构RED 状态绝不重构一次只做一个原子步骤每个提取/移动/改名之后立即跑测试重复代码已收敛Duplication → Extract function/class长方法已拆私有辅助测试仍只挂在公共接口上浅模块已合并或加深优先加深窄接口 深实现依恋逻辑已迁移Feature envy → Move logic to where data lives基本类型已值对象化Primitive obsession → Introduce value objects新代码揭示的旧问题已处理按上述手法小步迁移旧代码测试描述行为而非实现测试名是 WHAT只用公共 API能存活于内部重构Mock 只发生在系统边界不 mock 自己的模块与内部协作者未添加投机性功能代码只为当前测试最小实现不预支未来需求这份清单可以直接贴在每一次 RED→GREEN 循环的收尾处先逐条排查六类重构候选再确认测试仍然是行为测试、mock 仍在边界内最后跑完整测试套件确认绿灯延续。以 PentestGPT 的 tests 与 pentestgpt_agent/tests 为参照系你可以用同样的节奏在自己的 agent 系统上把重构做成低风险、可验证、可持续的日常动作。【免费下载链接】PentestGPTAutomated Penetration Testing Agentic Framework Powered by Large Language Models项目地址: https://gitcode.com/GitHub_Trending/pe/PentestGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
