微信公众号案例汇聚 → 腾讯文档结构化表格

把一个或多个来源（单篇推文链接、用户整理的清单、公众号专辑页、网页案例汇总页）的案例/推文，汇聚成一张带可点击超链接、可分板块浏览、可按发布时间倒序的腾讯文档表格，并保证链接与标题严格对应、可复核。

何时使用

• 用户给出若干 mp.weixin.qq.com 链接或一个专辑页链接，要求"汇总/加进表格/继续补充"
• 用户已有此类表格，要求"再补一批""修一下丢掉的超链接""链接和标题错位了""按时间倒序重排"
• 用户要求做"板块/分类"以便浏览，或要求统计各板块条数
• 腾讯文档连接器不可用，需要先产出本地 xlsx 备份

不适用

• 抓取登录态内容、绕过验证码（不做）
• 修改他人文档（只操作本人有权限的 file_id）

六条铁律

> 全部来自真实事故复盘，违反任意一条都会产生静默错误（数据看着对、实际错位）。

1. 超链接绝不能用"批量读回填"。批量 get_cell_data（一次读多行）返回的 hyperlinks 字段存在行错位与末行/新写入行缓存缺失。建立"标题→URL"映射、核验链接，必须逐行单读（start_row=end_row=r, start_col=end_col=0, return_csv=False）——用 scripts/td_client.py: read_col_map()。
2. 行号不是稳定标识。跨表、跨批次比对一律用规范化标题（去空白与标点后的小写串）。排序会整体改变行号，任何按行号建立的映射在排序后立刻失效。
3. 写入必须分块（每次 6~8 行）。一次塞几十行中文 JSON 会触发 Windows 命令行超长（WinError 206）或服务端 WAF 501。用 write_values(..., chunk=6)。
4. 先备份，再改线上。任何批量改写/重排前，先用 scripts/backup_sheet_to_xlsx.py 落一份本地 xlsx。连接器票据随时可能被吊销，备份是唯一能保全成果的东西。
5. 改完必须回验。回验 = 逐行单读链接 + 抽样人工核对（顺带确认标题与链接同源）。只信回验结果，不信写入时的返回值。
6. 不猜元数据。作者、单位、发布时间必须来自原文或可信快照；查不到就写"待核实"，绝不编造。备注列要能解释"这条为什么可信"。

七阶段工作流

Phase 0 — 定列结构

先确认列定义，之后所有脚本都按这个顺序映射列下标。本项目验证过的列结构：

col0 推文名称（点击跳转原文）  ← 承载体超链接
col1 发布平台   col2 作者   col3 发布时间   col4 应用场景分类（初步判断）   col5 备注

发布时间统一写 YYYY-MM-DD（只有年月写 YYYY-MM），这是后续排序的解析依据。

Phase 1 — 采集

• 若干单篇链接：用 mp.weixin.qq.com/s/xxx（含 sn=32位hex 的长链最稳）。标题/作者/公众号/日期从 WebSearch 快照或原文取。
• 专辑页整页抓取：python scripts/fetch_album.py <biz> <album_id> <out.json>。参数提取与反爬现状见 references/wechat-harvest.md。
• 用户整理的清单文件（xls/xlsx/csv/txt）：解析出"标题 + 链接"两列再入库。
• 其他数据库（知网/万方/维普等）的元数据技巧见 references/wechat-harvest.md。

Phase 2 — 规范化与去重

去重优先级：sn(32位hex) → 短链尾段 → 规范化标题。td_client.norm_title() 同时用于去重与跨表比对，务必全流程共用同一函数。专辑抓取脚本已内置去重，输出 new / dupes 两组。

Phase 3 — 写入腾讯文档

import td_client as T
fid = T.create_sheet("文档标题")      # 或沿用已有 file_id
sids = T.get_sheets(fid)              # {sheet_name: sheet_id}
T.write_values(fid, sid, header_values, chunk=6)
T.write_values(fid, sid, row_values, chunk=6)
T.set_link(fid, sid, row, col=0, url)  # 逐行挂，失败的单独重试

随后设置样式：表头填充/字色、数据区自动换行、冻结首行、筛选、列宽。参数细节与全部工具见 references/tencent-sheet-mcp.md。

Phase 4 — 板块化（分类浏览）

每个板块一个子表 + 一个"板块总览"导航页（板块名/条数/内容说明）。一条记录只进一个板块，总表保留全量。参考板块划分：官方功能教程 / AI工具与智能体 / 教师备课与授课 / 双师课堂 / 学生自主学习与作业活动 / 家校共育与课后服务 / 教师研修与教研 / 学校管理与学情评价 / 汇总索引与案例清单。

Phase 5 — 校验（必做）

python scripts/verify_links.py --file-id <fid> \
    --sheet 工作表1=<sid> --sheet 双师课堂=<sid> --ref 工作表1

逐行单读每张表，输出：无链接的行、标题重复、与基准表不一致的链接。再抽查若干条，点开链接确认标题与内容同源。

Phase 6 — 排序（按需）

python scripts/sort_sheet_by_date.py --file-id <fid> --date-col 3 \
    --sheet 工作表1=<sid>:300 --sheet 双师课堂=<sid>:90

逻辑：批量读文本（文本可靠）→ 逐行单读取链接 → 按日期倒序（无日期沉底、稳定排序）→ 分块重写文本 → 按新行号逐行重挂链接（空 url 会清除旧链接）→ 回验。

Phase 7 — 备份与交付

python scripts/backup_sheet_to_xlsx.py --file-id <fid> --out 备份.xlsx

产出带超链接样式、冻结首行、自动筛选的本地备份，用 present_files 交付。

连接器不可用时的降级路径

若出现 no_token / provider ... connector_disabled：

1. 判定为用户侧授权被停用，不是临时抖动（间隔重试 3~4 次仍失败即可确认）。
2. 明确告知用户在 WorkBuddy 连接器管理中重新授权"腾讯文档"，不要反复重试。
3. 立即用本地数据产出 openpyxl 版 xlsx 并交付，同时把上云脚本写好，授权恢复后一条命令即可上云。

资源索引