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

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.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`;