refactor: update cmd/help/kvspace, keytree/vthread, layoutcode

Author: miaobyte

cmd/kvlang/help.go

@@ -30,6 +30,7 @@ func showHelp() {
 	fmt.Fprintln(os.Stderr, "  watch <key> [--timeout 5s]     阻塞等待通知")
 	fmt.Fprintln(os.Stderr, "  notify <key> <value>           推送通知")
 	fmt.Fprintln(os.Stderr, "  clear                          清空所有 kvspace 数据")
+	fmt.Fprintln(os.Stderr, "  trace <vtid>                   追踪 vthread 单步执行，输出 NDJSON")
 	fmt.Fprintln(os.Stderr)
 	fmt.Fprintln(os.Stderr, "全局选项:")
 	fmt.Fprintln(os.Stderr, "  --addr host:port               Redis 地址（默认 127.0.0.1:6379）")

cmd/kvlang/kvspace.go

@@ -1,10 +1,12 @@
 package main
 
 import (
+	"encoding/json"
 	"flag"
 	"fmt"
 	"os"
 	"strings"
+	"time"
 
 	"kvlang/internal/keytree"
 	"kvlang/internal/kvspace"
@@ -16,7 +18,7 @@ func cmdKVSpace(args []string) {
 	addr := fs.String("addr", "127.0.0.1:6379", "Redis 地址 (host:port)")
 	fs.Usage = func() {
 		fmt.Fprintln(os.Stderr, "usage: kvlang kvspace [--addr host:port] <subcommand> [args]")
-		fmt.Fprintln(os.Stderr, "subcommands: get mget set del list tree dump watch notify clear")
+		fmt.Fprintln(os.Stderr, "subcommands: get mget set del list tree dump watch notify clear trace")
 		fs.PrintDefaults()
 	}
 	fs.Parse(args)
@@ -80,6 +82,16 @@ func cmdKVSpace(args []string) {
 	case "clear":
 		clearAll(kv)
 
+	case "trace":
+		// trace 监听 /vthread/<vtid>/.debug.pause 上的暂停事件，
+		// 将每个事件输出为一行 NDJSON，并自动发送 "step" 使程序继续执行。
+		// 用于捕获已开启调试模式（.debug = "step"）的 vthread 的执行轨迹。
+		//
+		// 用法：kvlang kvspace trace <vtid>
+		// 配合：先用 kvlang kvspace set /vthread/<vtid>/.debug "step" 开启调试
+		if len(sub) < 2 { usageExit("kvlang kvspace trace <vtid>") }
+		kvTrace(kv, sub[1])
+
 	default:
 		fmt.Fprintf(os.Stderr, "unknown kvspace subcommand: %s\n", sub[0])
 		os.Exit(1)
@@ -149,3 +161,52 @@ func dumpPrefix(kv kvspace.KVSpace, prefix string) {
 	children, _ := kv.List(prefix)
 	for _, c := range children { dumpPrefix(kv, prefix+"/"+c) }
 }
+
+// kvTrace 监听 /vthread/<vtid>/.debug.pause 上的暂停事件。
+//
+// 每收到一条暂停事件（JSON），将其原样输出为一行 NDJSON（stdout），
+// 然后自动向 /vthread/<vtid>/.debug.resume 发送 "step"，驱动 CPU 执行下一条指令。
+//
+// 终止条件：
+//   - 连续超时（30 s 无事件）：认为程序已结束
+//   - os.Interrupt（Ctrl-C）
+//
+// 用于配合 kvlang kvspace set /vthread/<vtid>/.debug "step" 捕获程序执行轨迹，
+// 输出结果可直接送入 jq / 其他 NDJSON 工具分析。
+func kvTrace(kv kvspace.KVSpace, vtid string) {
+	pauseKey  := keytree.VThreadDebugPause(vtid)
+	resumeKey := keytree.VThreadDebugResume(vtid)
+	statusKey := keytree.VThreadStatus(vtid)
+
+	const watchTimeout = 10 * time.Second
+	const maxIdle      = 3 // 连续超时次数上限
+
+	idle := 0
+	for {
+		val, err := kv.Watch(pauseKey, watchTimeout)
+		if err != nil {
+			// 超时：检查 vthread 是否已终止
+			idle++
+			statusVal, serr := kv.Get(statusKey)
+			if serr != nil || statusVal.IsNil() || idle >= maxIdle {
+				// vthread 已终止或长期无活动 → 正常结束 trace
+				return
+			}
+			continue
+		}
+		idle = 0
+
+		// 将暂停事件输出为一行 NDJSON
+		// val 本身是 CPU 投递的 JSON 字符串，直接输出即可
+		raw := val.Str()
+		if raw == "" {
+			// 空通知（不常见），构造最小 JSON
+			out, _ := json.Marshal(map[string]any{"vtid": vtid, "note": "empty-pause"})
+			raw = string(out)
+		}
+		fmt.Println(raw)
+
+		// 自动发送 "step"，驱动 CPU 继续执行下一条指令
+		kv.Notify(resumeKey, kvspace.Str("step")) //nolint:errcheck
+	}
+}

internal/keytree/vthread.go

@@ -52,6 +52,27 @@ func VThreadStatusMsg(vtid, statusVal string) string {
 // VThreadAt 返回 /vthread/<vtid>/<key>，通用路径构造（仅供引擎内部调试使用）
 func VThreadAt(vtid, key string) string { return "/vthread/" + vtid + "/" + key }
 
+// ── 调试标志（引擎保留，. 前缀）────────────────────────────────────────────
+//
+// 所有 kvcpu 实例在 execute 循环中自动检查这三个键，无需特殊启动方式。
+// Agent 通过已有 kvspace 命令读写这些键来控制调试行为。
+//
+//	.debug         调试控制键（agent 写，CPU 读）
+//	               ""/"" = 正常执行；"step" = 每条指令后暂停；"break:<func>" = 函数入口暂停
+//	.debug.pause   暂停事件键（CPU 写 Notify，agent 用 Watch 等待）
+//	               值：JSON {"pc":"...","func":"...","frame":"...","op":"..."}
+//	.debug.resume  恢复命令键（agent 写 Notify，CPU 用 Watch 等待）
+//	               值："step"（执行一步继续暂停）| "continue"（恢复全速）| "abort"（终止）
+
+// VThreadDebug 返回 /vthread/<vtid>/.debug（调试控制键）
+func VThreadDebug(vtid string) string { return "/vthread/" + vtid + "/.debug" }
+
+// VThreadDebugPause 返回 /vthread/<vtid>/.debug.pause（CPU → agent 暂停事件）
+func VThreadDebugPause(vtid string) string { return "/vthread/" + vtid + "/.debug.pause" }
+
+// VThreadDebugResume 返回 /vthread/<vtid>/.debug.resume（agent → CPU 恢复命令）
+func VThreadDebugResume(vtid string) string { return "/vthread/" + vtid + "/.debug.resume" }
+
 // VtidFromPC 从绝对 PC 提取 vtid。
 //
 //	"/vthread/42/[0,0]" → "42"

internal/layoutcode/layoutcode.go

@@ -223,12 +223,15 @@ func Bootstrap(ctx context.Context, kv kvspace.KVSpace, vtid, funcName string, a
 	kv.Set(vthreadRoot+"/.rootfunc", kvspace.Str(funcName))
 
 	// 绑定入参（若有）
+	// 使用 ResolveReadValue 而非 kvspace.Str，确保字面量（如 "3"、"true"）
+	// 以正确的类型（int/bool）写入帧，与 HandleCall 的参数绑定语义保持一致。
+	// 否则数字参数会被存储为 string，导致 le/lt 等比较操作进入 strCmp 分支。
 	if len(args) > 0 {
 		sigVal, _ := kv.Get(funcKey)
 		sig := parser.ParseFuncSig(sigVal.Str())
 		for i, param := range sig.ParamNames() {
 			if i < len(args) {
-				kv.Set(vthreadRoot+"/"+param, kvspace.Str(args[i]))
+				kv.Set(vthreadRoot+"/"+param, builtin.ResolveReadValue(kv, "", args[i]))
 			}
 		}
 	}