尧图网站建设 
Perfetto Agent Skill 环境初始化$SKILL_ROOT 与内置 trace_processor 的一次性配置【免费下载链接】perfettoProduction-grade client-side tracing, profiling, and analysis for complex software systems.项目地址: https://gitcode.com/GitHub_Trending/pe/perfetto本文基于 Perfetto 仓库中 AI skill 的 setup 环境参考文档setup.md讲解在为编码 Agent 配置 Perfetto 分析能力时每个会话需要完成的两个一次性设置定义$SKILL_ROOT绝对路径、把 skill 内置的trace_processor包装器接入PATH。读完本文你可以独立完成 skill 环境初始化理解首次调用时预构建二进制的下载与缓存机制源码见 perfetto_prebuilts.py并掌握 Windows 平台与环境自带trace_processor时的处理规则。1. setup.md 在 skill 中的定位Perfetto 的 Agent skillai/skills/perfetto/教会编码 Agent 如何录制和分析 Perfetto trace。它由一个路由文件SKILL.md、查询参考、录制指南和若干带脚本的分析工作流组成整体结构说明见 skills README。在这套体系中有两样东西是“每个会话设置一次”的$SKILL_ROOT环境变量trace_processor命令的可执行性。setup.md 的定位很明确它不是主路由SKILL.md的 Setup 一节重复了这些步骤而是供工作流文件指针对的权威参考——原文的表述是“(SKILL.mdrepeats this; it is here so workflow files have something to point at.)”。例如查询参考 querying.md 开篇就要求trace_processor必须在PATH上并把读者指到$SKILL_ROOT/environment-references/setup.md。2.$SKILL_ROOT把 skill 内所有引用锚定为绝对路径原文档对$SKILL_ROOT的定义是包含本 skill 的SKILL.md的目录的绝对路径。skill 中引用的每个文件都写成$SKILL_ROOT/path绝不允许相对于引用它的文件来写相对路径。为什么必须用绝对路径skills README 给出了解释skill 是从插件目录plugin directory加载的而不是从用户的工作区加载的。如果各文件内部使用相对路径会解析到错误的位置因此路由文件要求 Agent 在会话开始时把$SKILL_ROOT设置一次之后所有 skill 资产都以它为锚点。这与 SKILL-template.md 中 “every path below is written relative to it” 的约定一致。需要说明的一个仓库事实源码树里并没有SKILL.md而是 SKILL-template.md。skills README 说明了原因源码树是构建输入而非成品模板命名是为了避免 skill 加载器扫描到未打包的源文件。发布时 build_ai_agents.py 会把模板重命名为SKILL.md并把 tools/trace_processor 复制为bin/trace_processor加上各 Agent 的清单文件写入每个 release 的ai-agents分支——用户安装的就是那个分支里的成品。所以在已安装的 skill 中bin/trace_processor就位于$SKILL_ROOT/bin/下setup.md 中引用的$SKILL_ROOT/bin/trace_processor由此而来。想在本仓库本地复现同样的打包可用 ai/evals/setup_assets.py它以与发布流水线相同的方式把ai/skills/组装到仓库外目录。3. 内置 trace_processor四条命令完成初始化原文档给出的初始化命令完整如下这是 skill 内置流程的原始片段保持可复制export SKILL_ROOT/absolute/path/to/skills/perfetto chmod x $SKILL_ROOT/bin/trace_processor # some installs lose the exec bit export PATH$SKILL_ROOT/bin:$PATH trace_processor --version # smoke test逐行说明命令作用export SKILL_ROOT...将绝对路径写入环境变量后续所有 skill 文件引用都以它为基准chmod x ...补齐可执行位。注释明确说明动机某些安装方式会丢失 exec 位export PATH...把 skill 的bin/目录前置到PATH使trace_processor作为裸命令可直接调用trace_processor --version冒烟测试验证包装器可运行并顺带触发首次下载这里的bin/trace_processor并不是一个二进制而是一个自包含的 Python 包装器仓库中的 tools/trace_processor 即其源文件文件头注明由tools/gen_amalgamated_python_tools自动生成。它被设计为在任何调用方式下行为一致见 tools/trace_processor 的注释./trace_processor python trace_processor bash trace_processor cat ./trace_processor | bash cat ./trace_processor | python -这种“单文件可搬运”的设计正是 skill 能把整个工具链装进bin/目录随插件分发的原因。4. 首次调用发生了什么预构建二进制的下载与缓存原文档写道第一次调用会把宿主平台对应的预构建二进制下载到~/.local/share/perfetto/prebuilts/并缓存之后调用即命中缓存。这一点可以从包装器的实现得到完整印证核心逻辑在 perfetto_prebuilts.py平台匹配。get_perfetto_prebuilt()先读取sys.platform与platform.machine()在清单manifest中找到platform和machine都匹配的条目找不到就报错提示无可用预构建。清单本身内嵌在包装器里——tools/trace_processor 中的TRACE_PROCESSOR_SHELL_MANIFEST由tools/release/roll-prebuilts生成当前仓库版本固定为v58.2覆盖以下组合架构键平台CPUmac-amd64/mac-arm64darwinx86_64 / arm64linux-amd64/linux-arm/linux-arm64linuxx86_64 / armv6l~armv8l / aarch64android-arm/android-arm64/android-x86/android-x64Android 预构建供显式指定 arch 时匹配arm / arm64 / x86 / x64windows-amd64win32amd64每个条目都带url、file_size和sha256下载来源是 Perfetto 官方制品存储。下载与校验。download_or_get_cached()的具体行为缓存目录为~/.local/share/perfetto/prebuilts/文件名格式为$tool_name-$sha256前16位[扩展名]保留.exe等扩展名。SHA 前缀嵌入文件名是为了让同一工具的不同版本可以共存——例如两个 virtualenv 固定了不同的 Perfetto release 时互不覆盖若按 SHA 命名的文件已存在直接复用。因为该文件只会在 SHA-256 校验通过后经原子重命名产生所以无需每次重新计算哈希首次下载使用curl -f -L -#写入随机后缀的.tmp临时文件随机后缀用于防护并发执行时的竞争然后计算实际 SHA-256 与清单比对不匹配立即抛异常校验通过后chmod 0o755并os.replace()原子落盘。接管进程。run_perfetto_prebuilt()在非 Windows 平台上用os.execv()直接以真实二进制替换当前进程参数原样透传在 Windows 上改用subprocess.check_call并传播退出码。因此对 Agent 来说包装器透明trace_processor --version、trace_processor server unix ...等所有子命令都由缓存里的trace_processor_shell执行。5. 版本锁定为什么不要单独下载 trace_processor原文档明确告诫不要单独下载trace_processor因为包装器“被固定到 skill 所构建的那个 release”the wrapper is pinned to the release the skill was built for。从源码结构看这一锁定的实现方式就是清单内嵌manifest 直接写死在包装器文件里当前为 v58.2 的 URL 与 SHA-256而不是运行时向远端查询最新版本。这样做的工程意义在于skill 各工作流中携带的 SQL 查询与脚本如 workflows/android_memory/、workflows/gpu/ 下的scripts/是面向特定版本的 PerfettoSQL 标准库编写的如果 Agent 自行安装了别的trace_processor表结构或模块行为可能与 skill 的预期漂移查询结果不可复现。仓库的 evals 隔离机制 同样体现了这一点评估时特意向 Agent 隐藏本地构建和预构建缓存就是为了防止它“捡到”一个与条件不符的二进制。6. Windows 处理与环境自带 trace_processor 的覆盖规则原文档列出两条覆盖规则Windows。跳过PATH设置步骤直接以python $SKILL_ROOT/bin/trace_processor ...方式调用。这与第 3 节包装器的多调用方式设计吻合python trace_processor是官方支持的调用形态之一而清单中windows-amd64条目的文件名带.exe、且run_perfetto_prebuilt()在 win32 上走subprocess而非execv都说明 Windows 路径是被专门设计过的。环境自带工具优先。如果运行环境本身就强制提供trace_processor原文列举的场景Google internal、OEM build environments、CI images应优先采用该团队专属的配置而不是 skill 的包装器。这是“宿主环境约定高于 skill 默认值”的让位规则。7. setup 完成之后的下一步一次性设置完成trace_processor --version能正常输出后skill 的实际使用模式在 querying.md 中展开对大型 trace先用trace_processor server unix --name session --daemonize TRACE_FILE建立后台会话再用query --remote反复查询避免每次调用重复解析。各具体领域Android 内存、GPU 等则走 workflows/ 下的 runbook每个工作流自带 SQL/Python 脚本。setup 阶段要做的只有本文所述的三件事锚定$SKILL_ROOT、保证bin/trace_processor可执行并在PATH上、跑一次--version冒烟测试。要点回顾$SKILL_ROOT以绝对路径解决“skill 从插件目录加载、相对路径会解析错位置”的问题bin/trace_processor是内嵌平台清单当前 v58.2的自包含包装器首次调用时下载并 SHA-256 校验预构建二进制缓存在~/.local/share/perfetto/prebuilts/并以 SHA 前缀命名实现多版本共存版本锁定保证了 skill 查询与引擎版本一致Windows 用python显式调用团队环境自带工具时则让位于宿主约定。【免费下载链接】perfettoProduction-grade client-side tracing, profiling, and analysis for complex software systems.项目地址: https://gitcode.com/GitHub_Trending/pe/perfetto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Perfetto Agent Skill 环境初始化：$SKILL_ROOT 与内置 trace_processor 的一次性配置
Perfetto Agent Skill 环境初始化$SKILL_ROOT 与内置 trace_processor 的一次性配置【免费下载链接】perfettoProduction-grade client-side tracing, profiling, and analysis for complex software systems.项目地址: https://gitcode.com/GitHub_Trending/pe/perfetto本文基于 Perfetto 仓库中 AI skill 的 setup 环境参考文档setup.md讲解在为编码 Agent 配置 Perfetto 分析能力时每个会话需要完成的两个一次性设置定义$SKILL_ROOT绝对路径、把 skill 内置的trace_processor包装器接入PATH。读完本文你可以独立完成 skill 环境初始化理解首次调用时预构建二进制的下载与缓存机制源码见 perfetto_prebuilts.py并掌握 Windows 平台与环境自带trace_processor时的处理规则。1. setup.md 在 skill 中的定位Perfetto 的 Agent skillai/skills/perfetto/教会编码 Agent 如何录制和分析 Perfetto trace。它由一个路由文件SKILL.md、查询参考、录制指南和若干带脚本的分析工作流组成整体结构说明见 skills README。在这套体系中有两样东西是“每个会话设置一次”的$SKILL_ROOT环境变量trace_processor命令的可执行性。setup.md 的定位很明确它不是主路由SKILL.md的 Setup 一节重复了这些步骤而是供工作流文件指针对的权威参考——原文的表述是“(SKILL.mdrepeats this; it is here so workflow files have something to point at.)”。例如查询参考 querying.md 开篇就要求trace_processor必须在PATH上并把读者指到$SKILL_ROOT/environment-references/setup.md。2.$SKILL_ROOT把 skill 内所有引用锚定为绝对路径原文档对$SKILL_ROOT的定义是包含本 skill 的SKILL.md的目录的绝对路径。skill 中引用的每个文件都写成$SKILL_ROOT/path绝不允许相对于引用它的文件来写相对路径。为什么必须用绝对路径skills README 给出了解释skill 是从插件目录plugin directory加载的而不是从用户的工作区加载的。如果各文件内部使用相对路径会解析到错误的位置因此路由文件要求 Agent 在会话开始时把$SKILL_ROOT设置一次之后所有 skill 资产都以它为锚点。这与 SKILL-template.md 中 “every path below is written relative to it” 的约定一致。需要说明的一个仓库事实源码树里并没有SKILL.md而是 SKILL-template.md。skills README 说明了原因源码树是构建输入而非成品模板命名是为了避免 skill 加载器扫描到未打包的源文件。发布时 build_ai_agents.py 会把模板重命名为SKILL.md并把 tools/trace_processor 复制为bin/trace_processor加上各 Agent 的清单文件写入每个 release 的ai-agents分支——用户安装的就是那个分支里的成品。所以在已安装的 skill 中bin/trace_processor就位于$SKILL_ROOT/bin/下setup.md 中引用的$SKILL_ROOT/bin/trace_processor由此而来。想在本仓库本地复现同样的打包可用 ai/evals/setup_assets.py它以与发布流水线相同的方式把ai/skills/组装到仓库外目录。3. 内置 trace_processor四条命令完成初始化原文档给出的初始化命令完整如下这是 skill 内置流程的原始片段保持可复制export SKILL_ROOT/absolute/path/to/skills/perfetto chmod x $SKILL_ROOT/bin/trace_processor # some installs lose the exec bit export PATH$SKILL_ROOT/bin:$PATH trace_processor --version # smoke test逐行说明命令作用export SKILL_ROOT...将绝对路径写入环境变量后续所有 skill 文件引用都以它为基准chmod x ...补齐可执行位。注释明确说明动机某些安装方式会丢失 exec 位export PATH...把 skill 的bin/目录前置到PATH使trace_processor作为裸命令可直接调用trace_processor --version冒烟测试验证包装器可运行并顺带触发首次下载这里的bin/trace_processor并不是一个二进制而是一个自包含的 Python 包装器仓库中的 tools/trace_processor 即其源文件文件头注明由tools/gen_amalgamated_python_tools自动生成。它被设计为在任何调用方式下行为一致见 tools/trace_processor 的注释./trace_processor python trace_processor bash trace_processor cat ./trace_processor | bash cat ./trace_processor | python -这种“单文件可搬运”的设计正是 skill 能把整个工具链装进bin/目录随插件分发的原因。4. 首次调用发生了什么预构建二进制的下载与缓存原文档写道第一次调用会把宿主平台对应的预构建二进制下载到~/.local/share/perfetto/prebuilts/并缓存之后调用即命中缓存。这一点可以从包装器的实现得到完整印证核心逻辑在 perfetto_prebuilts.py平台匹配。get_perfetto_prebuilt()先读取sys.platform与platform.machine()在清单manifest中找到platform和machine都匹配的条目找不到就报错提示无可用预构建。清单本身内嵌在包装器里——tools/trace_processor 中的TRACE_PROCESSOR_SHELL_MANIFEST由tools/release/roll-prebuilts生成当前仓库版本固定为v58.2覆盖以下组合架构键平台CPUmac-amd64/mac-arm64darwinx86_64 / arm64linux-amd64/linux-arm/linux-arm64linuxx86_64 / armv6l~armv8l / aarch64android-arm/android-arm64/android-x86/android-x64Android 预构建供显式指定 arch 时匹配arm / arm64 / x86 / x64windows-amd64win32amd64每个条目都带url、file_size和sha256下载来源是 Perfetto 官方制品存储。下载与校验。download_or_get_cached()的具体行为缓存目录为~/.local/share/perfetto/prebuilts/文件名格式为$tool_name-$sha256前16位[扩展名]保留.exe等扩展名。SHA 前缀嵌入文件名是为了让同一工具的不同版本可以共存——例如两个 virtualenv 固定了不同的 Perfetto release 时互不覆盖若按 SHA 命名的文件已存在直接复用。因为该文件只会在 SHA-256 校验通过后经原子重命名产生所以无需每次重新计算哈希首次下载使用curl -f -L -#写入随机后缀的.tmp临时文件随机后缀用于防护并发执行时的竞争然后计算实际 SHA-256 与清单比对不匹配立即抛异常校验通过后chmod 0o755并os.replace()原子落盘。接管进程。run_perfetto_prebuilt()在非 Windows 平台上用os.execv()直接以真实二进制替换当前进程参数原样透传在 Windows 上改用subprocess.check_call并传播退出码。因此对 Agent 来说包装器透明trace_processor --version、trace_processor server unix ...等所有子命令都由缓存里的trace_processor_shell执行。5. 版本锁定为什么不要单独下载 trace_processor原文档明确告诫不要单独下载trace_processor因为包装器“被固定到 skill 所构建的那个 release”the wrapper is pinned to the release the skill was built for。从源码结构看这一锁定的实现方式就是清单内嵌manifest 直接写死在包装器文件里当前为 v58.2 的 URL 与 SHA-256而不是运行时向远端查询最新版本。这样做的工程意义在于skill 各工作流中携带的 SQL 查询与脚本如 workflows/android_memory/、workflows/gpu/ 下的scripts/是面向特定版本的 PerfettoSQL 标准库编写的如果 Agent 自行安装了别的trace_processor表结构或模块行为可能与 skill 的预期漂移查询结果不可复现。仓库的 evals 隔离机制 同样体现了这一点评估时特意向 Agent 隐藏本地构建和预构建缓存就是为了防止它“捡到”一个与条件不符的二进制。6. Windows 处理与环境自带 trace_processor 的覆盖规则原文档列出两条覆盖规则Windows。跳过PATH设置步骤直接以python $SKILL_ROOT/bin/trace_processor ...方式调用。这与第 3 节包装器的多调用方式设计吻合python trace_processor是官方支持的调用形态之一而清单中windows-amd64条目的文件名带.exe、且run_perfetto_prebuilt()在 win32 上走subprocess而非execv都说明 Windows 路径是被专门设计过的。环境自带工具优先。如果运行环境本身就强制提供trace_processor原文列举的场景Google internal、OEM build environments、CI images应优先采用该团队专属的配置而不是 skill 的包装器。这是“宿主环境约定高于 skill 默认值”的让位规则。7. setup 完成之后的下一步一次性设置完成trace_processor --version能正常输出后skill 的实际使用模式在 querying.md 中展开对大型 trace先用trace_processor server unix --name session --daemonize TRACE_FILE建立后台会话再用query --remote反复查询避免每次调用重复解析。各具体领域Android 内存、GPU 等则走 workflows/ 下的 runbook每个工作流自带 SQL/Python 脚本。setup 阶段要做的只有本文所述的三件事锚定$SKILL_ROOT、保证bin/trace_processor可执行并在PATH上、跑一次--version冒烟测试。要点回顾$SKILL_ROOT以绝对路径解决“skill 从插件目录加载、相对路径会解析错位置”的问题bin/trace_processor是内嵌平台清单当前 v58.2的自包含包装器首次调用时下载并 SHA-256 校验预构建二进制缓存在~/.local/share/perfetto/prebuilts/并以 SHA 前缀命名实现多版本共存版本锁定保证了 skill 查询与引擎版本一致Windows 用python显式调用团队环境自带工具时则让位于宿主约定。【免费下载链接】perfettoProduction-grade client-side tracing, profiling, and analysis for complex software systems.项目地址: https://gitcode.com/GitHub_Trending/pe/perfetto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考