@monoedge/jdu-cli 0.4.0 → 0.5.0

package/dist/cli.js

@@ -2,11 +2,11 @@
 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, readdirSync, statSync, writeFileSync } from "node:fs";
+import fs, { chmodSync, createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import process$1 from "node:process";
 import { stripVTControlCharacters } from "node:util";
 import { createHash, randomBytes } from "node:crypto";
-import { homedir, hostname } from "node:os";
+import { homedir, hostname, tmpdir } from "node:os";
 import { createServer } from "node:http";
 import { createInterface } from "node:readline";
 import { readFile, readdir } from "node:fs/promises";
@@ -3326,6 +3326,11 @@ async function loadRuntimeConfig() {
 }
 //#endregion
 //#region src/comments.ts
+/** 附件一行：`[图片 ×N] /blob/… /blob/…`，给 agent 的是相对路径，拼上 server 地址就能取 */
+function attachmentsLine(c) {
+	const list = c.attachments ?? [];
+	return list.length === 0 ? null : `[图片 ×${list.length}] ${list.map((s) => `/blob/${s}`).join(" ")}`;
+}
 var QUOTE_MAX = 120;
 function when(ms) {
 	return new Date(ms).toISOString().slice(0, 16).replace("T", " ");
@@ -3360,7 +3365,7 @@ async function listComments(api, docId, opts) {
 	for (const root of roots) {
 		const head = [
 			root.id,
-			root.blockId ?? "-",
+			root.blockId ?? "全文",
 			root.resolved ? "resolved" : "open",
 			who(root),
 			when(root.createdAt)
@@ -3369,10 +3374,14 @@ async function listComments(api, docId, opts) {
 		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, "  "));
+		if (root.body) out.push(indent(root.body, "  "));
+		const rootPics = attachmentsLine(root);
+		if (rootPics) out.push(`  ${rootPics}`);
 		for (const reply of replies.get(root.id) ?? []) {
 			out.push(`  ↳ ${reply.id}  ${who(reply)}  ${when(reply.createdAt)}`);
-			out.push(indent(reply.body, "    "));
+			if (reply.body) out.push(indent(reply.body, "    "));
+			const pics = attachmentsLine(reply);
+			if (pics) out.push(`    ${pics}`);
 		}
 		out.push("");
 	}
@@ -3390,116 +3399,6 @@ async function resolveComment(api, threadId, opts) {
 	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}`;
-	}
-	async getJson(path) {
-		return this.json("GET", path, void 0, void 0);
-	}
-	async postJson(path, body) {
-		return this.json("POST", path, JSON.stringify(body), "application/json");
-	}
-	async putJson(path, body) {
-		return this.json("PUT", path, JSON.stringify(body), "application/json");
-	}
-	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();
-		if (text.trim() === "") return void 0;
-		try {
-			return JSON.parse(text);
-		} catch {
-			throw new CliError(`POST ${this.url(path)} 返回的不是合法 JSON：${clip(text)}`);
-		}
-	}
-	/** blob 上传走原始字节，不做任何包装 —— server 直接对 body 校验 sha256。 */
-	async putBytes(path, bytes, contentType) {
-		await this.send("PUT", path, bytes, contentType);
-	}
-	async json(method, path, body, contentType) {
-		const text = await (await this.send(method, path, body, contentType)).text();
-		if (text.trim() === "") return void 0;
-		try {
-			return JSON.parse(text);
-		} catch {
-			throw new CliError(`${method} ${this.url(path)} 返回的不是合法 JSON：${clip(text)}`);
-		}
-	}
-	async send(method, path, body, contentType) {
-		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 {
-			res = await fetch(url, {
-				method,
-				headers,
-				body,
-				redirect: "manual"
-			});
-		} catch (err) {
-			throw new CliError(`请求 ${method} ${url} 失败：${describeNetworkError(err)}`, "确认 server 已启动、地址与端口正确");
-		}
-		if (!res.ok) throw await httpError(method, url, res);
-		return res;
-	}
-};
-function clip(text) {
-	const t = text.trim();
-	return t.length > MAX_DETAIL ? `${t.slice(0, MAX_DETAIL)}…` : t;
-}
-/** fetch 失败时真正的原因藏在 cause 里（ECONNREFUSED / ENOTFOUND / 证书错误…）。 */
-function describeNetworkError(err) {
-	const cause = err?.cause;
-	if (cause instanceof Error) {
-		const code = cause.code;
-		return code ? `${code} ${cause.message}` : cause.message;
-	}
-	return err instanceof Error ? err.message : String(err);
-}
-async function httpError(method, url, res) {
-	let detail = "";
-	try {
-		detail = clip(await res.text());
-	} catch {
-		detail = "";
-	}
-	if (detail.startsWith("{")) try {
-		const obj = JSON.parse(detail);
-		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>；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 login 的浏览器授权（#66）：本机起一个 loopback 回调，打开 server 下发的 authorizeUrl，
@@ -3803,11 +3702,355 @@ function fallbackMethods(provider) {
 	if (provider === "forward-auth") return ["oidc", "token"];
 	return ["token"];
 }
+//#endregion
+//#region src/deploy.ts
+/**
+* `jdu deploy`：在用户自己的 Cloudflare 账号里起一个 jiandu，一条命令从零到能登录。
+*
+* 为什么是 CLI 而不是 Deploy 按钮：jiandu 是给 agent 用的，agent 会跑命令不会点按钮；
+* 而且这条路不要求 GitHub 账号、不在用户账号里留一个仓库与构建流水线，`JIANDU_SETUP_SECRET`
+* 由这里随机生成（用户手填的 secret 强度没法保证）。
+*
+* 我们不自己调 Cloudflare API：Worker 上传、Durable Object migration、静态资源上传会话
+* 是三套协议，wrangler 已经把它们做完了，重写一遍只会多一份要跟着 Cloudflare 演进的代码。
+* 所以这里只做三件事：把产物取下来、按正确的顺序敲 wrangler、把结果接回 jdu 的登录态。
+*
+*   jdu deploy --owner mason     首次：部署 → 生成 secret → 自动 jdu login
+*   jdu deploy                   升级：npm 取 latest 再部署一次，vars 与 secret 原样保留
+*/
+/** npm 上的部署产物包：worker.js + assets/ + wrangler.json。 */
+var PACKAGE = "@monoedge/jiandu-cf";
+/** wrangler 主版本锁死：它改 flag 我们要跟着改，不能让用户某天突然拿到 v5。 */
+var WRANGLER = "wrangler@4";
+/** 默认 runner：stdio 继承给用户看（wrangler 的 OAuth 提示、进度条都靠它）。 */
+var spawnRunner = (cmd, args, opts) => new Promise((ok, fail) => {
+	const child = spawn(cmd, args, {
+		stdio: [
+			opts.input === void 0 ? "inherit" : "pipe",
+			"inherit",
+			"inherit"
+		],
+		shell: process.platform === "win32",
+		env: {
+			...process.env,
+			...opts.env
+		}
+	});
+	if (opts.input !== void 0) child.stdin?.end(opts.input);
+	child.on("error", (err) => fail(new CliError(`跑不起来 ${cmd}：${err.message}`, "需要 node 与 npm 在 PATH 里")));
+	child.on("exit", (code) => code === 0 ? ok() : fail(new CliError(`${cmd} ${args[0] ?? ""} 失败（退出码 ${code}）`)));
+});
+/** 24 字节随机，base64url —— 它会出现在 URL 的 query 里（/setup?invite=），别带需要转义的字符。 */
+function newSecret() {
+	return randomBytes(24).toString("base64url");
+}
+/**
+* 取部署产物：`--dist` 指本地目录，否则临时装一份 npm 包。
+* 返回 wrangler 配置的绝对路径 —— wrangler 按**配置文件所在目录**解析 main 与 assets.directory，
+* 所以不需要把产物拷到工作目录，也不需要生成任何脚手架。
+*/
+async function resolveConfig(opts, run) {
+	if (opts.dist !== void 0) {
+		const config = resolve(opts.dist, "wrangler.json");
+		if (!existsSync(config)) throw new CliError(`${config} 不存在`, "--dist 要指向 server/dist-cf 那样的构建产物目录");
+		return {
+			config,
+			cleanup: () => void 0
+		};
+	}
+	const dir = mkdtempSync(join(tmpdir(), "jdu-deploy-"));
+	try {
+		await run("npm", [
+			"install",
+			"--no-audit",
+			"--no-fund",
+			"--prefix",
+			dir,
+			`${PACKAGE}@latest`
+		], {});
+	} catch (err) {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		throw err;
+	}
+	const config = join(dir, "node_modules", PACKAGE, "dist", "wrangler.json");
+	if (!existsSync(config)) {
+		rmSync(dir, {
+			recursive: true,
+			force: true
+		});
+		throw new CliError(`${PACKAGE} 里没有 dist/wrangler.json`, "包版本太老或装坏了，重试一次；仍失败请报 issue");
+	}
+	return {
+		config,
+		cleanup: () => rmSync(dir, {
+			recursive: true,
+			force: true
+		})
+	};
+}
+/** wrangler 的结构化输出：NDJSON，deploy 那条带 targets（部署好的地址）。 */
+function urlFromOutput(file) {
+	if (!existsSync(file)) return null;
+	for (const line of readFileSync(file, "utf8").split("\n")) {
+		if (line.trim() === "") continue;
+		try {
+			const entry = JSON.parse(line);
+			if (entry.type !== "deploy" || !Array.isArray(entry.targets)) continue;
+			const target = entry.targets.find((t) => typeof t === "string" && t.startsWith("http"));
+			if (target !== void 0) return target;
+		} catch {}
+	}
+	return null;
+}
+/** 部署完探一次 healthz：缺 secret 的实例冷启动就抛错，所有请求 500。 */
+async function healthy(url) {
+	try {
+		return (await fetch(`${url}/healthz`, { headers: { accept: "application/json" } })).ok;
+	} catch {
+		return false;
+	}
+}
+async function runDeploy(opts) {
+	const run = opts.run ?? spawnRunner;
+	const name = opts.name ?? "jiandu";
+	const { config, cleanup } = await resolveConfig(opts, run);
+	try {
+		if (opts.dryRun) {
+			await run("npx", [
+				"--yes",
+				WRANGLER,
+				"deploy",
+				"--dry-run",
+				"-c",
+				config,
+				"--name",
+				name
+			], {});
+			return {
+				name,
+				url: null,
+				setupSecret: null,
+				setupUrl: null,
+				loggedIn: false
+			};
+		}
+		await run("npx", [
+			"--yes",
+			WRANGLER,
+			"login"
+		], {});
+		const outDir = mkdtempSync(join(tmpdir(), "jdu-wrangler-out-"));
+		const outFile = join(outDir, "out.ndjson");
+		const args = [
+			"--yes",
+			WRANGLER,
+			"deploy",
+			"-c",
+			config,
+			"--name",
+			name,
+			"--keep-vars"
+		];
+		if (opts.owner !== void 0) args.push("--var", `JIANDU_AUTH_OWNER:${opts.owner}`);
+		await run("npx", args, { env: { WRANGLER_OUTPUT_FILE_PATH: outFile } });
+		const url = urlFromOutput(outFile);
+		rmSync(outDir, {
+			recursive: true,
+			force: true
+		});
+		if (url === null) throw new CliError("部署命令跑完了，但没能从 wrangler 的输出里读到地址", "去 Cloudflare 控制台看这个 Worker 的地址，再手动 npx wrangler secret put JIANDU_SETUP_SECRET");
+		const setupSecret = await healthy(url) ? null : newSecret();
+		if (setupSecret !== null) {
+			await run("npx", [
+				"--yes",
+				WRANGLER,
+				"secret",
+				"put",
+				"JIANDU_SETUP_SECRET",
+				"-c",
+				config,
+				"--name",
+				name
+			], { input: setupSecret });
+			if (!await healthy(url)) throw new CliError(`${url} 起不来（secret 已设）`, `跑 npx ${WRANGLER} tail --name ${name} 看冷启动日志；常见原因是 JIANDU_AUTH_OWNER 没设或 provider 填了不支持的值`);
+		}
+		let loggedIn = false;
+		if (setupSecret !== null) {
+			await runLogin({
+				server: url,
+				token: setupSecret,
+				browser: false
+			});
+			loggedIn = true;
+		}
+		return {
+			name,
+			url,
+			setupSecret,
+			setupUrl: setupSecret === null ? null : `${url}/setup?invite=${setupSecret}`,
+			loggedIn
+		};
+	} finally {
+		cleanup();
+	}
+}
+//#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}`;
+	}
+	async getJson(path) {
+		return this.json("GET", path, void 0, void 0);
+	}
+	async postJson(path, body) {
+		return this.json("POST", path, JSON.stringify(body), "application/json");
+	}
+	async putJson(path, body) {
+		return this.json("PUT", path, JSON.stringify(body), "application/json");
+	}
+	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();
+		if (text.trim() === "") return void 0;
+		try {
+			return JSON.parse(text);
+		} catch {
+			throw new CliError(`POST ${this.url(path)} 返回的不是合法 JSON：${clip(text)}`);
+		}
+	}
+	/** blob 上传走原始字节，不做任何包装 —— server 直接对 body 校验 sha256。 */
+	async putBytes(path, bytes, contentType) {
+		await this.send("PUT", path, bytes, contentType);
+	}
+	async json(method, path, body, contentType) {
+		const text = await (await this.send(method, path, body, contentType)).text();
+		if (text.trim() === "") return void 0;
+		try {
+			return JSON.parse(text);
+		} catch {
+			throw new CliError(`${method} ${this.url(path)} 返回的不是合法 JSON：${clip(text)}`);
+		}
+	}
+	async send(method, path, body, contentType) {
+		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 {
+			res = await fetch(url, {
+				method,
+				headers,
+				body,
+				redirect: "manual"
+			});
+		} catch (err) {
+			throw new CliError(`请求 ${method} ${url} 失败：${describeNetworkError(err)}`, "确认 server 已启动、地址与端口正确");
+		}
+		if (!res.ok) throw await httpError(method, url, res);
+		return res;
+	}
+};
+function clip(text) {
+	const t = text.trim();
+	return t.length > MAX_DETAIL ? `${t.slice(0, MAX_DETAIL)}…` : t;
+}
+/** fetch 失败时真正的原因藏在 cause 里（ECONNREFUSED / ENOTFOUND / 证书错误…）。 */
+function describeNetworkError(err) {
+	const cause = err?.cause;
+	if (cause instanceof Error) {
+		const code = cause.code;
+		return code ? `${code} ${cause.message}` : cause.message;
+	}
+	return err instanceof Error ? err.message : String(err);
+}
+async function httpError(method, url, res) {
+	let detail = "";
+	try {
+		detail = clip(await res.text());
+	} catch {
+		detail = "";
+	}
+	if (detail.startsWith("{")) try {
+		const obj = JSON.parse(detail);
+		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>；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);
+}
 /** 只取链接/图片的目标部分，标签内容可以任意嵌套，不参与匹配。 */
 var MD_DEST_RE = /\]\(([^)]*)\)/g;
 var HTML_ATTR_RE = /\b(?:src|href)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'`=<>]+))/gi;
-/** 抽出一份文本里所有可能的引用目标（未过滤外链，原样返回）。 */
-function extractRefs(text) {
+/** 与 server 的 scanFences 同一条规则（rewrite.ts）：缩进 ≤3、3 个以上反引号或波浪号。 */
+var FENCE_RE = /^([ \t]{0,3})(`{3,}|~{3,})(.*)$/;
+/**
+* 去掉 fenced code block 再找引用：代码块里的 `](./a.png)` 是给人看的例子，不是引用。
+*
+* 这条规则必须与 server 对齐 —— `rewriteReferences` 就是按 `scanFences` 跳过同样的区间。
+* 不一致的后果是双向的：CLI 多收就会上传一堆永远不会被改写的文件，还对着代码里的
+* `steps[i](tx)` 这种写法报「跳过不存在的本地引用」；CLI 少收则会漏传真引用。
+*
+* 明知是重复实现：CLI 是零依赖的单文件发布物，为十几行扫描规则给它加一个 workspace 依赖不值。
+* 规则本身是 CommonMark 定死的，不会漂。
+*/
+function stripFences(text) {
+	const out = [];
+	let open = null;
+	for (const line of text.split("\n")) {
+		const m = FENCE_RE.exec(line);
+		const marker = m?.[2];
+		if (marker !== void 0) {
+			const char = marker[0];
+			const rest = m?.[3] ?? "";
+			if (open === null) {
+				if (!(char === "`" && rest.includes("`"))) {
+					open = {
+						char,
+						len: marker.length
+					};
+					continue;
+				}
+			} else if (char === open.char && marker.length >= open.len && rest.trim() === "") {
+				open = null;
+				continue;
+			}
+		}
+		if (open === null) out.push(line);
+	}
+	return out.join("\n");
+}
+/** 抽出一份文本里所有可能的引用目标（未过滤外链，原样返回）。代码块内的写法不算。 */
+function extractRefs(raw) {
+	const text = stripFences(raw);
 	const out = [];
 	for (const m of text.matchAll(MD_DEST_RE)) {
 		const dest = destinationOf(m[1] ?? "");
@@ -3922,15 +4165,30 @@ function collectReferences(entryPath, maxDepth = 10) {
 //#region src/push.ts
 /** 可见性三档。link 档已废除：定向分享走读者池（jdu share --to）。 */
 var VISIBILITIES = ["private", "public"];
+function asLint(v) {
+	if (v === null || typeof v !== "object") return null;
+	const r = v;
+	if (typeof r["code"] !== "string" || typeof r["message"] !== "string") return null;
+	return {
+		code: r["code"],
+		lang: typeof r["lang"] === "string" ? r["lang"] : "",
+		...typeof r["line"] === "number" ? { line: r["line"] } : {},
+		...typeof r["blockId"] === "string" ? { blockId: r["blockId"] } : {},
+		message: r["message"]
+	};
+}
 function log(line) {
 	process.stderr.write(`${line}\n`);
 }
-/** 没给 --title 时用首个一级标题，再退化到文件名。 */
+/** 没给 --title 时用首个一级标题，其次 frontmatter 的 title / name（SKILL.md 形态，#122），再退化到文件名。 */
 function inferTitle(entryPath) {
 	try {
 		const text = readFileSync(entryPath, "utf8");
 		const m = /^[ \t]{0,3}#[ \t]+(.+?)[ \t]*#*[ \t]*$/m.exec(text);
 		if (m?.[1]) return m[1].trim();
+		const fm = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text)?.[1];
+		const t = fm ? /^(?:title|name)[ \t]*:[ \t]*(.+?)[ \t]*$/m.exec(fm)?.[1] : void 0;
+		if (t) return /^(["']).*\1$/.test(t) ? t.slice(1, -1) : t;
 	} catch {}
 	return basename(entryPath, extname(entryPath));
 }
@@ -3977,13 +4235,19 @@ async function pushDoc(api, entryArg, opts) {
 	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}`);
+	const lint = Array.isArray(res?.lint) ? res.lint.map(asLint).filter((l) => l !== null) : [];
+	for (const l of lint) {
+		const where = l.line !== void 0 ? ` 第 ${l.line} 行` : l.blockId ? ` ${l.blockId}` : "";
+		log(`lint: ${l.code} ${l.lang}${where} — ${l.message}`);
+	}
 	if (typeof res?.seq === "number") log(`已发布 ${id ?? ""} v${res.seq}`);
 	if (url === void 0) throw new CliError("server 未返回文档 id 或 url，无法给出访问地址");
 	return {
 		id,
 		seq: typeof res?.seq === "number" ? res.seq : void 0,
 		url,
-		warnings
+		warnings,
+		lint
 	};
 }
 //#endregion
@@ -4023,6 +4287,73 @@ function printTable(rows, columns) {
 * 模板原样发出去，怎么填是 agent 的事。agent 侧走 MCP 的 list_templates → read_doc → 按骨架写 → push_doc。
 */
 var TEMPLATE_TAG = "template";
+/**
+* 模板元数据（#115）：写在模板里的一个 HTML 注释，渲染不可见，agent 侧拿它当 MCP prompt 的 name / description：
+*
+*   <!-- jiandu-template
+*   name: weekly
+*   description: 每周五给团队同步进展。触发：周报、weekly
+*   -->
+*
+* 没有这段也能用：name 退回文档 id，description 退回摘要。
+* 文首 YAML frontmatter 里的同名字段也认（k7 起内核不渲染 frontmatter，SKILL.md 可以原样发；#122），注释优先。
+*
+* `arguments:` 声明 prompt 参数（#121）：`week（本周编号，如 2026-W36）; owner?（负责人）`——分号分隔，`?` 表示可选，
+* 括号里是说明。prompts/get 时 `jdu mcp` 把正文里的 `{{week}}` 换成客户端给的值；server 仍不做任何替换。
+*/
+var META_RE = /<!--\s*jiandu-template\s*\r?\n([\s\S]*?)-->[ \t]*\r?\n?/;
+/** 与 render 的 splitFrontmatter 同一条正则；cli 不为这一处引整个渲染包 */
+var FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/** prompt name 会拼进 `/mcp__jiandu__<name>` 这类客户端命令，只放行安全字符 */
+var NAME_RE$1 = /^[A-Za-z0-9_-]{1,64}$/;
+var ARG_RE = /^([A-Za-z0-9_-]{1,64})(\?)?\s*(?:[（(](.*)[）)])?$/;
+function parseArgs(raw) {
+	return raw.split(/[;；]/).map((s) => s.trim()).filter(Boolean).flatMap((item) => {
+		const m = ARG_RE.exec(item);
+		if (!m?.[1]) return [];
+		const desc = m[3]?.trim();
+		return [{
+			name: m[1],
+			required: m[2] === void 0,
+			...desc ? { description: desc } : {}
+		}];
+	});
+}
+/** 一段 `key: value` 行（注释正文或 frontmatter）→ 填进 meta；先到先得，所以调用顺序就是优先级。 */
+function readFields(block, out) {
+	for (const line of block.split("\n")) {
+		const kv = /^\s*([a-z]+)\s*:\s*(.*?)\s*$/.exec(line);
+		if (!kv?.[2]) continue;
+		const v = /^(["']).*\1$/.test(kv[2]) ? kv[2].slice(1, -1) : kv[2];
+		if (kv[1] === "name" && out.name === void 0 && NAME_RE$1.test(v)) out.name = v;
+		else if (kv[1] === "description" && out.description === void 0) out.description = v;
+		else if (kv[1] === "arguments" && out.arguments.length === 0) out.arguments = parseArgs(v);
+	}
+}
+function parseTemplateMeta(md) {
+	const out = {
+		arguments: [],
+		body: md
+	};
+	const fm = FRONTMATTER_RE.exec(md);
+	if (fm) out.body = md.slice(fm[0].length);
+	const m = META_RE.exec(out.body);
+	if (m) {
+		out.body = out.body.replace(m[0], "");
+		readFields(m[1] ?? "", out);
+	}
+	if (fm) readFields(fm[1] ?? "", out);
+	return out;
+}
+/** `{{name}}` → 值；没给的可选参数替换成空串。只替换声明过的参数，别的 `{{…}}` 原样留着。 */
+function fillTemplate(body, args, values) {
+	let out = body;
+	for (const a of args) {
+		const v = typeof values[a.name] === "string" ? values[a.name] : "";
+		out = out.replace(new RegExp(`\\{\\{\\s*${a.name}\\s*\\}\\}`, "g"), v);
+	}
+	return out;
+}
 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")]);
@@ -4048,6 +4379,10 @@ async function listTemplates(api, opts) {
 			key: "title",
 			header: "TITLE"
 		},
+		{
+			key: "uses",
+			header: "USES"
+		},
 		{
 			key: "updatedAt",
 			header: "UPDATED"
@@ -4069,6 +4404,7 @@ async function pullTemplate(api, id, opts) {
 * （push 的 tags 字段是整体覆盖语义，不先取回就会把别的标签抹掉）。
 */
 async function pushTemplate(api, file, opts) {
+	if (!parseTemplateMeta(readFileSync(file, "utf8")).name) process.stderr.write("warn: 模板没有 <!-- jiandu-template name/description --> 元数据注释（或 frontmatter）：agent 侧的 prompt 名会退回文档 id、描述退回摘要\n");
 	let tags = [TEMPLATE_TAG];
 	if (opts.id) {
 		const cur = await api.getJson(`/api/docs/${encodeURIComponent(opts.id)}/tags`).catch(() => ({}));
@@ -4089,8 +4425,12 @@ async function pushTemplate(api, file, opts) {
 * 当可读可写的知识库用（#9 A 段）。凭据复用 ~/.config/jiandu/config.json，server 端零改动。
 *
 * ponytail: 不引 @modelcontextprotocol/sdk——它带 express / hono / zod 一整套，而这里只需要
-* initialize / tools/list / tools/call 三个方法的 JSON-RPC 换行分帧。协议有变再换官方 SDK。
+* initialize / tools/* / prompts/* 几个方法的 JSON-RPC 换行分帧。协议有变再换官方 SDK。
 * stdout 是协议信道：本文件之外任何写 stdout 的代码都不能在 mcp 模式下被调到（pushDoc 已改为返回值）。
+*
+* 模板即 prompt（#115）：打了 template 标签的文档同时暴露为 MCP prompts（Claude Code 里是 /mcp__jiandu__<name>），
+* name / description 来自模板里的 `<!-- jiandu-template -->` 注释。语法三层（#116）：常驻 instructions 放最容易错的几条，
+* get_syntax 按需拿这台实例的完整规则（带 widget= 就是某个组件的完整 schema），push_doc 响应的 lint[] 事后指出会降级的 fence。
 */
 var SUPPORTED_PROTOCOLS = [
 	"2025-06-18",
@@ -4099,13 +4439,41 @@ var SUPPORTED_PROTOCOLS = [
 ];
 var SERVER_INFO = {
 	name: "jiandu",
-	version: "0.2.0"
+	version: "0.6.0"
 };
-var INSTRUCTIONS = "jiandu（简牍）是一个 Markdown 知识库。先用 search_docs / list_docs 找到文档 id，read_doc 拿 markdown 原文；改稿后用 push_doc 发布新版本（带 id 才是更新，不带是新建）。文档里的 widget fence（```widget:Name）保留原样。写新文档前先 list_templates 看有没有对应骨架（周报 / 技术方案…），有就 read_doc 取模板按节填，占位注释自己替换掉。";
+/**
+* 常驻开场白（#116 L0）：只放**跨工具**的知识——各个工具自己做什么由它们的 description 讲，
+* 在这里复述一遍等于每轮对话都多付一份 token。留下的是顺序、写作规范，和 fence 那几条最容易错的。
+*/
+var INSTRUCTIONS = "jiandu（简牍）是一个 Markdown 知识库，这些工具都是它 HTTP API 的薄封装。典型顺序：list_docs 找到 id → read_doc 拿原文 → 改稿 → push_doc 发新版本；写新文档前先 list_templates 看有没有现成骨架。写法：标准 markdown + GFM；一级标题就是文档标题，第一段会截成摘要。可交互组件写 ```widget:Name fence、正文是一个 JSON 对象入参：Name 区分大小写、必须是这台实例已注册的，写错不报错、只会静默变成普通代码块；JSON 字符串里的 markdown 要转义（换行 \\n、引号 \\\"）。mermaid / diff / vega-lite 直接写 ```mermaid 这类 fence，正文是 DSL 不是 JSON。用扩展语法前先 get_syntax；push_doc 响应的 lint[] 非空就是有 fence 会降级，按提示改稿重推。已有的 widget fence 保留原样。";
+/** prompts/get 给模型的开场：模板正文前的一段固定说明，不在模板里另起一套「指令字段」。 */
+function promptText(t) {
+	return `下面是文档模板「${t.title}」的骨架。按节填写，删掉所有 <!-- --> 占位注释，第一段写一句话摘要；写完用 push_doc 发布（默认 private，进团队传 team），并把链接给用户。模板里的说明文字不要带进正文。
+
+---
+
+` + t.body;
+}
 function str(v, name) {
 	if (typeof v !== "string" || v.trim() === "") throw new CliError(`${name} 必填且为非空字符串`);
 	return v.trim();
 }
+var SCOPES$1 = [
+	"mine",
+	"official",
+	"shared",
+	"all"
+];
+function asScope(v) {
+	if (typeof v === "string" && SCOPES$1.includes(v)) return v;
+	throw new CliError(`scope 只能是 ${SCOPES$1.join(" / ")}：${String(v)}`);
+}
+function strList(v) {
+	return Array.isArray(v) ? v.map(String).filter((s) => s.trim() !== "") : [];
+}
+function isRecord(v) {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
 function asDoc(raw, scope, server) {
 	if (raw === null || typeof raw !== "object") return null;
 	const d = raw;
@@ -4117,8 +4485,10 @@ function asDoc(raw, scope, server) {
 		visibility: typeof d["visibility"] === "string" ? d["visibility"] : scope === "official" ? "official" : "",
 		tags: Array.isArray(d["tags"]) ? d["tags"].map(String) : [],
 		scope,
+		...typeof d["team"] === "string" || d["team"] === null ? { team: d["team"] } : {},
 		...typeof d["archived"] === "boolean" ? { archived: d["archived"] } : {},
 		...typeof d["updatedAt"] === "number" ? { updatedAt: d["updatedAt"] } : {},
+		...typeof d["uses"] === "number" ? { uses: d["uses"] } : {},
 		url: typeof d["url"] === "string" ? d["url"] : `${server}/d/${d["id"]}`
 	};
 }
@@ -4137,152 +4507,345 @@ function buildTools(api) {
 		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 生效：包含已归档"
+	const loadTemplates = async () => {
+		const [mine, shared, official] = await Promise.all([
+			listOf("mine", false),
+			listOf("shared", false),
+			listOf("official", false)
+		]);
+		const seen = /* @__PURE__ */ new Set();
+		const docs = [
+			...mine,
+			...shared,
+			...official
+		].filter((d) => d.tags.includes("template") && !seen.has(d.id) && seen.add(d.id));
+		const infos = await Promise.all(docs.map(async (d) => {
+			const meta = parseTemplateMeta(await api.getText(`/d/${encodeURIComponent(d.id)}.md`));
+			return {
+				...d,
+				name: meta.name ?? d.id,
+				description: meta.description ?? (d.excerpt || d.title),
+				arguments: meta.arguments,
+				body: meta.body
+			};
+		}));
+		const names = /* @__PURE__ */ new Set();
+		return infos.filter((t) => !names.has(t.name) && names.add(t.name));
+	};
+	return {
+		tools: [
+			{
+				name: "list_docs",
+				description: "列 / 搜文档，返回 id、标题、摘要、可见性、标签、URL。给 query 就按关键词过滤（标题 / 摘要 / 标签，空格分词、全部命中），不给就是纯列表。scope：mine（我发布的）/ official（官方知识库）/ shared（分享给我的 + 我所属团队的）/ all；不传时——搜（有 query）默认 all、列（无 query）默认 mine。没有全文检索，正文搜不到——要读正文用 read_doc。",
+				inputSchema: {
+					type: "object",
+					properties: {
+						query: {
+							type: "string",
+							description: "关键词，空格分词、全部命中；不给就是纯列表"
+						},
+						scope: {
+							type: "string",
+							enum: [...SCOPES$1]
+						},
+						limit: {
+							type: "integer",
+							minimum: 1,
+							maximum: 200,
+							description: "最多几条；不给时搜默认 20 条、纯列表不截断"
+						},
+						includeArchived: {
+							type: "boolean",
+							default: false,
+							description: "仅 mine 生效：包含已归档"
+						}
+					}
+				},
+				run: async (args) => {
+					const terms = (typeof args["query"] === "string" ? args["query"].trim() : "").toLowerCase().split(/\s+/).filter(Boolean);
+					const scope = args["scope"] === void 0 ? terms.length === 0 ? "mine" : "all" : asScope(args["scope"]);
+					const includeArchived = args["includeArchived"] === true;
+					const docs = scope === "all" ? await listAll(includeArchived) : await listOf(scope, includeArchived);
+					if (terms.length === 0) {
+						const cap = Number.isInteger(args["limit"]) ? Math.max(1, Math.min(200, args["limit"])) : docs.length;
+						return JSON.stringify(docs.slice(0, cap), null, 2);
 					}
+					const hits = docs.filter((d) => {
+						const hay = `${d.title}\n${d.excerpt}\n${d.tags.join(" ")}`.toLowerCase();
+						return terms.every((t) => hay.includes(t));
+					});
+					const limit = Number.isInteger(args["limit"]) ? Math.max(1, Math.min(200, args["limit"])) : 20;
+					return JSON.stringify(hits.slice(0, limit), null, 2);
 				}
 			},
-			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
+			{
+				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`);
 				}
 			},
-			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"
+			{
+				name: "list_templates",
+				description: "列出文档模板（打了 template 标签的文档：我的 + 我所属团队的 + 官方）。每条带 name（同时是 MCP prompt 名）和 description（什么场景用）。写新文档前先看这里；选中后 read_doc 取原文，按骨架填内容、删掉 <!-- --> 占位注释，再 push_doc。server 不做任何变量替换。",
+				inputSchema: {
+					type: "object",
+					properties: {}
+				},
+				run: async () => {
+					const out = (await loadTemplates()).map(({ body: _body, ...rest }) => rest);
+					return JSON.stringify(out, null, 2);
+				}
+			},
+			{
+				name: "get_syntax",
+				description: "取这台实例的写作语法（markdown）：内核语法、widget fence 与多态 CodeBlock（mermaid / diff / vega-lite…）的规则、已注册 widget 的清单与字段摘要。写含 fence / 组件 / 图表的文档前先调一次（不带参数）。要某几个组件的完整入参就带 widget=名字（多个用逗号分隔），拿到 dataSchema（JSON Schema）、sampleData 和可直接粘进文档的 fence 示例；标了 contentMediaType: text/markdown 的字符串字段可以写 markdown。",
+				inputSchema: {
+					type: "object",
+					properties: { widget: {
+						type: "string",
+						description: "组件名，区分大小写；多个用逗号分隔。不给就返回整份语法说明"
+					} }
+				},
+				run: async (args) => {
+					const want = typeof args["widget"] === "string" ? args["widget"].split(",").map((s) => s.trim()).filter(Boolean) : [];
+					if (want.length === 0) return api.getText("/api/syntax");
+					const res = await api.getJson("/api/widgets");
+					const out = [];
+					const active = [];
+					for (const raw of Array.isArray(res?.widgets) ? res.widgets : []) {
+						if (raw === null || typeof raw !== "object") continue;
+						const w = raw;
+						if (w["status"] !== "active" || typeof w["name"] !== "string") continue;
+						active.push(w["name"]);
+						if (!want.includes(w["name"])) continue;
+						out.push({
+							name: w["name"],
+							scope: typeof w["scope"] === "string" ? w["scope"] : "",
+							version: typeof w["version"] === "string" ? w["version"] : "",
+							description: typeof w["description"] === "string" ? w["description"] : null,
+							dataSchema: w["dataSchema"] ?? null,
+							sampleData: w["sampleData"] ?? null,
+							fence: `\`\`\`widget:${w["name"]}\n${JSON.stringify(w["sampleData"] ?? {}, null, 2)}\n\`\`\``
+						});
 					}
+					const missing = want.filter((n) => !out.some((w) => w.name === n));
+					if (missing.length > 0) throw new CliError(`这台实例没有注册：${missing.join(" / ")}。可用的是：${active.join(" / ")}`);
+					return JSON.stringify(out, null, 2);
 				}
 			},
-			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: {}
+			{
+				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);
+				}
 			},
-			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" } }
+			{
+				name: "push_doc",
+				description: "发布 markdown。正文二选一：path（本机入口 .md 的绝对路径，会递归收集图片 / 嵌套 md 等本地引用一起上传）或 content（markdown 字串，没有本地引用可收，标题取一级标题、否则传 title）。带 id 是给已有文档发新版本（标题 / 可见性 / 标签 / 团队不传则保持原值）；不带 id 新建，默认 private。响应里的 lint[] 列出会静默降级成普通代码块的 fence（unknown-widget / invalid-json / invalid-data，带行号或 blockId）——发布已成功，但非空就该按提示改稿再 push_doc 一次。",
+				inputSchema: {
+					type: "object",
+					properties: {
+						path: {
+							type: "string",
+							description: "入口 .md 的绝对路径；与 content 二选一"
+						},
+						content: {
+							type: "string",
+							description: "markdown 正文；与 path 二选一"
+						},
+						id: {
+							type: "string",
+							description: "要更新的文档 id"
+						},
+						title: { type: "string" },
+						visibility: {
+							type: "string",
+							enum: [...VISIBILITIES]
+						},
+						tags: {
+							type: "array",
+							items: { type: "string" },
+							description: "整体覆盖标签；不传则不动"
+						},
+						team: {
+							type: "string",
+							description: "进团队的团队 id（需是成员）；空串移出团队；不传则不动"
+						}
+					}
+				},
+				run: async (args) => {
+					const content = typeof args["content"] === "string" ? args["content"] : void 0;
+					const hasPath = typeof args["path"] === "string" && args["path"].trim() !== "";
+					if (content === void 0 === !hasPath) throw new CliError("path 与 content 必须且只能传一个");
+					const tmp = content !== void 0 ? mkdtempSync(join(tmpdir(), "jdu-mcp-")) : null;
+					const path = tmp ? join(tmp, "doc.md") : str(args["path"], "path");
+					if (tmp && content !== void 0) writeFileSync(path, content, "utf8");
+					const tags = Array.isArray(args["tags"]) ? args["tags"].map(String) : void 0;
+					try {
+						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,
+							team: typeof args["team"] === "string" ? args["team"] : void 0
+						});
+						return JSON.stringify(res, null, 2);
+					} finally {
+						if (tmp) rmSync(tmp, {
+							recursive: true,
+							force: true
+						});
+					}
+				}
 			},
-			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: "整体覆盖标签；不传则不动"
+			{
+				name: "share_doc",
+				description: "改文档的访问范围，不用重推正文：visibility（private / public）、team（团队 id；空串移出团队）、addReaders / removeReaders（定向读者的身份串，如邮箱 / 用户名）。私有文档谁能读 = 作者 ∪ 指定读者 ∪ 所选团队成员。",
+				inputSchema: {
+					type: "object",
+					required: ["id"],
+					properties: {
+						id: { type: "string" },
+						visibility: {
+							type: "string",
+							enum: [...VISIBILITIES]
+						},
+						team: {
+							type: "string",
+							description: "团队 id；空串移出团队"
+						},
+						addReaders: {
+							type: "array",
+							items: { type: "string" }
+						},
+						removeReaders: {
+							type: "array",
+							items: { type: "string" }
+						}
 					}
+				},
+				run: async (args) => {
+					const id = encodeURIComponent(str(args["id"], "id"));
+					const access = {};
+					if (typeof args["visibility"] === "string") access["visibility"] = args["visibility"];
+					if (typeof args["team"] === "string") access["team"] = args["team"];
+					const add = strList(args["addReaders"]);
+					const remove = strList(args["removeReaders"]);
+					if (Object.keys(access).length === 0 && add.length === 0 && remove.length === 0) throw new CliError("share_doc 需要 visibility / team / addReaders / removeReaders 之一");
+					const out = { id: args["id"] };
+					if (Object.keys(access).length > 0) Object.assign(out, await api.putJson(`/api/docs/${id}/visibility`, access));
+					if (add.length > 0 || remove.length > 0) Object.assign(out, await api.putJson(`/api/docs/${id}/readers`, {
+						add,
+						remove
+					}));
+					return JSON.stringify(out, null, 2);
 				}
 			},
-			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);
+			{
+				name: "list_comments",
+				description: "列出文档的评论线程（读者在阅读页划词 / 块把手 / 文末评论区留下的）。默认只列未处理的；每条带 blockId（对应正文哪一块，null = 评论整篇文档）、selection.quote 引文、正文、attachments（图片附件的 sha256，取图 GET /blob/<sha256>）、作者、replies。处理流程：按 blockId 找到段落改稿 → push_doc 新版本 → reply_comment 回一句并 resolved=true 关掉。",
+				inputSchema: {
+					type: "object",
+					required: ["id"],
+					properties: {
+						id: { type: "string" },
+						includeResolved: {
+							type: "boolean",
+							default: false
+						}
+					}
+				},
+				run: async (args) => {
+					const id = encodeURIComponent(str(args["id"], "id"));
+					const res = await api.getJson(`/api/docs/${id}/comments`);
+					const all = (Array.isArray(res?.comments) ? res.comments : []).filter(isRecord);
+					const includeResolved = args["includeResolved"] === true;
+					const threads = all.filter((c) => c["parentId"] === null && (includeResolved || c["resolved"] !== true)).map((root) => ({
+						...root,
+						replies: all.filter((c) => c["parentId"] === root["id"])
+					}));
+					return JSON.stringify(threads, null, 2);
+				}
+			},
+			{
+				name: "reply_comment",
+				description: "回复评论线程并/或改它的处理状态。body 回一句（以 agent 身份发出，authorType=ai，读者页里会标出来）；resolved=true 标记已处理、false 重新打开（仅文档 owner）。改完稿发了新版本后，通常一次调用把两件事一起做掉。",
+				inputSchema: {
+					type: "object",
+					required: ["threadId"],
+					properties: {
+						threadId: { type: "string" },
+						body: {
+							type: "string",
+							description: "回复正文；只想改状态就不传"
+						},
+						resolved: {
+							type: "boolean",
+							description: "true 关掉线程、false 重新打开；不传就只回复不改状态"
+						}
+					}
+				},
+				run: async (args) => {
+					const tid = encodeURIComponent(str(args["threadId"], "threadId"));
+					const body = typeof args["body"] === "string" && args["body"].trim() !== "" ? args["body"].trim() : null;
+					const resolved = typeof args["resolved"] === "boolean" ? args["resolved"] : null;
+					if (body === null && resolved === null) throw new CliError("reply_comment 需要 body（回复）或 resolved（改状态）之一");
+					const out = { threadId: args["threadId"] };
+					if (body !== null) out["reply"] = await api.postJson(`/api/comments/${tid}/reply`, {
+						body,
+						authorType: "ai"
+					});
+					if (resolved !== null) out["resolve"] = await api.postJson(`/api/comments/${tid}/resolve`, { resolved });
+					return JSON.stringify(out, null, 2);
+				}
+			},
+			{
+				name: "archive_doc",
+				description: "归档文档：从列表撤下、读者打开 404（owner 自己仍可读），版本与评论都保留；undo=true 取消归档。这就是「撤回发布」——没有比它更重的删除给 agent 用。",
+				inputSchema: {
+					type: "object",
+					required: ["id"],
+					properties: {
+						id: { type: "string" },
+						undo: {
+							type: "boolean",
+							default: false,
+							description: "取消归档"
+						}
+					}
+				},
+				run: async (args) => {
+					const id = encodeURIComponent(str(args["id"], "id"));
+					const res = await api.postJson(`/api/docs/${id}/archive`, { archived: args["undo"] !== true });
+					return JSON.stringify(res, null, 2);
+				}
 			}
-		}
-	];
+		],
+		loadTemplates
+	};
 }
 function write(msg) {
 	process.stdout.write(`${JSON.stringify(msg)}\n`);
@@ -4298,7 +4861,7 @@ function rpcError(id, code, message) {
 	});
 }
 async function runMcp(api) {
-	const tools = buildTools(api);
+	const { tools, loadTemplates } = buildTools(api);
 	const byName = new Map(tools.map((t) => [t.name, t]));
 	const handle = async (req) => {
 		const { id, method } = req;
@@ -4311,18 +4874,81 @@ async function runMcp(api) {
 		switch (method) {
 			case "initialize": {
 				const asked = typeof params["protocolVersion"] === "string" ? params["protocolVersion"] : "";
+				const protocolVersion = SUPPORTED_PROTOCOLS.includes(asked) ? asked : SUPPORTED_PROTOCOLS[0];
+				let instructions = INSTRUCTIONS;
+				try {
+					const templates = await loadTemplates();
+					if (templates.length > 0) instructions += `可用模板（同名 prompt 可直接用）：${templates.map((t) => `${t.name}——${t.description}`).join("；")}。`;
+				} catch {}
 				write({
 					jsonrpc: "2.0",
 					id,
 					result: {
-						protocolVersion: SUPPORTED_PROTOCOLS.includes(asked) ? asked : SUPPORTED_PROTOCOLS[0],
-						capabilities: { tools: {} },
+						protocolVersion,
+						capabilities: {
+							tools: {},
+							prompts: {}
+						},
 						serverInfo: SERVER_INFO,
-						instructions: INSTRUCTIONS
+						instructions
 					}
 				});
 				return;
 			}
+			case "prompts/list":
+				try {
+					write({
+						jsonrpc: "2.0",
+						id,
+						result: { prompts: (await loadTemplates()).map((t) => ({
+							name: t.name,
+							title: t.title,
+							description: t.description,
+							...t.arguments.length > 0 ? { arguments: t.arguments } : {}
+						})) }
+					});
+				} catch (err) {
+					rpcError(id, -32603, `模板列表取不到：${err instanceof CliError ? err.message : String(err)}`);
+				}
+				return;
+			case "prompts/get": {
+				const name = typeof params["name"] === "string" ? params["name"] : "";
+				try {
+					const t = (await loadTemplates()).find((x) => x.name === name);
+					if (!t) {
+						rpcError(id, -32602, `未知 prompt：${name}`);
+						return;
+					}
+					const given = isRecord(params["arguments"]) ? params["arguments"] : {};
+					const missing = t.arguments.filter((a) => a.required && (typeof given[a.name] !== "string" || given[a.name] === ""));
+					if (missing.length > 0) {
+						rpcError(id, -32602, `缺少必填参数：${missing.map((a) => a.name).join(", ")}`);
+						return;
+					}
+					api.postJson(`/api/docs/${encodeURIComponent(t.id)}/used`, {}).catch(() => void 0);
+					const body = t.arguments.length > 0 ? fillTemplate(t.body, t.arguments, given) : t.body;
+					write({
+						jsonrpc: "2.0",
+						id,
+						result: {
+							description: t.description,
+							messages: [{
+								role: "user",
+								content: {
+									type: "text",
+									text: promptText({
+										...t,
+										body
+									})
+								}
+							}]
+						}
+					});
+				} catch (err) {
+					rpcError(id, -32603, `模板取不到：${err instanceof CliError ? err.message : String(err)}`);
+				}
+				return;
+			}
 			case "ping":
 				write({
 					jsonrpc: "2.0",
@@ -4427,6 +5053,7 @@ async function readWidgetJson(dir) {
 		name,
 		scope,
 		version,
+		...typeof obj.description === "string" && obj.description.trim() !== "" ? { description: obj.description.trim() } : {},
 		dataSchema: obj.dataSchema ?? null,
 		sampleData: obj.sampleData ?? null
 	};
@@ -4521,6 +5148,9 @@ async function pushWidget(api, dirArg) {
 	process.stdout.write(`${meta.scope}/${meta.name}@${meta.version}${src}${where}\n`);
 }
 //#endregion
+//#region ../docs/design-system/tokens.css?raw
+var tokens_default = "/* ============================================================\n   简牍 Jiandu · Design Tokens  (v3 · 2026-09)\n   这是设计系统唯一的取值来源。规则、对比度依据、组件规格见同目录 README.md。\n\n   - 双主题 = 同一套语义 token 换值；结构、间距、字号、圆角逐像素一致。\n   - 主题真源是 <html class=\"dark\">（跨宿主契约：widget、dsh 都读它）；\n     暗色块同时匹配 [data-t=\"dark\"]，供设计画布与局部反色容器使用。\n     组件代码里不要写 .dark / [data-t] / prefers-color-scheme 分支，只走 token。\n   - accent 家族用 oklch 定义（同 L 同 C 只变 hue），注释里是 oklch，值是出码 hex。\n   - 每个文字色都在它实际会落到的最深一档表面（--s-4）上过 WCAG AA 4.5:1。\n     改任何一个值之前先重跑对比度（见 README「校验」）。\n   ============================================================ */\n\n/* ---------- 与主题无关的量纲 ---------- */\n:root {\n  --f-sans: \"Instrument Sans\", -apple-system, BlinkMacSystemFont, \"Segoe UI\",\n    \"PingFang SC\", \"HarmonyOS Sans SC\", \"Noto Sans CJK SC\", \"Microsoft YaHei\", sans-serif;\n  --f-serif: \"Instrument Serif\", \"Iowan Old Style\", Palatino, Georgia, serif;\n  --f-mono: \"JetBrains Mono\", ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, monospace;\n\n  /* 字号阶 · 1.20 主比例，UI 段加密到约 1.07 以保住 13/14/15 三档 */\n  --t-micro: 11px;  --t-cap: 12px;  --t-sm: 13px;   --t-ui: 14px;\n  --t-body: 15px;   --t-lg: 16px;   --t-h5: 18px;   --t-h4: 20px;\n  --t-h3: 24px;     --t-h2: 30px;   --t-h1: 38px;\n  --t-d3: 48px;     --t-d2: 60px;   --t-d1: 76px;\n\n  --lh-tight: 1.05; --lh-head: 1.25; --lh-ui: 1.4; --lh-body: 1.65; --lh-loose: 1.8;\n\n  /* 间距阶 · 4 基准，2/6 只用于图标与描边补偿 */\n  --s1: 2px; --s2: 4px; --s3: 6px;  --s4: 8px;  --s5: 12px; --s6: 16px;\n  --s7: 20px; --s8: 24px; --s9: 32px; --s10: 40px; --s11: 48px;\n  --s12: 64px; --s13: 80px; --s14: 96px; --s15: 128px;\n\n  /* 圆角 · 四档，同心圆角规则：外层 = 内层 + padding */\n  --r-xs: 4px;   --r-sm: 6px;   --r-md: 10px;   --r-lg: 14px;   --r-full: 999px;\n\n  --topbar-h: 56px;\n  --sidebar-w: 264px;\n  --w-content: 1160px;\n  --w-reader: 1600px;\n  --w-prose: clamp(46rem, 60vw, 60rem);\n  --w-marketing: 1200px;\n\n  --dur: 140ms;\n  --ease: cubic-bezier(.32, .72, 0, 1);\n\n  /* 实心按钮顶部那道高光。两套主题同值（它压在 accent / danger 填充上，不压在页面底色上）。 */\n  --gloss: inset 0 1px 0 rgba(255, 255, 255, .14);\n  /* 对话框背后的遮罩。两套主题同值：亮色下也要压暗，不然弹层浮不起来。 */\n  --scrim: rgba(9, 10, 12, .44);\n}\n\n/* ---------- 亮色 ---------- */\n:root, [data-t=\"light\"] {\n  color-scheme: light;\n  --bg: #FBFBFC;\n  --s-1: #FFFFFF;\n  --s-2: #F5F6F8;\n  --s-3: #EDEFF2;\n  --s-4: #E3E6EA;\n  --line: #E4E7EB;\n  --line-strong: #D6DAE0;\n  --line-loud: #C3C9D1;\n  --hairline: transparent;\n\n  --fg: #101317;\n  --fg-muted: #565E68;\n  --fg-subtle: #606871;\n\n  --accent: #057558;\n  --accent-hover: #065E47;\n  --accent-quiet: #E3F7EE;\n  --accent-ring: #B5DFCE;\n  --on-accent: #FFFFFF;\n  --on-danger: #FFFFFF;\n\n  --amber: #825B0C;\n  --amber-quiet: #FAF0E0;\n  --danger: #C02B2F;\n  --danger-hover: #A21921;\n  --danger-quiet: #FFEBE9;\n  --danger-ring: #F4C8C4;\n  --success: #1B763A;\n  --success-quiet: #E6F6E9;\n  --warn: #885716;\n  --warn-quiet: #FAF0E0;\n\n  /* 输入框的内凹。向内凹是「可输入」的信号（按钮向外抬），组件里只引这个 token，\n     不写 .dark 分支 —— 暗色那份在下面的暗色块里换值。 */\n  --inset-field: inset 0 1px 2px rgba(16,19,23,.04);\n  /* 弹层表面：亮色用卡片色 + 控件描边；暗色整体抬一档（见暗色块） */\n  --pop-bg: #FFFFFF;\n  --pop-line: #D6DAE0;\n\n  /* 头像色相散列。**唯一绕开「竹青只表示可交互」的地方**：它区分人，不表达状态。\n     放进 token 而不是留在组件里，是为了让组件代码保持零 hex、零 .dark 分支。 */\n  --av-1-bg: #E3F7EE; --av-1-fg: #045A43;\n  --av-2-bg: #E5EFFC; --av-2-fg: #1B4C8F;\n  --av-3-bg: #FAF0E0; --av-3-fg: #6D4B08;\n  --av-4-bg: #F3E9FB; --av-4-fg: #5A2B8C;\n\n  --sh-1: 0 1px 2px rgba(16,19,23,.06), 0 1px 1px rgba(16,19,23,.04);\n  --sh-2: 0 4px 12px -2px rgba(16,19,23,.08), 0 2px 4px -1px rgba(16,19,23,.05);\n  --sh-3: 0 16px 32px -8px rgba(16,19,23,.14), 0 4px 8px -2px rgba(16,19,23,.06);\n  --press: inset 0 2px 4px rgba(16,19,23,.10);\n\n  --code-key: #A2145E; --code-str: #0A5B45; --code-num: #1F4FA8;\n  --code-com: #7A828C; --code-fn: #6B3FBF;  --code-tag: #0F6B36;\n\n  /* 图表系列色（Chart widget）。六档固定顺序按槽位分配、不循环，顺序本身就是色盲安全机制：\n     相邻两档在 protan / deutan 模拟下 ΔE ≥ 8.5，全部对表面 ≥ 3:1（dataviz 校验器过的，改值先重跑）。\n     刻意不用 --accent：竹青只表示可交互，数据不是控件。第一档蓝、第二档琥珀（与 --amber 同族但抬亮到标记档）。 */\n  --chart-1: #3B6FD4; --chart-2: #A6720C; --chart-3: #1A8F7A;\n  --chart-4: #7C55D9; --chart-5: #D2447F; --chart-6: #5E8C2E;\n}\n\n/* ---------- 暗色 ---------- */\n.dark, [data-t=\"dark\"] {\n  color-scheme: dark;\n  --bg: #090A0C;\n  --s-1: #121519;\n  --s-2: #1A1E23;\n  --s-3: #23282E;\n  --s-4: #2D333A;\n  --line: #242830;\n  --line-strong: #2E333B;\n  --line-loud: #3A4048;\n  /* 暗色里阴影几乎不可见，层次靠这道顶部高光边 */\n  --hairline: rgba(255,255,255,.055);\n\n  --fg: #F5F6F8;\n  --fg-muted: #B4BBC4;\n  --fg-subtle: #939BA5;\n\n  --accent: #48C49C;\n  --accent-hover: #6DD9B3;\n  --accent-quiet: #143B2E;\n  --accent-ring: #256550;\n  --on-accent: #05130F;\n  --on-danger: #200A08;\n\n  --amber: #D6A044;\n  --amber-quiet: #412F13;\n  --danger: #FE7871;\n  --danger-hover: #FF8B83;\n  --danger-quiet: #492826;\n  --danger-ring: #7D4743;\n  --success: #68CA80;\n  --success-quiet: #1F3A25;\n  --warn: #F7AC55;\n  --warn-quiet: #412F13;\n\n  /* 暗色里 .04 的内凹完全看不见，要加深到 .35 才成立 */\n  --inset-field: inset 0 1px 2px rgba(0,0,0,.35);\n  --pop-bg: #1A1E23;\n  --pop-line: #3A4048;\n\n  --av-1-bg: #143B2E; --av-1-fg: #7FDCC0;\n  --av-2-bg: #15294A; --av-2-fg: #9CC3F5;\n  --av-3-bg: #412F13; --av-3-fg: #E0B96F;\n  --av-4-bg: #2E2043; --av-4-fg: #C4A6FF;\n\n  --sh-1: 0 1px 2px rgba(0,0,0,.5);\n  --sh-2: 0 4px 14px -2px rgba(0,0,0,.6), 0 1px 3px rgba(0,0,0,.4);\n  --sh-3: 0 20px 40px -10px rgba(0,0,0,.7), 0 4px 10px rgba(0,0,0,.45);\n  --press: inset 0 2px 4px rgba(0,0,0,.34);\n\n  --code-key: #FF9CB4; --code-str: #7FDCC0; --code-num: #8FBCFF;\n  --code-com: #7C858F; --code-fn: #C4A6FF;  --code-tag: #7EE0A0;\n\n  /* 同六个色相为暗表面重新取档（OKLCH L 0.48–0.67），不是亮色的直接反转 */\n  --chart-1: #5A8BE0; --chart-2: #B8842A; --chart-3: #2FA48C;\n  --chart-4: #9878E8; --chart-5: #D45A8E; --chart-6: #7DA34A;\n}\n\n/* ============================================================\n   旧 token 名的别名（过渡层，下个大版本删）\n\n   现在只剩正文排版（viewer/src/reader.css，自 base.css 原样迁入）还在读它们。\n   official widget 已全部改走 theme.css 的语义 utility（bg-card / text-muted-foreground …），\n   `jdu widget create` 的模板同步换成短名；这里把旧名指向 v3 的新值，reader.css 一行不改就跟着换色板。\n\n   新代码只用短名。改动这一段前先 grep 一遍 `--jiandu-`，确认没人还在读它。\n   ============================================================ */\n:root, [data-t=\"light\"], .dark, [data-t=\"dark\"] {\n  --jiandu-font-sans: var(--f-sans);\n  --jiandu-font-mono: var(--f-mono);\n\n  --jiandu-bg: var(--bg);\n  --jiandu-bg-subtle: var(--s-2);\n  --jiandu-bg-code: var(--s-2);\n  --jiandu-bg-inline-code: var(--s-3);\n  --jiandu-fg: var(--fg);\n  --jiandu-fg-muted: var(--fg-muted);\n  --jiandu-fg-subtle: var(--fg-subtle);\n  --jiandu-border: var(--line-strong);\n  --jiandu-border-muted: var(--line);\n\n  --jiandu-link: var(--accent);\n  --jiandu-link-hover: var(--accent-hover);\n  --jiandu-accent: var(--accent);\n  --jiandu-accent-subtle: var(--accent-quiet);\n  --jiandu-info: var(--accent);\n  --jiandu-info-subtle: var(--accent-quiet);\n  --jiandu-success: var(--success);\n  --jiandu-success-subtle: var(--success-quiet);\n  --jiandu-warning: var(--warn);\n  --jiandu-warning-subtle: var(--warn-quiet);\n  --jiandu-danger: var(--danger);\n  --jiandu-danger-subtle: var(--danger-quiet);\n  --jiandu-selection: var(--accent-quiet);\n\n  --jiandu-skeleton-base: var(--s-2);\n  --jiandu-skeleton-shine: var(--s-3);\n  --jiandu-radius: var(--r-md);\n  --jiandu-radius-sm: var(--r-sm);\n  /* 阅读页正文随视口流体扩展，中文正文保持约 44–58 字/行的可读范围。 */\n  --jiandu-doc-width: var(--w-prose);\n\n  /* 代码高亮：v2 分了 12 档，v3 的 --code-* 只有 6 档，按语义就近合并 */\n  --jiandu-hl-keyword: var(--code-key);\n  --jiandu-hl-entity: var(--code-fn);\n  --jiandu-hl-string: var(--code-str);\n  --jiandu-hl-comment: var(--code-com);\n  --jiandu-hl-constant: var(--code-num);\n  --jiandu-hl-section: var(--code-num);\n  --jiandu-hl-variable: var(--amber);\n  --jiandu-hl-tag: var(--code-tag);\n  --jiandu-hl-addition-fg: var(--success);\n  --jiandu-hl-addition-bg: var(--success-quiet);\n  --jiandu-hl-deletion-fg: var(--danger);\n  --jiandu-hl-deletion-bg: var(--danger-quiet);\n}\n";
+//#endregion
 //#region src/widget-dev.ts
 var ARTIFACTS = [
 	"index.js",
@@ -4563,19 +5193,28 @@ function readMeta(dir, dist) {
 		version: ""
 	};
 }
-/** 线上 base.css 的地址：抓首页 HTML 里的 `/_v/base.<hash>.css`。拿不到返回 null，页面用兜底样式。 */
+/**
+* 线上正文样式表的地址：读 `/_v/manifest.json`（viewer 的产物清单，本来就在那条静态路由下）。
+* 早先是抓首页 HTML 里的 `/_v/base.<hash>.css`，但站点页换成 React 直出后首页只链 app.css，
+* 而 widget 预览要的是**正文**那套排版与 token。清单里按名字取，页面怎么改都不影响。
+* 拿不到返回 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}/`, {
+		const res = await fetch(`${server}/_v/manifest.json`, {
 			signal: ctrl.signal,
 			redirect: "follow"
-		})).text();
+		});
 		clearTimeout(t);
-		const m = /\/_v\/base\.[a-f0-9]+\.css/.exec(html);
-		return m ? `${server}${m[0]}` : null;
+		if (!res.ok) return null;
+		const manifest = await res.json();
+		if (typeof manifest !== "object" || manifest === null) return null;
+		const m = manifest;
+		const file = m["reader.css"] ?? m["app.css"];
+		return typeof file === "string" ? `${server}/_v/${file}` : null;
 	} catch {
 		return null;
 	}
@@ -4588,23 +5227,25 @@ function page(meta, baseCss, hasCss, mtime) {
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${esc(meta.name)} · jdu widget dev</title>
+<style>
+/* 设计系统 tokens（构建期内联的 docs/design-system/tokens.css）：widget 只读 token、不带兜底色，
+   预览页必须自己给一份；连上 server 时线上正文样式表再叠在后面 */
+${tokens_default}
+</style>
 ${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); }
+  html { background: var(--bg); color: var(--fg); font-family: var(--f-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-bar { display: flex; gap: 1rem; align-items: center; padding: 0.5rem 1rem; border-bottom: 1px solid var(--line); font-size: var(--t-sm); color: var(--fg-muted); }
+  .dev-bar b { color: var(--fg); }
+  .dev-bar button { margin-left: auto; height: 26px; padding: 0 var(--s4); border: 1px solid var(--line-strong); border-radius: var(--r-sm); background: var(--s-1); color: var(--fg); font: 550 var(--t-sm) var(--f-sans); 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; }
+  .dev-stage { min-height: 4rem; padding: 1rem; border: 1px dashed var(--line-strong); border-radius: var(--r-md); }
+  details { margin-top: 1.5rem; font-size: var(--t-sm); color: var(--fg-muted); }
+  textarea { width: 100%; min-height: 8rem; margin-top: 0.5rem; padding: 0.5rem; box-sizing: border-box; border: 1px solid var(--line-strong); border-radius: var(--r-sm); background: var(--s-1); color: var(--fg); font: 12px/1.5 var(--f-mono); }
+  .dev-err { color: var(--danger); white-space: pre-wrap; font-family: var(--f-mono); font-size: 12px; }
+  .dev-degraded { padding: 0.75rem; border-radius: var(--r-sm); background: var(--s-2); font-family: var(--f-mono); font-size: 12px; white-space: pre-wrap; }
 </style>
 </head>
 <body>
@@ -4812,26 +5453,36 @@ export interface Data {
   count?: number;
 }
 `;
-var STYLE_CSS = (c) => `/* 颜色一律走 --jiandu-* token（带兜底值），亮 / 暗主题跟宿主一起变；暗色用 .dark 选择器，不要 prefers-color-scheme */
+var STYLE_CSS = (c) => `/* 颜色、字号、圆角一律走宿主的设计 token（docs/design-system/tokens.css），亮 / 暗主题跟宿主一起变；
+   不写 hex，不写 .dark 分支，不用 prefers-color-scheme。常用的：
+   表面 --bg --s-1 --s-2 --s-3 --s-4 · 描边 --line --line-strong --line-loud · 文字 --fg --fg-muted --fg-subtle
+   强调 --accent --accent-quiet --accent-ring --on-accent · 语义 --success --warn --danger（各配 -quiet）
+   字号 --t-sm(13) --t-ui(14) --t-body(15) · 间距 --s4(8) --s5(12) --s6(16) · 圆角 --r-sm(6) --r-md(10) */
 .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);
+  gap: var(--s4);
+  padding: var(--s4) var(--s5);
+  border: 1px solid var(--line);
+  border-radius: var(--r-md);
+  background: var(--s-2);
+  color: var(--fg);
+  font: var(--t-ui) / 1.4 var(--f-sans);
 }
 .w-${c.kebab} button {
-  padding: 0 0.5rem;
-  border: 1px solid var(--jiandu-border, #d0d7de);
-  border-radius: 6px;
-  background: var(--jiandu-bg, #fff);
+  height: 26px;
+  padding: 0 var(--s4);
+  border: 1px solid var(--line-strong);
+  border-radius: var(--r-sm);
+  background: var(--s-1);
   color: inherit;
+  font: 550 var(--t-sm) var(--f-sans);
   cursor: pointer;
 }
+.w-${c.kebab} button:hover {
+  background: var(--s-2);
+  border-color: var(--line-loud);
+}
 `;
 var VANILLA_INDEX = (c) => `import type { WidgetContext } from './_base/contract.js';
 import type { Data } from './types.js';
@@ -5144,6 +5795,7 @@ var WIDGET_JSON = (c) => `${JSON.stringify({
 	name: c.name,
 	scope: "personal",
 	version: "1.0.0",
+	description: "一句话说清什么场景用这个组件——agent 靠它决定选不选",
 	dataSchema: {
 		type: "object",
 		required: ["title"],
@@ -5189,7 +5841,7 @@ npm run push         # = build + jdu widget push dist
 |---|---|
 | \`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\` 选择器 |
+| \`src/style.css\` | 样式。颜色 / 字号 / 圆角走宿主的设计 token（\`--bg\` \`--fg\` \`--line\` \`--accent\` \`--t-ui\` \`--r-md\` …），不写 hex 与 \`.dark\` 分支；主题真源是 \`<html class="dark">\`，token 会自己换值 |
 | \`widget.json\` | name / scope / version / sampleData；dataSchema 由 build 生成，不用手写 |
 | \`scripts/build.mjs\` | 全内联构建配置${c.runtime ? "；`RUNTIME_PATHS` 是平台版本档 runtime 的 URL" : ""} |
 
@@ -5297,8 +5949,28 @@ async function client() {
 function collectTag(value, previous) {
 	return [...previous ?? [], value];
 }
+var VERSION = "0.5.0";
 var program = new Command();
-program.name("jdu").description("jiandu 命令行").version("0.4.0").showHelpAfterError();
+program.name("jdu").description("jiandu 命令行").version(VERSION).showHelpAfterError();
+program.command("deploy").description("把一台简牍部署到你自己的 Cloudflare 账号（Worker + Durable Object，Free 计划够用）").option("--owner <name>", "管理员用户名（JIANDU_AUTH_OWNER）。首次部署必填；升级时不给就保持账号上现有的值").option("--name <name>", "Worker 名字，决定 workers.dev 的子域名前缀", "jiandu").option("--dist <dir>", "用本地构建的产物代替 npm 包（开发用，指向 server/dist-cf）").option("--dry-run", "只校验配置与产物，不上传、不碰你的账号", false).option("--json", "机器可读输出（agent 联动用）", false).action(async (opts) => {
+	const result = await runDeploy(opts);
+	if (opts.json) {
+		process.stdout.write(`${JSON.stringify(result)}\n`);
+		return;
+	}
+	if (opts.dryRun) {
+		process.stdout.write("校验通过：产物与 wrangler 配置都没问题，没有上传任何东西\n");
+		return;
+	}
+	process.stdout.write(`已部署 ${result.url}\n`);
+	if (result.setupSecret === null) {
+		process.stdout.write("实例本来就在跑，secret 与配置原样保留（这是一次升级）\n");
+		return;
+	}
+	process.stdout.write(`\n第一把钥匙（只在这里出现这一次，记下来）：\n  ${result.setupSecret}\n`);
+	process.stdout.write(`\n打开这个链接绑 passkey：\n  ${result.setupUrl}\n`);
+	if (result.loggedIn) process.stdout.write("\njdu 已经连上它了，可以直接 jdu push\n");
+});
 program.command("login").description("登录到一台简牍：定站点、拿凭据、写本地配置（必须指定 --server 或 --local）").option("--local", "目标是本机自部署（http://127.0.0.1:8080）").option("--server <url>", "目标简牍站点地址").option("--token <token>", "直接用 token 登录（无浏览器的机器；token 在 server 首启 stdout / data/initial-token.txt）").option("--user <owner>", "forward-auth：以指定 owner 直连，跳过 SSO（请求注入 X-Forwarded-User 头）").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）").option("--no-browser", "站点支持浏览器授权时也不打开浏览器，只给 token 指引").option("--json", "机器可读输出（agent 联动用；不会打开浏览器）", false).action(async (opts) => {
 	const result = await runLogin({
 		...opts,
@@ -5440,7 +6112,7 @@ template.command("push").argument("<file.md>", "模板文件").description("发
 	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 () => {
+program.command("mcp").description("以 MCP server（stdio）暴露文档 / 评论 / widget / 语法工具，模板同时暴露为 prompts，给本机 agent 用").action(async () => {
 	await runMcp(await client());
 });
 program.command("share").argument("<docId>").description("改可见性 / 进出团队，或管理读者池（定向分享，可撤销）").option("--visibility <v>", VISIBILITIES.join(" | ")).option("--team <teamId>", "进团队（需是该团队成员）").option("--no-team", "移出团队").option("--to <reader>", "加入读者池（身份串，如邮箱 / forward-auth 的 owner），可重复", collectTag, void 0).option("--revoke <reader>", "从读者池移除，立刻失效，可重复", collectTag, void 0).option("--readers", "列出当前读者池", false).action(async (docId, opts) => {
@@ -5493,6 +6165,12 @@ tokenCmd.command("list").description("列出我的 token；CURRENT 是本次请
 		}
 	]);
 });
+tokenCmd.command("create").option("--label <label>", "备注（jdu token list 里辨认用），如 agent / ci", "cli").description("再签一枚 token 给别的机器 / headless agent 用；stdout 只有 token，方便 $(jdu token create --label agent)").action(async (opts) => {
+	const res = await (await client()).postJson("/api/tokens", { label: opts.label });
+	if (typeof res.token !== "string") throw new CliError("server 没有返回 token");
+	process.stderr.write(`id=${String(res.id)} label=${String(res.label)}（明文只显示这一次）\n`);
+	process.stdout.write(`${res.token}\n`);
+});
 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`);