TaskHandoff

DeepSeek-friendly long-task project memory & cross-session handoff for coding agents.

长任务做到一半换会话 / 上下文被压掉 / 换模型 —— Agent 忘了目标、决策和下一步。
TaskHandoff 把状态写进仓库 .handoff/：任何能读项目文件的 Harness 都能恢复任务状态，并拿到结构化的下一步上下文。
「能恢复」有自动化测试证据；「LLM 一定把活干完」仍需 harness 级评测。

Repo	https://github.com/sutongwuyanzu/TaskHandoff
Skill name	task-handoff
CLI	handoff（pip install -e . 后）
MCP	handoff-mcp（纯 stdlib，无额外依赖）见 references/mcp.md
Harness	Skill + CLI + MCP 同一 .handoff/ 契约；DSH 适配计划见 references/deepseek-notes.md

init → save --auto → recall --brief → doctor
怎么录 / 怎么重渲：examples/how-to-record-gif.md

Continuity evidence（跨会话可恢复）

命令 / 材料	角色
pytest tests/test_continuity.py -q	完整 CI 证据（hooks 闭环、save --auto、brief→完成 next#1 toy、强断言）
python scripts/continuity_proof.py	约 15 秒 smoke demo（显式 save → recall only；不覆盖 hooks/--auto/toy）
examples/dogfood-20260813.md	真人跨会话：Session A save --auto → 关聊天 → Session B 只 recall --brief

# Full evidence (what CI runs via pytest -q):
pytest tests/test_continuity.py -q

# Quick human-readable smoke (not a substitute for the suite):
python scripts/continuity_proof.py

The suite proves disk-level continuity across independent processes.
LLM execution quality still requires harness-level evaluation.
Details: examples/continuity-proof.md

---

30 秒心智模型

会话 A 干到一半  →  handoff save [--auto]  →  写入 .handoff/
新开会话 / 换模型 →  handoff recall --brief →  恢复 goal + next 1..3
                         （Agent 可据此继续；执行成败取决于模型/harness）

文件	作用
.handoff/MEMORY.md	长期记忆（偏好、架构、坑）
.handoff/handoffs/LATEST.md	上一会话状态 + 下一步 3 条
.handoff/todos.json / decisions.jsonl	结构化待办与决策日志

---

安装（推荐最低完整版）

需要 Python 3.9+，零第三方运行时依赖。

git clone https://github.com/sutongwuyanzu/TaskHandoff.git
cd TaskHandoff
pip install -e .

# 验证
handoff --version
# 或
python -m taskhandoff --version

MCP（stdio，零额外依赖）

pip install -e .
handoff-mcp
# 或
python -m taskhandoff.mcp_server

把 stdio server 配进 Claude Desktop / Cursor 等（示例：examples/mcp-config.sample.json，说明：references/mcp.md）。

不装包也可以用 CLI：

python scripts/handoff_cli.py init --root /path/to/project

装成 Agent Skill

# 一键脚本（推荐）— 在仓库根目录执行
# Windows PowerShell:
powershell -ExecutionPolicy Bypass -File scripts/install-skill.ps1

# macOS / Linux:
bash scripts/install-skill.sh

# 或手动
cp -r TaskHandoff ~/.claude/skills/task-handoff

装好后对 Agent 说：交接 / 接着做 / handoff。
SKILL.md 是剧本；handoff CLI / MCP 是执行层。

---

快速演示：init → save → recall

在任意项目里：

cd /path/to/your-app

# 1) 初始化（每个仓库一次）
handoff init --root .

# 2) 会话结束前交接（推荐 --auto：自动带上 git 变更/最近 commit）
handoff save --root . --auto \
  --goal "Ship JWT auth" \
  --done "Middleware scaffolded" \
  --decision "Refresh token in httpOnly cookie" \
  --next "Finish refresh endpoint" \
  --next "Add 401/403 tests" \
  --next "Document env vars" \
  --memory-delta "Auth: access token memory-only; refresh httpOnly cookie"

# 3) 新会话只读 brief（短、稳、给 Agent 直接开干）
handoff recall --root . --brief

# 4) 需要全文时
handoff recall --root . --budget 2500

…