page-agent-sdk 2.36.0 → 2.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "page-agent-sdk",
-  "version": "2.36.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",

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` 增加召回(噪声多时收小)
+- 检索充分即综合结论,不过度检索

package/types/headless.d.ts

@@ -223,6 +223,9 @@ export interface SubagentConfig {
   maxToolRounds?: number;
   /** 子 agent 可写路径前缀白名单(给子 agent 写权限;写工具包 path guard,越界 PATH_OUT_OF_SCOPE;整体 set 禁)。subagent-writable Phase 2 */
   writablePaths?: string[];
+  allowedTools?: string[];
+  middleware?: any[];
+  summarization?: boolean | any;
 }
 export interface AgentInfo {
   id: string;
@@ -902,6 +905,8 @@ export interface ChatSdk {
   exportData(): any;
   /** 导入数据整体替换主数据 bind(就地还原,保留 reactive 引用);默认经 schema 校验,不合法返回 {ok:false,error};opts.validate:false 跳过校验,opts.emit:false 不发 data_change */
   importData(json: any, opts?: { validate?: boolean; emit?: boolean }): { ok: boolean; error?: string };
+  /** 往 vfs 异步注入/更新文件(RAG 文档池 / HTML 代码等);content 字符串直存,对象 JSON.stringify。与 vfs_write 工具一致语义(集成方侧命令式入口) */
+  vfsWrite(path: string, content: string | object): void;
   /** 创建/注册受保护资源(返回 handle);需配 data.resources + vfsStore,否则抛错 */
   createResource(path: string, value?: unknown): string;
   /** 取受保护资源真值(by path 或 handle);不存在返 undefined */
@@ -1300,6 +1305,42 @@ export interface SubagentOptions {
 }
 export interface SubagentLlmConfig { [k: string]: any }
 
+// 能力包(专用子 agent 工厂):RAG 多源检索 + HTML 代码组件生成(add-capability-packs)
+export interface RagHit { content: string; source?: string; score?: number }
+export interface RagRetrieveOptions { topK?: number }
+export type RagRetriever = (query: string, opts?: RagRetrieveOptions) => Promise<RagHit[]>;
+export type RagLoader = (source: string) => Promise<RagHit | RagHit[]>;
+export interface CreateRagSubagentOptions {
+  retriever?: (query: string, opts?: RagRetrieveOptions) => Promise<RagHit[]>;
+  loader?: (source: string) => Promise<RagHit | RagHit[]>;
+  useVfs?: boolean;
+  id?: string;
+  description?: string;
+  topK?: number;
+  searchToolName?: string;
+  loadToolName?: string;
+  maxToolRounds?: number;
+  summarization?: boolean | any;
+  skills?: SkillSpec[];
+  extraTools?: any[];
+  [k: string]: any;
+}
+export interface CreateHtmlSubagentOptions {
+  writablePaths: string[];
+  codeVfsPrefix?: string;
+  id?: string;
+  description?: string;
+  planning?: boolean;
+  summarization?: boolean | any;
+  maxToolRounds?: number;
+  temperature?: number;
+  skills?: SkillSpec[];
+  extraTools?: any[];
+  [k: string]: any;
+}
+export declare function createRagSubagent(options: CreateRagSubagentOptions): SubagentConfig;
+export declare function createHtmlSubagent(options: CreateHtmlSubagentOptions): SubagentConfig;
+
 // checkpoint / dataOps / permissions
 export interface CheckpointDeps { [k: string]: any }
 export interface DataAuditEntry { [k: string]: any }

package/types/index.d.ts

@@ -216,6 +216,12 @@ export interface SubagentConfig {
   maxToolRounds?: number;
   /** 子 agent 可写路径前缀白名单(给子 agent 写权限;写工具包 path guard,越界 PATH_OUT_OF_SCOPE;整体 set 禁)。subagent-writable Phase 2 */
   writablePaths?: string[];
+  /** 从主 allTools 额外拿的工具名(追加到默认只读白名单);如 ['vfs_grep','vfs_write'] */
+  allowedTools?: string[];
+  /** 子 agent 自定义中间件(如 createTodosMiddleware 给规划能力) */
+  middleware?: any[];
+  /** 跨轮上下文压缩;true=默认索引摘要(零 LLM),或 SummarizationOptions 自配(含 llmInvoke 升级)。不传=不装 */
+  summarization?: boolean | any;
 }
 export interface AgentInfo {
   id: string;
@@ -909,6 +915,8 @@ export interface ChatSdk {
   exportData(): any;
   /** 导入数据整体替换主数据 bind(就地还原,保留 reactive 引用);默认经 schema 校验,不合法返回 {ok:false,error};opts.validate:false 跳过校验,opts.emit:false 不发 data_change */
   importData(json: any, opts?: { validate?: boolean; emit?: boolean }): { ok: boolean; error?: string };
+  /** 往 vfs 异步注入/更新文件(RAG 文档池 / HTML 代码等);content 字符串直存,对象 JSON.stringify。与 vfs_write 工具一致语义(集成方侧命令式入口) */
+  vfsWrite(path: string, content: string | object): void;
   /** 创建/注册受保护资源(返回 handle);需配 data.resources + vfsStore,否则抛错 */
   createResource(path: string, value?: unknown): string;
   /** 取受保护资源真值(by path 或 handle);不存在返 undefined */
@@ -1307,6 +1315,42 @@ export interface SubagentOptions {
 }
 export interface SubagentLlmConfig { [k: string]: any }
 
+// 能力包(专用子 agent 工厂):RAG 多源检索 + HTML 代码组件生成(add-capability-packs)
+export interface RagHit { content: string; source?: string; score?: number }
+export interface RagRetrieveOptions { topK?: number }
+export type RagRetriever = (query: string, opts?: RagRetrieveOptions) => Promise<RagHit[]>;
+export type RagLoader = (source: string) => Promise<RagHit | RagHit[]>;
+export interface CreateRagSubagentOptions {
+  retriever?: (query: string, opts?: RagRetrieveOptions) => Promise<RagHit[]>;
+  loader?: (source: string) => Promise<RagHit | RagHit[]>;
+  useVfs?: boolean;
+  id?: string;
+  description?: string;
+  topK?: number;
+  searchToolName?: string;
+  loadToolName?: string;
+  maxToolRounds?: number;
+  summarization?: boolean | any;
+  skills?: SkillSpec[];
+  extraTools?: any[];
+  [k: string]: any;
+}
+export interface CreateHtmlSubagentOptions {
+  writablePaths: string[];
+  codeVfsPrefix?: string;
+  id?: string;
+  description?: string;
+  planning?: boolean;
+  summarization?: boolean | any;
+  maxToolRounds?: number;
+  temperature?: number;
+  skills?: SkillSpec[];
+  extraTools?: any[];
+  [k: string]: any;
+}
+export declare function createRagSubagent(options: CreateRagSubagentOptions): SubagentConfig;
+export declare function createHtmlSubagent(options: CreateHtmlSubagentOptions): SubagentConfig;
+
 // checkpoint / dataOps / permissions
 export interface CheckpointDeps { [k: string]: any }
 export interface DataAuditEntry { [k: string]: any }