---
title: "Log API"
description: "TypeScript 平台日志 API。"
---


> 在 TypeScript 中向宿主平台日志写入有界消息。

## 模块边界

`KSM.log` 只负责单条日志写入，不负责持久化、上传、轮转或远程采集。日志脱敏和采集策略由
宿主应用负责。

实现入口是 `frontend/src/api/log.ts` 和 `frontend/src/api/guards.ts`。

## 平台支持

| 项 | Windows | Android |
| --- | --- | --- |
| `log.write` | 支持 | 支持 |
| 输出 | 调试输出通道 | Android 系统日志 |
| 持久化 | 否 | 否 |

## 方法

```ts
await KSM.log.write({
  level: 'info',
  target: 'application',
  message: 'settings saved'
});
```

| 字段 | 约束 |
| --- | --- |
| `level` | `trace`、`debug`、`info`、`warn`、`error` |
| `message` | 1 到 65536 字节 |
| `target` | 可选，1 到 128 字节 |

## 安全规则

- 不记录密码、令牌、Cookie、连接字符串或用户隐私数据。
- 不在循环中输出高频日志。
- 不把 `log.write` 当作审计日志，审计记录需要宿主持久化和访问控制。

## 错误行为

| 错误码 | 场景 |
| --- | --- |
| `INVALID_ARGS` | 级别、message 或 target 非法 |
| `PERMISSION_DENIED` | 没有 `log.write` 权限 |
| `IO_ERROR` | 宿主日志服务拒绝写入 |
| `NOT_SUPPORTED` | 宿主未注册 Log 插件或日志服务 |
| `TIMEOUT` / `CANCELLED` | 请求被超时或取消 |

## 相关

- [Log 插件规则](/docs/kasumi/plugins/log)
- [共享类型](/docs/kasumi/api/types)

## 排查路径

1. 确认级别和 UTF-8 字节长度。
2. 确认 `log.write` 在 allowlist 中。
3. Windows 检查调试输出，Android 使用 `logcat` 查看对应 tag。