jorinyang 需求对齐差异分析
触发条件
用户需要基于PRD和多轮会议对齐结果，产出以需求项为核心的逐项对比分析文档时使用。
反向需求追溯：当用户不是要求产出分析文档，而是查询某个具体功能/字段的需求全貌时（如"XXX字段的需求是什么"），使用 references/requirement-tracing-reverse-lookup.md 中的反向查找工作流。两者共享源材料读取方法，但输出形式不同。
核心原则
以需求项为核心，逐项追踪多轮状态变化。 不使用散落的分类列表，每个需求项作为一行，在统一表格中展示 PRD → 第一次对齐 → 第二次对齐 的完整演变。
文档格式
表格结构
每个模块一张表，列结构：
| 序号 | 需求项 | 状态 | PRD v2.0 | 第一次对齐 (日期) | 第二次对齐 (日期) |
状态标注（中文+emoji）
- 🟢 原有/已对齐 — 三轮均一致，或PRD提出后后续对齐确认无变化
- 🟡 差异/调整 — 与PRD或前次对齐结果不一致，需说明原设计、变更后、变更原因
- 🔵 新增 — PRD及前次对齐均未涉及，本次新提出
- 🔴 待确定 — 已提出但尚未最终确定
文档结构
标题: <系统名> - 第X次需求对齐差异分析
版本/日期/编制人 + 对照基线说明 + 状态标注图例
一、主数据管理 （表格）
二、采购管理 （表格）
三、销售管理 （表格）
四、仓库管理 （表格）
五、[新增模块] （表格，标注"新增模块"）
...
N、待确定事项汇总 （表格：事项|责任方|期望时间）
N+1、关键决策与共识（列表）
反例（禁止）
❌ 先列"已对齐"再列"差异"再列"新增" — 无法看出需求项演变轨迹 ❌ 不标注状态 — 无法快速识别确认/变化/新增 ❌ 英文状态标注 — 中文语境应使用中文标注
失败模式与降级策略
| 触发条件 | 症状 | 修复方案 | 降级方案 |
|---|---|---|---|
| docx 节点实为上传文件 | 3380002: Unsupported document type 'file' |
改走 wiki +node-get → drive +download 下载后读取 |
请用户手动复制文档内容为飞书原生文档 |
| wiki 下载缺 scope | wiki +node-get 报 missing_scope |
lark-cli auth login --scope "wiki:node:retrieve" 授权 |
请用户直接在对话中粘贴源材料文本 |
| PDF 文本提取失败 | PyPDF2 报错或输出乱码/空白 | 尝试 pdftotext 或 marker-pdf 备用工具 |
标注"⚠️ PDF解析失败"，请用户提供文本版 |
| 源材料内容为空 | 读取成功但无有效文本输出 | 检查文件是否损坏，尝试重新上传/导出 | 跳过该材料，在报告中标注"📭 待补充" |
| 缺少模块范围定义 | 源材料中无明确模块列表 | 从会议纪要和PRD标题中推导模块边界 | 使用通用模块模板，标注"⚠️ 模块待确认" |
| 多轮对齐缺少日期 | 源材料中无会议日期信息 | 从文件名/飞书文档元数据中提取 | 标注为"日期待补充"，不阻塞分析 |
工作流
并行读取所有源材料（PRD + 所有轮次的录音转写 + 会议纪要）
工作流
第一步：读取源材料
源材料可能是飞书原生文档（docx）或 wiki 上传文件（PDF/txt/md）。按以下优先级尝试：
- 首选
lark-cli docs +fetch --api-version v2 --doc "<URL>" --as user - ⚠️ 若返回
3380002: Unsupported document type 'file'→ 节点是上传文件，改走 wiki 下载路径：lark-cli wiki +node-get --as user --node-token "<URL>" --format json获取obj_tokenlark-cli drive +download --file-token "<obj_token>" --output "./filename.ext" --as user- ⚠️
wiki +node-get需要wiki:node:retrievescope，缺失时报missing_scope→ 走 split-flow 授权：lark-cli auth login --scope "wiki:node:retrieve" --no-wait --json # → 用 verification_url 生成 QR code 发给用户 # → 用户确认后执行 lark-cli auth login --device-code <code> - 下载路径仅接受相对路径，建议
cd /tmp后下载
- PDF 文件用 PyPDF2 提取文本：
python3 -c "import PyPDF2; ..." - 优先读纪要（含结构化结论），转写用于补充细节和确认语境
🔍 CHECKPOINT D4-1：源材料读取完成。 确认：(a) 每个源材料已成功读取并包含有效文本内容；(b) 状态标注图例（🟢🟡🔵🔴）已就绪。如任一材料读取失败或为空，查看下方「失败模式与降级策略」选择对应降级路径，不得继续进入交叉对比。
第二步：交叉对比
逐模块梳理需求项，追踪 PRD → 每轮对齐的状态变化。
第三步：标注状态
"差异"项必须写清：原设计 → 变更后 → 变更原因。
🔍 CHECKPOINT D4-2：交叉对比与标注完成。 确认：(a) 所有模块的需求项已逐项追踪 PRD→第一次对齐→第二次对齐 完整链条；(b) 每个需求项状态（原有/差异/新增/待确定）已正确标注；(c) 所有差异项包含完整的三段式说明 原设计→变更后→变更原因；(d) 待确定事项已汇总。通过后方可产出飞书文档。
第四步：产出飞书文档
- 先写本地 Markdown 文件
- 再
lark-cli docs +create --api-version v2 --doc-format markdown --content @文件路径 --as user - 对于长文档（>10KB），直接全量传入 Markdown（
@file）即可，飞书 API 支持
第五步：验证
lark-cli docs +fetch --api-version v2 --doc "<新文档URL>" --as user检查所有表格和章节完整渲染- 首选