前言¶
在 DSH「一切皆插件」的工作流里，浏览器控制插件常要面对两类任务：一类是隔离、可重复的 CI 浏览器；另一类是本机已经登录、带有本地会话状态的 Chrome profile。
后一类如果靠 copied profiles、debug profile、remote-debugging port 或 Edge 来迁就，通常会把登录态和权限边界搞复杂。bpc-oss/chrome-faithful 针对第二种场景：让智能体直接驱动真实、已登录的 Chrome profile。
这是什么¶
bpc-oss/chrome-faithful 由 bpc-oss 维护。已核实资料显示：
- 许可证为
MIT，README 与package.json都写明。 package.json标明版本0.4.0。- README 徽章标明
Node >= 22.12。 - README 有 English 和 简体中文版本。
它把 MCP server、MV3 Chrome extension 和 authenticated localhost bridge 组合在一起。README 描述其 MCP tool surface 为 38 tools。
核心功能¶
精确多 Profile 路由¶
它用 metadata.profileName 做 exact multi-profile routing。调用者必须选择一个 exact metadata.profileName。同一个 profile name 的 duplicate live registrations 会被拒绝，避免多个 agent 交错操作同一个 profile。
启动与断开恢复¶
如果目标 profile 或整个 Chrome 已关闭，它会用 ordinary Chrome 启动 exact profile，并等待 exact extension profileName 注册后才报告成功。已核实资料写明没有 fallback 到 generic profile、port 9222、Edge 或 UI automation。
目标 disconnected 时，调用者使用：
chrome_profile_catalog
chrome_profile_start
这里的成功条件是 exact extension profileName 已注册。
本地桥接与权限边界¶
Bridge 只绑定 127.0.0.1，并要求 generated secret。已核实资料描述该 secret 为 256-bit。
Extension host access 被限制到：
http://127.0.0.1/*
用于 local bridge。Extension 使用 broad capabilities，包括 debugger、history、downloads 和 clipboard permissions。资料还说明 configuration 是 closed-schema，必须位于 source tree 外。
文件上传与媒体导出¶
文件上传通过注入 page File / DataTransfer objects 完成，不使用 DOM.setFileInputFiles，也不依赖 OS file chooser。
媒体导出使用：
chrome_page_asset
它带 tab 的 user agent、referer 和 matching profile cookies 来 stream page-exposed media。
滚动采集与最小化窗口¶
它有 durable virtual-list/scroll capture，包括 asset parity、fail-closed manifests、exclusive cross-process locks 和 resume。Locator waits/actions 和 screenshots 使用 CDP focus emulation，这样即使 Chrome window 被 minimized 或 obscured，controls 也可以继续 rendering。
Raw CDP 与验证¶
Raw CDP 访问通过：
chrome_cdp
其 event reads 会 redact Network headers、query strings 和 post data。send action 是 deliberately unrestricted raw CDP，只能暴露给 fully trusted MCP client。chrome_cdp with action=send 在 safe-projection boundary 之外，不应给 untrusted clients 或 shared MCP hosts 启用。
验证处理包括 challenge detection、click-first solving 和 human handoff。
Codex 兼容 JS API¶
它提供 Codex-compatible JS API：
src/agent-browser.mjs
该文件实现 agent.browsers，让 JavaScript agents 可以调用同一套 browser surface。
安装与启用¶
已核实资料中未包含完整 DSH 安装命令；README 的 DSH first-class integration 部分也被截断。因此这里不放猜测命令。
已核实的前置信息如下。
https://github.com/bpc-oss/chrome-faithful
这是 GitHub 仓库地址，不是安装命令。
MIT
0.4.0
Node >= 22.12
分别是许可证、package.json 版本和 README 徽章中的 Node 要求。
启用前以仓库 README 中完整的 DSH integration 说明为准，不要把仓库名直接拼成安装命令。
典型用法¶
以下顺序来自已核实资料。
- 先选择 exact profile。
metadata.profileName
这是路由标识，表示调用者必须选定一个 exact profile。
- 如果目标 disconnected，先查询再启动。
chrome_profile_catalog
chrome_profile_start
启动成功的前提是 exact extension profileName 已注册。
- 在做浏览器工作前，先通过 live self-test。
tabs
Runtime.evaluate
这两项必须先通过。
- 导出页面暴露的媒体资源时，使用
chrome_page_asset。
chrome_page_asset
它会带 tab 的 user agent、referer 和 matching profile cookies。
- 需要 raw CDP 时，使用
chrome_cdp。
chrome_cdp
注意 send action 是 unrestricted，只能给 fully trusted client。
适用场景与注意¶
适合¶
- 需要在 DSH 智能体里控制真实、已登录 Chrome profile 的团队。
- 多 profile 并发，并且需要按 exact
profileName隔离。 - 不想使用 copied profiles、debug profile、
remote-debugging port或 Edge。
不适合¶
- 需要 deterministic、disposable CI 浏览器时，README 建议改用 Playwright 或 Puppeteer。
注意¶
- 插件以当前 dsh 进程权限运行。安装前应检查源码与许可证。
- Extension 拥有 broad capabilities：
debugger、history、downloads、clipboard permissions。 - Configuration 是 closed-schema，并必须位于 source tree 外。
- Windows installers 被描述为 transactional，带 SHA-256-verified、DPAPI-encrypted backups。
chrome_cdp的sendaction 在 safe-projection boundary 之外，不要给 untrusted clients 或 shared MCP hosts 启用。
结尾¶
bpc-oss/chrome-faithful 的价值在于把“控制已登录 Chrome”这件事收束到 exact profile、localhost bridge 和显式 trust boundary 上。它不是面向通用 CI 的浏览器方案，而是面向真实本地 profile 的 DSH 浏览器控制插件。
DSH 的理念是「一切皆插件」，社区目录是独立站点。已核实资料未包含具体目录页 URL；GitHub 地址如下：
https://github.com/bpc-oss/chrome-faithful
