configure-workspaces

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configure workspaces

配置 workspace

Build an evidence-backed workspace configuration, let the user review the complete JSON, then write only what they approve.

The shared file is

.agent-work/workspace.json

. Machine-specific overrides belong in

.agent-work/workspace.local.json

, which must be ignored by Git. Compatible task runners use these files to create worktrees immediately for a task.

基于证据构建 workspace 配置，让用户审阅完整的 JSON，然后只写入用户批准的内容。

共享文件是

.agent-work/workspace.json

。机器专用覆盖配置应放在

.agent-work/workspace.local.json

中，并且必须被 Git 忽略。兼容的 task runner 会使用这些文件为任务立即创建 worktree。

1. Resolve the repository

1. 解析仓库

Run

git rev-parse --show-toplevel

from the current directory. Use the returned root and state it in one sentence.

If the command fails, ask exactly one question:

Which repository should I configure? Send its path.

Resolve the reply with

git -C <path> rev-parse --show-toplevel

. Quote the path safely in every command. Keep asking only when the supplied path is not a Git repository.

Complete when: one canonical Git root has been selected and every later read or command is anchored to it.

从当前目录运行

git rev-parse --show-toplevel

。使用返回的根目录，并用一句话说明它。

如果命令失败，只问一个问题：

我应该配置哪个仓库？请提供其路径。

使用

git -C <path> rev-parse --show-toplevel

解析回复中的路径。在每条命令中都要安全地引用路径。仅当提供的路径不是 Git 仓库时继续询问。

完成条件： 已选定一个规范的 Git 根目录，且后续所有读取和命令均以其为基准。

2. Inventory before inferring

2. 先盘点，再推断

Read these files when present:

.agent-work/workspace.json

and

.agent-work/workspace.local.json

```
AGENTS.md
```
,
```
.agent-work/tasks/
```
, and project-documented agent or runtime configuration
```
package.json
```
, lockfiles,
```
Makefile
```
, and the relevant setup sections of
```
README.md
```
```
.gitignore
```
and
```
scripts/create_worktree.sh
```

Inspect

git remote -v

. Inspect sibling directories only when the selected repository or the user's request indicates a coordination repository or multi-repo workspace. Never read the contents of candidate secrets; check only whether names such as

.env

.env.local

, and

.env.development.local

exist.

Treat an existing workspace configuration as the baseline. Record, without writing yet:

whether the workspace is single-repo or multi-repo;
which repository should launch sessions by default;
the source remote/ref for every repository;
the setup command supported by project evidence;
existing local-only files worth copying into worktrees;
which values are shared and which are machine-specific.
whether an existing local overlay will be retained, updated, or removed.

For the inference rules and evidence priority, read

references/project-inference.md

now.

Complete when: every proposed repository, ref, setup command, copy glob, and local override traces to an inspected fact or an explicitly identified default; unresolved remote or primary-repo choices have been asked of the user.

存在以下文件时对其进行读取：

.agent-work/workspace.json

和

.agent-work/workspace.local.json

```
AGENTS.md
```
、
```
.agent-work/tasks/
```
，以及项目文档中说明的 Agent 或 runtime 配置
```
package.json
```
、lockfile、
```
Makefile
```
，以及
```
README.md
```
中相关的 setup 章节
```
.gitignore
```
和
```
scripts/create_worktree.sh
```

检查

git remote -v

。仅当选定仓库或用户请求表明存在协调仓库或多仓库 workspace 时，才检查同级目录。绝不读取候选 secret 的内容；只检查

.env

、

.env.local

和

.env.development.local

等名称是否存在。

将现有 workspace 配置作为基线。记录以下信息，但暂不写入：

workspace 是单仓库还是多仓库；
哪个仓库应默认启动 session；
每个仓库的源 remote/ref；
项目证据支持的 setup command；
值得复制到 worktree 中的现有本地专用文件；
哪些值是共享的，哪些值是机器专用的；
现有本地 overlay 将被保留、更新还是删除。

有关推断规则和证据优先级，现在阅读

references/project-inference.md

。

完成条件： 每个建议的仓库、ref、setup command、复制 glob 和本地覆盖配置都能追溯至已检查的事实或明确标识的默认值；尚未确定的 remote 或主仓库选择已向用户询问。

3. Construct the candidate

3. 构建候选配置

Before drafting JSON, read

references/config-contract.md

in full. It is the package's schema and merge-semantics source of truth.

Default to one repository:

json

{
  "disabled": false,
  "pathTemplate": "~/.agent-work/workspaces/{{ TASKSLUG }}/{{ REPOBASENAME }}",
  "branchTemplate": "{{ TASKSLUG }}",
  "sourceRef": "origin/main",
  "setupCommand": "",
  "copyGlobs": [],
  "repos": [
    {
      "localPath": ".",
      "description": "Selected repository",
      "primary": true
    }
  ]
}

Add sibling repositories only when project evidence or the user requires them. Put team-shareable behavior in

workspace.json

; put machine paths or personal overrides in

workspace.local.json

. Include only useful copy globs that exist or intentionally match local variants.

Hold the candidate until it passes Step 4. Do not ask for approval of unchecked JSON.

Complete when: complete candidate contents exist for every file that may be written, with all shared values and local overrides placed in their correct file.

在起草 JSON 前，完整阅读

references/config-contract.md

。它是该 package 的 schema 和 merge semantics 唯一事实来源。

默认使用一个仓库：

json

{
  "disabled": false,
  "pathTemplate": "~/.agent-work/workspaces/{{ TASKSLUG }}/{{ REPOBASENAME }}",
  "branchTemplate": "{{ TASKSLUG }}",
  "sourceRef": "origin/main",
  "setupCommand": "",
  "copyGlobs": [],
  "repos": [
    {
      "localPath": ".",
      "description": "Selected repository",
      "primary": true
    }
  ]
}

仅当项目证据或用户要求时，才添加同级仓库。将团队可共享的行为放入

workspace.json

；将机器路径或个人覆盖配置放入

workspace.local.json

。仅包含确实存在或有意匹配本地变体的有用 copy glob。

在候选配置通过步骤 4 之前，不要请求用户批准。不要让用户批准未经检查的 JSON。

完成条件： 每个可能写入的文件都有完整的候选内容，且所有共享值和本地覆盖配置均已放入正确的文件。

4. Validate, present, and revise

4. 验证、展示和修改

Validate the candidate without executing setup commands or creating worktrees.

在不执行 setup command 或创建 worktree 的情况下验证候选配置。

Syntax and schema

语法和 schema

Parse each document with an available JSON parser, such as
```
jq empty
```
or
```
python3 -m json.tool
```
, by feeding it the exact candidate contents.
Apply every root, repository-entry, override, merge, and template rule in
```
references/config-contract.md
```
.
Require unique
```
localPath
```
values within each
```
repos
```
array.
Require exactly one effective
```
primary: true
```
after overlays for a multi-repo proposal, and exactly one in a newly generated multi-repo shared configuration. Keep the sole repository explicit as primary in newly generated single-repo configurations.
Accept
```
$patch: "delete"
```
only on a repository entry in
```
workspace.local.json
```
.
Keep
```
branchTemplate
```
at the root; reject it inside a repository entry.
Reject template variables other than
```
{{ TASKSLUG }}
```
and
```
{{ REPOBASENAME }}
```
.

使用可用的 JSON parser（例如
```
jq empty
```
或
```
python3 -m json.tool
```
）解析每个文档，并向其传入候选配置的确切内容。
应用
```
references/config-contract.md
```
中的所有 root、repository-entry、override、merge 和 template 规则。
要求每个
```
repos
```
数组内的
```
localPath
```
值唯一。
对于多仓库提案，在应用 overlay 后必须有且仅有一个生效的
```
primary: true
```
；对于新生成的多仓库共享配置，也必须有且仅有一个。对于新生成的单仓库配置，仍应将唯一仓库显式标为 primary。
仅允许在
```
workspace.local.json
```
的仓库条目中使用
```
$patch: "delete"
```
。
将
```
branchTemplate
```
保留在 root；拒绝在仓库条目中使用它。
拒绝除
```
{{ TASKSLUG }}
```
和
```
{{ REPOBASENAME }}
```
之外的 template 变量。

Repository and ref checks

仓库和 ref 检查

For every effective repository:

resolve
```
localPath
```
relative to the selected repository and verify the directory exists;

run

git -C <resolved-path> rev-parse --show-toplevel

and verify it names that repository;

identify the effective
```
sourceRef
```
after root and per-repo overrides;
when the ref begins with
```
<remote>/
```
, verify
```
<remote>
```
exists and the remote-tracking ref resolves locally; report a missing local ref rather than fetching automatically.

对于每个生效仓库：

相对于选定仓库解析
```
localPath
```
，并验证目录存在；

运行

git -C <resolved-path> rev-parse --show-toplevel

，并验证其指明该仓库；

确定应用 root 和按仓库覆盖配置后的生效
```
sourceRef
```
；
当 ref 以
```
<remote>/
```
开头时，验证
```
<remote>
```
存在且 remote-tracking ref 可在本地解析；报告缺失的本地 ref，而不是自动 fetch。

Setup and copy checks

setup 和复制检查

Explain each non-empty setup command in one sentence and show why repository evidence supports it. Do not run it during configuration.
Confirm each literal copy path exists. For wildcard globs, confirm at least one intended match or identify the glob as deliberately future-facing.
Confirm the repository
```
.gitignore
```
contains an exact
```
.agent-work/workspace.local.json
```
rule when the local file exists or will be written; include that edit in the proposal when absent.
Compute the effective config mentally using shared → local → per-repo precedence, while concatenating and de-duplicating
```
copyGlobs
```
. Confirm the resulting repositories, refs, setup commands, and primary repo match the proposal.

After every check passes, the first response after inspection must contain:

the complete proposed
```
.agent-work/workspace.json
```
in a fenced
```
json
```
block;
the complete proposed
```
.agent-work/workspace.local.json
```
in a second fenced
```
json
```
block when local overrides are useful;
an explicit deletion notice when an existing local file will be removed;
the proposed
```
.gitignore
```
addition when one is required;
one sentence identifying any assumption that needs attention;
this final line:

Tell me what to change, or approve this config.

On feedback, rebuild and revalidate the candidate, then print the complete proposal again. A partial fragment never replaces the full reviewable JSON. Approval must be explicit; presenting a proposal is not approval. If validation itself changes previously displayed JSON, show the full corrected proposal and obtain approval again.

Complete when: every validation item passes and the user has explicitly approved the exact full proposal that passed.

用一句话解释每个非空 setup command，并说明项目证据为何支持它。配置期间不要运行该命令。
确认每个字面量复制路径都存在。对于通配符 glob，确认至少存在一个预期匹配项，或说明该 glob 有意为未来预留。
当本地文件存在或将被写入时，确认仓库的
```
.gitignore
```
包含规则完全匹配的
```
.agent-work/workspace.local.json
```
；如果缺少该规则，则在提案中包含此编辑。
按 shared → local → per-repo 的优先级在头脑中计算生效配置，同时拼接并去重
```
copyGlobs
```
。确认最终得到的仓库、ref、setup command 和 primary 仓库与提案一致。

所有检查通过后，检查后的首次响应必须包含：

放在
```
json
```
fenced code block 中的完整建议
```
.agent-work/workspace.json
```
；
当本地覆盖配置有用时，放在第二个
```
json
```
fenced code block 中的完整建议
```
.agent-work/workspace.local.json
```
；
当现有本地文件将被删除时，明确给出删除通知；
需要添加时，给出建议的
```
.gitignore
```
条目；
用一句话指出任何需要关注的假设；
以下最终行：

告诉我需要修改什么，或者批准此配置。

收到反馈后，重新构建并重新验证候选配置，然后再次打印完整提案。局部片段绝不能取代完整、可审阅的 JSON。批准必须是明确的；展示提案并不等于批准。如果验证过程改动了此前展示的 JSON，请展示完整的更正后提案，并再次获得批准。

完成条件： 每项验证均通过，并且用户已明确批准通过验证的确切完整提案。

5. Write and verify

5. 写入和验证

Immediately before writing, re-read any existing workspace files. If they changed since inspection, stop and reconcile the new contents through the proposal loop.

Create

.agent-work/

when needed, then write the approved JSON with a trailing newline:

always write
```
.agent-work/workspace.json
```
;
write
```
.agent-work/workspace.local.json
```
only when the approved proposal contains local overrides;
remove an existing
```
.agent-work/workspace.local.json
```
only when the full proposal explicitly included its deletion and the user approved it;
add one exact
```
.agent-work/workspace.local.json
```
entry to
```
.gitignore
```
when the local file is not already ignored.

Preserve unrelated

.gitignore

contents. Do not stage, commit, or push unless the user separately asks.

Re-read both written files, parse them again, repeat the semantic checks affected by disk paths, run

git diff --check

, and inspect

git status --short

scoped to the written files and

.gitignore

Complete when: disk contents equal the approved proposal, both files parse, semantic validation still passes, the local file is ignored, and the scoped diff has no whitespace errors.

紧接写入前，重新读取所有现有 workspace 文件。如果它们自检查后发生变化，停止操作，并通过提案流程重新核对和调整新内容。

需要时创建

.agent-work/

，然后写入已批准的 JSON，并确保末尾带有换行：

始终写入
```
.agent-work/workspace.json
```
；
仅当已批准的提案包含本地覆盖配置时，才写入
```
.agent-work/workspace.local.json
```
；
仅当完整提案明确包含删除操作且用户已批准时，才删除现有的
```
.agent-work/workspace.local.json
```
；
当本地文件尚未被忽略时，向
```
.gitignore
```
添加一条完全匹配的
```
.agent-work/workspace.local.json
```
规则。

保留

.gitignore

中无关的内容。除非用户另行要求，否则不要 stage、commit 或 push。

重新读取两个已写入的文件，再次解析它们，重复受磁盘路径影响的语义检查，运行

git diff --check

，并检查范围限定于已写入文件和

.gitignore

的

git status --short

。

完成条件： 磁盘内容与已批准的提案一致，两个文件均可解析，语义验证仍然通过，本地文件已被忽略，且限定范围内的 diff 没有空白错误。

6. Hand off

6. 交接

Summarize:

files written;
number of effective repositories and the primary repository;
rendered path-template intent;
setup commands, if any;
copy-glob intent;
validation results.

Then explain:

The workspace configuration is ready. Use the task runner's immediate workspace option to provision it now. If the host provides a workspace settings view or permalink, that is an optional way to review or share the configuration; the files remain authoritative.

The task runner creates a worktree for each configured repository, copies the configured local files, runs each setup command, and starts the task in the primary repository's worktree.

For a team configuration, recommend committing

.agent-work/workspace.json

and any

.gitignore

change while keeping

.agent-work/workspace.local.json

untracked. Show the relevant paths in

git status

; leave staging to the user unless they asked for it.

Complete when: the user has the written-file inventory, effective behavior, validation outcome, task-runner next action, and correct shared-versus-local commit guidance.

总结：

已写入的文件；
生效仓库数量和 primary 仓库；
渲染后的 path template 意图；
setup command（如果有）；
copy glob 意图；
验证结果。

然后说明：

workspace 配置已就绪。使用 task runner 的 immediate workspace 选项立即创建它。如果 host 提供 workspace settings 视图或 permalink，可选择使用该方式审阅或分享配置；这些文件仍是权威来源。

task runner 会为每个已配置的仓库创建 worktree，复制已配置的本地文件，运行每个 setup command，并在 primary 仓库的 worktree 中启动任务。

对于团队配置，建议提交

.agent-work/workspace.json

和任何

.gitignore

更改，同时让

.agent-work/workspace.local.json

保持未跟踪。在

git status

中显示相关路径；除非用户要求，否则不要 stage。

完成条件： 已提供写入文件清单、生效行为、验证结果、task runner 的后续操作，以及正确的共享配置与本地配置提交建议。