# Claude Code 内部机制 学习笔记
> **Session 背景**：设计了 `/exit-learn` command（session 知识萃取→Obsidian 图文笔记）和 `session-learn.sh`（处理历史 session 的独立子进程方案）
> **新知识点**：3 个
---
## 一、Claude Code Commands 机制
**是什么**：`/exit-learn`、`/code-review` 等斜杠命令，本质是 `~/.claude/commands/` 目录下的 Markdown 文件。
**核心机制**：
| 问题 | 技术回答 | 小白秒懂版 |
|------|----------|-----------|
| /command 是什么？ | `~/.claude/commands/<name>.md` 文件内容注入为 prompt | 配方书：文件名=菜名，内容=做法 |
| Claude 怎么执行？ | 读取 .md 文件内容作为指令，按 Step by Step 执行 | 厨师照着配方做菜 |
| Skills 和 Commands 的区别？ | Skills 有独立目录+脚本，Commands 是纯 Markdown prompt | Skills=程序，Commands=说明书 |
**口诀**：Markdown 即 Prompt，放进 commands/ 目录即成斜杠命令。
> 图解待补充：`assets/ClaudeCode命令机制_手绘白板_0.png`（OpenRouter 网络异常未生成）
**与已知的关联**：类似 ChatGPT 的 Custom Instructions，但更灵活——文件即命令，可以版本控制、共享、组合调用。本质是 prompt engineering 的工程化封装。
---
## 二、Claude Code Session JSONL 存储结构
**是什么**：Claude Code 的每次对话（session）以 JSONL 格式持久化存储，可被外部脚本读取和分析。
**存储路径**：
```
~/.claude/projects/<项目目录编码>/<session-id>.jsonl
```
- 项目目录编码：把路径中 `/` 替换为 `-`（如 `/Users/foo/bar` → `-Users-foo-bar`）
- 子 agent 对话存在 `<session-id>/subagents/` 子目录
**关键字段**：
| 字段 | 含义 | 过滤方式 |
|------|------|---------|
| `type` | 消息类型 | 只取 `"user"` 和 `"assistant"` |
| `isSidechain` | 是否为子 agent 消息 | `false` = 主对话，`true` 过滤掉 |
| `message.content` | 消息内容 | string 直接用；list 时取 `type="text"` 的块，跳过 `type="thinking"` |
**Python 解析模板**：
```python
with open(jsonl_file) as f:
for line in f:
obj = json.loads(line)
if obj.get('isSidechain'): continue
if obj.get('type') not in ('user', 'assistant'): continue
content = obj['message']['content']
if isinstance(content, list):
text = ' '.join(c.get('text','') for c in content
if isinstance(c,dict) and c.get('type')=='text')
else:
text = content
```
**口诀**：type=user/assistant + isSidechain=false = 主对话；content 是 list 时只取 type=text 块。
> 图解待补充：`assets/ClaudeCode-Session存储_手绘白板_0.png`（OpenRouter 网络异常未生成）
**与已知的关联**：类似 Jupyter Notebook 的 `.ipynb` 格式（也是 JSON，每个 cell 一条记录）。JSONL（每行一个 JSON）是大数据场景的标准格式，LLM 系统喜欢用它做日志——可追加写入，流式读取。
---
## 三、`claude --print` 非交互模式
**是什么**：Claude Code CLI 的批处理模式，适合脚本自动化调用。
**核心机制**：
| 问题 | 技术回答 | 小白秒懂版 |
|------|----------|-----------|
| 怎么用？ | `claude --print --allowedTools "Bash,Read,Write" < prompt.txt` | 把 prompt 文件喂给 claude，结果吐到 stdout |
| 和交互模式有什么区别？ | 无 TUI，无上下文保留，每次独立执行 | 交互=对话，--print=一次性执行脚本 |
| 认证怎么处理？ | `env -u ANTHROPIC_API_KEY claude ...` 移除 API key，使用 Pro 订阅 | 用会员卡进场，不用现金付费 |
**完整调用模式**：
```bash
PROMPT_FILE=$(mktemp)
echo "$PROMPT" > "$PROMPT_FILE"
env -u ANTHROPIC_API_KEY claude \
--print \
--allowedTools "Bash,Read,Write,Glob,Grep" \
< "$PROMPT_FILE"
rm -f "$PROMPT_FILE"
```
**口诀**：`--print` = 无人值守批处理；stdin 喂 prompt，stdout 收结果。
> 图解待补充（网络异常）
**与已知的关联**：类似 `python script.py` 非交互运行脚本。结合 `env -u` 移除 API key 的设计，对应 CLAUDE.md 中已有的「Hook 启动 Agent 规范」——本质是同一套认证隔离思路。
---
## 总结
| 知识点 | 核心要点 | 记忆口诀 | 领域 |
|--------|----------|----------|------|
| Commands 机制 | Markdown 文件 = slash command | 文件即命令 | Claude Code |
| Session JSONL 存储 | `~/.claude/projects/` + JSONL格式，过滤 isSidechain | type+isSidechain双过滤 | Claude Code |
| `--print` 非交互模式 | stdin→prompt，stdout→结果，env -u 去 API key | 无人值守批处理 | Claude Code |
**本次 session 最大收获**：Claude Code 的内部存储是完全可编程的——session 是可读的 JSONL，commands 是可写的 Markdown，整个工具链可以被自动化脚本深度集成。
---
> ⚠️ 图解因 OpenRouter 网络异常未能生成，可补充运行：
> ```bash
> cd ~/.claude/skills/api-draw
> python scripts/nanobanana_draw.py "..." --style "手绘白板" --subject "ClaudeCode命令机制" --save-dir "/Users/liuyishou/usr/odyssey/0 收集箱/assets/"
> ```