流式汇总与 UI 展示

fn new() -> Self

作用：创建一个新的引用流解析器。有人要开始从文字流里剥离引用标签时，就先调用它。

数据流：进去不需要外部输入 → 它准备好一条规则：看到 <oai-mem-citation> 就开始隐藏并收集，看到 </oai-mem-citation> 就结束 → 出来一个可以连续接收文字块的 CitationStreamParser。

调用关系：这是整个解析流程的起点。strip_citations 会用它处理完整字符串，多个测试也会用它直接检查流式输入、半截标签和未闭合标签这些情况。它把真正识别标签的活交给底层的 InlineHiddenTagParser::new。

调用图：调用 1 个内部函数（new）；被 11 处调用（strip_citations, citation_parser_auto_closes_unterminated_tag_on_finish, citation_parser_buffers_partial_open_tag_prefix, citation_parser_preserves_partial_open_tag_at_eof_if_not_a_full_tag, citation_parser_streams_across_chunk_boundaries, utf8_stream_parser_errors_on_incomplete_code_point_at_eof, utf8_stream_parser_handles_split_code_points_across_chunks, utf8_stream_parser_into_inner_errors_when_partial_code_point_is_buffered, utf8_stream_parser_into_inner_lossy_drops_buffered_partial_code_point, utf8_stream_parser_rolls_back_entire_chunk_when_invalid_byte_follows_valid_prefix (+1 more)）；外部调用 1 个（vec!）。

fn default() -> Self

作用：提供一种标准的默认创建方式，效果和直接调用 CitationStreamParser::new 一样。

数据流：进去没有参数 → 它转手调用 new → 出来一个按默认引用标签规则配置好的解析器。

调用关系：这是 Rust 里常见的默认构造入口。需要泛型代码或工具函数用“默认值”创建解析器时，可以走这里；实际配置仍然由 CitationStreamParser::new 完成。

调用图：外部调用 1 个（new）。

fn push_str(&mut self, chunk: &str) -> StreamTextChunk<Self::Extracted>

作用：把新到来的一小段文字喂给解析器，并立刻拿回这一小段能确定的可见文字和引用内容。

数据流：进去是一段字符串切片 chunk，同时读取解析器内部之前攒下的状态 → 它交给内部解析器识别引用标签，把标签从可见文字中去掉，把标签里的内容提出来 → 出来一个 StreamTextChunk，里面有可显示的正文和新提取到的引用字符串；解析器内部状态也会更新，方便下一块文字继续接上。

调用关系：这是流式解析的主要工作口。外层的流式文本处理会反复调用它；它自己不重新发明识别规则，而是调用内部 InlineHiddenTagParser 的 push_str，再把带标签信息的结果简化成普通字符串引用。

调用图：调用 1 个内部函数（push_str）；被 1 处调用（push_str）。

fn finish(&mut self) -> StreamTextChunk<Self::Extracted>

作用：告诉解析器“文字已经没有后续了”，让它把最后攒着的内容结算出来。

数据流：进去没有新文字，但会读取解析器内部还没吐出的缓存 → 它让内部解析器完成收尾；如果已经进入引用标签但没等到关闭标签，就按文件约定自动关闭 → 出来最后一批可见文字和引用内容。

调用关系：它通常在所有 push_str 调用之后执行。没有这一步，末尾半截普通文字或未闭合引用可能还留在缓存里。它把收尾细节交给内部解析器的 finish。

调用图：调用 1 个内部函数（finish）；被 1 处调用（finish）。

fn strip_citations(text: &str) -> (String, Vec<String>)

作用：处理一整段已经拿到手的文字，直接返回“去掉引用标签后的正文”和“引用内容列表”。这是给不需要流式喂数据的调用方用的快捷函数。

数据流：进去是一整段 text → 它新建一个 CitationStreamParser，把整段文字一次性喂进去，再调用 finish 做收尾，然后把两次产出的正文和引用合并 → 出来一个二元结果：干净正文 String 和引用 Vec<String>。

调用关系：这是便利入口，内部仍然复用 CitationStreamParser::new 和同一套流式语义，所以行为和逐块解析一致。相关测试用它验证多条引用、未闭合引用、以及不支持嵌套标签的表现。

调用图：调用 1 个内部函数（new）；被 3 处调用（citation_parser_does_not_support_nested_tags, strip_citations_auto_closes_unterminated_citation_at_eof, strip_citations_collects_all_citations）。

fn collect_chunks(parser: &mut P, chunks: &[&str]) -> StreamTextChunk<P::Extracted>

作用：测试用的小帮手：把多块输入依次喂给某个流式解析器，并把每次输出合并成一个总结果。

数据流：进去是一个可变解析器和一组字符串块 → 它先建一个空的 StreamTextChunk，逐块调用解析器的 push_str，把可见文字接起来，把提取结果追加起来，最后再调用 finish → 出来一份完整汇总后的解析结果。

调用关系：它只在测试里用，目的是让测试更像真实流式场景。多个引用解析测试会借它模拟“数据被切成几段到达”的情况，它调用的是解析器接口里的 push_str 和 finish。

调用图：调用 1 个内部函数（default）；外部调用 2 个（finish, push_str）。

fn citation_parser_streams_across_chunk_boundaries()

作用：验证引用标签就算被拆在不同文字块里，解析器也能认出来。

数据流：进去是一组故意切开的字符串块，其中打开标签和关闭标签都跨块断开 → 测试把这些块交给 collect_chunks → 期望出来的正文是 Hello world，引用列表里只有 source A。

调用关系：这个测试先用 CitationStreamParser::new 创建解析器，再用 collect_chunks 模拟连续输入。它证明 push_str 不是只看当前块，而是会记住上一块留下的半截标签。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, collect_chunks）。

fn citation_parser_buffers_partial_open_tag_prefix()

作用：验证当输入末尾像是引用开始标签的一部分时，解析器会先等一等，不会急着把它当普通文字吐出去。

数据流：第一次进去 abc <oai-mem- → 解析器输出 abc ，把半截标签暂存；第二次进去补全的 citation>x</oai-mem-citation>z → 解析器识别出引用 x，输出后面的 z；最后 finish 没有额外内容。

调用关系：这个测试直接调用 CitationStreamParser::new、push_str 和 finish。它盯住的是流式解析里很容易出错的地方：半截标签必须缓存，不能提前误判。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert!, assert_eq!）。

fn citation_parser_auto_closes_unterminated_tag_on_finish()

作用：验证引用标签打开后如果一直没有关闭，到输入结束时也会把里面的内容当作引用取出来。

数据流：进去的文字是 x<oai-mem-citation>source，没有关闭标签 → collect_chunks 喂完后调用 finish → 出来的可见正文是 x，引用列表是 source。

调用关系：这个测试通过 CitationStreamParser::new 和 collect_chunks 走完整流式流程。它确认 finish 的收尾行为：遇到未闭合引用时自动收口，而不是丢掉内容。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, collect_chunks）。

fn citation_parser_preserves_partial_open_tag_at_eof_if_not_a_full_tag()

作用：验证如果结尾只是一个像标签开头的半截文字，但并没有组成完整引用标签，它会被当作普通正文保留下来。

数据流：进去的文字是 hello <oai-mem- → 解析器等到 finish 时发现它并不是完整的 <oai-mem-citation> → 出来的可见正文仍是 hello <oai-mem-，引用列表为空。

调用关系：这个测试同样通过 CitationStreamParser::new 和 collect_chunks 运行。它补充了上一个未闭合引用测试：只有真正进入了完整引用标签，结尾才会自动关闭；普通半截文字不能被误删。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, collect_chunks）。

fn strip_citations_collects_all_citations()

作用：验证快捷函数 strip_citations 能从一整段文字里收集多条引用，并把正文拼干净。

数据流：进去是一段夹着两组引用标签的字符串 → strip_citations 去掉两组标签和标签内容，同时收集 one、two → 出来的可见正文是 abc，引用列表是 one 和 two。

调用关系：这个测试不直接操作流式解析器，而是检查完整字符串入口 strip_citations。它保证快捷入口没有漏掉多次出现的引用。

调用图：调用 1 个内部函数（strip_citations）；外部调用 1 个（assert_eq!）。

fn strip_citations_auto_closes_unterminated_citation_at_eof()

作用：验证快捷函数遇到没有关闭标签的引用时，也和流式解析器一样会在结尾自动收口。

数据流：进去是 x<oai-mem-citation>y → strip_citations 内部解析并收尾 → 出来正文 x，引用列表 y。

调用关系：这个测试调用 strip_citations，间接覆盖它内部的 CitationStreamParser::finish 行为。它说明快捷函数继承了流式解析器的结尾规则。

调用图：调用 1 个内部函数（strip_citations）；外部调用 1 个（assert_eq!）。

fn citation_parser_does_not_support_nested_tags()

作用：验证这个解析器不支持引用标签套引用标签，并把这种限制固定下来，避免以后有人误以为它会处理嵌套结构。

数据流：进去是一段外层引用里又放了一个引用标签的文字 → strip_citations 按“遇到第一个关闭标签就结束”的简单规则处理 → 出来的引用是 x<oai-mem-citation>y，剩下的 z</oai-mem-citation>b 留在可见正文里。

调用关系：这个测试调用 strip_citations。它记录的是重要边界：解析器按字面、非嵌套方式工作，适合简单隐藏标签，不适合像 HTML 那样解析复杂层级。

调用图：调用 1 个内部函数（strip_citations）；外部调用 1 个（assert_eq!）。

fn new() -> Self

作用：创建一个新的计划块解析器。它告诉底层解析器：只需要认 <proposed_plan> 和 </proposed_plan> 这一对标签。

数据流：进去没有业务数据 → 它准备一条标签规则，说明开始标签、结束标签，以及这个标签代表“计划块” → 出来一个干净的新 ProposedPlanParser，可以马上接收流式文字。

调用关系：这是整个文件的起点。strip_proposed_plan_blocks、extract_proposed_plan_text 和多个测试都会先调用它造出解析器；它内部把具体识别工作交给 TaggedLineParser::new。

调用图：调用 1 个内部函数（new）；被 5 处调用（extract_proposed_plan_text, strip_proposed_plan_blocks, closes_unterminated_plan_block_on_finish, preserves_non_tag_lines, streams_proposed_plan_segments_and_visible_text）；外部调用 1 个（vec!）。

fn default() -> Self

作用：提供一种默认创建方式，让别人可以用 Rust 的默认值习惯来得到一个计划块解析器。

数据流：进去没有参数 → 它直接调用 ProposedPlanParser::new → 出来一个和手动 new 一样的解析器。

调用关系：它是 new 的简写入口。需要默认构造解析器的代码会走这里，而真正的初始化规则仍然集中在 ProposedPlanParser::new。

调用图：外部调用 1 个（new）。

fn push_str(&mut self, chunk: &str) -> StreamTextChunk<Self::Extracted>

作用：把新收到的一小段文字喂给解析器，并立刻拿到这小段里能确定的结果。它适合处理流式输出，也就是文字一块一块到来的情况。

数据流：进去一段新文字 chunk，以及解析器之前记住的未完成状态 → 它先让底层 parse 判断哪些是普通文字、哪些是标签或标签内容，再用 map_segments 翻译成计划块专用结果 → 出来一个 StreamTextChunk，里面有可直接显示的文字和按顺序记录的计划相关片段。

调用关系：它是外部持续喂数据时最常用的入口。调用图里它会被 parse_visible_text 这类上层解析流程使用；它自己把识别交给底层 parse，再把格式转换交给 map_segments。

调用图：调用 2 个内部函数（map_segments, parse）；被 1 处调用（parse_visible_text）。

fn finish(&mut self) -> StreamTextChunk<Self::Extracted>

作用：告诉解析器“没有更多文字了”，让它吐出最后还压在内部的内容。没有这一步，末尾没凑齐的标签或未关闭的计划块可能不会被正确处理。

数据流：进去的是解析器当前记住的剩余状态 → 它调用底层 finish 做收尾，比如处理未关闭的块，再用 map_segments 转成计划块结果 → 出来最后一批 StreamTextChunk，包括可能补出的 ProposedPlanEnd。

调用关系：它在一整段流式文本结束时使用。调用图里它被上层的 finish 流程使用；内部仍然是先让通用标签解析器收尾，再交给 map_segments 做专用翻译。

调用图：调用 2 个内部函数（map_segments, finish）；被 1 处调用（finish）。

fn map_segments(segments: Vec<TaggedLineSegment<PlanTag>>) -> StreamTextChunk<ProposedPlanSegment>

作用：把底层通用标签解析器的结果，翻译成这个文件专用的计划块结果。它还顺手把普通文字拼进 visible_text，让上层知道哪些内容可以显示。

数据流：进去一串 TaggedLineSegment，可能是普通文字、标签开始、标签内容、标签结束 → 它逐个改名成 ProposedPlanSegment，普通文字会同时加入可见文本，计划块内容则只进入提取结果 → 出来一个 StreamTextChunk，同时包含“可见正文”和“完整片段记录”。

调用关系：push_str 和 finish 都会调用它。它处在底层识别和上层使用之间，像翻译员一样，把通用的标签事件翻译成“计划块开始、计划块内容、计划块结束”。

调用图：调用 1 个内部函数（default）；被 2 处调用（finish, push_str）；外部调用 2 个（Normal, ProposedPlanDelta）。

fn strip_proposed_plan_blocks(text: &str) -> String

作用：从一整段文字里删掉 <proposed_plan> 计划块，只返回普通可见文字。适合上层只想展示最终回复、不想展示计划草稿时使用。

数据流：进去完整文本 → 它创建一个 ProposedPlanParser，把文本喂进去，再做一次收尾 → 出来一个字符串，里面已经去掉计划块和计划块内容，只留下普通正文。

调用关系：这是给调用者用的快捷工具，不需要调用者自己处理流式片段。它先通过 ProposedPlanParser::new 建解析器，然后利用解析器产出的 visible_text 得到最终结果。

调用图：调用 1 个内部函数（new）。

fn extract_proposed_plan_text(text: &str) -> Option<String>

作用：从一整段文字里提取计划块中的文字。如果没有看到计划块，就返回空结果。

数据流：进去完整文本 → 它创建解析器，读取所有解析片段；看到 ProposedPlanStart 就记下“确实有计划块”并清空旧内容，看到 ProposedPlanDelta 就把内容追加进去，普通文字和结束标记不加入 → 出来 Some(计划文字)，如果没见过计划块就出来 None。

调用关系：这是另一个快捷工具，服务于只关心计划内容的场景。它调用 ProposedPlanParser::new 建立解析器，然后消费解析器产生的片段，自己负责把计划文字拼起来。

调用图：调用 1 个内部函数（new）；外部调用 1 个（new）。

fn collect_chunks(parser: &mut P, chunks: &[&str]) -> StreamTextChunk<P::Extracted>

作用：测试用的小帮手，把多段输入依次喂给某个流式解析器，并把每次吐出的结果合并起来。这样测试可以模拟真实网络流一样的“分块到达”。

数据流：进去一个解析器和若干文字块 → 它逐块调用 push_str，把每次的可见文字和提取片段累加，最后调用 finish 收尾 → 出来一份合并后的 StreamTextChunk，方便断言检查。

调用关系：它只在测试模块里使用。多个测试函数把不同切法的文字交给它，借此验证 ProposedPlanParser 在分块输入和收尾时是否稳定。

调用图：调用 1 个内部函数（default）；外部调用 2 个（finish, push_str）。

fn streams_proposed_plan_segments_and_visible_text()

作用：验证解析器能在标签被拆开的情况下，仍然正确识别计划块，并把可见正文和计划片段分开。

数据流：进去的是几段故意切开的文字，比如 <proposed_plan> 被拆成两块 → 测试用 collect_chunks 喂给解析器 → 结果应当是可见文字只剩开头和结尾，提取片段里按顺序出现普通文字、计划开始、计划内容、计划结束、普通文字。

调用关系：这个测试先调用 ProposedPlanParser::new 建解析器，再交给 tests::collect_chunks 模拟流式输入，最后用 assert_eq! 检查输出是否符合预期。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, collect_chunks）。

fn preserves_non_tag_lines()

作用：验证看起来有点像标签、但不是独立合法标签的行，不会被误删。比如前面有空格、后面有额外文字的 <proposed_plan> 应该当普通文字处理。

数据流：进去一行 <proposed_plan> extra\n → 解析器处理后不应该进入计划模式 → 出来的可见文字保持原样，提取片段也只是一个普通文字片段。

调用关系：这个测试同样通过 ProposedPlanParser::new 和 tests::collect_chunks 运行解析流程，最后用 assert_eq! 保证解析器不会过度敏感、误伤正常文本。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, collect_chunks）。

fn closes_unterminated_plan_block_on_finish()

作用：验证计划块如果开始了但文本结束前没有写关闭标签，解析器在 finish 时也会自动给出结束事件。

数据流：进去一段只有 <proposed_plan> 开始和计划内容、没有 </proposed_plan> 结束的文字 → collect_chunks 在最后调用 finish → 出来的片段里仍然有计划开始、计划内容、计划结束，可见文字为空。

调用关系：这个测试关注收尾行为。它用 ProposedPlanParser::new 创建解析器，借 tests::collect_chunks 触发最后的 finish，再用 assert_eq! 检查未关闭块是否被安全收束。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, collect_chunks）。

fn strips_proposed_plan_blocks_from_text()

作用：验证快捷函数 strip_proposed_plan_blocks 真的能把计划块整段删掉，只留下前后的普通文字。

数据流：进去一段包含 before、计划块、after 的完整文本 → 调用被测试的删除计划块函数 → 期望出来的字符串是 before\nafter。

调用关系：这是面向便捷工具的测试。它不直接操纵解析器，而是用 assert_eq! 检查 strip_proposed_plan_blocks 对外表现是否正确。

调用图：外部调用 1 个（assert_eq!）。

fn extracts_proposed_plan_text()

作用：验证快捷函数 extract_proposed_plan_text 能把计划块里的正文取出来，而不是取到外面的普通文字。

数据流：进去一段包含普通文字和计划块的完整文本 → 调用提取函数 → 期望出来 Some("- step\n")，表示确实找到计划块并拿到了里面的内容。

调用关系：这是另一个便捷工具的测试。它通过 assert_eq! 检查 extract_proposed_plan_text 的最终返回值，保证上层以后可以放心直接用这个函数拿计划内容。

调用图：外部调用 1 个（assert_eq!）。

fn is_empty(&self) -> bool

作用：判断这次解析结果是不是完全没有东西。别人可以用它来决定要不要继续处理、显示，或者发送这个空结果。

数据流：进去的是一个 AssistantTextChunk 自己已有的三份内容：可见文字、引用列表、计划片段 → 它检查这三份是不是都为空 → 出来一个真假值；它不会改动任何数据。

调用关系：它是结果包上的小检查工具，常用于收尾后判断还有没有剩余内容。文件里的计划解析测试最后就用它确认 finish 没有再吐出多余东西。

fn new(plan_mode: bool) -> Self

作用：创建一个新的助手文本流解析器，并决定要不要开启“计划模式”。计划模式开启后，它会额外识别 <proposed_plan> 里的内容。

数据流：进去的是一个布尔值 plan_mode，意思是是否解析计划块 → 它用默认值准备好内部的引用解析器和计划解析器，再把 plan_mode 存进去 → 出来一个可以持续接收文本片段的新解析器。

调用关系：这是使用解析器的起点。在这个文件的两个测试 tests::parses_citations_across_seed_and_delta_boundaries 和 tests::parses_plan_segments_after_citation_stripping 里，都会先调用它搭好解析器。它内部依赖默认初始化来准备其余零件。

调用图：被 2 处调用（parses_citations_across_seed_and_delta_boundaries, parses_plan_segments_after_citation_stripping）；外部调用 1 个（default）。

fn push_str(&mut self, chunk: &str) -> AssistantTextChunk

作用：把新到的一小段助手文本喂给解析器，立刻拿到这一段里已经能确定的可见文字、引用和计划片段。

数据流：进去的是一段新文本 chunk → 它先交给引用解析器的 push_str，把引用标签剥掉并拿到引用内容；然后把剥完引用后的可见文字交给 parse_visible_text，必要时再解析计划块 → 出来一个 AssistantTextChunk，其中包含这次能显示的文字、这次抽出的引用、以及计划片段；同时解析器内部会记住还没闭合的半截标签。

调用关系：它是流式解析的日常入口：上层每收到一段新文字，就该调用它一次。它自己不包办所有细节，而是先把引用处理交给引用解析器，再把剩下的可见文字交给 AssistantTextStreamParser::parse_visible_text。

调用图：调用 2 个内部函数（parse_visible_text, push_str）。

fn finish(&mut self) -> AssistantTextChunk

作用：告诉解析器“文本流结束了”，让它把还攒在内部、之前不能确定的尾巴内容吐出来。

数据流：进去时不需要新文本，但会读取解析器内部缓存的半截内容 → 它先让引用解析器 finish，拿到最后剩下的可见文字和引用；再调用 parse_visible_text 处理这段文字；如果开启了计划模式，还会让计划解析器 finish，把计划解析器里最后的尾巴合并进结果 → 出来一个最终的 AssistantTextChunk，并完成内部收尾。

调用关系：它用在流结束时，是 push_str 的收尾搭档。它会调用 AssistantTextStreamParser::parse_visible_text，也会调用内部引用解析器和计划解析器各自的 finish，确保没有内容卡在半路。

调用图：调用 3 个内部函数（parse_visible_text, finish, finish）。

fn parse_visible_text(&mut self, visible_text: String) -> AssistantTextChunk

作用：处理已经去掉引用标签的文字：如果没开计划模式，就原样当可见文字返回；如果开了，就继续识别计划块并拆出计划片段。

数据流：进去的是一段已经剥掉引用的 visible_text → 如果 plan_mode 为假，它直接包装成结果返回；如果 plan_mode 为真，它把文字交给计划解析器的 push_str，得到真正该显示的文字和计划片段 → 出来一个 AssistantTextChunk，通常不包含引用，因为引用已经在前一步处理完了。

调用关系：它是引用解析之后的第二道过滤网。AssistantTextStreamParser::push_str 和 AssistantTextStreamParser::finish 都会调用它，用同一套规则处理普通流入内容和最后收尾内容。

调用图：调用 1 个内部函数（push_str）；被 2 处调用（finish, push_str）；外部调用 1 个（default）。

fn parses_citations_across_seed_and_delta_boundaries()

作用：测试引用标签被拆成两段发来时，解析器仍然能正确隐藏标签并提取引用。

数据流：进去的是测试里手写的两段文本：第一段包含引用标签开头和半个引用，第二段补完引用并接上普通文字 → 测试创建不开计划模式的解析器，依次调用 push_str 和 finish → 检查结果是：用户只看到正常文字，引用 doc1 被单独提取，结尾没有多余内容。

调用关系：它通过 AssistantTextStreamParser::new 建立解析器，然后用断言检查行为。这个测试保护的是引用解析的关键场景：特殊标签跨越流式边界时不能出错。

调用图：调用 1 个内部函数（new）；外部调用 1 个（assert_eq!）。

fn parses_plan_segments_after_citation_stripping()

作用：测试在计划模式下，解析器会先去掉引用，再正确识别 <proposed_plan> 计划块。

数据流：进去的是几段故意拆开的文本：有普通开头、被拆开的计划标签、计划内容里的引用、结束标签和结尾文字 → 测试创建开启计划模式的解析器，连续喂入这些片段并最终 finish → 检查结果是：引用被抽走，计划开始、计划内容、计划结束、普通文字都按顺序变成计划片段，可见文字里不混入计划标签。

调用关系：它同样从 AssistantTextStreamParser::new 开始，用断言确认引用解析和计划解析这两层过滤能正确配合。它特别证明了处理顺序很重要：先剥引用，再拆计划。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert!, assert_eq!）。

fn new() -> Self

作用：创建一个全新的表格延后扫描器。它用于从一段还没扫描过的流式文本开头开始，重新判断是否有 Markdown 表格正在形成。

数据流：进去不需要任何输入 → 它把当前读到的源文本位置设为 0，创建代码块追踪器，并清空“上一行”“待确认表头”“已确认表格”等记忆 → 出来一个干净的 TableHoldbackScanner，可以开始按顺序喂入文本块。

调用关系：它是这个扫描器的起点。测试和外层构造流程会调用它；reset 也会借它的逻辑把旧扫描器恢复成刚创建时的状态。内部还会创建 FenceTracker，用来判断当前行是不是在代码块里。

调用图：调用 1 个内部函数（new）；被 3 处调用（new, incremental_holdback_detects_header_delimiter_across_chunk_boundary, incremental_holdback_matches_stateless_scan_per_chunk）。

fn reset(&mut self)

作用：把扫描器清空，恢复到刚创建时的样子。适合一段流结束、换新内容，或者需要丢掉旧判断时使用。

数据流：进去是一个已经用过的扫描器 → 它调用新建逻辑，覆盖掉原来的偏移量、代码块状态、上一行记录和表格判断 → 出来还是同一个扫描器变量，但内容像新的一样。

调用关系：它站在生命周期重置的位置，不自己逐项清理，而是把活交给 TableHoldbackScanner::new。这样初始化和重置保持一致，不容易漏掉某个状态。

调用图：被 1 处调用（reset）；外部调用 1 个（new）。

fn state(&self) -> TableHoldbackState

作用：告诉外面当前应该怎么延后表格内容。结果可能是没有表格、疑似表头、或者已经确认表格。

数据流：进去读取扫描器内部保存的两个位置：已确认表格开头、待确认表头开头 → 它优先返回“已确认”，其次返回“疑似表头”，都没有就返回“无” → 出来一个 TableHoldbackState，供界面决定哪些行可以固定、哪些行还要保持可改。

调用关系：它是外层询问结果的窗口。active_tail_budget_lines 会用它来计算活跃尾巴要留多少；push_source_chunk 扫描新文本后也会在日志里记录这个状态。

调用图：被 1 处调用（active_tail_budget_lines）。

fn push_source_chunk(&mut self, source_chunk: &str)

作用：把新确认可以扫描的一小段原始文本喂给扫描器。它通常只接收已经完整到换行的内容，避免把半行误判成表格结构。

数据流：进去是一段追加来的 source_chunk → 如果为空就不做事；否则按包含换行符的行逐行拆开，逐行交给 push_line，同时统计字节数、行数和耗时 → 出来没有直接返回值，但扫描器内部的表格状态和源文本偏移量会前进，并写一条跟踪日志。

调用关系：它是流式更新进入本文件的主要入口。push_delta 在收到新输出时会调用它，finalize_remaining 在收尾时也会调用它；它自己不判断每一行细节，而是把每行交给 TableHoldbackScanner::push_line。

调用图：调用 1 个内部函数（push_line）；被 2 处调用（finalize_remaining, push_delta）；外部调用 2 个（now, trace!）。

fn push_line(&mut self, source_line: &str)

作用：扫描一行已经提交的源文本，更新“上一行是不是表头”“这一行是不是分隔线”“表格是否确认”等核心判断。

数据流：进去是一行文本，可能带换行符 → 它记录这一行在原始文本里的起点，查看当前是否在代码块中；如果不是普通代码块，就清理引用符号并检查是否像表格行。若上一行是表头、这一行是分隔线，就把表格确认为从上一行开始；若只是看到新的疑似表头，就暂时记住它。最后更新上一行记录、推进代码块追踪器、增加源文本偏移量 → 出来不返回值，但扫描器的状态被推进一行。

调用关系：它是实际状态机，也就是这台小机器的齿轮。push_source_chunk 会反复调用它；它会调用 table_candidate_text 找出可疑表格文本，并调用 FenceTracker 的 kind 和 advance 来判断和更新代码块位置。

调用图：调用 3 个内部函数（table_candidate_text, advance, kind）；被 1 处调用（push_source_chunk）。

fn table_candidate_text(line: &str) -> Option<&str>

作用：从一行文字里取出可能用于判断表格的部分。它会先去掉引用块前缀，再确认这行确实有 Markdown 表格那种竖线分段。

数据流：进去是一行文本 → 它先用 strip_blockquote_prefix 去掉类似“>”的引用标记，再裁掉两边空白，然后用 parse_table_segments 看它能不能按表格竖线拆成段 → 如果像表格行，就输出清理后的文本；否则输出 None，表示别拿它当表格候选。

调用关系：它是表格识别前的过滤器。push_line 用它处理实时流里的每一行；测试用的 table_holdback_state 也用它做同样判断，保证测试扫描和增量扫描看待表格的标准一致。

调用图：调用 2 个内部函数（parse_table_segments, strip_blockquote_prefix）；被 2 处调用（push_line, table_holdback_state）。

fn parse_lines_with_fence_state(source: &str) -> Vec<ParsedLine<'_>>

作用：这是测试用的辅助函数，用来把一整段源文本拆成行，并给每一行标上当时是否处在代码块里。

数据流：进去是一整段 source 文本 → 它创建 FenceTracker，从头按换行拆行；每遇到一行，就记录行文本、当前代码块类型、这一行在原文里的起始位置，然后让追踪器读完这一行并更新状态 → 出来一个 ParsedLine 列表，供测试版扫描器逐行检查。

调用关系：它只在测试编译时存在。table_holdback_state 会先调用它，把原始文本变成带上下文的行列表；它内部依赖 FenceTracker::new 和 advance 维持代码块状态。

调用图：调用 1 个内部函数（new）；被 1 处调用（table_holdback_state）；外部调用 1 个（new）。

fn table_holdback_state(source: &str) -> TableHoldbackState

作用：这是测试用的“一次性扫描”版本：给它完整文本，它直接算出表格延后状态。它用来和真正的增量扫描器对照，确认逐块扫描不会扫错。

数据流：进去是一整段 source → 它先用 parse_lines_with_fence_state 得到每行及其代码块环境；再两行两行查看是否有“表头行 + 分隔线行”，并跳过普通代码块里的内容。找到就返回 Confirmed 和表格起点；如果没找到，就看最后一个非空行是否像表头，像的话返回 PendingHeader；否则返回 None → 出来是一个 TableHoldbackState，不改动外部状态。

调用关系：它是测试里的参照答案生成器。它调用 table_candidate_text、is_table_header_line 和 is_table_delimiter_line 来复用正式逻辑里的判断标准，帮助测试证明 TableHoldbackScanner 的增量结果和完整扫描结果一致。

调用图：调用 4 个内部函数（parse_lines_with_fence_state, table_candidate_text, is_table_delimiter_line, is_table_header_line）。

fn should_render_records(
    rows: &[Vec<TableCell>],
    column_widths: &[usize],
    metrics: &[TableColumnMetrics],
) -> bool

作用：判断一个表格是否应该放弃传统网格样式，改用竖排的“记录”样式。有人会在真正渲染表格前调用它，避免把已经挤坏的表格继续画成难读的网格。

数据流：输入是一批表格行、每列当前分到的宽度、以及每列内容类型的统计信息。它逐行检查：有没有词比列宽还长，或者有没有长文本列被压得换了很多行。最后它数一数受影响的行够不够多；如果够多，就输出 true，表示该换成竖排记录；否则输出 false，不改动原数据。

调用关系：它由 render_table_lines 在决定表格怎么画时调用。它相当于排版前的“体检员”：如果发现网格显示已经不健康，就建议后续交给 render_records 来画竖排版本；检查长文本是否被严重挤压时，会用到 expansive_cells_are_starved 这个内部判断。

调用图：被 1 处调用（render_table_lines）。

fn expansive_cells_are_starved(
    row: &[TableCell],
    column_widths: &[usize],
    metrics: &[TableColumnMetrics],
) -> bool

作用：检查一行里那些本来需要较大空间的单元格，是否被列宽挤得太厉害。这里的“expansive”可以理解为内容比较展开的列，比如长句子或大量文字，不适合塞进很窄的小格子。

数据流：输入是一行单元格、各列宽度、各列类型。它只关注非紧凑列，把每个单元格按当前宽度试着换行，然后看换出来的行数是否过多。若一行里有多个展开型单元格都变得很高，或者叙述型文字在很窄的宽度下变成灾难性多行，它就返回 true；否则返回 false。

调用关系：它在 should_render_records 的判断过程中充当更细的检查项。should_render_records 先看有没有被切碎的长词，再靠它判断长文本列是否已经被挤成难读的竖条。它自己主要做遍历和估算，不负责最终渲染。

调用图：外部调用 1 个（iter）。

fn render_records(
    headers: &[TableCell],
    rows: &[Vec<TableCell>],
    metrics: &[TableColumnMetrics],
    available_width: Option<usize>,
    label_style: Style,
    separator_style: Style,
)

作用：把整张表格真正画成竖排记录样式。它把每个表头当作字段名，把每个单元格当作字段值，让窄屏下的表格仍然能一项一项读清楚。

数据流：输入是表头、数据行、列类型统计、可用宽度，以及字段名和分隔线的样式。它先算字段名最长有多宽，再判断屏幕是否足够把字段名和值左右对齐。如果够宽，就逐项调用 render_aligned_field；如果不够，就调用 render_stacked_field。每两条记录之间，它会加一条横向分隔线。输出是一组带样式、也可能带超链接信息的终端文本行。

调用关系：它由 render_table_lines 在决定使用竖排表格时调用，是这个文件里的主渲染入口。它不亲自处理每个字段的细节，而是根据宽度把工作分给 render_aligned_field 或 render_stacked_field；最后还会借助 widest_line_width 在没有固定宽度时决定分隔线该画多长。

调用图：调用 3 个内部函数（render_aligned_field, render_stacked_field, new）；被 1 处调用（render_table_lines）；外部调用 5 个（from, styled, new, iter, iter）。

fn render_aligned_field(
    out: &mut Vec<HyperlinkLine>,
    header: &TableCell,
    value: &TableCell,
    label_width: usize,
    available_width: Option<usize>,
    label_style: Style,
)

作用：在空间比较够的时候，把一个字段画成“字段名在左、字段值在右”的对齐形式。这样读起来像整齐的清单，字段名上下对齐，值也从同一列开始。

数据流：输入是输出列表、一个表头、一个值、字段名统一宽度、可用总宽度和字段名样式。它先算出字段值应该从第几列开始，再把值按剩余宽度换行。第一行会放缩进、字段名和间隔；后续换行只放同样宽度的空白，让值继续对齐。最终它把生成的行追加到输出列表里。

调用关系：它由 render_records 在判断“宽度够对齐显示”时调用。它会调用 wrap_cell 给字段值换行，并把每一行交给 push_prefixed_value_line；后者负责把前缀空格和内容拼起来，同时修正超链接位置。

调用图：调用 3 个内部函数（plain_text, push_prefixed_value_line, wrap_cell）；被 1 处调用（render_records）；外部调用 3 个（raw, styled, new）。

fn render_stacked_field(
    out: &mut Vec<HyperlinkLine>,
    header: &TableCell,
    value: &TableCell,
    available_width: Option<usize>,
    label_style: Style,
)

作用：在空间太窄时，把一个字段画成上下两段：先显示字段名，再缩进显示字段值。这样虽然不如左右对齐紧凑，但不会把内容硬挤到看不懂。

数据流：输入是输出列表、表头、值、可用宽度和字段名样式。它先按可用宽度把字段名自己换行，并在前面加一点缩进；然后再把字段值按更窄的宽度换行，并用更深的缩进显示。它把这些生成的行依次追加到输出列表里。

调用关系：它由 render_records 在宽度不足以左右对齐时调用。字段名换行时会用 word_wrap_line 和 push_owned_lines，字段值换行时会用 wrap_cell；每一行值最后交给 push_prefixed_value_line 来拼接缩进并维护链接位置。

调用图：调用 7 个内部函数（plain_text, push_prefixed_value_line, wrap_cell, push_owned_lines, new, new, word_wrap_line）；被 1 处调用（render_records）；外部调用 4 个（from, styled, new, vec!）。

fn push_prefixed_value_line(
    out: &mut Vec<HyperlinkLine>,
    mut prefix: Vec<Span<'static>>,
    mut value_line: HyperlinkLine,
)

作用：把一段前缀，比如空格缩进或字段名，占位加到一行值内容前面。它的重要点是：加了前缀以后，超链接所在的列也要整体往后挪，否则链接会点错地方。

数据流：输入是输出列表、一组前缀文本片段，以及一行已经带有内容和超链接信息的值。它先算前缀总共占几列宽，再把前缀和原来的值内容拼成一行。然后它把原有每个超链接的起止列都加上这个偏移量。最后把修正后的新行追加到输出列表。

调用关系：它被 render_aligned_field 和 render_stacked_field 共同使用，是两种排版方式共享的小工具。上游负责决定前面要加什么；它负责安全地拼起来，并保证终端超链接不会因为缩进或标签而错位。

调用图：调用 1 个内部函数（new）；被 2 处调用（render_aligned_field, render_stacked_field）；外部调用 1 个（from）。

fn wrap_cell(cell: &TableCell, width: usize) -> Vec<HyperlinkLine>

作用：把一个表格单元格按指定宽度换成多行，同时尽量保留原来的样式和超链接。简单说，它就是给单元格内容做“自动换行”的地方。

数据流：输入是一个单元格和目标宽度。如果单元格没有内容，它会返回一行空行。否则它会逐条处理单元格里的原始行，用 word_wrap_line 按宽度切成多行，再把这些新行转换成可长期保存的文本，并用 remap_wrapped_line 重新对应原来的超链接范围。输出是换好行的一组 HyperlinkLine；如果结果为空，也会补一行空行。

调用关系：它被 render_aligned_field、render_stacked_field 用来处理字段值，也被 expansive_cells_are_starved 用来估算某个单元格在当前列宽下会变多高。它把底层换行函数和超链接重映射函数串起来，让上层不必关心这些细节。

调用图：调用 4 个内部函数（new, remap_wrapped_line, new, word_wrap_line）；被 2 处调用（render_aligned_field, render_stacked_field）；外部调用 3 个（default, new, vec!）。

fn cell_width(cell: &TableCell) -> usize

作用：计算一个单元格原始内容中最宽的一行有多宽。这个宽度常用于没有外部宽度限制时，给内容一个合适的显示宽度。

数据流：输入是一个单元格。它查看单元格里的每一行，把这一行里所有文字片段的显示宽度加起来，再从所有行里取最大值。输出是这个最大宽度；如果单元格没有行，就输出 0。它不修改任何内容。

调用关系：它被渲染函数用作宽度估算，特别是在没有给定 available_width 时，render_aligned_field 和 render_stacked_field 需要靠它知道值大概应该占多宽。它是一个安静的测量工具，只负责量尺寸。

fn widest_line_width(lines: &[HyperlinkLine]) -> usize

作用：计算一组已经渲染好的终端文本行里，最宽的一行有多宽。它主要用来决定分隔线应该画多长。

数据流：输入是一组 HyperlinkLine。它逐行把这一行所有文字片段的显示宽度加起来，然后取最大值。输出是最宽行的宽度；如果没有任何行，就输出 0。它不改变这些行本身。

调用关系：它在 render_records 里用于没有固定可用宽度的情况。当两条竖排记录之间需要画分隔线时，render_records 会请它量一下当前已经生成的内容有多宽，再按这个宽度生成分隔线。

调用图：外部调用 1 个（iter）。

fn syntax_set() -> &'static SyntaxSet

作用：拿到全程序共用的“语言规则库”。这个库知道 Rust、Python、Markdown 等代码该怎么拆成不同语法部分。

数据流：没有外部输入 → 如果规则库还没建，就从 two_face 初始化一份；如果已经有了，就直接复用 → 返回同一份只读的语法规则库，不改别的数据。

调用关系：find_syntax 用它查某个语言名能不能识别；highlight_to_line_spans_with_theme 在真正高亮每一行时也用它给 syntect 提供规则。

调用图：被 2 处调用（find_syntax, highlight_to_line_spans_with_theme）。

fn set_theme_override(
    name: Option<String>,
    codex_home: Option<PathBuf>,
) -> Option<String>

作用：在启动时记住用户配置的主题名和配置目录，并尽量立刻应用这个主题。它还能返回给用户看的警告，比如主题名写错了。

数据流：输入一个可选主题名和可选配置目录 → 先检查主题是否存在，再把这两个设置写进只能初始化一次的全局槽；如果当前主题已经初始化，还会马上切换运行中的主题 → 输出可能的警告文字，并可能改变当前主题。

调用关系：run_ratatui_app 在应用启动、配置最终确定后调用它；它内部会请 validate_theme_name 检查名字，请 resolve_theme_with_override 找到实际主题，必要时交给 set_syntax_theme 切换。

调用图：调用 3 个内部函数（resolve_theme_with_override, set_syntax_theme, validate_theme_name）；被 1 处调用（run_ratatui_app）；外部调用 1 个（debug!）。

fn validate_theme_name(name: Option<&str>, codex_home: Option<&Path>) -> Option<String>

作用：检查用户写的主题名是不是可用。可用就安静返回，不可用就生成一段容易理解的提示。

数据流：输入可选主题名和配置目录 → 没写主题就不管；先看是不是内置主题，再看配置目录里有没有同名 .tmTheme 文件并且能不能读 → 输出 None 表示没问题，或输出一段警告文字。

调用关系：set_theme_override 启动时用它提前发现配置错误；测试也专门用它确认缺文件、坏文件、内置主题等情况的提示是否正确。

调用图：调用 3 个内部函数（custom_theme_path, load_custom_theme, parse_theme_name）；被 3 处调用（set_theme_override, validate_theme_name_warns_for_missing_custom, validate_theme_name_warns_when_custom_file_is_invalid）；外部调用 1 个（format!）。

fn parse_theme_name(name: &str) -> Option<EmbeddedThemeName>

作用：把用户写的短横线风格主题名，比如 dracula，翻译成程序内部的内置主题编号。

数据流：输入一个字符串主题名 → 在固定名单里逐个匹配 → 匹配到就返回对应内置主题，匹配不到就返回 None。

调用关系：配置检查、主题解析、当前配置主题名判断都会用它；它是内置主题名字和 two_face 内部枚举之间的翻译表。

调用图：被 4 处调用（configured_theme_name, resolve_theme_by_name, resolve_theme_with_override, validate_theme_name）。

fn custom_theme_path(name: &str, codex_home: &Path) -> PathBuf

作用：拼出自定义主题文件应该放在哪里。规则是配置目录下面的 themes/{名字}.tmTheme。

数据流：输入主题名和 codex_home 路径 → 拼接 themes 子目录和文件名 → 返回完整文件路径。

调用关系：load_custom_theme 用它去读文件；validate_theme_name 用它生成提示里的路径，让用户知道该把文件放到哪。

调用图：被 2 处调用（load_custom_theme, validate_theme_name）；外部调用 2 个（join, format!）。

fn load_custom_theme(name: &str, codex_home: &Path) -> Option<Theme>

作用：尝试从磁盘读取用户自定义的 .tmTheme 主题文件。

数据流：输入主题名和配置目录 → 先用 custom_theme_path 找到文件，再交给 syntect 的 ThemeSet 解析 → 成功返回主题对象，失败返回 None。

调用关系：主题解析和配置检查都会用它；测试用它确认有效文件能加载、缺失文件不会误判成功。

调用图：调用 1 个内部函数（custom_theme_path）；被 5 处调用（configured_theme_name, resolve_theme_by_name, resolve_theme_with_override, load_custom_theme_from_tmtheme_file, validate_theme_name）；外部调用 1 个（get_theme）。

fn adaptive_default_theme_selection() -> (EmbeddedThemeName, &'static str)

作用：自动选择默认主题：终端背景亮就用浅色主题，背景暗就用深色主题。

数据流：读取当前终端默认背景色 → 判断背景是不是偏亮 → 返回内置主题编号和对应的配置名。

调用关系：adaptive_default_embedded_theme_name 和 adaptive_default_theme_name 都从它拿结果；这样默认主题既能用于真正加载，也能用于界面显示名字。

调用图：调用 2 个内部函数（is_light, default_bg）；被 2 处调用（adaptive_default_embedded_theme_name, adaptive_default_theme_name）。

fn adaptive_default_embedded_theme_name() -> EmbeddedThemeName

作用：拿到自动默认主题的内部编号，用来真正加载主题。

数据流：没有输入 → 调用 adaptive_default_theme_selection → 返回内置主题枚举值。

调用关系：resolve_theme_with_override 在用户没有有效主题时调用它，作为兜底选择。

调用图：调用 1 个内部函数（adaptive_default_theme_selection）；被 1 处调用（resolve_theme_with_override）。

fn adaptive_default_theme_name() -> &'static str

作用：拿到自动默认主题的文字名字，比如 catppuccin-mocha 或 catppuccin-latte。

数据流：没有输入 → 调用 adaptive_default_theme_selection → 返回短横线风格的主题名字符串。

调用关系：configured_theme_name 用它告诉界面当前配置最终会落到哪个默认主题；恢复运行时主题的流程也会用它。

调用图：调用 1 个内部函数（adaptive_default_theme_selection）；被 2 处调用（restore_runtime_theme_from_config, configured_theme_name）。

fn resolve_theme_with_override(name: Option<&str>, codex_home: Option<&Path>) -> Theme

作用：根据用户配置和默认规则，真正选出要用的主题对象。

数据流：输入可选主题名和配置目录 → 先试内置主题，再试自定义 .tmTheme 文件；都不行就记录调试信息并选自动默认主题 → 返回一个可直接用于高亮的 Theme。

调用关系：build_default_theme 初始化全局主题时用它；set_theme_override 在启动或预览时也用它把配置转成实际主题。

调用图：调用 3 个内部函数（adaptive_default_embedded_theme_name, load_custom_theme, parse_theme_name）；被 2 处调用（build_default_theme, set_theme_override）；外部调用 2 个（debug!, extra）。

fn build_default_theme() -> Theme

作用：根据已经保存的全局配置，构建当前默认主题。

数据流：读取 THEME_OVERRIDE 和 CODEX_HOME 里的值 → 交给 resolve_theme_with_override 解析 → 返回主题对象。

调用关系：theme_lock 第一次创建全局主题锁时会调用它；它把启动时保存的配置接到运行时主题系统里。

调用图：调用 1 个内部函数（resolve_theme_with_override）。

fn theme_lock() -> &'static RwLock<Theme>

作用：拿到保护当前主题的读写锁。读写锁就是一把允许多人读、但写时独占的锁，避免主题切换和高亮同时把数据弄乱。

数据流：没有输入 → 如果全局主题锁还没创建，就用 build_default_theme 创建；否则直接复用 → 返回全局 RwLock<Theme>。

调用关系：current_syntax_theme 读它，set_syntax_theme 写它，highlight_to_line_spans 在高亮时也读它。

调用图：被 3 处调用（current_syntax_theme, highlight_to_line_spans, set_syntax_theme）。

fn set_syntax_theme(theme: Theme)

作用：运行中切换当前语法高亮主题，主要用于主题选择器的即时预览。

数据流：输入一个 Theme → 获取主题写锁；如果锁曾因异常被污染，也尽量取回里面的数据 → 用新主题替换旧主题，没有返回值。

调用关系：set_theme_override、事件处理和恢复配置主题的流程都会调用它；它是实际改变全局主题的地方。

调用图：调用 1 个内部函数（theme_lock）；被 3 处调用（restore_runtime_theme_from_config, handle_event, set_theme_override）。

fn current_syntax_theme() -> Theme

作用：复制一份当前正在使用的语法主题，方便别人查看或临时保存。

数据流：没有输入 → 获取主题读锁；如果锁被污染也继续读取 → 返回当前 Theme 的克隆，不改全局主题。

调用关系：diff_scope_background_rgbs 和 foreground_style_for_scopes 用它读取颜色；主题选择器也用它保存当前状态，方便取消时恢复。

调用图：调用 1 个内部函数（theme_lock）；被 3 处调用（diff_scope_background_rgbs, foreground_style_for_scopes, build_theme_picker_params）。

fn diff_scope_background_rgbs() -> DiffScopeBackgroundRgbs

作用：从当前主题里找 diff 增加行和删除行的背景色。diff 就是代码改动对比。

数据流：没有输入 → 复制当前主题 → 交给 diff_scope_background_rgbs_for_theme 分析 → 返回插入和删除背景色，可能都没有。

调用关系：resolve_diff_backgrounds 调用它来决定改动预览的底色；它把全局主题读取和纯粹颜色提取分开。

调用图：调用 2 个内部函数（current_syntax_theme, diff_scope_background_rgbs_for_theme）；被 1 处调用（resolve_diff_backgrounds）。

fn diff_scope_background_rgbs_for_theme(theme: &Theme) -> DiffScopeBackgroundRgbs

作用：从指定主题里提取“新增”和“删除”两类代码范围的背景色。

数据流：输入一个主题 → 建立 highlighter（按主题查样式的小工具），优先查 markup.inserted/deleted，再查 diff.inserted/deleted → 返回两个可选 RGB 颜色。

调用关系：diff_scope_background_rgbs 用它处理当前主题；多组测试用它验证内置主题、自定义主题、回退规则都正常。

调用图：调用 1 个内部函数（scope_background_rgb）；被 5 处调用（diff_scope_background_rgbs, bundled_theme_can_provide_diff_scope_backgrounds, custom_tmtheme_diff_scope_backgrounds_are_resolved, diff_scope_backgrounds_prefer_markup_scope_then_diff_fallback, diff_scope_backgrounds_return_none_when_no_background_scope_matches）；外部调用 1 个（new）。

fn scope_background_rgb(highlighter: &Highlighter<'_>, scope_name: &str) -> Option<(u8, u8, u8)>

作用：查询某一个 TextMate scope 的背景色。scope 可以理解为主题里给某类语法区域起的标签。

数据流：输入 highlighter 和 scope 名 → 先把名字解析成 Scope，再问主题这个标签有没有背景色 → 有就返回 RGB 三元组，没有或解析失败就返回 None。

调用关系：diff_scope_background_rgbs_for_theme 用它分别查询新增、删除相关标签。

调用图：被 1 处调用（diff_scope_background_rgbs_for_theme）；外部调用 2 个（style_mod_for_stack, new）。

fn foreground_style_for_scopes(scope_names: &[&str]) -> Option<Style>

作用：从当前主题里找一组 scope 中第一个可用的前景色，并转成终端样式。

数据流：输入多个 scope 名 → 读取当前主题 → 交给 foreground_style_for_scopes_with_theme 查找 → 返回可选的 ratatui Style。

调用关系：表格、标签、数字和活动状态等界面组件会调用它，让普通 UI 颜色也能跟语法主题协调。

调用图：调用 2 个内部函数（current_syntax_theme, foreground_style_for_scopes_with_theme）；被 4 处调用（label_style, numeric_style, theme_activity_style, render_table_lines）。

fn foreground_style_for_scopes_with_theme(theme: &Theme, scope_names: &[&str]) -> Option<Style>

作用：在指定主题里按顺序查找 scope 的文字颜色。

数据流：输入主题和 scope 名列表 → 逐个解析 scope，并查询主题有没有前景色；找到第一个就转换成 ratatui 样式 → 返回样式或 None。

调用关系：foreground_style_for_scopes 用它处理当前主题；测试用它确认能读取匹配 scope，也会按输入顺序选择第一个有颜色的 scope。

调用图：被 3 处调用（foreground_style_for_scopes, foreground_style_for_scopes_reads_matching_theme_scope, foreground_style_for_scopes_uses_first_scope_with_foreground）；外部调用 1 个（new）。

fn configured_theme_name() -> String

作用：告诉界面“配置上最终算哪个主题”。它看的是持久配置，不看临时预览切换。

数据流：读取全局保存的主题名和配置目录 → 如果用户配置的内置或自定义主题有效，就返回它；否则返回自动默认主题名 → 输出一个字符串。

调用关系：主题选择器参数构建会用它决定当前选中项；相关测试确保坏配置会回到默认显示。

调用图：调用 3 个内部函数（adaptive_default_theme_name, load_custom_theme, parse_theme_name）；被 2 处调用（build_theme_picker_params, unavailable_configured_theme_falls_back_to_configured_or_default_selection）。

fn resolve_theme_by_name(name: &str, codex_home: Option<&Path>) -> Option<Theme>

作用：按名字查找主题，既支持内置主题，也支持配置目录里的自定义主题。

数据流：输入主题名和可选配置目录 → 先按内置主题解析，再尝试加载自定义 .tmTheme → 成功返回 Theme，失败返回 None。

调用关系：主题选择器事件和从配置恢复主题都会用它；测试也用它拿到指定主题来检查颜色行为。

调用图：调用 2 个内部函数（load_custom_theme, parse_theme_name）；被 6 处调用（restore_runtime_theme_from_config, handle_event, ansi_family_themes_use_terminal_palette_colors_not_rgb, bundled_theme_can_provide_diff_scope_backgrounds, custom_tmtheme_diff_scope_backgrounds_are_resolved, unique_foreground_colors_for_theme）；外部调用 1 个（extra）。

fn list_available_themes(codex_home: Option<&Path>) -> Vec<ThemeEntry>

作用：列出主题选择器里能选的所有主题，包括内置主题和有效的自定义主题。

数据流：输入可选配置目录 → 先放入全部内置主题；再扫描 themes 目录，只加入能成功解析且不重名的 .tmTheme 文件 → 返回按名字稳定排序的 ThemeEntry 列表。

调用关系：build_theme_picker_params 调用它生成主题选择界面；测试确认坏主题文件不会出现、不同文件系统下排序也稳定。

调用图：被 3 处调用（list_available_themes_excludes_invalid_custom_files, list_available_themes_returns_stable_sorted_order, build_theme_picker_params）；外部调用 2 个（get_theme, read_dir）。

fn ansi_palette_color(index: u8) -> RtColor

作用：把 ANSI 调色板编号变成终端颜色。ANSI 是终端常用的一套基础颜色编号。

数据流：输入 0 到 255 的颜色编号 → 0 到 7 转成 Black、Red 等命名颜色，其他转成 Indexed 编号色 → 返回 ratatui 颜色。

调用关系：convert_syntect_color 在遇到特殊 ANSI 主题编码时调用它，保证终端主题能按终端自己的调色板显示。

调用图：被 1 处调用（convert_syntect_color）；外部调用 1 个（Indexed）。

fn convert_syntect_color(color: SyntectColor) -> Option<RtColor>

作用：把 syntect 的颜色格式转换成 ratatui 的终端颜色格式，并理解一些主题用透明度字段塞进去的特殊含义。

数据流：输入 syntect Color → 如果 alpha 是 0，就把 r 当 ANSI 调色板编号；alpha 是 1，就表示用终端默认色；alpha 是 255 或其他值，就当普通 RGB → 返回可选终端颜色。

调用关系：convert_style 用它转换前景色；这是 ANSI/base16 主题不被错误当成普通 RGB 的关键。

调用图：调用 1 个内部函数（ansi_palette_color）；被 1 处调用（convert_style）；外部调用 1 个（Rgb）。

fn convert_style(syn_style: SyntectStyle) -> Style

作用：把 syntect 给出的完整样式转换成终端界面能画的样式。

数据流：输入 syntect Style → 转换前景色，故意忽略背景色；如果有粗体就保留，斜体和下划线故意丢掉 → 返回 ratatui Style。

调用关系：highlight_to_line_spans_with_theme 给每段代码文字上样式时调用它；测试覆盖颜色、粗体、斜体和下划线的取舍。

调用图：调用 1 个内部函数（convert_syntect_color）；被 7 处调用（highlight_to_line_spans_with_theme, convert_style_suppresses_underline, style_conversion_correctness, style_conversion_unexpected_alpha_falls_back_to_rgb, style_conversion_uses_ansi_named_color_when_alpha_is_zero_low_index, style_conversion_uses_indexed_color_when_alpha_is_zero_high_index, style_conversion_uses_terminal_default_when_alpha_is_one）；外部调用 1 个（default）。

fn find_syntax(lang: &str) -> Option<&'static SyntaxReference>

作用：根据用户传入的语言名或文件扩展名，找到对应的语法规则。

数据流：输入 lang 字符串 → 先修正常见别名，比如 golang 变 go、python3 变 python；再按 token、正式名称、忽略大小写名称、扩展名依次查找 → 返回语法引用或 None。

调用关系：highlight_to_line_spans_with_theme 在高亮前必须先调用它；如果找不到，外层会退回普通文本显示。

调用图：调用 1 个内部函数（syntax_set）；被 1 处调用（highlight_to_line_spans_with_theme）。

fn exceeds_highlight_limits(total_bytes: usize, total_lines: usize) -> bool

作用：快速判断一批内容是否太大，不适合做语法高亮。

数据流：输入总字节数和总行数 → 和 512KB、10000 行两个上限比较 → 返回 true 表示应该跳过高亮。

调用关系：render_change 在处理 diff 改动时用它提前做总量检查，避免逐行高亮时浪费资源。

调用图：被 1 处调用（render_change）。

fn highlight_to_line_spans_with_theme(
    code: &str,
    lang: &str,
    theme: &Theme,
) -> Option<Vec<Vec<Span<'static>>>>

作用：这是核心高亮函数：用指定主题把代码拆成一行行带样式的小片段。

数据流：输入代码、语言名和主题 → 空文本、过大文本、未知语言都返回 None；否则逐行让 syntect 标色，去掉换行符和 Windows 的回车符，把每段文字转成 Span → 返回每行的 Span 列表。

调用关系：highlight_to_line_spans 调它处理正式路径；一些测试直接传指定主题进来，避免改全局主题。

调用图：调用 3 个内部函数（convert_style, find_syntax, syntax_set）；被 3 处调用（highlight_to_line_spans, ansi_family_themes_use_terminal_palette_colors_not_rgb, unique_foreground_colors_for_theme）；外部调用 6 个（new, from, raw, styled, new, new）。

fn highlight_to_line_spans(code: &str, lang: &str) -> Option<Vec<Vec<Span<'static>>>>

作用：用当前全局主题高亮代码，并返回每行的样式片段。

数据流：输入代码和语言名 → 读取当前主题锁 → 调用 highlight_to_line_spans_with_theme → 返回高亮结果或 None。

调用关系：highlight_code_to_lines 和 highlight_code_to_styled_spans 都通过它使用统一的高亮逻辑。

调用图：调用 2 个内部函数（highlight_to_line_spans_with_theme, theme_lock）；被 2 处调用（highlight_code_to_lines, highlight_code_to_styled_spans）。

fn highlight_code_to_lines(code: &str, lang: &str) -> Vec<Line<'static>>

作用：给普通代码块生成可以直接渲染的终端 Line。失败时也会返回无样式文本，调用方不用自己兜底。

数据流：输入代码和语言名 → 先尝试高亮；成功就把 Span 组装成 Line；失败就按普通文本逐行生成 Line，空输入也保证有一行 → 返回 Line 列表。

调用关系：Markdown 代码块渲染和 bash 命令显示都用它；highlight_bash_to_lines 只是固定语言为 bash 后转调它。

调用图：调用 1 个内部函数（highlight_to_line_spans）；被 9 处调用（end_codeblock, highlight_bash_to_lines, fallback_trailing_newline_no_phantom_line, highlight_crlf_strips_carriage_return, highlight_empty_string, highlight_markdown_preserves_content, highlight_multiline_python, highlight_rust_has_keyword_style, highlight_unknown_lang_falls_back）；外部调用 2 个（from, new）。

fn highlight_bash_to_lines(script: &str) -> Vec<Line<'static>>

作用：专门给 bash 脚本上色的便捷入口。

数据流：输入脚本文本 → 调用 highlight_code_to_lines，并把语言固定为 bash → 返回可渲染的 Line 列表。

调用关系：命令头、命令展示、会话记录等地方用它显示 shell 命令；它避免各处重复写语言名。

调用图：调用 1 个内部函数（highlight_code_to_lines）；被 4 处调用（build_header, command_display_lines, transcript_lines, highlight_bash_preserves_content）。

fn highlight_code_to_styled_spans(
    code: &str,
    lang: &str,
) -> Option<Vec<Vec<Span<'static>>>>

作用：给 diff 等更复杂的渲染场景提供按行分好的高亮片段，而不是完整 Line。

数据流：输入代码和语言名 → 调用 highlight_to_line_spans → 成功返回每行 Span，失败返回 None，让调用方改用自己的普通 diff 着色。

调用关系：diff 预览和相关快照测试会调用它；它让 diff 渲染能把语法颜色和增删行颜色组合起来。

调用图：调用 1 个内部函数（highlight_to_line_spans）；被 8 处调用（ui_snapshot_syntax_highlighted_insert_wraps, ui_snapshot_syntax_highlighted_insert_wraps_text, update_diff_preserves_multiline_highlight_state_within_hunk, highlight_code_to_styled_spans_returns_some_for_known, highlight_large_input_falls_back, highlight_many_lines_falls_back, highlight_many_lines_no_trailing_newline_falls_back, render_preview）。

fn write_minimal_tmtheme(path: &Path)

作用：测试辅助函数，写出一个最小但有效的 .tmTheme 文件。

数据流：输入文件路径 → 写入一段简单的 XML plist 主题内容 → 文件系统里多出一个可被 syntect 解析的主题文件。

调用关系：自定义主题加载和主题列表测试用它快速搭建临时主题文件。

调用图：外部调用 1 个（write）。

fn write_tmtheme_with_diff_backgrounds(
        path: &Path,
        inserted_scope: &str,
        inserted_background: &str,
        deleted_scope: &str,
        deleted_background: &str,
    )

作用：测试辅助函数，写出带有 diff 背景色设置的自定义主题。

数据流：输入路径、插入/删除 scope 名和颜色字符串 → 拼成 .tmTheme XML 并写入磁盘 → 得到一个可测试 diff 颜色提取的主题文件。

调用关系：custom_tmtheme_diff_scope_backgrounds_are_resolved 用它创建测试材料，再验证解析出的新增/删除颜色正确。

调用图：外部调用 2 个（format!, write）。

fn reconstructed(lines: &[Line<'static>]) -> String

作用：把高亮后的 Line 重新拼回纯文本，用来确认高亮没有改坏内容。

数据流：输入 Line 列表 → 逐个取出 Span 的文字内容并按行用换行符连接 → 返回重建后的字符串。

调用关系：多个测试用它比较原文和高亮后的文本，确保上色只加样式、不改文字。

调用图：外部调用 1 个（iter）。

fn unique_foreground_colors_for_theme(theme_name: &str) -> Vec<String>

作用：测试辅助函数，收集某个主题高亮 Rust 示例时用到的所有前景色。

数据流：输入主题名 → 解析主题，调用核心高亮函数高亮一段 Rust 代码，收集每个 Span 的前景色并去重排序 → 返回颜色描述列表。

调用关系：ANSI 调色板快照测试用它观察 ansi、base16 等主题实际产生哪些终端颜色。

调用图：调用 2 个内部函数（highlight_to_line_spans_with_theme, resolve_theme_by_name）。

fn theme_item(scope: &str, background: Option<(u8, u8, u8)>) -> ThemeItem

作用：测试辅助函数，构造一个带背景色的主题规则。

数据流：输入 scope 名和可选 RGB 背景色 → 解析 scope，并填进 syntect 的 ThemeItem 结构 → 返回可放进测试主题的规则。

调用关系：diff 背景色提取测试用它手工搭主题，不需要真实主题文件。

调用图：外部调用 2 个（from_str, default）。

fn theme_item_with_foreground(scope: &str, foreground: (u8, u8, u8)) -> ThemeItem

作用：测试辅助函数，构造一个带前景色的主题规则。

数据流：输入 scope 名和 RGB 前景色 → 解析 scope，并填入 ThemeItem 的 foreground 字段 → 返回测试用主题规则。

调用关系：foreground_style_for_scopes 相关测试用它制造可控的颜色规则。

调用图：外部调用 2 个（from_str, default）。

fn assert_rgb(color: Option<RtColor>, expected: (u8, u8, u8))

作用：测试辅助断言，确认一个可选终端颜色正好是指定 RGB。

数据流：输入可选颜色和期望 RGB → 如果不是 RGB 就直接让测试失败；如果是 RGB 就比较三个通道 → 没有返回值，只在不符合时失败。

调用关系：前景色读取测试用它把颜色检查写得更清楚。

调用图：外部调用 2 个（assert_eq!, panic!）。

fn highlight_rust_has_keyword_style()

作用：测试 Rust 代码能被识别，并且关键字 fn 真的有样式。

数据流：准备一段 Rust 代码 → 调用 highlight_code_to_lines，再重建文本和查找 fn 片段 → 断言内容不变且 fn 不是默认样式。

调用关系：它覆盖从公共入口到语法识别、样式转换的基本成功路径。

调用图：调用 1 个内部函数（highlight_code_to_lines）；外部调用 2 个（assert!, assert_eq!）。

fn highlight_unknown_lang_falls_back()

作用：测试未知语言不会报错，而是退回普通文本。

数据流：输入随便的文本和不存在的语言名 → 调用 highlight_code_to_lines → 断言文字不变，所有 Span 都没有样式。

调用关系：它验证 find_syntax 找不到语言时，公共接口的兜底行为可靠。

调用图：调用 1 个内部函数（highlight_code_to_lines）；外部调用 1 个（assert_eq!）。

fn fallback_trailing_newline_no_phantom_line()

作用：测试普通文本兜底时，末尾换行不会多生成一行空白。

数据流：输入以换行结尾的未知语言代码 → 调用 highlight_code_to_lines → 断言只得到一行 hello world。

调用关系：它保护 Markdown 代码块等上游传入尾随换行时的显示效果。

调用图：调用 1 个内部函数（highlight_code_to_lines）；外部调用 1 个（assert_eq!）。

fn highlight_empty_string()

作用：测试空字符串也能产生一行空 Line，而不是完全没有内容。

数据流：输入空代码和 rust 语言 → 调用 highlight_code_to_lines → 断言结果长度为 1，重建文本为空。

调用关系：它确保渲染层收到空代码块时仍有稳定的结构可画。

调用图：调用 1 个内部函数（highlight_code_to_lines）；外部调用 1 个（assert_eq!）。

fn highlight_bash_preserves_content()

作用：测试 bash 高亮不会改变命令文本。

数据流：输入一段 shell 命令 → 调用 highlight_bash_to_lines，再重建文本 → 断言和原命令完全一致。

调用关系：它覆盖 bash 便捷入口，并间接验证 highlight_code_to_lines 的内容保持能力。

调用图：调用 1 个内部函数（highlight_bash_to_lines）；外部调用 1 个（assert_eq!）。

fn highlight_crlf_strips_carriage_return()

作用：测试 Windows 风格换行里的回车符不会残留到显示文本中。

数据流：输入带 \r\n 的 Rust 代码 → 调用 highlight_code_to_lines → 检查每个 Span 内容都不含 \r。

调用关系：它保护 highlight_to_line_spans_with_theme 中去掉行尾换行符的逻辑。

调用图：调用 1 个内部函数（highlight_code_to_lines）；外部调用 1 个（assert!）。

fn style_conversion_correctness()

作用：测试基本样式转换：RGB 前景色和粗体保留，背景、斜体不保留。

数据流：构造一个 syntect Style → 调用 convert_style → 断言前景色、背景、粗体和斜体状态符合预期。

调用关系：它直接覆盖 convert_style 的设计取舍，防止终端显示变得花或难读。

调用图：调用 1 个内部函数（convert_style）；外部调用 2 个（assert!, assert_eq!）。

fn convert_style_suppresses_underline()

作用：测试主题里的下划线会被压掉。

数据流：构造一个带下划线的 syntect Style → 调用 convert_style → 断言输出样式没有下划线。

调用关系：它保护 Dracula 等主题下类型名不会在终端里出现大量干扰性下划线。

调用图：调用 1 个内部函数（convert_style）；外部调用 1 个（assert!）。

fn style_conversion_uses_ansi_named_color_when_alpha_is_zero_low_index()

作用：测试特殊 ANSI 编码的低编号颜色会转成命名颜色。

数据流：构造 alpha 为 0、r 为 2 的颜色 → 调用 convert_style → 断言前景色是 Green。

调用关系：它验证 convert_syntect_color 和 ansi_palette_color 对 ANSI 主题的兼容。

调用图：调用 1 个内部函数（convert_style）；外部调用 2 个（empty, assert_eq!）。

fn style_conversion_uses_indexed_color_when_alpha_is_zero_high_index()

作用：测试特殊 ANSI 编码的高编号颜色会转成 Indexed 颜色。

数据流：构造 alpha 为 0、r 为 0x9a 的颜色 → 调用 convert_style → 断言输出是 Indexed(0x9a)。

调用关系：它覆盖 8 到 255 号 ANSI 调色板颜色的转换路径。

调用图：调用 1 个内部函数（convert_style）；外部调用 2 个（empty, assert!）。

fn style_conversion_uses_terminal_default_when_alpha_is_one()

作用：测试 alpha 为 1 时表示“用终端默认颜色”。

数据流：构造 alpha 为 1 的前景色 → 调用 convert_style → 断言输出没有设置前景色。

调用关系：它保护 ANSI/base16 主题里“默认色”的特殊约定不被误当成黑色。

调用图：调用 1 个内部函数（convert_style）；外部调用 2 个（empty, assert_eq!）。

fn style_conversion_unexpected_alpha_falls_back_to_rgb()

作用：测试遇到不常见 alpha 值时仍按普通 RGB 处理。

数据流：构造 alpha 为 0x80 的颜色 → 调用 convert_style → 断言输出 RGB(10,20,30)。

调用关系：它让 convert_syntect_color 对非标准主题保持宽容。

调用图：调用 1 个内部函数（convert_style）；外部调用 2 个（empty, assert!）。

fn ansi_palette_color_maps_ansi_white_to_gray()

作用：测试 ANSI 里的白色编号 7 在 ratatui 中对应 Gray。

数据流：输入颜色编号 0x07 → 调用 ansi_palette_color → 断言结果是 RtColor::Gray。

调用关系：它固定低编号 ANSI 颜色的映射细节，避免显示行为被无意改掉。

调用图：外部调用 1 个（assert_eq!）。

fn ansi_family_themes_use_terminal_palette_colors_not_rgb()

作用：测试 ansi、base16、base16-256 这些主题不会产生普通 RGB 前景色。

数据流：逐个解析主题并高亮 Rust 示例 → 遍历所有 Span 的前景色 → 如果出现 RGB 就失败，同时确认至少有非默认颜色。

调用关系：它直接保护特殊 alpha 编码的解释逻辑，是防止上游主题格式变化的报警器。

调用图：调用 2 个内部函数（highlight_to_line_spans_with_theme, resolve_theme_by_name）；外部调用 2 个（assert!, panic!）。

fn ansi_family_foreground_palette_snapshot()

作用：生成 ANSI 系列主题前景色列表的快照，方便发现颜色输出变化。

数据流：遍历三个 ANSI 系列主题 → 收集去重后的前景色并拼成文本 → 用快照断言比较。

调用关系：它调用 unique_foreground_colors_for_theme，把颜色行为固定成可审查的测试快照。

调用图：外部调用 4 个（new, assert_snapshot!, format!, unique_foreground_colors_for_theme）。

fn highlight_multiline_python()

作用：测试多行 Python 代码高亮后仍保持三行和原文内容。

数据流：输入三行 Python 代码 → 调用 highlight_code_to_lines → 断言重建文本相同且行数为 3。

调用关系：它覆盖多行输入的正常高亮路径。

调用图：调用 1 个内部函数（highlight_code_to_lines）；外部调用 1 个（assert_eq!）。

fn highlight_code_to_styled_spans_returns_none_for_unknown()

作用：测试给 diff 用的 Span 接口遇到未知语言会返回 None。

数据流：输入代码 x 和不存在的语言名 → 检查 highlight_code_to_styled_spans 的结果 → 断言是 None。

调用关系：它确认 diff 渲染能通过 None 知道该走普通着色兜底。

调用图：外部调用 1 个（assert!）。

fn highlight_code_to_styled_spans_returns_some_for_known()

作用：测试给 diff 用的 Span 接口遇到已知语言会返回内容。

数据流：输入 Rust 片段 → 调用 highlight_code_to_styled_spans → 断言结果存在且不为空。

调用关系：它覆盖 diff 高亮接口的成功路径。

调用图：调用 1 个内部函数（highlight_code_to_styled_spans）；外部调用 1 个（assert!）。

fn highlight_markdown_preserves_content()

作用：测试 Markdown 内容高亮时不会破坏里面的反引号和换行文字。

数据流：输入一段包含围栏代码块文本的 Markdown → 调用 highlight_code_to_lines 并重建 → 断言与原文完全一致。

调用关系：它保护 Markdown 语法高亮只加样式、不重写内容。

调用图：调用 1 个内部函数（highlight_code_to_lines）；外部调用 2 个（assert_eq!, reconstructed）。

fn highlight_large_input_falls_back()

作用：测试超过 512KB 的输入会跳过高亮。

数据流：构造超大字符串 → 调用 highlight_code_to_styled_spans → 断言返回 None。

调用关系：它验证核心保护栏，防止大输入拖慢界面。

调用图：调用 1 个内部函数（highlight_code_to_styled_spans）；外部调用 1 个（assert!）。

fn highlight_many_lines_falls_back()

作用：测试超过 10000 行的输入会跳过高亮。

数据流：构造行数超限的 Rust 文本 → 调用 highlight_code_to_styled_spans → 断言返回 None。

调用关系：它保护按行数量限制资源消耗的逻辑。

调用图：调用 1 个内部函数（highlight_code_to_styled_spans）；外部调用 1 个（assert!）。

fn highlight_many_lines_no_trailing_newline_falls_back()

作用：测试没有末尾换行时，真实行数超限也能被发现。

数据流：构造 10001 行但最后一行不带换行的文本 → 先确认 lines() 计数，再调用高亮接口 → 断言返回 None。

调用关系：它防止用换行符数量粗略计数导致漏掉最后一行。

调用图：调用 1 个内部函数（highlight_code_to_styled_spans）；外部调用 2 个（assert!, assert_eq!）。

fn find_syntax_resolves_languages_and_aliases()

作用：测试常见语言、扩展名和手工修补的别名都能被识别。

数据流：遍历多组语言名、扩展名和别名 → 调用 find_syntax → 断言每个都能找到语法规则。

调用关系：它直接守住 find_syntax 的语言覆盖面，尤其是 csharp、golang、python3 等常见别名。

调用图：外部调用 1 个（assert!）。

fn diff_scope_backgrounds_prefer_markup_scope_then_diff_fallback()

作用：测试 diff 背景色优先用 markup.，没有时才用 diff.。

数据流：手工构造一个含 markup.inserted 和 diff.deleted 的主题 → 调用 diff_scope_background_rgbs_for_theme → 断言插入、删除颜色分别来自正确规则。

调用关系：它覆盖 diff_scope_background_rgbs_for_theme 的优先级设计。

调用图：调用 1 个内部函数（diff_scope_background_rgbs_for_theme）；外部调用 4 个（default, default, assert_eq!, vec!）。

fn diff_scope_backgrounds_return_none_when_no_background_scope_matches()

作用：测试主题没有相关 diff 背景色时会返回空结果。

数据流：构造一个只有普通 numeric scope 的主题 → 调用 diff_scope_background_rgbs_for_theme → 断言 inserted 和 deleted 都是 None。

调用关系：它确保 diff 渲染能知道主题没提供颜色，然后使用自己的默认调色。

调用图：调用 1 个内部函数（diff_scope_background_rgbs_for_theme）；外部调用 4 个（default, default, assert_eq!, vec!）。

fn foreground_style_for_scopes_reads_matching_theme_scope()

作用：测试能从主题里读到匹配 scope 的前景色。

数据流：构造 keyword 前景色为 (10,20,30) 的主题 → 调用 foreground_style_for_scopes_with_theme → 断言输出 RGB 正确。

调用关系：它覆盖普通 UI 借用语法主题颜色的基础能力。

调用图：调用 1 个内部函数（foreground_style_for_scopes_with_theme）；外部调用 4 个（default, default, assert_rgb, vec!）。

fn foreground_style_for_scopes_uses_first_scope_with_foreground()

作用：测试多个 scope 里会选择第一个真正有前景色的项。

数据流：构造只有 string 有颜色的主题 → 输入 keyword、string 两个候选 → 断言返回 string 的颜色。

调用关系：它保护 foreground_style_for_scopes_with_theme 的顺序查找规则。

调用图：调用 1 个内部函数（foreground_style_for_scopes_with_theme）；外部调用 4 个（default, default, assert_rgb, vec!）。

fn bundled_theme_can_provide_diff_scope_backgrounds()

作用：测试至少某个内置主题能提供 diff 增删背景色。

数据流：加载内置 github 主题 → 调用 diff_scope_background_rgbs_for_theme → 断言插入和删除颜色都存在。

调用关系：它验证内置主题和 diff 颜色提取逻辑能实际配合。

调用图：调用 2 个内部函数（diff_scope_background_rgbs_for_theme, resolve_theme_by_name）；外部调用 1 个（assert!）。

fn custom_tmtheme_diff_scope_backgrounds_are_resolved()

作用：测试自定义 .tmTheme 里的 diff 背景色能被正确解析。

数据流：创建临时 themes 目录并写入自定义 diff 主题 → 用 resolve_theme_by_name 加载，再提取背景色 → 断言 RGB 与文件中写的一致。

调用关系：它把自定义主题加载和 diff 颜色提取连起来测试。

调用图：调用 2 个内部函数（diff_scope_background_rgbs_for_theme, resolve_theme_by_name）；外部调用 4 个（assert_eq!, create_dir, tempdir, write_tmtheme_with_diff_backgrounds）。

fn parse_theme_name_covers_all_variants()

作用：测试每个已知内置主题名都能映射到正确的内部主题枚举。

数据流：遍历主题名和期望枚举的清单 → 调用 parse_theme_name → 逐项断言相等。

调用关系：它保护 parse_theme_name 这张手写映射表不被改错。

调用图：外部调用 1 个（assert_eq!）。

fn parse_theme_name_returns_none_for_unknown()

作用：测试未知主题名和空字符串不会被误认为内置主题。

数据流：输入 nonexistent-theme 和空字符串 → 调用 parse_theme_name → 断言都返回 None。

调用关系：它覆盖主题名解析的失败路径。

调用图：外部调用 1 个（assert_eq!）。

fn load_custom_theme_from_tmtheme_file()

作用：测试有效的自定义 .tmTheme 文件可以被加载。

数据流：创建临时 themes 目录并写入最小主题文件 → 调用 load_custom_theme → 断言返回 Some。

调用关系：它验证 custom_theme_path 和 syntect 主题解析能一起工作。

调用图：调用 1 个内部函数（load_custom_theme）；外部调用 4 个（assert!, create_dir, tempdir, write_minimal_tmtheme）。

fn load_custom_theme_returns_none_for_missing()

作用：测试自定义主题文件不存在时加载结果是 None。

数据流：创建空临时目录 → 尝试加载不存在的主题名 → 断言没有主题返回。

调用关系：它保护 load_custom_theme 的失败行为，避免缺文件被当成成功。

调用图：外部调用 2 个（assert!, tempdir）。

fn validate_theme_name_none_for_bundled()

作用：测试内置主题名不会产生警告。

数据流：输入 dracula、nord 等内置主题名 → 调用 validate_theme_name → 断言返回 None。

调用关系：它确认配置检查不会误吓用户。

调用图：外部调用 1 个（assert!）。

fn validate_theme_name_none_when_no_override()

作用：测试用户没有配置主题时不会有警告。

数据流：输入 None 作为主题名 → 调用 validate_theme_name → 断言返回 None。

调用关系：它覆盖默认配置路径，保证不写主题也正常。

调用图：外部调用 1 个（assert!）。

fn validate_theme_name_warns_for_missing_custom()

作用：测试自定义主题文件不存在时会给用户警告。

数据流：创建临时目录但不放主题文件 → 调用 validate_theme_name("my-fancy") → 断言有警告且包含主题名。

调用关系：它保护启动时的可操作提示，告诉用户文件该放哪。

调用图：调用 1 个内部函数（validate_theme_name）；外部调用 2 个（assert!, tempdir）。

fn validate_theme_name_none_when_custom_file_is_valid()

作用：测试有效自定义主题不会产生警告。

数据流：创建临时 themes 目录并写入有效 .tmTheme → 调用 validate_theme_name → 断言返回 None。

调用关系：它确认自定义主题配置的正常路径不会被误报。

调用图：外部调用 4 个（assert!, create_dir, tempdir, write_minimal_tmtheme）。

fn validate_theme_name_warns_when_custom_file_is_invalid()

作用：测试自定义主题文件存在但格式坏时会警告。

数据流：写入一个内容不是合法主题的 .tmTheme 文件 → 调用 validate_theme_name → 断言有警告且说明无法加载。

调用关系：它确保用户能区分“文件缺失”和“文件格式坏”。

调用图：调用 1 个内部函数（validate_theme_name）；外部调用 4 个（assert!, create_dir, write, tempdir）。

fn list_available_themes_excludes_invalid_custom_files()

作用：测试主题列表只收录有效的自定义主题文件。

数据流：在临时 themes 目录里放一个有效主题和一个坏文件 → 调用 list_available_themes → 断言有效主题出现，坏主题不出现。

调用关系：它保护主题选择器不会展示点了也不能用的主题。

调用图：调用 1 个内部函数（list_available_themes）；外部调用 5 个（assert!, create_dir, write, tempdir, write_minimal_tmtheme）。

fn list_available_themes_returns_stable_sorted_order()

作用：测试主题列表排序稳定，不受文件系统读取顺序影响。

数据流：创建多个大小写不同的自定义主题 → 调用 list_available_themes → 用同样规则排序一份期望值并比较。

调用关系：它保证主题选择器在不同系统上显示顺序一致。

调用图：调用 1 个内部函数（list_available_themes）；外部调用 4 个（assert_eq!, create_dir, tempdir, write_minimal_tmtheme）。

fn parse_theme_name_is_exhaustive()

作用：测试 two_face 提供的所有内置主题都被 parse_theme_name 覆盖。

数据流：读取 two_face 的全部主题枚举 → 确认数量仍是 32，再把手写名字全部映射 → 断言每个上游主题都能找到。

调用关系：它像一道保险：如果依赖库新增主题，测试会提醒维护者更新映射表和内置名单。

调用图：外部调用 3 个（theme_names, assert!, assert_eq!）。

fn default() -> Self

作用：给 Markdown 各种元素准备一套默认外观，比如标题加粗、代码变青色、链接加下划线。没有它，渲染出来的文字就会很难区分层次。

数据流：进去没有参数 → 它创建一组 Style（样式，表示粗体、斜体、颜色等）→ 出来一个 MarkdownStyles，后面的渲染器拿它给文字上色和加效果。

调用关系：Writer::new 创建渲染器时会调用它，相当于开工前先把画笔颜色和字体效果准备好。

调用图：被 1 处调用（new）；外部调用 1 个（new）。

fn new(prefix: Vec<Span<'static>>, marker: Option<Vec<Span<'static>>>, is_list: bool) -> Self

作用：记录当前这层缩进该怎么显示，比如引用前面的“> ”、列表项前面的“- ”或编号。它让嵌套列表和引用不会乱套。

数据流：进去前缀、可选列表标记、是否是列表 → 它原样装进一个 IndentContext → 出来一个缩进上下文，后面生成每一行前缀时使用。

调用关系：start_blockquote、start_codeblock、start_item 会调用它，把新进入的引用、代码块或列表项压到缩进栈里。

调用图：被 3 处调用（start_blockquote, start_codeblock, start_item）。

fn ensure_line(&mut self)

作用：保证表格单元格里至少有一行可写。这样追加文字时不会因为单元格还是空的而出错。

数据流：进去一个可修改的单元格 → 如果里面没有行，就放入一条空的 HyperlinkLine（带链接信息的显示行）→ 单元格变成可以继续追加内容的状态。

调用关系：TableCell::push_span 和 TableCell::push_annotated 在真正写内容前会先调用它。

调用图：调用 1 个内部函数（new）；被 2 处调用（push_annotated, push_span）；外部调用 1 个（default）。

fn push_span(&mut self, span: Span<'static>)

作用：往表格单元格当前行里追加一小段文字。Span 可以理解成“带样式的一截文字”。

数据流：进去一个 Span → 先确保单元格有行 → 把这段文字加到最后一行末尾，单元格内容被更新。

调用关系：这是表格单元格写普通文字的基础动作，被 Writer 写代码、HTML、软换行等内容时间接使用。

调用图：调用 1 个内部函数（ensure_line）。

fn push_annotated(&mut self, mut appended: HyperlinkLine)

作用：把一整段带超链接标注的内容接到表格单元格当前行后面，并修正链接所在列号。它保证链接拼接后仍然点在正确文字上。

数据流：进去一条 HyperlinkLine → 先确保单元格有行 → 把文字片段接到最后一行，并把新内容里的链接列范围整体右移 → 单元格保留正确的链接位置。

调用关系：Writer::push_text_spans_to_table_cell 会用它把自动识别的网页链接或 Markdown 链接放进单元格。

调用图：调用 1 个内部函数（ensure_line）。

fn hard_break(&mut self)

作用：在表格单元格里强制换一行。比如 Markdown 里有硬换行或块级 HTML 时需要这样做。

数据流：进去一个可修改单元格 → 追加一条新的空 HyperlinkLine → 后续内容会写到新行。

调用关系：Writer::push_table_cell_hard_break 会调用它，专门处理表格内部的换行。

调用图：调用 1 个内部函数（new）；外部调用 1 个（default）。

fn plain_text(&self) -> String

作用：把表格单元格里的样式和链接都去掉，只取可见文字。它主要用于计算表格宽度和判断内容类型。

数据流：进去一个单元格 → 逐行读取所有 Span 的文字，多行之间用空格连接 → 出来一个普通字符串。

调用关系：render_aligned_field、render_stacked_field 以及表格宽度统计逻辑会依赖这种纯文字结果。

调用图：被 2 处调用（render_aligned_field, render_stacked_field）；外部调用 2 个（new, write!）。

fn new(alignments: Vec<Alignment>) -> Self

作用：开始渲染一个表格时，创建一份空的表格临时记录。它会保存表头、行、当前单元格和对齐方式。

数据流：进去每列的对齐设置 → 初始化空表头、空行列表、空当前行和状态标记 → 出来一个可逐步填充的 TableState。

调用关系：Writer::start_table 调用它，之后表格头、行、单元格的开始和结束函数都会往这份状态里填内容。

调用图：被 1 处调用（start_table）；外部调用 1 个（new）。

fn render_markdown_text(input: &str) -> Text<'static>

作用：最简单的入口：把 Markdown 字符串渲染成终端可显示的 Text。调用者不用关心宽度和当前目录。

数据流：进去 Markdown 文本 → 转交给 render_markdown_text_with_width，宽度传 None → 出来 ratatui 的 Text（终端 UI 使用的多行文字对象）。

调用关系：测试和普通调用会用它；它只是轻量包装，真正工作交给带宽度的版本。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；被 72 处调用（vt100_deep_nested_mixed_list_third_level_marker_is_colored, crlf_code_block_no_extra_blank_lines, fenced_code_info_string_with_metadata_highlights, blockquote_heading_inherits_heading_style, blockquote_in_ordered_list_on_next_line, blockquote_in_unordered_list_on_next_line, blockquote_inside_nested_list, blockquote_list_then_nested_blockquote, blockquote_multiple_with_break, blockquote_nested_two_levels (+15 more)）。

fn render_markdown_text_with_width(input: &str, width: Option<usize>) -> Text<'static>

作用：把 Markdown 渲染成 Text，同时允许指定最大行宽。它还会顺手读取当前目录，用来显示本地文件链接。

数据流：进去文本和可选宽度 → 读取当前工作目录 → 调用 render_markdown_text_with_width_and_cwd → 出来可显示的 Text。

调用关系：render_markdown_text 调用它；需要测试换行效果的地方也直接调用它。

调用图：调用 1 个内部函数（render_markdown_text_with_width_and_cwd）；被 20 处调用（render_markdown_text, does_not_split_long_url_like_token_without_scheme, does_not_wrap_code_blocks, wraps_blockquotes, wraps_blockquotes_inside_lists, wraps_list_items_containing_blockquotes, wraps_list_items_preserving_indent, wraps_nested_lists, wraps_ordered_lists, wraps_plain_text_when_width_provided (+10 more)）；外部调用 1 个（current_dir）。

fn render_markdown_text_with_width_and_cwd(
    input: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
) -> Text<'static>

作用：把 Markdown 渲染成 Text，并显式指定屏幕宽度和当前目录。当前目录用于把本地链接显示得更友好。

数据流：进去文本、宽度、目录 → 先生成带链接信息的可见行 → 去掉不可见辅助内容并转成 Text → 出来给终端组件显示的结果。

调用关系：append_markdown、append_markdown_agent 和带宽度入口会调用它；底层工作交给 render_markdown_lines_with_width_and_cwd。

调用图：调用 2 个内部函数（render_markdown_lines_with_width_and_cwd, visible_lines）；被 8 处调用（append_markdown, append_markdown_agent, render_markdown_text_with_width, consecutive_unordered_list_local_file_links_do_not_detach_paths, render_markdown_text_for_cwd, table_wraps_file_paths_before_collapsing_narrative_columns_snapshot, unordered_list_local_file_link_soft_break_before_colon_stays_inline, unordered_list_local_file_link_stays_inline_with_following_text）；外部调用 1 个（from）。

fn render_markdown_lines_with_width_and_cwd(
    input: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
) -> Vec<HyperlinkLine>

作用：这是核心渲染入口，输出的不只是文字行，还保留每行里的超链接范围。适合需要点击链接或保留链接注解的界面。

数据流：进去 Markdown、宽度、目录 → 打开删除线和表格支持 → 用 Markdown 解析器生成事件 → 创建 Writer 跑完整个事件流 → 出来 Vec<HyperlinkLine>。

调用关系：上层 Text 渲染和带链接的 agent 渲染都会调用它；它创建 Writer，后续所有具体排版都由 Writer::run 驱动。

调用图：调用 2 个内部函数（new, new）；被 10 处调用（render_markdown_agent_with_links_and_cwd, render_markdown_text_with_width_and_cwd, annotates_explicit_web_link_label_and_visible_destination, does_not_annotate_code_or_non_web_markdown_links, key_value_table_keeps_web_annotations, pipe_table_fallback_keeps_web_annotations, wrapped_table_url_fragments_keep_complete_web_destination, bare_url_with_tilde_keeps_complete_hyperlink, merged_text_events_preserve_entity_decoding, table_url_with_tilde_keeps_complete_hyperlink）；外部调用 2 个（empty, new_ext）。

fn should_render_link_destination(dest_url: &str) -> bool

作用：判断一个链接是否应该把目标地址显示在正文后面。网页链接通常显示，本地文件路径则不这样显示。

数据流：进去链接目标字符串 → 判断它是不是本地路径样式 → 出来 true 表示显示“(url)”后缀，false 表示不显示。

调用关系：Writer::push_link 在遇到 Markdown 链接开始时调用它，决定后面 pop_link 怎么收尾。

调用图：调用 1 个内部函数（is_local_path_like_link）；被 1 处调用（push_link）。

fn new(input: &'a str, iter: I, wrap_width: Option<usize>, cwd: Option<&Path>) -> Self

作用：创建 Markdown 渲染的工作机。它保存输入、解析事件、样式、缩进、链接、代码块、表格等所有中间状态。

数据流：进去原文、事件迭代器、可选换行宽度、可选当前目录 → 初始化一大组状态字段 → 出来一个准备运行的 Writer。

调用关系：render_markdown_lines_with_width_and_cwd 调用它，然后马上调用 Writer::run。

调用图：调用 1 个内部函数（default）；被 1 处调用（render_markdown_lines_with_width_and_cwd）；外部调用 3 个（new, default, new）。

fn run(&mut self)

作用：驱动整个渲染过程：不停读取 Markdown 解析事件并处理，最后把没输出的当前行刷出去。

数据流：进去 Writer 自己持有的事件流 → 循环取事件并交给 handle_event → 结束时 flush_current_line → Writer.text 里留下最终行。

调用关系：由 render_markdown_lines_with_width_and_cwd 创建 Writer 后调用；每个事件的细节交给 handle_event。

调用图：调用 2 个内部函数（flush_current_line, handle_event）；外部调用 1 个（next）。

fn handle_event(&mut self, event: Event<'a>, range: Range<usize>)

作用：把解析器给出的一个 Markdown 事件分派给对应处理函数。它是事件到排版动作之间的总路口。

数据流：进去一个 Event 和它在原文中的范围 → 先处理可能挂起的本地链接软换行 → 根据事件类型开始标签、结束标签、写文字、写代码、换行等 → Writer 状态和输出行被更新。

调用关系：Writer::run 每读到一个事件就调用它；它再把工作交给 start_tag、end_tag、text、code、html 等函数。

调用图：调用 11 个内部函数（code, end_tag, flush_current_line, hard_break, html, prepare_for_event, push_blank_line, push_line, soft_break, start_tag (+1 more)）；被 1 处调用（run）；外部调用 1 个（from）。

fn prepare_for_event(&mut self, event: &Event<'a>)

作用：处理本地文件链接后面紧跟软换行的特殊情况。它避免“文件路径”和后面的说明文字被错误拆成两行。

数据流：进去下一个事件 → 如果没有挂起的本地链接软换行就不动；如果下个文本以冒号开头就保持同行；否则补一条空行 → 更新 pending_local_link_soft_break 状态。

调用关系：handle_event 在处理任何事件前都会调用它，专门补救 soft_break 留下的决定。

调用图：调用 1 个内部函数（push_line）；被 1 处调用（handle_event）；外部调用 2 个（default, matches!）。

fn start_tag(&mut self, tag: Tag<'a>, range: Range<usize>)

作用：处理 Markdown 开始标签，比如段落开始、标题开始、列表开始、链接开始、表格开始。它把“进入某种结构”转换成状态变化。

数据流：进去一个 Tag 和原文范围 → 按标签类型调用对应 start_* 函数或压入样式、链接状态 → Writer 进入相应上下文。

调用关系：handle_event 遇到 Event::Start 时调用它；它会分派到 start_paragraph、start_heading、start_table_row 等具体函数。

调用图：调用 12 个内部函数（push_inline_style, push_link, start_blockquote, start_codeblock, start_heading, start_item, start_list, start_paragraph, start_table, start_table_cell (+2 more)）；被 1 处调用（handle_event）；外部调用 1 个（from）。

fn end_tag(&mut self, tag: TagEnd)

作用：处理 Markdown 结束标签，比如段落结束、列表项结束、链接结束、表格结束。它把当前结构收尾并恢复状态。

数据流：进去一个 TagEnd → 按类型关闭段落、标题、引用、代码块、列表、链接、表格等 → 可能输出行、弹出缩进或样式、保存表格内容。

调用关系：handle_event 遇到 Event::End 时调用它；结束链接时交给 pop_link，结束表格时交给 end_table。

调用图：调用 12 个内部函数（end_blockquote, end_codeblock, end_heading, end_list, end_paragraph, end_table, end_table_cell, end_table_head, end_table_row, flush_current_line (+2 more)）；被 1 处调用（handle_event）。

fn start_paragraph(&mut self)

作用：开始一个普通段落，必要时先插入空行。表格单元格里的段落不会单独开外部行。

数据流：进去 Writer 当前状态 → 如果在表格单元格中就跳过；否则按 needs_newline 补空行，再开一条新行 → 标记正在段落中。

调用关系：start_tag 遇到 Paragraph 时调用它，段落结束由 end_paragraph 收尾。

调用图：调用 3 个内部函数（in_table_cell, push_blank_line, push_line）；被 1 处调用（start_tag）；外部调用 1 个（default）。

fn end_paragraph(&mut self)

作用：结束一个普通段落，并告诉后面内容通常需要换行。它也会清掉列表标记行的等待状态。

数据流：进去 Writer 当前状态 → 如果在表格单元格中不处理；否则设置 needs_newline、in_paragraph 为 false → 后续块会从新行开始。

调用关系：end_tag 遇到 Paragraph 时调用它。

调用图：调用 1 个内部函数（in_table_cell）；被 1 处调用（end_tag）。

fn start_heading(&mut self, level: HeadingLevel)

作用：开始标题，并按标题级别套用不同样式。它还会在显示内容前加上类似“# ”的标记。

数据流：进去标题级别 → 若不在表格里，选择对应样式，创建带 # 的新行，并把标题样式压入当前内联样式栈 → 后续标题文字会继承样式。

调用关系：start_tag 遇到 Heading 时调用它；end_heading 会弹出这里压入的样式。

调用图：调用 3 个内部函数（in_table_cell, push_inline_style, push_line）；被 1 处调用（start_tag）；外部调用 4 个（default, from, format!, vec!）。

fn end_heading(&mut self)

作用：结束标题，让后面内容另起一行，并取消标题文字样式。

数据流：进去 Writer 当前状态 → 如果不在表格里，设置 needs_newline 并弹出标题样式 → 后续文字恢复原样。

调用关系：end_tag 遇到 Heading 时调用它。

调用图：调用 2 个内部函数（in_table_cell, pop_inline_style）；被 1 处调用（end_tag）。

fn start_blockquote(&mut self)

作用：开始引用块，在每行前加“> ”这样的前缀。这样读者能看出这是引用内容。

数据流：进去 Writer 当前状态 → 必要时先补空行 → 把一个带“> ”前缀的 IndentContext 压入缩进栈 → 后续行自动带引用前缀。

调用关系：start_tag 遇到 BlockQuote 时调用它；end_blockquote 会弹出这层缩进。

调用图：调用 3 个内部函数（new, in_table_cell, push_blank_line）；被 1 处调用（start_tag）；外部调用 1 个（vec!）。

fn end_blockquote(&mut self)

作用：结束引用块，移除“> ”前缀，并让后面内容换行。

数据流：进去 Writer 当前状态 → 如果不在表格里，弹出引用缩进 → 设置 needs_newline。

调用关系：end_tag 遇到 BlockQuote 时调用它。

调用图：调用 1 个内部函数（in_table_cell）；被 1 处调用（end_tag）。

fn text(&mut self, text: CowStr<'a>)

作用：处理普通文本内容，是最常见的写字入口。它会根据当前位置决定写到正文、代码缓冲区还是表格单元格。

数据流：进去一段文本 → 如果本地链接标签被隐藏就丢弃；如果在表格里写入单元格；如果在带语言代码块里先缓存；否则按行拆开并应用当前样式 → 输出行或缓冲区被更新。

调用关系：handle_event 遇到 Event::Text 时调用它；它会用 push_text_spans 或 push_text_to_table_cell 真正写入。

调用图：调用 5 个内部函数（in_table_cell, push_line, push_text_spans, push_text_to_table_cell, suppressing_local_link_label）；被 1 处调用（handle_event）；外部调用 2 个（lines, default）。

fn code(&mut self, code: CowStr<'a>)

作用：处理行内代码，也就是 Markdown 反引号里的短代码。它会用代码样式显示。

数据流：进去代码文本 → 如果本地链接标签被隐藏就不写；在表格里写到单元格，否则写到当前正文行 → 内容带上 code 样式。

调用关系：handle_event 遇到 Event::Code 时调用它；底层通过 push_span 或 push_span_to_table_cell 添加文字。

调用图：调用 5 个内部函数（in_table_cell, push_line, push_span, push_span_to_table_cell, suppressing_local_link_label）；被 1 处调用（handle_event）；外部调用 3 个（into_string, default, from）。

fn html(&mut self, html: CowStr<'a>, inline: bool)

作用：处理 Markdown 中的 HTML 文本。这里不会真正解析 HTML，而是按文本显示，并处理行内或块级换行差异。

数据流：进去 HTML 文本和是否行内 → 表格里按行写入单元格，块级 HTML 后加硬换行；正文里按行写入当前输出 → 更新 needs_newline。

调用关系：handle_event 遇到 Html 或 InlineHtml 时调用它。

调用图：调用 6 个内部函数（in_table_cell, push_line, push_span, push_span_to_table_cell, push_table_cell_hard_break, suppressing_local_link_label）；被 1 处调用（handle_event）；外部调用 3 个（lines, default, styled）。

fn hard_break(&mut self)

作用：处理强制换行，相当于用户明确要求这里断行。表格内外有不同的换行方式。

数据流：进去 Writer 当前状态 → 如果在表格单元格里让单元格换行；否则开一条新输出行 → 当前链接结尾状态被清掉。

调用关系：handle_event 遇到 Event::HardBreak 时调用它。

调用图：调用 4 个内部函数（in_table_cell, push_line, push_table_cell_hard_break, suppressing_local_link_label）；被 1 处调用（handle_event）；外部调用 1 个（default）。

fn soft_break(&mut self)

作用：处理普通软换行。它通常变成新行，但在表格里变空格；本地文件链接后还有特殊延迟判断。

数据流：进去 Writer 当前状态 → 表格里追加空格；如果刚输出本地链接目标，则先挂起决定；否则直接开新行 → 状态按情况更新。

调用关系：handle_event 遇到 Event::SoftBreak 时调用它；挂起的情况由 prepare_for_event 在下个事件前处理。

调用图：调用 4 个内部函数（in_table_cell, push_line, push_span_to_table_cell, suppressing_local_link_label）；被 1 处调用（handle_event）；外部调用 2 个（default, styled）。

fn start_list(&mut self, index: Option<u64>)

作用：开始一个列表，并记录这是有序列表还是无序列表。有序列表会记住当前编号。

数据流：进去可选起始编号 → 顶层列表前可能补空行 → 把编号状态和“下一项前是否要空行”的状态压栈 → 后续列表项可生成正确标记。

调用关系：start_tag 遇到 List 时调用它；每个 Item 由 start_item 处理，列表结束由 end_list 处理。

调用图：调用 1 个内部函数（push_line）；被 1 处调用（start_tag）；外部调用 1 个（default）。

fn end_list(&mut self)

作用：结束当前列表，弹出列表编号和空行状态。它还让后续块通常另起一行。

数据流：进去 Writer 当前状态 → 弹出 list_indices 和 list_needs_blank_before_next_item → 设置 needs_newline。

调用关系：end_tag 遇到 List 时调用它。

调用图：被 1 处调用（end_tag）。

fn start_item(&mut self)

作用：开始一个列表项，生成“- ”或“1. ”这样的列表标记，并准备缩进。嵌套列表也靠它排齐。

数据流：进去 Writer 当前列表状态 → 必要时插空行并刷出上一行 → 计算层级、编号、标记文字和后续缩进 → 把列表缩进上下文压栈。

调用关系：start_tag 遇到 Item 时调用它；Item 结束时 end_tag 会刷行、判断是否需要在下一项前加空行并弹出缩进。

调用图：调用 3 个内部函数（new, flush_current_line, push_blank_line）；被 1 处调用（start_tag）；外部调用 2 个（new, vec!）。

fn start_codeblock(&mut self, lang: Option<String>, indent: Option<Span<'static>>)

作用：开始代码块，准备按代码原样显示。带语言名的围栏代码块会先缓存，结束时做语法高亮。

数据流：进去可选语言名和可选缩进 → 刷掉当前行、必要时加空行 → 解析语言名第一段、清空代码缓冲区、压入代码块缩进 → 标记进入代码块。

调用关系：start_tag 遇到 CodeBlock 时调用它；end_codeblock 负责输出或高亮缓存内容。

调用图：调用 3 个内部函数（new, flush_current_line, push_blank_line）；被 1 处调用（start_tag）；外部调用 1 个（vec!）。

fn end_codeblock(&mut self)

作用：结束代码块。若之前知道代码语言，就把缓存内容做语法高亮后输出。

数据流：进去 Writer 当前代码块状态 → 如果有语言和缓存代码，调用 highlight_code_to_lines 生成彩色行并输出 → 清除代码块状态、弹出缩进、设置需要换行。

调用关系：end_tag 遇到 CodeBlock 时调用它；它会把最终代码行交给 push_line 和 push_span。

调用图：调用 3 个内部函数（push_line, push_span, highlight_code_to_lines）；被 1 处调用（end_tag）；外部调用 2 个（default, take）。

fn start_table(&mut self, alignments: Vec<Alignment>)

作用：开始收集一个 Markdown 表格。表格不会马上输出，而是先攒完整再统一排版。

数据流：进去列对齐设置 → 刷当前行，必要时补空行 → 创建 TableState 保存表格临时数据 → Writer 进入表格模式。

调用关系：start_tag 遇到 Table 时调用它；end_table 会把收集好的表格真正渲染出来。

调用图：调用 3 个内部函数（new, flush_current_line, push_blank_line）；被 1 处调用（start_tag）。

fn end_table(&mut self)

作用：结束表格并把它排成最终显示行。它会选择普通表格、预换行表格或溢出文本等输出方式。

数据流：进去 Writer 当前表格状态 → 取出 TableState → 调用 render_table_lines 生成表格行和溢出行 → 按是否已预换行分别输出 → 设置后续需要换行。

调用关系：end_tag 遇到 Table 时调用它；核心排版交给 render_table_lines。

调用图：调用 4 个内部函数（flush_current_line, push_hyperlink_line, push_prewrapped_line, render_table_lines）；被 1 处调用（end_tag）。

fn start_table_head(&mut self)

作用：开始表头行的收集。表头通常会用更醒目的样式显示。

数据流：进去 Writer 当前表格状态 → 标记 in_header 为 true，并创建新的当前行 → 后续单元格会进入表头。

调用关系：start_tag 遇到 TableHead 时调用它；end_table_head 会把当前行保存成 header。

调用图：被 1 处调用（start_tag）；外部调用 1 个（new）。

fn end_table_head(&mut self)

作用：结束表头收集，把最后一个单元格和当前行保存为表头。

数据流：进去表格状态 → 如果还有当前单元格就放入当前行 → 把当前行取出保存为 header → 关闭 in_header 标记。

调用关系：end_tag 遇到 TableHead 时调用它。

调用图：被 1 处调用（end_tag）。

fn start_table_row(&mut self, source_range: Range<usize>)

作用：开始收集表格的一行，并记住原文这一行有没有管道符边界。这个信息用来判断某些“伪表格行”。

数据流：进去原文范围 → 检查这一段源码是否以 | 开头或结尾 → 创建空当前行并记录管道符语法标记。

调用关系：start_tag 遇到 TableRow 时调用它；检查工作交给 has_table_row_boundary_pipe。

调用图：调用 1 个内部函数（has_table_row_boundary_pipe）；被 1 处调用（start_tag）；外部调用 1 个（new）。

fn has_table_row_boundary_pipe(&self, source_range: Range<usize>) -> bool

作用：判断表格行原文是不是明显使用了“|”管道表格写法。它帮助区分真正表格和被解析器误吞进去的普通段落。

数据流：进去源码范围 → 从原始输入中取出对应文本并去掉两端空白 → 看是否以 | 开头或结尾 → 返回布尔值。

调用关系：start_table_row 调用它，把结果存进 TableState。

调用图：被 1 处调用（start_table_row）。

fn end_table_row(&mut self)

作用：结束当前表格行，把它放到表头或表体里。

数据流：进去表格状态 → 若当前单元格还没入行就先放入 → 取出当前行 → 根据是否在表头保存为 header 或追加到 rows → 清掉本行管道标记。

调用关系：end_tag 遇到 TableRow 时调用它。

调用图：被 1 处调用（end_tag）。

fn start_table_cell(&mut self)

作用：开始一个新的表格单元格，准备接收里面的文本、链接或换行。

数据流：进去表格状态 → 创建默认 TableCell 作为 current_cell → 后续内容写进这个单元格。

调用关系：start_tag 遇到 TableCell 时调用它；end_table_cell 会把它放入当前行。

调用图：被 1 处调用（start_tag）；外部调用 1 个（default）。

fn end_table_cell(&mut self)

作用：结束当前表格单元格，并把它加入当前表格行。

数据流：进去表格状态 → 取出 current_cell → 确保有 current_row 并把单元格推进去 → 当前单元格清空。

调用关系：end_tag 遇到 TableCell 时调用它。

调用图：被 1 处调用（end_tag）。

fn in_table_cell(&self) -> bool

作用：判断当前是不是正在写表格单元格。很多处理逻辑要根据这个结果走不同路线。

数据流：进去 Writer 状态 → 查看 table_state 里是否有 current_cell → 返回 true 或 false。

调用关系：text、code、html、换行、链接收尾等函数都会用它决定写到表格里还是正文里。

调用图：被 12 处调用（code, end_blockquote, end_heading, end_paragraph, hard_break, html, pop_link, soft_break, start_blockquote, start_heading (+2 more)）。

fn push_span_to_table_cell(&mut self, span: Span<'static>)

作用：把一小段带样式文字写进当前表格单元格。没有当前单元格时它什么也不做。

数据流：进去 Span → 找到 table_state.current_cell → 调用单元格的 push_span 追加内容 → 单元格文字增加。

调用关系：code、html、soft_break、pop_link 等在表格内部写内容时调用它。

调用图：被 4 处调用（code, html, pop_link, soft_break）。

fn push_table_cell_hard_break(&mut self)

作用：在当前表格单元格里插入硬换行。它只影响单元格内部，不会直接输出整张表。

数据流：进去 Writer 状态 → 找到当前单元格 → 调用 TableCell::hard_break → 单元格新增一行。

调用关系：hard_break、html、push_text_to_table_cell 会调用它。

调用图：被 3 处调用（hard_break, html, push_text_to_table_cell）。

fn push_text_to_table_cell(&mut self, text: &str)

作用：把普通文本写入表格单元格，并保留文本里的换行。

数据流：进去字符串 → 取当前内联样式 → 按行拆分，行与行之间插入单元格硬换行 → 每行交给 push_text_spans_to_table_cell 处理链接和样式。

调用关系：Writer::text 在发现自己位于表格单元格中时调用它。

调用图：调用 2 个内部函数（push_table_cell_hard_break, push_text_spans_to_table_cell）；被 1 处调用（text）。

fn push_text_spans_to_table_cell(&mut self, text: &str, style: Style)

作用：把一行表格单元格文本变成带样式、可能带链接标注的内容。它也会自动识别裸露的网页地址。

数据流：进去文本和样式 → 如果当前 Markdown 链接是网页，整段标注为该链接；如果在链接或代码块里就不自动识别；否则自动识别网页 URL → 把结果追加到当前单元格。

调用关系：push_text_to_table_cell 调用它；它使用 annotate_web_urls_in_line 给普通文本里的网址加注解。

调用图：调用 2 个内部函数（new, annotate_web_urls_in_line）；被 1 处调用（push_text_to_table_cell）；外部调用 4 个（default, from, styled, take）。

fn render_table_lines(&self, mut table_state: TableState) -> RenderedTableLines

作用：把已经收集好的表格数据排成最终要显示的多行文字。这是表格渲染的核心决策点。

数据流：进去 TableState → 过滤被解析器误当表格的溢出行，补齐列数，统计每列宽度和内容类型 → 根据可用宽度选择列宽、键值记录形式或管道表格回退 → 出来 RenderedTableLines。

调用关系：end_table 调用它；它会进一步调用 compute_column_widths、render_table_row、render_table_pipe_fallback 以及 table_key_value 的记录渲染逻辑。

调用图：调用 9 个内部函数（available_record_width, available_table_width, compute_column_widths, render_table_pipe_fallback, render_table_row, render_records, should_render_records, foreground_style_for_scopes, table_separator_style）；被 1 处调用（end_table）；外部调用 7 个（collect_table_column_metrics, is_spillover_row, normalize_row, render_table_separator, default, new, with_capacity）。

fn normalize_row(row: &mut Vec<TableCell>, column_count: usize)

作用：把一行表格修正成固定列数。多余单元格丢掉，缺少的补空白。

数据流：进去一行单元格和目标列数 → truncate 截断多余列，resize 补默认空单元格 → 这行变得和表头列数一致。

调用关系：render_table_lines 在真正计算宽度前使用它，避免后面按列访问时错位。

调用图：外部调用 1 个（default）。

fn available_table_width(&self, column_count: usize) -> Option<usize>

作用：计算表格内容区最多能占多少宽度。它会扣掉列表、引用前缀、列间距和单元格内边距。

数据流：进去列数 → 如果有 wrap_width，就算出当前前缀宽度和表格固定开销 → 返回剩余宽度；没有 wrap_width 就返回 None。

调用关系：render_table_lines 调用它，为 compute_column_widths 提供宽度预算。

调用图：被 1 处调用（render_table_lines）。

fn available_record_width(&self) -> Option<usize>

作用：计算键值记录式表格可用的整行宽度。它只扣掉当前缩进前缀。

数据流：进去 Writer 状态 → 如果有 wrap_width，减去 prefix_spans 的显示宽度 → 返回可用宽度；否则返回 None。

调用关系：render_table_lines 在决定使用 table_key_value::render_records 时调用它。

调用图：被 1 处调用（render_table_lines）。

fn compute_column_widths(
        &self,
        header: &[TableCell],
        rows: &[Vec<TableCell>],
        alignments: &[Alignment],
        available_width: Option<usize>,
    ) -> Option<Vec<us

作用：根据内容和屏幕宽度给每个表格列分配宽度。它会尽量保留重要长词，又在空间不够时逐步压缩列。

数据流：进去表头、表体、对齐方式、可用宽度 → 收集列指标，先用最大内容宽度，再按最小宽度和偏好下限收缩 → 成功返回每列宽度，太窄则返回 None。

调用关系：render_table_lines 调用它；它依赖 collect_table_column_metrics、preferred_column_floor、next_column_to_shrink。

调用图：被 1 处调用（render_table_lines）；外部调用 3 个（len, collect_table_column_metrics, next_column_to_shrink）。

fn collect_table_column_metrics(
        header: &[TableCell],
        rows: &[Vec<TableCell>],
        column_count: usize,
    ) -> Vec<TableColumnMetrics>

作用：统计每一列表格内容的特征，比如最宽内容、最长单词、是不是长篇描述列。后面分配列宽要靠这些信息。

数据流：进去表头、表体和列数 → 逐列扫描纯文字和显示宽度，统计词数、长词数量、平均长度 → 出来一组 TableColumnMetrics。

调用关系：render_table_lines 和 compute_column_widths 都会用它，为宽度和布局选择提供依据。

调用图：外部调用 3 个（cell_display_width, longest_token_width, with_capacity）。

fn preferred_column_floor(metrics: &TableColumnMetrics, min_column_width: usize) -> usize

作用：给某一列算一个“最好别再窄”的宽度下限。这样压缩表格时不会轻易把长词或描述压得太碎。

数据流：进去列指标和硬性最小宽度 → 根据列类型选择目标宽度，再限制在最小值和最大内容宽度之间 → 返回偏好的下限。

调用关系：compute_column_widths 在压缩列宽前调用它生成 floors。

fn next_column_to_shrink(
        widths: &[usize],
        floors: &[usize],
        metrics: &[TableColumnMetrics],
    ) -> Option<usize>

作用：在需要缩窄表格时，挑下一列来减少宽度。它会优先缩那些更适合换行的列。

数据流：进去当前宽度、每列下限和列指标 → 过滤还能缩的列 → 按列类型优先级和剩余空间选择一列 → 返回列索引或 None。

调用关系：compute_column_widths 的收缩循环反复调用它。

fn column_shrink_priority(kind: TableColumnKind) -> usize

作用：给不同类型的列排压缩优先级。长令牌列、叙述列、紧凑列会按不同顺序被压缩。

数据流：进去 TableColumnKind → 返回数字优先级，数字越小越先被考虑 → 供列宽收缩算法排序。

调用关系：next_column_to_shrink 和 compute_column_widths 内部选择收缩对象时使用它。

fn render_table_separator(
        column_widths: &[usize],
        separator_char: char,
        style: Style,
    ) -> HyperlinkLine

作用：生成表格中的分隔线，比如表头下面的一排横线。它会按每列宽度拼出合适长度。

数据流：进去列宽、分隔字符和样式 → 为每列重复分隔字符并加上单元格 padding 和列间距 → 出来一条 HyperlinkLine。

调用关系：render_table_lines 在表头后和表体行之间调用它。

调用图：调用 1 个内部函数（new）；外部调用 2 个（from, styled）。

fn render_table_row(
        &self,
        row: &[TableCell],
        column_widths: &[usize],
        alignments: &[Alignment],
        row_style: Style,
    ) -> Vec<HyperlinkLine>

作用：把一行表格单元格渲染成一行或多行显示文字，并按左中右对齐补空格。

数据流：进去一行单元格、列宽、对齐方式、整行样式 → 先把每个单元格按列宽换行 → 逐显示行拼接各列、补 padding、调整链接列位置 → 出来多条 HyperlinkLine。

调用关系：render_table_lines 用它渲染表头和每一行表体；单元格换行交给 wrap_cell。

调用图：调用 1 个内部函数（new）；被 1 处调用（render_table_lines）；外部调用 7 个（default, from, line_display_width, raw, new, with_capacity, iter）。

fn render_table_pipe_fallback(
        &self,
        header: &[TableCell],
        rows: &[Vec<TableCell>],
        alignments: &[Alignment],
    ) -> Vec<HyperlinkLine>

作用：当宽度太窄或没有表体时，把表格退回成原始 Markdown 管道表格样式。这样至少还能完整表达表格结构。

数据流：进去表头、表体和对齐方式 → 生成表头管道行、对齐分隔行、每个表体管道行 → 出来多条 HyperlinkLine。

调用关系：render_table_lines 在无法正常分配列宽的某些情况下调用它。

调用图：调用 1 个内部函数（new）；被 1 处调用（render_table_lines）；外部调用 4 个（from, alignments_to_pipe_delimiter, row_to_pipe_line, new）。

fn row_to_pipe_line(row: &[TableCell]) -> HyperlinkLine

作用：把一行表格单元格变成“| a | b |”这种管道文本，同时保留网页链接标注。单元格里的竖线会被转义，避免看起来像分列。

数据流：进去一行 TableCell → 逐单元格拼文字，多行用空格合并，遇到 | 写成 \|，并按原链接范围给输出片段加链接 → 出来一条 HyperlinkLine。

调用关系：render_table_pipe_fallback 调用它生成表头和表体的管道行。

调用图：调用 1 个内部函数（new）；外部调用 3 个（default, new, width）。

fn alignments_to_pipe_delimiter(alignments: &[Alignment]) -> String

作用：把列对齐方式变成 Markdown 管道表格里的分隔行，比如左对齐是“:---”。

数据流：进去对齐方式数组 → 逐列追加对应分隔片段并用 | 包起来 → 出来一个分隔行字符串。

调用关系：render_table_pipe_fallback 调用它生成表头下面的对齐说明行。

调用图：外部调用 1 个（new）。

fn wrap_cell(&self, cell: &TableCell, width: usize) -> Vec<HyperlinkLine>

作用：把一个表格单元格按指定列宽折行，同时保持链接仍指向正确文字。它让窄屏表格能读。

数据流：进去单元格和宽度 → 对单元格每一行调用 word_wrap_line 换行 → 用 remap_wrapped_line 重映射链接位置 → 出来换行后的 HyperlinkLine 列表。

调用关系：render_table_row 在渲染每个单元格前调用它。

调用图：调用 4 个内部函数（new, remap_wrapped_line, new, word_wrap_line）；外部调用 3 个（default, new, vec!）。

fn is_spillover_row(row: &TableBodyRow, next_row: Option<&TableBodyRow>) -> bool

作用：判断某一行是不是被 Markdown 解析器误当成表格行的普通内容。常见情况是表格后面的段落或 HTML 被吞进表格。

数据流：进去当前表体行和下一行 → 找第一列非空且其他列为空的文字，再结合是否有管道符、是否像 HTML、是否像“HTML:”标签判断 → 返回是否应作为表格外溢出文本。

调用关系：render_table_lines 在整理表体行时调用它，把误入表格的内容移到 spillover_lines。

调用图：外部调用 3 个（first_non_empty_only_text, looks_like_html_content, looks_like_html_label_line）。

fn first_non_empty_only_text(row: &[TableCell]) -> Option<String>

作用：检查一行表格是否只有第一格有文字，其他格都空。这个形态常用于识别表格外溢内容。

数据流：进去一行单元格 → 取第一格纯文字，若为空返回 None；再确认后续单元格都为空 → 成功返回第一格文字。

调用关系：is_spillover_row 调用它做第一步筛选。

调用图：外部调用 1 个（first）。

fn looks_like_html_content(text: &str) -> bool

作用：粗略判断一段文字里是否像 HTML 标签，比如“<div>”。它不是完整 HTML 解析，只是识别明显特征。

数据流：进去字符串 → 扫描字符里的 <，允许后面有 / 或 !，再看是否跟字母且后面有 > → 返回是否像 HTML。

调用关系：is_spillover_row 用它判断表格后面的 HTML 内容是否被误收进表格。

fn looks_like_html_label_line(text: &str) -> bool

作用：判断一行是否像“HTML block:”这样的说明标签。它用于把表格末尾的 HTML 引导文字从表格里挪出来。

数据流：进去字符串 → 去空白，检查是否以冒号结尾，再看冒号前是否有单词 html（忽略大小写）→ 返回布尔值。

调用关系：is_spillover_row 在没有下一行可参考时调用它。

fn spans_display_width(spans: &[Span<'_>]) -> usize

作用：计算一组 Span 在终端里实际占多少列宽。中文、emoji 等字符可能不止占一列，所以不能只数字节。

数据流：进去 Span 列表 → 对每段文字调用 width 计算显示宽度并求和 → 返回总宽度。

调用关系：available_table_width、available_record_width、line_display_width、flush_current_line 等宽度相关逻辑会用它。

调用图：外部调用 1 个（iter）。

fn line_display_width(line: &Line<'_>) -> usize

作用：计算一整行在终端里显示的宽度。它把行里的多个 Span 加总。

数据流：进去 Line → 取出 spans → 调用 spans_display_width → 返回显示列数。

调用关系：render_table_row、cell_display_width 等表格布局函数用它判断内容宽度。

调用图：外部调用 1 个（spans_display_width）。

fn cell_display_width(cell: &TableCell) -> usize

作用：计算一个表格单元格最宽一行的显示宽度。列宽估算需要这个值。

数据流：进去 TableCell → 遍历单元格里的每一行，计算每行显示宽度 → 返回最大值，没有内容则返回 0。

调用关系：collect_table_column_metrics 用它统计每列最大宽度。

fn longest_token_width(text: &str) -> usize

作用：找出一段文本里最长单词或连续片段的显示宽度。长 URL、路径、标识符会影响表格换行策略。

数据流：进去字符串 → 按空白拆成 token → 计算每个 token 的显示宽度并取最大 → 返回最大值或 0。

调用关系：collect_table_column_metrics 用它识别长词较多的列。

fn push_inline_style(&mut self, style: Style)

作用：进入加粗、斜体、标题等内联样式时，把新样式叠加到当前样式栈。这样嵌套样式能同时生效。

数据流：进去一个 Style → 取当前栈顶样式，与新样式 patch 合并 → 把合并结果压入 inline_styles。

调用关系：start_heading 和 start_tag 处理 Emphasis、Strong、Strikethrough 时调用它；对应结束时 pop_inline_style 弹出。

调用图：被 2 处调用（start_heading, start_tag）。

fn pop_inline_style(&mut self)

作用：离开当前内联样式范围时，恢复上一层样式。

数据流：进去 Writer 样式栈 → 弹出栈顶 → 后续文字使用新的栈顶样式或默认样式。

调用关系：end_heading 和 end_tag 处理强调、加粗、删除线结束时调用它。

调用图：被 2 处调用（end_heading, end_tag）。

fn push_link(&mut self, dest_url: String)

作用：进入 Markdown 链接时，记录链接目标，并决定之后怎样显示。网页链接和本地文件链接会走不同策略。

数据流：进去链接目标字符串 → 判断是否显示目标地址、是否像本地路径；本地路径会生成友好显示文本 → 保存 LinkState 到 self.link。

调用关系：start_tag 遇到 Link 时调用它；链接正文期间 text/code 可能受它影响，结束时 pop_link 使用这份状态。

调用图：调用 3 个内部函数（is_local_path_like_link, render_local_link_target, should_render_link_destination）；被 1 处调用（start_tag）。

fn pop_link(&mut self)

作用：结束 Markdown 链接时，把链接目标或本地路径补到输出里。它保证网页链接可点击，本地文件链接显示真实路径而不是随便的标签文字。

数据流：进去当前 link 状态 → 如果应显示网页目标，就追加“ (url)”并给 url 加链接注解；如果是本地目标，就用代码样式输出解析后的路径 → 更新正文或表格单元格内容。

调用关系：end_tag 遇到 Link 时调用它；它会根据是否在表格里调用 push_span_to_table_cell、push_annotated 或 push_span。

调用图：调用 7 个内部函数（in_table_cell, push_annotated, push_line, push_span, push_span_to_table_cell, new, web_destination）；被 1 处调用（end_tag）；外部调用 2 个（default, styled）。

fn suppressing_local_link_label(&self) -> bool

作用：判断当前链接的原始标签文字是否应该被隐藏。本地文件链接会隐藏标签，改显示解析后的路径。

数据流：进去 Writer 链接状态 → 如果当前 link 有 local_target_display 就返回 true → 调用方据此跳过普通文本、代码或换行。

调用关系：text、code、html、hard_break、soft_break 都会先问它，避免把本地链接标签写出来。

调用图：被 5 处调用（code, hard_break, html, soft_break, text）。

fn flush_current_line(&mut self)

作用：把正在拼的一行真正送进输出列表。它还会按屏幕宽度自动换行，并修正缩进和链接位置。

数据流：进去 current_line_content → 如果不是代码块且设置了宽度，就按缩进自适应换行并重映射链接；否则把初始缩进直接拼到行首并右移链接列号 → 输出到 text，并清空当前行状态。

调用关系：run 结束、push_line 开新行、end_table、start_codeblock 等很多地方都会调用它，确保上一行不会丢。

调用图：调用 4 个内部函数（push_output_line, remap_wrapped_line, new, adaptive_wrap_line）；被 10 处调用（end_table, end_tag, handle_event, push_blank_line, push_line, push_prewrapped_line, run, start_codeblock, start_item, start_table）；外部调用 1 个（from_iter）。

fn is_blockquote_active(&self) -> bool

作用：判断当前是否处在引用块里。引用块里的行需要套用引用样式。

数据流：进去缩进栈 → 查找是否有前缀包含“>” → 返回 true 或 false。

调用关系：push_line 和 push_prewrapped_line 用它决定是否给行加 blockquote 样式。

调用图：被 2 处调用（push_line, push_prewrapped_line）。

fn push_prewrapped_line(&mut self, mut line: HyperlinkLine, pending_marker_line: bool)

作用：输出一条已经提前排好换行的行，比如表格行。它只负责加当前缩进和修正链接位置，不再重新换行。

数据流：进去 HyperlinkLine 和是否还在等待列表标记 → 先刷当前行，计算引用样式和前缀 → 把前缀拼到行首并整体右移链接列号 → 直接推入输出。

调用关系：end_table 在表格已经预换行时调用它。

调用图：调用 5 个内部函数（flush_current_line, is_blockquote_active, prefix_spans, push_output_line, style）；被 1 处调用（end_table）；外部调用 1 个（from）。

fn push_line(&mut self, line: Line<'static>)

作用：开始拼一条新的当前行。它会先把旧行刷出去，再准备本行的缩进、样式和换行信息。

数据流：进去 Line → flush_current_line 输出旧行 → 根据引用状态和 pending_marker_line 生成初始/后续缩进 → 创建 current_line_content → 清掉列表标记等待状态。

调用关系：大量内容写入函数都会用它开新行，比如 text、code、hard_break、pop_link、prepare_for_event。

调用图：调用 4 个内部函数（flush_current_line, is_blockquote_active, prefix_spans, new）；被 16 处调用（code, end_codeblock, handle_event, hard_break, html, pop_link, prepare_for_event, push_annotated, push_blank_line, push_hyperlink_line (+6 more)）。

fn push_hyperlink_line(&mut self, line: HyperlinkLine)

作用：把一条已有链接注解的行放入当前渲染流程。它保留原来的 hyperlinks 信息。

数据流：进去 HyperlinkLine → 先取出 hyperlinks，再用 push_line 开行 → 把 hyperlinks 放回 current_line_content → 当前行拥有原始链接标注。

调用关系：end_table 输出非预换行表格行和溢出行时调用它。

调用图：调用 1 个内部函数（push_line）；被 1 处调用（end_table）。

fn push_span(&mut self, span: Span<'static>)

作用：往当前行追加一小段文字；如果还没有当前行，就先创建一行。

数据流：进去 Span → 如果 current_line_content 存在就追加到它的 Line；否则创建只含这段文字的新行 → 当前行内容增加。

调用关系：code、html、end_codeblock、pop_link 等需要直接写一段文字时调用它。

调用图：调用 1 个内部函数（push_line）；被 4 处调用（code, end_codeblock, html, pop_link）；外部调用 2 个（from, vec!）。

fn push_annotated(&mut self, mut appended: HyperlinkLine)

作用：往当前行追加一段可能带超链接标注的内容，并把链接位置接到正确列号上。

数据流：进去 HyperlinkLine → 如果没有当前行就先开空行 → 计算当前行已有宽度作为偏移 → 追加 spans，并把新链接列范围整体右移 → 当前行保留正确链接。

调用关系：push_text_spans 和 pop_link 用它合并带链接的文字。

调用图：调用 1 个内部函数（push_line）；被 2 处调用（pop_link, push_text_spans）；外部调用 1 个（default）。

fn push_text_spans(&mut self, text: &str, style: Style)

作用：把普通文本变成可输出的 Span，并处理网页链接标注或自动识别裸 URL。

数据流：进去文本和样式 → 如果当前 Markdown 链接是网页，则整段绑定目标；如果在链接或代码块里则不自动识别；否则自动识别文本中的网址 → 交给 push_annotated 追加。

调用关系：Writer::text 在正文中写普通文字时调用它。

调用图：调用 3 个内部函数（push_annotated, new, annotate_web_urls_in_line）；被 1 处调用（text）；外部调用 3 个（default, from, styled）。

fn push_blank_line(&mut self)

作用：插入空白行，并考虑列表和引用的缩进规则。它避免空行破坏列表显示。

数据流：进去 Writer 状态 → 先刷当前行 → 如果当前缩进全是列表，就直接输出真正空行；否则开一条带上下文的空行再刷出 → 输出多一条空白行。

调用关系：handle_event 的水平线、start_paragraph、start_blockquote、start_codeblock、start_item、start_table 都可能调用它。

调用图：调用 4 个内部函数（flush_current_line, push_line, push_output_line, new）；被 6 处调用（handle_event, start_blockquote, start_codeblock, start_item, start_paragraph, start_table）；外部调用 1 个（default）。

fn push_output_line(&mut self, line: HyperlinkLine)

作用：把最终完成的一行放进输出结果列表。它是写入 self.text 的最底层动作。

数据流：进去 HyperlinkLine → 直接 push 到 self.text → 输出结果增加一行。

调用关系：flush_current_line、push_blank_line、push_prewrapped_line 调用它。

调用图：被 3 处调用（flush_current_line, push_blank_line, push_prewrapped_line）。

fn prefix_spans(&self, pending_marker_line: bool) -> Vec<Span<'static>>

作用：根据当前缩进栈生成一行开头应该显示的前缀，比如列表标记、引用符号和缩进空格。

数据流：进去是否正在等待列表标记 → 遍历 indent_stack，按规则选择 marker 或 prefix，跳过不该重复显示的中间列表缩进 → 返回 Span 列表作为行前缀。

调用关系：push_line、push_prewrapped_line、available_table_width、available_record_width 用它计算或添加行前缀。

调用图：被 2 处调用（push_line, push_prewrapped_line）；外部调用 1 个（new）。

fn is_local_path_like_link(dest_url: &str) -> bool

作用：判断一个链接目标看起来是不是本地文件路径，而不是普通网页地址。它支持 Unix、Windows、file://、相对路径等常见写法。

数据流：进去链接字符串 → 检查 file://、/、~/、./、../、网络共享路径、Windows 盘符路径等模式 → 返回 true 或 false。

调用关系：should_render_link_destination 和 Writer::push_link 调用它，决定链接显示策略。

调用图：被 2 处调用（push_link, should_render_link_destination）；外部调用 1 个（matches!）。

fn render_local_link_target(dest_url: &str, cwd: Option<&Path>) -> Option<String>

作用：把本地文件链接转换成最终要显示的路径文本，必要时保留行号等位置后缀。这样用户看到的是可理解的本地目标。

数据流：进去链接目标和可选当前目录 → parse_local_link_target 拆出路径和位置后缀 → display_local_link_path 把路径转成适合显示的形式 → 拼回后缀并返回。

调用关系：Writer::push_link 在发现链接像本地路径时调用它；结果会在 pop_link 中作为代码样式路径输出。

调用图：调用 2 个内部函数（display_local_link_path, parse_local_link_target）；被 1 处调用（push_link）。

fn parse_local_link_target(dest_url: &str) -> Option<(String, Option<String>)>

作用：把一个 Markdown 里的本地链接目标拆成“文件路径”和“可选的位置后缀”，比如行号。这样界面才能知道链接指向哪个文件，以及是否要跳到某一行。

数据流：进去的是一个链接字符串，可能是 file:// 开头的网址，也可能是普通路径，还可能带 #L10 或 :10 这种位置标记。它先识别 file://，转成本地路径；否则先找井号形式的位置，再找冒号形式的位置，然后把 URL 编码过的字符解码，最后展开 ~/ 并统一路径写法。出来的是一个路径字符串和一个可选的位置字符串；如果 file:// 解析失败，就返回空。

调用关系：它是本地链接渲染流程里的解析员，由 render_local_link_target 调用。它把具体杂活分给 file_url_to_local_path_text、normalize_hash_location_suffix_fragment、extract_colon_location_suffix 和 expand_local_link_path，让后面的显示逻辑拿到干净、统一的目标。

调用图：调用 4 个内部函数（expand_local_link_path, extract_colon_location_suffix, file_url_to_local_path_text, normalize_hash_location_suffix_fragment）；被 1 处调用（render_local_link_target）；外部调用 3 个（parse, Borrowed, decode）。

fn normalize_hash_location_suffix_fragment(fragment: &str) -> Option<String>

作用：把链接里 # 后面的行号片段整理成统一格式。比如只接受像 L10 这种看起来真的是位置的片段，避免把普通章节标题误当成行号。

数据流：进去的是井号后面的片段文本。它先用规则检查这个片段是不是位置标记，是的话补回 #，再交给更通用的位置后缀整理函数处理。出来的是整理好的位置字符串；如果不像行号位置，就返回空。

调用关系：它只被 parse_local_link_target 使用，专门服务 #L.. 这种链接形式。它在冒号行号解析之前运行，避免 path#L10 被误看成普通路径的一部分。

调用图：被 1 处调用（parse_local_link_target）。

fn extract_colon_location_suffix(path_text: &str) -> Option<String>

作用：从路径末尾抠出 :10、:10:5 这类冒号形式的位置后缀。这样 “文件名:行号” 能被识别成跳转位置，而不是完整文件名。

数据流：进去的是路径文本。它用匹配规则查找冒号位置标记，并且要求这个标记必须刚好在字符串末尾。出来的是这个后缀字符串；如果末尾没有合法后缀，就返回空。

调用关系：它由 parse_local_link_target 调用，只在没有找到 #L.. 形式位置时使用。它帮解析流程兼容常见的编辑器/终端写法。

调用图：被 1 处调用（parse_local_link_target）。

fn expand_local_link_path(path_text: &str) -> String

作用：把本地路径整理成显示和比较都方便的形式，特别是把 ~/ 开头的路径展开成用户家目录。这样同一个文件不会因为写法不同而被当成不同路径。

数据流：进去的是路径文字。如果它以 ~/ 开头，并且系统能找到用户家目录，就把 ~ 换成真实家目录，再统一斜杠写法；否则直接统一斜杠写法。出来的是规范化后的路径字符串。

调用关系：它被 parse_local_link_target 调用，是本地链接解析的收尾步骤。它会调用 normalize_local_link_path_text，把不同系统的路径分隔符统一起来。

调用图：调用 1 个内部函数（normalize_local_link_path_text）；被 1 处调用（parse_local_link_target）；外部调用 1 个（home_dir）。

fn file_url_to_local_path_text(url: &Url) -> Option<String>

作用：把 file:// 形式的网址变成本地文件路径。没有它，Markdown 里的 file:// 链接在终端里就很难显示成用户熟悉的路径。

数据流：进去的是已经解析好的 Url 对象。它先尝试用标准方式转成本地文件路径；如果失败，就手动拼回路径，兼容网络共享路径和 Windows 盘符路径。最后统一斜杠格式。出来的是路径字符串；如果无法转换则返回空。

调用关系：它由 parse_local_link_target 在遇到 file:// 链接时调用。它负责把网址世界的话翻译成本地文件系统的话，再交回解析流程继续处理位置片段。

调用图：调用 1 个内部函数（normalize_local_link_path_text）；被 1 处调用（parse_local_link_target）；外部调用 5 个（host_str, path, to_file_path, format!, matches!）。

fn normalize_local_link_path_text(path_text: &str) -> String

作用：统一本地路径里的斜杠写法，把 Windows 常见的反斜杠换成正斜杠。这样显示、比较、裁剪路径时不会因为系统差异出错。

数据流：进去的是任意路径文本。如果是 Windows 网络共享路径开头的 \\，它会保留成 // 这种形式；其他反斜杠都会替换成 /。出来的是统一后的路径字符串。

调用关系：它是多个路径函数共用的小工具，被 expand_local_link_path、file_url_to_local_path_text 和 display_local_link_path 使用。它让后续判断绝对路径、去掉当前目录前缀这些步骤有统一标准。

调用图：被 3 处调用（display_local_link_path, expand_local_link_path, file_url_to_local_path_text）；外部调用 1 个（format!）。

fn is_absolute_local_link_path(path_text: &str) -> bool

作用：判断一个本地路径是不是绝对路径，也就是从根位置或盘符开始的完整路径。这样显示时才能决定要不要尝试缩短它。

数据流：进去的是已经基本规范化的路径文本。它检查 Unix 的 /、网络路径的 //，以及 Windows 的 C:/ 这类盘符格式。出来是真或假。

调用关系：它被 display_local_link_path 调用。只有判断为绝对路径时，显示逻辑才会考虑把当前工作目录前缀去掉。

调用图：被 1 处调用（display_local_link_path）；外部调用 1 个（matches!）。

fn trim_trailing_local_path_separator(path_text: &str) -> &str

作用：去掉路径末尾多余的 /，但不破坏根目录这种特殊路径。这样比较两个路径时，不会因为一个多了斜杠就认为不一样。

数据流：进去的是路径文本。它先保护 /、//、C:/ 这类根路径不被削坏；其他路径则去掉末尾的 /。出来的是借用原文本的一段切片。

调用关系：它被 strip_local_path_prefix 调用，是做路径前缀裁剪前的清理步骤。它保证 /tmp/app 和 /tmp/app/ 能被当成同一个目录来比较。

调用图：被 1 处调用（strip_local_path_prefix）；外部调用 1 个（matches!）。

fn strip_local_path_prefix(path_text: &'a str, cwd_text: &str) -> Option<&'a str>

作用：如果一个绝对路径位于当前工作目录下面，就把前面的当前目录去掉，只留下相对部分。这样界面里显示的路径更短、更好读。

数据流：进去的是目标路径和当前工作目录路径。它先去掉两边末尾多余斜杠；如果两者完全相同，就返回空，表示没剩下可显示的相对部分；如果当前目录是根目录，就特殊处理；否则尝试裁掉当前目录加后面的 /。出来的是可显示的相对路径片段，或者空。

调用关系：它被 display_local_link_path 调用。它依赖 trim_trailing_local_path_separator 先把路径整理干净，是“把长路径变短”的核心步骤。

调用图：调用 1 个内部函数（trim_trailing_local_path_separator）；被 1 处调用（display_local_link_path）。

fn display_local_link_path(path_text: &str, cwd: Option<&Path>) -> String

作用：决定本地链接最终在界面上显示成什么路径。它会尽量把当前目录下的绝对路径显示成短路径，同时保留其他绝对路径，避免让用户误会。

数据流：进去的是目标路径文本，以及可选的当前工作目录。它先统一斜杠；如果不是绝对路径，直接原样返回；如果是绝对路径且给了当前目录，就尝试去掉当前目录前缀。出来的是最终给用户看的路径字符串。

调用关系：它被 render_local_link_target 调用，是链接渲染前的展示整理步骤。它把判断绝对路径的事交给 is_absolute_local_link_path，把裁剪前缀的事交给 strip_local_path_prefix。

调用图：调用 3 个内部函数（is_absolute_local_link_path, normalize_local_link_path_text, strip_local_path_prefix）；被 1 处调用（render_local_link_target）。

fn lines_to_strings(text: &Text<'_>) -> Vec<String>

作用：测试用的小帮手，把渲染结果里的多段样式文字合并成普通字符串。这样测试可以只关心每一行显示了什么字。

数据流：进去的是渲染后的 Text 对象，里面每行有多个 span，也就是带样式的一小段文字。它逐行把 span 的内容拼起来。出来的是字符串列表。

调用关系：它服务很多换行和代码块测试。测试函数先调用渲染函数，再用它把结果变简单，最后和期望文本比较。

fn wraps_plain_text_when_width_provided()

作用：确认普通段落在给定宽度时会自动换行。这样终端窄的时候，文字不会横向溢出。

数据流：进去的是一段普通英文句子和宽度 16。测试渲染它，取出每行文字，再检查是否被拆成三行。结果是通过或失败的测试断言。

调用关系：它直接测试 render_markdown_text_with_width 的基础换行能力，并用 tests::lines_to_strings 辅助读取结果。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn wraps_list_items_preserving_indent()

作用：确认列表项换行后会保留缩进。这样第二行不会看起来像一个新的普通段落。

数据流：进去的是一个项目符号列表和宽度 14。渲染后它检查第一行带 -，续行用两个空格缩进。出来的是测试断言结果。

调用关系：它覆盖列表排版路径，调用 render_markdown_text_with_width，再借助 tests::lines_to_strings 比较最终行文本。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn wraps_nested_lists()

作用：确认嵌套列表在窄宽度下仍然保持层级。外层和内层列表换行后都要缩进正确。

数据流：进去的是外层列表和内层列表组成的 Markdown，以及宽度 20。渲染后测试逐行检查外层续行、内层项目符号和内层续行的缩进。出来的是测试是否通过。

调用关系：它测试 render_markdown_text_with_width 对复杂列表结构的处理，确保列表嵌套不会在排版时被压扁。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn wraps_ordered_lists()

作用：确认有编号的列表换行后，后续行会对齐正文，而不是对齐到最左边。这样编号列表读起来仍然清楚。

数据流：进去的是一个 1. 开头的列表项和宽度 18。渲染后它检查第一行带编号，后面几行用三个空格缩进。出来的是断言结果。

调用关系：它测试 render_markdown_text_with_width 的有序列表排版规则，和无序列表测试一起守住列表显示质量。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn wraps_blockquotes()

作用：确认引用块换行后每一行都保留 > 符号。这样用户能看出这些行都属于引用内容。

数据流：进去的是一段 > 开头的引用和宽度 22。渲染后它检查每行都以 > 加空格开头，并按宽度拆分。出来的是测试断言结果。

调用关系：它调用 render_markdown_text_with_width，专门覆盖引用块的换行前缀处理。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn wraps_blockquotes_inside_lists()

作用：确认列表里面的引用块换行时，既保留列表缩进，也保留引用符号。这样混合结构不会乱套。

数据流：进去的是一个列表项和它下面的引用块，宽度 24。渲染后检查引用行前面有列表缩进和 >。出来的是测试结果。

调用关系：它测试 render_markdown_text_with_width 处理“列表套引用”的场景，是列表和引用两套排版规则的组合验证。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn wraps_list_items_containing_blockquotes()

作用：确认编号列表中的引用块换行仍然对齐正确。它防止列表编号、缩进和引用符号互相干扰。

数据流：进去的是一个编号列表项，下面接引用文本，宽度 24。渲染后检查列表行和两行引用行的文本。出来的是断言通过或失败。

调用关系：它调用 render_markdown_text_with_width，覆盖“有序列表加引用”的复合排版路径。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn does_not_wrap_code_blocks()

作用：确认代码块里的长行不会被自动换行。代码讲究原样显示，随便折行可能改变可读性甚至含义。

数据流：进去的是围栏代码块和很窄的宽度 10。渲染后测试期望仍然只有原始那一整行代码。出来的是测试断言结果。

调用关系：它测试 render_markdown_text_with_width 对代码块的特殊保护，和普通文字自动换行形成对比。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn does_not_split_long_url_like_token_without_scheme()

作用：确认很长、像网址的单个词不会被硬拆开，即使它没有 https:// 这种协议开头。这样路径或接口名不会被切得难以复制。

数据流：进去的是一长串类似 URL 的文本和宽度 24。渲染后测试统计完整长串是否仍出现在同一行。出来的是断言结果。

调用关系：它测试 render_markdown_text_with_width 的分词换行策略，防止长 token 被错误切碎。

调用图：调用 1 个内部函数（render_markdown_text_with_width）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn fenced_code_info_string_with_metadata_highlights()

作用：确认代码块语言后面带额外信息时，仍然能识别出语言并做语法高亮。比如 rust,no_run 也应该按 Rust 代码上色。

数据流：进去的是几种带元数据的 Rust 围栏代码块。测试渲染后检查是否有 RGB 颜色样式。出来的是高亮是否生效的断言结果。

调用关系：它调用 render_markdown_text，覆盖代码块信息字符串解析和语法高亮之间的衔接。

调用图：调用 1 个内部函数（render_markdown_text）；外部调用 2 个（assert!, format!）。

fn crlf_code_block_no_extra_blank_lines()

作用：确认 Windows 风格换行的代码块不会被多插入空白行。否则同一段代码在不同系统输入下显示会不一致。

数据流：进去的是带 CRLF 换行的 Rust 代码块。渲染后提取每行文字，检查只有两行代码，没有夹杂多余空行。出来的是测试断言结果。

调用关系：它测试 render_markdown_text 对代码块文本事件的拼接方式，防止底层解析器拆分文本后渲染器错误加分隔符。

调用图：调用 1 个内部函数（render_markdown_text）；外部调用 2 个（assert_eq!, lines_to_strings）。

fn wrap_cell_preserves_hard_break_lines()

作用：确认表格单元格里的强制换行会被保留。也就是说，用户明确分成两行的内容，不会被包装函数合成一行。

数据流：进去的是一个手工构造的表格单元格，中间有 hard_break。测试创建渲染器并调用 wrap_cell，再把结果行拼成字符串。出来的是两行文本的断言结果。

调用关系：它直接测试 W::wrap_cell，保证表格换行算法尊重单元格内部的硬换行。

调用图：外部调用 4 个（new, assert_eq!, empty, default）。

fn make_cell(text: &str) -> TableCell

作用：测试用的小工厂，用一段普通文字快速做出一个表格单元格。这样后面的表格测试不用反复写构造代码。

数据流：进去的是文本字符串。它创建默认 TableCell，把这段文字作为普通 span 放进去。出来的是一个 TableCell。

调用关系：它被多种表格列分类和溢出行测试调用，是测试数据准备的辅助函数。

调用图：外部调用 2 个（raw, default）。

fn make_body_row(cells: Vec<TableCell>, has_table_pipe_syntax: bool) -> TableBodyRow

作用：测试用的小工厂，用一组单元格快速做出表格正文行。它还能标记这一行是不是来自标准的管道表格写法。

数据流：进去的是单元格列表和一个布尔值，表示是否有表格管道语法。它把两者装进 TableBodyRow。出来的是测试用表格行对象。

调用关系：它被溢出行相关测试调用，帮助构造不同形态的表格行来喂给 W::is_spillover_row。

fn column_classification_narrative_by_word_count()

作用：确认表格列里如果是长句描述，会被识别成叙述型列。叙述型列通常需要更适合阅读的宽度。

数据流：进去的是两列表格：一列短 ID，一列长描述。测试收集列指标后检查第一列是 Compact，第二列是 Narrative。出来的是断言结果。

调用关系：它测试 W::collect_table_column_metrics 的列类型判断，确保表格排版能根据内容性质分配宽度。

调用图：外部调用 3 个（collect_table_column_metrics, assert_eq!, vec!）。

fn column_classification_token_heavy_by_url_like_tokens()

作用：确认主要由长 URL 组成的列会被识别成 token-heavy，也就是长块状词很多的列。这样的列换行策略和普通句子不同。

数据流：进去的是一列表格，单元格里都是长网址。测试收集列指标，并检查列类型是 TokenHeavy。出来的是断言结果。

调用关系：它测试 W::collect_table_column_metrics 对长网址类内容的识别，帮助表格渲染避免把 URL 排得太难用。

调用图：外部调用 3 个（collect_table_column_metrics, assert_eq!, vec!）。

fn column_classification_token_heavy_for_local_path_lists()

作用：确认包含很多本地文件路径的列也会被识别成 token-heavy。文件路径和网址一样，常常是长 token，不能按普通句子处理。

数据流：进去的是一列表格，里面是多个源码文件路径和行号。测试计算列指标后检查类型是 TokenHeavy。出来的是断言结果。

调用关系：它覆盖 W::collect_table_column_metrics 对本地路径列表的判断，保证文件清单类表格排版更稳。

调用图：外部调用 3 个（collect_table_column_metrics, assert_eq!, vec!）。

fn column_classification_compact_all_short()

作用：确认全是短值的表格列会被识别成紧凑型列。这样短状态、数字这类内容不会占太多宽度。

数据流：进去的是两列短文本和数字。测试收集列指标后检查两列都是 Compact。出来的是断言结果。

调用关系：它测试 W::collect_table_column_metrics 的基础分类，和叙述型、长 token 型测试一起覆盖三种列风格。

调用图：外部调用 3 个（collect_table_column_metrics, assert_eq!, vec!）。

fn preferred_floor_narrative_retains_readable_width()

作用：确认叙述型列在压缩表格宽度时，仍保留一个比较能读的最低宽度。否则长句会被切得太碎。

数据流：进去的是两组手工列指标和最小列宽 3。测试调用 preferred_column_floor，检查宽内容得到 16，较短内容保留 12。出来的是断言结果。

调用关系：它直接测试 W::preferred_column_floor，验证表格宽度分配里“最低保底宽度”的规则。

调用图：外部调用 1 个（assert_eq!）。

fn preferred_floor_token_heavy_retains_readable_width()

作用：确认长 token 很多的列也会保留一个可用的最低宽度。这样长网址或路径不会在极窄列里变得特别难看。

数据流：进去的是一个 TokenHeavy 列指标，最大宽度很大、最长 token 很长。测试计算首选底线宽度，期望是 16。出来的是断言结果。

调用关系：它测试 W::preferred_column_floor 针对 TokenHeavy 列的规则，和叙述型列的保底测试互补。

调用图：外部调用 1 个（assert_eq!）。

fn preferred_floor_compact_uses_body_token()

作用：确认紧凑型列的最低宽度主要看表头和正文里的短 token，并且正文 token 会有上限。这样短列不会被长偶发值撑得太夸张。

数据流：进去的是两组 Compact 列指标。第一组正文最长 token 是 12，期望底线 12；第二组正文 token 是 20，但按规则封顶到 16。出来的是两次断言结果。

调用关系：它直接测试 W::preferred_column_floor 的 Compact 分支，保证紧凑列在表格压缩时行为合理。

调用图：外部调用 1 个（assert_eq!）。

fn next_column_to_shrink_prefers_token_heavy_then_narrative()

作用：确认表格太宽需要缩小时，优先缩长 token 列，其次缩叙述列，最后才动紧凑列。这样最重要的短状态列更不容易被挤坏。

数据流：进去的是当前列宽、各列最低宽度和三种列指标。第一次三列都能缩，期望选 TokenHeavy；第二次 TokenHeavy 已到底线，期望选 Narrative。出来的是断言结果。

调用关系：它测试 W::next_column_to_shrink，是表格自适应宽度流程里决定“先压哪一列”的策略验证。

调用图：外部调用 2 个（next_column_to_shrink, assert_eq!）。

fn spillover_detects_single_cell_row()

作用：确认没有管道表格语法的单单元格行会被当成溢出行。溢出行通常不是正常表格数据，而是前面内容漏出来的一部分。

数据流：进去的是一个只有一个单元格、且没有表格管道语法的行。测试调用 is_spillover_row，期望返回真。出来的是断言结果。

调用关系：它测试 W::is_spillover_row 的基础判断，使用 make_body_row 和 make_cell 构造输入。

调用图：外部调用 3 个（assert!, make_body_row, vec!）。

fn spillover_keeps_single_cell_row_with_table_pipe_syntax()

作用：确认如果单单元格行确实来自管道表格语法，就不要误判成溢出行。这样合法的稀疏表格不会被丢掉。

数据流：进去的是一个只有一个单元格、但标记为有管道语法的行。测试调用 is_spillover_row，期望返回假。出来的是断言结果。

调用关系：它测试 W::is_spillover_row 对表格来源标记的尊重，避免过度清理。

调用图：外部调用 3 个（assert!, make_body_row, vec!）。

fn spillover_detects_html_content()

作用：确认只在第一格出现 HTML 内容、其他格为空的行会被识别成溢出行。这通常说明 Markdown 表格解析时把 HTML 块吞进了表格区域。

数据流：进去的是三格行，第一格是 <div>content</div>，后两格为空，且没有管道语法。测试期望 is_spillover_row 返回真。出来的是断言结果。

调用关系：它测试 W::is_spillover_row 对 HTML 噪声行的识别，帮助表格渲染过滤异常内容。

调用图：外部调用 3 个（assert!, make_body_row, vec!）。

fn spillover_detects_label_followed_by_html()

作用：确认像“HTML block:”这样的标签，如果下一行是 HTML，也会被当成溢出行。这样 HTML 块的说明文字不会混进表格数据。

数据流：进去的是当前行第一格为 HTML block:，下一行第一格为 <div>x</div>。测试调用 is_spillover_row 并期望为真。出来的是断言结果。

调用关系：它测试 W::is_spillover_row 使用下一行上下文做判断，而不是只看当前行。

调用图：外部调用 3 个（assert!, make_body_row, vec!）。

fn spillover_detects_trailing_html_label()

作用：确认最后一行如果只是 HTML block: 这种尾随标签，也会被识别成溢出行。即使没有下一行，也不应把它当成正常表格数据。

数据流：进去的是第一格为 HTML block:、其他格为空的行，并且没有下一行。测试期望 is_spillover_row 返回真。出来的是断言结果。

调用关系：它测试 W::is_spillover_row 在缺少下一行时的兜底判断。

调用图：外部调用 3 个（assert!, make_body_row, vec!）。

fn spillover_keeps_normal_multi_cell_row()

作用：确认正常多列都有内容的表格行不会被误判成溢出行。否则真正的数据会被错误过滤。

数据流：进去的是三格都非空的普通表格行。测试调用 is_spillover_row，期望返回假。出来的是断言结果。

调用关系：它给 W::is_spillover_row 提供反例测试，确保溢出检测不会太激进。

调用图：外部调用 3 个（assert!, make_body_row, vec!）。

fn spillover_keeps_label_when_next_is_not_html()

作用：确认普通标签行后面如果不是 HTML，就不要当成溢出行。比如 Status: 后面是 ok，这是正常内容。

数据流：进去的是当前行 Status: 和下一行 ok。测试调用 is_spillover_row，期望返回假。出来的是断言结果。

调用关系：它测试 W::is_spillover_row 的上下文判断是否精确，只针对 HTML 相关异常触发。

调用图：外部调用 3 个（assert!, make_body_row, vec!）。

fn annotates_explicit_web_link_label_and_visible_destination()

作用：确认普通 Markdown 网页链接会被标注成可点击链接，而且标签文字和显示出来的目标都指向同一个网址。

数据流：进去的是一句包含 docs 的 Markdown。渲染成带行信息的结果后，测试收集所有 hyperlink，检查数量为 2 且目标一致。出来的是断言结果。

调用关系：它测试 render_markdown_lines_with_width_and_cwd 的网页链接标注能力，确保显示文字和附加链接信息同步。

调用图：调用 1 个内部函数（render_markdown_lines_with_width_and_cwd）；外部调用 2 个（assert!, assert_eq!）。

fn wrapped_table_url_fragments_keep_complete_web_destination()

作用：确认表格里的长网址换行后，每一段仍然保留完整点击目标。用户点任何一段，都应该打开完整网址，而不是残缺片段。

数据流：进去的是一个包含长 URL 的 Markdown 表格和很窄的宽度 32。渲染后测试找出带链接的行，确认有多行，并且每个链接目标都是完整 destination。出来的是断言结果。

调用关系：它测试 render_markdown_lines_with_width_and_cwd 在表格换行和超链接标注同时发生时的正确性。

调用图：调用 1 个内部函数（render_markdown_lines_with_width_and_cwd）；外部调用 2 个（assert!, format!）。

fn key_value_table_keeps_web_annotations()

作用：确认很窄的多列表格里，网页链接标注不会丢失。即使表格排版退化或压缩，链接仍要能点。

数据流：进去的是六列表格，其中第一格是长网址，宽度只有 20。渲染后收集所有链接目标，检查非空且全部等于原网址。出来的是断言结果。

调用关系：它测试 render_markdown_lines_with_width_and_cwd 的表格链接保留能力，特别是键值型或窄表格场景。

调用图：调用 1 个内部函数（render_markdown_lines_with_width_and_cwd）；外部调用 2 个（assert!, format!）。

fn does_not_annotate_code_or_non_web_markdown_links()

作用：确认代码里的 URL、mailto 链接，以及目标不是网页的网址，不会被错误标成可点击网页链接。这样界面不会误导用户。

数据流：进去的是包含行内代码、代码块、mailto 链接和表格链接标签的 Markdown。渲染后测试所有行的 hyperlink 都为空。出来的是断言结果。

调用关系：它测试 render_markdown_lines_with_width_and_cwd 的链接过滤规则，确保只给真正的网页目标加注解。

调用图：调用 1 个内部函数（render_markdown_lines_with_width_and_cwd）；外部调用 1 个（assert!）。

fn pipe_table_fallback_keeps_web_annotations()

作用：确认表格在极窄宽度下走备用排版时，网页链接标注仍然正确，同时代码里的 URL 不会被标注。

数据流：进去的是一个表格：一格裸 URL，一格代码 URL，一格 Markdown 链接标签，宽度只有 5。渲染后收集链接目标，检查包含裸 URL 和 Markdown 链接目标，不包含代码 URL，也不把显示标签误当目标。出来的是断言结果。

调用关系：它测试 render_markdown_lines_with_width_and_cwd 在管道表格备用渲染路径中的链接处理，是表格、代码和链接规则的综合验证。

调用图：调用 1 个内部函数（render_markdown_lines_with_width_and_cwd）；外部调用 2 个（assert!, format!）。

fn append_markdown(
    markdown_source: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
    lines: &mut Vec<Line<'static>>,
)

作用：把一段普通 Markdown 渲染成终端界面的一行行文字，并追加到已有列表里。适合已经整理好的计划块、历史内容等，不会额外拆掉代码围栏。

数据流：输入是一段 Markdown、可选宽度、可选工作目录，以及一个要追加内容的行列表。它先把 Markdown 交给 render_markdown_text_with_width_and_cwd 渲染成带样式的行，再用 push_owned_lines 把这些行复制进外部传入的列表。结果是原来的列表后面多了可直接显示的终端文字行。

调用关系：它是普通 Markdown 渲染的入口，被提交完整行、收尾并排空流式内容、以及多项测试使用。它自己不解析细节，而是把真正渲染交给 render_markdown_text_with_width_and_cwd，再把结果交给 push_owned_lines 放入输出容器。

调用图：调用 2 个内部函数（render_markdown_text_with_width_and_cwd, push_owned_lines）；被 13 处调用（append_markdown_keeps_ordered_list_line_unsplit_in_context, append_markdown_matches_tui_markdown_for_ordered_item, append_markdown_preserves_full_text_line, citations_render_as_plain_text, indented_code_blocks_preserve_leading_whitespace, commit_complete_lines, finalize_and_drain, assert_streamed_equals_full, heading_not_inlined_when_split_across_chunks, loose_list_with_split_dashes_matches_full_render (+3 more)）。

fn append_markdown_agent(
    markdown_source: &str,
    width: Option<usize>,
    lines: &mut Vec<Line<'static>>,
)

作用：这是测试环境下使用的 AI 回复渲染入口。它会先修正 AI 常把表格包进 markdown 代码块的问题，再渲染成终端行。

数据流：输入是 AI 回复文本、可选宽度和输出行列表。它先调用 unwrap_markdown_fences，把符合条件的 ``md 或 ``markdown 表格围栏去掉；然后调用 render_markdown_text_with_width_and_cwd 渲染；最后用 push_owned_lines 追加到输出列表。出来的是更符合用户预期的显示结果，比如表格会被画成表格而不是代码。

调用关系：它被大量围绕 AI 表格显示的测试调用，也被一些流式收集相关测试覆盖。它位于“AI 原文”和“终端渲染器”之间，先做安全的文本正规化，再把活交给通用 Markdown 渲染器。

调用图：调用 3 个内部函数（unwrap_markdown_fences, render_markdown_text_with_width_and_cwd, push_owned_lines）；被 20 处调用（append_markdown_agent_keeps_markdown_fence_when_content_is_not_table, append_markdown_agent_keeps_non_markdown_fences_as_code, append_markdown_agent_unwraps_markdown_fences_for_no_outer_table_rendering, append_markdown_agent_unwraps_markdown_fences_for_single_column_table, append_markdown_agent_unwraps_markdown_fences_for_table_rendering, append_markdown_agent_unwraps_markdown_fences_for_two_column_no_outer_table, collector_source_chunks_round_trip_into_agent_fence_unwrapping, controller_handles_table_immediately_after_heading, controller_holds_blockquoted_table_tail_until_stable, controller_keeps_markdown_fenced_no_outer_tables_mutable_until_finalize (+10 more)）。

fn render_markdown_agent_with_links_and_cwd(
    markdown_source: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
) -> Vec<HyperlinkLine>

作用：把 AI 回复渲染成带超链接信息的终端行。它既处理 AI 表格围栏问题，也保留路径、链接这类可点击信息。

数据流：输入是 Markdown 文本、可选宽度和可选工作目录。它先用 unwrap_markdown_fences 规范文本，再调用 render_markdown_lines_with_width_and_cwd 生成 HyperlinkLine，也就是带链接元数据的一行行内容。输出是一个新的行列表，不直接修改外部列表。

调用关系：它被 display_hyperlink_lines、render_source、stable_prefix_len_for_source_start 等显示路径调用。它是带链接显示流程里的入口，先清理 AI Markdown，再把渲染和链接识别交给 markdown_render 模块。

调用图：调用 2 个内部函数（unwrap_markdown_fences, render_markdown_lines_with_width_and_cwd）；被 4 处调用（display_hyperlink_lines, display_hyperlink_lines, render_source, stable_prefix_len_for_source_start）。

fn unwrap_markdown_fences(markdown_source: &'a str) -> Cow<'a, str>

作用：专门检查并去掉 AI 回复中包住表格的 ``md 或 ``markdown 围栏。这样 Markdown 表格能被当成真正表格解析，而不是被当成代码块。

数据流：输入是一整段 Markdown 字符串。它先快速检查有没有 ``` 或 ~~~，没有就直接借用原文返回，避免浪费内存；如果有，就逐行扫描，识别代码围栏的开始和结束。遇到 md/markdown 围栏时，它先暂存里面的内容，等看到结束围栏后再判断里面是否有表格结构；有表格就只输出内容、去掉围栏，没有表格就原样输出。未闭合的 markdown 围栏会把开头和内容补回去，避免半截流式文本被错误改写。输出可能是借用原文，也可能是一份新字符串。

调用关系：它被 append_markdown_agent、render_markdown_agent_with_links_and_cwd 以及多项边界测试调用。它处在渲染前的预处理位置，作用像安检员：只放行真正需要拆开的 markdown 表格围栏，其它代码块和可疑情况都尽量保持原样。

调用图：被 6 处调用（append_markdown_agent, render_markdown_agent_with_links_and_cwd, append_markdown_agent_keeps_markdown_fence_with_blank_line_between_header_and_delimiter, append_markdown_agent_keeps_non_blockquoted_markdown_fence_with_blockquote_table_example, append_markdown_agent_unwraps_blockquoted_markdown_fence_table, unwrap_markdown_fences_repro_keeps_fence_without_header_delimiter_pair）；外部调用 7 个（MarkdownCandidate, Passthrough, new, Borrowed, Owned, with_capacity, new）。

fn lines_to_strings(lines: &[Line<'static>]) -> Vec<String>

作用：把测试里渲染出来的 Line 转成普通字符串，方便比较结果。Line 里可能有多个带样式的小片段，这个函数把它们拼回一行文字。

数据流：输入是一组 ratatui 的 Line。它遍历每一行，再遍历这一行里的所有 span，也就是一小段文字，把内容拼成 String。输出是 Vec<String>，每个字符串对应屏幕上的一行可见文字。

调用关系：它是测试辅助函数，被多个测试用来检查渲染结果。测试先调用 append_markdown 或 append_markdown_agent 得到带样式行，再交给它去掉样式外壳，只看最终文字是否正确。

调用图：外部调用 1 个（iter）。

fn citations_render_as_plain_text()

作用：验证类似引用标记的特殊文本不会被 Markdown 渲染器乱改。用户看到的文件引用应该保持原样。

数据流：输入是一段包含“【F:/x.rs†L1】”这类引用文字的 Markdown。测试创建空输出列表，调用 append_markdown 渲染，再用 lines_to_strings 转成普通文本，最后断言两行内容和输入期望一致。

调用关系：它直接测试 append_markdown 的普通渲染路径。它不关心围栏拆解，只确保通用渲染器不会把引用样式的文本误解析成别的东西。

调用图：调用 1 个内部函数（append_markdown）；外部调用 3 个（new, assert_eq!, lines_to_strings）。

fn indented_code_blocks_preserve_leading_whitespace()

作用：验证缩进代码块前面的空格不会丢。对代码来说，开头空格常常有意义，显示时不能被悄悄删掉。

数据流：输入是一段包含四个空格缩进代码行的 Markdown。测试调用 append_markdown 渲染，然后转成字符串列表，最后确认输出里仍然有“ code 1”这行，并且前后空行也保留。

调用关系：它测试 append_markdown 经过通用 Markdown 渲染器后的基础行为。这个测试保护的是“代码块显示不要破坏空白”的体验。

调用图：调用 1 个内部函数（append_markdown）；外部调用 3 个（new, assert_eq!, lines_to_strings）。

fn append_markdown_preserves_full_text_line()

作用：验证一整行普通文本不会被无故拆开或截断。聊天界面里的普通回复应该按完整句子显示。

数据流：输入是一句较长但普通的文本。测试调用 append_markdown 渲染到输出列表，先确认只生成一行，再把这一行所有片段拼起来，确认和预期完整文本一致。

调用关系：它直接覆盖 append_markdown 的普通文本路径。它保证渲染器在没有特殊 Markdown 语法时不会制造多余换行。

调用图：调用 1 个内部函数（append_markdown）；外部调用 2 个（new, assert_eq!）。

fn append_markdown_matches_tui_markdown_for_ordered_item()

作用：验证有序列表的一项，比如“1. Tight item”，会按一整行显示。这样列表在终端里看起来才自然。

数据流：输入是一个只有一项的有序列表 Markdown。测试调用 append_markdown，再把结果转成字符串，最后确认输出就是“1. Tight item”。

调用关系：它测试 append_markdown 对列表语法的渲染表现。这个测试防止列表编号和正文被拆成不符合预期的两行。

调用图：调用 1 个内部函数（append_markdown）；外部调用 3 个（new, assert_eq!, lines_to_strings）。

fn append_markdown_keeps_ordered_list_line_unsplit_in_context()

作用：验证有序列表放在普通文字后面时，也不会被拆成“1.”一行和内容一行。它检查的是更接近真实聊天内容的场景。

数据流：输入先有一句说明文字，下一行是“1. Tight item”。测试调用 append_markdown 渲染，转成字符串后，确认结果里能找到完整的列表行，同时确认没有出现编号和正文分离的连续两行。

调用关系：它继续保护 append_markdown 的列表显示行为。和单独列表项测试相比，它检查列表在上下文中仍然稳定。

调用图：调用 1 个内部函数（append_markdown）；外部调用 3 个（new, assert!, lines_to_strings）。

fn append_markdown_agent_unwraps_markdown_fences_for_table_rendering()

作用：验证 AI 把表格包在 ```markdown 里时，测试入口能拆掉围栏并把它画成表格。用户看到的应该是表格，不是一段代码。

数据流：输入是一个 markdown 代码围栏，里面有标准表格。测试调用 append_markdown_agent，转成字符串后，检查输出里有表格线条字符和表格数据位置，说明表格渲染生效。

调用关系：它测试 append_markdown_agent 的核心价值：先调用 unwrap_markdown_fences，再走 Markdown 渲染。它是表格围栏拆解功能的基本用例。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 3 个（new, assert!, lines_to_strings）。

fn append_markdown_agent_unwraps_markdown_fences_for_no_outer_table_rendering()

作用：验证没有外侧竖线的 Markdown 表格也能被识别并渲染成表格。Markdown 表格不一定都写成“| A | B |”这种完整样子。

数据流：输入是 ```md 围栏中的三列表格，表头行没有最外侧竖线。测试调用 append_markdown_agent，检查输出有表格横线和排好版的表头，同时确认原始表头文本没有以代码样子原封不动出现。

调用关系：它覆盖 append_markdown_agent 和 unwrap_markdown_fences 对宽松表格写法的支持。这个测试让围栏拆解不只适用于最标准的表格格式。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 3 个（new, assert!, lines_to_strings）。

fn append_markdown_agent_unwraps_markdown_fences_for_two_column_no_outer_table()

作用：验证两列表格即使没有外侧竖线，也会被拆围栏并正常画表。两列表格是很常见的简短说明格式。

数据流：输入是 ```md 围栏中的两列表格。测试调用 append_markdown_agent 后，把渲染结果转成字符串，确认出现表格线和排版后的“left/right”，并确认原始“A | B”没有作为普通代码行留下。

调用关系：它是对 append_markdown_agent 表格识别能力的补充测试。它确保两列这种较小表格不会被漏掉。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 3 个（new, assert!, lines_to_strings）。

fn append_markdown_agent_unwraps_markdown_fences_for_single_column_table()

作用：验证单列表格也能被当作表格处理，而不是因为只有一列就被忽略。

数据流：输入是 ```md 围栏中的单列表格。测试调用 append_markdown_agent，检查输出里有表格线条，同时确认原始“| Only |”没有以代码文本形式显示。

调用关系：它测试 append_markdown_agent 通过 unwrap_markdown_fences 处理边界表格的能力。这个测试防止表格识别只照顾多列表格。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 3 个（new, assert!, lines_to_strings）。

fn append_markdown_agent_keeps_non_markdown_fences_as_code()

作用：验证 Rust 等非 Markdown 代码块不会被拆掉。真正的代码块即使看起来像表格，也应该按代码显示。

数据流：输入是 ```rust 围栏，里面故意放了像表格的文本。测试调用 append_markdown_agent 后转成字符串，确认输出就是三行原始内容，没有表格线条或表格排版。

调用关系：它保护 unwrap_markdown_fences 的保守原则：只有 md/markdown 围栏才可能被拆。append_markdown_agent 会经过这个预处理，所以必须保证代码语言不被误伤。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 3 个（new, assert_eq!, lines_to_strings）。

fn append_markdown_agent_unwraps_blockquoted_markdown_fence_table()

作用：验证引用块里的 markdown 表格围栏也能被识别并拆掉。引用块就是每行前面带“>”的 Markdown 区域。

数据流：输入是每行都带“>”的 ``markdown 表格围栏。测试直接调用 unwrap_markdown_fences，然后确认结果里不再包含 ``，说明围栏被去掉。

调用关系：它直接测试 unwrap_markdown_fences，而不是完整渲染流程。它覆盖了带引用前缀时开围栏、关围栏和表格检测如何配合。

调用图：调用 1 个内部函数（unwrap_markdown_fences）；外部调用 1 个（assert!）。

fn append_markdown_agent_keeps_non_blockquoted_markdown_fence_with_blockquote_table_example()

作用：验证普通 markdown 围栏里如果只是放了一个引用形式的表格示例，不会被误拆。因为这可能是用户想展示的代码内容。

数据流：输入是普通 ```markdown 围栏，但里面的表格行都带“>”。测试调用 unwrap_markdown_fences，最后确认输出和输入完全一样。

调用关系：它测试 unwrap_markdown_fences 的谨慎边界。前一个测试是“围栏本身在引用块里”，这个测试是“围栏不在引用块里但内容像引用”，两者不能混淆。

调用图：调用 1 个内部函数（unwrap_markdown_fences）；外部调用 1 个（assert_eq!）。

fn append_markdown_agent_keeps_markdown_fence_when_content_is_not_table()

作用：验证 markdown 围栏里如果不是表格，就仍然按代码块显示。比如用户可能就是想展示“bold”这段 Markdown 源码。

数据流：输入是 ```markdown 围栏，里面只有加粗语法文本。测试调用 append_markdown_agent，转成字符串后确认输出是字面量“bold”，而不是加粗后的内容。

调用关系：它覆盖 append_markdown_agent 的一个关键防误伤场景。unwrap_markdown_fences 只有看到表格结构才拆围栏，否则让后面的渲染器继续把它当代码块。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 3 个（new, assert_eq!, lines_to_strings）。

fn unwrap_markdown_fences_repro_keeps_fence_without_header_delimiter_pair()

作用：验证只有像表格的几行还不够，必须有连续的表头行和分隔行才拆围栏。这样可以避免把普通文本误判成表格。

数据流：输入是 ```markdown 围栏，里面有竖线，也有类似分隔符的行，但表头和分隔行没有形成正确相邻关系。测试调用 unwrap_markdown_fences，确认输出和输入完全相同。

调用关系：它直接保护 unwrap_markdown_fences 的表格判断规则。这个测试来自复现场景，防止以后放宽规则时重新引入误拆问题。

调用图：调用 1 个内部函数（unwrap_markdown_fences）；外部调用 1 个（assert_eq!）。

fn append_markdown_agent_keeps_markdown_fence_with_blank_line_between_header_and_delimiter()

作用：验证表头和分隔行中间有空行时，不算真正的 Markdown 表格，因此围栏不能被拆。Markdown 表格要求这两行挨着。

数据流：输入是 ```markdown 围栏，表头后面空了一行才出现分隔行。测试调用 unwrap_markdown_fences，确认输出仍然等于原文。

调用关系：它直接测试 unwrap_markdown_fences 的严格性。它和其它表格拆围栏测试一起，说明这个功能不是看到竖线就拆，而是按 Markdown 表格的基本结构来判断。

调用图：调用 1 个内部函数（unwrap_markdown_fences）；外部调用 1 个（assert_eq!）。

fn new(width: Option<usize>, cwd: &Path) -> Self

作用：创建一个新的 Markdown 流收集器。调用者用它开始接收一段新的流式 Markdown 输出。

数据流：输入显示宽度和当前目录路径 → 它准备一个空字符串作为缓存，把“已经交出去多少字节”记为 0，并在测试时保存当前目录 → 输出一个干净的新收集器。

调用关系：测试辅助函数 simulate_stream_markdown_for_tests 和多项测试都会先调用它来搭好收集器；它内部会创建空 String，并在测试环境把路径复制成 PathBuf，后续 push_delta、commit 和 finalize 都围绕这个对象工作。

调用图：被 9 处调用（simulate_stream_markdown_for_tests, collector_source_chunks_round_trip_into_agent_fence_unwrapping, finalize_commits_partial_line, heading_not_inlined_when_split_across_chunks, heading_starts_on_new_line_when_following_paragraph, no_commit_until_newline, pipe_text_without_table_prefix_is_not_delayed, table_header_commits_without_holdback, new）；外部调用 2 个（to_path_buf, new）。

fn set_width(&mut self, width: Option<usize>)

作用：修改测试渲染时使用的显示宽度。它主要用于测试不同终端宽度下的 Markdown 换行效果。

数据流：输入一个可选宽度 → 它把收集器里记录的 width 替换掉 → 后续测试渲染时会按这个新宽度处理。

调用关系：这是一个简单的设置入口，不把工作交给别的函数；它影响的是测试专用的 commit_complete_lines 和 finalize_and_drain 的渲染结果。

fn clear(&mut self)

作用：把收集器清空，准备接下一段新内容。它用于流结束后或需要丢弃当前缓存时恢复初始状态。

数据流：读取当前缓存、已提交位置和测试里的已提交行数 → 清空文字缓存，把计数归零 → 收集器回到刚创建时的状态。

调用关系：finalize_and_drain_source 和测试用的 finalize_and_drain 在收尾后会调用它，确保下一次流式输出不会混进上一轮残留内容。

调用图：被 3 处调用（finalize_and_drain, finalize_and_drain_source, clear）。

fn push_delta(&mut self, delta: &str)

作用：把新收到的一小段 Markdown 文本追加进缓存。这里的 delta 就是流式传输里刚到的一块文字。

数据流：输入一段字符串 delta → 它先记录一条 trace 级日志，方便调试，然后把这段文字接到内部 buffer 末尾 → 收集器里保存的原始 Markdown 变长。

调用关系：流式控制器或测试会反复调用它喂入新片段；喂完后通常会根据这段文字里有没有换行，继续调用 commit_complete_source 或测试用的 commit_complete_lines。

调用图：外部调用 1 个（trace!）。

fn commit_complete_source(&mut self) -> Option<String>

作用：交出最新已经完整的原始 Markdown 行。它只认换行符，没遇到换行就不交，避免把没写完的一行提前显示。

数据流：读取内部 buffer 和上次已经提交到的位置 → 找到最后一个换行符，只截取“上次没交过、这次已经完整”的部分 → 返回这段新文本，并把已提交位置推进；如果没有新完整行，就返回 None。

调用关系：正式的流式显示流程会在收到含换行的片段后调用它；它不解析 Markdown，只给外部渲染器提供稳定的文本边界。

fn finalize_and_drain_source(&mut self) -> String

作用：在流真正结束时，把最后没交出去的原始 Markdown 也交出来。即使最后一行没有换行，它也会补一个换行，方便后续 Markdown 解析。

数据流：读取当前 buffer 和已提交位置 → 如果没有剩余内容，就清空并返回空字符串；如果还有剩余，就截出剩下的文本，必要时补上换行 → 清空收集器，返回最后这块文本。

调用关系：它是 commit_complete_source 的收尾搭档；流正常结束或中断时调用它，内部会调用 clear，避免旧内容污染下一次流。

调用图：调用 1 个内部函数（clear）；外部调用 1 个（new）。

fn commit_complete_lines(&mut self) -> Vec<Line<'static>>

作用：这是测试专用函数：把已经完整的 Markdown 内容渲染成终端行，并只返回这次新增的那些行。它用来验证“分块收到”和“一次性收到”的显示是否一致。

数据流：读取缓存、宽度、测试当前目录和已提交行数 → 找到最后一个换行，把完整前缀交给 append_markdown 渲染，再去掉末尾可能多出来的纯空白行 → 返回上次之后新增的 Line，并更新已提交字节数和行数。

调用关系：simulate_stream_markdown_for_tests 和多项测试会用它模拟真实流式显示；它把具体 Markdown 渲染交给 markdown::append_markdown，并用 is_blank_line_spaces_only 判断末尾空白行。

调用图：调用 2 个内部函数（append_markdown, is_blank_line_spaces_only）；外部调用 2 个（as_path, new）。

fn finalize_and_drain(&mut self) -> Vec<Line<'static>>

作用：这是测试专用的收尾函数：流结束时，把所有剩余 Markdown 渲染成终端行并返回。它确保最后没有换行的内容也能被测试看到。

数据流：复制当前缓存 → 如果为空就清空并返回空列表；如果末尾没有换行就临时补上 → 调用 append_markdown 渲染完整内容，只取之前没返回过的行 → 清空收集器，返回新增 Line。

调用关系：simulate_stream_markdown_for_tests 在 finalize 为 true 时调用它；它会记录 debug 和 trace 日志，把渲染交给 append_markdown，最后用 clear 重置状态。

调用图：调用 2 个内部函数（append_markdown, clear）；外部调用 4 个（as_path, new, debug!, trace!）。

fn test_cwd() -> PathBuf

作用：给测试提供一个稳定的当前目录路径。这样测试里涉及本地文件链接显示时，不会因为不同操作系统根目录不同而变得不稳定。

数据流：不接收输入 → 调用系统的临时目录函数 temp_dir → 返回一个 PathBuf 路径给测试使用。

调用关系：simulate_stream_markdown_for_tests 会调用它来创建 MarkdownStreamCollector；很多测试也通过它给收集器或 Markdown 渲染函数提供一致的目录。

调用图：被 1 处调用（simulate_stream_markdown_for_tests）；外部调用 1 个（temp_dir）。

fn simulate_stream_markdown_for_tests(
    deltas: &[&str],
    finalize: bool,
) -> Vec<Line<'static>>

作用：这是测试里的“假装流式输出”工具。它把一组小文本片段按顺序喂给收集器，模拟真实聊天内容一块块到达。

数据流：输入若干 delta 字符串和是否最终收尾的开关 → 创建收集器，逐个 push_delta；每当片段里有换行，就提交完整行；如果要求 finalize，就再交出最后剩余内容 → 输出渲染后的 Line 列表。

调用关系：许多端到端测试调用它来少写重复代码；它内部串起 new、test_cwd、push_delta、commit_complete_lines 和 finalize_and_drain，模拟完整的流式生命周期。

调用图：调用 2 个内部函数（new, test_cwd）；被 6 处调用（assert_streamed_equals_full, empty_fenced_block_is_dropped_and_separator_preserved_before_heading, loose_list_with_split_dashes_matches_full_render, loose_vs_tight_list_items_streaming_matches_full, paragraph_then_empty_fence_then_heading_keeps_heading_on_new_line, utf8_boundary_safety_and_wide_chars）；外部调用 1 个（new）。

async fn no_commit_until_newline()

作用：测试没有换行时不会提前提交内容。它防止半行文字被过早显示。

数据流：创建收集器 → 先放入没有换行的 “Hello, world”，检查没有输出；再放入 “!\n”，检查这时正好输出一行 → 测试通过说明换行边界生效。

调用关系：它直接使用 MarkdownStreamCollector::new、push_delta 和 commit_complete_lines，是最基础的边界行为测试。

调用图：调用 1 个内部函数（new）；外部调用 3 个（assert!, assert_eq!, test_cwd）。

async fn finalize_commits_partial_line()

作用：测试流结束时，即使最后一行没有换行，也会被输出。它保证结尾内容不会丢。

数据流：创建收集器 → 放入一行没有换行的文本 → 调用 finalize_and_drain → 检查返回一行内容。

调用关系：它验证测试收尾函数 finalize_and_drain 的价值，和 no_commit_until_newline 形成互补：平时不提前交，结束时必须交。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, test_cwd）。

async fn e2e_stream_blockquote_simple_is_green()

作用：测试简单引用块在流式渲染后是绿色的。引用块就是 Markdown 里用 “>” 开头的文字。

数据流：输入 “> Hello\n” 到模拟流 → 得到渲染行 → 检查只有一行，并且前景色是绿色。

调用关系：它通过 simulate_stream_markdown_for_tests 走完整流式流程，重点确认收集器不会破坏引用块的样式。

调用图：外部调用 2 个（assert_eq!, simulate_stream_markdown_for_tests）。

async fn e2e_stream_blockquote_nested_is_green()

作用：测试嵌套引用块也保持绿色。嵌套引用块就是 “>” 里面再有 “>>”。

数据流：把两行引用内容送进模拟流 → 过滤掉可能插入的空白引用行 → 检查剩下两行都显示为绿色。

调用关系：它依赖 simulate_stream_markdown_for_tests 生成流式结果，用来覆盖更复杂的引用层级。

调用图：外部调用 2 个（assert_eq!, simulate_stream_markdown_for_tests）。

async fn e2e_stream_blockquote_with_list_items_is_green()

作用：测试引用块里面放列表项时，整行仍然保持引用块的绿色样式。

数据流：输入两行 “> - item” 形式的 Markdown → 模拟流式渲染 → 检查输出两行，并且两行前景色都是绿色。

调用关系：它通过 simulate_stream_markdown_for_tests 验证引用和列表两种 Markdown 结构叠在一起时没有被收集器拆坏。

调用图：外部调用 2 个（assert_eq!, simulate_stream_markdown_for_tests）。

async fn e2e_stream_nested_mixed_lists_ordered_marker_is_light_blue()

作用：测试多层混合列表里，第三层有序列表编号的颜色是浅蓝色。有序列表就是 “1.” 这种编号列表。

数据流：输入一段包含编号列表和项目符号列表的多层 Markdown → 模拟流式渲染 → 找到含有第三层编号文本的行 → 检查至少有一个片段是浅蓝色。

调用关系：它调用 simulate_stream_markdown_for_tests，确认流式提交不会让复杂列表的编号样式丢失。

调用图：外部调用 2 个（assert!, simulate_stream_markdown_for_tests）。

async fn e2e_stream_blockquote_wrap_preserves_green_style()

作用：测试长引用行被自动换行后，每一段仍然保持绿色。自动换行是终端宽度不够时把一行拆成多行显示。

数据流：输入一条很长的引用行 → 模拟流式渲染 → 再用 word_wrap_lines 按窄宽度强制换行 → 过滤空行后检查每个显示行的开头仍是绿色。

调用关系：它先用 simulate_stream_markdown_for_tests 得到结果，再把换行工作交给 wrapping::word_wrap_lines，检查渲染样式能穿过两个步骤保持不变。

调用图：调用 2 个内部函数（new, word_wrap_lines）；外部调用 3 个（assert!, assert_eq!, simulate_stream_markdown_for_tests）。

async fn heading_starts_on_new_line_when_following_paragraph()

作用：测试段落后面的标题会另起一行，而不是粘到前一句后面。标题就是 Markdown 里用 “##” 这类符号开头的行。

数据流：先输入 “Hello.\n” 并提交 → 检查只有段落行；再输入 “## Heading\n” 并提交 → 检查输出包含空白分隔行和标题行 → 最后确认原段落和标题文本正确。

调用关系：它直接操作收集器，覆盖标题紧跟段落时的增量提交行为，防止分块渲染把块级结构合并错。

调用图：调用 1 个内部函数（new）；外部调用 2 个（assert_eq!, test_cwd）。

async fn heading_not_inlined_when_split_across_chunks()

作用：测试标题被拆在不同数据块里时，也不会被错误地并进上一段文字。

数据流：先输入没有换行的段落，确认不提交；再输入换行加标题开头，先只提交完整段落；最后输入标题结尾换行，再提交标题 → 还额外用 append_markdown 检查普通整行渲染不会多出奇怪内容。

调用关系：它直接使用收集器和 markdown::append_markdown，专门验证“换行在一个块里、标题文字在后续块里”的真实流式场景。

调用图：调用 2 个内部函数（append_markdown, new）；外部调用 4 个（new, assert!, assert_eq!, test_cwd）。

fn lines_to_plain_strings(lines: &[ratatui::text::Line<'_>]) -> Vec<String>

作用：把终端渲染用的 Line 列表变成普通字符串列表，方便测试比较内容。Line 里可能有多个带样式的 span，这里只取文字。

数据流：输入一组 Line → 遍历每一行的 spans，把每个 span 的 content 拼起来 → 输出普通 String 列表。

调用关系：很多测试用它把复杂的带样式渲染结果简化成纯文本，再和预期结果做 assert_eq 比较。

调用图：外部调用 1 个（iter）。

async fn table_header_commits_without_holdback()

作用：测试表格头、分隔线和表格内容在测试收集器里不会被无故延迟。这里的 holdback 指为了等更多内容而暂时不显示。

数据流：依次输入表头、分隔线、数据行和空行 → 每次提交并转成纯文本 → 检查表头能立即出现，后续行也持续有输出。

调用关系：它直接创建收集器，并用 lines_to_plain_strings 检查结果，确保这个文件的测试提交逻辑只按换行提交，不额外实现表格等待策略。

调用图：调用 1 个内部函数（new）；外部调用 4 个（assert!, assert_eq!, test_cwd, lines_to_plain_strings）。

async fn pipe_text_without_table_prefix_is_not_delayed()

作用：测试普通文字里出现竖线 “|” 时，不会被误当成表格而延迟显示。

数据流：输入一行包含多个竖线的普通句子 → 提交完整行 → 转成纯文本 → 检查输出就是原句。

调用关系：它使用收集器和 lines_to_plain_strings，验证换行边界逻辑不会因为看见表格常用符号而改变提交节奏。

调用图：调用 1 个内部函数（new）；外部调用 3 个（assert_eq!, test_cwd, lines_to_plain_strings）。

async fn lists_and_fences_commit_without_duplication()

作用：测试列表和围栏代码块在分块流式输入时不会重复显示。围栏代码块就是用三个反引号包起来的代码区域。

数据流：分别准备列表分块和代码块分块 → 调用 assert_streamed_equals_full → 比较流式渲染和一次性完整渲染是否完全一样。

调用关系：它把主要检查交给 assert_streamed_equals_full，是针对常见 Markdown 结构的回归测试。

调用图：外部调用 1 个（assert_streamed_equals_full）。

async fn utf8_boundary_safety_and_wide_chars()

作用：测试表情、中文、控制字符、组合字符这些特殊 Unicode 文本在分块输入时不会被截坏或重复。Unicode 可以理解为统一表示各种语言和符号的字符标准。

数据流：准备包含 emoji、汉字和组合符号的完整文本，再把它拆成多个 delta → 用模拟流得到流式结果 → 同时用 append_markdown 做一次性完整渲染 → 把两边转成纯文本后比较完全相等。

调用关系：它调用 simulate_stream_markdown_for_tests、append_markdown 和 lines_to_plain_strings，重点保护多字节字符边界安全。

调用图：调用 2 个内部函数（append_markdown, simulate_stream_markdown_for_tests）；外部调用 5 个（new, assert_eq!, test_cwd, lines_to_plain_strings, vec!）。

async fn e2e_stream_deep_nested_third_level_marker_is_light_blue()

作用：更精确地测试深层列表里第三层编号标记是浅蓝色，而列表正文保持默认颜色。

数据流：输入一段多层列表 Markdown → 模拟流式渲染 → 找到第三层有序列表那一行 → 检查第一个 span，也就是缩进和 “1.” 标记，是浅蓝色；再检查正文 span 没有被染色。

调用关系：它使用 simulate_stream_markdown_for_tests 和 lines_to_plain_strings，细查样式分布，而不只是检查整行有没有某种颜色。

调用图：外部调用 4 个（assert!, assert_eq!, simulate_stream_markdown_for_tests, lines_to_plain_strings）。

async fn empty_fenced_block_is_dropped_and_separator_preserved_before_heading()

作用：测试空代码块后面接标题时，空代码块标记不会显示出来，同时标题还能正常另起一行。

数据流：输入一个空的 fenced code block，再输入标题 → 模拟流式渲染并转成纯文本 → 检查结果里没有反引号代码块标记，并且能找到标题行。

调用关系：它通过 simulate_stream_markdown_for_tests 走流式路径，用 lines_to_plain_strings 做文本检查，覆盖空代码块这种容易产生多余行的情况。

调用图：调用 1 个内部函数（simulate_stream_markdown_for_tests）；外部调用 3 个（assert!, lines_to_plain_strings, vec!）。

async fn paragraph_then_empty_fence_then_heading_keeps_heading_on_new_line()

作用：测试段落、空代码块、标题连续出现时，标题不会和段落粘在一起。

数据流：依次输入段落、空代码块和标题 → 模拟流式渲染 → 转成纯文本 → 找到段落和标题的位置，检查标题出现在段落之后。

调用关系：它调用 simulate_stream_markdown_for_tests 和 lines_to_plain_strings；如果找不到关键行会 panic，说明渲染结构已经明显错了。

调用图：调用 1 个内部函数（simulate_stream_markdown_for_tests）；外部调用 4 个（assert!, panic!, lines_to_plain_strings, vec!）。

async fn loose_list_with_split_dashes_matches_full_render()

作用：测试松散列表里单独拆开的短横线不会变成多余的悬空列表项。松散列表指列表项之间有空行的列表。

数据流：把 “- item” 后面接一个单独的 “-” 作为分块输入 → 得到流式渲染纯文本 → 再把所有分块拼成完整 Markdown 一次性渲染 → 比较两边完全一致。

调用关系：它同时使用 simulate_stream_markdown_for_tests、append_markdown 和 lines_to_plain_strings，是针对曾经发现的分块问题的定向回归测试。

调用图：调用 2 个内部函数（append_markdown, simulate_stream_markdown_for_tests）；外部调用 5 个（new, assert_eq!, test_cwd, lines_to_plain_strings, vec!）。

async fn loose_vs_tight_list_items_streaming_matches_full()

作用：测试紧凑列表和松散列表混在一起时，流式输出的编号、缩进和空行都符合预期。紧凑列表是列表项之间没有空行，松散列表则有空行或段落。

数据流：用很多很小的 delta 模拟真实会话里的逐词输出 → 流式渲染并转成纯文本 → 同时做一次完整渲染用于诊断 → 最后和手写的预期行列表逐项比较。

调用关系：它调用 simulate_stream_markdown_for_tests、append_markdown 和 lines_to_plain_strings，覆盖复杂列表结构，也是比较综合的回归测试。

调用图：调用 2 个内部函数（append_markdown, simulate_stream_markdown_for_tests）；外部调用 5 个（new, assert_eq!, test_cwd, lines_to_plain_strings, vec!）。

async fn assert_streamed_equals_full(deltas: &[&str])

作用：这是测试里的通用断言工具：检查分块流式渲染结果和一次性完整渲染结果完全一样。

数据流：输入一组 delta → 用 simulate_stream_markdown_for_tests 得到流式结果并转纯文本；再把 delta 拼成完整 Markdown，用 append_markdown 渲染并转纯文本 → 比较两边，不一样就带上完整输入内容报错。

调用关系：多个 fuzz 回归测试和结构测试都调用它；它把重复的“流式 vs 完整”比较流程集中到一个地方。

调用图：调用 2 个内部函数（append_markdown, simulate_stream_markdown_for_tests）；外部调用 4 个（new, assert_eq!, test_cwd, lines_to_plain_strings）。

async fn fuzz_class_bullet_duplication_variant_1()

作用：测试一种由 fuzz 测试发现的项目符号重复问题。fuzz 测试就是自动生成很多奇怪输入来找 bug 的测试方法。

数据流：输入两段曾经会触发列表重复的 Markdown 分块 → 调用 assert_streamed_equals_full → 如果流式结果和完整渲染一致，就说明这个 bug 没复发。

调用关系：它把实际比较交给 assert_streamed_equals_full，是一个保留历史问题样本的回归测试。

调用图：外部调用 1 个（assert_streamed_equals_full）。

async fn fuzz_class_bullet_duplication_variant_2()

作用：测试另一种 fuzz 发现的项目符号重复场景，防止列表项被分块拆开后重复显示。

数据流：输入一组不同拆法的列表 Markdown 片段 → 调用 assert_streamed_equals_full → 比较流式和完整渲染。

调用关系：它和 fuzz_class_bullet_duplication_variant_1 一起覆盖同类问题的不同形态，核心检查仍交给 assert_streamed_equals_full。

调用图：外部调用 1 个（assert_streamed_equals_full）。

async fn streaming_html_block_then_text_matches_full()

作用：测试 HTML 块后面接普通文字时，流式渲染和完整渲染一致。HTML 块就是 Markdown 里直接写的类似 <div> 的标签内容。

数据流：输入标题文字、HTML 行、普通文字三段 → 调用 assert_streamed_equals_full → 检查没有因为 HTML 块边界而多显示或少显示。

调用关系：它依赖 assert_streamed_equals_full，覆盖 Markdown 中 HTML 结构和普通文本相邻的场景。

调用图：外部调用 1 个（assert_streamed_equals_full）。

async fn table_like_lines_inside_fenced_code_are_not_held()

作用：测试代码块里的表格样式文本不会被当成真正表格而特殊等待。代码块里的内容应该按代码显示。

数据流：输入一个 fenced code block，其中间有 “| a | b |” 这种像表格的行 → 调用 assert_streamed_equals_full → 检查流式和完整渲染一致。

调用关系：它把比较交给 assert_streamed_equals_full，保护代码块内部文本不被外面的表格逻辑误判。

调用图：外部调用 1 个（assert_streamed_equals_full）。

async fn collector_source_chunks_round_trip_into_agent_fence_unwrapping()

作用：测试收集器交出的原始 Markdown 片段能正确送进 agent 专用渲染器，并触发 Markdown 代码围栏的解包逻辑。这里的 agent 渲染器是给助手输出用的特殊 Markdown 渲染入口。

数据流：创建收集器 → 分块输入一个 ```md 围起来的表格 → 每遇到换行就用 commit_complete_source 收集原始片段，最后用 finalize_and_drain_source 收尾 → 把完整原始文本交给 append_markdown_agent → 检查渲染结果里有表格分隔线，并且没有原始表头文本残留。

调用关系：它直接覆盖生产路径更关心的原始 source 提交流程：push_delta、commit_complete_source、finalize_and_drain_source 先合成文本，再交给 markdown::append_markdown_agent 做最终渲染。

调用图：调用 2 个内部函数（append_markdown_agent, new）；外部调用 5 个（new, new, assert!, test_cwd, lines_to_plain_strings）。

fn new(width: Option<usize>, cwd: &Path) -> Self

作用：创建一个新的流式输出状态。调用方会把当前工作目录传进来，这样 Markdown 里的本地文件链接可以按正确位置显示。

数据流：输入是可选的显示宽度和当前目录路径 → 它新建一个 Markdown 收集器、一个空的行队列，并把“是否见过增量内容”设为否 → 输出一个干净的 StreamState，准备接收后续流式文本。

调用关系：这是这套流式状态的起点。更高层创建流控制器时会用它；测试 drain_n_clamps_to_available_lines 也会先用它造出一个状态，再检查后续排队和取队列是否正常。

调用图：调用 1 个内部函数（new）；被 2 处调用（new, drain_n_clamps_to_available_lines）；外部调用 1 个（new）。

fn clear(&mut self)

作用：把当前流的状态全部清空，准备迎接下一轮流式输出。它不只是清队列，也会清掉 Markdown 收集器里的临时内容。

数据流：输入是一个已有的 StreamState → 它清空 Markdown 收集器、清空等待显示的行队列，并把“见过增量内容”的标记改回否 → 这个状态回到刚开始那样的空白状态。

调用关系：当上层 reset 流程要重开一轮输出时会调用它。它负责做彻底复位，避免上一轮没显示完或没收集完的内容污染下一轮。

调用图：调用 1 个内部函数（clear）；被 1 处调用（reset）；外部调用 1 个（clear）。

fn step(&mut self) -> Vec<HyperlinkLine>

作用：从队列最前面取出一行，交给界面显示。它用于那种“一次推进一点点”的显示节奏。

数据流：输入是当前队列状态 → 它从队首弹出最早排队的一行，如果有就取出来，没有就什么也不取 → 输出一个列表，里面最多只有这一行，并且队列少了一行。

调用关系：上层的 tick 会调用它。tick 可以理解成界面刷新时的一次小动作，每次只放出一点内容，让显示看起来平滑且有秩序。

调用图：被 1 处调用（tick）；外部调用 1 个（pop_front）。

fn drain_n(&mut self, max_lines: usize) -> Vec<HyperlinkLine>

作用：一次从队列前面取出最多指定数量的行。它适合需要批量推进显示的时候，比如队列积压太多，需要多放几行。

数据流：输入是想取出的最大行数 max_lines 和当前队列 → 它先看队列实际有多少行，只取两者中较小的数量 → 输出这些被取出的行，并从队列里删除它们。

调用关系：上层的 tick_batch 会调用它做批量刷新。测试 drain_n_clamps_to_available_lines 专门验证：即使要求取 8 行，而队列只有 1 行，也只会安全地取出 1 行。

调用图：被 1 处调用（tick_batch）；外部调用 2 个（drain, len）。

fn clear_queue(&mut self)

作用：只清空等待显示的行队列，但保留 Markdown 收集器和当前流生命周期的其他状态。它用于“显示队列要重建，但整轮流还没结束”的场景。

数据流：输入是当前 StreamState → 它只把 queued_lines 清空 → 输出没有返回值，但状态里的待显示队列变成空，其他部分保持原样。

调用关系：当上层需要重建稳定显示队列、切换渲染模式、调整宽度或同步队列时会用它。这样可以先倒掉旧的排队结果，再按新规则重新装入内容。

调用图：被 4 处调用（rebuild_stable_queue_from_render, set_render_mode, set_width, sync_stable_queue）；外部调用 1 个（clear）。

fn is_idle(&self) -> bool

作用：判断现在有没有排队等待显示的行。简单说，就是问这条流的显示队列是不是空了。

数据流：输入是当前 StreamState → 它检查 queued_lines 是否为空 → 输出 true 或 false，true 表示没有待显示内容。

调用关系：上层也有自己的 is_idle，会通过它判断底层队列是否已经清空。这个判断常用于决定要不要继续刷新、提交或等待。

调用图：被 1 处调用（is_idle）；外部调用 1 个（is_empty）。

fn queued_len(&self) -> usize

作用：返回当前还有多少行在排队等待显示。它让上层知道队列压力有多大。

数据流：输入是当前 StreamState → 它读取 queued_lines 的长度 → 输出一个数字，表示待显示行数，不改动任何内容。

调用关系：上层的 queued_lines、set_render_mode、set_width 和 sync_stable_queue 会用到它。比如改宽度或改显示模式时，需要知道旧队列里还有多少东西，才能决定怎么同步。

调用图：被 4 处调用（queued_lines, set_render_mode, set_width, sync_stable_queue）；外部调用 1 个（len）。

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

作用：查看队列里最早那一行已经等了多久。这个信息可以帮助上层判断是否该加快显示，避免内容一直憋在队列里。

数据流：输入是当前时间 now 和队列状态 → 它看队首那一行的入队时间，并计算从入队到现在经过了多久；如果队列为空就没有结果 → 输出一个可选的时间长度。

调用关系：上层的 oldest_queued_age 会调用它。它不需要偷看文字内容，只看最老一行的等待时间，这样策略代码能根据“等了多久”做决定。

调用图：被 1 处调用（oldest_queued_age）；外部调用 1 个（front）。

fn enqueue(&mut self, lines: Vec<HyperlinkLine>)

作用：把一批已经整理好的显示行放进队列末尾。它保证新来的内容排在旧内容后面，不会插队。

数据流：输入是一组 HyperlinkLine，也就是可能带终端超链接的显示行 → 它记录当前时间，并给这一批行都贴上同一个入队时间，再追加到队列尾部 → 输出没有返回值，但队列多了这些待显示行。

调用关系：rebuild_stable_queue_from_render 和 sync_stable_queue 会调用它，把重新渲染或同步出来的稳定行放回队列。后续 step 或 drain_n 再按先进先出的顺序取走。

调用图：被 2 处调用（rebuild_stable_queue_from_render, sync_stable_queue）；外部调用 2 个（now, extend）。

fn test_cwd() -> PathBuf

作用：给测试准备一个稳定的当前目录路径。它用系统临时目录，避免测试依赖某个操作系统特有的根目录写法。

数据流：没有业务输入 → 它向系统询问临时目录在哪里 → 输出一个 PathBuf 路径，供测试创建 StreamState 时使用。

调用关系：测试 drain_n_clamps_to_available_lines 会调用它。它只是测试辅助工具，让测试里的路径参数合法且跨平台。

调用图：外部调用 1 个（temp_dir）。

fn drain_n_clamps_to_available_lines()

作用：验证 drain_n 的安全行为：要求取出的行数超过队列现有数量时，不会出错，也不会凭空产生内容。

数据流：它先创建一个 StreamState，并放入一行文字 one → 然后要求一次取最多 8 行 → 结果应该只得到那 1 行，并且队列随后变为空。

调用关系：这是针对 StreamState::drain_n 的单元测试。它会用 StreamState::new 创建状态，用 tests::test_cwd 提供目录，再用断言确认取出的内容和空队列状态都符合预期。

调用图：调用 1 个内部函数（new）；外部调用 4 个（assert!, assert_eq!, test_cwd, vec!）。

fn new(width: Option<usize>, cwd: &Path, render_mode: HistoryRenderMode) -> Self

作用：创建一个流式输出的核心记录本。它准备好保存原文、渲染结果、提交队列、当前宽度和表格检测状态。

数据流：输入终端内容宽度、当前工作目录和渲染模式 → 建好 StreamState、空字符串、空行列表、缓存和表格扫描器 → 返回一个还没接收任何内容的 StreamCore。

调用关系：普通消息控制器和计划控制器在创建时都会先调用它，把共用的流式处理底座搭起来。

调用图：调用 2 个内部函数（new, new）；被 2 处调用（new, new）；外部调用 3 个（to_path_buf, with_capacity, with_capacity）。

fn push_delta(&mut self, delta: &str) -> bool

作用：接收模型新吐出来的一小段文字，并决定哪些行已经安全到可以放进聊天记录。它会等到一行真正结束后再提交，避免半行表格闪一下又变掉。

数据流：输入一段 delta 文本 → 放进收集器；如果里面有换行，就取出完整来源、追加到原文、更新表格扫描、重新渲染并同步稳定队列 → 返回这次有没有新稳定行入队。

调用关系：StreamController::push 和 PlanStreamController::push 都把新内容交给它；它再调用重新渲染和队列同步这两步。

调用图：调用 3 个内部函数（recompute_streaming_render, sync_stable_queue, push_source_chunk）；被 2 处调用（push, push）。

fn finalize_remaining(&mut self) -> Vec<HyperlinkLine>

作用：在一次流式输出结束时，把还没显示完的尾巴一次性整理出来。它保证最终聊天记录以完整原文重新渲染为准。

数据流：读取收集器里剩下的未完成文字 → 追加到原文并更新表格扫描 → 用完整原文重新渲染 → 返回尚未发到聊天记录的那些行。

调用关系：普通消息和计划在 finalize 时都会调用它；之后外层控制器会把这些行包装成对应的历史单元。

调用图：调用 2 个内部函数（render_source, push_source_chunk）；被 2 处调用（finalize, finalize）；外部调用 1 个（new）。

fn tick(&mut self) -> Vec<HyperlinkLine>

作用：推进一次提交动画，也就是从稳定队列里拿出一小步内容显示。它同时记住已经真正显示了多少行。

数据流：读取当前队列 → 从 StreamState 取出一步要显示的行 → 增加已发出行数 → 返回这一步的行。

调用关系：两个控制器的 on_commit_tick 都调用它，用来一点点把稳定内容搬到聊天记录。

调用图：调用 1 个内部函数（step）；被 2 处调用（on_commit_tick, on_commit_tick）。

fn tick_batch(&mut self, max_lines: usize) -> Vec<HyperlinkLine>

作用：一次性从稳定队列里取出最多指定数量的行。它用于想快速清空或批量推进动画的场景。

数据流：输入最多取几行 → 如果是 0 就什么也不做；否则从队列取出这些行 → 更新已发出行数 → 返回取出的行。

调用关系：两个控制器的 on_commit_tick_batch 调用它；测试里也用它验证 resize 后队列能被完整排出。

调用图：调用 1 个内部函数（drain_n）；被 2 处调用（on_commit_tick_batch, on_commit_tick_batch）；外部调用 1 个（new）。

fn is_idle(&self) -> bool

作用：判断当前稳定队列是不是已经空了。外层用它知道这轮动画是否结束。

数据流：读取 StreamState 的队列状态 → 转交给 StreamState 判断 → 返回是否空闲。

调用关系：每次普通消息或计划消息提交一批内容后，外层都会用它决定是否继续 tick。

调用图：调用 1 个内部函数（is_idle）；被 4 处调用（on_commit_tick, on_commit_tick_batch, on_commit_tick, on_commit_tick_batch）。

fn queued_lines(&self) -> usize

作用：告诉外面现在还有多少稳定行排队等显示。它主要用于节流、动画和测试检查。

数据流：读取 StreamState 队列长度 → 返回待显示行数。

调用关系：两个控制器都把这个信息暴露出去，调用方可据此决定是否需要继续刷新。

调用图：调用 1 个内部函数（queued_len）；被 2 处调用（queued_lines, queued_lines）。

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

作用：查看队列里最早那批内容已经等了多久。这样上层可以判断动画是不是积压太久。

数据流：输入当前时间 → 询问 StreamState 最老排队项的年龄 → 返回一个时长，或者没有队列时返回空。

调用关系：两个控制器提供同名接口，把排队老化信息交给外层调度逻辑。

调用图：调用 1 个内部函数（oldest_queued_age）；被 2 处调用（oldest_queued_age, oldest_queued_age）。

fn current_tail_lines(&self) -> Vec<HyperlinkLine>

作用：取出还不能正式写入聊天记录、但可以作为临时尾巴显示的行。它避免已入队但还没播放的行在尾巴里重复出现。

数据流：读取当前渲染行和已入队稳定边界 → 从边界之后切出尾巴 → 返回这些可变行。

调用关系：普通消息和计划消息都用它显示活动单元里的实时尾巴。

调用图：被 2 处调用（current_tail_lines, current_tail_lines）。

fn has_tail(&self) -> bool

作用：判断当前有没有还在变化的尾巴内容。它告诉外层是否需要保留一个临时显示区域。

数据流：比较已入队稳定行数和总渲染行数 → 如果后面还有内容就返回 true。

调用关系：两个控制器的 has_live_tail 会调用它；改宽度和改渲染模式时也用它保护未稳定尾巴。

调用图：被 4 处调用（has_live_tail, has_live_tail, set_render_mode, set_width）。

fn set_width(&mut self, width: Option<usize>)

作用：终端宽度变化时重新排版正在流的内容。它尽量不重放已经显示过的内容，同时保住还没显示的队列和可变尾巴。

数据流：输入新宽度 → 如果变了，就更新收集器宽度、重新渲染原文、修正已显示计数、清掉旧宽度下的队列并重建 → 改动内部排版状态。

调用关系：两个外层控制器的 set_width 都转给它；它会调用重新渲染和队列重建，防止 resize 后丢行或重复。

调用图：调用 5 个内部函数（clear_queue, queued_len, has_tail, rebuild_stable_queue_from_render, recompute_streaming_render）；被 2 处调用（set_width, set_width）。

fn reset(&mut self)

作用：清空一次流式输出留下的所有临时状态。没有它，上一条回答可能会混进下一条回答。

数据流：读取并清理内部状态 → 清空队列、原文、渲染行、计数、缓存和表格扫描器 → 回到刚创建后的干净状态。

调用关系：两个 finalize 在拿走最终结果后都会调用它，作为收尾清场。

调用图：调用 2 个内部函数（clear, reset）；被 2 处调用（finalize, finalize）。

fn render_source(&self, source: &str) -> Vec<HyperlinkLine>

作用：把原始 Markdown 文本变成终端能显示的行。它支持富文本模式和原样文本模式。

数据流：输入源文本 → 如果是 Rich 就按 Markdown、链接和当前目录渲染；如果是 Raw 就按原始行处理 → 返回带链接信息的显示行。

调用关系：最终渲染和每次重新渲染都靠它，是原文到屏幕行之间的转换器。

调用图：调用 3 个内部函数（raw_lines_from_source, render_markdown_agent_with_links_and_cwd, plain_hyperlink_lines）；被 2 处调用（finalize_remaining, recompute_streaming_render）；外部调用 1 个（as_path）。

fn recompute_streaming_render(&mut self)

作用：用当前原文和当前设置重新生成整份渲染快照。它让后续稳定区和尾巴都基于最新画面计算。

数据流：读取 raw_source、宽度和渲染模式 → 调用 render_source → 覆盖 rendered_lines。

调用关系：收到完整新行、窗口改宽、渲染模式改变时都会调用它。

调用图：调用 1 个内部函数（render_source）；被 3 处调用（push_delta, set_render_mode, set_width）。

fn set_render_mode(&mut self, render_mode: HistoryRenderMode)

作用：切换渲染模式，比如从富 Markdown 显示切到原始文本显示。它会像 resize 一样重新整理队列，避免画面错位。

数据流：输入新模式 → 如果真的改变，就记住旧队列和尾巴状态、重新渲染、修正计数、清队列并按新模式重建 → 内部显示状态更新。

调用关系：两个外层控制器的 set_render_mode 会调用它；它复用 resize 类似的保护逻辑。

调用图：调用 5 个内部函数（clear_queue, queued_len, has_tail, rebuild_stable_queue_from_render, recompute_streaming_render）；被 2 处调用（set_render_mode, set_render_mode）。

fn compute_target_stable_len(&mut self) -> usize

作用：计算当前有多少渲染行可以算作稳定区。它是决定“哪些能进聊天记录、哪些还要留在尾巴”的核心判断。

数据流：读取总渲染行数和已发出行数 → 计算需要扣住的尾巴行数 → 得出目标稳定行数，且不会小于已发出的行数。

调用关系：同步队列和重建队列时都会先问它稳定边界在哪里。

调用图：调用 1 个内部函数（active_tail_budget_lines）；被 2 处调用（rebuild_stable_queue_from_render, sync_stable_queue）。

fn sync_stable_queue(&mut self) -> bool

作用：把新变稳定的行加入提交队列。遇到表格导致稳定边界回退时，它会重建队列而不是硬接旧内容。

数据流：计算目标稳定行数 → 如果边界后退就清队列并按新快照重放未发稳定行；如果前进就把新增稳定行入队 → 返回是否有新队列内容。

调用关系：push_delta 在每次完整行到达并重新渲染后调用它。

调用图：调用 4 个内部函数（clear_queue, enqueue, queued_len, compute_target_stable_len）；被 1 处调用（push_delta）。

fn rebuild_stable_queue_from_render(&mut self)

作用：按当前渲染快照重新生成稳定队列。它主要在宽度或渲染模式改变后使用，因为旧队列的换行已经不可信。

数据流：计算目标稳定行数 → 清空旧队列 → 把已显示之后、稳定边界之前的行重新入队 → 更新稳定边界。

调用关系：set_width 和 set_render_mode 在重新渲染后调用它。

调用图：调用 3 个内部函数（clear_queue, enqueue, compute_target_stable_len）；被 2 处调用（set_render_mode, set_width）。

fn active_tail_budget_lines(&mut self) -> usize

作用：决定现在要扣住多少行作为可变尾巴。尤其是表格出现时，它会把表格从表头开始留在尾巴里，等最终确定再提交。

数据流：读取表格扫描器状态 → 如果发现或怀疑表格，就把源文本位置换算成尾巴行数；否则尾巴预算为 0 → 返回应扣住的行数。

调用关系：compute_target_stable_len 调用它；它再根据扫描器状态转给 tail_budget_from_source_start。

调用图：调用 2 个内部函数（tail_budget_from_source_start, state）；被 1 处调用（compute_target_stable_len）；外部调用 2 个（now, trace!）。

fn tail_budget_from_source_start(&mut self, source_start: usize) -> usize

作用：把“原文里的某个字节位置”转换成“渲染结果里要扣住多少行”。这是原文坐标和屏幕行坐标之间的桥。

数据流：输入表格开始的源文本位置 → 算出这个位置之前会渲染成多少行 → 用总渲染行数减去前缀行数 → 返回尾巴行数。

调用关系：active_tail_budget_lines 在发现表格或疑似表头时调用它。

调用图：调用 1 个内部函数（stable_prefix_len_for_source_start）；被 1 处调用（active_tail_budget_lines）。

fn stable_prefix_len_for_source_start(&mut self, source_start: usize) -> usize

作用：计算表格开始前的那段原文会渲染成几行，并缓存结果。缓存能避免表格一行行到来时反复做同样的渲染。

数据流：输入源文本位置 → 如果缓存的起点和宽度匹配就直接返回；否则渲染前缀文本、数行数、写入缓存 → 返回前缀行数。

调用关系：tail_budget_from_source_start 调用它；它直接调用 Markdown 渲染器来得到准确行数。

调用图：调用 1 个内部函数（render_markdown_agent_with_links_and_cwd）；被 1 处调用（tail_budget_from_source_start）；外部调用 3 个（now, as_path, trace!）。

fn new(width: Option<usize>, cwd: &Path, render_mode: HistoryRenderMode) -> Self

作用：创建普通助手消息的流式控制器。它在 StreamCore 之外再记录消息头是否已经显示。

数据流：输入宽度、当前目录和渲染模式 → 创建 StreamCore，并把 header_emitted 设为 false → 返回普通消息控制器。

调用关系：上层收到助手流式回答时会创建它；内部依赖 StreamCore::new。

调用图：调用 1 个内部函数（new）；被 4 处调用（handle_streaming_delta, flush_answer_stream_keeps_default_reflow_for_plain_text_tail, flush_answer_stream_requests_scrollback_reflow_for_live_table_tail, stream_controller）。

fn push(&mut self, delta: &str) -> bool

作用：把普通助手消息的新片段送进流式系统。调用者不用关心表格和队列细节。

数据流：输入 delta → 直接交给 core.push_delta → 返回是否有稳定行入队。

调用关系：这是普通消息外层入口，实际工作由 StreamCore::push_delta 完成。

调用图：调用 1 个内部函数（push_delta）。

fn finalize(&mut self) -> (Option<Box<dyn HistoryCell>>, Option<String>)

作用：结束普通助手消息流，并拿到最后要写入历史的单元和原始 Markdown。原文会用于后续整理成正式聊天记录。

数据流：调用 core.finalize_remaining 得到剩余行 → 如果没有原文就重置并返回空；否则取走原文、emit 成消息单元、重置状态 → 返回单元和原文。

调用关系：一次助手回答结束时调用；它把核心结果交给 emit 包装成 AgentMessageCell。

调用图：调用 3 个内部函数（emit, finalize_remaining, reset）；外部调用 1 个（take）。

fn on_commit_tick(&mut self) -> (Option<Box<dyn HistoryCell>>, bool)

作用：普通消息每次动画 tick 时取一小步稳定内容显示。它返回这步的历史单元和队列是否空了。

数据流：从 core.tick 取行 → 用 emit 包装 → 查询 core.is_idle → 返回可显示单元和空闲状态。

调用关系：drain_stream_controller 等外层排队刷新逻辑会调用它。

调用图：调用 3 个内部函数（emit, is_idle, tick）；被 1 处调用（drain_stream_controller）。

fn on_commit_tick_batch(
        &mut self,
        max_lines: usize,
    ) -> (Option<Box<dyn HistoryCell>>, bool)

作用：普通消息一次取多行稳定内容显示。适合需要快速排空队列的时候。

数据流：输入最多行数 → core.tick_batch 取出这些行 → emit 包装 → 返回单元和是否空闲。

调用关系：批量排空普通消息流时由 drain_stream_controller 调用。

调用图：调用 3 个内部函数（emit, is_idle, tick_batch）；被 1 处调用（drain_stream_controller）。

fn queued_lines(&self) -> usize

作用：查看普通消息还有多少稳定行等待提交。用于判断动画积压情况。

数据流：读取 core.queued_lines → 返回行数。

调用关系：它只是 StreamCore 对外的一层普通消息接口。

调用图：调用 1 个内部函数（queued_lines）。

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

作用：查看普通消息队列里最早内容等了多久。上层可以用它决定是否加速刷新。

数据流：输入当前时间 → 转给 core.oldest_queued_age → 返回等待时长或空。

调用关系：它把 StreamCore 的队列年龄信息暴露给普通消息调度。

调用图：调用 1 个内部函数（oldest_queued_age）。

fn current_tail_lines(&self) -> Vec<HyperlinkLine>

作用：取得普通消息当前临时尾巴的原始显示行。外层可以把它放在活动单元里显示。

数据流：无额外输入 → 从 core.current_tail_lines 取出未入队尾巴 → 返回这些行。

调用关系：UI 渲染普通助手正在输出的尾部时会用它。

调用图：调用 1 个内部函数（current_tail_lines）。

fn tail_starts_stream(&self) -> bool

作用：判断当前尾巴是不是从整条消息开头就开始。这样 UI 能决定是否还需要显示消息头。

数据流：读取 header_emitted 和 core.enqueued_stable_len → 如果头没发且稳定区为空就返回 true。

调用关系：活动尾巴显示时用它判断尾巴是不是第一块内容。

fn has_live_tail(&self) -> bool

作用：判断普通消息有没有正在变化的尾巴。比如表格正在生成时通常会有。

数据流：调用 core.has_tail → 返回是否存在尾巴。

调用关系：上层用它决定是否显示临时流尾单元。

调用图：调用 1 个内部函数（has_tail）。

fn clear_queue(&mut self)

作用：清掉普通消息当前等待提交的稳定队列。它还把已入队边界拉回到已发出位置，避免状态不一致。

数据流：清空 core.state 队列 → 把 enqueued_stable_len 设为 emitted_stable_len → 内部队列被丢弃。

调用关系：外层需要取消或重排队列时会用它。

fn set_width(&mut self, width: Option<usize>)

作用：通知普通消息控制器终端内容宽度变了。它会触发核心重新排版。

数据流：输入新宽度 → 转给 core.set_width → 内部渲染和队列按新宽度更新。

调用关系：窗口 resize 后由上层调用；实际复杂处理在 StreamCore::set_width。

调用图：调用 1 个内部函数（set_width）。

fn set_render_mode(&mut self, render_mode: HistoryRenderMode)

作用：切换普通消息的显示方式，比如富文本和原始文本。它让核心重新渲染当前流。

数据流：输入新渲染模式 → 转给 core.set_render_mode → 内部队列和尾巴随之重建。

调用关系：设置变化时由上层调用；具体重排由 StreamCore 完成。

调用图：调用 1 个内部函数（set_render_mode）。

fn emit(&mut self, lines: Vec<HyperlinkLine>) -> Option<Box<dyn HistoryCell>>

作用：把普通助手消息的一组显示行包装成历史单元。第一次输出时会带上消息头，之后就不重复带头。

数据流：输入若干 HyperlinkLine → 如果为空返回空；否则创建 AgentMessageCell，并更新 header_emitted → 返回可插入历史的单元。

调用关系：finalize、on_commit_tick 和 on_commit_tick_batch 都用它把核心行变成 UI 能放进聊天记录的东西。

调用图：调用 1 个内部函数（new_hyperlink_lines）；被 3 处调用（finalize, on_commit_tick, on_commit_tick_batch）；外部调用 1 个（new）。

fn new(width: Option<usize>, cwd: &Path, render_mode: HistoryRenderMode) -> Self

作用：创建“提议计划”的流式控制器。它除了核心流式状态，还记录计划标题和顶部空行是否已经显示。

数据流：输入宽度、当前目录和渲染模式 → 创建 StreamCore，并把 header_emitted、top_padding_emitted 设为 false → 返回计划控制器。

调用关系：上层收到计划流时创建它；底层仍使用 StreamCore::new。

调用图：调用 1 个内部函数（new）；被 5 处调用（on_plan_delta, completed_token_activity_refresh_retries_after_plan_item_completion, completed_plan_table_tail_skips_provisional_history_insert, finalized_plan_stream_preserves_semantic_url_fragments, plan_stream_controller）。

fn push(&mut self, delta: &str) -> bool

作用：把计划内容的新片段送进流式系统。它复用普通消息一样的稳定区和尾巴机制。

数据流：输入 delta → 交给 core.push_delta → 返回是否有稳定行入队。

调用关系：计划流的外层入口，真正的增量处理由 StreamCore 负责。

调用图：调用 1 个内部函数（push_delta）。

fn finalize(&mut self) -> (Option<Box<dyn HistoryCell>>, Option<String>)

作用：结束计划流，返回最终计划单元和原始 Markdown。它会在最后补上计划块底部留白。

数据流：调用 core.finalize_remaining → 如果没有原文就重置并返回空；否则取走原文、emit 剩余行且包含底部空行、重置 → 返回单元和原文。

调用关系：计划输出结束时调用；它把核心结果交给计划专用 emit 包装。

调用图：调用 3 个内部函数（emit, finalize_remaining, reset）；外部调用 1 个（take）。

fn on_commit_tick(&mut self) -> (Option<Box<dyn HistoryCell>>, bool)

作用：计划流每次动画 tick 时提交一小步稳定内容。中途提交不会加底部留白。

数据流：从 core.tick 取一批行 → 用计划 emit 包装且不带底部 padding → 查询是否空闲 → 返回单元和状态。

调用关系：drain_plan_stream_controller 会在计划流播放队列时调用它。

调用图：调用 3 个内部函数（emit, is_idle, tick）；被 1 处调用（drain_plan_stream_controller）。

fn on_commit_tick_batch(
        &mut self,
        max_lines: usize,
    ) -> (Option<Box<dyn HistoryCell>>, bool)

作用：计划流一次提交多行稳定内容。它适合快速排空计划队列。

数据流：输入最多行数 → core.tick_batch 取行 → emit 为计划单元且不带底部留白 → 返回单元和是否空闲。

调用关系：批量排空计划流时由 drain_plan_stream_controller 调用。

调用图：调用 3 个内部函数（emit, is_idle, tick_batch）；被 1 处调用（drain_plan_stream_controller）。

fn queued_lines(&self) -> usize

作用：查看计划流还有多少稳定行没显示。它用于调度和测试。

数据流：读取 core.queued_lines → 返回待显示行数。

调用关系：这是计划控制器对 StreamCore 队列长度的简单转发。

调用图：调用 1 个内部函数（queued_lines）。

fn has_live_tail(&self) -> bool

作用：判断计划内容是否有正在变化的尾巴。表格计划常会被留在尾巴直到最终确定。

数据流：调用 core.has_tail → 返回是否有可变尾巴。

调用关系：上层决定是否显示计划临时尾巴时会用它。

调用图：调用 1 个内部函数（has_tail）。

fn current_tail_lines(&self) -> Vec<HyperlinkLine>

作用：取出计划流的未稳定尾巴行，未加计划块外观。它是计划尾巴显示的原材料。

数据流：从 core.current_tail_lines 读取 → 返回尾巴行。

调用关系：current_tail_display_lines 会在它基础上加计划样式。

调用图：调用 1 个内部函数（current_tail_lines）；被 1 处调用（current_tail_display_lines）。

fn tail_starts_stream(&self) -> bool

作用：判断计划尾巴是否从计划块开头开始。这样 UI 能决定是否要连同标题一起显示。

数据流：读取 header_emitted 和 core.enqueued_stable_len → 如果标题未发且稳定边界为 0，就返回 true。

调用关系：计划活动尾巴渲染时可用它判断显示形态。

fn current_tail_display_lines(&self) -> Vec<HyperlinkLine>

作用：取得已经加好计划标题、缩进和样式的尾巴行。它给 UI 直接显示临时计划块用。

数据流：先取 current_tail_lines → 如果为空返回空；否则调用 render_display_lines 加外观 → 返回可显示行。

调用关系：它连接核心尾巴数据和计划专用展示格式。

调用图：调用 2 个内部函数（current_tail_lines, render_display_lines）；外部调用 1 个（new）。

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

作用：查看计划稳定队列中最早内容等了多久。用于判断计划动画是否积压。

数据流：输入当前时间 → 转给 core.oldest_queued_age → 返回时长或空。

调用关系：计划流调度可以用它和普通消息一样做节奏控制。

调用图：调用 1 个内部函数（oldest_queued_age）。

fn clear_queue(&mut self)

作用：清空计划流当前等待提交的稳定队列。它同步修正入队边界，避免之后重复显示。

数据流：清空 core.state 队列 → 把 enqueued_stable_len 改成 emitted_stable_len → 队列被重置。

调用关系：外层需要取消或重排计划流时会用它。

fn set_width(&mut self, width: Option<usize>)

作用：通知计划控制器内容宽度变了。计划正文会按新宽度重新排版。

数据流：输入新宽度 → 调用 core.set_width → 内部渲染快照和队列被更新。

调用关系：终端 resize 后由上层调用，核心处理和普通消息相同。

调用图：调用 1 个内部函数（set_width）。

fn set_render_mode(&mut self, render_mode: HistoryRenderMode)

作用：切换计划内容的渲染方式。它让计划流在新模式下保持队列和尾巴正确。

数据流：输入新渲染模式 → 转给 core.set_render_mode → 内部重新渲染并重建必要队列。

调用关系：设置变化时由上层调用，实际重排由 StreamCore 完成。

调用图：调用 1 个内部函数（set_render_mode）。

fn emit(
        &mut self,
        lines: Vec<HyperlinkLine>,
        include_bottom_padding: bool,
    ) -> Option<Box<dyn HistoryCell>>

作用：把计划内容行包装成一个计划历史单元。它负责决定是不是续块，以及要不要加底部空行。

数据流：输入显示行和是否包含底部留白 → 如果没有行且不需要留白就返回空；否则渲染计划外观、更新标题和顶部留白状态 → 返回计划单元。

调用关系：计划 finalize 和提交 tick 都通过它生成 new_proposed_plan_stream。

调用图：调用 1 个内部函数（render_display_lines）；被 3 处调用（finalize, on_commit_tick, on_commit_tick_batch）；外部调用 2 个（new, new_proposed_plan_stream）。

fn render_display_lines(
        &self,
        lines: Vec<HyperlinkLine>,
        include_bottom_padding: bool,
    ) -> Vec<HyperlinkLine>

作用：给计划正文加上“Proposed Plan”标题、空行、缩进和背景样式。它把普通渲染行变成计划块外观。

数据流：输入正文行和是否加底部空行 → 必要时加标题和顶部空行；正文前加两个空格并套用计划样式；可选加底部空行 → 返回最终显示行。

调用关系：emit 和 current_tail_display_lines 都调用它，是计划流样式的集中出口。

调用图：调用 3 个内部函数（proposed_plan_style, new, prefix_hyperlink_lines）；被 2 处调用（current_tail_display_lines, emit）；外部调用 3 个（from, with_capacity, vec!）。

fn test_cwd() -> PathBuf

作用：给测试提供一个稳定的当前目录。这样测试不用依赖具体操作系统的根目录写法。

数据流：无输入 → 读取系统临时目录 → 返回 PathBuf。

调用关系：测试里的控制器工厂都会调用它。

调用图：外部调用 1 个（temp_dir）。

fn stream_controller(width: Option<usize>) -> StreamController

作用：快速创建一个测试用普通消息控制器。它减少每个测试里的重复设置。

数据流：输入宽度 → 使用 test_cwd 和 Rich 渲染模式创建 StreamController → 返回控制器。

调用关系：大量普通消息测试都用它作为起点。

调用图：调用 1 个内部函数（new）；外部调用 1 个（test_cwd）。

fn plan_stream_controller(width: Option<usize>) -> PlanStreamController

作用：快速创建一个测试用计划控制器。它统一计划流测试的默认环境。

数据流：输入宽度 → 使用 test_cwd 和 Rich 模式创建 PlanStreamController → 返回控制器。

调用关系：计划相关测试都通过它创建控制器。

调用图：调用 1 个内部函数（new）；外部调用 1 个（test_cwd）。

fn lines_to_plain_strings(lines: &[ratatui::text::Line<'_>]) -> Vec<String>

作用：把带样式的终端行转成普通字符串。测试只关心文字内容时会用它。

数据流：输入 ratatui Line 列表 → 把每行所有 span 的文字拼起来 → 返回字符串列表。

调用关系：很多测试用它比较实际输出和预期输出。

调用图：外部调用 1 个（iter）。

fn hyperlink_lines_to_plain_strings(lines: &[HyperlinkLine]) -> Vec<String>

作用：把带链接信息的行转成普通字符串。这样测试可以忽略链接样式，只比可见文字。

数据流：输入 HyperlinkLine 列表 → 先取可见行，再转成普通字符串 → 返回字符串列表。

调用关系：尾巴和表格显示测试会用它查看当前画面文字。

调用图：调用 1 个内部函数（visible_lines）；外部调用 2 个（lines_to_plain_strings, to_vec）。

fn collect_streamed_lines(deltas: &[&str], width: Option<usize>) -> Vec<String>

作用：模拟普通消息从多个 delta 流式输出到最终结束，并收集所有显示文字。它让测试能像真实运行一样检查结果。

数据流：输入 delta 列表和宽度 → 逐段 push、不断 tick 排队内容、最后 finalize → 去掉普通消息前缀后返回文本行。

调用关系：许多普通消息 Markdown 和表格测试用它生成实际流式输出。

调用图：外部调用 3 个（new, lines_to_plain_strings, stream_controller）。

fn collect_plan_streamed_lines(deltas: &[&str], width: Option<usize>) -> Vec<String>

作用：模拟计划内容完整流式输出，并收集最终显示文字。它用于比较计划流分段输出和一次性输出是否一致。

数据流：输入 delta 列表和宽度 → 逐段 push、tick、finalize → 返回计划块显示行的普通字符串。

调用关系：计划表格和 Markdown fenced table 测试主要用它。

调用图：外部调用 3 个（new, lines_to_plain_strings, plan_stream_controller）。

fn controller_set_width_rebuilds_queued_lines()

作用：验证窗口变窄后，已经排队但还没显示的行会按新宽度重新换行。没有这个保护，用户会看到旧宽度下的排版。

数据流：创建控制器并推入长行 → 确认先入队一行 → 改宽度到更窄 → 批量 tick 后检查输出变成多行。

调用关系：直接覆盖 StreamCore::set_width 重建队列的行为。

调用图：外部调用 4 个（assert!, assert_eq!, lines_to_plain_strings, stream_controller）。

fn controller_set_width_no_duplicate_after_emit()

作用：验证已经显示过的内容在 resize 后不会再次入队。它防止聊天记录出现重复行。

数据流：推入并完全显示一行 → 改宽度 → 检查队列仍为空。

调用关系：针对 set_width 中“无待队列无尾巴时不要重放”的分支。

调用图：外部调用 3 个（assert!, assert_eq!, stream_controller）。

fn controller_tick_batch_zero_is_noop()

作用：验证批量 tick 数量为 0 时什么也不发生。这样调用方传 0 不会误清队列。

数据流：推入一行形成队列 → 调用 batch tick 0 → 检查没有输出、未空闲、队列长度不变。

调用关系：覆盖 StreamCore::tick_batch 的保护分支。

调用图：外部调用 3 个（assert!, assert_eq!, stream_controller）。

fn controller_has_live_tail_reflects_tail_presence()

作用：验证普通消息的 has_live_tail 能正确反映有没有尾巴。它直接检查边界比较是否可靠。

数据流：创建控制器 → 手动放入一条渲染行并调整 enqueued_stable_len → 分别检查有尾巴和无尾巴。

调用关系：覆盖 StreamController::has_live_tail 和 StreamCore::has_tail。

调用图：外部调用 3 个（assert!, stream_controller, vec!）。

fn plan_controller_has_live_tail_reflects_tail_presence()

作用：验证计划流的 has_live_tail 也能正确判断尾巴存在。计划和普通消息应使用同一套核心逻辑。

数据流：创建计划控制器 → 手动设置渲染行和稳定边界 → 检查 true/false 结果。

调用关系：覆盖 PlanStreamController::has_live_tail 和 StreamCore::has_tail。

调用图：外部调用 3 个（assert!, plan_stream_controller, vec!）。

fn controller_live_tail_keeps_uncommitted_table_cell_newline_gated()

作用：验证表格里未换行结束的半个单元格不会出现在尾巴里。这样用户不会看到临时坏掉的表格。

数据流：推入表头、分隔行和未完成的 partial → 读取当前尾巴文字 → 确认不包含 partial。

调用关系：覆盖 push_delta 只提交完整行的规则和表格 holdback 行为。

调用图：外部调用 3 个（assert!, hyperlink_lines_to_plain_strings, stream_controller）。

fn controller_live_tail_requires_table_holdback_state()

作用：验证普通未换行文字不会自动成为 live tail。没有表格延后状态时，半截内容应留在收集器里。

数据流：推入没有换行的普通文本 → 读取尾巴和 has_live_tail → 检查二者都为空或 false。

调用关系：针对 collector 与表格 holdback 的边界行为。

调用图：外部调用 2 个（assert!, stream_controller）。

fn controller_live_tail_rerenders_table_tail_after_resize()

作用：验证表格尾巴在窗口宽度变化后会重新渲染。表格尾巴必须跟最终 Markdown 渲染保持一致。

数据流：推入表格 → 多次改变宽度 → 每次读取尾巴并和同宽度完整渲染结果比较。

调用关系：覆盖 set_width 对 live table tail 的保护和重排。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 5 个（new, assert_eq!, hyperlink_lines_to_plain_strings, lines_to_plain_strings, stream_controller）。

fn controller_set_width_partial_drain_no_lost_lines()

作用：验证队列只播放了一部分时 resize 不会丢掉后面的内容。特别检查第二行仍能在 finalize 时出现。

数据流：推入长行和第二行 → tick 一次留下队列 → 改窄宽度 → finalize 并检查第二行存在。

调用关系：针对 set_width 在部分已发出、部分仍排队时的修正逻辑。

调用图：外部调用 2 个（assert!, stream_controller）。

fn controller_set_width_partial_drain_keeps_pending_queue()

作用：验证部分播放后 resize 会保留待播放队列。它确保队列还能继续 drain。

数据流：推入两行并 tick 一次 → 改宽度 → 检查仍有队列 → 持续 tick 并确认第二行出现。

调用关系：覆盖 set_width 后 rebuild_stable_queue_from_render 的实际可播放性。

调用图：外部调用 4 个（new, assert!, lines_to_plain_strings, stream_controller）。

fn controller_set_width_preserves_in_flight_tail()

作用：验证没有换行的在途尾巴在 resize 后不会消失。最终结束时仍应显示这段文字。

数据流：推入未换行文本 → 改宽度 → finalize → 检查输出包含该尾巴。

调用关系：覆盖 resize 对 collector 中未完成内容的保护。

调用图：外部调用 3 个（assert_eq!, lines_to_plain_strings, stream_controller）。

fn controller_set_width_preserves_table_tail_when_queue_is_empty()

作用：验证队列为空但表格尾巴存在时，resize 不能误以为没有东西要保留。表头仍应留在 live tail。

数据流：先推入并播放 intro → 推入表格表头形成尾巴 → 改宽度 → 检查尾巴仍包含表头内容。

调用关系：覆盖 set_width 中 had_live_tail 的重要分支。

调用图：外部调用 4 个（assert!, assert_eq!, hyperlink_lines_to_plain_strings, stream_controller）。

fn plan_controller_set_width_preserves_in_flight_tail()

作用：验证计划流中未完成尾巴在 resize 后也不会丢。计划控制器应和普通消息一样安全。

数据流：推入未换行计划项 → 改宽度 → finalize → 检查输出里还有该计划项。

调用关系：覆盖 PlanStreamController 通过 StreamCore::set_width 保护尾巴的行为。

调用图：外部调用 3 个（assert!, lines_to_plain_strings, plan_stream_controller）。

fn plan_controller_holds_table_header_as_live_tail()

作用：验证计划流里的表格表头会先留作 live tail，而不是马上写进历史。这样后续分隔行到来时表格能整体重排。

数据流：推入 Intro 并排空 → 推入表格表头 → 检查没有新队列但有 live tail。

调用关系：覆盖计划流表格 holdback 对 PendingHeader 的处理。

调用图：外部调用 2 个（assert!, plan_stream_controller）。

fn controller_loose_vs_tight_with_commit_ticks_matches_full()

作用：验证复杂 Markdown 列表分段流式输出后，结果和一次性完整渲染一样。它防止增量提交破坏列表格式。

数据流：把松散列表和紧凑列表拆成很多 delta → 边 push 边 tick 收集输出 → 和完整 Markdown 渲染及手写预期比较。

调用关系：覆盖普通消息流式渲染与 Markdown 解析的一致性。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 5 个（new, assert_eq!, lines_to_plain_strings, stream_controller, vec!）。

fn controller_streamed_table_matches_full_render_widths()

作用：验证普通表格流式输出与完整渲染一致。表格不应因为分段到达而格式不同。

数据流：分段推入表格 → 收集流式输出 → 用完整源文本渲染一次 → 比较两者。

调用关系：覆盖表格 holdback 到 finalize 后的最终一致性。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 5 个（new, assert_eq!, collect_streamed_lines, lines_to_plain_strings, vec!）。

fn controller_holds_blockquoted_table_tail_until_stable()

作用：验证引用块里的表格也会被正确延后处理。带 > 的表格不能被误当成普通文本乱提交。

数据流：流式推入 blockquote 表格 → 收集输出 → 和完整渲染比较。

调用关系：覆盖表格扫描器对引用表格的支持。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 5 个（new, assert_eq!, collect_streamed_lines, lines_to_plain_strings, vec!）。

fn controller_keeps_pre_table_lines_queued_when_table_is_confirmed()

作用：验证表格确认后，表格前面的普通行仍可以独立提交。表格延后不应该把前面的文字卡住。

数据流：推入表格前说明行并确认入队 → 推入表头和分隔行 → 检查队列仍只有前文并能正常提交。

调用关系：覆盖 holdback 只从表格开始处扣住尾巴的规则。

调用图：外部调用 3 个（assert!, assert_eq!, stream_controller）。

fn controller_set_width_during_confirmed_table_stream_matches_finalize_render()

作用：验证确认中的表格遇到 resize 后，最终显示和新宽度完整渲染一致。它防止表格在宽度变化后错位。

数据流：推入表格并保持可变 → 改窄宽度 → finalize → 和同宽度完整渲染比较。

调用关系：覆盖 live table tail 的 resize 和 finalize 组合流程。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 4 个（new, assert_eq!, lines_to_plain_strings, stream_controller）。

fn controller_does_not_hold_back_pipe_prose_without_table_delimiter()

作用：验证含竖线的普通句子不会被误判成表格长期扣住。只有后面跟表格分隔线才算表格。

数据流：推入带竖线的普通行并播放 → 推入下一行 → 确认下一次能释放内容。

调用关系：覆盖表格扫描器区分 pipe prose 和 table 的能力。

调用图：外部调用 2 个（assert!, stream_controller）。

fn controller_does_not_stall_repeated_pipe_prose_paragraphs()

作用：验证多段含竖线但不是表格的文字不会让流式输出停住。它防止错误 holdback 造成卡屏。

数据流：推入两段 pipe prose → 第二次提交时检查第一段已经能出现。

调用关系：继续覆盖非表格竖线文本的释放逻辑。

调用图：外部调用 2 个（assert!, stream_controller）。

fn controller_handles_table_immediately_after_heading()

作用：验证标题后面立刻跟表格也能正确渲染。表格前没有空行或只有标题时不应破坏格式。

数据流：分段推入标题和表格 → 收集流式输出 → 和完整渲染比较。

调用关系：覆盖表格扫描和 Markdown 渲染在标题相邻场景下的一致性。

调用图：调用 1 个内部函数（append_markdown_agent）；外部调用 5 个（new, assert_eq!, collect_streamed_lines, lines_to_plain_strings, vec!）。

fn controller_renders_separators_for_multi_table_response_shape()

作用：验证一段回答里多个表格最终会渲染出表格分隔线。它确保真实复杂回答不会退化成原始竖线文本。

数据流：把多表格大文本按行切成 delta → 收集输出 → 检查其中出现表格分隔符。

调用关系：覆盖多表格流式处理和最终表格样式。

调用图：外部调用 2 个（assert!, collect_streamed_lines）。