Copilot Instructions for ONNX Runtime
【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime
Read and follow AGENTS.md for repository-wide guidance, including codebase conventions, architecture, and coding standards.
这正是文档所要求的：**保持 `.github/copilot-instructions.md` 最小化**，它只负责把 GitHub Copilot 路由到 AGENTS.md 中的权威指导，而**不**承载其他 Agent 无法发现的内容。原因很直接：AGENTS.md 是通用规范（如 [AGENTS.md](https://link.gitcode.com/i/d1958ad6531d2f4b295531cb7c21190f) 中 AGENTS 协议约定），而 copilot-instructions.md 是 Copilot 专属入口；若把知识写进专属文件，本地 Agent 就无法发现，等于制造了第二份会漂移的知识副本。 ## 三、添加路径级指令：`.github/instructions/` 的完整写法 路径级指令是这套体系中最精细的一层，用于把「某子系统的不变量（invariant）」绑定到具体文件路径上。 ### 3.1 YAML frontmatter 结构 创建文件时需放在 `.github/instructions/` 下，文件名要有描述性，以 `*.instructions.md` 结尾。文件头必须包含 YAML frontmatter，提供有意义的 `description` 与 `applyTo` 字符串，多个路径模式用**逗号分隔**。文档给出的标准模板： ```markdown --- description: "Guidance for Example subsystem changes." applyTo: "onnxruntime/core/example/**/*.cc,onnxruntime/core/example/**/*.h" --- # Example Subsystem State the invariant, why it matters when that is not obvious, and what a correct change must update.3.2 仓库中的真实范例：C API 指令
仓库里已有现成的最佳实践样本 —— .github/instructions/c-api.instructions.md。其 frontmatter 如下：
--- description: "C API implementation and review guidance for public C API updates." applyTo: "include/onnxruntime/core/session/onnxruntime_c_api.h,include/onnxruntime/core/session/onnxruntime_ep_c_api.h" ---注意它没有使用宽泛的applyTo: "**"，而是精确限定到两个公开 C API 头文件，正符合文档「使用能可靠识别相关改动的最窄路径」的要求。其正文沉淀了几条高价值不变量：
- ABI 兼容性：不得删除、重排或修改已发布 C API 结构体中的函数指针签名；新增函数必须追加到
OrtApi、OrtModelEditorApi、OrtCompileApi、OrtInteropApi（见 include/onnxruntime/core/session/onnxruntime_c_api.h）以及OrtEpApi（见 include/onnxruntime/core/session/onnxruntime_ep_c_api.h）的末尾，并同步更新对应 initializer 表； - Doxygen 文档：每个新 C API 成员必须完整注释行为、参数、返回值与所有权/生命周期要求，并带
\since Version X.Y.标签； - 版本号纪律：新增 API 时不要擅自 bump
ORT_API_VERSION，那是发布准备阶段的工作（详见 docs/Versioning.md）； - C++ 包装层：按需为每个新 C API 添加 C++ 包装，声明在 include/onnxruntime/core/session/onnxruntime_cxx_api.h，实现在 include/onnxruntime/core/session/onnxruntime_cxx_inline.h。
这个例子完整演示了文档强调的「可操作的（actionable）不变量」：每条都指向一个具体失败模式（ABI 破坏、文档缺失、版本号误改）和要求的修正动作，而不是泛泛的「请小心」。
四、作用域（applyTo）选型与匹配语义
文档对applyTo给出三条明确规则：
- 使用最窄路径：
applyTo: "**"应被避免——仓库级指导属于 AGENTS.md，路径级指令只负责特定路径； - 实现与评审双向生效：除非正文明确限定，否则匹配的指令同时适用于实现（implementation）与评审（review）。这从 .github/skills/code-review/SKILL.md 中得到印证：评审流程第一步就是「读取每个
applyTo作用域覆盖到变更路径的.github/instructions/**/*.instructions.md文件」； - 模式匹配语法：多个模式用逗号分隔，支持 glob（如
onnxruntime/core/example/**/*.cc）。
从代码结构看，applyTo的 glob 语义与仓库中的路径约定保持一致：C++ 源文件按子系统组织在onnxruntime/core/{graph,optimizer,framework,session,providers}下，因此路径级指令通常精确到具体子系统目录，甚至具体文件。
五、Agent Skills：深层工作流与知识的容器
当知识不再只是「一条不变量」，而是一整套可重复执行的流程（如升级依赖、跑测试、排查 CI）时，应沉淀为 Skill，放在 .github/skills/ 下，每个 Skill 一个目录，内含SKILL.md。
仓库现有多达十余个 Skill，覆盖典型维护场景：
| Skill | 解决的问题 |
|---|---|
| .github/skills/code-review/SKILL.md | 评审 PR/分支/补丁的三步工作流：确立评审范围 → 分析变更行为 → 输出可执行 findings |
| .github/skills/ort-test/SKILL.md | C++（gtest）与 Python（unittest/pytest）测试的定位与运行，并给出「假绿（false-green）」五类陷阱 |
| .github/skills/ort-lint/SKILL.md | 用 lintrunner 完成 C++（clang-format）与 Python（ruff）的格式化与静态检查 |
| .github/skills/ort-ci/SKILL.md | 触发/重跑/解堵 GitHub Actions 与 Azure Pipelines 检查，含故障分类表 |
| .github/skills/onnx-opset-bump-checklist/SKILL.md | ONNX 依赖/opset 升级的完整可重复流程（文件分类、哈希校验、patch 重基、验证关卡） |
5.1 Skill 的 YAML frontmatter
Skill 同样使用 YAML frontmatter，字段为name与description（注意与路径级指令的description+applyTo不同）。以 .github/skills/code-review/SKILL.md 为例：
--- name: code-review description: "Review ONNX Runtime pull requests, branches, commits, patches, and working-tree changes for actionable findings and missing tests." ---【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
