@syrkos/filaxis 0.1.0-alpha.12 → 0.1.0-alpha.13

package/dist/runtime-stack.d.ts

@@ -1,6 +1,7 @@
 import type { RuntimeDriver, RuntimeDescriptor } from "./driver.js";
 import { RuntimeFactory } from "./factory.js";
 import { EventBus } from "./events.js";
+import { type SshConnParams } from "./ssh-helpers.js";
 import type { SessionEvent } from "./session-types.js";
 import { type FilaxisLogger } from "./logger.js";
 export type FilaxisEvents = SessionEvent | {
@@ -24,6 +25,23 @@ export interface RuntimeStackOptions {
     logger?: FilaxisLogger;
     factory?: RuntimeFactory;
 }
+/** 命名层句柄（Paramiko 式「连接即句柄」的持有与寻址单元） */
+export interface LayerHandle {
+    /** 层名（注册表内唯一——显式寻址零歧义） */
+    name: string;
+    descriptor: RuntimeDescriptor;
+    driver: RuntimeDriver;
+    /** 落点校验缓存（hostname 实测——宁重连不错主机） */
+    actualHostname?: string;
+}
+/** 层注册表快照（descriptor 即可序列化层身份——可 JSON 落盘跨进程恢复） */
+export interface LayerSnapshot {
+    layers: Array<{
+        name: string;
+        descriptor: RuntimeDescriptor;
+    }>;
+    active?: string;
+}
 export declare class RuntimeStack {
     /** 进程级驱动缓存：同连接拓扑指纹复用既有连接（杜绝孤儿/重复建连） */
     private static driverCache;
@@ -35,7 +53,10 @@ export declare class RuntimeStack {
     /**
      * 连接拓扑指纹（净室移植自源版 driverKey，身份白名单投影）：
      * 显示标签/运行态缓存等非身份字段不进键——不把既有连接挤出缓存、不误建重复连接。
-     * 注：ssh 层的 enterSteps 管线属 ssh Transport 批次，届时并入 cfg 投影。
+     * 环境身份三列（源版同款）：pty 标志 + sshHops 逐跳链 + enters 进入管线（归一化——
+     * legacy enterCmd 与等价 enterPipeline 单步同键）。缺列后果：同 target/connParams
+     * 但进不同容器的两层指纹相同 → connect 复用错连接 → B 容器的命令跑进 A 容器
+     * （「执行环境即 Layer」的身份底线——平移时曾丢列，第十季检查补齐）。
      */
     static driverKey(d: RuntimeDescriptor): string;
     /** 建立层连接：指纹命中即复用（AC-07 连接计数语义） */
@@ -44,6 +65,67 @@ export declare class RuntimeStack {
     static evictDriver(d: RuntimeDescriptor): RuntimeDriver | undefined;
     /** 开放注册（透传 factory；AC-09 第三方 Transport 同权） */
     registerDriver(type: string, f: (descriptor: RuntimeDescriptor) => RuntimeDriver): void;
+    private namedLayers;
+    private activeName?;
+    /** 层注册表只读视图 */
+    get layers(): ReadonlyMap<string, LayerHandle>;
+    /** 默认层 driver（最近注册/setActive 的层；无层时 undefined——消费方自兜底） */
+    get active(): RuntimeDriver | undefined;
+    /** 默认层句柄（含层名；无层时 undefined） */
+    get activeLayer(): LayerHandle | undefined;
+    /**
+     * 注册命名层。descriptor 形态走 connect（指纹复用）+ 回环检测幂等；
+     * driver 形态直接登记现成句柄（pushChild/pushInto 派生产物、消费方自建连接）。
+     * 新层自动成为默认层。
+     */
+    addLayer(name: string, descriptorOrDriver: RuntimeDescriptor | RuntimeDriver): Promise<{
+        handle: LayerHandle;
+        reused: boolean;
+        reusedFrom?: string;
+    }>;
+    /** 从命名层派生进入层（docker exec/kubectl 等——enter 管线全量继承追加） */
+    layerInto(from: string, name: string, enterCmd: string, opts?: {
+        label?: string;
+    }): Promise<LayerHandle>;
+    /** 从命名层链式 ssh 派生子层（本层路径为前缀——途经继承；含回环检测幂等） */
+    sshInto(from: string, name: string, target: string, connParams?: SshConnParams): Promise<{
+        handle: LayerHandle;
+        reused: boolean;
+        reusedFrom?: string;
+    }>;
+    /** 按名取层（不存在时报错并附候选清单） */
+    layer(name: string): LayerHandle;
+    /** 设默认层（显式声明「接下来都在这层干」——无全局焦点指针，最近使用 + 显式声明双轨） */
+    setActive(name: string): LayerHandle;
+    /** 移出注册表（缺省连接保留在指纹缓存可复用；destroy=true 才真销毁） */
+    removeLayer(name: string, opts?: {
+        destroy?: boolean;
+    }): Promise<void>;
+    /** 层清单纯文本（零 ANSI/零表格——npm 零依赖红线；彩色表格留消费方） */
+    layerText(): string;
+    /** 层身份快照（可 JSON 落盘——跨进程恢复的凭证） */
+    snapshot(): LayerSnapshot;
+    /**
+     * 按快照重建（幂等：已在层的名字跳过）：tmux 层 terminalId 命中=零成本 re-attach
+     * （现场全保）；ssh 层=重握手 + enterPipeline 逐条重放（位置确定性恢复）。
+     */
+    restore(snap: LayerSnapshot): Promise<void>;
+    private assertNotDupName;
+    private requireLayer;
+    private isDriver;
+    /**
+     * descriptor 落点 identity（路径末节点）比对既有层全部路径节点。
+     * 判重边界（原版 push_ssh 语义忠实平移）：**只在无 enter 管线的纯 ssh 落点层之间**——
+     * enter 层（容器/内层 shell）的落点是容器而非宿主机，hop identity 管不到（enter 管线
+     * 不进 layerPathIdentities）：同宿主机两个不同容器层会撞 identity + hostname 同为宿主机
+     * → 误幂等返回错容器。enter 层的身份与复用归 driverKey（含 enters 三列）。
+     */
+    private findIdentityHit;
+    /** terminal=true：identity 命中在该层路径**末节点**（同落点构造性成立，免 hostname 探测）；
+     *  false：命中途经节点（identity 撞了中间跳——hostname 落点校验把关） */
+    private findIdentityHopHit;
+    /** 落点校验（宁重连不错主机）：命中层实测 hostname vs 期望 host——不符=identity 撞途经节点 */
+    private verifyLanding;
     /**
      * 能力探测（AC-02：降级不靠猜）。结果缓存至注册表变化。
      * Windows 无 ControlMaster → mux=false（自动退化直连为既定行为）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syrkos/filaxis",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "description": "牵丝 Filaxis — 面向自动化与 Agent 的远程执行运行时 SDK（Syrkos · 漩核）。千里一线，执行有迹。",
   "type": "module",
   "license": "Apache-2.0",

package/src/agent-toolkit.ts

@@ -1,10 +1,13 @@
 /**
- * agent-toolkit.ts — 原生 Agent 工具集（Gemini 试用反馈 #3）
+ * agent-toolkit.ts — 原生 Agent 工具集（Gemini 试用反馈 #3 + 第十季层族）
  *
- * 一行 `createAgentToolkit(stack)` 生成 LLM 工具面（run_command / spawn_and_observe /
- * stop_and_verify）——OpenAI/Anthropic/Vercel AI SDK 通吃的 {tools, handlers} 双层结构：
- * 定义层喂模型，执行层留宿主（桥到任意框架）。语义契约（退出码是数据/终态三态/
- * 就绪握手）由内核承载，宿主零胶水。
+ * 一行 `createAgentToolkit(stack)` 生成 LLM 工具面——OpenAI/Anthropic/Vercel AI SDK
+ * 通吃的 {tools, handlers} 双层结构：定义层喂模型，执行层留宿主（桥到任意框架）。
+ * 语义契约（退出码是数据/终态三态/就绪握手）由内核承载，宿主零胶水。
+ *
+ * 第十季层族：执行类工具带可选 layer 参数（缺省=默认层——最近 push 的命名层；
+ * 未用层族时与旧行为一致，零破坏）；push_ssh/push_into/list_layers/remove_layer
+ * 操作 RuntimeStack 命名层注册表（Paramiko 式句柄寻址——栈/焦点弱化归消费方）。
  */
 import type { RuntimeStack } from "./runtime-stack.js";
 import { editFile } from "./file-edit.js";
@@ -27,15 +30,26 @@ export interface AgentToolHandlers {
     edit_file(args: { path: string; old: string; new: string; all?: boolean; layer?: string }): Promise<{
         path: string; occurrences: number; bytes_before: number; bytes_after: number;
     }>;
-    observe_stream(args: { command: string; duration_ms?: number; stream?: "stdout" | "stderr" | "both"; name?: string }): Promise<{
+    observe_stream(args: { command: string; duration_ms?: number; stream?: "stdout" | "stderr" | "both"; name?: string; layer?: string }): Promise<{
         session_id: string; lines: Array<{ stream: string; text: string }>;
     }>;
-    spawn_and_observe(args: { command: string; ready_marker?: string; error_pattern?: string; name?: string }): Promise<{
+    spawn_and_observe(args: { command: string; ready_marker?: string; error_pattern?: string; name?: string; layer?: string }): Promise<{
         session_id: string; log_base: string; note?: string;
     }>;
     stop_and_verify(args: { session_id: string }): Promise<{
         status: "exited" | "stopped" | "unknown"; exit_code?: number | null; note?: string;
     }>;
+    // ── 层族（第十季命名层注册表——Paramiko 式句柄寻址）──
+    push_ssh(args: { host: string; port?: number; user?: string; key?: string; jump?: string; name?: string }): Promise<{
+        layer: string; reused: boolean; reused_from?: string; note?: string;
+    }>;
+    push_into(args: { enter_cmd: string; label?: string; from?: string; name?: string }): Promise<{
+        layer: string; target?: string;
+    }>;
+    list_layers(args: Record<string, never>): Promise<{
+        text: string; layers: Array<{ name: string; driver: string; target?: string }>;
+    }>;
+    remove_layer(args: { name: string; destroy?: boolean }): Promise<{ removed: string }>;
 }
 
 export interface AgentToolkit {
@@ -66,6 +80,7 @@ const TOOL_DEFS: AgentToolDef[] = [
                 properties: {
                     command: { type: "string", description: "shell 命令" },
                     timeout_ms: { type: "number", description: "超时毫秒（缺省 120000）" },
+                    layer: { type: "string", description: "目标层名（缺省=默认层——最近 push_ssh/push_into 的层）" },
                 },
                 required: ["command"],
             },
@@ -79,13 +94,14 @@ const TOOL_DEFS: AgentToolDef[] = [
                 "启动长跑任务（立即返回句柄不阻塞）。可选就绪标记（ready_marker——回溯热窗口，" +
                 "快输出进程竞态安全）与错误模式（error_pattern——命中即自动收摊防遗忘泄漏）。" +
                 "后续用 stop_and_verify 停止并核实终态。",
-            parameters: {
+                parameters: {
                 type: "object",
                 properties: {
                     command: { type: "string", description: "长跑命令" },
                     ready_marker: { type: "string", description: "就绪标记（如 'listening on'）" },
                     error_pattern: { type: "string", description: "错误模式（命中即收摊）" },
                     name: { type: "string", description: "会话名（人读前缀）" },
+                    layer: { type: "string", description: "目标层名（缺省=默认层）" },
                 },
                 required: ["command"],
             },
@@ -116,6 +132,7 @@ const TOOL_DEFS: AgentToolDef[] = [
                 type: "object",
                 properties: {
                     path: { type: "string" },
+                    layer: { type: "string", description: "目标层名（缺省=默认层）" },
                 },
                 required: ["path"],
             },
@@ -135,6 +152,7 @@ const TOOL_DEFS: AgentToolDef[] = [
                     old: { type: "string", description: "待替换片段（含足够上下文唯一）" },
                     new: { type: "string" },
                     all: { type: "boolean", description: "多处命中全替换（缺省报错）" },
+                    layer: { type: "string", description: "目标层名（缺省=默认层）" },
                 },
                 required: ["path", "old", "new"],
             },
@@ -154,11 +172,77 @@ const TOOL_DEFS: AgentToolDef[] = [
                     duration_ms: { type: "number", description: "观察时长（缺省 8000）" },
                     stream: { type: "string", enum: ["stdout", "stderr", "both"], description: "流过滤（缺省 both）" },
                     name: { type: "string" },
+                    layer: { type: "string", description: "目标层名（缺省=默认层）" },
                 },
                 required: ["command"],
             },
         },
     },
+    {
+        type: "function",
+        function: {
+            name: "push_ssh",
+            description:
+                "建立命名 ssh 层（成为默认层——后续工具缺省落它）。同落点幂等复用（reused=true 返回既有层，" +
+                "不重复建连）+ 落点校验（宁重连不错主机）。跳板传 jump（-J 不占层）。",
+            parameters: {
+                type: "object",
+                properties: {
+                    host: { type: "string", description: "目标主机（user@host 或 ssh config 别名）" },
+                    port: { type: "number", description: "SSH 端口（非 22 时指定）" },
+                    user: { type: "string", description: "登录用户名" },
+                    key: { type: "string", description: "私钥文件路径（-i）" },
+                    jump: { type: "string", description: "跳板（-J：途径机不占层）" },
+                    name: { type: "string", description: "层名（缺省=host；注册表内唯一，显式寻址用）" },
+                },
+                required: ["host"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "push_into",
+            description:
+                "从默认层（或 from 指定层）进入内层 shell（docker exec -i <ctr> sh / kubectl exec 等）——" +
+                "enter 管线全量继承追加（父层 docker→再 su 不丢）。新层成为默认层。需 ssh 层为源。",
+            parameters: {
+                type: "object",
+                properties: {
+                    enter_cmd: { type: "string", description: "进入命令，如 \"docker exec -i web sh\"" },
+                    label: { type: "string", description: "层显示标签" },
+                    from: { type: "string", description: "源层名（缺省=默认层）" },
+                    name: { type: "string", description: "层名（缺省=label）" },
+                },
+                required: ["enter_cmd"],
+            },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "list_layers",
+            description:
+                "列出全部命名层（链路/状态/有效用户/默认层标记）。死层/退化层有警示标注（removeLayer 后按原参数重建）。",
+            parameters: { type: "object", properties: {}, required: [] },
+        },
+    },
+    {
+        type: "function",
+        function: {
+            name: "remove_layer",
+            description:
+                "移出命名层（缺省连接保留在指纹缓存——再建同层零成本；destroy=true 才真销毁连接）。",
+            parameters: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "层名" },
+                    destroy: { type: "boolean", description: "真销毁连接（缺省 false=保留可复用）" },
+                },
+                required: ["name"],
+            },
+        },
+    },
 ];
 
 /** 生成 Agent 工具集（定义层 + 执行层；宿主桥接到任意 LLM 框架） */
@@ -167,21 +251,27 @@ export function createAgentToolkit(stack: RuntimeStack, opts: AgentToolkitOption
         ? Promise.resolve(opts.driver)
         : stack.connect(opts.descriptor ?? { driver: "local" });
     const readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+    /** 层寻址（第十季注册表）：显式层名 > 注册表默认层（最近 push）> 初始层——
+     *  未用层族时与旧行为逐字节一致（零破坏），push 后六工具自动落新默认层 */
+    const resolveDrv = async (layerName?: string): Promise<RuntimeDriver> => {
+        if (layerName) return stack.layer(layerName).driver;
+        return stack.active ?? await layer;
+    };
 
     return {
         tools: TOOL_DEFS,
         layer,
         handlers: {
-            async run_command({ command, timeout_ms }) {
-                const drv = await layer;
+            async run_command({ command, timeout_ms, layer: layerName }) {
+                const drv = await resolveDrv(layerName);
                 const r = await drv.exec(command, { timeoutMs: timeout_ms });
                 return {
                     stdout: r.stdout, stderr: r.stderr, exit_code: r.exitCode,
                     effective_user: r.effectiveUser,
                 };
             },
-            async spawn_and_observe({ command, ready_marker, error_pattern, name }) {
-                const drv = await layer;
+            async spawn_and_observe({ command, ready_marker, error_pattern, name, layer: layerName }) {
+                const drv = await resolveDrv(layerName);
                 const h = await drv.execSession(command, name ? { name } : undefined);
                 if (error_pattern) {
                     drv.watchSession(h.sessionId, { pattern: error_pattern, once: false, thenStop: true });
@@ -202,21 +292,21 @@ export function createAgentToolkit(stack: RuntimeStack, opts: AgentToolkitOption
                 }
                 return { session_id: h.sessionId, log_base: h.logBase, note };
             },
-            async read_file({ path }) {
-                const drv = await layer;
+            async read_file({ path, layer: layerName }) {
+                const drv = await resolveDrv(layerName);
                 if (!drv.fs.stat) throw new Error("该层不支持 read_file 的元数据（fs.stat 缺席）");
                 const st = await drv.fs.stat(path);
                 if (!st) throw new Error(`文件不存在: ${path}`);
                 const content = await drv.fs.readFile(path);
                 return { path, content, size: st.size, mtime_ms: st.mtimeMs };
             },
-            async edit_file({ path, old, new: newStr, all }) {
-                const drv = await layer;
+            async edit_file({ path, old, new: newStr, all, layer: layerName }) {
+                const drv = await resolveDrv(layerName);
                 const r = await editFile(drv, path, old, newStr, { all });
                 return { path: r.path, occurrences: r.occurrences, bytes_before: r.bytesBefore, bytes_after: r.bytesAfter };
             },
-            async observe_stream({ command, duration_ms, stream, name }) {
-                const drv = await layer;
+            async observe_stream({ command, duration_ms, stream, name, layer: layerName }) {
+                const drv = await resolveDrv(layerName);
                 const h = await drv.execSession(command, name ? { name } : undefined);
                 const dur = duration_ms ?? 8000;
                 await new Promise((r) => setTimeout(r, dur));
@@ -238,6 +328,41 @@ export function createAgentToolkit(stack: RuntimeStack, opts: AgentToolkitOption
                 await drv.stopSession(h.sessionId).catch(() => undefined);
                 return { session_id: h.sessionId, lines: filtered };
             },
+            // ── 层族（第十季命名层注册表）──
+            async push_ssh({ host, port, user, key, jump, name }) {
+                const connParams: Record<string, unknown> = {};
+                if (port != null) connParams.port = Number(port);
+                if (user) connParams.user = String(user);
+                if (key) connParams.keyFile = String(key);
+                if (jump) connParams.jump = String(jump);
+                const r = await stack.addLayer(name ?? String(host), {
+                    driver: "ssh", target: String(host),
+                    config: Object.keys(connParams).length ? { connParams } : undefined,
+                });
+                return {
+                    layer: r.handle.name, reused: r.reused, reused_from: r.reusedFrom,
+                    note: r.reused ? "落点已由既有层持有——幂等复用（未重复建连）" : "新层已建并成为默认层",
+                };
+            },
+            async push_into({ enter_cmd, label, from, name }) {
+                const srcName = from ?? stack.activeLayer?.name;
+                if (!srcName) throw new Error("无源层——先 push_ssh 建层，或显式传 from");
+                const h = await stack.layerInto(srcName, name ?? label ?? enter_cmd.slice(0, 30), enter_cmd, { label });
+                return { layer: h.name, target: h.descriptor.target };
+            },
+            async list_layers(_args) {
+                void _args;
+                return {
+                    text: stack.layerText(),
+                    layers: [...stack.layers.values()].map((h) => ({
+                        name: h.name, driver: h.descriptor.driver, target: h.descriptor.target,
+                    })),
+                };
+            },
+            async remove_layer({ name, destroy }) {
+                await stack.removeLayer(name, { destroy });
+                return { removed: name };
+            },
             async stop_and_verify({ session_id }) {
                 const drv = await layer;
                 const r = (await drv.stopSession(session_id)) as { status?: string; exitCode?: number | null };

package/src/file-edit.ts

@@ -6,10 +6,16 @@
  *
  * 第七季盲测反馈（B2 逐秒拆解）：旧实现一次 editFile = 5 次串行 SSH 往返
  * （stat/read/stat/write/stat），Windows 无 ControlMaster 下放大到 15s+。
- * 本版：合成 **2 次往返**（读+戳 1 次；**远端 CAS 原子写回** 1 次——GPT 并发
- * 安全意见采纳：「最后一次校验与写入放进同一个远端受控操作」——戳比对与写回
- * 在远端一条命令内原子完成，杜绝 A/B 丢失更新）+ 方言适配（stat/base64 三族，
- * 每 driver 缓存一次探测）。大文件（base64>30KB）自动回落旧 5 次路径（fs 层）。
+ * 第七季版合成「读+戳 1 次 + 远端 CAS 原子写回 1 次」——但方言探测（base64
+ * -w 0/-d/-D）是独立往返，SDK 常驻内存下有 dialectCache 掩护，**CLI 每次冷启动
+ * 实为 3 次物理往返**（第十季 B5 轨迹实锤：3×SSH 握手 ≈11.4s 突破宿主 10s 后台
+ * 阈值，多耗 3 轮轮询）。
+ *
+ * 本版（第十季）：**真 2 次往返**——方言探测合成进读往返（① stat/sha 戳 +
+ * base64 -d 探测 + 文件读取一次带回；② CAS 写回用已确定 argv）。编码侧无需
+ * 探测：折行输出由解析侧 \s+ 归一消化（base64 < file 全方言通吃）；解码侧
+ * 不用 `base64 -d || base64 -D` 赌 fallback（GPT 否决：双解码器共用 stdin，
+ * 首个消费后第二个拿不到完整载荷）。大文件（base64>30KB）自动回落 fs 层路径。
  *
  * **仅适用 UTF-8 文本**（readFile 返回 UTF-8 字符串；二进制文件的编辑走
  * readBase64 + 消费方自行改写 + writeFile）。
@@ -42,51 +48,24 @@ const q = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
 /** 单引号安全检查（base64/stamp 等嵌入 shell 引号前的红线） */
 const shellSafe = (s: string) => !s.includes("'") && !s.includes("\n");
 
-interface ShellDialect {
-    statCmd: string; // 戳命令（输出 "mtime size"）
-    enc: string;    // base64 编码 argv（无换行）
-    dec: string;    // base64 解码 argv
-    /** 内容指纹命令模板（{f}=文件——三族 fallback 链：sha256sum → sha256 -q → openssl；
-     *  CAS 戳的内容分量：stat %Y 秒级粒度有同秒同 size 盲区——内容指纹封死） */
-    shaCmd: string;
-}
-
 /**
  * stat 戳命令模板（{f}=文件——行为 fallback 链，不探版本：GNU -c 优先、
  * 失败自动 BSD -f——CI 实证版本探测在 Ubuntu 误判走 BSD 分支）。
  */
 const statCmdOf = (f: string) => `stat -c '%Y %s' ${f} 2>/dev/null || stat -f '%m %z' ${f} 2>/dev/null`;
 
-/** 每 driver 的方言缓存（key=driver 描述符投影——仅 base64 族） */
-const dialectCache = new Map<string, ShellDialect>();
-
-async function dialectOf(drv: RuntimeDriver): Promise<ShellDialect> {
-    const key = JSON.stringify(drv.descriptor);
-    const hit = dialectCache.get(key);
-    if (hit) return hit;
-    // 一次往返探测 base64 族（-w 0 GNU / 解码 -d vs -D）
-    const probe = await drv.exec(
-        "echo FX2=$(printf filaxis | base64 -w 0 2>/dev/null | head -c 8);" +
-        "echo FX3=$(printf ZmlsYXhpcw== | base64 -d 2>/dev/null | head -c 7);" +
-        "echo FX4=$(printf ZmlsYXhpcw== | base64 -D 2>/dev/null | head -c 7)",
-        { timeoutMs: 15_000 },
-    );
-    const out = probe.stdout || "";
-    const b64Gnu = /FX2=ZmlsYXhp/.test(out);
-    const decD = /FX4=filaxis/.test(out);
-    const d: ShellDialect = {
-        statCmd: "", // 行为 fallback（statCmdOf）——不走探测
-        enc: b64Gnu ? "base64 -w 0" : "base64",
-        dec: decD ? "base64 -D" : "base64 -d",
-        shaCmd: `{ sha256sum ${"{f}"} 2>/dev/null || sha256 -q ${"{f}"} 2>/dev/null || openssl dgst -sha256 ${"{f}"} 2>/dev/null | tail -1; } | head -c 12`,
-    };
-    dialectCache.set(key, d);
-    return d;
-}
+/**
+ * 内容指纹命令（三族 fallback 链：sha256sum → sha256 -q → openssl；
+ * CAS 戳的内容分量：stat %Y 秒级粒度有同秒同 size 盲区——内容指纹封死）。
+ */
+const shaCmdOf = (f: string) =>
+    `{ sha256sum ${f} 2>/dev/null || sha256 -q ${f} 2>/dev/null || openssl dgst -sha256 ${f} 2>/dev/null | tail -1; } | head -c 12`;
 
 /**
- * 受控编辑（合成 2 次往返 + 远端 CAS 原子写回）：
- * ① 读+戳（1 次往返）：`stat 戳; __FXS__; base64 读` —— 拿 (mtime,size)+全文
+ * 受控编辑（真 2 次往返 + 远端 CAS 原子写回）：
+ * ① 读+戳+方言探测（1 次往返）：`stat 戳; sha 戳; __FXS__; base64 -d 探测;
+ *    __FXD__; base64 < file` —— (mtime,size)+全文+解码 argv 一次带回
+ *    （__FXD__ 含下划线不在 base64 字母表——与 __FXS__ 同款防撞）
  * ② 精确替换（本地）：0 命中/多处命中（未开 all）拒绝
  * ③ CAS 原子写回（1 次往返）：远端一条命令内完成「戳比对 + tmp 写 + mv 原子替换 + 新戳回执」
  *    —— 戳不符（他人先写）→ EditConflictError；写后回执新戳
@@ -101,12 +80,16 @@ export async function editFile(
     newStr: string,
     opts: EditFileOptions = {},
 ): Promise<EditFileResult> {
-    const dialect = await dialectOf(drv);
-    // 读+戳 合成一次往返（读时戳与读到的内容同窗——读后他人写 → CAS 必不符）
+    // 读+戳+探测 合成一次往返（读时戳与读到的内容同窗——读后他人写 → CAS 必不符）。
+    // 编码用 base64 < file（stdin 全方言通吃，折行由解析侧 \s+ 归一消化——无需 -w 0 探测）；
+    // 解码探测 printf | base64 -d：GNU/busybox 出 filaxis → -d；BSD 失败 → -D（行为判定
+    // 与旧探测等价）。CAS 写回用本次确定的 argv——不赌 || fallback 的 stdin 双消费。
     const qp = q(path);
-    const readCmd = `${statCmdOf(qp)}; ${dialect.shaCmd.replace(/\{f\}/g, qp)}; echo __FXS__; ${dialect.enc} ${qp} 2>/dev/null`;
+    const readCmd =
+        `${statCmdOf(qp)}; ${shaCmdOf(qp)}; echo __FXS__; ` +
+        `printf ZmlsYXhpcw== | base64 -d 2>/dev/null; echo __FXD__; base64 < ${qp} 2>/dev/null`;
     const r = await drv.exec(readCmd, { timeoutMs: 30_000 });
-    const [stampPart, b64Part] = (r.stdout || "").split("__FXS__");
+    const [stampPart, restPart] = (r.stdout || "").split("__FXS__");
     const originStampRaw = (stampPart ?? "").trim();
     const originLines = originStampRaw.split(/\n/);
     const statStamp = (originLines[0] ?? "").trim();
@@ -120,7 +103,9 @@ export async function editFile(
         size: parseInt(originParts[1] ?? "0", 10),
     };
     if (!origin.size || !shaStamp) throw new Error(`文件不存在或指纹异常: ${path}（${originStampRaw}）`);
-    const content0 = Buffer.from((b64Part ?? "").replace(/\s+/g, ""), "base64").toString("utf-8");
+    const [decPart, b64Part = ""] = (restPart ?? "").split("__FXD__");
+    const dec = (decPart ?? "").trim() === "filaxis" ? "base64 -d" : "base64 -D";
+    const content0 = Buffer.from(b64Part.replace(/\s+/g, ""), "base64").toString("utf-8");
 
     const occurrences = content0.split(oldStr).length - 1;
     if (occurrences === 0) {
@@ -140,8 +125,8 @@ export async function editFile(
 
     const cmd =
         `if [ "$(${statCmdOf(qp)})" = "${statStamp}" ] && ` +
-        `[ "$(${dialect.shaCmd.replace(/\{f\}/g, qp)})" = "${shaStamp}" ]; then ` +
-        `printf %s ${q(newB64)} | ${dialect.dec} > ${qp}.fx-tmp && mv ${qp}.fx-tmp ${qp} && ` +
+        `[ "$(${shaCmdOf(qp)})" = "${shaStamp}" ]; then ` +
+        `printf %s ${q(newB64)} | ${dec} > ${qp}.fx-tmp && mv ${qp}.fx-tmp ${qp} && ` +
         `echo "FX_OK $(stat -c '%Y %s' ${qp} 2>/dev/null || stat -f '%m %z' ${qp} 2>/dev/null)"; ` +
         `else echo FX_CAS_FAIL; fi`;