日志别急着滚走。

终端里一直有字在动，会让人觉得系统正在认真工作。但当问题出现，真正需要的可能只有前后几行：输入从哪里来，哪一步接受了它，谁又拒绝了它。如果这些关系没有留下，打印得再热闹，也只是把寻找答案的工作推给未来的自己。

这篇示例文章从 SCOPE 的概念出发，讨论一条记录怎样变得容易回看。所有事件与错误都是创作用例，不来自真实故障现场。下面的代码可复制到浏览器开发者工具或 Node.js 处理自备文本；它只处理文中声明的格式，不连接设备，也不提供未知格式的自动解析保证。

先记录一件事，再考虑打印一句话。

把日志看成一件事的记录，字段就有了目的。来源区分示例与真实输入，模块说明由谁产生，等级提示关注顺序，事件标识把同一操作的多条记录串起来，消息则补充人能直接读懂的解释。字段不必一开始很多，但每个字段都应该有一致含义。

时间尤其需要说明语境。演示里可以用从启动后经过的相对时间，但不能把它伪装成设备真实时钟；真实固件也可能只有单调计时，没有可信的日历时间。多来源记录放到一起前，还要知道它们能否比较。一个好看的时间格式，并不能自动解决时钟不同步的问题。

{
  "source": "simulation",
  "elapsedMs": 1200,
  "module": "view",
  "level": "info",
  "eventId": "demo-0001",
  "message": "示意参数已更新；未发送硬件指令"
}

原创记录提示：让每条消息回答“发生了什么”，让共同字段回答“它和谁有关”。

写给实践时的自己

结构化之后，也别把原文丢了。

当一段文本被拆成字段，界面会更好筛选，但也可能丢失细节。解析器应该保留原始行号与原文，遇到无法识别的内容时给出明确状态，而不是悄悄跳过，再让读者误以为系统从来没有输出那一行。成功解析和记录内容正确，是两件不同的事。

下面示例只接受每行一个 JSON 对象，并校验一组最小字段。它不猜测任意终端文本的格式；有效行和错误行分开返回，错误仍保留输入位置。实际使用时还应按真实数据量决定文件大小限制、分块策略与字段长度约束，不能因为短样例顺畅就承诺大文件也一样。

// 只处理每行一个 JSON 对象的示例格式。
function parseLines(text) {
  const valid = [];
  const invalid = [];
  text.split(/\r?\n/).forEach((raw, index) => {
    if (!raw.trim()) return;
    try {
      const row = JSON.parse(raw);
      if (!row || typeof row !== 'object' || Array.isArray(row)
        || !['module', 'level', 'eventId', 'message'].every(
          key => typeof row[key] === 'string'
        )) {
        throw new Error('缺少约定的文本字段');
      }
      valid.push({ ...row, line: index + 1, raw });
    } catch {
      invalid.push({ line: index + 1, raw, reason: '格式未识别' });
    }
  });
  return { valid, invalid };
}

筛掉干扰，也要留住上下文。

关键词、模块和等级应该共同影响同一份结果。选择一个模块，再输入关键词，含义应是同时满足这两个条件，而不是后一个动作悄悄覆盖前一个条件。当前筛选条件、结果数量和清空入口都要可见，零结果时也要告诉读者如何退回，而不只留一片空白。

但筛选越精确，越容易把原因藏到看不见的地方。因此展开一条记录时，还应该能找回同一事件的其他步骤，或者按原始行号查看邻近内容。筛选是临时的观察视角，不应修改原始集合；清空条件后，所有输入记录仍然在那里。

• 默认视图：交代数据来源、总量与支持的格式。
• 筛选结果：显示组合条件和当前匹配数量。
• 没有结果：保留输入，提供清空条件的操作。
• 事件详情：展示原文与同一操作的相关记录。
• 解析失败：保留失败行，不把它当成普通的空结果。

让一次操作，从头到尾都找得到。

以机器人关节演示为例，选择关节、确认参数和更新图形可以共享一个事件标识；展开最后一条记录时，仍应能回到最初的输入。把作品、关节、结构模块与相关文章连接起来，记录就能帮助读者从结果返回原因。浏览器里的这条探索链仍属于模拟，不能替代实物动作记录。

关联也要守住范围：页面更新不能记成“电机已到位”，计划发送不能记成“设备执行成功”。真实工程将来接入时，需要分别表达目标生成、发送、接收与观测；没有反馈的环节就保留未知。准确描述状态，比把每次操作都涂成绿色更重要。

少一点噪声，多一点可以复现的条件。

连续变化的数字适合放在实时面板，关键事件适合进入日志。拖动时每帧输出同类消息，会把真正的转折淹没；在确认输入时记录摘要，再允许展开细节，通常更适合回看。哪些事件必须保留，应根据调试目标决定，而不是用输出数量证明系统在运行。

回到真实项目，记录还需要包含版本、环境、步骤和限制，并在分享前检查凭据与私人信息。SCOPE 的方案与本文示例先定义阅读边界；接入真实文件时，还要根据支持格式验证解析、错误恢复和性能。希望下一次回来时，留下的是一条能够从头读到尾的线索。