worktree-bay 2.4.0 → 3.0.0

package/README.md

@@ -45,7 +45,9 @@ worktree-bay down drill-fix
 worktree-bay gc
 ```
 
-> 需要更细的控制：`claim <feature>` 单独占槽、`add <feature> <service> [branch]` 单加一个服务（branch 可自定义，省略则用功能名）、`rm <feature> [service]` 拆单个服务。
+> 运行体随起随停（不动 worktree/代码）：`worktree-bay stop drill-fix` 停掉（docker 容器 + dev server 一起）、`start` 起回来、`restart` 重启。
+>
+> 更细的控制：`claim <feature>` 单独占槽、`add <feature> <service> [branch]` 单加一个服务（branch 可自定义，省略则用功能名）、`rm <feature> [service]` 拆单个服务。
 
 ## 配置
 
@@ -61,8 +63,9 @@ worktree-bay gc
       "vars": { "project": "myapi-{slug}" },
       "copy": [".env", "vendor"],                                  // 从主 checkout 递归拷文件/目录
       "env": { ".env": { "APP_PORT": "{port}" } },                 // 合并键值进 dotenv（保留其它键）
-      "setup": "docker compose -p {project} up -d",                // 挂入时执行
-      "teardown": "docker compose -p {project} down -v",           // 拆除时执行
+      "setup": "docker compose -p {project} up -d",                // up 时执行（建运行体）
+      "stop": "docker compose -p {project} stop",                  // stop/restart 时执行（停而不毁）
+      "teardown": "docker compose -p {project} down -v",           // down 时执行（销毁）
       "exec": ["docker", "exec", "-i", "{project}-app-1", "{cmd...}"], // 透传模板（argv）
       "run": { "test": ["composer", "run", "test"] }               // 命名命令
     },
@@ -71,7 +74,7 @@ worktree-bay gc
       "upstream": { "service": "api", "fallback": "http://localhost:6001" }, // → {upstreamBase}
       "env": { ".env.dev.local": { "VITE_API_BASE_URL": "{upstreamBase}" } },
       "setup": "pnpm install",
-      "start": "pnpm dev --port {port}"                            // 长进程：只打印命令，交你自起
+      "start": "pnpm dev --port {port}"                            // 长进程 dev server：up 时自动后台启动
     }
   }
 }
@@ -87,8 +90,9 @@ worktree-bay gc
 | `copy` | 从主 checkout 递归拷贝的文件/目录（含依赖目录） |
 | `env` | 按文件合并 dotenv 键值，文件不存在则建 |
 | `upstream` | 声明依赖的上游服务，产出 `{upstreamBase}` |
-| `setup` / `teardown` | 挂入 / 拆除时执行的 shell 命令 |
-| `start` | 长进程命令，只打印不阻塞 |
+| `setup` / `teardown` | 建立 / 销毁运行体的 shell（`up` 时 setup、`down` 时 teardown） |
+| `start` | 长进程 dev server（如 `pnpm dev`），`up` 时自动**后台启动**、日志落 `.worktree-bay/logs/`，由 `start`/`stop`/`restart` 控制 |
+| `stop` | 停止 infra 运行体的 shell（如 `docker compose stop`），供 `stop`/`restart` 用（让 docker 停而不毁） |
 | `exec` | 透传命令模板（argv 数组，`{cmd...}` splice） |
 | `run` | 命名命令（argv 数组），供 `worktree-bay run <feature> <service> <name>` |
 
@@ -116,9 +120,9 @@ worktree-bay completion install
 
 ## MCP（让 AI 直接用）
 
-内置一个 MCP 服务，让 AI（Claude Code 等）通过 MCP 调用 worktree-bay 完成并行开发，并内置工作流指导（告诉 AI 何时用 up/ls/run/down/gc）。
+内置一个 MCP 服务，让 AI（Claude Code 等）通过 MCP 调用 worktree-bay 完成并行开发，并内置工作流指导（三层模型 + 何时用 doctor/up/path/run/start-stop-restart/down/gc）。
 
-启动：`worktree-bay mcp`（stdio）。在 Claude Code 里注册：
+启动：`worktree-bay mcp`（stdio）。在 Claude Code 里注册（项目级 `.mcp.json` 或全局，跨平台、无需写死路径）：
 
 ```json
 {
@@ -128,7 +132,7 @@ worktree-bay completion install
 }
 ```
 
-> 服务在哪个工作区目录启动，就用哪个目录的 `worktree-bay.config.json`（或设 `WORKTREE_BAY_CONFIG`）。暴露的工具：`worktree_bay_doctor / ls / up / claim / add / path / run / down / gc / init / skill`（`doctor` 列出全部服务名，`ls` 以 JSON 返回各 worktree 路径，`path` 直接给某功能某服务的目录，`down` 可只拆单个服务，`skill` 取完整指南）。
+> 服务在哪个工作区目录启动，就用哪个目录的 `worktree-bay.config.json`（cwd 自动向上查找，**无需写死路径**；也可设 `WORKTREE_BAY_CONFIG`）。暴露的工具：`worktree_bay_doctor / ls / up / claim / add / path / run / start / stop / restart / down / gc / init / skill`（`doctor` 列出全部服务名，`ls` JSON 返回各 worktree 路径与 `▸run`，`path` 给某功能某服务目录，`start/stop/restart` 控制运行体，`down` 可只拆单个服务，`skill` 取完整指南）。MCP 调用时自动以非交互模式运行（输出不含颜色/进度控制符）。
 
 ## 许可证
 

package/dist/cli.js

@@ -73,8 +73,10 @@ catch (e) {
     die(e.message);
 } });
 program.command('add <feature> <service> [branch] [base]').description(t('为功能在某服务开 worktree（branch 默认 = 功能名）', 'open a worktree for a feature on one service (branch defaults to feature name)'))
-    .action(async (f, s, b, base) => { try {
-    await addCommand(loadConfig(process.cwd()), f, s, b, base);
+    .option('--branch <branch>', t('要创建的分支名（默认 = 功能名）', 'branch to create (default = feature name)'))
+    .option('--base <base>', t('分支基点（默认 = origin/<主分支>）', 'base ref for the branch (default = origin/<main>)'))
+    .action(async (f, s, b, base, o) => { try {
+    await addCommand(loadConfig(process.cwd()), f, s, o.branch ?? b, o.base ?? base);
 }
 catch (e) {
     die(e.message);
@@ -83,35 +85,35 @@ program.command('run <feature> <service> <name> [args...]').description(t('在
     .action((f, s, n, args) => sync((c) => runCommand(c, f, s, n, args ?? [])));
 program.command('sh <feature> <service>').description(t('进入服务运行体的 shell', 'open a shell inside the service runtime'))
     .action((f, s) => sync((c) => shCommand(c, f, s)));
-program.command('start <feature> [service]').description(t('启动该功能的 dev server（worktree 已在，只起 start 进程，不动 worktree）', 'start the feature\'s dev server(s) (worktree already exists; runs the start process only)'))
+program.command('start <feature> [services...]').description(t('启动功能的运行体（docker 容器 + dev server）；省略 service = 全部，可列多个。不动 worktree', 'start the feature\'s runtime (docker + dev server); omit services = all, or list several. Leaves the worktree untouched'))
     .action(async (f, s) => { try {
-    await startCommand(loadConfig(process.cwd()), f, s);
+    await startCommand(loadConfig(process.cwd()), f, s ?? []);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('stop <feature> [service]').description(t('停止该功能的 dev server（保留 worktree）', 'stop the feature\'s dev server(s) (keeps the worktree)'))
+program.command('stop <feature> [services...]').description(t('停止功能的运行体（停 docker + 杀 dev server）；省略 = 全部，可列多个。保留 worktree', 'stop the feature\'s runtime (stop docker + kill dev server); omit = all, or list several. Keeps the worktree'))
     .action(async (f, s) => { try {
-    await stopCommand(loadConfig(process.cwd()), f, s);
+    await stopCommand(loadConfig(process.cwd()), f, s ?? []);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('restart <feature> [service]').description(t('重启该功能的 dev server（停掉再起）', 'restart the feature\'s dev server(s) (stop then start)'))
+program.command('restart <feature> [services...]').description(t('重启功能的运行体（停掉再起）；省略 = 全部，可列多个', 'restart the feature\'s runtime (stop then start); omit = all, or list several'))
     .action(async (f, s) => { try {
-    await restartCommand(loadConfig(process.cwd()), f, s);
+    await restartCommand(loadConfig(process.cwd()), f, s ?? []);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('down <feature>').description(t('拆除整个功能的所有服务 worktree（= rm <feature>）', 'tear down all of a feature\'s service worktrees (= rm <feature>)')).option('-f, --force', t('跳过脏/未推检查强制删除', 'skip dirty/unpushed checks and force-remove'))
+program.command('down <feature>').description(t('拆除整个功能（所有服务的 worktree）', 'tear down the whole feature (all its service worktrees)')).option('-f, --force', t('跳过脏/未推检查强制删除', 'skip dirty/unpushed checks and force-remove'))
     .action(async (f, o) => { try {
-    await rmCommand(loadConfig(process.cwd()), f, undefined, !!o.force);
+    await rmCommand(loadConfig(process.cwd()), f, [], !!o.force);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('rm <feature> [service]').description(t('拆除某服务或整槽的 worktree（默认查脏/未推保护）', 'remove one service\'s or the whole slot\'s worktree (dirty/unpushed protected by default)')).option('-f, --force', t('跳过脏/未推检查强制删除', 'skip dirty/unpushed checks and force-remove'))
+program.command('rm <feature> <services...>').description(t('拆除功能下指定的一个或多个服务的 worktree（拆整功能用 down）。默认查脏/未推保护', 'remove the worktree(s) of the given service(s) of a feature (use down for the whole feature). Dirty/unpushed protected by default')).option('-f, --force', t('跳过脏/未推检查强制删除', 'skip dirty/unpushed checks and force-remove'))
     .action(async (f, s, o) => { try {
     await rmCommand(loadConfig(process.cwd()), f, s, !!o.force);
 }

package/dist/commands/add.js

@@ -4,7 +4,7 @@ import { repoPath } from '../config.js';
 import { withLock } from '../lock.js';
 import { claim } from '../slots.js';
 import { slugify, worktreeDirName } from '../naming.js';
-import { buildVars, bringUp, ensureStarted } from '../engine.js';
+import { buildVars, bringUp, ensureStarted, ensureRuntime } from '../engine.js';
 import { mainBranch } from '../git.js';
 import { log } from '../util/log.js';
 import { color as c } from '../util/color.js';
@@ -23,9 +23,9 @@ export async function addCommand(cfg, feature, service, branch, base) {
         const sp = cfg.services[service];
         const ctxBase = { cfg, service, sp, slot: p.slot, slug: p.slug, dir: p.dir, repo: p.repo };
         const ctx = { ...ctxBase, vars: buildVars(cfg, ctxBase) };
-        if (fs.existsSync(p.dir)) { // 幂等重入：worktree 已在 → 不重建/不重跑 setup，但确保 dev server 在跑
+        if (fs.existsSync(p.dir)) { // 幂等重入：worktree 已在 → 不重建，但「恢复运行体」（docker 容器 + dev server 都拉回来）
             log(c.bold(c.cyan(service)) + c.dim(t(`  ·  已就绪 · 槽 ${p.slot} · 端口 ${ctx.vars.port}`, `  ·  ready · slot ${p.slot} · port ${ctx.vars.port}`)));
-            await ensureStarted(ctx);
+            await ensureRuntime(ctx);
             return;
         }
         log(c.bold(c.cyan(service)) + c.dim(t(`  ·  槽 ${p.slot} · 端口 ${ctx.vars.port} · 分支 ${br}`, `  ·  slot ${p.slot} · port ${ctx.vars.port} · branch ${br}`)));

package/dist/commands/completion.js

@@ -17,12 +17,12 @@ export function complete(cfg, words) {
     const featureSubs = ['up', 'add', 'rm', 'down', 'run', 'sh', 'path', 'start', 'stop', 'restart'];
     if (featureSubs.includes(sub) && pos === 1)
         return Object.values(readLabels(cfg));
-    if (['add', 'run', 'sh', 'path', 'start', 'stop', 'restart'].includes(sub) && pos === 2)
-        return Object.keys(cfg.services);
+    if (['add', 'run', 'sh', 'path'].includes(sub) && pos === 2)
+        return Object.keys(cfg.services); // 单服务
     if (sub === 'run' && pos === 3)
         return Object.keys(cfg.services[prev[2]]?.run ?? {}); // run <feature> <service> <name>：补该服务的 run 命令名
-    if (sub === 'up' && pos >= 2)
-        return Object.keys(cfg.services); // up 接变长服务列表
+    if (['up', 'start', 'stop', 'restart', 'rm'].includes(sub) && pos >= 2)
+        return Object.keys(cfg.services); // 变长服务列表
     return [];
 }
 export function completionScript(shell) {

package/dist/commands/lifecycle.js

@@ -1,65 +1,73 @@
 import { repoPath } from '../config.js';
 import { withLock } from '../lock.js';
 import { scanOccupancy, slotOfFeature } from '../slots.js';
-import { buildVars, ensureStarted } from '../engine.js';
-import { stopManaged } from '../proc.js';
+import { buildVars, ensureRuntime, stopRuntime } from '../engine.js';
 import { portInUse } from '../ports.js';
-import { log, warn } from '../util/log.js';
+import { log } from '../util/log.js';
 import { color as c } from '../util/color.js';
 import { t } from '../i18n.js';
-// dev server 生命周期：start/stop/restart（只管 start 配置起的进程，不动 worktree）
-function occupantsOf(cfg, feature, service) {
+// dev server + infra 生命周期：stop/start/restart 同时管 node（managed 进程）与 docker（stop 钩子 + setup 恢复），不动 worktree。
+// services 为空 = 整功能；否则只这些服务
+function occupantsOf(cfg, feature, services = []) {
     const slot = slotOfFeature(cfg, feature);
     if (slot === undefined)
         throw new Error(t(`功能「${feature}」未占槽。先 \`worktree-bay up ${feature} <服务...>\` 起它。`, `feature "${feature}" hasn't claimed a slot. Run \`worktree-bay up ${feature} <services...>\` first.`));
     const all = scanOccupancy(cfg).get(slot) ?? [];
-    return service ? all.filter((o) => o.service === service) : all;
+    if (!services.length)
+        return all;
+    for (const s of services)
+        if (!all.some((o) => o.service === s))
+            throw new Error(t(`服务「${s}」不在功能「${feature}」里。用 \`worktree-bay ls\` 看已起的服务。`, `service "${s}" is not in feature "${feature}". See \`worktree-bay ls\`.`));
+    return all.filter((o) => services.includes(o.service));
 }
 function ctxOf(cfg, o) {
-    const sp = cfg.services[o.service];
-    const base = { cfg, service: o.service, sp, slot: o.slot, slug: o.slug, dir: o.dir, repo: repoPath(cfg, o.service) };
+    const base = { cfg, service: o.service, sp: cfg.services[o.service], slot: o.slot, slug: o.slug, dir: o.dir, repo: repoPath(cfg, o.service) };
     return { ...base, vars: buildVars(cfg, base) };
 }
-export async function startCommand(cfg, feature, service) {
+// 该服务是否有「可停起的运行体」：managed dev server(start) 或可停的 infra(stop 钩子)
+const hasRuntime = (cfg, service) => { const sp = cfg.services[service]; return !!(sp.start || sp.stop); };
+export async function stopCommand(cfg, feature, services = []) {
     await withLock(cfg.workspaceRoot, async () => {
         let any = false;
-        for (const o of occupantsOf(cfg, feature, service)) {
-            if (!cfg.services[o.service].start)
+        for (const o of occupantsOf(cfg, feature, services)) {
+            if (!hasRuntime(cfg, o.service))
                 continue;
             any = true;
             log(c.bold(c.cyan(o.service)));
-            await ensureStarted(ctxOf(cfg, o));
+            await stopRuntime(ctxOf(cfg, o));
         }
         if (!any)
-            warn(t('没有可启动的 dev server（相关服务未配置 start）', 'nothing to start (those services have no start configured)'));
+            log(t('没有可停止的运行体（相关服务未配置 start/stop）', 'nothing to stop (no start/stop configured for those services)'));
     });
 }
-export async function stopCommand(cfg, feature, service) {
+export async function startCommand(cfg, feature, services = []) {
     await withLock(cfg.workspaceRoot, async () => {
         let any = false;
-        for (const o of occupantsOf(cfg, feature, service)) {
-            const stopped = stopManaged(cfg.workspaceRoot, o.dir);
-            if (stopped) {
-                any = true;
-                log(`${c.green('✓')} ` + t(`已停止 ${o.service} dev server（pid ${stopped.pid}）`, `stopped ${o.service} dev server (pid ${stopped.pid})`));
-            }
+        for (const o of occupantsOf(cfg, feature, services)) {
+            if (!hasRuntime(cfg, o.service))
+                continue;
+            any = true;
+            log(c.bold(c.cyan(o.service)));
+            await ensureRuntime(ctxOf(cfg, o));
         }
         if (!any)
-            log(t('没有在跑的 dev server', 'no running dev server'));
+            log(t('没有可启动的运行体（相关服务未配置 start/stop）', 'nothing to start (no start/stop configured for those services)'));
     });
 }
-export async function restartCommand(cfg, feature, service) {
+export async function restartCommand(cfg, feature, services = []) {
     await withLock(cfg.workspaceRoot, async () => {
-        for (const o of occupantsOf(cfg, feature, service)) {
-            const sp = cfg.services[o.service];
-            if (!sp.start)
+        for (const o of occupantsOf(cfg, feature, services)) {
+            if (!hasRuntime(cfg, o.service))
                 continue;
+            const ctx = ctxOf(cfg, o);
             log(c.bold(c.cyan(o.service)) + c.dim(t('  ·  重启…', '  ·  restarting…')));
-            stopManaged(cfg.workspaceRoot, o.dir);
-            const port = Number(ctxOf(cfg, o).vars.port);
-            for (let i = 0; i < 40 && (await portInUse(port)); i++)
-                await new Promise((r) => setTimeout(r, 100)); // 等端口释放（最多 ~4s）
-            await ensureStarted(ctxOf(cfg, o));
+            await stopRuntime(ctx);
+            if (cfg.services[o.service].start) {
+                const port = Number(ctx.vars.port);
+                for (let i = 0; i < 40 && (await portInUse(port)); i++)
+                    await new Promise((r) => setTimeout(r, 100));
+            } // 等端口释放
+            await ensureRuntime(ctx);
         }
     });
 }

package/dist/commands/rm.js

@@ -9,17 +9,24 @@ import { stopManaged } from '../proc.js';
 import { log, warn } from '../util/log.js';
 import { color as c } from '../util/color.js';
 import { t } from '../i18n.js';
-export function resolveRm(cfg, feature, service) {
+// services 为空 = 整功能；否则只这些服务（顺带校验服务名确实在该功能里）
+export function resolveRm(cfg, feature, services = []) {
     const slot = slotOfFeature(cfg, feature);
     if (slot === undefined)
         throw new Error(t(`功能「${feature}」未占槽，无需拆除。用 \`worktree-bay ls\` 看在用的功能。`, `feature "${feature}" has no slot — nothing to tear down. See \`worktree-bay ls\`.`));
     const all = scanOccupancy(cfg).get(slot) ?? [];
-    return service ? all.filter((o) => o.service === service) : all;
+    if (!services.length)
+        return all;
+    for (const s of services)
+        if (!all.some((o) => o.service === s))
+            throw new Error(t(`服务「${s}」不在功能「${feature}」里。用 \`worktree-bay ls\` 看已起的服务。`, `service "${s}" is not in feature "${feature}". See \`worktree-bay ls\`.`));
+    return all.filter((o) => services.includes(o.service));
 }
-export async function rmCommand(cfg, feature, service, force) {
+export async function rmCommand(cfg, feature, services, force) {
     await withLock(cfg.workspaceRoot, async () => {
         let removed = 0;
-        const occs = resolveRm(cfg, feature, service);
+        const wholeFeature = services.length === 0;
+        const occs = resolveRm(cfg, feature, services);
         for (const o of occs) {
             const repo = repoPath(cfg, o.service);
             const branch = currentBranch(o.dir);
@@ -41,7 +48,7 @@ export async function rmCommand(cfg, feature, service, force) {
             removed++;
         }
         const slot = slotOfFeature(cfg, feature);
-        if (!service && (scanOccupancy(cfg).get(slot) ?? []).length === 0) {
+        if (wholeFeature && (scanOccupancy(cfg).get(slot) ?? []).length === 0) {
             removeLabel(cfg, slot);
             if (removed === 0)
                 log(`${c.green('✓')} ` + t(`释放空槽预约 "${feature}"（槽 ${slot}）`, `released empty slot reservation "${feature}" (slot ${slot})`));

package/dist/engine.js

@@ -8,7 +8,7 @@ import { runShellLive, run, spliceArgv, isTTY } from './util/exec.js';
 import { warn, log } from './util/log.js';
 import { withProgress } from './util/progress.js';
 import { color as cc } from './util/color.js';
-import { startDetached, recordedFor, pidAlive, setPid, pidOnPort, readLogTail } from './proc.js';
+import { startDetached, recordedFor, pidAlive, setPid, pidOnPort, readLogTail, stopManaged } from './proc.js';
 import { t } from './i18n.js';
 export function mergeEnvText(text, kv) {
     const lines = text.split('\n');
@@ -114,6 +114,27 @@ async function waitForListen(port, ms) {
         await new Promise((r) => setTimeout(r, 200));
     }
 }
+// 「运行体」= docker 容器(infra) + node dev server。up 重入 / start / restart 共用，统一边界。
+// 恢复运行体：有 stop 钩子的 infra 服务重跑 setup（docker compose up -d 幂等恢复）+ 起 managed dev server。
+export async function ensureRuntime(ctx) {
+    const { sp, dir, service, vars } = ctx;
+    if (sp.stop && sp.setup) {
+        const cmd = renderTemplate(sp.setup, vars);
+        await runShellLive(cmd, { cwd: dir }, t(`恢复 ${service}：${cmd}`, `resume ${service}: ${cmd}`));
+    }
+    await ensureStarted(ctx);
+}
+// 停止运行体：杀 managed dev server + 跑 stop 钩子（docker compose stop）。不动 worktree。
+export async function stopRuntime(ctx) {
+    const { cfg, sp, dir, service, vars } = ctx;
+    const stopped = stopManaged(cfg.workspaceRoot, dir);
+    if (stopped)
+        log(`  ${cc.green('✓')} ` + t(`已停止 dev server（pid ${stopped.pid}）`, `stopped dev server (pid ${stopped.pid})`));
+    if (sp.stop) {
+        const cmd = renderTemplate(sp.stop, vars);
+        await runShellLive(cmd, { cwd: dir }, t(`停 ${service}：${cmd}`, `stop ${service}: ${cmd}`));
+    }
+}
 export function execArgv(ctx, cmd) {
     const tpl = (ctx.sp.exec ?? ['sh', '-c', '{cmd...}']).map((el) => el === '{cmd...}' ? el : renderTemplate(el, ctx.vars));
     const spliced = spliceArgv(tpl, cmd);

package/dist/mcp.js

@@ -7,24 +7,30 @@ import path from 'node:path';
 const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), 'cli.js');
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const PROTOCOL_VERSION = '2024-11-05';
-export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开发编排器。当你需要在一个多服务工作区里并行开发多个功能、又不想让它们的端口/依赖/数据互相干扰时，用本服务的工具来完成开发工作。
+export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开发编排器。在一个多服务工作区里并行开发多个功能、又不想让它们的端口/依赖/数据互相干扰时，用本服务的工具完成开发。
 
-核心模型：每个服务有自己的端口段（基址 = 主 dev/槽0）；一个功能占一个「槽位 N」，用到哪些服务就在哪些服务上各开一个 git worktree 挂进这个槽，该服务端口 = 基址 + N，自动错开，前端自动连到同槽的后端。
+核心模型：每个服务有自己的端口段（基址 = 主 dev/槽0）；一个功能占一个「槽位 N」，用到哪些服务就在哪些服务上各开一个 git worktree 挂进这个槽，该服务端口 = 基址 + N，自动错开；前端自动连到同槽的后端。
+
+三层职责（决定每个工具的边界）：
+- worktree + 基础设施：worktree_bay_up/_add 建立（开 worktree、拷依赖、注入 .env、跑 setup 如 docker compose up），worktree_bay_down 销毁（teardown + 删 worktree）。
+- dev server（前端等长进程）：up 时按配置自动「后台」拉起；worktree_bay_start/_stop/_restart 单独控制它，不动 worktree。
+- 在运行体里执行命令：worktree_bay_run（如 test/migrate）。
 
 推荐工作流：
-0. 摸清工作区（首次或拿不准时）：worktree_bay_doctor 列出全部服务及其仓、校验 git/配置/各仓是否就绪——这也是你获知「有哪些服务名可传给 up/add」的途径。
-1. 起新功能：调用 worktree_bay_up，传功能名 + 要改的服务列表（如 ["api","lms"]）。它会自动占槽、为每个服务开 worktree、拷依赖、注入端口并起服务。
-2. 定位代码：用 worktree_bay_path 拿某功能某服务的 worktree 绝对路径，进去改代码；或 worktree_bay_ls（JSON，含各 worktree 路径）总览全局。
-3. 在某功能的某服务里跑测试/命令：worktree_bay_run（name 用配置里定义的，如 "test"）。
-4. 收尾：分支合并后，先 worktree_bay_gc 看可回收项，再 worktree_bay_down 拆掉该功能（只传 feature=拆整功能；带 service=只拆某个服务）。
+0. 摸清工作区（首次/拿不准时）：worktree_bay_doctor —— 列出全部服务及其仓、校验就绪；这也是获知「有哪些服务名可传给 up」的途径。
+1. 起新功能：worktree_bay_up，传功能名 + 要改的服务列表（如 ["api","lms"]）。自动占槽、开 worktree、拷依赖、注入端口、跑 setup，并把配了 start 的服务（如前端 dev server）后台拉起（日志在 .worktree-bay/logs/）。
+2. 定位代码：worktree_bay_path 拿某功能某服务的 worktree 绝对路径进去改；或 worktree_bay_ls（JSON，含各 worktree 路径，▸run 标记 dev server 是否在跑）总览。
+3. 跑命令/测试：worktree_bay_run（name 用配置里定义的，如 "test"）。
+4. 控制 dev server（按需）：worktree_bay_restart 重启 / _stop 停 / _start 起——只影响 dev server，worktree 与代码不受影响。
+5. 收尾：分支合并后先 worktree_bay_gc 看可回收项，再 worktree_bay_down 拆掉该功能（省略 service=整功能；带 service=只拆该服务）。
 
 要点：
-- 同一个功能从头到尾用同一个功能名（它同时是默认分支名）贯穿 up/path/run/down。
-- 只起这个功能「实际要改」的服务，不要全起。不知道有哪些服务名时先调 worktree_bay_doctor。
-- 拿不准当前状态时先调 worktree_bay_ls。
-- worktree_bay_gc 默认只读（dry-run 列出建议），apply=true 才真删，且只删「已合并到主分支且工作区干净」的，安全保守、不会误删未完成的工作。
-- worktree_bay_init 可在新工作区生成配置骨架（已存在则不覆盖）；worktree_bay_claim 只占槽并打印各服务端口、不建 worktree（一般直接用 up 即可）。
-- 要写或修改 worktree-bay.config.json、或拿不准任何命令/参数/配置细节时，先调用 worktree_bay_skill 获取完整的使用与配置指南（含每个配置原语、模板变量、校验规则与完整示例）。`;
+- 一个功能从头到尾用同一个功能名（= 默认分支名）。
+- 只起「实际要改」的服务，不要全起；不知道有哪些服务名先调 worktree_bay_doctor。
+- 拿不准当前状态先调 worktree_bay_ls。
+- worktree_bay_gc 默认只读（dry-run 列建议），apply=true 才真删，且只删「已合并到主分支且工作区干净」的，保守不误删。
+- worktree_bay_init 在新工作区生成配置骨架（已存在则不覆盖）；worktree_bay_claim 只占槽并打印端口、不建 worktree（一般直接用 up 即可）。
+- 要写/改 worktree-bay.config.json、或拿不准任何命令/参数/配置细节，先调 worktree_bay_skill 取完整指南（每个配置原语、模板变量、校验规则、完整示例）。`;
 const str = { type: 'string' };
 export const TOOLS = [
     { name: 'worktree_bay_doctor', description: '体检并列出工作区全部服务及其仓目录、校验 git/配置/各仓是否就绪。起步前先调它，也是获知「有哪些服务名可传给 up/add」的途径。',
@@ -46,9 +52,18 @@ export const TOOLS = [
     { 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 ?? [])] },
-    { name: 'worktree_bay_down', description: '拆除功能的 worktree：省略 service 拆整个功能的所有服务，传 service 只拆该服务（默认查脏/未推保护，force=true 强删）',
-        inputSchema: { type: 'object', properties: { feature: str, service: str, force: { type: 'boolean' } }, required: ['feature'] },
-        toArgs: (a) => ['rm', String(a.feature), ...(a.service ? [String(a.service)] : []), ...(a.force ? ['-f'] : [])] },
+    { name: 'worktree_bay_start', description: '启动功能的运行体（docker 容器 + node dev server 一起），不动 worktree。services 省略=该功能所有服务，也可列多个。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature'] },
+        toArgs: (a) => ['start', String(a.feature), ...(a.services ?? [])] },
+    { name: 'worktree_bay_stop', description: '停止功能的运行体（停 docker 容器 + 杀 node dev server），保留 worktree。services 省略=全部，也可列多个。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature'] },
+        toArgs: (a) => ['stop', String(a.feature), ...(a.services ?? [])] },
+    { name: 'worktree_bay_restart', description: '重启功能的运行体（停掉再起，docker + node 一起）。改了配置或端口卡住时用。services 省略=全部，也可列多个。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature'] },
+        toArgs: (a) => ['restart', String(a.feature), ...(a.services ?? [])] },
+    { name: 'worktree_bay_down', description: '拆除 worktree：省略 services 拆整个功能（所有服务），给 services 只拆这些服务（默认查脏/未推保护，force=true 强删）',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str }, force: { type: 'boolean' } }, required: ['feature'] },
+        toArgs: (a) => { const s = a.services ?? []; const force = a.force ? ['-f'] : []; return s.length ? ['rm', String(a.feature), ...s, ...force] : ['down', String(a.feature), ...force]; } },
     { name: 'worktree_bay_gc', description: '合并感知回收：默认 dry-run 只列建议，apply=true 才实际删除「已合并且干净」的功能',
         inputSchema: { type: 'object', properties: { apply: { type: 'boolean' } } },
         toArgs: (a) => ['gc', ...(a.apply ? ['--apply'] : [])] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "2.4.0",
+  "version": "3.0.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

@@ -35,11 +35,11 @@ worktree-bay completion install   # 一键装 shell 补全（可选）
 | `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 |
-| `worktree-bay start <feature> [service]` | 启动该功能的 dev server（worktree 已在，只起 `start` 进程，不动 worktree） |
-| `worktree-bay stop <feature> [service]` | 停止该功能的 dev server（保留 worktree） |
-| `worktree-bay restart <feature> [service]` | 重启 dev server（停掉再起；改了配置/端口卡住时用） |
-| `worktree-bay down <feature> [-f]` | 拆除整个功能的所有服务 worktree（= `rm <feature>`） |
-| `worktree-bay rm <feature> [service] [-f]` | 拆除某服务或整槽。默认查脏/未推保护，`-f` 强删 |
+| `worktree-bay start <feature> [services...]` | 启动功能的运行体（docker 容器 + node dev server 一起）；**省略 = 全部**，也可列多个。不动 worktree |
+| `worktree-bay stop <feature> [services...]` | 停止功能的运行体（停 docker + 杀 node dev server）；省略 = 全部，可列多个。保留 worktree |
+| `worktree-bay restart <feature> [services...]` | 重启运行体（停掉再起）；省略 = 全部，可列多个 |
+| `worktree-bay down <feature> [-f]` | 拆除**整个功能**（所有服务的 worktree）。`up` 的反操作 |
+| `worktree-bay rm <feature> <services...> [-f]` | 拆除指定的**一个或多个服务**（拆整功能用 `down`）。`add` 的反操作。默认查脏/未推保护，`-f` 强删 |
 | `worktree-bay gc [--apply]` | 合并感知回收：默认 dry-run 只列建议，`--apply` 才删「已合并且干净」的 |
 | `worktree-bay completion <install\|bash\|zsh\|fish>` | `install` 一键装进 shell；或打印补全脚本 |
 | `worktree-bay mcp` | 启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 |
@@ -84,9 +84,10 @@ worktree-bay gc                        # 回收已合并的
 | `copy` | | string[] | 挂入时从主 checkout **递归拷贝**到 worktree 的文件/目录（含依赖目录，如 `vendor`）。含符号链接也安全（会跟随拷目标内容） |
 | `env` | | object | dotenv 注入：`{ "文件名": { "KEY": "值模板" } }`，把键值**合并**进该文件（保留其它行，文件不存在则建） |
 | `upstream` | | object | 声明依赖的上游服务：`{ "service": "api", "fallback": "http://localhost:6001" }`，产出 `{upstreamBase}` 变量 |
-| `setup` | | string | 挂入后执行的 shell 命令（继承 stdio，会真跑） |
-| `teardown` | | string | 拆除时执行的 shell 命令（可只依赖 `{project}`，在 repo 根跑，不绑 worktree） |
-| `start` | | string | 长进程命令（如 `pnpm dev`）。**只打印命令、不阻塞**，交你自己起 |
+| `setup` | | string | 挂入后执行的 shell 命令（创建/装好运行体，如 `docker compose up -d`、`pnpm install`）。`up` 时跑 |
+| `teardown` | | string | 拆除时执行的 shell 命令（销毁运行体，如 `docker compose down -v`）。`down`/`rm`/`gc` 时跑 |
+| `start` | | string | 长进程 dev server（如 `pnpm dev`）。`up` 时**自动后台启动**（detach + 日志落 `.worktree-bay/logs/`），按端口追踪 pid；由 `start`/`stop`/`restart` 控制，`ls` 标 `▸run` |
+| `stop` | | string | 停止该服务 infra 运行体的 shell（如 `docker compose stop`）。供 `stop`/`restart` 用——让 docker 容器能「停而不毁」；`start` 时对配了它的服务重跑 `setup` 幂等恢复 |
 | `exec` | | string[] | 透传命令模板（argv 数组），`{cmd...}` 是 argv splice 占位，防 shell 注入。如 `["docker","exec","-i","{project}-app-1","{cmd...}"]` |
 | `run` | | object | 命名命令：`{ "test": ["composer","run","test"] }`，供 `worktree-bay run <feature> <service> test` 调用 |
 
@@ -127,6 +128,7 @@ worktree-bay gc                        # 回收已合并的
       "copy": [".env", "vendor"],
       "env": { ".env": { "APP_PORT": "{port}", "CACHE_PREFIX": "dev:{slug}:" } },
       "setup": "docker compose -p {project} up -d",
+      "stop": "docker compose -p {project} stop",
       "teardown": "docker compose -p {project} down -v",
       "exec": ["docker", "exec", "-i", "{project}-app-1", "{cmd...}"],
       "run": { "test": ["composer", "run", "test"], "migrate": ["php", "artisan", "migrate"] }
@@ -146,9 +148,22 @@ worktree-bay gc                        # 回收已合并的
 
 ---
 
+## 命令边界（三层）
+
+| 层 | 是什么 | 建立 | 控制运行 | 销毁 |
+|---|---|---|---|---|
+| ① worktree + 基础设施 | git worktree + `copy`/`env` + `setup` 起的东西 | `up` / `add` | — | `down` / `rm` / `gc`（`teardown`） |
+| ② 运行体(runtime) | docker 容器(infra) + node dev server(`start`) | `up` 顺带起 | **`start` / `stop` / `restart`**（docker+node 一起，不动 worktree） | `down`（一并停） |
+| ③ 在运行体里执行 | 跑命令 / 开 shell | — | `run` / `sh` | — |
+
+- `up`：建 worktree+infra（首次）并起运行体；**重入 = 恢复运行体**（docker 挂了重跑 `up` 能拉回来，等价 `start`）。
+- `start`/`stop`/`restart`：只管②运行体，省略 service = 整功能、带 service = 单个；不碰 worktree 与代码。
+- `down`(=`rm <feature>`) ↔ `up`（功能级）；`rm <feature> <service>` ↔ `add`（单服务级）。
+
 ## 工作原理要点
 
 - **占用真相 = 文件系统**：扫各服务 `.worktrees/s<N>-*`；`.worktree-bay-slots.json` 只是「功能名→槽号」标签账本（预约）。
+- **dev server 托管**：`start` 进程后台 detach 启动、日志落 `.worktree-bay/logs/`、按端口追踪真实 pid；`ls` 标 `▸run`；`stop`/`down` 按端口可靠停。
 - **并发安全**：`claim/add/up/rm/down/gc` 全程持工作区原子锁。
 - **前端自接后端**：前端有 `upstream` 且同槽该上游服务的 worktree 已建，则 `{upstreamBase}` = 本槽上游端口；否则用 `fallback`。所以**联调时先 `up`/`add` 后端，再起前端**。
 - **合并感知回收**：`gc` 先 `git fetch`，用 `merge-base --is-ancestor` 判断是否并入主分支；**只在「已合并 + 工作区干净 + 无未推」时才自动删**，判不准一律保守不删、只标记。
@@ -157,7 +172,7 @@ worktree-bay gc                        # 回收已合并的
 
 ## 给 AI（MCP）
 
-`worktree-bay mcp` 暴露工具：`worktree_bay_doctor / ls / up / claim / add / path / run / down / gc / init / skill`。`doctor` 列出全部服务（AI 借此得知有哪些服务名可用）；`ls` 以 JSON 返回（含各 worktree 绝对路径）；`path` 直接给某功能某服务的 worktree 目录；`down` 省略 service 拆整功能、带 service 只拆该服务。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
+`worktree-bay mcp` 暴露工具：`worktree_bay_doctor / ls / up / claim / add / path / run / start / stop / restart / down / gc / init / skill`。`doctor` 列出全部服务（AI 借此得知服务名）；`ls` 以 JSON 返回（含各 worktree 绝对路径、`▸run`）；`path` 给某功能某服务的 worktree 目录；`start/stop/restart` 控制运行体（docker+node）；`down` 省略 service 拆整功能、带 service 只拆该服务。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
 
 ## 常见坑