doc: make doc better

Author: lvsi

.work/extra/doc/3.DEVELOPMENT_EN.md

@@ -312,3 +312,60 @@ Each service has a ```data``` directory, which is the only data channel from the
 
 - The persistent data of databases like MySQL and Redis will be mounted to their ```data``` directories.
 - Projects based on environments such as Python/PHP/Go will be mounted to their ```data``` directories.
+
+## 6. Service Lifecycle Hooks
+
+### (1) What are hooks
+
+Each service can drop up to 4 scripts into its `hooks/` directory; sparrow runs each at a fixed point in the start/stop flow:
+
+| Script | When it runs |
+|---|---|
+| `before_start.sh` | **Before** the container starts (before pull/build and `docker compose up`) |
+| `after_start.sh` | **After** the container starts |
+| `before_stop.sh` | **Before** the container stops |
+| `after_stop.sh` | **After** the container stops |
+
+Typical uses: generate or seed config files the container needs in `before_start.sh`; clean up scratch resources in `after_stop.sh`.
+
+The dispatcher lives in the `sparrow` script: it looks for `{service}/hooks/{hook_type}.sh` and executes it if present. A missing file is treated as a no-op (not an error).
+
+### (2) Hooks are sourced into the current shell — **do not use `exit`**
+
+⚠️ **Important footgun**: hooks are not forked into a subshell. Sparrow runs them with `.` (source) inside its own main shell. The non-obvious consequence:
+
+- Writing `exit 0` / `exit 1` in a hook **terminates the entire sparrow process**. The remaining steps (pull, build, `docker compose up`) are silently skipped, and the user sees what looks like a clean exit — very easy to misdiagnose.
+- To return early from a hook, use **`return 0` / `return 1`** instead. That only exits the sourced block; sparrow's main flow keeps going.
+
+Reference pattern:
+
+```sh
+#!/bin/sh
+
+# include sdk of sparrow.
+. .work/include/sdk.sh
+
+# Config already initialized — skip and let sparrow continue.
+if [ -f "./myservice/data/config.json" ]; then
+    print_info "config already exists, skip init"
+    return 0          # ← correct: exits the hook only
+fi
+
+# ... initialization logic ...
+if ! some_init_command; then
+    print_error "init failed"
+    return 1          # ← still use return, even on the failure path
+fi
+```
+
+By the same logic, **do not** use `set -e` or anything like `kill $$` inside a hook — they affect the parent shell. If you need to signal a precondition failure, log it with `print_error` and `return 1`.
+
+### (3) What is available inside a hook
+
+`sdk.sh` has already been sourced by the time your hook runs, so you can use sparrow's helpers directly:
+
+- `print_info` / `print_warn` / `print_error` — colored log helpers
+- All exported variables from `.env` (including `ENABLE_SERVICE_LIST` and per-service `IMAGE_*_VERSION`)
+- `${SPARROW_BASE_PATH}` — project root
+
+Re-sourcing the sdk inside a hook (as defensive guard) is safe.

.work/extra/doc/3.DEVELOPMENT_ZH.md

@@ -312,3 +312,60 @@ server {
 
 - MySQL、Redis 等数据库的持久化数据会挂载到各自的 data 目录。
 - Python/PHP/Go 等开发环境项目也会挂载到对应的 data 目录。
+
+## 6. 服务生命周期 hook
+
+### (1) hook 是什么
+
+每个服务的 `hooks/` 目录下可以放置 4 个脚本，分别在服务启停的关键节点被自动执行：
+
+| 脚本 | 触发时机 |
+|---|---|
+| `before_start.sh` | 容器启动**之前**（pull/build 镜像、`docker compose up` 之前） |
+| `after_start.sh` | 容器启动**之后** |
+| `before_stop.sh` | 容器停止**之前** |
+| `after_stop.sh` | 容器停止**之后** |
+
+典型用途：在 `before_start.sh` 里生成或初始化容器需要的配置文件、密钥；在 `after_stop.sh` 里清理临时资源。
+
+调用入口在 `sparrow` 脚本中：找到名为 `{service}/hooks/{hook_type}.sh` 的文件就执行。文件不存在视为无操作，不报错。
+
+### (2) hook 是被 source 进当前 shell 的，**不要在 hook 里用 `exit`**
+
+⚠️ **重要陷阱**：hook 不是 fork 子进程执行，而是用 `.` (source) 在 sparrow 主 shell 里执行。这带来一个反直觉的后果：
+
+- 在 hook 里写 `exit 0`/`exit 1` 会**直接终止 sparrow 整个进程**，后续的 pull、build、docker compose up 全部跳过，但用户看到的仍然是看似"正常退出"——非常隐蔽。
+- 想从 hook 中途返回，请使用 **`return 0` / `return 1`**，效果是退出当前 source 块，sparrow 主流程继续向下走。
+
+参考写法：
+
+```sh
+#!/bin/sh
+
+# include sdk of sparrow.
+. .work/include/sdk.sh
+
+# 如果配置已存在，跳过初始化（让 sparrow 继续后续步骤）。
+if [ -f "./myservice/data/config.json" ]; then
+    print_info "config already exists, skip init"
+    return 0          # ← 正确：仅退出 hook，sparrow 继续
+fi
+
+# ... 初始化逻辑 ...
+if ! some_init_command; then
+    print_error "init failed"
+    return 1          # ← 即使想以失败状态退出，也用 return
+fi
+```
+
+同样地，hook 内**不要**用 `set -e` 或调用 `kill $$` 之类会影响父 shell 的语句。需要校验前置条件失败就告警时，用 `print_error` + `return 1` 即可。
+
+### (3) hook 里可以用什么
+
+`sdk.sh` 在 hook 被执行前就已经 source 过了，因此 hook 内可以直接使用 sparrow 的工具函数，例如：
+
+- `print_info` / `print_warn` / `print_error` —— 带颜色的日志输出
+- `.env` 中所有已 export 的变量（包括 `ENABLE_SERVICE_LIST`、各服务的 `IMAGE_*_VERSION` 等）
+- `${SPARROW_BASE_PATH}` —— 项目根目录
+
+如果 hook 内还想再次主动 source sdk（例如为了防御性写法），重复 source 是安全的。

.work/extra/service_example/hooks/README.md

@@ -1,2 +1,20 @@
 ## What is this directory
+
 This is the hook actions while the service/container start/stop.
+
+### Important: hooks are sourced, not forked
+
+Hooks are executed via `. filename` (source), not in a subshell. Therefore:
+
+- **Do NOT use `exit 0` / `exit 1` in hooks** — it terminates the whole sparrow process.
+- **Use `return 0` / `return 1` instead** — it exits only the sourced block, and sparrow continues.
+- Do NOT use `set -e` inside hooks — it affects the parent shell.
+
+### Available hooks
+
+| Hook file | Timing |
+|---|---|
+| `before_start.sh` | Before container start (before pull/build and `docker compose up`) |
+| `after_start.sh` | After container start |
+| `before_stop.sh` | Before container stop |
+| `after_stop.sh` | After container stop |

openclaw/hooks/README.md

@@ -1,2 +1,20 @@
 ## What is this directory
+
 This is the hook actions while the service/container start/stop.
+
+### Important: hooks are sourced, not forked
+
+Hooks are executed via `. filename` (source), not in a subshell. Therefore:
+
+- **Do NOT use `exit 0` / `exit 1` in hooks** — it terminates the whole sparrow process.
+- **Use `return 0` / `return 1` instead** — it exits only the sourced block, and sparrow continues.
+- Do NOT use `set -e` inside hooks — it affects the parent shell.
+
+### Available hooks
+
+| Hook file | Timing |
+|---|---|
+| `before_start.sh` | Before container start (before pull/build and `docker compose up`) |
+| `after_start.sh` | After container start |
+| `before_stop.sh` | Before container stop |
+| `after_stop.sh` | After container stop |