# @askjo/camofox-browser - Doramagic AI Context Pack

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

## 充分原则

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

## 给宿主 AI 的使用方式

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

## Claim 消费规则

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

## 它最适合谁

- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0025` supported 0.86

## 它能做什么

- **Anti-Detection Browser Engine**（需要安装后验证）：Camoufox-based Firefox fork with C++-level fingerprint spoofing (navigator.hardwareConcurrency, WebGL, AudioContext, screen geometry, WebRTC) that bypasses Google, Cloudflare, and most bot detection. 证据：`README.md`, `package.json`, `Dockerfile` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等
- **REST API Server with Tab Management**（需要安装后验证）：Express-based HTTP server on port 9377 (configurable) providing tab creation, navigation, listing, and closure with per-user session isolation. 证据：`AGENTS.md`, `server.js`, `openapi.json` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Accessibility Snapshot with Element Refs**（需要安装后验证）：DOM-to-ARIA accessibility tree snapshots with stable e1/e2/e3 element references for reliable element targeting, ~90% smaller than raw HTML. 证据：`server.js`, `AGENTS.md`, `server.js` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Element Interaction (Click, Type, Scroll)**（需要安装后验证）：Click/type using element refs or CSS selectors with auto-refresh of stale refs from dynamic SPAs, plus scroll and keyboard press capabilities. 证据：`AGENTS.md`, `server.js`, `package.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Session Isolation with Cookie Import**（需要安装后验证）：Per-user cookie/storage isolation via userId, with Netscape-format cookie file import and Playwright storageState for authenticated browsing. 证据：`AGENTS.md`, `server.js`, `openapi.json` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Search Macros**（需要安装后验证）：URL expansion macros for common sites (@google_search, @youtube_search, @amazon_search, @reddit_search, @wikipedia_search, @twitter_search, @yelp_search, @linkedin_search) instead of manual URL construction. 证据：`AGENTS.md`, `lib/macros.js` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Screenshot Capture**（需要安装后验证）：Base64 PNG screenshot capture alongside accessibility snapshots, useful for visual verification and debugging. 证据：`README.md`, `package.json` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等
- **Download Capture**（需要安装后验证）：Browser download capture with programmatic access via API, including optional inline base64 encoding for direct retrieval. 证据：`changelog/1.4.0.md`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **DOM Image Extraction**（需要安装后验证）：List img src/alt attributes from page DOM, optionally returning inline data URLs for product photos, charts, or web app images. 证据：`README.md`, `changelog/1.4.0.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **JavaScript Evaluation**（需要安装后验证）：Execute arbitrary JavaScript in page context for reading state, calling web app APIs, or injecting scripts. 证据：`package.json`, `changelog/1.4.0.md` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等
- **Proxy Pool with GeoIP**（需要安装后验证）：Residential proxy support with automatic locale/timezone spoofing, round-robin and backconnect strategies, and provider-specific username rewriting. 证据：`lib/proxy.js`, `README.md`, `lib/proxy.js` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **YouTube Transcript Extraction**（可做安装前预览）：Extract captions from any YouTube video via yt-dlp (fast path) with Playwright browser fallback, no API key needed. 证据：`plugins/youtube/index.js`, `plugins/youtube/youtube.js`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **VNC Interactive Access**（可做安装前预览）：Interactive browser access via noVNC for visual login, CAPTCHA solving, OAuth approval, with storage state export for agent reuse. 证据：`plugins/vnc/index.js`, `plugins/vnc/vnc-launcher.js`, `plugins/vnc/README.md` Claim：`clm_0013` supported 0.86
- **Session Persistence**（可做安装前预览）：Saves and restores per-user browser storage state (cookies + localStorage) across restarts using Playwright storageState API, with SHA256-hashed profile directories. 证据：`plugins/persistence/index.js`, `plugins/persistence/README.md`, `lib/persistence.js` Claim：`clm_0014` supported 0.86
- **Structured Data Extraction**（需要安装后验证）：POST /tabs/:tabId/extract with JSON Schema that maps properties to snapshot refs via x-ref extension for deterministic structured output. 证据：`lib/extract.js`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **Session Tracing**（可做安装前预览）：Opt-in per-session Playwright trace capture (screenshots + DOM snapshots + network) with API endpoints to list, fetch, and delete trace ZIPs. 证据：`README.md`, `openapi.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0005` supported 0.86, `clm_0007` supported 0.86 等
- **Anonymized Crash/Hang Telemetry**（可做安装前预览）：Automatic anonymized crash/hang telemetry via GitHub Issues with HMAC-hashed private domains, public domains verbatim, and opt-out via CAMOFOX_CRASH_REPORT_ENABLED=false. 证据：`lib/reporter.js`, `openclaw.plugin.json`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **Prometheus Metrics**（可做安装前预览）：Lazy-loaded Prometheus metrics endpoint with off-by-default activation via PROMETHEUS_ENABLED=1. 证据：`AGENTS.md`, `package.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **OpenAPI Documentation**（可做安装前预览）：Auto-generated OpenAPI 3.0.3 spec at /openapi.json and interactive Swagger UI at /docs. 证据：`lib/openapi.js`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **Plugin System**（可做安装前预览）：Config-driven plugin loader with event bus (emitAsync/emit) supporting lifecycle hooks, route registration, and isolated child_process management per plugin. 证据：`lib/plugins.js`, `camofox.config.json`, `scripts/plugin.js` Claim：`clm_0020` supported 0.86
- **Docker Deployment**（可做安装前预览）：Containerized deployment via Docker, Fly.io, or Railway with lazy browser launch and idle shutdown keeping memory at ~40MB when idle. 证据：`Dockerfile`, `Dockerfile.ci`, `railway.toml`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **OpenClaw Plugin Integration**（需要安装后验证）：TypeScript-based OpenClaw plugin providing 11 browser automation tools (camofox_create_tab, snapshot, click, type, navigate, scroll, screenshot, close_tab, evaluate, list_tabs, import_cookies). 证据：`package.json`, `plugin.ts`, `openclaw.plugin.json` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0010` supported 0.86 等
- **Large Page Handling with Pagination**（需要安装后验证）：Automatic snapshot truncation for large pages with offset-based pagination to handle SPAs and content-heavy pages. 证据：`README.md`, `server.js` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Access Control (API Key / Access Key)**（可做安装前预览）：Bearer token authentication via CAMOFOX_API_KEY for sensitive endpoints and CAMOFOX_ACCESS_KEY as global gate for all routes except /health. 证据：`lib/auth.js`, `openapi.json`, `openclaw.plugin.json` Claim：`clm_0002` supported 0.86, `clm_0005` supported 0.86, `clm_0016` supported 0.86, `clm_0017` supported 0.86 等

## 怎么开始

- `git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser` 证据：`README.md` Claim：`clm_0026` supported 0.86
- `npm install && npm start` 证据：`README.md` Claim：`clm_0027` supported 0.86
- `npx @askjo/camofox-browser` 证据：`README.md` Claim：`clm_0028` supported 0.86
- `git clone https://github.com/jo-inc/camofox-browser` 证据：`README.md` Claim：`clm_0026` supported 0.86, `clm_0029` supported 0.86
- `curl -X POST http://localhost:9377/tabs \` 证据：`README.md` Claim：`clm_0030` supported 0.86, `clm_0041` supported 0.86, `clm_0042` supported 0.86, `clm_0043` supported 0.86
- `curl -X DELETE http://localhost:9377/sessions/agent1` 证据：`README.md` Claim：`clm_0031` supported 0.86, `clm_0035` supported 0.86
- `curl http://localhost:9377/sessions/agent1/traces` 证据：`README.md` Claim：`clm_0032` supported 0.86, `clm_0033` supported 0.86
- `curl http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip > session.zip` 证据：`README.md` Claim：`clm_0033` supported 0.86
- `npx playwright show-trace session.zip` 证据：`README.md` Claim：`clm_0034` supported 0.86
- `curl -X DELETE http://localhost:9377/sessions/agent1/traces/trace-2026-04-18T04-05-00-abc.zip` 证据：`README.md` Claim：`clm_0035` supported 0.86

## 继续前判断卡

- **当前建议**：需要管理员/安全审批
- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。

### 30 秒判断

- **现在怎么做**：需要管理员/安全审批
- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装
- **先别相信**：工具权限边界不能在安装前相信。
- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件

### 现在可以相信

- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0025` supported 0.86
- **能力存在：Anti-Detection Browser Engine**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `package.json`, `Dockerfile` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86
- **能力存在：REST API Server with Tab Management**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `server.js`, `openapi.json` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86
- **能力存在：Accessibility Snapshot with Element Refs**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`server.js`, `AGENTS.md`, `server.js` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86
- **能力存在：Element Interaction (Click, Type, Scroll)**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `server.js`, `package.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86
- **能力存在：Session Isolation with Cookie Import**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`AGENTS.md`, `server.js`, `openapi.json` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86

### 现在还不能相信

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

### 继续会触碰什么

- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`AGENTS.md`, `README.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `openclaw.plugin.json`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`AGENTS.md`, `Dockerfile`, `README.md`, `changelog/1.4.0.md` 等
- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `docs/openapi.json`, `openapi.json`, `openclaw.plugin.json` 等
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

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

### 退出方式

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

## 哪些只能预览

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

## 哪些必须安装后验证

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

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0048` inferred 0.45
- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`openclaw.plugin.json` Claim：`clm_0049` supported 0.86
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`AGENTS.md`, `README.md` Claim：`clm_0050` 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。

### 任务路由

- **Anti-Detection Browser Engine**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `package.json`, `Dockerfile` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等
- **REST API Server with Tab Management**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `server.js`, `openapi.json` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Accessibility Snapshot with Element Refs**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`server.js`, `AGENTS.md`, `server.js` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Element Interaction (Click, Type, Scroll)**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `server.js`, `package.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Session Isolation with Cookie Import**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `server.js`, `openapi.json` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Search Macros**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`AGENTS.md`, `lib/macros.js` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86 等
- **Screenshot Capture**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `package.json` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等
- **Download Capture**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`changelog/1.4.0.md`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **DOM Image Extraction**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `changelog/1.4.0.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **JavaScript Evaluation**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`package.json`, `changelog/1.4.0.md` Claim：`clm_0001` supported 0.86, `clm_0004` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等
- **Proxy Pool with GeoIP**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`lib/proxy.js`, `README.md`, `lib/proxy.js` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **YouTube Transcript Extraction**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`plugins/youtube/index.js`, `plugins/youtube/youtube.js`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **VNC Interactive Access**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`plugins/vnc/index.js`, `plugins/vnc/vnc-launcher.js`, `plugins/vnc/README.md` Claim：`clm_0013` supported 0.86
- **Session Persistence**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`plugins/persistence/index.js`, `plugins/persistence/README.md`, `lib/persistence.js` Claim：`clm_0014` supported 0.86
- **Structured Data Extraction**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`lib/extract.js`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **Session Tracing**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`README.md`, `openapi.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0005` supported 0.86, `clm_0007` supported 0.86 等
- **Anonymized Crash/Hang Telemetry**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`lib/reporter.js`, `openclaw.plugin.json`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **Prometheus Metrics**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`AGENTS.md`, `package.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **OpenAPI Documentation**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`lib/openapi.js`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0009` supported 0.86 等
- **Plugin System**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`lib/plugins.js`, `camofox.config.json`, `scripts/plugin.js` Claim：`clm_0020` supported 0.86

### 上下文规模

- 文件总数：79
- 重要文件覆盖：40/79
- 证据索引条目：63
- 角色 / Skill 条目：9

### 证据不足时的处理

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

## Prompt Recipes

### 适配判断

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

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

### 安装前体验

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

```text
请把 @askjo/camofox-browser 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
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
请基于 @askjo/camofox-browser 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```


## 角色 / Skill 索引

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

- **camofox-browser Agent Guide**（project_doc）：Headless browser automation server for AI agents. Run locally or deploy to any cloud provider. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`
- **- http://localhost:9377**（project_doc）：camofox-browser Anti-detection browser server for AI agents, powered by Camoufox Standing on the mighty shoulders of Camoufox - a Firefox fork with fingerprint spoofing at the C++ level. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`
- **Persistence Plugin — Agent Guide**（project_doc）：Saves and restores per-user browser storage state cookies + localStorage across session restarts using Playwright's storageState API. Enabled by default — profiles persist to ~/.camofox/profiles/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`plugins/persistence/AGENTS.md`
- **persistence**（project_doc）：Optional per-user browser storage state persistence for camofox-browser. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`plugins/persistence/README.md`
- **VNC Plugin — Agent Guide**（project_doc）：Interactive browser access via noVNC. Log into sites visually, solve CAPTCHAs, approve OAuth prompts — then export the authenticated storage state for agent reuse. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`plugins/vnc/AGENTS.md`
- **VNC Plugin**（project_doc）：Originally contributed by @leoneparise https://github.com/leoneparise in PR 65 https://github.com/jo-inc/camofox-browser/pull/65 . Reworked as a plugin for the camofox extension system. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`plugins/vnc/README.md`
- **YouTube Plugin — Agent Guide**（project_doc）：Extracts video transcripts via yt-dlp preferred with Playwright browser fallback. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`plugins/youtube/AGENTS.md`
- **Contributing to camofox-browser**（project_doc）：Do not pass the host environment to child processes. This is a hard rule. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`
- **Camofox Browser v1.4.0**（project_doc）：🖼️ Download & Image Capture - File downloads : Camofox now captures files downloaded during browser sessions — PDFs, CSVs, images, and more. Your agent can access them programmatically after a download completes. - Page image extraction : A new endpoint pulls all visible images from a page, useful for extracting product photos, charts, or screenshots from web apps. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`changelog/1.4.0.md`

## 证据索引

- 共索引 63 条证据。

- **camofox-browser Agent Guide**（documentation）：Headless browser automation server for AI agents. Run locally or deploy to any cloud provider. 证据：`AGENTS.md`
- **- http://localhost:9377**（documentation）：camofox-browser Anti-detection browser server for AI agents, powered by Camoufox Standing on the mighty shoulders of Camoufox - a Firefox fork with fingerprint spoofing at the C++ level. 证据：`README.md`
- **Persistence Plugin — Agent Guide**（documentation）：Saves and restores per-user browser storage state cookies + localStorage across session restarts using Playwright's storageState API. Enabled by default — profiles persist to ~/.camofox/profiles/ . 证据：`plugins/persistence/AGENTS.md`
- **persistence**（documentation）：Optional per-user browser storage state persistence for camofox-browser. 证据：`plugins/persistence/README.md`
- **VNC Plugin — Agent Guide**（documentation）：Interactive browser access via noVNC. Log into sites visually, solve CAPTCHAs, approve OAuth prompts — then export the authenticated storage state for agent reuse. 证据：`plugins/vnc/AGENTS.md`
- **VNC Plugin**（documentation）：Originally contributed by @leoneparise https://github.com/leoneparise in PR 65 https://github.com/jo-inc/camofox-browser/pull/65 . Reworked as a plugin for the camofox extension system. 证据：`plugins/vnc/README.md`
- **YouTube Plugin — Agent Guide**（documentation）：Extracts video transcripts via yt-dlp preferred with Playwright browser fallback. 证据：`plugins/youtube/AGENTS.md`
- **Package**（package_manifest）：{ "name": "@askjo/camofox-browser", "version": "1.11.2", "description": "Headless browser automation server and OpenClaw plugin for AI agents - anti-detection, element refs, and session isolation", "type": "module", "main": "server.js", "license": "MIT", "author": "Jo Inc ", "homepage": "https://github.com/jo-inc/camofox-browser readme", "repository": { "type": "git", "url": "git+https://github.com/jo-inc/camofox-browser.git" }, "bugs": { "url": "https://github.com/jo-inc/camofox-browser/issues" }, "keywords": "browser", "automation", "headless", "scraping", "camofox", "camoufox", "anti-detection", "ai-agent", "openclaw", "clawdbot", "moltbot", "playwright", "firefox", "youtube", "transcrip… 证据：`package.json`
- **Contributing to camofox-browser**（documentation）：Do not pass the host environment to child processes. This is a hard rule. 证据：`CONTRIBUTING.md`
- **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`
- **Camofox.Config**（structured_config）：{ "id": "camofox-browser", "name": "Camofox Browser", "version": "1.6.0", "plugins": { "youtube": { "enabled": true }, "persistence": { "enabled": true }, "vnc": { "enabled": false, "resolution": "1920x1080" } } } 证据：`camofox.config.json`
- **Openapi**（structured_config）：{ "openapi": "3.0.3", "info": { "title": "camofox-browser", "version": "1.6.0", "description": "Anti-detection browser automation server for AI agents. Accessibility snapshots, element refs, session isolation, cookie import, proxy rotation, and structured logs.", "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "contact": { "name": "Jo Inc", "url": "https://askjo.ai", "email": "oss@askjo.ai" } }, "servers": { "url": "http://localhost:9377", "description": "Local development" } , "tags": { "name": "System", "description": "Server health, metrics, and status." }, { "name": "Tabs", "description": "Create, list, inspect, and destroy browser tabs." }, { "name": "Naviga… 证据：`docs/openapi.json`
- **Openapi**（structured_config）：{ "openapi": "3.0.3", "info": { "title": "camofox-browser", "version": "1.11.2", "description": "Anti-detection browser automation server for AI agents. Accessibility snapshots, element refs, session isolation, cookie import, proxy rotation, and structured logs.", "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "contact": { "name": "Jo Inc", "url": "https://askjo.ai", "email": "oss@askjo.ai" } }, "servers": { "url": "http://localhost:9377", "description": "Local development" } , "tags": { "name": "System", "description": "Server health, metrics, and status." }, { "name": "Tabs", "description": "Create, list, inspect, and destroy browser tabs." }, { "name": "Navig… 证据：`openapi.json`
- **CI/CD Dockerfile — downloads binaries during build no bind mounts needed .**（source_file）：CI/CD Dockerfile — downloads binaries during build no bind mounts needed . For local builds with pre-downloaded binaries, use the default Dockerfile + Makefile. 证据：`Dockerfile.ci`
- **!/usr/bin/env pwsh**（source_file）：!/usr/bin/env pwsh < .SYNOPSIS Build and manage camofox-browser on Windows PowerShell alternative to Makefile . 证据：`build.ps1`
- **Api**（source_file）：API Reference { "specUrl": "./openapi.json", "logoUrl": "./fox.png", "title": "camofox-browser", "subtitle": "API Reference", "accent": " 9B30FF", "accentLight": " B366FF", "methodGet": " 9B30FF" } / ======================================================== Design tokens — dark default ======================================================== / :root, data-theme="dark" { --accent: 9B30FF; --accent-light: B366FF; --accent-subtle: rgba 155,48,255,0.08 ; --bg-primary: 070E1A; --bg-secondary: 0B1628; --bg-tertiary: 0F1D33; --bg-code: 0a1120; --text-primary: E8F0FF; --text-secondary: 8BA3C7; --text-muted: 5a7394; --border: 1a2a42; --border-light: 243550; --method-get: 9B30FF; --method-post: 2563EB… 证据：`docs/api.html`
- **Config**（source_file）：function readCrashReporterConfig ⋮---- function parseProxyPorts portsEnv, singlePort ⋮---- function inferProxyStrategy explicitStrategy ⋮---- function camoufoxCacheDir env = process.env ⋮---- function camoufoxExecutablePath env = process.env ⋮---- function loadConfig 证据：`lib/config.js`
- **Extract**（source_file）：export function validateSchema schema ⋮---- function coerceValue raw, type ⋮---- function extractFromRef refs, refId ⋮---- export function extractDeterministic 证据：`lib/extract.js`
- **Launcher**（source_file）：function launchServer 证据：`lib/launcher.js`
- **Openapi**（source_file）：export function mountDocs app, opts = 证据：`lib/openapi.js`
- **Plugins**（source_file）：function readPluginConfig ⋮---- export function createPluginEvents ⋮---- export async function loadPlugins app, ctx 证据：`lib/plugins.js`
- **Proxy**（source_file）：function decodeProxyCredential value ⋮---- export function normalizePlaywrightProxy proxy ⋮---- function makeSessionId prefix = 'sess' ⋮---- function sanitizeBackconnectValue value ⋮---- / Decodo residential proxy provider. Username DSL: user-{base}-country-{cc}-state-{st}-session-{id}-sessionduration-{min} / ⋮---- buildSessionUsername baseUsername, options = ⋮---- buildProxyUrl proxy, config ⋮---- / Generic backconnect provider -- no username rewriting, just pass-through. Works with any SOCKS/HTTP proxy that supports sticky sessions via separate session IDs in the username field e.g. BrightData, Oxylabs . / ⋮---- // Provider registry ⋮---- export function getProvider name ⋮---- export func… 证据：`lib/proxy.js`
- **Reporter**（source_file）：export function anonymize text ⋮---- // 1. Strip known secret-prefixed tokens ⋮---- } catch { / not a valid URL, strip it / } ⋮---- // 6. Strip absolute file paths Unix + Windows , preserve last filename ⋮---- export function stackSignature type, error ⋮---- function fnv1a str ⋮---- export function createUrlAnonymizer ⋮---- function isPublicDomain hostname ⋮---- function hashHost hostname ⋮---- function anonymizeUrl rawUrl ⋮---- function anonymizeChain urls ⋮---- // ============================================================================ // Per-tab health tracker count-only, no content // ============================================================================ ⋮---- // Known bot-det… 证据：`lib/reporter.js`
- **Plugin**（source_file）：const getPluginDir = = ⋮---- async function startServer pluginDir, port, log, pluginCfg async function checkServerRunning baseUrl async function fetchApi baseUrl, path, options = function toToolResult data export default function register api ⋮---- async execute id, params ⋮---- // Guard: if server returns JSON/text instead of image e.g. error with 200 , // return as text to avoid crashing the client with base64-encoded JSON. ⋮---- async execute id, params ⋮---- handler: async args = 证据：`plugin.js`
- **Railway**（source_file）：build builder = "DOCKERFILE" dockerfilePath = "Dockerfile.ci" 证据：`railway.toml`
- **Plugin**（source_file）：function readConfig ⋮---- function writeConfig config ⋮---- function getEnabledPlugins config ⋮---- function addToConfig name ⋮---- function removeFromConfig name ⋮---- function parseSource source ⋮---- // Extract name from URL ⋮---- // Re-add .git for clone ⋮---- function isPluginDir dir ⋮---- function installFromLocal srcDir, name ⋮---- function installFromGit url, name ⋮---- function installPluginDeps name ⋮---- function removePlugin name ⋮---- function listPlugins ⋮---- function copyDirSync src, dest ⋮---- function fatal msg 证据：`scripts/plugin.js`
- **Postinstall**（source_file）：function camoufoxCacheDir ⋮---- function warn message ⋮---- function fail message ⋮---- export function externalExecutableFromEnv env = process.env ⋮---- function assertExternalExecutable path ⋮---- export async function main 证据：`scripts/postinstall.js`
- **Server**（source_file）：function countTabs function browserPid function resourceOpts ⋮---- const authMiddleware = ⋮---- function log level, msg, fields = ⋮---- class StaleRefsError extends Error ⋮---- function safeError err ⋮---- function sendError res, err, extraFields = ⋮---- function validateUrl url ⋮---- class TabLock ⋮---- acquire timeoutMs ⋮---- release ⋮---- tryNext ⋮---- drain ⋮---- function getTabLock tabId ⋮---- async function withTabLock tabId, operation, timeoutMs = HANDLER TIMEOUT MS ⋮---- function withTimeout promise, ms, label ⋮---- function requestTimeoutMs baseMs = HANDLER TIMEOUT MS ⋮---- async function withUserLimit userId, operation ⋮---- async function safePageClose page ⋮---- function getHost… 证据：`server.js`
- **Index**（source_file）：export async function register app, ctx, pluginConfig = ⋮---- warn: msg, fields = ⋮---- async function checkpoint userId, context, reason 证据：`plugins/persistence/index.js`
- **Index**（source_file）：export async function register app, ctx, pluginConfig = ⋮---- class VncVirtualDisplay extends VirtualDisplay ⋮---- get xvfb args ⋮---- ctx.createVirtualDisplay = 证据：`plugins/vnc/index.js`
- **Vnc Launcher**（source_file）：export function resolveVncConfig pluginConfig = ⋮---- export function startWatcher 证据：`plugins/vnc/vnc-launcher.js`
- **Index**（source_file）：export async function register app, ctx, pluginConfig = ⋮---- async function browserTranscript reqId, url, videoId, lang 证据：`plugins/youtube/index.js`
- **Camofox Browser v1.4.0**（documentation）：🖼️ Download & Image Capture - File downloads : Camofox now captures files downloaded during browser sessions — PDFs, CSVs, images, and more. Your agent can access them programmatically after a download completes. - Page image extraction : A new endpoint pulls all visible images from a page, useful for extracting product photos, charts, or screenshots from web apps. 证据：`changelog/1.4.0.md`
- **Openclaw.Plugin**（structured_config）：{ "id": "camofox-browser", "name": "Camofox Browser", "description": "Anti-detection browser automation for AI agents using Camoufox Firefox-based ", "version": "1.11.2", "envVars": { "CAMOFOX API KEY": { "description": "Secret key for the cookie-import endpoint. Cookie import is disabled when unset. Only set this if you need to import browser cookies and the server is local or access-controlled.", "required": false, "sensitive": true }, "CAMOFOX ACCESS KEY": { "description": "Global bearer token for all routes except /health . When set, every request must include Authorization: Bearer . Recommended when exposing the server beyond localhost.", "required": false, "sensitive": true }, "CAMOFO… 证据：`openclaw.plugin.json`
- **Tsconfig**（structured_config）：{ "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "esModuleInterop": true, "skipLibCheck": true, "noImplicitAny": false, "types": "node" }, "files": "plugin.ts" } 证据：`tsconfig.json`
- **Shell scripts must always use LF line endings**（source_file）：Shell scripts must always use LF line endings CRLF breaks shebang lines in Linux containers e.g. Docker builds .sh text eol=lf 证据：`.gitattributes`
- **Logs**（source_file）：node modules/ .env .env.local .env. .local 证据：`.gitignore`
- **Pinned Camoufox version for reproducible builds**（source_file）：FROM node:22-slim AS camofox-browser 证据：`Dockerfile`
- **Auto-detect host architecture; map arm64 macOS → aarch64**（source_file）：VERSION ?= 135.0.1 RELEASE ?= beta.24 证据：`Makefile`
- **Jest.Config**（source_file）：// Disable transforms — we use native ESM via --experimental-vm-modules ⋮---- testTimeout: 60000, // 60 seconds per test ⋮---- // Run tests sequentially to avoid resource conflicts ⋮---- // Test file patterns ⋮---- // Ignore patterns ⋮---- // Setup and teardown ⋮---- // Verbose output ⋮---- // Don't bail — run full suite even if a test fails ⋮---- // Coverage settings optional ⋮---- // Reporter settings 证据：`jest.config.cjs`
- **Jest.Config.E2E**（source_file）：// e2e tests run sequentially shared browser state 证据：`jest.config.e2e.cjs`
- **Auth**（source_file）：function timingSafeCompare a, b ⋮---- function isLoopbackAddress address ⋮---- export function requireAuth config, options = ⋮---- // Accept API key ⋮---- // Accept access key as alternative superkey ⋮---- // If any key is configured, a valid token was required -- reject ⋮---- export function accessKeyMiddleware config 证据：`lib/auth.js`
- **Camoufox Executable**（source_file）：function assertExecutable path ⋮---- function nixStoreRoot path ⋮---- function collectDirs root, maxDepth = 4 ⋮---- function findResourceDir executablePath ⋮---- function ensureSymlink target, linkPath, type = 'file' ⋮---- function shimRootFor executablePath, resourceDir ⋮---- function ensureLaunchShim executablePath, resourceDir ⋮---- function camoufoxLaunchFileName ⋮---- function ensureCamoufoxJsCache resourceDir, cacheDir, executablePath ⋮---- export function prepareExternalCamoufoxExecutable executablePath, 证据：`lib/camoufox-executable.js`
- **Cookies**（source_file）：function parseNetscapeCookieFile text ⋮---- async function readCookieFile ⋮---- async function importBootstrapCookies 证据：`lib/cookies.js`
- **Downloads**（source_file）：function sanitizeFilename value ⋮---- function guessMimeTypeFromName value ⋮---- async function removeDownloadFileIfPresent record ⋮---- async function trimTabDownloads tabState ⋮---- async function clearTabDownloads tabState ⋮---- async function clearSessionDownloads session ⋮---- function attachDownloadListener tabState, tabId, log, pluginEvents, userId ⋮---- async function getDownloadsList tabState, 证据：`lib/downloads.js`
- **Fly**（source_file）：export function createFlyHelpers config ⋮---- function makeTabId ⋮---- function parseTabOwner tabId ⋮---- function isLocalTab tabId ⋮---- function replayMiddleware log 证据：`lib/fly.js`
- **Images**（source_file）：async function extractPageImages page, ⋮---- const toDataUrl = blob ⋮---- reader.onload = reader.onerror = 证据：`lib/images.js`
- **Inflight**（source_file）：async function coalesceInflight map, key, factory 证据：`lib/inflight.js`
- **Macros**（source_file）：function expandMacro macro, query ⋮---- function getSupportedMacros 证据：`lib/macros.js`
- **Metrics**（source_file）：const noopCounter = const noopHistogram = const noopGauge = ⋮---- function buildNoopMetrics ⋮---- async function buildRealMetrics ⋮---- export async function initMetrics ⋮---- export function getMetrics ⋮---- export function getRegister ⋮---- export function isMetricsEnabled ⋮---- export async function createMetric type, options ⋮---- export function startMemoryReporter ⋮---- const report = ⋮---- export function stopMemoryReporter 证据：`lib/metrics.js`
- **Persistence**（source_file）：function getUserPersistencePaths profileDir, userId ⋮---- async function loadPersistedStorageState profileDir, userId, logger = console ⋮---- async function persistStorageState 证据：`lib/persistence.js`
- **Request Utils**（source_file）：export function actionFromReq req ⋮---- export function classifyError err 证据：`lib/request-utils.js`
- **Resources**（source_file）：function readVmRssKb pid ⋮---- function readChildPids pid ⋮---- export function browserProcessTreeRssMb browserPid ⋮---- export function collectResourceSnapshot opts = ⋮---- export function classifyProxyError errorMessage 证据：`lib/resources.js`
- **Sentry**（source_file）：export function initSentry config = ⋮---- export function captureException error, context = ⋮---- export function setupExpressErrorHandler app ⋮---- export async function flush timeoutMs = 2000 证据：`lib/sentry.js`
- **Snapshot**（source_file）：function windowSnapshot yaml, offset = 0 ⋮---- const contentBudget = MAX SNAPSHOT CHARS - SNAPSHOT TAIL CHARS - 200; // room for marker 证据：`lib/snapshot.js`
- **Tmp Cleanup**（source_file）：export function cleanupOrphanedTempFiles ⋮---- export function cleanupStaleFirefoxProfiles ⋮---- function dirSizeSync dirPath 证据：`lib/tmp-cleanup.js`
- **Tracing**（source_file）：function hashUserId userId ⋮---- export function userTracesDir baseDir, userId ⋮---- export function ensureTracesDir baseDir, userId ⋮---- export function makeTraceFilename ⋮---- export function tracePathFor baseDir, userId, filename ⋮---- export function resolveTracePath baseDir, userId, filename ⋮---- export async function listUserTraces baseDir, userId ⋮---- export async function statTrace fullPath ⋮---- export async function deleteTrace fullPath ⋮---- export function sweepOldTraces 证据：`lib/tracing.js`
- **Plugin**（source_file）：import type { ChildProcess } from "child process"; import { join, dirname, resolve } from "path"; import { fileURLToPath } from "url"; import { randomUUID } from "crypto"; ⋮---- import { loadConfig } from "./lib/config.js"; import { launchServer } from "./lib/launcher.js"; import { readCookieFile } from "./lib/cookies.js"; ⋮---- const getPluginDir = : string = ⋮---- interface PluginConfig { url?: string; autoStart?: boolean; port?: number; maxSessions?: number; maxTabsPerSession?: number; sessionTimeoutMs?: number; browserIdleTimeoutMs?: number; maxOldSpaceSize?: number; } ⋮---- interface ToolResult { content: Array ; } ⋮---- interface HealthCheckResult { status: "ok" "warn" "error"; messag… 证据：`plugin.ts`
- **--- Pre-flight checks ---**（source_file）：set -euo pipefail BUMP="${1:-patch}" if "$BUMP" != "patch" && "$BUMP" != "minor" && "$BUMP" != "major" ; then echo "Usage: ./release.sh patch minor major " exit 1 fi cd "$ dirname "$0" " --- Pre-flight checks --- echo "🔍 Pre-flight checks..." Clean working tree if -n "$ git status --porcelain " ; then echo "❌ Working tree is dirty. Commit or stash changes first." exit 1 fi On master BRANCH=$ git branch --show-current if "$BRANCH" != "master" ; then echo "❌ Not on master on $BRANCH . Switch to master first." exit 1 fi git fetch origin master --quiet LOCAL=$ git rev-parse HEAD REMOTE=$ git rev-parse origin/master if "$LOCAL" != "$REMOTE" ; then echo "❌ Local master $LOCAL differs from origin… 证据：`release.sh`
- **Run**（source_file）：CAMOFOX PORT=3000 while getopts "p:" opt; do case $opt in p CAMOFOX PORT="$OPTARG" ;; echo "Usage: $0 -p port "; exit 1 ;; esac done export CAMOFOX PORT if ! -d "node modules" ; then echo "Installing dependencies..." npm install fi if ! npx camoufox-js --version & /dev/null 2 &1; then echo "Fetching Camoufox browser..." npx camoufox-js fetch fi if ! command -v nodemon & /dev/null; then echo "Installing nodemon..." npm install -g nodemon fi echo "Starting camofox-browser on http://localhost:$CAMOFOX PORT with auto-reload " echo "Logs: /tmp/camofox-browser.log" nodemon --watch server.js --exec "node --max-old-space-size=128 server.js" 2 &1 while IFS= read -r line; do echo " $ date '+%Y-%m-%d… 证据：`run.sh`
- 其余 3 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

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

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

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

- 你准备在哪个宿主 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, package.json, lib/launcher.js
- **系统架构**：importance `high`
  - source_paths: server.js, lib/launcher.js, lib/fly.js, lib/snapshot.js, lib/sentry.js
- **安装与快速开始**：importance `high`
  - source_paths: package.json, Dockerfile, Makefile, build.ps1, scripts/postinstall.js
- **反检测机制**：importance `high`
  - source_paths: lib/camoufox-executable.js, lib/resources.js, lib/launcher.js
- **会话管理**：importance `high`
  - source_paths: lib/persistence.js, lib/cookies.js, lib/proxy.js, lib/tracing.js, lib/fly.js
- **API 参考**：importance `high`
  - source_paths: lib/snapshot.js, lib/images.js, lib/downloads.js, lib/extract.js, lib/openapi.js
- **插件系统**：importance `medium`
  - source_paths: plugin.js, plugin.ts, plugins/vnc/index.js, plugins/vnc/vnc-launcher.js, plugins/persistence/index.js
- **搜索宏**：importance `medium`
  - source_paths: lib/macros.js

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

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `dc93f51308f0c4f7372642f2fc426c57ecdfb364`
- inspected_files: `Dockerfile`, `package.json`, `README.md`, `docs/openapi.json`

宿主 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: 来源证据：[0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)
- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_509e4f60bc5b4f59b2f30d8e940b435f | https://github.com/jo-inc/camofox-browser/issues/4493 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 来源证据：[50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)
- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_9b0d643d129c40bba9029a91908b6df8 | https://github.com/jo-inc/camofox-browser/issues/4495 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 来源证据：[5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)
- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_b64265a647de4b7b87d3c451230683a7 | https://github.com/jo-inc/camofox-browser/issues/4483 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 来源证据：[1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_bc5774adce304ebcb8ccd6511fcf24df | https://github.com/jo-inc/camofox-browser/issues/4859 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 来源证据：[1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_66b048f511104e1f9c71f1ab5bb753ad | https://github.com/jo-inc/camofox-browser/issues/4854 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 来源证据：[43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_34506ec241e243b79da0f0ffc55849da | https://github.com/jo-inc/camofox-browser/issues/4858 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 来源证据：[51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_ec01f035f6474fde8b54a78998fcf0e8 | https://github.com/jo-inc/camofox-browser/issues/4851 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 来源证据：[674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_ea7990b603954ff98742c9307eaa3873 | https://github.com/jo-inc/camofox-browser/issues/4856 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 来源证据：[7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_79456dd0004342acba398cdc03c58748 | https://github.com/jo-inc/camofox-browser/issues/4852 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 来源证据：[8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)

- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)
- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Why it matters: 可能阻塞安装或首次运行。
- Evidence: community_evidence:github | cevd_d5beb836c1824c75b5eedfce488baaeb | https://github.com/jo-inc/camofox-browser/issues/4853 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。