Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* ssh/_shared.ts —— cindy_ssh 工具家族的共享 helper。
*
* 设计原则(规则 9:确定性进代码,不靠 prompt):
* - 主机名解析、cwd 引号包装、输出截断、错误分类全部在这里用代码保证,
* agent 只负责传"用户想连哪台机、跑什么命令"。
* - 任何 error payload / 日志都不携带 command 原文——maker-remote-ssh 模块
* 红线:调用方可能把密钥内联在命令里,回显会经统一日志路径落盘。
*/
import type { SshHostSnapshotLike, SshMcpDeps, SshPoolLike } from '../types.js';
import type { SshToolResult } from './registry.js';
// ── payload helpers(与 xdt-helper/_payload.ts 同形) ───────────────────────
export function okPayload(data: Record<string, unknown>): SshToolResult {
return {
content: [{ type: 'text', text: JSON.stringify({ ok: true, ...data }) }],
};
}
export function errorPayload(
errorCode: SshErrorCode,
hint: string,
extra?: Record<string, unknown>,
): SshToolResult {
return {
content: [
{
type: 'text',
text: JSON.stringify({
ok: false,
errorCode,
data: { hint, ...(extra ?? {}) },
}),
},
],
isError: true,
};
}
export type SshErrorCode =
| 'HOST_NOT_FOUND'
| 'AMBIGUOUS_HOST'
| 'SSH_AUTH_FAILED'
| 'SSH_KEY_FILE_NOT_FOUND'
| 'SSH_AGENT_UNAVAILABLE'
| 'SSH_CONFIG_AUTH_UNSUPPORTED'
| 'SSH_CONNECT_FAILED'
| 'EXEC_TIMEOUT'
| 'PLUGIN_DISABLED'
| 'HOST_ALREADY_EXISTS'
| 'INVALID_ARGS'
| 'SSH_CONFIG_RELOAD_REQUIRED'
| 'SSH_CONFIG_WRITE_FAILED'
| 'INTERNAL';
/**
* 主机只能用密码登录时的标准做法。askpass 代输入:本机任务命令行里的 ssh 要口令时,
* Cindy 直接向用户弹卡片索取并交回 ssh,值不经过模型(docs/product-rules/input-handoff.md §5)。
*/
export const PASSWORD_LOGIN_HINT =
'主机目前只能用密码登录时,先在本机任务的命令行运行 `ssh-copy-id -i ~/.ssh/<公钥>.pub [-p 端口] 用户@主机` 装上公钥'
+ '(没有密钥就先 ssh-keygen 生成):ssh 要密码时 Cindy 会直接弹卡片让用户输入,你看不到密码(macOS / Linux)。'
+ '不要在聊天里向用户索要密码。';
// ── host resolution ─────────────────────────────────────────────────────────
/** ssh_list_hosts / HOST_NOT_FOUND 候选清单共用的精简视图。 */
const REDACTION_FAILURE_TEXT = 'SSH error details are unavailable.';
/** Fail closed if the host redactor is unavailable; never log either input. */
export function safeRedactSensitiveText(
deps: Pick<SshMcpDeps, 'redactSensitiveText'>,
snapshot: SshHostSnapshotLike,
text: string,
): string {
try {
return deps.redactSensitiveText(snapshot, text);
} catch {
return REDACTION_FAILURE_TEXT;
}
}
export function hostBrief(
s: SshHostSnapshotLike,
deps: Pick<SshMcpDeps, 'redactSensitiveText'>,
): Record<string, unknown> {
return {
id: s.config.id,
hostname: s.config.hostname,
port: s.config.port,
user: s.config.user,
authMethod: s.config.authMethod,
status: s.status,
...(s.lastAuthLabel ? { lastAuthLabel: s.lastAuthLabel } : {}),
...(s.lastError ? { lastError: safeRedactSensitiveText(deps, s, s.lastError) } : {}),
};
}
export type ResolveHostResult =
| { ok: true; snapshot: SshHostSnapshotLike }
| { ok: false; result: SshToolResult };
/**
* 把用户口中的"某台机器"解析成已配置主机:
* 1. alias(config.id)精确匹配 —— 唯一主键,直接命中;
* 2. hostname(IP / 域名)精确匹配 —— 唯一命中放行,多命中要求改用 alias;
* 3. 都没有 → HOST_NOT_FOUND,附现有主机清单引导用户去「设置 → 远程连接」添加
* (v1 刻意不支持连未配置的主机——那会退回"猜 key / 猜 agent"的老路)。
*/
export function resolveHost(
pool: SshPoolLike,
nameOrIp: string,
deps: Pick<SshMcpDeps, 'redactSensitiveText'>,
): ResolveHostResult {
const snapshots = pool.list();
const byId = snapshots.find((s) => s.config.id === nameOrIp);
if (byId) return { ok: true, snapshot: byId };
const byHostname = snapshots.filter((s) => s.config.hostname === nameOrIp);
if (byHostname.length === 1) return { ok: true, snapshot: byHostname[0] };
if (byHostname.length > 1) {
return {
ok: false,
result: errorPayload(
'AMBIGUOUS_HOST',
`hostname "${nameOrIp}" 命中多台已配置主机,请改用唯一的 alias(candidates 里的 id 字段)指定。`,
{ candidates: byHostname.map((snapshot) => hostBrief(snapshot, deps)) },
),
};
}
return {
ok: false,
result: errorPayload(
'HOST_NOT_FOUND',
`"${nameOrIp}" 不在已配置的 SSH 主机里。确认 alias 拼写;确实没配置时用 ssh_add_host 添加,不要退回手拼 ssh 命令。`,
{ configuredHosts: snapshots.map((snapshot) => hostBrief(snapshot, deps)) },
),
};
}
// ── output truncation ───────────────────────────────────────────────────────
export const OUTPUT_CAP_CHARS = 32_000;
const TAIL_KEEP = 8_000;
// marker 固定预算:head + marker + tail 严格 ≤ OUTPUT_CAP_CHARS(截断后的
// 返回长度是工具对外的上限契约,不能因插入标记而超出)。marker 实际 ~30-45
// 字符,64 给 dropped 位数留足余量。
const MARKER_RESERVE = 64;
const HEAD_KEEP = OUTPUT_CAP_CHARS - TAIL_KEEP - MARKER_RESERVE;
/** stdout / stderr 各自 cap,超限保头留尾,防单条 `cat 大文件` 炸上下文。 */
export function truncateOutput(text: string): { text: string; truncated: boolean } {
if (text.length <= OUTPUT_CAP_CHARS) return { text, truncated: false };
const dropped = text.length - HEAD_KEEP - TAIL_KEEP;
return {
text:
text.slice(0, HEAD_KEEP) +
`\n...[truncated ${dropped} chars]...\n` +
text.slice(text.length - TAIL_KEEP),
truncated: true,
};
}
// ── cwd wrapping ────────────────────────────────────────────────────────────
/** POSIX 单引号安全转义:' → '\''。 */
function shellQuote(value: string): string {
return `'${value.replace(/'/g, `'\\''`)}'`;
}
/** cwd 存在时包装成 `cd '<cwd>' && (command)`,引号处理由代码保证。 */
export function wrapCwd(command: string, cwd?: string): string {
if (!cwd) return command;
return `cd ${shellQuote(cwd)} && (${command})`;
}
// ── error classification ────────────────────────────────────────────────────
/** RemoteHost.exec 超时错误的确定性签名(`${label} timed out after ${ms}ms`)。 */
const EXEC_TIMEOUT_RE = / timed out after \d+ms$/;
/** desktop throwIpcError 的 `[CODE] message` 前缀编码。 */
const IPC_CODE_RE = /^\[([A-Z0-9_]+)\]\s*/;
/** 拆出 desktop throwIpcError 的错误码与正文;无前缀时 code 为 undefined。 */
export function splitIpcError(err: unknown): { code?: string; detail: string } {
const message = err instanceof Error ? err.message : String(err);
const match = IPC_CODE_RE.exec(message);
return match ? { code: match[1], detail: message.slice(match[0].length) } : { detail: message };
}
export interface ClassifiedSshError {
errorCode: SshErrorCode;
hint: string;
}
/**
* best-effort 分类 deps.ensureReady / host.exec 抛出的错误。
* 认证失败的 message 内含 authFailureHint 的可操作提示(如 ssh-copy-id 指引),
* 去掉 main-only 凭证路径后透传进 hint 让 agent 转告用户——认证失败是确定性的,
* 不要重试。
*/
export function classifySshError(
err: unknown,
deps: Pick<SshMcpDeps, 'redactSensitiveText'>,
snapshot?: SshHostSnapshotLike,
): ClassifiedSshError {
const rawMessage = err instanceof Error ? err.message : String(err);
const message = snapshot ? safeRedactSensitiveText(deps, snapshot, rawMessage) : rawMessage;
if (EXEC_TIMEOUT_RE.test(message)) {
return {
errorCode: 'EXEC_TIMEOUT',
hint:
'命令执行超时。长任务请改成后台运行再轮询结果,例如 `nohup <cmd> > /tmp/task.log 2>&1 &`,随后用 ssh_exec 查看日志文件。',
};
}
const { code, detail } = splitIpcError(message);
switch (code) {
case 'SSH_HOST_NOT_FOUND':
return {
errorCode: 'HOST_NOT_FOUND',
hint: `主机不存在:${detail}。用 ssh_list_hosts 查看已配置主机。`,
};
case 'SSH_AUTH_FAILED':
return {
errorCode: 'SSH_AUTH_FAILED',
hint: `SSH 认证失败(确定性错误,重试无效):${detail}。${PASSWORD_LOGIN_HINT}`,
};
case 'SSH_KEY_FILE_NOT_FOUND':
return {
errorCode: 'SSH_KEY_FILE_NOT_FOUND',
// Strip the raw-error prefix (identity file not found: ) so the hint
// doesn't mix an English prefix into the localized message — same
// treatment the renderer toast applies.
hint: `配置的私钥文件在本机磁盘上不存在/不可读(本机路径问题,不是网络或服务端错误):${detail.replace(/^identity file not found:\s*/, '')}。请到「设置 → 远程连接」重新选择私钥或编辑主机的 Identity file 路径。`,
};
case 'SSH_AGENT_UNAVAILABLE':
return {
errorCode: 'SSH_AGENT_UNAVAILABLE',
hint: `SSH Agent 当前不可用(重复连接不会自行恢复):${detail}。请启动 ssh-agent,并用 ssh-add 加载对应私钥后重试。`,
};
case 'SSH_CONFIG_AUTH_UNSUPPORTED':
return {
errorCode: 'SSH_CONFIG_AUTH_UNSUPPORTED',
hint: `此主机的部分 SSH 配置规则超出 Cindy 当前支持的子集(重复连接无效,终端 SSH 仍可能成功):${detail}。请检查 Match、条件 Include、IdentityAgent、IdentitiesOnly 和公钥设置。`,
};
default:
return {
errorCode: 'SSH_CONNECT_FAILED',
hint: `SSH 连接/执行失败:${detail}。可用 ssh_host_status 查看主机状态后重试;反复失败请转告用户。`,
};
}
}