# 写日志技能拆分 概念文档

更新时间：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。