@opentiny/next-sdk 0.3.1 → 0.3.3-alpha.1

package/dist/page-tools/a11y-tree.d.ts

@@ -0,0 +1,103 @@
+/**
+ * a11y-tree.ts
+ *
+ * 浏览器内语义化 ARIA 树生成器（重构版）
+ *
+ * 核心改进：
+ * 1. 两阶段处理：buildVNode（构建中间树）→ serializeVNode（剪枝序列化）
+ * 2. 统一剪枝规则：无 ref 且无 accessible name → 透明穿透（跳过本节点，保留子节点）
+ *    - 兼顾操作场景（去掉 generic/list/listitem 噪音）
+ *    - 兼顾内容理解场景（有 name 的 listitem 等节点保留）
+ * 3. 修复全局可变状态：refCounter 改为局部对象，消除并发调用隐患
+ *
+ * 依赖：
+ *   - dom-accessibility-api: W3C AccName 规范 JS 实现（计算 accessible name）
+ *   - tabbable: 可交互/可聚焦元素检测（工业级，处理所有边界情况）
+ */
+/** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
+export type RefMap = Map<number, HTMLElement>;
+export interface A11yTreeOptions {
+    /**
+     * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
+     * 默认 true（推荐）
+     */
+    pruneUnnamed?: boolean;
+    /**
+     * 强制保留的角色列表，即使无 name 也不穿透（优先级最高）
+     * 例如：['table', 'row'] 用于保留表格结构
+     */
+    preserveRoles?: string[];
+}
+export interface A11yTreeResult {
+    /** 语义化 YAML 文本（供 AI 阅读和 Diff 计算） */
+    yaml: string;
+    /** ref 索引 → HTMLElement 映射（供后续操作使用） */
+    refMap: RefMap;
+    /** 可交互元素总数 */
+    interactiveCount: number;
+    /** 原始行数组（不含 yaml 代码块包裹），供搜索使用 */
+    lines: string[];
+}
+/** 关键词搜索选项 */
+export interface SearchA11yTreeOptions extends A11yTreeOptions {
+    /**
+     * 每个匹配行前后保留的上下文行数（类似 grep -C N）
+     * 默认 2
+     */
+    contextLines?: number;
+    /**
+     * 是否大小写不敏感，默认 true
+     */
+    caseInsensitive?: boolean;
+    /**
+     * 最大返回匹配分组数（防止命中过多撑爆上下文），默认 20
+     */
+    maxMatches?: number;
+}
+/** 单个匹配分组 */
+export interface A11ySearchMatch {
+    /** 主命中行行号（1-based） */
+    lineNumber: number;
+    /** 主命中行内容 */
+    line: string;
+    /** 含上下文的行列表（带行号） */
+    context: Array<{
+        lineNumber: number;
+        line: string;
+    }>;
+}
+/** searchA11yTree 返回值 */
+export interface SearchA11yTreeResult {
+    /** 格式化后可直接发给 LLM 的文本 */
+    text: string;
+    /** 结构化匹配列表 */
+    matches: A11ySearchMatch[];
+    /** 无障碍树总行数 */
+    totalLines: number;
+    /** 原始命中行数（去重前） */
+    matchCount: number;
+}
+/**
+ * 生成当前页面的语义化 ARIA YAML 树
+ *
+ * @param root 遍历起点，默认 document.body
+ * @param blacklist 需要跳过的元素（用户自定义黑名单）
+ * @param whitelist 需要识别为可交互的白名单元素列表
+ * @param options 过滤选项
+ */
+export declare function buildA11yTree(root?: Element, blacklist?: Element[], whitelist?: Element[], options?: A11yTreeOptions): A11yTreeResult;
+/**
+ * 在无障碍树中按关键词搜索，返回带行号的匹配结果和上下文
+ *
+ * 支持的搜索维度（均对同一个 query 字符串做包含匹配）：
+ *   - role：如 `button`、`link`、`heading`
+ *   - accessible name：节点的语义化名称（引号内文本）
+ *   - state token：如 `checked`、`disabled`、`expanded`
+ *   - ref 索引：如 `#5`
+ *
+ * @example
+ *   searchA11yTree('button')    // 找全部按钮
+ *   searchA11yTree('提交')      // 找名称含"提交"的节点
+ *   searchA11yTree('#3')        // 找 ref #3
+ */
+export declare function searchA11yTree(query: string, root?: Element, blacklist?: Element[], whitelist?: Element[], options?: SearchA11yTreeOptions): SearchA11yTreeResult;

package/dist/page-tools/bridge.d.ts

@@ -131,10 +131,4 @@ export type RegisterPageToolByHandlersOptions = {
     handlers: PageToolHandlers;
 };
 export declare function registerPageTool(options: RegisterPageToolByHandlersOptions): () => void;
-/**
- * 建立浏览器原生或 polyfill 与 next-sdk 页面工具桥接的联系。
- * 若用户或第三方库直接操作 navigator.modelContext 进行工具注册，
- * 我们通过此函数进行拦截劫持，并同步到 next-sdk 的握手线路 (MSG_TOOL_REGISTERED / MSG_TOOL_UNREGISTERED)，
- * 从而保证无论浏览器是否原生支持，均能正常完成 WebMCP 握手交互。
- */
 export declare function setupModelContextBridge(): void;

package/dist/page-tools/initialize-builtin-WebMCP.d.ts

@@ -0,0 +1 @@
+export declare const initializeBuiltinWebMCP: () => void;

package/dist/page-tools/page-agent-tool.d.ts

@@ -0,0 +1,9 @@
+declare global {
+    interface Window {
+        __webmcpcli_interactiveWhitelist?: Element[];
+        __webmcpcli_interactiveBlacklist?: Element[];
+        __webmcpcli_beforeGetBrowserState?: (() => void) | null;
+    }
+}
+/** 在浏览器页面中注册 page-agent-tool, 用于页面的内容获取和操作，页面的动效 */
+export declare function registerPageAgentTool(): void;

package/dist/page-tools/page-state-cache.d.ts

@@ -0,0 +1,36 @@
+/**
+ * page-state-cache.ts
+ *
+ * 页面状态 Diff 缓存模块
+ * - 缓存上一次 buildA11yTree 生成的 YAML 文本
+ * - 每次操作后计算 diff，只返回 +/- 变化行，大幅节省 Token
+ */
+export interface PageSnapshot {
+    url: string;
+    yaml: string;
+}
+export interface DiffResult {
+    /** 是否为全量刷新（首次加载或 URL 变化） */
+    isFullRefresh: boolean;
+    /** 上一次的 URL（用于拼接 URL 变化提示） */
+    prevUrl: string;
+    /** 新增行数 */
+    addedLines: number;
+    /** 删除行数 */
+    removedLines: number;
+    /** 只含 +/- 行的 diff 文本（不含相同行，节省 Token） */
+    diffText: string;
+}
+export declare class PageStateCache {
+    private prev;
+    /** URL 变化或首次调用时，需要全量输出 */
+    isFullRefresh(currentUrl: string): boolean;
+    /**
+     * 更新缓存并返回 diff 结果
+     * @param url 当前页面 URL
+     * @param yaml 当前 YAML 树文本
+     */
+    update(url: string, yaml: string): DiffResult;
+    /** 强制清空缓存（页面刷新 / 手动重置场景） */
+    invalidate(): void;
+}

package/dist/skills/index.d.ts

@@ -15,41 +15,36 @@ export interface SkillMeta {
 /**
  * 从主 SKILL.md 的 YAML front matter 中用正则提取 name、description
  */
-export declare function parseSkillFrontMatter(content: string): {
+export declare function parseSkillFrontMatter(content: string | (() => Promise<string>)): Promise<{
     name: string;
     description: string;
-} | null;
+} | null>;
 /**
  * 获取所有「主 SKILL.md」的路径（一级子目录下的 SKILL.md）
  * - 对传入的 modules 先做 normalize，兼容任意 import.meta.glob 写法
  */
-export declare function getMainSkillPaths(modules: Record<string, string>): string[];
+export declare function getMainSkillPaths(modules: Record<string, string | (() => Promise<string>)>): Promise<string[]>;
 /**
  * 获取所有技能的概况列表（name、description、path），用于 systemPrompt 或列表展示
  * - 内部统一对 modules 做 normalize，避免调用方关心路径细节
  */
-export declare function getSkillOverviews(modules: Record<string, string>): SkillMeta[];
+export declare function getSkillOverviews(modules: Record<string, string | (() => Promise<string>)>): Promise<SkillMeta[]>;
 /**
  * 格式化为大模型 systemPrompt 可用的技能说明文本
  * @param skills 不传则需由调用方传入从 getSkillOverviews 得到的结果
  */
 export declare function formatSkillsForSystemPrompt(skills: SkillMeta[]): string;
-/**
- * 获取所有已加载的技能文件路径（含主 SKILL.md 与 reference 下的 .md/.json/.xml 等）
- * - 对 modules 做 normalize 后再返回 key 列表
- */
-export declare function getSkillMdPaths(modules: Record<string, string>): string[];
 /**
  * 根据相对路径获取某个技能文档的原始内容（支持 .md、.json、.xml 等文本格式）
  * - 自动对 modules 做 normalize，再按 path 查找
  */
-export declare function getSkillMdContent(modules: Record<string, string>, path: string): string | undefined;
+export declare function getSkillMdContent(modules: Record<string, string | (() => Promise<string>)>, path: string): Promise<string | undefined>;
 /**
  * 根据技能 name 查找其主 SKILL.md 的路径
  * 支持匹配目录名（如 ecommerce）或 SKILL.md 内 frontmatter 定义的 name
  * - 依赖 getMainSkillPaths，内部已做 normalize
  */
-export declare function getMainSkillPathByName(modules: Record<string, string>, name: string): string | undefined;
+export declare function getMainSkillPathByName(modules: Record<string, string | (() => Promise<string>)>, name: string): Promise<string | undefined>;
 /** AI SDK Tool 类型，用于 extraTools 合并，不写死泛型避免与 ai 包版本强绑定 */
 export type SkillToolsSet = Record<string, any>;
 /**
@@ -57,4 +52,4 @@ export type SkillToolsSet = Record<string, any>;
  * - get_skill_content: 按技能名或路径获取完整文档内容，便于大模型自动识别并加载技能
  * remoter 可将返回的 tools 合并进 extraTools 注入 agent
  */
-export declare function createSkillTools(modules: Record<string, string>): SkillToolsSet;
+export declare function createSkillTools(modules: Record<string, string | (() => Promise<string>)>): SkillToolsSet;