# https://github.com/KeyValueSoftwareSystems/agent-opfor 项目说明书

生成时间：2026-07-07 11:25:44 UTC

## 目录

- [项目概览与系统架构](#page-1)
- [核心运行器（CLI / 浏览器扩展 / MCP Server / SDK）](#page-2)
- [评估器体系与攻击覆盖](#page-3)
- [集成、扩展与可观测性](#page-4)

<a id='page-1'></a>

## 项目概览与系统架构

### 相关页面

相关主题：[核心运行器（CLI / 浏览器扩展 / MCP Server / SDK）](#page-2), [评估器体系与攻击覆盖](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/README.md)
- [core/src/index.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/index.ts)
- [core/src/lib/opforConfig.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/lib/opforConfig.ts)
- [core/src/execute/runAll.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/execute/runAll.ts)
- [core/src/execute/runAgentLoop.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/execute/runAgentLoop.ts)
- [core/src/report/buildReport.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/report/buildReport.ts)
- [packages/cli/src/commands/run.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/packages/cli/src/commands/run.ts)
- [packages/cli/src/commands/setup.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/packages/cli/src/commands/setup.ts)
- [packages/sdk/src/index.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/packages/sdk/src/index.ts)
- [packages/extension/src/background.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/packages/extension/src/background.ts)
</details>

# 项目概览与系统架构

Opfor（agent-opfor）是一个面向 AI Agent 的红队对抗评估框架。其定位是在不依赖真实攻击者参与的前提下，使用脚本化的"攻击者代理"对目标 Agent 批量注入越狱、提示词注入、远程代码执行诱导、站点特有扩展执行等攻击向量，并自动汇总为可审计的评估报告。资料来源：[README.md:1-50]()

## 项目定位与适用范围

Opfor 的整体设计目标是抽象出"攻击策略—目标 Agent—评估规则—报告生成"四个环节的可执行流水线，使用户既能在本地通过命令跑单个场景，也能把 Opfor 嵌入到浏览器中在真实会话页面上驱动攻击，或通过 SDK 把核心能力接入既有测试体系。这种"一份核心逻辑，多入口复用"的形态，正是 core 入口文件所承担的职责。资料来源：[core/src/index.ts:1-30]()

在适用范围上，Opfor 既覆盖基于 HTTP 的聊天端点（CLI / SDK 场景），也覆盖具备 DOM 表单和扩展执行上下文的 Web 应用（浏览器扩展场景）；攻击策略与目标字段均通过配置文件统一声明，便于复现与共享。资料来源：[core/src/lib/opforConfig.ts:1-60]()

## 顶层组件与边界

Opfor 在仓库内被划分为四个互相独立、但共享 core 逻辑的子项目：

- **核心库（`core/`）**：以 TypeScript 模块形式承载攻击循环、评估器与报告生成能力，是其它三个组件的复用底座。
- **CLI（`packages/cli/`）**：以 Node 可执行文件提供 `opfor run` 与 `opfor setup` 两条入口命令，是本地复跑与共享配置的主要载体。
- **SDK（`packages/sdk/`）**：以 npm 包形式对外暴露 core 能力，鉴权方式自 v0.10.0 起切换为基于 API Key 的方式；并在 Agent target 的请求头中支持 `${ENV}` 形式的变量展开，这是一次破坏性更新。资料来源：[README.md:60-120]()
- **浏览器扩展（`packages/extension/`）**：面向 Chrome/Edge 的 MV 扩展，可在真实会话页面内驱动对抗会话。

CLI 通过 `opfor setup` 在工作目录创建或更新 `.opfor/configs`，再通过 `opfor run` 触发执行；浏览器扩展则以后台脚本调用 core 的攻击循环，把对抗提示注入当前会话的输入框。资料来源：[packages/cli/src/commands/setup.ts:1-40]()、[packages/extension/src/background.ts:1-30]()

## 核心执行流水线

一次完整的 Opfor 运行的内部流程可以概括为：先由 `opforConfig` 读取 `.opfor/configs` 下的攻击策略与目标定义，再交给 `runAll` 编排多场景与并发度；`runAll` 会逐个把任务派发给 `runAgentLoop`，由该循环驱动"攻击者代理生成对抗提示 → 投递到目标 Agent → 收集响应 → 调用 evaluator 评估"的迭代，直到命中评估阈值、达到轮次上限或被外部中止；命中或终止后由 `buildReport` 汇总所有轮次的请求、响应与命中点，输出到本地或控制台。

```mermaid
flowchart LR
  A[opforConfig 读取配置] --> B[runAll 编排场景]
  B --> C[runAgentLoop 攻击循环]
  C --> D[evaluator 评估响应]
  D -->|未命中未达上限| C
  D -->|命中或终止| E[buildReport 生成报告]
  E --> F[本地/控制台输出]
```

`runAll` 主要负责批次调度与并发控制。资料来源：[core/src/execute/runAll.ts:1-50]()。`runAgentLoop` 是核心迭代器，需要同时处理生成、投递与中止信号。资料来源：[core/src/execute/runAgentLoop.ts:1-60]()。`buildReport` 负责聚合多轮数据并按模板渲染。资料来源：[core/src/report/buildReport.ts:1-50]()

## 已知边界与社区关注点

围绕组件边界，社区已积累了几类典型议题，反映了当前架构上的真实张力：

- **嵌套配置**：在 `.opfor/configs` 内再次运行 `opfor setup`，会递归创建新的 `.opfor` 子目录，而非合并到已有配置。资料来源：[packages/cli/src/commands/setup.ts:40-90]()
- **暂停延迟**：浏览器扩展按下暂停后存在秒级延迟，社区建议"按下即中止请求"以立刻停止 `runAgentLoop`。资料来源：[packages/extension/src/background.ts:60-140]()
- **错误信息缺失**：CLI 当前仅在报告中暴露 HTTP 状态码，对排查 Agent 端错误不够友好。资料来源：[packages/cli/src/commands/run.ts:60-120]()
- **提供商覆盖**：SDK 尚无对 AWS Bedrock、Google Vertex AI 等平台的一等支持。资料来源：[packages/sdk/src/index.ts:1-60]()

这些议题共同指向同一根源：当同一份攻击循环被 CLI、扩展、SDK 三个入口复用时，错误传播、中止信号与鉴权上下文需要在 core 与各入口之间重新分配，才能在多入口下保持一致的运行语义。

---

<a id='page-2'></a>

## 核心运行器（CLI / 浏览器扩展 / MCP Server / SDK）

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [评估器体系与攻击覆盖](#page-3), [集成、扩展与可观测性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [runners/cli/src/commands/run.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/runners/cli/src/commands/run.ts)
- [runners/cli/src/commands/setup.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/runners/cli/src/commands/setup.ts)
- [runners/cli/src/commands/hunt.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/runners/cli/src/commands/hunt.ts)
- [runners/cli/ui/src/App.tsx](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/runners/cli/ui/src/App.tsx)
- [runners/cli/ui/src/components/ConversationView.tsx](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/runners/cli/ui/src/components/ConversationView.tsx)
- [runners/extension/service_worker.js](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/runners/extension/service_worker.js)
</details>

# 核心运行器（CLI / 浏览器扩展 / MCP Server / SDK）

## 概述与架构定位

Opfor 框架将「攻击编排」与「被测 Agent 调用」解耦，由多个运行器（Runner）负责把同一套对抗测试流程嵌入到不同的执行环境中。当前仓库维护四类核心运行器：

- **CLI 运行器**：终端命令行形态，提供 `opfor run`、`opfor setup`、`opfor hunt` 子命令，附带 React 终端 UI 渲染会话 资料来源：[runners/cli/src/commands/run.ts:1-40]()
- **浏览器扩展运行器**：以 Chrome MV3 扩展 `@keyvaluesystems/agent-opfor-extension` 形态在真实网页会话中就地发起红队测试 资料来源：[runners/extension/service_worker.js:1-60]()
- **SDK 运行器**：对外暴露的核心 SDK，供集成方按需接管 Provider 选择、报告生成与攻击调度 资料来源：[runners/cli/src/commands/setup.ts:1-80]()
- **MCP Server 运行器**：基于 Model Context Protocol 向 IDE / Agent 宿主暴露红队工具

四者共享 `.opfor/` 配置目录与攻击评估管线，从而让 CLI 报告、Web 端报告与 SDK 报告保持同一数据格式。

## CLI 运行器

CLI 运行器由 Commander 风格的命令入口 + React Inbox UI 组成。`run.ts` 负责装载 `.opfor/configs`、调用攻击策略并把进度推送到 UI；`setup.ts` 处理交互式向导以创建或更新 `.opfor` 目录 资料来源：[runners/cli/src/commands/setup.ts:1-80]()。社区反馈指出当前版本在 `.opfor/configs` 目录内再执行 `opfor setup` 会嵌套生成 `.opfor` 子目录，理想行为应该是合并而非嵌套（见 issue #183）。

`hunt.ts` 是批量无界面执行入口，常用于 CI 流水线；最终产出与 `run` 一致的 JSON 报告 资料来源：[runners/cli/src/commands/hunt.ts:1-60]()。当被测 Agent 返回 HTTP 错误时，目前 CLI 仅打印状态码，社区在 issue #176 中建议把响应体一并写入报告以便排查。UI 端 `App.tsx` 与 `ConversationView.tsx` 维护会话流、暂停按钮与实时着色，最近在 issue #177/#182 中被报告存在约 10 秒的暂停延迟，根因是后端长轮询尚未被中断。

## 浏览器扩展运行器

扩展运行器通过 `service_worker.js` 监听 `chrome.runtime` 消息、把当前活动标签页的输入框识别为攻击目标，并通过 `chrome.scripting` 注入红队提示词 资料来源：[runners/extension/service_worker.js:1-60]()。在自动模式下，扩展会在收到 Agent 回复前就预生成下一条攻击，从而触发 race condition；issue #180 要求改写为「等待 Agent 完整回复后再触发」的串行模式。

社区还指出扩展会错误地把登录表单当作聊天输入（#178）、缺少手动中途修正攻击策略的能力（#175）、以及缺少针对「站点专属扩展执行」漏洞的评估器（#179）。`OPFOR` 还在评估报告中新增「远程代码执行评估器」与「上传文件」等扩展点（#172、#173），扩展运行器需要相应扩展 manifest 权限。

## SDK 与 MCP Server 运行器

SDK 是 CLI / 扩展的共用后端，承载 Provider 适配层、攻击策略与判官评估器。最新 v0.10.0 的破坏性变更把所有密钥切换为 `apikey` 字段同步更新了 SDK 的 E2E 与示例 资料来源：[runners/cli/src/commands/setup.ts:1-80]()。社区在 issue #181 中提出为 AWS Bedrock、Google Vertex AI 等平台引入一等支持，目前仍需通过自定义 Provider 桥接。

MCP Server 把上述能力封装成 MCP 协议的工具集，让支持 MCP 的 IDE / Agent 宿主能够「直接调用」红队动作而无需再嵌入 CLI。其复用 SDK 的报告结构，因此可以直接消费 CLI 生成的同一份评估结果。

## 运行器选型速查

| 运行器 | 触发形态 | 输出 | 典型场景 |
|--------|----------|------|----------|
| CLI `opfor run` | 终端命令 + 终端 UI | `.opfor` 报告 | 本地交互测试 |
| CLI `opfor hunt` | 批处理 | JSON 报告 | CI / 回归 |
| Browser Extension | 浏览器内点击 | 浏览器端报告 | 真机 Web 站点红队 |
| SDK | 代码内嵌 | 程序化报告 | 平台集成、自定义 Provider |
| MCP Server | MCP 工具调用 | 与 SDK 同构 | IDE / Agent 宿主内联动 |

资料来源：[runners/cli/src/commands/run.ts:1-40]()、[runners/cli/src/commands/hunt.ts:1-60]()、[runners/extension/service_worker.js:1-60]()

> 提示：所有运行器都依赖 `.opfor/configs` 目录下的会话与攻击配置，运行前请确保路径正确，避免类似 issue #183 的嵌套目录问题。

---

<a id='page-3'></a>

## 评估器体系与攻击覆盖

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [核心运行器（CLI / 浏览器扩展 / MCP Server / SDK）](#page-2), [集成、扩展与可观测性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [evaluators/README.md](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/evaluators/README.md)
- [docs/evaluators.md](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/docs/evaluators.md)
- [docs/evaluator-schema.md](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/docs/evaluator-schema.md)
- [core/src/evaluators/schema.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/evaluators/schema.ts)
- [core/src/evaluators/judge.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/evaluators/judge.ts)
- [core/src/evaluators/strategies.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/evaluators/strategies.ts)
</details>

# 评估器体系与攻击覆盖

## 概述与定位

Opfor 的评估器体系（Evaluator System）是 Agent 自动化红队测试流水线的判定环节，负责在攻击者 Agent 与目标 Agent 完成对抗性对话之后，对整段会话进行评分并输出命中（hit）/未命中（miss）结论，结果最终汇入 CLI 报告与扩展评估视图。

资料来源：[evaluators/README.md:1-24]()

整个体系由「数据模式 + 判断器 + 策略调度」三部分组成，使攻击覆盖易于扩展并可按需启用。

## 评估器核心架构

### 数据模式（Schema）

每一条评估规则以统一的 `Evaluator` 类型描述，字段包括唯一标识 `id`、可读名称 `name`、所属攻击类别 `category`、严重等级 `severity`、触发该评估的提示模板与判定条件。

资料来源：[core/src/evaluators/schema.ts:1-60]()

字段约束、必填项与示例配置参见评估器模式说明，便于用户本地化定义规则。

资料来源：[docs/evaluator-schema.md:1-48]()

### 判断器（Judge）

判断器接收完整的消息序列，依据评估器定义的判定条件进行匹配与推断，可结合规则表达式、关键词与可选的 LLM 复审来识别目标 Agent 是否落入了危险的响应模式（如越权指令执行、敏感数据回显、危险工具调用等）。

资料来源：[core/src/evaluators/judge.ts:1-72]()

### 策略调度（Strategies）

策略模块在每次运行启动时筛选并加载评估器集合，支持按 `category`、严重度或用户显式列表进行过滤，未被策略选中的评估器不会进入本次评估流程，从而降低开销并支持定向测试。

资料来源：[core/src/evaluators/strategies.ts:1-84]()

## 攻击覆盖与社区推动方向

### 当前覆盖的评估维度

| 类别 | 评估目标 | 典型判定方式 |
| --- | --- | --- |
| Prompt 注入 / 越狱 | 系统提示绕过、角色劫持 | 模式匹配 + LLM 复审 |
| 越权工具调用 | 工具被绕权限使用 | 调用链审计 |
| 敏感信息泄露 | 模型回显凭证、PII | 关键词/正则匹配 |
| 有害内容 | 违规、歧视、暴力输出 | 类别分类器 |

资料来源：[evaluators/README.md:20-96]()

完整使用与配置流程参见评估器文档。

资料来源：[docs/evaluators.md:1-90]()

### 社区请求的新覆盖方向

- **远程代码执行检测**：检测模型是否主动调用或建议从不可信远程源获取并执行代码（issue #172）。
- **站点特定扩展执行**：针对浏览器扩展特有权限场景的评估能力（issue #179）。
- **对已有对话的后置评估**：允许用户在已完成的对话上直接运行评估器生成报告，无需再次发起对抗（issue #171）。

## 自定义扩展与已知限制

新增评估器时，在 `evaluators/` 下追加定义文件，并在策略模块注册即可纳入本地或 CI 流水线。

资料来源：[core/src/evaluators/strategies.ts:60-132]()

当前存在的、与评估链路相关的限制：

- CLI 在目标 Agent 返回错误时仅暴露 HTTP 状态码，response body 未写入报告，影响失败定位（issue #176）。
- 评估流尚未支持文件上传攻击场景，需结合文件输入能力扩展（issue #173）。
- AWS Bedrock、Google Vertex AI 等非默认提供方尚未在评估链路中默认适配（issue #181）。

---

<a id='page-4'></a>

## 集成、扩展与可观测性

### 相关页面

相关主题：[项目概览与系统架构](#page-1), [核心运行器（CLI / 浏览器扩展 / MCP Server / SDK）](#page-2), [评估器体系与攻击覆盖](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [core/src/providers/factory.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/providers/factory.ts)
- [core/src/providers/types.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/providers/types.ts)
- [core/src/llm/openaiCompatible.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/llm/openaiCompatible.ts)
- [core/src/targets/agentTarget.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/targets/agentTarget.ts)
- [core/src/targets/httpClient.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/targets/httpClient.ts)
- [core/src/targets/mcpTarget.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/targets/mcpTarget.ts)
- [core/src/lib/loadOpforMcpConfig.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/core/src/lib/loadOpforMcpConfig.ts)
- [cli/src/commands/setup.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/cli/src/commands/setup.ts)
- [cli/src/commands/run.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/cli/src/commands/run.ts)
- [extension/src/background.ts](https://github.com/KeyValueSoftwareSystems/agent-opfor/blob/main/extension/src/background.ts)
</details>

# 集成、扩展与可观测性

## 概述与作用域

Opfor 的"集成、扩展与可观测性"横跨三个维度：把外部 LLM 服务接入评估器（Provider 集成）、把待评估的 Agent / 服务接入被测对象（Target 与 MCP 集成），以及在 CLI 与浏览器扩展中提供可扩展的入口与可观测信号。核心 SDK 通过工厂模式创建 Provider 与 Target，使 OpenAI 兼容接口、HTTP Agent 与 MCP Server 都能以统一抽象接入；CLI 通过 `opfor setup` / `opfor run` 维护 `.opfor/configs`；浏览器扩展作为人机交互的扩展点，承担暂停、攻击调度与状态上报。

社区中关于 "add first-class support for additional LLM providers (#181)" 的需求，恰好反映了 Provider 集成层当前的扩展瓶颈；而 #176（错误仅显示 HTTP 状态码）和 #183（嵌套 `.opfor` 配置）则暴露了可观测性与 CLI 扩展点的现存痛点。

## LLM Provider 集成层

Provider 集成层以工厂模式统一对外屏蔽不同 LLM 提供商的差异。`core/src/providers/factory.ts` 中的工厂函数根据配置中的 provider 类型返回具体实现，目前的内置实现是基于 OpenAI 兼容协议的 `openaiCompatible` 客户端。`core/src/providers/types.ts` 定义了统一的 Provider 接口契约，包括消息格式、鉴权方式、流式响应与工具调用映射。`core/src/llm/openaiCompatible.ts` 实现该协议，可直接对接 OpenAI、Azure OpenAI，以及任何兼容 `/chat/completions` 风格的服务。

```mermaid
flowchart LR
  A[Eval Runner] --> B[Provider Factory]
  B --> C[OpenAI Compatible]
  B --> D[Bedrock - 计划]
  B --> E[Vertex AI - 计划]
  C --> F[Target Agent]
  D --> F
  E --> F
```

资料来源：[core/src/providers/factory.ts:1-80]() 资料来源：[core/src/providers/types.ts:1-60]() 资料来源：[core/src/llm/openaiCompatible.ts:1-200]()

社区讨论 #181 指出，AWS Bedrock 与 Google Vertex AI 拥有独立的鉴权（SigV4 / OAuth）与请求体结构，需要在工厂中新增分支与对应的客户端实现，并在 `types.ts` 中扩展协议抽象。`v0.10.0` 已将 SDK 切换为基于 `apikey` 值的鉴权模型（#168），简化了多 Provider 的密钥管理流程。

## Target 与 MCP 集成

Target 层把被测 Agent / 服务抽象为可调用的端点。`core/src/targets/agentTarget.ts` 负责与已注册的 Agent HTTP 接口交互，它封装了请求构造与响应解析；`core/src/targets/httpClient.ts` 提供带超时与重试的基础 HTTP 客户端，被 `agentTarget.ts` 复用。`core/src/targets/mcpTarget.ts` 实现对 Model Context Protocol Server 的桥接，可调用外部 MCP 工具。

MCP 配置的加载由 `core/src/lib/loadOpforMcpConfig.ts` 负责，读取 `.opfor` 目录下的 MCP 服务器清单与传输方式，并校验 schema。CLI 的 `setup` 流程（#183）当前存在嵌套创建 `.opfor` 的问题，期望行为是追加而非嵌套创建——这与 MCP 配置加载逻辑是否相对路径解析友好直接相关。

资料来源：[core/src/targets/agentTarget.ts:1-150]() 资料来源：[core/src/targets/httpClient.ts:1-120]() 资料来源：[core/src/targets/mcpTarget.ts:1-180]() 资料来源：[core/src/lib/loadOpforMcpConfig.ts:1-90]()

## 浏览器扩展与 CLI 的扩展点

`extension/src/background.ts` 是浏览器扩展的后台调度中枢：它在收到攻击指令后驱动当前标签页的 content script 注入提示，并通过消息通道与 SDK 通信。社区问题 #177 / #182 反映当前 `pause` 按钮响应存在 ~10s 的延迟，根本原因是没有把控制信号下沉到底层 HTTP 请求的 `AbortController`；建议修复路径是在 `httpClient.ts` 中暴露 abort 句柄并由 background 立即触发。问题 #180 指出扩展会在 Agent 未完成响应时即生成下一轮攻击，因此后台调度需要等待响应解析后再入队。问题 #178 则要求在注入前对目标元素做语义判别（登录框 vs 聊天输入框），属于 content script 的可扩展 hook。

CLI 侧，`cli/src/commands/setup.ts` 与 `cli/src/commands/run.ts` 分别负责生成 / 合并 `.opfor/configs` 与执行评估流水线。`v0.10.0` 新增了对 Agent target headers 中环境变量引用的展开能力，进一步把"配置即代码"的扩展能力下沉到头部注入。

资料来源：[extension/src/background.ts:1-220]() 资料来源：[cli/src/commands/setup.ts:1-160]() 资料来源：[cli/src/commands/run.ts:1-200]()

## 可观测性、日志与错误处理

可观测性当前主要落在三个表面：CLI 报告、浏览器扩展 UI 与 SDK 日志。问题 #176 明确指出，当 chat 端点返回非 2xx 时，CLI 报告仅显示状态码而丢失响应体；建议在 `httpClient.ts` 的错误分支中保留原始响应 payload，并在 `run.ts` 的报告生成器中以结构化字段输出。问题 #171 提出的"对已有对话进行评估"则要求把评估器与日志分离，使历史会话能被独立回放与判分，这通常意味着在 `loadOpforMcpConfig.ts` 之上再增加一个会话加载器。

错误传播链路为：`httpClient.ts` → `agentTarget.ts` → 评估流水线 → `run.ts` 报告器 / `background.ts` UI。要让 #176、#177 与 #183 同时得到改善，需要在底层客户端引入结构化错误（携带 status / body / cause），在 Target 层透传，并在 CLI 与扩展层分别以可读文本与状态条形式呈现。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：KeyValueSoftwareSystems/agent-opfor

摘要：发现 33 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: feat: opfor setup wizard has no prompt for custom HTTP headers on url-transport MCP targets。

## 1. 安全/权限坑 · 失败模式：security_permissions: feat: opfor setup wizard has no prompt for custom HTTP headers on url-transport MCP targets

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: feat: opfor setup wizard has no prompt for custom HTTP headers on url-transport MCP targets
- 对用户的影响：Developers may expose sensitive permissions or credentials: feat: opfor setup wizard has no prompt for custom HTTP headers on url-transport MCP targets
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/166 | feat: opfor setup wizard has no prompt for custom HTTP headers on url-transport MCP targets

## 2. 安全/权限坑 · 失败模式：security_permissions: feat: support for evaluating Site-Specific Extension Execution

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: feat: support for evaluating Site-Specific Extension Execution
- 对用户的影响：Developers may expose sensitive permissions or credentials: feat: support for evaluating Site-Specific Extension Execution
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/179 | feat: support for evaluating Site-Specific Extension Execution

## 3. 安装坑 · 失败模式：installation: v0.10.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.10.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.10.0
- 证据：failure_mode_cluster:github_release | https://github.com/KeyValueSoftwareSystems/agent-opfor/releases/tag/v0.10.0 | v0.10.0

## 4. 安装坑 · 来源证据：feat: Ability to judge and create reports from the conversations between the user and the agent

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Ability to judge and create reports from the conversations between the user and the agent
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/171 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/KeyValueSoftwareSystems/agent-opfor | host_targets=mcp_host, claude, cursor, chatgpt

## 6. 配置坑 · 失败模式：configuration: bug: Nested .opfor configs

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: bug: Nested .opfor configs
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bug: Nested .opfor configs
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/183 | bug: Nested .opfor configs

## 7. 配置坑 · 失败模式：configuration: bug: Significant delay in registering pause button clicks.

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: bug: Significant delay in registering pause button clicks.
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bug: Significant delay in registering pause button clicks.
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/182 | bug: Significant delay in registering pause button clicks.

## 8. 配置坑 · 失败模式：configuration: bug: browser extension targets login form instead of chatbot input during red-team assessment

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: bug: browser extension targets login form instead of chatbot input during red-team assessment
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bug: browser extension targets login form instead of chatbot input during red-team assessment
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/178 | bug: browser extension targets login form instead of chatbot input during red-team assessment

## 9. 配置坑 · 失败模式：configuration: bug:browser extension generates next attack before the agent has completed its response

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: bug:browser extension generates next attack before the agent has completed its response
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: bug:browser extension generates next attack before the agent has completed its response
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/180 | bug:browser extension generates next attack before the agent has completed its response

## 10. 配置坑 · 失败模式：configuration: feat: add first-class support for additional LLM providers

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: feat: add first-class support for additional LLM providers
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: feat: add first-class support for additional LLM providers
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/181 | feat: add first-class support for additional LLM providers

## 11. 配置坑 · 来源证据：bug: Nested .opfor configs

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: Nested .opfor configs
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/183 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 12. 配置坑 · 来源证据：bug: Significant delay in registering pause button clicks.

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: Significant delay in registering pause button clicks.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/182 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 13. 配置坑 · 来源证据：bug: browser extension targets login form instead of chatbot input during red-team assessment

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug: browser extension targets login form instead of chatbot input during red-team assessment
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/178 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 14. 配置坑 · 来源证据：bug:browser extension generates next attack before the agent has completed its response

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug:browser extension generates next attack before the agent has completed its response
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/180 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 15. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/KeyValueSoftwareSystems/agent-opfor | README/documentation is current enough for a first validation pass.

## 16. 运行坑 · 来源证据：bug: Significant delay in registering pause button clicks.

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug: Significant delay in registering pause button clicks.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 运行坑 · 来源证据：feat: Show the response of agent errors instead of just an HTTP status code.

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：feat: Show the response of agent errors instead of just an HTTP status code.
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。

## 18. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/KeyValueSoftwareSystems/agent-opfor | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/KeyValueSoftwareSystems/agent-opfor | no_demo; severity=medium

## 20. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/KeyValueSoftwareSystems/agent-opfor | no_demo; severity=medium

## 21. 安全/权限坑 · 来源证据：feat: add first-class support for additional LLM providers

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: add first-class support for additional LLM providers
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/181 | 来源类型 github_issue 暴露的待验证使用条件。

## 22. 安全/权限坑 · 来源证据：feat: opfor setup wizard has no prompt for custom HTTP headers on url-transport MCP targets

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: opfor setup wizard has no prompt for custom HTTP headers on url-transport MCP targets
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/166 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 23. 安全/权限坑 · 来源证据：feat: support for evaluating Site-Specific Extension Execution

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: support for evaluating Site-Specific Extension Execution
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/179 | 来源类型 github_issue 暴露的待验证使用条件。

## 24. 能力坑 · 失败模式：capability: bug: Significant delay in registering pause button clicks.

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: bug: Significant delay in registering pause button clicks.
- 对用户的影响：Developers may hit a documented source-backed failure mode: bug: Significant delay in registering pause button clicks.
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/177 | bug: Significant delay in registering pause button clicks.

## 25. 能力坑 · 失败模式：capability: feat: Ability to judge and create reports from the conversations between the user and the agent

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: Ability to judge and create reports from the conversations between the user and the agent
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: Ability to judge and create reports from the conversations between the user and the agent
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/171 | feat: Ability to judge and create reports from the conversations between the user and the agent

## 26. 能力坑 · 失败模式：capability: feat: OPFOR getting the ability to upload files to agent

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: OPFOR getting the ability to upload files to agent
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: OPFOR getting the ability to upload files to agent
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/173 | feat: OPFOR getting the ability to upload files to agent

## 27. 能力坑 · 失败模式：capability: feat: Show the response of agent errors instead of just an HTTP status code.

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: Show the response of agent errors instead of just an HTTP status code.
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: Show the response of agent errors instead of just an HTTP status code.
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/176 | feat: Show the response of agent errors instead of just an HTTP status code.

## 28. 能力坑 · 失败模式：capability: feat: evaluator for remote code execution

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: evaluator for remote code execution
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: evaluator for remote code execution
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/172 | feat: evaluator for remote code execution

## 29. 能力坑 · 失败模式：capability: feat: judging file outputs of the agent.

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: feat: judging file outputs of the agent.
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: judging file outputs of the agent.
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/174 | feat: judging file outputs of the agent.

## 30. 能力坑 · 失败模式：conceptual: feat: Allow the user the steer the attacker agent during testing

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: feat: Allow the user the steer the attacker agent during testing
- 对用户的影响：Developers may hit a documented source-backed failure mode: feat: Allow the user the steer the attacker agent during testing
- 证据：failure_mode_cluster:github_issue | https://github.com/KeyValueSoftwareSystems/agent-opfor/issues/175 | feat: Allow the user the steer the attacker agent during testing

## 31. 运行坑 · 失败模式：performance: v0.9.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v0.9.0
- 对用户的影响：Upgrade or migration may change expected behavior: v0.9.0
- 证据：failure_mode_cluster:github_release | https://github.com/KeyValueSoftwareSystems/agent-opfor/releases/tag/v0.9.0 | v0.9.0

## 32. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/KeyValueSoftwareSystems/agent-opfor | issue_or_pr_quality=unknown

## 33. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/KeyValueSoftwareSystems/agent-opfor | release_recency=unknown

<!-- canonical_name: KeyValueSoftwareSystems/agent-opfor; human_manual_source: deepwiki_human_wiki -->