ai-code-sessions 完整指南#

# 方式 1：uvx 直接运行（无需安装，推荐）
uvx ai-code-sessions

# 方式 2：pip 安装
pip install ai-code-sessions

# 方式 3：pipx 安装（隔离环境）
pipx install ai-code-sessions

# 方式 4：uv 工具安装
uv tool install ai-code-sessions

# 验证安装
ais --help

# 交互式选择并导出本地会话
ais local

# 限制显示数量
ais local --limit 20

# 导出所有会话为 HTML 归档
ais all -o ./archive --open

# 转换指定的 JSONL 文件
ais json path/to/session.jsonl -o ./output

# 转换并附带标签和 GitHub 提交链接
ais json session.jsonl -o ./output --label "修复登录 Bug" --repo owner/repo --open

# 在输出目录中包含原始 JSON 文件
ais json session.jsonl -o ./output --json

# 导出并上传到 GitHub Gist
ais local --gist

# 运行 Claude 并自动导出
ais ctx claude "修复数据库连接池"

# 运行 Codex 并自动导出
ais ctx codex "重构认证模块"

# 导出后自动打开浏览器
ais ctx claude "调试内存泄漏" --open

# 同时生成变更日志
ais ctx claude "添加用户认证" --changelog

# 指定 GitHub 仓库（用于提交链接）
ais ctx claude "修复 Bug" --repo owner/repo --changelog --open

# 交互式选择之前的 Claude 会话恢复
ais ctx claude --resume

# 交互式选择之前的 Codex 会话恢复
ais ctx codex --resume

# 从列表中选择恢复
ais ctx codex --resume --pick

# 恢复特定会话（按 ID）
ais ctx claude --resume --session-id <id> "继续调试"

# 直接恢复最新的会话
ais ctx-resume claude --latest

# 限制显示数量
ais ctx-resume claude --limit 20

# 在当前 git 仓库生成归档
ais archive

# 指定项目根目录
ais archive --project-root /path/to/repo

# 指定输出目录并打开
ais archive -o ./my-archive --open

# 为已导出但未生成 changelog 的会话补充
ais changelog backfill

# 指定项目根目录
ais changelog backfill --project-root "$(git rev-parse --show-toplevel)"

# 使用 Claude 作为评估器
ais changelog backfill --evaluator claude --max-concurrency 5

# 覆盖作者
ais changelog backfill --actor your-github-username

# 查看某个日期之后的变更
ais changelog since 2026-02-01

# 支持自然语言日期
ais changelog since yesterday
ais changelog since "3 days ago"

# 按 Git 提交查询
ais changelog since HEAD~10

# 输出为 JSON 格式
ais changelog since 2026-01-15 --format json

# 按工具过滤
ais changelog since 2026-01-15 --tool codex

# 按标签过滤
ais changelog since 2026-01-15 --tag feat --tag fix

# 检查 changelog 质量
ais changelog lint

# 自动修复有问题的条目
ais changelog lint --fix

# 预览修复但不实际更改
ais changelog lint --fix --dry-run

# 重新计算 touched_files、tests、commits 等元数据
ais changelog refresh-metadata --project-root "$(git rev-parse --show-toplevel)"

# 刷新所有条目（默认仅刷新空的）
ais changelog refresh-metadata --all

# 预览更改
ais changelog refresh-metadata --dry-run

# 手动查找匹配的原始会话日志
ais find-source codex "$PWD" "$(git rev-parse --show-toplevel)"

# 如果匹配错误，用正确的文件重新导出
ais json <correct-file> -o <output-dir>

# 完整设置向导
ais setup

# 跳过全局配置
ais setup --skip-global

# 跳过项目配置
ais setup --skip-repo

# 覆盖已有配置
ais setup --overwrite

ais all [OPTIONS]

选项：
  --source PATH       Claude Code projects 目录（默认 ~/.claude/projects）
  -o, --output PATH   输出目录（必填）
  --include-agents    包含 agent-* 会话文件（默认排除）
  --dry-run           预览模式，不创建文件
  --open              导出后在浏览器中打开
  --gist              上传到 GitHub Gist
  -q, --quiet         静默模式

ais ctx [codex|claude] [OPTIONS] [LABEL]

选项：
  --resume                  恢复之前的会话
  --pick                    从列表中选择恢复（配合 --resume）
  --session-id TEXT         指定恢复的会话 ID（配合 --resume）
  --tz TEXT                 时区（默认 America/Los_Angeles）
  --repo TEXT               GitHub 仓库（owner/name），用于提交链接
  --open                    导出后打开 index.html
  --changelog               导出后追加变更日志条目
  --changelog-evaluator     变更日志评估器（codex/claude）
  --changelog-actor TEXT    覆盖变更日志中的 actor
  --changelog-model TEXT    覆盖变更日志评估模型

ais json <FILE> [OPTIONS]

选项：
  -o, --output PATH   输出目录（必填）
  --label TEXT        转录标题中显示的标签
  --repo TEXT         GitHub 仓库（owner/name），用于提交链接
  --json              在输出目录中包含原始会话文件
  --open              生成后在浏览器中打开
  --gist              上传到 GitHub Gist

# 单级详细日志
ais -v local

# 双级详细日志
ais -vv local

# 输出到日志文件
ais --log-file ./debug.log local

[ctx]
tz = "Asia/Shanghai"                 # 会话文件夹名的时区

[changelog]
enabled = true                       # 启用 changelog 生成
actor = "your-github-username"       # changelog 中的署名
evaluator = "codex"                  # "codex" 或 "claude"
model = ""                           # 留空使用工具默认值
claude_thinking_tokens = 8192        # Claude 评估器专用设置

.changelog/
└── your-username/
    ├── entries.jsonl      # 成功的 changelog 条目（追加写入）
    └── failures.jsonl     # 失败的生成尝试（用于调试）

.codex/sessions/2026-01-02-1435_fix-auth-race-condition/
├── index.html          # 提示时间线 + 统计信息
├── page-001.html       # 前 5 个对话
├── page-002.html       # 后续对话（每页 5 个）
├── source_match.json   # 源文件匹配信息
└── session.jsonl       # 原始日志（归档）

# 用 ctx 启动每个开发任务，自动记录和导出
ais ctx claude "添加用户认证功能" --changelog --open

# 任务完成后，changelog 自动生成
# 转录自动保存到 .claude/sessions/

# 恢复最近的 Claude 会话
ais ctx claude --resume

# 或从列表中选择
ais ctx codex --resume --pick

# 用 Claude 做架构设计
ais ctx claude "设计微服务架构" --changelog

# 用 Codex 做具体实现
ais ctx codex "实现用户服务 API" --changelog

# 统一归档
ais archive --open

# 查看本周所有 AI 辅助变更
ais changelog since "1 week ago" --format table

# 按成员过滤
ais changelog since 2026-02-01 --actor alice

# 按标签过滤
ais changelog since 2026-02-01 --tag feat --tag fix

# 导出为 JSON 供其他工具消费
ais changelog since 2026-02-01 --format json > weekly-report.json

# 在项目根目录生成所有 AI 会话的归档
cd /path/to/my-project
ais archive --open

# 指定输出目录
ais archive -o ./ai-sessions-archive --open

# 开启详细日志排查问题
ais -vv all -o ./debug-archive --log-file ./debug.log

# 检查源文件匹配结果
Get-Content .codex/sessions/*/source_match.json | ConvertFrom-Json

# 用正确的文件重新导出
ais json <correct-file> -o <output-dir> --label "重新导出"

# 启用 changelog 后，为之前的会话补充生成
ais changelog backfill

# 使用 Claude 评估器获得更详细的分析
ais changelog backfill --evaluator claude --max-concurrency 5

# 检查质量
ais changelog lint

# 自动修复有问题的条目
ais changelog lint --fix

# 导出并上传到 Gist（需要 gh CLI 已认证）
ais local --gist

# 或从 JSONL 文件
ais json session.jsonl -o ./output --gist

Exit code 2
Usage: ai-code-sessions config [OPTIONS] COMMAND [ARGS]...

# ✅ 正确
ais config show

# ❌ 错误
ais config

# 检查是否在 git 仓库中
git rev-parse --show-toplevel

# 手动指定项目根目录
ais archive --project-root D:\Documents\IDE\202602

# 命令行参数
ais ctx claude "我的任务" --changelog --changelog-evaluator claude

# 或设置环境变量
$env:CTX_CHANGELOG_EVALUATOR = "claude"
ais ctx claude "我的任务" --changelog

# 或写入配置文件
# .ai-code-sessions.toml
# [changelog]
# evaluator = "claude"

Get-Content .codex/sessions/*/source_match.json

# 如果匹配错误，用正确的文件重新导出
ais json <correct-file> -o <output-dir>

# 安装 gh
winget install GitHub.cli

# 认证
gh auth login

# 然后就可以使用 --gist
ais local --gist

# 方式 1：环境变量
$env:CTX_TZ = "Asia/Shanghai"

# 方式 2：配置文件（推荐）
# 运行 ais setup 或手动编辑 %APPDATA%\ai-code-sessions\config.toml
# [ctx]
# tz = "Asia/Shanghai"