# @fragments\_awe/ops-mcp 中文文档

规范地址：https://npmcn.com/package/%40fragments_awe/ops-mcp/

版本：0\.24\.0
npm 元数据更新时间：2026-11-15T03:04:30.604Z
中文译文更新时间：2026-11-15T11:42:03.449Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fragments_awe/ops-mcp
原文对照：https://npmcn.com/package/%40fragments_awe/ops-mcp/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62.3 MB，7 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-28T03:50:58.209Z
- 最新版本发布：2026-11-15T03:04:30.255Z
- 近 30 天下载量：3702（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

WG Ops MCP 本地AI客户端工具

## 安装

```sh
npm install @fragments_awe/ops-mcp
```

也可以使用：`pnpm add @fragments_awe/ops-mcp`、`yarn add @fragments_awe/ops-mcp`、`bun add @fragments_awe/ops-mcp`

## README

# Ops MCP

需要 Node.js 18+。支持 macOS Apple/Intel、Windows x64、Linux x64。

```sh
npm install -g @fragments_awe/ops-mcp
ops-mcp login us_east
```

国内登录用 `ops-mcp login cn`，新加坡用 `ops-mcp login singapore`。在浏览器完成飞书授权。

AI 客户端的 MCP 配置：

```json
{
  "mcpServers": {
    "wgops": {
      "command": "ops-mcp",
      "args": []
    }
  }
}
```

Claude Code 可执行 `claude mcp add --transport stdio --scope user wgops -- ops-mcp`。 如果图形客户端找不到命令，使用 `which ops-mcp`（Windows 用 `where ops-mcp`）输出的完整路径。

对 AI 说“先绑定美东路演，再列出测试集合”。区域分别是 `cn_dev`、`singapore_dev`、`us_east_exhibition`。

MCP 启动后立即在后台查询 npm latest，长驻进程每 30 秒再次检查；本地版本缓存仅在查询失败时兜底。 发现新版后，在接下来的工具返回中附带更新提醒，由 AI 转述。每个新版最多提醒 3 次，次数保存在 `~/.wgops-mcp/update-notices/<版本>/`，多个客户端和进程重启共用上限；更高版本有新的 3 次名额。 没有工具调用时不会主动唤醒对话，不保证客户端弹出通知。

```sh
npm install -g @fragments_awe/ops-mcp@latest
```

更新后重启客户端里的 MCP。登录凭据仍保存在 `~/.wgops-mcp/session.json`，不包含在 npm 包中。

维护者从仓库 backend 目录构建，再进入 npm/ops-mcp 发布：

```sh
GOTOOLCHAIN=auto go run ./cmd/package-ops-mcp --npm-output ../npm/ops-mcp
cd ../npm/ops-mcp
npm test
npm pack
npm publish --access public
```

发布前同步修改 `backend/internal/opsmcp/version.go` 与 `package.json` 的版本，构建及 prepack 都会验证版本一致。

## 通过 Ops 调用理解、生图和视频模型

这组工具复用 Ops 登录态和 `bind_region`，不需要个人 ModelHub API Key。 使用前须部署支持生成接口的 Ops 后端，并安装相应版本的 MCP。后端只调用本部署的 ModelHub，环境不匹配时会拒绝请求。

先登录、绑定美东路演，再查询本环境的模型目录：

```text
bind_region({"region":"us_east_exhibition"})
list_generation_models({"category":"video"})
list_generation_models({"category":"image"})
list_generation_models({"category":"text"})
```

文本和图片理解使用 `generate_text` 和 `get_text_generation`。 `text` 目录包含当前环境的 `llm` 和 `multimodal` 模型，不限于 Gemini。 从目录选择真实模型 ID；`llm` 只接受文本，`multimodal` 可带图片。

```text
generate_text({"model":"目录返回的模型 ID","prompt":"概括这段文字的含义"})
generate_text({"model":"gemini-4-argon","prompt":"分析这段代码","thinking_level":"high"})
generate_text({"model":"目录返回的 multimodal 模型 ID","prompt":"描述图片中的衣物","images":["/absolute/path/reference.png"]})
get_text_generation({"task_id":"生成返回的本机任务编号"})
```

`images` 支持本机绝对路径或 HTTP/HTTPS 图片 URL，内联图片总大小最多 16 MiB。 `thinking_level` 可选，接受 `minimal`、`low`、`medium`、`high`；不传时沿用模型默认值。 档位由 ModelHub 按模型处理，例如 Argon/Carbon 的 `minimal` 会映射为 `low`。 使用此参数需要支持该字段的 Ops 后端，发布时先更新后端，再更新 MCP。 MCP 在本机等待 Ops 返回，最长 10 分钟；等待期间须保持 MCP 运行并保持原环境绑定。 `running` 表示仍在等待，`succeeded` 才表示收到完整文本。 结果保留文本、模型响应编号、结束原因和 token 用量；失败或中断不自动重提。

`generate_video` 接受 `model`、`prompt`，以及可选的 `images`、`aspect_ratio`、`duration_seconds` 和 `resolution`。 从目录选择真实模型 ID；美东路演的 Vmind 穿搭视频也使用这个入口。 `images` 支持本机图片绝对路径或 HTTP/HTTPS URL，上传的图片总大小最多 16 MiB。 具体时长、分辨率和参考图数量由模型校验。

```text
generate_video({"model":"Vmind_outfit_video_v1.0","prompt":"保持全身入画，缓慢转身","images":["/absolute/path/reference.png"]})
get_video_generation({"task_id":"提交返回的任务引用","output_dir":"/absolute/path/deliverables"})
```

`accepted` 只表示视频任务受理。返回 `pending` 或 `running` 时，按 `poll_after_ms` 再查询同一个任务。 成功后返回完整 MP4 文件路径，文件最大 200 MiB。查询需要原提交用户的 Ops 登录态和相同环境；任务引用与提交时的登录会话同时到期。 查询失败不重新生成。提交结果不确定时保留返回的 `request_id`；确认需要重试提交时，使用原 UUID 和完全相同的参数。

生图使用 `generate_image` 和 `get_image_generation`，支持文生图和参考图编辑：

```text
generate_image({"model":"gpt-image-2","prompt":"一张简洁的服装展示海报","aspect_ratio":"3:4","image_size":"1K"})
get_image_generation({"task_id":"生成返回的本机任务编号","output_dir":"/absolute/path/deliverables"})
```

生图同样要先确认模型在本环境目录中。可选参数为 `images`、`aspect_ratio`、`image_size` 和 `temperature`，显式的 `temperature: 0` 会原样传递。 MCP 在本机后台等待 Ops 的生图事件流，最长 10 分钟，等待期间须保持 MCP 运行。 结果包含全部图片、诊断文字和生成状态，原始有序事件保存在本机任务文件中。 断连、进程退出或缺少完整终态时返回失败或中断，不自动重新生成。

生成结果默认保存在 `~/.wgops-mcp/ops-generation/` 或 `~/.wgops-mcp/ops-generated/`； 查询时可用 `output_dir` 将完整媒体保存到交付目录，新文件不会覆盖已有文件。 这些工具仅供个人 Ops 登录会话使用，不向扫描或压测 Worker 开放。

## Wardrobe 深度推荐

从 0.21.0 起，`get_recommendation_task` 同时接受 Ops 独立推荐编号和 Wardrobe 原始任务编号。 原始编号查询 Hub 已登记的任务，完整 `pipeline.final_result` 需要配套 Ops 后端版本。

美东路演先运行 `ops-mcp login us_east`，在 AI 客户端重启升级后的 MCP，再调用：

```text
bind_region({"region":"us_east_exhibition"})
list_users({"q":"用户昵称或已知 user_id","limit":10})
```

使用查询返回的真实 `user_id`。每次新推荐生成一个 UUID，作为 `request_id`；同一次请求重试沿用原 UUID 和完整参数。

```text
generate_recommendation({"request_id":"本次请求的 UUID","user_id":"本环境的真实用户编号","query":"适合通勤的简洁搭配","outfit_count":2,"use_vton_video":false})
get_recommendation_task({"task_id":"返回的 ops-recommend-... 编号"})
get_recommendation_task({"task_id":"同一环境的 Wardrobe 原始 task_id"})
```

独立推荐的 `status=success` 表示完成，完整回调和产物在 `result` 中，最终产物在 `result.final_result`。 业务任务保留 Hub 的 `status`，如 `running`、`succeeded`、`failed`；Wardrobe 回调状态在 `pipeline.overall_status`，步骤在 `pipeline.steps`，最终产物在 `pipeline.final_result`。 查询只访问当前绑定环境；中国区编号不能在美东路演查询。缺少回调或查询失败不代表生成失败，也不能据此换编号重新生成。

`generate_recommendation` 会消耗模型资源并保存产物，使用 APP 模式，不推送镜子 UI。 `accepted`、`processing` 表示仍在进行；`submission_unknown`、`result_unknown` 表示尚未确认。 继续查询原编号，直到确认终态。服务端成功不代表镜子已经展示。

## 自动发版

相关代码合入 dev 后，`Publish Ops MCP to npm` 自动运行：检查两处版本一致且高于 npm latest， 跑测试、编译四平台、验证 npm 包，再使用仓库 Actions Secret NPM\_TOKEN 发布并回查 latest 与 gitHead。 同一源码提交重跑会跳过已发布版本，其他提交复用已发布版本会失败，要求先提升版本。 Token 仅在发布步骤注入 NODE\_AUTH\_TOKEN，不进入安装包；到期后更新仓库 Secret。 Secret 只需包级发布权限，无需组织管理权限。

## AI 压测历史与小数 QPS

绑定 `us_east_exhibition` 后：

-   `list_ai_load_tests({scenario:"deep_recommend",limit:5})`：按功能查询整轮 AI 历史目录与飞书报告摘要/链接。
-   `get_ai_load_test({ai_load_run_id:"目录返回的ID"})`：按需读取整轮配置、报告和各档 Run 事实。
-   继续用子 `run_id` 读取样本、Trace 和资源指标。历史工具只读，不启动测试。

`start_load_test` 的 `target_qps` 支持正小数，例如 0.5 表示每两秒新增一个任务。窗口开始即发首个请求，短窗口的实际速率须看 Run 真实计数。AI 发压身份仍只传 QPS 和时长，用户与生成配置由 Ops 冻结；个人会话需传用户名单。

## 常见问题

### @fragments\_awe/ops-mcp 是什么？

WG Ops MCP 本地AI客户端工具

### 如何安装 @fragments\_awe/ops-mcp？

在项目目录运行 npm install @fragments\_awe/ops-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ops-mcp，可以用 npx ops-mcp 直接运行。

### @fragments\_awe/ops-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fragments\_awe\_\_ops-mcp 是否存在。

### @fragments\_awe/ops-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fragments\_awe/ops-mcp 可以商用吗？

@fragments\_awe/ops-mcp 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @fragments\_awe/ops-mcp 的下载量有多少？

根据 npm 官方下载统计，@fragments\_awe/ops-mcp 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,702 次，日均约 123 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fragments\_awe/ops-mcp 还在维护吗？

最新版本 0\.24\.0 发布于 2026/11/15（今天）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/10/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。