Searchlight board

searchlight-board · 网页交互层（被 radar 调度）

探照灯工作流的本地 web 界面。CLI 做不好的事（框选原文、补漏术语、>7 个批量勾选、并排阅读、可视化增强配置）交给它。被 searchlight-radar 调度——radar 判定需要网页时加载本 skill，本 skill 启动 server、收集用户选择、返回 result，radar 再继续路由 lecturer/curator。

When to Activate

• 只被 searchlight-radar 调度，不直接对用户激活。
• radar 判定命中以下任一即加载本 skill：术语多 / 用户要详解 / 要固化 / 要框选 / 要可视化增强。

Role

你是探照灯的网页交互层。职责：把 radar 组装的 pending 数据渲染成网页 → 用户勾选/框选/配置 → 提交后写 result → 自动退出。你不提取术语、不讲解、不固化——那些是 radar/lecturer/curator 的事。你只管"交互收集"。

可视化增强选项（三项，额外 token，网页里勾选）

这三项默认关闭，用户在网页勾选才启用（传给 lecturer/curator 执行）。对话框模式无法启用（没有 UI）：

选项	result 字段	谁执行	关联 skill
关联表用 Mermaid 画（回扣表/对比表）	viz.mermaid	lecturer	format-md-mermaid（避免渲染坑）
演示小程序写文件（可运行代码落盘）	viz.demos	lecturer	—
本地 md 渲染（go-grip 预览生成的 md）	viz.render	board（见下）	format-md-toolchain（go-grip 安装/用法）

用户勾选 → 进 result.viz → radar 透传给下游。lecturer 见 viz.mermaid=true 就用 mermaid 画表；见 viz.demos=true 就把代码写到文件。

启动流程

1. 接收 pending 数据

radar 组装好 pending.json（原文 + 术语 + AI 预选 + step_options），告诉你交换目录路径。

2. 启动 server（必须用 WScript.Shell，脱离 bash 工具的进程树）

⚠️ 禁止用 Start-Process 或直接 python ...：opencode 的 bash 工具用 Windows Job Object 管理进程树，命令结束时整个 Job Object（含所有子进程）会被一并 TerminateProcess，server 会跟着死（实测：bash 命令一返回 server 就退出）。必须用 WScript.Shell COM 启动——它创建的进程脱离当前 Job Object，bash 命令结束后仍存活。

$script = "<REPO>/searchlight-board\scripts\searchlight_server.py"
$pending = "<交换目录>\pending.json"
$log = "<交换目录>\server.log"
# cmd /c 双重作用：①让 cmd 解释 > 重定向 ②stdout→log 文件（隐藏窗口下 python 直接写 stdout 会崩，必须重定向）
$cmd = "cmd /c python `"$script`" --pending `"$pending`" --open-browser > `"$log`" 2>&1"
$ws = New-Object -ComObject WScript.Shell
$ws.Run($cmd, 0, $false)   # 0=隐藏窗口, $false=不等待（立即返回）

• --open-browser 自动开浏览器（用户不用手敲 URL）。
• server 启动后把实际端口写入同目录 port.txt、PID 写入 server.pid。
• 绑 127.0.0.1；空闲 15 分钟无操作 或 硬上限 30 分钟 自动退出（防僵尸）。

3. 读 port.txt，确认服务起来了

读 <交换目录>\port.txt 拿到端口，确认 http://localhost:<port>/ping 返回 pong。

4. 轮询三种终止 flag（done / cancel / timeout）

server 有三种终止态，分别写不同 flag。轮询时任一出现即跳出：

$ex = "<交换目录>"
while ($true) {
  if (Test-Path "$ex\done.flag")    { $status = "done";    break }
  if (Test-Path "$ex\cancel.flag")  { $status = "cancel";  break }
  if (Test-Path "$ex\timeout.flag") { $status = "timeout"; break }
  Start-Sleep -Seconds 2
}

• done = 用户点"提交"（正常完成）
• cancel = 用户点"取消"按钮 / 关闭了网页（beforeunload 发 sendBeacon，主动放弃）
• timeout = 空闲超时（无心跳 15 分钟）或硬上限（30 分钟），用户可能已离开

5. 按终止态分支处理，交回 radar

flag	你的动作
done	读 result.json，把内容（用户选择 + viz）告知 radar，radar 继续 Step 5 路由 lecturer/curator
cancel	告知 radar"用户取消了"，radar 停止本次探照灯流程（不调下游），问用户要不要重来
timeout	告知 radar"超时了，用户可能关了网页"，radar 停止等待，提示用户检查/重来

server 无论哪种终止都自动退出（done/cancel 走 _delayed_shutdown，timeout 走 watchdog 线程）。异常残留用 taskkill /PID <server.pid> /F 兜底。

6. 自动清理

server 提交后自动退出（_delayed_shutdown 0.6s 后 sys.exit）；浏览器端提交成功后尝试 window.close()（见下）。异常残留用 taskkill /PID <server.pid> /F 兜底。

三种终止态的生命周期

终止态	触发	server	浏览器	AI(board→radar)
提交	用户点"提交"	写 done.flag+result.json，0.5s 退出	显示✅ + window.close()	读 result → 继续路由
取消	用户点"取消" / 关网页	写 cancel.flag，0.5s 退出	显示🚫 + window.close()	告 radar 取消 → 停止流程
超时	无心跳 15min / 硬上限 30min	watchdog 写 timeout.flag，退出	（用户已离开）	告 radar 超时 → 提示用户

• 心跳保活：网页每 30s GET /heartbeat，用户在操作就不会空闲超时。
• 关页兜底：beforeunload 时若未提交，navigator.sendBeacon('/api/cancel') 发取消信号（不可靠，心跳超时是最终兜底）。
• 提交/取消：server + 浏览器都自动关（两道保险）。
• 超时：用户已离开，server 自动退出，AI 停止干等。

pending.json schema（radar 写，board 读）

{
  "session_id": "sl_<timestamp>",
  "mode": "select",
  "created_at": "ISO-8601",
  "article": {"text": "原文全文", "source": "chat|file|paste", "source_ref": "路径或对话标识"},
  "terms": [
    {"id": "t1", "canonical_name": "KV Cache", "aliases": ["Key-Value Cache"],
     "one_liner": "一句话快照", "role": "地基",
     "location": {"para": 3, "sent": 2}, "ai_selected": true,
     "blackbox_risk": "不懂它会误以为..."}
  ],
  "step_options": {
    "scope": ["fulltext", "selected_terms"],
    "persist": ["none", "temp", "perm"],
    "viz": ["mermaid", "demos", "render"]
  },
  "ai_preselect": {"scope": "selected_terms", "persist": "none",
                   "viz": {"mermaid": false, "demos": false, "render": false},
                   "rationale": "为什么这样预选"}
}

result.json schema（board 写，radar 读）

{
  "session_id": "sl_<timestamp>",
  "submitted_at": "ISO-8601",
  "selected_term_ids": ["t1", "t3"],
  "user_added_terms": [{"text": "原文框选片段", "name": "用户起的术语名", "location_hint": "para 4"}],
  "selected_contexts": ["框选的补充上下文片段"],
  "scope": "selected_terms",
  "persist": "perm",
  "perm_path": null,
  "domain": "llm-inference",
  "user_note": "自由补充",
  "viz": {"mermaid": true, "demos": false, "render": true}
}

本地 md 渲染（viz.render=true 时）

用户勾了"本地渲染"，lecturer/curator 输出 md 后，调 board 渲染：

go-grip "<生成的 md 文件路径>"

• 浏览器访问 http://localhost:6419/，支持 Mermaid/公式/代码高亮/热重载。
• 安装/参数/故障排查见 format-md-toolchain（go-grip 的权威参考）。
• 停止：终端 Ctrl+C，或 Get-Process go-grip | Stop-Process -Force。

关联 format-md-toolchain：go-grip 的安装、端口、暗黑模式、Mermaid CDN 等细节以它为准，本 skill 不重复。

Constraints

• 只被 radar 调度，不自己提取术语/讲解/固化。
• 启动前确认 pending.json 已由 radar 写完整（原文+全部术语+预选+step_options）。
• --open-browser 默认开（省得用户手敲 URL）。
• 轮询 done.flag 要有 15 分钟超时兜底，别死等。
• server 提交后自动退出 + 浏览器尝试自动关；留 about 页兜底。
• viz 三项默认全关，用户勾了才传 true。
• 本地渲染用 go-grip，细节查 format-md-toolchain，不在本 skill 重复。

Files in this skill

searchlight-board/
├── SKILL.md
├── scripts/
│   ├── searchlight_server.py   # 本地交互式 web 服务（动态端口·一次性·提交后自动退出）
│   └── exchange.py              # pending/result JSON 读写 + schema 校验
└── assets/
    └── select_page.html         # 选择页（框选/补漏/配置/viz 选项/提交后自动关）