在 Fusion Framework React…

当需要在 Fusion Framework React 应用（基于 @equinor/fusion-framework-cli）中新增或修改功能、组件、Hook、服务、模块配置及其测试时，按此流程执行。

适用场景

解决思路

1. 第 1 步——先摸清项目约定：读取 package.json 确认包管理器（bun/pnpm/npm）、脚本与依赖；读取 tsconfig.json 确认 TypeScript 设置与路径别名；扫描 src/ 了解目录布局与分层结构；检查 docs/adr/ 或 contribute/ 中的项目代码规范；检查格式化/lint 配置（biome.json、.eslintrc、prettier）；读取 app.config.ts 与 app.manifest.ts 了解端点与环境设置；对不确定的 Fusion Framework 行为、包归属或示例，先交给 fusion-research 再写代码。以发现的约定为准，references/ 中的模式只是默认值。
2. 第 2 步——规划实现：从零新建应用时使用 assets/new-app-checklist.md；把工作拆成独立的文件/改动；映射到正确目录（src/components/ 放 React 组件、src/hooks/ 放自定义 Hook、src/api/ 放 API 客户端与数据转换与业务逻辑、src/types/ 放类型、src/routes.ts 放路由、src/config.ts 放 Fusion 模块配置、src/App.tsx 放根组件）；尽早识别共享类型并在引用前定义；若项目使用路由，按 references/using-router.md 的 DSL 与页面模式；若结构不同则遵循项目结构。
3. 第 3 步——按代码规范实现：遵循第 1 步发现的项目标准；命名、TSDoc、内联注释、类型模式、代码风格、错误处理交给 fusion-code-conventions；实现中遇到约定问题直接调用 fusion-code-conventions。
4. 第 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 优先用 EDS（@equinor/eds-core-react）；颜色、间距、排版用 EDS 设计令牌（@equinor/eds-tokens）；用 styled() 扩展 EDS；EDS 没有的领域需求（人员展示/选择、侧边面板、进度）用 @equinor/fusion-react-*；内联 style 仅用于一次性微调；页面/视图结构（外壳组合、布局分区、空/加载状态）调用 agents/design.md，组件级 EDS 样式调用 agents/styling.md。
5. 第 5 步——接入数据获取（如适用）：遵循 references/configure-services.md、references/using-react-query.md、references/configure-mocking.md；在 config.ts 或 app.config.ts 中通过 configureHttpClient 注册 HTTP 客户端；用 @equinor/fusion-framework-react-app/http 的 useHttpClient(name) 访问客户端；优先使用 @equinor/fusion-framework-react-app/* 的 Hook 而非直接访问模块，framework.modules.* 仅用于非 React 上下文；React Query 中把 useQuery 包在薄自定义 Hook 里；查询键由 API 路径加参数派生；客户端 UI 状态放在 React state/context，不要放进服务端状态库。
6. 第 6 步——配置 Fusion 模块（如适用）：先确定需要哪个模块，再只读对应参考——HTTP 客户端/API 集成看 references/configure-services.md，Context 模块看 references/using-context.md，路由与页面看 references/using-router.md，AG Grid 看 references/using-ag-grid.md，AG Charts（独立）看 references/using-ag-charts.md，AG Grid 集成图表看 references/using-ag-grid-charts.md，EDS 与 Fusion React 组件看 references/using-fusion-react-components.md，人员服务看 references/using-people-service.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，自定义模块编写看 references/using-custom-modules.md；模块在 config.ts 中通过 AppModuleInitiator 回调设置；通过 useAppModule、useHttpClient、useCurrentContext 等 Hook 访问模块；新 API 集成在 app.config.ts 注册 HTTP 端点；应用使用路由时在 config.ts 中用 enableNavigation 启用导航；用 Fusion Router DSL（layout、index、route、prefix）定义路由以自动代码分割；框架 API 不清楚时先用 fusion-research 再选实现模式。
7. 第 7 步——新增或更新测试：遵循 references/testing.md；用 agents/testing.md 做聚焦的测试创建、维护与执行，它会把框架设置/渲染路由到 fusion-framework-testing，把模块/HTTP 状态路由到 fusion-framework-mocking。
8. 第 8 步——验证：用 assets/review-checklist.md 作为生成后检查清单；运行类型检查（bun run typecheck 或 pnpm typecheck）要求零错误；运行 lint/format 检查要求零违规；每个新导出符号都要有 TSDoc；样式遵循项目约定；除非有正当理由并获批准，否则不新增依赖。
9. 预期产出：新增/修改的 src/ 文件遵循项目分层结构；所有文件通过类型检查与 lint；每个导出的函数、组件、Hook、类型都有 TSDoc；样式遵循项目约定；测试覆盖变更行为并使用 fusion-framework-testing，测试期 Fusion 状态按需使用 fusion-framework-mocking；简要说明改了什么以及为什么。
10. 辅助 agent（可选，用于聚焦审查或实现中途指导；无 skill 局部 agent 的运行时按内联标准执行）：agents/testing.md 创建、维护并执行应用测试，路由到测试/模拟配套技能，用于行为变更、测试文件、fixture、配置或失败；agents/framework.md 处理 Fusion Framework 集成（模块、HTTP 客户端、bootstrap、运行时配置、设置、书签、分析），优先用 mcp_fusion_search_framework，回退到 mcp_fusion_search_docs，在接 config.ts、app.config.ts 或框架模块访问时咨询；agents/styling.md 处理 EDS 组件选择、styled-components、设计令牌、可访问性，优先用 mcp_fusion_search_eds，在构建/修改视觉组件时咨询；agents/design.md 处理页面/视图结构（Fusion Portal 外壳组合、布局分区、侧边面板用法、空/加载状态模式），参考 equinor-design-system 作为布局依据，组件级检查委托给 agents/styling.md，在搭建新页面或布局包装时咨询；agents/data-display.md 处理 AG Grid 与 AG Charts 选择、模块设置、列定义、图表选项、集成图表，优先用 mcp_fusion_search_framework，用于网格、图表、仪表盘，库选择用 assets/charts-decision-matrix.md；agents/person-components.md 处理 @equinor/fusion-react-person（PersonAvatar、PersonCard、PersonListItem、PersonPicker、PeoplePicker、PeopleViewer、PersonCell），含 DOM 事件模式、valueGetter 设置与陷阱，用于任何人员展示、搜索或选择 UI；agents/code-quality.md 把命名、TSDoc、TS 严格性、意图注释等约定检查委托给 fusion-code-conventions 并汇总结果，在每个新增/修改文件定稿前运行。
11. 安全与约束：未经明确批准不新增依赖；不做直接 DOM 操作，使用 React 模式；不用 any 类型，遵循 TypeScript 严格模式；源码中不放密钥或凭据；使用约定式提交（feat:、fix:、refactor: 等）；除非明确要求，不添加基础设施文件（docker-compose、CI 配置）。

适用边界 · 注意事项

• 问题（issue）撰写/分诊，应使用 fusion-issue-authoring
• 技能（skill）编写，应使用 fusion-skill-authoring
• 后端/服务端改动（在独立仓库）、CI/CD 或部署配置、与应用实现无关的通用 Fusion 文档