面向没有读过 AstrBot 源码的开发者。以一条对话为入口，查看模型输入、插件改动、工具、Skills、请求差异和用量；复读探针独立保留，不要求安装其他插件。
- 安装并启用插件，重载一次。
- 打开 AstrBot WebUI → 插件 → MsgDebugger → Pages → logs。
- 发送一条消息，在左侧按群聊或私聊对象展开并选中记录。先读“过程总览”，再沿顶部流程进入具体请求。
- “模型输入”默认定位最后一条 user，消息目录每页 8 条。50 条输入可以只属于一次模型请求；角色、排列顺序和工具循环可在页内的一分钟教程里学习。
- 用顶部标签切换“过程总览、模型输入、插件改动、工具、Skills、请求对比、Token 与耗时、复读与采集”。
自动刷新仅更新左侧列表；点击“更新这条记录”获取新的详情，阅读展开内容时不会跳动。列表显示最近 200 条，可按文本、群、用户、会话搜索。每个对象的记录单独分页，不同平台实例不会合并；缺少归属字段的旧记录保留原会话。完整的新手路径和界面截图见 中文导航说明。
- 已注册、本次提供、实际调用是不同状态。 工具标签分别显示当前目录、历史请求工具定义、执行记录。
- Skill 已安装不等于全文已被模型读取。 页面显示当前文件和请求中名称 / 路径的文本匹配证据，不把文本匹配当作读取证明。
- 采集快照不等于最终 HTTP 请求。 内置 Agent 记录点位于 Provider 转换之前；模型能力过滤、服务商格式转换、Provider 内部重试仍可能发生。
- 过程总览：入站、插件处理、模型每次尝试、工具执行、最终响应、回复装饰和发送通知。
- 模型输入：按消息顺序展示 system / developer / user / assistant / tool，以及工具参数定义和额外内容。
- 插件改动：显示来源插件、处理函数、事件类型、执行耗时、采集字段前后快照。默认仅显示改动和异常。
- 请求对比：默认定位同一会话的上一条记录，可手动选择两条记录及其中的模型请求。支持基础指令 / 工具和全部内容两种范围。
- Token：按请求展示服务商回报的输入、输出、缓存输入；只对已回报部分求和。分块的“字符数 ÷ 4”仅是粗估，不是分词计数或账单。
- 导出：预览 JSON 后下载，隐藏记录头部身份字段及部分常见密钥形式。正文仍需人工检查。
对移动端做了最小适配
新安装默认关闭复读，升级保留原有配置值。可以在“复读与采集”标签临时开关，也可以由管理员发送：
/md echo on
/md echo off
/md echo status
/md echo reset
reset 恢复插件配置。重载也会清除临时覆盖。配置中可选被动回复 / 主动发送、纯文本 / 完整消息链，以及群和用户白名单。白名单只限制复读，不限制采集。主动发送直接调用 AstrBot，不依赖 MsgProcessor 或其他插件。
插件归因通过可恢复的运行时适配器包装 AstrBot 注册的消息事件处理函数。记录每次协程执行或生成器恢复前后的状态，避免把 yield 之后的下游处理归到前一个插件。保留原返回值和异常，卸载时只恢复仍由本实例持有的包装。
“执行边界观测”证明变化发生在这个函数执行区间。嵌套调用、插件自行创建任务、共享事件被并发修改时，不能证明某一行代码是唯一来源。采集字段包含消息文本/消息链、回复、请求指令/历史/工具、可识别的 Agent 消息和字典参数；不跟踪任意对象全部属性。
内部 Agent runner 适配器记录每次已观测的模型调用尝试，使用独立 attempt ID 关联响应，支持并发对话。第三方 Agent、插件直接调用网络或绕过 runner 的请求、Provider 内部重试不保证覆盖。工具起止钩子没有稳定调用 ID 时，按事件顺序展示，不把同名并发调用强行配对。
适配器依赖 AstrBot 内部接口，接口不可用时独立降级，页面显示未覆盖。astrbot_version 表示最低安装要求，不代表所有版本上的内部采集适配器均已验证。模型内部未返回的思考内容无法采集。
插件数据目录：traces.sqlite3。使用 Python 标准库 SQLite，前端不引入框架；仅需 PyYAML（读取 Skill frontmatter），见 requirements.txt。
- 默认保留 200 条，数量可配置为 10–1000。
- 单阶段 256 KiB、单记录 2 MiB / 300 阶段；内存与持久化内容各约 64 MiB 上限。
- 字符串最多 64000 字符、集合最多 500 项、嵌套最多 16 层；内嵌 base64 媒体省略。
- 截断处有标记；因此历史对比、统计可能不完整。SQLite 文件因空闲页可能大于内容上限。
- 存储失败降级为内存，并在页面显示错误。
- 首次创建数据库时导入旧
traces.jsonl，保留原文件。页面清空不会删除这个旧备份；如需彻底清理旧隐私记录，另行删除旧文件。
日志会包含聊天正文、提示词和工具结果。已知密钥字段会被隐藏，但不保证任意正文都自动脱敏。页面通过 AstrBot 自带 Pages 桥接访问，不另开公开服务。
不需要依赖或导入 MsgDebugger。其他插件可以在 on_llm_request 中写入追加式报告，版本 1 示例：
reports = list(event.get_extra("_msgdebugger_events", []))
reports.append(
{
"version": 1,
"source": "your_plugin_name",
"kind": "prompt_injection",
"summary": "Added project instructions",
"data": {"position": "system", "text": "..."},
}
)
event.set_extra("_msgdebugger_events", reports)报告跟随该事件关联到对话。Debugger 在自己的请求快照钩子（priority -10000）消费最多 100 条报告并清空队列，因此报告应在这个钩子之前写入；之后写入的报告不保证本轮采集。报告来源标为“插件自行报告”，不等同于独立验证的归因。未知业务字段作为数据展示，不参与执行。
页面入口仍是 logs，原“精简 / 注入 / 完整”预设改为八个任务标签；注入详情迁移到“插件改动 / 请求对比”，原复读命令保留并限制管理员使用。旧 JSONL 作为历史数据导入，缺少逐轮快照的记录不能补算工具、对比和用量。旧 _md_injection / _ii_injected 专用约定不再采集，新接入请使用上述统一报告接口。
python -m unittest discover -s tests -v
ruff format .
ruff check .
node --check pages/logs/app.js
node --check pages/logs/ui.js
node --check pages/logs/conversation.js
node --experimental-vm-modules tests/page_smoke.mjs
测试使用最小替身验证采集契约，无需安装完整 AstrBot。真实平台、服务商、Pages 布局和插件热重载仍需在运行中的 AstrBot 环境验收。