pi-web-ui 0.94.1 → 0.96.0

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;

package/dist/server/plugin-llm.js

@@ -48,82 +48,88 @@ export async function completeWithIsolatedSession(env, req) {
     const maxChars = Math.min(Math.max(Number(req?.maxChars ?? DEFAULT_MAX_CHARS) || DEFAULT_MAX_CHARS, 1), MAX_MAX_CHARS);
     const timeoutMs = Math.min(Math.max(Number(req?.timeoutMs ?? DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS), MAX_TIMEOUT_MS);
     inflight += 1;
-    try {
-        const run = (async () => {
-            let dispose;
-            try {
-                const services = await createAgentSessionServices({
-                    cwd: env.cwd,
-                    agentDir: env.agentDir,
-                    // 技能全剥：纯补全不需要技能上下文（省 token，结果可预测）。
-                    resourceLoaderOptions: {
-                        skillsOverride: (res) => ({ ...res, skills: [] }),
-                    },
-                    modelRuntime: await ModelRuntime.create({
-                        authPath: join(env.agentDir, "auth.json"),
-                        modelsPath: join(env.agentDir, "models.json"),
-                    }),
-                });
-                // 模型：显式指定 > 主会话回落 > 会话默认（与 reviewer 同优先级）。
-                let model;
-                let modelName = "default";
-                const spec = parseModelSpec(req?.model);
-                if (spec) {
-                    model = services.modelRuntime.getModel(spec.provider, spec.id);
-                    if (!model)
-                        return fail(`llm.complete: 找不到模型 ${spec.spec}`);
-                    modelName = spec.spec;
-                }
-                if (!model && env.fallbackModel) {
-                    model = services.modelRuntime.getModel(env.fallbackModel.provider, env.fallbackModel.id);
-                    if (model)
-                        modelName = `${env.fallbackModel.provider}/${env.fallbackModel.id}`;
-                }
-                const srv = await createAgentSessionFromServices({
-                    services,
-                    sessionManager: SessionManager.inMemory(env.cwd),
-                    ...(model ? { model } : {}),
-                    // 全部工具关闭（"all"）：纯补全，无副作用（SDK 的 noTools 是 "builtin"|"all" 枚举）。
-                    noTools: "all",
-                });
-                dispose = () => {
-                    try {
-                        srv.session.dispose();
-                    }
-                    catch {
-                        /* dispose 尽力而为 */
-                    }
-                };
-                const text = system.trim() ? `系统指令：${system.trim()}\n\n---\n\n任务：${prompt}` : prompt;
-                await srv.session.prompt(text, { expandPromptTemplates: false });
-                const raw = srv.session.getLastAssistantText() ?? "";
-                let usage;
-                try {
-                    const stats = srv.session.getSessionStats();
-                    usage = { input: stats.tokens.input, output: stats.tokens.output };
-                }
-                catch {
-                    /* usage 尽力而为 */
-                }
-                return { ok: true, text: raw.slice(0, maxChars), model: modelName, ...(usage ? { usage } : {}) };
+    const run = (async () => {
+        let dispose;
+        try {
+            const services = await createAgentSessionServices({
+                cwd: env.cwd,
+                agentDir: env.agentDir,
+                // 技能全剥：纯补全不需要技能上下文（省 token，结果可预测）。
+                resourceLoaderOptions: {
+                    skillsOverride: (res) => ({ ...res, skills: [] }),
+                },
+                modelRuntime: await ModelRuntime.create({
+                    authPath: join(env.agentDir, "auth.json"),
+                    modelsPath: join(env.agentDir, "models.json"),
+                }),
+            });
+            // 模型：显式指定 > 主会话回落 > 会话默认（与 reviewer 同优先级）。
+            let model;
+            let modelName = "default";
+            const spec = parseModelSpec(req?.model);
+            if (spec) {
+                model = services.modelRuntime.getModel(spec.provider, spec.id);
+                if (!model)
+                    return fail(`llm.complete: 找不到模型 ${spec.spec}`);
+                modelName = spec.spec;
+            }
+            if (!model && env.fallbackModel) {
+                model = services.modelRuntime.getModel(env.fallbackModel.provider, env.fallbackModel.id);
+                if (model)
+                    modelName = `${env.fallbackModel.provider}/${env.fallbackModel.id}`;
             }
-            finally {
-                // 会话回收跟 run 走：超时竞速输了 run 还在飞，run 落定才 dispose，不留孤儿。
+            const srv = await createAgentSessionFromServices({
+                services,
+                sessionManager: SessionManager.inMemory(env.cwd),
+                ...(model ? { model } : {}),
+                // 全部工具关闭（"all"）：纯补全，无副作用（SDK 的 noTools 是 "builtin"|"all" 枚举）。
+                noTools: "all",
+            });
+            dispose = () => {
                 try {
-                    dispose?.();
+                    srv.session.dispose();
                 }
                 catch {
                     /* dispose 尽力而为 */
                 }
+            };
+            const text = system.trim() ? `系统指令：${system.trim()}\n\n---\n\n任务：${prompt}` : prompt;
+            await srv.session.prompt(text, { expandPromptTemplates: false });
+            const raw = srv.session.getLastAssistantText() ?? "";
+            let usage;
+            try {
+                const stats = srv.session.getSessionStats();
+                usage = { input: stats.tokens.input, output: stats.tokens.output };
+            }
+            catch {
+                /* usage 尽力而为 */
+            }
+            return { ok: true, text: raw.slice(0, maxChars), model: modelName, ...(usage ? { usage } : {}) };
+        }
+        finally {
+            // 会话回收跟 run 走：超时竞速输了 run 还在飞，run 落定才 dispose，不留孤儿。
+            try {
+                dispose?.();
+            }
+            catch {
+                /* dispose 尽力而为 */
             }
-        })();
+        }
+    })();
+    // 并发计数跟**真实 run** 走，而不是外层函数的 finally：超时竞速返回后 run 还在飞，
+    // 计数必须继续占着 MAX_INFLIGHT 的位 —— 否则每次超时都「腾出」一路并发，
+    // 连续超时的插件能把在飞会话越堆越多，护栏失效。catch 挂在分支上兜住 run 的
+    // 拒绝（竞速已由 timer 赢时，外层 catch 不会再收到它）。
+    void run
+        .catch(() => { })
+        .finally(() => {
+        inflight -= 1;
+    });
+    try {
         const timer = new Promise((resolve) => setTimeout(() => resolve(fail(`llm.complete: 超时（约${Math.round(timeoutMs / 1000)}s）`)), timeoutMs));
         return await Promise.race([run, timer]);
     }
     catch (err) {
         return fail(`llm.complete: ${err.message}`);
     }
-    finally {
-        inflight -= 1;
-    }
 }