WorkBuddy本质是嵌入企业内部Web系统的轻量级交互代理，非独立CLI或桌面应用；其初始化端点需手动拼接路径（如/workbuddy/init或/api/v2/workbuddy/start），失败常见于租户上下文缺失、调用频控或域名未白名单；首次消息发送前必须传入隐式参数context.app_version（前端构建版本号）和context.user_role（整型权限码），且首条消息会触发静默上下文预热，依赖完整浏览器环境。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WorkBuddy不是传统意义上的 CLI 工具或独立应用，它本质是一个嵌入在企业内部 Web 系统中的轻量级交互代理。所谓“五分钟完成初次交互”，关键不在于安装或启动，而在于绕过文档陷阱、直连可用入口。
怎么找到真正的 WorkBuddy 初始化端点？
多数团队把 WorkBuddy 挂在内部中台系统某个子路径下，但导航菜单常标为“智能助手”“工作小帮手”等模糊名称，且默认不展示初始化按钮。
实操建议：
- 打开中台首页后，直接在浏览器地址栏末尾追加
/workbuddy/init（注意不是/workbuddy/）； - 如果返回 404，尝试
/api/v2/workbuddy/start—— 这是新版鉴权后才暴露的真入口； - 若仍失败，检查 Network 面板里页面加载时是否发出过含
workbuddy_session的请求头，那个请求的endpoint就是真实初始化地址。
init() 调用失败时最常见的三个响应体
调用成功返回的是 { "session_id": "wb_xxx", "status": "ready" }；失败则往往卡在这三类错误上：
-
{"error": "missing_tenant_context"}：说明当前登录账号没绑定租户 ID，需联系管理员在 IAM 后台补全tenant_id字段； -
{"error": "rate_limit_exceeded", "retry_after": 60}：不是你操作快，而是该账号过去 5 分钟内被其他前端页面静默调用过init()，需清空 localStorage 里的workbuddy_last_init时间戳再试； -
{"error": "invalid_origin"}：当前域名不在白名单，比如你从dev.internal.company.com访问却配置了只允许app.company.com，得让运维更新WORKBUDDY_ALLOWED_ORIGINS环境变量。
第一次发消息前必须设置的两个隐式参数
WorkBuddy 的 sendMessage() 看似只要传 text，但底层会校验两个未文档化的字段，缺一不可：
启用该技能，可以在WorkBuddy对话页的右边栏添加一个日历，提供月历视图、日程增删改查、分类标签（开庭/会议/截止日期/个人/研究/其他），支持从对话中提取事件并自动同步到日历。当用户提到"日历""日程""打开日历""添加日程""我的日程""calendar""安排"或询问已记录的日程信息时使用。
-
context.app_version：必须是当前中台前端的构建版本号（如"2.14.3"），硬写"latest"或空字符串会触发422 Unprocessable Entity； -
context.user_role：不是用户角色名（如"admin"），而是后端分配的整型权限码（常见值为101普通员工、205技术负责人），这个值通常藏在登录后返回的 JWT payload 里叫role_id。
为什么发第一条消息总卡在 “thinking…”？
这不是网络延迟，而是 WorkBuddy 在首次交互时强制执行一次上下文预热：它会同步拉取当前用户近 3 天的 Jira ticket 标题、Confluence 最近编辑页摘要、以及所在项目组的 Slack 频道关键词表 —— 全部走内部 RPC，不走浏览器缓存。
实操建议：
- 如果等超过 8 秒还没响应，打开 DevTools 的 Network 面板，过滤
rpc/workbuddy/warmup，看是否卡在某个下游服务超时； - 跳过预热的唯一办法是手动在
localStorage写入workbuddy_warmup_complete: "true"，但后续若提示 “context stale”，就得删掉重来； - 别用
curl或 Postman 测接口 —— 预热依赖完整的 Cookie + SameSite=Lax 上下文，脱离浏览器环境必然失败。
真正卡住人的从来不是代码怎么写，而是初始化阶段那些没报错、也不提示、但死活不往下走的静默依赖。比如 context.app_version 错一位数字，或者 tenant_id 是字符串却传了数字类型——这些都不会抛 JS 异常，只会让整个 session 停在 pending 状态。
