page-agent-sdk 2.43.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 +2949 -2782
  4. package/dist/page-agent-sdk.iife.js +173 -160
  5. package/dist/page-agent-sdk.js +3979 -3812
  6. package/dist/page-agent-sdk.umd.cjs +116 -103
  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 +4 -0
  11. package/types/index.d.ts +4 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "page-agent-sdk",
3
- "version": "2.43.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
@@ -954,6 +954,8 @@ export interface ChatSdk {
954
954
  importData(json: any, opts?: { validate?: boolean; emit?: boolean }): { ok: boolean; error?: string };
955
955
  /** 往 vfs 异步注入/更新文件(RAG 文档池 / HTML 代码等);content 字符串直存,对象 JSON.stringify。与 vfs_write 工具一致语义(集成方侧命令式入口) */
956
956
  vfsWrite(path: string, content: string | object): void;
957
+ /** 只读读取 vfs 文件内容(集成方渲染层按 data.codeRef 取代码渲染 custom 组件;文件不存在返 undefined)。与 vfs_read 工具一致语义,命令式入口(不经工具调用/无工具开销) */
958
+ vfsRead(path: string): string | undefined;
957
959
  /** 创建/注册受保护资源(返回 handle);需配 data.resources + vfsStore,否则抛错 */
958
960
  createResource(path: string, value?: unknown): string;
959
961
  /** 取受保护资源真值(by path 或 handle);不存在返 undefined */
@@ -1391,6 +1393,8 @@ export interface CreateHtmlSubagentOptions {
1391
1393
  codeKind?: 'sfc' | 'html';
1392
1394
  /** 输出格式校验(validate_code 工具 + verify beforeReturn 门禁);默认 true */
1393
1395
  formatCheck?: boolean;
1396
+ /** 子 agent 收口(afterAgent,verify 门禁通过后)一次性回调,传代码区全部文件 {path:content};集成方据此把代码同步进 data bind(响应式驱动渲染),无需 hook vfs 工具事件 */
1397
+ onComplete?: (files: Record<string, string>) => void;
1394
1398
  [k: string]: any;
1395
1399
  }
1396
1400
  export declare function createRagSubagent(options: CreateRagSubagentOptions): SubagentConfig;
package/types/index.d.ts CHANGED
@@ -970,6 +970,8 @@ export interface ChatSdk {
970
970
  importData(json: any, opts?: { validate?: boolean; emit?: boolean }): { ok: boolean; error?: string };
971
971
  /** 往 vfs 异步注入/更新文件(RAG 文档池 / HTML 代码等);content 字符串直存,对象 JSON.stringify。与 vfs_write 工具一致语义(集成方侧命令式入口) */
972
972
  vfsWrite(path: string, content: string | object): void;
973
+ /** 只读读取 vfs 文件内容(集成方渲染层按 data.codeRef 取代码渲染 custom 组件;文件不存在返 undefined)。与 vfs_read 工具一致语义,命令式入口(不经工具调用/无工具开销) */
974
+ vfsRead(path: string): string | undefined;
973
975
  /** 创建/注册受保护资源(返回 handle);需配 data.resources + vfsStore,否则抛错 */
974
976
  createResource(path: string, value?: unknown): string;
975
977
  /** 取受保护资源真值(by path 或 handle);不存在返 undefined */
@@ -1407,6 +1409,8 @@ export interface CreateHtmlSubagentOptions {
1407
1409
  codeKind?: 'sfc' | 'html';
1408
1410
  /** 输出格式校验(validate_code 工具 + verify beforeReturn 门禁);默认 true */
1409
1411
  formatCheck?: boolean;
1412
+ /** 子 agent 收口(afterAgent,verify 门禁通过后)一次性回调,传代码区全部文件 {path:content};集成方据此把代码同步进 data bind(响应式驱动渲染),无需 hook vfs 工具事件 */
1413
+ onComplete?: (files: Record<string, string>) => void;
1410
1414
  [k: string]: any;
1411
1415
  }
1412
1416
  export declare function createRagSubagent(options: CreateRagSubagentOptions): SubagentConfig;