V3.0 — 全书叙事结构重构

V3.0 发布说明

发布状态：正式发布。公开版本标签为 v3.0，发布目标为 anyue-git/Terminal-AI-Coding-Handbook 的 main 分支。

《终端与 AI 编程手册》V3.0 的重点不是继续堆叠章节，而是对 V2.0 中普遍存在的碎片化叙事进行全书重构。原版本已经覆盖终端、Git、SSH、Python、Docker、三套 AI CLI、配置凭证和 GPU 远程开发，但不少页面采用“一句引导—代码块—一句解释—列表—下一个标题”的卡片式节奏，导致页面看起来很长，连续理解却比较困难。V3.0 将重构单位从单个知识点改为完整意思、真实任务和可验证决策：一个自然段围绕同一问题展开，一个小节解决真正不同的问题，一章形成从场景、操作、结果判断到恢复方法的连续过程。

叙事结构重构

V3.0 建立了叙事结构审计、公式化文风审查和内容覆盖反查三套机制，再完成 README、Quickstart、快速开始、Part 01–12 与主要附录的人工重写。为了避免新增路线图、覆盖记录和发布说明影响比较，下表只统计 V2 中原有、V3 中仍存在的同一批 73 个文档；这些数字用于观察结构变化，不单独作为内容质量结论。

指标	V2.0 基线	V3.0 代表性审计	变化
普通正文字符	137786	122367	-11.2%
自然段	4526	2066	-54.4%
微型段落	2311	536	-76.8%
短段落	3355	952	-71.6%
一句段落	3304	1095	-66.9%
平均段长	30.4 字	59.2 字	+28.8 字
标题	1433	522	-63.6%
列表项	2446	276	-88.7%
代码块	2467	1048	-57.5%
正文偏薄的小节	544	20	-96.3%
空引导短句	151	15	-90.1%
短段占比	74.1%	46.1%	-28.0 个百分点

普通正文减少并不等于内容简单删减。术语表和维护清单改为表格后，表格单元格不计入普通正文；重复 Prompt、重复 Git 流程和跨章安全提醒也被合并或迁移。V3.0 同时回查 V2 主分支，从缩减较大的章节中逐项寻找被删除的独特命令、故障场景和恢复方法，确认由其他主讲章节承接，或直接补回。

入口、基础工具与开发环境

README 现在直接承担读者入口和全书内容地图，不再只把读者引向 SUMMARY.md。两个短版快速开始分别形成终端与 AI CLI 的最小闭环，完整 Quickstart 则保留可脱离真实项目运行的独立练习。Terminal、Shell、zsh、路径、文件生命周期、进程生命周期、Git、SSH、Homebrew、Python 和 Docker 的职责边界重新划分，命令不再被拆成大量只承载一两句话的小节。

覆盖反查补回了多项容易在压缩结构时丢失的细节，包括 git diff --check、忽略规则验证、Homebrew 前缀与服务诊断、Python 环境标记与私有索引、Docker 构建上下文与 .dockerignore、Compose 合并顺序、GPU 镜像与 UID/GID 边界，以及 Mac 通过命名 SSH Context 操作 Ubuntu Docker daemon 时的远程路径规则。

Claude Code、Codex CLI、Grok Build 与多供应商配置

三套客户端各自主讲产品特有的安装、认证、权限、会话、自动化和扩展能力；共同的模型、Provider、Base URL、配置、凭证、Profile、状态目录、独立实例和本地网关集中到 Part 10C。Codex 的 TOML、Profile 与凭证，Claude Code 的设置作用域与网关，CC Switch、ccswitch、Cockpit Tools 和第三方 Provider 的职责边界都得到强化，避免把“配置投影”“凭证替换”和“本地路由”混为一谈。

V3.0 也保留了 Claude Code MCP 的项目 Scope、凭据边界、提示注入和双数据链，Grok Headless 的工具白名单、Allow/Deny、JSONL 前向兼容，以及 Codex 非交互执行、审批、退出状态、超时、CI 凭据和 Git 写操作边界。第三方项目声明的能力不会被写成上游平台已经授权或官方保证的能力。

Mac、Ubuntu 与 GPU 远程开发

Part 11 按局域网链路、源码同步、tmux、NVIDIA/PyTorch、跨平台环境、Tailscale、VS Code/AI CLI 协作和实验恢复重新组织。Mac 负责主要编辑、Git 与复核，Ubuntu 负责 Linux、CUDA 与训练；源码、环境、数据、模型和运行产物分目录管理，日志、退出状态、代码快照、最终配置、指标、checkpoint 和恢复演练组成完整证据链。

实验记录部分明确区分 git diff、git diff --cached 与 git diff HEAD 的覆盖范围，并单独记录未跟踪文件，避免把一个不完整的补丁文件误认为足以复现实验。

AI 开发工作流

Part 12 将 Prompt、安全边界、复杂任务、多 Agent 和端到端案例组织为一条可检查的闭环：

定义完成标准
→ 建立现实基线
→ 只读调查
→ 选择方案
→ 小批实施
→ 证据验证
→ 独立复核与人工提交

同一工作区同时只保留一个实施者；其他 Agent 使用只读职责或独立 Worktree。每个批次需要记录命令、运行环境、退出状态、通过/失败/跳过、关键警告、覆盖行为和未覆盖内容，最终验收还会检查凭据、大型生成物和范围外修改。

自动审计与发布机制

V3.0 新增并接入以下自动检查：

• scripts/audit_prose_structure.py：统计微型段、短段、连续短段、薄小节和空引导；
• scripts/audit_formulaic_style.py：定位跨章重复长句、固定段首、公式化转折和超长段落候选；
• scripts/audit_sensitive_patterns.py：扫描当前树、提交说明和 Git 历史中的高置信度凭据特征；
• scripts/audit_external_links.py：忽略代码块和占位域名，检查公开快照外链；
• scripts/test_audit_tools.py：回归审计规则，并扫描 Shell printf 格式参数转义；
• Source Release Audit：构建隔离公开快照，执行 Markdown、敏感信息、外链和真实导出预演检查。

公开仓库新增基于发布清单的 GitHub Release 工作流。发布清单改变后，工作流会在公开仓库创建或更新对应标签与 Release；在私有源仓库中同一工作流会自动跳过，从而继续保持“私有源仓库是唯一开发源头，公开仓库是发布副本”的结构。

兼容性与验证边界

自动检查只能证明其覆盖的规则、静态审计和公开快照流程通过，不能证明所有命令已经在每一种真实 Mac、Ubuntu、NVIDIA GPU、账号和网络环境中执行，也不能保证外部平台、CLI 参数和第三方服务未来不会变化。涉及快速变化的工具时，应同时查看正文中的版本说明和官方资料。

许可证

本项目采用双许可证：正文、解释、表格、练习和其他非代码教学内容使用 CC BY-NC-SA 4.0；脚本、GitHub Actions、Shell 命令、配置示例和围栏代码使用 MIT License。第三方商标、引用、截图和链接材料仍受各自权利人条款约束。