pi-web-ui 0.94.1 → 0.95.0

package/dist/server/plugin-api-catalog.js

@@ -0,0 +1,296 @@
+export const PLUGIN_API_CATALOG_VERSION = 1;
+/** 每个 slot 的 manifest 最小例子（与 parseUiContributions 同口径，别名已展开写法也收）。 */
+export const SLOT_EXAMPLES = {
+    "topbar.primary": `{ "topbar": [{ "id": "inbox", "label": "收件箱", "kind": "action", "action": "my:open" }] }`,
+    "topbar.overflow": `{ "topbar.more": [{ "id": "about", "label": "关于", "kind": "action", "action": "my:about" }] }`,
+    bottombar: `{ "ui": { "bottombar": [{ "id": "st", "label": "状态", "kind": "action", "action": "my:st" }] } }`,
+    "composer.leading": `{ "ui": { "composer.leading": [{ "id": "m", "label": "＋", "kind": "action", "action": "my:m" }] } }`,
+    "composer.actions": `{ "composer": [{ "id": "pick", "label": "拾取", "kind": "action", "action": "my:pick" }] }`,
+    "message.actions": `{ "message": [{ "id": "send", "label": "转存", "kind": "action", "action": "my:send" }] }`,
+    "rightpanel.tabs": `{ "rightpanel": [{ "id": "mail", "label": "邮件", "kind": "view" }] }`,
+    "contextmenu.topbar": `{ "ui": { "contextmenu.topbar": [{ "id": "m", "label": "顶栏菜单", "kind": "action", "action": "my:m" }] } }`,
+    "contextmenu.message": `{ "ui": { "contextmenu.message": [{ "id": "m", "label": "消息菜单", "kind": "action", "action": "my:m" }] } }`,
+    "contextmenu.session": `{ "ui": { "contextmenu.session": [{ "id": "m", "label": "会话菜单", "kind": "action", "action": "my:m" }] } }`,
+    "contextmenu.file": `{ "contextmenu.file": [{ "id": "mail", "label": "发到邮箱", "kind": "action", "action": "my:send" }] }`,
+    "contextmenu.toolcall": `{ "ui": { "contextmenu.toolcall": [{ "id": "m", "label": "工具菜单", "kind": "action", "action": "my:m" }] } }`,
+    "settings.pages": `{ "settings": [{ "id": "conf", "label": "邮箱设置", "kind": "page" }] }`,
+    "leftpanel.sessions": `{ "ui": { "leftpanel.sessions": [{ "id": "m", "label": "会话区", "kind": "action", "action": "my:m" }] } }`,
+    "chat.header": `{ "ui": { "chat.header": [{ "id": "m", "label": "会话题头", "kind": "action", "action": "my:m" }] } }`,
+    "chat.empty": `{ "ui": { "chat.empty": [{ "id": "m", "label": "空态", "kind": "action", "action": "my:m" }] } }`,
+    "file.preview.toolbar": `{ "ui": { "file.preview.toolbar": [{ "id": "m", "label": "预览工具", "kind": "action", "action": "my:m" }] } }`,
+    "terminal.toolbar": `{ "ui": { "terminal.toolbar": [{ "id": "m", "label": "终端工具", "kind": "action", "action": "my:m" }] } }`,
+    "scm.toolbar": `{ "ui": { "scm.toolbar": [{ "id": "m", "label": "SCM 工具", "kind": "action", "action": "my:m" }] } }`,
+    "goalbar.actions": `{ "ui": { "goalbar.actions": [{ "id": "m", "label": "目标条", "kind": "action", "action": "my:m" }] } }`,
+    "notice.actions": `{ "ui": { "notice.actions": [{ "id": "m", "label": "通知动作", "kind": "action", "action": "my:m" }] } }`,
+    "modal.dialog": `{ "modal": [{ "id": "m", "label": "弹窗", "kind": "action", "action": "my:m" }] }`,
+};
+/** 宿主方法表（与 server/plugins.ts#PluginHost 同语义的精简版：只收发现用的注册/调用面）。
+ *  needs="-" = 观察/基础设施类（无需能力声明）；其余走 can() 门控。 */
+export const HOST_METHODS = [
+    {
+        name: "ui.register",
+        needs: "ui",
+        summary: "运行时注册 UI 条目（与 manifest 同口径，别名映射+枚举校验）",
+        example: `host.ui.register({ slot: "topbar.primary", id: "btn", label: "按钮" })`,
+    },
+    {
+        name: "ui.update",
+        needs: "ui",
+        summary: "按 id 改已存在条目（label/badge/checked/value/progress）",
+        example: `host.ui.update("btn", { badge: "3" })`,
+    },
+    {
+        name: "ui.remove",
+        needs: "ui",
+        summary: "移除条目（manifest 声明的也能压住，直到 reload）",
+        example: `host.ui.remove("btn")`,
+    },
+    {
+        name: "ui.arrange",
+        needs: "ui",
+        summary: "整理任何条目（含 host:* 内置）：hide/order/group/label",
+        example: `host.ui.arrange([{ id: "host:tasks", hide: true }])`,
+    },
+    {
+        name: "ui.list",
+        needs: "ui",
+        summary: "自查本插件的 items + arrange（调别的插件看不见）",
+        example: `host.ui.list()`,
+    },
+    {
+        name: "onUiAction",
+        needs: "ui",
+        summary: "订阅条目点击（action 名 → 回调，client bundle 侧）",
+        example: `__piWebUiHost.onUiAction("my:open", () => {})`,
+    },
+    {
+        name: "registerAgentTool",
+        needs: "tools",
+        summary: "给 AI 注册工具（插件给模型加能力，与 AI 写插件方向相反）",
+        example: `host.registerAgentTool({ name: "mail_list", description: "…", execute: async () => ({}) })`,
+    },
+    {
+        name: "onToolPre",
+        needs: "tools",
+        summary: "工具 pre 拦截（仅 bash/read）：allow/deny/ask，首个阻断胜出",
+        example: `host.onToolPre((req) => req.params?.command?.includes("rm -rf") ? { decision: "deny" } : undefined)`,
+    },
+    {
+        name: "onToolPost",
+        needs: "tools",
+        summary: "工具 post 编辑（仅 bash/read）：换 content / 补 additionalContext",
+        example: `host.onToolPost(({ result }) => ({ content: result.content }))`,
+    },
+    {
+        name: "onToolEvent",
+        needs: "-",
+        summary: "订阅工具执行事件（start/end 成对，只观测）",
+        example: `host.onToolEvent((ev) => {})`,
+    },
+    {
+        name: "bash",
+        needs: "tools",
+        summary: "受限 shell（无 piped shell，按词切分；cwd 锁工作区内，默认 60s 超时）",
+        example: `await host.bash("ls", { timeoutMs: 10000 })`,
+    },
+    {
+        name: "registerCommand",
+        needs: "-",
+        summary: "注册斜杠命令（/name 选择器 + prompt 拦截执行）",
+        example: `host.registerCommand({ name: "deploy", description: "部署", run: (args) => {} })`,
+    },
+    {
+        name: "route",
+        needs: "http",
+        summary: "挂载 HTTP 路由（/plugins-api/<id><path>）",
+        example: `host.route("GET", "/inbox", (req, res) => res.json([]))`,
+    },
+    {
+        name: "registerProxy",
+        needs: "http",
+        summary: "反向代理前缀（透传到 127.0.0.1:port，防 SSRF 锁回环）",
+        example: `host.registerProxy("/app", 3000)`,
+    },
+    {
+        name: "chat",
+        needs: "chat",
+        summary: "无头调用：把外部通道文本投给 agent（fire-and-forget）",
+        example: `await host.chat({ text: "hi" })`,
+    },
+    {
+        name: "chatWait",
+        needs: "chat",
+        summary: "等无头调用的 run_end（默认 120s，上下钳制）",
+        example: `await host.chatWait({ conversationId })`,
+    },
+    {
+        name: "llm.complete",
+        needs: "llm",
+        summary: "孤立无工具一次性补全（花用户模型额度）",
+        example: `await host.llm.complete({ prompt: "…" })`,
+    },
+    {
+        name: "requestPermission",
+        needs: "-",
+        summary: "申请能力授权（net 主机 / llm 模型作用域，用户确认）",
+        example: `await host.requestPermission({ family: "net", hosts: ["api.example.com"] })`,
+    },
+    {
+        name: "fs",
+        needs: "fs",
+        summary: "工作区文件（list/read/readText/write/remove…，锚定活 cwd，越界拒绝）",
+        example: `await host.fs.readText("notes/todo.md")`,
+    },
+    {
+        name: "fs.requestAccess",
+        needs: "fs",
+        summary: "申请工作区外目录授权（浏览器确认框，remember 记盘）",
+        example: `await host.fs.requestAccess("/data")`,
+    },
+    {
+        name: "project.create",
+        needs: "fs",
+        summary: "在已授权目录组装项目（mkdir/clone/写文件/git init）",
+        example: `await host.project.create({ dir: "/data/app", files: {} })`,
+    },
+    {
+        name: "schedule",
+        needs: "-",
+        summary: "定时任务（cron/延迟，持久化可重启不丢，远期分片防溢出）",
+        example: `host.schedule("0 9 * * *", () => {})`,
+    },
+    {
+        name: "registerBackgroundTask",
+        needs: "-",
+        summary: "常驻后台任务（并入后台任务面板，随反激活移除）",
+        example: `host.registerBackgroundTask({ id: "svc", label: "服务" })`,
+    },
+    {
+        name: "onRunEvent",
+        needs: "-",
+        summary: "订阅运行轨迹（run/message/tool…，时间线聚合用）",
+        example: `host.onRunEvent((ev) => {})`,
+    },
+    {
+        name: "getActiveConversation",
+        needs: "-",
+        summary: "读当前打开对话快照（只读引用，广播前抽摘要）",
+        example: `host.getActiveConversation()`,
+    },
+    {
+        name: "onConversationChanged",
+        needs: "-",
+        summary: "订阅切对话（轨迹插件重拉时间线）",
+        example: `host.onConversationChanged(() => {})`,
+    },
+    {
+        name: "storage",
+        needs: "-",
+        summary: "插件私有 KV（storage.json，原子写，卸载即删）",
+        example: `host.storage.get("k")`,
+    },
+    { name: "secrets", needs: "-", summary: "加密 secrets（明文永不落盘/下发）", example: `host.secrets.get("token")` },
+    {
+        name: "ensureDeps",
+        needs: "-",
+        summary: "依赖自动补装（单飞，npm 包）",
+        example: `await host.ensureDeps(["dayjs"])`,
+    },
+    {
+        name: "getSettings",
+        needs: "-",
+        summary: "读声明式设置值（manifest.settings 字段）",
+        example: `host.getSettings()`,
+    },
+    {
+        name: "onSettingsChanged",
+        needs: "-",
+        summary: "订阅设置保存（⚙ 面板保存后触发）",
+        example: `host.onSettingsChanged((v) => {})`,
+    },
+    { name: "onCwdChange", needs: "-", summary: "订阅工作区切换", example: `host.onCwdChange((cwd) => {})` },
+    {
+        name: "onAttach",
+        needs: "-",
+        summary: "订阅浏览器接入（主动推完整状态，服务端是唯一事实源）",
+        example: `host.onAttach((clientId) => {})`,
+    },
+    {
+        name: "broadcast",
+        needs: "-",
+        summary: "向所有浏览器广播本插件消息",
+        example: `host.broadcast({ kind: "state" })`,
+    },
+    { name: "notify", needs: "-", summary: "发系统通知条（notice toast）", example: `host.notify("info", "完成")` },
+    {
+        name: "effect",
+        needs: "-",
+        summary: "自建副作用挂进 effect 栈（反激活逆序回卷）",
+        example: `host.effect("timer", () => clearInterval(t))`,
+    },
+    {
+        name: "events.emit/on",
+        needs: "-",
+        summary: "插件间事件总线（topic 建议 <id>: 前缀，发送方不可伪造）",
+        example: `host.events.on("notes:changed", () => {})`,
+    },
+    { name: "models.list", needs: "-", summary: "列出已配置鉴权的模型（provider/id）", example: `host.models.list()` },
+    {
+        name: "scm",
+        needs: "-",
+        summary: "只读 git 查询（status/branches/history，不经过 shell）",
+        example: `await host.scm.status()`,
+    },
+    {
+        name: "net.fetch",
+        needs: "net",
+        summary: "出站网络（白名单命中才放行，失败回 {ok:false} 不抛）",
+        example: `await host.net.fetch("https://api.example.com/x")`,
+    },
+    {
+        name: "conversations",
+        needs: "-",
+        summary: "会话目录（list/get/search，只读组装+定向投递）",
+        example: `await host.conversations.list()`,
+    },
+    {
+        name: "prompt",
+        needs: "-",
+        summary: "向指定对话发一条用户消息（无注入回 ok:false）",
+        example: `await host.prompt(convId, { text: "hi" })`,
+    },
+    { name: "steer", needs: "-", summary: "插队指定对话的当前运行", example: `await host.steer(convId, "换方向")` },
+    { name: "abortRun", needs: "-", summary: "中止指定对话的运行", example: `await host.abortRun(convId)` },
+];
+/** 装配目录：静态表（本模块）+ 动态占用（调用方现算）。调用方保证入参即真相（别名/枚举与解析层同源）。 */
+export function buildPluginApiCatalog(opts) {
+    const aliasByTarget = new Map();
+    for (const [alias, target] of Object.entries(opts.aliases)) {
+        const list = aliasByTarget.get(target) ?? [];
+        list.push(alias);
+        aliasByTarget.set(target, list);
+    }
+    const slots = [...opts.slots].sort().map((slot) => {
+        const example = SLOT_EXAMPLES[slot] ??
+            `{ "ui": { "${slot}": [{ "id": "m", "label": "条目", "kind": "action", "action": "my:m" }] } }`;
+        return {
+            slot,
+            aliases: [...(aliasByTarget.get(slot) ?? [])].sort(),
+            kinds: [...opts.kinds].sort(),
+            occupants: [...opts.occupantsOf(slot)].sort((a, b) => (a.pluginId < b.pluginId ? -1 : 1)),
+            replaceRisk: "插件 arrange 可改任何条目（含 host:* 内置），用户偏好最后说话（布局页可恢复）",
+            example,
+        };
+    });
+    return {
+        version: PLUGIN_API_CATALOG_VERSION,
+        slots,
+        agentTools: opts.agentTools.map((t) => ({
+            name: t.name,
+            group: t.group,
+            defaultOn: t.defaultOn,
+            dshVisible: t.dshVisible,
+        })),
+        hostMethods: HOST_METHODS.map((m) => ({ ...m })),
+    };
+}

package/dist/server/plugin-install-spec.js

@@ -0,0 +1,196 @@
+/**
+ * plugin-install-spec — 「安装前先读 spec」（DSH 对照清单 P0-3 / 引导式安装）。
+ *
+ * 背景：设置面板「添加到列表 / 从市场安装」原样把用户填的来源交给 CLI。打错字、
+ * 已装过、根本不是插件包，全都要等 pnpm/git 跑完、用户在输出里自己找原因。
+ * 这里在**动 CLI 之前**先做一次可解释的检查，把失败归到七种 problem 之一，
+ * 每种都给一句人话 +（能给的）修复建议。
+ *
+ * 纪律：
+ *   - 本模块**不联网、不写盘**（纯分类 + 本地文件系统探测）；真正的远端探测
+ *     （raw.githubusercontent 读 manifest.json）在 installer 的 inspect 里做，
+ *     这样本文件可以离线单测、也可以被前端复用同一套文案 key。
+ *   - 分类结果只是**建议**，不是硬门禁：installer 仍会在真正安装前再校验一次，
+ *     未知/疑似可用一律放行（宁可让 CLI 说话，也不要因为探测失败把能装的挡掉）。
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { isValidSource } from "./plugin-catalog.js";
+/** npm 包名形状（宽松）：可带 @scope/ 前缀与 @version 后缀；不含 `/` 之外的路径段。 */
+const NPM_RE = /^(?:@[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?\/)?[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?(?:@[^\s/]+)?$/i;
+/**
+ * 解析并按形状分类一个安装来源。纯函数、不碰网络与磁盘（除 `path` 分支的
+ * 存在性判断——那是刻意让「本机路径 vs 形状不对」可区分）。
+ */
+export function parseInstallSpec(rawSpec) {
+    const raw = String(rawSpec ?? "").trim();
+    if (!raw)
+        return { kind: "invalid", normalized: "" };
+    // 1) 本机路径：绝对路径、file:// 前缀、或当前存在的相对目录（CLI 自己的判据）。
+    const localCandidate = raw.replace(/^file:\/\//i, "");
+    if (isAbsolute(localCandidate) || safeExists(localCandidate))
+        return { kind: "path", normalized: localCandidate };
+    // 2) 完整 URL（git 仓库 / 目录文档）。
+    if (/^https?:\/\//i.test(raw)) {
+        // GitHub 的网页 URL 仍归 github（能拿 owner/repo/ref/subpath，可做远端探测）。
+        const gh = parseGithubUrl(raw);
+        if (gh)
+            return gh;
+        return { kind: "url", normalized: raw };
+    }
+    // 3) GitHub 的 owner/repo[/sub][#ref] 简写。
+    const short = parseGithubShort(raw);
+    if (short)
+        return short;
+    // 4) npm 包名。
+    if (NPM_RE.test(raw))
+        return { kind: "npm", normalized: raw };
+    return { kind: "invalid", normalized: raw };
+}
+function safeExists(p) {
+    try {
+        return existsSync(p);
+    }
+    catch {
+        // 非法路径字符（Windows 上的 `<` `>` 等）→ 当不存在。
+        return false;
+    }
+}
+/** 解析 https://github.com/owner/repo[/tree/<ref>[/<sub>]] 或 `owner/repo` 简写。 */
+function parseGithubUrl(raw) {
+    const m = raw.match(/^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/#?]+)(?:\/(?:tree|blob)\/([^/]+)((?:\/[^#?]+)*))?/i);
+    if (!m)
+        return null;
+    const [, owner, repoRaw, refRaw, rest] = m;
+    const repo = String(repoRaw ?? "").replace(/\.git$/i, "");
+    const subpath = String(rest ?? "")
+        .replace(/^\/+/, "")
+        .replace(/\/+$/, "");
+    const hashRef = raw.includes("#") ? raw.slice(raw.indexOf("#") + 1).trim() : "";
+    const ref = hashRef || String(refRaw ?? "");
+    return {
+        kind: "github",
+        normalized: [owner, repo, subpath].filter(Boolean).join("/") + (ref ? `#${ref}` : ""),
+        owner,
+        repo,
+        ...(ref ? { ref } : {}),
+        ...(subpath ? { subpath } : {}),
+    };
+}
+/** 解析 owner/repo[/sub][#ref]（cli 与 marketplace 的主写法）。 */
+function parseGithubShort(raw) {
+    // 带 @ 前缀 = npm scope（@scope/pkg），GitHub 的 owner 不允许 @ —— 先摘出去，
+    // 免得 `@scope/pkg` 被当成 owner=`@scope` 的仓库（分类错会让 UI 给错建议）。
+    if (raw.startsWith("@"))
+        return null;
+    const hash = raw.indexOf("#");
+    const ref = hash >= 0 ? raw.slice(hash + 1).trim() : "";
+    const body = (hash >= 0 ? raw.slice(0, hash) : raw).replace(/\/+$/, "");
+    if (!isValidSource(body))
+        return null;
+    const segs = body.split("/").filter(Boolean);
+    const [owner, repo, ...rest] = segs;
+    if (!owner || !repo)
+        return null;
+    // URL 的 tree/blob 写法也可简写过来（owner/repo/tree/<ref>/<sub>）。
+    let subpath = rest.join("/");
+    let effectiveRef = ref;
+    if (rest[0] === "tree" || rest[0] === "blob") {
+        effectiveRef = rest[1] ?? ref;
+        subpath = rest.slice(2).join("/");
+    }
+    return {
+        kind: "github",
+        normalized: body + (effectiveRef ? `#${effectiveRef}` : ""),
+        owner,
+        repo,
+        ...(effectiveRef ? { ref: effectiveRef } : {}),
+        ...(subpath ? { subpath } : {}),
+    };
+}
+/** 粗略的 id 字符集（与 server/plugins.ts 的 ID_RE 一致）。 */
+const ID_RE = /^[A-Za-z0-9_-]+$/;
+/** 由来源推导落盘 id（与 CLI / plugin-catalog 同规则：子目录末段 > 仓库名 > 末段）。 */
+export function suggestPluginId(spec, explicit) {
+    if (explicit && ID_RE.test(explicit))
+        return explicit;
+    const seg = spec.subpath
+        ? spec.subpath.split("/").filter(Boolean).pop()
+        : (spec.repo ?? lastSegment(spec.normalized));
+    const cleaned = String(seg ?? "")
+        .replace(/[^A-Za-z0-9_-]/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return cleaned || "plugin";
+}
+function lastSegment(s) {
+    const body = s.split("#")[0].replace(/\/+$/, "");
+    const segs = body.split("/").filter(Boolean);
+    return segs[segs.length - 1] ?? "";
+}
+/**
+ * 本地检查：形状分类 + 已装判定。**不联网** —— 远端 manifest 探测由 installer
+ * 的 `inspectRemote()` 补上（本函数是它的第一步，也可单独用于「添加到列表」）。
+ */
+export function inspectLocalInstallSpec(rawSpec, deps) {
+    const spec = parseInstallSpec(rawSpec);
+    const suggestedId = suggestPluginId(spec, deps.explicitId);
+    const installed = safeExists(join(deps.pluginsDir, suggestedId));
+    const base = { spec, installed, suggestedId };
+    if (spec.kind === "invalid")
+        return {
+            ...base,
+            problem: "invalid-spec",
+            detail: "Unrecognized source — expected owner/repo, owner/repo/subdir[#ref], a GitHub URL, or an npm package name.",
+        };
+    if (spec.kind === "path" && !safeExists(spec.normalized))
+        return { ...base, problem: "not-found", detail: `Local path does not exist: ${spec.normalized}` };
+    if (installed && !deps.force)
+        return {
+            ...base,
+            problem: "already-installed",
+            detail: `A plugin named "${suggestedId}" is already installed — use Update to replace it.`,
+        };
+    return base;
+}
+/** 读本地目录里的 manifest.json（本地路径源用；失败返回 null，不抛）。 */
+export function readLocalManifest(dir) {
+    try {
+        const p = join(dir, "manifest.json");
+        if (!statSync(p).isFile())
+            return null;
+        const raw = JSON.parse(readFileSync(p, "utf8"));
+        return pickManifestFields(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** 从任意 manifest 对象里摘出可展示字段（顺带校验它是插件）。 */
+export function pickManifestFields(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    if (typeof o.id !== "string" && typeof o.name !== "string")
+        return null;
+    const permissions = Array.isArray(o.permissions)
+        ? o.permissions.filter((x) => typeof x === "string").slice(0, 32)
+        : undefined;
+    return {
+        ...(typeof o.id === "string" ? { id: o.id } : {}),
+        ...(typeof o.name === "string" ? { name: o.name } : {}),
+        ...(typeof o.version === "string" ? { version: o.version } : {}),
+        ...(typeof o.description === "string" ? { description: o.description } : {}),
+        ...(permissions ? { permissions } : {}),
+    };
+}
+/**
+ * 远端 manifest 的候选 raw URL（按 ref 有无/子目录有无各一条）。
+ * 只用 raw.githubusercontent.com —— 与 server/locales.ts 同一取用姿势，无需 API token。
+ */
+export function manifestCandidateUrls(spec) {
+    if (spec.kind !== "github" || !spec.owner || !spec.repo)
+        return [];
+    const ref = spec.ref || "HEAD";
+    const base = `https://raw.githubusercontent.com/${spec.owner}/${spec.repo}/${ref}`;
+    return spec.subpath ? [`${base}/${spec.subpath}/manifest.json`] : [`${base}/manifest.json`];
+}

package/dist/server/plugin-installer.js

@@ -22,6 +22,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { pick } from "./i18n.js";
 import { isValidSource } from "./plugin-catalog.js";
+import { inspectLocalInstallSpec, manifestCandidateUrls, readLocalManifest, suggestPluginId, } from "./plugin-install-spec.js";
 import { killPidTree } from "./process-utils.js";
 /** 插件 id 字符集（与 server/plugins.ts、plugin-catalog.ts 一致，防路径穿越）。 */
 const ID_RE = /^[A-Za-z0-9_-]+$/;
@@ -60,6 +61,78 @@ export function buildPluginJobArgs(spec, dataDir, lang) {
         args.push("--no-build");
     return { args };
 }
+/** 安装前的 spec 检查（DSH P0-3 引导式安装）。
+ *
+ * 三层：① 形状分类（parseInstallSpec）+ 本地已装判定（inspectLocalInstallSpec）；
+ * ② 本地路径源：直接读它的 manifest.json；
+ * ③ 远端 GitHub 源：一次 raw.githubusercontent 探测（超时 6s，失败不阻断）——
+ *    拿到 manifest 就归到 not-found / not-a-package / not-a-bundle 之一，
+ *    拿不到（网络/代理问题）回 network 但**不阻塞安装**（problem 只作提示）。
+ *
+ * 通一不联网：测试时传 fetchImpl 替身；生产走全局 fetch。
+ */
+export async function inspectInstallSpec(rawSpec, deps) {
+    const local = inspectLocalInstallSpec(rawSpec, deps);
+    // 形状就不对 / 本地路径不存在 / 已装（且没 force）：本地已经能给出结论，不再联网。
+    if (local.problem || local.spec.kind === "npm" || local.spec.kind === "url") {
+        // npm/url 不在本检查的覆盖范围（CLI/注册表自己会报）——原样返回，让 CLI 说话。
+        return local;
+    }
+    if (local.spec.kind === "path") {
+        const manifest = readLocalManifest(local.spec.normalized);
+        if (!manifest)
+            return {
+                ...local,
+                problem: "not-a-package",
+                detail: `No manifest.json found in ${local.spec.normalized} — this is not a pi-web-ui plugin.`,
+            };
+        return { ...local, manifest, suggestedId: suggestPluginId(local.spec, deps.explicitId ?? manifest.id) };
+    }
+    // github 简写：远端探测 best-effort（失败只补一条提示，不挡安装）。
+    for (const url of manifestCandidateUrls(local.spec)) {
+        try {
+            const res = await (deps.fetchImpl ?? fetch)(url, { signal: AbortSignal.timeout(deps.timeoutMs ?? 6000) });
+            if (res.status === 404)
+                continue;
+            if (!res.ok)
+                return { ...local, problem: "network", detail: `Remote probe failed: HTTP ${res.status}` };
+            const manifest = pickManifest(local, await res.json());
+            if (!manifest)
+                return {
+                    ...local,
+                    problem: "not-a-bundle",
+                    detail: "The remote manifest.json is not a valid plugin manifest (missing id/name).",
+                };
+            return { ...local, manifest, suggestedId: suggestPluginId(local.spec, deps.explicitId ?? manifest.id) };
+        }
+        catch {
+            return { ...local, problem: "network", detail: "Could not reach the remote repository to verify the plugin." };
+        }
+    }
+    // 连 manifest 都没探到 —— 仓库/子目录/分支不存在，或根本不是插件包。
+    return {
+        ...local,
+        problem: "not-found",
+        detail: `No manifest.json at the remote source — check the repo/subdirectory and the #ref.`,
+    };
+}
+function pickManifest(local, raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    if (typeof o.id !== "string" && typeof o.name !== "string")
+        return null;
+    void local;
+    return {
+        ...(typeof o.id === "string" ? { id: o.id } : {}),
+        ...(typeof o.name === "string" ? { name: o.name } : {}),
+        ...(typeof o.version === "string" ? { version: o.version } : {}),
+        ...(typeof o.description === "string" ? { description: o.description } : {}),
+        ...(Array.isArray(o.permissions)
+            ? { permissions: o.permissions.filter((x) => typeof x === "string").slice(0, 32) }
+            : {}),
+    };
+}
 export class PluginInstaller {
     deps;
     child = null;