new-workspace

创建新的 Git 工作区

操作前 — 必须执行

1. 检测当前范围：运行 git rev-parse --git-common-dir 和 --show-toplevel，确认当前操作的仓库。在项目控制根目录布局中，识别目标是根仓库、code/ 还是 paper/。
2. 阅读项目记忆（如果存在 memory/BRIEFING.md）：
   • memory/BRIEFING.md — 当前阶段和活动工作树
   • memory/project-conventions.md — 本项目的工作树命名政策和路径约定
3. 检查现有工作树：创建新工作树前运行 git worktree list，避免名称冲突或产生孤立工作树。

跳过第 2 步可能导致工作树路径错误，或使用与现有分支或工作树政策冲突的名称。

---

创建分支或 Git 工作树时，不要混淆项目级管理与组件仓库管理。

在以下情况下使用此技能：

• 代码、实验、基线、功能、调试或 rebuttal 实现分支
• NeurIPS、ICML、ICLR、CVPR、ACL 或 EMNLP 等会议的论文分支
• arXiv 论文发布
• 会议终稿版本

在完整的研究项目中，代码工作树应位于 <ProjectName>/code-worktrees/ 下，论文工作树应位于 <ProjectName>/paper-worktrees/ 下。

将此技能与以下技能配合使用：

• safe-git-ops：处理非简单的 Git 状态、冲突或沙箱写入失败
• research-project-memory：记录工作树用途和退出条件
• remote-project-control：在 SSH/HPC 服务上使用代码工作树时
• run-experiment：新工作区创建后立即启动作业时
• submit-paper：论文工作树用于投稿、arXiv 发布或会议终稿时
• camera-ready-finalizer：论文工作树用于录用后的版本时

核心原则

• 为组件仓库创建工作树，而不是为整个项目根目录创建。
• 优先将代码工作树放在 <ProjectName>/code-worktrees/ 下，与代码仓库同级。
• 优先将论文工作树放在 <ProjectName>/paper-worktrees/ 下，与论文仓库同级。
• 除非用户明确要求这种布局，否则避免在 code/ 或 paper/ 内嵌套工作树。
• 每个研究工作树都应记录用途、关联的论点／风险／实验以及退出条件。
• 论文工作树还应记录目标会议／版本、投稿模式、模板／样式差异、清理要求和源码可见性假设。
• 论文源码可见性与会议无关。论文工作树可以是 agent-private、author-visible、anonymous-submission、public-preprint、camera-ready-public 或 publisher-artifact。
• experiments/ 存放可运行逻辑；稳定的结果摘要放在 docs/results/，报告放在 docs/reports/，运行指针放在 docs/runs/。
• 运行 uv sync 后，代码工作树应有自己的 .venv/。默认情况下，论文工作树不需要本地安装 TeX；Overleaf/GitHub 编译可以作为权威版本。

步骤 1 - 确定目标类型

询问用户：

• 工作区类型：branch 或 worktree
• 组件：code 或 paper
• 分支类型：
  • 代码：feature、exp、baseline、debug、rebuttal 或自定义
  • 论文：venue、submission、arxiv、camera-ready、rebuttal、paper-fix 或自定义
• 不带前缀的分支名称
• 目标仓库路径（如果不明显）
• 对于论文工作区：源码可见性级别、受众、同步目标和清理门槛
• 是否写入工作树记忆

如果在 <ProjectName>/ 内运行，实验、基线、调试和 rebuttal 实现工作优先使用 code/ 仓库。 如果是会议适配、arXiv 发布、会议终稿、源码清理、仅修改论文的 rebuttal，或投稿格式调整，优先使用 paper/ 仓库。

如果在 <ProjectName>/code/ 内运行，则推断：

code repo root:      <ProjectName>/code/
project control root: <ProjectName>/
worktree root:      <ProjectName>/code-worktrees/

如果在 <ProjectName>/paper/ 内运行，则推断：

paper repo root:      <ProjectName>/paper/
project control root: <ProjectName>/
worktree root:        <ProjectName>/paper-worktrees/

如果在独立代码仓库内运行，则使用以下备用工作树根目录：

<code-repo-parent>/worktrees/

如果在独立论文仓库内运行，则使用以下备用工作树根目录：

<paper-repo-parent>/paper-worktrees/

步骤 2 - 验证 Git 状态

在目标仓库中：

git -C <repo-root> rev-parse --show-toplevel
git -C <repo-root> status --short
git -C <repo-root> branch --show-current
git -C <repo-root> worktree list

如果存在未提交的更改，询问是要提交、暂存、仅使用分支继续，还是取消。

步骤 3 - 选择分支名称

使用：

<branch-type>/<branch-name>

示例：

• exp/new-loss
• baseline/fair-tuning
• debug/nan-loss
• rebuttal/add-ablation
• feature/data-loader
• venue/neurips
• venue/icml
• arxiv/v1
• camera-ready/neurips
• private/draft
• overleaf/main-clean

工作树目录名称应便于文件系统使用：

<branch-type>-<branch-name-with-slashes-replaced-by-hyphens>

步骤 4 - 创建分支

对于仅使用分支的工作：

git -C <repo-root> checkout -b <branch-type>/<branch-name>

然后，如果该分支有研究用途，请更新组件记忆。

步骤 5 - 创建工作树

确定工作树根目录：

对于代码：

1. 如果 <repo-root> 是 <ProjectName>/code/，则使用 <ProjectName>/code-worktrees/。
2. 如果 <repo-root>/../code-worktrees/ 存在，则使用该目录。
3. 如果项目记忆中声明了代码工作树根目录，则使用该目录。
4. 否则使用 <repo-root>/../worktrees/。

对于论文：

1. 如果 <repo-root> 是 <ProjectName>/paper/，则使用 <ProjectName>/paper-worktrees/。
2. 如果 <repo-root>/../paper-worktrees/ 存在，则使用该目录。
3. 如果项目记忆中声明了论文工作树根目录，则使用该目录。
4. 否则使用 <repo-root>/../paper-worktrees/。

创建工作树：

mkdir -p <worktree-root>
git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> -b <branch-type>/<branch-name>

如果分支已存在，询问是否要基于现有分支创建工作树：

git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> <branch-type>/<branch-name>

步骤 6 - 复制本地工具配置并链接共享资源

如果存在本地 IDE/工具配置目录，请复制：

.vscode/
.cursor/
.claude/

请复制而不是创建符号链接，因为每个工作树可能需要独立的 IDE 状态。

如果 <repo-root>/.worktree-links 存在，请读取其中的相对路径，并将共享的大型资源符号链接到工作树中。典型条目：

data/
models/
.env
configs/local_settings.yaml

使用绝对符号链接目标，确保链接在工作树路径下仍然有效。

步骤 7 - 准备组件专用路径

代码工作树

在工作树中，确保：

docs/results/
docs/reports/
docs/runs/
.agent/

使用以下路径存放分支专属证据：

• docs/results/：稳定的结果摘要、表格备注、图表备注
• docs/reports/：实验报告和结果说明
• docs/runs/：作业 ID、配置路径、提交哈希、远程路径、简要指标
• .agent/worktree-status.md：用途、关联的主张/风险、最新可靠状态、退出条件

不要在 docs/ 中存放原始日志、检查点、wandb 运行数据、tensorboard 缓存或大型输出。

论文 Worktree

在论文 worktree 中，确保：

.agent/

创建或更新 .agent/worktree-status.md，填写论文版本相关字段：

• 目标会议或发布版本：NeurIPS、ICML、ICLR、CVPR、ACL、EMNLP、arXiv、camera-ready
• 投稿模式：anonymous、preprint、camera-ready、rebuttal 或 internal
• 与主论文在样式／模板上的差异
• 源文件可见性层级：
  • agent-private：可包含 .agent/、AGENTS.md、CLAUDE.md、写作记忆、来源记录、内部结果文档、CSV 和绘图脚本；不应同步到 Overleaf／公共远程仓库
  • author-visible：合作者／Overleaf 可见；必须排除 .agent/、AGENTS.md、CLAUDE.md、原始 CSV、内部文档、绘图脚本、审稿人策略和私有路径
  • anonymous-submission：会议／源文件上传可见；必须确保匿名，并排除 Agent／私有文件
  • public-preprint：arXiv／公开源文件；必须清理为可公开状态
  • camera-ready-public：最终录用后的公开／出版方源文件；必须取消匿名并清理为可公开状态
  • publisher-artifact：仅包含最终公开源文件及面向产物／发布的文件
• 受众和同步目标：none、Overleaf-GitHub、GitHub、submission-system、arXiv、publisher 或 artifact
• 允许的路径和禁止的路径
• 清理检查点：before-push、before-submission、before-arxiv、before-camera-ready 或 before-release
• 清理要求：
  • arXiv／公开源文件：删除 TODO、作者评论、审稿人备注、TeX 注释中的内部图表说明、隐藏备注和匿名化残留
  • 作者可见／Overleaf：删除或避免包含 .agent/、AGENTS.md、CLAUDE.md、原始 CSV、内部结果文档、绘图脚本、私有路径和仅供 Agent 使用的备注
  • 会议匿名稿：确保匿名并符合会议格式；若源文件会被上传，源代码注释仍可能带来风险，因此不要依赖注释来保护隐私
  • camera-ready：取消匿名、添加致谢／经费信息、落实 rebuttal 中的承诺，并删除仅供草稿使用的备注
• 源文件格式检查：安装了 tex-fmt 时运行 tex-fmt --check --nowrap --recursive .；仅在用户要求或项目政策规定时，才使用 tex-fmt --nowrap --recursive . 格式化
• 如果使用了 Overleaf/GitHub，记录其编译状态和分支映射

除非用户明确要求在论文 worktree 中记录论文专属备注，否则不要将代码侧的 docs/results/、docs/reports/ 或 docs/runs/ 约定复制到论文 worktree 中。论文版本记忆优先放在 .agent/ 中，持久的跨版本状态则放在根目录的 memory/ 中。

步骤 8 - 同步环境

对于代码 worktree，如果其中存在 pyproject.toml：

cd <worktree-path>
uv sync

如果 uv sync 失败，请报告错误，但不要删除 worktree。用户可能仍想检查或修复该分支。

对于论文 worktree，默认不要安装 TeX。使用项目的编译工作流：本地静态检查、可用时使用 tex-fmt，以及与 GitHub 关联的 Overleaf；除非用户明确要求使用本地 TeX。

第 9 步——编写 Worktree 记忆

如果工作区用于研究，请创建或更新：

<worktree>/.agent/worktree-status.md

包括：

• 分支
• 路径
• 创建日期
• 父分支
• 用途
• 关联的主张、实验、风险或审阅者提出的问题
• 与 main 分支的预期差异
• 对于论文 worktree：目标投稿场合/版本、模板/样式差异、源文件清理策略，以及公开/私有源文件假设
• 对于论文 worktree：源文件可见性级别、受众、同步目标、允许/禁止的文件策略，以及清理关卡
• 结果/输出路径
• 退出条件：合并、继续、搁置或终止
• 下一步验证操作

如果存在项目记忆，还要添加简短指引，指向：

• memory/component-index.yaml：已知 worktree 路径
• <component>/.agent/worktree-index.md：组件本地的活动 worktree 汇总
• memory/source-visibility-board.md：论文 worktree 或可见分支的源文件可见性级别和清理关卡
• memory/action-board.md：该 worktree 的下一步操作
• memory/current-status.md：仅当这是当前重点时
• memory/project-conventions.md：如果此 worktree 引入了新的命名约定、分支策略或 worktree 范围规则，且后续 Agent 必须了解，则将其添加到 worktree 类别下

根目录注册表和组件 worktree 索引是跨 worktree 的记忆记录位置。不要依赖某个 worktree 的叶级状态文件来告知后续 Agent 还存在其他哪些同级分支或论文版本。

第 10 步——最终摘要

报告：

Workspace created

Repo: <repo-root>
Branch: <branch-type>/<branch-name>
Worktree: <path or branch-only>
Evidence paths:
  <code worktree only: docs/results/, docs/reports/, docs/runs/>
Memory:
  .agent/worktree-status.md <created|skipped>

Next:
  cd <worktree-path>
  <code: uv sync and run/edit the planned experiment>
  <paper: run submit-paper checks and sync to Overleaf/GitHub if needed>

错误处理

• 不是 Git 仓库：停止并询问目标仓库。
• 工作树有未提交的更改：询问是提交、暂存、继续还是取消。
• 分支已存在：询问是使用现有分支还是选择新名称。
• Worktree 路径已存在：询问是选择新名称还是检查现有路径。
• 沙盒阻止写入 Git 元数据：视为权限问题，并使用 safe-git-ops。
• UV 同步失败：保留 worktree 并报告环境问题。
• 本地无法编译论文：默认不安装 TeX；改用 Overleaf/GitHub。

配置文件模板

如果 .worktree-links 不存在，请提出创建：

# .worktree-links
#
# Symlinks to create in new worktrees.
# List paths relative to the code repo root.

# data/
# models/
# .env
# configs/local_settings.yaml

最终健全性检查

• 分支或 worktree 已在预期的组件仓库中创建
• 除非有明确请求，否则 worktree 不嵌套在 code/ 或 paper/ 内
• git worktree list 显示预期路径
• 代码 worktree 的代码证据路径存在
• 论文 worktree 已记录版本策略
• 论文 worktree 已记录论文源文件可见性策略，尤其是对 Overleaf/合著者可见的分支和公开源文件分支
• 在相关情况下，worktree 记忆记录了用途和退出条件
• 项目记忆仅更新持久有效的指引，不记录日志