chendelian
f973208fe3
All checks were successful
skill-release-placeholder / release (push) Successful in 1s
77 lines
3.7 KiB
Markdown
77 lines
3.7 KiB
Markdown
# OpenClaw 技能日志约定（各技能统一）
|
||
|
||
规范目标：同一用户工作区下**一份按日轮转的主日志**，行内带 **技能标识** 与 **trace_id**，便于跨技能排查。
|
||
|
||
## 目录与文件
|
||
|
||
- 统一日志目录（与技能数据目录**无关**，不按 skill 分子目录）：
|
||
- `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/logs/`
|
||
- 主日志文件（默认）：
|
||
- `{...}/logs/jiangchang.log`（午夜轮转，历史带日期后缀，由 `TimedRotatingFileHandler` 管理）
|
||
- 覆盖主日志**绝对路径**（可选）：
|
||
- `JIANGCHANG_LOG_FILE`
|
||
|
||
实现源码以 **`jiangchang-platform-kit/sdk/jiangchang_skill_core/unified_logging.py`** 为准；各技能 `scripts/jiangchang_skill_core/unified_logging.py` 为发布用副本，**修改后请同步各技能**。
|
||
|
||
数据根与用户 id 的解析与本地 CLI 注入见同目录 **`runtime_env.py`**（`get_data_root` / `get_user_id` / `apply_cli_local_defaults`）；新技能应在 `main.py` 最早阶段调用 `apply_cli_local_defaults()`（在 import 业务包之前）。
|
||
|
||
## 轮转与编码
|
||
|
||
- `TimedRotatingFileHandler`，`when=midnight`，保留份数默认 30，可用 `JIANGCHANG_LOG_BACKUP_COUNT` 覆盖（1～365）。
|
||
- 编码 **UTF-8**。
|
||
- 目录在首次写日志前创建（`exist_ok=True`）。
|
||
|
||
## 日志格式（行文本）
|
||
|
||
```text
|
||
%(asctime)s | %(levelname)-8s | %(trace_id)s | %(skill_slug)s | %(name)s | %(message)s
|
||
```
|
||
|
||
- `datefmt`：`%Y-%m-%dT%H:%M:%S`（本地时间）
|
||
- `skill_slug`：与 `SKILL.md` 中 `metadata.openclaw.slug` 一致（如 `account-manager`）
|
||
- `name`：分层 logger，如 `openclaw.skill.account_manager`、`openclaw.skill.account_manager.login_child`
|
||
- `trace_id`：调用链 ID，见下节
|
||
|
||
## 调用链（trace）
|
||
|
||
- 环境变量 **`JIANGCHANG_TRACE_ID`**：同一 shell/进程树内子进程默认继承；跨技能 `subprocess` 时父进程应使用 `subprocess_env_with_trace()` 构造 `env`，保证子进程沿用同一 trace。
|
||
- 若未设置，各技能在 `setup_skill_logging` 时会生成 12 位 hex 并写入环境，供后续子进程继承。
|
||
|
||
## Logger 命名
|
||
|
||
- 主 logger：`openclaw.skill.<slug_下划线>`（如 `openclaw.skill.content_manager`）
|
||
- 子进程专用 logger：如 `openclaw.skill.account_manager.login_child`，仍写入**同一**主日志文件（`FileHandler` 追加，格式与主进程一致）
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `JIANGCHANG_DATA_ROOT` | 数据根 |
|
||
| `JIANGCHANG_USER_ID` | 用户/工作区 id，默认 `_anon` |
|
||
| `JIANGCHANG_LOG_LEVEL` | 默认 `INFO` |
|
||
| `JIANGCHANG_LOG_TO_STDERR` | `1`/`true` 时 WARNING+ 同时打 stderr |
|
||
| `JIANGCHANG_LOG_FILE` | 覆盖主日志文件绝对路径 |
|
||
| `JIANGCHANG_LOG_BACKUP_COUNT` | 轮转保留份数，默认 `30` |
|
||
| `JIANGCHANG_TRACE_ID` | 可选；由运行时注入以串联调用链 |
|
||
|
||
## 技能侧接入（最少改动）
|
||
|
||
1. 保证 `scripts/jiangchang_skill_core/` 与平台 kit 中实现保持同步。
|
||
2. `main.py` 将 `scripts` 目录加入 `sys.path`（若尚未加入）。
|
||
3. CLI `main` 早期调用：`setup_skill_logging(SKILL_SLUG, LOG_LOGGER_NAME)`。
|
||
4. 业务代码：`get_skill_logger()` 打日志。
|
||
5. 拉起子技能 CLI 时：`subprocess.run(..., env=subprocess_env_with_trace())`。
|
||
|
||
## 级别与敏感信息
|
||
|
||
- **INFO**：子命令入口、成功结束（含关键业务 id）。
|
||
- **WARNING**：可恢复问题、校验失败。
|
||
- **ERROR**：不可继续的异常。
|
||
- **DEBUG**：高频细节；默认关闭。
|
||
- 日志可能含路径、账号信息，注意权限与留存。
|
||
|
||
## 参考实现
|
||
|
||
- `jiangchang-platform-kit/sdk/jiangchang_skill_core/unified_logging.py`
|
||
- `account-manager` / `content-manager` / `llm-manager` 的 `util/logging_config.py`（re-export）与 CLI 入口
|