worktree-bay 1.5.1 → 2.1.0

package/README.md

@@ -5,13 +5,13 @@
 
 > 配置驱动、与语言/技术栈无关的 **git worktree 槽位 + 端口编排器**——为多服务并行开发而生。
 
-一个功能来了，先**占一个槽位**，用到哪个服务就在哪个服务开一个 worktree 挂进这个槽。同一槽里的所有服务共享一套**端口块**、各自独立进程，前端自动接上同槽的后端。工具替你管好 worktree 路径、端口分配、依赖、`.env` 注入与回收。
+一个功能来了，先**占一个槽位 `N`**，用到哪个服务就在哪个服务开一个 worktree 挂进这个槽。每个服务有自己的**端口段**，同槽的各服务都取段里的第 `N` 个端口（`服务基址 + N`）、各自独立进程，前端自动接上同槽的后端。工具替你管好 worktree 路径、端口分配、依赖、`.env` 注入与回收。
 
 ## 为什么
 
 在 monorepo / 多仓工作区里并行开发多个功能时，git worktree 能隔离代码，但隔离不了运行时——端口会撞、依赖要重装、前端连不上你本地起在偏移端口的后端。`worktree-bay` 在 worktree 之上补一层「**功能 = 槽位**」的编排：
 
-- **端口不撞**：每个功能占一个槽 `N`，得到端口块 `6000 + N*10`，块内各服务按固定偏移取端口。
+- **端口不撞**：每个服务有自己的端口段，功能占槽 `N` → 各服务用 `自己的基址 + N`，与主 dev（槽 0）和其它槽天然错开。
 - **免重装**：依赖从主 checkout 拷贝（或按服务自定义安装命令），不必每个 worktree 从头装。
 - **前端自接后端**：前端按「同槽上游服务」自动把 api base 指向本槽后端端口。
 - **不泄漏**：槽位占用从文件系统派生；`gc` 合并感知回收（已并入主分支且干净才删，保守不误删）。
@@ -52,12 +52,10 @@ worktree-bay gc
 ```jsonc
 {
   "workspaceRoot": "/path/to/workspace",
-  "portBase": 6000,
-  "slotSpan": 10,
   "maxSlots": 9,
   "services": {
     "api": {
-      "offset": 1,
+      "port": 6001,                                                // 端口段基址（= 主 dev/槽0），槽 N 用 6001+N
       "vars": { "project": "myapi-{slug}" },
       "copy": [".env", "vendor"],                                  // 从主 checkout 递归拷文件/目录
       "env": { ".env": { "APP_PORT": "{port}" } },                 // 合并键值进 dotenv（保留其它键）
@@ -67,7 +65,7 @@ worktree-bay gc
       "run": { "test": ["composer", "run", "test"] }               // 命名命令
     },
     "lms": {
-      "offset": 2,
+      "port": 6011,                                                // 与 api 段不重叠（间距 > maxSlots）
       "upstream": { "service": "api", "fallback": "http://localhost:6001" }, // → {upstreamBase}
       "env": { ".env.dev.local": { "VITE_API_BASE_URL": "{upstreamBase}" } },
       "setup": "pnpm install",
@@ -81,7 +79,7 @@ worktree-bay gc
 
 | 原语 | 说明 |
 |---|---|
-| `offset`（必填） | 本服务端口 = `块基址 + offset`，各服务互不相同、`1 ≤ offset < slotSpan` |
+| `port`（必填） | 本服务端口段基址（= 主 dev/槽0）；槽 N 端口 = `port + N`；各服务的段 `[port, port+maxSlots]` 互不重叠 |
 | `repo` | 仓库目录名（相对 workspaceRoot），默认 = 服务名 |
 | `vars` | 自定义模板变量 |
 | `copy` | 从主 checkout 递归拷贝的文件/目录（含依赖目录） |
@@ -94,11 +92,11 @@ worktree-bay gc
 
 ### 模板变量
 
-`{slot}` `{blockBase}` `{port}` `{slug}` `{worktree}` `{repo}` `{upstreamBase}` `{cmd...}`，以及 `vars` 里自定义的。
+`{slot}` `{port}` `{slug}` `{worktree}` `{repo}` `{upstreamBase}` `{cmd...}`，以及 `vars` 里自定义的。
 
 ## 工作原理
 
-- **槽位 = 端口块**：功能占槽 `N`（1..`maxSlots`）→ 端口块 `portBase + N*slotSpan`；块内服务按 `offset` 取端口。
+- **按服务分段**：每个服务有自己的端口段（基址 `port` = 主 dev/槽0），功能占槽 `N`（1..`maxSlots`）→ 该服务用 `port + N`。服务数量无上限，各段不重叠即可。
 - **占用从文件系统派生**：槽是否被占，看各服务 `<repo>/.worktrees/s<N>-*` 目录是否存在；`.worktree-bay-slots.json` 只是「功能名 → 槽号」的标签账本（预约）。删了 worktree，槽自动空出。
 - **并发安全**：`claim/add/rm/gc` 全程持工作区原子锁。
 - **前端自接**：前端有 `upstream` 时，若同槽已起该上游服务的 worktree，就把 api base 指向本槽端口；否则用 `fallback`。
@@ -128,7 +126,7 @@ worktree-bay completion install
 }
 ```
 
-> 服务在哪个工作区目录启动，就用哪个目录的 `worktree-bay.config.json`（或设 `WORKTREE_BAY_CONFIG`）。暴露的工具：`worktree_bay_up / ls / add / run / down / gc`。
+> 服务在哪个工作区目录启动，就用哪个目录的 `worktree-bay.config.json`（或设 `WORKTREE_BAY_CONFIG`）。暴露的工具：`worktree_bay_up / ls / add / path / run / down / gc / skill`（`ls` 以 JSON 返回各 worktree 路径，`path` 直接给某功能某服务的目录，`skill` 取完整指南）。
 
 ## 许可证
 

package/dist/cli.js

@@ -40,7 +40,7 @@ program.command('init').description('在当前工作区生成 worktree-bay.confi
 catch (e) {
     die(e.message);
 } });
-program.command('claim <feature>').description('为功能占一个槽位（端口块）')
+program.command('claim <feature>').description('为功能占一个槽位（打印各服务在该槽的端口）')
     .action(async (f) => { try {
     await claimCommand(loadConfig(process.cwd()), f);
 }

package/dist/commands/claim.js

@@ -1,11 +1,10 @@
 import { withLock } from '../lock.js';
 import { claim } from '../slots.js';
-import { blockBase } from '../ports.js';
+import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
 export async function claimCommand(cfg, feature) {
     const slot = await withLock(cfg.workspaceRoot, async () => claim(cfg, feature));
-    const base = blockBase(cfg.portBase, cfg.slotSpan, slot);
-    log(`功能 "${feature}" → 槽 ${slot}（块 ${base}）`);
+    log(`功能 "${feature}" → 槽 ${slot}`);
     for (const [n, sp] of Object.entries(cfg.services))
-        log(`  ${n.padEnd(8)} ${base + sp.offset}`);
+        log(`  ${n.padEnd(8)} ${portOf(sp.port, slot)}`);
 }

package/dist/commands/completion.js

@@ -11,10 +11,10 @@ export function complete(cfg, words) {
         return SUBCMDS;
     const sub = prev[0];
     const pos = prev.length;
-    const featureSubs = ['up', 'add', 'rm', 'down', 'run', 'sh'];
+    const featureSubs = ['up', 'add', 'rm', 'down', 'run', 'sh', 'path'];
     if (featureSubs.includes(sub) && pos === 1)
         return Object.values(readLabels(cfg));
-    if (['add', 'run', 'sh'].includes(sub) && pos === 2)
+    if (['add', 'run', 'sh', 'path'].includes(sub) && pos === 2)
         return Object.keys(cfg.services);
     if (sub === 'up' && pos >= 2)
         return Object.keys(cfg.services); // up 接变长服务列表

package/dist/commands/doctor.js

@@ -12,7 +12,7 @@ export function doctor(cfg) {
         ok('git 可用');
     else
         bad('git 不可用（worktree 依赖 git）');
-    ok(`配置已加载并通过校验（${Object.keys(cfg.services).length} 个服务，槽位 1..${cfg.maxSlots}，端口块 ${cfg.portBase}+N*${cfg.slotSpan}）`);
+    ok(`配置已加载并通过校验（${Object.keys(cfg.services).length} 个服务，槽位 1..${cfg.maxSlots}，端口 = 服务基址 + 槽号）`);
     for (const name of Object.keys(cfg.services)) {
         const repo = repoPath(cfg, name);
         if (!fs.existsSync(repo))

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { log, warn } from '../util/log.js';
-// 引导生成一份 worktree-bay.config.json：扫描 cwd 子目录里的 git 仓预填为服务
+// 引导生成一份 worktree-bay.config.json：扫描 cwd 子目录里的 git 仓预填为服务（按服务分配端口段）
 export function initCommand(cwd) {
     const target = path.join(cwd, 'worktree-bay.config.json');
     if (fs.existsSync(target)) {
@@ -18,19 +18,19 @@ export function initCommand(cwd) {
     let services;
     if (repos.length) {
         services = {};
-        repos.slice(0, 9).forEach((r, i) => { services[r] = { offset: i + 1, setup: 'echo TODO: 起本服务的命令', run: { test: ['echo', 'TODO'] } }; });
+        repos.forEach((r, i) => { services[r] = { port: 6001 + i * 10, setup: 'echo TODO: 起本服务的命令', run: { test: ['echo', 'TODO'] } }; });
     }
     else {
         services = {
-            api: { offset: 1, copy: ['.env'], env: { '.env': { APP_PORT: '{port}' } }, setup: 'echo TODO: 起后端', run: { test: ['echo', 'TODO'] } },
-            web: { offset: 2, upstream: { service: 'api', fallback: 'http://localhost:6001' }, env: { '.env.local': { VITE_API_BASE_URL: '{upstreamBase}' } }, setup: 'pnpm install', start: 'pnpm dev --port {port}' },
+            api: { port: 6001, copy: ['.env'], env: { '.env': { APP_PORT: '{port}' } }, setup: 'echo TODO: 起后端', run: { test: ['echo', 'TODO'] } },
+            web: { port: 6011, upstream: { service: 'api', fallback: 'http://localhost:6001' }, env: { '.env.local': { VITE_API_BASE_URL: '{upstreamBase}' } }, setup: 'pnpm install', start: 'pnpm dev --port {port}' },
         };
     }
-    const config = { workspaceRoot: cwd, portBase: 6000, slotSpan: 10, maxSlots: 9, services };
+    const config = { workspaceRoot: cwd, maxSlots: 9, services };
     fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n');
     log(`✓ 已生成 ${target}`);
     if (repos.length)
-        log(`  识别到服务: ${repos.join(', ')}（按目录预填，offset 自增）`);
+        log(`  识别到服务: ${repos.join(', ')}（每个分配一段端口，基址间隔 10）`);
     else
         log(`  未识别到子 git 仓，已写入 api/web 示例模板`);
     log(`  下一步：补全各服务的 setup/env/upstream/exec/run。完整配置说明：worktree-bay skill`);

package/dist/commands/ls.js

@@ -1,5 +1,5 @@
 import { scanOccupancy, readLabels } from '../slots.js';
-import { blockBase } from '../ports.js';
+import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
 export function renderSlots(cfg) {
     const occ = scanOccupancy(cfg);
@@ -7,9 +7,8 @@ export function renderSlots(cfg) {
     const slots = new Set([...occ.keys(), ...Object.keys(labels).map(Number)]);
     const lines = [];
     for (const n of [...slots].sort((a, b) => a - b)) {
-        const base = blockBase(cfg.portBase, cfg.slotSpan, n);
-        const svc = (occ.get(n) ?? []).map((o) => `${o.service}@${base + cfg.services[o.service].offset}`);
-        lines.push(`slot ${n}  ${labels[String(n)] ?? '(unnamed)'}  block=${base}  [${svc.join(', ') || 'no worktree'}]`);
+        const svc = (occ.get(n) ?? []).map((o) => `${o.service}@${portOf(cfg.services[o.service].port, n)}`);
+        lines.push(`slot ${n}  ${labels[String(n)] ?? '(unnamed)'}  [${svc.join(', ') || 'no worktree'}]`);
     }
     return lines.join('\n') || '(no slots in use)';
 }
@@ -17,9 +16,9 @@ export function slotsData(cfg) {
     const occ = scanOccupancy(cfg);
     const labels = readLabels(cfg);
     const slots = new Set([...occ.keys(), ...Object.keys(labels).map(Number)]);
-    return [...slots].sort((a, b) => a - b).map((n) => {
-        const base = blockBase(cfg.portBase, cfg.slotSpan, n);
-        return { slot: n, feature: labels[String(n)] ?? null, block: base, services: (occ.get(n) ?? []).map((o) => ({ service: o.service, port: base + cfg.services[o.service].offset, dir: o.dir })) };
-    });
+    return [...slots].sort((a, b) => a - b).map((n) => ({
+        slot: n, feature: labels[String(n)] ?? null,
+        services: (occ.get(n) ?? []).map((o) => ({ service: o.service, port: portOf(cfg.services[o.service].port, n), dir: o.dir })),
+    }));
 }
 export function lsCommand(cfg, json = false) { log(json ? JSON.stringify(slotsData(cfg), null, 2) : renderSlots(cfg)); }

package/dist/config.js

@@ -3,33 +3,35 @@ import path from 'node:path';
 function refs(tpl) { return [...tpl.matchAll(/\{(\w+)\}/g)].map((m) => m[1]); }
 export function parseConfig(configPath) {
     const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    for (const k of ['workspaceRoot', 'portBase', 'slotSpan', 'maxSlots'])
+    for (const k of ['workspaceRoot', 'maxSlots'])
         if (raw[k] === undefined)
             throw new Error(`config: ${k} required`);
+    const maxSlots = raw.maxSlots;
     const services = raw.services ?? {};
-    const offsets = new Set();
+    // 端口段：每个服务 [port, port+maxSlots]（port=主 dev/槽0，槽 1..maxSlots 落在段内）
     for (const [name, sp] of Object.entries(services)) {
-        if (typeof sp.offset !== 'number')
-            throw new Error(`config: ${name}.offset required`);
-        if (sp.offset < 1 || sp.offset >= raw.slotSpan)
-            throw new Error(`config: ${name}.offset must be 1..${raw.slotSpan - 1}`); // V2
-        if (offsets.has(sp.offset))
-            throw new Error(`config: duplicate offset ${sp.offset} (${name})`); // V1
-        offsets.add(sp.offset);
+        if (typeof sp.port !== 'number' || sp.port < 1)
+            throw new Error(`config: ${name}.port must be a positive number`); // V2
         const repoDir = path.join(raw.workspaceRoot, sp.repo ?? name);
         if (!fs.existsSync(repoDir))
             throw new Error(`config: ${name}.repo dir missing: ${repoDir}`); // V5
     }
+    const entries = Object.entries(services);
+    for (let i = 0; i < entries.length; i++)
+        for (let j = i + 1; j < entries.length; j++) { // V1: 段不重叠
+            if (Math.abs(entries[i][1].port - entries[j][1].port) <= maxSlots)
+                throw new Error(`config: 服务 ${entries[i][0]} 与 ${entries[j][0]} 端口段重叠（间距需 > maxSlots=${maxSlots}）`);
+        }
     for (const [name, sp] of Object.entries(services))
         if (sp.upstream && !services[sp.upstream.service])
             throw new Error(`config: ${name}.upstream.service '${sp.upstream.service}' not found`); // V3
-    const known = new Set(['slot', 'blockBase', 'port', 'slug', 'worktree', 'repo', 'upstreamBase', 'cmd']); // V4
+    const known = new Set(['slot', 'port', 'slug', 'worktree', 'repo', 'upstreamBase', 'cmd']); // V4
     for (const sp of Object.values(services))
         for (const v of Object.values(sp.vars ?? {}))
             for (const ref of refs(v))
                 if (!known.has(ref) && !(sp.vars && ref in sp.vars))
                     throw new Error(`config: unknown template var {${ref}}`);
-    return { workspaceRoot: raw.workspaceRoot, portBase: raw.portBase, slotSpan: raw.slotSpan, maxSlots: raw.maxSlots, services, configDir: path.dirname(configPath) };
+    return { workspaceRoot: raw.workspaceRoot, maxSlots, services, configDir: path.dirname(configPath) };
 }
 export function loadConfig(startDir) {
     if (process.env.WORKTREE_BAY_CONFIG)

package/dist/engine.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { renderTemplate } from './config.js';
-import { blockBase, portOf, isPortFree } from './ports.js';
+import { portOf, isPortFree } from './ports.js';
 import { scanOccupancy } from './slots.js';
 import { addWorktree } from './git.js';
 import { runShell, run, spliceArgv, isTTY } from './util/exec.js';
@@ -23,13 +23,13 @@ export function mergeEnvText(text, kv) {
     return out.join('\n');
 }
 export function resolveUpstreamBase(cfg, slot, up, materialized) {
-    return materialized ? `http://localhost:${portOf(cfg.portBase, cfg.slotSpan, slot, cfg.services[up.service].offset)}` : up.fallback;
+    return materialized ? `http://localhost:${portOf(cfg.services[up.service].port, slot)}` : up.fallback;
 }
 function upstreamMaterialized(cfg, slot, service) {
     return (scanOccupancy(cfg).get(slot) ?? []).some((o) => o.service === service);
 }
 export function buildVars(cfg, ctx) {
-    const base = { slot: ctx.slot, blockBase: blockBase(cfg.portBase, cfg.slotSpan, ctx.slot), port: portOf(cfg.portBase, cfg.slotSpan, ctx.slot, ctx.sp.offset), slug: ctx.slug, worktree: ctx.dir, repo: ctx.repo };
+    const base = { slot: ctx.slot, port: portOf(ctx.sp.port, ctx.slot), slug: ctx.slug, worktree: ctx.dir, repo: ctx.repo };
     if (ctx.sp.upstream)
         base.upstreamBase = resolveUpstreamBase(cfg, ctx.slot, ctx.sp.upstream, upstreamMaterialized(cfg, ctx.slot, ctx.sp.upstream.service));
     for (const [k, v] of Object.entries(ctx.sp.vars ?? {}))

package/dist/mcp.js

@@ -9,30 +9,33 @@ const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.u
 const PROTOCOL_VERSION = '2024-11-05';
 export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开发编排器。当你需要在一个多服务工作区里并行开发多个功能、又不想让它们的端口/依赖/数据互相干扰时，用本服务的工具来完成开发工作。
 
-核心模型：一个功能占一个「槽位」→ 得到一个端口块；该功能用到哪些服务，就在哪些服务上各开一个 git worktree 挂进这个槽，端口自动错开，前端自动连到同槽的后端。
+核心模型：每个服务有自己的端口段（基址 = 主 dev/槽0）；一个功能占一个「槽位 N」，用到哪些服务就在哪些服务上各开一个 git worktree 挂进这个槽，该服务端口 = 基址 + N，自动错开，前端自动连到同槽的后端。
 
 推荐工作流：
 1. 起新功能：调用 worktree_bay_up，传功能名 + 要改的服务列表（如 ["api","lms"]）。它会自动占槽、为每个服务开 worktree、拷依赖、注入端口并起服务。
-2. 查看在跑的功能：worktree_bay_ls。
+2. 定位代码：用 worktree_bay_path 拿某功能某服务的 worktree 绝对路径，进去改代码；或 worktree_bay_ls（JSON，含各 worktree 路径）总览全局。
 3. 在某功能的某服务里跑测试/命令：worktree_bay_run（name 用配置里定义的，如 "test"）。
 4. 收尾：分支合并后，先 worktree_bay_gc 看可回收项，再 worktree_bay_down 拆掉该功能。
 
 要点：
-- 同一个功能从头到尾用同一个功能名（它同时是默认分支名）贯穿 up/run/down。
+- 同一个功能从头到尾用同一个功能名（它同时是默认分支名）贯穿 up/path/run/down。
 - 只起这个功能「实际要改」的服务，不要全起。
 - 拿不准当前状态时先调 worktree_bay_ls。
 - worktree_bay_gc 默认只读（dry-run 列出建议），apply=true 才真删，且只删「已合并到主分支且工作区干净」的，安全保守、不会误删未完成的工作。
 - 要写或修改 worktree-bay.config.json、或拿不准任何命令/参数/配置细节时，先调用 worktree_bay_skill 获取完整的使用与配置指南（含每个配置原语、模板变量、校验规则与完整示例）。`;
 const str = { type: 'string' };
 export const TOOLS = [
-    { name: 'worktree_bay_ls', description: '列出所有功能槽位与占用（功能名、端口块、已起服务及端口、是否已并入主分支）',
-        inputSchema: { type: 'object', properties: {} }, toArgs: () => ['ls'] },
+    { name: 'worktree_bay_ls', description: '列出所有功能槽位与占用（JSON：每槽的功能名、已起服务及端口、各 worktree 绝对路径），用于总览当前并行开发状态',
+        inputSchema: { type: 'object', properties: {} }, toArgs: () => ['ls', '--json'] },
     { name: 'worktree_bay_up', description: '为一个功能一次性起多个服务（自动占槽 + 各服务开 worktree，分支默认=功能名，前端自动接同槽后端）。并行开发新功能首选。',
         inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature', 'services'] },
         toArgs: (a) => ['up', String(a.feature), ...(a.services ?? [])] },
     { name: 'worktree_bay_add', description: '为功能在单个服务上开 worktree（branch 省略则用功能名）',
         inputSchema: { type: 'object', properties: { feature: str, service: str, branch: str }, required: ['feature', 'service'] },
         toArgs: (a) => ['add', String(a.feature), String(a.service), ...(a.branch ? [String(a.branch)] : [])] },
+    { name: 'worktree_bay_path', description: '打印某功能某服务的 worktree 绝对路径——up 之后用它定位代码目录，再进去改文件',
+        inputSchema: { type: 'object', properties: { feature: str, service: str }, required: ['feature', 'service'] },
+        toArgs: (a) => ['path', String(a.feature), String(a.service)] },
     { name: 'worktree_bay_run', description: '在某功能某服务的运行体里跑预设命令（如 test），可透传额外参数',
         inputSchema: { type: 'object', properties: { feature: str, service: str, name: str, args: { type: 'array', items: str } }, required: ['feature', 'service', 'name'] },
         toArgs: (a) => ['run', String(a.feature), String(a.service), String(a.name), ...(a.args ?? [])] },

package/dist/ports.js

@@ -1,6 +1,6 @@
 import net from 'node:net';
-export function blockBase(portBase, slotSpan, slot) { return portBase + slot * slotSpan; }
-export function portOf(portBase, slotSpan, slot, offset) { return blockBase(portBase, slotSpan, slot) + offset; }
+// 按服务分段：某服务在某槽的端口 = 服务基址(主 dev/槽0) + 槽号
+export function portOf(servicePort, slot) { return servicePort + slot; }
 export function isPortFree(port) {
     return new Promise((resolve) => {
         const srv = net.createServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "1.5.1",
+  "version": "2.1.0",
   "description": "Per-feature git worktree + port slots for parallel multi-service development: auto deps, env wiring, frontend-to-backend, merge-aware reclaim, plus an MCP server for AI agents.",
   "keywords": [
     "git",

package/skill.md

@@ -4,8 +4,8 @@
 
 ## 核心模型：功能 = 槽位
 
-- 一个**功能**认领一个**槽位 `N`**（1..maxSlots）→ 得到一个**端口块** `portBase + N*slotSpan`。
-- 功能用到哪些**服务**，就在哪些服务各开一个 **git worktree** 挂进这个槽；块内每个服务按自己的 `offset` 取一个端口，互不相撞。
+- 每个**服务**有自己的**端口段**：基址 `port` 就是它的主 dev 端口（= 槽 0），段为 `[port, port+maxSlots]`。
+- 一个**功能**认领一个**槽位 `N`**（1..maxSlots）；功能用到哪些**服务**，就在那些服务各开一个 **git worktree** 挂进这个槽，该服务在本槽的端口 = `service.port + N`，与主 dev（槽 0）和其它槽天然错开、互不相撞。
 - 同槽的前端服务自动把 api base 指向同槽的后端端口。
 - 槽位占用从文件系统派生（看 `<repo>/.worktrees/s<N>-*` 是否存在），删了 worktree 槽自动空出。
 
@@ -27,9 +27,9 @@ worktree-bay completion install   # 一键装 shell 补全（可选）
 | `worktree-bay init` | 在当前工作区生成 `worktree-bay.config.json`（扫描子 git 仓预填服务） |
 | `worktree-bay doctor` | 体检：git 是否可用、配置是否有效、各服务仓是否就绪 |
 | `worktree-bay up <feature> <service...>` | **最常用**：一条命令为功能起多个服务（自动占槽 + 各服务开 worktree，分支默认 = 功能名） |
-| `worktree-bay claim <feature>` | 只占一个槽、打印端口块（不开 worktree） |
+| `worktree-bay claim <feature>` | 只占一个槽、打印各服务在该槽的端口（不开 worktree） |
 | `worktree-bay add <feature> <service> [branch] [base]` | 为功能在单个服务开 worktree。`branch` 省略 = 功能名；`base` 省略 = `origin/<主分支>` |
-| `worktree-bay ls [--json]` | 列出所有槽位：功能名、端口块、已起服务及端口、是否已并入主分支；`--json` 输出结构化数据（含 worktree 路径） |
+| `worktree-bay ls [--json]` | 列出所有槽位：功能名、已起服务及端口；`--json` 输出结构化数据（含 worktree 绝对路径，便于脚本/AI 消费）。合并状态由 `gc` 判定，`ls` 不查（避免每次都 `git fetch`） |
 | `worktree-bay path <feature> <service>` | 打印某服务 worktree 的绝对路径（可 `cd $(worktree-bay path f api)`） |
 | `worktree-bay run <feature> <service> <name> [args...]` | 在某服务运行体里跑配置的 `run.<name>`（如 test），透传 args |
 | `worktree-bay sh <feature> <service>` | 进入某服务运行体的 shell |
@@ -63,19 +63,17 @@ worktree-bay gc                        # 回收已合并的
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `workspaceRoot` | string | 工作区根绝对路径，各服务仓在其下 |
-| `portBase` | number | 端口基址，如 `6000` |
-| `slotSpan` | number | 每个槽位的端口跨度（块大小），如 `10` |
-| `maxSlots` | number | 最大并行功能数，如 `9` |
+| `maxSlots` | number | 最大并行功能数（每个服务预留 `maxSlots` 个端口），如 `9` |
 | `services` | object | 服务名 → 服务定义（见下） |
 
-**端口计算**：`块基址 = portBase + 槽位N * slotSpan`；`某服务端口 = 块基址 + 该服务 offset`。
-例：portBase=6000, slotSpan=10，槽 1 的块基址 = 6010，offset=1 的服务端口 = 6011。
+**端口模型（按服务分段）**：每个服务有自己的端口段，基址 `port` 就是它的主 dev 端口（= 槽 0）；某服务在某槽 N 的端口 = `service.port + N`（槽 1..maxSlots）。
+例：`api.port=6001` → 槽 1 用 6002、槽 2 用 6003…；`lms.port=6011` → 槽 1 用 6012…。**服务数量无上限**，只要各服务端口段（`[port, port+maxSlots]`）互不重叠即可。
 
 ### 服务定义原语
 
 | 原语 | 必填 | 类型 | 说明 |
 |---|---|---|---|
-| `offset` | ✅ | number | 本服务在块内的偏移；`1 ≤ offset < slotSpan`，各服务互不相同 |
+| `port` | ✅ | number | 本服务端口段基址（= 主 dev/槽0 端口）；各服务的段 `[port, port+maxSlots]` 互不重叠 |
 | `repo` | | string | 仓库目录名（相对 workspaceRoot），**默认 = 服务名** |
 | `vars` | | object | 自定义模板变量，值里可引用基础变量，如 `{ "project": "myapi-{slug}" }` |
 | `copy` | | string[] | 挂入时从主 checkout **递归拷贝**到 worktree 的文件/目录（含依赖目录，如 `vendor`）。含符号链接也安全（会跟随拷目标内容） |
@@ -94,8 +92,7 @@ worktree-bay gc                        # 回收已合并的
 | 变量 | 含义 |
 |---|---|
 | `{slot}` | 槽位号 |
-| `{blockBase}` | 块基址 `portBase + slot*slotSpan` |
-| `{port}` | 本服务端口 `blockBase + offset` |
+| `{port}` | 本服务端口 `service.port + slot` |
 | `{slug}` | worktree 目录名 `s<slot>-<分支归一化>` |
 | `{worktree}` | worktree 绝对路径 |
 | `{repo}` | 服务仓绝对路径 |
@@ -105,8 +102,8 @@ worktree-bay gc                        # 回收已合并的
 
 ### 加载时强制校验
 
-1. 各服务 `offset` 互不相同；
-2. `1 ≤ offset < slotSpan`；
+1. 各服务端口段 `[port, port+maxSlots]` 互不重叠（任意两服务 `|portA - portB| > maxSlots`）；
+2. `port` 必填且为正数；
 3. `upstream.service` 必须存在于 `services`；
 4. 所有模板里引用的 `{var}` 可解析（基础变量或本服务 vars 已声明）；
 5. `repo` 指向的目录存在。
@@ -117,12 +114,10 @@ worktree-bay gc                        # 回收已合并的
 ```jsonc
 {
   "workspaceRoot": "/path/to/workspace",
-  "portBase": 6000,
-  "slotSpan": 10,
   "maxSlots": 9,
   "services": {
     "api": {
-      "offset": 1,
+      "port": 6001,
       "vars": { "project": "myapi-{slug}" },
       "copy": [".env", "vendor"],
       "env": { ".env": { "APP_PORT": "{port}", "CACHE_PREFIX": "dev:{slug}:" } },
@@ -132,7 +127,7 @@ worktree-bay gc                        # 回收已合并的
       "run": { "test": ["composer", "run", "test"], "migrate": ["php", "artisan", "migrate"] }
     },
     "web": {
-      "offset": 2,
+      "port": 6011,
       "upstream": { "service": "api", "fallback": "http://localhost:6001" },
       "env": { ".env.local": { "VITE_API_BASE_URL": "{upstreamBase}" } },
       "setup": "pnpm install",
@@ -157,7 +152,7 @@ worktree-bay gc                        # 回收已合并的
 
 ## 给 AI（MCP）
 
-`worktree-bay mcp` 暴露工具：`worktree_bay_up / ls / add / run / down / gc / skill`。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
+`worktree-bay mcp` 暴露工具：`worktree_bay_up / ls / add / path / run / down / gc / skill`。`ls` 以 JSON 返回（含各 worktree 绝对路径），`path` 直接给某功能某服务的 worktree 目录——拿到路径后即可进去改代码。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
 
 ## 常见坑