项目背景

Agent Handoff 是一个本地运行的 AI 编程项目接力包生成器。M1 完成仓库扫描，M2 完成技术栈、入口、命令和 Git 状态识别，M3 处理任务说明和 Agent 交接信息。

当前版本：0.3.0。

M3 的目标不是生成代码，而是让另一个 Agent 能在较少背景问答的情况下继续工作。

1. 使用方式

Node.js 20+ 环境下运行：

node bin/agent-handoff.js /path/to/project --task task.md

不提供任务文件时：

node bin/agent-handoff.js /path/to/project

输出目录：

.agent-handoff/
├── TASK.md
├── HANDOFF.md
├── REPO_MAP.md
├── COMMANDS.md
├── GIT_STATE.md
└── manifest.json

M3 新增的核心文件是 TASK.md、HANDOFF.md，并在 manifest.json 中记录任务来源和解析结果。

2. 任务解析模型

任务文件以 Markdown 二级标题组织章节，支持：

目标
必须完成
不做的内容
技术与部署限制
验收标准
已知问题
已完成
进行中
待处理
失败尝试

其中最后四个是交接状态章节，可选。解析结果不包含推测内容，缺失章节保持为空。

实现中的关键边界是代码块过滤。围栏代码块（```````````或 ~~~）以及缩进代码块中的标题和列表不会参与解析，否则任务示例里的 Markdown 很容易被误识别成真实任务。

3. 无任务文件的处理

无 --task 参数时，工具生成模板，并在输出中提醒用户补充；--task 指向不存在的文件时，CLI 返回退出码 2。

这两个场景必须区分：

• 无任务文件：合法运行，但任务内容未知；
• 指定文件不存在：输入错误，直接失败。

不能因为用户传错路径，就静默生成一个看起来正常的空任务。

4. TASK.md 与 HANDOFF.md

TASK.md 负责结构化任务本身，主要字段带有来源信息（任务文件或模板）。

HANDOFF.md 固定输出 10 个章节：

1. 项目基本信息；
2. 当前任务和非目标；
3. 技术栈和启动方式；
4. 仓库地图文件入口；
5. 当前 Git 状态；
6. 已完成、进行中和待处理事项；
7. 已知失败尝试及结果；
8. 测试和验收方式；
9. 安全和敏感信息说明；
10. 给下一个 Agent 的第一步建议。

工作状态的输出有三种明确口径：

• 有条目：输出实际条目；
• 章节声明为空：输出“无”；
• 章节未声明：输出“未知”。

失败尝试单独标记为“失败”，不会被合并到已完成列表。

5. 验收测试

在项目目录运行：

npm test

当前结果：51 项通过，0 失败。

M3 相关测试覆盖：

• 完整任务文件的所有章节；
• 缺失章节和空输入；
• 无任务文件时模板输出；
• 指定任务文件不存在时抛错；
• 失败尝试和未知状态的渲染；
• 围栏代码块和缩进代码块过滤；
• --task 端到端输出 TASK.md、HANDOFF.md；
• manifest.task 来源和解析结果；
• 未识别技术栈时的启动方式占位。

6. 交接前后的流程变化

以前的交接依赖聊天记录：

复制旧聊天 -> 新 Agent 重新提问 -> 猜测当前状态 -> 开始修改

M3 后可以变成：

读取 TASK.md -> 读取 HANDOFF.md -> 按报告运行测试 -> 开始修改

它不能替代代码审查，但能把任务边界、非目标、失败尝试和验证命令放到同一份可复核材料里。

7. 已知限制

• 任务文件主要解析 Markdown 二级标题和列表，复杂表格不在当前范围内；
• 动态生成的任务内容不会被执行或推测；
• 敏感信息脱敏和更完整的真实项目验证属于后续 M4；
• 工具不自动修改、提交、推送或上传用户代码。

总结

M3 把 Agent Handoff 从“仓库状态扫描器”推进成了“任务交接包生成器”。它没有让 AI 更会写代码，但让下一个 Agent 更容易知道该写什么、哪些地方不要碰，以及前面哪些尝试已经失败。

这正是降低 AI 编程知识债务的基础。

#Node.js #AI编程 #Agent #Git #软件工程 #代码工具