name: create-handoff description: 创建交接文档以将工作转移到另一个会话

创建交接文档

你的任务是编写一个交接文档，将你的工作交给新会话中的另一个代理。你将创建一个交接文档，既要彻底，又要简洁。目标是在不丢失你所做工作的关键细节的情况下，压缩和总结你的上下文。

流程

1. 文件路径与元数据

使用以下信息来理解如何创建文档：

首先，从现有交接中确定会话名称：

ls -td thoughts/shared/handoffs/*/ 2>/dev/null | head -1 | xargs basename

这会返回最近修改的交接文件夹名称（例如，open-source-release）。使用这个作为交接文件夹名称。

如果没有交接存在，使用general作为文件夹名称。

在以下路径下创建文件： thoughts/shared/handoffs/{session-name}/YYYY-MM-DD_HH-MM_description.yaml，其中：

{session-name} 来自现有交接（例如，open-source-release），如果没有则使用general
YYYY-MM-DD 是今天的日期
HH-MM 是当前时间，24小时格式（不需要秒）
description 是一个简短的中划线分隔描述

示例：

thoughts/shared/handoffs/open-source-release/2026-01-08_16-30_memory-system-fix.yaml
thoughts/shared/handoffs/general/2026-01-08_16-30_bug-investigation.yaml

2. 编写YAML交接文档（约400个令牌 vs 约2000个标记）

关键：使用完全相同的YAML格式。不要偏离或使用替代字段名。

goal: 和 now: 字段在状态行中显示 - 它们必须被命名为这个。

---
session: {session-name from ledger}
date: YYYY-MM-DD
status: complete|partial|blocked
outcome: SUCCEEDED|PARTIAL_PLUS|PARTIAL_MINUS|FAILED
---

goal: {本会话完成的内容 - 在状态行中显示}
now: {下一个会话应首先做什么 - 在状态行中显示}
test: {验证此项工作的命令，例如，pytest tests/test_foo.py}

done_this_session:
  - task: {第一个完成的任务}
    files: [{file1.py}, {file2.py}]
  - task: {第二个完成的任务}
    files: [{file3.py}]

blockers: [{任何阻塞问题}]

questions: [{下一个会话未解决的问题}]

decisions:
  - {decision_name}: {理由}

findings:
  - {关键发现}: {细节}

worked: [{有效的方法}]
failed: [{失败的方法及原因}]

next:
  - {第一步}
  - {第二步}

files:
  created: [{新文件}]
  modified: [{修改过的文件}]

字段指南：

goal: + now: - 必填，在状态行中显示
done_this_session: - 完成的内容，包括文件引用
decisions: - 重要选择和理由
findings: - 关键学习
worked: / failed: - 重复的内容与避免的内容
next: - 下一个会话的行动项

不要使用替代字段名，如 `session_goal`、`objective`、`focus`、`current` 等。状态行解析器查找完全相同的 `goal:` 和 `now:` - 其他都不行。

3. 标记会话结果（必填）

重要： 在响应用户之前，你必须询问会话结果。

使用AskUserQuestion工具，这些确切的选项：

问题: "这个会话进展如何？"
选项:
  - SUCCEEDED: 任务成功完成
  - PARTIAL_PLUS: 基本完成，仍有小问题
  - PARTIAL_MINUS: 有一些进展，仍有重大问题
  - FAILED: 任务被放弃或阻塞

用户响应后，索引并标记结果：

# 标记最近的交接（适用于PostgreSQL或SQLite）
# 使用git根目录找到项目，然后opc/scripts/core/
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-.}")

# 首先，将交接索引到数据库中
cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_index.py --file thoughts/shared/handoffs/{session_name}/{filename}.yaml

# 然后标记结果
cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_mark.py --latest --outcome <用户选择>

重要： 将 {session_name} 和 {filename} 替换为步骤1中的实际值。

这些命令自动检测数据库（PostgreSQL如果配置，SQLite回退）。

注意： 如果索引失败，标记步骤将显示“数据库标记不可用” - 对于第一次交接是可接受的，但表明索引步骤被跳过。

4. 确认完成

标记结果后，响应用户：

交接已创建！结果标记为 [结果]。

在新会话中恢复：
/resume_handoff path/to/handoff.yaml

额外笔记与指令

信息多而非少。这是定义交接最小要求的指南。始终如有必要，包括更多信息。
要彻底和精确。包括高层目标和必要时的低层细节。
避免过多的代码片段。虽然描述关键更改的简要片段很重要，但避免大代码块或差异；除非必要（例如，与调试的错误相关），否则不要包含。偏好使用 /path/to/file.ext:line 引用，代理可以稍后跟进，例如 packages/dashboard/src/app/dashboard/page.tsx:12-24