feat: release ZIP keeps scripts/ tree; JIANGCHANG_SKILLS_ROOT and sibling skills root
All checks were successful
skill-release-placeholder / release (push) Successful in 1s
All checks were successful
skill-release-placeholder / release (push) Successful in 1s
This commit is contained in:
@@ -1,59 +1,76 @@
|
||||
# OpenClaw 技能日志约定（各技能统一）
|
||||
|
||||
本文档为**规范**：新技能与 `account-manager` 等现有技能应遵循同一套路径、格式与环境变量，便于排查与运维。
|
||||
规范目标：同一用户工作区下**一份按日轮转的主日志**，行内带 **技能标识** 与 **trace_id**，便于跨技能排查。
|
||||
|
||||
## 目录与文件
|
||||
|
||||
- 日志目录与技能数据目录同级：
|
||||
- `{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/logs/`
|
||||
- 主日志文件（示例）：
|
||||
- `{...}/account-manager/logs/account-manager.log`
|
||||
- `skill_slug` 与 `SKILL.md` 中 `metadata.openclaw.slug` 一致。
|
||||
- 统一日志目录（与技能数据目录**无关**，不按 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 业务包之前）。
|
||||
|
||||
## 轮转与编码
|
||||
|
||||
- 使用 Python `logging.handlers.TimedRotatingFileHandler`，`when=midnight`，保留约 30 个历史文件（可按技能调整 `backupCount`）。
|
||||
- 文件编码 **UTF-8**。
|
||||
- 首次写日志前创建 `logs/` 目录（`exist_ok=True`）。
|
||||
- `TimedRotatingFileHandler`，`when=midnight`，保留份数默认 30，可用 `JIANGCHANG_LOG_BACKUP_COUNT` 覆盖（1～365）。
|
||||
- 编码 **UTF-8**。
|
||||
- 目录在首次写日志前创建（`exist_ok=True`）。
|
||||
|
||||
## 日志格式（行文本）
|
||||
|
||||
推荐单行格式（与 `account-manager` 一致）：
|
||||
|
||||
```text
|
||||
%(asctime)s | %(levelname)-8s | %(name)s | %(message)s
|
||||
%(asctime)s | %(levelname)-8s | %(trace_id)s | %(skill_slug)s | %(name)s | %(message)s
|
||||
```
|
||||
|
||||
`datefmt` 建议：`%Y-%m-%dT%H:%M:%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 命名
|
||||
|
||||
- 使用分层命名，便于按前缀过滤，例如：`openclaw.skill.account_manager`。
|
||||
- 子进程若需写同一文件，可使用子 logger：`openclaw.skill.account_manager.login_child`，仍追加到**同一日志文件**（`logging.FileHandler(..., encoding='utf-8')` 追加模式）。
|
||||
- 主 logger：`openclaw.skill.<slug_下划线>`（如 `openclaw.skill.content_manager`）
|
||||
- 子进程专用 logger：如 `openclaw.skill.account_manager.login_child`，仍写入**同一**主日志文件（`FileHandler` 追加，格式与主进程一致）
|
||||
|
||||
## 环境变量（全局）
|
||||
## 环境变量
|
||||
|
||||
| 变量 | 说明 |
|
||||
|------|------|
|
||||
| `JIANGCHANG_LOG_LEVEL` | 默认 `INFO`；调试轮询等可设 `DEBUG`。 |
|
||||
| `JIANGCHANG_LOG_TO_STDERR` | 设为 `1`/`true` 时，将 `WARNING` 及以上同时输出到 `stderr`（不替代文件）。 |
|
||||
| `JIANGCHANG_{SKILL}_LOG_FILE` | 可选，覆盖该技能主日志**绝对路径**（需自行保证目录可写）。`account-manager` 使用 `JIANGCHANG_ACCOUNT_MANAGER_LOG_FILE`。 |
|
||||
| `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` | 可选；由运行时注入以串联调用链 |
|
||||
|
||||
## 级别与内容建议
|
||||
## 技能侧接入（最少改动）
|
||||
|
||||
- **INFO**：子命令入口、成功结束（含关键业务 id，避免仅打「成功」）。
|
||||
- **WARNING**：可恢复问题、校验失败、登录未检测到。
|
||||
- **ERROR**：依赖缺失、不可继续的异常。
|
||||
- **DEBUG**：高频轮询状态（URL 列表、规则命中说明）；默认关闭。
|
||||
- 日志中可能含 **手机号、路径等敏感信息**，注意文件权限与留存策略；必要时仅记录后四位或 hash（按合规要求）。
|
||||
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())`。
|
||||
|
||||
## 与标准输出的关系
|
||||
## 级别与敏感信息
|
||||
|
||||
- 面向用户的 `print`（成功提示、`ERROR:` 前缀）可保留；**诊断细节以日志为准**。
|
||||
- 登录失败等场景可在终端提示日志文件路径，便于用户打开 `*.log`。
|
||||
- **INFO**：子命令入口、成功结束（含关键业务 id）。
|
||||
- **WARNING**：可恢复问题、校验失败。
|
||||
- **ERROR**：不可继续的异常。
|
||||
- **DEBUG**：高频细节；默认关闭。
|
||||
- 日志可能含路径、账号信息，注意权限与留存。
|
||||
|
||||
## 参考实现
|
||||
|
||||
- `account-manager/scripts/main.py`：`get_skill_logs_dir`、`get_skill_logger`、`get_skill_log_file_path`、login 子进程内 `FileHandler` 追加同一文件。
|
||||
|
||||
新技能可复制上述函数结构，替换 `SKILL_SLUG` 与 `LOG_LOGGER_NAME` 即可。
|
||||
- `jiangchang-platform-kit/sdk/jiangchang_skill_core/unified_logging.py`
|
||||
- `account-manager` / `content-manager` / `llm-manager` 的 `util/logging_config.py`（re-export）与 CLI 入口
|
||||
|
||||
@@ -34,6 +34,18 @@
|
||||
|
||||
编排型技能若需要通过子进程调用兄弟技能，应基于该变量定位脚本，避免写死绝对路径。
|
||||
|
||||
### `JIANGCHANG_SKILLS_ROOT`（可选）
|
||||
|
||||
与 `CLAW_SKILLS_ROOT` 同义；匠厂桌面宿主可只注入此名。未设置时，技能可从「本技能 `scripts/` 的上一级目录的上一级」推断并列根（OpenClaw 开发仓与 `skills/<slug>/` 解压布局均适用）。
|
||||
|
||||
### `JIANGCHANG_APP_ROOT`（可选）
|
||||
|
||||
匠厂应用安装根。未设置且未设置上述技能根时，Windows 下会尝试用默认 `D:\AI\jiangchang`：若存在子目录 `skills` 且其下像并列技能安装，则技能根为 `{APP}/skills`；否则若 `{APP}` 下直接可见各技能 slug 子目录，则 `{APP}` 即技能根。其他平台默认回退为 `~/.openclaw/skills`。
|
||||
|
||||
### 加密发布包布局
|
||||
|
||||
CI 产物 ZIP 解压后与仓库技能目录结构一致：含 `SKILL.md` 与 **`scripts/`**（PyArmor 输出在 `scripts/` 内）。宿主启动入口应为 **`python scripts/main.py`**（工作目录为技能根）。
|
||||
|
||||
## 本技能推荐的数据目录
|
||||
|
||||
```text
|
||||
|
||||
Reference in New Issue
Block a user