mcp-devbridge AGENTS.md

AGENTS.md — 项目引导

本项目为多角色开发。请 AI（各类 agent，包括 opencode/Claude/Copilot）以及参与开发的工程师阅读本文件。

一、先读什么（上下文受限时的速览路径）

当上下文被压缩后，按以下顺序阅读以快速恢复项目知识：

1. AGENTS.md（本文件） — 快速定位与约定
2. 项目架构.md — 代码结构、模块职责、数据流、关键实现细节
3. 开发计划.md — 完整开发计划 + 每个 Phase 的验收标准
4. 进度验收.md — 当前开发进度、已完成 Phase、遗留事项（写操作前必须读）

若本文件与上述任一文档冲突，以 项目架构.md 为准并同步修 AGENTS.md。

二、项目一句话

MCP DevBridge（原 LocalDev MCP Bridge）：一款 Windows / Linux（含 SteamOS Desktop Mode）桌面程序（PySide6 单窗口），让用户在桌面选定一个本地开发项目， 一键启动独立的 MCP Server 子进程（仅监听 127.0.0.1），并通过 Cloudflare Named Tunnel 提供一个 长期固定、永不变化的 HTTPS MCP 地址，供 ChatGPT / Gemini 等支持自定义 MCP 的客户端接入。

三、开发约定（必须遵守）

• 不修改外部项目：禁止修改 D:\AStockMultiAgent 及其它非本项目的目录（测试一律写在 .test-workspace）。
• 不删除原型与旧的 .venv：D:\Environment\mcp\backups-prototype\dev-mcp.py 为原型备份；D:\Environment\mcp\.venv 保留。
• 合并/文档优先：任何“并发/压缩上下文”场景，先写 进度验收.md 再继续开发。
• 认证与 URL 分离：公开 MCP URL 必须固定（Named Tunnel），令牌（Bearer）由用户在客户端单独配置，绝不允许把随机密钥拼进 URL。
• 本机匿名放行：仅允许 127.0.0.1 / ::1 / localhost 的本地连接匿名访问 /mcp；/control/* 一律要求 Bearer。
• 公网必须 Bearer：经 Cloudflare 转发（Host 为公网域名）的请求必须携带有效 Bearer； 默认 MCP SDK 2.0.0 的 streamable_http_app() 会自动加 DNS rebinding 防护，只放行 localhost， 公网隧道接入时需显式禁用/调整 rebinding（见 项目架构.md「安全模型」）。
• 桌面默认完全访问：桌面新项目默认 system + full_system（“完全访问（危险）”）；不做逐次写操作确认，但第一次实际启动完全访问模式仍需要一次性风险确认。后端/CLI 的兼容默认值不等同于桌面产品默认值。
• 不泄漏密钥：日志必须脱敏（文件名/参数含 KEY/TOKEN/SECRET/PASSWORD/COOKIE/AUTH 时整值遮罩）。

四、环境与依赖（复现命令）

# 进入项目
cd D:\Environment\mcp\mcp-devBridge
# 创建 venv（Windows）并安装开发依赖
python -m venv .venv
.venv\Scripts\activate
uv pip install -e ".[dev,package]"

# 测试（必须在项目根执行，保证导入路径）
PYTHONIOENCODING=utf-8 .venv\Scripts\python.exe -m pytest tests/ -q

# 运行后端命令入口
.venv\Scripts\python.exe -m local_dev_mcp_bridge.standalone_server      # 单一入口（CLI 简化）
.venv\Scripts\python.exe -m local_dev_mcp_bridge.server_main --config ...  # 子进程后端入口（正式路径）

已锁定：Python 3.12.10、mcp==2.0.0、pydantic 2.13.4、starlette 1.4.1、uvicorn 0.52.1、PySide6 6.11.1、pytest 9.1.1、pywin32 312。

Windows-MCP 版本锁定在 `engines.py` 的 `WINDOWS_MCP_PINNED_VERSION`（当前 `0.8.2`，
`uvx --from windows-mcp==0.8.2 windows-mcp serve`）；升级必须先实测兼容再人工改常量。
（其余依赖见 `pyproject.toml`）

## 五、目录结构

mcp-devBridge/ ├── pyproject.toml # 包定义、脚本入口、ruff/pyright/pytest 配置 ├── README.md # 一句话 + 文档索引 ├── AGENTS.md # ← 本文件 ├── 项目架构.md # 架构说明 ├── 开发计划.md # 计划 + 验收 ├── 进度验收.md # 进度 ├── src/ │ └── local_dev_mcp_bridge/ │ ├── init.py # version、APP_NAME、APP_IDENT │ ├── constants.py # 目录/默认值/错误码常量；配置目录 default %LOCALAPPDATA%\LocalDevMCPBridge（LOCALDEV_MCP_CONFIG_DIR 可覆盖） │ ├── models.py # ProjectConfig / AppConfig / RuntimeConfig / TunnelState（pydantic） │ ├── config_store.py # 读/写这些 JSON；功能探测；命令建议 │ ├── secrets.py # Bearer 令牌（Win CredManager + DPAPI 回退文件 secrets.dpapi.json） │ ├── audit.py # 审计日志 + 密钥脱敏 │ ├── agent_pool.py # v0.9 本地并发 Agent 池：OpenCode/Claude Code + worktree + bounded queue │ ├── agent_runtime.py # v0.10 Persistent Runtime：TaskState/checkpoint/validator/retry/restart resume │ ├── agent_orchestrator.py # logical Agent/Team 与 Runtime/Pool 接线 │ ├── agent_gateway.py # Agent MCP 参数规范化与本机分派 │ ├── shell.py # PowerShell 命令执行、进程树终止、环境探测 │ ├── processes.py # 受管进程注册（dev server 等） │ ├── permissions.py # 权限：read_only / workspace / system │ ├── execution_profile.py # Shell 执行档位：safe / developer（默认）/ full_system + 危险命令拦截 │ ├── project_manager.py # 多项目：ProjectUnit（每项目引擎对）+ ProjectManager（编目/独立端口/生命周期；enabled 仅兼容旧配置） │ ├── tools.py # 37 个 MCP 工具实现（含 list_projects / switch_workspace / shell_info / shell_self_test） │ ├── server_factory.py # MCPServer + Starlette app + 认证/审计/限速中间件 │ ├── server_main.py # 后端 CLI（--config / --port），被桌面进程拉起 │ ├── standalone_server.py# 简化 CLI 单进程入口 │ ├── selftest.py # 本地 MCP 客户端自测（桌面“测试连接”按钮） │ ├── engines.py # 引擎进程管理：CodexProManager / WindowsBridgeManager / 脱敏 / 就绪检测 │ ├── tunnel_manager.py # 隧道进程：Cloudflare Named / Quick / ngrok / 仅本机；固定 URL 解析 │ ├── oauth_provider.py # Phase 8 OAuth：LocalOAuthProvider（SDK Provider 实现，单 scope / code / refresh 轮换） │ ├── gateway.py # Phase 8 OAuth 网关：uvicorn 8786，OAuth 路由 + 同意页 + /mcp 反向代理 │ ├── app_state.py # 服务协调状态机 ServiceCoordinator（顺序、URL 固定性、故障清理；无 Qt） │ ├── backend_manager.py # 后端子进程管理 /health 轮询（已归档，桌面改走 ServiceCoordinator） │ └── desktop_main.py # Phase 3 桌面 UI（PySide6 单窗口，已接线 ServiceCoordinator） ├── tests/ # pytest 测试（Phase 12 当前 304 项全绿，以实际 pytest 输出为准） │ ├── conftest.py │ ├── test_fs.py · test_commands.py · test_git.py · test_config.py │ ├── test_mcp_integration.py · test_selftest.py │ ├── test_engines.py · test_tunnel_manager.py · test_app_state.py │ ├── test_oauth.py # OAuth 2.1 发现/注册/PKCE/刷新/撤销/网关代理（27 项） │ ├── test_project_manager.py # 多项目：编目/端口唯一/并行启停/自动恢复/真机双引擎 │ └── test_workspace_switch.py# 会话级 switch_workspace 隔离 + shell_info ├── .test-workspace/ # 测试用临时工作区 └── .tools/ # cloudflared.exe（2026.7.3）等二进制

## 六、常用命令（结果为准）

部分命令必须在 PowerShell 下运行（`$env:PYTHONIOENCODING="utf-8"`），否则 GBK 编码报错。