项目定位与目标

handoff-mcp 是一个基于 Model Context Protocol (MCP) 协议的服务器端工具，专门为 AI 编码会话（coding session）提供"上下文交接"能力。其核心目标是解决 LLM 驱动开发中常见的"会话中断即上下文丢失"问题：当一次 AI 会话因为上下文窗口耗尽、用户切换、或断电等意外中断时，开发者往往难以快速恢复到原先的工作状态。该项目通过结构化的项目状态、任务与会话记录，让"接力"成为可审计、可恢复的工程实践。

资料来源：README.md:1-40

从功能边界看，handoff-mcp 涵盖三大能力面：

• 会话上下文管理：开始/结束会话时记录 summary、decisions、blockers、handoff_notes、context_pointers 等结构化字段；
• 任务追踪：在 .handoff/ 目录下管理任务、依赖、里程碑、工时与排期；
• 跨项目协作（Referrals）：在多个独立项目之间发送结构化的"转介单"（bug、improvement、request、info），并跟踪其处理状态。

资料来源：README.md:20-80, src/mcp/handlers/refer.rs:1-40

系统架构总览

整个项目以 MCP 服务器的形式运行，对外暴露一组标准化的 tools/* 接口，对内通过文件系统持久化每个项目根目录下的 .handoff/ 数据。

flowchart LR
    Client[AI 客户端 / Agent] -->|JSON-RPC| MCPServer[handoff-mcp Server]
    MCPServer --> Router[src/mcp/router.rs]
    Router --> Handlers[handlers/*]
    Handlers --> Storage[src/storage/*]
    Handlers --> Git[Git CLI 集成]
    Storage --> DotHandoff[".handoff/<br/>config.toml / tasks / sessions / referrals"]
    MCPServer -.暴露.-> Tools[handoff_* 工具集]
    Tools --> Skills[skills/handoff-*<br/>SKILL.md]

关键模块构成：

资料来源：src/mcp/mod.rs:1-6, src/storage/config.rs:1-30

工具与协议层

MCP 工具通过 JSON Schema 严格约束入参，是服务器对外的"契约"层。src/mcp/tools.rs 中集中声明了所有可用工具，例如：

• handoff_init：初始化项目，生成 .handoff/config.toml；
• handoff_load_context：读取当前项目上下文（含 paused_sessions、session_guidance、任务列表等）；
• handoff_save_context：在会话结束或中断时持久化 summary / decisions / blockers / handoff_notes / references / context_pointers / environment；
• handoff_list_tasks / handoff_update_task：任务状态机推进；
• handoff_refer / handoff_list_referrals / handoff_update_referral：跨项目转介。

资料来源：src/mcp/tools.rs:1-80, src/mcp/handlers/refer.rs:1-40

session_guidance 字段是 0.11.0 之后的关键设计：若当前没有活跃会话，服务器会通过 session_guidance.suggested_fields 把前一会话的可继承字段（summary、decisions、context_pointers 等）原样返回，强制客户端在写入新会话时保留上下文血统。资料来源：CHANGELOG.md:1-20, skills/handoff/SKILL.md:15-30

技能系统与典型工作流

为了让 AI 客户端在不阅读源代码的情况下也能正确使用工具，项目在 skills/ 目录下发布了一组"剧本式"技能描述文件：

• skills/handoff/SKILL.md：主流程，定义会话开始 → 工作中 → 会话结束的标准剧本；
• skills/handoff-load/SKILL.md：轻量级"只读恢复"流程，专注于 handoff_load_context 与状态摘要；
• skills/handoff-import/SKILL.md：将外部文档（Markdown / JSON / 文本）解析为结构化任务与上下文；
• skills/handoff-refer/SKILL.md：跨项目转介的提交流程，强调 details / tasks / priority 必填并校验完整性。

资料来源：skills/handoff/SKILL.md:1-30, skills/handoff-load/SKILL.md:1-10, skills/handoff-import/SKILL.md:1-20, skills/handoff-refer/SKILL.md:1-15

一个最小化的"接力"闭环工作流如下：

1. 开始：调用 handoff_load_context → 若有 paused_sessions 则提示用户恢复 → 写入 session_status: "active" 的新会话；
2. 工作中：用 handoff_update_task 推进任务状态（todo → in_progress → done），并将非结构化想法通过 handoff_notes 记录为 caution / context / suggestion；
3. 结束：调用 handoff_save_context，至少包含一条 suggestion handoff_note（服务器会校验）并附 checklist，方便下一次会话直接执行。

资料来源：skills/handoff/SKILL.md:25-60

配置与数据模型

项目级配置统一存放在 .handoff/config.toml，由 src/storage/config.rs 中的强类型结构体解析，包括：

• [project]：项目名与描述；
• [settings]：history_limit、done_task_limit、auto_git_summary、context_files、custom_fields；
• [dashboard]：跨项目仪表盘扫描目录与排除规则；
• [calendar] / [calendar.day_hours]：工作时间、休息日、schedule_mode（auto/manual）、overwork_limit_percent；
• [assignees.*]：成员花名册与个人工时/休息日；
• [milestones.*]：里程碑；
• [effort_budget] / [gantt_view]：总工数上限与甘特图渲染偏好。

资料来源：src/storage/config.rs:15-70, README.md:60-100

0.11.0 版本实现了 GUI-MCP 严格对齐：VSCode GUI 写入的每个字段都对应一个 serde(default) 的 Rust 字段，且配置更新通过 handoff_update_config 的点号路径（如 "calendar.work_hours_per_day"）进行局部修改，从而保证 GUI 与 MCP 双向写入的崩溃安全。资料来源：CHANGELOG.md:1-25

See Also

• 任务与会话生命周期管理
• 跨项目转介（Referrals）协议
• 配置参考（.handoff/config.toml）
• MCP 工具清单与参数约定

概述

handoff-mcp 是一款通过 Model Context Protocol（MCP）运行的服务器，为 AI 编码代理提供跨会话的持久化内存能力。它采用 stdio 传输方式与客户端通信（package.json 中声明 "type": "stdio"），并以本地 .handoff/ 目录作为后端存储，使任务状态、决策与上下文在会话中断后仍可恢复 资料来源：package.json:1-15。

服务器在 src/mcp/router.rs 的 ServerInfo.instructions 中向客户端注入操作指引：要求代理在会话开始调用 handoff_load_context、在会话结束调用 handoff_save_context，并在进行中通过 handoff_update_task、handoff_check_criterion、handoff_update_session 等工具做渐进式更新 资料来源：src/mcp/router.rs。

MCP 工具分类参考

所有工具的定义集中在 src/mcp/tools.rs，使用 JSON Schema 描述入参。下表按类别汇总主要工具及其职责：

handoff_save_context 的入参定义了 summary、decisions、blockers、checklist、handoff_notes、context_pointers、environment 等结构化字段；其中 handoff_notes 至少要包含一条 category: "suggestion"，否则服务器会发出警告 资料来源：src/mcp/tools.rs。handoff_update_referral 则将推荐状态机限制为 open → acknowledged → resolved 三态枚举，避免非法跃迁 资料来源：src/mcp/tools.rs。

标准工作流

skills/handoff/SKILL.md 描述了代理应遵循的三段式工作流：

1. 会话开始：调用 handoff_load_context（无参，默认使用当前工作目录）；若返回 session_guidance，先用 handoff_save_context(session_status: "active") 建立持久会话；previous_session.handoff_notes 中 suggestion 字段是上一次的推荐下一步，代理应从第一条开始执行，避免重复验证已完成的工作 资料来源：skills/handoff/SKILL.md。若返回 not_initialized，skills/handoff-load/SKILL.md 会基于当前目录名推测项目名并自动调用 handoff_init 完成初始化 资料来源：skills/handoff-load/SKILL.md。
2. 进行中：以渐进方式调用 handoff_update_task（状态从 todo → in_progress → done），并通过 handoff_check_criterion 逐条勾选完成条件；当需要用户确认时将任务状态置为 review；同时调用 handoff_update_session 持续追加决策、备注和上下文指针 资料来源：skills/handoff/SKILL.md。skills/handoff-import/SKILL.md 进一步给出从非结构化文档抽取任务与决策字段的指导 资料来源：skills/handoff-import/SKILL.md。
3. 会话结束：再次调用 handoff_save_context 关闭活动会话，写入 summary、decisions、blockers、checklist 等字段；handoff_notes 至少包含一条 suggestion 明确下次该做什么 资料来源：src/mcp/router.rs。README.md 提示用户将 .handoff/ 加入 .gitignore，因为它保存的是本地工作状态而非代码 资料来源：README.md。

配置与会话状态

.handoff/config.toml 的所有节均被建模为带 #[serde(default)] 的强类型结构（CalendarConfig、MilestoneConfig、GanttViewConfig、EffortBudgetConfig 等），便于通过 MCP 工具读写并保持向后兼容 资料来源：src/storage/config.rs。CHANGELOG.md 显示 0.11.0 版本实现了与 handoff-vscode 扩展的 GUI-MCP 对等：每一节都有专属的 MCP CRUD 工具，写入具备崩溃安全特性 资料来源：CHANGELOG.md。

会话生命周期支持 active、paused、closed 三态：paused 状态可被 handoff_load_context(session_id) 恢复为 active，也可通过 handoff_save_context(close_session_id) 直接关闭 资料来源：skills/handoff-load/SKILL.md。

跨项目推荐 referral 由 src/mcp/handlers/refer.rs 中的发送函数实现：源项目在 target/.handoff/referrals/ 目录写入 ReferralData（含 id、source_project_dir、referral_type、summary、details、tasks、context 等字段），并在缺少 details 时打印警告，提示目标项目无法得知具体动作 资料来源：src/mcp/handlers/refer.rs。

另见

• README.md — 完整配置示例与工具一览
• CHANGELOG.md — 版本演进历史
• skills/handoff-import/SKILL.md — 历史 handoff 文档批量导入规范

概述

handoff-mcp 是一个基于 Model Context Protocol（MCP）的会话与任务管理系统，其持久化层采用"项目根目录下的 .handoff/ 文件夹 + TOML/JSON 文件"的纯文件方案。该方案由 src/storage/ 下的若干子模块负责读写，覆盖配置、任务、会话、Git 状态与跨项目 referrals 五大实体。运行时 MCP 工具（如 handoff_save_context、handoff_update_task、handoff_send_referral）直接调用这些存储模块完成 CRUD 资料来源：README.md 与 src/mcp/handlers/refer.rs。

持久化目录结构

所有数据落在被管理项目根目录下的 .handoff/ 子目录中。handoff_init 工具负责创建该目录骨架；handoff_send_referral 会额外在目标项目的 .handoff/referrals/ 下写入 ReferralData 资料来源：src/mcp/handlers/refer.rs。典型布局如下：

graph TD
    A[project root] --> B[.handoff/]
    B --> C[config.toml]
    B --> D[tasks/<id>.json]
    B --> E[sessions/<id>.json]
    B --> F[git_state.json]
    B --> G[referrals/<id>.json]

各文件的写入时机不同：配置只在 handoff_init / handoff_update_config / 各类 update_* 工具调用时改写；任务与会话在每次状态变更时立即落盘，以保证"会话被中断后状态可恢复"。handoff_save_context 会将当前 summary、decisions、blockers、checklist、handoff_notes、references、context_pointers、environment 整体序列化进 sessions/<session_id>.json，并可由 close_session_id 字段触发将活跃会话转为 closed 状态资料来源：src/mcp/tools.rs。

配置模型（`config.toml`）

src/storage/config.rs 中的 Config 是顶层聚合结构，其子结构均使用 #[serde(default)]，从而保证旧版配置文件在升级后仍可被反序列化资料来源：src/storage/config.rs 与 CHANGELOG.md。核心字段说明如下：

所有配置段都可以通过 handoff_update_config 之类的工具以点号键名（如 calendar.work_hours_per_day）原地更新，无需整体重写文件资料来源：README.md。

任务与会话数据模型

任务与会话是持久化层最重要的两类实体。任务由 src/storage/tasks.rs 负责，典型字段包括：id、title、status（todo / in_progress / blocked / review / done / skipped）、priority（low / medium / high）、schedule 子结构（start_date / due_date / estimate_hours / actual_hours / remaining_hours / milestone / pinned）以及 dependencies（其他任务 ID 列表，循环依赖会在写入时被拒绝）资料来源：README.md 与 src/mcp/tools.rs。

会话由 src/storage/sessions.rs 管理，其内容是嵌套式的 summary + 结构化载荷：

• decisions[] — 每条包含 decision、reason、confidence（confirmed / estimated / unverified）。
• blockers[] — 字符串数组，描述阻碍项。
• checklist[] — 每项含 item、checked、owner（user / ai），用于在交接时确认验证步骤。
• handoff_notes[] — 至少需包含一条 category: suggestion；另支持 caution 与 context。服务器在 checklist 留有未勾选项或缺少 suggestion 时会主动警告资料来源：skills/handoff/SKILL.md。
• references[] — {label, uri, type, notes}，type 取值限定为 file / issue / mr / wiki / doc / url。
• context_pointers[] — {path, reason, lines}，指向下一会话应优先打开的文件与行号。

当新会话启动并通过 handoff_load_context 检测到上一会话时，可使用 session_guidance.suggested_fields 携带的建议字段快速建立新会话，确保在中断时已写入的 decisions、references、context_pointers 不丢失资料来源：skills/handoff/SKILL.md。

Git 状态与跨项目 Referrals

src/storage/git.rs 负责在 auto_git_summary = true 时自动捕获当前分支、最近提交与脏文件，作为 sessions/*.json 的附属上下文写入。这使下一会话在加载时能直接看到提交 SHA，而无需重新执行 git log 资料来源：src/storage/config.rs 与 README.md。

src/storage/referrals.rs 处理项目间协作：发起方调用 handoff_send_referral，服务器在目标项目 .handoff/referrals/<id>.json 中写入 ReferralData（含 source_project、source_project_dir、created_at、referral_type、summary、details、priority、tasks[]、context），并在响应中回填警告——例如缺少 details 或 tasks[*].done_criteria 时，会提示对方"无法知道要做什么"资料来源：src/mcp/handlers/refer.rs。接收方通过 handoff_list_referrals / handoff_update_referral 把状态从 open 推进到 acknowledged，最终到 resolved 资料来源：src/mcp/tools.rs。

写入策略与常见失败模式

整体写入策略遵循"小文件 + 即时落盘"原则：每次 MCP 工具调用都会触发对应 src/storage/ 模块的 write_* 函数，将变更以原子方式写入对应 JSON/TOML 文件。常见的失败与处理方式包括：

• 配置缺字段：Config 全部子结构使用 #[serde(default)]，升级 v0.11.0 后旧 config.toml 仍可读取，新增的 started_at / schedule_mode / labels / calendar / assignees / milestones / gantt_view / effort_budget 默认为空资料来源：CHANGELOG.md 与 src/storage/config.rs。
• 会话缺少 suggestion：服务器警告并拒绝保存空 note 集合，确保下一会话始终有可执行建议资料来源：skills/handoff/SKILL.md。
• Referral 缺少 details / done_criteria：服务器返回 Warning: No details...，要求发起方补全后再发送资料来源：src/mcp/handlers/refer.rs。
• 任务循环依赖：写入时检测 dependencies，构成环则拒绝落盘，避免调度死锁资料来源：README.md。

See Also

• 会话生命周期与会话切换
• MCP 工具总览
• Skill 与命令参考
• Referrals 跨项目协作

1. 配置体系（`.handoff/config.toml`）

handoff-mcp 的所有项目级配置都集中在 .handoff/config.toml，由 Config 结构统一建模；新增字段均标记为 serde(default)，因此旧配置文件可在不破坏兼容性的前提下平滑升级 资料来源：src/storage/config.rs:1-40。

1.1 主要配置节

1.2 动态更新

任意配置节都可以通过 handoff_update_config 以点号键（如 "calendar.work_hours_per_day"）原地修改，避免直接编辑 config.toml 时与服务端内存状态失同步 资料来源：README.md:140-180。

2. 技能文件体系

技能文件位于 skills/<name>/SKILL.md，为 AI 代理提供场景化工作流模板。

2.1 主技能 `handoff`

覆盖会话的全生命周期：

• 会话开始：调用 handoff_load_context；若返回 not_initialized，立即调用 handoff_init；若存在 paused_sessions，向用户展示 ID/summary/branch；遇到 session_guidance 时必须先调用 handoff_save_context(session_status: "active") 建立活跃会话，否则中断后上下文会丢失 资料来源：skills/handoff/SKILL.md:1-60。
• 任务管理：启动任务时通过 handoff_update_task 将状态置为 in_progress。
• 会话结束：handoff_save_context 必须包含 summary、decisions、blockers、checklist、handoff_notes，且 handoff_notes 中至少要有一条 suggestion，否则服务端会发出警告 资料来源：src/mcp/tools.rs:40-120、skills/handoff/SKILL.md:60-130。

2.2 加载技能 `handoff-load`

面向“恢复工作”场景：以无参形式调用 handoff_load_context，依次处理 not_initialized→初始化、paused_sessions→恢复或丢弃、session_guidance→继承上次会话；任务展示优先级为 blocked → in_progress → todo，并强调工数、逾期与 unverified 决策 资料来源：skills/handoff-load/SKILL.md:1-50。

2.3 导入技能 `handoff-import`

把既有 Markdown/JSON/自由文本转为结构化数据，一次性调用 handoff_import_context：

• 按扩展名自动识别 format（.md→markdown、.json→json、.txt→text、其他→other）资料来源：skills/handoff-import/SKILL.md:30-70。
• 关键词驱动优先级推断：must/blocker/urgent→high，should/improve→medium，could/nice to have→low，歧义默认 medium 资料来源：skills/handoff-import/SKILL.md:1-30。
• 把模糊验收描述拆为可独立验证的 done_criteria 列表，覆盖实现、自动检查与真实运行验证三层。
• 无法结构化的内容回落到 raw_notes，永不丢失信息；同时要求 references 始终引用源文件 资料来源：skills/handoff-import/SKILL.md:70-120。

2.4 转发技能 `handoff-refer`

跨项目协作：handoff_refer_project 把任务、上下文、引用发送给目标项目；目标可通过名称（target_project，由 scan_dirs 解析）或路径（target_project_dir）指定。校验环节会针对缺失 details/tasks/context/priority，以及任务缺少 done_criteria 发出警告 资料来源：src/mcp/handlers/refer.rs:1-60、skills/handoff-refer/SKILL.md:1-60。收到方使用 handoff_update_referral 在 open → acknowledged → resolved 三态间推进 资料来源：src/mcp/tools.rs:120-180。

3. 部署与运维

3.1 MCP 服务器形态

handoff-mcp 以 stdio JSON-RPC 暴露工具集；客户端首先调用 handoff_init 在目标目录创建 .handoff/，所有后续读写都围绕该目录展开 资料来源：src/mcp/tools.rs:1-40。

3.2 数据持久化与一致性

v0.11.0（2026-06-24）以“GUI-MCP parity”为主线，把 GUI 所写的每一个 config.toml 节升级为强类型 Config 模型，并配套专用 CRUD 工具（handoff_add_assignee、handoff_update_milestone、handoff_remove_assignee、handoff_update_calendar、handoff_update_labels、handoff_start_project 等），同时保证写操作 crash-safe（崩溃安全）资料来源：CHANGELOG.md:1-30。handoff_auto_schedule 还会把已应用的排程变更以 decision 形式记录到当前会话，便于追溯 资料来源：CHANGELOG.md:30-50。

3.3 多项目巡检

handoff_dashboard 配合 [dashboard].scan_dirs 列出多项目摘要，可直接作为运维巡检视图：

## my-project (3 tasks)
  - [in_progress] Implement auth (high)
  - [todo] Add tests (medium)
  - [blocked] Deploy staging (medium)

资料来源：README.md:40-80。

4. See Also

• MCP 工具与接口
• 会话与任务模型
• 跨项目转发与协作

Pitfall Log / 踩坑日志

项目：alphaelements/handoff-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/alphaelements/handoff-mcp | host_targets=mcp_host, claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/alphaelements/handoff-mcp | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/alphaelements/handoff-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/alphaelements/handoff-mcp | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/alphaelements/handoff-mcp | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/alphaelements/handoff-mcp | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/alphaelements/handoff-mcp | release_recency=unknown