magic-agent 2.4.3 → 2.6.3

package/internal/client/knowledge_test.go

@@ -0,0 +1,510 @@
+package client
+
+/* knowledge_test.go — 「发现 → 知识库」（OpenViking）的行为钉住：
+ *  ① 清单只从服务端那张表里来，客户端传什么都在表里找；
+ *  ② 安装动作只跑服务端构造好的 argv，**不接受客户端传命令**；
+ *  ③ 状态如实：没装就说没装，版本读不到就留空（不编），查不到最新版本也不报错卡住；
+ *  ④ 可升级的判定要真的比较版本号，且预发布版不提示升级。
+
+ * ⚠️ 这些用例**不打外网、不真装 openviking**：PyPI 查询与 python 探测都换成桩。 */
+
+import (
+	"bufio"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// fakeKnowledgeEnv 造一个「家目录 + 干净的 PATH」的临时环境。
+//
+// ⚠️ PATH 必须**只留临时 binDir**、不能追加原 PATH：本机真的装了 OpenViking
+// （`C:\Python313\Scripts\ov.exe` 在 PATH 上），追加原 PATH 会让「PATH 上没有 ov」
+// 这条断言永远不成立 —— 而且那不是代码的问题，是本机的真实状态。
+func fakeKnowledgeEnv(t *testing.T) (home string, binDir string) {
+	t.Helper()
+	root := t.TempDir()
+	home = filepath.Join(root, "home")
+	binDir = filepath.Join(root, "bin")
+	for _, d := range []string{home, binDir} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("PATH", binDir)
+	t.Setenv(ovEnvBin, "")
+	t.Setenv(ovEnvPython, "")
+
+	oldHome := ovHomeDir
+	oldProbe := ovPythonProbe
+	oldPyPI := pypiLatest
+	t.Cleanup(func() {
+		ovHomeDir = oldHome
+		ovPythonProbe = oldProbe
+		pypiLatest = oldPyPI
+	})
+	ovHomeDir = func() (string, error) { return home, nil }
+	// python 探测打桩：假装系统里有 3.13（够 ≥3.10 就行），但**不真的建 venv**。
+	ovPythonProbe = func() ([]string, string) { return []string{"python3"}, "3.13.3" }
+	pypiLatest = func(pkg string) (string, error) { return "", nil }
+	return home, binDir
+}
+
+// writeFakeOV 在 PATH 上放一个假 `ov`。
+//
+// ⚠️ Windows 上必须带 .exe 后缀：Go 的 LookPath 对无扩展名的文件会按 PATHEXT
+// 逐个加后缀去找，不会直接用裸名 —— 裸名文件在 Windows 上永远找不到。
+func writeFakeOV(t *testing.T, binDir, name, content string) string {
+	t.Helper()
+	if runtime.GOOS == "windows" && filepath.Ext(name) == "" {
+		name += ".exe"
+	}
+	p := filepath.Join(binDir, name)
+	if err := os.WriteFile(p, []byte(content), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return p
+}
+
+func knowledgeService() *Service { return &Service{opts: Options{}} }
+
+/* ── 清单 ── */
+
+func TestKnowledgeListsCatalog(t *testing.T) {
+	fakeKnowledgeEnv(t)
+	rec := httptest.NewRecorder()
+	knowledgeService().handleKnowledge(rec, httptest.NewRequest(http.MethodGet, "/desk/knowledge", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("状态码 = %d，期望 200", rec.Code)
+	}
+	var body struct {
+		Knowledge []knowledgeInfo `json:"knowledge"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("响应不是合法 JSON：%v（%s）", err, rec.Body.String())
+	}
+	if len(body.Knowledge) != 1 {
+		t.Fatalf("知识库数 = %d，期望 1（openviking）", len(body.Knowledge))
+	}
+	k := body.Knowledge[0]
+	if k.ID != "openviking" {
+		t.Fatalf("id = %q，期望 openviking", k.ID)
+	}
+	// PATH 上没有 → 必须如实说没装，而不是给一个看起来成功的空壳
+	if k.Installed {
+		t.Fatal("PATH 上没有 ov 时 Installed 应为 false")
+	}
+	if k.Tagline == "" || k.Description == "" || len(k.Examples) == 0 {
+		t.Fatal("介绍三件套（一句话简介 / 详细说明 / 示例）不能空 —— 发现页要展示它们")
+	}
+	if !strings.Contains(k.UsePrompt, "知识库") {
+		t.Fatal("让它干活的预填提示里要点明用途")
+	}
+	if k.Note == "" {
+		t.Fatal("必须有一句 note 讲清「为什么是现在这个状态」")
+	}
+}
+
+/* ── 探测：环境变量 / venv / PATH 三档 ── */
+
+// 环境变量指定的命令优先级最高（用户显式指定）。
+func TestKnowledgeDetectsEnvOverride(t *testing.T) {
+	home, binDir := fakeKnowledgeEnv(t)
+	custom := writeFakeOV(t, binDir, "my-ov", "#!/bin/sh\n")
+	t.Setenv(ovEnvBin, custom)
+
+	d := detectOpenViking()
+	if d.Bin != custom {
+		t.Fatalf("bin = %q，期望 %q", d.Bin, custom)
+	}
+	if d.Source != "env" {
+		t.Fatalf("source = %q，期望 env", d.Source)
+	}
+	_ = home
+}
+
+// 自建 venv 里的命令**不在 PATH 上** —— 一键安装装进 venv 后 `ov` 就不在 PATH，
+// 所以 venv 这档必须排在 PATH 之前，否则「刚装好」会被误报成「未安装」。
+func TestKnowledgeDetectsVenvBeforePath(t *testing.T) {
+	home, binDir := fakeKnowledgeEnv(t)
+	// PATH 上放一个同名命令：它应该被 venv 里那个**盖掉**（venv 优先）。
+	writeFakeOV(t, binDir, "ov", "#!/bin/sh\n")
+
+	venvBin := filepath.Join(ovVenvBinDir(filepath.Join(home, ovVenvName)), "ov")
+	if runtime.GOOS == "windows" {
+		venvBin += ".exe"
+	}
+	if err := os.MkdirAll(filepath.Dir(venvBin), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(venvBin, []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	d := detectOpenViking()
+	if d.Source != "venv" {
+		t.Fatalf("source = %q，期望 venv（venv 里的命令不在 PATH 上，必须先认它）", d.Source)
+	}
+	if d.Bin != venvBin {
+		t.Fatalf("bin = %q，期望 %q", d.Bin, venvBin)
+	}
+}
+
+// 两个命令名都认：0.5.2 的文档给 `ov`，0.4.15 的文档给 `openviking`。
+// 认错的后果是「明明装了却说没装」。
+func TestKnowledgeAcceptsBothCLINames(t *testing.T) {
+	_, binDir := fakeKnowledgeEnv(t)
+	for _, name := range ovCLINames {
+		t.Run(name, func(t *testing.T) {
+			_, binDir := fakeKnowledgeEnv(t)
+			p := writeFakeOV(t, binDir, name, "#!/bin/sh\n")
+			d := detectOpenViking()
+			if d.Bin != p {
+				t.Fatalf("bin = %q，期望 %q（命令名 %s 应当被认）", d.Bin, p, name)
+			}
+		})
+	}
+	_ = binDir
+}
+
+/* ── 版本号：分层兜底 ── */
+
+// L1：CLI 自己说（`--version`）。
+func TestKnowledgeVersionFromCLI(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("本用例用 shell 脚本桩，Windows 上跑不了")
+	}
+	_, binDir := fakeKnowledgeEnv(t)
+	bin := writeFakeOV(t, binDir, "ov", "#!/bin/sh\necho 'ov 0.5.2'\n")
+	if got := versionFromCLI(bin); got != "0.5.2" {
+		t.Fatalf("版本 = %q，期望 0.5.2", got)
+	}
+}
+
+// L2：从 dist-info 目录名读（纯文件系统，不依赖解释器）。
+// 这层是「CLI 没有 --version」时的主路径 —— `ov --version` 是否被支持并未确认。
+func TestKnowledgeVersionFromDistInfo(t *testing.T) {
+	home, _ := fakeKnowledgeEnv(t)
+	venv := filepath.Join(home, ovVenvName)
+	site := filepath.Join(venv, "Lib", "site-packages")
+	if runtime.GOOS != "windows" {
+		site = filepath.Join(venv, "lib", "python3.12", "site-packages")
+	}
+	dist := filepath.Join(site, "openviking-0.4.15.dist-info")
+	if err := os.MkdirAll(dist, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dist, "METADATA"), []byte("Name: openviking\nVersion: 0.4.15\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// 放一个空的 bin（不传 bin 也行，但传了更贴近真实形态）
+	bin := filepath.Join(ovVenvBinDir(venv), "ov")
+	if runtime.GOOS == "windows" {
+		bin += ".exe"
+	}
+	if err := os.MkdirAll(filepath.Dir(bin), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	got := versionFromDistInfo(bin, venv)
+	if got != "0.4.15" {
+		t.Fatalf("版本 = %q，期望 0.4.15", got)
+	}
+}
+
+// 读不到版本就留空 —— 绝不编一个看起来对的版本号。
+func TestKnowledgeVersionEmptyWhenUnreadable(t *testing.T) {
+	home, _ := fakeKnowledgeEnv(t)
+	if got := readOpenVikingVersion("", home); got != "" {
+		t.Fatalf("没有命令时版本应为空串，实际 %q", got)
+	}
+}
+
+/* ── 版本比较 ── */
+
+func TestKnowledgeVersionCompare(t *testing.T) {
+	cases := []struct {
+		cur, latest string
+		less        bool
+	}{
+		{"0.4.15", "0.5.2", true},
+		{"0.5.2", "0.5.2", false},
+		{"0.6.0", "0.5.2", false},
+		{"0.5.2", "0.5.10", true},
+		{"1.0.0", "0.9.9", false},
+		{"", "0.5.2", false},
+		{"0.5.2", "", false},
+	}
+	for _, c := range cases {
+		if got := ovVersionLess(c.cur, c.latest); got != c.less {
+			t.Fatalf("ovVersionLess(%q, %q) = %v，期望 %v", c.cur, c.latest, got, c.less)
+		}
+	}
+}
+
+// 预发布版**不**提示升级 —— 那不是「有新版」，是「有测试版」。
+//
+// ⚠️ 判据不是「有没有 '-'」：PEP 440 的预发布形态**不一定用连字符分隔**
+// （实测本机 `ov --version` 吐 `0.4.16.dev0`，PyPI 上还有 `0.6.0rc1` 这种连字符都没有的）。
+func TestKnowledgePreReleaseNotOffered(t *testing.T) {
+	for _, v := range []string{
+		"0.6.0rc1", "0.6.0-rc1", "1.0.0a2", "1.0.0-alpha2", "0.7.0.dev3",
+		"0.4.16.dev0", "1.0.0b1", "1.0.0pre1",
+	} {
+		if !ovIsPreRelease(v) {
+			t.Fatalf("%q 应判为预发布", v)
+		}
+	}
+	for _, v := range []string{"0.5.2", "1.0.0", "0.4.16", "2.0.0+local"} {
+		if ovIsPreRelease(v) {
+			t.Fatalf("%q 不应判为预发布", v)
+		}
+	}
+}
+
+// 版本号提取要连后缀一起拿：`ov --version` 吐的是 `openviking 0.4.16.dev0`，
+// 只取数字段会把这个 dev 版说成正式版 0.4.16（然后界面就误判「已是最新」）。
+func TestKnowledgeVersionTokenKeepsSuffix(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"openviking 0.4.16.dev0", "0.4.16.dev0"},
+		{"OpenViking v0.5.2", "0.5.2"},
+		{"0.6.0rc1", "0.6.0rc1"},
+		{"0.5.2+local", "0.5.2+local"},
+		{"no version here", ""},
+	}
+	for _, c := range cases {
+		if got := ovVersionToken(c.in); got != c.want {
+			t.Fatalf("ovVersionToken(%q) = %q，期望 %q", c.in, got, c.want)
+		}
+	}
+}
+
+/* ── 最新版本：查不到不报错 ── */
+
+func TestKnowledgeLatestVersionUnavailable(t *testing.T) {
+	fakeKnowledgeEnv(t)
+	pypiLatest = func(pkg string) (string, error) { return "", os.ErrNotExist }
+	s := knowledgeService()
+	v, ok := s.ovLatestVersion(ovPyPackage)
+	if ok {
+		t.Fatalf("查不到时 ok 应为 false，实际 %q", v)
+	}
+	if v != "" {
+		t.Fatalf("查不到时版本应为空串，实际 %q", v)
+	}
+}
+
+// 缓存：连续两次查询只打一次外网。
+func TestKnowledgeLatestVersionCached(t *testing.T) {
+	fakeKnowledgeEnv(t)
+	calls := 0
+	pypiLatest = func(pkg string) (string, error) {
+		calls++
+		return "0.5.2", nil
+	}
+	s := knowledgeService()
+	for i := 0; i < 3; i++ {
+		v, ok := s.ovLatestVersion(ovPyPackage)
+		if !ok || v != "0.5.2" {
+			t.Fatalf("第 %d 次查询 = (%q, %v)", i+1, v, ok)
+		}
+	}
+	if calls != 1 {
+		t.Fatalf("外网查询次数 = %d，期望 1（要有缓存）", calls)
+	}
+}
+
+/* ── 可升级判定 ── */
+
+func TestKnowledgeUpgradeAvailable(t *testing.T) {
+	home, binDir := fakeKnowledgeEnv(t)
+	// 造一个「装着 0.4.15」的 venv：dist-info 目录名就是版本来源
+	venv := filepath.Join(home, ovVenvName)
+	site := filepath.Join(venv, "Lib", "site-packages")
+	if runtime.GOOS != "windows" {
+		site = filepath.Join(venv, "lib", "python3.12", "site-packages")
+	}
+	if err := os.MkdirAll(filepath.Join(site, "openviking-0.4.15.dist-info"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	bin := filepath.Join(ovVenvBinDir(venv), "ov")
+	if runtime.GOOS == "windows" {
+		bin += ".exe"
+	}
+	if err := os.MkdirAll(filepath.Dir(bin), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(bin, []byte("#!/bin/sh\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writeFakeOV(t, binDir, "other", "#!/bin/sh\n") // PATH 上有个无关命令，别被认成 ov
+
+	pypiLatest = func(pkg string) (string, error) { return "0.5.2", nil }
+	s := knowledgeService()
+	info := s.knowledgeInfoOf(knowledgeSpecs()[0])
+	if !info.Installed {
+		t.Fatal("venv 里有命令时 Installed 应为 true")
+	}
+	if info.Version != "0.4.15" {
+		t.Fatalf("版本 = %q，期望 0.4.15", info.Version)
+	}
+	if !info.UpgradeAvailable {
+		t.Fatal("本机 0.4.15 < 最新 0.5.2，UpgradeAvailable 应为 true")
+	}
+	if info.LatestVersion != "0.5.2" {
+		t.Fatalf("最新版本 = %q，期望 0.5.2", info.LatestVersion)
+	}
+}
+
+/* ── 安装 / 升级 ── */
+
+// 安装动作：只跑服务端构造好的 argv，输出按行流回。
+func TestKnowledgeInstallStreams(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("本用例用 shell 脚本桩，Windows 上跑不了")
+	}
+	home, binDir := fakeKnowledgeEnv(t)
+	// 桩 python：建 venv 那步把「假 ov」放进 venv 的 bin 目录 ——
+	// 于是「跑完重新探测」这条链真的会翻成 installed=true，而不是靠测试自己断言。
+	venv := filepath.Join(home, ovVenvName)
+	py := filepath.Join(binDir, "python3")
+	script := "#!/bin/sh\necho \"python $*\"\n" +
+		"if [ \"$2\" = \"venv\" ]; then\n" +
+		"  mkdir -p \"" + filepath.Join(venv, "bin") + "\"\n" +
+		"  printf '#!/bin/sh\\necho \"ov 0.5.2\"\\n' > \"" + filepath.Join(venv, "bin", "ov") + "\"\n" +
+		"  chmod +x \"" + filepath.Join(venv, "bin", "ov") + "\"\n" +
+		"fi\n" +
+		"exit 0\n"
+	if err := os.WriteFile(py, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	rec := httptest.NewRecorder()
+	knowledgeService().handleKnowledgeAction(rec,
+		httptest.NewRequest(http.MethodPost, "/desk/knowledge/openviking/install", nil))
+	if rec.Code != http.StatusOK {
+		t.Fatalf("状态码 = %d，期望 200（SSE）：%s", rec.Code, rec.Body.String())
+	}
+	if ct := rec.Header().Get("Content-Type"); !strings.Contains(ct, "text/event-stream") {
+		t.Fatalf("Content-Type = %q，期望 SSE", ct)
+	}
+
+	events := map[string][]string{}
+	var cur string
+	sc := bufio.NewScanner(strings.NewReader(rec.Body.String()))
+	for sc.Scan() {
+		line := sc.Text()
+		switch {
+		case strings.HasPrefix(line, "event: "):
+			cur = strings.TrimPrefix(line, "event: ")
+		case strings.HasPrefix(line, "data: "):
+			events[cur] = append(events[cur], strings.TrimPrefix(line, "data: "))
+		}
+	}
+	if len(events["open"]) != 1 {
+		t.Fatalf("应先发一条 open（告诉客户端要跑什么），实际 %v", events)
+	}
+	var open struct {
+		Commands []string `json:"commands"`
+	}
+	_ = json.Unmarshal([]byte(events["open"][0]), &open)
+	if len(open.Commands) != 3 {
+		t.Fatalf("open.commands = %v，期望三条（建 venv / pip install / pip show）", open.Commands)
+	}
+	if !strings.Contains(strings.Join(open.Commands, " "), "pip") {
+		t.Fatalf("命令里应有 pip：%v", open.Commands)
+	}
+	if !strings.Contains(strings.Join(events["line"], "\n"), "python") {
+		t.Fatalf("安装输出没有流回客户端：%v", events["line"])
+	}
+	if len(events["end"]) != 1 {
+		t.Fatalf("必须恰好一条 end 收尾，实际 %d", len(events["end"]))
+	}
+	var end struct {
+		OK        bool          `json:"ok"`
+		Knowledge knowledgeInfo `json:"knowledge"`
+	}
+	_ = json.Unmarshal([]byte(events["end"][0]), &end)
+	if !end.OK {
+		t.Fatalf("安装成功却回了 ok=false：%s", events["end"][0])
+	}
+	if !end.Knowledge.Installed {
+		t.Fatalf("跑完应重新探测到已安装（end.knowledge.installed 仍为 false）：%s", events["end"][0])
+	}
+}
+
+// 未知 id / 未知动作一律 404，且**没有任何命令被执行** —— 这条接口不能变成任意命令执行器。
+func TestKnowledgeActionRejectsUnknown(t *testing.T) {
+	fakeKnowledgeEnv(t)
+	for _, target := range []string{
+		"/desk/knowledge/rm-rf/install",
+		"/desk/knowledge/openviking/run",
+		"/desk/knowledge/openviking",
+	} {
+		rec := httptest.NewRecorder()
+		knowledgeService().handleKnowledgeAction(rec, httptest.NewRequest(http.MethodPost, target, nil))
+		if rec.Code != http.StatusNotFound {
+			t.Fatalf("%s 状态码 = %d，期望 404", target, rec.Code)
+		}
+	}
+}
+
+// 失败的安装：退出码 + 错误要回给客户端，end.ok=false（不能静默当成功）。
+func TestKnowledgeInstallFailureReported(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("本用例用 shell 脚本桩，Windows 上跑不了")
+	}
+	_, binDir := fakeKnowledgeEnv(t)
+	py := filepath.Join(binDir, "python3")
+	if err := os.WriteFile(py, []byte("#!/bin/sh\necho 'EACCES: permission denied' >&2\nexit 3\n"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	knowledgeService().handleKnowledgeAction(rec,
+		httptest.NewRequest(http.MethodPost, "/desk/knowledge/openviking/install", nil))
+	body := rec.Body.String()
+	if !strings.Contains(body, "EACCES: permission denied") {
+		t.Fatalf("stderr 没有流回客户端：%s", body)
+	}
+	if !strings.Contains(body, `"ok":false`) {
+		t.Fatalf("失败应以 ok=false 收尾：%s", body)
+	}
+}
+
+/* ── python 探测 ── */
+
+// 找不到 ≥3.10 的 python → 就没有安装命令（界面要如实说「装不了」，而不是给一条跑不通的命令）。
+func TestKnowledgeNoPythonNoSteps(t *testing.T) {
+	fakeKnowledgeEnv(t)
+	ovPythonProbe = func() ([]string, string) { return nil, "" }
+	isteps, usteps := ovSteps()
+	if len(isteps) != 0 || len(usteps) != 0 {
+		t.Fatalf("没有 python 时不该有步骤，实际 %v / %v", isteps, usteps)
+	}
+	rec := httptest.NewRecorder()
+	knowledgeService().handleKnowledgeAction(rec,
+		httptest.NewRequest(http.MethodPost, "/desk/knowledge/openviking/install", nil))
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("状态码 = %d，期望 400（没有 python 就装不了）", rec.Code)
+	}
+}
+
+// 3.9 不满足 OpenViking 的要求（需要 ≥3.10）。
+func TestKnowledgePythonVersionGate(t *testing.T) {
+	if ovPythonVersionOK("3.9.7") {
+		t.Fatal("3.9.7 不该通过（OpenViking 需要 ≥3.10）")
+	}
+	if !ovPythonVersionOK("3.10.0") {
+		t.Fatal("3.10.0 应通过")
+	}
+	if !ovPythonVersionOK("3.13.3") {
+		t.Fatal("3.13.3 应通过")
+	}
+}

package/internal/client/lan.go

@@ -8,9 +8,9 @@ import (
 
 /* 局域网接入（P4 的第一级：让手机能连上）。
  *
- * 默认只绑 127.0.0.1 是刻意的：本地端口对同机所有进程可见，开了鉴权才敢往外露。
- * 手机要连就得绑到局域网，而这一开，**令牌就成了唯一的门锁** —— 所以这里的两条
- * 守卫是配套的：`--lan` 必须给足强度的令牌，短令牌直接拒绝启动。
+ * 默认就绑局域网（0.0.0.0:9100，手机开箱可连）：这一开，**令牌就是唯一的门锁** ——
+ * 所以这里的两条守卫是配套的：局域网模式必须给足强度的令牌，短令牌直接拒绝启动；
+ * 只想本机访问用 `--local` 绑回 127.0.0.1。
  *
  * 三级接入里这一级是 L1（局域网）；L2 的跨网中继需要服务端，不在本文件范围。
  */

package/internal/client/plugins.go

@@ -31,7 +31,8 @@ import (
 type pluginStep struct {
 	Args     []string
 	Optional bool
-	SkipNote string // Optional 步骤跳过时展示的原因
+	SkipNote string   // Optional 步骤跳过时展示的原因
+	Env      []string // 非空 = 用它替代继承的父进程环境（见 npmEnv）
 }
 
 func (p pluginStep) Command() string { return strings.Join(p.Args, " ") }
@@ -342,6 +343,9 @@ func runPluginStep(ctx context.Context, st pluginStep, onLine func(string)) (int
 		return 0, errors.New("空命令")
 	}
 	cmd := exec.CommandContext(ctx, st.Args[0], st.Args[1:]...)
+	if len(st.Env) > 0 {
+		cmd.Env = st.Env
+	}
 	pr, pw, err := os.Pipe()
 	if err != nil {
 		return 1, err

package/internal/client/prefs.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"strings"
 )
 
 /* 移动端「环境配置」的远端存储（2026-10-22 用户：
@@ -97,3 +98,69 @@ func (s *Service) handlePrefs(w http.ResponseWriter, r *http.Request) {
 		writeErr(w, http.StatusMethodNotAllowed, "只支持 GET / PUT")
 	}
 }
+
+// defaultEngineModel 读「我的 → 默认引擎/模型」（2026-10-26 用户：
+// 「手动自动都要默认设置的引擎」）。
+//
+// 手动「整理」是从请求体拿的（移动端每次点都带 engine/model）；后台自动归纳没有
+// 请求体，只能自己去读 —— 与移动端同一份权威存储：/desk/prefs 落的
+// ~/.magic-agent/mobile-prefs.json（键名由移动端定义，这里只按约定取两个）。
+//
+// 不做任何猜测或回退：配置里没设引擎就是空串（core 走自己的默认 llm），
+// **不**用「备用引擎」替补 —— 备用是主引擎失败时才切的东西，不是默认值。
+// 模型只在引擎非空时才返回（core 侧 model 不能脱离 engine 单独指定）。
+func (s *Service) defaultEngineModel() (string, string) {
+	p := mobilePrefsPath()
+	if p == "" {
+		return "", ""
+	}
+	b, err := os.ReadFile(p)
+	if err != nil || len(b) == 0 {
+		return "", ""
+	}
+	var v map[string]any
+	if err := json.Unmarshal(b, &v); err != nil {
+		return "", ""
+	}
+	engine := strings.TrimSpace(prefString(v[prefKeyEngine]))
+	if engine == "" {
+		return "", ""
+	}
+	// 白名单同样要过：白名单外的引擎 core 会拒绝，自动归纳每轮都失败等于没跑。
+	if !s.opts.Profile.AllowsEngine(engine) {
+		s.logf("需求自动归纳: 默认引擎 %q 不在 profile 白名单里，回落 core 默认", engine)
+		return "", ""
+	}
+	return engine, strings.TrimSpace(prefString(v[prefKeyModel]))
+}
+
+// 移动端 /desk/prefs 里的键名（客户端定义、服务端不解释；这里只读这两个）。
+const (
+	prefKeyEngine = "magic.engine"
+	prefKeyModel  = "magic.model"
+)
+
+// prefString 把配置值规整成字符串（值理论上都是字符串，但坏文件兜一下）。
+func prefString(v any) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	return ""
+}
+
+// logf 防御性写日志：Options.Logger 可空（单测 / 内嵌调用），nil 时**不能 panic** ——
+// 自动归纳是后台弱路径，日志丢了可以接受，把客户端带崩不行。
+func (s *Service) logf(format string, args ...any) {
+	if s.log == nil {
+		return
+	}
+	s.log.Printf(format, args...)
+}
+
+// modelSuffix 日志里拼「 · 模型」；没配模型时只留引擎名。
+func modelSuffix(model string) string {
+	if model == "" {
+		return ""
+	}
+	return " · " + model
+}

package/internal/client/procstart_linux.go

@@ -0,0 +1,59 @@
+package client
+
+import (
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// init 在 Linux 上把 procStart 换成精确的版本：/proc/self/stat 的字段 22（starttime，单位
+// 是开机后的时钟滴答）+ btime（/proc/stat），算出本进程真正被拉起的那一刻。
+// 只关系到「盘上的 magic-agent 是不是本进程启动后才被 npm 换掉的」（见 replacedAfterStart），
+// 读不到就保留 mtime 兜底，不影响任何正常路径。
+func init() {
+	start, ok := linuxProcessStart()
+	if !ok {
+		return
+	}
+	procStart = func() (time.Time, bool) { return start, true }
+}
+
+func linuxProcessStart() (time.Time, bool) {
+	b, err := os.ReadFile("/proc/self/stat")
+	if err != nil {
+		return time.Time{}, false
+	}
+	// comm 可能带空格和括号：从最后一个 ')' 之后才开始数字段。之后第一个字段是 3（state），
+	// starttime 是第 22 个 ⇒ 下标 22-3 = 19。
+	s := string(b)
+	i := strings.LastIndexByte(s, ')')
+	if i < 0 {
+		return time.Time{}, false
+	}
+	fields := strings.Fields(s[i+1:])
+	if len(fields) < 20 {
+		return time.Time{}, false
+	}
+	ticks, err := strconv.ParseUint(fields[19], 10, 64)
+	if err != nil {
+		return time.Time{}, false
+	}
+	sb, err := os.ReadFile("/proc/stat")
+	if err != nil {
+		return time.Time{}, false
+	}
+	var btime uint64
+	for _, ln := range strings.Split(string(sb), "\n") {
+		if strings.HasPrefix(ln, "btime ") {
+			btime, _ = strconv.ParseUint(strings.TrimSpace(ln[len("btime "):]), 10, 64)
+			break
+		}
+	}
+	if btime == 0 {
+		return time.Time{}, false
+	}
+	// USER_HZ 在 Linux 上恒为 100（内核导出给用户态的时钟刻度，不随 CONFIG_HZ 变）。
+	sec := btime + ticks/100
+	return time.Unix(int64(sec), int64(ticks%100)*10_000_000), true
+}