You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
28 lines
2.4 KiB
28 lines
2.4 KiB
1 week ago
|
# 06 — research：Bruno 示例注入机制（再生会不会覆盖手改）
|
||
|
|
|
||
|
|
Type: research
|
||
|
|
Status: resolved
|
||
|
|
Blocked by: —
|
||
|
|
|
||
|
|
## Question
|
||
|
|
|
||
|
|
回答「接口文档示例怎么落才不会被 bruno-sync 再生冲掉」：
|
||
|
|
|
||
|
|
1. 读 bruno-sync skill 与其源码（本仓库 `bruno-sync.config.json` / `bruno-sync.local.json` 指向 `D:/code/crm-api-docs`），弄清：`/bruno-sync` 再生时对已存在 `.bru` 文件是**整文件重写**还是**字段级合并**——手改的 body/query 示例值会不会被重置；
|
||
|
|
2. 看 `D:/code/crm-api-docs` 集合实际格式：请求示例（body params / query）在 `.bru` 里的落点；Bruno 是否支持 `example` 块 / docs 字段承载「示例值 + 说明」；
|
||
|
|
3. 给出**示例注入方案**：
|
||
|
|
- (a) 合并式 sync、手改安全 → 直接改 `.bru`，给出改法模板；
|
||
|
|
- (b) 再生会覆盖 → 示例放哪（单独 examples 目录 / docs 字段 / 给 sync 工具加 example 支持），推荐其一。
|
||
|
|
|
||
|
|
产出：`.scratch/opportunity-e2e/research-bruno-examples.md`（结论 + 推荐方案）。票 11 按此执行。
|
||
|
|
|
||
|
|
## Answer
|
||
|
|
|
||
|
|
（20260828 research 完成）产出 `research-bruno-examples.md`。结论：**方案 (a) 合并式 sync、手改安全 → 票 11 直接改 `.bru`**。
|
||
|
|
|
||
|
|
1. **再生是字段级合并非整文件重写**：SKILL.md 铁律 1「结构听源码，表述听人」——手改实参值/说明文字/示例值再生时**逐字保留**；skill 只对结构（参数条目集合/类型/必填/默认/响应字段骨架）做行级 patch；对账钥匙 = METHOD+路径（tag 分组下加 tag 段）；想重来 = 删文件重跑（唯一重建通道）；无 `generated` 标记的文件是私产永不动。
|
||
|
|
2. **示例落点**：Bruno 原生无 example 块；`docs` 块（Markdown 渲染）即「示例值+说明」承载机制（四个 H2 段），可发送实参在 `body:form-urlencoded`/`params:query` 块。已抽 `商机模块/商机管理/商机分页.bru` 验证实际格式。
|
||
|
|
3. **票 11 执行手册**（research 文档内）：实参块换 E2E 实测真实值 → docs 请求示例同步 → 说明自由增补；三条纪律：保持 `tags:[generated]`、docs 首行钥匙勿动、复杂字段按 `json-string-in-form`。
|
||
|
|
|
||
|
|
关键事实：`sourceRoots` 含 crm-opportunity+crm-rule（规则族 25 端点此前未入集合，票 11 补齐后再生即可）；同一接口挂 N 个 tag 生成 N 副本各自独立对账。
|