bb-search-protocol

职责

在项目 wiki/protocols/ 目录里按关键词搜索协议文档，返回匹配文件、行号、片段，供 bba-architect 用 Read 工具读取细节。

• 调用者：bba-architect
• 禁止使用：Task / Agent / Skill

Input Args

arg	type	required	默认	说明
pattern	string	true	—	关键词（uart / axi4 / ucie）
field	string	false	—	限定字段（baud / timing）
max_results	int	false	20	最多返回条数

Output Contract

field	值
artifact_path	— （inline 返回，不写文件）
matches	[{file:path, line:int, snippet:str}]
count	int
valid	bool

4-Phase 执行

Phase 1 — render_search_cmd

scripts/render_search.py 生成 rg 命令：

rg -i "<pattern>" wiki/protocols/ --include="*.md" -n -A 2 --max-count=<max_results>

如指定 field，叠加 && rg "<field>" 二次过滤。

Phase 2 — run_search

scripts/run_search.py：

1. timeout 30 bash -c "<cmd>" > /tmp/protocol_search_<stamp>.txt 2>&1
2. 解析 rg file:line:content 三段格式

Phase 3 — parse_results

scripts/parse_results.py：

• 每行 <file>:<line>:<content> → 一条 match
• 聚合相邻行作为 snippet
• 统计 count

Phase 4 — return

返回 JSON。调用方 (bba-architect) 据 file 列表 Read 详细内容补充 PRD。

收敛 / 失败

状态	行动
count>0	有结果
count==0	调用方放宽 pattern 重试；超 3 次记录 gap: <pattern> 入 MAS
rg 不可用	退到 grep -r

MVP 覆盖

wiki/protocols/
├── uart.md
├── axi4-lite.md
└── ucie-overview.md  (planned, not yet available)

资源索引

• scripts/render_search.py、scripts/run_search.py、scripts/parse_results.py
• references/protocol_index.md — 已知协议清单