worktree-bay 2.1.1 → 2.2.0

package/README.md

@@ -24,6 +24,8 @@ npm i -g worktree-bay
 
 需要 Node ≥ 20。
 
+> 输出语言按系统区域自动切换中/英（识别不出时默认中文）。可用环境变量 `WORKTREE_BAY_LANG=zh|en` 强制指定。
+
 ## 快速上手
 
 ```bash
@@ -126,7 +128,7 @@ worktree-bay completion install
 }
 ```
 
-> 服务在哪个工作区目录启动，就用哪个目录的 `worktree-bay.config.json`（或设 `WORKTREE_BAY_CONFIG`）。暴露的工具：`worktree_bay_up / ls / add / path / run / down / gc / skill`（`ls` 以 JSON 返回各 worktree 路径，`path` 直接给某功能某服务的目录，`skill` 取完整指南）。
+> 服务在哪个工作区目录启动，就用哪个目录的 `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` 取完整指南）。
 
 ## 许可证
 

package/dist/cli.js

@@ -14,10 +14,12 @@ import { startMcp } from './mcp.js';
 import { readSkill } from './skill.js';
 import { initCommand } from './commands/init.js';
 import { die, log } from './util/log.js';
+import { t } from './i18n.js';
+import { friendlyParseError } from './util/clierr.js';
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const program = new Command();
-program.name('worktree-bay').description('worktree 槽位 + 端口编排器：多服务并行开发利器').version(pkg.version);
-program.addHelpText('after', `
+program.name('worktree-bay').description(t('worktree 槽位 + 端口编排器：多服务并行开发利器', 'Per-feature git worktree + port slot orchestrator for parallel multi-service development')).version(pkg.version);
+program.addHelpText('after', t(`
 示例:
   worktree-bay init                      在当前工作区生成配置（扫描子 git 仓预填服务）
   worktree-bay up drill-fix api lms      一条命令为功能起 api+lms（分支默认 = 功能名）
@@ -26,73 +28,82 @@ program.addHelpText('after', `
   worktree-bay down drill-fix            拆除整个功能
   worktree-bay gc                        回收已合并的功能（默认 dry-run）
 
-更多: worktree-bay skill（完整使用与配置指南） · worktree-bay help <命令>（单命令帮助）`);
+更多: worktree-bay skill（完整使用与配置指南） · worktree-bay help <命令>（单命令帮助）`, `
+Examples:
+  worktree-bay init                      scaffold config here (scans child git repos)
+  worktree-bay up drill-fix api lms      bring up api+lms for a feature (branch defaults to feature name)
+  worktree-bay ls                        list all features / port usage
+  worktree-bay run drill-fix api test    run run.test inside api
+  worktree-bay down drill-fix            tear down the whole feature
+  worktree-bay gc                        reclaim merged features (dry-run by default)
+
+More: worktree-bay skill (full usage & config guide) · worktree-bay help <command>`));
 const sync = (fn) => { try {
     fn(loadConfig(process.cwd()));
 }
 catch (e) {
     die(e.message);
 } };
-program.command('init').description('在当前工作区生成 worktree-bay.config.json（扫描子 git 仓预填服务）')
+program.command('init').description(t('在当前工作区生成 worktree-bay.config.json（扫描子 git 仓预填服务）', 'scaffold worktree-bay.config.json here (scans child git repos to prefill services)'))
     .action(() => { try {
     initCommand(process.cwd());
 }
 catch (e) {
     die(e.message);
 } });
-program.command('claim <feature>').description('为功能占一个槽位（打印各服务在该槽的端口）')
+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);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('ls').description('列出所有槽位与占用状态').option('--json', '以 JSON 输出（含 worktree 路径，便于脚本/AI 消费）')
+program.command('ls').description(t('列出所有槽位与占用状态', 'list all slots and their occupancy')).option('--json', t('以 JSON 输出（含 worktree 路径，便于脚本/AI 消费）', 'output JSON (includes worktree paths, for scripts/AI)'))
     .action((o) => sync((c) => lsCommand(c, !!o.json)));
-program.command('path <feature> <service>').description('打印某功能某服务的 worktree 绝对路径（可 cd $(...)）')
+program.command('path <feature> <service>').description(t('打印某功能某服务的 worktree 绝对路径（可 cd $(...)）', 'print the absolute worktree path for a feature\'s service (cd $(...))'))
     .action((f, s) => sync((c) => pathCommand(c, f, s)));
-program.command('doctor').description('体检：git/配置/各服务仓是否就绪')
+program.command('doctor').description(t('体检：git/配置/各服务仓是否就绪', 'health check: git / config / each service repo readiness'))
     .action(() => sync(doctorCommand));
-program.command('up <feature> <services...>').description('一条命令为功能起多个服务（自动 claim + 各服务默认分支 = 功能名）')
+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);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('add <feature> <service> [branch] [base]').description('为功能在某服务开 worktree（branch 默认 = 功能名）')
+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);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('run <feature> <service> <name> [args...]').description('在服务运行体里跑 run.<name> 命令（透传 args）')
+program.command('run <feature> <service> <name> [args...]').description(t('在服务运行体里跑 run.<name> 命令（透传 args）', 'run the configured run.<name> command inside a service (passes args through)'))
     .action((f, s, n, args) => sync((c) => runCommand(c, f, s, n, args ?? [])));
-program.command('sh <feature> <service>').description('进入服务运行体的 shell')
+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('down <feature>').description('拆除整个功能的所有服务 worktree（= rm <feature>）').option('-f, --force', '跳过脏/未推检查强制删除')
+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'))
     .action(async (f, o) => { try {
     await rmCommand(loadConfig(process.cwd()), f, undefined, !!o.force);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('rm <feature> [service]').description('拆除某服务或整槽的 worktree（默认查脏/未推保护）').option('-f, --force', '跳过脏/未推检查强制删除')
+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'))
     .action(async (f, s, o) => { try {
     await rmCommand(loadConfig(process.cwd()), f, s, !!o.force);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('gc').description('合并感知回收（默认 dry-run）').option('--apply', '实际执行回收')
+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);
 }
 catch (e) {
     die(e.message);
 } });
-program.command('completion <target> [shell]').description('install 一键装进 shell；或 bash|zsh|fish 打印补全脚本')
+program.command('completion <target> [shell]').description(t('install 一键装进 shell；或 bash|zsh|fish 打印补全脚本', 'install: set up shell completion; or bash|zsh|fish: print the completion script'))
     .action((target, shell) => { try {
     if (target === 'install')
         installCompletion(shell);
@@ -102,21 +113,21 @@ program.command('completion <target> [shell]').description('install 一键装进
 catch (e) {
     die(e.message);
 } });
-program.command('mcp').description('启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 worktree-bay')
+program.command('mcp').description(t('启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 worktree-bay', 'start the MCP server (stdio, lightweight, spawned on demand) for AI agents'))
     .action(() => { try {
     startMcp();
 }
 catch (e) {
     die(e.message);
 } });
-program.command('skill').description('打印 worktree-bay 使用与配置完全指南')
+program.command('skill').description(t('打印 worktree-bay 使用与配置完全指南', 'print the full worktree-bay usage & config guide'))
     .action(() => { try {
     log(readSkill());
 }
 catch (e) {
     die(e.message);
 } });
-program.command('version').description('显示版本号').action(() => log(pkg.version));
+program.command('version').description(t('显示版本号', 'show the version number')).action(() => log(pkg.version));
 program.command('__complete', { hidden: true }).allowUnknownOption().action(() => {
     const words = process.argv.slice(process.argv.indexOf('--') + 1);
     let cfg = null;
@@ -129,4 +140,13 @@ program.command('__complete', { hidden: true }).allowUnknownOption().action(() =
     }
     catch { /* 静默 */ }
 });
-program.parseAsync(process.argv);
+// 把 commander 的英文解析错误（missing required argument 等）重写为自然语言（中/英）+ 用法 + 建议。
+// 走 configureOutput.writeErr（会被子命令继承）而非 exitOverride+catch（子命令上不可靠）。
+program.showSuggestionAfterError(false);
+program.configureOutput({
+    writeErr: (str) => {
+        const sub = program.commands.find((c) => c.name() === process.argv[2]);
+        process.stderr.write('worktree-bay: ' + friendlyParseError(str, sub ? { name: sub.name(), usage: sub.usage(), description: sub.description() } : undefined) + '\n');
+    },
+});
+program.parseAsync(process.argv).catch((e) => die(e.message));

package/dist/commands/add.js

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import { repoPath } from '../config.js';
 import { withLock } from '../lock.js';
@@ -5,10 +6,11 @@ import { claim } from '../slots.js';
 import { slugify, worktreeDirName } from '../naming.js';
 import { buildVars, bringUp } from '../engine.js';
 import { mainBranch } from '../git.js';
-import { log } from '../util/log.js';
+import { log, warn } from '../util/log.js';
+import { t } from '../i18n.js';
 export function resolveAdd(cfg, feature, service, branch) {
     if (!cfg.services[service])
-        throw new Error('unknown service: ' + 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 slug = worktreeDirName(slot, slugify(branch));
     return { service, slot, slug, dir: path.join(repoPath(cfg, service), '.worktrees', slug), repo: repoPath(cfg, service) };
@@ -18,10 +20,23 @@ export async function addCommand(cfg, feature, service, branch, base) {
     await withLock(cfg.workspaceRoot, async () => {
         const p = resolveAdd(cfg, feature, service, br);
         const sp = cfg.services[service];
+        if (fs.existsSync(p.dir)) { // 幂等：该服务已在本功能下开过 worktree → 跳过（让 up 可安全重跑）
+            warn(t(`• ${service} 已在功能 "${feature}"（槽 ${p.slot}），跳过。要重建先 \`worktree-bay rm ${feature} ${service}\`。`, `• ${service} already in "${feature}" (slot ${p.slot}), skipping. To recreate: \`worktree-bay rm ${feature} ${service}\`.`));
+            return;
+        }
         const ctxBase = { cfg, service, sp, slot: p.slot, slug: p.slug, dir: p.dir, repo: p.repo };
         const ctx = { ...ctxBase, vars: buildVars(cfg, ctxBase) };
-        await bringUp(ctx, base ?? `origin/${mainBranch(p.repo)}`, br);
-        log(`✓ ${service} 挂入 "${feature}"（槽 ${p.slot}，端口 ${ctx.vars.port}，分支 ${br}）`);
+        const resolvedBase = base ?? `origin/${mainBranch(p.repo)}`;
+        try {
+            await bringUp(ctx, resolvedBase, br);
+        }
+        catch (e) {
+            const m = String(e.message);
+            if (/invalid reference|unknown revision|ambiguous argument|not a valid|Not a valid object name/i.test(m))
+                throw new Error(t(`基分支「${resolvedBase}」无效（该仓可能没有 origin 或对应主分支）。给 add 显式传 base，例如：worktree-bay add ${feature} ${service} ${br} HEAD`, `invalid base ref "${resolvedBase}" (this repo may have no origin or main branch). Pass an explicit base to add, e.g.: worktree-bay add ${feature} ${service} ${br} HEAD`));
+            throw e;
+        }
+        log(t(`✓ ${service} 挂入 "${feature}"（槽 ${p.slot}，端口 ${ctx.vars.port}，分支 ${br}）`, `✓ ${service} added to "${feature}" (slot ${p.slot}, port ${ctx.vars.port}, branch ${br})`));
     });
 }
 // up: 一条命令为功能批量起多个服务（claim 自动 + 各服务默认分支）

package/dist/commands/claim.js

@@ -2,9 +2,10 @@ import { withLock } from '../lock.js';
 import { claim } from '../slots.js';
 import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
+import { t } from '../i18n.js';
 export async function claimCommand(cfg, feature) {
     const slot = await withLock(cfg.workspaceRoot, async () => claim(cfg, feature));
-    log(`功能 "${feature}" → 槽 ${slot}`);
+    log(t(`功能 "${feature}" → 槽 ${slot}`, `feature "${feature}" → slot ${slot}`));
     for (const [n, sp] of Object.entries(cfg.services))
         log(`  ${n.padEnd(8)} ${portOf(sp.port, slot)}`);
 }

package/dist/commands/completion.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { readLabels } from '../slots.js';
 import { log } from '../util/log.js';
+import { t } from '../i18n.js';
 const SUBCMDS = ['init', 'doctor', 'claim', 'up', 'add', 'ls', 'path', 'gc', 'down', 'rm', 'run', 'sh', 'completion', 'mcp', 'skill', 'version', 'help'];
 // words = 命令名 + 光标前已输入完的词（不含当前正在补的词）
 export function complete(cfg, words) {
@@ -42,7 +43,7 @@ export function installCompletion(shell) {
         fs.mkdirSync(dir, { recursive: true });
         const file = path.join(dir, 'worktree-bay.fish');
         fs.writeFileSync(file, completionScript('fish') + '\n');
-        log(`✓ fish 补全已写入 ${file}（新开 fish 即生效）`);
+        log(t(`✓ fish 补全已写入 ${file}（新开 fish 即生效）`, `✓ fish completion written to ${file} (effective in a new fish session)`));
         return;
     }
     const isZsh = sh === 'zsh';
@@ -50,9 +51,9 @@ export function installCompletion(shell) {
     const line = `eval "$(worktree-bay completion ${isZsh ? 'zsh' : 'bash'})"`;
     const cur = fs.existsSync(rc) ? fs.readFileSync(rc, 'utf8') : '';
     if (cur.includes(line)) {
-        log(`✓ 补全已在 ${rc}，无需重复安装`);
+        log(t(`✓ 补全已在 ${rc}，无需重复安装`, `✓ completion already in ${rc}, nothing to do`));
         return;
     }
     fs.appendFileSync(rc, `\n# worktree-bay completion\n${line}\n`);
-    log(`✓ 补全已加入 ${rc}，执行 'source ${rc}' 或重开终端即生效`);
+    log(t(`✓ 补全已加入 ${rc}，执行 'source ${rc}' 或重开终端即生效`, `✓ completion added to ${rc}; run 'source ${rc}' or reopen your terminal to enable it`));
 }

package/dist/commands/doctor.js

@@ -3,26 +3,27 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { repoPath } from '../config.js';
 import { log, warn } from '../util/log.js';
+import { t } from '../i18n.js';
 // 体检：git 是否可用、配置是否有效、各服务仓是否存在且是 git 仓。返回问题数。
 export function doctor(cfg) {
     let problems = 0;
     const ok = (m) => log(`✓ ${m}`);
     const bad = (m) => { warn(`✗ ${m}`); problems++; };
     if (spawnSync('git', ['--version'], { encoding: 'utf8' }).status === 0)
-        ok('git 可用');
+        ok(t('git 可用', 'git available'));
     else
-        bad('git 不可用（worktree 依赖 git）');
-    ok(`配置已加载并通过校验（${Object.keys(cfg.services).length} 个服务，槽位 1..${cfg.maxSlots}，端口 = 服务基址 + 槽号）`);
+        bad(t('git 不可用（worktree 依赖 git，请先安装 git）', 'git not available (worktree needs git — install it first)'));
+    ok(t(`配置已加载并通过校验（${Object.keys(cfg.services).length} 个服务，槽位 1..${cfg.maxSlots}，端口 = 服务基址 + 槽号）`, `config loaded and valid (${Object.keys(cfg.services).length} services, slots 1..${cfg.maxSlots}, port = service base + slot)`));
     for (const name of Object.keys(cfg.services)) {
         const repo = repoPath(cfg, name);
         if (!fs.existsSync(repo))
-            bad(`服务 ${name} 仓目录不存在: ${repo}`);
+            bad(t(`服务 ${name} 仓目录不存在: ${repo}（检查配置里的 workspaceRoot / repo，或先 git clone）`, `service ${name} repo dir missing: ${repo} (check workspaceRoot/repo in config, or clone it)`));
         else if (!fs.existsSync(path.join(repo, '.git')))
-            bad(`服务 ${name} 不是 git 仓: ${repo}`);
+            bad(t(`服务 ${name} 不是 git 仓: ${repo}（在该目录 git init 或 clone）`, `service ${name} is not a git repo: ${repo} (git init or clone there)`));
         else
-            ok(`服务 ${name} → ${repo}`);
+            ok(`${t('服务', 'service')} ${name} → ${repo}`);
     }
-    log(problems === 0 ? '\n✓ 一切正常' : `\n✗ 发现 ${problems} 个问题`);
+    log(problems === 0 ? t('\n✓ 一切正常', '\n✓ all good') : t(`\n✗ 发现 ${problems} 个问题`, `\n✗ found ${problems} problem(s)`));
     return problems;
 }
 export function doctorCommand(cfg) { if (doctor(cfg) > 0)

package/dist/commands/gc.js

@@ -5,6 +5,7 @@ import { buildVars } from '../engine.js';
 import { currentBranch, isDirty, hasUnpushed, isMergedToMain, remoteBranchGone, removeWorktree } from '../git.js';
 import { runShell } from '../util/exec.js';
 import { log, warn } from '../util/log.js';
+import { t } from '../i18n.js';
 export function classifyForGc(s) {
     if (s.merged && !s.dirty && !s.unpushed)
         return 'auto-remove';
@@ -20,7 +21,7 @@ export async function gcCommand(cfg, apply) {
                 const branch = currentBranch(o.dir);
                 const v = classifyForGc({ merged: isMergedToMain(repo, branch), dirty: isDirty(o.dir), unpushed: hasUnpushed(repo, branch) });
                 if (v === 'auto-remove') {
-                    log(`[gc] ${o.service} (slot ${slot}) 已合并且干净 → 移除`);
+                    log(t(`[gc] ${o.service} (槽 ${slot}) 已合并且干净 → 移除`, `[gc] ${o.service} (slot ${slot}) merged & clean → remove`));
                     if (apply) {
                         const sp = cfg.services[o.service];
                         if (sp.teardown) {
@@ -31,16 +32,16 @@ export async function gcCommand(cfg, apply) {
                     }
                 }
                 else if (v === 'flag')
-                    warn(`[gc] ${o.service} (slot ${slot}) 已合并但脏/未推 → 跳过，确认后手动删`);
+                    warn(t(`[gc] ${o.service} (槽 ${slot}) 已合并但有脏/未推改动 → 跳过；确认无误后用 \`worktree-bay rm ${o.slug.replace(/^s\d+-/, '')} ${o.service} -f\` 删`, `[gc] ${o.service} (slot ${slot}) merged but dirty/unpushed → skipped; once sure, remove with \`worktree-bay rm <feature> ${o.service} -f\``));
                 else if (remoteBranchGone(repo, branch))
-                    warn(`[gc] ${o.service} (slot ${slot}) 远端分支已删（疑似 squash）→ 确认后 bay rm`);
+                    warn(t(`[gc] ${o.service} (槽 ${slot}) 远端分支已删（疑似 squash 合并）→ 确认后用 \`worktree-bay down <功能>\` 拆`, `[gc] ${o.service} (slot ${slot}) remote branch gone (likely squash-merged) → once sure, tear down with \`worktree-bay down <feature>\``));
             }
         for (const { slot, feature } of pruneEmptyLabels(cfg)) {
-            log(`[gc] 槽 ${slot}（${feature}）空预约（无 worktree）`);
+            log(t(`[gc] 槽 ${slot}（${feature}）是空预约（无 worktree）`, `[gc] slot ${slot} (${feature}) is an empty reservation (no worktree)`));
             if (apply)
                 removeLabel(cfg, slot);
         }
         if (!apply)
-            log('（dry-run；加 --apply 执行 auto-remove 与空预约清理）');
+            log(t('（dry-run；加 --apply 才真正执行 auto-remove 与空预约清理）', '(dry-run; pass --apply to actually perform auto-remove and clear empty reservations)'));
     });
 }

package/dist/commands/init.js

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { log, warn } from '../util/log.js';
+import { t } from '../i18n.js';
 // 引导生成一份 worktree-bay.config.json：扫描 cwd 子目录里的 git 仓预填为服务（按服务分配端口段）
 export function initCommand(cwd) {
     const target = path.join(cwd, 'worktree-bay.config.json');
     if (fs.existsSync(target)) {
-        warn(`已存在 ${target}，未覆盖`);
+        warn(t(`已存在 ${target}，未覆盖`, `${target} already exists, not overwriting`));
         return;
     }
     const repos = [];
@@ -28,10 +29,10 @@ export function initCommand(cwd) {
     }
     const config = { workspaceRoot: cwd, maxSlots: 9, services };
     fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n');
-    log(`✓ 已生成 ${target}`);
+    log(t(`✓ 已生成 ${target}`, `✓ wrote ${target}`));
     if (repos.length)
-        log(`  识别到服务: ${repos.join(', ')}（每个分配一段端口，基址间隔 10）`);
+        log(t(`  识别到服务: ${repos.join(', ')}（每个分配一段端口，基址间隔 10）`, `  detected services: ${repos.join(', ')} (each gets a port segment, base ports 10 apart)`));
     else
-        log(`  未识别到子 git 仓，已写入 api/web 示例模板`);
-    log(`  下一步：补全各服务的 setup/env/upstream/exec/run。完整配置说明：worktree-bay skill`);
+        log(t(`  未识别到子 git 仓，已写入 api/web 示例模板`, `  no child git repos found; wrote an api/web example template`));
+    log(t(`  下一步：补全各服务的 setup/env/upstream/exec/run。完整配置说明：worktree-bay skill`, `  next: fill in each service's setup/env/upstream/exec/run. Full config guide: worktree-bay skill`));
 }

package/dist/commands/ls.js

@@ -1,6 +1,7 @@
 import { scanOccupancy, readLabels } from '../slots.js';
 import { portOf } from '../ports.js';
 import { log } from '../util/log.js';
+import { t } from '../i18n.js';
 export function renderSlots(cfg) {
     const occ = scanOccupancy(cfg);
     const labels = readLabels(cfg);
@@ -8,9 +9,9 @@ export function renderSlots(cfg) {
     const lines = [];
     for (const n of [...slots].sort((a, b) => a - b)) {
         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'}]`);
+        lines.push(`slot ${n}  ${labels[String(n)] ?? t('(未命名)', '(unnamed)')}  [${svc.join(', ') || t('无 worktree', 'no worktree')}]`);
     }
-    return lines.join('\n') || '(no slots in use)';
+    return lines.join('\n') || t('(无槽位在用)', '(no slots in use)');
 }
 export function slotsData(cfg) {
     const occ = scanOccupancy(cfg);

package/dist/commands/passthrough.js

@@ -2,13 +2,14 @@ import { repoPath } from '../config.js';
 import { scanOccupancy, slotOfFeature } from '../slots.js';
 import { buildVars, execArgv, run } from '../engine.js';
 import { log } from '../util/log.js';
+import { t } from '../i18n.js';
 function occupantOf(cfg, feature, service) {
     const slot = slotOfFeature(cfg, feature);
     if (slot === undefined)
-        throw new Error('unknown feature: ' + feature);
+        throw new Error(t(`功能「${feature}」未占槽。先 \`worktree-bay up ${feature} <服务...>\` 起它，再用 \`worktree-bay ls\` 确认。`, `feature "${feature}" hasn't claimed a slot. Run \`worktree-bay up ${feature} <services...>\` first, then check \`worktree-bay ls\`.`));
     const occ = (scanOccupancy(cfg).get(slot) ?? []).find((o) => o.service === service);
     if (!occ)
-        throw new Error(`${service} not in ${feature}`);
+        throw new Error(t(`服务「${service}」不在功能「${feature}」里。先 \`worktree-bay add ${feature} ${service}\`，或用 \`worktree-bay ls\` 看已起的服务。`, `service "${service}" is not in feature "${feature}". Run \`worktree-bay add ${feature} ${service}\` first, or see \`worktree-bay ls\`.`));
     return occ;
 }
 function ctxOf(cfg, feature, service) {
@@ -23,7 +24,7 @@ export function runCommand(cfg, feature, service, name, args) {
     const ctx = ctxOf(cfg, feature, service);
     const named = ctx.sp.run?.[name];
     if (!named)
-        throw new Error(`run.${name} 未定义于 ${service}`);
+        throw new Error(t(`服务 ${service} 没有定义 run.${name}。在 worktree-bay.config.json 里该服务的 "run" 下加一条，如 "run": { "${name}": ["echo", "hi"] }。`, `service ${service} has no run.${name}. Add it under that service's "run" in worktree-bay.config.json, e.g. "run": { "${name}": ["echo", "hi"] }.`));
     const argv = execArgv(ctx, [...named, ...args]);
     process.exit(run(argv[0], argv.slice(1)).code);
 }

package/dist/commands/rm.js

@@ -5,10 +5,11 @@ import { buildVars } from '../engine.js';
 import { isDirty, hasUnpushed, currentBranch, removeWorktree } from '../git.js';
 import { runShell } from '../util/exec.js';
 import { log, warn } from '../util/log.js';
+import { t } from '../i18n.js';
 export function resolveRm(cfg, feature, service) {
     const slot = slotOfFeature(cfg, feature);
     if (slot === undefined)
-        throw new Error('unknown feature: ' + feature);
+        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;
 }
@@ -19,7 +20,7 @@ export async function rmCommand(cfg, feature, service, force) {
             const repo = repoPath(cfg, o.service);
             const branch = currentBranch(o.dir);
             if (!force && (isDirty(o.dir) || hasUnpushed(repo, branch))) {
-                warn(`跳过 ${o.service}：有未提交/未推改动（-f 强删）`);
+                warn(t(`跳过 ${o.service}：有未提交或未推送的改动。先提交/推送，或加 -f 强制删除（会丢这些改动）。`, `skipped ${o.service}: it has uncommitted or unpushed changes. Commit/push first, or pass -f to force-remove (discards them).`));
                 continue;
             }
             const sp = cfg.services[o.service];
@@ -28,14 +29,14 @@ export async function rmCommand(cfg, feature, service, force) {
                 runShell(renderTemplate(sp.teardown, vars), { cwd: repo });
             }
             removeWorktree(repo, o.dir, force);
-            log(`✓ 移除 ${o.service}`);
+            log(t(`✓ 移除 ${o.service}`, `✓ removed ${o.service}`));
             removed++;
         }
         const slot = slotOfFeature(cfg, feature);
         if (!service && (scanOccupancy(cfg).get(slot) ?? []).length === 0) {
             removeLabel(cfg, slot);
             if (removed === 0)
-                log(`✓ 释放空槽预约 "${feature}"（槽 ${slot}）`);
+                log(t(`✓ 释放空槽预约 "${feature}"（槽 ${slot}）`, `✓ released empty slot reservation "${feature}" (slot ${slot})`));
         }
     });
 }

package/dist/config.js

@@ -1,36 +1,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { t } from './i18n.js';
 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', 'maxSlots'])
         if (raw[k] === undefined)
-            throw new Error(`config: ${k} required`);
+            throw new Error(t(`config: 缺少必填字段 ${k}`, `config: ${k} required`));
     const maxSlots = raw.maxSlots;
     const services = raw.services ?? {};
     // 端口段：每个服务 [port, port+maxSlots]（port=主 dev/槽0，槽 1..maxSlots 落在段内）
     for (const [name, sp] of Object.entries(services)) {
         if (typeof sp.port !== 'number' || sp.port < 1)
-            throw new Error(`config: ${name}.port must be a positive number`); // V2
+            throw new Error(t(`config: ${name}.port 必须是正整数`, `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
+            throw new Error(t(`config: ${name}.repo 目录不存在: ${repoDir}（检查 workspaceRoot 与 repo 名，或先 git clone）`, `config: ${name}.repo dir missing: ${repoDir} (check workspaceRoot and the repo name, or clone it first)`)); // 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}）`);
+                throw new Error(t(`config: 服务 ${entries[i][0]} 与 ${entries[j][0]} 端口段重叠（两服务 port 间距需 > maxSlots=${maxSlots}，请拉开端口基址）`, `config: services ${entries[i][0]} and ${entries[j][0]} have overlapping port segments (|portA-portB| must be > maxSlots=${maxSlots}; spread the base ports apart)`));
         }
     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
+            throw new Error(t(`config: ${name}.upstream.service '${sp.upstream.service}' 不存在于 services（写成已声明的服务名）`, `config: ${name}.upstream.service '${sp.upstream.service}' not found in services (use a declared service name)`)); // V3
     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}}`);
+                    throw new Error(t(`config: 未知模板变量 {${ref}}（只能引用内置变量或本服务 vars 里已声明的）`, `config: unknown template var {${ref}} (only built-in vars or this service's declared vars are allowed)`));
     return { workspaceRoot: raw.workspaceRoot, maxSlots, services, configDir: path.dirname(configPath) };
 }
 export function loadConfig(startDir) {
@@ -43,14 +44,14 @@ export function loadConfig(startDir) {
             return parseConfig(p);
         const parent = path.dirname(dir);
         if (parent === dir)
-            throw new Error('worktree-bay.config.json not found');
+            throw new Error(t('未找到 worktree-bay.config.json。请在工作区根目录运行 `worktree-bay init` 生成，或用环境变量 WORKTREE_BAY_CONFIG 指定其绝对路径。', 'worktree-bay.config.json not found. Run `worktree-bay init` in your workspace root to create one, or set WORKTREE_BAY_CONFIG to its absolute path.'));
         dir = parent;
     }
 }
 export function repoPath(cfg, service) {
     const sp = cfg.services[service];
     if (!sp)
-        throw new Error('unknown service: ' + service);
+        throw new Error(t(`未知服务「${service}」。运行 \`worktree-bay doctor\` 查看配置里有哪些服务。`, `unknown service "${service}". Run \`worktree-bay doctor\` to see configured services.`));
     return path.join(cfg.workspaceRoot, sp.repo ?? service);
 }
 export function renderTemplate(tpl, vars) {

package/dist/engine.js

@@ -6,6 +6,7 @@ import { scanOccupancy } from './slots.js';
 import { addWorktree } from './git.js';
 import { runShell, run, spliceArgv, isTTY } from './util/exec.js';
 import { warn, log } from './util/log.js';
+import { t } from './i18n.js';
 export function mergeEnvText(text, kv) {
     const lines = text.split('\n');
     const seen = new Set();
@@ -39,7 +40,7 @@ export function buildVars(cfg, ctx) {
 export async function bringUp(ctx, base, branch) {
     const { sp, dir, repo, vars } = ctx;
     if (!(await isPortFree(Number(vars.port))))
-        throw new Error(`port ${vars.port} 被占用（Codex#11）`);
+        throw new Error(t(`端口 ${vars.port} 已被占用。先停掉占用它的进程，或用 \`worktree-bay gc\`/\`worktree-bay down <功能>\` 释放其它槽后重试。`, `port ${vars.port} is already in use. Stop whatever is using it, or free a slot with \`worktree-bay gc\`/\`worktree-bay down <feature>\`, then retry.`));
     addWorktree(repo, dir, branch, base);
     for (const rel of sp.copy ?? []) {
         // dereference: vendor/node_modules 含符号链接，Windows 下原样复制符号链接会失败，跟随并拷目标内容
@@ -47,7 +48,7 @@ export async function bringUp(ctx, base, branch) {
         for (const lock of ['composer.lock', 'pnpm-lock.yaml', 'package-lock.json']) {
             const a = path.join(repo, lock), b = path.join(dir, lock);
             if (fs.existsSync(a) && fs.existsSync(b) && fs.readFileSync(a, 'utf8') !== fs.readFileSync(b, 'utf8'))
-                warn(`⚠ ${lock} 与主 checkout 不一致，拷来依赖可能版本错位，建议改跑安装（Codex#18）`);
+                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 ?? {})) {
@@ -61,10 +62,10 @@ export async function bringUp(ctx, base, branch) {
     if (sp.setup) {
         const r = runShell(renderTemplate(sp.setup, vars), { cwd: dir });
         if (r.code !== 0)
-            throw new Error('setup 失败');
+            throw new Error(t(`setup 命令失败（退出码 ${r.code}）。查看上面的输出排查；修好后可重跑 add（已建的 worktree 会被复用，不会重复创建）。`, `setup command failed (exit code ${r.code}). Check the output above; after fixing, re-run add (the existing worktree is reused, not recreated).`));
     }
     if (sp.start)
-        log(`  启动: (cd ${dir} && ${renderTemplate(sp.start, vars)})`);
+        log(t(`  启动: (cd ${dir} && ${renderTemplate(sp.start, vars)})`, `  start: (cd ${dir} && ${renderTemplate(sp.start, vars)})`));
 }
 export function execArgv(ctx, cmd) {
     const tpl = (ctx.sp.exec ?? ['sh', '-c', '{cmd...}']).map((el) => el === '{cmd...}' ? el : renderTemplate(el, ctx.vars));

package/dist/git.js

@@ -3,7 +3,16 @@ import fs from 'node:fs';
 function git(repo, ...a) { return spawnSync('git', ['-C', repo, ...a], { encoding: 'utf8' }); }
 function ok(repo, ...a) { const r = git(repo, ...a); if (r.status !== 0)
     throw new Error(`git ${a.join(' ')}: ${r.stderr || r.stdout}`); return r.stdout; }
-export function addWorktree(repo, dir, branch, base) { ok(repo, 'worktree', 'add', '-b', branch, dir, base); }
+export function branchExists(repo, branch) {
+    return git(repo, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`).status === 0;
+}
+export function addWorktree(repo, dir, branch, base) {
+    // 分支已存在（如上次 worktree 删了但分支留着）→ 直接挂出复用，不用 -b 重建（否则 git 会报 "branch already exists"）
+    if (branchExists(repo, branch))
+        ok(repo, 'worktree', 'add', dir, branch);
+    else
+        ok(repo, 'worktree', 'add', '-b', branch, dir, base);
+}
 export function removeWorktree(repo, dir, force) {
     const a = ['worktree', 'remove', dir];
     if (force)

package/dist/i18n.js

@@ -0,0 +1,23 @@
+// 识别顺序：WORKTREE_BAY_LANG 覆盖 → POSIX locale 环境变量 → Intl(OS 区域) → 回落中文。
+// 规则：命中 zh* → zh；有明确的非中文 locale → en；完全识别不出 → zh（用户选定的回落）。
+export function detectLang() {
+    const envLocale = process.env.WORKTREE_BAY_LANG || process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '';
+    if (/^zh/i.test(envLocale))
+        return 'zh';
+    if (envLocale.trim())
+        return 'en';
+    let osLocale = '';
+    try {
+        osLocale = Intl.DateTimeFormat().resolvedOptions().locale;
+    }
+    catch { /* 某些精简运行时无 Intl */ }
+    if (/^zh/i.test(osLocale))
+        return 'zh';
+    if (osLocale.trim())
+        return 'en';
+    return 'zh';
+}
+// 取中/英文案。两种语言都就地给出，运行时按 detectLang() 选。
+export function t(zh, en) {
+    return detectLang() === 'zh' ? zh : en;
+}

package/dist/lock.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { t } from './i18n.js';
 export async function withLock(ws, fn) {
     const lockDir = path.join(ws, '.worktree-bay', 'lock');
     fs.mkdirSync(path.join(ws, '.worktree-bay'), { recursive: true });
@@ -11,7 +12,7 @@ export async function withLock(ws, fn) {
         }
         catch {
             if (Date.now() - start > 30000)
-                throw new Error('worktree-bay: lock timeout (另一个 worktree-bay 在运行?)');
+                throw new Error(t('获取工作区锁超时（是否有另一个 worktree-bay 在运行？）。若确认没有，删掉 .worktree-bay/lock 目录再试。', 'timed out acquiring the workspace lock (is another worktree-bay running?). If not, delete the .worktree-bay/lock directory and retry.'));
             await new Promise((r) => setTimeout(r, 50));
         }
     }

package/dist/mcp.js

@@ -12,24 +12,31 @@ export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开
 核心模型：每个服务有自己的端口段（基址 = 主 dev/槽0）；一个功能占一个「槽位 N」，用到哪些服务就在哪些服务上各开一个 git worktree 挂进这个槽，该服务端口 = 基址 + N，自动错开，前端自动连到同槽的后端。
 
 推荐工作流：
+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 拆掉该功能。
+4. 收尾：分支合并后，先 worktree_bay_gc 看可回收项，再 worktree_bay_down 拆掉该功能（只传 feature=拆整功能；带 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 获取完整的使用与配置指南（含每个配置原语、模板变量、校验规则与完整示例）。`;
 const str = { type: 'string' };
 export const TOOLS = [
+    { name: 'worktree_bay_doctor', description: '体检并列出工作区全部服务及其仓目录、校验 git/配置/各仓是否就绪。起步前先调它，也是获知「有哪些服务名可传给 up/add」的途径。',
+        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)] : [])] },
@@ -39,12 +46,14 @@ 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（默认查脏/未推保护，force=true 强删）',
-        inputSchema: { type: 'object', properties: { feature: str, force: { type: 'boolean' } }, required: ['feature'] },
-        toArgs: (a) => ['down', String(a.feature), ...(a.force ? ['-f'] : [])] },
+    { 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_gc', description: '合并感知回收：默认 dry-run 只列建议，apply=true 才实际删除「已合并且干净」的功能',
         inputSchema: { type: 'object', properties: { apply: { type: 'boolean' } } },
         toArgs: (a) => ['gc', ...(a.apply ? ['--apply'] : [])] },
+    { name: 'worktree_bay_init', description: '在当前工作区生成 worktree-bay.config.json 骨架（扫描子 git 仓预填服务）；已存在则不覆盖。新工作区首次落地配置时用。',
+        inputSchema: { type: 'object', properties: {} }, toArgs: () => ['init'] },
     { name: 'worktree_bay_skill', description: 'worktree-bay 完整使用与配置指南（每个命令、每个配置原语、模板变量、校验规则、完整示例）。写/改 worktree-bay.config.json 或拿不准细节时先调用它。',
         inputSchema: { type: 'object', properties: {} }, toArgs: () => ['skill'] },
 ];

package/dist/slots.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { repoPath } from './config.js';
 import { parseWorktreeDir } from './naming.js';
+import { t } from './i18n.js';
 export function scanOccupancy(cfg) {
     const map = new Map();
     for (const service of Object.keys(cfg.services)) {
@@ -35,7 +36,7 @@ export function freeSlot(cfg) {
     for (let n = 1; n <= cfg.maxSlots; n++)
         if (!occ.has(n) && l[String(n)] === undefined)
             return n;
-    throw new Error(`no free slot (1..${cfg.maxSlots} all taken)`);
+    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; }

package/dist/util/clierr.js

@@ -0,0 +1,19 @@
+import { t } from '../i18n.js';
+export function friendlyParseError(rawMessage, cmd) {
+    const m = (rawMessage || '').replace(/\r?\n$/, '');
+    const grab = (re) => { const x = re.exec(m); return x ? x[1] : ''; };
+    const hint = cmd
+        ? t(`\n用法: worktree-bay ${cmd.name} ${cmd.usage}\n说明: ${cmd.description}\n查看完整帮助: worktree-bay help ${cmd.name}`, `\nUsage: worktree-bay ${cmd.name} ${cmd.usage}\n${cmd.description}\nFull help: worktree-bay help ${cmd.name}`)
+        : t('\n运行 worktree-bay help 查看所有命令与用法', '\nRun: worktree-bay help');
+    if (/missing required argument/i.test(m))
+        return t(`缺少必填参数「${grab(/argument '(.+?)'/)}」。把它补在命令后面再试。${hint}`, `Missing required argument "${grab(/argument '(.+?)'/)}". Append it to the command and retry.${hint}`);
+    if (/argument missing/i.test(m))
+        return t(`选项「${grab(/option '(.+?)'/)}」缺少取值。${hint}`, `Option "${grab(/option '(.+?)'/)}" needs a value.${hint}`);
+    if (/too many arguments/i.test(m))
+        return t(`参数过多，多余的请删掉。${hint}`, `Too many arguments — remove the extra ones.${hint}`);
+    if (/unknown option/i.test(m))
+        return t(`未知选项「${grab(/unknown option '?(.+?)'?$/)}」。检查拼写或去掉它。${hint}`, `Unknown option "${grab(/unknown option '?(.+?)'?$/)}" — check spelling or drop it.${hint}`);
+    if (/unknown command/i.test(m))
+        return t(`未知命令「${grab(/unknown command '(.+?)'/)}」。运行 worktree-bay help 查看所有命令。`, `Unknown command "${grab(/unknown command '(.+?)'/)}". Run: worktree-bay help`);
+    return m.replace(/^error:\s*/i, '');
+}

package/package.json

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

@@ -18,6 +18,8 @@ npm i -g worktree-bay        # 需要 Node >= 20
 worktree-bay completion install   # 一键装 shell 补全（可选）
 ```
 
+> **输出语言**：按系统区域（locale / `LANG` / `LC_*`）自动中英切换，识别不出时默认中文。可用 `WORKTREE_BAY_LANG=zh|en` 强制。错误提示均为自然语言并附「应该怎么做」的建议。
+
 ---
 
 ## 命令大全
@@ -152,7 +154,7 @@ worktree-bay gc                        # 回收已合并的
 
 ## 给 AI（MCP）
 
-`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` 取本指南全文。
+`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` 取本指南全文。
 
 ## 常见坑