worktree-bay 2.0.0 → 2.1.0

package/README.md

@@ -5,7 +5,7 @@
 
 > 配置驱动、与语言/技术栈无关的 **git worktree 槽位 + 端口编排器**——为多服务并行开发而生。
 
-一个功能来了，先**占一个槽位**，用到哪个服务就在哪个服务开一个 worktree 挂进这个槽。同一槽里的所有服务共享一套**端口块**、各自独立进程，前端自动接上同槽的后端。工具替你管好 worktree 路径、端口分配、依赖、`.env` 注入与回收。
+一个功能来了，先**占一个槽位 `N`**，用到哪个服务就在哪个服务开一个 worktree 挂进这个槽。每个服务有自己的**端口段**，同槽的各服务都取段里的第 `N` 个端口（`服务基址 + N`）、各自独立进程，前端自动接上同槽的后端。工具替你管好 worktree 路径、端口分配、依赖、`.env` 注入与回收。
 
 ## 为什么
 
@@ -126,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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "2.0.0",
+  "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 |
@@ -152,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` 取本指南全文。
 
 ## 常见坑