# 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.*`

```js
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](./05-renderer-components.md) · 回到 [索引](./README.md) · 契约全集 [../plugins.md](../plugins.md) · 视觉规范 [DESIGN.md](./DESIGN.md)