@sstar/boardlinker_host 0.2.0

package/README.md

@@ -0,0 +1,103 @@
+# @sstar/boardlinker_host
+
+BoardLinker Host - MCP (Model Context Protocol) 服务器，让 AI 工具能够直接与嵌入式硬件交互。
+
+## 功能特性
+
+通过标准的 MCP 协议，为 AI 工具（如 Claude Code）提供以下硬件交互能力：
+
+- **板卡 UART 操作**: 多会话串口管理、命令发送、信号控制
+- **文件传输**: Host 与 Agent 之间的双向文件传输
+- **固件烧录**: 镜像准备和 ISP 恢复烧录
+- **Agent 状态查询**: 获取 Agent 运行状态和网络信息
+- **文档系统**: 内置硬件操作文档和指南
+
+## 使用
+
+### npx 直接运行
+
+```bash
+npx @sstar/boardlinker_host
+```
+
+### 全局安装
+
+```bash
+npm install -g @sstar/boardlinker_host
+
+# 安装后运行
+boardlinker-host
+```
+
+## 前置条件
+
+在使用 Host 之前，需要先在同一台机器上启动 Agent：
+
+```bash
+# 终端 1: 启动 Agent
+boardlinker
+
+# 终端 2: 启动 Host
+npx @sstar/boardlinker_host
+```
+
+## 环境变量
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `BOARDLINKER_AGENT_ADDR` | Agent 连接地址 | `127.0.0.1:10000` |
+| `BOARDLINKER_HOST_DEBUG` | Host 调试模式 | `false` |
+| `BOARDLINKER_DEBUG` | 全局调试模式 | `false` |
+
+## MCP 工具列表
+
+Host 向 AI 工具暴露以下 MCP 工具：
+
+### 板卡 UART 操作
+- `board_uart-sessions` - 列出所有 UART 会话
+- `board_uart-run_command` - 发送命令到 UART
+- `board_uart-send_signal` - 发送控制信号（ENTER, Ctrl+C 等）
+- `board_uart-read` - 从 UART 读取数据
+- `board_uart-status` - 获取 UART 硬件状态
+
+### 文件操作
+- `files-put` - 上传文件到 Agent
+- `files-get` - 从 Agent 下载文件
+- `files-list` - 列出 Agent 文件
+- `files-stat` - 获取文件状态
+- `files-mkdir` - 创建目录
+- `files-rm` - 删除文件/目录
+
+### 固件操作
+- `firmware-prepare_images` - 准备固件镜像
+- `firmware-burn_recover` - 执行固件烧录/恢复
+
+### 其他
+- `agent-status` - 获取 Agent 状态
+- `docs-list` - 列出可用文档
+- `docs-read` - 读取文档内容
+
+## 在 Claude Code 中使用
+
+在 Claude Code 的 MCP 配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "boardlinker": {
+      "command": "npx",
+      "args": ["-y", "@sstar/boardlinker_host"]
+    }
+  }
+}
+```
+
+## 系统要求
+
+- Node.js >= 18.0.0
+- 需要先启动 [@sstar/boardlinker_agent](../agent/)
+- 支持 macOS、Linux、Windows
+
+## 许可证
+
+MIT

package/dist/.platform

@@ -0,0 +1 @@
+linux-x64

package/dist/grpc.js

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Metadata, credentials, loadPackageDefinition } from '@grpc/grpc-js';
+import { loadSync } from '@grpc/proto-loader';
+export function createAgentClient(addr, opts) {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // 优先：构建输出目录中的 proto (dist/proto/agent.proto)
+        path.join(here, 'proto', 'agent.proto'),
+        // 兼容旧模式：Host 包自身目录下的 proto (packages/host/proto)
+        path.join(here, '..', 'proto', 'agent.proto'),
+        // 兼容当前 monorepo 结构：packages/host/dist/../.. -> repo 根
+        path.join(here, '..', '..', 'proto', 'agent.proto'),
+    ];
+    const protoPath = candidates.find((p) => fs.existsSync(p)) || candidates[0];
+    const def = loadSync(protoPath, {
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+        keepCase: true,
+    });
+    const pkg = loadPackageDefinition(def);
+    const AgentCls = pkg.boardlinker.agent.v1.AgentService;
+    const PairingCls = pkg.boardlinker.agent.v1.PairingService;
+    const FilesCls = pkg.boardlinker.agent.v1.FilesService;
+    const client = new AgentCls(addr, credentials.createInsecure());
+    const pairingClient = new PairingCls(addr, credentials.createInsecure());
+    const filesClient = new FilesCls(addr, credentials.createInsecure());
+    const meta = new Metadata();
+    const hostInstanceId = (opts?.hostInstanceId || '').trim();
+    if (hostInstanceId) {
+        meta.set('x-boardlinker-host-instance-id', hostInstanceId);
+    }
+    return {
+        pairCheck(params) {
+            const payload = {
+                pairCode: params.pairCode,
+                clientId: params.clientId || 'boardlinker-host',
+                timestamp: Date.now(),
+            };
+            return new Promise((resolve, reject) => {
+                const deadlineMs = typeof params.timeoutMs === 'number' && params.timeoutMs > 0 ? params.timeoutMs : 3000;
+                const deadline = new Date(Date.now() + deadlineMs);
+                pairingClient.PairCheck(payload, { deadline }, (e, r) => e ? reject(e) : resolve(r));
+            });
+        },
+        status() {
+            return new Promise((resolve, reject) => client.Status({}, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardUartWrite(params) {
+            return new Promise((resolve, reject) => client.BoardUartWrite(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardUartListSessions() {
+            return new Promise((resolve, reject) => client.BoardUartListSessions({}, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardUartSessionWrite(params) {
+            return new Promise((resolve, reject) => client.BoardUartSessionWrite(params, meta, (e, r) => e ? reject(e) : resolve(r)));
+        },
+        boardUartSessionRead(params) {
+            return new Promise((resolve, reject) => client.BoardUartSessionRead(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardUartOpenManual(params) {
+            return new Promise((resolve, reject) => client.BoardUartOpenManual(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardUartCloseSession(params) {
+            return new Promise((resolve, reject) => client.BoardUartCloseSession(params, meta, (e, r) => e ? reject(e) : resolve(r)));
+        },
+        boardUartStatus() {
+            return new Promise((resolve, reject) => client.BoardUartStatus({}, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardUartForceClose() {
+            return new Promise((resolve, reject) => client.BoardUartForceClose({}, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        tftpUpload(params) {
+            return new Promise((resolve, reject) => client.TftpUpload(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        tftpDownload(params) {
+            return new Promise((resolve, reject) => client.TftpDownload(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        tftpList(params) {
+            return new Promise((resolve, reject) => client.TftpList(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        tftpUserguide() {
+            return new Promise((resolve, reject) => client.TftpUserguide({}, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        ubootBreak(params) {
+            return new Promise((resolve, reject) => client.UBootBreak(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        ubootRunCommand(params) {
+            return new Promise((resolve, reject) => client.UBootRunCommand(params, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardUartListPorts() {
+            return new Promise((resolve, reject) => client.BoardUartListPorts({}, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        listSshCandidates() {
+            return new Promise((resolve, reject) => client.ListSshCandidates({}, meta, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        nfsUpload(params) {
+            return new Promise((resolve, reject) => client.NfsUpload(params, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        nfsDownload(params) {
+            return new Promise((resolve, reject) => client.NfsDownload(params, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        nfsList(params) {
+            // 转换mode为protobuf枚举值
+            const protoParams = {
+                remoteSubpath: params.remoteSubpath || '',
+                mode: params.mode === 'detailed' ? 2 : 1, // 2 = NFS_LIST_MODE_DETAILED, 1 = NFS_LIST_MODE_SIMPLE
+                limit: params.limit,
+            };
+            return new Promise((resolve, reject) => client.NfsList(protoParams, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        nfsInfo() {
+            return new Promise((resolve, reject) => client.NfsInfo({}, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        nfsUserguide() {
+            return new Promise((resolve, reject) => client.NfsUserguide({}, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        boardNotes(params) {
+            return new Promise((resolve, reject) => client.BoardNotes(params, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        firmwarePrepareImages(params) {
+            const req = {
+                imagesRoot: params.imagesRoot,
+            };
+            return new Promise((resolve, reject) => client.FirmwarePrepareImages(req, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        firmwareBurnRecover(params) {
+            const req = {
+                imagesRoot: params.imagesRoot,
+                args: params.args ?? [],
+                timeoutMs: params.timeoutMs ?? 0,
+                force: params.force ?? false,
+            };
+            return new Promise((resolve, reject) => client.FirmwareBurnRecover(req, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        firmwareUserGuide() {
+            return new Promise((resolve, reject) => client.FirmwareUserGuide({}, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        tunnelStart(params) {
+            const req = {
+                host: params.host,
+                user: params.user,
+                port: params.port ?? 22,
+                password: params.password ?? '',
+                privateKeyPath: params.privateKeyPath ?? '',
+                localPort: params.localPort ?? 0,
+                forwardHost: params.forwardHost ?? '',
+                forwardPort: params.forwardPort ?? 0,
+            };
+            return new Promise((resolve, reject) => client.TunnelStart(req, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        tunnelStop() {
+            return new Promise((resolve, reject) => client.TunnelStop({}, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        hostLogStream() {
+            let resolver = () => { };
+            let rejecter = () => { };
+            const response = new Promise((resolve, reject) => {
+                resolver = resolve;
+                rejecter = reject;
+            });
+            const call = client.HostLogStream(meta, (e, r) => (e ? rejecter(e) : resolver(r)));
+            return { call, response };
+        },
+        // Files Service 客户端方法
+        filesPutPath() {
+            let resolver = () => { };
+            let rejecter = () => { };
+            const response = new Promise((resolve, reject) => {
+                resolver = resolve;
+                rejecter = reject;
+            });
+            const call = filesClient.PutPath((e, r) => (e ? rejecter(e) : resolver(r)));
+            return { call, response };
+        },
+        filesGetPath(params) {
+            return filesClient.GetPath(params);
+        },
+        filesList(params) {
+            return new Promise((resolve, reject) => filesClient.ListFiles(params || {}, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        filesRemove(params) {
+            return new Promise((resolve, reject) => filesClient.RemoveFiles(params, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        filesMakeDir(params) {
+            return new Promise((resolve, reject) => filesClient.MakeDirectory(params, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+        filesGetStat(params) {
+            return new Promise((resolve, reject) => filesClient.GetStat(params, (e, r) => (e ? reject(e) : resolve(r))));
+        },
+    };
+}