用途
Portless（来自 Vercel Labs）是一个本地开发用 HTTPS 代理，用命名 URL 取代端口号，在本地开发角色上是 Caddy/nginx 的替代品，明确不适用于生产环境。上游项目为 vercel-labs/portless（Apache-2.0 许可）。本技能在上游规范用法之外，补充了在实际生产中验证过的运维模式，包括 Windows 特定事项、静态别名配合进程管理器模式、TLD 重置流程与供应链卫生。规范 CLI 用法以上游参考文件为准。
心智模型与职责边界
Portless 拥有：路由（主机名到端口映射、HTTPS 终止、HTTP/2、CA 信任）、命名（<名称>.<TLD> 形态，每个代理一个 TLD）、以及在以 portless myapp <cmd> 调用时的进程派生。Portless 不拥有：进程守护（需使用 Process Compose 或 PM2）、每个服务独立 TLD（不支持）、崩溃恢复、重启策略与健康检查。关键形态约束：portless 始终渲染为 <别名>.<TLD>，一个代理内不能混用两个 TLD，因为 TLD 是每实例的；带点的别名如 portless alias api.<app> 8108 会被追加 TLD，变成 api.<app>.<tld>。
安装
使用 npm install -g portless@0.13.0 固定具体版本（零运行时依赖，供应链面小），安装后用 portless --version 验证。建议在仓库中记录固定版本，升级走显式 PR。
CLI 速查
代理生命周期：portless proxy start --tld lab --port 443（在 443 上启动 HTTPS 代理，路由 *.lab）、portless proxy start --tld test --port 1355（非特权端口用于测试）、portless proxy stop、portless trust（将 CA 加入系统信任库）。
别名（用于 portless 未派生的服务，如 PM2、Process Compose、Docker 等）：portless alias axiom 8108（https://axiom.lab → :8108）、portless alias axiom 8108 --force（覆盖已有）、portless alias --remove axiom（注意会追加 TLD，需谨慎）。
派生模式（portless 管理进程）：portless myapp next dev（https://myapp.lab，自动端口 4000-4999）、portless run pnpm dev（从 package.json 自动推断名称）。
发现（便于智能体）：portless list（活动路由）、portless get axiom（返回 https://axiom.lab）。
开机持久化：portless service install（操作系统原生启动任务）、portless service status、portless service uninstall。
静态别名模式（portless + 外部进程管理器）
常见做法：由进程管理器（Process Compose、PM2、Docker）在固定端口上运行开发服务器，portless 只负责将命名 URL 路由到这些端口，例如 portless alias <your-app> <your-port>。这种解耦意味着：重启开发服务器（如 pm2 restart <your-app>）后 portless 路由保持透明；互换进程管理器不影响 portless 层。建议把别名注册放在进程管理器配置中作为唯一事实来源，例如用 scripts/install.ps1 从 process-compose.yaml 读取服务名与端口并注册别名。
TLD 选择
.localhost（默认）：启动最快，在多数系统上自动解析到 127.0.0.1。.lab：个人/有辨识度，非 IANA 保留（本地实际无 DNS 冲突）。.test：对 OAuth 友好，IANA 保留、安全。.dev：用于 OAuth（Google、Apple），Google 所有、强制 HTTPS，portless 可正常处理。.local：避免使用，与 mDNS/Bonjour 冲突。OAuth 提供方会拒绝 .localhost 子域（不在公共后缀列表中），做 OAuth 开发时切换到 --tld test 或 --tld dev。
重置（干净状态）
停止代理后，删除别名文件 ~/.portless/routes.json（Linux/macOS），PowerShell 下为 Remove-Item "$env:USERPROFILE\.portless\routes.json"；再以目标 TLD 重新启动代理并重新注册别名。更改 TLD 时这是正确做法，因为 portless alias --remove 会追加当前 TLD，容易造成干扰。
Windows 特定事项
需要在 PATH 中有 openssl。Portless 用 OpenSSL 生成本地 CA，Git for Windows 自带该工具，可将 C:\Program Files\Git\usr\bin 加入用户 PATH，否则报错 Error: openssl failed: spawnSync openssl ENOENT。开机持久化方面，portless service install 注册任务计划程序条目，建议再配合进程管理器自身的开机任务，并检查两者均已注册。关于证书：Windows 上 curl 使用自带 CA 存储而非系统存储，因此即使执行过 portless trust，curl 访问仍会返回 000；可用 -k 跳过验证，或用 --cacert ~/.portless/ca.pem。浏览器使用系统存储，不受影响。
常见错误
openssl failed: spawnSync openssl ENOENT：OpenSSL 不在 PATH，加入 Git 的 usr/bin。No alias found for "foo.lab"：--remove 会追加 TLD，有时会多追加，清理 routes.json 后重新注册。浏览器显示证书警告：CA 未加入系统信任库，重新运行 portless trust（可能需要管理员权限）。访问 https://name.lab 显示“未注册应用”：别名未设置或代理已停止，用 portless list 确认并重新注册。Safari 无法解析 *.lab：Safari 使用系统 DNS 而非 Node 解析器，可用 portless hosts sync 写入 /etc/hosts。启动代理时 443 端口冲突：被其他服务（Caddy、IIS）占用，停止该服务或测试时改用 --port 1355。
反模式
重复为同一名称注册不同端口而不加 --force，第二次会静默失败；把 portless 当生产反向代理（应仅用于开发，生产用 nginx/Caddy/云负载均衡）；依赖 portless 做崩溃恢复（其对派生进程没有该能力，应搭配 Process Compose / PM2 / supervisord）；通过停启并更换 --tld 来改 TLD 并期望别名自动更新（正确做法是停代理、清理 routes.json、以新 TLD 启动、从进程管理器配置重新注册）。
本技能内资源
参考文件包括上游 portless SKILL.md 逐字副本（CLI 参考、monorepo、turborepo、worktrees、LAN、Tailscale、HTTPS、故障排查）、上游 OAuth 设置（Google/Apple/Microsoft/Facebook/GitHub）、TLD 选择决策树、Windows 特定事项、集成模式（与 Process Compose / Docker / PM2 / Tailscale / git worktrees 组合）。脚本包括 install-portless.ps1、reset-state.ps1、sync-aliases-from-yaml.ps1。资产包括单应用、monorepo、自定义 TLD 的 portless.json 模板及 package.json 内嵌 portless 配置示例。相关技能：process-compose-ops、mcp-ops、cli-ops。
限制
Portless 为本地开发用途，不适用于生产；不提供进程守护与崩溃恢复；一个代理实例只能使用一个 TLD；OAuth 场景下不支持 .localhost 子域。