企业官网建设流程全解析

claude-howto 项目 v2.0.0 → v2.3.0 演进全记录：文档同步、国际化、Hook 与质量工程实战

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

本篇技术指南以 vi/CHANGELOG.md 为主体，梳理 claude-howto 这一面向 Claude Code 的可视化、示例驱动指南仓库在 v2.0.0（2026-02-01）至 v2.3.0（2026-04-07）期间的关键版本演进。读者将从中掌握：如何围绕上游 Claude Code 版本做大规模文档同步与纠错、如何组织多语言国际化与质量门禁（CI + pre-commit + Hook），以及如何把文档仓库升级为可构建 EPUB、可自动审计依赖与权限的可交付工程。

版本演进总览：从单一英文文档到多语言可交付工程

对照 vi/CHANGELOG.md 的版本时间线，claude-howto 在三个月内完成了三条主线的升级：

这一演进路线说明：该仓库不仅是"翻译文档"，而是把教程内容当作软件工程制品来维护——每次上游 Claude Code 发版都会触发一次全量同步与审计，版本号与上游同步（v2.1.84、v2.1.112 等即上游 Claude Code 版本号）。

v2.0.0：与上游特性全面同步 + 虚构内容大扫除

v2.0.0 是一次里程碑式发布，更新了全部 10 个教程目录下的 26 个文件和 7 份参考文档，新增了对以下 Claude Code 特性的文档覆盖：

• Auto Memory——按项目持久化学习记录，对应 02-memory/README.md；
• Remote Control、Web Sessions、Desktop App；
• Agent Teams（实验性多 Agent 协作）；
• MCP OAuth 2.0、Tool Search、Claude.ai Connectors；
• Persistent Memory 与 Worktree Isolation（针对 subagent）；
• Background Subagents、Task List、Prompt Suggestions；
• Sandboxing 与 Managed Settings（企业级）；
• HTTP Hooks 及 7 个新 hook 事件；
• Plugin Settings、LSP Servers、Marketplace 更新；
• Summarize from Checkpoint回退选项；
• 17 个新 slash 命令（/fork、/desktop、/teleport、/tasks、/fast等）；
• 新 CLI 参数（--worktree、--from-pr、--remote、--teleport、--teammate-mode等）。

纠错清单：删除虚构 API，对齐真实配置

v2.0.0 的另一半价值在于纠正文档中不符合真实 Claude Code 行为的虚构内容，这正是技术文档仓库最该警惕的"幻觉"问题。对照 changelog 的 Bug Fixes 段落，可总结为以下七类：

1. 模型名更新：Sonnet 4.5 → Sonnet 4.6、Opus 4.5 → Opus 4.6；
2. 权限模式名：删除虚构的 "Unrestricted/Confirm/Read-only"，改为真实的default/acceptEdits/plan/dontAsk/bypassPermissions；
3. Hook 事件：删除虚构的PreCommit/PostCommit/PrePush，替换为真实事件（SubagentStart、WorktreeCreate、ConfigChange等）；
4. CLI 语法：claude-code --headless→claude -p（print 模式）；
5. Checkpoint 命令：虚构的/checkpoint save/list/rewind/diff→ 真实的Esc+Esc//rewind交互界面；
6. 会话管理：虚构的/session list/new/switch/save→ 真实的/resume//rename//fork；
7. 插件清单格式：plugin.yaml→.claude-plugin/plugin.json；MCP 配置路径统一为项目级.mcp.json与用户级~/.claude.json。

这一轮纠错体现的原则是：文档必须可复制、可运行，任何虚构命令或配置都会直接误导使用者。

v2.1.0：自适应学习路径与测验型 Skill

v2.1.0 从"参考文档"转向"教学系统"，新增两个核心 Skill：

• /self-assessment——覆盖 10 个功能领域的交互式熟练度测验，输出个性化学习路径；
• /lesson-quiz [lesson]——针对每个课程的 8–10 道定向知识检测。

同期完成的还有：Giai đoạn 3–5（阶段 3–5）QA 流程，修复跨文档的一致性、URL 与术语问题；在 STYLE_GUIDE.md 中新增基于仓库现有约定的样式规范；为 MCP 上下文膨胀章节补充 MCPorter 运行时。这些工作表明，该仓库用**分阶段 QA（Phase 3–5）**的方式管理文档质量，而非一次性写完。

v2.2.0：同步 Claude Code v2.1.84 与落地页式 README

v2.2.0 将全部教程与参考文档同步到 Claude Code v2.1.84，关键增量包括：

• slash 命令更新为55+ 内置 + 5 个捆绑 skill，标记 3 个已废弃；
• hook 事件从 18 个扩展到25 个，新增agenthook 类型（合计 4 种类型）；
• 高级特性新增 Auto Mode、Channels、Voice Dictation；
• Skill frontmatter 新增effort、shell字段；Agent 新增initialPrompt、disallowedTools字段；
• MCP 新增 WebSocket transport、elicitation、2KB 工具大小上限；
• 插件新增 LSP 支持、userConfig与${CLAUDE_PLUGIN_DATA}占位符；
• 同步更新 CATALOG、QUICK_REFERENCE、LEARNING-ROADMAP、INDEX 全部参考文档。

此外，README 被重写为落地页结构（landing-page-structured guide），让新读者能按导航快速定位到 01-slash-commands 至 10-cli 的十个模块。

v2.3.0：Hook 补全、多语言本地化与可构建 EPUB

v2.3.0 是变化最丰富的一个版本，直接推动了仓库工程化程度的大幅提升。

新增功能

• 构建并发布各语言的 EPUB 制品——对应 scripts/build_epub.py。该脚本按目录结构（01-slash-commands、02-memory 等）组织章节，通过本地mmdcCLI 将 Mermaid 图渲染为 PNG（无需网络），生成封面、转换内部链接为 EPUB 章节引用，并采用严格错误模式（任一图渲染失败即构建失败）。运行方式：uv run scripts/build_epub.py或python scripts/build_epub.py；
• 补全缺失的 pre-tool-check.sh 到 06-hooks；
• 新增中文翻译目录zh/；
• 新增 performance-optimizer subagent 与 dependency-check hook。

关键 Bug 修复

• Windows Git Bash 兼容 + stdin JSON 协议：Hook 脚本在 Windows Git Bash 下的可移植性修复。以 06-hooks/dependency-check.sh 为例，它通过INPUT=$(cat)读取 stdin JSON，再用可移植sed提取file_path，对package.json、requirements.txt、go.mod等各类依赖清单分别触发npm audit、pip-audit/safety、govulncheck、cargo audit、bundler-audit与 trivy 扫描，最后始终exit 0（警告但不阻塞提交）；
• 修正 08-checkpoints 中 autoCheckpoint 配置文档——与 08-checkpoints/README.md 中的自动 checkpoint 行为（每次用户输入创建、30 天自动清理等）保持一致；
• 嵌入 SVG 图片而非用占位符替换；
• 修复 memory README 中嵌套代码围栏渲染问题。

重构：质量左移与权限基线收窄

v2.3.0 的三项重构最能体现工程思维：

1. 用本地 mmdc 渲染替换 Kroki HTTP 依赖——消除对外部渲染服务的网络依赖，保证构建的确定性；
2. 质量检查左移到 pre-commit，CI 作为第二道防线——并新增 mypy 到 pre-commit，修复 CI 失败，实现"提交前发现问题"；
3. 收窄 auto-mode 权限基线，用一次性权限设置脚本替换自动适配 Hook——即 09-advanced-features/setup-auto-mode-permissions.py。该脚本为~/.claude/settings.json播种一套保守的权限基线：核心集只含只读检查类命令（Read(*)、Glob(*)、Grep(*)、Bash(ls:*)、Bash(git status:*)等），编辑、测试、git 写操作、包安装、GitHub CLI 均需通过--include-edits、--include-tests、--include-git-write、--include-packages、--include-gh-write等可选参数显式开启，并提供--dry-run预览。

越南语本地化

v2.3.0 的 "Other" 类别记录了越南语（Tiếng Việt）本地化的落地，并在语言切换器中加入中英文互切与中文链接。这正是 vi/CHANGELOG.md 自身诞生的背景——它本身就是越南语本地化维护过程的产物。

仓库源码佐证：Hook 与权限脚本的真实实现

为印证 changelog 中 v2.3.0 的修复条目，可直接阅读仓库内的实际实现：

• 06-hooks/pre-tool-check.sh：注册为PreToolUse（matcher: Bash）的钩子，通过 stdin JSON 读取待执行命令。它对rm -rf /（锚定后需跟空白或行尾，避免误伤rm -rf /tmp/foo）、dd if=/dev/zero、fork 炸弹、mkfs.等模式执行exit 2硬性阻塞（阻塞原因写入 stderr，Claude Code 将 stderr 作为阻塞原因回显）；对rm -rf、git push --force、DROP TABLE等高风险模式仅记入审计日志$CLAUDE_PROJECT_DIR/.claude/hooks/audit.log后放行；
• 06-hooks/context-tracker.py：把UserPromptSubmit与Stop配对使用，基于 transcript 估算每次请求的 token 增量；其上下文上限默认 1M（Opus 5、Sonnet 5、Opus 4.8、Sonnet 4.6），并注明 Haiku 4.5 为 200K——与"收窄权限、控制上下文"的方向一致；
• 04-subagents/performance-optimizer.md：v2.3.0 新增的性能优化 subagent，提供从"界定范围→剖析测量→分析瓶颈→实施优化→记录结果"的完整流程，并内置 Big O、N+1 查询、内存分配等检查清单与各语言 profiling 命令。

质量门禁方法论：CHANGELOG 之外的配套工具

changelog 中反复出现的 "CI 合规"、"cSpell 词典"、"链接检查"并非空话，仓库为此提供了完整工具链：

• scripts/check_links.py（链接检查）、scripts/check_cross_references.py（交叉引用一致性）、scripts/check_markdown_rendering.py（Markdown 渲染）与 scripts/check_mermaid.py（Mermaid 图检查）共同构成质量检查层；
• scripts/sync_translations.py 用于维护vi/、zh/、ja/、uk/四个本地化目录与英文源的一致性；
• v2.1.1 中"删除导致 CI 链接检查失败的死 marketplace 链接"、向 cSpell 词典补充sandboxed、pycache等词，正是这套门禁在真实迭代中拦截问题的记录。

总结与可借鉴实践

从 vi/CHANGELOG.md 这份发布记录中，可以提炼出四条可直接复用的工程实践：

1. 版本号与上游同步：教程文档的版本紧跟上游 Claude Code 版本（v2.1.84、v2.1.112…），每次上游发版即触发全量审计，避免文档滞后；
2. 纠错即迭代：每个版本都包含大量"删除虚构命令/字段、对齐真实配置"的修复，这是技术文档仓库保持可信度的核心动作；
3. 质量左移：pre-commit（含 mypy）承担第一道质量关卡，CI 作为第二道，配合 cSpell、链接与 Mermaid 检查脚本形成闭环；
4. 多语言与可交付物并重：越南语、中文、日语、乌克兰语本地化与按语言构建 EPUB 并行推进，使教程既能在线阅读，也能离线分发。

如果你正在维护面向 CLI/Agent 工具的教程仓库，这份 changelog 展示的"同步—纠错—QA—发布"节奏，是一份高价值的过程模板。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto