fusion-core-services

Fusion Core Services

适用场景

当任务涉及一个或多个 Fusion Core 服务 API，且 Agent 需要确定合适的服务指南，无需单独安装技能时使用。

典型触发场景：

• 实现 Fusion API 客户端
• 接入 Fusion 后端服务
• 确定哪个 Fusion Core 服务负责某个工作流
• 解决跨服务任务，例如上下文与人员、角色与通知，或应用与服务消息

不适用场景

• 修改 fusion-core-services 中的代码
• 不涉及 Fusion 服务层的非 Fusion API 或通用 Microsoft Graph / Power BI 工作
• 已由 Fusion Core 服务之外的其他专用技能涵盖的独立产品工作流

必需输入

• 目标工作流或用户目标
• 目标使用方类型（react、typescript client、csharp httpclient、backend service 或其他）
• 已知的服务线索（如有）
• 相关的版本管理或授权预期

说明

1. 首先界定请求范围。

• 确定工作流涉及一个还是多个服务。
• 如果服务不明确，请先使用 agents/service-router.md 将工作流映射到可能涉及的服务，再提供实现指导。

2. 仅阅读相关服务参考资料。

• 从 综合 API 概览 开始。
• 然后打开匹配的单服务参考文件。
• 仅查阅对回答有实质影响的服务的端点目录和模型资源。

3. 在信任具体名称或结构前，先获取实时 OpenAPI 文档。

• 每个 Fusion Core 服务都会公开当前 OpenAPI 文档，无需 JWT： https://{service}.api.fusion.equinor.com/openapi/api-v{version}.json（例如 https://people.api.fusion.equinor.com/openapi/api-v3.json、 https://context.api.fusion.equinor.com/openapi/api-v1.json）。
• 随附的参考文件是服务／控制器索引，并说明了如何着手处理；它们并非准确架构／类型名称的事实来源，因为名称会随服务变化。请获取目标服务的实时文档，并查看 components.schemas 中的真实类型名称。响应通常采用 Api{Entity} 格式，请求正文通常采用 {Verb}{Entity}Request 这一普通名称，但应始终以实时文档中的确切名称为准，而不是依照模式推断；切勿臆造 components.schemas 中不存在的 Dto 后缀名称。
• 如果无法获取实时 OpenAPI 文档（没有网页抓取工具或网络访问权限），请明确说明这一限制，将随附参考资料／资源视为尽力而为的依据，并避免断言确切的架构／类型名称或必填字段。
• 如果服务目录中未列出子域名，请按照平台级规则，通过 Fusion 服务发现来解析，而不是猜测。平台级规则禁止硬编码服务地址。

4. 提供以源资料为依据的指导。

• 如果实时 OpenAPI 文档与随附参考文件中的“建议模型”列表不一致，应优先采用实时 OpenAPI 文档；它始终是最新的，随附文件可能已过时。
• 指出仍需直接核对源资料后才能发布的路由或模型区域。

5. 明确处理功能能力。

• 如果服务提供 OPTIONS 或其他访问探测路由，请使用它们来驱动具备能力感知的 UI 或变更逻辑。
• 如果服务没有提供稳定的探测路由，请记录保守的客户端行为，并将 403 Forbidden 视为备用能力信号。

6. 除非参考资料另有说明，否则将订阅视为仅供后端使用。

• /subscriptions/... 路由用于应用令牌事件注册和 CloudEvent 风格的变更处理，不用于普通前端 CRUD 流程。

7. 提供可供使用者直接采用的指导。

• 对前端使用者，提供与 TypeScript 兼容的模型（以真实架构名称命名，而非带 Dto 后缀的名称），以及最简客户端／Hook 模式。
• 对 .NET 使用者，提供一个强类型 HttpClient 方案，直接反序列化为实时文档中的真实架构类型（通常为 Api{Entity}，但应使用 components.schemas 中的实际名称），而不是手写影子记录；如果文档中公布了该类型，就应使用它。
• 对跨服务任务，说明服务调用顺序以及服务间的数据交接。

服务目录

• 应用：参考文档、端点目录、模型
• 书签：参考文档、端点目录、模型
• 上下文：参考文档、端点目录、模型
• 合同人员：参考文档、端点目录、模型
• 邮件：参考文档、端点目录、模型
• 通知：参考文档、端点目录、模型
• 人员：参考文档、端点目录、模型
• 门户配置：参考文档、端点目录、模型
• 报告：参考文档、端点目录、模型
• RolesV2：参考文档、端点目录、模型
• 服务消息：参考文档、端点目录、模型
• 任务：参考文档、端点目录、模型

预期输出

按以下顺序返回标题：

1. 范围检查
2. 服务选择
3. 端点映射
4. 模型映射
5. 消费方实现计划
6. 集成代码示例
7. 验证和测试说明
8. 风险与假设

安全与约束

绝不可：

• 臆造服务归属、路由或模型字段
• 臆造以 Dto 结尾的类型名称，或任何未实际出现在实时 OpenAPI 文档 components.schemas 中的名称——必须使用确切的真实名称，无论它遵循何种命名模式
• 在打包的 Fusion 参考资料有具体说明时，仍根据通用 SaaS/API 假设作答
• 将后端订阅路由视为常规前端交互流程

务必：

• 在命名类型前，先获取目标服务的实时 OpenAPI 文档——打包的参考文件可能过时，而实时文档不会
• 涉及多个服务时，明确说明跨服务推理
• 当服务提供 OPTIONS 时，说明能力探测行为
• 优先选择满足用户工作流所需的最少服务参考资料