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）

在本仓库根目录：

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：

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

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

{
  "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 客户端）。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build

常用命令：

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 脚本验收）：

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。