@dyyz1993/create-agent 2.1.0 → 2.1.2

package/templates/browser-agent/src/shared/lib/mock-stream.ts

@@ -0,0 +1,147 @@
+/**
+ * Mock 流式引擎 — 模拟真实 Agent 的多步骤流式输出
+ *
+ * 当 ENABLE_MOCK_STREAM=true 时，browser.agentChat 不连接真实 AI 进程，
+ * 而是走这里。脚本化地按真实流程顺序 emit 事件：
+ *
+ *   agentStart → thinking → turn → toolCall → toolResult → textDelta(逐字) → done
+ *
+ * 这样无需 AI 进程即可验证流式渲染效果和演示产品。
+ *
+ * 事件 payload 结构与 BrowserEvents 接口严格一致（见 modules/browser.ts）。
+ */
+
+/** emit 回调签名 — 和真实 handler 里的 emitEvent 调用一一对应 */
+export type MockEmit = (event: string, payload: Record<string, unknown>) => void;
+
+/** 单条文本按 chunk 切分并逐块 emit（模拟 token 流） */
+async function streamText(
+	text: string,
+	messageId: string,
+	emit: MockEmit,
+	chunkSize = 3,
+	delayMs = 30,
+): Promise<void> {
+	for (let i = 0; i < text.length; i += chunkSize) {
+		const chunk = text.slice(i, i + chunkSize);
+		emit('browser.textDelta', { messageId, delta: chunk });
+		await sleep(delayMs);
+	}
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * 运行一次完整的 mock agent 对话流程。
+ *
+ * @param message  用户输入（用于生成贴合的回复）
+ * @param messageId 后端分配的消息 ID
+ * @param emit     事件发射回调
+ * @returns 最终文本 + 步骤列表（与真实 agentChat 返回值结构一致）
+ */
+export async function runMockAgentChat(
+	message: string,
+	messageId: string,
+	emit: MockEmit,
+): Promise<{ text: string; steps: { label: string; status: string; detail?: string }[] }> {
+	const steps: { label: string; status: string; detail?: string }[] = [];
+
+	// ── 1. Agent 开始 ──────────────────────────────────────────
+	emit('browser.agentStart', { messageId, reply: '🤔 思考中...' });
+	await sleep(400);
+
+	// ── 2. 思考增量 ────────────────────────────────────────────
+	const thinkingChunks = [
+		'用户想要',
+		`「${message.slice(0, 20)}」`,
+		'。\n我需要先打开浏览器，',
+		'然后执行采集操作。',
+	];
+	for (const chunk of thinkingChunks) {
+		emit('browser.thinking', { messageId, delta: chunk });
+		await sleep(80);
+	}
+	await sleep(300);
+
+	// ── 3. 轮次 1 开始 ─────────────────────────────────────────
+	emit('browser.turn', { messageId, turn: 1, maxTurns: 3 });
+	await sleep(200);
+
+	// ── 4. 工具调用：navigate ──────────────────────────────────
+	const tcId = `tc_mock_${Date.now().toString(36)}`;
+	emit('browser.toolCall', {
+		messageId,
+		toolCall: {
+			id: tcId,
+			tool: 'navigate',
+			input: '{"url":"https://www.xiaohongshu.com/explore"}',
+			status: 'running',
+		},
+	});
+	await sleep(600);
+
+	// 工具结果
+	emit('browser.toolResult', {
+		messageId,
+		toolCallId: tcId,
+		output: '{"success":true,"title":"小红书 - 标记我的生活","tabs":1}',
+	});
+	steps.push({
+		label: 'navigate',
+		status: 'done',
+		detail: '{"url":"https://www.xiaohongshu.com/explore"}',
+	});
+	await sleep(300);
+
+	// ── 5. 第一段文本（逐 token 流）────────────────────────────
+	await streamText('好的，我已经打开了小红书。现在我来帮你采集页面上的笔记内容。', messageId, emit);
+	await sleep(400);
+
+	// ── 6. 轮次 2：采集工具 ────────────────────────────────────
+	emit('browser.turn', { messageId, turn: 2, maxTurns: 3 });
+	await sleep(200);
+
+	const tcId2 = `tc_mock2_${Date.now().toString(36)}`;
+	emit('browser.toolCall', {
+		messageId,
+		toolCall: {
+			id: tcId2,
+			tool: 'scrape',
+			input: '{"selector":".note-item","fields":["title","author","likes"]}',
+			status: 'running',
+		},
+	});
+	await sleep(800);
+
+	emit('browser.toolResult', {
+		messageId,
+		toolCallId: tcId2,
+		output: '{"success":true,"count":12,"items":[...]}',
+	});
+	steps.push({
+		label: 'scrape',
+		status: 'done',
+		detail: '采集到 12 条笔记',
+	});
+	await sleep(300);
+
+	// ── 7. 采集进度 ────────────────────────────────────────────
+	emit('browser.progress', {
+		messageId,
+		steps: [...steps, { label: 'export', status: 'running', detail: '导出 CSV...' }],
+	});
+	await sleep(500);
+
+	// ── 8. 总结文本（逐 token 流）──────────────────────────────
+	const finalText = `采集完成！✅\n\n共获取到 **12 条笔记**，包含标题、作者、点赞数等字段。\n\n你可以点击右侧「资产面板」查看完整数据，或导出为 CSV / JSON / Markdown 格式。`;
+	await streamText(finalText, messageId, emit, 4, 25);
+
+	// ── 9. 完成 ────────────────────────────────────────────────
+	emit('browser.done', {
+		messageId,
+		reply: finalText,
+		steps: [...steps, { label: 'export', status: 'done', detail: '已导出 CSV (12 行)' }],
+	});
+
+	return { text: finalText, steps };
+}

package/templates/browser-agent/src/shared/lib/path-security.ts

@@ -0,0 +1,38 @@
+import { resolve } from "path";
+
+let allowedRoots: string[] = [process.cwd()];
+
+export function setAllowedRoots(roots: string[]): void {
+  allowedRoots = roots.map((r) => resolve(r));
+}
+
+export function isRpcPathAllowed(requestedPath: string): boolean {
+  try {
+    if (requestedPath.includes("\0")) return false;
+
+    const decoded = decodeURIComponent(requestedPath);
+    const resolved = resolve(decoded);
+    return allowedRoots.some(
+      (root) => resolved === root || resolved.startsWith(root + "/")
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function validatePath(requestedPath: string): string {
+  if (requestedPath.includes("\0")) {
+    throw new Error(`Access denied: path contains null bytes`);
+  }
+
+  const decoded = decodeURIComponent(requestedPath);
+  const resolved = resolve(decoded);
+
+  if (!isRpcPathAllowed(resolved)) {
+    throw new Error(
+      `Access denied: path "${requestedPath}" is outside allowed roots`
+    );
+  }
+
+  return resolved;
+}

package/templates/browser-agent/src/shared/lib/port-registry.ts

@@ -0,0 +1,103 @@
+/**
+ * Global port registry — tracks all running pi-agent instances.
+ *
+ * File: ~/.pi-agent/ports.json
+ *
+ * Format:
+ * {
+ *   "/absolute/project/path": {
+ *     "port": 3101,
+ *     "pid": 12345,
+ *     "startedAt": "2026-04-29T08:00:00.000Z",
+ *     "name": "my-project"
+ *   }
+ * }
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, basename } from "path";
+import { homedir } from "os";
+
+const REGISTRY_DIR = join(homedir(), ".pi-agent");
+const REGISTRY_FILE = join(REGISTRY_DIR, "ports.json");
+
+export interface PortEntry {
+  port: number;
+  pid: number;
+  startedAt: string;
+  name: string;
+}
+
+export type PortRegistry = Record<string, PortEntry>;
+
+function ensureDir() {
+  if (!existsSync(REGISTRY_DIR)) {
+    mkdirSync(REGISTRY_DIR, { recursive: true });
+  }
+}
+
+export function readRegistry(): PortRegistry {
+  try {
+    if (!existsSync(REGISTRY_FILE)) return {};
+    return JSON.parse(readFileSync(REGISTRY_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeRegistry(registry: PortRegistry): void {
+  ensureDir();
+  writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2), "utf-8");
+}
+
+export function registerPort(projectPath: string, port: number, name: string): void {
+  const registry = readRegistry();
+  registry[projectPath] = {
+    port,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    name: name || basename(projectPath),
+  };
+  writeRegistry(registry);
+}
+
+export function unregisterPort(projectPath: string): void {
+  const registry = readRegistry();
+  delete registry[projectPath];
+  if (Object.keys(registry).length === 0) {
+    writeRegistry(registry);
+  } else {
+    writeRegistry(registry);
+  }
+}
+
+export function cleanupStaleEntries(): void {
+  const registry = readRegistry();
+  let changed = false;
+  for (const [path, entry] of Object.entries(registry)) {
+    try {
+      process.kill(entry.pid, 0);
+    } catch {
+      delete registry[path];
+      changed = true;
+    }
+  }
+  if (changed) writeRegistry(registry);
+}
+
+export function formatRegistryForOutput(): string {
+  cleanupStaleEntries();
+  const registry = readRegistry();
+  const entries = Object.entries(registry);
+  if (entries.length === 0) return "No active instances.";
+
+  const lines = entries.map(([path, entry]) => {
+    const uptime = Math.round((Date.now() - new Date(entry.startedAt).getTime()) / 1000);
+    const uptimeStr = uptime < 60 ? `${uptime}s` : uptime < 3600 ? `${Math.floor(uptime / 60)}m ${uptime % 60}s` : `${Math.floor(uptime / 3600)}h ${Math.floor((uptime % 3600) / 60)}m`;
+    return `  ${entry.name}  →  http://localhost:${entry.port}  (PID ${entry.pid}, up ${uptimeStr})\n  ${path}`;
+  });
+
+  return `Active pi-agent instances (${entries.length}):\n${lines.join("\n\n")}\n\nRegistry: ${REGISTRY_FILE}`;
+}
+
+export { REGISTRY_FILE };

package/templates/browser-agent/src/shared/lib/web-server.ts

@@ -0,0 +1,127 @@
+import { createServer, type Server } from "http";
+import { networkInterfaces } from "os";
+import { createHttpHandler } from "../http-routes";
+import { createSseHandler, type SseHandler } from "../../gateway/sse-transport";
+import { createLogger } from "./logger";
+
+const log = createLogger("web-server");
+
+export interface WebServerConfig {
+	port: number;
+	authToken: string;
+	maxUploadSize: number;
+	corsOrigin: string;
+}
+
+export interface WebServerResult {
+	httpServer: Server;
+	sse: SseHandler;
+	port: number;
+	authToken: string;
+	close: () => Promise<void>;
+}
+
+export function getLocalIP(): string {
+	const nets = networkInterfaces();
+	for (const name of Object.keys(nets)) {
+		const interfaces = nets[name];
+		if (!interfaces) continue;
+		for (const net of interfaces) {
+			if (net.family === "IPv4" && !net.internal) {
+				return net.address;
+			}
+		}
+	}
+	return "127.0.0.1";
+}
+
+function checkPort(port: number): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const testServer = createServer();
+		testServer.once("error", (err: NodeJS.ErrnoException) => {
+			testServer.close();
+			reject(err);
+		});
+		testServer.once("listening", () => {
+			testServer.close();
+			resolve(port);
+		});
+		testServer.listen(port);
+	});
+}
+
+export async function findAvailablePort(startPort: number, maxRetries = 10): Promise<number> {
+	for (let port = startPort; port < startPort + maxRetries; port++) {
+		try {
+			await checkPort(port);
+			return port;
+		} catch {
+			continue;
+		}
+	}
+	throw new Error(`No available port found after ${maxRetries} retries starting from ${startPort}`);
+}
+
+function getFreePort(): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const s = createServer();
+		s.listen(0, () => {
+			const addr = s.address();
+			s.close(() => {
+				if (typeof addr === "object" && addr) {
+					resolve(addr.port);
+				} else {
+					reject(new Error("Failed to allocate port"));
+				}
+			});
+		});
+		s.on("error", reject);
+	});
+}
+
+export async function createWebServer(config: WebServerConfig): Promise<WebServerResult> {
+	const port = config.port === 0 ? await getFreePort() : await findAvailablePort(config.port);
+
+	const httpServer = createServer();
+
+	const sse = createSseHandler(httpServer, {
+		config: {
+			port,
+			authToken: config.authToken,
+			maxUploadSize: config.maxUploadSize,
+		},
+	});
+
+	httpServer.on(
+		"request",
+		createHttpHandler({
+			config: {
+				port,
+				authToken: config.authToken,
+				maxUploadSize: config.maxUploadSize,
+				corsOrigin: config.corsOrigin,
+			},
+			getSseClientCount: () => sse.clients.size,
+			sse,
+		})
+	);
+
+	return new Promise((resolve, reject) => {
+		httpServer.listen(port, () => {
+			log.info("Web server started", { port, corsOrigin: config.corsOrigin });
+
+			resolve({
+				httpServer,
+				sse,
+				port,
+				authToken: config.authToken,
+				close: () =>
+					new Promise<void>((res) => {
+						sse.close();
+						httpServer.close(() => res());
+					}),
+			});
+		});
+		httpServer.on("error", reject);
+	});
+}

package/templates/browser-agent/src/shared/lib/xhs-extract.ts

@@ -0,0 +1,71 @@
+/**
+ * 小红书 DOM 提取表达式
+ *
+ * 作为 eval 表达式注入浏览器执行，返回 JSON 字符串。
+ * 多重 selector 兜底 → 通用 <img>/<a> 退化，保证不空手。
+ */
+
+export const XHS_EXTRACT_EXPR = `JSON.stringify((function(){
+  var notes = [];
+
+  // 策略 1：小红书新版 feed 卡片
+  var cards = document.querySelectorAll('section.note-item, div.note-item, .feeds-page section, .note-item');
+  cards.forEach(function(card){
+    try {
+      var a = card.querySelector('a.cover, a[href*="/explore/"], a[href*="/discovery/item/"], a[href*="/search_result/"]');
+      var img = card.querySelector('img');
+      var titleEl = card.querySelector('.title, .footer .title, .desc, .note-text, h3');
+      var authorEl = card.querySelector('.author-wrapper .name, .author .name, .user-nickname, .name');
+      var likeEl = card.querySelector('.like-wrapper .count, .like-wrapper .like-text, .count, .like-text');
+      var title = titleEl ? titleEl.textContent.trim() : (img ? (img.alt||'').trim() : '');
+      var href = a ? a.href : '';
+      var cover = img ? (img.src||img.getAttribute('data-src')||'') : '';
+      if (!cover) {
+        var bg = card.querySelector('[style*="background-image"]');
+        if (bg) { var m = bg.style.backgroundImage.match(/url\\(["']?(.+?)["']?\\)/); if (m) cover = m[1]; }
+      }
+      if (href || cover) {
+        notes.push({ title: title||'(无标题)', author: authorEl?authorEl.textContent.trim():'', noteUrl: href, coverUrl: cover, likes: likeEl?likeEl.textContent.trim():'' });
+      }
+    } catch(e){}
+  });
+
+  // 策略 2：搜索结果/瀑布流通用
+  if (notes.length === 0) {
+    document.querySelectorAll('a[href*="/explore/"], a[href*="/discovery/item/"], a[href*="/search_result/"]').forEach(function(a){
+      try {
+        var img = a.querySelector('img') || (a.parentElement && a.parentElement.querySelector('img'));
+        var title = img ? (img.alt||'').trim() : a.textContent.trim().slice(0,40);
+        var cover = img ? (img.src||img.getAttribute('data-src')||'') : '';
+        if (a.href) notes.push({ title: title||'(无标题)', author:'', noteUrl: a.href, coverUrl: cover, likes:'' });
+      } catch(e){}
+    });
+  }
+
+  // 策略 3：通用退化
+  if (notes.length === 0) {
+    document.querySelectorAll('img').forEach(function(img){
+      try {
+        var src = img.src || img.getAttribute('data-src') || '';
+        if (!src || src.indexOf('data:')===0 || img.width<80) return;
+        var link = img.closest('a');
+        notes.push({ title: (img.alt||'').trim().slice(0,40)||'(无标题)', author:'', noteUrl: link?link.href:location.href, coverUrl: src, likes:'' });
+      } catch(e){}
+    });
+  }
+
+  // 去重
+  var seen = {}; var uniq = [];
+  notes.forEach(function(n){
+    var key = n.noteUrl || n.coverUrl;
+    if (key && !seen[key]) { seen[key]=1; uniq.push(n); }
+  });
+
+  return { notes: uniq, pageUrl: location.href, pageTitle: document.title, count: uniq.length };
+})())`;
+
+export const XHS_SCROLL_EXPR = `JSON.stringify((function(){
+  var before = document.body.scrollHeight;
+  window.scrollBy(0, 1200);
+  return { scrolled: true, heightBefore: before, heightAfter: document.body.scrollHeight };
+})())`;

package/templates/browser-agent/src/shared/modules/browser.ts

@@ -0,0 +1,86 @@
+/**
+ * Browser 模块 — 浏览器控制、Agent 对话、采集
+ *
+ * 对应 PRD §7.2 SSE 流式 API / §6 Agent 设计
+ */
+
+export interface BrowserMethods {
+  /** 检测浏览器连接状态 */
+  "browser.checkConnection": {
+    params: { pluginId?: string };
+    result: { connected: boolean; browserCount: number; browsers: { pluginId: string; name: string; tabs: number }[] };
+  };
+  /** 获取连接状态（用户视角，不暴露技术细节） */
+  "browser.getConnectionGuide": {
+    params: {};
+    result: { connected: boolean; tabs: number };
+  };
+  /** 获取 Chrome Tab 列表 */
+  "browser.listTabs": {
+    params: {};
+    result: { total: number; activeIndex: number; tabs: { index: number; url: string; title: string; active: boolean }[] };
+  };
+  /** xbrowser 插件列表 */
+  "browser.listPlugins": {
+    params: {};
+    result: { plugins: { name: string; description: string }[] };
+  };
+  /** Agent 对话（触发 Agent 循环，事件通过 RPC 事件推送） */
+  "browser.agentChat": {
+    params: { message: string; sessionId: string; activePlugins?: string[] };
+    result: { messageId: string; text: string; steps: { label: string; status: string; detail?: string }[] };
+  };
+  /** 执行单个 xbrowser 命令（如 scrape/crawl/map/goto/click 等） */
+  "browser.execXbrowser": {
+    params: { command: string; tabIndex?: number };
+    result: { success: boolean; data?: any };
+  };
+  /** 开始录制浏览器操作 */
+  "browser.recordStart": {
+    params: { session?: string; url?: string };
+    result: { success: boolean; session: string; startUrl?: string };
+  };
+  /** 停止录制，返回录制数据 */
+  "browser.recordStop": {
+    params: { session?: string };
+    result: { success: boolean; actions: number; network: number; durationMs: number; steps: number; data?: any };
+  };
+  /** 查询录制状态 */
+  "browser.recordStatus": {
+    params: { session?: string };
+    result: { recording: boolean; actions?: number; network?: number; hasRecording?: boolean };
+  };
+  /** Agent 加工录制数据（流式推送 browser.* 事件） */
+  "browser.processRecording": {
+    params: { sessionId: string; recordingData: any; title?: string };
+    result: { messageId: string; text: string };
+  };
+  /** 系统信息 */
+  "browser.getSystemInfo": {
+    params: {};
+    result: {
+      xbrowser: { available: boolean; version: string | null };
+      browser: { connected: boolean; browsers: any[] };
+      serverVersion: string;
+    };
+  };
+}
+
+export interface BrowserEvents {
+  /** Agent 开始 */
+  "browser.agentStart": { messageId: string; reply: string };
+  /** 工具调用 */
+  "browser.toolCall": { messageId: string; toolCall: { id: string; tool: string; input: string; status: string } };
+  /** 工具结果 */
+  "browser.toolResult": { messageId: string; toolCallId: string; output: string };
+  /** 轮次切换 */
+  "browser.turn": { messageId: string; turn: number; maxTurns: number };
+  /** 思考增量 */
+  "browser.thinking": { messageId: string; delta: string };
+  /** 文本增量 */
+  "browser.textDelta": { messageId: string; delta: string };
+  /** Agent 完成 */
+  "browser.done": { messageId: string; reply: string; steps: any[] };
+  /** 采集进度 */
+  "browser.progress": { messageId: string; steps: { label: string; status: string; detail?: string }[] };
+}

package/templates/browser-agent/src/shared/modules/chat.ts

@@ -0,0 +1,20 @@
+/**
+ * Chat 模块 — 聊天消息
+ */
+export interface ChatMethods {
+  "chat.list": {
+    params: { limit?: number; cursor?: string };
+    result: {
+      messages: { id: string; role: "user" | "assistant"; content: string; timestamp: number }[];
+      hasMore: boolean;
+    };
+  };
+  "chat.send": {
+    params: { content: string };
+    result: { ok: boolean };
+  };
+}
+
+export interface ChatEvents {
+  "chat.message": { id: string; role: "user" | "assistant"; content: string; timestamp: number };
+}

package/templates/browser-agent/src/shared/modules/file.ts

@@ -0,0 +1,40 @@
+/**
+ * File 模块 — 文件系统操作
+ */
+export interface FileMethods {
+  "file.findProjectRoot": {
+    params: Record<string, never>;
+    result: { path: string };
+  };
+  "file.listDir": {
+    params: { path: string };
+    result: {
+      entries: { name: string; path: string; type: "file" | "directory"; size?: number }[];
+      basePath: string;
+    };
+  };
+  "file.createFile": {
+    params: { dirPath: string; name: string };
+    result: { path: string };
+  };
+  "file.createDir": {
+    params: { dirPath: string; name: string };
+    result: { path: string };
+  };
+  "file.rename": {
+    params: { oldPath: string; newName: string };
+    result: { newPath: string };
+  };
+  "file.delete": {
+    params: { path: string };
+    result: { ok: boolean };
+  };
+  "file.copy": {
+    params: { srcPath: string; destDir: string };
+    result: { path: string };
+  };
+  "file.readFile": {
+    params: { path: string };
+    result: { content: string; size: number };
+  };
+}

package/templates/browser-agent/src/shared/modules/session.ts

@@ -0,0 +1,55 @@
+/**
+ * Session 模块 — 会话管理、消息、资源
+ *
+ * 对应 PRD §8 数据模型 — User → Session → Message + Asset
+ */
+
+export interface SessionMethods {
+  /** 创建会话 */
+  "session.create": {
+    params: { title?: string };
+    result: { id: string; title: string; createdAt: number };
+  };
+  /** 获取会话详情 */
+  "session.get": {
+    params: { id: string };
+    result: {
+      id: string; title: string; messages: any[]; assets: any[];
+      createdAt: number; status: string;
+    } | null;
+  };
+  /** 会话列表 */
+  "session.list": {
+    params: {};
+    result: {
+      sessions: { id: string; title: string; createdAt: number; status: string; messageCount: number; assetCount: number }[];
+    };
+  };
+  /** 添加消息 */
+  "session.addMessage": {
+    params: { sessionId: string; message: { role: string; text: string; id?: string } };
+    result: { id: string } | null;
+  };
+  /** 更新最后一条 agent 消息 */
+  "session.updateLastMessage": {
+    params: { sessionId: string; patch: Record<string, any> };
+    result: { ok: boolean };
+  };
+  /** 设置会话状态 */
+  "session.setStatus": {
+    params: { sessionId: string; status: string };
+    result: { ok: boolean };
+  };
+  /** 获取会话历史消息（从 Agent 获取） */
+  "session.getMessages": {
+    params: { sessionId: string };
+    result: { messages: any[] };
+  };
+  /** 清理 Agent session */
+  "session.disposeAgent": {
+    params: { sessionId: string };
+    result: { ok: boolean };
+  };
+}
+
+export interface SessionEvents {}