Oil Claude Title

---
name: oil-claude-title
description: 管理 oil-claude-title 插件的会话自动命名：检查后台 Hook、预览或写入当前会话标题、暂停恢复、锁定保护、配置命名模型。当用户要求管理 Claude Code 会话标题、预览新标题、固定标题、暂停/恢复自动命名或检查本插件时使用；不用于文章标题、视频标题、文件重命名，也不在普通对话结束时由主 Agent 主动执行。
metadata:
  compatibility: Claude Code 本地插件专用；需要 Python 3.9+、已登录的 Claude Code CLI（2.1.266 实测）。macOS 已实测；Linux/Windows 未实测。云端会话不支持。
---

# oil-claude-title

管理后台命名流程。主对话只负责用户明确请求的设置与操作；自动命名由独立的 Stop Hook 在后台执行，不向对话注入内容。

## 定位入口

执行本 Skill 内的 `scripts/run.py`。该入口会定位插件根目录并调用共享程序。下面的 `<入口>` 表示该脚本的绝对路径。

会话 ID 不用猜：在 Claude Code 会话内运行 Bash 时环境变量 `CLAUDE_CODE_SESSION_ID` 就是当前会话，程序会自动读取；用户指定其他会话时才显式传 ID。

## 检查与配置

1. 执行 `python3 <入口> doctor`，检查 Python、Claude 可执行文件、插件登记状态；追加 `--session <会话 ID>` 可验证某个会话记录能否读取。
2. 需要换模型时执行 `configure --model <模型别名或 ID>`；`--thinking on|off` 控制是否允许扩展思考（默认 off，更快更省）；`--effort low|medium|high`。模型应来自用户选择，不猜模型名。默认 haiku。
3. 安装方式见插件根目录 `README.md`。只通过官方插件安装入口操作，不手工改 `settings.json`。

`doctor` 里的 `hook.status` 只说明插件是否已登记启用，不能证明 Hook 已经在某次对话里实际触发；实际触发的证据是数据目录 `logs/<会话 ID>.jsonl` 里出现该会话的记录。

## 改名与预览

1. 执行 `python3 <入口> rename`，由独立模型生成当前会话的候选标题（只预览，不写入）。
2. 用户已经明确要求改名时，执行 `python3 <入口> rename --apply`；预览请求停在候选结果。
3. 读取命令结果：`renamed` 表示标题元数据已追加并读回核验；`kept`/`unchanged` 表示保留；它不证明桌面侧边栏已刷新。
4. 向用户返回实际标题和状态，不把候选当作已生效的标题。

`locked` 或 `manual_title` 表示标题受保护。只有用户要求恢复自动命名或覆盖手动标题时，才执行 `unlock` 后重试。

`stale_result` 或 `outdated_event` 表示对话已更新，本次候选已丢弃；用户要立即更新时可重新执行。`ambiguous_title` 表示候选与同目录下已记录的会话重名，本次保留原名，可请用户补充具体对象再试。

Claude 桌面版为每个会话保存自己的标题缓存，并会在新一轮提问时把缓存的标题写回会话记录。因此在桌面会话里：`rename --apply` 返回 `renamed` 后，如果宿主提供了 `set_session_title` 工具，必须紧接着用它把同一个标题设给 `self`；用户反馈侧边栏仍显示旧标题时，先用 `doctor --session` 读回真实标题，再用该工具同步。后台 Hook 没有这条通道：它写入的标题会在下一轮提问时被桌面端写回旧值，插件容忍一次（状态 `host_reverted`），第二次就以「宿主反复写回旧标题」锁定；解决办法是用 `set_session_title` 同步后再 `unlock`。不得宣称后台 Hook 能刷新桌面缓存。

`rename --apply` 会向会话记录文件追加一行标题元数据。auto 权限模式的分类器可能把这类命令当作修改会话记录而拦截；此时告知用户可以改用宿主自带的 `/rename`，或为该脚本添加 Bash 权限规则。

## 暂停与保护

- `pause`：暂停自动命名；正在生成的结果会在写入前再次检查暂停状态。
- `resume`：恢复后续轮次的自动命名。
- `lock [会话 ID]`：固定该会话当前标题。
- `unlock [会话 ID]`：重新允许该会话自动命名。
- `status`：显示配置位置、启用状态和已记录会话数量。

第一次接触会话时，插件无法区分现有标题来自宿主自动生成还是用户手动设置。需永久保留的标题请 `lock`。用户用 `/rename` 手动改名后，插件下次会检测到外部改名并自动锁定。宿主把改名前的旧标题原样写回不算用户改名：第一次只重建基线并继续，第二次才锁定。

## 失败处理

命令失败时保留原标题，先处理 `doctor` 报告的登录、路径或版本问题，再重试。不要让主 Agent 自己生成标题去调用 `/rename` 代替后台流程，不直接编辑会话记录文件，不修改宿主配置。

后台日志仅记录状态、标题和用量，不保留完整对话。日志与配置位于 `status` 返回的数据目录；诊断时只读取相关会话的记录。