xfqtrace-skills 0.1.3

Agent skills and xfq CLI for private xfQTrace kits

xfqtrace-skills（技能仓库）

用于私有 xfQTrace kit 的 xfq CLI 和智能体技能。

安装

pipx install xfqtrace-skills

首次使用

# xfqtrace-kit zip 和密码请进入 x1a0f3n9 知识星球自取，公开 pip 包不内置私有 kit
xfq init ./xfqtrace-kit-<version>.zip -p <password>
# Windows 如果不想把 kit 放 C 盘，可以指定:
# xfq init ./xfqtrace-kit-<version>.zip -p <password> --dir D:\xfqtrace
xfq doctor --serial <device-serial>
xfq run test --serial <device-serial>                # 默认 xfinject；lite kit 需要设备已预装 com.shopee.vn

可选：

xfq set auto-update-check off
xfq run test --serial <device-serial> --inject-backend frida-server

常用命令

命令	作用
xfq paths	查看 kit 安装目录、配置文件路径
xfq doctor --serial <device>	只检查环境，不做清理
xfq doctor --serial <device> --install-kpm --kpm-superkey <key>	检查并按需加载 kit/bin/xfvmahide.kpm
xfq run test --serial <device> --dry-run	用当前真实 kit 检查将执行的命令；lite kit 不含 APK，Shopee 需预装
xfq clean --traces -y	清理本机 kit/examples 下的 trace/logcat 产物
xfq clean --all-versions -y	删除非当前版本的旧 kit
xfq update	更新 xfqtrace-skills 包并刷新技能
xfq skill install --target both --force	安装/刷新技能

安装目录

kit 安装在用户数据目录。Linux/macOS 默认走 XDG 风格目录，Windows 默认走 %LOCALAPPDATA%。具体以 xfq paths 实际输出为准。

$HOME/.local/share/xfqtrace/versions/<version>/   # Linux/macOS
%LOCALAPPDATA%/xfqtrace/versions/<version>/        # Windows

Windows 想改到 D 盘：

xfq init .\xfqtrace-kit-<version>.zip -p <password> --dir D:\xfqtrace

技能目录不受 --dir 影响，仍然是用户目录下的 .codex/skills / .claude/skills。

关于 Shopee smoke

当前默认发布的是 lite kit，不内置 Shopee APK。xfq run test 仍然指向 com.shopee.vn 的 smoke 脚本，但要求设备上已经预装对应 app；只有 full kit 或手动放入 APK/XAPK 时，xfq run 才可能自动安装 APK。

智能体技能

xfq skill install --target both
xfq skill status

查看日志

xfq run 会把本轮产物放到：

<kit>/examples/<package>/xfqtrace_logs/<N>/

控制台会打印 Session dir 和最终 Output。重点看：

sed -n '1,200p' <output>/logcat.txt
cat <output>/crash_summary.txt
ls <output>/*.log.lz4

实时看设备日志：

adb -s <device-serial> logcat -v threadtime -s xfQTrace

更新

xfq 默认会检查 xfqtrace-skills 更新。检测到 CLI / skill 有新版本时，会提示输入 y/n：

• 输入 y：自动更新本地 pip 包，并刷新 Codex / Claude 已安装技能。
• 输入 n：跳过本次更新。

也可以手动执行：

xfq update
xfq update -y

0.1.2 用户建议先升级 CLI，再安装后续新 kit：

xfq update -y
xfq version

发布私有 kit 新版本时，公开 pip 包仍不包含 kit、APK、辅助脚本或密码。用户流程是先从知识星球下载 zip，再安装/覆盖当前 kit：

xfq init ./xfqtrace-kit-2.1.zip -p <password> --force
xfq doctor --serial <device-serial>
xfq run test --serial <device-serial> --dry-run

发布顺序应保持：先发布兼容新布局的 xfqtrace-skills，更新通道先只放 cli_version、不要提前放新 kit；等 PyPI 上能安装新 CLI 后，再把更新通道里的 latest_bundle_version 改到新 kit 版本。这样旧用户会先升级 CLI，不会拿老 CLI 去装新布局 kit。

kit/bin 工具检查

xfq init 会显示 kit/bin 里的工具状态；xfq doctor --json 里也有 bundle.bundled_tools 和 bundle.artifact_versions：

• 必须：libxfqtrace.so、xfinjectd
• 建议：lz4、lz4.exe、pidcat、pidcat.exe、7z、7z.exe
• 可选：xfvmahide.kpm

bundle.artifact_versions 会尽量从本地文件里读出 libxfqtrace.so 的 banner/version，以及 xfinjectd 的 Go build info / git revision；这只做本地静态识别，不会执行 Android 二进制。

默认后端是 xfinject，所以 kit 里缺 bin/xfinjectd 就不是“可选缺失”，而是这个 kit 不能正常跑默认链路，需要重新获取/安装完整 kit。

xj3 / frida-server 不打包进 kit。选择 --inject-backend frida-server 时，推荐设备侧 server 为 16.5.7，Python 侧推荐 frida==16.2.1、frida-tools==12.0.0。

样本反馈

如果一个样本跑不通，按最小材料格式反馈。尽量包含：

apk: <package / version / source>
json: <recipe.json or CONFIG snippet>
target: libxxx.so!0xoffset
sig: <optional JNI/RegisterNatives name/signature>
steps: <trigger steps + whether clear data/login needed>
backend: <xfinject | frida-server>
logs: <logcat/crash/trace dir>

sig 是 Java native 方法签名，例如 (Landroid/content/Context;Ljava/lang/String;)Ljava/lang/String;。