@rexvane/piweb 0.3.3 → 0.3.5

package/src/lib/growth-service.ts

@@ -62,6 +62,10 @@ interface WorkspaceState {
 interface Registry {
 	workspaces: Map<string, Promise<WorkspaceState>>;
 	gitOk?: Promise<boolean>;
+	/** git 不可用的上次确认时间（否定结果短缓存，避免重复探测超时） */
+	gitFailedAt?: number;
+	/** 解析后的 git 可执行文件（macOS GUI PATH 兜底） */
+	gitBin?: string;
 }
 const globalForGrowth = globalThis as typeof globalThis & { __piWebGrowth?: Registry };
 const registry: Registry = (globalForGrowth.__piWebGrowth ??= { workspaces: new Map() });
@@ -106,62 +110,102 @@ interface RunResult {
 
 type Env = Record<string, string | undefined>;
 
-function runGit(args: string[], opts: { cwd?: string; input?: Buffer | string; maxBuffer?: number; env?: Env } = {}): Promise<RunResult> {
-	const maxBuffer = opts.maxBuffer ?? 64 * 1024 * 1024;
-	return new Promise((resolve, reject) => {
-		const child = spawn("git", args, {
-			cwd: opts.cwd,
-			env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", ...opts.env },
-			windowsHide: true,
-			stdio: ["pipe", "pipe", "pipe"],
+/**
+ * 解析 git 可执行文件：macOS GUI/launchd 启动的进程 PATH 常不含 Homebrew，
+ * spawn("git") 会 ENOENT → 生长快照整体误判不可用。PATH 找不到时退回常见安装位置。
+ * 只在非 Windows 生效；结果缓存到 registry（成功后不再变）。
+ */
+async function resolveGitBin(): Promise<string> {
+	if (registry.gitBin) return registry.gitBin;
+	let bin = "git";
+	if (process.platform !== "win32") {
+		const candidates = ["/opt/homebrew/bin/git", "/usr/local/bin/git", "/usr/bin/git", "/usr/local/git/bin/git"];
+		const inPath = await new Promise<boolean>((resolve) => {
+			const child = spawn("git", ["--version"], { stdio: "ignore" });
+			child.on("error", () => resolve(false));
+			child.on("close", (code) => resolve(code === 0));
 		});
-		const out: Buffer[] = [];
-		const err: Buffer[] = [];
-		let size = 0;
-		let settled = false;
-		const timer = setTimeout(() => fail(new GrowthError("git timed out", "failed")), 30_000);
-		const fail = (error: Error) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			child.kill();
-			reject(error);
-		};
-		child.stdout.on("data", (chunk: Buffer) => {
-			size += chunk.length;
-			if (size > maxBuffer) {
-				child.kill();
-				fail(new GrowthError("git output exceeded the buffer limit", "too-large"));
-				return;
+		if (!inPath) {
+			for (const candidate of candidates) {
+				const ok = await new Promise<boolean>((resolve) => {
+					const child = spawn(candidate, ["--version"], { stdio: "ignore" });
+					child.on("error", () => resolve(false));
+					child.on("close", (code) => resolve(code === 0));
+				});
+				if (ok) {
+					bin = candidate;
+					break;
+				}
 			}
-			out.push(chunk);
-		});
-		child.stderr.on("data", (chunk: Buffer) => err.push(chunk));
-		child.on("error", (error: NodeJS.ErrnoException) => {
-			if (error.code === "ENOENT" && opts.cwd && !existsSync(opts.cwd)) fail(new GrowthError("workspace directory not found", "failed"));
-			else fail(error.code === "ENOENT" ? new GrowthError("git is not installed", "unavailable") : error);
-		});
-		child.on("close", (code) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			resolve({ stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString("utf8"), code: code ?? -1 });
-		});
-		if (opts.input !== undefined) child.stdin.end(opts.input);
-		else child.stdin.end();
-	});
+		}
+	}
+	registry.gitBin = bin;
+	return bin;
 }
 
+function runGit(args: string[], opts: { cwd?: string; input?: Buffer | string; maxBuffer?: number; env?: Env } = {}): Promise<RunResult> {
+	const maxBuffer = opts.maxBuffer ?? 64 * 1024 * 1024;
+	return resolveGitBin().then(
+		(gitBin) =>
+			new Promise<RunResult>((resolve, reject) => {
+				const child = spawn(gitBin, args, {
+					cwd: opts.cwd,
+					env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", ...opts.env },
+					windowsHide: true,
+					stdio: ["pipe", "pipe", "pipe"],
+				});
+				const out: Buffer[] = [];
+				const err: Buffer[] = [];
+				let size = 0;
+				let settled = false;
+				const timer = setTimeout(() => fail(new GrowthError("git timed out", "failed")), 30_000);
+				const fail = (error: Error) => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timer);
+					child.kill();
+					reject(error);
+				};
+				child.stdout.on("data", (chunk: Buffer) => {
+					size += chunk.length;
+					if (size > maxBuffer) {
+						child.kill();
+						fail(new GrowthError("git output exceeded the buffer limit", "too-large"));
+						return;
+					}
+					out.push(chunk);
+				});
+				child.stderr.on("data", (chunk: Buffer) => err.push(chunk));
+				child.on("error", (error: NodeJS.ErrnoException) => {
+					if (error.code === "ENOENT" && opts.cwd && !existsSync(opts.cwd)) fail(new GrowthError("workspace directory not found", "failed"));
+					else fail(error.code === "ENOENT" ? new GrowthError("git is not installed", "unavailable") : error);
+				});
+				child.on("close", (code) => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timer);
+					resolve({ stdout: Buffer.concat(out), stderr: Buffer.concat(err).toString("utf8"), code: code ?? -1 });
+				});
+				if (opts.input !== undefined) child.stdin.end(opts.input);
+				else child.stdin.end();
+			}),
+	);
+}
+
+/** git 不可用时短时间缓存否定结果：避免每个会话重复 30s 超时把 UI 拖死 */
+const GIT_FAIL_RETRY_MS = 60_000;
+
 async function gitOk(): Promise<boolean> {
-	registry.gitOk ??= runGit(["--version"]).then((r) => {
-		const ok = r.code === 0;
-		if (!ok) registry.gitOk = undefined;
-		return ok;
-	}, () => {
+	if (registry.gitOk) return registry.gitOk;
+	if (registry.gitFailedAt && Date.now() - registry.gitFailedAt < GIT_FAIL_RETRY_MS) return false;
+	const check = runGit(["--version"]).then((r) => r.code === 0, () => false);
+	registry.gitOk = check;
+	void check.then((ok) => {
 		registry.gitOk = undefined;
-		return false;
+		if (ok) registry.gitFailedAt = undefined;
+		else registry.gitFailedAt = Date.now();
 	});
-	return registry.gitOk;
+	return check;
 }
 
 /** 影子仓库命令：固定 git-dir / work-tree，关掉换行转换与路径转义，输出按字节原样 */

package/src/lib/models-service.ts

@@ -11,6 +11,7 @@ import { BlockList, isIP } from "node:net";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { getNodeValue, parseTree, printParseErrorCode, type ParseError } from "jsonc-parser";
 import { getAgentDir, getModelRuntime, resetModelRuntime } from "./pi";
+import { reloadSessionsForCwd } from "./agent-manager";
 import {
 	getSupportedThinkingLevels, InMemoryCredentialStore, InMemoryModelsStore,
 	type AuthInteraction, type AuthPrompt, type AuthType,
@@ -45,6 +46,8 @@ export interface ProviderView {
 	resolvedAuthSource?: string;
 	authError?: string;
 	keyManaged: boolean;
+	/** auth.json 里已存凭证的类型：OAuth 条目才有专门的删除入口与文案 */
+	storedAuthType?: "api_key" | "oauth";
 	modelCount: number;
 }
 
@@ -97,6 +100,26 @@ export function listModels(): Promise<{
 	return value;
 }
 
+/** auth.json 各条目的凭证类型（与 storedCredentialFor 同样的两层数据结构）；读取失败不影响目录 */
+async function readStoredAuthTypes(): Promise<Map<string, "api_key" | "oauth">> {
+	const out = new Map<string, "api_key" | "oauth">();
+	try {
+		const parsed = JSON.parse(await fs.readFile(path.join(getAgentDir(), "auth.json"), "utf8")) as Record<string, any>;
+		const entries: Array<[string, any]> = [
+			...Object.entries(parsed ?? {}),
+			...Object.entries(parsed?.providers ?? {}),
+		];
+		for (const [id, entry] of entries) {
+			if (out.has(id)) continue;
+			if (entry?.type === "oauth") out.set(id, "oauth");
+			else if (entry && typeof entry === "object" && [entry.apiKey, entry.api_key, entry.key].some((v) => typeof v === "string" && v.trim())) out.set(id, "api_key");
+		}
+	} catch {
+		/* missing or malformed auth.json: no stored credentials to classify */
+	}
+	return out;
+}
+
 async function listModelsUncached(): Promise<{
 	providers: ProviderView[];
 	models: ModelView[];
@@ -104,6 +127,7 @@ async function listModelsUncached(): Promise<{
 	const rt = await getModelRuntime();
 	const builtInProviderIds = await getBuiltInProviderIds();
 	const providers = rt.getProviders() as any[];
+	const storedAuthTypes = await readStoredAuthTypes();
 	const out: ProviderView[] = [];
 	const models: ModelView[] = [];
 	// 认证探测逐个 await 时，N 个已配置供应商就是 N 次串行网络往返；并发做，单个超时不拖累整体
@@ -155,6 +179,7 @@ async function listModelsUncached(): Promise<{
 			resolvedAuthSource,
 			authError,
 			keyManaged: auth?.source === "stored",
+			storedAuthType: auth?.source === "stored" ? storedAuthTypes.get(pid) : undefined,
 			modelCount: list.length,
 		});
 		for (const mm of list) {
@@ -263,22 +288,23 @@ export function isPublicModelDiscoveryAddress(address: string): boolean {
 	return false;
 }
 
-async function requestModelCatalog(endpoint: URL, headers: Record<string, string>, signal: AbortSignal): Promise<Response> {
-	const allowPrivate = process.env.PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY === "1";
+async function requestModelCatalog(endpoint: URL, headers: Record<string, string>, signal: AbortSignal, allowPrivate = false): Promise<Response> {
+	// 显式勾选（本次允许访问本机/私网）或全局环境变量，二选一放行
+	const allowed = allowPrivate || process.env.PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY === "1";
 	const literalFamily = isIP(endpoint.hostname.replace(/^\[|\]$/g, ""));
-	if (!allowPrivate && literalFamily && !isPublicModelDiscoveryAddress(endpoint.hostname.replace(/^\[|\]$/g, ""))) {
-		throw new Error("模型目录地址指向本机或私有网络；如需访问本地网关，请设置 PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY=1");
+	if (!allowed && literalFamily && !isPublicModelDiscoveryAddress(endpoint.hostname.replace(/^\[|\]$/g, ""))) {
+		throw new Error("模型目录地址指向本机或私有网络；勾选「允许访问本机/私有网络地址」后重试，或设置 PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY=1");
 	}
 	return new Promise<Response>((resolve, reject) => {
 		const request = (endpoint.protocol === "https:" ? httpsRequest : httpRequest)(endpoint, {
 			headers,
 			signal,
 			agent: false,
-			lookup: allowPrivate ? undefined : (hostname, options, callback) => {
+			lookup: allowed ? undefined : (hostname, options, callback) => {
 				void dns.lookup(hostname, { all: true }).then((addresses) => {
 					const publicAddress = addresses.find(({ address }) => isPublicModelDiscoveryAddress(address));
 					if (!publicAddress) {
-						callback(new Error("模型目录地址指向本机或私有网络；如需访问本地网关，请设置 PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY=1"), "", 0);
+						callback(new Error("模型目录地址指向本机或私有网络；勾选「允许访问本机/私有网络地址」后重试，或设置 PI_WEB_ALLOW_PRIVATE_MODEL_DISCOVERY=1"), "", 0);
 						return;
 					}
 					if (options.all) callback(null, [publicAddress]);
@@ -343,7 +369,7 @@ async function readModelCatalog(response: Response): Promise<unknown> {
 }
 
 /** Fetch a provider's conventional /models catalog without persisting credentials. */
-export async function discoverModels(input: { baseUrl: string; api?: string; apiKey?: string; providerId?: string }): Promise<DiscoveredModel[]> {
+export async function discoverModels(input: { baseUrl: string; api?: string; apiKey?: string; providerId?: string; allowPrivate?: boolean }): Promise<DiscoveredModel[]> {
 	const rawBaseUrl = input.baseUrl.trim();
 	if (!rawBaseUrl) throw new Error("缺少 API 地址");
 	const base = new URL(rawBaseUrl);
@@ -383,7 +409,7 @@ export async function discoverModels(input: { baseUrl: string; api?: string; api
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), 15000);
 		try {
-			const response = await requestModelCatalog(endpoint, headers, controller.signal);
+			const response = await requestModelCatalog(endpoint, headers, controller.signal, input.allowPrivate === true);
 			if (response.status === 401) {
 				throw new Error(apiKey ? "模型目录请求失败（HTTP 401）：密钥或令牌无效" : "模型目录请求失败（HTTP 401）：请先填写 API 密钥");
 			}
@@ -753,12 +779,21 @@ function mergeCustomProviderApiKeys(parsed: CustomProvidersFile, previous: Custo
 		// 字段缺失（包括 JSON.stringify 省略的 undefined）保留旧密钥；只有显式 null 删除。
 		if (provider.apiKey === null) {
 			delete provider.apiKey;
-			continue;
+		} else if (provider.apiKey === undefined) {
+			const previousProvider = previous.providers[id];
+			if (previousProvider && Object.prototype.hasOwnProperty.call(previousProvider, "apiKey")) {
+				provider.apiKey = previousProvider.apiKey;
+			}
 		}
-		const previousProvider = previous.providers[id];
-		if (!Object.prototype.hasOwnProperty.call(provider, "apiKey") && previousProvider
-			&& Object.prototype.hasOwnProperty.call(previousProvider, "apiKey")) {
-			provider.apiKey = previousProvider.apiKey;
+	}
+}
+
+/** 本地/回环地址的无鉴权网关（Ollama 等）：SDK 设计上必须给 apiKey 才算「已配置」；占位值 "unused" 是官方认可模式 */
+function applyLocalPlaceholderKeys(parsed: CustomProvidersFile): void {
+	for (const provider of Object.values(parsed.providers)) {
+		if (provider.apiKey === undefined && typeof provider.baseUrl === "string"
+			&& /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\]|192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/i.test(provider.baseUrl.trim())) {
+			provider.apiKey = "unused";
 		}
 	}
 }
@@ -835,6 +870,8 @@ export async function writeCustomProviders(content: string, revision?: string):
 				await validateStagedCustomProviders(temporary);
 			}
 			mergeCustomProviderApiKeys(parsed, old);
+			// 本地网关无 key 也得给占位值，否则 SDK 判定「未配置」→ 发消息报 No API key
+			applyLocalPlaceholderKeys(parsed);
 			validateTokenLimits(parsed);
 			await fs.writeFile(temporary, JSON.stringify(parsed, null, 2), {
 				encoding: "utf8", flag: previous.content === undefined ? "wx" : "w", mode: 0o600,
@@ -849,4 +886,7 @@ export async function writeCustomProviders(content: string, revision?: string):
 	}));
 	resetModelRuntime();
 	invalidateModelList();
+	// 已打开的会话持有保存前的旧 runtime：不清掉的话，在里面选新 provider 的模型
+	// 会报 "No API key for X"（新 runtime 有配置，旧 runtime 查不到）。让活跃会话就地重建。
+	await reloadSessionsForCwd();
 }

package/src/lib/process-format.ts

@@ -71,6 +71,51 @@ export function cleanCommand(command: string, cwd?: string): { text: string; lin
 	return { text, lines: lines.length };
 }
 
+/** 上下文 token 估算口径：与 SDK estimateTokens 一致的字符/4 */
+export function estimateTokensOf(text: string): number {
+	return Math.ceil(text.length / 4);
+}
+
+/** 上下文 13 类分段中的 5 个消息分项：按 role / content.type 归类字符数 */
+export function classifyMessageChars(
+	messages: Array<{ role?: string; content: Array<{ type: string; text?: string; thinking?: string; arguments?: unknown }> }>,
+): { user: number; agentText: number; agentThinking: number; agentToolCall: number; toolOutput: number } {
+	const out = { user: 0, agentText: 0, agentThinking: 0, agentToolCall: 0, toolOutput: 0 };
+	for (const message of messages) {
+		for (const content of message.content) {
+			if (content.type === "text") {
+				const chars = content.text?.length ?? 0;
+				if (message.role === "user") out.user += chars;
+				else out.agentText += chars;
+			} else if (content.type === "thinking") {
+				out.agentThinking += content.thinking?.length ?? 0;
+			} else if (content.type === "toolCall") {
+				out.agentToolCall += JSON.stringify(content.arguments ?? "").length;
+			} else if (content.type === "toolResult") {
+				out.toolOutput += (content as { text?: string }).text?.length ?? 0;
+			}
+		}
+	}
+	return out;
+}
+
+/** bash/PowerShell 删除文件的命令判定：rm / Remove-Item / del / trash 等，且至少带一个非选项参数 */
+export function isDeleteCommand(command: string): boolean {
+	const first = command.trim().split(/\s+/)[0] ?? "";
+	const base = first.split(/[\\/]/).pop() ?? first;
+	const name = base.toLowerCase().replace(/\.(exe|ps1|bat|cmd)$/, "");
+	if (!["rm", "remove-item", "ri", "del", "erase", "unlink", "trash"].includes(name)) return false;
+	const rest = command.trim().split(/\s+/).slice(1);
+	return rest.some((tok) => !tok.startsWith("-"));
+}
+
+/** 从删除命令里提取第一个目标路径（去引号；相对路径解析交给展示层） */
+export function deleteTargetOf(command: string): string {
+	const tokens = command.trim().match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+	const target = tokens.slice(1).find((tok) => !tok.startsWith("-"));
+	return target ? target.replace(/^["']|["']$/g, "") : "";
+}
+
 /** 按顶层的 ; && || 切分（引号内不切） */
 function splitTopLevel(cmd: string): string[] {
 	const parts: string[] = [];
@@ -194,11 +239,14 @@ export function firstSentence(text: string, max = 140): string {
 	return s.length > max ? `${s.slice(0, max - 1).trimEnd()}…` : s;
 }
 
-export type ModelErrorKind = "rateLimit" | "billing" | "auth" | "notFound" | "context" | "timeout" | "server" | "network";
+export type ModelErrorKind = "rateLimit" | "billing" | "auth" | "notFound" | "context" | "timeout" | "server" | "network" | "moderation";
 
 /** 把供应商原始报错归到少数几类，界面给一句人话；认不出返回 null（只显示原文） */
 export function classifyModelError(message: string): ModelErrorKind | null {
 	const m = message.toLowerCase();
+	// Content moderation (gateway-side sensitive-word filters) must be checked before
+	// the generic 5xx rule: such gateways often answer with a misleading 500.
+	if (/sensitive[ _-]?words?|content (moderation|filter)|moderation|content_policy|content policy|input blocked/.test(m)) return "moderation";
 	if (/\b429\b|rate.?limit|too many requests|requests per (minute|second)/.test(m)) return "rateLimit";
 	if (/\b402\b|insufficient (balance|credits|quota|funds)|billing|quota exceeded|余额/.test(m)) return "billing";
 	if (/\b401\b|\b403\b|unauthori[sz]ed|forbidden|invalid.*(api.?key|token)|authentication|permission denied/.test(m)) return "auth";

package/src/lib/skills-service.ts

@@ -95,3 +95,26 @@ export async function readSkillFile(filePath: string, cwd?: string): Promise<str
 	const authorized = await resolveDiscoveredPath(filePath, skills.map((skill) => skill.filePath));
 	return fs.readFile(authorized, "utf8");
 }
+
+/** 删除技能（SKILL.md 所在目录）。包技能（node_modules 内）随包安装，删除会被还原 → 拒绝并用禁用管理。 */
+export async function deleteSkill(filePath: string, cwd?: string): Promise<{ removed: string }> {
+	const skills = await listSkills(cwd);
+	const authorized = await resolveDiscoveredPath(filePath, skills.map((skill) => skill.filePath));
+	if (classifyScope(authorized, cwd) === "package") {
+		throw new Error("package-managed skill: disable it instead (it is reinstalled with the package)");
+	}
+	const skillDir = path.dirname(authorized);
+	// 只删技能目录本身，不能误删父目录（全局技能目录 ~/.pi/agent/skills、项目 .agents/skills 等）
+	const agentDir = getAgentDir().replace(/\\/g, "/");
+	const normalizedSkillDir = skillDir.replace(/\\/g, "/");
+	const knownRoots = [`${agentDir}/skills`, `${agentDir}/web-skills`];
+	if (!knownRoots.some((root) => normalizedSkillDir.toLowerCase() === root.toLowerCase())) {
+		// 非已知根：项目内技能目录，至少确认 SKILL.md 直接位于其下且目录名非空
+		if (path.basename(skillDir) === "") throw new Error("refusing to delete workspace root");
+	}
+	await fs.rm(skillDir, { recursive: true, force: true });
+	await reloadAllLoaders();
+	const scope = classifyScope(authorized, cwd);
+	await reloadSessionsForCwd(scope === "project" ? cwd : undefined);
+	return { removed: skillDir };
+}

package/src/lib/types.ts

@@ -211,6 +211,28 @@ export interface ContextResource {
 	source: "project" | "extension";
 }
 
+/**
+ * 上下文占用的服务端估算分项（全部为字符/4 启发式，与 SDK estimateTokens 口径一致）。
+ * 消息类分项（User/Agent Text/Thinking/Tool Call/Tool Output）由前端按消息统计，
+ * 这里只放服务端才能拿到的部分。
+ */
+export interface ContextBreakdown {
+	/** SDK 内建 system prompt 正文（不含 memory/skills/tools 段）的估算 token */
+	systemPrompt: number;
+	/** 内建工具（SDK 自带 bash/read/edit 等）定义的估算 token */
+	systemTools: number;
+	/** 扩展注册的 custom 工具定义的估算 token */
+	customTools: number;
+	/** AGENTS.md 等注入文件（contextResources 的 project 部分） */
+	memory: number;
+	/** 系统提示里的 skills 段 */
+	skills: number;
+	/** 最新一次压缩的摘要正文 */
+	compacted: number;
+	/** auto-compact 预留（compaction.reserveTokens 设置值；未启用为 0） */
+	autoCompactBuffer: number;
+}
+
 /** SSE 连接建立时先发的完整快照 */
 export interface WebSnapshot {
 	seq: number;
@@ -221,6 +243,8 @@ export interface WebSnapshot {
 	contextFiles: string[];
 	/** 注入的上下文资源（AGENTS.md 与扩展附加 prompt，来自 Pi 资源加载器）。 */
 	contextResources: ContextResource[];
+	/** 上下文占用的服务端估算分项（13 类分段里的非消息部分） */
+	contextBreakdown?: ContextBreakdown;
 	/** 斜杠命令数据源：技能 */
 	skills: { name: string; description: string }[];
 	/** 斜杠命令数据源：提示模板（~/.pi/agent/prompts、<cwd>/.pi/prompts 里的 .md） */

package/src/lib/update-service.ts

@@ -75,7 +75,7 @@ export function createUpdateService({ root = APP_ROOT, run = runCommand, version
 		const behind = Number((await command("git", ["rev-list", "--count", "HEAD..origin/main"], 15_000)).trim());
 		if (!Number.isSafeInteger(behind) || behind < 0) throw new Error("invalid upstream commit count");
 		const remotePkg = JSON.parse(await command("git", ["show", "origin/main:package.json"], 15_000)) as { name?: string; version?: string };
-		if ((remotePkg.name !== "piweb" && remotePkg.name !== "pi-web") || typeof remotePkg.version !== "string" || !remotePkg.version) throw new Error("upstream is not a PiWeb package");
+		if (!["piweb", "pi-web", "@rexvane/piweb"].includes(String(remotePkg.name)) || typeof remotePkg.version !== "string" || !remotePkg.version) throw new Error("upstream is not a PiWeb package");
 		// Do not advertise a tag version that `git pull origin main` will never install.
 		return { current: piWeb, latest: remotePkg.version, behind, canUpdate: isNewer(remotePkg.version, piWeb) || behind > 0 };
 	}

package/src/lib/workspace-store.ts

@@ -3,6 +3,7 @@
  * 会话 cwd + 手动添加的目录共同构成侧栏「工作区」列表；pi 不受影响（独立文件）。
  */
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { APP_ROOT } from "./app-root";
 import { spawn } from "node:child_process";
@@ -207,54 +208,91 @@ export async function removeWorkspace(dir: string): Promise<{ workspaces: string
 
 let picking = false;
 
-/** 弹出系统原生文件夹选择对话框（Windows 现代资源管理器风格，屏幕居中） */
+/** 收集子进程 stdout（utf8）与 stderr 尾部，带超时；退出码非 0 抛错 */
+function runDialog(argv: string[], opts: { timeoutMs?: number; windowsHide?: boolean } = {}): Promise<string> {
+	const { timeoutMs = 5 * 60 * 1000, windowsHide = false } = opts;
+	return new Promise<string>((resolve, reject) => {
+		const child = spawn(argv[0], argv.slice(1), { stdio: ["ignore", "pipe", "pipe"], windowsHide });
+		const decoder = new StringDecoder("utf8");
+		let buf = "";
+		let stderr = "";
+		let decoderEnded = false;
+		child.stdout.on("data", (data: Buffer) => {
+			buf += decoder.write(data);
+		});
+		child.stderr.on("data", (data: Buffer) => { stderr = (stderr + data.toString("utf8")).slice(-1000); });
+		let settled = false;
+		let timeout: ReturnType<typeof setTimeout>;
+		const finish = (error?: Error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			if (!decoderEnded) {
+				decoderEnded = true;
+				buf += decoder.end();
+			}
+			if (error) reject(error);
+			else resolve(buf.trim());
+		};
+		child.on("error", (error) => finish(error));
+		child.on("close", (code) => finish(code === 0 ? undefined : new Error(stderr || `folder picker exited with code ${code}`)));
+		timeout = setTimeout(() => {
+			try {
+				child.kill();
+			} catch {
+				/* ignore */
+			}
+			finish(new Error("folder picker timed out"));
+		}, timeoutMs);
+	});
+}
+
+/** osascript 的 POSIX path 输出带前后引号（可能含转义），剥成普通路径 */
+function unquoteApplePath(out: string): string {
+	const m = out.match(/^alias "?(.*?)"?$/s) ?? out.match(/^(\/.*)$/s);
+	return (m ? m[1] : out).trim();
+}
+
+/**
+ * 弹出系统原生文件夹选择对话框。
+ * - Windows：PowerShell 脚本（现代资源管理器风格，屏幕居中）
+ * - macOS：osascript choose folder（原生选择框）
+ * - Linux：zenity / kdialog（哪个可用用哪个）
+ * 都不可用时抛错，前端有手动输入路径的兜底入口。
+ */
 export async function pickFolderNative(): Promise<{ path: string | null; canceled: boolean }> {
-	if (process.platform !== "win32") throw new Error("native folder picker is currently available only on Windows");
 	if (picking) return { path: null, canceled: true };
 	picking = true;
 	try {
-		const script = path.join(APP_ROOT, "scripts", "pick-folder.ps1");
-		const out = await new Promise<string>((resolve, reject) => {
-			const child = spawn(
-				"powershell.exe",
-				["-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", script, "选择工作区文件夹"],
-				// windowsHide：不再先闪出一个黑色 PowerShell 控制台窗口，只出现资源管理器风格的选择对话框
-				{ stdio: ["ignore", "pipe", "pipe"], windowsHide: true },
+		if (process.platform === "win32") {
+			const script = path.join(APP_ROOT, "scripts", "pick-folder.ps1");
+			const out = await runDialog(
+				["powershell.exe", "-NoProfile", "-STA", "-ExecutionPolicy", "Bypass", "-File", script, "选择工作区文件夹"],
+				{ windowsHide: true },
 			);
-			const decoder = new StringDecoder("utf8");
-			let buf = "";
-			let stderr = "";
-			let decoderEnded = false;
-			child.stdout.on("data", (data: Buffer) => {
-				buf += decoder.write(data);
-			});
-			child.stderr.on("data", (data: Buffer) => { stderr = (stderr + data.toString("utf8")).slice(-1000); });
-			let settled = false;
-			let timeout: ReturnType<typeof setTimeout>;
-			const finish = (error?: Error) => {
-				if (settled) return;
-				settled = true;
-				clearTimeout(timeout);
-				if (!decoderEnded) {
-					decoderEnded = true;
-					buf += decoder.end();
-				}
-				if (error) reject(error);
-				else resolve(buf.trim());
-			};
-			child.on("error", (error) => finish(error));
-			child.on("close", (code) => finish(code === 0 ? undefined : new Error(stderr || `folder picker exited with code ${code}`)));
-			// 5 分钟超时保护
-			timeout = setTimeout(() => {
-				try {
-					child.kill();
-				} catch {
-					/* ignore */
-				}
-				finish(new Error("folder picker timed out"));
-			}, 5 * 60 * 1000);
-		});
-		return out ? { path: out, canceled: false } : { path: null, canceled: true };
+			return out ? { path: out, canceled: false } : { path: null, canceled: true };
+		}
+		if (process.platform === "darwin") {
+			const out = await runDialog(["osascript", "-e", 'choose folder with prompt "选择工作区文件夹"']);
+			const p = unquoteApplePath(out);
+			return p ? { path: p, canceled: false } : { path: null, canceled: true };
+		}
+		// Linux /其他：zenity → kdialog
+		for (const argv of [
+			["zenity", "--file-selection", "--directory", "--title=选择工作区文件夹"],
+			["kdialog", "--getexistingdirectory", `${os.homedir()}`, "--title", "选择工作区文件夹"],
+		]) {
+			try {
+				const out = await runDialog(argv);
+				return out ? { path: out, canceled: false } : { path: null, canceled: true };
+			} catch (error) {
+				// 未安装（ENOENT）→ 试下一个；用户取消的 zenity 退出码 1 但 stdout 可能为空
+				if (error instanceof Error && /ENOENT|not found|not recognized/i.test(error.message)) continue;
+				if (/exited with code (1|5)$/.test(error instanceof Error ? error.message : String(error))) return { path: null, canceled: true };
+				throw error;
+			}
+		}
+		throw new Error("no folder picker available: install zenity or kdialog, or type the path manually");
 	} finally {
 		picking = false;
 	}