feat(commondev): 主管式多仓库开发流水线 + sidecar 后端抽象（pi/zcode） (#3)

* feat(commondev): 主管式多仓库开发流水线 + sidecar 后端抽象（pi/zcode） ## 是什么 agent 统筹开发流程的插件：登记项目 → 开工程线（每条线一个隔离工作目录 + 一个 sidecar 子进程 + 一对通道）→ 投递任务 → 同会话续投 → 评审/合入。 38 个工具：project_*/branch_*/workdir_*/job_*/review_*/test_*/ endpoint_*/agent_*/pi_*/conflict_check。 ## sidecar 后端抽象（本轮核心）传输层（local/ssh）与后端（pi/zcode/自定义）**正交**，四个自由组合： driver.json 描述一个后端：script / cliPath / env / args / llmConfig 三级查找：插件数据目录 → **随包 rawfile** → 内置 pi 描述占位符：{workdir} {dataDir} {pluginDir} {rawfile} {sessionId} ★ 内置 pi 回退**与默认后端解耦**（2026-10-17 修）：原实现写 `if cli == defaultAgentCLI { return builtinPiDriver() }`，把"给谁兜底" 和"默认选谁"耦合到同一常量 —— 一旦有人改默认，pi 当场失去兜底，显式 cli="pi" 开始报「驱动不存在」。现在判断字面 "pi"。默认后端保持 **pi**（我们本地主用）；交付方用 zcode 走两种局部开关： · 单线：commondev_branch_open(cli="zcode") · 按机器：commondev_endpoint_set(host=..., cli="zcode") ## zcode 接入（三条真机判据，全部要求真改工程文件） · TestZcodeFullPipeline（29-34s）：随包 driver + 真实 ZCode CLI · TestZcodeOverSSH（39s）：真 ssh + scp，远端 node 跑 zcode · TestZcodeOverSSHWithPerHostEndpoints（68s）：两个 host 别名配不同 cli_path，走端点表而不是全局 settings ★ 会话库必须隔离到工作区（sidecar.mjs 的 ensureWorkspaceSessionStore）：实测 ZCode 的会话库路径**硬编码 homedir()**，`ZCODE_DATA_BASE_DIR` 对它完全无效（26 个会话全落全局库）。但 `<workdir>/.zcode/config.json` 的 `storage.sessionDbPath` **确实生效**。所以启动前写一份工作区配置，一举解决：多线不共用历史 / 不污染全局 ~/.zcode / 删线不留孤儿会话。只在不存在时写 —— 用户手工放的要尊重。 ## 其他 · rawfile：项目根 rawfile/ 默认全收，解到 <插件目录>/rawfile/，绝对路径拒绝 · 凭证：命名引用 + ${ENV_VAR}，独立 0600 文件，绝不进 config.db(0644) · secretshell：给不受信 agent 用的安全 shell（ackey + safeshell） · 冲突检查 / 评审判据 / 镜像 / 每条线独立 workdir（hash 命名，合并后删除）判据 30+ 条，含 4 条「判据本身的判据」（防止判据假绿）。 * fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染 ## 核心缺陷：插件往 stdout 打日志 = 污染 JSON-RPC 协议通道子进程插件与内核用 stdout 传 NDJSON 帧，stderr 才是日志通道。脚手架模板（及 4 个示例插件）用 `fmt.Printf` 打日志 ⇒ 内核收到非 JSON 文本： [proc] weather 收到非法 JSON 帧（21 字节）: invalid character 'i' **生产实测 1038 条**（huawei_smarthome 720 / weather 113 / rss 103 / calendar 102）。后果不只是日志噪音：那一行日志被**丢弃**，插件看起来"没启动"。修法： - hmapdev 模板 `fmt.Printf` → `log.Printf`（9 处） - 示例插件 4 个 14 处：ai_image(2) calendar(5) rss(4) weather(3) + 补 "log" import - 内核侧（主仓）同步让报错可定位：内容摘要 + 可能原因 + 修法判别法：`package main` = 子进程（协议通道，禁用 stdout 打日志）；普通库包 = 进程内插件（编译进内核，写真实终端，**不是**缺陷）—— `internal/plugins/cli` 的 `fmt.Println` 属后者。 ## hmapdev - `cmd_build.go` +136：平台产物精确匹配（`--target` 是**append** 语义，原脚本 `ls dist/*.hmap | head -1` 会按字典序抓到 amd64， **导致 arm64 包里装的是 x86-64 二进制**，且退出码 0、校验和通过） - `cmd_init.go` +46：脚手架 stdio 纪律 - `templates/proc_main.go.tmpl`：补齐 mgrStop/mgrStart/mgrIsRuntimeStopped 三态能力（插件管理器运行态停启） - `templates/plg.json.tmpl` 删除（合并进 cmd_init） ## 判据 - `scaffold_stdout_test.go`（3 条）：扫模板生成的代码不得写 stdout。 ★ 判据自身先假红过一次：**模板的注释里就写了 `fmt.Printf`** ⇒ 必须 `stripTemplateComments()` 之后才判 - `example_stdout_test.go`（2 条）：扫全部 20 个子进程示例插件，报错给**文件:行号**；变异咬住并给出准确行号 - `package_examples_test.go`（2 条）：**执行真实打包脚本** （第一版测的是 hmapdev 而不是脚本 ⇒ 变异不咬） - `cmd_build` / `cmd_init` 新判据 ## 其他 - sdk/settings.go +15（三态能力透传） - `docs/versions.md` +§示例插件协议通道纪律（含生产 1038 条实测表格） - `skills/homeagent-plugin-dev/SKILL.md` +§协议通道纪律（正误代码对比） * fix(examples): 恢复 go.mod 相对路径 + 移除 plg.json 的 sdk 固定（修 CI 红） CI 上 `Examples (linux/amd64)` 与 `(darwin/arm64)` 双红，只有两个失败： ✗ commondev 构建失败 ✗ editdoc 构建失败 error: 项目声明 sdk=1.4.0，但本地 SDK 存储里没有这个版本其余 20 个示例全部成功 —— 说明不是通用问题，而是这两个被改坏了。 ## 根因（两个叠加） **① go.mod 被本机绝对路径污染** 我在上一个提交里用 `git add -A`，把本机 `go build` **自动改写**过的 go.mod 一并提交了： require github.com/JianFeeeee/homeagentsdk v1.4.0 replace github.com/JianFeeeee/homeagentsdk => /root/.homeagent/hmapdev/sdk/v1.4.0 基线（origin/main）是： require github.com/JianFeeeee/homeagentsdk v0.0.0 replace github.com/JianFeeeee/homeagentsdk => ../../ 本机那个目录真的存在 ⇒ 本地全绿；CI 没有 ⇒ 必红。 **② plg.json 声明了 `"sdk": "1.4.0"`** 一声明版本，hmapdev 就去**本地 SDK store** 找它，找不到直接拒绝构建。全仓 20+ 示例**都不声明**，只有我改过的这两个声明了。示例的正确依赖表达是 go.mod 的 `v0.0.0` + `replace ../../`。 ## 修法两个文件都恢复到与其余示例一致的写法。 ## 判据（3 条，都是新加的） · `TestExampleGoModHasNoAbsoluteReplace`：任何示例 go.mod 不得含 `/root/`、`/home/`、`/Users/`、`C:\` · `TestExampleGoModUsesRelativeSDKReplace`：replace 必须是相对路径 `../../` · `TestExamplePlgJsonDoesNotPinSDKVersion`：plg.json 不得声明 sdk 变异 2/2 咬住（重新引入绝对路径 / 重新声明 sdk，都准确报出文件路径）。 ## 本地验证（模拟 CI 干净环境）用干净 HOME 跑 `package/build-examples.sh`： · 修复前：成功 18 / 失败 4（commondev, editdoc, browser, rss） · 修复后：成功 20 / 失败 2（browser, rss —— **本机代理不通**， `proxy.golang.org` 超时；用本地 modcache 验证这两个可正常构建）即 22/22 源码都能构建，CI 有网络不受影响。 ## 教训 `git add -A` 会把「构建工具自动改写的文件」一起提交。提交前必须 `git status` 逐个看，尤其 go.mod / go.sum。 --------- Co-authored-by: JianFeeeee <JianFeeeee@users.noreply.gitcode.com>
2026-11-01 06:47:25 +00:00 · 2026-10-17 19:44:15 +08:00
parent 65d2bd9e61
commit 81a3efa4df
91 changed files with 21184 additions and 224 deletions
--- a/example/commondev/endpoints_test.go
+++ b/example/commondev/endpoints_test.go
@ -0,0 +1,388 @@
+package main
+
+// 远端端点表的判据。
+//
+// 核心要证明的**不是**"有个 endpoints.json"，而是：
+//   ① 多台机器**互不干扰**（这是用户提出该需求的唯一理由）；
+//   ② 本机路径**绝不**下发到远端（这是最危险的真实缺陷）；
+//   ③ 同一机器上不同后端可以各有各的路径；
+//   ④ 出错时错误信息**指出该改哪里**（否则用户只能猜）。
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	sdk "github.com/JianFeeeee/homeagentsdk/sdk"
+)
+
+// newEndpointPlugin 造一个带端点表的插件（数据目录在临时目录）。
+func newEndpointPlugin(t *testing.T) *Plugin {
+	t.Helper()
+	sdkp := sdk.New("commondev-test", nil, nil, nil, nil, nil)
+	p := &Plugin{sdk: sdkp}
+	dir := t.TempDir()
+	p.path = filepath.Join(dir, "ledger.json")
+	if err := p.loadEndpoints(); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+// ★★★ 判据：两台机器的配置**互不干扰**。
+//
+// 这是用户提出该需求的原因：改动前只有一组全局 settings
+// （ssh_node_path / ssh_runtime_root / ssh_workdir_root），两台机器时
+// 后配的覆盖前一台，表现为"换台机器就报找不到 node/脚本"，
+// 而报错指向的是**另一台机器的路径**。
+func TestEndpointsArePerHost(t *testing.T) {
+	p := newEndpointPlugin(t)
+
+	set := func(host string, kv map[string]interface{}) {
+		t.Helper()
+		args := map[string]interface{}{"host": host, "verify": false}
+		for k, v := range kv {
+			args[k] = v
+		}
+		r, _ := p.handleEndpointSet(args)
+		if m := r.(map[string]interface{}); m["error"] != nil {
+			t.Fatalf("设置 %s 失败: %v", host, m["error"])
+		}
+	}
+
+	set("alpha", map[string]interface{}{
+		"cli_path": "/opt/alpha/bin/zcode.cjs", "node_path": "/usr/local/bin/node",
+		"runtime_root": "/home/a/rt", "workdir_root": "/home/a/prog",
+	})
+	set("beta", map[string]interface{}{
+		"cli_path": "/srv/beta/zcode.mjs", "node_path": "/opt/node/bin/node",
+		"runtime_root": "/srv/rt", "workdir_root": "/srv/prog",
+	})
+
+	// ★ 每台机器解析出的都必须是**自己**那套
+	drv := driverSpec{}
+	ctx := driverCtx{}
+
+	ea := p.resolveEndpoint("alpha", "zcode", drv, ctx)
+	if ea.CLIPath != "/opt/alpha/bin/zcode.cjs" {
+		t.Errorf("alpha 的 cliPath 被串了: %q", ea.CLIPath)
+	}
+	if ea.NodePath != "/usr/local/bin/node" || ea.RuntimeRoot != "/home/a/rt" {
+		t.Errorf("alpha 的 node/runtime 被串了: %+v", ea)
+	}
+	if ea.WorkdirRoot != "/home/a/prog" {
+		t.Errorf("alpha 的 workdirRoot 被串了: %q", ea.WorkdirRoot)
+	}
+
+	eb := p.resolveEndpoint("beta", "zcode", drv, ctx)
+	if eb.CLIPath != "/srv/beta/zcode.mjs" {
+		t.Errorf("beta 的 cliPath 被串了: %q", eb.CLIPath)
+	}
+	if eb.NodePath != "/opt/node/bin/node" || eb.RuntimeRoot != "/srv/rt" {
+		t.Errorf("beta 的 node/runtime 被串了: %+v", eb)
+	}
+	if eb.WorkdirRoot != "/srv/prog" {
+		t.Errorf("beta 的 workdirRoot 被串了: %q", eb.WorkdirRoot)
+	}
+
+	// 未配置的第三台：不能"借用"别人的值
+	ec := p.resolveEndpoint("gamma", "zcode", drv, ctx)
+	if ec.CLIPath != "" {
+		t.Errorf("★ gamma 未配置却拿到了别人的 cliPath: %q", ec.CLIPath)
+	}
+}
+
+// ★★★ 判据：同一机器上**不同后端各有各的路径**。
+//
+// 这是需求里"每个 cli 客户端有自己的 ip/cli 对"的一半：
+// 同一台机器上 zcode 在 A、别的 CLI 在 B，必须能分别指定。
+func TestEndpointsPerHostAndCLI(t *testing.T) {
+	p := newEndpointPlugin(t)
+
+	// 机器级默认
+	if r, _ := p.handleEndpointSet(map[string]interface{}{
+		"host": "box", "cli_path": "/usr/local/bin/default-cli", "verify": false,
+	}); r.(map[string]interface{})["error"] != nil {
+		t.Fatalf("设机器默认失败: %v", r)
+	}
+	// zcode 专属（应覆盖机器默认）
+	if r, _ := p.handleEndpointSet(map[string]interface{}{
+		"host": "box", "cli": "zcode", "cli_path": "/opt/zcode/zcode.cjs",
+		"node_path": "/opt/node/bin/node", "verify": false,
+	}); r.(map[string]interface{})["error"] != nil {
+		t.Fatalf("设 zcode 专属失败: %v", r)
+	}
+
+	drv := driverSpec{}
+	ctx := driverCtx{}
+
+	z := p.resolveEndpoint("box", "zcode", drv, ctx)
+	if z.CLIPath != "/opt/zcode/zcode.cjs" {
+		t.Errorf("★ zcode 专属路径未覆盖机器默认: %q", z.CLIPath)
+	}
+	if z.NodePath != "/opt/node/bin/node" {
+		t.Errorf("zcode 专属 node 未生效: %q", z.NodePath)
+	}
+	// 另一个后端：应拿到**机器默认**，而不是 zcode 的
+	other := p.resolveEndpoint("box", "othercli", drv, ctx)
+	if other.CLIPath != "/usr/local/bin/default-cli" {
+		t.Errorf("★ 其他后端应回落到机器默认: %q", other.CLIPath)
+	}
+	if other.NodePath != "node" {
+		t.Errorf("zcode 的 node 不该泄漏给其他后端: %q", other.NodePath)
+	}
+	// 解析来源必须可读（错误信息靠它指出该改哪里）
+	if !strings.Contains(z.CLIPathFrom, "专属") {
+		t.Errorf("CLIPathFrom 未标明来源: %q", z.CLIPathFrom)
+	}
+	if !strings.Contains(other.CLIPathFrom, "host") {
+		t.Errorf("回落时应标明来源是 host 默认: %q", other.CLIPathFrom)
+	}
+}
+
+// ★★★ 判据：**本机路径不得下发到远端**（本会话最危险的真实缺陷）。
+//
+// 改动前 `drv.buildArgs(ctx)` 会把 driver.json 的 `cliPath`
+// （随包默认是 `{rawfile}/zcode/zcode.cjs`）展开成**本机**路径塞进 `--cli`，
+// 然后整条命令发到远端 ⇒ 远端必然报 "No such file"，而用户会去
+// **远端**找原因，真正的错在本地。
+func TestRemoteCommandDoesNotCarryLocalPaths(t *testing.T) {
+	ctx := driverCtx{
+		Workdir: "/w", SessionID: "s", SessionName: "n",
+		DataDir: "/d", PluginDir: "/p", RawfileDir: "/rf",
+	}
+	drv := driverSpec{
+		Args:    []string{"--workdir", "{workdir}", "--session-id", "{sessionId}"},
+		CLIPath: "{rawfile}/zcode/zcode.cjs", // ★ 本机占位符
+	}
+
+	// ① 端点表里配了远端真实路径 ⇒ 命令里只能出现远端那条
+	ep := resolvedEndpoint{CLIPath: "/opt/remote/zcode.cjs"}
+	_, args, _ := buildRemoteCommandFor(drv, ctx, "/usr/bin/node", ep)
+	joined := strings.Join(args, " ")
+	if strings.Contains(joined, "/rf/") || strings.Contains(joined, "{rawfile}") {
+		t.Errorf("★ 远端命令里出现了**本机**路径: %v", args)
+	}
+	if !strings.Contains(joined, "/opt/remote/zcode.cjs") {
+		t.Errorf("★ 远端命令里没有远端 CLI 路径: %v", args)
+	}
+
+	// ② 端点表没配的机器：必须在**启动 ssh 之前**响亮拒绝，
+	//    而不是把本机路径发过去让远端报错。
+	//
+	//    判定依据是**占位符**（本机专属、展开后必然是本机路径），
+	//    不是"任意看起来像本机的绝对路径"—— 后者在 localhost/同构机器上
+	//    是合法的，强制拒绝会挡住真实用法。所以这里用占位符版本断言。
+	errPH := validateRemoteCLIPath("{rawfile}/zcode/zcode.cjs", "zcode")
+	if errPH == nil {
+		t.Error("★ 含本机占位符的路径必须拒绝（展开后就是本机路径）")
+	} else if !strings.Contains(errPH.Error(), "本机") {
+		t.Errorf("错误应点明本机占位符问题: %v", errPH)
+	}
+	// 未配路径（空）必须拒绝并告知去哪儿配
+	if err := validateRemoteCLIPath("", "zcode"); err == nil {
+		t.Error("★ 未配远端路径时应拒绝，而不是把值发过去")
+	}
+	// 完全没配也拒绝，且**告知去哪儿配**
+	err := validateRemoteCLIPath("", "zcode")
+	if err == nil {
+		t.Fatal("未配路径应拒绝")
+	}
+	for _, want := range []string{"endpoint_set", "cli_path", "zcode"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("错误应含 %q 以便用户知道怎么修: %v", want, err)
+		}
+	}
+	// 远端真实路径应通过
+	if err := validateRemoteCLIPath("/opt/remote/zcode.cjs", "zcode"); err != nil {
+		t.Errorf("远端真实路径不该被拒: %v", err)
+	}
+}
+
+// ★★★ 判据：**声明了本机路径要当场拒绝并说明原因**。
+func TestEndpointSetRejectsLocalPath(t *testing.T) {
+	p := newEndpointPlugin(t)
+	// 构造一个"看起来是本机"的路径：用本机真实存在的根
+	hint := currentLocalRootHint()
+	if hint == "" {
+		t.Skip("无法确定本机根，跳过")
+	}
+	local := filepath.Join(hint, "some", "zcode.cjs")
+
+	r, _ := p.handleEndpointSet(map[string]interface{}{
+		"host": "box", "cli_path": local, "verify": false,
+	})
+	m := r.(map[string]interface{})
+	if m["error"] == nil {
+		t.Fatalf("★ 应拒绝本机路径: %s", local)
+	}
+	if !strings.Contains(fmtStr(m["error"]), "本机") {
+		t.Errorf("错误应点明是本机路径: %v", m["error"])
+	}
+	// 占位符同样拒绝
+	r2, _ := p.handleEndpointSet(map[string]interface{}{
+		"host": "box", "cli_path": "{rawfile}/z/x.cjs", "verify": false,
+	})
+	if r2.(map[string]interface{})["error"] == nil {
+		t.Error("★ 应拒绝含 {rawfile} 的路径")
+	}
+	// 远端真实路径应接受
+	r3, _ := p.handleEndpointSet(map[string]interface{}{
+		"host": "box", "cli_path": "/opt/remote/zcode.cjs", "verify": false,
+	})
+	if e := r3.(map[string]interface{})["error"]; e != nil {
+		t.Errorf("远端路径不该被拒: %v", e)
+	}
+}
+
+// ★★★ 判据：删除**不能留下幽灵子项**。
+//
+// 否则会出现"以为删了机器，实际后端覆盖还在，下次又把老路径拿出来用"。
+func TestEndpointRemoveRefusesSilentPartial(t *testing.T) {
+	p := newEndpointPlugin(t)
+	p.handleEndpointSet(map[string]interface{}{"host": "box", "cli_path": "/opt/d", "verify": false})
+	p.handleEndpointSet(map[string]interface{}{"host": "box", "cli": "zcode", "cli_path": "/opt/z", "verify": false})
+
+	// 只给 host：必须拒绝（有子项）
+	r, _ := p.handleEndpointRemove(map[string]interface{}{"host": "box"})
+	m := r.(map[string]interface{})
+	if m["status"] != "refused" {
+		t.Fatalf("★ 有后端覆盖时应拒绝整体删除: %v", m)
+	}
+	// 拒绝后表必须**完整保留**（不能删一半）
+	he := p.getHost("box", false)
+	if he == nil || he.CLIPath != "/opt/d" || len(he.CLIs) != 1 {
+		t.Fatalf("拒绝后配置被改动了: %+v", he)
+	}
+
+	// 先删子项，再删机器 → 成功
+	if r, _ := p.handleEndpointRemove(map[string]interface{}{"host": "box", "cli": "zcode"}); r.(map[string]interface{})["removed"] != true {
+		t.Fatalf("删子项失败: %v", r)
+	}
+	if r, _ := p.handleEndpointRemove(map[string]interface{}{"host": "box"}); r.(map[string]interface{})["removed"] != true {
+		t.Fatalf("删机器失败: %v", r)
+	}
+	if p.getHost("box", false) != nil {
+		t.Error("机器未真正删除")
+	}
+
+	// force 可以一并删
+	p.handleEndpointSet(map[string]interface{}{"host": "box2", "cli_path": "/opt/d", "verify": false})
+	p.handleEndpointSet(map[string]interface{}{"host": "box2", "cli": "zcode", "cli_path": "/opt/z", "verify": false})
+	if r, _ := p.handleEndpointRemove(map[string]interface{}{"host": "box2", "force": true}); r.(map[string]interface{})["removed"] != true {
+		t.Fatalf("force 删除失败: %v", r)
+	}
+	if p.getHost("box2", false) != nil {
+		t.Error("force 未连带删掉子项")
+	}
+}
+
+// ★★★ 判据：端点表**持久化且损坏响亮**。
+//
+// 静默用空表 ⇒ 所有远端配置凭空消失，表现为"我明明配过，怎么又要配"，
+// 而用户会先怀疑自己。
+func TestEndpointsPersistAndCorruptionIsLoud(t *testing.T) {
+	dir := t.TempDir()
+	sdkp := sdk.New("commondev-test", nil, nil, nil, nil, nil)
+	p := &Plugin{sdk: sdkp}
+	p.path = filepath.Join(dir, "ledger.json")
+	if err := p.loadEndpoints(); err != nil {
+		t.Fatal(err)
+	}
+	p.handleEndpointSet(map[string]interface{}{
+		"host": "h1", "cli_path": "/opt/a", "runtime_root": "/rt/a",
+		"workdir_root": "/wd/a", "verify": false,
+	})
+
+	// 重新加载（模拟重启）
+	p2 := &Plugin{sdk: sdkp}
+	p2.path = filepath.Join(dir, "ledger.json")
+	if err := p2.loadEndpoints(); err != nil {
+		t.Fatalf("重载失败: %v", err)
+	}
+	got := p2.resolveEndpoint("h1", "zcode", driverSpec{}, driverCtx{})
+	if got.CLIPath != "/opt/a" || got.RuntimeRoot != "/rt/a" || got.WorkdirRoot != "/wd/a" {
+		t.Fatalf("重启后配置丢失: %+v", got)
+	}
+
+	// 权限 0600（可能含内网地址/目录结构，不该 world-readable）
+	st, err := os.Stat(p.endpointsPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if st.Mode().Perm() != 0o600 {
+		t.Errorf("端点表权限应为 0600，实际 %v", st.Mode().Perm())
+	}
+
+	// 损坏 → 必须响亮
+	if err := os.WriteFile(p.endpointsPath(), []byte("{ not json"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	p3 := &Plugin{sdk: sdkp}
+	p3.path = filepath.Join(dir, "ledger.json")
+	if err := p3.loadEndpoints(); err == nil {
+		t.Fatal("★ 端点表损坏时必须报错（静默用空表 = 所有远端配置消失）")
+	} else if !strings.Contains(err.Error(), "损坏") {
+		t.Errorf("错误应点明损坏: %v", err)
+	}
+
+	// 缺文件不是错误（首次运行）
+	p4 := &Plugin{sdk: sdkp}
+	p4.path = filepath.Join(t.TempDir(), "ledger.json")
+	if err := p4.loadEndpoints(); err != nil {
+		t.Errorf("缺文件不该报错: %v", err)
+	}
+	if p4.endpoints == nil || p4.endpoints.Hosts == nil {
+		t.Error("缺文件后应初始化为空表（不是 nil）")
+	}
+}
+
+// ★★★ 判据：旧配置（全局 settings）**仍然生效**（升级不破坏既有部署）。
+//
+// 但端点表**优先**：不能出现"配了端点表还被旧全局键盖住"。
+func TestEndpointOverridesLegacySettings(t *testing.T) {
+	p := newEndpointPlugin(t)
+	// 用 stubSettings 提供旧键
+	p.sdk = sdk.New("commondev-test", newStubSettingsWith(t.TempDir(), map[string]interface{}{
+		"ssh_runtime_root": "/legacy/rt",
+		"ssh_workdir_root": "/legacy/wd",
+		"ssh_node_path":    "/legacy/node",
+	}), nil, nil, nil, nil)
+
+	// ① 旧键生效（升级不破坏）
+	e := p.resolveEndpoint("h", "zcode", driverSpec{}, driverCtx{})
+	if e.RuntimeRoot != "/legacy/rt" || e.WorkdirRoot != "/legacy/wd" || e.NodePath != "/legacy/node" {
+		t.Fatalf("旧全局配置应仍生效: %+v", e)
+	}
+
+	// ② 端点表配了 → 必须压过旧键
+	p.handleEndpointSet(map[string]interface{}{
+		"host": "h", "runtime_root": "/new/rt", "workdir_root": "/new/wd",
+		"node_path": "/new/node", "verify": false,
+	})
+	e2 := p.resolveEndpoint("h", "zcode", driverSpec{}, driverCtx{})
+	if e2.RuntimeRoot != "/new/rt" {
+		t.Errorf("★ 端点表未压过旧键: %q", e2.RuntimeRoot)
+	}
+	if e2.WorkdirRoot != "/new/wd" {
+		t.Errorf("★ 端点表未压过旧 ssh_workdir_root: %q", e2.WorkdirRoot)
+	}
+	if e2.NodePath != "/new/node" {
+		t.Errorf("★ 端点表未压过旧 ssh_node_path: %q", e2.NodePath)
+	}
+}
+
+func fmtStr(v interface{}) string {
+	if v == nil {
+		return ""
+	}
+	return strings.TrimSpace(strings.ReplaceAll(strings.TrimSpace(toString(v)), "\n", " "))
+}
+
+func toString(v interface{}) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	return ""
+}