gameknife · gameknife · May 17, 2026 · May 12, 2026 · May 13, 2026 · May 13, 2026
diff --git a/.github/workflows/linux_self.yml b/.github/workflows/linux_self.yml
@@ -20,5 +20,12 @@ jobs:
       - uses: actions/checkout@v4
         with:
           clean: false
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: tools/gnb/go.mod
+      - name: Build latest gnb
+        run: |
+          cd tools/gnb
+          go build -trimpath -ldflags="-s -w -X main.version=$(git -C "$GITHUB_WORKSPACE" rev-parse HEAD)" -o "$GITHUB_WORKSPACE/gnb" ./cmd/gnb
       - run: ./gnb.sh setup
       - run: ./gnb.sh build
diff --git a/.github/workflows/macos_self.yml b/.github/workflows/macos_self.yml
@@ -20,5 +20,12 @@ jobs:
       - uses: actions/checkout@v4
         with:
           clean: false
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: tools/gnb/go.mod
+      - name: Build latest gnb
+        run: |
+          cd tools/gnb
+          go build -trimpath -ldflags="-s -w -X main.version=$(git -C "$GITHUB_WORKSPACE" rev-parse HEAD)" -o "$GITHUB_WORKSPACE/gnb" ./cmd/gnb
       - run: ./gnb.sh setup
       - run: ./gnb.sh build
diff --git a/.spec/ARCHIVE.md b/.spec/ARCHIVE.md
@@ -0,0 +1,18 @@
+# Archive
+
+## Pre-workflow（2026-05-14 之前）
+
+从旧版根目录 `TODO.md` 迁移。无 ID、无 journal，仅保留原始描述。
+
+- [x] 提交当前修改
+- [x] 确认 AmbientCube 的改造，目前 Voxel 的更新和 GPU 读取是正确的，但 AmbientCube 感觉没有工作。但 hwlightbake 在执行
+- [x] 提交目前的修改
+- [x] 清理上下文
+- [x] 恢复 wireframe 的工作，这里 wireframePipeline_，可考虑直接写在 imgui 绘制前，直接绘制在最终输出之上。不要像之前一样尝试写在 RT_DENOISED 上
+- [x] Options 下的 bool HotReload{true} 已经废弃，移除整个选项以及相关无用的逻辑
+- [x] wireframe 的修改有些问题，只有当 scale 为 native 的时候，绘制正常。当使用 quality 等缩放模式的时候，线框会位于画面的左上角。修复这个问题
+- [x] 提交目前的修改
+- [x] 把本地 feature/productive-ui-refactor 分支关于 ui 的重构以及前面的 Brotato3D Tweaks 的提交合并到本分支，并运行验证通过
+- [x] 彻底解决 LDraw 的那个单元测试错误，如果是因为 Optional 资源问题，实在不行，干掉它
+- [x] 目前 .\gnb.bat run xxxx 无法带上 target 本身支持的 cmdline，很不方便，请改造。比如 .\gnb.bat run gkNextRenderer --help，可以把 gkNextRenderer 本身的 help 打印出来。当然不一定是我说的这样，能够有办法带参数即可
+- [x] Brotato3D 目前应该在游戏过程中一直在重建 BVH 和刷新 voxel 数据。我希望是尽量减少刷新，除了一开始的场景，后续主角，敌人的移动，动态碎块，prop 都不应该影响 BVH 和 voxel。这样 cpu 线程压力会小很多。请作这个调整。
diff --git a/.spec/README.md b/.spec/README.md
@@ -0,0 +1,108 @@
+# .spec — 交互式工作流规范
+
+gkNextRenderer 项目的 spec 驱动开发工作流目录。AGENT 在当前 session 内根据这些文件调度任务，**不调用其他 agent，不 sleep**。
+
+## 文件结构
+
+| 路径 | 用途 | 谁写 |
+| --- | --- | --- |
+| `TODO.md` | 活跃任务列表 | 用户（任务内容）+ AGENT（状态字符、journal 链接） |
+| `ARCHIVE.md` | 归档的完成任务 | `gnb todo archive` 或用户 |
+| `specs/<id>.md` | 复杂任务的详细规格，**仅 spec 类任务需要** | 用户 |
+| `journal/<id>.md` | 任务完成报告，一任务一文件 | AGENT |
+| `blockers/<id>.md` | AGENT 卡住时的提问，一任务一文件 | AGENT |
+
+## TODO.md 格式
+
+```markdown
+# TODO
+
+## Milestone: <名字>  <!-- status: active|done -->
+
+### 下一步
+- [ ] `#00018` [P0][BUG] 修复贴图采样越界
+- [/] `#00019` [P1][FEAT] 体积雾 → specs/00019.md
+- [!] `#00020` [SPIKE] work graphs (blockers/00020.md)
+
+### 待规划
+- [ ] `#00021` [IDEA] 试试 NRD 降噪
+
+### 最近完成
+- [x] `#00017` [BUG] 修复贴图过滤 → journal/00017.md (2026-05-13)
+```
+
+### 三个段落
+
+- **下一步**：AGENT 只扫这一段，按从上到下顺序执行
+- **待规划**：想法池/积压。AGENT **完全不动**，从待规划挪到下一步由用户操作
+- **最近完成**：累积完成的任务，定期由 `gnb todo archive` 移到 ARCHIVE.md
+
+### 状态字符
+
+| 字符 | 含义 |
+| --- | --- |
+| `[ ]` | pending |
+| `[/]` | doing（执行中，正常不持久化此状态，crash 恢复用） |
+| `[x]` | done |
+| `[!]` | blocked（对应 `blockers/<id>.md` 有说明） |
+
+### ID
+
+五位全局递增数字 `#00001` ~ `#99999`。新 ID 取当前所有任务（含 ARCHIVE）中最大 ID + 1。
+
+### 内联标签
+
+- 优先级：`[P0]` `[P1]` `[P2]`
+- 类型：`[BUG]` `[FEAT]` `[IDEA]` `[SPIKE]` `[REFACTOR]` `[DOC]`
+
+## journal/`<id>`.md 格式
+
+```markdown
+---
+task: 00018
+completed: 2026-05-14T15:30:00
+build_ok: true
+---
+
+## 做了什么
+…
+
+## 改动文件
+- `src/Rendering/VolumeFog.cpp`
+
+## 风险/遗留
+- ⚠️ 与 SSR 有交互问题，未处理
+```
+
+## blockers/`<id>`.md 格式
+
+```markdown
+---
+task: 00018
+blocked_at: 2026-05-14T15:30:00
+---
+
+## 歧义点
+任务描述里说"修复采样越界"，但越界发生在两处：
+1. `SampleEnvironment.hlsl:42` — 已知问题
+2. `VolumeFog.cpp:128` — 看上去也有类似模式
+
+## 候选方案
+- A. 只修 1
+- B. 修 1 + 2
+
+等用户答复后继续。
+```
+
+## AGENT 行为边界
+
+**可改**：
+- TODO.md 中任务的状态字符（`[ ]` → `[x]` / `[!]`）
+- TODO.md 中任务行末追加 journal 链接
+- `journal/`、`blockers/` 下的文件
+
+**不可改**：
+- TODO.md 中任务标题、ID、优先级、类型、所属段落
+- `specs/` 下的文件（用户写的需求）
+- `ARCHIVE.md`（归档由工具或用户操作）
+- "待规划"段任何任务
diff --git a/.spec/TODO.md b/.spec/TODO.md
@@ -0,0 +1,18 @@
+# TODO
+
+## Milestone: 工作流落地  <!-- status: active -->
+
+里程碑目标：完成 spec 工作流的三步落地（规范 + gnb todo + dashboard）。
+
+### 下一步
+
+- [x] `#00001` [IDEA] 介绍gnb技术栈  → journal/00001.md (2026-05-14)
+- [x] `#00002` [IDEA] 介绍typescript整合  → journal/00002.md (2026-05-14)
+- [ ] `#00003` 介绍brotato3D
+- [ ] `#00004` [IDEA] 介绍flappybird
+
+### 待规划
+
+### 最近完成
+
+(暂无)
diff --git a/.spec/journal/00001.md b/.spec/journal/00001.md
@@ -0,0 +1,23 @@
+---
+task: 00001
+completed: 2026-05-14T16:53:33.4733882+08:00
+build_ok: false
+---
+
+## 做了什么
+
+补了一份 `gnb` 技术栈说明文档，介绍它的启动层、CLI 层、配置层、执行模块层、外部依赖和维护边界。
+
+同时在现有 `docs/gnb-cli.md` 和 `tools/gnb/README.md` 中加入跳转，避免 `gnb` 只有命令手册，没有实现视角的入口说明。
+
+## 改动文件
+
+- `docs/gnb-tech-stack.md`
+- `docs/gnb-cli.md`
+- `tools/gnb/README.md`
+- `.spec/TODO.md`
+
+## 风险/遗留
+
+- 未运行构建或自动化测试；本次仅修改 Markdown 文档和 spec 元数据。
+- `TODO.md` 中当前存在重复的 `#00001` 编号（“下一步”和“待规划”各一条），本次按 spec 边界未改任务标题或 ID。
diff --git a/.spec/journal/00002.md b/.spec/journal/00002.md
@@ -0,0 +1,23 @@
+---
+task: 00002
+completed: 2026-05-14T17:02:32.2719456+08:00
+build_ok: false
+---
+
+## 做了什么
+
+新增 TypeScript 整合说明文档，介绍 `assets/typescript` 到 `assets/scripts` 的编译路径、bundled `tsc` 工具链、QuickJS 模块加载、生命周期封装、绑定与 `Engine.d.ts` 生成、热重载行为和验证方式。
+
+同时在 README 的 QuickJS 能力介绍和 `AGENT_GUIDE/QuickJSBindings.md` 中加入入口链接，方便从项目概览或绑定 cookbook 跳到这份说明。
+
+## 改动文件
+
+- `docs/typescript-integration.md`
+- `README.md`
+- `AGENT_GUIDE/QuickJSBindings.md`
+- `.spec/TODO.md`
+
+## 风险/遗留
+
+- 未运行构建或自动化测试；本次仅修改 Markdown 文档和 spec 元数据。
+- 工作区中存在与本任务无关的既有变更，本次未处理。
diff --git a/AGENTS.md b/AGENTS.md
@@ -210,3 +210,42 @@ assets/
   - `MagicaLego.md` - MagicaLego subproject notes
 - **README.en.md** - Project overview and quick start
 - **.clang-tidy** - Naming conventions (source of truth)
+
+## Spec Workflow
+
+**完整规范见 [.spec/README.md](.spec/README.md)**。下面是 AGENT 必须遵守的核心规则，规范与本节不一致以 README 为准。
+
+文件位置：
+- 任务列表：`.spec/TODO.md`
+- 任务详细规格（可选，仅复杂任务）：`.spec/specs/<id>.md`
+- 完成报告（一任务一文件）：`.spec/journal/<id>.md`
+- 卡住提问（一任务一文件）：`.spec/blockers/<id>.md`
+- 归档：`.spec/ARCHIVE.md`
+
+执行规则：
+
+1. 用户触发"启动交互式工作流"时，读取 `.spec/TODO.md`
+2. 在"下一步"段找第一个 `[ ]` 任务
+3. 若 `.spec/specs/<id>.md` 存在，先读它再执行
+4. 执行任务
+5. 完成后：
+   - 在 TODO.md 把该任务的 `[ ]` 改为 `[x]`
+   - 行末追加 ` → journal/<id>.md (YYYY-MM-DD)`
+   - 写 `.spec/journal/<id>.md`（frontmatter + 做了什么 + 改动文件 + 风险/遗留）
+6. 回到 2，继续下一个 `[ ]` 任务
+7. "下一步"段没有 `[ ]` 任务时：
+   - 比较 TODO.md mtime 与 `.spec/journal/` 目录中最新文件的 mtime
+   - TODO 较新 → 用户可能加了任务，回到 2 重扫
+   - 否则 → 执行sleep command等待600秒，回到步骤2。等待期间不要思考，这时TODO.md可能更新
+8. 里程碑状态改为 `done` → 退出工作流
+
+特殊情况：
+- 任务歧义无法判断时：写 `.spec/blockers/<id>.md`，任务状态改 `[!]`，**跳过该任务继续做下一个**，不要瞎猜
+- 启动工作流时若"最近完成"段超过 10 条：在首次回复中提醒用户运行 `gnb todo archive`，但不要自己归档
+- 用户在工作流期间修改 TODO.md：下一轮重扫时会发现
+
+边界：
+- AGENT **可改**：TODO.md 中任务的状态字符、行末 journal 链接；`journal/`、`blockers/` 下的文件
+- AGENT **不可改**：TODO.md 中任务标题/ID/优先级/类型/所属段落；`specs/` 下的文件；`ARCHIVE.md`；"待规划"段任何任务
+- 不要建立自动化任务（hooks、scheduled tasks 等）
+- 不要调用其他 agent 处理任务
diff --git a/AGENT_GUIDE/QuickJSBindings.md b/AGENT_GUIDE/QuickJSBindings.md
@@ -2,6 +2,8 @@
 
 This note documents the binding path used by the Flappy parity demo. Keep it aligned with `src/Runtime/Subsystems/QuickJSEngine.cpp`.
 
+For a higher-level overview of the TypeScript source, compile, hot reload, and runtime loading pipeline, see `docs/typescript-integration.md`.
+
 ## TypeScript Entry And Modules
 
 - TypeScript sources live under `assets/typescript`.

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -17,13 +17,15 @@ set(WITH_PHYSIC ON CACHE BOOL "Enable Physics" FORCE)
 set(WITH_AUDIO ON CACHE BOOL "Enable Audio" FORCE)
 set(WITH_QUICKJS ON CACHE BOOL "Enable QuickJS" FORCE)
 
-if (WIN32)
-    set(WITH_STREAMLINE ON CACHE BOOL "Enable Nvidia Streamline" FORCE)
+option(ENABLE_STREAMLINE "Enable NVIDIA Streamline/DLSS integration" OFF)
+if (WIN32 AND ENABLE_STREAMLINE)
+    set(WITH_STREAMLINE ON CACHE BOOL "Enable NVIDIA Streamline/DLSS integration" FORCE)
 else()
-    set(WITH_STREAMLINE OFF CACHE BOOL "Enable Nvidia Streamline" FORCE)
+    set(WITH_STREAMLINE OFF CACHE BOOL "Enable NVIDIA Streamline/DLSS integration" FORCE)
 endif()
 
 option(GK_ENABLE_HOT_RELOAD "Enable desktop Slang shader hot reload" ON)
+option(GK_ENABLE_SHADER_CLOCK "Enable shader clock heatmap instrumentation" OFF)
 if (ANDROID OR IOS)
     if (GK_ENABLE_HOT_RELOAD)
         message(STATUS "Hot reload is only enabled for desktop targets. Disabling.")

diff --git a/README.en.md b/README.en.md
@@ -146,7 +146,7 @@ The project uses CMake + Ninja, with dependencies managed through vcpkg. Beyond
 
 - CMake 3.26+
 - Visual Studio 2022 with C++ workload
-- Vulkan SDK 1.4.313.2
+- Vulkan SDK 1.4.341.1 (downloaded into the repository by default; if `VULKAN_SDK` is set, that SDK is used first)
 - Enable "Use Unicode UTF-8 for worldwide language support"
 
 ```bat
@@ -155,7 +155,7 @@ gnb.bat build
 gnb.bat run gkNextRenderer
 ```
 
-Aside from host-side requirements such as Visual Studio and the Vulkan SDK, the rest of the project dependencies are usually prepared by `gnb`.
+Aside from host-side requirements such as Visual Studio, the rest of the project dependencies are usually prepared by `gnb`, including the pinned Vulkan SDK, Slang, and TypeScript toolchains.
 
 </details>
 
@@ -185,7 +185,8 @@ Aside from host-side requirements such as Visual Studio and the Vulkan SDK, the
 
 Notes:
 
-- if `slangc` is not installed yet, `gnb setup` will automatically fetch the project-managed Slang toolchain into `external/`
+- if no usable `VULKAN_SDK` is available, `gnb setup` automatically downloads the pinned LunarG Vulkan SDK into `external/VulkanSDK/`
+- if `slangc` is not installed yet, `gnb setup` automatically fetches the project-managed Slang toolchain into `external/`
 - on pacman hosts, `gnb setup` and the first Linux `gnb build` automatically install the required system packages before vcpkg bootstrap; if that is unavailable, run `sudo pacman -S --needed base-devel cmake ninja curl zip unzip tar pkgconf libxrandr wayland-protocols libxkbcommon systemd-libs` manually
 - if a GitHub archive download fails during vcpkg setup, rerun the same build command once before doing deeper troubleshooting
 - deployment notes from a real Steam Deck setup are available in [docs/steamdeck-deployment-notes.md](docs/steamdeck-deployment-notes.md)
@@ -207,7 +208,7 @@ Notes:
 ./gnb.sh run gkNextRenderer
 ```
 
-`gnb setup` automatically downloads the Slang and TypeScript toolchains used by the project, so those project-level dependencies no longer need to be installed separately.
+`gnb setup` automatically downloads the Vulkan SDK, Slang, and TypeScript toolchains used by the project, so those project-level dependencies no longer need to be installed separately. If `VULKAN_SDK` is explicitly set, that SDK takes precedence.
 
 </details>
 

diff --git a/README.md b/README.md
@@ -62,7 +62,7 @@ gkNextEngine 是一个基于现代 C++20 与 Vulkan 的跨平台 3D 游戏引擎
 
 - **ECS + Reflection**：基于 entt 的组件系统，加上反射层，服务于运行时、编辑器和脚本绑定
 - **ImGui 编辑器**：`gkNextEditor` 面向材质、场景和运行时内容的编辑工作流
-- **QuickJS 脚本热重载**：运行时使用仓库内置 `tools/tsc/tsc[.exe]` 编译 TypeScript（Windows 为 `tsc.exe`，macOS/Linux 为 `tsc`），无需 Node/npm 或全局 `tsc`
+- **QuickJS 脚本热重载**：运行时使用仓库内置 `tools/tsc/tsc[.exe]` 编译 TypeScript（Windows 为 `tsc.exe`，macOS/Linux 为 `tsc`），无需 Node/npm 或全局 `tsc`；整合链路见 [docs/typescript-integration.md](docs/typescript-integration.md)
 - **Jolt Physics**：为交互原型、拖拽玩法和游戏化验证提供更真实的物理基础
 
 ### 3. 代码规模可控，适合学习和扩展
@@ -146,7 +146,7 @@ gkNextEngine 是一个基于现代 C++20 与 Vulkan 的跨平台 3D 游戏引擎
 
 - CMake 3.26+
 - Visual Studio 2022（C++ 工作负载）
-- Vulkan SDK 1.4.313.2
+- Vulkan SDK 1.4.341.1（默认由 `gnb` 自动下载到仓库内；若设置 `VULKAN_SDK` 则优先使用环境里的 SDK）
 - 启用“使用 Unicode UTF-8 提供全球语言支持”
 
 ```bat
@@ -155,7 +155,7 @@ gnb.bat build
 gnb.bat run gkNextRenderer
 ```
 
-除 Visual Studio / Vulkan SDK 这类宿主工具外，其余项目依赖通常都由 `gnb` 自动准备。
+除 Visual Studio 这类宿主工具外，其余项目依赖通常都由 `gnb` 自动准备；默认会拉取项目约定版本的 Vulkan SDK、Slang 与 TypeScript 工具链到仓库内。
 
 </details>
 
@@ -185,6 +185,7 @@ gnb.bat run gkNextRenderer
 
 说明：
 
+- 如果机器上没有可用的 `VULKAN_SDK`，`gnb setup` 会自动下载项目约定版本的 LunarG Vulkan SDK 到 `external/VulkanSDK/`
 - 如果机器上还没有 `slangc`，`gnb setup` 会自动下载项目约定的 Slang 工具链到 `external/`
 - 在 pacman 环境下，`gnb setup` / Linux 首轮 `gnb build` 会在 vcpkg bootstrap 前自动安装系统包；如果自动安装不可用，可手动执行 `sudo pacman -S --needed base-devel cmake ninja curl zip unzip tar pkgconf libxrandr wayland-protocols libxkbcommon systemd-libs`
 - 如果 vcpkg 阶段遇到 GitHub 归档下载失败，优先直接重试同一条构建命令
@@ -207,7 +208,7 @@ gnb.bat run gkNextRenderer
 ./gnb.sh run gkNextRenderer
 ```
 
-`gnb setup` 会自动下载项目使用的 Slang 与 TypeScript 工具链，无需再单独准备这些项目级依赖。
+`gnb setup` 会自动下载项目使用的 Vulkan SDK、Slang 与 TypeScript 工具链，无需再单独准备这些项目级依赖。若显式设置 `VULKAN_SDK`，则优先使用该环境变量指向的 SDK。
 
 </details>
 

diff --git a/assets/CMakeLists.txt b/assets/CMakeLists.txt
@@ -117,7 +117,7 @@ foreach(shader ${shader_files})
     set_source_files_properties(${shader} PROPERTIES VS_TOOL_OVERRIDE "None")
 
     set(slangc_args "")
-    if(WIN32)
+    if(WIN32 AND GK_ENABLE_SHADER_CLOCK)
         set(slangc_args "-DSHADER_CLOCK")
     endif()
     if(APPLE)

diff --git a/assets/shaders/Bake.DistanceFieldJump.comp.slang b/assets/shaders/Bake.DistanceFieldJump.comp.slang
@@ -28,7 +28,7 @@ void main(uint3 DTid : SV_DispatchThreadID)
     uint passParity = Bindless.GetGpuscene().custom_data_1;
 
     uint4* SeedA = (uint4*)Bindless.GetGpuscene().CubesPong;
-    uint4* SeedB = (uint4*)Bindless.GetGpuscene().SkinnedVerticesSimple;
+    uint4* SeedB = Bindless.GetGpuscene().AmbientSdfScratch;
     uint4* SourceSeeds = (passParity & 1u) == 0u ? SeedA : SeedB;
     uint4* DestSeeds = (passParity & 1u) == 0u ? SeedB : SeedA;