page-agent-sdk 4.8.2 → 4.9.0

package/README.md

@@ -251,7 +251,7 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
 | **Capability packs** (2.37+) | `subagents` | `createRagSubagent({retriever?,loader?,useVfs?})` / `createHtmlSubagent({writablePaths?,codeVfsPrefix?,codeField?,orchestratorPrompt?,formatCheck?,craftNotes?,design?})` (3.9+ usually no need to declare one — createChatSdk auto-registers a default HTML subagent at assembly; declare explicitly only to customize codeField/formatCheck etc.; open schemas / nested containers / dotted codeField need an explicit value) | Specialized subagent factories — **RAG**: multi-source retrieval (semantic `search_docs` / async `load_doc` / vfs / fetch), read-only, independent context; **HTML**: code-component generation — **code as a data asset** (code lives in `data.<writablePath>[i].code`, persisted with the data JSON; vfs is an edit working copy). The framework auto-checks-out (data.code→vfs by `__pgId`) before the subagent runs and auto-commits (vfs→data.code, direct bind mutation — no snapshot stack) after; the main agent is transparent (main-scope read sees a `<code Nkb>` summary). New components via `write`; edits via `vfs_edit` on the working copy. `codeField` (default `'code'`, nested jsonPath like `'props.html_code'` for open-schema platforms; + assembly-time hit-check warns on wrong path); main-agent orchestration **auto-injected** at assembly (3.9+ zero-config: a default HTML subagent is **auto-registered** when no explicit one exists and the schema has a code array — no switch needed, info logged; opt out prompt-only via `orchestratorPrompt:false`); model advice: prefer strong instruction-following models (deepseek-v4/claude/gpt-4o) for html codegen — flash-class amplifies over-thinking; **craft notes `craftNotes`** (on by default): the html subagent's final reply `[note]` lines are persisted to the component's `__pgNotes` (travels with the data JSON), and injected via the file map on the next delegation to that component ("handoff from the previous maintainer": design decisions / user feedback / pitfalls) — design intent persists across delegations; opt out via `craftNotes:false`; **built-in design-taste skill `design`** (4.7+ mounted by default): vendors ConardLi garden-skills `web-design-engineer` (MIT) — declare-the-design-system-first / anti-AI-cliché rules / oklch palettes / 25 named style recipes (linear/apple-hig/muji…), progressive disclosure (33K main doc + 29 references enter context only on load_skill); complements the html-fragment skill (taste vs. mechanics); `design:false` disables / pass a SkillSpec to replace; `formatCheck` on by default = `validate_code` self-check + verify beforeReturn gate with feedback self-correction; `validateHtmlFormat` exported. **Breaking (3.0)**: removed `onComplete`/`codeRef`/`codeSnapshots` — migrate `codeRef`→`code` field, drop `onComplete`/mirror. Composable/splitable, opt-in, ship with `rag-search`/`html-builder` skills. Plus `sdk.vfsWrite(path,content)` for async doc injection. See [doc/usage-guide.md](doc/usage-guide.md#capability-packs) |
 | **Subagent observability** (2.38+) | — | `inspect().subagent.{active,history}` / `sdk.{getActiveSubagents,subagentHistory}` | active/history runtime state + DebugDrawer "🤖 subagent" tab (follows `subagent` capability, session-level, not persisted) |
 | **Context** | `contextPreset` | `'auto' \| 'conservative' \| 'aggressive' \| 'complex'` · default `auto` | Compression preset (`complex` for multi-step / large-JSON / long-workflow tasks) |
-| | `contextOptions` | `Partial<ContextManagerOptions> \| false` | Fine params (`false` disables compression). Includes `promptSoftCapTokens` (3.11+ compression cost cap — 160K default when window ≥320K, explicit `0` disables) and `preserveLastToolResults` (default `['describe_data','describe_data']` — keep field descriptions in compressed summary) |
+| | `contextOptions` | `Partial<ContextManagerOptions> \| false` | Fine params (`false` disables compression). Includes `promptSoftCapTokens` (3.11+ compression cost cap — 160K default when window ≥320K, explicit `0` disables) and `preserveLastToolResults` (default `['schema_data','read']` — keep field descriptions in compressed summary) |
 | | `summaryLlm` | `BaseChatModel \| LLMConfig` | Summary-dedicated LLM (defaults to main `llm`) |
 | | `maxMemoryRounds` | `number` · default `30` | Dialog history memory round cap (`0` disables trim) |
 | | `staleReadInvalidation` | `boolean` · default `true` | 3.42+ write-driven stale read invalidation: within one invoke's ReAct window, old `read`/`query_data`/`search_data` results hit by a later successful write are replaced with an invalidation placeholder (keeps the model from answering state from stale snapshots; anti-thrash copy references the write's own new value/hash). `false` = off for main + subagent stacks |
@@ -308,7 +308,7 @@ createChatSdk({ subagents: [
 
 ### Built-in tools (Agent-callable)
 
-- **data ops** (all 10 tools always exposed): `read` (list/get/describe merged) / `write` (set/edit/delete merged + auto optimistic lock + auto snapshot) — recommended; `restore_data` / `history_data` (snapshot rollback/history); `describe_data` / `schema_data` / `diff_data` / focus tools (low-level CRUD `get_data`/`set_data`/`edit_data`/`delete_data` removed in 4.0 — `read`/`write` cover everything)
+- **data ops** (all 9 tools always exposed): `read` (list/get/describe merged; omitting jsonPath returns overall description + format) / `write` (set/edit/delete merged + auto optimistic lock + auto snapshot) — recommended; `restore_data` / `history_data` (snapshot rollback/history); `schema_data` / `diff_data` / focus tools (low-level CRUD `get_data`/`set_data`/`edit_data`/`delete_data` removed in 4.0; `describe_data` removed in 4.9 — fully equivalent to `read` without jsonPath, 0 calls across three consecutive real-LLM baselines)
 - **window query**: `query_data` (JSONPath) / `search_data` (fuzzy) / `eval_script` (sandboxed)
 - **fetch**: `fetch_document`
 - **vfs**: `vfs_read` / `vfs_write` / `vfs_edit` / `vfs_ls` / `vfs_glob` / `vfs_grep`

package/README.zh-CN.md

@@ -247,7 +247,7 @@ ChatDialog, MessageContent, CodePreview, SkillPanel, DebugDrawer, useChat
 | **能力包** (2.37+) | `subagents` | `createRagSubagent({retriever?,loader?,useVfs?})` / `createHtmlSubagent({writablePaths?,codeVfsPrefix?,codeField?,orchestratorPrompt?,formatCheck?,craftNotes?,design?})`(3.9+ 通常无需显式声明 —— createChatSdk 装配期自动装配默认 HTML 子 agent;显式传仅用于定制 codeField/formatCheck 等;开放 schema/嵌套容器/点路径 codeField 需显式传) | 专用子 agent 工厂 —— **RAG**:多源检索(语义 `search_docs` / 异步 `load_doc` / vfs / fetch),只读,独立上下文;**HTML**:代码组件生成 —— **代码作为 data 资产**(代码存 `data.<writablePath>[i].code`,随 data json 持久化;vfs 作编辑工作副本)。框架自动 checkout(data.code→vfs 按 `__pgId`)/ commit(vfs→data.code,直改 bind,不进快照栈),主 agent 透明(主 scope read 见 `<code Nkb>` 摘要)。新建走 `write`;修改走 `vfs_edit` 工作副本。`codeField`(默认 `'code'`,嵌套 jsonPath 如 `'props.html_code'` 适配开放 schema 平台;+ 装配期命中校验填错路径 onWarning);主 agent 编排**装配期自适应注入**(3.9+ 零配置:无显式 html 子 agent + schema 含 code 数组→**自动装配默认 HTML 子 agent**(无开关,info 留痕);有显式子 agent→委派;`orchestratorPrompt:false` opt-out);模型建议:html 代码生成推荐强指令模型(deepseek-v4/claude/gpt-4o),flash 类放大过度思考;**工匠笔记 `craftNotes`**(默认开):子 agent 收口回复 `[note]` 行沉淀为组件 `__pgNotes`(随 data 持久化),下次委派同组件经文件地图注入「前任的交接」(设计决策/用户反馈/踩坑)—— 同组件跨委派设计意图持续,`craftNotes:false` 关闭;**内置设计品味 skill `design`**(4.7+ 默认挂载):vendored ConardLi garden-skills `web-design-engineer`(MIT)—— 设计系统先声明 / 反 AI 俗套 / oklch 配色 / 25 风格配方(linear/apple-hig/muji…),渐进披露(33K 主文 + 29 参考只在 load_skill 时进上下文);与 html-fragment 规范 skill 分工并列(品味 vs 落地);`design:false` 关闭 / 传 SkillSpec 替换;`formatCheck` 默认开 = `validate_code` 自检 + verify beforeReturn 门禁回灌自纠;`validateHtmlFormat` 导出。**Breaking(3.0)**:去 `onComplete`/`codeRef`/`codeSnapshots` —— 迁移 `codeRef`→`code` 字段,去 `onComplete`/镜像。可组合/拆分,opt-in,随 `rag-search`/`html-builder` skill 分发。另 `sdk.vfsWrite(path,content)` 异步注入文档。见 [doc/usage-guide.md](doc/usage-guide.md#能力包) |
 | **子 agent 观察层** (2.38+) | — | `inspect().subagent.{active,history}` / `sdk.{getActiveSubagents,subagentHistory}` | active/history 运行态 + DebugDrawer「🤖 子 agent」tab(随 `subagent` 能力开,会话级不持久化) |
 | **上下文** | `contextPreset` | `'auto' \| 'conservative' \| 'aggressive' \| 'complex'` · 默认 `auto` | 压缩预设档位（`complex` 面向多步 / 大 JSON / 长流程编排任务） |
-| | `contextOptions` | `Partial<ContextManagerOptions> \| false` | 细参覆盖（`false` 关压缩）。含 `promptSoftCapTokens`（3.11+ 压缩触发成本上限,窗口 ≥320K 默认 160K、显式 0 关）与 `preserveLastToolResults`（默认 `['describe_data','describe_data']`——压缩摘要里保留字段说明） |
+| | `contextOptions` | `Partial<ContextManagerOptions> \| false` | 细参覆盖（`false` 关压缩）。含 `promptSoftCapTokens`（3.11+ 压缩触发成本上限,窗口 ≥320K 默认 160K、显式 0 关）与 `preserveLastToolResults`（默认 `['schema_data','read']`——压缩摘要里保留字段说明） |
 | | `summaryLlm` | `BaseChatModel \| LLMConfig` | 摘要专用 LLM（不配用主 `llm`） |
 | | `maxMemoryRounds` | `number` · 默认 `30` | 对话历史内存上限轮次（`0` 关裁剪） |
 | | `staleReadInvalidation` | `boolean` · 默认 `true` | 3.42+ 写驱动过期读失效：单次 invoke 窗口内，后续成功写击中路径的旧 `read`/`query_data`/`search_data` 结果替换为失效占位（防模型凭旧快照答状态；占位引用写结果自带新值/hash 防 thrash）。`false` = 主/子栈一致关闭 |
@@ -306,7 +306,7 @@ createChatSdk({ subagents: [
 
 ### 内置工具（Agent 可调用）
 
-- **数据操作**（10 工具恒全暴露）：`read`（合并 describe/get）/ `write`（合并 set/edit/delete + 自动乐观锁 + 自动快照）—— 推荐；`restore_data` / `history_data`（快照回退/查历史）；`describe_data` / `schema_data` / `diff_data` / focus 工具族（底层 CRUD `get_data`/`set_data`/`edit_data`/`delete_data` 已于 4.0 移除，`read`/`write` 全覆盖）
+- **数据操作**（9 工具恒全暴露）：`read`（合并 describe/get，不传 jsonPath 返回整体说明+格式）/ `write`（合并 set/edit/delete + 自动乐观锁 + 自动快照）—— 推荐；`restore_data` / `history_data`（快照回退/查历史）；`schema_data` / `diff_data` / focus 工具族（底层 CRUD `get_data`/`set_data`/`edit_data`/`delete_data` 已于 4.0 移除；`describe_data` 已于 4.9 移除，与 read 不传 jsonPath 完全等价、真 LLM 基线连续三版 0 调用）
 - **window 查询**：`query_data`（JSONPath）/ `search_data`（模糊搜索）/ `eval_script`（沙箱脚本）
 - **抓取**：`fetch_document`
 - **DOM 检视**（`capabilities.domInspect`，opt-in）：`get_dom`（常驻）+ `dom_search` / `dom_info`（经内置 `dom-inspect` skill 按需注入 —— `load_skill("dom-inspect")` 激活；skills 关时降级直插）