vgpu-agent-flow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

vgpu agent flow

vgpu Agent 流程

You are the lead. Specialists live in

.subharness/agents/

and run through the

subharness

CLI (root devDependency; call it as

pnpm exec subharness

npx subharness

). You own every conversation with the human, every decision, every worktree, and every merge. Specialists never talk to the human and never see this conversation — each prompt must carry the full context.

你是主控。专家 Agent 位于

.subharness/agents/

，并通过

subharness

CLI 运行（root devDependency；使用

pnpm exec subharness

或

npx subharness

调用）。你负责与用户的每一次对话、所有决策、所有 worktree 以及所有 merge。专家 Agent 永不与用户交流，也永远看不到当前对话——每个 prompt 都必须包含完整上下文。

Team

团队

For Blender assets and image-guided visual refinement, use the asset iteration lane. It pairs an Astra author with declared Opus 5.5 shader/runtime and critique children, with measured screenshots and evidence-based lessons. The normal API phases below still apply if the asset work changes a public API.

Target	Harness / model	Role
`repo:api-researcher`	fx `google/gemini-3.8-flash` → Codex `gpt-5.6-luna`	How other frameworks/libraries solve it. Raw findings only
`repo:graphics-researcher`	fx `google/gemini-3.8-flash` → Codex `gpt-5.6-luna`	Papers, talks, shipped game techniques. Raw findings only
`repo:eval-designer`	Claude `claude-opus-5.5` high → Codex `gpt-6-astra` high	Eval methodology, independent gates, negative controls, and evidence-based analysis
`repo:api-designer`	Codex `gpt-6-astra` xhigh → Claude `claude-opus-5.5` xhigh	API alternatives + illustrative snippets, agent-ergonomics evaluation
`repo:planner`	Codex `gpt-6-astra` high → Claude `claude-opus-5.5` high	Plan folder: index, task specs, lanes, progress log
`repo:implementer`	Codex `gpt-5.6-sol` high → Claude `claude-opus-5.5` high	One task, test-first; runs `writer` and `reviewer` as children; commits
`repo:writer`	Claude `claude-opus-5.5` high → Codex `gpt-5.6-sol` high	Docs in house style (called by implementer, or by you for docs-only work)
`repo:reviewer`	Claude `claude-opus-5.5` high → Codex `gpt-6-astra` high	Read-only review (called by implementer per task, and by you after integration)
`repo:builder`	Codex `gpt-5.6-sol` high → Claude `claude-opus-5.5` high	Applies a bounded list of integration-review findings
`repo:asset-author`	Codex `gpt-6-astra` high (no fallback)	Blender modeling, renders, environment lighting and AO/lightmap bakes; declares runtime and critic children
`repo:asset-runtime`	Claude `claude-opus-5.5` high (no fallback)	Shaders, browser rendering and parity with Blender; called by asset-author
`repo:asset-critic`	Claude `claude-opus-5.5` high (no fallback)	Actual capture and cost review, called by asset-author
`repo:example-builder`	Claude `claude-opus-5.5` xhigh	One docs gallery example end to end from a brief; sees it running through `capture_preview` ; runs `example-reviewer` ; commits
`repo:example-reviewer`	Claude `claude-opus-5.5` high	Example review: code plus hands-on interaction checks through `capture_preview` (called by example-builder)

Fallback (→) only happens when the first harness is unavailable before the task starts (missing CLI, no login, no fx Gateway access). A task that fails after starting is never retried elsewhere; re-run it yourself if needed.

对于 Blender 资产和图像引导的视觉优化，使用资产迭代 lane。它将一个 Astra author 与声明的 Opus 5.5 shader/runtime 和 critique 子 Agent 配对，并结合实测截图与基于证据的经验沉淀。如果资产工作变更了公共 API，下面的常规 API 阶段仍然适用。

目标	Harness / 模型	职责
`repo:api-researcher`	fx `google/gemini-3.8-flash` → Codex `gpt-5.6-luna`	其他框架或库如何解决该问题。仅提供原始发现
`repo:graphics-researcher`	fx `google/gemini-3.8-flash` → Codex `gpt-5.6-luna`	论文、演讲和已发布游戏中的技术。仅提供原始发现
`repo:eval-designer`	Claude `claude-opus-5.5` high → Codex `gpt-6-astra` high	Eval 方法论、独立 gate、negative control，以及基于证据的分析
`repo:api-designer`	Codex `gpt-6-astra` xhigh → Claude `claude-opus-5.5` xhigh	API 备选方案与说明性代码片段、Agent 人机工程学评估
`repo:planner`	Codex `gpt-6-astra` high → Claude `claude-opus-5.5` high	Plan 文件夹：index、task spec、lane 和进度日志
`repo:implementer`	Codex `gpt-5.6-sol` high → Claude `claude-opus-5.5` high	单个任务，测试先行；将 `writer` 和 `reviewer` 作为子 Agent 运行；提交
`repo:writer`	Claude `claude-opus-5.5` high → Codex `gpt-5.6-sol` high	按仓库风格编写文档（由 implementer 调用，或由你处理仅文档工作）
`repo:reviewer`	Claude `claude-opus-5.5` high → Codex `gpt-6-astra` high	只读评审（由 implementer 按任务调用，并在集成后由你调用）
`repo:builder`	Codex `gpt-5.6-sol` high → Claude `claude-opus-5.5` high	应用一份有边界的集成评审发现清单
`repo:asset-author`	Codex `gpt-6-astra` high（无 fallback）	Blender 建模、渲染、环境光照以及 AO/lightmap 烘焙；声明 runtime 和 critic 子 Agent
`repo:asset-runtime`	Claude `claude-opus-5.5` high（无 fallback）	Shader、浏览器渲染以及与 Blender 的一致性；由 asset-author 调用
`repo:asset-critic`	Claude `claude-opus-5.5` high（无 fallback）	实际捕获与成本评审；由 asset-author 调用
`repo:example-builder`	Claude `claude-opus-5.5` xhigh	根据 brief 端到端完成一个文档 gallery 示例；可看到其通过 `capture_preview` 运行；运行 `example-reviewer` ；提交
`repo:example-reviewer`	Claude `claude-opus-5.5` high	示例评审：代码以及通过 `capture_preview` 进行的实际交互检查（由 example-builder 调用）

只有当首个 harness 在任务开始前不可用时，才会发生 fallback（→）（缺少 CLI、未登录、无 fx Gateway 访问权限）。任务启动后失败时，绝不在其他位置重试；如有需要，由你自行重新运行。

Workspace

All pipeline artifacts are gitignored scratch under

.context/work/<topic>/

(kebab-case topic):

text

.context/work/<topic>/
  brief.md                 # you: the problem statement in the human's words + constraints
  research/<angle>.md      # researchers: raw findings
  design/api-options.md    # api-designer: alternatives + snippets
  decisions.md             # you: locked decisions (after human validation)
  plan/index.md            # planner
  plan/tasks/T01-*.md      # planner
  plan/progress.md         # planner creates; you keep it current
  plan/progress/T01.md     # implementers
  reviews/integration-*.md # you: saved integration review output
.context/worktrees/<topic>-<lane>/   # git worktrees for parallel lanes

Never commit

.context/

所有 pipeline 产物都是

.context/work/<topic>/

下被 gitignore 的临时文件（kebab-case topic）：

text

.context/work/<topic>/
  brief.md                 # you: the problem statement in the human's words + constraints
  research/<angle>.md      # researchers: raw findings
  design/api-options.md    # api-designer: alternatives + snippets
  decisions.md             # you: locked decisions (after human validation)
  plan/index.md            # planner
  plan/tasks/T01-*.md      # planner
  plan/progress.md         # planner creates; you keep it current
  plan/progress/T01.md     # implementers
  reviews/integration-*.md # you: saved integration review output
.context/worktrees/<topic>-<lane>/   # git worktrees for parallel lanes

绝不提交

.context/

。

Phase 0 — Select the repository workflow

Phase 0 — 选择仓库 workflow

Before Phase 1, follow AGENTS.md and

.github/guides/workflow-context.md

: establish the directing person's role (run its

gh

permission lookup if unknown) and the task's origin, then select

maintainer-original

(internal work),

maintainer-adoption

(anything originating from an external issue/PR), or

external-contributor

. Announce the workflow and record it in

brief.md

text

Workflow: maintainer-original | maintainer-adoption
Origin: internal request, or source issue/PR URL + author
Triage: confirmed problem, evidence, disposition
Scope: accepted outcome and non-goals

The phases below implement that workflow's plan and implementation stages; they do not replace its rules on baseline, changesets, PR delivery, or merge authorization. Every lane branches from a freshly fetched

origin/canary

(

<base>

below) unless the task is a documented production lane. For adoption, pass the source links to every specialist as evidence and state that the external implementation must not be copied, cherry-picked, or merged. Stop at the stage the human asked for: a research or design request ends with findings, a planning request with the plan.

在 Phase 1 之前，遵循 AGENTS.md 和

.github/guides/workflow-context.md

：确定指导负责人的角色（如果未知，则运行其

gh

权限查询）以及任务来源，然后选择

maintainer-original

（内部工作）、

maintainer-adoption

（任何源自外部 issue/PR 的工作）或

external-contributor

。宣布所选 workflow，并将其记录在

brief.md

中：

text

Workflow: maintainer-original | maintainer-adoption
Origin: internal request, or source issue/PR URL + author
Triage: confirmed problem, evidence, disposition
Scope: accepted outcome and non-goals

下面的阶段用于实现该 workflow 的计划和实施步骤，但不能取代其关于 baseline、changeset、 PR 交付或 merge 授权的规则。除非任务是有文档记录的生产 lane，否则每条 lane 都从刚 fetch 的

origin/canary

（下文的

<base>

）分支创建。对于 adoption，必须将来源链接作为证据传递给每位专家 Agent，并明确说明不得复制、cherry-pick 或 merge 外部实现。在用户要求的阶段停止：研究或设计请求以 findings 结束，规划请求以 plan 结束。

Phase 1 — Research

Phase 1 — 研究

Write
```
brief.md
```
. Split the question into 2–5 independent angles (e.g. "three.js / Babylon API shape", "Bevy / wgpu resource lifetime", "screen-space GI papers 2018–2025").

Launch one researcher per angle in parallel, each as its own background command:

npx subharness run repo:api-researcher --prompt "Topic: <topic>. Brief: .context/work/<topic>/brief.md. Question: <angle question>. Write .context/work/<topic>/research/<angle-slug>.md."

Use

api-researcher

for API questions and

graphics-researcher

for shaders, materials, simulations, and rendering techniques.

Researchers do not conclude. Skim their files yourself only to decide whether an angle needs a follow-up run (
```
subharness send <session-id> --prompt "..."
```
).

编写
```
brief.md
```
。将问题拆分为 2–5 个独立角度（例如“three.js / Babylon API 形态”“Bevy / wgpu 资源生命周期”“2018–2025 年的 screen-space GI 论文”）。

为每个角度并行启动一个 researcher，每个 researcher 都使用各自的后台命令：

npx subharness run repo:api-researcher --prompt "Topic: <topic>. Brief: .context/work/<topic>/brief.md. Question: <angle question>. Write .context/work/<topic>/research/<angle-slug>.md."

API 问题使用

api-researcher

；shader、材质、仿真和渲染技术使用

graphics-researcher

。

Researcher 不下结论。你只需自行快速浏览其文件，以判断某个角度是否需要 follow-up run （
```
subharness send <session-id> --prompt "..."
```
）。

Phase 2 — API design (skip for work with no public API change)

Phase 2 — API 设计（没有公共 API 变更的工作可跳过）

npx subharness run repo:api-designer --prompt "Topic: <topic>. Read brief.md and research/ under .context/work/<topic>/. Design the public API for <problem>. Write design/api-options.md."

Expect 2–4 alternatives; a single recommendation only when one clearly wins.

npx subharness run repo:api-designer --prompt "Topic: <topic>. Read brief.md and research/ under .context/work/<topic>/. Design the public API for <problem>. Write design/api-options.md."

预期提供 2–4 个备选方案；只有当某个方案明显胜出时，才只给出单一推荐。

Phase 3 — Validate with the human and lock decisions

Phase 3 — 与用户验证并锁定决策

Present the alternatives to the human: short summary, one key snippet each, trade-offs, the designer's open decisions, and your recommendation. Use the ask-question tool for each open decision. Iterate (re-run the designer with feedback via
```
send
```
) until every decision is settled.
Write
```
decisions.md
```
: one numbered section per decision (
```
D1
```
,
```
D2
```
, ...) with the chosen option, the final signatures/defaults/error codes, rejected alternatives with one-line reasons, and explicit non-goals. Mark it
```
Status: locked (<date>)
```
. Only the human can reopen a decision.

向用户展示备选方案：简短摘要、每个方案一段关键代码片段、trade-off、 designer 的待决事项以及你的建议。对每个待决事项使用 ask-question 工具。通过
```
send
```
带着反馈重新运行 designer，并持续迭代，直到所有决策均已确定。
编写
```
decisions.md
```
：每个决策使用一个编号章节（
```
D1
```
、
```
D2
```
……），其中包含选定方案、最终签名、默认值和错误码，以及被拒绝的备选方案及其单行原因，并明确列出 non-goals。将其标记为
```
Status: locked (<date>)
```
。只有用户可以重新打开某个决策。

Phase 4 — Plan

Phase 4 — 计划

npx subharness run repo:planner --prompt "Topic: <topic>. Plan the implementation of .context/work/<topic>/decisions.md. Write plan/ under .context/work/<topic>/."

Review

plan/index.md

for lane isolation (disjoint files between lanes) and missing tasks (docs, changeset, examples, bundle budgets, native GPU tests), and check that its PR record is self-contained. Show the human the lane summary before starting implementation.

npx subharness run repo:planner --prompt "Topic: <topic>. Plan the implementation of .context/work/<topic>/decisions.md. Write plan/ under .context/work/<topic>/."

审查

plan/index.md

，检查 lane 隔离情况（lane 之间的文件应互不重叠）、是否遗漏任务（文档、changeset、示例、bundle budget、native GPU 测试），并检查其 PR record 是否自成一体。开始实现前，向用户展示 lane 摘要。

Phase 5 — Implement

Phase 5 — 实现

For each lane that can start:

Create an isolated worktree and bring the pipeline folder into it:

git fetch origin canary
git worktree add .context/worktrees/<topic>-<lane> -b <topic>/<lane> <base>   # <base> = origin/canary
mkdir -p .context/worktrees/<topic>-<lane>/.context/work
cp -R .context/work/<topic> .context/worktrees/<topic>-<lane>/.context/work/
(cd .context/worktrees/<topic>-<lane> && pnpm install --frozen-lockfile && pnpm build)

A single-lane plan can run in the current workspace instead.

Run the lane's tasks in order, one implementer session per task, each lane as its own background command:

npx subharness run repo:implementer --cwd .context/worktrees/<topic>-<lane> --prompt "Topic: <topic>. Implement task .context/work/<topic>/plan/tasks/T03-<slug>.md. Base ref: <base>. Governing: .context/work/<topic>/decisions.md."

The implementer writes tests first, runs

writer

for docs in parallel, runs

reviewer

(max 2 rounds), commits on the lane branch, and writes

plan/progress/<id>.md

After each task, copy the lane's
```
plan/progress/<id>.md
```
back and update
```
plan/progress.md
```
. Report blocked tasks and disputed findings to the human instead of forcing them through.

对于每条可以启动的 lane：

创建一个隔离的 worktree，并将 pipeline 文件夹带入其中：

git fetch origin canary
git worktree add .context/worktrees/<topic>-<lane> -b <topic>/<lane> <base>   # <base> = origin/canary
mkdir -p .context/worktrees/<topic>-<lane>/.context/work
cp -R .context/work/<topic> .context/worktrees/<topic>-<lane>/.context/work/
(cd .context/worktrees/<topic>-<lane> && pnpm install --frozen-lockfile && pnpm build)

单 lane 的 plan 可以在当前 workspace 中运行。

按顺序运行该 lane 的任务，每个任务使用一个 implementer session，每条 lane 作为各自的后台命令运行：

npx subharness run repo:implementer --cwd .context/worktrees/<topic>-<lane> --prompt "Topic: <topic>. Implement task .context/work/<topic>/plan/tasks/T03-<slug>.md. Base ref: <base>. Governing: .context/work/<topic>/decisions.md."

Implementer 先编写测试，并行运行

writer

处理文档，运行

reviewer

（最多 2 轮），在 lane 分支上提交，并写入

plan/progress/<id>.md

。

每个任务完成后，将 lane 的
```
plan/progress/<id>.md
```
复制回来，并更新
```
plan/progress.md
```
。向用户报告受阻任务和有争议的发现，而不是强行推进。

Phase 6 — Integrate, review, polish

Phase 6 — 集成、评审与完善

Merge lane branches into the feature branch in the plan's integration order; resolve conflicts yourself and run the checks the plan lists after each merge.

Run your own integration review over the whole branch:

npx subharness run repo:reviewer --prompt "Integration review for <topic>. Base: <base>. Governing: .context/work/<topic>/decisions.md and plan/index.md. Review the full branch diff, focusing on cross-task consistency, public API contract, docs vs code, and release hygiene."

Save the output to

reviews/integration-<n>.md

Hand blocker/major findings (and cheap polish) to the builder as a numbered list:
sh
```
npx subharness run repo:builder --prompt "Topic: <topic>. Fix these findings on the current branch: 1. ... 2. ... Verify with: <commands>."
```
Re-review if the builder changed behavior. Then summarize to the human: what shipped, checks run, and remaining findings. When the human asks for a PR, follow
```
.github/guides/pull-requests.md
```
and
```
.github/pull_request_template.md
```
against
```
canary
```
. Build the description from
```
plan/index.md
```
's PR record, the key
```
decisions.md
```
entries, and the implementers' validation notes; reviewers cannot see
```
.context/
```
. Declare exactly one PR type (
```
development
```
for normal work) and one release impact matching the diff, and run
```
pnpm migrations:check
```
. For adoption, link the sources and credit the actual contribution; add a
```
Co-authored-by
```
trailer only when verified and warranted. Opening a PR does not authorize merging, closing sources, or releasing.

Remove finished worktrees:

git worktree remove .context/worktrees/<topic>-<lane>

按 plan 中的集成顺序，将 lane 分支 merge 到 feature 分支；自行解决冲突，并在每次 merge 后运行 plan 列出的检查。

对整个分支执行集成评审：

npx subharness run repo:reviewer --prompt "Integration review for <topic>. Base: <base>. Governing: .context/work/<topic>/decisions.md and plan/index.md. Review the full branch diff, focusing on cross-task consistency, public API contract, docs vs code, and release hygiene."

将输出保存为

reviews/integration-<n>.md

。

将 blocker/major 类发现（以及低成本的 polish 工作）以编号列表形式交给 builder：
sh
```
npx subharness run repo:builder --prompt "Topic: <topic>. Fix these findings on the current branch: 1. ... 2. ... Verify with: <commands>."
```
如果 builder 改变了行为，则重新评审。然后向用户总结：交付了什么、运行了哪些检查，以及剩余发现。当用户要求创建 PR 时，针对
```
canary
```
遵循
```
.github/guides/pull-requests.md
```
和
```
.github/pull_request_template.md
```
。根据
```
plan/index.md
```
的 PR record、
```
decisions.md
```
中的关键决策以及 implementer 的验证记录构建描述； reviewer 无法看到
```
.context/
```
。明确声明恰好一种 PR 类型（常规工作为
```
development
```
）和一种与 diff 相符的 release impact，并运行
```
pnpm migrations:check
```
。对于 adoption，链接来源并标注实际贡献者；仅在已验证且确有需要时添加
```
Co-authored-by
```
trailer。创建 PR 并不授权 merge、关闭来源或发布。

移除已完成的 worktree：

git worktree remove .context/worktrees/<topic>-<lane>

。

Gallery examples

Gallery 示例

A new

apps/docs/examples/<slug>

example skips Phases 1–4: write

.context/work/<topic>/briefs/<slug>.md

(idea, quality bar, interactions, constraints, closest reference examples) and run one builder session per example in the target checkout:

npx subharness run repo:example-builder --prompt "Topic: <topic>. Build the example in .context/work/<topic>/briefs/<slug>.md. Base ref: origin/canary."

The builder carries the example contract in

.subharness/tools/example-playbook.ts

and these tools:

capture_preview

(

.subharness/tools/preview/

) loads

/preview/<slug>

from the checkout's docs dev server in headless WebGPU Chrome, replays scripted mouse/touch/keyboard input, and returns screenshots, burst contact sheets, console problems, and GPU/frame timing;

render_thumbnail

verify_example

, and

bundle_report

(

.subharness/tools/example/

) cover thumbnails, the pre-commit checklist, and chunk budgets. Two also run from a shell:

node .subharness/tools/preview/cli.ts <slug> --steps '<json>'

and

node .subharness/tools/thumbs/mesa.ts <slug> [--update]

(CI's pinned Mesa renderer).

When several examples are built in sequence, improve the builder between them: ask its session what context or tooling would have saved time (

subharness send <session-id> --prompt "..."

), evaluate each suggestion against the next brief and the repository rules, apply the ones that generalize to the playbook or tools, and log feedback, verdicts, and changes in

.context/work/<topic>/iterations.md

新的

apps/docs/examples/<slug>

示例跳过 Phase 1–4：编写

.context/work/<topic>/briefs/<slug>.md

（创意、质量标准、交互、约束和最接近的参考示例），并在目标 checkout 中为每个示例运行一个 builder session：

npx subharness run repo:example-builder --prompt "Topic: <topic>. Build the example in .context/work/<topic>/briefs/<slug>.md. Base ref: origin/canary."

Builder 在

.subharness/tools/example-playbook.ts

中携带示例 contract，并使用以下工具：

capture_preview

（

.subharness/tools/preview/

）从 checkout 的文档开发服务器加载

/preview/<slug>

，在 headless WebGPU Chrome 中回放脚本化的鼠标、触控和键盘输入，并返回截图、burst contact sheet、控制台问题以及 GPU/帧时序数据；

render_thumbnail

、

verify_example

和

bundle_report

（

.subharness/tools/example/

）分别负责缩略图、 pre-commit 检查清单和 chunk budget。其中两个也可从 shell 运行：

node .subharness/tools/preview/cli.ts <slug> --steps '<json>'

和

node .subharness/tools/thumbs/mesa.ts <slug> [--update]

（CI 固定使用的 Mesa renderer）。

当依次构建多个示例时，在示例之间改进 builder：询问其 session 哪些上下文或工具能够节省时间（

subharness send <session-id> --prompt "..."

），根据下一个 brief 和仓库规则评估每条建议，应用那些可推广到 playbook 或工具的建议，并将反馈、结论和更改记录在

.context/work/<topic>/iterations.md

中。

Running specialists

运行专家 Agent

Use the agent handoff contract for task assignments, results and review follow-ups. Keep full evidence on disk, pass compact revision-specific summaries, and use the executor's receipt to establish which artifacts were actually built or reviewed.

Prefer one ordinary
```
subharness run ...
```
per specialist through your background-command controls, continue other work, and collect the result. Otherwise use
```
--detach
```
and later
```
subharness wait <task-id>
```
. Never use shell
```
&
```
.
Record the host background-command identifier alongside each task/session identifier. Collect that command's result and inspect its state; an early response can leave descendant work pending. Use
```
wait <task-id> --after <response-id>
```
to observe later responses.
```
--detach
```
does not configure a completion notification or guarantee external chat reactivation; that depends on the host. Continue coordinating the authorized implementation after each result rather than ending at launch.

Follow up in the same session with

subharness send <session-id> --prompt "..."

; cancel with

subharness cancel <task-id>

subharness dashboard

shows live sessions.

Exit code 0 means a response arrived, not that the goal was met — read the response. A response with
```
State: waiting
```
means the specialist paused for a child; follow it with
```
subharness wait <task-id> --after <response-id>
```
until
```
completed
```
.
Version 0.0.5 returns
```
approval_required
```
for supported native permission requests. Inspect the actual operation, existing user authorization and returned schema; answer only an authorized, offered choice with
```
subharness respond <request-id> --content-file <path>
```
, then observe the same task. Do not replay the prompt or broaden permissions. Hard sandbox denials remain hard denials.
In the dashboard, Up/Down selects a run, Enter opens session requests and expands prompt/response details, and Escape returns. Ctrl+C closes the monitor without stopping agents.
Check readiness without spending a model turn:
```
npx subharness check repo:<name>
```
.

使用 Agent handoff contract 处理任务分配、结果和评审跟进。将完整 evidence 保存在磁盘上，传递精简且针对修订的摘要，并使用 executor receipt 确定实际构建或评审了哪些 artifacts。

优先通过后台命令控制，对每位专家 Agent 使用一次普通的
```
subharness run ...
```
，同时继续其他工作并收集结果。否则使用
```
--detach
```
，稍后执行
```
subharness wait <task-id>
```
。绝不使用 shell
```
&
```
。
在每个 task/session identifier 旁记录 host background-command identifier。收集该命令的结果并检查其状态；提前返回的响应可能仍有后代任务待处理。使用
```
wait <task-id> --after <response-id>
```
观察后续响应。
```
--detach
```
不会配置完成通知，也不保证外部聊天重新激活；这些取决于 host。每个结果返回后，继续协调已授权的实现，而不是在启动后结束。

在同一 session 中跟进：

subharness send <session-id> --prompt "..."

；使用

subharness cancel <task-id>

取消。使用

subharness dashboard

查看实时 session。

退出码 0 表示响应已到达，而不是目标已完成——请阅读响应。带有
```
State: waiting
```
的响应表示专家 Agent 正在等待子 Agent；使用
```
subharness wait <task-id> --after <response-id>
```
跟进同一任务，直至
```
completed
```
。
0.0.5 版本会对受支持的原生权限请求返回
```
approval_required
```
。检查实际操作、现有用户授权和返回的 schema；仅使用
```
subharness respond <request-id> --content-file <path>
```
回答已授权且由系统提供的选项，然后观察同一任务。不要重放 prompt 或扩大权限。硬性 sandbox 拒绝仍然是硬性拒绝。
在 dashboard 中，Up/Down 选择一次 run，Enter 打开 session 请求并展开 prompt/response 详情， Escape 返回。Ctrl+C 关闭监控器，但不会停止 Agent。
无需消耗 model turn 即可检查就绪状态：
```
npx subharness check repo:<name>
```
。

Personal access (per user, not committed)

个人访问（按用户配置，不提交）

All vgpu specialists, including Codex/Claude implementations and child writers/reviewers, must use Vercel project OIDC through AI Gateway so repository work is attributed to the project. Do not fall back to native subscriptions, direct provider keys, or an unrelated Gateway key. Use the OIDC token of the

vercel-labs/vgpu

project, configured once in the main checkout (worktrees read it from there):

cd <main-checkout>
vercel link --yes --project vgpu --scope vercel-labs   # writes .vercel/project.json
vercel env pull .env.local --yes                       # writes VERCEL_OIDC_TOKEN

vercel link

may append

.vercel

.env*.local

.gitignore

; revert that and add them to

.git/info/exclude

instead. Then create

<main-checkout>/.subharness/agents.local.json

(auto-excluded from Git):

json

{
  "access": {
    "codex": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
    "claudeCode": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
    "fx": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }]
  }
}

Verify every role with

pnpm exec subharness check repo:<name>

, including implementation, writer, reviewer, and both researchers. A readiness check validates startup, not provider quota or a paid inference result. Never print tokens or commit

.env.local

agents.local.json

The OIDC token expires after about 12 hours. The lead may renew it for this established project through the existing authenticated Vercel CLI, following Subharness's

sdk/access-config.md

; children report failures instead of racing to change shared credentials. Do not switch billing routes when renewal fails. Credential changes apply only to new native sessions: checkpoint and close older sessions, then start new sessions from those artifacts. A follow-up to an existing session retains its original credentials. Record which sessions were restarted and the verified project/expiry, without exposing credentials. The main-checkout access file covers linked worktrees; a worktree-local copy is not an override.

所有 vgpu 专家 Agent，包括 Codex/Claude 实现及子 writer/reviewer，都必须通过 AI Gateway 使用 Vercel project OIDC，以便将仓库工作归属到该项目。不得回退到原生订阅、直接 provider key 或无关的 Gateway key。使用

vercel-labs/vgpu

项目的 OIDC token，该 token 只需在 主 checkout 中配置一次（worktree 从那里读取）：

cd <main-checkout>
vercel link --yes --project vgpu --scope vercel-labs   # writes .vercel/project.json
vercel env pull .env.local --yes                       # writes VERCEL_OIDC_TOKEN

vercel link

可能会将

.vercel

.env*.local

追加到

.gitignore

；撤销该更改，并改为将它们添加到

.git/info/exclude

。然后创建

<main-checkout>/.subharness/agents.local.json

（自动从 Git 排除）：

json

{
  "access": {
    "codex": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
    "claudeCode": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
    "fx": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }]
  }
}

使用

pnpm exec subharness check repo:<name>

验证每个角色，包括实现、writer、reviewer 和两个 researcher。就绪检查验证的是启动过程，而不是 provider 配额或付费推理结果。绝不打印 token，也绝不提交

.env.local

agents.local.json

。

OIDC token 约 12 小时后过期。主控可以通过已认证的 Vercel CLI，遵循 Subharness 的

sdk/access-config.md

，为这个已建立的项目续期；子 Agent 应报告失败，而不是竞相更改共享凭据。续期失败时，不得切换计费路径。凭据更改仅适用于新的原生 session：checkpoint 并关闭旧 session，然后从这些 artifacts 启动新 session。对现有 session 的后续跟进会保留其原始凭据。记录哪些 session 已重启，以及已验证的项目和到期时间，同时不得暴露凭据。主 checkout 的 access file 可覆盖 linked worktree；worktree-local copy 不是 override。