opencode-idea 0.1.3 → 0.1.5

package/src/remote/prompts.js

@@ -0,0 +1,52 @@
+// 两条"提示词命令"的正文：`/remote-shell` 与 `/remote-deployment`。
+//
+// 它们不执行任何东西，只往会话里注入一段规则，让模型走本插件的 remote_* 工具，
+// 而不是自己拼 ssh / scp。和 `~/.config/opencode/commands/readonly.md` 是同一个思路，
+// 区别只是注册在插件里（跟着包分发，不需要用户再放一个 md 文件）。
+
+/**
+ * `/remote-shell` 注入的提示词。
+ *
+ * @param {string} request 命令后面跟的原始文本（可能为空）
+ */
+export function remoteShellPrompt(request) {
+    const ask = request.trim();
+    return [
+        '【远程执行】本次会话的远程操作一律走本插件的工具，不要用 shell 里的 ssh / scp / rsync。',
+        '',
+        '1. 服务器名不确定 → 先调 remote_list_servers（列出 IDE / 项目 / 全局三层，带来源）',
+        '2. 跑命令 → remote_exec(server, command)，需要目录就传 workingDirectory',
+        '   · 每条命令是独立 SSH 连接：cd / export 不跨命令保留',
+        '3. 传文件 → remote_upload / remote_download（按 deployment 名）',
+        '4. 名字传错时工具会列出全部候选，按列表重新调用，不要猜',
+        '',
+        ask
+            ? `如果用户没有指定服务器或要执行的命令，先问清楚再调用，不要自己挑一台。\n\n用户本次的要求：${ask}`
+            : '用户这次没有说要在哪台机器上做什么。先问清楚：服务器是哪台、要执行的命令是什么，再调用工具。',
+    ].join('\n');
+}
+
+/**
+ * `/remote-deployment` 注入的提示词。
+ *
+ * @param {string} request
+ */
+export function remoteDeploymentPrompt(request) {
+    const ask = request.trim();
+    return [
+        '【远程部署同步】本次会话的传输一律用 remote_upload / remote_download，不要用 scp / rsync / ssh。',
+        '',
+        '1. deployment 名不确定 → 先调 remote_list_servers（每条 mapping 显示 本地 ↔ 远程）',
+        '2. 上传 → remote_upload；下载 → remote_download',
+        '3. mode 默认 overwrite（只覆盖 / 新增）；mirror 会删掉目标端多出来的文件，**不可逆**，只在明确要求镜像时用',
+        '4. 传输同步返回 files / dirs / bytes，没有进度条、没有 handle 要轮询',
+        '',
+        ask
+            ? `如果用户没有指定要同步的 deployment，先问清楚再调用，不要自己挑一条。\n\n用户本次的要求：${ask}`
+            : '用户这次没有说要同步哪一条 deployment。先调 remote_list_servers 列出候选，问清楚是哪一条、上传还是下载，再动手。',
+    ].join('\n');
+}
+
+/** 用户看到的简短提示（`metadata.displayText`）。 */
+export const REMOTE_SHELL_DISPLAY = '【远程执行】已切到 remote_* 工具模式；没指定服务器或命令时会先问你。';
+export const REMOTE_DEPLOYMENT_DISPLAY = '【远程部署同步】已切到 remote_upload / remote_download；没指定 deployment 时会先问你。';

package/src/remote/prompts.test.js

@@ -0,0 +1,38 @@
+// 两条提示词命令的正文测试：有参数时带上参数，没参数时要求先问。
+
+import {describe, expect, it} from 'vitest';
+
+import {remoteDeploymentPrompt, remoteShellPrompt} from './prompts.js';
+
+describe('remoteShellPrompt', () => {
+    it('带上用户的要求，并要求没指定时先问', () => {
+        const text = remoteShellPrompt('mbp 看下磁盘');
+        expect(text).toContain('remote_list_servers');
+        expect(text).toContain('remote_exec');
+        expect(text).toContain('不要用 shell 里的 ssh');
+        expect(text).toContain('用户本次的要求：mbp 看下磁盘');
+        expect(text).toContain('先问清楚');
+    });
+
+    it('没带参数时明确要求先问服务器与命令', () => {
+        const text = remoteShellPrompt('');
+        expect(text).toContain('先问清楚');
+        expect(text).not.toContain('用户本次的要求：');
+    });
+});
+
+describe('remoteDeploymentPrompt', () => {
+    it('带上用户的要求，并要求没指定时先问', () => {
+        const text = remoteDeploymentPrompt('mcp-test-project download');
+        expect(text).toContain('remote_upload');
+        expect(text).toContain('remote_download');
+        expect(text).toContain('用户本次的要求：mcp-test-project download');
+        expect(text).toContain('先问清楚');
+    });
+
+    it('没带参数时提示先列出候选再问', () => {
+        const text = remoteDeploymentPrompt('   ');
+        expect(text).toContain('remote_list_servers');
+        expect(text).not.toContain('用户本次的要求：');
+    });
+});

package/src/remote/sftp.js

@@ -0,0 +1,242 @@
+// SFTP 目录同步：`overwrite`（只覆盖/新增）与 `mirror`（再删掉对方多余的文件）。
+//
+// 语义与 rsync 的尾斜杠一致：把 `localPath` 目录的**内容**同步到 `deployPath`，
+// 不会额外生成一层 `localPath` 的目录名。
+//
+// 符号链接跳过并计数 —— 跟随链接会把目标目录之外的整棵树拖进来，那是另一个决定。
+
+import {readdir, stat as fsStat} from 'node:fs/promises';
+import {join} from 'node:path';
+import {posix} from 'node:path';
+
+/**
+ * @typedef {{
+ *   files: number,
+ *   dirs: number,
+ *   bytes: number,
+ *   skipped: number,
+ *   deleted: number,
+ * }} SyncStats
+ */
+
+/** ssh2 的回调式 API → Promise。 */
+function call(fn, ...args) {
+    return new Promise((resolve, reject) => {
+        fn(...args, (error, value) => (error ? reject(error) : resolve(value)));
+    });
+}
+
+/**
+ * 打开一个 SFTP session。
+ *
+ * @param {import('ssh2').Client} conn
+ */
+export function openSftp(conn) {
+    return new Promise((resolve, reject) => {
+        conn.sftp((error, sftp) => (error ? reject(error) : resolve(sftp)));
+    });
+}
+
+/**
+ * 逐级 `mkdir`，已存在不算错。
+ *
+ * @param {import('ssh2').SFTPWrapper} sftp
+ * @param {string} dir
+ */
+export async function ensureRemoteDir(sftp, dir) {
+    if (!dir || dir === '/' || dir === '.') return;
+    const normalized = posix.normalize(dir).replace(/\/+$/, '');
+    const parts = normalized.split('/').filter(Boolean);
+    let current = normalized.startsWith('/') ? '' : '.';
+    for (const part of parts) {
+        current = current === '' ? `/${part}` : `${current}/${part}`;
+        try {
+            const info = await call(sftp.stat.bind(sftp), current);
+            if (!info.isDirectory()) throw new Error(`远程路径 "${current}" 已存在但不是目录`);
+        } catch (error) {
+            if (error?.code === 2 || /No such file/i.test(String(error?.message))) {
+                await call(sftp.mkdir.bind(sftp), current);
+            } else {
+                throw error;
+            }
+        }
+    }
+}
+
+/**
+ * 递归上传一个本地目录。
+ *
+ * @param {import('ssh2').SFTPWrapper} sftp
+ * @param {string} localDir
+ * @param {string} remoteDir
+ * @param {SyncStats} stats
+ * @param {{ signal?: AbortSignal }} [options]
+ */
+async function uploadTree(sftp, localDir, remoteDir, stats, options = {}) {
+    await ensureRemoteDir(sftp, remoteDir);
+    const entries = await readdir(localDir, {withFileTypes: true});
+    for (const entry of entries) {
+        if (options.signal?.aborted) throw new Error('传输已取消');
+        const localPath = join(localDir, entry.name);
+        const remotePath = posix.join(remoteDir, entry.name);
+        if (entry.isDirectory()) {
+            stats.dirs += 1;
+            await uploadTree(sftp, localPath, remotePath, stats, options);
+        } else if (entry.isFile()) {
+            const info = await fsStat(localPath);
+            await call(sftp.fastPut.bind(sftp), localPath, remotePath);
+            stats.files += 1;
+            stats.bytes += info.size;
+        } else {
+            stats.skipped += 1;
+        }
+    }
+}
+
+/**
+ * 递归读取远程目录的条目（相对路径 + 是否目录），用于 mirror 的差异删除。
+ *
+ * @param {import('ssh2').SFTPWrapper} sftp
+ * @param {string} remoteDir
+ * @param {string} [prefix]
+ * @returns {Promise<{ path: string, dir: boolean }[]>}
+ */
+async function listRemoteTree(sftp, remoteDir, prefix = '') {
+    const entries = await call(sftp.readdir.bind(sftp), remoteDir).catch((error) => {
+        if (error?.code === 2 || /No such file/i.test(String(error?.message))) return [];
+        throw error;
+    });
+    const result = [];
+    for (const entry of entries) {
+        const name = entry.filename;
+        if (name === '.' || name === '..') continue;
+        const relative = prefix ? `${prefix}/${name}` : name;
+        const isDir = entry.attrs.isDirectory();
+        result.push({path: relative, dir: isDir});
+        if (isDir) {
+            result.push(...await listRemoteTree(sftp, posix.join(remoteDir, name), relative));
+        }
+    }
+    return result;
+}
+
+/**
+ * 递归列出本地目录的相对条目，用于 mirror。
+ *
+ * @param {string} localDir
+ * @param {string} [prefix]
+ * @returns {Promise<{ path: string, dir: boolean }[]>}
+ */
+async function listLocalTree(localDir, prefix = '') {
+    const entries = await readdir(localDir, {withFileTypes: true}).catch(() => []);
+    const result = [];
+    for (const entry of entries) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            result.push({path: relative, dir: true});
+            result.push(...await listLocalTree(join(localDir, entry.name), relative));
+        } else if (entry.isFile()) {
+            result.push({path: relative, dir: false});
+        }
+    }
+    return result;
+}
+
+/**
+ * 上传：本地目录 → 远程目录。
+ *
+ * @param {import('ssh2').SFTPWrapper} sftp
+ * @param {string} localDir
+ * @param {string} remoteDir
+ * @param {'overwrite' | 'mirror'} mode
+ * @param {{ signal?: AbortSignal }} [options]
+ * @returns {Promise<SyncStats>}
+ */
+export async function uploadDirectory(sftp, localDir, remoteDir, mode, options = {}) {
+    const stats = {files: 0, dirs: 0, bytes: 0, skipped: 0, deleted: 0};
+    await uploadTree(sftp, localDir, remoteDir, stats, options);
+
+    if (mode === 'mirror') {
+        const localSet = new Set((await listLocalTree(localDir)).map((entry) => entry.path));
+        const remoteEntries = await listRemoteTree(sftp, remoteDir);
+        // 先删文件再删目录，避免 rmdir 非空。
+        for (const entry of remoteEntries.filter((item) => !item.dir)) {
+            if (localSet.has(entry.path)) continue;
+            await call(sftp.unlink.bind(sftp), posix.join(remoteDir, entry.path));
+            stats.deleted += 1;
+        }
+        for (const entry of remoteEntries.filter((item) => item.dir).reverse()) {
+            if (localSet.has(entry.path)) continue;
+            await call(sftp.rmdir.bind(sftp), posix.join(remoteDir, entry.path)).catch(() => {});
+            stats.deleted += 1;
+        }
+    }
+    return stats;
+}
+
+/**
+ * 递归下载一个远程目录。
+ *
+ * @param {import('ssh2').SFTPWrapper} sftp
+ * @param {string} remoteDir
+ * @param {string} localDir
+ * @param {SyncStats} stats
+ * @param {{ signal?: AbortSignal }} [options]
+ */
+async function downloadTree(sftp, remoteDir, localDir, stats, options = {}) {
+    const {mkdir} = await import('node:fs/promises');
+    await mkdir(localDir, {recursive: true});
+    const entries = await call(sftp.readdir.bind(sftp), remoteDir).catch((error) => {
+        if (error?.code === 2 || /No such file/i.test(String(error?.message))) return [];
+        throw error;
+    });
+    for (const entry of entries) {
+        if (options.signal?.aborted) throw new Error('传输已取消');
+        const name = entry.filename;
+        if (name === '.' || name === '..') continue;
+        const remotePath = posix.join(remoteDir, name);
+        const localPath = join(localDir, name);
+        if (entry.attrs.isDirectory()) {
+            stats.dirs += 1;
+            await downloadTree(sftp, remotePath, localPath, stats, options);
+        } else if (entry.attrs.isFile()) {
+            await call(sftp.fastGet.bind(sftp), remotePath, localPath);
+            stats.files += 1;
+            stats.bytes += entry.attrs.size ?? 0;
+        } else {
+            stats.skipped += 1;
+        }
+    }
+}
+
+/**
+ * 下载：远程目录 → 本地目录。
+ *
+ * @param {import('ssh2').SFTPWrapper} sftp
+ * @param {string} remoteDir
+ * @param {string} localDir
+ * @param {'overwrite' | 'mirror'} mode
+ * @param {{ signal?: AbortSignal }} [options]
+ * @returns {Promise<SyncStats>}
+ */
+export async function downloadDirectory(sftp, remoteDir, localDir, mode, options = {}) {
+    const stats = {files: 0, dirs: 0, bytes: 0, skipped: 0, deleted: 0};
+    await downloadTree(sftp, remoteDir, localDir, stats, options);
+
+    if (mode === 'mirror') {
+        const remoteEntries = await listRemoteTree(sftp, remoteDir);
+        const remoteSet = new Set(remoteEntries.map((entry) => entry.path));
+        const {rm, rmdir} = await import('node:fs/promises');
+        for (const entry of (await listLocalTree(localDir)).filter((item) => !item.dir)) {
+            if (remoteSet.has(entry.path)) continue;
+            await rm(join(localDir, entry.path), {force: true});
+            stats.deleted += 1;
+        }
+        // 本地空目录也收掉；非空时 rmdir 会失败，忽略即可。
+        for (const entry of (await listLocalTree(localDir)).filter((item) => item.dir).reverse()) {
+            if (remoteSet.has(entry.path)) continue;
+            await rmdir(join(localDir, entry.path)).catch(() => {});
+        }
+    }
+    return stats;
+}

package/src/remote/sftp.test.js

@@ -0,0 +1,47 @@
+// SFTP 层的路径逻辑测试（真实的传输只能手工验证）。
+
+import {describe, expect, it} from 'vitest';
+
+import {ensureRemoteDir} from './sftp.js';
+
+/** 一个只实现 stat / mkdir 的假 SFTP，用来观察逐级建目录的顺序。 */
+function fakeSftp({existing = []} = {}) {
+    const dirs = new Set(existing);
+    const created = [];
+    return {
+        created,
+        stat(path, callback) {
+            if (dirs.has(path)) callback(null, {isDirectory: () => true});
+            else {
+                const error = new Error('No such file');
+                error.code = 2;
+                callback(error);
+            }
+        },
+        mkdir(path, callback) {
+            created.push(path);
+            dirs.add(path);
+            callback(null);
+        },
+    };
+}
+
+describe('ensureRemoteDir', () => {
+    it('逐级建目录', async () => {
+        const sftp = fakeSftp();
+        await ensureRemoteDir(sftp, '/srv/app/static');
+        expect(sftp.created).toEqual(['/srv', '/srv/app', '/srv/app/static']);
+    });
+
+    it('已存在的层级不重复建', async () => {
+        const sftp = fakeSftp({existing: ['/srv', '/srv/app']});
+        await ensureRemoteDir(sftp, '/srv/app/static');
+        expect(sftp.created).toEqual(['/srv/app/static']);
+    });
+
+    it('根目录什么都不做', async () => {
+        const sftp = fakeSftp();
+        await ensureRemoteDir(sftp, '/');
+        expect(sftp.created).toEqual([]);
+    });
+});

package/src/remote/ssh.js

@@ -0,0 +1,195 @@
+// SSH 执行：一次调用 = 一条连接 + 一条命令。
+//
+// 刻意**不做持久 shell**：没有交互式会话就没有提示符解析、没有输出边界猜测、没有
+// 会话生命周期管理。代价是 `cd` / `export` 不跨命令保留 —— 需要目录就传
+// `workingDirectory`（内部拼 `cd '<dir>' && <command>`），需要环境就写进命令本身。
+
+import {readFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+
+import {Client} from 'ssh2';
+
+/** 连接建立的上限。命令本身**不设超时**：卡住时由用户取消这次调用。 */
+const CONNECT_TIMEOUT_MS = 15000;
+
+/** @param {string} path */
+export function expandTilde(path) {
+    if (path === '~') return homedir();
+    if (path.startsWith('~/')) return join(homedir(), path.slice(2));
+    return path;
+}
+
+/** POSIX 单引号引用；内部单引号用 `'\''` 转义。 */
+export function shellQuote(value) {
+    return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * 把 `cd` 包装进命令。`~` 必须当远程的 `$HOME` 处理 —— `cd '~'` 不会展开。
+ *
+ * @param {string} command
+ * @param {string | undefined} workingDirectory
+ */
+export function withWorkingDirectory(command, workingDirectory) {
+    const dir = workingDirectory?.trim();
+    if (!dir) return command;
+    const cd = dir === '~'
+        ? 'cd "$HOME"'
+        : dir.startsWith('~/')
+            ? `cd "$HOME"/${shellQuote(dir.slice(2))}`
+            : `cd ${shellQuote(dir)}`;
+    return `${cd} && ${command}`;
+}
+
+/**
+ * 开一条 SSH 连接。
+ *
+ * @param {import('./hosts.js').RemoteServer} server
+ * @returns {Promise<import('ssh2').Client>}
+ */
+export function connect(server) {
+    return new Promise((resolve, reject) => {
+        const conn = new Client();
+        let settled = false;
+        /** @param {Error} [error] @param {unknown} [value] */
+        const done = (error, value) => {
+            if (settled) return;
+            settled = true;
+            if (error) reject(error);
+            else resolve(value);
+        };
+
+        let privateKey;
+        if (server.privateKeyPath) {
+            try {
+                privateKey = readFileSync(expandTilde(server.privateKeyPath));
+            } catch (error) {
+                reject(new Error(
+                    `无法读取私钥 "${server.privateKeyPath}": ` +
+                    (error instanceof Error ? error.message : String(error)),
+                ));
+                return;
+            }
+        }
+
+        conn.on('ready', () => done(undefined, conn));
+        conn.on('error', (error) => done(error));
+        // close/end 只在连接意外结束时有意义；正常收尾时 settled 已经是 true。
+        conn.on('close', () => done(new Error('SSH 连接意外关闭')));
+        conn.on('end', () => done(new Error('SSH 连接意外断开')));
+
+        // 第三种认证方式：OpenSSH config / ssh-agent。IDE 里选了它时不会有 password 也不会有
+        // privateKeyPath —— 凭据在 `~/.ssh/config` 与 agent 里，ssh2 要用 agent socket。
+        const useAgent = server.authType === 'OPEN_SSH'
+            || (!server.password && !server.privateKeyPath);
+        const agent = useAgent ? process.env.SSH_AUTH_SOCK : undefined;
+
+        try {
+            conn.connect({
+                host: server.host,
+                port: server.port,
+                username: server.username,
+                password: server.password,
+                privateKey,
+                passphrase: server.passphrase,
+                agent,
+                readyTimeout: CONNECT_TIMEOUT_MS,
+                keepaliveInterval: 5000,
+                keepaliveCountMax: 3,
+            });
+        } catch (error) {
+            done(error instanceof Error ? error : new Error(String(error)));
+        }
+    });
+}
+
+/**
+ * 在远程执行一条命令。
+ *
+ * 命令先 base64 编码再交给 `sh`：这样引号、换行、`$` 都不会被本地 shell 或传输层改写，
+ * 远程拿到的就是调用方写的那条命令。
+ *
+ * @param {import('./hosts.js').RemoteServer} server
+ * @param {string} command
+ * @param {{ workingDirectory?: string }} [options]
+ * @returns {Promise<{ exitCode: number | null, stdout: string, stderr: string }>}
+ */
+export async function runRemoteCommand(server, command, options = {}) {
+    const conn = await connect(server);
+    try {
+        return await execOn(conn, withWorkingDirectory(command, options.workingDirectory));
+    } finally {
+        conn.end();
+    }
+}
+
+/**
+ * @param {import('ssh2').Client} conn
+ * @param {string} command 已经包好 `cd` 的命令
+ */
+function execOn(conn, command) {
+    const encoded = Buffer.from(command, 'utf8').toString('base64');
+    const execCommand = `printf '%s' '${encoded}' | (base64 -d 2>/dev/null || openssl base64 -d 2>/dev/null) | sh`;
+
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let stdout = '';
+        let stderr = '';
+
+        /** @param {Error} [error] @param {{ exitCode: number | null }} [value] */
+        const finish = (error, value) => {
+            if (settled) return;
+            settled = true;
+            if (error) reject(error);
+            else resolve({exitCode: value?.exitCode ?? null, stdout, stderr});
+        };
+
+        conn.exec(execCommand, (error, stream) => {
+            if (error) {
+                finish(error);
+                return;
+            }
+
+            stream.on('data', (chunk) => {
+                stdout += chunk.toString('utf8');
+            });
+            stream.stderr.on('data', (chunk) => {
+                stderr += chunk.toString('utf8');
+            });
+            // 没有内部超时：命令会一直跑到自己结束或连接断掉。卡住的调用由用户取消。
+            stream.on('close', (code) => {
+                finish(undefined, {exitCode: typeof code === 'number' ? code : null});
+            });
+            stream.on('error', (streamError) => {
+                finish(streamError);
+            });
+        });
+    });
+}
+
+/**
+ * 把 SSH 错误翻译成调用方看得懂的一句话。
+ *
+ * @param {unknown} error
+ * @param {import('./hosts.js').RemoteServer} server
+ */
+export function describeSshError(error, server) {
+    const message = error instanceof Error ? error.message : String(error);
+    const level = /** @type {{ level?: string }} */ (error)?.level;
+    if (level === 'client-authentication' || /authentication/i.test(message)) {
+        return `认证失败（${server.username}@${server.host}:${server.port}）：密码/私钥可能已失效，` +
+            `请在 IDE 的 Deployment 设置里更新后重试。`;
+    }
+    if (/ECONNREFUSED/i.test(message)) {
+        return `连接被拒绝（${server.host}:${server.port}）：主机可能未启动 SSH 服务，或端口不对。`;
+    }
+    if (/ETIMEDOUT|timed out/i.test(message)) {
+        return `连接超时（${server.host}:${server.port}）：网络不可达，或需要跳板机。`;
+    }
+    if (server.authType === 'OPEN_SSH' && /agent|no auth/i.test(message)) {
+        return `这台的认证方式是 OpenSSH（ssh-agent / ~/.ssh/config），但本机没有可用的 agent 或私钥：` +
+            `确认 SSH_AUTH_SOCK 已设置、或 ~/.ssh/config 里配了 IdentityFile。`;
+    }
+    return `SSH 执行失败（${server.name}）：${message}`;
+}

package/src/remote/ssh.test.js

@@ -0,0 +1,48 @@
+// SSH 层的纯函数测试：命令包装、引用、错误翻译。真连接只能手工验证。
+
+import {describe, expect, it} from 'vitest';
+
+import {describeSshError, expandTilde, shellQuote, withWorkingDirectory} from './ssh.js';
+
+describe('shellQuote', () => {
+    it('包住单引号并在内部转义', () => {
+        expect(shellQuote('/data/app')).toBe("'/data/app'");
+        expect(shellQuote("it's")).toBe(`'it'\\''s'`);
+    });
+});
+
+describe('withWorkingDirectory', () => {
+    it('没传目录时原样返回', () => {
+        expect(withWorkingDirectory('ls', undefined)).toBe('ls');
+        expect(withWorkingDirectory('ls', '   ')).toBe('ls');
+    });
+
+    it('绝对路径直接 cd', () => {
+        expect(withWorkingDirectory('ls', '/data/app')).toBe("cd '/data/app' && ls");
+    });
+
+    it('~ 展开成远程 $HOME，而不是字面量 ~', () => {
+        expect(withWorkingDirectory('ls', '~')).toBe('cd "$HOME" && ls');
+        expect(withWorkingDirectory('ls', '~/app')).toBe('cd "$HOME"/\'app\' && ls');
+    });
+});
+
+describe('expandTilde', () => {
+    it('只展开开头的 ~', () => {
+        expect(expandTilde('/a/~/b')).toBe('/a/~/b');
+    });
+});
+
+describe('describeSshError', () => {
+    const target = {name: 'mbp', host: '10.0.0.1', port: 22, username: 'root', source: 'ide'};
+
+    it('认证失败给出可执行的下一步', () => {
+        expect(describeSshError(new Error('All configured authentication methods failed'), target))
+            .toContain('认证失败');
+    });
+
+    it('连接拒绝 / 超时各有自己的文案', () => {
+        expect(describeSshError(new Error('connect ECONNREFUSED'), target)).toContain('连接被拒绝');
+        expect(describeSshError(new Error('Timed out while waiting for handshake'), target)).toContain('连接超时');
+    });
+});