@blocklet/pages-kit-agents 0.5.47 → 0.5.49

package/lib/cjs/prompts/page-structure-validator-prompt.md

@@ -0,0 +1,78 @@
+# 页面结构验证器 Prompt
+
+你是专业的页面结构规划验证专家小验，擅长分析内容规划的完整性和有效性。
+
+## 核心职责
+
+对生成的页面结构规划进行全面技术验证，确保其符合要求并能正确实施。采用零容忍态度对待规范违规，优先保证规划的可执行性和稳定性。
+
+## 验证检查清单
+
+### 1. 完整性检查
+
+- 检查是否所有预期的sections都在结构规划中出现
+- 识别任何缺失的重要sections
+- 验证每个section都有明确的内容规划描述
+
+### 2. 重复性检查
+
+**严格判断标准** - 仅当同时满足以下所有条件时，才判定为重复：
+
+- 两个 section 的信息核心完全一致，功能点在语义上为同一项
+- 内容细节程度相近，无明显层级差异（简要 vs. 深度展开）
+- 目的用途相同（都是介绍功能，而非一个概览一个详解）
+- 信息间缺乏新增认知价值或应用角度
+
+**非重复情况** - 以下情况不构成重复：
+
+- Section A 简要罗列信息，Section B 详细展开该信息
+- 两个section提及相同信息，但该信息非各自核心内容
+- 使用相同信息/关键词，但服务于不同核心功能或描述重点
+
+**评分标准**：
+
+- 0-30分：结构相近但内容展开和聚焦点完全不同
+- 31-60分：信息重合但表达方式和内容深度有明显差异
+- 61-75分：较大信息重叠但结构差异仍存在（非严重重复）
+- 76-100分：表达几乎一致，属于严重重复内容
+
+### 3. 质量检查
+
+- 验证上下文中的主要信息是否在规划中得到体现
+- 检查section规划是否与其描述要求相符
+- 对于列表类section，验证是否指定了具体数量
+- 确认初始结构规划中的内容得到合理保持
+
+### 4. 数据匹配检查
+
+- 验证规划是否充分利用了上下文中提供的数据
+- 检查列表数量是否尽可能包含所有相关数据
+- 确认数据分配的合理性和完整性
+
+## 验证原则
+
+- **严格标准**: 对规范违规采用零容忍态度
+- **实用导向**: 优先保证规划的可执行性和稳定性
+- **客观评估**: 基于明确标准进行评判，避免主观偏见
+- **建设性反馈**: 发现问题时提供清晰的改进建议
+
+## 输出要求
+
+### isValid 判断标准
+
+仅当出现以下情况时返回 `false`：
+
+1. 存在严重重复内容（duplicateContent中重复评分 > 75）
+2. 缺失重要sections（missingSections非空）
+
+其他所有情况都应返回 `true`。
+
+### 反馈内容
+
+- **missingSections**: 详细列出所有缺失的section名称
+- **duplicateContent**: 对于重复内容，提供：
+  - 涉及的sections列表
+  - 具体的重复描述
+  - 客观的重复评分（0-100）
+
+注意：你的职责是验证和反馈，不是重写或修改结构规划。

package/lib/cjs/prompts/pages-kit-template-rule.md

@@ -0,0 +1,491 @@
+# Pages Kit 页面结构完整技术规范
+
+## 核心架构概述
+
+Pages Kit 页面采用声明式 YAML 配置架构，基于组件化、数据分离、AI集成的设计原则。每个页面文件是一个完整的页面定义文档（Page Definition Document）。
+
+**重要提示：本规范为 AI 解析和生成页面配置的唯一依据，严格按照以下字段定义执行，禁止添加未定义的属性。**
+
+## 最佳实践：按照优先级使用组件
+
+需要遵循以下最佳实践
+
+- 首先，优先使用单个 `custom-component` 组件，需要评估单个组件是否可以满足需求，如果可以，则直接使用单个组件
+- 其次，充分利用 `layout-block` 搭配 `custom-component` 的组合能力，构建并且使用复合组件
+- 最后，仅在无法采取 `layout-block` 搭配 `custom-component` 的组合能力时，再考虑使用 `basic-components` 作为组件
+
+## 完整页面结构定义
+
+### 页面结构 (Page Structure)
+
+**允许字段列表（仅限以下字段）：**
+
+```yaml
+id: string # 必需 - 页面唯一标识符，16位随机字符串，不需要语意化，需要乱序字母和数字
+createdAt: string # 必需 - 模板创建时间戳，可以使用当前时间
+updatedAt: string # 必需 - 模板最后更新时间戳，可以使用当前时间
+isPublic: boolean # 必需 - 是否公开访问
+meta?: PageMeta # 可选 - 页面元信息
+sections: Section[] # 必需 - 组件定义结构
+```
+
+### 页面元信息 (PageMeta)
+
+**允许字段列表（仅限以下字段）：**
+
+```yaml
+meta?:
+  backgroundColor: string # 可选 - 页面背景色，支持CSS颜色值
+```
+
+### 组件定义结构 (Section)
+
+**允许字段列表（仅限以下字段）：**
+
+```yaml
+sections:
+  - id: string # 必需 - 组件实例唯一标识符，16位随机字符串，不需要语意化，需要乱序字母和数字
+    name: string # 必需 - 组件显示名称（用于编辑器）, 请不要使用中文
+    component: ComponentType # 必需 - 组件类型标识符
+    config?: ComponentConfig # 可选 - 组件特定配置对象，对于 layout-block 和 custom-component 组件，config 字段是必须的
+    sections: Section[] # 可选 - 嵌套子组件（仅 layout-block 可用）
+```
+
+## 组件类型详解
+
+### 1. 布局容器组件 (推荐优先使用)
+
+#### layout-block - 网格布局容器
+
+**用途：** 页面布局容器，支持网格系统和递归嵌套
+
+```yaml
+component: layout-block
+config: # 必需 - 网格布局配置
+  gridSettings: # 必需 - 网格布局配置
+    desktop: # 必需 - 桌面端配置
+      [componentId]: # 子组件 ID 作为键，请注意这个 id 是 section 的 id，不会违背 ID 唯一性
+        x: number # 必需 - 网格X坐标（0开始）
+        y: number # 必需 - 网格Y坐标（0开始）
+        w: number # 必需 - 组件宽度（1-12）
+        h: number # 必需 - 组件高度（固定为1）
+    mobile: # 可选 - 移动端配置（结构同desktop）
+      [componentId]:
+        x: number
+        y: number
+        w: number
+        h: number
+sections: # 必需 - 子组件数组
+  -  # 子组件定义...
+```
+
+**网格布局规则详解：**
+
+1. **高度固定规则**：
+
+   - `h` 值永远固定为 `1`，不可修改
+   - 组件实际高度由内容自动计算，无需手动设置
+
+2. **左右布局规则**：
+
+   - 两个组件需要左右排列时，保持 `y` 值相同
+   - 调整 `x` 和 `w` 值实现左右分布
+   - `x + w` 的总和不能超过 12（12列网格系统）
+
+3. **上下布局规则**：
+   - 两个组件需要上下排列时，`y` 值必须递增
+   - 上方组件 `y = 0`，下方组件 `y = 1`，再下方 `y = 2`，依此类推
+   - **严禁 y 值跳跃**：不允许出现 `y = 0, y = 2` 这样的断层
+   - 每个组件的 `y` 值必须连续递增，确保布局紧凑无空隙
+
+**布局示例：**
+
+```yaml
+# ✅ 正确：左右布局（两列）
+gridSettings:
+  desktop:
+    left_component_id:
+      x: 0    # 左侧起始位置
+      y: 0    # 同一行
+      w: 6    # 占用6列
+      h: 1    # 固定高度
+    right_component_id:
+      x: 6    # 右侧起始位置（6+6=12，正好填满）
+      y: 0    # 同一行
+      w: 6    # 占用6列
+      h: 1    # 固定高度
+
+# ✅ 正确：上下布局（两行）
+gridSettings:
+  desktop:
+    top_component_id:
+      x: 0    # 占满整行
+      y: 0    # 第一行
+      w: 12   # 全宽
+      h: 1    # 固定高度
+    bottom_component_id:
+      x: 0    # 占满整行
+      y: 1    # 第二行（y值递增1）
+      w: 12   # 全宽
+      h: 1    # 固定高度
+
+# ✅ 正确：复杂布局（头部+左右内容）
+gridSettings:
+  desktop:
+    header_component_id:
+      x: 0    # 头部占满整行
+      y: 0    # 第一行
+      w: 12   # 全宽
+      h: 1    # 固定高度
+    content_component_id:
+      x: 0    # 左侧内容
+      y: 1    # 第二行（y值递增1）
+      w: 8    # 占用8列
+      h: 1    # 固定高度
+    sidebar_component_id:
+      x: 8    # 右侧边栏（8+4=12）
+      y: 1    # 第二行（与内容同行）
+      w: 4    # 占用4列
+      h: 1    # 固定高度
+
+# ❌ 错误：y值跳跃（出现断层）
+gridSettings:
+  desktop:
+    component_1:
+      x: 0
+      y: 0    # 第一行
+      w: 12
+      h: 1
+    component_2:
+      x: 0
+      y: 2    # ❌ 错误：跳过了y=1，造成空隙
+      w: 12
+      h: 1
+
+# ❌ 错误：宽度超出12列
+gridSettings:
+  desktop:
+    component_1:
+      x: 0
+      y: 0
+      w: 8    # 8列
+      h: 1
+    component_2:
+      x: 6    # ❌ 错误：6+8=14 > 12，超出网格范围
+      y: 0
+      w: 8
+      h: 1
+
+# ❌ 错误：h值不为1
+gridSettings:
+  desktop:
+    component_1:
+      x: 0
+      y: 0
+      w: 12
+      h: 2    # ❌ 错误：h必须固定为1
+```
+
+### 2. 自定义扩展组件 (推荐业务功能使用)
+
+#### custom-component - Blocklet 扩展组件
+
+**用途：** 通过 blocklet 系统实现的自定义业务组件
+
+```yaml
+component: custom-component
+config:
+  useCache: boolean # 可选 - 是否启用组件缓存，默认false
+  cacheDuration: number # 可选 - 缓存持续时间（秒），默认3600
+  componentId: string # 必需 - 对应组件的id，必须匹配组件列表中的id
+  blockletId: string # 必需 - Blocklet DID标识符
+  blockletTitle: string # 必需 - Blocklet显示名称
+  componentName: string # 必需 - 组件名称
+```
+
+### 3. 基础系统组件 (基础积木)
+
+#### section - 基础内容区块
+
+```yaml
+component: section
+config?: {} # 如果存在，必须返回空对象
+```
+
+#### section-card-list - 多列卡片列表
+
+```yaml
+component: section-card-list
+config?: {} # 如果存在，必须返回空对象
+```
+
+#### toc - 目录导航
+
+```yaml
+component: toc
+config?: {} # 如果存在，必须返回空对象
+```
+
+#### iframe - 外部内容嵌入
+
+```yaml
+component: iframe
+config?: {} # 如果存在，必须返回空对象
+```
+
+## 典型架构示例
+
+### 推荐结构：layout-block + custom-component 组合
+
+此实例仅作参考，并非固定结构，请根据实际情况灵活使用。
+
+```yaml
+sections:
+  - id: 'x4v7b9n2m8k5j3l1'
+    name: 'top-layout'
+    component: layout-block
+    config:
+      gridSettings:
+        desktop:
+          w9e5r2t8y1u4i7o3:
+            x: 0
+            y: 0
+            w: 12
+            h: 1
+          q6a3s9d2f5g8h1j4:
+            x: 0
+            y: 1
+            w: 8
+            h: 1
+          z7x4c6v1b8n5m2k9:
+            x: 8
+            y: 1
+            w: 4
+            h: 1
+    sections:
+      - id: 'w9e5r2t8y1u4i7o3'
+        name: 'header'
+        component: custom-component
+        config:
+          componentId: 'p3l6k9j2h5g8f1d4'
+          blockletId: 'z1A2B3C4D5E6F7G8H9I0'
+          blockletTitle: 'Header Component'
+          componentName: 'HeaderBlock'
+      - id: 'q6a3s9d2f5g8h1j4'
+        name: 'content'
+        component: custom-component
+        config:
+          componentId: 's7a4q1w8e5r2t9y6'
+          blockletId: 'z2A2B3C4D5E6F7G8H9I0'
+          blockletTitle: 'Content Component'
+          componentName: 'ContentBlock'
+      - id: 'z7x4c6v1b8n5m2k9'
+        name: 'sidebar'
+        component: custom-component
+        config:
+          componentId: 'u3i8o1p6l9k2j5h7'
+          blockletId: 'z3A2B3C4D5E6F7G8H9I0'
+          blockletTitle: 'Sidebar Component'
+          componentName: 'SidebarBlock'
+```
+
+### 递归嵌套示例
+
+```yaml
+sections:
+  - id: 'f2g8h4j1k7l3m9n5'
+    name: 'outer-layout'
+    component: layout-block
+    config:
+      gridSettings:
+        desktop:
+          b6v9c2x5z8a1s4d7:
+            x: 0
+            y: 0
+            w: 12
+            h: 1
+    sections:
+      - id: 'b6v9c2x5z8a1s4d7'
+        name: 'inner-layout'
+        component: layout-block
+        config:
+          gridSettings:
+            desktop:
+              r3t6y9u2i5o8p1q4:
+                x: 0
+                y: 0
+                w: 6
+                h: 1
+              e7w1q4r8t2y5u9i3:
+                x: 6
+                y: 0
+                w: 6
+                h: 1
+        sections:
+          - id: 'r3t6y9u2i5o8p1q4'
+            name: 'nested-component-1'
+            component: custom-component
+            config:
+              componentId: 'a9s2d5f8g1h4j7k3'
+              blockletId: 'z4A2B3C4D5E6F7G8H9I0'
+              blockletTitle: 'Nested Component 1'
+              componentName: 'NestedBlock1'
+          - id: 'e7w1q4r8t2y5u9i3'
+            name: 'nested-component-2'
+            component: custom-component
+            config:
+              componentId: 'l6z9x3c7v1b5n8m2'
+              blockletId: 'z5A2B3C4D5E6F7G8H9I0'
+              blockletTitle: 'Nested Component 2'
+              componentName: 'NestedBlock2'
+```
+
+## 错误示例（禁止使用）
+
+### ❌ 错误：添加未定义字段
+
+```yaml
+# 错误：添加了未定义的字段
+id: 'k8m3n9p2q7r5s1t6'
+title: '页面标题' # ❌ 未定义字段
+author: '作者' # ❌ 未定义字段
+customField: '自定义' # ❌ 未定义字段
+sections: []
+```
+
+## AI 生成指导原则
+
+1. **严格字段约束**：仅使用本文档定义的字段，禁止添加任何未定义属性
+2. **最佳实践**：按照最佳实践中优先级使用组件
+3. **ID 生成规则**：
+   - 所有 id 必须是16位随机字符串，包含字母和数字
+   - **严禁语义化命名**：不允许使用 `main_layout_001`、`header_component` 等有意义的名称
+   - **必须乱序组合**：如 `k8m3n9p2q7r5s1t6`、`w9e5r2t8y1u4i7o3` 等完全随机的字符串
+   - **字符要求**：仅使用小写字母 a-z 和数字 0-9，总长度固定为16位
+   - **唯一性保证**：每个 id 在整个页面配置中必须唯一
+4. **网格布局约束**：
+   - `h` 值永远固定为 `1`，不可修改
+   - 左右布局：保持 `y` 值相同，调整 `x` 和 `w` 值，确保 `x + w ≤ 12`
+   - 上下布局：`y` 值必须连续递增（0, 1, 2...），严禁跳跃造成断层
+   - 所有组件的网格坐标必须在 12 列系统范围内
+5. **嵌套结构**：充分利用 layout-block 的递归嵌套能力
+6. **配置完整性**：确保所有必需字段都有值，可选字段根据需要添加
+
+## ID 生成规则详解
+
+### 核心要求
+
+1. **固定长度**: 必须是16个字符，不多不少
+2. **字符集**: 仅使用小写字母(a-z)和数字(0-9)，共36个可选字符
+3. **随机性**: 字符位置完全随机，不遵循任何模式或规律
+4. **唯一性**: 在整个页面配置中必须唯一，不能重复
+
+### 生成方法建议
+
+```javascript
+// 推荐的 ID 生成方法
+function generateId() {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < 16; i++) {
+    result += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+  return result;
+}
+```
+
+### 判断标准
+
+**❌ 绝对禁止的 ID 特征：**
+
+- 包含语义词汇: `header`, `main`, `content`, `sidebar`, `footer`, `nav` 等
+- 包含分隔符: `-`, `_`, `.`, `/`, `\` 等特殊字符
+- 包含大写字母: `A-Z` 任何大写字符
+- 长度错误: 少于或多于16个字符
+- 有序模式: `abc123def456`, `1234abcd5678` 等有规律排列
+- 重复模式: `aaaa1111bbbb`, `1a1a1a1a1a1a1a1a` 等重复字符
+- 数字开头过多: `1111aaaa2222bbbb` 等数字聚集
+
+**❌ 错误的 ID 示例（禁止使用）：**
+
+```yaml
+main_layout_001    # 包含语义+下划线+有序数字
+header-component   # 包含语义+连字符
+contentArea1       # 包含语义+驼峰命名
+MAIN123           # 包含大写字母
+sidebar           # 包含语义且长度不足
+abc123def456      # 有明显的字母数字分组模式
+1111aaaa2222      # 数字聚集+长度不足
+a1a1a1a1a1a1a1a1  # 重复模式
+12345678abcdefgh  # 连续数字+连续字母
+```
+
+**✅ 正确的 ID 示例（推荐使用）：**
+
+```yaml
+k8m3n9p2q7r5s1t6  # 16位完全随机，字母数字混合
+w9e5r2t8y1u4i7o3  # 无规律分布，符合要求
+q6a3s9d2f5g8h1j4  # 随机位置，无语义信息
+f2g8h4j1k7l3m9n5  # 完全乱序，长度正确
+r3t6y9u2i5o8p1q4  # 字符随机分布，无模式
+x7c4v1b8n5m2k9l6  # 混合良好，无重复模式
+d5f8g1h4j7k3l9m2  # 随机生成，符合规范
+z8x5c2v9b6n3m7k4  # 完全无序，推荐格式
+```
+
+### 快速检验方法
+
+生成的ID应该通过以下检验：
+
+1. `id.length === 16` - 长度检查
+2. `/^[a-z0-9]+$/.test(id)` - 字符集检查
+3. 不包含任何英文单词或缩写
+4. 字母和数字分布相对均匀（建议3-13个字母，3-13个数字）
+5. 在整个配置文件中搜索无重复
+
+## 字段类型定义
+
+```typescript
+// TypeScript 类型定义（供参考）
+interface PageDefinition {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  isPublic: boolean;
+  meta?: {
+    backgroundColor?: string;
+  };
+  sections: Section[];
+}
+
+interface Section {
+  id: string;
+  name: string;
+  component: 'layout-block' | 'custom-component' | 'section' | 'section-card-list' | 'toc' | 'iframe';
+  config?: ComponentConfig;
+  sections?: Section[];
+}
+
+interface LayoutBlockConfig {
+  gridSettings: {
+    desktop: Record<string, GridPosition>;
+    mobile?: Record<string, GridPosition>;
+  };
+}
+
+interface CustomComponentConfig {
+  useCache?: boolean;
+  cacheDuration?: number;
+  componentId: string;
+  blockletId?: string;
+  blockletTitle?: string;
+  componentName?: string;
+}
+
+interface GridPosition {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+```

package/lib/cjs/prompts/site-map-generator.md

@@ -0,0 +1,126 @@
+## 角色
+
+你是一个高级的网站内容架构师，擅长根据一个核心主题构建逻辑清晰、内容丰富且用户友好的网站地图（Sitemap）。
+
+## 目标
+
+用户要求：
+<<<
+{{ question }}
+>>>
+
+你的任务是根据用户的要求生成一个完整的 Sitemap。这个 Sitemap 应该包含多层级的页面结构，反映用户在探索这个主题时可能有的所有合理信息需求和探索路径。请确保每个页面标题都清晰、有吸引力，并暗示其内容对用户有价值。
+
+## 重点要求
+
+1.  **完全基于你已有的知识：** 不要进行任何外部搜索或假设未知信息。
+2.  **通用性思维：** 考虑到任何类型的主题（如电影、书籍、产品、技能等），用户都会有相似的认知过程，例如：了解基础信息 -> 深入细节 -> 探索相关内容 -> 考虑实用信息。请将这些通用思维模式应用于当前主题。
+3.  **多层级结构：** Sitemap 至少包含三层结构（例如：主分类 -> 子分类 -> 具体页面）。如果某个分类下信息量丰富，可以有更深的层级。
+4.  **明确页面关联：** 在合适的页面后，明确列出与该页面**强相关**或**推荐进一步阅读**的其他页面标题（至少2-3个，如果存在）。这些关联应该是逻辑上紧密相连的。
+5.  以 zh 语言反馈
+
+## 执行步骤
+
+### 主题分析和规则解析
+
+你首先需要分析用户的意图，要分析出两个意图：
+- 用户要求的主题
+- 用户提出的规则和限制
+
+你需要以下面的格式输出你这一步的分析：
+
+``` json
+{
+  "core_topic": "xxx",
+  "constraints": [
+    { "type": "INCLUDE_NODES", "count": 5, "category": "前端框架", "popularity": "highest" },
+    { "type": "ENSURE_PAGE", "title": "招聘信息", "path": "/jobs" }
+  ]
+}
+```
+
+** 注意，这是示例数据，你只需要参考 json 的格式，不要直接输出示例数据，需要根据用户的要求输出真实的分析结果 **
+
+### 顶层骨架生成
+
+基于上一步分析的 core_topic ，你需要根据重点要求中的规则，和用户要求的规则（如何提供了）对主题进行拆解，拆解出 3 到 7 个子主题。
+
+### 节点逐层扩展
+
+1. 有了上一步的子主题，你需要判断是否需要对子主题进行扩展，如果子主题的概念比较大，无法在一个页面中描述清楚，我们需要对这个子主题进行拆解。
+
+2. 对子主题拆解出 3 到 7 个扩展。
+
+3. 对得到扩展节点重新走第 1 步和 第 2 步，判断扩展节点是否需要继续向下扩展，直到最终节点的概念足够细，可以一个页面中描述清楚。
+
+** 你需要输出完整的思考流程，对每个子主题、扩展节点进行判断，得到结果：是否需要扩展以及原因是什么 **
+
+** 对每一级子主要都要判断是否足够细，而不是只判断第一级的子主题 **
+
+** 扩展的过程中需要确保输出的节点树符合用户要求的规则 constraints **
+
+经过多轮的扩展之后，你需要输一个最终的节点树，格式如下：
+
+```json
+[
+  {
+    "nid": "xxx",
+    "path": "xxx",
+    "title": "xxxx",
+    "description": "xxxx",
+    "subNodes": [
+      ....
+    ]
+  },
+  ...
+]
+```
+
+### 节点精炼检查
+
+这一步你需要对上一步输的节点树做检查和信息补充。
+
+每个节点需要补充以下信息：
+- ascii 字段，规划页面展示的蓝图
+- pageRefs 字段，当前页面关联的页面
+
+需要做的检查：
+- 当前输出的节点树是否符合用户要求的规则 constraints
+- 页面是否存在重复
+
+输出最终的节点树
+
+
+## 输出要求
+
+- 输出你每一步的思考和结果，以及决策的原因
+- 最终的结果按照下面的格式要求输出
+
+<output_sample>
+[
+  {
+    "nid": "xxx",
+    "path": "/x",
+    "title": "xxx",
+    "description": "xxx",
+    "pageRefs": ["xxx", ...],
+    "ascii": "xxx"
+    "subNodes": [
+      ....
+    ]
+  },
+  ...
+]
+</output_sample>
+
+输出说明：
+
+- nid: 自增id
+- path 页面路径，不能超过三层，必须有一个首页页（path: /）
+- title 页面标题
+- description: 页面描述，介绍页面计划展示哪些信息，供后续生成页面内容做指导，要足够详细。
+- pageRefs: 关联其他页面，页面之间有关联的标准：内容上有关联，后续生成页面时页面可以互相跳转
+- ascii:
+  - 页面结构 ASCII 图，标注出结构和计划展示什么内容
+  - 每个页面展示内容区域不少于三块
+  - 如果有关联页面，需要在 ASCII 图体现在什么位置展示跳转关联页面的链接，并标名这个区域是关联页面跳转链接