🐤 SmolLogger：为 LLM 工程而生的极简日志工具

背景故事：当 AI 工程师被日志困扰

你正在调试一个大型 Prompt 工程，数以百计的 API 调用，每个调用的输入（Prompt）和输出（Response）混杂在终端的滚屏输出里。忽然某次调用出错了，但你根本分不清是哪一次——日志格式混乱，没有时间戳，没有调用位置，你能做的只是重新跑一遍，手动搜索。

这正是 smol-ai/logger（SmolLogger）要解决的问题。它的作者 swyxio 是 AI 工程领域的知名布道者，在 Node.js 生态中摸爬滚打多年，深知传统日志工具（Winston、Bunyan）对于 LLM 应用场景的"过重"——启动慢、依赖多、配置复杂。于是他用不到 100 行核心代码，打造了一个"刚刚好够用"的日志工具。

这个项目的诞生，折射出一个更大的趋势：Prompt 工程的工具化。当 LLM 应用从实验走向生产，开发者开始意识到，LLM 调用的日志记录、版本追踪、效果对比，都需要专门的工具支撑——而不能靠简单的 console.log。

核心功能：从"日志"到"Prompt 版本控制"

SmolLogger 表面上是一个日志库，但它的设计意图远比日志更深远。

Prompt 与 Response 的配对捕获

在 LLM 应用中，最核心的调试需求是什么？是记录"某次调用我输入了什么，AI 输出了什么"。SmolLogger 的 _log 方法正是围绕这个需求设计的。它通过 Node.js 的 callsite 信息（Error.stack）自动捕获调用所在的文件路径和行号，结合时间戳（距启动时间、距上次调用时间），将每次日志记录组织成结构化数据，写入 .logs/ 目录下的 JSON 文件。

每个日志文件包含：文件路径（$callsite.filePath）、代码行号（$callsite.location）、距启动时间（$timeElapsed.sinceStart）、距上次调用时间（$timeElapsed.sinceLast），以及任意结构的 payload 数据。开发者可以在 IDE 中直接浏览 .logs/ 目录，通过文件名（001: myPrompt.json）快速定位特定日志会话。

CLI 导出为 TSV：表格即分析

最有意思的功能是内置的 log2tsv CLI 工具。它将所有 JSON 日志文件聚合导出为一个 TSV（制表符分隔值）文件，可直接导入 Google Sheets、Excel 或在线表格工具（如 Quadratic）进行分析。

npx @smol-ai/logger log2tsv

这背后的逻辑很清晰：对于 Prompt 工程师来说，Excel 和 Google Sheets 才是真正的"数据分析工具"——不需要复杂的 BI 系统，不需要数据库，只要能排序、筛选、做简单的统计分析就够了。swyxio 在 README 中直接写道："Spreadsheets are all you need"（表格工具就是你所需要的一切）。

极简设计哲学：不是日志工具，是日志格式约定

SmolLogger 刻意不做日志级别（DEBUG/INFO/WARN/ERROR），理由是"太复杂"——对于 LLM 调试来说，你需要的是完整记录每一次调用，而不是按级别过滤。它也不追求浏览器端支持（虽然代码层面不难实现）。这种"有所不为"的设计选择，让核心代码压缩到 100 行以内。

技术实现：TypeScript + fs + 零依赖

架构概览

项目结构清晰，分为三个核心模块：

• src/smol-logger.ts：主类 SmolLogger，包含日志记录核心逻辑
• src/utils.ts：工具函数（JSON 序列化、时间格式化、路径捕获）
• src/cli.ts：log2tsv 命令行工具实现

核心类 SmolLogger 的构造函数接收 logToConsole 和 logToStore 两个布尔参数，分别控制是否输出到终端和写入文件（默认为 true）。每次实例化时，自动在项目根目录创建 .logs/{timestamp}/ 子目录。

关键实现细节：

1. callsite 捕获：使用 Error.stack 解析调用栈，从堆栈信息中提取文件名和行号。这是 Node.js 中获取调用位置的常用技巧，但要注意堆栈格式在不同版本中可能变化。

2. JSON 序列化：自定义 getCircularReplacer() 处理循环引用（LLM 返回的对象可能包含自引用），同时以 $$payload 字段额外保存 payload 的字符串化版本，便于直接读取。

3. stdout 拦截：在记录日志时临时重定向 process.stdout.write，将标准输出统一加上日志名前缀（黄色），使终端输出保持可读性。

4. Rollup 构建：使用 Rollup 打包为 UMD 和 ES5 格式，发布到 npm 的包名是 @smol-ai/logger，支持 CommonJS 和 ES Module 两种引入方式。

依赖分析

package.json 中没有生产依赖，只有一个开发依赖：ts-jest（测试框架）。这也是 swyxio 强调的"零依赖"承诺的实际体现。相比之下，Winston 依赖 1 个 npm 包，Bunyan 依赖 4 个。

Benchmark 验证

项目自带 benchmark 脚本，对比 SmolLogger 与 Winston、Bunyan 在基本日志记录场景下的性能。在 2023 年的测试中，SmolLogger 速度最快——当然，这种基准测试只覆盖了最基本的场景（创建 logger 实例 + 写入一条日志），真实项目的性能瓶颈通常在 I/O 层面，不在日志库本身。

上手体验：安装即用，无需配置

使用方式极度简单：

npm install @smol-ai/logger

import { SmolLogger } from '@smol-ai/logger';

const logger = new SmolLogger({ logToConsole: true, logToStore: true });
const log = logger.log;

// 记录 Prompt
const result = await openai.chat.completions.create({...});
log('GPT4 Response', { prompt: userInput, response: result });

// log 函数返回 payload，支持链式
const processed = logger.log('post-process', transformFn(result));

安装后，log 函数返回 payload 本身，可以直接链式使用——这是从 FP（函数式编程）借鉴的设计：单参数函数作为"日志包装"，同时保留原始返回值。

项目要求 Node.js >= 16.0.0，没有任何平台特定依赖，macOS/Linux/Windows 均可运行。

局限与争议：为什么没人用它做生产日志？

绑定已失效

README 在 2024 年就坦诚写道："logger binding 不工作了，虽然以前是可以的，我们也不知道为什么。"（> 2024 note: the binding for the logger doesnt work anymore even tho it used to - we don't super know why yet）这意味着项目在 2024 年后处于维护停滞状态——最后代码更新于 2024 年 3 月，距今已超过 1 年。对于一个 MIT 协议的开源项目，任何人都可以接手维护，但目前没有看到活跃的社区贡献。

非生产级日志系统

.logs/ 目录存储在项目本地，没有日志轮转（log rotation）机制，在高频调用场景下可能导致磁盘空间快速耗尽。没有内置的结构化日志格式规范（每条日志的 payload 结构完全由调用者决定），这在团队协作时会导致日志格式不统一的问题。

LLM 生态的快速迭代

2023-2024 年间，大量专业的 LLM 可观测性平台涌现（如 LangSmith、PromptLayer、Braintrust），提供了远比文件系统日志更强大的调试、评估和版本控制能力。这些平台有商业资金支持、持续迭代，SmolLogger 作为个人项目很难与之竞争。

行业意义：Prompt 工程工具化的一个注脚

SmolLogger 的价值不在于它本身有多强大，而在于它代表了一种思路：用极简工具解决特定场景问题。当主流日志库还在追求"日志级别 + 格式化 + 远程传输"的全面覆盖时，SmolLogger 用"文件即 UI + 表格即分析"的组合，回答了一个更精准的问题："LLM 工程师调试时真正需要什么？"

它的局限性也映射了一个现实：AI 应用的工具生态还在快速演进。2023 年的"最佳实践"，到 2025 年可能已被专业平台替代。但作为学习样本——看一个有 150 颗星的开源项目如何用不到 100 行核心代码解决一个具体问题——SmolLogger 仍然值得一读。

---

本报告由 Hermes Agent 自动生成，分析时间：2026-07-28