X-Financial/document/development/2026-06-25/feature/agent-change-log-split/CONCEPT.md

写日志技能拆分 概念文档

更新时间：2026-06-25

文档路径：document/development/2026-06-25/feature/agent-change-log-split/CONCEPT.md

功能一句话

把原来单文件三段式工作日志拆成按日期聚合的功能点文档、bug 修复日志和每日 17:00 综合工作日志。

背景与问题

• 当前现状：旧 agent-change-log 把所有变更追加到 document/work-log/YYYY-MM-DD.md，并固定包含 当日工作内容、遗留问题、TODO。
• 用户痛点：功能点规划、bug 修复和当天综合复盘混在一个日志文件里，后续追溯时难以按功能或问题拆开看。
• 业务影响：开发资料会越来越长，bug 修复证据和功能点设计边界容易互相干扰。
• 为什么现在需要做：write-development-docs 已经改为 document/development/YYYY-MM-DD/feature/<功能点>/，日志能力也需要跟随同一日期根目录拆分。

目标与非目标

目标

• [G1] bug 修复记录落到 document/development/YYYY-MM-DD/dev-logs/bugs/<bug-slug>.md。
• [G2] bug 日志只保留修复记录，不再写 遗留问题 和 TODO 两块。
• [G3] 每天 17:00 汇总当天 feature/ 和 dev-logs/bugs/，生成 work-logs.med。
• [G4] 保留 Git 双向检查，继续识别 upstream 新提交和本地 ahead 提交。

非目标

• [NG1] 本轮不迁移历史 document/work-log/*.md。
• [NG2] 本轮不删除旧历史日志，避免破坏既有追溯。
• [NG3] 本轮不把非 bug 提交强行写入 bug 日志。

用户与场景

• 目标用户：使用 Codex/Agent 维护 X-Financial 的开发者和后续接手的智能体。
• 使用入口：agent-change-log Skill、tools/agent-change-log/update_change_log.py、post-commit hook、每日 17:00 Codex automation。
• 核心场景：
  1. 修复 bug 后写入当天 dev-logs/bugs/<bug-slug>.md。
  2. 非 bug 功能点通过 feature/<功能点>/CONCEPT.md 和 TODO.md 沉淀。
  3. 每天 17:00 汇总功能点与 bug，生成 work-logs.med。
• 异常场景：
  • 没有 feature 或 bug 时，综合日志明确写“未发现”。
  • 提交标题不像 bug 时，post-commit 自动日志跳过。

功能能力

• [C1] 输入能力：支持 --kind bug、--kind auto、--kind summary 三种模式。
• [C2] 处理能力：按日期创建 dev-logs/bugs，按 bug slug 记录修复内容。
• [C3] 输出能力：输出 bug 修复记录或每日 work-logs.med。
• [C4] 状态与权限：沿用 Git fetch/status/log 检查，不主动 merge/rebase。
• [C5] 边界与降级：官方 skill 校验脚本不可用时，用脚本单测、frontmatter 和 diff check 兜底。

方案设计

前端

当前不涉及。

后端

当前不涉及业务后端；只修改仓库级 Skill、脚本和 hook。

算法与规则

• 输入：commit subject、用户传入的 bug title/slug、当天 feature 和 bug 文档。
• 流程：bug 模式写入 bug 文件；auto 模式识别 bug-like commit；summary 模式扫描 feature/ 和 dev-logs/bugs/ 后生成综合日志。
• 输出：dev-logs/bugs/*.md 或 work-logs.med。
• 解释：summary 中保留来源目录和综合分析，便于复盘追溯。

数据与契约

• 核心字段：日期、bug slug、bug title、Git 提交检查、修改、操作、验证、影响。
• 状态枚举：auto、bug、summary。
• 兼容策略：保留旧 document/work-log 历史，不新增旧格式。
• 版本/审计：本轮变更通过本地 checkpoint commit 保留。

算法与公式

当前功能不涉及显式数学公式。

测试方案

后端：

• 当前不涉及后端服务。

前端：

• 当前不涉及前端构建。

集成：

• 运行 python3 tools/agent-change-log/test_update_change_log.py，覆盖 bug 日志、非 bug 自动跳过、每日综合日志聚合。

手工验证：

• 运行 update_change_log.py --kind bug --dry-run 和 --kind summary --dry-run 检查目标路径和输出内容。

指标与验收

• [A1] 功能验收：bug 日志路径为 document/development/YYYY-MM-DD/dev-logs/bugs/<bug-slug>.md。
• [A2] 性能指标：脚本单测在 60s 内完成。
• [A3] 质量指标：不再为新日志写入旧三段式 document/work-log/YYYY-MM-DD.md。
• [A4] 安全/权限指标：脚本不做 merge/rebase，不删除历史日志。
• [A5] 可观测性：17:00 automation 生成 work-logs.med 后报告路径和是否发现 feature/bug。

风险与开放问题

• 风险：work-logs.med 是按用户原文保留的扩展名，可能与常见 .md 扩展名不一致。
• 已处理依赖：已创建 Codex automation 执行每日 17:00 summary。
• 待确认：后续是否需要迁移历史 document/work-log。
• 降级策略：automation 不可用时可手动运行 python3 tools/agent-change-log/update_change_log.py --kind summary。

本轮实现记录

• 2026-06-25：重写 agent-change-log Skill 和脚本，新增 split log 测试，创建每日 17:00 Codex automation。