# agent-web-interface - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 agent-web-interface 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86
- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`skills/agent-web-interface/SKILL.md` Claim：`clm_0005` supported 0.86

## 它能做什么

- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`skills/agent-web-interface/SKILL.md` Claim：`clm_0001` supported 0.86
- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86
- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86

## 怎么开始

- `npx agent-web-interface install` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- `npx agent-web-interface install --harness claude-code` 证据：`README.md` Claim：`clm_0007` supported 0.86
- `npx agent-web-interface install --harness cursor` 证据：`README.md` Claim：`clm_0008` supported 0.86, `clm_0011` supported 0.86
- `npx agent-web-interface install --harness vscode` 证据：`README.md` Claim：`clm_0009` supported 0.86
- `npx agent-web-interface install --harness claude-desktop` 证据：`README.md` Claim：`clm_0010` supported 0.86
- `npx agent-web-interface install --harness cursor,vscode` 证据：`README.md` Claim：`clm_0011` supported 0.86
- `npx agent-web-interface install --harness all` 证据：`README.md` Claim：`clm_0012` supported 0.86
- `npx agent-web-interface doctor` 证据：`README.md` Claim：`clm_0013` supported 0.86
- `npx skills add lespaceman/agent-web-interface` 证据：`README.md` Claim：`clm_0014` supported 0.86
- `npx agent-web-interface` 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等

## 继续前判断卡

- **当前建议**：先做权限沙盒试用
- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。

### 30 秒判断

- **现在怎么做**：先做权限沙盒试用
- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装
- **先别相信**：工具权限边界不能在安装前相信。
- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86
- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`skills/agent-web-interface/SKILL.md` Claim：`clm_0005` supported 0.86
- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`skills/agent-web-interface/SKILL.md` Claim：`clm_0001` supported 0.86
- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86
- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86
- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86

### 现在还不能相信

- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/plugin.json`, `AGENTS.md`, `CLAUDE.md`, `skills/agent-web-interface/SKILL.md`
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/plugin.json`
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。
- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`, `README.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/plugin.json`, `AGENTS.md`, `CLAUDE.md`, `skills/agent-web-interface/SKILL.md`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/plugin.json`, `CLAUDE.md`, `README.md`
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0020` inferred 0.45
- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/plugin.json` Claim：`clm_0021` supported 0.86
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0022` supported 0.86
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`skills/agent-web-interface/SKILL.md` Claim：`clm_0001` supported 0.86
- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86
- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86

### 上下文规模

- 文件总数：215
- 重要文件覆盖：40/215
- 证据索引条目：61
- 角色 / Skill 条目：1

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 agent-web-interface 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 agent-web-interface 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 agent-web-interface 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```

## 角色 / Skill 索引

- 共索引 1 个角色 / Skill / 项目文档条目。

- **agent-web-interface**（skill）： 激活提示：当用户任务与“agent-web-interface”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/agent-web-interface/SKILL.md`

## 证据索引

- 共索引 61 条证据。

- **Agent Web Interface**（documentation）：Agent Web Interface is an MCP server that gives AI agents a compact, semantic interface to the browser. 证据：`README.md`
- **Trigger eval — agent-web-interface skill description**（documentation）：Trigger eval — agent-web-interface skill description 证据：`skills/agent-web-interface/evals/README.md`
- **Package**（package_manifest）：{ "name": "agent-web-interface", "version": "4.6.6", "description": "Token-efficient browser automation MCP for AI agents — semantic page snapshots and stable element IDs.", "type": "module", "main": "dist/src/index.js", "bin": { "agent-web-interface": "./dist/src/index.js" }, "scripts": { "build": "tsc --project tsconfig.build.json", "dev": "tsc --watch", "start": "node dist/src/index.js", "mcp:inspect": "npx @modelcontextprotocol/inspector node dist/src/index.js", "prepare": "husky", "type-check": "tsc --noEmit", "lint": "eslint .", "lint:fix": "eslint . --fix", "format": "prettier --write \" / .{ts,js,json,md}\"", "format:check": "prettier --check \" / .{ts,js,json,md}\"", "test": "vites… 证据：`package.json`
- **Snapshot & Interaction Pipeline — Audit Results**（documentation）：Snapshot & Interaction Pipeline — Audit Results 证据：`AGENTS.md`
- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`
- **Agent Web Interface Guide**（skill_instruction）：Use this skill to open live web pages, carry out actions, move through multi-step flows, validate page state, and capture selectors for automation. 证据：`skills/agent-web-interface/SKILL.md`
- **Plugin**（structured_config）：{ "name": "agent-web-interface", "version": "0.1.0", "description": "Claude Code plugin for browser automation" } 证据：`.claude-plugin/plugin.json`
- **License**（source_file）：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: 证据：`LICENSE`
- **Apple Cart Journey: Why Agent Web Interface Works for LLM Agents**（documentation）：Apple Cart Journey: Why Agent Web Interface Works for LLM Agents 证据：`docs/apple-cart-journey-mcp-design.md`
- **CAPTCHA Solving with Agent Web Interface**（documentation）：CAPTCHA Solving with Agent Web Interface 证据：`docs/captcha-solving-findings.md`
- **Ephemeral Elements Investigation Report**（documentation）：Ephemeral Elements Investigation Report 证据：`docs/ephemeral-elements-investigation.md`
- **Handle Non-DOM Dialogs**（documentation）：JavaScript dialogs block normal DOM interaction. When one is open, the page state exposes synthetic nd-dialog- controls. Use normal click and type calls against those controls. 证据：`docs/handle-non-dom-dialogs.md`
- **Handle Permission Requests With Click**（documentation）：Handle Permission Requests With Click 证据：`docs/handle-permission-requests-with-click.md`
- **Releasing Guide**（documentation）：This document describes how to release new versions of agent-web-interface to npm. 证据：`docs/releasing.md`
- **Upload Files With Click and Type**（documentation）：1. Click the multi-file upload control: 证据：`docs/upload-files-with-click-type.md`
- **Uploads assume MCP server and browser are co-located**（documentation）：Uploads assume MCP server and browser are co-located 证据：`docs/adr/0001-co-location-precondition-for-uploads.md`
- **The skill is one portable, tool-gating-free document delivered to every harness**（skill_instruction）：The skill is one portable, tool-gating-free document delivered to every harness 证据：`docs/adr/0002-portable-gating-free-skill.md`
- **Keep npx skills alongside the first-party installer**（documentation）：Keep npx skills alongside the first-party installer 证据：`docs/adr/0003-keep-npx-skills-alongside-installer.md`
- **Domain Docs**（documentation）：How the engineering skills should consume this repo's domain documentation when exploring the codebase. 证据：`docs/agents/domain.md`
- **Issue tracker: GitHub**（documentation）：Issues and PRDs for this repo live as GitHub issues. Use the gh CLI for all operations. 证据：`docs/agents/issue-tracker.md`
- **Triage Labels**（documentation）：The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. 证据：`docs/agents/triage-labels.md`
- **Cross-Baseline Region Deduplication**（documentation）：Cross-Baseline Region Deduplication 证据：`docs/plans/2026-01-31-cross-baseline-region-dedup-design.md`
- **Implicit Interactivity Detection — Implementation Plan**（documentation）：Implicit Interactivity Detection — Implementation Plan 证据：`docs/plans/2026-03-01-implicit-interactivity-detection-plan.md`
- **Implicit Interactivity Detection**（documentation）：Web applications frequently use non-semantic HTML elements , , with JavaScript click handlers for navigation and interaction. The current system only recognizes elements with semantic ARIA roles button, link, textbox, etc. as interactive. Non-semantic clickable elements get unknown- or rd- prefixed IDs that cannot be resolved by the click tool, blocking agents from interacting with table rows, cards, and other custom clickable components. 证据：`docs/plans/2026-03-01-implicit-interactivity-detection.md`
- **Multi-Tenancy Implementation Plan**（documentation）：For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. 证据：`docs/plans/2026-03-01-multi-tenancy.md`
- **Portal/Overlay Content Missing from Snapshots — Fix Plan**（documentation）：Portal/Overlay Content Missing from Snapshots — Fix Plan 证据：`docs/plans/2026-03-02-portal-overlay-snapshot-fix.md`
- **Deepen the Action Transaction: unify non-DOM surface detection**（documentation）：Deepen the Action Transaction: unify non-DOM surface detection 证据：`docs/plans/2026-06-16-deepen-action-transaction-non-dom-detection.md`
- **Non-DOM Tool Surface Consolidation**（documentation）：Task 1: Remove upload and handle dialog 证据：`docs/plans/2026-06-16-non-dom-tool-surface-consolidation.md`
- **Problem Statement**（documentation）：As an AI agent driving a browser through this MCP server, I can see certain interactions but I cannot perform them, and worse, attempting them silently wedges the page. 证据：`docs/plans/prd-non-dom-interaction-channel.md`
- **Http Entry**（source_file）：import http from 'node:http'; import express from 'express'; import { getServerConfig } from './server/server-config.js'; import { SessionRouter } from './gateway/session-router.js'; import { HttpGateway } from './gateway/http-gateway.js'; import { sendJsonRpcError } from './gateway/json-rpc-errors.js'; import { getLogger } from './shared/services/logging.service.js'; import { cleanupTempFiles } from './lib/temp-file.js'; ⋮---- export async function main : Promise ⋮---- const shutdown = async signal: string = 证据：`src/http-entry.ts`
- **Index**（source_file）：import { BrowserAutomationServer } from './server/mcp-server.js'; import { initServerConfig } from './server/server-config.js'; import { cleanupTempFiles } from './lib/temp-file.js'; import { VERSION } from './shared/version.js'; import { SessionRouter } from './gateway/session-router.js'; import { registerAllTools } from './tools/tool-registration.js'; import { dispatch } from './cli/dispatch.js'; ⋮---- function initializeServer : ⋮---- async function main : Promise ⋮---- const shutdown = signal: NodeJS.Signals = 证据：`src/index.ts`
- **Browser Session Config**（source_file）：import { isAbsolute } from 'node:path'; import { mkdirSync } from 'node:fs'; ⋮---- export type BrowserMode = typeof BROWSER MODES number ; ⋮---- export interface BrowserSessionConfig { browserMode?: BrowserMode; headless: boolean; cdpUrl?: string; stealth?: boolean; downloadDir?: string; } ⋮---- export function loadBrowserConfig : BrowserSessionConfig ⋮---- function resolveDownloadDir : string undefined 证据：`src/browser/browser-session-config.ts`
- **Ensure Browser**（source_file）：import type { SessionManager } from './session-manager.js'; import type { BrowserMode, BrowserSessionConfig } from './browser-session-config.js'; import { extractErrorMessage } from './connection-utils.js'; import { getLogger } from '../shared/services/logging.service.js'; ⋮---- export async function ensureBrowserReady session: SessionManager, config: BrowserSessionConfig : Promise ⋮---- async function attemptMode session: SessionManager, mode: BrowserMode, config: BrowserSessionConfig : Promise 证据：`src/browser/ensure-browser.ts`
- **Page Registry**（source_file）：import type { Page } from 'puppeteer-core'; import type { CdpClient } from '../cdp/cdp-client.interface.js'; import { randomUUID } from 'crypto'; ⋮---- export interface PageHandle { page id: string; page: Page; cdp: CdpClient; created at: Date; url?: string; title?: string; } ⋮---- export class PageRegistry ⋮---- register page: Page, cdp: CdpClient : PageHandle ⋮---- get page id: string : PageHandle undefined ⋮---- remove page id: string : boolean ⋮---- list : PageHandle ⋮---- clear : void ⋮---- size : number ⋮---- has page id: string : boolean ⋮---- replace page id: string, handle: PageHandle : boolean ⋮---- updateMetadata page id: string, metadata: Partial : boolean ⋮---- findByPage page:… 证据：`src/browser/page-registry.ts`
- **Session Manager**（source_file）：import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; import puppeteer, { type Browser, type BrowserContext, type Page, TargetType, } from 'puppeteer-core'; import { PuppeteerCdpClient } from '../cdp/puppeteer-cdp-client.js'; import { applyStealthToPage, buildStealthLaunchOptions } from './stealth.js'; import { PageRegistry, type PageHandle } from './page-registry.js'; import { getLogger } from '../shared/services/logging.service.js'; import { BrowserSessionError } from '../shared/errors/browser-session.error.js'; import type { ConnectionHealth } from '../state/health.types.js'; import { observationAccumulator } from '../observation/index.js'; import { waitForNet… 证据：`src/browser/session-manager.ts`
- **Session Manager.Types**（source_file）：export type ChromeChannel = typeof CHROME CHANNELS number ; ⋮---- export type ConnectionState = 'idle' 'connecting' 'connected' 'disconnecting' 'failed'; ⋮---- export interface ConnectionStateChangeEvent { previousState: ConnectionState; currentState: ConnectionState; timestamp: Date; } ⋮---- export interface StorageState { cookies: { name: string; value: string; domain: string; path: string; expires: number; httpOnly: boolean; secure: boolean; sameSite?: 'Strict' 'Lax' 'None'; } ; origins: { origin: string; localStorage: { name: string; value: string } ; } ; } ⋮---- export interface LaunchOptions { headless?: boolean; viewport?: { width: number; height: number }; channel?: ChromeChannel; e… 证据：`src/browser/session-manager.types.ts`
- **Stealth**（source_file）：import type { CdpClient } from '../cdp/cdp-client.interface.js'; ⋮---- export interface StealthLaunchOptions { args: string ; ignoreDefaultArgs: string ; } ⋮---- export function buildStealthLaunchOptions stealth: boolean : StealthLaunchOptions ⋮---- export function buildStealthEvasionScript opts: ⋮---- export interface ApplyStealthOptions { headless: boolean; } ⋮---- export async function applyStealthToPage cdp: CdpClient, opts: ApplyStealthOptions : Promise 证据：`src/browser/stealth.ts`
- **Index**（source_file）：import type { HarnessAdapter, ApplyResult } from './harness-adapter.js'; import type { CommandRunner } from './harness/claude-code.js'; import { parseInstallFlags, buildServerCommand } from './flags.js'; import { ALL ADAPTERS, detectAdapters, getAdapter } from './registry.js'; ⋮---- export interface InstallDeps { claudeCodeRunner?: CommandRunner; isTTY?: boolean; cwd?: string; homeDir?: string; } ⋮---- interface HarnessResult { adapter: HarnessAdapter; result?: ApplyResult; error?: string; } ⋮---- function printSummaryTable results: HarnessResult : void ⋮---- async function printClackSummary results: HarnessResult : Promise ⋮---- async function applyAdapters adapters: HarnessAdapter , flags… 证据：`src/install/index.ts`
- **Mcp Server**（source_file）：import { EventEmitter } from 'events'; import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import type { ZodRawShape } from 'zod'; import { getLogger, type LogLevel, type McpNotificationSender, } from '../shared/services/logging.service.js'; import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js'; import type { ToolRegistrar } from './tool-registrar.types.js'; import { wrapToolHandler } from './tool-result-handler.js'; ⋮---- export interface ServerConfig { name: string; version: string; } ⋮---- export interface SessionStartEvent { clientInfo: { name: string; version: string… 证据：`src/server/mcp-server.ts`
- **Server Config**（source_file）：import { parseArgs, type ServerArgs } from '../cli/args.js'; ⋮---- export function initServerConfig argv: string : void ⋮---- export function getServerConfig : ServerArgs ⋮---- export function resetServerState : void 证据：`src/server/server-config.ts`
- **Element Resolver**（source_file）：import type { CdpClient } from '../cdp/cdp-client.interface.js'; ⋮---- function computeModifiers modifiers?: string : number ⋮---- async function scrollAndGetContentQuad cdp: CdpClient, backendNodeId: number : Promise ⋮---- export async function getElementTopLeft cdp: CdpClient, backendNodeId: number : Promise ⋮---- export async function clickByBackendNodeId cdp: CdpClient, backendNodeId: number, modifiers?: string : Promise ⋮---- export async function clickAtCoordinates cdp: CdpClient, x: number, y: number, modifiers?: string : Promise ⋮---- export async function clickAtElementOffset cdp: CdpClient, backendNodeId: number, offsetX: number, offsetY: number, modifiers?: string : Promise ⋮----… 证据：`src/snapshot/element-resolver.ts`
- **Heading Index**（source_file）：import type { DomExtractionResult, AxExtractionResult } from './extractors/index.js'; import { resolveLabel } from './extractors/index.js'; import { getTextContent } from '../lib/text-utils.js'; import type { AdjacencyMaps, IdMapsByContext } from './frame-context.js'; import { getIdMapForNode } from './frame-context.js'; ⋮---- export function buildHeadingIndex domResult: DomExtractionResult, axResult: AxExtractionResult undefined, idMapsByContext: IdMapsByContext, adjacencyMaps: AdjacencyMaps : Map ⋮---- function isHeading backendNodeId: number : ⋮---- function traverse nodeId: number, currentHeading: string undefined : string undefined 证据：`src/snapshot/heading-index.ts`
- **Kind Mapping**（source_file）：import type { NodeKind, SnapshotOptions } from './snapshot.types.js'; ⋮---- export interface CompileOptions extends Partial { includeReadable?: boolean; includeLayout?: boolean; } ⋮---- export function mapRoleToKind role: string undefined : NodeKind undefined ⋮---- export function getKindFromTag tagName: string : NodeKind undefined 证据：`src/snapshot/kind-mapping.ts`
- **Node Filter**（source_file）：import type { ReadableNode } from './snapshot.types.js'; import type { RawNodeData, RawDomNode, RawAxNode } from './extractors/index.js'; import { isInteractiveKind } from '../state/actionables-filter.js'; ⋮---- export function filterNoiseNodes nodes: ReadableNode , domTree: Map , axTree: Map : ReadableNode ⋮---- const hasInteractiveDescendant = nodeId: number : boolean = ⋮---- const getParentLabel = nodeId: number : string undefined = ⋮---- export function sliceWithOverlayPriority nodes: RawNodeData , maxNodes: number : RawNodeData 证据：`src/snapshot/node-filter.ts`
- **Node Synthesizer**（source_file）：import type { RawNodeData, RawDomNode, RawAxNode, DomExtractionResult, } from './extractors/index.js'; import { getTextContent } from '../lib/text-utils.js'; ⋮---- export function isToastLibraryNode domNode: RawDomNode : boolean ⋮---- export function synthesizeOptionNodes nodesToProcess: RawNodeData , domResult: DomExtractionResult : void ⋮---- const collectOptions = parentId: number = ⋮---- // Transfer selected attribute to AX property ⋮---- export function synthesizeCanvasNodes nodesToProcess: RawNodeData , domResult: DomExtractionResult : void ⋮---- / Promote unsemantic toast library nodes to alert role. Popular toast libraries Sonner, react-hot-toast, Toastify, Ant Design, Chakra UI don… 证据：`src/snapshot/node-synthesizer.ts`
- **Snapshot Compiler**（source_file）：import type { Page } from 'puppeteer-core'; import type { CdpClient } from '../cdp/cdp-client.interface.js'; import type { BaseSnapshot, ReadableNode, NodeKind, SnapshotMeta, NodeLocation, NodeLayout, NodeState, NodeLocators, } from './snapshot.types.js'; import { createExtractorContext, extractDom, extractAx, extractLayout, extractState, resolveLabel, resolveRegion, buildLocators, resolveGrouping, classifyAxRole, extractAttributes, LIVE REGION AX ROLES, type RawNodeData, type RawDomNode, type RawAxNode, type DomExtractionResult, type AxExtractionResult, type LayoutExtractionResult, type ExtractorContext, } from './extractors/index.js'; import { detectInteractivity } from './extractors/inte… 证据：`src/snapshot/snapshot-compiler.ts`
- **Snapshot Store**（source_file）：import type { BaseSnapshot, ReadableNode } from './snapshot.types.js'; ⋮---- export interface SnapshotEntry { snapshot: BaseSnapshot; storedAt: number; pageId: string; } ⋮---- export interface SnapshotStoreOptions { ttlMs?: number; cleanupIntervalMs?: number; } ⋮---- export interface SnapshotStoreStats { snapshotCount: number; totalNodes: number; oldestSnapshot?: number; newestSnapshot?: number; } ⋮---- export class SnapshotStore ⋮---- constructor options?: SnapshotStoreOptions ⋮---- private startCleanupTimer intervalMs: number : void ⋮---- stopCleanupTimer : void ⋮---- store pageId: string, snapshot: BaseSnapshot : void ⋮---- get snapshotId: string : BaseSnapshot undefined ⋮---- getEntry s… 证据：`src/snapshot/snapshot-store.ts`
- **Form Tools**（source_file）：import { z } from 'zod'; import type { ToolContext } from './tool-context.types.js'; import { detectForms, computeFormState, readRuntimeValues, type FormRegion, type FormField, type FormAction, type FieldDependency, type FieldValueRequest, } from '../form/index.js'; import { escapeXml } from '../lib/text-utils.js'; import type { ElementRegistry } from '../state/element-registry.js'; import type { ReadableNode } from '../snapshot/snapshot.types.js'; ⋮---- function resolveFormEids forms: FormRegion , registry: ElementRegistry, nodes?: ReadableNode : void ⋮---- const resolve = backendNodeId: number ⋮---- export type GetFormUnderstandingInput = z.infer ; ⋮---- export type GetFieldContextInput =… 证据：`src/tools/form-tools.ts`
- **Interaction Tools**（source_file）：import { clickByBackendNodeId, clickAtCoordinates, clickAtElementOffset, typeByBackendNodeId, pressKey, selectOption, hoverByBackendNodeId, type ReadableNode, } from '../snapshot/index.js'; import { ClickInputSchema, TypeInputSchema, PressInputSchema, SelectInputSchema, HoverInputSchema, } from './tool-schemas.js'; import { executeAction, executeActionWithRetry, type CaptureSnapshotFn } from './execute-action.js'; import { createActionCapture, prepareActionContext } from './action-context.js'; import type { ToolContext } from './tool-context.types.js'; import { getOrCreateDialogManager } from '../non-dom/dialog-manager.js'; import { getOrCreatePermissionDetector } from '../non-dom/permissio… 证据：`src/tools/interaction-tools.ts`
- **Observation Tools**（source_file）：import { scrollIntoView, scrollPage as scrollPageByAmount } from '../snapshot/index.js'; import { ATTACHMENT SIGNIFICANCE THRESHOLD } from '../observation/observation.types.js'; import type { NodeDetails } from './tool-schemas.js'; import { CaptureSnapshotInputSchema, FindElementsInputSchema, GetNodeDetailsInputSchema, ScrollElementIntoViewInputSchema, ScrollPageInputSchema, } from './tool-schemas.js'; import { QueryEngine } from '../query/query-engine.js'; import type { FindElementsRequest } from '../query/types/query.types.js'; import type { NodeKind, SemanticRegion } from '../snapshot/snapshot.types.js'; import { isReadableNode, isStructuralNode, isLiveRegionNode } from '../snapshot/snap… 证据：`src/tools/observation-tools.ts`
- **Tool Registration**（source_file）：import type { ToolContext } from './tool-context.types.js'; import type { ToolRegistrar } from '../server/tool-registrar.types.js'; ⋮---- import { listPages, closePage } from './navigation-tools.js'; import { navigate, goBack, goForward, reload } from './navigation-tools.js'; import { captureSnapshot, findElements, getNodeDetails, scrollElementIntoView, scrollPage, } from './observation-tools.js'; import { click, type, press, select, hover } from './interaction-tools.js'; import { drag, wheel, takeScreenshot } from './viewport-tools.js'; import { inspectCanvas } from './canvas-tools.js'; import { getFormUnderstanding, getFieldContext } from './form-tools.js'; import { readPage } from './rea… 证据：`src/tools/tool-registration.ts`
- **4.6.6 - 2026-07-04**（documentation）：- docs tools : enrich tool + param descriptions for LLM discoverability 99 - docs: add website link near top of README 100 证据：`CHANGELOG.md`
- **Agent Web Interface**（documentation）：An MCP server for AI-driven browser automation. It produces semantic page snapshots and exposes tools for an AI agent to observe and act on web pages. 证据：`CONTEXT.md`
- **Generate Apple.com iPhone-to-Cart Tool Use Example**（documentation）：Generate Apple.com iPhone-to-Cart Tool Use Example 证据：`commands/generate-apple-doc.md`
- **.Mcp**（structured_config）：{ "mcpServers": { "agent-web-interface-dev": { "command": "node", "args": "dist/src/index.js" , "cwd": "/Users/nadeem/athena/agent-web-interface" } } } 证据：`.mcp.json`
- **.Prettierrc**（structured_config）：{ "semi": true, "trailingComma": "es5", "singleQuote": true, "printWidth": 100, "tabWidth": 2, "useTabs": false, "arrowParens": "always", "endOfLine": "lf" } 证据：`.prettierrc.json`
- **Skills Lock**（structured_config）：{ "version": 1, "skills": { "agent-web-interface": { "source": "lespaceman/agent-web-interface", "sourceType": "github", "skillPath": "skills/agent-web-interface/SKILL.md", "computedHash": "76952e2c466a5942e97f901fc669dce29ff19ef4eb9c2c64e2bbb633a6235e2c" }, "diagnose": { "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/diagnose/SKILL.md", "computedHash": "15939a26f86edec2d4862042b8564e5a062cb81d04e047a0cea6305c8830b5f5" } } } 证据：`skills-lock.json`
- **Tsconfig.Build**（structured_config）：{ "extends": "./tsconfig.json", "include": "src/ / .ts", " .ts" , "exclude": "node modules", "dist", "tests" } 证据：`tsconfig.build.json`
- **Tsconfig**（structured_config）：{ "compilerOptions": { "target": "ES2022", "module": "nodenext", "lib": "ES2022" , "moduleResolution": "nodenext", "outDir": "./dist", "rootDir": "./", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "resolveJsonModule": true, "declaration": true, "declarationMap": true, "sourceMap": true, "types": "node" }, "include": "src/ / .ts", "tests/ / .ts", " .ts" , "exclude": "node modules", "dist" } 证据：`tsconfig.json`
- **Train Queries**（structured_config）：{ "id": "HP1", "query": "open https://news.ycombinator.com and tell me the top 3 story titles right now", "should trigger": true }, { "id": "HP2", "query": "is the cookie banner still covering the signup CTA on acme.com? we shipped a fix about an hour ago — can you check", "should trigger": true }, { "id": "HP4", "query": "confirm the prod homepage at https://app.acme.io still loads after the deploy and the nav actually renders", "should trigger": true }, { "id": "HP6", "query": "walk the add-to-cart then checkout flow on https://shop.demo.io and tell me where it breaks", "should trigger": true }, { "id": "HP8", "query": "explore the filters on airbnb.com and note how the results change whe… 证据：`skills/agent-web-interface/evals/train_queries.json`
- 其余 1 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `skills/agent-web-interface/evals/README.md`, `package.json`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `skills/agent-web-interface/evals/README.md`, `package.json`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概述与三层架构**：importance `high`
  - source_paths: README.md, src/index.ts, src/server/mcp-server.ts, src/server/server-config.ts, src/http-entry.ts
- **浏览器生命周期、CDP 与 Worker 管理**：importance `high`
  - source_paths: src/browser/browser-session-config.ts, src/browser/ensure-browser.ts, src/browser/session-manager.ts, src/browser/session-manager.types.ts, src/browser/stealth.ts
- **语义快照生成与元素状态系统**：importance `high`
  - source_paths: src/snapshot/snapshot-compiler.ts, src/snapshot/snapshot-store.ts, src/snapshot/element-resolver.ts, src/snapshot/node-synthesizer.ts, src/snapshot/node-filter.ts
- **MCP 工具集与非 DOM 表面统一**：importance `high`
  - source_paths: src/tools/tool-registration.ts, src/tools/browser-tools.ts, src/tools/interaction-tools.ts, src/tools/navigation-tools.ts, src/tools/observation-tools.ts

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `cd8eaec0356b0440ac5d4aee3e25892d8fdf273d`
- inspected_files: `Dockerfile`, `README.md`, `package.json`, `docs/adr/0001-co-location-precondition-for-uploads.md`, `docs/adr/0002-portable-gating-free-skill.md`, `docs/adr/0003-keep-npx-skills-alongside-installer.md`, `docs/agents/domain.md`, `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/apple-cart-journey-mcp-design.md`, `docs/captcha-solving-findings.md`, `docs/ephemeral-elements-investigation.md`, `docs/handle-non-dom-dialogs.md`, `docs/handle-permission-requests-with-click.md`, `docs/plans/2026-01-31-cross-baseline-region-dedup-design.md`, `docs/plans/2026-03-01-implicit-interactivity-detection-plan.md`, `docs/plans/2026-03-01-implicit-interactivity-detection.md`, `docs/plans/2026-03-01-multi-tenancy.md`, `docs/plans/2026-03-02-portal-overlay-snapshot-fix.md`, `docs/plans/2026-06-16-deepen-action-transaction-non-dom-detection.md`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 失败模式：security_permissions: Add end-to-end acceptance suite for non-DOM surfaces

- Trigger: Developers should check this security_permissions risk before relying on the project: Add end-to-end acceptance suite for non-DOM surfaces
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Add end-to-end acceptance suite for non-DOM surfaces. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may expose sensitive permissions or credentials: Add end-to-end acceptance suite for non-DOM surfaces
- Evidence: failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/90 | Add end-to-end acceptance suite for non-DOM surfaces
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 失败模式：security_permissions: PRD: Unify non-DOM surfaces with snapshot action semantics

- Trigger: Developers should check this security_permissions risk before relying on the project: PRD: Unify non-DOM surfaces with snapshot action semantics
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: PRD: Unify non-DOM surfaces with snapshot action semantics. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may expose sensitive permissions or credentials: PRD: Unify non-DOM surfaces with snapshot action semantics
- Evidence: failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/85 | PRD: Unify non-DOM surfaces with snapshot action semantics
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 失败模式：security_permissions: Represent permission and download non-DOM surfaces

- Trigger: Developers should check this security_permissions risk before relying on the project: Represent permission and download non-DOM surfaces
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Represent permission and download non-DOM surfaces. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may expose sensitive permissions or credentials: Represent permission and download non-DOM surfaces
- Evidence: failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/88 | Represent permission and download non-DOM surfaces
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 失败模式：security_permissions: Update agent-web-interface skill for non-DOM surfaces

- Trigger: Developers should check this security_permissions risk before relying on the project: Update agent-web-interface skill for non-DOM surfaces
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Update agent-web-interface skill for non-DOM surfaces. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Developers may expose sensitive permissions or credentials: Update agent-web-interface skill for non-DOM surfaces
- Evidence: failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/89 | Update agent-web-interface skill for non-DOM surfaces
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 失败模式：installation: Release v4.4.0

- Trigger: Developers should check this installation risk before relying on the project: Release v4.4.0
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Release v4.4.0. Context: Source discussion did not expose a precise runtime context.
- Why it matters: Upgrade or migration may change expected behavior: Release v4.4.0
- Evidence: failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.4.0 | Release v4.4.0
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 失败模式：installation: Release v4.6.2

- Trigger: Developers should check this installation risk before relying on the project: Release v4.6.2
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Release v4.6.2. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: Release v4.6.2
- Evidence: failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.2 | Release v4.6.2
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 失败模式：installation: Release v4.6.3

- Trigger: Developers should check this installation risk before relying on the project: Release v4.6.3
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Release v4.6.3. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: Release v4.6.3
- Evidence: failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.3 | Release v4.6.3
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 失败模式：installation: Release v4.6.4

- Trigger: Developers should check this installation risk before relying on the project: Release v4.6.4
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Release v4.6.4. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: Release v4.6.4
- Evidence: failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.4 | Release v4.6.4
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 失败模式：installation: Release v4.6.5

- Trigger: Developers should check this installation risk before relying on the project: Release v4.6.5
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Release v4.6.5. Context: Observed when using node, docker
- Why it matters: Upgrade or migration may change expected behavior: Release v4.6.5
- Evidence: failure_mode_cluster:github_release | https://github.com/lespaceman/agent-web-interface/releases/tag/v4.6.5 | Release v4.6.5
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 失败模式：installation: Remove upload and handle_dialog MCP tools

- Trigger: Developers should check this installation risk before relying on the project: Remove upload and handle_dialog MCP tools
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: Remove upload and handle_dialog MCP tools. Context: Observed during installation or first-run setup.
- Why it matters: Developers may fail before the first successful local run: Remove upload and handle_dialog MCP tools
- Evidence: failure_mode_cluster:github_issue | https://github.com/lespaceman/agent-web-interface/issues/92 | Remove upload and handle_dialog MCP tools
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。