oh-my-pi 的 read 工具全解析一个 path 打通文件、归档、SQLite、图片与网页的统一读取协议【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本文以 oh-my-pi⌥ Coding agent with the IDE wired in为背景深度剖析其内置read工具的完整能力。read通过单个path字符串统一读取文件、目录、归档、SQLite、文档、图片、内部资源与 Web URL并附加强大的选择器selector语法用于精确定位行区间。读完本文你将掌握行选择器与各资源类型的完整语法、底层实现原理含关键源码路径以及并行化与安全读取的实战准则。一、工具定位Agent 的全能读取器在 oh-my-pi 的 coding-agent 工具集中read是面向 Agent 的统一读取入口。模型端提示词 read.md 明确界定了两条使用准则应该并行化独立的读取SHOULD parallelize independent readsAgent 面对多个互不依赖的读取目标时应并发发起多个read调用而不是串行等待以最大化吞吐Web 内容应优先使用read而非browserread能直接抓取并渲染网页为干净的 reader 模式文本只有read无法交付时才回退到浏览器工具从而省去浏览器启动与渲染开销。该提示词通过 read.ts 第 30 行的import readDescription from ../prompts/tools/read.md直接嵌入工具实现属于模型可见的运行时提示。工具本身在 tools/index.ts 中注册read: s new ReadTool(s)。二、Selector 语法用:sel后缀精确切分任何资源read最核心的设计是把定位信息编码进path字符串本身。任何资源路径本地文件、归档成员、SQLite、内部 URI 等后都可追加:sel选择器。官方速查示例src/foo.ts:50-200、src/foo.ts:raw、db.sqlite:users:42。2.1 行选择器Line Selectors语法含义:50/:50-从第 50 行开始开放结尾:50-200第 50 到 200 行两端含:50150从第 50 行起共 150 行:-60文件最后 60 行:5-16,960-973多区间逗号分隔读取前会排序合并:raw原样输出无锚点/行号前缀:2-4:raw/:raw:2-4区间 原样组合:conflicts每个未解决的 Git 合并冲突块输出一行索引:img将本地.svg/.svgz栅格化为 PNG 图片返回实现层面selector 解析位于 read-selector.ts 的parseSel()它能识别lines一个或多个闭区间、tail:-N需要先获知源文件总行数后再由resolveTailSelector()转成绝对区间、raw、conflicts、image五种形态。值得注意的是行号是1-indexed:0会直接抛错后的行数必须 1区间-的结束行必须开始行见 docs/tools/read.md 对parseLineRangeChunk()的说明字面文件路径优先于选择器解释如果一个已存在的 POSIX 文件名恰好以选择器样式的文本结尾如真实文件report:raw会按字面文件名读取避免误伤未识别的尾随:...会有意放行fall through因为归档和 SQLite 路径有自己的冒号语法需要消费见parseSel()中Unrecognized compound — fall through的分支注释。2.2 图片与视频的特殊处理裸图片路径当活动模型支持图片输入时图片会直接以像素形式送入模型decoded inline for vision-capable models?qquestion查询仅图片同样适用于.svg:img?q、attachment://N?q、local://…?q——把问题交给视觉模型以文本返回答案而非像素。它在任何模型上都能工作且节省上下文但若活动模型本身就支持图片输入仍优先使用裸图片路径视频文件.mp4、.mov、.mkv、.webm、.m4v、.avi、.wmv需要系统安装ffmpeg/ffprobe。裸读返回预览网格 元数据分辨率、编码、时长、fps:412抽取第 412 帧:1h5m42s、:90s、:01:23可跳到指定时间戳取帧。三、Source kinds按目标类型自动分派read对path指向的目标类型自动分派处理策略这从 read.ts 庞大的导入表即可见一斑它同时接入了read-archive、read-sqlite、read-pdf、read-summary、read-path-resolution、sqlite-reader、fetch、video、image-loading等子模块。3.1 可解析源码结构摘要Structural Summary对无选择器的可解析代码文件read返回结构摘要——只含声明declarations only函数/类体被省略body elided。摘要页脚会列出被省略的区间名recovery selectorAgent 必须仅重发这些区间以获取细节绝不允许猜测../…的内容。在IS_HL_MODEhashline 模式下文件 选择器会输出[foo.ts#1A2B]快照头 编号行。复制[FILENAME#TAG]可作带锚点的编辑绝不编造 tagNEVER fabricate the tag——tag 由文件快照存储file-snapshot-store.ts哈希生成后续edit工具会用它做校验与恢复。3.2 目录、SQLite、归档目标行为目录输出深度受限的 dirent 列表由 workspace-tree.ts 渲染目录树SQLite.sqlite/.sqlite3/.db/.db3file.db列出表file.db:table输出表结构行file.db:table:key按主键取行支持?limit、?where、?qSELECT原生 SQL归档.zip家族含.jar/.apk/.whl、.tar系列.tar.gz/.bz2/.xz/.zst、.rar、.7z、.iso、.cab、.deb/.rpm/.cpio/.ar/.a、.lzh/.arj、.asar以及单流.gz/.bz2/.xz/.zst用archive.ext:path/inside/archive读取内部成员SQLite 底层实现sqlite-reader.ts有大量工程细节值得注意通过文件头魔数SQLite format 3\x00SQLITE_MAGIC识别目标见looksLikeSqlite()连接默认PRAGMA query_only ON即纯只读查询杜绝副作用busy_timeout 3000容忍写锁默认查询上限DEFAULT_QUERY_LIMIT 20schema 采样默认 5 行?q原生 SQL 行数上限MAX_RAW_QUERY_ROWS 1000防止SELECT *击穿百万行大表表计数采用sqlite_stat1规划器估算 小表精确计数探测上限ROW_COUNT_PROBE_CAP 50000避免在 TUI 线程上对多 GB 数据库执行同步全表COUNT(*)导致界面冻结宽行渲染受MAX_RENDER_WIDTH 120/MAX_COLUMN_WIDTH 40约束列数过多时自动退化为垂直块布局。3.3 文档、Notebook、URL 与内部 URI文档提取纯文本Notebook.ipynb转换为可编辑的# %% [...] cell:N文本notebook.tsSVG默认按文本读取除非指定:imgimg.png?qquestion交给视觉模型以文本作答:raw则绕过一切转换器URL默认返回 reader 模式的干净文本/markdown:raw返回未经处理的 HTML。裸host:port需要末尾加斜杠因为 URL 端口也使用:例如https://example.com/:80见 docs/tools/read.md内部 URI所有 scheme 都支持选择器。artifact://id可恢复溢出的输出配合:N-M/:raw:N-M分页ssh://host/path读取远端文件/目录UTF-8≤1 MiB裸ssh://列出主机支持被write写入、被grep搜索。字面:、?、#需百分号编码%3A/%3F/%23并要求远端有已验证的 POSIX shellWindows 等不支持的主机可用bash 远程 SSH 命令或sshfs挂载绕过。四、源码级实现印证4.1 分派流水线ReadTool.execute()的流程详见 docs/tools/read.md 的 Flow 一节接收{ path }file://...输入先经expandPath()展开conflict://N[/ours|theirs|base|both]在普通 URL 之前被处理尝试 Web URL 处理parseReadUrlTarget()fetch.ts普通 URL 走executeReadUrl()带行选择器的 URL 读取先抓取/渲染进 URL 缓存再对渲染后的文本本地分页检查内部 URL 路由router.ts包括内置 scheme 与 MCP 宣告的扩展 scheme回退到本地文件系统读取期间由splitPathAndSel()path-utils.ts拆分路径与尾随选择器。4.2 单次缓冲、多重视图的读取优化read.ts 中的BufferedFileText接口第 168-183 行体现了性能设计二进制嗅探、结构摘要、行窗口、括号上下文与快照哈希全部共享同一份字节一次打开、一次 UTF-8 解码、一次 CRLF 归一化。文件 ≤SNAPSHOT_MAX_BYTES4 MiB时才整体缓冲超出后流式读取窗口严格更省成本。readWholeFile()与deriveBufferedFileText()分离保证对解码成乱码的文件在构造三个字符串视图之前就被二进制嗅探拒绝。4.3 测试佐证仓库提供了充分的测试覆盖可用于理解行为边界read-tool.test.ts验证attachment://N图片附件 URL 与底层图片文件路径读取结果一致且未知附件会报错并列出可用 URIread-multi-range.test.ts验证多区间选择器下 hashline 头保留工作区相对路径并可通过settings.set(read.summarize.enabled, false)关闭结构摘要以断言裸行内容其他如 read-summary.test.ts、read-edit-out-of-cwd.test.ts、tools/path-literal-colon-selector.test.ts 分别覆盖摘要、越界读取与字面文件名含冒号等边界。五、使用准则与 红线提示词最后用critical强调了不可逾越的安全约束摘要页脚列出的省略区间只重发这些区间绝不猜测../…内容。这意味着 Agent 的读取行为必须是可验证的精确结构摘要负责导航区间重读负责取证二者配合既省 token 又保证模型读到的一定是真实存在的行不会因幻觉补全而产生错误理解。配合:conflicts扫描未解决 Git 合并冲突并注册进会话冲突历史、:raw绕过一切转换器拿原文等能力read构成了 Agent 侧先精确观察、再决定编辑的安全闭环。六、小结oh-my-pi 的read工具将读取抽象为一门小型协议路径定位 冒号选择器 类型自动分派。无论目标是源码、目录、压缩包、SQLite、Notebook、图片、视频、网页还是ssh://远端Agent 都只需构造一条path字符串即可且可对独立目标并行调用。想深入源码的读者可从入口 read.ts 出发配合 path-utils.ts、read-selector.ts、sqlite-reader.ts、fetch.ts 逐层阅读模型侧行为则以 prompts/tools/read.md 为准绳。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考