#WorkBuddy# 万字长文档别整篇丢给 AI：目录 → 分块 → 逐块摘要 → 覆盖校验，一条零依赖脚本跑完（macOS 实测）

# 环境：macOS，Python 3.9+，零第三方依赖
mkdir -p longdoc-demo && cd longdoc-demo
curl -O https://example.com/longdoc_kit.py   # 换成你自己的存放路径
python3 make_longdoc_demo.py                 # 生成一份虚构示例文档

python3 longdoc_kit.py outline longdoc-demo/spec_v23.md --stats
echo $?    # 有跳级返回 1

文件: longdoc-demo/spec_v23.md
总行数: 429  字符数: 15233
识别标题: 59 个（朴素 ^# 扫描: 77 个，含围栏内误判）
层级分布: H1=1  H2=13  H3=30  H4=15
------------------------------------------------------------
H1  L   7  智能办公助手部署与运维规范（示例文档）
  H2  L  12  1. 部署前检查
    H3  L  16  1.1 环境依赖
    ...
------------------------------------------------------------
[WARN] 检测到 1 处层级跳级，目录可能编号有误：
       H2 → H4  8.0 跳级小节（示例：H2 下直接 H4）

python3 longdoc_kit.py chunk longdoc-demo/spec_v23.md --max-chars 3000 --overlap 200
python3 longdoc_kit.py hardcut longdoc-demo/spec_v23.md --max-chars 3000  # 对照组

--- 硬切 max_chars=3000 ---
块数: 6
被切断的代码块: 2 处（该块内围栏数为奇数，AI 会看到半个代码块）
被切断的表格:   1 处（表头与数据行分家）

python3 longdoc_kit.py pack longdoc-demo/spec_v23.md --max-chars 3000 --overlap 150 --out packs/
# 输出：packs/chunk-01.md … chunk-14.md

只摘要下面这一个块，不要臆测块外内容。
输出三行：① 本块讲了什么（≤60 字）② 关键参数或结论（有就列，没有写"无"）
③ 本块是否包含表格（是/否，是则原样保留表头）
块内容：
<粘贴 chunk-XX.md>

python3 longdoc_kit.py verify longdoc-demo/spec_v23.md --max-chars 3000
echo $?    # 0=通过，1=有遗漏或重复，可直接挂流水线做门禁

覆盖校验: 块数=14  应覆盖正文行=264  实际覆盖=264  耗时=0.1 ms
覆盖率: 100.0%
[OK] 无遗漏
[OK] 无重复覆盖

python3 longdoc_kit.py tables longdoc-demo/spec_v23.md

共 11 张表
  #            行区间   列   数据行  表头
  1         L42-48   3     5  | # | 操作 | 示例阈值 |
  ...
 11       L423-427   3     3  | # | 版本 | 说明 |

# ① 先标围栏与 frontmatter，再找标题（顺序反了就全错）
ATX_RE = re.compile(r"^(#{1,6})[ \t]+(\S.*?)[ \t]*#*\s*$")
FENCE_RE = re.compile(r"^[ \t]{0,3}(```+|~~~+)")

def find_headings(doc):
    out = []
    for i, ln in enumerate(doc.lines):
        if doc.in_fence[i] or doc.is_frontmatter[i] or doc.is_table[i]:
            continue                      # 围栏内、frontmatter、表格行一律不看
        m = ATX_RE.match(ln)
        if m:
            out.append((len(m.group(1)), i, m.group(2).strip())); continue
        if i + 1 < doc.n and doc.lines[i].strip():
            if re.match(r"^=+[ \t]*$", doc.lines[i + 1]):
                out.append((1, i, doc.lines[i].strip()))     # Setext H1
            elif re.match(r"^-{3,}[ \t]*$", doc.lines[i + 1]):
                out.append((2, i, doc.lines[i].strip()))     # Setext H2
    return out

# ② 分块主循环：+1 是换行符；超长行切成片段且各自成块
for i in seg:
    ln = doc.lines[i]
    if cur and cur_len + len(ln) + 1 > max_chars:
        flush()
    if split_long and len(ln) > max_chars:
        flush()
        for piece in split_sentences(ln, max_chars):
            raw.append((path, [(i, piece)], {i}))   # 片段单独成块
        continue
    cur.append((i, ln)); cur_len += len(ln) + 1

# ③ 覆盖校验：按行号，不按文本
expect = set(doc.content_line_idxs())      # 非空、非 frontmatter 的行
covered = {}
for c in chunks:
    for i in set(c.lines):
        covered[i] = covered.get(i, 0) + 1
missing = sorted(expect - set(covered))    # 漏
dup = {i: n for i, n in covered.items()
       if n > 1 and i not in partial_lines}   # 重复（排除句子切分的行）

python3 longdoc_kit.py selftest
# [PASS] 目录提取 / 对照组 / 覆盖校验 —— 全部通过（3 项）