06 — research：Bruno 示例注入机制（再生会不会覆盖手改）

Type: research Status: resolved Blocked by: —

Question

回答「接口文档示例怎么落才不会被 bruno-sync 再生冲掉」：

读 bruno-sync skill 与其源码（本仓库 bruno-sync.config.json / bruno-sync.local.json 指向 D:/code/crm-api-docs），弄清：/bruno-sync 再生时对已存在 .bru 文件是整文件重写还是字段级合并——手改的 body/query 示例值会不会被重置；
看 D:/code/crm-api-docs 集合实际格式：请求示例（body params / query）在 .bru 里的落点；Bruno 是否支持 example 块 / docs 字段承载「示例值 + 说明」；
给出示例注入方案：
- (a) 合并式 sync、手改安全 → 直接改 .bru，给出改法模板；
- (b) 再生会覆盖 → 示例放哪（单独 examples 目录 / docs 字段 / 给 sync 工具加 example 支持），推荐其一。

产出：.scratch/opportunity-e2e/research-bruno-examples.md（结论 + 推荐方案）。票 11 按此执行。

（20260828 research 完成）产出 research-bruno-examples.md。结论：方案 (a) 合并式 sync、手改安全 → 票 11 直接改 .bru。

再生是字段级合并非整文件重写：SKILL.md 铁律 1「结构听源码，表述听人」——手改实参值/说明文字/示例值再生时逐字保留；skill 只对结构（参数条目集合/类型/必填/默认/响应字段骨架）做行级 patch；对账钥匙 = METHOD+路径（tag 分组下加 tag 段）；想重来 = 删文件重跑（唯一重建通道）；无 generated 标记的文件是私产永不动。
示例落点：Bruno 原生无 example 块；docs 块（Markdown 渲染）即「示例值+说明」承载机制（四个 H2 段），可发送实参在 body:form-urlencoded/params:query 块。已抽 商机模块/商机管理/商机分页.bru 验证实际格式。
票 11 执行手册（research 文档内）：实参块换 E2E 实测真实值 → docs 请求示例同步 → 说明自由增补；三条纪律：保持 tags:[generated]、docs 首行钥匙勿动、复杂字段按 json-string-in-form。

关键事实：sourceRoots 含 crm-opportunity+crm-rule（规则族 25 端点此前未入集合，票 11 补齐后再生即可）；同一接口挂 N 个 tag 生成 N 副本各自独立对账。