chore: sync from OpenClaw workspace (2026-04-05 09:17)

docs/LOGGING.md

@@ -0,0 +1,59 @@
+# OpenClaw 技能日志约定（各技能统一）
+
+本文档为**规范**：新技能与 `account-manager` 等现有技能应遵循同一套路径、格式与环境变量，便于排查与运维。
+
+## 目录与文件
+
+- 日志目录与技能数据目录同级：
+  - `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/logs/`
+- 主日志文件（示例）：
+  - `{...}/account-manager/logs/account-manager.log`
+- `skill_slug` 与 `SKILL.md` 中 `metadata.openclaw.slug` 一致。
+
+## 轮转与编码
+
+- 使用 Python `logging.handlers.TimedRotatingFileHandler`，`when=midnight`，保留约 30 个历史文件（可按技能调整 `backupCount`）。
+- 文件编码 **UTF-8**。
+- 首次写日志前创建 `logs/` 目录（`exist_ok=True`）。
+
+## 日志格式（行文本）
+
+推荐单行格式（与 `account-manager` 一致）：
+
+```text
+%(asctime)s | %(levelname)-8s | %(name)s | %(message)s
+```
+
+`datefmt` 建议：`%Y-%m-%dT%H:%M:%S`（本地时间）。
+
+## Logger 命名
+
+- 使用分层命名，便于按前缀过滤，例如：`openclaw.skill.account_manager`。
+- 子进程若需写同一文件，可使用子 logger：`openclaw.skill.account_manager.login_child`，仍追加到**同一日志文件**（`logging.FileHandler(..., encoding='utf-8')` 追加模式）。
+
+## 环境变量（全局）
+
+| 变量 | 说明 |
+|------|------|
+| `JIANGCHANG_LOG_LEVEL` | 默认 `INFO`；调试轮询等可设 `DEBUG`。 |
+| `JIANGCHANG_LOG_TO_STDERR` | 设为 `1`/`true` 时，将 `WARNING` 及以上同时输出到 `stderr`（不替代文件）。 |
+| `JIANGCHANG_{SKILL}_LOG_FILE` | 可选，覆盖该技能主日志**绝对路径**（需自行保证目录可写）。`account-manager` 使用 `JIANGCHANG_ACCOUNT_MANAGER_LOG_FILE`。 |
+
+## 级别与内容建议
+
+- **INFO**：子命令入口、成功结束（含关键业务 id，避免仅打「成功」）。
+- **WARNING**：可恢复问题、校验失败、登录未检测到。
+- **ERROR**：依赖缺失、不可继续的异常。
+- **DEBUG**：高频轮询状态（URL 列表、规则命中说明）；默认关闭。
+- 日志中可能含 **手机号、路径等敏感信息**，注意文件权限与留存策略；必要时仅记录后四位或 hash（按合规要求）。
+
+## 与标准输出的关系
+
+- 面向用户的 `print`（成功提示、`ERROR:` 前缀）可保留；**诊断细节以日志为准**。
+- 登录失败等场景可在终端提示日志文件路径，便于用户打开 `*.log`。
+
+## 参考实现
+
+- `account-manager/scripts/main.py`：`get_skill_logs_dir`、`get_skill_logger`、`get_skill_log_file_path`、login 子进程内 `FileHandler` 追加同一文件。
+
+新技能可复制上述函数结构，替换 `SKILL_SLUG` 与 `LOG_LOGGER_NAME` 即可。