share-pages 0.1.1 → 0.3.0

package/README.md

@@ -2,12 +2,16 @@
 
 Share Pages 的命令行客户端，用于发布和管理 HTML、目录、Markdown、LaTeX、EPUB 与 CSV 内容。
 
+默认输出为适合人阅读的摘要；添加 `--json` 可获得稳定的单行 JSON。直接运行 `share-pages`，或在任意命令后添加 `--help`，即可看到按工作流组织的示例。
+
 ## 安装
 
 需要 Node.js 22 或更高版本。
 
 ```sh
 npm install --global share-pages
+share-pages --version
+share-pages
 ```
 
 ## 登录
@@ -16,6 +20,7 @@ npm install --global share-pages
 
 ```sh
 share-pages login --server https://pages.example.com
+share-pages status
 ```
 
 自动化环境可通过 stdin 提供 Token：
@@ -35,15 +40,46 @@ share-pages publish ./README.md --id readme --access public
 share-pages publish ./report.csv --id report --title "Report"
 ```
 
+成功后 CLI 会给出页面地址、管理入口和下一次更新命令。更新已有页面必须显式添加 `--update`，避免误操作：
+
+```sh
+share-pages publish ./README.md --id readme --update
+```
+
 发布前只做本地转换和校验：
 
 ```sh
 share-pages publish ./site --dry-run --json
 ```
 
+## 查询与恢复
+
+```sh
+share-pages pages list
+share-pages pages get readme
+share-pages versions list readme
+share-pages stats readme
+share-pages download readme --output readme-original.md
+```
+
+网络中断后，使用首次上传时打印的会话 ID 继续：
+
+```sh
+share-pages publish ./site --id docs --resume <upload-id>
+share-pages uploads <upload-id>
+```
+
+删除本机凭据不会撤销远端 Token；敏感 Token 仍应在后台撤销：
+
+```sh
+share-pages logout
+```
+
 查看全部命令：
 
 ```sh
 share-pages --help
 share-pages publish --help
 ```
+
+完整参数、约束和示例均可通过 `share-pages help <命令>` 离线查看。

package/dist/{dist-JyXFh6I5.mjs → dist-LkxVliJx.mjs}

@@ -5079,9 +5079,7 @@ const limitsSchema = object({
 	zipRatio: number$1().positive().default(100),
 	storageBytes: number$1().int().positive().default(8 * 1024 ** 3),
 	uploadHours: number$1().positive().default(24),
-	trashDays: number$1().positive().default(7),
-	analyticsMonths: number$1().int().positive().default(24),
-	uvDays: number$1().int().min(1).default(3)
+	trashDays: number$1().positive().default(7)
 });
 const defaultLimits = limitsSchema.parse({});
 function validateManifestLimits(manifest, limits) {
@@ -5238,11 +5236,7 @@ const settings = object({
 	limits: limitsSchema,
 	used_bytes: integer,
 	reserved_bytes: integer,
-	maintenance: integer,
-	analytics_error: nullableText,
-	last_aggregate: integer.nullable(),
-	analytics_started_at: integer,
-	analytics_watermark: nullableText
+	maintenance: integer
 });
 const jobSummary = object({
 	id: text,
@@ -5388,27 +5382,43 @@ const metrics = object({
 	errors: number,
 	denied: number,
 	cache_hits: number,
-	duration: number,
-	sampled: number
+	duration: number
 });
 object({
+	source: _enum(["analytics-engine", "local-memory"]),
 	scope: string(),
-	timezone: string(),
+	timezone: literal("UTC"),
 	from: string(),
 	to: string(),
-	days: array(metrics.partial().extend({
+	queriedAt: number,
+	cacheStatus: _enum([
+		"live",
+		"fresh-cache",
+		"stale-cache"
+	]),
+	days: array(metrics.extend({
 		day: string(),
-		uv: number,
-		complete: boolean(),
-		state: string(),
-		ingestError: boolean(),
-		updatedAt: number.nullable()
+		uv: number.nullable(),
+		uvStatus: _enum([
+			"exact",
+			"sampled-estimate",
+			"unavailable"
+		]),
+		partial: boolean(),
+		sampled: boolean()
 	})),
 	distributions: array(metrics.extend({
-		day: string(),
-		scope: string(),
-		dimension: string(),
-		value: string()
+		dimension: _enum([
+			"country",
+			"device",
+			"browser",
+			"referer",
+			"status",
+			"event",
+			"bot"
+		]),
+		value: string(),
+		sampled: boolean()
 	})),
 	popular: array(object({
 		scope: string(),
@@ -5420,12 +5430,8 @@ object({
 		id: string().optional(),
 		number: number.optional()
 	})),
-	visitorDays: number,
-	uvLabel: string(),
-	lastAggregate: number.nullable(),
-	watermark: string().nullable(),
-	mode: string(),
-	error: string().nullable()
+	visitorDays: number.nullable(),
+	retentionDays: literal(90)
 });
 async function digest(data) {
 	const b = typeof data === "string" ? new TextEncoder().encode(data) : data;
@@ -5441,4 +5447,4 @@ function escapeHtml(value) {
 	})[c] ?? c);
 }
 //#endregion
-export { digest as a, manifestSchema as c, defaultLimits as i, safePath as l, CHUNK_SIZE as n, escapeHtml as o, assert as r, formats as s, AppError as t, validateManifestLimits as u };
+export { defaultLimits as a, formats as c, slugSchema as d, validateManifestLimits as f, assert as i, manifestSchema as l, CHUNK_SIZE as n, digest as o, accessSchema as r, escapeHtml as s, AppError as t, safePath as u };

package/dist/{epub-BXQPqTFk-CGD2NLS1.mjs → epub-BXQPqTFk-DV2p5uyW.mjs}

@@ -1,6 +1,6 @@
 import { t as __commonJSMin } from "./rolldown-runtime-B4iAMlE-.mjs";
-import { l as safePath, r as assert } from "./dist-JyXFh6I5.mjs";
-import { c as unzipSafe, n as document, o as safeXMLText, r as encoder, s as sanitizeEPUB, t as decodeText } from "./prepare-C56DezIS-DiqwpdkG.mjs";
+import { i as assert, u as safePath } from "./dist-LkxVliJx.mjs";
+import { c as unzipSafe, n as document, o as safeXMLText, r as encoder, s as sanitizeEPUB, t as decodeText } from "./prepare-C56DezIS-pzIt9WD8.mjs";
 //#region ../../node_modules/.pnpm/@xmldom+xmldom@0.8.15/node_modules/@xmldom/xmldom/lib/conventions.js
 var require_conventions = /* @__PURE__ */ __commonJSMin(((exports) => {
 	/**

package/dist/index.mjs

@@ -1,14 +1,105 @@
 #!/usr/bin/env node
-import { a as digest, i as defaultLimits, n as CHUNK_SIZE, r as assert, s as formats, t as AppError } from "./dist-JyXFh6I5.mjs";
-import { Command, CommanderError, Option } from "commander";
+import { a as defaultLimits, c as formats, d as slugSchema, i as assert, n as CHUNK_SIZE, o as digest, r as accessSchema, t as AppError } from "./dist-LkxVliJx.mjs";
+import { Command, CommanderError, Help, Option } from "commander";
 import { randomUUID } from "node:crypto";
-import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { StringDecoder } from "node:string_decoder";
 import { createWriteStream } from "node:fs";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
+//#region src/terminal.ts
+const control = /[\x00-\x1f\x7f-\x9f]/g;
+function terminalText(value, multiline = false) {
+	return String(value).replace(control, (character) => multiline && character === "\n" ? "\n" : " ");
+}
+//#endregion
+//#region src/errors.ts
+const hints = {
+	LOGIN_REQUIRED: "先运行 share-pages login --server https://你的实例域名",
+	SERVER_REQUIRED: "添加 --server https://你的实例域名，或为已有 profile 重新登录",
+	INVALID_SERVER: "--server 只填写 origin，例如 https://pages.example.com",
+	INSECURE_SERVER: "远程实例必须使用 HTTPS；只有 localhost 可以使用 HTTP",
+	TOKEN_REQUIRED: "在后台创建发布 Token，然后重新登录",
+	INVALID_PAGE_ID: "页面 ID 使用 3–40 位小写字母、数字或连字符，并避开系统保留名称",
+	INVALID_PROFILE: "例如使用 default、production 或 team_docs",
+	INVALID_UPLOAD_ID: "复制上传开始时 CLI 输出的完整会话 ID",
+	INVALID_DATE: "例如使用 2026-09-10",
+	INVALID_DATE_RANGE: "交换起止日期，确保 --from 不晚于 --to",
+	INVALID_LIMIT: "将 --limit 设置为 1–100 的整数",
+	INVALID_TIMEOUT: "将 --timeout 设置为 1–3600 的整数秒数",
+	ID_REQUIRED: "添加 --id <已有页面 ID>，或去掉 --update 创建新页面",
+	TYPE_REQUIRED: "stdin 没有文件名；添加 --type markdown、html、latex、epub、csv 或 zip",
+	INVALID_INDEX_POLICY: "改用 --access public，或移除 --indexable",
+	INPUT_REQUIRED: "自动化环境请使用 --token-stdin、--password-file 或对应环境变量",
+	CONFIRMATION_REQUIRED: "确认目标无误后添加 --yes；永久删除无法恢复",
+	ID_EXISTS: "若要为已有页面创建新版本，请保持相同 --id 并添加 --update",
+	PAGE_NOT_FOUND: "运行 share-pages pages list 查找可用页面 ID",
+	VERSION_NOT_FOUND: "运行 share-pages versions list <页面 ID> 查找版本 ID",
+	RESUME_MISMATCH: "使用创建该会话时相同的文件和实例，或去掉 --resume 开始新上传",
+	INVALID_RESUME_STATE: "去掉 --resume 开始新上传；损坏状态不会影响服务端已有内容",
+	NETWORK_ERROR: "检查网络和实例地址后重试；已有上传会话可用 --resume 继续",
+	REQUEST_TIMEOUT: "可增大 --timeout，或用 --no-wait 后运行 share-pages uploads <上传 ID>",
+	OUTPUT_EXISTS: "换一个 --output 路径；CLI 不会覆盖已有文件",
+	INPUT_NOT_FOUND: "检查输入路径、--password-file 或 --resume 的值是否正确",
+	PERMISSION_DENIED: "检查文件权限以及当前目录是否可读写",
+	CONFIG_ERROR: "修复或移走配置文件后重新登录；默认位置为 ~/.config/share-pages/config.json",
+	INSECURE_SECRET_FILE: "秘密文件只能由当前用户读写，建议设置为 chmod 600",
+	INVALID_PASSWORD: "换用 8–256 位页面密码后重试",
+	PASSWORD_ACCESS_CONFLICT: "使用 --access password，或移除 --password-file",
+	EMPTY_PATCH: "运行 share-pages pages edit --help 查看可修改字段",
+	OUTPUT_CONFLICT: "只选择一种 stdout 输出格式后重试"
+};
+function systemError(error) {
+	const path = error.path ? `：${error.path}` : "";
+	if (error.code === "EEXIST") return new AppError("OUTPUT_EXISTS", `目标文件已存在${path}`);
+	if (error.code === "ENOENT") return new AppError("INPUT_NOT_FOUND", `找不到文件或目录${path}`);
+	if (error.code === "EACCES" || error.code === "EPERM") return new AppError("PERMISSION_DENIED", `没有文件访问权限${path}`, 403);
+}
+function isHelpExit(error) {
+	return error instanceof CommanderError && (error.exitCode === 0 || ["commander.help", "commander.helpDisplayed"].includes(error.code));
+}
+function normalizeError(error) {
+	if (error instanceof CommanderError) return {
+		code: "CLI_USAGE",
+		message: error.message.replace(/^error:\s*/i, "").trim().replace(/^unknown command /i, "未知命令 ").replace(/^unknown option /i, "未知选项 ").replace(/^missing required argument /i, "缺少必填参数 ").replace(/^too many arguments\./i, "参数过多。").replace(/\(Did you mean (.+)\?\)/i, "你可能想输入 $1。"),
+		status: 400,
+		hint: "运行 share-pages --help，或 share-pages <命令> --help 查看示例"
+	};
+	const resolved = (error instanceof AppError ? error : systemError(error)) ?? new AppError("CLI_ERROR", error instanceof Error ? error.message : "命令执行失败；请重试或使用 --help 检查参数");
+	return {
+		code: resolved.code,
+		message: resolved.message,
+		status: resolved.status,
+		fields: resolved.fields,
+		requestId: resolved.requestId,
+		hint: hints[resolved.code]
+	};
+}
+function exitCode(error) {
+	if (error.status === 401 || error.status === 403) return 3;
+	if (error.status === 409) return 4;
+	if (error.status >= 500) return 5;
+	return 2;
+}
+function printError(error, json) {
+	if (json) {
+		const { status: _, ...result } = error;
+		process.stdout.write(`${JSON.stringify({ error: result })}\n`);
+		return;
+	}
+	process.stderr.write(`错误 [${terminalText(error.code)}]: ${terminalText(error.message, true)}\n`);
+	if (error.requestId) process.stderr.write(`请求 ID: ${terminalText(error.requestId)}\n`);
+	if (error.hint) process.stderr.write(`下一步: ${terminalText(error.hint)}\n`);
+}
+function wantsJSON(arguments_) {
+	const separator = arguments_.indexOf("--");
+	const options = separator === -1 ? arguments_ : arguments_.slice(0, separator);
+	return options.includes("--json") || options.includes("-j");
+}
+//#endregion
 //#region ../../packages/sdk/dist/index.js
 function checkAbort(signal) {
 	if (signal?.aborted) throw new AppError("ABORTED", "操作已取消，上传会话仍可恢复", 499);
@@ -320,6 +411,34 @@ function resumePath(id) {
 	if (!/^[a-z0-9-]+$/i.test(id)) throw new AppError("INVALID_UPLOAD_ID", "非法上传 ID");
 	return join(configDir, `upload-${id}.json`);
 }
+async function removeResume(id) {
+	await unlink(resumePath(id)).catch((error) => {
+		if (error.code !== "ENOENT") throw error;
+	});
+}
+//#endregion
+//#region src/help.ts
+const headings = /* @__PURE__ */ new Map([
+	["Usage:", "用法:"],
+	["Arguments:", "参数:"],
+	["Options:", "选项:"],
+	["Commands:", "命令:"],
+	["Global Options:", "全局选项:"]
+]);
+function configureHelp(command) {
+	command.helpOption("-h, --help", "显示命令帮助").helpCommand("help [command]", "显示指定命令的帮助").showSuggestionAfterError().showHelpAfterError(false).configureOutput({ writeErr: (value) => {
+		if (/^(用法|Usage):|^\n(?:示例|说明):/.test(value)) process.stdout.write(value);
+	} }).configureHelp({
+		helpWidth: Math.min(process.stdout.columns || 100, 120),
+		formatHelp(current, helper) {
+			return Help.prototype.formatHelp.call(helper, current, helper).replace(/^(Usage:|Arguments:|Options:|Commands:|Global Options:)/gm, (title) => headings.get(title) ?? title).replace(/\(choices: ([^)]+)\)/g, "（可选值: $1）").replace(/\(default: ([^)]+)\)/g, "（默认: $1）");
+		}
+	});
+}
+function examples(command, lines, notes = []) {
+	command.addHelpText("after", `\n示例:\n${lines.map((line) => `  ${line}`).join("\n")}${notes.length ? `\n\n说明:\n${notes.map((line) => `  ${line}`).join("\n")}` : ""}\n`);
+	return command;
+}
 //#endregion
 //#region src/input.ts
 async function stdinBytes(limit = 100 * 1024 ** 2) {
@@ -340,31 +459,57 @@ async function secret(prompt, interactive = true) {
 	process.stdin.resume();
 	return new Promise((resolve, reject) => {
 		let value = "";
+		const decoder = new StringDecoder("utf8");
 		const onData = (data) => {
-			for (const c of data.toString("utf8")) {
+			for (const c of decoder.write(data)) {
 				if (c === "\r" || c === "\n") {
 					cleanup();
 					resolve(value);
 					return;
 				}
-				if (c === "") {
+				if (c === "" || c === "") {
 					cleanup();
 					reject(new AppError("CANCELLED", "操作取消"));
 					return;
 				}
-				if (c === "") value = value.slice(0, -1);
+				if (c === "\b" || c === "") value = value.slice(0, -1);
 				else if (c >= " ") value += c;
 			}
 		};
+		const onEnd = () => {
+			cleanup();
+			reject(new AppError("CANCELLED", "输入已结束，操作取消"));
+		};
+		const onError = (error) => {
+			cleanup();
+			reject(error);
+		};
 		function cleanup() {
 			process.stdin.off("data", onData);
+			process.stdin.off("end", onEnd);
+			process.stdin.off("error", onError);
 			process.stdin.setRawMode(false);
 			process.stdin.pause();
 			process.stderr.write("\n");
 		}
 		process.stdin.on("data", onData);
+		process.stdin.once("end", onEnd);
+		process.stdin.once("error", onError);
 	});
 }
+async function secretFile(path, label = "秘密文件") {
+	const file = await open(path, "r");
+	try {
+		const metadata = await file.stat();
+		if (!metadata.isFile()) throw new AppError("INVALID_SECRET_FILE", `${label}必须是普通文件`);
+		if (process.platform !== "win32" && (metadata.mode & 63) !== 0) throw new AppError("INSECURE_SECRET_FILE", `${label}权限过宽；请先运行 chmod 600 ${JSON.stringify(path)}`);
+		const value = (await file.readFile("utf8")).trimEnd();
+		if (!value) throw new AppError("EMPTY_SECRET_FILE", `${label}不能为空`);
+		return value;
+	} finally {
+		await file.close();
+	}
+}
 async function confirm(message, yes, interactive) {
 	if (yes) return;
 	if (!interactive || !process.stdin.isTTY) throw new AppError("CONFIRMATION_REQUIRED", "自动化删除需要显式 --yes");
@@ -380,11 +525,11 @@ async function confirm(message, yes, interactive) {
 }
 //#endregion
 //#region package.json
-var version = "0.1.1";
+var version = "0.3.0";
 //#endregion
 //#region src/shared.ts
 function createCommand() {
-	return new Command().name("share-pages").description("个人静态内容发布工具").version(version).option("--json", "stdout 仅输出 JSON").option("--quiet", "隐藏进度").option("--no-interactive", "禁止交互输入").option("--profile <name>", "实例 profile").option("--server <url>", "覆盖实例地址").exitOverride();
+	return new Command().name("share-pages").description("将 HTML、站点目录和文档发布到你自己的 Share Pages 实例").version(version, "-V, --version", "显示 CLI 版本").addOption(new Option("-j, --json", "以单行 JSON 输出结果和错误（适合脚本）")).addOption(new Option("-q, --quiet", "隐藏进度和操作提示")).addOption(new Option("--no-interactive", "禁止密码和删除确认等交互输入")).addOption(new Option("-p, --profile <name>", "使用指定的实例配置")).addOption(new Option("--server <url>", "临时覆盖实例地址")).exitOverride();
 }
 function options(command) {
 	const chain = [];
@@ -401,27 +546,75 @@ function stringOptions(options, keys) {
 	}
 	return values;
 }
-function output(value, o) {
+function output(value, o, human) {
 	if (o.json) process.stdout.write(`${JSON.stringify(value)}\n`);
-	else if (typeof value === "object" && value && "url" in value) process.stdout.write(`${String(value.url)}\n`);
+	else if (human) process.stdout.write(`${terminalText(human, true).trimEnd()}\n`);
+	else if (typeof value === "object" && value && "url" in value) process.stdout.write(`${terminalText(value.url)}\n`);
 	else process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function note(message, o) {
+	if (!o.quiet) process.stderr.write(`${terminalText(message).trimEnd()}\n`);
+}
 async function client(o) {
 	return new SharePagesClient(await profile(o.profile, o.server));
 }
 //#endregion
+//#region src/validation.ts
+const choices = {
+	access: accessSchema.options,
+	format: formats,
+	pageState: [
+		"active",
+		"trash",
+		"purging",
+		"purged",
+		"all"
+	]
+};
+function pageId(value) {
+	const parsed = slugSchema.safeParse(value);
+	if (!parsed.success) throw new AppError("INVALID_PAGE_ID", parsed.error.issues[0]?.message ?? "页面 ID 无效");
+	return parsed.data;
+}
+function profileName(value) {
+	if (!/^[a-z0-9][a-z0-9._-]{0,39}$/i.test(value)) throw new AppError("INVALID_PROFILE", "Profile 名称需为 1–40 位字母、数字、点、下划线或连字符");
+	return value;
+}
+function uploadId(value) {
+	if (!/^[a-z0-9-]{1,80}$/i.test(value)) throw new AppError("INVALID_UPLOAD_ID", "上传 ID 只能包含字母、数字和连字符");
+	return value;
+}
+function positiveSeconds(value) {
+	if (!/^\d+$/.test(value)) throw new AppError("INVALID_TIMEOUT", "--timeout 必须是 1–3600 之间的整数秒数");
+	const seconds = Number(value);
+	if (seconds < 1 || seconds > 3600) throw new AppError("INVALID_TIMEOUT", "--timeout 必须是 1–3600 之间的整数秒数");
+	return seconds;
+}
+function pageLimit(value) {
+	if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 100) throw new AppError("INVALID_LIMIT", "--limit 必须是 1–100 之间的整数");
+	return Number(value);
+}
+function isoDate(value) {
+	const parsed = /* @__PURE__ */ new Date(`${value}T00:00:00Z`);
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(parsed.valueOf()) || parsed.toISOString().slice(0, 10) !== value) throw new AppError("INVALID_DATE", "日期必须使用 YYYY-MM-DD 格式");
+	return value;
+}
+function requirePatch(patch) {
+	if (!Object.keys(patch).length) throw new AppError("EMPTY_PATCH", "没有要修改的内容；请指定 --title、--access、--indexable 或 --password-file");
+}
+//#endregion
 //#region src/accounts.ts
 function registerAccounts(cli) {
-	cli.command("login").description("保存实例和发布 Token").option("--token-stdin", "从 stdin 读取 Token").action(async (_local, command) => {
-		const o = options(command), token = o.tokenStdin ? new TextDecoder().decode(await stdinBytes(1024)).trim() : process.env.SHARE_PAGES_TOKEN ?? await secret("发布 Token：", o.interactive);
-		if (!o.server) throw new AppError("SERVER_REQUIRED", "登录需要 --server <url>");
+	examples(cli.command("login").description("验证并安全保存实例地址和发布 Token").helpGroup("开始使用").option("--token-stdin", "从 stdin 读取 Token（推荐用于自动化）").action(async (_local, command) => {
+		const o = options(command), config = await readConfig(), name = profileName(o.profile ?? config.active ?? "default"), existing = Object.hasOwn(config.profiles, name) ? config.profiles[name] : void 0, server = o.server ?? process.env.SHARE_PAGES_SERVER ?? existing?.server, token = o.tokenStdin ? new TextDecoder().decode(await stdinBytes(1024)).trim() : process.env.SHARE_PAGES_TOKEN ?? await secret("发布 Token：", o.interactive);
+		if (!server) throw new AppError("SERVER_REQUIRED", "首次登录需要 --server <url>");
+		if (!token) throw new AppError("TOKEN_REQUIRED", "发布 Token 不能为空", 401);
 		const sdk = new SharePagesClient({
-			server: o.server,
+			server,
 			token
 		});
+		note(`正在验证 ${terminalText(sdk.server)}…`, o);
 		await sdk.request("/me");
-		const config = await readConfig();
-		const name = o.profile ?? "default";
 		config.profiles = {
 			...config.profiles,
 			[name]: {
@@ -435,81 +628,226 @@ function registerAccounts(cli) {
 			profile: name,
 			server: sdk.server,
 			status: "logged-in"
-		}, o);
-	});
-	const profiles = cli.command("profiles");
-	profiles.command("list").action(async (_o, command) => {
+		}, o, `已登录并启用 profile “${name}”\n实例: ${sdk.server}`);
+		note("下一步: share-pages publish <文件或目录> --id <页面 ID>", o);
+	}), [
+		"share-pages login --server https://pages.example.com",
+		"printf '%s' \"$SHARE_PAGES_TOKEN\" | share-pages login --server \"$SHARE_PAGES_SERVER\" --token-stdin --no-interactive",
+		"share-pages login --profile production  # 更新已有 profile 的 Token"
+	]);
+	const profiles = cli.command("profiles").description("查看和切换本机保存的实例配置（永不显示 Token）").helpGroup("开始使用");
+	examples(profiles, [
+		"share-pages profiles list",
+		"share-pages profiles use production",
+		"share-pages status --profile production"
+	]);
+	examples(profiles.command("list").description("列出 profile 和当前实例").action(async (_o, command) => {
 		const o = options(command), c = await readConfig();
+		const items = Object.entries(c.profiles).map(([name, p]) => ({
+			name,
+			server: p.server
+		}));
 		output({
 			active: c.active,
-			profiles: Object.entries(c.profiles).map(([name, p]) => ({
-				name,
-				server: p.server
-			}))
-		}, o);
-	});
-	profiles.command("use <name>").action(async (name, _o, command) => {
+			profiles: items
+		}, o, items.length ? items.map((item) => `${item.name === c.active ? "*" : " "} ${terminalText(item.name)}  ${terminalText(item.server)}`).join("\n") : "尚未保存 profile。");
+		if (!items.length) note("下一步: share-pages login --server https://你的实例域名", o);
+	}), ["share-pages profiles list", "share-pages profiles list --json"]);
+	examples(profiles.command("use <name>").description("切换默认 profile").action(async (name, _o, command) => {
 		const o = options(command), c = await readConfig();
-		if (!Object.hasOwn(c.profiles, name)) throw new AppError("PROFILE_NOT_FOUND", "实例配置不存在");
-		c.active = name;
+		const key = profileName(name);
+		if (!Object.hasOwn(c.profiles, key)) throw new AppError("PROFILE_NOT_FOUND", "实例配置不存在");
+		c.active = key;
 		await writeConfig(c);
-		output({ active: name }, o);
+		output({ active: key }, o, `已启用 profile “${key}”`);
+	}), ["share-pages profiles use production"]);
+	examples(cli.command("logout [name]").description("删除本机保存的一个 profile（不会撤销远端 Token）").helpGroup("开始使用").action(async (name, _local, command) => {
+		const o = options(command), config = await readConfig(), key = profileName(name ?? o.profile ?? config.active);
+		if (!Object.hasOwn(config.profiles, key)) throw new AppError("PROFILE_NOT_FOUND", "实例配置不存在");
+		const { [key]: _, ...remaining } = config.profiles;
+		config.profiles = remaining;
+		if (config.active === key) config.active = Object.keys(remaining)[0] ?? "default";
+		await writeConfig(config);
+		output({
+			profile: key,
+			status: "logged-out",
+			active: config.active
+		}, o, `已删除 profile “${key}”`);
+		note("安全提示: 如需让 Token 立即失效，请同时在后台撤销它。", o);
+	}), ["share-pages logout", "share-pages logout production"]);
+	examples(cli.command("status").description("检查当前 profile、网络、认证和服务端能力").helpGroup("开始使用").action(async (_local, command) => {
+		const o = options(command), config = await readConfig(), name = o.profile ?? config.active, sdk = await client(o);
+		note(`正在检查 ${terminalText(sdk.server)}…`, o);
+		const [actor, capabilities] = await Promise.all([sdk.request("/me"), sdk.capabilities()]);
+		const result = {
+			status: "ok",
+			profile: Object.hasOwn(config.profiles, name) ? name : null,
+			server: sdk.server,
+			actor: actor.kind,
+			scopes: actor.scopes,
+			pageIds: actor.pageIds,
+			prefixes: actor.prefixes,
+			formats: capabilities.formats,
+			apiVersion: capabilities.apiVersion,
+			contractVersion: capabilities.contractVersion
+		};
+		output(result, o, [
+			"连接与认证正常",
+			`Profile: ${terminalText(result.profile ?? "环境变量 / 临时参数")}`,
+			`实例: ${terminalText(result.server)}`,
+			`身份: ${terminalText(result.actor)}`,
+			`权限: ${terminalText(result.scopes.join(", ") || "无")}`,
+			`页面范围: ${terminalText(result.pageIds.length || result.prefixes.length ? [...result.pageIds, ...result.prefixes.map((prefix) => `${prefix}*`)].join(", ") : "全部（仍受 scope 限制）")}`,
+			`格式: ${terminalText(result.formats.join(", "))}`,
+			`API: v${terminalText(result.apiVersion)} · Contract ${terminalText(result.contractVersion)}`
+		].join("\n"));
+	}), ["share-pages status", "share-pages status --profile production --json"]);
+}
+//#endregion
+//#region src/presentation.ts
+const date = (value) => {
+	if (!value || !Number.isFinite(value)) return "—";
+	try {
+		return new Date(value).toISOString();
+	} catch {
+		return "—";
+	}
+};
+const bytes = (value) => {
+	if (!Number.isFinite(value) || value < 0) return "—";
+	if (value < 1024) return `${value} B`;
+	if (value < 1024 ** 2) return `${(value / 1024).toFixed(1)} KiB`;
+	return `${(value / 1024 ** 2).toFixed(1)} MiB`;
+};
+function pagesList(result) {
+	if (!result.items.length) return "没有符合条件的页面。";
+	const rows = result.items.map((page) => `${terminalText(page.slug)}  ${terminalText(page.title)}\n  ${terminalText(page.format)} · ${terminalText(page.access)} · ${terminalText(page.state)} · ${date(page.updated_at)}`);
+	if (result.nextCursor) rows.push(`\n下一页: --cursor ${terminalText(result.nextCursor)}`);
+	return rows.join("\n");
+}
+function pageDetail(page) {
+	return [
+		`${terminalText(page.slug)}  ${terminalText(page.title)}`,
+		`格式: ${terminalText(page.format)}`,
+		`访问: ${terminalText(page.access)}`,
+		`状态: ${terminalText(page.state)}`,
+		`收录: ${page.indexable ? "允许" : "禁止"}`,
+		`当前版本: ${terminalText(page.current_version_id ?? "尚未发布")}`,
+		`更新时间: ${date(page.updated_at)}`
+	].join("\n");
+}
+function versionsList(result) {
+	if (!result.items.length) return "该页面还没有版本。";
+	const rows = result.items.map((version) => `v${version.number}  ${terminalText(version.id)}\n  ${terminalText(version.state)} · ${bytes(version.bytes)} · ${date(version.created_at)}`);
+	if (result.nextCursor) rows.push(`\n下一页: --cursor ${terminalText(result.nextCursor)}`);
+	return rows.join("\n");
+}
+function statisticsSummary(result) {
+	const total = result.days.reduce((sum, day) => ({
+		pv: sum.pv + day.pv,
+		downloads: sum.downloads + day.downloads,
+		bytes: sum.bytes + day.bytes,
+		errors: sum.errors + day.errors
+	}), {
+		pv: 0,
+		downloads: 0,
+		bytes: 0,
+		errors: 0
+	});
+	const recent = result.days.slice(-7).map((day) => {
+		const uv = day.uv === null ? "不可用" : `${day.uv}${day.uvStatus === "exact" ? "" : "（估算）"}`;
+		return `  ${terminalText(day.day)}  PV ${day.pv} · UV ${uv} · 下载 ${day.downloads}`;
 	});
+	const popular = result.popular.slice(0, 5).map((item) => `  ${terminalText(item.slug ?? item.id ?? item.scope)}  PV ${item.pv} · 下载 ${item.downloads}`);
+	return [
+		`统计范围: ${terminalText(result.scope)}`,
+		`UTC 区间: ${terminalText(result.from)} 至 ${terminalText(result.to)}`,
+		`来源: ${terminalText(result.source)} · ${terminalText(result.cacheStatus)}`,
+		`汇总: PV ${total.pv} · 下载 ${total.downloads} · 流量 ${bytes(total.bytes)} · 错误 ${total.errors}`,
+		`访客日: ${result.visitorDays ?? "不可用"}`,
+		recent.length ? `最近 ${recent.length} 天:\n${recent.join("\n")}` : "该区间没有每日数据。",
+		popular.length ? `热门内容:\n${popular.join("\n")}` : void 0,
+		result.days.length > recent.length ? "完整逐日和分布数据请使用 --json 或 --csv。" : void 0
+	].filter(Boolean).join("\n");
 }
 //#endregion
 //#region src/pages.ts
 function registerPages(cli) {
-	const pages = cli.command("pages");
-	pages.command("list").option("--state <state>").option("--q <text>").option("--format <format>").option("--access <mode>").option("--cursor <cursor>").action(async (_local, command) => {
+	const pages = cli.command("pages").description("查询、修改、删除和恢复页面").helpGroup("页面管理");
+	examples(pages, [
+		"share-pages pages list",
+		"share-pages pages get handbook",
+		"share-pages pages edit handbook --title \"团队手册\""
+	]);
+	examples(pages.command("list").description("列出页面；默认显示 active 页面").addOption(new Option("--state <state>", "按页面状态筛选").choices(choices.pageState)).option("--q <text>", "按页面 ID 或标题搜索").addOption(new Option("--format <format>", "按内容格式筛选").choices(choices.format)).addOption(new Option("--access <mode>", "按访问方式筛选").choices(choices.access)).option("--limit <count>", "每页返回 1–100 条", pageLimit, 30).option("--cursor <cursor>", "继续读取服务端返回的下一页").action(async (_local, command) => {
 		const o = options(command);
-		output(await (await client(o)).listPages(stringOptions(o, [
+		const params = stringOptions(o, [
 			"state",
 			"q",
 			"format",
 			"access",
 			"cursor"
-		])), o);
-	});
-	pages.command("get <id>").action(async (id, _local, command) => {
+		]);
+		if (o.limit) params.limit = String(o.limit);
+		const result = await (await client(o)).listPages(params);
+		output(result, o, pagesList(result));
+		if (!result.items.length) note("提示: 使用 --state all 查看包括回收站在内的所有页面。", o);
+	}), [
+		"share-pages pages list",
+		"share-pages pages list --q handbook --format markdown",
+		"share-pages pages list --state trash --json"
+	]);
+	examples(pages.command("get").description("查看一个页面的元数据和当前版本").argument("<id>", "页面 ID", pageId).action(async (id, _local, command) => {
 		const o = options(command);
-		output(await (await client(o)).getPage(id), o);
-	});
-	pages.command("edit <id>").option("--title <title>").option("--access <mode>").option("--indexable <boolean>").option("--password-file <path>").action(async (id, _local, command) => {
+		const result = await (await client(o)).getPage(id);
+		output(result, o, pageDetail(result));
+	}), ["share-pages pages get handbook", "share-pages pages get handbook --json"]);
+	examples(pages.command("edit").description("修改页面标题、访问方式或收录策略").argument("<id>", "页面 ID", pageId).option("--title <title>", "设置新标题").addOption(new Option("--access <mode>", "设置访问方式").choices(choices.access)).addOption(new Option("--indexable <boolean>", "是否允许搜索引擎收录").choices(["true", "false"])).addOption(new Option("--password-file <path>", "从权限为 600 的文件读取新密码").implies({ access: "password" })).action(async (id, _local, command) => {
 		const o = options(command);
 		const patch = {};
-		if (o.title) patch.title = o.title;
+		if (o.passwordFile && o.access !== "password") throw new AppError("PASSWORD_ACCESS_CONFLICT", "--password-file 只能用于 password 访问方式");
+		if (o.title !== void 0) patch.title = o.title;
 		if (o.access) patch.access = o.access;
-		if (o.indexable !== void 0) {
-			if (typeof o.indexable !== "string" || !["true", "false"].includes(o.indexable)) throw new AppError("VALIDATION_ERROR", "--indexable 使用 true/false");
-			patch.indexable = o.indexable === "true";
-		}
-		if (o.access === "password") patch.password = o.passwordFile ? (await readFile(o.passwordFile, "utf8")).trimEnd() : await secret("页面密码：", o.interactive);
-		output(await (await client(o)).patchPage(id, patch), o);
-	});
-	pages.command("delete <id>").option("--purge").option("--yes").action(async (id, _local, command) => {
+		if (o.indexable !== void 0) patch.indexable = o.indexable === "true";
+		if (o.access === "password") patch.password = o.passwordFile ? await secretFile(o.passwordFile, "页面密码文件") : await secret("页面密码（至少 8 位）：", o.interactive);
+		if (typeof patch.password === "string" && (patch.password.length < 8 || patch.password.length > 256)) throw new AppError("INVALID_PASSWORD", "页面密码长度必须为 8–256 位");
+		requirePatch(patch);
+		const result = await (await client(o)).patchPage(id, patch);
+		output(result, o, pageDetail(result));
+		note(`已更新页面 ${id}`, o);
+	}), [
+		"share-pages pages edit handbook --title \"团队手册\"",
+		"share-pages pages edit handbook --access admin --indexable false",
+		"share-pages pages edit handbook --password-file ./private/password.txt"
+	]);
+	examples(pages.command("delete").description("将页面移入回收站，或永久删除").argument("<id>", "页面 ID", pageId).option("--purge", "永久删除页面和全部版本（不可恢复）").option("--yes", "跳过交互确认（自动化环境必需）").action(async (id, _local, command) => {
 		const o = options(command), sdk = await client(o);
 		const page = await sdk.getPage(id);
-		await confirm(`${o.purge ? "永久删除" : "移入回收站"}页面 ${id}（${page.title}）及全部版本。`, !!o.yes, !!o.interactive);
-		output(await sdk.deletePage(id, o.purge), o);
-	});
-	pages.command("restore <id>").option("--replace-with <version>").action(async (id, _local, command) => {
+		await confirm(`${o.purge ? "永久删除" : "移入回收站"}页面 ${id}（${terminalText(page.title)}）及全部版本。`, !!o.yes, !!o.interactive);
+		output(await sdk.deletePage(id, o.purge), o, o.purge ? `页面 ${id} 已进入永久清理队列。` : `页面 ${id} 已移入回收站。`);
+	}), ["share-pages pages delete handbook", "share-pages pages delete handbook --purge --yes --no-interactive"]);
+	examples(pages.command("restore").description("从回收站恢复页面").argument("<id>", "页面 ID", pageId).option("--replace-with <version>", "当前版本不可用时指定接替版本 ID").action(async (id, _local, command) => {
 		const o = options(command);
-		output(await (await client(o)).restorePage(id, o.replaceWith), o);
-	});
+		output(await (await client(o)).restorePage(id, o.replaceWith), o, `页面 ${id} 已恢复。`);
+	}), ["share-pages pages restore handbook", "share-pages pages restore handbook --replace-with <版本 UUID>"]);
 }
 //#endregion
 //#region src/publish.ts
 function registerPublish(cli) {
-	cli.command("publish <input>").description("发布文件、ZIP 或目录；使用 - 从 stdin 读取内容").option("--id <id>").option("--update", "更新已有 ID").option("--type <format>").option("--title <title>").option("--entry <path>", "HTML 入口", "index.html").option("--spa", "启用 HTML 导航回退").option("--access <access>", "public / password / admin").option("--indexable", "允许公开页面收录").option("--encoding <encoding>", "文本编码", "utf-8").option("--delimiter <delimiter>", "CSV 分隔符").option("--no-header", "CSV 没有表头").option("--password-file <path>", "从权限受限文件读取页面密码").option("--dry-run", "仅检查转换和 manifest").option("--resume <uploadId>", "继续上传会话").option("--idempotency-key <key>").option("--no-wait", "提交后返回处理中状态").option("--timeout <seconds>", "等待秒数", "120").action(async (input, _local, command) => {
+	examples(cli.command("publish").description("检查、转换并发布文件、ZIP 或目录").helpGroup("发布与传输").argument("<input>", "文件、ZIP、目录，或 -（从 stdin 读取）").option("--id <id>", "设置 3–40 位稳定页面 ID", pageId).option("--update", "更新已有 ID").addOption(new Option("--type <format>", "覆盖自动识别的内容格式").choices(choices.format)).option("--title <title>", "覆盖从内容推导的页面标题").option("--entry <path>", "HTML/站点入口文件", "index.html").option("--spa", "找不到站点路径时回退到入口文件").addOption(new Option("--access <mode>", "访问方式（新页面默认 public）").choices(choices.access)).option("--indexable", "允许公开页面被搜索引擎收录").option("--encoding <encoding>", "Markdown/LaTeX/CSV 文本编码", "utf-8").option("--delimiter <delimiter>", "覆盖 CSV 分隔符自动识别").option("--no-header", "将 CSV 第一行视为数据而非表头").addOption(new Option("--password-file <path>", "从权限为 600 的文件读取页面密码").implies({ access: "password" })).addOption(new Option("--dry-run", "仅在本地转换和校验，不访问服务器").conflicts("resume")).addOption(new Option("--resume <upload-id>", "继续先前中断的上传").conflicts("dryRun")).option("--idempotency-key <key>", "为自动化重试提供稳定幂等键").option("--no-wait", "提交后返回处理中状态").option("--timeout <seconds>", "等待发布完成的秒数（1–3600）", positiveSeconds, 120).action(async (input, _local, command) => {
 		const o = options(command);
-		const { prepareNode, prepareBytes, ensureDOM } = await import("./node-Lh4CQjZ4.mjs");
-		if (o.type && !formats.includes(o.type)) throw new AppError("UNSUPPORTED_FORMAT", `--type 必须是 ${formats.join(", ")}`);
+		const { prepareNode, prepareBytes, ensureDOM } = await import("./node-DVMkHtVp.mjs");
+		if (o.update && !o.id) throw new AppError("ID_REQUIRED", "--update 必须同时指定 --id");
+		if (o.passwordFile && o.access !== "password") throw new AppError("PASSWORD_ACCESS_CONFLICT", "--password-file 只能用于 password 访问方式");
+		if (o.indexable && o.access && o.access !== "public") throw new AppError("INVALID_INDEX_POLICY", "--indexable 只适用于 public 页面");
 		if (input === "-" && !o.type) throw new AppError("TYPE_REQUIRED", "stdin 需要显式 --type");
 		let sdk, limits = defaultLimits;
 		if (!o.dryRun) {
 			sdk = await client(o);
+			note(`正在检查实例限制: ${terminalText(sdk.server)}…`, o);
 			limits = (await sdk.capabilities()).limits;
 		}
+		note(o.dryRun ? "正在本地检查并转换内容…" : "正在检查并转换内容…", o);
 		const prepareOptions = {
 			type: o.type,
 			title: o.title,
@@ -526,21 +864,38 @@ function registerPublish(cli) {
 			prepared = await prepareBytes(`stdin.${o.type === "markdown" ? "md" : o.type === "latex" ? "tex" : o.type}`, await stdinBytes(limits.inputBytes), prepareOptions);
 		} else prepared = await prepareNode(input, prepareOptions);
 		if (o.dryRun) {
+			const totalBytes = prepared.manifest.files.reduce((sum, file) => sum + file.size, 0);
 			output({
 				status: "valid",
 				title: prepared.title,
 				manifest: prepared.manifest,
 				warnings: prepared.warnings
-			}, o);
+			}, o, [
+				"本地检查通过（未访问服务器）",
+				`标题: ${terminalText(prepared.title)}`,
+				`格式: ${prepared.manifest.format}`,
+				`文件: ${prepared.manifest.files.length}`,
+				`总大小: ${totalBytes} bytes`,
+				`警告: ${prepared.warnings.length ? prepared.warnings.join("；") : "无"}`
+			].join("\n"));
 			return;
 		}
 		const manifestHash = await digest(JSON.stringify(prepared.manifest));
 		if (!sdk) throw new AppError("MISSING_CLIENT", "发布客户端尚未初始化");
 		if (o.resume) {
-			const saved = JSON.parse(await readFile(resumePath(o.resume), "utf8"));
-			if (saved.manifestHash !== manifestHash || saved.server !== sdk?.server) throw new AppError("RESUME_MISMATCH", "文件内容或实例与断点会话不一致");
+			let saved;
+			try {
+				saved = JSON.parse(await readFile(resumePath(o.resume), "utf8"));
+			} catch (error) {
+				if (error.code) throw error;
+				throw new AppError("INVALID_RESUME_STATE", "续传状态文件已损坏，请开始新的上传");
+			}
+			if (!saved || typeof saved !== "object" || !("manifestHash" in saved) || !("server" in saved) || saved.manifestHash !== manifestHash || saved.server !== sdk.server) throw new AppError("RESUME_MISMATCH", "文件内容或实例与断点会话不一致");
 		}
-		const password = o.access === "password" ? o.passwordFile ? (await readFile(o.passwordFile, "utf8")).trimEnd() : await secret("页面密码（至少 8 位）：", o.interactive) : void 0;
+		const password = o.access === "password" ? o.passwordFile ? await secretFile(o.passwordFile, "页面密码文件") : await secret("页面密码（至少 8 位）：", o.interactive) : void 0;
+		if (password && (password.length < 8 || password.length > 256)) throw new AppError("INVALID_PASSWORD", "页面密码长度必须为 8–256 位");
+		let sessionId = o.resume;
+		note(o.resume ? `正在恢复上传 ${o.resume}…` : "正在创建上传会话…", o);
 		const result = await sdk.publish(prepared, {
 			id: o.id,
 			update: !!o.update,
@@ -551,29 +906,47 @@ function registerPublish(cli) {
 			idempotencyKey: o.idempotencyKey,
 			uploadId: o.resume,
 			wait: o.wait,
-			timeoutMs: Number(o.timeout) * 1e3,
+			timeoutMs: (o.timeout ?? 120) * 1e3,
 			onSession: async (s) => {
+				sessionId = s.id;
 				await savePrivate(resumePath(s.id), {
 					server: sdk?.server,
 					uploadId: s.id,
 					manifestHash
 				});
-				if (!o.quiet) process.stderr.write(`上传会话 ${s.id}\n`);
+				note(`上传会话: ${s.id}（网络中断后可使用 --resume ${s.id}）`, o);
 			},
 			onProgress: (done, total) => {
 				if (!o.quiet && process.stderr.isTTY) process.stderr.write(`\r上传 ${total ? Math.floor(done / total * 100) : 100}%`);
 			}
 		});
+		if (result.status === "ready" && sessionId) await removeResume(sessionId);
 		if (!o.quiet && process.stderr.isTTY) process.stderr.write("\n");
-		output(result, o);
+		output(result, o, result.status === "ready" ? terminalText(result.url) : `上传 ${terminalText(result.id)}: ${terminalText(result.status)}`);
+		if (result.status === "ready") {
+			note(`已发布 ${terminalText(result.pageId)} · 版本 ${result.versionNumber}`, o);
+			note(`管理: ${terminalText(result.manageUrl)}`, o);
+			note(`下一次更新: share-pages publish ${terminalText(input)} --id ${result.pageId} --update`, o);
+		} else note(`下一步: share-pages uploads ${result.id}`, o);
 		if (result.status !== "ready") process.exitCode = 6;
-	});
+	}), [
+		"share-pages publish ./dist --id my-site",
+		"share-pages publish ./README.md --id project-readme --dry-run",
+		"share-pages publish ./README.md --id project-readme --update",
+		"printf '# Hello' | share-pages publish - --type markdown --id hello"
+	], [
+		"支持 html、zip、markdown、latex、epub、csv；目录按静态站点发布。",
+		"新建已有 ID 会失败；更新必须显式使用 --update，以避免误覆盖。",
+		"JSON 模式下结果只写 stdout，进度和提示写 stderr；添加 --quiet 可隐藏提示。"
+	]);
 }
 //#endregion
 //#region src/stats.ts
 function registerStats(cli) {
-	cli.command("stats [id]").option("--version <version>").option("--from <date>").option("--to <date>").option("--csv").action(async (id, _local, command) => {
+	examples(cli.command("stats").description("查询全站、页面或版本的访问统计").helpGroup("观测与诊断").argument("[id]", "可选的页面 ID", pageId).option("--version <version>", "只查询指定版本 UUID").option("--from <date>", "UTC 起始日期（YYYY-MM-DD）", isoDate).option("--to <date>", "UTC 结束日期（YYYY-MM-DD）", isoDate).option("--csv", "以 CSV 输出到 stdout").action(async (id, _local, command) => {
 		const o = options(command), params = {};
+		if (o.csv && o.json) throw new AppError("OUTPUT_CONFLICT", "--csv 和 --json 不能同时使用");
+		if (o.from && o.to && o.from > o.to) throw new AppError("INVALID_DATE_RANGE", "--from 不能晚于 --to");
 		if (id) params.page = id;
 		for (const k of [
 			"version",
@@ -582,24 +955,45 @@ function registerStats(cli) {
 		]) if (o[k]) params[k] = o[k];
 		if (o.csv) params.format = "csv";
 		const data = await (await client(o)).stats(params);
-		if (data instanceof Response) process.stdout.write(await data.text());
-		else output(data, o);
-	});
-	cli.command("uploads <id>").action(async (id, _local, command) => {
+		if (data instanceof Response) {
+			const csv = await data.text();
+			process.stdout.write(csv.endsWith("\n") ? csv : `${csv}\n`);
+		} else output(data, o, statisticsSummary(data));
+	}), [
+		"share-pages stats --from 2026-09-01 --to 2026-09-07",
+		"share-pages stats handbook --json",
+		"share-pages stats handbook --csv > stats.csv"
+	]);
+	examples(cli.command("uploads").description("查询断点上传或异步发布任务的状态").helpGroup("观测与诊断").argument("<id>", "上传会话 ID", uploadId).action(async (id, _local, command) => {
 		const o = options(command);
-		output(await (await client(o)).request(`/uploads/${encodeURIComponent(id)}`), o);
-	});
+		const result = await (await client(o)).request(`/uploads/${encodeURIComponent(id)}`);
+		output(result, o, [
+			`上传 ${terminalText(result.id)}: ${terminalText(result.status)}`,
+			`版本: ${terminalText(result.versionId)}`,
+			result.result?.url ? `页面: ${terminalText(result.result.url)}` : void 0,
+			result.error ? `错误: ${terminalText(result.error.code)} · ${terminalText(result.error.message)}` : void 0,
+			result.missing.length ? `待上传分片文件: ${result.missing.length}` : void 0
+		].filter(Boolean).join("\n"));
+	}), ["share-pages uploads <上传会话 ID>", "share-pages uploads <上传会话 ID> --json"]);
 }
 //#endregion
 //#region src/transfer.ts
 function registerTransfer(cli) {
-	cli.command("download <id>").option("--version <version>").option("-o, --output <file>").action(async (id, _local, command) => {
-		const o = options(command), sdk = await client(o);
+	examples(cli.command("download").description("下载页面当前版本或指定版本的原件").helpGroup("发布与传输").argument("<id>", "页面 ID", pageId).option("--version <version>", "下载指定版本 UUID（默认当前版本）").option("-o, --output <file>", "输出文件；使用 - 写入 stdout").action(async (id, _local, command) => {
+		const o = options(command);
+		if (o.output === "-" && o.json) throw new AppError("OUTPUT_CONFLICT", "--output - 输出原件字节，不能与 --json 同时使用");
+		const sdk = await client(o);
+		note(`正在下载 ${id}${o.version ? ` 的版本 ${terminalText(o.version)}` : ""}…`, o);
 		const version = o.version ?? (await sdk.getPage(id)).current_version_id;
 		if (!version) throw new AppError("NO_CURRENT_VERSION", "页面没有当前版");
 		const response = await sdk.download(id, String(version));
 		const filename = o.output ?? `${id}-${version}.source`;
 		if (!response.body) throw new AppError("EMPTY_DOWNLOAD", "下载内容为空");
+		if (filename === "-") {
+			note(`正在将 ${id} 的原件写入 stdout…`, o);
+			await pipeline(Readable.fromWeb(response.body), process.stdout);
+			return;
+		}
 		await pipeline(Readable.fromWeb(response.body), createWriteStream(filename, {
 			flags: "wx",
 			mode: 384
@@ -607,18 +1001,24 @@ function registerTransfer(cli) {
 		output({
 			file: filename,
 			versionId: version
-		}, o);
-	});
+		}, o, `原件已保存: ${terminalText(filename)}\n版本: ${terminalText(version)}`);
+	}), [
+		"share-pages download handbook --output handbook.md",
+		"share-pages download handbook --version <版本 UUID> --output handbook-v1.md",
+		"share-pages download handbook --output - > handbook.source"
+	], ["CLI 使用独占创建模式，不会覆盖已有文件。"]);
 }
 //#endregion
 //#region src/versions.ts
 function registerVersions(cli) {
-	const versions = cli.command("versions");
-	versions.command("list <id>").option("--cursor <cursor>").action(async (id, _local, command) => {
+	const versions = cli.command("versions").description("查询、删除和恢复页面历史版本").helpGroup("页面管理");
+	examples(versions, ["share-pages versions list handbook", "share-pages rollback handbook --to <版本 UUID>"]);
+	examples(versions.command("list").description("按版本号倒序列出历史版本").argument("<id>", "页面 ID", pageId).option("--cursor <cursor>", "继续读取服务端返回的下一页").action(async (id, _local, command) => {
 		const o = options(command);
-		output(await (await client(o)).listVersions(id, o.cursor), o);
-	});
-	versions.command("delete <id> <version>").option("--replace-with <version>").option("--unpublish").option("--purge").option("--yes").action(async (id, version, _local, command) => {
+		const result = await (await client(o)).listVersions(id, o.cursor);
+		output(result, o, versionsList(result));
+	}), ["share-pages versions list handbook", "share-pages versions list handbook --json"]);
+	examples(versions.command("delete").description("将历史版本移入回收站，或永久删除").argument("<id>", "页面 ID", pageId).argument("<version>", "版本 UUID").option("--replace-with <version>", "删除当前版时指定接替版本 UUID").option("--unpublish", "删除当前版且不指定接替版本时下线页面").option("--purge", "永久删除版本（不可恢复）").option("--yes", "跳过交互确认（自动化环境必需）").action(async (id, version, _local, command) => {
 		const o = options(command), sdk = await client(o);
 		await sdk.getPage(id);
 		await confirm(`${o.purge ? "永久删除" : "移入回收站"} ${id} 的版本 ${version}。`, !!o.yes, !!o.interactive);
@@ -626,33 +1026,54 @@ function registerVersions(cli) {
 			replaceWith: o.replaceWith,
 			unpublish: o.unpublish,
 			purge: o.purge
-		}), o);
-	});
-	versions.command("restore <id> <version>").action(async (id, version, _local, command) => {
+		}), o, o.purge ? `版本 ${version} 已进入永久清理队列。` : `版本 ${version} 已移入回收站。`);
+	}), ["share-pages versions delete handbook <版本 UUID>", "share-pages versions delete handbook <版本 UUID> --purge --yes --no-interactive"]);
+	examples(versions.command("restore").description("恢复回收站中的历史版本（不切换当前版本）").argument("<id>", "页面 ID", pageId).argument("<version>", "版本 UUID").action(async (id, version, _local, command) => {
 		const o = options(command);
-		output(await (await client(o)).restoreVersion(id, version), o);
-	});
-	cli.command("rollback <id>").requiredOption("--to <version>").option("--no-wait").action(async (id, _local, command) => {
-		const o = options(command), result = await (await client(o)).rollback(id, o.to ?? "", { wait: o.wait });
-		output(result, o);
+		output(await (await client(o)).restoreVersion(id, version), o, `版本 ${version} 已恢复。`);
+	}), ["share-pages versions restore handbook <版本 UUID>"]);
+	examples(cli.command("rollback").description("以历史版本内容创建一个新的当前版本").helpGroup("页面管理").argument("<id>", "页面 ID", pageId).requiredOption("--to <version>", "要回滚到的版本 UUID").option("--idempotency-key <key>", "为自动化重试提供稳定幂等键").option("--no-wait", "提交后返回处理中状态").option("--timeout <seconds>", "等待完成的秒数（1–3600）", positiveSeconds, 120).action(async (id, _local, command) => {
+		const o = options(command), result = await (await client(o)).rollback(id, o.to ?? "", {
+			wait: o.wait,
+			idempotencyKey: o.idempotencyKey,
+			timeoutMs: (o.timeout ?? 120) * 1e3
+		});
+		output(result, o, result.status === "ready" ? result.url : `上传 ${result.id}: ${result.status}`);
+		if (result.status === "ready") note(`已创建版本 ${result.versionNumber}，当前页面已切换。`, o);
+		else note(`下一步: share-pages uploads ${result.id}`, o);
 		if (result.status !== "ready") process.exitCode = 6;
-	});
+	}), [
+		"share-pages versions list handbook",
+		"share-pages rollback handbook --to <版本 UUID>",
+		"share-pages rollback handbook --to <版本 UUID> --no-wait --json"
+	]);
 }
 //#endregion
 //#region src/program.ts
 function buildCLI() {
 	const cli = createCommand();
+	configureHelp(cli);
 	registerAccounts(cli);
 	registerPublish(cli);
 	registerPages(cli);
 	registerVersions(cli);
 	registerTransfer(cli);
 	registerStats(cli);
+	examples(cli, [
+		"share-pages login --server https://pages.example.com",
+		"share-pages publish ./dist --id my-site",
+		"share-pages pages list",
+		"share-pages status"
+	], [
+		"全局选项可以写在子命令前后。自动化环境建议添加 --json --no-interactive。",
+		"环境变量：SHARE_PAGES_SERVER、SHARE_PAGES_TOKEN、SHARE_PAGES_CONFIG_DIR。",
+		"完整说明：https://www.npmjs.com/package/share-pages，或运行 share-pages help <命令>。"
+	]);
 	const configure = (command) => {
 		command.enablePositionalOptions();
 		for (const option of cli.options) {
 			if (option.long === "--version" || command.options.some((local) => local.long === option.long)) continue;
-			command.addOption(new Option(option.flags, option.description));
+			command.addOption(new Option(option.flags, option.description).helpGroup("全局选项"));
 		}
 		for (const child of command.commands) configure(child);
 	};
@@ -661,21 +1082,19 @@ function buildCLI() {
 }
 //#endregion
 //#region src/index.ts
+process.stdout.on("error", (error) => {
+	if (error.code === "EPIPE") process.exitCode = 0;
+	else throw error;
+});
 const cli = buildCLI();
 try {
 	await cli.parseAsync();
 } catch (error) {
-	if (error instanceof CommanderError && error.exitCode === 0) process.exitCode = 0;
+	if (isHelpExit(error)) process.exitCode = 0;
 	else {
-		const e = error instanceof AppError ? error : new AppError("CLI_ERROR", error instanceof Error ? error.message : "命令执行失败");
-		const result = {
-			code: e.code,
-			message: e.message,
-			fields: e.fields
-		};
-		if (process.argv.includes("--json")) process.stdout.write(`${JSON.stringify({ error: result })}\n`);
-		else process.stderr.write(`${e.code}: ${e.message}\n`);
-		process.exitCode = e.status === 401 || e.status === 403 ? 3 : e.status === 409 ? 4 : e.status >= 500 ? 5 : 2;
+		const resolved = normalizeError(error);
+		printError(resolved, wantsJSON(process.argv.slice(2)));
+		process.exitCode = exitCode(resolved);
 	}
 }
 //#endregion

package/dist/{latex-DMo_3IW8-B6ogeBvw.mjs → latex-DMo_3IW8-DdNgxe_1.mjs}

@@ -1,5 +1,5 @@
-import { o as escapeHtml, r as assert, t as AppError } from "./dist-JyXFh6I5.mjs";
-import { n as document } from "./prepare-C56DezIS-DiqwpdkG.mjs";
+import { i as assert, s as escapeHtml, t as AppError } from "./dist-LkxVliJx.mjs";
+import { n as document } from "./prepare-C56DezIS-pzIt9WD8.mjs";
 //#region ../../packages/content/dist/latex-DMo_3IW8.js
 async function latex(source, title) {
 	assert(!/\\(?:usepackage|RequirePackage|input|include|newcommand|renewcommand|def|bibliography|bibliographystyle|includegraphics|write18|catcode)\b/.test(source), "UNSUPPORTED_LATEX", "不支持任意宏包、宏定义、外部文件、图片或参考文献编译");

package/dist/{markdown-BWlCFeLJ-OwSvKM8l.mjs → markdown-BWlCFeLJ-CCxfGkZu.mjs}

@@ -1,6 +1,6 @@
 import { i as __toESM, n as __exportAll, t as __commonJSMin } from "./rolldown-runtime-B4iAMlE-.mjs";
-import { o as escapeHtml, r as assert } from "./dist-JyXFh6I5.mjs";
-import { d as parse$4, l as walk, n as document$3 } from "./prepare-C56DezIS-DiqwpdkG.mjs";
+import { i as assert, s as escapeHtml } from "./dist-LkxVliJx.mjs";
+import { d as parse$4, l as walk, n as document$3 } from "./prepare-C56DezIS-pzIt9WD8.mjs";
 import minpath from "node:path";
 import minproc from "node:process";
 import { fileURLToPath as urlToPath } from "node:url";

package/dist/{node-Lh4CQjZ4.mjs → node-DVMkHtVp.mjs}

@@ -1,5 +1,5 @@
-import { i as defaultLimits, l as safePath, r as assert } from "./dist-JyXFh6I5.mjs";
-import { a as prepareBytes, i as finalize, u as zipSync } from "./prepare-C56DezIS-DiqwpdkG.mjs";
+import { a as defaultLimits, i as assert, u as safePath } from "./dist-LkxVliJx.mjs";
+import { a as prepareBytes, i as finalize, u as zipSync } from "./prepare-C56DezIS-pzIt9WD8.mjs";
 import { lstat, readFile, readdir } from "node:fs/promises";
 import { basename, join } from "node:path";
 //#region ../../packages/content/dist/directory-Cz5DdsHB.js

package/dist/{prepare-C56DezIS-DiqwpdkG.mjs → prepare-C56DezIS-pzIt9WD8.mjs}

@@ -1,5 +1,5 @@
 import { i as __toESM } from "./rolldown-runtime-B4iAMlE-.mjs";
-import { a as digest, c as manifestSchema, i as defaultLimits, l as safePath, o as escapeHtml, r as assert, t as AppError, u as validateManifestLimits } from "./dist-JyXFh6I5.mjs";
+import { a as defaultLimits, f as validateManifestLimits, i as assert, l as manifestSchema, o as digest, s as escapeHtml, t as AppError, u as safePath } from "./dist-LkxVliJx.mjs";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "module";
 //#region ../../node_modules/.pnpm/parse5@8.0.1/node_modules/parse5/dist/common/unicode.js
@@ -8514,7 +8514,7 @@ async function prepareBytes(name, data, options = {}) {
 		if (type === "markdown" || type === "latex") {
 			assert(data.length <= limits.textBytes, "TEXT_TOO_LARGE", "文本文档超过 5 MiB 限额", 413);
 			const source = decodeText(data, options.encoding);
-			files.set("index.html", encoder.encode(type === "markdown" ? await (await import("./markdown-BWlCFeLJ-OwSvKM8l.mjs")).markdown(source, title) : await (await import("./latex-DMo_3IW8-B6ogeBvw.mjs")).latex(source, title)));
+			files.set("index.html", encoder.encode(type === "markdown" ? await (await import("./markdown-BWlCFeLJ-CCxfGkZu.mjs")).markdown(source, title) : await (await import("./latex-DMo_3IW8-DdNgxe_1.mjs")).latex(source, title)));
 		} else if (type === "csv") {
 			assert(data.length <= limits.csvBytes, "CSV_TOO_LARGE", "CSV 超过字节限额", 413);
 			const source = decodeText(data, options.encoding);
@@ -8549,7 +8549,7 @@ async function prepareBytes(name, data, options = {}) {
 				header,
 				maxRows: limits.csvRows
 			})));
-		} else if (type === "epub") files = await (await import("./epub-BXQPqTFk-CGD2NLS1.mjs")).prepareEPUB(data, title, limits, await digest(data));
+		} else if (type === "epub") files = await (await import("./epub-BXQPqTFk-DV2p5uyW.mjs")).prepareEPUB(data, title, limits, await digest(data));
 		for (const [path, bytes] of await loadViewerAssets(type)) files.set(path, bytes);
 	}
 	return finalize(name, data, files, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "share-pages",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Command-line client for publishing and managing Share Pages content",
   "keywords": [
     "share-pages",
@@ -19,11 +19,6 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "pnpm --filter @share-pages/viewers build && tsdown && node scripts/copy-viewer-resources.mjs",
-    "prepublishOnly": "node scripts/check-publish-manifest.mjs && pnpm build && pnpm typecheck",
-    "typecheck": "tsc --noEmit"
-  },
   "publishConfig": {
     "access": "public"
   },
@@ -32,9 +27,13 @@
     "jsdom": "26.1.0"
   },
   "devDependencies": {
-    "@share-pages/content": "workspace:*",
-    "@share-pages/contracts": "workspace:*",
-    "@share-pages/sdk": "workspace:*",
-    "tsdown": "catalog:"
+    "tsdown": "0.23.0",
+    "@share-pages/contracts": "0.1.0",
+    "@share-pages/content": "0.1.0",
+    "@share-pages/sdk": "0.1.0"
+  },
+  "scripts": {
+    "build": "pnpm --filter @share-pages/viewers build && tsdown && node scripts/copy-viewer-resources.mjs",
+    "typecheck": "tsc --noEmit"
   }
-}
+}