60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# 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` 即可。
|