# https://github.com/alphaelements/handoff-mcp 项目说明书

生成时间：2026-06-24 10:31:37 UTC

## 目录

- [项目概述与系统架构](#page-overview)
- [MCP 工具参考与工作流](#page-tools)
- [数据模型与持久化机制](#page-data)
- [配置体系、技能文件与部署运维](#page-config-deploy)

<a id='page-overview'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[MCP 工具参考与工作流](#page-tools), [数据模型与持久化机制](#page-data)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/alphaelements/handoff-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/alphaelements/handoff-mcp/blob/main/CHANGELOG.md)
- [src/mcp/mod.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/mod.rs)
- [src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/tools.rs)
- [src/mcp/handlers/refer.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)
- [src/storage/config.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/config.rs)
- [skills/handoff/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)
- [skills/handoff-load/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-load/SKILL.md)
- [skills/handoff-import/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-import/SKILL.md)
- [skills/handoff-refer/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-refer/SKILL.md)
</details>

# 项目概述与系统架构

## 项目定位与目标

`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/` 数据。

```mermaid
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/` | MCP 协议实现、路由、工具定义、处理器 |
| `src/storage/` | `.handoff/` 文件 IO、配置模型（如 `ProjectConfig`、`CalendarConfig`） |
| `skills/handoff*` | 客户端侧行为规范（启动→工作中→结束的剧本） |
| `.handoff/` | 项目本地数据：配置、任务、会话、跨项目转介 |

资料来源：[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

- [任务与会话生命周期管理](tasks-and-sessions.md)
- [跨项目转介（Referrals）协议](referrals.md)
- [配置参考（.handoff/config.toml）](configuration.md)
- [MCP 工具清单与参数约定](tools-reference.md)

---

<a id='page-tools'></a>

## MCP 工具参考与工作流

### 相关页面

相关主题：[项目概述与系统架构](#page-overview), [数据模型与持久化机制](#page-data), [配置体系、技能文件与部署运维](#page-config-deploy)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/tools.rs)
- [src/mcp/router.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/router.rs)
- [src/mcp/handlers/refer.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)
- [skills/handoff/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)
- [skills/handoff-load/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-load/SKILL.md)
- [skills/handoff-import/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-import/SKILL.md)
- [README.md](https://github.com/alphaelements/handoff-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/alphaelements/handoff-mcp/blob/main/CHANGELOG.md)
- [package.json](https://github.com/alphaelements/handoff-mcp/blob/main/package.json)
- [src/storage/config.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/config.rs)
</details>

# MCP 工具参考与工作流

## 概述

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

服务器在 `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](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/router.rs)。

## MCP 工具分类参考

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

| 类别 | 代表工具 | 职责 |
|---|---|---|
| 会话生命周期 | `handoff_init`、`handoff_load_context`、`handoff_save_context` | 初始化 `.handoff/` 目录、加载/保存会话上下文 |
| 任务管理 | `handoff_list_tasks`、`handoff_update_task`、`handoff_check_criterion` | 维护任务树与逐条勾选完成条件 |
| 跨项目协作 | `handoff_send_referral`、`handoff_list_referrals`、`handoff_update_referral` | 发送、列出与更新跨项目推荐 |
| 配置管理 | `handoff_get_config`、`handoff_update_config`、`handoff_add_assignee` | 读写 `.handoff/config.toml` 各节 |
| 仪表盘与导入 | `handoff_dashboard`、`handoff_import` | 跨项目汇总与历史 handoff 文档批量导入 |

`handoff_save_context` 的入参定义了 `summary`、`decisions`、`blockers`、`checklist`、`handoff_notes`、`context_pointers`、`environment` 等结构化字段；其中 `handoff_notes` 至少要包含一条 `category: "suggestion"`，否则服务器会发出警告 资料来源：[src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/tools.rs)。`handoff_update_referral` 则将推荐状态机限制为 `open → acknowledged → resolved` 三态枚举，避免非法跃迁 资料来源：[src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/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](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)。若返回 `not_initialized`，`skills/handoff-load/SKILL.md` 会基于当前目录名推测项目名并自动调用 `handoff_init` 完成初始化 资料来源：[skills/handoff-load/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-load/SKILL.md)。
2. **进行中**：以渐进方式调用 `handoff_update_task`（状态从 `todo` → `in_progress` → `done`），并通过 `handoff_check_criterion` 逐条勾选完成条件；当需要用户确认时将任务状态置为 `review`；同时调用 `handoff_update_session` 持续追加决策、备注和上下文指针 资料来源：[skills/handoff/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)。`skills/handoff-import/SKILL.md` 进一步给出从非结构化文档抽取任务与决策字段的指导 资料来源：[skills/handoff-import/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-import/SKILL.md)。
3. **会话结束**：再次调用 `handoff_save_context` 关闭活动会话，写入 summary、decisions、blockers、checklist 等字段；`handoff_notes` 至少包含一条 `suggestion` 明确下次该做什么 资料来源：[src/mcp/router.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/router.rs)。`README.md` 提示用户将 `.handoff/` 加入 `.gitignore`，因为它保存的是本地工作状态而非代码 资料来源：[README.md](https://github.com/alphaelements/handoff-mcp/blob/main/README.md)。

## 配置与会话状态

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

会话生命周期支持 `active`、`paused`、`closed` 三态：`paused` 状态可被 `handoff_load_context(session_id)` 恢复为 `active`，也可通过 `handoff_save_context(close_session_id)` 直接关闭 资料来源：[skills/handoff-load/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/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](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)。

## 另见

- [README.md](https://github.com/alphaelements/handoff-mcp/blob/main/README.md) — 完整配置示例与工具一览
- [CHANGELOG.md](https://github.com/alphaelements/handoff-mcp/blob/main/CHANGELOG.md) — 版本演进历史
- [skills/handoff-import/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-import/SKILL.md) — 历史 handoff 文档批量导入规范

---

<a id='page-data'></a>

## 数据模型与持久化机制

### 相关页面

相关主题：[项目概述与系统架构](#page-overview), [MCP 工具参考与工作流](#page-tools), [配置体系、技能文件与部署运维](#page-config-deploy)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/storage/mod.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/mod.rs)
- [src/storage/config.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/config.rs)
- [src/storage/tasks.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/tasks.rs)
- [src/storage/sessions.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/sessions.rs)
- [src/storage/git.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/git.rs)
- [src/storage/referrals.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/referrals.rs)
- [README.md](https://github.com/alphaelements/handoff-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/alphaelements/handoff-mcp/blob/main/CHANGELOG.md)
- [src/mcp/handlers/refer.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)
- [src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/tools.rs)
- [skills/handoff/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)
</details>

# 数据模型与持久化机制

## 概述

`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](https://github.com/alphaelements/handoff-mcp/blob/main/README.md) 与 [src/mcp/handlers/refer.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)。

## 持久化目录结构

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

```mermaid
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](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/tools.rs)。

## 配置模型（`config.toml`）

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

| 字段 | 含义 | 默认/示例 |
|---|---|---|
| `project.name`、`project.description` | 项目显示名与说明 | 来自目录名推断 |
| `settings.history_limit` | 保留的已关闭会话数 | `20` |
| `settings.done_task_limit` | 列表中显示的已完成任务数 | `10` |
| `settings.auto_git_summary` | 是否自动捕获 Git 状态 | `true` |
| `dashboard.scan_dirs` | 仪表盘扫描根目录列表 | `["~/pro/"]` |
| `calendar.work_hours_per_day` / `closed_weekdays` / `closed_dates` / `schedule_mode` | 项目级排程日历 | `8` 小时 / `["sat","sun"]` / `auto` |
| `effort_budget.total_hours` | 项目工数总上限 | `500` |
| `assignees.<name>` | 团队成员：显示名、颜色、单日工时、休息日 | 配置段 |
| `milestones.<id>` | 里程碑：标题、计划日期、目标 | 配置段 |
| `gantt_view.sort`/`zoom`/`mode` | 甘特图视图选项 | `start` / `week` / `compare` |

所有配置段都可以通过 `handoff_update_config` 之类的工具以点号键名（如 `calendar.work_hours_per_day`）原地更新，无需整体重写文件资料来源：[README.md](https://github.com/alphaelements/handoff-mcp/blob/main/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](https://github.com/alphaelements/handoff-mcp/blob/main/README.md) 与 [src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/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](https://github.com/alphaelements/handoff-mcp/blob/main/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](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)。

## Git 状态与跨项目 Referrals

`src/storage/git.rs` 负责在 `auto_git_summary = true` 时自动捕获当前分支、最近提交与脏文件，作为 `sessions/*.json` 的附属上下文写入。这使下一会话在加载时能直接看到提交 SHA，而无需重新执行 `git log` 资料来源：[src/storage/config.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/config.rs) 与 [README.md](https://github.com/alphaelements/handoff-mcp/blob/main/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](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)。接收方通过 `handoff_list_referrals` / `handoff_update_referral` 把状态从 `open` 推进到 `acknowledged`，最终到 `resolved` 资料来源：[src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/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](https://github.com/alphaelements/handoff-mcp/blob/main/CHANGELOG.md) 与 [src/storage/config.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/config.rs)。
- **会话缺少 `suggestion`**：服务器警告并拒绝保存空 note 集合，确保下一会话始终有可执行建议资料来源：[skills/handoff/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)。
- **Referral 缺少 `details` / `done_criteria`**：服务器返回 `Warning: No details...`，要求发起方补全后再发送资料来源：[src/mcp/handlers/refer.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)。
- **任务循环依赖**：写入时检测 `dependencies`，构成环则拒绝落盘，避免调度死锁资料来源：[README.md](https://github.com/alphaelements/handoff-mcp/blob/main/README.md)。

## See Also

- [会话生命周期与会话切换](会话生命周期与会话切换.md)
- [MCP 工具总览](MCP工具总览.md)
- [Skill 与命令参考](Skill与命令参考.md)
- [Referrals 跨项目协作](Referrals跨项目协作.md)

---

<a id='page-config-deploy'></a>

## 配置体系、技能文件与部署运维

### 相关页面

相关主题：[项目概述与系统架构](#page-overview), [MCP 工具参考与工作流](#page-tools), [数据模型与持久化机制](#page-data)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/alphaelements/handoff-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/alphaelements/handoff-mcp/blob/main/CHANGELOG.md)
- [src/storage/config.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/storage/config.rs)
- [src/mcp/tools.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/tools.rs)
- [src/mcp/handlers/refer.rs](https://github.com/alphaelements/handoff-mcp/blob/main/src/mcp/handlers/refer.rs)
- [skills/handoff/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff/SKILL.md)
- [skills/handoff-load/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-load/SKILL.md)
- [skills/handoff-import/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-import/SKILL.md)
- [skills/handoff-refer/SKILL.md](https://github.com/alphaelements/handoff-mcp/blob/main/skills/handoff-refer/SKILL.md)
</details>

# 配置体系、技能文件与部署运维

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

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

### 1.1 主要配置节

| 配置节 | 关键字段 | 说明 |
|---|---|---|
| `[project]` | `name`、`description` | 项目元信息，由 `handoff_init` 写入 资料来源：[src/mcp/tools.rs:1-40]() |
| `[settings]` | `history_limit`(20)、`done_task_limit`(10)、`auto_git_summary`(true) | 控制历史/已完成任务的展示数量与是否自动捕获 git 状态 资料来源：[README.md:1-60]() |
| `[dashboard]` | `scan_dirs`、`exclude_patterns` | 供 `handoff_dashboard` 扫描多项目根目录 资料来源：[README.md:60-120]() |
| `[calendar]` | `work_hours_per_day`、`closed_weekdays`、`schedule_mode`、`overwork_limit_percent`、`day_hours` | 全局工作日历，v0.11.0 起可通过 `handoff_update_calendar` 直接修改 资料来源：[CHANGELOG.md:10-30]() |
| `[effort_budget]` | `total_hours` | 项目总工数上限 |
| `[assignees.*]` | `display_name`、`color`、`work_hours_per_day`、`closed_weekdays` | 成员档案与个人日历 |
| `[milestones.*]` | 名称/日期 | v0.11.0 新增的强类型里程碑模型 资料来源：[CHANGELOG.md:10-30]() |
| `[gantt_view]` | `sort`、`zoom`、`mode` | 控制甘特图渲染 资料来源：[README.md:80-140]() |

### 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 工具与接口](mcp-tools.md)
- [会话与任务模型](session-task-model.md)
- [跨项目转发与协作](referral-workflow.md)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: alphaelements/handoff-mcp; human_manual_source: deepwiki_human_wiki -->