worktree-bay 1.2.0 → 1.4.0

package/dist/cli.js

@@ -10,7 +10,8 @@ import { rmCommand } from './commands/rm.js';
 import { gcCommand } from './commands/gc.js';
 import { complete, completionCommand, installCompletion } from './commands/completion.js';
 import { startMcp } from './mcp.js';
-import { die } from './util/log.js';
+import { readSkill } from './skill.js';
+import { die, log } from './util/log.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);
@@ -78,9 +79,16 @@ program.command('completion <target> [shell]').description('install 一键装进
 catch (e) {
     die(e.message);
 } });
-program.command('mcp').description('启动 MCP 服务（stdio），供 AI 通过 MCP 调用 worktree-bay 完成并行开发')
-    .action(async () => { try {
-    await startMcp();
+program.command('mcp').description('启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 worktree-bay')
+    .action(() => { try {
+    startMcp();
+}
+catch (e) {
+    die(e.message);
+} });
+program.command('skill').description('打印 worktree-bay 使用与配置完全指南')
+    .action(() => { try {
+    log(readSkill());
 }
 catch (e) {
     die(e.message);

package/dist/commands/completion.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { readLabels } from '../slots.js';
 import { log } from '../util/log.js';
-const SUBCMDS = ['claim', 'up', 'add', 'ls', 'gc', 'down', 'rm', 'run', 'sh', 'completion', 'mcp'];
+const SUBCMDS = ['claim', 'up', 'add', 'ls', 'gc', 'down', 'rm', 'run', 'sh', 'completion', 'mcp', 'skill'];
 // words = 命令名 + 光标前已输入完的词（不含当前正在补的词）
 export function complete(cfg, words) {
     const prev = words.slice(1);

package/dist/mcp.js

@@ -1,18 +1,12 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readFileSync } from 'node:fs';
+import readline from 'node:readline';
 import path from 'node:path';
+// 轻量脚本式 MCP：手写 JSON-RPC over stdio，零依赖。客户端按需 spawn，stdin 关闭即退出，非常驻守护进程。
 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;
-// 工具实现：直接调底层 worktree-bay CLI 并捕获输出返回，复用全部逻辑
-function runCli(args) {
-    const r = spawnSync(process.execPath, [CLI, ...args], { encoding: 'utf8' });
-    const text = [r.stdout, r.stderr].filter(Boolean).join('\n').trim() || '(无输出)';
-    return { content: [{ type: 'text', text }] };
-}
+const PROTOCOL_VERSION = '2024-11-05';
 export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开发编排器。当你需要在一个多服务工作区里并行开发多个功能、又不想让它们的端口/依赖/数据互相干扰时，用本服务的工具来完成开发工作。
 
 核心模型：一个功能占一个「槽位」→ 得到一个端口块；该功能用到哪些服务，就在哪些服务上各开一个 git worktree 挂进这个槽，端口自动错开，前端自动连到同槽的后端。
@@ -27,30 +21,69 @@ export const INSTRUCTIONS = `worktree-bay 是「功能 = 槽位」的并行开
 - 同一个功能从头到尾用同一个功能名（它同时是默认分支名）贯穿 up/run/down。
 - 只起这个功能「实际要改」的服务，不要全起。
 - 拿不准当前状态时先调 worktree_bay_ls。
-- worktree_bay_gc 默认只读（dry-run 列出建议），apply=true 才真删，且只删「已合并到主分支且工作区干净」的，安全保守、不会误删未完成的工作。`;
-export function createServer() {
-    const server = new McpServer({ name: 'worktree-bay', version: VERSION }, { instructions: INSTRUCTIONS });
-    server.tool('worktree_bay_ls', '列出所有功能槽位与占用（每槽：功能名、端口块、已起服务及端口、是否已并入主分支）', {}, async () => runCli(['ls']));
-    server.tool('worktree_bay_up', '为一个功能一次性起多个服务（自动占槽 + 各服务开 worktree，分支默认 = 功能名，前端自动接同槽后端）。并行开发新功能首选。', {
-        feature: z.string().describe('功能名（同时作为默认分支名）'),
-        services: z.array(z.string()).describe('要起的服务名列表，如 ["api","lms"]'),
-    }, async ({ feature, services }) => runCli(['up', feature, ...services]));
-    server.tool('worktree_bay_add', '为功能在单个服务上开 worktree（branch 省略则用功能名）', {
-        feature: z.string(), service: z.string(), branch: z.string().optional(),
-    }, async ({ feature, service, branch }) => runCli(['add', feature, service, ...(branch ? [branch] : [])]));
-    server.tool('worktree_bay_run', '在某功能某服务的运行体里跑预设命令（如 test），可透传额外参数', {
-        feature: z.string(), service: z.string(),
-        name: z.string().describe('配置里 run.<name> 的名字，如 test'),
-        args: z.array(z.string()).optional(),
-    }, async ({ feature, service, name, args }) => runCli(['run', feature, service, name, ...(args ?? [])]));
-    server.tool('worktree_bay_down', '拆除整个功能的所有服务 worktree（默认查脏/未推保护，force=true 强删）', {
-        feature: z.string(), force: z.boolean().optional(),
-    }, async ({ feature, force }) => runCli(['down', feature, ...(force ? ['-f'] : [])]));
-    server.tool('worktree_bay_gc', '合并感知回收：默认 dry-run 只列建议，apply=true 才实际删除「已合并且干净」的功能', {
-        apply: z.boolean().optional(),
-    }, async ({ apply }) => runCli(['gc', ...(apply ? ['--apply'] : [])]));
-    return server;
+- worktree_bay_gc 默认只读（dry-run 列出建议），apply=true 才真删，且只删「已合并到主分支且工作区干净」的，安全保守、不会误删未完成的工作。
+- 要写或修改 worktree-bay.config.json、或拿不准任何命令/参数/配置细节时，先调用 worktree_bay_skill 获取完整的使用与配置指南（含每个配置原语、模板变量、校验规则与完整示例）。`;
+const str = { type: 'string' };
+export const TOOLS = [
+    { name: 'worktree_bay_ls', description: '列出所有功能槽位与占用（功能名、端口块、已起服务及端口、是否已并入主分支）',
+        inputSchema: { type: 'object', properties: {} }, toArgs: () => ['ls'] },
+    { name: 'worktree_bay_up', description: '为一个功能一次性起多个服务（自动占槽 + 各服务开 worktree，分支默认=功能名，前端自动接同槽后端）。并行开发新功能首选。',
+        inputSchema: { type: 'object', properties: { feature: str, services: { type: 'array', items: str } }, required: ['feature', 'services'] },
+        toArgs: (a) => ['up', String(a.feature), ...(a.services ?? [])] },
+    { name: 'worktree_bay_add', description: '为功能在单个服务上开 worktree（branch 省略则用功能名）',
+        inputSchema: { type: 'object', properties: { feature: str, service: str, branch: str }, required: ['feature', 'service'] },
+        toArgs: (a) => ['add', String(a.feature), String(a.service), ...(a.branch ? [String(a.branch)] : [])] },
+    { name: 'worktree_bay_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_gc', description: '合并感知回收：默认 dry-run 只列建议，apply=true 才实际删除「已合并且干净」的功能',
+        inputSchema: { type: 'object', properties: { apply: { type: 'boolean' } } },
+        toArgs: (a) => ['gc', ...(a.apply ? ['--apply'] : [])] },
+    { name: 'worktree_bay_skill', description: 'worktree-bay 完整使用与配置指南（每个命令、每个配置原语、模板变量、校验规则、完整示例）。写/改 worktree-bay.config.json 或拿不准细节时先调用它。',
+        inputSchema: { type: 'object', properties: {} }, toArgs: () => ['skill'] },
+];
+function runCli(args) {
+    const r = spawnSync(process.execPath, [CLI, ...args], { encoding: 'utf8' });
+    return [r.stdout, r.stderr].filter(Boolean).join('\n').trim() || '(无输出)';
+}
+export function handle(msg) {
+    const { id, method, params } = msg;
+    if (method === 'initialize')
+        return { jsonrpc: '2.0', id, result: { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: 'worktree-bay', version: VERSION }, instructions: INSTRUCTIONS } };
+    if (method === 'tools/list')
+        return { jsonrpc: '2.0', id, result: { tools: TOOLS.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })) } };
+    if (method === 'tools/call') {
+        const tool = TOOLS.find((t) => t.name === params?.name);
+        if (!tool)
+            return { jsonrpc: '2.0', id, error: { code: -32602, message: 'unknown tool: ' + params?.name } };
+        return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: runCli(tool.toArgs(params?.arguments ?? {})) }] } };
+    }
+    if (method === 'ping')
+        return { jsonrpc: '2.0', id, result: {} };
+    if (method?.startsWith('notifications/'))
+        return null;
+    if (id !== undefined)
+        return { jsonrpc: '2.0', id, error: { code: -32601, message: 'method not found: ' + method } };
+    return null;
 }
-export async function startMcp() {
-    await createServer().connect(new StdioServerTransport());
+export function startMcp() {
+    const rl = readline.createInterface({ input: process.stdin });
+    rl.on('line', (line) => {
+        const t = line.trim();
+        if (!t)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(t);
+        }
+        catch {
+            return;
+        }
+        const res = handle(msg);
+        if (res)
+            process.stdout.write(JSON.stringify(res) + '\n');
+    });
 }

package/dist/skill.js

@@ -0,0 +1,5 @@
+import { readFileSync } from 'node:fs';
+// 读取随包发布的 skill.md（位于包根，dist 的上一级）
+export function readSkill() {
+    return readFileSync(new URL('../skill.md', import.meta.url), 'utf8');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worktree-bay",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Config-driven git worktree slot + port orchestrator for parallel multi-service development",
   "keywords": [
     "git",
@@ -27,7 +27,8 @@
     "worktree-bay": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skill.md"
   ],
   "engines": {
     "node": ">=20"
@@ -43,9 +44,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "commander": "^12.1.0",
-    "zod": "^3.23.8"
+    "commander": "^12.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skill.md

@@ -0,0 +1,161 @@
+# worktree-bay 使用与配置完全指南
+
+`worktree-bay` 是配置驱动、与语言/技术栈无关的 **git worktree 槽位 + 端口编排器**，为多服务工作区的并行开发而生。
+
+## 核心模型：功能 = 槽位
+
+- 一个**功能**认领一个**槽位 `N`**（1..maxSlots）→ 得到一个**端口块** `portBase + N*slotSpan`。
+- 功能用到哪些**服务**，就在哪些服务各开一个 **git worktree** 挂进这个槽；块内每个服务按自己的 `offset` 取一个端口，互不相撞。
+- 同槽的前端服务自动把 api base 指向同槽的后端端口。
+- 槽位占用从文件系统派生（看 `<repo>/.worktrees/s<N>-*` 是否存在），删了 worktree 槽自动空出。
+
+---
+
+## 安装
+
+```bash
+npm i -g worktree-bay        # 需要 Node >= 20
+worktree-bay completion install   # 一键装 shell 补全（可选）
+```
+
+---
+
+## 命令大全
+
+| 命令 | 作用 |
+|---|---|
+| `worktree-bay up <feature> <service...>` | **最常用**：一条命令为功能起多个服务（自动占槽 + 各服务开 worktree，分支默认 = 功能名） |
+| `worktree-bay claim <feature>` | 只占一个槽、打印端口块（不开 worktree） |
+| `worktree-bay add <feature> <service> [branch] [base]` | 为功能在单个服务开 worktree。`branch` 省略 = 功能名；`base` 省略 = `origin/<主分支>` |
+| `worktree-bay ls` | 列出所有槽位：功能名、端口块、已起服务及端口、是否已并入主分支 |
+| `worktree-bay run <feature> <service> <name> [args...]` | 在某服务运行体里跑配置的 `run.<name>`（如 test），透传 args |
+| `worktree-bay sh <feature> <service>` | 进入某服务运行体的 shell |
+| `worktree-bay down <feature> [-f]` | 拆除整个功能的所有服务 worktree（= `rm <feature>`） |
+| `worktree-bay rm <feature> [service] [-f]` | 拆除某服务或整槽。默认查脏/未推保护，`-f` 强删 |
+| `worktree-bay gc [--apply]` | 合并感知回收：默认 dry-run 只列建议，`--apply` 才删「已合并且干净」的 |
+| `worktree-bay completion <install\|bash\|zsh\|fish>` | `install` 一键装进 shell；或打印补全脚本 |
+| `worktree-bay mcp` | 启动 MCP 服务（stdio，轻量脚本，客户端按需 spawn），供 AI 调用 |
+| `worktree-bay skill` | 打印本指南 |
+
+典型流程：
+
+```bash
+worktree-bay up drill-fix api lms      # 起整个功能（api+前端，分支都叫 drill-fix）
+worktree-bay ls
+worktree-bay run drill-fix api test    # 跑测试
+worktree-bay down drill-fix            # 拆掉
+worktree-bay gc                        # 回收已合并的
+```
+
+---
+
+## 配置详解：`worktree-bay.config.json`
+
+放在工作区根目录，工具自下而上查找（或用环境变量 `WORKTREE_BAY_CONFIG` 指定绝对路径）。
+
+### 顶层字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `workspaceRoot` | string | 工作区根绝对路径，各服务仓在其下 |
+| `portBase` | number | 端口基址，如 `6000` |
+| `slotSpan` | number | 每个槽位的端口跨度（块大小），如 `10` |
+| `maxSlots` | number | 最大并行功能数，如 `9` |
+| `services` | object | 服务名 → 服务定义（见下） |
+
+**端口计算**：`块基址 = portBase + 槽位N * slotSpan`；`某服务端口 = 块基址 + 该服务 offset`。
+例：portBase=6000, slotSpan=10，槽 1 的块基址 = 6010，offset=1 的服务端口 = 6011。
+
+### 服务定义原语
+
+| 原语 | 必填 | 类型 | 说明 |
+|---|---|---|---|
+| `offset` | ✅ | number | 本服务在块内的偏移；`1 ≤ offset < slotSpan`，各服务互不相同 |
+| `repo` | | string | 仓库目录名（相对 workspaceRoot），**默认 = 服务名** |
+| `vars` | | object | 自定义模板变量，值里可引用基础变量，如 `{ "project": "myapi-{slug}" }` |
+| `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`）。**只打印命令、不阻塞**，交你自己起 |
+| `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` 调用 |
+
+### 模板变量
+
+`vars` / `copy` / `env` 的值 / `setup` / `teardown` / `start` / `exec` 里都可用 `{变量}`：
+
+| 变量 | 含义 |
+|---|---|
+| `{slot}` | 槽位号 |
+| `{blockBase}` | 块基址 `portBase + slot*slotSpan` |
+| `{port}` | 本服务端口 `blockBase + offset` |
+| `{slug}` | worktree 目录名 `s<slot>-<分支归一化>` |
+| `{worktree}` | worktree 绝对路径 |
+| `{repo}` | 服务仓绝对路径 |
+| `{upstreamBase}` | 上游服务地址（同槽上游已起则为 `http://localhost:<上游端口>`，否则 `upstream.fallback`） |
+| `{cmd...}` | 透传命令的 argv splice（仅 `exec` 数组里用） |
+| 自定义 | `vars` 里声明的，如 `{project}` |
+
+### 加载时强制校验
+
+1. 各服务 `offset` 互不相同；
+2. `1 ≤ offset < slotSpan`；
+3. `upstream.service` 必须存在于 `services`；
+4. 所有模板里引用的 `{var}` 可解析（基础变量或本服务 vars 已声明）；
+5. `repo` 指向的目录存在。
+任一不满足则报错退出。
+
+### 完整示例（docker 后端 + vite 前端）
+
+```jsonc
+{
+  "workspaceRoot": "/path/to/workspace",
+  "portBase": 6000,
+  "slotSpan": 10,
+  "maxSlots": 9,
+  "services": {
+    "api": {
+      "offset": 1,
+      "vars": { "project": "myapi-{slug}" },
+      "copy": [".env", "vendor"],
+      "env": { ".env": { "APP_PORT": "{port}", "CACHE_PREFIX": "dev:{slug}:" } },
+      "setup": "docker compose -p {project} up -d",
+      "teardown": "docker compose -p {project} down -v",
+      "exec": ["docker", "exec", "-i", "{project}-app-1", "{cmd...}"],
+      "run": { "test": ["composer", "run", "test"], "migrate": ["php", "artisan", "migrate"] }
+    },
+    "web": {
+      "offset": 2,
+      "upstream": { "service": "api", "fallback": "http://localhost:6001" },
+      "env": { ".env.local": { "VITE_API_BASE_URL": "{upstreamBase}" } },
+      "setup": "pnpm install",
+      "start": "pnpm dev --port {port}"
+    }
+  }
+}
+```
+
+> 依赖处理：后端 `copy: ["vendor"]`（拷已装好的，免重装）；前端不拷 `node_modules`，用 `setup: "pnpm install"`（暖 store 下近乎瞬时，且躲开符号链接拷贝坑）。两种都支持，纯配置选择。
+
+---
+
+## 工作原理要点
+
+- **占用真相 = 文件系统**：扫各服务 `.worktrees/s<N>-*`；`.worktree-bay-slots.json` 只是「功能名→槽号」标签账本（预约）。
+- **并发安全**：`claim/add/up/rm/down/gc` 全程持工作区原子锁。
+- **前端自接后端**：前端有 `upstream` 且同槽该上游服务的 worktree 已建，则 `{upstreamBase}` = 本槽上游端口；否则用 `fallback`。所以**联调时先 `up`/`add` 后端，再起前端**。
+- **合并感知回收**：`gc` 先 `git fetch`，用 `merge-base --is-ancestor` 判断是否并入主分支；**只在「已合并 + 工作区干净 + 无未推」时才自动删**，判不准一律保守不删、只标记。
+
+---
+
+## 给 AI（MCP）
+
+`worktree-bay mcp` 暴露工具：`worktree_bay_up / ls / add / run / down / gc / skill`。要写或修改 `worktree-bay.config.json`、或拿不准命令/配置细节时，调用 `worktree_bay_skill` 取本指南全文。
+
+## 常见坑
+
+- 前端 api base 没指对：确认先起了同槽后端，且前端 `upstream.service` 写的是后端服务名。
+- `add` 报 `origin/...` invalid：该仓没有 origin 或主分支，显式传 `base`（如 `HEAD`）。
+- 槽位不够（maxSlots）：`worktree-bay gc` 回收已合并的，或 `down` 拆掉用完的。