10 KiB
配置标准：.env 规范与首次落盘机制
解决"每个 skill 每次都要手动搞一堆环境变量、账号、地址"的痛点。统一约定：模板内置
.env.example，skill 首次运行自动落盘到用户数据目录，之后从那里读。
核心原则
- 三层优先级：
进程环境变量>{数据目录}/.env> 仓库.env.example默认值。 .env.example进仓库：带注释的全量默认配置，是配置项的"单一事实来源"。- 首次运行自动 copy（bootstrap）：
scripts/main.py启动与cli.app.main()均会调用util.config_bootstrap.bootstrap_skill_config()，把仓库根目录.env.example复制到{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{slug}/.env（已存在则不整体覆盖，保护用户改过的值）。 - 技能升级合并缺失项：
merge_missing_env_keys会把.env.example中新增、但用户.env尚未包含的 key 追加进去（带注释块）。 - 敏感信息绝不进
.env：密码/密钥/口令走 account-manager 的secret-ref（见下"红线"）。
.env.example 注释 = 配置管理用户文案（硬规则）
匠厂宿主「数据管理 → 配置管理」会把 .env / .env.example 的注释展示给最终用户（英文 key 可保留作标题）。因此注释必须按产品文案来写，不能按开发备忘录来写。
行头与行尾分工
| 位置 | 职责 | 要求 |
|---|---|---|
行头（KEY= 上一行的 # …） |
是什么：中文说明该配置项干什么 | 每个活跃 key 必有一行完整中文行头 |
行尾（KEY=值 同一行 # 之后） |
怎么填：可选值、单位、推荐默认、何时要改 | 有枚举、开关、单位时必有；纯自由文本也应尽量写清填法 |
宿主当前会把「行头 + 行尾」拼成 key 下方的多行说明。按上表书写后，用户看到的自然是「先懂是什么，再知道怎么填」。
不要依赖 # ── 分组 ── 装饰线给整组做唯一说明：宿主只会把行头挂到紧挨着的下一个活跃 key，后面的 key 不会自动继承。分组可用空行区分；逐 key 自带行头（+ 行尾）才是硬要求。
必须做到
- 每个会进入配置管理的活跃
KEY=都有完整中文行头。 - 枚举 /
0|1开关 / 带单位的数值：必须有中文行尾，解释每个可选值或单位，并给出推荐。 - 业务专属 key 同样适用本规则，不得只留英文 key、不写中文说明。
- 开发向细节（四档 adapter 实现、录屏管线、路径解析 API）写在
development/ADAPTER.md、RPA.md、DATA_PATHS.md等文档；禁止写进.env.example注释。
禁止出现在注释中的内容
见 development/...、见 ADAPTER.md、见 RPA.md、见 DATA_PATHS.md等仓库文档指向- 默认假设读者是开发者的黑话：如单独甩
adapter 档位、CI、account-manager、CWD、workspace而不解释 - 只写裸枚举（如
mock | real_rpa）却不说明每个值对用户意味着什么 - 多个 key 共用一个行头，后面的 key 没有任何自己的说明
若必须提到账号体系：写成用户能懂的「请在账号管理中登记密码 / 平台标识须一致」，不要只写内部模块名。
正例
# 运行模式：决定本技能用模拟数据还是真实浏览器/接口去执行
OPENCLAW_TEST_TARGET=mock # 可选：mock=本地模拟，simulator_rpa=仿真站点，real_api=真实接口，real_rpa=真实浏览器；模板默认 mock，日常正式使用请改为 real_rpa
# 是否显示浏览器窗口：打开后能否看见自动化操作过程
OPENCLAW_BROWSER_HEADLESS=0 # 0=显示窗口（推荐，便于排查），1=后台静默运行
反例（禁止）
# ── 运行模式 / adapter 档位（见 development/ADAPTER.md）──
OPENCLAW_TEST_TARGET=real_rpa # 生产默认真实 RPA；单测/CI 可改为 mock
# ── 好看视频 / 百度账号（须与 account-manager 平台 key 一致）──
TARGET_PLATFORM=baidu
HAOKAN_VIDEO_SELECTOR=video.art-video
问题：文档路径与开发黑话；行尾半给用户半给 CI；后续 key 无行头/行尾，用户只看到英文名。
标准配置项（.env 分组）
每个 skill 的 .env.example 至少包含这些通用项（按需增减）。注释写法须与仓库根目录 .env.example 保持同级清晰度（行头 = 是什么，行尾 = 怎么填）：
# 运行模式：决定本技能用模拟数据还是真实浏览器/接口去执行
OPENCLAW_TEST_TARGET=mock # 可选：mock=本地模拟，simulator_rpa=仿真站点，real_api=真实接口，real_rpa=真实浏览器；模板默认 mock，日常正式使用请改为 real_rpa
# 目标网站地址：技能要访问的网站或服务地址
TARGET_BASE_URL=https://sandbox.jc2009.com # 填写完整网址（含 https://）；换环境时再改，一般保持默认即可
# 默认登录账号：仅填写非敏感的账号标识（如工号/登录名）
DEFAULT_LOGIN_ID=04110001 # 只填账号标识，不要填密码；密码请在「账号管理」中登记
# 是否显示浏览器窗口：打开后能否看见自动化操作过程
OPENCLAW_BROWSER_HEADLESS=0 # 0=显示窗口（推荐，便于排查），1=后台静默运行
# 浏览器防检测：降低被网站识别为自动化工具的概率
OPENCLAW_PLAYWRIGHT_STEALTH=1 # 1=开启（推荐），0=关闭；一般保持默认
# 是否录制操作过程：用于留证、复现问题或向他人演示
OPENCLAW_RECORD_VIDEO=0 # 0=不录屏（默认），1=录屏并生成带说明的视频文件；需要留证时再改为 1
# 失败时是否截图：任务出错时自动保存现场截图，便于排查
OPENCLAW_ARTIFACTS_ON_FAILURE=1 # 1=失败时截图（推荐），0=不截图
# 步骤最短等待：两步操作之间随机停顿的下限，模拟真人节奏
STEP_DELAY_MIN=1.0 # 单位：秒；一般保持默认，页面不稳定时可略调大
# 步骤最长等待：两步操作之间随机停顿的上限
STEP_DELAY_MAX=5.0 # 单位：秒；须大于等于最短等待；一般保持默认
# 人工处理超时：遇到滑块、验证码、二次验证时，等待人工处理的最长时间
HUMAN_WAIT_TIMEOUT=180 # 单位：秒；来不及处理时可调大，如 300
四档运行模式的实现与测试约定见 ADAPTER.md；录屏管线见 RPA.md。这些内容不要写回 .env.example 注释。
业务专属配置必须带技能前缀（如 DEMO_XXX、MY_SKILL_XXX、SKILL_DOWNLOAD_DIR），不要污染全局命名空间（禁止 SCRAPE_1688_*、RECEIVE_ORDER_* 等跨技能前缀写入模板）。
数据目录子路径（下载 / 导入 / 导出）
技能自己写入的文件默认在 {JIANGCHANG_DATA_ROOT}/{USER_ID}/{slug}/ 下标准子目录（downloads/、imports/、exports/ 等）。须通过 util.runtime_paths.resolve_data_path() 或 get_*_dir() 解析，禁止 os.path.abspath(config.get(...)) 相对 CWD。
- 权威说明（开发）：
DATA_PATHS.md .env.example中路径类配置留空或保持注释即用默认；若写相对路径，必须相对 skill 数据目录，禁止./outputs/...这类相对 workspace 的写法- 可选 env：
SKILL_DOWNLOAD_DIR、SKILL_IMPORT_DIR、SKILL_EXPORT_DIR等；若作为活跃 key 出现在配置管理中，同样须有用户向行头/行尾（见模板根.env.example）
录屏开关（OPENCLAW_RECORD_VIDEO）
- 模板默认
OPENCLAW_RECORD_VIDEO=0，降低本地开发 / 调试成本（不启 ffmpeg、不生成 MP4）。 - 需要生产留证、合规记录、客户现场复现或排障时，可在用户
.env或进程环境变量中设为OPENCLAW_RECORD_VIDEO=1。 - 默认关闭不代表可以删除录屏接入：RPA / 长任务代码仍须保留
RpaVideoSession、video.add_step与 video artifact 写入result_summary（见RPA.md§5.3）。 - 已落盘的用户
.env不会被模板整体覆盖；老用户保留原值，技能升级时仅通过merge_missing_env_keys追加.env.example中新增的 key。
🚫 红线：敏感信息不进 .env
.env 只放非敏感运行参数（模式、地址、开关、超时、账号标识）。密码、密钥、动态口令、token——
- 走 account-manager 注册凭据，用
--secret-storage env --secret-ref XXX引用； - 真实值由宿主/用户通过进程环境变量注入，不落任何文件、不进 git。
.gitignore 必须包含：
.env
*.env.local
配置 bootstrap（模板提供）
模板在 scripts/util/config_bootstrap.py 提供 bootstrap_skill_config()：
from util.config_bootstrap import bootstrap_skill_config
bootstrap_skill_config() # main.py 与 cli.app.main() 启动时调用
内部委托共享 runtime 的 jiangchang_skill_core.config：
config.ensure_env_file(SKILL_SLUG, example_path) # 首次落盘
config.merge_missing_env_keys(example_path, env_path) # 升级后追加缺失 key
业务代码只通过 config.get* 读配置，不直接 os.environ：
config.get("TARGET_BASE_URL")
config.get_bool("OPENCLAW_BROWSER_HEADLESS")
config.get_float("STEP_DELAY_MIN", 1.0)
health / config-path
health：输出collect_runtime_diagnostics字段（platform_kit_version_ok、ffmpeg_path等），不打印敏感值；补充env_path/env_exists/example_path。config-path：输出 JSON，包含skill、env_path（用户数据目录.env）、example_path（仓库.env.example绝对路径），便于排查落盘位置；业务 skill 建议附加list_resolved_data_paths()中的子目录路径（见DATA_PATHS.md）。
doctor / setup 命令（可选）
每个 skill 可提供自检命令：
python scripts/main.py doctor：检查浏览器、Profile/账号、.env落盘、设备等。python scripts/main.py setup：初始化演示账号、首次落盘.env。
相关文档
RPA.md— 三端 RPA 标准与各开关含义（开发向；勿写入.env注释）ADAPTER.md—OPENCLAW_TEST_TARGET四档模式（开发向；勿写入.env注释）RUNTIME.md—JIANGCHANG_DATA_ROOT与数据根约定DATA_PATHS.md— 下载/导入/导出等子目录与resolve_data_path规范