fusion-help-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fusion Help Documentation

Fusion 帮助文档

Use this skill to help app teams author, structure, and publish help documentation (articles, release notes, FAQs) to the Fusion Help system using the

fhelp

CLI.

使用本技能帮助应用团队通过

fhelp

CLI 向Fusion帮助系统创作、结构化并发布帮助文档（文章、发布说明、常见问题）。

When to use

适用场景

User wants to write a help article for their Fusion app
User wants to create or update release notes
User wants to set up the docs folder structure and config file for their app
User needs help structuring markdown content for the help system
User wants to publish/sync documentation to a Fusion environment
User asks about FAQs or how to add FAQ entries
User wants to set up a CI/CD pipeline to auto-publish help docs

用户想要为其Fusion应用撰写帮助文章
用户想要创建或更新发布说明
用户想要为其应用搭建文档文件夹结构与配置文件
用户需要帮助为帮助系统结构化Markdown内容
用户想要将文档发布/同步到Fusion环境
用户询问常见问题或如何添加常见问题条目
用户想要搭建CI/CD流水线以自动发布帮助文档

When not to use

不适用场景

Modifying the
```
fusion-help-cli
```
source code itself (that lives in
```
tooling/fusion-help-cli/
```
)
Changing the Fusion.Services.Help backend API
General markdown editing unrelated to Fusion Help
Non-documentation tasks

修改
```
fusion-help-cli
```
源代码（代码位于
```
tooling/fusion-help-cli/
```
）
修改Fusion.Services.Help后端API
与Fusion Help无关的通用Markdown编辑
非文档类任务

Required inputs

必要输入

Before creating documentation, collect:

Input	Required	Description
App key	Yes	The Fusion app key (e.g. `my-app` , `resource-allocation-landingpage` ). User must be admin for this app.
Content type	Yes	`articles` , `release-notes` , or `faqs`
Docs root path	Yes	Where the team stores their docs (e.g. `docs/help/` )
Target environment	For publish	`ci` , `fqa` , `tr` , or `fprd`

If the user doesn't know their app key, point them to:

CI:

https://fusion.ci.fusion-dev.net/apps/app-admin

Production:

https://fusion.equinor.com/apps/app-admin

Open the app and look for the "Admins" section — you must be listed as admin to publish articles.

创建文档前，请收集以下信息：

输入项	是否必填	描述
应用密钥	是	Fusion应用密钥（例如 `my-app` , `resource-allocation-landingpage` ）。用户必须是该应用的管理员。
内容类型	是	`articles` （文章）、 `release-notes` （发布说明）或 `faqs` （常见问题）
文档根路径	是	团队存储文档的路径（例如 `docs/help/` ）
目标环境	发布时必填	`ci` 、 `fqa` 、 `tr` 或 `fprd`

如果用户不知道自己的应用密钥，可引导他们前往：

CI环境:

https://fusion.ci.fusion-dev.net/apps/app-admin

生产环境:

https://fusion.equinor.com/apps/app-admin

打开应用并查看“管理员”部分——只有被列为管理员才能发布文章。

Instructions

操作步骤

1. Set up docs folder structure

1. 搭建文档文件夹结构

Create the standard directory layout in the team's repository:

docs/
  help/
    articles/                    # Markdown article files
      images/                    # Article images (PNG format)
    release-notes/               # Markdown release note files
      images/                    # Release note images (PNG format)
    faqs/                        # Optional: markdown FAQ body overrides
    help-articles.json           # Article config
    help-release-notes.json      # Release notes config (if using release notes)

The actual folder names and config file names are flexible — they just need to match what you pass to
fhelp
. The above is a recommended convention.

在团队代码仓库中创建标准目录结构：

docs/
  help/
    articles/                    # Markdown文章文件
      images/                    # 文章图片（PNG格式）
    release-notes/               # Markdown发布说明文件
      images/                    # 发布说明图片（PNG格式）
    faqs/                        # 可选：Markdown常见问题内容覆盖文件
    help-articles.json           # 文章配置文件
    help-release-notes.json      # 发布说明配置文件（如果使用发布说明）

实际文件夹名称和配置文件名可灵活设置——只需与传递给
fhelp
的参数匹配即可。以上是推荐的约定。

2. Create the article config file

2. 创建文章配置文件

The config file tells the CLI which articles to sync and their metadata. Create

help-articles.json

jsonc

{
  "articles": [
    {
      "slug": "my-app-getting-started",        // Must match the .md filename (without extension)
      "title": "Getting Started",               // Display title in Fusion Help
      "appKey": "my-app",                       // Your Fusion app key
      "sortOrder": 1.0,                         // Controls display order (lower = first)
      "summary": "Learn how to get started.",   // Short description shown in article list
      "tags": ["getting-started", "onboarding"],// Searchable tags
      "relevantApps": []                        // Optional: other app keys where this shows
    }
  ]
}

配置文件用于告知CLI需要同步哪些文章及其元数据。创建

help-articles.json

：

jsonc

{
  "articles": [
    {
      "slug": "my-app-getting-started",        # 必须与.md文件名（不含扩展名）匹配
      "title": "Getting Started",               # 在Fusion Help中显示的标题
      "appKey": "my-app",                       # 你的Fusion应用密钥
      "sortOrder": 1.0,                         # 控制显示顺序（数值越小越靠前）
      "summary": "Learn how to get started.",   # 文章列表中显示的简短描述
      "tags": ["getting-started", "onboarding"],# 可搜索标签
      "relevantApps": []                        # 可选：该文章需要显示的其他应用密钥
    }
  ]
}

Config field reference

配置字段说明

Field	Required	Type	Description
`slug`	Yes	string	Unique identifier. Must match a `{slug}.md` file in the articles root folder. Use kebab-case.
`title`	Yes	string	Human-readable title displayed in Fusion Help.
`appKey`	Yes	string	Fusion app key this article belongs to. You must be admin for this app.
`sortOrder`	No	number	Controls display order. Lower numbers appear first. Default varies. Use decimals (1.0, 1.1, 2.0) for flexible ordering.
`summary`	Yes	string	Short description shown in article listings.
`tags`	No	string[]	Searchable tags for categorization.
`relevantApps`	No	string[]	Additional app keys where this article should appear.

字段	是否必填	类型	描述
`slug`	是	字符串	唯一标识符。必须与文章根文件夹中的 `{slug}.md` 文件匹配。使用短横线分隔命名法（kebab-case）。
`title`	是	字符串	在Fusion Help中显示的易读标题。
`appKey`	是	字符串	该文章所属的Fusion应用密钥。你必须是该应用的管理员。
`sortOrder`	否	数字	控制显示顺序。数值越小越靠前。默认值不定。使用小数（1.0、1.1、2.0）实现灵活排序。
`summary`	是	字符串	文章列表中显示的简短描述。
`tags`	否	字符串数组	用于分类的可搜索标签。
`relevantApps`	否	字符串数组	该文章需要显示的其他应用密钥。

3. Write article content

3. 撰写文章内容

Create markdown files in the articles root folder. The filename (without

.md

) must match the

slug

in the config.

Article writing guidelines:

Write in clear, concise language aimed at end-users of the Fusion app
Use headings (
```
##
```
,
```
###
```
) to structure content — avoid
```
#
```
as the title comes from config
Use images to illustrate UI workflows — place them in the
```
images/
```
subfolder
Image references in markdown use standard syntax:
```
![Alt text](images/my-screenshot.png)
```
The CLI automatically uploads images and rewrites paths to the Fusion CDN
Images must be PNG format — this is a current CLI limitation
Keep articles focused on a single topic or workflow
Link to related articles by mentioning their title (deep linking is handled by the platform)

Example article (

docs/help/articles/my-app-getting-started.md

markdown

undefined

在文章根文件夹中创建Markdown文件。文件名（不含

.md

）必须与配置中的

slug

匹配。

文章撰写指南：

使用清晰、简洁的语言，面向Fusion应用的终端用户
使用标题（
```
##
```
、
```
###
```
）结构化内容——避免使用
```
#
```
，因为标题来自配置文件
使用图片说明UI操作流程——将图片放在
```
images/
```
子文件夹中
Markdown中的图片引用使用标准语法：
```
![替代文本](images/my-screenshot.png)
```
CLI会自动上传图片并重写路径至Fusion CDN
图片必须为PNG格式——这是当前CLI的限制
文章内容聚焦于单个主题或操作流程
通过提及相关文章的标题进行链接（平台会处理深度链接）

示例文章 (

docs/help/articles/my-app-getting-started.md

markdown

undefined

Overview

概述

This guide walks you through the basics of using My App.

本指南将带你了解My App的基础使用方法。

Prerequisites

前提条件

Before you begin, make sure you have:

Access to the Fusion portal
The correct role assigned to your user

开始之前，请确保你已具备：

访问Fusion门户的权限
已被分配正确的用户角色

Step 1: Navigate to the app

步骤1：导航至应用

Open Fusion and search for "My App" in the app launcher.

打开Fusion并在应用启动器中搜索“My App”。

Step 2: Create your first item

步骤2：创建你的第一个项目

Click the New button in the toolbar to create your first item.

点击工具栏中的新建按钮创建你的第一个项目。

Need help?

需要帮助？

Contact the team on Teams or check the FAQ section.

undefined

在Teams上联系团队或查看常见问题板块。

undefined

4. Create the release notes config file (optional)

4. 创建发布说明配置文件（可选）

If the team publishes release notes, create

help-release-notes.json

jsonc

{
  "releaseNotes": [
    {
      "slug": "my-app-v2-release",              // Must match the .md filename
      "title": "Version 2.0 Release",           // Display title
      "appKey": "my-app",                       // Your Fusion app key
      "publishedDate": "2026-03-14T00:00:00Z",  // Publication date (ISO 8601)
      "tags": ["release", "v2"],                // Searchable tags
      "relevantApps": []                        // Optional: other app keys
    }
  ]
}

如果团队需要发布发布说明，请创建

help-release-notes.json

：

jsonc

{
  "releaseNotes": [
    {
      "slug": "my-app-v2-release",              # 必须与.md文件名匹配
      "title": "Version 2.0 Release",           # 显示标题
      "appKey": "my-app",                       # 你的Fusion应用密钥
      "publishedDate": "2026-03-14T00:00:00Z",  # 发布日期（ISO 8601格式）
      "tags": ["release", "v2"],                # 可搜索标签
      "relevantApps": []                        # 可选：其他应用密钥
    }
  ]
}

Release notes config field reference

发布说明配置字段说明

Field	Required	Type	Description
`slug`	Yes	string	Unique identifier. Must match a `{slug}.md` file in the release notes root folder.
`title`	Yes	string	Release note title.
`appKey`	Yes	string	Fusion app key. You must be admin.
`publishedDate`	Yes	ISO 8601 date	When the release was published.
`tags`	No	string[]	Searchable tags.
`relevantApps`	No	string[]	Additional app keys.

Example release note (

docs/help/release-notes/my-app-v2-release.md

markdown

undefined

字段	是否必填	类型	描述
`slug`	是	字符串	唯一标识符。必须与发布说明根文件夹中的 `{slug}.md` 文件匹配。
`title`	是	字符串	发布说明标题。
`appKey`	是	字符串	Fusion应用密钥。你必须是该应用的管理员。
`publishedDate`	是	ISO 8601日期	发布说明的发布日期。
`tags`	否	字符串数组	可搜索标签。
`relevantApps`	否	字符串数组	其他应用密钥。

示例发布说明 (

docs/help/release-notes/my-app-v2-release.md

markdown

undefined

What's new in Version 2.0

版本2.0新功能

New dashboard

全新仪表板

We've completely redesigned the dashboard with new charts and filtering capabilities.

我们彻底重新设计了仪表板，新增了图表和筛选功能。

Performance improvements

性能提升

Page load times reduced by 40%
Search results now appear in under 1 second

页面加载时间缩短40%
搜索结果现在可在1秒内显示

Bug fixes

问题修复

Fixed an issue where filters would reset on navigation
Corrected date formatting in the export feature

undefined

修复了导航时筛选器重置的问题
修正了导出功能中的日期格式

undefined

5. Install and authenticate the CLI

5. 安装并认证CLI

Install from the Fusion Public feed:

powershell

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

Update an existing installation:

powershell

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

Authenticate via Azure CLI:

powershell

az login

The CLI uses

DefaultAzureCredentials

— it will pick up your

az login

session automatically.

从Fusion公共源安装：

powershell

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

更新现有安装：

powershell

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

通过Azure CLI认证：

powershell

az login

CLI使用

DefaultAzureCredentials

——会自动获取你的

az login

会话。

6. Publish documentation

6. 发布文档

Sync articles:

powershell

fhelp article sync -f docs/help/help-articles.json -r docs/help/articles -e ci -v

Sync release notes:

powershell

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

Command flags:

Flag	Description
`-f` , `--file`	Path to the JSON config file
`-r` , `--root`	Path to the folder containing markdown files
`-e` , `--env`	Target environment: `ci` , `fqa` , `tr` , `fprd`
`-t` , `--token`	Override the access token (optional)
`-v` , `--verbose`	Show detailed logging output
`--no-validation`	Skip source system check — use with caution, can overwrite UI-created content

Environment promotion order:

ci

→

fqa

→

fprd

(skip

tr

unless testing infrastructure).

Always test in

ci

first before promoting to

fqa

and then

fprd

同步文章：

powershell

fhelp article sync -f docs/help/help-articles.json -r docs/help/articles -e ci -v

同步发布说明：

powershell

fhelp releasenotes sync -f docs/help/help-release-notes.json -r docs/help/release-notes -e ci -v

命令参数说明：

参数	描述
`-f` , `--file`	JSON配置文件的路径
`-r` , `--root`	包含Markdown文件的文件夹路径
`-e` , `--env`	目标环境： `ci` 、 `fqa` 、 `tr` 、 `fprd`
`-t` , `--token`	覆盖访问令牌（可选）
`-v` , `--verbose`	显示详细日志输出
`--no-validation`	跳过源系统检查——谨慎使用，可能会覆盖通过UI创建的内容

环境升级顺序：

ci

→

fqa

→

fprd

（除非测试基础设施，否则跳过

tr

）。

在发布到

fqa

和

fprd

之前，务必先在

ci

环境中测试。

7. Set up CI/CD pipeline (recommended)

7. 搭建CI/CD流水线（推荐）

Automate documentation publishing in your Azure DevOps pipeline or GitHub Actions workflow.

Azure DevOps pipeline example:

yaml

parameters:
  - name: environment
    type: string
    default: ci
    values: [ci, fqa, fprd]
  - name: azureSubscription
    type: string

steps:
  - checkout: self

  - script: |
      dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli
    displayName: "Install fusion help CLI"

  - task: AzureCLI@2
    displayName: "Sync help articles"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp article sync `
          -f ./docs/help/help-articles.json `
          -r ./docs/help/articles `
          -e "${{ parameters.environment }}" `
          -v

  - task: AzureCLI@2
    displayName: "Sync release notes"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp releasenotes sync `
          -f ./docs/help/help-release-notes.json `
          -r ./docs/help/release-notes `
          -e "${{ parameters.environment }}" `
          -v

GitHub Actions example:

yaml

name: Sync Help Documentation

on:
  push:
    branches: [main]
    paths: ['docs/help/**']

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install fusion help CLI
        run: |
          dotnet tool install --global \
            --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \
            Fusion.Help.Cli

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Sync articles
        run: |
          fhelp article sync \
            -f ./docs/help/help-articles.json \
            -r ./docs/help/articles \
            -e ci -v

在Azure DevOps流水线或GitHub Actions工作流中自动化文档发布。

Azure DevOps流水线示例：

yaml

parameters:
  - name: environment
    type: string
    default: ci
    values: [ci, fqa, fprd]
  - name: azureSubscription
    type: string

steps:
  - checkout: self

  - script: |
      dotnet tool install --global --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" Fusion.Help.Cli
    displayName: "安装fusion help CLI"

  - task: AzureCLI@2
    displayName: "同步帮助文章"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp article sync `
          -f ./docs/help/help-articles.json `
          -r ./docs/help/articles `
          -e "${{ parameters.environment }}" `
          -v

  - task: AzureCLI@2
    displayName: "同步发布说明"
    inputs:
      azureSubscription: ${{ parameters.azureSubscription }}
      scriptType: pscore
      scriptLocation: inlineScript
      inlineScript: |
        fhelp releasenotes sync `
          -f ./docs/help/help-release-notes.json `
          -r ./docs/help/release-notes `
          -e "${{ parameters.environment }}" `
          -v

GitHub Actions示例：

yaml

name: Sync Help Documentation

on:
  push:
    branches: [main]
    paths: ['docs/help/**']

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '8.0.x'

      - name: Install fusion help CLI
        run: |
          dotnet tool install --global \
            --add-source "https://statoil-proview.pkgs.visualstudio.com/Fusion%20-%20Packages/_packaging/Fusion-Public/nuget/v3/index.json" \
            Fusion.Help.Cli

      - name: Azure Login
        uses: azure/login@v2
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: '3aa4a235-b6e2-48d5-9195-7fcf05b459b0'
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      - name: Sync articles
        run: |
          fhelp article sync \
            -f ./docs/help/help-articles.json \
            -r ./docs/help/articles \
            -e ci -v

8. FAQs (supplementary)

8. 常见问题（补充）

FAQs use an Excel-based workflow and require app-level access. This is a temporary solution best suited for scenarios where FAQs span multiple apps.

powershell

fhelp faq sync -f docs/help/faqs.xlsx -e ci -v

For most teams, managing FAQs through the Fusion Help Admin UI at

https://fusion.equinor.com/apps/fusion-help-admin

is simpler.

常见问题使用基于Excel的工作流，需要应用级权限。这是一个临时解决方案，最适合常见问题跨多个应用的场景。

powershell

fhelp faq sync -f docs/help/faqs.xlsx -e ci -v

对于大多数团队来说，通过Fusion Help管理UI（

https://fusion.equinor.com/apps/fusion-help-admin

）管理常见问题更简单。

Expected output

预期输出

When this skill completes, the user should have:

A
```
docs/help/
```
folder structure with articles root, images folder, and config file(s)
One or more markdown article files with proper content

A valid

help-articles.json

(and optionally

help-release-notes.json

)

Knowledge of how to install, authenticate, and run
```
fhelp
```
to publish
Optionally, a CI/CD pipeline snippet for automated publishing

本技能完成后，用户应具备以下成果：

包含文章根目录、图片文件夹和配置文件的
```
docs/help/
```
文件夹结构
一个或多个内容规范的Markdown文章文件

有效的

help-articles.json

（可选

help-release-notes.json

）

掌握安装、认证和运行
```
fhelp
```
进行发布的方法
可选：用于自动化发布的CI/CD流水线代码片段

Troubleshooting

故障排查

Problem	Cause	Solution
`DefaultAzureCredential failed to retrieve a token`	Not authenticated	Run `az login`
`403 Forbidden`	Not an admin for the app key	Check admin list at the app admin page, or verify the `appKey` in your config
Article not created (skipped)	No matching `.md` file in root folder	Ensure filename matches slug exactly: `{slug}.md`
Source system mismatch warning	Article was created via UI, CLI won't overwrite	Use `--no-validation` carefully, or use a different slug
Images not uploading	Wrong format	Images must be PNG format

问题	原因	解决方案
`DefaultAzureCredential failed to retrieve a token`	未认证	运行 `az login`
`403 Forbidden`	不是应用密钥的管理员	查看应用管理页面的管理员列表，或验证配置中的 `appKey`
文章未创建（被跳过）	根文件夹中没有匹配的 `.md` 文件	确保文件名与slug完全匹配： `{slug}.md`
源系统不匹配警告	文章是通过UI创建的，CLI不会覆盖	谨慎使用 `--no-validation` ，或使用不同的slug
图片未上传	格式错误	图片必须为PNG格式

Safety & constraints

安全与约束

Never use
--no-validation
without understanding the consequences — it can overwrite content that was manually created through the Fusion Help Admin UI
Always test in
```
ci
```
before publishing to
```
fprd
```
(production)
The
```
sourceSystem
```
is automatically set to
```
Fusion.Help.Cli
```
— articles created by the CLI and articles created via the UI have different source systems and won't conflict unless
```
--no-validation
```
is used
Slugs must be globally unique across all apps — use an app-specific prefix (e.g.
```
my-app-getting-started
```
)
Do not commit access tokens to source control — rely on
```
az login
```
or pipeline service principals

务必在理解后果后再使用
--no-validation
——它会覆盖通过Fusion Help管理UI手动创建的内容
发布到
```
fprd
```
（生产环境）前务必在
```
ci
```
环境中测试
```
sourceSystem
```
会自动设置为
```
Fusion.Help.Cli
```
——通过CLI创建的文章和通过UI创建的文章源系统不同，除非使用
```
--no-validation
```
，否则不会冲突
Slug必须在所有应用中全局唯一——使用应用特定前缀（例如
```
my-app-getting-started
```
）
不要将访问令牌提交到源代码管理——依赖
```
az login
```
或流水线服务主体