WorkBuddy沙箱开发避坑指南：OCR失败、内存超限与热更新幻觉

发布时间：2026/11/4 4:13:34
WorkBuddy沙箱开发避坑指南：OCR失败、内存超限与热更新幻觉

1. 这不是技能上架流水账，而是一份开放平台开发者生存实录

WorkBuddy 开放平台刚上线那会儿，我盯着控制台里“新建 Skill”按钮足足看了三分钟——不是犹豫要不要做，而是盘算着：这次得把坑踩得够深、够准、够痛，才能攒出真正能帮到后来人的经验。不是所有人在写“从0到4”的时候，都默认省略了背后删库重来3次、推翻重写2轮、凌晨三点对着报错日志骂脏话的78小时。这4个上架成功的技能里，有3个是硬扛着文档缺失、API抖动、沙箱限制反复调优才活下来的；剩下那个OCR类技能，我连代码都没敢提交审核，直接在本地删了整个项目文件夹——不是技术不行，是它根本就跑不通WorkBuddy的底层约束逻辑。

你搜“WorkBuddy OCR”出来的结果，90%是教程、安装包、v6 tiny速度对比，但没人告诉你：WorkBuddy 的 Skill 运行环境不支持动态加载.so文件，不挂载GPU设备，内存上限卡死在512MB，且不允许子进程调用外部二进制（比如tesseract.exe或paddleocr的inference模型加载器）。这些不是隐藏条款，是平台架构决定的硬边界。而绝大多数OCR方案——包括PaddleOCR官方推荐的推理方式、Tesseract的CLI调用、AnyTXT的本地服务模式——全都在这个边界之外。我试过PaddleOCR v2.7、v2.8、v3.0、v3.5，也试过用ONNX Runtime手动加载tiny模型，甚至把PaddleOCR的C++ inference库编译成静态链接版本塞进Python包里……最后发现，问题不在模型大小、不在推理速度、不在Python版本，而在WorkBuddy根本没给你打开“执行外部命令”这扇门。

所以这篇不是教你“怎么用PaddleOCR识别文字”，而是带你回到那个真实的开发现场：看一个技能如何在WorkBuddy沙箱里从“能跑通”变成“能上架”，再被“审核驳回”，最后“彻底放弃”。关键词不是“OCR”，而是“沙箱兼容性”、“模型轻量化路径”、“无子进程推理方案”、“Skill生命周期管理”。如果你正打算在WorkBuddy上做图像处理类技能，别急着pip install paddleocr——先读完这四个真实踩坑，再决定要不要碰OCR这个雷区。

2. 第一个坑：WorkBuddy Skill 的“Hello World”根本不是打印字符串

2.1 你以为的入口，其实是平台埋的第一个钩子

WorkBuddy 官方文档里写的Skill启动方式，是让你写一个main.py，里面定义handle_event()函数，然后扔进zip包上传。看起来和Flask、FastAPI的路由写法差不多？错。这是第一个认知陷阱。

我第一次提交的Skill，结构长这样：

skill/ ├── main.py ├── requirements.txt └── assets/ └── logo.png

main.py里只有一行：

def handle_event(event): return {"text": "Hello, WorkBuddy!"}

审核失败，理由：“未响应事件类型”。不是报错，是静默驳回。我查遍文档，没找到“事件类型”具体指什么。直到翻到WorkBuddy开发者后台的“调试日志”面板——那里显示了一行极小的灰色字：“[WARN] event type 'message' not handled”。

原来，WorkBuddy的Skill不是被动等待调用，而是主动订阅事件流。handle_event必须显式声明支持哪些event type，否则平台根本不把消息路由过来。而这个声明，不在代码里，而在skill.json配置文件中。文档里把它藏在“高级配置”章节第三页，字号比正文小两号。

skill.json必须包含：

{ "name": "my-first-skill", "version": "1.0.0", "description": "My first skill", "event_types": ["message", "command"], "entry_point": "main:handle_event" }

提示：event_types字段是强制校验项。漏写"message"，用户发消息你收不到；漏写"command"，自定义指令无法触发。WorkBuddy不会报错提示，只会静默丢弃事件。这是所有新手必踩的第一坑，也是最隐蔽的——因为控制台没有任何错误反馈，只有“技能不响应”的用户投诉。

2.2 沙箱里的Python，不是你本地装的那个Python

我填好skill.json，重新打包上传，这次审核通过了。但用户一发消息，Skill就返回500。日志里只有一行：

ModuleNotFoundError: No module named 'requests'

我明明写了requirements.txt：

requests==2.31.0

查文档，说支持pip安装依赖。再试，还是报错。最后发现：WorkBuddy的沙箱环境只预装了标准库和少量基础包（如json,os,sys），其他所有第三方包必须满足两个条件才能被加载：

  1. 必须是纯Python包（no C extensions）
    requests本身是纯Python，但它依赖urllib3和chardet，而chardet的某些版本含C加速模块（_cchardet）。WorkBuddy沙箱禁用所有.so/.dll加载，所以哪怕你pip install requests成功，运行时也会因ImportError: cannot import name '_cchardet'崩溃。

  2. 必须指定精确版本号，且该版本在WorkBuddy白名单内
    平台维护了一个已验证兼容的包版本白名单。requests==2.31.0不在其中，但requests==2.28.2在。这不是随机选的——2.28.2是最后一个不带_cchardet依赖的版本。我花了一整天用pip show requests+pipdeptree逐层排查依赖树，才定位到这个点。

最终requirements.txt改成：

requests==2.28.2 certifi==2022.12.7 charset-normalizer==2.1.1 idna==3.4 urllib3==1.26.13

注意：WorkBuddy的包白名单每季度更新一次，但文档不公开完整列表。最稳妥的做法是：在本地用pip install --no-cache-dir --force-reinstall -r requirements.txt模拟沙箱环境，然后用python -c "import requests; print(requests.__version__)"验证是否真能导入。别信文档写的“支持”，要信自己跑通的日志。

2.3 日志不是写给你的，是写给审核员看的

我终于让Skill稳定返回“Hello, WorkBuddy!”了。但第二天用户反馈：“点了三次才出结果”。我看日志，全是INFO级别，干净得像没运行过。WorkBuddy的日志系统默认只记录ERROR和WARNING，INFO以下全过滤。而Skill的主逻辑执行耗时，恰恰需要DEBUG级日志才能看到。

我加了logging.basicConfig(level=logging.DEBUG)，上传后审核又失败了，理由：“日志输出不符合规范”。查文档才发现：WorkBuddy要求所有日志必须用print()输出，且格式为[LEVEL] message，例如：

print("[DEBUG] start processing event") print("[INFO] response sent to user") print("[ERROR] model load failed")

它不认logging模块，也不接受JSON格式日志。所有logging.info()调用都会被沙箱拦截，导致Skill卡死在初始化阶段。

实操技巧：我写了个简易日志封装：

def log(level, msg): print(f"[{level}] {msg}") # 使用 log("DEBUG", f"event received: {event.get('text', '')}") log("INFO", "response generated")

这样既满足平台规范，又能保留调试信息。记住：在WorkBuddy里，print()不是调试手段，是唯一合法的日志接口。

3. 第二个坑：PaddleOCR 在沙箱里“加载模型”等于自杀式操作

3.1 PaddleOCR 的默认加载路径，和WorkBuddy沙箱是两条平行线

当我确认基础Skill能跑通后，开始做第二个技能：PDF文本提取。自然想到PaddleOCR——开源、中文强、社区活跃。我按官网教程，在main.py里写：

from paddleocr import PaddleOCR ocr = PaddleOCR(use_angle_cls=True, lang='ch') result = ocr.ocr("input.pdf")

本地测试OK。打包上传，审核失败，日志里只有一行：

OSError: [Errno 30] Read-only file system: '/root/.paddleocr'

PaddleOCR默认把模型缓存到~/.paddleocr目录。但在WorkBuddy沙箱里，/root是只读的，且没有~环境变量。更致命的是，PaddleOCR的PaddleOCR()初始化过程会自动下载模型文件并解压到缓存目录——而沙箱禁止网络请求（除平台允许的https://api.workbuddy.com外），所以下载必然失败；即使提前下载好模型，解压操作也会因权限不足报错。

我尝试手动指定模型路径：

ocr = PaddleOCR( use_angle_cls=True, lang='ch', det_model_dir='./models/det', rec_model_dir='./models/rec', cls_model_dir='./models/cls' )

然后把det,rec,cls三个模型文件夹放进skill包。上传后，日志报：

FileNotFoundError: [Errno 2] No such file or directory: './models/det/inference.pdmodel'

查源码发现：PaddleOCR的模型加载逻辑里，inference.pdmodel和inference.pdiparams必须在同一目录，且文件名不能改。但我压缩zip时，macOS的Finder默认把.DS_Store文件也打进去，导致路径解析异常。Linux下用zip -r skill.zip skill/ -x "*.DS_Store"才解决。

关键教训：WorkBuddy沙箱对文件路径极其敏感。所有相对路径必须以./开头，不能用models/det/；所有模型文件必须是PaddleOCR v2.7+的inference格式（不是训练格式）；且必须确保pdmodel+pdiparams+pdiparams.info三件套齐全。少一个，加载就失败。

3.2 内存炸弹：一个OCR调用吃掉400MB，沙箱直接OOM Kill

模型路径问题解决后，Skill终于能初始化PaddleOCR对象了。但用户上传一张A4扫描图（2480×3508像素），Skill直接超时。日志显示：

Killed

没有堆栈，没有错误，只有冰冷的Killed。这是Linux OOM Killer干的——当进程内存超过沙箱限制（512MB），内核直接SIGKILL终止进程。

我用psutil监控本地内存：

import psutil proc = psutil.Process() log("DEBUG", f"memory usage: {proc.memory_info().rss / 1024 / 1024:.1f} MB")

发现：PaddleOCR加载tiny模型后，常驻内存约180MB；但一调用ocr.ocr()处理一张A4图，内存瞬间飙到520MB+，然后被Kill。

原因在于PaddleOCR的推理引擎默认启用use_gpu=False时，仍会加载大量CUDA相关符号（即使没GPU），且图像预处理（resize、normalize）在CPU上非常吃内存。尤其PaddleOCR内部用cv2做图像缩放，而cv2的resize算法在高分辨率图上内存占用呈平方级增长。

我试过：

  • 把图片resize到1024px宽（用PIL）再传入OCR → 内存降到320MB，但文字识别率暴跌（小字体模糊）
  • 改用--use_tensorrt False参数 → 无效，沙箱没TensorRT
  • 降级到PaddleOCR v2.6 → 内存略降，但兼容性更差

最终方案：放弃PaddleOCR的整图OCR，改用分块裁剪+局部识别。我把A4图切成8块（每块约800×1200），每块单独调用OCR，结果合并。单次调用内存峰值压到120MB，总耗时增加30%，但成功率从62%提升到91%（因为小图里文字更清晰）。

实操步骤：

  1. 用PIL打开PDF转图，统一转为RGB模式
  2. 计算最佳切块数：max_blocks = min(8, int(512 / 120))（预留内存余量）
  3. 每块调用前，显式gc.collect()释放前序内存
  4. 合并结果时，按原始坐标排序，避免段落错乱

这不是优化，是生存策略。WorkBuddy的512MB内存墙，逼你把一个“端到端OCR”任务，拆解成8个“微型OCR”任务。

3.3 模型瘦身：从220MB到18MB，不是删文件，是重编译

即便分块处理，模型文件本身还是太大。det模型220MB，rec模型120MB，加起来340MB，占满skill包限额（500MB）。我试过删*.pdiparams.info、删__pycache__、删model.yml——没用，PaddleOCR加载时校验MD5，缺一不可。

真正的解法来自PaddlePaddle官方文档冷门章节：模型导出时启用--save_inference=True+--export_format=onnx。但ONNX Runtime在WorkBuddy沙箱里也不受支持（需额外DLL）。

最后我找到PaddleOCR的tools/export_model.py，修改其导出逻辑：

# 不用官方导出，自己用paddle.jit.save python -c " import paddle from paddleocr import PPStructure model = PPStructure(table=False, ocr=True) paddle.jit.save(model, './exported/model', input_spec=[paddle.static.InputSpec(shape=[1,3,640,640], dtype='float32')]) "

生成的model.pdmodel只有18MB，且不含任何外部依赖。关键点在于：必须指定input_spec的固定shape（如640×640），不能用None。否则导出的模型在沙箱里会因动态shape推理失败。

验证方法：在本地用paddle.inference.Config加载导出模型，设置config.disable_glog_info()和config.enable_memory_optim()，再测内存占用。WorkBuddy沙箱等效于开启了所有内存优化选项，所以本地测试必须开同等配置。

4. 第三个坑：WorkBuddy 的“技能热更新”根本不存在，只有冷重启

4.1 你以为的“发布即生效”，其实是“发布即重建容器”

我第三个技能是Excel数据清洗。写完后，习惯性在控制台点“发布新版本”，以为用户马上能用。结果用户反馈：“还是旧版，没变”。我看控制台，版本号确实变了，状态是“已发布”。

查文档，说“发布后1分钟内生效”。等了10分钟，还是旧版。我怀疑缓存，清浏览器、换设备、换账号，全一样。

最后发现：WorkBuddy的Skill发布机制，是每次发布都创建全新容器实例，但旧实例不会立即销毁。平台有“滚动更新”策略：新实例启动成功后，流量才逐步切过去。而我的Excel技能有个致命问题——它在main.py顶层写了：

import pandas as pd df_template = pd.read_excel("template.xlsx") # 全局变量

df_template在容器启动时加载一次，之后所有请求共用。但新容器启动时，template.xlsx是旧版本；旧容器还在处理请求，用的也是旧模板。所以用户看到的，是新旧两个版本模板混用的结果。

根本原因：WorkBuddy没有提供“优雅停机”钩子（如pre_stop回调），你无法在旧实例退出前清理全局状态。所有“初始化一次”的逻辑，都必须重构为“每次请求初始化”。

修正方案：

def handle_event(event): # 每次请求都重新加载 df_template = pd.read_excel("template.xlsx") # ... 处理逻辑 return result

但这带来新问题：pandas.read_excel()每次调用都要解析xlsx，耗时200ms+。我试过用functools.lru_cache缓存，但沙箱里lru_cache的key是文件路径字符串，而Excel文件内容变了，路径没变，缓存永远不更新。

4.2 文件系统不是你的，是平台的——别想存中间文件

为提速，我尝试把Excel解析结果存到临时文件：

import tempfile with tempfile.NamedTemporaryFile(delete=False, suffix='.csv') as f: df.to_csv(f.name, index=False) cache_path = f.name

本地OK。上传后，日志报：

PermissionError: [Errno 13] Permission denied: '/tmp/tmpabc123.csv'

WorkBuddy沙箱的/tmp目录是可写的，但只允许创建文件，不允许删除或重命名。tempfile.NamedTemporaryFile(delete=False)生成的文件，后续os.remove()会失败。更糟的是，沙箱的/tmp是内存文件系统（tmpfs），容量上限128MB，存大文件直接满。

我改用io.BytesIO内存缓存：

import io buffer = io.BytesIO() df.to_csv(buffer, index=False) buffer.seek(0) # 直接用buffer.getvalue()或传给下游

但pandas.to_csv()在内存里生成的bytes，对10MB Excel会吃掉30MB内存，逼近沙箱红线。

最终方案：放弃缓存，拥抱流式处理。我把Excel解析拆成两步：

  1. 用户上传Excel → Skill只校验格式，返回“已接收，处理中”
  2. 后台异步任务（用WorkBuddy的background_taskAPI）真正解析 → 解析完发消息通知用户

WorkBuddy的background_task是唯一能绕过512MB内存限制的出口。它运行在独立容器，内存上限2GB，且支持time.sleep()和长时IO。但代价是：你得自己实现任务队列、状态查询、失败重试——WorkBuddy只提供create_task()和get_task_status()两个API。

4.3 “技能下架”不是删除，是封印——旧版本永远在线

我修复了Excel技能的缓存问题，发布v2.0。用户说“v1.0还有人用”。我去看控制台，v1.0状态是“已下架”。但日志显示，仍有请求打到v1.0实例。

问客服，回复：“下架仅停止新流量接入，已有连接保持1小时”。这意味着：WorkBuddy没有真正的“下架”概念，只有“流量切换延迟”。v1.0实例可能还在处理未完成的请求，甚至缓存着旧数据。

我遇到的真实案例：v1.0技能里有个硬编码的API密钥（API_KEY = "xxx"），v2.0已替换。但v1.0实例还在运行，且密钥泄露风险持续存在。我不得不手动登录服务器（WorkBuddy不提供SSH），用kill -9杀掉所有v1.0进程——但这违反平台协议，可能导致账号受限。

合规做法：所有敏感配置必须从代码移出，改用WorkBuddy的Secrets管理。在控制台创建Secret，代码里用：

import os api_key = os.getenv("WORKBUDDY_SECRET_API_KEY")

Secrets在发布新版本时自动注入，旧版本实例重启后会加载新值。但注意：Secrets不支持热更新，必须重启容器（即发布新版本）才生效。

经验总结：WorkBuddy的版本管理，本质是容器编排。所谓“技能”，就是一组Docker容器；所谓“发布”，就是docker pull新镜像；所谓“下架”，只是docker stop旧容器的软性指令。理解这点，你就明白为什么所有状态都该是无状态的——别信“下架”，信“重启”。

5. 第四个坑：那个让我删掉整个OCR项目的惨痛教训

5.1 不是模型不准，是WorkBuddy根本没给你“识别”的机会

第四个技能，我铁了心要做OCR，但目标降级：只识别固定格式的发票。我想，固定模板+规则引擎，应该比通用OCR简单。我用PaddleOCR检测文字框，再用正则匹配“金额：¥(\d+.\d+)”、“日期：(\d{4}-\d{2}-\d{2})”。

本地测试完美。上传后，用户上传发票图片，Skill返回空结果。日志里只有：

[INFO] OCR result: []

我加了debug日志，发现ocr.ocr()返回空列表。不是报错，是安静地返回空。我试了10张不同发票，全空。

查PaddleOCR源码，发现ocr.ocr()在检测不到文字框时，返回[]，不抛异常。而WorkBuddy沙箱里，cv2的cv2.dnn.readNetFromPaddle()加载模型时，如果输入图分辨率太低（<320px），会静默跳过检测——不是bug，是PaddleOCR的防错机制。

我的发票图是手机拍的，平均宽度800px，但部分图因拍摄角度被压缩到400px以下。PaddleOCR认为“太小，不值得检测”，直接返回空。

我加了预处理：

from PIL import Image img = Image.open("invoice.jpg") if img.width < 640: img = img.resize((640, int(img.height * 640 / img.width)), Image.LANCZOS)

上传，还是空。日志显示resize后宽度640，但OCR还是空。

最后，我用cv2.imread()读图，再cv2.imshow()看——沙箱里根本没有GUI，cv2.imshow()直接崩溃，但崩溃被沙箱捕获，静默忽略。我根本不知道图被读成了全黑。

真相是：WorkBuddy沙箱的OpenCV，不支持JPEG解码器。cv2.imread("invoice.jpg")返回None，但PaddleOCR的ocr.ocr()内部做了if img is None: return []，所以永远空。

验证方法：在main.py开头加：

import cv2 import numpy as np test_img = np.zeros((100,100,3), dtype=np.uint8) cv2.imwrite("/tmp/test.jpg", test_img) # 看能否写入 loaded = cv2.imread("/tmp/test.jpg") # 看能否读出 log("DEBUG", f"cv2 write success: {os.path.exists('/tmp/test.jpg')}") log("DEBUG", f"cv2 read result: {loaded is not None}")

结果：write success: True，read result: False。证实JPEG解码器缺失。

5.2 所有OCR方案，在WorkBuddy里都输给了同一个敌人：没有libjpeg

我试了所有替代方案：

  • Tesseract：pytesseract.image_to_string()→ 依赖libtesseract.so，沙箱无
  • EasyOCR：底层用torchvision.io.read_image()→ 依赖libpng/libjpeg，沙箱无
  • OCRmyPDF：调用gs命令 → 沙箱禁用子进程
  • 自研CNN：用PIL.Image.open()读图 → PIL的JPEG解码器是C扩展，沙箱禁用

所有路都被堵死。WorkBuddy沙箱的Python环境，是用musl libc编译的精简版，只保留最基础的图像解码能力（PNG、GIF），明确移除了JPEG、TIFF、WEBP支持——因为这些解码器依赖外部库，且有安全风险。

我查了WorkBuddy的python -m PIL输出：

--- PIL CORE --- ... jpeg: False tiff_little_endian: False webp: False ...

jpeg: False，四个字母，终结了所有OCR梦想。

5.3 放弃OCR不是认输，是转向更可靠的“结构化数据提取”

我删掉了整个OCR项目文件夹，重开了个新目录。既然图像识别走不通，就回归本质：WorkBuddy的用户要的不是“识别文字”，是“提取发票里的金额和日期”。而发票是结构化文档，有固定字段位置。

我改用PDF解析+坐标定位：

  • 用户上传PDF发票（非扫描图，是电子版）
  • 用pdfplumber提取所有文本及其坐标
  • 找到“金额”文字的y坐标，取同一行右侧的数字
  • 找到“开票日期”文字，取其后冒号后的日期字符串

pdfplumber是纯Python包，不依赖C库，且PDF文本坐标精准。测试100张电子发票，准确率99.2%。

关键代码：

import pdfplumber with pdfplumber.open("invoice.pdf") as pdf: page = pdf.pages[0] # 获取所有字符及其bbox chars = page.chars # 按y坐标分组（行） lines = {} for c in chars: y_round = round(c["y1"]) if y_round not in lines: lines[y_round] = [] lines[y_round].append(c) # 找“金额”所在行，取右侧数字 for y, line_chars in lines.items(): text = "".join([c["text"] for c in line_chars]) if "金额" in text: # 取同一行中x坐标更大的数字 nums = [c["text"] for c in line_chars if c["text"].replace(".", "").isdigit()] if nums: amount = nums[-1] # 最右的数字

这个方案不碰图像，不依赖OCR，完全在WorkBuddy沙箱能力范围内。它慢一点（PDF解析比OCR快，但比纯文本匹配慢），但稳得多。后来我把它包装成“发票助手”，成了4个上架技能里用户评分最高的一个。

我的体会是：在开放平台做开发，最大的陷阱不是技术难度，而是“路径依赖”。当你认定“必须用OCR”，就会在JPEG解码、内存优化、模型瘦身上无限投入，却忘了问一句：用户真正要的，是不是非得从图里抠字？有时候，换条路，不是妥协，是更聪明的抵达。

6. 四个技能背后的共同生存法则

6.1 WorkBuddy不是服务器，是“应用商店式沙箱”——设计思维必须切换

很多人把WorkBuddy Skill当成一个微型Web服务来写：启动时加载模型、缓存数据、监听请求。这是错的。WorkBuddy的Skill，更像iOS App——每次调用都是全新进程，没有持久化状态，没有共享内存，没有后台服务。它的设计哲学是：每个Skill调用，都该是原子的、幂等的、无状态的。

所以，我后来所有技能都遵循：

  • 绝不依赖全局变量：所有数据，从event里来，往return里去
  • 绝不写文件到磁盘：/tmp只读，/home不存在，所有中间数据用io.BytesIO或dict内存暂存
  • 绝不假设环境一致性：os.getenv("HOME")返回None，platform.system()返回"Linux"但内核是musl，sys.version是CPython但C扩展被阉割

一个检验标准：把你的Skill代码复制到一个全新的、没装任何包的Python虚拟环境中，只装requirements.txt里写的包，然后运行python main.py模拟一次调用。如果能跑通，它在WorkBuddy里大概率也能跑通。本地跑不通的，WorkBuddy里100%失败。

6.2 文档不是指南，是考古现场——你得自己拼出完整地图

WorkBuddy的官方文档，像一本残缺的古籍。API列表齐全，但每个参数的约束条件（如timeout_ms最小值、max_file_size上限、event_types可选值）散落在不同页面的脚注里；错误码列表有，但没写触发场景；沙箱限制（内存、CPU、网络、文件系统）只在FAQ角落提了一句。

我建了个本地知识库，记录所有踩坑：

  • event_types可选值：["message", "command", "file_upload", "background_task_complete"]
  • timeout_ms范围：1000~30000（低于1000被截断，高于30000被拒绝）
  • max_file_size：10485760字节（10MB），超限直接HTTP 400，不进Skill
  • /tmp容量：134217728字节（128MB），写满时报No space left on device

这些数字，全是从日志、报错、反复测试中抠出来的。没有捷径，只有实测。

6.3 “上架成功”不是终点，是运维起点——监控必须前置

四个技能上架后，我以为可以松口气。结果第二天，用户投诉：“发票助手有时返回空”。我看日志，发现是pdfplumber解析某些PDF时抛KeyError: 'x0'。原因是PDF用了特殊字体，chars里没有x0字段。

我立刻加了防御：

try: chars = page.chars except KeyError: # 降级用extract_text() text = page.extract_text() # 用正则找金额和日期 amount = re.search(r"金额[:：]\s*¥?(\d+\.\d+)", text)

但问题在于：这个KeyError在本地测试时从未出现，因为测试PDF都是标准Acrobat生成的。线上用户上传的PDF，来源五花八门。

所以，我所有Skill都加了错误分类上报：

import json import urllib.request def report_error(error_type, detail): data = { "skill_id": os.getenv("WORKBUDDY_SKILL_ID"), "error_type": error_type, "detail": detail[:200], # 截断防超长 "timestamp": int(time.time()) } req = urllib.request.Request( "https://api.workbuddy.com/v1/errors", data=json.dumps(data).encode(), headers={"Authorization": f"Bearer {os.getenv('WORKBUDDY_API_TOKEN')}"} ) try: urllib.request.urlopen(req, timeout=2) except: pass # 上报失败不阻塞主逻辑 # 在catch里调用 except Exception as e: report_error("pdf_parse_failed", str(e)) raise

WorkBuddy不提供错误监控，你得自己造。现在我的Dashboard上，实时显示各技能的错误率、TOP3错误类型、地域分布——这才是真正的“上架后”。

6.4 最后一条铁律：别和沙箱对抗，学着和它共舞

我见过太多开发者，在WorkBuddy上执着于“我要用TensorRT加速”、“我要挂载GPU”、“我要用最新版PyTorch”。结果呢？要么卡在审核，要么上线后崩。真正的高手，不是把本地环境搬上云，而是用沙箱给的积木，搭出最稳的塔。

  • 没有GPU？那就用PaddleOCR的CPU版，再配合分块处理。
  • 没有JPEG？那就只接PDF、PNG、文本文件，把“支持格式”写进技能描述。
  • 内存有限？那就用yield做流式处理，用del及时释放大对象，用gc.collect()主动回收。

WorkBuddy的沙箱不是牢笼，是滤网。它筛掉的是“想当然”的开发者，留下的是“懂约束”的建造者。我那四个上架技能，没有一个是靠“硬刚”做出来的，全是靠“绕行”、“降级”、“重构”、“妥协”——但最终交付给用户的，反而更可靠。

所以，如果你正准备做WorkBuddy Skill，别急着查“PaddleOCR怎么装”，先查“WorkBuddy沙箱支持哪些PIL解码器”；别急着写“OCR识别”，先问“用户要的真的是OCR，还是某个结构化字段”；别急着追求“最新版”，先验证“这个版本在沙箱里能不能import”。

毕竟，在开放平台的世界里，能上架的技能，不一定是技术最强的，但一定是和沙箱相处得最好的。