@monoedge/jdu-cli 0.1.0 → 0.3.0

package/dist/cli.js

@@ -2,12 +2,13 @@
 import { EventEmitter } from "node:events";
 import childProcess, { spawn } from "node:child_process";
 import path, { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
-import fs, { chmodSync, createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import fs, { chmodSync, createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import process$1 from "node:process";
 import { stripVTControlCharacters } from "node:util";
 import { createHash, randomBytes } from "node:crypto";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { createServer } from "node:http";
+import { createInterface } from "node:readline";
 import { readFile, readdir } from "node:fs/promises";
 //#region ../node_modules/.pnpm/commander@15.0.0/node_modules/commander/lib/error.js
 /**
@@ -2975,7 +2976,7 @@ function sha256File(path) {
 		rs.on("end", () => res(h.digest("hex")));
 	});
 }
-var MIME = Object.freeze({
+var MIME$1 = Object.freeze({
 	".md": "text/markdown; charset=utf-8",
 	".markdown": "text/markdown; charset=utf-8",
 	".txt": "text/plain; charset=utf-8",
@@ -3002,7 +3003,7 @@ var MIME = Object.freeze({
 	".woff2": "font/woff2"
 });
 function guessMime(path) {
-	return MIME[extname(path).toLowerCase()] ?? "application/octet-stream";
+	return MIME$1[extname(path).toLowerCase()] ?? "application/octet-stream";
 }
 /**
 * 增量上传：先用 hash 清单跟 server 协商，只 PUT 缺失的。
@@ -3271,6 +3272,8 @@ function readStoredConfig() {
 	const out = {};
 	if (typeof obj.server === "string") out.server = obj.server;
 	if (typeof obj.token === "string") out.token = obj.token;
+	if (typeof obj.user === "string") out.user = obj.user;
+	if (typeof obj.proxySecret === "string") out.proxySecret = obj.proxySecret;
 	const oidc = readOidc(obj.oidc);
 	if (oidc) out.oidc = oidc;
 	return out;
@@ -3280,6 +3283,8 @@ function saveConfig(next) {
 	mkdirSync(dirname(path), { recursive: true });
 	const body = { server: next.server };
 	if (next.token !== void 0) body.token = next.token;
+	if (next.user !== void 0) body.user = next.user;
+	if (next.proxySecret !== void 0) body.proxySecret = next.proxySecret;
 	if (next.oidc !== void 0) body.oidc = next.oidc;
 	writeFileSync(path, `${JSON.stringify(body, null, 2)}\n`, { mode: 384 });
 	return path;
@@ -3290,9 +3295,13 @@ function loadConfig() {
 	const server = (process.env.JIANDU_SERVER ?? stored.server ?? "").trim().replace(/\/+$/, "");
 	const rawToken = process.env.JIANDU_TOKEN ?? stored.token;
 	if (server === "") throw new CliError("未配置 jiandu server 地址", "执行 jdu login --server <url>，或设置环境变量 JIANDU_SERVER");
+	const user = process.env.JIANDU_FORWARD_AUTH_USER ?? stored.user;
+	const proxySecret = process.env.JIANDU_PROXY_SECRET ?? stored.proxySecret;
 	const cfg = {
 		server,
-		token: rawToken && rawToken.length > 0 ? rawToken : void 0
+		token: rawToken && rawToken.length > 0 ? rawToken : void 0,
+		user: user && user.length > 0 ? user : void 0,
+		proxySecret: proxySecret && proxySecret.length > 0 ? proxySecret : void 0
 	};
 	if (stored.oidc) cfg.oidc = stored.oidc;
 	return cfg;
@@ -3316,15 +3325,86 @@ async function loadRuntimeConfig() {
 	return cfg;
 }
 //#endregion
+//#region src/comments.ts
+var QUOTE_MAX = 120;
+function when(ms) {
+	return new Date(ms).toISOString().slice(0, 16).replace("T", " ");
+}
+/** owner 是 UUID 且没有显示名时 authorLabel 为空串，退回原始 id 也比空着好认。 */
+function who(c) {
+	return `${c.authorLabel || c.author}${c.authorType === "ai" ? " [ai]" : ""}`;
+}
+function indent(text, pad) {
+	return text.split("\n").map((line) => `${pad}${line}`).join("\n");
+}
+/**
+* 线程列表。stdout 纯文本、一线程一段，给 agent 直接读：
+* 首行 `<threadId>  <blockId>  <open|resolved>  <作者>  <时间>  [v<seq>]`，引文一行 `> …`，正文缩进两格，回复 `↳` 缩进。
+*/
+async function listComments(api, docId, opts) {
+	const res = await api.getJson(`/api/docs/${encodeURIComponent(docId)}/comments`);
+	const all = Array.isArray(res?.comments) ? res.comments : [];
+	const roots = all.filter((c) => c.parentId === null && (opts.all || !c.resolved));
+	if (roots.length === 0) {
+		process.stdout.write(`${opts.all ? "(无评论)" : "(无未处理评论)"}\n`);
+		return;
+	}
+	const replies = /* @__PURE__ */ new Map();
+	for (const c of all) {
+		if (c.parentId === null) continue;
+		const list = replies.get(c.parentId) ?? [];
+		list.push(c);
+		replies.set(c.parentId, list);
+	}
+	const out = [];
+	for (const root of roots) {
+		const head = [
+			root.id,
+			root.blockId ?? "-",
+			root.resolved ? "resolved" : "open",
+			who(root),
+			when(root.createdAt)
+		];
+		if (root.versionSeq !== null) head.push(`v${root.versionSeq}`);
+		out.push(head.join("  "));
+		const quote = root.selection?.quote;
+		if (quote) out.push(`  > ${quote.length > QUOTE_MAX ? `${quote.slice(0, QUOTE_MAX)}…` : quote}`);
+		out.push(indent(root.body, "  "));
+		for (const reply of replies.get(root.id) ?? []) {
+			out.push(`  ↳ ${reply.id}  ${who(reply)}  ${when(reply.createdAt)}`);
+			out.push(indent(reply.body, "    "));
+		}
+		out.push("");
+	}
+	process.stdout.write(out.join("\n"));
+}
+async function replyComment(api, threadId, opts) {
+	const res = await api.postJson(`/api/comments/${encodeURIComponent(threadId)}/reply`, {
+		body: opts.message,
+		authorType: opts.ai ? "ai" : "human"
+	});
+	process.stdout.write(`replied ${String(res?.parentId ?? threadId)} → ${String(res?.id ?? "")}\n`);
+}
+async function resolveComment(api, threadId, opts) {
+	const res = await api.postJson(`/api/comments/${encodeURIComponent(threadId)}/resolve`, { resolved: !opts.undo });
+	process.stdout.write(`${opts.undo ? "reopened" : "resolved"} ${String(res?.id ?? threadId)}\n`);
+}
+//#endregion
 //#region src/http.ts
 /** 错误响应体太长会淹没终端，只留头部。 */
 var MAX_DETAIL = 400;
 var ApiClient = class {
 	server;
 	token;
+	/** forward-auth 直连身份：作为 X-Forwarded-User 注入（server 默认 userHeader） */
+	user;
+	/** forward-auth fail-closed 的共享密钥：作为 X-Jiandu-Proxy-Secret 注入 */
+	proxySecret;
 	constructor(cfg) {
 		this.server = cfg.server;
 		this.token = cfg.token;
+		this.user = cfg.user;
+		this.proxySecret = cfg.proxySecret;
 	}
 	url(path) {
 		return `${this.server}${path}`;
@@ -3341,6 +3421,10 @@ var ApiClient = class {
 	async deleteJson(path) {
 		return this.json("DELETE", path, void 0, void 0);
 	}
+	/** 文本路由（`/d/:id.md`）：原样返回正文。 */
+	async getText(path) {
+		return (await this.send("GET", path, void 0, void 0)).text();
+	}
 	/** widget push 走 multipart：boundary 交给 fetch 生成，别自己设 Content-Type。 */
 	async postForm(path, form) {
 		const text = await (await this.send("POST", path, form, void 0)).text();
@@ -3368,6 +3452,8 @@ var ApiClient = class {
 		const url = this.url(path);
 		const headers = {};
 		if (this.token !== void 0) headers.Authorization = `Bearer ${this.token}`;
+		if (this.user !== void 0) headers["X-Forwarded-User"] = this.user;
+		if (this.proxySecret !== void 0) headers["X-Jiandu-Proxy-Secret"] = this.proxySecret;
 		if (contentType !== void 0) headers["Content-Type"] = contentType;
 		let res;
 		try {
@@ -3409,11 +3495,72 @@ async function httpError(method, url, res) {
 		const msg = obj.error ?? obj.message;
 		if (typeof msg === "string" && msg !== "") detail = msg;
 	} catch {}
-	const hint = res.status === 401 || res.status === 403 ? "token 无效或无权访问，执行 jdu login --server <url>" : res.status === 302 ? "网关要登录。forward-auth 下先 jdu login；若已登录，网关需接受 Authorization: Bearer" : void 0;
+	const hint = res.status === 401 || res.status === 403 ? "token 无效或无权访问，执行 jdu login --server <url>；forward-auth 下确认已设 JIANDU_FORWARD_AUTH_USER 与 JIANDU_PROXY_SECRET" : res.status === 302 ? "网关要登录。forward-auth 下先 jdu login；若已登录，网关需接受 Authorization: Bearer" : void 0;
 	const suffix = detail === "" ? "" : `：${detail}`;
 	return new CliError(`${method} ${url} 返回 HTTP ${res.status} ${res.statusText}${suffix}`, hint);
 }
 //#endregion
+//#region src/browser-auth.ts
+/**
+* jdu init 的浏览器授权（#66）：本机起一个 loopback 回调，打开 server 下发的 authorizeUrl，
+* 人在浏览器里用 passkey 会话点一次「授权」，回跳带回一次性 code，再用 PKCE verifier 向 server 换 token。
+*
+* authorizeUrl 与 server 可能不同源（CLI 连 127.0.0.1:18082，浏览器开 https://md.mason.local）——
+* 浏览器去前者，code 换 token 打后者。回调端口随机（server 接受任意 loopback 端口），不和 OIDC 的 8085 抢。
+*/
+async function browserAuthorize(input) {
+	const { verifier, challenge } = pkce();
+	const state = randomBytes(16).toString("base64url");
+	const code = await new Promise((resolve, reject) => {
+		const finish = (fn) => (value) => {
+			clearTimeout(timer);
+			server.close();
+			fn(value);
+		};
+		const fail = finish((msg) => reject(new CliError(msg, "重新执行 jdu init；不想开浏览器就带 --token")));
+		const handler = callbackHandler(state, finish(resolve));
+		const server = createServer((req, res) => {
+			if (new URL(req.url ?? "/", "http://localhost").pathname !== "/callback") {
+				res.writeHead(404).end();
+				return;
+			}
+			handler(req, res);
+		});
+		const timer = setTimeout(() => fail("等待浏览器授权超时"), input.timeoutMs ?? 18e4);
+		server.on("error", (err) => fail(`监听 loopback 回调失败：${err.message}`));
+		server.listen(0, "127.0.0.1", () => {
+			const port = server.address().port;
+			const url = new URL(input.authorizeUrl);
+			url.search = new URLSearchParams({
+				state,
+				code_challenge: challenge,
+				port: String(port),
+				label: input.label ?? hostname()
+			}).toString();
+			process.stderr.write(`在浏览器中完成授权：${url.toString()}\n`);
+			(input.open ?? openBrowser)(url.toString());
+		});
+	});
+	const res = await fetch(`${input.server}/api/cli/token`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			code,
+			code_verifier: verifier
+		})
+	});
+	const text = await res.text();
+	if (!res.ok) throw new CliError(`code 换 token 失败（HTTP ${res.status}）：${text.slice(0, 200)}`, "重新执行 jdu init 再试一次");
+	let token;
+	try {
+		token = JSON.parse(text).token;
+	} catch {
+		token = void 0;
+	}
+	if (typeof token !== "string" || token === "") throw new CliError("server 没有返回 token");
+	return token;
+}
+//#endregion
 //#region src/login.ts
 var OIDC_PARAM_HINT = `传入 --issuer / --client-id，或在 server 配置 auth.oidc（healthz 会带出来），或设置 ${OIDC_ISSUER_ENV} / ${OIDC_CLIENT_ID_ENV}`;
 function resolveOidc(input) {
@@ -3454,6 +3601,15 @@ async function runLogin(opts) {
 	if (server === "") throw new CliError("--server 不能为空");
 	const healthz = await (opts.fetchHealthz ?? fetchHealthz)(server);
 	const provider = healthz.authProvider ?? "token";
+	if (opts.user !== void 0 && opts.user.trim() !== "") return {
+		configPath: saveConfig({
+			server,
+			user: opts.user.trim(),
+			proxySecret: opts.proxySecret && opts.proxySecret !== "" ? opts.proxySecret : void 0
+		}),
+		source: "forward-auth",
+		warning: provider !== "forward-auth" ? `这个 server 是 ${provider} 鉴权，--user 只对 forward-auth 生效；当前请求仍会带 X-Forwarded-User 头（无害）。` : void 0
+	};
 	if (opts.token !== void 0 && opts.token !== "") return {
 		configPath: saveConfig({
 			server,
@@ -3465,7 +3621,7 @@ async function runLogin(opts) {
 		configPath: saveConfig({ server }),
 		source: "anonymous"
 	};
-	if (provider === "token") throw new CliError("这个 server 用 token 鉴权，需要 --token", "jdu login --server <url> --token <token>，token 在 server 首次启动的 stdout / data/initial-token.txt");
+	if (provider === "token" || provider === "password") throw new CliError(`这个 server 用 ${provider} 鉴权，CLI 需要 --token`, "jdu init --server <url>（站点支持时打开浏览器授权），或 jdu login --server <url> --token <token>（token 在 server 首启 stdout / data/initial-token.txt）");
 	const oidc = resolveOidc({
 		issuer: opts.issuer,
 		clientId: opts.clientId,
@@ -3501,31 +3657,117 @@ async function runLogin(opts) {
 	};
 }
 //#endregion
-//#region src/output.ts
-/** server 可能返回裸数组，也可能包一层 `{ docs: [...] }`，两种都认。 */
-function asRows(payload, key) {
-	const raw = Array.isArray(payload) ? payload : payload !== null && typeof payload === "object" ? payload[key] : void 0;
-	if (!Array.isArray(raw)) return [];
-	return raw.filter((r) => r !== null && typeof r === "object");
-}
-function cell(value) {
-	if (value === null || value === void 0) return "-";
-	if (typeof value === "boolean") return value ? "yes" : "no";
-	if (typeof value === "number" && value > 0xe8d4a51000) return new Date(value).toISOString().slice(0, 16).replace("T", " ");
-	if (typeof value === "object") return JSON.stringify(value);
-	return String(value);
+//#region src/init.ts
+/**
+* jdu init：选定部署目标并写好本地配置，一条命令把「指向哪台简牍」定下来。
+*
+* 目标三选一：
+*   （默认）     官方线上服务 https://docs.mszhou.com（OFFICIAL_SERVER）
+*   --local      本机自部署（http://127.0.0.1:8080）
+*   --server <u> 任意自部署地址
+*
+* 为 agent 联动而设计：全 flag 驱动、无交互提示、--json 输出机器可读结果，
+* 拿到 next 字段就知道下一步该干什么（要不要 token、去哪拿）。
+*
+* 登录方式听 server 的（healthz.cliAuth，#66）：声明了 browser 就开浏览器授权换 token；
+* 只有 token 就把 server 给的 tokenHint 拼进 next。CLI 不按「官方 / 自部署」猜。
+*/
+/** 官方线上地址。password 鉴权：浏览器 passkey，CLI 走 token，token 向站点管理员申领。 */
+var OFFICIAL_SERVER = "https://docs.mszhou.com";
+var LOCAL_SERVER = "http://127.0.0.1:8080";
+function resolveInitTarget(opts) {
+	if (opts.local && opts.server) throw new CliError("--local 与 --server 只能二选一");
+	if (opts.server !== void 0) {
+		const server = opts.server.trim().replace(/\/+$/, "");
+		let parsed;
+		try {
+			parsed = new URL(server);
+		} catch {
+			throw new CliError(`--server 不是合法 URL：${opts.server}`);
+		}
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || /[\s'"`$\\;|&<>(){}*?#\[\]]/.test(server)) throw new CliError(`--server 需要干净的 http/https 地址（不含空白与 shell 元字符）：${opts.server}`);
+		return {
+			target: "custom",
+			server
+		};
+	}
+	if (opts.local) return {
+		target: "local",
+		server: LOCAL_SERVER
+	};
+	return {
+		target: "official",
+		server: OFFICIAL_SERVER
+	};
 }
-/** 定宽文本表，便于人和 agent 直接读；无数据时给一行提示而不是空输出。 */
-function printTable(rows, columns) {
-	if (rows.length === 0) {
-		process.stdout.write("(空)\n");
-		return;
+async function runInit(opts) {
+	const { target, server } = resolveInitTarget(opts);
+	const healthz = await (opts.fetchHealthz ?? fetchHealthz)(server);
+	const provider = healthz.authProvider ?? "token";
+	const methods = healthz.cliAuth?.methods ?? fallbackMethods(provider);
+	const base = {
+		target,
+		server,
+		authProvider: provider,
+		authMethods: methods
+	};
+	if (opts.token !== void 0 && opts.token !== "") {
+		if (!await (opts.probe ?? probeApiWithBearer)(server, opts.token)) throw new CliError("token 校验失败（/api/docs 未放行）", "确认 token 正确、且网关放行 Authorization: Bearer");
+		const path = saveConfig({
+			server,
+			token: opts.token
+		});
+		return {
+			...base,
+			loggedIn: true,
+			configPath: path,
+			next: null
+		};
 	}
-	const body = rows.map((row) => columns.map((c) => cell(row[c.key])));
-	const widths = columns.map((c, i) => Math.max(c.header.length, ...body.map((r) => (r[i] ?? "").length)));
-	const line = (cells) => cells.map((v, i) => v.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
-	process.stdout.write(`${line(columns.map((c) => c.header))}\n`);
-	for (const r of body) process.stdout.write(`${line(r)}\n`);
+	const oidc = healthz.oidc?.issuer && healthz.oidc.clientId ? {
+		issuer: healthz.oidc.issuer,
+		clientId: healthz.oidc.clientId
+	} : void 0;
+	const path = saveConfig(oidc ? {
+		server,
+		oidc
+	} : { server });
+	if (provider === "anonymous") return {
+		...base,
+		loggedIn: true,
+		configPath: path,
+		next: null
+	};
+	const authorizeUrl = healthz.cliAuth?.authorizeUrl;
+	if (opts.browser && methods.includes("browser") && authorizeUrl) {
+		const withToken = saveConfig({
+			server,
+			token: await (opts.authorize ?? browserAuthorize)({
+				server,
+				authorizeUrl
+			})
+		});
+		return {
+			...base,
+			loggedIn: true,
+			configPath: withToken,
+			next: null
+		};
+	}
+	const viaToken = `jdu init --server '${server}' --token <token>（${healthz.cliAuth?.tokenHint ?? "token 在 server 首启 stdout / data/initial-token.txt"}）`;
+	const next = provider === "forward-auth" ? `jdu login --server '${server}'（浏览器 SSO），或 ${viaToken}` : methods.includes("browser") ? `jdu init --server '${server}'（不带 --json / --no-browser，打开浏览器授权），或 ${viaToken}` : viaToken;
+	return {
+		...base,
+		loggedIn: false,
+		configPath: path,
+		next
+	};
+}
+/** 老 server 的 healthz 没有 cliAuth：按 provider 推断，与 server 侧 cliAuthOf 的保守档一致。 */
+function fallbackMethods(provider) {
+	if (provider === "anonymous") return [];
+	if (provider === "forward-auth") return ["oidc", "token"];
+	return ["token"];
 }
 /** 只取链接/图片的目标部分，标签内容可以任意嵌套，不参与匹配。 */
 var MD_DEST_RE = /\]\(([^)]*)\)/g;
@@ -3644,11 +3886,8 @@ function collectReferences(entryPath, maxDepth = 10) {
 }
 //#endregion
 //#region src/push.ts
-var VISIBILITIES = [
-	"private",
-	"link",
-	"public"
-];
+/** 可见性三档。link 档已废除：定向分享走读者池（jdu share --to）。 */
+var VISIBILITIES = ["private", "public"];
 function log(line) {
 	process.stderr.write(`${line}\n`);
 }
@@ -3661,6 +3900,7 @@ function inferTitle(entryPath) {
 	} catch {}
 	return basename(entryPath, extname(entryPath));
 }
+/** 收集 → 协商上传 → 发布。进度走 stderr；结果返回给调用方（CLI 打印 URL，mcp 转成 JSON）。 */
 async function pushDoc(api, entryArg, opts) {
 	const visibility = opts.visibility;
 	if (visibility !== void 0 && !VISIBILITIES.includes(visibility)) throw new CliError(`不支持的 visibility：${String(opts.visibility)}`, `可选值：${VISIBILITIES.join(" | ")}`);
@@ -3696,20 +3936,437 @@ async function pushDoc(api, entryArg, opts) {
 	else if (opts.id === void 0 || opts.id === "") body.title = inferTitle(collected.entry.path);
 	if (opts.id !== void 0 && opts.id !== "") body.id = opts.id;
 	if (opts.tag !== void 0) body.tags = opts.tag.flatMap((t) => t.split(",")).map((t) => t.trim()).filter((t) => t.length > 0);
+	if (opts.official === true) body.official = true;
 	const res = await api.postJson("/api/docs", body);
 	const id = typeof res?.id === "string" ? res.id : opts.id;
 	const url = typeof res?.url === "string" && res.url !== "" ? res.url : id !== void 0 ? api.url(`/d/${id}`) : void 0;
+	const warnings = Array.isArray(res?.warnings) ? res.warnings.map(String) : [];
+	for (const w of warnings) log(`warn: ${w}`);
 	if (typeof res?.seq === "number") log(`已发布 ${id ?? ""} v${res.seq}`);
 	if (url === void 0) throw new CliError("server 未返回文档 id 或 url，无法给出访问地址");
-	process.stdout.write(`${url}\n`);
+	return {
+		id,
+		seq: typeof res?.seq === "number" ? res.seq : void 0,
+		url,
+		warnings
+	};
 }
 //#endregion
-//#region src/widget.ts
-var SCOPES = [
-	"official",
-	"team",
-	"personal"
+//#region src/output.ts
+/** server 可能返回裸数组，也可能包一层 `{ docs: [...] }`，两种都认。 */
+function asRows(payload, key) {
+	const raw = Array.isArray(payload) ? payload : payload !== null && typeof payload === "object" ? payload[key] : void 0;
+	if (!Array.isArray(raw)) return [];
+	return raw.filter((r) => r !== null && typeof r === "object");
+}
+function cell(value) {
+	if (value === null || value === void 0) return "-";
+	if (typeof value === "boolean") return value ? "yes" : "no";
+	if (typeof value === "number" && value > 0xe8d4a51000) return new Date(value).toISOString().slice(0, 16).replace("T", " ");
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+}
+/** 定宽文本表，便于人和 agent 直接读；无数据时给一行提示而不是空输出。 */
+function printTable(rows, columns) {
+	if (rows.length === 0) {
+		process.stdout.write("(空)\n");
+		return;
+	}
+	const body = rows.map((row) => columns.map((c) => cell(row[c.key])));
+	const widths = columns.map((c, i) => Math.max(c.header.length, ...body.map((r) => (r[i] ?? "").length)));
+	const line = (cells) => cells.map((v, i) => v.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
+	process.stdout.write(`${line(columns.map((c) => c.header))}\n`);
+	for (const r of body) process.stdout.write(`${line(r)}\n`);
+}
+//#endregion
+//#region src/template.ts
+/**
+* 文档模板（#7）：模板就是打了 `template` 标签的普通文档。
+*
+* ponytail: 不开 templates 表、不加 /api/templates——版本链、可见性（personal 私有 / official 全站）、
+* 标签检索全是现成的，独立表只会把同一套东西再抄一遍。server **不做**任何占位符替换，
+* 模板原样发出去，怎么填是 agent 的事。agent 侧走 MCP 的 list_templates → read_doc → 按骨架写 → push_doc。
+*/
+var TEMPLATE_TAG = "template";
+var hasTemplateTag = (d) => Array.isArray(d.tags) && d.tags.map(String).includes("template");
+async function listTemplates(api, opts) {
+	const [mine, official] = await Promise.all([api.getJson(`/api/docs${opts.all ? "?all=1" : ""}`), api.getJson("/api/official")]);
+	const mineRows = asRows(mine, "docs").filter(hasTemplateTag);
+	const mineIds = new Set(mineRows.map((d) => String(d["id"])));
+	const officialRows = asRows(official, "docs").filter((d) => hasTemplateTag(d) && !mineIds.has(String(d["id"])));
+	printTable([...mineRows.map((d) => ({
+		...d,
+		scope: d["visibility"] === "official" ? "official" : "personal"
+	})), ...officialRows.map((d) => ({
+		...d,
+		scope: "official"
+	}))], [
+		{
+			key: "id",
+			header: "ID"
+		},
+		{
+			key: "scope",
+			header: "SCOPE"
+		},
+		{
+			key: "title",
+			header: "TITLE"
+		},
+		{
+			key: "updatedAt",
+			header: "UPDATED"
+		}
+	]);
+}
+/** 拉模板原文：默认打到 stdout（agent 直接读 / 重定向成新文件），--out 落盘。 */
+async function pullTemplate(api, id, opts) {
+	const md = await api.getText(`/d/${encodeURIComponent(id)}.md`);
+	if (opts.out) {
+		writeFileSync(opts.out, md, "utf8");
+		process.stderr.write(`已写入 ${opts.out}\n`);
+		return;
+	}
+	process.stdout.write(md.endsWith("\n") ? md : `${md}\n`);
+}
+/**
+* 发布 / 更新模板 = push + 保证带 `template` 标签。更新已有模板时保留它原有的其它标签
+* （push 的 tags 字段是整体覆盖语义，不先取回就会把别的标签抹掉）。
+*/
+async function pushTemplate(api, file, opts) {
+	let tags = [TEMPLATE_TAG];
+	if (opts.id) {
+		const cur = await api.getJson(`/api/docs/${encodeURIComponent(opts.id)}/tags`).catch(() => ({}));
+		const existing = Array.isArray(cur.tags) ? cur.tags.map(String) : [];
+		tags = [.../* @__PURE__ */ new Set([...existing, TEMPLATE_TAG])];
+	}
+	return pushDoc(api, file, {
+		title: opts.title,
+		id: opts.id,
+		tag: tags,
+		official: opts.official
+	});
+}
+//#endregion
+//#region src/mcp.ts
+/**
+* `jdu mcp`：把已有 HTTP API 包成 MCP server（stdio），给 Claude Code / codex / dsh 这类本机 agent
+* 当可读可写的知识库用（#9 A 段）。凭据复用 ~/.config/jiandu/config.json，server 端零改动。
+*
+* ponytail: 不引 @modelcontextprotocol/sdk——它带 express / hono / zod 一整套，而这里只需要
+* initialize / tools/list / tools/call 三个方法的 JSON-RPC 换行分帧。协议有变再换官方 SDK。
+* stdout 是协议信道：本文件之外任何写 stdout 的代码都不能在 mcp 模式下被调到（pushDoc 已改为返回值）。
+*/
+var SUPPORTED_PROTOCOLS = [
+	"2025-06-18",
+	"2025-03-26",
+	"2024-11-05"
 ];
+var SERVER_INFO = {
+	name: "jiandu",
+	version: "0.2.0"
+};
+var INSTRUCTIONS = "jiandu（简牍）是一个 Markdown 知识库。先用 search_docs / list_docs 找到文档 id，read_doc 拿 markdown 原文；改稿后用 push_doc 发布新版本（带 id 才是更新，不带是新建）。文档里的 widget fence（```widget_component:Name）保留原样。写新文档前先 list_templates 看有没有对应骨架（周报 / 技术方案…），有就 read_doc 取模板按节填，占位注释自己替换掉。";
+function str(v, name) {
+	if (typeof v !== "string" || v.trim() === "") throw new CliError(`${name} 必填且为非空字符串`);
+	return v.trim();
+}
+function asDoc(raw, scope, server) {
+	if (raw === null || typeof raw !== "object") return null;
+	const d = raw;
+	if (typeof d["id"] !== "string") return null;
+	return {
+		id: d["id"],
+		title: typeof d["title"] === "string" ? d["title"] : "",
+		excerpt: typeof d["excerpt"] === "string" ? d["excerpt"] : "",
+		visibility: typeof d["visibility"] === "string" ? d["visibility"] : scope === "official" ? "official" : "",
+		tags: Array.isArray(d["tags"]) ? d["tags"].map(String) : [],
+		scope,
+		...typeof d["archived"] === "boolean" ? { archived: d["archived"] } : {},
+		...typeof d["updatedAt"] === "number" ? { updatedAt: d["updatedAt"] } : {},
+		url: typeof d["url"] === "string" ? d["url"] : `${server}/d/${d["id"]}`
+	};
+}
+function buildTools(api) {
+	const listOf = async (scope, includeArchived) => {
+		const path = scope === "mine" ? `/api/docs${includeArchived ? "?all=1" : ""}` : scope === "official" ? "/api/official" : "/api/shared";
+		const res = await api.getJson(path);
+		return (Array.isArray(res?.docs) ? res.docs : []).map((d) => asDoc(d, scope, api.server)).filter((d) => d !== null);
+	};
+	const listAll = async (includeArchived) => {
+		const [mine, official, shared] = await Promise.all([
+			listOf("mine", includeArchived),
+			listOf("official", false),
+			listOf("shared", false)
+		]);
+		const seen = new Set(mine.map((d) => d.id));
+		return [...mine, ...[...official, ...shared].filter((d) => !seen.has(d.id) && seen.add(d.id))];
+	};
+	return [
+		{
+			name: "list_docs",
+			description: "列出文档。scope：mine（我发布的，默认）/ official（官方知识库）/ shared（分享给我的）/ all。返回 id、标题、摘要、可见性、标签、URL。",
+			inputSchema: {
+				type: "object",
+				properties: {
+					scope: {
+						type: "string",
+						enum: [
+							"mine",
+							"official",
+							"shared",
+							"all"
+						],
+						default: "mine"
+					},
+					includeArchived: {
+						type: "boolean",
+						default: false,
+						description: "仅 mine 生效：包含已归档"
+					}
+				}
+			},
+			run: async (args) => {
+				const scope = typeof args["scope"] === "string" ? args["scope"] : "mine";
+				const includeArchived = args["includeArchived"] === true;
+				const docs = scope === "all" ? await listAll(includeArchived) : scope === "mine" || scope === "official" || scope === "shared" ? await listOf(scope, includeArchived) : (() => {
+					throw new CliError(`scope 只能是 mine / official / shared / all：${scope}`);
+				})();
+				return JSON.stringify(docs, null, 2);
+			}
+		},
+		{
+			name: "search_docs",
+			description: "按关键词搜文档（标题 / 摘要 / 标签，空格分词、全部命中）。范围是我能看到的全部文档。没有全文检索——要读正文用 read_doc。",
+			inputSchema: {
+				type: "object",
+				required: ["query"],
+				properties: {
+					query: { type: "string" },
+					limit: {
+						type: "integer",
+						minimum: 1,
+						maximum: 100,
+						default: 20
+					}
+				}
+			},
+			run: async (args) => {
+				const terms = str(args["query"], "query").toLowerCase().split(/\s+/).filter(Boolean);
+				const limit = Number.isInteger(args["limit"]) ? Math.max(1, Math.min(100, args["limit"])) : 20;
+				const hits = (await listAll(false)).filter((d) => {
+					const hay = `${d.title}\n${d.excerpt}\n${d.tags.join(" ")}`.toLowerCase();
+					return terms.every((t) => hay.includes(t));
+				});
+				return JSON.stringify(hits.slice(0, limit), null, 2);
+			}
+		},
+		{
+			name: "read_doc",
+			description: "读文档的 markdown 原文（本地引用已改写为 /blob/<hash>）。不传 version 读最新版。",
+			inputSchema: {
+				type: "object",
+				required: ["id"],
+				properties: {
+					id: { type: "string" },
+					version: {
+						type: "integer",
+						minimum: 1,
+						description: "版本号 seq，见 list_versions"
+					}
+				}
+			},
+			run: async (args) => {
+				const id = encodeURIComponent(str(args["id"], "id"));
+				const version = args["version"];
+				if (version !== void 0 && !Number.isInteger(version)) throw new CliError("version 必须是整数");
+				return api.getText(version === void 0 ? `/d/${id}.md` : `/d/${id}/v/${String(version)}.md`);
+			}
+		},
+		{
+			name: "list_templates",
+			description: "列出文档模板（打了 template 标签的文档：官方模板 + 我的）。写新文档前先看这里；选中后 read_doc 取原文，按骨架填内容、删掉 <!-- --> 占位注释，再 push_doc。server 不做任何变量替换。",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			},
+			run: async () => {
+				const docs = (await listAll(false)).filter((d) => d.tags.includes(TEMPLATE_TAG));
+				return JSON.stringify(docs, null, 2);
+			}
+		},
+		{
+			name: "list_versions",
+			description: "列出文档全部版本（seq、发布时间、源文 hash）。只追加不覆盖，回滚也是新版本。",
+			inputSchema: {
+				type: "object",
+				required: ["id"],
+				properties: { id: { type: "string" } }
+			},
+			run: async (args) => {
+				const res = await api.getJson(`/api/docs/${encodeURIComponent(str(args["id"], "id"))}/versions`);
+				return JSON.stringify(res, null, 2);
+			}
+		},
+		{
+			name: "push_doc",
+			description: "发布本机的 markdown 文件（递归收集图片 / 嵌套 md 等本地引用并上传）。带 id 是给已有文档发新版本（标题 / 可见性 / 标签不传则保持原值）；不带 id 新建，默认 private。path 用绝对路径。",
+			inputSchema: {
+				type: "object",
+				required: ["path"],
+				properties: {
+					path: {
+						type: "string",
+						description: "入口 .md 的绝对路径"
+					},
+					id: {
+						type: "string",
+						description: "要更新的文档 id"
+					},
+					title: { type: "string" },
+					visibility: {
+						type: "string",
+						enum: [...VISIBILITIES]
+					},
+					tags: {
+						type: "array",
+						items: { type: "string" },
+						description: "整体覆盖标签；不传则不动"
+					}
+				}
+			},
+			run: async (args) => {
+				const path = str(args["path"], "path");
+				const tags = Array.isArray(args["tags"]) ? args["tags"].map(String) : void 0;
+				const res = await pushDoc(api, path, {
+					id: typeof args["id"] === "string" ? args["id"] : void 0,
+					title: typeof args["title"] === "string" ? args["title"] : void 0,
+					visibility: typeof args["visibility"] === "string" ? args["visibility"] : void 0,
+					tag: tags
+				});
+				return JSON.stringify(res, null, 2);
+			}
+		}
+	];
+}
+function write(msg) {
+	process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+function rpcError(id, code, message) {
+	write({
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code,
+			message
+		}
+	});
+}
+async function runMcp(api) {
+	const tools = buildTools(api);
+	const byName = new Map(tools.map((t) => [t.name, t]));
+	const handle = async (req) => {
+		const { id, method } = req;
+		const params = req.params ?? {};
+		if (typeof method !== "string") {
+			if (id !== void 0) rpcError(id, -32600, "method 缺失");
+			return;
+		}
+		if (id === void 0) return;
+		switch (method) {
+			case "initialize": {
+				const asked = typeof params["protocolVersion"] === "string" ? params["protocolVersion"] : "";
+				write({
+					jsonrpc: "2.0",
+					id,
+					result: {
+						protocolVersion: SUPPORTED_PROTOCOLS.includes(asked) ? asked : SUPPORTED_PROTOCOLS[0],
+						capabilities: { tools: {} },
+						serverInfo: SERVER_INFO,
+						instructions: INSTRUCTIONS
+					}
+				});
+				return;
+			}
+			case "ping":
+				write({
+					jsonrpc: "2.0",
+					id,
+					result: {}
+				});
+				return;
+			case "tools/list":
+				write({
+					jsonrpc: "2.0",
+					id,
+					result: { tools: tools.map(({ name, description, inputSchema }) => ({
+						name,
+						description,
+						inputSchema
+					})) }
+				});
+				return;
+			case "tools/call": {
+				const tool = typeof params["name"] === "string" ? byName.get(params["name"]) : void 0;
+				if (!tool) {
+					rpcError(id, -32602, `未知工具：${String(params["name"])}`);
+					return;
+				}
+				const args = params["arguments"] ?? {};
+				try {
+					write({
+						jsonrpc: "2.0",
+						id,
+						result: { content: [{
+							type: "text",
+							text: await tool.run(args)
+						}] }
+					});
+				} catch (err) {
+					write({
+						jsonrpc: "2.0",
+						id,
+						result: {
+							content: [{
+								type: "text",
+								text: err instanceof CliError ? `${err.message}${err.hint ? `（${err.hint}）` : ""}` : String(err)
+							}],
+							isError: true
+						}
+					});
+				}
+				return;
+			}
+			default: rpcError(id, -32601, `不支持的方法：${method}`);
+		}
+	};
+	const rl = createInterface({
+		input: process.stdin,
+		crlfDelay: Infinity
+	});
+	const pending = [];
+	for await (const line of rl) {
+		if (line.trim() === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			rpcError(null, -32700, "JSON 解析失败");
+			continue;
+		}
+		for (const msg of Array.isArray(parsed) ? parsed : [parsed]) {
+			if (msg === null || typeof msg !== "object") {
+				rpcError(null, -32600, "请求不是对象");
+				continue;
+			}
+			pending.push(handle(msg));
+		}
+	}
+	await Promise.all(pending);
+}
+//#endregion
+//#region src/widget.ts
+var SCOPES = ["official", "personal"];
 function exists(path) {
 	const st = statSync(path, { throwIfNoEntry: false });
 	return st !== void 0 && st.isFile();
@@ -3829,6 +4486,774 @@ async function pushWidget(api, dirArg) {
 	process.stdout.write(`${meta.scope}/${meta.name}@${meta.version}${src}${where}\n`);
 }
 //#endregion
+//#region src/widget-dev.ts
+var ARTIFACTS = [
+	"index.js",
+	"index.css",
+	"widget.json"
+];
+var MIME = {
+	"index.js": "text/javascript; charset=utf-8",
+	"index.css": "text/css; charset=utf-8",
+	"widget.json": "application/json; charset=utf-8"
+};
+/** 允许直接指向产物目录（如 packages/widgets/dist/Alert），也允许指向作者目录（取其 dist/）。 */
+function locateDist(dir) {
+	if (existsSync(join(dir, "index.js"))) return dir;
+	if (existsSync(join(dir, "dist", "index.js"))) return join(dir, "dist");
+	if (existsSync(join(dir, "package.json"))) return join(dir, "dist");
+	throw new CliError(`${dir} 下既没有 index.js 也没有 dist/`, "指向 jdu widget create 生成的目录，或某个构建产物目录");
+}
+function mtimeOf(dist) {
+	let latest = 0;
+	for (const f of ARTIFACTS) {
+		const st = statSync(join(dist, f), { throwIfNoEntry: false });
+		if (st && st.mtimeMs > latest) latest = st.mtimeMs;
+	}
+	return latest;
+}
+function readMeta(dir, dist) {
+	for (const p of [join(dist, "widget.json"), join(dir, "widget.json")]) {
+		if (!existsSync(p)) continue;
+		try {
+			const m = JSON.parse(readFileSync(p, "utf8"));
+			return {
+				name: typeof m["name"] === "string" ? m["name"] : "Widget",
+				version: typeof m["version"] === "string" ? m["version"] : ""
+			};
+		} catch {}
+	}
+	return {
+		name: "Widget",
+		version: ""
+	};
+}
+/** 线上 base.css 的地址：抓首页 HTML 里的 `/_v/base.<hash>.css`。拿不到返回 null，页面用兜底样式。 */
+async function siteBaseCss(server) {
+	if (!server) return null;
+	try {
+		const ctrl = new AbortController();
+		const t = setTimeout(() => ctrl.abort(), 2e3);
+		const html = await (await fetch(`${server}/`, {
+			signal: ctrl.signal,
+			redirect: "follow"
+		})).text();
+		clearTimeout(t);
+		const m = /\/_v\/base\.[a-f0-9]+\.css/.exec(html);
+		return m ? `${server}${m[0]}` : null;
+	} catch {
+		return null;
+	}
+}
+var esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
+function page(meta, baseCss, hasCss, mtime) {
+	return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(meta.name)} · jdu widget dev</title>
+${baseCss ? `<link rel="stylesheet" href="${esc(baseCss)}">` : ""}
+${hasCss ? `<link rel="stylesheet" href="/index.css?t=${mtime}">` : ""}
+<style>
+  /* 兜底 token：连不上 jiandu server 时也有亮 / 暗两套 */
+  :root { --jiandu-bg: #fff; --jiandu-bg-subtle: #f6f8fa; --jiandu-fg: #1f2328; --jiandu-fg-muted: #59636e; --jiandu-border: #d0d7de; --jiandu-font-sans: system-ui, sans-serif; --jiandu-font-mono: ui-monospace, monospace; }
+  .dark { --jiandu-bg: #0d1117; --jiandu-bg-subtle: #161b22; --jiandu-fg: #e6edf3; --jiandu-fg-muted: #9198a1; --jiandu-border: #3d444d; }
+  html { background: var(--jiandu-bg); color: var(--jiandu-fg); font-family: var(--jiandu-font-sans); }
+  body { margin: 0; }
+  .dev-bar { display: flex; gap: 1rem; align-items: center; padding: 0.5rem 1rem; border-bottom: 1px solid var(--jiandu-border); font-size: 13px; color: var(--jiandu-fg-muted); }
+  .dev-bar b { color: var(--jiandu-fg); }
+  .dev-bar button { margin-left: auto; padding: 0.25rem 0.6rem; border: 1px solid var(--jiandu-border); border-radius: 6px; background: var(--jiandu-bg-subtle); color: inherit; cursor: pointer; }
+  .dev-main { max-width: 760px; margin: 0 auto; padding: 1.5rem 1rem; }
+  .dev-stage { min-height: 4rem; padding: 1rem; border: 1px dashed var(--jiandu-border); border-radius: 8px; }
+  details { margin-top: 1.5rem; font-size: 13px; color: var(--jiandu-fg-muted); }
+  textarea { width: 100%; min-height: 8rem; margin-top: 0.5rem; padding: 0.5rem; box-sizing: border-box; border: 1px solid var(--jiandu-border); border-radius: 6px; background: var(--jiandu-bg-subtle); color: var(--jiandu-fg); font: 12px/1.5 var(--jiandu-font-mono); }
+  .dev-err { color: #d1242f; white-space: pre-wrap; font-family: var(--jiandu-font-mono); font-size: 12px; }
+  .dev-degraded { padding: 0.75rem; border-radius: 6px; background: var(--jiandu-bg-subtle); font-family: var(--jiandu-font-mono); font-size: 12px; white-space: pre-wrap; }
+</style>
+</head>
+<body>
+<div class="dev-bar"><b>${esc(meta.name)}</b><span>${esc(meta.version)}</span><span id="status">加载中…</span><button type="button" id="dark">切换暗色</button></div>
+<main class="dev-main jiandu-doc">
+  <div class="dev-stage"><div id="island" data-jiandu-island="b0-dev00000" data-widget="${esc(meta.name)}"></div></div>
+  <details open>
+    <summary>sampleData（改了即时 update；校验发生在 push 后 server 渲染期，这里不校验）</summary>
+    <textarea id="data" spellcheck="false"></textarea>
+    <div id="err" class="dev-err" role="alert"></div>
+  </details>
+</main>
+<script type="module">
+const $ = (id) => document.getElementById(id);
+const started = ${mtime};
+const island = $('island'), ta = $('data'), err = $('err'), status = $('status');
+$('dark').addEventListener('click', () => { document.documentElement.classList.toggle('dark'); inst?.update?.(ctx(data)); });
+
+// 与 viewer loader 同一条链路：import → new → mount(el, ctx)；抛错就按线上的降级形态显示原始 fence
+let meta = {}, inst = null, W = null, data = {};
+const ctx = (d) => ({ data: d, loading: false, blockId: 'b0-dev00000', source: JSON.stringify(d, null, 2), language: 'widget_component:' + (meta.name ?? '') });
+function degrade(reason) {
+  const pre = document.createElement('pre');
+  pre.className = 'dev-degraded';
+  pre.textContent = '[降级为代码块] ' + reason + '\\n\\n\`\`\`widget_component:' + (meta.name ?? '') + '\\n' + JSON.stringify(data, null, 2) + '\\n\`\`\`';
+  island.replaceChildren(pre);
+  status.textContent = '挂载失败';
+}
+function remount() {
+  try { inst?.destroy?.(); } catch {}
+  island.replaceChildren();
+  try { inst = new W(); inst.mount(island, ctx(data)); status.textContent = '已挂载'; }
+  catch (e) { degrade(e instanceof Error ? e.message : String(e)); }
+}
+try {
+  meta = await (await fetch('/widget.json', { cache: 'no-store' })).json();
+  data = meta.sampleData ?? {};
+  ta.value = JSON.stringify(data, null, 2);
+  const mod = await import('/index.js?t=' + started);
+  W = mod.default;
+  if (typeof W !== 'function') throw new Error('默认导出不是可构造的 class');
+  remount();
+} catch (e) { degrade(e instanceof Error ? e.message : String(e)); }
+
+ta.addEventListener('input', () => {
+  try {
+    data = JSON.parse(ta.value); err.textContent = '';
+    if (inst?.update) inst.update(ctx(data)); else remount();
+  } catch (e) { err.textContent = e instanceof Error ? e.message : String(e); }
+});
+
+// 产物 mtime 变了就整页刷新（watch 构建完成 → 这里 <1s 内看到）
+setInterval(async () => {
+  try {
+    const s = await (await fetch('/__status', { cache: 'no-store' })).json();
+    if (s.mtime !== started && s.mtime > 0) location.reload();
+  } catch {}
+}, 700);
+<\/script>
+</body>
+</html>
+`;
+}
+async function runWidgetDev(dirArg, opts) {
+	const dir = resolve(dirArg);
+	const dist = locateDist(dir);
+	const baseCss = await siteBaseCss(opts.server);
+	let child = null;
+	const pkgPath = join(dir, "package.json");
+	if (opts.watch && existsSync(pkgPath)) {
+		if (JSON.parse(readFileSync(pkgPath, "utf8")).scripts?.["watch"]) {
+			child = spawn("npm", ["run", "watch"], {
+				cwd: dir,
+				stdio: "inherit",
+				shell: process.platform === "win32"
+			});
+			child.on("exit", (code) => {
+				if (code !== null && code !== 0) process.stderr.write(`jdu: npm run watch 退出（${code}），预览页仍在，产物不再更新\n`);
+			});
+		} else process.stderr.write("jdu: package.json 没有 watch 脚本，不自动构建；改完源码请自行 build\n");
+	}
+	const server = createServer((req, res) => {
+		const url = new URL(req.url ?? "/", "http://localhost");
+		const send = (code, type, body) => {
+			res.writeHead(code, {
+				"Content-Type": type,
+				"Cache-Control": "no-store"
+			});
+			res.end(body);
+		};
+		if (url.pathname === "/") return send(200, "text/html; charset=utf-8", page(readMeta(dir, dist), baseCss, existsSync(join(dist, "index.css")), mtimeOf(dist)));
+		if (url.pathname === "/__status") return send(200, "application/json", JSON.stringify({ mtime: mtimeOf(dist) }));
+		const file = url.pathname.slice(1);
+		if (ARTIFACTS.includes(file)) {
+			const p = join(dist, file);
+			if (!existsSync(p)) return send(404, "text/plain; charset=utf-8", `${file} 还没构建出来`);
+			return send(200, MIME[file], readFileSync(p));
+		}
+		return send(404, "text/plain; charset=utf-8", "not found");
+	});
+	await new Promise((ok, fail) => {
+		server.once("error", fail);
+		server.listen(opts.port, "127.0.0.1", () => ok());
+	}).catch((err) => {
+		child?.kill();
+		throw new CliError(`预览 server 起不来：${err.code ?? err.message}`, `端口 ${opts.port} 可能被占用，换 --port`);
+	});
+	process.stderr.write(`预览  http://127.0.0.1:${opts.port}/\n产物  ${dist}\n${baseCss ? `样式  ${baseCss}\n` : "样式  未连上 jiandu server，用内置兜底 token\n"}Ctrl+C 退出\n`);
+	await new Promise((done) => {
+		const stop = () => {
+			child?.kill();
+			server.close(() => done());
+		};
+		process.once("SIGINT", stop);
+		process.once("SIGTERM", stop);
+		child?.once("exit", () => {});
+	});
+}
+//#endregion
+//#region src/widget-scaffold.ts
+/**
+* `jdu widget create`（M3，#38）：生成一个能直接 build / dev / push 的 widget 目录。
+*
+* 模板刻意「全内联」：契约类型、框架适配基类、构建脚本都拷进作者目录，不依赖任何 jiandu 的 npm 包——
+* 平台对 widget 只做鸭子类型检查，作者拿到的是自己的代码，改坏了也只影响自己。
+* dataSchema 从 `src/types.ts` 的 `export interface Data` 生成（JSDoc 直通 description / @default），
+* 由作者目录里的 ts-json-schema-generator 在 build 时做，CLI 本身不带 TS 编译器。
+*/
+var TEMPLATES = [
+	"vanilla",
+	"react",
+	"vue"
+];
+var RUNTIMES = ["shared", "custom"];
+var REACT_SPECIFIERS = [
+	"react",
+	"react-dom",
+	"react-dom/client",
+	"react/jsx-runtime"
+];
+var NAME_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+/** `star-rating` / `star_rating` / `StarRating` → `StarRating`（class 名 / widget 名）。 */
+function pascalCase(name) {
+	return name.split(/[-_]+/).filter(Boolean).map((p) => p[0]?.toUpperCase() + p.slice(1)).join("");
+}
+/** `StarRating` → `star-rating`（目录 / package 名 / css class）。 */
+function kebabCase(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase();
+}
+var CONTRACT_TS = `/**
+ * 平台 mount 契约（与 jiandu 的 packages/render/src/types.ts 同构，拷贝一份免得依赖 jiandu 的包）。
+ * 宿主只做鸭子类型检查：默认导出无参可构造 class，实例有 mount，update / destroy 可选。
+ */
+export interface WidgetContext<D = unknown> {
+  /** fence 里作者写的 JSON（未声明流式时保证完整且已过 dataSchema 校验） */
+  data: D;
+  /** 流式输出中 data 尚未完整时为 true（未声明流式的 widget 恒为 false） */
+  loading: boolean;
+  /** 所属块的稳定 id，可当 DOM id 前缀用 */
+  blockId: string;
+  /** 原始 fence 正文 */
+  source: string;
+  /** 原始代码块语言标识，如 \`widget_component:StarRating\` */
+  language: string;
+  /**
+   * 嵌套 markdown：dataSchema 里标了 \`contentMediaType: "text/markdown"\` 的字符串字段，宿主渲成已 sanitize 的 HTML
+   * 放在这里（JSON pointer → HTML，如 \`/content\`），widget 直接 innerHTML；宿主没给时退回纯文本。
+   * src/types.ts 里给字段加 JSDoc \`@contentMediaType text/markdown\` 即可声明。
+   */
+  rendered?: Record<string, string>;
+}
+
+export interface WidgetConfigDecl {
+  /** 声明 true 才会在流式生成中途被 mount，并要自己处理半截 data；默认 false */
+  streaming?: boolean;
+}
+
+export interface WidgetInstance<D = unknown> {
+  mount(el: HTMLElement, ctx: WidgetContext<D>): void;
+  update?(ctx: WidgetContext<D>): void;
+  destroy?(): void;
+}
+
+export interface WidgetClass<D = unknown> {
+  new (): WidgetInstance<D>;
+  __widgetConfig?: WidgetConfigDecl;
+}
+`;
+var TYPES_TS = (c) => `// fence 里的 data 长什么样，这里是唯一事实：\`npm run build\` 会把 Data 生成为 widget.json 的 dataSchema
+// （字段上的 JSDoc → description，@default → default）。文档里的 data 不合法时平台会把 fence 降级成代码块。
+//
+//   \`\`\`widget_component:${c.name}
+//   { "title": "你好，简牍", "count": 3 }
+//   \`\`\`
+//
+// 接口本身别写 JSDoc——那会整段进 schema 的 description。
+
+export interface Data {
+  /** 标题 */
+  title: string;
+  /**
+   * 计数
+   * @default 0
+   */
+  count?: number;
+}
+`;
+var STYLE_CSS = (c) => `/* 颜色一律走 --jiandu-* token（带兜底值），亮 / 暗主题跟宿主一起变；暗色用 .dark 选择器，不要 prefers-color-scheme */
+.w-${c.kebab} {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--jiandu-border, #d0d7de);
+  border-radius: 8px;
+  background: var(--jiandu-bg-subtle, #f6f8fa);
+  color: var(--jiandu-fg, #1f2328);
+  font: 14px/1.4 var(--jiandu-font-sans, system-ui, sans-serif);
+}
+.w-${c.kebab} button {
+  padding: 0 0.5rem;
+  border: 1px solid var(--jiandu-border, #d0d7de);
+  border-radius: 6px;
+  background: var(--jiandu-bg, #fff);
+  color: inherit;
+  cursor: pointer;
+}
+`;
+var VANILLA_INDEX = (c) => `import type { WidgetContext } from './_base/contract.js';
+import type { Data } from './types.js';
+import './style.css';
+
+/**
+ * ${c.name}：默认导出无参可构造的 class，副作用全在 mount 里（构造函数不做事）。
+ * 默认非流式——mount 时 ctx.data 已完整且过了 dataSchema 校验，不用写守卫。
+ */
+export default class ${c.cls} {
+  private root?: HTMLElement;
+  private count = 0;
+
+  mount(el: HTMLElement, ctx: WidgetContext<Data>): void {
+    this.root = document.createElement('div');
+    this.root.className = 'w-${c.kebab}';
+    el.replaceChildren(this.root);
+    this.count = ctx.data.count ?? 0;
+    this.render(ctx.data);
+  }
+
+  /** 主题切换、或声明流式后 data 补齐时宿主会调；这里简单重画 */
+  update(ctx: WidgetContext<Data>): void {
+    this.render(ctx.data);
+  }
+
+  destroy(): void {
+    this.root?.remove();
+  }
+
+  private render(data: Data): void {
+    if (!this.root) return;
+    const title = document.createElement('strong');
+    title.textContent = data.title;
+    const num = document.createElement('span');
+    num.textContent = \`× \${this.count}\`;
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.textContent = '+1';
+    btn.addEventListener('click', () => {
+      this.count += 1;
+      num.textContent = \`× \${this.count}\`;
+    });
+    this.root.replaceChildren(title, num, btn);
+  }
+}
+`;
+var REACT_BASE = `import { createElement } from 'react';
+import type { ComponentType } from 'react';
+import { createRoot } from 'react-dom/client';
+import type { Root } from 'react-dom/client';
+import type { WidgetClass, WidgetConfigDecl, WidgetContext } from './contract.js';
+
+export interface WidgetProps<D> {
+  data: D;
+  ctx: WidgetContext<D>;
+}
+
+/**
+ * React 组件 → mount 契约 class。update 走 React diff 不拆重建，destroy 卸载 root。
+ * 第二个参数原样成为 __widgetConfig（要处理流式半截 data 才传 { streaming: true }）。
+ */
+export function reactWidget<D>(Component: ComponentType<WidgetProps<D>>, config: WidgetConfigDecl = {}): WidgetClass<D> {
+  return class {
+    static __widgetConfig = config;
+    private root?: Root;
+
+    mount(el: HTMLElement, ctx: WidgetContext<D>): void {
+      this.root = createRoot(el);
+      this.root.render(createElement(Component, { data: ctx.data, ctx }));
+    }
+
+    update(ctx: WidgetContext<D>): void {
+      this.root?.render(createElement(Component, { data: ctx.data, ctx }));
+    }
+
+    destroy(): void {
+      this.root?.unmount();
+    }
+  };
+}
+`;
+var REACT_INDEX = `import { reactWidget } from './_base/react-widget.js';
+import { App } from './App.js';
+
+export default reactWidget(App);
+`;
+var REACT_APP = (c) => `import { useState } from 'react';
+import type { WidgetProps } from './_base/react-widget.js';
+import type { Data } from './types.js';
+import './style.css';
+
+/** 组件只管渲染 data；mount 时 data 已完整且过了 dataSchema 校验，不用写守卫。 */
+export function App({ data }: WidgetProps<Data>) {
+  const [count, setCount] = useState(data.count ?? 0);
+  return (
+    <div className="w-${c.kebab}">
+      <strong>{data.title}</strong>
+      <span>× {count}</span>
+      <button type="button" onClick={() => setCount((n) => n + 1)}>
+        +1
+      </button>
+    </div>
+  );
+}
+`;
+var VUE_BASE = `import { createApp, h, shallowReactive } from 'vue';
+import type { App, Component } from 'vue';
+import type { WidgetClass, WidgetConfigDecl, WidgetContext } from './contract.js';
+
+/**
+ * Vue 组件 → mount 契约 class。根组件收 \`data\` 与 \`ctx\` 两个 prop；
+ * update 只改响应式状态，Vue 自己 patch；destroy 卸载 app。
+ */
+export function vueWidget<D>(Root: Component, config: WidgetConfigDecl = {}): WidgetClass<D> {
+  return class {
+    static __widgetConfig = config;
+    private app?: App;
+    private state = shallowReactive<{ ctx: WidgetContext<D> | null }>({ ctx: null });
+
+    mount(el: HTMLElement, ctx: WidgetContext<D>): void {
+      this.state.ctx = ctx;
+      this.app = createApp({
+        render: () => (this.state.ctx ? h(Root, { data: this.state.ctx.data, ctx: this.state.ctx }) : null),
+      });
+      this.app.mount(el);
+    }
+
+    update(ctx: WidgetContext<D>): void {
+      this.state.ctx = ctx;
+    }
+
+    destroy(): void {
+      this.app?.unmount();
+    }
+  };
+}
+`;
+var VUE_INDEX = `import { vueWidget } from './_base/vue-widget.js';
+import { App } from './App.js';
+
+export default vueWidget(App);
+`;
+var VUE_APP = (c) => `import { defineComponent, h, ref } from 'vue';
+import type { PropType } from 'vue';
+import type { Data } from './types.js';
+import './style.css';
+
+// ponytail: 用 h() 渲染函数而不是 .vue 单文件——零编译插件；想写 SFC 就给 scripts/build.mjs 加 esbuild 的 vue 插件
+export const App = defineComponent({
+  props: { data: { type: Object as PropType<Data>, required: true } },
+  setup(props) {
+    const count = ref(props.data.count ?? 0);
+    return () =>
+      h('div', { class: 'w-${c.kebab}' }, [
+        h('strong', props.data.title),
+        h('span', \`× \${count.value}\`),
+        h('button', { type: 'button', onClick: () => (count.value += 1) }, '+1'),
+      ]);
+  },
+});
+`;
+var BUILD_MJS = (c) => `#!/usr/bin/env node
+/**
+ * 由 \`jdu widget create\` 生成的构建脚本（全内联，改它就是改你自己的构建）：
+ *   1. esbuild 打成单文件 ESM（--platform=browser；产物里出现 node 内置模块 server 会拒收）
+ *   2. widget.json 的 dataSchema 从 src/types.ts 的 \`Data\` 重新生成，写到 dist/ 与源目录
+ *   3. 源码拷到 dist/src —— \`jdu widget push dist\` 会把它一并上传，注册表里不只剩 minify 过的 bundle
+ * \`node scripts/build.mjs --watch\` 监听改动重建，配 \`jdu widget dev\` 的预览页自动刷新。
+ */
+import { build, context } from 'esbuild';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const DIST = join(ROOT, 'dist');
+const ENTRY = '${c.template === "react" ? "src/index.tsx" : "src/index.ts"}';
+
+/**
+ * 平台版本档 runtime（shared 档）：这些 bare import 不打进产物，改写成 jiandu 上内容寻址的 runtime URL，
+ * 同档 widget 在浏览器里共享一份下载。null = custom 档，框架全内联进产物（任何框架任何版本都行）。
+ * 值来自 \`GET /api/runtimes\`（create 时抄下来的${c.tierLabel ? `：${c.tierLabel}` : ""}）；平台升级档位不追溯，重新 create 或手改这里才换。
+ */
+const RUNTIME_PATHS = ${c.runtime ? JSON.stringify(c.runtime, null, 2) : "null"};
+
+const runtimePlugin = {
+  name: 'jiandu-runtime',
+  setup(b) {
+    if (!RUNTIME_PATHS) return;
+    b.onResolve({ filter: /^(react|react-dom|react-dom\\/client|react\\/jsx-runtime)$/ }, (args) => ({
+      path: RUNTIME_PATHS[args.path],
+      external: true,
+    }));
+  },
+};
+
+async function dataSchema(fallback) {
+  try {
+    const { createGenerator } = await import('ts-json-schema-generator');
+    const schema = createGenerator({
+      path: join(ROOT, 'src/types.ts'),
+      tsconfig: join(ROOT, 'tsconfig.json'),
+      type: 'Data',
+      skipTypeCheck: true,
+      expose: 'none',
+      topRef: false,
+      additionalProperties: true,
+      // 字段 JSDoc 写 @contentMediaType text/markdown → 宿主把该字段渲成 HTML 放进 ctx.rendered
+      extraTags: ['contentMediaType'],
+    }).createSchema('Data');
+    delete schema.$schema;
+    if (schema.definitions && Object.keys(schema.definitions).length === 0) delete schema.definitions;
+    return schema;
+  } catch (err) {
+    console.warn(\`[widget] dataSchema 未重新生成（\${err.message}），沿用 widget.json 里的现值\`);
+    return fallback;
+  }
+}
+
+async function emitMeta() {
+  const meta = JSON.parse(readFileSync(join(ROOT, 'widget.json'), 'utf8'));
+  meta.dataSchema = await dataSchema(meta.dataSchema);
+  const text = \`\${JSON.stringify(meta, null, 2)}\\n\`;
+  mkdirSync(DIST, { recursive: true });
+  writeFileSync(join(DIST, 'widget.json'), text);
+  writeFileSync(join(ROOT, 'widget.json'), text);
+  rmSync(join(DIST, 'src'), { recursive: true, force: true });
+  cpSync(join(ROOT, 'src'), join(DIST, 'src'), { recursive: true });
+}
+
+const options = {
+  entryPoints: [join(ROOT, ENTRY)],
+  bundle: true,
+  format: 'esm',
+  target: 'es2022',
+  platform: 'browser',
+  minify: true,
+  outfile: join(DIST, 'index.js'),
+  define: { 'process.env.NODE_ENV': '"production"' },
+  jsx: 'automatic',
+  logLevel: 'info',
+  plugins: [
+    runtimePlugin,
+    {
+      name: 'widget-json',
+      setup(b) {
+        b.onEnd(async (result) => {
+          if (result.errors.length === 0) await emitMeta();
+        });
+      },
+    },
+  ],
+};
+
+if (process.argv.includes('--watch')) {
+  const ctx = await context(options);
+  await ctx.watch();
+  console.log('[widget] watching src/ …');
+} else {
+  if (existsSync(DIST)) rmSync(DIST, { recursive: true, force: true });
+  await build(options);
+}
+`;
+var TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": [],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src"]
+}
+`;
+var PACKAGE_JSON = (c) => {
+	const dev = {
+		esbuild: "^0.28.2",
+		"ts-json-schema-generator": "^2.9.0",
+		typescript: "^5.9.0"
+	};
+	if (c.template === "react") Object.assign(dev, {
+		react: "^19.2.0",
+		"react-dom": "^19.2.0",
+		"@types/react": "^19.2.0",
+		"@types/react-dom": "^19.2.0"
+	});
+	if (c.template === "vue") dev["vue"] = "^3.5.0";
+	const sorted = Object.fromEntries(Object.entries(dev).sort(([a], [b]) => a.localeCompare(b)));
+	return `${JSON.stringify({
+		name: `widget-${c.kebab}`,
+		private: true,
+		type: "module",
+		scripts: {
+			build: "node scripts/build.mjs",
+			watch: "node scripts/build.mjs --watch",
+			dev: "jdu widget dev",
+			push: "npm run build && jdu widget push dist",
+			typecheck: "tsc -p tsconfig.json --noEmit"
+		},
+		devDependencies: sorted
+	}, null, 2)}\n`;
+};
+var WIDGET_JSON = (c) => `${JSON.stringify({
+	name: c.name,
+	scope: "personal",
+	version: "1.0.0",
+	dataSchema: {
+		type: "object",
+		required: ["title"],
+		properties: {
+			title: {
+				type: "string",
+				description: "标题"
+			},
+			count: {
+				type: "number",
+				description: "计数",
+				default: 0
+			}
+		},
+		additionalProperties: true
+	},
+	sampleData: {
+		title: "你好，简牍",
+		count: 3
+	}
+}, null, 2)}\n`;
+var README = (c) => `# ${c.name}
+
+由 \`jdu widget create ${c.name} --template ${c.template}${c.template === "react" ? ` --runtime ${c.runtime ? "shared" : "custom"}` : ""}\` 生成。
+
+\`\`\`sh
+npm install
+npm run dev          # = jdu widget dev：起 watch 构建 + 本地预览页（sampleData 挂载，改代码自动刷新）
+npm run push         # = build + jdu widget push dist
+\`\`\`
+
+然后在任何一篇文档里：
+
+\`\`\`\`markdown
+\`\`\`widget_component:${c.name}
+{ "title": "你好，简牍", "count": 3 }
+\`\`\`
+\`\`\`\`
+
+## 改什么
+
+| 文件 | 作用 |
+|---|---|
+| \`src/types.ts\` | \`Data\` 接口 = fence 里 data 的唯一事实。JSDoc → description，\`@default\` → default；\`npm run build\` 生成 widget.json 的 dataSchema |
+| ${c.template === "vanilla" ? "`src/index.ts`" : c.template === "react" ? "`src/App.tsx`" : "`src/App.ts`"} | 渲染逻辑${c.template === "vanilla" ? "（mount / update / destroy 三个生命周期）" : "（组件收 `data` prop；契约适配在 `src/_base/`，一般不用动）"} |
+| \`src/style.css\` | 样式。颜色走 \`--jiandu-*\` token 带兜底值，暗色用 \`.dark\` 选择器 |
+| \`widget.json\` | name / scope / version / sampleData；dataSchema 由 build 生成，不用手写 |
+| \`scripts/build.mjs\` | 全内联构建配置${c.runtime ? "；`RUNTIME_PATHS` 是平台版本档 runtime 的 URL" : ""} |
+
+版本号改 \`widget.json\` 的 \`version\`；同名同版本重推会覆盖产物、不改上线状态。
+
+## 契约要点
+
+- 默认导出无参可构造 class，实例有 \`mount(el, ctx)\`，\`update\` / \`destroy\` 可选；平台只做鸭子类型检查
+- 默认非流式：mount 时 \`ctx.data\` 完整且已过 dataSchema 校验，**不用写守卫**。要在 AI 流式生成中途就渲染，声明 \`static __widgetConfig = { streaming: true }\` 并自己处理半截 data
+- 产物必须是浏览器可跑的单文件 ESM：不要 import node 内置模块，server 会拒收
+- 字段要支持嵌套 Markdown：在 \`src/types.ts\` 给它加 JSDoc \`@contentMediaType text/markdown\`，宿主会渲成已 sanitize 的 HTML 放进 \`ctx.rendered['/字段']\`，直接 innerHTML；\`jdu widget dev\` 预览里没有这一步，会看到原文
+${c.runtime ? `- shared 档：\`react\` 等四个 import 改写为平台 runtime URL（${c.tierLabel ?? ""}），产物只有几 KB。要用平台没有的框架 / 版本，把 \`scripts/build.mjs\` 的 \`RUNTIME_PATHS\` 设为 null 即 custom 档` : ""}
+`;
+var GITIGNORE = `node_modules/\ndist/\n`;
+function filesFor(c) {
+	const files = /* @__PURE__ */ new Map();
+	files.set("package.json", PACKAGE_JSON(c));
+	files.set("tsconfig.json", TSCONFIG);
+	files.set("widget.json", WIDGET_JSON(c));
+	files.set("README.md", README(c));
+	files.set(".gitignore", GITIGNORE);
+	files.set("scripts/build.mjs", BUILD_MJS(c));
+	files.set("src/_base/contract.ts", CONTRACT_TS);
+	files.set("src/types.ts", TYPES_TS(c));
+	files.set("src/style.css", STYLE_CSS(c));
+	if (c.template === "vanilla") files.set("src/index.ts", VANILLA_INDEX(c));
+	else if (c.template === "react") {
+		files.set("src/_base/react-widget.ts", REACT_BASE);
+		files.set("src/index.tsx", REACT_INDEX);
+		files.set("src/App.tsx", REACT_APP(c));
+	} else {
+		files.set("src/_base/vue-widget.ts", VUE_BASE);
+		files.set("src/index.ts", VUE_INDEX);
+		files.set("src/App.ts", VUE_APP(c));
+	}
+	return files;
+}
+/** 从 server 拿平台默认档的四个 runtime URL。拿不到就报错——静默退成 custom 会让作者以为自己在 shared 档。 */
+async function fetchRuntime(api) {
+	let client;
+	try {
+		client = await api();
+	} catch (err) {
+		throw new CliError(`shared 档要从 server 取 runtime 地址，但 CLI 未配置：${err instanceof Error ? err.message : String(err)}`, "先 jdu init / login，或改用 --runtime custom（自带 react 全内联，不需要 server）");
+	}
+	const res = await client.getJson("/api/runtimes");
+	const name = typeof res?.default === "string" ? res.default : null;
+	const tier = name ? res.tiers?.[name] : void 0;
+	const paths = tier?.paths;
+	if (!name || !tier || paths === null || typeof paths !== "object") throw new CliError(`server ${client.server} 没有可用的 shared 档 runtime`, "实例可能关了 official 种子（JIANDU_SEED_OFFICIAL=0）；改用 --runtime custom");
+	const out = {};
+	for (const spec of REACT_SPECIFIERS) {
+		const url = paths[spec];
+		if (typeof url !== "string") throw new CliError(`/api/runtimes 的 ${name} 档缺 ${spec}`);
+		out[spec] = url.startsWith("/") ? url : `/${url}`;
+	}
+	return {
+		paths: out,
+		label: `${name}${typeof tier.label === "string" ? ` · ${tier.label}` : ""}`
+	};
+}
+async function createWidget(nameArg, opts, api) {
+	if (!NAME_RE.test(nameArg)) throw new CliError(`widget 名不合法：${nameArg}`, "字母开头，只允许字母 / 数字 / - / _，最长 64");
+	const template = opts.template;
+	if (!TEMPLATES.includes(template)) throw new CliError(`未知模板：${opts.template}`, `可选：${TEMPLATES.join(" | ")}`);
+	const runtimeOpt = opts.runtime;
+	if (!RUNTIMES.includes(runtimeOpt)) throw new CliError(`未知 runtime：${opts.runtime}`, `可选：${RUNTIMES.join(" | ")}`);
+	const name = pascalCase(nameArg);
+	const dir = resolve(opts.dir ?? kebabCase(name));
+	if (existsSync(dir) && readdirSync(dir).length > 0) throw new CliError(`目录非空：${dir}`, "换个名字，或用 --dir 指定输出目录");
+	let runtime = null;
+	let tierLabel = null;
+	if (template === "react" && runtimeOpt === "shared") {
+		const rt = await fetchRuntime(api);
+		runtime = rt.paths;
+		tierLabel = rt.label;
+	}
+	const files = filesFor({
+		name,
+		cls: name,
+		kebab: kebabCase(name),
+		template,
+		runtime,
+		tierLabel
+	});
+	for (const [rel, content] of files) {
+		const abs = join(dir, rel);
+		mkdirSync(dirname(abs), { recursive: true });
+		writeFileSync(abs, content, "utf8");
+	}
+	return {
+		dir,
+		files: [...files.keys()],
+		template,
+		runtime: template === "react" ? runtime ? "shared" : "custom" : null,
+		tier: tierLabel
+	};
+}
+//#endregion
 //#region src/cli.ts
 async function client() {
 	return new ApiClient(await loadRuntimeConfig());
@@ -3838,22 +5263,39 @@ function collectTag(value, previous) {
 	return [...previous ?? [], value];
 }
 var program = new Command();
-program.name("jdu").description("jiandu 命令行").version("0.1.0").showHelpAfterError();
-program.command("login").description("登录到 jiandu server（forward-auth 会打开浏览器走 SSO）").requiredOption("--server <url>", "jiandu server 地址").option("--token <token>", "直接保存访问 token（token provider / 跳过浏览器）").option("--issuer <url>", "OIDC issuer（缺省读 healthz.oidc 或 JIANDU_OIDC_ISSUER）").option("--client-id <id>", "OIDC client id（缺省读 healthz.oidc 或 JIANDU_OIDC_CLIENT_ID）").action(async (opts) => {
+program.name("jdu").description("jiandu 命令行").version("0.3.0").showHelpAfterError();
+program.command("init").description("选定部署目标并初始化本地配置（默认官方线上；自部署 / 本机需显式指定）").option("--local", "目标是本机自部署（http://127.0.0.1:8080）").option("--server <url>", "目标是指定的自部署地址").option("--token <token>", "一并完成 token 登录（server 首启 stdout / data/initial-token.txt）").option("--no-browser", "站点支持浏览器授权时也不打开浏览器，只给 token 指引").option("--json", "机器可读输出（agent 联动用；不会打开浏览器）", false).action(async (opts) => {
+	const result = await runInit({
+		...opts,
+		browser: opts.browser && !opts.json
+	});
+	if (opts.json) {
+		process.stdout.write(`${JSON.stringify(result)}\n`);
+		return;
+	}
+	process.stdout.write(`目标 ${result.target} · ${result.server}（auth: ${result.authProvider}）\n`);
+	process.stdout.write(`配置已写入 ${result.configPath}\n`);
+	process.stdout.write(result.loggedIn ? "凭据就绪，可以直接 jdu push。\n" : `下一步：${result.next ?? ""}\n`);
+});
+program.command("login").description("登录到 jiandu server（forward-auth 默认打开浏览器走 SSO；--user 则直连注入身份头）").requiredOption("--server <url>", "jiandu server 地址").option("--token <token>", "直接保存访问 token（token provider / 跳过浏览器）").option("--user <owner>", "forward-auth：以指定 owner 直连（请求注入 X-Forwarded-User 头，跳过 SSO）").option("--proxy-secret <secret>", "forward-auth：网关共享密钥（请求注入 X-Jiandu-Proxy-Secret 头）").option("--issuer <url>", "OIDC issuer（缺省读 healthz.oidc 或 JIANDU_OIDC_ISSUER）").option("--client-id <id>", "OIDC client id（缺省读 healthz.oidc 或 JIANDU_OIDC_CLIENT_ID）").action(async (opts) => {
 	const result = await runLogin({
 		server: opts.server,
 		token: opts.token,
+		user: opts.user,
+		proxySecret: opts.proxySecret,
 		issuer: opts.issuer,
 		clientId: opts.clientId
 	});
 	process.stdout.write(`${result.configPath}\n`);
 	if (result.source === "anonymous") process.stderr.write("这个 server 是匿名模式，无需登录。\n");
+	if (result.source === "forward-auth") process.stderr.write("已保存 forward-auth 直连身份（X-Forwarded-User）。\n");
 	if (result.source === "oidc-cache") process.stderr.write("已复用本机 SSO credential。\n");
 	if (result.source === "oidc-browser") process.stderr.write("SSO 登录成功。\n");
 	if (result.warning) process.stderr.write(`jdu: ${result.warning}\n`);
 });
-program.command("push").argument("<entry.md>", "入口 markdown 文件").description("递归收集本地引用、增量上传并发布一个新版本").option("--title <title>", "文档标题，默认取首个一级标题").option("--visibility <v>", `${VISIBILITIES.join(" | ")}（新文档默认 private；更新已有文档时不传则保持原值）`).option("--id <docId>", "复用已有文档 id（发布新版本）").option("--tag <name>", "打标签，可重复；不传则保持原有标签", collectTag, void 0).action(async (entry, opts) => {
-	await pushDoc(await client(), entry, opts);
+program.command("push").argument("<entry.md>", "入口 markdown 文件").description("递归收集本地引用、增量上传并发布一个新版本").option("--title <title>", "文档标题，默认取首个一级标题").option("--visibility <v>", `${VISIBILITIES.join(" | ")}（新文档默认 private；更新已有文档时不传则保持原值）`).option("--id <docId>", "复用已有文档 id（发布新版本）").option("--tag <name>", "打标签，可重复；不传则保持原有标签", collectTag, void 0).option("--official", "上架到官方知识库（需管理员；同时公开）").action(async (entry, opts) => {
+	const res = await pushDoc(await client(), entry, opts);
+	process.stdout.write(`${res.url}\n`);
 });
 program.command("list").description("列出文档").option("--all", "包含已归档", false).action(async (opts) => {
 	printTable(asRows(await (await client()).getJson(`/api/docs${opts.all ? "?all=1" : ""}`), "docs"), [
@@ -3882,16 +5324,16 @@ program.command("versions").argument("<docId>").description("列出某文档的
 			header: "SEQ"
 		},
 		{
-			key: "created_at",
+			key: "createdAt",
 			header: "CREATED"
 		},
 		{
-			key: "source_hash",
+			key: "sourceHash",
 			header: "SOURCE"
 		},
 		{
-			key: "html_hash",
-			header: "HTML"
+			key: "resolvedMdHash",
+			header: "RESOLVED"
 		}
 	]);
 });
@@ -3958,38 +5400,98 @@ tag.command("rm").argument("<name>").description("删除标签：只解绑，文
 	const res = await (await client()).postJson("/api/tags/delete", { name });
 	process.stdout.write(`已删除 ${name}（解绑 ${String(res.unlinked ?? 0)} 篇）\n`);
 });
-program.command("share").argument("<docId>").description("改可见性 / 团队归属 / 按人授权").option("--visibility <v>", VISIBILITIES.join(" | ")).option("--team <teamId>", "设为团队可见；传空串取消").option("--to <user>", "授权给某人，可重复（整体覆盖）", collectTag, void 0).action(async (docId, opts) => {
+program.command("comments").argument("<docId>").description("列出文档的评论线程（默认只列未 resolve；块 id / 引文 / 作者 / 回复）").option("--all", "包含已 resolve 的线程", false).action(async (docId, opts) => {
+	await listComments(await client(), docId, opts);
+});
+program.command("reply").argument("<threadId>", "线程 id（jdu comments 首列；给回复 id 也行，一律挂到根）").requiredOption("-m, --message <text>", "回复正文").option("--ai", "以 agent 身份回复（authorType=ai，阅读页会标出来）", false).description("回复一条评论线程").action(async (threadId, opts) => {
+	await replyComment(await client(), threadId, opts);
+});
+program.command("resolve").argument("<threadId>").option("--undo", "重新打开", false).description("标记线程已处理（仅文档 owner）").action(async (threadId, opts) => {
+	await resolveComment(await client(), threadId, opts);
+});
+var template = program.command("template").description("文档模板（打了 template 标签的文档）");
+template.command("list").description("列出模板：我的 + 官方").option("--all", "包含已归档", false).action(async (opts) => {
+	await listTemplates(await client(), opts);
+});
+template.command("pull").argument("<docId>", "模板 id（jdu template list 首列）").description("取模板原文（stdout；--out 写文件），按骨架填完再 jdu push").option("--out <file>", "写到文件而不是 stdout").action(async (docId, opts) => {
+	await pullTemplate(await client(), docId, opts);
+});
+template.command("push").argument("<file.md>", "模板文件").description("发布 / 更新模板（= jdu push 并打上 template 标签；更新时保留原有其它标签）").option("--title <title>", "模板名，默认取首个一级标题").option("--id <docId>", "更新已有模板").option("--official", "上架为官方模板（需管理员）").action(async (file, opts) => {
+	const res = await pushTemplate(await client(), file, opts);
+	process.stdout.write(`${res.url}\n`);
+});
+program.command("mcp").description("以 MCP server（stdio）暴露 list_docs / search_docs / read_doc / list_versions / push_doc，给本机 agent 用").action(async () => {
+	await runMcp(await client());
+});
+program.command("share").argument("<docId>").description("改可见性，或管理读者池（定向分享，可撤销）").option("--visibility <v>", VISIBILITIES.join(" | ")).option("--to <reader>", "加入读者池（身份串，如邮箱 / forward-auth 的 owner），可重复", collectTag, void 0).option("--revoke <reader>", "从读者池移除，立刻失效，可重复", collectTag, void 0).option("--readers", "列出当前读者池", false).action(async (docId, opts) => {
 	const api = await client();
-	const id = encodeURIComponent(docId);
-	if (opts.visibility !== void 0 || opts.team !== void 0) {
-		const body = {};
-		if (opts.visibility !== void 0) body.visibility = opts.visibility;
-		if (opts.team !== void 0) body.teamId = opts.team;
-		const res = await api.putJson(`/api/docs/${id}/visibility`, body);
-		process.stdout.write(`可见性 ${String(res.visibility)}${res.teamId ? ` · 团队 ${String(res.teamId)}` : ""}\n`);
-	}
-	if (opts.to !== void 0) {
-		const res = await api.putJson(`/api/docs/${id}/grants`, { grantees: opts.to });
-		const list = Array.isArray(res.grantees) ? res.grantees.map(String) : [];
-		process.stdout.write(`已授权：${list.join(", ") || "(已清空)"}\n`);
+	const url = `/api/docs/${encodeURIComponent(docId)}`;
+	if (opts.readers) {
+		const res = await api.getJson(`${url}/readers`);
+		const readers = Array.isArray(res.readers) ? res.readers.map(String) : [];
+		process.stdout.write(`${readers.length > 0 ? readers.join("\n") : "(读者池为空)"}\n`);
+		return;
+	}
+	if (opts.to !== void 0 || opts.revoke !== void 0) {
+		const res = await api.putJson(`${url}/readers`, {
+			add: opts.to ?? [],
+			remove: opts.revoke ?? []
+		});
+		const readers = Array.isArray(res.readers) ? res.readers.map(String) : [];
+		process.stdout.write(`${readers.length > 0 ? readers.join("\n") : "(读者池为空)"}\n`);
+		return;
 	}
+	if (opts.visibility === void 0) throw new CliError("share 需要 --visibility / --to / --revoke / --readers 之一");
+	const res = await api.putJson(`${url}/visibility`, { visibility: opts.visibility });
+	process.stdout.write(`可见性 ${String(res.visibility)}\n`);
 });
-program.command("teams").description("列出我所属的团队").action(async () => {
-	printTable(asRows(await (await client()).getJson("/api/teams"), "teams"), [
+var tokenCmd = program.command("token").description("CLI token（首启那枚与浏览器授权签发的）");
+tokenCmd.command("list").description("列出我的 token；CURRENT 是本次请求用的那枚").action(async () => {
+	printTable(asRows(await (await client()).getJson("/api/tokens"), "tokens"), [
 		{
 			key: "id",
 			header: "ID"
 		},
 		{
-			key: "name",
-			header: "NAME"
+			key: "label",
+			header: "LABEL"
+		},
+		{
+			key: "createdAt",
+			header: "CREATED"
 		},
 		{
-			key: "members",
-			header: "MEMBERS"
+			key: "lastUsedAt",
+			header: "LAST_USED"
+		},
+		{
+			key: "current",
+			header: "CURRENT"
 		}
 	]);
 });
+tokenCmd.command("rm").argument("<id>", "jdu token list 里的 ID").description("吊销一枚 token（正在使用的那枚不能删）").action(async (id) => {
+	await (await client()).deleteJson(`/api/tokens/${encodeURIComponent(id)}`);
+	process.stdout.write(`revoked ${id}\n`);
+});
+var officialCmd = program.command("official").description("官方知识库上架");
+officialCmd.command("list").description("列出已上架的官方文档").action(async () => {
+	printTable(asRows(await (await client()).getJson("/api/official"), "docs"), [{
+		key: "id",
+		header: "ID"
+	}, {
+		key: "title",
+		header: "TITLE"
+	}]);
+});
+officialCmd.command("add").argument("<docId>").description("上架到官方知识库（需管理员；同时公开）").action(async (docId) => {
+	await (await client()).putJson(`/api/docs/${encodeURIComponent(docId)}/official`, { official: true });
+	process.stdout.write(`official ${docId}\n`);
+});
+officialCmd.command("rm").argument("<docId>").description("从官方知识库拿下（正文和下架前的可见性保留）").action(async (docId) => {
+	await (await client()).putJson(`/api/docs/${encodeURIComponent(docId)}/official`, { official: false });
+	process.stdout.write(`unofficial ${docId}\n`);
+});
 program.command("blob").description("内容寻址 blob（shared 档 runtime 等原始资产）").command("push").argument("<files...>", "要上传的文件（如 packages/widgets/dist/_runtime/*.js）").description("按内容 hash 上传为 blob，输出 /blob/<hash> 地址（已存在则跳过）").action(async (files) => {
 	const api = await client();
 	const entries = await Promise.all(files.map(async (f) => ({
@@ -4002,7 +5504,22 @@ program.command("blob").description("内容寻址 blob（shared 档 runtime 等
 		process.stdout.write(`${state}  /blob/${e.hash}  ${e.path}\n`);
 	}
 });
-var widget = program.command("widget").description("widget 注册表");
+var widget = program.command("widget").description("widget 注册表与作者工作流");
+widget.command("create").argument("<name>", "widget 名（字母开头，如 StarRating / star-rating）").description("生成一个能直接 build / dev / push 的 widget 目录（契约类型、框架基类、构建脚本全内联）").option("--template <t>", TEMPLATES.join(" | "), "vanilla").option("--runtime <r>", `react 模板：${RUNTIMES.join(" | ")}。shared = 平台版本档 runtime（产物几 KB，需能连 server）；custom = 自带 react 全内联`, "shared").option("--dir <path>", "输出目录，默认 ./<name 的 kebab-case>").action(async (name, opts) => {
+	const res = await createWidget(name, opts, client);
+	process.stdout.write(`${res.dir}\n`);
+	process.stderr.write(`已生成 ${res.files.length} 个文件（${res.template}${res.runtime ? ` · runtime ${res.runtime}` : ""}${res.tier ? ` · ${res.tier}` : ""}）\n下一步：cd ${res.dir} && npm install && npm run dev\n`);
+});
+widget.command("dev").argument("[dir]", "widget 目录（jdu widget create 生成的）或产物目录，默认当前目录", ".").description("本地预览：起 npm run watch + 预览页（sampleData 挂载、改代码自动刷新、暗色切换）").option("--port <n>", "预览端口", "5173").option("--no-watch", "不自动跑 npm run watch").action(async (dir, opts) => {
+	const port = Number.parseInt(opts.port, 10);
+	if (!Number.isInteger(port) || port <= 0) throw new CliError(`端口不合法：${opts.port}`);
+	const server = await loadRuntimeConfig().then((c) => c.server).catch(() => void 0);
+	await runWidgetDev(dir, {
+		port,
+		watch: opts.watch,
+		server
+	});
+});
 widget.command("push").argument("<dir>", "含 widget.json + index.js[ + index.css] 的构建产物目录").description("发布 widget").action(async (dir) => {
 	await pushWidget(await client(), dir);
 });