Function convert_file

scripts/convert.py:170–227

转换/处理单个文件。返回 (成功与否, 消息)。 Pipeline: 1. 非 .md：markitdown 转为 markdown 文本；.md：直接读原文 2. postprocess.process 加锚点 + 生成 outline 数据 3. 写 .md（仅当内容变化）+ 写 .outline.json

(md: MarkItDown, source: Path)

def convert_file(md: MarkItDown, source: Path) -> tuple[bool, str]:
    """
    转换/处理单个文件。返回 (成功与否, 消息)。

    Pipeline:
      1. 非 .md：markitdown 转为 markdown 文本；.md：直接读原文
      2. postprocess.process 加锚点 + 生成 outline 数据
      3. 写 .md（仅当内容变化）+ 写 .outline.json
    """
    is_md = source.suffix.lower() == ".md"

    if is_md:
        try:
            markdown = source.read_text(encoding="utf-8")
        except Exception as e:
            return False, f"读取失败: {e}"
        target_md = source
    else:
        result = md.convert(str(source))
        markdown = result.markdown if result.markdown else ""
        if not markdown.strip():
            return False, "转换结果为空"
        target_md = source.with_suffix(".md")

    target_outline = source.with_suffix(".outline.json")
    doc_path = _project_relative_posix(target_md)

    # 读旧 outline（如果存在），让 process 保留 agent_summary
    previous_outline = None
    if target_outline.exists():
        try:
            previous_outline = json.loads(target_outline.read_text(encoding="utf-8"))
        except Exception:
            previous_outline = None

    text_with_anchors, outline_data = postprocess_text(
        markdown, doc_path, previous_outline=previous_outline
    )

    # 仅当内容变化时写 .md（保护 git 工作树）
    md_changed = (
        not target_md.exists()
        or target_md.read_text(encoding="utf-8") != text_with_anchors
    )
    if md_changed:
        _atomic_write_text(target_md, text_with_anchors)

    _atomic_write_text(
        target_outline,
        json.dumps(outline_data, ensure_ascii=False, indent=2),
    )

    sec_count = sum(_count_sections(s) for s in outline_data["sections"])
    md_msg = "新增" if md_changed else "未变"
    return True, (
        f"-> {target_md.name} ({md_msg}, {len(text_with_anchors)} 字符, "
        f"{sec_count} 章节, {outline_data['doc_paragraphs']} 段)"
    )