此渲染由 Yohaku API 生成，或存排版之虞，最佳体验请往：https://jiajian233.xyz/notes/9

览毕，何不一言？

上个月我写了篇文章，讲我搭了个飞书多维表格 AI 评分服务：有人提交需求，webhook 收到事件，大模型打分，分数写回表格，机器人给提交者发卡片。文章列了十个坑，最深的一个是写回死循环——评分本身要写表，写表又触发新事件，服务再评一次，无限循环。当时的解法是内容指纹：把参与评分的输入算个 MD5，内容没变就跳过。

这个月我把那个解法删了。不是找到了更好的哈希，而是想明白问题根本不在哈希上。新代码连让回声进入处理流程的机会都不给。

这篇是续集。讲三件事：上篇文章的解法为什么必须死；替掉它的是什么（ReviewFlow 现在是 v2.0.0）；以及两个比调提示词重要得多的设计决定——用状态机门控触发，而不是猜意图；对 AI 输出做严格校验，而不是打捞。

第一个被删的解法：内容指纹

先回顾 v1 的链路。记录变更事件进来 → 收集文本、文档链接、附件 → 发给模型 → 分数和状态写回 → 通知。写回本身就是一次记录变更，于是又以新事件的形式弹回来。v1 的准入判断是"内容到底变没变"——对参与评分的输入算 MD5，存在内存里。

生产环境里三个雷把它炸穿了：

1. 事件 payload 带的是全部字段，不是变更字段。 飞书 record_changed 事件的 before_value/after_value 实测是整条记录，和文档里"只含变更字段"的示例对不上。diff 的前提从一开始就不成立。
2. 人员字段序列化不稳定。 "提报人"这类字段每次读出来序列化结果都不一样，diff 恒为"有变更"，假阳性。自己写回的事件永远认不出来。
3. 普通文本字段也会偶发假阳性。 连文本字段都偶尔能 diff 出根本不存在的变更。

就算指纹偶尔生效，它也是个带内存的启发式：进程一重启，每条记录多评一次。当时我觉得"可接受"。不可接受。指纹是在给一个允许系统自我触发的设计打补丁，而且靠猜。

指纹后面还藏着一层二级循环：没有可评内容（比如只传了图，模型读不了）的记录会被复位成"待评分"等用户补充，这次复位写回又触发新事件，而我的守卫对"待评分"状态开了豁免，于是"无可评审→复位待评分→事件→无可评审……"实测一轮约 2 秒，每秒打一次飞书 API，永不停，只能手动删记录止损。

替掉它的是什么：你没有资格触发自己

v2 的准入逻辑是两个变量的纯函数：记录当前状态 + 谁在请求。就这些。不看内容，不比 diff，不算哈希。

状态 × 触发来源 → 是否准入

• 初始事件 / 崩溃恢复：只准入 待评分。
• 用户重评：只准入 未通过，只能点卡片里的按钮，而且点击人的 open_id 必须和提报人字段一致。隐藏的 修改轮次 递增，满 5 轮进入 已驳回，按钮消失。
• 管理员重试：只准入 评分异常，只能来自管理员群的卡片（chat_id 必须匹配）。
• 其余一切：静默拒绝。

以前制造回声的那次写回，现在落进 已通过 / 未通过 / 评分异常——这三个状态对初始事件来源全部不可触发。门控没有放行的分支，循环在结构上就形不成。没有启发式可以猜错。

诀窍就一句话：把写回结果放进事件源碰不了的状态里，回声靠设计吸收，不靠检测硬扛。

Not support render this content in RSS render

光有状态门控还不够，世界不是单线程的。三个机制把它补严：

Fencing。 每条记录的任务拿到一个递增的 fence 序号。最终写回前检查 is_current(key, fence)，如果已经被更新的任务接管（或评分过程中用户重评了），旧结果直接作废——僵尸写回盖不掉新分数。对应的回归测试叫 test_fencing_discards_zombie_result_before_final_write。

每记录串行 + 幂等。 完整记录键（app_token:table_id:record_id）同时只允许一个在岗任务；webhook 的 event_id 在 300 秒滑动窗口里去重。卡片回调用 message_id + 操作人 + 动作值 派生幂等键，连点两次"重新评分"只会产生一个任务，重复投递自动折叠。

清道夫兜底崩溃场景。 fencing 和串行都在内存里，进程被杀就丢。清道夫每 60 秒扫一次卡在 评分中 的记录，系统 last_modified_time 超过 900 秒且没有活任务 的，复位成待评分重新准入。注意那个"没有活任务"——跑得慢但还活着的评分永远不会被复位，哪怕时间戳看起来很旧。test_slow_live_task_is_never_reset_even_when_timestamp_is_old 把这条钉死了。

准入矩阵可以直接抄走：

第二个被删的解法：JSON 打捞

v1 解析模型返回用了三级降级：直接 json.loads → 正则抠最外层 {} → 逐字段正则捞。每一级成功都会产出一个"分数"，其中一些内部根本对不上账。典型故障：长 detail 撞上 max_tokens 被截断，JSON 后半截非法，于是降级分别捞 score 和四个维度分……加起来不等于总分。系统返回了一个错的数字，打上 _parse_fallback 标记，继续运行。

当时管这叫健壮性。它比失败更糟：静默降级没有告警。 崩溃有堆栈，打捞出来的分数什么都没有——评分质量悄悄烂掉，没有任何信号。

v2 把方向反过来：

• 让截断不发生。 max_tokens 调到 4000，schema 又把内容压住（detail ≤ 500 字、highlights ≤ 150、improvements ≤ 250），正常响应是段短 JSON，留足余量。
• 全量校验。 响应用 Pydantic 严格模式解析：字段精确、类型精确、score 必须等于四维度之和（model_validator 强制）、维度在各自区间内、extra="forbid"。校验不过就拒绝，绝不修复。
• 只允许两种语法恢复。 剥一层 Markdown 代码围栏，或者从前后废话里提取一个完整 JSON 对象。字段级打捞删除——测试名就叫 test_parse_response_rejects_non_json_without_field_salvage。
• 响亮地失败，然后升级。 非法响应抛异常，工作流重试最多 3 次，仍失败进 评分异常，通知管理员群而不是提交者，修改轮次不加。

原则：先让输入不容易坏（token 余量、temperature 0、提示词里写清 JSON schema），真坏了就响亮地失败到有人盯的通道里。永远不要静默返回一个没有意义的数字。

上篇文章里没删的坑

不是所有东西都被删了。四个坑原样保留，因为它们就是飞书的真实行为：

• 订阅 API 是硬前提。 控制台勾选事件类型不会推任何东西，必须对具体多维表格调一次 drive/v1/file/subscribe。零报错，静默，仍然是"事件收不到"的头号原因。
• 没有顶层 record_id。 ID 在 action_list[i].record_id 里，一个事件可能带多条 action。
• FastAPI 把 header 转小写，SDK 不认。 转交 lark-oapi 前把 X-Lark-* 复原成规范大小写，否则每次签名校验都失败。
• wiki 链接给的是节点 token，不是文档 token。 导出接口直接拒收（1069914），必须先 wiki/v2/space/get_node 解析，还要给应用开 wiki:wiki:readonly，否则静默降级。

两个坑换了形态。日期字段要毫秒时间戳那个坑没了——v2 干脆不写评分时间字段，detail、亮点、改进建议只进通知卡片，不进表。图片占位符污染评分的坑也没了，但原因更彻底：v2 把 raw_content 纯文本整个移除了。

替掉纯文本的内容管线

两篇文章之间最大的架构变化：评分输入从"你抓来的文本"变成"你造出来的一份 PDF"。所有在线文档经导出任务 API 转 PDF，所有附件转 PDF（图片走 Pillow，处理 EXIF 方向、压平透明通道；Word/Markdown/纯文本走无头 LibreOffice，独立 profile、60 秒硬超时、超时杀进程组），然后合并成一份确定性总 PDF——文档在前、附件在后，每份材料前有来源分隔页，按解析后的真实 token / file_token 去重。

这一下消灭了一类 bug（模型看到的就是用户看到的：排版、截图、表格），也带来一批必须一起上线的限制：

• 附件最多 20 个、单个 20MB、总共 100MB、PDF 最多 300 页、图片最多 20 张，能提前查的都在下载前查。
• 加密或损坏的 PDF 是用户可修复的材料问题，不是技术故障：提交者收到一张列明全部问题文件的卡片，记录落 未通过，不烧修改轮次。
• 任何一份文档导出或附件转换失败，整次采集中止——没有部分 PDF，没有"差不多得了"的降级。test_transient_retry_repeats_only_failed_download_step 证明重试按步骤隔离，test_pdf_bundle_failure_never_calls_ai_or_writes_partial_result 证明 AI 永远不会收到残缺的 PDF。
• 启动时校验：模型不支持 PDF 文件输入、或 LibreOffice 不在，直接拒绝启动。开机就失败，而不是凌晨两点静默降级。

还有两条生产经验值得抄：

写工作流之前先给失败分类。 每个错误都有类别：瞬时故障（重试最多 3 次）、用户可修复的材料问题（→ 未通过 + 列明哪些文件坏了的卡片）、系统硬失败（→ 评分异常，只进管理员群，提交者永远看不到技术报错卡片）。上面那张准入矩阵之所以成立，靠的就是这套分类。

熔断发送侧，不熔断提报侧。 单条记录 5 分钟窗口最多 20 张卡片，超限停发并给管理员群发一次告警。正常提报永远不限流，熔断只拦"一条记录不断产卡片"的病态循环。

动手之前先问三个问题

如果你要把 AI 接进飞书、Airtable、Notion，或者任何"你的服务既消费事件又往同一个存储里写"的平台，先跑一遍这个：

1. 我是不是这张表的写回者兼消费者？ 不是，普通幂等（按 event_id 去重）就够了。是，往下看。
2. 我的写回能不能落进事件源碰不了的状态？ 能，就做状态门控 + 显式人工动作（按钮、管理员重试）——这是让回声在结构上不可能发生的设计。
3. 如果不能（比如 A 表写回必须立刻驱动 B 表的处理），门控关不掉回声，这时才轮到指纹/幂等键，而且要把它们当启发式用：预期假阳性，预期重启丢内存，再加个清道夫兜底。

AI 输出侧同理：优先"不容易坏"，而不是"坏了再捞"。 token 余量、确定性采样、提示词里写清 JSON schema、严格校验、响亮失败带重试、升级到人工通道。你要是发现自己正在写第四个解析兜底，停下来问一句前三个为什么存在。

Not support render this content in RSS render

什么时候这套不适用

状态门控模式的前提是：流程能建模成少量状态 + 少量触发来源。它失效的情况：需要连续自由编辑持续触发重评（没有离散状态可以设门）；多实例部署但没把串行和 fencing 外置（内存守卫是单实例假设）；写回者/消费者跨表分离（问题 2 的答案是"不能"）。这些场景里指纹方案不算错——它只是启发式，你应该预算它的失败模式，而不是像我一样在生产里踩出来。

相关阅读：这个项目的上一篇，飞书 webhook AI 评分踩坑清单，把平台坑讲得很细。LLM 评委那部分，评分提示词在仓库的 app/ai.py 里，飞书官方文档的文件订阅和文档导出是两个最先接触的 API 的权威参考。

我给飞书多维表格搭了个 AI 自动评分服务:有人往表里提交待评审的内容,服务监听到记录变更,把文本、飞书文档、附件全收集起来喂给大模型打分,再把分数、评语、通过/未通过状态写回表格,顺带用机器人给提交者发条通知。

听起来是个"接个 AI API 就完事"的活。真做下来,我在生产里踩了 10 个坑,其中 9 个和 AI 的智能程度毫无关系。

它们分两类。一类是平台不按你以为的方式工作,飞书 webhook 有一堆反直觉行为;另一类是 LLM 当裁判天生放水,你不摁住它,它就给同情分。真正调通"让模型打个分"这件事,大概占了我 10% 的时间。

这不算一篇夸 no-code + AI 有多神的文章,更像一份过来人把坑摊开给你看的清单:每个坑我给你现象、根因,和代码级的修复。如果你正打算在飞书、Airtable、Notion 这类平台上接 AI 做自动化,这些坑大概率也在等你。

这套流水线到底在做什么

先把架构讲清楚,后面的坑才有坐标。整条链路是事件驱动的:飞书表里一条记录变了 → webhook 收到事件 → 一个编排器(orchestrator)把这条记录的所有内容凑齐 → 发给 AI 打分 → 结果写回表格 → 通知提交者。

Not support render this content in RSS render

注意那条虚线:写回结果本身会触发一个新的记录变更事件。这条不起眼的回边是全文最深的坑,后面第二幕专门讲。

技术栈很朴素:FastAPI 收 webhook,lark-oapi SDK 跟飞书打交道,大模型用豆包(Doubao),httpx 下载文件。没有一样是花活。坑不来自技术选型,坑来自平台的真实行为和文档描述之间的那道缝。

下面按我踩坑的顺序,分四幕讲。

第一幕:平台不按你以为的方式工作

飞书 webhook 的头四个坑有个共同点:每一个都是闷声失败。代码没报错、服务正常跑、日志一片祥和,但事件就是收不到,或者字段就是写不进去。没有异常栈给你指路,你只能靠猜。这是最耗时间的一类 bug。

坑 1:配了回调 URL,事件却一条都收不到

我最早卡了大半天在这:webhook 地址配好了、事件类型在控制台勾了、握手验证也过了,可是往表里改记录,服务端一个事件都收不到。

根因反直觉到离谱:飞书云文档事件,光在控制台订阅是不够的,你必须用代码主动调一次订阅 API,去"激活"对某个具体文档的订阅。控制台里那个勾更像是"授权",真正的订阅动作得你自己发:

from lark_oapi.api.drive.v1 import SubscribeFileRequest

req = SubscribeFileRequest.builder() \
    .file_token("<BITABLE_APP_TOKEN>") \
    .file_type("bitable") \
    .build()
client.drive.v1.file.subscribe(req)

这段代码不在我的服务主流程里,它是部署前的一次性手动操作,得对每个要监听的多维表格执行一次。我特意提这点,是因为你翻遍服务代码也找不到它,却又非它不可。需要 docs:event:subscribe 或 drive:drive 权限。

避坑:如果你的 webhook 握手能过、但业务事件收不到,先别怀疑代码,去确认这个订阅 API 调没调过。这一步没有任何报错提示你漏了它。

坑 2:事件 payload 里没有顶层 record_id

订阅通了,事件能收到了,下一个坑立刻来:我按直觉去 event.record_id 取记录 ID,拿到的是 None。

飞书多维表格变更事件(P2DriveFileBitableRecordChangedV1)根本没有顶层 recordid。ID 藏在 `actionlist` 里,而且一个事件可能携带多条 action(新增/编辑/删除混在一起),得遍历:

# action_list 里才是变更的记录,一个事件可能有多条
action_list = getattr(event, "action_list", []) or []
for action in action_list:
    record_id = getattr(action, "record_id", None)
    action_type = getattr(action, "action", "") or ""
    if not record_id:
        continue
    # ... 逐条处理

这个坑的隐蔽之处在于:SDK 自动生成的事件模型里,record_id 这个属性名压根不在你以为的层级,IDE 补全也不会提示你去 action_list 里找。批量编辑时一个事件带多条 action,也是个容易漏的点:你要是只取第一条,批量操作就丢记录了。

坑 3:FastAPI 把 header 全转小写,SDK 却要原始大小写

这个坑更阴,因为它表现成签名验证失败,而不是"header 找不到"。

飞书用 X-Lark-Request-Timestamp、X-Lark-Request-Nonce、X-Lark-Signature 这几个 header 做签名校验。而 FastAPI 的 dict(request.headers) 会把所有 header 名转成全小写(HTTP 标准允许),lark-oapi SDK 却用大小写敏感的方式去查它们:查不到,拿到 None,签名计算直接崩,所有事件被拒。

修复就是在把请求转交给 SDK 之前,手动把这几个签名 header 的大小写复原:

raw_headers = dict(request.headers)   # 已被 FastAPI 转成全小写
headers: dict[str, str] = {}
for k, v in raw_headers.items():
    kl = k.lower()
    if kl == "x-lark-request-timestamp":
        headers["X-Lark-Request-Timestamp"] = v
    elif kl == "x-lark-request-nonce":
        headers["X-Lark-Request-Nonce"] = v
    elif kl == "x-lark-signature":
        headers["X-Lark-Signature"] = v
    else:
        headers[k] = v

只需复原这三个签名相关的,其余 header 不敏感。这个坑的教训是:当一个 Web 框架和一个 SDK 对同一份 HTTP 元数据有不同假设时,缝就夹在中间。两边各自都"没错",但拼一起就漏。

坑 4:日期字段要毫秒时间戳,不是 ISO 字符串

前三个坑卡在"收事件",这个坑卡在"写回去"。

我要把评分时间写进多维表格的日期字段,顺手塞了个 ISO 8601 字符串(2026-07-13T14:30:00Z),飞书默默拒绝,字段写不进去,还不给你清晰的报错。飞书 Bitable 的日期/时间字段吃的是毫秒级 Unix 时间戳(整数):

now = int(datetime.now(timezone.utc).timestamp() * 1000)  # 例如 1752408000000

update_fields = {
    FIELD_AI_SCORE: score,
    FIELD_AI_SCORE_TIME: now,   # 毫秒 int,不是 ISO 字符串
    FIELD_SCORE_STATUS: new_status,
    # ...
}

必须是 int,不能是 float、更不能是字符串。这类"格式对了才写得进、错了也不明说"的坑,飞书里散落着好几处(附件下载的认证也是一个,后面第三幕会讲)。

第一幕小结:这四个坑没有一个需要你懂 AI。它们是 no-code + AI 自动化里那部分"没人会在 demo 里提"的隐藏工时:平台的真实契约和文档、直觉之间的每一道缝,你都得亲自摔一次才知道。而下一个坑,比这四个加起来都深。

第二幕:最深的坑——写回把自己打进死循环

这是我在这个项目上花时间最多、也最能说明"事件驱动 + 自动写回"到底难在哪的一个坑。它不是一个 bug,是一串层层嵌套的 bug:每修好一层,下一层就冒出来。

病根:写回会触发一个新事件

回到开头那张流程图的虚线。评分完成后,我把分数、评语、状态写回记录。这个写回操作本身,在飞书看来就是一次"记录变更",于是又推给我一个 webhook 事件。服务收到这个事件,又开始评分,又写回,又触发……

Not support render this content in RSS render

如果评分结果落在一个"可触发评分"的状态(比如"未通过",用户改完还得再评),那这个回声就会稳稳地把系统拖进无限循环。第一次上线,我眼睁睁看着一条记录被反复评分,豆包的调用量和飞书的 API 请求量一起往上飙。

第一次尝试:用字段级 diff 识别写回,被击穿

最直觉的解法:事件里带了变更前后的字段值,那我比一下 diff。如果只有输出字段(分数/状态)变了、输入字段没变,就判定是我自己的写回,跳过。

这个方案在真实表里被彻底击穿,踩了三个雷:

1. payload 携带的是全部字段,不是变更字段。飞书事件里 action.after_value / before_value 实测带的是记录的所有字段,和官方文档给的"只含变更字段"示例矛盾。diff 的基础前提就不成立。
2. 人员字段序列化不稳定。"提报人"这类人员字段每次序列化的结果都不完全一样,diff 因此恒为"有变更",假阳性,写回永远被误判成用户编辑。
3. 文本字段偶发假阳性。连普通文本字段都会偶尔 diff 出不存在的变更。

三个雷叠加,字段级识别彻底不可靠。这是我从官方文档示例出发、结果被真实数据打脸的一次:文档描述的事件模型,和你的表实际推送的,不是一回事。

正解:内容指纹

既然没法靠"谁变了"判断,那就靠"内容本身变没变"判断。我给每条记录算一个内容指纹:只取真正参与评分的字段(原始描述、需求文档链接、需求附件),算个 MD5。附件用稳定标识(file_token,退化时用文件名+大小),刻意避开 tmp_url 这种每次拉取都变的易变值,保证同一份内容多次读取,指纹恒定。

def _content_signature(self, fields: dict) -> str:
    text = str(fields.get(FIELD_TEXT_CONTENT, "") or "")

    doc = fields.get(FIELD_DOC_LINK, "")
    if isinstance(doc, dict):
        doc = doc.get("link", "") or doc.get("text", "")
    doc = str(doc or "")

    atts = fields.get(FIELD_ATTACHMENT, []) or []
    att_parts = []
    for a in atts if isinstance(atts, list) else []:
        if isinstance(a, dict):
            # file_token 稳定;退化时用 名字+大小,避开每次都变的 tmp_url
            att_parts.append(str(
                a.get("file_token") or f"{a.get('name','')}:{a.get('size','')}"
            ))

    raw = "".join([text, doc, *att_parts])
    return hashlib.md5(raw.encode("utf-8")).hexdigest()

逻辑很简单:处理前算一次指纹,和上次存的比。一样,是我自己写回的回声,跳过;不一样,用户真改了内容,重评。指纹存内存,重启后每条至多多评一次,可接受。

content_sig = self._content_signature(fields)
if self._scored_sig.get(record_id) == content_sig:
    logger.info("跳过写回回声(评分内容未变化): record=%s", record_id)
    return
self._scored_sig[record_id] = content_sig

用"内容变没变"代替"字段 diff",绕开了人员字段序列化不稳定的假阳性。用户改内容,指纹变,自然重评;单纯的状态写回,指纹不变,一律跳过。

二级坑:空内容记录停在"待评分"态,又循环了

以为搞定了,结果又冒出一层,这层更狡猾。

我早期的守卫写的是 if status != 待评分 and 指纹相同: 跳过。加那个 status != 待评分 的豁免,是想着"待评分一定是用户显式想重新评,不该当回声跳过"。这个假设是错的。

问题出在两个分支上:一条记录没有可评审内容(比如只上传了图,而模型不支持图),或者附件格式不认,系统会把状态恢复成"待评分"等用户补充。可是,恢复"待评分"的这次写回又触发了一个事件;因为 status == 待评分 命中了豁免,回声没被跳过;于是又"无可评审→恢复待评分→事件→无可评审……"

实测:每 ~2 秒一轮,永不停止。不发 AI(空内容分支在调模型前就返回了),通知被冷却挡着,但它持续打飞书 API,约 1 次/秒,靠自身逻辑永远不会停。止损只能手动删记录。

修复很干脆:去掉那个豁免,回声守卫改成纯指纹比对:

# 改前:if status != STATUS_PENDING and 指纹相同: return   # 待评分被豁免 → 漏
# 改后:
if self._scored_sig.get(record_id) == content_sig:
    return

去掉 status != 待评分 后,首次到达仍会正常处理(此时还没指纹缓存,比对不相等),之后相同内容(含"待评分"态的空内容回声)一律跳过。实测:空内容记录只处理一次就稳住,死循环根除;而未通过的记录改成充实内容后,score 从 0 重新评到 79、轮次 1→2,没被误判成回声。

这一幕真正的教训

写回死循环这一串,本质是事件驱动自动化的一个结构性陷阱:只要你的系统既是事件的消费者、又是事件源的写入者,它就会听到自己的回声。飞书这个案例把它放大了,因为你连"这是不是我自己的回声"都没法可靠判断(字段 diff 被击穿)。

解法的通用形态值得记住:别问"谁改的",问"实质内容变了没有"。给你真正在乎的输入算一个稳定指纹,拿指纹当幂等键。这个思路能迁移到任何"写回会触发再处理"的自动化场景,不只是飞书。

第三幕:喂给 AI 之前,内容是脏的

前两幕在跟"事件"较劲。这一幕跟"内容"较劲:你从飞书拿到的内容,不是你以为的那份干净内容。这些坑不会让服务崩,而是会悄悄拉低评分质量,比崩溃更难发现,因为一切都"看起来正常"。

坑 7:文档里的图片,变成了污染评分的 image.png

这个坑我排查了半天,因为它表现成一个自相矛盾的现象:缓存里的文档文本明明很干净,评分详情却在抱怨"文档里有一堆 image.png 冗余占位符,格式扣分"。文本里没有的东西,模型怎么会抱怨?

根因:飞书文档的 raw_content 接口会把每一张内嵌图片渲染成一个独占一行的裸文件名,截图或粘贴图默认就叫 image.png,也可能是 image (1).png、截图.jpg。这些既不是用户写的内容,又被评分模型当成"排版里塞了一堆冗余占位符"莫名扣格式分。

而那个"自相矛盾"是这么来的:转写缓存用的提示词明令禁止输出占位符,把它们剔了,所以缓存干净;评分走的是另一条路,看到了带占位符的原文。同源内容,两套提示词,制造了一个假矛盾。

修复是在内容进评分和缓存之前,统一清洗掉"整行就是一个图片文件名"的行:

_IMAGE_PLACEHOLDER_LINE = re.compile(
    r"^[\w一-鿿.\-()（） ]{1,80}\.(?:png|jpe?g|gif|webp|bmp|svg|tiff?)$",
    re.IGNORECASE,
)

def strip_image_placeholders(text: str) -> str:
    if not text:
        return text
    kept = [ln for ln in text.splitlines()
            if not _IMAGE_PLACEHOLDER_LINE.match(ln.strip())]
    cleaned = "\n".join(kept)
    return re.sub(r"\n{3,}", "\n\n", cleaned).strip("\n")   # 顺手压掉多余空行

关键分寸:只删"整行就是图片文件名"的行,保留正文里顺带提到文件名的句子(比如"详见附件 方案.png"),也保留 .docx 这类非图片名。实测拿真实 wiki 文档跑,占位符从 4 行清到 0 行,评分详情不再无端抱怨格式。

通用教训:任何"富文本导出成纯文本"的接口,都会往文本里掺你没预期的渲染产物(图片占位符、表格边框字符、脚注标记)。进 LLM 之前务必过一道清洗,否则模型会把这些噪声当成内容质量的一部分来评判。

坑 8:wiki 链接里的 token,不是文档 token

飞书文档链接有好几种形态。普通文档是 /docx/<token>,知识库链接是 /wiki/<node_token>。这个 node_token 是知识库"节点"的 token,不是背后真实文档的 token。

坑在于:raw_content 接口能直接吃 wiki 节点 token(内部帮你自动解析了),于是纯文本读取一切正常,你毫无察觉。但导出 PDF 的 export_task 接口不认:直接拿节点 token 去导,报 1069914 file token invalid,于是永远回退到纯文本,文档里的图片永远不会被解析(多模态模型看不到图)。

修复是导出前先把 wiki 节点解析成真实文档 token:

# wiki 链接的 token 是节点 token,导出前必须先解析出挂载的真实文档 obj_token
req = GetNodeSpaceRequest.builder().token(node_token).build()
resp = client.wiki.v2.space.get_node(req)
# resp.data.node.obj_token / obj_type(docx/doc/sheet...)才是能拿去导出的

这里还埋了个权限坑:get_node 需要应用有 wiki 访问权限,否则报 99991672 Access denied。这个权限得去飞书控制台单独给应用开(wiki:wiki:readonly 或 wiki:node:read),开通前 wiki 文档只能走纯文本、看不到图。又是一个代码写对了、但权限没配就闷声降级的坑。

坑 9:附件下载,不带认证就是 400

顺带说个小而致命的:飞书返回的附件下载 URL,直接用 httpx.get() 裸拉会 400。必须带上租户级 access token:

token = TokenManager.get_self_tenant_token(self._client._config)
headers = {"Authorization": f"Bearer {token}"}
resp = await self._http.get(url, headers=headers)

飞书所有文件资源的下载都得带这个 header。它和坑 4(datetime 格式)是同一类:平台的隐性契约,文档里一笔带过,漏了就失败,而且报错不告诉你真正原因。

坑 10:AI 返回的 JSON 会破,直接 json.loads 就崩

内容干净了,喂给模型,模型该老老实实还我一个 JSON 评分了吧?也不一定。

我让模型返回 {score, detail, dimensions} 结构。但豆包在边界情况下会返回破碎的 JSON,最典型的是 detail(评语,有时还带文档转写)很长,撞上 max_tokens 被从中间截断,末尾的 JSON 直接非法。这时候 json.loads() 一抛异常,整个评分流程终止,用户永远等不到结果。

解法是三级降级解析,能捞多少捞多少:

def _parse_response(self, text: str) -> dict:
    # 一级:直接解析,正常情况 95% 命中
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        pass

    # 二级:正则抠出最外层 {...} 再解析,容忍模型加的前后缀废话
    m = re.search(r"\{[\s\S]*\}", text)
    if m:
        try:
            return json.loads(m.group())
        except json.JSONDecodeError:
            pass

    # 三级:JSON 仍破(通常是尾部被截断),逐字段正则捞回 score/detail/维度分
    score_match = re.search(r'"score"[\s:]*(\d+)', text)
    score = max(0, min(100, int(score_match.group(1)) if score_match else 0))
    # ... 各维度同理,捞不到才退 0
    return {"score": score, ..., "_parse_fallback": True}

三级的设计有个讲究:为什么不直接在解析失败时把维度分填 0?因为响应被截断时,靠前的 score 和各维度分往往是完整可读的,只有靠后的长 detail 被切了。硬填 0 会造成 score 和四个维度分之和对不上,一个明显的数据不一致。逐字段正则捞,能保住这份一致性。结果里标个 _parse_fallback: True,方便事后统计降级率。

第三幕小结:这一幕的四个坑,没有一个会让你的服务挂掉,它们只会让评分悄悄变差或悄悄降级。这比崩溃危险,因为崩溃有栈、有告警,而"评分质量慢慢烂掉"没有任何信号。接 AI 做自动化,输入侧的数据清洗和输出侧的容错解析,值得的投入远超你的预期。

第四幕:AI 当评委,天生放水

前三幕的坑都在 AI 外围。这一幕才碰到 AI 本身,而它暴露的问题可能是这套系统最反直觉的一点:大模型当评委,默认是个老好人。

症状:"把要求做完了"就能拿 80 分

第一版提示词我写得挺"正经":要求模型"严格、客观、可复现,发现缺陷就扣分"。上线一跑,分数普遍虚高,只要内容不是空的、把要求大致做完了,轻松 80 分往上。想分出"哪份该打 60、哪份该打 90",分数却挤在一起分不开。

问题不在模型笨,在于 LLM 的默认人格是讨好型的。你说"严格",它理解成"别太苛刻";你让它评价,它倾向于找优点、给"努力分"和"同情分"。中性、礼貌的措辞,喂出来的就是中性偏高、区分度低的分数。这不是 prompt 写得不够详细,是方向就没摁住。

解法:从"印象给分"逼成"逐条扣分"

我把系统提示词重写了一版,核心是换掉模型的给分心智模型。对比一下改动前后的措辞:

三个改动最关键。

一是"从满分起扣的扣分账"。让模型别再"看一眼给个印象分",而是从 100 分开始,强制逐条列出缺陷、逐条标注扣多少。这把打分从一个模糊的直觉动作,变成了一个可追溯的清算过程,顺带评语也更有理有据了。

二是"硬性上限红线"。有些缺陷是致命的,不该被别的维度救回来。比如内容有事实性错误、足以误导使用者,那不管排版多漂亮、篇幅多完整,整份分数封顶 60。这一条直接解决了"局部亮点掩盖致命伤"的虚高。

【硬性上限(红线,满足任一项则整份 score 被封顶)】
- 存在事实性错误、逻辑硬伤或自相矛盾,足以误导使用者:score ≤ 60。
- 关键要素缺失,导致内容无法据以落地/执行/理解:score ≤ 55。
- 通篇空泛、无实质信息或严重跑题:score ≤ 40。
- 内容近乎空白、敷衍了事或答非所问:score ≤ 25。
(多条红线同时命中时,取最低的上限。)

三是明令反注水。LLM 特别容易被"看起来很努力"骗到:篇幅长、态度诚恳、排版花哨,它就想加分。得显式禁止:不因篇幅、态度、排版加分,注水内容反而倒扣。

改完之后,分数分布明显拉开了,"做完了"落回中档,真正专业的交付才够得着高分。同一份内容重复评,分数也稳(配合 temperature=0 的确定性采样)。

但要诚实:LLM 评委有天花板

摁住放水之后,它变得能用了,但别指望它变成一个完美裁判。两个改不掉的局限得摊开说。

一是一致性只是"够用",不是"绝对"。即便 temperature=0,同一份内容多次评分仍可能有轻微漂移。它适合做初筛和分档,不适合做"精确到分、分数还直接决定钱和晋升"的终裁。

二是它评的是"文本表现",不是"事实真伪"。一段写得漂亮但事实错误的内容,模型不一定抓得住,除非错误明显到它的知识能覆盖。红线能兜住"它发现的"致命伤,兜不住"它没发现的"。所以我的定位始终是 AI 初筛加人工复核,而不是全自动终判。这条边界直接引出最后一幕:什么场景值得这么搭。

一张飞书 webhook + AI 评分踩坑速查表

最后把这 10 个坑压成一张表,你可以截图存下来,搭之前对着排雷:

收个尾

回到开头那个数字:10 个坑,9 个和 AI 无关。

这不是说 AI 不重要。而是说,当"接个大模型"变得越来越简单,真正的工程量就整个转移到了别处:转移到平台集成那些没人写进文档的隐性契约里,转移到"事件驱动系统听到自己回声"这类结构性陷阱里,转移到把一个讨好型 LLM 摁成一个能用的评委上。

如果你也要在飞书、Airtable、Notion 上接 AI 做自动化,别被 demo 的丝滑骗了。demo 展示的是那 10%,这篇文章讲的是等着你的那 90%。搭之前,把上面那张速查表和那段提示词骨架存下来,至少能帮你把最深的两个坑(收不到事件、写回死循环)提前绕过去。

相关阅读:如果你对"LLM 当评委"这个话题感兴趣,可以继续了解 LLM-as-a-judge 的评测偏差,以及事件驱动架构里的幂等性设计。这两个主题在这个项目里被反复验证,值得单独深挖。

此渲染由 Yohaku API 生成，或存排版之虞，最佳体验请往：https://jiajian233.xyz/notes/7

览毕，何不一言？

此渲染由 Yohaku API 生成，或存排版之虞，最佳体验请往：https://jiajian233.xyz/notes/6

览毕，何不一言？

https://github.com/wjiajian/astrbot_plugin_hindsight_memory

这是一个 AstrBot 插件，用于接入 Hindsight Cloud，为私聊和群聊提供按会话隔离的长期记忆能力。

Hindsight 是一个面向 AI 应用的长期记忆服务，可以把对话中的信息沉淀到 Memory Bank，并在后续请求中按语义检索相关记忆。Hindsight Cloud 提供托管版 API 和后台管理界面，适合在不自建向量数据库、不维护记忆管理 WebUI 的情况下，为 Bot 增加可持续积累和召回的记忆能力。

插件不修改 AstrBot 核心，也不提供自定义 WebUI。配置仍然通过 AstrBot 根据 _conf_schema.json 生成的插件配置界面完成，记忆管理使用 Hindsight Cloud 自带后台。

https://github.com/wjiajian/astrbot_plugin_supermemory

功能特性

• 在每次 LLM 请求前，从 Hindsight Cloud 召回相关记忆。
• 通过 extra_user_content_parts 注入临时 <hindsight_memory> 内容，不写入 AstrBot 持久会话历史。
• 在 LLM 回复后，按写入判定策略将值得长期保存的内容写入 Hindsight Cloud。
• 私聊和群聊严格按 scope 隔离，群聊使用“群公共记忆 + 群成员个人记忆”双层召回，避免同群不同用户的个人记忆互相串扰。
• 发送到 Hindsight 的 sender ID、group ID、unified_msg_origin 都会先做 hash。
• 可启用统一的 memory_ai_* 配置，让小模型负责判断是否写入、生成自然事实句，并为自动召回和 /hindsight recall 拓展搜索 query。
• 提供 /hindsight 命令，用于状态检查、手动召回和当前会话临时开关。

平台兼容性

已测试 AstrBot 平台：

• aiocqhttp
• qq_official
• qq_official_webhook

其他 AstrBot 平台理论兼容，未逐一测试。

安装与配置

1. 在 Hindsight Cloud 创建一个 Memory Bank。
2. 为该 Bank 创建 Bank-scoped API Key。
3. 将本仓库安装到 AstrBot 插件目录。
4. 在 AstrBot 插件配置中填写：
   • api_key：Hindsight Cloud API Key
   • bank_id：Hindsight Memory Bank ID
   • api_base：保持默认值 https://api.hindsight.vectorize.io
   • recall_item_max_chars：每条召回记忆注入前的最大字符数，默认 360
   • memory_extract_max_depth：解析召回结果嵌套结构的最大深度，默认 4
   • memory_ai_enabled：是否启用 AI 记忆分析和召回拓展，默认关闭
   • memory_ai_provider_id：建议选择便宜、快速的小模型 Provider；留空时使用当前会话 Provider
5. 保存配置后，重载插件或重启 AstrBot。

插件依赖只包含 httpx，AstrBot 通常会根据 requirements.txt 自动安装。

如果需要手动安装依赖，可在 AstrBot 环境中执行：

pip install -r data/plugins/astrbot_plugin_hindsight_memory/requirements.txt

配置项说明

• enabled：全局启用或关闭插件。
• api_base：Hindsight Cloud API Base URL，默认 https://api.hindsight.vectorize.io。
• api_key：Hindsight Cloud API Key。
• bank_id：Hindsight Memory Bank ID。
• enable_private_memory：启用私聊记忆。
• enable_group_memory：启用群聊记忆。
• recall_limit：每轮最多注入的记忆条数。
• recall_item_max_chars：每条召回记忆注入前的最大字符数，默认 360。
• memory_extract_max_depth：解析召回结果嵌套结构的最大深度，默认 4。
• retain_enabled：启用 LLM 回复后写入 Hindsight。
• retain_decision_mode：写入判定模式，默认 balanced。all 保持旧行为，balanced 只自动写入较稳定的记忆，strict 只写入明确要求记住的内容。
• retain_min_chars：自动写入判定的最小有效字符数，默认 8。
• retain_sensitive_requires_explicit：邮箱、手机号、身份证等敏感信息必须明确要求记住才允许写入，默认开启；API Key、密码、token、private key 永不自动写入。
• memory_ai_enabled：启用 AI 记忆分析和召回拓展，默认关闭。开启后写入判定和召回 query 拓展都会额外调用 AstrBot LLM Provider。
• memory_ai_provider_id：AI 记忆分析使用的 AstrBot LLM 供应商。建议单独配置便宜、快速的小模型；留空时使用当前会话供应商。
• memory_ai_fallback_to_current_provider：所选 AI 记忆供应商调用失败时是否回退到当前会话供应商，默认开启。
• memory_ai_min_confidence：AI 写入判定最低置信度，默认 0.7。低于该值会跳过写入。
• retain_ai_enabled / retain_ai_provider_id / retain_ai_fallback_to_current_provider / retain_ai_min_confidence：兼容旧配置；新安装和新配置建议使用 memory_ai_*。
• retain_dedupe_enabled：写入前先检索当前 scope，跳过高度相似的重复记忆，默认开启。
• retain_dedupe_threshold：重复记忆相似度阈值，默认 0.85。
• retain_dedupe_limit：写入前去重最多检查的历史记忆条数，默认 5。
• retain_write_raw_conversation：写入原始本轮对话而不是精炼后的记忆文本，默认关闭；retain_decision_mode=all 始终保持原始对话写入。
• retain_user_message：写入用户本轮消息。
• retain_assistant_message：写入助手本轮回复。
• request_timeout_seconds：Hindsight 请求超时时间，单位秒。

写入判定策略

写入流程现在采用 AI 优先、规则兜底：

1. 如果 memory_ai_enabled=true，本地只做空文本、命令、硬敏感信息等必要过滤，然后直接调用 AI 判断是否写入、写入什么事实句、写入哪个 scope，以及记忆类型和置信度。
2. AI 必须返回结构化 JSON；插件解析失败、调用失败或置信度低于 memory_ai_min_confidence 时，不影响聊天流程，会回退到本地精简规则。
3. 如果未启用 AI，本地规则只保留明确记忆意图、基础稳定事实、群规则/项目事实、个人偏好等几类，不再依赖大量手写锚点。
4. 写入前仍会用 memory_text 在当前 scope recall，若相似度超过 retain_dedupe_threshold 则跳过；纠正类记忆会继续写入，并在 metadata 中标记为 correction。

AI 生成的 memory_text 会作为自然、独立、可检索的事实句写入，不再强制添加人工锚点前缀。默认不会额外调用 LLM；只有开启 memory_ai_enabled 后才会调用小模型。需要兼容旧行为时，可设置 retain_decision_mode=all。

召回拓展策略

默认召回只使用用户原始 query。开启 memory_ai_enabled 后，每次自动召回和手动 /hindsight recall 都会先让 AI 将原始 query 改写成 1 到 4 条搜索 query，插件会逐条检索、按记忆文本去重，并按 recall_limit 注入结果。AI 只负责拓展搜索词，不允许回答用户问题；如果 AI 调用失败或 JSON 解析失败，则直接回退为只使用原 query。

Hindsight 仍固定使用原有 recall API 和 tags_match: all_strict，本版不引入阈值配置。

命令

• /hindsight status：检查配置完整性和 Hindsight Cloud 连通性。
• /hindsight recall <query>：在当前会话 scope 下手动检索记忆。
• /hindsight on：启用当前会话记忆。
• /hindsight off：关闭当前会话记忆。
• /hindsight help：显示命令帮助。

/hindsight on 和 /hindsight off 的状态保存在 AstrBot 插件数据目录中，只影响当前会话 scope，不会修改 Hindsight Cloud 中已有的记忆。

Scope 隔离策略

私聊使用以下 tags：

scope:private
platform:<platform_id>
sender:<sender_id_hash>
umo:<umo_hash>

群聊使用双层 tags。

群公共记忆：

scope:group
scope:group_shared
platform:<platform_id>
group:<group_id_hash>
umo:<umo_hash>

群成员个人记忆：

scope:group
scope:group_member
platform:<platform_id>
group:<group_id_hash>
sender:<sender_id_hash>
umo:<umo_hash>

召回时固定使用 tags_match: all_strict。私聊只召回当前私聊 scope 的记忆；群聊会同时召回当前群的公共记忆和当前发言成员在该群内的个人记忆。启用 memory_ai_enabled 时由 AI 在允许范围内选择 group_shared 或 group_member；未启用 AI 或 AI 失败时，本地规则会把群规则、群公告、项目约定等内容写入群公共层，把个人偏好、称呼、个人资料等内容写入群成员个人层。retain_decision_mode=all 时保持旧行为，同时写入群公共层和群成员个人层。

写入 metadata 会附带 retention_reason、retention_type、retention_source、retention_confidence 和 retention_action，便于在 Hindsight Cloud 后台排查某条记忆来自规则、AI 判断还是纠正/补充写入。

ID 稳定性与迁移注意事项

正常重启 AstrBot 通常不会改变记忆 scope。插件生成 tags 时会使用：

• platform_id：AstrBot 平台名，例如 aiocqhttp、qq_official。
• sender_id：平台提供的用户 ID。
• group_id：平台提供的群 ID。
• unified_msg_origin：AstrBot 的会话来源标识。
• 本地 salt：插件首次运行时生成，并保存在 AstrBot 插件数据目录中。

只要平台适配器、机器人账号和插件数据目录不变，重启后 hash 出来的 tags 应保持稳定，旧记忆可以继续召回。

以下情况可能导致同一个用户或群生成不同 scope，从而召回不到旧记忆：

• 删除或迁移时丢失插件数据目录，导致 salt.txt 重新生成。
• 更换平台适配器，例如从 aiocqhttp 切换到 qq_official。
• 更换机器人账号、QQ 官方应用或平台配置，导致平台侧用户 ID 变化。
• 平台或 AstrBot 适配器更新后改变了 sender_id、group_id、unified_msg_origin 的生成方式。
• 群聊事件暂时拿不到 group_id，插件会降级为私聊 scope；之后如果又能拿到 group_id，scope 会发生变化。
• 群聊事件拿不到当前发言人的 sender_id，插件会跳过本轮记忆操作，避免多个未知用户被归入同一个个人记忆层。

迁移 AstrBot 或插件时，建议同时备份插件数据目录中的 salt.txt 和 scope_state.json。其中 salt.txt 会影响历史记忆是否还能被同一 scope 召回，scope_state.json 保存 /hindsight on 和 /hindsight off 的当前会话开关状态。

Hindsight API

插件直接调用 Hindsight Cloud REST API，不依赖官方 SDK：

• Recall：POST /v1/default/banks/{bank_id}/memories/recall
• Retain：POST /v1/default/banks/{bank_id}/memories
• 状态检查：GET /v1/default/banks/{bank_id}/tags?limit=1

Retain 使用 item-level tags，并固定使用 async: true，减少对聊天流程延迟的影响。

测试方法

本地单元测试

在仓库根目录执行：

python -B -m unittest discover -s tests -v

语法检查

python -B -m py_compile main.py commands.py hindsight_client.py memory_formatter.py scope.py retention_policy.py memory_ai.py

AstrBot 手动验收

1. 在 AstrBot WebUI 中确认插件已启用，且 api_key、bank_id 已配置。

2. 在聊天中发送：

   /hindsight status
   

   期望看到配置完整，并且 Hindsight Cloud 连接正常。

3. 发送一条需要记忆的内容，例如：

   我最喜欢的饮料是冰美式，请记住。
   

4. 等待几秒到几十秒后，再问：

   我最喜欢喝什么？
   

   如果 Hindsight 已完成异步处理，模型应能通过 recall 回答出相关记忆。

5. 测试当前会话开关：

   /hindsight off
   /hindsight on
   

6. 在不同私聊、不同群聊之间分别测试，确认记忆不会跨 scope 召回。

以下为小学生流水账。

独居生活

2025年，从学生变成打工仔的一年。

一个人住在出租屋，连天然气都没有。入冬过后洗澡都不能洗太久，电热水器只能装一点热水。做饭还是用旧的电磁炉（虽然大多数情况下还是点外卖）。

我很佩服世界上第一个吃螃蟹的人

跨年公司发的大闸蟹到手都没办法处理，下班现场买的蒸格（应该是叫这个吧，总之就是放在锅上蒸东西的那个东西），运气挺好买来和家里的锅刚好合得上。

跟着视频然后请教了一下网友，勉勉强强还是把大闸蟹蒸来吃了，沾点葱蒜生抽调料嗦着吃了。说是蟹心要去掉，但是我根本没看出来哪是蟹心，一口闷了算了。

总之……味道还不错，但也没感觉有多好吃，可能是做的不太好吧。

仔细算了一下，也有半年没自己正经做过饭了，不是外卖就是随便煮点面煮点抄手啥的。

五一出游

上半年在重庆找工作，但是全要有经验的，基础太差技术没有，投了不知道多少简历，最后还是没有找到工作。

五一去了杭州和上海玩了玩。这边物价是真高啊，但是城市建设比重庆好多了。

杭州

• 和朋友转了转西湖
• 爬了爬灵隐寺
• 去杭电走了一圈

上海

本来是想去明日方舟音律联觉的，但是没买到票，就在上海瞎玩了五天：

• 看了看明日方舟主题地铁站
• 跟着朋友走了一圈同济大学
• 跟朋友去看了看卖谷子的地方（忘了叫啥了都）
• 一个人逛了逛植物园
• 和看完音律联觉的朋友一起吃了饭

这还是第一次出去玩。

工作

尝试在这边找了找工作，最后在某电商企业做程序员了。 8：30-17：30，不加班但是大小周。 和互联网相比还是算比较轻松了。

待续

不知道怎么写了，后面再补吧，图也后面再补。

某一天在 GitHub 日 star 排行榜上看到了 lobehub 这个项目，项目链接：https://github.com/lobehub/lobehub

逛到核心开发者 Innei 的个人网站时一下子便被吸引住了，随即我便产生了制作个人网站的想法。由于我没有一点前端基础，只能借助 AI 去 Vibe Coding，磕磕绊绊做出了出来，当然在 Vibe 的过程中参考了很多 Yohaku（Shiro）的效果。

本来我是想实现前后端分离的，但是经验不足最后还是糊到了一起，用 Vue 做了一个静态网站 XD。最后实在做不下去了，还是直接用 Yohaku吧。