CLI开发工具【免费下载链接】gdownGoogle Drive public file downloader when curl/wget fails.项目地址https://gitcode.com/gh_mirrors/gd/gdown点击查看免费下载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 行围绕三件事展开Changelog用户可见变更必须写成 towncrier fragments写入changelog.d/严禁直接编辑CHANGELOG.mdAgent skills三个技能模块——Issue tracker、Issue/PR 标签、Domain docs分别指向 docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md 三份详细文档Domain docs 的组织原则仓库采用 single-context 结构即根目录只有一份CONTEXT.md加一个docs/adr/目录。这三块约定分别对应变更如何被记录问题如何被跟踪与裁决领域知识如何沉淀共同构成了 Agent 在该仓库协作的完整闭环。下面逐一展开。二、Changelog 管理towncrier fragments 工作流2.1 为什么必须用 fragmentAGENTS.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 之间永远不会产生编辑冲突。这是 towncrierPython 社区常用的 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.dfilename指向聚合目标CHANGELOG.mdignore [README.md]说明changelog.d/README.md本身不会被视为变更条目。issue_format会把 fragment 文件名中的 PR 号自动渲染为指向该 PR 的链接——这正是条目中不写 PR 链接约定的来源。2.2 fragment 命名规则每个 fragment 文件名必须符合PR number.type.md格式其中type是以下六种之一type含义added新增功能changed行为变更deprecated弃用removed移除fixed修复security安全修复这六种类型与 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 时建议major1.0.0存在 added/changed/deprecated/removed 类型 fragment 时建议major.(minor1).0否则建议major.minor.(patch1)。2.5 发布流程按 changelog.d/README.md 与 Makefile发布版本X.Y.Z的标准流程为执行make release VERSIONX.Y.Z提交更新后的 changelog 与已删除的 fragments然后给该提交打 tag推送 taggit 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 CLIAGENTS.md 声明 Issues 托管在 GitHub Issuesgithub.com/wkentaro/gdown所有操作统一通过ghCLI 完成详见 docs/agents/issue-tracker.md。该文档给出了一套完整的命令惯例操作命令创建 Issuegh issue create --title ... --body ...多行 body 建议用 heredoc读取 Issuegh issue view number --comments可用jq过滤评论并同时抓取 labels列出 Issuesgh issue list --state open --json number,title,body,labels,comments --jq [.[] \| {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]配合--label与--state过滤评论 Issuegh issue comment number --body ...打标签 / 去标签gh issue edit number --add-label .../--remove-label ...关闭 Issuegh issue close number --comment ...仓库信息repo通过git remote -v推断gh在克隆目录内运行时能自动识别。文档还对两条典型指令给出了语义约定publish to the issue tracker 即创建 GitHub Issuefetch 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 标签一个问题属于哪一类工作Type label含义type: bug报告需要修复的缺陷type: feature请求新能力或改进type: task维护、重构、文档或其他工作triage 标签问题的处理状态与责任人Triage label含义needs-triage需要维护者评估该问题needs-info等待报告者补充更多信息ready-for-agent已充分描述可供 AFK离线Agent 处理ready-for-human需要人类实现wontfix将不予处理规则要点没有 triage 标签的 Issue 属于待 Agent 路由的新工作needs-triage保留给只有维护者才能做出的决定。needs-info在 Issue 与 PR 之间共享语义。4.2 PR 裁决标签Agent verdictAgent 对每个 PR 必须记录恰好一个终态裁决terminal verdictAgent verdict含义recommend-merge已完成定稿推荐维护者评审并合并recommend-close推荐维护者评审后关闭recommend-triage技术上没问题但产品/范围必须由维护者决定另有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.mddocs/adr/中与将要工作的区域相关的 ADRArchitecture Decision Records。如果这些文件不存在静默继续不要标记缺失也不要主动建议创建。/grill-with-docs这类 producer skill 会在术语或决定真正被解决时才惰性创建它们。5.2 词汇表纪律当输出中命名领域概念时Issue 标题、重构提案、假设、测试名必须使用CONTEXT.md中定义的术语不得漂移到词汇表明确回避的同义词。gdown 的 CONTEXT.md 就是很好的范例——它用术语 定义 Avoid应避免的说法的格式约束了关键概念Drive filenameGoogle Drive 持有的文件真实名称携带真实扩展名单文件从Content-Disposition响应头读取文件夹内普通文件从嵌入的文件夹视图 HTML 读取Avoid: output name, basenameGoogle-native fileGoogle Docs/Sheets/Slides 条目下载即导出为选定格式写入的文件名总带 Drive 名称所缺的导出扩展名Avoid: document, extensionless fileListing--json输出即列出将下载什么的 JSON 数组每个条目为{url, path}不取输出目的地与-O/--output组合是硬错误Avoid: manifest, index, dumpCookies filegdown 打开会话时读取、解析每个 Google Drive 文件时重写的 Netscape 格式文件默认~/.cache/gdown/cookies.txtAvoid: 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()返回GoogleDriveFileToDownloadnamedtuple(id, path, local_path)而非裸字符串使探测模式在类型层面区别于正常返回的str | BinaryIO0002-vendor-ytdlp-cookie-extraction.md以符号级方式 vendor yt-dlp 的 cookie 提取代码Unlicense 公有领域而非引入 browser-cookie3 / yt-dlp 运行时依赖支持--cookies-from-browser0003-folder-listing-path-is-written-filename.md文件夹 Listing 的path承诺将写入的文件名Google-native 文件逐条探测导出文件名普通文件永不探测。从源码结构可以进一步印证这些决策例如 gdown/download.py 定义了GoogleDriveFileToDownloadnamedtuplegdown/download.py 在skip_downloadTrue时返回该对象且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 管理。开发者在setupuv 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默认--numprocessesauto并行通过。七、总结Agent 在该仓库工作的最小行动清单改用户可见行为先开 PR 拿到 PR 号再在 changelog.d/ 添加PR号.type.md单行条目有 breaking 变更加**Breaking:**前缀绝不直接改 CHANGELOG.md处理 Issue用 docs/agents/issue-tracker.md 中的gh命令操作注意一个type:标签 一个 triage 标签的纪律needs-triage只留给维护者裁决 PR记录恰好一个终态 verdict不自行 merge/close新提交使 verdict 失效后重新走评审探索代码库先读根目录 CONTEXT.md 与 docs/adr/ 相关记录输出时使用词汇表术语与 ADR 冲突时显式提出发布由维护者执行make release VERSIONX.Y.Z聚合 fragments、提交并打 tag、推送触发 PyPI 发布与 GitHub Release。AGENTS.md 的价值在于它把人的隐性协作规则显式化成了机器可读、可执行的约定文件让 AI Agent 在 gdown 仓库中的每一次变更、每一次 Issue 操作、每一次代码探索都有章可循——这也是现代开源仓库为 Agent 化协作铺路的标准范式。赞分享CLI开发工具【免费下载链接】gdownGoogle Drive public file downloader when curl/wget fails.项目地址https://gitcode.com/gh_mirrors/gd/gdown点击查看免费下载相关推荐Unkey 仓库 AGENTS.md 指南面向 Agent 与开发者的协作规范与开发工作流Unkey 仓库 AGENTS.md 指南面向 Agent 与开发者的协作规范与开发工作流 本篇指南以 Unkey 仓库根目录的 AGENTS.md http后端API网关认证鉴权ClickHouse 仓库的 AGENTS.md 全解读面向 AI Agent 的研发协作规范与工具链指南ClickHouse 仓库的 AGENTS.md 全解读面向 AI Agent 的研发协作规范与工具链指南 导读 AGENTS.md 是 ClickHouse数据库OLAP列式数据库大数据实时分析数据分析Sunshine 仓库工程协作规范全解面向 AI Agent 与贡献者的 AGENTS.md 实战指南Sunshine 仓库工程协作规范全解面向 AI Agent 与贡献者的 AGENTS.md 实战指南 AGENTS.md 是 Sunshine面向 Moo音视频后端上一篇WeChatMsg 微信聊天记录导出完整指南3 条命令把 HTML、Word、CSV 永久保存下来下一篇FasterTransformer T5 推理实战指南从模型架构、编译部署到翻译与摘要任务优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CLI开发工具【免费下载链接】gdownGoogle Drive public file downloader when curl/wget fails.项目地址https://gitcode.com/gh_mirrors/gd/gdown点击查看免费下载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 行围绕三件事展开Changelog用户可见变更必须写成 towncrier fragments写入changelog.d/严禁直接编辑CHANGELOG.mdAgent skills三个技能模块——Issue tracker、Issue/PR 标签、Domain docs分别指向 docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md 三份详细文档Domain docs 的组织原则仓库采用 single-context 结构即根目录只有一份CONTEXT.md加一个docs/adr/目录。这三块约定分别对应变更如何被记录问题如何被跟踪与裁决领域知识如何沉淀共同构成了 Agent 在该仓库协作的完整闭环。下面逐一展开。二、Changelog 管理towncrier fragments 工作流2.1 为什么必须用 fragmentAGENTS.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 之间永远不会产生编辑冲突。这是 towncrierPython 社区常用的 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.dfilename指向聚合目标CHANGELOG.mdignore [README.md]说明changelog.d/README.md本身不会被视为变更条目。issue_format会把 fragment 文件名中的 PR 号自动渲染为指向该 PR 的链接——这正是条目中不写 PR 链接约定的来源。2.2 fragment 命名规则每个 fragment 文件名必须符合PR number.type.md格式其中type是以下六种之一type含义added新增功能changed行为变更deprecated弃用removed移除fixed修复security安全修复这六种类型与 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 时建议major1.0.0存在 added/changed/deprecated/removed 类型 fragment 时建议major.(minor1).0否则建议major.minor.(patch1)。2.5 发布流程按 changelog.d/README.md 与 Makefile发布版本X.Y.Z的标准流程为执行make release VERSIONX.Y.Z提交更新后的 changelog 与已删除的 fragments然后给该提交打 tag推送 taggit 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 CLIAGENTS.md 声明 Issues 托管在 GitHub Issuesgithub.com/wkentaro/gdown所有操作统一通过ghCLI 完成详见 docs/agents/issue-tracker.md。该文档给出了一套完整的命令惯例操作命令创建 Issuegh issue create --title ... --body ...多行 body 建议用 heredoc读取 Issuegh issue view number --comments可用jq过滤评论并同时抓取 labels列出 Issuesgh issue list --state open --json number,title,body,labels,comments --jq [.[] \| {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]配合--label与--state过滤评论 Issuegh issue comment number --body ...打标签 / 去标签gh issue edit number --add-label .../--remove-label ...关闭 Issuegh issue close number --comment ...仓库信息repo通过git remote -v推断gh在克隆目录内运行时能自动识别。文档还对两条典型指令给出了语义约定publish to the issue tracker 即创建 GitHub Issuefetch 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 标签一个问题属于哪一类工作Type label含义type: bug报告需要修复的缺陷type: feature请求新能力或改进type: task维护、重构、文档或其他工作triage 标签问题的处理状态与责任人Triage label含义needs-triage需要维护者评估该问题needs-info等待报告者补充更多信息ready-for-agent已充分描述可供 AFK离线Agent 处理ready-for-human需要人类实现wontfix将不予处理规则要点没有 triage 标签的 Issue 属于待 Agent 路由的新工作needs-triage保留给只有维护者才能做出的决定。needs-info在 Issue 与 PR 之间共享语义。4.2 PR 裁决标签Agent verdictAgent 对每个 PR 必须记录恰好一个终态裁决terminal verdictAgent verdict含义recommend-merge已完成定稿推荐维护者评审并合并recommend-close推荐维护者评审后关闭recommend-triage技术上没问题但产品/范围必须由维护者决定另有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.mddocs/adr/中与将要工作的区域相关的 ADRArchitecture Decision Records。如果这些文件不存在静默继续不要标记缺失也不要主动建议创建。/grill-with-docs这类 producer skill 会在术语或决定真正被解决时才惰性创建它们。5.2 词汇表纪律当输出中命名领域概念时Issue 标题、重构提案、假设、测试名必须使用CONTEXT.md中定义的术语不得漂移到词汇表明确回避的同义词。gdown 的 CONTEXT.md 就是很好的范例——它用术语 定义 Avoid应避免的说法的格式约束了关键概念Drive filenameGoogle Drive 持有的文件真实名称携带真实扩展名单文件从Content-Disposition响应头读取文件夹内普通文件从嵌入的文件夹视图 HTML 读取Avoid: output name, basenameGoogle-native fileGoogle Docs/Sheets/Slides 条目下载即导出为选定格式写入的文件名总带 Drive 名称所缺的导出扩展名Avoid: document, extensionless fileListing--json输出即列出将下载什么的 JSON 数组每个条目为{url, path}不取输出目的地与-O/--output组合是硬错误Avoid: manifest, index, dumpCookies filegdown 打开会话时读取、解析每个 Google Drive 文件时重写的 Netscape 格式文件默认~/.cache/gdown/cookies.txtAvoid: 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()返回GoogleDriveFileToDownloadnamedtuple(id, path, local_path)而非裸字符串使探测模式在类型层面区别于正常返回的str | BinaryIO0002-vendor-ytdlp-cookie-extraction.md以符号级方式 vendor yt-dlp 的 cookie 提取代码Unlicense 公有领域而非引入 browser-cookie3 / yt-dlp 运行时依赖支持--cookies-from-browser0003-folder-listing-path-is-written-filename.md文件夹 Listing 的path承诺将写入的文件名Google-native 文件逐条探测导出文件名普通文件永不探测。从源码结构可以进一步印证这些决策例如 gdown/download.py 定义了GoogleDriveFileToDownloadnamedtuplegdown/download.py 在skip_downloadTrue时返回该对象且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 管理。开发者在setupuv 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默认--numprocessesauto并行通过。七、总结Agent 在该仓库工作的最小行动清单改用户可见行为先开 PR 拿到 PR 号再在 changelog.d/ 添加PR号.type.md单行条目有 breaking 变更加**Breaking:**前缀绝不直接改 CHANGELOG.md处理 Issue用 docs/agents/issue-tracker.md 中的gh命令操作注意一个type:标签 一个 triage 标签的纪律needs-triage只留给维护者裁决 PR记录恰好一个终态 verdict不自行 merge/close新提交使 verdict 失效后重新走评审探索代码库先读根目录 CONTEXT.md 与 docs/adr/ 相关记录输出时使用词汇表术语与 ADR 冲突时显式提出发布由维护者执行make release VERSIONX.Y.Z聚合 fragments、提交并打 tag、推送触发 PyPI 发布与 GitHub Release。AGENTS.md 的价值在于它把人的隐性协作规则显式化成了机器可读、可执行的约定文件让 AI Agent 在 gdown 仓库中的每一次变更、每一次 Issue 操作、每一次代码探索都有章可循——这也是现代开源仓库为 Agent 化协作铺路的标准范式。赞分享CLI开发工具【免费下载链接】gdownGoogle Drive public file downloader when curl/wget fails.项目地址https://gitcode.com/gh_mirrors/gd/gdown点击查看免费下载相关推荐Unkey 仓库 AGENTS.md 指南面向 Agent 与开发者的协作规范与开发工作流Unkey 仓库 AGENTS.md 指南面向 Agent 与开发者的协作规范与开发工作流 本篇指南以 Unkey 仓库根目录的 AGENTS.md http后端API网关认证鉴权ClickHouse 仓库的 AGENTS.md 全解读面向 AI Agent 的研发协作规范与工具链指南ClickHouse 仓库的 AGENTS.md 全解读面向 AI Agent 的研发协作规范与工具链指南 导读 AGENTS.md 是 ClickHouse数据库OLAP列式数据库大数据实时分析数据分析Sunshine 仓库工程协作规范全解面向 AI Agent 与贡献者的 AGENTS.md 实战指南Sunshine 仓库工程协作规范全解面向 AI Agent 与贡献者的 AGENTS.md 实战指南 AGENTS.md 是 Sunshine面向 Moo音视频后端上一篇WeChatMsg 微信聊天记录导出完整指南3 条命令把 HTML、Word、CSV 永久保存下来下一篇FasterTransformer T5 推理实战指南从模型架构、编译部署到翻译与摘要任务优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
