用途
watch 描述了一套“先捕获、再诊断”的监控式开发方法。它不依靠猜测故障原因,而是要求先完整记录时间线,再读取分析。d3k(dev3000)把服务器、浏览器和网络事件统一到一份日志中,使根因更容易被看到。
主要能力
- 统一时间线:服务器、浏览器、网络事件集中记录。
- 错误上下文:通过 d3k errors --context 查看错误及其前后交互事件。
- 来源分类:输出中的来源标签用于判断排查方向:
- [SERVER]:后端崩溃或异常,查服务端代码、依赖、环境变量。
- [CONSOLE ERROR]:前端 JS 错误,查组件代码、状态、props。
- [NETWORK] 4xx:客户端请求问题,查 URL、认证头、请求体。
- [NETWORK] 5xx:服务端处理问题,查 API 路由、数据库查询、外部服务。
- [RUNTIME.ERROR]:未处理的 rejection 或异常,查异步代码、错误边界。
- 日志过滤:d3k logs --type browser / server / network 按来源查看。
- 页面快照与截图:通过 agent-browser 结合 CDP 端口获取页面快照或截图。
- AI 辅助诊断:d3k fix 可基于已捕获上下文给出诊断,支持 -f 聚焦某类错误、-t 限定时间范围。
使用方式
- 检查前置条件:which d3k || npm install -g dev3000,which portless || npm install -g portless。
- 读取 package.json 的 scripts,确定开发命令与包管理器。
- 启动受监控会话,同时启用 CDP 浏览器监控:
portless <name> d3k -c "<runner> <dev-cmd>" --no-tui --no-skills --no-agent
示例:
portless myapp d3k -c "bun run dev" --no-tui --no-skills --no-agent portless playground d3k -c "bun next dev --webpack" --no-tui --no-skills --no-agent portless docs d3k -c "npx vitepress dev" --no-tui --no-skills --no-agent
d3k 会自动启动受 CDP 监控的 Chrome,portless 提供稳定地址(<name>.localhost:1355)。只有在明确要求跳过浏览器启动时才使用 --servers-only。
- 调试循环:启动后复现问题,执行 d3k errors --context,按来源标签分类,修复后再次复现,直到 d3k errors 输出干净。
- 检查页面状态:d3k agent-browser --cdp $(d3k cdp-port) snapshot -i,必要时用 screenshot /tmp/page.png 截图。
- 日常监控开发:从开始就用 d3k 启动,定期 d3k logs --type browser 检查警告,提交前运行 d3k errors。
- 复杂时间线可用 d3k fix、d3k fix -f build、d3k fix -t 5 让工具综合诊断。
适用场景
- 调试 Web 应用,需要同时看到前端、后端与网络行为。
- 需要读取错误上下文、判断因果链而非单条报错。
- 需要记录浏览器交互作为调试或验证证据。
- 与 hope:loop 配合,在失败时提供调试证据;与 hope:verify 配合,用截图作为视觉回归证据。
限制与注意事项
- 不要让开发服务器脱离 d3k 单独运行,否则无法完整捕获。
- 不要在没有捕获时间线的情况下直接诊断。
- 默认不要使用 --servers-only,它会关闭最有价值的 CDP 浏览器监控。
- d3k 子命令中 -c 与 --command 冲突,应使用长参数 --context、--type。
- 不要只修复表面症状;例如前端因接口失败而崩溃,应修后端接口。
- 资料未提供 d3k 或 portless 的收费、平台支持范围、性能数据等细节,暂未提供。
产品信息
名称:watch 来源目录:saadshahd/moo.md 地址:https://www.skills.sh/saadshahd/moo.md/watch