Searchlight radar

searchlight-radar · 术语雷达与流程编排器

探照灯工作流的唯一入口与编排器。提取术语、归一黑话、生成快照，判定走对话框还是调度 searchlight-board（网页），再把上下文路由给 searchlight-narrative / searchlight-lecturer / searchlight-curator。本 skill 只编排，绝不自己讲解，也绝不自己启动网页 server——讲解归 lecturer，网页交互归 board。

When to Activate

• 对话中用户遇到/提到陌生术语，或 AI 回复里出现一堆黑话，用户想"搞懂"
• 用户粘贴一篇满是术语的密集文章/文档，要快速建立认知
• 用户给出文件路径要求"拆解这篇文章""讲讲里面这些概念"
• 用户明确说"探照灯""术语""黑话""看不懂""这段在讲什么""快速认知"

Role（编排器铁律）

1. 提取 + 归一 + 快照：自己完成（语义推理，不写脚本）。
2. 判定交互模式：按 §交互模式判定规则，选对话框或调度 board。
3. 路由执行：根据用户选择，调用子 skill：
   • 要文章整体逻辑 → searchlight-narrative
   • 要术语深度讲解 → searchlight-lecturer
   • 要沉淀成知识文档 → searchlight-curator
   • 要网页交互（框选/多选/可视化） → searchlight-board
4. 追问路由：子 skill 执行中，用户的追问/补充由本 skill 路由给当前活跃子 skill，不重启流程。

绝对不做：自己写文脉追踪、自己写术语讲解、自己整理知识卡片、自己启动 web server——这些必须交给对应子 skill。

输入来源（三种，自动合并）

来源	处理方式
对话上文	默认。无显式"全文"时，把近期对话累积作为语境
文件路径	用 read 工具读取（支持 .md/.txt/.代码）
粘贴片段	用户直接贴的长文，视为"全文"首选

多来源同时存在时：粘贴片段 > 文件 > 对话上文（更具体的优先）。

Workflow（状态机）

Step 1 · 收集输入

确认"分析对象"是什么：扫一遍对话上文 + 用户给的路径/粘贴，合并出一份 原文。若对象不明确（既没贴文也没给路径，对话也很短），先问一句"分析哪段内容？贴过来或给个文件路径"。

Step 2 · 术语提取 + 黑话归一 + 快照

对原文做语义提取（纯推理，不调脚本）：

1. 提取：扫出所有"不懂它就误判文章决策逻辑"的术语（不是所有名词，是关键认知门槛）。

2. 黑话归一：同一技术的不同叫法合并成一个条目。例：

   • Continuous Batching / In-flight Batching → 归一为 Continuous Batching（同一技术，两个名字）
   • Key-Value Cache / KV Cache → 归一为 KV Cache（同一技术，两个名字）

   ⚠️ 不要合并"同类但不同"的方法（这是最常见的归一错误）：

   • Pearson 与 Spearman 相关系数 —— 参数 vs 非参数，不同方法，分开列
   • 配对 t 检验 与 Wilcoxon 符号秩检验 —— 参数 vs 非参数，不同方法，分开列
   • 归一只针对"同一技术的别名"，不针对"解决同类问题的不同方案"。

3. 快照：每个术语生成一句话工程快照（"它是干什么的"，不是"它定义是什么"）。

4. 角色标注：每个术语在文中的角色 = 地基 / 支柱 / 桥梁 / 结果。

5. 黑箱风险：补一句"不懂它会误以为___"。

6. AI 预选：在全部提取出的术语里勾选你认为最该讲的（ai_selected: true），给出预选理由。未预选的术语仍要完整列在清单里（ai_selected: false）——预选是"建议"，不是"筛选"，不许藏起未预选的术语。

提取完整性优先：扫出原文里所有"不懂就误判决策"的关键术语（典型 5-12 个，密集文章可能 15+）。穷尽提取，绝不替用户筛选。术语多正是 board 的价值所在（见判定规则），不要为了走对话框而砍术语。

Step 3 · 判定交互模式

按 §交互模式判定规则，自主选 对话框 或 调度 board。先告诉用户选了哪种、为什么（透明），再执行 Step 4。

Step 4 · 用户确认选择

4a · 对话框清单模式（轻量）

直接在回复里输出编号清单（见 §对话框清单格式）。用户回复编号微调即可。补漏术语：清单末尾留一行"还有没列出来的？直接说，或要我开网页给你框选"。

对话框模式的限制：无法框选原文、无法补漏术语（只能打字描述）、无法启用可视化增强（mermaid 表/演示小程序/本地渲染都只在网页可用）。用户要这些功能时，转 4b。

4b · 调度 searchlight-board（网页交互）

判定为网页模式时：

1. 你（radar）写 pending.json 到交换目录 %TEMP%\opencode\searchlight\<session_id>\。schema 见 searchlight-board/SKILL.md（含原文 + 全部术语 + AI 预选 + step_options，step_options 里带上 viz 可选项让用户勾）。
2. 加载 searchlight-board skill，由它启动 server、开浏览器、轮询 done.flag、读 result.json、自动关页。
3. board 返回三种终止态之一（done / cancel / timeout），按状态分支：
   • done：读 result.json，按用户选择走 Step 5（路由 lecturer/curator）
   • cancel：用户主动取消（点取消/关网页），停止本次探照灯流程（不调下游），问用户"要重来吗"
   • timeout：空闲超时/用户离开，停止等待，提示用户"网页可能关了，要重开吗"

pending/result schema、启动命令、轮询、自动关页细节全在 searchlight-board/SKILL.md。你只负责：写 pending、读 result、透传给下游。不要自己跑 searchlight_server.py。

Step 5 · 路由执行

按用户最终选择组装上下文（见 §上下文组装），调用子 skill：

用户要	调用	备注
文章整体逻辑	searchlight-narrative	文章级，可选
某几个术语深讲	searchlight-lecturer	术语级，可批量，每个独立
沉淀成知识文档	searchlight-curator	可选

两者同时要：先 narrative 后 lecturer（先整体后局部）。子 skill 输出流式回到对话框，Markdown 实时渲染。

透传 viz：若 result.viz 有勾选（mermaid/demos/render），组装上下文时带上，lecturer/curator 据此启用可视化增强。

固化是可选步骤：若用户在 Step 4 没指定 persist，输出完成后问一句"要不要存进知识库？"，要则调用 searchlight-curator。

Step 6 · 追问路由

子 skill 输出中/输出后，用户追问（"等等，这里的权衡指什么"）：

• 把追问 + 当前活跃子 skill 的上下文一起路由回去，不重启 radar 流程。
• 用户要换目标（"别讲这个，换讲另一个"）→ 中断当前，回 Step 5 路由新目标。
• 用户要补框选 → 注入当前子 skill 上下文。

对话框清单格式

## 🔦 探照灯 · 术语清单（共 N 个，已预选 M 个）

> 文章一句话：{article_summary}
> 建议路径：{suggested_path}

| # | 术语 | 别名 | 一句话快照 | 角色 | 选 |
|---|------|------|-----------|------|----|
| 1 | KV Cache | Key-Value Cache | 用内存冗余消除重复注意力计算 | 地基 | ✓ |
| 2 | PagedAttention | 分页注意力 | 按页管理 KV Cache 显存 | 支柱 | ✓ |
| 3 | GQA | 分组查询注意力 | 多 query 共享 KV 换显存减半 | 桥梁 | ○ |

**回复示例**：「去掉2，加讲5，全文逻辑也要」
**还有没列出来的？** 直接说术语名，或回复「开网页」让我给你框选。
**后续步骤**：回复「存知识库」可沉淀；要 mermaid 表/演示代码/本地预览回复「开网页」。

✓ = AI 预选，○ = 未选。角色用文字标注。用户回复编号即可微调。

清单本身不限数量（表格能容纳 10+ 行）。但术语 >7 或用户要框选/详解/固化/可视化时，走 board 更舒适（见判定规则）。不要为了"清单好看"而砍术语。

交互模式判定规则

⚠️ 本末倒置警告：规则是"提取完术语 + 理解用户意图 → 选交互方式"，不是"为了走对话框把术语砍到 ≤7"。术语多/要详解/要可视化 → 走 board，这正是 board 的设计目的。砍术语凑对话框 = 剥夺用户选择权，严重违规。

条件（任一命中）	模式
术语 ≤ 7 且用户未要求详解/框选/固化/可视化	对话框
术语 > 7	board
用户说"详解/深度/讲透/彻底/系统讲"	board（详解输出长 + 可视化增强只在网页）
用户要固化（"存知识库/沉淀/做成卡片"）	board（固化配置在网页更方便）
用户说"框选/精选/补几个/我没看到 XX"	board
用户要可视化增强（mermaid 表/演示小程序/本地渲染）	board（这些只在网页模式可用）
原文 > 2000 字且需并排阅读	board
用户拒绝对话框（"给我个界面/开网页"）	board
其余	对话框（默认）

判准已解耦：不再只看术语数量。用户语言里的"详解/固化/可视化"意图同样触发 board。对话框适合少量术语的快速确认；board 适合术语多/详解/固化/框选/可视化的场景——两者分工，无优劣。

上下文组装规范

调用子 skill 时，传递的上下文必须包含：

{
  "article_full_text": "原文",
  "user_selected_terms": ["canonical_name"],
  "user_selected_context": "框选片段（对话框模式下用户补充的文本）",
  "user_added_terms": [{"name": "...", "text": "..."}],
  "user_note": "补充指令",
  "scope": "fulltext|selected_terms",
  "persist": "none|temp|perm",
  "perm_path": "null 或用户指定路径（perm 模式；留空=默认 skill 仓库 knowledge/）",
  "domain": "AI 预填的领域分类，用户可改",
  "session_id": "sl_<timestamp>",
  "viz": {"mermaid": false, "demos": false, "render": false}
}

viz 来自 board 的 result（对话框模式全 false）。lecturer 见 viz.mermaid=true 用 mermaid 画表、viz.demos=true 把代码写文件；curator 见 viz.render=true（或 lecturer 完成后）可调 board 启动本地渲染。

Output Format

每次激活后，对话里应出现：

项	期望
文章一句话摘要	有
术语清单（编号+快照+预选）	有
选择的交互模式 + 理由	有（透明）
路由到的子 skill	明确告知
固化询问（若未预先指定）	输出完成后有

Constraints

• 禁止为走对话框而精选/砍术语（严重违规）：提取阶段穷尽所有关键术语；术语多/要详解/要可视化就走 board。替用户筛选"哪些值得讲" = 越权。
• 黑话归一只合并"同一技术的别名"，不合并同类但不同的方法（Pearson ≠ Spearman，t 检验 ≠ Wilcoxon）。
• 未预选（ai_selected: false）的术语必须留在清单里——预选是建议，不是筛选。
• 只编排，不越界讲解（讲解交给 narrative/lecturer），不自己启动 web server（交给 board）。
• 术语提取纯推理，不调脚本。
• 判准解耦：术语数、详解意图、固化意图、框选意图、可视化意图任一命中即走 board。
• 选了 board 就先把 pending.json 写完整（原文+全部术语+预选+step_options 含 viz），让用户在浏览器里只需微调。
• 一次会话一个 session_id，追问复用同一 session，不重启。
• 中文触发词同时写进 description 和 tags（registry 会截断 description 到 100 字符，tags 完整保留）。

Files in this skill

searchlight-radar/
└── SKILL.md

网页交互脚本（server/exchange/html）在 searchlight-board/；知识固化脚本在 searchlight-curator/。