forhumans：让AI代理的JSON日志变得可读，提升CI工作流的可观测性

forhumans是一个轻量级CLI工具，专门用于将pi.dev AI代理工具输出的结构化JSONL事件流转换为人类可读的日志格式，帮助开发者在CI环境中清晰了解AI代理的运行状态和思考过程，解决原始JSON日志阅读繁琐的问题。该工具采用Go语言编写，无外部依赖，部署简单且性能优异。

随着AI代理在软件开发工作流中的广泛应用，开发者面临监控和理解其行为的挑战。在非交互式CI环境中，AI代理输出的JSON格式事件流便于程序处理，但人类阅读和理解这些原始日志十分繁琐。forhumans项目正是为解决这一问题而生。

forhumans的设计理念是保持简单、专注单一职责。作为纯Go语言编写的工具，它不依赖外部库，仅使用Go标准库实现所有功能，带来部署简单和性能优异的优势。其核心工作流程遵循Unix过滤器模式：从标准输入读取JSONL事件流，解析事件类型和内容，输出人类可读的日志行。

forhumans定义的日志格式为HH:MM:SS [TAG] content，包含时间戳、事件类型TAG和具体内容。支持的事件类型包括：会话事件（元数据如会话ID、工作目录）、代理生命周期事件（START/END）、对话轮次事件（START/END）、用户消息、思考过程（默认截断200字符）、代理响应（多行缩进）、工具调用事件（全过程记录）。

forhumans典型使用场景是CI/CD管道，开发者可将AI代理的标准输出通过管道传递给工具，实时获取可读日志。基本使用方式如cat output.jsonl | ./forhumans-cli或./agent-harness | ./forhumans-cli。工具提供--lifecycle选项，可显示完整生命周期事件（默认隐藏以保持简洁）。

forhumans代码结构清晰：internal/events包负责事件类型定义、JSON反序列化、时间戳解析和文本提取；internal/formatter包处理格式化逻辑（文本截断、输出生成）；cmd/main.go作为CLI入口，负责JSONL读取和参数解析。项目包含40个单元测试，覆盖所有事件类型、边界情况等，确保稳定性。

forhumans自动跳过冗余中间事件：_delta事件（如thinking_delta）、除tool_execution_start/end外的_start/*_update事件、非用户类型的message_start事件。对于未知类型事件，标记为[UNKNOWN]并保留原始JSON，保证向前兼容性和新事件可见性。

forhumans是小而美的工具，解决了AI代理工作流中的实际问题，架起AI代理与人类开发者的桥梁。随着AI代理在软件开发中角色的重要性提升，这类可观测性工具将更关键，助力调试理解AI行为，提升AI系统的透明度和可解释性。