mcpField
F
fusion-help-api

fusion-help-api

github.com/equinor开发915 次安装
代码仓库

关于 fusion-help-api

面向开发者和管理员，指导通过 Fusion Help REST API 读取、搜索及管理帮助内容。它涵盖认证、权限、版本化端点和集成示例，支持应用内展示或自动化内容管理。

主要功能

  1. 01读取文章、FAQ 和发布说明
  2. 02搜索与建议帮助内容
  3. 03创建、更新和删除内容
  4. 04管理图片资源与变更记录
  5. 05说明认证、权限和端点

适用场景

  1. 01在 Fusion 应用中展示帮助内容
  2. 02构建内容管理命令行工具
  3. 03自动化帮助文档维护
  4. 04为应用添加帮助搜索

MCP 相关

该技能说明如何调用 Fusion Help REST API；输入中未提及 MCP 集成。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/equinor/fusion-skills --skill fusion-help-api

安装后在 Claude Code 中输入/fusion-help-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

CHANGELOG.md
references/
api-endpoints.md
api-quick-reference.md
authentication.md
integration-patterns.md
response-models.md

详细介绍

Fusion Help API

当开发者或管理员需要直接与 Fusion Help REST API 交互时使用——例如读取帮助内容、构建自定义工具，或自动化管理内容。

适用场景

  • 在 Fusion 应用中显示帮助文章、常见问题解答或发行说明
  • 构建自定义命令行工具或自动化流程来管理帮助内容
  • 以编程方式创建、更新或删除帮助文档
  • 在应用中搜索或推荐帮助内容
  • 了解 Help API 端点、身份验证或数据模型
  • 读取其他系统的帮助内容

不适用场景

  • 使用 fhelp CLI 同步 markdown 文档 → 使用 fusion-help-docs
  • 修改 Fusion.Services.Help 后端服务代码
  • 与 Help 无关的一般 REST API 问题

必需输入

输入必需描述
使用场景是读取、管理或搜索内容
App key范围限定查询时必需要读取或管理其帮助内容的 Fusion 应用 key
目标环境是ci、fqa、tr 或 fprd
身份验证上下文是用户令牌（交互式）或服务主体（自动化）

操作说明

1. 发现 Help API 基础 URL

动态解析 URL，或使用已知模式：

环境基础 URL
cihttps://help.ci.api.fusion-dev.net
fqahttps://help.fqa.api.fusion-dev.net
fprdhttps://help.api.fusion.equinor.com

动态发现（生产工具推荐）：

GET https://discovery.fusion.equinor.com/service-registry/environments/{env}/services

在响应中查找 key: "help" 的服务，并使用 uri 字段作为基础 URL。

2. 身份验证

所有端点都需要有效的 Azure AD bearer token。前端、后端和 CLI 的令牌受众及代码示例请参阅 references/authentication.md。

快速参考 — 令牌受众：

环境资源 ID（受众）
ci、fqa、tr5a842df8-3238-415d-b168-9f16a6a6031b/.default
fprd97978493-9777-4d48-b38a-67b0b9cd88d2/.default
3. 授权级别
操作执行权限
读取文章、常见问题解答、发行说明、搜索任何通过身份验证的 Fusion 用户
创建 / 更新 / 删除文章、常见问题解答、发行说明应用管理员、受信任应用或 Fusion.Help.FullControl
上传资源（图片）应用管理员、受信任应用或 Fusion.Help.FullControl
查看变更日志（全局）仅限 Fusion.Help.FullControl
查看变更日志（按应用）应用管理员或 Fusion.Help.FullControl
4. 调用 API

端点采用版本控制——请包含 ?api-version=1.0。资源：文章、常见问题解答、发行说明、资源、搜索/推荐、变更日志。

完整的 CRUD 详情、请求/响应正文、OData 筛选器和验证规则，请参阅 references/api-endpoints.md。

精简的端点矩阵和 OData 速查表，请参阅 references/api-quick-reference.md。

响应模型架构请参阅 references/response-models.md。

5. 集成模式

可直接使用的代码示例（React 组件、发行说明横幅、常见问题搜索、C# 后端自动化、Python 脚本）请参阅 references/integration-patterns.md。

预期输出

  • 可运行的身份验证及调用 Help API 代码
  • 符合使用场景的正确端点 URL 和查询参数
  • 了解响应模型和 OData 查询选项
  • 管理员使用场景：正确的创建/更新/删除请求正文
  • 集成模式：相关语言/框架的示例代码

安全与限制

  • 任何经过身份验证的用户都可以安全地访问只读端点——无需管理员权限
  • 写入操作需要应用管理员、受信任的应用程序或 Fusion.Help.FullControl
  • 已删除的文章/FAQ/发行说明为软删除状态——其 slug 无法重复使用
  • sourceSystem 用于跟踪创建记录的工具——同一 slug 混用不同的来源系统会导致 fhelp CLI 拒绝更新（除非使用 --no-validation）
  • 始终先在 ci 环境中测试，再以 fprd 为目标
  • 切勿硬编码 bearer 令牌——请使用 DefaultAzureCredential 或等效方式
  • 上传的图片必须为 PNG；API 会将其处理为 WebP 格式以供展示

评论

支持 Markdown