dev-structured-logs

结构化日志

对旧版日志调用和 Serilog JSON 配置进行保守且便于审查的重写。默认采用试运行模式，并始终生成机器可读的预览输出。

这是一项用于确定性日志重写的操作技能。请勿将其用作通用后端可观测性或 CI/CD 指南技能。

工作流

1. 先运行试运行：

python .codex/skills/dev-structured-logs/scripts/structured_logs.py --path <repo> --dry-run

2. 审查：

• <repo>/patch.diff
• <repo>/preview-report.json

3. 审查后再应用：

python .codex/skills/dev-structured-logs/scripts/structured_logs.py --path <repo> --apply --backup-dir <dir>

4. 可选：提交：

python .codex/skills/dev-structured-logs/scripts/structured_logs.py --path <repo> --apply --commit-msg "chore: structured logging migration"

如果任务扩展到服务设计、运行时可观测性策略或 API 层重构，请切换到 $software-csharp-backend。 如果任务扩展到 nuke/Build.cs 或 CI 执行变更，请切换到 $ops-nuke-cicd。

CLI 合约

支持以下选项：

--path <repo>
[--dry-run]
[--apply]
[--preview-file <path>]
[--backup-dir <dir>]
[--enable-handler-scope]
[--handler-pattern <pattern>]
[--log-framework <serilog|microsoft|auto>]
[--exclude <glob>] (repeatable)
[--commit-msg "message"]

行为：

• 未提供 --apply 时，默认采用试运行模式。
• 默认禁用 CommandHandler 范围插入；使用 --enable-handler-scope 可显式启用。
• 不要触碰排除的／生成的文件夹：bin/、obj/、node_modules/、packages/、.git/、.vs/。
• 在 preview-report.json 中通过 risk_level 和 reason 标记有风险的重写。

第 1 部分：日志转换规则

仅重写 logger.Log* 和 _logger.Log* 形式的调用，且消息参数使用以下形式：

• 字符串拼接
• String.Format(...)
• 字符串插值（$"..."）

将其转换为带有属性和参数列表的消息模板。 保留插值表达式作为参数表达式（包括三元表达式）。

保留：

• 异常重载的参数顺序（LogError(ex, "...", args...)）
• 原始表达式顺序

如果任何消息参数可能产生副作用（方法调用、new、递增／递减、复合赋值）：

• 在日志调用前将表达式提取到临时变量
• 在报告中将该变更标记为需人工审查

不要尝试有风险的跨语句重写。将变更限制在调用点。

第 2 部分：CommandHandler 范围规则

通过以下任一方式检测处理程序：

• 实现 ICommandHandler<T> 的类
• 符合处理程序模式的方法（默认 Handle|HandleAsync），并将第一个参数视为命令对象的公共方法

设置 --enable-handler-scope 时，如果方法开头缺少范围，则插入范围：

• 根据命令的键属性构建字典：UserId、TransactionId、TransferId、VerificationId、SessionId、Id
• 使用字典集合初始化器样式初始化范围项，例如：

var __scopeItems = new Dictionary<string, object>
{
    ["Property1"] = command.Property1
};

• 使用 using var _scope = _logger.BeginScope(__scopeItems);

如果方法序言中已存在等效的命令属性 BeginScope 块，则跳过。

第 3 部分：Serilog appsettings 规则

通过 *.csproj 中包含 Serilog、Serilog.* 或 Sc.Infrastructure.Serilog 的包引用自动检测 Serilog。 如果任何 *.csproj 文件包含上述包名之一，则将仓库视为已启用 Serilog，并对仓库中的所有 appsettings.json 文件应用 Serilog 配置更新。

如果检测到 Serilog，请检查仓库中的所有 appsettings.json 文件。

对于每个带有对象 Args 的 Serilog File sink（包括嵌套的 WriteTo 管道，例如 Async -> Logger -> configureLogger -> WriteTo）：

• 确保 Args.path 以 .json 结尾
• 如果 Args.path 是调试日志文件路径（例如 *.debug），将其重命名为 .debug.json
• 将 Args.formatter 设置为：
  • Sc.Infrastructure.Serilog.CustomJsonFormatter, Sc.Infrastructure.Serilog
• 移除 Args.outputTemplate

不要修改非 File sinks。 如果不存在 Serilog 节或 File sink，则不执行任何操作。

输出

始终在仓库根目录生成：

• patch.diff 统一差异
• preview-report.json 条目：
  • file
  • line
  • original
  • transformed
  • risk_level
  • reason

应用时：

• 在 --backup-dir 或 .codex/skills/dev-structured-logs/backups 中创建备份
• 应用文件更新
• 如果提供了 --commit-msg，则尝试执行 git commit

示例

使用 examples/ 中的文件验证行为：

• concatenation.before.cs / concatenation.after.cs
• string-format.before.cs / string-format.after.cs
• interpolation.before.cs / interpolation.after.cs
• side-effect.before.cs / side-effect.after.cs
• handler-scope.before.cs / handler-scope.after.cs
• appsettings.before.json / appsettings.after.json