后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载在 Macro 这样一个包含邮件、聊天、文档、任务、Agent、通话与 CRM 的统一工作空间中任何用户可见的改动都不能只靠类型检查和单元测试来判定“修好了”。仓库通过.agents/agents/browser-verifier.md定义了一个专用子代理要求它在真实浏览器里复现一次改动、按docs/agent-guide的规范操作、留存截图并只回传结论。本文以该子代理定义文档为主体结合docs/agent-guide系列指南、仓库前端的浏览器验证约定与 Playwright 配置说明它为什么这样设计、如何被调度、执行时有哪些硬性边界以及如何读懂它返回的结论。子代理的定位只验证不改代码.agents/agents/browser-verifier.md的第一句话就把职责钉死了You verify one described web change in a real browser. You do not edit source files.这里包含三层约束值得逐条拆开看一次只验证一个改动one described web change。验证任务由父代理在 prompt 中描述子代理不负责猜测需求、不负责扩大范围。必须在真实浏览器中验证in a real browser。它不能通过阅读代码、跑单测或看截图猜测交互是否成立而要真正驱动页面。不修改源码You do not edit source files。这与它的工具集是互相印证的见下一节的 front matter 解析。这个定位在仓库的整体代理体系中是有意为之的AGENTS.md 明确列出.agents/agents/下的两个子代理auditor与browser-verifier并说明.claude/agents只是指向该目录的软链接——真实文件只存在于.agents/各工具目录仅做链接避免多份副本漂移。实际检查也确认.claude/agents是指向../.agents/agents的符号链接。front matter 逐字段解析文档开头的元数据块browser-verifier.md不是装饰每一行都直接决定子代理的行为边界字段值实际含义与影响namebrowser-verifier子代理标识符父代理按此名调度也是其余工具目录软链接后可见的名字description验证用户可见的 Web 改动遵循docs/agent-guide返回结论与截图路径建议在改动 UI、路由、编辑器或 AI 界面之后使用以便 DOM 快照不进入主上下文这既是“什么时候该叫它”的判定条件也是它存在的核心理由上下文预算隔离toolsBash, Read, Grep, Glob只有读取类与命令执行能力没有 Edit / Write。因此“不得修改源码”不是口头纪律而是能力上的硬约束modelsonnet指定该子代理使用的模型档位与主代理解耦description里有两个关键词最容易被忽略却决定它的使用价值“Use after changing UI, routes, editors, or AI surfaces”触发面覆盖界面组件、路由、富文本/文档编辑器以及 AI 相关界面例如 AI 对话、AI 编辑。这与仓库前端指南的要求一致——apps/web/AGENTS.md 明确写着“任何用户可见的改动都应该在浏览器里跑一遍再宣布修好因为类型检查、biome、vitest 全部通过代码里依然可能存在交互 bug”。“so DOM snapshots stay out of the main context”Macro 的 DOM 快照体量很大browser-technique.md 记载分裂视图会重复整篇文档文本、Activity 热力图会额外带来约 400 个节点。把这类噪声放进主代理上下文会挤掉真正用于推理的空间。子代理把原始快照留在自己的执行环境里只回传结论与截图路径。tools与model的组合还有一层工程含义Bash让它可以自行启动 Playwright Chromium、把快照写入临时文件再用grep过滤这正是 browser-technique.md 推荐的“filePath:落盘 Bash grep”做法而缺少写文件工具则防止它顺手“修一下”。五步执行流程详解browser-verifier.md 给出了编号 1 到 4 的四段正文第 5 段是截图落盘要求合起来构成一次完整的验证会话第一步先读指南再动手Readdocs/agent-guide/README.md, then the guide pages for the surfaces named in the prompt, anddocs/agent-guide/browser-technique.md.这里要求按三层递进阅读顺序不能颠倒总索引docs/agent-guide/README.md它用一张表列出二十多个按“表面surface”划分的指南页包括登录、导航、文档、数据库、表单、AI 对话、频道、任务、邮件、日历、搜索、文件、通话、CRM、PR 评审、活动、通知、外部标签、设置、引导、画布、Soup 实时更新、UI 约定、浏览器技术与可观测性。验证者必须先从这张表里定位到本次改动涉及的那一页。具体表面页面例如改动编辑器就查 documents.md改动频道就查 channels.md改动通知就查 notifications.md。这些页面描述了该表面的真实交互路径与边界情况是“按指南的方式操作”的依据。浏览器技术总纲browser-technique.md跨表面通用的操作与诊断经验。总索引还给出了本地栈的约定README.md前端是http://localhost:fe/app后端代理是https://localhost:be使用仓库内签入的自签名证书需要信任infra/local/certs/ca.pemMailpit 是http://localhost:mp端口由--instance决定例如lgtm实例使用 27910 / 27909 / 27908。远程浏览器验证时要信任同一份 CA 并访问启动器打印的https://hostname:proxy-port/app/在远程主机名上使用纯 HTTP 无法保留安全登录 Cookie。这些约定直接影响验证者能否进入登录态、能否看到真实的邮件与通知。第二步使用自己的无头 Playwright ChromiumUse your own headless Playwright Chromium. Never attach to the users browser or a shared Chrome on port 9222.这是整份文档中最“硬”的一条禁令。原因可以从仓库配置里读出来opencode.json 把chrome-devtoolsMCP 配成--browser-url http://127.0.0.1:9222也就是说9222 端口是主会话共享的浏览器实例。如果子代理挂到这个实例上会出现几类典型故障它与主代理抢同一个标签页导航互相打断主代理正在人工观察VNC 场景时画面被自动化操作污染主代理的登录态、页面上下文被覆盖或污染验证结论不可信。因此子代理必须自己拉起无头 Chromium获得独立的浏览器进程、独立的 profile 与独立页面上下文。仓库中大量“无后端浏览器回归”用例也是同一模式每个测试目录自带playwright.config.ts并通过webServer自行起一个 Vite 服务例如 Resize 用例的配置 使用固定testDir、testMatch: *.browser.e2e.ts、workers: 1、screenshot: only-on-failure并在指定端口拉起bunx vite。这种“自起、自测、自收尾”的结构正是浏览器验证子代理应当遵循的模板。第三步不启动服务URL 由 prompt 提供Use the app URL from the prompt. If none is given, ask for one in your result instead of starting servers; dont start or restart the local stack.这条规则把“环境准备”和“环境验证”彻底分离。理由很实际本地栈的启动涉及数据库、后端代理、证书与端口分配见 README.md 与just run_local的约定这不属于验证职责重启栈会清空登录态与数据状态破坏其他并行工作的前提若 prompt 没给 URL正确做法是在返回结果中索要 URL而不是自行猜一个端口去试。需要区分的例外是子代理自行拉起的Vite 预览服务用于渲染待验证页面或运行无后端回归属于它自己的测试夹具不属于“本地栈”。文档中的禁令针对的是just run_local这类共享本地栈。第四步按指南操作并覆盖 prompt 列出的边界情况Exercise the change the way the guide describes, including the edge cases the prompt lists.“按指南描述的方式操作”意味着不能只点一下主路径就收工。Macro 的指南页本身就是可执行的检查清单例如登录login.md 覆盖无密码登录全流程、Mailpit 取码、已知崩溃与恢复导航navigation.md 覆盖路由、侧边栏、命令菜单、键盘模型与分屏AI 对话ai-chat.md 覆盖独立会话与文档内会话实时更新soup-live-updates.md 覆盖扁平 Soup 列表的实时刷新UI 约定ui-conventions.md 覆盖列表加载、顶栏、对话框动作、用户卡片与信息面板等共享行为通知与提示notifications.md、toasts.md。“包括 prompt 列出的边界情况”则是把父代理的业务判断注入进来例如“空列表”“权限不足”“断线重连”“移动端窄屏”等由父代理在 prompt 中列出子代理逐条走一遍。第五步隐含截图落盘到指定目录Save screenshots under the scratch directory given in the prompt, or under$TMPDIR.截图路径有优先级prompt 指定的临时目录优先否则用$TMPDIR。这条规则同时解决了两个问题一是截图不进入仓库仓库是只读的也不应被验证产物污染二是父代理可以按路径直接把图交给用户或后续流程。从 browser-technique.md 继承的操作经验browser-technique.md记录的是在 Macro 上使用 chrome-devtools MCP 的经验教训。子代理被要求必读它是合理的这些经验与具体工具无关迁移到 Playwright 驱动时同样成立。下面挑出对验证质量影响最大的几条。快照优先且不要相信过期引用browser-technique.md 建议每次导航或面板切换后重新取快照只在最新快照的 uid 上操作由于应用是 SolidJS区域重渲染时 uid 前缀会跳变7_x→9_x过期 uid 会直接报错——正确反应是重新取快照而不是猜一个引用。快照要落盘靠 grep 读同一节指出 Macro 的快照体量巨大分屏重复整篇文档、热力图增加约 400 节点因此应带filePath:保存到文件再用 Bashgrep提取而不是把整份快照灌进上下文读取时可过滤掉匹配Notifications (alt的噪声行。这正是子代理的工具集里同时存在Bash与Grep的原因。contenteditable 不能用 fillbrowser-technique.md 的关键结论fill只对真正的input/textarea/select有效Macro 的所有编辑器与消息输入框都是 contenteditable必须先点击聚焦再type_text必要时用submitKey: Enter令牌型下拉框邀请频道成员、添加参与者需要点击下拉、输入值、观察N option(s) available的实时区域文本再按 Enter 提交成 chip最后才提交表单单选式标签条Messages/Attachments/Participants、Signal/Noise/All点击 radio 输入可能报“element did not become interactive”应改点相邻的 StaticText 标签菜单按钮点一次可能只是聚焦若下一次快照里没有出现预期菜单就再点一次对话框提交常用CtrlEnter新建任务、后台对话发送。这些细节直接决定验证结论的真伪编辑器内容没输进去后面的“编辑成功”判断全部失效。等待要选对信号browser-technique.md 指出navigate_page可能在 10 秒超时但 SPA 其实已经加载此时应改用等待页面出现预期文本而不是重试导航wait_for匹配的是页面任意文本包括 placeholder 和重复的文档正文因此要选不可能预先存在的字符串AI 生成完成没有可靠文本信号应在evaluate_script中轮询“停止生成”按钮是否消失。文档给出的轮询片段如下async () { for (let i 0; i 60; i) { if (![...document.querySelectorAll(button)] .find(b /Stop generating|^Stop$/.test(b.textContent.trim()))) return true; await new Promise(r setTimeout(r, 1000)); } return false; }失败诊断的两把刀browser-technique.md 给出的诊断顺序非常明确遇到错误弹窗或白屏先list_console_messageserror/warn再list_network_requestsxhr/fetch然后对可疑请求做get_network_request看头与体——把控制台错误与失败请求配对往往一步就能定位故障。常见的几类现象也被逐一记录应用根节点为空时要连script请求一起看即使/app/返回 200某个 Vite 模块 502 也会让入口模块无法渲染生成的 Vite 代理把上游连接限制在 16 个避免模块加载期间打爆宿主监听器更新后只需重启受影响的代理满屏net::ERR_NETWORK_CHANGED表示环境网络抖动先在 shell 里用 curl 验证栈再重新导航全屏“Something went terribly wrong”对话框按Home可恢复导航级崩溃而 LoroDoc 崩溃需要带ignoreCache: true重新加载详见 documents.md浏览器重启会让页面 id 失效并在新 profile 下丢失登录态需要list_pages重新选中并预期重新登录每个后端请求都带traceparent头并返回x-request-id可用于与后端链路关联详见 observability.md。环境隔离与安全边界把前几节串起来可以看到一套清晰的隔离设计维度主代理 / 人工browser-verifier浏览器实例chrome-devtoolsMCP 连接127.0.0.1:9222的共享 Chrome见 opencode.json自行启动的无头 Playwright Chromium独立进程与 profile本地栈由人工或父代理启动just run_local等不启动、不重启只用 prompt 给的 URL文件系统可写改代码只读无 Edit/Write 工具仅可落盘截图上下文业务推理主战场DOM 快照与日志留在子代理内只回传结论这套设计还带来一个副作用验证是幂等的。子代理不会改变仓库、不会重启共享栈、不会污染共享浏览器因此可以反复调用或在同一批改动上多次运行而不会互相踩踏。需要注意一个前置条件本地栈用的是自签名证书README.md 明确要求信任infra/local/certs/ca.pem。如果子代理的浏览器实例没有信任该 CA访问https://localhost:be会直接失败症状看起来像“页面打不开”而不是“改动坏了”——这类环境问题应在返回结果中与真实回归区分开。返回契约四种信息缺一不可browser-verifier.md 规定了固定返回结构Verdict结论只能是works、broken、couldnt verify三态之一。做过什么逐步说明每一步都附上展示该步结果的截图路径。看到的控制台错误或失败请求简短引用原文。指南要求检查、但你无法检查的内容。这个结构有几个精妙之处三态结论避免二值化误判。couldnt verify的存在让“环境没起来”“拿不到 URL”“CA 未信任”这类情形不会被硬塞进broken从而不会让父代理去修一个并不存在的 bug。强制逐步截图把结论与可视证据绑定。截图落在 prompt 指定目录或$TMPDIR父代理可以直接引用。强制引用原始错误而不是转述。控制台原文与失败请求是后续排查的锚点尤其是配合traceparent/x-request-id时。强制声明未覆盖项让“已验证”的边界清晰可审计。一个符合该契约的返回示例结构示意非仓库文件Verdict: broken 1. Opened https://localhost:27909/app/ and signed in with the email code from Mailpit. Screenshot: $TMPDIR/verify/01-login.png 2. Opened the target document and typed into the title field (contenteditable, click type). Screenshot: $TMPDIR/verify/02-title.png 3. Saved, reloaded with ignoreCache, observed the title revert to the old value. Screenshot: $TMPDIR/verify/03-reload.png Console errors: Failed to fetch on POST /graphql Failed requests: POST /graphql - 500, x-request-id: 0f3c... Could not check: mobile drawer layout — prompt listed it, but no phone viewport was provided.对照上文这个返回满足全部四项要求三态结论、逐步截图、原始错误、未覆盖声明。与其他质量门禁的分工仓库在交付前有两类子代理质量门禁职责互不重叠browser-verifier回答“这个用户可见改动在真实浏览器里表现如何”。偏交互与视觉行为。auditor按.agents/skills/audit/SKILL.md在当前分支上跑仓库检查默认基线origin/main只返回通过/失败/跳过的表格与失败摘录。偏静态检查、测试与 lint。AGENTS.md 的“Before handing off”要求交付前运行audit技能通过auditor子代理并把 DOM 快照留在主上下文之外而 apps/web/AGENTS.md 则要求任何用户可见改动都必须在浏览器里跑过。两者合起来才是完整的交付标准静态检查通过 ≠ 交互正确浏览器看起来对 ≠ 所有检查通过。与仓库自带 Playwright 回归的关系如果这次改动对应的 surface 已经有“无后端浏览器回归”验证者应当优先跑它再叠加手工验证。仓库中这类配置分布在各功能目录内例如分屏拖拽与输入框重排Resize 用例讨论链接滚动messages 用例手机端多层 Sheet 背板点击mobile 用例输入框浮动菜单朝向LexicalMarkdown directive 用例日历事件详情定位calendar-view 用例频道草稿持久化channel Input 用例画布区块block-canvas 用例。这些用例的共同特征是“无后端”playwright.config.ts自带webServer启动 Vite用固定端口与reuseExistingServer: true避免重复启动workers: 1保证串行失败才留截图与 trace。对验证者而言这类套件是确定性最高的证据来源而需要真实登录态、真实数据与 AI 返回的路径才依赖docs/agent-guide的手工式操作。常见失败模式速查把文档与指南中的约束集中成一张排查表便于在拿到broken或couldnt verify时快速定位现象优先怀疑依据couldnt verify提示缺少 URLprompt 未提供 app URL子代理按规则不自行起服务browser-verifier.md页面打不开 / 证书错误未信任infra/local/certs/ca.pem或端口与--instance不匹配README.md白屏但/app/返回 200某个 Vite 模块 502需连script请求一起看browser-technique.md输入后内容为空对 contenteditable 误用fill应点击后type_textbrowser-technique.md操作报“元素不可交互”点了 radio 输入而非相邻标签browser-technique.mdAI 编辑“看起来没完成”没有可靠文本信号需轮询“停止生成”按钮消失browser-technique.md满屏ERR_NETWORK_CHANGED环境网络抖动先用 curl 验证栈再重新导航browser-technique.md全屏“Something went terribly wrong”先按HomeLoroDoc 崩溃需ignoreCache: true重载browser-technique.md操作后要求重新登录浏览器重启导致页面 id 与会话失效browser-technique.md落地清单发起一次高质量验证请求要让这个子代理发挥最大价值父代理在发起时应当把四类信息写全正好对应它执行所需的输入改动描述改的是哪个 surface编辑器、路由、AI 界面、通知……期望看到什么行为。App URL本地栈或远程主机的完整/app/地址缺失就会得到couldnt verify。边界情况清单需要覆盖的空态、错误态、移动端窄屏、权限差异等。截图落盘目录不给则落到$TMPDIR。再加上两条使用建议按表面拆分成多次验证而不是一次塞进多个不相关表面——文档定义的就是“one described web change”拆小能让每份返回都有清晰的截图链路。在有既有 Playwright 回归的 surface 上先跑回归再手工验证用确定性用例兜底把人工/Agent 操作留给无法自动化的 AI 与实时交互路径。至此browser-verifier的设计意图可以一句话概括用一个只读、独立浏览器、必须读指南的子代理把“改动在真实浏览器里到底行不行”变成一份带截图证据、可审计、且不会污染主上下文的结论。它不替代auditor的静态检查也不替代仓库中的无后端回归而是补齐“用户真的能点通”这最后一环。赞分享后端前端协同办公即时通讯企业应用CRMAI Agent人工智能【免费下载链接】macroMacro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — -linked together with shared AI memory.项目地址https://gitcode.com/GitHub_Trending/macro3/macro点击查看免费下载相关推荐Lightpanda Browser 完全指南轻量级无头浏览器的实战应用Lightpanda Browser 完全指南轻量级无头浏览器的实战应用 你是否正在为传统浏览器资源消耗过大而烦恼是否需要在无头环境中高效执行网页自动化任务浏览器控制AI AgentMCP 服务GUI 自动化人工智能极速轻量无头浏览器Lightpanda Browser 完全使用指南极速轻量无头浏览器Lightpanda Browser 完全使用指南 Lightpanda Browser 是一款专为无头环境设计的开源浏览器以其极低的内存浏览器控制AI AgentMCP 服务GUI 自动化人工智能终极轻量级无头浏览器Lightpanda Browser 完整入门手册终极轻量级无头浏览器Lightpanda Browser 完整入门手册 Lightpanda Browser 是一款专为无头环境设计的开源浏览器以其极低的内浏览器控制AI AgentMCP 服务GUI 自动化人工智能上一篇终极指南如何用ComfyUI Video Combine节点制作专业级AI动画视频下一篇如何快速掌握AMD Ryzen专业调试工具面向初学者的完整使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考