agentleFS
ykjshenzhen2008-ship-itykjshenzhen2008-ship-it/commercial-real-estate-skills/skills/zsxq-bd-harvest/SKILL.md

zsxq-bd-harvest

Skill0 starsChanged 35 days agoMITView on GitHub

知识星球「招商品牌拓展」采集流水线。抓主题 → 抽品牌/联系人/电话/微信 → 下载图片 → 本地 OCR 认图里的文字 → 出 Excel 主表 → 备份到腾讯文档。当用户说「知识星球」「星球招商品牌」「拓店信息收集进表格」「每日招商品牌更新」「把星球的内容整理成表」时使用。

  • Installs packages

The file

Files
SKILL.md

知识星球招商品牌采集(zsxq-bd-harvest)

是什么

把知识星球里每天刷屏的招商品牌拓展帖(正文 + 海报/名片/表格截图)抽成一张可用的 Excel, 并备份到腾讯文档。文本和图片两条腿都要有——星球上大量信息只存在于图片里。

一键跑

PY=$HOME/.workbuddy/binaries/python/envs/default/bin/python
SK=~/.workbuddy/skills/zsxq-bd-harvest/scripts

# ① 每日增量:抓最近 1 天,全套跑到腾讯文档
$PY $SK/run_all.py --days 1

# ② 区间全量:抓近一年(含图片 OCR + 附件下载)
$PY $SK/run_all.py --start 2025-10-01 --label year \
    --outdir ~/WorkBuddy/知识星球年度全量_$(date +%Y%m%d)

# 抓最近 3 天,只落本地
$PY $SK/run_all.py --days 3 --outdir ~/WorkBuddy/知识星球_$(date +%Y%m%d) --no-upload

# 赶时间,跳过图片识别
$PY $SK/run_all.py --days 1 --skip-ocr

产物:知识星球招商品牌拓展总表_YYYYMMDD.xlsx(3 个工作表)+ 同结构 .csv。

区间全量(一年)怎么跑

一年全量的量级和每日增量差三个数量级,流程也不同:

每日增量区间全量(近一年实测)
抓取collect.py(从今天往回数 N 天)harvest_range.py(游标直跳历史时点)
下资产dl_images.py(只图片)dl_assets.py(图片 + 附件文件)
主题数~10 条/天2,379 条
图片0~5 张447 张
附件基本没有361 个 / 3.3 GB
耗时几分钟抓 2 分钟 + 下资产 ~30 分钟 + OCR ~2 小时

关键:游标能直跳,不用线性翻页

--end-time 不是「只能取比这更早的下一页」,而是可以直接跳到任意历史时点:

# 直接拿到 2025-09-30 的帖子,不必从今天一页页翻过去
zsxq-cli group +topics --group-id 28514852255141 --limit 30 \
  --end-time "2025-10-01T00:00:00.000+0800"

所以 harvest_range.py 可以按任意区间抓。一年 82 页 2,460 条原始记录,2 分钟抓完。

附件下载要两步

files[].file_id 本身不是 URL。得先换签名直链再下:

# 第一步:换 download_url(会起一次 node 进程,约 0.5s,361 个约几分钟)
zsxq-cli api raw --method GET --path /v2/files/<file_id>/download_url
# 返回 {"body":{"resp_data":{"download_url":"https://files.zsxq.com/...?token=..."}}}

# 第二步:curl 直链。files.zsxq.com 可直连,无需登录态
curl -sSL --fail -o out.pdf "<download_url>"

实测能下到《TOD模式研究-2026 91P.pdf》这类 15MB 的研报,单帖最多 8 个附件。 附件类型以 .pdf(208) / .pptx(83) / .xlsx(21) 为主,是星球里最值钱的部分。

长任务要串起来自己走完

OCR 要一两个小时,不能干等。做法是 finalize_year.py 在后台等 OCR 退出、 再自动出表并归档:

# 后台:等 OCR 和下载都结束 → 出 Excel → 把资产搬进交付目录
$PY $SK/finalize_year.py --work /tmp/zsxq_year --outdir ~/WorkBuddy/知识星球年度全量_$(date +%Y%m%d) \
    --wait-ocr --wait-download &

⚠️ /tmp 会被系统清理,3.3GB 附件必须搬进 ~/WorkBuddy/...。 /tmp 与 /Users 同卷(/dev/disk3s5),os.rename 是改名、瞬间完成,不会真拷 3.3GB。

输出表结构(Kelvin 2026-09-30 定版)

主表 招商品牌 固定 5 列,一个帖子一行:

列内容
品牌品牌名 / 项目名
联系人只放姓名,不含职务;抓不到就留空(职务不许冒充人名)
联系方式/微信电话:x|微信:x|邮箱:x|QQ:x,有什么显示什么
其他信息职务|业态|区域|面积|楼层位置|租金|模式|工程条件|备注|含图N张|⚠️提示|发布:日期|抓取方式
信息源星球原帖链接(可点超链接)

「联系人」和「职务」必须分家:职务统一走「其他信息」(职务:市场开发总监)。 反例——欢乐迪 这张名片只有职务没有姓名,早期版本把 市场开发总监 填进了「联系人」列, 读表的人会以为要找一个姓「市」的人。contact_cell() 现在只回姓名,职务由 other_info() 出。

另两个表:图片OCR原文(33 行,证据层)、说明与口径。

完整 26 字段不丢——留在 _源数据/文本层抽取_主题明细.csv 里做审计底稿。 改列结构只动 build_xlsx.py 的 Sheet1 段,别去删源 CSV。

两个结构上的设计决定(改代码前先读)

  1. 图片 OCR 结果并回所属主题行。不合并的话,带图帖会同时出「文本层」和「图片OCR」 两行、品牌重复,读表要自己拼。合并后「抓取方式」会显示 首行+图片OCR。 合并只并给该 主题ID 的首行(多品牌拆行时避免联系方式重复挂到每一行)。
  2. 主表按发布日期倒序,新帖在最上面,符合「今天有什么新品牌」的读法。

分步跑(调试用)

步骤命令产物
1 抓主题collect.py --fresh --days 1$WORK/raw/page_*.json
2 抽字段extract.py$WORK/zsxq_brands.csv + img_manifest.json
3 下图片dl_images.py $WORK/images33 张 jpg
4 图 OCRocr_batch.py$WORK/ocr_out/*.md + .txt
5 出表build_xlsx.py -o xx.xlsxExcel 主表
6 备份tdoc_upload.py xx.xlsx腾讯文档链接

ZSXQ_WORK 环境变量决定数据目录,脚本间靠它共享中间产物。

星球清单与权限(重要)

星球group_id状态
广东品牌拓店及商业资料28514852255141✅ 可采
商业地产资源信息平台28855115828521❌ 未开通 Skill 权限
每日商业地产操盘心得28511182812511❌ 未开通 Skill 权限

后两个返回 该星球暂未开通 Skill 权限,如需使用,可联系星主申请开通。 这是星主侧的开关,不是技术问题——要数据得让用户找星主开通。别反复重试。

二十七个必须知道的坑

最贵的九条是 6(姓氏表缺字→静默清空联系人)、16(校正跑在并表之前→整批绕过)、 18(清单在搬迁之前找文件→整列空白)、19(ocr_out 不清空→旧图混成孤儿行)、 20(OCR 侧人名兜底比文本层少三条→图片里的联系人静默丢失)、 21(首行兜底扫到第 4 行 + 称谓词表缺字→垃圾品牌与联系人丢失同帖发生)、 22(资源汇总帖未识别→101 个电话塞一格、号码与品牌人全错位)、 23(三层兜底全要求职务词→无职务的纯本名整批丢失,年度语料 112 行)、 26(只认全角 【…】→半角/混排括号标签整条失效、品牌静默留空)、 27(反爬「乱序插字」→品牌/区域变成乱码且不带任何告警**)。 它们的共同点:都不抛异常、日志看着正常、单测全绿,只是交付物里安静地少东西/错东西。** 判断任何一步是否安全,先问「这一步跑的时候,它要读的东西还在原处吗 / 是否已经被后续步骤改过 / 是否混进了上一次运行留下的东西」。

1. 腾讯文档上传:必须覆盖 API base

凭证网关下发的是内网友域 https://www-docs.workbuddy.cn,代理隧道对它一律 502:

ERROR:http_failed - Tunnel connection failed: 502 Bad Gateway

tdoc_upload.py 已内置 TDOC_API_BASE_URL=https://docs.qq.com。 如果你自己调 tencentdocs.py,必须手动带上这个环境变量,否则一定 502。

⚠️ tencentdocs.py 不在本 skill 的 scripts/ 下,在腾讯文档插件目录里,且带版本号, 升级插件后路径会变。用通配解析,别硬编版本号:

# 解析插件路径(版本号用通配,避免升级后失效)
T=$(ls -d ~/.workbuddy/plugins/cache/workbuddy-builtin/tencent-docs-plugin/*/skills/tencent-docs | tail -1)

TDOC_API_BASE_URL=https://docs.qq.com $PY "$T/tencentdocs.py" \
  tdoc_call tencent-docs manage.delete_file '{"file_id":"xxx","delete_type":"origin"}'

导入链路是三步:import_file.py(pre_import + COS PUT)→ manage.async_import → manage.import_progress 轮询到 progress=100。

腾讯文档不能覆盖更新——manage.pre_import 只有 file_name/file_size/file_md5 三个参数, 没有 file_id,每次导入都是新建一个文件。改了表要换版时:

# 1) 传新版,拿到新 file_id
$PY $SK/tdoc_upload.py 新文件.xlsx

# 2) 把旧版移入回收站(可恢复),避免用户文档里留两份同名不同结构的表
TDOC_API_BASE_URL=https://docs.qq.com $PY "$T/tencentdocs.py" tdoc_call tencent-docs \
  manage.delete_file '{"file_id":"<旧file_id>","delete_type":"origin"}'

# 3) 复核:确认同名文件只剩一份在列
TDOC_API_BASE_URL=https://docs.qq.com $PY "$T/tencentdocs.py" tdoc_call tencent-docs \
  manage.search_file '{"search_key":"知识星球招商"}'

manage.delete_file 是移入回收站(不是永久删除),所以换版可以放心做; 但仍要在回复里明确告诉用户「旧的已进回收站」。

列文件用 manage.search_file,参数名是 search_key(不是 keyword,也不是 manage.list_files——那个工具没注册)。

2. RE_TAIL_NOISE 是 $ 锚定的,位置不能挪

尾部噪声截断必须放在 clean_brand 的最后。放在函数开头等于白写—— 那时「逗号尾巴」和「括号说明」还没剥掉,噪声词不在行尾,$ 匹配不上。

粤迹-岭南家宴深圳(福田 南山罗湖)选址排烟风量45000,通天然气… 这一条, 早放位置时整条截断全部落空。

3. 正则开头绝不能多一个 |

写多分支正则时,如果第一行不小心以 | 开头,会产生一个空分支, search() 命中 span=(0,0)(空串),然后被 m.start() >= 2 这类守卫挡掉, 整个清洗静默失效且不报错。加一句自检:

assert not RE_TAIL_NOISE.pattern.startswith("|")
assert RE_TAIL_NOISE.search("abcxyz") is None

4. 【品牌定位】 不等于 【品牌名称】

标签匹配不能只做包含判断。【品牌定位】 里也有「品牌」两字, 按包含匹配会把整句正文(大型仓储式、会员制品牌名品集合折扣仓)当品牌名, 真品牌 原品仓城市奥莱(在首行)反而丢了。 find_group 用的 _tag_hit() 要求 【…】 内容等于关键词, 或带白名单修饰词(品牌名称✓ / 品牌定位✗)。白名单在 TAG_SUFFIX_QUAL / TAG_PREFIX_QUAL。

扩白名单时注意别漏真标签:品牌对接人、重点拓展区域、需求城市、品牌名字、 拓店区域、商铺面积 这几个曾经因为白名单太窄被误杀。

5. 制表符表格路径会绕过清洗

parse_tab_rows() 曾经裸赋值 out["品牌"] = f,导致 全国连锁TOTA眼镜品牌拓店 这类带噪声的整串直接进表。任何新增的品牌候选出口都必须过 clean_brand。

6. 姓名表要带复姓 —— 而且必须完整

surname 单字表漏了 欧,星巴克名片上的 欧阳琴 就被整条丢掉。 现已在 SURNAMES 基础上补了 C_SURNAMES(欧阳/司马/上官/诸葛… 40 个复姓)。 persony(s) 加 strict=True 做姓氏校验(文本层用), strict=False 只挡 PERSON_BAD(名片 OCR 用)。

尾部人名剥离还有个反直觉约束:整串含空格时一律不剥。 否则 美团 浣熊食堂 会被削成 美团 浣(「熊」是姓氏)。

6.1 ★ 姓氏表缺字 = 联系人被静默清空,这是本项目最严重的一类缺陷

field_fix.py 的 SURNAMES 是从百家姓手抄的,上一次抄漏了 莫 之后 连续 74 个字(经房裘缪…宁仇栾暴 整块)。后果:

  • 崔先生 程总 邓生 段先生 焦先生 单先生 芮总 邓总 石… —— 这些完全正常的联系人在 2,469 行里被批量判成「非人名结构」清空。
  • 不抛异常、不写日志、表里看不出少人。是逐条读改动日志才发现的。
  • 自检当时是 43/43 全绿的 —— 因为 fix_brand / fix_contact 按当前姓氏表 算都是对的。单测照不出「词表本身缺项」。

已经加的那道闸门(不许删):field_fix.py::_check_surnames() + REQUIRED_SURNAMES(268 个哨兵字),在 --selftest 开头跑,缺一个就红。 改 SURNAMES 后自检第一行会直接告诉你缺了什么。

另一个方向也会翻车:姓氏表多收了字同样有害,而且产出的是错值不是空值, 更难发现:

误收的字后果处置
区白云区陈经理 → 区陈经理(区 在粤语区是真姓氏,但本语料里 99% 是行政区划字,白云区/番禺区/天河区 满地都是)不收。宁可少认一个罕见姓
法FADAJE法大吉(杭州真烘焙品牌,已进广州/深圳)被当成「法+大吉」人名切开保留 法,改为要求尾部规则里 head 含空格
第电话: 第三方 里 第三方 被当成「第+三方」人名,反过来把 电话: 留成了品牌保留,用 NON_PERSON + RE_LABEL 拦

判据一句话:当某个字在本语料里高频地以「非姓氏」身份出现时,就不收它。 因为罕见姓漏认的代价是「留空」,而高频误认的代价是「写错」——错值更贵。

6b. 岗位词/铺位词形态上和人名一模一样

招商经理(招+商+经理)、商铺(商+铺)、第三方(第+三方)—— 锚定会成功,形态完美,但它们不是人。数据里 招商经理 真的以联系人身份进过表。 闸门是 field_fix.py::NON_PERSON + RE_NON_PERSON,位置在锚定之后 (必须放后面,它拦的正是「锚定成功」的那批)。

7. build_xlsx.py 里别用 a 当局部变量

main() 里 a = ap.parse_args()。任何内层循环再用 a 做临时变量(比如合并字段时的 a, b = host.get(k), o.get(k))都会把它覆盖掉,最后 wb.save(a.out) 直接 AttributeError: 'str' object has no attribute 'out'。 合并那一段现在用 cur / new。加变量名前先扫一眼 main 作用域。

8. 名片「姓名+职务」连写要正向切分,不能倒切

名片常把姓名和职务写在一行:陈清明市场开发总监。 按「头衔词倒切」是错的——总监 在第 7 位,倒切得到 陈清明市场开(6 字), 会被 2 <= len(pre) <= 4 的长度闸挡掉,姓名静默丢失。

正确做法是正向试切,从 2 字起、要求切开处紧接着是职务词:

JOBW = ("市场","招商","拓展","开发","运营","销售","工程","项目","品牌",
        "渠道","投资","商管","物业","设计","采购","人力","法务",
        "总监","经理","主管","负责人","专员","店长","总经理","副总","董事","总裁")
for ln in lines[:8]:
    for i in range(2, min(5, len(ln))):          # 姓名 2~4 字
        if ln[i:].startswith(JOBW) and persony(ln[:i], strict=True):
            out["人名"] = ln[:i]; break

词表必须含 市场/开发/招商 这类职能词,因为职务的前缀本身就是职务的一部分—— 只放 总监/经理 一样捞不到 陈清明。

9. 海报顶部的品牌名会压过真名——需要「下一行是职务行」这个信号

蒙自源 那张名片:

蒙自源                        ← 品牌(错当成人名)
姜蒙                          ← 真名(被丢)
开发中心
手机:18638795718

蒙自源 靠「出现在前两行」+1 分拿下 4 分,姜蒙 只有 3 分。 但名片版式是「姓名 / 职务 / 手机」三行连排,所以**「紧邻下一行就是职务行」是比『在前两行』更强的信号**:

if i + 1 < len(lines) and RE_JOBLINE.search(lines[i + 1]):
    score += 2          # 姜蒙 → 5 分,反超蒙自源 4 分

改完 7 张有名字的图全部正确:欧阳琴 / 陈清明 / 姜蒙 / 冯毅 / 邵徽建 / 银星 / 程杨。

10. 文件名清洗必须剥掉 / —— 否则 curl 静默写失败

星球正文常用 主体/业态 的写法(深圳TOP商业体/商圈大),如果直接拿它当文件名, / 会被当成路径分隔符,curl 去写一个不存在的子目录,报:

curl: (56) Failure writing output to destination, passed 8192 returned 429496729

症状是「下载了 0 字节」,很容易被误判成网络抖动。旧版 dl_images.py 有 .replace("/","_"),重写 dl_assets.py 时漏过一次,447 张里挂了 1 张。 sanitize() 必须一起换掉 / 和 \:

name = re.sub(r'[/\\:*?"<>|\r\n\t]', "_", name)

11. OCR 串行比并行快 —— 别被直觉骗了

llama-server 只有 1 个推理槽,并发只会互相排队还多付调度开销。实测:

并发速率447 张预计
1 进程~5 秒/张~37 分钟
4 进程~20 秒/张~145 分钟

所以 ocr_batch.py 默认 --workers 1。想验证一定要带上 --no-cache, 否则第二次跑会命中缓存秒返回,测出来的「并行快 30 倍」是假的。

12. OCR 结果认回主题必须按 image_id,不能重建文件名

build_xlsx.py 要把每张图的 OCR 结果并回它所属的主题行,靠的是 「OCR 文件名 → manifest 条目」的映射。早期实现是按规则重建文件名:

stem = f"{man.index(x)+1:02d}_{x['date']}_{hint}_{image_id}"   # ✗ 脆

只要下载器的命名规则变一点(是否带序号前缀、线索取抽取出的品牌名还是帖子标题、 sanitize 保留哪些字符),就全量失配且不报错 —— 447 条 OCR 结果会退化成 孤儿行、品牌重复一遍。正确做法是用唯一且一定在文件名里的 image_id 反查:

def man_of(stem):
    if stem in stem2hint:                 # 旧命名兼容
        return stem2hint[stem]
    m = re.search(r"_(\d{6,})$", stem)    # 按尾部 image_id 反查
    if m and m.group(1) in iid2man:
        return iid2man[m.group(1)]
    return {}

凡是「靠重建字符串来跨模块对齐」的地方,都要换成用真实 ID 反查。

13. 外部插件的路径不能写死版本号

腾讯文档 skill 的目录带版本串:

~/.workbuddy/plugins/cache/workbuddy-builtin/
    tencent-docs-plugin/5.6.2-wb.39298511.g37a65c0b.hbf00e3f3d64d/skills/tencent-docs

tdoc_upload.py 早期把这一整条硬编码在 SKILL 常量里。插件一升级, 目录名就变,脚本抛 FileNotFoundError,表现是上传整批静默失败。 改成 glob 取最新,并校验关键文件真的在:

def _resolve_skill() -> str:
    pat = os.path.expanduser(
        "~/.workbuddy/plugins/cache/workbuddy-builtin/"
        "tencent-docs-plugin/*/skills/tencent-docs")
    for c in reversed(sorted(glob.glob(pat))):     # 版本号字典序最大 = 最新
        if os.path.exists(os.path.join(c, "tencentdocs.py")):
            return c
    raise SystemExit(f"[ERR] 找不到 tencent-docs skill\n      glob: {pat}")

注意 glob 匹配到的是多个历史版本(本机有 3 个:1.0.0 / 5.5.6-* / 5.6.2-*), 所以必须 sorted() 取最后一个,不能随便取第一个。

14. OCR 的图片清单在启动那一刻就定死了,晚落盘的图会被静默漏掉

ocr_batch.py 一上来就 glob 出图片清单:

imgs = sorted(glob.glob(.../*.jpg) + glob.glob(.../*.png))   # ← 只取这一次

之后新落盘的文件它完全不知道。年度全量实测:447 张里有 1 张 (2025-11-19_周黑鸭_...)因为下载重试,比 OCR 启动晚了 6 分钟才落盘, 于是整轮 OCR 漏掉它——而且日志上完全看不出来(报「446 张」,看着自洽)。

对策:主进程退出后再跑一次 ocr_batch.py。它会重新 glob、跳过已有 .md、 只补那几张漏的,代价几十秒。finish_year.py 里已内置这一步(「补漏」)。

推而广之:任何「启动时枚举输入」的批处理,都要在收尾时再校验一次覆盖率, 别信第一次枚举的结果。

15. 下载器把所有图都写成 .jpg,144 张其实是 PNG

do_image() 早期实现是:

name = sanitize(f"{date}_{hint}_{iid}") + ".jpg"   # ✗ 无论真实格式

年度全量 447 张里 144 张内容其实是 PNG,全被扣上 .jpg 扩展名。 PIL / 浏览器多半按内容嗅探所以没炸,但按扩展名判格式的工具(部分上传接口、 图片处理服务)会出错。已改为下载后按 magic 改回真实扩展名,并把 四种扩展名都纳入续跑检查(否则上次存成 .png 的这次会被当成没下过、重下一遍):

IMG_EXTS = (".jpg", ".png", ".webp", ".gif")
for e in IMG_EXTS:                      # 续跑要把四种都查一遍
    p = os.path.join(outdir, stem + e)
    if os.path.exists(p) and os.path.getsize(p) > 5000:
        ...  # skip

⚠️ 改扩展名前先确认下游怎么收文件。ocr_batch.py 同时收 *.jpg 和 *.png 所以安全;但如果下游只 glob *.jpg,改名就等于让那批图从 OCR 里消失。 另外别在 OCR 跑着的时候改名——它手上是启动时抓的那批绝对路径。

16. ★ 字段校正必须跑在 OCR 并表之后

build_xlsx.py 的流程有两段会写「品牌 / 联系人」:

  1. 文本层(rows,来自 zsxq_brands.csv)
  2. OCR 并表(把图片 OCR 结果并回它所属主题行,用 cur + " / " + new 追加)

字段校正(field_fix.fix_row)原先挂在第 1 段后面,于是第 2 段写进去的值 整批绕过校正。实跑证据非常好认——漏出来的三行都带 +图片OCR 标记:

漏出的值实际应是
梁总 / 梁润池梁总(并表拼接物)
成都 / 储备项目总""(地名 + 岗位,都不是人)
全国搜寻100家物业场地!""(整句)

这是本项目第二次栽在同一类错上(第一次是 _pick() 列名不适配):判据在单函数里 是对的,错的是调用时机/调用层。所以:

  • 校正循环现在跑在 allrows = rows + orphan 之后;
  • 并表拼出来的 A / B 有专门处理:只认带职务词的段 (梁总 / 梁润池 取 梁总;两段都没职务词就整条置空)。 理由:没职务的段多半是 OCR 顺带抓到的地名/公司名,而文本层比 OCR 可靠。

推广:只要一条数据流有「后置追加/合并」环节,任何清洗都必须排在它后面, 并且在最终 allrows 上再跑一遍覆盖率抽查,不能只测中间态。

17. 品牌校验要真的联网查,而且「改对了」也可能只是看起来对

年度全量跑完后按 Kelvin 要求逐条上网核,结论分三档:

✅ 确实是真品牌(修正方向正确)

品牌核实到的公开事实
蒙自源云南米线连锁,2001 东莞创立,2000+ 店
大米先生乡村基旗下中式快餐,1200+ 店 → 出现在联系人列是错的
货郎先生百货连锁,1000+ 店 → 同上
余美娟生焗排骨饭中山市余美娟餐饮管理有限公司,品牌取自创始人母亲 → 差点被姓氏启发式误切
FADAJE法大吉杭州烘焙设计师品牌,2023 创立,隶属杭州法龙餐饮,已进广州/深圳,有百度百科词条
北岩女装全国连锁女装,赣县实体店百人级,目标当地 23 店 → 原被括号规则整段删掉(数据丢失)
聚满分中山 2020 创立,西点烘焙直营 35+ 店,中山/珠海/佛山/广州
三立方咖啡CUBIC3,上海思睿立方咖啡,2021 创立,2025-12 设深圳公司
好特卖超级仓好特卖 HotMaxx 旗下仓储业态,2024-11 南京全国首店,2025 北京/通州
鱼你在一起北京鱼你在一起品牌管理,2017 魏彤蓉创立,全球 2700+ 店 —— 与源数据「创立于2017年」完全对上
天天惠天天惠超市(浙江)/ 天天惠生鲜(广东连锁便利店),广东占其门店 55%

鱼你在一起 那条尤其值得记:源数据里自带的「创立于2017年」和品牌公开创立年份一致, 等于拿到了一个免费的交叉校验点。

⚠️ 残留判断项(如实记录,不装作已解决)

项说明
大众服装联网查出 大众服饰 在百度百科是服饰术语/品类,不是品牌;地图上那一堆「大众服装」是各地同名小店。保留原值但在报告里标注
赛百味大力Subway 赛百味为真,但「赛百味大力」查不到独立主体,疑为「赛百味」+人名的粘连残留
山水生山 补进姓氏表后由 水生 变为整串 山水生;两种读法都无从核实,按「左匹配优先」一致性处理
柳姨妈螺蛳粉只查到加盟聚合页,广西柳州螺蛳粉品牌,中等置信度

方法上的两条:① 校验要查具体主体(工商名/门店数/创立年份),不要只看名字像不像; ② 发现「改前改后都说得通」的项要留档,别为了收尾好看而抹平。

18. 附件清单必须在交付目录找本地文件(收尾链里它跑在搬迁之后)

report_year.py::build_attachment_inventory() 生成 _附件清单.csv,其中 本地文件 列要把每个附件对到磁盘上的实际文件名。它原先只扫工作目录 {work}/files —— 但 finalize_year.py 已经把附件搬进交付目录的 附件资料/,而清单生成在收尾链里排在搬迁之后。

结果:本地文件 列 361 行全空,日志只有一句轻描淡写的 「本地未匹配 361」,读起来像"有些没下到",实际上是一个都没认上。

修法:两个目录都扫({outdir}/附件资料 优先,再落回 {work}/files)。 修完 本地未匹配 361 → 0。

顺带加了一条"喊出来":miss == len(rows) 时不再打 [ok], 改打 [!!] ... 匹配逻辑失效 ... —— 全空和部分缺失是两种病, 日志里必须能一眼区分开。

这条和 #16 是同一个病根:校验/清洗跑在了最终状态之前。 收尾链只要涉及「移动资产」,任何"资产在哪"的判断都得排在移动之后。 判断口诀:凡是要读磁盘上资产清单的步骤,先问自己"这时候资产还在原处吗"。

20. ★ OCR 侧的人名兜底比文本层少三条 → 图片里的联系人静默丢失

extract.py::pick_person(文本层)有三层兜底:① 显式标签取值 → ② 标签独占一行、 姓名在下一行 → ③ 姓氏+称谓后缀([\u4e00-\u9fa5]{1,3}(?:总|先生|生|经理|…))。 而 build_xlsx.py::parse_ocr_text(OCR 侧)只有「裸行姓名」+「姓名+职务连写」两条, 三条标签兜底一条都没有。

后果:海报上最常见的写法 联系人:高生 整条落空。2026-10-03 实跑踩到 (如梦唯美 那张图)——主表联系人列空白,而同一份交付物的「图片OCR原文」页里 明明写着「联系人:高生」,两页自相矛盾。不抛异常、日志全绿、并入图片OCR 3 行 看着完全正常。

判别这类问题的唯一有效手段是交叉核对交付物内部两页: 拿 图片OCR原文 页的文本,去主表对应行看有没有落下来。 光看日志和汇总数字发现不了——它只少一个名字。

修法:在 parse_ocr_text 末尾按 if not out["人名"] 串上同样三层兜底—— ① (?:联系人|对接人|联络人|负责人|招商经理|拓展经理)\s*[::]\s*([\u4e00-\u9fa5]{2,4}) ② 行尾是 负责人|联系人|对接人|联络人 → 取下一行 ③ 姓氏+称谓后缀(用整段 txt 而非逐行) 每层都过 persony(strict=True);职务词(招商经理)会被 strict 判否, field_fix.NON_PERSON 再做第二道闸。

行尾追加不改变已有结果(星巴克 欧阳琴 / 欢乐迪 陈清明 仍由前两轮拿下), 只补空值,所以是安全的增量修法。改完实测 5 张图: 欧阳琴 / 陈清明 / 高生 三人全对,另 2 张(基诺浦海报、佛山项目预览图)仍正确地留空。

口诀:同一份交付物里,A 页的信息必须在 B 页出现。 凡是「抽取逻辑在两条路径上各写一套」的地方,都要拿路径产出的原始证据回查一遍—— 两套逻辑漂移是必然的,只差哪次实跑暴露。

21. ★ 首行兜底扫到第 4 行 + 称谓词表缺字 → 垃圾品牌与联系人丢失同帖发生

2026-10-06 唯一一条新帖(急求租商业物业做医院…联系电话:18680557096 胡院长)两个字段同时错:

字段产出应为根因
品牌离地铁站1000空(需求帖无品牌)pick_brand 的首行兜底扫 lines[:4],第 3 行是描述长句,被 clean_brand 的「从句截断」切出片段
联系人空胡院长院长 不在 TITLE_SUFFIX / pick_person 的称谓表里

① 兜底行数:for ln in text.splitlines()[:4] 改成 [:1]。 实测年度语料 1,414 条「首行」品牌全部来自第 1 行(0 条来自第 2~4 行), 所以收紧到第 1 行是零回归的——扫后续行收益为 0,只会引入长句碎片。 (离地铁站1000米左右。附近没有学校… → 离地铁站1000,还附带一条假备注 「疑似人名:米左右」;米 是姓氏,1000米左右 的尾巴被当人名剥掉。)

② 称谓词表要完整:和坑 #6 的姓氏表同构——缺一个字 = 该称谓的人静默丢光。 院长 不属于高频误认词(不像 区/法/第 那样在本语料里高频以非姓氏身份出现), 所以可以直接加。已同步三处(必须一起改,分叉必漂移):

  • extract.py::TITLE_SUFFIX(供 brandy 拒识标题、strip_contact_tail 剥尾)
  • extract.py::pick_person 第 ③ 层 finditer 正则
  • build_xlsx.py::parse_ocr_text 第 ③ 层 finditer 正则(坑 #20 的位置)

回归验证方法(每次改词表都跑):拿年度 _源数据/zsxq_brands.csv 的 正文全文 (2,469 行)跑新旧两版 pick_brand / pick_person 逐行对比,要求 0 条变化, 再验证目标帖已修好。本次实测:品牌变化 0 / 联系人变化 0,医院帖 → 品牌空、联系人 胡院长。

口诀:收紧兜底前先量收益。拿全量语料统计「命中来自第几行」, 如果 100% 来自第 1 行,那把范围收到第 1 行就是免费的鲁棒性升级。

22. ★ 资源汇总帖(一帖 N 品牌)→ 电话全塞一格、品牌只剩一个、号码与人错位【告警已实装,真拆行未做】

症状(Kelvin 2026-10-08 肉眼发现):主表某行「联系方式/微信」有 101 个电话。

根因不是正则错,是缺「帖子类型识别」这一层。 extract.py 通篇假设一帖 = 一品牌:

  • all_contacts(text) 把整帖所有号码无条件并进 联系电话(:659 → :712 " / ".join(phones)),而 pick_brand / pick_person 只取第一个;
  • 「多品牌并列」拆行(:379-386 定义、:728-741 落行)的判据是 首行被 //、 切开且每段都像品牌。而汇总帖首行是 生活服务资源 / 超市资源 / 珠海资源 这种标题,永远不触发。

实锤:主题 45548584442884128(2026-09-28)原始正文 4,655 字 / 118 个手机号 / 几十个品牌, 产出 = 品牌空、联系人 蔡先生(第一个出现的人名)、联系电话 101 个。

影响面(年度 2,469 行实测):唯一号码 ≥4 的行 20 行,涉及 284 个号码:

行品牌列(只留了清单第一个)号码数真实内容
19空101生活服务资源(几十个品牌)
—屈臣氏9屈臣氏/KKV/名创/蕉下/荣耀/小米… 华南拓展负责人清单
—乐有家9超市资源:零小吉/赵一鸣/良品铺子/好想来/华联…
—老碗会6老碗会/7-11/陈香贵/大米先生/耳道/同仁四季…
—中影6珠海资源 8 个品牌
—米线类别8蒙自源/味千/大鼓/五谷渔粉… 品类清单
—一年四季…16健身资源 14 个健身品牌

三条损失:① 后续品牌整体丢失(估算 ≈264 个品牌未出表); ② 号码-人-品牌对应关系全丢(打 13880305213 本该找「大米先生 欧总」,表上挂在「老碗会 田总」名下) ——这条最贵,会直接打错人;③ 号码本身没编造(118 → 去重 101),是「多收 + 错挂」。

轻度同根因:东方麒麟(3 号)三人各一号(袁泽坤 / 13916105251 / 刘鹏山)被并成一格、 联系人列反而空白。≥3 号就该怀疑,不必等到 100。

修复方案(两步,先低风险)

  1. 探测器 + 告警(零回归,可立即上) —— ✅ 2026-10-13 已实装(extract.py flags 段)。 唯一号码 ≥4 且(正文号码密度 ≥1.8 个/百字 或 称谓数 ≥4)→ 数据质量提示 写 ⚠️疑似资源汇总帖(N 号码),联系方式未按品牌拆分,勿直接引用。 实测分离度:≥4 号行密度 min 1.79 / 中位 3.33;2~3 号行中位 1.50 → 阈值 1.8 有区分度但非绝对, 所以只告警不删数据。首次命中:2026-10-13 的 广州地区新能源(7 号码,6 个汽车品牌)。
  2. 按三元组真拆行(高收益,需回归验证):识别「品牌 / 人名 / 号码」重复模式, 每三元组出一行,做到品牌/联系人/电话一一对应;拆不出三元组的退回第 1 步告警。 验证动作:年度 _源数据/zsxq_brands.csv 新旧对比,要求仅这 20 行变化、其余 2,449 行 0 变化。

旁证缺陷(同批修):正文全文[:2000](:720)把该 4,655 字帖的审计底稿砍到 2,000 字, 57% 原文在 _源数据 里消失。年度表仅此 1 行触顶,但恰好是最大那帖 —— 既然 SKILL.md 承诺「完整 26 字段不丢」,截断上限就该提到 ≥8,000 或不截。

口诀:抽样看的是「字段对不对」,看行内数量级才能发现「类型没认出来」。 一格里塞了 101 个电话,任何逐字段校验都不会报错——它每个号码都合法。

23. ★ 三层人名兜底全都要求职务/称谓词 → 无职务的纯本名整批丢失

症状(2026-10-09 每日增量肉眼发现):当天新增 9 帖里有 3 帖主表联系人空白, 而正文里姓名写得清清楚楚:

帖正文原句产出应为
引调傅俊新-13729503797空傅俊新
蒲妈妈-张力兵18908686933空张力兵
求租茶楼13662521220小龙空小龙(昵称,可不收)

根因:extract.py::pick_person 的三层兜底分别是 ① 显式标签 → ② 标签独占一行 / 姓名在下一行 → ③ 姓氏+称谓后缀 ([\u4e00-\u9fa5]{1,3}(?:总|先生|…|院长))。 每一层都隐含要求「姓名旁边有职务或称谓词」。星球上极常见的 姓名<分隔>手机号(纯本名、无职务)就一层都命中不了 → 静默留空。

影响面(年度 2,469 行实测):补上第 ④ 层后多出 112 行联系人(原本全空), 已有联系人行 0 改写 —— 纯增量。

修法:新增第 ④ 层 pick_person_near_phone(text, brand), pick_person 末尾调用;build_xlsx.py::parse_ocr_text 同步挂上(坑 #20 同源,两处必须一起改)。 判据是「一行内只有一个手机号,且紧贴号码的那段连续汉字是个人名」。

三条精度约束(缺一条就出误报,都做过实测对比):

约束不管它会发生什么
① 邻接分隔符只允许空白/横线/冒号(不含逗号句号括号)杨艺洋18848524372,全国 会取到 全国(全 在姓氏表里)
② 一行内只允许一个手机号,多号帖直接跳过资源汇总帖(坑 #22)号码与人本就不对应,猜错比留空贵
③ 候选长度 2~3 字,且排除单字复姓(欧阳)放到 4 字会把 左右价格、全国大熊 收进来(左/全 都是姓氏)

另加 persony(strict=True) + 不等于品牌 + is_generic_brand 三道闸。

验证协议(改完必跑,与坑 #21 同款): 拿年度 _源数据/zsxq_brands.csv 的 正文全文(2,469 行)跑新旧两版 pick_person 逐行 diff, 要求「已有值的行 0 变化」,再把新增的行逐条打印命中行原文人工过一遍。 本次实测:0 改写 / 112 新增全对(抽样 39 条打印完整命中行核对,无误报)。

口诀:兜底链的每一层如果都隐含同一个前置条件,这个条件就成了整条链的盲区。 三层兜底看起来「很稳」,其实它们共用「必须有职务词」这一个假设 —— 而星球的真实写法里,傅俊新-13729503797 这种不带职务的占了一大片。

26. ★ 半角/混排括号标签 → 品牌整批静默留空(【…】 之外还有 [品牌名称】 / [拓展品牌])

症状(2026-10-11 每日增量肉眼发现):帖子 [拓展品牌】:凡可思 / [业态类别]:西餐/意式简餐 / … 品牌列为空,而正文第一段就写着品牌名。

根因:RE_BRACKET = 【([^】\n]{0,26})】 只认全角成对括号。星球上大量帖子用 半角/混排写法([拓展品牌】: [品牌]: 【企业品牌] [品牌名称]),这类标签整条失效, find_group 一路落到首行兜底,兜底捞不到就留空 —— 不抛异常、日志全绿。

修法(extract.py 三处,缺一处就出事)

  1. 新增 RE_BRACKET_ANY = re.compile(r"[【\[]\s*([^】\]\n]{0,26})\s*[】\]]"),find_group 改用它。
  2. ⚠️ 只有全角 【…】 才享受白名单修饰词,半角/混排一律要求内容完全等于标签词:

    _full = bm.group(0)[0] == "【" and bm.group(0)[-1] == "】"
    if not (_tag_hit(_bc, k) if _full else _bc == k):
        continue

    不管这条会回归:【品牌简介](混排)经「品牌 + 简介」白名单命中, 把品牌简介整段当品牌名 —— 年度实测 2 行 A S時尚女裝大牌 被污染成 A S品牌。

  3. 值里出现 /(全角斜杠)且下一段以 :/:/【/[ 开头 → 判为下一字段,截掉:

    v = re.sub(r"\s*/\s*(?:[::]|[【\[]).*$", "", v).strip()

    必须带「下一段是标签开头」这个条件:无条件按 / 截会把 【品牌】星海拾贝/精灵气泡 / V16673103667华中… 的真值截成 星海拾贝(实测踩到,2 行)。

配套词表补齐:RE_NON_NAME_TAIL_WORD 加 健身 —— 砺猿24小时健身 的尾三字 时健身 被当人名(时 是姓氏)剥掉,品牌变成 砺猿24小。

验证协议(与 #21/#23 同款,改完必跑):年度 _源数据/zsxq_brands.csv 的 正文全文 (2,469 行)跑新旧两版 pick_brand / pick_person 逐行 diff。 本次实测:品牌 10 行变化且全为改善,联系人 0 行变化,空品牌 460 → 458。 判「改善」的口径:值从空/垃圾变成真品牌算改善;值变长但仍带噪声算残留,如实记录不改。

口诀:「标签没认出来」和「标签认错」是同一枚硬币的两面。 放宽括号识别必然引入「假标签」风险(【品牌简介]), 所以放宽的同时必须给新形式配更严的判据(精确相等),而不是沿用旧的白名单宽松度。

27. ★ 反爬「乱序插字」→ 品牌/区域直接变成乱码,而且不带任何告警

症状(2026-10-13 每日增量肉眼发现):主表品牌列写着 火串锅串、区域列写着 限圳深市, 读起来像乱码,但既不抛异常、也没有 ⚠️ 提示,字段还都「有值」——最容易被当成正常数据引用。

根因:星球对部分帖子做了字符乱序反爬。原始 content 是:

【火\x14串锅\u202c串拓店选址】
【区域】限\x14圳深\u202c市
【电话】18938659773微\x14同信\u202c号
备注:请\x14笔以\u202c记方\x14呈式\u202c现

规则(30 帖 / 27 个标记实测确认):

  • \x14 是触发标记,其后紧邻两字被对调;
  • \u202c(POP DIRECTIONAL FORMATTING) 等是闭合标记,直接丢弃。

还原后逐段完全可读:火\x14串锅\u202c串 → 火锅串串;限\x14圳深\u202c市 → 限深圳市; 微\x14同信\u202c号 → 微信同号;推\x14铺荐\u202c子 → 推荐铺子;我司收\x14资到\u202c料 → 收到资料。

修法:extract.py 新增 deswap_antispam(s) -> (文本, 是否还原过),在所有字段抽取之前、 对 t["content"] 应用一次(raw, _deswapped = deswap_antispam(...))。 晚做等于漏一半——品牌/区域/备注全从这个 raw 派生。还原过就打一条 ⚠️ 原文含反爬乱序字符,已自动还原 留痕(此前这类行一条提示都没有)。

⚠️ 两个标记必须分开处理:只对 \x14 做「换回两字」,对 \u202c 只丢弃。 若对两者都做交换,会把刚还原的字再换回去(实测 火锅串串 会变成 火锅串拓串店)。

回归验证:年度语料 2,469 行 —— 品牌 0 变化、联系人 0 变化、电话 0 变化 (年度里只有 4 行含 \x14,且标记不在品牌段内)。

同批附带修复:纯数字微信号丢失(联系人:【张经理】 微信:【1091473103】)

  • RE_WX 要求首字符是字母 → 纯数字微信号整条落空、微信列空白。
  • 新增 RE_WX_DIGIT,限 5~10 位、故意排除 11 位(11 位是手机号,走「微信同号」那条线)。
  • ⚠️ 必须排除反爬插字号码的碎片:电话,微信同号:18160请勿外传885807 会截出假微信号 18160(年度实测 2 行误报)。判据:候选数字与 RE_ANTISPAM 的匹配区间有交叠即弃。
  • 回归:年度语料微信 +8 行,逐条核对全为真值(83406255 / 285229446 / 1091473103 / 757673746), 品牌/联系人/电话 0 变化。

口诀:「字段里有值」不等于「值是对的」。 前 26 个坑都是「少东西」, 这个坑是「给了个看着像品牌的乱码」——逐字段非空校验 100% 通过,只有肉眼看品牌列才发现。

图片 OCR 要点

用 local-ocr skill 的 PaddleOCR-VL-1.6,llama.cpp :8080,离线、不消耗积分。

  • 先探活:curl -s http://127.0.0.1:8080/health → {"status":"ok"}。不通就跳过,别死等。
  • 模型视觉 token 上限 ≈1.0 MP,超出的像素纯浪费。--precise 会自动按 1.0 MP 分块, 相当于把有效分辨率翻倍——这是提准的唯一有效手段。
  • 实测 33 张海报/名片 ≈224 秒(6.8 秒/张)。
  • 星球的图床是 images.zsxq.com,带签名参数,可以直接 curl 下载,不需要登录态。 下载后必须校验 magic(\xff\xd8\xff / \x89PNG),防拿到 HTML 错误页。
  • 海报/实拍图没有文字是正常情况,不要当失败——落一行并标注「图片无可识别文字」。

OCR 的真实成本模型(2026-09-30 年度全量实测,别再靠猜)

耗时 ≈ 块数 × 5 秒(视觉编码)+ 输出 token ÷ 115(文本生成)

年度全量 447 张图 = 900 个块,实测:

环节实测值
视觉编码(服务端 image processed in)中位 5.0 秒/块(289 ms ~ 11.2 s)
单块输出 token中位 209,均值 901,18% 的块 >3000 token
生成速度115 token/s
合计算900×5 + 81万÷115 ≈ 192 分钟(与实测吻合)

由此得出三条结论,能省掉一整轮瞎试:

  1. 服务端已经在 GPU 上,ocr.py 启动参数是 -ngl 99,日志里 MTL0: Apple M4 + EMBED_LIBRARY = 1。没有"改成 Metal 就快 10 倍"这种免费午餐。
  2. 压缩分辨率不划算。 块数 ∝ 总像素,降到 1/3 只能省下编码那 1/3 (约 50 分钟),但生成的 token 数几乎不变(内容一样多), 而长截图(1080×25765 这类,长宽比 ≥4)会被压到认不出字。风险大于收益,不做。
  3. 块数直接由原图的像素决定。 auto_tile_count = round(宽×高 / 1.0MP), 而 preprocess() 只放大不缩小,所以 4032×3024 的手机原图 = 12 块。 想估时间先量像素分布,别用"张数 × 常数"拍脑袋。

并发:串行就是最优,别再试

llama-server 日志里写着 n_parallel = 4,看着像能并发,但实测是负优化: 1 进程 ≈ 5 秒/张,4 进程 ≈ 20 秒/张。原因是视觉编码独占 GPU, 并发请求互相排队还要多付调度开销。ocr_batch.py 默认 --workers 1。

⚠️ 测速度必须加 --no-cache。缓存键是 md5(文件哈希 + 模式 + dpi + 标志),第二次跑同一批图会直接命中缓存秒回, 于是"测量出"一个假的 30 倍加速。年度全量续跑靠缓存,但测速别用它。

单张失败绝不能拖垮整批(subprocess.run 的坑)

one() 里那句 subprocess.run(cmd, timeout=900) 必须包在 try 里。 subprocess.run 超时抛的是 TimeoutExpired,不接住的话异常会从线程池的 future 里冒出来,主循环 fu.result() 直接抛,整批 OCR 当场崩, 后面还没跑的图全部作废(已写盘的 .md 还在,但要人手动续跑)。

年度全量是能踩到的:28 块的长截图,28 块 × 最长约 40 秒/块 > 900 秒。 已改为单张超时只记失败、继续跑,并加了 --timeout 让超大图能单独放宽。

验证方式(别靠读代码判断):把 OCR 指到一个 time.sleep(60) 的假脚本, 用 timeout=2 调 one(),应当返回 ('fail', ..., '超时 >2s…') 而不抛异常。

★ 顺带一条通用规律:编辑正在跑的脚本,不影响当前进程,但会影响它之后再拉起的子进程。 这次修的 ocr_batch.py 之所以有效,是因为收尾链的"补漏"那步会在稍后重新拉起它。 反过来,想改「已经在跑的」那份行为,只能重启进程。

19. ★ ocr_out/ 跨次运行不清空 → 旧 OCR 结果变成整批孤儿行混进主表

collect.py --fresh 只清 raw/,images/ 和 ocr_out/ 一路留着。 而 build_xlsx.py 早先是裸 glob(ocr_dir/*.md),把目录里所有历史 OCR 结果 都读进来。凡是 image_id 不在本次 manifest 里的,by_tid.get() 返回 None → 走 orphan 分支 → 作为独立行进主表。

每日增量实跑(2026-10-01)踩到:文本层 30 行,结果主表出 60 行, 虚增的 30 行全是 9-24 及更早的旧图(盒马/蒙自源/凡可思/麦颂KTV…), 特征是「无发布日期、无信息源」,去重品牌数被虚抬(26 而非真实的 21)。 不抛异常、不提示,日志写着「文本层 30 行,6 行并入图片OCR」看着完全自洽。

已经加的那道闸门(不许删):

if has_man and not meta:      # meta = man_of(stem),按 image_id 反查 manifest
    n_stale += 1
    continue

配一行「喊出来」:[!!] 跳过 N 张不属于本次抓取范围的旧 OCR 结果。 has_man 用「manifest 文件是否存在」判断,这样手工调试(不传 manifest)时 仍保留全部 OCR 结果,不误伤。

顺带修掉一个同源的小毛病:同一张图在 images/ 下可能有两个文件名 (旧命名 01_..._<iid>.jpg vs 本次新下 03_..._<iid>.jpg), OCR 证据层会一张图出两行。按 image_id 去重即可(with _iid in seen_iid)。

与 #16/#18 同一个病根:读的东西被上一次运行污染了。 判断口诀:凡是从「跨次运行不清空的目录」里枚举输入,都必须用本次 manifest (或本次 ID 集合)过滤一遍。 每日增量尤其容易中招——全量跑一次就换目录, 反而掩盖了这个问题。

数据质量声明(对外交付要抄上)

  1. 电话已归一化:186 8886 3879 → 连续 11 位(修掉 27 个原本静默丢失的号码)
  2. 国际区号已剥离:86 13714412252 → 13714412252
  3. 反爬插字不采信:18819请勿外传75319 只在「数据质量提示」列标注,不猜测还原
  4. 联系人做姓氏校验,剔除 公共卫生/能做生/云南野生 这类误抓
  5. 多品牌并列帖(新万悦超市/悦满家超市)拆成多行,备注标注同帖来源
  6. 「抓取方式=首行」是正文首行推断,不是显式标签,可信度据此判断
  7. 未做外呼核验,招商前请自行确认
  8. 联系人与职务已分列:联系人只放姓氏校验通过的姓名,职务统一进「其他信息」

历史表现(2026-09-30 首跑)

262 主题 / 270 条记录(一个帖子一行) / 219 个去重品牌 / 229 条可直联 · 其中 11 行并入了图片 OCR 挖到的联系方式 · 图片 OCR 33 张全成功(挖出 11 条只存在于图片里的电话、7 个人名)· 可疑品牌 0、联系人列噪声 0、联系人列职务冒充 0。

腾讯文档备份(2026-09-30 修正版):

  • 主表 xlsx LcSwCCbDcUES / 同结构 csv LMXIGIOLAPKt / 报告 md LDLRxpVkyBGZ / 源数据底稿(26 字段)LmMzGbXAoYdy
  • 被取代的旧版(旧 xlsx LhhbcDJzWDDX、旧报告 LbSuCiolzgDU / LCqQNOuDkvpK) 已移入回收站,可恢复

历史表现(2026-10-01 首次每日增量)

覆盖 2026-09-28 ~ 09-30(--days 1 取第 1 页,跨到 28 号) 30 主题 / 30 条记录 / 23 有品牌 / 11 有联系人 / 27 可直联 / 去重品牌 21 / 11 位手机号 123 个(含一帖多号)/ 文本层 20 有电话 8 有微信 · 图片 5 张全部下载并 OCR(3 张并入主题行,挖出 2 个只存在于图片里的手机号)· 双非空「品牌==联系人」0 行。

首次跑即触发坑 #19(主表虚增 30 行旧图孤儿行),已修复并重出表。 run_all.py 的 --workers-ocr 默认值由 4 改回 1(原默认与 #11 矛盾)。

历史表现(2026-10-03 每日增量)

结论:今日无新增。 覆盖 2026-09-28 ~ 09-30,与 10-01 那次同一批 30 个主题—— 经直查星球确认最新一帖为 2026-09-30 17:49(国庆假期静默),不是抓取故障。

30 条记录 / 有品牌 23 / 有联系人 12 / 27 可直联(手机号可直拨 24)/ 去重品牌 21 / 图片 5 张全部下载并 OCR(3 张并入主题行,挖出 3 个图片内手机号)· 双非空「品牌==联系人」0 行 · 联系人列含电话/长句 0 行。

  • 本地:知识星球招商品牌_每日/知识星球招商品牌拓展总表_20261003.xlsx(+同结构 csv)
  • 腾讯文档(现行版)主表 LewcfJwlAZOl → https://docs.qq.com/sheet/DTGV3Y2ZKd2xBWk9s?_fid=LewcfJwlAZOl
  • 同次首传版 LwsGnruanWDT(缺 高生 那一版)已移入回收站,可恢复

首传即暴露坑 #20:如梦唯美 的联系人 高生 只存在于图片里, OCR 侧缺标签兜底 → 主表空白、证据层却写着 联系人:高生。补三层兜底后重出表重传。

本次为规避坑 #19,故意用当日全新工作目录 ZSXQ_WORK=/tmp/zsxq_daily_20261003 (不复用 /tmp/zsxq),从根上杜绝旧 images/ocr_out 混入。代价只是几张图重跑 OCR。 每日增量建议沿用这个做法。

历史表现(2026-10-05 / 2026-10-06 每日增量)

两轮结论相同:今日无新增。 均覆盖 2026-09-28 ~ 09-30,与 10-01 / 10-03 同一批 30 主题。

  • 10-05:30 条 / 有品牌 23 / 有联系人 12 / 可直联 27 / 去重品牌 21 / 图片 5 张全 OCR
  • 10-06:完全一致。硬证据 = 今日 CSV 与 10-05 CSV 逐字节一致 (7915 bytes / md5 d27b4ad28dd0f0202be57c13c4d6da0e)
  • 直查星球确认最新一帖恒为 2026-09-30 17:49 → 国庆假期静默,非抓取故障
  • 10-05 与 10-06 均执行坑 #20 交叉核对:欧阳琴 / 陈清明 / 高生 三人全落主表联系人列 ✅
  • 云端:10-05 LbLphmJbdijS / 10-06 LvkqyUOfvdMO

「逐字节一致」是判定零新增最快的硬证据(比逐页比对省事,且比看汇总数字可靠): sorted 无关,直接 diff -q 上期.csv 本期.csv + md5 对比即可。

⚠️ 待观察(别把长期静默一律当正常):截至 10-06 已连续 4 天零新增。 假期结束(2026-10-09 起)应恢复更新;若届时仍无新帖,必须按「抓取故障」排查 (检查 zsxq-cli 凭证/权限、--days 1 的 cutoff 计算、group_id 是否变更), 不能再简单归因为静默。长期静默与抓取失效在汇总数字上长得一模一样。

历史表现(2026-10-07 每日增量)

结论:恢复更新(静默 4 天后首条新帖)。 覆盖 2026-09-28 ~ 10-06, 新增 1 帖(急求租商业物业做医院…胡院长 18680557096,物业求租类), 金属狗 因第 1 页滚动被挤出,故总行数仍 30。

30 条 / 有品牌 21 / 有联系人 13 / 可直联 27 / 去重品牌 19 / 双非空「品牌==联系人」0 行 · 图片 5 张全部下载 + OCR(621 字符 / 0 失败,3 张并入主题行)。

本轮首次暴露并修复坑 #21(首行兜底扫到第 4 行 → 垃圾品牌;称谓表缺 院长 → 联系人丢失), 两处同帖发生。修复后回归验证:年度语料 2,469 行品牌/联系人 0 变化。 坑 #20 交叉核对通过:欧阳琴 / 陈清明 / 高生 三人全落主表联系人列。

数字口径说明:品牌/去重品牌/联系人比 10-05/10-06 少/多,都是帖子本身进出造成的, 不是抽取退化 —— 10-06 的 离地铁站1000 是垃圾值、金属狗 已出页; 13 = 12 + 胡院长。

历史表现(2026-10-08 每日增量)

结论:今日无新增。 覆盖 2026-09-28 ~ 2026-10-06,最新一帖恒为 2026-10-06T17:33:40(10-07 报的医院求租帖)→ 10-07 / 10-08 均无新帖。

  • 硬证据:今日 CSV 与 10-07 CSV 逐字节一致(7859 bytes / md5 39a5ffd8…)
  • 30 条 / 有品牌 21 / 有联系人 13 / 有联系方式 27 / 去重品牌 19 / 「品牌==联系人」0 行 / 联系人列含数字或长句 0 行
  • 图片 5 张全部下载 + OCR(621 字符 / 0 失败,3 张并入主题行)
  • 本地 知识星球招商品牌_每日/知识星球招商品牌拓展总表_20261008.xlsx(+同结构 csv)
  • 腾讯文档主表 LPwpuTftycVs → https://docs.qq.com/sheet/DTFB3cHVUZnR5Y1Zz?_fid=LPwpuTftycVs

收尾核对均通过(第 4 次连续):坑 #20 交叉核对 欧阳琴 / 陈清明 / 高生 全落联系人列; 坑 #21 回归观察无复现(离地铁站1000 未再现、胡院长 稳落)→ 10-07 两处修复稳定。

节后节奏提示:恢复更新 ≠ 每天都更新。10-07 出 1 帖、10-08 又零新增属正常波动。 判「真零新增」的充分条件是「同页最新时间戳与上期相同」+「CSV 逐字节一致」, 二者同时成立就不必再去查抓取故障。

历史表现(2026-10-09 每日增量)

结论:节后第 2 次更新,当日新增 9 帖(2026-10-08)。 覆盖 2026-09-28 ~ 2026-10-08, 第 1 页滚动:9 条新增 / 9 条出页 → 总行数仍 30。

  • 30 条 / 有品牌 23 / 有联系人 16(上期 13)/ 可直联 28 / 去重品牌 21 / 「品牌==联系人」0 行 / 联系人列含数字或长句 0 行
  • 图片 5 张全部下载 + OCR(402 字符 / 0 失败,1 行并入主题行,图片内手机号 1 个 13714412252)
  • 本地 知识星球招商品牌_每日/知识星球招商品牌拓展总表_20261009.xlsx(+同结构 csv)
  • 腾讯文档:本轮备份失败(见下)

本轮首次暴露并修复坑 #23(三层人名兜底全要求职务词 → 无职务的纯本名整批丢失), 傅俊新(引调)/ 张力兵(蒲妈妈)两帖当日即修好。 回归验证:年度语料 2,469 行「已有联系人 0 改写」,新增 112 行逐条核对无误报。

⚠️ 本轮唯一异常:腾讯文档备份失败,非脚本问题。 ERROR:pre_import_failed - manage.pre_import 调用失败: no_token, TDOC_DEBUG=1 打出根因:provider personal=not_connected enterprise=connector_disabled ——腾讯文档连接器当前未授权/已断开(list_installed_plugins 返回「No connectors installed」)。 这不是 502(网关域名那种),重试无效,必须由用户在 WorkBuddy 里重新授权腾讯文档连接器。 当天数据已完整落本地目录。

历史表现(2026-10-10 每日增量)

结论:节后第 3 次更新,13 条新帖(2026-10-09)。 覆盖 2026-09-30 ~ 2026-10-09, 第 1 页滚动:13 条新增 / 13 条出页 → 总行数仍 30。

  • 30 条 / 有品牌 25 / 有联系人 18 / 有联系方式 29(含手机号 27)/ 去重品牌 25 / 「品牌==联系人」0 行 / 联系人列含数字或长句 0 行
  • 图片 4 张全部下载 + OCR(248 字符 / 0 失败 / 0 行并入主题行 —— 4 张图均属已出页旧帖, 不是漏并;判据是 manifest 里那些 image_id 的主题已不在本次 30 条窗口内)
  • 本地 知识星球招商品牌_每日/知识星球招商品牌拓展总表_20261010.xlsx(+同结构 csv)
  • 腾讯文档主表 LRsFbBBhdTJT → https://docs.qq.com/sheet/DTFJzRmJCQmhkVEpU?_fid=LRsFbBBhdTJT

腾讯文档连接器已恢复:10-09 的 pre_import_failed: no_token 消失,上传一次通过; 顺手补传 10-09 漏传的那版 → LqzGfCLBzDfm → https://docs.qq.com/sheet/DTHF6R2ZDTEJ6RGZt?_fid=LqzGfCLBzDfm

收尾核对的适用性判断(补一条口径):坑 #20 交叉核对要求 「OCR 原文里的人名必须落进主表」。若本期 OCR 原文根本不含人名 (本期 4 张图 = 名创优品×2 / 佛山项目预览图 / 基诺浦),该项无适用对象, 应记为「不适用」而不是「未通过」。

残留(不改,属设计取舍):单行连写帖 鹤祥宫珠三角区域800平左右李昌平 13823595436 → 品牌、联系人均空。坑 #23 第 ④ 层要求手机号紧邻分隔符只能是空白/横线/冒号, 此处 李昌平 前紧贴「左右」→ 留空优于取到 左右李昌平。留空是正确行为。

历史表现(2026-10-11 每日增量)

结论:节后第 4 次更新,17 条新帖(2026-10-10)。 覆盖 2026-10-09 ~ 2026-10-10, 第 1 页滚动:17 条新增 / 17 条出页 → 总行数仍 30。

  • 30 条 / 有品牌 23 / 有联系人 13 / 有联系方式 26(去重手机号 26)/ 去重品牌 23 / 「品牌==联系人」0 行 / 联系人列含数字或长句 0 行
  • 发布日期分布:10-09:13 / 10-10:17
  • 硬证据:CSV md5 368a25ea… → db2bb69e…(≠ 上期)
  • 图片 1 张(10-10 唯一带图帖),OCR 仅 1979(21 字符)、不含人名/电话 → 0 行并表属正确(无可并内容),与 10-10 那次「图片属已出页旧帖」是两种不同的「0」
  • 本地 知识星球招商品牌_每日/知识星球招商品牌拓展总表_20261011.xlsx(+同结构 csv)
  • 腾讯文档主表 LmBtDIWEnzFy → https://docs.qq.com/sheet/DTG1CdERJV0VuekZ5?_fid=LmBtDIWEnzFy (首传版 LAzSqrkkmdad 已移入回收站,可恢复)

本轮首次暴露并修复坑 #26(半角/混排括号标签 → 品牌静默留空), 凡可思 当日即修好(去重品牌 22 → 23)。 回归验证:年度语料 2,469 行「品牌 10 行变化且全为改善 / 联系人 0 行变化」。

坑 #20 交叉核对口径补充:本期 OCR 原文仅 1979、不含任何人名 → 该项不适用 (与「未通过」区分开,见 10-10 那条口径)。

数字口径:本期联系人 13 少于上期 18,是帖子进出造成的(上期多帖联系人已随页滚出), 非抽取退化 —— 单次比对汇总数字前先确认窗口是否同一批帖。

历史表现(2026-10-13 每日增量)

结论:恢复更新,20 条新帖(2026-10-12)。 覆盖 2026-10-10 ~ 2026-10-12; 第 1 页滚动:20 条新增 / 19 条出页 → 总行数 30 → 31(多出 1,属帖子进出正常)。

  • 31 行 / 有品牌 22 / 有联系人 9 / 有联系方式 26 / 去重品牌 22 / 「品牌==联系人」0 行 / 联系人列含数字或长句 0 行
  • 发布日期分布:10-10:11 / 10-12:20
  • 硬证据:CSV md5 db2bb69e… → 15372989fce971a5bed4e87eb23a0d6e(≠ 上期)
  • 图片 2 张全部下载 + OCR(175 字符 / 0 失败),2 行并入主题行
  • 本地 知识星球招商品牌_每日/知识星球招商品牌拓展总表_20261013.xlsx(+同结构 csv)
  • 腾讯文档主表 LFJeFlpklqTJ → https://docs.qq.com/sheet/DTEZKZUZscGtscVRK?_fid=LFJeFlpklqTJ (首传版 LEXWjWQVbDOA 已移入回收站,可恢复;search_file 复核当日仅一份)

本轮首次暴露并修复坑 #27(反爬乱序插字 → 品牌/区域乱码且无告警), 火串锅串 → 火锅串串、限圳深市 → 限深圳市,当日即修好。 同批实装坑 #22 的探测器+告警(此前只有方案、没代码),首次命中 广州地区新能源(7 号码); 顺带补上纯数字微信号(张经理 微信:1091473103,此前空白)。

坑 #20 交叉核对通过:本期 OCR 两张名片的人名 姜蒙(蒙自源)/ 程庆怡(尚品宅配) 全部落进主表联系人列。

残留(如实记录,非回归):山东火唛苹果经销商,广东区域 田晓晅,17667请勿外传809520 —— 联系人留空。坑 #23 第 ④ 层要求姓名紧贴手机号(分隔符仅空白/横线/冒号), 此处是「姓名**,手机号」且号码本身被反爬插字,按设计宁可留空不猜**。

观察:节后节奏稳定为「隔日更新」——10-11 / 10-12 连续零新增,10-13 恢复 20 帖。 不要把「隔日」误判为静默:判零新增仍须「同页最新时间戳不变 + CSV 逐字节一致」两条同时成立。

历史表现(2026-09-30 年度全量)

窗口 2025-09-30 ~ 2026-09-30 · 82 页 / 2,379 个去重主题(talk 2,377 + q&a 2)

  • 文本层:2,481 条记录(多品牌拆行加出来的)/ 有品牌 2,167(87%)/ 有电话 1,600(64%)/ 有联系人 868(35%)/ 有微信 487
  • 图片层:346 帖带图 / 447 张全部下载,OCR 完成 445 张(有效 417), 2 张两次调用均 llama-server HTTP 500
  • 附件层:103 帖带附件 / 361 个文件 / 3.27 GB(.pdf 208 / .pptx 83 / .xlsx 21)
  • 月高峰 2026-07(260 条),低谷 2026-02(83 条,春节)

★ 最终主表基线(后续做对比都用这一组)

指标值
交付主表行数2,469
去重品牌1,740
有联系方式/微信1,899 行(手机号可直拨 1,712)
有联系人878 行
品牌列 == 联系人列0 行
联系人列含电话/长句0 行
字段校正记录128 条
_附件清单.csv 本地匹配361 / 361

去重品牌数按「品牌名变体不归一」的口径统计,视为偏保守/偏高(见 #17 与报告「已知限制 6」)。

⚠️ 3.27 GB 附件不进腾讯文档(放不下也没必要),只落本地交付目录; 云端只放表格 + 报告。

Shell 环境坑(macOS + zsh)

  • timeout 命令不存在(那是 GNU coreutils),报 command not found。 要限时用 gtimeout(需 brew install coreutils)或干脆不设。
  • mapfile / readarray 是 bash 专有,zsh 里报 command not found, 而且循环体直接不执行——表现为「命令 0 秒跑完、无产物」, 极易误判成脚本有 bug。改用:
    ls *.jpg | head -6 > /tmp/_list.txt
    while IFS= read -r f; do ...; done < /tmp/_list.txt
  • 沙箱里 ps 不可用(operation not permitted),查进程用 pgrep / lsof。
  • 语法校验若 py_compile 被拦,改用 importlib.util.spec_from_file_location 动态加载来验证。
  • macOS 没有 setsid(那是 util-linux 的东西),报 nohup: setsid: No such file or directory,而且整条命令直接不执行。 要让长跑任务脱离终端,用:
    nohup $PY xxx.py args > /tmp/xxx.log 2>&1 < /dev/null & disown
  • pgrep -f 模式 会匹配到你自己的命令行。 比如 pgrep -fl "ocr_batch" 会把 当前这条 shell 也算进去,输出一大堆。要么用更精确的模式,要么在结果里排掉自己。 wait_proc() 里用的模式是 "ocr_batch.py" 这种带扩展名的,就是为了减少误匹配。

长跑脚本的纪律

年度全量要无人值守跑几小时,有三条硬规矩:

  1. 已经在跑的无人值守脚本,不要改。 finalize_year.py 一旦启动就在后台等 OCR, 此时去编辑它,改的是下一次的行为,正在跑的进程用的还是旧代码, 两边对不上。收尾的活另起一个启动器串在后面(本 skill 用 finish_year.py)。
  2. 每一步都要能单独失败。 出表失败也要照样出报告、写日志, 别让一个环节挂掉就整条链路哑火——无人值守跑挂了没人看日志最麻烦。
  3. ★ 挂后台不要用 nohup ... &,要用后台任务机制。 实测 nohup $PY finish_year.py ... > log 2>&1 < /dev/null & disown 在同一条命令内看着是活的(kill -0 通过),但命令一返回进程就被回收, 日志停在第一行,之后几小时什么都没发生——而你以为它在跑。 年度全量就差点因此静默失败(收尾链整条没执行)。 正确做法是把长跑命令直接交给后台任务执行,别自己 nohup。 验证方法:过几分钟再查一次 pgrep,不要只在启动那一下确认。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.