企业官网建设流程全解析

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发

本篇指南面向在 FastLED 仓库中承担"测试执行与结果汇报"职责的 AI Agent（以及需要理解这套 CI 测试入口的开发者），系统讲解 test-agent 的角色定位、四步工作流程、uv run test.py全套命令的语义与源码级原理、标准化的通过/失败汇报格式，以及必须遵守的六条关键规则。读完你可以直接复用这套流程跑全量测试、定向调试单个用例、驱动 AVR8JS 仿真器测试，并产出可被其他 Agent 直接消费的测试结论。

角色定位：一个"只测试、不修复"的专职子代理

test-agent 是 FastLED 仓库中定义的专职测试子代理，其定义文件为 .claude/agents/test-agent.md。从该文件的 YAML front-matter 可以看到它的三个关键属性：

• name:test-agent，供.claude工作流按名引用；
• description: "Runs test suite and reports pass/fail status"——它的全部职责就是运行测试套件并汇报通过/失败状态；
• tools / model: 仅授予Bash工具，并使用轻量模型（haiku），意味着它应尽量做"薄"：执行命令、解析输出、格式化汇报，而不承担复杂的代码推理。

配套的工作流接线也印证了这一分工：命令入口 .claude/commands/test.md 明确要求"Use the 'test-agent' sub-agent to execute tests and report results in a clear, actionable format"，技能文件 .claude/skills/test/SKILL.md 则把context: fork与agent: test-agent绑定在一起。也就是说：开发者发起bash test ...，Claude Code 会 fork 出 test-agent 去执行，再由它返回结构化的测试结论。

一个值得强调的边界：test-agent 只汇报问题、不修复问题（"Don't fix issues - only report them (fixing is the job of other agents)"）。这与仓库中其他专职子代理（如 .claude/agents/lint-agent.md、.claude/agents/fix-board-agent.md）形成流水线分工。

四步工作流程

test-agent 的执行过程被固定为四个步骤，任何一次测试任务都应遵循：

1. Parse arguments（解析参数）：理解用户到底要跑什么——全量测试、单个指定测试、仅 C++ 测试，还是带--run的仿真器测试；
2. Run tests（运行测试）：以正确的 flags 执行uv run test.py对应的命令；
3. Analyze results（分析结果）：判定测试是通过还是失败，失败时提取失败测试名称与原因；
4. Report（汇报）：按固定模板输出清晰、可操作的反馈，供用户或上游 Agent 直接使用。

从源码侧看，这四步与 test.py 的主流程一一对应：main()先调用 ci/util/test_args.py 的parse_args()完成参数解析与自动补全（步骤 1）；随后根据参数走 fingerprint 缓存判定、测试调度（步骤 2）；测试结果通过异常与退出码汇聚（步骤 3）；最后由 Agent 按模板汇报（步骤 4）。

常用测试命令速查（含源码级语义）

test-agent 文档规定的核心命令均通过uv run test.py执行。下面逐条给出语义，并补充源码依据与实用建议。

1. 全量测试

uv run test.py

• 不指定任何参数时运行全部测试（C++ 单元测试 + 示例编译测试 + Python 测试）。
• 源码依据：test.py 的main()中，无--unit/--examples/--py且带--full时走RunningProcessGroup并行调度，Python 测试与示例测试并行执行以缩短墙钟时间（见 ci/util/test_runner.py 的RunningProcessGroup用法）。
• 若没有任何指定测试且全部 scope 成功，FingerprintManager会把cpp、examples、python、wasm四个 scope 的指纹标记为成功，下次运行可直接命中缓存（详见 ci/util/fingerprint.py 的save_success/mark_failure）。

2. 仅运行 C++ 测试

uv run test.py --cpp

• 语义等价于--unit --examples（C++ 单元测试 + 示例编译），并抑制 Python 测试（参数定义见 ci/util/test_args.py 中--cpp的 help 文本："Run C++ tests only (equivalent to --unit --examples, suppresses Python tests)"）。
• 如果你只关心库本身的 C++ 单元测试，可以更进一步用uv run test.py --unit。

3. 运行指定测试

uv run test.py TestName

例如文档中给出的xypath（对应 examples/XYPath 示例），也可以传 C++ 单元测试名，甚至可以用多个单词做模糊匹配：

uv run test.py string interner

• 源码依据：parse_args会把nargs="*"收集到的多个单词用空格拼成查询串；若该名称不是ci/tests下已有的 Python 测试，则交给 ci/util/smart_selector.py 的get_best_match_or_prompt()做智能匹配——它对空格、下划线、连字符做归一化，并用 Levenshtein 编辑距离打分，能自动判定你指的是单元测试还是示例，并自动补全--cpp/--unit/--examples等标志。
• 当匹配到的是示例时，会把args.examples置为[匹配名]并开启--cpp；匹配到单元测试时，会把名称转换为 Meson 目标名（如tests/fl/async.cpp→fl_async）。

4. 强制重建/重跑

uv run test.py --no-fingerprint

• 跳过 fingerprint 缓存判定，强制重建并重跑。
• 源码警示：test.py 中--no-fingerprint会把四个 scope 的 change 标志全部置为True，同时把RebuildMode设为NO_CACHE；而仓库的测试指南 agents/docs/testing-commands.md 明确把该 flag 标记为"LAST RESORT ONLY"：它会让构建慢 10～100 倍，只有在怀疑指纹缓存本身损坏（而非构建过期）时才允许使用。若只是怀疑构建过期，应改用--clean。
• 指纹缓存本体在.cache/下，由 ci/util/fingerprint.py 的FingerprintManager管理，check()方法通过比对源文件哈希与上次指纹决定needs_run。

5. 仿真器测试：AVR8JS 与 ESP32 QEMU 的分岔

uv run test.py --run uno Blink

• 这条命令走 AVR8JS 仿真器：由 ci/runners/avr8js_runner.py 负责，先以 fbuild 编译示例固件，再在 Docker 镜像中运行 AVR 仿真器。
• 源码细节：--run的第一个参数是板子名，avr8js_runner目前支持的板子为uno、attiny85、attiny88、nano_every；后续参数是要测试的示例名，若不指定默认测试Test示例。板子到后端（backend）的映射表位于 ci/runners/backends.json。
• 重要差异：ESP32 QEMU 不再有本地 runner。--run esp32s3 ...会走到 test.py 的报错分支——提示你改用 fbuild 的test-emu子命令。具体做法是先暂存配置再仿真（命令与 CI 的qemu_template.yml保持一致）：

# 1. 仅暂存源码与配置（不编译固件） uv run ci/stage_fbuild_project.py \ --board esp32s3 \ --example Blink \ --define FASTLED_ESP32_IS_QEMU \ --build-dir .build/fbuild/esp32s3 # 2. 用 fbuild 仿真（自动下载 Espressif QEMU 二进制） uv run fbuild test-emu \ --emulator qemu \ --environment esp32s3 \ --timeout 120 \ --halt-on-success "Blink setup complete - starting blink loop" \ --halt-on-error "Guru Meditation|abort\\(\\)|Backtrace:|TEST_SUITE_COMPLETE: FAIL|QEMU_LCD_CLOCKLESS_REGISTRATION: FAIL" \ .build/fbuild/esp32s3

这两条 QEMU 命令在 agents/docs/testing-commands.md 的 "QEMU Commands" 一节有完整说明，是 test-agent 文档中--run一句的落地展开。

汇报格式：让结果可直接被机器与上游 Agent 消费

test-agent 的产出必须遵循三种固定模板，保证任何下游都能零成本解析。

全部通过：

✅ TESTS PASSED [X/X] tests passed successfully.

存在失败：

❌ TESTS FAILED Failed tests: - [Test name 1]: [Brief failure reason] - [Test name 2]: [Brief failure reason] Run `uv run test.py` for full details.

未指定具体测试（全量）：

✅ TESTS PASSED Ran all tests - [X/X] passed.

模板要点：通过/失败符号 + 明确的计数[X/X]+ 逐条失败列表（测试名 + 简短原因）+ 复跑指引。测试名必须直接从命令输出中复制（"Report actual test names - copy from output"），不得凭记忆拼写，这样下游 Agent 才能拿这个名字去复现或修复。

六条关键规则

test-agent 文档的 "Key Rules" 是它区别于普通脚本执行者的行为契约，逐条展开如下：

1. Python 命令一律用uv run：绝不裸写python。这与仓库统一环境管理一致——pyproject.toml 定义了ci包的完整依赖集（meson、ninja、pytest、fbuild==2.5.29 等），只有通过uv run才能拿到一致的执行环境。
2. 始终停留在项目根目录：绝不cd到子目录。原因可以从 test.py 开头看到：脚本自身os.chdir(Path(__file__).parent)把工作目录钉在仓库根，且指纹缓存、.build/、src/等全部按根目录相对路径解析，任何目录漂移都会破坏解析。
3. 汇报真实的测试名：从输出复制，不臆造。
4. 简洁但信息充分：用户需要的是可行动的结论（哪些失败、为什么），不是原始日志。
5. 只报告、不修复：修复是其他专职子代理（fix 类 Agent）的工作，test-agent 擅自改动代码会破坏流水线的职责边界。
6. 合理设置超时：长测试套件要给出足够的 timeout。这一点在源码中有量化依据——ci/util/test_runner.py 里默认单进程超时 240 秒、GitHub Actions 环境 600 秒，Python 套件（含 fbuild QEMU 冒烟测试）冷缓存时子进程最长可达 1860 秒，因此顶层看门狗超时被设为_PYTHON_TEST_TIMEOUT + 120秒左右；顺序 debug 构建（带 sanitizer）更是会被放宽到 2700 秒（见 test.py 的超时调整逻辑）。Agent 调用命令时的 shell 超时必须大于这些内部超时，否则会在看门狗兜底前就误杀进程。

失败排查：超时、看门狗与崩溃转储

test-agent 只负责汇报，但当汇报需要足够信息时，理解底层机制能让你给出"简短失败原因"：

• 看门狗双层兜底：test.py 启动两个守护线程——主看门狗在超时后先释放构建锁、dump_thread_stacks()抓线程栈再以退出码 2 强制退出；若主看门狗自身卡死，deadman_timer会在seconds + 60s后无条件os._exit(3)。这意味着"挂死"的测试最终都会留下线程栈证据。
• 崩溃转储提醒：test.py 的_check_crash_dumps()会扫描.gdb_crash/crash_*.txt，发现新的崩溃转储会给出红色醒目提示（可用bash lint清理）。测试若崩溃，内部 crash handler 会先输出栈信息，再叠加外部调试器路径（详见 docs/signal-handler-chaining.md 与 docs/deadlock-detection.md）。
• 快速失败策略：MAX_FAILURES_BEFORE_ABORT = 3——全量模式下失败总数超过 3 即中止（见 ci/util/test_runner.py），避免无效长跑。

进阶参数与构建模式（test-agent 能力边界的完整画像）

虽然 test-agent 文档只列出五条常用命令，但了解 ci/util/test_args.py 中全部参数有助于 Agent 在"解析参数"环节做出正确判断。按用途归类：

参数联动示例（来自 ci/util/test_args.py 的自动补全逻辑）：

• 指定测试名时自动补全--py（Python 测试）或--cpp --unit（C++ 单元测试）；
• 带--examples时自动开启--cpp，并在未显式指定 preset 时自动补--quick；
• --debug-thin与--debug/--build-mode互斥，且仅限 Linux；
• --no-interactive与--interactive互斥，同时传入直接报错退出。

这些联动保证了 Agent 即使只给出最简命令，测试入口也会落到正确的 scope 与构建模式上。

在实际仓库工作流中的接入方式

test-agent 并非孤岛，它被三个层级串联进 FastLED 的 Agent 工作流：

• 命令层：.claude/commands/test.md 定义了test命令，接受[test-name] [--cpp] [--no-fingerprint] [--run platform]等参数，内部直接委托给 test-agent；
• 技能层：.claude/skills/test/SKILL.md 声明agent: test-agent与context: fork，并再次强调"Usebash testwrapper (NEVER barepython)"——注意技能层推荐bash test包装脚本（根目录的 test 脚本内容就是uv run test.py "$@"），与 agent 文档中的uv run test.py直调方式互补：日常交互优先用bash test，Agent 内部精确控制 flags 时用uv run test.py；
• 文档层：agents/docs/testing-commands.md 是 test-agent 命令清单的完整展开，包含"禁止直接调 meson/ninja/clang++"、超时挂死检测、指纹缓存红线、fbuild 默认后端等更细的约束。

结语：一份可复制的测试执行契约

test-agent 的价值不在于"会跑测试"，而在于它把"解析参数 → 执行 → 分析 → 汇报"固化成了一套可被其他 Agent 与 CI 消费的契约：命令有据可查（.claude/agents/test-agent.md + ci/util/test_args.py），行为有规则约束（六条 Key Rules），产出有标准模板（✅/❌ TESTS PASSED/FAILED+[X/X]计数）。无论你是手工执行uv run test.py，还是让 Claude Code fork 出 test-agent 代跑，这套契约都能确保测试结论清晰、准确、可行动。

• 嵌入式
• 物联网
• 硬件开发
• 驱动开发