Paseo 端口分配与 Worktree 机制

一、为什么需要这套机制

当你同时跑多个 AI Coding Agent 操作同一个项目时，会遇到三层冲突：

Paseo 从平台层抽象掉这些问题。核心两招：Git Worktree 隔离 + 统一反向代理。

二、第一层隔离：Git Worktree

给每个 Agent 任务创建独立的 Git Worktree——自己的目录、分支、node_modules。

三、第二层解决：动态端口分配

paseo.json：项目自描述

{
  "worktree": { "setup": "npm ci" },
  "scripts": {
    "web": {
      "type": "service",
      "command": "npm run dev -- --port $PASEO_PORT",
      "port": 3000
    },
    "api": {
      "type": "service",
      "command": "go run . --port $PASEO_PORT"
    }
  }
}

四、第三层统一：反向代理 + 可读 URL

*.localhost 自动解析到 127.0.0.1，不改 hosts。

五、WebSocket 自动透传

检测到 Upgrade: websocket 后自动升级为 TCP 隧道，Vite HMR / Next.js Fast Refresh 全部正常工作。

六、服务间互相发现

# web 进程里自动注入的环境变量：

PASEO_PORT=14001
PASEO_URL=http://web--feat-x--my-app.localhost:6767

PASEO_SERVICE_API_PORT=14002
PASEO_SERVICE_API_URL=http://api--feat-x--my-app.localhost:6767

七、完整工作流

八、有无 Paseo 的对比

九、设计哲学

十、工程意义

10.1 端口问题是症状，不是病因

EADDRINUSE 只是表象。真正的工程问题有两个：

10.2 这条思路的工程谱系

Paseo 的做法不是凭空冒出来的。它在工程史上有两条清晰的谱系：

10.3 为什么这不是「过度工程」

从单 Agent 视角看，确实一把 PORT 就能用。但问题在于：

• N 个 Agent 并行时，需要 N 个不冲突的端口，而且需要知道哪个端口对应哪个 Agent。管理 O(N) 的手工配置很快失控。
• Vite 的 WS 端口（24678）不受 PORT 控制，这是框架层面的硬编码。只改 HTTP 端口不够。
• 多服务项目（前端 + 后端 + 数据库），需要 N×M 个端口的协调编排。
• 跨设备访问，手机/另一台电脑需要知道 VPS 上某 Agent 的端口。纯数字不可读、不可记、不可分享。

Paseo 的整套机制，本质上是把 N 个 Agent × M 个服务的 O(N×M) 手工配置复杂度，降维成一个 paseo.json 声明 + 零配置运行时。

10.4 对开发体验的降维打击

10.5 更深远的意义：Agent 时代的「开发环境即服务」

过去十年，CI/CD 把「构建环境」变成可编排的服务。现在 Agent 来了，「开发环境」也需要变成可编排的服务——不只是 Docker 容器这样笨重的方案，而是轻量、瞬时、可按需创建和销毁的 worktree + 动态路由。

Paseo 的这套机制，本质上是 Development Environment as a Service（DEaaS）的最小可行实现：声明一个 paseo.json → 得到一个完整隔离、可预览、可分享、可远程操控的开发环境。

这个方向不再只是「让 Agent 不撞端口」——它是在定义 Agent 时代的开发基础设施标准。

十一、封装为独立模块的可能性

Paseo 内部的四个核心能力，每一个都可以拆成独立可复用的模块。以下逐一分析接口、可行性、以及如果独立发布会是什么形态。

模块间的依赖关系

如果今天就要拆：推荐的独立模块顺序

独立模块的战略价值

拆分的代价与边界

• API 稳定性承诺：独立模块意味着独立 semver。接口一旦发布就有兼容性包袱，不像内部模块可以随意重构。
• 集成测试成本：4 个模块组合使用时，集成问题（如端口分配了但代理没注册上）的责任边界需要额外测试覆盖。
• 跨模块的「Group」概念：当前 Paseo 的 worktree 是隐式的 group——同一 worktree 的 services 自动互相可见。拆开后需要显式传递给每个模块。
• 进程生命周期管理：Reverse Proxy 需要知道目标进程是否还活着（否则路由指向死端口）。这块逻辑目前和 daemon 耦合，拆分需要定义 clear 的 health check 接口。

一个可能的开放标准：「Dev Workspace Spec」

如果这四个模块不只是 Paseo 的内部实现，而是成为社区标准，可以定义一个 dev-workspace.json 规范：

这个 spec 可以同时被 Paseo、Multica、CI 系统、甚至 VS Code 插件消费。任何一个实现了 spec 的 runtime（Paseo daemon / 自定义 runner / CI agent），拿到的都是一份标准化的 workspace 描述。