继续完善代码

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` 绝对路径）。
 
 ### 引用方式