@vibe-lark/larkpal 0.1.8

package/dist/preview-proxy-KMPQK_j4.mjs

@@ -0,0 +1,505 @@
+import { t as larkLogger } from "./lark-logger-D7_pEVQc.mjs";
+import { mkdir, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { createHmac, randomBytes } from "crypto";
+import { join } from "path";
+import { homedir } from "os";
+import { Router } from "express";
+import http from "http";
+//#region src/gateway/plugins/preview-proxy/proxy-middleware.ts
+/**
+* 轻量反向代理中间件
+*
+* 使用 Node.js 内置 http 模块实现，无需额外依赖。
+* 将 Express 请求代理到 localhost:{port}。
+*
+* 功能：
+* - 支持 GET/POST/PUT/DELETE 等所有 HTTP 方法
+* - 传递请求头（移除 host，添加 X-Forwarded-* 头）
+* - 流式传输请求体和响应体
+* - 错误处理（目标不可达时返回 502）
+*/
+const log$3 = larkLogger("preview/proxy");
+/**
+* 创建反代中间件函数
+*
+* @param port 目标端口（Pod 内的 localhost:{port}）
+* @param previewId 用于日志追踪
+*/
+function createProxyMiddleware(port, previewId) {
+	return (req, res) => {
+		const prefix = `/preview/${previewId}`;
+		let targetPath = req.originalUrl;
+		if (targetPath.startsWith(prefix)) targetPath = targetPath.slice(prefix.length) || "/";
+		const url = new URL(targetPath, `http://127.0.0.1:${port}`);
+		url.searchParams.delete("token");
+		const cleanPath = url.pathname + (url.search || "");
+		const headers = { ...req.headers };
+		delete headers.host;
+		headers["x-forwarded-for"] = req.ip || req.socket.remoteAddress || "";
+		headers["x-forwarded-proto"] = req.protocol;
+		headers["x-forwarded-host"] = req.get("host") || "";
+		headers["x-preview-id"] = previewId;
+		const proxyReq = http.request({
+			hostname: "127.0.0.1",
+			port,
+			path: cleanPath,
+			method: req.method,
+			headers
+		}, (proxyRes) => {
+			res.writeHead(proxyRes.statusCode || 200, proxyRes.headers);
+			proxyRes.pipe(res);
+		});
+		proxyReq.on("error", (err) => {
+			log$3.warn("反代请求失败", {
+				previewId,
+				port,
+				targetPath: cleanPath,
+				error: err.message
+			});
+			if (!res.headersSent) res.status(502).send(`Preview target unreachable (port ${port}): ${err.message}`);
+		});
+		req.pipe(proxyReq);
+	};
+}
+//#endregion
+//#region src/gateway/plugins/preview-proxy/token-auth.ts
+/**
+* Preview Token 鉴权
+*
+* 使用 HMAC-SHA256 生成和验证访问 Token。
+*
+* Token 格式：{expiresAt}.{signature}
+*   - expiresAt: Unix 毫秒时间戳
+*   - signature: HMAC-SHA256(previewId + expiresAt, secret) 的 URL-safe base64
+*
+* 密钥来源：
+*   - 环境变量 LARKPAL_PREVIEW_SECRET（推荐，持久化）
+*   - 未设置时：启动时随机生成 32 字节密钥（Pod 重启后旧 Token 失效）
+*/
+const log$2 = larkLogger("preview/token-auth");
+/** Token 签名密钥 */
+const SECRET = process.env.LARKPAL_PREVIEW_SECRET || randomBytes(32).toString("hex");
+if (!process.env.LARKPAL_PREVIEW_SECRET) log$2.warn("LARKPAL_PREVIEW_SECRET 未设置，使用随机密钥（Pod 重启后旧 Token 失效）");
+/** 默认 Token 有效期：24 小时 */
+const DEFAULT_TTL_MS = 1440 * 60 * 1e3;
+/**
+* 生成访问 Token
+*/
+function generateToken(previewId, ttlMs = DEFAULT_TTL_MS) {
+	const expiresAt = Date.now() + ttlMs;
+	const token = `${expiresAt}.${sign(previewId, expiresAt)}`;
+	log$2.info("生成 Preview Token", {
+		previewId,
+		expiresAt: new Date(expiresAt).toISOString()
+	});
+	return {
+		token,
+		expiresAt
+	};
+}
+/**
+* 验证访问 Token
+*
+* @returns true 如果 Token 有效且未过期
+*/
+function verifyToken(previewId, token) {
+	const dotIndex = token.indexOf(".");
+	if (dotIndex === -1) return false;
+	const expiresAtStr = token.substring(0, dotIndex);
+	const signature = token.substring(dotIndex + 1);
+	const expiresAt = Number(expiresAtStr);
+	if (isNaN(expiresAt)) return false;
+	if (Date.now() > expiresAt) {
+		log$2.debug("Token 已过期", {
+			previewId,
+			expiresAt: new Date(expiresAt).toISOString()
+		});
+		return false;
+	}
+	if (signature !== sign(previewId, expiresAt)) {
+		log$2.debug("Token 签名不匹配", { previewId });
+		return false;
+	}
+	return true;
+}
+/** HMAC-SHA256 签名 */
+function sign(previewId, expiresAt) {
+	const data = `${previewId}:${expiresAt}`;
+	return createHmac("sha256", SECRET).update(data).digest("base64url");
+}
+//#endregion
+//#region src/gateway/plugins/preview-proxy/preview-manager.ts
+/**
+* Preview 实例管理器
+*
+* 管理所有活跃的 Preview 实例：
+* - 创建 / 查询 / 删除
+* - 按 sessionId 批量回收
+* - 定期清理过期实例
+*/
+const log$1 = larkLogger("preview/manager");
+/** 默认过期时间：24 小时 */
+const DEFAULT_EXPIRES_MS = 1440 * 60 * 1e3;
+/** 清理间隔：10 分钟 */
+const CLEANUP_INTERVAL_MS = 600 * 1e3;
+var PreviewManager = class {
+	/** previewId → PreviewInstance */
+	previews = /* @__PURE__ */ new Map();
+	/** 定期清理定时器 */
+	cleanupTimer = null;
+	/** 外部基础 URL */
+	externalBaseUrl;
+	constructor(externalBaseUrl) {
+		this.externalBaseUrl = externalBaseUrl || "";
+	}
+	/**
+	* 创建 Preview 实例
+	*/
+	create(request) {
+		const previewId = this.generateId();
+		const visibility = request.visibility || "private";
+		let token;
+		let expiresAt;
+		if (visibility === "private") {
+			const tokenResult = generateToken(previewId);
+			token = tokenResult.token;
+			expiresAt = tokenResult.expiresAt;
+		} else expiresAt = Date.now() + DEFAULT_EXPIRES_MS;
+		const baseUrl = this.externalBaseUrl || `http://localhost:${process.env.PORT || 3e3}`;
+		let url = `${baseUrl}/preview/${previewId}`;
+		if (visibility === "private" && token) url += `?token=${encodeURIComponent(token)}`;
+		const instance = {
+			previewId,
+			port: request.port,
+			visibility,
+			sessionId: request.sessionId,
+			createdAt: Date.now(),
+			expiresAt,
+			token,
+			url
+		};
+		this.previews.set(previewId, instance);
+		log$1.info("Preview 已创建", {
+			previewId,
+			port: request.port,
+			visibility,
+			sessionId: request.sessionId,
+			expiresAt: new Date(expiresAt).toISOString(),
+			url: visibility === "public" ? url : `${baseUrl}/preview/${previewId}?token=***`
+		});
+		return {
+			previewId,
+			url,
+			token,
+			visibility,
+			expiresAt: new Date(expiresAt).toISOString()
+		};
+	}
+	/**
+	* 根据 previewId 获取实例
+	*/
+	get(previewId) {
+		return this.previews.get(previewId);
+	}
+	/**
+	* 删除指定 Preview
+	*/
+	delete(previewId) {
+		const existed = this.previews.delete(previewId);
+		if (existed) log$1.info("Preview 已删除", { previewId });
+		return existed;
+	}
+	/**
+	* 按 sessionId 批量回收
+	*/
+	deleteBySession(sessionId) {
+		let count = 0;
+		for (const [id, instance] of this.previews) if (instance.sessionId === sessionId) {
+			this.previews.delete(id);
+			count++;
+		}
+		if (count > 0) log$1.info("按会话批量回收 Preview", {
+			sessionId,
+			count
+		});
+		return count;
+	}
+	/**
+	* 列出所有活跃 Preview
+	*/
+	list() {
+		return Array.from(this.previews.values());
+	}
+	/**
+	* 启动定期清理任务
+	*/
+	startCleanup() {
+		this.cleanupTimer = setInterval(() => {
+			this.cleanupExpired();
+		}, CLEANUP_INTERVAL_MS);
+		log$1.info("Preview 定期清理已启动", { intervalMs: CLEANUP_INTERVAL_MS });
+	}
+	/**
+	* 停止清理任务并回收所有 Preview
+	*/
+	dispose() {
+		if (this.cleanupTimer) {
+			clearInterval(this.cleanupTimer);
+			this.cleanupTimer = null;
+		}
+		const count = this.previews.size;
+		this.previews.clear();
+		log$1.info("PreviewManager 已清理", { clearedCount: count });
+	}
+	/** 清理过期实例 */
+	cleanupExpired() {
+		const now = Date.now();
+		let cleaned = 0;
+		for (const [id, instance] of this.previews) if (instance.expiresAt < now) {
+			this.previews.delete(id);
+			cleaned++;
+		}
+		if (cleaned > 0) log$1.info("清理过期 Preview", {
+			cleaned,
+			remaining: this.previews.size
+		});
+	}
+	/** 生成 12 字符的随机 ID */
+	generateId() {
+		return randomBytes(9).toString("base64url");
+	}
+};
+//#endregion
+//#region src/gateway/plugins/preview-proxy/index.ts
+/**
+* Preview 插件 — preview-proxy
+*
+* 将 Pod 内 dev server 反代到公网可访问的 URL。
+* 支持 private（Token 鉴权）和 public（无限制）两种权限。
+*
+* 路由：
+*   POST   /api/previews             创建 preview
+*   GET    /api/previews             列出活跃 previews
+*   DELETE /api/previews/:previewId  删除 preview
+*   ALL    /preview/:previewId/*     反代到 localhost:{port}
+*/
+const log = larkLogger("plugin/preview-proxy");
+/**
+* Preview 插件工厂函数
+*/
+function createPreviewProxyPlugin() {
+	let manager;
+	return {
+		name: "preview-proxy",
+		version: "0.1.0",
+		description: "将 Pod 内 dev server 反代到公网可访问的 URL，支持 private/public 权限",
+		requiresExternalAccess: true,
+		register(app, context) {
+			manager = new PreviewManager(context.externalBaseUrl);
+			const apiRouter = Router();
+			apiRouter.post("/api/previews", (req, res) => {
+				try {
+					const body = req.body;
+					if (!body.port || !body.sessionId) {
+						res.status(400).json({ error: "缺少必要参数: port, sessionId" });
+						return;
+					}
+					if (body.port < 1 || body.port > 65535) {
+						res.status(400).json({ error: "端口范围无效: 1-65535" });
+						return;
+					}
+					const result = manager.create(body);
+					log.info("API: 创建 Preview 成功", {
+						previewId: result.previewId,
+						port: body.port,
+						visibility: result.visibility
+					});
+					res.status(201).json(result);
+				} catch (err) {
+					log.error("API: 创建 Preview 失败", { error: err instanceof Error ? err.message : String(err) });
+					res.status(500).json({ error: "创建 Preview 失败" });
+				}
+			});
+			apiRouter.get("/api/previews", (_req, res) => {
+				const list = manager.list().map((p) => ({
+					previewId: p.previewId,
+					port: p.port,
+					visibility: p.visibility,
+					sessionId: p.sessionId,
+					url: p.visibility === "public" ? p.url : p.url.replace(/\?token=.*/, "?token=***"),
+					createdAt: new Date(p.createdAt).toISOString(),
+					expiresAt: new Date(p.expiresAt).toISOString()
+				}));
+				res.json({
+					previews: list,
+					total: list.length
+				});
+			});
+			apiRouter.delete("/api/previews/:previewId", (req, res) => {
+				const previewId = String(req.params.previewId);
+				if (manager.delete(previewId)) {
+					log.info("API: 删除 Preview", { previewId });
+					res.json({ deleted: true });
+				} else res.status(404).json({ error: "Preview 不存在" });
+			});
+			apiRouter.delete("/api/previews/session/:sessionId", (req, res) => {
+				const sessionId = String(req.params.sessionId);
+				const count = manager.deleteBySession(sessionId);
+				log.info("API: 按会话回收 Preview", {
+					sessionId,
+					count
+				});
+				res.json({ deleted: count });
+			});
+			app.use(apiRouter);
+			app.all("/preview/:previewId", handlePreviewRequest);
+			app.all("/preview/:previewId/*splat", handlePreviewRequest);
+			/**
+			* Preview 反代请求处理
+			*/
+			function handlePreviewRequest(req, res) {
+				const previewId = String(req.params.previewId);
+				const instance = manager.get(previewId);
+				if (!instance) {
+					res.status(404).send("Preview not found or expired");
+					return;
+				}
+				if (Date.now() > instance.expiresAt) {
+					manager.delete(previewId);
+					res.status(410).send("Preview expired");
+					return;
+				}
+				if (instance.visibility === "private") {
+					const token = req.query.token || "";
+					if (!token || !verifyToken(previewId, token)) {
+						log.debug("Preview Token 验证失败", { previewId });
+						res.status(403).send("Access denied: invalid or expired token");
+						return;
+					}
+				}
+				createProxyMiddleware(instance.port, previewId)(req, res);
+			}
+			log.info("Preview 插件路由已注册", { routes: [
+				"POST /api/previews",
+				"GET /api/previews",
+				"DELETE /api/previews/:previewId",
+				"DELETE /api/previews/session/:sessionId",
+				"ALL /preview/:previewId/*"
+			] });
+		},
+		async init() {
+			manager.startCleanup();
+			await installPreviewSkill();
+			log.info("Preview 插件初始化完成");
+		},
+		async dispose() {
+			manager.dispose();
+			log.info("Preview 插件已关闭");
+		}
+	};
+}
+/** 技能文件路径 */
+const SKILL_PATH = join(homedir(), ".claude", "commands", "preview.md");
+/** 技能版本标记（更新技能内容时递增，触发覆盖旧版本） */
+const SKILL_VERSION = "v0.1.1";
+/**
+* 安装 /preview 技能文件
+*
+* 幂等操作：仅在文件不存在或版本不匹配时写入。
+*/
+async function installPreviewSkill() {
+	await mkdir(join(homedir(), ".claude", "commands"), { recursive: true });
+	if (existsSync(SKILL_PATH)) {
+		const { readFile } = await import("fs/promises");
+		if ((await readFile(SKILL_PATH, "utf-8")).includes(`skill-version: ${SKILL_VERSION}`)) {
+			log.debug("Preview 技能已是最新版本，跳过安装");
+			return;
+		}
+	}
+	await writeFile(SKILL_PATH, PREVIEW_SKILL_CONTENT, "utf-8");
+	log.info("Preview 配套技能已安装", {
+		path: SKILL_PATH,
+		version: SKILL_VERSION
+	});
+}
+/**
+* /preview 技能内容
+*
+* 教会 CC 如何启动 dev server 并通过网关 API 注册 Preview，
+* 将公网可访问的链接返回给用户。
+*/
+const PREVIEW_SKILL_CONTENT = `---
+skill-version: ${SKILL_VERSION}
+description: 启动 dev server 并生成公网可访问的预览链接
+---
+
+# Preview — 公网预览
+
+当用户要求预览一个 Web 应用（网站、页面等）时，按以下步骤操作：
+
+## 步骤
+
+### 1. 启动 dev server
+
+根据项目类型启动对应的 dev server，确保监听 \`127.0.0.1\`：
+
+- **Vite/React/Vue**: \`npm run dev -- --host 127.0.0.1\`
+- **Next.js**: \`npm run dev -- -H 127.0.0.1\`
+- **静态文件**: \`npx serve -l 5173 .\`
+- **其他**: 确保 dev server 监听在某个本地端口
+
+记下实际监听的端口号（通常是 5173、3000、3001 等）。
+
+### 2. 注册 Preview
+
+调用网关 API 创建 Preview：
+
+\`\`\`bash
+curl -s -X POST http://localhost:3000/api/previews \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "port": <实际端口号>,
+    "sessionId": "<当前会话ID>",
+    "visibility": "private"
+  }'
+\`\`\`
+
+参数说明：
+- \`port\`: dev server 监听的端口号
+- \`sessionId\`: 使用环境变量 \`$LARKPAL_SESSION_ID\` 或当前工作目录名
+- \`visibility\`: \`"private"\`（仅创建者可访问，需要 token）或 \`"public"\`（任何人可访问）
+
+### 3. 返回链接
+
+API 会返回：
+\`\`\`json
+{
+  "previewId": "xxx",
+  "url": "https://larkpal.example.com/preview/xxx?token=yyy",
+  "visibility": "private",
+  "expiresAt": "2025-01-01T00:00:00.000Z"
+}
+\`\`\`
+
+将 \`url\` 返回给用户。如果是 private 模式，提醒用户此链接仅本人可访问。
+
+**重要：输出给用户的地址汇总中，必须使用 API 返回的公网 \`url\`，不要使用 \`localhost\` 或 \`127.0.0.1\` 地址。用户无法访问 Pod 内部的本地端口。**
+
+### 4. 关闭 Preview（可选）
+
+完成预览后，可以关闭：
+
+\`\`\`bash
+curl -s -X DELETE http://localhost:3000/api/previews/<previewId>
+\`\`\`
+
+## 注意事项
+
+- dev server 必须监听 \`127.0.0.1\`，不要监听 \`0.0.0.0\`（安全要求）
+- Preview 默认 24 小时后过期
+- 如果用户说"分享给别人看"，使用 \`"visibility": "public"\`
+- 如果用户只是自己看，使用 \`"visibility": "private"\`（默认）
+`;
+//#endregion
+export { createPreviewProxyPlugin };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@vibe-lark/larkpal",
+  "version": "0.1.8",
+  "description": "LarkPal - Lark/Feishu bot service",
+  "type": "module",
+  "main": "./dist/main.mjs",
+  "bin": {
+    "larkpal": "bin/larkpal.js"
+  },
+  "files": [
+    "bin/",
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vibe-lark/larkpal.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.32.1",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "start": "node --env-file=.env bin/larkpal.js",
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write src/**/*.ts",
+    "format:check": "prettier --check src/**/*.ts"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.60.0",
+    "@sinclair/typebox": "0.34.48",
+    "dotenv": "^17.4.2",
+    "express": "^5.1.0",
+    "image-size": "^2.0.2",
+    "node-cron": "^4.0.8",
+    "openclaw": "^2026.4.9",
+    "uuid": "^11.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/express": "^5.0.2",
+    "@types/node": "^25.2.3",
+    "@types/node-cron": "^3.0.11",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^9.39.3",
+    "eslint-plugin-import-x": "^4.16.2",
+    "eslint-plugin-n": "^17.24.0",
+    "globals": "^16.2.0",
+    "prettier": "^3.8.1",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.32.1",
+    "vitest": "^4.1.1"
+  }
+}