WorkBuddy 连接器使用说明

这是什么

WorkBuddy（AI 工作台）可通过 MCP（Model Context Protocol）直连 EDH 数据空间，在对话中完成：读取空间资源 → 把设备通讯协议转换为产品物模型 → 保存到你的数据空间，全链路留痕（space_usage 中 deviceType=mcp）。

连接凭证是 API 密钥（edhak_ 开头），永久有效、可随时吊销——不需要反复登录换取 7 天有效的登录 token。

前置条件

项	要求
账号	任一 EDH 平台账号（密钥权限 = 该账号本人全部空间）
服务端	edh-cloud 已部署 mcp 容器（/mcp 端点可访问）
环境	生产 https://edatahub.cn/mcp；测试 https://edatahub.cn:8088/mcp

三步接入

第 1 步：创建 API 密钥（Web 端）

登录 EDH 平台 → 数据空间 → 空间详情 → 「API 密钥」页签 → 创建密钥，输入名称（如 workbuddy）→ 确认后立即复制弹窗中的明文密钥。

⚠️ 明文仅此一次展示（服务端只存 SHA-256）。关掉弹窗后丢失只能吊销重发。

第 2 步：配置 WorkBuddy 连接器

方式 A（推荐）：WorkBuddy → 连接器管理 → 自定义连接器，添加 MCP 服务器：

• URL：https://edatahub.cn/mcp
• 请求头：Authorization: Bearer edhak_xxxxxxxx_yyyyyyyy…

方式 B：直接编辑 WorkBuddy 的 MCP 配置文件（~/.workbuddy/mcp.json）：

{
  "mcpServers": {
    "edh-space": {
      "url": "https://edatahub.cn/mcp",
      "headers": {
        "Authorization": "Bearer edhak_<keyId>_<secret>"
      }
    }
  }
}

保存后，在连接器管理页对该服务器点击信任/启用。

第 3 步：验证连接

在 WorkBuddy 对话中说一句：

列出我的数据空间

若返回空间列表即接入成功。也可先 tools/list 确认 16 个工具在列。

能做什么（工具面一览）

类别	工具
读（8）	resolve_edh_id / list_spaces / get_space / list_resources / get_resource / list_published_standards / get_standard / search_resources
写（6）	create_resource / update_resource / delete_resource / put_properties / put_registers / export_resource
物模型子资源（2）	list_properties / list_registers

典型任务：通讯协议 → 产品物模型

对 WorkBuddy 说：

把这份 DL645-2007 协议转成物模型，保存到我的数据空间

WorkBuddy 会走既定链路：

1. create_resource(kind=file) —— 协议原文落库（溯源锚点）；
2. 读取原文 + 参照同类物模型解析点位/功能码/缩放；
3. create_resource(kind=product-data) 建产品数据档案（upstream 指向协议原文）；
4. put_properties / put_registers 整表写入属性/寄存器（整体替换 + 乐观锁，回执含前后 diff 自检）；
5. 复核回执与 verify，确认无误。

转换结果在 Web 端空间详情「资源」页签可见，与人工编辑共用同一套门禁与版本 CAS。

安全说明

项	说明
权限面	密钥 = 创建者本人身份，零新增权限（读走 requireSpaceAccess、写走 requireSpaceWrite）
吊销	「API 密钥」页签点吊销（或 DELETE /api/v1/auth/api-keys/{keyId}），≤60 秒全网生效
角色变更	密钥持有创建时的角色快照，账号角色变化后需吊销重发
审计	创建/吊销写 auth_logs；每次资源读写写 space_usage（DeviceType=mcp）
并发	AI 写为整表版本级操作，与 Web 人工单条编辑并存，冲突统一走资源版本 CAS（409 回显 currentVersion）

常见问题

现象	原因与处理
401 invalid api key	密钥错误或已吊销 → 重新创建并更新连接器配置
401 api key auth disabled	服务端 mcp 容器未连库（MONGO_URL 未配置）或版本过旧 → 检查部署
409 version_conflict	资源版本已被他人修改 → 让 AI 重读资源后携带 currentVersion 重试（正常乐观锁流程）
工具只有 8 个（无写）	服务端仍是旧构建 → 部署含 P2 的版本
密钥列表为空但确认创建过	列表只显示当前登录账号名下的密钥（owner 记账）