mehdi214designer/server-studio

保存服务器到仪表板

用户运行 Server Studio，一个列出本地服务器并支持一键运行/停止的应用。 此技能用于将服务器添加到该仪表板，避免遗漏。

使用时机

在搭建或设置任何运行在本地端口的项目后，进行注册。示例：

• 您搭建了一个站点/应用，开发命令为 npm run dev，运行在 localhost:3000
• 您启动了静态预览、Vite/Next/Astro 服务器、php -S、wp-env、Storybook 等
• 用户要求“保存服务器”、“添加到仪表板”、“注册此项目”

如果运行命令或端口尚不明确，请先确认（检查 package.json 中的 scripts、框架默认端口，或服务器启动时打印的信息）。不要胡乱猜测。

黄金法则：每个项目一个永久端口

每个项目分配一个固定的、唯一的、永不改变的端口。保存的条目只有在端口正确时才有用，因此：

1. 一次性分配。 对于新项目，使用 --assign 让脚本自动选择一个空闲且从未使用过的端口（或直接指定 --url）。这保证没有两个项目共享端口。

2. 将其嵌入项目，使开发服务器始终使用该确切端口，避免随机端口。使用框架的 strict-port 选项，确保端口冲突时报错而不是漂移到其他端口。

   合并，而非替换。 如果已有配置，仅修改端口和 strict-port 相关键，保留其他所有键不变。server 块通常包含 proxy、host、https 或 hmr 等手动调整的设置，丢失这些设置比端口漂移更糟糕。如果无法精确编辑，请停止操作并告知用户，而不是重写整个块。

   • Vite：在 vite.config 中设置 server.port 为 <n> 且 server.strictPort 为 true，保留 server 中已有的其他键。仅当不存在 server 块时，才添加仅包含这两个键的块。（或者保持配置不变，在开发脚本中使用 vite --port <n> --strictPort。）
   • Next.js：开发脚本 → next dev -p <n>
   • Astro：astro dev --port <n>
   • CRA / react-scripts：PORT=<n> react-scripts start
   • 普通 Node/Express：读取 process.env.PORT || <n> 并记录端口
   • PHP：php -S localhost:<n> 在注册的 --command 和 --url 中使用完全相同的端口。

3. 绝不要重新分配。 对同一项目重复运行技能会保留其已锁定的端口——仅更新其他字段。脚本会强制执行此规则；除非用户明确要求将项目迁移到新端口，否则不要传递 --force。

如何保存

使用已知字段运行帮助脚本。仅 --name（或 --url/--command）为必需。

对于新项目，添加 --assign 以获取保证唯一的端口，然后读取它打印的 PORT <n> 行，并将该端口嵌入项目配置（参见上面的黄金法则）。

node "$HOME/.claude/skills/server-studio/register-server.js" \
  --name "项目名称" \
  --project "所属项目/任务" \
  --folder "WordPress" \
  --cwd "/绝对/路径/到/项目" \
  --command "npm run dev -- --port 3001 --strictPort" \
  --url "localhost:3001" \
  --tag "Vite" \
  --note "需要记住的任何信息，例如登录信息" \
  --assign

字段说明：

• --name — 简短标签，例如“作品集网站”
• --project — 所属的项目/任务
• --folder — 归档的文件夹名称（如不存在则创建，显示在侧边栏中）。--category 作为旧版本调用者的别名仍然可用。
• --cwd — 项目绝对路径；运行命令在此目录下执行
• --command — 启动服务器的确切命令（运行按钮将执行此命令）
• --url — 地址或裸端口（3000 即可，自动补全为 localhost:3000）
• --tag — 小细节：Vite、MAMP、Next、php
• --note — 可选提醒（凭据、注意事项）

行为说明

• 脚本通过 文件夹（cwd）或 名称 匹配已有项目。如果找到，则更新该条目但保持其锁定端口；否则添加新条目。可以安全重复运行，不会创建重复条目，也不会更改项目的端口。
• 所有条目间端口唯一。--assign 从 3001 开始选择最低空闲端口。
• 脚本输出 PORT <n>——在配置项目开发设置时使用该数字。
• 数据写入 Server Studio 数据文件：macOS 为 ~/Library/Application Support/Server Studio/data.json，Windows 为 %APPDATA%\Server Studio\data.json，Linux 为 ~/.config/server-studio/data.json。
• 仪表板每几秒自动刷新，因此新建或更新的条目会自动显示。

助手默认行为

当您完成带有本地服务器的项目搭建后，自动保存该项目，并用一行文字告知用户已保存的内容。保持简洁，例如“已将'X'保存到您的 Server Studio，重新加载标签页即可运行。”仅当确实没有本地服务器时才跳过保存。