@zhipu/zp-cli 0.0.0 → 0.0.1

package/README.md

@@ -1,23 +1,134 @@
-# vite-plus-starter
+# zp-cli
 
-A starter for creating a Vite Plus project.
+内部单命令部署工具（`@zhipu/zp-cli`）。用 `zpc pack` 构建打包、`zpc deploy` 在服务器上解压并挂到 Nginx / PM2。
 
-## Development
+路线图见 [docs/ROADMAP.md](./docs/ROADMAP.md)。
 
-- Install dependencies:
+## 使用
 
 ```bash
-vp install
+# 在项目根生成 zpc.config
+zpc init
+
+# 构建并打出 dist.zip（全量）
+zpc pack
+
+# 仅 api 增量包
+zpc pack -i
+
+# 在服务器上：目录内需有 dist.zip + zpc.config.*（配置不要打进压缩包）
+zpc deploy
+zpc deploy -i          # 增量（api 保留 public，跳过 web）
+zpc deploy --full      # 强制全量
+zpc deploy --force     # 允许抢占冲突的 nginx proxy
+```
+
+可选环境变量：`DEPLOY_DIR`、`DEPLOY_INCREMENTAL`、`DEPLOY_FORCE`；测试可用 `ZPC_API_ROOT` / `ZPC_WEB_ROOT` / `ZPC_NGINX_DEFAULT_D` / `ZPC_DEPLOY_SKIP_RUNTIME`。
+
+## 部署约定
+
+`zpc.config` 中的 `projectName` 即下文 `<system-tag>`。
+
+### 目录结构
+
+```text
+─┬─ etc/nginx/
+ │  ├─ default.d/
+ │  │  └─ <system-tag>.conf
+ │  └─ nginx.conf
+ └─ usr/share/nginx/
+    ├─ api/
+    │  └─ <system-tag>/
+    │     ├─ <api-1>/
+    │     │  ├─ dist
+    │     │  ├─ public
+    │     │  ├─ bootstrap.js
+    │     │  └─ package.json
+    │     ├─ <api-2>/
+    │     │  ├─ dist
+    │     │  ├─ public
+    │     │  ├─ bootstrap.js
+    │     │  └─ package.json
+    │     └─ ...
+    └─ html/
+       └─ <system-tag>/
+          ├─ <web-1>/
+          │  ├─ assets
+          │  └─ index.html
+          ├─ <web-2>/
+          │  ├─ assets
+          │  └─ index.html
+          └─ ...
 ```
 
-- Run the unit tests:
+### Nginx 配置
+
+1. 单系统配置放在 `/etc/nginx/default.d/`，文件名为 `<system-tag>.conf`（当前实现尚未完全对齐，见路线图「进行中」）：
+
+   ```text
+   location /<API_PROXY>/ {
+       proxy_pass http://127.0.0.1:<PORT>/;
+       proxy_http_version 1.1;
+       proxy_set_header Host $host;
+       proxy_set_header X-Real-IP $remote_addr;
+       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+       proxy_set_header X-Forwarded-Proto $scheme;
+       proxy_set_header Upgrade $http_upgrade;
+       proxy_set_header Connection "upgrade";
+   }
+
+   location = /<API_PROXY> {
+       return 301 /<API_PROXY>/;
+   }
+   ```
+
+2. 宿主机 `nginx.conf` 的 `server` 块须包含 `include`，以便加载系统配置（机器初始化时完成，非 `zpc deploy` 职责）：
+
+   ```text
+   server {
+       listen       80;
+       listen       [::]:80;
+       server_name  _;
+       root         /usr/share/nginx/html;
+
+       # Load configuration files for the default server block.
+       include /etc/nginx/default.d/*.conf;
+
+       error_page 404 /404.html;
+       location = /404.html {
+       }
+
+       error_page 500 502 503 504 /50x.html;
+       location = /50x.html {
+       }
+   }
+   ```
+
+服务器软件栈（Nginx、Node、pnpm、PM2 等）的一键安装不在本仓库范围，见路线图「展望」。
+
+## 开发
 
 ```bash
+# 安装依赖
+vp install
+# 校验（格式 / lint / 类型）
+vp check
+# 单元测试
 vp test
+# 构建可发布产物
+vp pack
+```
+
+## 发布
+
+因 pnpm 安全策略，access token 需配在用户级 npmrc（`~/.npmrc`）：
+
+```text
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
 ```
 
-- Build the library:
+在环境变量中设置 `NPM_TOKEN` 后发布：
 
 ```bash
-vp pack
+pnpm publish
 ```

package/dist/cli.d.mts

@@ -1,4 +1 @@
-//#region src/cli.d.ts
-declare function cli(): void;
-//#endregion
-export { cli };
+export {}

package/dist/cli.mjs

@@ -1,15 +1,702 @@
-//#region src/cli.ts
-const args = process.argv.slice(2);
-function cli() {
-	if (args.includes("--help")) {
-		console.log("Usage: zp-cli <command>");
-		process.exit(0);
+import { a as findConfigFile, c as loadConfig, l as templateFileName, n as SCHEMA_FILE_NAME, o as isConfigFormat, r as configFileName, s as listConfigFiles, t as CONFIG_FORMATS } from "./config-BZc9pg7J.mjs";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "@commander-js/extra-typings";
+import { spawn } from "node:child_process";
+import zlib from "node:zlib";
+//#region package.json
+var version = "0.0.1";
+var description = "内部单命令部署工具";
+//#endregion
+//#region src/utils/deploy-paths.ts
+/** 增量包标记（打进 dist.zip 根目录；deploy 据此拒绝误全量）。 */
+const INCREMENTAL_MARKER = ".deploy-incremental";
+function envPath(name, fallback) {
+	const value = process.env[name];
+	return value && value.trim() !== "" ? value : fallback;
+}
+/** API 静态/产物根目录（可用 ZPC_API_ROOT 覆盖，便于测试） */
+function getApiRoot() {
+	return envPath("ZPC_API_ROOT", "/usr/share/nginx/api");
+}
+/** Web 静态根目录 */
+function getWebRoot() {
+	return envPath("ZPC_WEB_ROOT", "/usr/share/nginx/html");
+}
+/** nginx location 片段目录（需被 server 块 include） */
+function getNginxDefaultD() {
+	return envPath("ZPC_NGINX_DEFAULT_D", "/etc/nginx/default.d");
+}
+/** 测试用：跳过 pnpm / pm2 / nginx */
+function shouldSkipDeployRuntime() {
+	return process.env.ZPC_DEPLOY_SKIP_RUNTIME === "1";
+}
+//#endregion
+//#region src/utils/run.ts
+function runCommand(command, args, opts = {}) {
+	return new Promise((resolve, reject) => {
+		const useCmd = opts.windowsCmd && process.platform === "win32";
+		const child = spawn(useCmd ? process.env.ComSpec || "cmd.exe" : command, useCmd ? [
+			"/d",
+			"/s",
+			"/c",
+			command,
+			...args
+		] : args, {
+			cwd: opts.cwd,
+			stdio: opts.stdio ?? "inherit",
+			windowsHide: true,
+			env: opts.env ? {
+				...process.env,
+				...opts.env
+			} : process.env
+		});
+		child.on("error", (err) => {
+			reject(/* @__PURE__ */ new Error(`无法启动 ${command}: ${err.message}`));
+		});
+		child.on("exit", (code) => {
+			if (code === 0 || opts.ignoreExit) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`${command} ${args.join(" ")} 退出码 ${code}${opts.cwd ? ` (cwd: ${opts.cwd})` : ""}`));
+		});
+	});
+}
+//#endregion
+//#region src/utils/templates.ts
+const require = createRequire(import.meta.url);
+function resolveTemplatesDir() {
+	return path.join(path.dirname(require.resolve("@zhipu/zp-cli/package.json")), "src", "templates");
+}
+function resolveTemplateFile(format) {
+	const file = path.join(resolveTemplatesDir(), templateFileName(format));
+	if (!fs.existsSync(file)) throw new Error(`[init] 缺少模板 ${templateFileName(format)}`);
+	return file;
+}
+function resolveSchemaFile() {
+	const file = path.join(resolveTemplatesDir(), SCHEMA_FILE_NAME);
+	if (!fs.existsSync(file)) throw new Error(`[init] 缺少 ${SCHEMA_FILE_NAME}`);
+	return file;
+}
+const NGINX_PROXY_TEMPLATE = "nginx-proxy.conf.template";
+function resolveNginxProxyTemplate() {
+	const file = path.join(resolveTemplatesDir(), NGINX_PROXY_TEMPLATE);
+	if (!fs.existsSync(file)) throw new Error(`[deploy] 缺少 ${NGINX_PROXY_TEMPLATE}`);
+	return file;
+}
+function renderTemplate(template, vars) {
+	return template.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+		if (!(key in vars)) throw new Error(`[template] 缺少变量 ${key}`);
+		return String(vars[key]);
+	});
+}
+//#endregion
+//#region src/utils/deploy-ops.ts
+function isSafeProxy(proxy) {
+	if (!proxy.startsWith("/") || proxy.length < 2) return false;
+	if (proxy.includes("..") || proxy.includes("//") || proxy.includes("\\")) return false;
+	return /^\/[A-Za-z0-9._/-]+$/.test(proxy);
+}
+function parsePort(env) {
+	if (!env || env.PORT == null || env.PORT === "") return null;
+	const n = Number(env.PORT);
+	if (!Number.isInteger(n) || n < 1 || n > 65535) return null;
+	return n;
+}
+function toEnvMap(env) {
+	const out = { NODE_ENV: "production" };
+	if (!env) return out;
+	for (const [key, value] of Object.entries(env)) {
+		if (value == null) continue;
+		out[key] = String(value);
+	}
+	return out;
+}
+function nginxLocation(proxy) {
+	return proxy.endsWith("/") ? proxy : `${proxy}/`;
+}
+function nginxOwnerId(projectName, name) {
+	return `${projectName}/${name}`;
+}
+function parseNginxOwnedBy(text) {
+	return text.match(/^#\s*owned-by:\s*(\S+)/m)?.[1] ?? null;
+}
+let nginxProxyTemplateCache;
+function loadNginxProxyTemplate() {
+	if (nginxProxyTemplateCache === void 0) nginxProxyTemplateCache = fs.readFileSync(resolveNginxProxyTemplate(), "utf8");
+	return nginxProxyTemplateCache;
+}
+function renderNginxProxy(proxy, port, ownerId) {
+	const loc = nginxLocation(proxy);
+	const exact = loc.slice(0, -1);
+	return renderTemplate(loadNginxProxyTemplate(), {
+		ownerId,
+		loc,
+		exact,
+		port
+	}).trimEnd() + "\n";
+}
+function confDefinesProxy(text, proxy) {
+	const loc = nginxLocation(proxy);
+	const exact = loc.slice(0, -1);
+	const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return new RegExp(`location\\s*=\\s*${esc(exact)}(?:\\s|\\{)`).test(text) || new RegExp(`location\\s+${esc(loc)}(?:\\s|\\{)`).test(text) || new RegExp(`location\\s+${esc(exact)}(?:\\s|\\{)`).test(text);
+}
+function assertNginxProxyAvailable(proxy, keepPath, ownerId, force, log) {
+	if (!fs.existsSync(getNginxDefaultD())) return;
+	const keep = path.resolve(keepPath);
+	const loc = nginxLocation(proxy);
+	for (const name of fs.readdirSync(getNginxDefaultD())) {
+		if (!name.endsWith(".conf")) continue;
+		const full = path.join(getNginxDefaultD(), name);
+		if (path.resolve(full) === keep) continue;
+		let text;
+		try {
+			text = fs.readFileSync(full, "utf8");
+		} catch {
+			continue;
+		}
+		if (!confDefinesProxy(text, proxy)) continue;
+		const owned = parseNginxOwnedBy(text);
+		if (force) {
+			log(`--force：删除冲突 nginx 配置 ${full}（与 ${loc} 重复，原归属 ${owned ?? "未知"}）`);
+			fs.unlinkSync(full);
+			continue;
+		}
+		const who = owned ? `归属 ${owned}` : "无归属标记（可能为其它项目或旧配置）";
+		throw new Error(`[deploy] nginx proxy ${loc} 已被占用: ${full}（${who}）。当前部署归属 ${ownerId}。若确认抢占请加 --force`);
+	}
+}
+/** 部署期额外校验：proxy 合法性、配 proxy 时必须有 PORT。 */
+function assertDeployConfig(config) {
+	for (const item of config.web ?? []) if (item.proxy != null) throw new Error(`[deploy] 只有 api 项可以配置 proxy（web/${item.name}）`);
+	for (const item of config.api ?? []) {
+		if (item.proxy == null) continue;
+		const proxy = item.proxy;
+		if (!isSafeProxy(proxy)) throw new Error(`[deploy] api/${item.name} 的 proxy 不合法: ${proxy}`);
+		if (parsePort(item.env) == null) throw new Error(`[deploy] api/${item.name} 配置了 proxy，需要 env.PORT（1–65535）`);
+	}
+}
+function isSafeDirName(name) {
+	if (!name || name === "." || name === "..") return false;
+	return !name.includes("/") && !name.includes("\\") && !name.includes("\0");
+}
+function listNamedDirs(parent) {
+	if (!fs.existsSync(parent)) return [];
+	return fs.readdirSync(parent, { withFileTypes: true }).filter((d) => d.isDirectory() && isSafeDirName(d.name) && !d.name.startsWith(".")).map((d) => d.name);
+}
+/** 原子风格替换目录：删旧 `.bak` → 现目录改名为 `.bak` → 拷入新内容。 */
+function deployDir(src, dest, log) {
+	fs.mkdirSync(path.dirname(dest), { recursive: true });
+	const bak = `${dest}.bak`;
+	if (fs.existsSync(bak)) {
+		log(`删除旧备份 ${bak}`);
+		fs.rmSync(bak, {
+			recursive: true,
+			force: true
+		});
+	}
+	if (fs.existsSync(dest)) {
+		log(`备份 ${dest} -> ${bak}`);
+		fs.renameSync(dest, bak);
+	}
+	try {
+		fs.cpSync(src, dest, { recursive: true });
+		log(`全量部署 ${src} -> ${dest}`);
+	} catch (err) {
+		if (fs.existsSync(bak) && !fs.existsSync(dest)) {
+			fs.renameSync(bak, dest);
+			log(`部署失败，已从备份恢复 ${dest}`);
+		}
+		throw err;
+	}
+}
+const API_INCREMENTAL_FILES = ["package.json", "bootstrap.js"];
+/** api 增量部署：只替换 dist 与根部 package.json / bootstrap.js，不碰 public。 */
+function deployApiIncremental(src, dest, log) {
+	const distSrc = path.join(src, "dist");
+	if (!fs.existsSync(distSrc)) throw new Error(`[deploy] ${src} 缺少 dist，无法增量部署`);
+	fs.mkdirSync(dest, { recursive: true });
+	const distDest = path.join(dest, "dist");
+	const distBak = `${distDest}.bak`;
+	if (fs.existsSync(distBak)) fs.rmSync(distBak, {
+		recursive: true,
+		force: true
+	});
+	if (fs.existsSync(distDest)) fs.renameSync(distDest, distBak);
+	try {
+		fs.cpSync(distSrc, distDest, { recursive: true });
+	} catch (err) {
+		if (fs.existsSync(distBak) && !fs.existsSync(distDest)) fs.renameSync(distBak, distDest);
+		throw err;
+	}
+	if (fs.existsSync(distBak)) fs.rmSync(distBak, {
+		recursive: true,
+		force: true
+	});
+	for (const file of API_INCREMENTAL_FILES) {
+		const from = path.join(src, file);
+		if (!fs.existsSync(from)) throw new Error(`[deploy] ${src} 缺少 ${file}，无法增量部署`);
+		fs.cpSync(from, path.join(dest, file));
+	}
+	fs.mkdirSync(path.join(dest, "public"), { recursive: true });
+	log(`增量部署 ${src} -> ${dest}（更新 dist、${API_INCREMENTAL_FILES.join("、")}，保留 public）`);
+}
+async function installAndReloadApi(name, dest, item, log) {
+	if (!fs.existsSync(path.join(dest, "package.json"))) throw new Error(`[deploy] ${dest} 缺少 package.json，无法 pnpm i`);
+	if (!fs.existsSync(path.join(dest, "bootstrap.js"))) throw new Error(`[deploy] ${dest} 缺少 bootstrap.js，无法用 pm2 启动`);
+	log(`pnpm i --prod @ ${dest}`);
+	await runCommand("pnpm", [
+		"i",
+		"--prod",
+		"--dangerously-allow-all-builds"
+	], { cwd: dest });
+	const env = toEnvMap(item.env);
+	const ecoPath = path.join(dest, "ecosystem.config.cjs");
+	fs.writeFileSync(ecoPath, `module.exports = ${JSON.stringify({ apps: [{
+		name,
+		script: "bootstrap.js",
+		env
+	}] }, null, 2)};\n`);
+	log(`pm2 startOrReload ${name}，注入 ${Object.keys(env).join(", ")}`);
+	await runCommand("pm2", [
+		"startOrReload",
+		ecoPath,
+		"--update-env"
+	], {
+		cwd: dest,
+		env: {
+			...process.env,
+			...env
+		}
+	});
+}
+async function configureNginxProxies(projectName, apis, force, log) {
+	const items = (apis ?? []).filter((item) => item.proxy);
+	if (!items.length) {
+		log("未配置 api.proxy，跳过 nginx location");
+		return;
+	}
+	const seen = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const key = nginxLocation(item.proxy);
+		if (seen.has(key)) throw new Error(`[deploy] 同一份配置里 proxy 重复: ${key}（${seen.get(key)} 与 ${item.name}）`);
+		seen.set(key, item.name);
+	}
+	fs.mkdirSync(getNginxDefaultD(), { recursive: true });
+	for (const item of items) {
+		const port = parsePort(item.env);
+		if (port == null) throw new Error(`[deploy] ${item.name} 缺少合法 env.PORT`);
+		const ownerId = nginxOwnerId(projectName, item.name);
+		const confPath = path.join(getNginxDefaultD(), `${projectName}-${item.name}.conf`);
+		assertNginxProxyAvailable(item.proxy, confPath, ownerId, force, log);
+		fs.writeFileSync(confPath, renderNginxProxy(item.proxy, port, ownerId));
+		log(`nginx ${nginxLocation(item.proxy)} -> 127.0.0.1:${port}（bypass 前缀，owned-by ${ownerId}）`);
+	}
+	await runCommand("nginx", ["-t"]);
+	try {
+		await runCommand("nginx", ["-s", "reload"]);
+	} catch {
+		await runCommand("systemctl", ["reload", "nginx"]);
+	}
+	log("nginx 已 reload");
+}
+//#endregion
+//#region src/utils/zip.ts
+/** ZIP End of Central Directory 签名 */
+const SIG_EOCD = 101010256;
+/** ZIP Central Directory 文件头签名 */
+const SIG_CD = 33639248;
+/** ZIP Local file header 签名 */
+const SIG_LOCAL = 67324752;
+function readHead(filePath, length = 4) {
+	const fd = fs.openSync(filePath, "r");
+	try {
+		const buf = Buffer.alloc(length);
+		const n = fs.readSync(fd, buf, 0, length, 0);
+		return buf.subarray(0, n);
+	} finally {
+		fs.closeSync(fd);
+	}
+}
+function isZip(filePath) {
+	const head = readHead(filePath);
+	return head.length >= 4 && head[0] === 80 && head[1] === 75;
+}
+function findEocdOffset(buf) {
+	const min = 22;
+	if (buf.length < min) throw new Error("zip 文件过小");
+	const maxScan = Math.min(buf.length, 65557);
+	for (let i = buf.length - min; i >= buf.length - maxScan; i--) if (buf.readUInt32LE(i) === SIG_EOCD) return i;
+	throw new Error("找不到 zip 目录结尾（EOCD）");
+}
+function inflateZipData(method, data) {
+	if (method === 0) return data;
+	if (method === 8) return zlib.inflateRawSync(data);
+	throw new Error(`不支持的 zip 压缩方式: ${method}`);
+}
+function resolveZipEntry(dest, name) {
+	const normalized = name.replace(/\\/g, "/");
+	const parts = normalized.split("/").filter((p) => p && p !== ".");
+	if (parts.includes("..")) throw new Error(`非法 zip 路径: ${name}`);
+	const target = path.resolve(dest, ...parts);
+	const root = path.resolve(dest);
+	const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+	if (target !== root && !target.startsWith(prefix)) throw new Error(`非法 zip 路径: ${name}`);
+	return {
+		target,
+		isDir: normalized.endsWith("/")
+	};
+}
+/** 用 Node 解析 ZIP 并解压到 dest（兼容 Windows `tar -a`；不依赖系统 unzip）。 */
+function unzipTo(zipPath, dest) {
+	const buf = fs.readFileSync(zipPath);
+	const eocd = findEocdOffset(buf);
+	const entryCount = buf.readUInt16LE(eocd + 10);
+	const cdSize = buf.readUInt32LE(eocd + 12);
+	const cdOffset = buf.readUInt32LE(eocd + 16);
+	if (cdOffset === 4294967295 || cdSize === 4294967295) throw new Error("不支持 Zip64 压缩包");
+	let off = cdOffset;
+	const cdEnd = cdOffset + cdSize;
+	for (let i = 0; i < entryCount && off + 46 <= buf.length && off < cdEnd; i++) {
+		if (buf.readUInt32LE(off) !== SIG_CD) throw new Error("zip central directory 损坏");
+		const method = buf.readUInt16LE(off + 10);
+		const compSize = buf.readUInt32LE(off + 20);
+		const nameLen = buf.readUInt16LE(off + 28);
+		const extraLen = buf.readUInt16LE(off + 30);
+		const commentLen = buf.readUInt16LE(off + 32);
+		const localOff = buf.readUInt32LE(off + 42);
+		const name = buf.toString("utf8", off + 46, off + 46 + nameLen);
+		off += 46 + nameLen + extraLen + commentLen;
+		const { target, isDir } = resolveZipEntry(dest, name);
+		if (isDir) {
+			fs.mkdirSync(target, { recursive: true });
+			continue;
+		}
+		if (buf.readUInt32LE(localOff) !== SIG_LOCAL) throw new Error(`zip local header 损坏: ${name}`);
+		const localNameLen = buf.readUInt16LE(localOff + 26);
+		const localExtraLen = buf.readUInt16LE(localOff + 28);
+		const dataStart = localOff + 30 + localNameLen + localExtraLen;
+		const data = buf.subarray(dataStart, dataStart + compSize);
+		fs.mkdirSync(path.dirname(target), { recursive: true });
+		fs.writeFileSync(target, inflateZipData(method, data));
+	}
+}
+/** 解压压缩包到 dest：ZIP 走 Node 实现，否则尝试系统 tar。 */
+async function extractArchive(zipPath, dest) {
+	fs.rmSync(dest, {
+		recursive: true,
+		force: true
+	});
+	fs.mkdirSync(dest, { recursive: true });
+	if (isZip(zipPath)) {
+		unzipTo(zipPath, dest);
+		return;
+	}
+	await runCommand("tar", [
+		"-xf",
+		zipPath,
+		"-C",
+		dest
+	]);
+}
+/** 将 staging 打成 zip（Windows / 通用: tar -a）。 */
+async function zipDirectory(stagingDir, zipPath, cwd) {
+	if (fs.existsSync(zipPath)) fs.rmSync(zipPath);
+	await runCommand("tar", [
+		"-a",
+		"-cf",
+		zipPath,
+		"-C",
+		stagingDir,
+		"."
+	], {
+		cwd,
+		windowsCmd: true
+	});
+}
+//#endregion
+//#region src/commands/deploy.ts
+function log$1(message) {
+	console.log(`[deploy] ${message}`);
+}
+function envFlag(name) {
+	const value = process.env[name];
+	return value === "1" || value === "true";
+}
+function resolveFlags(options) {
+	const forceFull = Boolean(options.full);
+	const force = Boolean(options.force) || envFlag("DEPLOY_FORCE");
+	let wantIncremental = Boolean(options.incremental) || envFlag("DEPLOY_INCREMENTAL");
+	if (forceFull) wantIncremental = false;
+	return {
+		wantIncremental,
+		forceFull,
+		force
+	};
+}
+function hasProjectFiles(dir) {
+	return fs.existsSync(path.join(dir, "dist.zip")) && Boolean(findConfigFile(dir));
+}
+function resolveProjectDir(dirArg) {
+	let dir;
+	if (dirArg) {
+		const abs = path.resolve(dirArg);
+		if (!fs.existsSync(abs)) throw new Error(`[deploy] 找不到路径: ${abs}`);
+		dir = fs.statSync(abs).isDirectory() ? abs : path.dirname(abs);
+	} else if (process.env.DEPLOY_DIR) dir = path.resolve(process.env.DEPLOY_DIR);
+	else dir = process.cwd();
+	if (!hasProjectFiles(dir)) throw new Error(`[deploy] ${dir} 中需要同时有 dist.zip 和 zpc.config.*（配置请单独上传，不要打进压缩包）`);
+	return dir;
+}
+async function deployKind(stagingDir, items, kind, destRoot, projectName, incremental) {
+	const packed = new Set(listNamedDirs(path.join(stagingDir, kind)));
+	const configured = items ?? [];
+	for (const extra of packed) if (!configured.some((item) => item.name === extra)) log$1(`跳过压缩包中的 ${kind}/${extra}（未在配置中列出）`);
+	for (const item of configured) {
+		const src = path.join(stagingDir, kind, item.name);
+		if (!fs.existsSync(src)) throw new Error(`[deploy] 配置中有 ${kind}/${item.name}，但压缩包中没有对应目录`);
+		const dest = path.join(destRoot, projectName, item.name);
+		const pm2Name = `${projectName}-${item.name}`;
+		if (kind === "api" && incremental && fs.existsSync(dest)) deployApiIncremental(src, dest, log$1);
+		else {
+			if (kind === "api" && incremental && !fs.existsSync(dest)) log$1(`${dest} 不存在，增量改为全量部署`);
+			deployDir(src, dest, log$1);
+		}
+		if (kind === "api" && !shouldSkipDeployRuntime()) await installAndReloadApi(pm2Name, dest, item, log$1);
+	}
+}
+async function runDeploy(dir, options) {
+	const { wantIncremental, forceFull, force } = resolveFlags(options);
+	const projectDir = resolveProjectDir(dir);
+	const stagingDir = path.join(projectDir, ".deploy-staging");
+	const zipPath = path.join(projectDir, "dist.zip");
+	const { file, config } = await loadConfig(projectDir);
+	assertDeployConfig(config);
+	log$1(`项目目录: ${projectDir}`);
+	log$1(`压缩包: ${zipPath}`);
+	log$1(`配置: ${file}`);
+	log$1(`项目: ${config.projectName}`);
+	try {
+		log$1(`解压 ${zipPath}`);
+		await extractArchive(zipPath, stagingDir);
+	} catch (err) {
+		fs.rmSync(stagingDir, {
+			recursive: true,
+			force: true
+		});
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`[deploy] 解压失败: ${message}`);
 	}
-	if (args.includes("--version")) {
-		console.log("zp-cli 0.0.1");
-		process.exit(0);
+	const packIsIncremental = fs.existsSync(path.join(stagingDir, INCREMENTAL_MARKER));
+	let incremental = wantIncremental || packIsIncremental;
+	try {
+		if (packIsIncremental && forceFull) throw new Error("[deploy] 当前 dist.zip 是增量包（含 .deploy-incremental），不能 --full，请使用 --incremental，或重新 pack 全量包");
+		if (packIsIncremental && !wantIncremental) throw new Error("[deploy] 当前 dist.zip 是增量包（由 zpc pack -i 生成），请加上 --incremental / -i，以免全量覆盖清空 public");
+		incremental = wantIncremental || packIsIncremental;
+		log$1(`模式: ${incremental ? "增量（api 保留 public，跳过 web）" : "全量"}`);
+		if (force) log$1("已启用 --force（允许抢占冲突的 nginx proxy）");
+		await deployKind(stagingDir, config.api, "api", getApiRoot(), config.projectName, incremental);
+		if (!incremental) await deployKind(stagingDir, config.web, "web", getWebRoot(), config.projectName, false);
+		else if (config.web?.length) log$1("增量模式跳过 web 部署");
+	} finally {
+		fs.rmSync(stagingDir, {
+			recursive: true,
+			force: true
+		});
 	}
+	if (!shouldSkipDeployRuntime()) {
+		await configureNginxProxies(config.projectName, config.api, force, log$1);
+		if (config.api?.length) await runCommand("pm2", ["save"], { ignoreExit: true });
+	}
+	const apiCount = config.api?.length ?? 0;
+	const webCount = incremental ? 0 : config.web?.length ?? 0;
+	const prefix = `${config.projectName}/<name>`;
+	log$1(`完成: api ${apiCount} 个 -> ${getApiRoot()}/${prefix}，web ${webCount} 个 -> ${getWebRoot()}/${prefix}`);
+}
+function createDeployCommand() {
+	return new Command("deploy").description("按 zpc.config 将 dist.zip 部署到服务器").argument("[dir]", "项目目录，默认为当前目录").option("-i, --incremental", "增量部署（api 保留 public，跳过 web）").option("--full", "全量部署").option("--force", "允许抢占冲突的 nginx proxy").action(async (dir, options) => {
+		await runDeploy(dir, options);
+	});
+}
+//#endregion
+//#region src/commands/init.ts
+async function runInit(dir, options) {
+	const format = resolveFormat(options.template);
+	const root = path.resolve(dir ?? process.cwd());
+	const dest = path.join(root, configFileName(format));
+	const schemaDest = path.join(root, SCHEMA_FILE_NAME);
+	const existing = listConfigFiles(root);
+	if (existing.length > 0 && !options.force) {
+		const names = existing.map((file) => path.basename(file)).join("、");
+		throw new Error(`[init] 已存在 ${names}，如需覆盖请加 --force`);
+	}
+	fs.mkdirSync(root, { recursive: true });
+	for (const file of existing) if (file !== dest) fs.rmSync(file);
+	fs.copyFileSync(resolveTemplateFile(format), dest);
+	console.log(`[init] 已写入 ${dest}`);
+	if (format === "json") {
+		fs.copyFileSync(resolveSchemaFile(), schemaDest);
+		console.log(`[init] 已写入 ${schemaDest}`);
+	} else if (fs.existsSync(schemaDest)) fs.rmSync(schemaDest);
+}
+function resolveFormat(template) {
+	const format = template ?? "json";
+	if (!isConfigFormat(format)) throw new Error(`[init] 不支持的模板 ${format}，可选：${CONFIG_FORMATS.join(", ")}`);
+	return format;
 }
-cli();
+function createInitCommand() {
+	return new Command("init").description("在项目目录生成 zpc.config 配置文件").argument("[dir]", "项目目录，默认为当前目录").option("-f, --force", "覆盖已有 zpc.config 文件").option("-t, --template <format>", `配置文件格式：${CONFIG_FORMATS.join(" / ")}`, "json").action(async (dir, options) => {
+		await runInit(dir, options);
+	});
+}
+//#endregion
+//#region src/commands/pack.ts
+function log(message) {
+	console.log(`[pack] ${message}`);
+}
+function resolveIncremental(options) {
+	if (options.full) return false;
+	return Boolean(options.incremental);
+}
+function resolveProjects(root, config, incremental) {
+	const projects = [];
+	const kinds = incremental ? ["api"] : ["api", "web"];
+	for (const kind of kinds) {
+		const items = config[kind];
+		if (items == null) continue;
+		for (const item of items) {
+			const absPath = path.resolve(root, item.path);
+			if (!fs.existsSync(absPath)) throw new Error(`[pack] 项目目录不存在: ${absPath} (${kind}/${item.name})`);
+			const pkgJson = path.join(absPath, "package.json");
+			if (!fs.existsSync(pkgJson)) throw new Error(`[pack] 缺少 package.json: ${pkgJson} (${kind}/${item.name})`);
+			projects.push({
+				...item,
+				kind,
+				absPath,
+				distPath: path.join(absPath, "dist")
+			});
+		}
+	}
+	if (projects.length === 0) throw new Error(incremental ? "[pack] 增量打包需要配置中至少有一个 api 项目" : "[pack] 配置中没有 api / web 项目");
+	return projects;
+}
+function resolveBuildEnv(project, config) {
+	const env = { ...process.env };
+	if (project.buildEnv) for (const [key, value] of Object.entries(project.buildEnv)) env[key] = String(value);
+	if (project.kind === "web" && !env.VITE_API_PROXY) {
+		let proxy = project.proxy;
+		if (!proxy) {
+			const apis = (config.api ?? []).filter((a) => typeof a.proxy === "string" && a.proxy);
+			if (apis.length === 1) proxy = apis[0].proxy;
+		}
+		if (proxy) env.VITE_API_PROXY = proxy.endsWith("/") ? proxy.slice(0, -1) : proxy;
+	}
+	return env;
+}
+async function buildAll(projects, config) {
+	log(`并行构建 ${projects.length} 个项目`);
+	await Promise.all(projects.map(async (project) => {
+		const env = resolveBuildEnv(project, config);
+		if (project.kind === "web" && env.VITE_API_PROXY) log(`build ${project.kind}/${project.name} VITE_API_PROXY=${env.VITE_API_PROXY}`);
+		else log(`build ${project.kind}/${project.name} -> ${project.absPath}`);
+		await runCommand("npm", ["run", "build"], {
+			cwd: project.absPath,
+			env,
+			windowsCmd: true
+		});
+	}));
+}
+function copyRequiredFile(src, destDir, label) {
+	if (!fs.existsSync(src)) throw new Error(`[pack] 缺少 ${label}: ${src}`);
+	fs.cpSync(src, path.join(destDir, path.basename(src)));
+}
+function stageApi(project, dest, incremental) {
+	fs.mkdirSync(dest, { recursive: true });
+	fs.cpSync(project.distPath, path.join(dest, "dist"), { recursive: true });
+	copyRequiredFile(path.join(project.absPath, "package.json"), dest, "package.json");
+	copyRequiredFile(path.join(project.absPath, "bootstrap.js"), dest, "bootstrap.js");
+	if (incremental) {
+		log(`api/${project.name} 增量：跳过 public`);
+		return;
+	}
+	const publicDir = path.join(project.absPath, "public");
+	const destPublic = path.join(dest, "public");
+	if (fs.existsSync(publicDir)) fs.cpSync(publicDir, destPublic, { recursive: true });
+	else fs.mkdirSync(destPublic, { recursive: true });
+}
+function stageDist(stagingDir, root, projects, incremental) {
+	fs.rmSync(stagingDir, {
+		recursive: true,
+		force: true
+	});
+	fs.mkdirSync(stagingDir, { recursive: true });
+	if (incremental) fs.writeFileSync(path.join(stagingDir, INCREMENTAL_MARKER), "1\n");
+	for (const project of projects) {
+		if (!fs.existsSync(project.distPath)) throw new Error(`[pack] 构建产物不存在: ${project.distPath} (${project.kind}/${project.name})`);
+		const dest = path.join(stagingDir, project.kind, project.name);
+		if (project.kind === "api") stageApi(project, dest, incremental);
+		else fs.cpSync(project.distPath, dest, { recursive: true });
+		log(`收集 ${project.kind}/${project.name} -> ${path.relative(root, dest)}`);
+	}
+}
+async function runPack(dir, options) {
+	const root = path.resolve(dir ?? process.cwd());
+	if (!fs.existsSync(root)) throw new Error(`[pack] 找不到路径: ${root}`);
+	const projectRoot = fs.statSync(root).isDirectory() ? root : path.dirname(root);
+	const incremental = resolveIncremental(options);
+	const stagingDir = path.join(projectRoot, ".packup-staging");
+	const zipPath = path.join(projectRoot, "dist.zip");
+	const { file, config } = await loadConfig(projectRoot);
+	log(`项目目录: ${projectRoot}`);
+	log(`配置: ${file}`);
+	log(`项目: ${config.projectName}`);
+	log(`模式: ${incremental ? "增量（仅 api，不含 public）" : "全量"}`);
+	const projects = resolveProjects(projectRoot, config, incremental);
+	await buildAll(projects, config);
+	stageDist(stagingDir, projectRoot, projects, incremental);
+	try {
+		log(`压缩 ${path.relative(projectRoot, zipPath)}`);
+		await zipDirectory(stagingDir, zipPath, projectRoot);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`[pack] 打包失败（需要系统 tar）: ${message}`);
+	} finally {
+		fs.rmSync(stagingDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	log(`完成: ${zipPath}`);
+	if (incremental) log("请使用: zpc deploy --incremental");
+}
+function createPackCommand() {
+	return new Command("pack").description("按 zpc.config 构建并打包 dist.zip").argument("[dir]", "项目目录，默认为当前目录").option("-i, --incremental", "增量打包（仅 api，不含 public）").option("--full", "全量打包").action(async (dir, options) => {
+		await runPack(dir, options);
+	});
+}
+//#endregion
+//#region src/utils/program.ts
+function createProgram() {
+	const program = new Command().name("zpc").description(description).version(version).showHelpAfterError().addCommand(createInitCommand()).addCommand(createPackCommand()).addCommand(createDeployCommand());
+	program.action(() => {
+		program.outputHelp();
+	});
+	return program;
+}
+async function runCli(argv = process.argv) {
+	try {
+		await createProgram().parseAsync(argv);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.error(message);
+		process.exitCode = 1;
+	}
+}
+//#endregion
+//#region src/cli.ts
+runCli();
 //#endregion
-export { cli };
+export {};

package/dist/config-BZc9pg7J.mjs

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createJiti } from "jiti";
+//#region src/utils/config.ts
+const CONFIG_FILE_PREFIX = "zpc.config";
+const SCHEMA_FILE_NAME = `${CONFIG_FILE_PREFIX}.schema.json`;
+const CONFIG_FORMATS = [
+	"ts",
+	"mts",
+	"cts",
+	"js",
+	"mjs",
+	"cjs",
+	"json"
+];
+function defineConfig(config) {
+	return config;
+}
+function isConfigFormat(value) {
+	return CONFIG_FORMATS.includes(value);
+}
+function configFileName(format) {
+	return `${CONFIG_FILE_PREFIX}.${format}`;
+}
+function templateFileName(format) {
+	return `${configFileName(format)}.template`;
+}
+const jiti = createJiti(import.meta.url);
+function listConfigFiles(dir) {
+	return CONFIG_FORMATS.map((format) => path.join(dir, configFileName(format))).filter((file) => fs.existsSync(file));
+}
+function findConfigFile(dir) {
+	return listConfigFiles(dir)[0];
+}
+async function loadConfig(dir) {
+	const file = findConfigFile(dir);
+	if (!file) throw new Error(`[config] 在 ${dir} 找不到 ${CONFIG_FILE_PREFIX}.{${CONFIG_FORMATS.join(",")}}，请先运行 zpc init`);
+	let loaded;
+	try {
+		loaded = await readConfigFile(file);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`[config] 无法加载 ${file}: ${message}`);
+	}
+	return {
+		file,
+		config: validateConfig(loaded, file)
+	};
+}
+async function readConfigFile(file) {
+	if (file.endsWith(".json")) return JSON.parse(fs.readFileSync(file, "utf8"));
+	return await jiti.import(file, { default: true });
+}
+function validateConfig(config, source) {
+	if (!isPlainObject(config)) throw new Error(`[config] ${source} 必须导出一个对象`);
+	if (!isSafeName(config.projectName)) throw new Error(`[config] ${source} 缺少合法 projectName`);
+	const api = optionalAppList(config.api, "api", source);
+	const web = optionalAppList(config.web, "web", source);
+	if (api.length === 0 && web.length === 0) throw new Error(`[config] ${source} 中没有 api / web 项目`);
+	return {
+		projectName: config.projectName,
+		...api.length ? { api } : {},
+		...web.length ? { web } : {}
+	};
+}
+function optionalAppList(value, kind, source) {
+	if (value == null) return [];
+	if (!Array.isArray(value)) throw new Error(`[config] ${source} 中 ${kind} 必须是数组`);
+	return value.map((item, index) => parseAppConfig(item, `${source} ${kind}[${index}]`));
+}
+function parseAppConfig(item, label) {
+	if (!isPlainObject(item)) throw new Error(`[config] ${label} 必须是对象`);
+	if (typeof item.path !== "string" || item.path.trim() === "") throw new Error(`[config] ${label} 缺少 path`);
+	if (!isSafeName(item.name)) throw new Error(`[config] ${label} 缺少合法 name`);
+	const parsed = {
+		path: item.path,
+		name: item.name
+	};
+	if (item.proxy != null) {
+		if (typeof item.proxy !== "string") throw new Error(`[config] ${label} 的 proxy 必须是字符串`);
+		parsed.proxy = item.proxy;
+	}
+	if (item.buildEnv != null) parsed.buildEnv = parseEnvMap(item.buildEnv, `${label} buildEnv`);
+	if (item.env != null) parsed.env = parseEnvMap(item.env, `${label} env`);
+	return parsed;
+}
+function parseEnvMap(value, label) {
+	if (!isPlainObject(value)) throw new Error(`[config] ${label} 必须是对象`);
+	const out = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`[config] ${label} 含非法环境变量名: ${key}`);
+		if (typeof entry !== "string" && typeof entry !== "number" && typeof entry !== "boolean") throw new Error(`[config] ${label}.${key} 必须是 string / number / boolean`);
+		out[key] = entry;
+	}
+	return out;
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSafeName(name) {
+	if (typeof name !== "string" || name === "" || name === "." || name === "..") return false;
+	return !name.includes("/") && !name.includes("\\") && !name.includes(String.fromCharCode(0));
+}
+//#endregion
+export { findConfigFile as a, loadConfig as c, defineConfig as i, templateFileName as l, SCHEMA_FILE_NAME as n, isConfigFormat as o, configFileName as r, listConfigFiles as s, CONFIG_FORMATS as t };

package/dist/index.d.mts

@@ -1,4 +1,24 @@
-//#region src/index.d.ts
-declare function fn(): string;
+//#region src/utils/config.d.ts
+declare const CONFIG_FORMATS: readonly ["ts", "mts", "cts", "js", "mjs", "cjs", "json"];
+type ConfigFormat = (typeof CONFIG_FORMATS)[number];
+type ZpcEnvMap = Record<string, string | number | boolean>;
+interface ZpcAppConfig {
+  /** 相对项目根的源码目录 */
+  path: string;
+  /** 打包 / 部署目录名 */
+  name: string;
+  /** api 对外路径前缀；web 未写 buildEnv.VITE_API_PROXY 时也可作回退 */
+  proxy?: string;
+  /** 仅构建期注入 */
+  buildEnv?: ZpcEnvMap;
+  /** 仅运行时注入（pm2） */
+  env?: ZpcEnvMap;
+}
+interface ZpcConfig {
+  projectName: string;
+  api?: ZpcAppConfig[];
+  web?: ZpcAppConfig[];
+}
+declare function defineConfig(config: ZpcConfig): ZpcConfig;
 //#endregion
-export { fn };
+export { type ConfigFormat, type ZpcAppConfig, type ZpcConfig, type ZpcEnvMap, defineConfig };

package/dist/index.mjs

@@ -1,6 +1,2 @@
-//#region src/index.ts
-function fn() {
-	return "Hello, tsdown!";
-}
-//#endregion
-export { fn };
+import { i as defineConfig } from "./config-BZc9pg7J.mjs";
+export { defineConfig };

package/package.json

@@ -1,22 +1,27 @@
 {
   "name": "@zhipu/zp-cli",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "内部单命令部署工具",
   "bin": {
     "zpc": "./dist/cli.mjs"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/templates"
   ],
   "type": "module",
   "exports": {
     ".": "./dist/index.mjs",
-    "./cli": "./dist/cli.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@commander-js/extra-typings": "^15.0.0",
+    "commander": "^15.0.0",
+    "jiti": "^2.7.0"
+  },
   "devDependencies": {
     "@types/node": "^26.1.1",
     "bumpp": "^11.1.0",

package/src/templates/nginx-proxy.conf.template

@@ -0,0 +1,16 @@
+# generated by zpc deploy
+# owned-by: {{ownerId}}
+location {{loc}} {
+    proxy_pass http://127.0.0.1:{{port}}/;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+}
+
+location = {{exact}} {
+    return 301 {{loc}};
+}

package/src/templates/zpc.config.cjs.template

@@ -0,0 +1,20 @@
+/** @type {import("@zhipu/zp-cli").ZpcConfig} */
+module.exports = {
+  projectName: "my-project",
+  api: [
+    {
+      path: "api",
+      name: "api",
+      proxy: "/api",
+      env: {
+        PORT: 3000,
+      },
+    },
+  ],
+  web: [
+    {
+      path: "web",
+      name: "web",
+    },
+  ],
+};

package/src/templates/zpc.config.cts.template

@@ -0,0 +1,21 @@
+import { defineConfig } from "@zhipu/zp-cli";
+
+export default defineConfig({
+  projectName: "my-project",
+  api: [
+    {
+      path: "api",
+      name: "api",
+      proxy: "/api",
+      env: {
+        PORT: 3000,
+      },
+    },
+  ],
+  web: [
+    {
+      path: "web",
+      name: "web",
+    },
+  ],
+});

package/src/templates/zpc.config.js.template

@@ -0,0 +1,21 @@
+import { defineConfig } from "@zhipu/zp-cli";
+
+export default defineConfig({
+  projectName: "my-project",
+  api: [
+    {
+      path: "api",
+      name: "api",
+      proxy: "/api",
+      env: {
+        PORT: 3000,
+      },
+    },
+  ],
+  web: [
+    {
+      path: "web",
+      name: "web",
+    },
+  ],
+});

package/src/templates/zpc.config.json.template

@@ -0,0 +1,20 @@
+{
+  "$schema": "./zpc.config.schema.json",
+  "projectName": "my-project",
+  "api": [
+    {
+      "path": "api",
+      "name": "api",
+      "proxy": "/api",
+      "env": {
+        "PORT": 3000
+      }
+    }
+  ],
+  "web": [
+    {
+      "path": "web",
+      "name": "web"
+    }
+  ]
+}

package/src/templates/zpc.config.mjs.template

@@ -0,0 +1,21 @@
+import { defineConfig } from "@zhipu/zp-cli";
+
+export default defineConfig({
+  projectName: "my-project",
+  api: [
+    {
+      path: "api",
+      name: "api",
+      proxy: "/api",
+      env: {
+        PORT: 3000,
+      },
+    },
+  ],
+  web: [
+    {
+      path: "web",
+      name: "web",
+    },
+  ],
+});

package/src/templates/zpc.config.mts.template

@@ -0,0 +1,21 @@
+import { defineConfig } from "@zhipu/zp-cli";
+
+export default defineConfig({
+  projectName: "my-project",
+  api: [
+    {
+      path: "api",
+      name: "api",
+      proxy: "/api",
+      env: {
+        PORT: 3000,
+      },
+    },
+  ],
+  web: [
+    {
+      path: "web",
+      name: "web",
+    },
+  ],
+});

package/src/templates/zpc.config.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "zpc.config",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["projectName"],
+  "anyOf": [{ "required": ["api"] }, { "required": ["web"] }],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "projectName": {
+      "type": "string",
+      "minLength": 1,
+      "description": "项目名，部署路径为 <root>/<projectName>/<name>"
+    },
+    "api": {
+      "$ref": "#/definitions/appList"
+    },
+    "web": {
+      "$ref": "#/definitions/appList"
+    }
+  },
+  "definitions": {
+    "appList": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/app"
+      }
+    },
+    "app": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "name"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "相对项目根的源码目录"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "打包 / 部署目录名"
+        },
+        "proxy": {
+          "type": "string",
+          "description": "api 对外路径前缀；web 未写 buildEnv.VITE_API_PROXY 时也可作回退"
+        },
+        "buildEnv": {
+          "$ref": "#/definitions/envMap",
+          "description": "仅构建期注入"
+        },
+        "env": {
+          "$ref": "#/definitions/envMap",
+          "description": "仅运行时注入（pm2）"
+        }
+      }
+    },
+    "envMap": {
+      "type": "object",
+      "additionalProperties": {
+        "type": ["string", "number", "boolean"]
+      }
+    }
+  }
+}

package/src/templates/zpc.config.ts.template

@@ -0,0 +1,21 @@
+import { defineConfig } from "@zhipu/zp-cli";
+
+export default defineConfig({
+  projectName: "my-project",
+  api: [
+    {
+      path: "api",
+      name: "api",
+      proxy: "/api",
+      env: {
+        PORT: 3000,
+      },
+    },
+  ],
+  web: [
+    {
+      path: "web",
+      name: "web",
+    },
+  ],
+});