---
title: "Log 插件"
description: "向宿主平台日志写入有界消息。"
---


> 理解 Log 插件的日志级别、大小限制、输出目标和安全边界。

## 模块边界

Log 插件把前端消息写入宿主平台日志，不负责持久化、上传、轮转或远程采集。日志采集、
脱敏和保留策略由宿主应用配置。

| 层级 | 入口 | 责任 |
| --- | --- | --- |
| 前端 API | `frontend/src/api/log.ts` | 参数守卫和命令封装 |
| 协议清单 | `protocol/plugins.json` | `log.write` 归属 `log` |
| Windows 插件 | `windows/src/plugins/ksm_log_plugin.cpp` | 调用宿主日志服务 |
| Android 插件 | `KSMLogPlugin.kt` | 调用 Android 日志服务 |

## 参数

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

## 示例

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

Windows 写入调试输出通道，默认 target 为 `kasumi`。Android 使用系统日志优先级映射，
不会把日志自动写入应用数据目录。

## 安全规则

- 不记录密码、令牌、连接字符串、完整 Cookie 或用户隐私数据。
- 不在循环中输出高频日志，避免调试器或系统日志成为性能瓶颈。
- message 和 target 受字节长度限制，超长请求返回 `INVALID_ARGS`。
- 发布环境是否可见由宿主日志策略决定，不能把日志当作持久审计记录。

## 平台差异

| 项 | Windows | Android |
| --- | --- | --- |
| 输出 | `OutputDebugStringW` | Android `Log` |
| target | 默认 `kasumi` | 传入日志 tag |
| 持久化 | 否 | 否 |
| 权限 | `log.write` | `log.write` |

## 错误行为

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

## 排查路径

1. 确认级别属于协议枚举。
2. 检查 message 和 target 的 UTF-8 字节长度。
3. 确认宿主日志服务和权限已配置。
4. Windows 使用 DebugView 或调试器查看输出，Android 使用 `logcat` 查看对应 tag。