Maka Agent诊断日志系统怎么运作？AI助手故障排查完全指南

Maka Agent诊断日志系统怎么运作？AI助手故障排查完全指南

【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka

Maka（Apache Maka，孵化中）是一个本地优先（local-first）的 AI Agent 工作台：模型消息、工具调用、权限决策等事件都被记录为只追加的日志。当 AI 助手"失灵"时，Maka 诊断日志系统就是你最可靠的排查线索——它由有界日志缓冲器、无侵入的 console 捕获、启动失败诊断文件和单轮执行追踪（TurnTrace）组成，而且自带密钥脱敏，复制报告不会泄露隐私。本文带你从零读懂这套系统，并给出一份新手可直接照做的故障排查清单。

💡 想边读边看源码？先克隆仓库：git clone https://gitcode.com/GitHub_Trending/mak/maka

一、诊断日志系统的三大核心部件

先建立全局认知，Maka 的诊断能力由三层组成：

三者共同回答排查中最关键的三个问题：最近发生了什么？日志会不会失控膨胀？启动失败时能不能留下证据？

二、有界日志缓冲器：日志不会撑爆内存

日志系统的核心是DiagnosticLogBuffer（diagnostic-log.ts），它的设计对新手非常友好：

• 5 个日志级别：debug、info、log、warn、error，每条日志自动加 ISO 时间戳前缀；
• 容量硬上限：默认 64KB，超过就自动丢弃最旧的条目——诊断信息"新者优先"，内存占用永远可控；
• 单条限长：单条日志默认最多 8192 个码点，超长自动截断并标注<log entry truncated>，防止一条巨型输出冲掉整个缓冲区；
• 自动脱敏：写入前先经过redactSecrets（redaction.ts），密钥类内容会被打码。

三、无侵入捕获 console 输出

installConsoleDiagnosticLogCapture 会挂钩console的 5 个方法，把输出同时写入缓冲器，但完全保留原来的打印行为。它还有一个保险：捕获过程抛异常会被静默吞掉——诊断功能永远不会反过来破坏正常运行。

不同进程的缓冲器大小按需配置：

• Runtime Host 进程：64KB 缓冲（process-diagnostics.ts），并为 stderr 管道加了 EPIPE 保护——当宿主进程比客户端活得更久、管道被关闭时，后续日志直接丢弃而不是引发致命错误；
• 桌面端主进程：256KB 缓冲（main-process-diagnostics.ts），另配一个 16KB、仅留 4 条的宿主进程日志缓冲，专门记录"宿主进程消失"这类关键证据。

四、启动失败诊断：startup-diagnostic.json

最棘手的故障是"进程根本起不来"——此时内存日志已丢失。Maka 的对策是把启动失败写成磁盘文件startup-diagnostic.json（startup-diagnostic.ts）：

• 4 类失败原因：存储数据不兼容、状态迁移被阻塞、本地 IPC 安全校验失败、内部启动异常；
• 错误链：最多保留 4 层name/code/message，让你看清"谁引发了谁"；
• 日志摘录：附带最近 4 条关键日志；
• 自动清理：最多保留 32 份、仅保留 24 小时，不占空间。

下次启动成功时，系统会读取这份"遗书"，把上一次的崩溃证据直接呈现给你。

五、单轮执行诊断：TurnTrace

如果问题只出在某一次对话轮次上，Maka 可以按会话和轮次精确提取执行轨迹：getTurnTrace(sessionId, turnId)，超时控制为 2 秒（类型定义见 session-trace.ts）。配合桌面端一键复制诊断报告的机制（main-process-diagnostics.ts），你可以把环境信息 + 主进程日志 + 宿主日志 + 单轮轨迹打包发给维护者，信息完整且已脱敏。

六、隐私细节：脱敏与路径折叠

诊断报告会被复制出去，所以内置了两道防护：

1. 密钥脱敏：所有日志入缓冲前经redactSecrets处理；
2. 家目录折叠：collapseHomePath（diagnostic-log.ts）会把日志中的家目录路径统一替换为~，你的用户名、磁盘布局不会外泄；
3. 输入限长：手动报告的标题限 512 字符、描述限 24KB，防止误粘贴大段敏感内容。

七、新手故障排查 5 步实操清单 🛠️

按这个顺序走，能覆盖绝大多数"AI 助手罢工"场景：

1. 看提示、留报告：出现错误 toast 时先点"复制诊断报告"，别急着重启——报告里已含环境版本、日志和轨迹；
2. 查启动失败文件：应用起不来时，检查工作区里的startup-diagnostic.json，对照 4 类失败原因定位；
3. 核对连接状态：在扩展页打开对应 MCP 的详情面板，确认"状态"是已连接、传输方式和端点是否正确（配置入口见下图）；
4. 抓单轮轨迹：问题只在某轮对话复现时，用 TurnTrace 提取该轮的工具调用与权限决策序列；
5. 筛日志级别：在诊断报告中优先搜索ERROR与WARN，再回溯前后的INFO时间线，通常 1 分钟就能锁定异常点。

八、关键文件速查表

掌握了这套"有界缓冲 + 无侵入捕获 + 落盘遗书 + 单轮追踪"的组合拳，你对 Maka 故障的判断力就已经超过多数用户了——下次遇到异常，先复制报告、再查startup-diagnostic.json，让日志替你说出真相。

【免费下载链接】makaApache Maka (Incubating) is a local-first AI agent workspace. Model messages, tool calls, tool results, permission decisions, and termination events are recorded as an append-only log.项目地址: https://gitcode.com/GitHub_Trending/mak/maka