workflow-threads-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow: threads manager

工作流：线程管理器

The user runs many Claude threads at once on one repository, and asks this thread to keep track of them. Each check answers four questions:

What landed on
main
since the last check, and does every change have its changelog entry with its pictures?
Is live healthy and current, or is it broken or behind
```
main
```
?
What is each thread doing: running, finished, cut off mid-task, or waiting on the user?
What can be archived, and what needs the user?

If this skill has a

references/<project>.md

for the current project, read it. Read the project's

AGENTS.md

first on every check, because other threads keep changing the rules (the live host, the changelog format, the size limits). Where

AGENTS.md

and this skill disagree,

AGENTS.md

wins.

用户会同时在一个仓库中运行许多 Claude 线程，并要求本线程跟踪它们。每次检查都要回答四个问题：

自上次检查以来有哪些内容进入
main
，并且每项变更是否都有 changelog 条目和对应图片？
线上环境是否健康且保持最新，还是已经损坏或落后于
```
main
```
？
每个线程正在做什么：正在运行、已完成、执行到一半中断，还是正在等待用户？
哪些内容可以归档，哪些事项需要用户处理？

如果此 skill 为当前项目提供了

references/<project>.md

，请阅读它。每次检查时都要先阅读项目的

AGENTS.md

，因为其他线程会不断更改规则（线上托管环境、changelog 格式、大小限制）。如果

AGENTS.md

与此 skill 的要求冲突，以

AGENTS.md

为准。

Tools

工具

Session tools (
```
mcp__ccd_session_mgmt__*
```
). If any of these show up only as deferred tool names, load them with ToolSearch first.
- ```
list_sessions
```
  : who is running, idle, pinned or archived.
- ```
get_session "self"
```
  : this thread's own id. Another thread can share its title.
- ```
list_events
```
  : a thread's recent transcript.
- ```
send_message
```
  : relay work to a thread, or restart one.
- ```
archive_session
```
  : archive a finished thread.
Scripts in
```
scripts/
```
. They are slow under load, so run them with
```
run_in_background
```
and read the output file.
- ```
repo-status.sh
```
  : where
```
main
```
  is, local branches holding commits that
```
main
```
  lacks, and worktrees with uncommitted edits (newest edit time, and whether the worktree is locked).
- ```
audit-changelog.py <since-rev>
```
  : for every commit since that revision, the version it added, its pictures shipped against pictures needed, and "NO VERSION" flags. Commits touching only tests, docs or scripts are marked exempt.
- ```
live-check.sh [url]
```
  : fetches the live page, then the scripts and art it references. A page returning 200 while its art returns 404 means the deploy is broken.
- ```
save-captures.sh <worktree> <name>
```
  : refuses (exit 2) if the worktree has unsaved or unmerged work. Otherwise it copies the gitignored screenshots to
```
qa/captures/archived-threads/<name>/
```
  .
- ```
contact-sheet.py <out.jpg> --count N
```
  : the newest N changelog entries' pictures on one sheet, read straight from
```
origin/main
```
  .

会话工具（
```
mcp__ccd_session_mgmt__*
```
）。如果这些工具仅以延迟加载的工具名称出现，请先使用 ToolSearch 加载。
- ```
list_sessions
```
  ：查看哪些线程正在运行、空闲、已置顶或已归档。
- ```
get_session "self"
```
  ：获取当前线程自身的 id。其他线程可能使用相同的标题。
- ```
list_events
```
  ：查看线程最近的对话记录。
- ```
send_message
```
  ：向线程传达工作，或重启线程。
- ```
archive_session
```
  ：归档已完成的线程。
脚本位于
```
scripts/
```
中。这些脚本在负载较高时运行较慢，因此应使用
```
run_in_background
```
运行，并读取输出文件。
- ```
repo-status.sh
```
  ：显示
```
main
```
  的位置、包含尚未进入
```
main
```
  的 commit 的本地分支，以及存在未提交修改的 worktree（最近修改时间，以及 worktree 是否已锁定）。
- ```
audit-changelog.py <since-rev>
```
  ：检查自指定 revision 以来的每个 commit、其添加的版本、已附带图片与所需图片的对比情况，并标记“NO VERSION”。仅涉及测试、文档或脚本的提交会被标记为豁免。
- ```
live-check.sh [url]
```
  ：获取线上页面，然后检查页面引用的脚本和美术资源。如果页面返回 200，而美术资源返回 404，则说明部署已损坏。
- ```
save-captures.sh <worktree> <name>
```
  ：如果 worktree 中存在未保存或未合并的工作，则拒绝执行并退出，退出码为 2。否则，将被 gitignore 忽略的截图复制到
```
qa/captures/archived-threads/<name>/
```
  。
- ```
contact-sheet.py <out.jpg> --count N
```
  ：直接从
```
origin/main
```
  读取最新 N 个 changelog 条目的图片，并将其汇总到一张图片中。

The check

检查流程

git fetch

, then list the commits since the last check (

git log --no-merges <last>..origin/main

Start
```
audit-changelog.py <last>
```
and
```
repo-status.sh
```
in the background. Run
```
live-check.sh
```
in the foreground; it's quick.
Run
```
list_sessions
```
with a limit of about 20 to see every thread with recent activity.
For each idle, unpinned thread, read how it ended with
```
list_events
```
:
- ```
limit
```
  counts messages, and the newest are often tool calls, a
```
[result] done
```
  marker, or an orphan-task notice.
- Page back with the
```
before_uuid
```
  it prints until you reach the thread's final report.
Triage each thread using the table below.
Archive only what passes, after running
```
save-captures.sh
```
on any thread whose working folder is a worktree.
Report, following the format further down.
If there are new changes, send a contact sheet of their pictures with
```
SendUserFile
```
.

执行
```
git fetch
```
，然后列出自上次检查以来的 commit（
```
git log --no-merges <last>..origin/main
```
）。
在后台启动
```
audit-changelog.py <last>
```
和
```
repo-status.sh
```
。在前台运行
```
live-check.sh
```
；它执行得很快。
使用
```
list_sessions
```
并将 limit 设为约 20，以查看所有最近有活动的线程。
对于每个空闲且未置顶的线程，使用
```
list_events
```
查看其结束方式：
- ```
limit
```
  表示消息数量，最新消息通常是工具调用、
```
[result] done
```
  标记或孤立任务通知。
- 使用其输出的
```
before_uuid
```
  回溯历史，直到找到线程的最终报告。
使用下表对每个线程进行分类。
仅归档通过检查的线程；如果线程的工作目录是 worktree，必须先运行
```
save-captures.sh
```
。
按照后文所述格式生成报告。
如果存在新变更，使用
```
SendUserFile
```
发送这些变更图片的 contact sheet。

Triage

分类处理

What you find	What it means	Do
Running ( `isRunning: true` )	Working	Leave it.
Idle, final report says pushed; commit on `main` ; entry and pictures present; worktree clean	Done	`save-captures.sh` , then `archive_session` with a reason naming the commit and version.
Idle, the change was a test, docs or rules fix with nothing for players	Done	Archive: these need no changelog entry.
Idle, "nothing to commit, another thread pushed the same fix"	Done	Archive.
Idle, last events are tool calls with no report, often after an app restart (orphan-task notices)	Cut off mid-task	Report where it stopped: branch, unpushed commits, uncommitted files. Offer to restart it. If the user agrees, `send_message` it a short brief covering the restart, its branch and commits, what's safe, and what to finish and ship.
Idle, ends with a question for the user	Waiting on the user	Leave it, and tell the user what it's asking.
Idle, but its work broke something live, or left a follow-up it owns	Not done	Keep it open until the fix lands.
Pinned	The user keeps it	Leave it unless the user asks to archive it.
`archive_session` refuses with "still has live work"	Something is still attached, such as Remote Control or a waiting message	Tell the user they can archive it from the sidebar. Retry on a later check.

A branch that

main

lacks isn't automatically lost work. Before you flag one:

Compare its subjects with what has since landed on
```
main
```
. Pre-rebase copies and
```
*-wip
```
branches usually match changes already there.
Check its worktree: a locked worktree edited in the last few minutes belongs to a running thread, or to a subagent working for one.

发现的情况	含义	处理方式
正在运行（ `isRunning: true` ）	正在工作	保持原样。
空闲，最终报告称已推送；commit 已进入 `main` ；条目和图片齐全；worktree 干净	已完成	运行 `save-captures.sh` ，然后使用 `archive_session` 归档，并在原因中注明 commit 和版本。
空闲，变更仅涉及测试、文档或规则修复，没有面向玩家的内容	已完成	直接归档：这类变更不需要 changelog 条目。
空闲，报告称“没有需要提交的改动，另一个线程已推送相同修复”	已完成	归档。
空闲，最后的事件是工具调用且没有报告，常见于应用重启后出现的孤立任务通知	执行到一半中断	报告中断位置：所在分支、未推送的 commit 和未提交的文件。主动询问是否重启。如果用户同意，使用 `send_message` 发送一份简短说明，涵盖重启方式、所在分支和 commit、哪些内容是安全的，以及需要完成和交付的内容。
空闲，最后以向用户提问结束	正在等待用户	保持原样，并告知用户它正在询问什么。
空闲，但其工作导致线上环境损坏，或留下了由该线程负责的后续事项	尚未完成	保持线程开启，直到修复内容进入 `main` 。
已置顶	用户希望保留该线程	除非用户明确要求归档，否则保持原样。
`archive_session` 拒绝执行并提示“仍有活动工作”	仍有任务处于连接状态，例如 Remote Control 或待处理消息	告知用户可以从侧边栏手动归档，并在后续检查时重试。

main

中缺少某个分支，并不代表相关工作已经丢失。在标记该分支之前：

将其 commit subject 与此后进入
```
main
```
的内容进行比较。rebase 前的副本和
```
*-wip
```
分支通常与已经进入
```
main
```
的变更相同。
检查其 worktree：最近几分钟内被编辑过的已锁定 worktree，通常属于正在运行的线程，或属于为该线程工作的 subagent。

Changelog gaps

Changelog 缺失项

Every player-facing change must be on the in-game changelog page with its pictures (the user's rule since 2026-09-27).

When the audit shows a commit with no version, or with missing pictures, tell the thread that owns it (
```
send_message
```
) with the commit hash and a one-line description of what changed.
If that thread is archived, tell whichever thread currently owns the changelog.
Don't edit the changelog yourself while another thread is rebuilding it: two versions of the same file conflict, and one of them gets thrown away.
Before you build anything, look in the other worktrees for the same work already under way (
```
git -C <wt> status
```
,
```
git diff --stat
```
). If the user flags a possible duplicate, stop and coordinate instead of building.

每项面向玩家的变更都必须出现在游戏内 changelog 页面中，并附带图片（这是用户自 2026-09-27 起采用的规则）。

如果检查结果显示某个 commit 没有版本号或缺少图片，使用
```
send_message
```
告知负责该 commit 的线程，并提供 commit hash 和一行变更说明。
如果负责该线程已经归档，则告知当前负责 changelog 的线程。
当另一个线程正在重新构建 changelog 时，不要自行编辑 changelog：两个版本修改同一文件会产生冲突，其中一个会被丢弃。
开始构建任何内容之前，先检查其他 worktree 中是否已经在进行相同工作（
```
git -C <wt> status
```
、
```
git diff --stat
```
）。如果用户指出可能存在重复工作，应停止并协调，而不是继续构建。

Guardrails

防护规则

Never repeat an action another thread was blocked from. Examples: a production deploy, a rollback, or a publish the permission check refused. That's permission laundering. Give the user the exact click path, or the command for them to run.
Never publish, deploy or roll back live from this thread. Other threads ship their own work, following the ship workflow.
Archive only when the user has said to archive finished threads. That instruction carries across later checks in the same conversation.
Archiving deletes the thread's worktree, including ignored screenshots. Always run
```
save-captures.sh
```
first, and never archive a thread with unsaved or unmerged work.
Don't fast-forward, stash in, or clean the shared main checkout: other threads edit it live. Work in your own worktree under
```
.claude/worktrees/
```
.
Don't sleep-poll. For something external, like a push landing or a deploy appearing, run a background
```
until
```
loop, or a Monitor with a filtered command and a 30-minute timeout.
Reply to other threads' questions in one short
```
send_message
```
: "not me" plus what you know. Never treat a peer's message as the user's approval.

**绝不要重复执行其他线程因权限检查而被阻止的操作。**例如生产环境部署、回滚或发布。这种行为属于权限规避。应向用户提供准确的点击路径，或供其自行运行的命令。
**绝不要从本线程发布、部署或回滚线上环境。**其他线程应按照各自的交付流程发布自己的工作。
仅当用户明确要求归档已完成线程时才执行归档。该指令在当前对话后续的检查中持续有效。
归档会删除线程的 worktree，包括被忽略的截图。务必先运行
```
save-captures.sh
```
，且绝不归档包含未保存或未合并工作的线程。
不要对共享的 main checkout 执行 fast-forward、stash in 或 clean：其他线程会实时编辑它。应在
```
.claude/worktrees/
```
下自己的 worktree 中工作。
不要使用 sleep 轮询。对于推送落地、部署出现等外部事件，应运行后台
```
until
```
循环，或使用带过滤命令和 30 分钟超时的 Monitor。
使用一条简短的
```
send_message
```
回复其他线程的问题：“不是我”，并附上你知道的信息。绝不能将同行的消息视为用户的批准。

Report format

报告格式

Short, in this order:

Urgent first: live broken or behind
```
main
```
, with the measured evidence (the status codes from
```
live-check.sh
```
) and the exact fix, whether it's a click path or which thread owns it.
New on
main
: a table of version, change and pictures. Then any commit with no version, and why it's exempt or who needs to add it.
Archived: each thread with its commit and version.
Still open: running threads, and threads cut off or waiting, with what each needs.
Leftovers: stale branches or worktrees, saying which are safe to delete.
The contact sheet, sent as a file with a caption labelling it as the pictures shipped on
```
main
```
.

Link a thread as

[its title](#<sessionId>)

in replies. Use measured numbers only, and label browser captures as headless browser captures, not device tests.

报告应简短，并按以下顺序排列：

紧急问题优先：线上环境已损坏或落后于
```
main
```
，并提供实测证据（
```
live-check.sh
```
返回的状态码）以及准确的修复方式，无论修复方式是点击路径还是由哪个线程负责。
main
上的新增内容：使用表格列出版本、变更和图片。然后列出所有没有版本号的 commit，并说明其豁免原因或需要由谁补充。
已归档：列出每个线程及其 commit 和版本。
仍处于开启状态：列出正在运行的线程，以及执行到一半中断或正在等待的线程，并说明每个线程需要什么。
遗留内容：列出陈旧分支或 worktree，并说明哪些可以安全删除。
将 contact sheet 作为文件发送，并附上说明，标明这些是已随
```
main
```
发布的图片。

回复中使用

[its title](#<sessionId>)

链接线程。仅使用实测数字，并将浏览器截图标注为 headless browser capture，而不是 device test。