Skip to main content

执行质量与 QA

目标​

把 Project2 的执行质量管理固化为长期 Hub 规则：提高 ADP 执行产出质量，重点改善 Unity UI 执行；定期运行 Unity Editor 版本和真实 APK 模拟器版本，发现游戏 bug，输出性能报告和视觉 QA 报告。

本文是当前规则来源。context/ 和 decisions/ 不再作为新增 Project2 管理规则的写入面。

当前主干登录联调​

Project2 定期登录联调以Agent 主干登录联调流程为当前操作入口，2026-10-14 复盘保存首次通过及失败原因。此范围采用 Linear → 既有 project2-linear → 外部 CI Runner，固定工作区、复用缓存、实际界面输入、清理确认后结束。下文历史 Unity/APK 工具与报告不得作为该流程的第二入口；其中本地执行或扩展覆盖的描述不适用于当前登录测试。定期能力只证明登录范围，未扩大为 APK、性能或全玩法回归。

用户授权的功能测试闭环​

Agent 功能测试闭环用于用户明确授权的 Linear Project2 功能测试 Issue。每次新会话从 registry 指定主干读取最新源码，不冻结版本；每轮尽量完成可执行覆盖，明确缺陷独立建 bug 并关联测试单，已有问题补证据并保留生命周期。新 bug 在本轮报告和 Runner 清理证据齐备前保持 Backlog，结束后具备修复条件的转 Todo；Backlog 调查不得提前放行本轮新问题。修复进入可测试主干后继续功能覆盖和缺陷复测，测试 agent 不自行修复产品，最终验收和 Done 属于人类。

Producer 授权​

Producer 于 2026-10-14 明确要求所有项目的 Codex 执行与交付权限全面放开； 以下长期授权直接替代旧 Hub-only、普通文档文件白名单和逐次操作批准规则：

  • 所有 Project2 注册 active repo 由所属 principal 执行授权任务的开发、重构、配置、依赖、 仓库 CI、工具和 guidance 调整，不再逐文件、逐命令请求批准。
  • Codex 与 agent 配置统一使用 sandbox_mode = "danger-full-access"、 approval_policy = "never"；删除 scoped permission profiles 和 default_permissions。
  • 所属 principal 源码审阅完成，且外部 CI 对精确 MR head 通过后，可以合并任务 MR 并通过 既有发布路径交付，不再要求 Producer 逐 MR/head 或既有发布单次再批准。
  • 人类最终产品/美术/测试验收及 Issue Done 保持人类所有；合并、CI 与发布不代签验收。
  • owner routing、需求/依赖、事实来源、隔离工作树、秘密不打印以及真实外部权限边界仍有效。 401/403、保护分支与缺少凭据不能通过换身份或改外部权限绕过。
  • 任务之外的新生产目标、凭据身份/权限变更、重要数据删除须有明确用户指令； 已授权任务不得被旧逐次审批规则再次阻塞。
  • 禁止本地验证；本页中的编译、运行、测试、校验、截图与性能检查流程由外部 CI Runner 或人类提供证据。未经明确测试编写指令及具体用例或输入/预期结果，不新增或扩写测试。

对话执行与 Linear 建单​

默认在当前聊天完成已授权工作，包括实现、源码审阅、外部 CI、提交、推送、合并和既有发布。 repo ownership 与 principal 分工用于路由，不以创建 Issue 或交给 Symphony 为执行前提。 未经用户明确同意，不创建 Linear Issue、child Issue 或后续跟进任务，也不通过技能、工具、 脚本或其他 agent 间接创建。实现请求、方案确认、验收标准和全权限授权均不代表建单或 Symphony 交接授权；确需建单/交接时，必须先取得用户对目标及范围的明确同意。 建单只覆盖指定项目、范围和批次；可执行状态、指派执行者及 Symphony 交接必须分别 属于明确授权范围。 已有明确授权的任务继续执行，不因本规则自行取消任务、停止 executor 或改业务状态。 原生状态/依赖检查适用于已授权的既有 Linear/Symphony 工作；直接对话任务无需先建单。

长期职责​

Project2 执行质量职责包括：

  1. 打通和优化 ADP 执行流程，提升执行产出质量。
  2. 强化 UI 相关执行的 handoff、截图、视觉验收和打回标准。
  3. 定期运行 Unity Editor 版本，发现编译、Console、Prefab、资源、场景、UI 和玩法问题。
  4. 定期运行真实 APK 模拟器版本，发现游戏 bug，采集 crash、ANR、logcat 和性能指标。
  5. 优化 Hub-local skills、repo-local skills、验证脚本和 QA 报告模板。
  6. 缺陷记录到当前聊天报告或既有明确授权任务的证据面；只有明确 publication 指令才创建 tracker Issue，不从严重度、方案确认或实施请求推导建单授权。

UI 执行质量门​

UI-facing execution 包括 Unity panels、prefabs、View/Com bindings、buttons、lists、red dots、 reward display、localization、visual states、layout、safe area 和 art integration。

UI repo work 之前，Hub 应确认：

  • feature key 和 screen id；
  • 玩家可见状态矩阵；
  • 交互矩阵；
  • config、backend、frontend、art contract 的数据驱动和 owner；
  • 是否已有或需要 art-ui-handoff；
  • frontend 需要执行输入时，是否已有 project2.ui_handoff.v1；
  • 必需截图或录屏 evidence；
  • frontend 不得自行推断的 open questions。

UI MR evidence 应包含截图或录屏。适用时至少覆盖：

  • 默认态；
  • 可操作态；
  • 空态、错误态或加载态；
  • 红点、奖励、可领取或已领取态；
  • 长文本或本地化压力态；
  • 主力分辨率和一个窄屏/安全区 profile。

Hub review 应显式检查：

  • 文字溢出、裁切和遮挡；
  • 按钮状态不清或 disabled 行为缺失；
  • 列表滚动、虚拟列表或动态 item 错误；
  • 红点刷新、残留或缺失；
  • 奖励展示、数量、图标和领取状态；
  • 重复点击、防抖和失败反馈；
  • 后端不可用、超时、空数据或异常返回；
  • 常见宽高比和 safe area；
  • 资源清晰度、缩放和视觉一致性；
  • 未能本地渲染状态的 residual risk。

Unity Editor 巡检​

Hub Codex 可通过 repo-local tools 或 Unity MCP 运行 Project2 Unity Editor 版本。每次 Unity run 应记录：

  • frontend repo ref、Unity version、scene 或 entry point；
  • 编译状态、Console errors 和关键 warnings；
  • PlayMode 或 test scenario；
  • 可见结果截图或录屏；
  • crash、hang、black screen、missing asset、layout 或 interaction findings；
  • login、server state 或 test data 阻塞 full coverage 时的 residual risk。

最小 recurring Unity smoke：

open project -> compile clean enough for target run -> launch/play
  -> reach main UI or selected scene
  -> exercise one core UI or gameplay path
  -> capture screenshot/log evidence
  -> summarize issues and performance-relevant observations

APK 模拟器 QA​

Hub Codex 可在 Android emulator 中运行真实 APK 并输出 QA 和性能报告。首版矩阵至少包含：

  • 一个主力分辨率/device profile；
  • 一个受限 profile，例如窄屏、安全区或低性能 profile。

每份 APK QA report 应记录：

  • APK source、version、build id、commit 或 artifact URL；
  • emulator profile、Android version、resolution、CPU/memory 配置；
  • test account、server 和 data setup，禁止记录 secret 原文；
  • install、startup、login、main-flow steps；
  • 覆盖的 gameplay 或 UI paths；
  • screenshots、recordings、logcat path、crash/ANR evidence；
  • performance metrics；
  • bug list，包括 severity、repro steps、owner surface、evidence 和 suggested next action。

首版性能指标：

  • install success 和 app launch success；
  • startup time to first visible screen；
  • login to main UI time；
  • main UI FPS；
  • battle FPS；
  • dumpsys gfxinfo frame stats；
  • dumpsys meminfo memory；
  • loading duration for main scene、battle scene 和 major UI transitions；
  • crash、ANR、black screen、stuck loading 或 fatal logcat patterns。

Bug 分级与闭环​

Bug 处理闭环：

发现问题 -> 取证与去重 -> 定 owner/repo -> 在明确授权范围内创建 Linear Project2 bug 或更新原单
  -> 本轮报告与清理完成 -> 新就绪 bug Backlog 转 Todo
  -> 修复交付 -> 功能复测 -> 人类验收或记录阻塞与未测

此闭环只适用于用户明确授权的 Linear Project2 功能测试，不自动创建其他项目或人类 Plane 任务。严重度决定影响和优先级，不绕过本轮结束前 Backlog 的等待规则；其他 QA/MR 问题仍按其授权范围写入证据或原单。

Severity guidance：

  • P0：无法启动、无法登录、核心玩法阻断、数据完整性风险、支付风险、频繁 crash/ANR。立即记录缺陷与影响；仅明确 publication 指令允许建单。
  • P1：重要功能或 UI 路径不可用、严重性能退化、奖励或状态正确性问题。记录缺陷与影响；不默认创建任务。
  • P2：可见缺陷、体验混乱、中等性能问题、可绕过流程错误。记录当前版本影响并进入报告；是否建单由明确 publication 指令决定。
  • P3：polish、轻微视觉不一致、低风险建议。默认进入报告或体验债务清单。

视觉报告标准​

视觉报告必须 evidence-first，避免只写主观判断。每次报告应包含：

  • 一句话结论：通过、建议接受并跟踪、需要打回、阻塞发布或需要 Producer 决策；
  • 截图或录屏索引，按流程或页面状态分组；
  • annotated issue list；
  • 性能表；
  • owner routing recommendation；
  • 具体 next action：accept、rework、create issue、block 或 monitor。

工具与 Skill 优化​

Hub Codex 可优化：

  • work-package-exe-issue：强化 UI issue DAG、Unity/APK QA evidence 要求。
  • review-project-execution：增加 UI visual QA、Unity smoke、APK QA 检查。
  • ui-design-handoff：补状态矩阵、截图矩阵、视觉基线要求。
  • Hub-local schemas、report validators 和 QA templates。

当前 Hub 已补齐以下执行质量入口：

  • 执行配置：.codex/config.toml 的 danger-full-access / never，不使用权限 profile。
  • quality agent：.codex/agents/project2-quality-codex.toml。
  • UI visual QA skill：.agents/skills/project2-ui-visual-qa。
  • Unity Editor smoke skill：.agents/skills/project2-unity-editor-smoke。
  • APK emulator QA skill：.agents/skills/project2-apk-emulator-qa。
  • UI visual QA report schema：pipeline/ui-visual-qa-report.schema.yaml。
  • Unity smoke report schema：pipeline/unity-smoke-report.schema.yaml。
  • APK emulator QA report schema：pipeline/apk-emulator-qa-report.schema.yaml。
  • QA report validator：pipeline/tools/validate_quality_report.py。
  • QA report index：reports/qa/README.md。
  • frontend Unity smoke report adapter：/Users/wjai/AutoDev/repos/project2/tools/project2_unity_smoke_report.py。
  • frontend APK emulator QA runner：/Users/wjai/AutoDev/repos/project2/tools/project2_apk_emulator_qa.py。

报告验证命令：

python3 pipeline/tools/validate_quality_report.py \
  pipeline/golden-samples/ui-visual-qa-report.yaml \
  pipeline/golden-samples/unity-smoke-report.yaml \
  pipeline/golden-samples/apk-emulator-qa-report.yaml

组件仓库工具和 repo-local skills 需要通过对应 repo 的 branch/MR/evidence 流程修改。可优化项包括：

  • Unity smoke script；
  • UI prefab/page audit；
  • screenshot/recording capture；
  • APK install/run/logcat/perf scripts；
  • emulator scenario scripts；
  • test account/server config loading，禁止提交 secret。

当前 frontend repo 已具备首版命令行工具：

python3 tools/project2_unity_smoke_report.py \
  --agent-report Logs/Project2TestReport/<run>/report.json \
  --frontend-ref <branch-or-commit> \
  --output Logs/Project2Quality/<run>/unity-smoke.yaml

python3 tools/project2_apk_emulator_qa.py \
  --apk <path-to-apk> \
  --package <android-package> \
  --output-root Logs/Project2ApkQa \
  --version <version> \
  --build-id <build-id>

生成后必须使用 Hub validator 校验：

python3 /Users/wjai/AutoDev/hubs/hub-project2/pipeline/tools/validate_quality_report.py \
  <unity-smoke.yaml> <apk-emulator-qa.yaml>

定期运行节奏​

建议默认节奏：

  • 每周一次完整 Unity smoke + APK smoke；
  • 每个 UI MR 跑 focused Unity visual QA；
  • 每个 release candidate APK 跑完整 APK QA + performance report；
  • 每月一次 performance trend report。

固定输出建议：

reports/qa/YYYY-MM-DD-unity-smoke.md
reports/qa/YYYY-MM-DD-apk-emulator-qa.md
reports/qa/YYYY-MM-performance-trend.md

报告可以作为 Hub/docs evidence 或 Plane comment/MR review evidence；大型二进制截图和录屏应放在 runtime artifacts、repo-local report artifacts 或 review surface，不应直接提交到 Hub docs。

Review Boundary​

所有 active repo 的任务 MR 可由所属 principal 在源码审阅与精确 head 外部 CI 通过后按长期授权 合并。review-project-execution 提供独立评审证据，不代签人类最终产品验收。未通过外部 CI 或 CI 不存在时记录无法验证，不通过本地执行补偿，也不制造 CI 通过结论。