docs: update SCHEMA.md / ERRORS.md / PLATFORMS.md / RUNTIME.md for v2

Co-authored-by: Cursor <cursoragent@cursor.com>

references/RUNTIME.md

@@ -2,58 +2,80 @@
 
 ## 数据落盘位置
 
-`get_data_root()` / `get_user_id()` 来自 **`scripts/jiangchang_skill_core/runtime_env.py`**；`scripts/util/runtime_paths.py` 在此基础上拼技能子目录。
+`get_data_root()` / `get_user_id()` 来自 **`scripts/jiangchang_skill_core/runtime_env.py`**（兼容 **`JIANGCHANG_*` / `CLAW_*` 别名**）；`scripts/util/runtime_paths.py` 在此基础上拼接技能子目录。
 
-- **数据根目录**：优先 **`JIANGCHANG_DATA_ROOT`**；未设置且未走本地注入时，Windows 默认 `D:\jiangchang-data`，其它系统 `~/.jiangchang-data`。
-- **用户/工作空间 id**：优先 **`JIANGCHANG_USER_ID`**；未设置时为 **`_anon`**。
+- **数据根目录**：默认读取宿主注入变量；开发模式下未注入时可能落到 Windows `D:\jiangchang-data` 等（详见 runtime_env 实现）。
+- **用户 / 工作空间 id**：默认 `_anon`（以实际注入为准）。
 - **技能数据目录**：`{数据根}/{用户id}/account-manager/`
   - **SQLite**：`account-manager.db`
+  - **Master Key**：`master.key`（仅当执行过 `account init-master-key` 且未仅用环境变量场景）
   - **Profile**：`profiles/{domain}/{platform_key}/{safe_label}[_{login_id_suffix}]/`
   - **日志**：与其它技能共用 `{数据根}/{用户id}/logs/jiangchang.log`
 
 ## 调试：为什么「list 没数据」
 
-- 若终端与网关注入的 `JIANGCHANG_*` 不一致，会写到**不同用户目录**。
-- 设置 **`JIANGCHANG_ACCOUNT_DEBUG_PATHS=1`** 后，每次 CLI 命令前在 **stderr** 打印实际路径。
+- 若终端与网关注入的数据根 / 用户 id 不一致，会写到**不同目录**。
+- 设置 **`JIANGCHANG_ACCOUNT_DEBUG_PATHS=1`**（或宿主等价开关）后，CLI 会在 **stderr** 打印实际路径。
 
 ## 本地 CLI 默认值
 
 各技能 `main.py` 调用 `apply_cli_local_defaults()`：
+
 - `CLI_LOCAL_DEV_ENABLED = True` 时，未设置环境变量则注入平台默认值。
 - 发版前改为 `False` 或依赖宿主注入。
 
 ## Secret 存储
 
 | 方式 | 说明 | 适用场景 |
-|------|------|----------|
+|---|---|---|
 | `none` | 不存 secret | 浏览器 profile 登录态 |
-| `env` | SQLite 只存环境变量名，运行时从 `os.environ` 读取 | 轻量测试 |
-| `windows_credential` | 真实 secret 存 Windows Credential Manager | Windows 本地正式部署 |
+| `env` | SQLite 存变量名，运行时从 `os.environ` 读取 | 轻量测试 |
+| `windows_credential` | secret 存 Windows Credential Manager | Windows 本地部署 |
+| `local_encrypted` | Fernet 密文存 SQLite（`secret_ciphertext`），密钥来自 master key | RPA 密码落地；需先 `account init-master-key` |
 
-- **不把 secret 明文写入 SQLite**
-- **不在日志中记录 secret 明文**
-- 只有 `credential pick --reveal` 或 `credential resolve --reveal` 才返回 secret
+- **禁止**把明文写入日志。
+- `credential pick --reveal` / `credential resolve --reveal` 仍会输出明文 secret——仅限受控环境。
+
+## Master Key
+
+| 变量 | 作用 |
+|---|---|
+| `ACCOUNT_MANAGER_MASTER_KEY` | Fernet key（典型为 url-safe Base64 **44** 字符）；**优先级高于** `master.key` 文件 |
+
+**加载优先级（解密路径）**：环境变量 → `master.key` 文件 → `ERR_MASTER_KEY_MISSING`。
+
+**安全建议**
+
+- 生产环境优先 **环境变量 / Secret Manager** 注入，不在磁盘留 `master.key`。
+- 桌面环境可使用文件（默认尽力写入私有权限）。
+- 备份 master key 至密码管理器；**丢失将导致所有 `local_encrypted` 凭据不可解密**。
+
+详见 [`CLI.md`](CLI.md)（`init-master-key`）、[`ERRORS.md`](ERRORS.md)。
 
 ## 日志
 
 | 变量 | 作用 |
-|------|------|
+|---|---|
 | `JIANGCHANG_LOG_LEVEL` | 日志级别，默认 `INFO` |
 | `JIANGCHANG_LOG_TO_STDERR` | 设为 `1`/`true` 等时，WARNING 及以上同步 stderr |
 | `JIANGCHANG_LOG_FILE` | 覆盖主日志文件绝对路径 |
 | `JIANGCHANG_LOG_BACKUP_COUNT` | 轮转保留份数，默认 `30` |
 | `JIANGCHANG_TRACE_ID` | 可选；跨技能子进程由父进程注入 |
 
-## 浏览器（open）
+## 浏览器（`account open` / rpa_helpers）
 
-- 本机已安装 Chrome 或 Edge
-- Python 环境需 `playwright` 包（匠厂共享 runtime 已包含）
-- 使用 **channel 模式**（`channel=chrome|msedge`），**不下载 Chromium**
-- **不要执行 `playwright install chromium`**
+- 本机需安装 Chrome 或 Edge。
+- Python 侧依赖 **`playwright`**（匠厂共享 runtime 已内置）。
+- 使用 **channel 模式**（`chrome` / `msedge`），**不下载 Chromium**。
+- **不要执行** `playwright install chromium`。
 
-### 关键浏览器参数
+### 关键浏览器参数（摘录）
 
 - `headless=False`
 - `no_viewport=True`
 - `args` 包含 `--start-maximized`
-- stealth 模式可选（`OPENCLAW_PLAYWRIGHT_STEALTH` 环境变量控制）
+- stealth 是否启用由 `OPENCLAW_PLAYWRIGHT_STEALTH` 控制（见 `launch_browser_with_profile`）
+
+### rpa_helpers
+
+登录编排封装见 [`RPA_HELPERS.md`](RPA_HELPERS.md)。