SKILL: yak 脚本与 Yakit UI 交互机制

AI LOAD INSTRUCTION: yak 脚本不是孤立的命令行程序——在 Yakit 引擎中运行时，yakit.* 库函数会通过 gRPC ExecResult 双向流把结构化消息推送到前端，前端 useHoldGRPCStream 按 message type / log level 路由到 不同的 UI 组件（日志面板、进度条、表格、图表、风险列表、网站树...）。本页讲清这条完整链路，并给出每个 UI 输出函数的 API 速查与可运行示例。写插件时想"让界面显示 X"就从这里查。

0. 相关路由

• 总入口：yak
• Yakit 基本使用与功能区说明：yakit-basic
• 数据库操作（db 库）：yaklang-database
• 原生插件 + cli 参数表单：yakit-native-plugin
• 右键 codec 插件：yakit-rightclick-plugin
• 验证工具链：yaklang-toolchain

1. 核心智模型：从 yak 脚本到 UI 的完整链路

flowchart LR
    subgraph Script["yak 脚本 (引擎内执行)"]
        Call["yakit.Info(...)<br/>yakit.SetProgress(...)<br/>yakit.EnableTable(...)<br/>yakit.Output(table)"]
    end
    subgraph Bridge["gRPC 桥接 (引擎 -> 前端)"]
        Client["YakitClient.send()<br/>封装为 ExecResult"]
        Stream["gRPC 双向流<br/>ExecResult.IsMessage=true<br/>Message=JSON(YakitMessage)"]
    end
    subgraph Frontend["Yakit 前端"]
        Hook["useHoldGRPCStream<br/>解析 YakitMessage"]
        Route{"type / level<br/>路由"}
        UI["日志面板 / 进度条<br/>表格 / 图表 / 卡片<br/>风险列表 / 网站树"]
    end
    Call --> Client --> Stream --> Hook --> Route --> UI

关键理解：

1. yakit.* 函数不是直接操作 DOM：它们构造 YakitLog / YakitProgress / YakitFeature 等结构体， 通过 YakitClient.send() 发出。
2. send 的两种模式：
   • VirtualYakitClient（命令行 yak xxx.yak）：send 回调把 ExecResult 打印到 stdout（log.Info）。
   • gRPC YakitClient（Yakit 引擎环境）：send 把 ExecResult 通过 gRPC 双向流推到前端。
3. 前端按 type + level 路由：useHoldGRPCStream 解析 YakitMessage JSON，按 type（log/progress/ status-card）和 logData.level（json-feature/feature-table-data/json-risk/info/warn/...） 分发到不同 UI 组件。

源码定位：

• 引擎侧导出：yaklang/common/yak/yaklib/yakit.go（YakitExports / GetExtYakitLibByClient）
• Client 实现：yaklang/common/yak/yaklib/yakit_client.go（YakitClient.Output / YakitLog / send）
• 消息序列化：yaklang/common/yak/yaklib/yakit.go（MarshalYakitOutput / YakitMessageGenerator）
• 前端消费：yakit/app/renderer/src/main/src/hook/useHoldGRPCStream/useHoldGRPCStream.ts

2. 消息协议：YakitMessage 结构

引擎到前端的每条消息都是 ExecResult{IsMessage: true, Message: JSON}，其中 Message 是 YakitMessage 的 JSON 序列化：

// yaklang/common/yak/yaklib/yakit.go
type YakitMessage struct {
    Type    string          `json:"type"`    // "log" / "progress" / "status-card"
    Content json.RawMessage `json:"content"` // YakitLog / YakitProgress / YakitStatusCard
}

type YakitLog struct {
    Level     string `json:"level"`     // info/warn/error/success/debug/code/markdown/text/report/file/
                                         // json-feature/feature-table-data/feature-text-data/
                                         // json-risk/json-table/json-graph/json-httpflow/fingerprint/...
    Data      string `json:"data"`      // 内容或 JSON 字符串
    Timestamp int64  `json:"timestamp"`
}

前端 useHoldGRPCStream 消费逻辑（简化）：

// yakit/app/renderer/src/main/src/hook/useHoldGRPCStream/useHoldGRPCStream.ts
if (obj.type === 'progress') { /* 进度条 */ }
if (obj.type === 'log' && logData.level === 'feature-status-card-data') { /* 状态卡片 */ }
if (obj.type === 'log' && logData.level === 'json-feature') { /* 启用表格/网站树/文本标签页 */ }
if (obj.type === 'log' && logData.level === 'feature-table-data') { /* 表格行数据 */ }
if (obj.type === 'log' && logData.level === 'feature-text-data') { /* 文本标签页数据 */ }
if (obj.type === 'log' && logData.level === 'json-risk') { /* 风险列表 */ }
// 其余 log -> 日志面板

3. UI 输出函数分类速查

3.1 日志输出（日志面板）

注意：yakit.Info / yakit.Warn / yakit.Error 支持 printf 格式化（第一个参数是格式串）； yakit.Success / yakit.Text / yakit.Code / yakit.Markdown 不做 printf，需先用 sprintf / f-string 拼好。 log.info 是 printf 风格，打印含 % 的内容要用 log.info("%s", x) 占位，不能直接字符串拼接。

3.2 进度条

3.3 状态卡片（关键指标小卡片）

3.4 静态表格（一次性输出）

yakit.NewTable 是"收集完再统一展示"的静态表格。边扫边出结果用 EnableTable + TableData（见 3.5）。

3.5 动态表格（实时增量更新）

EnableTable 发送 json-feature(feature=fixed-table) 声明表格，TableData 发送 feature-table-data 逐行写入。用相同 uuid 再次写入可"更新"同一行。

3.6 图表

四种图表构造器签名完全一致，仅展示形态不同。图表对象通过 yakit.Output 发送，前端按 json-graph level 渲染。

3.7 网站树

3.8 文本标签页

3.9 DOT 图标签页

3.10 统一输出通道

yakit.Output 是"智能路由"——传入 *YakitTable 走 json-table，传入 *YakitGraph 走 json-graph， 传入 *schema.Risk 走 json-risk，传入 *fp.MatchResult 走 fingerprint，传入 *YakitFixedTableData 走 feature-table-data，传入 *YakitStatusCard 走 feature-status-card-data... 这意味着可以把扫描器的原生结果对象直接 Output 出去，由前端渲染成对应的卡片/表格。

3.11 风险与文件

3.12 流式输出

4. 完整示例：一个输出多种 UI 组件的插件

// 关键词: yakit.Output, EnableTable, TableData, StatusCard, SetProgress, NewTable, NewBarGraph, Markdown
// 适用: yak 原生插件（在 Yakit 中执行时各 UI 组件实时展示）

func runPlugin() {
    // 1. 进度条
    yakit.SetProgress(0)

    // 2. 状态卡片（关键指标）
    yakit.StatusCard("Targets", "0/10", "progress")

    // 3. 动态表格（边扫边出）
    yakit.EnableTable("Port Scan Result", ["host", "port", "service"])

    // 模拟扫描
    results = [["10.0.0.1", "80", "http"], ["10.0.0.1", "443", "https"], ["10.0.0.2", "22", "ssh"]]
    for i = 0; i < len(results); i++ {
        r = results[i]
        // 写动态表格
        yakit.TableData("Port Scan Result", {"host": r[0], "port": r[1], "service": r[2]})
        // 更新进度与卡片
        yakit.SetProgress(float(i + 1) / float(len(results)))
        yakit.StatusCard("Targets", sprintf("%d/%d", i + 1, len(results)), "progress")
        yakit.Info("scanned %s:%s -> %s", r[0], r[1], r[2])
        sleep(0.05)
    }
    yakit.SetProgress(1.0)
    yakit.StatusCard("Targets", "10/10", "done")

    // 4. 静态表格（汇总）
    table = yakit.NewTable("Host", "Port", "Service")
    for r in results { table.Append(r[0], r[1], r[2]) }
    yakit.Output(table)

    // 5. 柱状图
    graph = yakit.NewBarGraph("port distribution")
    graph.Add("80", 1)
    graph.Add("443", 1)
    graph.Add("22", 1)
    yakit.Output(graph)

    // 6. Markdown 报告
    yakit.Markdown(sprintf("# Scan Report\n\n- hosts: 2\n- open ports: %d\n", len(results)))
    yakit.Success("scan completed")
}

func runSelfTest() {
    // 命令行自测: 调用纯函数验证逻辑，不依赖 UI
    // yakit.* 在命令行环境走 VirtualYakitClient, 输出到 stdout
    runPlugin()
    assert true, "should complete without error"
}

if YAK_MAIN {
    runSelfTest()
}

5. 命令行环境下的 yakit.* 行为（重要）

当脚本不在 Yakit 引擎中运行（即 yak xxx.yak 命令行运行）时：

• AutoInitYakit() 检测到没有 --yakit-webhook 参数 → 使用 emptyVirtualClient（NewVirtualYakitClient）。
• emptyVirtualClient 的 send 回调把 ExecResult 打印到 log.Info（即 stdout）。
• 因此 yakit.Info("hello") 在命令行下等同于 log.Info("hello")，yakit.Output(table) 会打印 table 的 JSON。

这意味着：含 yakit.* 调用的脚本在命令行下不会崩溃，所有输出退化为日志打印。所以 "先在命令行自测逻辑，再粘回 Yakit 使用"的安全调试闭环依然成立。

源码：yaklang/common/yak/yaklib/yakit.go 中 emptyVirtualClient 和 AutoInitYakit。

6. 引擎如何注入 yakit 全局变量

引擎启动脚本前，通过 SetEngineClient 把一个 YakitClient 实例注入为脚本的 yakit 全局变量：

// yaklang/common/yak/yaklib/yakit_client.go
func SetEngineClient(e *antlr4yak.Engine, client *YakitClient) {
    e.OverrideRuntimeGlobalVariables(map[string]any{
        "yakit": GetExtYakitLibByClient(client),
        "risk":  map[string]any{ /* risk 库, 内部用 client 做 risk 输出 */ },
    })
    InitYakit(client)  // 设置全局默认客户端
}

GetExtYakitLibByClient(client) 返回一个 map[string]interface{}，其中每个 key 就是脚本能调用的 yakit.xxx 函数名，value 是绑定到该 client 的函数。因此同一个脚本在不同 client 下运行：

• gRPC client → 输出到前端 UI
• VirtualYakitClient → 输出到 stdout
• 空 client → 输出被丢弃

7. 前端 useHoldGRPCStream 消费逻辑详解

前端 useHoldGRPCStream 是所有插件/扫描结果展示的核心 hook，它：

1. 通过 yakitStream.onData(token, callback) 监听 gRPC 流。
2. 每收到一个 ExecResult，解析 YakitMessage JSON。
3. 按 type + level 路由到不同缓冲区：

4. 定时（默认 500ms）把缓冲区快照到 React state，触发 UI 重渲染。

理解这条链路后，你就知道"写 yakit.EnableTable 时前端在做什么"——它在等 json-feature 消息来 建表格 Tab，再等 feature-table-data 消息逐行填充。

8. 坑与注意事项

9. 示例 (examples/)

10. 验证

cd /Users/v1ll4n/Projects/yaklang
go run common/yak/cmd/yak.go skills/yakit-ui-binding/examples/ui-output-tour.yak

命令行运行时，yakit.* 走 VirtualYakitClient，所有输出退化为 stdout 日志。 在 Yakit 中运行同一脚本，各 UI 组件实时展示。

合格标准：10 秒内完成、无 panic、log 全英文、末尾出现 ... self test passed。

参考来源

• 引擎侧 yakit 库导出：yaklang/common/yak/yaklib/yakit.go（YakitExports / GetExtYakitLibByClient）
• Client 实现：yaklang/common/yak/yaklib/yakit_client.go（YakitClient.Output / YakitLog / send）
• Viewer 扩展（EnableTable/StatusCard 等）：yaklang/common/yak/yaklib/yakit_viewer.go
• 消息序列化：yaklang/common/yak/yaklib/yakit.go（MarshalYakitOutput / YakitMessageGenerator）
• 脚本执行：yaklang/common/yak/yakscript/exec.go（ExecScriptWithParam / ExecScriptWithExecParam）
• 前端 gRPC 流消费：yakit/app/renderer/src/main/src/hook/useHoldGRPCStream/useHoldGRPCStream.ts
• 前端类型定义：yakit/app/renderer/src/main/src/hook/useHoldGRPCStream/useHoldGRPCStreamType.d.ts
• 前端结果展示：yakit/app/renderer/src/main/src/pages/plugins/operator/pluginExecuteResult/PluginExecuteResult.tsx