罗拉超算站

概述

box-connect

把盒子服务器接入 WorkBuddy，使知识库检索（RAG）与本地模型（llama-swap）可用。

前置条件

• 盒子已启动 luya library-mcp（http://<box-ip>/luya/v1/mcp，Bearer 鉴权）；
• 盒子已创建 API Key（sk- 开头，luya 管理端创建）；
• 盒子已启动 llama-swap（本地模型，端口 11435）。

脚本

使用流程（严格按序执行）

1. 询问盒子 IP 与 API Key：向用户询问盒子服务器 IP（IPv4 格式，校验格式 x.x.x.x，非法则重新询问）；再询问 API Key（sk- 开头，用户没有则让其先在 luya 管理端创建）。
2. 探测知识库 MCP 端点：运行

   python scripts/probe.py box --ip <IP>

• 成功：继续下一步；
• 失败：向用户说明原因（区分 IP 不通 / 超时），并建议 ping <IP> 排查后重试。
• 注：HTTP 探测不带鉴权，仅确认端点可达。

1. 探测本地模型端点：运行

   python scripts/probe.py model --ip <IP>

• 成功：向用户展示可用模型列表（从 /v1/models 获取），记录模型名列表供步骤 5 使用；
• 失败：提示用户"本地模型端点不可达，知识库 MCP 可正常使用，但本地模型对话暂不可用。请确认盒子已启动 llama-swap（端口 11435）"；
• 注意：模型端点探测失败不阻塞知识库 MCP 的配置流程。

1. 写入 MCP 配置：运行

   python scripts/write_config.py mcp --ip <IP> --api-key <KEY>

• 脚本幂等合并写入 ~/.workbuddy/mcp.json（server 名固定 box-library），Key 以 Authorization: Bearer <KEY> 写入 headers；
• 幂等策略：仅当 IP 与 Key 均与旧配置相同时才跳过；换 IP、换 Key 或两者都换时直接重跑即可覆盖更新；
• 写入前会自动做一次 MCP 握手预检（验证 IP 可达 + Key 有效），不匹配则不写入并提示；确需跳过预检时加 --no-verify。

1. 写入模型配置：若步骤 3 探测成功，运行

   python scripts/write_config.py model --ip <IP> --models <模型名列表>

• 将探测到的模型写入 ~/.workbuddy/models.json，自动设置 vendor: Custom、supportsToolCall: true；
• WorkBuddy 约 1 秒自动重载配置，无需重启；
• 若 models.json 已存在其他自定义模型，只会追加/更新当前盒子的模型，不影响原有配置。

1. 验证 MCP 连接：运行

   python scripts/verify_mcp.py --ip <IP> --api-key <KEY>

• 脚本会依次完成：MCP initialize 握手（携带鉴权头）→ tools/list → 调用 library_list；
• 成功后向用户展示：发现 M 个知识库；
• 若 M=0：告知用户无可用知识库；
• 若握手返回 401/403，提示用户检查 Key 是否有效（确认 Key 以 sk- 开头且在 luya 管理端为正常启用状态）。

1. 提示启用 MCP：告知用户 在左侧菜单进入【专家・技能・连接器】页面，顶部切换至「连接器」标签，点击右上角「自定义连接器」，在弹窗找到 box‑library 并点击信任。（ WorkBuddy 新增 MCP 组件必须信任后才能正常使用。
2. 给出使用示例（对话话术）：

• 知识库问答："总结产品手册里关于 XX 的内容" —— 调用 library_search；
• 创建知识库："帮我创建一个技术笔记知识库" —— 调用 library_create；
• 上传文档："把这个 PDF/图片传到知识库" —— 先解析成 Markdown 文本，再调 document_create_from_text 上传；
• 本地模型对话：WorkBuddy 右下角 Auto 选择盒子模型（如 qwen2.5:7b）直接对话。

注意事项

• 检索前置：先调 library_list 确认可用库；返回空则禁调其他工具并告知用户无库（library_create 除外）；操作仅限返回的 ID，禁止编造。
• 只追加/覆盖 box-library，不删除其他 server；不支持多盒子并行。
• 鉴权：每次 MCP 调用都携带 Authorization: Bearer <KEY>，由 luya 侧 apikey 管理校验（失效/禁用即拒绝）；
• 自动配置：MCP 配置写入 ~/.workbuddy/mcp.json，模型配置写入 ~/.workbuddy/models.json，均为本地文件，自动合并不覆盖其他配置；
• 模型端点无鉴权：llama-swap 默认不鉴权，如盒子侧配置了鉴权则需用户手动在 WorkBuddy 模型设置中填入 API Key；
• 若 library_list 调用失败，提示"盒子知识库 MCP 异常"，检查盒子 luya library-mcp 是否启动、Key 是否有效。
• 文件上传边界：MCP document_create_from_text 仅接收文本内容；遇到 PDF/图片等二进制文件时，先解析成 Markdown 再上传；扫描件/复杂排版等解析失真明显时，引导用户去 luya 知识库页面手动上传以保真。

API Key 使用边界（重要）

本技能的 API Key 只能用于 /luya/v1/mcp，禁止调用其他任何 luya REST 端点。