Agent Handoff 自动跟踪 Skill：安装、事件映射与证据分级

适用版本与目标

本文基于 Agent Handoff 当前 0.6.0 源码中的 track-agent-handoff Skill，说明如何让 Codex 在需求、进度、技术决策、阻塞和测试状态发生变化时，主动调用 agent-handoff memory record 写入项目记忆。

当前源码已通过 npm test 213/213 和 npm run release:check。发布验收确认打包产物包含 Skill 的 3 个必要文件。本文未核对公网 npm 包是否已同步更新，因此安装步骤分别说明源码目录和全局安装目录两种来源。

1. Hook、Skill、MCP与CLI的区别

组件	职责	是否自动理解任务进度
SessionStart Hook	运行 `memory context`，加载 `CONTEXT.md`	否
Stop Hook	记录一次会话结束或交接事件	否
`track-agent-handoff` Skill	根据语义和证据识别项目状态变化	是，但可能漏记或误判
CLI / MCP	校验并写入事件，刷新状态与上下文	不负责语义判断

Skill 不是后台监听器，也不会抓取完整 Prompt 和模型回复。它是 Agent 工作规则的一部分：当 Agent 观察到状态变化时，主动调用现有 CLI 或 MCP 能力。

2. 安装Skill

前置条件：Node.js 20+，已安装 Agent Handoff。

2.1 从源码安装到Codex

在 Agent Handoff 源码根目录执行：

bash 复制代码

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/track-agent-handoff \
  "${CODEX_HOME:-$HOME/.codex}/skills/"

重启 Codex。

2.2 从全局安装目录复制

定位 npm 全局目录：

bash 复制代码

npm root -g

把下面的目录复制到 ${CODEX_HOME:-$HOME/.codex}/skills/：

text 复制代码

<npm root -g>/agent-handoff/skills/track-agent-handoff

复制前应确认全局包内实际存在该目录，不能只根据版本号推断。

2.3 初始化项目并触发Skill

bash 复制代码

cd /path/to/project
agent-handoff memory init .

第一次使用建议显式触发：

text 复制代码

使用 $track-agent-handoff 持续跟踪当前任务

Skill 的 description 也覆盖"持续记忆项目状态""自动跟踪开发过程""恢复已有上下文"和项目存在 .agent-handoff 等场景，平台可能通过语义匹配自动加载，但显式触发更容易验证配置是否生效。

3. 会话生命周期

3.1 会话开始

Skill 指导 Agent：

确认当前目录是项目根目录；
检查 .agent-handoff/EVENTS.jsonl 是否存在；
已初始化时执行 agent-handoff memory context .；
未初始化时先征得用户同意，再执行 memory init；
使用真实 Agent 名称，只有平台提供真实会话 ID 时才写入 --session-id。

3.2 开发过程中

事件映射如下：

检测到的事实	事件类型	最低记录条件
新主要工作项开始	`task`	用户已要求执行，且不是现有任务延续
新需求或验收条件确认	`requirement`	用户明确确认，不是候选讨论
实现达到可交接阶段	`progress`	有观察到的状态变化
技术或范围选择确定	`decision`	决策已确定并影响后续工作
工作实际被阻塞	`blocker`	当前无法继续且原因明确
阻塞解除	`blocker-resolved`	有 observed/verified 证据
测试命令执行完成	`test`	有真实命令和退出结果
整项任务完成	`task-completed`	有 observed/verified 证据
需要交接	`checkpoint`	存在下一步或未完成状态

普通解释、探索性搜索、计划微调、无结果重试和闲聊不记录。同一需求、决策、阻塞或进度只记录一次，状态或证据发生实质变化后才追加。

3.3 会话结束

已经逐项记录的进展不应在 checkpoint 中重复。收尾只写下一步：

bash 复制代码

printf '%s\n' '{
  "completed": [],
  "inProgress": [],
  "blocked": [],
  "decisions": [],
  "nextSteps": ["在目标平台验证 Skill 自动触发"],
  "tests": []
}' | agent-handoff memory checkpoint . --from-stdin --agent codex

agent-handoff memory verify .

这样可以避免同一事件重复落盘，也避免一组测试结果被错误关联到多个完成项。

4. 事件命令示例

Skill 最终仍调用现有 memory CLI。下面的命令通常不需要用户手动输入，但理解它们有助于排查自动记录是否正确。

4.1 开始任务

bash 复制代码

agent-handoff memory record . \
  --type task \
  --text "实现登录接口" \
  --status in_progress \
  --task-id "task-login" \
  --agent codex

4.2 记录实现进展

bash 复制代码

agent-handoff memory record . \
  --type progress \
  --text "登录接口已实现，等待页面联调" \
  --status in_progress \
  --task-id "task-login" \
  --agent codex \
  --file "src/login.js" \
  --evidence-level observed

4.3 记录测试结果

bash 复制代码

agent-handoff memory record . \
  --type test \
  --text "登录模块测试通过" \
  --status passed \
  --task-id "task-login" \
  --agent codex \
  --command "npm test" \
  --tests "12:0" \
  --evidence-level verified

测试工具没有提供准确计数时，应省略 --tests，不得猜测数字。

4.4 确认整个任务完成

bash 复制代码

agent-handoff memory record . \
  --type task-completed \
  --text "登录功能已实现并通过验证" \
  --task-id "task-login" \
  --agent codex \
  --command "npm test" \
  --evidence-level verified

只有文件变化时，不能使用 task-completed。此时只能记录 progress，或者使用 reported 标记尚待验证的完成状态。

5. 证据分级

证据等级	来源	能否确认完成或解除阻塞
`verified`	实际运行测试、构建或检查命令	能
`observed`	直接检查文件、配置、提交或外部状态	能，但仅限观察范围
`reported`	用户或 Agent 陈述，尚未验证	不能，状态显示待确认
`inferred`	模型推断	协议拒绝

自动跟踪的关键不是多写事件，而是只把可以说明来源的状态写入记忆。文件修改不等于需求完成，单条测试也不代表所有验收条件都满足。

6. 漏记、误记和状态修复

自动检测依赖 Agent 的语义判断，不是确定性 Hook。

漏记时手动补充：

bash 复制代码

agent-handoff memory record . --type progress \
  --text "补记登录接口联调进展" --status in_progress --agent codex

误记时撤销最后一条事件：

bash 复制代码

agent-handoff memory undo .

查看当前上下文：

bash 复制代码

agent-handoff memory context .

派生产物不一致时，从事件日志重建：

bash 复制代码

agent-handoff memory rebuild .
agent-handoff memory verify .

7. 当前验证结果与边界

2026年9月1日在当前源码执行：

text 复制代码

npm test              213/213 通过
npm run release:check 通过
tarball 文件数         36
Skill 必要文件         3/3
安装后输出文件         8/8

3 个 Skill 必要文件为：

text 复制代码

skills/track-agent-handoff/SKILL.md
skills/track-agent-handoff/agents/openai.yaml
skills/track-agent-handoff/references/event-rules.md

测试覆盖了 Skill 结构、触发描述、事件命令和发布配置；release-check 覆盖了打包、安装后版本、输出文件和全量测试。它没有证明所有平台都能稳定自动触发 Skill，因此平台级端到端行为仍应单独验证。

8. 结论

Hook 解决"新会话先读什么"，Skill 解决"开发过程中什么时候写"，CLI/MCP 解决"事件如何落盘"。安装 track-agent-handoff 后，用户通常不必手动输入每一条 memory record 命令，但仍需要检查关键完成状态和测试证据。