oclaw/docs/runtime-skill-troubleshooting.md

# oclaw Skill 排障手册

本文用于排查 oclaw skill 在安装、暴露、执行、记忆回写四个阶段的问题。

## 1) 安装接口返回字段

`/admin/api/skills/install*`、`/admin/api/skills/auto-install`、`/admin/api/skills/retry-install` 统一返回：

- `ok`: 是否成功
- `result.detail`: 原始细节文本
- `result.error_code`: 归一化错误码
- `result.retryable`: 是否建议重试

## 2) 常见 `error_code` 与处理建议

| `error_code` | 含义 | `retryable` | 建议 |
| --- | --- | --- | --- |
| `ok` | 安装/创建成功 | `false` | 无 |
| `transport_or_extract_error` | 下载失败或解压异常 | `true` | 检查网络、URL、压缩包完整性后重试 |
| `invalid_archive` | 压缩包不合法（空包/过大/类型不支持） | `false` | 修正包格式或来源 |
| `invalid_skill_package` | 缺 `SKILL.md` 或包含不安全路径/文件 | `false` | 修正技能包结构和内容 |
| `already_exists` | 目标技能目录已存在 | `false` | 使用 overwrite 或换名 |
| `runtime_error` | 自动安装中途异常并已回滚 | `true` | 看 detail 定位异常后重试 |
| `unknown` | 未归类错误 | `false` | 结合 detail 和 trace 排查 |

## 3) 按 `trace_id` 排障路径

推荐按下列顺序查询同一个 `trace_id`：

1. `oclaw_gateway`
   - `skill_manifest`
   - `router_decision`
2. `oclaw_agent_core`
   - `run_started`
   - `attempt_started`
3. `oclaw_direct_loop`
   - `tool_wire_filter`
   - `tool_result_context_guard`
4. `oclaw_skill_executor`
   - `skill_selected`
   - `skill_executed`
5. `oclaw_agent_core`
   - `after_turn_memory`
   - `attempt_finished`
   - `run_finished`

可快速判断问题落在哪一段：安装未生效、工具未暴露、工具执行失败、结果被截断、记忆未写入。

## 4) 快速检查项

- `AIA_SKILL_RUNTIME_ENABLED` 是否开启
- `AIA_SKILLS_PROMPT_IN_SYSTEM` 是否开启
- `AIA_SKILL_DISABLED_NAMES` 是否误禁用了目标 skill
- `AIA_SKILL_AUTO_INSTALL_ENABLED` 是否关闭
- 目标 skill 的 `SKILL.md` 是否包含合法 frontmatter（尤其 `metadata.oclaw.install`）

## 5) 典型故障定位

- **症状：skill 在 prompt 中看不到**
  - 查 `skill_manifest.skills_total` 与 `hidden_total`
  - 查 `AIA_SKILL_DISABLED_NAMES`
  - 查 wire policy 是否过滤（`tool_wire_filter.hidden_*`）

- **症状：skill 可见但执行失败**
  - 查 `skill_executed.ok=false` 与 `error_code`
  - 查 `attempt_finished.error_code` 是否被归类为可重试错误

- **症状：有回复但记忆未入库**
  - 查 `after_turn_memory`
  - 若无该事件，先看 attempt 是否成功
  - 若有该事件仍无记录，检查记忆写入阈值与 writer 配置

## 6) Admin 接口字段对照（速查）

以下接口都返回统一结构：`{ ok, result: { detail, error_code, retryable } }`。

| 接口 | 用途 | 常见请求字段 | 关键返回字段 |
| --- | --- | --- | --- |
| `POST /admin/api/skills/install` | 从本地目录安装 | `source_dir`, `overwrite` | `result.error_code`, `result.retryable` |
| `POST /admin/api/skills/install-registry` | 从 registry 压缩包安装 | `archive_url`, `overwrite` | `result.error_code`, `result.retryable` |
| `POST /admin/api/skills/auto-install` | 依据描述自动安装 | `name`, `description` | `result.error_code`, `result.retryable` |
| `POST /admin/api/skills/retry-install` | 对失败记录重试安装 | `install_id` | `result.error_code`, `result.retryable` |

排障时建议优先读取：

- `result.error_code`：确定是否是包格式、下载链路、运行时异常
- `result.retryable`：决定是否直接重试，还是先改包/改配置
- `result.detail`：补充上下文（具体 URL、异常片段、回滚原因）

## 7) 值班排障最短路径

1. 在 Admin 安装结果中先看 `result.error_code` 与 `result.retryable`
2. 按 `trace_id` 检索 `skill_manifest -> skill_executed -> after_turn_memory`
3. 若 `retryable=true`，修复网络/瞬时问题后执行 `/retry-install`
4. 若 `retryable=false`，优先修正技能包内容或运行时开关再重试

## 8) Relay 文件指针排障（新增）

当技能/专家输出文件引用时，优先检查：

- 入站消息 `attachments[]` 是否包含 `type=relay_pointer` 与 `pointer_uri`
- `metadata.relay_share_envelope.attachments.pointers[]` 是否存在且数量匹配
- `gateway_received` trace 中：
  - `relay_pointer_count`
  - `relay_envelope_present`
  - `relay_envelope_pointer_count`

常见问题：

- **有附件但 pointer 计数为 0**
  - 附件对象缺少 `pointer_uri`，或字段名不符合协议
- **envelope 存在但 pointer 数量为 0**
  - `relay_share_envelope.attachments.pointers` 结构错误（非数组/元素非对象）
- **LLM 无法使用共享文件**
  - 确认消息构建阶段将 pointer 作为文本元信息注入，而不是直接传大文件内容

- **ACP 子任务立即失败（无模型执行）**
  - 常见 `error_code`：`relay_envelope_invalid`、`relay_envelope_unsupported_version`
  - 语义：输入契约错误，固定 `retryable=false`，应先修 payload 再重试