@blocklet/pages-kit-agents 0.5.41 → 0.5.42

package/lib/cjs/utils/component-tuils.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare function getSchemaByComponentIds(sections: {
+    componentId: string;
+    componentName: string;
+    sectionName: string;
+}[]): z.ZodObject<Record<string, any>, "strip", z.ZodTypeAny, {
+    [x: string]: any;
+}, {
+    [x: string]: any;
+}>;
+export declare function getComponentsSimpleMetadata(): string;
+export declare function getComponentsMetadata(): string;

package/lib/cjs/utils/component-tuils.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSchemaByComponentIds = getSchemaByComponentIds;
+exports.getComponentsSimpleMetadata = getComponentsSimpleMetadata;
+exports.getComponentsMetadata = getComponentsMetadata;
+const zod_utils_1 = require("@blocklet/pages-kit-block-studio/zod-utils");
+const zod_1 = require("zod");
+const componentList = [
+    {
+        name: 'HeroV2',
+        id: '1',
+        description: 'Hero 区域，展示核心价值主张，主 CTA',
+        properties: zod_1.z.object({
+            title: zod_1.z.string().describe('主标题'),
+            description: zod_1.z.string().describe('描述'),
+            image: zod_1.z.string().describe('图片'),
+            buttons: zod_1.z
+                .array(zod_1.z.object({
+                text: zod_1.z.string().describe('按钮文本'),
+                link: zod_1.z.string().describe('按钮链接'),
+            }))
+                .describe('按钮列表'),
+        }),
+    },
+    {
+        name: 'ContentCards',
+        id: '2',
+        description: 'Hero、Features 、 Benefits、How it Works、',
+        properties: zod_1.z.object({
+            title: zod_1.z.string().describe('标题'),
+            description: zod_1.z.string().describe('描述'),
+            list: zod_1.z
+                .array(zod_1.z.object({
+                title: zod_1.z.string().describe('标题'),
+                description: zod_1.z.string().describe('描述'),
+                image: zod_1.z.string().describe('图片'),
+            }))
+                .describe('列表'),
+        }),
+    },
+    {
+        name: 'FAQ',
+        id: '3',
+        description: 'FAQ 区域，展示常见问题及答案',
+        properties: zod_1.z.object({
+            title: zod_1.z.string().describe('标题'),
+            list: zod_1.z
+                .array(zod_1.z.object({
+                question: zod_1.z.string().describe('问题'),
+                answer: zod_1.z.string().describe('答案'),
+            }))
+                .describe('列表'),
+        }),
+    },
+    {
+        name: 'Pricing',
+        id: '4',
+        description: 'Pricing 区域，展示价格方案',
+        properties: zod_1.z.object({
+            title: zod_1.z.string().describe('标题'),
+            list: zod_1.z
+                .array(zod_1.z.object({
+                title: zod_1.z.string().describe('标题'),
+                description: zod_1.z.string().describe('描述'),
+                price: zod_1.z.string().describe('价格'),
+            }))
+                .describe('列表'),
+        }),
+    },
+    {
+        name: 'CTA',
+        id: '5',
+        description: 'CTA 区域，展示最终行动召唤',
+        properties: zod_1.z.object({
+            title: zod_1.z.string().describe('标题'),
+            description: zod_1.z.string().describe('描述'),
+            buttons: zod_1.z
+                .array(zod_1.z.object({
+                text: zod_1.z.string().describe('按钮文本'),
+                link: zod_1.z.string().describe('按钮链接'),
+            }))
+                .describe('按钮列表'),
+        }),
+    },
+    {
+        name: 'Logo List',
+        id: '6',
+        description: 'Logo 列表，展示合作伙伴',
+        properties: zod_1.z.object({
+            title: zod_1.z.string().describe('标题'),
+            list: zod_1.z
+                .array(zod_1.z.object({
+                image: zod_1.z.string().describe('图片'),
+                name: zod_1.z.string().describe('名称'),
+                link: zod_1.z.string().describe('链接'),
+            }))
+                .describe('列表'),
+        }),
+    },
+];
+function getSchemaByComponentIds(sections) {
+    const schemaObject = {};
+    sections.forEach((section) => {
+        const component = componentList.find((comp) => comp.id === section.componentId);
+        if (component) {
+            schemaObject[section.sectionName] = component.properties;
+        }
+    });
+    return zod_1.z.object(schemaObject);
+}
+function getComponentsSimpleMetadata() {
+    return componentList
+        .map((component) => {
+        const context = `
+    ------------------------------------------------------------
+     组件名称：${component.name}
+     组件Id：${component.id}
+     组件描述(适用场景)：${component.description}
+    ------------------------------------------------------------
+    `;
+        return context;
+    })
+        .filter(Boolean)
+        .join('\n');
+}
+function getComponentsMetadata() {
+    return componentList
+        .map((component) => {
+        const context = `
+    ------------------------------------------------------------
+     组件名称：${component.name}
+     组件Id：${component.id}
+     组件描述(适用场景)：${component.description}
+     组件属性结构：${JSON.stringify((0, zod_utils_1.zodSchemaToJsonSchema)(component.properties))}
+    ------------------------------------------------------------
+    `;
+        return context;
+    })
+        .filter(Boolean)
+        .join('\n');
+}

package/lib/cjs/utils/file-utils.d.ts

@@ -3,3 +3,26 @@
  * and generating a list of all HTML files in each subfolder
  */
 export declare function updateFileList(): Promise<void>;
+/**
+ * File content information interface
+ */
+export interface FileContent {
+    filePath: string;
+    fileName: string;
+    content: string;
+}
+/**
+ * Recursively reads files matching a pattern from a directory and its subdirectories
+ * @param dirPath - The directory path to search in
+ * @param pattern - String or RegExp pattern to match file names
+ * @param options - Optional configuration
+ * @returns Promise<FileContent[]> - Array of file content objects
+ */
+export declare function readFilesByPattern(dirPath: string, pattern: string | RegExp, options?: {
+    recursive?: boolean;
+}): Promise<FileContent[]>;
+export declare function readFileByPath(filePath: string): Promise<string>;
+/**
+ * Save content to a file, creating directories if needed
+ */
+export declare function saveFileByPath(filePath: string, content: string): Promise<void>;

package/lib/cjs/utils/file-utils.js

@@ -27,6 +27,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateFileList = updateFileList;
+exports.readFilesByPattern = readFilesByPattern;
+exports.readFileByPath = readFileByPath;
+exports.saveFileByPath = saveFileByPath;
 const fs_1 = require("fs");
 const fs = __importStar(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
@@ -132,3 +135,77 @@ const FILE_LIST_DATA = [];`);
         console.error('Error updating file list:', error);
     }
 }
+/**
+ * Recursively reads files matching a pattern from a directory and its subdirectories
+ * @param dirPath - The directory path to search in
+ * @param pattern - String or RegExp pattern to match file names
+ * @param options - Optional configuration
+ * @returns Promise<FileContent[]> - Array of file content objects
+ */
+async function readFilesByPattern(dirPath, pattern, options = { recursive: true }) {
+    const results = [];
+    // Convert string pattern to RegExp if needed
+    const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+    /**
+     * Recursively process directory
+     */
+    async function processDirectory(currentPath) {
+        try {
+            const entries = await fs.readdir(currentPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path_1.default.join(currentPath, entry.name);
+                if (entry.isDirectory() && options.recursive) {
+                    // Recursively process subdirectory
+                    await processDirectory(fullPath);
+                }
+                else if (entry.isFile() && regex.test(entry.name)) {
+                    // Read file content if it matches the pattern
+                    try {
+                        const content = await fs.readFile(fullPath, 'utf8');
+                        results.push({
+                            filePath: fullPath,
+                            fileName: entry.name,
+                            content,
+                        });
+                    }
+                    catch (fileError) {
+                        // Ignore individual file read errors and continue
+                        console.warn(`Warning: Failed to read file ${fullPath}:`, fileError);
+                    }
+                }
+            }
+        }
+        catch (dirError) {
+            // Ignore directory read errors and continue
+            console.warn(`Warning: Failed to read directory ${currentPath}:`, dirError);
+        }
+    }
+    // Check if the directory exists before processing
+    if (!(0, fs_1.existsSync)(dirPath)) {
+        console.warn(`Warning: Directory ${dirPath} does not exist`);
+        return results;
+    }
+    await processDirectory(dirPath);
+    return results;
+}
+// 读取文件内容
+async function readFileByPath(filePath) {
+    try {
+        const absolutePath = path_1.default.resolve(process.cwd(), filePath);
+        const content = await fs.readFile(absolutePath, 'utf-8');
+        return content;
+    }
+    catch (error) {
+        throw new Error(`无法读取文件 "${filePath}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Save content to a file, creating directories if needed
+ */
+async function saveFileByPath(filePath, content) {
+    const pathModule = await Promise.resolve().then(() => __importStar(require('path')));
+    const fsModule = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+    const dir = pathModule.dirname(filePath);
+    await fsModule.mkdir(dir, { recursive: true });
+    await fsModule.writeFile(filePath, content, 'utf8');
+}

package/lib/cjs/workflow-agents/reflection-agent.d.ts

@@ -0,0 +1,16 @@
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type Message } from '@aigne/core';
+import type { PromiseOrValue } from '@aigne/core/utils/type-utils.js';
+export interface ReflectionAgentOptions<I extends Message = Message, RO extends Message = Message> extends AgentOptions<I, I> {
+    editor: Agent<I, I>;
+    reviewer: Agent<I, RO>;
+    isApproved?: (result: RO) => PromiseOrValue<boolean>;
+    maxIterations?: number;
+}
+export declare class ReflectionAgent<I extends Message = Message, RO extends Message = Message> extends Agent<I, I> {
+    constructor(options: ReflectionAgentOptions<I, RO>);
+    editor: Agent<I, I>;
+    reviewer: Agent<I, RO>;
+    isApproved?: (result: RO) => PromiseOrValue<boolean>;
+    maxIterations: number;
+    process(input: I, options: AgentInvokeOptions): Promise<AgentProcessResult<I>>;
+}

package/lib/cjs/workflow-agents/reflection-agent.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReflectionAgent = void 0;
+const core_1 = require("@aigne/core");
+const DEFAULT_MAX_ITERATIONS = 3;
+class ReflectionAgent extends core_1.Agent {
+    constructor(options) {
+        super(options);
+        this.editor = options.editor;
+        this.reviewer = options.reviewer;
+        this.isApproved = options.isApproved;
+        this.maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    }
+    editor;
+    reviewer;
+    isApproved;
+    maxIterations;
+    async process(input, options) {
+        let previousResult = input;
+        let reviewResult;
+        let iterations = 0;
+        // 先执行一次 editor，确保有结果
+        previousResult = await options.context.invoke(this.editor, previousResult);
+        do {
+            reviewResult = await options.context.invoke(this.reviewer, previousResult);
+            const isApproved = await this.isApproved?.(reviewResult);
+            if (isApproved === true) {
+                return previousResult;
+            }
+            previousResult = await options.context.invoke(this.editor, {
+                ...previousResult,
+                ...reviewResult,
+            });
+        } while (++iterations < this.maxIterations);
+        return previousResult;
+    }
+}
+exports.ReflectionAgent = ReflectionAgent;

package/lib/esm/agents/template-designer.d.ts

@@ -0,0 +1,13 @@
+import { AIAgent } from '@aigne/core';
+/**
+ * 用于设计页面结构的 workflow
+ * 1. AI 根据拿到的 collectorResult 和 componentList，生成一个页面设计模板，需要用 ASCII 图画出来，给到用户确认
+ * 2. 用户确认后，AI 保存页面设计模板，并返回页面设计模板
+ */
+export declare const designerAgent: AIAgent<{
+    collectResult: string;
+}, {
+    ascii: string;
+    $message: string;
+    filteredComponentList: string[];
+}>;

package/lib/esm/agents/template-designer.js

@@ -0,0 +1,61 @@
+import { DefaultMemory } from '@aigne/agent-library/default-memory/index.js';
+import { AIAgent } from '@aigne/core';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+const { OPENAI_API_KEY } = process.env;
+assert(OPENAI_API_KEY, 'Please set the OPENAI_API_KEY environment variable');
+const memory = new DefaultMemory({
+    storage: {
+        url: 'file:./dbs/memory.db', // Path to store memory data, such as 'file:./memory.db'
+    },
+});
+const componentList = fs.readFileSync(path.join(__dirname, '../data-sources/pages-kit-component-list.yaml'), 'utf-8');
+const agentInstructions = `
+你是一个专业的页面设计师，名叫小设。你的任务是根据整理好的用户需求，设计一个页面结构。
+
+设计规则：
+1. 设计的页面结构，需要画出 ASCII 图，给到用户确认
+2. 需要在 ASCII 图上，标注出结构和放什么内容
+3. 需要在限定的组件列表中，选择合适的组件
+4. 具有把拼装复合组件的能力，如果涉及到复合组件，请将他们框选起来，标注出复合组件的结构
+5. 不用告诉用户这是 ASCII 图，用户不关心，用户只关心页面设计模板
+6. 你只能使用支持的组件列表中的组件，不能使用其他组件
+7. 如果在没有找到合适的组件，请使用拼装组件的能力，将多个组件拼装起来，形成一个复合组件
+
+
+支持使用的组件列表：
+<component-list>
+${componentList}
+</component-list>
+
+整理好的用户需求：
+<collect-result>
+{{collectResult}}
+</collect-result>
+
+用户反馈：
+<<< {{userFeedBack}} >>>
+`;
+/**
+ * 用于设计页面结构的 workflow
+ * 1. AI 根据拿到的 collectorResult 和 componentList，生成一个页面设计模板，需要用 ASCII 图画出来，给到用户确认
+ * 2. 用户确认后，AI 保存页面设计模板，并返回页面设计模板
+ */
+export const designerAgent = AIAgent.from({
+    name: 'designer',
+    description: '设计页面结构，并且给到用户确认',
+    inputSchema: z.object({
+        collectResult: z.string().describe('整理好的用户需求'),
+    }),
+    outputSchema: z.object({
+        ascii: z.string().describe('ASCII 图'),
+        $message: z.string().describe('给到用户的信息，用于用户确认，不需要包含 ASCII 图'),
+        filteredComponentList: z.array(z.string()).describe('过滤后的组件列表，只包含页面设计需要的组件'),
+    }),
+    memory,
+    instructions: `
+${agentInstructions}
+  `,
+});

package/lib/esm/agents/template-generator.d.ts

@@ -0,0 +1,18 @@
+import { FunctionAgent } from '@aigne/core';
+import { ReflectionAgent } from '../workflow-agents/reflection-agent.js';
+export declare const generatorAgentWithReflection: ReflectionAgent<{
+    ascii: string;
+    collectResult: string;
+    $message: string;
+    filteredComponentList: string[];
+    feedback?: string | null | undefined;
+}, {
+    isApproved: boolean;
+    feedback: string;
+}>;
+export declare const saveYamlAgent: FunctionAgent<{
+    $message: string;
+    yaml: string;
+}, {
+    $message: string;
+} & import("@aigne/core").Message>;

package/lib/esm/agents/template-generator.js

@@ -0,0 +1,180 @@
+import { DefaultMemory } from '@aigne/agent-library/default-memory/index.js';
+import { AIAgent, FunctionAgent, createMessage } from '@aigne/core';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { ReflectionAgent } from '../workflow-agents/reflection-agent.js';
+const { OPENAI_API_KEY } = process.env;
+assert(OPENAI_API_KEY, 'Please set the OPENAI_API_KEY environment variable');
+const memory = new DefaultMemory({
+    storage: {
+        url: 'file:./dbs/memory.db', // Path to store memory data, such as 'file:./memory.db'
+    },
+});
+const componentList = fs.readFileSync(path.join(__dirname, '../data-sources/pages-kit-component-list.yaml'), 'utf-8');
+const pagesKitTemplateRule = fs.readFileSync(path.join(__dirname, '../data-sources/pages-kit-template-rule.md'), 'utf-8');
+const generatorAgentInstructions = `
+你是专业的 Pages Kit 模板工程师小猿。你的任务是根据用户需求和设计师的页面设计模板，生成完全符合 Pages Kit 框架规范的 YAML 结构。
+
+## 核心职责
+基于提供的用户需求、设计师ASCII图和组件列表，生成可直接使用的 Pages Kit YAML 模板。
+
+## 严格遵循的编码原则
+1. **结构完整性**: 必须完全符合 Pages Kit 框架的 YAML Schema 结构规范
+2. **设计一致性**: 严格按照设计师的页面设计模板实现，不得擅自修改布局和结构
+3. **组件组合**: 当单个组件无法满足设计需求时，使用多个组件组合实现复杂布局
+4. **ID唯一性**: 所有涉及 id 的属性值必须唯一，使用16位随机字符串（字母+数字混合，无语义化）
+5. **语义准确性**: 确保组件选择和属性配置准确反映用户需求和设计意图
+
+## 输出要求
+- 生成完整可执行的 YAML 结构
+- 在 $message 中简洑说明实现思路和关键设计决策
+- 确保所有组件都来自提供的过滤组件列表
+- 必须返回所有输入字段以保持数据流的完整性
+
+## 技术规范参考
+<pages-kit-template-rule>
+${pagesKitTemplateRule}
+</pages-kit-template-rule>
+
+## 全部可用组件
+<component-list>
+${componentList}
+</component-list>
+
+## 当前任务输入
+用户需求：
+<collect-result>
+{{collectResult}}
+</collect-result>
+
+设计师页面模板：
+<ascii>
+{{ascii}}
+</ascii>
+
+本次可使用的组件（已过滤）：
+<filtered-component-list>
+{{filteredComponentList}}
+</filtered-component-list>
+
+<#if feedback>
+## 验证反馈
+上一次生成的YAML结构存在以下问题，请根据反馈进行修正：
+<feedback>
+{{feedback}}
+</feedback>
+</#if>
+
+<#if yaml>
+## 上一次生成的YAML结构
+<yaml>
+{{yaml}}
+</yaml>
+</#if>
+
+请严格按照上述要求生成YAML结构，并确保返回所有必需的字段。`;
+const validatorAgentInstructions = `
+你是专业的 Pages Kit 模板验证专家小验。你的任务是严格验证生成的 YAML 结构是否完全符合 Pages Kit 框架规范。
+
+## 核心职责
+对生成的 YAML 模板进行全面技术验证，确保其在 Pages Kit 框架中能够正确运行。
+
+## 验证检查清单
+1. **结构规范性**: 严格检查是否完全符合 Pages Kit 框架的 YAML Schema 结构
+2. **语法正确性**: 验证 YAML 语法格式是否正确，缩进、字段名等是否准确
+3. **ID唯一性**: 所有 id 属性值必须唯一且为16位随机字符串（字母数字混合，非语义化）
+4. **组件合法性**: 确认所有使用的组件都在允许的组件列表中
+5. **属性完整性**: 检查必需属性是否全部提供，可选属性是否合理
+6. **嵌套层级**: 验证嵌套结构深度和层级关系是否正确
+7. **数据类型**: 确认各字段的数据类型符合规范要求
+
+## 技术规范依据
+<pages-kit-template-rule>
+${pagesKitTemplateRule}
+</pages-kit-template-rule>
+
+## 验证输入
+用户需求：{{collectResult}}
+设计师ASCII图：{{ascii}}
+可用组件列表：{{filteredComponentList}}
+生成的YAML：{{yaml}}
+
+## 验证原则
+- 零容忍态度对待规范违规
+- 优先保证模板的可执行性和稳定性
+- 发现问题时提供清晰的改进建议
+
+请对提供的 YAML 结构进行全面验证。`;
+/**
+ * 用于实现页面结构的 workflow
+ * 1. AI 根据拿到的 ASCII 图，整理好的用户需求，支持使用的组件列表，生成一个 Yaml 结构，给到验证器验证
+ * 2. 使用反思工作流，AI 自动根据验证器反馈，自动修改 Yaml 结构，直到验证器验证通过
+ * 3. 验证器验证通过后，AI 保存 Yaml 结构，并返回 Yaml 结构
+ */
+const generatorAgent = AIAgent.from({
+    name: 'generator',
+    description: '实现页面结构，并且给到用户确认',
+    inputSchema: z.object({
+        ascii: z.string().describe('ASCII 图'),
+        collectResult: z.string().describe('整理好的用户需求'),
+        filteredComponentList: z.array(z.string()).describe('过滤后的组件列表，只包含页面设计需要的组件'),
+        $message: z.string(),
+        feedback: z.string().nullish().describe('Feedback from the reviewer'),
+    }),
+    outputSchema: z.object({
+        ascii: z.string().describe('ASCII 图'),
+        collectResult: z.string().describe('整理好的用户需求'),
+        filteredComponentList: z.array(z.string()).describe('过滤后的组件列表，只包含页面设计需要的组件'),
+        $message: z.string().describe('给到用户的信息，用于用户确认'),
+        yaml: z.string().describe('Yaml 结构'),
+        feedback: z.string().nullish().describe('Feedback from the reviewer'),
+    }),
+    memory,
+    instructions: `
+${generatorAgentInstructions}
+  `,
+});
+const validatorAgent = AIAgent.from({
+    name: 'validator',
+    description: '验证 Yaml 结构符合 Pages Kit 框架的 Yaml Schema 结构',
+    inputSchema: z.object({
+        ascii: z.string().describe('ASCII 图'),
+        collectResult: z.string().describe('整理好的用户需求'),
+        filteredComponentList: z.array(z.string()).describe('过滤后的组件列表，只包含页面设计需要的组件'),
+        $message: z.string(),
+        yaml: z.string().describe('Yaml 结构'),
+        feedback: z.string().nullish().describe('Feedback from the reviewer'),
+    }),
+    memory,
+    outputSchema: z.object({
+        isApproved: z.boolean().describe('是否符合 Pages Kit 框架的 Yaml Schema 结构'),
+        feedback: z.string().describe('Feedback for the markdown'),
+    }),
+    instructions: `
+${validatorAgentInstructions}
+  `,
+});
+export const generatorAgentWithReflection = new ReflectionAgent({
+    name: 'generator-with-reflection',
+    maxIterations: 3,
+    editor: generatorAgent,
+    reviewer: validatorAgent,
+    isApproved: (result) => result.isApproved,
+});
+export const saveYamlAgent = FunctionAgent.from({
+    inputSchema: z.object({
+        $message: z.string().describe('给到用户的信息，用于用户确认'),
+        yaml: z.string().describe('Yaml 结构'),
+    }),
+    name: 'save-yaml',
+    description: '保存 Yaml 结构到文件',
+    async process({ yaml }) {
+        const templateName = new Date().toISOString().replace(/[:.]/g, '-');
+        const filePath = path.join(__dirname, `../test-templates/template-${templateName}.yaml`);
+        // 把 yaml 结构保存到文件
+        fs.writeFileSync(filePath, yaml);
+        return createMessage(`Yaml 结构已保存到 ${filePath}`);
+    },
+});