会话救援 · Session Rescuer
把一条无法继续的 Codex 线程诊断清楚,并给出能继续的产物。它覆盖两种常见
故障:tool call 没有配对的 tool output,以及切换 provider / 中转站后
Model provider not found。前者可以从磁盘交付物接手或生成可恢复 rollout
副本;后者只同步 state_*.sqlite 的 provider 绑定,不改写 rollout。
Triggers
Activate when
- “修复 codex://threads/… 里报错:No tool output found for tool call …”
- “修复 codex://threads/… 里报错:Model provider
custom not found”
- “切换中转站 / CC Switch 后旧 Codex 线程打不开,需要把 model_provider 统一为当前 provider”
- “这条 Codex 会话继续不了了 / 会话卡死在 systemError / 会话恢复不了”
- “帮我诊断这个 Codex 线程为什么无法继续,怎么救回里面的产物”
- “Fix this stuck Codex session showing 'No tool output found for tool call …'”
- “Sync all Codex thread model_provider values to the current provider name”
- “Diagnose and recover a Codex thread that can no longer be resumed.”
Do not activate when
- 只是要打开、导航到某个 Codex 会话 —— 交给
lov-open-codex-session。
- 只是要检索过去聊过什么 / 上次怎么解决的 —— 交给
lov-search-chat。
- 只修改
config.toml、不处理 thread 元数据 —— 交给 provider manager / CC Switch;
本 Skill 处理的是 thread 与配置已经不一致后的恢复。
- 面向任意软件错误的通用定位与修复 —— 交给
lov-fix-general;本 Skill 只处理
Codex 会话持久化状态与 provider 绑定的特定故障。
- 要把修复后的源发布 / 上架 / 上传 —— 交给
lov-skill-publisher。
User Profile (cross-session)
skill.yaml 声明 user-profile/v1。每次运行开始先读共享的 user、brand、
workspace、preferences 与 skills.lov-fix-codex-session 命名空间。线程 id、
rollout 路径、转录内容、秘密或完整私有路径都不写入持久 Profile;涉及会话的
标识只在当前请求内使用。字段解析优先级:当前请求 → 项目上下文 → Skill 记录
→ 共享偏好 → 共享 user/brand Profile → 安全默认值。
When the user directly states a durable preference or brand fact, persist it
through scripts/profile_store.py and report the saved profile path. Put
Skill-specific values under records.<field>; use brand.<field> or
user.<field> for shared values. Do not persist inferred secrets or credentials.
See references/user-profile.md for the complete contract.
Skill Group Composition
Read references/skill-composition.md before deciding whether to invoke or
extend any adjacent capability. The record distinguishes optional upstream and
downstream handoffs from embedded Kit modules. Do not silently depend on a
sibling Skill that is not shipped with this source.
Workflow (MANDATORY)
You MUST follow these steps in order.
Step 0: Resolve skill root, dependencies, and runtime context
- Use
SKILL_DIR if the environment provides it.
- Otherwise infer the installed skill directory from the current skill context.
- Verify every required local module, reference, script, and asset before work.
- If a required resource is missing, name its expected relative path and stop
before producing a partial result.
When running scripts manually:
export SKILL_DIR="/path/to/lov-fix-codex-session"
context.profile 按上述优先级解析。用户直接说出的、希望跨会话保留的值,用
scripts/profile_store.py record --confirm 原子写回并报告保存路径;推断值、
秘密、token、cookie 与 key 不入库。
Step 1: Understand the requested outcome
- Separate internal context from user-visible output.
- Confirm the input, intended audience, expected deliverable, and evidence gaps.
- Record one real user case before calling the Skill complete. The case must show
the input, the prompt or minimum brief, and the output; do not invent results.
- 先判断故障类型:报错含
Model provider ... not found 时,输入是当前
config.toml / state_*.sqlite;报错含 No tool output found 时,输入是
线程 id / codex:// 链接。输出始终是一份诊断结论 + 可继续的恢复路径;
不要把实现细节作为用户制品。
Step 1.5: Analyze nearby Skills before implementation
- Inspect related local and installed Skills by routing contract and concrete
input/output, not by filename alone.
- Record upstream, core, downstream, overlap, and not-composed decisions in
references/skill-composition.md.
- Keep sibling Skills optional and artifact-based. When stages require hard
coupling for one outcome, create a self-contained Kit instead.
- 本 Skill 是 Codex 会话恢复这一窄领域的核心原子,与通用修复、会话导航、
会话检索是相邻不重叠关系;见
references/skill-composition.md。
Step 2: Execute the workflow
- 故障分诊:错误是
Model provider ... not found 时走 A;否则按
B 处理悬挂 tool call。
- A. 同步 provider 绑定(只读预演):
python3 "$SKILL_DIR/scripts/sync_thread_provider.py" --codex-home "$HOME/.codex" --json
确认 candidate_ids 只包含真正过期的 provider(默认 stale-only,不会
动 built-in 的 openai)。然后退出 Codex Desktop,运行:python3 "$SKILL_DIR/scripts/sync_thread_provider.py" --codex-home "$HOME/.codex" --apply
脚本会先做 SQLite 一致备份再写 threads.model_provider。不要重写
sessions/ 下的 JSONL:paginated 会话的 end_byte_offset 会因此失效。
- B. 解析标识:若错误是悬挂 tool call,从
codex://threads/<uuid>、
线程 id 提取 thread_id;若给的是链接,只取 UUID。
- B. 定位 rollout:优先读
state_5.sqlite 的 threads.rollout_path;拿不到
就在 ~/.codex/sessions 下按线程 id 搜索 rollout-*.jsonl。
- B. 只读诊断:
python3 "$SKILL_DIR/scripts/fix_codex_session.py" "$thread_id" --json
核对报告中的 dangling_calls 与 last_turn_error;poisoned=true 即为毒点。
- 恢复交付物:找出该线程在项目目录里已生成的 Markdown、PDF、图片、代码。
这些是真正值得抢救的产物,先把它们确认下来并回读。
- 给出恢复路径(tool-call 场景二选一,优先第一条):
- 验证:provider 场景回读
threads.model_provider 分布并确认无过期 provider;
tool-call 场景确认修复副本仍是合法 JSONL、dangling_calls 已清空、交付物可打开。
报告具体文件与恢复结论,不要回读被丢弃的私密内容。
Step 3: Validate the deliverable
- Verify completeness, factual support, user-visible copy, and output paths.
- Report concrete files or results, plus any remaining evidence gaps.
- Validate
skill-card.yaml, cases/cases.json, and pricing-card.yaml as the
standard trust bundle for this Skill.
Dependencies
- Python 3.8+(仅标准库;
fix_codex_session.py 与 sync_thread_provider.py
都不需要第三方包)。
- 可读的 Codex 会话目录(默认
~/.codex/sessions);线程 id 用于定位。
- 可读的
config.toml 与 state_*.sqlite;provider 同步只写 SQLite 索引。
- 宿主若提供
read_thread / list_threads 等能力,可用于确认线程当前状态。
- 其他 Skill 均为可选手柄,不是运行前提:
lov-open-codex-session(导航)、
lov-fix-general(通用修复)、lov-search-chat(会话检索)。
1---2name: lov-fix-codex-session3description: >4 诊断并修复无法恢复的 Codex 会话:定位悬挂 tool call/output,并在切换模型5 提供商后处理 Model provider not found 的 provider 绑定,恢复交付物与可继续路径。6license: MIT7compatibility: "Portable Agent Skills format. Python 3.8+ standard library only for the8 diagnostic CLIs; reads ~/.codex rollout JSONL and state_*.sqlite, and can sync9 thread provider metadata. No network or external CLI required."10metadata:11 source: https://skillmd.com/skills/lovstudio/lov-fix-codex-session12 author: skill-publisher13 version: "0.2.0"14 card_standard: lovstudio/skill-card/v115 content_class: deterministic-output16 tags:17 - codex18 - session-repair19 - rollout20 - provider-sync21 - troubleshooting22 - tool-call23---2425# 会话救援 · Session Rescuer2627把一条无法继续的 Codex 线程诊断清楚,并给出能继续的产物。它覆盖两种常见28故障:tool call 没有配对的 tool output,以及切换 provider / 中转站后29`Model provider not found`。前者可以从磁盘交付物接手或生成可恢复 rollout30副本;后者只同步 `state_*.sqlite` 的 provider 绑定,不改写 rollout。3132## Triggers3334### Activate when3536- “修复 codex://threads/… 里报错:No tool output found for tool call …”37- “修复 codex://threads/… 里报错:Model provider `custom` not found”38- “切换中转站 / CC Switch 后旧 Codex 线程打不开,需要把 model_provider 统一为当前 provider”39- “这条 Codex 会话继续不了了 / 会话卡死在 systemError / 会话恢复不了”40- “帮我诊断这个 Codex 线程为什么无法继续,怎么救回里面的产物”41- “Fix this stuck Codex session showing 'No tool output found for tool call …'”42- “Sync all Codex thread model_provider values to the current provider name”43- “Diagnose and recover a Codex thread that can no longer be resumed.”4445### Do not activate when4647- 只是要打开、导航到某个 Codex 会话 —— 交给 `lov-open-codex-session`。48- 只是要检索过去聊过什么 / 上次怎么解决的 —— 交给 `lov-search-chat`。49- 只修改 `config.toml`、不处理 thread 元数据 —— 交给 provider manager / CC Switch;50 本 Skill 处理的是 thread 与配置已经不一致后的恢复。51- 面向任意软件错误的通用定位与修复 —— 交给 `lov-fix-general`;本 Skill 只处理52 Codex 会话持久化状态与 provider 绑定的特定故障。53- 要把修复后的源发布 / 上架 / 上传 —— 交给 `lov-skill-publisher`。5455## User Profile (cross-session)5657`skill.yaml` 声明 `user-profile/v1`。每次运行开始先读共享的 user、brand、58workspace、preferences 与 `skills.lov-fix-codex-session` 命名空间。线程 id、59rollout 路径、转录内容、秘密或完整私有路径都不写入持久 Profile;涉及会话的60标识只在当前请求内使用。字段解析优先级:当前请求 → 项目上下文 → Skill 记录61→ 共享偏好 → 共享 user/brand Profile → 安全默认值。6263When the user directly states a durable preference or brand fact, persist it64through `scripts/profile_store.py` and report the saved profile path. Put65Skill-specific values under `records.<field>`; use `brand.<field>` or66`user.<field>` for shared values. Do not persist inferred secrets or credentials.67See `references/user-profile.md` for the complete contract.6869## Skill Group Composition7071Read `references/skill-composition.md` before deciding whether to invoke or72extend any adjacent capability. The record distinguishes optional upstream and73downstream handoffs from embedded Kit modules. Do not silently depend on a74sibling Skill that is not shipped with this source.7576## Workflow (MANDATORY)7778**You MUST follow these steps in order.**7980### Step 0: Resolve skill root, dependencies, and runtime context8182- Use `SKILL_DIR` if the environment provides it.83- Otherwise infer the installed skill directory from the current skill context.84- Verify every required local module, reference, script, and asset before work.85- If a required resource is missing, name its expected relative path and stop86 before producing a partial result.8788When running scripts manually:8990```bash91export SKILL_DIR="/path/to/lov-fix-codex-session"92```9394`context.profile` 按上述优先级解析。用户直接说出的、希望跨会话保留的值,用95`scripts/profile_store.py record --confirm` 原子写回并报告保存路径;推断值、96秘密、token、cookie 与 key 不入库。9798### Step 1: Understand the requested outcome99100- Separate internal context from user-visible output.101- Confirm the input, intended audience, expected deliverable, and evidence gaps.102- Record one real user case before calling the Skill complete. The case must show103 the input, the prompt or minimum brief, and the output; do not invent results.104- 先判断故障类型:报错含 `Model provider ... not found` 时,输入是当前105 `config.toml` / `state_*.sqlite`;报错含 `No tool output found` 时,输入是106 **线程 id / codex:// 链接**。输出始终是**一份诊断结论 + 可继续的恢复路径**;107 不要把实现细节作为用户制品。108109### Step 1.5: Analyze nearby Skills before implementation110111- Inspect related local and installed Skills by routing contract and concrete112 input/output, not by filename alone.113- Record upstream, core, downstream, overlap, and not-composed decisions in114 `references/skill-composition.md`.115- Keep sibling Skills optional and artifact-based. When stages require hard116 coupling for one outcome, create a self-contained Kit instead.117- 本 Skill 是 Codex 会话恢复这一窄领域的核心原子,与通用修复、会话导航、118 会话检索是相邻不重叠关系;见 `references/skill-composition.md`。119120### Step 2: Execute the workflow1211221. **故障分诊**:错误是 `Model provider ... not found` 时走 `A`;否则按123 `B` 处理悬挂 tool call。1242. **A. 同步 provider 绑定(只读预演)**:125 ```bash126 python3 "$SKILL_DIR/scripts/sync_thread_provider.py" --codex-home "$HOME/.codex" --json127 ```128 确认 `candidate_ids` 只包含真正过期的 provider(默认 `stale-only`,不会129 动 built-in 的 `openai`)。然后退出 Codex Desktop,运行:130 ```bash131 python3 "$SKILL_DIR/scripts/sync_thread_provider.py" --codex-home "$HOME/.codex" --apply132 ```133 脚本会先做 SQLite 一致备份再写 `threads.model_provider`。**不要重写134 `sessions/` 下的 JSONL**:paginated 会话的 `end_byte_offset` 会因此失效。1353. **B. 解析标识**:若错误是悬挂 tool call,从 `codex://threads/<uuid>`、136 线程 id 提取 `thread_id`;若给的是链接,只取 UUID。1374. **B. 定位 rollout**:优先读 `state_5.sqlite` 的 `threads.rollout_path`;拿不到138 就在 `~/.codex/sessions` 下按线程 id 搜索 `rollout-*.jsonl`。1395. **B. 只读诊断**:140 ```bash141 python3 "$SKILL_DIR/scripts/fix_codex_session.py" "$thread_id" --json142 ```143 核对报告中的 `dangling_calls` 与 `last_turn_error`;`poisoned=true` 即为毒点。1446. **恢复交付物**:找出该线程在项目目录里已生成的 Markdown、PDF、图片、代码。145 这些是真正值得抢救的产物,先把它们确认下来并回读。1467. **给出恢复路径**(tool-call 场景二选一,优先第一条):147 - 在已保存交付物的基础上新开一条干净线程,把收尾工作做完(不要继续旧线程)。148 - 若必须沿用同一线程,运行:149 ```bash150 python3 "$SKILL_DIR/scripts/fix_codex_session.py" "$thread_id" --fix151 ```152 生成 `<rollout>.repaired.jsonl`(不覆盖原文件,宿主未运行线程时才用153 `--write`,且会留 `.bak` 备份)。告知用户:部分宿主需重启或重新加载后154 修复才生效。1558. **验证**:provider 场景回读 `threads.model_provider` 分布并确认无过期 provider;156 tool-call 场景确认修复副本仍是合法 JSONL、`dangling_calls` 已清空、交付物可打开。157 报告具体文件与恢复结论,不要回读被丢弃的私密内容。158159### Step 3: Validate the deliverable160161- Verify completeness, factual support, user-visible copy, and output paths.162- Report concrete files or results, plus any remaining evidence gaps.163- Validate `skill-card.yaml`, `cases/cases.json`, and `pricing-card.yaml` as the164 standard trust bundle for this Skill.165166## Dependencies167168- Python 3.8+(仅标准库;`fix_codex_session.py` 与 `sync_thread_provider.py`169 都不需要第三方包)。170- 可读的 Codex 会话目录(默认 `~/.codex/sessions`);线程 id 用于定位。171- 可读的 `config.toml` 与 `state_*.sqlite`;provider 同步只写 SQLite 索引。172- 宿主若提供 `read_thread` / `list_threads` 等能力,可用于确认线程当前状态。173- 其他 Skill 均为可选手柄,不是运行前提:`lov-open-codex-session`(导航)、174 `lov-fix-general`(通用修复)、`lov-search-chat`(会话检索)。