继续完善代码

references/CLI.md

@@ -6,9 +6,24 @@
 
 ```bash
 python {baseDir}/scripts/main.py health
+python {baseDir}/scripts/main.py config-path
 python {baseDir}/scripts/main.py version
 ```
 
+## config-path（配置路径）
+
+输出 JSON，便于排查用户 `.env` 落盘位置：
+
+```json
+{
+  "skill": "your-skill-slug",
+  "env_path": "{DATA_ROOT}/{USER_ID}/your-skill-slug/.env",
+  "example_path": "{skill_root}/.env.example"
+}
+```
+
+启动任意 CLI 命令前会自动执行 `bootstrap_skill_config()`（首次 copy `.env.example`，升级后合并缺失 key）。
+
 ## health 标准输出（runtime diagnostics）
 
 `health` 委托 `jiangchang_skill_core.collect_runtime_diagnostics`，输出统一 runtime 诊断。典型字段：
@@ -20,6 +35,7 @@ python {baseDir}/scripts/main.py version
 - `ffmpeg_path` / `ffmpeg_available` — ffmpeg 探测结果
 - `background_music_mp3_count` — 可用背景音乐数量
 - `runtime_issue[warning|error]` — 非致命/致命问题列表
+- `env_path` / `env_exists` / `example_path` — 用户 `.env` 与仓库模板路径（不输出敏感值）
 
 `health` **只读诊断**，不下载、不修复 media-assets，不执行业务 DB / 邮箱 / 订单等检查。
 

references/CONFIG.md

@@ -5,10 +5,11 @@
 ## 核心原则
 
 1. **`.env.example` 进仓库**：带注释的全量默认配置，是配置项的"单一事实来源"。
-2. **首次运行自动 copy**：`setup` / `doctor` / 首次 `run` 时，把 `.env.example` 复制到
-   `{CLAW_DATA_ROOT}/{user}/{slug}/.env`（**已存在则不覆盖**，保护用户改过的值）。
-3. **三级优先级读取**：`进程环境变量` > `数据目录/.env` > `.env.example 默认值`。
-4. **敏感信息绝不进 `.env`**：密码/密钥/口令走 account-manager 的 `secret-ref`（见下"红线"）。
+2. **首次运行自动 copy**：`scripts/main.py` 启动与 `cli.app.main()` 均会调用 `util.config_bootstrap.bootstrap_skill_config()`，把仓库根目录 `.env.example` 复制到
+   `{CLAW_DATA_ROOT}/{user}/{slug}/.env`（**已存在则不整体覆盖**，保护用户改过的值）。
+3. **技能升级合并缺失项**：`merge_missing_env_keys` 会把 `.env.example` 中新增、但用户 `.env` 尚未包含的 key **追加**进去（带 `comment_skill` 注释块）。
+4. **三级优先级读取**：`进程环境变量` > `数据目录/.env` > `.env.example 默认值`。
+5. **敏感信息绝不进 `.env`**：密码/密钥/口令走 account-manager 的 `secret-ref`（见下"红线"）。
 
 ## 标准配置项
 
@@ -53,19 +54,32 @@ HUMAN_WAIT_TIMEOUT=180                 # 滑块/验证码/2FA 等人工超时(
 *.env.local
 ```
 
-## 配置读取层（模板提供）
+## 配置 bootstrap（模板提供）
 
-模板会提供一个统一 `config.py`，约定行为：
+模板在 `scripts/util/config_bootstrap.py` 提供 `bootstrap_skill_config()`：
 
 ```python
-config.get("TARGET_BASE_URL")              # 三级优先级解析
-config.get_bool("OPENCLAW_BROWSER_HEADLESS")
-config.get_float("STEP_DELAY_MIN", 1.0)
-config.ensure_env_file()                   # 首次把 .env.example copy 到数据目录
+from util.config_bootstrap import bootstrap_skill_config
+
+bootstrap_skill_config()  # main.py 与 cli.app.main() 启动时调用
 ```
 
-- 启动时调一次 `ensure_env_file()` 完成落盘。
-- 所有业务代码**只通过 `config.get*` 读配置**，不直接 `os.environ`，便于统一管理与测试覆盖。
+内部委托共享 runtime 的 `jiangchang_skill_core.config`：
+
+```python
+config.ensure_env_file(SKILL_SLUG, example_path)      # 首次落盘
+config.merge_missing_env_keys(example_path, env_path)   # 升级后追加缺失 key
+```
+
+业务代码**只通过 `config.get*` 读配置**，不直接 `os.environ`：
+
+```python
+config.get("TARGET_BASE_URL")
+config.get_bool("OPENCLAW_BROWSER_HEADLESS")
+config.get_float("STEP_DELAY_MIN", 1.0)
+```
+
+`config-path` 命令输出 JSON：`skill`、`env_path`（用户数据目录 `.env`）、`example_path`（仓库 `.env.example` 绝对路径）。
 
 ### 引用方式
 

references/RUNTIME.md

@@ -32,7 +32,15 @@ Windows:
 - `media_assets_root`、`ffmpeg_path`、`background_music_*`
 - `record_video_enabled`、`runtime_issue[warning|error]`
 
-`health` 是**只读诊断**，**不会**触发 media-assets 下载或修复。
+`health` 是**只读诊断**，**不会**触发 media-assets 下载或修复。并补充 `env_path` / `env_exists` / `example_path` 配置路径字段。
+
+## 配置 bootstrap
+
+- 仓库内 `.env.example` 是配置模板（单一事实来源）。
+- 用户实际 `.env`：`{CLAW_DATA_ROOT}/{CLAW_USER_ID}/{skill_slug}/.env`。
+- `scripts/main.py` 与 `cli.app.main()` 启动时调用 `util.config_bootstrap.bootstrap_skill_config()`。
+- 配置优先级：**进程环境变量** > **用户 `.env`** > **`.env.example` 默认值**。
+- 公共 `config` / `merge_missing_env_keys` 来自共享 runtime 的 `jiangchang-platform-kit>=1.0.11`，**不得** vendored `scripts/jiangchang_skill_core/`。
 
 ## media-assets / ffmpeg / 背景音乐