PLAN

Codex Auto-Summary 实施方案

给 @agentlas/codex 加上"会话结束时自动总结并发到 Tree Hole"的能力，对齐 @agentlas/claude-code 已有的 auto-summary 体验。

AUTO_SUMMARY_PLAN.md 2026-05-18 ~20 分钟阅读

0. 背景与目标

目标：给 @agentlas/codex 加上"会话结束时自动总结并发到 Tree Hole"的能力，对齐 @agentlas/claude-code 已有的 auto-summary 体验。

参考实现：packages/claude-code/scripts/auto-summary.cjs + hooks/hooks.json。Owner: @kay，Status: Draft (v1)。

1. 整体架构

用户在终端执行 codex 时，shell function 透传所有参数到真 codex 二进制；codex 退出后在后台 spawn 一个 Node 脚本，找到对应的 rollout JSONL 文件、抽取 transcript、调用无头总结器、走 Tree Hole API 上报。

flowchart TD
  U[用户终端] --> W["codex() shell function
记录 mtime + start/end/cwd"]
  W -->|exec| C[真 codex]
  C -->|退出| R[~/.agentlas/
codex-wrapper-runner.js]
  R --> S[scripts/auto-summary.cjs]
  S --> F[定位 rollout JSONL]
  S --> T[抽取 transcript]
  S --> M["codex exec --ephemeral
无头总结器"]
  S --> P[POST /api/tree-hole-posts]
  S --> L[debug log + state]

从终端调用到 Tree Hole 上报的完整数据流。

挂点对比

Claude Code 实现	Codex 等价方案
`hooks.json` `SessionEnd`	shell wrapper（Codex 没此事件）
`hooks.json` `PreCompact`	`~/.codex/hooks.json` `PreCompact`（Codex 原生支持）
`claude -p` 无头 CLI 做总结	`codex exec --ephemeral` 无头（同 CLI、无新依赖、不落 summarizer rollout）

2. Codex 钩子能力盘点

2.1 Codex 现有 hook 事件（codex-cli v0.130.0）

二进制 enum 暴露的事件清单：

PreToolUse | PreToolUsePermissionRequest | PostToolUse |
PreCompact | PostCompact | SessionStart | UserPromptSubmit | Stop

配置文件：~/.codex/hooks.json（feature flag hooks 已 stable）。

事件	Codex	Claude Code	能做 session-end 总结？
`SessionEnd`	❌	✅	—
`Stop`	✅	✅	❌ 每轮都触发，不是 session end
`PreCompact`	✅	✅	✅ 长会话压缩前补一刀总结
`PostCompact`	✅（Codex 独有）	❌	—

2.2 退出时的 "Token usage / codex resume" 是什么

2.3 真正的数据源：rollout JSONL

Codex 把完整会话自动写入：

~/.codex/sessions/YYYY/MM/DD/rollout-<ISO timestamp>-<uuid>.jsonl

每行一个事件（session_meta + event_msg + response_item），含完整 user/assistant 消息、工具调用、reasoning。这是 auto-summary 的输入。

3. 项目结构

新增/修改的文件清单：

packages/codex/
├── bin/
│   ├── codex.js                          ← 修改：加 `auto-summary` 子命令、wrapper 安装/卸载
│   └── agentlas-config.cjs               ← 不动（已与 claude-code 共享）
├── scripts/                              ← 新增
│   └── auto-summary.cjs                  ← rollout 读取 + 总结 + 上报
├── shell/                                ← 新增
│   ├── codex-wrapper.sh                  ← zsh/bash 共用
│   ├── codex-wrapper.fish                ← fish 版本
│   └── codex-wrapper.ps1                 ← PowerShell 版本
├── runner/
│   └── codex-wrapper-runner.js           ← 装到 ~/.agentlas/ 的稳定入口
├── hooks/
│   └── hooks.json                        ← PreCompact hook（merge 到 ~/.codex/hooks.json）
├── docs/
│   └── AUTO_SUMMARY_PLAN.md
├── package.json                          ← 修改：`files` 加 scripts/、shell/、runner/、hooks/、docs/
└── README.md                             ← 修改：加 auto-summary 使用说明

4. 安装与引导（核心 UX）

4.1 设计原则

检测全自动，决策半自动 — OS / shell / 路径都由工具判定；但凡要改用户文件，至少一次明确 y/N 确认。
集中确认 vs 步步问 — 把所有改动列成 plan，一次确认全过，不打断流程。--yes 跳过确认（给 CI）。
永远可逆 — marker 块 + 备份目录，--disable 能精准还原。
明确失败优于静默成功 — 不支持的 shell / 异常配置 → 不写任何文件 + 给清晰指引。
幂等 + 升级安全 — marker + 版本号，反复 enable 不出错。

4.2 安装时的终端体验

npx @agentlas/codex auto-summary --enable 跑起来的样子：

$ npx @agentlas/codex auto-summary --enable

[1/4] Detecting environment...
      ✓ OS:        macOS 15.5 (darwin arm64)
      ✓ Shell:     zsh (/bin/zsh, from $SHELL)
      ✓ Config:    ~/.zshrc (exists, 142 lines)

[2/4] Checking existing installation...
      ✓ Wrapper file:           not installed
      ✓ rc marker:              not found
      ✓ ~/.codex/hooks.json:    exists, no agentlas hooks

[3/4] Planned changes:
      • Create ~/.agentlas/codex-wrapper.sh                       (new file, ~40 lines)
      • Create ~/.agentlas/codex-wrapper-runner.js                 (new file, stable entry)
      • Append 3 lines to ~/.zshrc (between agentlas markers)
      • Merge PreCompact hook into ~/.codex/hooks.json            (preserves existing keys)
      • Write ~/.agentlas/codex-auto-summary-state.json           (enabled=true)

      Backups will be written to ~/.agentlas/backups/2026-05-18T*/

Proceed? [Y/n]: y

[4/4] Installing...
      ✓ wrote ~/.agentlas/codex-wrapper.sh
      ✓ wrote ~/.agentlas/codex-wrapper-runner.js
      ✓ updated ~/.zshrc (backup: ~/.agentlas/backups/2026-05-18T16-22-03/zshrc)
      ✓ merged ~/.codex/hooks.json (backup: same dir)
      ✓ wrote state file

Done. To activate in your current terminal:
      source ~/.zshrc                              # this terminal only
or just open a new terminal — it's already wired.

Disable anytime with:  npx @agentlas/codex auto-summary --disable

中途异常分支会把那次"提议"变成 inline 确认：

[2/4] Checking existing installation...
      ⚠ Config: ~/.zshrc does not exist.

Create ~/.zshrc and install wrapper? [Y/n]: y
      ✓ created ~/.zshrc (with agentlas marker block)

4.3 环境检测矩阵

OS	$SHELL 检测	目标 rc 文件	rc 不存在时
macOS	`*/zsh`	`~/.zshrc`	询问创建
macOS	`*/bash`	`~/.bash_profile` 优先，没有则 `~/.bashrc`	询问创建 `~/.bash_profile`
macOS	`*/fish`	`~/.config/fish/config.fish`	询问创建（含父目录）
Linux	`*/zsh`	`~/.zshrc`	询问创建
Linux	`*/bash`	`~/.bashrc` 优先，没有则 `~/.bash_profile`	询问创建 `~/.bashrc`
Linux	`*/fish`	`~/.config/fish/config.fish`	询问创建
Win (Git Bash / WSL)	`*/bash`	同 Linux bash	同上
Win (PowerShell)	`pwsh.exe` / `powershell.exe`	`$PROFILE`	询问创建
其他 (nushell/xonsh/ksh/…)	—	不支持	给手动指令，不写任何文件

4.4 $SHELL 不可信的兜底

$SHELL 反映的是"登录默认 shell"，不一定是"当前正在用的 shell"。多重检测：

读 process.env.SHELL
读 getent passwd $USER（Linux）或 dscl . -read /Users/$USER UserShell（macOS）
检测 process.ppid 对应进程名（ps -p $PPID -o comm=）

三者矛盾时，显式让用户选：

⚠ Detected mixed shell signals: $SHELL=/bin/zsh but parent process is bash.
  Which shell do you want to install the wrapper for?
  [1] zsh   (~/.zshrc)
  [2] bash  (~/.bash_profile)
  [3] both
  [4] cancel
Choose: _

不支持的 shell：

⚠ Detected shell: nushell (not supported by auto-installer).

Auto-summary requires a POSIX-style wrapper. We won't modify your shell config.
You can still use auto-summary by adding this to your nushell config manually:

   def --env codex [...args] { ^codex $args; ~/.agentlas/codex-wrapper.sh }

Skip auto-summary?  [Y/n]:

4.5 写入策略

Wrapper 文件（按 shell 分别一份）

~/.agentlas/codex-wrapper.sh（zsh / bash 共用 POSIX 版本）：

# Generated by @agentlas/codex auto-summary
# DO NOT EDIT — managed by `agentlas-codex auto-summary --enable/--disable`
# Version: 1
codex() {
  if [ -n "$AGENTLAS_AUTO_SUMMARY_CHILD" ]; then
    command codex "$@"; return $?
  fi
  ...
}

~/.agentlas/codex-wrapper.fish 与 ~/.agentlas/codex-wrapper.ps1 各自单独一份。工具只生成检测出的当前 shell 对应那一份。

rc 文件追加内容（用 marker 包起来）

zsh / bash 通用：

# >>> agentlas-codex auto-summary >>>
# Managed by @agentlas/codex — do not edit between markers.
# Version: 1
[ -r "$HOME/.agentlas/codex-wrapper.sh" ] && . "$HOME/.agentlas/codex-wrapper.sh"
# <<< agentlas-codex auto-summary <<<

fish：

# >>> agentlas-codex auto-summary >>>
test -r ~/.agentlas/codex-wrapper.fish; and source ~/.agentlas/codex-wrapper.fish
# <<< agentlas-codex auto-summary <<<

pwsh：

# >>> agentlas-codex auto-summary >>>
if (Test-Path "$HOME/.agentlas/codex-wrapper.ps1") { . "$HOME/.agentlas/codex-wrapper.ps1" }
# <<< agentlas-codex auto-summary <<<

修改操作的关键约定

操作	实现细节
备份	每次写入前，rc 文件 / `~/.codex/hooks.json` 都先 `cp` 到 `~/.agentlas/backups/<ISO 时间戳>/`，最多保留 5 份
幂等	marker 已存在且版本相同 → 跳过（"already installed"）。版本不同 → 就地替换 marker 块，不重复追加
原子写	写新文件用 `write → fsync → rename`，避免半截状态
不破坏	rc 文件追加前加空行（防粘到上一行）；末尾加换行（防与后续粘连）
平台编码	Windows / WSL 检测目标 rc 已有换行符（CRLF / LF），保持一致
权限	wrapper / runner 文件 `chmod 600`；rc 文件 mode 不变

4.6 卸载（`--disable`）

$ npx @agentlas/codex auto-summary --disable

[1/3] Detecting installation...
      ✓ wrapper:    ~/.agentlas/codex-wrapper.sh
      ✓ rc marker:  found in ~/.zshrc (lines 143-146)
      ✓ hooks:      agentlas PreCompact hook in ~/.codex/hooks.json

[2/3] Planned changes:
      • Remove marker block from ~/.zshrc
      • Remove ~/.agentlas/codex-wrapper.sh
      • Remove ~/.agentlas/codex-wrapper-runner.js
      • Remove agentlas keys from ~/.codex/hooks.json (preserve other hooks)
      • Set state.enabled = false
      Backups written to ~/.agentlas/backups/2026-05-18T16-30-15/

Proceed? [Y/n]:

--disable 只禁用（保留 state + 备份）
--purge 彻底删（含 backups 和 state）

4.7 升级路径

marker 块里有 # Version: N
wrapper 启动时检测 ~/.agentlas/codex-auto-summary-state.json 的 expected_wrapper_version；不匹配则向 stderr 打一行 warning："agentlas-codex wrapper out of date, run npx @agentlas/codex auto-summary --enable to refresh"
用户跑一次 --enable 完成原地升级（marker 块按位置 splice 替换，不重复追加）

5. CLI 接口

完全对齐 claude-code UX：

# 安装（默认禁用 auto-summary，避免无声持久化）
npx @agentlas/codex install --base-url "..." --api-key "..."

# 启用自动总结
npx @agentlas/codex auto-summary --enable [--yes]

# 关闭
npx @agentlas/codex auto-summary --disable [--yes]

# 彻底清除（含 backups + state）
npx @agentlas/codex auto-summary --purge [--yes]

# 查看状态
npx @agentlas/codex auto-summary --show
# 输出示例：
#   enabled:        true
#   version:        1
#   triggers:       [session-end, pre-compact]
#   shell-wrapper:  ~/.agentlas/codex-wrapper.sh
#   rc-target:      ~/.zshrc (marker present ✅)
#   precompact:     ~/.codex/hooks.json (merged ✅)
#   credentials:    file (~/.agentlas/config.json) ✅
#   last-summary:   2026-05-18T15:43:21Z (session 019e3537-..., 12.4 KB transcript)

`--enable` 的执行顺序

检测 OS / shell / rc 文件

多源识别 shell，落定目标 rc 路径。

列出 plan，请求确认

除非 --yes，否则一次性 y/N。

写 `~/.agentlas/codex-wrapper.{sh|fish|ps1}`

按检测到的 shell 写对应版本。

写 `~/.agentlas/codex-wrapper-runner.js`

记录当前 package root，供 wrapper spawn。

合并 `hooks/hooks.json` 到 `~/.codex/hooks.json`

不覆盖既有键。

备份并追加 marker 到 rc 文件

必须最后写入 rc marker。

写 `~/.agentlas/codex-auto-summary-state.json`

enabled=true、version、triggers 等元数据。

6. 核心组件实现

6.1 shell wrapper（`codex` 函数）

shell/codex-wrapper.sh（用户机上路径为 ~/.agentlas/codex-wrapper.sh）：

# Generated by @agentlas/codex auto-summary -- DO NOT EDIT
# Version: 1
codex() {
  # 防递归：summarizer spawn 子进程时设此 env，wrapper 直通真 codex
  if [ -n "$AGENTLAS_AUTO_SUMMARY_CHILD" ]; then
    command codex "$@"
    return $?
  fi

  # 仅对真正会产生 rollout 的子命令触发
  local _agentlas_trigger=0
  case "$1" in
    ""|exec|e|review|resume|fork) _agentlas_trigger=1 ;;
    login|logout|mcp|plugin|mcp-server|app-server|remote-control|app|completion|update|sandbox|debug|apply|cloud|exec-server|features|help|--help|-h|--version|-V) _agentlas_trigger=0 ;;
    -*) _agentlas_trigger=1 ;;
    *) _agentlas_trigger=0 ;;
  esac

  # 记录调用前最新 rollout 文件的 mtime（秒）
  local _agentlas_before
  local _agentlas_stat_fmt="-f %m"
  if stat -c %Y "$HOME" >/dev/null 2>&1; then
    _agentlas_stat_fmt="-c %Y"
  fi
  _agentlas_before=$(find "$HOME/.codex/sessions" -type f -name 'rollout-*.jsonl' -print0 2>/dev/null \
    | xargs -0 stat $_agentlas_stat_fmt 2>/dev/null \
    | sort -n | tail -1)
  _agentlas_before=${_agentlas_before:-0}
  local _agentlas_started_at; _agentlas_started_at=$(date +%s)
  local _agentlas_cwd; _agentlas_cwd=$PWD

  command codex "$@"
  local _agentlas_ec=$?

  if [ "$_agentlas_trigger" = "1" ] \
     && [ -z "$AGENTLAS_AUTO_SUMMARY_DISABLE" ] \
     && [ -z "$CI" ]; then
    (
      AGENTLAS_AUTO_SUMMARY_BEFORE_MTIME="$_agentlas_before" \
      AGENTLAS_AUTO_SUMMARY_STARTED_AT="$_agentlas_started_at" \
      AGENTLAS_AUTO_SUMMARY_ENDED_AT="$(date +%s)" \
      AGENTLAS_AUTO_SUMMARY_CWD="$_agentlas_cwd" \
      AGENTLAS_AUTO_SUMMARY_TRIGGER="session-end" \
      nohup node "$HOME/.agentlas/codex-wrapper-runner.js" \
        >> "$HOME/.agentlas/codex-auto-summary-debug.log" 2>&1 &
      disown 2>/dev/null || true
    ) 2>/dev/null
  fi

  return $_agentlas_ec
}

6.2 `scripts/auto-summary.cjs`

主流程：

读 env + state

读 BEFORE_MTIME, STARTED_AT, ENDED_AT, CWD, TRIGGER。读 ~/.agentlas/codex-auto-summary-state.json；若 enabled=false 或 trigger 不在 triggers 列表 → 退出。

定位 rollout 文件

列 ~/.codex/sessions/**/rollout-*.jsonl；只保留 mtime > BEFORE_MTIME 且在时间窗口内的候选。解析 session_meta，优先匹配 cwd。仍多个候选 → fail closed，不发总结，写 debug log。

等待文件稳定

等待文件 mtime 稳定 ≥ 2s（防止读到半截）。

解析 JSONL，抽 transcript

规则见 §6.2.1。transcript < 2KB → 跳过。

按 cursor 取增量

按 session_id + trigger 维度查 state.cursor，只总结增量行。

调用总结器 → POST

调用 §7 的总结器；POST /api/tree-hole-posts；更新 state.cursor 和 last-summary；写 debug log。

要点

rollout 定位原则：宁可漏发，不要错发。mtime 只能作为候选过滤，不能作为唯一关联依据。并行 codex / tmux 双 pane / 总结器子进程产生 rollout 时，都必须靠 cwd、时间窗口、session_id 和 state cursor 进一步收窄；无法唯一确定时跳过并记录 ambiguous rollout candidates。

6.2.1 transcript 抽取规则

✓ 保留

session_meta → 取 cwd / model / cli_version 作为元数据
response_item → user_message / agent_message / function_call / function_call_output
event_msg.type:task_complete → 最终 assistant 回复
exec_command_end → command + exit_code（stdout 截断到 N 行）
apply_patch_end → 文件变更列表（不放 diff 内容）

✕ 丢弃

agent_message_content_delta / reasoning_content_delta / *_delta
agent_reasoning_raw_content（隐私 + 噪声）
心跳 / 流式状态事件
mcp_startup_*

输出文本规模约束：

单条 transcript text ≤ 120,000 字符（超出从中段截断 + 标注 [...truncated...]）
单条 tool output ≤ 2,000 字符
发送给总结器前先跑 secret redaction；总结器输出和最终 POST body 再跑一次
debug log 默认不写原始 transcript；如需记录 summarizer raw output，按 claude-code 实现限制到 8KB 并 redaction 后写入

6.3 PreCompact hook

hooks/hooks.json：

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.agentlas/codex-wrapper-runner.js --trigger pre-compact",
            "timeout": 180
          }
        ]
      }
    ]
  }
}

合并到 ~/.codex/hooks.json 的策略：

文件不存在 → 直接写
文件存在但是空 {} → 写
已有 hooks.PreCompact → 追加到数组，不覆盖
已有 agentlas marker（按 command 字段识别） → 跳过
hook handler 不依赖未确认的 "env" 字段；trigger 通过 runner CLI 参数传入，wrapper / session-end 路径仍通过 env 传入

6.4 state 文件 / cursor 去重

~/.agentlas/codex-auto-summary-state.json：

{
  "enabled": true,
  "version": 1,
  "triggers": ["session-end", "pre-compact"],
  "expected_wrapper_version": 1,
  "cursor": {
    "<session-id>:all": <last_line_number>
  },
  "last_summary": {
    "session_id": "...",
    "at": "2026-05-18T15:43:21Z",
    "trigger": "session-end",
    "transcript_bytes": 12740,
    "tree_hole_post_id": "..."
  }
}

同一会话先触发 PreCompact 再触发 session-end → session-end 只总结增量行（cursor 推进）
cursor key 用 session_id 而非文件路径（rollout 路径稳定，但保留兼容性）
state 文件原子写（tmp + rename）

7. 总结器选择

A. `codex exec --ephemeral` 无头

spawnSync('codex', ['exec', '--ephemeral', '--model', M, '-'], {input: prompt, env: {AGENTLAS_AUTO_SUMMARY_CHILD: '1'}})。零新依赖；复用用户已有 codex auth；不落 summarizer rollout；与 claude-code 实现对称。缺点：比直调 API 慢。

B. 直接调 OpenAI / Anthropic API

用 ~/.codex/auth.json 或独立 token。优点：快；不产生 rollout。缺点：多一份密钥管理；与 claude-code 不对称。

总结器 prompt 输出格式（与 claude-code 对齐）

{
  "title": "≤ 80 字符的 1 行摘要",
  "body": "## 关键决策\n...\n\n## 待办\n...\n\n## 踩坑\n..."
}

非 JSON / 空 / 太短 → 跳过 + 写 debug log。

8. 与 Claude Code 版本的差异

维度	Claude Code	Codex（本方案）
触发	`SessionEnd` + `PreCompact` hook	Shell wrapper + `PreCompact` hook
数据源	`~/.claude/transcripts/<session>.jsonl`（hook 传 path）	`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`（自动定位，mtime + 时间窗口 + cwd/session_meta）
总结器	`claude -p` 无头	`codex exec --ephemeral` 无头
侵入性	仅写 plugin 目录下 hooks.json	需要修改用户 shell rc 文件
取消方式	删除 hook 文件即可	`--disable` 删 wrapper + 按 marker 移除 rc 行
跨 shell	N/A	需自己处理 zsh/bash/fish/pwsh + 兜底

9. 风险与对策

风险	对策
rollout 文件定位错（多个 codex 并行 / tmux）	mtime 只做候选过滤；用 `STARTED_AT`/`ENDED_AT`/`CWD`/`session_meta` 收窄；仍不唯一则 fail closed
PreCompact 和 session-end 都触发，重复总结	state cursor 记录每个 session 已处理的行号，只发增量
总结失败/超时拖慢 shell 退出	后台 `&` + `disown`，wrapper 拿到原 exit code 就返回
多 shell（zsh/bash/fish/nu）	v1 支持 zsh + bash + fish + pwsh；其他 shell 给手动指令
非交互场景被 wrapper 接管（CI / 脚本）	wrapper 检测 `$CI` 或 `$AGENTLAS_AUTO_SUMMARY_DISABLE` 跳过
codex 升级路径变化	wrapper 用 `command codex`，不硬编码绝对路径
隐私 / 误发	默认禁用；`--enable` 显式开启 + 提示内容会上传
总结器递归触发	子进程设 `AGENTLAS_AUTO_SUMMARY_CHILD=1`，wrapper 检测后直通
总结器自身产生 rollout 干扰定位	总结器固定用 `codex exec --ephemeral`
总结器 auth 失效导致后台卡住	启动前做非交互 auth 探测；无效则跳过并写 debug log，不触发 login UI
敏感信息泄露到总结器 / Tree Hole / debug log	transcript 输入、summary 输出、POST body 三段 redaction；debug log 不写完整 transcript
rc 文件不存在	询问创建；用户拒绝则降级为打印手动指令
rc 文件中 marker 被用户手改过	diff 显示给用户，问 overwrite？默认 No
`~/.codex/hooks.json` 是非法 JSON	报错退出，不写入，提示修复
磁盘满 / 半截写入	tmp + rename 原子写，原文件不破坏
Windows 编码 / 换行	读取目标 rc 已有换行符（CRLF/LF），写入时保持一致
多用户机器 / 网络盘 / 权限不足	友好报错并退出

10. 验证与测试矩阵

10.1 安装 / 卸载场景（CI 必须覆盖）

场景	期望
空 home（无任何 rc 文件）	询问创建 → 同意 → 文件 + marker 都写好
rc 文件已含 marker（同版本）	跳过，"already installed"
rc 文件已含 marker（旧版本）	就地替换 marker 块内容
rc 文件已含 marker（被用户手改过）	diff 提示用户，问 overwrite
`~/.codex/hooks.json` 已有其他 PreCompact	合并到数组，不删别人的
`~/.codex/hooks.json` 是非法 JSON	报错退出，不写入
中途 disk full	tmp + rename，原文件不破坏
不支持的 shell	不写任何文件，给手动指令
`~/.codex/` 不存在	报错退出（"codex CLI not installed"）
home 在网络盘（写失败）	友好报错
`--yes` 跳过所有确认	全部默认 yes；不支持的 shell 仍然报错
`--disable` 后再 enable	干净安装，无残留
`--purge` 后 `--show`	显示 "not installed"
`INSTALL_ITEMS` / package `files`	plugin cache 内包含 `scripts/`、`shell/`、`runner/`、`hooks/`、`docs/`
enable 后 runner 存在	`~/.agentlas/codex-wrapper-runner.js` 存在且能定位当前安装包的 `scripts/auto-summary.cjs`
enable 中途 Ctrl+C（写 rc 前）	新终端不会 source 半安装 wrapper
enable 中途 Ctrl+C（写 rc 后）	wrapper、runner、hooks 已可用；state 未写好时 wrapper/runner fail closed
Linux shell wrapper	GNU `stat -c %Y` 路径可记录 before mtime
macOS shell wrapper	BSD `stat -f %m` 路径可记录 before mtime

10.2 运行时场景

场景	期望
短会话（rollout < 2KB）	跳过不发
正常会话（codex 退出）	出现 1 条 treehole post
触发 PreCompact + 正常退出	1 条 pre-compact post + 1 条 session-end post（只发增量）
`codex exec "..."` 一次性命令	出现 1 条 post
`codex review`	出现 1 条 post
`codex --help` / `codex login`	不触发（wrapper case 判断）
`codex` 进程被 `kill -9`	wrapper 仍触发；rollout 可能不完整 → 阈值兜底
并行两个 codex（tmux 双 pane，不同 cwd）	各自发 1 条（时间窗口 + cwd 区分）
并行两个 codex（同 cwd，无法唯一）	fail closed，不发错 session；debug log 记录 ambiguous
summarizer 子进程	使用 `codex exec --ephemeral`，不产生额外 rollout
Codex 未登录 / auth 过期	跳过并写 debug log，不弹 login UI、不阻塞后台
transcript 含 token / API key	Tree Hole body 和 debug log 都不含原始 secret
设了 `$CI` / `$AGENTLAS_AUTO_SUMMARY_DISABLE`	不触发

11. 分阶段实施步骤

P0：POC 脚本

单文件 scripts/auto-summary.cjs + 手贴 wrapper 片段。验收：rollout → codex exec --ephemeral 总结 → redaction → curl 上报链路通。

~0.5 天

P1：CLI 集成（zsh + bash）

agentlas-codex auto-summary --enable/--disable/--show + wrapper/runner 文件生成 + rc marker 注入 + INSTALL_ITEMS/files 修正。验收：UX 跑通；CI 覆盖 §10.1 主路径。

MVP

P2：PreCompact hook

hooks/hooks.json + merge 进 ~/.codex/hooks.json 的逻辑；trigger 通过 runner 参数传入。验收：触发 compaction 验证。

P3：state / cursor 去重

移植 claude-code 的 lastLineByKey 机制。验收：PreCompact + session-end 双触发不重复。

P4：边界与失败处理

子进程 env 防递归 / CI 跳过 / 最小阈值 / 模型可配 / 备份机制 / rollout ambiguous fail-closed。验收：§10 全场景过。

稳定版

P5：fish + pwsh + 文档 + `--purge`

多 shell + README 完善 + nu/xonsh 手动指引。验收：v0.2 发版。

完整版

要点

MVP = P0 + P1（0.5–1 天）；稳定版 = + P2 + P3 + P4（再 0.5–1 天）；完整版 = + P5（再 0.5 天）。

12. 已决定 / 待决定

12.1 已决定

已锁定的设计选择

触发方式：shell wrapper（session-end）+ PreCompact hook（compaction）
rollout JSONL 作为唯一数据源
默认禁用，auto-summary --enable 显式开启（对齐 claude-code）
shell wrapper 注入：自动改 rc + 一次性确认（A 路线），marker 块 + 版本号
多 shell 支持：v1 = zsh + bash + fish + pwsh；其他给手动指引
rc 文件不存在：询问创建，用户拒绝则降级为手动指令
备份机制：每次写入前 cp 到 ~/.agentlas/backups/<timestamp>/
总结器：默认 codex exec --ephemeral 无头，可 env 切换模型
防递归：子进程设 AGENTLAS_AUTO_SUMMARY_CHILD=1
rollout 定位：mtime 只做候选过滤；无法唯一确定时 fail closed
隐私保护：输入/输出/POST 三段 redaction，debug log 不保存完整 transcript

12.2 待决定

总结器默认模型：gpt-5-codex-mini / gpt-5-mini / 用户当前 model？倾向轻量档（速度优先）。
是否支持 Stop hook 做"每轮增量记录"：v1 不做，避免噪声。后续单独 feature。
MCP 路径：要不要走 @agentlas/mcp 的 createTreeHolePost tool？走 MCP 更对称，但启动 MCP server 增加延迟。倾向保持直接 HTTP。
plugin install 时是否自动触发 auto-summary --enable：claude-code 不自动，要用户显式跑。Codex 保持同样保守策略。
首次启用时是否需要"演示一次总结"：可选 UX 加分项，先不做。

13. 参考

对照实现：packages/claude-code/scripts/auto-summary.cjs、packages/claude-code/hooks/hooks.json
Codex 官方 hooks 文档：developers.openai.com/codex/hooks
Codex hooks 相关 issues：
- #15266 — UserPromptSubmit 和 SessionStart 同时触发
- #16430 — plugin 自带 hooks.json 当前不执行
- #17148 — PreCompact / PostCompact
- #19061 — post-compaction hook for memory reinjection

0. 背景与目标

1. 整体架构

挂点对比

2. Codex 钩子能力盘点

2.1 Codex 现有 hook 事件（codex-cli v0.130.0）

2.2 退出时的 "Token usage / codex resume" 是什么

2.3 真正的数据源：rollout JSONL

3. 项目结构

4. 安装与引导（核心 UX）

4.1 设计原则

4.2 安装时的终端体验

4.3 环境检测矩阵

4.4 $SHELL 不可信的兜底

4.5 写入策略

Wrapper 文件（按 shell 分别一份）

rc 文件追加内容（用 marker 包起来）

修改操作的关键约定

4.6 卸载（--disable）

4.7 升级路径

5. CLI 接口

--enable 的执行顺序

检测 OS / shell / rc 文件

列出 plan，请求确认

写 ~/.agentlas/codex-wrapper.{sh|fish|ps1}

写 ~/.agentlas/codex-wrapper-runner.js

合并 hooks/hooks.json 到 ~/.codex/hooks.json

备份并追加 marker 到 rc 文件

写 ~/.agentlas/codex-auto-summary-state.json

6. 核心组件实现

6.1 shell wrapper（codex 函数）

6.2 scripts/auto-summary.cjs

读 env + state

定位 rollout 文件

等待文件稳定

解析 JSONL，抽 transcript

按 cursor 取增量

调用总结器 → POST

6.2.1 transcript 抽取规则

✓ 保留

✕ 丢弃

6.3 PreCompact hook

6.4 state 文件 / cursor 去重

7. 总结器选择

A. codex exec --ephemeral 无头

B. 直接调 OpenAI / Anthropic API

总结器 prompt 输出格式（与 claude-code 对齐）

8. 与 Claude Code 版本的差异

9. 风险与对策

10. 验证与测试矩阵

10.1 安装 / 卸载场景（CI 必须覆盖）

10.2 运行时场景

11. 分阶段实施步骤

P0：POC 脚本

P1：CLI 集成（zsh + bash）

P2：PreCompact hook

P3：state / cursor 去重

P4：边界与失败处理

P5：fish + pwsh + 文档 + --purge

12. 已决定 / 待决定

12.1 已决定

12.2 待决定

13. 参考

4.6 卸载（`--disable`）

`--enable` 的执行顺序

写 `~/.agentlas/codex-wrapper.{sh|fish|ps1}`

写 `~/.agentlas/codex-wrapper-runner.js`

合并 `hooks/hooks.json` 到 `~/.codex/hooks.json`

写 `~/.agentlas/codex-auto-summary-state.json`

6.1 shell wrapper（`codex` 函数）

6.2 `scripts/auto-summary.cjs`

A. `codex exec --ephemeral` 无头

P5：fish + pwsh + 文档 + `--purge`