本文件只面向 AI coding agent，描述“如何安全、准确地改这个仓库”。
用户上手、安装、运行、接口说明请看 README.md。
- 适用于本仓库内所有代码与文档修改。
- 目标是降低错误修改、路径幻觉、过时说明复用。
main.py: CLI 会话入口。api.py: FastAPI 服务入口（/chat、/tools、/upload）。run_server.py: 启动 API 并打开前端页面。
如需求影响入口行为，必须同步核对并更新相关说明。
utils/agent_factory.py: agent 组装与中间件链。utils/mcp_client.py: MCP 持久会话管理（create_persistent_mcp_session），解决每次工具调用创建新 subprocess 的问题。utils/my_browser.py: 浏览器进程管理（启动、CDP 端口检测、清理），启动流程全异步。context/context_manager.py: 上下文压缩、归档、消息重写。tools/: 工具定义。当前包含：capture_element_context_tool、vision_analysis_tool、delay_tool_call、terminal_tools、rag_tools。浏览器操作工具由 MCP 会话动态加载，不在此目录。rag/: 检索与向量相关逻辑。loggers/: 记录与经验总结中间件（仅文字日志，无截图）。
仅在边界明确时修改，跨模块改动需检查调用链是否一致。
- 先读代码再改文档，文档必须映射真实实现。
- 不把规划文档中的设计当作已实现能力。
- 不引入仓库中不存在的路径、模块或类名。
- 改动后不得破坏现有入口可运行性。
- 涉及消息重写时，必须保证 Human/AI 角色严格交替。
- 改接口行为：同步更新
README.md的用法或接口说明。 - 改目录结构：同步更新本文件“真实入口/核心边界”。
- 改运行前置条件：同步更新
README.md环境与排障章节。
- 浏览器操作已迁移至
@playwright/mcp(snapshot-ref 模式)，通过utils/mcp_client.py管理持久 MCP 会话。 - 已废弃并删除的工具：
fill_text_tool、get_all_element_tool、get_page_img_tool、playwright_mcp_tool。 context/context_manager.py存在且为生效中间件，支持旧消息压缩和字符硬阈值双触发。context/state_manager.py、context/assembly_engine.py、context/dynamic_id/当前不存在。docx/下内容主要是设计和过程文档，不等于运行时代码。loggers/screen_logger.py仅保留文字日志，不再持有 ScreenshotHelper / CDP 连接。ToolNode已全局修补_handle_tool_errors = True，MCP 工具异常不会导致 Agent 直接崩溃。
- 小步修改，优先最小可验证变更。
- 每次修改后至少做一次本地一致性检查（路径、导入、文档引用）。
- 避免在不相关文件做顺手重构。