feat(skills): 新增 codex-session-reader skill

[DCjanus]

Why

• 需要一个仅面向 Codex 的只读 session/thread 阅读 skill，便于在已知 thread id 时直接查看会话内容。
• 通过 codex app-server 官方接口读取数据，可以避免耦合底层本地存储格式，并降低后续维护成本。

What

• 新增 codex-session-reader skill，提供 read 子命令，通过 codex app-server 读取单个 Codex thread。
• 支持 --preview-only 与 0-based、接近 Python 切片语法的 --turns 参数，用于控制输出范围。
• 更新根目录 README.md 的 skills 表格，补充 codex-session-reader 与遗漏的 coderabbit-cli 条目。

Testing

• uvx ruff check skills/codex-session-reader/scripts/codex_session_reader.py
• ./skills/codex-session-reader/scripts/codex_session_reader.py --help
• ./skills/codex-session-reader/scripts/codex_session_reader.py read --help
• ./skills/codex-session-reader/scripts/codex_session_reader.py read <thread-id> --preview-only
• ./skills/codex-session-reader/scripts/codex_session_reader.py read <thread-id> --turns :5
• ./skills/codex-session-reader/scripts/codex_session_reader.py read <thread-id> --turns -5:
• ./skills/codex-session-reader/scripts/codex_session_reader.py read <thread-id> --turns 10:-1
• ./skills/codex-session-reader/scripts/codex_session_reader.py read <thread-id> --turns 13
• ./skills/codex-session-reader/scripts/codex_session_reader.py read <thread-id> --turns 1:10:2（确认报错）

[coderabbitai]

Important

Review skipped

This PR was authored by the user configured for CodeRabbit reviews. CodeRabbit does not review PRs authored by this user. It's recommended to use a dedicated user account to post CodeRabbit review feedback.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 78c10dad-5107-44f5-8ad2-71ea93906815

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new read-only "codex-session-reader" skill: documentation (README and SKILL.md) and a Python CLI that uses a synchronous JSON‑RPC client to fetch and render a single Codex thread via a codex app-server, with turn-slicing, validation, and Typer/Rich CLI entrypoints.

Changes

Cohort / File(s)	Summary
Top-level README README.md	Added two new skill entries: coderabbit-cli and codex-session-reader.
Skill README skills/codex-session-reader/README.md	New README describing purpose, scope, API usage (thread/list, thread/read), architecture notes, and file layout.
Skill Documentation skills/codex-session-reader/SKILL.md	New SKILL.md covering CLI usage, turn-slice syntax, output formats (markdown/json), examples, and error behavior.
CLI Implementation skills/codex-session-reader/scripts/codex_session_reader.py	New CLI implementation: Pydantic models and types, CodexAppServerClient JSON‑RPC lifecycle, thread_id validation, turn-slice parsing/selection, markdown/JSON rendering, Typer entrypoints, subprocess/stderr management, and custom domain error class.

Sequence Diagram

sequenceDiagram
    participant User as CLI User
    participant CLI as codex_session_reader.py
    participant Client as CodexAppServerClient
    participant Server as Codex App Server

    User->>CLI: invoke read_thread_command(thread_id, opts)
    CLI->>CLI: validate_thread_id()
    CLI->>Client: start codex app-server / __enter__()
    Client->>Server: initialize (JSON-RPC)
    Server-->>Client: initialize response
    CLI->>Client: request thread/read (JSON-RPC)
    Server-->>Client: thread/read response
    Client-->>CLI: ThreadReadResponse
    CLI->>CLI: select_turns_by_expr()
    CLI->>CLI: render_thread_markdown() or serialize JSON
    CLI->>User: emit_output (stdout)
    CLI->>Client: __exit__() / cleanup

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• feat(skills): 新增 CodeRabbit CLI skill #28 — Adds skills/coderabbit-cli/SKILL.md; related because the top-level README update includes the same skill entry.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a new codex-session-reader skill to the repository.
Description check	✅ Passed	The description is directly related to the changeset, explaining the motivation (Why), implementation details (What), and testing approach.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bbd0c2a2-0afa-45dd-bc0e-7c35c95cb537

📥 Commits

Reviewing files that changed from the base of the PR and between 110db0b and 74d58dd.

📒 Files selected for processing (4)

• README.md
• skills/codex-session-reader/README.md
• skills/codex-session-reader/SKILL.md
• skills/codex-session-reader/scripts/codex_session_reader.py

[coderabbitai]

Actionable comments posted: 4

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6e250414-5853-422f-bcd5-06e10809aa92

📥 Commits

Reviewing files that changed from the base of the PR and between 74d58dd and fe11a80.

📒 Files selected for processing (1)

• skills/codex-session-reader/scripts/codex_session_reader.py

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

skills/codex-session-reader/scripts/codex_session_reader.py (1)

735-777: Avoid duplicate turn-slice work between JSON and Markdown paths.

selected_turns and effective_result are computed even when --format markdown, then slicing is done again in render_thread_markdown. Consider moving the pre-slice/model-copy logic inside the JSON branch only.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3e167a0b-3882-4d3b-993a-e4752b640c45

📥 Commits

Reviewing files that changed from the base of the PR and between fe11a80 and 7164390.

📒 Files selected for processing (1)

• skills/codex-session-reader/scripts/codex_session_reader.py

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

skills/codex-session-reader/scripts/codex_session_reader.py (1)

256-268: Reset per-session stream buffers on __enter__ for safe client reuse.

Instance-scoped _stdout_queue/_stderr_lines persist across runs. A stale EOF sentinel from a previous session can poison the next request if the same client object is reused.

Proposed fix

         self._process = process
+        self._stderr_lines.clear()
+        self._stdout_queue = Queue()
         self._stdout_thread = threading.Thread(
             target=self._drain_stdout,
             name="codex-session-reader-stdout",
             daemon=True,
         )

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f572e2fc-bd14-47a3-9b6d-7198041330ea

📥 Commits

Reviewing files that changed from the base of the PR and between 7164390 and df893ae.

📒 Files selected for processing (1)

• skills/codex-session-reader/scripts/codex_session_reader.py

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

skills/codex-session-reader/scripts/codex_session_reader.py (2)

278-292: Close stdout and stderr during teardown as well.

__exit__() only closes stdin. Because self._process stays referenced on the client, the parent-side stdout / stderr pipe objects can remain open until GC, which will accumulate file descriptors in long-lived processes or repeated tests. Close both streams and clear self._process after teardown.

Proposed fix

     def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
         """关闭 app-server 子进程。"""
 
         if self._process is None:
             return
 
-        if self._process.stdin:
-            self._process.stdin.close()
-        if self._process.poll() is None:
-            self._process.terminate()
-            try:
-                self._process.wait(timeout=3)
-            except subprocess.TimeoutExpired:
-                self._process.kill()
-                self._process.wait(timeout=3)
+        process = self._process
+        try:
+            if process.stdin:
+                process.stdin.close()
+            if process.poll() is None:
+                process.terminate()
+                try:
+                    process.wait(timeout=3)
+                except subprocess.TimeoutExpired:
+                    process.kill()
+                    process.wait(timeout=3)
+        finally:
+            if process.stdout:
+                process.stdout.close()
+            if process.stderr:
+                process.stderr.close()
+            self._process = None

---

411-417: Make notify() serialize models the same way as request().

request() accepts AppModel and dumps it before encoding, but notify() forwards params verbatim. Passing a model here will fail later with a raw TypeError from json.dumps, so the public client API is currently inconsistent. Either mirror the model_dump() branch or narrow the signature to dict[str, Any] | None.

Proposed fix

-    def notify(self, method: str, params: Any | None) -> None:
+    def notify(
+        self, method: str, params: AppModel | dict[str, Any] | None
+    ) -> None:
         """发送 JSON-RPC 通知。"""
 
         payload: dict[str, Any] = {"method": method}
         if params is not None:
-            payload["params"] = params
+            payload["params"] = (
+                params.model_dump(by_alias=True, exclude_none=True)
+                if isinstance(params, AppModel)
+                else params
+            )
         self._send_json(payload)

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ab827f5b-8d90-403b-bbdc-96911f5ede28

📥 Commits

Reviewing files that changed from the base of the PR and between df893ae and e84b0ee.

📒 Files selected for processing (1)

• skills/codex-session-reader/scripts/codex_session_reader.py