微智私域智能体（webuddy）
这是「微智私域智能体」的完整能力包。能力分两组：
| 能力组 | 提供方 | 覆盖 |
|---|---|---|
| 本机图片上传 | 本包（scripts/ 下的本地脚本） |
本机图片直传火山 TOS：SOP 配图 media_id、通用公网链接 |
| 业务能力 | MCP 服务端 https://ai.webuddy.top/mcp |
SOP 创建与下发、执行端设备、任务与周期规则、知识库检索 / 问 AI、私域数据看板 |
两组能力都用同一把凭证（见下），调用方无需区分。
> ⚠️ 本包只处理图片（jpg/png/webp/gif/bmp）。其他任何文件（安装包、zip、pdf、音视频等，
> 尤其 GB 级大文件）本包不提供上传通道，也不要去找旁路脚本 —— 直接告知用户「不支持该类文件上传」。
业务能力：从 MCP 获取
业务能力不在本包里实现，也不在本包里列工具清单——它们由 MCP 服务端提供，工具名、参数、说明
以服务端 tools/list 的返回为准。原因：服务端加/减工具、改参数，客户端零改动即可见，
技能包因此不需要、也不应该复制一份会过期的能力面。
- 端点：
https://ai.webuddy.top/mcp（streamable-http），已作为 MCP 连接器接入。 - 覆盖范围：SOP 创建与下发、执行端设备列表、任务与结果查询、周期规则（每天/每周定时）、
知识库检索与问 AI、私域数据看板。 - 想调业务能力时：直接调用对应的 MCP 工具；不确定有哪些工具就先用
tools/list看一眼。
数据看板（MCP 工具 dashboard_overview）
一次调用拿到整套私域经营指标，用于汇报经营状况、定位瓶颈层、生成运营建议。
结构：headline（私域用户资产价值 = 用户规模 × 健康度 × 变现效率，含 components）
+ kpis（好友总数 / 今日新增 / 窗口新增 / 会话数 / 消息数 / 任务数）
+ funnel（五层，每层一组 metric）+ trends（逐日新增好友数）+ pending（待完善清单）。
| 层 | 指标 | 数据状态 |
|---|---|---|
| ① 引流获客 | 新增好友数（今日 / 近 N 天） | real（执行端每日上报 wework_customer_stat） |
| ① | 加微率、获客成本 CAC | mock |
| ② 激活触达 | 触达率、已触达会话数、SOP 任务执行成功率 | derived（会话消息 + task 表推导） |
| ② | 内容打开率、入群率 | mock |
| ③ 留存互动 | 新客/活跃/沉睡/流失 分层数、活跃率、互动率、群活跃率、流失率 | derived |
| ③ | 次日 / 7 日 / 30 日留存率 | mock |
| ④ 转化成交 | 转化率、客单价、复购率、私域 GMV | mock |
| ⑤ 裂变传播 | 分享率、K 因子、转介绍率 | mock |
每个指标都带 status —— 转述时必须如实说明
| status | 含义 | 怎么讲给用户 |
|---|---|---|
real |
平台已采集的真实数据 | 直接当事实讲 |
derived |
由真实数据按明确口径推导（formula 字段写口径） |
讲数值 + 一句口径 |
mock |
平台暂无该数据源，返回占位值（placeholder: true） |
必须说明「这是待接入数据源的示意值」 |
硬纪律：status="mock" 的指标绝不能当作真实经营数据去分析结论或给建议。
pending 列表就是「待完善功能」清单，可以直接转述给用户。
占位值由 账号+指标+日期 确定性生成：同一天多次调用值不变，跨天缓慢演化，因此可以放心缓存/对比。
> 总指标 headline 的成色取最弱一环：变现效率（LTV/CAC）目前是占位值，所以
> 私域用户资产价值整体标 mock，即使它的用户规模是真实值、健康度是推导值。
> 汇报时必须说"这个资产额含占位因子、不能当真实金额"。等订单/成本数据接入后它会自动转为真实。
调用建议
- 汇报经营状况：
dashboard_overview（默认近 30 天趋势），必要时把pending里尚未接通的指标
一并说明，避免用户误以为"数据不准"。 - 只要汇总不要趋势：
include_trends=false（趋势序列有 30~90 条，省 token）。 - 看单台执行端：
device_id（先sop_device_list拿）。 - 回溯某天：
date="2026-09-25"。
为什么上传留在本地（互补，不是重复）
MCP 工具的参数是 JSON，服务端拿不到客户端的本地文件句柄；且按设计，文件字节从本机直连 TOS、
不经过业务服务器。所以「上传」这一步天然只能在本地做，其余业务步骤全部走 MCP。
凭证：只有一把 API Key
- 凭证是
sk-aim-v1-*开头的 API Key，无状态、无 TTL，不随网页登出或改密失效。 - 本包脚本与 MCP 的全部工具都用它；MCP 侧在
mcp.json的 headers 里配一个
"Authorization": "Bearer sk-aim-v1-..."即可（不再需要X-Session-Id）。 - 日志与回复中绝不展示完整 Key。
运行环境
- Python 解析顺序：
python3→python→ WorkBuddy 托管解释器
（Windows 下C:\Users\<user>\.workbuddy\binaries\python\versions\<ver>\python.exe）。 - 全部命令在 Skill 根目录执行，形如：
python scripts/aim.py <命令> [参数] --json。 - 无需 pip install，无第三方依赖。
- 环境变量：
AIM_OPS_BASE_URL覆盖站点（默认https://ai.webuddy.top）；AIM_OPS_CONFIG
覆盖凭证路径。
第一步：确认登录（每次会话必做）
- 运行
python scripts/aim.py whoami --json。 - 退出码 0 → 已登录，继续。退出码 3 → 未登录，执行登录：
- 首选python scripts/aim.py login：优先调用软件自带的浏览器，不行就弹开其他浏览器打开 ai.webuddy.top 官方授权页，
引导用户在页面登录并点「确认授权」；CLI 自动轮询取回凭证，用户无需复制粘贴。
明确告诉用户"会打开 ai.webuddy.top 官方页面"。
- 若服务端授权端点未上线（CLI 会提示 404）或用户不方便弹浏览器，改用
python scripts/aim.py login --manual，引导用户到站点用户中心复制sk-aim-v1-开头的 API Key。 - 凭证存于
~/.aim/credentials.json（0600），之后所有命令自动携带。
设备码登录的执行纪律（重要）
- login 会阻塞轮询最长 5 分钟（
--wait可调）。调用 shell 工具时必须把超时设为 ≥ 320 秒
（或用后台运行 + 稍后取结果），否则工具默认 2 分钟超时会误杀登录进程——这是"授权页刚打开就被放弃"的根因。 - 超时不是失败：5 分钟内用户没点确认，CLI 以退出码 3 返回
auth_wait_timeout并给出授权码。
此时正确动作是提醒用户尽快完成授权，用户确认后用
python scripts/aim.py login --code WD-XXXXX续等原授权码直接取回凭证（授权码服务器侧 10 分钟有效），
不要立刻重新 login 生成新页。 - 移动端 / 远程遥控会话（用户在手机上、浏览器开在桌面没人看）：加
--no-open，把 CLI 打印的
授权页 URL 和授权码直接发到对话里，请用户用手机浏览器打开，CLI 轮询会自动感知。
命令速查（本包脚本）
| 命令 | 用途 | 关键参数 |
|---|---|---|
login [--manual] |
登录授权 | --wait 秒（默认300）--code 续等 --no-open；manual 模式用 --api-key |
whoami |
登录状态（含 key_valid） |
— |
logout |
清除本地凭证 | — |
img upload <file> |
通用图片上传 → 公网 URL（不登记媒体库） | ≤10MB；--usage cover\|gallery\|sop（默认 sop） |
sop media <file> |
SOP 配图一条龙：TOS 直传 + 登记媒体库 → media_id | ≤1MB，jpg/png/webp |
统一约定：--json 时 stdout 只输出单行 JSON（优先用于解析）；诊断走 stderr；
退出码 0 成功 / 1 业务失败 / 2 参数错 / 3 未登录 / 4 网络或 5xx。
标准工作流（上传部分）
A. 给 SOP 配图（最常用）
python scripts/aim.py sop media <图片路径> --json逐张上传，拿media_id。
- 不要把外链 URL 传给这个命令——它只吃本机文件路径。
- 单张上限 1MB；超了先用本地工具压图。- 把
media_id逗号拼接，交给 MCP 里「创建 SOP」类工具的media_ids参数。
- 配图张数：单条建议 1–3 张，不要默认顶到 9 张。 服务端允许 1–9 张（第 10 张必被拒），
但执行端「下载 → 相册索引 → 选图」链路在张数多时实测会偶发失败（9 张实测 2 次挂 1 次）；
失败时执行端安全降级为只发文字（不会错选别的图）。需要更多图时拆成多条 SOP 分批发。 - 后续的创建与下发都由 MCP 完成。
B. 只要一个公网链接
- 图片（≤10MB）→
python scripts/aim.py img upload <路径> --json，返回url（public-read 长期有效）。 - 非图片文件本包不支持上传（无旁路脚本）：直接告知用户本包只处理图片；若确有必要，请用户另想办法。
硬约束
- 上传凭证是临时的：
/api/tos/upload_token签发的 STS2 凭证 1 小时失效（仅影响再次上传）；
已传文件的公网 URL 为 public-read，长期可访问（不随 STS 过期）。 - 桶是 public-read，不要传敏感文件。 用户要传身份证/合同/密钥这类东西时先提醒一句。
- 配图上限：
sop media单张 ≤1MB、jpg/png/webp；img upload≤10MB、含 gif/bmp。
media_from_url有 SSRF 白名单，只接受本站 TOS 桶/CDN 域名。 - 只支持图片：
sop media/img upload都只吃图片。非图片文件（zip/pdf/安装包/音视频，
尤其大文件）本包没有上传通道，也不要用别的方式绕过去 —— 直接回复用户「不支持」。 - 写操作用户确认：涉及对外发布/发消息的 MCP 工具，执行前必须向用户复述
「SOP 名称 + 目标设备 + 内容与时间」并取得明确确认。 - 看板指标不得张冠李戴：
dashboard_overview里status="mock"的指标是占位值，
汇报时必须说明"该指标数据源尚未接入"，不能当成真实经营数据下结论。 - 401 → 重新 login；403/400 把服务端中文 message 原样转述给用户，不自行编造原因。
- 接口细节与错误码见
references/api.md；异常排查见references/troubleshooting.md。
示例对话
用户："帮我给手机发个朋友圈 SOP：文案「新品上新，欢迎来撩」，配图用 D:\pics\new-product.jpg"
Agent：whoami --json → sop media D:\pics\new-product.jpg --json 拿 media_id →
调 MCP 的「执行端设备列表」工具选设备 → 复述"将向设备「门店1号机」下发朋友圈 SOP，文案：新品上新，欢迎来撩，
配图 1 张。确认？" → 用户确认 → MCP 的「创建 SOP」工具（带 media_ids）→ MCP 的下发工具 →
MCP 的任务等待工具 → "已发布成功（任务 #34 completed）"。
用户："把这 8 张活动照发到朋友圈"
Agent：先说明"单条塞 8 张执行端有偶发失败风险（实测 9 张约 50% 失败，失败会降级只发文字），
建议拆成 3 条各 3 张，或者按 8 张直接试、失败我帮你重试"；用户选定后逐张
sop media 上传 → 把 media_ids 交给 MCP 的创建/下发工具。
用户："把这个安装包 / 这个 2GB 的压缩包传上去，给我个下载链接"
Agent：说明本包只支持图片上传（sop media ≤1MB / img upload ≤10MB），非图片、尤其 GB 级文件
没有上传通道 —— 请用户换别的方式，不要自作主张找旁路。
用户："这张图我不想配到朋友圈，就要个链接"
Agent：python scripts/aim.py img upload D:\pics\a.jpg --json → 回复 url。
用户："刚才那个群发任务结果怎么样"
Agent：调 MCP 的「任务查询 / 任务等待」工具拿结果并复述给用户。
用户："我这个月私域做得怎么样？拉个数据看板"
Agent：调 MCP 的 dashboard_overview（近 30 天）→ 回复结构：
"近 30 天新增好友 1,240 人（今日 +58，真实上报）；好友总数 12,860；触达率 72.3%、
互动率 41.0%（口径：有消息往来的会话 / 全部会话）；分层：活跃 320 / 沉睡 180 / 流失 95。
⚠️ 另外——加微率、CAC、内容打开率、入群率、次日/7/30 日留存率、转化率、客单价、复购率、
私域 GMV、分享率、K 因子、转介绍率 这 14 项数据源还没接通，看板返回的是示意占位值，
先别用来做决策（要接的话告诉我接哪个数据源）。"
用户："转化率 3.2% 是不是太低了"
Agent：先纠正前提——"这个 3.2% 是待接入数据源的占位值，不是真实转化率，不能据此判断高低。
目前真实可用的只有新增好友数、触达/互动率、留存分层和任务成功率。"
