Easydict 文档治理实践统一 Agent 计划与变更历史文件的 YYYY-MM-DD 日期命名规范【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。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.mdslug 均为小写 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/PRlink 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.mddocs/exec-plans/templates.mddocs/histories/README.mddocs/histories/template.mddocs/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就是这套规范最好的说明书。【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考