PingCraft：从需求文档到可追踪工作项的 Agent 实践之路
<blockquote><p><strong>来自博主的开源项目</strong>：PingCraft（Apache-2.0）</p>
</blockquote>
<hr>
<p>最近开源了一个项目 <strong>PingCraft</strong>（GitHub 地址：https://github.com/knqiufan/PingCraft）：一个基于 AI 的需求智能分析与导入工具。<br>
简单说下它的作用：<strong>上传需求文档（Word / Markdown / TXT），用大模型解析成结构化工作项，与 PingCode 已同步的数据做对齐和查重，然后一键批量导入。</strong></p>
<p><img src="https://img2024.cnblogs.com/blog/1456590/202603/1456590-20260322234034586-736079037.png" alt="image-20260322004618337" loading="lazy"></p>
<p><img src="https://img2024.cnblogs.com/blog/1456590/202603/1456590-20260323000104359-2059504158.png" alt="image-20260322004719923" loading="lazy"></p>
<p>核心功能包括：</p>
<ul>
<li>文档上传与 AI 解析，输出符合 PingCode 格式的工作项</li>
<li>基于向量相似度的项目推荐和需求查重（标记 New / Similar）</li>
<li>字段自动映射（"高优先级" → PingCode 的 priority_id）</li>
<li>SSE 实时推送导入进度</li>
<li>统计分析 + AI 解读报告 + PDF 导出</li>
</ul>
<p>下面聊聊为什么要做这个项目，以及过程中对 Agent 应用的一些思考。</p>
<hr>
<h2 id="一做这个项目的初心">一、做这个项目的初心</h2>
<p>先说说为什么会有 PingCraft 这个项目。</p>
<h3 id="周五下午有些繁琐">周五下午有些繁琐</h3>
<p>每周五下午都有一项固定工作：把本周工作内容和相关需求全部录入到 PingCode 里。</p>
<p>看起来很简单对吧。其实不。每录入一条工作项我都要：</p>
<ol>
<li>点击「新增工作项」</li>
<li>从下拉列表里找项目</li>
<li>选择工作项类型（Story？Task？Bug？）</li>
<li>填写标题和描述</li>
<li>选择负责人（谁来做？）</li>
<li>选择优先级（高？中？低？）</li>
<li>填写预估工时</li>
<li>选择计划开始时间和结束时间</li>
<li>选择状态（待处理？进行中？）</li>
<li>……</li>
</ol>
<p>一条工作项录完两分钟过去了。如果有十来条工作项半小时就没了。这半小时甚至更长的时间里我就在机械重复的做数据录入的工作。</p>
<h3 id="做重复繁琐的工作ai-擅长啊">做重复繁琐的工作，AI 擅长啊</h3>
<p>其实也是受了博主的一个同事做的一个 PingCode 录入的 MCP 的启发。AI 模型可以直接调用这个 MCP 来对需求和工作项直接进行录入。但是这个 MCP 当时有个不方便的地方在于，登录连接上 PingCode 的步骤挺麻烦的.要使用这个 MCP，得先执行某个接口或脚本，然后手动从地址栏中获取相关凭证令牌，再填入配置文件中，，没有方便的一键登录的方式，这个操作其实对用户来说是不友好的。所以这个 MCP 当初也没有大范围的推广使用。</p>
<p>也没有缓解博主在每周五下午的工作录入的痛苦（因为 MCP 没用上 orz）</p>
<p>但是！感谢同事先做出的 PingCode MCP 给予的灵感，想法是很好的，但我寻思在具体使用步骤和方式上可以更便利。</p>
<p>so 进行了一番思考。AI 在这个场景其实很适合让他来干一些事情啊，such as：</p>
<ul>
<li><strong>理解语义</strong>：大模型可以从一段非结构化的需求描述中提取关键信息</li>
<li><strong>映射字段</strong>：把"高优先级"自动对应到系统里的优先级</li>
<li><strong>判断重复</strong>：用向量相似度检测新需求和已有工作项是否语义相近</li>
<li>...</li>
</ul>
<p>也就是：</p>
<ol>
<li>把那些乱七八糟的需求文档（Word、MD、TXT 都行）扔进去</li>
<li>AI 自动解析成符合 PingCode 格式的结构化数据</li>
<li>再通过 API 一键导入</li>
</ol>
<p>而登录的问题好解决，加个可视化界面去自动获取点击嘛。且有了可视化界面之后甚至可以做到更多的功能，比如一些信息和统计图表展示什么的。所以有了 PingCraft。</p>
<p><strong>其实做 PingCraft 的初心是：用 AI 把那些重复的、机械的操作自动化，把人从搬运工的角色里解放出来。</strong></p>
<p>即，AI 在实际应用中正确发挥作用的地方——不是替代人做决策，而是帮人省掉那些本就不该由人来做的事情。</p>
<h2 id="二pingcraft-具体是解决什么">二、PingCraft 具体是解决什么？</h2>
<p>定位明确：<strong>打通「文档 → 结构化工作项 → 与线上数据对齐 → 批量落库」这条链路</strong>。它不是一个通用的"AI 写需求"工具，而是一个<strong>面向 PingCode 的需求导入管道</strong>。</p>
<h3 id="核心价值主张">核心价值主张</h3>
<p>一句话概括：</p>
<blockquote>
<p>让大模型在<strong>真实的业务上下文</strong>中理解需求，并把理解结果<strong>直接对接到真实的项目管理系统</strong>。</p>
</blockquote>
<p>有两个关键词：</p>
<ul>
<li><strong>真实上下文</strong>：同步 PingCode 的项目、类型、状态、优先级等元数据，让 AI 知道"在这个项目里，'紧急'对应哪个优先级"</li>
<li><strong>真实系统</strong>：不是生成一份漂亮的 Markdown 报告，而是调用 API 创建真实的工作项</li>
</ul>
<h3 id="ok那现在它能做什么">OK，那现在它能做什么？</h3>
<table>
<thead>
<tr>
<th>场景</th>
<th>PingCraft 的处理方式</th>
</tr>
</thead>
<tbody>
<tr>
<td>上传 Word/MD/TXT 文档</td>
<td>大模型解析，输出结构化工作项 JSON</td>
</tr>
<tr>
<td>自动匹配项目</td>
<td>基于向量相似度推荐目标项目</td>
</tr>
<tr>
<td>担心重复造单</td>
<td>对每条草案与已同步工作项做语义比对，标记 New / Similar</td>
</tr>
<tr>
<td>字段映射困难</td>
<td>自动将"高优先级"映射为 PingCode 的 <code>priority_id</code></td>
</tr>
<tr>
<td>批量导入等待焦虑</td>
<td>SSE 推送实时进度</td>
</tr>
<tr>
<td>需要汇报总结</td>
<td>统计数据 + AI 生成解读报告 + 导出 PDF</td>
</tr>
</tbody>
</table>
<p><img src="https://img2024.cnblogs.com/blog/1456590/202603/1456590-20260322235912038-547636489.png" alt="image-20260322005610971" loading="lazy"></p>
<p>上传需求文档后，AI 会自动解析并生成结构化的工作项列表，包括标题、描述、优先级、预估工时、计划时间、负责人等字段，同时标记每条工作项是 New（全新）还是 Similar（与历史需求相似）。</p>
<h3 id="明确一下边界">明确一下边界</h3>
<p>为了避免误解明确一下边界：</p>
<ul>
<li><strong>不是</strong>全自动无人值守系统——人需要确认项目、查重结果、字段映射等等</li>
<li><strong>不是</strong>需求编写工具——它处理的是已有的需求材料，不是从零生成</li>
<li><strong>不是</strong>替代 PingCode——它是 PingCode 的"前置处理管道"</li>
</ul>
<h2 id="三对当下-agent-应用的思考">三、对当下 Agent 应用的思考</h2>
<p>做这个项目的过程中，我对 Agent 应用有了一些更具体的思考。</p>
<h3 id="连接性可能比智能性更重要">连接性可能比智能性更重要</h3>
<p>现在很多人谈 Agent，焦点往往在"模型够不够聪明"、"Prompt 写得好不好"。但实际落地时，<strong>连接真实系统的能力</strong>往往才是瓶颈。<br>
PingCraft 里最复杂的部分，不是需求解析的 Prompt，而是：</p>
<ul>
<li>PingCode OAuth 授权与 Token 自动刷新</li>
<li>项目、工作项、类型、状态、属性的增量同步</li>
<li>元数据名称到 UUID 的映射表</li>
<li>向量索引的构建与查询<br>
这些脏活累活是 Agent 能落地的地基。</li>
</ul>
<h3 id="找到-ai-正确发挥作用的场景">找到 AI 正确发挥作用的场景</h3>
<p>不是所有问题都适合用 AI 解决。但有一类场景特别适合：<strong>重复的、机械的、需要跨系统转换的操作。</strong><br>
需求录入就是典型的例子：</p>
<ul>
<li>需要理解自然语言（AI 擅长）</li>
<li>需要映射到系统字段（规则明确，但人做很烦）</li>
<li>需要批量执行（API 可以自动化）<br>
这类场景的特点是：<strong>任务本身不复杂，但人工做很耗时</strong>。用 AI 把它自动化，投入产出比很高。</li>
</ul>
<h3 id="深度融合场景的-agent-才有价值">深度融合场景的 Agent 才有价值</h3>
<p>市面上有很多通用的 Agent 框架和工具，但真正能解决业务问题的，往往是<strong>深度融合特定场景</strong>的 Agent。<br>
PingCraft 的深度不在于模型参数量，而在于：</p>
<ol>
<li><strong>对象真实</strong>：工作项、项目、优先级、OAuth Token，全是 PingCode 系统里的真实实体</li>
<li><strong>闭环完整</strong>：解析 → 对齐 → 导入 → 统计 → 报告，链路闭合</li>
<li><strong>约束到位</strong>：多租户、RBAC、向量查重、元数据映射，把 LLM 的自由度限制在安全区间</li>
</ol>
<h2 id="四技术选型的取舍">四、技术选型的取舍</h2>
<p>最后简单聊下技术选型的考量。</p>
<h3 id="为什么是-langchain">为什么是 LangChain？</h3>
<p>需求解析场景需要：结构化输出、可调试的 Prompt、多模型支持。LangChain 的 <code>PromptTemplate</code> + <code>JsonOutputParser</code> 组合，让 Prompt 可以独立目录维护、版本管理，方便迭代。</p>
<h3 id="为什么是-seekdb">为什么是 SeekDB？</h3>
<p>向量检索是"查重"能力的核心。选择 SeekDB（MySQL 兼容 + 向量）的原因是：<strong>减少运维复杂度</strong>。业务数据和向量数据同库，不需要再叠一套 Milvus 或 Pinecone。</p>
<h3 id="为什么是-sse-而不是-websocket">为什么是 SSE 而不是 WebSocket？</h3>
<p>批量导入是"服务端推送进度"的场景，客户端不需要频繁发消息。SSE 比 WebSocket 更轻量，也更容易和 Express 集成。<br>
导入过程中通过 SSE 实时推送进度，让用户知道当前处理到哪一条，而不是对着一个加载动画干等。</p>
<h3 id="技术栈一览">技术栈一览</h3>
<table>
<thead>
<tr>
<th>层级</th>
<th>选型</th>
</tr>
</thead>
<tbody>
<tr>
<td>前端</td>
<td>Vue 3、TypeScript、Vite、Element Plus、Pinia、ECharts</td>
</tr>
<tr>
<td>后端</td>
<td>Node.js、Express 5、ES Module</td>
</tr>
<tr>
<td>数据库</td>
<td>SeekDB（MySQL 兼容 + 向量）</td>
</tr>
<tr>
<td>AI</td>
<td>LangChain、OpenAI 兼容 API、Anthropic</td>
</tr>
<tr>
<td>实时</td>
<td>Server-Sent Events</td>
</tr>
</tbody>
</table>
<h2 id="五总结">五、总结</h2>
<p>PingCraft 是一个很工程化的 Agent 项目：它没有炫技式的 Prompt，也没有复杂的推理链，但它把"需求文档到可追踪工作项"这条链路上的每个环节都做实了。<br>
项目初衷很简单：<strong>不想每周五下午花半小时做重复的录入工作</strong>。<br>
更深层次的思考是，<strong>AI 在实际场景中应该怎么正确发挥作用？</strong><br>
答案似乎很朴素，就是<strong>帮人省掉那些本就不该由人来做的事情</strong>。<br>
不是替代人做决策，不是炫技式的"全自动"，而是把那些重复的、机械的、跨系统转换的操作自动化，让人能把时间花在真正需要思考的事情上。<br>
这和我在之前文章里写过的一个观点是一致的：<strong>把领域里的做法显式化</strong>，让 AI 在边界内做推理，而不是期望它全知全能。</p>
<hr>
<p><strong>参考资料：</strong></p>
<ol>
<li>项目仓库：https://github.com/knqiufan/PingCraft</li>
<li>PingCode 开放平台：https://open.pingcode.com/</li>
<li>SeekDB 文档：https://www.seekdb.com/</li>
</ol>
</div>
<div id="MySignature" role="contentinfo">
<p>本文来自博客园，作者：knqiufan，转载请注明原文链接：https://www.cnblogs.com/knqiufan/p/19755015</p><br><br>
来源：https://www.cnblogs.com/knqiufan/p/19755015
頁:
[1]