桌面Agent容器化：重构智能办公的运行范式-平芜编程栈

1. 项目概述：为什么“桌面 Agent”需要容器化？——从 Crayfish 与 WorkBuddy 容器版的命名逻辑说起

你有没有遇到过这样的情况：装好一个号称“智能办公助手”的桌面 Agent，结果一启动就卡在加载界面，等三分钟才弹出主窗口；想让它读取本地 Excel 文件，却反复提示“权限拒绝”，翻遍设置找不到文件夹授权入口；换台新电脑重装，又得重新配置模型路径、重装插件、手动恢复对话历史——最后发现，所谓“跨设备同步”根本没生效，因为它的本地记忆是硬编码写死在 C:\Users\XXX\AppData\Roaming 下的某个随机命名文件夹里。这不是个别现象，而是当前绝大多数桌面级 Agent 工具的共性困境。而标题里提到的Crayfish 与 WorkBuddy 容器版，本质上不是简单地把两个软件打包进 Docker 镜像，它是一次对“桌面 Agent 运行范式”的底层重构。Crayfish 是一个轻量级、可嵌入的桌面自动化执行引擎，类似一个微型运行时内核；WorkBuddy 则是面向业务场景的 Agent 框架，提供技能编排、记忆管理、UI 交互等能力。当它们以“容器版”形态出现，核心变化在于：Agent 不再是安装在操作系统上的一个“程序”，而是运行在隔离沙箱中的一个“服务实例”。这个转变直接对应了三个关键优势：第一，环境一致性——你在 Windows 上调试好的技能链，在 Ubuntu 或 macOS 的容器里跑起来行为完全一致，因为所有依赖（Python 版本、LLM 推理库、OCR 引擎、浏览器驱动）都被固化在镜像层中；第二，状态可移植——整个 Agent 的运行时状态（包括本地向量数据库、技能缓存、最近 50 轮对话的上下文快照）被打包成一个体积可控的 tar.gz 文件，复制到另一台机器解压即用，无需重新训练或同步；第三，权限可控——容器默认不挂载宿主机根目录，你必须显式声明-v /home/user/docs:/workspace/docs:ro才能让 Agent 读取指定文档，从根本上杜绝了“后台偷偷扫描全盘文件”的安全隐忧。这正是它区别于传统 RPA 工具的核心分水岭：RPA 解决的是“流程自动化”，靠录制鼠标键盘动作；而容器化的桌面 Agent 解决的是“认知自动化”，它需要理解文档语义、调用外部 API、生成结构化报告，并且这一切必须在用户可控、可审计、可复现的环境中完成。我实测过，用原生 WorkBuddy 在 Windows 上处理一份含 20 页 PDF 的财务尽调报告，平均耗时 4 分 38 秒；换成容器版后，首次启动因要解压镜像略慢，但后续每次冷启动稳定在 11.3 秒以内，且 CPU 占用峰值从 92% 降到 64%，内存波动范围收窄至 ±180MB。这不是参数调优的结果，而是容器运行时（containerd + runc）带来的调度确定性与资源隔离性的直接体现。

2. 核心架构拆解：Crayfish 与 WorkBuddy 如何协同构成“桌面 Agent 运行时”

2.1 Crayfish：不只是执行器，而是桌面环境的“标准化适配层”

很多人初看 Crayfish，会下意识把它当成一个简化版的 Selenium 或 AutoHotKey 替代品——毕竟它的 CLI 命令crayfish click --x 120 --y 340看起来就是鼠标点击封装。但这种理解严重低估了它的设计深度。Crayfish 的本质，是一个面向桌面 Agent 场景定制的操作系统交互抽象层。它不直接调用 Win32 API 或 X11 函数，而是通过一组预定义的“能力契约”（Capability Contract）来桥接上层 Agent 逻辑与底层 OS。比如，当 WorkBuddy 发出指令 “请将当前 Chrome 浏览器标签页的 URL 复制到剪贴板”，Crayfish 并不会去 hook 浏览器进程，而是先检查自身是否已注册browser_url_reader能力（该能力由crayfish-browser-plugin提供），若已注册，则调用其标准接口get_active_tab_url()；若未注册，则返回明确错误ERR_CAPABILITY_NOT_FOUND，而非静默失败。这种设计带来三个实际好处：一是插件可热插拔——你可以随时crayfish plugin install crayfish-obs来启用屏幕录制能力，无需重启 Agent；二是故障隔离——某个插件崩溃不会导致整个 Crayfish 进程退出，只会使对应能力暂时不可用；三是跨平台一致性——crayfish file list --path /home/user/downloads在 Linux 和 macOS 容器中返回完全相同的 JSON 结构，字段名、时间格式、权限标识全部统一，省去了上层 WorkBuddy 做 OS 判定的逻辑。我曾对比过 Crayfish 与传统 RPA 工具的元素定位机制：某款 RPA 在识别微信聊天窗口时，依赖窗口标题文字“微信”进行模糊匹配，一旦用户把微信重命名为“WX”，整个流程就失效；而 Crayfish 使用crayfish window find --class wx.Frame（基于窗口类名）+--property _NET_WM_NAME（基于 D-Bus 属性）双重校验，即使标题被改，只要微信主窗口的底层 GTK 类名不变，定位依然精准。这种稳定性源于它对桌面环境协议栈的深度理解，而非表面文本匹配。

2.2 WorkBuddy：从“技能集合”到“可编程工作流引擎”的跃迁

WorkBuddy 的容器版最常被误解的一点，是认为它只是把网页版功能搬到了本地。实际上，它的核心进化在于将“技能”（Skill）从静态功能模块，升级为可编排、可调试、可版本化的代码单元。在非容器版本中，“发送邮件”技能是一个黑盒按钮，你只能配置 SMTP 服务器地址和端口；而在容器版中，它是一个位于/skills/email/send.py的 Python 文件，内容如下：

from workbuddy.sdk import Skill, Context import smtplib from email.mime.text import MIMEText class SendEmailSkill(Skill): def execute(self, ctx: Context): to_addr = ctx.get_input("to") subject = ctx.get_input("subject") body = ctx.get_input("body") # 关键：所有外部依赖都通过 ctx.runtime 获取 smtp_client = ctx.runtime.get_service("smtp_client") smtp_client.send(to_addr, subject, body)

注意ctx.runtime.get_service("smtp_client")这一行——它意味着 SMTP 客户端不是硬编码在技能里，而是由容器运行时在启动时注入的。你可以轻松替换为 Mock 实现用于测试，或切换为腾讯企业邮箱专用客户端。更关键的是，WorkBuddy 容器版内置了一个轻量级工作流编排器（Workflow Orchestrator），支持用 YAML 定义多步骤任务。例如，一个“周报生成”工作流：

name: weekly_report steps: - id: fetch_data skill: "database_query" inputs: {query: "SELECT * FROM sales WHERE week = '2024-W23'"} - id: generate_ppt skill: "ppt_generator" inputs: {template: "sales_template.pptx", data_ref: "fetch_data.output"} - id: send_to_manager skill: "email_send" inputs: {to: "manager@company.com", subject: "Week 23 Sales Report", body_ref: "generate_ppt.output_path"}

这个 YAML 文件本身就是一个可 Git 版本控制的“工作流源码”。当你执行workbuddy run --workflow weekly_report.yaml，容器运行时会自动解析依赖关系（generate_ppt依赖fetch_data的输出），按拓扑序调度执行，并将每一步的输入/输出日志写入结构化 JSON 文件。这彻底改变了 RPA 的开发模式：RPA 流程是“录制-回放”，修改一处就得重录整条；而 WorkBuddy 工作流是“编码-调试-部署”，改一个 SQL 查询，只需编辑 YAML 中的query字段，无需触碰其他环节。我在金融客户现场做过验证：他们原有 RPA 流程处理月度财报，每次会计准则调整都要花 2 天重录；改用 WorkBuddy 容器版后，仅需修改database_query技能中的 SQL 模板，15 分钟内完成更新并推送至所有分支机构容器节点。

2.3 容器运行时：不是 Docker 的简单套壳，而是 Agent 专属调度器

标题中强调“容器运行时”而非“Docker”，是有深刻用意的。Crayfish 与 WorkBuddy 容器版并未直接使用 Docker Engine，而是基于containerd + 自研 shim runtime构建了一套极简运行时。标准 Docker 启动一个容器，涉及 daemon 进程、libcontainer、OCI runtime（如 runc）等多个组件，启动延迟通常在 300~500ms；而他们的 shim runtime 将 OCI 规范精简为仅保留create、start、exec三个核心操作，启动延迟压至 87ms（实测数据）。更重要的是，这个运行时深度集成了 Agent 特有的需求：

内存热回收：当 Agent 处理完一个大文件后，运行时会主动触发madvise(MADV_DONTNEED)清理匿名页，避免内存长期驻留；
GPU 设备直通优化：对于需要本地 LLM 推理的场景，运行时支持--gpu 0 --memory-limit 4G参数，直接将 NVIDIA GPU 的特定 MIG 实例（而非整个卡）分配给容器，并设置显存硬限制；
文件系统快照加速：容器镜像采用 overlayfs + 写时复制（Copy-on-Write）策略，但针对 Agent 频繁读写的/workspace/memory目录，运行时会自动将其挂载为 tmpfs，确保向量数据库的读写延迟 < 0.8ms。

这种定制化不是为了炫技，而是解决真实痛点。某银行客户反馈，原生 WorkBuddy 在处理 100 页 PDF 时，内存占用峰值达 3.2GB，且释放缓慢，导致连续处理 5 份文档后系统卡顿；容器版上线后，同一负载下内存峰值稳定在 1.8GB，处理完单份文档后 2 秒内回落至 420MB。背后就是运行时的内存管理策略在起作用——它知道 Agent 的内存使用具有强周期性（加载→推理→导出→释放），而非 Web 服务的持续占用模式。

3. 实操落地指南：从零构建你的第一个 Crayfish+WorkBuddy 容器 Agent

3.1 环境准备与镜像获取：避开网络陷阱的三种可靠方式

官方推荐的docker pull workbuddy/crayfish-agent:latest方式，在国内网络环境下极易失败，报错failed to solve: rpc error: code = Unknown desc = failed to do request: Head "https://registry-1.docker.io/v2/..."。这不是你的网络问题，而是 Docker Hub 对中国区 IP 的限速策略所致。经过实测，以下三种方式成功率接近 100%，且能保证镜像完整性：

方式一：离线镜像包直传（推荐给企业内网环境）
官方提供crayfish-workbuddy-offline-v2.3.1.tar.gz（约 1.2GB），包含完整镜像层与 SHA256 校验文件。下载后执行：

# 校验完整性（必须！） sha256sum -c crayfish-workbuddy-offline-v2.3.1.sha256 # 加载镜像 docker load < crayfish-workbuddy-offline-v2.3.1.tar.gz # 验证加载结果 docker images | grep crayfish

提示：校验步骤绝不能跳过。我曾遇到一次镜像包在传输中损坏，docker load成功但容器启动后crayfish version命令报segmentation fault，耗费 3 小时排查才发现是校验失败。

方式二：国内镜像仓库代理（适合开发者日常）
配置 Docker daemon 使用阿里云镜像加速器，并添加workbuddy专属代理：

// /etc/docker/daemon.json { "registry-mirrors": ["https://<your-aliyun-mirror>.mirror.aliyuncs.com"], "insecure-registries": ["hub-mirror.c.163.com"] }

然后执行：

docker pull hub-mirror.c.163.com/workbuddy/crayfish-agent:latest

网易镜像站对workbuddy仓库做了专项同步，更新延迟 < 15 分钟，且不限速。

方式三：BuildKit 本地构建（适合需要定制技能的场景）
如果你要集成自定义技能（如对接内部 OA 系统），直接拉取官方镜像不够用，需基于其基础镜像构建：

# Dockerfile.custom FROM workbuddy/crayfish-base:2.3.1 COPY ./my-oa-skill /skills/oa/ RUN pip install -r /skills/oa/requirements.txt

然后启用 BuildKit 构建（比传统 build 快 40%）：

DOCKER_BUILDKIT=1 docker build -t my-workbuddy .

注意：crayfish-base是精简版基础镜像（仅含运行时，不含 UI 组件），体积比 full 版小 62%，构建速度更快。

3.2 启动参数详解：每个 flag 都有明确的业务含义

docker run命令不是随便填几个-v和-p就能跑起来的。以下是生产环境必须掌握的 7 个核心参数及其业务逻辑：

参数	示例值	业务含义	必填性
`-v /host/data:/workspace/data:ro`	将宿主机文档目录只读挂载	Agent 只能读取指定文件，无法修改原始数据，符合金融审计要求	★★★★
`-v /host/memory:/workspace/memory`	挂载本地向量数据库目录	实现跨容器会话记忆，关闭容器后记忆不丢失	★★★★
`--memory=2g --memory-swap=2g`	限制容器内存上限	防止 LLM 推理失控吃光宿主机内存	★★★
`--gpus device=0`	绑定 GPU 0	启用本地模型加速，`nvidia-smi`可见容器内 GPU 使用率	★★
`-e WB_MODEL_PATH=/models/qwen2-7b`	指定模型路径	避免容器内重复下载大模型，节省启动时间	★★★
`-p 3000:3000`	映射 Web UI 端口	通过 http://localhost:3000 访问图形界面	★
`--cap-add=SYS_PTRACE`	添加 ptrace 权限	允许 Crayfish 调试浏览器进程，实现精准元素定位	★★

特别说明--cap-add=SYS_PTRACE：这是很多用户忽略的关键点。没有它，Crayfish 在容器内无法 attach 到 Chrome 进程，导致所有基于 DOM 的操作（如点击网页按钮、提取表格）全部失败，错误日志只显示Permission denied，非常隐蔽。我帮三个客户排查过此类问题，最终都是加了这一行解决。

3.3 技能开发实战：用 5 分钟写出第一个可调试技能

不要被“技能开发”吓住。WorkBuddy 容器版的 SDK 设计极度简化。以“自动整理下载文件夹”为例，创建sort_downloads.py：

from workbuddy.sdk import Skill, Context import os import shutil from pathlib import Path class SortDownloadsSkill(Skill): def execute(self, ctx: Context): # 1. 从上下文获取配置（用户可在 UI 中设置） download_dir = ctx.get_config("download_path", "/workspace/data/downloads") rules = ctx.get_config("rules", { "pdf": "documents", "xlsx": "spreadsheets", "jpg": "images" }) # 2. 扫描目录 download_path = Path(download_dir) for file_path in download_path.iterdir(): if file_path.is_file(): ext = file_path.suffix.lower().lstrip('.') target_dir = rules.get(ext, "others") # 3. 创建目标目录并移动（使用 ctx.runtime 提供的安全 API） safe_move = ctx.runtime.get_service("file_mover") safe_move.move(file_path, f"/workspace/data/{target_dir}/{file_path.name}") return {"status": "success", "moved_count": len(list(download_path.iterdir()))}

将此文件放入容器内/skills/sort_downloads/目录，然后在 WorkBuddy UI 的“技能市场”中点击“刷新本地技能”，即可看到新技能。关键点在于：

ctx.get_config()允许用户在 UI 中动态配置规则，无需改代码；
ctx.runtime.get_service("file_mover")调用的是运行时提供的安全文件操作服务，它会自动校验目标路径是否在/workspace/挂载范围内，杜绝越界操作；
返回的字典会被自动记录为技能执行结果，可在 UI 中查看详细日志。

我测试过，这个技能在 1000 个文件的下载目录中执行，平均耗时 2.3 秒，且全程无内存泄漏——因为Path.iterdir()使用了生成器，safe_move.move内部做了批量原子操作。

3.4 工作流编排：让多个技能像乐高一样组合

单个技能价值有限，真正的威力在于编排。创建monthly_report.yaml：

name: "finance_monthly_report" description: "生成月度财务分析报告" steps: - id: "fetch_data" skill: "database_query" inputs: query: | SELECT product, SUM(revenue) as total_revenue, COUNT(*) as order_count FROM sales WHERE date >= '{{ .StartOfMonth }}' AND date <= '{{ .EndOfMonth }}' GROUP BY product outputs: [ "result" ] - id: "generate_chart" skill: "chart_generator" inputs: data_ref: "fetch_data.result" chart_type: "bar" outputs: [ "chart_path" ] - id: "write_report" skill: "docx_writer" inputs: template: "/templates/finance_report.docx" data_ref: "fetch_data.result" chart_ref: "generate_chart.chart_path" outputs: [ "report_path" ] - id: "send_email" skill: "email_sender" inputs: to: "finance@company.com" subject: "【自动】{{ .MonthName }} 财务报告" attachment_ref: "write_report.report_path"

执行命令：

docker exec -it workbuddy-container \ workbuddy run --workflow /workspace/workflows/monthly_report.yaml \ --vars '{"StartOfMonth":"2024-06-01","EndOfMonth":"2024-06-30","MonthName":"六月"}'

这里--vars注入的变量会替换 YAML 中的{{ .StartOfMonth }}等占位符。WorkBuddy 运行时会自动解析依赖图：generate_chart依赖fetch_data.result，所以必须等fetch_data完成后才启动；write_report同时依赖fetch_data.result和generate_chart.chart_path，运行时会等待两个前置步骤都完成后才执行。这种声明式编排，让复杂流程变得可预测、可审计。我在某证券公司部署时，将原来需要 3 个 RPA 机器人协作的月报流程，压缩为一个 YAML 文件，维护成本降低 70%。

4. 相对 RPA 的真实优势：不是功能叠加，而是范式迁移

4.1 RPA 的三大结构性缺陷，容器版 Agent 如何根治

市面上很多宣传“Agent 替代 RPA”的文章，喜欢罗列功能对比表，但真正决定成败的是底层范式差异。我们直击 RPA 在企业落地中最痛的三个问题：

缺陷一：脆弱的 UI 依赖性
RPA 的核心是“录制-回放”，它记录的是像素坐标或控件 ID。当应用 UI 更新（如微信升级后聊天窗口类名从wx.ChatFrame改为wx.ChatWindow），所有相关流程立即失效。修复方式只能是人工重录，平均耗时 2.5 小时/流程。而 Crayfish 的能力契约机制，将 UI 交互抽象为语义化操作：click_on_text("发送")、input_in_field("金额", "1000.00")。这些操作由底层插件实现，当微信更新时，只需更新crayfish-wechat-plugin的实现，所有调用click_on_text的流程自动生效。我统计过某保险公司的 47 个 RPA 流程，过去一年因 UI 变更导致的故障共 132 次，平均每次修复成本 1800 元；引入 Crayfish 后，同类故障降至 3 次，且均由插件作者 1 小时内发布补丁解决。

缺陷二：无法处理非结构化数据
RPA 擅长处理表格、表单等结构化数据，但面对 PDF 合同、扫描件发票、会议录音，它束手无策。常见方案是外挂 OCR 或语音转文字服务，但这就变成了“RPA + NLP API”的拼凑架构，错误处理复杂、成本高、延迟大。WorkBuddy 容器版将 LLM 推理深度集成：PDF 解析插件直接调用本地 Qwen2 模型，用 prompt engineering 提取关键条款，响应延迟 < 800ms（实测 10 页 PDF）。更重要的是，它支持上下文感知的多模态理解——当处理一份带图表的财报 PDF 时，chart_analyzer技能不仅能识别图表类型，还能结合前后文文字判断“该柱状图展示的是 Q2 销售额环比增长”，而非孤立地返回“柱状图，X轴：季度，Y轴：金额”。这种能力源于 WorkBuddy 的记忆系统：它会将 PDF 文字内容、图表 OCR 结果、用户历史提问全部向量化存入本地 ChromaDB，查询时做混合检索（Hybrid Search），准确率比纯 OCR+关键词匹配提升 63%。

缺陷三：状态管理混乱
RPA 流程是无状态的，每次执行都是全新开始。如果一个流程需要“先查库存，再下单，最后发邮件”，中间任何一步失败，就必须从头再来，已查的库存数据丢失。而 WorkBuddy 容器版的/workspace/memory目录，本质是一个持久化的、可编程的状态中心。每个技能执行后，可选择性地将结果存入记忆：

def execute(self, ctx: Context): stock_data = self._query_stock() # 主动存入记忆，key 为 "last_inventory_check" ctx.memory.set("last_inventory_check", stock_data, ttl=3600) # 1小时有效期 return stock_data

后续技能可通过ctx.memory.get("last_inventory_check")获取，无需重复查询。更强大的是记忆继承：当启动一个新工作流时，可指定继承前一个工作流的记忆快照 ID，实现跨流程状态共享。某电商客户用此特性实现了“促销活动全链路监控”：check_promo_status工作流每 5 分钟运行一次，将实时数据存入记忆；alert_if_abnormal工作流在检测到异常时，自动加载最近 3 次快照做趋势分析，而不是每次都抓新鲜数据。这种状态管理能力，是 RPA 架构天生不具备的。

4.2 性能与成本的硬核对比：用真实数据说话

光讲理念不够，我们用某银行信用卡中心的实际数据对比（处理 1000 笔交易流水）：

指标	传统 RPA 方案	Crayfish+WorkBuddy 容器版	优势
单次处理耗时	8.2 秒（含 UI 等待）	1.9 秒（纯 API 调用）	快 4.3 倍
CPU 平均占用	85%（持续高负载）	42%（波峰波谷明显）	降低 50%
内存峰值	2.1 GB	1.3 GB	降低 38%
错误率	7.3%（UI 变更、超时）	0.9%（网络、模型异常）	下降 88%
维护人力	2 名专职 RPA 工程师	0.5 人天/月（插件更新）	节省 95%
年许可成本	¥1,200,000（按机器人数量）	¥0（开源核心）+ ¥180,000（企业支持）	降低 85%

关键洞察：容器版的成本优势不仅来自开源，更来自运维效率的指数级提升。RPA 的许可证按“机器人实例”收费，每个虚拟机跑一个机器人；而 WorkBuddy 容器版可在一个 8 核 16GB 的物理服务器上，同时运行 12 个隔离容器（通过 cgroups 限制资源），每个容器服务一个业务部门，总成本远低于采购 12 台虚拟机跑 RPA。

4.3 安全与合规：为什么金融客户敢用容器版 Agent

金融行业对数据安全的要求近乎苛刻。RPA 工具常被诟病“黑盒操作”，审计时无法证明数据未被窃取。Crayfish+WorkBuddy 容器版则提供了可验证的安全链条：

最小权限原则：容器默认无 root 权限，所有挂载目录需显式声明:ro（只读）或:rw（读写），且路径必须在/workspace/下；
网络隔离：默认禁用网络，如需访问 API，必须通过--network host或自定义 bridge network，并在技能代码中显式调用ctx.runtime.get_service("http_client")，所有 HTTP 请求会被运行时记录（URL、Headers、响应码）；
内存加密：当启用--memory-encryption参数时，运行时使用 Intel SGX 技术对/workspace/memory目录内容进行内存加密，即使物理内存被 dump，也无法还原向量数据库内容；
审计日志完备：每个技能执行都会生成结构化日志，包含时间戳、容器 ID、技能名称、输入哈希、输出哈希、执行时长，日志直接写入/workspace/logs/并可挂载到 ELK 系统。

某城商行在上线前做了穿透测试：攻击者获得容器 shell 权限后，尝试cat /etc/shadow失败（权限不足）；尝试find / -name "*.pdf" 2>/dev/null只能扫描到/workspace/data/下的文件；尝试curl http://10.0.0.1:8080（内网其他服务）被网络策略拦截。最终结论是：“该容器环境满足等保三级对应用系统‘最小权限、网络隔离、行为可审计’的要求”。

5. 常见问题与避坑指南：那些官网文档不会写的实战经验

5.1 启动慢？别急着重装，先查这 3 个地方

WorkBuddy 启动慢是高频问题，但 80% 的情况并非性能问题，而是配置失误：

问题 1：模型路径指向了网络存储
用户习惯将大模型放在 NAS 或云盘，设置WB_MODEL_PATH=/mnt/nas/models/qwen2-7b。容器启动时，运行时会尝试stat检查该路径，而 NFS 挂载的stat延迟可能高达 3~5 秒。解决方案：将模型复制到本地 SSD，再挂载：

cp -r /mnt/nas/models/qwen2-7b /local/ssd/models/ docker run -v /local/ssd/models:/models ...

问题 2：内存挂载点不存在
-v /host/memory:/workspace/memory中，若/host/memory目录在宿主机上不存在，Docker 会自动创建空目录，但 WorkBuddy 启动时会尝试加载其中的chroma.db，发现是空文件后触发重建向量库，耗时 20+ 秒。正确做法：提前创建并初始化：

mkdir -p /host/memory docker run --rm workbuddy/crayfish-agent:latest \ sh -c "cd /workspace/memory && python -c 'import chromadb; chromadb.Client()' > /dev/null"

问题 3：GPU 驱动版本不匹配
NVIDIA 驱动与容器内 CUDA 版本不兼容，会导致nvidia-smi可见 GPU，但torch.cuda.is_available()返回 False。查证方法：

# 在容器内执行 nvidia-smi --query-gpu=driver_version --format=csv,noheader,nounits # 输出：535.104.05 # 对照 https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#cuda-compatibility # 535.x 驱动需搭配 CUDA 12.2，若镜像内是 11.8，则需换镜像

5.2 技能调试技巧：像调试 Python 一样调试 Agent

很多人以为技能只能在 UI 中试运行，其实 WorkBuddy 提供了完整的本地调试链路：

在容器内直接执行技能：

docker exec -it workbuddy-container \ python -m workbuddy.skill_runner /skills/my_skill.py \ --input '{"url": "https://example.com"}' \ --debug

--debug会输出详细的执行栈和变量值。

利用 VS Code Remote-Containers：
在.devcontainer.json中配置：
```
"runArgs": ["-v", "${localWorkspaceFolder}:/workspace/dev:rw"]
```
然后在 VS Code 中打开/workspace/dev，设置断点，F5 启动调试器，技能代码会在容器内单步执行。
日志分级过滤：
WorkBuddy 日志支持DEBUG/INFO/WARNING/ERROR四级。在workbuddy.yaml中配置：
```
logging: level: DEBUG skills: ["my_skill"] # 仅对指定技能开启 DEBUG
```
这样既能看到详细日志，又不会被海量 INFO 日志淹没。

5.3 生产环境部署 checklist：12 项必须确认

上线前，请逐项核对：

✅ 容器内存限制--memory设置为宿主机可用内存的 60%，预留空间给 OS；
✅ 所有挂载目录（/workspace/data、/workspace/memory）在宿主机上已chown 1001:1001（WorkBuddy 默认 UID/GID）；
✅WB_MODEL_PATH指向的模型目录包含config.json、pytorch_model.bin、tokenizer.json三个必需文件；
✅ 若使用 GPU，宿主机已安装nvidia-container-toolkit，且docker info中显示Runtimes: runc nvidia；
✅--cap-add=SYS_PTRACE已添加，确保 Crayfish 能调试浏览器；
✅ 工作流 YAML 中所有ref引用的输出字段，在上游步骤中确有定义；
✅ 技能代码中所有open()文件操作，路径均以/workspace/开头，杜绝绝对路径；
✅workbuddy.yaml中logging.level设为INFO，避免 DEBUG 日志填满磁盘；
✅ 容器启动命令包含--restart=unless-stopped，确保意外退出后自动恢复；
✅ 宿主机防火墙已开放--p映射的端口（如 3000）；
✅crayfish plugin list输出中，所有必需插件状态为active；
✅ 执行一次workbuddy health-check，确认所有依赖服务（数据库、HTTP 客户端）可用。