尧图网站建设 
Qwen Code Serve 大文本区间读取一致性基于 open-time stat 快照的流式窗口实现【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读在 Qwen Code 的 Serve 文件服务中readText边界在文件超过MAX_READ_BYTES256 KiB时会切换到大文件有限行窗口的流式读取路径而不是一次性吞入整个文件。但打开文件描述符只能固定 inode无法冻结 inode 上的字节并发写入、原地重写、截断、路径替换都可能让读者观察到打开之后的字节。本文基于设计文档 serve-large-text-range-consistency.md 并结合 workspace-file-system.ts 与 policy.ts 源码深入讲解这条流式路径如何以open-time stat 快照为基线做前后一致性校验、如何在读后统一归并为hash_mismatch错误以及GET /file与 ACP_qwen/file/read两个消费入口的实际行为。读完你将掌握这套有限窗口 快照校验 明确错误分类的一致性模型以及它在源码与测试中的落点。背景为什么打开文件句柄还不够Serve 目前对超过MAX_READ_BYTES的文件会流式返回有限大小的文本窗口。触发条件很严格只有同时携带行窗口参数如line/limit的请求才能进入该路径纯line或纯maxBytes请求不会解锁此路径仍停留在全量快照门内工作区边界会只打开一次文件全程通过这个句柄读取并返回不带全文件哈希的部分元数据。这里的关键难点是一个打开的 fd 固定了 inode但并没有冻结 inode 的字节内容。Node 也不会同步同一文件上的并发修改操作。因此一个读者完全可能观察到open之后才写入的字节——包括同 inode、同大小的原地重写in-place rewrite。这正是 Issue #7946 要求解决的契约读取期间被修改或替换的文件必须被拒绝。同时该契约明确不包含对追加append的容忍——追加容忍不是本 bug 修复的目标。决策以 open-time stat 作为快照基线针对上述问题设计文档给出的决策是大文件流式窗口以打开时刻的 stat 作为快照基线通过一前一后两次校验来保证一致性打开前校验初始lstat与打开后的fstat必须指向同一个普通文件且 device、inode、size、mtime修改时间、ctime变更时间全部一致读取后校验流式读取结束后句柄上的fstat与路径上的lstat都必须保持该身份与版本不变且路径名不得是符号链接symlink句柄释放时机调用方在finally中关闭句柄——即所有读取和稳定性检查完成之后才关闭失败归并任何一项稳定性校验不通过统一返回hash_mismatch。内容校验错误的延迟上报一个值得注意的细节是内容校验错误如二进制探测、非 UTF-8 解码失败会被捕获并挂起直到读后稳定性检查全部通过后才抛出。这样做的目的是如果并发变更同时导致了解码失败最终结果仍然是hash_mismatch变更优先而如果没有并发变更则按内容分类二进制内容 →binary_file大体积非 UTF-8 文本 →file_too_large并附带转换提示hint。测试 workspace-file-system.test.ts 验证了这一点携带真实dev/ino的游标能通过陈旧性门禁后开始解码非 UTF-8 内容会被重新分类为binary_file而不是file_too_large——后者会让客户端永远重试。与全量快照策略的一致性该策略与既有的全量快照稳定性策略保持一致并且有意拒绝并发追加size 增长本身就证明 open-time 快照不稳定而仅凭 inode 身份相同无法证明原始前缀未被修改。若要做到可靠的追加容忍需要单独的快照机制或第二次有界读取来逐字节验证用于定位/产出目标行窗口的每一个字节——这部分额外 I/O 与协议策略被明确划出本 bug 修复范围。实现落点workspace-file-system.ts 中的校验链在 workspace-file-system.ts 中大文件行窗口路径由readLargeTextWindowFromResolvedFile承担L2106-L2169其核心流程为fsp.open(p, r)打开句柄随后fh.stat()得到打开态openedassertSameFile(pre, opened, p, read)assertStreamWindowStable确认 lstat 与 fstat 身份、版本一致用BINARY_PROBE_BYTES4 KiB探测头字节looksBinary命中即记录为二进制错误policy.ts 中该采样大小与 core 的isBinaryFile对齐委托 lowFs 的readTextFileFromHandle从句柄上流式解码窗口传入limit、line、maxOutputBytes默认MAX_READ_BYTES与maxScanBytesfinally中关闭句柄随后执行读后校验路径lstat若为符号链接 → 抛symlink_escapeTOCTOU 替换检测assertSameFile(opened, afterRead, ...)assertStreamWindowStable句柄身份与版本未变assertSameFile(opened, post, ...)assertStreamWindowStable路径身份与版本未变。无游标的字节窗口路径readBytesWindowL835-L920采用同样纪律打开前lstat→fh.stat()→assertSameFile→ 定位读取 → 读后fh.stat()比对ino size mtimeMs不符即抛hash_mismatch并提示重新读取最新文件哈希后重试句柄关闭后再通过assertInodeStableAfterRead复核路径 inode 未被替换。快照校验的粒度说明校验对比的维度包含size、mtime修改时间、ctime变更时间。这意味着同大小的原地重写只要落在后一个时间戳量子内就会被拒绝mtime 与 ctime 都要保持一种更刁钻的情况——重写同时恢复 mtime——只能靠 ctime 前进捕获这依赖内核粗粒度时钟的 best-effort 精度并非绝对保证即便如此该策略也严格强于此前size mtime的全量快照比较设计文档明确如此表述。Range-reader 清理移除 forceStreaming 与句柄缓冲快路径由于调用方持有的文件句柄总是走流式路径原本独立的forceStreaming开关以及句柄缓冲快路径被一并移除。当前实现要点句柄分块读取器将定位读取限制在调用方捕获的文件大小内任何一次读取都不会越过 open-time 的 EOF全程复用一个 512 KiB 的缓冲区——因为每个块在生成器推进之前都是同步解码的不存在多块并行占用的问题没有固定的扫描字节预算行偏移需要对字节流从第 0 字节开始扫描因此深层窗口的代价仍是 O(文件大小)。返回内容与内存由有限行数与MAX_READ_BYTES上限约束读取之间会检查取消cancellation标志。关于无固定扫描预算这一点后续实现已在 policy.ts 中引入MAX_TEXT_SCAN_BYTES 8 MiB作为定位行窗口的扫描成本上限超过该预算的请求返回file_too_large并指引使用可 O(1) 到达任意偏移的readBytes——这是对设计文档中未来需要扫描成本策略cursor 或等价续传契约的直接落地而不是让有效深度偏移静默不可达。lineEnding 的派生规则Serve 的全量快照读取从整个解码文件派生lineEnding而大文件窗口路径从返回窗口本身派生但存在两处例外字节游标页游标页会统计其返回切片之外的终止符——即恢复读取时承接的那个终止符当页首行被字节预算截断时还会统计重定位扫描越过的那一个终止符。这样做的效果是在统一换行符的文件中未终止的尾页与前一页判定一致字节截断页与后一页判定一致。混合换行符的文件仍可能在页间翻转对同一份字节大文件行窗口与字节游标页也可能给出不同的lineEnding——设计文档将统一两条路径列为候选后续工作尚无跟踪 issue。Core 层可继续为自己的其他消费者报告文件级元数据不受影响。truncated 标志的真实语义每个大文件窗口都保持truncated: true即使扫描恰好到达 EOF 也是如此。这个标志在此边界的用途是区分两类结果无全文件哈希的窗口大文件流式读取可安全视为全文件内容的完整快照。也就是说truncated在这里不仅仅表示解码字符被省略。这与 workspace-file-system.test.ts 的断言一致limit: 20的行窗口返回后truncated true且hash undefined即使请求的行号超出 EOF返回空内容时也保持truncated: true仅额外给出originalLineCount。消费者哪些入口会到达这条边界所有 Serve 调用方在到达此边界前都会先经过选定的工作区运行时解析GET /file路由实现位于 workspace-file-read.ts是文本读取的主要 HTTP 入口ACP HTTP_qwen/file/read在 acp-http/index.ts 中注册由 dispatch.ts 转发到fs.readText其参数校验与默认值行为在 transport.test.ts 中有完整覆盖。readTextFile 适配器不再是生产消费者注入的 ACPreadTextFile适配器bridge-file-system-adapter.ts已不再是生产路径的消费者同主机的 daemon 运行时对外宣告readTextFile: false因此 agent 的文本读取由子进程常规 CLI 文件系统服务承接永远不会到达此边界。适配器的读取路径被保留为fail-closed 守卫仅在出现意外或能力违规的委托读取时兜底拒绝。因此本文档后续验证的并发追加、截断、符号链接替换等保证不再适用于任何 agent 读取。相关细节见 daemon-local-text-reads.md。另外工作区设置workspace setup使用的无窗口读取仍保留既有的256 KiB 全量快照拒绝策略enforceReadBytesSize见 policy.ts。验证矩阵从设计到测试设计文档给出了明确的验证清单其中大部分已在源码测试中落地验证项期望行为落点混合 EOL 大文件的行窗口返回切片内实际存在的换行风格readLargeTextWindowFromResolvedFile的 lineEnding 派生字节游标页的终止符统计可报告切片外的终止符游标续传路径并发追加 / 截断 / 路径替换 / 符号链接替换全部拒绝hash_mismatch/symlink_escape读后fstatlstat双校验同大小原地重写落入后一时间戳量子即拒绝mtime ctime 对比句柄绑定范围读取不使用全缓冲快路径、复用流式缓冲chunk reader 单一 512 KiB 缓冲超过 10 MiB 的深层偏移在有限行数下成功返回深偏移行窗口场景无 limit / 仅 line / 仅 maxBytes仍停留在 256 KiB 全量快照门内路径选择条件输出、编码、二进制、哈希、行数限制保持不变既有策略常量测试文件 workspace-file-system.test.ts 给出了一个典型用例构造MAX_READ_BYTES 1字节的文件分别以{ limit: 20 }、{ line: 3, limit: 20 }、超出行号请求读取断言返回切片精确、sizeBytes为全文件大小、truncated恒为true且无hash——这组断言就是上文有限窗口 快照元数据契约的直接体现。小结Serve 的大文本区间读取一致性本质上是把文件内容不可变从假设变成可验证的运行时契约以 open-time stat 为快照基线用 lstat/fstat 双重校验锁定 device、inode、size、mtime、ctime 与符号链接身份把一切并发变更统一归并为hash_mismatch并以truncated: true明确标识无全文件哈希的窗口这一状态。对于想要继续深入该边界的读者推荐按以下路径研读源码policy.ts容量与预算常量、workspace-file-system.tsreadBytesWindow与readLargeTextWindowFromResolvedFile两条校验链、workspace-file-system.test.ts行为契约测试以及 workspace-file-read.ts 与 dispatch.ts两个消费入口的转发与参数校验。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Qwen Code Serve 大文本区间读取一致性：基于 open-time stat 快照的流式窗口实现
Qwen Code Serve 大文本区间读取一致性基于 open-time stat 快照的流式窗口实现【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读在 Qwen Code 的 Serve 文件服务中readText边界在文件超过MAX_READ_BYTES256 KiB时会切换到大文件有限行窗口的流式读取路径而不是一次性吞入整个文件。但打开文件描述符只能固定 inode无法冻结 inode 上的字节并发写入、原地重写、截断、路径替换都可能让读者观察到打开之后的字节。本文基于设计文档 serve-large-text-range-consistency.md 并结合 workspace-file-system.ts 与 policy.ts 源码深入讲解这条流式路径如何以open-time stat 快照为基线做前后一致性校验、如何在读后统一归并为hash_mismatch错误以及GET /file与 ACP_qwen/file/read两个消费入口的实际行为。读完你将掌握这套有限窗口 快照校验 明确错误分类的一致性模型以及它在源码与测试中的落点。背景为什么打开文件句柄还不够Serve 目前对超过MAX_READ_BYTES的文件会流式返回有限大小的文本窗口。触发条件很严格只有同时携带行窗口参数如line/limit的请求才能进入该路径纯line或纯maxBytes请求不会解锁此路径仍停留在全量快照门内工作区边界会只打开一次文件全程通过这个句柄读取并返回不带全文件哈希的部分元数据。这里的关键难点是一个打开的 fd 固定了 inode但并没有冻结 inode 的字节内容。Node 也不会同步同一文件上的并发修改操作。因此一个读者完全可能观察到open之后才写入的字节——包括同 inode、同大小的原地重写in-place rewrite。这正是 Issue #7946 要求解决的契约读取期间被修改或替换的文件必须被拒绝。同时该契约明确不包含对追加append的容忍——追加容忍不是本 bug 修复的目标。决策以 open-time stat 作为快照基线针对上述问题设计文档给出的决策是大文件流式窗口以打开时刻的 stat 作为快照基线通过一前一后两次校验来保证一致性打开前校验初始lstat与打开后的fstat必须指向同一个普通文件且 device、inode、size、mtime修改时间、ctime变更时间全部一致读取后校验流式读取结束后句柄上的fstat与路径上的lstat都必须保持该身份与版本不变且路径名不得是符号链接symlink句柄释放时机调用方在finally中关闭句柄——即所有读取和稳定性检查完成之后才关闭失败归并任何一项稳定性校验不通过统一返回hash_mismatch。内容校验错误的延迟上报一个值得注意的细节是内容校验错误如二进制探测、非 UTF-8 解码失败会被捕获并挂起直到读后稳定性检查全部通过后才抛出。这样做的目的是如果并发变更同时导致了解码失败最终结果仍然是hash_mismatch变更优先而如果没有并发变更则按内容分类二进制内容 →binary_file大体积非 UTF-8 文本 →file_too_large并附带转换提示hint。测试 workspace-file-system.test.ts 验证了这一点携带真实dev/ino的游标能通过陈旧性门禁后开始解码非 UTF-8 内容会被重新分类为binary_file而不是file_too_large——后者会让客户端永远重试。与全量快照策略的一致性该策略与既有的全量快照稳定性策略保持一致并且有意拒绝并发追加size 增长本身就证明 open-time 快照不稳定而仅凭 inode 身份相同无法证明原始前缀未被修改。若要做到可靠的追加容忍需要单独的快照机制或第二次有界读取来逐字节验证用于定位/产出目标行窗口的每一个字节——这部分额外 I/O 与协议策略被明确划出本 bug 修复范围。实现落点workspace-file-system.ts 中的校验链在 workspace-file-system.ts 中大文件行窗口路径由readLargeTextWindowFromResolvedFile承担L2106-L2169其核心流程为fsp.open(p, r)打开句柄随后fh.stat()得到打开态openedassertSameFile(pre, opened, p, read)assertStreamWindowStable确认 lstat 与 fstat 身份、版本一致用BINARY_PROBE_BYTES4 KiB探测头字节looksBinary命中即记录为二进制错误policy.ts 中该采样大小与 core 的isBinaryFile对齐委托 lowFs 的readTextFileFromHandle从句柄上流式解码窗口传入limit、line、maxOutputBytes默认MAX_READ_BYTES与maxScanBytesfinally中关闭句柄随后执行读后校验路径lstat若为符号链接 → 抛symlink_escapeTOCTOU 替换检测assertSameFile(opened, afterRead, ...)assertStreamWindowStable句柄身份与版本未变assertSameFile(opened, post, ...)assertStreamWindowStable路径身份与版本未变。无游标的字节窗口路径readBytesWindowL835-L920采用同样纪律打开前lstat→fh.stat()→assertSameFile→ 定位读取 → 读后fh.stat()比对ino size mtimeMs不符即抛hash_mismatch并提示重新读取最新文件哈希后重试句柄关闭后再通过assertInodeStableAfterRead复核路径 inode 未被替换。快照校验的粒度说明校验对比的维度包含size、mtime修改时间、ctime变更时间。这意味着同大小的原地重写只要落在后一个时间戳量子内就会被拒绝mtime 与 ctime 都要保持一种更刁钻的情况——重写同时恢复 mtime——只能靠 ctime 前进捕获这依赖内核粗粒度时钟的 best-effort 精度并非绝对保证即便如此该策略也严格强于此前size mtime的全量快照比较设计文档明确如此表述。Range-reader 清理移除 forceStreaming 与句柄缓冲快路径由于调用方持有的文件句柄总是走流式路径原本独立的forceStreaming开关以及句柄缓冲快路径被一并移除。当前实现要点句柄分块读取器将定位读取限制在调用方捕获的文件大小内任何一次读取都不会越过 open-time 的 EOF全程复用一个 512 KiB 的缓冲区——因为每个块在生成器推进之前都是同步解码的不存在多块并行占用的问题没有固定的扫描字节预算行偏移需要对字节流从第 0 字节开始扫描因此深层窗口的代价仍是 O(文件大小)。返回内容与内存由有限行数与MAX_READ_BYTES上限约束读取之间会检查取消cancellation标志。关于无固定扫描预算这一点后续实现已在 policy.ts 中引入MAX_TEXT_SCAN_BYTES 8 MiB作为定位行窗口的扫描成本上限超过该预算的请求返回file_too_large并指引使用可 O(1) 到达任意偏移的readBytes——这是对设计文档中未来需要扫描成本策略cursor 或等价续传契约的直接落地而不是让有效深度偏移静默不可达。lineEnding 的派生规则Serve 的全量快照读取从整个解码文件派生lineEnding而大文件窗口路径从返回窗口本身派生但存在两处例外字节游标页游标页会统计其返回切片之外的终止符——即恢复读取时承接的那个终止符当页首行被字节预算截断时还会统计重定位扫描越过的那一个终止符。这样做的效果是在统一换行符的文件中未终止的尾页与前一页判定一致字节截断页与后一页判定一致。混合换行符的文件仍可能在页间翻转对同一份字节大文件行窗口与字节游标页也可能给出不同的lineEnding——设计文档将统一两条路径列为候选后续工作尚无跟踪 issue。Core 层可继续为自己的其他消费者报告文件级元数据不受影响。truncated 标志的真实语义每个大文件窗口都保持truncated: true即使扫描恰好到达 EOF 也是如此。这个标志在此边界的用途是区分两类结果无全文件哈希的窗口大文件流式读取可安全视为全文件内容的完整快照。也就是说truncated在这里不仅仅表示解码字符被省略。这与 workspace-file-system.test.ts 的断言一致limit: 20的行窗口返回后truncated true且hash undefined即使请求的行号超出 EOF返回空内容时也保持truncated: true仅额外给出originalLineCount。消费者哪些入口会到达这条边界所有 Serve 调用方在到达此边界前都会先经过选定的工作区运行时解析GET /file路由实现位于 workspace-file-read.ts是文本读取的主要 HTTP 入口ACP HTTP_qwen/file/read在 acp-http/index.ts 中注册由 dispatch.ts 转发到fs.readText其参数校验与默认值行为在 transport.test.ts 中有完整覆盖。readTextFile 适配器不再是生产消费者注入的 ACPreadTextFile适配器bridge-file-system-adapter.ts已不再是生产路径的消费者同主机的 daemon 运行时对外宣告readTextFile: false因此 agent 的文本读取由子进程常规 CLI 文件系统服务承接永远不会到达此边界。适配器的读取路径被保留为fail-closed 守卫仅在出现意外或能力违规的委托读取时兜底拒绝。因此本文档后续验证的并发追加、截断、符号链接替换等保证不再适用于任何 agent 读取。相关细节见 daemon-local-text-reads.md。另外工作区设置workspace setup使用的无窗口读取仍保留既有的256 KiB 全量快照拒绝策略enforceReadBytesSize见 policy.ts。验证矩阵从设计到测试设计文档给出了明确的验证清单其中大部分已在源码测试中落地验证项期望行为落点混合 EOL 大文件的行窗口返回切片内实际存在的换行风格readLargeTextWindowFromResolvedFile的 lineEnding 派生字节游标页的终止符统计可报告切片外的终止符游标续传路径并发追加 / 截断 / 路径替换 / 符号链接替换全部拒绝hash_mismatch/symlink_escape读后fstatlstat双校验同大小原地重写落入后一时间戳量子即拒绝mtime ctime 对比句柄绑定范围读取不使用全缓冲快路径、复用流式缓冲chunk reader 单一 512 KiB 缓冲超过 10 MiB 的深层偏移在有限行数下成功返回深偏移行窗口场景无 limit / 仅 line / 仅 maxBytes仍停留在 256 KiB 全量快照门内路径选择条件输出、编码、二进制、哈希、行数限制保持不变既有策略常量测试文件 workspace-file-system.test.ts 给出了一个典型用例构造MAX_READ_BYTES 1字节的文件分别以{ limit: 20 }、{ line: 3, limit: 20 }、超出行号请求读取断言返回切片精确、sizeBytes为全文件大小、truncated恒为true且无hash——这组断言就是上文有限窗口 快照元数据契约的直接体现。小结Serve 的大文本区间读取一致性本质上是把文件内容不可变从假设变成可验证的运行时契约以 open-time stat 为快照基线用 lstat/fstat 双重校验锁定 device、inode、size、mtime、ctime 与符号链接身份把一切并发变更统一归并为hash_mismatch并以truncated: true明确标识无全文件哈希的窗口这一状态。对于想要继续深入该边界的读者推荐按以下路径研读源码policy.ts容量与预算常量、workspace-file-system.tsreadBytesWindow与readLargeTextWindowFromResolvedFile两条校验链、workspace-file-system.test.ts行为契约测试以及 workspace-file-read.ts 与 dispatch.ts两个消费入口的转发与参数校验。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考