fusion-devtools

Fusion DevTools

适用场景

当你需要从命令行与 Fusion 平台服务交互时使用，例如调用 API、获取令牌、发现服务或查找人员。

典型触发语句：

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

隐式触发场景：

• Agent 需要验证 API 契约或响应结构
• Agent 需要为 HTTP 请求获取持有者令牌
• Agent 需要查找哪个服务键对应某个 URL
• Agent 需要查找人员身份以用于测试数据

不适用场景

• 修改后端服务源代码——直接使用服务仓库
• 部署或发布服务——使用 CI/CD 管道
• 配置基础设施——使用 Terraform/Bicep
• 调试 Service Bus / SignalR——使用 Azure 门户或专用工具
• 管理 AI 搜索索引——这是单独的运维事项

前提条件

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

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

更新到最新版本：

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

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

fdev login

核心工作流

1 — 调用 Fusion REST API

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

fdev rest <serviceKey> '<path>'

在 zsh/bash 中必须将路径加引号，以防止 ? 被展开为通配符。

示例：

# GET from people service (production)
fdev rest people '/persons/me?api-version=3.0'

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

# POST with body from file
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)
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

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

2 — 获取访问令牌

使用 fdev get-access-token 获取结构化 JSON 令牌输出，类似于 az account get-access-token。输出适合通过管道传递。

# 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'

输出格式：

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

3 — 发现服务和环境

# List all environments
fdev disc envs

# List services in an environment (JSON output)
# Note: disc subcommand uses single-dash flags (-json, -out) — this is by design
fdev disc env list fprd -json

# List services showing key and URI
fdev disc env list fprd -out ku

4 — 查找人员

# Resolve by email
fdev persons resolve [email protected]

# Search by name
fdev persons search "John"

5 — 激活 PIM 角色

在管理操作需要时提升 Azure 访问权限：

fdev pim azure activate

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

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

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

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

使用说明

第 1 步 — 确认 fdev 可用

使用任何 fdev 命令前，先确认它已安装：

fdev --version

如果尚未安装，请显示“前提条件”中的安装命令。如果需要身份验证，请运行 fdev login。

第 2 步 — 选择合适的命令

需求	命令
调用 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

第 3 步 — 使用详细模式进行调试

在任意命令中添加 --verbose，即可查看诊断输出，包括缓存命中/未命中、完整的请求/响应标头以及令牌详细信息。

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

第 4 步 — 按需绕过缓存

服务发现结果会缓存在本地（环境：24h，服务：1h）。使用 --no-cache 强制执行实时查询：

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

环境

键	用途	备注
ci	持续集成 / 开发	稳定性最低，包含最新更改
fqa	质量保证	生产前验证
fprd	生产环境	所有命令的默认环境

所有命令的默认环境均为 fprd。使用 -e <env> 覆盖。

参考指南

详细的命令选项和工作流示例请参阅 references/：

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

安全

• 此技能具有修改能力。发生冲突时，仓库本地工作流说明优先于行内指导。
• 面向用户显示输出时，绝不公开原始访问令牌；显示时应截断或脱敏
• Shell 命令中包含 ? 的路径始终加引号，以防止 glob 扩展
• 仅对确实公开的端点使用 --no-auth
• 运行 fdev pim azure activate（需要提升权限）前，先征得用户同意
• 除非用户明确要求，否则不要将令牌存储或记录到文件中