Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* protocol — remote file-service 的 NDJSON JSON-RPC 线协议定义。
*
* 传输:SSH exec channel stdio。client(desktop main)把请求逐行写进 daemon
* 的 stdin,daemon 把响应/通知逐行写回 stdout;stderr 专走日志。daemon 生命
* 周期 = channel 生命周期(stdin EOF 即退出),没有常驻状态要迁移,断线后
* 重新 exec 一个新进程即可。
*
* 版本策略:
* - `FILE_SERVICE_SCHEMA_VERSION` 是协议兼容性判据。client handshake 时带上
* 自己的版本,不相等即视为不兼容 → 上层重推 bundle(bundle ~几百 KB,重推
* 是秒级操作,所以不做向后兼容协商,严格相等最简单)。
* - `FILE_SERVICE_BUNDLE_VERSION` 标识实现版本,行为变化时手动 bump。
* Desktop 会在 probe 的 bundle 版本不匹配时重推,即使 schema 兼容。
*
* 帧类型三种,全部单行 JSON:
* - Request (client → daemon): { id, method, params }
* - Response (daemon → client): { id, ok: true, result } | { id, ok: false, error }
* - Event (daemon → client): { event, data } —— 无 id,搜索流(P3)、
* watch 事件(P4)用;P1 不发任何 event,但解码层从第一版就支持,协议不用改。
*
* 二进制内容:readFile 走 UTF-8 文本(scanner 层已拦二进制文件);后续媒体
* 下行(P4)预留 readFileBase64 方法位,届时内容 base64 进 JSON string,单帧
* 上限由 MAX_FILE_BYTES(2 MiB → base64 ~2.7 MB)兜底,decoder 缓冲远大于此。
*/
import type {
DirEntry,
FileReadResult,
FileStat,
ListAllFilesResult,
SearchEvent,
} from '@cindy/file-browser-core';
/** 协议兼容版本:client 与 daemon 严格相等才可用。改动任何请求/响应形状时 +1。 */
export const FILE_SERVICE_SCHEMA_VERSION = 3;
/** 实现版本;含共享扫描器在内的行为变化需 bump,使已安装的远端自动更新。 */
export const FILE_SERVICE_BUNDLE_VERSION = '0.2.7';
/* ============================== 帧 ============================== */
export interface FsRpcRequest {
id: number;
method: string;
params?: unknown;
}
export interface FsRpcError {
/** 稳定错误码,client 侧据此分支(见 FS_RPC_ERROR_CODES)。 */
code: FsRpcErrorCode;
/** 人读信息,进日志;不要求可 i18n(renderer 层按 code 映射文案)。 */
message: string;
}
export type FsRpcResponse =
| { id: number; ok: true; result: unknown }
| { id: number; ok: false; error: FsRpcError };
export interface FsRpcEvent {
event: string;
data: unknown;
}
export type FsRpcFrame = FsRpcResponse | FsRpcEvent;
/** daemon → client 帧的运行时判别。 */
export function isFsRpcResponse(v: unknown): v is FsRpcResponse {
return (
typeof v === 'object' &&
v !== null &&
typeof (v as { id?: unknown }).id === 'number' &&
typeof (v as { ok?: unknown }).ok === 'boolean'
);
}
export function isFsRpcEvent(v: unknown): v is FsRpcEvent {
return (
typeof v === 'object' &&
v !== null &&
typeof (v as { event?: unknown }).event === 'string'
);
}
/** client → daemon 帧的运行时判别(daemon 侧用)。 */
export function isFsRpcRequest(v: unknown): v is FsRpcRequest {
return (
typeof v === 'object' &&
v !== null &&
typeof (v as { id?: unknown }).id === 'number' &&
typeof (v as { method?: unknown }).method === 'string'
);
}
/* ============================== 错误码 ============================== */
export const FS_RPC_ERROR_CODES = [
/** scanner 判定为二进制文件(读路径的预期分支,renderer 渲染不可预览卡)。 */
'BINARY_FILE',
/** 版本不匹配:daemon schema ≠ client schema,上层应重推 bundle。 */
'SCHEMA_MISMATCH',
/** 参数缺失/形状不对。 */
'BAD_REQUEST',
/** 远端没有可用 ripgrep(搜索 / 文件名索引的预期降级分支,renderer 按码映射友好文案)。 */
'RG_UNAVAILABLE',
/** 未知 method(通常也是版本偏斜的症状)。 */
'UNKNOWN_METHOD',
/** 其余一切执行失败(fs 错误、路径越界拒绝等),message 带原始描述。 */
'OPERATION_FAILED',
] as const;
export type FsRpcErrorCode = (typeof FS_RPC_ERROR_CODES)[number];
/* ============================== 方法表 ============================== */
/**
* 方法名 → { params, result } 的类型表。client.request 与 daemon 分发共用,
* 两端不可能对同一方法产生不同理解(编译期对齐)。
*/
export interface FsRpcMethods {
/** 握手:校验 schema、回报 daemon 自身信息。client 连上后必须首发。 */
handshake: {
params: { clientSchemaVersion: number };
result: {
schemaVersion: number;
bundleVersion: string;
pid: number;
/** daemon 端 process.platform(远端一律 POSIX;'win32' 视为不支持)。 */
platform: string;
/** 远端 ripgrep 是否可用(--rg 启动参数已传且存在);决定搜索/文件名索引能力。 */
rgAvailable: boolean;
};
};
listDir: {
params: {
workdir: string;
relPath?: string;
hideMetaFiles?: boolean;
docMode?: boolean;
/**
* 完全绕过展示过滤(手机 HTML 快照枚举用)。可选 / append-only:老 daemon
* 忽略未知字段 → 维持隐藏语义(拿不到全量,但不会报错)。
*/
includeIgnored?: boolean;
/** 条目上限;超出时 daemon 返回 DIRECTORY_TOO_LARGE。 */
maxEntries?: number;
/**
* 控制端「显示被忽略的目录」开关。可选 / append-only:老 daemon 忽略未知
* 字段 → 维持隐藏语义(拿不到放行,但不会报错)。
*/
showIgnoredDirs?: boolean;
};
result: { entries: DirEntry[] };
};
readFile: {
params: { workdir: string; relPath: string };
result: FileReadResult;
};
/**
* 大文件分片读:按 [offset, offset+length) 返回 base64 字节片(与 readFile 的
* 2MiB 文本截断语义无关,任意大小文件可完整拉回)。安全校验与 readFile 同源
* (assertInsideWorkdir + realpath);单片 length 上限 daemon 侧钳制 1MiB,
* base64 后 ~1.37MB,远低于 NDJSON 解码缓冲。
*/
readFileChunk: {
params: { workdir: string; relPath: string; offset: number; length: number };
result: {
/** base64 字节片;eof 且 offset 超界时为空串。 */
dataBase64: string;
/** offset+片长 ≥ 文件大小,即已是最后一片。 */
eof: boolean;
/** 整文件大小(bytes),供 caller 预分配/进度。 */
size: number;
mtimeMs: number;
};
};
stat: {
params: { workdir: string; relPath: string };
result: FileStat;
};
writeFile: {
params: { workdir: string; relPath: string; content: string };
result: { size: number; mtimeMs: number };
};
createFile: {
params: { workdir: string; relPath: string };
result: FileStat;
};
createFolder: {
params: { workdir: string; relPath: string };
result: FileStat;
};
renameEntry: {
params: { workdir: string; fromRel: string; toRel: string };
result: FileStat;
};
deleteEntry: {
params: { workdir: string; relPath: string };
result: { ok: true };
};
listAllFiles: {
params: { workdir: string; cap?: number };
result: ListAllFilesResult;
};
searchStart: {
params: { workdir: string; query: string; caseSensitive: boolean; maxMatches: number };
result: { searchId: string };
};
searchCancel: {
params: { searchId: string };
result: { ok: true };
};
/**
* 订阅某个 workdir 的文件事件。`consumerId` 标识订阅方(desktop 文件树 /
* device-link 被控端 watch),可选 —— 老调用方缺省即归到默认消费者。
* 同一 workdir 的多个消费者各自登记过滤需求,daemon 取**可见性并集**
* (见 WorkdirWatchManager),不会互相覆盖 matcher。
*/
watchStart: {
params: {
workdir: string;
hideMetaFiles?: boolean;
showIgnoredDirs?: boolean;
consumerId?: string;
};
result: { ok: true };
};
watchStop: {
params: { workdir: string; consumerId?: string };
result: { ok: true };
};
}
export type FsRpcMethodName = keyof FsRpcMethods;
/* ============================== 事件 ============================== */
/**
* daemon → client 的事件负载表(FsRpcEvent.event → data 形状)。
*/
export interface FsRpcEvents {
search: SearchEvent;
fileTree: { workdir: string; type: 'add' | 'change' | 'unlink'; relPath: string };
}
export type FsRpcEventName = keyof FsRpcEvents;