Skip to main content
Glama
workbench-ecs

workbench-ecs

by nishuoyang
README.md
# workbench-ecs

[![CI](https://github.com/nishuoyang/workbench-ecs/actions/workflows/ci.yml/badge.svg)](https://github.com/nishuoyang/workbench-ecs/actions/workflows/ci.yml)

把 **dsh-workbench-ecs**(DeepSeek Harness 的阿里云 ECS 插件,v0.9.0)移植为 WorkBuddy 的 MCP 服务器。

- 本仓库路径: `E:\AiProject\workbench-ecs`(唯一有效来源)
- 移植来源: `C:\Users\ASUS\.dsh\node_modules\dsh-workbench-ecs`(github.com/nishuoyang/dsh-workbench-ecs)
- 运行方式: 零依赖 Node.js(≥18)MCP stdio 服务器,`src/server.mjs` 单文件
- 底层通道: 复用同一本机 **阿里云 Workbench CLI**(`~/.workbench/config.json` 凭据),实例经 Workbench 后端连接,**无需公网 IP / SSH 密钥**

## 目录结构

```
workbench-ecs/
├── src/
│   └── server.mjs          # MCP 服务器入口(唯一代码文件,零依赖)
├── scripts/
│   └── smoke.mjs           # 冒烟测试:initialize + tools/list 握手校验
├── config/
│   └── mcp.example.json    # 连接器配置片段(粘贴进 ~/.workbuddy/mcp.json)
├── docs/
│   └── MIGRATION.md        # 迁移记录(来源、变更、验证)
├── package.json            # 依赖声明(无运行时依赖)+ scripts
├── .gitignore
└── README.md
```

## 提供的工具(8 个)

| 工具 | 说明 |
|---|---|
| `ecs_list` | 列出指定地域的 ECS 实例 |
| `ecs_find` | 跨地域关键字检索(缺省扫全部 22 个公共地域) |
| `ecs_exec` | 远程执行命令/脚本(script 走 base64 直送零转义) |
| `ecs_log` | 按字节游标续读远端日志文件 |
| `ecs_upload` | 上传文件/目录(sha256 校验、瞬时失败重试、目录 tar 自动解包) |
| `ecs_download` | 下载远端文件到本机 |
| `ecs_diagnose` | 7 段预置只读体检(主机/负载/内存/磁盘/服务/进程/端口) |
| `ecs_session` | Workbench CLI 会话 list/close |

## 保留的原插件语义

- **破坏性命令守卫(fail-closed)**:`rm -rf`/`shutdown`/`dd`/`systemctl stop` 等默认拒绝,须显式 `allow_destructive: true`(会出现在 WorkBuddy 权限提示里)
- **read_only 护栏**:`read_only: true` 拒绝重定向/rm/docker 变更等 17 类写操作,并给出改写建议
- **远端超时结算**:`timed_out` 一律结算为 `exit_code=124`(不显示成"成功")
- **上传 sha256 校验**:不一致即中止,坏包不落地
- **ANSI/进度帧清洗**:去 ANSI/控制字符,并按 `\r` 覆盖语义折叠上传/下载的进度帧(只保留最后一段真实结果),不再出现 `⠋ Preparing...` 残留;上传**仅瞬时网络失败**自动重试(指数退避)
- **空会话归一**:`ecs_session list` 在没有活动会话时返回 `{sessions: [], count: 0}`,而不是 CLI 原样的 `null`

## 未移植(后续可加)

`ecs_deploy` / `ecs_runbook` / `ecs_snapshot` 编排引擎、伪会话(cd/export 继承)、detach 长任务、批量实例、可视化设置面板(dsh 专属 UI)。

## 开发与运行

```bash
cd /e/AiProject/workbench-ecs

node src/server.mjs      # 前台直接起服务(stdio,通常由 WorkBuddy 拉起)
npm start                # 同上
npm test                 # 冒烟测试:握手 + 8 个工具清单校验
```

无需 `npm install`:运行时只用 Node 内置模块。`package.json` 中的 `engines.node >= 18` 是唯一的运行前提。

## 注册到 WorkBuddy

把 `config/mcp.example.json` 的片段合并进 `~/.workbuddy/mcp.json` 的 `mcpServers`:

```json
{
  "workbench-ecs": {
    "type": "stdio",
    "command": "node",
    "args": ["E:\\AiProject\\workbench-ecs\\src\\server.mjs"]
  }
}
```

然后在连接器管理页右上角"自定义连接器"里 **Trust** 该服务器。改动 `src/server.mjs` 后重启会话生效。

## 发布(维护者)

```bash
git tag v1.0.1 && git push origin v1.0.1
```

打 tag 触发 `.github/workflows/release.yml`:测试与版本一致性校验 → `npm publish --provenance` → 确认版本真正上架 → 创建 GitHub Release。tag 必须与 `package.json` 的 `version` 一致,否则在第一步就被拦下。

**npm 12 默认分阶段发布**:`npm publish` 之后版本可能先进暂存队列,registry 上只出现 `0.0.0-stage` 占位(描述为 "Temporary package placeholder for staged publishing"),真实的 `latest` 要等放行才指向新版本。工作流会轮询最多 6 分钟;仍未公开则失败,并提示用 `npm stage list` + `npm stage approve` 人工批准(需 2FA)。

## 手动测试(协议层)

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node src/server.mjs
```

## 实测记录

- 2026-11-02(迁移前,旧路径):`ecs_exec` 对 `i-bp1xxxxxxxxxxxxxxxxx`(示例生产机)执行 `hostname && uptime` → exit_code=0,118ms;破坏性守卫拒绝 `rm -rf`;read_only 拒绝 `echo hi > /tmp/f`。
- 2026-11-14(迁移后,本路径):`npm test` 通过 —— `workbench-ecs v1.0.0`,协议 `2025-06-18`,8 个工具全部就位。
- 2026-11-14(改名后,经客户端 MCP 通道全量实测):`ecs_list` 按 status 过滤正常;`ecs_find` 跨 22 地域检索(20 成功,ap-southeast-2 / ap-south-1 因本地 DNS 解析失败跳过并逐条报错);`ecs_exec` 只读执行 83ms;`ecs_diagnose` 分段体检正常;`ecs_log` 读 400 字节并返回 `next_offset=400`;`ecs_upload` → `ecs_download` 往返 sha256 一致、内容无损;`ecs_session list` 无活动会话时返回 `null`。