诊断通道

组件在运行期发现契约问题时不直接 console.warn，而是向诊断通道投递一条结构化记录。宿主订阅后自行决定打印、收集还是上报。

不直接打日志的原因

契约违约需要被处理，不只是被看见。wc.missing-part 这类问题在开发时应明显报出，在测试中应使用例失败，在生产环境应静默：同一条记录，三种归宿。写死 console.warn 只满足第一种。

记录的形状

interface DiagnosticRecord {
  code: string; // 稳定标识，如 'wc.missing-part'
  level: "error" | "warn";
  message: string; // 面向开发者的说明，文案可变
  scope?: string; // 组件名，取解剖名
  instanceId?: string; // 区分同一组件的多个实例
  part?: string;
  node?: Element;
  detail?: Record<string, unknown>;
}

code 稳定，message 不稳定。订阅方按码分流，不匹配文案。

现有的码

export const DIAGNOSTIC_CODES = {
  invariant: "core.invariant", // 断言不成立
  warn: "core.warn", // 条件告警
  layerDisposeNotTop: "core.layer.dispose-not-top", // dispose 的层不是栈顶
  machineError: "machine.error", // 机器抛出 MachineError
  wcMissingPart: "wc.missing-part", // 作者未渲染必需的角色节点
  wcUnknownPart: "wc.unknown-part", // 角色节点的 part 名不在组件解剖内
  wcWrongPartTag: "wc.wrong-part-tag", // 角色节点的标签不满足要求，原生语义会静默失效
  matrixCodeLogoDamage: "matrix-code.logo-damage", // 中心 logo 挖掉的码字超出纠错级别能恢复的量
  matrixCodeOptionIgnored: "matrix-code.option-ignored", // 二维码收到一个对当前码制没有意义的选项，按没给处理
  barCodeOptionIgnored: "bar-code.option-ignored", // 条形码收到一个对当前码制没有意义的选项，按没给处理
  stylesMissingSkin: "styles.missing-skin", // 页面上出现了组件，但它那份皮肤没被引入
  versionMismatch: "core.version-mismatch", // 适配器与 core 的版本不一致，锁步发版被打破
  ignoredSlot: "core.ignored-slot", // 作者给了默认插槽，但该组件不渲染插槽内容
  overlayStackingTrap: "overlay.stacking-trap", // 浮层的祖先建了层叠上下文，浮层的层号被困在其中
  scrollbarMissingScrollable: "scrollbar.missing-scrollable", // 滚动条挂载时找不到它要管的滚动容器
  overlayMissingAnchor: "overlay.missing-anchor", // 浮层展开了却没有锚点，位置无从算起
  chartMissingName: "chart.missing-name", // 图表没有可及名：caption 部件、aria-label、aria-labelledby 都没有
  chartUnknownField: "chart.unknown-field", // 系列引用的字段在数据里不存在
  chartDuplicateSeries: "chart.duplicate-series", // 两个系列的 id 相同
  chartTooManySeries: "chart.too-many-series", // 分类系列超过 8 个：没有第 9 色
  chartMixedColorRoles: "chart.mixed-color-roles", // 同一张图混用分类色与语气色
  chartInvalidSlot: "chart.invalid-slot", // 固定色槽越界，或两个系列固定到同一槽
  chartStackOffsetConflict: "chart.stack-offset-conflict", // 同一堆叠组的 stackOffset 不一致
  chartLogDomain: "chart.log-domain", // 对数轴的定义域含 0 或跨越正负
  chartBarBaseline: "chart.bar-baseline", // 柱系列所在的值轴不含 0
  chartNegativeShare: "chart.negative-share", // 占比类图表出现负值
};

这份清单与 @xihan-ui/core 中的码表逐条对账，不会遗漏，可以直接据此编写分流。

machine.error 的 detail.machineCode 是状态机错误码。机器崩溃或正常停机清理失败时，detail.reason 保留实际上报的原始或聚合异常对象；同时发生 cleanup 与 exit 异常时，它与调用方捕获的 AggregateError 是同一个对象，可以继续读取 errors 与 cause。

状态机实现引用属于执行前置条件。UNKNOWN_ACTION、UNKNOWN_GUARD、UNKNOWN_EFFECT 在创建机器时拒绝静态缺项；动态列表或实现内部引用缺项时使用 MISSING_ACTION、MISSING_GUARD、MISSING_EFFECT。后三种错误在开发与生产都会先投递 machine.error；没有其他停机异常时，其 detail.reason 与随后抛出的 MachineError 是同一个对象，存在其他停机异常时则由后续崩溃记录携带聚合结果。服务同时进入 Stopped。诊断阈值只控制记录是否送达，不会把错误改成继续执行、guard 的 false 或部分 effect。

三条 wc.* 是 Web Components 适配器的部件契约校验，也是日常最常遇到的三条：手写 DOM 时遗漏一个 data-xh-part 或写错名字，通道会明确指出节点与部件。

用法

import { onDiagnostic, setDiagnosticsConsoleOutput, setDiagnosticsLevel } from "@xihan-ui/core";

// 订阅
const off = onDiagnostic((record) => {
  if (record.code === "wc.missing-part")
    reportToSentry(record);
});

// 调阈值：'error' | 'warn' | 'silent'
setDiagnosticsLevel("warn");

// 关闭内建 console 输出，只使用自己的订阅
setDiagnosticsConsoleOutput(false);

其余可用的接口：

函数	作用
`getDiagnostics()`	获取通道对象本身
`reportDiagnostic(record)`	投递一条（自定义组件中使用）
`setDiagnosticsDedupe(on)`	同一 `code + scope + instanceId + part + message` 是否只报一次
`resetDiagnostics()`	清空订阅者、去重记录与全部开关

默认行为

环境	阈值	console 输出	去重
开发	`warn`	开	开
生产	`silent`	关	开

生产默认 silent，投递直接被丢弃，不产生任何开销。需要在生产收集时，显式调用 setDiagnosticsLevel('error') 并挂载自己的订阅。

去重键包含 message：同一个码下不同文案是不同的问题，只有逐帧重复的同一条才应被压缩。去重集有容量上限，超出即整体清空，长时间运行的进程不会无界增长。

隔离性

通道挂在全局，同一页面中多份 @xihan-ui/core 副本共用一条通道；
订阅方抛错不会回流进组件：上报逻辑出错不影响界面。

在测试中使用

把阈值调到 warn 并订阅，即可把契约违约变为用例失败：

import { onDiagnostic, resetDiagnostics, setDiagnosticsLevel } from "@xihan-ui/core";

beforeEach(() => {
  resetDiagnostics();
  setDiagnosticsLevel("warn");
});

it("不应有契约违约", () => {
  const records: DiagnosticRecord[] = [];
  onDiagnostic(r => records.push(r));
  render();
  expect(records).toEqual([]);
});

诊断通道 ​

不直接打日志的原因 ​

记录的形状 ​

现有的码 ​

用法 ​

默认行为 ​

隔离性 ​

在测试中使用 ​

相关 ​