pharosone/vector-plugin

## 这是什么 [Vector](https://pharosone.ai) 是一个针对 LLM agent 的红队控制平面，由 [Pharos One](https://pharosone.ai) 运营。它会针对你特定的 agent 规划定向攻击，使用独立的 LLM 评估响应，并生成可操作的检测结果 —— 每次攻击对应 `PASS` / `FAIL` / `PARTIAL`，并进行评分、分类，映射到 AIUC-1 领域。 此插件为你的 AI 编辑器提供了访问 Vector 控制平面的一流入口，并内置了四项技能，可将检测结果转化为 pull request： ``` your AI editor ─▶ Vector plugin ─▶ MCP (OAuth) ─▶ Vector SaaS ─▶ planner + judge │ ◀──── findings ◀── report ◀────────────────────────────┘ │ ▼ skills propose: adapter, CI step, narrow fix, regression test ``` 在编辑器内使用无需复制任何 API 密钥。MCP server 在首次调用时通过 OAuth 2.1 进行授权 —— 你的浏览器将打开 Clerk 的授权同意页面，你只需点击批准，token 就会由编辑器在本地缓存。（仅在用于 CI/CD 时才需要长效 API 密钥 —— 请参阅下方的[认证机制](#how-auth-works)。） ## 安装说明 ### Claude Code ``` /plugin marketplace add pharosone/vector-plugin /plugin install vector@vector ``` 然后输入 `/mcp` → 选择 `plugin:vector:vector` → 在浏览器中批准。 ### Cursor 1. Cursor 设置 (`⌘⇧J`) → **Plugins** → **Add from URL** 2. 粘贴 `https://github.com/pharosone/vector-plugin` ### Codex ``` codex plugin marketplace add pharosone/vector-plugin ``` 在 Codex 中：输入 `/plugins` → 选择 **vector** → **Install**。 ### Gemini CLI ``` gemini extensions install https://github.com/pharosone/vector-plugin ``` Gemini 原生不支持 HTTP MCP，因此该扩展通过 `mcp-remote@latest` 进行桥接（首次使用时 npx 会自动安装桥接程序）。OAuth 认证流程相同。 ## 功能特性 安装后，你将获得：**四项技能** + **一个 MCP server**。 ### 技能 | 技能 | 何时使用 | 产出内容 | | --- | --- | --- | | **`integrate`** | 首次设置 | 一个调用你 LLM agent 的 `AgentAdapter`，一个驱动 Vector REST API 的 `RedTeamRunner`，一个 CI workflow，以及一个供你审查的 PR | | **`harden-from-finding`** | 在出现单个 `FAIL` 后 | 针对你的系统 prompt 或工具定义进行定向修改，外加一个重放该确切攻击的回归测试 | | **`batch-fix-findings`** | 在包含多个 `FAIL` 的完整会话后 | 检测结果按**根本原因**分组，每组一个最小补丁，每组一个回归测试 —— 而不是针对 N 个检测结果生成 N 个修复 | | **`create-agent-context`** | 创建已保存的 agent 配置时 | Slug + 包含 5 个字段的 `AgentContext` JSON，可直接粘贴到控制台的 **New agent** 表单中 | ### 如何调用技能 | 编辑器 | 调用方式 | | --- | --- | | Claude Code | `/vector:integrate`, `/vector:harden-from-finding` 等 | | Cursor / Codex | `/integrate`, `/harden-from-finding` 等 | | Gemini CLI | 自然语言 —— *“integrate Vector into this repo”* 即可匹配 `integrate` 技能 | 在所有这四个客户端中，技能描述都会自动与你的请求进行匹配 —— 通常你不需要刻意去记这些名称。 ### MCP server 预先配置好的入口，指向 `https://vector-api.pharosone.ai/api/v1/mcp/`。安装后，编辑器的 MCP 面板将列出 `vector`，其包含的工具与 SDK 保持 1:1 对应： | 工具 | 功能描述 | | --- | --- | | `create_session` | 启动一个新的红队会话（规划器会为你的 agent 选择攻击方式） | | `get_session` | 获取会话的状态与进度 | | `list_attacks` | 拉取计划好的攻击 prompt 以发送给你的 agent | | `submit_results` | 提交你 agent 的响应以供评判 | | `wait_for_report` | 长轮询等待直到报告生成完毕 | | `get_report` | 获取结论、摘要、AIUC 覆盖范围及检测结果 | | `agents.*` | 对已保存的 agent 配置执行 CRUD 操作 | ## 认证机制 这里有**两个独立的认证端**，分别供两种不同的调用者使用： | 端 | 调用者 | 认证方式 | 设置位置 | | --- | --- | --- | --- | | **MCP 工具**（此插件） | 交互式会话中的 AI 编辑器 | OAuth 2.1 (Clerk) —— 首次调用时通过浏览器流程授权 | 已在此预先配置 —— 无需复制任何内容。你只需在编辑器打开的浏览器标签页中点击一次即可。 | | **REST API** (`/api/v1/sessions`, `/api/v1/agents`, …) | CI 运行器（夜间定时任务、PR 门禁、部署后的冒烟测试） | `Authorization: Bearer ak_...` —— Clerk 长效 API 密钥 | 在控制台中生成一次 → **API keys** (`https://vector.pharosone.ai/api-keys`)，作为 CI 密钥存储并配置到本地 `.env` 中。`integrate` 技能生成的代码会从 `VECTOR_API_KEY` 读取它。 | | **控制台**（浏览器 UI） | 浏览器中的人工操作 | Clerk 会话 cookie | `https://vector.pharosone.ai` —— 使用你的组织账户登录 | 这两个认证端都连接到同一个后端（`https://vector-api.pharosone.ai`）并查看相同的数据，只是入口不同。只要涉及读取会话或检测结果，该插件的技能会优先使用 MCP —— 完全不需要处理任何密钥。`integrate` 为你的代码仓库构建的 CI 集成是唯一需要长效密钥的地方，因为 CI 在无人值守的情况下运行，没有浏览器界面。 ### 首次 MCP 调用 (OAuth 2.1, PKCE-S256, RFC 8707) ``` 1. plugin ─▶ POST /api/v1/mcp (no auth) 2. server ─▶ 401 WWW-Authenticate: Bearer ... resource_metadata= 3. plugin ─▶ fetches resource metadata, opens Clerk consent URL in your browser 4. you ─▶ pick the org you want to act as, approve 5. Clerk ─▶ access_token (TTL 1h) + refresh_token (TTL 14d), bound to vector-api.pharosone.ai/api/v1/mcp 6. plugin ─▶ caches tokens locally, retries the call — succeeds ``` Token 的权限范围仅限于你选择的用户和组织，并且其 audience 绑定到了 Vector MCP endpoint。它们无法针对任何其他 API 重放使用。Token 由你的编辑器存储在其标准凭据缓存中（如 `~/.cursor/...`, `~/.codex/...`，Claude Code 的 keychain 条目等）—— 绝不会由本插件存储。 ### 关于 API 密钥 (`ak_...`) 这是集成系统接触到的**唯一**密钥，且 AI 编辑器永远不会看到它的具体值： - **生成：** 打开 `https://vector.pharosone.ai/api-keys` → 新建 → 复制一次 `ak_...` 的值（控制台只会显示一次）。 - **存储：** 将其粘贴到你的 CI 密钥管理器中（GitHub Actions secret `VECTOR_API_KEY`、GitLab CI/CD 变量、Vault、Doppler、k8s Secret 等），并放入本地 `.env` 用于临时运行。确保 `.env` 已被 gitignore。 - **使用：** `integrate` 技能会生成代码，从 `process.env.VECTOR_API_KEY`（或特定语言的等价写法）中读取它，并作为 `Authorization: Bearer ak_...` 发送。该密钥永远不会出现在源文件中，不会进入 git 历史记录，也不会出现在 AI 编辑器的聊天记录中。 - **撤销：** 在同一个控制台页面 —— 点击撤销。立即生效；无需重新构建。 API 密钥是不透明的（`ak_...`），并不是 JWT —— 不要尝试解码它们。验证过程是每次请求由 Clerk 进行一次往返；对于典型的 CI 频率（每天少量的红队运行），其延迟是可以忽略不计的。 ## 自托管 / 私有化部署 在启动编辑器之前，设置 `VECTOR_MCP_URL` 环境变量： ``` export VECTOR_MCP_URL="https://your-vector-host.example.com/api/v1/mcp" ``` - **Cursor / Claude Code / Codex** —— 环境变量会在运行时于 manifest 的 `url` 字段中被展开。 - **Gemini CLI** —— 环境变量会被直接传递给 `mcp-remote` 桥接程序。 如果你的编辑器不会展开 JSON manifest 中的环境变量，请在本地编辑 `.mcp.json` 以硬编码该 URL。 ## 仓库结构 ``` vector-plugin/ ├── .claude-plugin/ Claude Code manifest + marketplace catalog ├── .cursor-plugin/ Cursor manifest ├── .codex-plugin/ Codex manifest (with interface metadata) ├── .mcp.json MCP server config (Claude Code + Cursor) ├── mcp.json MCP server config (Codex) ├── gemini-extension.json Gemini CLI manifest (mcp-remote bridge) ├── GEMINI.md Gemini CLI context file ├── skills/ Shared by all four clients │ ├── integrate/ │ ├── harden-from-finding/ │ ├── batch-fix-findings/ │ └── create-agent-context/ ├── assets/ │ └── logo.svg ├── LICENSE └── README.md you are here ``` 技能的具体内容是**纯 Markdown 格式**，并带有 YAML frontmatter，且不含任何特定于客户端的代码 —— 要增加对第五种编辑器的支持，只需添加另一个 manifest 文件即可，无需重写技能本身。 ## 版本控制 - 版本号在**五个** manifest 中同步声明 (`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`)。 - 每个发布版本都会打上 `vX.Y.Z` 标签，并通过 [GitHub Releases](https://github.com/pharosone/vector-plugin/releases) 发布。 - Claude Code、Codex 和 Gemini CLI 默认拉取 `main` 分支；若要固定到某个标签，需要用户从特定的 ref (`@vX.Y.Z`) 进行安装。

标签：AI智能体, LNA, MCP协议, 大语言模型安全, 安全测试, 插件, 攻击性安全, 机密管理, 防御加固