@parkinglot/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ParkingLot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const PROTOCOL_VERSION: "0.1.0";
+/** 协议标识名，用于握手（extension.hello / ping）确认两端协议一致。 */
+export declare const PROTOCOL_NAME: "parkinglot";
+export declare function protocolName(): string;

package/dist/constants.js

@@ -0,0 +1,7 @@
+export const PROTOCOL_VERSION = '0.1.0';
+/** 协议标识名，用于握手（extension.hello / ping）确认两端协议一致。 */
+export const PROTOCOL_NAME = 'parkinglot';
+export function protocolName() {
+    return PROTOCOL_NAME;
+}
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAgB,CAAC;AAEjD,kDAAkD;AAClD,MAAM,CAAC,MAAM,aAAa,GAAG,YAAqB,CAAC;AAEnD,MAAM,UAAU,YAAY;IAC1B,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/envelope.d.ts

@@ -0,0 +1,53 @@
+import type { ErrorCode } from './errors.js';
+import type { Method, ParamsMap, ResultMap } from './methods.js';
+import type { ContextSnapshot } from './types.js';
+/**
+ * 请求信封。params 可省略（NoopParams 命令）。
+ * sessionId / tabId 为 server 寻址后注入的目标字段（与 Response 信封对称），
+ * CLI/HTTP 客户端可选传入，extension 收到的请求总是携带已解析的目标。
+ */
+export interface Request<M extends Method = Method> {
+    id: string;
+    method: M;
+    params?: ParamsMap[M];
+    sessionId?: string;
+    tabId?: number;
+}
+/**
+ * 命令结果信封。三个公共字段统一携带寻址与连续性信息：
+ * - sessionId / tabId：本次命令实际作用的会话与标签页（寻址解析结果）
+ * - context：页面上下文快照（url/title/navId）——Agent 连续性的"自证"
+ * data 存放命令特有结果。
+ */
+export interface CommandResult<M extends Method = Method> {
+    sessionId?: string;
+    tabId?: number;
+    context?: ContextSnapshot;
+    data: ResultMap[M];
+}
+export interface Response<M extends Method = Method> {
+    id: string;
+    result: CommandResult<M>;
+}
+export interface ErrorBody {
+    code: ErrorCode;
+    message: string;
+    data?: Record<string, unknown>;
+}
+/** 错误信封（Response 的失败形态，与成功 Response 共用 id）。 */
+export interface ProtocolError {
+    id: string;
+    error: ErrorBody;
+}
+export declare const EVENT_NAMES: readonly ["extension.connected", "extension.disconnected", "extension.tab-activated", "page.navigated", "approval.requested", "approval.responded", "approval.respond"];
+export type EventName = (typeof EVENT_NAMES)[number];
+/** 事件消息（extension → server，server 按需转发给订阅方）。 */
+export interface EventMessage {
+    event: EventName;
+    params: Record<string, unknown>;
+}
+export type Message = Request | Response | ProtocolError | EventMessage;
+export declare function isRequest(value: unknown): value is Request;
+export declare function isResponse(value: unknown): value is Response;
+export declare function isError(value: unknown): value is ProtocolError;
+export declare function isEvent(value: unknown): value is EventMessage;

package/dist/envelope.js

@@ -0,0 +1,40 @@
+export const EVENT_NAMES = [
+    'extension.connected',
+    'extension.disconnected',
+    'extension.tab-activated',
+    'page.navigated',
+    'approval.requested',
+    'approval.responded',
+    // 扩展 → server 控制事件：popup 对 HITL 请求的批准/拒绝
+    'approval.respond',
+    // Network.* 为扩展点：v1 不实现页面级网络事件
+];
+// ---------------------------------------------------------------------------
+// 类型守卫（wire 层判别，供 WS/HTTP 消息路由使用）
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function isRequest(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        typeof value.method === 'string' &&
+        (value.params === undefined || isRecord(value.params)));
+}
+export function isResponse(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        isRecord(value.result) &&
+        'data' in value.result);
+}
+export function isError(value) {
+    return (isRecord(value) &&
+        typeof value.id === 'string' &&
+        isRecord(value.error) &&
+        typeof value.error.code === 'string' &&
+        typeof value.error.message === 'string');
+}
+export function isEvent(value) {
+    return isRecord(value) && typeof value.event === 'string' && isRecord(value.params);
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AA+CA,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,qBAAqB;IACrB,wBAAwB;IACxB,yBAAyB;IACzB,gBAAgB;IAChB,oBAAoB;IACpB,oBAAoB;IACpB,yCAAyC;IACzC,kBAAkB;IAClB,+BAA+B;CACvB,CAAC;AAYX,8EAA8E;AAC9E,kCAAkC;AAClC,8EAA8E;AAE9E,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC;QACf,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;QAC5B,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAChC,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CACvD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC;QACf,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;QAC5B,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,MAAM,CACvB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC;QACf,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;QAC5B,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;QACrB,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;QACpC,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,KAAK,QAAQ,CACxC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACtF,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 协议错误码与错误类型。
+ * 错误码是 wire 协议的一部分：extension 与 server 两侧都必须使用同一套枚举。
+ */
+export declare const ERROR_CODES: readonly ["INVALID_REQUEST", "INVALID_PARAMS", "UNKNOWN_METHOD", "MESSAGE_TOO_LARGE", "EXTENSION_OFFLINE", "EXTENSION_NO_TAB", "SESSION_NOT_FOUND", "SESSION_TAB_CLOSED", "TIMEOUT", "TARGET_NOT_FOUND", "TARGET_AMBIGUOUS", "URL_INVALID", "HOST_NOT_ALLOWED", "EVAL_DISABLED", "PENDING_APPROVAL", "APPROVAL_DENIED", "APPROVAL_TIMEOUT", "INTERNAL"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export interface ProtocolErrorData {
+    requestId?: string;
+    [key: string]: unknown;
+}
+/** 协议层错误：携带稳定的机器可读 code，供 CLI/Agent 决策。 */
+export declare class ParkinglotError extends Error {
+    readonly code: ErrorCode;
+    readonly data: ProtocolErrorData | undefined;
+    constructor(code: ErrorCode, message: string, data?: ProtocolErrorData);
+}
+export declare function isErrorCode(value: unknown): value is ErrorCode;

package/dist/errors.js

@@ -0,0 +1,45 @@
+/**
+ * 协议错误码与错误类型。
+ * 错误码是 wire 协议的一部分：extension 与 server 两侧都必须使用同一套枚举。
+ */
+export const ERROR_CODES = [
+    // 信封/参数层
+    'INVALID_REQUEST',
+    'INVALID_PARAMS',
+    'UNKNOWN_METHOD',
+    'MESSAGE_TOO_LARGE',
+    // 连接层
+    'EXTENSION_OFFLINE',
+    'EXTENSION_NO_TAB',
+    // 会话/寻址层
+    'SESSION_NOT_FOUND',
+    'SESSION_TAB_CLOSED',
+    // 执行层
+    'TIMEOUT',
+    'TARGET_NOT_FOUND',
+    'TARGET_AMBIGUOUS',
+    'URL_INVALID',
+    'HOST_NOT_ALLOWED',
+    'EVAL_DISABLED',
+    // HITL 层
+    'PENDING_APPROVAL',
+    'APPROVAL_DENIED',
+    'APPROVAL_TIMEOUT',
+    // 兜底
+    'INTERNAL',
+];
+/** 协议层错误：携带稳定的机器可读 code，供 CLI/Agent 决策。 */
+export class ParkinglotError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = 'ParkinglotError';
+        this.code = code;
+        this.data = data;
+    }
+}
+export function isErrorCode(value) {
+    return typeof value === 'string' && ERROR_CODES.includes(value);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,SAAS;IACT,iBAAiB;IACjB,gBAAgB;IAChB,gBAAgB;IAChB,mBAAmB;IACnB,MAAM;IACN,mBAAmB;IACnB,kBAAkB;IAClB,SAAS;IACT,mBAAmB;IACnB,oBAAoB;IACpB,MAAM;IACN,SAAS;IACT,kBAAkB;IAClB,kBAAkB;IAClB,aAAa;IACb,kBAAkB;IAClB,eAAe;IACf,SAAS;IACT,kBAAkB;IAClB,iBAAiB;IACjB,kBAAkB;IAClB,KAAK;IACL,UAAU;CACF,CAAC;AASX,2CAA2C;AAC3C,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,CAAY;IAChB,IAAI,CAAgC;IAE7C,YAAY,IAAe,EAAE,OAAe,EAAE,IAAwB;QACpE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @parkinglot/protocol — 共享协议层。
+ *
+ * 内容：消息信封（Request/Response/Error/Event）、命令全集与类型映射、
+ * 公共类型（ContextSnapshot/PageSnapshot/ElementInfo/SessionInfo…）、
+ * 错误码、Zod 校验 schema。
+ *
+ * 协议权威文档：skills/parkinglot/references/protocol.md
+ */
+export { PROTOCOL_NAME, PROTOCOL_VERSION, protocolName } from './constants.js';
+export * from './errors.js';
+export * from './types.js';
+export * from './methods.js';
+export * from './envelope.js';
+export * from './schemas.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @parkinglot/protocol — 共享协议层。
+ *
+ * 内容：消息信封（Request/Response/Error/Event）、命令全集与类型映射、
+ * 公共类型（ContextSnapshot/PageSnapshot/ElementInfo/SessionInfo…）、
+ * 错误码、Zod 校验 schema。
+ *
+ * 协议权威文档：skills/parkinglot/references/protocol.md
+ */
+export { PROTOCOL_NAME, PROTOCOL_VERSION, protocolName } from './constants.js';
+export * from './errors.js';
+export * from './types.js';
+export * from './methods.js';
+export * from './envelope.js';
+export * from './schemas.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE/E,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC"}

package/dist/methods.d.ts

@@ -0,0 +1,189 @@
+import type { ElementInfo, PageSnapshot, SearchPagination, SearchResult, SessionInfo, TabInfo, Viewport } from './types.js';
+/**
+ * 命令全集（v1）。method 名与 CLI 子命令一一对应（kebab-case）。
+ * 分类：导航 / 交互 / 滚动截图 / 提取 / 页面内网络 / 标签页 / 等待 / 会话 / 高级。
+ */
+export declare const METHODS: readonly ["goto", "back", "forward", "reload", "click", "click-text", "fill", "type", "press", "hover", "select", "scroll", "screenshot", "extract", "get-page-info", "fetch", "search", "list-tabs", "create-tab", "close-tab", "activate-tab", "wait", "ping", "get-status", "eval"];
+export type Method = (typeof METHODS)[number];
+/** HITL 分类：'always'=写操作需批准；'never'=只读；'conditional'=视参数（fetch 的 HTTP method）。 */
+export type WriteAccess = 'always' | 'never' | 'conditional';
+export interface MethodMeta {
+    writeAccess: WriteAccess;
+    summary: string;
+}
+export declare const METHOD_META: Record<Method, MethodMeta>;
+export type NoopParams = Record<string, never>;
+export interface GotoParams {
+    url: string;
+    waitUntil?: 'load' | 'domcontentloaded';
+}
+export interface ClickParams {
+    selector: string;
+}
+export interface ClickTextParams {
+    text: string;
+}
+export interface FillParams {
+    selector: string;
+    value: string;
+}
+export interface TypeParams {
+    selector: string;
+    text: string;
+}
+export interface PressParams {
+    selector?: string;
+    key: string;
+}
+export interface HoverParams {
+    selector: string;
+}
+export interface SelectParams {
+    selector: string;
+    /** value 与 label 至少提供其一 */
+    value?: string;
+    label?: string;
+}
+export interface ScrollParams {
+    /** direction 与 amount 二选一；提供 selector 则滚动该元素 */
+    direction?: 'up' | 'down' | 'top' | 'bottom';
+    amount?: number;
+    selector?: string;
+}
+export interface ScreenshotParams {
+    format?: 'png' | 'jpeg';
+    fullPage?: boolean;
+    /** 由 CLI 侧解析后写入的本地路径（协议不负责写文件） */
+    path?: string;
+}
+export interface ExtractParams {
+    mode?: 'text' | 'structured';
+    /** 返回文本的最大字符数（LLM 上下文裁剪） */
+    limit?: number;
+}
+export interface FetchParams {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    returnType?: 'text' | 'json' | 'binary';
+}
+export interface SearchParams {
+    query: string;
+    engine?: string;
+    /** 结果页页码（1-based，默认 1；每页 ~10 条） */
+    page?: number;
+}
+export interface CreateTabParams {
+    url: string;
+}
+export interface CloseTabParams {
+    tabId?: number;
+}
+export interface ActivateTabParams {
+    tabId: number;
+}
+export interface WaitParams {
+    /** ms / selector / condition 至少提供其一 */
+    ms?: number;
+    selector?: string;
+    condition?: 'networkidle' | 'load';
+}
+export interface EvalParams {
+    expression: string;
+}
+export interface ParamsMap {
+    goto: GotoParams;
+    back: NoopParams;
+    forward: NoopParams;
+    reload: NoopParams;
+    click: ClickParams;
+    'click-text': ClickTextParams;
+    fill: FillParams;
+    type: TypeParams;
+    press: PressParams;
+    hover: HoverParams;
+    select: SelectParams;
+    scroll: ScrollParams;
+    screenshot: ScreenshotParams;
+    extract: ExtractParams;
+    'get-page-info': NoopParams;
+    fetch: FetchParams;
+    search: SearchParams;
+    'list-tabs': NoopParams;
+    'create-tab': CreateTabParams;
+    'close-tab': CloseTabParams;
+    'activate-tab': ActivateTabParams;
+    wait: WaitParams;
+    ping: NoopParams;
+    'get-status': NoopParams;
+    eval: EvalParams;
+}
+export interface ElementActionResult {
+    element: ElementInfo;
+}
+export interface ResultMap {
+    goto: Record<string, never>;
+    back: Record<string, never>;
+    forward: Record<string, never>;
+    reload: Record<string, never>;
+    click: ElementActionResult;
+    'click-text': ElementActionResult;
+    fill: ElementActionResult;
+    type: ElementActionResult;
+    press: ElementActionResult;
+    hover: ElementActionResult;
+    select: ElementActionResult;
+    scroll: {
+        viewport: Viewport;
+    };
+    screenshot: {
+        data?: string;
+        path?: string;
+    };
+    extract: {
+        snapshot: PageSnapshot;
+    };
+    'get-page-info': {
+        url: string;
+        title: string;
+        viewport: Viewport;
+        scrollY: number;
+    };
+    fetch: {
+        status: number;
+        statusText?: string;
+        headers: Record<string, string>;
+        body: string;
+    };
+    search: {
+        results: SearchResult[];
+        pagination?: SearchPagination;
+    };
+    'list-tabs': {
+        tabs: TabInfo[];
+    };
+    'create-tab': {
+        tab: TabInfo;
+    };
+    'close-tab': Record<string, never>;
+    'activate-tab': {
+        tab: TabInfo;
+    };
+    wait: Record<string, never>;
+    ping: {
+        pong: 'pong';
+        protocolVersion: string;
+        extensionConnected: boolean;
+    };
+    'get-status': {
+        extensionConnected: boolean;
+        sessions: SessionInfo[];
+        config: Record<string, unknown>;
+    };
+    eval: {
+        value: unknown;
+    };
+}
+export type ParamsOf<M extends Method> = ParamsMap[M];
+export type ResultOf<M extends Method> = ResultMap[M];

package/dist/methods.js

@@ -0,0 +1,77 @@
+/**
+ * 命令全集（v1）。method 名与 CLI 子命令一一对应（kebab-case）。
+ * 分类：导航 / 交互 / 滚动截图 / 提取 / 页面内网络 / 标签页 / 等待 / 会话 / 高级。
+ */
+export const METHODS = [
+    // 导航
+    'goto',
+    'back',
+    'forward',
+    'reload',
+    // 交互
+    'click',
+    'click-text',
+    'fill',
+    'type',
+    'press',
+    'hover',
+    'select',
+    // 滚动 / 视图
+    'scroll',
+    'screenshot',
+    // 提取
+    'extract',
+    'get-page-info',
+    // 页面内网络
+    'fetch',
+    'search',
+    // 标签页
+    'list-tabs',
+    'create-tab',
+    'close-tab',
+    'activate-tab',
+    // 等待
+    'wait',
+    // 会话
+    'ping',
+    'get-status',
+    // 高级（默认禁用）
+    'eval',
+];
+export const METHOD_META = {
+    // 导航
+    goto: { writeAccess: 'always', summary: '导航到指定 URL' },
+    back: { writeAccess: 'always', summary: '后退到上一页' },
+    forward: { writeAccess: 'always', summary: '前进到下一页' },
+    reload: { writeAccess: 'always', summary: '重新加载当前页' },
+    // 交互
+    click: { writeAccess: 'always', summary: '按 CSS 选择器点击元素' },
+    'click-text': { writeAccess: 'always', summary: '按可见文本点击元素' },
+    fill: { writeAccess: 'always', summary: '填充输入框（整体替换）' },
+    type: { writeAccess: 'always', summary: '聚焦后逐键输入' },
+    press: { writeAccess: 'always', summary: '按下键盘按键' },
+    hover: { writeAccess: 'always', summary: '悬停在元素上' },
+    select: { writeAccess: 'always', summary: '选择下拉选项' },
+    // 滚动 / 视图
+    scroll: { writeAccess: 'always', summary: '滚动页面或元素' },
+    screenshot: { writeAccess: 'never', summary: '截图（viewport 或整页）' },
+    // 提取
+    extract: { writeAccess: 'never', summary: '提取页面可读文本快照' },
+    'get-page-info': { writeAccess: 'never', summary: '获取页面 URL/标题/视口/滚动位置' },
+    // 页面内网络
+    fetch: { writeAccess: 'conditional', summary: '在页面上下文发起网络请求（带登录态）' },
+    search: { writeAccess: 'never', summary: '用搜索引擎查询并返回结果列表' },
+    // 标签页
+    'list-tabs': { writeAccess: 'never', summary: '列出所有标签页' },
+    'create-tab': { writeAccess: 'always', summary: '新建标签页' },
+    'close-tab': { writeAccess: 'always', summary: '关闭标签页' },
+    'activate-tab': { writeAccess: 'always', summary: '激活（切换到）标签页' },
+    // 等待
+    wait: { writeAccess: 'never', summary: '等待时间/元素/加载条件' },
+    // 会话
+    ping: { writeAccess: 'never', summary: '连通性检查（pong + 版本）' },
+    'get-status': { writeAccess: 'never', summary: '获取 server/扩展/session 状态摘要' },
+    // 高级
+    eval: { writeAccess: 'always', summary: '在页面上下文执行 JS（默认禁用）' },
+};
+//# sourceMappingURL=methods.js.map

package/dist/methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.js","sourceRoot":"","sources":["../src/methods.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 运行时子路径导出：不引入 zod/schemas，供浏览器端（extension）使用。
+ * 类型可从主包或此处导入（type-only，编译期消除）。
+ */
+export { PROTOCOL_NAME, PROTOCOL_VERSION, protocolName } from './constants.js';
+export { ERROR_CODES, ParkinglotError, isErrorCode, type ErrorCode, type ProtocolErrorData, } from './errors.js';
+export { EVENT_NAMES, isError, isEvent, isRequest, isResponse, type CommandResult, type ErrorBody, type EventMessage, type EventName, type Message, type ProtocolError, type Request, type Response, } from './envelope.js';
+export { METHOD_META, METHODS, type Method, type MethodMeta, type WriteAccess } from './methods.js';
+export type { ActivateTabParams, ClickParams, ClickTextParams, CloseTabParams, CreateTabParams, EvalParams, FetchParams, FillParams, GotoParams, HoverParams, NoopParams, ParamsMap, ParamsOf, PressParams, ResultMap, ResultOf, ScrollParams, ScreenshotParams, SearchParams, SelectParams, TypeParams, WaitParams, } from './methods.js';
+export type { ContextSnapshot, ElementBox, ElementInfo, Locator, PageSnapshot, SearchPagination, SearchResult, SessionInfo, SessionMode, TabInfo, Viewport, } from './types.js';

package/dist/runtime.js

@@ -0,0 +1,9 @@
+/**
+ * 运行时子路径导出：不引入 zod/schemas，供浏览器端（extension）使用。
+ * 类型可从主包或此处导入（type-only，编译期消除）。
+ */
+export { PROTOCOL_NAME, PROTOCOL_VERSION, protocolName } from './constants.js';
+export { ERROR_CODES, ParkinglotError, isErrorCode, } from './errors.js';
+export { EVENT_NAMES, isError, isEvent, isRequest, isResponse, } from './envelope.js';
+export { METHOD_META, METHODS } from './methods.js';
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,GAGZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,OAAO,EACP,OAAO,EACP,SAAS,EACT,UAAU,GASX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,OAAO,EAAkD,MAAM,cAAc,CAAC"}

package/dist/schemas.d.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod';
+import type { Method } from './methods.js';
+import type { ParamsMap } from './methods.js';
+/**
+ * Zod 校验层。原则（Postel's Law）：
+ * - 发送保守：schema 精确到每个命令的参数形状
+ * - 接收宽容：未知字段默认 strip，缺省字段用 optional/默认值
+ */
+export declare const contextSchema: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodString;
+    navId: z.ZodNumber;
+    tabId: z.ZodNumber;
+}, z.core.$strip>;
+export declare const viewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export declare const elementInfoSchema: z.ZodObject<{
+    tag: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    attrs: z.ZodRecord<z.ZodString, z.ZodString>;
+    box: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const paramsSchemas: {
+    goto: z.ZodObject<{
+        url: z.ZodString;
+        waitUntil: z.ZodOptional<z.ZodEnum<{
+            load: "load";
+            domcontentloaded: "domcontentloaded";
+        }>>;
+    }, z.core.$strip>;
+    back: z.ZodObject<{}, z.core.$strip>;
+    forward: z.ZodObject<{}, z.core.$strip>;
+    reload: z.ZodObject<{}, z.core.$strip>;
+    click: z.ZodObject<{
+        selector: z.ZodString;
+    }, z.core.$strip>;
+    'click-text': z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strip>;
+    fill: z.ZodObject<{
+        selector: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>;
+    type: z.ZodObject<{
+        selector: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strip>;
+    press: z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+    }, z.core.$strip>;
+    hover: z.ZodObject<{
+        selector: z.ZodString;
+    }, z.core.$strip>;
+    select: z.ZodObject<{
+        selector: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    scroll: z.ZodObject<{
+        direction: z.ZodOptional<z.ZodEnum<{
+            up: "up";
+            down: "down";
+            top: "top";
+            bottom: "bottom";
+        }>>;
+        amount: z.ZodOptional<z.ZodNumber>;
+        selector: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    screenshot: z.ZodObject<{
+        format: z.ZodOptional<z.ZodEnum<{
+            png: "png";
+            jpeg: "jpeg";
+        }>>;
+        fullPage: z.ZodOptional<z.ZodBoolean>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    extract: z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            structured: "structured";
+        }>>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    'get-page-info': z.ZodObject<{}, z.core.$strip>;
+    fetch: z.ZodObject<{
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        body: z.ZodOptional<z.ZodString>;
+        returnType: z.ZodOptional<z.ZodEnum<{
+            text: "text";
+            json: "json";
+            binary: "binary";
+        }>>;
+    }, z.core.$strip>;
+    search: z.ZodObject<{
+        query: z.ZodString;
+        engine: z.ZodOptional<z.ZodString>;
+        page: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    'list-tabs': z.ZodObject<{}, z.core.$strip>;
+    'create-tab': z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>;
+    'close-tab': z.ZodObject<{
+        tabId: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    'activate-tab': z.ZodObject<{
+        tabId: z.ZodNumber;
+    }, z.core.$strip>;
+    wait: z.ZodObject<{
+        ms: z.ZodOptional<z.ZodNumber>;
+        selector: z.ZodOptional<z.ZodString>;
+        condition: z.ZodOptional<z.ZodEnum<{
+            load: "load";
+            networkidle: "networkidle";
+        }>>;
+    }, z.core.$strip>;
+    ping: z.ZodObject<{}, z.core.$strip>;
+    'get-status': z.ZodObject<{}, z.core.$strip>;
+    eval: z.ZodObject<{
+        expression: z.ZodString;
+    }, z.core.$strip>;
+};
+export type ParamsSchemaOf<M extends Method> = (typeof paramsSchemas)[M];
+/** 按 method 校验命令参数。未知字段被 strip，返回规范化后的参数。 */
+export declare function validateParams<M extends Method>(method: M, params: unknown): {
+    success: true;
+    data: ParamsMap[M];
+} | {
+    success: false;
+    error: z.ZodError;
+};
+export declare const requestSchema: z.ZodObject<{
+    id: z.ZodString;
+    method: z.ZodEnum<{
+        goto: "goto";
+        back: "back";
+        forward: "forward";
+        reload: "reload";
+        click: "click";
+        "click-text": "click-text";
+        fill: "fill";
+        type: "type";
+        press: "press";
+        hover: "hover";
+        select: "select";
+        scroll: "scroll";
+        screenshot: "screenshot";
+        extract: "extract";
+        "get-page-info": "get-page-info";
+        fetch: "fetch";
+        search: "search";
+        "list-tabs": "list-tabs";
+        "create-tab": "create-tab";
+        "close-tab": "close-tab";
+        "activate-tab": "activate-tab";
+        wait: "wait";
+        ping: "ping";
+        "get-status": "get-status";
+        eval: "eval";
+    }>;
+    params: z.ZodOptional<z.ZodUnknown>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    tabId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const commandResultSchema: z.ZodObject<{
+    sessionId: z.ZodOptional<z.ZodString>;
+    tabId: z.ZodOptional<z.ZodNumber>;
+    context: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        title: z.ZodString;
+        navId: z.ZodNumber;
+        tabId: z.ZodNumber;
+    }, z.core.$strip>>;
+    data: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const responseSchema: z.ZodObject<{
+    id: z.ZodString;
+    result: z.ZodObject<{
+        sessionId: z.ZodOptional<z.ZodString>;
+        tabId: z.ZodOptional<z.ZodNumber>;
+        context: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+            navId: z.ZodNumber;
+            tabId: z.ZodNumber;
+        }, z.core.$strip>>;
+        data: z.ZodUnknown;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const errorSchema: z.ZodObject<{
+    id: z.ZodString;
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            INVALID_REQUEST: "INVALID_REQUEST";
+            INVALID_PARAMS: "INVALID_PARAMS";
+            UNKNOWN_METHOD: "UNKNOWN_METHOD";
+            MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE";
+            EXTENSION_OFFLINE: "EXTENSION_OFFLINE";
+            EXTENSION_NO_TAB: "EXTENSION_NO_TAB";
+            SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+            SESSION_TAB_CLOSED: "SESSION_TAB_CLOSED";
+            TIMEOUT: "TIMEOUT";
+            TARGET_NOT_FOUND: "TARGET_NOT_FOUND";
+            TARGET_AMBIGUOUS: "TARGET_AMBIGUOUS";
+            URL_INVALID: "URL_INVALID";
+            HOST_NOT_ALLOWED: "HOST_NOT_ALLOWED";
+            EVAL_DISABLED: "EVAL_DISABLED";
+            PENDING_APPROVAL: "PENDING_APPROVAL";
+            APPROVAL_DENIED: "APPROVAL_DENIED";
+            APPROVAL_TIMEOUT: "APPROVAL_TIMEOUT";
+            INTERNAL: "INTERNAL";
+        }>;
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const eventSchema: z.ZodObject<{
+    event: z.ZodEnum<{
+        "extension.connected": "extension.connected";
+        "extension.disconnected": "extension.disconnected";
+        "extension.tab-activated": "extension.tab-activated";
+        "page.navigated": "page.navigated";
+        "approval.requested": "approval.requested";
+        "approval.responded": "approval.responded";
+        "approval.respond": "approval.respond";
+    }>;
+    params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;

package/dist/schemas.js

@@ -0,0 +1,153 @@
+import { z } from 'zod';
+import { ERROR_CODES } from './errors.js';
+import { EVENT_NAMES } from './envelope.js';
+import { METHODS } from './methods.js';
+/**
+ * Zod 校验层。原则（Postel's Law）：
+ * - 发送保守：schema 精确到每个命令的参数形状
+ * - 接收宽容：未知字段默认 strip，缺省字段用 optional/默认值
+ */
+// ---------------------------------------------------------------------------
+// 公共形状
+// ---------------------------------------------------------------------------
+export const contextSchema = z.object({
+    url: z.string(),
+    title: z.string(),
+    navId: z.number().int().nonnegative(),
+    tabId: z.number().int().nonnegative(),
+});
+export const viewportSchema = z.object({
+    width: z.number().nonnegative(),
+    height: z.number().nonnegative(),
+});
+export const elementInfoSchema = z.object({
+    tag: z.string(),
+    text: z.string().optional(),
+    attrs: z.record(z.string(), z.string()),
+    box: z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() }).optional(),
+});
+const httpUrlSchema = z.string().url();
+// ---------------------------------------------------------------------------
+// 每个命令的参数 schema
+// ---------------------------------------------------------------------------
+const noopSchema = z.object({});
+export const paramsSchemas = {
+    // 导航
+    goto: z.object({
+        url: httpUrlSchema,
+        waitUntil: z.enum(['load', 'domcontentloaded']).optional(),
+    }),
+    back: noopSchema,
+    forward: noopSchema,
+    reload: noopSchema,
+    // 交互
+    click: z.object({ selector: z.string().min(1) }),
+    'click-text': z.object({ text: z.string().min(1) }),
+    fill: z.object({ selector: z.string().min(1), value: z.string() }),
+    type: z.object({ selector: z.string().min(1), text: z.string() }),
+    press: z.object({ selector: z.string().min(1).optional(), key: z.string().min(1) }),
+    hover: z.object({ selector: z.string().min(1) }),
+    select: z
+        .object({
+        selector: z.string().min(1),
+        value: z.string().optional(),
+        label: z.string().optional(),
+    })
+        .refine((p) => p.value !== undefined || p.label !== undefined, {
+        message: 'select 需要提供 value 或 label（至少其一）',
+    }),
+    // 滚动 / 视图
+    scroll: z
+        .object({
+        direction: z.enum(['up', 'down', 'top', 'bottom']).optional(),
+        amount: z.number().optional(),
+        selector: z.string().min(1).optional(),
+    })
+        .refine((p) => p.direction !== undefined || p.amount !== undefined || p.selector !== undefined, {
+        message: 'scroll 需要提供 direction / amount / selector（至少其一）',
+    }),
+    screenshot: z.object({
+        format: z.enum(['png', 'jpeg']).optional(),
+        fullPage: z.boolean().optional(),
+        path: z.string().optional(),
+    }),
+    // 提取
+    extract: z.object({
+        mode: z.enum(['text', 'structured']).optional(),
+        limit: z.number().int().positive().optional(),
+    }),
+    'get-page-info': noopSchema,
+    // 页面内网络
+    fetch: z.object({
+        url: httpUrlSchema,
+        method: z.string().optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        body: z.string().optional(),
+        returnType: z.enum(['text', 'json', 'binary']).optional(),
+    }),
+    search: z.object({
+        query: z.string().min(1),
+        engine: z.string().optional(),
+        page: z.number().int().min(1).optional(),
+    }),
+    // 标签页
+    'list-tabs': noopSchema,
+    'create-tab': z.object({ url: httpUrlSchema }),
+    'close-tab': z.object({ tabId: z.number().int().nonnegative().optional() }),
+    'activate-tab': z.object({ tabId: z.number().int().nonnegative() }),
+    // 等待
+    wait: z
+        .object({
+        ms: z.number().nonnegative().optional(),
+        selector: z.string().min(1).optional(),
+        condition: z.enum(['networkidle', 'load']).optional(),
+    })
+        .refine((p) => p.ms !== undefined || p.selector !== undefined || p.condition !== undefined, {
+        message: 'wait 需要提供 ms / selector / condition（至少其一）',
+    }),
+    // 会话
+    ping: noopSchema,
+    'get-status': noopSchema,
+    // 高级
+    eval: z.object({ expression: z.string().min(1) }),
+};
+/** 按 method 校验命令参数。未知字段被 strip，返回规范化后的参数。 */
+export function validateParams(method, params) {
+    const result = paramsSchemas[method].safeParse(params ?? {});
+    return result.success
+        ? { success: true, data: result.data }
+        : { success: false, error: result.error };
+}
+// ---------------------------------------------------------------------------
+// 信封 schema
+// ---------------------------------------------------------------------------
+export const requestSchema = z.object({
+    id: z.string().min(1),
+    method: z.enum(METHODS),
+    params: z.unknown().optional(),
+    sessionId: z.string().optional(),
+    tabId: z.number().int().nonnegative().optional(),
+});
+export const commandResultSchema = z.object({
+    sessionId: z.string().optional(),
+    tabId: z.number().int().nonnegative().optional(),
+    context: contextSchema.optional(),
+    data: z.unknown(),
+});
+export const responseSchema = z.object({
+    id: z.string().min(1),
+    result: commandResultSchema,
+});
+export const errorSchema = z.object({
+    id: z.string().min(1),
+    error: z.object({
+        code: z.enum(ERROR_CODES),
+        message: z.string(),
+        data: z.record(z.string(), z.unknown()).optional(),
+    }),
+});
+export const eventSchema = z.object({
+    event: z.enum(EVENT_NAMES),
+    params: z.record(z.string(), z.unknown()),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+/** 公共数据形状（wire 协议的一部分，两端共享）。 */
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/**
+ * 上下文快照：每个命令响应都必须携带，Agent 据此自证"看到的是哪个页面"。
+ * - url / title 变化 → 页面跳转了
+ * - navId 递增 → 发生了导航（goto/back/forward/reload/SPA 路由，按实现能力）
+ * - tabId 变化 → 焦点被切走
+ */
+export interface ContextSnapshot {
+    url: string;
+    title: string;
+    navId: number;
+    tabId: number;
+}
+export interface ElementBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ElementInfo {
+    tag: string;
+    text?: string;
+    attrs: Record<string, string>;
+    box?: ElementBox;
+}
+export interface PageSnapshot {
+    context: ContextSnapshot;
+    visibleText: string;
+    viewport: Viewport;
+    scrollY: number;
+}
+export interface TabInfo {
+    id: number;
+    title: string;
+    url: string;
+    active: boolean;
+}
+export type SessionMode = 'auto' | 'ask';
+export interface SessionInfo {
+    id: string;
+    tabId?: number;
+    mode: SessionMode;
+    createdAt: string;
+    lastUsedAt: string;
+}
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet?: string;
+}
+/** search 的分页信息（哪一页的什么查询），便于 Agent 续取后续结果。 */
+export interface SearchPagination {
+    query: string;
+    engine: string;
+    page: number;
+}
+/** 定位器表示：CSS 选择器或可见文本（v1 两种，后续可扩展 css=/text=/role= 前缀）。 */
+export type Locator = {
+    type: 'css';
+    value: string;
+} | {
+    type: 'text';
+    value: string;
+};

package/dist/types.js

@@ -0,0 +1,3 @@
+/** 公共数据形状（wire 协议的一部分，两端共享）。 */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gCAAgC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@parkinglot/protocol",
+  "version": "0.1.0",
+  "description": "Shared protocol for ParkingLot: message envelope, command set, common types, validation.",
+  "license": "MIT",
+  "keywords": [
+    "parkinglot",
+    "browser",
+    "agent",
+    "protocol",
+    "cdp",
+    "playwright"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/myz-suite/parkinglot.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.5.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}