better-logging

更完善的日志记录

将重要操作转化为持久化的结构化记录，让你通过一次查询就能回答“发生了什么？”，而无需翻阅一串日志行。

应将运行时负责的操作视为埋点单位，而不是在整个代码库中零散地添加单条日志语句。

快速开始

• 先运行审计脚本：

python3 scripts/audit_queryable_outcomes.py \
  --root . \
  --format markdown

从此技能目录运行随附的 scripts/audit_queryable_outcomes.py。如有需要，解析出包含此 SKILL.md 的目录，并显式传入脚本路径。

• 更改代码前，只阅读一份运行时参考文档：
  • Electron、tRPC、IPC、桌面后台任务：references/runtime-patterns-electron.md
  • Node HTTP 应用和工作进程：references/runtime-patterns-node.md
• 在编写中间件或包装器之前，使用 references/event-schema.md 定义规范事件结构。
• 先为最关键的 3 个用户操作添加埋点。不要一开始就覆盖仓库中的每条路由或命令。

工作流

1. 梳理操作边界。 传输边界通常最重要：HTTP 处理程序、tRPC 过程、IPC 命令、队列使用者、定时任务、启动流程。 将底层辅助函数视为补充信息的入口，而不是规范操作。
2. 选择操作记录结构。 阅读 references/event-schema.md。 先锁定必需字段：操作名称、类型、时间戳、持续时间、成功状态、稳定的错误代码、关联 ID、版本元数据。
3. 在边界处添加一个包装器。 在入口处开始记录。 在操作运行期间补充信息。 在 finally 中完成并持久化，以便成功和失败路径都会生成结果。
4. 添加有助于调试的领域上下文。 有数据时，加入操作者、资源、触发因素、灰度发布标志、重试次数和版本信息。 省略仅对本地调试有用或包含机密的字段。
5. 持久化或可靠地发出结果。 优先选择本地表、运维事件存储或可查询的分析数据接收端。 关键结果不能依赖易失的控制台日志或内存缓冲区。
6. 用实际问题验证。 阅读 references/rollout-and-queries.md。 如果新结构无法快速回答有关失败、延迟和回归的问题，那么埋点仍然不够完善。

运行时选择

• Electron 桌面应用： 阅读 references/runtime-patterns-electron.md，了解 tRPC mutations、ipcMain.handle、启动操作和后台任务。
• Node 服务端或工作进程： 阅读 references/runtime-patterns-node.md，了解 Express、Fastify、Hono 风格的处理程序、队列和定时任务。

注意事项

• 对每个重要操作，优先记录一个持久化的结果事件，而不是添加许多零散的日志行。
• 保持 error_code 稳定且可通过机器查询。将自由格式消息视为次要信息。
• 记录每个关键操作的持续时间和重试次数。
• 尽早添加关联字段。缺少 request_id、operation_id 或 session_id 会削弱所有下游查询。
• 将运维事实与产品分析区分开。可以镜像，但不能用产品分析取代运维事实。
• 对不严格必需的机密、令牌、原始提示词、用户内容和完整 URL 进行脱敏或哈希处理。
• 默认不要发出巨型数据块。应改为持久化引用或经过概述的上下文。

资源

• scripts/audit_queryable_outcomes.py 扫描仓库，查找可能的操作边界、现有埋点、关联字段和持久化结果信号。
• references/event-schema.md 必需字段和推荐字段、命名指南及脱敏规则。
• references/runtime-patterns-electron.md Electron、tRPC、IPC、启动流程和后台任务的边界选择及包装器模式。
• references/runtime-patterns-node.md HTTP 应用、队列使用者和定时任务的边界选择及包装器模式。
• references/rollout-and-queries.md 改造计划、验收清单，以及新埋点必须能够回答的示例问题。