117 lines
4.9 KiB
Markdown
117 lines
4.9 KiB
Markdown
# 写日志技能拆分 概念文档
|
||
|
||
更新时间：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。
|