codex-browser-bridge AGENTS.md

AGENTS.md

禁止提交 .env、凭据、私钥。提交前 git diff --staged 自查。

仓库级 Skill

本仓库包含项目级 skill：skills/codex-browser/SKILL.md

该 skill 是 LLM agent 使用全部 52 个 MCP 工具的操作手册，包含工具分组速查、常用工作流、工具选择原则。支持项目级 skill 的 MCP 客户端会自动加载。

MCP 工具设计规范

新增 MCP 工具遵循以下模式：

1. Browser 层（src/browser.rs）

• 每个 CDP 操作封装为一个 pub async fn，接受 &Client + 参数
• CDP 响应解析用私有函数，返回 Result<T>
• 使用 #[derive(Deserialize)] 私有结构体解析 CDP 响应
• execute_cdp_generic() 是显式低风险方法 allowlist 的 raw CDP 入口；不要用域名前缀放宽，高风险能力必须走专用受控工具

2. MCP 层（src/mcp/ 目录）

• types.rs：ToolHandler 枚举新增 variant（当前 52 个工具）
• handlers.rs：handle_tool_call 新增 match arm + handle_* 方法
• schema.rs：registered_tools() 新增工具定义
• profiles.rs：如需加入 profile，更新 BASIC_TOOLS / NETWORK_TOOLS 数组

3. 安全层（src/security.rs）

• 新增文件操作需经过 validate_file_path() 路径穿越防护
• 新增 URL 参数需经过 validate_url() scheme 检查

4. 诊断（src/doctor.rs）

• run_diagnostics() — 独立于 MCP Server 的 pipe 探活逻辑

5. 测试

• Extractor 测试（src/mcp/types.rs）：required_str、required_string_vec 等
• Schema 测试（src/mcp/schema.rs）：验证工具 required 字段、name order、type=object
• 集成测试（tests/browser_api.rs）：公开 browser/helper 行为与安全边界
• Reconnect/mock 测试（src/client.rs，cfg(not(windows))）：tokio::io::duplex() mock pipe
• Harness 计划：新的真实/模拟 E2E 应放在 tests/，不要使用 #[path] 嵌入源码文件
• Mock pipe / E2E harness 等待必须 bounded：正向 pipe read 和 spawned task join 用明确 timeout，负向“不得发 pipe 请求”断言用短 grace window；live E2E 的 doctor preflight 和 cleanup MCP 调用也必须有 timeout。

6. 工具数量

• 当前：52 个 MCP 工具
• 新增工具命名：codex_<domain>_<action>，group tag 放描述开头

构建

cargo check --locked              # 快速检查
cargo test --locked                # 全量测试
cargo clippy --locked -- -D warnings  # lint
cargo build --locked --release     # 发布构建 → target/release/codex-browser-bridge.exe
npm --prefix npm test              # npm installer/package helper 测试
.\scripts\live-e2e.ps1             # 可选真实 Codex Desktop + Chrome 冒烟测试

Release 时遵循 docs/release-process.md：确保 Cargo.toml 和 npm/package.json 版本号与 tag 一致，CHANGELOG.md 有对应段，npm 包 dry-run 包含 skills/codex-browser/SKILL.md 和 examples/ 多客户端模板。npm 发布走 Trusted Publishing/OIDC，不在 GitHub secrets 中放 npm write token。