fusion-app-react-dev

已弃用 — 此技能已重命名为 fusion-developer-app。 安装替代技能：npx -y skills add equinor/fusion-skills --skill fusion-developer-app 此技能将在未来版本中移除。

Fusion 应用开发

适用场景

在 Fusion Framework React 应用中开发功能、组件、钩子、服务或类型时，使用此技能。

常见触发语句：

• “添加一个用于……的组件”
• “创建一个……钩子”
• “接入 API”
• “构建一个……页面”
• “添加一个用于获取……的服务”
• “配置一个 Fusion 模块”
• “此应用应该使用哪个 Fusion Framework 钩子？”
• “此应用集成应该使用哪个包或模块？”
• “在实现此应用更改之前，找到正确的 Fusion Framework 示例”
• “将此偏好设置保存为应用设置”
• “为此视图添加书签支持”
• “读取运行时配置或环境变量”
• “为此页面添加分析埋点”
• “为此应用添加功能标志”
• “如何在 Fusion 应用中使用 useFeature 钩子？”
• “实现一个……功能”

隐式触发条件：

• 用户要求在 src/ 中构建内容
• 用户提及 Fusion Framework 模块、EDS 组件、Fusion React 组件（@equinor/fusion-react-*）或 styled-components 模式
• 用户提及应用设置、书签、分析或 app.config.ts
• 用户想要添加新路由、页面或数据获取层

不适用场景

以下情况不要使用此技能：

• 编写或分类问题（使用 fusion-issue-authoring）
• 编写技能（使用 fusion-skill-authoring）
• 后端／服务更改（位于独立代码库）
• CI/CD 流水线或部署配置
• 架构文档（使用 ADR 模板）

如果请求主要涉及 Fusion Framework 包的归属、钩子行为或示例查找，而非应用实现，请先使用配套技能 fusion-research，然后返回此处进行代码更改。

必需输入

必填

• 要构建的内容：对功能、组件、钩子或服务的清晰描述
• 所属位置：所在层（组件、钩子、服务、类型）以及相关的父级／同级上下文

如果用户的请求含糊不清或缺少关键信息，请在实现之前查阅 assets/follow-up-questions.md，了解针对该领域的澄清问题。

条件必填

• 功能涉及数据获取时提供 API 端点详情
• 构建视觉组件时提供设计／布局细节
• 扩展模块配置时提供 Fusion 模块名称
• 说明状态应按用户持久化、通过书签共享，还是仅在运行时保留

说明

步骤 1 — 了解项目惯例

编写任何代码之前，请检查目标代码库，了解其具体设置：

1. 阅读 package.json，确定包管理器（bun/pnpm/npm）、可用脚本和已安装的依赖项。
2. 阅读 tsconfig.json，确认 TypeScript 设置和路径别名。
3. 扫描 src/，了解当前目录布局和分层结构。
4. 检查 ADR（docs/adr/）或 contribute/ 目录，查找项目特定的代码规范。
5. 检查格式化工具／代码检查工具配置（biome.json、.eslintrc、prettier 配置）。
6. 阅读 app.config.ts 和 app.manifest.ts，了解现有端点和环境设置。
7. 如果实现依赖不确定的 Fusion Framework 行为、确切的包归属或示例，请在编写代码之前委派给 fusion-research 进行调研。

根据此处发现的惯例调整所有后续步骤。references/ 中的模式仅为默认方案；如果项目特定规则与之不同，请以项目规则为准。

步骤 2 — 规划实现

如果要从零开始搭建新应用，请使用 assets/new-app-checklist.md 跟踪进度。

1. 将工作拆分为明确的文件或变更。
2. 将每项工作映射到正确的目录。典型的 Fusion 应用会使用：
   • src/components/ — React 组件（表示层）
   • src/hooks/ — 自定义 React Hook（状态和副作用逻辑）
   • src/api/ — API 客户端、数据转换、业务逻辑
   • src/types/ — TypeScript 接口、类型别名、枚举
   • src/routes.ts — 路由定义（使用 Fusion Router 时）
   • src/config.ts — Fusion 模块配置
   • src/App.tsx — 根组件、布局外壳
3. 尽早确定共享类型——在引用之前先定义它们。
4. 如果项目使用路由，请遵循 references/using-router.md 中的 DSL 和页面模式。
5. 如果项目使用不同的结构，请遵循该结构。

步骤 3 — 遵循代码约定进行实现

遵循项目的代码规范（在步骤 1 中发现）。对于所有约定规则——命名、TSDoc、行内注释、类型模式、代码风格和错误处理——请以 fusion-code-conventions 技能为准。

在实现过程中遇到约定相关的问题时，请直接调用 fusion-code-conventions。它会路由到正确的语言 Agent，并返回权威规则及示例。

步骤 4 — 使用 styled-components、EDS 和 Fusion React 组件设置样式

遵循 references/styled-components.md、references/styling-with-eds.md 和 references/using-fusion-react-components.md：

• 使用 styled-components 自定义样式——这是 Fusion 生态系统的约定。
• 除非项目明确使用，否则不要引入 CSS Modules、全局 CSS 文件、Tailwind 或其他 CSS-in-JS 方案。
• 对同置的样式化组件使用 Styled 对象模式。
• 对于标准 UI 元素，优先使用来自 @equinor/eds-core-react 的 EDS 组件作为基础。
• 使用 EDS 设计令牌（CSS 自定义属性或 @equinor/eds-tokens）设置颜色、间距和字体排版。
• 需要自定义时，使用 styled() 扩展 EDS 组件。
• 对于 EDS 未涵盖的特定领域需求（人员展示/选择、Fusion 侧边面板和进度指示器），使用 Fusion React 组件（@equinor/fusion-react-*）。
• 行内 style 属性仅适用于一次性微调。

步骤 5 — 接入数据获取（如适用）

遵循 references/configure-services.md、references/using-react-query.md 和 references/configure-mocking.md 中的数据获取和本地开发模拟模式：

• 通过 config.ts 中的 configureHttpClient 或通过 app.config.ts 端点注册 HTTP 客户端。
• 在组件中使用 @equinor/fusion-framework-react-app/http 中的 useHttpClient(name) 访问客户端。
• 始终优先使用 @equinor/fusion-framework-react-app/* Hook（useHttpClient、useCurrentContext 等），而不是直接访问模块。仅在路由加载器等非 React 上下文中使用 framework.modules.*。
• 当项目使用 React Query（@tanstack/react-query）时，请围绕 useQuery 创建轻量的自定义 Hook 包装器。
• 使用由 API 路径和参数派生的查询键。
• 将客户端 UI 状态保存在 React 状态/上下文中，而不是服务器状态库中。

第 6 步 — 配置 Fusion 模块（如适用）

确定用户需要哪个模块，然后只阅读匹配的参考文档：

需求	参考文档
HTTP 客户端 / API 集成	references/configure-services.md
上下文模块	references/using-context.md
路由器和页面	references/using-router.md
AG Grid	references/using-ag-grid.md
EDS + Fusion React 组件	references/using-fusion-react-components.md
设置	references/using-settings.md
书签	references/using-bookmarks.md
分析	references/using-analytics.md
运行时配置 / 环境	references/using-assets-and-environment.md
功能标志	references/using-feature-flags.md
通用框架模块	references/using-framework-modules.md

• 使用 AppModuleInitiator 回调在 config.ts 中添加模块设置。
• 在组件中通过钩子访问模块：useAppModule、useHttpClient、useCurrentContext。
• 添加新的 API 集成时，在 app.config.ts 中注册 HTTP 客户端端点。
• 如果应用使用路由，则在 config.ts 中通过 enableNavigation 启用导航。
• 使用 Fusion Router DSL（layout、index、route、prefix）定义路由，以实现自动代码分割。
• 如果不清楚应使用哪个框架 API，请先使用 fusion-research 收集有来源支持的答案，再选择实现模式。

第 7 步 — 验证

使用 assets/review-checklist.md 作为全面的生成后检查清单。

1. 运行项目的类型检查命令（例如 bun run typecheck 或 pnpm typecheck）——必须零错误。
2. 运行项目的 lint/格式检查——不得有任何违规项。
3. 验证每个新增的导出符号都有 TSDoc。
4. 确认样式符合项目规范。
5. 确认没有新增依赖，除非有充分理由或已明确批准。

预期输出

• 在 src/ 中新增或修改的源文件，遵循项目的分层结构。
• 所有文件均通过类型检查和 lint。
• 每个导出的函数、组件、钩子和类型都有 TSDoc。
• 样式符合项目规范（通常在适用时使用 styled-components + EDS + Fusion React 组件）。
• 简要说明创建或修改了哪些内容，以及原因。

辅助 Agent

此技能包含 agents/ 中的三个可选辅助 Agent。可在实现更改后使用它们进行专项审查，也可在实现期间咨询它们以获取特定指导。如果运行环境不支持技能本地 Agent，请直接应用相同的审查标准。

此技能还有一个配套技能 fusion-research，用于基于来源研究 Fusion 生态系统。如果实现工作因不确定框架行为、EDS 组件 API 或技能目录问题而受阻，请使用它。

• agents/framework.md — 审查 Fusion Framework 集成：模块配置、HTTP 客户端、引导生命周期、运行时配置、设置、书签、分析和钩子用法。API 查询优先使用 mcp_fusion_search_framework；一般平台指导则改用 mcp_fusion_search_docs。在配置 config.ts、app.config.ts 或任何访问框架模块的组件时，请参考此文档。
• agents/styling.md — 审查 EDS 组件选择、styled-components 模式、设计令牌用法和无障碍性。组件文档、属性和示例优先使用 mcp_fusion_search_eds。在构建或修改视觉组件时，请参考此文档。
• agents/code-quality.md — 将规范检查（命名、TSDoc、TypeScript 严格性、意图注释）委托给 fusion-code-conventions，然后结合 Fusion 应用上下文汇总检查结果。定稿前，对每个新增或修改的文件运行此检查。

安全与约束

• 未经用户明确批准，不添加新依赖。
• 不直接操作 DOM——使用 React 模式。
• 不使用 any 类型——Fusion 应用默认采用 TypeScript 严格模式。
• 源文件中不得包含密钥或凭据。
• 所有更改都使用 Conventional Commits（feat:、fix:、refactor: 等）。
• 除非明确要求，否则不要修改基础设施文件（docker-compose、CI 配置）。