agent-hub-runner 0.1.0 → 0.1.2

package/README.md

@@ -1,65 +1,84 @@
+<!-- @意图#R690(2026-11-01): 加「改动记录」一节：存在哪、打码、64 KB、30 天、怎么删 -->
+<!-- @意图#R666(2026-10-29): 改成不用全局安装的 npx 一条命令（码@地址）、Mac 开机自启、stop / uninstall、常见报错 -->
 <!-- @意图#R664(2026-10-29): npm 包 agent-hub-runner 的说明（随包发布）：给客户看的安装、配对、再连、查看、断开、卸载和安全提示 -->
 # agent-hub-runner
 
 agent-hub 的电脑运行器。装在你自己的电脑上，配对之后，你的 bot 就能在你给它选的文件夹里读、写、改文件，跑命令（跑命令每次都要你在网页上点批准）。
 
-- 没有第三方依赖，只用 Node 自带的功能。
-- 在终端前台运行，按 Ctrl-C 立刻断开；不会开机自启。
+- 没有第三方依赖，只用 Node 自带的功能。不用先装：用 `npx` 直接运行。
+- Mac 上可以设成开机自动连上（在后台跑，不用开终端）；不设的话在终端前台跑，按 Ctrl-C 断开。
 
 ## 需要
 
-- **Node 22 或更新**（`node -v` 看版本）。
-- **macOS**：给 bot 选目录时会在 Mac 上弹出系统的「选文件夹」窗口。别的系统目前弹不出这个窗口，选不了目录。
+- **Node 22 或更新**（终端里运行 `node -v` 看版本）。还没装：去 [nodejs.org](https://nodejs.org) 下载 LTS 版（Mac 选 .pkg 安装包），或者 `brew install node`。
+- **macOS**：给 bot 选目录时会在 Mac 上弹出系统的「选文件夹」窗口；开机自启也只支持 Mac。别的系统能连上，但选不了目录。
 - bot 跑命令时用 `bash`（macOS、Linux 自带）。
 
-## 安装
-
-```bash
-npm i -g agent-hub-runner
-```
-
-装过的跳过这一步。
-
 ## 第一次连接
 
-1. 在网页上打开某个 bot 的私聊，点输入框下面「我的电脑」那一行，右侧会打开抽屉，里面有配对码和一条命令。
+1. 在网页上打开某个 bot 的私聊，点输入框下面「我的电脑」那一行，右侧会打开抽屉，里面有一条命令。
 2. 复制那条命令到终端运行，形如：
 
    ```bash
-   agent-hub-runner pair <配对码> --start --server https://你的服务器地址
+   npx -y agent-hub-runner@latest pair <配对码>@你的服务器地址
    ```
 
-   配对码 5 分钟有效、只能用一次；过期了在抽屉里点「换一个码」。`--start` 表示配对成功后直接连上。
-3. 抽屉里第 2 步会自动打勾。第 3 步点「选择目录…」，在 Mac 弹出的窗口里选这个 bot 能用的文件夹。每个 bot 各选各的。
+   配对码 5 分钟有效、只能用一次；过期了在抽屉里点「换一个码」。配对成功后直接连上。
+3. Mac 上会问「开机自动连上？(Y/n)」：回车就是「是」，以后开机自己连上，终端可以关；选「否」的话终端窗口别关。
+4. 抽屉里第 2 步会自动打勾。第 3 步点「选择目录…」，在 Mac 弹出的窗口里选这个 bot 能用的文件夹。每个 bot 各选各的。
 
-终端窗口别关：关了 bot 就用不了你的电脑。
+`@` 后面的地址默认是 https；`localhost`、`127.x` 默认 http；也可以写全 `码@http://…`。老写法 `pair <配对码> --server <地址>` 照样能用。只配对不连：加 `--no-start`。
 
 ## 以后再连
 
-重启电脑或关了终端之后，运行：
+开了开机自启的不用管。没开的，重启电脑或关了终端之后运行：
 
 ```bash
-agent-hub-runner start
+npx -y agent-hub-runner@latest start
 ```
 
-服务器地址和令牌配对时已经存下了，不用再给。
+服务器地址和令牌配对时已经存下了，不用再给。后台已经连着时再 `start` 会说「已经在后台连着，不用再开」。
 
 ## 其他命令
 
 ```bash
-agent-hub-runner status   # 看连的是哪个服务器、每个 bot 选了哪个目录
-agent-hub-runner          # 看用法
+npx -y agent-hub-runner@latest status          # 版本、连的哪个服务器、在不在跑、开机自启、每个 bot 的目录
+npx -y agent-hub-runner@latest autostart on    # 开机自动连上（Mac）；升级到新版也用这条
+npx -y agent-hub-runner@latest autostart off   # 关掉开机自启
+npx -y agent-hub-runner@latest autostart status
+npx -y agent-hub-runner@latest stop            # 停掉在跑的运行器（开机自启的下次开机还会起）
+npx -y agent-hub-runner@latest uninstall       # 关掉开机自启、删掉复制的程序；会问要不要删配置
 ```
 
+开机自启时，程序复制到 `~/.agent-runner/bin/<版本>/`，日志在 `~/.agent-runner/logs/runner.log`（超过 5MB 自动清空）。网页上提示「有新版本」时，按提示运行那一条升级命令。
+
+仓库开发者（R699）：要让仓库里的源码 `runner/runner.mjs` 直接连测试服、开机自启，用 `agent-hub/scripts/runner-test.sh autostart on|off | start | stop | status | log`（launchd 服务 `com.agenthub.runner.src`，日志 `~/.agent-runner/logs/runner-src.log`，不复制程序，改了代码 `start` 一下就生效）。普通用户不用管这个。
+
 ## 配置文件
 
 - 默认在 `~/.agent-runner/config.json`（权限 600），里面有服务器地址、设备 id、长期令牌、电脑名和每个 bot 的目录。别发给别人。
 - 想放别处：设环境变量 `AGENT_RUNNER_CONFIG=/某个路径/config.json`。
+- 文件坏了：删掉它，回网页拿新配对码重新配对。
+
+## 常见问题
+
+- `command not found: npx`：还没装 Node。
+- 「需要 Node 22 或更新」（上面还有几行英文 `npm warn EBADENGINE`）：Node 太旧，装新的 LTS 版后关掉终端重开。
+- 「权限不够」/ `EACCES`：别用 sudo；运行 `sudo chown -R "$(whoami)" ~/.npm ~/.agent-runner` 修好再试。
+- 「找不到服务器」「连不上服务器」「超时」：检查网络；命令要整条原样复制。
+- 「配对码过期了 / 已经用过了 / 已经作废了」：网页上点「换一个码」再运行新命令。
+- 「这个账号已经连着一台电脑了」：一个账号同时只能连一台，先在网页抽屉「连着的电脑」里点「断开」。
 
 ## 断开、卸载
 
-- 在网页抽屉「连着的电脑」里点「断开」：令牌立刻作废，再连要重新配对。
-- 卸载：`npm rm -g agent-hub-runner`，再删掉 `~/.agent-runner/`。
+- 在网页抽屉「连着的电脑」里点「断开」：令牌立刻作废，再连要重新配对；开机自启也会自己关掉。
+- 卸载：`npx -y agent-hub-runner@latest uninstall`（加 `--purge` 连配置一起删，不再问）。
+
+## 改动记录（0.1.2 起）
+
+- bot 每次写文件、改文件，运行器在配置文件旁边的 `edits/` 文件夹（默认 `~/.agent-runner/edits/`，只有你能读）存一份改动记录，网页上点「已改文件 / 已写文件（自动允许）」那行灰字就能看到改了什么。内容只在你电脑上，服务器不存。
+- 存之前会把像密钥的字符串换成 `***`（`sk-…`、`ghp_…`、连接串里的密码、私钥、`XXX_KEY=…` 这类赋值）；每条最多 64 KB；只留 30 天，过期自动删。电脑不在线时网页上看不到。
+- 不想留：直接删掉 `edits/` 文件夹，不影响别的。
 
 ## 安全提示
 

package/autostart.mjs

@@ -0,0 +1,189 @@
+// @意图#R666(2026-10-29): Mac 开机自启（king 同意 R666 二丙）：配对后选「是」就写一个 launchd 的 LaunchAgent，之后登录 Mac 自动连上，不用开终端。
+// - 不靠 npx 缓存（路径不稳定、会被清）：把运行器自己（零依赖的几份源码 + package.json）复制到 ~/.agent-runner/bin/<版本>/，current 软链指向它；
+//   plist 里跑 [node 绝对路径（优先 /opt/homebrew/bin/node、/usr/local/bin/node 这种稳定软链）, ~/.agent-runner/bin/current/runner.mjs, start]，开机不联网也能起来，
+//   也不会每次登录自动拉 npm 上的新代码；升级 = 重新跑一次 npx -y agent-hub-runner@latest autostart on。
+// - Label com.agenthub.runner；用的不是默认配置（AGENT_RUNNER_CONFIG 指别处）时加配置路径 sha256 前 8 位后缀，一份配置一个后台任务；
+//   环境变量写明 AGENT_RUNNER_CONFIG 绝对路径、AGENT_RUNNER_LAUNCHD=1（运行器据此知道自己在后台），PATH 用开启时终端里的（bot 跑的命令要找得到 git、npm 这些）。
+// - RunAtLoad；KeepAlive 只在非 0 退出时拉起（被网页断开、令牌失效、被顶掉都是 0 退出，不会被反复拉起）；ThrottleInterval 10 秒；
+//   日志 ~/.agent-runner/logs/runner.log（非默认配置 runner-<后缀>.log），每次启动超过 5MB 就清空。
+// - launchctl 调用可以换成假的（测试用：参数里传，或环境变量 AGENT_RUNNER_LAUNCHCTL 指一个假程序），目录可以用 AGENT_RUNNER_HOME、AGENT_RUNNER_LAUNCH_AGENTS 换到临时目录。
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, truncateSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const LABEL = "com.agenthub.runner";
+export const LOG_MAX_BYTES = 5 * 1024 * 1024;
+export const THROTTLE_S = 10;
+/** 复制到 ~/.agent-runner/bin/<版本>/ 的文件（package.json 用来读版本号） */
+// @意图#R690(2026-11-01): 多复制 changes.mjs（runner.mjs 要 import 它，少了开机自启的副本起不来）
+export const COPY_FILES = ["runner.mjs", "ops.mjs", "edit.mjs", "changes.mjs", "autostart.mjs", "package.json"];
+/** 优先用的稳定 node 路径（Homebrew 升级 node 后这两个软链还在；nvm 的带版本号路径卸了就没了） */
+export const STABLE_NODES = ["/opt/homebrew/bin/node", "/usr/local/bin/node"];
+export const ONLY_MAC = "开机自启目前只支持 Mac";
+
+const real = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+
+/** 运行器自己的目录（配置、副本、日志都在这下面）；测试可用 AGENT_RUNNER_HOME 换掉 */
+export const runnerHome = (env = process.env) => env.AGENT_RUNNER_HOME || path.join(os.homedir(), ".agent-runner");
+export const defaultConfigFile = (env = process.env) => path.join(runnerHome(env), "config.json");
+export const launchAgentsDir = (env = process.env) => env.AGENT_RUNNER_LAUNCH_AGENTS || path.join(os.homedir(), "Library", "LaunchAgents");
+
+/** 默认配置没有后缀；别的配置用绝对路径 sha256 前 8 位 */
+export function configTag(configFile, env = process.env) {
+  const abs = path.resolve(configFile);
+  if (abs === path.resolve(defaultConfigFile(env))) return "";
+  return createHash("sha256").update(abs).digest("hex").slice(0, 8);
+}
+export const labelFor = (configFile, env = process.env) => { const t = configTag(configFile, env); return t ? `${LABEL}.${t}` : LABEL; };
+export const plistPathFor = (configFile, env = process.env) => path.join(launchAgentsDir(env), `${labelFor(configFile, env)}.plist`);
+export const logFileFor = (configFile, env = process.env) => {
+  const t = configTag(configFile, env);
+  return path.join(runnerHome(env), "logs", t ? `runner-${t}.log` : "runner.log");
+};
+
+/** node 的绝对路径：稳定软链和当前 node 是同一个文件就用软链，否则用当前的 */
+export function pickNode(execPath = process.execPath, candidates = STABLE_NODES) {
+  const me = real(execPath);
+  for (const c of candidates) if (existsSync(c) && real(c) === me) return c;
+  return execPath;
+}
+
+const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+/** 生成 LaunchAgent 的 plist（XML） */
+export function plistXml({ label, args, env, log }) {
+  const envXml = Object.entries(env).map(([k, v]) => `      <key>${esc(k)}</key>\n      <string>${esc(v)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${esc(label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${args.map((a) => `      <string>${esc(a)}</string>`).join("\n")}
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+${envXml}
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>${THROTTLE_S}</integer>
+    <key>StandardOutPath</key>
+    <string>${esc(log)}</string>
+    <key>StandardErrorPath</key>
+    <string>${esc(log)}</string>
+  </dict>
+</plist>
+`;
+}
+
+/** 把运行器复制到 <home>/bin/<版本>/，current 软链指过去（先建临时链再改名，换的那一下不会断）。返回 current/runner.mjs 的路径。 */
+export function installCopy({ srcDir, version, env = process.env }) {
+  const binRoot = path.join(runnerHome(env), "bin");
+  const dest = path.join(binRoot, version);
+  mkdirSync(dest, { recursive: true, mode: 0o700 });
+  if (real(srcDir) !== real(dest)) {
+    for (const f of COPY_FILES) {
+      const from = path.join(srcDir, f);
+      if (existsSync(from)) copyFileSync(from, path.join(dest, f));
+    }
+  }
+  const cur = path.join(binRoot, "current");
+  const tmp = path.join(binRoot, `.current-${process.pid}`);
+  rmSync(tmp, { force: true });
+  symlinkSync(version, tmp);
+  renameSync(tmp, cur);
+  return path.join(cur, "runner.mjs");
+}
+
+/** 默认的 launchctl：返回 { code, stdout, stderr }，不抛错。AGENT_RUNNER_LAUNCHCTL 可换成别的程序（测试用假的，不真加载） */
+export function runLaunchctl(args, env = process.env) {
+  return new Promise((resolve) => {
+    execFile(env.AGENT_RUNNER_LAUNCHCTL || "launchctl", args, { encoding: "utf8" }, (err, stdout, stderr) => resolve({ code: err ? (typeof err.code === "number" ? err.code : 1) : 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") }));
+  });
+}
+const uid = () => (typeof process.getuid === "function" ? process.getuid() : 0);
+
+/**
+ * 开启开机自启：复制自己、写 plist、（先卸掉旧的）再加载。加载后 launchd 马上起一个后台运行器（RunAtLoad）。
+ * 返回 { label, plist, script, node, log }。
+ */
+export async function autostartOn({ configFile, version, srcDir, execPath = process.execPath, env = process.env, launchctl, platform = process.platform }) {
+  launchctl ??= (a) => runLaunchctl(a, env);
+  if (platform !== "darwin") throw new Error(ONLY_MAC);
+  const cfg = path.resolve(configFile);
+  if (!existsSync(cfg)) throw new Error(`还没配对：没有 ${cfg}，配对成功后才能设开机自启`);
+  const script = installCopy({ srcDir, version, env });
+  const node = pickNode(execPath);
+  const label = labelFor(cfg, env);
+  const log = logFileFor(cfg, env);
+  mkdirSync(path.dirname(log), { recursive: true, mode: 0o700 });
+  const vars = { AGENT_RUNNER_CONFIG: cfg, AGENT_RUNNER_LAUNCHD: "1", PATH: env.PATH || "/usr/bin:/bin:/usr/sbin:/sbin", LANG: env.LANG || "en_US.UTF-8" };
+  if (env.AGENT_RUNNER_HOME) vars.AGENT_RUNNER_HOME = env.AGENT_RUNNER_HOME;
+  const plist = plistPathFor(cfg, env);
+  mkdirSync(path.dirname(plist), { recursive: true });
+  writeFileSync(plist, plistXml({ label, args: [node, script, "start"], env: vars, log }), { mode: 0o644 });
+  await launchctl(["bootout", `gui/${uid()}/${label}`]); // 以前加载过（升级）：先卸掉，没有也不要紧
+  const r = await launchctl(["bootstrap", `gui/${uid()}`, plist]);
+  if (r.code !== 0) throw new Error(`开机自启没设成：launchctl bootstrap 失败（${(r.stderr || r.stdout).trim() || r.code}）`);
+  return { label, plist, script, node, log };
+}
+
+/** 关掉开机自启：卸载任务（后台那个会被停掉）、删 plist。返回 { wasOn }（原来有没有 plist）。 */
+export async function autostartOff({ configFile, env = process.env, launchctl }) {
+  launchctl ??= (a) => runLaunchctl(a, env);
+  const cfg = path.resolve(configFile);
+  const plist = plistPathFor(cfg, env);
+  const wasOn = existsSync(plist);
+  rmSync(plist, { force: true });
+  await launchctl(["bootout", `gui/${uid()}/${labelFor(cfg, env)}`]);
+  return { wasOn };
+}
+
+/** 开机自启现在的样子：装没装（有没有 plist）、加载没有、后台进程号；plist 里的 node / 脚本找不到就写进 problems */
+export async function autostartStatus({ configFile, env = process.env, launchctl, platform = process.platform }) {
+  launchctl ??= (a) => runLaunchctl(a, env);
+  const cfg = path.resolve(configFile);
+  const label = labelFor(cfg, env);
+  const plist = plistPathFor(cfg, env);
+  const out = { supported: platform === "darwin", installed: existsSync(plist), loaded: false, pid: null, label, plist, log: logFileFor(cfg, env), problems: [] };
+  if (!out.supported) return out;
+  if (out.installed) {
+    const xml = readFileSync(plist, "utf8");
+    const args = [...(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml)?.[1] ?? "").matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1].replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&amp;/g, "&"));
+    if (args[0] && !existsSync(args[0])) out.problems.push(`找不到 node：${args[0]}（换过 Node 的装法？重新运行 autostart on）`);
+    if (args[1] && !existsSync(args[1])) out.problems.push(`找不到运行器副本：${args[1]}（重新运行 autostart on）`);
+  }
+  const r = await launchctl(["print", `gui/${uid()}/${label}`]);
+  if (r.code === 0) {
+    out.loaded = true;
+    const m = /\bpid = (\d+)/.exec(r.stdout);
+    if (m) out.pid = Number(m[1]);
+  }
+  return out;
+}
+
+/** 还有没有别的配置开着自启（uninstall 时决定删不删共用的 bin 副本） */
+export function otherAutostarts(configFile, env = process.env) {
+  const mine = `${labelFor(configFile, env)}.plist`;
+  try { return readdirSync(launchAgentsDir(env)).filter((f) => f.startsWith(LABEL) && f.endsWith(".plist") && f !== mine); } catch { return []; }
+}
+
+/** 日志超过 max 字节就清空（launchd 用追加方式打开，清空后接着往后写不会乱）。清了返回 true。 */
+export function truncateLogIfBig(file, max = LOG_MAX_BYTES) {
+  try {
+    if (statSync(file).size <= max) return false;
+    truncateSync(file, 0);
+    return true;
+  } catch { return false; }
+}

package/bin/agent-hub-runner.mjs

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 // @意图#R664(2026-10-29): npm 包 agent-hub-runner 的命令入口（package.json 的 bin）：客户电脑 npm i -g agent-hub-runner 后直接跑
 // agent-hub-runner pair <配对码> --start --server <地址> / start / status；逻辑全在 ../runner.mjs，这里只把参数和命令名交过去。
-import { main, progName } from "../runner.mjs";
-
-main(process.argv.slice(2), progName()).catch((e) => { console.error(e?.message ?? String(e)); process.exit(1); });
+// @意图#R666(2026-10-29): 主要用法改成 npx -y agent-hub-runner@latest pair 码@地址；最先查 Node 版本（在加载别的代码之前，老 Node 上也只打一句大白话，
+// 说明上面 npm 的英文 EBADENGINE 警告不用管）；出错用 explainError 打大白话（权限不够单独说）
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 22 || typeof WebSocket === "undefined") {
+  console.error(`需要 Node 22 或更新，你这台电脑上是 ${process.versions.node}。\n（上面如果有几行英文 npm warn EBADENGINE，说的就是这个，不用管它。）\n去 https://nodejs.org 下载 LTS 版装上（Mac 选 .pkg 安装包），装好后关掉终端重新打开，再运行同一条命令。`);
+  process.exit(1);
+}
+const { main, progName, explainError } = await import("../runner.mjs");
+main(process.argv.slice(2), progName()).catch((e) => { console.error(explainError(e)); process.exit(1); });

package/changes.mjs

@@ -0,0 +1,195 @@
+// @意图#R690(2026-11-01): 私聊里「已改文件 / 已写文件（自动允许）」点开看改动（king 同意 R690）：改动内容只存在你电脑上（运行器配置旁边的 edits/<auto_id>.json，权限 600），
+// 服务器库里只记 id。改文件存按行对比（带改前、改后行号和前后 3 行，网页左右对照用），写文件存写进去的内容；存之前先打码（和服务器 redactSecrets 同一套规则，
+// 共用测试样例 test/fixtures/redact-cases.json）；每条最多 64 KB（超出截断并标记）；只留 30 天（启动时和每次存时顺手清，最多一小时一次）。存失败只记日志，不影响写改本身。
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const CHANGE_ID_RE = /^auto-[0-9a-f]{32}$/;
+export const MAX_RECORD_BYTES = 64 * 1024;
+export const KEEP_MS = 30 * 24 * 60 * 60_000;
+export const CLEAN_EVERY_MS = 60 * 60_000;
+export const CONTEXT_LINES = 3;
+/** 中间改动部分（去掉首尾相同的行后）行数乘积超过这个就不细算，整块当作删了再加 */
+export const MAX_DIFF_CELLS = 4_000_000;
+
+/** 改动记录放在配置文件旁边的 edits/ 里（跟着 AGENT_RUNNER_CONFIG 走，dev 和正式配置各管各的文件，名字是 auto_id 不会撞）。 */
+// @意图#R690(2026-11-01): king 定甲：放配置旁边
+export const changesDirFor = (configFile) => path.join(path.dirname(configFile), "edits");
+
+// 变量名以 KEY / TOKEN / SECRET / PASSWORD / PASSWD 结尾（API_KEY、db.password、apiKey、token 都算；monkey、tokens 不算）
+const NAME = String.raw`(?:(?:[A-Za-z0-9]+[_.-])*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|key|token|secret|password|passwd|Key|Token|Secret|Password)|[a-z][A-Za-z0-9]*(?:Key|Token|Secret|Password))`;
+const QUOTED_ASSIGN = new RegExp(String.raw`(^|[^\w.-])(["']?)(${NAME})\2([ \t]*[=:][ \t]*)(["'])([^"'\r\n]+)\5`, "gm");
+const LINE_ASSIGN = new RegExp(String.raw`^([ \t]*(?:export[ \t]+)?)(${NAME})([ \t]*[=:][ \t]*)([^\s"'#][^\s#]*)`, "gm");
+
+/**
+ * 打码（和服务器 server/src/model-keys.ts 的 redactSecrets 规则一字不差，样例见 test/fixtures/redact-cases.json）：
+ * sk- / ghp_ 开头的串、连接串里的密码、私钥块（BEGIN/END 两行留着，中间每行换成 ***，行数不变）、
+ * 变量名像密钥的赋值（带引号的值任何位置都打；不带引号的只认行首的 .env / yaml 写法）。
+ */
+// @意图#R690(2026-11-01): king 定乙：服务器三条规则 + 私钥块 + .env 式 XXX_KEY / TOKEN / SECRET / PASSWORD = 值；打码不改变行数（行号对得上）
+export function redactSecrets(text) {
+  let s = String(text);
+  s = s.replace(/(-----BEGIN [A-Z0-9 ]*-----)([\s\S]*?)(-----END [A-Z0-9 ]*-----)/g, (_m, a, body, b) => a + body.replace(/[^\r\n]+/g, "***") + b);
+  s = s.replace(/(-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----)((?:(?!-----END )[\s\S])*)$/, (_m, a, body) => a + body.replace(/[^\r\n]+/g, "***")); // 截断了没有 END 的私钥块
+  s = s.replace(/(?<![A-Za-z0-9])sk-[A-Za-z0-9_-]+/g, "sk-***").replace(/(?<![A-Za-z0-9])ghp_[A-Za-z0-9_]+/g, "ghp_***")
+    .replace(/([a-z][a-z0-9+.-]*:\/\/[^\s:/@]+):[^\s@/]+@/gi, "$1:***@");
+  s = s.replace(QUOTED_ASSIGN, (m, pre, q1, name, eq, q2, val) => (val === "***" ? m : `${pre}${q1}${name}${q1}${eq}${q2}***${q2}`));
+  s = s.replace(LINE_ASSIGN, "$1$2$3***");
+  return s;
+}
+
+/** 按行拆（去 BOM、换行统一成 LF；末尾换行不算多一行）。 */
+export function splitLines(text) {
+  let t = String(text);
+  if (t.startsWith("\uFEFF")) t = t.slice(1);
+  t = t.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (t === "") return [];
+  const a = t.split("\n");
+  if (a[a.length - 1] === "") a.pop();
+  return a;
+}
+
+/** 逐行对比：返回每一行 {t:" "|"-"|"+", o:改前行号|null, n:改后行号|null, s:内容}；连着的一段改动里先删后加。 */
+// @意图#R690(2026-11-01): 带两边行号，网页既能画左右对照也能画红绿一栏
+export function diffLines(a, b) {
+  let p = 0;
+  while (p < a.length && p < b.length && a[p] === b[p]) p++;
+  let q = 0;
+  while (q < a.length - p && q < b.length - p && a[a.length - 1 - q] === b[b.length - 1 - q]) q++;
+  const A = a.slice(p, a.length - q), B = b.slice(p, b.length - q);
+  const mid = []; // " " / "-" / "+" 序列
+  if (A.length && B.length && A.length * B.length <= MAX_DIFF_CELLS) {
+    const n = A.length, m = B.length, w = m + 1;
+    const dp = new Uint32Array((n + 1) * w);
+    for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) {
+      dp[i * w + j] = A[i] === B[j] ? dp[(i + 1) * w + j + 1] + 1 : Math.max(dp[(i + 1) * w + j], dp[i * w + j + 1]);
+    }
+    let i = 0, j = 0;
+    while (i < n || j < m) {
+      if (i < n && j < m && A[i] === B[j]) { mid.push(" "); i++; j++; }
+      else if (j >= m || (i < n && dp[(i + 1) * w + j] >= dp[i * w + j + 1])) { mid.push("-"); i++; }
+      else { mid.push("+"); j++; }
+    }
+  } else {
+    for (let i = 0; i < A.length; i++) mid.push("-");
+    for (let j = 0; j < B.length; j++) mid.push("+");
+  }
+  // 连着的改动里先删后加
+  const tags = [];
+  for (let k = 0; k < mid.length;) {
+    if (mid[k] === " ") { tags.push(" "); k++; continue; }
+    let d = 0, ad = 0;
+    while (k < mid.length && mid[k] !== " ") { if (mid[k] === "-") d++; else ad++; k++; }
+    for (let x = 0; x < d; x++) tags.push("-");
+    for (let x = 0; x < ad; x++) tags.push("+");
+  }
+  const out = [];
+  let o = 0, nn = 0;
+  for (let k = 0; k < p; k++) { out.push({ t: " ", o: o + 1, n: nn + 1, s: a[o] }); o++; nn++; }
+  for (const t of tags) {
+    if (t === " ") { out.push({ t, o: o + 1, n: nn + 1, s: a[o] }); o++; nn++; }
+    else if (t === "-") { out.push({ t, o: o + 1, n: null, s: a[o] }); o++; }
+    else { out.push({ t, o: null, n: nn + 1, s: b[nn] }); nn++; }
+  }
+  for (let k = 0; k < q; k++) { out.push({ t: " ", o: o + 1, n: nn + 1, s: a[o] }); o++; nn++; }
+  return out;
+}
+
+/** 把逐行对比切成几处改动，每处前后带 ctx 行没变的；两处之间没变的不超过 2×ctx 行就并成一处。 */
+export function hunksOf(rows, ctx = CONTEXT_LINES) {
+  const idx = [];
+  rows.forEach((r, i) => { if (r.t !== " ") idx.push(i); });
+  const hunks = [];
+  let k = 0;
+  while (k < idx.length) {
+    let start = idx[k], end = idx[k];
+    while (k + 1 < idx.length && idx[k + 1] - end - 1 <= 2 * ctx) { k++; end = idx[k]; }
+    k++;
+    const from = Math.max(0, start - ctx), to = Math.min(rows.length, end + ctx + 1);
+    const lines = rows.slice(from, to);
+    let oStart = 1, nStart = 1;
+    for (let i = 0; i < from; i++) { if (rows[i].t !== "+") oStart++; if (rows[i].t !== "-") nStart++; }
+    hunks.push({ old_start: oStart, new_start: nStart, lines });
+  }
+  return hunks;
+}
+
+const jsonBytes = (v) => Buffer.byteLength(JSON.stringify(v), "utf8") + 1; // 存进去占的字节（加逗号）
+
+/**
+ * 生成一条改动记录（存之前先打码、截到 64 KB）。
+ * edit：{ v, id, tool, path, at, hunks, added, removed, truncated }；write：{ v, id, tool, path, at, lines, total_lines, chars, truncated }
+ */
+// @意图#R690(2026-11-01): 改文件存红绿对比（king 定），写文件只存写进去的内容、不存旧文件（king 定乙）；每条最多 64 KB（king 定甲）
+export function buildChangeRecord({ id, tool, path: p, before, after, content, at = new Date().toISOString() }) {
+  const budget = MAX_RECORD_BYTES - 1024;
+  const head = { v: 1, id, tool, path: String(p ?? ""), at };
+  if (tool === "write") {
+    const text = String(content ?? "");
+    const all = splitLines(redactSecrets(text));
+    const lines = [];
+    let used = 0, truncated = false;
+    for (const l of all) {
+      const b = jsonBytes(l);
+      if (used + b > budget) { truncated = true; break; }
+      lines.push(l); used += b;
+    }
+    return { ...head, lines, total_lines: all.length, chars: text.length, truncated };
+  }
+  const rows = diffLines(splitLines(redactSecrets(before ?? "")), splitLines(redactSecrets(after ?? "")));
+  let added = 0, removed = 0;
+  for (const r of rows) { if (r.t === "+") added++; else if (r.t === "-") removed++; }
+  const hunks = [];
+  let used = 0, truncated = false;
+  for (const h of hunksOf(rows)) {
+    used += jsonBytes({ old_start: h.old_start, new_start: h.new_start, lines: [] });
+    const keep = [];
+    for (const l of h.lines) {
+      const b = jsonBytes(l);
+      if (used + b > budget) { truncated = true; break; }
+      keep.push(l); used += b;
+    }
+    if (keep.length) hunks.push({ ...h, lines: keep });
+    if (truncated) break;
+  }
+  return { ...head, hunks, added, removed, truncated };
+}
+
+/** 改动记录的存取和清理（目录用到时才建，700；文件 600）。 */
+// @意图#R690(2026-11-01): 只留 30 天（king 定甲）：启动时清一次，每次存时顺手清（最多一小时一次），按文件修改时间算
+export function createChangeStore(dir, { now = Date.now, log = () => {} } = {}) {
+  let lastClean = 0;
+  const fileOf = (id) => path.join(dir, `${id}.json`);
+  async function clean(force = false) {
+    if (!force && now() - lastClean < CLEAN_EVERY_MS) return 0;
+    lastClean = now();
+    let names;
+    try { names = await fs.readdir(dir); } catch { return 0; }
+    let removed = 0;
+    for (const f of names) {
+      if (!/^auto-[0-9a-f]{32}\.json$/.test(f)) continue;
+      try {
+        const st = await fs.stat(path.join(dir, f));
+        if (now() - st.mtimeMs > KEEP_MS) { await fs.unlink(path.join(dir, f)); removed++; }
+      } catch { /* 别的进程删了 */ }
+    }
+    return removed;
+  }
+  return {
+    dir,
+    clean,
+    async save(id, record) {
+      if (!CHANGE_ID_RE.test(String(id))) throw new Error("改动记录 id 不对");
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+      const f = fileOf(id);
+      await fs.writeFile(f, JSON.stringify(record), { mode: 0o600 });
+      await fs.chmod(f, 0o600);
+      await clean().catch((e) => log(`清理旧改动记录失败：${e?.message ?? e}`));
+    },
+    /** 找不到（没存、已清理、id 不对）返回 null */
+    async get(id) {
+      if (!CHANGE_ID_RE.test(String(id))) return null;
+      try { return JSON.parse(await fs.readFile(fileOf(id), "utf8")); } catch { return null; }
+    },
+  };
+}

package/ops.mjs

@@ -77,24 +77,28 @@ export async function opRead(args, root) {
 }
 
 /** write：建好上级目录再整份写入。 */
+// @意图#R690(2026-11-01): 写成功后交给 onChange 存一份改动记录（写进去的内容），存记录的事不影响写本身
 // @意图#R636(2026-10-27): 写文件（已经过批准，只执行这一次）
-export async function opWrite(args, root) {
+export async function opWrite(args, root, { onChange } = {}) {
   if (typeof args.content !== "string") throw new Error("content 必须是文字");
   const real = await resolveInside(args.path, root);
   await fs.mkdir(path.dirname(real), { recursive: true });
   await fs.writeFile(real, args.content, "utf8");
+  await onChange?.({ tool: "write", path: args.path, content: args.content });
   return { bytes: Buffer.byteLength(args.content, "utf8") };
 }
 
 /** edit：和 pi 原版同样的精确替换。 */
+// @意图#R690(2026-11-01): 写回成功后把改前（读到的原文）、改后（写回的内容）交给 onChange 算对比、存记录：同一个函数里拿到的两份，不会和别的改动串
 // @意图#R636(2026-10-27): 改文件（已经过批准，只执行这一次）
-export async function opEdit(args, root) {
+export async function opEdit(args, root, { onChange } = {}) {
   if (!Array.isArray(args.edits) || args.edits.length === 0) throw new Error("Edit tool input is invalid. edits must contain at least one replacement.");
   const real = await resolveInside(args.path, root);
   let raw;
   try { raw = await fs.readFile(real, "utf8"); } catch (e) { throw new Error(`Could not edit file: ${args.path}. Error code: ${e?.code ?? "unknown"}.`); }
   const next = editText(raw, args.edits, args.path);
   await fs.writeFile(real, next, "utf8");
+  await onChange?.({ tool: "edit", path: args.path, before: raw, after: next });
   return { replaced: args.edits.length };
 }
 
@@ -141,12 +145,13 @@ export function opBash(args, root, { onData, signal } = {}) {
 }
 
 /** 按 op 分派；未知 op 拒绝。 */
+// @意图#R690(2026-11-01): write、edit 也收 extra（onChange 存改动记录）
 // @意图#R636(2026-10-27): 协议里只有这四种工具调用
 export function runOp(op, args, root, extra) {
   const a = args && typeof args === "object" ? args : {};
   if (op === "read") return opRead(a, root);
-  if (op === "write") return opWrite(a, root);
-  if (op === "edit") return opEdit(a, root);
+  if (op === "write") return opWrite(a, root, extra);
+  if (op === "edit") return opEdit(a, root, extra);
   if (op === "bash") return opBash(a, root, extra);
   return Promise.reject(new Error(`未知操作 ${op}`));
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agent-hub-runner",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "agent-hub 的电脑运行器：配对后让你的 bot 在这台电脑上读写授权目录里的文件、跑命令（跑命令要你在网页上批准）",
   "type": "module",
   "bin": { "agent-hub-runner": "bin/agent-hub-runner.mjs" },
-  "files": ["runner.mjs", "ops.mjs", "edit.mjs", "bin/agent-hub-runner.mjs", "README.md"],
+  "files": ["runner.mjs", "ops.mjs", "edit.mjs", "changes.mjs", "autostart.mjs", "bin/agent-hub-runner.mjs", "README.md"],
   "engines": { "node": ">=22" },
   "scripts": { "test": "node --test" }
 }

package/runner.mjs

@@ -1,36 +1,53 @@
 #!/usr/bin/env node
 // @意图#R636(2026-10-27): 你电脑上的运行器（第一轮最小可用，king 定甲）：零第三方依赖，只用 Node 22+ 自带的 WebSocket、fetch、进程和文件 API。
 // 用法：
-//   node agent-hub/runner/runner.mjs pair <配对码> [--start] [--server http://127.0.0.1:3220]
-//   node agent-hub/runner/runner.mjs start
+//   npx -y agent-hub-runner@latest pair <配对码>@<服务器地址>     （R666：抽屉里就这一条；配完直接连上）
+//   node agent-hub/runner/runner.mjs pair <配对码> [--no-start] [--server http://127.0.0.1:3220]
+//   node agent-hub/runner/runner.mjs start | stop | status | autostart on|off|status | uninstall
+// @意图#R666(2026-10-29): 更傻瓜（king 同意 R666）：抽屉只给一条 npx 命令、配对码后面带服务器（码@域名）、pair 默认配完直接 start（--no-start 只配对）；
+//   Mac 上配对后问要不要开机自启（launchd，见 autostart.mjs）；报错一律大白话（Node 版本、连不上的各种原因、配对码不对/用过/过期、已有电脑、权限不够、配置坏了）；
+//   同一份配置只能跑一个（配置旁边 <配置>.lock 记进程号）；被服务器 4409 顶掉不再重连；4401/4403/顶掉都正常退出（0）并关掉自启；
+//   hello 报自己的版本和是不是开机自启，网页据此提示「有新版本」。
 // @意图#R664(2026-10-29): 运行器做成客户电脑 npm 安装的小工具（包名、命令名都是 agent-hub-runner，入口 bin/agent-hub-runner.mjs）：
 //   npm i -g agent-hub-runner → agent-hub-runner pair <配对码> --start --server <地址>；以后 agent-hub-runner start。仓库里 node 直接跑照旧。
 // @意图#R663(2026-10-29): pair 加 --start（二甲）：配对成功后直接接着 start 连上，网页上只给一条命令；不带 --start 的老用法不变
 // @意图#R640(2026-10-27): 一台电脑一个运行器，但每个 bot 有自己的授权目录（bot→目录 对照表 bot_dirs），互相碰不到；king 定乙：没有默认目录，
-// 每个 bot 都要在它的私聊右栏「我的电脑」里点「选择目录」，运行器在本机弹窗选。服务器只报 bot_id，定不了路径。pair 不再收 --dir。
+// 每个 bot 都要在它的私聊里「我的电脑」（R663 起是输入框下面那一行，原来是右栏）点「选择目录」，运行器在本机弹窗选。服务器只报 bot_id，定不了路径。pair 不再收 --dir。
 // @意图#R639(2026-10-27): 配对不再选目录（king 定乙，替换 R637 配对时弹窗）；start 连上后在网页「我的电脑」点「选择目录」，
 // 服务器经这条 WebSocket 叫运行器在 Mac 上弹系统选文件夹窗口，选完马上生效并写回配置文件。
 // 配对后长期令牌和授权目录存在 ~/.agent-runner/config.json（权限 600）；目录只能由你在本机窗口里选，服务器只能叫你弹窗、定不了目录。
 // （R639 时目录是一台电脑一个、配对时还能 --dir；R640 起换成每个 bot 一个，老配置里的单一 dir 读到直接忽略。）
-// start 在终端前台运行，主动用 WebSocket 连服务器；按 Ctrl-C 立刻断开。没有开机自启、没有 npx 安装包、没有沙箱。
-import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+// start 在终端前台运行，主动用 WebSocket 连服务器；按 Ctrl-C 立刻断开。没有沙箱。（R666 起有开机自启、npx 用法。）
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import readline from "node:readline/promises";
 import { execFile } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { runOp } from "./ops.mjs";
+import { buildChangeRecord, changesDirFor, CHANGE_ID_RE, createChangeStore } from "./changes.mjs";
+import { autostartOff, autostartOn, autostartStatus, logFileFor, ONLY_MAC, otherAutostarts, runnerHome, truncateLogIfBig } from "./autostart.mjs";
 
 export const PROTOCOL_VERSION = 1;
 /** npm 包名，也是装好后的命令名 */
 export const PKG_BIN = "agent-hub-runner";
+/** R666：抽屉里给的、npx 运行时提示里写的命令前缀（@latest：每次都用最新版，也不会被电脑上旧的全局安装盖掉） */
+export const NPX_CMD = `npx -y ${PKG_BIN}@latest`;
+/** R666：自己的版本号（读同目录的 package.json；开机自启的副本也带着它），hello 时报给服务器 */
+export const RUNNER_VERSION = (() => { try { return String(JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version); } catch { return "0.0.0"; } })();
+/** R666：配对请求、连接超时（秒） */
+export const PAIR_TIMEOUT_MS = 15_000;
 export const HEARTBEAT_MS = 10_000;
 export const DEFAULT_SERVER = "http://127.0.0.1:3220";
 /** 服务器用这两个关闭码表示令牌不对 / 已在网页上断开：不再重连。 */
 export const CLOSE_BAD_TOKEN = 4401;
 export const CLOSE_REVOKED = 4403;
+/** R666：同一台电脑又连上来一个（同一份配置开了两个运行器），服务器把旧的这条用 4409 断开：不再重连 */
+export const CLOSE_REPLACED = 4409;
 
-export const configPath = () => process.env.AGENT_RUNNER_CONFIG || path.join(os.homedir(), ".agent-runner", "config.json");
+// @意图#R666(2026-10-29): 默认目录可用 AGENT_RUNNER_HOME 换（测试、开机自启的副本用）；不设时和原来一样是 ~/.agent-runner/config.json
+export const configPath = () => process.env.AGENT_RUNNER_CONFIG || path.join(runnerHome(), "config.json");
 
 const stamp = () => new Date().toLocaleTimeString("zh-CN", { hour12: false });
 const say = (s) => console.log(`[${stamp()}] ${s}`);
@@ -41,36 +58,49 @@ export function saveConfig(cfg, file = configPath()) {
   writeFileSync(file, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 });
   chmodSync(file, 0o600);
 }
+// @意图#R666(2026-10-29): 提示改成现在网页上的位置（输入框下面「我的电脑」那一行），不再说「连接电脑」；配置文件坏了说清楚怎么办
 export function loadConfig(file = configPath()) {
-  if (!existsSync(file)) throw new Error(`还没配对：没有 ${file}。先在网页「我的电脑」里点「连接电脑」拿配对码，再运行 pair。`);
-  return JSON.parse(readFileSync(file, "utf8"));
+  if (!existsSync(file)) throw new Error(`还没配对：没有 ${file}。先在网页上 bot 的私聊里点输入框下面「我的电脑」那一行，复制里面的命令运行。`);
+  const text = readFileSync(file, "utf8");
+  try { return JSON.parse(text); }
+  catch { throw new Error(`配置文件坏了：${file}。删掉它（rm "${file}"），再回网页拿新配对码重新配对。`); }
 }
 
+// @意图#R666(2026-10-29): pair 默认配完直接 start：--start 照样认（老命令），--no-start 只配对；--autostart / --no-autostart 跳过「开机自动连上？」的提问；
+// uninstall --purge 连配置一起删；--version / -v 打版本
 // @意图#R663(2026-10-29): 认 --start（只对 pair 有意义，不带值）
 export function parseArgs(argv) {
   const [cmd, ...rest] = argv;
-  const out = { cmd, positional: [] };
+  const out = { cmd: cmd === "--version" || cmd === "-v" ? "version" : cmd === "--help" || cmd === "-h" ? "help" : cmd, positional: [] };
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--dir") out.dir = rest[++i];
     else if (a === "--server") out.server = rest[++i];
     else if (a === "--name") out.name = rest[++i];
     else if (a === "--start") out.start = true;
+    else if (a === "--no-start") out.start = false;
+    else if (a === "--autostart") out.autostart = true;
+    else if (a === "--no-autostart") out.autostart = false;
+    else if (a === "--purge") out.purge = true;
     else if (a.startsWith("--")) throw new Error(`不认识的参数 ${a}`);
     else out.positional.push(a);
   }
   return out;
 }
 
+/** R666：Node 太低时的大白话（bin 入口在加载别的代码之前也用同样的话） */
+export const nodeTooOld = (v) => `需要 Node 22 或更新，你这台电脑上是 ${v}。\n（上面如果有几行英文 npm warn EBADENGINE，说的就是这个，不用管它。）\n去 https://nodejs.org 下载 LTS 版装上（Mac 选 .pkg 安装包），装好后关掉终端重新打开，再运行同一条命令。`;
+// @意图#R666(2026-10-29): 版本太低的提示改成大白话（怎么装、英文警告不用管）
 function checkNode() {
   const major = Number(process.versions.node.split(".")[0]);
-  if (major < 22 || typeof WebSocket === "undefined") throw new Error(`需要 Node 22 或更新（现在是 ${process.versions.node}）`);
+  if (major < 22 || typeof WebSocket === "undefined") throw new Error(nodeTooOld(process.versions.node));
 }
 
 export const PICK_PROMPT = "选择要授权给 bot 的文件夹";
 export const PICK_SCRIPT = `POSIX path of (choose folder with prompt "${PICK_PROMPT}")`;
 /** R640：这个 bot 在对照表里没有目录时，调用一律回这句。 */
-export const NO_DIR = "还没给这个 bot 选目录，请在这个 bot 的私聊右栏「我的电脑」里点「选择目录」";
+// @意图#R666(2026-10-29): 「右栏」是 R663 以前的位置，改成输入框下面「我的电脑」那一行（和服务器 devices.ts 的 NO_DIR 一字不差）
+export const NO_DIR = "还没给这个 bot 选目录，请在这个 bot 的私聊里点输入框下面「我的电脑」那一行，再点「选择目录」";
 export const PICK_ONLY_MAC = "只支持 Mac：选目录的窗口只在 Mac 上弹";
 /** R640：pair 带了 --dir 时的提示（不报错，照常配对，目录不用）。 */
 export const PAIR_DIR_IGNORED = "目录请连上后在每个 bot 的私聊里选（--dir 已不用，这次没用它）";
@@ -121,17 +151,99 @@ export async function checkDir(dir) {
 // @意图#R639(2026-10-27已废弃): 配对不弹窗、不要求目录（king 定乙）；--dir 还能用，给了就照旧检查；没给 config.dir 为空（R640 去掉 --dir）
 // @意图#R637(2026-10-27已废弃): Mac 上没写 --dir 就弹窗选目录、取消不请求服务器（R639 改成连上后在网页上选）
 // @意图#R636(2026-10-27): 配对码一次性、5 分钟有效（服务器判断）；授权目录先换成真实路径再存
-export async function pair({ code, dir, server = DEFAULT_SERVER, name = os.hostname() }, file = configPath()) {
+// @意图#R666(2026-10-29): 配对码可以写成「码@服务器」（code 里带 @ 时拆开，见 parsePairTarget；显式给了 server 就用 server）；15 秒超时；
+// 连不上、服务器回错都翻成大白话（explainNetError / explainPairFailure）；缺码的提示不再写 runner.mjs
+export async function pair({ code, dir, server, name = os.hostname(), timeoutMs = PAIR_TIMEOUT_MS }, file = configPath()) {
   checkNode();
-  if (!code) throw new Error("缺配对码：runner.mjs pair <配对码>");
-  const r = await fetch(`${server.replace(/\/$/, "")}/devices/pair`, {
-    method: "POST", headers: { "content-type": "application/json" },
-    body: JSON.stringify({ code, name, os: `${process.platform} ${os.release()}` }),
-  });
-  const body = await r.json().catch(() => ({}));
-  if (r.status !== 201) throw new Error(`配对失败（${r.status}）：${body.error ?? "未知原因"}`);
-  saveConfig({ server: server.replace(/\/$/, ""), device_id: body.device_id, token: body.token, name, bot_dirs: {} }, file);
-  return { deviceId: body.device_id, file, dirIgnored: dir !== undefined && dir !== null && dir !== "" };
+  const t = parsePairTarget(code, server);
+  if (!t.code) throw new Error(`缺配对码：${progName()} pair <配对码>@<服务器地址>（请从网页上原样复制整条命令）`);
+  let r;
+  try {
+    r = await fetch(`${t.server}/devices/pair`, {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ code: t.code, name, os: `${process.platform} ${os.release()}` }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) { throw new Error(explainNetError(e, t.server, timeoutMs)); }
+  const text = await r.text().catch(() => "");
+  let body = null;
+  try { body = JSON.parse(text); } catch { body = null; }
+  if (r.status !== 201 || !body || typeof body.token !== "string") throw new Error(explainPairFailure(r.status, body));
+  saveConfig({ server: t.server, device_id: body.device_id, token: body.token, name, bot_dirs: {} }, file);
+  return { deviceId: body.device_id, file, server: t.server, dirIgnored: dir !== undefined && dir !== null && dir !== "" };
+}
+
+const isLoopback = (h) => h === "localhost" || /^127\./.test(h) || h === "[::1]" || h === "::1";
+/**
+ * 「码@服务器」拆成 { code, server }（R666）：@ 后面没写 http:// / https:// 时默认 https，localhost、127.x、[::1] 用 http；可以带端口、路径；
+ * 去掉末尾的 /。显式给了 server（--server）就用它；没 @ 也没 --server 用 DEFAULT_SERVER（老行为）。地址看不懂、带 ? # 或账号密码就报错。
+ */
+// @意图#R666(2026-10-29): 配对码里带服务器信息（king 定一甲：码@域名），命令里不用再写 --server；老写法 pair 码 --server 地址照样能用
+export function parsePairTarget(raw, server) {
+  const s = String(raw ?? "").trim();
+  const at = s.indexOf("@");
+  const code = (at < 0 ? s : s.slice(0, at)).trim();
+  const where = at < 0 ? "" : s.slice(at + 1).trim();
+  if (server) return { code, server: String(server).trim().replace(/\/+$/, "") };
+  if (!where) return { code, server: DEFAULT_SERVER };
+  const explicit = /^https?:\/\//i.test(where);
+  let u;
+  try { u = new URL(explicit ? where : `https://${where}`); }
+  catch { throw new Error(`配对码后面的服务器地址看不懂：${where}。请从网页上原样复制整条命令。`); }
+  if (u.search || u.hash || u.username || u.password) throw new Error(`服务器地址不能带 ? # 或账号密码：${where}。请从网页上原样复制整条命令。`);
+  if (!explicit && isLoopback(u.hostname)) u.protocol = "http:";
+  return { code, server: `${u.origin}${u.pathname}`.replace(/\/+$/, "") };
+}
+
+const hostOf = (server) => { try { return new URL(server).host; } catch { return server; } };
+/** fetch 失败（连不上）翻成大白话：找不到、没开、证书、超时、被断开、其他 */
+// @意图#R666(2026-10-29): 原来只打一句英文 fetch failed；按 cause.code 分开说（king 定五）
+export function explainNetError(e, server, timeoutMs = PAIR_TIMEOUT_MS) {
+  const code = String(e?.cause?.code ?? e?.cause?.cause?.code ?? e?.code ?? "");
+  const host = hostOf(server);
+  if (e?.name === "TimeoutError" || e?.name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT") {
+    return `连服务器超时（${Math.round(timeoutMs / 1000)} 秒没回应）：${host}。检查这台电脑能不能上网，或者稍后再试。`;
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") return `找不到服务器 ${host}：命令里 @ 后面的地址可能写错了，或者这台电脑没联网。`;
+  if (code === "ECONNREFUSED") return `连不上服务器 ${server}：服务器没开，或者地址、端口不对。`;
+  if (/CERT|SELF_SIGNED|UNABLE_TO_VERIFY|ERR_TLS|SSL/.test(code)) return `服务器 ${host} 的 https 证书有问题（${code}）：可能证书过期了，或者网络在拦截。请告诉服务器的管理员。`;
+  if (code === "ECONNRESET" || code === "EPIPE" || code === "UND_ERR_SOCKET") return `和服务器 ${host} 的连接被断开了：稍后再试；一直这样请检查代理或网络。`;
+  return `连不上服务器 ${server}（${code || e?.message || "未知原因"}）：检查网络和命令里的地址。`;
+}
+
+/** R666：服务器回的错误码（/devices/pair 返回的 code）对应的大白话 */
+export const PAIR_ERR = {
+  bad_code: "配对码不对：请从网页上原样复制整条命令再运行（码只能用一次，5 分钟有效）。",
+  used: "这个配对码已经用过了：回网页点「换一个码」，再复制新命令运行。",
+  replaced: "这个配对码已经作废了（网页上换过新码）：请复制网页上最新的那条命令运行。",
+  expired: "配对码过期了（5 分钟有效）：回网页点「换一个码」，再复制新命令运行。",
+  device_exists: "这个账号已经连着一台电脑了：先在网页「我的电脑」抽屉最下面「连着的电脑」里点「断开」，再换一个码重新配对。",
+  bad_input: "命令不完整：请从网页上原样复制整条命令再运行。",
+};
+const NOT_HUB = (status) => `这个地址不是 agent-hub 服务器（回了 ${status}）：检查命令里 @ 后面的地址，请从网页上原样复制整条命令。`;
+/** 配对请求回的不是 201：先看服务器给的 code，老服务器没 code 就按状态码猜；回的不是 JSON 多半不是 agent-hub */
+// @意图#R666(2026-10-29): 400/410/409/404/405/非 JSON/5xx 各给一句（king 定五）
+export function explainPairFailure(status, body) {
+  if (body && typeof body === "object" && PAIR_ERR[body.code]) return `配对失败：${PAIR_ERR[body.code]}`;
+  if (status === 404 || status === 405) return `配对失败：${NOT_HUB(status)}`;
+  if (status >= 500) return `配对失败：服务器出错了（${status}），稍后再试。`;
+  if (!body || typeof body !== "object") return `配对失败：${NOT_HUB(status)}`;
+  if (status === 410) return `配对失败：${PAIR_ERR.expired}`;
+  if (status === 409) return `配对失败：${PAIR_ERR.device_exists}`;
+  if (status === 400) return `配对失败：${PAIR_ERR.bad_code}`;
+  return `配对失败（${status}）：${body.error ?? "未知原因"}`;
+}
+
+/** 整个命令出错时打给人看的话：权限不够（多半用 sudo 跑过）单独说怎么修，别的原样 */
+// @意图#R666(2026-10-29): EACCES / EPERM 提示别用 sudo + chown（king 定五）
+export function explainError(e) {
+  const code = e?.code;
+  if (code === "EACCES" || code === "EPERM") {
+    const p = e.path ? String(e.path) : runnerHome();
+    const dir = p.startsWith(runnerHome()) ? runnerHome() : path.dirname(p);
+    return `权限不够，写不了 ${p}：别用 sudo 运行这个命令。如果以前用 sudo 跑过，先运行 sudo chown -R "$(whoami)" "${dir}"，再重新运行。`;
+  }
+  return e?.message ?? String(e);
 }
 
 const wsUrlOf = (server) => `${server.replace(/^http/, "ws")}/devices/ws`;
@@ -143,10 +255,26 @@ const wsUrlOf = (server) => `${server.replace(/^http/, "ws")}/devices/ws`;
 // @意图#R640(2026-10-27): 目录按 bot 分：call 按 bot_id 查对照表，没有就拒绝 NO_DIR；pick_dir 带 bot_id，选完检查后记进对照表、写回配置（600），
 // 回 dir_result {id, ok, bot_id, dir}；老配置的单一 dir 忽略
 // @意图#R639(2026-10-27已废弃): 目录不再是连接时固定的常量；没目录时 call 一律拒绝；pick_dir 选完检查、写回配置（600）、回 dir_result（R640 改成按 bot 分）
-export function createSession(cfg, { log = say, pickDir = pickDirMac, platform = process.platform, file = configPath() } = {}) {
+// @意图#R690(2026-11-01): write / edit 带 change_id（服务器记灰字时生成的 auto_id）就在写改成功后存一份改动记录（存失败只记日志）；
+// 新消息 change_get {id, change_id} → change_result {id, ok:true, found, record}，不看这个 bot 有没有目录（换了目录也能看旧记录）
+export function createSession(cfg, { log = say, pickDir = pickDirMac, platform = process.platform, file = configPath(), changes } = {}) {
   let dirs = botDirsOf(cfg); // bot_id → 授权目录
   const jobs = new Map(); // 调用 id → AbortController
   const picks = new Map(); // 弹窗 id → AbortController
+  let store = changes; // 改动记录（R690），用到时才建
+  const changeStore = () => (store ??= createChangeStore(changesDirFor(file), { log }));
+  const recorder = (args) => {
+    const id = typeof args?.change_id === "string" ? args.change_id : "";
+    if (!CHANGE_ID_RE.test(id)) return undefined;
+    return async (info) => {
+      try { await changeStore().save(id, buildChangeRecord({ id, ...info })); } catch (e) { log(`改动记录没存上（不影响这次写改）：${e?.message ?? e}`); }
+    };
+  };
+
+  async function handleChangeGet(send, msg) {
+    const record = await changeStore().get(msg.change_id).catch(() => null);
+    send({ type: "change_result", id: msg.id, ok: true, found: !!record, ...(record ? { record } : {}) });
+  }
 
   async function handleCall(send, msg) {
     const { id, op, args } = msg;
@@ -157,7 +285,8 @@ export function createSession(cfg, { log = say, pickDir = pickDirMac, platform =
     jobs.set(id, ac);
     log(`[${bot}] ${op === "bash" ? `bash：${args?.command}` : `${op}：${args?.path}`}`);
     try {
-      const res = await runOp(op, args, dir, { signal: ac.signal, onData: (d) => send({ type: "output", id, data: Buffer.from(d).toString("base64") }) });
+      const onChange = op === "write" || op === "edit" ? recorder(args) : undefined;
+      const res = await runOp(op, args, dir, { signal: ac.signal, onChange, onData: (d) => send({ type: "output", id, data: Buffer.from(d).toString("base64") }) });
       if (ac.signal.aborted) send({ type: "result", id, ok: false, error: "已中止" });
       else send({ type: "result", id, ok: true, ...res });
     } catch (e) {
@@ -196,9 +325,12 @@ export function createSession(cfg, { log = say, pickDir = pickDirMac, platform =
 
   return {
     get botDirs() { return { ...dirs }; },
+    /** R690：清掉 30 天前的改动记录（startRunner 启动时调一次） */
+    cleanChanges() { return changeStore().clean(true).catch(() => 0); },
     onMessage(msg, send) {
       if (msg.type === "call") return handleCall(send, msg);
       if (msg.type === "pick_dir") return handlePick(send, msg);
+      if (msg.type === "change_get") return handleChangeGet(send, msg);
       if (msg.type === "abort") { jobs.get(msg.id)?.abort(); picks.get(msg.id)?.abort(); }
       return undefined;
     },
@@ -215,12 +347,17 @@ export function createSession(cfg, { log = say, pickDir = pickDirMac, platform =
  * 连服务器并执行转发来的工具调用。断线会自动重连（不重放旧调用）；令牌不对或网页上断开了就停。
  * 返回 { stop, done }：stop() 立刻断开并杀掉正在跑的命令。
  */
+// @意图#R666(2026-10-29): hello 多报 runner_version（网页提示有新版本）和 autostart（是不是开机自启起的，网页据此给升级命令）；
+// 服务器用 4409 顶掉这条（同一份配置又开了一个）：不再重连、结束（"replaced"）；连不上时只在第一次和之后每 30 次打一行，开机自启没网时日志不刷屏；
+// 连上那句不再说「右栏」，开机自启时不说「按 Ctrl-C」
 // @意图#R640(2026-10-27): hello 报 bot→目录 对照表（bot_dirs），不再报单一 dir
 // @意图#R639(2026-10-27): 没目录也能连上；目录由 createSession 管（网页上选完马上生效），重连时 hello 带当前目录
 // @意图#R636(2026-10-27): 前台运行、心跳、执行工具调用；断线时杀掉正在跑的命令，重连后不重放
-export function startRunner(cfg, { log = say, retryMs = 2000, pickDir = pickDirMac, platform = process.platform, file = configPath() } = {}) {
+export function startRunner(cfg, { log = say, retryMs = 2000, pickDir = pickDirMac, platform = process.platform, file = configPath(), background = process.env.AGENT_RUNNER_LAUNCHD === "1" } = {}) {
   checkNode();
+  let fails = 0;
   const session = createSession(cfg, { log, pickDir, platform, file });
+  void session.cleanChanges(); // R690：启动时清一次 30 天前的改动记录
   let ws = null;
   let stopped = false;
   let beat = null;
@@ -235,16 +372,18 @@ export function startRunner(cfg, { log = say, retryMs = 2000, pickDir = pickDirM
     ws = sock;
     sock.addEventListener("open", () => {
       send(sock, { type: "hello", version: PROTOCOL_VERSION, device_id: cfg.device_id, token: cfg.token, bot_dirs: session.botDirs,
-        name: cfg.name ?? os.hostname(), os: `${process.platform} ${os.release()}` });
+        name: cfg.name ?? os.hostname(), os: `${process.platform} ${os.release()}`, runner_version: RUNNER_VERSION, autostart: background });
       beat = setInterval(() => send(sock, { type: "ping" }), HEARTBEAT_MS);
     });
     sock.addEventListener("message", (ev) => {
       let msg;
       try { msg = JSON.parse(typeof ev.data === "string" ? ev.data : Buffer.from(ev.data).toString("utf8")); } catch { return; }
       if (msg.type === "ready") {
+        fails = 0;
         const n = Object.keys(session.botDirs).length;
-        log(n ? `已连上服务器 ${cfg.server}，${n} 个 bot 选了目录。按 Ctrl-C 断开。`
-          : `已连上服务器 ${cfg.server}，还没有 bot 选目录：请在每个 bot 的私聊右栏「我的电脑」里点「选择目录」。按 Ctrl-C 断开。`);
+        const tail = background ? "（开机自启，在后台运行）" : "按 Ctrl-C 断开。";
+        log(n ? `已连上服务器 ${cfg.server}，${n} 个 bot 选了目录。${tail}`
+          : `已连上服务器 ${cfg.server}，还没有 bot 选目录：请在网页上每个 bot 的私聊里点输入框下面「我的电脑」那一行，再点「选择目录」。${tail}`);
       } else if (msg.type === "revoked") { session.killAll(); log("网页上已断开这台电脑，令牌已作废。要再连，请在网页上重新拿配对码配对。"); }
       else void session.onMessage(msg, (m) => send(sock, m));
     });
@@ -255,7 +394,9 @@ export function startRunner(cfg, { log = say, retryMs = 2000, pickDir = pickDirM
       if (stopped) return;
       if (ev.code === CLOSE_BAD_TOKEN) { log("服务器不认这个令牌（可能已经在网页上断开过）。请重新配对。"); finish("bad_token"); return; }
       if (ev.code === CLOSE_REVOKED) { log("这台电脑已在网页上断开。请重新配对。"); finish("revoked"); return; }
-      log(`和服务器的连接断了，${retryMs / 1000} 秒后重连`);
+      if (ev.code === CLOSE_REPLACED) { log("同一份配置在别处又开了一个运行器，服务器把这个顶掉了：这个先退出（不再重连）。"); finish("replaced"); return; }
+      fails += 1;
+      if (fails === 1 || fails % 30 === 0) log(`和服务器的连接断了，${retryMs / 1000} 秒后重连${fails > 1 ? `（已经连不上 ${fails} 次，会一直重试）` : ""}`);
       setTimeout(connect, retryMs);
     });
     sock.addEventListener("error", () => { /* close 里处理 */ });
@@ -272,43 +413,198 @@ export function startRunner(cfg, { log = say, retryMs = 2000, pickDir = pickDirM
   return { stop, done };
 }
 
+/** R666：同一份配置只能跑一个：配置旁边的 <配置>.lock 记着进程号 */
+export const lockPath = (file = configPath()) => `${file}.lock`;
+export function readLock(file = configPath()) {
+  try { const j = JSON.parse(readFileSync(lockPath(file), "utf8")); return Number.isInteger(j?.pid) ? j : null; } catch { return null; }
+}
+export const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e?.code === "EPERM"; } };
+/**
+ * 拿锁：别的活着的进程拿着就返回 { ok: false, pid, launchd }；否则写上自己（600）返回 { ok: true, release }。
+ * 进程死了留下的旧锁直接覆盖。
+ */
+// @意图#R666(2026-10-29): 防互踢（king 定必须做）：开机自启的在后台跑着，再在终端里 start 就提示「已经在后台连着」退出，不再两个互相顶
+export function takeLock(file = configPath(), { pid = process.pid, launchd = process.env.AGENT_RUNNER_LAUNCHD === "1" } = {}) {
+  const cur = readLock(file);
+  if (cur && cur.pid !== pid && pidAlive(cur.pid)) return { ok: false, pid: cur.pid, launchd: !!cur.launchd };
+  mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  writeFileSync(lockPath(file), `${JSON.stringify({ pid, launchd, started_at: new Date().toISOString() })}\n`, { mode: 0o600 });
+  return { ok: true, release: () => { if (readLock(file)?.pid === pid) rmSync(lockPath(file), { force: true }); } };
+}
+
+/** 被网页断开 / 令牌失效后把这份配置的开机自启关掉（不然每次登录都白起一次）；不是 Mac、没开都不要紧 */
+async function autostartOffQuietly(file, deps) {
+  if ((deps.platform ?? process.platform) !== "darwin") return false;
+  try { return (await autostartOff({ configFile: file, launchctl: deps.launchctl })).wasOn; } catch { return false; }
+}
+
+// @意图#R666(2026-10-29): 先拿锁（后台已在跑就提示退出 0）；开机自启时启动前日志超 5MB 清空、配置坏了/没配对也退出 0（不让 launchd 反复拉起）；
+// 结束一律退出码 0（Ctrl-C、被网页断开、令牌失效、被顶掉），被断开 / 令牌失效时顺手关掉自启
 // @意图#R663(2026-10-29): 前台跑 start，Ctrl-C 断开（pair --start 和 start 共用）
-async function runStart() {
-  const cfg = loadConfig();
-  const r = startRunner(cfg);
-  const quit = () => { r.stop(); setTimeout(() => process.exit(0), 100); };
+async function runStart(prog = progName(), deps = {}) {
+  const file = configPath();
+  const background = process.env.AGENT_RUNNER_LAUNCHD === "1";
+  if (background && truncateLogIfBig(logFileFor(file))) say("日志超过 5MB，已清空");
+  let cfg;
+  try { cfg = loadConfig(file); } catch (e) {
+    if (background) { console.error(explainError(e)); process.exit(0); }
+    throw e;
+  }
+  const lock = takeLock(file);
+  if (!lock.ok) {
+    console.log(`已经在后台连着，不用再开（进程 ${lock.pid}${lock.launchd ? "，开机自启起的" : ""}）。要停掉它：${prog} stop`);
+    process.exit(0);
+  }
+  const r = startRunner(cfg, { file, background });
+  const quit = () => { r.stop(); lock.release(); setTimeout(() => process.exit(0), 100); };
   process.on("SIGINT", quit);
   process.on("SIGTERM", quit);
   const why = await r.done;
-  process.exit(why === "stopped" ? 0 : 1);
+  lock.release();
+  if (why === "bad_token" || why === "revoked") {
+    if (await autostartOffQuietly(file, deps)) say("已关掉开机自启（这台电脑在网页上断开了）。");
+  }
+  process.exit(0);
+}
+
+/** R666：配完要不要开机自启：flag（--autostart / --no-autostart）优先；不是 Mac 不开；是终端就问；不是终端（脚本、管道）不问、只提示 */
+export function decideAutostart({ flag, platform = process.platform, tty = !!(process.stdin.isTTY && process.stdout.isTTY) }) {
+  if (flag === true) return platform === "darwin" ? "on" : "unsupported";
+  if (flag === false) return "off";
+  if (platform !== "darwin") return "off";
+  return tty ? "ask" : "hint";
 }
 
+/** 终端里问一句 是/否；直接回车 = dflt */
+export async function askYesNo(question, dflt = true, { input = process.stdin, output = process.stdout } = {}) {
+  const rl = readline.createInterface({ input, output });
+  try {
+    const a = (await rl.question(question)).trim().toLowerCase();
+    if (!a) return dflt;
+    return ["y", "yes", "是", "好", "要"].includes(a);
+  } finally { rl.close(); }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** 停掉拿着锁的那个运行器（不是自己）；等它真退出（最多 5 秒）。返回被停的锁信息，没有在跑的返回 null */
+async function stopHolder(file) {
+  const l = readLock(file);
+  if (!l || l.pid === process.pid || !pidAlive(l.pid)) return null;
+  try { process.kill(l.pid, "SIGTERM"); } catch { /* 已经没了 */ }
+  for (let i = 0; i < 50 && pidAlive(l.pid); i++) await sleep(100);
+  return l;
+}
+
+const here = () => path.dirname(fileURLToPath(import.meta.url));
+// @意图#R666(2026-10-29): 开启自启：前台有一个在跑就先停掉它（不然后台那个起来就因为锁退出了），再交给 autostart.mjs（复制自己、写 plist、加载）
+async function turnAutostartOn(file, prog, deps = {}) {
+  const held = readLock(file);
+  if (held && !held.launchd) await stopHolder(file);
+  const r = await autostartOn({ configFile: file, version: RUNNER_VERSION, srcDir: here(), launchctl: deps.launchctl, platform: deps.platform });
+  console.log(`已设开机自启：以后登录这台 Mac 会自动连上，不用开终端。现在已经在后台连着，可以关掉这个终端窗口了。\n日志：${r.log}\n关掉开机自启：${prog} autostart off`);
+  return r;
+}
+
+const usage = (prog) => `用法：
+  ${prog} pair <配对码>@<服务器地址> [--no-start] [--autostart | --no-autostart]
+    （网页上「我的电脑」里复制的就是这一条；配完直接连上，Mac 上会问要不要开机自动连上；--no-start 只配对不连）
+    （老写法 ${prog} pair <配对码> --server <地址> 也能用）
+  ${prog} start              连上服务器（终端窗口别关；Ctrl-C 断开）
+  ${prog} stop               停掉在跑的运行器
+  ${prog} status             看配置、各 bot 的目录、在不在跑、开机自启
+  ${prog} autostart on|off|status   Mac 开机自启（on 也用来升级到新版本）
+  ${prog} uninstall [--purge]       关掉自启、删掉本地副本和日志（--purge 连配置一起删）
+  ${prog} --version
+目录请连上后在网页上每个 bot 的私聊里点输入框下面「我的电脑」那一行选，Mac 上会弹窗让你选。`;
+
+// @意图#R666(2026-10-29): pair 默认配完直接 start（--no-start 只配对）；配完按 decideAutostart 问 / 提示 / 开启开机自启，开了就不在前台跑；
+// 新命令 stop、autostart on|off|status、uninstall、--version；status 多显示在不在跑、版本、开机自启；用法里的命令按运行方式写（npx 时写 npx 写法）
 // @意图#R664(2026-10-29): 导出给 bin/agent-hub-runner.mjs 调；用法和「现在运行：… start」里的命令名用 progName（装好的 agent-hub-runner，仓库里 node 写法）
-// @意图#R663(2026-10-29): pair --start 配对成功后直接进 start（二甲）；提示里「我的电脑」改成在私聊输入框下面那一行点开（R663 挪了位置）；不带 --start 照旧提示再运行 start
+// @意图#R663(2026-10-29): pair --start 配对成功后直接进 start（二甲）；提示里「我的电脑」改成在私聊输入框下面那一行点开（R663 挪了位置）；不带 --start 照旧提示再运行 start（R666 起默认就 start，--no-start 才提示）
 // @意图#R640(2026-10-27): pair 带 --dir 只提示不报错；status 列出每个 bot 的目录；用法文字去掉 --dir
-export async function main(argv, prog = progName()) {
+export async function main(argv, prog = progName(), deps = {}) {
+  checkNode();
   const a = parseArgs(argv);
+  const platform = deps.platform ?? process.platform;
   if (a.cmd === "pair") {
-    const r = await pair({ code: a.positional[0], dir: a.dir, server: a.server ?? DEFAULT_SERVER, name: a.name ?? os.hostname() });
+    const r = await pair({ code: a.positional[0], dir: a.dir, server: a.server, name: a.name ?? os.hostname() });
     if (r.dirIgnored) console.log(PAIR_DIR_IGNORED);
     const where = "目录：连上后在网页上每个 bot 的私聊里，点输入框下面「我的电脑」那一行选。";
-    if (a.start) {
-      console.log(`配对成功。${where}\n配置存在 ${r.file}（权限 600）。\n接着连服务器（--start）……`);
-      await runStart();
+    console.log(`配对成功（服务器 ${r.server}）。${where}\n配置存在 ${r.file}（权限 600）。`);
+    const how = decideAutostart({ flag: a.autostart, platform, tty: deps.tty });
+    let on = how === "on";
+    if (how === "ask") on = await (deps.ask ?? askYesNo)("开机自动连上？以后不用开终端 (Y/n) ", true);
+    if (how === "unsupported") console.log(ONLY_MAC + "，这次不设。");
+    if (on) {
+      try { await turnAutostartOn(r.file, prog, deps); return; }
+      catch (e) { console.log(`开机自启没设成：${explainError(e)}\n这次先在前台连着（终端窗口别关）。`); }
+    }
+    if (how === "ask") console.log(`好的，不设开机自启。以后想开：${prog} autostart on`);
+    if (how === "hint") console.log(`想开机自动连上（不用开终端）：运行 ${prog} autostart on`);
+    if (a.start === false) { console.log(`现在运行：${prog} start`); return; }
+    console.log("接着连服务器……");
+    await runStart(prog, deps);
+    return;
+  }
+  if (a.cmd === "start") { await runStart(prog, deps); return; }
+  if (a.cmd === "stop") {
+    const l = await stopHolder(configPath());
+    if (!l) { console.log("没有在跑的运行器。"); return; }
+    console.log(`已停掉（进程 ${l.pid}）。${l.launchd ? `开机自启还开着，下次登录会自己连上；不想要：${prog} autostart off` : ""}`);
+    return;
+  }
+  if (a.cmd === "autostart") {
+    const sub = a.positional[0] ?? "status";
+    const file = configPath();
+    if (sub === "on") { loadConfig(file); await turnAutostartOn(file, prog, deps); return; }
+    if (platform !== "darwin") { console.log(ONLY_MAC); return; }
+    if (sub === "off") {
+      const r = await autostartOff({ configFile: file, launchctl: deps.launchctl });
+      console.log(r.wasOn ? "已关掉开机自启（后台那个也停了）。" : "本来就没开开机自启。");
       return;
     }
-    console.log(`配对成功。${where}\n配置存在 ${r.file}（权限 600）。\n现在运行：${prog} start`);
+    if (sub === "status") {
+      const st = await autostartStatus({ configFile: file, launchctl: deps.launchctl, platform });
+      console.log(st.installed ? `开机自启：开着（${st.loaded ? (st.pid ? `后台在跑，进程 ${st.pid}` : "已加载，现在没在跑") : "还没加载"}）\nplist：${st.plist}\n日志：${st.log}` : "开机自启：没开");
+      for (const p of st.problems) console.log(`注意：${p}`);
+      return;
+    }
+    throw new Error(`autostart 后面只能是 on、off 或 status（${sub} 不认识）`);
+  }
+  if (a.cmd === "uninstall") {
+    const file = configPath();
+    if (platform === "darwin") await autostartOff({ configFile: file, launchctl: deps.launchctl }).catch(() => {});
+    await stopHolder(file);
+    const home = runnerHome();
+    if (!otherAutostarts(file).length) {
+      rmSync(path.join(home, "bin"), { recursive: true, force: true });
+      rmSync(path.join(home, "logs"), { recursive: true, force: true });
+    }
+    let purge = !!a.purge;
+    if (!purge && existsSync(file) && (deps.tty ?? !!(process.stdin.isTTY && process.stdout.isTTY))) {
+      purge = await (deps.ask ?? askYesNo)("要连配对信息（令牌）一起删掉吗？删了以后要重新配对 (y/N) ", false);
+    }
+    if (purge) { rmSync(file, { force: true }); rmSync(lockPath(file), { force: true }); }
+    console.log(`已卸载：开机自启关了、本地副本和日志删了。${purge ? `配置也删了（${file}）；记得在网页「我的电脑」里点「断开」作废令牌。` : `配置留着（${file}）；连配置一起删：${prog} uninstall --purge`}`);
     return;
   }
-  if (a.cmd === "start") await runStart();
   if (a.cmd === "status") {
-    const cfg = loadConfig();
+    const file = configPath();
+    const cfg = loadConfig(file);
     const d = Object.entries(botDirsOf(cfg));
-    console.log(`服务器：${cfg.server}\n设备：${cfg.device_id}\n各 bot 的授权目录：${d.length ? d.map(([b, p]) => `\n  ${b}：${p}`).join("") : "（还没有，start 连上后在每个 bot 的私聊里点「选择目录」）"}`);
+    const l = readLock(file);
+    const run = l && pidAlive(l.pid) ? `在跑（进程 ${l.pid}${l.launchd ? "，开机自启" : ""}）` : "没在跑";
+    let auto = "";
+    if (platform === "darwin") {
+      const st = await autostartStatus({ configFile: file, launchctl: deps.launchctl, platform }).catch(() => null);
+      auto = `\n开机自启：${st?.installed ? "开着" : "没开"}${st?.problems?.length ? `（${st.problems.join("；")}）` : ""}`;
+    }
+    console.log(`服务器：${cfg.server}\n设备：${cfg.device_id}\n运行器版本：${RUNNER_VERSION}\n现在：${run}${auto}\n各 bot 的授权目录：${d.length ? d.map(([b, p]) => `\n  ${b}：${p}`).join("") : "（还没有，连上后在每个 bot 的私聊里点「选择目录」）"}`);
     return;
   }
-  console.log(`用法：\n  ${prog} pair <配对码> [--start] [--server http://127.0.0.1:3220]\n    （--start：配对成功后直接连上，不用再跑 start；目录请连上后在网页上每个 bot 的私聊里点输入框下面「我的电脑」那一行选，Mac 上会弹窗让你选）\n  ${prog} start\n  ${prog} status`);
-  process.exitCode = a.cmd ? 1 : 0;
+  if (a.cmd === "version") { console.log(RUNNER_VERSION); return; }
+  console.log(usage(prog));
+  process.exitCode = a.cmd && a.cmd !== "help" ? 1 : 0;
 }
 
 const real = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
@@ -323,15 +619,26 @@ export function isMainModule(argv1 = process.argv[1], metaUrl = import.meta.url)
  * 用法和提示里怎么称呼自己：npm 装好的（经 bin 里的 agent-hub-runner 链接运行，或文件在 node_modules 里）说 agent-hub-runner，
  * 仓库里直接跑说 node <相对路径>。
  */
+// @意图#R666(2026-10-29): npx 跑的（npm 设 npm_lifecycle_event=npx，或文件在 npx 缓存 _npx 目录里）和开机自启的本地副本（~/.agent-runner/bin 下）都写 npx 写法：
+// 这两种情况电脑上都没有 agent-hub-runner 这个命令
 // @意图#R664(2026-10-29): 用法和配对成功提示按运行方式区分：装好的显示 agent-hub-runner …，仓库里显示 node 写法
-export function progName(entry = process.argv[1], cwd = process.cwd()) {
+export function progName(entry = process.argv[1], cwd = process.cwd(), env = process.env) {
   if (!entry) return PKG_BIN;
-  if (path.basename(entry) === PKG_BIN) return PKG_BIN;
+  if (isNpx(entry, env)) return NPX_CMD;
   const r = real(entry);
+  const bin = real(path.join(runnerHome(env), "bin"));
+  if (r === bin || r.startsWith(`${bin}${path.sep}`)) return NPX_CMD;
+  if (path.basename(entry) === PKG_BIN) return PKG_BIN;
   if (/[\\/]node_modules[\\/]/.test(r)) return PKG_BIN;
   return `node ${path.relative(cwd, r) || path.basename(r)}`;
 }
+/** 是不是 npx 跑起来的 */
+export function isNpx(entry = process.argv[1], env = process.env) {
+  if (env.npm_lifecycle_event === "npx") return true;
+  return !!entry && /[\\/]_npx[\\/]/.test(real(entry));
+}
 
+// @意图#R666(2026-10-29): 出错时打大白话（权限不够单独说）
 if (isMainModule()) {
-  main(process.argv.slice(2)).catch((e) => { console.error(e?.message ?? String(e)); process.exit(1); });
+  main(process.argv.slice(2)).catch((e) => { console.error(explainError(e)); process.exit(1); });
 }