agent-hub-runner 0.2.1 → 0.3.1

package/README.md

@@ -1,5 +1,8 @@
+<!-- @意图#R747(2026-11-06): 说明 .claude/skills 需运行器 0.3.1 -->
+<!-- @意图#R745(2026-11-06): 说明 context_snapshot / 0.3.0 -->
 <!-- @意图#R729(2026-11-04): 加 browser install / status 和「bot 的浏览器」一节（0.2.0） -->
 <!-- @意图#R690(2026-11-01): 加「改动记录」一节：存在哪、打码、64 KB、30 天、怎么删 -->
+<!-- @意图#R732(2026-11-04): 常见问题加「升级了网页还说版本太旧」（0.2.2 起新版自动顶掉旧进程） -->
 <!-- @意图#R731(2026-11-04): 常见问题加开机自启「Bootstrap failed: 5」（0.2.1 起自动处理） -->
 <!-- @意图#R666(2026-10-29): 改成不用全局安装的 npx 一条命令（码@地址）、Mac 开机自启、stop / uninstall、常见报错 -->
 <!-- @意图#R664(2026-10-29): npm 包 agent-hub-runner 的说明（随包发布）：给客户看的安装、配对、再连、查看、断开、卸载和安全提示 -->
@@ -64,6 +67,11 @@ npx -y agent-hub-runner@latest browser status  # 看浏览器装没装
 - 想放别处：设环境变量 `AGENT_RUNNER_CONFIG=/某个路径/config.json`。
 - 文件坏了：删掉它，回网页拿新配对码重新配对。
 
+
+## 项目上下文快照（0.3.0；`.claude/skills` 起 0.3.1）
+
+服务器在每轮主对话开始时可能调用只读操作 `context_snapshot`（没有路径参数）：在**当前 bot 的授权文件夹根**里读取一份 AGENTS/CLAUDE 规则，并列出 `.pi/skills`、`.agents/skills`、`.claude/skills` 下技能的名称与说明（不上传技能全文）。目录外路径和越界符号链接一律拒绝。基础快照需要运行器 **0.3.0+**；发现 `.claude/skills` 需要 **0.3.1+**。
+
 ## 常见问题
 
 - `command not found: npx`：还没装 Node。
@@ -73,6 +81,7 @@ npx -y agent-hub-runner@latest browser status  # 看浏览器装没装
 - 「配对码过期了 / 已经用过了 / 已经作废了」：网页上点「换一个码」再运行新命令。
 - 「这个账号已经连着一台电脑了」：一个账号同时只能连一台，先在网页抽屉「连着的电脑」里点「断开」。
 - 开机自启报「Bootstrap failed: 5: Input/output error」：这个后台任务以前被 macOS 记成了「已禁用」。0.2.1 起 `autostart on` 会自己解除并重试，直接再运行一次 `npx -y agent-hub-runner@latest autostart on` 就行；还不行就按它给的那条 `launchctl enable …` 命令运行后再试，或重启电脑再试。
+- 升级后网页还说「运行器版本太旧」：旧版本的运行器还在后台跑着（升级前开的终端，或者旧的开机自启），新版一看有人连着就退出了。0.2.2 起新版会自己把旧版本停掉、接上服务器；从 0.2.1 或更早升上来的，运行一次 `npx -y agent-hub-runner@latest autostart on` 就行，它会先停掉正在跑的那个，等新版本真连上了才说「已设开机自启」。
 
 ## 断开、卸载
 

package/autostart.mjs

@@ -20,7 +20,7 @@ export const THROTTLE_S = 10;
 /** 复制到 ~/.agent-runner/bin/<版本>/ 的文件（package.json 用来读版本号） */
 // @意图#R729(2026-11-04): 多复制 browser.mjs（runner.mjs 要 import 它）
 // @意图#R690(2026-11-01): 多复制 changes.mjs（runner.mjs 要 import 它，少了开机自启的副本起不来）
-export const COPY_FILES = ["runner.mjs", "ops.mjs", "edit.mjs", "changes.mjs", "browser.mjs", "autostart.mjs", "package.json"];
+export const COPY_FILES = ["runner.mjs", "ops.mjs", "project-context.mjs", "edit.mjs", "changes.mjs", "browser.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 和 Windows";

package/ops.mjs

@@ -6,6 +6,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { editText } from "./edit.mjs";
+import { opContextSnapshot } from "./project-context.mjs";
 
 export const MAX_READ_BYTES = 20 * 1024 * 1024;
 /** bash 没给 timeout 时的默认上限（秒），到点杀掉整个进程组。 */
@@ -183,12 +184,15 @@ export function opBash(args, root, { onData, signal, platform = process.platform
 
 /** 按 op 分派；未知 op 拒绝。 */
 // @意图#R690(2026-11-01): write、edit 也收 extra（onChange 存改动记录）
-// @意图#R636(2026-10-27): 协议里只有这四种工具调用
+// @意图#R745(2026-11-06): 另加只读 context_snapshot（无路径入参）
+// @意图#R636(2026-10-27): 协议里原有四种工具调用
+// @意图#R745(2026-11-06): 从客户已授权目录加载项目规则并按需提供技能
 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, extra);
   if (op === "edit") return opEdit(a, root, extra);
   if (op === "bash") return opBash(a, root, extra);
+  if (op === "context_snapshot") return opContextSnapshot(a, root); // 固定扫授权根，忽略路径参数
   return Promise.reject(new Error(`未知操作 ${op}`));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub-runner",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "agent-hub 的电脑运行器：配对后让你的 bot 在这台电脑上读写授权目录里的文件、跑命令（跑命令要你在网页上批准），还能用它自己的独立浏览器",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "runner.mjs",
     "ops.mjs",
+    "project-context.mjs",
     "edit.mjs",
     "changes.mjs",
     "browser.mjs",

package/project-context.mjs

@@ -0,0 +1,402 @@
+// @意图#R747(2026-11-06): 授权根增加 .claude/skills，兼容 Claude Code 项目技能目录
+// @意图#R745(2026-11-06): 从客户已授权目录加载项目规则并按需提供技能
+// 只扫授权根：一份 AGENTS/CLAUDE 候选 + .pi/skills + .agents/skills + .claude/skills；不读祖先、不读 ~/.agents / ~/.pi / ~/.claude。
+import fs from "node:fs/promises";
+import { existsSync, readFileSync, readdirSync, statSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+// 路径校验与 ops.mjs 同语义，避免与 ops 循环依赖。
+export const inside = (real, root) => real === root || real.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+
+export async function realOf(abs, depth = 0) {
+  if (depth > 40) throw new Error("符号链接太多层");
+  try {
+    return await fs.realpath(abs);
+  } catch (e) {
+    if (e?.code !== "ENOENT") throw e;
+    let st;
+    try { st = lstatSync(abs); } catch { st = undefined; }
+    if (st?.isSymbolicLink()) {
+      const target = path.resolve(path.dirname(abs), readlinkSync(abs));
+      return realOf(target, depth + 1);
+    }
+    const parent = path.dirname(abs);
+    if (parent === abs) throw e;
+    return path.join(await realOf(parent, depth + 1), path.basename(abs));
+  }
+}
+
+export const AGENTS_CANDIDATES = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+export const MAX_TOTAL_BYTES = 2 * 1024 * 1024;
+export const MAX_FILE_BYTES = 128 * 1024;
+export const MAX_SKILLS = 100;
+export const SKILL_DIRS = [".pi/skills", ".agents/skills", ".claude/skills"];
+export const IGNORE_FILE_NAMES = [".gitignore", ".ignore", ".fdignore"];
+
+export function stripBom(s) {
+  return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+/** 极简 ignore：注释、否定、末尾 /、* 与 **（不含完整 gitignore 语义，够 pi 技能树常用规则）。 */
+export function createIgnoreMatcher() {
+  const rules = [];
+  return {
+    add(patterns) {
+      for (const raw of patterns) {
+        const line = String(raw);
+        const trimmed = line.trim();
+        if (!trimmed || (trimmed.startsWith("#") && !trimmed.startsWith("\\#"))) continue;
+        let negated = false;
+        let pattern = line;
+        if (pattern.startsWith("!")) { negated = true; pattern = pattern.slice(1); }
+        else if (pattern.startsWith("\\!")) pattern = pattern.slice(1);
+        if (pattern.startsWith("/")) pattern = pattern.slice(1);
+        rules.push({ negated, pattern: pattern.replace(/\\/g, "/"), dirOnly: pattern.endsWith("/") });
+      }
+    },
+    ignores(rel, isDir = false) {
+      const target = toPosix(rel).replace(/^\/+/, "");
+      let ignored = false;
+      for (const r of rules) {
+        const pat = r.dirOnly ? r.pattern.slice(0, -1) : r.pattern;
+        if (r.dirOnly && !isDir) continue;
+        if (matchGlob(pat, target) || matchGlob(pat, target.split("/").pop() || "")) {
+          ignored = !r.negated;
+        }
+      }
+      return ignored;
+    },
+  };
+}
+
+function matchGlob(pat, text) {
+  if (pat === text) return true;
+  if (pat.endsWith("/**")) {
+    const base = pat.slice(0, -3);
+    return text === base || text.startsWith(base + "/");
+  }
+  if (pat.includes("**")) {
+    const parts = pat.split("**");
+    if (parts.length !== 2) return false;
+    const [a, b] = parts;
+    if (a && !text.startsWith(a.replace(/\/$/, ""))) {
+      if (!text.includes("/" + a.replace(/^\/|\/$/g, ""))) return false;
+    }
+    const rest = a ? text.slice(Math.max(text.indexOf(a.replace(/\/$/, "")) + a.replace(/\/$/, "").length, 0)) : text;
+    const needle = b.replace(/^\//, "");
+    return !needle || rest.includes(needle) || rest.endsWith(needle.replace(/^\//, ""));
+  }
+  if (!pat.includes("*") && !pat.includes("?")) {
+    return text === pat || text.endsWith("/" + pat);
+  }
+  const esc = pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+  return new RegExp(`(?:^|/)${esc}$`).test(text) || new RegExp(`^${esc}$`).test(text);
+}
+
+function addIgnoreRules(ig, dir, root) {
+  const relativeDir = path.relative(root, dir);
+  const prefix = relativeDir && relativeDir !== "." ? `${toPosix(relativeDir)}/` : "";
+  for (const filename of IGNORE_FILE_NAMES) {
+    const ignorePath = path.join(dir, filename);
+    if (!existsSync(ignorePath)) continue;
+    try {
+      const content = readFileSync(ignorePath, "utf8");
+      const patterns = content.split(/\r?\n/).map((line) => {
+        const trimmed = line.trim();
+        if (!trimmed || (trimmed.startsWith("#") && !trimmed.startsWith("\\#"))) return null;
+        let pattern = line;
+        let negated = false;
+        if (pattern.startsWith("!")) { negated = true; pattern = pattern.slice(1); }
+        else if (pattern.startsWith("\\!")) pattern = pattern.slice(1);
+        if (pattern.startsWith("/")) pattern = pattern.slice(1);
+        const prefixed = prefix ? `${prefix}${pattern}` : pattern;
+        return negated ? `!${prefixed}` : prefixed;
+      }).filter(Boolean);
+      if (patterns.length) ig.add(patterns);
+    } catch { /* ignore unreadable */ }
+  }
+}
+
+/**
+ * 小型 frontmatter：只认 name / description / disable-model-invocation（及 camelCase）。
+ * 支持单双引号、| / > / |- / >- / |> / >| 多行块。
+ */
+export function parseSkillFrontmatter(raw) {
+  const text = stripBom(String(raw ?? ""));
+  if (!text.startsWith("---")) return null;
+  const nl = text.indexOf("\n");
+  if (nl < 0) return null;
+  const end = text.indexOf("\n---", nl);
+  if (end < 0) return null;
+  const body = text.slice(nl + 1, end);
+  const out = {};
+  const lines = body.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+    if (!m) { i += 1; continue; }
+    const key = m[1];
+    let val = m[2];
+    if (val === "" || /^[|>](?:[+-]\d?|\d[+-]?)$/.test(val) || val === "|>" || val === ">|") {
+      const block = [];
+      i += 1;
+      while (i < lines.length) {
+        const L = lines[i];
+        if (L === "" || L.startsWith(" ") || L.startsWith("\t")) {
+          block.push(L.replace(/^  /, "").replace(/^\t/, ""));
+          i += 1;
+          continue;
+        }
+        if (/^[A-Za-z0-9_-]+\s*:/.test(L)) break;
+        block.push(L);
+        i += 1;
+      }
+      while (block.length && block[block.length - 1] === "") block.pop();
+      out[key] = block.join("\n");
+      continue;
+    }
+    if (val.startsWith('"')) {
+      // 双引号：优先按 JSON 字符串解（支持 \" \\ \n）；失败再剥一层皮
+      try { out[key] = JSON.parse(val); }
+      catch {
+        out[key] = val.length >= 2 && val.endsWith('"') ? val.slice(1, -1) : val.slice(1);
+      }
+    } else if (val.startsWith("'")) {
+      // 单引号：YAML 里 '' 表示一个 '
+      let s = val.endsWith("'") ? val.slice(1, -1) : val.slice(1);
+      out[key] = s.replace(/''/g, "'");
+    } else if (val === "true") out[key] = true;
+    else if (val === "false") out[key] = false;
+    else out[key] = val;
+    i += 1;
+  }
+  return out;
+}
+
+function skillFromFile(filePath) {
+  let raw;
+  try { raw = readFileSync(filePath, "utf8"); } catch { return { skill: null, notice: `无法读取技能文件：${filePath}` }; }
+  let bytes;
+  try { bytes = Buffer.byteLength(raw, "utf8"); } catch { bytes = raw.length; }
+  if (bytes > MAX_FILE_BYTES) {
+    return { skill: null, notice: `技能文件超过 ${MAX_FILE_BYTES} 字节，已跳过：${filePath}` };
+  }
+  const fm = parseSkillFrontmatter(raw);
+  const declared = path.basename(filePath) === "SKILL.md";
+  if (!fm) return { skill: null, notice: declared ? `技能缺少有效 YAML frontmatter，已跳过：${filePath}` : null };
+  const description = typeof fm.description === "string" ? fm.description.trim().slice(0, 1024) : "";
+  if (!description) return { skill: null, notice: declared ? `技能缺少 description，已跳过：${filePath}` : null };
+  const parentDirName = path.basename(path.dirname(filePath));
+  const name = typeof fm.name === "string" && fm.name.trim() ? fm.name.trim() : parentDirName;
+  const disable = fm["disable-model-invocation"] === true || fm.disableModelInvocation === true;
+  return {
+    skill: {
+      name,
+      description,
+      filePath,
+      baseDir: path.dirname(filePath),
+      disableModelInvocation: disable,
+      _bytes: Buffer.byteLength(JSON.stringify({ name, description, filePath, baseDir: path.dirname(filePath) }), "utf8"),
+    },
+    notice: null,
+  };
+}
+
+function markSkillsCapped(acc, detail) {
+  if (acc.capped) return;
+  acc.capped = true;
+  acc.stopped = true;
+  acc.notices.push(detail || `技能超过 ${MAX_SKILLS} 个上限，已停止发现`);
+}
+
+async function ensureInside(abs, authRoot, notices, label) {
+  let real;
+  try { real = await realOf(abs); } catch (e) {
+    notices.push(`无法解析${label}：${abs}（${e?.code ?? e?.message ?? e}）`);
+    return null;
+  }
+  if (!inside(real, authRoot)) {
+    notices.push(`目录外路径已拒绝：${label}（授权目录是 ${authRoot}）`);
+    return null;
+  }
+  return real;
+}
+
+async function loadSkillsFromDirInternal(dir, includeRootFiles, ig, root, acc, authRoot) {
+  if (!existsSync(dir)) return;
+  if (acc.skills.length >= MAX_SKILLS) { markSkillsCapped(acc); return; }
+  // 循环 symlink 指向已扫过的目录时跳过，不能卡住运行器事件循环。
+  if (acc.visited.has(dir)) return;
+  acc.visited.add(dir);
+  addIgnoreRules(ig, dir, root);
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+
+  // SKILL.md 优先：有则加载并停止向子目录递归（pi 行为）
+  for (const entry of entries) {
+    if (entry.name !== "SKILL.md") continue;
+    const fullPath = path.join(dir, entry.name);
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try { isFile = statSync(fullPath).isFile(); } catch { continue; }
+    }
+    const relPath = toPosix(path.relative(root, fullPath));
+    if (!isFile || ig.ignores(relPath, false)) continue;
+    const realFile = await ensureInside(fullPath, authRoot, acc.notices, relPath || entry.name);
+    if (!realFile) return; // 越界 symlink：记 notice，本目录当作技能根已处理完
+    const { skill, notice } = skillFromFile(realFile);
+    if (notice) acc.notices.push(notice);
+    if (skill) {
+      if (acc.total + skill._bytes > MAX_TOTAL_BYTES) {
+        acc.notices.push(`技能总大小将超过 ${MAX_TOTAL_BYTES} 字节，已停止发现：${fullPath}`);
+        acc.stopped = true;
+        return;
+      }
+      if (acc.skills.length >= MAX_SKILLS) { markSkillsCapped(acc); return; }
+      if (acc.names.has(skill.name)) acc.notices.push(`技能重名，已跳过后一份：${skill.name}（${skill.filePath}）`);
+      if (!acc.names.has(skill.name)) {
+        acc.names.add(skill.name);
+        acc.total += skill._bytes;
+        const { _bytes, ...rest } = skill;
+        acc.skills.push(rest);
+      }
+    }
+    return; // 有 SKILL.md 不再递归
+  }
+
+  for (const entry of entries) {
+    if (acc.stopped || acc.skills.length >= MAX_SKILLS) return;
+    // 技能树内部仍跳过隐藏项；根上的 .pi / .agents / .claude 由 SKILL_DIRS 显式进入，不会走到这里
+    if (entry.name.startsWith(".")) continue;
+    if (entry.name === "node_modules") continue;
+    const fullPath = path.join(dir, entry.name);
+    let isDirectory = entry.isDirectory();
+    let isFile = entry.isFile();
+    if (entry.isSymbolicLink()) {
+      try {
+        const st = statSync(fullPath);
+        isDirectory = st.isDirectory();
+        isFile = st.isFile();
+      } catch { continue; }
+    }
+    const relPath = toPosix(path.relative(root, fullPath));
+    if (ig.ignores(relPath, isDirectory)) continue;
+    if (isDirectory) {
+      const realDir = await ensureInside(fullPath, authRoot, acc.notices, relPath || entry.name);
+      if (!realDir) continue; // 越界目录 symlink：跳过并已记 notice
+      await loadSkillsFromDirInternal(realDir, false, ig, root, acc, authRoot);
+      continue;
+    }
+    if (!isFile || !includeRootFiles || !entry.name.endsWith(".md")) continue;
+    const realFile = await ensureInside(fullPath, authRoot, acc.notices, relPath || entry.name);
+    if (!realFile) continue;
+    const { skill, notice } = skillFromFile(realFile);
+    if (notice) acc.notices.push(notice);
+    if (!skill) continue;
+    if (acc.total + skill._bytes > MAX_TOTAL_BYTES) {
+      acc.notices.push(`技能总大小将超过 ${MAX_TOTAL_BYTES} 字节，已停止发现：${fullPath}`);
+      acc.stopped = true;
+      return;
+    }
+    if (acc.skills.length >= MAX_SKILLS) { markSkillsCapped(acc); return; }
+    if (acc.names.has(skill.name)) acc.notices.push(`技能重名，已跳过后一份：${skill.name}（${skill.filePath}）`);
+    if (!acc.names.has(skill.name)) {
+      acc.names.add(skill.name);
+      acc.total += skill._bytes;
+      const { _bytes, ...rest } = skill;
+      acc.skills.push(rest);
+    }
+  }
+}
+
+async function resolveRootFile(root, name) {
+  const abs = path.join(root, name);
+  if (!existsSync(abs)) return null;
+  let st;
+  try { st = statSync(abs); } catch { return null; }
+  if (!st.isFile()) return null;
+  let real;
+  try { real = await realOf(abs); } catch (e) {
+    return { error: `无法解析路径：${name}（${e?.code ?? e?.message ?? e}）` };
+  }
+  if (!inside(real, root)) return { error: `目录外路径已拒绝：${name}（授权目录是 ${root}）` };
+  return { real, size: st.size };
+}
+
+/**
+ * 在授权根目录发现项目上下文。无路径入参；越界 symlink 拒绝。
+ * @returns {{ kind: 'project_context', contextFiles: {path,content}[], skills: object[], notices: string[] }}
+ */
+// @意图#R747(2026-11-06): 授权根增加 .claude/skills，兼容 Claude Code 项目技能目录
+// @意图#R745(2026-11-06): 从客户已授权目录加载项目规则并按需提供技能
+export async function discoverProjectContext(root) {
+  const notices = [];
+  const contextFiles = [];
+  let total = 0;
+
+  for (const name of AGENTS_CANDIDATES) {
+    const got = await resolveRootFile(root, name);
+    if (!got) continue;
+    if (got.error) { notices.push(got.error); break; }
+    if (got.size > MAX_FILE_BYTES) {
+      notices.push(`${name} 超过 ${MAX_FILE_BYTES} 字节，未注入项目规则（避免撑爆提示）`);
+      break;
+    }
+    if (total + got.size > MAX_TOTAL_BYTES) {
+      notices.push(`${name} 会使总大小超过 ${MAX_TOTAL_BYTES} 字节，未注入项目规则`);
+      break;
+    }
+    let raw;
+    try { raw = await fs.readFile(got.real, "utf8"); } catch (e) {
+      notices.push(`无法读取 ${name}：${e?.message ?? e}`);
+      break;
+    }
+    const content = stripBom(raw);
+    const bytes = Buffer.byteLength(content, "utf8");
+    if (bytes > MAX_FILE_BYTES) {
+      notices.push(`${name} 超过 ${MAX_FILE_BYTES} 字节，未注入项目规则（避免撑爆提示）`);
+      break;
+    }
+    contextFiles.push({ path: got.real, content });
+    total += bytes;
+    break; // 只取最高优先级一份
+  }
+
+  const acc = { skills: [], notices, names: new Set(), visited: new Set(), total, stopped: false, capped: false };
+  for (const rel of SKILL_DIRS) {
+    if (acc.stopped) break;
+    const dir = path.join(root, rel);
+    if (!existsSync(dir)) continue;
+    let realDir;
+    try { realDir = await realOf(dir); } catch (e) {
+      notices.push(`无法解析技能目录 ${rel}：${e?.code ?? e?.message ?? e}`);
+      continue;
+    }
+    if (!inside(realDir, root)) {
+      notices.push(`目录外路径已拒绝：${rel}（授权目录是 ${root}）`);
+      continue;
+    }
+    const ig = createIgnoreMatcher();
+    // authRoot 用授权根（非 skills 子根），越界 symlink 相对整棵授权树判断
+    await loadSkillsFromDirInternal(realDir, true, ig, realDir, acc, root);
+  }
+
+  return {
+    kind: "project_context",
+    contextFiles,
+    skills: acc.skills,
+    notices,
+  };
+}
+
+/** ops 入口：忽略任何路径参数，只扫授权根。 */
+// @意图#R747(2026-11-06): 授权根增加 .claude/skills，兼容 Claude Code 项目技能目录
+// @意图#R745(2026-11-06): 从客户已授权目录加载项目规则并按需提供技能
+export async function opContextSnapshot(_args, root) {
+  return discoverProjectContext(root);
+}

package/runner.mjs

@@ -510,12 +510,22 @@ export const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } ca
  * 拿锁：别的活着的进程拿着就返回 { ok: false, pid, launchd }；否则写上自己（600）返回 { ok: true, release }。
  * 进程死了留下的旧锁直接覆盖。
  */
+/** R732：a 比 b 新（只比 x.y.z；带预发布后缀的算旧一点；b 不是版本号 = 很旧） */
+export function newerVersion(a, b) {
+  const re = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/;
+  const pa = re.exec(String(a ?? "")); const pb = re.exec(String(b ?? ""));
+  if (!pa) return false;
+  if (!pb) return true;
+  for (let i = 1; i <= 3; i++) { const d = Number(pa[i]) - Number(pb[i]); if (d) return d > 0; }
+  return !String(a).includes("-") && String(b).includes("-");
+}
+// @意图#R732(2026-11-04): 锁里记版本号；拿不到锁时告诉调用方对方是不是旧版本（older：锁里没版本号或比我旧），旧的由 runStart 顶掉
 // @意图#R666(2026-10-29): 防互踢（king 定必须做）：开机自启的在后台跑着，再在终端里 start 就提示「已经在后台连着」退出，不再两个互相顶
-export function takeLock(file = configPath(), { pid = process.pid, launchd = process.env.AGENT_RUNNER_LAUNCHD === "1" } = {}) {
+export function takeLock(file = configPath(), { pid = process.pid, launchd = process.env.AGENT_RUNNER_LAUNCHD === "1", version = RUNNER_VERSION } = {}) {
   const cur = readLock(file);
-  if (cur && cur.pid !== pid && pidAlive(cur.pid)) return { ok: false, pid: cur.pid, launchd: !!cur.launchd };
+  if (cur && cur.pid !== pid && pidAlive(cur.pid)) return { ok: false, pid: cur.pid, launchd: !!cur.launchd, version: cur.version ?? null, older: newerVersion(version, cur.version) };
   mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  writeFileSync(lockPath(file), `${JSON.stringify({ pid, launchd, started_at: new Date().toISOString() })}\n`, { mode: 0o600 });
+  writeFileSync(lockPath(file), `${JSON.stringify({ pid, launchd, version, started_at: new Date().toISOString() })}\n`, { mode: 0o600 });
   return { ok: true, release: () => { if (readLock(file)?.pid === pid) rmSync(lockPath(file), { force: true }); } };
 }
 
@@ -532,6 +542,7 @@ async function autostartOffQuietly(file, deps) {
   } catch { return false; }
 }
 
+// @意图#R732(2026-11-04): 拿锁时发现拿着锁的是旧版本（或没记版本的老运行器）就先让它退出再接管，客户升级后不用自己停旧进程；同版本或更新的照旧提示退出
 // @意图#R666(2026-10-29): 先拿锁（后台已在跑就提示退出 0）；开机自启时启动前日志超 5MB 清空、配置坏了/没配对也退出 0（不让 launchd 反复拉起）；
 // 结束一律退出码 0（Ctrl-C、被网页断开、令牌失效、被顶掉），被断开 / 令牌失效时顺手关掉自启
 // @意图#R663(2026-10-29): 前台跑 start，Ctrl-C 断开（pair --start 和 start 共用）
@@ -544,7 +555,14 @@ async function runStart(prog = progName(), deps = {}) {
     if (background) { console.error(explainError(e)); process.exit(0); }
     throw e;
   }
-  const lock = takeLock(file);
+  let lock = takeLock(file);
+  if (!lock.ok && lock.older) {
+    // R732：后台是旧版本（升级前起的那个还在内存里）：让它退出，我来接
+    const old = lock;
+    await stopPid(old.pid);
+    lock = takeLock(file);
+    if (lock.ok) say(`已顶掉旧版本 ${old.version ?? "（0.2.1 以前）"}（进程 ${old.pid}），现在是 ${RUNNER_VERSION}`);
+  }
   if (!lock.ok) {
     console.log(`已经在后台连着，不用再开（进程 ${lock.pid}${lock.launchd ? "，开机自启起的" : ""}）。要停掉它：${prog} stop`);
     process.exit(0);
@@ -586,22 +604,40 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 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);
+  await stopPid(l.pid);
   return l;
 }
+/** R732：发 SIGTERM 让它正常退出（退出码 0，launchd 不会再拉起），等最多 5 秒 */
+async function stopPid(pid) {
+  try { process.kill(pid, "SIGTERM"); } catch { /* 已经没了 */ }
+  for (let i = 0; i < 50 && pidAlive(pid); i++) await sleep(100);
+}
+/** R732：等新起的后台运行器拿到锁（锁里是 version 且进程活着），最多 ms 毫秒；拿到返回锁信息，超时 null */
+export async function waitNewHolder(file, { version = RUNNER_VERSION, ms = 10000, step = 200 } = {}) {
+  for (let t = 0; ; t += step) {
+    const l = readLock(file);
+    if (l && l.pid !== process.pid && l.version === version && pidAlive(l.pid)) return l;
+    if (t >= ms) return null;
+    await sleep(step);
+  }
+}
 
 const here = () => path.dirname(fileURLToPath(import.meta.url));
 // @意图#R666(2026-10-29): 开启自启：前台有一个在跑就先停掉它（不然后台那个起来就因为锁退出了），再交给 autostart.mjs（复制自己、写 plist、加载）
 // @意图#R725(2026-11-03): Windows 走计划任务（autostartOnWindows），Mac 走 launchd。提示里的「这台 Mac」按平台写。
+// @意图#R732(2026-11-04): 不管拿着锁的是终端里的还是开机自启起的（包括别的标签起的旧版本），一律先停掉；装好后等新版本真的拿到锁才报「已设开机自启」，没接上就说清楚、给日志位置
 async function turnAutostartOn(file, prog, deps = {}) {
-  const held = readLock(file);
-  if (held && !held.launchd) await stopHolder(file);
+  await stopHolder(file);
   const platform = deps.platform ?? process.platform;
   const r = platform === "win32"
     ? await autostartOnWindows({ configFile: file, version: RUNNER_VERSION, srcDir: here(), execPath: deps.execPath, schtasks: deps.schtasks })
     : await autostartOn({ configFile: file, version: RUNNER_VERSION, srcDir: here(), launchctl: deps.launchctl, platform });
   const where = platform === "win32" ? "这台电脑" : "这台 Mac";
+  const got = await (deps.waitNewHolder ?? waitNewHolder)(file, { version: RUNNER_VERSION });
+  if (!got) {
+    console.log(`开机自启已经装好（${RUNNER_VERSION}），但等了 10 秒后台还没连上。可以看日志找原因：${r.log}\n过一会儿可以再运行一次：${prog} autostart on`);
+    return r;
+  }
   console.log(`已设开机自启：以后登录${where}会自动连上，不用开终端。现在已经在后台连着，可以关掉这个终端窗口了。\n日志：${r.log}\n关掉开机自启：${prog} autostart off`);
   return r;
 }