PingCraft：从需求文档到可追踪工作项的 Agent 实践之路

来自博主的开源项目：PingCraft（Apache-2.0）

最近开源了一个项目 PingCraft（GitHub 地址：https://github.com/knqiufan/PingCraft）：一个基于 AI 的需求智能分析与导入工具。
简单说下它的作用：上传需求文档（Word / Markdown / TXT），用大模型解析成结构化工作项，与 PingCode 已同步的数据做对齐和查重，然后一键批量导入。

核心功能包括：

• 文档上传与 AI 解析，输出符合 PingCode 格式的工作项
  
• 基于向量相似度的项目推荐和需求查重（标记 New / Similar）
  
• 字段自动映射（"高优先级" → PingCode 的 priority_id）
  
• SSE 实时推送导入进度
  
• 统计分析 + AI 解读报告 + PDF 导出
  

下面聊聊为什么要做这个项目，以及过程中对 Agent 应用的一些思考。
一、做这个项目的初心

先说说为什么会有 PingCraft 这个项目。
周五下午有些繁琐

每周五下午都有一项固定工作：把本周工作内容和相关需求全部录入到 PingCode 里。
看起来很简单对吧。其实不。每录入一条工作项我都要：

• 点击「新增工作项」
  
• 从下拉列表里找项目
  
• 选择工作项类型（Story？Task？Bug？）
  
• 填写标题和描述
  
• 选择负责人（谁来做？）
  
• 选择优先级（高？中？低？）
  
• 填写预估工时
  
• 选择计划开始时间和结束时间
  
• 选择状态（待处理？进行中？）
  
• ……
  

一条工作项录完两分钟过去了。如果有十来条工作项半小时就没了。这半小时甚至更长的时间里我就在机械重复的做数据录入的工作。
做重复繁琐的工作，AI 擅长啊

其实也是受了博主的一个同事做的一个 PingCode 录入的 MCP 的启发。AI 模型可以直接调用这个 MCP 来对需求和工作项直接进行录入。但是这个 MCP 当时有个不方便的地方在于，登录连接上 PingCode 的步骤挺麻烦的.要使用这个 MCP，得先执行某个接口或脚本，然后手动从地址栏中获取相关凭证令牌，再填入配置文件中，，没有方便的一键登录的方式，这个操作其实对用户来说是不友好的。所以这个 MCP 当初也没有大范围的推广使用。
也没有缓解博主在每周五下午的工作录入的痛苦（因为 MCP 没用上 orz）
但是！感谢同事先做出的 PingCode MCP 给予的灵感，想法是很好的，但我寻思在具体使用步骤和方式上可以更便利。
so 进行了一番思考。AI 在这个场景其实很适合让他来干一些事情啊，such as：

• 理解语义：大模型可以从一段非结构化的需求描述中提取关键信息
  
• 映射字段：把"高优先级"自动对应到系统里的优先级
  
• 判断重复：用向量相似度检测新需求和已有工作项是否语义相近
  
• ...
  

也就是：

• 把那些乱七八糟的需求文档（Word、MD、TXT 都行）扔进去
  
• AI 自动解析成符合 PingCode 格式的结构化数据
  
• 再通过 API 一键导入
  

而登录的问题好解决，加个可视化界面去自动获取点击嘛。且有了可视化界面之后甚至可以做到更多的功能，比如一些信息和统计图表展示什么的。所以有了 PingCraft。
其实做 PingCraft 的初心是：用 AI 把那些重复的、机械的操作自动化，把人从搬运工的角色里解放出来。
即，AI 在实际应用中正确发挥作用的地方——不是替代人做决策，而是帮人省掉那些本就不该由人来做的事情。
二、PingCraft 具体是解决什么？

定位明确：打通「文档 → 结构化工作项 → 与线上数据对齐 → 批量落库」这条链路。它不是一个通用的"AI 写需求"工具，而是一个面向 PingCode 的需求导入管道。
核心价值主张

一句话概括：

让大模型在真实的业务上下文中理解需求，并把理解结果直接对接到真实的项目管理系统。

有两个关键词：

• 真实上下文：同步 PingCode 的项目、类型、状态、优先级等元数据，让 AI 知道"在这个项目里，'紧急'对应哪个优先级"
  
• 真实系统：不是生成一份漂亮的 Markdown 报告，而是调用 API 创建真实的工作项
  

OK，那现在它能做什么？

场景PingCraft 的处理方式上传 Word/MD/TXT 文档大模型解析，输出结构化工作项 JSON自动匹配项目基于向量相似度推荐目标项目担心重复造单对每条草案与已同步工作项做语义比对，标记 New / Similar字段映射困难自动将"高优先级"映射为 PingCode 的 priority_id批量导入等待焦虑SSE 推送实时进度需要汇报总结统计数据 + AI 生成解读报告 + 导出 PDF

上传需求文档后，AI 会自动解析并生成结构化的工作项列表，包括标题、描述、优先级、预估工时、计划时间、负责人等字段，同时标记每条工作项是 New（全新）还是 Similar（与历史需求相似）。
明确一下边界

为了避免误解明确一下边界：

• 不是全自动无人值守系统——人需要确认项目、查重结果、字段映射等等
  
• 不是需求编写工具——它处理的是已有的需求材料，不是从零生成
  
• 不是替代 PingCode——它是 PingCode 的"前置处理管道"
  

三、对当下 Agent 应用的思考

做这个项目的过程中，我对 Agent 应用有了一些更具体的思考。
连接性可能比智能性更重要

现在很多人谈 Agent，焦点往往在"模型够不够聪明"、"rompt 写得好不好"。但实际落地时，连接真实系统的能力往往才是瓶颈。
PingCraft 里最复杂的部分，不是需求解析的 Prompt，而是：

• PingCode OAuth 授权与 Token 自动刷新
  
• 项目、工作项、类型、状态、属性的增量同步
  
• 元数据名称到 UUID 的映射表
  
• 向量索引的构建与查询
  这些脏活累活是 Agent 能落地的地基。
  

找到 AI 正确发挥作用的场景

不是所有问题都适合用 AI 解决。但有一类场景特别适合：重复的、机械的、需要跨系统转换的操作。
需求录入就是典型的例子：

• 需要理解自然语言（AI 擅长）
  
• 需要映射到系统字段（规则明确，但人做很烦）
  
• 需要批量执行（API 可以自动化）
  这类场景的特点是：任务本身不复杂，但人工做很耗时。用 AI 把它自动化，投入产出比很高。
  

深度融合场景的 Agent 才有价值

市面上有很多通用的 Agent 框架和工具，但真正能解决业务问题的，往往是深度融合特定场景的 Agent。
PingCraft 的深度不在于模型参数量，而在于：

• 对象真实：工作项、项目、优先级、OAuth Token，全是 PingCode 系统里的真实实体
  
• 闭环完整：解析 → 对齐 → 导入 → 统计 → 报告，链路闭合
  
• 约束到位：多租户、RBAC、向量查重、元数据映射，把 LLM 的自由度限制在安全区间
  

四、技术选型的取舍

最后简单聊下技术选型的考量。
为什么是 LangChain？

需求解析场景需要：结构化输出、可调试的 Prompt、多模型支持。LangChain 的 PromptTemplate + JsonOutputParser 组合，让 Prompt 可以独立目录维护、版本管理，方便迭代。
为什么是 SeekDB？

向量检索是"查重"能力的核心。选择 SeekDB（MySQL 兼容 + 向量）的原因是：减少运维复杂度。业务数据和向量数据同库，不需要再叠一套 Milvus 或 Pinecone。
为什么是 SSE 而不是 WebSocket？

批量导入是"服务端推送进度"的场景，客户端不需要频繁发消息。SSE 比 WebSocket 更轻量，也更容易和 Express 集成。
导入过程中通过 SSE 实时推送进度，让用户知道当前处理到哪一条，而不是对着一个加载动画干等。
技术栈一览

层级选型前端Vue 3、TypeScript、Vite、Element Plus、Pinia、ECharts后端Node.js、Express 5、ES Module数据库SeekDB（MySQL 兼容 + 向量）AILangChain、OpenAI 兼容 API、Anthropic实时Server-Sent Events五、总结

PingCraft 是一个很工程化的 Agent 项目：它没有炫技式的 Prompt，也没有复杂的推理链，但它把"需求文档到可追踪工作项"这条链路上的每个环节都做实了。
项目初衷很简单：不想每周五下午花半小时做重复的录入工作。
更深层次的思考是，AI 在实际场景中应该怎么正确发挥作用？
答案似乎很朴素，就是帮人省掉那些本就不该由人来做的事情。
不是替代人做决策，不是炫技式的"全自动"，而是把那些重复的、机械的、跨系统转换的操作自动化，让人能把时间花在真正需要思考的事情上。
这和我在之前文章里写过的一个观点是一致的：把领域里的做法显式化，让 AI 在边界内做推理，而不是期望它全知全能。
参考资料：

• 项目仓库：https://github.com/knqiufan/PingCraft
  
• PingCode 开放平台：https://open.pingcode.com/
  
• SeekDB 文档：https://www.seekdb.com/
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！