page-agent-sdk 2.35.0 → 2.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.35.0",
+  "version": "2.37.0",
   "type": "module",
   "description": "AI agent SDK for web pages — embed a chat assistant that edits page data via schema-validated tools. A lighter, framework-agnostic alternative to CopilotKit/LangChain for in-page JSON-editing agents. Vue-bundled; works with DeepSeek, OpenAI, MCP.",
   "main": "./dist/page-agent-sdk.umd.cjs",
@@ -29,6 +29,10 @@
       "types": "./types/index.d.ts",
       "import": "./dist/page-agent-sdk.js"
     },
+    "./headless": {
+      "types": "./types/headless.d.ts",
+      "import": "./dist/page-agent-sdk.headless.js"
+    },
     "./style.css": "./dist/style.css"
   },
   "files": [
@@ -42,8 +46,9 @@
     "mcp:probe": "tsx scripts/mcp-probe.ts",
     "proxy:mock": "tsx scripts/proxy-mock-server.ts",
     "verify:probe": "tsx scripts/verify-probe.ts",
-    "build": "npm run build:lib && npm run build:iife",
+    "build": "npm run build:lib && npm run build:headless && npm run build:iife",
     "build:lib": "vite build",
+    "build:headless": "vite build --config vite.headless.config.ts",
     "build:iife": "vite build --config vite.iife.config.ts",
     "preview": "vite preview",
     "test": "tsx src/core/__tests__/selftest.ts",

package/skills/html-builder/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: html-builder
+description: 纯代码组件(custom Vue SFC)生成规范——代码存 vfs+data 引用 / 何时写 / SFC 规范 / 安全底线 / props / 组件库引用 / 可访问性
+---
+
+# 纯代码组件生成规范
+
+> 内置 skill(add-capability-packs)。createHtmlSubagent 默认装进 HTML 子 agent;亦可独立分发,集成方 `defineSkill` 自挂。
+
+## 代码存储约定(重要)
+
+- 代码正文写 vfs:`html/<name>.vue`(如 `html/hero.vue`)
+- data 存引用:`{ type:'custom', codeRef:'vfs://html/<name>.vue', name, props }`
+- 改代码:`vfs_edit` 改 vfs 文件(data 的 `codeRef` 引用不变,无需改 data)
+- 渲染层(集成方契约):遇 `type:'custom'` 组件,读 `data.codeRef` → vfs 取 code → 渲染
+
+## 何时写代码组件
+
+- 组件库**无对应类型**(高度定制交互 / 一次性特效 / 特殊布局)→ 写 custom 代码组件
+- 组件库**已有**(按钮 / 卡片 / 列表)→ 用现有组件配置,不重造
+
+## Vue SFC 规范
+
+- Vue 3 `<template>` + `<script setup>`(组合式)
+- props 用 `defineProps`;事件用 `defineEmits`
+- 只渲染 UI,不做副作用(不发请求 / 不读写 storage)
+
+## props 定义
+
+- 代码组件 `defineProps` 接受外部 data 传入(集成方渲染时按 data 的 `props` 字段传)
+
+## 组件库引用
+
+- 代码内可 import 组件库组件(如 `<Button>`);所用依赖以集成方渲染层已注入为准,不重复造
+
+## 安全底线(必须)
+
+- 禁 `eval` / `new Function` / `Function` 构造器
+- 禁访问 window 敏感属性(`document.cookie` / `apiKey` / `token`)
+- 不引入外部脚本 / CDN
+
+## 可访问性 + 语义化
+
+- 语义化标签(`button` / `nav` / `section`);图片 `alt`;交互可键盘聚焦
+- 颜色对比达标;不只用颜色传达信息
+
+## 提交策略
+
+- 小段代码:`vfs_write` 整体写
+- 大段代码:先 `vfs_write` 建骨架,再 `vfs_edit` 增量拼(避免单次输出超 max_tokens 截断)
+- 删除组件:`vfs_rm` 删 vfs 代码 + `write` 移除 data 引用

package/skills/rag-search/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: rag-search
+description: 多源知识检索策略——vfs 预注入文档 / 语义检索 / 指定文档加载 / 公网,综合结构化结论 + 溯源
+---
+
+# 知识检索策略(RAG)
+
+> 内置 skill(add-capability-packs)。createRagSubagent 默认装进 RAG 子 agent;亦可独立分发,集成方 `defineSkill` 自挂。
+
+## 多源决策树
+
+- **vfs_grep / vfs_read**:搜集成方预注入 vfs 的文档(组件文档 / UI 规范)—— 快、静态,先查
+- **search_docs**:语义检索(retriever 向量库)—— 模糊匹配,关键词不确定 / 语义相似时用
+- **load_doc**:按 source 精确加载(已知文档 id / URL / key)—— 精确取特定文档
+- **fetch_document**:公网 URL —— 查公开资料
+
+## 综合规范
+
+- 多源交叉验证(关键结论优先 ≥2 源印证,或单一权威源)
+- 标注来源(文档名 / URL / 段落),便于溯源
+- 结构化、可执行结论(组件清单 + 各自 props 约束 + 适用场景),不堆原文
+- 未检索到明确说「未检索到」,不编造;建议替代方案(改关键词 / 建议写代码组件等)
+
+## 何时用何源
+
+- 静态文档(组件库文档 / UI 规范):`vfs_grep`
+- 语义相似(「瀑布流组件」「倒计时」「拼团」):`search_docs`
+- 已知文档 id / URL:`load_doc`
+- 公开 URL(设计规范网站 / 第三方文档):`fetch_document`
+
+## 多轮检索
+
+- 单源不够时换源或换关键词重试(如 `search_docs` 没命中 → `vfs_grep` 换词)
+- 扩大 `topK` 增加召回(噪声多时收小)
+- 检索充分即综合结论,不过度检索