cursor Init 完善多人协同changelog，以及godot相关基础skill和代码规范

.cursor/hooks/README.md

@@ -1,38 +1,61 @@
 # Cursor Hooks 说明
 
-## 结构
+## 文件
 
-```
+```text
 hooks/
-├── run-hook.ps1           # Windows dispatcher（读取 local-env.json 后分发）
-├── session-init.ps1       # sessionStart hook（PowerShell 版）
-├── session-init.sh        # sessionStart hook（bash 版）
-├── check-changelog.ps1    # stop hook（PowerShell 版）
-├── check-changelog.sh     # stop hook（bash 版）
-└── README.md              # 本文件
+├── run-hook.ps1           # Windows dispatcher；读取 local-env.json 并校验 JSON 输出
+├── session-init.ps1       # sessionStart（PowerShell）
+├── session-init.sh        # sessionStart（Bash）
+├── check-changelog.ps1    # stop / changelog guard（PowerShell）
+├── check-changelog.sh     # stop / changelog guard（Bash）
+└── README.md
 ```
 
-## 跨平台适配
+## Windows 配置（当前模板）
 
-`hooks.json` 中的 `command` 字段是**平台绑定的**——Windows 用 `powershell`，macOS/Linux 用 `bash`。
+`.cursor/hooks.json` 统一通过 dispatcher 调用：
 
-### Windows（当前）
+- `sessionStart`：`powershell -ExecutionPolicy Bypass -File .cursor/hooks/run-hook.ps1 session-init`，超时 5 秒。
+- `stop`：`powershell -ExecutionPolicy Bypass -File .cursor/hooks/run-hook.ps1 check-changelog`，超时 10 秒，`loop_limit` 为 1。
 
-hooks.json 使用 `powershell ... run-hook.ps1` 作为入口，dispatcher 根据
-`.cursor/local-env.json` 的 `shell` 字段决定执行 `.ps1` 还是 `.sh` 脚本。
+dispatcher 从 `.cursor/local-env.json` 读取 `shell`：
 
-### 迁移到 macOS / Linux
+- `powershell` / `pwsh`：运行同名 `.ps1`。
+- `bash` / `zsh` / `sh`：选择同名 `.sh`，并通过 `bash` 执行。
 
-将 hooks.json 的 command 改为直接调用 `.sh` 脚本：
+stdin 以 UTF-8 原样转发。子脚本成功时，dispatcher 校验并规范化其 JSON 对象；脚本缺失、配置无效、启动失败、非零退出或输出无效时，只向 stderr 写诊断，并向 hook 返回非阻断的 `{}`。
+
+## macOS / Linux 切换
+
+macOS/Linux 不需要 Windows dispatcher。将 `.cursor/hooks.json` 改为 Bash 直调：
 
 ```json
 {
   "version": 1,
   "hooks": {
-    "sessionStart": [{ "command": "bash .cursor/hooks/session-init.sh", "timeout": 5 }],
-    "stop": [{ "command": "bash .cursor/hooks/check-changelog.sh", "timeout": 10, "loop_limit": 1 }]
+    "sessionStart": [
+      {
+        "command": "bash .cursor/hooks/session-init.sh",
+        "timeout": 5
+      }
+    ],
+    "stop": [
+      {
+        "command": "bash .cursor/hooks/check-changelog.sh",
+        "timeout": 10,
+        "loop_limit": 1
+      }
+    ]
   }
 }
 ```
 
-同时更新 `.cursor/local-env.json` 的 `shell` 字段为 `bash` 或 `zsh`。
+同时把本机 `.cursor/local-env.json` 的 `shell` 设为 `bash`（或实际使用的 `zsh`）。Bash 脚本不依赖 `jq`；优先用 `python3`（Windows Git Bash 可回退 `python`）安全解析/生成 JSON，解释器缺失或解析失败时 fail-open 返回 `{}`。
+
+## 行为
+
+- `session-init` 清除上一会话的 `.cursor/changelog/.changelog-ack`，并刷新 gitignored 的 `.cursor/changelog/.session-start`。非 `agent` 模式通过 hook `env` 设置 `CURSOR_SKIP_CHANGELOG=1`。
+- Cursor 的 `stop` 输入不包含可靠的工具编辑历史，因此 `check-changelog` 不解析不存在的“编辑证据”。它只在未 ack、未被 session 环境跳过，且 Godot 源码/配置同时晚于本会话起点与当前 changelog 时返回 `followup_message`，避免旧会话残留 mtime 误报。
+- 扫描从仓库根开始，覆盖 `project.godot`、`.gd`、`.tscn`、`.tres`、`.res`、`.gdshader`、`.cfg`、`.json`、`.cs`、`.csproj` 及常用工具脚本；跳过 `.git`、`.cursor`、`.godot`、依赖目录、Python 缓存/虚拟环境和常见构建输出目录。
+- 所有正常与失败路径都在 stdout 输出一个合法 JSON 对象；检查失败默认不阻断。