AI实践 - 插件之开发日志篇

Development Log 插件使用说明

1. 插件简介

development-log 是一个面向 Codex 开发任务的项目级开发日志插件。它通过自然语言命令启用或关闭，在每轮任务开始时记录代码基线，并在任务结束前检查“代码是否发生变化、开发日志是否同步更新”。

它的核心目标不是生成泛泛的工作总结，而是依据用户目标、实际 Git Diff 和已经执行的验证，形成简洁、可追溯的中文开发记录。

当前插件版本：0.1.0+codex.20260730095946。

2. 适用场景

功能开发完成后留档

完成新页面、新接口、新交互或其他功能后，用结构化日志记录需求背景、采用方案、关键修改、涉及文件和验证结果，方便后续维护与交接。

Bug 修复与根因追踪

适合记录问题现象、根因、修复方案、影响范围及回归验证。以后遇到相似问题时，可以快速了解当时为什么这样修改。

重构与配置变更审计

重构通常不应改变外部行为，配置变更又可能影响环境、构建或部署。插件可以把修改依据、边界、验证情况和遗留风险集中记录下来。

多轮开发任务的持续总结

同一轮任务已有日志时，Skill 会优先更新同一篇文档，避免一次任务产生多篇零散记录。

团队交接与代码审查辅助

日志可以作为 Git Diff 之外的背景材料，补充“为什么改、影响什么、验证到了哪一层”，降低代码审查和任务交接成本。

3. 不太适合的场景

• 当前目录不是 Git 仓库。
• 只进行讨论、调研或方案设计，没有代码或配置修改。
• 需要逐分钟工时记录、个人日记或完整操作流水账。
• 希望用构建成功代替真实环境验证。插件会明确区分不同验证层级，不支持这种等同表述。

4. 快速使用

4.1 开启开发日志

在 Git 项目根目录或其子目录中对 Codex 说：

开启开发日志

插件会在项目中创建或更新 .codex/devlog.json。默认配置类似：

{
  "schemaVersion": 1,
  "enabled": true,
  "outputDirectory": "docs/development-log",
  "summaryMode": "per-task"
}

默认日志目录为 docs/development-log。

4.2 查看状态

查看开发日志状态

插件会返回当前项目是否已开启，以及实际使用的输出目录。

4.3 关闭开发日志

关闭开发日志

关闭后会保留历史日志和 .codex/devlog.json，只把 enabled 改为 false。

4.4 手动补写日志

可以直接说：

为当前开发任务补写开发日志

也可以显式调用 Skill：

$development-log:write-development-log

5. 工作机制

1. 用户提交开发任务时，插件检查当前目录是否属于 Git 仓库，并读取 .codex/devlog.json。
2. 如果开发日志已开启，插件记录本轮开始前的代码快照和日志目录快照。
3. Codex 准备结束任务时，插件重新计算快照。
4. 如果代码没有变化，或日志已经同步变化，则正常结束。
5. 如果代码发生变化但日志没有更新，插件会要求 Codex 调用 write-development-log Skill 完成收尾。
6. 为避免异常情况下无限循环，自动收尾只阻止结束一次；第二次仍未写入时会放行并给出提醒。

快照覆盖未暂存修改、已暂存修改和未跟踪文件。插件只保存 SHA-256 摘要，不把完整 Diff 写入内部状态文件；配置文件和日志目录本身也会从业务代码快照中排除。

6. 日志文件格式

默认文件路径：

docs/development-log/YYYY-MM/YYYYMMDD-HHmmss-任务短名称.md

文档结构如下：

---
type: feature | bugfix | refactor | config | other
status: completed | partial
created_at: YYYY-MM-DD HH:mm:ss
---

# 任务标题

## 需求背景

## 问题或根因

## 采用方案

## 关键修改

## 涉及文件

## 验证结果

## 风险与待办

没有适用内容的章节可以写“无”或省略，但不能虚构信息。

7. 使用技巧

先开启，再开始开发

插件需要在任务开始时记录基线。建议先单独执行“开启开发日志”，下一轮再提出开发需求，这样本轮修改范围更清晰。

一轮只聚焦一个明确任务

尽量让一轮开发对应一个具体目标，例如“修复登录按钮重复提交”，不要同时混入多个无关需求。这样日志标题、Diff 归属和风险说明更准确。

明确告诉 Codex 验证到了哪一层

可以在任务要求中直接说明：

修改后运行单元测试和构建，并把未进行的真实环境验证明确写入开发日志。

插件要求分别记录静态检查、单元测试、构建、手工验证和真实环境验证。未运行的项目必须写“未运行”。

使用 partial 表达真实完成度

如果测试失败、功能只完成一部分，或关键验证未通过，应把日志状态写为 partial，并在“风险与待办”中说明剩余工作。

自定义输出目录

可以修改项目中的 .codex/devlog.json：

{
  "schemaVersion": 1,
  "enabled": true,
  "outputDirectory": "docs/engineering/devlog",
  "summaryMode": "per-task"
}

outputDirectory 应使用项目相对路径。插件会将 Windows 反斜杠规范化为正斜杠，便于 Git 路径匹配。

提交前把日志和代码一起审阅

建议检查：

• 日志描述是否与实际 Diff 一致。
• 是否把计划中的修改误写成已经完成。
• 是否错误认领了原本就存在的未提交改动。
• 测试、构建和真实环境验证是否被准确区分。
• 风险和待办是否与 status 一致。

讨论命令时避免使用完整控制句

插件只对完整的控制句进行精确匹配，以避免“如何开启开发日志”之类的讨论误改配置。真正执行控制操作时，优先使用简短命令：“开启开发日志”“关闭开发日志”“查看开发日志状态”。

8. 插件特点

项目级持久开关

启用状态保存在仓库的 .codex/devlog.json 中，而不是仅对当前聊天生效。项目重新打开后仍可沿用配置。

基于实际 Git 变化

日志生成依据包括用户目标、git status --short、实际 Git Diff 和已执行验证，能够减少“总结内容与代码不一致”的问题。

自动检查遗漏

插件使用 UserPromptSubmit 和 Stop 两类生命周期 Hook：前者记录任务基线，后者在结束前检查代码与日志是否同步变化。

覆盖多种工作区状态

快照同时考虑未暂存 Diff、已暂存 Diff 以及未跟踪文件，新增文件不会因为尚未执行 git add 而被漏掉。

防止日志触发日志

插件将 .codex/devlog.json 和配置的日志输出目录排除在业务代码快照之外，因此单纯更新日志不会再次触发新的总结循环。

注重证据边界

插件明确要求：构建成功不等于功能已在真实环境验证；没有执行的验证要标记为“未运行”；失败或部分完成时状态应为 partial。

保护用户现有改动

无法确认归属的变化不能宣称为本轮成果。Skill 还要求保留用户已有的未提交修改，并且不会自动提交、推送或修改未授权文件。

低上下文开销

未启用开发日志的项目只进行快速配置检查。只有检测到代码变化但缺少日志时，才会要求加载详细的日志生成 Skill。

失败时优先不中断开发

非 Git 目录会跳过普通检查；配置损坏、基线损坏或 Hook 异常时，插件通常允许任务结束并给出诊断提示，避免日志功能阻塞正常开发。

9. 注意事项与边界

• 必须在 Git 仓库中使用，非 Git 目录无法启用项目级开发日志。
• 需要本机可以运行 node 和 git。
• .codex/devlog.json 损坏或 JSON 格式无效时，会被视为未启用。
• 如果任务开始时没有成功保存基线，结束时会跳过自动总结，以免把旧修改错误归入本轮。
• 自动检测只判断代码与日志是否发生变化；日志内容是否准确仍需由 Skill 根据真实 Diff 和验证证据生成并检查。
• 插件不会自动执行 Git 提交或推送。
• 插件不会删除历史日志；关闭功能时仍保留配置和已有记录。

10. 推荐提示词

功能开发

实现用户列表筛选功能。完成后运行现有静态检查和单元测试，并使用 $development-log:write-development-log 根据实际 Diff 补写开发日志；未进行的真实环境验证要明确标注。

Bug 修复

修复表单重复提交问题。请先确认根因，只修改相关代码；完成后记录修复方案、影响范围、回归验证和仍存在的风险。

重构

重构订单状态转换逻辑，保持外部行为不变。完成后在开发日志中说明重构动机、兼容性边界和验证结果。

手动补写

使用 $development-log:write-development-log，根据本轮用户目标、实际 Git Diff 和已经执行的验证，为当前任务补写一篇结构化开发日志。不要把未验证内容写成已完成。

11. 一句话总结

development-log 的价值在于：让每次真实代码变更都留下“为什么改、改了什么、验证到哪里、还有什么风险”的项目内记录，同时避免把计划、猜测或构建结果包装成已经验证的事实。