[docs]: add contribuing guide and add hooks install (#1613)

* [feat]: update kt-kernel hooks and add contribution guide

* [docs]: add contributing guide
* [style]: format the python file and cpp file in kt-kernel

Author: KMSorSMS

.github/CONTRIBUTING.md

@@ -0,0 +1,139 @@
+## Before Commit!
+
+Your commit message must follow Conventional Commits (https://www.conventionalcommits.org/) and your code should be formatted. The Git hooks will do most of the work automatically:
+
+### Tool Requirements
+
+You need a recent `clang-format` (>= 18). In a conda environment you can install:
+
+```shell
+conda install -c conda-forge clang-format=18
+```
+
+If you previously configured with an older version, remove the build directory and reconfigure:
+
+```shell
+rm -rf kt-kernel/build
+```
+
+Install `black` for Python formatting:
+
+```shell
+conda install black
+```
+
+### Install hook:
+```shell
+bash kt-kernel/scripts/install-git-hooks.sh
+#or just cmake the kt-kernel
+cmake -S kt-kernel -B kt-kernel/build
+```
+
+There are manual commands if you need format.
+
+```shell
+cmake -S kt-kernel -B kt-kernel/build
+cmake --build kt-kernel/build --target format
+```
+
+## Developer Note
+
+Formatting and commit message rules are enforced by Git hooks. After installing `clang-format` and `black`, just commit normally—the hooks will run formatting for you.
+
+> [!NOTE]
+> If formatting modifies files, the commit is aborted after staging those changes. Review them and run `git commit` again. Repeat until no further formatting changes appear.
+
+---
+
+### Conventional Commit Regex (Reference)
+
+The commit-msg hook enforces this pattern:
+
+```text
+regex='^\[(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip)\](\([^\)]+\))?(!)?: .+'
+```
+
+Meaning (English):
+* `[type]` required — one of feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip
+* Optional scope: `(scope)` — any chars except `)`
+* Optional breaking change marker: `!` right after type or scope
+* Separator: `: ` (colon + space)
+* Subject: free text (at least one character)
+
+Examples:
+```text
+[feat]: add adaptive batching
+[fix(parser)]: handle empty token list
+[docs]!: update API section for breaking rename
+```
+
+You can bypass locally (not recommended) with:
+```shell
+git commit --no-verify
+```
+## 提交前提醒
+
+提交信息必须满足 Conventional Commits 规范 (https://www.conventionalcommits.org/)，代码需要符合格式要求。Git 钩子已经集成了大部分工作：
+### 软件要求
+
+需要较新的 `clang-format` (>= 18)，在 conda 环境中安装：
+
+```shell
+conda install -c conda-forge clang-format=18
+```
+
+如果之前用老版本配置过，请删除构建目录重新配置：
+
+```shell
+rm -rf kt-kernel/build
+```
+
+安装 `black` 以进行 Python 文件格式化：
+
+```shell
+conda install black
+```
+### 安装钩子
+```shell
+bash kt-kernel/scripts/install-git-hooks.sh
+#or just cmake the kt-kernel
+cmake -S kt-kernel -B kt-kernel/build
+```
+如果你需要手动格式化：
+```shell
+cmake -S kt-kernel -B kt-kernel/build
+cmake --build kt-kernel/build --target format
+```
+
+## 开发者说明
+
+本仓库通过 Git hooks 自动执行代码格式化与提交信息规范检查。只需安装好 `clang-format` 与 `black` 后正常执行提交即可，钩子会自动格式化。
+
+> [!NOTE]
+> 如果格式化修改了文件，钩子会终止提交并已暂存这些改动。请查看修改后再次执行 `git commit`，重复直到没有新的格式化变更。
+
+### 提交信息正则（参考）
+
+钩子使用如下正则检查提交信息：
+```text
+regex='^\[(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip)\](\([^\)]+\))?(!)?: .+'
+```
+含义：
+* `[type]` 必填：feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert|wip
+* 作用域可选：`(scope)`，不能包含右括号
+* 可选的破坏性标记：`!`
+* 分隔符：冒号+空格 `: `
+* 描述：至少一个字符
+
+示例：
+```text
+[feat]: 增加自适应 batch 功能
+[fix(tokenizer)]: 修复空 token 列表处理
+[docs]!: 更新接口文档（存在破坏性修改）
+```
+
+跳过钩子（不推荐，仅紧急时）：
+```shell
+git commit --no-verify
+```
+

kt-kernel/.githooks/pre-commit

@@ -1,10 +1,12 @@
 #!/usr/bin/bash
-# Pre-commit hook: run clang-format via CMake 'format' target and Black for Python before allowing commit.
-# If formatting makes changes, stage them and abort so user can review.
+# Pre-commit hook: run clang-format via kt-kernel's CMake 'format' target and Black for Python
+# before allowing commit. If formatting makes changes, stage them and abort so user can review.
 set -euo pipefail
 
 REPO_ROOT="$(git rev-parse --show-toplevel)"
-BUILD_DIR="$REPO_ROOT/build"
+# kt-kernel project directory within the monorepo
+KERNEL_DIR="$REPO_ROOT/kt-kernel"
+BUILD_DIR="$KERNEL_DIR/build"
 FORMAT_TARGET="format"
 CLANG_FORMAT_BIN="${CLANG_FORMAT_BIN:-clang-format}"
 BLACK_BIN="${BLACK_BIN:-black}"
@@ -20,10 +22,10 @@ if ! command -v "$BLACK_BIN" >/dev/null 2>&1; then
   echo "[pre-commit] black not found (looked for $BLACK_BIN). Skipping Python format." >&2
 fi
 
-# Configure build directory if missing (quiet)
-if [ ! -d "$BUILD_DIR" ] || [ ! -f "$BUILD_DIR/Makefile" ] && [ ! -f "$BUILD_DIR/build.ninja" ]; then
-  echo "[pre-commit] configuring project (cmake) ..." >&2
-  cmake -S "$REPO_ROOT" -B "$BUILD_DIR" >/dev/null
+# Configure kt-kernel build directory if missing (quiet)
+if [ ! -d "$BUILD_DIR" ] || { [ ! -f "$BUILD_DIR/Makefile" ] && [ ! -f "$BUILD_DIR/build.ninja" ]; }; then
+  echo "[pre-commit] configuring kt-kernel (cmake) ..." >&2
+  cmake -S "$KERNEL_DIR" -B "$BUILD_DIR" >/dev/null
 fi
 
 # Run format target (prefer ninja if present)
@@ -38,15 +40,18 @@ fi
 
 # Run black on staged python files (or entire repo if you prefer)
 if command -v "$BLACK_BIN" >/dev/null 2>&1; then
-  # Get staged python files; if none, skip
-  PY_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.py$' || true)
-  if [ -n "$PY_FILES" ]; then
-    echo "[pre-commit] running black on staged python files..." >&2
-    $BLACK_BIN $PY_FILES
-  else
-    # Optionally format all python files; comment out if not desired
-    # $BLACK_BIN "$REPO_ROOT"
-    :
+  # Run black only on kt-kernel's python and scripts directories
+  BLACK_PATHS=""
+  if [ -d "$KERNEL_DIR/python" ]; then
+    BLACK_PATHS="$BLACK_PATHS $KERNEL_DIR/python"
+  fi
+  if [ -d "$KERNEL_DIR/scripts" ]; then
+    BLACK_PATHS="$BLACK_PATHS $KERNEL_DIR/scripts"
+  fi
+  if [ -n "$BLACK_PATHS" ]; then
+    echo "[pre-commit] running black on:$BLACK_PATHS" >&2
+    # shellcheck disable=SC2086
+    $BLACK_BIN $BLACK_PATHS
   fi
 fi
 

kt-kernel/CMakeLists.txt

@@ -79,27 +79,40 @@ if(USE_CONDA_TOOLCHAIN)
     set(CMAKE_INSTALL_RPATH_USE_LINK_PATH OFF)
 endif()
 
-## Ensure git hooks are installed when configuring the project
-# If this is a git working copy and the installer exists, run it and fail the CMake configure
-# when installation fails. If no .git directory is present (e.g. source tarball), skip.
-if(EXISTS "${CMAKE_SOURCE_DIR}/.git" AND IS_DIRECTORY "${CMAKE_SOURCE_DIR}/.git")
-    if(EXISTS "${CMAKE_SOURCE_DIR}/scripts/install-git-hooks.sh")
-        message(STATUS "Detected .git; installing git hooks using scripts/install-git-hooks.sh")
-        execute_process(
-            COMMAND sh "${CMAKE_SOURCE_DIR}/scripts/install-git-hooks.sh"
-            WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
-            RESULT_VARIABLE _INSTALL_GIT_HOOKS_RESULT
-            OUTPUT_VARIABLE _INSTALL_GIT_HOOKS_OUT
-            ERROR_VARIABLE _INSTALL_GIT_HOOKS_ERR
+## Ensure git hooks are installed when configuring the project (monorepo-aware)
+# If we are inside a git worktree (repo root is outside kt-kernel now), invoke the installer
+# which will link kt-kernel/.githooks into the top-level .git/hooks. Otherwise, skip.
+find_program(GIT_BIN git)
+if(GIT_BIN)
+    execute_process(
+        COMMAND "${GIT_BIN}" rev-parse --show-toplevel
+        WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+        OUTPUT_VARIABLE _GIT_TOP
+        RESULT_VARIABLE _GIT_RV
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET
+    )
+    if(_GIT_RV EQUAL 0 AND EXISTS "${_GIT_TOP}/.git" AND IS_DIRECTORY "${_GIT_TOP}/.git")
+        if(EXISTS "${CMAKE_SOURCE_DIR}/scripts/install-git-hooks.sh")
+            message(STATUS "Detected git worktree at ${_GIT_TOP}; installing hooks from kt-kernel/.githooks")
+            execute_process(
+                COMMAND sh "${CMAKE_SOURCE_DIR}/scripts/install-git-hooks.sh"
+                WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+                RESULT_VARIABLE _INSTALL_GIT_HOOKS_RESULT
+                OUTPUT_VARIABLE _INSTALL_GIT_HOOKS_OUT
+                ERROR_VARIABLE _INSTALL_GIT_HOOKS_ERR
             )
-        if(NOT _INSTALL_GIT_HOOKS_RESULT EQUAL 0)
-            message(FATAL_ERROR "Installing git hooks failed (exit ${_INSTALL_GIT_HOOKS_RESULT}).\nOutput:\n${_INSTALL_GIT_HOOKS_OUT}\nError:\n${_INSTALL_GIT_HOOKS_ERR}")
+            if(NOT _INSTALL_GIT_HOOKS_RESULT EQUAL 0)
+                message(FATAL_ERROR "Installing git hooks failed (exit ${_INSTALL_GIT_HOOKS_RESULT}).\nOutput:\n${_INSTALL_GIT_HOOKS_OUT}\nError:\n${_INSTALL_GIT_HOOKS_ERR}")
+            endif()
+        else()
+            message(FATAL_ERROR "Required script 'scripts/install-git-hooks.sh' not found in kt-kernel; cannot install hooks.")
         endif()
     else()
-        message(FATAL_ERROR "Repository appears to be a git repo but required script 'scripts/install-git-hooks.sh' was not found. Please ensure hooks installer is present.")
+        message(STATUS "No git worktree detected; skipping git hooks installation")
     endif()
 else()
-    message(STATUS "No .git directory found; skipping git hooks installation")
+    message(STATUS "git not found; skipping git hooks installation")
 endif()
 
 set(CMAKE_CXX_STANDARD 20)

kt-kernel/cpu_backend/shared_mem_buffer.cpp

@@ -9,10 +9,10 @@
  **/
 #include "shared_mem_buffer.h"
 
+#include <errno.h>
 #include <numa.h>
 
 #include <cstdio>
-#include <errno.h>
 
 size_t MemoryRequest::total_size() {
   size_t total = 0;

kt-kernel/operators/moe-tp.hpp

@@ -7,6 +7,7 @@
 #include <cstdio>
 #include <type_traits>
 
+#include "../cpu_backend/shared_mem_buffer.h"
 #include "common.hpp"
 
 // Forward declaration for Llamafile backend type checking

kt-kernel/operators/moe_kernel/moe.hpp

@@ -13,11 +13,11 @@
 #include <vector>
 
 #include "../common.hpp"
+#include "../cpu_backend/shared_mem_buffer.h"
 #include "../moe-tp.hpp"
 #include "api/common.h"
 #include "api/mat_kernel.h"
 #include "llama.cpp/ggml.h"
-
 template <class T, bool PLAIN = true>
 class MOE_KERNEL_TP
 #ifdef FORWARD_TIME_PROFILE