prd-to-md-mcp

把 Lark PRD 链接丢进来，自动在桌面生成一份英文、一份中文的结构化 Markdown。

输入：https://traveloka.sg.larksuite.com/wiki/xxxx
输出：~/Desktop/prd-en-20260609-143022.md
      ~/Desktop/prd-zh-20260609-143022.md

前置要求

安装前确认以下工具已就绪：

| 工具 | 说明 | |---|---| | Node.js ≥ 18 | nodejs.org | | VS Code + GitHub Copilot | 需要 Agent 模式 | | opencode | 已安装 + 配置好 API key | | Lark MCP | 已在 opencode 里配置好 Lark 账号权限 |

opencode 和 Lark MCP 是硬依赖，缺一不可。

安装

npm install -g prd-to-md-mcp

安装完成后自动输出：

✅ MCP server registered  →  ~/...Code/User/mcp.json
✅ Prompt file installed  →  ~/...Code/User/prompts/prd-to-md.prompt.md

👉 Restart VS Code, then use in Agent:
   #prompt:prd-to-md.prompt.md <lark-url>

重启 VS Code，安装完成。

使用

方式一：VS Code Agent（推荐）

打开 Copilot Chat，切换到 Agent 模式，输入：

#prompt:prd-to-md.prompt.md https://traveloka.sg.larksuite.com/wiki/xxxx

Agent 自动完成读取 → 生成 → 告知文件路径，全程显示进度条：

⏳ [1/3] Validating URL and preparing…
🔄 [2/3] Fetching Lark document and generating Markdown…
✅ [3/3] Complete!
EN → ~/Desktop/prd-en-20260616_143022.md
ZH → ~/Desktop/prd-zh-20260616_143022.md

方式二：直接运行脚本

适合在 CI 或终端批量处理：

# 需要 clone 仓库
git clone https://github.com/yuhao05/prd-to-md-mcp.git
cd prd-to-md-mcp && npm install

bash scripts/prd-to-md.sh "https://traveloka.sg.larksuite.com/wiki/xxxx"

输出说明

| 文件 | 内容 | |---|---| | prd-en-<timestamp>.md | 英文版：结构化 + 完整翻译 | | prd-zh-<timestamp>.md | 中文版：保留原文表述 |

两份文件均包含：背景、目标、用户故事、功能需求、非功能需求、边界条件、验收标准。

工作原理与进度显示

npm install -g prd-to-md-mcp
  └─ postinstall → 注册 MCP 到 VS Code 用户配置
               → 复制 prompt 文件到 VS Code prompts 目录

#prompt:prd-to-md.prompt.md <lark-url>
  └─ Agent 调用 bash scripts/prd-to-md.sh

⏳ [1/3] Validating URL and preparing…
🔄 [2/3] Fetching Lark document and generating Markdown…
   ├─ → [1/2] Fetching Lark document via opencode...
   └─ → [2/2] Saving to Desktop...
✅ [3/3] Complete!
EN → ~/Desktop/prd-en-*.md
ZH → ~/Desktop/prd-zh-*.md

━ 可选：手动质量检查

node scripts/validate-prd.js ~/Desktop/prd-en-*.md

🔍 Running quality checks...
  [1/7] Checking required sections... 14%
  [2/7] Validating heading hierarchy... 29%
  [3/7] Checking table formatting... 43%
  [4/7] Calculating Flesch-Kincaid grade... 57%
  [5/7] Analyzing sentence length... 71%
  [6/7] Analyzing paragraph length... 86%
  [7/7] Detecting clarity pitfalls... 100%
✅ Quality check complete: 6/7 checks passed

✨ 新增：可选的质量保证工具

生成文档后，可以运行 validate-prd.js 检查质量（非自动集成）：

质量检查项

✅ 结构检查
   - 包含必要章节（背景、目标、需求、验收标准）
   - 标题层级正确（H1 → H2 → H3，无跳层）
   - 表格单元格对齐

✅ 可读性检查
   - Flesch-Kincaid 等级（目标 6-8）
   - 句子平均长度（目标 < 20 词）
   - 段落平均长度（目标 < 5 句）

✅ 清晰性检查
   - 隐形复数（"file retrieval" vs "the file is retrieved"）
   - 模糊代词（"it" 指代不清）
   - 名词化过度（"Upon completion" vs "After completes"）
   - 堆积修饰词（"public repository default settings" 顺序）

✅ 术语一致性
   - EN ↔ ZH 术语映射（见 docs/TERMINOLOGY.md）
   - 技术术语保持原文（API 路径、字段名）

使用方法

# Step 1: 生成文档（opencode + MCP 调用）— 不能修改
bash scripts/prd-to-md.sh "https://lark.com/your-prd"

# Step 2: 手动运行质量检查（可选）
node scripts/validate-prd.js ~/Desktop/prd-en-*.md

# 输出：进度条 + JSON 报告
# 🔍 Running quality checks...
#   [1/7] Checking required sections... 14%
#   [2/7] Validating heading hierarchy... 29%
#   ...
#   [7/7] Detecting clarity pitfalls... 100%
# 
# ✅ Quality check complete: 6/7 checks passed

📚 质量指南

• 详细指南：docs/QUALITY_GUIDE.md
• 术语映射：docs/TERMINOLOGY.md
• Prompt 参考：.github/prompts/prd-to-md.prompt.md

常见问题

Q：运行后没有输出文件？
检查 opencode 是否能正常调用 Lark MCP，确认 Lark 账号有该文档的阅读权限。

Q：VS Code Agent 里找不到 #prompt:prd-to-md.prompt.md？
重启 VS Code 后再试。如果仍然没有，手动确认文件是否存在：

ls ~/Library/Application\ Support/Code/User/prompts/prd-to-md.prompt.md

Q：提示 opencode: command not found？
参考 opencode 安装文档 完成安装并配置 API key。

License

MIT