docs: 渐进式插件教程（L0→L5）+ DESIGN.md 视觉规范 + plugin-template 脚手架

2026-09-11 02:18:01 +08:00
parent 8e4b5496e8
commit 4ed31a34fc
16 changed files with 844 additions and 1 deletions
@@ -0,0 +1,84 @@
+# 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)