fusion-devtools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fusion DevTools

When to use

适用场景

Use when you need to interact with Fusion platform services from the command line — calling APIs, getting tokens, discovering services, or looking up persons.

Typical triggers:

"Call the People API"
"Get a token for the context service"
"Which services are available in production?"
"Test this endpoint"
"Resolve this person's Azure ID"
"What's the base URL for the org service?"
"Get me an access token I can pipe to jq"

Implicit triggers:

Agent needs to verify an API contract or response shape
Agent needs a bearer token for an HTTP request
Agent needs to find which service key maps to a URL
Agent needs to look up a person's identity for test data

当你需要通过命令行与Fusion平台服务交互时使用——调用API、获取令牌、发现服务或查询人员信息。

典型触发场景：

"调用People API"
"获取Context服务的令牌"
"生产环境中有哪些可用服务？"
"测试这个端点"
"解析此人的Azure ID"
"Org服务的基础URL是什么？"
"给我一个可以通过管道传递给jq的访问令牌"

隐含触发场景：

Agent需要验证API契约或响应格式
Agent需要用于HTTP请求的Bearer令牌
Agent需要查找哪个服务密钥对应某个URL
Agent需要查询人员身份以生成测试数据

When not to use

不适用场景

Modifying backend service source code — use the service repo directly
Deploying or publishing services — use CI/CD pipelines
Infrastructure provisioning — use Terraform/Bicep
Service Bus / SignalR debugging — use Azure portal or dedicated tooling
Managing AI search indexes — separate ops concern

修改后端服务源代码——直接使用服务代码仓库
部署或发布服务——使用CI/CD流水线
基础设施配置——使用Terraform/Bicep
Service Bus / SignalR调试——使用Azure门户或专用工具
管理AI搜索索引——属于独立的运维范畴

Prerequisites

前置条件

Install fdev as a .NET global tool:

bash

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools

Update to latest:

bash

dotnet tool update --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools

Authenticate before first use:

bash

fdev login

将fdev安装为.NET全局工具：

bash

dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools

更新至最新版本：

bash

dotnet tool update --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" fusion-devtools

首次使用前进行身份验证：

bash

fdev login

Core workflows

核心工作流

1 — Call a Fusion REST API

1 — 调用Fusion REST API

Use

fdev rest

to call any Fusion service. Service discovery resolves the base URL and acquires a token automatically.

bash

fdev rest <serviceKey> '<path>'

The path must be quoted in zsh/bash to prevent

glob expansion.

Examples:

bash

undefined

使用

fdev rest

调用任意Fusion服务。服务发现会自动解析基础URL并获取令牌。

bash

fdev rest <serviceKey> '<path>'

在zsh/bash中，路径必须加引号以避免

触发通配符扩展。

示例：

bash

undefined

GET from people service (production)

从People服务（生产环境）发起GET请求

fdev rest people '/persons/me?api-version=3.0'

POST with JSON body

带JSON请求体的POST请求

fdev rest context '/contexts?api-version=1.0' -m post -b '{"query":"test"}'

POST with body from file

从文件读取请求体的POST请求

fdev rest people '/persons/search?api-version=3.0' -m post -b @request.json

Different environment

指定其他环境

fdev rest people '/persons/me?api-version=3.0' -e ci

Save response to file

将响应保存到文件

fdev rest people '/persons/me?api-version=3.0' -o response.json

Full URL mode (skip discovery)

完整URL模式（跳过服务发现）

fdev rest --url https://httpbin.org/get --no-auth

Custom scope override

自定义权限范围覆盖

fdev rest people '/persons/me?api-version=3.0' --scope api://my-app/.default


Key options: `-m` method, `-b` body (`@file` supported), `-e` environment, `--url` full URL mode, `--no-auth` skip auth, `--scope` override scope, `-o` output file, `--header KEY=VALUE`.

fdev rest people '/persons/me?api-version=3.0' --scope api://my-app/.default


关键选项：`-m` 指定请求方法，`-b` 请求体（支持`@file`格式），`-e` 指定环境，`--url` 完整URL模式，`--no-auth` 跳过身份验证，`--scope` 覆盖权限范围，`-o` 输出文件，`--header KEY=VALUE` 设置请求头。

2 — Get an access token

2 — 获取访问令牌

Use

fdev get-access-token

for structured JSON token output, similar to

az account get-access-token

. Output is pipe-friendly.

bash

undefined

使用

fdev get-access-token

获取结构化JSON格式的令牌输出，类似

az account get-access-token

。输出支持管道传递。

bash

undefined

Token for a specific service (resolves scope via discovery)

针对特定服务的令牌（通过服务发现解析权限范围）

fdev get-access-token --service-key people

Token with explicit scope

带明确权限范围的令牌

fdev get-access-token --scope api://97978493-9777-4d48-b38a-67b0b9cd88d2/.default

Extract just the token

只提取令牌内容

fdev get-access-token --service-key people | jq -r '.accessToken'


Output format:

```json
{
  "accessToken": "eyJ...",
  "expiresOn": "2026-05-15T12:00:00+00:00",
  "expiresOnUnix": 1778846400,
  "scope": "api://app-id/.default",
  "tokenType": "Bearer"
}

fdev get-access-token --service-key people | jq -r '.accessToken'


输出格式：

```json
{
  "accessToken": "eyJ...",
  "expiresOn": "2026-05-15T12:00:00+00:00",
  "expiresOnUnix": 1778846400,
  "scope": "api://app-id/.default",
  "tokenType": "Bearer"
}

3 — Discover services and environments

3 — 发现服务与环境

bash

undefined

bash

undefined

List all environments

列出所有环境

fdev disc envs

List services in an environment (JSON output)

列出某环境中的服务（JSON输出）

Note: disc subcommand uses single-dash flags (-json, -out) — this is by design

注意：disc子命令使用单横线标志（-json, -out）——这是有意设计的

fdev disc env list fprd -json

List services showing key and URI

列出服务并显示密钥和URI

fdev disc env list fprd -out ku

undefined

fdev disc env list fprd -out ku

undefined

4 — Look up a person

4 — 查询人员信息

bash

undefined

bash

undefined

Resolve by email

通过邮箱解析人员信息

fdev persons resolve user@equinor.com

Search by name

通过名称搜索人员

fdev persons search "John"

undefined

fdev persons search "John"

undefined

5 — Activate PIM role

5 — 激活PIM角色

Elevate Azure access when needed for admin operations:

bash

fdev pim azure activate

Safety: always confirm with the user before running PIM activation — this grants elevated access.

需要提升Azure访问权限以执行管理员操作时使用：

bash

fdev pim azure activate

安全提示：执行PIM激活前务必与用户确认——此操作会授予提升的访问权限。

6 — Get a raw JWT token (clipboard)

6 — 获取原始JWT令牌（复制到剪贴板）

For quick clipboard-based token workflows (existing command):

bash

fdev token          # test environment token
fdev token --prod   # production token

适用于快速的剪贴板令牌工作流（现有命令）：

bash

fdev token          # 测试环境令牌
fdev token --prod   # 生产环境令牌

Instructions

使用步骤

Step 1 — Confirm fdev is available

步骤1 — 确认fdev可用

Before using any fdev command, verify it is installed:

bash

fdev --version

If not installed, show the install command from Prerequisites. If authentication is needed, run

fdev login

使用任何fdev命令前，先验证是否已安装：

bash

fdev --version

若未安装，展示前置条件中的安装命令。若需要身份验证，运行

fdev login

。

Step 2 — Choose the right command

步骤2 — 选择正确的命令

Need	Command
Call a Fusion API and see the response	`fdev rest <service> '<path>'`
Get a token for scripting/piping	`fdev get-access-token --service-key <key>`
Find available services	`fdev disc env list <env>`
Find service base URL and scope	`fdev disc env list <env> -json` then filter by key
Look up a person	`fdev persons resolve <email>`
Quick clipboard token	`fdev token`

需求	命令
调用Fusion API并查看响应	`fdev rest <service> '<path>'`
获取用于脚本/管道传递的令牌	`fdev get-access-token --service-key <key>`
查找可用服务	`fdev disc env list <env>`
查找服务基础URL和权限范围	`fdev disc env list <env> -json` 然后按密钥过滤
查询人员信息	`fdev persons resolve <email>`
快速获取剪贴板令牌	`fdev token`

Step 3 — Use verbose mode for debugging

步骤3 — 使用详细模式调试

Add

--verbose

to any command for diagnostic output including cache hit/miss, full request/response headers, and token details.

bash

fdev rest people '/persons/me?api-version=3.0' --verbose

在任意命令后添加

--verbose

以获取诊断输出，包括缓存命中/未命中、完整请求/响应头以及令牌详情。

bash

fdev rest people '/persons/me?api-version=3.0' --verbose

Step 4 — Bypass cache when needed

步骤4 — 必要时绕过缓存

Service discovery results are cached locally (environments: 24h, services: 1h). Use

--no-cache

to force fresh lookups:

bash

fdev rest people '/persons/me?api-version=3.0' --no-cache

服务发现结果会在本地缓存（环境：24小时，服务：1小时）。使用

--no-cache

强制刷新查询：

bash

fdev rest people '/persons/me?api-version=3.0' --no-cache

Environments

环境说明

Key	Purpose	Notes
`ci`	Continuous integration / development	Least stable, latest changes
`fqa`	Quality assurance	Pre-production validation
`fprd`	Production	Default environment

Default environment is

fprd

for all commands. Override with

-e <env>

密钥	用途	备注
`ci`	持续集成/开发环境	稳定性最低，包含最新变更
`fqa`	质量保证环境	用于预生产验证
`fprd`	生产环境	默认环境

所有命令的默认环境为

fprd

。可通过

-e <env>

覆盖。

Reference guides

参考指南

See

references/

for detailed command options and workflow recipes:

```
command-reference.md
```
— compact command cheat sheet with all options
```
agentic-patterns.md
```
— common agentic workflow recipes

查看

references/

目录获取详细的命令选项和工作流示例：

```
command-reference.md
```
— 包含所有选项的简洁命令速查表
```
agentic-patterns.md
```
— 常见Agent工作流示例

Safety

安全注意事项

This skill is mutation-capable. Repository-local workflow instructions take precedence over inline guidance when they conflict.
Never expose raw access tokens in output shown to users — truncate or redact when displaying
Always quote paths containing
```
?
```
in shell commands to prevent glob expansion
Use
```
--no-auth
```
only for genuinely public endpoints
Confirm with the user before running
```
fdev pim azure activate
```
(elevated access)
Do not store or log tokens to files unless explicitly requested

此工具支持修改操作。当仓库本地工作流说明与本文内联指南冲突时，以仓库本地说明为准。
向用户展示输出时，绝不能暴露原始访问令牌——显示时需截断或脱敏
在shell命令中，包含
```
?
```
的路径必须加引号以避免通配符扩展
仅对真正的公开端点使用
```
--no-auth
```
执行
```
fdev pim azure activate
```
前务必与用户确认（此操作会授予提升的访问权限）
除非明确要求，否则不要将令牌存储或记录到文件中