{"id":51031770,"url":"https://github.com/tytsxai/claude-code-guide-zh","last_synced_at":"2026-06-22T01:01:44.862Z","repository":{"id":361709733,"uuid":"1255479703","full_name":"tytsxai/claude-code-guide-zh","owner":"tytsxai","description":"Cranot/claude-code-guide 的中文同步翻译版 · 自动追踪上游 + DeepSeek 翻译 | Auto-synced Chinese mirror of the Claude Code guide","archived":false,"fork":false,"pushed_at":"2026-05-31T22:24:23.000Z","size":111,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T00:13:27.215Z","etag":null,"topics":["agentic-coding","ai","anthropic","chinese","claude","claude-code","deepseek","documentation","github-actions","i18n","llm","localization","mcp","translation","zh-cn"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tytsxai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T21:57:03.000Z","updated_at":"2026-05-31T22:24:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tytsxai/claude-code-guide-zh","commit_stats":null,"previous_names":["tytsxai/claude-code-guide-zh"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tytsxai/claude-code-guide-zh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fclaude-code-guide-zh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fclaude-code-guide-zh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fclaude-code-guide-zh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fclaude-code-guide-zh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tytsxai","download_url":"https://codeload.github.com/tytsxai/claude-code-guide-zh/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tytsxai%2Fclaude-code-guide-zh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34630753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai","anthropic","chinese","claude","claude-code","deepseek","documentation","github-actions","i18n","llm","localization","mcp","translation","zh-cn"],"created_at":"2026-06-22T01:01:43.960Z","updated_at":"2026-06-22T01:01:44.856Z","avatar_url":"https://github.com/tytsxai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSEO/GEO meta: Claude Code 中文指南 / Claude Code 中文文档 / Claude Code 教程 / Claude Code CLI 中文 /\nAnthropic Claude Code Chinese guide / DeepSeek 文档自动翻译 / Markdown 翻译流水线 / GitHub Actions 自动同步.\n--\u003e\n\n# Claude Code 完全指南（中文版）· Claude Code Complete Guide in Chinese\n\n\u003e **一句话 / TL;DR**：这是 [Claude Code](https://github.com/anthropics/claude-code)（Anthropic 官方的终端 AI 编程助手 / agentic coding CLI）社区指南 [`Cranot/claude-code-guide`](https://github.com/Cranot/claude-code-guide) 的**中文镜像**，并附带一套**自动同步 + DeepSeek 机器翻译**的开源流水线，让中文译文持续跟随上游英文原文更新。\n\u003e\n\u003e **In one line**: A continuously auto-synced, machine-translated **Chinese mirror** of the Claude Code CLI guide, plus the open-source pipeline (Python + GitHub Actions + DeepSeek) that keeps the translation up to date with upstream.\n\n[![上游 Upstream](https://img.shields.io/badge/上游-Cranot%2Fclaude--code--guide-black?logo=github)](https://github.com/Cranot/claude-code-guide)\n[![Claude Code](https://img.shields.io/badge/关于-Claude_Code-7c3aed?logo=anthropic)](https://github.com/anthropics/claude-code)\n[![翻译引擎 DeepSeek](https://img.shields.io/badge/翻译引擎-DeepSeek-5b6cff)](https://api.deepseek.com)\n[![自动同步 Auto-sync](https://img.shields.io/badge/自动同步-每小时-brightgreen)](#-自动化流水线--github-actions)\n[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python\u0026logoColor=white)](#-技术栈--tech-stack)\n\n## 📖 直接阅读中文指南 / Read the Guide\n\n\u003e **完整中文指南 → [`content/README.md`](./content/README.md)** —— 这是上游英文指南的完整简体中文译文，覆盖安装、命令、MCP、Hooks、Skills、Plugins、Subagents、SDK、配置与故障排查。\n\u003e\n\u003e - 📘 [完整中文指南 · Full Chinese Guide → `content/README.md`](./content/README.md)\n\u003e - ❓ [常见问题 · FAQ → `docs/FAQ.md`](./docs/FAQ.md)\n\u003e - 🧩 [架构说明 · Architecture → `docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)\n\u003e - 🗒️ [同步更新日志 · Sync Log → `content/update-log-zh.md`](./content/update-log-zh.md)\n\n\u003e ⚠️ 译文为机器自动翻译，**一切以[官方英文文档](https://code.claude.com/docs/en/overview)与[上游仓库](https://github.com/Cranot/claude-code-guide)为准**。本项目为非官方社区翻译。\n\n---\n\n## 🧭 这是什么 / What \u0026 Why\n\n**问题**：Claude Code 的优质学习资料几乎都是英文，更新频繁，中文开发者跟进成本高、容易看到过时内容。\n\n**本项目做两件事**：\n\n1. **一份持续更新的 Claude Code 中文指南** —— 把上游英文指南完整翻译为高可读性的简体中文（见 [`content/`](./content/)）。\n2. **一套可复用的「英文文档 → 中文」自动翻译流水线** —— 用 Python + GitHub Actions + DeepSeek 实现增量同步、结构保真翻译、自动提交。它本身也可以拿去翻译**任意** Markdown 仓库。\n\n\u003e 简言之：既是「**Claude Code 中文文档**」，也是「**一个开源的文档本地化（i18n）工具**」。\n\n## 👤 适合谁 / Who It's For\n\n- **中文 Claude Code 用户 / 学习者**：想用母语系统学习 Claude Code CLI、命令、MCP、Hooks、Skills。\n- **想做文档本地化的维护者**：需要把某个英文 Markdown 仓库**持续**翻译成中文，且不想每次手动搬运。\n- **研究自动翻译流水线的开发者**：想参考「结构保真的 LLM 文档翻译」「多 Key 轮询」「增量同步 + 缓存」的实现。\n\n## ✨ 核心功能 / Features\n\n- **增量同步 Incremental sync**：基于 `git diff` 只处理上游有变化的 Markdown，不重复翻译、不浪费 API。\n- **结构保真翻译 Structure-preserving translation**：标题 / 正文 / 代码块**分离处理**，标题层级逐字沿用原文，代码块**完全不送入模型、逐字节保留**，杜绝围栏破坏与层级丢失。\n- **锚点自愈 Anchor rewriting**：英文锚点按中文标题重新计算改写，保证目录与页内链接在 GitHub 上可正常跳转。\n- **多 Key 轮询与故障转移 Multi-key rotation**：支持多个 DeepSeek API Key 负载均衡，限流 / 鉴权失败自动隔离切换。\n- **章节级缓存 Chunk-level cache**：按内容哈希缓存翻译结果，未变动段落零成本复用。\n- **术语一致性 Terminology consistency**：[`glossary.json`](./glossary.json)（翻译时提示）+ [`fixups.json`](./fixups.json)（译后确定性修订）双层保证术语统一（如 `pipeline→流水线`、`sub-agents→子代理`、`Changelog→更新日志`）。\n- **密钥安全 Secret-safe**：API Key 仅来自环境变量 / GitHub Secrets，**绝不**硬编码或入库。\n- **CI 自动化 Automation**：[GitHub Actions](./.github/workflows/sync.yml) 每小时自动同步并提交译文。\n\n## 🧱 技术栈 / Tech Stack\n\n| 层 | 选型 |\n|---|---|\n| 语言 Language | **Python 3.10+**（CI 使用 3.12，本地已在 3.14 验证） |\n| 依赖 Dependencies | 仅 [`requests`](./requirements.txt) **≥2.31,\u003c3**（其余由标准库完成） |\n| 翻译模型 LLM | **DeepSeek** `deepseek-v4-flash`（默认）/ `deepseek-chat` / `deepseek-reasoner` |\n| 自动化 CI | **GitHub Actions**（cron + 手动触发） |\n| 数据格式 | Markdown、JSON（状态 / 术语 / 缓存） |\n\n## 🚀 快速开始 / Quick Start\n\n### A. 只想读中文指南（零依赖）\n\n直接打开 **[`content/README.md`](./content/README.md)** 即可阅读，无需安装任何东西。\n\n### B. 在本地运行翻译流水线\n\n```bash\n# 1) 克隆\ngit clone https://github.com/tytsxai/claude-code-guide-zh.git\ncd claude-code-guide-zh\n\n# 2) 安装依赖\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\n\n# 3) 配置 DeepSeek 密钥（.env 已被 .gitignore，不会入库）\n#    申请 Key：https://platform.deepseek.com → 注册后在后台创建 API Key\ncp .env.example .env\n#   编辑 .env，填入一个或多个 Key（逗号 / 空格 / 分号分隔）\nset -a; source .env; set +a\n\n# 4) 预览将翻译哪些文件（不调用 API）\npython -m tools.sync --dry-run\n\n# 5) 增量同步 + 翻译\npython -m tools.sync\n\n# 6) （可选）强制全量重翻\npython -m tools.sync --full\n```\n\n\u003e 命令、路径与 `tools/` 下真实代码一致。`python -m tools.sync` 支持 `--dry-run` 与 `--full` 两个参数。\n\n## 🎯 使用场景 / Use Cases\n\n- 用中文系统学习 **Claude Code CLI**（安装、命令、MCP、Hooks、Skills、Plugins、SDK）。\n- 为团队/社区维护一份**自动跟随上游**的中文技术文档镜像。\n- 把本流水线指向任意英文 Markdown 仓库（改 `UPSTREAM_REPO`），做**持续本地化**（出处声明 banner 需按新仓库微调，详见 [FAQ](./docs/FAQ.md)）。\n- 学习「LLM 翻译如何不破坏 Markdown 结构」「多 Key 轮询」「增量翻译缓存」的工程实现。\n\n## 🔧 工作原理 / How It Works\n\n```\n上游英文仓库 ──git diff──\u003e 变更的 .md\n   │\n   ├─ 解析：标题 / 正文 / 代码块分离（structured_doc.py）\n   ├─ 翻译：标题批量翻译 + 正文分块翻译（DeepSeek，多 Key 并行，translator.py）\n   │        代码块逐字节保留、不送模型\n   ├─ 修订：glossary 术语提示 + fixups 确定性替换\n   ├─ 锚点：英文锚点 → 中文标题锚点改写\n   └─ 写回：content/ 镜像目录 + 更新 .sync-state.json\n```\n\n详见 **[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md)**（结构保真翻译引擎设计）。\n\n## ⚙️ 配置 / Configuration\n\n所有配置通过环境变量读取（默认值见下表，定义在 [`tools/config.py`](./tools/config.py)）：\n\n| 环境变量 Env var | 说明 | 默认值 |\n|---|---|---|\n| `DEEPSEEK_API_KEYS` | 一个或多个 Key，逗号/空格/分号分隔，用于轮询与故障转移 | —（必填） |\n| `DEEPSEEK_API_KEY` | 单 Key 写法（与上者二选一） | — |\n| `DEEPSEEK_MODEL` | 翻译模型 | `deepseek-v4-flash` |\n| `DEEPSEEK_BASE_URL` | API 地址 | `https://api.deepseek.com` |\n| `DEEPSEEK_MAX_TOKENS` | 单次输出上限（防截断） | `8192` |\n| `MAX_CHUNK_CHARS` | 单次翻译片段最大字符数 | `6000` |\n| `TRANSLATE_CONCURRENCY` | 并发翻译数（跨多 Key 扇出） | `6` |\n| `DEEPSEEK_TIMEOUT` | 单次请求超时（秒） | `300` |\n| `MAX_RETRIES_PER_KEY` | 每个 Key 的重试次数 | `3` |\n| `DEEPSEEK_TEMPERATURE` | 采样温度；不设则不发送（推理模型可能拒绝该参数） | 不发送 |\n| `UPSTREAM_REPO` | 上游仓库地址（完整 git URL） | `https://github.com/Cranot/claude-code-guide.git` |\n| `UPSTREAM_BRANCH` | 上游分支 | `main` |\n| `PROJECT_REPO_URL` | 本项目仓库地址（用于译文署名 banner） | 本仓库 URL |\n\n\u003e 完整环境变量与默认值以 [`tools/config.py`](./tools/config.py) 为权威来源。\n\n\u003e ℹ️ **关于模型**：`deepseek-v4-flash` 是真实可用的轻量推理模型（已对 API 实测）。它会单独返回 `reasoning_content` 并消耗少量推理 token，因此默认显式设置 `DEEPSEEK_MAX_TOKENS=8192` 以避免长段落被截断。可替换为 `deepseek-chat`（V3.x）或 `deepseek-reasoner`（R1）。\n\n## 🤖 自动化流水线 / GitHub Actions\n\n[`.github/workflows/sync.yml`](./.github/workflows/sync.yml) 每小时（及手动触发）执行：拉取上游 → 与上次同步 commit 做 diff → DeepSeek 翻译变更 → 自动提交 `content/`。手动触发（`workflow_dispatch`）时可勾选 `full` 选项强制全量重翻。\n\n**启用自动同步**：在仓库 `Settings → Secrets and variables → Actions` 添加：\n\n- Secret `DEEPSEEK_API_KEYS`：你的一个或多个 Key（逗号分隔）。\n- （可选）Variable `DEEPSEEK_MODEL`：覆盖默认模型。\n\nAPI Key 全程只从 Secrets 注入，不出现在代码、日志或提交中。\n\n## 🛡️ 翻译质量保障 / Quality\n\n机器翻译要达到可发布质量，本流水线内置多重确定性保障：\n\n- **结构零损失**：标题数量/层级与原文一致；代码块逐字节保留；译后自动校验。\n- **锚点可跳转**：页内目录链接按中文标题重算，GitHub 上点击有效。\n- **术语统一**：`glossary.json` + `fixups.json` 双层归一（如 pipeline→流水线、sub-agents→子代理）。\n- **代码逐字保留（有意取舍）**：代码块、命令、路径中的内容（含注释）保持英文原样，确保技术准确、不破坏可执行性。\n- **可选多智能体质检**：逐章节对照「英 vs 中」查遗漏/误译/术语/格式，高危项独立复核后修订。\n\n\u003e 本仓库初版译文已通过上述流程：结构校验显示标题与代码块逐字节一致、页内锚点全部可解析。详见 [`docs/FAQ.md`](./docs/FAQ.md) 中「翻译质量如何保证」。\n\n## ❓ 常见问题 / FAQ\n\n完整 FAQ 见 **[`docs/FAQ.md`](./docs/FAQ.md)**。最常见的几条：\n\n- **这是官方文档吗？** 不是。本项目是非官方社区翻译，**以官方英文为准**。\n- **译文有多新？** 流水线每小时检查上游，有更新即自动翻译提交。\n- **能换成别的模型/仓库吗？** 能。改 `DEEPSEEK_MODEL` 换模型，改 `UPSTREAM_REPO` 翻译其它英文 Markdown 仓库。\n- **为什么代码注释还是英文？** 有意为之 —— 代码区块逐字保留以保证准确与可执行。\n\n## 🚧 限制与注意事项 / Limitations\n\n- **机器翻译**：可能存在个别误译/不自然表达，欢迎提 Issue / PR；技术细节请对照英文原文。\n- **非官方**：与 Anthropic、Claude Code 团队及上游作者无隶属关系。\n- **代码/注释不翻译**：代码块默认保持英文（见上）。\n- **依赖上游结构**：上游若大改目录结构，可能需要同步调整。\n- **API 成本**：全量翻译会消耗 DeepSeek token；增量同步成本很低。\n\n## 🔖 关键词 / Keywords\n\n`Claude Code` · `Claude Code 中文` · `Claude Code 中文文档` · `Claude Code 中文指南` · `Claude Code 教程` · `Claude Code CLI` · `Anthropic` · `agentic coding` · `AI 编程助手` · `MCP` · `Model Context Protocol` · `Hooks` · `Skills` · `Plugins` · `Subagents` · `DeepSeek 翻译` · `文档自动翻译` · `Markdown 翻译` · `i18n` · `GitHub Actions 自动化` · `多 Key 轮询` · `增量同步`\n\n## 📄 版权与许可 / License \u0026 Attribution\n\n本项目是上游英文文档的**翻译衍生作品**。原始内容版权归原作者 [@Cranot](https://github.com/Cranot) 所有，详见 [`NOTICE`](./NOTICE)。译文仅供学习交流，**一切以官方英文原文为准**。如原作者或官方提出异议，将及时配合调整或下架。\n\n---\n\n🤖 本仓库由自动化流水线持续维护；翻译由机器生成，可能存在疏漏，欢迎 [提 Issue / PR](https://github.com/tytsxai/claude-code-guide-zh/issues) 修正。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftytsxai%2Fclaude-code-guide-zh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftytsxai%2Fclaude-code-guide-zh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftytsxai%2Fclaude-code-guide-zh/lists"}