# Worktree Map

[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black)](https://react.dev/)
[![Vite](https://img.shields.io/badge/Vite-6-646CFF?logo=vite&logoColor=white)](https://vite.dev/)
[![MCP](https://img.shields.io/badge/MCP-Apps%20%2B%20stdio-000000?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io/)
[![Codex Plugin](https://img.shields.io/badge/Codex-Plugin-1f6b5a)](https://github.com/520wheat/worktree-map)

Codex 桌面端插件：在当前仓库里查看**分支家谱 + worktree 工位**，标出当前会话位置，并支持创建、谨慎删除、安全清理与会话跳转（含降级指引）。

交付形态：Skills + 本地 MCP（stdio）+ MCP App UI（对话内面板）。

## 演示
Personal marketplace 安装后，在任意仓库会话里打开关系图：

<img 
  src="https://github.com/user-attachments/assets/1104b826-8778-4c2f-8ee3-04450e2b96a2" 
  alt="1"
  style="border-radius: 16px; width: 402px; height: auto;"
/>


仓库总览：分支家谱、worktree 工位与当前会话标记：

<img 
  width="432" height="474.4" 
  alt="2" 
  src="https://github.com/user-attachments/assets/aacf18d7-81c4-4d31-8f64-3cee72eebf12" 
  style="border-radius: 16px;" 
/>

分支操作：新建子分支、新建 worktree、一并创建：

<img 
  width="426.16" height="343.84" 
  alt="3" 
  src="https://github.com/user-attachments/assets/72bf8cb0-2b86-4a89-b6a7-50f77225ebf2" 
  style="border-radius: 16px;" 
/>


## 要求

- Node.js 20+
- pnpm 9（可用 Corepack）
- 本机 `git`

## 安装（Codex 本地 marketplace）

在本仓库根目录：

```bash
corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install
pnpm build
```

### 仅在本仓库会话可用（repo marketplace）

仓库内已有 `.agents/plugins/marketplace.json`（`path: ./`）。

1. 把 Codex 会话 cwd 设为**本仓库根**。
2. **重启 Codex**，打开 **Plugins**，安装 **Worktree Map**。

### 在任意仓库可用（推荐：personal marketplace）

Repo marketplace **不会**跟着你进别的项目。要在其他仓库用，需装到个人 marketplace：

```bash
mkdir -p ~/.agents/plugins ~/.codex/plugins
ln -sfn /Users/apple/Desktop/worktree_map ~/.codex/plugins/worktree-map
```

写入 `~/.agents/plugins/marketplace.json`（若已有其它插件，把下面这条合并进 `plugins` 数组）：

```json
{
  "name": "personal",
  "plugins": [
    {
      "name": "worktree-map",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/worktree-map"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}
```

然后：

1. **完全退出并重启** Codex。
2. 任意打开一个 git 仓库会话 → **Plugins** → 安装 / 启用 **Worktree Map**。
3. 调用时让 `session_cwd` = **当前会话所在仓库的绝对路径**（不是插件源码目录）。

MCP 由 `.mcp.json` 经 `/bin/bash scripts/run-mcp.sh` 启动（Codex 桌面端 PATH 通常没有 nvm 的 `node`，脚本会优先用 ChatGPT 自带 Node）。真正入口是自包含包 `packages/mcp-server/dist/mcp.mjs`（避免插件缓存里 pnpm 链接损坏）。

更新后请 `pnpm build`，再在 Plugins 里对 **personal** 版 Worktree Map **卸载 → 安装**（版本会升到缓存新目录）。不要同时依赖未安装的 local-repo 副本；跨仓库用 personal 即可。改完后**新开会话**再试（旧会话可能仍挂着坏掉的 MCP 客户端）。

## 开发

```bash
pnpm install
pnpm typecheck
pnpm test
pnpm build
```

常用命令：

```bash
pnpm test          # core / mcp-server / ui 测试 + 插件清单校验
pnpm accept        # 规格 §10 成功标准脚本化验收（临时 git 仓）
pnpm dev:ui        # UI 开发服务器（可加 ?fixture=1）
pnpm dev:mcp       # 构建并以前台方式启动 MCP stdio 进程
```

包结构：

| 包 | 作用 |
|----|------|
| `packages/core` | Git / 元数据 / 树 / 创建删除清理 / 会话桥 |
| `packages/mcp-server` | stdio MCP 工具 + UI resource |
| `packages/ui` | MCP App 双页签面板 |

规格与分步计划见 `docs/superpowers/`。

## 插件文件

| 路径 | 说明 |
|------|------|
| `.codex-plugin/plugin.json` | 插件清单 |
| `.mcp.json` | 捆绑 MCP 服务器 |
| `skills/worktree-map/SKILL.md` | 使用约定与工具编排 |
| `.agents/plugins/marketplace.json` | 仓库本地 marketplace（`path: ./`） |
| `scripts/run-mcp.mjs` | 以插件根解析 MCP/UI 产物路径并做构建预检 |

## 端到端验收（规格 §10）

一键门禁（单测 + 类型检查 + 构建 + §10 脚本验收）：

```bash
pnpm verify
```

或分步：`pnpm test && pnpm typecheck && pnpm build && pnpm accept`。

成功标准对照：

| # | 标准 | 证据 |
|---|------|------|
| 1 | 打开可见本地分支 / worktree 关系图 | `pnpm accept` 检查 1 |
| 2 | 识别当前会话工位或「未知」 | `pnpm accept` 2a/2b；UI StatusBar「未知」单测 |
| 3 | 只起名创建子分支+worktree，并 open_session 或降级 | `pnpm accept` 检查 3（默认降级指引） |
| 4 | 删除不误伤家族；安全清理只动合格候选 | `pnpm accept` 4a–4c；core remove/cleanup 单测 |

桌面端仍需你本地确认：Plugins 安装 → `@Worktree Map` → 双页签面板可渲染。

计划原文：`docs/superpowers/plans/worktree-map/14-端到端验收.md`。