61 lines
4.4 KiB
Markdown
61 lines
4.4 KiB
Markdown
---
|
|
name: handoff
|
|
description: 基于当前任务和项目证据生成可持续更新的本地或共享交接文档，并输出新任务接续提示词。适用于任务暂停、切换会话或交接给他人；普通总结、长期知识库维护或自动提交不应触发本 Skill。
|
|
---
|
|
|
|
# 任务交接
|
|
|
|
把当前任务的真实状态写入 `.craftkit/`，并输出一段可复制到新任务的接续提示词。交接只记录有证据的事实；未知、未测试或未确认的内容必须明确标记。
|
|
|
|
## 选择可见性
|
|
|
|
执行前确认交接范围、下一步目标和可见性：
|
|
|
|
- 本地交接是默认选项，写入 `.craftkit/local/handoff/current.md`，不进入 Git。
|
|
- 共享交接只有用户明确选择时使用，写入 `.craftkit/handoff/current.md`，可以作为项目资产提交。
|
|
- 已有目标文件时先读取并更新，不因切换可见性自动移动或复制另一侧文件。
|
|
|
|
## 初始化项目目录
|
|
|
|
首次使用时，只创建 [目录说明模板](assets/craftkit-readme.md) 对应的 `.craftkit/README.md` 和 [排除规则模板](assets/craftkit-gitignore) 对应的 `.craftkit/.gitignore`，以及本次实际需要的交接目录。
|
|
|
|
在 Git 仓库中执行以下检查：
|
|
|
|
1. 使用 `git check-ignore --no-index -v .craftkit/README.md` 和 `.craftkit/.gitignore` 检查整个目录是否被项目规则、全局规则或 `.git/info/exclude` 错误排除。发现宽泛排除时停止并说明规则来源，不自动删除用户规则。
|
|
2. 使用 `git ls-files -- .craftkit/local .craftkit/cache` 检查本地目录是否已经被跟踪。存在结果时停止本地写入并提示隐私风险，不自动修改索引。
|
|
3. 初始化或修正 `.craftkit/.gitignore` 前展示内容并取得确认。规则只排除 `/local/` 和 `/cache/`，不得排除父目录。
|
|
4. 初始化后使用 `git check-ignore --no-index -v .craftkit/local/handoff/current.md` 验证本地路径被排除；再检查 `.craftkit/README.md` 未被忽略。
|
|
|
|
非 Git 目录也可以使用相同结构，但应说明没有 Git 机制区分共享与本地内容。
|
|
|
|
## 收集交接证据
|
|
|
|
- 确认本次交接的任务范围、当前状态和下一步目标；下一步不明确时向用户确认，不自行推断。
|
|
- 读取项目内适用的 `AGENTS.md`、`.craftkit/README.md`、相关设计或说明文档，以及本次可见性对应的已有交接文件。
|
|
- 在 Git 仓库中只读检查 `git status --short --branch`、必要的 `git diff --stat`、`git diff --cached --stat` 和与本任务相关的 `git log`。
|
|
- 只把实际执行过的测试和观察到的结果写入“验证”；没有运行的验证写为“未验证”，不以静态检查代替运行结果。
|
|
- 避免记录凭据、令牌、私钥、个人信息和不必要的内部地址。引用项目文件时优先使用相对路径。
|
|
|
|
## 生成和更新文档
|
|
|
|
按 [交接模板](assets/handoff-template.md) 生成文档。目标文件不存在时创建；已存在时先完整读取，再按章节更新：
|
|
|
|
- 保留无法确认用途的既有章节和用户内容。
|
|
- 合并重复待办，删除已完成项前必须有当前证据。
|
|
- 被新证据推翻的旧结论应改写并说明依据，不保留互相矛盾的活跃结论。
|
|
- 不整文件覆盖，不自动建立历史归档。只有用户明确要求保留历史时，才在当前可见性对应的 `handoff/history/` 创建带日期的副本。
|
|
- 写入后重新读取关键章节，并运行 `git status --short --ignored`。本地交接必须处于 ignored 状态；共享交接应作为普通项目文件可见。
|
|
|
|
## 接续提示词
|
|
|
|
文档完成后直接输出一段简短提示词，至少包含：
|
|
|
|
1. 先读取本次实际交接路径和其中明确引用的项目文件。
|
|
2. 复述任务目标、已完成内容、限制、风险和待办。
|
|
3. 给出下一步计划，并在发生写入或外部操作前遵循项目授权约定。
|
|
4. 内联最多三条最容易重复踩到的风险；其余内容留在交接文档中。
|
|
|
|
最后报告写入路径、可见性和主要更新，不执行 `git add`、`git commit` 或 `git push`。共享交接可由用户后续确认提交；本地交接不得交给其他 Git Skill 提交。
|
|
|
|
任务暂停时，若存在 `workRoot/<task>/task.json`，将状态更新为 `paused` 并记录交接路径；恢复任务时改回 `active`。任务已经完成且不需要接续时不生成新的交接文档，改用 `knowledge:document-output close` 生成关闭预览。
|