GSY Github App Flutter 的 Author Handoff 交接规范构建中立、最小、可验证的 Review Bundle【免费下载链接】gsy_github_app_flutterFlutter 超完整的开源项目功能丰富适合学习和日常使用。GSYGithubApp 系列的优势我们目前已经拥有 Flutter、Weex、ReactNative、Kotlin View、Kotlin Jetpack Compose Compose MultiPlatformHarmony ArkUI 七个版本功能齐全项目框架内技术涉及面广完成度高持续维护配套文章适合全面学习对比参考。项目地址: https://gitcode.com/gh_mirrors/gs/gsy_github_app_flutter导读本文围绕仓库中的 Author Handoff Prompt 展开深入解析 GSY GitHub App Flutter 项目在 AI 辅助开发流程中author agent 完成代码改动后如何与 reviewer agent 交接包括六段式交接报告的字段定义、约束条款的意图以及配套的build_review_bundle.ps1脚本、验证命令矩阵与冒烟证据规范。读完本文你将掌握一套可直接复用的中立、最小、可验证的 AI 代码审查交接方法论并能在本仓库的 agent 协作流程中正确落地。一、为什么需要一份 Handoff PromptAuthor / Reviewer 分离的审查机制在深入交接模板之前需要先理解它在整个工作流中的位置。仓库文档 Review Harness 明确说明本仓库默认采用author agent 与 reviewer subagent 分离的方式进行 AI 审查其设计目标是让代码审查尽量摆脱 author 视角避免作者自己解释自己为什么没问题。这套机制的核心原则可以概括为五点author和reviewer不共用上下文reviewer应使用新的 subagent 或新的干净上下文reviewer不读取 author 的完整对话历史reviewer只拿到最小必要信息任务目标、相关文档入口、变更文件、diff、验证结果reviewer的默认职责是找问题不是帮 author 辩护。文档中还特意强调了一个工程要点这里最重要的不是把 review 写成文档而是把 review 运行在一个新的思维上下文里——如果 reviewer 继承了 author 的长上下文它就很容易共享 author 的错误假设。而 Author Handoff Prompt 正是这条链条上连接两个角色的桥梁author 在完成实现后用它约束自己输出一份交接材料handoff / review bundle供独立的 reviewer 审查。二、Author Handoff 六段式输出结构详解Author Handoff Prompt 要求 author agent 在完成实现后输出以下六项内容。这六项共同构成一份 review bundle 的主体下面逐项结合仓库实际展开。1. 本次任务目标用一两句话说明这次改动要解决什么问题。注意目标应当描述任务要求做什么而不是我做了什么。例如修复 Bug 时应写明修复仓库详情页切换分支后 Readme 不刷新的问题而不是罗列修改了哪些文件。这与 任务模板 fix-bug.md 的输出要求相呼应至少说明复现路径、根因在哪一层、改动边界为什么足够小、跑了哪些验证。2. 变更文件列表列出所有被修改、新增、删除的文件。这是 reviewer 执行 diff 审查的索引应尽量精确到文件路径。这里有一个可选的自动化辅助tool/ai/build_review_bundle.ps1脚本会自动调用git diff --name-only $BaseRef收集变更文件并按照目录前缀规则生成功能域提示feature hints例如lib/page/repos/→reposlib/page/trend/→trendlib/page/notify/→notifylib/common/net/→common-netlib/redux/→reduxlib/provider/→provider默认基线是-BaseRef HEAD即收集当前工作区相对 HEAD 的未提交变更如果要审查某个分支相对基线分支的差异可以显式传入-BaseRef origin/master等基线。生成的 bundle 默认输出到build/ai/review-bundle.md。3. 改动边界这是整个交接报告中最关键的一项用来回答这次改动为什么是这么大而不是更大或更小。仓库的 Agent 工作指引 为此提供了明确的边界判断标准优先遵循目标模块现有模式不主动创造新的抽象层页面局部问题不要上升到根装配层优先通过 repository 或共享网络边界收口不要把传输细节散落到页面需要生成的内容改源文件不改生成输出*.g.dart、多语言生成文件、env 生成文件都是生成产物优先重新生成而不是手改。AGENTS.md 中的高风险目录清单lib/app.dart根装配、lib/common/net/共享网络栈、lib/common/repositories/数据访问边界等也提示了哪些区域的改动需要格外谨慎这同样应该反映在改动边界的说明中。4. 已运行的验证命令如实列出本次改动实际执行过的验证命令及结果。仓库 AGENTS.md 定义了本地最小验证集合flutter pub getdart run build_runner build --delete-conflicting-outputs改模型、env、注解生成代码时跑flutter gen-l10n改 ARB 或本地化输入时跑flutter analyzeflutter build apk --release --target-platformandroid-arm64 --no-shrink改 Android 构建、依赖或运行时关键路径时跑手工回归按 Smoke Matrix 执行改动前确认本次变更影响哪些功能域改动后至少执行对应功能域的基础用例改共享层时额外抽查一个高频功能。5. 未覆盖的风险诚实列出本次验证覆盖不到的分支或场景。这在 Handoff 约束中被明确强调不要省略失败过或没做的验证。例如 Smoke Matrix 中记录了真实案例P0-2 修复涉及 expanded 双栏关键路径但真机手机 dp 宽约 400达不到 ≥840dp 的 expanded 断点于是作者明确标注目前依赖单测保证行为等下次装机到平板 / Fold 再补真机 widget tree依赖升级冒烟中WebView 主路径、inappwebview markdown 图片渲染路径、SVG 渲染路径未覆盖也逐条列出并给出了下轮补齐方式。这就是未覆盖风险的正确写法。6. 建议 reviewer 优先检查的功能域把改动波及最重、回归风险最高的功能域明确指出来帮助 reviewer 把有限注意力放在最关键的地方。Reviewer System Prompt 规定的审查优先级是先找 bug 和行为回归 → 再看边界是否越界 → 再看验证是否足够 → 最后才是风格和可维护性建议。因此这里应该聚焦哪些功能域最容易出现回归。三、约束条款为什么交接报告必须去自我辩护化Author Handoff Prompt 的约束部分包含四条硬性要求理解它们的意图比记住文字更重要不要输出长篇自我辩护交接报告是给 reviewer 的事实材料不是作者的辩护词不要把为什么我认为没问题作为主体这正好呼应 Review Harness 的目标——避免作者自己解释自己为什么没问题式的自我安慰复查不要省略失败过或没做的验证省略验证失败记录等于把 reviewer 引向错误结论违背最小、可验证的初衷用事实描述不要用结论压 reviewer给出 diff、命令输出、证据路径而不是应该没问题这类结论。Reviewer System Prompt 的禁止事项从 reviewer 一侧强化了同一原则不要把 author 的描述当成事实不要因为改动小就跳过共享边界检查不要在没有证据时给出应该没问题式结论。两份提示词一收一发共同构建了防自证的闭环。四、Review Bundle 的内容清单与最小化原则Review Harness 定义了两种交接形态首选直接让新的 reviewer subagent 读取代码和 diff因为 reviewer 本身能访问仓库代码此时 review bundle 不是必需的兜底当无法方便地把 diff 和验证结果直接交给 reviewer 时才使用 review bundle。最小 review bundle 至少应包含任务摘要、变更文件列表、diff 统计、关键 diff、运行过的验证命令、对应功能域和回归建议。默认情况下tool/ai/build_review_bundle.ps1会收集当前工作区相对HEAD的未提交变更生成包含以下内容的 Markdown 文件Head与Base ref信息git rev-parse --short HEADReviewer prompt 与 Review harness 的引用路径Changed Files 列表Feature Hints按目录前缀自动识别功能域Recommended DocsAGENTS.md、CONTRIBUTING_AI.md、smoke-matrix.md、fix-bug.mdDiff Statgit diff --statDiffgit diff --unified3带 3 行上下文需要强调的是该脚本在 AGENTS.md 和 Agent 工作指引 中都被明确标注为只是可选辅助不是主路径——主路径始终是拉起一个新的 reviewer subagent 或新的干净上下文。五、验证证据规范交接材料中的可验证落地可验证是本仓库 AI 审查体系的关键词它落在 AGENTS.md 的运行时冒烟验证强制章节。该章节开宗明义能编译过 装机不崩不算测试通过。任何涉及运行时行为的改动在宣告完成前author 必须在真机或模拟器上跑通对应路径并把真实证据以文件形式产出并写清路径。交接报告中的已运行的验证命令一栏应该按照三段式汇报填写看代码改了哪些文件、哪些函数、为什么这么改看编译flutter analyze/build_runner/gen-l10n的产物结论看运行设备 id 平台、DTD/VM Service URI、get_runtime_errors结果、widget_inspector命中的关键 widget/textPreview、截图文件绝对路径、无法覆盖的分支列表。证据等级按改动类型分级摘自 AGENTS.md改动类型最低证据要求纯模型 / 纯工具函数flutter analyze 单测若 test 目录已存在无需截图UI 渲染 / 文案 / 事件行至少 1 张真机截图 widget tree 命中目标 widget 或textPreview runtime errors 无异常关键路径登录 / 网络栈 / 根装配 / 状态边界主路径截图 widget tree 命中 runtime errors 无异常 至少 1 个失败/边界分支的证据同时有一批明确的禁止行为直接关系到交接材料的真实性只跑flutter analyze就报测试通过、把app 启动到首页当成本次功能验证、拿日志里没 Exception当作行为正确的证据、只把截图放在自己上下文里而不写路径导致 reviewer 拿不到证据等都被列为违规。这些禁止项实质上是给 Author Handoff 中已运行的验证命令和未覆盖的风险两栏划定了诚实底线。六、与统一收尾流程的关系交接不是终点Author Handoff 是author 完成实现后的固定动作但它不是流程的终点。所有任务模板fix-bug.md、add-page.md、add-api.md、refactor-state.md都内置了统一收尾步骤author 完成修改和最小验证后必须先拉起新的 reviewer subagentreviewer 独立审查后author 才能对外汇报完成。Review Harness 的推荐流程给出了完整闭环Author 完成代码和最小验证 → 启动新的 reviewer subagent → Reviewer 只读取 reviewer-system.md、当前 diff、变更相关文件、相关功能文档、验证结果 → Reviewer 输出 findings / 风险 / 验证缺口 → Author 根据 findings 修复 → 必要时开启下一轮 reviewer 会话。在这个流程完成前author 不应直接对外宣告任务已完成对外汇报应发生在至少一轮独立 reviewer 审查之后。Reviewer 的输出格式建议同样适用于 author 理解 reviewer 会如何审视自己的交接材料为Findings、Open Questions、Verification Gaps、Residual Risks。如果没有发现问题reviewer 也必须明确说明未发现明显问题以及仍然存在哪些验证空白。七、在仓库中落地完整文档导航要将这套 Author Handoff 规范投入实际使用建议按以下顺序阅读仓库文档统一入口docs/CONTRIBUTING_AI.md——按任务类型修 Bug / 新增页面 / 新增接口 / 整理状态 / 各功能域改动 / AI review选择正确路径工作指引docs/05-ai/agent-guide.md——编辑前先读的文档清单与工作规则审查机制docs/05-ai/review-harness.md 与 docs/05-ai/prompts/reviewer-system.md——理解 reviewer 的视角与审查标准交接模板docs/05-ai/prompts/author-handoff.md——本文主题author 交接时的固定输出结构验证基准docs/04-quality/smoke-matrix.md 与 AGENTS.md——确定已运行的验证命令和未覆盖的风险的填写依据辅助工具tool/ai/build_review_bundle.ps1——需要打包 review bundle 时的可选生成器。结语Author Handoff Prompt 虽然只有短短数行却是一套严谨的 AI 审查工程实践的浓缩它用六段式结构规定了交接什么用四条约束规定了怎么交接并借助 author / reviewer 上下文分离的机制把审查从作者自我解释变成独立第三方找问题。对于任何在 AI agent 工作流中维护代码质量、希望让 review 可验证、可追溯的团队而言这份模板都值得直接借鉴——其核心思想可以概括为一句话交接材料的价值不在于证明作者正确而在于让 reviewer 能以最小成本、最快速度发现真正的问题。【免费下载链接】gsy_github_app_flutterFlutter 超完整的开源项目功能丰富适合学习和日常使用。GSYGithubApp 系列的优势我们目前已经拥有 Flutter、Weex、ReactNative、Kotlin View、Kotlin Jetpack Compose Compose MultiPlatformHarmony ArkUI 七个版本功能齐全项目框架内技术涉及面广完成度高持续维护配套文章适合全面学习对比参考。项目地址: https://gitcode.com/gh_mirrors/gs/gsy_github_app_flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考