用途
Worker Handover 定义了当工作者（worker）接近回合上限（100 回合）时所需的上下文交接格式。其目标是让接替的新工作者能够无损地继续原有工作。核心原则是：接替者应当像原工作者一样理解这项工作。
开始时需声明：“我正接近回合上限。正在为接替工作者创建交接。”
状态管理
关键点：交接上下文存储在 GitHub issue 评论中，不使用本地交接文件。
- 交接上下文：Issue 评论，用于为接替工作者提供完整上下文
- Git 变更：分支提交，记录目前已完成的工作
- 测试状态：Issue 评论，记录当前测试状态
由于交接保存在 GitHub 而非本地文件中，因此能够从崩溃中恢复。
何时交接
- 85+ 回合：评估是否需要交接
- 90+ 回合：开始准备交接
- 95+ 回合：完成交接，准备退出
- 100 回合：退出（自动）
交接格式
使用结构化标记发布到 issue：
<!-- HANDOVER:START -->
# Handover: Issue #[ISSUE]
## Metadata
| Field | Value |
|-------|-------|
| Issue | #[ISSUE] |
| Previous Worker | [WORKER_ID] |
| Turns Used | [N]/100 |
| Timestamp | [ISO_TIMESTAMP] |
| Orchestration | [ORCHESTRATION_ID] |
| Attempt | [N] |
## Issue Summary
[Concise summary of what the issue requires - in your own words, not copied]
## Current State
### Branch Status
- **Branch:** `[BRANCH_NAME]`
- **Commits:** [N] commits ahead of main
- **Last Commit:** `[COMMIT_HASH]` - [COMMIT_MESSAGE]
### Files Modified
[List of modified files with brief description of changes]
### Tests Status
- **Passing:** [N]
- **Failing:** [N]
- **Coverage:** [X]%
## Work Completed
### Done
- [x] [Completed task 1]
- [x] [Completed task 2]
### In Progress
- [ ] [Current task - describe state]
### Remaining
- [ ] [Remaining task 1]
- [ ] [Remaining task 2]
## Context & Decisions
### Key Decisions Made
1. **[Decision]:** [Why this choice was made]
2. **[Decision]:** [Why this choice was made]
### Approaches Tried
1. **[Approach]:** [Result/Why abandoned]
### Important Discoveries
- [Discovery that affects implementation]
## Technical Notes
### Architecture Notes
[Any architectural decisions or patterns being used]
### Gotchas
- [Thing that might trip up the next worker]
- [Non-obvious behavior discovered]
## Current Blocker (if any)
[Description of what's blocking progress, if anything]
## Recommended Next Steps
1. [Specific next action to take]
2. [Following action]
3. [Following action]
## Files to Review First
1. `[path/to/key/file.ts]` - [Why it's important]
2. `[path/to/key/file.ts]` - [Why it's important]
## Commands to Run
```bash
# Verify current state
pnpm test
# Continue development
[specific commands]
Handover created by [WORKER_ID] at [TIMESTAMP]
<!-- HANDOVER:END -->
## 创建交接
### 第一步：评估状态
```bash
# Check git status
git status
git log --oneline -10
# Check test status
pnpm test 2>&1 | tail -20
# Count modified files
git diff --name-only HEAD~[N]
第二步：将交接发布到 Issue
ISSUE=123
WORKER_ID="worker-1234567890-123"
BRANCH=$(git branch --show-current)
LAST_COMMIT=$(git log -1 --format='%h - %s')
COMMITS_AHEAD=$(git rev-list --count main..HEAD)
gh issue comment "$ISSUE" --body "<!-- HANDOVER:START -->
# Handover: Issue #$ISSUE
## Metadata
| Field | Value |
|-------|-------|
| Issue | #$ISSUE |
| Previous Worker | $WORKER_ID |
| Turns Used | 94/100 |
| Timestamp | $(date -u +%Y-%m-%dT%H:%M:%SZ) |
| Orchestration | $ORCHESTRATION_ID |
## Current State
### Branch Status
- **Branch:** \`$BRANCH\`
- **Commits:** $COMMITS_AHEAD commits ahead of main
- **Last Commit:** \`$LAST_COMMIT\`
[... rest of handover content ...]
<!-- HANDOVER:END -->"
第三步：提交所有未提交的工作
git add -A
git commit -m "chore: Save progress before handover
Worker $WORKER_ID reached turn limit.
Handover posted to issue #$ISSUE.
Orchestrator: $ORCHESTRATION_ID"
第四步：优雅退出
工作者在发布交接后退出。编排器将启动接替工作者。
接收交接
当接替工作者启动时，会从 issue 评论中读取交接内容：
第一步：从 GitHub 读取交接
ISSUE=123
# Get latest handover from issue comments
HANDOVER=$(gh api "/repos/$OWNER/$REPO/issues/$ISSUE/comments" \
--jq '[.[] | select(.body | contains("<!-- HANDOVER:START -->"))] | last | .body')
echo "$HANDOVER"
第二步：验证状态
# Verify branch
git branch --show-current
# Check current state matches handover
git status
git log --oneline -5
# Run tests
pnpm test
第三步：确认接收
向 issue 发布确认：
**Handover Received**
**Replacement Worker:** [NEW_WORKER_ID]
**Continuing from:** [PREVIOUS_WORKER_ID]
**Attempt:** [N]
**Handover verified:**
- [x] Branch state matches
- [x] Tests status matches
- [x] Context understood
**Continuing with:**
[First task from "Recommended Next Steps"]
---
*Orchestration: [ORCHESTRATION_ID]*
第四步：继续工作
遵循交接中的“建议的下一步”执行。
交接质量检查清单
创建交接前：
- [ ] 所有本地变更已提交
- [ ] 交接准确反映当前状态
- [ ] 关键决策已记录
- [ ] 注意事项（Gotchas）已说明
- [ ] 下一步具体且可执行
- [ ] 需审查文件已按优先级列出
- [ ] 需运行的命令已测试且正确
- [ ] 交接已发布到 issue 评论
- [ ] 工作已提交到分支
差劲的交接示例
过于笼统：
## Work Completed
- Did some stuff
- Made progress
## Next Steps
- Finish the feature
缺少上下文：
## Work Completed
- [x] Implemented the thing
## Next Steps
- Fix the tests
（未说明测试为何失败）
优秀的交接示例
参见上文完整格式，其中包含：具体的提交引用、测试失败详情、带理由的决策、发现的注意事项、可执行的下一步、文件优先级列表、已验证的命令。
集成
本技能被以下对象使用：
- worker-protocol - 触发交接创建
- worker-dispatch - 将交接提供给接替工作者
本技能使用：
- GitHub issue 评论用于存储交接
- Git 用于状态验证