Function build_outline_data

scripts/postprocess.py:219–278

基于已加锚点的 markdown 文本构建 outline.json 数据结构。 输入约定：text_with_anchors 应当已经被 add_anchors 处理过（每个块末尾 带 ` ^h-/^p-/...` 锚点）。本函数只切一次块，从行末回填 anchor，构建 嵌套 section 树。 若提供 previous_outline，会按 anchor（失配再按 title）把旧 agent_summary 合并进 新 outline——见 _restore_summaries。 **谁会传 previous_outli

(
    text_with_anchors: str,
    doc_path: str,
    *,
    previous_outline: dict | None = None,
)

def build_outline_data(
    text_with_anchors: str,
    doc_path: str,
    *,
    previous_outline: dict | None = None,
) -> dict:
    """
    基于已加锚点的 markdown 文本构建 outline.json 数据结构。

    输入约定：text_with_anchors 应当已经被 add_anchors 处理过（每个块末尾
    带 ` ^h-/^p-/...` 锚点）。本函数只切一次块，从行末回填 anchor，构建
    嵌套 section 树。

    若提供 previous_outline，会按 anchor（失配再按 title）把旧 agent_summary 合并进
    新 outline——见 _restore_summaries。

    **谁会传 previous_outline（口径说明）**：只有 convert.py 的 raw re-convert 路径
    传它，处理对象是**不可变的 raw 源**（CLAUDE.md 视 raw 为事实来源，仅当源文件真
    改才重转，且增量转换跳过未变文件，故 re-convert 罕见）。k.py 的 wiki 读路径
    （load_or_build_outline）**不传** previous_outline——wiki 页可被 agent/人直接
    频繁编辑、整页换主题的风险高，过期即整体丢弃不合并。两条路径口径不同是**按对象
    特性的有意取舍**，非疏忽。
    已知残留：heading 锚点 hash 仅基于标题文本（见 :121），故"同标题换正文"在
    re-convert 路径仍可能复活旧摘要；因 raw 不可变 + 重转罕见，该残留风险低、接受。

    注：早期版本曾要求传入 add_anchors 返回的 blocks 列表，但实测 blocks
    的 char_start/char_end 是基于"加锚前 body"的偏移，加锚后会漂移；保留
    blocks 参数反而误导。本函数现在只接受 text_with_anchors，单次切块即可。
    """
    fm, body = strip_frontmatter(text_with_anchors)
    fm_offset = len(fm)

    # 切块 + 从行末回填 anchor（一次切块，一次扫描，无重复工作）
    parsed_blocks = split_blocks(body)
    for blk in parsed_blocks:
        if blk.kind == "hr":
            continue
        m = _BLOCK_ANCHOR_TAIL_RE.search(blk.text)
        if m:
            blk.anchor = m.group(1)
        # body 偏移 → 完整文件偏移
        blk.char_start += fm_offset
        blk.char_end += fm_offset

    total_chars = len(text_with_anchors)
    outline = build_outline(parsed_blocks, total_chars)
    sections_dicts = [section_to_dict(s) for s in outline["sections"]]

    if previous_outline:
        old_summaries = _collect_summaries(previous_outline.get("sections", []))
        if old_summaries:
            _restore_summaries(sections_dicts, old_summaries)

    return {
        "doc_path": doc_path,
        "doc_chars": total_chars,
        "doc_paragraphs": outline["paragraphs_count"],
        "generated_at": date.today().isoformat(),