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

package/bin/filaxis.ts

@@ -8,6 +8,11 @@
  * edit 免 Shell 通道（第八季盲测实锤：Windows CommandLineToArgvW 剥引号、多行
  * argv 要数缩进空格——Flash 卡 32 轮）：--stdin-json / --request-file 走 JSON
  * 载荷 {old,new,all}，多行/引号/缩进 100% 保真，绕开宿主 Shell 转义。
+ *
+ * 路径描述对齐内核三件套（第九季盲测：CLI 只有 --host 族，跳板+容器场景 Agent
+ * 被迫读 19 轮源码写 6 个 TS 脚本）：connParams（--jump/-J/--forward/--host-key/
+ * --known-hosts）+ sshHops 逐跳链（--hop 可重复）+ enterPipeline（--enter 可重复
+ * + --docker 糖）。每跳独立密钥等极端拓扑走 SDK descriptor 全量描述。
  */
 import { RuntimeStack, LocalRuntimeDriver, SshPtyDriver, editFile, discoverLayer } from "../src/index.js";
 import type { RuntimeDriver } from "../src/driver.js";
@@ -21,11 +26,14 @@ type MaybeAsync<T> = T | Promise<T>;
 
 function parseOpts(argv: string[]): {
     host?: string; user?: string; port?: number; key?: string;
+    jump?: string; hop: string[]; enter: string[];
+    docker?: string; dockerShell?: string; dockerRuntime?: string;
+    forward: string[]; hostKey?: string; knownHosts?: string;
     timeout?: number; duration?: number; stream?: string; all?: boolean;
     stdinJson?: boolean; requestFile?: string;
     positional: string[];
 } {
-    const o: ReturnType<typeof parseOpts> = { positional: [] };
+    const o: ReturnType<typeof parseOpts> = { positional: [], hop: [], enter: [], forward: [] };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i]!;
         if (a === "--") continue; // 命令分隔符（可省）
@@ -34,6 +42,15 @@ function parseOpts(argv: string[]): {
             case "--user": o.user = argv[++i]; break;
             case "--port": o.port = parseInt(argv[++i]!, 10); break;
             case "--key": o.key = argv[++i]; break;
+            case "-J": case "--jump": o.jump = argv[++i]; break;
+            case "--hop": o.hop.push(argv[++i]!); break;
+            case "--enter": o.enter.push(argv[++i]!); break;
+            case "--docker": o.docker = argv[++i]; break;
+            case "--docker-shell": o.dockerShell = argv[++i]; break;
+            case "--docker-runtime": o.dockerRuntime = argv[++i]; break;
+            case "--forward": o.forward.push(argv[++i]!); break;
+            case "--host-key": o.hostKey = argv[++i]; break;
+            case "--known-hosts": o.knownHosts = argv[++i]; break;
             case "--timeout": o.timeout = parseInt(argv[++i]!, 10); break;
             case "--duration": o.duration = parseInt(argv[++i]!, 10); break;
             case "--stream": o.stream = argv[++i]; break;
@@ -46,12 +63,71 @@ function parseOpts(argv: string[]): {
     return o;
 }
 
+/** 跳描述解析：user@host[:port]（任一存在→结构化跳；纯 host→纯字符串跳，旧形态逐字节不变） */
+function parseHopSpec(spec: string): { host: string; conn?: { user?: string; port?: number } } {
+    let rest = spec;
+    let user: string | undefined;
+    const at = rest.lastIndexOf("@");
+    if (at > 0) { user = rest.slice(0, at); rest = rest.slice(at + 1); }
+    let port: number | undefined;
+    const colon = rest.lastIndexOf(":");
+    if (colon > 0) {
+        const p = parseInt(rest.slice(colon + 1), 10);
+        if (Number.isFinite(p) && p > 0 && p < 65536) { port = p; rest = rest.slice(0, colon); }
+    }
+    return user != null || port != null ? { host: rest, conn: { user, port } } : { host: rest };
+}
+
+/** 端口透传解析：L:8080:localhost:80 / R:... / D:1080（bind 走 SDK descriptor） */
+function parseForwardSpec(spec: string): { kind: "L" | "R" | "D"; port: number; target?: string } {
+    const parts = spec.split(":");
+    const kind = (parts[0] ?? "").toUpperCase();
+    if (!["L", "R", "D"].includes(kind)) throw new Error(`--forward 格式非法: '${spec}'（应为 L:port:host:port / R:... / D:port）`);
+    const port = parseInt(parts[1] ?? "", 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) throw new Error(`--forward 端口非法: '${spec}'`);
+    const target = kind === "D" ? undefined : parts.slice(2).join(":");
+    if (kind !== "D" && !target) throw new Error(`--forward kind=${kind} 需 target（host:port）: '${spec}'`);
+    return { kind: kind as "L" | "R" | "D", port, target };
+}
+
 async function driverFor(opts: ReturnType<typeof parseOpts>): Promise<RuntimeDriver> {
     if (opts.host) {
-        return new SshPtyDriver({
-            driver: "ssh", target: opts.host,
-            config: { connParams: { user: opts.user, port: opts.port, keyFile: opts.key } },
-        });
+        // ① connParams（root 连接参数——对齐内核 SshConnParams 全字段）
+        const connParams: Record<string, unknown> = {};
+        if (opts.user) connParams.user = opts.user;
+        if (opts.port != null) connParams.port = opts.port;
+        if (opts.key) connParams.keyFile = opts.key;
+        if (opts.jump) connParams.jump = opts.jump; // -J：途径机不占层，ssh 自身代理
+        if (opts.forward.length) connParams.forwards = opts.forward.map(parseForwardSpec);
+        if (opts.hostKey) {
+            if (opts.hostKey !== "tofu" && opts.hostKey !== "strict") {
+                throw new Error(`--host-key 取值非法: '${opts.hostKey}'（限 tofu | strict）`);
+            }
+            connParams.hostKeyPolicy = opts.hostKey;
+        }
+        if (opts.knownHosts) connParams.knownHostsFile = opts.knownHosts;
+        const config: Record<string, unknown> = {};
+        if (Object.keys(connParams).length) config.connParams = connParams;
+        // ② sshHops 逐跳链（每跳 user@host[:port]，顺序=链序；密钥共享 --key——
+        //    每跳独立密钥等极端拓扑走 SDK descriptor）
+        if (opts.hop.length) config.sshHops = opts.hop.map(parseHopSpec);
+        // ③ enterPipeline 有序进入管线（--docker 糖在前 + --enter 按序追加；label
+        //    截取 cmd 前 30 字符=原版 push_enter 默认同款）
+        const enterSteps: Array<{ cmd: string; label: string }> = [];
+        if (opts.docker) {
+            const runtime = opts.dockerRuntime ?? "docker";
+            enterSteps.push({
+                cmd: `${runtime} exec -i ${opts.docker} ${opts.dockerShell ?? "sh"}`,
+                label: `${runtime}:${opts.docker}`,
+            });
+        }
+        for (const e of opts.enter) enterSteps.push({ cmd: e, label: e.slice(0, 30) });
+        if (enterSteps.length) config.enterPipeline = enterSteps;
+        return new SshPtyDriver({ driver: "ssh", target: opts.host, config });
+    }
+    // local 层无路径概念——路径参数在场而 --host 缺席 = 防呆报错（静默忽略=错机器风险）
+    if (opts.jump || opts.hop.length || opts.enter.length || opts.docker || opts.forward.length || opts.hostKey || opts.knownHosts) {
+        throw new Error("路径描述参数（--jump/--hop/--enter/--docker/--forward/--host-key/--known-hosts）需要 --host（local 层无路径概念）");
     }
     return new LocalRuntimeDriver();
 }
@@ -154,7 +230,16 @@ async function main() {
                   <path> --stdin-json | --request-file <f>  #   免 Shell 通道（JSON {old,new,all}——多行/引号保真）
   filaxis observe [--host ...] [--stream stderr|stdout|both] [--duration MS] -- <command>
   filaxis probe   [--host ...]                                     # 两段式环境探测
-缺省 --host 为 local。`);
+
+路径描述（需 --host；对齐内核三件套 connParams/sshHops/enterPipeline）:
+  -J, --jump <j>          跳板（-J：途径机不占层，ssh 自身代理）
+  --hop <user@host[:port]> 逐跳登录链（可重复=链序；每跳独立端口/用户，密钥共享 --key）
+  --enter <cmd>           进入内层 shell（可重复=管线序，如 "docker exec -i web bash"）
+  --docker <name>         糖 = --enter "docker exec -i <name> sh"（--docker-shell bash / --docker-runtime podman 可换）
+  --forward L:8080:host:80  端口透传（可重复；R:/D: 同构；bind 走 SDK descriptor）
+  --host-key tofu|strict  主机密钥策略（缺省 tofu=accept-new）
+  --known-hosts <file>    自定义 known_hosts
+每跳独立密钥等极端拓扑请用 SDK descriptor 全量描述。缺省 --host 为 local。`);
                 process.exit(cmd ? 1 : 0);
         }
     } finally {

package/dist/agent-toolkit.d.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 type { RuntimeDriver } from "./driver.js";
@@ -53,6 +56,7 @@ export interface AgentToolHandlers {
         duration_ms?: number;
         stream?: "stdout" | "stderr" | "both";
         name?: string;
+        layer?: string;
     }): Promise<{
         session_id: string;
         lines: Array<{
@@ -65,6 +69,7 @@ export interface AgentToolHandlers {
         ready_marker?: string;
         error_pattern?: string;
         name?: string;
+        layer?: string;
     }): Promise<{
         session_id: string;
         log_base: string;
@@ -77,6 +82,42 @@ export interface AgentToolHandlers {
         exit_code?: number | null;
         note?: string;
     }>;
+    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 {
     tools: AgentToolDef[];

package/dist/file-edit.d.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）。
@@ -31,8 +37,10 @@ export declare class EditConflictError extends Error {
     constructor(message: string);
 }
 /**
- * 受控编辑（合成 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；写后回执新戳