# General Translation Platform: 诊断
URL: https://generaltranslation.com/zh/docs/platform/core/reference/diagnostics.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 格式化诊断文本，但不进行日志记录或上报。createDiagnosticMessage 和 formatDiagnosticErrorDetails 的 API 参考。

从 `generaltranslation/diagnostics` 导入这些函数和类型。它们仅生成字符串，不会记录日志、上报异常、发送遥测数据，也不会对密钥做脱敏处理。

| 导出                                               | 描述            |
| ------------------------------------------------ | ------------- |
| [`createDiagnosticMessage`](#create-message)     | 将诊断文本组合为一条消息。 |
| [`DiagnosticMessageInput`](#message-input)       | 消息字段及可选的上下文。  |
| [`DiagnosticSeverity`](#severity)                | 支持的严重程度标签。    |
| [`formatDiagnosticErrorDetails`](#error-details) | 将未知错误转换为可选文本。 |

## `createDiagnosticMessage` [#create-message]

**签名** `(input: DiagnosticMessageInput) => string`

按以下顺序组合传入的字段：发生了什么及原因、安抚说明、修复方法与退路、详细信息，以及文档 URL。它会去除句子文本首尾的空白，并在需要时补充标点。可选的 source 和 severity 构成前缀；以小写字母开头的 `wayOut` 可以并入修复语句。

```ts
import { createDiagnosticMessage } from 'generaltranslation/diagnostics';

const message = createDiagnosticMessage({
  source: 'Importer',
  severity: 'Warning',
  whatHappened: 'The file was skipped',
  fix: 'Choose a supported format',
});
// 返回字符串，不会自动输出任何日志。
console.log(message);
```

## `DiagnosticMessageInput` [#message-input]

**类型** object · 消息格式化器的**必需**输入

| 字段             | 描述                | 类型                   | 可选 | 默认值 |
| -------------- | ----------------- | -------------------- | -- | --- |
| `whatHappened` | 主要说明。             | `string`             | 否  | —   |
| `source`       | 标识调用方的前缀。         | `string`             | 是  | —   |
| `severity`     | 前缀标签。             | `DiagnosticSeverity` | 是  | —   |
| `reassurance`  | 仍然安全或未受影响的内容。     | `string`             | 是  | —   |
| `why`          | 原因，会拼接在主要说明之后。    | `string`             | 是  | —   |
| `fix`          | 建议的修复操作。          | `string`             | 是  | —   |
| `wayOut`       | 替代操作。             | `string`             | 是  | —   |
| `details`      | 附加详情；若为数组，则以逗号连接。 | `string \| string[]` | 是  | —   |
| `docsUrl`      | 追加到消息末尾的文档 URL。   | `string`             | 是  | —   |

仅 `whatHappened` 为必需字段；省略的可选字段不会生成任何文本。各子句请按其在句中应有的大小写形式提供。请勿在 `details` 或其他字段中包含密钥：格式化器不会进行任何脱敏处理。

```ts
import type { DiagnosticMessageInput } from 'generaltranslation/diagnostics';

const input: DiagnosticMessageInput = { whatHappened: 'No files matched' };
```

## `DiagnosticSeverity` [#severity]

**类型** `'Error' | 'Warning'`

该值仅控制可选的文本标签，不影响日志级别或异常行为。若省略严重程度，则不会添加严重程度前缀。

```ts
import type { DiagnosticSeverity } from 'generaltranslation/diagnostics';

const severity: DiagnosticSeverity = 'Warning';
```

## `formatDiagnosticErrorDetails` [#error-details]

**签名** `(error: unknown) => string | undefined`

传入 `null` 或 `undefined` 时返回 `undefined`，否则返回 `String(error)`。该函数不会提取结构化的错误字段，也不会对字段内容进行脱敏。

```ts
import { formatDiagnosticErrorDetails } from 'generaltranslation/diagnostics';

console.log(formatDiagnosticErrorDetails(new Error('Invalid file'))); // Error: Invalid file
console.log(formatDiagnosticErrorDetails(null)); // undefined
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.