# 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 入口