L5 · 自诊断：日志规范与 Agent 自迭代闭环

本项目的愿景是「Agent 写插件、Agent 排障、Agent 迭代」。达成的前提是一切可观测：宿主日志、插件日志、渲染层错误都落盘且结构化。这一篇讲日志从哪来、到哪去、Agent 怎么用它排障。

1. 日志在哪

userData/logs/main-YYYY-MM-DD.log     ← 唯一日志文件，按天滚动，保留 14 天

Windows：C:\Users\<你>\AppData\Roaming\@aso\desktop\logs\ （Agent 侧：pi 的 read/grep 工具可直接读这个路径——排障第一步永远是读它。）

级别：dev 默认 debug，打包版默认 info；环境变量 ASO_LOG_LEVEL=debug|info|warn|error 覆盖。

2. 行格式

<ISO时间> <LEVEL> [<scope>] <message> k=v k=v
2026-09-10T10:21:33.120Z INFO  [plugin-host] plugin activated pluginId=demo-ui source=external
2026-09-10T10:21:33.451Z INFO  [plugin] settings changed pluginId=demo-ui endpoint=staging
2026-09-10T10:21:40.002Z ERROR [ipc] ipc failed channel=plugins:setEnabled ms=1203 err=Error: runtime rebuild failed

scope 一览：main / plugin-host / plugin（所有插件日志，带 pluginId 字段）/ agent-service / browser / ipc / renderer / logger。

3. 插件怎么写日志：`api.log.*`

export default function definePlugin(api) {
  const log = api.log                      // 自动带 pluginId 字段，进同一文件

  api.log.info('activation payload', { tools: 3, mode: 'standard' })
  try {
    risky()
  } catch (err) {
    api.log.error('risky step failed', { step: 'connect', err })   // err 会被序列化成 stack
  }
}

埋点规范（Agent 排障依赖这些惯例）：

激活时：info 一条「我装了什么」（能力清单/配置摘要）
关键决策与外部调用：info / debug + 结果字段
一切 catch：error + err 字段——禁止吞错不记
message 用英文短句、kv 用结构化字段（便于 grep pluginId=xxx）

4. 宿主替你记录的（不用自己写）

事件	scope	级别
插件扫描/装载/激活/禁用/重载全链路	plugin-host	info
main.mjs 加载失败 / 激活失败	plugin-host	error
设置值变更 / 一级入口切换 / 按钮动作	plugin-host	info/debug
全部 73 个 IPC 通道调用（成功 debug 含耗时，失败 error）	ipc	debug/error
Agent 回合开始/结束/结算、运行时重建	agent-service	info/error
渲染层 console（含插件 renderer 模块与 iframe 页）、白屏、崩溃	renderer	debug/error
进程级 uncaughtException / unhandledRejection	logger	error

5. Agent 排障闭环（自迭代的核心流程）

发现问题（用户反馈 / 日志 error）
  ↓ 读 userData/logs/main-<今天>.log
  ↓ grep pluginId=<自己的id>  与  ERROR
  ↓ 对照本文第 4 节判断：装载失败？激活抛错？IPC 超时？渲染崩溃？
  ↓ 改插件代码（L0-L4 的对应章节）
  ↓ 触发重载（设置页开关 / 重启）→ 再读日志验证新一次 plugin activated
  ↓ 循环直到日志干净

写插件时请遵守：每个可能失败的操作都有日志、每条 error 都能定位到步骤。这是 Agent 能替你维护插件的最低要求。

6. 快速自查清单

装载了吗：external main loaded pluginId=<id>
激活了吗：plugin activated pluginId=<id>
有报错吗：ERROR + pluginId=<id>
IPC 通吗：ipc failed channel=… 是宿主问题还是插件问题
渲染崩了吗：renderer console 中 [window.onerror] / [unhandledrejection]

上一篇 L4 · 回到索引 · 契约全集 ../plugins.md · 视觉规范 DESIGN.md

3.8 KiB Raw Blame History Unescape Escape