pi-to-chrome 0.1.2

package/tool-registry.ts

@@ -0,0 +1,48 @@
+/**
+ * tool-registry - Data-driven tool registration
+ *
+ * Replaces the ~120-line registerChromeTools() function with a declarative loop.
+ * New tools only need: add to ALL_TOOLS array.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ToolDefinition } from './core/types';
+import type { ConsoleBuffer } from './console-buffer';
+import { ensureConnection, getActivePage } from './core/browser';
+
+import { findElementsTool } from './tools/find-elements';
+import { inspectStylesTool } from './tools/inspect-styles';
+// import { takeScreenshotTool } from './tools/take-screenshot';
+import { readConsoleTool } from './tools/read-console';
+import { executeJsTool } from './tools/execute-js';
+
+const ALL_TOOLS: ToolDefinition[] = [
+  findElementsTool,
+  inspectStylesTool,
+  // takeScreenshotTool,
+  readConsoleTool,
+  executeJsTool,
+];
+
+export function registerTools(pi: ExtensionAPI, consoleBuffer: ConsoleBuffer): string[] {
+  const names: string[] = [];
+
+  for (const tool of ALL_TOOLS) {
+    pi.registerTool({
+      name: tool.name,
+      label: tool.label,
+      description: tool.description,
+      promptSnippet: tool.promptSnippet,
+      promptGuidelines: tool.promptGuidelines,
+      parameters: tool.parameters,
+      async execute(toolCallId, params, signal, onUpdate, ctx) {
+        await ensureConnection();
+        const page = await getActivePage();
+        return tool.execute(page, params, { consoleBuffer });
+      }
+    });
+    names.push(tool.name);
+  }
+
+  return names;
+}

package/tools/execute-js.ts

@@ -0,0 +1,69 @@
+/**
+ * chrome_execute_js - Execute JavaScript in the page context
+ *
+ * Uses IIFE wrapper to support both expressions and statements.
+ */
+
+import type { ToolDefinition } from '../core/types';
+import { Type } from '@sinclair/typebox';
+
+export const executeJsTool: ToolDefinition<{ expression: string }> = {
+  name: 'chrome_execute_js',
+  label: 'Chrome Execute JS',
+  description: '在页面上下文中执行 JavaScript 表达式，用于查询 DOM 状态、获取计算样式、测量元素尺寸等。',
+  promptSnippet: '在页面上下文中执行 JavaScript',
+  promptGuidelines: [
+    '【获取精确数据的工具】当你需要元素的精确数值（offsetHeight、scrollHeight、getBoundingClientRect、scrollTop 等）时，用 chrome_execute_js 获取，不要猜测。',
+    '调试布局问题时的常用查询：检查 scrollHeight vs clientHeight（判断是否溢出）、遍历父容器链的 overflow/display/height（定位高度约束断裂点）。',
+    '可以用 JSON.stringify() 包裹返回值来获取可读输出。',
+    '注意：代码中不能使用 const/let 等块级声明语句，请用 var 或 IIFE 包裹。例：JSON.stringify((function(){ var x = 1; return x })())'
+  ],
+  parameters: Type.Object({
+    expression: Type.String({ description: 'JavaScript code to execute' })
+  }),
+  async execute(page, params) {
+    // Wrap in IIFE: expression-body for simple values, block-body for statements
+    //   `(() => location.href)()`          → expression, returns value directly
+    //   `(() => { const x = 1; return x; })()`  → block, supports return/multi-line
+    const trimmed = params.expression.trim();
+    // If it starts with { or a statement keyword, use block form
+    // 语句: return, const, let, var, if, for, while, try, switch, throw, function, class
+    const statementKeywords = ['return ', 'const ', 'let ', 'var ', 'if ', 'for ', 'while ', 'try ', 'switch ', 'throw ', 'function ', 'class ', 'async '];
+    const isBlock = trimmed.startsWith('{') || statementKeywords.some(kw => trimmed.startsWith(kw));
+    const wrappedCode = isBlock
+      ? `(() => { ${params.expression} })()`
+      : `(() => ${params.expression})()`;
+
+    try {
+      const result = await page.evaluate(wrappedCode);
+
+      // Serialize result
+      let serializedResult: string;
+      let rawResult = result;
+
+      if (result === undefined) {
+        serializedResult = 'undefined';
+      } else if (result === null) {
+        serializedResult = 'null';
+      } else if (typeof result === 'string') {
+        serializedResult = result.length > 5000 ? result.slice(0, 5000) + '...' : result;
+      } else if (typeof result === 'number' || typeof result === 'boolean') {
+        serializedResult = String(result);
+      } else if (Array.isArray(result)) {
+        serializedResult = `Array(${result.length})`;
+      } else if (typeof result === 'object') {
+        serializedResult = 'Object';
+      } else {
+        serializedResult = JSON.stringify(result)?.slice(0, 5000) || String(result);
+      }
+
+      return {
+        content: [{ type: 'text', text: serializedResult }],
+        details: { raw: rawResult }
+      };
+
+    } catch (error: any) {
+      throw new Error(error.message);
+    }
+  }
+};

package/tools/find-elements.ts

@@ -0,0 +1,337 @@
+/**
+ * chrome_find_elements v2 - Search for elements by text keywords
+ *
+ * New matching: Tier 1 (id/text-exact) > Tier 2 (class/attr) > Tier 3 (text-substr/tag)
+ * Deduplication keeps deepest descendants, discards ancestors.
+ * Selector is guaranteed unique via CSS path + nth-child fallback.
+ */
+
+import type { ToolDefinition } from '../core/types';
+import { Type } from '@sinclair/typebox';
+
+const DEBUG = false;
+
+export const findElementsTool: ToolDefinition<{ text: string }> = {
+  name: 'chrome_find_elements',
+  label: 'Chrome Find Elements',
+  description: '搜索当前页面上的元素。关键词同时匹配文本、class、id、标签名等，智能排序返回最相关的结果。',
+  promptSnippet: '按关键词搜索页面元素',
+  promptGuidelines: [
+    '【定位元素的第一步】当你需要调试页面问题时，先用 chrome_find_elements 找到目标元素的 CSS selector，再用 chrome_inspect_styles 查看它的样式层叠链。',
+    'text 参数用 / 分隔中英文关键词，尽量多给变体。例：「灯泡」→ "灯泡/lamp/bulb/light"',
+    '拆成小词提高命中：「命令卡片列表」→ "命令卡片/命令/卡片/list/card/command"',
+    '返回的 selector 可直接用于 chrome_inspect_styles 和 chrome_execute_js。'
+  ],
+  parameters: Type.Object({
+    text: Type.String({
+      description: '搜索关键词，/ 分隔多关键词（OR）。同时匹配文本、class、id、标签名等。'
+    })
+  }),
+
+  async execute(page, params) {
+    if (!params.text || params.text.trim().length === 0) {
+      throw new Error('请提供搜索关键词');
+    }
+
+    const keywords = params.text
+      .split('/')
+      .map(k => k.trim().toLowerCase())
+      .filter(k => k.length > 0);
+
+    if (keywords.length === 0) {
+      throw new Error('请提供搜索关键词');
+    }
+
+    const results = await page.evaluate(
+      (keywords: string[], debug: boolean) => {
+        // ╔══════════════════════════════════════════════╗
+        // ║  Browser-side: no external vars, no imports ║
+        // ╚══════════════════════════════════════════════╝
+
+        // ─── Types (inline) ───────────────────────────
+        interface MatchResult {
+          tier: 1 | 2 | 3;
+          matchedBy: string;
+          matchedKeyword: string;
+        }
+
+        interface MatchWithEl {
+          el: Element;
+          match: MatchResult;
+          area: number;
+          y: number;
+        }
+
+        interface FindElementResult {
+          selector: string;
+          tag: string;
+          id: string | null;
+          classes: string[];
+          text: string;
+          ancestors: string;
+          rect: { x: number; y: number; w: number; h: number } | null;
+          _debug?: {
+            tier: number;
+            matchedBy: string;
+            matchedKeyword: string;
+            area: number;
+          };
+        }
+
+        // ─── isVisible ─────────────────────────────────
+        function isVisible(el: Element): boolean {
+          if (el.tagName === 'BODY') return true;
+          if ((el as HTMLElement).offsetParent === null) return false;
+          const rect = el.getBoundingClientRect();
+          if (rect.width === 0 || rect.height === 0) return false;
+          return true;
+        }
+
+        // ─── matchElement ──────────────────────────────
+        function matchElement(el: Element, keywords: string[]): MatchResult | null {
+          let bestTier = 99;
+          let matchedBy = '';
+          let matchedKeyword = '';
+
+          const textContent = (el.textContent || '').trim().toLowerCase();
+          const idLower = el.id.toLowerCase();
+          const tagLower = el.tagName.toLowerCase();
+          const classes = Array.from(el.classList);
+          const SKIP_ATTRS = ['aria-label', 'title', 'placeholder', 'alt'];
+
+          for (const keyword of keywords) {
+            // ── Tier 1: 精准 ──
+            if (idLower.includes(keyword)) {
+              if (1 < bestTier) {
+                bestTier = 1;
+                matchedBy = 'id:' + el.id;
+                matchedKeyword = keyword;
+              }
+            }
+            if (textContent === keyword) {
+              if (1 < bestTier) {
+                bestTier = 1;
+                matchedBy = 'text-exact';
+                matchedKeyword = keyword;
+              }
+            }
+
+            // ── Tier 2: 语义 ──
+            if (bestTier > 2) {
+              for (const cls of classes) {
+                if (cls.toLowerCase().includes(keyword)) {
+                  if (2 < bestTier) {
+                    bestTier = 2;
+                    matchedBy = 'class:' + cls;
+                    matchedKeyword = keyword;
+                  }
+                }
+              }
+            }
+
+            if (bestTier > 2) {
+              for (const attr of SKIP_ATTRS) {
+                const val = el.getAttribute(attr);
+                if (val && val.toLowerCase().includes(keyword)) {
+                  if (2 < bestTier) {
+                    bestTier = 2;
+                    matchedBy = 'attr:' + attr;
+                    matchedKeyword = keyword;
+                  }
+                }
+              }
+            }
+
+            // ── Tier 3: 模糊 ──
+            if (textContent.includes(keyword)) {
+              if (3 < bestTier) {
+                bestTier = 3;
+                matchedBy = 'text-substr';
+                matchedKeyword = keyword;
+              }
+            }
+            if (tagLower === keyword) {
+              if (3 < bestTier) {
+                bestTier = 3;
+                matchedBy = 'tag:' + tagLower;
+                matchedKeyword = keyword;
+              }
+            }
+          }
+
+          return bestTier === 99 ? null : { tier: bestTier as 1 | 2 | 3, matchedBy, matchedKeyword };
+        }
+
+        // ─── deduplicate ───────────────────────────────
+        function deduplicate(matches: MatchWithEl[]): MatchWithEl[] {
+          return matches.filter(m =>
+            !matches.some(n => n !== m && m.el.contains(n.el))
+          );
+        }
+
+        // ─── rank ──────────────────────────────────────
+        function rank(matches: MatchWithEl[]): void {
+          matches.sort((a, b) => {
+            const tierDiff = a.match.tier - b.match.tier;
+            if (tierDiff !== 0) return tierDiff;
+            if (a.area !== b.area) return a.area - b.area;
+            return a.y - b.y;
+          });
+        }
+
+        // ─── buildAncestorPath ──────────────────────────
+        function buildAncestorPath(el: Element): string {
+          const parts: string[] = [];
+          let current = el.parentElement;
+          let count = 0;
+          while (current && current !== document.body && count < 5) {
+            let s = current.tagName.toLowerCase();
+            if (current.id) {
+              s += '#' + current.id;
+            }
+            const cls = Array.from(current.classList).slice(0, 3);
+            if (cls.length > 0) {
+              s += '.' + cls.join('.');
+            }
+            parts.push(s);
+            current = current.parentElement;
+            count++;
+          }
+          return parts.join(' > ');
+        }
+
+        // ─── buildSelector ──────────────────────────────
+        function buildSelector(el: Element): string {
+          const tag = el.tagName.toLowerCase();
+          const allClasses = Array.from(el.classList);
+
+          // Strategy 1: id
+          if (el.id) {
+            const candidate = '#' + el.id;
+            if (document.querySelectorAll(candidate).length === 1) {
+              return candidate;
+            }
+          }
+
+          // Strategy 2: tag + all classes
+          if (allClasses.length > 0) {
+            const candidate = tag + '.' + allClasses.join('.');
+            if (document.querySelectorAll(candidate).length === 1) {
+              return candidate;
+            }
+          }
+
+          // Strategy 3: ancestor path
+          const path: string[] = [
+            tag + (allClasses.length > 0 ? '.' + allClasses.join('.') : '')
+          ];
+          let current = el.parentElement;
+          while (current && current !== document.body) {
+            let level = current.tagName.toLowerCase();
+            if (current.id) {
+              level += '#' + current.id;
+            }
+            const cls = Array.from(current.classList);
+            if (cls.length > 0) {
+              level += '.' + cls.join('.');
+            }
+            path.unshift(level);
+            const candidate = path.join(' > ');
+            if (document.querySelectorAll(candidate).length === 1) {
+              return candidate;
+            }
+            current = current.parentElement;
+          }
+
+          // Strategy 4: nth-child fallback
+          if (!el.parentElement) {
+            return tag;
+          }
+          const parentChildren = el.parentElement.children;
+          const index = Array.from(parentChildren).indexOf(el) + 1;
+          return path.join(' > ') + ':nth-child(' + index + ')';
+        }
+
+        // ─── buildResult ───────────────────────────────
+        function buildResult(el: Element, matchInfo: MatchResult, debug: boolean): FindElementResult {
+          const rect = el.getBoundingClientRect();
+          const result: FindElementResult = {
+            selector: buildSelector(el),
+            tag: el.tagName.toLowerCase(),
+            id: el.id || null,
+            classes: Array.from(el.classList).slice(0, 10),
+            text: (el.textContent || '').trim().slice(0, 80),
+            ancestors: buildAncestorPath(el),
+            rect: {
+              x: Math.round(rect.x),
+              y: Math.round(rect.y),
+              w: Math.round(rect.width),
+              h: Math.round(rect.height)
+            }
+          };
+
+          if (debug) {
+            result._debug = {
+              tier: matchInfo.tier,
+              matchedBy: matchInfo.matchedBy,
+              matchedKeyword: matchInfo.matchedKeyword,
+              area: Math.round(rect.width * rect.height)
+            };
+          }
+
+          return result;
+        }
+
+        // ─── searchElements (main entry) ───────────────
+        function searchElements(keywords: string[]): FindElementResult[] {
+          const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'LINK', 'META', 'HEAD', 'NOSCRIPT']);
+          const matches: MatchWithEl[] = [];
+
+          const walker = document.createTreeWalker(
+            document.body,
+            NodeFilter.SHOW_ELEMENT,
+            null
+          );
+
+          let node: Node | null = walker.currentNode;
+          while (node) {
+            const el = node as Element;
+            if (!SKIP_TAGS.has(el.tagName)) {
+              const match = matchElement(el, keywords);
+              if (match !== null && isVisible(el)) {
+                const rect = el.getBoundingClientRect();
+                matches.push({ el, match, area: rect.width * rect.height, y: rect.y });
+                // 截断保护：大页面避免后续 deduplicate O(n²) 过慢
+                if (matches.length > 500) break;
+              }
+            }
+            node = walker.nextNode();
+          }
+
+          // 截断保护触发时，先粗排再截断，保留高质量结果
+          if (matches.length > 500) {
+            rank(matches);
+            matches.length = 500;
+          }
+
+          const deduped = deduplicate(matches);
+          rank(deduped);
+
+          const top15 = deduped.slice(0, 15);
+          return top15.map(m => buildResult(m.el, m.match, debug));
+        }
+
+        return searchElements(keywords);
+      },
+      keywords,
+      DEBUG
+    );
+
+    const summary = `找到 ${results.length} 个匹配「${params.text}」的元素`;
+
+    return {
+      content: [{ type: 'text', text: summary }],
+      details: { total: results.length, results }
+    };
+  }
+};

package/tools/inspect-styles.ts

@@ -0,0 +1,204 @@
+/**
+ * chrome_inspect_styles - Inspect CSS cascade for an element
+ *
+ * Gets matched CSS rules through CDP's CSS.getMatchedStylesForNode API.
+ */
+
+import type { ToolDefinition } from '../core/types';
+import { Type } from '@sinclair/typebox';
+
+export const inspectStylesTool: ToolDefinition<{
+  selector: string;
+  includeChildren?: boolean;
+}> = {
+  name: 'chrome_inspect_styles',
+  label: 'Chrome Inspect Styles',
+  description: '查看元素的完整 CSS 样式层叠链：包括 inline style、class 样式、user-agent 样式，以及每条规则的来源文件和优先级。',
+  promptSnippet: '查看元素的 CSS 样式层叠链',
+  promptGuidelines: [
+    '【调试布局问题的核心工具】当元素显示异常（溢出、滚动条不出现、尺寸不对、布局错乱）时，立即用 chrome_inspect_styles 检查该元素及其父容器的样式层叠链，确认 inline style 是否覆盖了 CSS 规则、overflow 是否被意外设为 hidden 等。',
+    '调试滚动条问题时：依次检查 滚动容器 → 父容器 → 祖先容器的 overflow、display、height、flex 属性，定位哪一层断了高度约束链。',
+    '返回结果会按优先级排列（inline > CSS class > user-agent），注意 inline style 会覆盖 CSS 文件中的规则。',
+    '指定 CSS selector 来定位元素，例如 "#dashboardContainer"、".command-list"、"div > .card"。'
+  ],
+  parameters: Type.Object({
+    selector: Type.String({ description: 'CSS selector of the element to inspect' }),
+    includeChildren: Type.Optional(Type.Boolean({ description: 'Include direct children list', default: false }))
+  }),
+  async execute(page, params) {
+    let cdpSession: any = null;
+
+    try {
+      // Create CDP session for this page
+      cdpSession = await page.createCDPSession();
+
+      // Enable DOM and CSS agents
+      await cdpSession.send('DOM.enable');
+      await cdpSession.send('CSS.enable');
+
+      // Get document and find node
+      const { root } = await cdpSession.send('DOM.getDocument', { depth: 0 });
+      const { nodeId } = await cdpSession.send('DOM.querySelector', {
+        selector: params.selector,
+        nodeId: root.nodeId
+      });
+
+      if (!nodeId) {
+        throw new Error(`未找到匹配 "${params.selector}" 的元素`);
+      }
+
+      // Get element info
+      const { node: nodeInfo } = await cdpSession.send('DOM.describeNode', { nodeId });
+
+      // Get bounding rect
+      const boundingRect = await page.evaluate((sel: string) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const r = el.getBoundingClientRect();
+        return { x: r.x, y: r.y, width: r.width, height: r.height };
+      }, params.selector);
+
+      // Get text content (truncated)
+      const textContent = await page.evaluate((sel: string) => {
+        const el = document.querySelector(sel);
+        return (el?.textContent || '').trim().slice(0, 200);
+      }, params.selector);
+
+      // Build element info
+      const elementInfo = {
+        tagName: nodeInfo.localName?.toLowerCase() || 'unknown',
+        text: textContent,
+        classList: nodeInfo.attributes
+          ? extractClasses(nodeInfo.attributes)
+          : [],
+        attributes: nodeInfo.attributes || [],
+        boundingRect
+      };
+
+      // Get matched styles
+      const matchedStyles = await cdpSession.send('CSS.getMatchedStylesForNode', { nodeId });
+
+      // Process CSS rules
+      const cssRules: any[] = [];
+
+      // Inline style
+      if (matchedStyles.inlineStyle) {
+        const inlineProps = processStyleProperties(matchedStyles.inlineStyle.cssProperties, matchedStyles.inlineStyle.shorthandEntries);
+        if (Object.keys(inlineProps).length > 0) {
+          cssRules.push({
+            type: 'inline',
+            selector: '<inline style>',
+            source: 'inline style',
+            properties: inlineProps
+          });
+        }
+      }
+
+      // Regular matched rules
+      if (matchedStyles.matchedCSSRules) {
+        for (const rule of matchedStyles.matchedCSSRules) {
+          const props = processStyleProperties(rule.rule.style.cssProperties, rule.rule.style.shorthandEntries);
+
+          // Build source string
+          const source = rule.rule.origin === 'user-agent'
+            ? 'user-agent'
+            : rule.rule.selectorList?.selectors?.map((s: any) => s.value).join(', ') || 'unknown';
+
+          const sourceLocation = rule.rule.sourceURL
+            ? `${rule.rule.sourceURL}:${rule.rule.sourceLine || '?'}`
+            : 'inline';
+
+          cssRules.push({
+            type: rule.rule.origin === 'user-agent' ? 'user-agent' : 'regular',
+            selector: source,
+            source: sourceLocation,
+            properties: props
+          });
+        }
+      }
+
+      // Build summary
+      const summary = `元素 <${elementInfo.tagName}> 的 CSS 层叠链:\n` +
+        cssRules.map((rule, i) =>
+          `  ${i + 1}. [${rule.type}] ${rule.selector}\n     来源: ${rule.source}\n` +
+          (rule.properties.length > 0
+            ? `     属性: ${rule.properties.slice(0, 5).map((p: any) => `${p.name}: ${p.value}${p.important ? ' !important' : ''}`).join(', ')}${rule.properties.length > 5 ? '...' : ''}\n`
+            : '')
+        ).join('');
+
+      return {
+        content: [{ type: 'text', text: summary }],
+        details: { element: elementInfo, cssRules }
+      };
+
+    } finally {
+      // Clean up CDP session
+      if (cdpSession) {
+        try {
+          await cdpSession.detach();
+        } catch (error) {
+          console.error('[pi-to-chrome] inspect-styles: cdpSession.detach() 失败', error);
+        }
+      }
+    }
+  }
+};
+
+function extractClasses(attributes: string[]): string[] {
+  const classes: string[] = [];
+  for (let i = 0; i < attributes.length - 1; i += 2) {
+    if (attributes[i] === 'class') {
+      return attributes[i + 1].split(/\s+/).filter(c => c).slice(0, 10);
+    }
+  }
+  return classes;
+}
+
+function processStyleProperties(
+  cssProperties: any[],
+  shorthandEntries: any[]
+): any[] {
+  if (!cssProperties) return [];
+
+  const result: any[] = [];
+  const seenShorthands = new Set<string>();
+
+  // Track which shorthands are explicitly set
+  for (const entry of shorthandEntries || []) {
+    if (entry.value > 0) {
+      seenShorthands.add(cssProperties[entry.value]?.name || '');
+    }
+  }
+
+  for (const prop of cssProperties) {
+    // Skip empty values
+    if (!prop.value || prop.value === '') continue;
+
+    // Skip inherit/initial/unset unless it's the only value (shorthand)
+    const isInheritOrInitial = ['inherit', 'initial', 'unset', 'revert'].includes(prop.value);
+
+    // Keep the property if:
+    // 1. It's a shorthand property (entry in shorthandEntries)
+    // 2. It's not a longhand of an explicitly set shorthand
+    // 3. It's inherit/initial/unset with no shorthand entry
+    const isShorthand = shorthandEntries?.some((e: any) =>
+      e.value === cssProperties.indexOf(prop) && e.value >= 0
+    );
+
+    if (isShorthand) {
+      result.push({
+        name: prop.name,
+        value: prop.value,
+        important: prop.important || false
+      });
+    } else if (!isInheritOrInitial) {
+      result.push({
+        name: prop.name,
+        value: prop.value,
+        important: prop.important || false
+      });
+    }
+  }
+
+  return result;
+}