Log 插件 · 向宿主平台日志写入有界消息。 - 鼠子Blog

理解 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 字节

示例

TypeScript

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`	请求被超时或取消链路终止

排查路径

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