HeavySnail 智能体接入说明

第一版 · 2026-11-01 · 适用于内部成员

一、这是什么，能帮你做什么

在你的 WorkBuddy 里加一个连接，之后你可以像问同事一样问项目上的事，它直接查我们的项目库回答你，不用再翻群消息、翻表格、问别人。

它按你的账号权限回答：你能看到哪些项目、哪些产品，它就只答这些范围内的内容。

举几个实际能问的：

GGZ3281240 这个柜现在什么状态，到哪一步了？
这个项目现在有几个柜已放行、几个还在等装船？
B5-22 这批货走到哪了？
我这个项目现在有什么待办？
瓷砖 612H19 一共多少托，分在几个柜里？
报关和清关分别要哪些单据，口径是什么？

二、三步接入（约 5 分钟）

第 1 步：打开配置文件

WorkBuddy 的连接配置在一个 JSON 文件里：

系统	文件位置
macOS	`~/.workbuddy/mcp.json`
Windows	`C:\Users\<你的用户名>\.workbuddy\mcp.json`

地址里的 .workbuddy 是隐藏文件夹。macOS 在访达里按 Command + Shift + G，粘贴 ~/.workbuddy 回车即可进入。

第 2 步：把给你的那段配置合并进去

给你的文件叫 mcp-配置.json，内容形如：


{
  "mcpServers": {
    "heavysnail": {
      "type": "streamableHttp",
      "url": "https://mcp.heavysnail.com/api/mcp",
      "headers": {
        "Authorization": "Bearer 你的专属凭据"
      },
      "timeout": 30000,
      "disabled": false
    }
  }
}

分两种情况：

文件不存在（第一次配）：直接把整段内容存成 mcp.json，放到上面那个位置。
文件已存在（里面可能已有别的连接）：不要整体覆盖。只把 "heavysnail": { ... } 这一段加到 "mcpServers": { } 里面，并在相邻两项之间补一个英文逗号。

合并后大概长这样：


{
  "mcpServers": {
    "已有的一项": {
      "...": "..."
    },
    "heavysnail": {
      "type": "streamableHttp",
      "url": "https://mcp.heavysnail.com/api/mcp",
      "headers": {
        "Authorization": "Bearer 你的专属凭据"
      },
      "timeout": 30000,
      "disabled": false
    }
  }
}

第 3 步：完全退出 WorkBuddy，再打开

不是关窗口，是退出应用（macOS Command + Q；Windows 在托盘图标上右键退出）。配置只在启动时读取。

重开后，如果左侧「连接器」里看到 heavysnail 是关闭状态，把它打开——部分版本需要手动启用一次。

然后新建一个对话，问一句：

帮我看看 GGZ3281240 这个柜现在什么状态

能答出来，就通了。

三、自检：怎么确认真的通了

在对话里直接问：

你能用哪些工具？

正常情况下会列出 6 项能力：

工具	作用
`hs_workspace`	看你能访问的项目、当前业务版本与协作边界
`hs_todos`	看你名下的待办
`hs_rules`	读当前规则与字段口径
`hs_query`	查货物、柜、订单行、质检、问题、装载计划、出入库等事实
`hs_validate`	校验一份草稿是否符合当前规则（不提交）
`hs_receipt`	查一次操作的受理回执

如果列出的比 6 项多（比如还出现 hs_submit、hs_task_*），不是问题——这些是程序的完整清单，你的账号调用它们会被直接拒绝。你的实际权限就是那 6 项。

四、边界（请务必知道）

这是内部工作通道，规则很明确：

只读。 不能改数据、不能提交、不能审批、不能对外发送任何东西。要改动，走原来的流程找负责人。
看得到的范围由你的账号决定。 管理岗看整个项目；跟单岗只看到你负责的那几个产品。查不到不是故障，是权限。
价格、成本、付款条件不在可查范围内。 系统本来就不把这些放进可查字段。
这份配置是你的钥匙。 里面的 Bearer 后面那串就是你的身份，不要贴到群里、不要发给别人、不要写进公开文档。如果怀疑泄露了，告诉王松，立刻换发。
答案以系统里的记录为准。 它答的是"系统里记的"，不是"实际发生的"。放行不等于装船，计划不等于实收——这类判断仍要看单证与人。

五、常见问题

问不出东西，只说"Access denied" 你的账号没有该动作或该项目的权限。跟单岗问别的产品、或问未授权的项目，都会是这个结果。

提示"机器身份无效、已过期、已撤销或不在当前授权范围内" 凭据到期或被撤销了。找王松重新签发一份，替换掉 Authorization 那一行即可。

连接器列表里有 heavysnail，但是灰的 / 没启用 在「连接器」里手动打开开关，然后重开对话。

看不到任何工具，或者 WorkBuddy 提示连接失败 八成是 JSON 格式问题。检查三处：引号是不是英文引号、相邻两项之间有没有逗号、最后一项后面不能多逗号。改完仍不行，把文件内容发给王松（先删掉 Bearer 后面那串）。

能问项目，但查不到某个产品 那个产品不在你的授权范围内，或者它还没进项目库。后者找对应负责人补录。

答的内容和你知道的不一致 先看 hs_query 返回的 businessVersion——那是这条答案对应的业务版本。版本对不上说明系统里有更新的记录。仍不一致就报给王松，别自己改。

六、有效期与续期

本批凭据到期日：2027 年 1 月 30 日
到期前一周会统一换发，你只需要替换 Authorization 那一行，其余不动
需要提前撤销或换发，直接找王松

七、想自己看门户

浏览器打开 https://mcp.heavysnail.com/collaboration/，用你的账号和独立口令登录，可以看项目视图与自己的接入状态。

说明：本阶段的凭据由管理员统一签发，你不需要在门户里自己创建。门户里那条"创建凭据"是给以后自助开通用的。