admin/skill-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revert "feat: release ZIP keeps scripts/ tree; JIANGCHANG_SKILLS_ROOT and sibling skills root"

Browse Source 
This reverts commit f973208fe3.
This commit is contained in:
chendelian
2026-04-06 18:45:28 +08:00
parent f973208fe3
commit f11c596bde
2 changed files with 31 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/LOGGING.md
View File

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

12
docs/RUNTIME.md
View File

@@ -34,18 +34,6 @@
编排型技能若需要通过子进程调用兄弟技能，应基于该变量定位脚本，避免写死绝对路径。 编排型技能若需要通过子进程调用兄弟技能，应基于该变量定位脚本，避免写死绝对路径。
### `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 ```text