gdown 仓库 AGENTS.md 全解：面向 AI Agent 的变更管理与协作工作流指南

• CLI
• 开发工具

AGENTS.md 是 gdown 仓库为 AI Agent（以及人类协作者）定义的一套"工作方式约定"文件：它规定了用户可见变更必须以 towncrier fragment 的方式记录、Issue/PR 的标签体系与裁决规则、以及仓库领域文档的组织结构。本文以 AGENTS.md 为骨架，结合 changelog.d/README.md、docs/agents/ 三份技能文档以及仓库内的 Makefile、pyproject.toml、CONTEXT.md 等源码与配置证据，系统讲解这套约定如何工作、为何如此设计，以及作为 Agent 应当如何遵守，帮助你在该仓库中产出符合项目规范的变更、Issue 与代码贡献。

一、AGENTS.md 定位：一份给 Agent 看的"仓库工作手册"

gdown 仓库在根目录同时维护了AGENTS.md与CLAUDE.md（两者内容一致），它们不是面向终端用户的 README，而是写给"在仓库内工作的 AI Agent"的操作手册，全文仅 18 行，围绕三件事展开：

1. Changelog：用户可见变更必须写成 towncrier fragments，写入changelog.d/，严禁直接编辑CHANGELOG.md；
2. Agent skills：三个技能模块——Issue tracker、Issue/PR 标签、Domain docs，分别指向 docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md 三份详细文档；
3. Domain docs 的组织原则：仓库采用 single-context 结构，即根目录只有一份CONTEXT.md加一个docs/adr/目录。

这三块约定分别对应"变更如何被记录""问题如何被跟踪与裁决""领域知识如何沉淀"，共同构成了 Agent 在该仓库协作的完整闭环。下面逐一展开。

二、Changelog 管理：towncrier fragments 工作流

2.1 为什么必须用 fragment

AGENTS.md 第一条指令是："Record user-facing changes as towncrier fragments, followingchangelog.d/README.md; never editCHANGELOG.mddirectly."（记录用户可见变更时使用 towncrier fragments，遵循changelog.d/README.md；永远不要直接编辑CHANGELOG.md）。

changelog.d/README.md 给出了原因：每个用户可见的变更以独立文件的形式放在changelog.d/中，而不是直接编辑CHANGELOG.md，这样并发的 Pull Request 之间永远不会产生编辑冲突。这是 towncrier（Python 社区常用的 changelog 生成工具）的经典模式：变更条目作为"碎片"分散存放，发布时由工具自动聚合、排序、生成最终的 CHANGELOG。

仓库的 pyproject.toml 中可以看到完整的 towncrier 配置：

[tool.towncrier] directory = "changelog.d" filename = "CHANGELOG.md" title_format = "## {version} - {project_date}" issue_format = "[#{issue}](https://github.com/wkentaro/gdown/pull/{issue})" ignore = ["README.md"] type = [ { directory = "added", name = "Added", showcontent = true }, { directory = "changed", name = "Changed", showcontent = true }, { directory = "deprecated", name = "Deprecated", showcontent = true }, { directory = "removed", name = "Removed", showcontent = true }, { directory = "fixed", name = "Fixed", showcontent = true }, { directory = "security", name = "Security", showcontent = true }, ]

directory指向changelog.d，filename指向聚合目标CHANGELOG.md，ignore = ["README.md"]说明changelog.d/README.md本身不会被视为变更条目。issue_format会把 fragment 文件名中的 PR 号自动渲染为指向该 PR 的链接——这正是"条目中不写 PR 链接"约定的来源。

2.2 fragment 命名规则

每个 fragment 文件名必须符合<PR number>.<type>.md格式，其中<type>是以下六种之一：

这六种类型与 pyproject.toml 中[tool.towncrier]的type数组一一对应。若同一 PR、同一类型需要第二个 fragment，则追加计数器后缀：123.fixed.2.md。

关键时机：fragment 应在PR 打开之后、PR 号确定时才添加（"Add the fragment after opening the PR, when its number is known"）。

2.3 条目写法规范

• 每条内容写成单行，不加 bullet 符号，不写 PR 链接——PR 链接由 towncrier 依据文件名自动生成；
• 若变更会触发 major 版本升级，需以**Breaking:**前缀开头。

2.4 版本号策略

• 任何"已就绪的向后兼容改进"发minor版本；
• 向后兼容的修复发patch版本；
• 没有"最小发布规模"的限制，改动小也可以随时发版。

这个策略在 Makefile 的release目标中得到了机械化实现：make release（不带VERSION）会扫描changelog.d中的 fragments 并读取最近一个形如vX.Y.Z的 git tag，然后自动建议下一个版本号——存在**Breaking:**前缀的 fragment 时建议major+1.0.0，存在 added/changed/deprecated/removed 类型 fragment 时建议major.(minor+1).0，否则建议major.minor.(patch+1)。

2.5 发布流程

按 changelog.d/README.md 与 Makefile，发布版本X.Y.Z的标准流程为：

1. 执行make release VERSION=X.Y.Z；
2. 提交更新后的 changelog 与已删除的 fragments，然后给该提交打 tag；
3. 推送 tag（git push origin main vX.Y.Z）即发布到 PyPI，并从CHANGELOG.md对应章节生成 GitHub Release。

其中第 1 步在 Makefile 中的实现是：uv run towncrier build --yes --version $(VERSION)生成聚合后的 CHANGELOG，再用mdformat CHANGELOG.md格式化并git add，随后输出git commit -am "chore: prep $(VERSION) release"、git tag v$(VERSION)等后续提示。整个流程把"记录变更"与"发布版本"彻底解耦：日常开发只需丢 fragment，发布时一次性聚合。

三、Agent 技能之一：Issue tracker 工作流（gh CLI）

AGENTS.md 声明 Issues 托管在 GitHub Issues（github.com/wkentaro/gdown），所有操作统一通过ghCLI 完成，详见 docs/agents/issue-tracker.md。该文档给出了一套完整的命令惯例：

仓库信息（repo）通过git remote -v推断，gh在克隆目录内运行时能自动识别。文档还对两条典型指令给出了语义约定："publish to the issue tracker" 即创建 GitHub Issue；"fetch the relevant ticket" 即执行gh issue view <number> --comments。

四、Agent 技能之二：Issue 与 PR 标签体系

docs/agents/triage-labels.md 定义了完整的标签语义，是 Agent 路由 Issue、裁决 PR 的依据。

4.1 Issue 标签

每个完成 triage 的 Issue 必须携带恰好一个type:标签和一个triage 标签：

type 标签（一个问题属于哪一类工作）：

triage 标签（问题的处理状态与责任人）：

规则要点：没有 triage 标签的 Issue 属于"待 Agent 路由的新工作"；needs-triage保留给只有维护者才能做出的决定。needs-info在 Issue 与 PR 之间共享语义。

4.2 PR 裁决标签（Agent verdict）

Agent 对每个 PR 必须记录恰好一个终态裁决（terminal verdict）：

另有maintainer-approved标签，用于记录维护者"在必需检查通过后决定合并"这一显式决定：Agent只能在维护者明确指示时才打该标签，绝不能从 CI 状态、可合并性或 Agent 裁决中推断。它允许与一个 Agent verdict 共存，因为两者记录的是不同权威主体的决定。

4.3 裁决与合并的边界

关键纪律：verdict 只记录决定，不执行 merge/close。而且任何新的提交都会使所有适用的 verdict 失效——此时应移除旧 verdict，由同一权威主体评审新 diff 后再重新裁决。

五、Agent 技能之三：Domain docs 的 single-context 结构

docs/agents/domain.md 规定了 Agent 在探索代码库时应当如何消费仓库的领域文档。核心原则是：本仓库是 single-context——根目录只有一份CONTEXT.md加一个docs/adr/目录。

5.1 探索前必读

• 根目录的CONTEXT.md；
• docs/adr/中与将要工作的区域相关的 ADR（Architecture Decision Records）。

如果这些文件不存在，静默继续：不要标记缺失，也不要主动建议创建。/grill-with-docs这类 producer skill 会在术语或决定真正被解决时才惰性创建它们。

5.2 词汇表纪律

当输出中命名领域概念时（Issue 标题、重构提案、假设、测试名），必须使用CONTEXT.md中定义的术语，不得漂移到词汇表明确回避的同义词。gdown 的 CONTEXT.md 就是很好的范例——它用"术语 + 定义 + Avoid（应避免的说法）"的格式约束了关键概念：

• Drive filename（Google Drive 持有的文件真实名称，携带真实扩展名；单文件从Content-Disposition响应头读取，文件夹内普通文件从嵌入的文件夹视图 HTML 读取；Avoid: output name, basename）；
• Google-native file（Google Docs/Sheets/Slides 条目，下载即导出为选定格式，写入的文件名总带 Drive 名称所缺的导出扩展名；Avoid: document, extensionless file）；
• Listing（--json输出，即"列出将下载什么"的 JSON 数组，每个条目为{url, path}，不取输出目的地，与-O/--output组合是硬错误；Avoid: manifest, index, dump）；
• Cookies file（gdown 打开会话时读取、解析每个 Google Drive 文件时重写的 Netscape 格式文件，默认~/.cache/gdown/cookies.txt；Avoid: cookie jar）。

CONTEXT.md还提供了"示例对话"段落，用一问一答的形式澄清边界情况（例如单文件--json中path就是 Drive 文件名；无法解析出真实文件名时报错而不是输出坏名字）。

如果需要的概念尚不在词汇表中，这本身是个信号：要么你正在发明项目不使用的语言（应重新考虑），要么确实存在真实缺口（应记录给/grill-with-docs）。

5.3 ADR 冲突必须显式提出

如果输出与既有 ADR 矛盾，必须显式提出而不是静默覆盖，例如："Contradicts ADR-0007 — but worth reopening because…"。ADR 是既定决策，推翻它需要公开的论证。

5.4 仓库内的实际 ADR 样本

CONTEXT.md 中定义的词汇与 docs/adr/ 中三份已接受（Accepted）的决策记录相互印证，展示了"领域术语 ↔ 决策记录"如何互相锚定：

• 0001-single-file-json-returns-file-object.md：单文件--json模式下download()返回GoogleDriveFileToDownload（namedtuple(id, path, local_path)）而非裸字符串，使探测模式在类型层面区别于正常返回的str | BinaryIO；
• 0002-vendor-ytdlp-cookie-extraction.md：以符号级方式 vendor yt-dlp 的 cookie 提取代码（Unlicense 公有领域），而非引入 browser-cookie3 / yt-dlp 运行时依赖，支持--cookies-from-browser；
• 0003-folder-listing-path-is-written-filename.md：文件夹 Listing 的path承诺"将写入的文件名"，Google-native 文件逐条探测导出文件名，普通文件永不探测。

从源码结构可以进一步印证这些决策：例如 gdown/download.py 定义了GoogleDriveFileToDownloadnamedtuple，gdown/download.py 在skip_download=True时返回该对象且path与local_path同为解析出的 Drive 文件名；gdown/main.py 在--json与-O/--output同用时直接parser.error；而 gdown/main.py 将单文件结果包装为单元素列表，保证--json始终输出 JSON 数组。

六、约定落地的代码佐证与实战要点

6.1 towncrier 发布流程的自动化

Makefile 的vendor目标（uv run python scripts/vendor_ytdlp_cookies.py）与release目标共同展示了本仓库的工程化风格：一切可机械化的工作都写成 Makefile 目标 + uv 管理。开发者在setup（uv sync）之后，日常提交 PR 只需添加 fragment，其余交给make lint、make test、make release。

6.2 用户可见变更的典型实例

以 cookie 功能为例，--cookies-from-browser与--cookies属于典型的用户可见变更。它们在 gdown/main.py 中定义，在 gdown/download.py 中实现为"从浏览器复制 google.com 域 cookie 写入 cookies 文件、每次打开会话时读取"；对应的决策记录即 ADR-0002。当 Agent 为这类功能写 PR 时，就需要在changelog.d/中添加形如123.added.md的 fragment，条目内容按第二节规范编写。

6.3 与测试配套的验证习惯

仓库的 tests/ 目录（如 test_download.py、test___main__.py、test_download_folder.py、test_download_retries.py）覆盖了--json、skip_download、cookie、retries 等行为；pyproject.toml 中定义了networkmarker 用于标注需要真实网络（Google Drive、GitHub）的测试。Agent 在改动用户可见行为时，应同步补测试并保证make test（默认--numprocesses=auto并行）通过。

七、总结：Agent 在该仓库工作的最小行动清单

1. 改用户可见行为：先开 PR 拿到 PR 号，再在 changelog.d/ 添加<PR号>.<type>.md单行条目（有 breaking 变更加**Breaking:**前缀），绝不直接改 CHANGELOG.md；
2. 处理 Issue：用 docs/agents/issue-tracker.md 中的gh命令操作，注意一个type:标签 + 一个 triage 标签的纪律，needs-triage只留给维护者；
3. 裁决 PR：记录恰好一个终态 verdict，不自行 merge/close，新提交使 verdict 失效后重新走评审；
4. 探索代码库：先读根目录 CONTEXT.md 与 docs/adr/ 相关记录，输出时使用词汇表术语，与 ADR 冲突时显式提出；
5. 发布：由维护者执行make release VERSION=X.Y.Z聚合 fragments、提交并打 tag、推送触发 PyPI 发布与 GitHub Release。

AGENTS.md 的价值在于：它把"人的隐性协作规则"显式化成了机器可读、可执行的约定文件，让 AI Agent 在 gdown 仓库中的每一次变更、每一次 Issue 操作、每一次代码探索都有章可循——这也是现代开源仓库为 Agent 化协作铺路的标准范式。

• CLI
• 开发工具