feat(zh): add Chinese translations in zh/ directory

Add Chinese (Simplified) translations for all documentation, organized under a dedicated zh/ directory that mirrors the English folder structure. Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com> Translations originally contributed by @tanqingkuang in #45. Restructured from *-CN.md suffix pattern into zh/ directory to prevent the EPUB builder (scripts/build_epub.py collect_folder_files) from picking up Chinese files via glob("*.md") inside module folders.
2026-07-07 11:17:48 +02:00 · 2026-04-06 23:08:54 +02:00
parent 100c45eef2
commit 89e89d4aa3
100 changed files with 20487 additions and 1 deletions
@@ -0,0 +1,640 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../resources/logos/claude-howto-logo-dark.svg">
+  <img alt="Claude How To" src="../resources/logos/claude-howto-logo.svg">
+</picture>
+
+# CLI 参考
+
+## 概览
+
+Claude Code 的 CLI（命令行接口）是与 Claude Code 交互的主要方式。它提供了强大的参数和命令，用于执行查询、管理会话、配置模型，并把 Claude 集成进你的开发工作流。
+
+## 架构
+
+```mermaid
+graph TD
+    A["用户终端"] -->|"claude [options] [query]"| B["Claude Code CLI"]
+    B -->|Interactive| C["REPL 模式"]
+    B -->|"--print"| D["打印模式（SDK）"]
+    B -->|"--resume"| E["恢复会话"]
+    C -->|Conversation| F["Claude API"]
+    D -->|Single Query| F
+    E -->|Load Context| F
+    F -->|Response| G["输出"]
+    G -->|text/json/stream-json| H["终端 / 管道"]
+```
+
+## CLI 命令
+
+| 命令 | 说明 | 示例 |
+|---------|-------------|---------|
+| `claude` | 启动交互式 REPL | `claude` |
+| `claude "query"` | 带初始提示启动 REPL | `claude "解释这个项目"` |
+| `claude -p "query"` | 打印模式，查询后退出 | `claude -p "解释这个函数"` |
+| `cat file \| claude -p "query"` | 处理通过管道传入的内容 | `cat logs.txt \| claude -p "解释这些日志"` |
+| `claude -c` | 继续最近一次会话 | `claude -c` |
+| `claude -c -p "query"` | 在打印模式下继续会话 | `claude -c -p "检查类型错误"` |
+| `claude -r "<session>" "query"` | 通过 ID 或名称恢复会话 | `claude -r "auth-refactor" "完成这个 PR"` |
+| `claude update` | 更新到最新版本 | `claude update` |
+| `claude mcp` | 配置 MCP servers | 见 [MCP 文档](../05-mcp/README.md) |
+| `claude mcp serve` | 将 Claude Code 作为 MCP server 运行 | `claude mcp serve` |
+| `claude agents` | 列出所有已配置的 subagents | `claude agents` |
+| `claude auto-mode defaults` | 以 JSON 打印 auto mode 默认规则 | `claude auto-mode defaults` |
+| `claude remote-control` | 启动远程控制服务 | `claude remote-control` |
+| `claude plugin` | 管理插件（安装、启用、禁用） | `claude plugin install my-plugin` |
+| `claude auth login` | 登录（支持 `--email`、`--sso`） | `claude auth login --email user@example.com` |
+| `claude auth logout` | 注销当前账号 | `claude auth logout` |
+| `claude auth status` | 检查登录状态（已登录返回 0，否则返回 1） | `claude auth status` |
+
+## 核心标志
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `-p, --print` | 不进入交互式模式，直接输出结果 | `claude -p "query"` |
+| `-c, --continue` | 加载最近一次会话 | `claude --continue` |
+| `-r, --resume` | 按 ID 或名称恢复指定会话 | `claude --resume auth-refactor` |
+| `-v, --version` | 输出版本号 | `claude -v` |
+| `-w, --worktree` | 在隔离的 git worktree 中启动 | `claude -w` |
+| `-n, --name` | 设置会话显示名称 | `claude -n "auth-refactor"` |
+| `--from-pr <number>` | 恢复与 GitHub PR 关联的会话 | `claude --from-pr 42` |
+| `--remote "task"` | 在 claude.ai 上创建 web session | `claude --remote "implement API"` |
+| `--remote-control, --rc` | 使用 Remote Control 进入交互式会话 | `claude --rc` |
+| `--teleport` | 将 web session 恢复到本地 | `claude --teleport` |
+| `--teammate-mode` | agent team 显示模式 | `claude --teammate-mode tmux` |
+| `--bare` | 极简模式，跳过 hooks、skills、plugins、MCP、自动记忆和 `CLAUDE.md` | `claude --bare` |
+| `--enable-auto-mode` | 解锁 auto permission mode | `claude --enable-auto-mode` |
+| `--channels` | 订阅 MCP channel 插件 | `claude --channels discord,telegram` |
+| `--chrome` / `--no-chrome` | 启用 / 禁用 Chrome 浏览器集成 | `claude --chrome` |
+| `--effort` | 设置推理强度 | `claude --effort high` |
+| `--init` / `--init-only` | 运行初始化 hooks | `claude --init` |
+| `--maintenance` | 运行维护 hooks 后退出 | `claude --maintenance` |
+| `--disable-slash-commands` | 禁用所有 skills 和 slash commands | `claude --disable-slash-commands` |
+| `--no-session-persistence` | 禁用会话保存（打印模式） | `claude -p --no-session-persistence "query"` |
+
+### 交互模式 vs 打印模式
+
+```mermaid
+graph LR
+    A["claude"] -->|默认| B["交互式 REPL"]
+    A -->|"-p 参数"| C["打印模式"]
+    B -->|特性| D["多轮对话<br>Tab 补全<br>历史记录<br>Slash commands"]
+    C -->|特性| E["单次查询<br>可脚本化<br>可管道化<br>JSON 输出"]
+```
+
+**交互模式**（默认）：
+```bash
+# 启动交互式会话
+claude
+
+# 带初始提示启动
+claude "解释这个认证流程"
+```
+
+**打印模式**（非交互式）：
+```bash
+# 单次查询后退出
+claude -p "这个函数做什么？"
+
+# 处理文件内容
+cat error.log | claude -p "解释这个错误"
+
+# 与其他工具串联
+claude -p "列出待办事项" | grep "URGENT"
+```
+
+## 模型与配置
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--model` | 设置模型（sonnet、opus、haiku，或完整模型名） | `claude --model opus` |
+| `--fallback-model` | 当前模型负载过高时自动切换的后备模型 | `claude -p --fallback-model sonnet "query"` |
+| `--agent` | 为当前会话指定 agent | `claude --agent my-custom-agent` |
+| `--agents` | 通过 JSON 定义自定义 subagents | 见 [Agents Configuration](#subagents-配置) |
+| `--effort` | 设置推理级别（low、medium、high、max） | `claude --effort high` |
+
+### 模型选择示例
+
+```bash
+# 复杂任务使用 Opus 4.6
+claude --model opus "设计一个缓存策略"
+
+# 快速任务使用 Haiku 4.5
+claude --model haiku -p "格式化这个 JSON"
+
+# 使用完整模型名
+claude --model claude-sonnet-4-6-20250929 "审查这段代码"
+
+# 带后备模型以提升稳定性
+claude -p --model opus --fallback-model sonnet "分析架构"
+
+# 使用 opusplan（Opus 负责规划，Sonnet 负责执行）
+claude --model opusplan "设计并实现缓存层"
+```
+
+## 系统提示词自定义
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--system-prompt` | 替换整段默认系统提示词 | `claude --system-prompt "You are a Python expert"` |
+| `--system-prompt-file` | 从文件加载提示词（仅打印模式） | `claude -p --system-prompt-file ./prompt.txt "query"` |
+| `--append-system-prompt` | 在默认提示词后追加内容 | `claude --append-system-prompt "Always use TypeScript"` |
+
+### 系统提示词示例
+
+```bash
+# 完整自定义人格
+claude --system-prompt "你是一名资深安全工程师，重点关注漏洞。"
+
+# 追加特定指令
+claude --append-system-prompt "始终在代码示例中包含单元测试"
+
+# 从文件加载复杂提示词
+claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py"
+```
+
+### 系统提示词参数对比
+
+| 参数 | 行为 | 交互模式 | 打印模式 |
+|------|----------|-------------|-------|
+| `--system-prompt` | 替换整个默认系统提示词 | ✅ | ✅ |
+| `--system-prompt-file` | 用文件中的提示词替换 | ❌ | ✅ |
+| `--append-system-prompt` | 追加到默认系统提示词后 | ✅ | ✅ |
+
+**仅在打印模式中使用 `--system-prompt-file`。交互模式请使用 `--system-prompt` 或 `--append-system-prompt`。**
+
+## 工具与权限管理
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--tools` | 限制可用的内置工具 | `claude -p --tools "Bash,Edit,Read" "query"` |
+| `--allowedTools` | 无需提示即可执行的工具 | `"Bash(git log:*)" "Read"` |
+| `--disallowedTools` | 从上下文中移除的工具 | `"Bash(rm:*)" "Edit"` |
+| `--dangerously-skip-permissions` | 跳过所有权限提示 | `claude --dangerously-skip-permissions` |
+| `--permission-mode` | 以指定权限模式启动 | `claude --permission-mode auto` |
+| `--permission-prompt-tool` | 用于权限处理的 MCP tool | `claude -p --permission-prompt-tool mcp_auth "query"` |
+| `--enable-auto-mode` | 解锁 auto permission mode | `claude --enable-auto-mode` |
+
+### 权限示例
+
+```bash
+# 代码审查只读模式
+claude --permission-mode plan "审查这个代码库"
+
+# 只允许安全工具
+claude --tools "Read,Grep,Glob" -p "找出所有 TODO 注释"
+
+# 允许特定 git 命令无需提示
+claude --allowedTools "Bash(git status:*)" "Bash(git log:*)"
+
+# 阻止危险操作
+claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"
+```
+
+## 输出与格式
+
+| 参数 | 说明 | 选项 | 示例 |
+|------|-------------|---------|---------|
+| `--output-format` | 指定输出格式（打印模式） | `text`、`json`、`stream-json` | `claude -p --output-format json "query"` |
+| `--input-format` | 指定输入格式（打印模式） | `text`、`stream-json` | `claude -p --input-format stream-json` |
+| `--verbose` | 启用详细日志 |  | `claude --verbose` |
+| `--include-partial-messages` | 包含流式事件 | 需要 `stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` |
+| `--json-schema` | 获取符合 schema 的 JSON 输出 |  | `claude -p --json-schema '{"type":"object"}' "query"` |
+| `--max-budget-usd` | 打印模式最大花费 |  | `claude -p --max-budget-usd 5.00 "query"` |
+
+### 输出格式示例
+
+```bash
+# 纯文本（默认）
+claude -p "解释这段代码"
+
+# 供程序使用的 JSON
+claude -p --output-format json "列出 main.py 中的所有函数"
+
+# 用于实时处理的流式 JSON
+claude -p --output-format stream-json "生成一份长报告"
+
+# 使用 schema 验证的结构化输出
+claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \
+  "找出这段代码中的 bug，并以 JSON 返回"
+```
+
+## 工作区与目录
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--working-directory` | 设置工作目录 | `claude --working-directory /path/to/project` |
+| `--add-dir` | 追加额外工作目录 | `claude --add-dir /path/to/other/project` |
+
+### 多目录示例
+
+```bash
+# 在多个项目目录中协作
+claude --working-directory ~/projects/app --add-dir ~/projects/shared
+
+# 加载自定义设置
+claude --working-directory ./backend --add-dir ./frontend
+```
+
+## MCP 配置
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--mcp-config` | 从文件加载 MCP 配置 | `claude --mcp-config ./mcp.json` |
+| `--mcp` | 启用 / 配置 MCP 服务 | `claude --mcp github` |
+| `--mcp-list` | 列出可用 MCP 配置 | `claude --mcp-list` |
+
+### MCP 示例
+
+```bash
+# 加载 GitHub MCP server
+claude --mcp-config ./configs/github-mcp.json
+
+# 严格模式，只允许指定的 server
+claude --mcp-config ./configs/strict-mcp.json --mcp github
+```
+
+## 会话管理
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--session` | 指定会话名称 | `claude --session feature-auth` |
+| `--new-session` | 强制开启新会话 | `claude --new-session` |
+| `--resume-last` | 恢复最近一次会话 | `claude --resume-last` |
+| `--fork-session` | 从当前会话分叉 | `claude --fork-session` |
+
+### 会话示例
+
+```bash
+# 继续上一次对话
+claude --continue
+
+# 恢复命名会话
+claude --resume feature-auth
+
+# 为实验分叉会话
+claude --fork-session
+
+# 指定会话 ID
+claude --resume 123456789
+```
+
+### 会话分叉
+
+```bash
+# 分叉会话尝试不同方案
+claude --fork-session "尝试另一种实现"
+
+# 带自定义消息分叉
+claude --fork-session --session "experiment-a"
+```
+
+## 高级特性
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--disable-auto-checkpoints` | 禁用自动 checkpoint | `claude --disable-auto-checkpoints` |
+| `--enable-auto-checkpoints` | 启用自动 checkpoint | `claude --enable-auto-checkpoints` |
+| `--interactive` | 强制交互模式 | `claude --interactive` |
+| `--dry-run` | 仅模拟执行 | `claude --dry-run "review code"` |
+| `--unsafe` | 允许更多自动化操作 | `claude --unsafe` |
+
+### 高级示例
+
+```bash
+# 限制自主操作
+claude --permission-mode plan --model opus "设计并实现认证系统"
+
+# 调试 API 调用
+claude --verbose -p "diagnose this issue"
+
+# 启用 IDE 集成
+claude --ide "review this diff"
+```
+
+<a id="agents-configuration"></a>
+## Subagents 配置
+
+| 参数 | 说明 | 示例 |
+|------|-------------|---------|
+| `--agents` | 通过 JSON 定义自定义 subagents | `claude --agents ./agents.json` |
+| `--agent` | 指定当前会话使用的 agent | `claude --agent reviewer` |
+
+### Subagents JSON 格式
+
+```json
+{
+  "agent-name": {
+    "description": "Required: when to invoke this agent",
+    "prompt": "Required: system prompt for the agent",
+    "tools": ["Optional", "array", "of", "tools"],
+    "model": "optional: sonnet|opus|haiku"
+  }
+}
+```
+
+**必填字段：**
+- `description` - 何时使用这个 agent 的自然语言说明
+- `prompt` - 定义 agent 角色和行为的系统提示词
+
+**可选字段：**
+- `tools` - 可用工具数组（如果省略则继承全部工具）
+  - 格式：`["Read", "Grep", "Glob", "Bash"]`
+- `model` - 使用的模型：`sonnet`、`opus` 或 `haiku`
+
+### 完整 Agents 示例
+
+```json
+{
+  "code-reviewer": {
+    "description": "Expert code reviewer. Use proactively after code changes.",
+    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
+    "tools": ["Read", "Grep", "Glob", "Bash"],
+    "model": "sonnet"
+  },
+  "debugger": {
+    "description": "Debugging specialist for errors and test failures.",
+    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",
+    "tools": ["Read", "Edit", "Bash", "Grep"],
+    "model": "opus"
+  },
+  "documenter": {
+    "description": "Documentation specialist for generating guides.",
+    "prompt": "You are a technical writer. Create clear, comprehensive documentation.",
+    "tools": ["Read", "Write"],
+    "model": "haiku"
+  }
+}
+```
+
+### Agents 命令示例
+
+```bash
+# 直接定义自定义 agent
+claude --agents '{
+  "security-auditor": {
+    "description": "Security specialist for vulnerability analysis",
+    "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.",
+    "tools": ["Read", "Grep", "Glob"],
+    "model": "opus"
+  }
+}' "audit this codebase for security issues"
+
+# 从文件加载 agents
+claude --agents ./configs/agents.json
+
+# 与其他参数组合
+claude --agents ./configs/agents.json --model opus
+```
+
+### Subagent 优先级
+
+当同时存在多种 agent 定义时，加载优先级如下：
+1. **CLI 定义**（`--agents` 参数）- 当前会话专用
+2. **用户级**（`~/.claude/agents/`）- 所有项目可用
+3. **项目级**（`.claude/agents/`）- 当前项目可用
+
+命令行定义的 agents 会覆盖本次会话里的用户级和项目级 agents。
+
+## 高价值使用场景
+
+### 1. CI/CD 集成
+
+```bash
+claude -p --output-format json "run tests and summarize failures"
+```
+
+### 2. 管道式脚本处理
+
+```bash
+# 分析错误日志
+cat error.log | claude -p "解释这些错误并给出修复建议"
+
+# 查找访问日志中的模式
+cat access.log | claude -p "找出异常流量"
+
+# 分析 git 历史
+git log --oneline -20 | claude -p "总结最近的开发方向"
+
+# 审查某个文件
+claude -p "review src/app.ts and suggest improvements"
+
+# 生成文档
+claude -p "根据 README 生成 API 文档"
+
+# 查找 TODO 并排优先级
+rg -n "TODO|FIXME" . | claude -p "按优先级分类这些待办"
+```
+
+### 3. 多会话工作流
+
+```bash
+# 启动特性分支会话
+claude --session feature-auth
+
+# 之后继续该会话
+claude --resume feature-auth
+
+# 分叉尝试另一种方案
+claude --fork-session
+
+# 在不同特性会话之间切换
+claude --resume feature-auth
+claude --resume feature-payment
+```
+
+### 4. 自定义 agent 配置
+
+```bash
+# 将 agents 配置保存到文件
+cat > agents.json <<'JSON'
+{
+  "agents": [
+    {"name":"reviewer","description":"review code"},
+    {"name":"tester","description":"write tests"}
+  ]
+}
+JSON
+
+# 在会话中使用这些 agent
+claude --agents ./agents.json --agent reviewer
+```
+
+### 5. 批处理
+
+```bash
+# 处理多个文件
+find src -name "*.ts" | xargs -I{} claude -p "review {}"
+
+# 批量代码审查
+claude -p "review all changes in this branch"
+
+# 为所有模块生成测试
+claude -p "generate tests for the modified modules"
+```
+
+### 6. 安全敏感开发
+
+```bash
+# 只读安全审计
+claude --permission-mode plan -p "audit this repository"
+
+# 阻止危险命令
+claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)"
+
+# 限制自动化
+claude --tools "Read,Grep,Glob" -p "inspect the codebase"
+```
+
+### 7. JSON API 集成
+
+```bash
+# 获取结构化分析结果
+claude -p --output-format json "analyze this code and return findings"
+
+# 配合 jq 处理
+claude -p --output-format json "list functions" | jq '.functions[]'
+
+# 在脚本中使用
+result=$(claude -p --output-format json "summarize changes")
+```
+
+### jq 解析示例
+
+```bash
+# 提取特定字段
+claude -p --output-format json "analyze repo" | jq '.summary'
+
+# 过滤数组元素
+claude -p --output-format json "find bugs" | jq '.bugs[] | select(.severity=="high")'
+
+# 提取多个字段
+claude -p --output-format json "analyze" | jq '{summary, risk, recommendations}'
+
+# 转成 CSV
+claude -p --output-format json "list files" | jq -r '.files[] | [.name, .size] | @csv'
+
+# 条件处理
+claude -p --output-format json "check status" | jq 'if .ok then "pass" else "fail" end'
+
+# 提取嵌套值
+claude -p --output-format json "inspect" | jq '.details.metrics.coverage'
+
+# 处理整个数组
+claude -p --output-format json "find todos" | jq '.todos | length'
+
+# 转换输出
+claude -p --output-format json "review" | jq '{issues: [.issues[] | {file, line, message}]}'
+```
+
+## 模型
+
+### 模型选择
+
+```bash
+# 使用短名称
+claude --model sonnet
+claude --model opus
+claude --model haiku
+
+# 使用 opusplan 别名（Opus 负责规划，Sonnet 负责执行）
+claude --model opusplan "design and implement the caching layer"
+
+# 会话中切换快速模式
+claude --model haiku --effort low
+```
+
+### Effort 级别（Opus 4.6）
+
+```bash
+# 通过 CLI 参数设置 effort
+claude --model opus --effort high "design the architecture"
+
+# 通过 slash command 设置 effort
+/effort max
+
+# 通过环境变量设置 effort
+CLAUDE_EFFORT=medium claude --model opus
+```
+
+## 常用环境变量
+
+| 环境变量 | 说明 |
+|----------|------|
+| `ANTHROPIC_API_KEY` | API key |
+| `CLAUDE_MODEL` | 默认模型 |
+| `CLAUDE_EFFORT` | 默认推理强度 |
+| `CLAUDE_WORKING_DIRECTORY` | 默认工作目录 |
+| `CLAUDE_OUTPUT_FORMAT` | 默认输出格式 |
+| `CLAUDE_MCP_CONFIG` | 默认 MCP 配置 |
+
+## 快速参考
+
+### 最常用命令
+
+```bash
+# 交互式会话
+claude
+
+# 快速提问
+claude -p "explain this repo"
+
+# 继续上次对话
+claude -c
+
+# 处理某个文件
+claude -p "review README.md"
+
+# 为脚本输出 JSON
+claude -p --output-format json "list all classes"
+```
+
+### 参数组合
+
+```bash
+# 只读审查
+claude --permission-mode plan -p "review this codebase"
+
+# 高级模型 + JSON 输出
+claude --model opus -p --output-format json "analyze architecture"
+
+# 自定义工作目录 + MCP
+claude --working-directory ./backend --mcp-config ./mcp.json
+```
+
+## 故障排查
+
+### 找不到命令
+
+- 确认 `claude` 已安装并在 `PATH` 中
+- 重新打开终端
+- 检查是否需要重新登录或更新版本
+
+### API Key 问题
+
+- 检查 `ANTHROPIC_API_KEY`
+- 确认 key 未过期
+- 检查网络是否可访问 API
+
+### 找不到会话
+
+- 确认会话名称或 ID 正确
+- 先运行 `claude --list-sessions`（如果你的版本支持）
+- 检查当前账号是否一致
+
+### 输出格式问题
+
+- 使用 `--output-format json` 时确保输出可被解析
+- 如果是流式输出，加入 `--include-partial-messages`
+
+### 权限被拒绝
+
+- 检查 `--permission-mode`
+- 检查 `--allowedTools` 和 `--disallowedTools`
+- 如有必要，明确允许所需工具
+
+## 更多资源
+
+- [根目录中文指南](../README.md)
+- [Slash Commands 中文参考](../01-slash-commands/README.md)
+- [MCP 文档](../05-mcp/README.md)
+- [Claude Code 官方 CLI 文档](https://code.claude.com/docs/en/cli-reference)