常见问题与踩坑记录#

实际使用中遇到的问题和解决方案。

1. uvx 命令不可用#

报错：

uvx: The term 'uvx' is not recognized as a name of a cmdlet, function,
script file, or executable program.

原因： 系统未安装 uv 包管理器。uvx 是 uv 提供的命令，用于直接运行 Python 包而无需安装。

解决：

# 安装 uv（PowerShell）
irm https://astral.sh/uv/install.ps1 | iex

# 安装后重启终端
uvx claude-code-transcripts

替代方案（不装 uv）：

# 用 pip 安装后直接使用命令
pip install claude-conversation-extractor
claude-extract --list

# 或用 pipx
pipx run claude-code-transcripts

2. PowerShell 与 Bash 命令差异#

Claude Code 内部使用 Bash 执行命令，但用户终端可能是 PowerShell。常见差异：

操作	Bash（Claude Code 内部）	PowerShell（用户终端）
列出文件	`ls -lht`	`Get-ChildItem \| Sort-Object LastWriteTime -Descending`
查看文件	`cat file.txt`	`Get-Content file.txt`
搜索文本	`grep "keyword" file`	`Select-String "keyword" file`
管道过滤	`\| head -10`	`\| Select-Object -First 10`
打开文件	`open file.html`	`start file.html`
环境变量	`echo $HOME`	`echo $env:USERPROFILE`

踩坑示例：

# ❌ 在 PowerShell 中使用 Bash 语法会报错
ls -lht "C:/Users/AI-Olne/.claude/transcripts/"
# Get-ChildItem: A parameter cannot be found that matches parameter name 'lht'.

# ✅ 正确的 PowerShell 写法
Get-ChildItem "C:\Users\AI-Olne\.claude\transcripts\" |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 10

3. 交互式界面操作错误#

claude-search 搜索后无法导出#

问题： 使用 claude-search "AI 识图" 搜索后，在选项界面直接输入会话 ID 或编号，提示 Invalid choice。

原因： 交互式界面需要先选择操作类型，再输入具体编号。

正确操作流程：

Options:
  V. VIEW a conversation       ← 查看（不导出文件）
  E. EXTRACT all conversations ← 导出所有搜索结果
  Q. QUIT

# ❌ 错误：直接输入编号或会话 ID
Your choice: 5                 → Invalid choice

# ✅ 正确：先输入 V，再输入编号
Your choice: V
Enter conversation number: 5   → 查看第 5 个搜索结果

V（查看）不会导出文件#

选项	行为	是否生成文件
`V`	在终端中显示会话内容	❌ 不生成文件
`E`	导出所有搜索结果	✅ 导出到 `Desktop\Claude logs`

推荐：用命令行替代交互式界面#

交互式界面在某些环境下不稳定，推荐直接使用命令行参数：

# 替代 claude-search "关键词"
claude-extract --search "关键词" --output ./search-results

# 替代 claude-start 交互式选择
claude-extract --extract 1,2,3 --output ./my-export

# 替代交互式界面的 S 选择
claude-extract --extract 47 --format html --output ./session-47

4. ai-code-sessions 与 claude-code-transcripts 导出结果一样#

问题： 两款工具的基础 HTML 导出看起来完全一样。

原因： ai-code-sessions 是 claude-code-transcripts 的 fork，基础的 local 和 all 命令确实输出相同的 HTML。

区别在于额外功能：

ctx — 会话包装器（运行 AI 工具并自动导出）
ctx-resume — 恢复历史会话
archive — 项目级归档（扫描 .codex/.claude）
changelog — 变更日志管理
Codex 支持
日志级别控制（-v / -vv / --log-file）

如果只用基础导出功能，两者没有区别。

5. ai-code-sessions config 直接运行报错#

报错：

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

原因： config 是一个命令组，需要加子命令。

正确用法：

# ✅ 查看配置
uvx ai-code-sessions config show

# ❌ 不能直接运行
uvx ai-code-sessions config

6. 导出时部分会话被跳过#

现象：

📤 Extracting 5 session(s) as MARKDOWN...
⏭️  Skipped session 12 (no conversation)
✅ 1/5: claude-conversation-2026-02-14-eed2fa49.md (22 messages)
⏭️  Skipped session 15 (no conversation)

原因： 某些会话可能只包含系统消息或命令输出，没有实际的用户/助手对话内容。

解决： 这是正常行为。如果需要查看原始数据，可以直接读取 JSONL 文件：

Get-Content "~\.claude\projects\<项目路径>\<session-id>.jsonl" | Select-Object -First 20

7. 搜索提示安装 spacy#

提示：

Note: Install spacy for enhanced semantic search capabilities
      pip install spacy && python -m spacy download en_core_web_sm

说明： 这只是一个可选增强提示，不安装也能正常搜索。安装后可以获得语义搜索能力（理解同义词等）。

安装（可选）：

pip install spacy
python -m spacy download en_core_web_sm

8. 默认输出目录#

各工具的默认输出位置不同：

工具/命令	默认输出位置
`claude-extract`（交互式）	`C:\Users\<用户名>\Desktop\Claude logs`
`claude-extract --output`	自定义位置
`claude-code-transcripts all`	`./claude-archive`
`ai-code-sessions all`	必须指定 `-o` 参数
`ai-code-sessions archive`	`<project_root>/.ais-archive`

9. ai-code-sessions 环境变量#

ai-code-sessions 支持通过环境变量配置：

环境变量	说明	默认值
`AI_CODE_SESSIONS_LOG_DIR`	日志文件目录	—
`CTX_TZ`	时区	`America/Los_Angeles`
`CTX_CHANGELOG_EVALUATOR`	变更日志评估器	`codex`
`AI_CODE_SESSIONS_CHANGELOG_EVALUATOR`	同上（别名）	`codex`
`CTX_CHANGELOG_MODEL`	变更日志评估模型	—
`AI_CODE_SESSIONS_CHANGELOG_MODEL`	同上（别名）	—