mcpField
D
d3k

d3k

github.com/vercel-labs开发1.6k860 次安装2 天前更新
代码仓库

关于 d3k

d3k 是用于准备和操作项目服务器及托管浏览器的本地 Web 开发运行时技能。它将服务器、浏览器、网络、交互和截图记录到同一时间线上，供测试和调试使用。

主要功能

  1. 01启动或复用项目运行时
  2. 02Portless URL 和托管 Chrome 配置
  3. 03收集日志与浏览器证据
  4. 04操作受监控的浏览器
  5. 05在编辑和复测期间保留运行时

适用场景

  1. 01在受监控浏览器中复现项目问题
  2. 02检查服务器和浏览器错误
  3. 03代码更改后重新测试行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vercel-labs/dev3000 --skill d3k

安装后在 Claude Code 中输入/d3k确认已加载。

附带文件agents/openai.yamlPUBLISH.md

详细介绍

d3k Agent 运行时

d3k 是此任务的本地 Web 运行时。它会在稳定的 Portless URL 后启动开发服务器，使用项目专属的 Chrome 配置文件，并在同一时间线中记录服务器日志、浏览器控制台输出、网络活动、交互和屏幕截图。

此技能触发时，请操作 d3k，不要只告诉用户如何运行它。

解读请求

  • “让我用 d3k 测试／开发我的项目”：准备运行时和有界面浏览器，确认就绪后，将控制权交给用户。等待用户重现问题后，再检查证据。
  • “用 d3k 测试／调试／修复这个问题”：准备运行时，然后操作受管理的浏览器并自主调查。
  • 如果请求含糊，先启动运行时和浏览器。此操作对这两种情况都安全且有用。

启动或复用 d3k

从项目根目录运行。

  1. 启动任何应用进程之前，先检查 Portless 的规范就绪状态：
d3k portless status --json

如果 "setupRequired": true，请运行：

d3k portless setup

在 macOS 上，这会打开系统管理员授权对话框。等待用户批准，然后重新运行 d3k portless status --json。只有当 "canonical": true、"serviceInstalled": true 且 "setupRequired": false 时，才能启动 d3k。如果用户拒绝授权或无法完成授权，请停止并说明阻碍。绝不要悄悄改用直接访问 localhost。

  1. 检查是否已有该项目的运行时：
d3k status --json

仅当其报告 "running": true、"ready": true、"routing": "portless"、"browserConnected": true，且 appUrl 确实是无端口的 https://...localhost URL 时，才复用该运行时。如果活动会话报告 "routing": "direct"，请停止保留的 d3k 会话，并在 Portless 就绪后重新启动。不要启动第二个开发服务器或浏览器。

  1. 如果尚未安装 d3k，请安装：
bun install -g dev3000

仅当 Bun 不可用时，才使用 npm install -g dev3000。

  1. 使用 Agent 的 shell／进程工具，以保留在后台或可继续的会话启动 d3k（默认非 TUI）：
d3k -t

不要等待这个长时间运行的命令退出。保留其进程／会话句柄，以便稍后监控或停止。优先使用执行工具的后台／会话功能，而不是通过 shell 使用 &。

如果目标 URL 已知，请传入该 URL，以便受管理的浏览器在此处打开：

d3k -t --app-url "<url>"

让 d3k 自动检测包管理器、开发命令和端口。仅当检测有误或用户指定时，才添加 --command、--script 或 --port。

  1. 轮询，直到运行时就绪：
d3k status --json

只有在状态响应报告 "ready": true、"routing": "portless"、"browserConnected": true，且 appUrl 是无端口的 https://...localhost URL 时，才能将其视为已就绪。如果启动失败，请检查保留的进程输出和 d3k logs --type server；不要另行启动开发服务器。

用户主导的测试

用户说“让我测试”时：

  1. 确认状态响应包含应用 URL，且 "browserConnected": true。
  2. 告知用户受监控的浏览器已就绪。
  3. 保持 d3k 进程运行，等待用户重现相关行为。
  4. 用户报告问题已发生后，从以下命令开始：
d3k errors --context
d3k logs -n 200

用户测试期间，不要用自动化替代有界面浏览器。

Agent 主导的测试

操作 d3k 正在监控的确切浏览器：

d3k agent-browser snapshot -i
d3k agent-browser click @e2
d3k agent-browser fill @e3 "text"
d3k errors --context

打开 URL 时使用 --require-d3k-browser，以防失败时悄悄创建另一个浏览器：

d3k agent-browser --require-d3k-browser open "<url>"

每次重现问题或更改代码后，都要重新执行相关交互，并再次检查 d3k errors --context。

证据命令

优先使用以下命令，而不是临时抓取日志：

d3k status --json
d3k errors --context
d3k logs -n 200
d3k logs --type browser
d3k logs --type server

产物位于 ~/.d3k/<project>/ 下，包括 session.json、日志、屏幕截图和 Chrome 配置文件。

浏览器与身份验证安全

默认情况下，d3k 必须负责启动浏览器。它的每项目 Chrome 配置文件会保留登录状态、Cookie 和本地存储。

对于 Google OAuth、Supabase 身份验证及其他对身份验证敏感的流程，切勿改用原始 Chrome、Playwright、浏览器 MCP 会话、手动 CDP 附加或 agent-browser --profile。这些方式会使用不同的浏览器／配置文件，并可能触发“This browser or app may not be secure.”错误。

如果托管浏览器不可用，请停止或中断保留的 d3k 进程，然后干净地重启 d3k。不要通过创建另一个浏览器来绕过问题。

仅在 CI 环境中或明确提出要求时使用 --headless。仅当确实不需要浏览器监控时使用 --servers-only。

操作规则

  • 不要在 d3k 运行期间同时运行 npm run dev、bun run dev 或其他开发服务器。
  • 如果 d3k status --json 报告已有活动实例，不要再启动第二个 d3k。
  • 编辑和重新测试期间，让 d3k 保持运行。
  • 保留项目专用且稳定的 Chrome 配置文件，除非用户明确要求使用全新配置文件。
  • 将带界面的浏览器交给用户时，让运行时继续运行；仅在用户要求或任务需要干净重启时才停止。
  • 默认必须使用规范的 Portless HTTPS 路由。除非用户明确要求直接通过 localhost 路由，否则绝不要添加 --no-portless 或设置 PORTLESS=0。

评论

支持 Markdown