dlt 的 AGENTS.md 模板init Toolkit 如何用「始终激活」规则为 AI Agent 协作定基线【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dltdltdata load tool的 AI 工作台AI Workbench在项目初始化时会在仓库根目录生成一份AGENTS.md用于给 Claude、Cursor、Codex 等 AI Agent 设定全局协作规则。本篇文章以仓库中tests/workspace/cli/dlthub/ai/cases/mock_workbench/init/AGENTS.md这份最小模板为切入点讲解它为何只有两行却举足轻重、它如何被dlt ai命令读取与合并、以及「始终激活always-apply」技能在 dlt 的 AI 工具链中究竟如何落地。读完你会掌握 AGENTS.md 模板的结构约定、它在工具包安装流程中的角色以及如何在 dlt 项目中自行维护这类规则文件。模板定位一份只有两行的「全局规则契约」在 dlt 的测试夹具中initToolkit 的 AGENTS.md 模板内容极其精简## ALWAYS ACTIVATE those skills they are essential for ANY work in this project对应源码见 tests/workspace/cli/dlthub/ai/cases/mock_workbench/init/AGENTS.md即本文引用的关联文档。在测试代码中这一模板被定义为常量MOCK_AGENTS_MD_TEMPLATE并在工作台复制时按需回填到init/AGENTS.md见 tests/workspace/cli/dlthub/ai/utils.pyMOCK_AGENTS_MD_TEMPLATE ( ## ALWAYS ACTIVATE those skills\nthey are essential for ANY work in this project\n ) def _ensure_init_agents_template(base: Path) - None: Create init/AGENTS.md template in workbench base if missing. init_dir base / init agents_md init_dir / AGENTS.md if not agents_md.exists(): init_dir.mkdir(parentsTrue, exist_okTrue) agents_md.write_text(MOCK_AGENTS_MD_TEMPLATE, encodingutf-8)虽然只有两行但它定义了整个 AI 工作台的关键约定AGENTS.md 中带## ALWAYS ACTIVATE those skills标题的段落就是「始终激活技能」清单的落点。后续任何 Toolkit如 rest-api-pipeline安装规则rules时都会把对应的 always-apply 技能条目合并进这份文件而不是新增散落的说明文件。模板在工具包安装流程中的作用从ai init到 AGENTS.md 生成dlt 的 AI 工作台通过dlt ai系列命令管理工具包toolkit。其中ai init负责把 init Toolkit 安装到当前项目具体实现见 dlt/_workspace/cli/dlthub/ai/commands.py函数ai_init_command的注释明确写着 Install the init toolkit into the current project.。init Toolkit 是唯一不允许单独安装的「基础工具包」在测试辅助代码 tests/workspace/cli/dlthub/ai/utils.py 中KNOWN_TOOLKITS包含data-exploration, init, rest-api-pipeline, dlthub-platform而INSTALLABLE_TOOLKITS显式排除了init。init Toolkit 安装完成后项目根目录会出现一份 AGENTS.md其内容即以 init 模板为骨架。模板读取read_agents_md_template当其他工具包携带 rules 被安装时dlt 需要读取 init 的 AGENTS.md 模板源码见 dlt/_workspace/cli/dlthub/ai/utils.py_INIT_TOOLKIT init def read_agents_md_template(workbench_base: Optional[Path]) - str: Read AGENTS.md template from init toolkit in workbench. Raises FileNotFoundError when workbench_base is None or the template file is missing. if workbench_base is None: raise FileNotFoundError(workbench_base is required for AGENTS.md template) tpl_path workbench_base / _INIT_TOOLKIT / AGENTS.md return tpl_path.read_text(encodingutf-8)这段代码揭示了两点约束模板文件必须位于工作台目录下的init/AGENTS.md路径约定为workbench_base/init/AGENTS.md若工作台目录未提供或模板缺失安装流程会直接抛出FileNotFoundError说明 AGENTS.md 模板是「始终激活技能」机制的前置条件。这也解释了为什么 mock_workbench 夹具在复制后还要通过_ensure_init_agents_template兜底重建模板——一旦模板缺失后续所有涉及 rules 合并的测试与真实安装都会失败。合并逻辑merge_agents_md_skills真正把技能条目写进项目 AGENTS.md 的是 dlt/_workspace/cli/formatters.py 中的merge_agents_md_skills。它的工作方式与两行模板的结构一一对应去重按顺序收集要添加的技能名跳过已在existing中出现过技能名的条目同时保留用户已有内容解析模板标题用MarkdownDocument找出模板中的第一个 Markdown 标题即## ALWAYS ACTIVATE those skills以及紧随其后的第一行正文即they are essential for ANY work in this project作为 subheading定位插入点在目标 AGENTS.md 中查找该标题若标题已存在则把新条目形如- skill-name插入到标题及 subheading 之后若标题不存在则把整个模板段落连同新条目一起追加到文件末尾保底校验若模板中没有任何 Markdown 标题则抛出ValueError(AGENTS.md template must contain a markdown heading)——这正是两行模板里##标题存在的原因。由此可见mock 模板中的 H2 标题不是装饰而是合并算法的「锚点」其下的引导句则是 subheading用于在标题已存在时确定条目插入的精确位置避免挤占用户自定义内容。rules 如何变成「始终激活」技能AGENTS.md 模板之所以强调 ALWAYS ACTIVATE those skills是因为 dlt 把工具包中的 rules 自动转换为始终激活always-apply的技能。转换发生在 dlt/_workspace/cli/dlthub/ai/agents.py 的_install_command_or_rule中# rule → always-apply skill (AGENTS.md is handled by finalize_actions) skill_name toolkit_name - source_name wrapped wrap_as_skill(content, skill_name, always_applyTrue)对应的wrap_as_skilldlt/_workspace/cli/dlthub/ai/utils.py会在 SKILL.md 的 frontmatter 里注入描述前缀if always_apply: desc ALWAYS read and follow this skill before acting. desc即每个由 rule 转换来的技能其 description 都以 ALWAYS read and follow this skill before acting. 开头——这与 AGENTS.md 模板中 they are essential for ANY work in this project 的表述互为呼应共同向 Agent 传递「执行任何任务前都必须先读并遵循这些技能」的指令。每个转换出的技能同时会以SKILL.md形式写入 Agent 对应的技能目录如.claude/skills/toolkit-rule/SKILL.md、.codex/skills/...随后由finalize_actions统一收尾见 dlt/_workspace/cli/dlthub/ai/agents.py。finalize_actions把规则合并回 AGENTS.md安装流程的最后一步finalize_actions负责把规则转换出的技能名合并进项目根目录的 AGENTS.mddef finalize_actions(self, actions, project_root, workbench_baseNone): Coalesce rule-converted-to-skill actions into a single AGENTS.md merge action. skill_names: List[str] [] for a in actions: if a.source_kind rule and not a.conflict: skill_names.append(a.dest_path.parent.name) if not skill_names: return actions agents_md self.agents_md_path(project_root) existing agents_md.read_text(encodingutf-8) if agents_md.is_file() else template read_agents_md_template(workbench_base) merged merge_agents_md_skills(existing, skill_names, templatetemplate) if merged ! existing: actions.append( InstallAction( kindrule, source_nameAGENTS.md, dest_pathagents_md, opsave, content_or_pathmerged, conflictFalse, skip_indexTrue, ) ) return actions要点只有source_kind rule且无冲突的技能才会进入合并清单合并后的内容与原文件有差异时才会追加一个对 AGENTS.md 的save动作该动作skip_indexTrue即 AGENTS.md 不会进入.toolkits索引的哈希校验区别于其余被跟踪文件索引校验逻辑见 tests/workspace/cli/dlthub/ai/utils.py由于合并是基于模板结构而非覆盖写入用户此前对 AGENTS.md 的定制内容会被完整保留。测试端对这套行为有专门覆盖finalize_actions产出单一 AGENTS.md 动作、技能已存在时跳过合并、以及按 Agent 类型Claude/Cursor/Codex选择正确配置文件等场景见 tests/workspace/cli/dlthub/ai/test_ai_agent.py 与 tests/workspace/cli/dlthub/ai/test_ai_command_helpers.py。AGENTS.md 模板的维护要点综合模板结构约定与源码实现在 dlt 项目中维护 AGENTS.md 模板时应注意要点约定源码依据文件位置workbench_base/init/AGENTS.mdinit Toolkit 专属read_agents_md_templateutils.py段落标题必须含 Markdown 标题如## ALWAYS ACTIVATE those skills否则合并抛ValueErrormerge_agents_md_skillsformatters.py引导句标题后紧跟一行说明如 they are essential for ANY work in this project用作 subheading 精确定位插入点merge_agents_md_skillsformatters.py技能条目以- skill-name列表形式挂在标题段落之下new_lines [-%s % name ...]formatters.py幂等性已列出的技能不会重复插入用户内容保留去重逻辑formatters.py小结init/AGENTS.md这份两行模板看似简单实则是 dlt AI 工作台「始终激活技能」机制的锚点它定义了 AGENTS.md 中规则合并的目标段落结构被read_agents_md_template读取、被merge_agents_md_skills作为插入模板、被finalize_actions用来收拢所有 rule 转换出的技能清单。无论是阅读 tests/workspace/cli/dlthub/ai/cases/mock_workbench/init/AGENTS.md 理解测试夹具还是在自己项目中定制 init Toolkit 的全局规则掌握「H2 标题 引导句 技能列表」这个三段式结构就能保证 dlt 的规则合并流程按预期工作并让 Claude、Cursor、Codex 在项目里始终遵守统一的行为基线。【免费下载链接】dltdata load tool (dlt) is an open source Python library that makes data loading easy ️项目地址: https://gitcode.com/GitHub_Trending/dl/dlt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考