小丹尼DannyData我到现在还记得那次需求评审会后的“对账现场”。产品改了一版 7000 字的 PRD，研发组长照着文档目录手写了 38 条任务，两天后需求文档又改了三个字段，任务表跟文档各说各话，最后几个人凑在一起逐条核对“这条到底还做不做、验收标准以哪版为准”。PingCraft 这个项目，最初就是冲着消除这种“文档-任务漂移”去的。简单说，它是一套把需求文档翻译成可追踪工作项的 Agent 管线，用语言模型做语义理解，用工程手段保证每一步都可校验、可回滚。如果你在搞 Agent 应用落地，或者在做研发效能工具、项目管理自动化，这篇文章里的拆解思路、设计取舍和踩坑记录，应该能提供一些参考。
1. 为什么需要一套“需求转工作项”的 Agent 管线
1.1 需求与工作项之间的“翻译损耗”
需求评审会上大家看着同一份文档，但散会后每个人带走的理解并不一致。产品经理脑子里想的是“用户在登录失败时要得到清晰反馈”，研发任务写出来常常变成“优化登录错误提示”，测试用例则可能完全没覆盖这个场景。这种损耗不是某个人的责任心问题，而是手工维护方式的结构性缺陷：需求文档是自然语言，工作项是结构化条目，两者之间本来就需要一次翻译。
我在团队里观察过很多次，手工拆需求时最容易丢三样东西：
- 验收标准被压缩成功能描述，测试阶段才重新补细节；
- 需求之间的依赖关系被隐去，排期后期才发现阻塞；
- 需求变更记录被抹平，没人知道某个任务对应的是文档的哪一版描述。
PingCraft 想解决的，就是让这次“翻译”不依赖个人状态，而是由 Agent 按统一协议完成，并且把翻译过程的中间产物全部保留下来。
1.2 为什么普通脚本和规则引擎做不了这件事
如果只是把文档里“需求”两个字后面的句子提取出来，用正则也能做个七七八八。但真实需求文档的表述方式极其发散，比如这一句：
“当用户连续输错三次密码后，页面需要在 3 秒内提示账户暂时锁定，并明确告知 15 分钟后再试。”
规则脚本很难判断“连续输错三次”是触发条件，“提示账户暂时锁定”是业务规则，“15 分钟后再试”是操作引导。这三个信息在任务卡片里应该分别落到前置条件、功能行为和辅助提示栏位中。Agent 的价值不在于比你更懂业务，而在于它能稳定地把这类复合语义拆解成结构化要素，并且每次处理都保持同样的逻辑。
但这里的重点不是“LLM 很强”，而是“LLM 不可靠”。所以我在设计 PingCraft 时一开始就定了一个原则：Agent 负责理解，工程负责校验。
1.3 PingCraft 想解决的三个具体问题
第一个是拆得准。需求拆成的工作项要覆盖完整，验收标准不能漏，依赖关系不能被丢掉。第二个是跟得住。从需求文档的某一段原文，到拆解出来的需求单元，再到项目管理工具里的工作项，最后到代码提交记录，这条链路要能一路回溯。第三个是改得动。需求文档更新后，系统要能指出哪些旧工作项受影响、哪些验收标准被替换，而不是让团队重新手工对账。
这三个问题分别对应了三条技术线：抽取与生成、血缘与锚点、变更与影响分析。接下来的章节，我会按这三个方向展开。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. PingCraft 的整体架构：一颗“会拆解”的大脑加两条“守纪律”的流水线
2.1 架构总览：Agent 只出草案，执行器才落库
PingCraft 整体上分为三层，我习惯用一张职责表来概括：
| 层级 | 主要模块 | 职责 |
|---|---|---|
| 输入层 | 文档解析器、切片器 | 把 Markdown、docx、Confluence 内容归一化成带锚点的干净文本 |
| 智能层 | 解读 Agent、拆解 Agent | 做语义理解，输出结构化需求单元和工作项草案 |
| 执行层 | 校验服务、写库执行器、Webhook 监听器 | 做格式校验、字段补全、幂等写入、状态回写 |
一个容易让人困惑的点是：为什么不让 Agent 直接调用 Jira 或 Tapd 的 API 创建任务？那样看起来链路更短。我踩过这个坑之后才想明白：Agent 擅长的是“不确定中找出路”，写数据库这件事恰恰要求“绝对确定且可回滚”。让 Agent 直接改项目管理工具，一旦抽取结果产生幻觉，测试任务、脏数据