worktree-bay 4.0.4 → 4.2.0

package/README.md

@@ -30,7 +30,8 @@ npm i -g worktree-bay
 
 ```bash
 # 一条命令起整个功能：自动占槽 + 在 api/lms 上开 worktree（分支默认 = 功能名）
-worktree-bay up drill-fix api lms
+# -d 记录这个槽的用途，写进槽账本，ls 会显示、重入时参考（up/add/claim 都支持）
+worktree-bay up drill-fix api lms -d "修演练页 bug"
 
 # 看占用
 worktree-bay ls
@@ -48,6 +49,8 @@ worktree-bay gc
 > 运行体随起随停（不动 worktree/代码）：`worktree-bay stop drill-fix` 停掉（docker 容器 + dev server 一起）、`start` 起回来、`restart` 重启。
 >
 > 更细的控制：`claim <feature>` 单独占槽、`add <feature> <service> [branch]` 单加一个服务（branch 可自定义，省略则用功能名）、`down <feature> <service>` 只拆某个服务（省略服务则拆整功能）。
+>
+> dev server 起不来或报错？`worktree-bay logs <feature>`（`--tail N` 调行数、`--prev` 看上一轮）直接看日志尾部排障——日志每次启动滚动，当前文件只含本轮。
 
 ## 配置
 
@@ -132,7 +135,7 @@ worktree-bay completion install
 }
 ```
 
-> 服务在哪个工作区目录启动，就用哪个目录的 `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 调用时自动以非交互模式运行（输出不含颜色/进度控制符）。
+> 服务在哪个工作区目录启动，就用哪个目录的 `worktree-bay.config.json`（cwd 自动向上查找，**无需写死路径**；也可设 `WORKTREE_BAY_CONFIG`）。暴露的工具：`worktree_bay_doctor / ls / up / claim / add / path / run / start / stop / restart / down / logs / gc / init / skill`（`doctor` 列出全部服务名，`ls` JSON 返回各 worktree 路径与 `▸run`，`path` 给某功能某服务目录，`start/stop/restart` 控制运行体，`down` 可只拆单个服务，`logs` 看 dev server 日志排障，`skill` 取完整指南）。MCP 调用时自动以非交互模式运行（输出不含颜色/进度控制符）。
 
 ## 许可证
 

package/dist/cli.js

@@ -8,6 +8,7 @@ import { addCommand, upCommand } from './commands/add.js';
 import { runCommand, shCommand, pathCommand } from './commands/passthrough.js';
 import { rmCommand } from './commands/rm.js';
 import { startCommand, stopCommand, restartCommand } from './commands/lifecycle.js';
+import { logsCommand } from './commands/logs.js';
 import { gcCommand } from './commands/gc.js';
 import { doctorCommand } from './commands/doctor.js';
 import { complete, completionCommand, installCompletion } from './commands/completion.js';
@@ -52,9 +53,10 @@ program.command('init').description(t('在当前工作区生成 worktree-bay.con
 catch (e) {
     die(e.message);
 } });
-program.command('claim <feature>').description(t('为功能占一个槽位（打印各服务在该槽的端口）', 'claim a slot for a feature (prints each service\'s port in that slot)'))
-    .action(async (f) => { try {
-    await claimCommand(loadConfig(process.cwd()), f);
+program.command('claim <feature> [description]').description(t('为功能占一个槽位（打印各服务在该槽的端口）；可选 description 记录这个槽是干嘛的，供重入参考', 'claim a slot for a feature (prints each service\'s port in that slot); optional description records what this slot is for, as a re-entry hint'))
+    .option('-d, --description <text>', t('这个槽的介绍/用途（也可用位置参数传）', 'what this slot is for (can also be passed as the positional arg)'))
+    .action(async (f, desc, o) => { try {
+    await claimCommand(loadConfig(process.cwd()), f, o.description ?? desc);
 }
 catch (e) {
     die(e.message);
@@ -66,8 +68,9 @@ program.command('path <feature> <service>').description(t('打印某功能某服
 program.command('doctor').description(t('体检：git/配置/各服务仓是否就绪', 'health check: git / config / each service repo readiness'))
     .action(() => sync(doctorCommand));
 program.command('up <feature> <services...>').description(t('一条命令为功能起多个服务（自动 claim + 各服务默认分支 = 功能名）', 'bring up multiple services for a feature (auto-claim + branch defaults to feature name)'))
-    .action(async (f, services) => { try {
-    await upCommand(loadConfig(process.cwd()), f, services);
+    .option('-d, --description <text>', t('这个槽的介绍/用途，写进槽账本供重入参考', 'what this slot is for; recorded in the slot ledger as a re-entry hint'))
+    .action(async (f, services, o) => { try {
+    await upCommand(loadConfig(process.cwd()), f, services, undefined, o.description);
 }
 catch (e) {
     die(e.message);
@@ -75,8 +78,9 @@ catch (e) {
 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)'))
     .option('--branch <branch>', t('要创建的分支名（默认 = 功能名）', 'branch to create (default = feature name)'))
     .option('--base <base>', t('分支基点（默认 = origin/<主分支>）', 'base ref for the branch (default = origin/<main>)'))
+    .option('-d, --description <text>', t('这个槽的介绍/用途，写进槽账本供重入参考', 'what this slot is for; recorded in the slot ledger as a re-entry hint'))
     .action(async (f, s, b, base, o) => { try {
-    await addCommand(loadConfig(process.cwd()), f, s, o.branch ?? b, o.base ?? base);
+    await addCommand(loadConfig(process.cwd()), f, s, o.branch ?? b, o.base ?? base, o.description);
 }
 catch (e) {
     die(e.message);
@@ -113,6 +117,10 @@ program.command('down <feature> [services...]').description(t('拆除功能的 w
 catch (e) {
     die(e.message);
 } });
+program.command('logs <feature> [services...]').description(t('看功能各服务 dev server 日志尾部（排障 dev server 起不来/报错）；省略 services = 全部', 'tail each service\'s dev server log (debug dev servers that won\'t start / error out); omit services = all'))
+    .option('--tail <n>', t('显示末尾多少行（默认 40）', 'how many trailing lines (default 40)'))
+    .option('--prev', t('看上一轮启动的日志（.prev）', 'show the previous run\'s log (.prev)'))
+    .action((f, s, o) => sync((c) => logsCommand(c, f, s ?? [], { tail: o.tail ? Number(o.tail) : undefined, prev: !!o.prev })));
 program.command('gc').description(t('合并感知回收（默认 dry-run）', 'merge-aware reclaim (dry-run by default)')).option('--apply', t('实际执行回收', 'actually perform the reclaim'))
     .action(async (o) => { try {
     await gcCommand(loadConfig(process.cwd()), !!o.apply);

package/dist/commands/add.js

@@ -9,17 +9,17 @@ import { mainBranch } from '../git.js';
 import { log } from '../util/log.js';
 import { color as c } from '../util/color.js';
 import { t } from '../i18n.js';
-export function resolveAdd(cfg, feature, service, branch) {
+export function resolveAdd(cfg, feature, service, branch, description) {
     if (!cfg.services[service])
         throw new Error(t(`未知服务「${service}」。运行 \`worktree-bay doctor\` 查看配置里有哪些服务。`, `unknown service "${service}". Run \`worktree-bay doctor\` to see configured services.`));
-    const slot = claim(cfg, feature);
+    const slot = claim(cfg, feature, { branch, description });
     const slug = worktreeDirName(slot, slugify(branch));
     return { service, slot, slug, dir: path.join(repoPath(cfg, service), '.worktrees', slug), repo: repoPath(cfg, service) };
 }
-export async function addCommand(cfg, feature, service, branch, base) {
+export async function addCommand(cfg, feature, service, branch, base, description) {
     const br = branch || feature; // 默认分支 = 功能名
     await withLock(cfg.workspaceRoot, async () => {
-        const p = resolveAdd(cfg, feature, service, br);
+        const p = resolveAdd(cfg, feature, service, br, description);
         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) };
@@ -45,7 +45,7 @@ export async function addCommand(cfg, feature, service, branch, base) {
     });
 }
 // up: 一条命令为功能批量起多个服务（claim 自动 + 各服务默认分支）。每个服务由 addCommand 自己打印简洁标题。
-export async function upCommand(cfg, feature, services, base) {
+export async function upCommand(cfg, feature, services, base, description) {
     for (const service of services)
-        await addCommand(cfg, feature, service, undefined, base);
+        await addCommand(cfg, feature, service, undefined, base, description);
 }

package/dist/commands/claim.js

@@ -4,9 +4,11 @@ import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
 import { color as c } from '../util/color.js';
 import { t } from '../i18n.js';
-export async function claimCommand(cfg, feature) {
-    const slot = await withLock(cfg.workspaceRoot, async () => claim(cfg, feature));
+export async function claimCommand(cfg, feature, description) {
+    const slot = await withLock(cfg.workspaceRoot, async () => claim(cfg, feature, { description }));
     log(c.bold(c.cyan(t(`功能 "${feature}" → 槽 ${slot}`, `feature "${feature}" → slot ${slot}`))));
+    if (description)
+        log(c.dim('  ' + description));
     for (const [n, sp] of Object.entries(cfg.services))
         log(`  ${n.padEnd(8)} ${portOf(sp.port, slot)}`);
 }

package/dist/commands/logs.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { scanOccupancy, slotOfFeature } from '../slots.js';
+import { logPath, readLogTail } from '../proc.js';
+import { log } from '../util/log.js';
+import { color as c } from '../util/color.js';
+import { t } from '../i18n.js';
+// 看某功能各服务 dev server（配了 start 的）托管日志的尾部。排障 dev server 起不来/报错时用，
+// 省得自己拼 .worktree-bay/logs/<slug>-<service>.log 路径再读整个大文件。
+// 日志每次启动滚动（startDetached），当前文件只含本轮；--prev 看上一轮（.prev）。
+export function logsCommand(cfg, feature, services = [], opts = {}) {
+    for (const s of services)
+        if (!cfg.services[s])
+            throw new Error(t(`未知服务「${s}」。运行 \`worktree-bay doctor\` 查看配置里有哪些服务。`, `unknown service "${s}". Run \`worktree-bay doctor\` to see configured services.`));
+    const slot = slotOfFeature(cfg, feature);
+    if (slot === undefined) {
+        log(c.dim(t(`功能「${feature}」未占槽，没有可看的日志。`, `feature "${feature}" has no slot; no logs to show.`)));
+        return;
+    }
+    let occ = scanOccupancy(cfg).get(slot) ?? [];
+    if (services.length)
+        occ = occ.filter((o) => services.includes(o.service));
+    occ = occ.filter((o) => cfg.services[o.service].start); // 只有配了 start 的服务才有托管日志
+    if (!occ.length) {
+        log(c.dim(t('没有可看日志的运行体（这些服务未配置 start dev server）。', 'no logs available (those services have no start dev server configured).')));
+        return;
+    }
+    const tail = opts.tail ?? 40;
+    for (const o of occ) {
+        const file = logPath(cfg.workspaceRoot, o.slug, o.service) + (opts.prev ? '.prev' : '');
+        log(c.bold(c.cyan(o.service)) + c.dim('  ' + file));
+        if (!fs.existsSync(file)) {
+            log(c.dim(t(opts.prev ? '  （无上一轮日志）' : '  （暂无日志）', opts.prev ? '  (no previous-run log)' : '  (no log yet)')));
+            log('');
+            continue;
+        }
+        const body = readLogTail(file, tail);
+        log(body || c.dim(t('  （日志为空）', '  (log is empty)')));
+        log('');
+    }
+}

package/dist/commands/ls.js

@@ -1,4 +1,4 @@
-import { scanOccupancy, readLabels } from '../slots.js';
+import { scanOccupancy, readSlots } from '../slots.js';
 import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
 import { pidOnPort } from '../proc.js';
@@ -9,22 +9,38 @@ import { t } from '../i18n.js';
 function running(port) { return !!pidOnPort(port); }
 export function renderSlots(cfg) {
     const occ = scanOccupancy(cfg);
-    const labels = readLabels(cfg);
-    const slots = new Set([...occ.keys(), ...Object.keys(labels).map(Number)]);
+    const metas = readSlots(cfg);
+    const slots = new Set([...occ.keys(), ...Object.keys(metas).map(Number)]);
     const lines = [];
     for (const n of [...slots].sort((a, b) => a - b)) {
+        const meta = metas[String(n)];
         const svc = (occ.get(n) ?? []).map((o) => { const p = portOf(cfg.services[o.service].port, n); const dot = running(p) ? c.green('●') : c.dim('●'); return `${dot}${o.service}@${p}`; });
-        lines.push(`${c.bold(c.cyan(String(n)))}${c.dim(':')} ${c.bold(labels[String(n)] ?? t('(未命名)', '(unnamed)'))}  [${svc.join(', ') || c.dim(t('无 worktree', 'no worktree'))}]`);
+        lines.push(`${c.bold(c.cyan(String(n)))}${c.dim(':')} ${c.bold(meta?.feature ?? t('(未命名)', '(unnamed)'))}  [${svc.join(', ') || c.dim(t('无 worktree', 'no worktree'))}]`);
+        if (meta) { // 副行：介绍 + 分支(异于功能名时) + 创建日期，给重入/总览更多上下文
+            const bits = [];
+            if (meta.description)
+                bits.push(meta.description);
+            if (meta.branch && meta.branch !== meta.feature)
+                bits.push(t(`分支 ${meta.branch}`, `branch ${meta.branch}`));
+            if (meta.createdAt)
+                bits.push(meta.createdAt.slice(0, 10));
+            if (bits.length)
+                lines.push('   ' + c.dim(bits.join(' · ')));
+        }
     }
     return lines.join('\n') || t('(无槽位在用)', '(no slots in use)');
 }
 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) => ({
-        slot: n, feature: labels[String(n)] ?? null,
-        services: (occ.get(n) ?? []).map((o) => { const p = portOf(cfg.services[o.service].port, n); return { service: o.service, port: p, dir: o.dir, running: running(p) }; }),
-    }));
+    const metas = readSlots(cfg);
+    const slots = new Set([...occ.keys(), ...Object.keys(metas).map(Number)]);
+    return [...slots].sort((a, b) => a - b).map((n) => {
+        const meta = metas[String(n)];
+        return {
+            slot: n, feature: meta?.feature ?? null, branch: meta?.branch ?? null,
+            description: meta?.description ?? null, createdAt: meta?.createdAt ?? null,
+            services: (occ.get(n) ?? []).map((o) => { const p = portOf(cfg.services[o.service].port, n); return { service: o.service, port: p, dir: o.dir, running: running(p) }; }),
+        };
+    });
 }
 export function lsCommand(cfg, json = false) { log(json ? JSON.stringify(slotsData(cfg), null, 2) : renderSlots(cfg)); }

package/dist/engine.js

@@ -26,6 +26,26 @@ export function mergeEnvText(text, kv) {
         }
     return out.join('\n');
 }
+// 把 env 规格渲染并合并进 worktree 的 dotenv 文件。幂等：合并后内容与现有文件一致就【跳过写入】，
+// 避免无谓刷新 mtime 触发 dev server 的 .env 文件 watcher（如 vite）抖动重启——重跑 up/add（值已正确）很常见，
+// 运行中的前端被反复重启会偶发解析失败。返回实际写入的文件名（便于观测/测试）。
+export function writeEnvFiles(dir, env, vars) {
+    const written = [];
+    for (const [file, kv] of Object.entries(env ?? {})) {
+        const fp = path.join(dir, file);
+        const exists = fs.existsSync(fp);
+        const cur = exists ? fs.readFileSync(fp, 'utf8') : '';
+        const rendered = {};
+        for (const [k, v] of Object.entries(kv))
+            rendered[k] = renderTemplate(v, vars);
+        const next = mergeEnvText(cur, rendered);
+        if (!exists || next !== cur) {
+            fs.writeFileSync(fp, next);
+            written.push(file);
+        }
+    }
+    return written;
+}
 export function resolveUpstreamBase(cfg, slot, up, materialized) {
     return materialized ? `http://localhost:${portOf(cfg.services[up.service].port, slot)}` : up.fallback;
 }
@@ -55,14 +75,7 @@ export async function bringUp(ctx, base, branch) {
                 warn(t(`⚠ ${lock} 与主 checkout 不一致，拷来的依赖可能版本错位；建议把该服务的 copy 去掉、改用 setup 跑安装命令。`, `⚠ ${lock} differs from the main checkout; copied dependencies may be the wrong version. Consider dropping copy for this service and installing via setup instead.`));
         }
     }
-    for (const [file, kv] of Object.entries(sp.env ?? {})) {
-        const fp = path.join(dir, file);
-        const cur = fs.existsSync(fp) ? fs.readFileSync(fp, 'utf8') : '';
-        const rendered = {};
-        for (const [k, v] of Object.entries(kv))
-            rendered[k] = renderTemplate(v, vars);
-        fs.writeFileSync(fp, mergeEnvText(cur, rendered));
-    }
+    writeEnvFiles(dir, sp.env, vars);
     if (sp.setup) {
         const cmd = renderTemplate(sp.setup, vars);
         const r = await runShellLive(cmd, { cwd: dir }, t(`setup：${cmd}`, `setup: ${cmd}`));

package/dist/mcp.js

@@ -26,8 +26,9 @@ export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开
 
 要点：
 - 一个功能从头到尾用同一个功能名（= 默认分支名）。
+- 每个新任务都用一个【新的功能名】调 worktree_bay_up，让工具自动占一个空槽——【不要】去 worktree_bay_ls 挑一个现成的槽来复用。ls 是给你看占用情况的，不是用来选槽复用的；复用别的功能已占的槽会破坏隔离、互相污染。唯一例外：你是在【继续同一个功能】之前没跑完的工作（功能名相同），这时 up 会幂等复用它自己的槽。起 up / claim 时【带上 description】写明这个槽是干嘛的（记进槽账本、ls 会显示、ls --json 含 description/branch/createdAt），方便你之后重入时判断某个槽在做什么。
 - 只起「实际要改」的服务，不要全起；不知道有哪些服务名先调 worktree_bay_doctor。
-- 拿不准当前状态先调 worktree_bay_ls。
+- 拿不准当前状态先调 worktree_bay_ls；dev server 起不来或报错就调 worktree_bay_logs 看日志尾部排障。
 - worktree_bay_gc 默认只读（dry-run 列建议），apply=true 才真删，且只删「已合并到主分支且工作区干净」的，保守不误删。
 - worktree_bay_init 在新工作区生成配置骨架（已存在则不覆盖）；worktree_bay_claim 只占槽并打印端口、不建 worktree（一般直接用 up 即可）。
 - 要写/改 worktree-bay.config.json、或拿不准任何命令/参数/配置细节，先调 worktree_bay_skill 取完整指南（每个配置原语、模板变量、校验规则、完整示例）。`;
@@ -37,15 +38,15 @@ export const TOOLS = [
         inputSchema: { type: 'object', properties: {} }, toArgs: () => ['doctor'] },
     { 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_claim', description: '只为功能占一个槽位并打印各服务在该槽的端口，不开 worktree（一般直接用 up 即可；需要先预览端口/预约槽时用）',
-        inputSchema: { type: 'object', properties: { feature: str }, required: ['feature'] },
-        toArgs: (a) => ['claim', String(a.feature)] },
-    { 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_up', description: '为一个功能一次性起多个服务（自动占槽 + 各服务开 worktree，分支默认=功能名，前端自动接同槽后端）。并行开发新功能首选。【强烈建议带 description】写明这个槽是干嘛的，记进槽账本、`ls` 会显示，供之后重入参考。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str }, description: str }, required: ['feature', 'services'] },
+        toArgs: (a) => ['up', String(a.feature), ...(a.services ?? []), ...(a.description ? ['--description', String(a.description)] : [])] },
+    { name: 'worktree_bay_claim', description: '只为功能占一个槽位并打印各服务在该槽的端口，不开 worktree（一般直接用 up 即可；需要先预览端口/预约槽时用）。description 记录这个槽的用途供重入参考。',
+        inputSchema: { type: 'object', properties: { feature: str, description: str }, required: ['feature'] },
+        toArgs: (a) => ['claim', String(a.feature), ...(a.description ? ['--description', String(a.description)] : [])] },
+    { name: 'worktree_bay_add', description: '为功能在单个服务上开 worktree（branch 省略则用功能名）。description 记录这个槽的用途供重入参考。',
+        inputSchema: { type: 'object', properties: { feature: str, service: str, branch: str, description: str }, required: ['feature', 'service'] },
+        toArgs: (a) => ['add', String(a.feature), String(a.service), ...(a.branch ? [String(a.branch)] : []), ...(a.description ? ['--description', String(a.description)] : [])] },
     { 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)] },
@@ -64,6 +65,9 @@ export const TOOLS = [
     { 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) => ['down', String(a.feature), ...(a.services ?? []), ...(a.force ? ['-f'] : [])] },
+    { name: 'worktree_bay_logs', description: '看功能各服务 dev server 的日志尾部——dev server 起不来/报错时排障用，免得自己拼日志路径。services 省略=全部；tail 指定行数（默认 40）；prev=true 看上一轮启动的日志（每次启动会滚动）。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str }, tail: { type: 'number' }, prev: { type: 'boolean' } }, required: ['feature'] },
+        toArgs: (a) => ['logs', String(a.feature), ...(a.services ?? []), ...(a.tail ? ['--tail', String(a.tail)] : []), ...(a.prev ? ['--prev'] : [])] },
     { name: 'worktree_bay_gc', description: '合并感知回收：默认 dry-run 只列建议，apply=true 才实际删除「已合并且干净」的功能',
         inputSchema: { type: 'object', properties: { apply: { type: 'boolean' } } },
         toArgs: (a) => ['gc', ...(a.apply ? ['--apply'] : [])] },

package/dist/proc.js

@@ -34,6 +34,10 @@ export function readLogTail(file, lines = 15) {
         return '';
     }
 }
+// 某 worktree dev server 的日志路径（startDetached 写、logs 命令读，单一来源避免两处拼接漂移）。
+export function logPath(ws, slug, service) {
+    return path.join(ws, '.worktree-bay', 'logs', `${slug}-${service}.log`);
+}
 // 找出监听某端口的进程 pid（shell/pnpm 等中间层会让记录的 pid 漂移，按端口查最可靠）。
 export function pidOnPort(port) {
     if (process.platform === 'win32') {
@@ -126,7 +130,16 @@ export function stopUnrecordedOnPort(ws, dir, port) {
 export function startDetached(ws, dir, service, slug, port, cmd) {
     const logDir = path.join(ws, '.worktree-bay', 'logs');
     fs.mkdirSync(logDir, { recursive: true });
-    const log = path.join(logDir, `${slug}-${service}.log`);
+    const log = logPath(ws, slug, service);
+    // 每次启动滚动日志：上一轮留一份 .prev，当前日志只含本次运行，排障时不被跨会话的历史淹没。
+    // （fs.rename 跨平台覆盖已存在目标；失败也不阻断启动。）
+    try {
+        if (fs.existsSync(log) && fs.statSync(log).size > 0)
+            fs.renameSync(log, log + '.prev');
+    }
+    catch { /* 滚动失败忽略 */ }
+    // 启动头：标清「本次启动」的时间与命令，作为日志里这一轮运行的起点。
+    fs.writeFileSync(log, `===== worktree-bay start ${new Date().toISOString()} :: ${cmd} =====\n`);
     const fd = fs.openSync(log, 'a');
     // 后台启动、CLI 退出后仍存活、且不弹窗：
     // - Windows：不要 detached（detached 会新开控制台窗口、且与 windowsHide 冲突）；用 windowsHide 抑制窗口，

package/dist/slots.js

@@ -23,28 +23,66 @@ export function scanOccupancy(cfg) {
     return map;
 }
 function labelPath(cfg) { return path.join(cfg.workspaceRoot, '.worktree-bay-slots.json'); }
-export function readLabels(cfg) { const p = labelPath(cfg); return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : {}; }
-function save(cfg, l) { fs.writeFileSync(labelPath(cfg), JSON.stringify(l, null, 2) + '\n'); }
-export function writeLabel(cfg, slot, f) { const l = readLabels(cfg); l[String(slot)] = f; save(cfg, l); }
-export function removeLabel(cfg, slot) { const l = readLabels(cfg); delete l[String(slot)]; save(cfg, l); }
-export function slotOfFeature(cfg, f) { for (const [k, v] of Object.entries(readLabels(cfg)))
-    if (v === f)
+export function readSlots(cfg) {
+    const p = labelPath(cfg);
+    if (!fs.existsSync(p))
+        return {};
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const out = {};
+    for (const [k, v] of Object.entries(raw))
+        out[k] = typeof v === 'string' ? { feature: v } : v;
+    return out;
+}
+function save(cfg, store) { fs.writeFileSync(labelPath(cfg), JSON.stringify(store, null, 2) + '\n'); }
+// 兼容旧调用：slot → 功能名（completion/ls 等仍按字符串用）。
+export function readLabels(cfg) { const o = {}; for (const [k, v] of Object.entries(readSlots(cfg)))
+    o[k] = v.feature; return o; }
+export function removeLabel(cfg, slot) { const s = readSlots(cfg); delete s[String(slot)]; save(cfg, s); }
+export function slotOfFeature(cfg, f) { for (const [k, v] of Object.entries(readSlots(cfg)))
+    if (v.feature === f)
         return Number(k); return undefined; }
 export function freeSlot(cfg) {
     const occ = scanOccupancy(cfg);
-    const l = readLabels(cfg);
+    const s = readSlots(cfg);
     for (let n = 1; n <= cfg.maxSlots; n++)
-        if (!occ.has(n) && l[String(n)] === undefined)
+        if (!occ.has(n) && s[String(n)] === undefined)
             return n;
     throw new Error(t(`没有空闲槽位（1..${cfg.maxSlots} 全部占用）。用 \`worktree-bay gc\` 回收已合并的，或 \`worktree-bay down <功能>\` 拆掉用完的，或调大配置里的 maxSlots。`, `no free slot (1..${cfg.maxSlots} all taken). Reclaim merged ones with \`worktree-bay gc\`, tear down finished ones with \`worktree-bay down <feature>\`, or raise maxSlots in your config.`));
 }
-export function claim(cfg, f) { const e = slotOfFeature(cfg, f); if (e !== undefined)
-    return e; const n = freeSlot(cfg); writeLabel(cfg, n, f); return n; }
+// 占槽。首次认领写入 { feature, branch?, description?, createdAt }；已占同名功能则【补全/更新】非空的
+// branch / description（保留首次的 createdAt）——所以同一功能重入 up/claim 带上新 --description 即可改介绍。
+export function claim(cfg, f, meta = {}) {
+    const store = readSlots(cfg);
+    const existing = slotOfFeature(cfg, f);
+    if (existing !== undefined) {
+        const cur = store[String(existing)];
+        const next = { ...cur };
+        if (meta.branch)
+            next.branch = meta.branch;
+        if (meta.description)
+            next.description = meta.description;
+        if (JSON.stringify(next) !== JSON.stringify(cur)) {
+            store[String(existing)] = next;
+            save(cfg, store);
+        }
+        return existing;
+    }
+    const n = freeSlot(cfg);
+    const m = { feature: f };
+    if (meta.branch)
+        m.branch = meta.branch;
+    if (meta.description)
+        m.description = meta.description;
+    m.createdAt = new Date().toISOString();
+    store[String(n)] = m;
+    save(cfg, store);
+    return n;
+}
 export function pruneEmptyLabels(cfg) {
     const occ = scanOccupancy(cfg);
     const removed = [];
-    for (const [k, v] of Object.entries(readLabels(cfg)))
+    for (const [k, v] of Object.entries(readSlots(cfg)))
         if (!occ.has(Number(k)))
-            removed.push({ slot: Number(k), feature: v });
+            removed.push({ slot: Number(k), feature: v.feature });
     return removed;
 }

package/package.json

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

@@ -9,6 +9,8 @@
 - 同槽的前端服务自动把 api base 指向同槽的后端端口。
 - 槽位占用从文件系统派生（看 `<repo>/.worktrees/s<N>-*` 是否存在），删了 worktree 槽自动空出。
 
+> **每个新任务都用一个【新功能名】认领新槽**（`up <新功能名> ...`），让工具自动占一个空槽。**不要先 `ls` 再去挑一个现成的槽来复用**——`ls` 是给你看占用情况的，不是用来选槽复用的；复用别的功能已占的槽会破坏隔离、互相污染数据。唯一例外：你在**继续同一个功能**之前没跑完的工作（用同一功能名），此时 `up` 会幂等复用它自己的槽。起槽时给 `up`/`claim`/`add` 带 `-d/--description` 写明这个槽是干嘛的——记进槽账本、`ls` 会显示、`ls --json` 含 `description`/`branch`/`createdAt`，方便日后重入判断某个槽在做什么。
+
 ---
 
 ## 安装
@@ -28,9 +30,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 add <feature> <service> [branch] [base]` | 为功能在单个服务开 worktree。`branch` 省略 = 功能名；`base` 省略 = `origin/<主分支>` |
+| `worktree-bay up <feature> <service...>` | **最常用**：一条命令为功能起多个服务（自动占槽 + 各服务开 worktree，分支默认 = 功能名）。`-d/--description` 记录这个槽的用途（写进槽账本，`ls` 显示，重入参考） |
+| `worktree-bay claim <feature> [description]` | 只占一个槽、打印各服务在该槽的端口（不开 worktree）。可选 `description`（位置参数或 `-d`）记录槽用途 |
+| `worktree-bay add <feature> <service> [branch] [base]` | 为功能在单个服务开 worktree。`branch` 省略 = 功能名；`base` 省略 = `origin/<主分支>`；`-d/--description` 记录槽用途 |
 | `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 |
@@ -39,6 +41,7 @@ worktree-bay completion install   # 一键装 shell 补全（可选）
 | `worktree-bay stop <feature> [services...]` | 停止功能的运行体（停 docker + 杀 node dev server）；省略 = 全部，可列多个。保留 worktree |
 | `worktree-bay restart <feature> [services...]` | 重启运行体（停掉再起）；省略 = 全部，可列多个 |
 | `worktree-bay down <feature> [services...]` | 拆除 worktree（停运行体 + teardown + 删 worktree）；**省略 services = 整功能**，也可列多个只拆这些。默认查脏/未推保护，`-f` 强删 |
+| `worktree-bay logs <feature> [services...]` | 看各服务 dev server 日志尾部（排障 dev server 起不来/报错）；省略 services = 全部。`--tail N` 行数（默认 40）、`--prev` 看上一轮启动的日志 |
 | `worktree-bay gc [--apply]` | 合并感知回收：默认 dry-run 只列建议，`--apply` 才删「已合并且干净」的 |
 | `worktree-bay completion <install\|bash\|zsh\|fish>` | `install` 一键装进 shell；或打印补全脚本 |
 | `worktree-bay mcp` | 启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 |
@@ -81,7 +84,7 @@ worktree-bay gc                        # 回收已合并的
 | `repo` | | string | 仓库目录名（相对 workspaceRoot），**默认 = 服务名** |
 | `vars` | | object | 自定义模板变量，值里可引用基础变量，如 `{ "project": "myapi-{slug}" }` |
 | `copy` | | string[] | 挂入时从主 checkout **递归拷贝**到 worktree 的文件/目录（含依赖目录，如 `vendor`）。含符号链接也安全（会跟随拷目标内容） |
-| `env` | | object | dotenv 注入：`{ "文件名": { "KEY": "值模板" } }`，把键值**合并**进该文件（保留其它行，文件不存在则建） |
+| `env` | | object | dotenv 注入：`{ "文件名": { "KEY": "值模板" } }`，把键值**合并**进该文件（保留其它行，文件不存在则建）。**幂等**：合并结果与现有内容一致就跳过写入、不刷新 mtime——避免重跑 `up`/`add` 时无谓触发前端 `.env` watcher（如 vite）抖动重启 |
 | `upstream` | | object | 声明依赖的上游服务：`{ "service": "api", "fallback": "http://localhost:6001" }`，产出 `{upstreamBase}` 变量 |
 | `setup` | | string | 挂入后执行的 shell 命令（创建/装好运行体，如 `docker compose up -d`、`pnpm install`）。`up` 时跑 |
 | `teardown` | | string | 拆除时执行的 shell 命令（销毁运行体，如 `docker compose down -v`）。`down`/`rm`/`gc` 时跑 |
@@ -162,8 +165,8 @@ worktree-bay gc                        # 回收已合并的
 ## 工作原理要点
 
 - **全命令幂等**：`up / down / start / stop / restart` 重复执行都收敛到同一目标态、不报错——`up` 重入＝复用 worktree + 恢复运行体；`start`/`stop` 已在目标态则跳过/仍逐服务给状态；`down` 对未占槽或已拆的服务是友好 no-op。仅「未知服务名」（typo，不在 config）才报错。
-- **占用真相 = 文件系统**：扫各服务 `.worktrees/s<N>-*`；`.worktree-bay-slots.json` 只是「功能名→槽号」标签账本（预约）。
-- **dev server 托管**：`start` 进程后台 detach 启动、日志落 `.worktree-bay/logs/`、按端口追踪真实 pid；`ls` 行首 `●` 标在跑（绿）/未跑（灰）；`stop`/`down` 按端口可靠停。
+- **占用真相 = 文件系统**：扫各服务 `.worktrees/s<N>-*`；`.worktree-bay-slots.json` 是槽位元数据账本（每槽记 `feature` / `branch` / `description` / `createdAt`；旧的纯字符串值自动兼容为 `{feature}`），属预约标记，真正占用仍以 worktree 是否存在为准。
+- **dev server 托管**：`start` 进程后台 detach 启动、日志落 `.worktree-bay/logs/`、按端口追踪真实 pid。日志**每次启动滚动**（上一轮存一份 `.prev`，当前文件只含本轮 + 一行启动头，排障不被跨会话历史淹没；用 `worktree-bay logs <feature>` 直接看尾部，免拼路径）。`start` 会**阻塞到约定端口被监听才返回**（给 vite 冷启动留 ~25s），所以命令返回即代表就绪、`ls` 行首 `●` 绿即可开工；超时不算失败（可能仍在编译/重启），会提示去看日志。`stop`/`down` 按端口可靠停。
 - **运行状态判断 = 端口**：`ls`/`start`/`stop` 判「在不在跑」全用 `pidOnPort`（netstat/lsof，与 ls 同源），不用 connect 探测（docker 发布端口两者会不一致）、也不只看 pid 账本（dir 形态会漂移、docker 无账本记录）。`start` 端口已在监听就跳过、不再误报「恢复」。
 - **stop 严格停「本目录+本端口+本进程」**：① 优先用启动账本（dir 已规范化匹配：相对/绝对/大小写都认）；② 账本缺失时**校验后才杀**——Linux/macOS 比对进程 `cwd` 是否为本 worktree，Windows 取不到 cwd 则核对命令行含 `--port <本端口>`（端口按槽唯一，等价确证）；都确证不了就**不动它**并如实报告（绝不凭端口盲杀）。每个服务都有状态行：已停 / 端口空闲 / 无法确认未停。
 - **并发安全**：`claim/add/up/rm/down/gc` 全程持工作区原子锁。
@@ -174,7 +177,9 @@ worktree-bay gc                        # 回收已合并的
 
 ## 给 AI（MCP）
 
-`worktree-bay mcp` 暴露工具：`worktree_bay_doctor / ls / up / claim / add / path / run / start / stop / restart / down / gc / init / skill`。`doctor` 列出全部服务（AI 借此得知服务名）；`ls` 以 JSON 返回 `[{slot, feature(可 null), services:[{service, port, dir, running}]}]`（含各 worktree 绝对路径、布尔 `running`）；`path` 给某功能某服务的 worktree 目录；`start/stop/restart` 控制运行体（docker+node）；`down` 省略 services 拆整功能、给 services 只拆这些。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
+`worktree-bay mcp` 暴露工具：`worktree_bay_doctor / ls / up / claim / add / path / run / start / stop / restart / down / logs / gc / init / skill`。`doctor` 列出全部服务（AI 借此得知服务名）；`ls` 以 JSON 返回 `[{slot, feature(可 null), services:[{service, port, dir, running}]}]`（含各 worktree 绝对路径、布尔 `running`）；`path` 给某功能某服务的 worktree 目录；`start/stop/restart` 控制运行体（docker+node）；`down` 省略 services 拆整功能、给 services 只拆这些；`logs` 看 dev server 日志尾部排障。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
+
+**给 AI 的硬约束**：每个新任务用一个【新功能名】`up` 认领新槽，让工具自动占空槽；**不要用 `ls` 去挑现成的槽复用**（破坏隔离、污染数据）。只有继续同一功能未完成的工作才用同名 `up`（幂等复用自己的槽）。dev server 起不来/报错先 `logs` 看日志，别瞎猜。
 
 ## 常见坑