Opik 前端依赖治理实战基于 dependency-cruiser 基线文件管控循环依赖与架构违规【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本文档深入剖析 Opik 前端apps/opik-frontend如何借助.dependency-cruiser-known-violations.README.md与配套的.dependency-cruiser-known-violations.json基线文件把已知违规从构建拦路虎转化为可跟踪、可逐步消除的技术债台账。读完本文你将掌握 dependency-cruiser 的--ignore-known基线机制、Opik 前端单向分层依赖规则ui → shared → v2/pages-shared → v2/pages以及先冻结存量违规、再增量修复、最终清零的前端架构治理工作流。背景为什么 Opik 前端需要依赖基线Opik 前端是一个体量庞大的 React/TypeScript 单页应用其src/下划分了api/、constants/、hooks/、lib/、plugins/、store/、types/、ui/、shared/、v2/等十余个职责目录见 apps/opik-frontend/README.md其中v2/又细分为layout/、pages/、pages-shared/。目录众多、页面与共享组件交织若放任 import 关系自由生长很快会出现跨层引用、循环依赖、类型层携带运行时副作用等问题。为此项目引入了 dependency-cruiserpackage.json中声明版本^17.3.6见 apps/opik-frontend/package.json作为依赖关系静态分析工具并配套两样关键资产.dependency-cruiser.cjs声明全部forbidden规则即什么样的依赖关系算违规.dependency-cruiser-known-violations.json记录当前已存在的违规清单即存量技术债台账.dependency-cruiser-known-violations.README.md用人类可读的方式说明这套基线机制的目的、当前违规汇总、修复流程与 CI 集成方式。三者的关系是规则文件定义标准基线文件豁免存量README 指导团队如何持续消债。基线文件允许项目在不阻塞日常迭代的前提下把历史遗留与新增违规区分开来。基线机制的三重目的.dependency-cruiser-known-violations.README.md开篇即阐明基线文件存在的意义核心可以概括为三点阻止新增违规Prevent NEW violations任何不在基线清单内的新违规都会导致构建失败从源头杜绝技术债继续累积跟踪存量违规Track existing violations所有当前已存在的违规都被显式记录不会因为历史问题而被遗忘或选择性无视逐步修复Gradually fix issues修复一个、从基线删除一个台账持续收缩直到归零。这套先豁免存量、再严控增量的策略正是大型前端仓库在架构演进期常用的技术债管理手段它不追求一次性清理完毕而是用自动化的方式确保债务只减不增。规则体系.dependency-cruiser.cjs如何定义违规要理解基线文件中每一条记录的来源需要先看懂 .dependency-cruiser.cjs 中定义的规则集合。整个配置文件通过forbidden数组声明了十余条规则按主题可以归为以下几组循环依赖与不可解析no-circularseverity:error禁止模块间形成循环依赖注释直言循环依赖是维护噩梦Circular dependencies lead to maintenance nightmaresnot-to-unresolvableseverity:error所有 import 必须可解析防止出现悬空引用。组件分层架构单向依赖核心中的核心Opik 前端确立了严格的组件依赖层级规则用路径正则逐层拦截规则名含义源码依据no-ui-importing-sharedsrc/ui/不得反向引用shared/、v2/pages-shared/、v2/pages/保证基础 UI 组件的纯净性.dependency-cruiser.cjsno-shared-importing-pagessrc/shared/不得引用版本化代码v2/pages-shared/、v2/pages/.dependency-cruiser.cjsno-pages-shared-importing-pagesv2/pages-shared/不得引用具体页面v2/pages/共享物只能向下沉淀.dependency-cruiser.cjsno-cross-page-imports页面之间不得相互直接 import同页面内部除外用$1反向引用来限定同目录.dependency-cruiser.cjsno-importing-old-components历史遗留的src/components/目录已废弃全仓库禁止再引用.dependency-cruiser.cjs这组规则与 apps/opik-frontend/README.md 中声明的 import rules 完全一致ui → shared → v2/pages-shared → v2/pagesone-way only。各层的隔离约束no-api-importing-componentssrc/api/层禁止 import UI/组件代码仅放行src/ui/use-toast.ts它是 hook 而非组件这一个例外no-store-importing-componentsZustand store 禁止引用组件代码仅放行src/store/PluginsStore.ts插件注册需要no-hooks-importing-componentshooks 层不得引用 UI/共享组件同样为use-toast、ConfirmDialog、dialog.tsx、button.tsx开了白名单no-types-with-side-effectssrc/types/只能存放纯类型定义禁止 import 运行时代码no-constants-importing-runtimesrc/constants/不应引入运行时逻辑避免常量文件触发额外模块加载。依赖卫生与插件隔离no-lodash-default-import禁止import _ from lodash式的整体导入要求按路径逐个导入如import isString from lodash/isString以支持 tree-shakingno-project-importing-plugins项目主体代码不得 importsrc/plugins/插件是可选集成如 Comet仅PluginsStore.ts例外no-orphansseverity:info从入口不可达的孤立模块会被标记便于发现死代码同时豁免点号文件、*.d.ts、vite.config.*、测试文件与__mocks__等no-deprecated-core、no-duplicate-dep-types分别拦截 Node 弃用核心模块与同时出现在 dependencies 和 devDependencies的重复声明。可视化辅助配置文件还内置了 Graphviz dot 报告的主题配色src/api/模块着红色系、src/ui/绿色系、src/shared/蓝色系、src/v2/pages-shared/黄色系、src/v2/pages/粉色系等依赖边则按目标模块着色如指向api/的边为#cc0000让depcruise src --output-type dot生成的依赖图可以一眼看出跨层调用详见 .dependency-cruiser.cjs。当前违规汇总存量技术债全景.dependency-cruiser-known-violations.README.md将现有违规划分为七类并对每一类给出了修复方向。以下逐类展开并对照当前基线文件核实其最新状态。循环依赖Circular DependenciesREADME 标记 MUST FIXREADME 将其列为最高优先级理由是制造维护噩梦并潜藏运行时问题maintenance nightmares and potential runtime issues。文档中列举的典型循环包括useOpenAICompatibleModels↔provider.ts↔useLLMProviderModelsDatauseProviderKeys→provider.ts→useLLMProviderModelsData→useOpenAICompatibleModelsMetricTag↔PlaygroundOutputScoresuseDatasetItemData↔useDatasetItemFormHelpers两处位置FeedbackScoreTable的 cells ↔utils.ts↔constants.ts5 处违规。对照 .dependency-cruiser-known-violations.json当前基线中实际保留的循环依赖记录为 7 条且全部来自后三类useDatasetItemData.ts↔useDatasetItemFormHelpers.ts1 条两个 hook 位于同一目录v2/pages-shared/datasets/DatasetItemEditor/hooks/useDatasetItemData.ts 顶部就通过import { getFieldType } from ./useDatasetItemFormHelpers建立了正向引用而后者又反向引用了前者形成环FeedbackScoreTable的AuthorCell、ReasonCell、SourceCell、TypeCell、ValueCell五个单元格组件 ↔utils.ts↔constants.ts5 条环结构均为cells/*.tsx → utils.ts → constants.ts → cells/*.tsxMetricTag.tsx↔PlaygroundOutputScores.tsx1 条两者同处于 PlaygroundOutputScores 目录。一个值得注意的细节README 中列出的 LLM Provider 相关循环useOpenAICompatibleModels、useProviderKeys等在当前基线 JSON 中已不再出现。从源码结构看hooks/useOpenAICompatibleModels.ts、hooks/useLLMProviderModelsData.ts、api/provider-keys/useProviderKeys.ts 均仍存在可以推断这批违规是在某次重构中已被修复并从基线移除README 的汇总数字12 条尚未同步更新——这也侧面印证了基线文件是活台账README 需要配合维护。Shared → Pages-sharedREADME 统计 35 条需重构src/shared/中的组件反向引用了v2/pages-shared/违背了shared 不得引用版本化代码的规则。文档点名的对象包括 Dashboard widgets、DataTableCells、TruncationConfigPopover、PromptImprovementDialog 等。修复方向非常明确Fix:Move these components topages-shared/or extract shared utilities即要么把这类共享组件整体下沉到v2/pages-shared/要么把其中真正通用的逻辑抽取成lib/下的纯工具函数。从当前基线 JSON 看该类违规的最新记录已经不在其中README 的 35 条统计与基线文件存在差异说明大部分已清理或已从台账移除。Pages-shared → PagesREADME 统计 9 条需抽取共享代码这是v2/pages-shared/反向依赖具体页面的违规文档列出了 5 个代表AddToDatasetDialog→AddEditDatasetDialogDatasetSelectBox→AddEditDatasetDialogThreadDetailsPanel→WorkspacePreferencesTab/types.tsExperimentsRadarChart→useCompareExperimentsChartsDataIntegrationDetailsDialog→AgentOnboardingContext。修复建议是将共享的类型与工具函数抽取到pages-shared/或lib/。当前基线 JSON 中仍保留着该类的 1 条记录IntegrationDetailsDialog.tsx→AgentOnboardingContext.tsx违反no-pages-shared-importing-pages见 .dependency-cruiser-known-violations.json说明这一条属于尚未清偿的存量债务。Cross-page ImportsREADME 统计 5 条抽取到 pages-shared页面之间直接相互引用破坏了页面隔离。文档点名的有HomePage→ProjectsPage、OptimizationsPage以及TracesPage→HomePageShared。修复方向同样是把共享对话框/组件下沉到pages-shared/。这条规则对应的no-cross-page-imports使用正则反向引用实现同目录放行当前基线 JSON 中已无该类记录。其余小类违规Hooks → Components1 条useProviderOptions→ProviderGrid即 hooks/useProviderOptions.ts 引用了 v2/pages-shared/llm/SetupProviderDialog/ProviderGrid.tsx。修复建议是改用组合模式composition pattern把组件作为参数传入 hook而非在 hook 内直接 import 组件Types → Components2 条dashboard.ts→DateRangeSelect、breakdown.ts即 types/dashboard.ts 引用了运行时组件违反no-types-with-side-effects。修复建议是把类型放入 types 目录、运行时代码分离。当前基线 JSON 中该条仍存在src/types/dashboard.ts→src/shared/DateRangeSelect/index.ts见 .dependency-cruiser-known-violations.jsonAPI → Components1 条useProjectMetric→breakdown.ts建议将 breakdown.ts 移动到lib/目录保持 API 层的纯净。孤儿模块no-orphansseverity: info除了 README 汇总的七类当前基线 JSON 还记录了 3 条no-orphans规则命中severity 为infosrc/types/chart.ts、HelpResources.tsx、TraceAnnotateViewer/utils.ts均为从入口不可达的孤立模块提示可能存在死代码或缺失导出路径属于低优先级观察项。实战修复流程五步清偿一笔技术债.dependency-cruiser-known-violations.README.md给出的标准修复流程如下挑选违规项从基线清单中任选一条重构代码按对应分类给出的 Fix 方向修改源码运行校验执行npm run deps:validate确认修改没有引入新违规删除基线条目将已修复的条目从.dependency-cruiser-known-violations.json中移除提交变更代码与基线文件一同提交完成一轮消债。以当前仍存在的useDatasetItemData↔useDatasetItemFormHelpers循环为例实操路径是先观察 useDatasetItemData.ts 第 9 行的getFieldType导入确认循环发生的两个方向随后把getFieldType等双方共用的纯函数抽取到独立的utils.ts或lib/模块打破环最后运行npm run deps:validate若通过则删除基线 JSON 中对应的 cycle 记录。同理MetricTag↔PlaygroundOutputScores这类组件环通常需要把公共状态提升到父组件或抽出共享子组件来解耦。重新生成基线什么时候需要、命令是什么当存量违规被批量修复、或基线文件因长期累积而失真时可以一键重新生成基线npx depcruise src --config --output-type baseline .dependency-cruiser-known-violations.json该命令让 dependency-cruiser 扫描src/目录遵守 .dependency-cruiser.cjs 中options的过滤配置排除node_modules、*.test.ts(x)、*.spec.ts(x)、__tests__、__mocks__、*.d.ts且仅分析src/内部开启tsPreCompilationDeps并读取tsconfig.json解析别名把当前所有违规以 baseline 格式输出并覆盖写回 JSON 文件。注意重新生成基线只应在存量修复完成后执行。若在仍有大量违规时盲目重跑会让新引入的违规被一次性洗白从而丧失增量拦截能力。项目在package.json中也提供了等价的封装脚本npm run deps:baseline即上述重生成命令npm run deps:validatedepcruise src --config --ignore-known .dependency-cruiser-known-violations.json带--ignore-known参数执行校验。接入 CI把依赖治理变成硬约束将校验命令加入 CI 流水线即可让依赖治理自动化、常态化npm run deps:validate该命令的判定语义非常清晰✅通过当前只存在基线文件--ignore-known中已记录的违规❌失败检测到任何新增违规即不在已知清单中的循环依赖、跨层引用、不可解析导入等。--ignore-known是这套机制的精髓它读取.dependency-cruiser-known-violations.json并自动豁免其中登记的条目其余命中一律按规则声明的最低 severity多数为error判定失败。这意味着合并请求只要不引入新的架构问题就能顺利通过而存量债务的清偿进度由基线文件的删减速度来衡量。从文档到实践三份文件如何协同运转综合来看Opik 前端的依赖治理是一套规则—台账—流程三位一体的闭环.dependency-cruiser.cjs 是宪法用十几条正则可执行规则固化了ui → shared → v2/pages-shared → v2/pages的单向分层、API/store/hooks/types/constants 隔离、插件隔离与依赖卫生要求.dependency-cruiser-known-violations.json 是资产负债表如实登记每一笔存量违规的类型、涉及的模块与命中规则并充当deps:validate的豁免白名单.dependency-cruiser-known-violations.README.md 是操作手册告诉每个开发者三类违规长什么样、如何修复、如何重新生成基线、如何接入 CI。对于任何正在经历大规模重构、或目录结构持续膨胀的前端项目这套基线豁免 增量拦截 台账驱动消债的模式都极具参考价值它让架构约束从靠 code review 人工把关升级为提交即自动校验也让技术债从模糊的焦虑变成了逐条可勾销的清单。Opik 前端的实践表明只要规则清晰、台账透明、流程闭环再庞大的依赖网络也能在持续迭代中逐步收敛。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Opik 前端依赖治理实战：基于 dependency-cruiser 基线文件管控循环依赖与架构违规
Opik 前端依赖治理实战基于 dependency-cruiser 基线文件管控循环依赖与架构违规【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本文档深入剖析 Opik 前端apps/opik-frontend如何借助.dependency-cruiser-known-violations.README.md与配套的.dependency-cruiser-known-violations.json基线文件把已知违规从构建拦路虎转化为可跟踪、可逐步消除的技术债台账。读完本文你将掌握 dependency-cruiser 的--ignore-known基线机制、Opik 前端单向分层依赖规则ui → shared → v2/pages-shared → v2/pages以及先冻结存量违规、再增量修复、最终清零的前端架构治理工作流。背景为什么 Opik 前端需要依赖基线Opik 前端是一个体量庞大的 React/TypeScript 单页应用其src/下划分了api/、constants/、hooks/、lib/、plugins/、store/、types/、ui/、shared/、v2/等十余个职责目录见 apps/opik-frontend/README.md其中v2/又细分为layout/、pages/、pages-shared/。目录众多、页面与共享组件交织若放任 import 关系自由生长很快会出现跨层引用、循环依赖、类型层携带运行时副作用等问题。为此项目引入了 dependency-cruiserpackage.json中声明版本^17.3.6见 apps/opik-frontend/package.json作为依赖关系静态分析工具并配套两样关键资产.dependency-cruiser.cjs声明全部forbidden规则即什么样的依赖关系算违规.dependency-cruiser-known-violations.json记录当前已存在的违规清单即存量技术债台账.dependency-cruiser-known-violations.README.md用人类可读的方式说明这套基线机制的目的、当前违规汇总、修复流程与 CI 集成方式。三者的关系是规则文件定义标准基线文件豁免存量README 指导团队如何持续消债。基线文件允许项目在不阻塞日常迭代的前提下把历史遗留与新增违规区分开来。基线机制的三重目的.dependency-cruiser-known-violations.README.md开篇即阐明基线文件存在的意义核心可以概括为三点阻止新增违规Prevent NEW violations任何不在基线清单内的新违规都会导致构建失败从源头杜绝技术债继续累积跟踪存量违规Track existing violations所有当前已存在的违规都被显式记录不会因为历史问题而被遗忘或选择性无视逐步修复Gradually fix issues修复一个、从基线删除一个台账持续收缩直到归零。这套先豁免存量、再严控增量的策略正是大型前端仓库在架构演进期常用的技术债管理手段它不追求一次性清理完毕而是用自动化的方式确保债务只减不增。规则体系.dependency-cruiser.cjs如何定义违规要理解基线文件中每一条记录的来源需要先看懂 .dependency-cruiser.cjs 中定义的规则集合。整个配置文件通过forbidden数组声明了十余条规则按主题可以归为以下几组循环依赖与不可解析no-circularseverity:error禁止模块间形成循环依赖注释直言循环依赖是维护噩梦Circular dependencies lead to maintenance nightmaresnot-to-unresolvableseverity:error所有 import 必须可解析防止出现悬空引用。组件分层架构单向依赖核心中的核心Opik 前端确立了严格的组件依赖层级规则用路径正则逐层拦截规则名含义源码依据no-ui-importing-sharedsrc/ui/不得反向引用shared/、v2/pages-shared/、v2/pages/保证基础 UI 组件的纯净性.dependency-cruiser.cjsno-shared-importing-pagessrc/shared/不得引用版本化代码v2/pages-shared/、v2/pages/.dependency-cruiser.cjsno-pages-shared-importing-pagesv2/pages-shared/不得引用具体页面v2/pages/共享物只能向下沉淀.dependency-cruiser.cjsno-cross-page-imports页面之间不得相互直接 import同页面内部除外用$1反向引用来限定同目录.dependency-cruiser.cjsno-importing-old-components历史遗留的src/components/目录已废弃全仓库禁止再引用.dependency-cruiser.cjs这组规则与 apps/opik-frontend/README.md 中声明的 import rules 完全一致ui → shared → v2/pages-shared → v2/pagesone-way only。各层的隔离约束no-api-importing-componentssrc/api/层禁止 import UI/组件代码仅放行src/ui/use-toast.ts它是 hook 而非组件这一个例外no-store-importing-componentsZustand store 禁止引用组件代码仅放行src/store/PluginsStore.ts插件注册需要no-hooks-importing-componentshooks 层不得引用 UI/共享组件同样为use-toast、ConfirmDialog、dialog.tsx、button.tsx开了白名单no-types-with-side-effectssrc/types/只能存放纯类型定义禁止 import 运行时代码no-constants-importing-runtimesrc/constants/不应引入运行时逻辑避免常量文件触发额外模块加载。依赖卫生与插件隔离no-lodash-default-import禁止import _ from lodash式的整体导入要求按路径逐个导入如import isString from lodash/isString以支持 tree-shakingno-project-importing-plugins项目主体代码不得 importsrc/plugins/插件是可选集成如 Comet仅PluginsStore.ts例外no-orphansseverity:info从入口不可达的孤立模块会被标记便于发现死代码同时豁免点号文件、*.d.ts、vite.config.*、测试文件与__mocks__等no-deprecated-core、no-duplicate-dep-types分别拦截 Node 弃用核心模块与同时出现在 dependencies 和 devDependencies的重复声明。可视化辅助配置文件还内置了 Graphviz dot 报告的主题配色src/api/模块着红色系、src/ui/绿色系、src/shared/蓝色系、src/v2/pages-shared/黄色系、src/v2/pages/粉色系等依赖边则按目标模块着色如指向api/的边为#cc0000让depcruise src --output-type dot生成的依赖图可以一眼看出跨层调用详见 .dependency-cruiser.cjs。当前违规汇总存量技术债全景.dependency-cruiser-known-violations.README.md将现有违规划分为七类并对每一类给出了修复方向。以下逐类展开并对照当前基线文件核实其最新状态。循环依赖Circular DependenciesREADME 标记 MUST FIXREADME 将其列为最高优先级理由是制造维护噩梦并潜藏运行时问题maintenance nightmares and potential runtime issues。文档中列举的典型循环包括useOpenAICompatibleModels↔provider.ts↔useLLMProviderModelsDatauseProviderKeys→provider.ts→useLLMProviderModelsData→useOpenAICompatibleModelsMetricTag↔PlaygroundOutputScoresuseDatasetItemData↔useDatasetItemFormHelpers两处位置FeedbackScoreTable的 cells ↔utils.ts↔constants.ts5 处违规。对照 .dependency-cruiser-known-violations.json当前基线中实际保留的循环依赖记录为 7 条且全部来自后三类useDatasetItemData.ts↔useDatasetItemFormHelpers.ts1 条两个 hook 位于同一目录v2/pages-shared/datasets/DatasetItemEditor/hooks/useDatasetItemData.ts 顶部就通过import { getFieldType } from ./useDatasetItemFormHelpers建立了正向引用而后者又反向引用了前者形成环FeedbackScoreTable的AuthorCell、ReasonCell、SourceCell、TypeCell、ValueCell五个单元格组件 ↔utils.ts↔constants.ts5 条环结构均为cells/*.tsx → utils.ts → constants.ts → cells/*.tsxMetricTag.tsx↔PlaygroundOutputScores.tsx1 条两者同处于 PlaygroundOutputScores 目录。一个值得注意的细节README 中列出的 LLM Provider 相关循环useOpenAICompatibleModels、useProviderKeys等在当前基线 JSON 中已不再出现。从源码结构看hooks/useOpenAICompatibleModels.ts、hooks/useLLMProviderModelsData.ts、api/provider-keys/useProviderKeys.ts 均仍存在可以推断这批违规是在某次重构中已被修复并从基线移除README 的汇总数字12 条尚未同步更新——这也侧面印证了基线文件是活台账README 需要配合维护。Shared → Pages-sharedREADME 统计 35 条需重构src/shared/中的组件反向引用了v2/pages-shared/违背了shared 不得引用版本化代码的规则。文档点名的对象包括 Dashboard widgets、DataTableCells、TruncationConfigPopover、PromptImprovementDialog 等。修复方向非常明确Fix:Move these components topages-shared/or extract shared utilities即要么把这类共享组件整体下沉到v2/pages-shared/要么把其中真正通用的逻辑抽取成lib/下的纯工具函数。从当前基线 JSON 看该类违规的最新记录已经不在其中README 的 35 条统计与基线文件存在差异说明大部分已清理或已从台账移除。Pages-shared → PagesREADME 统计 9 条需抽取共享代码这是v2/pages-shared/反向依赖具体页面的违规文档列出了 5 个代表AddToDatasetDialog→AddEditDatasetDialogDatasetSelectBox→AddEditDatasetDialogThreadDetailsPanel→WorkspacePreferencesTab/types.tsExperimentsRadarChart→useCompareExperimentsChartsDataIntegrationDetailsDialog→AgentOnboardingContext。修复建议是将共享的类型与工具函数抽取到pages-shared/或lib/。当前基线 JSON 中仍保留着该类的 1 条记录IntegrationDetailsDialog.tsx→AgentOnboardingContext.tsx违反no-pages-shared-importing-pages见 .dependency-cruiser-known-violations.json说明这一条属于尚未清偿的存量债务。Cross-page ImportsREADME 统计 5 条抽取到 pages-shared页面之间直接相互引用破坏了页面隔离。文档点名的有HomePage→ProjectsPage、OptimizationsPage以及TracesPage→HomePageShared。修复方向同样是把共享对话框/组件下沉到pages-shared/。这条规则对应的no-cross-page-imports使用正则反向引用实现同目录放行当前基线 JSON 中已无该类记录。其余小类违规Hooks → Components1 条useProviderOptions→ProviderGrid即 hooks/useProviderOptions.ts 引用了 v2/pages-shared/llm/SetupProviderDialog/ProviderGrid.tsx。修复建议是改用组合模式composition pattern把组件作为参数传入 hook而非在 hook 内直接 import 组件Types → Components2 条dashboard.ts→DateRangeSelect、breakdown.ts即 types/dashboard.ts 引用了运行时组件违反no-types-with-side-effects。修复建议是把类型放入 types 目录、运行时代码分离。当前基线 JSON 中该条仍存在src/types/dashboard.ts→src/shared/DateRangeSelect/index.ts见 .dependency-cruiser-known-violations.jsonAPI → Components1 条useProjectMetric→breakdown.ts建议将 breakdown.ts 移动到lib/目录保持 API 层的纯净。孤儿模块no-orphansseverity: info除了 README 汇总的七类当前基线 JSON 还记录了 3 条no-orphans规则命中severity 为infosrc/types/chart.ts、HelpResources.tsx、TraceAnnotateViewer/utils.ts均为从入口不可达的孤立模块提示可能存在死代码或缺失导出路径属于低优先级观察项。实战修复流程五步清偿一笔技术债.dependency-cruiser-known-violations.README.md给出的标准修复流程如下挑选违规项从基线清单中任选一条重构代码按对应分类给出的 Fix 方向修改源码运行校验执行npm run deps:validate确认修改没有引入新违规删除基线条目将已修复的条目从.dependency-cruiser-known-violations.json中移除提交变更代码与基线文件一同提交完成一轮消债。以当前仍存在的useDatasetItemData↔useDatasetItemFormHelpers循环为例实操路径是先观察 useDatasetItemData.ts 第 9 行的getFieldType导入确认循环发生的两个方向随后把getFieldType等双方共用的纯函数抽取到独立的utils.ts或lib/模块打破环最后运行npm run deps:validate若通过则删除基线 JSON 中对应的 cycle 记录。同理MetricTag↔PlaygroundOutputScores这类组件环通常需要把公共状态提升到父组件或抽出共享子组件来解耦。重新生成基线什么时候需要、命令是什么当存量违规被批量修复、或基线文件因长期累积而失真时可以一键重新生成基线npx depcruise src --config --output-type baseline .dependency-cruiser-known-violations.json该命令让 dependency-cruiser 扫描src/目录遵守 .dependency-cruiser.cjs 中options的过滤配置排除node_modules、*.test.ts(x)、*.spec.ts(x)、__tests__、__mocks__、*.d.ts且仅分析src/内部开启tsPreCompilationDeps并读取tsconfig.json解析别名把当前所有违规以 baseline 格式输出并覆盖写回 JSON 文件。注意重新生成基线只应在存量修复完成后执行。若在仍有大量违规时盲目重跑会让新引入的违规被一次性洗白从而丧失增量拦截能力。项目在package.json中也提供了等价的封装脚本npm run deps:baseline即上述重生成命令npm run deps:validatedepcruise src --config --ignore-known .dependency-cruiser-known-violations.json带--ignore-known参数执行校验。接入 CI把依赖治理变成硬约束将校验命令加入 CI 流水线即可让依赖治理自动化、常态化npm run deps:validate该命令的判定语义非常清晰✅通过当前只存在基线文件--ignore-known中已记录的违规❌失败检测到任何新增违规即不在已知清单中的循环依赖、跨层引用、不可解析导入等。--ignore-known是这套机制的精髓它读取.dependency-cruiser-known-violations.json并自动豁免其中登记的条目其余命中一律按规则声明的最低 severity多数为error判定失败。这意味着合并请求只要不引入新的架构问题就能顺利通过而存量债务的清偿进度由基线文件的删减速度来衡量。从文档到实践三份文件如何协同运转综合来看Opik 前端的依赖治理是一套规则—台账—流程三位一体的闭环.dependency-cruiser.cjs 是宪法用十几条正则可执行规则固化了ui → shared → v2/pages-shared → v2/pages的单向分层、API/store/hooks/types/constants 隔离、插件隔离与依赖卫生要求.dependency-cruiser-known-violations.json 是资产负债表如实登记每一笔存量违规的类型、涉及的模块与命中规则并充当deps:validate的豁免白名单.dependency-cruiser-known-violations.README.md 是操作手册告诉每个开发者三类违规长什么样、如何修复、如何重新生成基线、如何接入 CI。对于任何正在经历大规模重构、或目录结构持续膨胀的前端项目这套基线豁免 增量拦截 台账驱动消债的模式都极具参考价值它让架构约束从靠 code review 人工把关升级为提交即自动校验也让技术债从模糊的焦虑变成了逐条可勾销的清单。Opik 前端的实践表明只要规则清晰、台账透明、流程闭环再庞大的依赖网络也能在持续迭代中逐步收敛。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考