Release v1.0.56: Credential & Browser Profile Manager

references/RUNTIME.md

@@ -1,48 +1,59 @@
 # 运行环境与数据路径（account-manager）
 
-## 数据落盘位置（当前实现）
+## 数据落盘位置
 
-`get_data_root()` / `get_user_id()` 来自 **`scripts/jiangchang_skill_core/runtime_env.py`**（与 `jiangchang-platform-kit` 同源）；`scripts/util/runtime_paths.py` 在此基础上拼技能子目录。
+`get_data_root()` / `get_user_id()` 来自 **`scripts/jiangchang_skill_core/runtime_env.py`**；`scripts/util/runtime_paths.py` 在此基础上拼技能子目录。
 
 - **数据根目录**：优先 **`JIANGCHANG_DATA_ROOT`**；未设置且未走本地注入时，Windows 默认 `D:\jiangchang-data`，其它系统 `~/.jiangchang-data`。
-- **用户/工作空间 id**：优先 **`JIANGCHANG_USER_ID`**；未设置且未走本地注入时为 **`_anon`**。
+- **用户/工作空间 id**：优先 **`JIANGCHANG_USER_ID`**；未设置时为 **`_anon`**。
 - **技能数据目录**：`{数据根}/{用户id}/account-manager/`
   - **SQLite**：`account-manager.db`
-  - **Profile**：`profiles/<平台展示名>/<手机号>/`（由 `get_default_profile_dir` 生成）
-  - **日志**：与其它技能共用**用户级**目录 `{数据根}/{用户id}/logs/jiangchang.log`（按日轮转）
+  - **Profile**：`profiles/{domain}/{platform_key}/{safe_label}[_{login_id_suffix}]/`
+  - **日志**：与其它技能共用 `{数据根}/{用户id}/logs/jiangchang.log`
 
 ## 调试：为什么「list 没数据」
 
-- 若终端与网关注入的 `JIANGCHANG_*` 不一致，会写到**不同用户目录**，库文件不是同一份。
-- 设置 **`JIANGCHANG_ACCOUNT_DEBUG_PATHS=1`**（`1`/`true`/`yes`/`on`）后，每次 CLI 子命令前会在 **stderr** 打印实际根目录、用户 id 与数据库路径（`_maybe_print_paths_debug_cli`）。
+- 若终端与网关注入的 `JIANGCHANG_*` 不一致，会写到**不同用户目录**。
+- 设置 **`JIANGCHANG_ACCOUNT_DEBUG_PATHS=1`** 后，每次 CLI 命令前在 **stderr** 打印实际路径。
 
-## 本地 CLI 默认值（`runtime_env`）
+## 本地 CLI 默认值
 
-各技能 **`main.py`** 在 `sys.path` 就绪后、import 业务包之前调用 **`apply_cli_local_defaults()`**（实现见 `jiangchang_skill_core.runtime_env`）：
+各技能 `main.py` 调用 `apply_cli_local_defaults()`：
+- `CLI_LOCAL_DEV_ENABLED = True` 时，未设置环境变量则注入平台默认值。
+- 发版前改为 `False` 或依赖宿主注入。
 
-- 代码内 **`CLI_LOCAL_DEV_ENABLED = True`** 时，若当前未设置 `JIANGCHANG_DATA_ROOT` / `JIANGCHANG_USER_ID`，会注入平台默认数据根与 **`DEFAULT_LOCAL_USER_ID`**（与 kit 中常量一致）。
-- 代码内为 **`False`** 时，可设环境变量 **`JIANGCHANG_CLI_LOCAL_DEV=1`** 达到同样效果。
-- **发版/嵌入宿主前**：将各技能 vendored 的 `runtime_env.py` 中 `CLI_LOCAL_DEV_ENABLED` 改为 **`False`**，或完全依赖宿主注入。
+## Secret 存储
+
+| 方式 | 说明 | 适用场景 |
+|------|------|----------|
+| `none` | 不存 secret | 浏览器 profile 登录态 |
+| `env` | SQLite 只存环境变量名，运行时从 `os.environ` 读取 | 轻量测试 |
+| `windows_credential` | 真实 secret 存 Windows Credential Manager | Windows 本地正式部署 |
+
+- **不把 secret 明文写入 SQLite**
+- **不在日志中记录 secret 明文**
+- 只有 `credential pick --reveal` 或 `credential resolve --reveal` 才返回 secret
 
 ## 日志
 
-实现见 `scripts/jiangchang_skill_core/unified_logging.py`，`util/logging_config.py` 仅 re-export。
-
 | 变量 | 作用 |
 |------|------|
 | `JIANGCHANG_LOG_LEVEL` | 日志级别，默认 `INFO` |
 | `JIANGCHANG_LOG_TO_STDERR` | 设为 `1`/`true` 等时，WARNING 及以上同步 stderr |
-| `JIANGCHANG_LOG_FILE` | 覆盖主日志文件绝对路径（默认 `{数据根}/{用户id}/logs/jiangchang.log`） |
+| `JIANGCHANG_LOG_FILE` | 覆盖主日志文件绝对路径 |
 | `JIANGCHANG_LOG_BACKUP_COUNT` | 轮转保留份数，默认 `30` |
-| `JIANGCHANG_TRACE_ID` | 可选；跨技能子进程由父进程注入以串联同一调用链 |
+| `JIANGCHANG_TRACE_ID` | 可选；跨技能子进程由父进程注入 |
 
 ## 浏览器（open）
 
-`open` 由 `service/browser_service.py` 与子进程 `service/open_child_runner.py` 启动持久化上下文，仅用于人工查看；**不做**登录态 DOM 检测。
+- 本机已安装 Chrome 或 Edge
+- Python 环境需 `playwright` 包（匠厂共享 runtime 已包含）
+- 使用 **channel 模式**（`channel=chrome|msedge`），**不下载 Chromium**
+- **不要执行 `playwright install chromium`**
 
-依赖：**本机已安装 Chrome 或 Edge**；Python 环境需 **`playwright` 包**（匠厂共享 `python-runtime` 已包含）。运行时使用 **Playwright `channel=chrome|msedge`** 调系统浏览器，**不要**执行 `playwright install chromium`（避免下载自带 Chromium）。
+### 关键浏览器参数
 
-## 常见问题（简要）
-
-- **`ERROR:需要 playwright Python 包`**：确认共享 venv 已 `uv sync`；本机安装 Chrome 或 Edge。
-- **`ERROR:PROFILE_DIR_MISSING`**：库中该账号 `profile_dir` 为空，需检查数据或重新添加账号流程。
+- `headless=False`
+- `no_viewport=True`
+- `args` 包含 `--start-maximized`
+- stealth 模式可选（`OPENCLAW_PLAYWRIGHT_STEALTH` 环境变量控制）