cssprobe-cli 0.2.5 → 0.2.7

package/dist/help.json

@@ -1,55 +1,90 @@
 {
-  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nInspection:\n  inspect <url> [selector]    inspect the runtime css of a page (layout, scroll, colors, fonts, backgrounds)\n  login <url>                 open browser for interactive login, then save state for later use\n  state-import [file]         import cookies from netscape format file into a playwright state file\n  interactive <url>           open browser and inspect interactively (repl mode)\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli (teaches agents how to use the cli)\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
+  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nSession Management:\n  open [url]                  open browser in session mode (non-blocking)\n  close                       close the browser session\n  status                      show current session status\n  eval <expression>           evaluate javascript expression on the page\n  state-import [file]         import cookies from netscape format file\n\nCSS Inspection:\n  inspect <selector>          inspect the runtime css of a page element\n  tree <selector>             show dom tree structure\n  layout <selector>           show ascii layout diagram\n  findings <selector>         show only issues/warnings/errors\n  inject-css <css>            inject css into the current page\n\nExport:\n  screenshot                  take a screenshot of the current page\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
   "commands": {
+    "open": {
+      "help": "cssprobe-cli open [url]\n\nOpen browser in session mode (non-blocking)\n\nArguments:\n  [url]                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --headed                    show the browser window\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "browser": "string",
+        "headed": "boolean"
+      },
+      "args": [
+        "url"
+      ]
+    },
+    "close": {
+      "help": "cssprobe-cli close \n\nClose the browser session\n\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": []
+    },
+    "status": {
+      "help": "cssprobe-cli status \n\nShow current session status\n\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": []
+    },
     "inspect": {
-      "help": "cssprobe-cli inspect <url> [selector]\n\nInspect the runtime CSS of a page (layout, scroll, colors, fonts, backgrounds)\n\nArguments:\n  <url>                       url, file:// path, or local html file path\n  [selector]                  css selector for the root element (auto-detected if omitted)\nOptions:\n  --json                      output structured json instead of markdown\n  --headed                    show the browser window\n  --browser                   browser engine (default chromium)\n  --zoom                      run 1x/0.5x viewport diagnosis\n  --depth                     dom tree depth (default: auto, max 20)\n  --max-nodes                 node count cap (default 60)\n  --up-to                     ancestor stop tag (default html)\n  --state                     path to saved state file (cookies + localstorage)\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --wait                      wait for user interaction before collecting (implies --headed)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli inspect <selector>\n\nInspect the runtime CSS of a page element\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --json                      output structured json instead of markdown\n  --brief                     compact output: tree sketch + warnings/errors only\n  --layout                    ascii layout diagram showing element positions and sizes\n  --depth                     dom tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "json": "boolean",
-        "headed": "boolean",
-        "browser": "string",
-        "zoom": "boolean",
-        "depth": "string",
-        "max-nodes": "string",
-        "up-to": "string",
-        "state": "string",
         "brief": "boolean",
         "layout": "boolean",
-        "wait": "boolean"
+        "depth": "string"
       },
       "args": [
-        "url",
         "selector"
       ]
     },
-    "login": {
-      "help": "cssprobe-cli login <url>\n\nOpen browser for interactive login, then save state for later use\n\nArguments:\n  <url>                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --out                       output state file path (default: ~/.cssprobe-cli/states/<domain>.json)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+    "tree": {
+      "help": "cssprobe-cli tree <selector>\n\nShow DOM tree structure\n\nArguments:\n  <selector>                  css selector for the root element\nOptions:\n  --depth                     tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
-        "browser": "string",
-        "out": "string"
+        "depth": "string"
       },
       "args": [
-        "url"
+        "selector"
       ]
     },
-    "state-import": {
-      "help": "cssprobe-cli state-import [file]\n\nImport cookies from Netscape format file into a Playwright state file\n\nArguments:\n  [file]                      netscape cookie file path (reads from stdin if omitted)\nOptions:\n  --out                       output state file path (default: ~/.cssprobe-cli/states/imported.json)\n  --merge                     existing state file to merge into\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+    "layout": {
+      "help": "cssprobe-cli layout <selector>\n\nShow ASCII layout diagram\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": [
+        "selector"
+      ]
+    },
+    "findings": {
+      "help": "cssprobe-cli findings <selector>\n\nShow only issues/warnings/errors\n\nArguments:\n  <selector>                  css selector for the root element\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": [
+        "selector"
+      ]
+    },
+    "inject-css": {
+      "help": "cssprobe-cli inject-css <css>\n\nInject CSS into the current page\n\nArguments:\n  <css>                       css code to inject\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
+      "args": [
+        "css"
+      ]
+    },
+    "screenshot": {
+      "help": "cssprobe-cli screenshot \n\nTake a screenshot of the current page\n\nOptions:\n  --full-page                 take screenshot of the full scrollable page\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
-        "out": "string",
-        "merge": "string"
+        "full-page": "boolean"
       },
+      "args": []
+    },
+    "eval": {
+      "help": "cssprobe-cli eval <expression>\n\nEvaluate JavaScript expression on the page\n\nArguments:\n  <expression>                javascript expression to evaluate\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {},
       "args": [
-        "file"
+        "expression"
       ]
     },
-    "interactive": {
-      "help": "cssprobe-cli interactive <url>\n\nOpen browser and inspect interactively (REPL mode)\n\nArguments:\n  <url>                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --state                     path to saved state file (cookies + localstorage)\n  --depth                     dom tree depth (default: auto, max 20)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+    "state-import": {
+      "help": "cssprobe-cli state-import [file]\n\nImport cookies from Netscape format file\n\nArguments:\n  [file]                      netscape cookie file path (reads from stdin if omitted)\nOptions:\n  --out                       output state file path (default: ~/.cssprobe-cli/states/imported.json)\n  --merge                     existing state file to merge into\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
-        "browser": "string",
-        "state": "string",
-        "depth": "string"
+        "out": "string",
+        "merge": "string"
       },
       "args": [
-        "url"
+        "file"
       ]
     },
     "config-show": {
@@ -60,7 +95,7 @@
       "args": []
     },
     "config-set": {
-      "help": "cssprobe-cli config-set <key> <value>\n\nSet a configuration value\n\nArguments:\n  <key>                       config key (browser, depth, headed)\n  <value>                     config value\nOptions:\n  --profile                   profile name",
+      "help": "cssprobe-cli config-set <key> <value>\n\nSet a configuration value\n\nArguments:\n  <key>                       config key (browser, depth, headed, viewport)\n  <value>                     config value\nOptions:\n  --profile                   profile name",
       "flags": {
         "profile": "string"
       },
@@ -94,7 +129,7 @@
       "args": []
     },
     "skill-install": {
-      "help": "cssprobe-cli skill-install \n\nInstall Agent Skill for cssprobe-cli (teaches agents how to use the CLI)\n\nOptions:\n  --target                    agent target: auto, all, opencode, claude, codex, cursor, hermes, gemini (default: auto)\n  --local                     install to current directory instead of home\n  --path                      custom base directory (overrides home/current)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "help": "cssprobe-cli skill-install \n\nInstall Agent Skill for cssprobe-cli\n\nOptions:\n  --target                    agent target: auto, all, opencode, claude, codex, cursor, hermes, gemini (default: auto)\n  --local                     install to current directory instead of home\n  --path                      custom base directory (overrides home/current)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
       "flags": {
         "target": "string",
         "local": "boolean",
@@ -113,12 +148,11 @@
     }
   },
   "booleanOptions": [
-    "json",
     "headed",
-    "zoom",
+    "json",
     "brief",
     "layout",
-    "wait",
+    "full-page",
     "local"
   ]
 }

package/dist/utils/socketConnection.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Socket communication utility.
+ * Adapted from playwright-cli.
+ */
+import net from 'net';
+export declare class SocketConnection {
+    private _socket;
+    private _pendingBuffers;
+    onclose?: () => void;
+    onmessage?: (message: any) => void;
+    constructor(socket: net.Socket);
+    send(message: {
+        id: number;
+        error?: string;
+        result?: any;
+    }): Promise<void>;
+    close(): void;
+    private _onData;
+    private _dispatchMessage;
+}
+export declare function compareSemver(a: string, b: string): number;

package/dist/utils/socketConnection.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Socket communication utility.
+ * Adapted from playwright-cli.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketConnection = void 0;
+exports.compareSemver = compareSemver;
+class SocketConnection {
+    _socket;
+    _pendingBuffers = [];
+    onclose;
+    onmessage;
+    constructor(socket) {
+        this._socket = socket;
+        socket.on('data', buffer => this._onData(buffer));
+        socket.on('close', () => {
+            this.onclose?.();
+        });
+        socket.on('error', e => console.error(`error: ${e.message}`));
+    }
+    async send(message) {
+        await new Promise((resolve, reject) => {
+            this._socket.write(`${JSON.stringify(message)}\n`, error => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(undefined);
+            });
+        });
+    }
+    close() {
+        this._socket.destroy();
+    }
+    _onData(buffer) {
+        let end = buffer.indexOf('\n');
+        if (end === -1) {
+            this._pendingBuffers.push(buffer);
+            return;
+        }
+        this._pendingBuffers.push(buffer.slice(0, end));
+        const message = Buffer.concat(this._pendingBuffers).toString();
+        this._dispatchMessage(message);
+        let start = end + 1;
+        end = buffer.indexOf('\n', start);
+        while (end !== -1) {
+            const message = buffer.toString(undefined, start, end);
+            this._dispatchMessage(message);
+            start = end + 1;
+            end = buffer.indexOf('\n', start);
+        }
+        this._pendingBuffers = [buffer.slice(start)];
+    }
+    _dispatchMessage(message) {
+        try {
+            this.onmessage?.(JSON.parse(message));
+        }
+        catch (e) {
+            console.error('failed to dispatch message', e);
+        }
+    }
+}
+exports.SocketConnection = SocketConnection;
+function compareSemver(a, b) {
+    const aBase = a.replace(/-.*$/, '');
+    const bBase = b.replace(/-.*$/, '');
+    const aParts = aBase.split('.').map(Number);
+    const bParts = bBase.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (aParts[i] > bParts[i])
+            return 1;
+        if (aParts[i] < bParts[i])
+            return -1;
+    }
+    return 0;
+}
+//# sourceMappingURL=socketConnection.js.map

package/docs/code-design-session-mode.md

@@ -0,0 +1,393 @@
+# Code Design: Session Mode
+
+## Overview
+
+cssprobe-cli 将复用 playwright-cli 的 daemon + session 架构，提供非阻塞的浏览器管理和 CSS 诊断能力。
+
+## Architecture
+
+```
+cssprobe-cli
+├── src/
+│   ├── cli/
+│   │   ├── program.ts          # CLI 入口
+│   │   ├── commands.ts         # 命令定义（合并 playwright-cli + cssprobe 命令）
+│   │   ├── command.ts          # 命令解析
+│   │   ├── output.ts           # 输出格式化
+│   │   └── minimist.ts         # 参数解析（已有）
+│   ├── daemon/
+│   │   ├── daemon.ts           # Daemon 进程（复制自 playwright-cli）
+│   │   ├── session.ts          # Session 管理（简化版，单 session）
+│   │   └── registry.ts         # Session 注册表（简化版）
+│   ├── backend/
+│   │   ├── browserBackend.ts   # 浏览器后端（复制自 playwright-cli）
+│   │   ├── context.ts          # 浏览器上下文（复制自 playwright-cli）
+│   │   ├── tool.ts             # Tool 接口（复制自 playwright-cli）
+│   │   ├── tools.ts            # Tool 注册（合并 playwright + cssprobe tools）
+│   │   ├── response.ts         # 响应处理（复制自 playwright-cli）
+│   │   └── tools/
+│   │       ├── evaluate.ts     # JS 执行（复制自 playwright-cli）
+│   │       ├── screenshot.ts   # 截图（复制自 playwright-cli）
+│   │       ├── pdf.ts          # PDF（复制自 playwright-cli）
+│   │       ├── navigate.ts     # 导航（复制自 playwright-cli）
+│   │       ├── tabs.ts         # Tab 管理（复制自 playwright-cli）
+│   │       ├── cssprobe.ts     # CSSprobe 工具（新增）
+│   │       │   ├── inspect.ts  # CSS 诊断
+│   │       │   ├── tree.ts     # DOM 树
+│   │       │   ├── layout.ts   # 布局图
+│   │       │   ├── findings.ts # 问题发现
+│   │       │   ├── snapshot.ts # 快照
+│   │       │   └── injectCss.ts# CSS 注入
+│   │       └── index.ts        # 工具导出
+│   ├── browser/
+│   │   └── launcher.ts         # 浏览器启动（保留，用于 daemon 启动）
+│   ├── engine/
+│   │   ├── collector.ts        # 数据收集（保留）
+│   │   ├── analyzer.ts         # 分析（保留）
+│   │   └── renderer.ts         # 渲染（保留）
+│   └── utils/
+│       └── socketConnection.ts # Socket 通信（复制自 playwright-cli）
+```
+
+## Key Components
+
+### 1. Session Management
+
+**简化版单 Session 实现：**
+
+```typescript
+// src/daemon/session.ts
+export class Session {
+  readonly name: string = 'default';
+  private _sessionFile: SessionFile;
+
+  async run(args: MinimistArgs): Promise<{ text: string }> {
+    const { socket } = await this._connect();
+    return await SocketConnectionClient.sendAndClose(socket, 'run', { args, cwd: process.cwd() });
+  }
+
+  async stop(): Promise<void> {
+    const { socket } = await this._connect();
+    await SocketConnectionClient.sendAndClose(socket, 'stop', {});
+  }
+
+  private async _connect(): Promise<{ socket?: net.Socket }> {
+    const sessionConfig = await this._loadSessionConfig();
+    if (!sessionConfig) return {};
+    return { socket: net.createConnection(sessionConfig.socketPath) };
+  }
+}
+```
+
+**Session 文件位置：**
+- macOS: `~/Library/Caches/ms-playwright/daemon/<workspaceHash>/default.session`
+- Linux: `~/.cache/ms-playwright/daemon/<workspaceHash>/default.session`
+
+### 2. Daemon Process
+
+**Daemon 启动流程：**
+1. `cssprobe-cli open <url>` 调用 `Session.startDaemon()`
+2. Daemon 进程启动，监听 Unix socket
+3. 接收命令，通过 BrowserBackend 执行
+4. 返回结果给客户端
+
+**Daemon 入口：**
+```typescript
+// src/daemon/daemonEntry.ts
+import { startCliDaemonServer } from './daemon';
+import { BrowserBackend } from '../backend/browserBackend';
+import { browserTools } from '../backend/tools';
+
+export async function runDaemon(sessionName: string, args: string[]) {
+  // 1. 启动浏览器
+  const browser = await chromium.launch({ headless: false });
+  const context = await browser.newContext();
+  
+  // 2. 创建 BrowserBackend
+  const backend = new BrowserBackend(config, context, browserTools);
+  
+  // 3. 启动 daemon server
+  await startCliDaemonServer(sessionName, context, browserInfo, config, clientInfo, mcpClientInfo, options);
+}
+```
+
+### 3. Backend Tools
+
+**现有 playwright-cli 工具（需要复制）：**
+- `evaluate.ts` - JS 执行
+- `screenshot.ts` - 截图
+- `pdf.ts` - PDF 生成
+- `navigate.ts` - 页面导航
+- `tabs.ts` - Tab 管理
+
+**新增 cssprobe 工具：**
+
+```typescript
+// src/backend/tools/cssprobe/inspect.ts
+import { defineTabTool } from '../tool';
+import { collect } from '../../../engine/collector';
+import { analyze } from '../../../engine/analyzer';
+import { renderMarkdown, renderJSON } from '../../../engine/renderer';
+
+const inspectTool = defineTabTool({
+  capability: 'core',
+  schema: {
+    name: 'cssprobe_inspect',
+    title: 'CSS Inspection',
+    description: 'Inspect runtime CSS of a page element',
+    inputSchema: z.object({
+      selector: z.string().describe('CSS selector for the root element'),
+      depth: z.number().optional().describe('DOM tree depth'),
+      json: z.boolean().optional().describe('Output as JSON'),
+      brief: z.boolean().optional().describe('Compact output'),
+      layout: z.boolean().optional().describe('ASCII layout diagram'),
+    }),
+    type: 'readOnly',
+  },
+  handle: async (tab, params, response) => {
+    const snapshot = await collect(tab.page, {
+      rootSelector: params.selector,
+      downDepth: params.depth || 6,
+      maxNodes: 60,
+    });
+    
+    const findings = analyze(snapshot);
+    
+    if (params.json) {
+      response.addResult('Inspection result', JSON.stringify(renderJSON(snapshot, findings, params.brief), null, 2));
+    } else {
+      response.addResult('Inspection result', renderMarkdown(snapshot, findings, params.brief, params.layout));
+    }
+  },
+});
+```
+
+### 4. Command Definitions
+
+**合并 playwright-cli 和 cssprobe 命令：**
+
+```typescript
+// src/cli/commands.ts
+import * as z from 'zod';
+import { declareCommand } from './command';
+
+// 浏览器管理命令（复用 playwright-cli）
+const open = declareCommand({
+  name: 'open',
+  category: 'core',
+  description: 'Open the browser',
+  args: z.object({
+    url: z.string().optional().describe('URL to navigate to'),
+  }),
+  options: z.object({
+    browser: z.string().optional().describe('Browser engine'),
+    headed: z.boolean().optional().describe('Show browser window'),
+  }),
+});
+
+const close = declareCommand({
+  name: 'close',
+  category: 'core',
+  description: 'Close the browser',
+});
+
+// CSSprobe 增强命令（新增）
+const inspect = declareCommand({
+  name: 'inspect',
+  category: 'cssprobe',
+  description: 'Inspect runtime CSS of a page element',
+  args: z.object({
+    selector: z.string().describe('CSS selector for the root element'),
+  }),
+  options: z.object({
+    json: z.boolean().optional().describe('Output as JSON'),
+    brief: z.boolean().optional().describe('Compact output'),
+    layout: z.boolean().optional().describe('ASCII layout diagram'),
+    depth: z.number().optional().describe('DOM tree depth'),
+  }),
+});
+
+const tree = declareCommand({
+  name: 'tree',
+  category: 'cssprobe',
+  description: 'Show DOM tree structure',
+  args: z.object({
+    selector: z.string().describe('CSS selector for the root element'),
+  }),
+  options: z.object({
+    depth: z.number().optional().describe('Tree depth'),
+  }),
+});
+
+const layout = declareCommand({
+  name: 'layout',
+  category: 'cssprobe',
+  description: 'Show ASCII layout diagram',
+  args: z.object({
+    selector: z.string().describe('CSS selector for the root element'),
+  }),
+});
+
+const findings = declareCommand({
+  name: 'findings',
+  category: 'cssprobe',
+  description: 'Show only issues/warnings',
+  args: z.object({
+    selector: z.string().describe('CSS selector for the root element'),
+  }),
+});
+
+const injectCss = declareCommand({
+  name: 'inject-css',
+  category: 'cssprobe',
+  description: 'Inject CSS into the current page',
+  args: z.object({
+    css: z.string().describe('CSS code to inject'),
+  }),
+});
+
+// 导出所有命令
+export const commands = {
+  open,
+  close,
+  inspect,
+  tree,
+  layout,
+  findings,
+  'inject-css': injectCss,
+  // ... 其他命令
+};
+```
+
+### 5. Socket Communication
+
+**复制自 playwright-cli，无需修改：**
+
+```typescript
+// src/utils/socketConnection.ts
+export class SocketConnection {
+  private _socket: net.Socket;
+  private _pendingBuffers: Buffer[] = [];
+
+  onclose?: () => void;
+  onmessage?: (message: any) => void;
+
+  constructor(socket: net.Socket) {
+    this._socket = socket;
+    socket.on('data', buffer => this._onData(buffer));
+    socket.on('close', () => this.onclose?.());
+  }
+
+  async send(message: { id: number, error?: string, result?: any }) {
+    await new Promise((resolve, reject) => {
+      this._socket.write(`${JSON.stringify(message)}\n`, error => {
+        if (error) reject(error);
+        else resolve(undefined);
+      });
+    });
+  }
+
+  close() {
+    this._socket.destroy();
+  }
+}
+```
+
+## Data Flow
+
+### 1. 打开浏览器
+
+```
+用户执行: cssprobe-cli open https://example.com --headed
+    ↓
+CLI 程序解析参数
+    ↓
+Session.startDaemon() 启动 daemon 进程
+    ↓
+Daemon 进程启动，监听 Unix socket
+    ↓
+CLI 连接 daemon，发送 goto 命令
+    ↓
+Daemon 执行导航，返回结果
+    ↓
+CLI 输出: {"sessionId":"default","pid":12345,"url":"https://example.com"}
+```
+
+### 2. 执行 CSS 诊断
+
+```
+用户执行: cssprobe-cli inspect .sidebar --json
+    ↓
+CLI 程序解析参数
+    ↓
+Session.run() 连接 daemon socket
+    ↓
+发送命令: { method: 'run', args: { _: ['inspect', '.sidebar'], json: true } }
+    ↓
+Daemon 接收命令，调用 cssprobe_inspect tool
+    ↓
+Tool 注入 collector，执行分析
+    ↓
+返回 JSON 结果
+    ↓
+CLI 输出诊断结果
+```
+
+### 3. 注入 CSS
+
+```
+用户执行: cssprobe-cli inject-css ".sidebar { background: red; }"
+    ↓
+CLI 程序解析参数
+    ↓
+Session.run() 连接 daemon socket
+    ↓
+发送命令: { method: 'run', args: { _: ['inject-css', '.sidebar { background: red; }'] } }
+    ↓
+Daemon 接收命令，调用 cssprobe_inject_css tool
+    ↓
+Tool 执行 page.addStyleTag({ content: css })
+    ↓
+返回成功结果
+    ↓
+CLI 输出: {"success":true}
+```
+
+## Dependencies
+
+| 依赖 | 版本 | 用途 |
+|------|------|------|
+| playwright-core | 已有 | 浏览器 API |
+| zod | 已有 | 参数验证 |
+| debug | 需要添加 | 日志 |
+
+## Migration Plan
+
+### Phase 1: 基础设施
+1. 复制 socketConnection.ts
+2. 复制 session.ts, registry.ts（简化版）
+3. 复制 daemon.ts
+4. 复制 backend 基础（browserBackend.ts, context.ts, tool.ts, response.ts）
+
+### Phase 2: 工具集成
+1. 复制 playwright-cli 工具（evaluate, screenshot, pdf, navigate, tabs）
+2. 实现 cssprobe 工具（inspect, tree, layout, findings, inject-css）
+
+### Phase 3: CLI 集成
+1. 合并命令定义
+2. 更新 CLI 入口
+3. 更新输出格式
+
+### Phase 4: 测试
+1. 单元测试
+2. 集成测试
+3. 端到端测试
+
+## Backward Compatibility
+
+| 旧命令 | 新命令 | 说明 |
+|--------|--------|------|
+| `login <url>` | `open <url>` → 手动登录 → `save-state` | 流程变化 |
+| `inspect <url> --wait` | `open <url>` → 手动操作 → `inspect <selector>` | 流程变化 |
+| `interactive <url>` | `open <url>` → 多次 `inspect`/`tree`/`inject-css` | 流程变化 |
+| `state-import` | 保留 | 不变 |

package/docs/guide/installation.md

@@ -238,12 +238,13 @@ confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
 export CSSPROBE_BROWSER=chromium
 export CSSPROBE_DEPTH=6
 export CSSPROBE_HEADED=true
+export CSSPROBE_VIEWPORT=375x812
 export CSSPROBE_PROFILE=default
 ```
 
 Priority (highest to lowest):
-1. CLI flags: `--browser`, `--depth`, `--headed`
-2. Environment variables: `CSSPROBE_BROWSER`, `CSSPROBE_DEPTH`, `CSSPROBE_HEADED`
+1. CLI flags: `--browser`, `--depth`, `--headed`, `--viewport`
+2. Environment variables: `CSSPROBE_BROWSER`, `CSSPROBE_DEPTH`, `CSSPROBE_HEADED`, `CSSPROBE_VIEWPORT`
 3. Config file: `~/.cssprobe-clirc`
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssprobe-cli",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Runtime CSS probe — inspect layout, colors, backgrounds, fonts and more in a live browser. AI agents and shell automation.",
   "keywords": [
     "css",