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/makaMakaApache Maka孵化中是一个本地优先local-first的 AI Agent 工作台模型消息、工具调用、权限决策等事件都被记录为只追加的日志。当 AI 助手失灵时Maka 诊断日志系统就是你最可靠的排查线索——它由有界日志缓冲器、无侵入的 console 捕获、启动失败诊断文件和单轮执行追踪TurnTrace组成而且自带密钥脱敏复制报告不会泄露隐私。本文带你从零读懂这套系统并给出一份新手可直接照做的故障排查清单。 想边读边看源码先克隆仓库git clone https://gitcode.com/GitHub_Trending/mak/maka一、诊断日志系统的三大核心部件先建立全局认知Maka 的诊断能力由三层组成部件职责核心文件有界日志缓冲器在内存里滚动保存最近的日志自动限长、脱敏diagnostic-log.tsconsole 捕获器把console.log/warn/error等输出顺手存入缓冲器node-diagnostic-log.ts启动失败诊断文件进程还没起来时把启动错误写成 JSON 落盘startup-diagnostic.ts三者共同回答排查中最关键的三个问题最近发生了什么日志会不会失控膨胀启动失败时能不能留下证据二、有界日志缓冲器日志不会撑爆内存日志系统的核心是DiagnosticLogBufferdiagnostic-log.ts它的设计对新手非常友好5 个日志级别debug、info、log、warn、error每条日志自动加 ISO 时间戳前缀容量硬上限默认 64KB超过就自动丢弃最旧的条目——诊断信息新者优先内存占用永远可控单条限长单条日志默认最多 8192 个码点超长自动截断并标注log entry truncated防止一条巨型输出冲掉整个缓冲区自动脱敏写入前先经过redactSecretsredaction.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.jsonstartup-diagnostic.ts4 类失败原因存储数据不兼容、状态迁移被阻塞、本地 IPC 安全校验失败、内部启动异常错误链最多保留 4 层name/code/message让你看清谁引发了谁日志摘录附带最近 4 条关键日志自动清理最多保留 32 份、仅保留 24 小时不占空间。下次启动成功时系统会读取这份遗书把上一次的崩溃证据直接呈现给你。五、单轮执行诊断TurnTrace如果问题只出在某一次对话轮次上Maka 可以按会话和轮次精确提取执行轨迹getTurnTrace(sessionId, turnId)超时控制为 2 秒类型定义见 session-trace.ts。配合桌面端一键复制诊断报告的机制main-process-diagnostics.ts你可以把环境信息 主进程日志 宿主日志 单轮轨迹打包发给维护者信息完整且已脱敏。六、隐私细节脱敏与路径折叠诊断报告会被复制出去所以内置了两道防护密钥脱敏所有日志入缓冲前经redactSecrets处理家目录折叠collapseHomePathdiagnostic-log.ts会把日志中的家目录路径统一替换为~你的用户名、磁盘布局不会外泄输入限长手动报告的标题限 512 字符、描述限 24KB防止误粘贴大段敏感内容。七、新手故障排查 5 步实操清单 ️按这个顺序走能覆盖绝大多数AI 助手罢工场景看提示、留报告出现错误 toast 时先点复制诊断报告别急着重启——报告里已含环境版本、日志和轨迹查启动失败文件应用起不来时检查工作区里的startup-diagnostic.json对照 4 类失败原因定位核对连接状态在扩展页打开对应 MCP 的详情面板确认状态是已连接、传输方式和端点是否正确配置入口见下图抓单轮轨迹问题只在某轮对话复现时用 TurnTrace 提取该轮的工具调用与权限决策序列筛日志级别在诊断报告中优先搜索ERROR与WARN再回溯前后的INFO时间线通常 1 分钟就能锁定异常点。八、关键文件速查表想了解什么看这里日志缓冲器与截断、脱敏算法diagnostic-log.tsconsole 捕获实现node-diagnostic-log.ts密钥脱敏规则redaction.tsRuntime Host 进程诊断process-diagnostics.ts桌面端诊断报告组装main-process-diagnostics.ts启动失败诊断协议startup-diagnostic.ts单轮执行追踪类型session-trace.ts缓冲器行为测试用例diagnostic-log.test.ts掌握了这套有界缓冲 无侵入捕获 落盘遗书 单轮追踪的组合拳你对 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考