定位

复用 WorkBuddy 宿主（桌面壳 / 多模型接入 / 文件系统访问），把现有 zfl- 技能编排成「一句话进、自动路由」的桌面办公智能体。

对标但不克隆：覆盖办公小浣熊的核心办公能力（数据分析、PPT、多格式文档、本地直读、浏览器自动化、token 预算与模型路由），但商标 / UI / 模型权重一概不碰，技术完全自有。

为什么不复刻独立 exe 壳：WorkBuddy 本身就是桌面壳，全局唤起、选区处理、文件访问、多模型接入它全有。另写 Electron/Tauri 是重复造轮子——真要脱离 WorkBuddy 分发再说。

能力路由表

深度能力编排（router.py）

scripts/router.py 是确定性路由层（不依赖 LLM），实现「探测先于调用」契约（借鉴 zfl-skill-governance）：

1. 意图识别：关键词启发式多命中计分，大小写不敏感。
2. 依赖探活：自建 zfl- 技能检查 ~/.workbuddy/skills/<name>/SKILL.md 是否存在；通用 Python 流探测对应库是否可 import。
3. 优雅降级：首选缺失 → 降级到内置技能 / 通用流，并写入 degradations[] 可见可追溯。
4. 模型档位：每个意图映射到 simple/medium/complex，供 tokenplan 选模型。
5. 降级落盘：--record 把每次路由结果（含 degradations）写入 data/router_log.jsonl，供 dashboard 聚合出趋势。

识别意图并路由（含探活 + 降级结论）

联动 tokenplan 拿具体推荐模型

结构化 JSON 输出（供上层编排消费）

落盘本次路由（降级历史，给看板用）

当前探活结果（本机）：zfl-pdf-toolkit / zfl-ppt-studio / zfl-ocr-helper 已装 → 直路由；数据分析依赖 pandas（本机需 pip install pandas openpyxl 后可用，router 会如实报「依赖未就绪」而非硬崩）。

执行后端分层（BackendTier）

复用「Agent 配电脑」哲学——每个意图选最轻够用的执行后端，不无脑起重环境：

• isolate：纯标准库、零启动开销（如 token 成本脚本）
• managed：跑带 pandas/openpyxl/docx 等第三方依赖的脚本（宿主受管运行时）
• container：需 Docker 的完整环境（本套件当前场景未触发，预留档）

router.py 在 INTENTS 为每个意图标了 backend 档位，resolve() 调 zfl-common 的 BackendRouter.select() 选档并做探测先于调用 + 优雅降级（与 router 现有「探测先于调用」契约同构），结果写入路由 JSON + router_log.jsonl（backend / backend_degradation 字段）。dashboard 据此出「执行后端分层分布」环图 + 轻后端占比 KPI。

> SSOT：zfl-common/scripts/exec_backend_tier.py + references/exec_backend_tier.md。升级 / bug 修复以 zfl-common 为准。

使用方式

直接说需求，套件识别意图并路由。例如：

• 「分析这个 Excel 的销售趋势，出份报告」
• 「把这份 Word 总结成 PPT」
• 「提取这个 PDF 第 3-5 页」
• 「抓一下这个网页的报价表」
• 「这个任务用哪个模型划算」（→ tokenplan route）

多模型接入

见 references/model-setup.md。套件不绑定模型，走 WorkBuddy 自定义模型设置接入商汤日日新 / DeepSeek / 混元等。

tokenplan（成本预算 + 模型路由策略）

见 scripts/tokenplan.py。两部分：① 成本预算（记录 token 消耗、设预算上限、出用量报告）；② 模型路由策略（按任务复杂度自动选模型 + 预算不足自动降级 + 映射可配置）。

成本预算

模型路由策略

路由分三档：simple（走最便宜模型，如 deepseek-chat）/ medium（deepseek-reasoner）/ complex（强模型，如 sensenova-pro）。复杂度由任务文本的关键词 + 长度启发式判定（命中"分析/趋势/图表/报告/excel"等升档，长文本也升档）。

预算感知降级：预算剩余比例低于阈值（默认 0.2）时，非 simple 任务自动降级到最便宜模型，避免超支——route 会明确标注降级原因。

可配置：映射与阈值持久化在 data/routes.json，用户可用 routes --set / routes --threshold 覆盖默认，无需改代码。

可视化看板（dashboard.py）

把「编排健康监测」可视化——这是 desk-agent 反哺治理器（zfl-skill-governance）的具体落地：router 的 degradations[] 降级记录 + tokenplan 的成本数据，聚合成 zfl-audit-charts 的 ops 契约，出一张自包含 HTML 看板。

• 降级趋势：按日期统计路由次数 vs 降级次数（折线）
• 能力可用性分布：可用 / 降级·依赖缺失 / 不可用（环图）
• 模型成本分布：按模型聚合 token 费用（环图）
• 意图路由分布：各意图被路由的次数（柱图）
• 执行后端分层分布：isolate / managed / container / 无档位（环图）
• KPI：路由总次数、降级占比（评分环）、完全不可用次数、近 N 天 token 成本、token 任务数

router 每次真实路由都落盘降级历史（在编排流程中加 --record）

出看板（聚合 router_log + tokenplan 历史，调 zfl-audit-charts）

当前环境能力探活快照（不污染历史，适合首次查看能力地图）

仅生成 ops JSON 不调图表（审计/调试用）

依赖 zfl-audit-charts（已加入 dependencies）；看板 HTML 默认落在 data/desk_dashboard.html，原生 Canvas 渲染、离线自包含。

桌面唤起 / 选区处理

见 templates/invoke-templates.md。Ctrl+K 式全局唤起、选中内容一键处理，用 WorkBuddy 宿主能力封装成可复用指令模板。

约束与错误处理

• 路由遵循「探测先于调用」：首选技能缺失时必须降级到内置流并记录 degradations[]，不得硬崩或静默假成功。
• 执行后端选最轻够用档（isolate/managed/container），不无脑起重环境；后端探活失败按降级链逐级回退。
• 预算感知降级：token 剩余 <20% 时非 simple 任务自动降档，必须在输出中标注降级原因，不得无声降本。

示例

场景：用户说「分析这个 Excel 的销售趋势，出份报告」，桌面办公智能体需自动识别意图、探活依赖、选模型档位并落盘路由日志。

执行步骤：
1. 意图识别：关键词命中「分析/Excel/趋势/报告」→ 映射到 data_analysis 意图（复杂度 medium）。
2. 依赖探活：检查 pandas / openpyxl 可 import；若缺失则降级到内置 xlsx 流并写入 degradations[]。
3. 选执行后端：data_analysis 映射到 managed 档（需 pandas），由 BackendRouter.select() 选最轻够用档。
4. 模型路由：medium 档 → deepseek-reasoner；查 tokenplan 预算，剩余 <20% 则降级到 cheap 模型并标注原因。
5. 落盘 + 看板：--record 写 data/router_log.jsonl；dashboard.py 聚合后出降级趋势 + 意图分布 HTML 看板。

实际命令形态（<skills_root> 为技能根目录占位符）：

# 1) 识别意图并路由（含探活 + 降级结论，输出结构化 JSON）
python <skills_root>/zfl-desk-agent-dev/scripts/router.py "分析这个Excel的销售趋势出份报告"

# 2) 落盘本次路由（降级历史，供看板聚合用）
python <skills_root>/zfl-desk-agent-dev/scripts/router.py "把这份Word总结成PPT" --record

# 3) 出编排健康度看板（聚合 router_log + tokenplan 成本，调 zfl-audit-charts）
python <skills_root>/zfl-desk-agent-dev/scripts/dashboard.py

自检与成功标准

• 成功标准：输出满足任务声明的全部要求，关键信息完整无遗漏，视为完成。
• 输出前自检：核对输出是否覆盖全部要求项、数据是否准确、格式是否符合规范。