docs: add discussion and认知修正 about gitea runner and sql.js migration

changelog.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file.
 
+## 认知修正
+
+### 1. Bun 编译与 native 模块
+Bun 的 `bun build --compile` 无法正确处理 native 模块（如 `@libsql/client`），运行时会报错 "Cannot find module"。这是 Bun 1.3.4+ 的已知 bug。
+
+**解决方案**：使用纯 JS 实现的 `sql.js` 替代 `@libsql/client`，可正常编译运行。
+
+### 2. Gitea Actions 镜像问题
+自定义镜像默认未安装 git，需要在 workflow 中手动安装：
+
+```yaml
+- name: Install git
+  run: apt-get update && apt-get install -y git
+```
+
+### 3. Release 自动生成 changelog
+在 workflow 中使用 git log 生成变更记录：
+
+```bash
+PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+CHANGES=$(git log --pretty=format:"- %s (%h)" "$PREV_TAG..HEAD" 2>/dev/null || echo "")
+```
+
+### 4. Gitea 发布二进制文件的限制
+由于 runner 运行在 Linux 环境，无法直接编译 Windows/macOS 可执行文件。如需跨平台发布，考虑：
+- 使用 Go/Rust 等支持交叉编译的语言
+- 或仅发布源代码压缩包
+
+---
+
 ## [0.1.0] - 2026-04-11
 
 ### Added