AI Session Logger

AI Session Logger 是一个面向 AI Coding Agent 的本地会话日志工具。它可以为 Claude Code、Codex CLI、Cursor、Gemini CLI、Kiro CLI 安装 hook，并在每轮 Agent 交互完成后，把用户问题、AI 回复、工具调用和工具结果写入当前项目的 JSONL 文件。

默认日志目录：

docs/agent-session

核心目标：

• 自动安装和卸载 Agent hook，不覆盖用户已有 hook。
• 默认项目级配置，尽量适合团队项目和跨机器使用。
• 默认对日志做基础脱敏，并建议加入 .gitignore。
• hook 失败不阻塞 Agent，支持 pending/recover 兜底补写。
• npm 包发布构建后的可运行 JS；无 Node 机器可使用 standalone binary。

文档导航

| 文档 | 面向对象 | 内容 | |------|----------|------| | README.md | 所有人 | 快速开始、核心概念、常用命令 | | 使用手册.md | 外部用户 | 完整安装、使用、卸载、源码本地安装、故障排查 | | PUBLISHING.md | 维护者 | npm 发布、包体检查、standalone binary 发布 | | REQUIREMENTS.md | 维护者 | 当前需求规格、路径规则、hook 写入规则、验收标准 | | IMPLEMENTATION_PLAN.md | 维护者 | 历史实施方案与实现回溯 |

支持情况

| Agent | 配置文件 | 默认事件 | 状态 | |------|----------|----------|------| | Claude Code | .claude/settings.json 或 ~/.claude/settings.json | Stop, UserPromptSubmit | 支持 | | Codex CLI | .codex/hooks.json 或 ~/.codex/hooks.json | Stop, UserPromptSubmit | 支持 | | Cursor | .cursor/hooks.json 或 ~/.cursor/hooks.json | stop, beforeSubmitPrompt | 实验性支持 | | Gemini CLI | .gemini/settings.json 或 $GEMINI_HOME/settings.json 或 ~/.gemini/settings.json | AfterAgent, BeforeAgent | 支持 | | Kiro CLI | .kiro/agents/ai-session-logger.json 或 $KIRO_HOME/agents/ai-session-logger.json | stop, userPromptSubmit | 实验性支持 |

Cursor hook 与 transcript 格式仍可能随版本变化，推荐优先使用项目级 .cursor/hooks.json。Kiro CLI hook 当前写入 custom agent 配置，使用时需要选择该 agent，或把 hooks block 复制到你自己的 Kiro agent 配置中。

安装

方式一：npm 全局安装

适合已经安装 Node.js 20+ 的机器：

npm install -g ai-session-logger
ai-logger --help

npm 包入口是 ai-logger，发布包内运行的是 dist/npm/bin/ai-logger.js。

方式二：npx 临时运行

npx ai-session-logger --help

不建议长期用 npx 安装 hook。项目级 hook 默认写入动态命令 ai-logger hook ...，后续 Agent 运行时仍需要在 PATH 中找到 ai-logger。

方式三：无 Node 环境使用 standalone binary

完全没有 Node/npm 的机器不能执行 npm install -g ai-session-logger。这种场景请从 GitHub Release 下载 standalone binary，或使用安装脚本。

macOS/Linux：

# 发布前请把 OWNER/ai-session-logger 换成真实 GitHub 仓库
AI_SESSION_LOGGER_REPO=OWNER/ai-session-logger \
  curl -fsSL https://raw.githubusercontent.com/OWNER/ai-session-logger/main/install/install.sh | sh

Windows PowerShell：

$env:AI_SESSION_LOGGER_REPO = "OWNER/ai-session-logger"
irm https://raw.githubusercontent.com/OWNER/ai-session-logger/main/install/install.ps1 | iex

安装后同样使用：

ai-logger --help

方式四：通过源码本地安装

适合开发、内测、未发布 npm 包时使用：

# 预览，不写入启动器
npm run install:local:dry

# 交互式安装到 ~/.local/bin/ai-logger
npm run install:local

# 非交互安装到 ~/.local/bin/ai-logger
npm run install:local -- --yes

如果终端找不到 ai-logger，把本地安装目录加入 PATH：

export PATH="$HOME/.local/bin:$PATH"

源码本地安装后直接进入 hook 安装：

npm run install:local:hooks

全自动本地安装 CLI 并写入当前项目 hook：

npm run install:local -- --install-hooks --target codex --scope project --yes

Node 环境说明

npm 安装方式需要 Node.js 20+，原因是：

• npm 包本身需要 Node.js 执行。
• Agent hook 默认调用 ai-logger hook ...，运行时仍需要 Node.js 或 standalone binary。

安装 hook 时默认不会写死某台机器的 Node 路径，也不会写死 npm 全局安装目录：

ai-logger hook --managed-by ai-session-logger --agent codex-cli --output-dir docs/agent-session --backfill latest-turn --redact

这样项目级 hook 配置更容易跨机器共享。要求是每台机器都能在 Agent 运行时的 PATH 中找到 ai-logger。

如果检测不到 Node，可以尝试：

ai-logger install-node
ai-logger install-node --yes

也可以在安装 hook 时自动尝试安装：

ai-logger install --target codex --scope project --yes --install-node

自动安装策略：

| 系统 | 安装方式 | |------|----------| | macOS | brew install node | | Windows | winget install OpenJS.NodeJS.LTS | | Linux | apt-get / dnf / yum，需要 sudo |

如果系统没有对应包管理器，工具会打印手动安装提示。

快速开始

进入需要记录日志的项目目录：

cd /path/to/project
ai-logger install

交互界面默认使用中文，支持 ↑/↓ 移动、Space 选择/切换、Enter 开始安装、Esc 取消：

┌───────────────────────────────────────────────────────┐
│  AI Session Logger v0.1.1                             │
│                                                       │
│  请选择需要配置的 Agent                               │
│  › ◼ Claude Code  (已检测)                            │
│    ◼ Codex CLI    (已检测)                            │
│    ◼ Cursor       (已检测，实验性)                    │
│    ◼ Gemini CLI   (已检测)                            │
│    ◼ Kiro CLI     (已检测，实验性)                    │
│                                                       │
│  配置写入范围                                         │
│    ● 仅当前项目 (local/project)                       │
│    ○ 所有项目 (global)                                │
│                                                       │
│  哪些事件触发日志记录？                               │
│    ◼ Stop / stop        (推荐)                        │
│    ◼ Prompt submit      (推荐)                        │
│    ◻ Cursor response    (可选)                        │
│                                                       │
│  是否对日志进行敏感信息脱敏？                         │
│    ● 是 (推荐)                                        │
│    ○ 否                                               │
│                                                       │
│  是否将 docs/agent-session 日志加入 .gitignore？      │
│    ● 是 (推荐)                                        │
│    ○ 否                                               │
│                                                       │
│  ↑/↓ 移动，Space 选择/切换，Enter 开始安装，Esc 取消  │
└───────────────────────────────────────────────────────┘

默认选中项目级安装，会在当前项目下写入 .claude/、.codex/、.cursor/、.gemini/ 或 .kiro/agents/ hook 配置。非交互模式不传 --scope 时也默认使用 project。

Dry-run 预览

ai-logger install --target codex --scope project --yes --dry-run --json
ai-logger install --target claude --scope project --yes --dry-run --json
ai-logger install --target cursor --scope project --yes --dry-run --json
ai-logger install --target gemini --scope project --yes --dry-run --json
ai-logger install --target kiro --scope project --yes --dry-run --json
ai-logger install --target all --scope project --yes --dry-run --json

项目级安装

ai-logger install --target codex --scope project --yes
ai-logger install --target claude --scope project --yes
ai-logger install --target cursor --scope project --yes
ai-logger install --target gemini --scope project --yes
ai-logger install --target kiro --scope project --yes
ai-logger install --target all --scope project --yes

全局安装

ai-logger install --target codex --scope global --yes
ai-logger install --target claude --scope global --yes
ai-logger install --target cursor --scope global --yes
ai-logger install --target gemini --scope global --yes
ai-logger install --target kiro --scope global --yes

Cursor 全局 hook 与 Kiro CLI custom agent hook 仍属于实验性支持，推荐优先使用项目级配置。

安装后检查

ai-logger status --scope project
ai-logger doctor --scope project

如果 Agent 提示 review/trust hook，请确认命令内容后信任，并重启或 reload 对应 Agent。

输出路径

Git 项目：

docs/agent-session/<branch>/<gitUser>/<agent>/<sessionId>.jsonl

非 Git 项目：

docs/agent-session/<YYYYMMDD>/<agent>/<sessionId>.jsonl

其中 <agent> 固定为 cursor、codex、claude、gemini 或 kiro。

示例：

docs/agent-session/feature-login/alice/codex/f31a969b-f656-40e1-b213-ff8ce37fbcae.jsonl
docs/agent-session/20260608/cursor/f31a969b-f656-40e1-b213-ff8ce37fbcae.jsonl
docs/agent-session/20260608/gemini/f31a969b-f656-40e1-b213-ff8ce37fbcae.jsonl

默认会建议把日志加入 .gitignore：

/docs/agent-session/**/*.jsonl
/.ai-session-logger/

JSONL 格式

每行是一条完整 turn 记录：

{
  "schemaVersion": 1,
  "agent": "codex-cli",
  "hookEvent": "Stop",
  "sessionId": "f31a969b-f656-40e1-b213-ff8ce37fbcae",
  "turnId": "turn_0001_abcd1234",
  "projectPath": "/path/to/project",
  "branch": "feature-login",
  "gitUser": "alice",
  "loggedAt": "2026-06-08T12:00:00.000Z",
  "messages": [
    { "role": "user", "content": "帮我修复这个 bug" },
    { "role": "assistant", "content": "我来分析一下..." }
  ],
  "messageFingerprint": "sha256:..."
}

失败兜底策略

AI Session Logger 不会因为日志失败阻塞 Agent。失败时采用以下兜底：

• Stop / stop 漏触发：下一次 prompt submit 事件补写上一轮。
• hook handler 崩溃或超时：state 不前移，下一次 hook 重新补写。
• JSONL append 失败：不更新 state，写入 pending，等待 recover。
• append 成功但 state 未更新：下一次扫描 JSONL 尾部 fingerprint，避免重复写。
• transcript 临时不可读：fallback 扫描 Agent session 目录。
• Cursor/Kiro/Gemini 部分事件缺少 transcript 时：可用 hook stdin 中的 prompt/response 做单条消息兜底。
• Cursor double-fire：lock + fingerprint 去重。

手动恢复：

ai-logger recover --dry-run
ai-logger recover
ai-logger recover --session <sessionId>
ai-logger recover --target codex

常用命令

# 帮助
ai-logger --help

# 交互式安装
ai-logger install

# 非交互安装，默认项目级
ai-logger install --target all --scope project --yes

# 指定输出目录
ai-logger install --target codex --scope project --yes --output-dir docs/agent-session

# 本地调试时指定 hook 启动命令
ai-logger install --target codex --scope project --yes --hook-command "node /absolute/path/src/bin/ai-logger.js"

# 状态和诊断
ai-logger status --scope project
ai-logger doctor --scope project

# 恢复
ai-logger recover --dry-run
ai-logger recover --session <sessionId>

# 卸载 hook
ai-logger uninstall --target all --scope project

# 删除本地/standalone CLI 启动器
ai-logger delete-cli --dry-run
ai-logger delete-cli --yes

本地开发与调试

克隆并检查

git clone <repo-url>
cd ai-session-logger
npm test
npm run check

本项目运行时不依赖第三方 npm 包，测试使用 Node.js 内置 node:test。

直接运行源码 CLI

node src/bin/ai-logger.js --help
node src/bin/ai-logger.js status --scope project

本地模拟 hook 输入

使用测试 fixture 模拟 Codex hook：

printf '{"session_id":"local-debug","transcript_path":"%s","cwd":"%s","hook_event_name":"Stop"}' \
  "$PWD/tests/fixtures/transcripts/codex-transcript.jsonl" \
  "$PWD" \
| node src/bin/ai-logger.js hook --agent codex-cli --output-dir docs/agent-session --backfill all --redact

运行后检查：

find docs/agent-session -name '*.jsonl' -print

本地安装 hook 的推荐方式

如果没有执行 npm install -g，项目级 hook 默认写入 ai-logger hook ... 可能找不到命令。调试时建议指定源码入口：

node src/bin/ai-logger.js install \
  --target codex \
  --scope project \
  --yes \
  --dry-run \
  --hook-command "node $PWD/src/bin/ai-logger.js"

确认 dry-run 没问题后去掉 --dry-run。

使用 npm link 模拟全局安装

npm link
ai-logger --help
ai-logger install --target codex --scope project --yes --dry-run

调试完成后取消：

npm unlink -g ai-session-logger

使用脚本一键本地调试

# 默认调试 Codex fixture
npm run debug:local

# 指定 Agent
npm run debug:local:codex
npm run debug:local:claude
npm run debug:local:cursor
npm run debug:local:gemini
npm run debug:local:kiro

如果希望真实写入项目级 hook：

npm run debug:local -- --agent codex --install-hooks

打包检查

npm run pack:dry

该命令会触发 prepack，执行构建、语法检查、测试、dist 检查，并进行 npm 包体 dry-run。

删除/卸载本机 CLI 工具

npm uninstall -g ai-session-logger 只会删除 npm 全局安装的包，不会删除源码本地安装或 standalone 安装写入的 ~/.local/bin/ai-logger。

ai-logger delete-cli --dry-run
ai-logger delete-cli --yes

npm run delete:cli:dry
npm run delete:cli -- --yes

npm run uninstall:local:dry
npm run uninstall:local -- --yes

如果还希望先卸载当前项目中由 AI Session Logger 写入的项目级 hook：

npm run delete:cli -- --remove-hooks --yes

发布

npm 发布说明见 PUBLISHING.md。常用命令：

# 建议先登录 npm 官方 registry
npm login --registry=https://registry.npmjs.org/
npm whoami --registry=https://registry.npmjs.org/

# 只做完整发布前检查，不真正发布
npm run deploy:npm:dry

# 正式发布，发布前会再次确认
npm run deploy:npm

# 非交互发布
npm run deploy:npm -- --yes

限制与后续计划

• npm 安装路径仍依赖 Node.js 20+。
• 完全无 Node/npm 的机器请使用 standalone binary。
• 当前 standalone 构建采用 Node SEA，后续也可以评估 Go/Rust 原生实现以进一步减小体积。
• Cursor 当前仍标记为实验性支持，建议通过真实 transcript fixture 持续校准解析器。
• Kiro CLI 当前写入 custom agent hook，无法自动覆盖 Kiro 内置默认 agent；如需记录自定义 agent，请把 hooks block 合并到对应 agent 配置。