面向编码代理的本地运行时证据层，用于调查性能、内存、执行、并发和可靠性问题。
Language / 语言: English | 简体中文
Flameox 协调受支持的性能分析器、基准测试工具和 trace 处理器，保留它们的原生产物及来源信息，并向代理提供有边界的证据。代理说明要验证的内容；Flameox 记录测量结果，并保留实验记录供复核。 ## 快速开始 使用引导式安装流程接入受支持的 MCP 客户端： ```console npx flameox@latest setup ``` 重启客户端，打开要检查的项目，然后询问它： > 在此项目中初始化 Flameox，并列出可用的性能分析能力。 `setup` 命令会安装一个有版本号的本地运行时，并且只修改已批准的客户端配置。项目初始化是独立步骤：只有客户端针对固定的项目根目录调用初始化工作流后，才会创建 `.diagnostics/`。 如果要进行源码开发： ```console uv sync --extra dev uv run flameox init . uv run flameox status ``` 需要 Python 3.12 或更高版本，以及仓库中提交的 `uv.lock`。 ## 调查流程 ```text 症状 → 采集或导入 → 有边界的证据 → 假设 → 区分假设的实验 → 支持、反驳或无法定论的结论 ``` 常见证据来源包括 pyperf、py-spy、pytest-reportlog、coverage.py、Memray、Perfetto、torch.profiler、Nsight Systems、Nsight Compute、ROCprofiler、Compute Sanitizer、NVBench，以及类型化的推理提供商导出结果。实际可用性取决于主机、权限、已安装的可选依赖（extra）和所选适配器（adapter）。如果缺少证据，Flameox 会明确报告，而不是静默换用更弱的来源。 性能分析结果适合探索。要得出性能或正确性结论，还需要具代表性的工作负载、声明过的指标和估计对象（estimand）、兼容的运行身份、保留的样本，以及合适的语义 oracle。 ## 命名工作负载 命令以参数数组的形式写在 `flameox.toml` 中。参数只能声明为标量；Flameox 不执行 shell 展开。 ```toml schema_version = 1 [workloads.scan] argv = ["python", "bench.py", "--implementation", "{implementation}"] cwd = "." timeout_seconds = 60 [workloads.scan.parameters] implementation = ["baseline", "candidate"] [workloads.scan.oracle] strength = "cross_treatment_equivalence" argv = ["python", "validate.py", "--implementation", "{implementation}"] [experiments.scan_comparison] workload = "scan" design = "randomized_complete_blocks" blocks = 10 treatment_factor = "implementation" combination_policy = "cartesian" primary_metric = "pyperf.workload" polarity = "lower_is_better" estimand = "median_paired_log_ratio" practical_threshold = 0.05 confidence_level = 0.95 random_seed = 1984 [experiments.scan_comparison.factors] implementation = ["baseline", "candidate"] ``` MCP 的 `configure_workload` 工具会校验并写入规范定义，但不会执行命令。手动编写的有效定义会立即生效；不存在审批副本或第二份工作负载注册表。 ```console uv run flameox workload show scan --json uv run flameox capture plan pyperf --workload scan \ --parameters '{"implementation":"baseline"}' --json uv run flameox capture run pyperf --workload scan \ --parameters '{"implementation":"baseline"}' --json ``` 规划阶段会为每个可执行文件解析一次。生成的绑定（binding）包含确切的调用路径、规范化目标、信任决策和文件身份。执行阶段会重新校验该绑定，而不是再次搜索 `PATH`。计划是短期、一次性的能力；完整意图会保存在工作区的 SQLite 控制平面中。 ## 实验与分析 ```console uv run flameox investigations create \ '{"question":"Does the candidate remove reverse-scan overhead?"}' --json uv run flameox hypotheses record @hypothesis.json --json uv run flameox experiment plan scan_comparison \ --investigation