page-agent-sdk 2.42.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +4 -4
  2. package/README.zh-CN.md +4 -4
  3. package/dist/page-agent-sdk.headless.js +3460 -3074
  4. package/dist/page-agent-sdk.iife.js +214 -153
  5. package/dist/page-agent-sdk.js +4182 -3796
  6. package/dist/page-agent-sdk.umd.cjs +157 -96
  7. package/package.json +1 -1
  8. package/skills/html-builder/SKILL.md +15 -10
  9. package/skills/html-fragment/SKILL.md +56 -0
  10. package/types/headless.d.ts +31 -0
  11. package/types/index.d.ts +31 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "page-agent-sdk",
3
- "version": "2.42.0",
3
+ "version": "3.0.0",
4
4
  "type": "module",
5
5
  "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.",
6
6
  "main": "./dist/page-agent-sdk.umd.cjs",
package/skills/html-builder/SKILL.md CHANGED
@@ -1,18 +1,22 @@
1
1
  ---
2
2
  name: html-builder
3
- description: 纯代码组件(custom Vue SFC)生成规范——代码存 vfs+data 引用 / 何时写 / SFC 规范 / 安全底线 / props / 组件库引用 / 可访问性
3
+ description: 纯代码组件(custom Vue SFC)生成规范——代码作为 data 资产 / vfs 工作副本 / 何时写 / SFC 规范 / 安全底线 / props / 组件库引用 / 可访问性
4
4
  ---
5
5
 
6
6
  # 纯代码组件生成规范
7
7
 
8
- > 内置 skill(add-capability-packs)。createHtmlSubagent 默认装进 HTML 子 agent;亦可独立分发,集成方 `defineSkill` 自挂。
8
+ > 内置 skill(createHtmlSubagent 单模式 code-as-data-asset)。createHtmlSubagent 默认装进 HTML 子 agent;亦可独立分发,集成方 `defineSkill` 自挂。
9
9
 
10
- ## 代码存储约定(重要)
10
+ ## 代码资产模型(重要)
11
11
 
12
- - 代码正文写 vfs:`html/<name>.vue`(如 `html/hero.vue`)
13
- - data 存引用:`{ type:'custom', codeRef:'vfs://html/<name>.vue', name, props }`
14
- - 改代码:`vfs_edit` 改 vfs 文件(data 的 `codeRef` 引用不变,无需改 data)
15
- - 渲染层(集成方契约):遇 `type:'custom'` 组件,读 `data.codeRef` → vfs 取 code → 渲染
12
+ - 代码正文是 data 的 `code` 字段(资产,随 data json 进服务端 DB);UI 绑 `data.code` 渲染
13
+ - vfs 是编辑工作副本:框架自动 checkout(`data.code`→vfs 按 `__pgId`)/ commit(vfs→`data.code`),你只改 vfs
14
+ - `__pgId` 框架管(read 看不到、write 写不进),别碰
15
+
16
+ ## 两条工作路径
17
+
18
+ - **修改已有组件**:必经 vfs(`vfs_read` → `vfs_edit` 增量改 → `validate_code`);勿直接 `write data.code`
19
+ - **新建组件**:`write({patch:{op:'set',jsonPath:'components.N',value:{name,code,props}}})` —— code 直接进 data,框架补 `__pgId`
16
20
 
17
21
  ## 何时写代码组件
18
22
 
@@ -46,6 +50,7 @@ description: 纯代码组件(custom Vue SFC)生成规范——代码存 vfs+data
46
50
 
47
51
  ## 提交策略
48
52
 
49
- - 小段代码:`vfs_write` 整体写
50
- - 大段代码:先 `vfs_write` 建骨架,再 `vfs_edit` 增量拼(避免单次输出超 max_tokens 截断)
51
- - 删除组件:`vfs_rm` 删 vfs 代码 + `write` 移除 data 引用
53
+ - **新建组件**:`write` data(`code` 字段直接进,框架补 `__pgId`)
54
+ - **修改组件**:必经 vfs —— `vfs_read` 看现状 → `vfs_edit` 增量改(不 `vfs_write` 重写整个文件,防丢既有内容);框架 afterAgent 自动 commit 回写 `data.code`
55
+ - 大段代码:`vfs_edit` 增量拼(避免单次输出超 max_tokens 截断)
56
+ - 删除组件:`write` del `components.N`(data 项移除 → 框架 afterAgent 孤儿清理删 vfs 工作副本)
package/skills/html-fragment/SKILL.md ADDED
@@ -0,0 +1,56 @@
1
+ ---
2
+ name: html-fragment
3
+ description: 纯 HTML 片段(v-html 注入)生成规范——代码作为 data 资产 / vfs 工作副本 / 无外围标签 / 单根元素 / 标签闭合 / validate_code 自检 / 安全底线 / 可访问性
4
+ ---
5
+
6
+ # HTML 片段生成规范
7
+
8
+ > 内置 skill(createHtmlSubagent 单模式 code-as-data-asset)。`createHtmlSubagent({ codeKind:'html' })` 默认装进 HTML 子 agent(v-html 注入场景);亦可独立分发,集成方 `defineSkill` 自挂。与 `html-builder`(Vue SFC 形态)对称。
9
+
10
+ ## 代码资产模型(重要)
11
+
12
+ - 代码正文是 data 的 `code` 字段(资产,随 data json 进服务端 DB);UI 绑 `data.code` 经 v-html 渲染
13
+ - vfs 是编辑工作副本:框架自动 checkout(`data.code`→vfs 按 `__pgId`)/ commit(vfs→`data.code`),你只改 vfs
14
+ - `__pgId` 框架管(read 看不到、write 写不进),别碰
15
+
16
+ ## 两条工作路径
17
+
18
+ - **修改已有组件**:必经 vfs(`vfs_read` → `vfs_edit` 增量改 → `validate_code`);勿直接 `write data.code`
19
+ - **新建组件**:`write({patch:{op:'set',jsonPath:'components.N',value:{name,code,props}}})` —— code 直接进 data,框架补 `__pgId`
20
+
21
+ ## 输出契约(必须)
22
+
23
+ - 输出经 **v-html 注入**宿主页面的 HTML 片段:**不要** `<!DOCTYPE>`,**不要** `<html>` / `<head>` / `<body>` 外围标签,只输出内容片段本身
24
+ - **单根元素**包裹(如 `<section class="hero">…</section>`),语义化标签
25
+ - **不写 `<script>`**(v-html 注入不执行脚本,且有安全风险);交互交宿主页面已有机制
26
+ - 样式用片段内 `<style>`,class **统一加前缀**防冲突(如 `.pg-hero-…`)
27
+ - 不引入外部脚本 / CDN / 外链样式
28
+
29
+ ## 标签闭合(必须)
30
+
31
+ - 非自闭合标签必须成对闭合(`<img>` / `<br>` / `<input>` 等 void 元素除外)
32
+ - 每次生成/修改后调 `validate_code` 自检,报错用 `vfs_edit` 修正后复查,直到通过
33
+ - `validate_code` 也会被返回前门禁(verify beforeReturn)二次扫一次,不通过会回灌自纠
34
+
35
+ ## 何时写 HTML 片段
36
+
37
+ - 组件库**无对应类型**(高度定制布局 / 一次性专题页 / 特殊视觉效果)→ 写 HTML 片段
38
+ - 组件库**已有**(按钮 / 卡片 / 列表)→ 用现有组件配置,不重造
39
+
40
+ ## 安全底线(必须)
41
+
42
+ - 禁 `eval` / `new Function` / `Function` 构造器
43
+ - 禁访问 window 敏感属性(`document.cookie` / `apiKey` / `token`)
44
+ - 不引入外部脚本 / CDN
45
+
46
+ ## 可访问性 + 语义化
47
+
48
+ - 语义化标签(`button` / `nav` / `section`);图片 `alt`;交互可键盘聚焦
49
+ - 颜色对比达标;不只用颜色传达信息
50
+
51
+ ## 提交策略
52
+
53
+ - **新建组件**:`write` data(`code` 字段直接进,框架补 `__pgId`)
54
+ - **修改组件**:必经 vfs —— `vfs_read` 看现状 → `vfs_edit` 增量改(不 `vfs_write` 重写整个文件,防丢既有内容);框架 afterAgent 自动 commit 回写 `data.code`
55
+ - 大段代码:`vfs_edit` 增量拼(避免单次输出超 max_tokens 截断)
56
+ - 删除组件:`write` del `components.N`(data 项移除 → 框架 afterAgent 孤儿清理删 vfs 工作副本)
package/types/headless.d.ts CHANGED
@@ -255,6 +255,8 @@ export interface SubagentConfig {
255
255
  allowedTools?: string[];
256
256
  middleware?: any[];
257
257
  summarization?: boolean | any;
258
+ /** beforeReturn 自纠上限(默认 0 = 关闭);>0 时返回前跑中间件 beforeReturn 钩子(如 verify 格式门禁),feedback 回灌自纠。配 verify 类中间件时必开 */
259
+ maxVerifyAttempts?: number;
258
260
  }
259
261
  export interface AgentInfo {
260
262
  id: string;
@@ -952,6 +954,8 @@ export interface ChatSdk {
952
954
  importData(json: any, opts?: { validate?: boolean; emit?: boolean }): { ok: boolean; error?: string };
953
955
  /** 往 vfs 异步注入/更新文件(RAG 文档池 / HTML 代码等);content 字符串直存,对象 JSON.stringify。与 vfs_write 工具一致语义(集成方侧命令式入口) */
954
956
  vfsWrite(path: string, content: string | object): void;
957
+ /** 只读读取 vfs 文件内容(集成方渲染层按 data.codeRef 取代码渲染 custom 组件;文件不存在返 undefined)。与 vfs_read 工具一致语义,命令式入口(不经工具调用/无工具开销) */
958
+ vfsRead(path: string): string | undefined;
955
959
  /** 创建/注册受保护资源(返回 handle);需配 data.resources + vfsStore,否则抛错 */
956
960
  createResource(path: string, value?: unknown): string;
957
961
  /** 取受保护资源真值(by path 或 handle);不存在返 undefined */
@@ -1385,10 +1389,37 @@ export interface CreateHtmlSubagentOptions {
1385
1389
  temperature?: number;
1386
1390
  skills?: SkillSpec[];
1387
1391
  extraTools?: any[];
1392
+ /** 代码形态:'sfc'(默认,Vue SFC)/ 'html'(纯 HTML 片段,v-html 注入场景) */
1393
+ codeKind?: 'sfc' | 'html';
1394
+ /** 输出格式校验(validate_code 工具 + verify beforeReturn 门禁);默认 true */
1395
+ formatCheck?: boolean;
1396
+ /** 子 agent 收口(afterAgent,verify 门禁通过后)一次性回调,传代码区全部文件 {path:content};集成方据此把代码同步进 data bind(响应式驱动渲染),无需 hook vfs 工具事件 */
1397
+ onComplete?: (files: Record<string, string>) => void;
1388
1398
  [k: string]: any;
1389
1399
  }
1390
1400
  export declare function createRagSubagent(options: CreateRagSubagentOptions): SubagentConfig;
1391
1401
  export declare function createHtmlSubagent(options: CreateHtmlSubagentOptions): SubagentConfig;
1402
+ export interface HtmlFormatIssue {
1403
+ /** 行号(1 基) */
1404
+ line: number;
1405
+ /** 问题码:UNCLOSED_TAG / STRAY_CLOSE_TAG / UNCLOSED_COMMENT / DOCTYPE_IN_FRAGMENT / DOC_TAG_IN_FRAGMENT / SCRIPT_IN_FRAGMENT */
1406
+ code: string;
1407
+ message: string;
1408
+ }
1409
+ export interface ValidateHtmlFormatOptions {
1410
+ /** Vue SFC 模式:允许 <script>(SFC 自有块);默认 false = 纯 HTML 片段(禁 <script>) */
1411
+ sfc?: boolean;
1412
+ }
1413
+ /** HTML 格式校验(标签闭合 + v-html 片段契约);纯函数,node/浏览器通用(集成方渲染层纵深防御可复用) */
1414
+ export declare function validateHtmlFormat(source: string, opts?: ValidateHtmlFormatOptions): HtmlFormatIssue[];
1415
+ /** HTML void 元素集合(无需闭合标签;validateHtmlFormat 用,集成方可复用) */
1416
+ export declare const HTML_VOID_TAGS: Set<string>;
1417
+ export interface HtmlFormatCheckOptions {
1418
+ /** vfs 代码路径前缀(与 createHtmlSubagent 的 codeVfsPrefix 一致);默认 'html/' */
1419
+ vfsPrefix?: string;
1420
+ }
1421
+ /** HTML 格式 verify check(beforeReturn 门禁):扫 state.files 代码文件,不通过回灌 feedback 自纠 */
1422
+ export declare function createHtmlFormatCheck(opts?: HtmlFormatCheckOptions): VerifyCheck;
1392
1423
 
1393
1424
  // checkpoint / dataOps / permissions
1394
1425
  export interface CheckpointDeps { [k: string]: any }
package/types/index.d.ts CHANGED
@@ -251,6 +251,8 @@ export interface SubagentConfig {
251
251
  middleware?: any[];
252
252
  /** 跨轮上下文压缩;true=默认索引摘要(零 LLM),或 SummarizationOptions 自配(含 llmInvoke 升级)。不传=不装 */
253
253
  summarization?: boolean | any;
254
+ /** beforeReturn 自纠上限(默认 0 = 关闭);>0 时返回前跑中间件 beforeReturn 钩子(如 verify 格式门禁),feedback 回灌自纠。配 verify 类中间件时必开 */
255
+ maxVerifyAttempts?: number;
254
256
  }
255
257
  export interface AgentInfo {
256
258
  id: string;
@@ -968,6 +970,8 @@ export interface ChatSdk {
968
970
  importData(json: any, opts?: { validate?: boolean; emit?: boolean }): { ok: boolean; error?: string };
969
971
  /** 往 vfs 异步注入/更新文件(RAG 文档池 / HTML 代码等);content 字符串直存,对象 JSON.stringify。与 vfs_write 工具一致语义(集成方侧命令式入口) */
970
972
  vfsWrite(path: string, content: string | object): void;
973
+ /** 只读读取 vfs 文件内容(集成方渲染层按 data.codeRef 取代码渲染 custom 组件;文件不存在返 undefined)。与 vfs_read 工具一致语义,命令式入口(不经工具调用/无工具开销) */
974
+ vfsRead(path: string): string | undefined;
971
975
  /** 创建/注册受保护资源(返回 handle);需配 data.resources + vfsStore,否则抛错 */
972
976
  createResource(path: string, value?: unknown): string;
973
977
  /** 取受保护资源真值(by path 或 handle);不存在返 undefined */
@@ -1401,10 +1405,37 @@ export interface CreateHtmlSubagentOptions {
1401
1405
  temperature?: number;
1402
1406
  skills?: SkillSpec[];
1403
1407
  extraTools?: any[];
1408
+ /** 代码形态:'sfc'(默认,Vue SFC)/ 'html'(纯 HTML 片段,v-html 注入场景) */
1409
+ codeKind?: 'sfc' | 'html';
1410
+ /** 输出格式校验(validate_code 工具 + verify beforeReturn 门禁);默认 true */
1411
+ formatCheck?: boolean;
1412
+ /** 子 agent 收口(afterAgent,verify 门禁通过后)一次性回调,传代码区全部文件 {path:content};集成方据此把代码同步进 data bind(响应式驱动渲染),无需 hook vfs 工具事件 */
1413
+ onComplete?: (files: Record<string, string>) => void;
1404
1414
  [k: string]: any;
1405
1415
  }
1406
1416
  export declare function createRagSubagent(options: CreateRagSubagentOptions): SubagentConfig;
1407
1417
  export declare function createHtmlSubagent(options: CreateHtmlSubagentOptions): SubagentConfig;
1418
+ export interface HtmlFormatIssue {
1419
+ /** 行号(1 基) */
1420
+ line: number;
1421
+ /** 问题码:UNCLOSED_TAG / STRAY_CLOSE_TAG / UNCLOSED_COMMENT / DOCTYPE_IN_FRAGMENT / DOC_TAG_IN_FRAGMENT / SCRIPT_IN_FRAGMENT */
1422
+ code: string;
1423
+ message: string;
1424
+ }
1425
+ export interface ValidateHtmlFormatOptions {
1426
+ /** Vue SFC 模式:允许 <script>(SFC 自有块);默认 false = 纯 HTML 片段(禁 <script>) */
1427
+ sfc?: boolean;
1428
+ }
1429
+ /** HTML 格式校验(标签闭合 + v-html 片段契约);纯函数,node/浏览器通用(集成方渲染层纵深防御可复用) */
1430
+ export declare function validateHtmlFormat(source: string, opts?: ValidateHtmlFormatOptions): HtmlFormatIssue[];
1431
+ /** HTML void 元素集合(无需闭合标签;validateHtmlFormat 用,集成方可复用) */
1432
+ export declare const HTML_VOID_TAGS: Set<string>;
1433
+ export interface HtmlFormatCheckOptions {
1434
+ /** vfs 代码路径前缀(与 createHtmlSubagent 的 codeVfsPrefix 一致);默认 'html/' */
1435
+ vfsPrefix?: string;
1436
+ }
1437
+ /** HTML 格式 verify check(beforeReturn 门禁):扫 state.files 代码文件,不通过回灌 feedback 自纠 */
1438
+ export declare function createHtmlFormatCheck(opts?: HtmlFormatCheckOptions): VerifyCheck;
1408
1439
 
1409
1440
  // checkpoint / dataOps / permissions
1410
1441
  export interface CheckpointDeps { [k: string]: any }