Dagger TypeScript SDK EnvChecksOpts 类型别名详解用 include 模式筛选 Env 检查【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger本篇技术指南围绕 Dagger自动化引擎用于构建、测试与交付任意代码库TypeScript SDK API 参考中的EnvChecksOpts类型别名展开讲解其定义、属性语义、在Env.checks()调用链中的作用以及include模式在模块检查Check发现与筛选流程中的底层实现。读完本文你将掌握如何在 Dagger 模块或客户端中按 glob 模式精准筛选环境中已安装模块所定义的检查并能理解dagger check系列命令与 GraphQL API 在筛选语义上的一致性。一、EnvChecksOpts 是什么EnvChecksOpts是 Dagger TypeScript SDK 中Env类方法checks()的可选参数类型别名定义于版本化 API 参考文档 type-aliases/EnvChecksOpts.md归属dagger.io/dagger包模块api/client.gen。其完整定义为type EnvChecksOpts { /** * Only include checks matching the specified patterns */ include?: string[]; };这是一个对象类型别名目前仅包含一个可选属性属性类型必填说明includestring[]可选只包含与指定模式匹配的检查从语义上看include是一个过滤白名单不传时返回环境内已安装模块定义的全部检查传入一个或多个模式字符串时只有名称/路径与这些模式匹配的检查才会被返回。模式基于 glob 通配语义如passing-*、**:unit具体匹配规则在本文第三节结合源码展开。二、使用位置Env.checks() 与 CheckGroupEnvChecksOpts是Env类方法checks()的入参类型。在 classes/Env.md 中该方法的签名与说明如下check()与checks()均标注为Experimental返回具有给定名称的检查必须精确匹配一个检查check(name)返回由已安装模块定义的所有检查checks(opts?)。// Env.checks() 的签名来自 version-0.19 API 参考 checks(opts?: EnvChecksOpts): CheckGroup;调用后返回CheckGroup对象它封装了一组检查及检查运行结果详见下文源码分析。在 TypeScript 模块中一个典型的使用片段形如import { dag } from dagger.io/dagger; // 获取环境中已安装模块定义的全部检查 const allChecks dag.env().checks(); // 仅筛选出名称匹配 passing-* 的检查 const passingOnly dag.env().checks({ include: [passing-*] });需要强调的是Env是一个面向 LLM/Agent 环境environment的抽象checks()返回的是由安装到该环境中的模块所定义的检查而不是某个模块内部直接调用的结果。这与dagger checkCLI 命令的发现并运行模块检查函数的定位一致——集成测试 core/integration/checks_test.go 的注释明确说明这些测试覆盖dagger checkwhich discovers and runs module check functions。三、include 模式的底层实现从 GraphQL 参数到 ModTree 过滤EnvChecksOpts.include最终会作为 GraphQL 查询参数include传给引擎。在当前仓库的 SDK 运行时生成代码 sdk/typescript/runtime/internal/dagger/dagger.gen.go 中可以看到 Go 侧的EnvChecksOpts结构与Env.Checks的完整实现// EnvChecksOpts contains options for Env.Checks type EnvChecksOpts struct { // Only include checks matching the specified patterns Include []string // When true, only return annotated check functions; exclude generate-as-checks NoGenerate bool } // Return all checks defined by the installed modules // // Experimental: Checks API is highly experimental and may be removed or replaced entirely. func (r *Env) Checks(opts ...EnvChecksOpts) *CheckGroup { q : r.query.Select(checks) for i : len(opts) - 1; i 0; i-- { // include optional argument if !querybuilder.IsZeroValue(opts[i].Include) { q q.Arg(include, opts[i].Include) } // noGenerate optional argument if !querybuilder.IsZeroValue(opts[i].NoGenerate) { q q.Arg(noGenerate, opts[i].NoGenerate) } } return CheckGroup{query: q} }从源码结构可以看到两点include是可选 GraphQL 参数仅当Include非零值时才会通过q.Arg(include, ...)附加到查询中未设置时引擎端按不过滤处理返回全部检查。API 存在演进version-0.19 的类型文档只收录了include属性而当前仓库生成代码中的EnvChecksOpts还包含NoGenerate bool字段对应 GraphQL 参数noGenerate用于排除由 generate 函数衍生的检查。这属于不同版本间的差异以你实际使用的 SDK 版本为准。引擎端Go 核心实现的过滤逻辑位于 core/checks.go 的NewCheckGroupfunc NewCheckGroup(ctx context.Context, mod dagql.ObjectResult[*Module], include []string, noGenerate, onlyGenerate bool) (*CheckGroup, error) { rootNode, err : NewModTree(ctx, mod) ... var checks []*Check if !onlyGenerate { checkNodes, err : rootNode.RollupChecks(ctx, include, nil) ... } if !noGenerate { genNodes, err : rootNode.RollupGenerator(ctx, include, nil) ... } ... }即引擎把已安装模块构建为一棵模块树ModTree然后分别用include对注解检查节点RollupChecks与生成器节点RollupGenerator做遍历过滤。两者的过滤函数定义在 core/modtree.go// Walk the tree and return all check nodes, with include and exclude filters applied. func (node *ModTreeNode) RollupChecks(ctx context.Context, include []string, exclude []string) ([]*ModTreeNode, error) { return node.RollupNodes(ctx, func(n *ModTreeNode) bool { return n.IsCheck }, include, exclude) }RollupNodes对树的叶子节点执行匹配include非空时节点路径必须与至少一个模式匹配n.Match(ctx, include)exclude非空时命中任意排除模式的节点被跳过。收集结果按路径字符串排序并去重避免同一函数出现在多个子树时重复。这解释了include的或语义——数组中的多个模式是并集关系命中任意一个即被包含。四、模式匹配语义从集成测试反推规则include使用的模式匹配与dagger checkCLI 的检查筛选共用同一套机制。仓库集成测试 core/integration/checks_test.go 覆盖了多种模式的真实行为可据此归纳模式规则以下均来自测试断言1. 通配符后缀匹配dagger check passing-*同时匹配passing-check与passing-container两个检查TestChecksDirectSDK--skip failing-*则排除failing-check与failing-container。说明*匹配任意字符串。2. 冒号路径namespace匹配模块内的检查可以形成命名空间路径例如test:lint、test:unit。测试使用--skip **:unit精确排除了test:unit而保留test:lint说明**可匹配任意层级的模块/对象前缀。3. 前缀匹配--skip test同时排除了test:lint与test:unitTestChecksSkipFlag的 list with prefix skip pattern 子测试说明不带通配符的字符串按路径前缀语义匹配。4. 无匹配时的报错dagger check missing-check输出no checks matched pattern missing-checkTestChecksNoMatch因此传入include时请确保模式至少能命中一个检查否则运行阶段会报错。5. include 与 skip 可叠加测试中dagger check -l test --skip **:unit的结果只含test:lint即先按 include 白名单收缩再按 skip 黑名单排除。这些行为同时适用于 CLI 与 API 场景CLI 的check [patterns]位置参数等价于include--skip等价于排除过滤器而EnvChecksOpts.include正是该机制的 API 形态。五、实战在 TypeScript 模块中定义检查并用 include 筛选要真正让EnvChecksOpts发挥作用需要环境中存在已安装模块所定义的检查。仓库提供了完整的 TypeScript 示例模块 core/integration/testdata/checks/hello-with-checks-ts/src/index.ts展示了用check()装饰器声明检查函数的方式import { Container, dag, object, func, check } from dagger.io/dagger; object() class HelloWithChecksTs { func() baseImage: string; constructor(baseImage: string alpine:3) { this.baseImage baseImage; } // 返回一个通过的检查容器命令退出码为 0 func() check() async passingCheck(): Promisevoid { await dag .container() .from(this.baseImage) .withExec([sh, -c, exit 0]) .sync(); } // 返回一个失败的检查容器命令退出码为 1 func() check() async failingCheck(): Promisevoid { await dag .container() .from(this.baseImage) .withExec([sh, -c, exit 1]) .sync(); } // 返回 Container 的检查引擎会运行该容器并以退出码判定成败 func() check() passingContainer(): Container { return dag .container() .from(this.baseImage) .withExec([sh, -c, exit 0]); } func() check() failingContainer(): Container { return dag .container() .from(this.baseImage) .withExec([sh, -c, exit 1]); } func() test(): Test { return new Test(); } } object() class Test { func() check() async lint(): Promisevoid { await dag.container().from(alpine).withExec([sh, -c, exit 0]).sync(); } func() check() async unit(): Promisevoid { await dag.container().from(alpine).withExec([sh, -c, exit 0]).sync(); } }该模块共声明 6 个检查路径分别为passing-check、failing-check、passing-container、failing-container、test:lint、test:unit集成测试正是用这些名字断言 CLI 输出。注意两个要点check()必须与func()组合使用其函数体返回Promisevoid命令成功即通过或Container引擎运行该容器以退出码判定。对象嵌套形成命名空间路径Test对象下的检查在筛选时表现为test:lint、test:unit形式这是**:unit这类模式存在的原因。在该模块被安装到 Env例如通过Env.withCurrentModule()或 workspace 模块安装后客户端即可用EnvChecksOpts筛选import { dag } from dagger.io/dagger; // 全部检查 const all dag.env().checks(); // 只看失败系failing-check、failing-container const failingOnly dag.env().checks({ include: [failing-*] }); // 只看 test 命名空间下的检查test:lint、test:unit const testChecks dag.env().checks({ include: [test:*] }); // 跨命名空间匹配任意层级下名为 unit 的检查 const unitChecks dag.env().checks({ include: [**:unit] });六、检查结果的落地CheckGroup 与运行语义checks()返回的CheckGroup并非立即执行检查而是先列出匹配的检查集合。真正运行由CheckGroup上的方法完成其 Go 侧实现位于 core/checks.goCheckGroup.Run(ctx, failFast)并行运行组内所有检查parallel.New()支持failFast短路每个检查重置Completed/Passed状态后执行node.RunCheck或对生成器节点执行RunGeneratorAsCheck失败时生成Error对象写入check.Error。引擎还会把 BoundWorkspace 注入 context确保 overlay 编辑对检查可见WorkspaceToContext。CheckGroup.Report(ctx)生成一张 Markdown 表格报告列为check / type / description / success行内容来自每个检查的名称、类型check或generate、描述与结果 emoji 通过 / 失败并以File对象checks.md形式返回。Check结构每个检查包含Node模块树节点、Completed、Passed与失败时的ErrorIsGenerate标记该检查是否由generate函数派生此时通过条件为生成器产生空 changeset。因此结合include筛选与CheckGroup的运行能力即可在客户端完成只运行特定模式检查的流水线。集成测试 core/integration/checks_test.go 中的TestChecksGenerateAsCheck还展示了--no-generate/--generate与注解检查之间的互斥与组合行为同时传入会报错if any flags in the group [no-generate generate] are set none of the others can be这在 API 侧对应EnvChecksOpts.NoGenerate字段。七、注意事项实验性 APIEnv上的check()/checks()均标注为ExperimentalGo 生成代码的注释为 Checks API is highly experimental and may be removed or replaced entirelyAPI 形态在后续版本中可能调整生产使用前请确认目标 SDK 版本。版本差异version-0.19 的类型文档仅收录include属性当前仓库源码中的EnvChecksOpts另有NoGenerate字段。文章中的源码示例对应仓库当前 HEAD文档示例对应 0.19 版本请按需对照。模式需谨慎include是白名单语义命中任一模式即包含空数组/未设置等价于不筛选若模式未命中任何检查运行阶段会报no checks matched pattern ...错误。来源限定Env.checks()返回的检查来自已安装到该环境中的模块含 workspace 安装的模块而非全局所有模块配置层面还可在 workspace 的dagger.toml中通过[modules.name] check.skip [...]与check-generated预设默认筛选参见 core/integration/checks_test.go 的TestWorkspaceCheckSkip与TestWorkspaceCheckGeneratedSetting。小结EnvChecksOpts虽然只是一个仅含include?属性的小类型别名但它连接着 Dagger 检查体系的关键链路从 TypeScript SDK 的Env.checks(opts)到 GraphQLchecks(include:)参数再到引擎端ModTree.RollupChecks/RollupGenerator的 glob 过滤最终由CheckGroup并行执行并产出报告。掌握include的模式语义*通配、**跨命名空间、前缀匹配、白名单并集你就能在 LLM 环境、CI 流水线或本地开发中精准控制要发现与执行的检查集合。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考