Skip to main content
Glama

牵丝 Filaxis

CI npm version License: Apache-2.0 Glama MCP Server

简体中文 · English

千里一线,执行有迹。—— Connect · Execute · Observe · Reattach

面向自动化与 Agent 的远程执行运行时 SDK(Syrkos · 漩核旗下)。TypeScript 编写,Bun 与 Node LTS 双运行时,Windows 与 Linux 同构。CLI / SDK / MCP Server 三入口(filaxis / createAgentToolkit / filaxis-mcp)共享同一工具词汇表;CI 覆盖(均在 Ubuntu runner):Bun 侧跑全量测试与 SSH 自环集成,Node 侧跑类型检查、边界检查、构建与编译版 CLI 冒烟(Node 不重复运行完整测试套)。

import { RuntimeStack } from "@syrkos/filaxis";

const stack = new RuntimeStack();
const host = await stack.connect({ driver: "ssh", target: "my-server" });

// exec:退出码是数据,失败是异常;stdout/stderr 物理分离
const r = await host.exec("uname -a", { timeoutMs: 10_000 });
console.log(r.stdout, r.stderr, r.exitCode, r.effectiveUser);

// 长跑会话:execSession 即返(句柄含 sessionId/logBase/pid)→ 观察 → 停止核实
const cap = await host.execSession("tcpdump -i eth0 -c 100 -w /tmp/x.pcap");
console.log(cap.sessionId, cap.logBase);                       // 句柄字段
console.log((await host.tailSession(cap.sessionId, 10)));      // 热窗口快照(最近 10 行)
const stop = await host.stopSession(cap.sessionId);            // 三态:exited/stopped/unknown
if (stop.status === "unknown") {
    const v = await host.verifySession(cap.sessionId);         // 核实原语(unknown 闭环)
    console.log("实测:", v.status, v.exitCode);                // running / exited(码) / unknown
}

// 事件(零消息队列依赖——消费方自行接队列/看板)
stack.events.on("exit", (e) => console.log("session", e.sessionId, "exit", e.exitCode));

能力矩阵

「成熟度」列:内置=开箱即用且 CI 真机覆盖;可接入=经配置/适配层支持(示例或文档指引);实验=有实现但真机覆盖薄,欢迎试用与反馈。

能力

成熟度

说明

多 Transport 统一语义

内置(local/ssh)/ 可接入(docker/k8s/teleport)

local / ssh / tmux 内置 + registerDriver() 开放注册;docker/k8s/teleport 经 launchCmd(如 "docker exec -it <ctr> bash")接入——能力同权,语义契约一致

exec 双通道

内置

缺省非 PTY 通道(stdout/stderr 物理分离 + 层上下文拼装:cwd/env/enter 进入管线在独立通道按需重放——docker exec 进的容器 exec 也直达);channel:"pty" 继承层内交互状态

长跑会话生命周期

内置

execSession 即返、双文件 .out/.err 落盘、热窗口、行级 watcher、终态三态 exited/stopped/unknown + verifySession 核实原语

ready() 就绪握手

内置

回溯匹配热窗口(快输出进程竞态根治);滚出判定有据(evictedCount)

观察流

内置

独立 SSH channel 真流式直推(无轮询);ControlMaster 复用;注意力衰减回收

持久会话

内置

tmux 后端 terminalId 跨进程 re-attach + cwd 恢复

文件传输

内置

putFile/getFile base64 管道分块 + size/sha256 双校验 + 方言适配(GNU/BSD/busybox——OPNsense/Alpine 不再必错)

受控编辑

内置

editFile CAS 原子写回(写入形态/锁保护/校验等级三轴显式报告,见 AGENTS.md 第 8 条)

环境规格

内置

两段式自发现(语言/GPU/关键包)蒸馏落盘;matchLayers({needs}) 按需选层;指纹漂移标 stale

连接治理

内置

连接拓扑指纹复用(同拓扑零重建);3 次退避自动重连;层状态机与退化哨兵

安全边界

内置

host key 策略显式(tofu 缺省/strict+known_hosts);凭据只传路径永不外泄;渲染永不含密钥内容

Related MCP server: Menager MCP Server

安装与运行时

bun add @syrkos/filaxis    # 或 npm install @syrkos/filaxis
  • 运行时:Bun ≥1.x / Node LTS(内核统一 node: 标准库,零 runtime 专有 API——CI lint 断言)

  • npm 依赖:零(dependencies 为空是 AC 门禁项,见 bun run check:boundaries)

  • 系统依赖按能力分列(stack.features() 探测本机视角——Agent 在容器里跑 filaxis 时探测的是容器内的 ssh/tmux/sftp,目标主机的能力经 launchCmd 层的 shell 自行确认):ssh≥7.3 全功能(-J)、tmux 仅持久会话(缺席自动降级非持久)、sftp 仅传输快路径

MCP 配置与 Agent Skill

npm i -g @syrkos/filaxis
filaxis mcp-config                # JSON,使用 mcpServers
filaxis mcp-config --format toml  # TOML,使用 mcp_servers(Codex)

命令把 MCP 配置片段写到标准输出,包含当前运行时和 filaxis-mcp 入口的绝对路径。Agent 根据自身平台和所需作用域选择配置位置,再将片段合并到现有配置。

也可直接在 MCP 客户端配置中通过 npx 启动:

{
  "mcpServers": {
    "filaxis": {
      "command": "npx",
      "args": ["-y", "-p", "@syrkos/filaxis", "filaxis-mcp"]
    }
  }
}

暴露的 15 个 MCP 工具速览:

  • 命令与批处理:run_command、run_batch

  • 长跑会话与观察窗:spawn_and_observe、stop_and_verify、observe_stream、read_stream、close_stream

  • 文件读写与传输:read_file、edit_file、put_file、get_file

  • 多层连接管理:push_ssh、push_into、list_layers、remove_layer

npm 包包含 Skill 入口与四份子剧本,以及配套的 AGENTS.md。需要登记 Skill 时,由 Agent 按自身平台的规则处理这些文件。

CLI 文件传输

filaxis put --layer app -- ./config.yaml /app/config.yaml
filaxis get --host user@host --transport sftp -- /var/tmp/result.bin ./result.bin

put/get 传输单个文件,支持 --layer 和 --host。默认用层的 exec 通道,可进入容器。SSH 目标的文件系统可直接访问时,可显式选择 --transport sftp,包括经 -J 跳板的连接。两条路径都先校验暂存文件再落位,JSON 结果标明校验等级和写入形态。详见 文件同步剧本。

MCP 对应工具是 put_file 和 get_file。local_path 位于 MCP 服务所在机器,remote_path 位于目标层。可用 layer 选择命名层。

已验证的平台与连接方式

操作系统

连接方式

验证范围

Windows

本地执行(Git Bash)

本地命令、长跑会话、观察窗、Windows Job 子进程回收

Ubuntu Linux

本地执行(WSL)、本地 tmux、CI SSH 回环

本地会话与观察窗、tmux 持久会话重挂与停止、SSH 集成测试。tmux 的 watcher 接管尚未实现

Debian GNU/Linux

SSH 直连

非交互 exec、交互 PTY、持续观察窗、重连后接管会话与 watcher、核实停止、文件操作

Debian GNU/Linux

SSH 单跳(ProxyJump / -J)

非交互 exec、stdout 与 stderr 分离

Alpine Linux

SSH 到 Linux 宿主后经 docker exec 进入容器

容器内非交互执行与受控文件编辑

OPNsense(FreeBSD)

SSH 直连(非交互 exec)

命令执行、目录读取、文件写入与覆盖时保留权限。默认交互登录进入设备菜单,PTY 握手在该配置下不可用

SSH 文件中转模式

运行环境限制匿名管道时,可在启动 CLI 或 MCP 服务前设置 FILAXIS_SSH_STDIO_MODE=inherit。使用 SDK 时,在建立 SSH 层前设置。该模式通过临时文件为 SSH 提供标准输入和双流输出。命名层使用非交互探测核实目标和工作目录,后续执行仍以完成哨兵确认退出码。

Windows 上,Filaxis 启动 OpenSSH 子进程时会补齐缺失的系统和账户环境变量,包括 SystemRoot、windir、ProgramData 和 USERNAME。已有值优先,补全只作用于子进程。成功补齐 SystemRoot 时,CLI 和 MCP 会在 stderr 告警一次,SDK 通过注入的 logger 记录。主机剥离这些变量和主机限制匿名管道是两类独立问题。

支持免交互认证的直连、单跳 connParams.jump(CLI -J)及可非交互重放的进入步骤。逐跳 PTY 登录链、交互式进入、持久端口转发和持续观察窗需要可用的匿名管道。会话日志可用 readSessionLog 读取落盘内容。

SSH 秒退 255 且双流为空只能作为排障线索。执行终态未知时,先核实远端状态再决定是否重发。

语义契约要点(使用前必读)

详见包内 AGENTS.md——终止即请求、死亡须核实(unknown 不是失败也不是成功);退出码非零是数据不是异常;PTY 通道 stderr 混流是终端语义;跨流聚合序为到达序。

示例与技能剧本

  • examples/:跨主机诊断 / 长跑观察 / Agent 工具面最小封装(三可运行示例)

  • docs/skills/:场景操作剧本(给人也给 Agent)

Benchmark(真实运维对照评测)

四期受控实战评测(涵盖 v0.1.0 ~ v0.2.5,内网与跨地域多跳、明盒与纯黑盒场景;每期内采用同模型对照,跨期因版本、考题与模型档位不同不可直接横向等同)的完整数据、方法论与局限说明见 benchmark.md。

最新一期(第四份:v0.2.5 跨地域无 ProxyJump 真实堡垒机、0 提示纯黑盒 9 处联动故障 + 跨海 PUT/GET 二进制文件传输,Gemini 4 Hydrogen 轻量档位子代理,四组均 100% 达标)总账:

组别

方式

轮数

耗时

报错/摩擦

全量活跃 Token (in+out)

纯实战活跃 Token (去文档预读)

总吞吐 Token (含 cache)

牵丝 MCP

filaxis-mcp 原生工具

14

225s (3m45s)

0

81,297

50,362

561,736

牵丝 SDK

@syrkos/filaxis TS 编排

18

273s (4m33s)

0

104,563

67,823

890,017

牵丝 CLI

filaxis + SKILL.md

22

368s (6m08s)

3

106,587

79,535

1,051,857

裸 SSH

原生 ssh / scp + shell

24

483s (8m03s)

4

107,151

86,917

999,825

在跨地域无 -J 纯黑盒排障场景下,牵丝 MCP 组达成 0 报错、墙钟耗时缩短 53.4%、全量活跃 Token 省 24.1%(剥离文档预读的纯实战活跃 Token 省 42.1%、总吞吐省 43.8%)。需要说明的是:上述结果为单次实战采样(非多随机种子统计),且在路径明确的简单局域网任务中裸 SSH 与牵丝差距较小(见报告第一份测试二);牵丝的效率与稳定性优势主要集中在无路径提示、多跳穿透与多故障联动排障场景。

许可

Apache-2.0 + NOTICE(牵丝 Filaxis / Syrkos · 漩核 品牌归属声明)。

Available Tools

15 tools
close_streamA

关闭由 observe_stream 打开的本地观察窗,确认终止并回收对应的远端观察流进程与通道资源,返回 { window_id, closed: true }。观察完成后应及时调用以防残留流进程;若 window_id 不存在或已关闭则报错(不影响其他观察窗)。

Inputs: window_id (required).

edit_fileA

受控编辑远端文件:精确替换(唯一命中校验,all=true 全替换)+ TOCTOU 乐观锁(他人先写则拒绝)+ base64 保真写回(零 Shell 转义——绝不 sed -i)。未命中/多处命中/冲突均报错不盲写。返回 write_mode:atomic-replace=原子替换;inplace-write=保留 inode(bind mount 挂载点 mv 不可用降级)——非原子写入,中断可暴露半截。

Inputs: new (required), old (required), path (required), all, +2 more.

get_fileA

从目标层下载单个文件到 MCP 服务所在机器(支持二进制)。先传输至本地暂存文件并校验大小与 SHA-256 后再落位,校验失败不破坏已有本地文件;成功时会覆盖已存在的 local_path,返回传输通道、字节大小、校验等级 (verification) 与写入形态 (write_mode)。仅读取远端小文本请用 read_file,批量传输多个文件请使用 run_batch。

Inputs: local_path (required), remote_path (required), layer, transport, +1 more.

list_layersA

列出全部命名层(链路/状态/有效用户/默认层标记)。死层/退化层有警示标注(removeLayer 后按原参数重建)。

Inputs: no named parameters.

observe_streamA

直接启动一条持续输出命令并打开本地滚动观察窗,立即返回 window_id(不等待命令结束)。适用于实时盯日志或持续监控输出(如 tail -f、事件流),配合 read_stream 按游标非破坏回看/翻页/续读,完成后用 close_stream 关闭并回收远端流进程。若需后台起停服务、等待就绪标记并核实进程退出码,请改用 spawn_and_observe + stop_and_verify。

Inputs: command (required), name, layer, stream.

push_intoA

从默认层(或 from 指定层)进入内层 shell(docker exec -i sh / kubectl exec 等)——enter 管线全量继承追加(父层 docker→再 su 不丢)。新层成为默认层。需 ssh 层为源。

Inputs: enter_cmd (required), from, name, label.

push_sshA

建立命名 ssh 层(成为默认层——后续工具缺省落它)。同落点幂等复用(reused=true 返回既有层,不重复建连)+ 落点校验(宁重连不错主机)。跳板传 jump(-J 不占层)。

Inputs: host (required), key, jump, name, +2 more.

put_fileA

从 MCP 服务所在机器上传一个文件到目标层。支持二进制,校验后落位,可能覆盖目标文件。返回校验等级和写入形态。

Inputs: local_path (required), remote_path (required), layer, transport, +2 more.

read_fileA

只读获取目标层中的 UTF-8 文本文件(不修改远端状态),返回 { path, content, size, mtime_ms }。文件不存在、无权限或层不支持元数据时报错;下载二进制文件请改用 get_file,同时读多个文件优先使用 run_batch,后续受控修改请配合 edit_file。

Inputs: path (required), layer.

read_streamA

读取本地观察窗。可读最近帧、按 before_seq 向前翻页、按 window_ms 回看或按 since_seq 续读。每次续读用 last_delivered_seq,gap 表示游标区间有丢失。

Inputs: window_id (required), limit, wait_ms, since_seq, +2 more.

remove_layerA

移出命名层(缺省连接保留在指纹缓存——再建同层零成本;destroy=true 才真销毁连接)。

Inputs: name (required), destroy.

run_batchA

批次组合:一次调用描述多个文件或命令操作(exec/edit/read/put/get),按依赖边(after)拓扑执行——步骤 layer 可覆盖批次 layer;after 可跨层引用步骤 id。无依赖步骤并行,顺序链靠 after 显式保序;默认任一步失败即停(未启动步骤标 skipped)。返回逐步骤状态与证据(退出码/输出/编辑明细)。不做自动回滚(配置恢复≠运行状态回滚——重载可能已产生外部副作用),失败现场交回调用方决策。

Inputs: steps (required), layer, output, max_parallel, +1 more.

run_commandA

执行会自行结束的一次性命令(多条命令/多文件操作请改用 run_batch 一次并行打包;持续盯实时输出且不关心退出码的命令如 tail -f 请改用 observe_stream 直接启动并流式读取;需后台起停服务、等就绪标记并核实进程退出码的任务请改用 spawn_and_observe)。退出码如实返回(非零不是异常——是数据,供条件分支);只有无法执行(超时/中断/连接死)才报错。stdout 与 stderr 分离返回。

Inputs: command (required), layer, timeout_ms.

spawn_and_observeA

启动后台任务或常驻服务(输出落盘到 log_base 对应的 .out/.err 文件,立即返回 session_id 与 log_base 句柄不阻塞)。适用于需要等待就绪标记(ready_marker——回溯热窗口,快输出竞态安全)、自动捕获错误模式(error_pattern——命中即收摊)并在结束后用 stop_and_verify 核实进程终态与退出码的场景。若只需持续流式查看实时输出(如 tail -f / 监控日志)并按游标翻页续读,请改用 observe_stream + read_stream。

Inputs: command (required), name, layer, ready_marker, +1 more.

stop_and_verifyA

停止任务并核实终态。status 三态:exited=拿到退出码;stopped=终止已核实;unknown=核实不可达(非成功非失败——重试核实或显式上报,严禁当已清理)。

Inputs: session_id (required), layer.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation4/5

    The execution-oriented tools (run_command, run_batch, spawn_and_observe, observe_stream) overlap conceptually, but their descriptions explicitly cross-reference each other and define crisp boundaries (one-shot vs batch vs background-with-readiness vs live tail). The stream family (observe_stream/read_stream/close_stream) and file family (read/edit/put/get) are cleanly separated. The only residual confusion is choosing between spawn_and_observe and observe_stream, which requires reading the fine print.

    Naming Consistency5/5

    Every tool follows a snake_case verb_noun pattern (run_command, read_file, edit_file, put_file, get_file, push_ssh, list_layers, remove_layer). Compound verbs like spawn_and_observe and stop_and_verify are a minor stylistic variation but still fit the same convention. The get/put vs read/write vocabulary is used coherently per family.

    Tool Count5/5

    15 tools map onto four coherent sub-domains: execution (4), files (4), streaming (3), and layers (4). Each tool serves a distinct role in one of these workflows, and the count sits within the well-scoped range for a remote shell/execution platform.

    Completeness4/5

    Core CRUD and lifecycle are covered: exec (run_command/run_batch), background lifecycle (spawn_and_observe/stop_and_verify), streaming (observe/read/close), files (read/edit/put/get), and layers (push_ssh/push_into/list/remove). Gaps remain: no directory-listing tool, no file delete, and no way to pop/switch back to a prior layer as default. These are largely workaroundable via run_command (ls/rm) or remove_layer, so coverage is strong but not complete.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents or human operators to spawn, monitor, drive, and hook into child terminal sessions—such as CLI tools, interactive shells, and polyglot runtimes—via POSIX pseudo-terminals, providing multiplexed control, event interception, and memory-bounded observability for orchestration.
      GPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to spawn and control persistent local shells, SSH sessions, REPLs, debuggers, and serial/UART devices with zero-loss output capture, timestamped history, and atomic expect matching for command execution and prompt synchronization.
      12
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to remotely execute shell commands and transfer files on SSH hosts, including jump-host tunneling, background tasks, resumable transfers, and optional approval of destructive commands, while SSH credentials remain in the local process. It runs over stdio or a streamable HTTP daemon and supports auditing, allow/deny lists, and multiple authentication methods.
      ISC