85 lines
3.8 KiB
Markdown
85 lines
3.8 KiB
Markdown
# 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)
|