chore: update build scripts and documentation for llama.cpp submodule integration

Author: ZMXJJ

.github/workflows/build-sidecar.yml

@@ -10,10 +10,12 @@ name: Build sidecar (llama-server + gateway)
 on:
   push:
     paths:
+      - "llama.cpp"
       - "minicpm-sidecar/**"
       - ".github/workflows/build-sidecar.yml"
   pull_request:
     paths:
+      - "llama.cpp"
       - "minicpm-sidecar/**"
       - ".github/workflows/build-sidecar.yml"
   workflow_dispatch:
@@ -43,6 +45,8 @@ jobs:
         working-directory: minicpm-sidecar
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Install cmake (Linux)
         if: runner.os == 'Linux'
@@ -69,10 +73,6 @@ jobs:
           irm https://astral.sh/uv/install.ps1 | iex
           Add-Content $env:GITHUB_PATH "$env:USERPROFILE\.local\bin"
 
-      - name: Clone vendored llama.cpp
-        shell: bash
-        run: ./scripts/clone-llama.sh
-
       - name: Build llama-server (POSIX)
         if: runner.os != 'Windows'
         shell: bash

.github/workflows/release.yml

@@ -36,6 +36,8 @@ jobs:
     name: mac-${{ matrix.triple }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -122,6 +124,8 @@ jobs:
     name: linux-x64
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -165,6 +169,8 @@ jobs:
         shell: pwsh
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -177,11 +183,6 @@ jobs:
           irm https://astral.sh/uv/install.ps1 | iex
           Add-Content $env:GITHUB_PATH "$env:USERPROFILE\.local\bin"
 
-      - name: Clone llama.cpp
-        working-directory: minicpm-sidecar
-        shell: bash
-        run: ./scripts/clone-llama.sh
-
       - name: Build llama-server
         working-directory: minicpm-sidecar
         run: ./scripts/build-llama.ps1

.gitignore

@@ -15,7 +15,9 @@ dist/
 minicpm-sidecar/bin/
 minicpm-sidecar/build/build/
 minicpm-sidecar/build/dist/
-minicpm-sidecar/third_party/llama.cpp/
+
+# llama.cpp submodule build outputs (the submodule itself is tracked)
+llama.cpp/build/
 
 # Model weights — too big to ship, friends/colleagues download separately
 models/

CHANGELOG.md

@@ -13,13 +13,11 @@
 - 根级 [`LICENSE`](LICENSE)（AGPL-3.0-only，与 `clawd-on-desk/LICENSE` 同源）。
 - 根级 [`NOTICE.md`](NOTICE.md)：fork 声明 + llama.cpp / MiniCPM / OpenClaw 等第三方 attribution。
 - 根级 [`CONTRIBUTING.md`](CONTRIBUTING.md)：quickstart、测试要求、commit / PR 约定。
-- [`docs/archive/`](docs/archive/) 子目录，迁入 v0.7 时代的设计文档（[PRD-sidecar-cross-platform-refactor.md](docs/archive/PRD-sidecar-cross-platform-refactor.md)、[architecture-and-cross-platform-report.md](docs/archive/architecture-and-cross-platform-report.md)），并附 [`README.md`](docs/archive/README.md) 解释归档背景。
 
 ### 变更
 
 - [`README.md`](README.md) 删除 deprecated 目录段落，文档索引指向归档后的新路径，新增 CONTRIBUTING 链接。
 - [`docs/development.md`](docs/development.md) 删除 conda 路径、双份 sidecar 同步注意事项、旧 `build/build-sidecar.sh` 引用；"仓库结构"框图按新平铺布局重写。
-- [`docs/llama-cpp-migration.md`](docs/llama-cpp-migration.md) 旧 PyTorch sidecar / PyInstaller 路径改为历史叙述。
 - [`skills/deploy-minicpm-pet/SKILL.md`](skills/deploy-minicpm-pet/SKILL.md) 完整改写：所有 `minicpm-pet-bridge*` 引用替换为 `minicpm-sidecar`，安装步骤更新到 cmake + uv + 几十 MB gateway。
 - [`.gitignore`](.gitignore) 删除 `build/*` 历史例外规则。
 
@@ -30,7 +28,7 @@
 ### 新增
 
 - 单一推理目录 [`minicpm-sidecar/`](minicpm-sidecar/)，结构为「llama-server（vendor llama.cpp）+ 瘦 FastAPI gateway」。
-- vendor 子模块脚本 [`scripts/clone-llama.sh`](minicpm-sidecar/scripts/clone-llama.sh)（pin 在 [zhangtao2-1/llama.cpp@c5ede29](https://github.com/zhangtao2-1/llama.cpp)，即 [PR #23384](https://github.com/ggml-org/llama.cpp/pull/23384) 的 MiniCPM5 tokenizer 提交）。
+- 顶层 git submodule [`llama.cpp/`](llama.cpp)（pin 在 [zhangtao2-1/llama.cpp@c5ede29](https://github.com/zhangtao2-1/llama.cpp)，即 [PR #23384](https://github.com/ggml-org/llama.cpp/pull/23384) 的 MiniCPM5 tokenizer 提交）。
 - 各平台编译脚本：`scripts/build-llama.sh`（macOS / Linux）+ `scripts/build-llama.ps1`（Windows），按 `LLAMA_ACCEL=metal|cuda|cpu` 走 cmake。
 - Gateway PyInstaller 单文件打包：`scripts/build-gateway.sh` + [`build/gateway.spec`](minicpm-sidecar/build/gateway.spec)，无 torch 依赖，最终二进制几十 MB 量级。
 - `scripts/build-all.sh` / `scripts/run-dev.sh` 一站式入口。
@@ -60,7 +58,7 @@
 
 ### 文档
 
-- 新增 [`docs/llama-cpp-migration.md`](docs/llama-cpp-migration.md) 记录本次变动 + vendor 升级路径。
+- 新增过 `docs/llama-cpp-migration.md` 记录本次变动 + vendor 升级路径，后续文档精简时已移除。
 - [`README.md`](README.md) 顶部状态行 / 安装步骤 / 文档索引同步更新到 v0.8。
 - 旧的两套 bridge 目录写入 [`DEPRECATED.md`](minicpm-pet-bridge/DEPRECATED.md)。
 

NOTICE.md

@@ -27,10 +27,10 @@ The sidecar embeds [`llama-server`](https://github.com/ggml-org/llama.cpp)
 (MIT License, © 2023 Georgi Gerganov and llama.cpp contributors).
 While MiniCPM5 tokenizer support is still in flight upstream
 ([PR #23384](https://github.com/ggml-org/llama.cpp/pull/23384)), the
-vendored sources are pinned to
+sources are included as a git submodule at `llama.cpp/`, pinned to
 [zhangtao2-1/llama.cpp@c5ede29](https://github.com/zhangtao2-1/llama.cpp).
-See [minicpm-sidecar/scripts/clone-llama.sh](minicpm-sidecar/scripts/clone-llama.sh)
-for the exact commit and [minicpm-sidecar/README.md](minicpm-sidecar/README.md#vendor-分支)
+See [.gitmodules](.gitmodules) for the URL and
+[minicpm-sidecar/README.md](minicpm-sidecar/README.md#submodule--vendor-分支)
 for the upgrade path.
 
 ### MiniCPM model weights

adapters/README.md

@@ -30,8 +30,8 @@ adapters/
 
 ## 从 PEFT safetensors 转成 GGUF
 
-llama.cpp 只认 GGUF 格式的 LoRA。`minicpm-sidecar/third_party/llama.cpp/convert_lora_to_gguf.py`
-（vendor 在 `scripts/clone-llama.sh` pin 的版本里）会把 PEFT 适配器 + 一份只读的 HF
+llama.cpp 只认 GGUF 格式的 LoRA。仓库顶层的 `llama.cpp/convert_lora_to_gguf.py`
+（submodule pin 的版本里）会把 PEFT 适配器 + 一份只读的 HF
 base config 拼成 llama-server 能消费的单文件 GGUF。
 
 ```bash
@@ -41,8 +41,8 @@ ADAPTER=adapters/lora_nekoqa_adapter_20260515_0738
 
 # 2. 跑转换脚本（需要一个带 torch + transformers 的 venv，
 #    本仓库的 minicpm-pet-bridge-uv/.venv 即可）
-minicpm-pet-bridge-uv/.venv/bin/python3 \
-  minicpm-sidecar/third_party/llama.cpp/convert_lora_to_gguf.py \
+python3 \
+  llama.cpp/convert_lora_to_gguf.py \
   --base "$BASE" \
   --outtype f16 \
   --outfile "$ADAPTER/adapter_model.f16.gguf" \

clawd-on-desk/docs/investigations/permission-hook-fail-deny-investigation.md

@@ -96,7 +96,7 @@ PreToolUse matcher 接受 `Bash`, `Edit|Write`, `mcp__.*` 等所有工具名。
 - [ ] 监控 anthropics/claude-code#46193 的 status
 - [ ] CC 修了之后：
   - 删除 `README.md` / `README.zh-CN.md` 里 Known Limitations 表格的对应行
-  - 把这个文档归档（移到 `docs/archive/` 或在标题加 RESOLVED）
+  - 在标题加 RESOLVED，或直接删除这份调查文档
   - 顺手更新 `hooks/install.js:248-250` 那条过时注释（"Edit/Write permissions are handled by Claude Code's own permission mode — not our hook"），写明历史脉络
 
 ## 不要做的事