来自博主的开源项目 ：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，焦点往往在"模型够不够聪明"、"Prompt 写得好不好"。但实际落地时，连接真实系统的能力 往往才是瓶颈。
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 兼容 + 向量） |
| AI | LangChain、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/