openinterpreter 的 codex-utils-stream-parser 深度解析LLM 流式输出中跨分块隐藏标签的增量解析【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter本篇技术指南基于 openinterpreter 仓库中的 codex-utils-stream-parser 文档 及其完整源码讲解如何在模型流式响应streaming场景下正确解析被分块切碎的隐藏标签如oai-mem-citation并覆盖 UTF-8 跨分块字节流处理。读完后你可以掌握该 crate 的全部公开 API、增量解析器的状态机原理以及它在 Codex 核心会话循环中的真实调用链。1. 问题背景为什么不能逐块独立解析流式文本模型的流式输出往往不是干净的纯文本其中可能夹带隐藏标记hidden markup。例如 Codex 的记忆引用会以内联标签形式出现oai-mem-citationdoc A/oai-mem-citation这类标签的作用是承载机器可消费的负载如引用来源不应展示给用户。问题在于流式传输按 chunk 切分标签可能被切在两个分块的边界上例如一个分块以oai-mem-结尾下一个分块才出现citation...。如果对每个 chunk 独立做正则替换或字符串查找就会漏掉这些跨边界的标签导致标记泄漏到用户可见文本中。crate 文档给出的解法原则是解析器必须在分块之间保持状态keep parser state across chunks每次输入返回两部分结果——可以立即渲染的可见文本以及单独提取的隐藏负载。文档还附了一段值得注意的自我声明This code is pretty complex and Codex did not manage to write it so before updating the code, make sure to deeply understand it and dont blindly trust Codex on it.也就是说这段代码是人工编写并经仔细审阅的理解其状态机行为比重写一遍更重要。2. 核心抽象StreamTextParsertrait 与StreamTextChunk整个 crate 围绕一个两方法的 trait 构建定义见 stream_text.rs/// Trait for parsers that consume streamed text and emit visible text plus extracted payloads. pub trait StreamTextParser { /// Payload extracted by this parser (for example a citation body). type Extracted; /// Feed a new text chunk. fn push_str(mut self, chunk: str) - StreamTextChunkSelf::Extracted; /// Flush any buffered state at end-of-stream (or end-of-item). fn finish(mut self) - StreamTextChunkSelf::Extracted; }每次push_str/finish都返回一个StreamTextChunkTstream_text.rspub struct StreamTextChunkT { /// Text safe to render immediately. pub visible_text: String, /// Hidden payloads extracted from the chunk. pub extracted: VecT, }visible_text的契约是可以立即安全渲染extracted是本次提取出的隐藏负载。StreamTextChunk提供is_empty()方法判断两者是否均为空——文档的 Known limitations 中也明确提醒流式解析可能返回空对象例如某个 chunk 全是待确认的标签前缀时visible_text与extracted都可能为空调用方必须容忍并继续累积而不能把空结果当作错误。3. 通用引擎InlineHiddenTagParserT这是 crate 的核心实现inline_hidden_tag.rs一个通过类型参数T: Clone Eq标记标签种类的泛型状态机。配置项为InlineTagSpecpub struct InlineTagSpecT { pub tag: T, pub open: static str, // 如 oai-mem-citation pub close: static str, // 如 /oai-mem-citation }构造函数InlineHiddenTagParser::new(specs)有三条硬性校验违反即 panic至少一个 spec、open非空、close非空分别对应测试generic_inline_parser_rejects_empty_open_delimiter等inline_hidden_tag.rs。3.1push_str的三段式状态机从 inline_hidden_tag.rs 的实现看每次push_str把新 chunk 追加进内部pending缓冲后进入一个循环按状态分三条路径已有激活标签等待闭合在pending中查找close分隔符。找到则将close之前的内容并入标签内容、发出ExtractedInlineTag { tag, content }消费掉闭合标记后继续循环处理后续文本找不到闭合标记时保留pending末尾最长后缀前缀即最可能是close开头的若干字符其余部分全部并入标签内容缓冲——这就是标签闭合也能跨分块工作的关键。未激活且发现开标签find_next_open在所有 spec 中搜索最早出现的开标签同一偏移有多个 spec 命中时优先更长的 open 分隔符再按 spec 下标稳定排序测试generic_inline_parser_prefers_longest_opener_at_same_offset验证了a与ab并存时xaby/abz只产出B标签。开标签之前的前缀文本直接作为可见文本输出随后进入激活状态。未激活且未发现开标签计算pending末尾对任一open的最长后缀前缀长度max_open_prefix_suffix_len保留该后缀等待下一分块确认其余全部作为可见文本排出。第 3 步依赖的longest_suffix_prefix_len工具函数inline_hidden_tag.rs从长到短枚举needle的前缀k要求needle在k处是字符边界且pending以needle[..k]结尾。字符边界检查保证了非 ASCII 分隔符如é.../é在按字节切分时也能正确匹配对应测试generic_inline_parser_supports_non_ascii_tag_delimiters。3.2finish的自动闭合语义finishinline_hidden_tag.rs的行为若流结束时标签仍处于激活状态则自动闭合把缓冲内容作为一条提取结果返回若无激活标签则把残留pending含未确认的标签前缀全部作为可见文本输出。这里有一个容易被忽略的细微差别由测试明确固定流结束在xoai-mem-citationsource完整开标签 无闭合→ 自动闭合提取出source测试citation_parser_auto_closes_unterminated_tag_on_finish流结束在hello oai-mem-只是标签的前缀不构成完整开标签→ 不提取hello oai-mem-原样作为可见文本返回测试citation_parser_preserves_partial_open_tag_at_eof_if_not_a_full_tag。3.3 自定义隐藏标签示例文档给出的自定义标签用法如下可复制运行标签种类用枚举区分use codex_utils_stream_parser::InlineHiddenTagParser; use codex_utils_stream_parser::InlineTagSpec; use codex_utils_stream_parser::StreamTextParser; #[derive(Clone, Debug, PartialEq, Eq)] enum Tag { Secret, } let mut parser InlineHiddenTagParser::new(vec![InlineTagSpec { tag: Tag::Secret, open: secret, close: /secret, }]); let out parser.push_str(asecretx/secretb); assert_eq!(out.visible_text, ab); assert_eq!(out.extracted.len(), 1); assert_eq!(out.extracted[0].content, x);InlineHiddenTagParser同时支持多种标签并存一个 parser 实例可配置多个 specextracted中每项通过ExtractedInlineTag.tag字段标明来源测试generic_inline_parser_supports_multiple_tag_types验证了1ax/a2by/b3输出可见文本123并分别提取x、y。4. 便捷封装CitationStreamParser与strip_citationsCitationStreamParser 是对InlineHiddenTagParser的薄封装固定匹配oai-mem-citation//oai-mem-citation并把Extracted简化为String即引用正文本身去掉了标签枚举这一层。其文档注释明确继承了两条语义字面量、非嵌套匹配EOF 前未闭合则自动闭合。文档示例引用流式解析use codex_utils_stream_parser::CitationStreamParser; use codex_utils_stream_parser::StreamTextParser; let mut parser CitationStreamParser::new(); let first parser.push_str(Hello oai-mem-); assert_eq!(first.visible_text, Hello ); assert!(first.extracted.is_empty()); let second parser.push_str(citationdoc A/oai-mem-citation world); assert_eq!(second.visible_text, world); assert_eq!(second.extracted, vec![doc A.to_string()]); let tail parser.finish(); assert!(tail.visible_text.is_empty()); assert!(tail.extracted.is_empty());对非流式场景整段文本已在手crate 提供一次性辅助函数strip_citationscitation.rs内部就是push 一次 finish 并合并pub fn strip_citations(text: str) - (String, VecString) { let mut parser CitationStreamParser::new(); let mut out parser.push_str(text); let tail parser.finish(); out.visible_text.push_str(tail.visible_text); out.extracted.extend(tail.extracted); (out.visible_text, out.extracted) }单测 citation.rs 测试模块 覆盖了几个关键行为其中最能体现非嵌套限制的是citation_parser_does_not_support_nested_tags对aoai-mem-citationxoai-mem-citationy/oai-mem-citationz/oai-mem-citationb第一个内层开标签被当作普通文本吞入提取内容结果为可见文本az/oai-mem-citationb、提取[xoai-mem-citationy]。如果你的上游内容可能出现嵌套标签需要自行处理。5. 字节流适配层Utf8StreamParserP上面所有解析器都以str为输入。但真实传输层socket、WebSocket 分帧等交付的是[u8]UTF-8 码点可能被切在分块边界例如é被切成0xC3与0xA9两个分块。直接String::from_utf8_lossy会引入替换字符并破坏标签匹配。Utf8StreamParserutf8_stream.rs以适配器模式包装任意P: StreamTextParser内部用pending_utf8: Vecu8缓冲跨块的不完整码点。文档示例use codex_utils_stream_parser::CitationStreamParser; use codex_utils_stream_parser::Utf8StreamParser; # fn demo() - Result(), codex_utils_stream_parser::Utf8StreamParserError { let mut parser Utf8StreamParser::new(CitationStreamParser::new()); // é split across chunks: 0xC3 0xA9 let first parser.push_bytes([bH, 0xC3])?; assert_eq!(first.visible_text, H); let second parser.push_bytes([0xA9, b!])?; assert_eq!(second.visible_text, é!); let tail parser.finish()?; assert!(tail.visible_text.is_empty()); # Ok(()) # }5.1 错误类型与回滚语义push_bytes返回Result_, Utf8StreamParserError错误枚举有两类utf8_stream.rsInvalidUtf8 { valid_up_to, error_len }字节序列本身非法IncompleteUtf8AtEof流结束时缓冲中残留不完整的码点。关键设计是整块回滚当本次push_bytes导致非法序列Error::error_len()有值时实现会把pending_utf8截断回推送前的长度utf8_stream.rs不会把该 chunk 的前缀部分喂给内部解析器。测试utf8_stream_parser_rolls_back_entire_chunk_when_invalid_byte_follows_valid_prefix固定了这一行为推送bok\xFF返回InvalidUtf8 { valid_up_to: 2, error_len: 1 }且不产出任何visible_text随后再推送b!能正常恢复。这样调用方无需担心半个坏 chunk 已污染解析器状态。而尾部不完整但可能是下一块补齐的码点error_len()为None是合法中间态先解码并转发前缀有效部分剩余字节继续留在缓冲中。finish时若缓冲非空且不完整则返回IncompleteUtf8AtEofinto_inner()同样会拒绝释放带有未解码字节的包装器into_inner_lossy()则显式放弃该部分码点直接取回内部解析器utf8_stream.rs。6. README 未列出的扩展 API计划块与助手文本组合解析crate 的 lib.rs 实际导出的 API 比 README 列出的五项更广还包含一个面向 Codex plan mode 的完整解析组合层6.1ProposedPlanParser与行级标签解析proposed_plan.rs 解析proposed_plan.../proposed_plan块其底层是内部的行级状态机TaggedLineParsertagged_line_parser.rs与InlineHiddenTagParser的任意内联位置不同它要求标签独占一行允许前导空白因此每行都要缓冲到可以排除是标签行为止模块注释The parser buffers each line until it can disprove that the line is a tag。例如proposed_plan extra这类带尾随文本的行会被判定为普通文本原样保留。输出的ProposedPlanSegment是有序事件流保证普通文本与计划内容的相对顺序pub enum ProposedPlanSegment { Normal(String), // 块外普通文本 ProposedPlanStart, // 块开始 ProposedPlanDelta(String), // 块内增量内容 ProposedPlanEnd, // 块结束 }同样具备自动闭合语义未闭合的计划块在finish时补发ProposedPlanEnd。另有两个非流式辅助函数strip_proposed_plan_blocks(text) - String与extract_proposed_plan_text(text) - OptionStringproposed_plan.rs。6.2AssistantTextStreamParser一次遍历同时剥离两类标记assistant_text.rs 是组合层构造时传入plan_mode: bool内部串联CitationStreamParser与plan 模式下ProposedPlanParser。每个 chunk 的处理顺序是先剥离 citation 标签得到可见文本再若 plan 模式对可见文本跑计划块解析。输出结构为pub struct AssistantTextChunk { pub visible_text: String, pub citations: VecString, pub plan_segments: VecProposedPlanSegment, }内联测试parses_plan_segments_after_citation_stripping覆盖了两种标记在跨块流中共存的完整场景citation 标签被切在_plan\n- step oai-mem-citationdoc...处仍能正确分离。7. 在仓库中的真实调用链从源码结构看该 crate 的主要消费方是 Codex 核心会话循环共三处流式消息解析主体session/turn.rs 中的AssistantMessageStreamParsers维护一个HashMapString, AssistantTextStreamParser按消息 item 隔离状态——每个 assistant 消息条目拥有独立的解析器实例。其方法seed_item_text以初始文本播种、parse_delta每次流式 delta 调用一次即 turn.rs 中assistant_message_stream_parsers.parse_delta(item_id, delta)、finish_item条目结束时finish并移除与drain_finished整轮结束时统一冲刷完整对应了 trait 的生命周期语义。非流式工具函数stream_events_utils.rs 引入strip_citations与strip_proposed_plan_blocks用于对完整文本做一次性清理。计划段事件session/mod.rs 使用ProposedPlanSegment把提取出的计划增量事件转发到会话层。这条调用链印证了 crate 的设计定位它不是一个独立工具库而是保证 TUI 渲染时隐藏标记绝不泄漏、引用与计划内容各归其位的流式数据清洗层。8. 工程细节与已知限制零运行时依赖Cargo.toml 没有任何[dependencies]仅 dev-dependencies 中的pretty_assertions用于测试断言这与 README 开头 Small, dependency-free utilities 的描述一致。README 示例不参与编译[lib] doctest false关闭了 doctest因此文档里的示例是说明性代码真正被持续验证的行为以各源文件内联的#[cfg(test)]模块为准例如 utf8_stream.rs 测试 覆盖了分块码点、回滚、EOF 不完整等六类场景。已知限制README Known limitations 一节且与源码一致标签匹配是字面量、区分大小写的——OAI-MEM-CITATION不会被识别不支持嵌套标签见第 4 节的测试证据;流式过程中可能返回空的StreamTextChunk消费端必须累积而非逐块判定。适用前提小结如果你要在自己的流式管线中处理模型输出里携带、需对用户隐藏的内联标记这套方案的前提是标记的分隔符是固定的字面量字符串、不嵌套、且负载内容不需要展示。满足这些条件时InlineHiddenTagParser 必要时Utf8StreamParser的组合可以直接复用若还涉及独占一行的块级标记可参考ProposedPlanParser/TaggedLineParser的行缓冲思路。所有实现细节与测试均可在 codex-rs/utils/stream-parser 目录下核对。【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 openinterpreter 的 codex-utils-stream-parser 深度解析：LLM 流式输出中跨分块隐藏标签的增量解析
openinterpreter 的 codex-utils-stream-parser 深度解析LLM 流式输出中跨分块隐藏标签的增量解析【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter本篇技术指南基于 openinterpreter 仓库中的 codex-utils-stream-parser 文档 及其完整源码讲解如何在模型流式响应streaming场景下正确解析被分块切碎的隐藏标签如oai-mem-citation并覆盖 UTF-8 跨分块字节流处理。读完后你可以掌握该 crate 的全部公开 API、增量解析器的状态机原理以及它在 Codex 核心会话循环中的真实调用链。1. 问题背景为什么不能逐块独立解析流式文本模型的流式输出往往不是干净的纯文本其中可能夹带隐藏标记hidden markup。例如 Codex 的记忆引用会以内联标签形式出现oai-mem-citationdoc A/oai-mem-citation这类标签的作用是承载机器可消费的负载如引用来源不应展示给用户。问题在于流式传输按 chunk 切分标签可能被切在两个分块的边界上例如一个分块以oai-mem-结尾下一个分块才出现citation...。如果对每个 chunk 独立做正则替换或字符串查找就会漏掉这些跨边界的标签导致标记泄漏到用户可见文本中。crate 文档给出的解法原则是解析器必须在分块之间保持状态keep parser state across chunks每次输入返回两部分结果——可以立即渲染的可见文本以及单独提取的隐藏负载。文档还附了一段值得注意的自我声明This code is pretty complex and Codex did not manage to write it so before updating the code, make sure to deeply understand it and dont blindly trust Codex on it.也就是说这段代码是人工编写并经仔细审阅的理解其状态机行为比重写一遍更重要。2. 核心抽象StreamTextParsertrait 与StreamTextChunk整个 crate 围绕一个两方法的 trait 构建定义见 stream_text.rs/// Trait for parsers that consume streamed text and emit visible text plus extracted payloads. pub trait StreamTextParser { /// Payload extracted by this parser (for example a citation body). type Extracted; /// Feed a new text chunk. fn push_str(mut self, chunk: str) - StreamTextChunkSelf::Extracted; /// Flush any buffered state at end-of-stream (or end-of-item). fn finish(mut self) - StreamTextChunkSelf::Extracted; }每次push_str/finish都返回一个StreamTextChunkTstream_text.rspub struct StreamTextChunkT { /// Text safe to render immediately. pub visible_text: String, /// Hidden payloads extracted from the chunk. pub extracted: VecT, }visible_text的契约是可以立即安全渲染extracted是本次提取出的隐藏负载。StreamTextChunk提供is_empty()方法判断两者是否均为空——文档的 Known limitations 中也明确提醒流式解析可能返回空对象例如某个 chunk 全是待确认的标签前缀时visible_text与extracted都可能为空调用方必须容忍并继续累积而不能把空结果当作错误。3. 通用引擎InlineHiddenTagParserT这是 crate 的核心实现inline_hidden_tag.rs一个通过类型参数T: Clone Eq标记标签种类的泛型状态机。配置项为InlineTagSpecpub struct InlineTagSpecT { pub tag: T, pub open: static str, // 如 oai-mem-citation pub close: static str, // 如 /oai-mem-citation }构造函数InlineHiddenTagParser::new(specs)有三条硬性校验违反即 panic至少一个 spec、open非空、close非空分别对应测试generic_inline_parser_rejects_empty_open_delimiter等inline_hidden_tag.rs。3.1push_str的三段式状态机从 inline_hidden_tag.rs 的实现看每次push_str把新 chunk 追加进内部pending缓冲后进入一个循环按状态分三条路径已有激活标签等待闭合在pending中查找close分隔符。找到则将close之前的内容并入标签内容、发出ExtractedInlineTag { tag, content }消费掉闭合标记后继续循环处理后续文本找不到闭合标记时保留pending末尾最长后缀前缀即最可能是close开头的若干字符其余部分全部并入标签内容缓冲——这就是标签闭合也能跨分块工作的关键。未激活且发现开标签find_next_open在所有 spec 中搜索最早出现的开标签同一偏移有多个 spec 命中时优先更长的 open 分隔符再按 spec 下标稳定排序测试generic_inline_parser_prefers_longest_opener_at_same_offset验证了a与ab并存时xaby/abz只产出B标签。开标签之前的前缀文本直接作为可见文本输出随后进入激活状态。未激活且未发现开标签计算pending末尾对任一open的最长后缀前缀长度max_open_prefix_suffix_len保留该后缀等待下一分块确认其余全部作为可见文本排出。第 3 步依赖的longest_suffix_prefix_len工具函数inline_hidden_tag.rs从长到短枚举needle的前缀k要求needle在k处是字符边界且pending以needle[..k]结尾。字符边界检查保证了非 ASCII 分隔符如é.../é在按字节切分时也能正确匹配对应测试generic_inline_parser_supports_non_ascii_tag_delimiters。3.2finish的自动闭合语义finishinline_hidden_tag.rs的行为若流结束时标签仍处于激活状态则自动闭合把缓冲内容作为一条提取结果返回若无激活标签则把残留pending含未确认的标签前缀全部作为可见文本输出。这里有一个容易被忽略的细微差别由测试明确固定流结束在xoai-mem-citationsource完整开标签 无闭合→ 自动闭合提取出source测试citation_parser_auto_closes_unterminated_tag_on_finish流结束在hello oai-mem-只是标签的前缀不构成完整开标签→ 不提取hello oai-mem-原样作为可见文本返回测试citation_parser_preserves_partial_open_tag_at_eof_if_not_a_full_tag。3.3 自定义隐藏标签示例文档给出的自定义标签用法如下可复制运行标签种类用枚举区分use codex_utils_stream_parser::InlineHiddenTagParser; use codex_utils_stream_parser::InlineTagSpec; use codex_utils_stream_parser::StreamTextParser; #[derive(Clone, Debug, PartialEq, Eq)] enum Tag { Secret, } let mut parser InlineHiddenTagParser::new(vec![InlineTagSpec { tag: Tag::Secret, open: secret, close: /secret, }]); let out parser.push_str(asecretx/secretb); assert_eq!(out.visible_text, ab); assert_eq!(out.extracted.len(), 1); assert_eq!(out.extracted[0].content, x);InlineHiddenTagParser同时支持多种标签并存一个 parser 实例可配置多个 specextracted中每项通过ExtractedInlineTag.tag字段标明来源测试generic_inline_parser_supports_multiple_tag_types验证了1ax/a2by/b3输出可见文本123并分别提取x、y。4. 便捷封装CitationStreamParser与strip_citationsCitationStreamParser 是对InlineHiddenTagParser的薄封装固定匹配oai-mem-citation//oai-mem-citation并把Extracted简化为String即引用正文本身去掉了标签枚举这一层。其文档注释明确继承了两条语义字面量、非嵌套匹配EOF 前未闭合则自动闭合。文档示例引用流式解析use codex_utils_stream_parser::CitationStreamParser; use codex_utils_stream_parser::StreamTextParser; let mut parser CitationStreamParser::new(); let first parser.push_str(Hello oai-mem-); assert_eq!(first.visible_text, Hello ); assert!(first.extracted.is_empty()); let second parser.push_str(citationdoc A/oai-mem-citation world); assert_eq!(second.visible_text, world); assert_eq!(second.extracted, vec![doc A.to_string()]); let tail parser.finish(); assert!(tail.visible_text.is_empty()); assert!(tail.extracted.is_empty());对非流式场景整段文本已在手crate 提供一次性辅助函数strip_citationscitation.rs内部就是push 一次 finish 并合并pub fn strip_citations(text: str) - (String, VecString) { let mut parser CitationStreamParser::new(); let mut out parser.push_str(text); let tail parser.finish(); out.visible_text.push_str(tail.visible_text); out.extracted.extend(tail.extracted); (out.visible_text, out.extracted) }单测 citation.rs 测试模块 覆盖了几个关键行为其中最能体现非嵌套限制的是citation_parser_does_not_support_nested_tags对aoai-mem-citationxoai-mem-citationy/oai-mem-citationz/oai-mem-citationb第一个内层开标签被当作普通文本吞入提取内容结果为可见文本az/oai-mem-citationb、提取[xoai-mem-citationy]。如果你的上游内容可能出现嵌套标签需要自行处理。5. 字节流适配层Utf8StreamParserP上面所有解析器都以str为输入。但真实传输层socket、WebSocket 分帧等交付的是[u8]UTF-8 码点可能被切在分块边界例如é被切成0xC3与0xA9两个分块。直接String::from_utf8_lossy会引入替换字符并破坏标签匹配。Utf8StreamParserutf8_stream.rs以适配器模式包装任意P: StreamTextParser内部用pending_utf8: Vecu8缓冲跨块的不完整码点。文档示例use codex_utils_stream_parser::CitationStreamParser; use codex_utils_stream_parser::Utf8StreamParser; # fn demo() - Result(), codex_utils_stream_parser::Utf8StreamParserError { let mut parser Utf8StreamParser::new(CitationStreamParser::new()); // é split across chunks: 0xC3 0xA9 let first parser.push_bytes([bH, 0xC3])?; assert_eq!(first.visible_text, H); let second parser.push_bytes([0xA9, b!])?; assert_eq!(second.visible_text, é!); let tail parser.finish()?; assert!(tail.visible_text.is_empty()); # Ok(()) # }5.1 错误类型与回滚语义push_bytes返回Result_, Utf8StreamParserError错误枚举有两类utf8_stream.rsInvalidUtf8 { valid_up_to, error_len }字节序列本身非法IncompleteUtf8AtEof流结束时缓冲中残留不完整的码点。关键设计是整块回滚当本次push_bytes导致非法序列Error::error_len()有值时实现会把pending_utf8截断回推送前的长度utf8_stream.rs不会把该 chunk 的前缀部分喂给内部解析器。测试utf8_stream_parser_rolls_back_entire_chunk_when_invalid_byte_follows_valid_prefix固定了这一行为推送bok\xFF返回InvalidUtf8 { valid_up_to: 2, error_len: 1 }且不产出任何visible_text随后再推送b!能正常恢复。这样调用方无需担心半个坏 chunk 已污染解析器状态。而尾部不完整但可能是下一块补齐的码点error_len()为None是合法中间态先解码并转发前缀有效部分剩余字节继续留在缓冲中。finish时若缓冲非空且不完整则返回IncompleteUtf8AtEofinto_inner()同样会拒绝释放带有未解码字节的包装器into_inner_lossy()则显式放弃该部分码点直接取回内部解析器utf8_stream.rs。6. README 未列出的扩展 API计划块与助手文本组合解析crate 的 lib.rs 实际导出的 API 比 README 列出的五项更广还包含一个面向 Codex plan mode 的完整解析组合层6.1ProposedPlanParser与行级标签解析proposed_plan.rs 解析proposed_plan.../proposed_plan块其底层是内部的行级状态机TaggedLineParsertagged_line_parser.rs与InlineHiddenTagParser的任意内联位置不同它要求标签独占一行允许前导空白因此每行都要缓冲到可以排除是标签行为止模块注释The parser buffers each line until it can disprove that the line is a tag。例如proposed_plan extra这类带尾随文本的行会被判定为普通文本原样保留。输出的ProposedPlanSegment是有序事件流保证普通文本与计划内容的相对顺序pub enum ProposedPlanSegment { Normal(String), // 块外普通文本 ProposedPlanStart, // 块开始 ProposedPlanDelta(String), // 块内增量内容 ProposedPlanEnd, // 块结束 }同样具备自动闭合语义未闭合的计划块在finish时补发ProposedPlanEnd。另有两个非流式辅助函数strip_proposed_plan_blocks(text) - String与extract_proposed_plan_text(text) - OptionStringproposed_plan.rs。6.2AssistantTextStreamParser一次遍历同时剥离两类标记assistant_text.rs 是组合层构造时传入plan_mode: bool内部串联CitationStreamParser与plan 模式下ProposedPlanParser。每个 chunk 的处理顺序是先剥离 citation 标签得到可见文本再若 plan 模式对可见文本跑计划块解析。输出结构为pub struct AssistantTextChunk { pub visible_text: String, pub citations: VecString, pub plan_segments: VecProposedPlanSegment, }内联测试parses_plan_segments_after_citation_stripping覆盖了两种标记在跨块流中共存的完整场景citation 标签被切在_plan\n- step oai-mem-citationdoc...处仍能正确分离。7. 在仓库中的真实调用链从源码结构看该 crate 的主要消费方是 Codex 核心会话循环共三处流式消息解析主体session/turn.rs 中的AssistantMessageStreamParsers维护一个HashMapString, AssistantTextStreamParser按消息 item 隔离状态——每个 assistant 消息条目拥有独立的解析器实例。其方法seed_item_text以初始文本播种、parse_delta每次流式 delta 调用一次即 turn.rs 中assistant_message_stream_parsers.parse_delta(item_id, delta)、finish_item条目结束时finish并移除与drain_finished整轮结束时统一冲刷完整对应了 trait 的生命周期语义。非流式工具函数stream_events_utils.rs 引入strip_citations与strip_proposed_plan_blocks用于对完整文本做一次性清理。计划段事件session/mod.rs 使用ProposedPlanSegment把提取出的计划增量事件转发到会话层。这条调用链印证了 crate 的设计定位它不是一个独立工具库而是保证 TUI 渲染时隐藏标记绝不泄漏、引用与计划内容各归其位的流式数据清洗层。8. 工程细节与已知限制零运行时依赖Cargo.toml 没有任何[dependencies]仅 dev-dependencies 中的pretty_assertions用于测试断言这与 README 开头 Small, dependency-free utilities 的描述一致。README 示例不参与编译[lib] doctest false关闭了 doctest因此文档里的示例是说明性代码真正被持续验证的行为以各源文件内联的#[cfg(test)]模块为准例如 utf8_stream.rs 测试 覆盖了分块码点、回滚、EOF 不完整等六类场景。已知限制README Known limitations 一节且与源码一致标签匹配是字面量、区分大小写的——OAI-MEM-CITATION不会被识别不支持嵌套标签见第 4 节的测试证据;流式过程中可能返回空的StreamTextChunk消费端必须累积而非逐块判定。适用前提小结如果你要在自己的流式管线中处理模型输出里携带、需对用户隐藏的内联标记这套方案的前提是标记的分隔符是固定的字面量字符串、不嵌套、且负载内容不需要展示。满足这些条件时InlineHiddenTagParser 必要时Utf8StreamParser的组合可以直接复用若还涉及独占一行的块级标记可参考ProposedPlanParser/TaggedLineParser的行缓冲思路。所有实现细节与测试均可在 codex-rs/utils/stream-parser 目录下核对。【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考