Release v1.0.60: harden business logging policies (LOGGING-006/007/008)

development/LOGGING.md

@@ -1,6 +1,26 @@
 # 日志规范
 
-本文件是 skill 日志规范的**权威入口**，面向技术人员与 AI 编程代理。涉及长任务、RPA、外部系统对接的技能，**必须**在实现前通读本文，并在 code review 时对照「必打日志节点清单」人工检查。
+本文件是 skill 日志规范的**权威入口**，面向技术人员与 AI 编程代理。涉及长任务、RPA、外部系统对接的技能，**必须**在实现前通读本文。
+
+自动 hard policy（`POLICY-LOGGING-001`～`008`）只保证底线；阶段是否够细仍须对照本文事件词表做 review。复制技能后可用 [`tests/samples/test_logging_contract.py.sample`](../tests/samples/test_logging_contract.py.sample) 做契约断言。
+
+---
+
+## 0. 验收铁律（先读）
+
+| 通道 | 给谁看 | 能否单独当排障依据 |
+|------|--------|-------------------|
+| 统一文件日志 `jiangchang.log` | 运维 / 离线打包 | **必须能单独定位到失败阶段与 error_code** |
+| Activity / 任务中心 `emit` | 用户进度 | **不能**替代文件日志 |
+| `print` / stdout | CLI 一眼结果 | **禁止**作为唯一失败记录 |
+| `task_logs` | 终态审计 | 摘要层；**不能**替代逐步 trace |
+
+硬规定：
+
+1. **没有关键节点文件日志 = 客户现场不可排障。**
+2. **`emit` ≠ 文件日志**：任务中心有进度，而 `jiangchang.log` 只有 `cli_start`，视为交付不合格。
+3. **失败出口必须先写文件日志，再 `print` / `finish`**：凡 `print(...ERROR:...)`、`finish(status=failed|partial)`、队列 `mark_failed`，同一出口须有 `log.warning` / `log.exception`（含 `error_code=` 或 `task_failed`）。
+4. **域模块也要打点**：`scripts/service/<domain>/`、`*_flow.py`、`*_driver.py` 等业务文件不得零日志（见 `POLICY-LOGGING-006`）。
 
 ---
 
@@ -24,8 +44,6 @@ OpenClaw 技能常在客户电脑上异步执行，且大量依赖 RPA、浏览
 | 重试与人工介入 | 第几次重试、是否等待验证码 / U 盾 |
 | 存证路径 | 截图、录屏、`video_log`、失败 artifacts |
 
-**没有关键节点日志 = 客户现场不可排障。** 不要把 `print` 当作日志；stdout 面向用户与 Agent，文件日志与 Run Journal 面向运维。
-
 ---
 
 ## 2. 日志分层
@@ -130,36 +148,73 @@ Journal 会写入 `type: lifecycle` 事件（`paused` / `resumed` / `stopping`
 
 ---
 
-## 3. 必打日志节点清单
+## 3. 固定事件词表（生产代码须出现）
 
-以下节点应在**生产代码**中有对应 `log.info` / `log.warning` / `log.exception`（或 Activity / RPA step）。复制模板后按业务增删，但**不可整体省略**。
+日志消息推荐 **key=value**。下列**事件名字符串**须出现在 `log.info` / `log.warning` / `log.exception` 的消息中（可用 f-string / `%s`，但事件名本身须可 grep）。
 
-| 阶段 | 建议日志 / emit |
-|------|-----------------|
-| CLI 入口启动 | `cli_start`（`cli/app.py`，已由模板提供） |
-| 参数解析完成 | `run_args target_id=... input_id=...` |
-| 鉴权开始 | `entitlement_check_start` |
-| 鉴权成功 | `entitlement_ok` |
-| 鉴权失败 | `entitlement_failed`（`warning`） |
-| 任务开始 | `task_start task_type=... target_id=... input_id=... batch_id=...` + `emit("开始处理任务")` |
-| adapter / test target 选择 | `adapter_selected adapter=... system=...` |
-| 账号 / profile / lease 获取 | `account_acquired account_id=...` |
-| 账号 / lease 释放 | `account_released account_id=...` |
-| 外部 API 开始 | `external_call_start system=... operation=...` |
-| 外部 API 结束 | `external_call_done system=... operation=... elapsed_ms=... status=...` |
-| 兄弟技能调用开始 / 结束 | 同上，或 `sibling_call_start/done skill_slug=...` |
-| RPA 操作开始 / 结束 | `rpa_start` / `rpa_done` + `video.add_step` 中文步骤 |
-| 打开页面 | step：「打开 xxx 页面」 |
-| 检查登录 | step + log |
-| 定位输入框 / 点击提交 | step + log |
-| 等待结果 | step + log（含 timeout 预期） |
-| 批量循环 | `batch_progress current=... total=...` |
-| 重试 | `retry_attempt n=... reason=...`（`warning`） |
-| 跳过 / 部分失败 | `skipped` / `partial_failure`（`warning`） |
-| 人工介入 | `human_intervention type=captcha|login|ukey|otp`（`warning`） |
-| 失败截图 / 视频 | `artifact_saved artifact_path=...` / `video_path=...` |
-| 任务成功 | `task_success ...` + `task_log_saved status=success` |
-| 任务失败 | `task_failed ...`（`exception` 保留 traceback）+ `task_log_saved status=failed` |
+### 3.1 长任务通用最低集（所有业务 skill）
+
+| 事件名 | 级别 | 说明 |
+|--------|------|------|
+| `cli_start` | info | CLI 入口（模板已提供） |
+| `task_start` | info | 主任务开始（含 `task_type=`） |
+| `entitlement_ok` / `entitlement_failed` | info / warning | 鉴权结果 |
+| `item_start` / `item_done` | info | 批量逐条时；单条可用 `task_start`/`task_success` 代替 |
+| `task_success` 或 `task_failed` | info / warning\|exception | 终态；失败须含 `error_code=` |
+| `task_log_saved` | info | 写入 `task_logs` 后 |
+
+### 3.2 RPA / 桌面 / 浏览器额外最低集
+
+当 `scripts/service/` 使用 `RpaVideoSession` / `uiautomation` / `playwright` / `@rpa_step` 时，额外要求：
+
+| 事件名 | 说明 |
+|--------|------|
+| `rpa_start` / `rpa_done` 或 `rpa_failed` | RPA 段起止（可与 `task_*` 同条合并，但事件名须可 grep） |
+| `stage=` | 至少 3 个不同阶段里程碑（如 `open_window` / `locate_control` / `submit` / `wait_result`） |
+| `risk_blocked` | 若有配额/工作时段/熔断等前置拦截 |
+
+**不要**要求每个 Click 一行日志；要求的是**阶段里程碑 + 全部失败出口**。
+
+### 3.3 其它常见节点（按业务选用）
+
+| 阶段 | 建议事件 |
+|------|----------|
+| adapter 选择 | `adapter_selected adapter=...` |
+| 账号 / lease | `account_acquired` / `account_released` |
+| 外部 API | `external_call_start` / `external_call_done`（含 `elapsed_ms=` / `status=`） |
+| 兄弟技能 | `sibling_call_start` / `sibling_call_done` |
+| 重试 / 跳过 / 人工 | `retry_attempt` / `skipped` / `human_intervention` |
+| 存证 | `artifact_saved` / `video_path=` |
+
+### 3.4 最低可验收日志串（示例）
+
+mock 或真实跑完一条主路径后，`jiangchang.log`（或宿主「运行日志」）应能 grep 到类似：
+
+```text
+cli_start argv=...
+task_start task_type=add-one target_id=...
+entitlement_ok task_type=add-one
+rpa_start stage=open_window
+rpa_start stage=locate_control
+rpa_start stage=submit
+task_failed error_code=ELEMENT_NOT_FOUND ...
+task_log_saved status=failed
+```
+
+成功路径则出现 `task_success` 而非 `task_failed`。若只有 `cli_start` → **不合格**。
+
+---
+
+## 3.5 必打节点与 Activity 对照
+
+以下节点除文件日志外，长任务仍应 `emit` / `video.add_step`（用户可见），但**不能只 emit 不打文件日志**。
+
+| 阶段 | 文件日志 | Activity |
+|------|----------|----------|
+| 任务开始 | `task_start` | `emit("开始…")` |
+| RPA 步骤 | `stage=...` | `add_step` / `@rpa_step` |
+| 批量进度 | `item_start` / `batch_progress` | `emit(..., progress=)` |
+| 失败 | `task_failed error_code=` | `finish(failed\|partial)` |
 
 ---