用途
Fusion Help Documentation 是 Equinor Fusion 平台的一项文档编写与发布技能，用于指导应用团队通过 fhelp 命令行工具（fusion-help-cli）编写、组织并发布帮助文档，涵盖帮助文章（articles）、发布说明（release notes）和常见问题（FAQ）。
适用场景
适合以下任务：
- 为 Fusion 应用编写帮助文章
- 创建或更新发布说明
- 搭建文档文件夹结构与配置
- 为帮助系统组织 Markdown 内容
- 向 Fusion 环境发布或同步文档
- 添加 FAQ 条目
- 配置自动发布的 CI/CD 流水线
不适用于：修改 fusion-help-cli 源码（tooling/fusion-help-cli/）、更改 Fusion.Services.Help 后端 API、与 Fusion Help 无关的通用 Markdown 编辑，以及非文档类任务。
必要输入
创建文档前需收集以下信息：
- App key（必需）：Fusion 应用键（例如 my-app、resource-allocation-landingpage），用户必须是该应用的管理员。
- Content type（必需）：articles、release-notes 或 faqs。
- Docs root path（必需）：团队存放文档的路径（例如 docs/help/）。
- Target environment（发布时需要）：ci、fqa、tr 或 fprd。
若不确定 app key，可查看应用管理员页面：CI 环境为 https://fusion.ci.fusion-dev.net/apps/app-admin，生产环境为 https://fusion.equinor.com/apps/app-admin，在 "Admins" 区域确认自己是否被列为管理员，只有管理员才能发布。
主要能力与使用方式
1. 搭建文档目录结构
创建如下目录布局：
docs/ help/ articles/ # Markdown 文章文件 images/ # 文章图片（PNG 格式） release-notes/ # Markdown 发布说明文件 images/ # 发布说明图片（PNG 格式） faqs/ # 可选：Markdown FAQ 正文覆盖 help-articles.json # 文章配置 help-release-notes.json # 发布说明配置（如使用发布说明）
文件夹与配置名称可灵活调整，但必须与传给 fhelp 的参数一致。
2. 创建文章配置文件
创建 help-articles.json，用于告诉 CLI 同步哪些文章，包含字段 slug（必需，需与 .md 文件名匹配，使用 kebab-case）、title（必需）、appKey（必需）、sortOrder（可选，控制显示顺序，数字越小越靠前）、summary（必需）、tags（可选）、relevantApps（可选）。
3. 编写文章内容
在 articles 根目录创建 Markdown 文件，文件名（不含 .md）必须与配置中的 slug 一致。写作规范：面向 Fusion 应用最终用户；使用 ##、### 组织结构，避免使用 #（标题来自配置）；图片放在 images/ 目录并以 引用，CLI 会自动上传图片并将路径重写为 CDN 地址；图片必须为 PNG 格式（CLI 限制）；一篇文章一个主题；通过标题链接相关文章。
4. 创建发布说明配置文件（可选）
如团队发布 release notes，创建 help-release-notes.json，字段包括 slug（必需）、title（必需）、appKey（必需）、publishedDate（必需，ISO 8601 日期）、tags（可选）、relevantApps（可选）。
5. 安装并认证 CLI
从 Fusion Public 源安装：
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
更新已有安装：
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 认证：
az login
CLI 使用 DefaultAzureCredentials，会自动拾取 az login 会话。
6. 发布文档
同步文章：
fhelp article sync -f docs/help/help-articles.json -r docs/help/articles -e ci -v
同步发布说明：
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）。先在 ci 测试，再提升到 fqa 和 fprd。
7. 配置 CI/CD 流水线（推荐）
可通过 Azure DevOps 或 GitHub Actions 自动发布。资料提供了 Azure DevOps 流水线示例（含 install fusion help CLI、Sync help articles、Sync release notes 步骤）与 GitHub Actions 示例（含 checkout、Setup .NET、安装 CLI、Azure Login、Sync articles 步骤），可参考使用。
8. FAQ（补充）
FAQ 使用基于 Excel 的工作流，需要应用级访问权限，属于临时方案，适合 FAQ 跨多个应用的情况：
fhelp faq sync -f docs/help/faqs.xlsx -e ci -v
对多数团队而言，通过 Fusion Help Admin UI（https://fusion.equinor.com/apps/fusion-help-admin）管理 FAQ 更简单。
预期产出
- 包含文章、图片与配置的 docs/help/ 文件夹
- 内容规范的 Markdown 文章文件
- 有效的 help-articles.json（以及可选的 help-release-notes.json）
- 安装、认证与运行 fhelp 的说明
- CI/CD 流水线片段（可选）
使用限制与安全约束
- 不要在未理解后果的情况下使用 --no-validation，它可能覆盖 UI 创建的内容。
- 发布到 fprd 前先在 ci 测试。
- sourceSystem 会自动设为 Fusion.Help.Cli；CLI 与 UI 文章来源系统不同，除非使用 --no-validation，否则不会冲突。
- slug 必须全局唯一，建议使用应用专属前缀（例如 my-app-getting-started）。
- 切勿提交访问令牌，使用 az login 或流水线服务主体。
故障排查
- DefaultAzureCredential failed to retrieve a token：未认证，运行 az login。
- 403 Forbidden：不是该 app key 的管理员，检查应用管理员页面或配置中的 appKey。
- 文章未创建（被跳过）：根文件夹中没有匹配的 .md 文件，确保文件名与 slug 完全一致（{slug}.md）。
- 来源系统不匹配警告：文章通过 UI 创建，CLI 不会覆盖，谨慎使用 --no-validation 或改用其他 slug。
- 图片未上传：格式错误，图片必须为 PNG 格式。