Flameox

flameox

为编码 Agent 提供有界的本地运行时证据。

Flameox 协调分析器、基准测试工具、跟踪处理器和直接本地目标。它将明确指定的产物或命令转化为有界证据，同时将持久化保留设为可选。Agent 选择假设和实验；Flameox 记录观测到的输入、执行来源、类型化证据、覆盖范围和局限性。

无需初始化工作区或维护项目配置。分析时传入确切的产物路径，采集时传入明确的 argv 和绝对工作目录。Flameox 不会搜索父目录、编辑项目文件或提供托管服务。

快速开始

使用全局设置命令配置 MCP 客户端：

npx flameox@latest setup

设置程序会检测受支持的客户端，并询问要更新哪些配置。对于自动化场景，请明确选择客户端，例如 --client codex --yes 或 --all --yes；--dry-run 会报告路径和操作，但不会写入任何内容。设置程序会保留客户端配置中的无关内容，也不会更改项目文件。详情请参阅 npm 包指南。

使用以下命令更新现有 MCP 注册：

npx flameox@latest update

update --check 会报告可用更新，但不会更改配置。更新会保留各客户端的提供方扩展项和设置，在更改版本固定项之前验证新环境，并报告哪些客户端需要重启或重新连接。使用 --client codex 选择单个客户端，或使用 --version 0.2.8 选择特定版本，也可用于回滚。Python CLI 提供相同的 flameox update 命令。

若要直接使用 CLI，请传入确切的产物路径或明确的命令：

uvx flameox analyze preview_artifact /absolute/path/to/artifact.json
uvx flameox capture --provider direct --cwd "$PWD" -- python benchmark.py

若要手动启动 stdio MCP 服务：

uvx flameox mcp serve

若要进行本地开发，请克隆仓库、安装开发依赖，并查看可用工具：

git clone https://github.com/morluto/flameox.git
cd flameox
uv sync --extra dev --extra memory --extra trace --extra cpu
uv run flameox mcp inspect

证据与存储

分析和未保留的采集使用有界会话临时空间。会话 analysis_id 会在被逐出或服务停止时过期。显式保留会创建用户级 Flameox 数据目录，并按 SHA-256 存储原生字节和规范化证据包。设置 FLAMEOX_DATA_DIR 可选择其他位置。保留是可选的；它不代表会完整保留控制台输出。

Flameox 区分观测所得、派生和推断的结论。性能分析结果有助于探索，但不能证明因果关系或性能提升。确认性结论需要具有代表性的工作负载、声明的指标和估计目标、兼容的身份信息、保留的样本以及语义判定器。

MCP

MCP 服务不绑定工作区。它通过与 CLI 相同的操作注册表提供命名的分析和采集工具。分析工具接受明确的来源；采集工具接受类型化目标和提供方。工具架构会直接公开特定操作的字段。使用 flameox mcp inspect 查看目录；使用 --tool TOOL_NAME 查看指定工具的架构和示例。完整契约和当前工具目录请参阅接口指南。

工具会以内联方式返回其完整的有界结果，包括失败和恢复操作。保留的证据具有持久的 evidence_id；inspect_evidence 会以内联方式返回其经过脱敏的元数据和重放来源。

采集接受 argv，而不是 shell 字符串。直接目标需要提供绝对工作目录和有界环境变量覆盖项。结果可能包含 next_page；请原样重放其中指定的分析工具和参数。采集续页会读取已收集的产物，不会重新运行目标。MCP 工作属于当前请求，因此取消操作会直接生效，重启后也不会遗留脱离请求的任务。

文档

• 架构介绍进程和包的边界。
• 存储与证据定义保存和来源追溯。
• 调查涵盖实验、比较和证据质量。
• 适配器介绍提供方兼容性和集成策略。
• 运行时安全涵盖限制、恢复、完整性和隐私。
• 接口定义 CLI 和 MCP 契约。
• 测试介绍测试选择和已知的验证缺口。

开发

Flameox 要求使用 Python 3.12 或更高版本，并使用已提交的 uv.lock。有关开发环境设置和贡献指南，请参阅 CONTRIBUTING.md。

uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run mypy src tests tools
uv run pytest -q

Flameox 根据 MIT 许可证授权。