1. 为什么Spec提取必须以Prompt为核心
在传统软件开发流程中，需求规格说明（Spec）的提取一直是个痛点。我曾参与过多个大型企业级项目，亲眼目睹开发团队花费数周时间手工编写解析器，结果却因为需求变更而前功尽弃。这种痛苦经历促使我开始探索LLM驱动的解决方案。
1.1 传统解析器的三大死穴
去年为某金融系统做遗留代码改造时，我们团队遇到了典型困境：
- 需要从200多份Word/PDF/Excel文档中提取API规范
- 文档格式五花八门（有的甚至是扫描件）
- 业务术语存在大量历史遗留的模糊表述
我们尝试了三种传统方案：
- 正则表达式：对格式规整的文档有效，但遇到表格嵌套立即失效
- 解析库组合（如Apache POI+PDFBox）：能提取文字但丢失语义关联
- 商业工具：特定领域效果尚可，但无法适配我们的业务术语
最终统计显示：
- 开发解析器耗时3人月
- 维护成本占项目总工时15%
- 准确率仅达到68%（人工校验后）
1.2 LLM带来的范式转变
当首次用GPT-4尝试解析一份混乱的需求文档时，效果令人震惊。它不仅正确识别了分散在多个段落中的接口参数，还自动补充了业务场景说明。这促使我系统性地对比了两种范式：
| 维度 | 传统方案 | LLM方案 |
|---|---|---|
| 开发周期 | 周/月级 | 小时级 |
| 多格式支持 | 需单独适配 | 原生支持 |
| 语义理解 | 仅语法解析 | 上下文推理 |
| 迭代成本 | 需修改代码 | 调整Prompt即可 |
| 模糊处理 | 必须明确规则 | 概率性输出合理结果 |
典型案例：某物联网设备协议文档中存在"当温度过高时..."的模糊描述。传统方案必须明确定义"过高"的阈值，而LLM能结合上下文推断出合理的数值范围。
1.3 Prompt工程的特殊价值
经过数十个项目的实践，我总结出Prompt在Spec提取中的不可替代性：
语义桥梁作用
- 将非结构化需求 → 结构化Spec
- 将业务术语 → 技术参数
- 将模糊描述 → 明确约束
动态适应能力
- 同一套Prompt可处理：
- 中文/英文文档混排
- 图文结合的说明
- 甚至会议录音转写的文本
实时修正机制
当发现解析偏差时，不需要改代码：
- 在Prompt中添加反例："注意：不要将'用户ID'误认为'客户编号'"
- 增加约束："所有时间参数必须转换为UTC格式"
- 效果立即提升
关键心得：Prompt本质上是在教LLM如何"阅读"业务文档，这比编写解析代码更接近需求分析的本质。
2. Skill化设计的工程实践
在将LLM应用于实际生产环境时，最大的挑战不是模型效果，而是工程化管理。我们开发的OpenSpec框架通过Skill机制解决了这个问题。
2.1 Skill的解剖结构
一个完整的Spec提取Skill包含以下核心组件：
code复制spec_extract_skill/
├── SKILL.md # 能力定义
├── prompts/ # Prompt模板库
│ ├── 01_identify.md # 阶段1：识别文档类型
│ ├── 02_parse.md # 阶段2：核心解析
│ └── 03_validate.md # 阶段3：逻辑校验
├── config.yaml # 参数配置
└── testcases/ # 测试用例
├── api_doc.pdf # 示例输入
└── expected.json # 预期输出
SKILL.md 示例
markdown复制# Spec提取技能
## 能力描述
从混合格式文档中提取结构化API规范，支持：
- RESTful接口描述
- 数据库Schema定义
- 状态转换规则
## 执行流程
1. 文档类型识别 → prompts/01_identify.md
2. 主体内容解析 → prompts/02_parse.md
3. 逻辑一致性检查 → prompts/03_validate.md
## 预期输出
JSON格式，包含：
- endpoint
- method
- params
- response
2.2 与传统脚本的对比
在某电商平台项目中的实测数据：
| 指标 | Python脚本方案 | Skill方案 |
|---|---|---|
| 代码行数 | 2,300行 | 4个Prompt文件 |
| 新格式适配 | 需要2天开发 | 添加测试用例即可 |
| 平均响应时间 | 1.2秒 | 3.5秒 |
| 准确率 | 82% | 91% |
| 异常处理 | 需要显式编码 | LLM自动尝试修复 |
虽然Skill方案在纯速度上稍慢，但其综合优势明显：
- 可维护性：修改业务规则只需编辑Prompt文本
- 可解释性：每个处理阶段都有明确的Prompt对应
- 可复用性：基础Prompt可跨项目共享
2.3 关键实现技巧
Prompt分阶段设计
-
识别阶段：用少量示例教会LLM判断文档类型
text复制
请判断以下文档的主要类型： [文档内容...] 可选类型：API文档/数据库设计/业务流程/其他 示例： "GET /user/{id}" → API文档 "CREATE TABLE users..." → 数据库设计 -
解析阶段：采用思维链(Chain-of-Thought)提示
text复制
请按以下步骤处理： 1. 找出所有接口定义 2. 识别每个接口的： - HTTP方法 - 路径参数 - 查询参数 - 请求体结构 3. 输出JSON格式 -
校验阶段：添加业务规则约束
text复制
检查提取结果是否符合： - 所有日期字段格式必须为YYYY-MM-DD - 金额字段必须包含currencyType - 分页参数必须包含pageSize和pageNum
配置管理艺术
在config.yaml中定义变量：
yaml复制output:
format: json
required_fields:
- name
- version
- endpoints
validation:
strict_mode: true
skip_unknown: false
避坑指南：避免在Prompt中硬编码业务规则，应该通过config.yaml注入，这样同一套Prompt能适应不同客户的规范要求。
3. 完整工作流解析
让我们通过一个真实案例演示OpenSpec的工作流程。某物流系统需要从混合文档中提取200+个API规范，文档包含：
- Word格式的需求说明书
- PDF格式的接口清单
- Excel格式的字段映射表
3.1 阶段一：智能预处理
文档类型识别Prompt
text复制请分析文档内容特征并选择最匹配的类型：
1. API文档 - 包含HTTP方法/路径/参数等
2. 数据模型 - 包含表/字段/关系描述
3. 业务流程 - 包含状态图/活动描述
4. 混合类型 - 同时包含以上多种
文档特征示例：
- "POST /api/v1/shipments" → 1
- "字段名|类型|长度|必填" → 2
- "司机接单后进入待装货状态" → 3
当前文档内容：
[用户上传的文档内容...]
处理策略
- 对混合类型文档自动启用拆分流程
- 为每种类型分配不同的解析Prompt
- 维护类型-Prompt的映射关系表
3.2 阶段二：自适应解析
字段提取的动态Prompt构造
python复制def build_field_prompt(doc_type):
templates = {
"API": "提取{method} {path}的...",
"DB": "分析{table}表的字段包括...",
"FLOW": "识别从{state1}到{state2}的..."
}
return templates[doc_type] + config["field_rules"]
处理复杂表格的技巧
当遇到合并单元格等复杂结构时：
- 先让LLM描述表格结构
- 再指导其按特定方式解析
- 最后进行交叉验证
示例Prompt：
text复制请按以下步骤处理此表格：
1. 识别表头行和对应列的含义
2. 处理可能存在的合并单元格
3. 将每行数据转换为如下JSON：
{
"field": "字段名",
"type": "数据类型",
"required": true/false
}
3.3 阶段三：智能校验
一致性检查机制
- 跨文档验证：确保接口A的输出匹配接口B的输入
- 业务规则检查：如"所有支付接口必须包含金额验证"
- 术语统一性：如"用户ID"不应同时存在"uid"和"userId"
典型校验Prompt
text复制请检查以下API规范是否符合要求：
1. 所有日期字段必须同时包含：
- 字段名以Date结尾
- 格式为ISO8601
- 时区明确指定
2. 分页响应必须包含：
- totalCount
- pageSize
- currentPage
3. 错误码必须来自标准列表
[自动插入标准错误码列表...]
4. 实战问题排查指南
在实际落地过程中，我们遇到了这些典型问题及解决方案：
4.1 文档质量差异问题
现象：
- 高质量文档准确率95%+
- 低质量扫描件准确率骤降至60%
解决方案：
- 前置OCR质量检测：
python复制def check_quality(text): return len(re.findall(r'[�□]', text)) / len(text) - 对低质量文档启用增强Prompt：
text复制
注意：本文档可能存在识别错误，请： - 优先识别清晰字段 - 对模糊内容标注[UNK] - 尝试结合上下文推测
4.2 领域术语混淆
典型案例：
- 医疗系统中"剂量"被误解析为"剂型"
- 金融领域"轧差"被当作错误词汇
优化方法：
- 构建领域词典：
yaml复制medical_terms: - name: "剂量" aliases: ["用量", "给药量"] definition: "每次用药的具体数量" - 在Prompt中注入术语说明：
text复制
特别注意以下专业术语： - "剂量"指...[详细定义] - "轧差"表示...[业务解释]
4.3 复杂逻辑遗漏
常见缺陷：
- 忽略接口间的依赖关系
- 漏掉异常流程分支
- 未捕获业务约束条件
检测方案：
- 实现逻辑图导出：
mermaid复制graph TD A[下单] --> B{库存检查} B -->|充足| C[生成订单] B -->|不足| D[通知补货] - 设计专项检查Prompt：
text复制
请分析是否存在： - 未处理的异常分支 - 缺少前置条件的操作 - 可能产生循环的流程
5. 性能优化关键策略
当处理大规模文档时，这些技巧能显著提升效率：
5.1 流式处理设计
传统方式：
- 全量加载文档
- 单次调用LLM处理
- 内存和响应时间瓶颈
优化方案：
- 按章节拆分文档
- 并行处理独立段落
- 增量合并结果
示例架构：
python复制def process_large_doc(doc):
chunks = split_by_chapter(doc)
with ThreadPool(8) as pool:
results = pool.map(process_chunk, chunks)
return merge_results(results)
5.2 缓存机制实现
高频内容缓存：
- 对标准字段描述（如"用户ID"）
- 常见错误模式修正
- 文档结构模板
缓存键设计：
python复制def make_cache_key(text):
return hashlib.md5(text.encode()).hexdigest()[:8]
5.3 混合精度解析
策略组合：
- 先用小模型（如GPT-3.5）快速初筛
- 对关键部分用大模型（GPT-4）精修
- 对简单表格使用传统解析器
条件路由示例：
python复制def route_processor(content):
if is_standard_table(content):
return parse_with_pandas
elif needs_deep_understanding(content):
return call_gpt4
else:
return call_gpt3
经过这些优化，在某个万页文档的解析任务中，我们将总耗时从预估的36小时压缩到4.5小时，同时保持了92%的准确率。