Community生产力与协作github.com

运行

在本地启动站点或应用,并通过真实浏览器预览。自动从 package.json、配置文件或纯 index.html 识别技术栈,选择空闲端口,启动开发服务器或静态服务器,等待服务响应后截图或打开浏览器,并可通过一个标志停止服务。

运行 是什么?

这个技能提供了一个轻量级工具,用于在本地迅速启动 Web 项目并在浏览器中预览。它支持 Node.js(npm 脚本)、Python HTTP 服务器以及静态站点(dist/、build/、public/)等多种技术栈,自动检测配置并分配空闲端口。该工具通过 Playwright 在 1440px 宽度下渲染页面并截图,同时记录进程 PID、端口和 URL 到 `.run/state.json`,并可通过 `--stop` 参数正确终止进程。该技能强调正确性的验证循环:启动(可选截图)、人工检查、修正,并设有严格规则,如不留下持续运行的服务器、不启动无法停止的服务、报告真实 URL 和端口等。它适用于 Claude Code、Cursor、Codex 等 AI 助手环境,帮助开发者快速预览和验证 Web 应用的运行状态。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/itsdanylol/claude-sitecraft/tree/HEAD/skills/run

Installed? Explore more 生产力与协作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

运行 是做什么的?

一个站点只有在实际运行过之后才算完成。源代码告诉你的是作者的意图;而浏览器展示的是用户得到的最终效果。这个技能是从文件夹到渲染页面的最短路径。

运行它

node <skill 文件夹>/scripts/serve.mjs <目录> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
  • --detect 仅打印检测结果而不启动任何服务。当文件夹不熟悉时,先执行此操作。
  • --port 从指定端口开始查找,并使用下一个空闲端口,因此两个项目可以同时运行。
  • --open 打开默认浏览器。
  • --shot out.png 通过 Playwright 在 1440px 宽度下渲染页面,并截取整个页面高度的截图。
  • --stop 根据 .run/state.json 终止进程树。

它会在项目旁边写入 .run/state.json(包含 pid、port、url、command)和 .run/server.log。这两个文件是启动和停止之间交接的全部内容。

它检测的内容

找到的文件执行的操作
包含 dev、start、serve 或 preview 脚本的 package.json在空闲端口上运行 npm run <对应脚本>,并设置 PORT 环境变量
根目录下的 index.html在该文件夹上运行 python -m http.server
public/index.html、dist/index.html、build/index.html以构建输出目录为根目录启动静态服务器
存在配置文件但没有脚本报告并停止:该项目需要使用自己的命令
go.mod、Cargo.toml、pubspec.yaml报告并停止:请使用项目自身的运行命令

关于框架细节、端口默认值和需要了解的失败模式,请参阅 references/stacks.md。

结果的解读

该脚本只验证三件事:进程已启动、端口已响应、页面已渲染。但它无法告诉你:

  • 在 375、768 和 1440 宽度下布局是否正确(请使用 sitecraft/scripts/verify.mjs 来验证)
  • 控制台是否干净(此处不捕获控制台信息;verify.mjs 会捕获)
  • 截图中的页面是否就是用户想要的页面(请检查 URL 是否与您请求的路由一致)

因此循环是:serve.mjs --shot,用肉眼查看截图,修复,再次截图。一次操作最多进行三次渲染;超过这个次数,问题就不在于 CSS,而在于方案本身。

规则

  • 永远不要留下一个持续运行的服务器。 检查完成后停止它,或者明确说明它仍在运行及其端口。用户的机器上残留开发服务器会带来混乱。
  • 不要启动你无法停止的服务。 如果项目需要 Docker、数据库或付费 API 密钥,请先说明再启动任何东西。
  • 报告真实的 URL。 例如 localhost:4173,而不是“这个应用”。如果由于 4173 被占用而端口发生变更,请告知新的端口。
  • 在猜测之前先读取日志。 启动失败几乎总是由于缺少依赖、缺少环境变量或端口已被占用。.run/server.log 包含了答案,引用实际错误比猜测更有效。
  • 未经告知不要进行安装。 如果缺少 node_modules,通常 npm install 是正确的做法,但这也修改了用户的项目。执行后需说明已运行,或者当安装量较大时征得同意。
  • 优先使用静态服务器而非框架服务器。 当构建输出存在且是最新的时,提供 dist/ 目录比运行开发服务器更快、更准确。

当它无法启动时

  1. 读取 .run/server.log 并引用第一个真正的错误,而不是最后一行。
  2. 缺少依赖:在项目中运行 npm install,然后重试。
  3. 缺少环境变量:查找 .env.example,说明需要哪些变量,如果缺少敏感值则停止。
  4. 端口已被占用:脚本会自动跳到下一个空闲端口;如果仍然失败,通常是因为框架配置中硬编码了端口。
  5. 需要构建步骤:先运行 npm run build,然后提供 dist/ 目录。
  6. 原生或容器化应用:请使用项目文档中指定的命令。并非所有技术栈都适合用脚本处理。

检查清单

  • 检测技术栈而非猜测
  • 启动服务并看到真实的 HTTP 响应,而不仅仅是进程已生成
  • 报告确切的 URL 和端口
  • 查看了截图,而不仅仅是日志
  • 检查路由是否与预期的页面一致
  • 停止服务,或说明它仍在运行及其位置
  • 失败时引用了真正的错误信息

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能