Dagger TypeScript SDK SearchResult 类完全指南:掌握 grep 搜索结果的结构化读取与源码实现
Dagger TypeScript SDK SearchResult 类完全指南掌握 grep 搜索结果的结构化读取与源码实现【免费下载链接】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导读SearchResult是 Dagger TypeScript SDKdagger.io/dagger客户端中用于承载文本搜索grep结果的核心类。当你对Directory或Workspace调用search方法时引擎会基于 ripgrep 扫描文件内容并把每个命中位置包装成一个SearchResult对象返回。读完本文你将掌握SearchResult的全部字段与方法语义、其底层 GraphQL 类型定义、以及它如何与SearchSubmatch协作实现命中位置精确高亮并能在自己的 Dagger 模块中用类型安全的代码完成跨文件内容检索。SearchResult 在 Dagger API 中的定位SearchResult定义于 TypeScript 客户端代码生成产物 classes/SearchResult.md位于api/client.gen模块即客户端生成代码目录参见 api/client.gen 模块索引。它继承自BaseClient与 SDK 中其他 GraphQL 对象一样构造器仅供内部使用new SearchResult(ctx?, _id?, _absoluteOffset?, _filePath?, _lineNumber?, _matchedLines?)文档明确标注 Constructor is used for internal usage only, do not create object from it.也就是说你不应该自己new SearchResult(...)而是通过Directory.search、Workspace.search等 API 的返回值获取其实例。构造器的可选参数恰好一一对应该对象的持久化字段_absoluteOffsetnumber、_filePathstring、_lineNumbernumber、_matchedLinesstring以及 ID 类型SearchResultID。在 GraphQL schema 层SearchResult被定义为实现Node接口的对象类型见 core/schema/testdata/base_schema.graphqlstype SearchResult implements Node { The byte offset of this line within the file. absoluteOffset: Int! The path to the file that matched. filePath: String! A unique identifier for this SearchResult. id: ID! The first line that matched. lineNumber: Int! The line content that matched. matchedLines: String! Sub-match positions and content within the matched lines. submatches: [SearchSubmatch!]! }每个字段在服务端都是非空!的因此客户端方法返回的Promise解析后不会出现对应字段为null的情况。六个公开方法逐一解析SearchResult类对外暴露 6 个方法全部返回Promise需要在await后取值。下面结合字段语义逐一说明。absoluteOffset()命中的字节偏移async absoluteOffset(): Promisenumber返回该行在文件中的字节偏移量byte offset。注意它定位的是匹配行的起始偏移而非文件中任意字节位置。该值直接来自 ripgrep JSON 输出中的absolute_offset字段见下文源码分析可用于在二进制/大文件中精确跳转到命中位置或与submatches()提供的行内偏移配合计算命中的绝对字节区间。filePath()命中的文件路径async filePath(): Promisestring返回发生匹配的文件路径The path to the file that matched。当一次搜索横跨多个目录、多个文件时用它区分命中来源配合lineNumber()即可拼出经典的路径:行号定位格式。id()对象唯一标识async id(): PromiseSearchResultID返回该 SearchResult 的唯一标识符类型为SearchResultIDSearchResultID string object它本质上是一个带__SearchResultID: never哨兵字段的字符串类型属于 TypeScript 的 branded/nominal typing 技巧——运行时就是一个字符串但编译期不会与普通string或其它 ID 类型混淆。SearchResultID对应 GraphQL 中的scalar SearchResultID见 base_schema.graphqls用于在会话间持久化引用某个具体的搜索结果对象。lineNumber()首个匹配行号async lineNumber(): Promisenumber返回第一个匹配的行号The first line that matched。行号从 1 开始计数对应文件内容中该行的实际行号而不是数组下标。多行模式multiline下一次命中可能跨越多行此字段记录的是起始行。matchedLines()命中的行内容async matchedLines(): Promisestring返回命中的行内容The line content that matched。这是搜索后最常直接消费的字段——拿到命中的整行文本即可用于日志过滤、代码审查、CI 校验等场景。在多行匹配时matchedLines会包含跨行的全部文本以\n连接。submatches()行内子匹配详情async submatches(): PromiseSearchSubmatch[]返回匹配行内的子匹配位置与内容Sub-match positions and content within the matched lines。每个元素是SearchSubmatch对象其方法为start(): Promisenumber—— 匹配在 matchedLines 内的起始偏移end(): Promisenumber—— 匹配在 matchedLines 内的结束偏移text(): Promisestring—— 实际命中的文本片段id(): PromiseSearchSubmatchID—— 子匹配的唯一标识。submatches的价值在于当正则表达式本身含有大量噪音例如整行都被matchedLines返回但你只关心真正命中的单词子匹配能给出精确的命中片段与行内区间便于实现高亮命中词之类的 UI 或精确替换逻辑。GraphQL 侧对应 SearchSubmatch 类型。深入源码SearchResult 的服务端结构与持久化SearchResult并非仅在 SDK 客户端存在它同时是 Dagger 引擎核心对象模型的一部分。核心结构体定义在 core/search.gotype SearchResult struct { FilePath string field:true doc:The path to the file that matched. LineNumber int field:true doc:The first line that matched. AbsoluteOffset int field:true doc:The byte offset of this line within the file. MatchedLines string field:true doc:The line content that matched. Submatches []*SearchSubmatch field:true doc:Sub-match positions and content within the matched lines. }可以看到Go 结构体字段上的doc注释与 GraphQL schema、TypeScript 客户端文档中的描述完全一致——这说明 TypeScript 的SearchResult.md正是由该 schema 代码生成而来三者共享同一套语义。该结构体实现了dagql.PersistedObject与dagql.PersistedObjectDecoder接口core/search.go意味着SearchResult具备跨会话持久化能力EncodePersistedObjectcore/search.go把FilePath、LineNumber、AbsoluteOffset、MatchedLines以及非空的Submatches序列化为 JSON payloadDecodePersistedObjectcore/search.go反向解码从持久化 payload 重建SearchResult对象。这就是SearchResultID存在的意义拿到 ID 后即使搜索上下文已销毁也能在后续调用中恢复引用。SearchSubmatch同样实现了这一对接口core/search.go其持久化字段为Text、Start、End三者。SearchOpts决定 SearchResult 产出方式的参数族要拿到SearchResult需要先调用搜索入口。Directory.search的服务端实现定义在 core/schema/directory.gotype searchArgs struct { core.SearchOpts Paths []string default:[] Globs []string default:[] } func (s *directorySchema) search(ctx context.Context, parent dagql.ObjectResult[*core.Directory], args searchArgs) (dagql.Array[*core.SearchResult], error) { return parent.Self().Search(ctx, parent, args.SearchOpts, true, args.Paths, args.Globs) }搜索选项由SearchOpts定义core/search.go全部参数如下参数类型默认值含义patternstring—必填要匹配的文本正则或字面量字符串literalbooleanfalse将 pattern 视为字面量字符串而非正则表达式multilinebooleanfalse允许跨行搜索dotallbooleanfalse在 multiline 模式下允许.匹配换行符insensitivebooleanfalse启用大小写不敏感匹配skipIgnoredbooleanfalse是否遵循.gitignore、.ignore、.rgignore文件skipHiddenbooleanfalse是否跳过隐藏文件以.开头的文件filesOnlybooleanfalse只返回匹配的文件路径不返回行内容limitnumber不限制限制返回的结果数量在Directory场景下还有两个补充参数paths在指定路径下搜索与globs按 glob 模式过滤文件默认[]。这些选项会逐一映射为底层 ripgrep 命令行参数core/search.goliteral→--fixed-stringsmultiline→--multilinedotall→--multiline-dotallinsensitive→--ignore-case未开启skipIgnored时追加--no-ignore即默认忽略 ignore 文件未开启skipHidden时追加--hidden即默认搜索隐藏文件filesOnly→--files-with-matches否则追加--json始终追加--regexppattern与--no-follow禁止跟随符号链接值得注意的一个实现细节limit没有对应的 ripgrep 标志ripgrep 只能按文件限制结果数无法限制总数因此它是在结果解析阶段生效的见 core/search.go——解析到len(results) *opts.Limit时便停止读取。ripgrep JSON 输出到 SearchResult 的映射过程默认非filesOnly模式下引擎以--json运行 ripgrep并通过parseRgOutputcore/search.go流式解码输出。JSON 的match类型记录结构如下core/search.gotype rgJSON struct { Type string json:type Data struct { Path rgContent json:path Lines rgContent json:lines LineNumber int json:line_number AbsoluteOffset int json:absolute_offset Submatches []struct { Match rgContent json:match Start int json:start End int json:end } json:submatches } json:data }解析时每个字段直接落到SearchResult上core/search.godata.path.text→FilePathdata.line_number→LineNumberdata.absolute_offset→AbsoluteOffsetdata.lines.text→MatchedLinesdata.submatches[*]逐条转为SearchSubmatch{Text, Start, End}同时有两处健壮性处理遇到非 UTF-8 的路径或内容会记录告警并跳过core/search.go保证不会因为个别二进制文件中断整个搜索若 ripgrep 以退出码 1 结束表示无匹配则返回空结果而非报错core/search.go。而在filesOnly模式下则简单地把每行输出作为一个仅含FilePath的SearchResult返回core/search.go此时其余字段为空——这与 GraphQL 类型中字段非空的约束并不冲突因为服务端字段依然按 schema 暴露只是对应值在生成客户端时由引擎保证类型安全。实战在 Dagger 模块中用 SearchResult 检索代码结合以上语义一个典型的 TypeScript 用法是对模块内的源码目录执行正则搜索遍历返回的SearchResult打印文件:行号:内容并对命中词做高亮import { dag, Directory, Container } from dagger.io/dagger; // 假设 src 是一个 Directory 对象例如从 host 目录加载 async function grepSrc(src: Directory): Promisevoid { // 大小写不敏感、忽略 .gitignore 规则、返回行级结果 const results await src.search(todo|fixme, { insensitive: true, }); for (const r of results) { const filePath await r.filePath(); const lineNumber await r.lineNumber(); const offset await r.absoluteOffset(); const lines await r.matchedLines(); const submatches await r.submatches(); console.log(${filePath}:${lineNumber} (byte offset ${offset})); // 用子匹配精确标出命中的文本区间 for (const sm of submatches) { const text await sm.text(); const start await sm.start(); const end await sm.end(); console.log( ^ ${text} [${start}, ${end})); } } }若只想定位文件而不是关心行内容可以开启filesOnly此时每个SearchResult只携带filePath适合做哪些文件包含某模式的清单型任务const files await dir.search(export class, { filesOnly: true }); for (const r of files) { console.log(await r.filePath()); }在 Workspace 场景下引擎会把搜索拆分为本地/底层文件系统与overlay 变更层两部分结果并做按文件的合并参见 core/schema/workspace.go 的mergeSearchResults逻辑并且支持paths、globs等同样的SearchOpts参数core/schema/workspace.go——也就是说无论搜索对象是Directory还是Workspace返回的SearchResult对象结构完全一致上层消费代码可以复用。小结SearchResult是 Dagger 文本搜索能力的统一返回值模型6 个方法覆盖命中定位四要素文件路径、行号、字节偏移、行内容以及精确子匹配submatches与对象 ID服务端核心实现位于 core/search.go由 ripgrep--json输出流式映射而来并支持跨会话持久化GraphQL 契约定义于 base_schema.graphqlsTypeScript 客户端文档与其一一对应搜索入口为Directory.searchcore/schema/directory.go与Workspace.searchcore/schema/workspace.go通过SearchOpts的 9 个选项灵活控制匹配语义。在编写 Dagger 模块时无论你是要做代码规范扫描、CI 中的禁止出现敏感关键字校验还是构建工具链中的源码分析SearchResultSearchSubmatch的组合都能以类型安全的方式把 ripgrep 的原始能力接入你的自动化流水线。【免费下载链接】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),仅供参考

相关新闻

Open-Claw电商监控系统:动态抓取与pandas分析实战

Open-Claw电商监控系统:动态抓取与pandas分析实战

1. 为什么“人工盯品”正在拖垮电商运营团队——从3个真实场景看监控失效的代价我去年帮一家做跨境美妆的客户做过一次诊断,他们团队每天早上9点雷打不动开晨会,第一件事就是让3个运营助理轮着刷京东、淘宝、拼多多的竞品页面,手动截图价格、…

2026/11/18 10:36:22 阅读更多 →
Flink StandAlone模式生产部署与作业提交全流程实战

Flink StandAlone模式生产部署与作业提交全流程实战

1. 为什么我在生产里宁愿选StandAlone:模式选型逻辑先说个背景。我最早接触Flink的时候,项目里清一色用的YARN模式,因为公司大数据平台标配就是Hadoop那一套,Flink on YARN看起来顺理成章。后来有一个独立的数据集成项目&#xff…

2026/11/18 10:36:22 阅读更多 →
WSL搭建OpenCart测试环境:Shell自动化与数据库校验实战

WSL搭建OpenCart测试环境:Shell自动化与数据库校验实战

1. 项目概述:为什么在WSL里搭OpenCart测试环境值得花时间折腾OpenCart 测试环境工程化——这标题里每个词都踩在真实开发痛点上。不是“本地跑起来就行”,而是“能像生产环境一样被版本管理、一键重建、数据可追溯、变更可回滚”。我带过三个电商项目团队…

2026/11/18 10:36:28 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/20 23:27:28 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/20 23:27:28 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/20 23:27:28 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/20 21:55:32 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/20 23:27:28 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/20 22:59:12 阅读更多 →

日新闻

周新闻

月新闻