@aiti-ai/aiti-cmd 0.0.0-stage → 0.1.9

package/skills/command-fill/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: command-fill
+title: AI 帮我填命令表单
+placeholder: 描述你想填的命令字段…（需从命令详情弹窗的 AI 按钮唤起）
+outputs:
+  format: json-obj
+  schema:
+    name: 命令名（简短动宾）
+    cmd: shell 命令（必填）
+    tags: 标签数组（可选）
+action:
+  type: fill
+  fields:
+    - key: name
+      label: 名称
+    - key: cmd
+      label: 命令
+    - key: tags
+      label: 标签
+---
+
+# command-fill · 填命令表单
+
+你是 aiti-cmd 表单助手。把 AI 结果直接操作到用户打开的「命令详情」弹窗表单里（不是只给 JSON 让用户自己贴）。
+
+## 步骤
+
+1. 先调工具 `self_ui`（缺省目标 AI 主窗口 xxx/ai）扫描当前打开的弹窗，拿到弹窗标题与字段清单（label/selector/type/当前值）——确认弹窗确实开着、字段名与你将输出的一致。
+2. 按用户要求确定各字段的值。
+3. 调工具 `form_fill` 把值填入弹窗表单：`fields` 传 `[{selector 或 label, value}]`（能用 label 就用 self_ui 返回的 label，selector 更准就用 selector）；一次填完或分多次都行。
+4. 返回里的 `filled` 表示填成功几个字段；若 `missed>0`，说明有字段没定位到，再 self_ui 确认实际字段名/选择器后重试。
+5. 需要提交时调 form_fill 的 `button` 参数（如「保存」「确定」）点击，或 page_exec 点按钮。
+6. 完成后用 self_ui 或 page_exec 抽查确认值已填入。
+
+## 输出格式（务必遵守）
+
+无论工具是否成功，**最后一行输出 JSON**：
+
+```json
+{ "filled": { "字段名": "实际填入的值" }, "note": "一两句过程说明（中文）" }
+```
+
+- `filled`: 真正写入弹窗的字段名 → 值
+- 若工具链不可用未填入，`filled` 传空对象 `{}` 并在 `note` 说明，让前端用本地回填兜底
+
+不要输出 JSON 代码块之外的无关文本。

package/skills/command-fix/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: command-fix
+title: AI 优化/修复命令
+placeholder: 描述要改哪条命令、怎么改（如：把打包命令加上 git 推送）…
+outputs:
+  format: json-obj
+  schema:
+    id: 命令 id（从列表读取）
+    name: 命令名
+    cmd: 改进后的命令（必填）
+    tags: 标签数组
+    confirm: 危险命令需确认（布尔）
+action:
+  type: api
+  method: PUT
+  path: /api/extensions/aiti-cmd/commands/{id}
+  mapping:
+    id: id
+    name: name
+    cmd: cmd
+    tags: tags
+    confirm: confirm
+---
+
+# command-fix · 优化命令
+
+你是 aiti-cmd 命令优化助手。用户想改进某条已收藏的命令。
+
+## 步骤
+
+1. 先用工具读取命令列表：`GET {basePath}/api/extensions/aiti-cmd/commands`（返回 `{ok, commands:[{id,name,cmd,tags,confirm}]}`）
+2. 找到用户指的那条命令的 `id`
+3. 按用户要求改进（如加参数、优化逻辑、更清晰的输出）
+
+## 输出格式
+
+只输出完整 JSON，不闲聊：
+
+```json
+{
+  "id": "命令 id（必须来自列表）",
+  "name": "命令名",
+  "cmd": "改进后的 shell 命令",
+  "tags": ["标签"],
+  "confirm": false
+}
+```
+
+前端会通过 `PUT {basePath}/api/extensions/aiti-cmd/commands/{id}` 更新（path 模板用 id 替换）。

package/skills/command-run/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: command-run
+title: AI 帮我执行命令
+placeholder: 描述要执行什么（如：起一个 watch 模式的前端构建，我要在面板里看日志）…
+outputs:
+  format: json-obj
+  schema:
+    command: 要执行的 shell 命令（必填）
+    cwd: 工作目录（可选）
+    name: 会话显示名（可选，如「前端 watch」）
+    ttlMs: 会话保留时长毫秒（可选，长驻任务建议 86400000）
+---
+
+# command-run · 执行命令
+
+你是 aiti-cmd 执行助手，帮用户在后端 PTY runner 里起命令会话。**调用工具 `aiti_cmd_run` 执行**（不要用自带 bash——本 skill 的价值是常驻会话 + 实时面板 + 全程审计）。只输出简短说明，不闲聊。
+
+## 执行
+
+调用工具 `aiti_cmd_run`，参数：
+
+```json
+{
+  "command": "shell 命令（必填）",
+  "cwd": "工作目录（可选）",
+  "name": "会话显示名（可选）",
+  "ttlMs": 86400000
+}
+```
+
+- **适用**：长驻/交互式/用户要在 ⚡命令 面板围观的任务（dev server、watch、日志跟随、登录 PTY）
+- **不适用**：要立刻拿输出的一次性命令（直接用自带 bash 更快）
+
+## 安全（必须遵守）
+
+1. 危险命令（rm -rf、git push --force、chmod -R 777、DROP TABLE 等）命中词库时工具会**拒绝并要求二次确认**——此时你必须把**命令原文**完整展示给用户，**获得明确同意后**才能以 `confirm: true` 重调；用户未同意就停止。
+2. 不确定后果的命令先向用户说明再执行，不要默默跑。
+
+## 结果告知
+
+执行成功后告诉用户：会话 id、去 ⚡命令 面板看实时日志；需要停止在面板里点 ⏹ 终止。

package/skills/index.json

@@ -0,0 +1,6 @@
+[
+  "command-create",
+  "command-fill",
+  "command-fix",
+  "command-run"
+]

package/store.ts

@@ -0,0 +1,228 @@
+/**
+ * aiti-cmd · 常用命令存储（~/.pi/web/data/aiti-cmd/config/commands.json）
+ *
+ * v2：树形分组。结构 { version, groups: GroupItem[], commands: CommandItem[] }
+ *   - groups：树（parentId 引用，根 parentId=null）
+ *   - commands.groupId：所属分组（null=未分组）
+ * CRUD + 原子写（临时文件 + rename）；{xxx} 占位符自动提取。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface GroupItem {
+  id: string;
+  name: string;
+  parentId: string | null;
+  sort: number;
+  createdAt: number;
+}
+
+export interface CommandItem {
+  id: string;
+  name: string;
+  cmd: string;
+  cwd?: string;
+  tags?: string[];
+  env?: Record<string, string>;
+  confirm?: boolean;
+  /** 从 cmd 提取的占位符（运行前填参数） */
+  params?: string[];
+  /** 所属分组（null=未分组） */
+  groupId?: string | null;
+  /** 沙箱模式：none=无沙箱（默认）；bwrap-ro=只读+工作目录可写；bwrap-offline=只读+断网；bwrap-tmp=临时可写盘（退出即丢） */
+  sandbox?: "none" | "bwrap-ro" | "bwrap-offline" | "bwrap-tmp";
+  /** 是否参与 aiti-ai-input 智能提示（suggest 联想/补全的来源；false=不提示；缺省/true=提示，默认开）
+   * 自动来源（source=ai-message/clipboard）未显式指定时默认 false（系统创建的条目不污染提示来源） */
+  suggest?: boolean;
+  createdAt: number;
+  lastRunAt?: number;
+  runCount?: number;
+  source?: "manual" | "ai-message" | "clipboard";
+}
+
+/** 合法沙箱模式（存储白名单；未知值一律丢弃→undefined） */
+export const SANDBOX_MODES = ["none", "bwrap-ro", "bwrap-offline", "bwrap-tmp"] as const;
+export type SandboxMode = (typeof SANDBOX_MODES)[number];
+export function normSandbox(v: unknown): SandboxMode | undefined {
+  return (SANDBOX_MODES as readonly string[]).includes(String(v)) ? (v as SandboxMode) : undefined;
+}
+
+/** 提取 {xxx} 占位符（排除 ${var} shell 变量） */
+export function extractParams(cmd: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const re = /\{([a-zA-Z_][\w.-]*)\}/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(cmd))) {
+    if (!seen.has(m[1])) { seen.add(m[1]); out.push(m[1]); }
+  }
+  return out;
+}
+
+export function createStore(configDir: string) {
+  const file = path.join(configDir, "commands.json");
+  fs.mkdirSync(configDir, { recursive: true });
+
+  function load(): { groups: GroupItem[]; commands: CommandItem[] } {
+    try {
+      if (!fs.existsSync(file)) return { groups: [], commands: [] };
+      const data = JSON.parse(fs.readFileSync(file, "utf8"));
+      const groups = Array.isArray(data.groups) ? data.groups : [];
+      const commands = Array.isArray(data.commands) ? data.commands : [];
+      return { groups, commands };
+    } catch {
+      return { groups: [], commands: [] };
+    }
+  }
+  function save(groups: GroupItem[], commands: CommandItem[]) {
+    const tmp = file + ".tmp";
+    fs.writeFileSync(tmp, JSON.stringify({ version: 2, groups, commands }, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  }
+  function genId(prefix: string) {
+    return prefix + "_" + randomBytes(6).toString("hex");
+  }
+
+  // 存量迁移：自动来源（非 manual）且未显式设置 suggest 的命令 → 默认不参与智能提示（一次）
+  function migrateAutoSuggest() {
+    const { groups, commands } = load();
+    let changed = false;
+    for (const c of commands) {
+      if (c.suggest === undefined && c.source && c.source !== "manual") { c.suggest = false; changed = true; }
+    }
+    if (changed) save(groups, commands);
+  }
+  migrateAutoSuggest();
+
+  // ---------- 命令 ----------
+  function list(): CommandItem[] {
+    return load().commands.sort((a, b) => (b.lastRunAt || b.createdAt) - (a.lastRunAt || a.createdAt));
+  }
+  function get(id: string): CommandItem | null {
+    return load().commands.find((c) => c.id === id) || null;
+  }
+  function create(input: Partial<CommandItem> & { name: string; cmd: string }): CommandItem {
+    const { groups, commands } = load();
+    const item: CommandItem = {
+      id: genId("c"),
+      name: String(input.name || input.cmd).trim(),
+      cmd: input.cmd,
+      cwd: input.cwd || undefined,
+      tags: input.tags || [],
+      env: input.env || undefined,
+      confirm: input.confirm ?? false,
+      params: extractParams(input.cmd),
+      groupId: input.groupId || null,
+      sandbox: normSandbox(input.sandbox),
+      // 显式 suggest 优先；缺省时手动创建的默认开、自动来源（ai-message/clipboard）默认关
+      suggest: input.suggest !== undefined ? input.suggest !== false : (!input.source || input.source === "manual"),
+      createdAt: Date.now(),
+      lastRunAt: undefined,
+      runCount: 0,
+      source: input.source || "manual",
+    };
+    commands.push(item);
+    save(groups, commands);
+    return item;
+  }
+  function update(id: string, patch: Partial<CommandItem>): CommandItem | null {
+    const { groups, commands } = load();
+    const idx = commands.findIndex((c) => c.id === id);
+    if (idx < 0) return null;
+    const clean = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+    // 防御清洗：tags 可能以逗号字符串传入（客户端表单原始值）——统一成 string[]
+    if (typeof clean.tags === "string") clean.tags = (clean.tags as string).split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+    if (clean.cwd === "") clean.cwd = undefined;
+    const next = { ...commands[idx], ...clean, id };
+    if (clean.cmd !== undefined) next.params = extractParams(next.cmd);
+    if (clean.name === undefined) next.name = next.name || next.cmd;
+    if (clean.groupId !== undefined) next.groupId = clean.groupId || null;
+    if (clean.sandbox !== undefined) next.sandbox = normSandbox(clean.sandbox);
+    next.cwd = next.cwd || undefined;
+    commands[idx] = next;
+    save(groups, commands);
+    return next;
+  }
+  function touchRun(id: string): void {
+    const { groups, commands } = load();
+    const idx = commands.findIndex((c) => c.id === id);
+    if (idx < 0) return;
+    commands[idx].lastRunAt = Date.now();
+    commands[idx].runCount = (commands[idx].runCount || 0) + 1;
+    save(groups, commands);
+  }
+  function remove(id: string): boolean {
+    const { groups, commands } = load();
+    const idx = commands.findIndex((c) => c.id === id);
+    if (idx < 0) return false;
+    commands.splice(idx, 1);
+    save(groups, commands);
+    return true;
+  }
+
+  // ---------- 分组（树） ----------
+  function listGroups(): GroupItem[] {
+    return load().groups;
+  }
+  function createGroup(name: string, parentId: string | null): GroupItem {
+    const { groups, commands } = load();
+    if (parentId && !groups.some((g) => g.id === parentId)) parentId = null;
+    const g: GroupItem = { id: genId("g"), name: String(name || "新分组").trim(), parentId, sort: 0, createdAt: Date.now() };
+    groups.push(g);
+    save(groups, commands);
+    return g;
+  }
+  function updateGroup(id: string, patch: Partial<GroupItem>): GroupItem | null {
+    const { groups, commands } = load();
+    const idx = groups.findIndex((g) => g.id === id);
+    if (idx < 0) return null;
+    const clean = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+    let parentId = clean.parentId !== undefined ? clean.parentId : groups[idx].parentId;
+    // 防环：不能把分组移到自己的子孙下
+    if (parentId) {
+      const desc = new Set<string>();
+      const walk = (gid: string) => {
+        for (const g of groups) if (g.parentId === gid && !desc.has(g.id)) { desc.add(g.id); walk(g.id); }
+      };
+      walk(id);
+      if (desc.has(parentId)) parentId = groups[idx].parentId;
+    }
+    groups[idx] = { ...groups[idx], ...clean, id, parentId };
+    save(groups, commands);
+    return groups[idx];
+  }
+  /** 删除分组（级联：子孙分组一并删；其下命令移入未分组） */
+  function removeGroup(id: string): boolean {
+    const { groups, commands } = load();
+    if (!groups.some((g) => g.id === id)) return false;
+    const doomed = new Set<string>();
+    const walk = (gid: string) => {
+      for (const g of groups) if (g.parentId === gid && !doomed.has(g.id)) { doomed.add(g.id); walk(g.id); }
+    };
+    doomed.add(id);
+    walk(id);
+    const rest = groups.filter((g) => !doomed.has(g.id));
+    const nextCommands = commands.map((c) => (c.groupId && doomed.has(c.groupId) ? { ...c, groupId: null } : c));
+    save(rest, nextCommands);
+    return true;
+  }
+
+  /** 分组路径（用于 UI 显示/选择），如 "构建 / 前端" */
+  function groupPath(id: string | null | undefined): string {
+    if (!id) return "未分组";
+    const { groups } = load();
+    const parts: string[] = [];
+    let cur = groups.find((g) => g.id === id);
+    let guard = 0;
+    while (cur && guard++ < 20) {
+      parts.unshift(cur.name);
+      cur = cur.parentId ? groups.find((g) => g.id === cur!.parentId) : undefined;
+    }
+    return parts.join(" / ") || "未分组";
+  }
+
+  return { list, get, create, update, touchRun, remove, listGroups, createGroup, updateGroup, removeGroup, groupPath };
+}
+
+export type CommandStore = ReturnType<typeof createStore>;

package/tools/build-client.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * aiti-cmd · 构建 client bundle（esbuild 打包 xterm.js + fit addon → dist/aiti-cmd-client.mjs）
+ *
+ * 用法：node tools/build-client.mjs
+ */
+import { createRequire } from "node:module";
+import { readFileSync, writeFileSync } from "node:fs";
+const require = createRequire(import.meta.url);
+const { build } = require("esbuild");
+
+// esbuild 从仓库根 node_modules 解析（node 向上查找）
+function resolveEsbuild() {
+  try { return require("esbuild"); } catch {}
+  throw new Error("esbuild 未找到——请在仓库根 npm i -D esbuild");
+}
+
+await resolveEsbuild().build({
+  entryPoints: ["client/src/index.js"],
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: ["es2020"],
+  loader: { ".css": "text" },
+  outfile: "dist/aiti-cmd-client.mjs",
+  logLevel: "warning",
+  banner: { js: "// aiti-cmd client bundle — built by tools/build-client.mjs (esbuild). Do not edit." },
+});
+console.log("[aiti-cmd] client bundle → dist/aiti-cmd-client.mjs");
+
+// post-build patch：xterm 6.0.0 RenderService.dimensions getter 对 _renderer.value（Optional）
+// 无空值防护——terminal dispose 后（renderer 已清）排在 RenderDebouncer 里的 rAF 回调
+// 仍会执行 Viewport._sync → 读 _renderService.dimensions → 崩
+// 「Cannot read properties of undefined (reading 'dimensions')」（上游 master 仍未修，无补丁版）。
+// 修法：getter 加 ?.；Viewport _sync/_handleScroll 的 !this._renderService 守卫追加 .dimensions 判空。
+// 属性名不被 esbuild 混淆，匹配对压缩产物稳定；替换次数断言保证上游变化时 fail loudly 不静默失效。
+{
+  const outfile = "dist/aiti-cmd-client.mjs";
+  let s = readFileSync(outfile, "utf8");
+  const A = "return this._renderer.value.dimensions;";
+  const A2 = "return this._renderer.value?.dimensions;";
+  const B = "!this._renderService ||";
+  const B2 = "!this._renderService?.dimensions ||";
+  const cA = s.split(A).length - 1, cB = s.split(B).length - 1;
+  if (cA !== 1 || cB !== 2) {
+    console.error(`[aiti-cmd][patch] 匹配数不符：getter×${cA}（期望1） guard×${cB}（期望2）——xterm 上游形态变了，人工核对后调整 patch，产物保持未写`);
+    process.exit(1);
+  }
+  s = s.split(A).join(A2).split(B).join(B2);
+  writeFileSync(outfile, s);
+  console.log("[aiti-cmd][patch] xterm dimensions 空值防护已应用（getter×1, guard×2）");
+}

package/tools/deploy.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * aiti-cmd · 部署到 ~/.pi/web/extensions/ 与 ~/.pi/web-dev/extensions/（pi-web 双实例扩展目录）
+ *
+ * 步骤：
+ *   1) 构建 client bundle（tools/build-client.mjs，esbuild 打包 xterm.js）
+ *   2) 拷贝服务端源码（index/runner/store/recognize/audit）→ 两个扩展目录
+ *   3) 拷贝 client bundle → 两个扩展目录 client/
+ *   4) package.json（dependencies 声明 node-pty 等）拷入 + 清理扩展本地 node_modules 残留
+ *   5) 提交部署状态到扩展 git 仓库（~/.pi/web/extensions/）（失败不影响部署）
+ *   6) 通知双实例 extman reconcile 共享依赖 → <webRoot>/node_modules（aiti-extman ops）
+ *   7) macOS：node-pty spawn-helper 补可执行位（共享根/本地两处都探测）
+ *   8) 双实例热重载
+ *
+ * 用法：node tools/deploy.mjs
+ * 生效：POST /api/extensions/reload；client no-store 刷新页面即新
+ */
+import { copyFileSync, mkdirSync, existsSync, cpSync, chmodSync, readdirSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+import { deployCommit } from "../../_shared/deploy-commit.mjs";
+import { copyIcons } from "../../_shared/ext-icons-deploy.mjs";
+import { notifyReconcile } from "../../_shared/reconcile-deps.mjs";
+
+// client TS 残留检查（.mjs 里是合法 JS 语法检查不报、运行时必炸；FAIL 即部署失败）
+{
+  const { checkClientDir } = await import("../../_shared/check-client.mjs");
+  checkClientDir(fileURLToPath(new URL("../client", import.meta.url)), { log: (m) => console.log("[deploy] " + m) });
+}
+
+const root = resolve(import.meta.dirname, ".."); // pi-web-ext/aiti-cmd
+const targets = [
+  resolve(homedir(), ".pi", "web", "extensions", "aiti-cmd"),
+  resolve(homedir(), ".pi", "web-dev", "extensions", "aiti-cmd"),
+];
+const extRepo = resolve(targets[0], "..");
+
+// 1) 构建 client
+console.log("[deploy] 构建 client bundle…");
+execSync("node " + resolve(root, "tools/build-client.mjs"), { cwd: root, stdio: "inherit" });
+
+// 2) 服务端源码 + 3) client bundle（两个实例目录）
+for (const extDir of targets) {
+  mkdirSync(extDir, { recursive: true });
+  for (const f of ["index.ts", "icon.svg", "runner.ts", "store.ts", "recognize.ts", "audit.ts", "pi-commands.ts"]) {
+    copyFileSync(resolve(root, f), resolve(extDir, f));
+    console.log("[deploy] 源码 → " + resolve(extDir, f));
+  }
+  const clientDir = resolve(extDir, "dist");
+  mkdirSync(clientDir, { recursive: true });
+  copyFileSync(resolve(root, "dist/aiti-cmd-client.mjs"), resolve(clientDir, "aiti-cmd-client.mjs"));
+  console.log("[deploy] client → " + resolve(clientDir, "aiti-cmd-client.mjs"));
+  // skills/ 帮助点目录（pi skills 标准：index.json + 每 skill 一个 SKILL.md）
+  const skillSrc = resolve(root, "skills");
+  if (existsSync(skillSrc)) {
+    const skillDest = resolve(extDir, "skills");
+    mkdirSync(skillDest, { recursive: true });
+    cpSync(skillSrc, skillDest, { recursive: true });
+    console.log("[deploy] skills → " + skillDest);
+  }
+}
+
+// 4) 运行时依赖（node-pty / command-exists / shell-quote）：package.json 一并部署（registry 读
+//    name/version/soul，dependencies 就是共享依赖的声明源）。依赖本体由 extman reconcile 统一装进
+//    <webRoot>/node_modules（jiti 从扩展目录向上解析自动命中，见步骤 6）——不再 npm i --prefix 装进
+//    扩展目录（旧方式 --no-save 还漏声明 node-pty）；本地 node_modules 残留每次部署清理，让解析稳定
+//    走共享根。不能裸 npm i：部署目录若无 package.json，npm 会向上命中 ~/package.json「假成功」，
+//    依赖全装进家目录 node_modules（历史踩坑）
+for (const extDir of targets) {
+  copyFileSync(resolve(root, "package.json"), resolve(extDir, "package.json"));
+  const legacyNm = resolve(extDir, "node_modules");
+  if (existsSync(legacyNm)) {
+    rmSync(legacyNm, { recursive: true, force: true });
+    console.log("[deploy] 清理扩展本地 node_modules（依赖走共享根）→ " + legacyNm);
+  }
+}
+
+// 5) 部署 commit（扩展 git 仓库；无变更跳过，失败不影响部署）
+
+// 图标文件拷贝（icon: "icons/<name>.svg" → 宿主加载时内嵌；库在 _shared/icons/）
+for (const t of targets) copyIcons(resolve(t, "icons"), ["terminal"], { log: (m2) => console.log(m2) });
+
+deployCommit({ repo: extRepo, name: "aiti-cmd", paths: ["aiti-cmd"], ident: true, log: (m) => console.log("[deploy] " + m) });
+
+// 6) 通知双实例 extman reconcile 共享依赖（依赖装进各自 <webRoot>/node_modules；await 等完成再 chmod/reload）。
+//    允许失败：extman 未就绪/实例不可达仅提示，不影响部署退出码（下次安装时自动对齐）
+await notifyReconcile();
+
+// 7) macOS：node-pty prebuild 的 spawn-helper 必须带可执行位（解包/拷贝链路可能丢 +x，
+//    丢失时 helper 起不来、所有 pty spawn 报 "posix_spawnp failed."）；非 darwin prebuild 不存在则空转。
+//    共享根（<webRoot>/node_modules，本部署刚 reconcile 出来）与扩展本地（残留兜底）两处都探测
+for (const nm of [...targets, ...targets.map((t) => resolve(t, "..", ".."))].map((d) => resolve(d, "node_modules"))) {
+  const prebuilds = resolve(nm, "node-pty", "prebuilds");
+  if (!existsSync(prebuilds)) continue;
+  for (const d of readdirSync(prebuilds)) {
+    if (!d.startsWith("darwin-")) continue;
+    const helper = resolve(prebuilds, d, "spawn-helper");
+    if (existsSync(helper)) { chmodSync(helper, 0o755); console.log("[deploy] chmod +x " + helper); }
+  }
+}
+
+console.log("[deploy] 完成。生效：POST /api/extensions/reload（或重启 pi-web）；client 刷新页面即新");
+
+// ── 双实例热重载（basePath 双 env 按机器设值）——允许失败：服务未启动/共享模块缺失仅提示，不影响 deploy 退出码 ──
+try {
+  const { reloadInstances } = await import("../../_shared/reload-instances.mjs");
+  await reloadInstances();
+} catch (e) {
+  console.log("[deploy] 自动 reload 未执行（" + String((e && e.message) || e) + "）— 需手动 POST /api/extensions/reload");
+}
+
+// ── dev-pack（方案 §3.2：源码+构建工具+AGENTS.md 直达部署目录，AI 可现场直改）——允许失败，不影响 deploy 退出码 ──
+try {
+  const { packDevPack } = await import("../../_shared/dev-pack.mjs");
+  packDevPack({ extRoot: resolve(import.meta.dirname, ".."), log: (m) => console.log("[deploy] " + m) });
+} catch (e) {
+  console.log("[deploy] dev-pack 未执行（" + String((e && e.message) || e) + "）");
+}