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

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/docs//346/265/213/350/257/2257.md

@@ -0,0 +1,179 @@
+Ran download and extract @syrkos/filaxis@0.1.0-alpha.11 · Exited with code 1
+Ran download and extract @syrkos/filaxis@0.1.0-alpha.11 via curl
+Analyzed filaxis.ts:L1-168
+Analyzed agent-toolkit.ts:L1-254
+Analyzed index.ts:L1-38
+Analyzed runtime-stack.ts:L1-128
+Analyzed ssh-helpers.ts:L1-225
+Analyzed ssh-pty-driver.ts:L1-655
+Ran check local SSH config
+Ran test SSH jump via vm-ai-server to vm-homelab and check docker
+Ran list existing docker images on vm-homelab
+Ran check available utilities in alpine:latest container on vm-homelab · Exited with code 1
+Ran check utilities in alpine:latest container
+Created test_alpha11_docker.ts
+Canceled test SshPtyDriver with jump to vm-homelab
+Killed task Test SshPtyDriver with jump to vm-homelab
+Edited test_alpha11_docker.ts
+Ran test SshPtyDriver with jump vm-ai-server to vm-homelab
+Killing task Test SshPtyDriver with jump vm-ai-server to vm-homelab
+Edited test_alpha11_docker.ts
+Ran test SshPtyDriver jump + docker enterCmd on vm-homelab
+
+已下载并解压 `@syrkos/filaxis@0.1.0-alpha.11`，正在通过 `vm-ai-server` 跳板机在 `vm-homelab` 的 Docker 容器层进行预检测试，稍候任务返回后继续部署新考题。
+
+Analyzed remote-session-manager.ts:L1-286
+Ran list files in filaxis 0.1.0-alpha.11 package
+Edited test_alpha11_docker.ts
+Ran test execSession and tailLines inside Alpine container via jump host
+
+正在验证 `SshPtyDriver` 在 `vm-ai-server` 跳板机 + `vm-homelab` Docker 容器内的异步会话观察（`execSession` + `tailLines` + `stopSession`）表现，稍候完成后即刻构建第四轮对比考题。
+
+Created setup_exam3_docker.ts
+Ran setup exam3-edge-a and exam3-edge-b containers on vm-homelab via vm-ai-server
+
+正在通过 `vm-ai-server` 跳板机在 `vm-homelab` 上初始化第四轮盲测的双容器沙箱（`exam3-edge-a` 与 `exam3-edge-b`，基于无 Python/jq 的纯净 `alpine:latest` 镜像），待环境就绪后立即并发启动两组 Gemini 3.8 Flash 子代理进行对决。
+
+Used tool: invoke_subagent
+Used tool: invoke_subagent
+
+已部署第四轮（`0.1.0-alpha.11`）三层穿透容器盲测考题，并同时启动两组 **Gemini 3.8 Flash** 子代理并发执行：
+
+1. **拓扑与环境**：`Windows 本地` $\rightarrow$ 跳板机 `vm-ai-server (10.0.20.2)` $\rightarrow$ 宿主机 `vm-homelab (10.0.20.1:3322)` $\rightarrow$ `alpine:latest` 纯净容器（**容器内无 `python3`、无 `jq`、无 `node`、无 `bash`**，仅 BusyBox `sh`）。
+2. **三项复合故障**：
+   - **故障 1（残留进程锁 + `stderr` 诊断流）**：清理 `/usr/local/bin/edge-lock-holder` 进程与 `/var/run/edge-dispatcher.lock`，并捕获 `/usr/local/bin/edge-dispatcher --diagnose` 输出在 `stderr` 上的故障规范；
+   - **故障 2（无 Python/jq 容器内的多块同构 JSON 修改）**：修改 `/etc/edge-dispatcher/webhooks.json` 中 `id="billing-sync"` 路由块的 3 个字段，严禁误伤 `global`、`order-created`、`inventory-audit` 三个同构块；
+   - **故障 3（含 `$2a`、`!`、`#`、`&` 特殊字符的密钥配置）**：将 `/etc/edge-dispatcher/credentials.conf` 中的 `BILLING_HMAC_SECRET` 更新为 `"whsec_9f$2a!Kp#88_Live&Key"`（含触发 Shell 变量展开的 `$2a` 和触发 `sed` 替换展开的 `&`）。
+3. **分组对决**：
+   - **A4 组（裸 SSH + Docker 组，`flash`）**：[`4ceee8c3-a385-49e4-8cf1-505e40db46cf`](conversation://4ceee8c3-a385-49e4-8cf1-505e40db46cf)（操作容器 `exam3-edge-a`）
+   - **B4 组（Filaxis `0.1.0-alpha.11` 组，`flash`）**：[`4e018b84-90c3-47d3-bcf8-28c8bea7f1d4`](conversation://4e018b84-90c3-47d3-bcf8-28c8bea7f1d4)（操作容器 `exam3-edge-b`）
+
+正在等待两个子代理完成任务回报，随后为您解析完整的 `transcript_full.jsonl` Token 账单与轨迹对比。
+
+Found 8 subagents
+
+A4 组（裸 SSH + Docker 组，`4ceee8c3-a385-49e4-8cf1-505e40db46cf`）已完成汇报；B4 组（Filaxis `0.1.0-alpha.11` 组，`4e018b84-90c3-47d3-bcf8-28c8bea7f1d4`）正在执行最后的 `--self-test` 校验，稍候其返回后立即为您输出第四轮完整 Token 与执行轨迹对比分析。
+
+Created analyze_r4_docker.ts
+Ran analyze Round 4 subagent transcripts and token usage
+Analyzed analyze_r3_flash.ts:L1-65
+Edited analyze_r4_docker.ts
+Ran run full Round 4 transcript and token analysis
+Analyzed output.txt:L35-227
+Analyzed test_connect.ts:L1-27
+Analyzed remediate.ts:L1-70
+Ran clean up exam3-edge-a and exam3-edge-b containers on vm-homelab
+
+第四轮（`0.1.0-alpha.11`）**三层穿透（Windows $\rightarrow$ `vm-ai-server` 跳板机 $\rightarrow$ `vm-homelab` 宿主机 $\rightarrow$ `alpine:latest` 纯净容器）** 的 Gemini 3.8 Flash 同模型盲测已全部跑完，宿主机上的两个测试容器 `exam3-edge-a` / `exam3-edge-b` 也已清理完毕。
+
+这轮实验出现了一个**非常关键的转折**：
+- 上一轮（`alpha.10`）卡死 Filaxis 组 32 轮（303 秒）的**多行 JSON 与特殊字符编辑，在这一轮实现了 `0` 报错、`1` 次命中过关**！
+- 与此同时，由于容器换成了**无 `python3`、无 `jq`、无 `node` 的 `alpine:latest`**，裸 SSH 组再也无法用 Python 逃课，被迫在本地手搓 Base64 整文件覆盖；而 Filaxis 组则暴露出了 **CLI 入口（`bin/filaxis.ts`）尚未透传 `--jump` 与 `--enter` 参数** 的新摩擦点。
+
+---
+
+### 一、 第四轮核心指标总表（Gemini 3.8 Flash 盲测）
+
+> 原始轨迹日志：
+> - **A4 组（裸 SSH + Docker）**：[`4ceee8c3-a385-49e4-8cf1-505e40db46cf`](conversation://4ceee8c3-a385-49e4-8cf1-505e40db46cf)
+> - **B4 组（Filaxis `0.1.0-alpha.11` + Docker）**：[`4e018b84-90c3-47d3-bcf8-28c8bea7f1d4`](conversation://4e018b84-90c3-47d3-bcf8-28c8bea7f1d4)
+> - 完整逐轮对账输出：[output.txt](file:///C:/Users/dream/.gemini/antigravity/brain/f7c26020-3bdd-4477-b804-f050d731bc85/.system_generated/steps/9174/output.txt)
+
+| 评测维度 | 对照 A4 组（Flash + 裸 SSH + Docker） | 实验 B4 组（Flash + Filaxis `alpha.11` + Docker） | 跨版本演进（对比第三轮 `alpha.10` B3 组） |
+| :--- | :--- | :--- | :--- |
+| **推理轮次 (Planner Turns)** | **23 轮** | **43 轮** | 从 53 轮降至 **43 轮**（**-10 轮**） |
+| **工具调用次数 (Tool Calls)** | **22 次** | **42 次** | 从 52 次降至 **42 次**（**-10 次**） |
+| **总耗时 (Wall-Clock Time)** | **234.0 秒** | **347.0 秒** | 从 540.0 秒降至 **347.0 秒**（**快了 193 秒 / -35.7%**） |
+| **编辑重试 / 引号翻车轮次** | 0 次（退化为手搓 Base64 全量覆盖） | **0 次（`editFile` 两次调用均 100% 一次命中）** | 从 **32 轮卡死（303 秒）** 降至 **0 轮（0 秒）** |
+| **杀进程 / Shell 踩坑次数** | **2 次**（`pkill -f` 自杀 + PowerShell 吞 `$?`） | **0 次**（`stdin` 管道注入，零 Shell 展开污染） | 保持 **0 事故** |
+| **计费新增输入 (New Input)** | `85,885` | `160,682` | 稳定（`162.5K` $\rightarrow$ `160.7K`） |
+| **缓存读取输入 (Cache Read)** | `506,795` | `1,825,715` | 因前 19 轮读源码垫高了前期上下文基数 |
+| **总输入上下文 (Total Input)** | **`592,680` (592.7K)** | **`1,986,397` (1,986.4K)** | 源码阅读（19 轮）+ 写脚本执行（22 轮）占大头 |
+| **总输出 Token (Output)** | **`13,779`** | **`22,873`** | 含编写 6 个 `.ts` 脚本的代码输出 |
+| **最终 `--self-test` 结果** | `ALL_CHECKS_PASSED (exit=0)` | `ALL_CHECKS_PASSED (exit=0)` | 均一次通过验收 |
+
+---
+
+### 二、 两组精彩现场复盘：当 Alpine 容器里没有 Python 时发生了什么？
+
+#### 1. 裸 SSH 组（A4）：没了 Python，只能退化为「无锁整文件 Base64 覆盖」+ 两处多层 Shell 翻车
+在第三轮中，裸 SSH 组靠远端宿主机的 `python3` 5 秒改完了 JSON。但这轮进入纯净 `alpine:latest` 容器（无 `python3`、无 `jq`、无 `node`）后，裸 SSH 组的轨迹暴露了三层 Shell 嵌套（`PowerShell` $\rightarrow$ `ssh -J` $\rightarrow$ `docker exec sh -c`）的真实痛点：
+- **踩坑 ①（Turn 9，`pkill -f` 自杀导致命令异常退出）**：
+  A4 执行 `ssh -J vm-ai-server vm-homelab "docker exec exam3-edge-a sh -c 'pkill -9 -f edge-lock-holder; rm -f /var/run/edge-dispatcher.lock; ps aux'"`。
+  因为外层 `sh -c '...'` 的命令行参数本身就包含字符串 `edge-lock-holder`，BusyBox 的 `pkill -9 -f edge-lock-holder` **当场把正在执行命令的 `sh -c` 自己给 `SIGKILL` 了**（返回 `exit code 1`，后面的 `rm -f` 和 `ps aux` 根本没执行）！A4 被迫花了 4 轮（Turn 9~12）改用手动查 PID `kill -9 106` 才杀掉。
+- **踩坑 ②（Turn 12，宿主 PowerShell 吞掉远端 `\$?`）**：
+  A4 执行 `ssh ... "docker exec exam3-edge-a sh -c 'ps aux ...; echo EXIT: \$?'"`，结果宿主机的 PowerShell 抢先将双引号里的 `$?` 展开成了 PowerShell 布尔值 `True`，打印出 `EXIT: True`！
+- **手搓无锁 Base64（Turn 14~19，耗时 61 秒）**：
+  面对含 `$2a!Kp#88_Live&Key` 的配置文件和同构 JSON，A4 发现容器里没有 Python，但有 `/bin/base64`（Turn 14），于是**在本地 PowerShell 里把整个文件全文硬编码敲了一遍**（Turn 15、16），算出 Base64 字符串后通过 `echo '<b64>' | docker exec -i exam3-edge-a sh -c 'base64 -d > ...'` 全量覆盖写回（Turn 17、19）。
+  - *隐患*：这种做法等于 Agent 在本地脑内重写整份文件再无锁覆盖（无 TOCTOU 校验，且一旦文件有几百行，Output Token 会成倍爆炸）。
+
+#### 2. Filaxis `0.1.0-alpha.11` 组（B4）：多层穿透与文件受控编辑“丝滑一次过”，但被 CLI 缺参数逼回写 TS 脚本
+B4 组在 [`remediate.ts`](file:///C:/Users/dream/.gemini/antigravity/brain/4e018b84-90c3-47d3-bcf8-28c8bea7f1d4/scratch/remediate.ts#L4-L55) 中展现了 `SshPtyDriver` + `editFile` 在三层容器穿透下的威力：
+```ts
+const drv = new SshPtyDriver({
+    driver: "ssh",
+    target: "vm-homelab",
+    config: {
+        connParams: { jump: "vm-ai-server" },
+        enterCmd: "docker exec -i exam3-edge-b sh",
+    },
+});
+```
+- **零嵌套转义**：通过 `renderExecChannel` 的 `docker exec -i exam3-edge-b sh -s` 标准输入管道注入，无论命令里有什么引号或 `$` 符号，宿主 PowerShell 与中间跳板机完全不解析。
+- **`editFile` 100% 一次命中**：
+  - 修改 `credentials.conf` 中的 `BILLING_HMAC_SECRET="whsec_9f$2a!Kp#88_Live&Key"`（含 `$2a`、`!`、`#`、`&`）：**1 次成功**（160B $\rightarrow$ 166B）。
+  - 修改 `webhooks.json` 中的 `billing-sync` 多行对象块：**1 次成功**（636B $\rightarrow$ 635B），其余三个同构块毫发无损。
+
+---
+
+### 三、 为什么 B4 组还是花了 43 轮（347 秒）？—— 罪魁祸首只有 6 行代码
+
+既然 `editFile` 0 翻车一次过，为什么 B4 组还是跑了 43 轮？
+拆解 [output.txt](file:///C:/Users/dream/.gemini/antigravity/brain/f7c26020-3bdd-4477-b804-f050d731bc85/.system_generated/steps/9174/output.txt) 的时间轴，原因一目了然：
+
+| 阶段 | 轮次范围 | 消耗轮次 | 耗时 | 发生了什么？ |
+| :--- | :--- | :--- | :--- | :--- |
+| **阶段 1：读源码找跳板与容器接口** | Turn 1 ~ 19 | **19 轮** | `93 秒` | Flash 在 Turn 5 读完 [`bin/filaxis.ts`](file:///C:/Users/dream/.gemini/antigravity/brain/f7c26020-3bdd-4477-b804-f050d731bc85/scratch/filaxis_alpha/package/bin/filaxis.ts#L22-L57) 发现：**CLI 只有 `--host --user --port --key`，没有 `--jump` 和 `--enter`！** 也就是说，`alpha.11` 在 `bin/filaxis.ts` 里刚加好的 `--stdin-json` / `--request-file`，在面对跳板机+容器时**根本用不上**！Flash 被迫连读 14 轮 `ssh-helpers.ts` 和 `ssh-pty-driver.ts` 源码去查 SDK 怎么配 `jump` 和 `enterCmd`。 |
+| **阶段 2：写 6 个 `.ts` 脚本并执行** | Turn 20 ~ 41 | **14 轮** | `199 秒` | 因为不能用 CLI 一行流，Flash 每做一步操作都要先 `write_file(xxx.ts)` 再 `run_command(bun run xxx.ts)`（共写了 `test_connect.ts`、`step1_diagnose.ts`、`inspect_files.ts`、`run_self_test.ts`、`remediate.ts`、`final_check.ts` 6 个脚本）。 |
+| **阶段 3：单脚本串行多次 SSH 触发后台轮询** | Turn 27~28, 34~38, 41 | **8 轮** | `40 秒` | 因为在单个 `.ts` 脚本里串行调了 4~6 次 `drv.exec` / `editFile`（每次跨跳板机+容器约 2.2s），单脚本总耗时约 12~15s，刚好超过 `run_command` 的 10s 同步等待阈值，触发了 8 次 `manage_task(status)` 轮询。 |
+
+---
+
+### 四、 给 `0.1.0-alpha.12` 的「最后一公里」建议：打通 CLI 的多层穿透参数
+
+目前 Filaxis 的**内核层（`SshPtyDriver` + `renderExecChannel` + `editFile`）已经完全支持跳板机（`jump`）和容器/内层 Shell 穿透（`enterPipeline` / `enterCmd`）**，而 `alpha.11` 新增的 `--request-file` / `--stdin-json` 也已经在 [`bin/filaxis.ts`](file:///C:/Users/dream/.gemini/antigravity/brain/f7c26020-3bdd-4477-b804-f050d731bc85/scratch/filaxis_alpha/package/bin/filaxis.ts#L98-L120) 就位了。
+
+唯一断掉的一环，就是 [`bin/filaxis.ts` (第 22-57 行)](file:///C:/Users/dream/.gemini/antigravity/brain/f7c26020-3bdd-4477-b804-f050d731bc85/scratch/filaxis_alpha/package/bin/filaxis.ts#L22-L57) 还没把 `jump` 和 `enter` 暴露成命令行参数！只需要在 `bin/filaxis.ts` 里加上 **6 行代码**：
+
+```ts
+// package/bin/filaxis.ts
+function parseOpts(argv: string[]): {
+    host?: string; user?: string; port?: number; key?: string;
+    jump?: string; enter?: string[];
+    ...
+} {
+    const o: ReturnType<typeof parseOpts> = { positional: [], enter: [] };
+    for (let i = 0; i < argv.length; i++) {
+        ...
+        case "--jump": case "-J": o.jump = argv[++i]; break;
+        case "--enter": o.enter!.push(argv[++i]!); break;
+        case "--docker": o.enter!.push(`docker exec -i ${argv[++i]!} sh`); break;
+```
+并在 `driverFor(opts)` 中透传：
+```ts
+    if (opts.host) {
+        return new SshPtyDriver({
+            driver: "ssh", target: opts.host,
+            config: {
+                connParams: { user: opts.user, port: opts.port, keyFile: opts.key, jump: opts.jump },
+                enterPipeline: opts.enter?.length ? opts.enter.map((cmd) => ({ cmd })) : undefined,
+            },
+        });
+    }
+```
+
+一旦补上这几个参数：
+1. Agent 看到 `filaxis --help` 就能直接写：
+   `filaxis edit --host vm-homelab -J vm-ai-server --docker exam3-edge-b /etc/edge-dispatcher/webhooks.json --request-file req.json`
+2. **前 19 轮读源码（93 秒）直接归零**；
+3. **6 次 `write_file(*.ts)` + 8 次后台任务轮询（14 轮）直接归零**，因为单次 CLI 调用都是 2~4 秒内同步返回的原子操作！

package/package.json

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