iFixAi 快速入门：先看演示，再审计自己的 Agent

这是什么？适合谁？

iFixAi 是面向 Agent 业务行为的审计工具。 它把角色、工具和业务规则放进模拟环境，向被测 Agent 发出请求，再由裁判评价回答。 重点不只是回答是否通顺，而是是否越权、泄露数据、隐瞒失败或偏离业务意图。

适合维护客服、运营与内部工具 Agent 的开发者，以及需要保留回归证据的测试团队。 如果你只有普通聊天账号、无法提供可测试端点，先体验内置演示即可。 它不是给产品颁发安全认证的机构，也不保证通过检查就不存在漏洞。

前置条件与安全边界

• Python 3.10 或更新版本；先确认实际运行的解释器，而不是只看系统里有没有 Python。
• 演示无需 API key，真实运行需要目标端点及裁判模型的相应凭据。
• 使用自己拥有或得到明确授权的测试环境，不能对第三方产品随意开展探测。
• 准备脱敏的业务角色与权限说明，不把客户真实记录作为默认样本。
• 真实探针会发出真实请求；测试端点必须隔离退款、付款、删库等副作用。
• 阅读模型供应商的数据处理政策；“本机 CLI”不代表所有评审数据都留在本机。

安装与第一个任务

1. 建一个独立环境

以下命令用于 macOS / Linux 的终端：

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install ifixai

Windows 使用 Python Launcher 创建环境，再在对应终端激活：

py -m venv .venv
.venv\Scripts\activate
python -m pip install ifixai

这里的激活命令适用于 cmd；PowerShell 应使用该环境的 Activate.ps1。 不要为了激活环境而全局关闭执行策略；也可以直接用虚拟环境内的 Python。

2. 生成并检查参考环境

ifixai author reference -o reference.yaml
ifixai validate reference.yaml

reference 是项目提供的虚构金融科技客服 Agent 示例。 author 生成模拟环境文件，validate 检查其结构与约束。 先读 reference.yaml，理解谁能执行什么动作，再进入运行步骤。

3. 只跑无凭据演示

ifixai run --provider mock --eval-mode self --fixture reference.yaml

这条命令使用预设回答和预设评判，不是在向独立裁判请求真实评价。 首次成功判据是终端出现逐项结果，并在 ./ifixai-results/ 看到报告。 报告应能找到检查项目、请求与回答等证据结构，而不是只剩一个字母等级。

默认运行覆盖 10 项检查；核验日 README 的 --full-run 覆盖 61 项检查。 完整集合中不适用的项目会被提前排除并说明原因，不能把排除当作通过。 演示的通过率不能放进产品介绍中充当自己的 Agent 已接受审计的证据。

初级用法：连接自己的测试 Agent

先从官方参考 profile 复制并编辑 my-agent.json。 文件应真实描述测试 Agent 的角色、业务规则与工具权限，不要把希望它做到的事写成已经具备的能力。 参考结构见官方 环境编写文档。

下面以 OpenAI 裁判依赖为例：

python -m pip install "ifixai[openai]"
ifixai author my-agent.json -o my-agent.yaml
ifixai validate my-agent.yaml
ifixai setup

向导配置目标端点、裁判和套件，保存到 ifixai.yaml。 真实审计会从已有密钥中选择不同于目标 Agent 供应商的裁判。 若目标自身也来自 OpenAI，应配置另一个受支持厂商，而不是照搬示例认定符合独立性要求。

凭据通过安全的本地环境管理方式注入，不要写入 profile、命令分享截图或 Git。 确认 AGENT_API_KEY 已在当前进程环境中设置，再先查看计划：

ifixai run --fixture ./my-agent.yaml --api-key "$AGENT_API_KEY" --dry-run

检查测试数量、裁判调用和不适用项；获得预算及测试范围确认后才运行：

ifixai run --fixture ./my-agent.yaml --api-key "$AGENT_API_KEY"

这些是 POSIX shell 的环境变量语法；Windows 用户应按当前 shell 的语法传入值。 不要把开发环境中无认证的示例照搬成生产端点配置。

高级玩法

1. 用 full-run 扩大检查面

在测试副本上给既有运行命令添加 --full-run，先加 --dry-run 查看范围变化。 逐个审阅被排除的检查及原因，判断是合理不适用，还是 profile 少写了工具或权限。 扩大集合也意味着更多调用和潜在副作用，不应跳过预算确认。

2. 把报告用于 CI 回归

官方提供 JSON、Markdown 报告与 --min-score 门槛。 先在人工检查过的测试集上建立基线，再按 CLI 文档配置门槛。 记录 Agent 版本、profile、裁判与套件，避免把不同条件的等级直接比较。 失败构建应该关联具体证据，不应只告诉维护者“字母等级下降”。

3. 从编码助手启动审计

Claude Code 的官方插件安装入口是：

/plugin marketplace add ifixai-ai/iFixAi
/plugin install ifixai@ifixai-community

安装后可请求它运行 iFixAi，先审阅生成环境与费用计划。 插件能帮助编写配置，但不能替你授予目标测试权限，也不能免除真实端点的费用。

4. 对非标准端点编写适配

OpenAI-compatible 端点可以直接接入，其他接口按官方 testing-your-agent.md 编写 Python 适配。 先让适配器在隔离测试副本中处理一条脱敏请求，再扩大探针集合。 把认证失败、超时和业务拒绝分开记录，否则评判结果可能只是在测适配器错误。

小技巧

1. 先用 validate 发现配置问题，再排查模型结果；结构错误不应靠增加推理预算解决。
2. 每次运行保留独立报告目录或归档副本，避免把两个版本的结果混在一起。
3. 把默认 10 项当作起点，不把它理解为对全部业务权限的完整覆盖。
4. 阅读 B01、B08、P01 的失败证据；这些最低要求失败时等级会被封顶到 D。
5. 从单一角色与单一业务流程开始，再扩展到多租户和多角色边界。
6. 共享报告前再检查一遍请求、回答与端点信息，报告也可能含机密。

常见踩坑

以下是依据官方操作机制推导的风险，不是本站实测经历。

1. 演示全通过，就认为自己的系统安全

现象：拿 mock 报告当上线依据。 原因：mock 使用 canned replies 和 canned grades，没有测试自己的真实 Agent。 解决：把演示仅用于理解报告，再在授权测试端点上使用真实裁判。

2. 找不到 ifixai 命令

现象：安装完成后终端报命令不存在。 原因：虚拟环境未激活或命令路径不在当前环境中。 解决：确认解释器与 pip 对应，官方提供 python -m ifixai.cli.main 入口作为回退。

3. 把端点写成网页地址

现象：探针返回 HTML 或接口错误。 原因：HTTP provider 需要 Agent 的 API 基地址，README 说明通常到 /v1 为止。 解决：按目标适配方式核对基地址、认证与请求格式，勿把产品首页当聊天 API。

4. 完整运行没有执行全部 61 项

现象：报告中的执行项少于集合标称数量。 原因：工具会排除不适用项；也可能是目标描述缺失导致适用性判断不同。 解决：先看每项解释并复查 profile，不要把跳过项手动改成通过。

5. 测试修改了真实业务数据

现象：测试请求触发了退款、通知或其他外部动作。 原因：探针是真实请求，而目标工具仍连接生产系统。 解决：使用隔离副本、测试账号和无真实支付能力的工具替身，未经授权不运行。

常见问题 FAQ

Q1：不提供 key 能做什么？

A：可以完成内置 mock 演示，了解环境编写、校验及报告；不能据此获得真实端点的独立评价。

Q2：默认检查与 full-run 有什么区别？

A：核验日默认 10 项，full-run 61 项，后者还会按适用性排除项目；数量可能随版本调整。

Q3：开源是否意味着审计零成本？

A：Apache-2.0 代码不收许可费，但真实目标请求、裁判模型和运行资源可能收费。

Q4：可以审计不是 OpenAI 的 Agent 吗？

A：可以，README 列出多种裁判供应商，并说明非标准接口可编写适配；仍需正确配置端点及凭据。

Q5：A 等级能作为合规证明吗？

A：不能。它是特定模拟环境、检查集与裁判配置下的评价，不是法律意见、认证或完整渗透测试。

权限、成本与免责声明

只在获授权范围内测试；对报告中的越权线索应在隔离环境人工复核。 裁判的独立供应商选择降低同源评判风险，但不消除模型误判。 CLI 支持 Windows 使用方式，shell 激活与环境变量语法仍因平台而异。 先以 --dry-run 确认计划，再按供应商当前账单核算成本，不预设统一单价。 本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

参考链接

核验日期：2026-11-03。命令与检查数量以所安装版本的官方文档为准。

• 官方仓库与 README
• 测试自己的 Agent
• 环境编写
• CLI 与套件选项
• 评判机制