Easydict 文档治理实践：统一 Agent 计划与变更历史文件的 YYYY-MM-DD 日期命名规范-港品优选

Easydict 文档治理实践：统一 Agent 计划与变更历史文件的 YYYY-MM-DD 日期命名规范

【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用，支持离线 OCR 识别，支持有道词典，🍎 苹果系统词典，🍎 苹果系统翻译，OpenAI，Gemini，DeepL，Google，Bing，腾讯，百度，阿里，小牛，彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict

导读

在 Easydict 仓库中，docs/exec-plans/（执行计划）与docs/histories/（变更历史）是记录 Agent 协作开发过程的两大文档体系。本文围绕 2026-08-23 的一次文档治理任务展开，系统讲解如何在两套文档目录中统一文件名日期格式为YYYY-MM-DD，包括 slug 命名规则、月份归档结构、模板约束与验证手段。读完本文，你将掌握一套可复制的「计划—历史」文档命名与归档规范，并能直接参照仓库模板落地到自己的项目中。

任务背景：为什么需要统一日期文件名

在 Agent 协作开发模式下，仓库中的执行计划和变更历史会随任务持续累积。如果文件名中的日期写法不统一——例如混用20260823与2026-08-23——会导致三个实际问题：

排序混乱：YYYYMMDD与YYYY-MM-DD在文件系统中的字典序表现不同，按文件名排序时月份归档目录内无法形成稳定的时间序列；
检索困难：目录日期、文件名日期和文档标题中的日期是三种写法时，人肉检索和脚本校验都需要同时维护多套规则；
引用断裂：计划与历史文档之间存在互相链接，重命名后若不同步更新路径引用，会出现失效链接。

因此，这次任务的用户请求非常明确：统一执行计划和变更历史文件名中的日期格式，使用YYYY-MM-DD。任务记录位于 docs/histories/2026-08/2026-08-23-agent-documentation-date-format.md，属于对仓库文档基础设施的一次规范化改造。

变更内容：三管齐下完成规范化

根据任务记录，本次变更包含三个层面，而不是简单改几个文件名：

统一重命名：将计划和历史任务文件统一命名为YYYY-MM-DD-<slug>.md；
规则写入文档：在计划、历史 README 和模板中明确文件名规则，让规则本身可被后续 Agent 和开发者遵循；
引用同步更新：更新重命名后残留的文档路径引用，避免docs/exec-plans/completed/与docs/histories/2026-08/内的旧链接失效。

可以看出，文档治理类任务同样遵循「改文件 → 改规则 → 改引用」的完整闭环，这与 docs/exec-plans/templates.md 中「记录重要选择及原因」「记录执行过的检查」的要求是一致的。

命名规则详解：`YYYY-MM-DD-<slug>.md`

规范的落点最终体现在docs/histories/README.md的「命名与 slug」一节，这是整个命名体系的核心依据：

记录与计划共用YYYY-MM-DD-<slug>.md文件名，同一任务共享 slug 并跨轮复用——这意味着一个任务从计划到落地，plan 与 history 的文件名前缀完全一致，便于配对检索；
<slug>使用小写 kebab-case（连字符分隔的小写单词）；
完整的标准标识可保留点号，例如release-0.1.1、upgrade-skills-v0.3.8这类带版本号的文件名是被允许的；
禁止使用的字符：空格、下划线、大写字母、斜杠、反斜杠或冒号。

规则原文见 docs/histories/README.md。上述规则在仓库文件列表中有大量实际样本可印证，例如：

docs/exec-plans/completed/2026-08/2026-08-23-release-easydict-skill.md docs/exec-plans/completed/2026-08/2026-08-23-release-issue-followup-skill.md docs/exec-plans/completed/2026-08/2026-08-29-review-pr-branch-selection.md

这些文件名全部满足YYYY-MM-DD-<slug>.md，slug 均为小写 kebab-case，无下划线与大写字母。

版本标识的写法约定

命名规则并非一成不变。在 2026-09-16 的后续任务 docs/histories/2026-09/2026-09-16-normalize-versioned-document-filenames.md 中，又进一步收紧了版本标识写法：将 10 个历史 plan/history 文件名中的v0.3.x、v2.9.1等版本标识统一为标准点分形式（如upgrade-tisfeng-skills-v0.6.1），并同步精简了<slug>命名规则。这说明该规范处于持续演进状态：日期格式先行统一，版本标识写法随后跟进，最终目标是「文件名与现行命名规则完全一致」。

目录结构与归档约定

命名规则服务于目录结构。Easydict 将计划与历史分置两套目录，各有独立的归档逻辑：

执行计划目录`docs/exec-plans/`

根据 docs/exec-plans/README.md，该目录保存「执行模式下的多步骤、跨模块或高风险任务计划」：

active/：进行中的计划；
completed/YYYY-MM/：按计划文件名月份归档的已完成计划；
templates.md：新计划模板。

归档约定：多步骤、跨模块或高风险的执行任务在active/下使用模板创建，完成后按文件名月份移动到completed/YYYY-MM/。也就是说，文件名中的日期同时决定了归档月份——这也是日期格式必须统一、可解析的原因。

一个特例是active/swift-migration.md（见 docs/exec-plans/active/swift-migration.md）：它是长期的 Objective-C 到 Swift 迁移路线图，属于「跨多月、长期演进」的文档，因此不适用按任务命名的规则，保持无日期文件名。README 明确要求：保持其中的已完成历史和剩余工作与当前源码同步；若某个迁移切片需要单独的里程碑或验证，则为其创建聚焦的计划。这体现了规则设计时「保留长期迁移路线图的无日期文件名」的边界意图。

变更历史目录`docs/histories/`

根据 docs/histories/README.md，该目录保存「执行模式下最终产生仓库文件差异的任务记录」：

YYYY-MM/：按完成月份归档的历史记录；
template.md：新记录模板。

归档约定：执行任务产生仓库差异时，在YYYY-MM/下使用模板记录结果；没有差异时不创建空记录——这是防止文档噪声的重要约束。

模板中的日期约束：让规则可执行

规则要长期生效，必须写进模板，让每个新建文档从出生起就符合规范。两个模板在文件头部都以注释形式嵌入了命名规则：

执行计划模板（docs/exec-plans/templates.md）

# <任务标题> <!-- 文件名：YYYY-MM-DD-<slug>.md；命名规则见 docs/histories/README.md 的“命名与 slug”。 --> <!-- 本模板只用于多步骤、跨模块或高风险的执行任务。 --> - 状态：active - 创建日期：YYYY-MM-DD - 负责人：<name> - 关联 Issue/PR：<link or none>

模板头部即注明文件名格式，并外链到命名规则原文，形成「模板 → 规则」的单一事实来源。模板还包含执行上下文（Agent Name / Model / Environment）、背景、目标与范围、工作计划、风险与决策、进度、验证、完成条件等必填区块，且要求「保留模板中的必填字段、章节和顺序」。

变更历史模板（docs/histories/template.md）

## YYYY-MM-DD | 任务：<简短动作> <!-- 文件名：YYYY-MM-DD-<slug>.md；命名规则见 docs/histories/README.md 的“命名与 slug”。 --> **Links:** <issue、PR、计划或 commit>

历史模板的标题行本身就是YYYY-MM-DD | 任务：<简短动作>格式，与文件名日期严格对应，实现了「目录日期、文件名日期和文档标题中的日期使用同一种可读格式」的设计意图。模板其余区块包括：执行上下文、用户请求、变更、设计意图、验证、受影响文件、后续事项。

设计意图：三处日期的一致性

任务记录中的「设计意图」一节点明了规范的最终目标：

让目录日期、文件名日期和文档标题中的日期使用同一种可读格式，同时保留docs/histories/YYYY-MM/月份归档结构和长期迁移路线图的无日期文件名。

即规范追求的是三处一致性（目录、文件名、标题），同时保留两个例外（月份归档目录的YYYY-MM粒度、长期路线图的无日期命名）。这种「统一中保留边界」的设计，比一刀切的全量重命名更贴近实际协作场景。

验证手段：如何确认规范落地

任务记录中的「验证」一节给出了四类检查，这也是文档治理任务可复用的验收清单：

文件名检查：全部任务文档均符合YYYY-MM-DD-<slug>.md——可用一条简单的 shell 通配或正则扫描实现；
旧文件名引用检查：未发现YYYYMMDD-*文件名引用——重点排查旧格式是否残留在文档正文、链接和脚本中；
git diff --check：通过——该命令用于检测补丁中的空白错误（行尾空白、冲突标记残留等）；
尾随空白检查：通过。

在后继任务 docs/histories/2026-09/2026-09-16-normalize-versioned-document-filenames.md 中，验证手段进一步升级为「全仓 210 个 Markdown 文件的相对链接检查」，说明这类命名规范化任务最终都会以全仓库范围的链接完整性检查收尾。

受影响文件清单与引用规范

本次任务的「受影响文件」清单如下，它同时展示了命名规则的作用范围：

docs/exec-plans/README.md
docs/exec-plans/templates.md
docs/histories/README.md
docs/histories/template.md
docs/exec-plans/completed/（重命名的已完成计划）
docs/histories/2026-08/（重命名的历史记录）

需要注意的一个细节是：规则文档之间的相互引用也采用了仓库内相对链接。例如 docs/exec-plans/README.md 中「文件命名与 slug 规则」指向../histories/README.md#命名与-slug（即从仓库根目录看为 docs/histories/README.md 的「命名与 slug」小节）。命名规则集中在 histories README 一处定义、exec-plans README 与两个模板分别引用，避免了规则的多处重复维护。

实践建议：在自己的仓库中落地这套规范

结合本次任务与仓库现状，可将这套方案提炼为可直接照搬的落地步骤：

先定规则再改名：在 README 中新增「命名与 slug」小节，明确YYYY-MM-DD-<slug>.md格式、kebab-case 约束、禁止字符与版本点号的例外写法，作为单一事实来源；
模板头部嵌入注释：在 plan 与 history 模板的首行注释中写入文件名格式，并外链到规则小节，让新文档天然合规；
批量重命名并同步引用：按YYYY-MM-DD-<slug>.md重命名现有文件，随后全文搜索旧格式（如YYYYMMDD-*）清理残留引用；
明确归档规则：计划完成后按文件名月份移入completed/YYYY-MM/，历史记录按完成月份归档到YYYY-MM/，无差异不创建空记录；
定义例外：长期路线图类文档（如swift-migration.md）保留无日期文件名，并在 README 中说明理由；
跑通验证链路：文件名格式检查 → 旧格式引用检查 →git diff --check→ 全仓相对链接检查，逐项通过后再归档。

这套规范的核心价值在于：把「文件名」当作文档系统的接口契约，让目录排序、任务配对（plan 与 history 共享 slug）、脚本校验和人工检索都建立在同一套可预测的规则之上。

总结

本次 Easydict 文档治理任务以一次小规模重命名为起点，最终沉淀为一套完整的文档命名治理方案：YYYY-MM-DD-<slug>.md统一文件名格式、kebab-case slug 约束、月份归档结构、模板头部规则注释，以及四层验证链路。它证明了在 Agent 协作开发中，文档治理同样需要「规则 → 模板 → 改名 → 校验」的工程化闭环，并且规则文档本身（docs/histories/README.md、docs/exec-plans/README.md）与模板（docs/histories/template.md、docs/exec-plans/templates.md）就是这套规范最好的说明书。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析