magic-agent 1.0.0

package/internal/session/sessionlog.go

@@ -0,0 +1,128 @@
+package session
+
+// sessionlog.go - 「看历史」会话持久化的纯读写路径。
+//
+// 谁用：core CLI 在流式跑时 append 事件到 `<dir>/<session_id>.jsonl`；
+// plugin (`magic-client`) 在 `GET /desk/session/{id}/messages` 路由上读这个文件。
+// 双方都在 `~/.magic-agent/sessions/`（同一目录）。
+//
+// 与 `Begin/Finish` 的关系：这里只管「事件落盘」的内容（流式输出每条事件）；
+// 登记表（`run-*.json`）只记元数据（提示词、状态、pid）。两条线相互独立。
+//
+// 读写路径都放在 `session` 包，而不是 `cli`：因为 plugin (`internal/client`) 也要读。
+// 跨包依赖方向：`internal/client -> internal/session`，避免 `internal/client -> internal/cli`。
+//
+// 设计约束：
+//   - 文件不存在 ≠ 错：返回空 slice + nil error（UI 上「空会话」也是合理状态）。
+//   - 坏行不阻塞：NDJSON 解析失败的行 skip 一次（stderr 打 warning）；
+//     文件里其它正常行仍能取到。
+//   - 大文件：16MB 单行上限（result 行可能很大）；调用方按 seq 翻页可另写。
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+)
+
+// DefaultLogDir 返回 ~/.magic-agent/sessions/（与 core CLI 用的目录一致）。
+//
+// 谁用：plugin (`internal/client`) 在 plugin 进程里直接读历史时 —— core CLI 是另一
+// 个进程，得在 plugin 这边再做一次解析。
+func DefaultLogDir() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("找不到家目录：%w", err)
+	}
+	return filepath.Join(home, ".magic-agent", "sessions"), nil
+}
+
+// SeqOf 从**已解析**的一条事件里取出 seq。
+//
+// 为什么要回调而不是要求 T 带字段：本包被 CLI（`sessionEvent` 结构体）与 plugin
+// （`map[string]any`，它不想依赖 cli 的 schema）两边共用，两者取 seq 的方式不同。
+type SeqOf[T any] func(T) uint64
+
+// ReadSessionLog 读整个 jsonl 到 `[]T`（每条事件一行 JSON）。
+//
+// dir 为空时报错（避免「默认进 home 写错了路径」这种难追的 bug，调用方必须显式传）。
+// 这是**泛型**，因为 events 的具体类型由调用方决定（CLI 用 `sessionEvent`、
+// plugin 也用同一类型 —— 所以 plugin 这边不需要再写一份）。
+//
+// 顺序：seq 升序；空文件返回 nil。损坏行跳过（warn 一行）。
+func ReadSessionLog[T any](dir, sessionID string, parse func([]byte) (T, error)) ([]T, error) {
+	evs, _, err := ReadSessionLogAfter(dir, sessionID, 0, nil, parse)
+	return evs, err
+}
+
+// ReadSessionLogAfter 只读 seq > after 的事件（**断线续读**用）。
+// 返回 (事件, 文件里的最大 seq, error)。after = 0 等价于全量。
+//
+// 语义对齐 agents-anywhere 的 `GET /sessions/{id}/events?after=seq:N`：
+// 客户端报「我已经看到 seq=N」，服务端就从 N+1 开始给。
+//
+// ⚠️ after 是**排他**上界：不回 seq == after 的那条。重复回一条会让客户端的去重
+//
+//	逻辑从「优化」变成「必需」—— 而续读的全部意义就是让客户端不必再关心去重。
+//
+// ⚠️ 返回的 maxSeq 覆盖**整个文件**（含被 after 滤掉的部分）：调用方要用它判断
+//
+//	「客户端的游标是不是超前了」（after > maxSeq ⇒ 客户端状态比磁盘还新，
+//	只可能是日志被重置过、或游标来自另一个会话）。只统计过滤后的事件得不到这个信息。
+//
+// ⚠️ 仍然顺序读完整文件后过滤，没有按 seq 做**定位**（文件是 NDJSON、seq 靠解析才拿到，
+//
+//	无法 seek）。代价是每次续读都要解析整个文件；收益是**网络只传增量**。
+//	本项目的会话规模下这个取舍是划算的（本地解析毫秒级，跨网传全量是百 KB 级）。
+func ReadSessionLogAfter[T any](dir, sessionID string, after uint64, seqOf SeqOf[T], parse func([]byte) (T, error)) ([]T, uint64, error) {
+	if dir == "" {
+		return nil, 0, fmt.Errorf("ReadSessionLog: dir 不能为空（调用方需用 DefaultLogDir() 解析）")
+	}
+	f, err := os.Open(filepath.Join(dir, sessionID+".jsonl"))
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil, 0, nil // 没历史 ≠ 错
+		}
+		return nil, 0, err
+	}
+	defer f.Close()
+	return readNDJSON(f, after, seqOf, parse)
+}
+
+// readNDJSON 流式读 NDJSON。空行 / 坏行跳过（warn 一次）。
+//
+// after / seqOf 都可选：seqOf 为 nil 时不按 seq 过滤（此时 after 无意义），
+// 返回的 maxSeq 也就恒为 0 —— 这两个参数是配套的，调用方别只给一半。
+func readNDJSON[T any](r io.Reader, after uint64, seqOf SeqOf[T], parse func([]byte) (T, error)) ([]T, uint64, error) {
+	var out []T
+	var maxSeq uint64
+	sc := bufio.NewScanner(r)
+	sc.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
+	for sc.Scan() {
+		line := sc.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+		v, err := parse(line)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "magic-agent: 会话历史行解析失败：%v（跳过该行）\n", err)
+			continue
+		}
+		if seqOf == nil {
+			out = append(out, v)
+			continue
+		}
+		s := seqOf(v)
+		// maxSeq 先更新、后过滤：它要反映整个文件，而不只是这一页。
+		if s > maxSeq {
+			maxSeq = s
+		}
+		if s <= after {
+			continue
+		}
+		out = append(out, v)
+	}
+	return out, maxSeq, sc.Err()
+}

package/internal/session/sessionlog_read_test.go

@@ -0,0 +1,157 @@
+package session
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// 会话日志的增量读（断线续读）。这一组钉住三件最容易写错的事：
+//
+//  1. after 是**排他**上界（不回 seq == after 那条）——写成 >= 会让客户端每次续读
+//     都重收一条，去重逻辑就被迫成为必需；
+//  2. 返回的 maxSeq 覆盖**整个文件**而不只是这一页 —— 它是「客户端游标是否超前」的
+//     唯一判据，只统计过滤后的事件就永远判不出超前；
+//  3. 文件不存在时不是错误（新会话没有历史是正常状态）。
+
+// seqEvent 测试用的事件类型：带 seq 与 text 两个字段。
+type seqEvent struct {
+	Seq  uint64 `json:"seq"`
+	Text string `json:"text"`
+}
+
+func parseSeqEvent(line []byte) (seqEvent, error) {
+	var ev seqEvent
+	err := json.Unmarshal(line, &ev)
+	return ev, err
+}
+
+// writeLog 写一份 fixture 会话日志，返回目录。
+func writeLog(t *testing.T, id string, lines ...string) string {
+	t.Helper()
+	dir := t.TempDir()
+	if len(lines) > 0 {
+		body := ""
+		for _, l := range lines {
+			body += l + "\n"
+		}
+		if err := os.WriteFile(filepath.Join(dir, id+".jsonl"), []byte(body), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return dir
+}
+
+func TestReadSessionLogAfterFiltersBySeq(t *testing.T) {
+	dir := writeLog(t, "s", `{"seq":1,"text":"a"}`, `{"seq":2,"text":"b"}`, `{"seq":3,"text":"c"}`)
+
+	// after=1 → 只回 2、3（排他）。
+	evs, maxSeq, err := ReadSessionLogAfter(dir, "s", 1, func(e seqEvent) uint64 { return e.Seq }, parseSeqEvent)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(evs) != 2 || evs[0].Seq != 2 || evs[1].Seq != 3 {
+		t.Fatalf("after=1 期望 [2 3]，实得 %+v", evs)
+	}
+	if maxSeq != 3 {
+		t.Fatalf("maxSeq 期望 3，实得 %d", maxSeq)
+	}
+
+	// after=0 → 全量（seq 从 1 起，所以 0 等价于「没过滤」）。
+	evs, _, err = ReadSessionLogAfter(dir, "s", 0, func(e seqEvent) uint64 { return e.Seq }, parseSeqEvent)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(evs) != 3 {
+		t.Fatalf("after=0 期望 3 条，实得 %d", len(evs))
+	}
+}
+
+// TestReadSessionLogAfterMaxSeqCoversWholeFile 是这一组里最要紧的一条：
+// maxSeq 必须反映**整个文件**，不能只统计返回的那一页。
+//
+// 为什么：调用方用 `after > maxSeq` 判「客户端游标超前了（日志被重置 / 游标来自
+// 别的会话）」，超时时得以全量重建。若 maxSeq 只统计过滤结果，after=99 这类超前
+// 情形会得到 maxSeq=0，判据恒为真 —— 客户端会被永久判成「超前」，每次进会话都
+// 重拉全量，增量能力形同虚设。
+func TestReadSessionLogAfterMaxSeqCoversWholeFile(t *testing.T) {
+	dir := writeLog(t, "s", `{"seq":1,"text":"a"}`, `{"seq":7,"text":"b"}`)
+
+	// after 超前（99 > 7）：这一页是空的，但 maxSeq 仍须是 7。
+	evs, maxSeq, err := ReadSessionLogAfter(dir, "s", 99, func(e seqEvent) uint64 { return e.Seq }, parseSeqEvent)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(evs) != 0 {
+		t.Fatalf("after=99 期望空页，实得 %+v", evs)
+	}
+	if maxSeq != 7 {
+		t.Fatalf("超前时 maxSeq 仍须覆盖整个文件（期望 7，实得 %d）", maxSeq)
+	}
+	if !(99 > maxSeq) {
+		t.Fatalf("判据 `after > maxSeq` 应为 true（客户端超前），maxSeq=%d", maxSeq)
+	}
+
+	// 追平（after == maxSeq）：空页，且判据为 false（这是正常的「没有新事件」）。
+	evs, maxSeq, err = ReadSessionLogAfter(dir, "s", 7, func(e seqEvent) uint64 { return e.Seq }, parseSeqEvent)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(evs) != 0 {
+		t.Fatalf("已追平期望空页，实得 %+v", evs)
+	}
+	if 7 > maxSeq {
+		t.Fatalf("追平时不该判成超前（maxSeq=%d）", maxSeq)
+	}
+}
+
+// TestReadSessionLogAfterMissingFile 没历史不是错（新会话 / 从未落盘）。
+func TestReadSessionLogAfterMissingFile(t *testing.T) {
+	dir := t.TempDir()
+	evs, maxSeq, err := ReadSessionLogAfter(dir, "nope", 3, func(e seqEvent) uint64 { return e.Seq }, parseSeqEvent)
+	if err != nil {
+		t.Fatalf("文件不存在不该报错，实得 %v", err)
+	}
+	if evs != nil || maxSeq != 0 {
+		t.Fatalf("期望 (nil, 0)，实得 (%+v, %d)", evs, maxSeq)
+	}
+}
+
+// TestReadSessionLogAfterNilSeqOf 不给 seqOf 时退化成全量（且 maxSeq 恒 0）。
+//
+// 这两个参数是配套的：seqOf 为 nil 就没法过滤，after 无意义。
+func TestReadSessionLogAfterNilSeqOf(t *testing.T) {
+	dir := writeLog(t, "s", `{"seq":1,"text":"a"}`, `{"seq":2,"text":"b"}`)
+	evs, maxSeq, err := ReadSessionLogAfter(dir, "s", 5, nil, parseSeqEvent)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(evs) != 2 || maxSeq != 0 {
+		t.Fatalf("seqOf=nil 期望全量 2 条 + maxSeq=0，实得 %d 条 / maxSeq=%d", len(evs), maxSeq)
+	}
+}
+
+// TestReadSessionLogAfterSkipsCorruptLines 坏行不该让整次续读失败。
+func TestReadSessionLogAfterSkipsCorruptLines(t *testing.T) {
+	dir := writeLog(t, "s", `{"seq":1,"text":"a"}`, `{ this is not json`, `{"seq":3,"text":"c"}`)
+	evs, maxSeq, err := ReadSessionLogAfter(dir, "s", 1, func(e seqEvent) uint64 { return e.Seq }, parseSeqEvent)
+	if err != nil {
+		t.Fatalf("坏行不该报错，实得 %v", err)
+	}
+	if len(evs) != 1 || evs[0].Seq != 3 {
+		t.Fatalf("期望只回 seq=3，实得 %+v", evs)
+	}
+	if maxSeq != 3 {
+		t.Fatalf("maxSeq 期望 3（坏行跳过但正常行仍算），实得 %d", maxSeq)
+	}
+}
+
+// TestReadSessionLogAfterEmptyDirRejected 空 dir 必须报错。
+//
+// 这是防「默认进 home 写/读错路径」那类难追的 bug：调用方必须显式给目录。
+func TestReadSessionLogAfterEmptyDirRejected(t *testing.T) {
+	if _, _, err := ReadSessionLogAfter("", "s", 0, nil, parseSeqEvent); err == nil {
+		t.Fatal("空 dir 期望报错，实得 nil")
+	}
+}

package/npm/install.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+"use strict";
+
+// install.js - postinstall 两件事：
+//
+// 1) magic-agent 二进制兜底：
+//    1a) 当前平台已有预编译二进制 -> 直接通过（正常路径）
+//    1b) 没有但有 go -> 现场编译（首次 npm install 于非预打包平台时有用）
+//    1c) 都没有 -> 只告警，不让安装失败（用户仍可自行 go build）
+//
+// 2) llm 引擎依赖：安装 simonw/LLM CLI（https://github.com/simonw/LLM）
+//    探测顺序（找到就跳过安装）：
+//      MAGIC_AGENT_LLM_BIN > ~/.llm-venv/bin/llm > PATH(llm) > brew
+//    都没有时建 ~/.llm-venv（pipx 风格隔离，不污染系统 Python）：
+//      python3 -m venv ~/.llm-venv && ~/.llm-venv/bin/pip install llm
+//    安装失败只告警（-e llm 不可用，其他引擎不受影响）。
+
+const { execFileSync, execSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const { currentTarget, binaryPath, pkgRoot, findGo } = require("./lib/platform");
+
+// ── 1) magic-agent 二进制 ──────────────────────────────────────
+
+const target = currentTarget();
+const out = binaryPath(target);
+
+if (!fs.existsSync(out)) {
+  const go = findGo();
+  if (go) {
+    const pkg = require(path.join(pkgRoot, "package.json"));
+    process.stdout.write(`magic-agent: 当前平台 ${target.dir} 无预编译产物，尝试用 go 现场编译 ... `);
+    try {
+      execFileSync(
+        go,
+        ["build", "-trimpath", "-ldflags", `-s -w -X github.com/darren/magic-agent/internal/cli.Version=${pkg.version}`, "-o", out, "./cmd/magic-agent"],
+        {
+          cwd: pkgRoot,
+          stdio: ["ignore", "ignore", "pipe"],
+          env: { ...process.env, CGO_ENABLED: "0", GOOS: target.goos, GOARCH: target.goarch },
+        }
+      );
+      fs.chmodSync(out, 0o755);
+      console.log("ok");
+    } catch (err) {
+      console.log(`失败: ${err.message}`);
+    }
+  } else {
+    process.stderr.write(
+      `magic-agent: 警告 - 当前平台 ${target.dir} 缺少预编译二进制，且本机未找到 go，命令可能无法运行。\n`
+    );
+  }
+}
+
+// ── 2) llm CLI（simonw/LLM）────────────────────────────────────
+
+function haveLlm() {
+  if (process.env.MAGIC_AGENT_LLM_BIN) return process.env.MAGIC_AGENT_LLM_BIN;
+  const venv = path.join(os.homedir(), ".llm-venv", "bin", "llm");
+  if (fs.existsSync(venv)) return venv;
+  try {
+    return execFileSync("llm", ["--version"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim() && "llm";
+  } catch (_) {
+    /* PATH 里没有 */
+  }
+  return null;
+}
+
+function installLlm() {
+  const home = os.homedir();
+  const venvBin = path.join(home, ".llm-venv", "bin");
+
+  // 找一个能用的 python3（python3 > python；都不行时放弃）。
+  let py = null;
+  for (const c of ["python3", "python"]) {
+    try {
+      execFileSync(c, ["--version"], { stdio: ["ignore", "pipe", "ignore"] });
+      py = c;
+      break;
+    } catch (_) {
+      /* 下一个 */
+    }
+  }
+  if (!py) return "未找到可用的 python3";
+
+  try {
+    process.stdout.write("magic-agent: 安装 llm CLI (simonw/LLM) 到 ~/.llm-venv ... ");
+    const env = { ...process.env };
+    // Homebrew Python pip 可能因 PIP_BREAK_SYSTEM_PACKAGES / truststore 报错，
+    // venv 内不需要这些；静音升级提示。
+    delete env.PIP_BREAK_SYSTEM_PACKAGES;
+    execFileSync(py, ["-m", "venv", path.join(home, ".llm-venv")], { stdio: ["ignore", "ignore", "pipe"] });
+    execFileSync(
+      path.join(venvBin, "pip"),
+      ["install", "--quiet", "--disable-pip-version-check", "llm"],
+      { stdio: ["ignore", "ignore", "pipe"], env }
+    );
+    console.log("ok");
+    return null;
+  } catch (err) {
+    console.log(`失败: ${err.message.split("\n")[0]}`);
+    return err.message.split("\n")[0];
+  }
+}
+
+if (!haveLlm()) {
+  const why = installLlm();
+  if (why) {
+    process.stderr.write(
+      `magic-agent: 警告 - llm CLI 安装失败（${why}）。-e llm 引擎不可用；claude/codebuddy/trae 不受影响。\n` +
+        `手动安装：pip install llm  或  pipx install llm，然后用 MAGIC_AGENT_LLM_BIN 指向可执行文件。\n`
+    );
+  }
+} else {
+  // 已有 llm：静默通过（安装输出越少越好）。
+}
+
+// postinstall 永不阻断安装。
+process.exit(0);

package/npm/lib/platform.js

@@ -0,0 +1,78 @@
+"use strict";
+
+// platform.js - node 平台标识 -> Go 交叉编译目标 / 产物路径 的统一映射。
+//
+// 约定：dist/<goos>-<goarch>/magic-agent[.exe]
+//   darwin-arm64  darwin-x64  linux-arm64  linux-x64  win32-x64
+
+const path = require("path");
+
+// 构建目标表（顺序即 build.js 的输出顺序）。
+const TARGETS = [
+  { dir: "darwin-arm64", goos: "darwin", goarch: "arm64" },
+  { dir: "darwin-x64", goos: "darwin", goarch: "amd64" },
+  { dir: "linux-x64", goos: "linux", goarch: "amd64" },
+  { dir: "linux-arm64", goos: "linux", goarch: "arm64" },
+  { dir: "win32-x64", goos: "windows", goarch: "amd64" },
+];
+
+const GOOS_BY_NODE = { darwin: "darwin", linux: "linux", win32: "windows" };
+
+/** 当前进程对应的 Go 目标 */
+function currentTarget() {
+  return {
+    dir: `${process.platform}-${process.arch}`,
+    goos: GOOS_BY_NODE[process.platform],
+    goarch: process.arch === "x64" ? "amd64" : process.arch,
+  };
+}
+
+function exeName(goos) {
+  return goos === "windows" ? "magic-agent.exe" : "magic-agent";
+}
+
+/** 包根目录（npm/ 的上一级） */
+const pkgRoot = path.resolve(__dirname, "..", "..");
+
+/** 二进制输出目录 */
+const distDir = path.join(pkgRoot, "npm", "dist");
+
+/** 某个目标产物的绝对路径 */
+function binaryPath(target) {
+  return path.join(distDir, target.dir, exeName(target.goos));
+}
+
+/**
+ * 定位可用的 go 可执行文件。
+ * 顺序：MAGIC_AGENT_GO_BIN > PATH > homebrew > /usr/local/go > 常见版本目录。
+ */
+function findGo() {
+  const fs = require("fs");
+  const candidates = [];
+  if (process.env.MAGIC_AGENT_GO_BIN) candidates.push(process.env.MAGIC_AGENT_GO_BIN);
+  candidates.push("go");
+  candidates.push("/opt/homebrew/bin/go", "/usr/local/go/bin/go", "/usr/local/bin/go");
+  for (const c of candidates) {
+    try {
+      if (c === "go") {
+        const { execFileSync } = require("child_process");
+        execFileSync("go", ["version"], { stdio: "ignore" });
+        return "go";
+      }
+      if (fs.existsSync(c)) return c;
+    } catch (_) {
+      /* 继续找下一个 */
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  TARGETS,
+  currentTarget,
+  exeName,
+  pkgRoot,
+  distDir,
+  binaryPath,
+  findGo,
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "magic-agent",
+  "version": "1.0.0",
+  "description": "专业的 agent CLI 代理工具 - 统一 claude / codebuddy / trae / llm / codex / openclaw 引擎",
+  "license": "MIT",
+  "bin": {
+    "magic-agent": "npm/bin/magic-agent.js"
+  },
+  "scripts": {
+    "build": "node npm/build.js",
+    "build:current": "node npm/build.js --current",
+    "bump": "node npm/bump.js",
+    "prepack": "node npm/build.js",
+    "postinstall": "node npm/install.js"
+  },
+  "files": [
+    "npm/bin/",
+    "npm/lib/",
+    "npm/dist/",
+    "npm/install.js",
+    "cmd/",
+    "internal/",
+    "go.mod",
+    "go.sum",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ]
+}